threadwire 0.1.6 → 0.1.8

package/src/isolated-state.js

@@ -0,0 +1,409 @@
+// @ts-nocheck
+/* eslint-disable jsdoc/require-jsdoc */
+
+import {createHmac, randomBytes, timingSafeEqual} from "node:crypto"
+import {constants} from "node:fs"
+import {chmod, lstat, mkdir, open, readFile, readdir, rename, unlink} from "node:fs/promises"
+import {dirname, join} from "node:path"
+
+const OWNER = "threadwire-isolated-runtime"
+
+/**
+ * Authenticated registry of both public session aliases and private volume
+ * ownership. Lineage ownership deliberately outlives an expired alias until
+ * Docker confirms that the volume was deleted.
+ * @param {{file: string, key: string, namespace: string, now?: () => number, random?: (size: number) => Buffer}} options
+ */
+export async function openStateRegistry(options) {
+  if (!/^\/.+/u.test(options.file) || options.key.length < 32 || !/^[A-Za-z0-9_.-]{1,64}$/u.test(options.namespace)) {
+    throw new Error("Invalid isolated state configuration")
+  }
+  const now = options.now ?? Date.now
+  const random = options.random ?? randomBytes
+  const durabilityObserver = options.durabilityObserver
+  await mkdir(dirname(options.file), {recursive: true, mode: 0o700})
+  await chmod(dirname(options.file), 0o700)
+  await requirePrivateDirectory(dirname(options.file))
+  const sessions = new Map()
+  const lineages = new Map()
+  const runs = new Map()
+  let serial = Promise.resolve()
+  try {
+    const document = JSON.parse(await readFile(options.file, "utf8"))
+    const payload = JSON.stringify(document.payload)
+    if (![1, 2, 3].includes(document.version) || typeof document.mac !== "string" || !equalMac(document.mac, mac(options.key, payload))) throw new Error()
+    if (!Array.isArray(document.payload?.sessions)) throw new Error()
+    for (const entry of document.payload.sessions) {
+      if (!validSession(entry)) throw new Error()
+      sessions.set(entry.sessionId, without(entry, "sessionId"))
+      lineages.set(entry.lineage, lineageFromSession(options.namespace, entry))
+    }
+    if (document.version === 2) {
+      if (!Array.isArray(document.payload.lineages)) throw new Error()
+      for (const entry of document.payload.lineages) {
+        if (!validLineage(entry, options.namespace)) throw new Error()
+        lineages.set(entry.lineage, entry)
+      }
+    }
+    if (document.version === 3) {
+      if (!Array.isArray(document.payload.lineages) || !Array.isArray(document.payload.runs)) throw new Error()
+      for (const entry of document.payload.lineages) {
+        if (!validLineage(entry, options.namespace)) throw new Error()
+        lineages.set(entry.lineage, entry)
+      }
+      for (const entry of document.payload.runs) {
+        canonicalRunIdentity(entry)
+        runs.set(entry.run, entry)
+      }
+    }
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== "ENOENT") throw new Error("Isolated state registry authentication failed", {cause: error})
+  }
+  await removeAuthenticatedTemps(dirname(options.file), options.key, options.namespace)
+
+  const persist = async (sessionState = sessions, lineageState = lineages, runState = runs, signal) => {
+    throwIfAborted(signal)
+    const payload = {
+      sessions: [...sessionState.entries()].map(([sessionId, entry]) => ({sessionId, ...entry})),
+      lineages: [...lineageState.values()],
+      runs: [...runState.values()]
+    }
+    const serializedPayload = JSON.stringify(payload)
+    const document = JSON.stringify({version: 3, payload, mac: mac(options.key, serializedPayload)})
+    const temporary = join(dirname(options.file), `.sessions-${random(12).toString("hex")}.tmp`)
+    let handle
+    try {
+      handle = await open(temporary, "wx", 0o600)
+      throwIfAborted(signal)
+      await handle.writeFile(document)
+      await durabilityObserver?.("before-file-sync")
+      await handle.sync()
+      await durabilityObserver?.("after-file-sync")
+      await handle.close()
+      handle = undefined
+      throwIfAborted(signal)
+      await durabilityObserver?.("before-rename")
+      await rename(temporary, options.file)
+      await durabilityObserver?.("after-rename")
+      const directory = await open(dirname(options.file), "r")
+      try {
+        await durabilityObserver?.("before-directory-sync")
+        await directory.sync()
+        await durabilityObserver?.("after-directory-sync")
+      } finally {
+        await directory.close()
+      }
+    } catch (error) {
+      await handle?.close().catch(() => {})
+      throw error
+    }
+  }
+  const transact = (operation) => {
+    const result = serial.then(operation)
+    serial = result.catch(() => {})
+    return result
+  }
+  const allocationRecord = (allocation) => ({
+    task: allocation.task,
+    lineage: allocation.lineage,
+    volume: allocation.volume,
+    labels: allocation.labels
+  })
+
+  return {
+    namespace: options.namespace,
+    allocate(task) {
+      const lineage = random(24).toString("hex")
+      return {
+        task,
+        lineage,
+        volume: `threadwire-state-${options.namespace}-${lineage}`,
+        labels: stateLabels(options.namespace, task, lineage)
+      }
+    },
+    sealRun(identity) {
+      return mac(options.key, canonicalRunIdentity(identity))
+    },
+    ownsRun(identity, seal) {
+      const lineage = lineages.get(identity.lineage)
+      if (!lineage || lineage.volume !== identity.volume || lineage.labels["org.threadwire.task"] !== identity.task) return false
+      return typeof seal === "string" && equalMac(seal, mac(options.key, canonicalRunIdentity(identity)))
+    },
+    async trackRun(identity, signal) {
+      await transact(async () => {
+        throwIfAborted(signal)
+        canonicalRunIdentity(identity)
+        if (!lineages.has(identity.lineage)) throw new Error("Codex run lineage is unavailable")
+        const existing = runs.get(identity.run)
+        if (existing && canonicalRunIdentity(existing) !== canonicalRunIdentity(identity)) throw new Error("Codex run ownership collision")
+        const nextRuns = new Map(runs)
+        nextRuns.set(identity.run, identity)
+        await persist(sessions, lineages, nextRuns, signal)
+        replace(runs, nextRuns)
+        throwIfAborted(signal)
+      })
+    },
+    async completeRun(run, signal) {
+      await transact(async () => {
+        throwIfAborted(signal)
+        if (!runs.has(run)) return
+        const nextRuns = new Map(runs)
+        nextRuns.delete(run)
+        await persist(sessions, lineages, nextRuns, signal)
+        replace(runs, nextRuns)
+        throwIfAborted(signal)
+      })
+    },
+    runRecords() {
+      return [...runs.values()].map((entry) => ({...entry}))
+    },
+    lookup(sessionId) {
+      const entry = sessions.get(sessionId)
+      if (!entry || entry.expiresAt <= now()) return undefined
+      return {...entry, labels: stateLabels(options.namespace, entry.task, entry.lineage)}
+    },
+    async track(allocation, signal) {
+      await transact(async () => {
+        throwIfAborted(signal)
+        const existing = lineages.get(allocation.lineage)
+        const candidate = allocationRecord(allocation)
+        if (existing && JSON.stringify(existing) !== JSON.stringify(candidate)) throw new Error("Codex lineage ownership collision")
+        const nextLineages = new Map(lineages)
+        nextLineages.set(allocation.lineage, candidate)
+        await persist(sessions, nextLineages, runs, signal)
+        replace(lineages, nextLineages)
+        throwIfAborted(signal)
+      })
+    },
+    async register(sessionIds, allocation, ttlMs, signal) {
+      await transact(async () => {
+        throwIfAborted(signal)
+        const candidate = allocationRecord(allocation)
+        const owned = lineages.get(allocation.lineage)
+        if (owned && JSON.stringify(owned) !== JSON.stringify(candidate)) throw new Error("Codex lineage ownership collision")
+        const nextSessions = new Map(sessions)
+        const nextLineages = new Map(lineages)
+        for (const sessionId of sessionIds) {
+          const existing = nextSessions.get(sessionId)
+          if (existing && (existing.task !== allocation.task || existing.lineage !== allocation.lineage || existing.volume !== allocation.volume)) {
+            throw new Error("Codex session lineage collision")
+          }
+          nextSessions.set(sessionId, {
+            task: allocation.task, lineage: allocation.lineage, volume: allocation.volume, expiresAt: now() + ttlMs
+          })
+        }
+        nextLineages.set(allocation.lineage, candidate)
+        await persist(nextSessions, nextLineages, runs, signal)
+        replace(sessions, nextSessions)
+        replace(lineages, nextLineages)
+        throwIfAborted(signal)
+      })
+    },
+    /**
+     * Sweeps aliases, adopts only exactly labelled namespace-owned orphan
+     * volumes, and retries failed deletions without dropping ownership.
+     */
+    async collect(docker, activeLineages = new Set(), requestOptions = {}) {
+      throwIfAborted(requestOptions.signal)
+      const listed = await docker.listVolumes({
+        "org.threadwire.owner": OWNER,
+        "org.threadwire.namespace": options.namespace
+      }, requestOptions)
+      const plan = await transact(async () => {
+        throwIfAborted(requestOptions.signal)
+        const nextSessions = new Map(sessions)
+        const nextLineages = new Map(lineages)
+        for (const [sessionId, entry] of nextSessions) if (entry.expiresAt <= now()) nextSessions.delete(sessionId)
+        for (const volume of Array.isArray(listed?.Volumes) ? listed.Volumes : []) {
+          const orphan = ownedVolumeRecord(volume, options.namespace)
+          if (orphan && !nextLineages.has(orphan.lineage)) nextLineages.set(orphan.lineage, orphan)
+        }
+        // Persist removals and adopted cleanup evidence before touching Docker.
+        await persist(nextSessions, nextLineages, runs, requestOptions.signal)
+        replace(sessions, nextSessions)
+        replace(lineages, nextLineages)
+        throwIfAborted(requestOptions.signal)
+        const live = new Set([...nextSessions.values()].map((entry) => entry.lineage))
+        return [...nextLineages].filter(([lineage]) => !live.has(lineage) && !activeLineages.has(lineage))
+      })
+      const removedCandidates = []
+      for (const [lineage, entry] of plan) {
+        throwIfAborted(requestOptions.signal)
+        try {
+          const volume = await docker.inspectVolume(entry.volume, requestOptions)
+          validateStateVolume(volume, entry.volume, entry.labels)
+          if (activeLineages.has(lineage)) continue
+          await docker.removeVolume(entry.volume, requestOptions)
+          removedCandidates.push([lineage, entry])
+        } catch (error) {
+          if (isDockerMissing(error)) removedCandidates.push([lineage, entry])
+        }
+      }
+      return transact(async () => {
+        throwIfAborted(requestOptions.signal)
+        const nextLineages = new Map(lineages)
+        let removed = 0
+        const live = new Set([...sessions.values()].filter((entry) => entry.expiresAt > now()).map((entry) => entry.lineage))
+        for (const [lineage, expected] of removedCandidates) {
+          if (live.has(lineage) || activeLineages.has(lineage)) continue
+          if (JSON.stringify(nextLineages.get(lineage)) !== JSON.stringify(expected)) continue
+          nextLineages.delete(lineage)
+          removed++
+        }
+        await persist(sessions, nextLineages, runs, requestOptions.signal)
+        replace(lineages, nextLineages)
+        throwIfAborted(requestOptions.signal)
+        return {sessions: sessions.size, lineages: lineages.size, removed}
+      })
+    },
+    counts() {
+      return {sessions: sessions.size, lineages: lineages.size, runs: runs.size}
+    }
+  }
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("Isolated state operation aborted")
+}
+
+export function stateLabels(namespace, task, lineage) {
+  return {
+    "org.threadwire.owner": OWNER,
+    "org.threadwire.namespace": namespace,
+    "org.threadwire.task": createHmac("sha256", namespace).update(task).digest("hex"),
+    "org.threadwire.lineage": lineage
+  }
+}
+
+export function validateStateVolume(volume, name, labels) {
+  if (!record(volume) || volume.Name !== name || !record(volume.Labels)) throw new Error("Isolated state volume collision")
+  const actual = volume.Labels
+  if (Object.keys(actual).length !== Object.keys(labels).length) throw new Error("Isolated state volume collision")
+  for (const [key, value] of Object.entries(labels)) if (actual[key] !== value) throw new Error("Isolated state volume collision")
+}
+
+function ownedVolumeRecord(volume, namespace) {
+  if (!record(volume) || !record(volume.Labels)) return undefined
+  const labels = volume.Labels
+  const lineage = labels["org.threadwire.lineage"]
+  const name = volume.Name
+  if (Object.keys(labels).length !== 4
+    || labels["org.threadwire.owner"] !== OWNER
+    || labels["org.threadwire.namespace"] !== namespace
+    || !/^[0-9a-f]{64}$/u.test(labels["org.threadwire.task"])
+    || !/^[0-9a-f]{48}$/u.test(lineage)
+    || name !== `threadwire-state-${namespace}-${lineage}`) return undefined
+  return {task: "", lineage, volume: name, labels}
+}
+
+function lineageFromSession(namespace, entry) {
+  return {
+    task: entry.task, lineage: entry.lineage, volume: entry.volume,
+    labels: stateLabels(namespace, entry.task, entry.lineage)
+  }
+}
+
+function validSession(value) {
+  return record(value) && typeof value.sessionId === "string" && typeof value.task === "string"
+    && /^[0-9a-f]{48}$/u.test(value.lineage)
+    && /^threadwire-state-[A-Za-z0-9_.-]+-[0-9a-f]{48}$/u.test(value.volume)
+    && Number.isSafeInteger(value.expiresAt)
+}
+
+function validLineage(value, namespace) {
+  return record(value) && typeof value.task === "string" && /^[0-9a-f]{48}$/u.test(value.lineage)
+    && value.volume === `threadwire-state-${namespace}-${value.lineage}` && record(value.labels)
+    && Object.keys(value.labels).length === 4
+    && value.labels["org.threadwire.owner"] === OWNER
+    && value.labels["org.threadwire.namespace"] === namespace
+    && value.labels["org.threadwire.lineage"] === value.lineage
+    && /^[0-9a-f]{64}$/u.test(value.labels["org.threadwire.task"])
+}
+
+function isDockerMissing(error) {
+  return error instanceof Error && /\(404\)/u.test(error.message)
+}
+
+function without(value, key) {
+  const copy = {...value}
+  delete copy[key]
+  return copy
+}
+
+function replace(target, source) {
+  target.clear()
+  for (const [key, value] of source) target.set(key, value)
+}
+
+async function removeAuthenticatedTemps(directory, key, namespace) {
+  const names = await readdir(directory)
+  let removed = false
+  for (const name of names) {
+    if (!/^\.sessions-[0-9a-f]{24}\.tmp$/u.test(name)) continue
+    let handle
+    try {
+      const path = join(directory, name)
+      handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+      const before = await handle.stat({bigint: true})
+      if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n
+        || before.uid !== BigInt(process.getuid?.() ?? -1)
+        || before.size < 1n || before.size > 4_194_304n || (before.mode & 0o077n) !== 0n) continue
+      const document = JSON.parse(await handle.readFile("utf8"))
+      if (!authenticatedDocument(document, key, namespace)) continue
+      const after = await lstat(path, {bigint: true})
+      if (after.dev !== before.dev || after.ino !== before.ino || after.isSymbolicLink()) continue
+      await unlink(path)
+      removed = true
+    } catch {
+      // Malformed, unreadable, and foreign temp files are deliberately left untouched.
+    } finally {
+      await handle?.close().catch(() => {})
+    }
+  }
+  if (!removed) return
+  const handle = await open(directory, "r")
+  try { await handle.sync() } finally { await handle.close() }
+}
+
+function authenticatedDocument(document, key, namespace) {
+  if (!record(document) || ![1, 2, 3].includes(document.version) || typeof document.mac !== "string"
+    || !record(document.payload) || !Array.isArray(document.payload.sessions)) return false
+  const payload = JSON.stringify(document.payload)
+  if (!equalMac(document.mac, mac(key, payload))) return false
+  if (!document.payload.sessions.every(validSession)) return false
+  if (document.version === 1) return true
+  if (!Array.isArray(document.payload.lineages)
+    || !document.payload.lineages.every((entry) => validLineage(entry, namespace))) return false
+  return document.version === 2 || (Array.isArray(document.payload.runs)
+    && document.payload.runs.every((entry) => {
+      try { canonicalRunIdentity(entry); return true } catch { return false }
+    }))
+}
+
+function canonicalRunIdentity(identity) {
+  const keys = [
+    "namespace", "run", "lineage", "task", "volume", "network", "container",
+    "image", "worktreeType", "worktreeSource", "worktreeSubpath"
+  ]
+  if (!record(identity) || Object.keys(identity).length !== keys.length
+    || keys.some((key) => typeof identity[key] !== "string")) throw new Error("Invalid isolated run identity")
+  return JSON.stringify(Object.fromEntries(keys.map((key) => [key, identity[key]])))
+}
+
+async function requirePrivateDirectory(path) {
+  const stats = await lstat(path)
+  if (!stats.isDirectory() || stats.isSymbolicLink() || (stats.mode & 0o077) !== 0) throw new Error("Invalid isolated state directory")
+}
+
+function mac(key, payload) {
+  return createHmac("sha256", key).update(payload).digest("hex")
+}
+
+function equalMac(left, right) {
+  if (!/^[0-9a-f]{64}$/u.test(left)) return false
+  return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"))
+}
+
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/isolated-worker.js

@@ -0,0 +1,123 @@
+// @ts-check
+
+import {isAbsolute, normalize} from "node:path"
+
+const DIGEST_IMAGE = /^(?:[^@\s]+@)?sha256:[0-9a-f]{64}$/u
+const SAFE_VALUE = /^[^\0\r\n]+$/u
+
+/**
+ * @typedef {{
+ *   image: string,
+ *   worktree: string,
+ *   networkName: string,
+ *   brokerToken: string,
+ *   prompt: string,
+ *   resumeSession?: string,
+ *   brokerUrl?: string
+ *   worktreeVolume?: {name: string, subpath: string}
+ *   workingDirectory: string,
+ *   providerArguments: string[],
+ *   stateVolume: string,
+ *   worktreeInode: string,
+ *   cwdInode: string
+ *   lineage?: string
+ *   namespace?: string
+ *   runId?: string
+ *   taskHash?: string
+ *   runSeal?: string
+ * }} WorkerSpecOptions
+ */
+
+/** @param {WorkerSpecOptions} options */
+export function buildWorkerContainerSpec(options) {
+  if (!DIGEST_IMAGE.test(options.image)) throw new Error("Worker image must use an immutable digest")
+  if (!isAbsolute(options.worktree) || normalize(options.worktree) !== options.worktree || options.worktree === "/") {
+    throw new Error("Worker worktree must be a normalized non-root absolute path")
+  }
+  for (const [name, value] of /** @type {[string, string][]} */ ([["network", options.networkName], ["capability", options.brokerToken], ["prompt", options.prompt]])) {
+    if (!SAFE_VALUE.test(value)) throw new Error(`Worker ${name} is invalid`)
+  }
+  if (options.resumeSession !== undefined && !SAFE_VALUE.test(options.resumeSession)) throw new Error("Worker resume session is invalid")
+  if (!isAbsolute(options.workingDirectory) || !withinWorktree(options.workingDirectory)) throw new Error("Worker cwd is invalid")
+  const environment = [
+    "HOME=/home/worker",
+    "CODEX_HOME=/home/worker/.codex",
+    "TMPDIR=/tmp",
+    `OPENAI_BASE_URL=${options.brokerUrl ?? "http://model-broker:8789/v1"}`,
+    `OPENAI_API_KEY=${options.brokerToken}`,
+    `CODEX_API_KEY=${options.brokerToken}`,
+    `THREADWIRE_PROMPT=${options.prompt}`,
+    `THREADWIRE_CODEX_ARGUMENTS=${JSON.stringify(options.providerArguments)}`,
+    `THREADWIRE_WORKTREE_INODE=${options.worktreeInode}`,
+    `THREADWIRE_CWD_INODE=${options.cwdInode}`,
+    ...(options.resumeSession === undefined ? [] : [`THREADWIRE_RESUME_SESSION=${options.resumeSession}`])
+  ]
+  const worktreeMount = options.worktreeVolume === undefined
+    ? {
+      Type: "bind",
+      Source: options.worktree,
+      Target: "/worktree",
+      ReadOnly: false,
+      BindOptions: {Propagation: "rprivate"}
+    }
+    : {
+      Type: "volume",
+      Source: options.worktreeVolume.name,
+      Target: "/worktree",
+      ReadOnly: false,
+      VolumeOptions: {Subpath: options.worktreeVolume.subpath}
+    }
+  return {
+    Image: options.image,
+    Labels: {
+      "org.threadwire.owner": "isolated-runtime",
+      ...(options.lineage === undefined ? {} : {
+        "org.threadwire.namespace": options.namespace,
+        "org.threadwire.run": options.runId,
+        "org.threadwire.lineage": options.lineage,
+        "org.threadwire.task": options.taskHash,
+        "org.threadwire.network": options.networkName,
+        "org.threadwire.state-volume": options.stateVolume,
+        "org.threadwire.run-seal": options.runSeal
+      })
+    },
+    Entrypoint: ["/usr/local/libexec/threadwire/worker-entrypoint"],
+    Env: environment,
+    WorkingDir: options.workingDirectory,
+    User: "10002:10002",
+    NetworkDisabled: false,
+    HostConfig: {
+      AutoRemove: false,
+      Mounts: [
+        worktreeMount,
+        {Type: "volume", Source: options.stateVolume, Target: "/home/worker", ReadOnly: false}
+      ],
+      CapDrop: ["ALL"],
+      NetworkMode: options.networkName,
+      ReadonlyRootfs: true,
+      SecurityOpt: ["no-new-privileges"],
+      PidsLimit: 128,
+      Memory: 1_073_741_824,
+      NanoCpus: 2_000_000_000,
+      Tmpfs: {
+        "/tmp": "rw,noexec,nosuid,nodev,size=67108864,uid=10002,gid=10002",
+        "/run": "rw,noexec,nosuid,nodev,size=1048576,uid=10002,gid=10002"
+      },
+      Ulimits: [
+        {Name: "nofile", Soft: 1024, Hard: 1024},
+        {Name: "core", Soft: 0, Hard: 0},
+        {Name: "fsize", Soft: 1_073_741_824, Hard: 1_073_741_824}
+      ]
+    }
+  }
+}
+
+/** @param {string} path */
+function withinWorktree(path) {
+  return path === "/worktree" || path.startsWith("/worktree/")
+}
+
+/** @param {string} value */
+export function isDigestImage(value) {
+  return DIGEST_IMAGE.test(value)
+}

package/src/model-broker-policy.js

@@ -0,0 +1,139 @@
+// @ts-check
+
+import {randomBytes} from "node:crypto"
+
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,128}$/u
+const NETWORK_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u
+const RUN_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u
+const ALLOWED_HEADERS = new Set([
+  "authorization", "content-length", "content-type", "user-agent", "accept",
+  "accept-encoding", "accept-language", "sec-fetch-mode",
+  "x-stainless-arch", "x-stainless-lang", "x-stainless-os",
+  "x-stainless-package-version", "x-stainless-runtime",
+  "x-stainless-runtime-version", "x-stainless-retry-count", "x-stainless-timeout",
+  "x-stainless-async", "originator", "conversation_id", "session_id",
+  "version", "x-codex-turn-metadata"
+])
+
+/** @param {{now?: () => number, random?: (bytes: number) => Buffer}} [options] */
+export function createGrantStore(options = {}) {
+  const now = options.now ?? Date.now
+  const random = options.random ?? randomBytes
+  /** @type {Map<string, {runId: string, provider: "codex", networkId: string, model: string, expiresAt: number, active: boolean}>} */
+  const grants = new Map()
+  return {
+    /** @param {{runId: string, provider: "codex", networkId: string, model: string, ttlMs: number}} grant */
+    issue(grant) {
+      if (!RUN_PATTERN.test(grant.runId) || !NETWORK_PATTERN.test(grant.networkId)) throw new Error("Invalid broker grant")
+      if (grant.provider !== "codex") throw new Error("Invalid broker grant")
+      if (typeof grant.model !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(grant.model)) throw new Error("Invalid broker grant")
+      if (!Number.isSafeInteger(grant.ttlMs) || grant.ttlMs < 1 || grant.ttlMs > 3_600_000) throw new Error("Invalid broker grant")
+      const token = random(32).toString("base64url")
+      grants.set(token, {...grant, expiresAt: now() + grant.ttlMs, active: false})
+      return token
+    },
+    /** @param {string} token */
+    activate(token) {
+      const grant = grants.get(token)
+      if (!grant) throw new Error("Broker grant unknown token")
+      if (grant.expiresAt < now()) {
+        grants.delete(token)
+        throw new Error("Broker grant expired")
+      }
+      if (grant.active) throw new Error("Broker grant already active")
+      grant.active = true
+      return {...grant}
+    },
+    /** @param {string} token @param {{provider: string, networkId: string, runId?: string}} context */
+    authorize(token, context) {
+      const grant = grants.get(token)
+      if (!grant) throw new Error("Broker grant unknown token")
+      if (grant.provider !== context.provider || grant.networkId !== context.networkId || (context.runId !== undefined && grant.runId !== context.runId)) throw new Error("Broker grant lineage denied")
+      if (!grant.active) throw new Error("Broker grant pending")
+      if (grant.expiresAt < now()) {
+        grants.delete(token)
+        throw new Error("Broker grant expired")
+      }
+      return {...grant}
+    },
+    /** @param {string} token */
+    revoke(token) {
+      grants.delete(token)
+    },
+    clear() {
+      grants.clear()
+    }
+  }
+}
+
+/**
+ * @param {{method?: string, path?: string, headers?: Record<string, string | string[] | undefined>}} request
+ */
+export function validateBrokerRequest(request) {
+  if (request.method !== "POST" || request.path !== "/v1/responses") throw new Error("Broker request denied")
+  for (const header of Object.keys(request.headers ?? {})) {
+    if (!ALLOWED_HEADERS.has(header.toLowerCase())) throw new Error(`Broker request denied header: ${header.toLowerCase()}`)
+  }
+  return {method: "POST", path: "/v1/responses"}
+}
+
+const RESPONSE_KEYS = new Set([
+  "model", "input", "instructions", "stream", "tools", "tool_choice",
+  "parallel_tool_calls", "previous_response_id", "reasoning", "store",
+  "include", "metadata", "max_output_tokens", "temperature", "top_p", "truncation",
+  "prompt_cache_key"
+])
+
+/** @param {Buffer} body @param {string} allowedModel */
+export function validateResponsesBody(body, allowedModel) {
+  const text = body.toString("utf8")
+  if (topLevelKeyCount(text, "model") !== 1) throw new Error("Broker request denied")
+  let value
+  try {
+    value = JSON.parse(text)
+  } catch {
+    throw new Error("Broker request denied")
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Broker request denied")
+  const unexpected = Object.keys(value).find((key) => !RESPONSE_KEYS.has(key))
+  if (unexpected !== undefined) throw new Error(`Broker request denied field: ${unexpected}`)
+  if (value.model !== allowedModel || !("input" in value)) throw new Error("Broker request denied")
+  return value
+}
+
+/** @param {string} text @param {string} wanted */
+function topLevelKeyCount(text, wanted) {
+  let depth = 0
+  let count = 0
+  let index = 0
+  while (index < text.length) {
+    const character = text[index]
+    if (character === "\"") {
+      let string = ""
+      index += 1
+      while (index < text.length && text[index] !== "\"") {
+        if (text[index] === "\\") {
+          index += 2
+          continue
+        }
+        string += text[index]
+        index += 1
+      }
+      if (depth === 1) {
+        let next = index + 1
+        while (/\s/u.test(text[next] ?? "")) next += 1
+        if (text[next] === ":" && string === wanted) count += 1
+      }
+    } else if (character === "{") depth += 1
+    else if (character === "}") depth -= 1
+    index += 1
+  }
+  return count
+}
+
+/** @param {string | undefined} authorization */
+export function bearerToken(authorization) {
+  const match = /^Bearer ([A-Za-z0-9_-]{32,128})$/u.exec(authorization ?? "")
+  if (!match || !TOKEN_PATTERN.test(match[1] ?? "")) throw new Error("Broker grant format denied")
+  return /** @type {string} */ (match[1])
+}