@adea-ai/spatial 0.93.0 → 0.95.0

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.93.0",
+  "version": "0.95.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": {

package/src/sim-bridge/availability.ts

@@ -0,0 +1,234 @@
+import type { SimFrameMessage } from './messages'
+import type { SimLaunchGrant } from './launch'
+
+/**
+ * What the host knows about a hosted Agent Sim launch, as a pure state machine. The host shows only
+ * what this state says: nothing is "running" until the frame reports it, and every failure names a
+ * cause. Chat and Dev never read this state, so a failed or offline sim cannot affect them.
+ */
+
+export const SIM_UNAVAILABLE_REASONS = [
+  'unauthenticated',
+  'not_entitled',
+  'not_configured',
+  'service_unavailable',
+  'origin_refused',
+  'bridge_incompatible',
+  'launch_rejected',
+  'engine_failed',
+  'frame_timeout',
+] as const
+export type SimUnavailableReason = (typeof SIM_UNAVAILABLE_REASONS)[number]
+
+type GrantedLaunch = Extract<SimLaunchGrant, { status: 'granted' }>
+
+/**
+ * Every state carries the `attempt` it belongs to. `start` begins attempt N+1, and every event
+ * that answers a specific attempt (`grant`, `frame`, `timeout`) names the attempt it was issued
+ * for. An event for any other attempt is dropped, so a late grant, frame message or timer from an
+ * abandoned attempt can never launch, fail or close a newer one. Callers also mint a fresh
+ * `bridgeId` per attempt, which stops a stale frame at the message layer as well.
+ */
+export type SimLaunchState =
+  | Readonly<{ phase: 'idle'; attempt: number }>
+  | Readonly<{ phase: 'requesting'; attempt: number }>
+  | Readonly<{ phase: 'awaiting_frame'; attempt: number; grant: GrantedLaunch }>
+  | Readonly<{ phase: 'launching'; attempt: number }>
+  | Readonly<{ phase: 'running'; attempt: number }>
+  | Readonly<{ phase: 'unavailable'; attempt: number; reason: SimUnavailableReason }>
+  | Readonly<{ phase: 'offline'; attempt: number }>
+
+export type SimLaunchEvent =
+  /**
+   * Begins a new attempt. `online: false` means the host already knows it is offline: the attempt
+   * is recorded as `offline` and no grant is requested, so a surface that mounts offline shows the
+   * offline state (with its retry) instead of staying idle, and the backend is never asked.
+   */
+  | Readonly<{ type: 'start'; online?: boolean }>
+  /** The backend's parsed reply for `attempt`; `null` is a reply that failed validation. */
+  | Readonly<{ type: 'grant'; attempt: number; grant: SimLaunchGrant | null }>
+  | Readonly<{ type: 'frame'; attempt: number; message: SimFrameMessage; now: number }>
+  | Readonly<{ type: 'timeout'; attempt: number }>
+  | Readonly<{ type: 'offline' }>
+  | Readonly<{ type: 'dispose' }>
+
+export type SimLaunchEffect =
+  | Readonly<{ type: 'request_grant'; attempt: number }>
+  | Readonly<{ type: 'post_launch'; attempt: number; grant: GrantedLaunch }>
+  | Readonly<{ type: 'dispose_frame'; attempt: number }>
+
+export type SimLaunchStep = Readonly<{ state: SimLaunchState; effect?: SimLaunchEffect }>
+
+const FRAME_ERROR_REASONS = {
+  launch_rejected: 'launch_rejected',
+  asset_unavailable: 'service_unavailable',
+  engine_failed: 'engine_failed',
+  bridge_incompatible: 'bridge_incompatible',
+} as const
+
+export const SIM_IDLE: SimLaunchState = { phase: 'idle', attempt: 0 }
+
+function stay(state: SimLaunchState): SimLaunchStep {
+  return { state }
+}
+
+function unavailable(attempt: number, reason: SimUnavailableReason): SimLaunchStep {
+  return { state: { phase: 'unavailable', attempt, reason } }
+}
+
+function reduceFrame(state: SimLaunchState, message: SimFrameMessage, now: number): SimLaunchStep {
+  const { attempt } = state
+  switch (message.type) {
+    case 'frame.ready': {
+      // Only the first ready of an awaited frame launches; a replay changes nothing.
+      if (state.phase !== 'awaiting_frame') return stay(state)
+      if (Date.parse(state.grant.expiresAt) <= now) return unavailable(attempt, 'frame_timeout')
+      return {
+        state: { phase: 'launching', attempt },
+        effect: { type: 'post_launch', attempt, grant: state.grant },
+      }
+    }
+    case 'frame.state': {
+      if (state.phase !== 'launching' && state.phase !== 'running') return stay(state)
+      const { state: reported, reason } = message.payload
+      if (reported === 'running') return stay({ phase: 'running', attempt })
+      if (reported === 'offline') return stay({ phase: 'offline', attempt })
+      if (reported === 'unavailable') return unavailable(attempt, reason ?? 'service_unavailable')
+      return stay(state)
+    }
+    case 'frame.error':
+      // A frame that fails before it ever reports ready (an engine that cannot start, a bridge
+      // version the host does not speak) is a failure of this attempt, not noise.
+      if (
+        state.phase !== 'awaiting_frame' &&
+        state.phase !== 'launching' &&
+        state.phase !== 'running'
+      )
+        return stay(state)
+      return unavailable(attempt, FRAME_ERROR_REASONS[message.payload.code])
+    case 'frame.close':
+      return state.phase === 'idle' ? stay(state) : stay({ phase: 'idle', attempt })
+  }
+}
+
+export function reduceSimLaunch(state: SimLaunchState, event: SimLaunchEvent): SimLaunchStep {
+  const { attempt } = state
+  switch (event.type) {
+    case 'start': {
+      if (state.phase !== 'idle' && state.phase !== 'unavailable' && state.phase !== 'offline')
+        return stay(state)
+      const next = attempt + 1
+      if (event.online === false) return stay({ phase: 'offline', attempt: next })
+      return {
+        state: { phase: 'requesting', attempt: next },
+        effect: { type: 'request_grant', attempt: next },
+      }
+    }
+    case 'grant': {
+      if (event.attempt !== attempt || state.phase !== 'requesting') return stay(state)
+      const { grant } = event
+      if (!grant) return unavailable(attempt, 'service_unavailable')
+      if (grant.status === 'granted') return stay({ phase: 'awaiting_frame', attempt, grant })
+      return unavailable(attempt, grant.reason)
+    }
+    case 'frame':
+      return event.attempt === attempt ? reduceFrame(state, event.message, event.now) : stay(state)
+    case 'timeout':
+      return event.attempt === attempt &&
+        (state.phase === 'awaiting_frame' || state.phase === 'launching')
+        ? unavailable(attempt, 'frame_timeout')
+        : stay(state)
+    case 'offline':
+      return state.phase === 'idle' ? stay(state) : stay({ phase: 'offline', attempt })
+    case 'dispose':
+      return state.phase === 'idle'
+        ? stay(state)
+        : { state: { phase: 'idle', attempt }, effect: { type: 'dispose_frame', attempt } }
+  }
+}
+
+export type SimAvailabilityNotice = Readonly<{
+  tone: 'neutral' | 'error'
+  title: string
+  detail: string
+  /** Whether trying again can help without the user changing anything else. */
+  retryable: boolean
+}>
+
+const REASON_COPY: Record<SimUnavailableReason, Omit<SimAvailabilityNotice, 'tone'>> = {
+  unauthenticated: {
+    title: 'Sign in to open Agent Sim',
+    detail: 'Agent Sim needs your Adea account.',
+    retryable: false,
+  },
+  not_entitled: {
+    title: 'Agent Sim is not included in this account',
+    detail: 'Your account does not include Agent Sim.',
+    retryable: false,
+  },
+  not_configured: {
+    title: 'Agent Sim is not set up here',
+    detail: 'This deployment has no Agent Sim service configured.',
+    retryable: false,
+  },
+  service_unavailable: {
+    title: 'Agent Sim is unavailable right now',
+    detail: 'The Agent Sim service did not respond.',
+    retryable: true,
+  },
+  origin_refused: {
+    title: 'Agent Sim was blocked',
+    detail: 'The Agent Sim frame did not come from an allowed address.',
+    retryable: false,
+  },
+  bridge_incompatible: {
+    title: 'Agent Sim needs an update',
+    detail: 'This version of Adea and Agent Sim cannot talk to each other.',
+    retryable: false,
+  },
+  launch_rejected: {
+    title: 'Agent Sim could not start',
+    detail: 'The launch was refused or had already expired.',
+    retryable: true,
+  },
+  engine_failed: {
+    title: 'Agent Sim stopped working',
+    detail: 'The simulation hit an error.',
+    retryable: true,
+  },
+  frame_timeout: {
+    title: 'Agent Sim took too long to start',
+    detail: 'It did not finish loading in time.',
+    retryable: true,
+  },
+}
+
+const INDEPENDENCE = ' Chat and Dev are not affected.'
+
+/** Truthful copy for a state, or null when the surface has nothing to say (idle, loading, running). */
+export function describeSimAvailability(state: SimLaunchState): SimAvailabilityNotice | null {
+  switch (state.phase) {
+    case 'offline':
+      return {
+        tone: 'error',
+        title: 'Agent Sim is offline',
+        detail: `You are offline, so Agent Sim cannot load.${INDEPENDENCE}`,
+        retryable: true,
+      }
+    case 'unavailable': {
+      const copy = REASON_COPY[state.reason]
+      return { tone: 'error', ...copy, detail: `${copy.detail}${INDEPENDENCE}` }
+    }
+    case 'requesting':
+    case 'awaiting_frame':
+    case 'launching':
+      return {
+        tone: 'neutral',
+        title: 'Opening Agent Sim',
+        detail: 'Checking your account and loading the simulation.',
+        retryable: false,
+      }
+    default:
+      return null
+  }
+}

package/src/sim-bridge/cookie.ts

@@ -0,0 +1,82 @@
+/**
+ * The sim-only session cookie set by the Agent Sim origin after a successful code exchange.
+ *
+ * It is `__Host-` prefixed (Secure, Path=/, no Domain), HttpOnly so no script on either origin can
+ * read it, and `SameSite=None; Partitioned` because the sim is embedded as a third-party frame: the
+ * browser keys it to the embedding Adea site and never sends it in any other context. It
+ * authorizes the sim origin's assets only; it is not an Adea account session and never appears in a
+ * response body or a bridge message.
+ */
+
+export const SIM_SESSION_COOKIE_NAME = '__Host-adea-sim'
+export const MAX_SIM_SESSION_SECONDS = 3600
+
+const SESSION_VALUE = /^[A-Za-z0-9_-]{32,256}$/
+
+export function buildSimSessionSetCookie(value: string, maxAgeSeconds: number): string {
+  if (!SESSION_VALUE.test(value)) throw new Error('Invalid Agent Sim session value')
+  return setCookie(value, boundedMaxAge(maxAgeSeconds))
+}
+
+/** Expires the session on the client. */
+export function buildSimSessionClearCookie(): string {
+  return setCookie('', 0)
+}
+
+function boundedMaxAge(seconds: number): number {
+  if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_SIM_SESSION_SECONDS)
+    throw new Error('Agent Sim session lifetime out of range')
+  return seconds
+}
+
+function setCookie(value: string, maxAge: number): string {
+  return [
+    `${SIM_SESSION_COOKIE_NAME}=${value}`,
+    `Max-Age=${maxAge}`,
+    'Path=/',
+    'Secure',
+    'HttpOnly',
+    'SameSite=None',
+    'Partitioned',
+  ].join('; ')
+}
+
+/** Every way a `Set-Cookie` header departs from the contract; empty means it conforms. */
+export function simSessionCookieViolations(header: string): readonly string[] {
+  const [pair = '', ...attributes] = header.split(';').map((part) => part.trim())
+  const violations: string[] = []
+  if (!pair.startsWith(`${SIM_SESSION_COOKIE_NAME}=`)) violations.push('name')
+  const names = new Map<string, string>()
+  for (const attribute of attributes) {
+    const index = attribute.indexOf('=')
+    const key = (index === -1 ? attribute : attribute.slice(0, index)).toLowerCase()
+    if (names.has(key)) violations.push(`duplicate:${key}`)
+    names.set(key, index === -1 ? '' : attribute.slice(index + 1))
+  }
+  if (!names.has('secure')) violations.push('secure')
+  if (!names.has('httponly')) violations.push('httponly')
+  if (!names.has('partitioned')) violations.push('partitioned')
+  if (names.get('path') !== '/') violations.push('path')
+  if (names.has('domain')) violations.push('domain')
+  if (names.get('samesite')?.toLowerCase() !== 'none') violations.push('samesite')
+  const maxAge = names.get('max-age')
+  if (maxAge === undefined || !/^\d+$/.test(maxAge) || Number(maxAge) > MAX_SIM_SESSION_SECONDS)
+    violations.push('max-age')
+  if (names.has('expires')) violations.push('expires')
+  return violations
+}
+
+/**
+ * The session value from a request's `Cookie` header, or null unless exactly one sim cookie of
+ * the right shape is present (a duplicate is refused rather than guessed between).
+ */
+export function readSimSessionCookie(cookieHeader: string | null | undefined): string | null {
+  if (!cookieHeader) return null
+  const values = cookieHeader
+    .split(';')
+    .map((part) => part.trim())
+    .filter((part) => part.startsWith(`${SIM_SESSION_COOKIE_NAME}=`))
+    .map((part) => part.slice(SIM_SESSION_COOKIE_NAME.length + 1))
+  const [only] = values
+  return values.length === 1 && only !== undefined && SESSION_VALUE.test(only) ? only : null
+}

package/src/sim-bridge/index.ts

@@ -0,0 +1,6 @@
+export * from './availability'
+export * from './cookie'
+export * from './launch'
+export * from './messages'
+export * from './origin'
+export * from './service'