@nifrajs/core 1.10.0 → 1.11.0

package/src/ledger.ts

@@ -0,0 +1,430 @@
+/**
+ * Effect ledger: a per-request, append-only, ordered record of side-effect intents and outcomes.
+ *
+ * Every owned effect seam (a repository write, an external call, an email send) records one entry via
+ * the `useCapability` beacon. The entry type is deliberately **token-only**: capability ids, phase,
+ * an adapter/resource token, dimensionless cost counters, an optional keyed digest, and an error code.
+ * There is no free-form payload field — request bodies, rows, and values cannot enter the ledger, so
+ * redaction holds by construction rather than by filtering. The sealed ledger carries the **route
+ * pattern** (`/users/:id`), never the concrete URL, so path parameters cannot leak either.
+ *
+ * The ledger is the substrate that audit, replay, reconciliation, and cost accounting read.
+ * This module ships the primitive: the entry contract, a bounded per-request ledger with an optional
+ * tamper-evident hash chain, a sink seam, an in-memory sink, and a keyed digest helper. Durable,
+ * encrypted, or retention-managed sinks implement the same {@link LedgerSink} seam externally.
+ */
+
+import { validCapabilityId } from "./internal/capability-runtime.ts"
+
+/** Lifecycle phase of one effect. `intent` precedes execution; the rest describe its outcome. */
+export type EffectPhase = "intent" | "committed" | "failed" | "compensated"
+
+const EFFECT_PHASES: ReadonlySet<string> = new Set(["intent", "committed", "failed", "compensated"])
+
+/**
+ * Dimensionless resource counters (`{ ms: 12, calls: 1, bytes: 512 }`). Counters carry *how much
+ * resource* an effect consumed; mapping counters to money/pricing is deliberately out of scope here.
+ */
+export type EffectCost = Readonly<Record<string, number>>
+
+/** Caller-supplied fields for one entry. Everything else (`seq`, `at`) is assigned by the ledger. */
+export interface EffectEntryInput {
+  /** Capability token (`db.write`, `payments.charge`). Must be a valid capability id. */
+  readonly capability: string
+  /** Default `"intent"`. Record `committed`/`failed`/`compensated` only after the outcome is known. */
+  readonly phase?: EffectPhase
+  /** Adapter/resource token (`repo:orders`, `provider:payments`). A token — never a value or a row. */
+  readonly target?: string
+  /** Dimensionless counters; see {@link EffectCost}. At most {@link MAX_COST_AXES} axes. */
+  readonly cost?: EffectCost
+  /** Optional keyed-HMAC digest of the effect payload (see {@link computeEffectDigest}); hex, 64 chars. */
+  readonly digest?: string
+  /** Outcome error as a bounded token code — never a message, never a stack. */
+  readonly error?: { readonly code: string }
+}
+
+/** One recorded effect. Frozen; token-only by construction (no payload field exists). */
+export interface EffectEntry {
+  /** Monotonic position within the request (0-based). The replay/simulation order. */
+  readonly seq: number
+  /** Milliseconds from the ledger's (injectable) clock at append time. */
+  readonly at: number
+  readonly capability: string
+  readonly phase: EffectPhase
+  readonly target?: string
+  readonly cost?: EffectCost
+  readonly digest?: string
+  readonly error?: { readonly code: string }
+}
+
+/** Tamper-evidence over the route identity, declarations, and sealed entries. */
+export interface EffectChain {
+  /** `hashes[i]` = SHA-256(hex) over (`hashes[i-1]` + canonical entry `i`). */
+  readonly hashes: readonly string[]
+  /** Last entry hash, or the route-header hash for an empty ledger. Anchor/sign this externally. */
+  readonly head: string
+}
+
+/** The immutable result of sealing a request's ledger. Token-only; safe to hand to any sink. */
+export interface SealedEffectLedger {
+  readonly method: string
+  /** The registered route pattern (`/users/:id`) — never the concrete request URL. */
+  readonly path: string
+  readonly entries: readonly EffectEntry[]
+  /** The route's declared capability tokens — the runtime-enforcement view: recorded ⊆ declared is
+   * guaranteed by the beacon, and `declared` minus the recorded ids is the unused declaration set. */
+  readonly declared: readonly string[]
+  /** Present when the ledger was created with `chain: true`. */
+  readonly chain?: EffectChain
+}
+
+/**
+ * Receives each sealed ledger once per request (only when it has entries). Implementations must not
+ * assume a payload: the ledger is token-only. A durable/tenant-scoped sink lives behind this seam.
+ */
+export type LedgerSink = (ledger: SealedEffectLedger) => void | Promise<void>
+
+/** Thrown by `append` when the per-request entry bound is exceeded. Fails the request closed. */
+export class EffectLedgerOverflowError extends Error {
+  constructor(public readonly maxEntries: number) {
+    super(`effect ledger overflow: more than ${maxEntries} entries in one request`)
+    this.name = "EffectLedgerOverflowError"
+  }
+}
+
+/** Thrown by `append` after `seal()` — e.g. an effect attempted while streaming a response body. */
+export class EffectLedgerSealedError extends Error {
+  constructor() {
+    super("effect ledger is sealed: effects cannot be recorded after the response settles")
+    this.name = "EffectLedgerSealedError"
+  }
+}
+
+/** Per-request ledger. `append` is synchronous (hot-path safe); `seal` is idempotent and async. */
+export interface RequestLedger {
+  /** Validate, freeze, and record one entry. Throws on invalid input, overflow, or after seal. */
+  append(input: EffectEntryInput): EffectEntry
+  /** Entries recorded so far (frozen snapshot view). */
+  entries(): readonly EffectEntry[]
+  readonly size: number
+  readonly sealed: boolean
+  /** Finalize the ledger (computing the chain when enabled). Idempotent — always the same result. */
+  seal(): Promise<SealedEffectLedger>
+}
+
+export interface CreateRequestLedgerOptions {
+  /** HTTP method of the matched route. */
+  readonly method: string
+  /** The registered route pattern — callers must never pass the concrete request URL. */
+  readonly path: string
+  /** The route's declared capability tokens, surfaced verbatim on the sealed ledger. Default `[]`. */
+  readonly declared?: readonly string[]
+  /** Entry bound; exceeding it throws {@link EffectLedgerOverflowError}. Default {@link DEFAULT_MAX_ENTRIES}. */
+  readonly maxEntries?: number
+  /** Compute the tamper-evident hash chain at seal. Default false. */
+  readonly chain?: boolean
+  /** Injectable monotonic clock (ms) for deterministic tests. Default `performance.now`. */
+  readonly clock?: () => number
+}
+
+/** Per-request entry bound. Generous for real handlers, small enough to stop a runaway loop. */
+export const DEFAULT_MAX_ENTRIES = 1_000
+
+/** Most cost axes one entry may carry. */
+export const MAX_COST_AXES = 8
+
+const TARGET_MAX_LENGTH = 128
+const ERROR_CODE = /^[a-z][a-z0-9_.-]{0,63}$/
+const DIGEST_HEX = /^[0-9a-f]{64}$/
+
+function printableToken(value: string, maxLength: number): boolean {
+  if (value.length === 0 || value.length > maxLength) return false
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    if (code < 33 || code > 126) return false
+  }
+  return true
+}
+
+function validateCost(cost: EffectCost): EffectCost {
+  const keys = Object.keys(cost)
+  if (keys.length > MAX_COST_AXES) {
+    throw new TypeError(`effect ledger: cost carries more than ${MAX_COST_AXES} axes`)
+  }
+  for (const key of keys) {
+    if (!validCapabilityId(key)) {
+      throw new TypeError(`effect ledger: invalid cost axis ${JSON.stringify(key)}`)
+    }
+    const value = cost[key]
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      throw new TypeError(`effect ledger: cost axis ${key} must be a finite non-negative number`)
+    }
+  }
+  return Object.freeze({ ...cost })
+}
+
+const defaultClock = (): number => performance.now()
+
+class BoundedRequestLedger implements RequestLedger {
+  private readonly items: EffectEntry[] = []
+  private readonly method: string
+  private readonly path: string
+  private readonly declared: readonly string[]
+  private readonly maxEntries: number
+  private readonly chain: boolean
+  private readonly clock: () => number
+  private sealResult: Promise<SealedEffectLedger> | undefined
+
+  constructor(options: CreateRequestLedgerOptions) {
+    if (!printableToken(options.method, 16) || !options.path.startsWith("/")) {
+      throw new TypeError("effect ledger: method/path must be a route pattern")
+    }
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+      throw new TypeError("effect ledger: maxEntries must be a positive safe integer")
+    }
+    const declared = options.declared ?? []
+    for (const id of declared) {
+      if (!validCapabilityId(id)) {
+        throw new TypeError(`effect ledger: invalid declared capability ${JSON.stringify(id)}`)
+      }
+    }
+    this.method = options.method.toUpperCase()
+    this.path = options.path
+    this.declared = Object.freeze([...declared])
+    this.maxEntries = maxEntries
+    this.chain = options.chain ?? false
+    this.clock = options.clock ?? defaultClock
+  }
+
+  get size(): number {
+    return this.items.length
+  }
+
+  get sealed(): boolean {
+    return this.sealResult !== undefined
+  }
+
+  append(input: EffectEntryInput): EffectEntry {
+    if (this.sealResult !== undefined) throw new EffectLedgerSealedError()
+    if (this.items.length >= this.maxEntries) throw new EffectLedgerOverflowError(this.maxEntries)
+    if (!validCapabilityId(input.capability)) {
+      throw new TypeError(`effect ledger: invalid capability ${JSON.stringify(input.capability)}`)
+    }
+    const phase = input.phase ?? "intent"
+    if (!EFFECT_PHASES.has(phase)) {
+      throw new TypeError(`effect ledger: invalid phase ${JSON.stringify(phase)}`)
+    }
+    if (input.target !== undefined && !printableToken(input.target, TARGET_MAX_LENGTH)) {
+      throw new TypeError("effect ledger: target must be a bounded printable token")
+    }
+    if (input.digest !== undefined && !DIGEST_HEX.test(input.digest)) {
+      throw new TypeError("effect ledger: digest must be 64 lowercase hex characters")
+    }
+    if (input.error !== undefined && !ERROR_CODE.test(input.error.code)) {
+      throw new TypeError("effect ledger: error code must be a bounded lowercase token")
+    }
+    // Only the known token fields are copied — a stray `payload`-like property never survives append.
+    const at = this.clock()
+    if (!Number.isFinite(at) || at < 0) {
+      throw new TypeError("effect ledger: clock must return a finite non-negative number")
+    }
+    const entry: EffectEntry = Object.freeze({
+      seq: this.items.length,
+      at,
+      capability: input.capability,
+      phase,
+      ...(input.target !== undefined ? { target: input.target } : {}),
+      ...(input.cost !== undefined ? { cost: validateCost(input.cost) } : {}),
+      ...(input.digest !== undefined ? { digest: input.digest } : {}),
+      ...(input.error !== undefined ? { error: Object.freeze({ code: input.error.code }) } : {}),
+    })
+    this.items.push(entry)
+    return entry
+  }
+
+  entries(): readonly EffectEntry[] {
+    return Object.freeze([...this.items])
+  }
+
+  seal(): Promise<SealedEffectLedger> {
+    this.sealResult ??= this.sealOnce()
+    return this.sealResult
+  }
+
+  private async sealOnce(): Promise<SealedEffectLedger> {
+    const entries = Object.freeze([...this.items])
+    const base = {
+      method: this.method,
+      path: this.path,
+      entries,
+      declared: this.declared,
+    }
+    if (!this.chain) return Object.freeze(base)
+    const hashes: string[] = []
+    // Seed the chain with the route identity and declared authority. Otherwise an anchored entry
+    // chain could be copied onto a different route/declaration without changing its head.
+    let previous = await sha256Hex(
+      JSON.stringify({ method: this.method, path: this.path, declared: [...this.declared].sort() }),
+    )
+    for (const entry of entries) {
+      previous = await sha256Hex(`${previous}${canonicalEntry(entry)}`)
+      hashes.push(previous)
+    }
+    return Object.freeze({
+      ...base,
+      chain: Object.freeze({ hashes: Object.freeze(hashes), head: previous }),
+    })
+  }
+}
+
+/** Create a bounded per-request ledger. The server wires one per capability-declaring route. */
+export function createRequestLedger(options: CreateRequestLedgerOptions): RequestLedger {
+  return new BoundedRequestLedger(options)
+}
+
+/** Canonical, key-ordered serialization of one entry — the hash-chain input. */
+function canonicalEntry(entry: EffectEntry): string {
+  const cost =
+    entry.cost === undefined
+      ? ""
+      : `,"cost":{${Object.keys(entry.cost)
+          .sort()
+          .map((key) => `${JSON.stringify(key)}:${JSON.stringify((entry.cost as EffectCost)[key])}`)
+          .join(",")}}`
+  return (
+    `{"seq":${entry.seq},"at":${JSON.stringify(entry.at)},"capability":${JSON.stringify(entry.capability)},"phase":${JSON.stringify(entry.phase)}` +
+    `${entry.target !== undefined ? `,"target":${JSON.stringify(entry.target)}` : ""}` +
+    cost +
+    `${entry.digest !== undefined ? `,"digest":${JSON.stringify(entry.digest)}` : ""}` +
+    `${entry.error !== undefined ? `,"error":${JSON.stringify(entry.error.code)}` : ""}}`
+  )
+}
+
+const encoder = new TextEncoder()
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)))
+  let hex = ""
+  for (let index = 0; index < digest.length; index++) {
+    hex += (digest[index] as number).toString(16).padStart(2, "0")
+  }
+  return hex
+}
+
+export interface MemoryLedgerSinkOptions {
+  /** Retain at most this many sealed ledgers (oldest evicted first). Default 1000. */
+  readonly maxLedgers?: number
+}
+
+export interface MemoryLedgerSink {
+  readonly sink: LedgerSink
+  /** Sealed ledgers received so far, oldest first. */
+  readonly ledgers: readonly SealedEffectLedger[]
+  clear(): void
+}
+
+/** Bounded in-memory sink for tests and local development. Token-only, like every sink. */
+export function createMemoryLedgerSink(options: MemoryLedgerSinkOptions = {}): MemoryLedgerSink {
+  const maxLedgers = options.maxLedgers ?? 1_000
+  if (!Number.isSafeInteger(maxLedgers) || maxLedgers < 1) {
+    throw new TypeError("effect ledger: maxLedgers must be a positive safe integer")
+  }
+  const ledgers: SealedEffectLedger[] = []
+  return {
+    sink: (ledger) => {
+      ledgers.push(ledger)
+      if (ledgers.length > maxLedgers) ledgers.shift()
+    },
+    get ledgers(): readonly SealedEffectLedger[] {
+      return Object.freeze([...ledgers])
+    },
+    clear: () => {
+      ledgers.length = 0
+    },
+  }
+}
+
+/** Minimum digest key material. A short key would make the keyed digest brute-forceable. */
+export const MIN_DIGEST_KEY_BYTES = 16
+
+/** Fresh random digest key (32 bytes). Per-process by default — persist one externally to correlate across restarts. */
+export function randomEffectDigestKey(): Uint8Array {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return bytes
+}
+
+/**
+ * Keyed HMAC-SHA-256 digest (hex) of an effect payload, for replay/reconciliation matching without
+ * storing the payload. Keyed on purpose: a bare hash of low-entropy data (an email, a flag) is
+ * brute-forceable and would itself leak. Digest the **whole** effect payload, never a single field.
+ */
+export async function computeEffectDigest(
+  key: Uint8Array | CryptoKey,
+  payload: Uint8Array,
+): Promise<string> {
+  let cryptoKey: CryptoKey
+  if (key instanceof Uint8Array) {
+    if (key.byteLength < MIN_DIGEST_KEY_BYTES) {
+      throw new TypeError(
+        `effect ledger: digest key must be at least ${MIN_DIGEST_KEY_BYTES} bytes`,
+      )
+    }
+    cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      key as unknown as ArrayBuffer,
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"],
+    )
+  } else {
+    const algorithm = key.algorithm as unknown as {
+      readonly name?: unknown
+      readonly hash?: { readonly name?: unknown }
+      readonly length?: unknown
+    }
+    if (
+      algorithm.name !== "HMAC" ||
+      algorithm.hash?.name !== "SHA-256" ||
+      typeof algorithm.length !== "number" ||
+      algorithm.length < MIN_DIGEST_KEY_BYTES * 8 ||
+      !key.usages.includes("sign")
+    ) {
+      throw new TypeError(
+        "effect ledger: CryptoKey must be an HMAC-SHA-256 signing key of at least 128 bits",
+      )
+    }
+    cryptoKey = key
+  }
+  const mac = new Uint8Array(
+    await crypto.subtle.sign("HMAC", cryptoKey, payload as unknown as ArrayBuffer),
+  )
+  let hex = ""
+  for (let index = 0; index < mac.length; index++) {
+    hex += (mac[index] as number).toString(16).padStart(2, "0")
+  }
+  return hex
+}
+
+const EFFECT_LEDGER = Symbol("nifra.effect.ledger")
+
+/** Framework wiring: attach a per-request ledger to a handler context. Not for application code. */
+export function attachEffectLedger(context: object, ledger: RequestLedger): void {
+  ;(context as Record<PropertyKey, unknown>)[EFFECT_LEDGER as unknown as string] = ledger
+}
+
+/** The request's effect ledger, when the server enabled one for this route. Read-only access. */
+export function effectLedgerOf(context: object): RequestLedger | undefined {
+  return (context as { readonly [EFFECT_LEDGER]?: RequestLedger })[EFFECT_LEDGER]
+}
+
+/** Server-level effect ledger configuration (see `server({ effectLedger })`). */
+export interface EffectLedgerOptions {
+  /** Receives each request's sealed ledger (only when it recorded entries). */
+  readonly sink: LedgerSink
+  /** Per-request entry bound. Default {@link DEFAULT_MAX_ENTRIES}. */
+  readonly maxEntries?: number
+  /** Compute the tamper-evident hash chain at seal. Default false. */
+  readonly chain?: boolean
+}