@adea-ai/spatial 0.94.0 → 0.96.0

package/src/sim-bridge/messages.ts

@@ -0,0 +1,338 @@
+import { boundedString, isPlainRecord, strictRecord } from './record'
+import type { OriginAllowlist } from './origin'
+import { SIM_SURFACES, type SimSurface } from './launch'
+import { parseSimCharacterValue } from './character'
+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 REQUEST_ID = /^[A-Za-z0-9_-]{1,32}$/
+
+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]
+
+/** Where HQ may send the host: the designers only. A designer returns with `frame.close`. */
+export const SIM_NAVIGATE_TARGETS = ['room-designer', 'character-designer'] as const
+export type SimNavigateTarget = (typeof SIM_NAVIGATE_TARGETS)[number]
+export const SIM_SAVE_FAILURES = ['refused', 'failed', 'timeout'] as const
+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 }>
+
+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')
+    }
+    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')
+  }
+}
+
+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 ? 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: 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
+}

package/src/sim-bridge/save-client.ts

@@ -0,0 +1,87 @@
+import { parseSimCharacterValue } from './character'
+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 const DEFAULT_SAVE_CLIENT_TIMEOUT_MS = 8_000
+
+export function createCharacterSaveClient(
+  options: CharacterSaveClientOptions
+): CharacterSaveClient {
+  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: { requestId: string; settle(saved: boolean): void } | null = 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<boolean>((resolve) => {
+        const cancel = schedule(() => failOpen(), timeoutMs)
+        const entry = {
+          requestId,
+          settle(saved: boolean) {
+            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()
+    },
+  }
+}