@huynle/hub 0.7.4 → 0.8.1

package/src/central/artifacts/routes.ts

@@ -0,0 +1,360 @@
+// The artifact transfer API (HWA-21; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Artifacts),
+// under /api/agent with the agent error envelope:
+//
+//   GET    /artifacts                                  the caller's library (limit, cursor, state, workspace)
+//   POST   /artifacts                                  create with the first revision (Idempotency-Key)
+//   POST   /artifacts/blobs                            stage raw bytes; answers a BlobRef to reference
+//   GET    /artifacts/:id                              one artifact
+//   PATCH  /artifacts/:id                              title, description, tags, metadata {expectedRevision}
+//   DELETE /artifacts/:id                              irreversible {expectedRevision}
+//   PUT    /artifacts/:id/visibility                   {expectedRevision, visibility, workspaceID?}
+//   POST   /artifacts/:id/archive | /unarchive         {expectedRevision}
+//   GET    /artifacts/:id/revisions                    newest first (limit, cursor)
+//   POST   /artifacts/:id/revisions                    {baseRevisionID, blobs|upload, entry?} (Idempotency-Key)
+//   GET    /artifacts/:id/revisions/:rev               one revision
+//   GET    /artifacts/:id/revisions/:rev/blobs/:hash   the bytes, as an attachment
+//
+// Files of a revision come two ways: `upload` carries small files inline in the JSON body (utf8 or base64, at most
+// ARTIFACT_UPLOAD_LIMITS.inlineBytes decoded in total), and `blobs` references bytes this user already stored:
+// staged with POST /artifacts/blobs (a raw, streamed body up to ARTIFACT_LIMITS.blobBytes) or unchanged files of an
+// earlier revision. So SDK and MCP callers pass references, never huge payloads. A staged blob nobody references is
+// collected by recovery once untouched for ARTIFACT_GRACE_MS (`referenceWithinMs` in the answer).
+//
+// Media types are the client's declaration, checked against ARTIFACT_MEDIA_TYPES and never sniffed. Downloads are
+// never rendered by the hub: Content-Disposition attachment, nosniff, a sandboxing CSP and no caching. Interactive
+// html/app content renders only in the isolated artifact host (HWA-26); src/central/assets.ts never serves it.
+//
+// Who: users (cookie, device token) everything; app tokens by scope (artifacts:read, artifacts:write); sessions may
+// read (the store admits workspace-visible artifacts of workspaces they currently belong to), create and stage
+// bytes, but never revise or manage (v1 write policy, enforced by the store's access policy). Another user's
+// records answer not_found. A hub without artifact storage (cluster mode before HWA-22) answers 422 unsupported.
+import { bodyError, boundedText, readBounded } from "../agent/body"
+import { ARTIFACT_LIMITS, ARTIFACT_MEDIA_TYPES, type ArtifactVisibility, type BlobRef, isBlobHash, isContractID, type RecordState } from "../../protocol"
+import type { AgentActor } from "../agent/actor"
+import { AgentError } from "../agent/errors"
+// Types only: ../agent/routes imports this module (a value import would be circular).
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import type { Clock, StateStore } from "../backend/types"
+import type { ArtifactPrincipal } from "./access"
+import { type BlobBody, BlobHashMismatchError, BlobInputError, BlobQuotaError, type BlobStore, BlobTooLargeError } from "./blob-store"
+import { ArtifactIdempotency } from "./idempotency"
+import { ARTIFACT_GRACE_MS, type ArtifactInput, type ArtifactStore, type RevisionFile, type RevisionInput } from "./store"
+
+export const ARTIFACT_UPLOAD_LIMITS = {
+  /** Decoded bytes of all inline (`upload`) files of one request. */
+  inlineBytes: 1024 * 1024,
+  /** A JSON request body. */
+  jsonBytes: 2 * 1024 * 1024,
+  /** A staged blob (the BlobStore's ceiling). */
+  blobBytes: ARTIFACT_LIMITS.blobBytes,
+  /** Staged uploads one user may stream at once (bounds temp disk use). */
+  uploadsInFlight: 4,
+} as const
+
+export interface ArtifactRouteDeps {
+  /** Absent: this hub keeps no artifacts (every route answers 422 unsupported). */
+  readonly artifacts?: ArtifactStore
+  /** The store's BlobStore (staged uploads write to it). */
+  readonly blobs?: BlobStore
+  /** Where Idempotency-Keys live. */
+  readonly state?: StateStore
+  readonly now?: Clock
+  /** Quota of staged uploads (default ARTIFACT_LIMITS.userBlobBytes; the store applies its own on publish). */
+  readonly userBlobBytes?: number
+}
+
+const P = "/api/agent/artifacts"
+const NO_STORE = { "cache-control": "no-store" }
+const READ = { session: true, scope: "artifacts:read" } as const
+const WRITE = { session: true, scope: "artifacts:write" } as const
+const MANAGE = { scope: "artifacts:write" } as const
+const CREATE_KEYS = new Set(["title", "kind", "description", "visibility", "workspaceID", "tags", "metadata", "entry", "blobs", "upload"])
+const REVISE_KEYS = new Set(["baseRevisionID", "entry", "blobs", "upload"])
+const FILE_KEYS = new Set(["path", "mediaType", "data", "encoding", "hash"])
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+const MEDIA_EXT: Readonly<Record<string, string>> = {
+  "text/markdown": ".md",
+  "text/plain": ".txt",
+  "text/csv": ".csv",
+  "text/html": ".html",
+  "text/css": ".css",
+  "text/javascript": ".js",
+  "application/json": ".json",
+  "application/pdf": ".pdf",
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/svg+xml": ".svg",
+}
+
+const invalid = (message: string) => new AgentError("invalid", message)
+const unsupported = () => new AgentError("unsupported", "This hub does not store artifacts", { extra: { feature: "artifacts" } })
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+const principalOf = (actor: AgentActor): ArtifactPrincipal => (actor.kind === "session" ? { kind: "session", sessionID: actor.sessionID } : { kind: "user" })
+
+/** Reads a JSON object body of at most `max` bytes (declared or streamed; agent/body.ts). */
+async function readJson(request: Request, max: number): Promise<Record<string, unknown>> {
+  const text = await boundedText(request, max)
+  let body: unknown
+  try {
+    body = JSON.parse(text)
+  } catch {
+    throw invalid("Invalid JSON")
+  }
+  if (!isObj(body)) throw invalid("Expected a JSON object")
+  return body
+}
+
+function onlyKeys(body: Record<string, unknown>, allowed: ReadonlySet<string>, what: string): void {
+  const extra = Object.keys(body).find((k) => !allowed.has(k))
+  if (extra !== undefined) throw invalid(`${what} has an unknown field ${JSON.stringify(extra.slice(0, 50))}`)
+}
+
+/** The files of a create/revise body: `blobs` references and decoded inline `upload` files (bounded). */
+function revisionInput(body: Record<string, unknown>): RevisionInput {
+  const files: RevisionFile[] = []
+  if (body.blobs !== undefined) {
+    if (!Array.isArray(body.blobs)) throw invalid("blobs must be a list of blob references")
+    for (const ref of body.blobs) {
+      if (!isObj(ref)) throw invalid("each blob must be {hash, bytes, mediaType, path?}")
+      const { hash, bytes, mediaType, path } = ref
+      files.push({ ref: { hash, bytes, mediaType, ...(path !== undefined ? { path } : {}) } as BlobRef })
+    }
+  }
+  if (body.upload !== undefined) {
+    if (!Array.isArray(body.upload)) throw invalid("upload must be a list of files")
+    let total = 0
+    for (const file of body.upload) {
+      if (!isObj(file)) throw invalid("each upload must be {mediaType, data, encoding?, path?, hash?}")
+      onlyKeys(file, FILE_KEYS, "an upload")
+      const { path, mediaType, data, encoding = "utf8", hash } = file
+      if (typeof mediaType !== "string") throw invalid("upload mediaType must be a string")
+      if (typeof data !== "string") throw invalid("upload data must be a string")
+      if (hash !== undefined && !isBlobHash(hash)) throw invalid("upload hash must be sha256:<64 hex>")
+      if (path !== undefined && typeof path !== "string") throw invalid("upload path must be a string")
+      let bytes: Uint8Array
+      if (encoding === "utf8") bytes = Buffer.from(data, "utf8")
+      else if (encoding === "base64") {
+        if (!BASE64.test(data)) throw invalid("upload data is not valid base64")
+        bytes = Buffer.from(data, "base64")
+      } else throw invalid("upload encoding must be utf8 or base64")
+      total += bytes.byteLength
+      if (total > ARTIFACT_UPLOAD_LIMITS.inlineBytes) {
+        throw invalid(`Inline uploads are limited to ${ARTIFACT_UPLOAD_LIMITS.inlineBytes} bytes per request; stage bigger files with POST ${P}/blobs`)
+      }
+      files.push({ body: bytes, mediaType, ...(path !== undefined ? { path } : {}), ...(hash !== undefined ? { expectedHash: hash } : {}) })
+    }
+  }
+  if (body.entry !== undefined && typeof body.entry !== "string") throw invalid("entry must be a path")
+  return { files, ...(body.entry !== undefined ? { entry: body.entry as string } : {}) }
+}
+
+/** A Content-Type's essence (`type/subtype`, lowercase, parameters dropped): the client's declaration, never sniffed. */
+function declaredMediaType(header: string | null): string {
+  const essence = (header ?? "").split(";")[0]!.trim().toLowerCase()
+  if (!(ARTIFACT_MEDIA_TYPES as readonly string[]).includes(essence)) {
+    throw new AgentError("invalid", "Content-Type must be an allowed artifact media type", { extra: { mediaTypes: ARTIFACT_MEDIA_TYPES } })
+  }
+  return essence
+}
+
+function mapBlobError(error: unknown): unknown {
+  if (error instanceof BlobQuotaError) return new AgentError("rate_limited", `Blob storage limit of ${error.quotaBytes} reached`, { extra: { limit: error.quotaBytes } })
+  if (error instanceof BlobTooLargeError || error instanceof BlobHashMismatchError || error instanceof BlobInputError) return invalid(error.message)
+  return error
+}
+
+function intParam(url: URL, key: string): number | undefined {
+  const raw = url.searchParams.get(key)
+  if (raw === null || raw === "") return undefined
+  if (!/^\d{1,6}$/.test(raw)) throw invalid(`${key} must be a whole number`)
+  return Number(raw)
+}
+
+function expectedRevision(body: Record<string, unknown>): number {
+  const value = body.expectedRevision
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw invalid("expectedRevision must be the revision you read")
+  return value
+}
+
+/** A download's file name: the bundle path's last segment (a restricted charset), else the hash and an extension. */
+function fileName(ref: BlobRef): string {
+  const base = ref.path?.split("/").pop()
+  return base && /^[A-Za-z0-9._-]{1,200}$/.test(base) ? base : `${ref.hash.slice("sha256:".length, "sha256:".length + 16)}${MEDIA_EXT[ref.mediaType] ?? ""}`
+}
+
+export function artifactRoutes(deps: ArtifactRouteDeps): AgentRoute[] {
+  const idempotency = deps.state ? new ArtifactIdempotency(deps.state, deps.now) : undefined
+  const inFlight = new Map<string, number>()
+  const store = (): ArtifactStore => {
+    if (!deps.artifacts) throw unsupported()
+    return deps.artifacts
+  }
+  const blobStore = (): BlobStore => {
+    if (!deps.artifacts || !deps.blobs) throw unsupported()
+    return deps.blobs
+  }
+  const json = (body: unknown, status = 200) => Response.json(body, { status, headers: NO_STORE })
+
+  const route = (method: string, path: string, allow: AgentRoute["allow"], handle: (c: AgentContext) => Promise<Response>): AgentRoute => ({ method, path, allow, handle })
+
+  /** Runs an idempotent create; `route` scopes the key. */
+  const idempotent = async (c: AgentContext, scope: string, body: unknown, work: () => Promise<{ artifact: { id: string }; revision: { id: string } }>) => {
+    const key = c.request.headers.get("idempotency-key")
+    // Keys are per principal as well as per user and route, so a replay answers only the caller that created the
+    // result (a session may not otherwise read what it created): the replay reads as the owner.
+    const principal = principalOf(c.actor)
+    const keyScope = `${scope}|${principal.kind === "session" ? principal.sessionID : "user"}`
+    const replay = async (ids: { artifactID: string; revisionID: string }) => {
+      const owner: ArtifactPrincipal = { kind: "user" }
+      return { artifact: await store().get(c.user.id, owner, ids.artifactID), revision: await store().getRevision(c.user.id, owner, ids.artifactID, ids.revisionID) }
+    }
+    const run = async () => {
+      const value = await work()
+      return { ids: { artifactID: value.artifact.id, revisionID: value.revision.id }, value }
+    }
+    if (key !== null && !idempotency) throw unsupported()
+    const result = idempotency ? await idempotency.run(c.user.id, keyScope, key, body, run, replay) : { value: (await run()).value, created: true }
+    return json(result.value, result.created ? 201 : 200)
+  }
+
+  return [
+    route("GET", P, READ, async ({ user, actor, url }) => {
+      const state = url.searchParams.get("state") ?? undefined
+      if (state !== undefined && state !== "active" && state !== "archived") throw invalid("state must be active or archived")
+      const limit = intParam(url, "limit")
+      const cursor = url.searchParams.get("cursor") ?? undefined
+      const workspaceID = url.searchParams.get("workspace") ?? undefined
+      const page = await store().list(user.id, principalOf(actor), {
+        ...(limit !== undefined ? { limit } : {}),
+        ...(cursor ? { cursor } : {}),
+        ...(state ? { state: state as RecordState } : {}),
+        ...(workspaceID ? { workspaceID } : {}),
+      })
+      return json(page)
+    }),
+
+    route("POST", P, WRITE, async (c) => {
+      store()
+      const body = await readJson(c.request, ARTIFACT_UPLOAD_LIMITS.jsonBytes)
+      onlyKeys(body, CREATE_KEYS, "The body")
+      const files = revisionInput(body)
+      const { blobs: _b, upload: _u, entry: _e, ...meta } = body
+      return idempotent(c, "create", body, () => store().create(c.user.id, principalOf(c.actor), meta as unknown as ArtifactInput, files))
+    }),
+
+    route("POST", `${P}/blobs`, WRITE, async ({ user, request }) => {
+      const blobs = blobStore()
+      const mediaType = declaredMediaType(request.headers.get("content-type"))
+      const expectedHash = request.headers.get("x-blob-hash") ?? undefined
+      if (expectedHash !== undefined && !isBlobHash(expectedHash)) throw invalid("X-Blob-Hash must be sha256:<64 hex>")
+      const running = inFlight.get(user.id) ?? 0
+      if (running >= ARTIFACT_UPLOAD_LIMITS.uploadsInFlight) {
+        throw new AgentError("rate_limited", `At most ${ARTIFACT_UPLOAD_LIMITS.uploadsInFlight} uploads at once`, { extra: { limit: ARTIFACT_UPLOAD_LIMITS.uploadsInFlight, retryAfter: 1 } })
+      }
+      inFlight.set(user.id, running + 1)
+      try {
+        // The whole body is read first, continuously, into memory bounded by the blob limit (agent/body.ts: bytes,
+        // rate and idle budgets; refused past the limit, with Connection: close when the rest is left on the
+        // socket), and only then handed to the store. Awaiting a disk write per chunk let Bun gather everything that
+        // arrived meanwhile into one chunk: an endless full-speed body grew the hub by gigabytes (HWA-28).
+        const max = ARTIFACT_UPLOAD_LIMITS.blobBytes
+        const read = await readBounded(request, max)
+        if (!read.ok) {
+          const refused = bodyError(read, max)
+          throw read.reason === "too_large" ? new AgentError("invalid", `A blob is at most ${max} bytes`, { ...refused.options }) : refused
+        }
+        const blob = await blobs
+          .put(user.id, read.bytes, mediaType, {
+            maxBytes: max,
+            quotaBytes: deps.userBlobBytes ?? ARTIFACT_LIMITS.userBlobBytes,
+            ...(expectedHash !== undefined ? { expectedHash } : {}),
+          })
+          .catch((error: unknown) => {
+            throw mapBlobError(error)
+          })
+        return json({ blob, referenceWithinMs: ARTIFACT_GRACE_MS }, 201)
+      } finally {
+        const left = (inFlight.get(user.id) ?? 1) - 1
+        if (left > 0) inFlight.set(user.id, left)
+        else inFlight.delete(user.id)
+      }
+    }),
+
+    route("GET", `${P}/:id`, READ, async ({ user, actor, params }) => json({ artifact: await store().get(user.id, principalOf(actor), params.id!) })),
+
+    route("PATCH", `${P}/:id`, MANAGE, async ({ user, actor, params, request }) => {
+      const body = await readJson(request, ARTIFACT_UPLOAD_LIMITS.jsonBytes)
+      onlyKeys(body, new Set(["expectedRevision", "title", "description", "tags", "metadata"]), "The body")
+      const artifact = await store().update(user.id, principalOf(actor), params.id!, { ...(body as object), expectedRevision: expectedRevision(body) } as Parameters<ArtifactStore["update"]>[3])
+      return json({ artifact })
+    }),
+
+    route("DELETE", `${P}/:id`, MANAGE, async ({ user, actor, params, request }) => {
+      const body = await readJson(request, 4096)
+      await store().delete(user.id, principalOf(actor), params.id!, expectedRevision(body))
+      return new Response(null, { status: 204, headers: NO_STORE })
+    }),
+
+    route("PUT", `${P}/:id/visibility`, MANAGE, async ({ user, actor, params, request }) => {
+      const body = await readJson(request, 4096)
+      onlyKeys(body, new Set(["expectedRevision", "visibility", "workspaceID"]), "The body")
+      if (body.workspaceID !== undefined && typeof body.workspaceID !== "string") throw invalid("workspaceID must be a workspace ID")
+      const artifact = await store().setVisibility(user.id, principalOf(actor), params.id!, {
+        expectedRevision: expectedRevision(body),
+        visibility: body.visibility as ArtifactVisibility,
+        ...(body.workspaceID !== undefined ? { workspaceID: body.workspaceID as string } : {}),
+      })
+      return json({ artifact })
+    }),
+
+    ...(["archive", "unarchive"] as const).map((verb) =>
+      route("POST", `${P}/:id/${verb}`, MANAGE, async ({ user, actor, params, request }) => {
+        const body = await readJson(request, 4096)
+        const artifact = await store()[verb](user.id, principalOf(actor), params.id!, expectedRevision(body))
+        return json({ artifact })
+      }),
+    ),
+
+    route("GET", `${P}/:id/revisions`, READ, async ({ user, actor, params, url }) => {
+      const limit = intParam(url, "limit")
+      const cursor = url.searchParams.get("cursor") ?? undefined
+      return json(await store().listRevisions(user.id, principalOf(actor), params.id!, { ...(limit !== undefined ? { limit } : {}), ...(cursor ? { cursor } : {}) }))
+    }),
+
+    route("POST", `${P}/:id/revisions`, WRITE, async (c) => {
+      store()
+      const body = await readJson(c.request, ARTIFACT_UPLOAD_LIMITS.jsonBytes)
+      onlyKeys(body, REVISE_KEYS, "The body")
+      const id = c.params.id!
+      if (!isContractID("artifact", id)) throw new AgentError("not_found", "No such artifact")
+      if (typeof body.baseRevisionID !== "string") throw invalid("baseRevisionID is required (the latest revision you read)")
+      const files = revisionInput(body)
+      return idempotent(c, `revise:${id}`, body, () => store().revise(c.user.id, principalOf(c.actor), id, { ...files, baseRevisionID: body.baseRevisionID as string }))
+    }),
+
+    route("GET", `${P}/:id/revisions/:rev`, READ, async ({ user, actor, params }) => json({ revision: await store().getRevision(user.id, principalOf(actor), params.id!, params.rev!) })),
+
+    route("GET", `${P}/:id/revisions/:rev/blobs/:hash`, READ, async ({ user, actor, params }) => {
+      const hash = params.hash!
+      if (!isBlobHash(hash)) throw new AgentError("not_found", "No such blob in this revision")
+      const { ref, blob } = await store().readBlob(user.id, principalOf(actor), params.id!, params.rev!, hash)
+      return new Response(blob.body, {
+        status: 200,
+        headers: {
+          "content-type": ref.mediaType,
+          "content-length": String(blob.bytes),
+          "content-disposition": `attachment; filename="${fileName(ref)}"`,
+          "x-content-type-options": "nosniff",
+          "content-security-policy": "default-src 'none'; sandbox",
+          "cross-origin-resource-policy": "same-origin",
+          "referrer-policy": "no-referrer",
+          "cache-control": "private, no-store",
+          etag: `"${ref.hash}"`,
+        },
+      })
+    }),
+  ]
+}