@huynle/hub 0.7.4 → 0.8.1

package/src/central/artifacts/blob-store.ts

@@ -0,0 +1,113 @@
+// The BlobStore contract (HWA-20; docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Artifacts): artifact
+// bytes, content-addressed by sha256 and immutable, stored per user (the tenant key). Implementations: memory
+// (src/central/backend/memory-blobs.ts, tests and the single-process default), files under the hub data directory
+// (HWA-21) and a chunked Postgres table (HWA-22, decision tctkrik8). Every implementation passes the shared suite in
+// test/blob-store-conformance.ts.
+//
+// Rules every implementation keeps:
+// - Tenancy: a blob belongs to one user. Another user's hash answers like a missing one (no existence oracle), and
+//   usage is per user. The same bytes stored by two users are two blobs.
+// - put streams the body: it hashes as it reads, stops reading (and cancels the source) as soon as the body passes
+//   `maxBytes` (default and ceiling ARTIFACT_LIMITS.blobBytes), and stores nothing when the body is too large, its
+//   hash is not `expectedHash`, the media type is not in ARTIFACT_MEDIA_TYPES (never sniffed), or a new blob would
+//   take the user past `quotaBytes` (default ARTIFACT_LIMITS.userBlobBytes). Storing bytes that are already there
+//   stores nothing new, is never refused for quota, and refreshes `touchedAt`.
+// - A blob becomes visible to get/has/stat/list only once all its bytes are durably stored and verified
+//   (write-temp-then-rename, a committed transaction): readers never see a partial blob.
+// - Reference counting lives with the revisions (src/central/artifacts/store.ts), not here: the artifact store
+//   decides a blob is unreferenced and then calls delete with `touchedBefore`. delete refuses (false) a blob touched
+//   at or after that time, atomically with the removal, so a writer that touched a blob after the deleter read the
+//   references keeps it (see the publish protocol in store.ts).
+import type { BlobRef, Page } from "../../protocol"
+
+/** A blob body: whole bytes, a web stream, or any async iterable of chunks (read once). */
+export type BlobBody = Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>
+
+export interface BlobPutOptions {
+  /** `sha256:<hex>` the body must hash to; a mismatch stores nothing (BlobHashMismatchError). */
+  readonly expectedHash?: string
+  /** Largest body accepted (default and ceiling ARTIFACT_LIMITS.blobBytes). */
+  readonly maxBytes?: number
+  /** The user's total stored bytes a new blob may not exceed (default ARTIFACT_LIMITS.userBlobBytes). */
+  readonly quotaBytes?: number
+}
+
+/** A stored blob's facts (no media type: that belongs to the revision's BlobRef). */
+export interface BlobInfo {
+  readonly hash: string
+  readonly bytes: number
+  /** When the bytes were first stored. */
+  readonly storedAt: number
+  /** The latest put or touch of these bytes. */
+  readonly touchedAt: number
+}
+
+/** A blob being read: its facts and its bytes as a stream (read once). */
+export interface BlobRead extends BlobInfo {
+  readonly body: ReadableStream<Uint8Array>
+}
+
+export interface BlobUsage {
+  readonly blobs: number
+  readonly bytes: number
+}
+
+export interface BlobDeleteOptions {
+  /** Delete only when the blob's touchedAt is before this time (checked atomically with the delete). */
+  readonly touchedBefore?: number
+}
+
+export interface BlobListOptions {
+  /** 1–LIST_LIMIT_MAX (default LIST_LIMIT_DEFAULT). */
+  readonly limit?: number
+  /** The cursor of the previous page. */
+  readonly cursor?: string
+}
+
+export interface BlobStore {
+  /** Stores the body (see the rules above) and answers its reference with the given media type. */
+  put(userID: string, body: BlobBody, mediaType: string, options?: BlobPutOptions): Promise<BlobRef>
+  /** The blob's bytes; undefined when missing (or another user's, or a malformed hash). */
+  get(userID: string, hash: string): Promise<BlobRead | undefined>
+  stat(userID: string, hash: string): Promise<BlobInfo | undefined>
+  has(userID: string, hash: string): Promise<boolean>
+  /** Refreshes touchedAt; false when the blob is missing. */
+  touch(userID: string, hash: string): Promise<boolean>
+  /** Removes the blob; false when missing or (touchedBefore) touched at or after that time. */
+  delete(userID: string, hash: string, options?: BlobDeleteOptions): Promise<boolean>
+  usage(userID: string): Promise<BlobUsage>
+  /** The user's blobs by hash, paged (orphan recovery walks it). */
+  list(userID: string, options?: BlobListOptions): Promise<Page<BlobInfo>>
+}
+
+/** A request the store refuses as malformed: a media type, maxBytes, limit or cursor. Maps to 400 invalid. */
+export class BlobInputError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "BlobInputError"
+  }
+}
+
+/** The body passed maxBytes; nothing was stored. Maps to 400 invalid. */
+export class BlobTooLargeError extends Error {
+  constructor(readonly maxBytes: number) {
+    super(`blob is larger than ${maxBytes} bytes`)
+    this.name = "BlobTooLargeError"
+  }
+}
+
+/** The body did not hash to expectedHash; nothing was stored. Maps to 400 invalid. */
+export class BlobHashMismatchError extends Error {
+  constructor(readonly expected: string, readonly actual: string) {
+    super(`blob hashes to ${actual}, not ${expected}`)
+    this.name = "BlobHashMismatchError"
+  }
+}
+
+/** A new blob would take the user past their quota; nothing was stored. Maps to 429 rate_limited (a user cap). */
+export class BlobQuotaError extends Error {
+  constructor(readonly quotaBytes: number, readonly usedBytes: number) {
+    super(`blob storage quota of ${quotaBytes} bytes reached`)
+    this.name = "BlobQuotaError"
+  }
+}

package/src/central/artifacts/blob-support.ts

@@ -0,0 +1,98 @@
+// Helpers every BlobStore implementation shares (memory, files HWA-21, Postgres HWA-22): option checks, the
+// bounded hashing body reader, and the list cursor. Keeping them here keeps the implementations alike.
+import { ARTIFACT_LIMITS, ARTIFACT_MEDIA_TYPES, isBlobHash, LIST_LIMIT_DEFAULT, LIST_LIMIT_MAX } from "../../protocol"
+import { type BlobBody, BlobHashMismatchError, BlobInputError, type BlobListOptions, type BlobPutOptions, BlobTooLargeError } from "./blob-store"
+
+export interface PutLimits {
+  readonly maxBytes: number
+  readonly quotaBytes: number
+  readonly expectedHash?: string
+}
+
+/** Checks put's media type and options (BlobInputError) and answers the limits in force. */
+export function putLimits(mediaType: string, options: BlobPutOptions = {}): PutLimits {
+  if (!(ARTIFACT_MEDIA_TYPES as readonly string[]).includes(mediaType)) throw new BlobInputError("mediaType is not allowed")
+  const maxBytes = options.maxBytes ?? ARTIFACT_LIMITS.blobBytes
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > ARTIFACT_LIMITS.blobBytes) {
+    throw new BlobInputError(`maxBytes must be 0–${ARTIFACT_LIMITS.blobBytes}`)
+  }
+  const quotaBytes = options.quotaBytes ?? ARTIFACT_LIMITS.userBlobBytes
+  if (!Number.isSafeInteger(quotaBytes) || quotaBytes < 0) throw new BlobInputError("quotaBytes must be a non-negative integer")
+  if (options.expectedHash !== undefined && !isBlobHash(options.expectedHash)) throw new BlobInputError("expectedHash must be sha256:<64 hex>")
+  return { maxBytes, quotaBytes, ...(options.expectedHash !== undefined ? { expectedHash: options.expectedHash } : {}) }
+}
+
+/**
+ * Reads the body once, handing each chunk to `sink` as it comes, hashing and counting it. Stops reading and
+ * cancels the source as soon as the body passes maxBytes (BlobTooLargeError), and checks expectedHash at the end
+ * (BlobHashMismatchError). The caller discards what the sink got when this throws.
+ */
+export async function readBlobBody(
+  body: BlobBody,
+  limits: PutLimits,
+  sink: (chunk: Uint8Array) => void | Promise<void>,
+): Promise<{ hash: string; bytes: number }> {
+  const hasher = new Bun.CryptoHasher("sha256")
+  let bytes = 0
+  const take = async (chunk: Uint8Array): Promise<boolean> => {
+    if (!(chunk instanceof Uint8Array)) throw new BlobInputError("blob chunks must be bytes")
+    bytes += chunk.byteLength
+    if (bytes > limits.maxBytes) return false
+    hasher.update(chunk)
+    await sink(chunk)
+    return true
+  }
+  if (body instanceof Uint8Array) {
+    if (!(await take(body))) throw new BlobTooLargeError(limits.maxBytes)
+  } else if (body instanceof ReadableStream) {
+    const reader = body.getReader()
+    try {
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        if (!(await take(value))) {
+          await reader.cancel().catch(() => {})
+          throw new BlobTooLargeError(limits.maxBytes)
+        }
+      }
+    } finally {
+      // Bun 1.3 can throw from releaseLock() on a finished body reader after other I/O (quirk tfxrxuta).
+      try {
+        reader.releaseLock()
+      } catch {
+        // best effort
+      }
+    }
+  } else {
+    const iterator = body[Symbol.asyncIterator]()
+    for (;;) {
+      const { done, value } = await iterator.next()
+      if (done) break
+      if (!(await take(value))) {
+        await iterator.return?.()
+        throw new BlobTooLargeError(limits.maxBytes)
+      }
+    }
+  }
+  const hash = `sha256:${hasher.digest("hex")}`
+  if (limits.expectedHash !== undefined && limits.expectedHash !== hash) throw new BlobHashMismatchError(limits.expectedHash, hash)
+  return { hash, bytes }
+}
+
+/** A list request's limit and the hash after which the page starts (BlobInputError on bad ones). */
+export function listWindow(options: BlobListOptions = {}): { limit: number; after?: string } {
+  const limit = options.limit ?? LIST_LIMIT_DEFAULT
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new BlobInputError(`limit must be 1–${LIST_LIMIT_MAX}`)
+  if (options.cursor === undefined) return { limit }
+  let after: string
+  try {
+    after = Buffer.from(options.cursor, "base64url").toString("utf8")
+  } catch {
+    throw new BlobInputError("cursor is not valid")
+  }
+  if (!isBlobHash(after)) throw new BlobInputError("cursor is not valid")
+  return { limit, after }
+}
+
+/** The cursor that continues a list after `hash`. */
+export const listCursor = (hash: string): string => Buffer.from(hash, "utf8").toString("base64url")

package/src/central/artifacts/events.ts

@@ -0,0 +1,27 @@
+// Artifact events for the canonical agent journal (HWA-21; contract: Cross-cutting rules, Events). The store's
+// onEvent hook gives compact events; this maps them to journal input in the `artifact` family (read with
+// artifacts:read). Payloads are IDs, kinds, revisions and counts only: never titles, descriptions or content.
+import type { ArtifactEvent } from "./store"
+
+/** Journal input of an artifact event (an EventInput of family "artifact"). */
+export interface ArtifactJournalInput {
+  readonly type: ArtifactEvent["type"]
+  readonly family: "artifact"
+  readonly subject: { readonly artifactID: string }
+  readonly data: Readonly<Record<string, string | number>>
+}
+
+export function artifactJournalEvent(event: ArtifactEvent): ArtifactJournalInput {
+  return {
+    type: event.type,
+    family: "artifact",
+    subject: { artifactID: event.artifactID },
+    data: {
+      kind: event.kind,
+      revision: event.revision,
+      ...(event.revisionID !== undefined ? { revisionID: event.revisionID } : {}),
+      ...(event.number !== undefined ? { number: event.number } : {}),
+      ...(event.state !== undefined ? { state: event.state } : {}),
+    },
+  }
+}

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
+  }
+}