@adea-ai/spatial 0.94.0 → 0.96.0

package/dist/sim-bridge/launch.d.ts

@@ -0,0 +1,111 @@
+import type { OriginAllowlist } from './origin';
+/**
+ * Launch contract between the Adea host, the Adea backend and the hosted Agent Sim origin.
+ *
+ * 1. The host asks the Adea backend to launch a surface (`SimLaunchRequest`). The backend checks
+ *    the signed-in account's entitlement; localhost, an embedded secret or the desktop shell's
+ *    claimed identity are never proof of it.
+ * 2. A granted reply carries one opaque, single-use, short-lived `code`, bound to the host's
+ *    `bridgeId`, the sim origin and the surface. It is not a session and not a credential for any
+ *    other Adea API.
+ * 3. The host posts the code to the sim frame (`host.launch`). The frame calls the sim origin's
+ *    exchange (`SimSessionExchangeRequest`); the sim origin redeems the code once and sets a
+ *    sim-only session cookie (see `cookie.ts`). No token appears in any request or response body.
+ *
+ * Every parser here is strict: unknown keys, wrong types and token-looking extras are refused.
+ */
+export declare const SIM_LAUNCH_SCHEMA_VERSION = 1;
+/** A launch code is useless after this long, whatever the backend says. */
+export declare const MAX_SIM_LAUNCH_TTL_MS = 120000;
+export declare const SIM_SURFACES: readonly ['hq', 'character-designer', 'room-designer'];
+export type SimSurface = (typeof SIM_SURFACES)[number];
+export declare const SIM_PLATFORMS: readonly ['desktop', 'web'];
+export type SimPlatform = (typeof SIM_PLATFORMS)[number];
+export type SimLaunchRequest = Readonly<{
+    schemaVersion: typeof SIM_LAUNCH_SCHEMA_VERSION;
+    workspaceId: string;
+    surface: SimSurface;
+    platform: SimPlatform;
+    bridgeId: string;
+}>;
+export type SimLaunchDeniedReason = 'unauthenticated' | 'not_entitled';
+export type SimLaunchUnavailableReason = 'not_configured' | 'service_unavailable';
+export type SimLaunchGrant = Readonly<{
+    status: 'granted';
+    code: string;
+    expiresAt: string;
+    surface: SimSurface;
+    frameOrigin: string;
+}> | Readonly<{
+    status: 'denied';
+    reason: SimLaunchDeniedReason;
+}> | Readonly<{
+    status: 'unavailable';
+    reason: SimLaunchUnavailableReason;
+}>;
+export type SimSessionExchangeRequest = Readonly<{
+    schemaVersion: typeof SIM_LAUNCH_SCHEMA_VERSION;
+    code: string;
+    bridgeId: string;
+}>;
+export type SimSessionRejectedReason = 'code_expired' | 'code_used' | 'not_entitled' | 'origin_refused';
+export type SimSessionExchangeResult = Readonly<{
+    status: 'session';
+    expiresAt: string;
+}> | Readonly<{
+    status: 'rejected';
+    reason: SimSessionRejectedReason;
+}> | Readonly<{
+    status: 'unavailable';
+}>;
+export declare function parseSimLaunchRequest(value: unknown): SimLaunchRequest | null;
+export type SimGrantExpectation = Readonly<{
+    origins: OriginAllowlist;
+    /** Epoch milliseconds the host considers "now". */
+    now: number;
+    /** The surface the host asked for; a grant for any other surface is refused. */
+    surface: SimSurface;
+}>;
+/**
+ * The backend's launch reply, or null when it is malformed, stale, longer-lived than the contract
+ * allows, for another surface, or points at a frame origin the host did not allowlist.
+ */
+export declare function parseSimLaunchGrant(value: unknown, expected: SimGrantExpectation): SimLaunchGrant | null;
+export declare function parseSimSessionExchangeRequest(value: unknown): SimSessionExchangeRequest | null;
+/** The sim origin's exchange reply. A session reply carries its expiry and nothing else. */
+export declare function parseSimSessionExchangeResult(value: unknown): SimSessionExchangeResult | null;
+export type SimLaunchPayload = Readonly<{
+    code: string;
+    expiresAt: string;
+    surface: SimSurface;
+    character?: string;
+}>;
+/**
+ * Frame side: accepts the first launch payload still inside its window and refuses every later one,
+ * so a replayed or duplicated `host.launch` can never trigger a second exchange.
+ */
+export declare function createLaunchOnce(): Readonly<{
+    take(payload: SimLaunchPayload, now: number): SimLaunchPayload | null;
+}>;
+export type LaunchCodeBinding = Readonly<{
+    bridgeId: string;
+    origin: string;
+    surface: SimSurface;
+}>;
+export type LaunchCodeRedemption = Readonly<{
+    ok: true;
+    surface: SimSurface;
+}> | Readonly<{
+    ok: false;
+    reason: 'unknown' | 'code_expired' | 'code_used' | 'origin_refused';
+}>;
+/**
+ * Reference single-use semantics for the backend's code exchange, used by the local bootstrap tests.
+ * A code redeems at most once: it is spent by its first presentation, whether or not that
+ * presentation matched the binding, so a leaked code cannot be retried with guessed bindings.
+ * A durable implementation keeps the same observable behaviour.
+ */
+export declare function createLaunchCodeLedger(): Readonly<{
+    issue(code: string, binding: LaunchCodeBinding, expiresAt: number): void;
+    redeem(code: string, presented: Omit<LaunchCodeBinding, 'surface'>, now: number): LaunchCodeRedemption;
+}>;

package/dist/sim-bridge/launch.js

@@ -0,0 +1,153 @@
+import { boundedString, isoInstant, ownDataValue, strictRecord } from './record';
+/**
+ * Launch contract between the Adea host, the Adea backend and the hosted Agent Sim origin.
+ *
+ * 1. The host asks the Adea backend to launch a surface (`SimLaunchRequest`). The backend checks
+ *    the signed-in account's entitlement; localhost, an embedded secret or the desktop shell's
+ *    claimed identity are never proof of it.
+ * 2. A granted reply carries one opaque, single-use, short-lived `code`, bound to the host's
+ *    `bridgeId`, the sim origin and the surface. It is not a session and not a credential for any
+ *    other Adea API.
+ * 3. The host posts the code to the sim frame (`host.launch`). The frame calls the sim origin's
+ *    exchange (`SimSessionExchangeRequest`); the sim origin redeems the code once and sets a
+ *    sim-only session cookie (see `cookie.ts`). No token appears in any request or response body.
+ *
+ * Every parser here is strict: unknown keys, wrong types and token-looking extras are refused.
+ */
+export const SIM_LAUNCH_SCHEMA_VERSION = 1;
+/** A launch code is useless after this long, whatever the backend says. */
+export const MAX_SIM_LAUNCH_TTL_MS = 120_000;
+export const SIM_SURFACES = ['hq', 'character-designer', 'room-designer'];
+export const SIM_PLATFORMS = ['desktop', 'web'];
+const BRIDGE_ID = /^[A-Za-z0-9_-]{16,64}$/;
+const LAUNCH_CODE = /^[A-Za-z0-9_-]{32,128}$/;
+const WORKSPACE_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
+const DENIED_REASONS = ['unauthenticated', 'not_entitled'];
+const UNAVAILABLE_REASONS = ['not_configured', 'service_unavailable'];
+const REJECTED_REASONS = ['code_expired', 'code_used', 'not_entitled', 'origin_refused'];
+export function parseSimLaunchRequest(value) {
+    const body = strictRecord(value, [
+        'schemaVersion',
+        'workspaceId',
+        'surface',
+        'platform',
+        'bridgeId',
+    ]);
+    if (!body || body.schemaVersion !== SIM_LAUNCH_SCHEMA_VERSION)
+        return null;
+    const workspaceId = boundedString(body.workspaceId, WORKSPACE_ID);
+    const bridgeId = boundedString(body.bridgeId, BRIDGE_ID);
+    const surface = SIM_SURFACES.find((item) => item === body.surface);
+    const platform = SIM_PLATFORMS.find((item) => item === body.platform);
+    if (!workspaceId || !bridgeId || !surface || !platform)
+        return null;
+    return { schemaVersion: SIM_LAUNCH_SCHEMA_VERSION, workspaceId, surface, platform, bridgeId };
+}
+/**
+ * The backend's launch reply, or null when it is malformed, stale, longer-lived than the contract
+ * allows, for another surface, or points at a frame origin the host did not allowlist.
+ */
+export function parseSimLaunchGrant(value, expected) {
+    const status = ownDataValue(value, 'status');
+    if (status === 'denied') {
+        const body = strictRecord(value, ['status', 'reason']);
+        const reason = DENIED_REASONS.find((item) => item === body?.reason);
+        return reason ? { status, reason } : null;
+    }
+    if (status === 'unavailable') {
+        const body = strictRecord(value, ['status', 'reason']);
+        const reason = UNAVAILABLE_REASONS.find((item) => item === body?.reason);
+        return reason ? { status, reason } : null;
+    }
+    if (status !== 'granted')
+        return null;
+    const body = strictRecord(value, ['status', 'code', 'expiresAt', 'surface', 'frameOrigin']);
+    const code = boundedString(body?.code, LAUNCH_CODE);
+    const expiresAt = isoInstant(body?.expiresAt);
+    const surface = SIM_SURFACES.find((item) => item === body?.surface);
+    const frameOrigin = body?.frameOrigin;
+    if (!body || !code || expiresAt === null || surface !== expected.surface)
+        return null;
+    if (!expected.origins.has(frameOrigin) || typeof frameOrigin !== 'string')
+        return null;
+    if (expiresAt <= expected.now || expiresAt > expected.now + MAX_SIM_LAUNCH_TTL_MS)
+        return null;
+    return { status, code, expiresAt: body.expiresAt, surface, frameOrigin };
+}
+export function parseSimSessionExchangeRequest(value) {
+    const body = strictRecord(value, ['schemaVersion', 'code', 'bridgeId']);
+    if (!body || body.schemaVersion !== SIM_LAUNCH_SCHEMA_VERSION)
+        return null;
+    const code = boundedString(body.code, LAUNCH_CODE);
+    const bridgeId = boundedString(body.bridgeId, BRIDGE_ID);
+    return code && bridgeId ? { schemaVersion: SIM_LAUNCH_SCHEMA_VERSION, code, bridgeId } : null;
+}
+/** The sim origin's exchange reply. A session reply carries its expiry and nothing else. */
+export function parseSimSessionExchangeResult(value) {
+    const status = ownDataValue(value, 'status');
+    if (status === 'unavailable')
+        return strictRecord(value, ['status']) ? { status } : null;
+    if (status === 'rejected') {
+        const body = strictRecord(value, ['status', 'reason']);
+        const reason = REJECTED_REASONS.find((item) => item === body?.reason);
+        return reason ? { status, reason } : null;
+    }
+    if (status !== 'session')
+        return null;
+    const body = strictRecord(value, ['status', 'expiresAt']);
+    return body && isoInstant(body.expiresAt) !== null
+        ? { status, expiresAt: body.expiresAt }
+        : null;
+}
+/**
+ * Frame side: accepts the first launch payload still inside its window and refuses every later one,
+ * so a replayed or duplicated `host.launch` can never trigger a second exchange.
+ */
+export function createLaunchOnce() {
+    let taken = false;
+    return {
+        take(payload, now) {
+            if (taken)
+                return null;
+            const expiresAt = isoInstant(payload.expiresAt);
+            if (expiresAt === null || expiresAt <= now)
+                return null;
+            taken = true;
+            return payload;
+        },
+    };
+}
+/**
+ * Reference single-use semantics for the backend's code exchange, used by the local bootstrap tests.
+ * A code redeems at most once: it is spent by its first presentation, whether or not that
+ * presentation matched the binding, so a leaked code cannot be retried with guessed bindings.
+ * A durable implementation keeps the same observable behaviour.
+ */
+export function createLaunchCodeLedger() {
+    const entries = new Map();
+    return {
+        issue(code, binding, expiresAt) {
+            if (!Number.isFinite(expiresAt))
+                throw new RangeError('launch code expiry must be finite');
+            entries.set(code, { binding, expiresAt, spent: false });
+        },
+        redeem(code, presented, now) {
+            // An unusable clock reading cannot prove the code is still live, so it fails closed. Nothing
+            // is spent: the comparison below would otherwise be false for NaN and let an expired code pass.
+            if (!Number.isFinite(now))
+                return { ok: false, reason: 'code_expired' };
+            const entry = entries.get(code);
+            if (!entry)
+                return { ok: false, reason: 'unknown' };
+            if (entry.spent)
+                return { ok: false, reason: 'code_used' };
+            entry.spent = true;
+            if (entry.expiresAt <= now)
+                return { ok: false, reason: 'code_expired' };
+            if (entry.binding.bridgeId !== presented.bridgeId ||
+                entry.binding.origin !== presented.origin)
+                return { ok: false, reason: 'origin_refused' };
+            return { ok: true, surface: entry.binding.surface };
+        },
+    };
+}

package/dist/sim-bridge/messages.d.ts

@@ -0,0 +1,133 @@
+import type { OriginAllowlist } from './origin';
+import { type SimSurface } from './launch';
+import { type SimUnavailableReason } from './availability';
+/**
+ * Versioned message schema between the Adea host window and the hosted Agent Sim frame.
+ *
+ * The bridge is a closed set of typed messages and nothing else: there is no generic call,
+ * eval, filesystem, native-bridge or credential message, and no field of any message may carry a
+ * token. Every message is validated against the exact frame origin, the exact frame window, the
+ * per-mount `bridgeId` the host issued, the protocol version and a strict payload shape. Anything
+ * else is dropped and never acted on.
+ */
+export declare const SIM_BRIDGE_CHANNEL = "adea.agent-sim.bridge";
+export declare const SIM_BRIDGE_VERSION = 1;
+export declare const MAX_SIM_MESSAGE_BYTES = 2048;
+export declare const SIM_FRAME_STATES: readonly ['loading', 'running', 'unavailable', 'offline'];
+export type SimFrameState = (typeof SIM_FRAME_STATES)[number];
+export declare const SIM_FRAME_ERRORS: readonly ['launch_rejected', 'asset_unavailable', 'engine_failed', 'bridge_incompatible'];
+export type SimFrameError = (typeof SIM_FRAME_ERRORS)[number];
+/** Where HQ may send the host: the designers only. A designer returns with `frame.close`. */
+export declare const SIM_NAVIGATE_TARGETS: readonly ['room-designer', 'character-designer'];
+export type SimNavigateTarget = (typeof SIM_NAVIGATE_TARGETS)[number];
+export declare const SIM_SAVE_FAILURES: readonly ['refused', 'failed', 'timeout'];
+export type SimSaveFailure = (typeof SIM_SAVE_FAILURES)[number];
+/** What the frame reports about its own launch; the pure launch reducer consumes only these. */
+export type SimFrameStatusMessage = Readonly<{
+    type: 'frame.ready';
+    payload: Readonly<Record<string, never>>;
+}> | Readonly<{
+    type: 'frame.state';
+    payload: Readonly<{
+        state: SimFrameState;
+        reason?: SimUnavailableReason;
+    }>;
+}> | Readonly<{
+    type: 'frame.close';
+    payload: Readonly<Record<string, never>>;
+}> | Readonly<{
+    type: 'frame.error';
+    payload: Readonly<{
+        code: SimFrameError;
+    }>;
+}>;
+/** Closed requests the frame may make of the host. Each is answered or ends the attempt. */
+export type SimFrameRequestMessage = Readonly<{
+    type: 'frame.navigate';
+    payload: Readonly<{
+        requestId: string;
+        target: SimNavigateTarget;
+    }>;
+}> | Readonly<{
+    type: 'frame.character.save';
+    payload: Readonly<{
+        requestId: string;
+        character: string;
+    }>;
+}>;
+export type SimFrameMessage = SimFrameStatusMessage | SimFrameRequestMessage;
+export type SimHostMessage = Readonly<{
+    type: 'host.launch';
+    payload: Readonly<{
+        /** Opaque single-use code. It is exchanged at the sim origin for a sim-only session. */
+        code: string;
+        expiresAt: string;
+        surface: SimSurface;
+        character?: string;
+    }>;
+}> | Readonly<{
+    type: 'host.dispose';
+    payload: Readonly<Record<string, never>>;
+}> | Readonly<{
+    type: 'host.character.save.result';
+    payload: Readonly<{
+        requestId: string;
+        saved: boolean;
+        reason?: SimSaveFailure;
+    }>;
+}>;
+export type SimBridgeFailure = 'origin_refused' | 'source_mismatch' | 'not_a_bridge_message' | 'version_unsupported' | 'bridge_mismatch' | 'unknown_type' | 'invalid_payload' | 'too_large';
+export type SimBridgeResult<T> = Readonly<{
+    ok: true;
+    message: T;
+}> | Readonly<{
+    ok: false;
+    reason: SimBridgeFailure;
+}>;
+export type SimMessageEventLike = Readonly<{
+    origin: unknown;
+    source: unknown;
+    data: unknown;
+}>;
+export type SimHostContext = Readonly<{
+    origins: OriginAllowlist;
+    /** The frame element's `contentWindow`, read when the event arrives. */
+    frameWindow: unknown;
+    /** Issued by the host for this mount; the frame must echo it. */
+    bridgeId: string;
+}>;
+/** Host side: accept a message only from the exact frame window at an allowlisted origin. */
+export declare function parseFrameMessage(event: SimMessageEventLike, context: SimHostContext): SimBridgeResult<SimFrameMessage>;
+export type SimFrameContext = Readonly<{
+    /** The exact origin of the Adea host that embeds this frame. */
+    parentOrigin: string;
+    /** `window.parent`, compared by identity. */
+    parentWindow: unknown;
+    bridgeId: string;
+}>;
+/** Frame side: accept a message only from the embedding host window at its exact origin. */
+export declare function parseHostMessage(event: SimMessageEventLike, context: SimFrameContext): SimBridgeResult<SimHostMessage>;
+/** A fresh per-mount nonce: 128 random bits as base64url. The host issues it; the frame echoes it. */
+export declare function createBridgeId(fill?: (bytes: Uint8Array) => Uint8Array): string;
+export declare function frameEnvelope(bridgeId: string, message: SimFrameMessage): {
+    readonly channel: "adea.agent-sim.bridge";
+    readonly version: 1;
+    readonly bridgeId: string;
+    readonly type: string;
+    readonly payload: object;
+};
+export declare function hostEnvelope(bridgeId: string, message: SimHostMessage): {
+    readonly channel: "adea.agent-sim.bridge";
+    readonly version: 1;
+    readonly bridgeId: string;
+    readonly type: string;
+    readonly payload: object;
+};
+type PostTarget = Readonly<{
+    postMessage(message: unknown, targetOrigin: string): void;
+}>;
+/** Host to frame. The target origin must be allowlisted; `*` can never be used. */
+export declare function postToFrame(frameWindow: PostTarget, frameOrigin: string, origins: OriginAllowlist, bridgeId: string, message: SimHostMessage): void;
+/** Frame to host. The target is the exact embedding origin the frame was configured with. */
+export declare function postToHost(parentWindow: PostTarget, parentOrigin: string, bridgeId: string, message: SimFrameMessage): void;
+export {};

package/dist/sim-bridge/messages.js

@@ -0,0 +1,244 @@
+import { boundedString, isPlainRecord, strictRecord } from './record';
+import { SIM_SURFACES } from './launch';
+import { parseSimCharacterValue } from './character';
+import { SIM_UNAVAILABLE_REASONS } from './availability';
+/**
+ * Versioned message schema between the Adea host window and the hosted Agent Sim frame.
+ *
+ * The bridge is a closed set of typed messages and nothing else: there is no generic call,
+ * eval, filesystem, native-bridge or credential message, and no field of any message may carry a
+ * token. Every message is validated against the exact frame origin, the exact frame window, the
+ * per-mount `bridgeId` the host issued, the protocol version and a strict payload shape. Anything
+ * else is dropped and never acted on.
+ */
+export const SIM_BRIDGE_CHANNEL = 'adea.agent-sim.bridge';
+export const SIM_BRIDGE_VERSION = 1;
+export const MAX_SIM_MESSAGE_BYTES = 2048;
+const BRIDGE_ID = /^[A-Za-z0-9_-]{16,64}$/;
+const LAUNCH_CODE = /^[A-Za-z0-9_-]{32,128}$/;
+const REQUEST_ID = /^[A-Za-z0-9_-]{1,32}$/;
+export const SIM_FRAME_STATES = ['loading', 'running', 'unavailable', 'offline'];
+export const SIM_FRAME_ERRORS = [
+    'launch_rejected',
+    'asset_unavailable',
+    'engine_failed',
+    'bridge_incompatible',
+];
+/** Where HQ may send the host: the designers only. A designer returns with `frame.close`. */
+export const SIM_NAVIGATE_TARGETS = ['room-designer', 'character-designer'];
+export const SIM_SAVE_FAILURES = ['refused', 'failed', 'timeout'];
+const ENVELOPE_KEYS = ['channel', 'version', 'bridgeId', 'type', 'payload'];
+function envelope(event, bridgeId) {
+    const data = strictRecord(event.data, ENVELOPE_KEYS);
+    if (!data || data.channel !== 'adea.agent-sim.bridge')
+        return fail('not_a_bridge_message');
+    if (data.version !== SIM_BRIDGE_VERSION)
+        return fail('version_unsupported');
+    if (data.bridgeId !== bridgeId)
+        return fail('bridge_mismatch');
+    if (typeof data.type !== 'string' || !isPlainRecord(data.payload))
+        return fail('invalid_payload');
+    if (!withinBudget(data))
+        return fail('too_large');
+    return { ok: true, message: { type: data.type, payload: data.payload } };
+}
+// Traversal limits for the size check. A record costs more than its keys so that even a cyclic
+// structure (reachable through structured clone) exhausts the budget in a bounded number of steps.
+const MAX_NODES = 32;
+const MAX_DEPTH = 3;
+const MAX_KEYS_PER_RECORD = 16;
+const RECORD_COST = 16;
+/**
+ * A finite size check over plain data: strings, numbers, booleans and nested plain records. It
+ * stops at `MAX_NODES` nodes, `MAX_DEPTH` levels and `MAX_KEYS_PER_RECORD` keys per record, charges
+ * every record against the byte budget, and refuses accessors, so no input (cyclic, deep or wide)
+ * can make it loop or run sender code.
+ */
+function withinBudget(value) {
+    let budget = MAX_SIM_MESSAGE_BYTES;
+    let nodes = 0;
+    const stack = [{ item: value, depth: 0 }];
+    while (stack.length > 0) {
+        const { item, depth } = stack.pop();
+        if (++nodes > MAX_NODES)
+            return false;
+        if (typeof item === 'string')
+            budget -= item.length;
+        else if (typeof item === 'number' || typeof item === 'boolean')
+            budget -= 8;
+        else if (isPlainRecord(item)) {
+            if (depth >= MAX_DEPTH)
+                return false;
+            const keys = Object.getOwnPropertyNames(item);
+            if (keys.length > MAX_KEYS_PER_RECORD)
+                return false;
+            budget -= RECORD_COST;
+            for (const key of keys) {
+                const descriptor = Object.getOwnPropertyDescriptor(item, key);
+                // Reading through a getter would run sender-controlled code; refuse accessors outright.
+                if (!descriptor || !('value' in descriptor))
+                    return false;
+                budget -= key.length + 1;
+                stack.push({ item: descriptor.value, depth: depth + 1 });
+            }
+        }
+        else if (item !== undefined)
+            return false;
+        if (budget < 0)
+            return false;
+    }
+    return true;
+}
+function fail(reason) {
+    return { ok: false, reason };
+}
+/** Host side: accept a message only from the exact frame window at an allowlisted origin. */
+export function parseFrameMessage(event, context) {
+    if (!BRIDGE_ID.test(context.bridgeId))
+        return fail('bridge_mismatch');
+    if (!context.origins.has(event.origin))
+        return fail('origin_refused');
+    if (event.source == null || event.source !== context.frameWindow)
+        return fail('source_mismatch');
+    const opened = envelope(event, context.bridgeId);
+    if (!opened.ok)
+        return opened;
+    const { type, payload } = opened.message;
+    switch (type) {
+        case 'frame.ready':
+        case 'frame.close':
+            return strictRecord(payload, [])
+                ? { ok: true, message: { type, payload: {} } }
+                : fail('invalid_payload');
+        case 'frame.state': {
+            const body = strictRecord(payload, ['state'], ['reason']);
+            const state = SIM_FRAME_STATES.find((item) => item === body?.state);
+            if (!body || !state)
+                return fail('invalid_payload');
+            const reason = SIM_UNAVAILABLE_REASONS.find((item) => item === body.reason);
+            // A reason belongs to `unavailable` and nothing else.
+            if ('reason' in body ? !reason || state !== 'unavailable' : state === 'unavailable')
+                return fail('invalid_payload');
+            return { ok: true, message: { type, payload: reason ? { state, reason } : { state } } };
+        }
+        case 'frame.error': {
+            const body = strictRecord(payload, ['code']);
+            const code = SIM_FRAME_ERRORS.find((item) => item === body?.code);
+            return code ? { ok: true, message: { type, payload: { code } } } : fail('invalid_payload');
+        }
+        case 'frame.navigate': {
+            const body = strictRecord(payload, ['requestId', 'target']);
+            const requestId = boundedString(body?.requestId, REQUEST_ID);
+            const target = SIM_NAVIGATE_TARGETS.find((item) => item === body?.target);
+            return requestId && target
+                ? { ok: true, message: { type, payload: { requestId, target } } }
+                : fail('invalid_payload');
+        }
+        case 'frame.character.save': {
+            const body = strictRecord(payload, ['requestId', 'character']);
+            const requestId = boundedString(body?.requestId, REQUEST_ID);
+            const character = parseSimCharacterValue(body?.character);
+            return requestId && character
+                ? { ok: true, message: { type, payload: { requestId, character } } }
+                : fail('invalid_payload');
+        }
+        default:
+            return fail('unknown_type');
+    }
+}
+/** Frame side: accept a message only from the embedding host window at its exact origin. */
+export function parseHostMessage(event, context) {
+    if (!BRIDGE_ID.test(context.bridgeId))
+        return fail('bridge_mismatch');
+    if (event.origin !== context.parentOrigin)
+        return fail('origin_refused');
+    if (event.source == null || event.source !== context.parentWindow)
+        return fail('source_mismatch');
+    const opened = envelope(event, context.bridgeId);
+    if (!opened.ok)
+        return opened;
+    const { type, payload } = opened.message;
+    switch (type) {
+        case 'host.dispose':
+            return strictRecord(payload, [])
+                ? { ok: true, message: { type, payload: {} } }
+                : fail('invalid_payload');
+        case 'host.launch': {
+            const body = strictRecord(payload, ['code', 'expiresAt', 'surface'], ['character']);
+            const code = boundedString(body?.code, LAUNCH_CODE);
+            const surface = SIM_SURFACES.find((item) => item === body?.surface);
+            const expiresAt = body?.expiresAt;
+            const character = body && 'character' in body ? parseSimCharacterValue(body.character) : undefined;
+            if (!body ||
+                !code ||
+                !surface ||
+                typeof expiresAt !== 'string' ||
+                Number.isNaN(Date.parse(expiresAt)) ||
+                character === null)
+                return fail('invalid_payload');
+            return {
+                ok: true,
+                message: {
+                    type,
+                    payload: { code, expiresAt, surface, ...(character ? { character } : {}) },
+                },
+            };
+        }
+        case 'host.character.save.result': {
+            const body = strictRecord(payload, ['requestId', 'saved'], ['reason']);
+            const requestId = boundedString(body?.requestId, REQUEST_ID);
+            if (!body || !requestId || typeof body.saved !== 'boolean')
+                return fail('invalid_payload');
+            const reason = SIM_SAVE_FAILURES.find((item) => item === body.reason);
+            // A failure names its reason; a success has none.
+            if (body.saved ? 'reason' in body : !reason)
+                return fail('invalid_payload');
+            return {
+                ok: true,
+                message: {
+                    type,
+                    payload: reason ? { requestId, saved: false, reason } : { requestId, saved: true },
+                },
+            };
+        }
+        default:
+            return fail('unknown_type');
+    }
+}
+/** A fresh per-mount nonce: 128 random bits as base64url. The host issues it; the frame echoes it. */
+export function createBridgeId(fill = (bytes) => crypto.getRandomValues(bytes)) {
+    const bytes = fill(new Uint8Array(16));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+function wrap(bridgeId, type, payload) {
+    if (!BRIDGE_ID.test(bridgeId))
+        throw new Error('Invalid Agent Sim bridge id');
+    return {
+        channel: SIM_BRIDGE_CHANNEL,
+        version: SIM_BRIDGE_VERSION,
+        bridgeId,
+        type,
+        payload,
+    };
+}
+export function frameEnvelope(bridgeId, message) {
+    return wrap(bridgeId, message.type, message.payload);
+}
+export function hostEnvelope(bridgeId, message) {
+    return wrap(bridgeId, message.type, message.payload);
+}
+/** Host to frame. The target origin must be allowlisted; `*` can never be used. */
+export function postToFrame(frameWindow, frameOrigin, origins, bridgeId, message) {
+    if (!origins.has(frameOrigin))
+        throw new Error('Refusing to post to an unlisted Agent Sim origin');
+    frameWindow.postMessage(hostEnvelope(bridgeId, message), frameOrigin);
+}
+/** Frame to host. The target is the exact embedding origin the frame was configured with. */
+export function postToHost(parentWindow, parentOrigin, bridgeId, message) {
+    if (parentOrigin === '*' || parentOrigin === 'null' || !parentOrigin.includes('://'))
+        throw new Error('Refusing to post to a non-exact Agent Sim host origin');
+    parentWindow.postMessage(frameEnvelope(bridgeId, message), parentOrigin);
+}

package/dist/sim-bridge/origin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Exact-origin allowlist for the hosted Agent Sim frame.
+ *
+ * An origin is allowed only by an exact string match against a canonical `scheme://host[:port]`.
+ * There are no wildcards, no suffix or subdomain matching, and `null`/opaque origins never match.
+ * Loopback `http:` origins are accepted only when the caller opts in explicitly for local
+ * development. Being on the allowlist (loopback included) says where a frame was served from; it
+ * never proves an official desktop identity or an entitlement.
+ */
+export type OriginAllowlist = Readonly<{
+    /** Canonical origins in the order given. */
+    origins: readonly string[];
+    has(origin: unknown): boolean;
+}>;
+/** The canonical origin when `value` is exactly one, otherwise null. */
+export declare function canonicalBridgeOrigin(value: unknown, options?: Readonly<{
+    allowLoopbackHttp?: boolean;
+}>): string | null;
+export declare function createOriginAllowlist(origins: readonly unknown[], options?: Readonly<{
+    allowLoopbackHttp?: boolean;
+}>): OriginAllowlist;