threadwire 0.1.5 → 0.1.8

package/src/evidence-store.js

@@ -0,0 +1,1472 @@
+// @ts-check
+
+import {createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual} from "node:crypto"
+import {spawnSync} from "node:child_process"
+import {constants as fsConstants} from "node:fs"
+import {mkdir, open, readdir, rename, unlink} from "node:fs/promises"
+import {basename, isAbsolute, join, parse, relative} from "node:path"
+import {StringDecoder} from "node:string_decoder"
+
+const HANDLE_PATTERN = /^evidence_([A-Za-z0-9_-]{43})$/u
+const META_SUFFIX = ".meta.json"
+const PAYLOAD_SUFFIX = ".payload"
+const PENDING_SUFFIX = ".pending"
+const LOCK_FILE = ".threadwire-evidence.lock"
+const ROOT_MARKER = ".threadwire-evidence-root.json"
+const FLOCK = "/usr/bin/flock"
+const ARTIFACT_DIRECTORY_OVERHEAD = 768
+/** @type {EvidenceLimits} */
+const DEFAULT_LIMITS = Object.freeze({
+  maxEventBytes: 1_048_576,
+  maxArtifactBytes: 64 * 1_048_576,
+  maxArtifactEvents: 100_000,
+  maxRunBytes: 128 * 1_048_576,
+  maxRunEvents: 200_000,
+  maxStoreBytes: 1024 * 1_048_576,
+  maxStoreEvents: 1_000_000,
+  maxArtifacts: 10_000,
+  maxReadBytes: 64 * 1024,
+  maxReadLines: 1_000,
+  retentionMs: 7 * 24 * 60 * 60 * 1000
+})
+const TEXT_CONTENT_TYPES = new Set(["application/json", "application/x-ndjson"])
+
+export class EvidenceAccessError extends Error {
+  constructor() {
+    super("Evidence artifact is unavailable")
+    this.name = "EvidenceAccessError"
+  }
+}
+
+export class EvidenceCapacityError extends Error {
+  /** @param {string} message */
+  constructor(message = "Evidence capacity exceeded") {
+    super(message)
+    this.name = "EvidenceCapacityError"
+  }
+}
+
+export class EvidenceStore {
+  /**
+   * @param {string} root
+   * @param {import("node:fs/promises").FileHandle} rootHandle
+   * @param {{dev: bigint, ino: bigint}} rootIdentity
+   * @param {import("node:fs/promises").FileHandle} lease
+   * @param {EvidenceLimits} limits
+   * @param {number} baseBytes
+   * @param {() => number} clock
+   * @param {string[]} runtimeRedactions
+   * @param {(point: string) => void | Promise<void>} durabilityObserver
+   */
+  constructor(root, rootHandle, rootIdentity, lease, limits, baseBytes, clock, runtimeRedactions, durabilityObserver) {
+    this.root = root
+    this.rootHandle = rootHandle
+    this.rootIdentity = rootIdentity
+    this.lease = lease
+    this.closed = false
+    this.closing = false
+    /** @type {Promise<void> | undefined} */
+    this.closePromise = undefined
+    this.activeOperations = 0
+    /** @type {(() => void)[]} */
+    this.operationWaiters = []
+    this.limits = limits
+    this.clock = clock
+    this.runtimeRedactions = runtimeRedactions
+    this.durabilityObserver = durabilityObserver
+    /** @type {Map<string, EvidenceMetadata>} */
+    this.artifacts = new Map()
+    /** @type {Map<string, string>} */
+    this.capabilities = new Map()
+    /** @type {WeakSet<object>} */
+    this.scopes = new WeakSet()
+    /** @type {Map<string, Set<string>>} */
+    this.redactions = new Map()
+    /** @type {Map<string, number>} */
+    this.activeReaders = new Map()
+    this.storeBytes = baseBytes
+    this.storeEvents = 0
+    this.artifactSlots = 0
+    /** @type {Promise<unknown>} */
+    this.maintenance = Promise.resolve()
+    /** @type {Map<string, {bytes: number, events: number}>} */
+    this.runs = new Map()
+  }
+
+  /**
+   * @param {{root: string, limits?: Partial<EvidenceLimits>, clock?: () => number, redactions?: string[], durabilityObserver?: (point: string) => void | Promise<void>}} options
+   */
+  static async open(options) {
+    if (process.platform !== "linux" || !process.getuid) throw new Error("Secure evidence root is supported only on Linux")
+    const limits = validateLimits({...DEFAULT_LIMITS, ...options.limits})
+    const rootHandle = await openSecureRoot(options.root, options.durabilityObserver)
+    try {
+      const rootStats = await rootHandle.stat({bigint: true})
+      if (!rootStats.isDirectory() || rootStats.uid !== BigInt(process.getuid()) || (rootStats.mode & 0o777n) !== 0o700n) {
+        throw new Error("Secure evidence root must be an owned 0700 directory")
+      }
+      const pinnedRoot = `/proc/self/fd/${rootHandle.fd}`
+      await proveDedicatedRoot(pinnedRoot)
+      await options.durabilityObserver?.("root-pinned-before-lease")
+      const lease = await acquireLease(pinnedRoot)
+      const baseBytes = await storeBaseReservation(pinnedRoot)
+      if (baseBytes > limits.maxStoreBytes) {
+        await lease.close()
+        throw new EvidenceCapacityError()
+      }
+      const store = new EvidenceStore(
+        pinnedRoot,
+        rootHandle,
+        {dev: rootStats.dev, ino: rootStats.ino},
+        lease,
+        limits,
+        baseBytes,
+        options.clock ?? Date.now,
+        validateRedactions(options.redactions ?? []),
+        options.durabilityObserver ?? (() => {})
+      )
+      try {
+        await store.reconcile()
+        return store
+      } catch (error) {
+        await store.close().catch(() => {})
+        throw error
+      }
+    } catch (error) {
+      await rootHandle.close().catch(() => {})
+      throw error
+    }
+  }
+
+  async close() {
+    if (this.closed) return
+    if (this.closePromise !== undefined) return this.closePromise
+    this.closing = true
+    this.closePromise = this.finishClose()
+    return this.closePromise
+  }
+
+  async finishClose() {
+    await this.maintenance
+    if (this.activeOperations > 0) await new Promise((resolve) => this.operationWaiters.push(() => resolve(undefined)))
+    await this.assertPinnedRoot()
+    await this.lease.close()
+    this.closed = true
+    await this.rootHandle.close()
+  }
+
+  async assertRootIdentity() {
+    if (this.closed || this.closing) throw new Error("Evidence store is closed")
+    await this.assertPinnedRoot()
+  }
+
+  async assertPinnedRoot() {
+    const stats = await this.rootHandle.stat({bigint: true})
+    if (!stats.isDirectory() || stats.dev !== this.rootIdentity.dev || stats.ino !== this.rootIdentity.ino) {
+      throw new Error("Secure evidence root identity changed")
+    }
+  }
+
+  /** @param {{destinationId: string, runId: string}} identity */
+  createOwnerScope(identity) {
+    if (!validIdentity(identity.destinationId) || !validIdentity(identity.runId)) throw new Error("Invalid trusted evidence owner identity")
+    const scope = Object.freeze({destinationId: identity.destinationId, runId: identity.runId})
+    this.scopes.add(scope)
+    return scope
+  }
+
+  /**
+   * @param {{destinationId: string, runId: string}} owner
+   * @param {{contentType: string, redactions?: string[]}} options
+   */
+  async createArtifact(owner, options) {
+    this.assertScope(owner)
+    const contentType = validateContentType(options.contentType)
+    const redactions = [...this.runtimeRedactions, ...validateRedactions(options.redactions ?? [])]
+    const id = randomBytes(32).toString("base64url")
+    const handle = `evidence_${randomBytes(32).toString("base64url")}`
+    const now = this.clock()
+    const metadata = /** @type {EvidenceMetadata} */ ({
+      version: 2, id, state: "pending", owner: {...owner}, contentType,
+      capabilityHash: capabilityHash(handle),
+      policyVersion: 1, framingVersion: 1,
+      redactionPolicy: {algorithm: "aes-256-gcm", nonce: "", ciphertext: "", tag: ""},
+      payloadCommitment: "A".repeat(43),
+      bytes: 0, storedBytes: 0, lines: 0, events: 0, createdAt: now, expiresAt: now + this.limits.retentionMs
+    })
+    metadata.redactionPolicy = encryptRedactions(handle, redactions, metadata)
+    const overheadBytes = durableArtifactReservation(metadata)
+    const finishOperation = this.beginOperation()
+    if (this.artifactSlots >= this.limits.maxArtifacts) {
+      finishOperation()
+      throw new EvidenceCapacityError("Evidence artifact count exceeded")
+    }
+    try {
+      this.reserve(metadata.owner.runId, overheadBytes, 0)
+    } catch (error) {
+      finishOperation()
+      throw error
+    }
+    metadata.reservedBytes = overheadBytes
+    // JavaScript runs through here without yielding: reserve the slot before
+    // the first await so concurrent creations observe this pending artifact.
+    this.artifactSlots += 1
+    /** @type {import("node:fs/promises").FileHandle | undefined} */
+    let file
+    try {
+      await atomicJson(this.root, `${id}${META_SUFFIX}`, metadata)
+      await this.durabilityObserver("pending-metadata-durable")
+      file = await open(this.path(id, PENDING_SUFFIX), "wx", 0o600)
+      await this.durabilityObserver("pending-payload-open")
+    } catch (error) {
+      await file?.close().catch(() => {})
+      await safeUnlink(this.path(id, PENDING_SUFFIX))
+      await safeUnlink(this.path(id, META_SUFFIX))
+      this.reserve(metadata.owner.runId, -overheadBytes, 0)
+      this.artifactSlots -= 1
+      finishOperation()
+      throw error
+    }
+    if (!file) throw new Error("Evidence pending payload is unavailable")
+    this.artifacts.set(id, metadata)
+    this.capabilities.set(metadata.capabilityHash, id)
+    this.redactions.set(id, new Set(redactions))
+    return new EvidenceWriter(this, metadata, file, handle, finishOperation, redactions, owner)
+  }
+
+  /** @param {object} owner @param {unknown} request */
+  async read(owner, request) {
+    this.assertScope(owner)
+    const validated = validateEvidenceReadRequest(request, this.limits)
+    const finishOperation = this.beginOperation()
+    const id = this.lookupCapability(validated.handle)
+    if (!id) {
+      finishOperation()
+      throw new EvidenceAccessError()
+    }
+    this.activeReaders.set(id, (this.activeReaders.get(id) ?? 0) + 1)
+    try {
+      const metadata = this.artifacts.get(id)
+      if (!metadata || metadata.state !== "ready" || metadata.expiresAt <= this.clock() || !sameOwner(metadata.owner, owner)) {
+        throw new EvidenceAccessError()
+      }
+      const payloadPath = this.path(id, PAYLOAD_SUFFIX)
+      const file = await open(payloadPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW).catch(() => { throw new EvidenceAccessError() })
+      let selected
+      let redacted = false
+      let truncated = false
+      try {
+        const payloadStats = await file.stat()
+        if (
+          !payloadStats.isFile() || payloadStats.nlink !== 1 || payloadStats.size !== metadata.storedBytes
+        || process.getuid?.() !== payloadStats.uid || (payloadStats.mode & 0o777) !== 0o600
+        ) throw new EvidenceAccessError()
+        const payloadMac = createHmac("sha256", payloadKey(validated.handle))
+        const events = framedChunks(file, payloadStats.size, this.limits.maxEventBytes, payloadMac)
+        const secrets = decryptRedactions(validated.handle, metadata.redactionPolicy, metadata)
+        const chunks = isText(metadata.contentType)
+          ? redactedChunks(events, secrets)
+          : redactedBinaryChunks(events, secrets)
+        const selection = await selectChunks(chunks, validated, this.limits.maxReadBytes)
+        const expected = Buffer.from(metadata.payloadCommitment, "base64url")
+        const actual = payloadMac.digest()
+        if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) throw new EvidenceAccessError()
+        selected = selection.data
+        redacted = selection.redacted
+        truncated = selection.truncated
+      } finally {
+        await file.close()
+      }
+      if (!isText(metadata.contentType)) {
+        const binary = selected.subarray(0, Math.min(selected.length, this.limits.maxReadBytes))
+        return fitSerializedResult({
+          contentType: metadata.contentType,
+          data: binary.toString("base64"),
+          encoding: "base64",
+          redacted,
+          truncated: truncated || binary.length < selected.length
+        }, this.limits.maxReadBytes)
+      }
+      return fitSerializedResult({
+        contentType: metadata.contentType,
+        data: decodeUtf8(selected),
+        redacted,
+        truncated
+      }, this.limits.maxReadBytes)
+    } finally {
+      const readers = (this.activeReaders.get(id) ?? 1) - 1
+      if (readers === 0) this.activeReaders.delete(id)
+      else this.activeReaders.set(id, readers)
+      finishOperation()
+    }
+  }
+
+  /** @param {unknown} request */
+  async readBearer(request) {
+    const validated = validateEvidenceReadRequest(request, this.limits)
+    const id = this.lookupCapability(validated.handle)
+    if (!id) throw new EvidenceAccessError()
+    const metadata = this.artifacts.get(id)
+    if (!metadata) throw new EvidenceAccessError()
+    const owner = Object.freeze({...metadata.owner})
+    this.scopes.add(owner)
+    try {
+      return await this.read(owner, validated)
+    } finally {
+      this.scopes.delete(owner)
+    }
+  }
+
+  /** @param {{chatId: string, threadId: number | null, senderId: string}} requester @param {unknown} request */
+  async readTelegram(requester, request) {
+    const validated = validateEvidenceReadRequest(request, this.limits)
+    const id = this.lookupCapability(validated.handle)
+    if (!id) throw new EvidenceAccessError()
+    const metadata = this.artifacts.get(id)
+    if (!metadata || metadata.owner.destinationId !== evidenceTelegramDestination(requester, requester.senderId)) throw new EvidenceAccessError()
+    const owner = Object.freeze({...metadata.owner})
+    this.scopes.add(owner)
+    try {
+      return await this.read(owner, validated)
+    } finally {
+      this.scopes.delete(owner)
+    }
+  }
+
+  cleanup() {
+    const finish = this.beginOperation()
+    return this.enqueueMaintenance(() => this.cleanupOnce()).finally(finish)
+  }
+
+  async cleanupOnce() {
+    await this.assertRootIdentity()
+    const now = this.clock()
+    for (const [id, metadata] of [...this.artifacts]) {
+      if (metadata.state !== "ready" || metadata.expiresAt > now) continue
+      if ((this.activeReaders.get(id) ?? 0) > 0) continue
+      await safeUnlink(this.path(id, PAYLOAD_SUFFIX))
+      await safeUnlink(this.path(id, META_SUFFIX))
+      await syncDirectory(this.root)
+      metadata.state = "expired"
+      this.artifacts.delete(id)
+      this.capabilities.delete(metadata.capabilityHash)
+      this.release(metadata)
+      this.artifactSlots -= 1
+      this.redactions.delete(id)
+    }
+  }
+
+  /** @param {object} owner @param {string} handle */
+  remove(owner, handle) {
+    const finish = this.beginOperation()
+    return this.enqueueMaintenance(() => this.removeOnce(owner, handle)).finally(finish)
+  }
+
+  /** @param {object} owner @param {string} handle */
+  async removeOnce(owner, handle) {
+    await this.assertRootIdentity()
+    this.assertScope(owner)
+    const id = this.lookupCapability(handle)
+    if (!id) throw new EvidenceAccessError()
+    const metadata = this.artifacts.get(id)
+    if (!metadata || metadata.state !== "ready" || !sameOwner(metadata.owner, owner)) throw new EvidenceAccessError()
+    if ((this.activeReaders.get(id) ?? 0) > 0) throw new Error("Evidence artifact is busy")
+    await safeUnlink(this.path(id, PAYLOAD_SUFFIX))
+    await safeUnlink(this.path(id, META_SUFFIX))
+    await syncDirectory(this.root)
+    metadata.state = "removed"
+    this.artifacts.delete(id)
+    this.capabilities.delete(metadata.capabilityHash)
+    this.release(metadata)
+    this.artifactSlots -= 1
+    this.redactions.delete(id)
+  }
+
+  /** @template T @param {() => Promise<T>} operation @returns {Promise<T>} */
+  enqueueMaintenance(operation) {
+    const result = this.maintenance.then(operation)
+    this.maintenance = result.catch(() => {})
+    return result
+  }
+
+  /** @param {string} handle */
+  async inspectFilesForTest(handle) {
+    const id = this.lookupCapability(handle)
+    if (!id) throw new EvidenceAccessError()
+    return {payload: this.path(id, PAYLOAD_SUFFIX), metadata: this.path(id, META_SUFFIX)}
+  }
+
+  async reconcile() {
+    await this.assertPinnedRoot()
+    const names = await readdir(this.root)
+    const candidates = new Map()
+    const abandonedTemps = []
+    for (const name of names) {
+      const match = /^([A-Za-z0-9_-]{43})(\.meta\.json|\.payload|\.pending)$/u.exec(name)
+      if (name === LOCK_FILE || name === ROOT_MARKER) continue
+      if (/^\.(?:[A-Za-z0-9_-]{43}\.meta\.json|\.threadwire-evidence-root\.json)\.[a-f0-9]{24}\.tmp$/u.test(name)) {
+        abandonedTemps.push(name)
+        continue
+      }
+      if (!match) {
+        throw new Error("Evidence store contains an unknown entry")
+      }
+      const id = match[1]
+      const suffix = match[2]
+      if (id === undefined || suffix === undefined) continue
+      const group = candidates.get(id) ?? new Set()
+      group.add(suffix)
+      candidates.set(id, group)
+    }
+    for (const name of abandonedTemps) await safeUnlink(join(this.root, basename(name)))
+    for (const [id, files] of candidates) {
+      let metadata
+      try {
+        const metaStats = await safeRegularFile(this.path(id, META_SUFFIX))
+        if (!metaStats || metaStats.nlink !== 1) throw new Error("invalid")
+        metadata = await readBoundedJson(this.path(id, META_SUFFIX), 512 * 1024)
+        if (!validMetadata(metadata, id, this.limits) || metadata.state !== "ready" || metadata.expiresAt <= this.clock()) throw new Error("invalid")
+        const payloadStats = await safeRegularFile(this.path(id, PAYLOAD_SUFFIX))
+        if (!payloadStats || payloadStats.nlink !== 1 || payloadStats.size !== metadata.storedBytes || files.has(PENDING_SUFFIX)) throw new Error("invalid")
+        const counters = await inspectFramedPayload(this.path(id, PAYLOAD_SUFFIX), payloadStats.size, this.limits.maxEventBytes)
+        if (counters.bytes !== metadata.bytes || counters.lines !== metadata.lines || counters.events !== metadata.events) throw new Error("invalid")
+        if (this.artifactSlots >= this.limits.maxArtifacts) throw new EvidenceCapacityError()
+        this.reserve(metadata.owner.runId, metadata.reservedBytes + metadata.storedBytes, metadata.events)
+        this.artifactSlots += 1
+        this.artifacts.set(id, metadata)
+        this.capabilities.set(metadata.capabilityHash, id)
+        this.redactions.set(id, new Set(this.runtimeRedactions))
+      } catch {
+        await Promise.all([...files].map((suffix) => safeUnlink(this.path(id, suffix))))
+      }
+    }
+  }
+
+  /** @param {string} runId @param {number} bytes @param {number} events */
+  reserve(runId, bytes, events) {
+    const run = this.runs.get(runId) ?? {bytes: 0, events: 0}
+    if (
+      this.storeBytes + bytes > this.limits.maxStoreBytes || this.storeEvents + events > this.limits.maxStoreEvents
+      || run.bytes + bytes > this.limits.maxRunBytes || run.events + events > this.limits.maxRunEvents
+    ) throw new EvidenceCapacityError()
+    this.storeBytes += bytes
+    this.storeEvents += events
+    run.bytes += bytes
+    run.events += events
+    this.runs.set(runId, run)
+  }
+
+  /** @param {EvidenceMetadata} metadata */
+  release(metadata) {
+    this.storeBytes -= metadata.storedBytes + metadata.reservedBytes
+    this.storeEvents -= metadata.events
+    const run = this.runs.get(metadata.owner.runId)
+    if (run) {
+      run.bytes -= metadata.storedBytes + metadata.reservedBytes
+      run.events -= metadata.events
+      if (run.bytes === 0 && run.events === 0) this.runs.delete(metadata.owner.runId)
+    }
+  }
+
+  /** @param {object} owner */
+  assertScope(owner) {
+    if (!this.scopes.has(owner)) throw new EvidenceAccessError()
+  }
+
+  beginOperation() {
+    if (this.closed || this.closing) throw new Error("Evidence store is closed")
+    this.activeOperations += 1
+    let finished = false
+    return () => {
+      if (finished) return
+      finished = true
+      this.activeOperations -= 1
+      if (this.activeOperations === 0) {
+        for (const resolveWaiter of this.operationWaiters.splice(0)) resolveWaiter()
+      }
+    }
+  }
+
+  /** @param {string} handle */
+  lookupCapability(handle) {
+    const candidate = Buffer.from(capabilityHash(handle), "base64url")
+    let found
+    for (const [hash, id] of this.capabilities) {
+      const stored = Buffer.from(hash, "base64url")
+      if (stored.length === candidate.length && timingSafeEqual(stored, candidate)) found = id
+    }
+    return found
+  }
+
+  /** @param {string} id @param {string} suffix */
+  path(id, suffix) {
+    return join(this.root, `${id}${suffix}`)
+  }
+}
+
+/** @param {{chatId: string, threadId: number | null}} target @param {string} senderId */
+export function evidenceTelegramDestination(target, senderId) {
+  if (!validIdentity(senderId)) throw new Error("Invalid trusted Telegram sender identity")
+  return `telegram:${target.chatId}:${target.threadId ?? "dm"}:sender:${senderId}`
+}
+
+class EvidenceWriter {
+  /** @type {object | undefined} */
+  #ownerScope
+
+  /** @param {EvidenceStore} store @param {EvidenceMetadata} metadata @param {import("node:fs/promises").FileHandle} file @param {string} handle @param {() => void} finishOperation @param {string[]} redactions @param {object} ownerScope */
+  constructor(store, metadata, file, handle, finishOperation, redactions, ownerScope) {
+    this.store = store
+    this.metadata = metadata
+    this.file = file
+    this.handle = handle
+    this.finishOperation = finishOperation
+    this.redactions = redactions
+    this.#ownerScope = ownerScope
+    this.payloadMac = createHmac("sha256", payloadKey(handle))
+    this.closed = false
+    this.decoder = new StringDecoder("utf8")
+    this.queue = Promise.resolve()
+  }
+
+  /** @param {string} kind @param {Buffer | string} chunk */
+  append(kind, chunk) {
+    if (!/^[a-z][a-z0-9_-]{0,31}$/u.test(kind)) return Promise.reject(new Error("Invalid evidence event kind"))
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    const kindBytes = Buffer.from(kind, "ascii")
+    const header = Buffer.allocUnsafe(1 + kindBytes.length + 4)
+    header[0] = kindBytes.length
+    kindBytes.copy(header, 1)
+    header.writeUInt32BE(bytes.length, 1 + kindBytes.length)
+    const storedBytes = header.length + bytes.length
+    this.queue = this.queue.then(async () => {
+      if (this.closed) throw new Error("Evidence writer is closed")
+      if (bytes.length > this.store.limits.maxEventBytes) throw new EvidenceCapacityError("Evidence event exceeds capacity")
+      if (
+        this.metadata.storedBytes + storedBytes > this.store.limits.maxArtifactBytes
+        || this.metadata.events + 1 > this.store.limits.maxArtifactEvents
+      ) throw new EvidenceCapacityError()
+      this.store.reserve(this.metadata.owner.runId, storedBytes, 1)
+      try {
+        await writeAll(this.file, header)
+        await writeAll(this.file, bytes)
+      } catch (error) {
+        this.store.reserve(this.metadata.owner.runId, -storedBytes, -1)
+        throw error
+      }
+      this.payloadMac.update(header)
+      this.payloadMac.update(bytes)
+      this.metadata.bytes += bytes.length
+      this.metadata.storedBytes += storedBytes
+      this.metadata.events += 1
+      for (const byte of bytes) if (byte === 0x0a) this.metadata.lines += 1
+    })
+    return this.queue
+  }
+
+  async finalize() {
+    await this.queue
+    if (this.closed) throw new Error("Evidence writer is closed")
+    this.closed = true
+    try {
+      return await this.store.enqueueMaintenance(() => this.finalizeOnce())
+    } finally {
+      this.#releaseOwnerScope()
+    }
+  }
+
+  async finalizeOnce() {
+    try {
+      await this.file.sync()
+      await this.store.durabilityObserver("payload-fsynced")
+      await this.file.close()
+      await rename(this.store.path(this.metadata.id, PENDING_SUFFIX), this.store.path(this.metadata.id, PAYLOAD_SUFFIX))
+      await this.store.durabilityObserver("payload-renamed")
+      this.metadata.state = "ready"
+      this.metadata.payloadCommitment = this.payloadMac.digest("base64url")
+      this.metadata.redactionPolicy = encryptRedactions(this.handle, this.redactions, this.metadata)
+      this.metadata.reservedBytes = durableArtifactReservation(this.metadata)
+      await atomicJson(this.store.root, `${this.metadata.id}${META_SUFFIX}`, this.metadata)
+      await this.store.durabilityObserver("ready-metadata-directory-fsynced")
+      this.finishOperation()
+      return {
+        contentType: this.metadata.contentType,
+        bytes: this.metadata.bytes,
+        lines: this.metadata.lines,
+        events: this.metadata.events
+      }
+    } catch (error) {
+      await this.file.close().catch(() => {})
+      this.store.release(this.metadata)
+      this.store.artifactSlots -= 1
+      this.store.artifacts.delete(this.metadata.id)
+      this.store.capabilities.delete(this.metadata.capabilityHash)
+      this.store.redactions.delete(this.metadata.id)
+      await safeUnlink(this.store.path(this.metadata.id, PENDING_SUFFIX))
+      await safeUnlink(this.store.path(this.metadata.id, PAYLOAD_SUFFIX))
+      await safeUnlink(this.store.path(this.metadata.id, META_SUFFIX))
+      await syncDirectory(this.store.root)
+      this.finishOperation()
+      throw error
+    }
+  }
+
+  async abort() {
+    await this.queue.catch(() => {})
+    if (this.closed) return
+    this.closed = true
+    try {
+      await this.store.enqueueMaintenance(() => this.abortOnce())
+    } finally {
+      this.#releaseOwnerScope()
+    }
+  }
+
+  #releaseOwnerScope() {
+    if (this.#ownerScope !== undefined) this.#ownerScope = undefined
+  }
+
+  async abortOnce() {
+    await this.file.close().catch(() => {})
+    this.store.release(this.metadata)
+    this.store.artifactSlots -= 1
+    this.store.artifacts.delete(this.metadata.id)
+    this.store.capabilities.delete(this.metadata.capabilityHash)
+    this.store.redactions.delete(this.metadata.id)
+    await safeUnlink(this.store.path(this.metadata.id, PENDING_SUFFIX))
+    await safeUnlink(this.store.path(this.metadata.id, META_SUFFIX))
+    await syncDirectory(this.store.root)
+    this.finishOperation()
+  }
+}
+
+/** @param {unknown} request @param {Partial<EvidenceLimits>} [limits] @returns {ValidatedRead} */
+export function validateEvidenceReadRequest(request, limits = DEFAULT_LIMITS) {
+  const maxReadBytes = limits.maxReadBytes ?? DEFAULT_LIMITS.maxReadBytes
+  const maxReadLines = limits.maxReadLines ?? DEFAULT_LIMITS.maxReadLines
+  if (!plainObject(request)) throw new Error("Invalid evidence handle")
+  const handleDescriptor = Object.getOwnPropertyDescriptor(request, "handle")
+  if (!handleDescriptor || handleDescriptor.get !== undefined || handleDescriptor.set !== undefined || typeof handleDescriptor.value !== "string" || !HANDLE_PATTERN.test(handleDescriptor.value)) {
+    throw new Error("Invalid evidence handle")
+  }
+  const selectors = ["bytes", "lines", "query"].filter((field) => Object.prototype.hasOwnProperty.call(request, field))
+  if (selectors.length !== 1) throw new Error("Evidence retrieval requires exactly one bounded selector")
+  if (request.bytes !== undefined) {
+    if (!plainObject(request.bytes) || !exactDataKeys(request.bytes, ["offset", "limit"]) || !nonnegative(request.bytes.offset) || !positive(request.bytes.limit) || typeof request.bytes.limit !== "number" || request.bytes.limit > maxReadBytes) {
+      throw new Error("Invalid bounded evidence byte range")
+    }
+  }
+  if (request.lines !== undefined) {
+    if (!plainObject(request.lines) || !exactDataKeys(request.lines, ["start", "limit"]) || !positive(request.lines.start) || !positive(request.lines.limit) || typeof request.lines.limit !== "number" || request.lines.limit > maxReadLines) {
+      throw new Error("Invalid bounded evidence line range")
+    }
+  }
+  if (request.query !== undefined) {
+    if (
+      !plainObject(request.query) || typeof request.query.literal !== "string" || request.query.literal.length === 0
+      || request.query.literal.length > 256 || request.query.limit !== 1
+      || !nonnegative(request.query.contextBytes) || typeof request.query.contextBytes !== "number" || request.query.contextBytes > maxReadBytes
+      || !exactDataKeys(request.query, ["literal", "limit", "contextBytes"])
+    ) throw new Error("Invalid bounded literal evidence query")
+  }
+  if (!exactOptionalDataKeys(request, ["handle", selectors[0]])) throw new Error("Invalid evidence retrieval field")
+  return /** @type {ValidatedRead} */ (request)
+}
+
+/** @param {string} root @param {string} name @param {unknown} value */
+async function atomicJson(root, name, value) {
+  const temporary = join(root, `.${name}.${randomBytes(12).toString("hex")}.tmp`)
+  const target = join(root, name)
+  const file = await open(temporary, "wx", 0o600)
+  try {
+    await file.writeFile(`${JSON.stringify(value)}\n`)
+    await file.sync()
+    await file.close()
+    await rename(temporary, target)
+    const directory = await open(root, "r")
+    await directory.sync()
+    await directory.close()
+  } catch (error) {
+    await file.close().catch(() => {})
+    await safeUnlink(temporary)
+    throw error
+  }
+}
+
+/** @param {string} root */
+async function acquireLease(root) {
+  const executable = await open(FLOCK, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW)
+  const lock = await open(join(root, LOCK_FILE), fsConstants.O_CREAT | fsConstants.O_RDWR | fsConstants.O_NOFOLLOW, 0o600)
+  try {
+    const stats = await executable.stat()
+    if (!stats.isFile() || stats.uid !== 0 || (stats.mode & 0o022) !== 0) throw new Error("Trusted flock executable is unavailable")
+    const lockStats = await lock.stat()
+    if (
+      !lockStats.isFile() || lockStats.nlink !== 1 || lockStats.uid !== process.getuid?.()
+      || (lockStats.mode & 0o777) !== 0o600
+    ) throw new Error("Invalid evidence store lock file")
+    const result = spawnSync("/proc/self/fd/4", ["-n", "3"], {
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe", lock.fd, executable.fd],
+      encoding: "utf8",
+      timeout: 2_000,
+      maxBuffer: 256
+    })
+    if (result.error || result.status !== 0 || result.stdout !== "" || result.stderr !== "") {
+      throw new Error("Evidence store is already open exclusively")
+    }
+    return lock
+  } catch (error) {
+    await lock.close().catch(() => {})
+    throw error
+  } finally {
+    await executable.close()
+  }
+}
+
+/** @param {string} root */
+async function proveDedicatedRoot(root) {
+  const markerPath = join(root, ROOT_MARKER)
+  const names = await readdir(root)
+  if (names.length === 0) {
+    await atomicJson(root, ROOT_MARKER, {version: 1, purpose: "threadwire-evidence"})
+    return
+  }
+  const marker = await readBoundedJson(markerPath, 256).catch(() => null)
+  if (
+    !plainObject(marker) || !exactKeys(marker, ["version", "purpose"])
+    || marker.version !== 1 || marker.purpose !== "threadwire-evidence"
+  ) throw new Error("Secure evidence root is not a proven dedicated store")
+}
+
+/** @param {string} requested @param {((point: string) => void | Promise<void>) | undefined} observer */
+async function openSecureRoot(requested, observer) {
+  if (!isAbsolute(requested) || requested.includes("\0")) throw new Error("Secure evidence root must be an absolute path")
+  if (requested.split("/").slice(1).some((component) => component === "" || component === "." || component === "..")) {
+    throw new Error("Invalid secure evidence root path")
+  }
+  const components = relative(parse(requested).root, requested).split("/")
+  if (components.length === 0 || components.some((component) => component === "" || component === "." || component === "..")) {
+    throw new Error("Invalid secure evidence root path")
+  }
+  let directory = await open("/", fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW)
+  try {
+    for (let index = 0; index < components.length; index += 1) {
+      const stats = await directory.stat()
+      if (!trustedRootAncestor(stats)) throw new Error("Untrusted evidence root ancestor")
+      const component = /** @type {string} */ (components[index])
+      const childPath = `/proc/self/fd/${directory.fd}/${component}`
+      await observer?.(`root-traversal-before-open:${index}`)
+      let child
+      try {
+        child = await open(childPath, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW)
+      } catch (error) {
+        if (/** @type {NodeJS.ErrnoException} */ (error).code !== "ENOENT" || index !== components.length - 1) throw error
+        await mkdir(childPath, {mode: 0o700})
+        child = await open(childPath, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW)
+      }
+      await directory.close()
+      directory = child
+    }
+    const finalStats = await directory.stat()
+    if (
+      !finalStats.isDirectory() || finalStats.uid !== process.getuid?.()
+      || (finalStats.mode & 0o777) !== 0o700
+    ) throw new Error("Secure evidence root must be an owned 0700 directory")
+    return directory
+  } catch (error) {
+    await directory.close().catch(() => {})
+    throw error
+  }
+}
+
+/** @param {import("node:fs").Stats} stats */
+function trustedRootAncestor(stats) {
+  const mode = stats.mode & 0o7777
+  if (!stats.isDirectory()) return false
+  if (stats.uid === process.getuid?.()) return (mode & 0o022) === 0
+  return stats.uid === 0 && ((mode & 0o022) === 0 || (mode & 0o1000) !== 0)
+}
+
+/** @param {string} root */
+async function syncDirectory(root) {
+  const directory = await open(root, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY)
+  try {
+    await directory.sync()
+  } finally {
+    await directory.close()
+  }
+}
+
+/** @param {string} root */
+async function storeBaseReservation(root) {
+  let bytes = 2 * ARTIFACT_DIRECTORY_OVERHEAD
+  for (const name of [ROOT_MARKER, LOCK_FILE]) {
+    const file = await open(join(root, name), fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW)
+    try {
+      const stats = await file.stat()
+      if (!stats.isFile() || stats.nlink !== 1) throw new Error("Invalid evidence store control file")
+      bytes += stats.size
+    } finally {
+      await file.close()
+    }
+  }
+  return bytes
+}
+
+/** @param {string} path @param {number} limit */
+async function readBoundedJson(path, limit) {
+  const file = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW)
+  try {
+    const stats = await file.stat()
+    if (
+      !stats.isFile() || stats.nlink !== 1 || stats.size > limit
+      || process.getuid?.() !== stats.uid || (stats.mode & 0o777) !== 0o600
+    ) throw new Error("Invalid bounded JSON file")
+    const bytes = Buffer.alloc(stats.size)
+    const {bytesRead} = await file.read(bytes, 0, bytes.length, 0)
+    if (bytesRead !== bytes.length) throw new Error("Invalid bounded JSON file")
+    return JSON.parse(bytes.toString("utf8"))
+  } finally {
+    await file.close()
+  }
+}
+
+/** @param {string} path */
+async function safeRegularFile(path) {
+  try {
+    const stats = await import("node:fs/promises").then(({lstat}) => lstat(path))
+    return stats.isFile() && !stats.isSymbolicLink() && stats.nlink === 1
+      && process.getuid?.() === stats.uid && (stats.mode & 0o777) === 0o600
+      ? stats
+      : null
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return null
+    throw error
+  }
+}
+
+/** @param {string} path */
+async function safeUnlink(path) {
+  try {
+    await unlink(path)
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code !== "ENOENT") throw error
+  }
+}
+
+/** @param {Buffer} buffer */
+function decodeUtf8(buffer) {
+  const decoded = buffer.toString("utf8")
+  if (Buffer.from(decoded).compare(buffer) !== 0) throw new Error("Evidence byte range must align to a UTF-8 boundary")
+  return decoded
+}
+
+/** @param {Buffer} buffer @param {number} limit */
+function utf8Prefix(buffer, limit) {
+  if (buffer.length <= limit) return buffer
+  let end = limit
+  while (end > 0 && ((buffer[end] ?? 0) & 0xc0) === 0x80) end -= 1
+  const lead = buffer[end]
+  if (lead !== undefined) {
+    const width = lead < 0x80 ? 1 : lead < 0xe0 ? 2 : lead < 0xf0 ? 3 : 4
+    if (end + width > limit) return buffer.subarray(0, end)
+  }
+  return buffer.subarray(0, limit)
+}
+
+/** @param {{contentType: string, data: string, encoding?: string, redacted: boolean, truncated: boolean}} result @param {number} limit */
+function fitSerializedResult(result, limit) {
+  if (Buffer.byteLength(`${JSON.stringify(result)}\n`) <= limit) return result
+  let bytes = Buffer.from(result.data, "utf8")
+  while (bytes.length > 0) {
+    let nextLength = Math.max(0, bytes.length - Math.max(1, Math.ceil(bytes.length / 8)))
+    if (result.encoding === "base64") nextLength -= nextLength % 4
+    bytes = Buffer.from(utf8Prefix(bytes, nextLength))
+    result.data = bytes.toString("utf8")
+    result.truncated = true
+    if (Buffer.byteLength(`${JSON.stringify(result)}\n`) <= limit) return result
+  }
+  if (Buffer.byteLength(`${JSON.stringify(result)}\n`) > limit) throw new EvidenceCapacityError("Evidence response metadata exceeds read capacity")
+  return result
+}
+
+/** @param {Buffer} buffer @param {number} offset */
+function utf8Start(buffer, offset) {
+  while (offset < buffer.length && ((buffer[offset] ?? 0) & 0xc0) === 0x80) offset += 1
+  return offset
+}
+
+/** @param {Buffer} buffer @param {number} offset */
+function utf8End(buffer, offset) {
+  while (offset > 0 && offset < buffer.length && ((buffer[offset] ?? 0) & 0xc0) === 0x80) offset -= 1
+  return offset
+}
+
+/** @param {string} text @param {string[]} secrets */
+function redactText(text, secrets) {
+  const merged = redactionRanges(text, secrets)
+  if (merged.length === 0) return {text, redacted: false}
+  return {text: applyRedactionRanges(text, merged, text.length), redacted: true}
+}
+
+/** @param {string} text @param {string[]} secrets */
+function redactionRanges(text, secrets) {
+  /** @type {{start: number, end: number}[]} */
+  const ranges = []
+  for (const secret of secrets) {
+    let offset = 0
+    while (offset <= text.length - secret.length) {
+      const index = text.indexOf(secret, offset)
+      if (index < 0) break
+      ranges.push({start: index, end: index + secret.length})
+      offset = index + 1
+    }
+  }
+  ranges.sort((left, right) => left.start - right.start || left.end - right.end)
+  /** @type {{start: number, end: number}[]} */
+  const merged = []
+  for (const range of ranges) {
+    const previous = merged.at(-1)
+    if (previous && range.start <= previous.end) previous.end = Math.max(previous.end, range.end)
+    else merged.push({...range})
+  }
+  return merged
+}
+
+/** @param {string} text @param {{start: number, end: number}[]} ranges @param {number} end */
+function applyRedactionRanges(text, ranges, end) {
+  let output = ""
+  let offset = 0
+  for (const range of ranges) {
+    if (range.start >= end) break
+    output += `${text.slice(offset, range.start)}[REDACTED]`
+    offset = range.end
+  }
+  return output + text.slice(offset, end)
+}
+
+/** @param {string} text @param {string[]} secrets @param {number} safeEnd */
+function redactStablePrefix(text, secrets, safeEnd) {
+  const ranges = redactionRanges(text, secrets)
+  let consumed = safeEnd
+  for (const range of ranges) if (range.start < safeEnd && range.end > consumed) consumed = range.end
+  return {
+    text: applyRedactionRanges(text, ranges, consumed),
+    consumed,
+    redacted: ranges.some((range) => range.start < consumed)
+  }
+}
+
+/**
+ * @param {import("node:fs/promises").FileHandle} file
+ * @param {number} size
+ * @param {number} maxEventBytes
+ * @param {import("node:crypto").Hmac} payloadMac
+ * @yields {{data: Buffer, redacted: boolean}}
+ */
+async function* framedChunks(file, size, maxEventBytes, payloadMac) {
+  let position = 0
+  while (position < size) {
+    const length = await readExact(file, position, 1)
+    payloadMac.update(length)
+    const kindLength = length[0] ?? 0
+    if (kindLength < 1 || kindLength > 32) throw new EvidenceAccessError()
+    const header = await readExact(file, position + 1, kindLength + 4)
+    payloadMac.update(header)
+    const kind = header.subarray(0, kindLength).toString("ascii")
+    if (!/^[a-z][a-z0-9_-]{0,31}$/u.test(kind)) throw new EvidenceAccessError()
+    const payloadLength = header.readUInt32BE(kindLength)
+    if (payloadLength > maxEventBytes || position + 1 + header.length + payloadLength > size) throw new EvidenceAccessError()
+    position += 1 + header.length
+    let remaining = payloadLength
+    while (remaining > 0) {
+      const data = await readExact(file, position, Math.min(16_384, remaining))
+      payloadMac.update(data)
+      position += data.length
+      remaining -= data.length
+      yield {data, redacted: false}
+    }
+  }
+}
+
+/** @param {string} path @param {number} size @param {number} maxEventBytes */
+async function inspectFramedPayload(path, size, maxEventBytes) {
+  const file = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW)
+  let position = 0
+  let bytes = 0
+  let lines = 0
+  let events = 0
+  try {
+    while (position < size) {
+      const length = await readExact(file, position, 1)
+      const kindLength = length[0] ?? 0
+      if (kindLength < 1 || kindLength > 32) throw new Error("invalid frame")
+      const header = await readExact(file, position + 1, kindLength + 4)
+      const kind = header.subarray(0, kindLength).toString("ascii")
+      const payloadLength = header.readUInt32BE(kindLength)
+      if (
+        !/^[a-z][a-z0-9_-]{0,31}$/u.test(kind) || payloadLength > maxEventBytes
+        || position + 1 + header.length + payloadLength > size
+      ) throw new Error("invalid frame")
+      position += 1 + header.length
+      let remaining = payloadLength
+      while (remaining > 0) {
+        const chunk = await readExact(file, position, Math.min(16_384, remaining))
+        for (const byte of chunk) if (byte === 0x0a) lines += 1
+        position += chunk.length
+        remaining -= chunk.length
+      }
+      bytes += payloadLength
+      events += 1
+    }
+    return {bytes, lines, events}
+  } finally {
+    await file.close()
+  }
+}
+
+/**
+ * @param {AsyncGenerator<{data: Buffer, redacted: boolean}>} chunks
+ * @param {string[]} secrets
+ * @yields {{data: Buffer, redacted: boolean}}
+ */
+async function* redactedChunks(chunks, secrets) {
+  const decoder = new StringDecoder("utf8")
+  const overlap = Math.max(1, ...secrets.map((secret) => secret.length))
+  let carry = ""
+  let anyRedacted = false
+  for await (const chunk of chunks) {
+    carry += decoder.write(chunk.data)
+    const safeEnd = safeStringEnd(carry, Math.max(0, carry.length - overlap))
+    if (safeEnd === 0) continue
+    const part = redactStablePrefix(carry, secrets, safeEnd)
+    anyRedacted ||= part.redacted
+    carry = carry.slice(part.consumed)
+    const data = Buffer.from(part.text, "utf8")
+    if (data.length > 0) yield {data, redacted: anyRedacted}
+  }
+  carry += decoder.end()
+  const part = redactText(carry, secrets)
+  anyRedacted ||= part.redacted
+  const data = Buffer.from(part.text, "utf8")
+  if (data.length > 0) yield {data, redacted: anyRedacted}
+}
+
+/**
+ * @param {AsyncGenerator<{data: Buffer, redacted: boolean}>} chunks
+ * @param {string[]} secrets
+ * @yields {{data: Buffer, redacted: boolean}}
+ */
+async function* redactedBinaryChunks(chunks, secrets) {
+  const patterns = secrets.map((secret) => Buffer.from(secret, "utf8"))
+  const overlap = Math.max(1, ...patterns.map((pattern) => pattern.length))
+  let carry = Buffer.alloc(0)
+  let anyRedacted = false
+  for await (const chunk of chunks) {
+    carry = Buffer.concat([carry, chunk.data])
+    const safeEnd = Math.max(0, carry.length - overlap)
+    if (safeEnd === 0) continue
+    const part = redactStableBinaryPrefix(carry, patterns, safeEnd)
+    anyRedacted ||= part.redacted
+    carry = carry.subarray(part.consumed)
+    if (part.data.length > 0) yield {data: part.data, redacted: anyRedacted}
+  }
+  const part = redactStableBinaryPrefix(carry, patterns, carry.length)
+  anyRedacted ||= part.redacted
+  if (part.data.length > 0) yield {data: part.data, redacted: anyRedacted}
+}
+
+/** @param {Buffer} value @param {Buffer[]} patterns @param {number} safeEnd */
+function redactStableBinaryPrefix(value, patterns, safeEnd) {
+  /** @type {{start: number, end: number}[]} */
+  const ranges = []
+  for (const pattern of patterns) {
+    let offset = 0
+    while (offset <= value.length - pattern.length) {
+      const index = value.indexOf(pattern, offset)
+      if (index < 0) break
+      ranges.push({start: index, end: index + pattern.length})
+      offset = index + 1
+    }
+  }
+  ranges.sort((left, right) => left.start - right.start || left.end - right.end)
+  /** @type {{start: number, end: number}[]} */
+  const merged = []
+  for (const range of ranges) {
+    const previous = merged.at(-1)
+    if (previous && range.start <= previous.end) previous.end = Math.max(previous.end, range.end)
+    else merged.push({...range})
+  }
+  let consumed = safeEnd
+  for (const range of merged) if (range.start < safeEnd && range.end > consumed) consumed = range.end
+  const output = []
+  let offset = 0
+  for (const range of merged) {
+    if (range.start >= consumed) break
+    output.push(value.subarray(offset, range.start), Buffer.from("[REDACTED]"))
+    offset = range.end
+  }
+  output.push(value.subarray(offset, consumed))
+  return {data: Buffer.concat(output), consumed, redacted: merged.some((range) => range.start < consumed)}
+}
+
+/** @param {import("node:fs/promises").FileHandle} file @param {number} position @param {number} length */
+async function readExact(file, position, length) {
+  const buffer = Buffer.allocUnsafe(length)
+  let offset = 0
+  while (offset < length) {
+    const {bytesRead} = await file.read(buffer, offset, length - offset, position + offset)
+    if (bytesRead <= 0) throw new EvidenceAccessError()
+    offset += bytesRead
+  }
+  return buffer
+}
+
+/** @param {import("node:fs/promises").FileHandle} file @param {Buffer} buffer */
+async function writeAll(file, buffer) {
+  let offset = 0
+  while (offset < buffer.length) {
+    const {bytesWritten} = await file.write(buffer, offset, buffer.length - offset)
+    if (bytesWritten <= 0) throw new Error("Evidence write made no progress")
+    offset += bytesWritten
+  }
+}
+
+/** @param {string} value @param {number} end */
+function safeStringEnd(value, end) {
+  if (end > 0 && end < value.length) {
+    const code = value.charCodeAt(end - 1)
+    if (code >= 0xd800 && code <= 0xdbff) return end - 1
+  }
+  return end
+}
+
+/** @param {AsyncGenerator<{data: Buffer, redacted: boolean}>} chunks @param {ValidatedRead} request @param {number} maxBytes */
+async function selectChunks(chunks, request, maxBytes) {
+  if (request.bytes) return selectBytes(chunks, request.bytes, maxBytes)
+  if (request.lines) return selectLines(chunks, request.lines, maxBytes)
+  return selectQuery(chunks, /** @type {NonNullable<ValidatedRead["query"]>} */ (request.query), maxBytes)
+}
+
+/** @param {AsyncGenerator<{data: Buffer, redacted: boolean}>} chunks @param {{offset: number, limit: number}} range @param {number} maxBytes */
+async function selectBytes(chunks, range, maxBytes) {
+  const limit = Math.min(range.limit, maxBytes)
+  let skipped = 0
+  let redacted = false
+  /** @type {Buffer[]} */
+  const output = []
+  let length = 0
+  let hasMore = false
+  let complete = false
+  for await (const chunk of chunks) {
+    redacted ||= chunk.redacted
+    if (complete) continue
+    if (skipped + chunk.data.length <= range.offset) {
+      skipped += chunk.data.length
+      continue
+    }
+    const start = Math.max(0, range.offset - skipped)
+    const available = chunk.data.subarray(start)
+    const take = Math.min(available.length, limit - length)
+    if (take > 0) {
+      output.push(available.subarray(0, take))
+      length += take
+    }
+    skipped += chunk.data.length
+    if (take < available.length) {
+      hasMore = true
+      complete = true
+    }
+  }
+  return {data: Buffer.concat(output, length), redacted, truncated: range.offset > 0 || hasMore}
+}
+
+/** @param {AsyncGenerator<{data: Buffer, redacted: boolean}>} chunks @param {{start: number, limit: number}} range @param {number} maxBytes */
+async function selectLines(chunks, range, maxBytes) {
+  let line = 1
+  let redacted = false
+  let length = 0
+  let complete = 0
+  let selectionDone = false
+  let truncated = range.start > 1
+  /** @type {Buffer[]} */
+  const output = []
+  for await (const chunk of chunks) {
+    redacted ||= chunk.redacted
+    if (selectionDone) {
+      if (chunk.data.length > 0) truncated = true
+      continue
+    }
+    for (let index = 0; index < chunk.data.length; index += 1) {
+      const byte = /** @type {number} */ (chunk.data[index])
+      if (line >= range.start && complete < range.limit && length < maxBytes) {
+        output.push(Buffer.from([byte]))
+        length += 1
+      }
+      if (byte === 0x0a) {
+        if (line >= range.start) complete += 1
+        line += 1
+        if (complete >= range.limit) {
+          truncated ||= index + 1 < chunk.data.length
+          selectionDone = true
+          break
+        }
+      }
+      if (length >= maxBytes) {
+        truncated = true
+        selectionDone = true
+        break
+      }
+    }
+  }
+  return {data: utf8Prefix(Buffer.concat(output, length), maxBytes), redacted, truncated}
+}
+
+/** @param {AsyncGenerator<{data: Buffer, redacted: boolean}>} chunks @param {{literal: string, limit: number, contextBytes: number}} query @param {number} maxBytes */
+async function selectQuery(chunks, query, maxBytes) {
+  const needle = Buffer.from(query.literal, "utf8")
+  const keep = Math.min(maxBytes, query.contextBytes + needle.length - 1)
+  let prefix = Buffer.alloc(0)
+  let dropped = false
+  let redacted = false
+  let match = -1
+  let matchStart = 0
+  /** @type {{data: Buffer, redacted: boolean, truncated: boolean} | null} */
+  let result = null
+  for await (const chunk of chunks) {
+    redacted ||= chunk.redacted
+    if (result) {
+      result.redacted ||= chunk.redacted
+      if (chunk.data.length > 0) result.truncated = true
+      continue
+    }
+    const combined = Buffer.concat([prefix, chunk.data])
+    const index = match >= 0 ? match : combined.indexOf(needle)
+    if (index >= 0) {
+      match = index
+      const start = utf8Start(combined, Math.max(0, index - query.contextBytes))
+      const requestedEnd = index + needle.length + query.contextBytes
+      if (combined.length < requestedEnd && combined.length < maxBytes) {
+        prefix = combined
+        matchStart = start
+        continue
+      }
+      const end = utf8End(combined, Math.min(combined.length, requestedEnd))
+      const data = utf8Prefix(combined.subarray(matchStart || start, end), maxBytes)
+      result = {
+        data,
+        redacted,
+        truncated: dropped || start > 0 || end < combined.length || data.length < end - start || requestedEnd > combined.length
+      }
+      continue
+    }
+    if (combined.length > keep) {
+      prefix = combined.subarray(combined.length - keep)
+      dropped = true
+    } else prefix = combined
+  }
+  return result ?? {data: Buffer.alloc(0), redacted, truncated: dropped}
+}
+
+/** @param {string} value */
+function isText(value) {
+  const base = value.split(";")[0]?.trim().toLowerCase() ?? ""
+  return base.startsWith("text/") || TEXT_CONTENT_TYPES.has(base)
+}
+
+/** @param {string} handle */
+function capabilityHash(handle) {
+  if (!HANDLE_PATTERN.test(handle)) throw new Error("Invalid evidence handle")
+  return createHash("sha256").update(handle, "utf8").digest("base64url")
+}
+
+/** @param {string} handle @param {string[]} redactions @param {EvidenceMetadata} metadata @returns {EvidenceMetadata["redactionPolicy"]} */
+function encryptRedactions(handle, redactions, metadata) {
+  const nonce = randomBytes(12)
+  const cipher = createCipheriv("aes-256-gcm", redactionKey(handle), nonce)
+  cipher.setAAD(redactionAad(metadata))
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(redactions), "utf8"), cipher.final()])
+  return {
+    algorithm: "aes-256-gcm",
+    nonce: nonce.toString("base64url"),
+    ciphertext: ciphertext.toString("base64url"),
+    tag: cipher.getAuthTag().toString("base64url")
+  }
+}
+
+/** @param {string} handle @param {EvidenceMetadata["redactionPolicy"]} policy @param {EvidenceMetadata} metadata */
+function decryptRedactions(handle, policy, metadata) {
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", redactionKey(handle), Buffer.from(policy.nonce, "base64url"))
+    decipher.setAAD(redactionAad(metadata))
+    decipher.setAuthTag(Buffer.from(policy.tag, "base64url"))
+    const plaintext = Buffer.concat([
+      decipher.update(Buffer.from(policy.ciphertext, "base64url")),
+      decipher.final()
+    ]).toString("utf8")
+    return validateRedactions(JSON.parse(plaintext))
+  } catch {
+    throw new EvidenceAccessError()
+  }
+}
+
+/** @param {EvidenceMetadata} metadata */
+function redactionAad(metadata) {
+  return Buffer.from(JSON.stringify([
+    "threadwire-evidence-policy", metadata.policyVersion, metadata.version, metadata.framingVersion, metadata.id,
+    metadata.state,
+    metadata.capabilityHash, metadata.owner.destinationId, metadata.owner.runId,
+    metadata.contentType, metadata.createdAt, metadata.expiresAt,
+    metadata.bytes, metadata.storedBytes, metadata.reservedBytes,
+    metadata.lines, metadata.events, metadata.payloadCommitment
+  ]), "utf8")
+}
+
+/** @param {EvidenceMetadata} metadata */
+function durableArtifactReservation(metadata) {
+  return 2_048 + metadata.redactionPolicy.ciphertext.length * 2 + ARTIFACT_DIRECTORY_OVERHEAD
+}
+
+/** @param {string} handle */
+function redactionKey(handle) {
+  return createHash("sha256").update("threadwire-evidence-redaction-v1\0").update(handle, "utf8").digest()
+}
+
+/** @param {string} handle */
+function payloadKey(handle) {
+  return createHash("sha256").update("threadwire-evidence-payload-v1\0").update(handle, "utf8").digest()
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function plainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+}
+
+/** @param {unknown} value */
+function positive(value) {
+  return Number.isSafeInteger(value) && /** @type {number} */ (value) > 0
+}
+
+/** @param {unknown} value */
+function nonnegative(value) {
+  return Number.isSafeInteger(value) && /** @type {number} */ (value) >= 0
+}
+
+/** @param {string} value */
+function validIdentity(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 256
+}
+
+/** @param {string} value */
+function validateContentType(value) {
+  if (typeof value !== "string" || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(?:;\s*charset=utf-8)?$/iu.test(value) || value.length > 96) {
+    throw new Error("Invalid evidence content type")
+  }
+  return value.toLowerCase()
+}
+
+/** @param {string[]} values */
+function validateRedactions(values) {
+  if (!Array.isArray(values) || values.length > 64 || values.some((value) => typeof value !== "string" || value.length < 4 || value.length > 4096)) {
+    throw new Error("Invalid evidence redactions")
+  }
+  return values
+}
+
+/** @param {Record<string, unknown>} left @param {object} right */
+function sameOwner(left, right) {
+  return left.destinationId === /** @type {{destinationId?: unknown}} */ (right).destinationId
+    && left.runId === /** @type {{runId?: unknown}} */ (right).runId
+}
+
+/** @param {unknown} value @param {string} id @param {EvidenceLimits} limits */
+function validMetadata(value, id, limits) {
+  return plainObject(value) && value.version === 2 && value.id === id && value.state === "ready"
+    && exactKeys(value, [
+      "version", "policyVersion", "framingVersion", "id", "state", "owner", "contentType", "capabilityHash",
+      "redactionPolicy", "payloadCommitment", "bytes", "storedBytes", "reservedBytes", "lines", "events", "createdAt", "expiresAt"
+    ])
+    && value.policyVersion === 1 && value.framingVersion === 1
+    && plainObject(value.owner) && typeof value.owner.destinationId === "string" && validIdentity(value.owner.destinationId)
+    && typeof value.owner.runId === "string" && validIdentity(value.owner.runId)
+    && exactKeys(value.owner, ["destinationId", "runId"])
+    && typeof value.capabilityHash === "string" && /^[A-Za-z0-9_-]{43}$/u.test(value.capabilityHash)
+    && validRedactionPolicy(value.redactionPolicy)
+    && typeof value.contentType === "string" && validContentType(value.contentType)
+    && typeof value.bytes === "number" && typeof value.storedBytes === "number"
+    && typeof value.reservedBytes === "number" && positive(value.reservedBytes)
+    && nonnegative(value.bytes) && nonnegative(value.storedBytes) && value.bytes <= value.storedBytes
+    && value.bytes <= limits.maxArtifactBytes && value.storedBytes <= limits.maxArtifactBytes
+    && typeof value.payloadCommitment === "string" && /^[A-Za-z0-9_-]{43}$/u.test(value.payloadCommitment)
+    && value.reservedBytes === durableArtifactReservation(/** @type {EvidenceMetadata} */ (value))
+    && typeof value.lines === "number" && nonnegative(value.lines) && value.lines <= value.bytes
+    && typeof value.events === "number" && nonnegative(value.events) && value.events <= limits.maxArtifactEvents
+    && typeof value.createdAt === "number" && typeof value.expiresAt === "number"
+    && nonnegative(value.createdAt) && positive(value.expiresAt) && value.createdAt < value.expiresAt
+}
+
+/** @param {unknown} value */
+function validRedactionPolicy(value) {
+  return plainObject(value) && value.algorithm === "aes-256-gcm"
+    && exactKeys(value, ["algorithm", "nonce", "ciphertext", "tag"])
+    && typeof value.nonce === "string" && typeof value.ciphertext === "string" && typeof value.tag === "string"
+    && value.nonce.length === 16 && value.tag.length === 22 && value.ciphertext.length <= 350_000
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} keys */
+function exactKeys(value, keys) {
+  const own = Reflect.ownKeys(value)
+  return own.length === keys.length && own.every((key) => typeof key === "string" && keys.includes(key))
+}
+
+/** @param {Record<string, unknown>} value @param {string[]} keys */
+function exactDataKeys(value, keys) {
+  return exactKeys(value, keys) && keys.every((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    return descriptor?.get === undefined && descriptor?.set === undefined && descriptor?.enumerable === true
+  })
+}
+
+/** @param {Record<string, unknown>} value @param {(string | undefined)[]} keys */
+function exactOptionalDataKeys(value, keys) {
+  const expected = keys.filter((key) => key !== undefined)
+  return exactDataKeys(value, /** @type {string[]} */ (expected))
+}
+
+/** @param {string} value */
+function validContentType(value) {
+  try {
+    return validateContentType(value) === value
+  } catch {
+    return false
+  }
+}
+
+/** @param {EvidenceLimits} limits */
+function validateLimits(limits) {
+  for (const [name, value] of Object.entries(limits)) if (!positive(value)) throw new Error(`Invalid evidence limit: ${name}`)
+  return Object.freeze(limits)
+}
+
+/**
+ * @typedef {{
+ * version: 2, policyVersion: 1, framingVersion: 1, id: string, state: "pending" | "ready" | "expired" | "removed",
+ * owner: {destinationId: string, runId: string}, contentType: string,
+ * capabilityHash: string,
+ * redactionPolicy: {algorithm: "aes-256-gcm", nonce: string, ciphertext: string, tag: string}, payloadCommitment: string,
+ * bytes: number, storedBytes: number, reservedBytes: number, lines: number, events: number, createdAt: number, expiresAt: number
+ * }} EvidenceMetadata
+ * @typedef {{
+ * handle: string,
+ * bytes?: {offset: number, limit: number},
+ * lines?: {start: number, limit: number},
+ * query?: {literal: string, limit: number, contextBytes: number}
+ * }} ValidatedRead
+ * @typedef {{
+ * maxEventBytes: number, maxArtifactBytes: number, maxArtifactEvents: number,
+ * maxRunBytes: number, maxRunEvents: number, maxStoreBytes: number,
+ * maxStoreEvents: number, maxArtifacts: number, maxReadBytes: number, maxReadLines: number,
+ * retentionMs: number
+ * }} EvidenceLimits
+ */