@huynle/hub 0.7.3 → 0.8.0

package/src/central/artifacts/host-caps.ts

@@ -0,0 +1,162 @@
+// Capabilities of the isolated artifact host (HWA-26; contract: Cross-cutting "Trust boundary", ADR in Brain).
+//
+// The artifact host serves an html/app revision's files at /artifact-host/v1/<token>/<path> with no ambient
+// credentials: no cookie, no bearer, only the token in the path. A token is
+//
+//   ahc1.<kid>.<base64url(JSON {c: capID, u: userID, a: artifactID, r: revisionID, e: expiresAt})>.<base64url(sig)>
+//
+// where sig = HMAC-SHA256(secret of kid, "ahc1.<kid>.<payload>"), signed with the hub's token keys (the "ahc1."
+// prefix separates it from every other token those keys sign). The payload names a record in the per-user
+// collection ARTIFACT_HOST_CAPS, which holds what the token may never assert by itself: the viewer it was minted
+// for (the user or a session, and the device) and whether it was revoked. So a capability is
+//   - short-lived: expiresAt is in the signed payload and in the record (min/max TTL below);
+//   - single-revision: one artifactID + revisionID, signed;
+//   - viewer-bound: the host re-checks the *viewer's* read access to that revision on every request (a session
+//     that leaves the workspace, an archived/deleted artifact or a removed device ends it at once);
+//   - revocable: revoke() marks the record; a missing record (deleted, pruned, another user's) fails closed.
+// Records live in the StateStore (file-state standalone, Postgres cluster), so every pod verifies every token and
+// they survive restarts. Secrets and tokens are never logged.
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto"
+import { AgentError } from "../agent/errors"
+import type { StateStore } from "../backend/types"
+import type { ArtifactPrincipal } from "./access"
+
+export const ARTIFACT_HOST_CAPS = "artifact-host-caps"
+
+export const ARTIFACT_HOST_LIMITS = {
+  /** A capability's lifetime when the minter names none. */
+  defaultTtlMs: 15 * 60_000,
+  minTtlMs: 5_000,
+  maxTtlMs: 60 * 60_000,
+  /** Unexpired capabilities one user may hold (a soft cap: concurrent mints may overshoot by a few). */
+  liveCapsPerUser: 64,
+  /** Characters of a token (anything longer is refused unparsed). */
+  tokenChars: 1024,
+} as const
+
+const PREFIX = "ahc1"
+const B64URL = /^[A-Za-z0-9_-]+$/
+
+/** The hub's signing keys (TokenKeys implements it). */
+export interface HostSigningKeys {
+  active(): { kid: string; secret: Buffer }
+  key(kid: string): Buffer | undefined
+}
+
+export interface StoredHostCap {
+  readonly v: 1
+  readonly id: string
+  readonly artifactID: string
+  readonly revisionID: string
+  /** Who minted it: the host reads the revision as this principal. */
+  readonly viewer: ArtifactPrincipal
+  /** The minting device (console users), re-checked on use when the hub can. */
+  readonly deviceID?: string
+  readonly createdAt: number
+  readonly expiresAt: number
+  readonly revokedAt?: number
+}
+
+export interface MintInput {
+  readonly artifactID: string
+  readonly revisionID: string
+  readonly ttlMs?: number
+  readonly deviceID?: string
+}
+
+export interface ArtifactHostCapsOptions {
+  readonly state: StateStore
+  readonly keys: HostSigningKeys
+  readonly now?: () => number
+}
+
+interface Payload {
+  c: string
+  u: string
+  a: string
+  r: string
+  e: number
+}
+
+const sign = (secret: Buffer, kid: string, payload: string): string => createHmac("sha256", secret).update(`${PREFIX}.${kid}.${payload}`).digest("base64url")
+
+const sameViewer = (a: ArtifactPrincipal, b: ArtifactPrincipal): boolean => a.kind === b.kind && (a.kind === "user" || (b.kind === "session" && a.sessionID === b.sessionID))
+
+export class ArtifactHostCaps {
+  private readonly state: StateStore
+  private readonly keys: HostSigningKeys
+  private readonly now: () => number
+
+  constructor(options: ArtifactHostCapsOptions) {
+    this.state = options.state
+    this.keys = options.keys
+    this.now = options.now ?? Date.now
+  }
+
+  /** A new capability for one revision as `viewer`; prunes the user's expired ones and enforces the live cap. */
+  async mint(userID: string, viewer: ArtifactPrincipal, input: MintInput): Promise<{ token: string; capability: { id: string; expiresAt: number } }> {
+    const now = this.now()
+    let live = 0
+    for (const entry of await this.state.list<StoredHostCap>(userID, ARTIFACT_HOST_CAPS)) {
+      if (entry.value.expiresAt <= now || entry.value.revokedAt !== undefined) await this.state.delete(userID, ARTIFACT_HOST_CAPS, entry.key)
+      else live++
+    }
+    if (live >= ARTIFACT_HOST_LIMITS.liveCapsPerUser) {
+      throw new AgentError("rate_limited", `At most ${ARTIFACT_HOST_LIMITS.liveCapsPerUser} open artifact views at once; close some first`, { extra: { limit: ARTIFACT_HOST_LIMITS.liveCapsPerUser } })
+    }
+    const ttl = Math.min(ARTIFACT_HOST_LIMITS.maxTtlMs, Math.max(ARTIFACT_HOST_LIMITS.minTtlMs, input.ttlMs ?? ARTIFACT_HOST_LIMITS.defaultTtlMs))
+    const id = `ahc_${randomBytes(12).toString("base64url")}`
+    const cap: StoredHostCap = {
+      v: 1,
+      id,
+      artifactID: input.artifactID,
+      revisionID: input.revisionID,
+      viewer: viewer.kind === "user" ? { kind: "user" } : { kind: "session", sessionID: viewer.sessionID },
+      ...(input.deviceID !== undefined ? { deviceID: input.deviceID } : {}),
+      createdAt: now,
+      expiresAt: now + ttl,
+    }
+    await this.state.put(userID, ARTIFACT_HOST_CAPS, id, cap)
+    const { kid, secret } = this.keys.active()
+    const payload = Buffer.from(JSON.stringify({ c: id, u: userID, a: cap.artifactID, r: cap.revisionID, e: cap.expiresAt } satisfies Payload)).toString("base64url")
+    return { token: `${PREFIX}.${kid}.${payload}.${sign(secret, kid, payload)}`, capability: { id, expiresAt: cap.expiresAt } }
+  }
+
+  /** The user and record of a valid token; undefined for anything else (malformed, forged, expired, revoked). */
+  async verify(token: string): Promise<{ userID: string; cap: StoredHostCap } | undefined> {
+    if (typeof token !== "string" || token.length > ARTIFACT_HOST_LIMITS.tokenChars) return undefined
+    const parts = token.split(".")
+    if (parts.length !== 4) return undefined
+    const [prefix, kid, payload, sig] = parts as [string, string, string, string]
+    if (prefix !== PREFIX || !B64URL.test(kid) || !B64URL.test(payload) || !B64URL.test(sig)) return undefined
+    const secret = this.keys.key(kid)
+    if (!secret) return undefined
+    const expected = Buffer.from(sign(secret, kid, payload))
+    const given = Buffer.from(sig)
+    if (expected.length !== given.length || !timingSafeEqual(expected, given)) return undefined
+    let body: Payload
+    try {
+      body = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as Payload
+    } catch {
+      return undefined
+    }
+    if (typeof body?.c !== "string" || typeof body.u !== "string" || typeof body.a !== "string" || typeof body.r !== "string" || typeof body.e !== "number") return undefined
+    const now = this.now()
+    if (body.e <= now) return undefined
+    const stored = await this.state.get<StoredHostCap>(body.u, ARTIFACT_HOST_CAPS, body.c)
+    const cap = stored?.value
+    if (!cap || cap.id !== body.c || cap.artifactID !== body.a || cap.revisionID !== body.r || cap.expiresAt !== body.e) return undefined
+    if (cap.revokedAt !== undefined || cap.expiresAt <= now) return undefined
+    return { userID: body.u, cap }
+  }
+
+  /** Revokes one capability of `userID`: the user may revoke any, a session only its own. False when none. */
+  async revoke(userID: string, viewer: ArtifactPrincipal, id: string): Promise<boolean> {
+    if (typeof id !== "string" || !/^ahc_[A-Za-z0-9_-]{16}$/.test(id)) return false
+    const stored = await this.state.get<StoredHostCap>(userID, ARTIFACT_HOST_CAPS, id)
+    if (!stored || stored.value.revokedAt !== undefined) return false
+    if (viewer.kind === "session" && !sameViewer(stored.value.viewer, viewer)) return false
+    await this.state.put(userID, ARTIFACT_HOST_CAPS, id, { ...stored.value, revokedAt: this.now() })
+    return true
+  }
+}

package/src/central/artifacts/host.ts

@@ -0,0 +1,315 @@
+// The isolated artifact host (HWA-26; contract: Cross-cutting "Trust boundary"; threat model in the Brain ADR and
+// docs/artifact-host.md). Interactive artifacts (ISOLATED_KINDS: html, app) run only here, never in the console
+// bundle and never in central: the hub serves the static bytes it stored and nothing else.
+//
+//   GET /artifact-host/v1/<token>/<path>            one file of the token's revision (no cookie or bearer used)
+//   GET /artifact-host/v1/<token>/…/__hub/bridge.js  the first-party bridge client (window.hubArtifact)
+//   POST   /api/agent/artifacts/:id/revisions/:rev/host  {ttlSeconds?} → {capability, base, url, files}
+//   DELETE /api/agent/artifact-host/:cap                 revoke (the minting viewer, or the user)
+//
+// Isolation, out of the box (no new hostname, DNS or TLS): every host response carries
+// `Content-Security-Policy: sandbox allow-scripts; …` and the console frames it with `sandbox="allow-scripts"`
+// (never allow-same-origin), so the document always gets a fresh *opaque* origin, even opened top-level. It can't
+// read the hub's cookies or the console's storage, and the browser treats its requests as cross-site (the hub's
+// SameSite=Lax cookie is not attached). No popups, top navigation, forms, modals or downloads (not allowed by the
+// sandbox), no plugins, workers or nested frames, and no network except this capability's own path prefix
+// (connect/script/style/img/font/media-src are path-scoped to `<origin>/artifact-host/v1/<token>/`). Only the
+// console origins may frame it (frame-ancestors). Bytes are served as declared (never sniffed: nosniff).
+// Authority: the token only (./host-caps.ts), re-checked as the minting viewer on every request, and rate limited
+// per capability. CORS answers `*` without credentials so module scripts load from the opaque origin.
+import { boundedText } from "../agent/body"
+import { type ArtifactKind, ISOLATED_KINDS, type BlobRef } from "../../protocol"
+import type { AgentActor } from "../agent/actor"
+import { AgentError } from "../agent/errors"
+// Types only: ../agent/routes imports the artifact modules (a value import would be circular).
+import type { AgentRoute } from "../agent/routes"
+import type { ArtifactPrincipal } from "./access"
+import { ARTIFACT_HOST_LIMITS, type ArtifactHostCaps } from "./host-caps"
+import type { ArtifactStore } from "./store"
+
+export const ARTIFACT_HOST_PATH = "/artifact-host/v1/"
+/** The bridge client, served at this path under any directory of a capability. Bundle files there are shadowed. */
+export const BRIDGE_CLIENT_PATH = "__hub/bridge.js"
+/** Must equal BRIDGE_PROTOCOL / BRIDGE_VERSION in web/src/core/artifact-bridge.ts (a test checks). */
+export const BRIDGE_PROTOCOL = "hub.artifact-bridge"
+export const BRIDGE_VERSION = 1
+
+export const ARTIFACT_HOST_LIMITS_HTTP = {
+  ...ARTIFACT_HOST_LIMITS,
+  /** Host requests one capability may make per minute (per hub process). */
+  requestsPerMinute: 600,
+  /** Capabilities tracked by the rate limiter before old windows are dropped. */
+  trackedCaps: 10_000,
+  /** A mint request body. */
+  mintBodyBytes: 1024,
+} as const
+
+export const isArtifactHostPath = (pathname: string): boolean => pathname === "/artifact-host" || pathname.startsWith("/artifact-host/")
+
+const FILE_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))(?!.*\/\/)[A-Za-z0-9._/-]{1,200}$/
+const BRIDGE_AT = /^(?:[A-Za-z0-9._-]+\/)*__hub\/bridge\.js$/
+const TOKEN = /^[A-Za-z0-9._-]{1,1024}$/
+const PERMISSIONS =
+  "accelerometer=(), autoplay=(), camera=(), clipboard-read=(), clipboard-write=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), hid=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), serial=(), usb=(), xr-spatial-tracking=()"
+
+const unique = (values: readonly string[]): string[] => [...new Set(values)]
+
+/** The host's Content-Security-Policy: sandboxed, nothing by default, sources only under the capability's path. */
+export function hostCsp(bases: readonly string[], ancestors: readonly string[]): string {
+  const b = unique(bases).join(" ")
+  return [
+    "sandbox allow-scripts",
+    "default-src 'none'",
+    `script-src ${b} 'unsafe-inline'`,
+    `style-src ${b} 'unsafe-inline'`,
+    `img-src ${b} data: blob:`,
+    `font-src ${b} data:`,
+    `media-src ${b} data: blob:`,
+    `connect-src ${b}`,
+    "frame-src 'none'",
+    "worker-src 'none'",
+    "object-src 'none'",
+    "manifest-src 'none'",
+    "form-action 'none'",
+    "base-uri 'none'",
+    `frame-ancestors ${ancestors.length ? unique(ancestors).join(" ") : "'none'"}`,
+  ].join("; ")
+}
+
+/** For a response without a capability (errors): nothing at all may load or run. */
+const LOCKED_CSP = "sandbox; default-src 'none'; frame-ancestors 'none'"
+
+/**
+ * The bridge client the artifact loads from `__hub/bridge.js`: window.hubArtifact. It accepts the init message only
+ * from its parent window (source check) on a console origin (origin check), then talks only on that channel to
+ * that origin. Replies are matched by request ID. First-party code; the artifact may also speak the protocol itself.
+ */
+export function bridgeClientScript(parents: readonly string[]): string {
+  return `// Hub artifact bridge client (HWA-26). Protocol ${BRIDGE_PROTOCOL} v${BRIDGE_VERSION}.
+(() => {
+  "use strict";
+  if (window.hubArtifact) return;
+  const P = ${JSON.stringify(BRIDGE_PROTOCOL)}, V = ${BRIDGE_VERSION}, PARENTS = ${JSON.stringify(unique(parents))};
+  const up = window.parent;
+  let channel, origin, info, seq = 0;
+  const pending = new Map(), waiting = [];
+  addEventListener("message", (e) => {
+    if (up === window || e.source !== up || !PARENTS.includes(e.origin)) return;
+    const m = e.data;
+    if (!m || typeof m !== "object" || m.p !== P || m.v !== V) return;
+    if (m.type === "init") {
+      if (channel !== undefined || typeof m.channel !== "string" || !/^[0-9a-f]{32}$/.test(m.channel)) return;
+      channel = m.channel;
+      origin = e.origin;
+      info = Object.freeze({ artifactID: String(m.artifactID), revisionID: String(m.revisionID), files: Object.freeze((Array.isArray(m.files) ? m.files : []).map((f) => Object.freeze({ ...f }))), capabilities: Object.freeze([...(m.capabilities || [])]) });
+      for (const resolve of waiting.splice(0)) resolve(info);
+      return;
+    }
+    if (m.channel !== channel || m.type !== "reply" || typeof m.id !== "string") return;
+    const p = pending.get(m.id);
+    if (!p) return;
+    pending.delete(m.id);
+    if (m.ok) p.resolve(m.result);
+    else p.reject(Object.assign(new Error(String((m.error && m.error.message) || "refused")), { code: m.error && m.error.code }));
+  });
+  const post = (message) => up.postMessage(Object.assign({ p: P, v: V, channel }, message), origin);
+  const ready = () => (info ? Promise.resolve(info) : new Promise((resolve) => waiting.push(resolve)));
+  const request = async (type, body) => {
+    await ready();
+    const id = "r" + ++seq;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+      post(Object.assign({ type, id }, body));
+    });
+  };
+  const resize = async (height) => {
+    await ready();
+    post({ type: "resize", height: Math.ceil(Number(height) || 0) });
+  };
+  const autoResize = () => {
+    const report = () => resize(document.documentElement.scrollHeight);
+    new ResizeObserver(report).observe(document.documentElement);
+    report();
+  };
+  window.hubArtifact = Object.freeze({ version: V, ready, resize, autoResize, askAI: (instruction) => request("askAI", { instruction: String(instruction) }) });
+})();
+`
+}
+
+export interface ArtifactHostDeps {
+  readonly caps: ArtifactHostCaps
+  /** Absent: this hub keeps no artifacts (every host path answers 404). */
+  readonly artifacts?: Pick<ArtifactStore, "get" | "getRevision" | "readBlob">
+  /** Origins the console is served from: the only frame ancestors and the bridge's accepted parents. */
+  readonly consoleOrigins: () => readonly string[]
+  /** False when a capability's minting device no longer exists (unpaired): the capability stops working. */
+  readonly deviceActive?: (userID: string, deviceID: string) => boolean
+  readonly now?: () => number
+}
+
+const isolated = (kind: ArtifactKind): boolean => ISOLATED_KINDS.includes(kind)
+
+/** The file a host path names in a revision: its bundle path, or "" for the one unnamed file. */
+function fileAt(blobs: readonly BlobRef[], rest: string): BlobRef | undefined {
+  if (rest === "") return blobs.length === 1 && blobs[0]!.path === undefined ? blobs[0] : undefined
+  return blobs.find((b) => b.path === rest)
+}
+
+const contentType = (mediaType: string): string => (mediaType.startsWith("text/") ? `${mediaType}; charset=utf-8` : mediaType)
+
+export function artifactHost(deps: ArtifactHostDeps): { handle(request: Request, url: URL): Promise<Response> } {
+  const now = deps.now ?? Date.now
+  const windows = new Map<string, { start: number; count: number }>()
+
+  const refuse = (status: number, text: string, extra: Record<string, string> = {}) =>
+    new Response(text, {
+      status,
+      headers: { "content-type": "text/plain; charset=utf-8", "content-security-policy": LOCKED_CSP, "x-content-type-options": "nosniff", "referrer-policy": "no-referrer", "cache-control": "no-store", ...extra },
+    })
+  const notFound = () => refuse(404, "Not found (the link may have expired or been revoked)")
+
+  /** False when the capability spent its requests for this minute. */
+  const spend = (capID: string): boolean => {
+    const t = now()
+    let w = windows.get(capID)
+    if (!w || t - w.start >= 60_000) {
+      if (!w && windows.size >= ARTIFACT_HOST_LIMITS_HTTP.trackedCaps) {
+        for (const [id, old] of windows) if (t - old.start >= 60_000) windows.delete(id)
+        if (windows.size >= ARTIFACT_HOST_LIMITS_HTTP.trackedCaps) windows.delete(windows.keys().next().value!)
+      }
+      w = { start: t, count: 0 }
+      windows.set(capID, w)
+    }
+    return ++w.count <= ARTIFACT_HOST_LIMITS_HTTP.requestsPerMinute
+  }
+
+  return {
+    async handle(request, url) {
+      if (request.method !== "GET" && request.method !== "HEAD") return refuse(405, "Method not allowed", { allow: "GET, HEAD" })
+      if (!url.pathname.startsWith(ARTIFACT_HOST_PATH)) return notFound()
+      const tail = url.pathname.slice(ARTIFACT_HOST_PATH.length)
+      const slash = tail.indexOf("/")
+      if (slash <= 0) return notFound()
+      const token = tail.slice(0, slash)
+      const rest = tail.slice(slash + 1)
+      if (!TOKEN.test(token)) return notFound()
+      const isBridge = BRIDGE_AT.test(rest)
+      if (rest !== "" && !isBridge && !FILE_PATH.test(rest)) return notFound()
+      const verified = await deps.caps.verify(token)
+      if (!verified || !deps.artifacts) return notFound()
+      const { userID, cap } = verified
+      if (!spend(cap.id)) return refuse(429, "Too many requests", { "retry-after": "60" })
+      if (cap.deviceID !== undefined && deps.deviceActive && !deps.deviceActive(userID, cap.deviceID)) return notFound()
+      const origins = deps.consoleOrigins()
+      const ancestors = unique([url.origin, ...origins])
+      const base = `${ARTIFACT_HOST_PATH}${token}/`
+      const headers: Record<string, string> = {
+        "content-security-policy": hostCsp(ancestors.map((o) => `${o}${base}`), ancestors),
+        "x-content-type-options": "nosniff",
+        "referrer-policy": "no-referrer",
+        "cache-control": "private, no-store",
+        "permissions-policy": PERMISSIONS,
+        "access-control-allow-origin": "*",
+        "cross-origin-opener-policy": "same-origin",
+      }
+      try {
+        // Re-checked as the minting viewer on every request: a revoked read ends the capability at once.
+        const artifact = await deps.artifacts.get(userID, cap.viewer, cap.artifactID)
+        if (!isolated(artifact.kind)) return notFound()
+        if (isBridge) {
+          const body = request.method === "HEAD" ? null : bridgeClientScript(ancestors)
+          return new Response(body, { status: 200, headers: { ...headers, "content-type": "text/javascript; charset=utf-8" } })
+        }
+        const revision = await deps.artifacts.getRevision(userID, cap.viewer, cap.artifactID, cap.revisionID)
+        const ref = fileAt(revision.blobs, rest)
+        if (!ref) return notFound()
+        const { blob } = await deps.artifacts.readBlob(userID, cap.viewer, cap.artifactID, cap.revisionID, ref.hash)
+        if (request.method === "HEAD") await blob.body.cancel().catch(() => {})
+        return new Response(request.method === "HEAD" ? null : blob.body, {
+          status: 200,
+          headers: { ...headers, "content-type": contentType(ref.mediaType), "content-length": String(blob.bytes), etag: `"${ref.hash}"` },
+        })
+      } catch (error) {
+        if (error instanceof AgentError && (error.code === "not_found" || error.code === "forbidden")) return notFound()
+        throw error
+      }
+    },
+  }
+}
+
+// ---- agent routes: mint and revoke -----------------------------------------------------------------------
+
+export interface ArtifactHostRouteDeps {
+  readonly caps: ArtifactHostCaps
+  /** Absent: this hub keeps no artifacts (422 unsupported). */
+  readonly artifacts?: Pick<ArtifactStore, "get" | "getRevision">
+}
+
+const READ = { session: true, scope: "artifacts:read" } as const
+const NO_STORE = { "cache-control": "no-store" }
+const invalid = (message: string) => new AgentError("invalid", message)
+const principalOf = (actor: AgentActor): ArtifactPrincipal => (actor.kind === "session" ? { kind: "session", sessionID: actor.sessionID } : { kind: "user" })
+
+async function mintBody(request: Request): Promise<{ ttlMs?: number }> {
+  const max = ARTIFACT_HOST_LIMITS_HTTP.mintBodyBytes
+  // Bounded in bytes and time, the drain too (agent/body.ts): "The body is larger than <max> bytes".
+  const text = await boundedText(request, max)
+  if (text.trim() === "") return {}
+  let body: unknown
+  try {
+    body = JSON.parse(text)
+  } catch {
+    throw invalid("Invalid JSON")
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw invalid("Expected a JSON object")
+  const extra = Object.keys(body).find((k) => k !== "ttlSeconds")
+  if (extra !== undefined) throw invalid(`The body has an unknown field ${JSON.stringify(extra.slice(0, 50))}`)
+  const ttl = (body as { ttlSeconds?: unknown }).ttlSeconds
+  if (ttl === undefined) return {}
+  const maxSeconds = ARTIFACT_HOST_LIMITS.maxTtlMs / 1000
+  if (typeof ttl !== "number" || !Number.isSafeInteger(ttl) || ttl < 1 || ttl > maxSeconds) throw invalid(`ttlSeconds must be a whole number 1–${maxSeconds}`)
+  return { ttlMs: ttl * 1000 }
+}
+
+export function artifactHostRoutes(deps: ArtifactHostRouteDeps): AgentRoute[] {
+  const store = () => {
+    if (!deps.artifacts) throw new AgentError("unsupported", "This hub does not store artifacts", { extra: { feature: "artifacts" } })
+    return deps.artifacts
+  }
+  return [
+    {
+      method: "POST",
+      path: "/api/agent/artifacts/:id/revisions/:rev/host",
+      allow: READ,
+      async handle({ user, actor, params, request }) {
+        const artifacts = store()
+        const { ttlMs } = await mintBody(request)
+        const principal = principalOf(actor)
+        const artifact = await artifacts.get(user.id, principal, params.id!)
+        if (!isolated(artifact.kind)) throw invalid(`Only ${ISOLATED_KINDS.join(" and ")} artifacts run in the artifact host; ${artifact.kind} renders in the console`)
+        const revision = await artifacts.getRevision(user.id, principal, artifact.id, params.rev!)
+        const entry = revision.entry ?? ""
+        const entryFile = fileAt(revision.blobs, entry)
+        if (!entryFile || entryFile.mediaType !== "text/html") throw invalid("The revision's entry must be an HTML file")
+        const { token, capability } = await deps.caps.mint(user.id, principal, {
+          artifactID: artifact.id,
+          revisionID: revision.id,
+          ...(ttlMs !== undefined ? { ttlMs } : {}),
+          ...(actor.kind === "user" ? { deviceID: actor.deviceID } : {}),
+        })
+        const base = `${ARTIFACT_HOST_PATH}${token}/`
+        const files = revision.blobs.map((b) => ({ ...(b.path !== undefined ? { path: b.path } : {}), mediaType: b.mediaType, bytes: b.bytes }))
+        return Response.json({ capability, base, url: `${base}${entry}`, files }, { status: 201, headers: NO_STORE })
+      },
+    },
+    {
+      method: "DELETE",
+      path: "/api/agent/artifact-host/:cap",
+      allow: READ,
+      async handle({ user, actor, params }) {
+        if (!(await deps.caps.revoke(user.id, principalOf(actor), params.cap!))) throw new AgentError("not_found", "No such artifact view")
+        return new Response(null, { status: 204, headers: NO_STORE })
+      },
+    },
+  ]
+}

package/src/central/artifacts/idempotency.ts

@@ -0,0 +1,109 @@
+// Idempotency-Key for the artifact creating routes (HWA-21; contract: Cross-cutting rules, Idempotency): per user and
+// per route, IDEMPOTENCY_TTL_MS. The same key and body answer the original result (created false); another body under
+// the same key is 409 conflict. Stored in the StateStore collection "artifact-idempotency":
+//   `<route>|<key>` → { v, digest, at, state: "pending" | "done", artifactID?, revisionID? }
+// A key is claimed (create-only write) before the work runs and released when the work fails, so two concurrent
+// requests with one key never both publish: the second sees a pending claim and answers 429 rate_limited
+// (retryAfter). A pending claim older than PENDING_MS belongs to a writer that crashed and is taken over.
+import { createHash } from "node:crypto"
+import { IDEMPOTENCY_KEY, IDEMPOTENCY_TTL_MS } from "../../protocol"
+import { AgentError } from "../agent/errors"
+import type { Clock, StateStore } from "../backend/types"
+
+export const ARTIFACT_IDEMPOTENCY = "artifact-idempotency"
+/** How long a claim may stay pending before another request takes it over. */
+export const PENDING_MS = 5 * 60_000
+/** Keys kept per user beyond expiry pruning (oldest dropped first). */
+export const IDEMPOTENCY_KEYS_MAX = 2_000
+const ATTEMPTS = 8
+
+export interface IdempotentResult {
+  readonly artifactID: string
+  readonly revisionID: string
+}
+
+interface Claim {
+  readonly v: 1
+  readonly digest: string
+  readonly at: number
+  readonly state: "pending" | "done"
+  readonly artifactID?: string
+  readonly revisionID?: string
+}
+
+/** A stable digest of a JSON body (object keys sorted). */
+export function bodyDigest(body: unknown): string {
+  return createHash("sha256").update(canonical(body)).digest("hex")
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).filter(([, v]) => v !== undefined)
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`
+  }
+  return JSON.stringify(value) ?? "null"
+}
+
+export class ArtifactIdempotency {
+  constructor(
+    private readonly state: StateStore,
+    private readonly now: Clock = Date.now,
+  ) {}
+
+  /**
+   * Runs `work` once per (user, route, key, body): a repeat answers `replay(original)`. Without a key the work just
+   * runs. `work` must resolve with the IDs that identify its result.
+   */
+  async run<T>(
+    userID: string,
+    route: string,
+    key: string | null | undefined,
+    body: unknown,
+    work: () => Promise<{ readonly ids: IdempotentResult; readonly value: T }>,
+    replay: (ids: IdempotentResult) => Promise<T>,
+  ): Promise<{ value: T; created: boolean }> {
+    if (key === null || key === undefined) return { value: (await work()).value, created: true }
+    if (!IDEMPOTENCY_KEY.test(key)) throw new AgentError("invalid", "Idempotency-Key must be 1–200 of A-Z a-z 0-9 _ . : -")
+    const digest = bodyDigest(body)
+    const id = `${route}|${key}`
+    await this.prune(userID)
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const held = await this.state.get<Claim>(userID, ARTIFACT_IDEMPOTENCY, id)
+      const live = held && this.now() - held.value.at < IDEMPOTENCY_TTL_MS ? held.value : undefined
+      if (live) {
+        if (live.digest !== digest) throw new AgentError("conflict", `Idempotency-Key ${key} was used with a different body`, { hint: "Use a new key, or resend the original body" })
+        if (live.state === "done" && live.artifactID && live.revisionID) return { value: await replay({ artifactID: live.artifactID, revisionID: live.revisionID }), created: false }
+        if (this.now() - live.at < PENDING_MS) throw new AgentError("rate_limited", `The request with Idempotency-Key ${key} is still running`, { extra: { retryAfter: 1 } })
+        // Its writer crashed: take the key over.
+      }
+      const claim: Claim = { v: 1, digest, at: this.now(), state: "pending" }
+      const claimed = await this.state.put<Claim>(userID, ARTIFACT_IDEMPOTENCY, id, claim, { ifVersion: held?.version ?? 0 })
+      if (!claimed.ok) continue
+      let result: { ids: IdempotentResult; value: T }
+      try {
+        result = await work()
+      } catch (error) {
+        await this.state.delete(userID, ARTIFACT_IDEMPOTENCY, id, { ifVersion: claimed.version }).catch(() => {})
+        throw error
+      }
+      await this.state
+        .put<Claim>(userID, ARTIFACT_IDEMPOTENCY, id, { ...claim, state: "done", ...result.ids }, { ifVersion: claimed.version })
+        .catch(() => {})
+      return { value: result.value, created: true }
+    }
+    throw new AgentError("rate_limited", `Idempotency-Key ${key} is contended; retry`, { extra: { retryAfter: 1 } })
+  }
+
+  /** Drops expired keys, and the oldest ones past IDEMPOTENCY_KEYS_MAX. */
+  private async prune(userID: string): Promise<void> {
+    const entries = await this.state.list<Claim>(userID, ARTIFACT_IDEMPOTENCY)
+    const cutoff = this.now() - IDEMPOTENCY_TTL_MS
+    const live = entries.filter((e) => e.value.at >= cutoff)
+    for (const e of entries) if (e.value.at < cutoff) await this.state.delete(userID, ARTIFACT_IDEMPOTENCY, e.key, { ifVersion: e.version })
+    if (live.length < IDEMPOTENCY_KEYS_MAX) return
+    const oldest = live.filter((e) => e.value.state === "done").sort((a, b) => a.value.at - b.value.at)
+    for (const e of oldest.slice(0, live.length - IDEMPOTENCY_KEYS_MAX + 1)) await this.state.delete(userID, ARTIFACT_IDEMPOTENCY, e.key, { ifVersion: e.version })
+  }
+}