@adea-ai/spatial 0.93.0 → 0.95.0

package/src/sim-bridge/launch.ts

@@ -0,0 +1,227 @@
+import { boundedString, isoInstant, ownDataValue, strictRecord } from './record'
+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 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'] as const
+export type SimSurface = (typeof SIM_SURFACES)[number]
+export const SIM_PLATFORMS = ['desktop', 'web'] as const
+export type SimPlatform = (typeof SIM_PLATFORMS)[number]
+
+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}$/
+
+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' }>
+
+const DENIED_REASONS = ['unauthenticated', 'not_entitled'] as const
+const UNAVAILABLE_REASONS = ['not_configured', 'service_unavailable'] as const
+const REJECTED_REASONS = ['code_expired', 'code_used', 'not_entitled', 'origin_refused'] as const
+
+export function parseSimLaunchRequest(value: unknown): SimLaunchRequest | null {
+  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 }
+}
+
+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 function parseSimLaunchGrant(
+  value: unknown,
+  expected: SimGrantExpectation
+): SimLaunchGrant | null {
+  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 as string, surface, frameOrigin }
+}
+
+export function parseSimSessionExchangeRequest(value: unknown): SimSessionExchangeRequest | null {
+  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: unknown): SimSessionExchangeResult | null {
+  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 as string }
+    : 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 function createLaunchOnce(): Readonly<{
+  take(payload: SimLaunchPayload, now: number): SimLaunchPayload | null
+}> {
+  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
+    },
+  }
+}
+
+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 function createLaunchCodeLedger(): Readonly<{
+  issue(code: string, binding: LaunchCodeBinding, expiresAt: number): void
+  redeem(
+    code: string,
+    presented: Omit<LaunchCodeBinding, 'surface'>,
+    now: number
+  ): LaunchCodeRedemption
+}> {
+  const entries = new Map<
+    string,
+    { binding: LaunchCodeBinding; expiresAt: number; spent: boolean }
+  >()
+  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/src/sim-bridge/messages.ts

@@ -0,0 +1,282 @@
+import { boundedString, isPlainRecord, strictRecord } from './record'
+import type { OriginAllowlist } from './origin'
+import { SIM_SURFACES, type SimSurface } from './launch'
+import { SIM_UNAVAILABLE_REASONS, 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 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 CHARACTER_ID = /^[A-Za-z0-9_.:-]{1,64}$/
+
+export const SIM_FRAME_STATES = ['loading', 'running', 'unavailable', 'offline'] as const
+export type SimFrameState = (typeof SIM_FRAME_STATES)[number]
+export const SIM_FRAME_ERRORS = [
+  'launch_rejected',
+  'asset_unavailable',
+  'engine_failed',
+  'bridge_incompatible',
+] as const
+export type SimFrameError = (typeof SIM_FRAME_ERRORS)[number]
+
+export type SimFrameMessage =
+  | 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 }> }>
+
+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>> }>
+
+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 }>
+
+const ENVELOPE_KEYS = ['channel', 'version', 'bridgeId', 'type', 'payload'] as const
+
+function envelope(
+  event: SimMessageEventLike,
+  bridgeId: string
+): SimBridgeResult<{ type: string; payload: unknown }> {
+  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: unknown): boolean {
+  let budget = MAX_SIM_MESSAGE_BYTES
+  let nodes = 0
+  const stack: { item: unknown; depth: number }[] = [{ 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<T>(reason: SimBridgeFailure): SimBridgeResult<T> {
+  return { ok: false, reason }
+}
+
+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 function parseFrameMessage(
+  event: SimMessageEventLike,
+  context: SimHostContext
+): SimBridgeResult<SimFrameMessage> {
+  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')
+    }
+    default:
+      return fail('unknown_type')
+  }
+}
+
+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 function parseHostMessage(
+  event: SimMessageEventLike,
+  context: SimFrameContext
+): SimBridgeResult<SimHostMessage> {
+  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 ? boundedString(body.character, CHARACTER_ID) : 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 } : {}) },
+        },
+      }
+    }
+    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: Uint8Array) => Uint8Array = (bytes) => crypto.getRandomValues(bytes)
+): string {
+  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: string, type: string, payload: object) {
+  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,
+  } as const
+}
+
+export function frameEnvelope(bridgeId: string, message: SimFrameMessage) {
+  return wrap(bridgeId, message.type, message.payload)
+}
+
+export function hostEnvelope(bridgeId: string, message: SimHostMessage) {
+  return wrap(bridgeId, message.type, message.payload)
+}
+
+type PostTarget = Readonly<{ postMessage(message: unknown, targetOrigin: string): void }>
+
+/** Host to frame. The target origin must be allowlisted; `*` can never be used. */
+export function postToFrame(
+  frameWindow: PostTarget,
+  frameOrigin: string,
+  origins: OriginAllowlist,
+  bridgeId: string,
+  message: SimHostMessage
+): void {
+  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: PostTarget,
+  parentOrigin: string,
+  bridgeId: string,
+  message: SimFrameMessage
+): void {
+  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/src/sim-bridge/origin.ts

@@ -0,0 +1,61 @@
+/**
+ * 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
+}>
+
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]']
+
+/** The canonical origin when `value` is exactly one, otherwise null. */
+export function canonicalBridgeOrigin(
+  value: unknown,
+  options: Readonly<{ allowLoopbackHttp?: boolean }> = {}
+): string | null {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 256) return null
+  let url: 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: readonly unknown[],
+  options: Readonly<{ allowLoopbackHttp?: boolean }> = {}
+): OriginAllowlist {
+  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: unknown) => typeof origin === 'string' && unique.includes(origin),
+  })
+}

package/src/sim-bridge/record.ts

@@ -0,0 +1,60 @@
+/** Strict structural readers shared by the bridge validators. No coercion, no extra keys. */
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  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: object): boolean {
+  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: unknown,
+  required: readonly string[],
+  optional: readonly string[] = []
+): Record<string, unknown> | null {
+  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: unknown, key: string): unknown {
+  if (!isPlainRecord(value)) return undefined
+  const descriptor = Object.getOwnPropertyDescriptor(value, key)
+  return descriptor && 'value' in descriptor ? descriptor.value : undefined
+}
+
+export function boundedString(value: unknown, pattern: RegExp): string | null {
+  return typeof value === 'string' && pattern.test(value) ? value : null
+}
+
+/** An ISO-8601 UTC instant as produced by `Date.prototype.toISOString`. */
+export function isoInstant(value: unknown): number | null {
+  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
+}