@huynle/hub 0.7.4 → 0.8.0

package/src/central/artifacts/workspaces.ts

@@ -0,0 +1,31 @@
+// The workspace facts artifact access needs (ArtifactWorkspaces, ./access.ts) from the HWA-03/04 stores: a
+// workspace of the user exists, and a session is a *current* member of it (re-read on every access, so leaving or
+// archiving the workspace ends a session's reads at once). Membership grants read of workspace-visible artifacts
+// only; it never grants writes (v1 write policy) and role labels confer nothing.
+import type { StateStore } from "../backend/types"
+import { MembershipStore } from "../workspaces/members"
+import { WorkspaceStore } from "../workspaces/store"
+import type { ArtifactWorkspaces } from "./access"
+
+export interface ArtifactWorkspaceSources {
+  readonly workspaces: Pick<WorkspaceStore, "get">
+  readonly members: Pick<MembershipStore, "membershipsOf">
+}
+
+export function artifactWorkspaces(sources: ArtifactWorkspaceSources): ArtifactWorkspaces {
+  return {
+    exists: async (userID, workspaceID) => (await sources.workspaces.get(userID, workspaceID)) !== undefined,
+    isCurrentMember: async (userID, workspaceID, sessionID) => (await sources.members.membershipsOf(userID, sessionID)).some((m) => m.workspaceID === workspaceID),
+  }
+}
+
+/**
+ * Read-only workspace facts straight from the StateStore, for a hub that has not wired the workspace routes'
+ * stores yet (HWA-06 passes its own). Only `get` and `membershipsOf` are ever called: machine ownership and
+ * session presence are not consulted for reads.
+ */
+export function artifactWorkspacesFromState(state: StateStore): ArtifactWorkspaces {
+  const workspaces = new WorkspaceStore({ state, ownsMachine: () => false })
+  const members = new MembershipStore({ state, workspaces, presence: () => "unknown" })
+  return artifactWorkspaces({ workspaces, members })
+}

package/src/central/backend/file-blobs.ts

@@ -0,0 +1,377 @@
+// BlobStore in files under the hub's state directory (HWA-21, decision tctkrik8): the standalone hub's artifact
+// bytes, the contract in ../artifacts/blob-store.ts (the shared suite in test/blob-store-conformance.ts).
+//
+// Layout (folders 0700, files 0600):
+//   <stateDir>/blobs/users/<user>/sha256/<ab>/<cd>/<64 hex>        the bytes (mtime = touchedAt)
+//   <stateDir>/blobs/users/<user>/sha256/<ab>/<cd>/<64 hex>.meta   {v, hash, bytes, storedAt}
+//   <stateDir>/blobs/users/<user>/tmp/<uuid>.tmp                   uploads in flight
+// Blobs are per user (the tenant key): the same bytes stored by two users are two files. <user> is the user ID when
+// it is a short lowercase [a-z0-9_-] name, else `~<sha256 of it>` (as the file StateStore does), so no ID becomes a
+// traversal. File names come only from validated hashes.
+//
+// Writes: the body streams into a fresh temp file (O_EXCL, O_NOFOLLOW), hashed and bounded as it comes
+// (readBlobBody); it is fsynced, then the sidecar is written (temp + rename), then the temp file is renamed into
+// place: the rename is the commit, so readers never see a partial blob. The quota check, the existence check and
+// the rename run in one synchronous step against the in-process index, so concurrent puts never overshoot the quota
+// and the same bytes stored concurrently become one blob. delete's touchedBefore check and the unlink are one
+// synchronous step too.
+//
+// The index (hash → bytes, storedAt, touchedAt per user) is built from disk on a user's first use: so a restart
+// recovers it. That scan also sweeps crash leftovers (temp files, sidecars without bytes) and ignores anything
+// that is not a regular file with a valid name (symlinks are never followed or indexed).
+//
+// Path defense: every folder from <stateDir>/blobs down is created and checked as a real directory (lstat, never
+// through a symlink), reads open with O_NOFOLLOW after checking that the blob's folder resolves to where it should,
+// and reads verify the sha256 of what they stream (bytes changed on disk fail the read instead of being served).
+//
+// One process owns a state directory (the standalone hub); a cluster keeps blobs in Postgres (HWA-22).
+import { createHash, randomUUID } from "node:crypto"
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  fsyncSync,
+  lstatSync,
+  lutimesSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs"
+import { open as openFile, type FileHandle } from "node:fs/promises"
+import path from "node:path"
+import { isBlobHash, type BlobRef, type Page } from "../../protocol"
+import {
+  type BlobBody,
+  type BlobDeleteOptions,
+  type BlobInfo,
+  type BlobListOptions,
+  type BlobPutOptions,
+  BlobQuotaError,
+  type BlobRead,
+  type BlobStore,
+  type BlobUsage,
+} from "../artifacts/blob-store"
+import { listCursor, listWindow, putLimits, readBlobBody } from "../artifacts/blob-support"
+import type { Clock } from "./types"
+
+/** The folder under the state directory. */
+export const BLOBS_DIR = "blobs"
+const READ_CHUNK = 64 * 1024
+const HEX = /^[0-9a-f]{64}$/
+const SAFE_SEGMENT = /^[a-z0-9_-]{1,64}$/
+
+export interface FileBlobStoreOptions {
+  /** The hub's state directory; blobs go to <stateDir>/blobs/. */
+  readonly stateDir: string
+  readonly now?: Clock
+}
+
+interface Indexed {
+  readonly bytes: number
+  readonly storedAt: number
+  touchedAt: number
+}
+
+interface UserIndex {
+  readonly dir: string
+  readonly blobs: Map<string, Indexed>
+  total: number
+}
+
+/** A file-system-safe, case-insensitive-safe folder name for a user ID. */
+const userSegment = (userID: string): string => (SAFE_SEGMENT.test(userID) ? userID : `~${createHash("sha256").update(userID).digest("hex")}`)
+const errno = (cause: unknown): string | undefined => (cause as NodeJS.ErrnoException | undefined)?.code
+
+export class FileBlobStore implements BlobStore {
+  private readonly now: Clock
+  private readonly root: string
+  private readonly users = new Map<string, UserIndex>()
+  /** Folders already restricted to the owner. */
+  private readonly restricted = new Set<string>()
+
+  constructor(options: FileBlobStoreOptions) {
+    this.now = options.now ?? Date.now
+    this.root = path.join(options.stateDir, BLOBS_DIR)
+  }
+
+  async put(userID: string, body: BlobBody, mediaType: string, options: BlobPutOptions = {}): Promise<BlobRef> {
+    const limits = putLimits(mediaType, options)
+    const user = this.user(userID)
+    const tmpDir = path.join(user.dir, "tmp")
+    this.folder(tmpDir)
+    const tmp = path.join(tmpDir, `${randomUUID()}.tmp`)
+    let handle: FileHandle | undefined = await openFile(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+    try {
+      const file = handle
+      const { hash, bytes } = await readBlobBody(body, limits, async (chunk) => {
+        for (let offset = 0; offset < chunk.byteLength; ) offset += (await file.write(chunk, offset)).bytesWritten
+      })
+      await file.sync()
+      await file.close()
+      handle = undefined
+      // The commit: one synchronous step from here (no await), so the index and the files agree.
+      const at = this.now()
+      const final = this.blobPath(user, hash)
+      if (this.refresh(user, hash, at)) {
+        rmSync(tmp, { force: true })
+      } else {
+        if (user.total + bytes > limits.quotaBytes) throw new BlobQuotaError(limits.quotaBytes, user.total)
+        const dir = path.dirname(final)
+        this.folder(dir)
+        const metaTmp = `${tmp}.meta`
+        writeFileSync(metaTmp, JSON.stringify({ v: 1, hash, bytes, storedAt: at }), { mode: 0o600, flag: "wx" })
+        renameSync(metaTmp, `${final}.meta`)
+        utimesSync(tmp, new Date(at), new Date(at))
+        renameSync(tmp, final)
+        syncFolder(dir)
+        user.blobs.set(hash, { bytes, storedAt: at, touchedAt: at })
+        user.total += bytes
+      }
+      return { hash, bytes, mediaType }
+    } catch (error) {
+      await handle?.close().catch(() => {})
+      rmSync(tmp, { force: true })
+      rmSync(`${tmp}.meta`, { force: true })
+      throw error
+    }
+  }
+
+  async get(userID: string, hash: string): Promise<BlobRead | undefined> {
+    const found = this.find(userID, hash)
+    if (!found) return undefined
+    const { user, blob } = found
+    const file = this.blobPath(user, hash)
+    if (!this.contained(path.dirname(file))) return undefined
+    let handle: FileHandle
+    try {
+      handle = await openFile(file, constants.O_RDONLY | constants.O_NOFOLLOW)
+    } catch {
+      return undefined
+    }
+    const stat = await handle.stat().catch(() => undefined)
+    if (!stat?.isFile()) {
+      await handle.close().catch(() => {})
+      return undefined
+    }
+    return { hash, bytes: blob.bytes, storedAt: blob.storedAt, touchedAt: blob.touchedAt, body: verifiedStream(handle, hash, blob.bytes) }
+  }
+
+  async stat(userID: string, hash: string): Promise<BlobInfo | undefined> {
+    const found = this.find(userID, hash)
+    return found && info(hash, found.blob)
+  }
+
+  async has(userID: string, hash: string): Promise<boolean> {
+    return this.find(userID, hash) !== undefined
+  }
+
+  async touch(userID: string, hash: string): Promise<boolean> {
+    const found = this.find(userID, hash)
+    return found !== undefined && this.refresh(found.user, hash, this.now())
+  }
+
+  async delete(userID: string, hash: string, options: BlobDeleteOptions = {}): Promise<boolean> {
+    const found = this.find(userID, hash)
+    if (!found) return false
+    if (options.touchedBefore !== undefined && found.blob.touchedAt >= options.touchedBefore) return false
+    const file = this.blobPath(found.user, hash)
+    rmSync(file, { force: true })
+    rmSync(`${file}.meta`, { force: true })
+    this.forget(found.user, hash)
+    return true
+  }
+
+  async usage(userID: string): Promise<BlobUsage> {
+    const user = this.user(userID)
+    return { blobs: user.blobs.size, bytes: user.total }
+  }
+
+  async list(userID: string, options: BlobListOptions = {}): Promise<Page<BlobInfo>> {
+    const { limit, after } = listWindow(options)
+    const user = this.user(userID)
+    const hashes = [...user.blobs.keys()].filter((h) => after === undefined || h > after).sort()
+    const page = hashes.slice(0, limit)
+    const items = page.map((h) => info(h, user.blobs.get(h)!))
+    return hashes.length > limit ? { items, cursor: listCursor(page[page.length - 1]!) } : { items }
+  }
+
+  // ---- internals ------------------------------------------------------------------------------------------
+
+  private find(userID: string, hash: string): { user: UserIndex; blob: Indexed } | undefined {
+    if (!isBlobHash(hash)) return undefined
+    const user = this.user(userID)
+    const blob = user.blobs.get(hash)
+    return blob && { user, blob }
+  }
+
+  private forget(user: UserIndex, hash: string): void {
+    const blob = user.blobs.get(hash)
+    if (!blob) return
+    user.blobs.delete(hash)
+    user.total -= blob.bytes
+  }
+
+  /** Sets an indexed blob's touchedAt (on disk: its mtime, never through a link); false (and forgotten) when its file is gone. */
+  private refresh(user: UserIndex, hash: string, at: number): boolean {
+    const blob = user.blobs.get(hash)
+    if (!blob) return false
+    try {
+      lutimesSync(this.blobPath(user, hash), new Date(at), new Date(at))
+    } catch (cause) {
+      if (errno(cause) !== "ENOENT") throw cause
+      this.forget(user, hash)
+      return false
+    }
+    blob.touchedAt = at
+    return true
+  }
+
+  private blobPath(user: UserIndex, hash: string): string {
+    const hex = hash.slice("sha256:".length)
+    return path.join(user.dir, "sha256", hex.slice(0, 2), hex.slice(2, 4), hex)
+  }
+
+  /** The user's index, built from disk on first use (sweeping crash leftovers). */
+  private user(userID: string): UserIndex {
+    const loaded = this.users.get(userID)
+    if (loaded) return loaded
+    const dir = path.join(this.root, "users", userSegment(userID))
+    const user: UserIndex = { dir, blobs: new Map(), total: 0 }
+    this.scan(user)
+    this.users.set(userID, user)
+    return user
+  }
+
+  private scan(user: UserIndex): void {
+    if (!isRealDir(user.dir) || !this.contained(user.dir)) return
+    const tmpDir = path.join(user.dir, "tmp")
+    if (isRealDir(tmpDir)) for (const name of readdirSync(tmpDir)) rmSync(path.join(tmpDir, name), { force: true, recursive: true })
+    const shaDir = path.join(user.dir, "sha256")
+    for (const ab of subfolders(shaDir)) {
+      for (const cd of subfolders(path.join(shaDir, ab))) {
+        const dir = path.join(shaDir, ab, cd)
+        const entries = readdirSync(dir, { withFileTypes: true })
+        const data = new Set(entries.filter((e) => e.isFile() && HEX.test(e.name) && e.name.startsWith(ab + cd)).map((e) => e.name))
+        for (const entry of entries) {
+          if (!entry.isFile() || !entry.name.endsWith(".meta")) continue
+          if (!data.has(entry.name.slice(0, -".meta".length))) rmSync(path.join(dir, entry.name), { force: true })
+        }
+        for (const hex of data) {
+          const file = path.join(dir, hex)
+          const stat = lstatSync(file, { throwIfNoEntry: false })
+          if (!stat?.isFile()) continue
+          const touchedAt = Math.round(stat.mtimeMs)
+          const storedAt = readStoredAt(`${file}.meta`, `sha256:${hex}`, stat.size) ?? touchedAt
+          user.blobs.set(`sha256:${hex}`, { bytes: stat.size, storedAt, touchedAt })
+          user.total += stat.size
+        }
+      }
+    }
+  }
+
+  /**
+   * Creates a folder (and its parents up to the root) restricted to the owner, checking every level as a real
+   * directory on every call (a folder swapped for a link later is caught, never written through).
+   */
+  private folder(dir: string): void {
+    if (dir !== this.root) this.folder(path.dirname(dir))
+    try {
+      mkdirSync(dir, { mode: 0o700, recursive: dir === this.root })
+    } catch (cause) {
+      if (errno(cause) !== "EEXIST") throw cause
+    }
+    if (!isRealDir(dir)) throw new Error(`${dir} is not a directory (refusing to follow a link)`)
+    if (this.restricted.has(dir)) return
+    chmodSync(dir, 0o700)
+    this.restricted.add(dir)
+  }
+
+  /** Whether a folder under the root resolves to itself (no symlinked folder on the way). */
+  private contained(dir: string): boolean {
+    try {
+      const root = realpathSync(this.root)
+      return realpathSync(dir) === path.join(root, path.relative(this.root, dir))
+    } catch {
+      return false
+    }
+  }
+}
+
+const info = (hash: string, blob: Indexed): BlobInfo => ({ hash, bytes: blob.bytes, storedAt: blob.storedAt, touchedAt: blob.touchedAt })
+
+function isRealDir(dir: string): boolean {
+  return lstatSync(dir, { throwIfNoEntry: false })?.isDirectory() === true
+}
+
+function subfolders(dir: string): string[] {
+  if (!isRealDir(dir)) return []
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && /^[0-9a-f]{2}$/.test(e.name))
+    .map((e) => e.name)
+}
+
+function readStoredAt(meta: string, hash: string, bytes: number): number | undefined {
+  try {
+    if (!lstatSync(meta).isFile()) return undefined
+    const raw = JSON.parse(readFileSync(meta, "utf8")) as Record<string, unknown>
+    return raw.v === 1 && raw.hash === hash && raw.bytes === bytes && typeof raw.storedAt === "number" ? raw.storedAt : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Makes a rename in a folder durable (best effort: some file systems refuse fsync on folders). */
+function syncFolder(dir: string): void {
+  let fd: number | undefined
+  try {
+    fd = openSync(dir, constants.O_RDONLY)
+    fsyncSync(fd)
+  } catch {
+    // best effort
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+/** The file's bytes as a stream that fails (instead of ending) when they are not the expected ones. */
+function verifiedStream(handle: FileHandle, hash: string, bytes: number): ReadableStream<Uint8Array> {
+  const hasher = createHash("sha256")
+  let read = 0
+  let closed = false
+  const close = async () => {
+    if (closed) return
+    closed = true
+    await handle.close().catch(() => {})
+  }
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const buffer = new Uint8Array(READ_CHUNK)
+        const { bytesRead } = await handle.read(buffer, 0, READ_CHUNK, null)
+        if (bytesRead > 0) {
+          read += bytesRead
+          if (read > bytes) throw new Error("blob is larger on disk than recorded")
+          const chunk = buffer.subarray(0, bytesRead)
+          hasher.update(chunk)
+          controller.enqueue(chunk)
+          return
+        }
+        await close()
+        if (read !== bytes || `sha256:${hasher.digest("hex")}` !== hash) throw new Error("blob bytes on disk do not match their hash")
+        controller.close()
+      } catch (cause) {
+        await close()
+        controller.error(cause)
+      }
+    },
+    async cancel() {
+      await close()
+    },
+  })
+}

package/src/central/backend/index.ts

@@ -2,7 +2,9 @@
 // a file StateStore under <stateDir>/agent, and the cluster bundle (Postgres + Valkey). startCentral creates the bundle its config selects (hubBackends:
 // file, or cluster when HUB_DATABASE_URL/HUB_VALKEY_URL are set) or takes one in its options, exposes it to
 // new code only, and flushes its state on stop.
+import { FileBlobStore } from "./file-blobs"
 import { FileStateStore, type FileStateStoreOptions } from "./file-state"
+import { MemoryBlobStore } from "./memory-blobs"
 import { MemoryBus } from "./memory-bus"
 import { MemoryCatalog } from "./memory-catalog"
 import { MemoryCounters, MemoryLocks } from "./memory-counters"
@@ -12,6 +14,7 @@ import { MemoryKv } from "./memory-kv"
 import { MemoryStateStore } from "./memory-state"
 import { randomUUID } from "node:crypto"
 import { RedisClient } from "bun"
+import { PostgresBlobStore } from "./postgres-blobs"
 import { PostgresStateStore } from "./postgres-state"
 import { ValkeyBus } from "./valkey-bus"
 import { ValkeyCatalog } from "./valkey-catalog"
@@ -43,6 +46,7 @@ export function memoryBackends(options: MemoryBackendsOptions = {}): Backends {
     locks: new MemoryLocks({ now }),
     catalog: new MemoryCatalog({ now }),
     kv: new MemoryKv({ now }),
+    blobs: new MemoryBlobStore({ now }),
   }
 }
 
@@ -52,7 +56,7 @@ export interface FileBackendsOptions extends MemoryBackendsOptions, Pick<FileSta
   readonly stateDir: string
 }
 
-/** The StateStore in files under the state directory, every other backend in process memory, on one clock. */
+/** The StateStore and artifact blobs in files under the state directory, every other backend in process memory, on one clock. */
 export function fileBackends(options: FileBackendsOptions): Backends {
   const { stateDir, debounceMs, warn, ...memory } = options
   const state = new FileStateStore({
@@ -62,7 +66,7 @@ export function fileBackends(options: FileBackendsOptions): Backends {
     ...(debounceMs !== undefined ? { debounceMs } : {}),
     ...(warn ? { warn } : {}),
   })
-  return { ...memoryBackends(memory), state }
+  return { ...memoryBackends(memory), state, blobs: new FileBlobStore({ stateDir, ...(memory.now ? { now: memory.now } : {}) }) }
 }
 
 export interface ClusterBackendsOptions extends MemoryBackendsOptions {
@@ -91,7 +95,10 @@ export function clusterBackends(options: ClusterBackendsOptions): Backends {
       client = undefined
     },
   } as unknown as RedisClient
-  const state = new PostgresStateStore({ url: cluster.databaseURL, ...(now ? { now } : {}) })
+  const timeout = cluster.statementTimeoutMs !== undefined ? { statementTimeoutMs: cluster.statementTimeoutMs } : {}
+  const state = new PostgresStateStore({ url: cluster.databaseURL, ...timeout, ...(now ? { now } : {}) })
+  // Artifact bytes in the same database (HWA-22, decision tctkrik8), on their own small pool.
+  const blobs = new PostgresBlobStore({ url: cluster.databaseURL, ...timeout, ...(now ? { now } : {}) })
   const bus = new ValkeyBus(cluster.valkeyURL, { instanceID: `${cluster.podID}-${randomUUID().slice(0, 8)}`, ...(options.timers ? { timers: options.timers } : {}) })
   return {
     state,
@@ -102,10 +109,12 @@ export function clusterBackends(options: ClusterBackendsOptions): Backends {
     locks: new ValkeyLocks(shared, now ? { now } : {}),
     catalog: new ValkeyCatalog(shared, now ? { now } : {}),
     kv: new ValkeyKv(shared),
+    blobs,
     async close() {
       bus.close()
       shared.close()
       await state.close()
+      await blobs.close()
     },
   }
 }

package/src/central/backend/memory-blobs.ts

@@ -0,0 +1,116 @@
+// BlobStore in process memory (tests, and the single-process hub until the file store (HWA-21) takes over): the
+// contract in ../artifacts/blob-store.ts. Bytes are copied in and out; a blob appears in the map only after its
+// whole body was read and verified, in one synchronous step that also checks the quota, so concurrent puts and
+// readers never see a partial blob and never overshoot the quota.
+import { isBlobHash, type BlobRef, type Page } from "../../protocol"
+import {
+  type BlobBody,
+  type BlobDeleteOptions,
+  type BlobInfo,
+  type BlobListOptions,
+  type BlobPutOptions,
+  BlobQuotaError,
+  type BlobRead,
+  type BlobStore,
+  type BlobUsage,
+} from "../artifacts/blob-store"
+import { listCursor, listWindow, putLimits, readBlobBody } from "../artifacts/blob-support"
+import type { Clock } from "./types"
+
+interface Stored {
+  readonly bytes: Uint8Array
+  readonly storedAt: number
+  touchedAt: number
+}
+
+export class MemoryBlobStore implements BlobStore {
+  private readonly now: Clock
+  /** userID → hash → blob. */
+  private readonly users = new Map<string, Map<string, Stored>>()
+
+  constructor(options: { now?: Clock } = {}) {
+    this.now = options.now ?? Date.now
+  }
+
+  async put(userID: string, body: BlobBody, mediaType: string, options: BlobPutOptions = {}): Promise<BlobRef> {
+    const limits = putLimits(mediaType, options)
+    const chunks: Uint8Array[] = []
+    const { hash, bytes } = await readBlobBody(body, limits, (chunk) => void chunks.push(chunk.slice()))
+    let blobs = this.users.get(userID)
+    const existing = blobs?.get(hash)
+    if (existing) {
+      existing.touchedAt = this.now()
+    } else {
+      const used = this.usedBytes(blobs)
+      if (used + bytes > limits.quotaBytes) throw new BlobQuotaError(limits.quotaBytes, used)
+      if (!blobs) this.users.set(userID, (blobs = new Map()))
+      const at = this.now()
+      blobs.set(hash, { bytes: Buffer.concat(chunks), storedAt: at, touchedAt: at })
+    }
+    return { hash, bytes, mediaType }
+  }
+
+  async get(userID: string, hash: string): Promise<BlobRead | undefined> {
+    const stored = this.find(userID, hash)
+    if (!stored) return undefined
+    const copy = stored.bytes.slice()
+    const body = new ReadableStream<Uint8Array>({
+      start(controller) {
+        if (copy.byteLength > 0) controller.enqueue(copy)
+        controller.close()
+      },
+    })
+    return { ...info(hash, stored), body }
+  }
+
+  async stat(userID: string, hash: string): Promise<BlobInfo | undefined> {
+    const stored = this.find(userID, hash)
+    return stored && info(hash, stored)
+  }
+
+  async has(userID: string, hash: string): Promise<boolean> {
+    return this.find(userID, hash) !== undefined
+  }
+
+  async touch(userID: string, hash: string): Promise<boolean> {
+    const stored = this.find(userID, hash)
+    if (!stored) return false
+    stored.touchedAt = this.now()
+    return true
+  }
+
+  async delete(userID: string, hash: string, options: BlobDeleteOptions = {}): Promise<boolean> {
+    const stored = this.find(userID, hash)
+    if (!stored) return false
+    if (options.touchedBefore !== undefined && stored.touchedAt >= options.touchedBefore) return false
+    const blobs = this.users.get(userID)!
+    blobs.delete(hash)
+    if (blobs.size === 0) this.users.delete(userID)
+    return true
+  }
+
+  async usage(userID: string): Promise<BlobUsage> {
+    const blobs = this.users.get(userID)
+    return { blobs: blobs?.size ?? 0, bytes: this.usedBytes(blobs) }
+  }
+
+  async list(userID: string, options: BlobListOptions = {}): Promise<Page<BlobInfo>> {
+    const { limit, after } = listWindow(options)
+    const hashes = [...(this.users.get(userID)?.keys() ?? [])].filter((h) => after === undefined || h > after).sort()
+    const page = hashes.slice(0, limit)
+    const items = page.map((h) => info(h, this.users.get(userID)!.get(h)!))
+    return hashes.length > limit ? { items, cursor: listCursor(page[page.length - 1]!) } : { items }
+  }
+
+  private find(userID: string, hash: string): Stored | undefined {
+    return isBlobHash(hash) ? this.users.get(userID)?.get(hash) : undefined
+  }
+
+  private usedBytes(blobs: Map<string, Stored> | undefined): number {
+    let used = 0
+    for (const stored of blobs?.values() ?? []) used += stored.bytes.byteLength
+    return used
+  }
+}
+
+const info = (hash: string, stored: Stored): BlobInfo => ({ hash, bytes: stored.bytes.byteLength, storedAt: stored.storedAt, touchedAt: stored.touchedAt })