@adea-ai/spatial 0.94.0 → 0.96.0

package/dist/sim-bridge/origin.js

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+/** The canonical origin when `value` is exactly one, otherwise null. */
+export function canonicalBridgeOrigin(value, options = {}) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 256)
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    // `origin` is "null" for opaque schemes; requiring equality also rejects paths, queries,
+    // credentials, trailing slashes and non-canonical spellings.
+    if (url.origin !== value)
+        return null;
+    // The URL parser tolerates `*` and similar in a host; an allowlist entry must be a real host.
+    if (!/^(?:[a-z0-9-]+(?:\.[a-z0-9-]+)*|\[[0-9a-f:]+\])$/.test(url.hostname))
+        return null;
+    if (url.protocol === 'https:')
+        return value;
+    if (url.protocol === 'http:' &&
+        options.allowLoopbackHttp === true &&
+        LOOPBACK_HOSTS.includes(url.hostname))
+        return value;
+    return null;
+}
+export function createOriginAllowlist(origins, options = {}) {
+    if (origins.length === 0)
+        throw new Error('The Agent Sim bridge needs at least one origin');
+    const canonical = origins.map((origin) => {
+        const value = canonicalBridgeOrigin(origin, options);
+        if (value === null)
+            throw new Error('Agent Sim bridge origins must be exact canonical origins');
+        return value;
+    });
+    const unique = [...new Set(canonical)];
+    return Object.freeze({
+        origins: Object.freeze(unique),
+        has: (origin) => typeof origin === 'string' && unique.includes(origin),
+    });
+}

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

@@ -0,0 +1,16 @@
+/** Strict structural readers shared by the bridge validators. No coercion, no extra keys. */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * The record when it is plain and carries exactly the allowed keys: every `required` key is
+ * present and no key outside `required` and `optional` exists. Accessor properties are refused so
+ * a getter can never run during validation.
+ */
+export declare function strictRecord(value: unknown, required: readonly string[], optional?: readonly string[]): Record<string, unknown> | null;
+/**
+ * An own data property of a plain record, or undefined. Used to branch on a discriminant before
+ * the strict reader runs, without ever invoking a getter or walking the prototype chain.
+ */
+export declare function ownDataValue(value: unknown, key: string): unknown;
+export declare function boundedString(value: unknown, pattern: RegExp): string | null;
+/** An ISO-8601 UTC instant as produced by `Date.prototype.toISOString`. */
+export declare function isoInstant(value: unknown): number | null;

package/dist/sim-bridge/record.js

@@ -0,0 +1,56 @@
+/** Strict structural readers shared by the bridge validators. No coercion, no extra keys. */
+export function isPlainRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return (prototype === Object.prototype || prototype === null) && !hasSymbolKeys(value);
+}
+function hasSymbolKeys(value) {
+    return Object.getOwnPropertySymbols(value).length > 0;
+}
+/**
+ * The record when it is plain and carries exactly the allowed keys: every `required` key is
+ * present and no key outside `required` and `optional` exists. Accessor properties are refused so
+ * a getter can never run during validation.
+ */
+export function strictRecord(value, required, optional = []) {
+    if (!isPlainRecord(value))
+        return null;
+    // Refuse a wide object before allocating a descriptor for each of its keys.
+    if (Object.getOwnPropertyNames(value).length > required.length + optional.length)
+        return null;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Object.keys(descriptors);
+    for (const key of keys) {
+        const descriptor = descriptors[key];
+        if (!('value' in descriptor))
+            return null;
+        if (!required.includes(key) && !optional.includes(key))
+            return null;
+    }
+    for (const key of required)
+        if (!keys.includes(key))
+            return null;
+    return value;
+}
+/**
+ * An own data property of a plain record, or undefined. Used to branch on a discriminant before
+ * the strict reader runs, without ever invoking a getter or walking the prototype chain.
+ */
+export function ownDataValue(value, key) {
+    if (!isPlainRecord(value))
+        return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor && 'value' in descriptor ? descriptor.value : undefined;
+}
+export function boundedString(value, pattern) {
+    return typeof value === 'string' && pattern.test(value) ? value : null;
+}
+/** An ISO-8601 UTC instant as produced by `Date.prototype.toISOString`. */
+export function isoInstant(value) {
+    if (typeof value !== 'string' ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/.test(value))
+        return null;
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? time : null;
+}

package/dist/sim-bridge/save-client.d.ts

@@ -0,0 +1,25 @@
+import type { SimFrameRequestMessage, SimHostMessage } from './messages';
+/**
+ * Frame side of the acknowledged character save.
+ *
+ * `save` resolves `true` only when the host answers the very request it sent with
+ * `saved: true`. A refusal, a failure, a timeout, a host dispose, `dispose()`, a second save while
+ * one is open, an invalid value, a post that throws, and a late or mismatched answer all resolve
+ * `false`, so the engine never shows a saved value the host did not commit.
+ */
+export type CharacterSaveClient = Readonly<{
+    save(character: string): Promise<boolean>;
+    /** Feed every parsed host message in; unrelated ones are ignored. */
+    receive(message: SimHostMessage): void;
+    /** Fails any open save. Call when the frame is torn down. */
+    dispose(): void;
+}>;
+export type CharacterSaveClientOptions = Readonly<{
+    post(message: SimFrameRequestMessage): void;
+    /** Longer than the host's own timeout so the host's answer normally arrives first. */
+    timeoutMs?: number;
+    mintRequestId?: () => string;
+    schedule?: (run: () => void, ms: number) => () => void;
+}>;
+export declare const DEFAULT_SAVE_CLIENT_TIMEOUT_MS = 8000;
+export declare function createCharacterSaveClient(options: CharacterSaveClientOptions): CharacterSaveClient;

package/dist/sim-bridge/save-client.js

@@ -0,0 +1,55 @@
+import { parseSimCharacterValue } from './character';
+export const DEFAULT_SAVE_CLIENT_TIMEOUT_MS = 8_000;
+export function createCharacterSaveClient(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SAVE_CLIENT_TIMEOUT_MS;
+    const schedule = options.schedule ??
+        ((run, ms) => {
+            const id = setTimeout(run, ms);
+            return () => clearTimeout(id);
+        });
+    let counter = 0;
+    const mint = options.mintRequestId ?? (() => `save${++counter}`);
+    let open = null;
+    let disposed = false;
+    function failOpen() {
+        open?.settle(false);
+    }
+    return {
+        save(character) {
+            if (disposed || open || parseSimCharacterValue(character) === null)
+                return Promise.resolve(false);
+            const requestId = mint();
+            return new Promise((resolve) => {
+                const cancel = schedule(() => failOpen(), timeoutMs);
+                const entry = {
+                    requestId,
+                    settle(saved) {
+                        if (open !== entry)
+                            return;
+                        open = null;
+                        cancel();
+                        resolve(saved);
+                    },
+                };
+                open = entry;
+                try {
+                    options.post({ type: 'frame.character.save', payload: { requestId, character } });
+                }
+                catch {
+                    entry.settle(false);
+                }
+            });
+        },
+        receive(message) {
+            if (message.type === 'host.dispose')
+                failOpen();
+            else if (message.type === 'host.character.save.result' &&
+                open?.requestId === message.payload.requestId)
+                open.settle(message.payload.saved);
+        },
+        dispose() {
+            disposed = true;
+            failOpen();
+        },
+    };
+}

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

@@ -0,0 +1,85 @@
+import { type LaunchCodeBinding, type LaunchCodeRedemption, type SimLaunchGrant, type SimPlatform, type SimSessionExchangeResult, type SimSurface } from './launch';
+/**
+ * Backend logic for the hosted Agent Sim launch, written against injectable ports.
+ *
+ * Nothing here picks an entitlement source, a sim origin or a storage engine: the caller supplies
+ * each as a port or a config value, and an absent value fails closed as `not_configured`. The
+ * module does no I/O, owns no endpoint and is not imported by the app. A real deployment adds the
+ * HTTP routes, the durable stores and the entitlement lookup around it.
+ *
+ * Two entry points mirror the two steps of the launch contract in `launch.ts`:
+ *
+ * - `createSimLaunchIssuer` (Adea backend): checks the signed-in account's entitlement and issues a
+ *   single-use code bound to the host's `bridgeId`, the sim origin and the surface.
+ * - `createSimSessionExchange` (sim origin): redeems that code once and mints a sim-only session
+ *   whose value travels only in the `Set-Cookie` header, never in a body.
+ */
+type MaybePromise<T> = T | Promise<T>;
+export type SimEntitlementQuery = Readonly<{
+    workspaceId: string;
+    surface: SimSurface;
+    /**
+     * The platform the client says it is. It is a hint for the entitlement source and never proof
+     * of anything: localhost, an embedded secret or a desktop shell's claim cannot entitle a launch.
+     */
+    platform: SimPlatform;
+}>;
+export type SimEntitlementVerdict = 'entitled' | 'not_entitled' | 'unauthenticated' | 'unavailable';
+/**
+ * Decides whether the account behind the current request may launch. The port is bound to that
+ * request's authenticated session by whoever builds it, so no account identity passes through the
+ * launch request body.
+ */
+export type SimEntitlementChecker = (query: SimEntitlementQuery) => MaybePromise<SimEntitlementVerdict>;
+/** Durable single-use code storage. `createLaunchCodeLedger()` is the in-memory reference. */
+export type SimLaunchCodeStore = Readonly<{
+    issue(code: string, binding: LaunchCodeBinding, expiresAt: number): MaybePromise<void>;
+    redeem(code: string, presented: Omit<LaunchCodeBinding, 'surface'>, now: number): MaybePromise<LaunchCodeRedemption>;
+}>;
+export type SimSessionRecord = Readonly<{
+    surface: SimSurface;
+    expiresAt: number;
+}>;
+/** Where the sim origin keeps the sessions it mints; looked up later by the asset gate. */
+export type SimSessionStore = Readonly<{
+    save(value: string, record: SimSessionRecord): MaybePromise<void>;
+}>;
+type Clock = () => number;
+type RandomBytes = (length: number) => Uint8Array;
+export type SimLaunchIssuerConfig = Readonly<{
+    /** The sim origin to embed. Absent or invalid means "not configured", never a default. */
+    frameOrigin: string | null | undefined;
+    allowLoopbackHttp?: boolean;
+    entitlement: SimEntitlementChecker;
+    store: SimLaunchCodeStore;
+    /** Code lifetime in milliseconds, clamped to the contract maximum. */
+    codeTtlMs?: number;
+    now?: Clock;
+    randomBytes?: RandomBytes;
+}>;
+export type SimLaunchIssueResult = SimLaunchGrant | Readonly<{
+    status: 'invalid_request';
+}>;
+/** The backend half of the launch: a request body in, a grant (or a refusal) out. */
+export declare function createSimLaunchIssuer(config: SimLaunchIssuerConfig): (body: unknown) => Promise<SimLaunchIssueResult>;
+export type SimSessionExchangeConfig = Readonly<{
+    /** This sim origin, as the issuer bound it into the code. Absent or invalid is "not configured". */
+    origin: string | null | undefined;
+    allowLoopbackHttp?: boolean;
+    store: SimLaunchCodeStore;
+    sessions: SimSessionStore;
+    /** Session lifetime in seconds, clamped to the contract maximum. */
+    sessionSeconds?: number;
+    now?: Clock;
+    randomBytes?: RandomBytes;
+}>;
+/** What the sim origin answers: a JSON body, plus the cookie header only for a new session. */
+export type SimSessionExchangeResponse = Readonly<{
+    body: SimSessionExchangeResult | Readonly<{
+        status: 'invalid_request';
+    }>;
+    setCookie?: string;
+}>;
+/** The sim origin's half of the launch: redeems a code once and sets the sim-only cookie. */
+export declare function createSimSessionExchange(config: SimSessionExchangeConfig): (body: unknown) => Promise<SimSessionExchangeResponse>;
+export {};

package/dist/sim-bridge/service.js

@@ -0,0 +1,166 @@
+import { createOriginAllowlist } from './origin';
+import { MAX_SIM_LAUNCH_TTL_MS, parseSimLaunchRequest, parseSimSessionExchangeRequest, } from './launch';
+import { MAX_SIM_SESSION_SECONDS, buildSimSessionSetCookie } from './cookie';
+const systemClock = () => Date.now();
+const systemRandom = (length) => crypto.getRandomValues(new Uint8Array(length));
+const DEFAULT_LAUNCH_TTL_MS = 60_000;
+const DEFAULT_SESSION_SECONDS = MAX_SIM_SESSION_SECONDS;
+const CODE_BYTES = 32;
+const SESSION_BYTES = 32;
+/** The backend half of the launch: a request body in, a grant (or a refusal) out. */
+export function createSimLaunchIssuer(config) {
+    const frameOrigin = configuredOrigin(config.frameOrigin, config.allowLoopbackHttp === true);
+    const now = config.now ?? systemClock;
+    const random = config.randomBytes ?? systemRandom;
+    const ttl = clampedLifetime(config.codeTtlMs, DEFAULT_LAUNCH_TTL_MS, MAX_SIM_LAUNCH_TTL_MS);
+    return async (body) => {
+        const request = parseSimLaunchRequest(body);
+        if (!request)
+            return { status: 'invalid_request' };
+        // A lifetime that is not a finite number is a misconfiguration, treated like a missing origin.
+        if (!frameOrigin || ttl === null)
+            return { status: 'unavailable', reason: 'not_configured' };
+        let verdict;
+        try {
+            verdict = await config.entitlement({
+                workspaceId: request.workspaceId,
+                surface: request.surface,
+                platform: request.platform,
+            });
+        }
+        catch {
+            return { status: 'unavailable', reason: 'service_unavailable' };
+        }
+        if (verdict === 'unauthenticated')
+            return { status: 'denied', reason: 'unauthenticated' };
+        if (verdict === 'not_entitled')
+            return { status: 'denied', reason: 'not_entitled' };
+        // Anything but an explicit "entitled" fails closed, including a verdict this code does not know.
+        if (verdict !== 'entitled')
+            return { status: 'unavailable', reason: 'service_unavailable' };
+        // Everything that can fail on bad injected input is computed before the store is touched, so a
+        // bad clock or random source leaves no stored code behind.
+        let code;
+        let expiresAt;
+        let expiresAtIso;
+        try {
+            code = base64url(random(CODE_BYTES));
+            expiresAt = readClock(now) + ttl;
+            expiresAtIso = isoInstant(expiresAt);
+        }
+        catch {
+            return { status: 'unavailable', reason: 'service_unavailable' };
+        }
+        if (!expiresAtIso)
+            return { status: 'unavailable', reason: 'service_unavailable' };
+        try {
+            await config.store.issue(code, { bridgeId: request.bridgeId, origin: frameOrigin, surface: request.surface }, expiresAt);
+        }
+        catch {
+            return { status: 'unavailable', reason: 'service_unavailable' };
+        }
+        return {
+            status: 'granted',
+            code,
+            expiresAt: expiresAtIso,
+            surface: request.surface,
+            frameOrigin,
+        };
+    };
+}
+/** The sim origin's half of the launch: redeems a code once and sets the sim-only cookie. */
+export function createSimSessionExchange(config) {
+    const origin = configuredOrigin(config.origin, config.allowLoopbackHttp === true);
+    const now = config.now ?? systemClock;
+    const random = config.randomBytes ?? systemRandom;
+    const seconds = clampedLifetime(config.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SIM_SESSION_SECONDS);
+    return async (body) => {
+        const request = parseSimSessionExchangeRequest(body);
+        if (!request)
+            return { body: { status: 'invalid_request' } };
+        if (!origin || seconds === null)
+            return { body: { status: 'unavailable' } };
+        // The session is fully prepared before the code is redeemed. Redeeming spends the code, so a
+        // bad clock or random source must fail here, where nothing has been consumed or stored.
+        let at;
+        let value;
+        let expiresAt;
+        let expiresAtIso;
+        let setCookie;
+        try {
+            at = readClock(now);
+            value = base64url(random(SESSION_BYTES));
+            expiresAt = at + seconds * 1000;
+            expiresAtIso = isoInstant(expiresAt);
+            setCookie = buildSimSessionSetCookie(value, seconds);
+        }
+        catch {
+            return { body: { status: 'unavailable' } };
+        }
+        if (!expiresAtIso)
+            return { body: { status: 'unavailable' } };
+        let redemption;
+        try {
+            redemption = await config.store.redeem(request.code, { bridgeId: request.bridgeId, origin }, at);
+        }
+        catch {
+            return { body: { status: 'unavailable' } };
+        }
+        if (!redemption.ok) {
+            // An unknown code carries no more information than an expired one; the reply never says
+            // whether a code ever existed.
+            const reason = redemption.reason === 'unknown' ? 'code_expired' : redemption.reason;
+            return { body: { status: 'rejected', reason } };
+        }
+        // The code is spent from here on: if saving fails the same code is not retryable, and the client
+        // starts a new launch.
+        try {
+            await config.sessions.save(value, { surface: redemption.surface, expiresAt });
+        }
+        catch {
+            return { body: { status: 'unavailable' } };
+        }
+        return { body: { status: 'session', expiresAt: expiresAtIso }, setCookie };
+    };
+}
+/**
+ * A configured lifetime in the unit the caller passes (milliseconds or seconds): the default when
+ * absent, clamped to [1, max] when a finite number, and null for anything else (NaN, Infinity, a
+ * non-number), which callers treat as a misconfiguration rather than guessing a value.
+ */
+function clampedLifetime(value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return null;
+    return Math.min(Math.max(1, Math.floor(value)), max);
+}
+/** One clock reading, which must be a finite number of milliseconds; anything else throws. */
+function readClock(now) {
+    const reading = now();
+    if (typeof reading !== 'number' || !Number.isFinite(reading)) {
+        throw new RangeError('clock returned a non-finite reading');
+    }
+    return reading;
+}
+/** The ISO string for an instant, or null when it is not a valid Date (NaN, beyond the Date range). */
+function isoInstant(ms) {
+    const date = new Date(ms);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function configuredOrigin(origin, allowLoopbackHttp) {
+    if (origin == null)
+        return null;
+    try {
+        return createOriginAllowlist([origin], { allowLoopbackHttp }).origins[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function base64url(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/spatial",
-  "version": "0.94.0",
+  "version": "0.96.0",
   "description": "Scene and asset manifest contracts plus the shell-to-engine spatial protocol for Adea workspaces: scene mount manifests, spawn URL helpers, and scene telemetry schemas. Pure types — no rendering, no binaries.",
   "keywords": [
     "assets",
@@ -32,6 +32,11 @@
       "types": "./dist/index.d.ts",
       "development": "./src/index.ts",
       "import": "./dist/index.js"
+    },
+    "./sim-bridge": {
+      "types": "./dist/sim-bridge/index.d.ts",
+      "development": "./src/sim-bridge/index.ts",
+      "import": "./dist/sim-bridge/index.js"
     }
   },
   "scripts": {
@@ -39,6 +44,6 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
     "test": "bun test test/*.test.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "bun check -p tsconfig.json"
   }
 }

package/src/index.ts

@@ -1,3 +1,5 @@
+import { isSerializedSimCharacter } from './sim-bridge/character'
+
 export * from './asset-manifests'
 export {
   agentSimEngineManifestUrl,
@@ -35,8 +37,11 @@ export const DEFAULT_CHARACTER_ID = configurableCharacterId
 /**
  * Shell-side character param check. The engine validates against its
  * reference/preset catalogs on mount; the shell only needs a plausible
- * non-empty value to thread through.
+ * non-empty value to thread through. A serialized customization
+ * (`character:v1:` and 13 slots, 157 characters by default) is checked by the
+ * bridge's structural parser instead of the short-id length rule.
  */
 export function isPlausibleCharacterId(value: string | undefined): value is string {
-  return typeof value === 'string' && value.length > 0 && value.length <= 128
+  if (typeof value !== 'string' || value.length === 0) return false
+  return value.length <= 128 || isSerializedSimCharacter(value)
 }