Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
import type {
SigningAddresses,
VaultSignedOperationContext,
VaultWebAuthnRegistrationPayload,
} from '@/context/ApiContext';
import type { BlindBox, ProtectedRecordEnvelope, SignatureResult, SignatureScheme } from './vaultCrypto';
import {
VAULT_SANDBOX_EXPECTED_BUILD_HASH,
VAULT_SANDBOX_INTEGRITY_ENFORCED,
VAULT_SANDBOX_IFRAME_URL,
VAULT_SANDBOX_IFRAME_RESOURCE_PATH,
VAULT_SANDBOX_MANIFEST_PATH,
VAULT_SANDBOX_ORIGIN,
VAULT_SANDBOX_PINNED_MANIFEST,
VAULT_SANDBOX_REQUIRED_RESOURCE_PATHS,
} from './vaultSandboxManifest';
import { openLinkInNewContext } from './pwaNavigation';
import { getVaultSandboxAppearance, type VaultSandboxAppearance } from './vaultSandboxAppearance';
import { getVaultSandboxPolicy, refreshVaultSandboxPolicy, type VaultSessionPolicy } from './vaultSandboxPolicy';
import { buildVaultConfirmSurface, type VaultConfirmSurface } from './vaultConfirmSurface';
const CHANNEL = 'avibe.vault.crypto';
const VERSION = 2;
// Protocol v2 operation surface (vault-sandbox #9): `unseal`→`reveal`, `releaseDEK`→`approveRelease`.
const REQUIRED_OPS = ['status', 'setup', 'unlock', 'lock', 'seal', 'reveal', 'sign', 'approveRelease'] as const;
const DEFAULT_TIMEOUT_MS = 15_000;
// Ops that may raise an in-sandbox card (confirm / passkey / plaintext display) can sit open for
// as long as the user takes to act, so they get the long ceremony timeout regardless of tier.
const INTERACTIVE_TIMEOUT_MS = 5 * 60_000;
// Cadence for refreshing the parent surface attestation while an embedded card is up. This remains
// useful for compatibility and diagnostics, but high-risk authorization itself is completed in a
// top-level sandbox window and does not trust parent hit-test claims.
const SURFACE_REFRESH_INTERVAL_MS = 10_000;
type VaultSandboxOp = (typeof REQUIRED_OPS)[number] | 'handshake';
type ParentOnlySandboxOp = 'set-appearance';
type PendingRequest = {
resolve: (value: unknown) => void;
reject: (err: Error) => void;
timer: number;
};
type SandboxBuild = {
sandboxVersion?: string;
buildHash?: string;
};
type ReadyMessage = {
type: 'ready';
channel: typeof CHANNEL;
version: typeof VERSION;
build?: SandboxBuild;
capabilities?: { operations?: string[] };
};
type TerminalMessage =
| { channel: typeof CHANNEL; version: typeof VERSION; id: string; ok: true; result: unknown }
| { channel: typeof CHANNEL; version: typeof VERSION; id: string; ok: false; error: { code?: string; message?: string; retryable?: boolean } | string };
/** Sandbox→parent one-way notification (protocol v2 §6.4). */
type EventMessage = {
channel: typeof CHANNEL;
version: typeof VERSION;
kind: 'event';
event: 'vault.state' | 'ui.show' | 'ui.hide';
payload?: unknown;
};
export type VaultSandboxState = 'needs-setup' | 'locked' | 'unlocked';
export type VaultStateReason = 'unlock' | 'renew' | 'manual-lock' | 'auto-lock' | 'unload';
/** The `vault.state` event payload — the single clock the parent mirrors (protocol v2 §6.4). */
export type VaultStateEvent = {
state: VaultSandboxState;
expiresAt?: number | null;
reason: VaultStateReason;
};
export type VaultSandboxStatusResult = {
state: VaultSandboxState;
expiresAt?: number | null;
freshSetup?: boolean;
policy?: VaultSessionPolicy;
session?: { expiresAt?: number; strict?: boolean };
};
export type VaultSandboxSetupResult = {
wrapMeta: string;
rpId: string;
credentialId: string;
authzRegistration?: VaultWebAuthnRegistrationPayload;
state: 'unlocked';
expiresAt?: number;
policy?: VaultSessionPolicy;
};
export type VaultSandboxUnlockResult = {
state: 'unlocked';
expiresAt?: number;
wrapMeta?: string;
policy?: VaultSessionPolicy;
};
export type VaultSandboxSealResult = {
envelope: ProtectedRecordEnvelope;
establishingVmk: boolean;
publicKey?: string;
addresses?: SigningAddresses;
};
/** One member of a batch `approveRelease` — the sandbox releases one blind box per item. */
export type ApproveReleaseItem = {
material: ProtectedUnlockMaterialLike;
context: VaultSignedOperationContext;
};
export type VaultSandboxSigningContext = Record<string, unknown>;
export class VaultSandboxError extends Error {
readonly code: string;
readonly retryable: boolean;
constructor(code: string, message: string, retryable = false) {
super(message);
this.name = 'VaultSandboxError';
this.code = code;
this.retryable = retryable;
}
}
let integrityPromise: Promise<void> | null = null;
let singleton: Promise<VaultSandboxClient> | null = null;
let activeClient: VaultSandboxClient | null = null;
// Bumped on every reset. A create() that started before a reset checks this after its handshake:
// if it advanced, the client handshook under the pre-reset (stale) policy and is discarded instead
// of being adopted, so a reset takes effect even for an in-flight client creation.
let clientGeneration = 0;
// Module-level so subscribers survive client recreation (a singleton reset on error) and can
// register before any client exists — the active client forwards every `vault.state` event here.
const vaultStateListeners = new Set<(event: VaultStateEvent) => void>();
/**
* Subscribe to sandbox `vault.state` events (unlock / renew / lock transitions). This is the
* single clock the parent renders off of — {@link useProtectedVault} wires one listener that
* mirrors state + `expiresAt`. Returns an unsubscribe function.
*/
export function subscribeVaultStateEvents(listener: (event: VaultStateEvent) => void): () => void {
vaultStateListeners.add(listener);
return () => {
vaultStateListeners.delete(listener);
};
}
function isObject(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value != null && !Array.isArray(value);
}
function randomId(): string {
const bytes = crypto.getRandomValues(new Uint8Array(16));
return [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
}
export type VaultAuthorizationWindow = {
id: string;
close: () => void;
};
/**
* Open the top-level sandbox authorization window for one protected operation (protocol v2
* §6.6). Call it synchronously from the user's approval click, before any await: the window needs
* that gesture, and opening it here lets the sandbox skip the in-frame launcher card. Pass the id
* to the operation and close the handle when the operation settles. Returns null when the browser
* blocks the window; the sandbox then falls back to its own launcher.
*/
export function openVaultAuthorizationWindow(): VaultAuthorizationWindow | null {
const id = randomId();
const url = new URL(VAULT_SANDBOX_IFRAME_URL);
const appearance = getVaultSandboxAppearance();
url.searchParams.set('mode', 'authorize');
url.searchParams.set('id', id);
url.searchParams.set('locale', appearance.locale);
url.searchParams.set('theme', appearance.theme);
// No noopener: the sandbox window reaches the requesting sandbox frame through its opener.
const popup = openLinkInNewContext(url.toString(), 'popup,width=520,height=760');
if (!popup) return null;
return {
id,
close: () => {
try {
if (!popup.closed) popup.close();
} catch {
// The sandbox may already have closed its window.
}
},
};
}
function base64(bytes: ArrayBuffer): string {
const raw = String.fromCharCode(...new Uint8Array(bytes));
return btoa(raw);
}
async function sha256Subresource(value: ArrayBuffer): Promise<string> {
return `sha256-${base64(await crypto.subtle.digest('SHA-256', value))}`;
}
function failIntegrity(message: string): never {
throw new VaultSandboxError('sandbox_integrity_failed', message);
}
function sameManifestShape(live: unknown): live is typeof VAULT_SANDBOX_PINNED_MANIFEST {
if (!isObject(live) || live.algorithm !== VAULT_SANDBOX_PINNED_MANIFEST.algorithm || !isObject(live.resources)) {
return false;
}
const liveResources = live.resources as Record<string, unknown>;
const pinnedEntries = Object.entries(VAULT_SANDBOX_PINNED_MANIFEST.resources);
if (Object.keys(liveResources).length !== pinnedEntries.length) return false;
return pinnedEntries.every(([path, digest]) => liveResources[path] === digest);
}
export async function verifyVaultSandboxIntegrity(): Promise<void> {
if (integrityPromise) return integrityPromise;
integrityPromise = (async () => {
if (typeof window === 'undefined' || typeof crypto === 'undefined' || !crypto.subtle) {
failIntegrity('Sandbox integrity requires Web Crypto in a browser context');
}
const manifestUrl = `${VAULT_SANDBOX_ORIGIN}${VAULT_SANDBOX_MANIFEST_PATH}`;
const manifestResponse = await fetch(manifestUrl, { cache: 'no-store', mode: 'cors', credentials: 'omit' });
if (!manifestResponse.ok) {
failIntegrity(`Unable to fetch sandbox manifest (${manifestResponse.status})`);
}
const liveManifest = await manifestResponse.json();
if (!sameManifestShape(liveManifest)) {
failIntegrity('Sandbox manifest does not match the pinned build manifest');
}
if (!VAULT_SANDBOX_REQUIRED_RESOURCE_PATHS.includes(VAULT_SANDBOX_IFRAME_RESOURCE_PATH)) {
failIntegrity('Sandbox iframe URL is not pinned in the build manifest');
}
await Promise.all(
VAULT_SANDBOX_REQUIRED_RESOURCE_PATHS.map(async (path) => {
const response = await fetch(`${VAULT_SANDBOX_ORIGIN}${path}`, {
cache: 'no-store',
mode: 'cors',
credentials: 'omit',
});
if (!response.ok) {
failIntegrity(`Unable to fetch sandbox resource ${path} (${response.status})`);
}
const actual = await sha256Subresource(await response.arrayBuffer());
const expected = VAULT_SANDBOX_PINNED_MANIFEST.resources[path];
if (actual !== expected) {
failIntegrity(`Sandbox resource hash mismatch for ${path}`);
}
}),
);
})().catch((err) => {
integrityPromise = null;
throw err;
});
return integrityPromise;
}
function serializeSandboxError(error: { code?: string; message?: string; retryable?: boolean } | string): VaultSandboxError {
if (typeof error === 'string') return new VaultSandboxError('sandbox_error', error);
return new VaultSandboxError(
typeof error?.code === 'string' ? error.code : 'sandbox_error',
typeof error?.message === 'string' ? error.message : 'Sandbox request failed',
Boolean(error?.retryable),
);
}
function parseReadyMessage(data: unknown): ReadyMessage | null {
if (!isObject(data)) return null;
if (data.type !== 'ready' || data.channel !== CHANNEL || data.version !== VERSION) return null;
return data as ReadyMessage;
}
function parseTerminalMessage(data: unknown): TerminalMessage | null {
if (!isObject(data)) return null;
if (data.channel !== CHANNEL || data.version !== VERSION || typeof data.id !== 'string') return null;
if (data.ok === true && 'result' in data) return data as TerminalMessage;
if (data.ok === false && 'error' in data) return data as TerminalMessage;
return null;
}
function parseEventMessage(data: unknown): EventMessage | null {
if (!isObject(data)) return null;
if (data.channel !== CHANNEL || data.version !== VERSION || data.kind !== 'event') return null;
if (data.event !== 'vault.state' && data.event !== 'ui.show' && data.event !== 'ui.hide') return null;
return data as EventMessage;
}
function parseVaultStateEvent(payload: unknown): VaultStateEvent | null {
if (!isObject(payload)) return null;
const state = payload.state;
if (state !== 'needs-setup' && state !== 'locked' && state !== 'unlocked') return null;
const reason = payload.reason;
const validReason =
reason === 'unlock' || reason === 'renew' || reason === 'manual-lock' || reason === 'auto-lock' || reason === 'unload';
return {
state,
reason: validReason ? reason : 'manual-lock',
expiresAt: typeof payload.expiresAt === 'number' && Number.isFinite(payload.expiresAt) ? payload.expiresAt : null,
};
}
/**
* One-shot IntersectionObserver reading of an element's on-screen visibility, mirroring the sandbox's
* own self-check (`trackVisibility` occlusion detection where the engine supports it, ratio fallback
* otherwise) so the parent attests visibility the same way the sandbox measures itself. Resolves on
* the first observer entry or a short timeout so it never hangs.
*/
function observeElementVisibility(target: Element): Promise<{ ratio: number; visible: boolean }> {
if (typeof IntersectionObserver === 'undefined') return Promise.resolve({ ratio: 0, visible: false });
return new Promise((resolve) => {
let settled = false;
let timer = 0;
const finish = (entry?: IntersectionObserverEntry): void => {
if (settled) return;
settled = true;
window.clearTimeout(timer);
observer.disconnect();
if (!entry) {
resolve({ ratio: 0, visible: false });
return;
}
const isVisible = (entry as IntersectionObserverEntry & { isVisible?: boolean }).isVisible;
resolve({
ratio: entry.intersectionRatio,
visible: isVisible === undefined ? entry.intersectionRatio >= 0.99 : isVisible === true,
});
};
const observer = new IntersectionObserver((entries) => finish(entries[0]), {
threshold: [0, 0.99, 1],
trackVisibility: true,
delay: 100,
} as IntersectionObserverInit);
observer.observe(target);
timer = window.setTimeout(() => finish(), 250);
});
}
export class VaultSandboxClient {
private iframe: HTMLIFrameElement;
private backdrop: HTMLDivElement | null = null;
private pending = new Map<string, PendingRequest>();
private readyPromise: Promise<ReadyMessage>;
private handshaken = false;
private modalVisible = false;
// Ids of in-flight interactive requests whose launcher card keeps the iframe expanded. While the
// modal is up, optional geometry evidence is refreshed; final high-risk authorization happens in
// the top-level sandbox window and never trusts a parent hit-test claim.
private interactiveRequests = new Set<string>();
private surfaceRefreshTimer: number | null = null;
private constructor(iframe: HTMLIFrameElement) {
this.iframe = iframe;
this.readyPromise = this.waitForReady();
window.addEventListener('message', this.handleMessage);
}
static async create(): Promise<VaultSandboxClient> {
// Snapshot the reset generation so we can discard this client if a reset lands mid-creation.
const generation = clientGeneration;
// Gated during pre-launch iteration — see VAULT_SANDBOX_INTEGRITY_ENFORCED. When off, the
// parent still origin-isolates the sandbox; it just doesn't fail-closed on a manifest mismatch.
if (VAULT_SANDBOX_INTEGRITY_ENFORCED) await verifyVaultSandboxIntegrity();
const iframe = document.createElement('iframe');
iframe.title = 'Avibe protected vault sandbox';
iframe.allow = 'publickey-credentials-get; publickey-credentials-create; clipboard-write';
iframe.referrerPolicy = 'no-referrer';
iframe.style.position = 'fixed';
iframe.style.top = '50%';
iframe.style.left = '50%';
iframe.style.transform = 'translate(-50%, -50%)';
iframe.style.border = '0';
iframe.style.background = 'transparent';
iframe.style.zIndex = '2147483647';
iframe.style.colorScheme = 'normal';
iframe.style.borderRadius = '16px';
iframe.style.overflow = 'hidden';
iframe.style.boxShadow = 'none';
// At rest the sandbox is a headless RPC worker: keep it in the DOM (so
// postMessage works) but 0-sized + hidden so it never covers the app. It
// only expands to a centered modal while the sandbox asks for its slot via
// a `ui.show` event — see setModalVisible().
iframe.style.width = '0';
iframe.style.height = '0';
iframe.style.visibility = 'hidden';
iframe.style.pointerEvents = 'none';
const client = new VaultSandboxClient(iframe);
iframe.src = VAULT_SANDBOX_IFRAME_URL;
document.body.appendChild(iframe);
await client.handshake();
if (generation !== clientGeneration) {
// A reset (e.g. Strict enabled) landed while we were handshaking — this client pinned the
// pre-reset policy. Discard it and fail so the caller re-acquires a fresh, correctly-pinned
// client instead of proceeding under the stale policy.
client.destroy();
throw new VaultSandboxError('sandbox_reset', 'Sandbox client was reset during creation', true);
}
activeClient = client;
return client;
}
private get target(): Window {
const target = this.iframe.contentWindow;
if (!target) throw new VaultSandboxError('sandbox_unavailable', 'Sandbox iframe is unavailable', true);
return target;
}
private ensureBackdrop(): HTMLDivElement {
if (this.backdrop?.isConnected) return this.backdrop;
const backdrop = document.createElement('div');
backdrop.setAttribute('aria-hidden', 'true');
backdrop.style.position = 'fixed';
backdrop.style.inset = '0';
backdrop.style.background = 'rgba(0, 0, 0, 0.5)';
backdrop.style.zIndex = '2147483646';
backdrop.style.pointerEvents = 'auto';
document.body.insertBefore(backdrop, this.iframe);
this.backdrop = backdrop;
return backdrop;
}
// Expand to a lightweight centered modal while the sandbox holds its slot (`ui.show`), otherwise
// collapse to a hidden 0-size worker (`ui.hide`) so silent R1/R2 ops never cover the app. Driven
// by sandbox events, not per-call flags — a silent operation emits no `ui.show` and stays hidden.
private setModalVisible(visible: boolean): void {
this.modalVisible = visible;
if (visible) {
this.ensureBackdrop();
} else {
this.backdrop?.remove();
this.backdrop = null;
}
this.iframe.style.width = visible ? 'min(440px, 92vw)' : '0';
this.iframe.style.height = visible ? 'min(640px, 88vh)' : '0';
this.iframe.style.visibility = visible ? 'visible' : 'hidden';
this.iframe.style.pointerEvents = visible ? 'auto' : 'none';
this.iframe.style.boxShadow = visible ? '0 24px 80px rgba(15, 23, 42, 0.38)' : 'none';
// The expanded modal is the sandbox's on-screen confirm surface. Attest it to the sandbox while
// it's up, and stop once it collapses (protocol v2 §6.6). Refresh starts only after this
// expansion so the measurement reflects the visible modal, not the 0-size headless worker.
if (visible) {
this.startSurfaceRefresh();
} else {
this.stopSurfaceRefresh();
}
}
/**
* Measure the sandbox iframe in the parent (embedder) document and package geometry/observer
* evidence for compatibility and diagnostics. No parent hit-test claim is sent because the
* embedder is not a trusted security authority for the final authorization.
*/
private async measureSurface(): Promise<VaultConfirmSurface | null> {
if (typeof window === 'undefined' || !this.iframe.isConnected) return null;
const rect = this.iframe.getBoundingClientRect();
const style = window.getComputedStyle(this.iframe);
const observed = await observeElementVisibility(this.iframe);
return buildVaultConfirmSurface({
frameWidth: rect.width,
frameHeight: rect.height,
intersectionRatio: observed.ratio,
visibleByIntersectionObserver: observed.visible,
opacity: style.opacity,
pointerEvents: style.pointerEvents,
sampledAt: Date.now(),
});
}
private startSurfaceRefresh(): void {
this.stopSurfaceRefresh();
// Emit once immediately (right after the modal expanded) then on a fixed cadence well under the
// sandbox's 60 s staleness cap, so a fresh attestation is always waiting when the user confirms.
void this.emitSurfaceAttestation();
this.surfaceRefreshTimer = window.setInterval(() => {
void this.emitSurfaceAttestation();
}, SURFACE_REFRESH_INTERVAL_MS);
}
private stopSurfaceRefresh(): void {
if (this.surfaceRefreshTimer !== null) {
window.clearInterval(this.surfaceRefreshTimer);
this.surfaceRefreshTimer = null;
}
}
/**
* Refresh the parent surface attestation for every in-flight interactive request via a
* `confirm.surface` event carrying the live rpc request id (protocol v2 §6.6 / §13). One
* measurement is shared across all active ceremonies (in practice the modal hosts one at a time).
*/
private async emitSurfaceAttestation(): Promise<void> {
if (this.interactiveRequests.size === 0) return;
const surface = await this.measureSurface();
if (!surface) return;
// The set may have drained (request settled) while we awaited the observer reading.
for (const id of [...this.interactiveRequests]) {
this.postSurfaceEvent(id, surface);
}
}
private postSurfaceEvent(id: string, surface: VaultConfirmSurface): void {
try {
this.target.postMessage(
{ channel: CHANNEL, version: VERSION, kind: 'event', event: 'confirm.surface', id, surface },
VAULT_SANDBOX_ORIGIN,
);
} catch {
// The iframe may be mid-teardown or already removed; the next real request surfaces staleness.
}
}
private waitForReady(): Promise<ReadyMessage> {
return new Promise((resolve, reject) => {
const timer = window.setTimeout(() => {
window.removeEventListener('message', onMessage);
reject(new VaultSandboxError('sandbox_ready_timeout', 'Sandbox did not become ready', true));
}, DEFAULT_TIMEOUT_MS);
const onMessage = (event: MessageEvent) => {
if (event.origin !== VAULT_SANDBOX_ORIGIN || event.source !== this.iframe.contentWindow) return;
const ready = parseReadyMessage(event.data);
if (!ready) return;
window.clearTimeout(timer);
window.removeEventListener('message', onMessage);
const operations = ready.capabilities?.operations ?? [];
const missing = REQUIRED_OPS.filter((op) => !operations.includes(op));
if (ready.build?.buildHash !== VAULT_SANDBOX_EXPECTED_BUILD_HASH) {
reject(new VaultSandboxError('sandbox_build_mismatch', 'Sandbox build hash does not match the pinned manifest'));
} else if (missing.length > 0) {
reject(new VaultSandboxError('sandbox_capability_mismatch', `Sandbox is missing operations: ${missing.join(', ')}`));
} else {
resolve(ready);
}
};
window.addEventListener('message', onMessage);
});
}
private handleMessage = (event: MessageEvent): void => {
if (event.origin !== VAULT_SANDBOX_ORIGIN || event.source !== this.iframe.contentWindow) return;
const eventMessage = parseEventMessage(event.data);
if (eventMessage) {
this.handleEvent(eventMessage);
return;
}
const reply = parseTerminalMessage(event.data);
if (!reply) return;
const pending = this.pending.get(reply.id);
if (!pending) return;
this.pending.delete(reply.id);
this.interactiveRequests.delete(reply.id);
window.clearTimeout(pending.timer);
// Safety net: if the sandbox errored out of a card without emitting `ui.hide`, collapse once
// the last in-flight request settles so a stale modal can't strand the app behind a backdrop.
if (this.pending.size === 0 && this.modalVisible) this.setModalVisible(false);
if (reply.ok) {
pending.resolve(reply.result);
} else {
pending.reject(serializeSandboxError(reply.error));
}
};
private handleEvent(message: EventMessage): void {
if (message.event === 'ui.show') {
this.setModalVisible(true);
return;
}
if (message.event === 'ui.hide') {
this.setModalVisible(false);
return;
}
const state = parseVaultStateEvent(message.payload);
if (!state) return;
for (const listener of [...vaultStateListeners]) listener(state);
}
private async handshake(): Promise<void> {
await this.readyPromise;
// Pull the daemon-persisted policy so the very first ceremony runs under the configured
// window/strict values; best-effort — a failure leaves the default policy in place.
await refreshVaultSandboxPolicy();
await this.request(
'handshake',
{
parentOrigin: window.location.origin,
nonce: randomId(),
expectedBuildHash: VAULT_SANDBOX_EXPECTED_BUILD_HASH,
appearance: getVaultSandboxAppearance(),
policy: getVaultSandboxPolicy(),
},
{ timeoutMs: DEFAULT_TIMEOUT_MS },
);
this.handshaken = true;
this.setAppearance(getVaultSandboxAppearance());
}
setAppearance(appearance: VaultSandboxAppearance): void {
if (!this.handshaken) return;
try {
this.target.postMessage(
{
channel: CHANNEL,
version: VERSION,
id: randomId(),
op: 'set-appearance' satisfies ParentOnlySandboxOp,
payload: appearance,
},
VAULT_SANDBOX_ORIGIN,
);
} catch {
// The iframe may be mid-navigation or already removed; the next real
// sandbox request will surface availability errors if the client is stale.
}
}
private async request<T>(
op: VaultSandboxOp,
payload?: unknown,
options: { timeoutMs?: number; interactive?: boolean; authorizationWindow?: string } = {},
): Promise<T> {
await this.readyPromise;
const id = randomId();
// Interactive ops expand the iframe before sending so the launcher card is visible before the
// request reaches the sandbox. The final authorization is completed in a top-level window;
// the optional surface evidence remains a compatibility field, never a security decision.
// When the caller already opened that window, the sandbox needs no launcher card, so the
// iframe stays collapsed until the sandbox asks for its slot with `ui.show`.
let surface: VaultConfirmSurface | null = null;
try {
if (options.interactive) {
this.interactiveRequests.add(id);
if (!options.authorizationWindow) {
this.setModalVisible(true);
surface = await this.measureSurface();
}
}
} catch (error) {
this.interactiveRequests.delete(id);
if (this.interactiveRequests.size === 0 && this.modalVisible) this.setModalVisible(false);
throw error;
}
const promise = new Promise<T>((resolve, reject) => {
const timer = window.setTimeout(() => {
this.pending.delete(id);
this.interactiveRequests.delete(id);
if (this.pending.size === 0 && this.modalVisible) this.setModalVisible(false);
reject(new VaultSandboxError('sandbox_request_timeout', `Sandbox ${op} request timed out`, true));
}, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
this.pending.set(id, {
resolve: (value) => resolve(value as T),
reject,
timer,
});
});
this.target.postMessage(
{
channel: CHANNEL,
version: VERSION,
id,
op,
payload: payload ?? {},
...(surface ? { surface } : {}),
...(options.authorizationWindow ? { authorizationWindow: options.authorizationWindow } : {}),
},
VAULT_SANDBOX_ORIGIN,
);
return promise;
}
status(wrapMeta?: string | null): Promise<VaultSandboxStatusResult> {
return this.request<VaultSandboxStatusResult>('status', wrapMeta ? { wrapMeta } : {});
}
async setup(payload: {
vaultUserHandle: string;
displayName: string;
existingProtectedVault: boolean;
authzCreationOptions?: unknown;
rootMetadata?: unknown;
}): Promise<VaultSandboxSetupResult> {
// Symmetric with unlock(): refresh the daemon policy and pass it so the first-ever unlocked
// session (the setup ceremony) reflects a window/Strict change made after handshake but before
// setup. The sandbox applies the passed policy on setup (protocol v2 §6.5).
await refreshVaultSandboxPolicy();
return this.request<VaultSandboxSetupResult>(
'setup',
{ ...payload, policy: getVaultSandboxPolicy() },
{ timeoutMs: INTERACTIVE_TIMEOUT_MS },
);
}
async unlock(payload: { wrapMeta: string }): Promise<VaultSandboxUnlockResult> {
// Pull the freshest daemon policy and pass it (protocol v2 §6.5): a settings change made in
// another tab only broadcasts a lock, not the new policy, and the handshake fetch is
// best-effort, so the cached mirror alone can carry stale settings. The sandbox applies the
// passed policy on unlock. Note this covers *explicit* unlocks; the sandbox's internal
// auto-unlock (a protected op run while locked) still uses the policy pinned at handshake, so a
// policy tightening like enabling Strict forces a fresh handshake (resetVaultSandboxClient) to
// re-pin — see the settings dialog. Best-effort: a failed refresh fails closed (strict).
await refreshVaultSandboxPolicy();
return this.request<VaultSandboxUnlockResult>(
'unlock',
{ wrapMeta: payload.wrapMeta, policy: getVaultSandboxPolicy() },
{ timeoutMs: INTERACTIVE_TIMEOUT_MS },
);
}
lock(): Promise<{ ok?: boolean; state?: VaultSandboxState }> {
return this.request<{ ok?: boolean; state?: VaultSandboxState }>('lock', {}, { timeoutMs: DEFAULT_TIMEOUT_MS });
}
seal(
payload:
| { name: string; kind: 'static'; value: string; wrapMeta?: string | null }
| { name: string; kind: 'keypair'; wrapMeta?: string | null },
): Promise<VaultSandboxSealResult> {
// Static = parent-typed value handed in for sealing (the #842 concession). Keypair = generated
// entirely inside the sandbox (generate-only, no input) returning ciphertext + public material.
const wire =
payload.kind === 'static'
? { name: payload.name, kind: 'static', inputMode: 'parent-value', value: payload.value, wrapMeta: payload.wrapMeta }
: { name: payload.name, kind: 'keypair', wrapMeta: payload.wrapMeta };
return this.request<VaultSandboxSealResult>('seal', wire, { timeoutMs: INTERACTIVE_TIMEOUT_MS });
}
reveal(
payload: { material: ProtectedUnlockMaterialLike; context: VaultSignedOperationContext },
authorizationWindow?: string,
): Promise<{ completed: boolean }> {
return this.request<{ completed: boolean }>('reveal', payload, {
timeoutMs: INTERACTIVE_TIMEOUT_MS,
interactive: true,
authorizationWindow,
});
}
sign(payload: {
material: ProtectedUnlockMaterialLike;
scheme: SignatureScheme;
signingContext: VaultSandboxSigningContext;
context: VaultSignedOperationContext;
}, authorizationWindow?: string): Promise<SignatureResult> {
return this.request<SignatureResult>('sign', payload, { timeoutMs: INTERACTIVE_TIMEOUT_MS, interactive: true, authorizationWindow });
}
/**
* Batch DEK release: one confirm card lists every member, then the sandbox emits one HPKE blind
* box per item (order matches `items`). Replaces v1 `releaseDEK`'s per-secret ceremony.
*/
approveRelease(payload: { items: ApproveReleaseItem[] }, authorizationWindow?: string): Promise<{ blindBoxes: BlindBox[] }> {
return this.request<{ blindBoxes: BlindBox[] }>('approveRelease', payload, {
timeoutMs: INTERACTIVE_TIMEOUT_MS,
interactive: true,
authorizationWindow,
});
}
/**
* Tear down this client: stop listening, collapse the modal, drop the iframe, and fail any
* in-flight request. Used by resetVaultSandboxClient() to force a fresh handshake (e.g. after a
* policy tightening) — the sandbox pins its enforced policy at handshake, so a new client is how
* a Strict change reaches the internal auto-unlock path immediately.
*/
destroy(): void {
window.removeEventListener('message', this.handleMessage);
for (const [, pending] of this.pending) {
window.clearTimeout(pending.timer);
pending.reject(new VaultSandboxError('sandbox_reset', 'Sandbox client was reset', true));
}
this.pending.clear();
this.interactiveRequests.clear();
this.setModalVisible(false);
this.iframe.remove();
}
}
type ProtectedUnlockMaterialLike = {
name: string;
kind?: string | null;
envelope: ProtectedRecordEnvelope;
};
export async function getVaultSandboxClient(): Promise<VaultSandboxClient> {
if (!singleton) {
const pending: Promise<VaultSandboxClient> = VaultSandboxClient.create().catch((err) => {
// Only clear the globals if they still refer to THIS attempt. A reset may have already
// replaced `singleton` with a newer create and `activeClient` with a live client; clearing
// them here unconditionally would orphan that client's iframe (leaving its session state
// behind while a fresh client is built on the next call). create() already destroyed its own
// client on the reset-throw path, so there's nothing else to clean up here.
if (singleton === pending) {
singleton = null;
activeClient = null;
}
throw err;
});
singleton = pending;
}
return singleton;
}
/**
* Discard the current sandbox client so the next {@link getVaultSandboxClient} builds a fresh one
* and re-handshakes. The sandbox pins its enforced session policy at the first handshake, so this
* is how a policy tightening (enabling Strict) takes effect immediately on *every* path — including
* the sandbox's internal auto-unlock — rather than only on the next explicit unlock. The caller is
* responsible for reflecting the resulting locked state in the parent (see the settings dialog).
*/
export function resetVaultSandboxClient(): void {
// Advance the generation first so any in-flight create() discards itself on completion.
clientGeneration += 1;
const client = activeClient;
singleton = null;
activeClient = null;
client?.destroy();
}
export function getActiveVaultSandboxClient(): VaultSandboxClient | null {
return activeClient;
}