@nifrajs/core 3.1.0 → 3.3.0

package/src/durable-approval.ts

@@ -0,0 +1,281 @@
+import type { CapabilityApprovalGate } from "./internal/capability-runtime.ts"
+import { durableApprovalProtocol } from "./internal/durable-approval-protocol.ts"
+import {
+  addDuration,
+  assertPositiveMs,
+  assertToken,
+  bytesToBase64Url,
+  cloneValue,
+  encoder,
+  readClock,
+  sha256,
+} from "./internal/durable-shared.ts"
+import type {
+  ApprovalConsumeResult,
+  ApprovalRecord,
+  ApprovalStore,
+} from "./internal/durable-types.ts"
+
+const decoder = new TextDecoder()
+
+function base64UrlToBytes(value: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]+$/u.test(value)) throw new ApprovalTokenInvalidError()
+  const padded = value
+    .replaceAll("-", "+")
+    .replaceAll("_", "/")
+    .padEnd(Math.ceil(value.length / 4) * 4, "=")
+  let binary: string
+  try {
+    binary = atob(padded)
+  } catch {
+    throw new ApprovalTokenInvalidError()
+  }
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0))
+}
+// Durable human approval with signed, single-use resume tokens
+
+export class ApprovalRequiredError extends Error {
+  readonly approvalId: string
+  readonly effectId: string
+  readonly resumeToken!: string
+  readonly expiresAt: number
+
+  constructor(approvalId: string, effectId: string, resumeToken: string, expiresAt: number) {
+    super("capability approval is required")
+    this.approvalId = approvalId
+    this.effectId = effectId
+    this.expiresAt = expiresAt
+    Object.defineProperty(this, "resumeToken", {
+      value: resumeToken,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    })
+    this.name = "ApprovalRequiredError"
+  }
+}
+
+export class ApprovalTokenInvalidError extends Error {
+  constructor() {
+    super("approval resume token is invalid")
+    this.name = "ApprovalTokenInvalidError"
+  }
+}
+export class ApprovalTokenExpiredError extends Error {
+  constructor() {
+    super("approval resume token has expired")
+    this.name = "ApprovalTokenExpiredError"
+  }
+}
+export class ApprovalTokenReplayError extends Error {
+  constructor() {
+    super("approval resume token has already been consumed")
+    this.name = "ApprovalTokenReplayError"
+  }
+}
+export class ApprovalBindingError extends Error {
+  constructor() {
+    super("approval resume token is bound to another tenant or principal")
+    this.name = "ApprovalBindingError"
+  }
+}
+export class ApprovalPendingError extends Error {
+  constructor() {
+    super("capability approval is still pending")
+    this.name = "ApprovalPendingError"
+  }
+}
+export class ApprovalDeniedError extends Error {
+  constructor() {
+    super("capability approval was denied")
+    this.name = "ApprovalDeniedError"
+  }
+}
+
+interface ResumeClaims {
+  readonly v: 1
+  readonly id: string
+  readonly nonce: string
+  readonly exp: number
+}
+
+export interface ApprovalCoordinator extends CapabilityApprovalGate {
+  decide(input: {
+    readonly approvalId: string
+    readonly tenantId: string
+    readonly decision: "approved" | "denied"
+    readonly decidedBy: string
+  }): Promise<void>
+  get(approvalId: string): Promise<ApprovalRecord | undefined>
+}
+
+export interface ApprovalCoordinatorOptions {
+  readonly store: ApprovalStore
+  /** At least 32 random bytes, kept separately from the approval store. */
+  readonly secret: Uint8Array
+  readonly ttlMs?: number
+  readonly now?: () => number
+  /** Tests/local development only. Production approval records require a durable store. */
+  readonly allowMemoryStore?: boolean
+}
+
+export function createApprovalCoordinator(
+  options: ApprovalCoordinatorOptions,
+): ApprovalCoordinator {
+  if (options.store.durability !== "durable" && options.allowMemoryStore !== true) {
+    throw new TypeError('approval coordinator requires store.durability === "durable"')
+  }
+  if (!(options.secret instanceof Uint8Array) || options.secret.byteLength < 32) {
+    throw new TypeError("approval secret must contain at least 32 random bytes")
+  }
+  const secret = new Uint8Array(options.secret)
+  const ttlMs = options.ttlMs ?? 15 * 60_000
+  assertPositiveMs(ttlMs, "approval ttlMs")
+  const clock = options.now ?? Date.now
+  const now = (): number => readClock(clock, "approval clock")
+  const key = crypto.subtle.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify",
+  ])
+
+  const sign = async (claims: ResumeClaims): Promise<string> => {
+    const payload = bytesToBase64Url(encoder.encode(JSON.stringify(claims)))
+    const signature = new Uint8Array(
+      await crypto.subtle.sign("HMAC", await key, encoder.encode(payload)),
+    )
+    return `v1.${payload}.${bytesToBase64Url(signature)}`
+  }
+  const verify = async (token: string): Promise<ResumeClaims> => {
+    if (typeof token !== "string" || token.length > 2048) throw new ApprovalTokenInvalidError()
+    const parts = token.split(".")
+    if (parts.length !== 3 || parts[0] !== "v1") throw new ApprovalTokenInvalidError()
+    const payload = parts[1] as string
+    const valid = await crypto.subtle.verify(
+      "HMAC",
+      await key,
+      base64UrlToBytes(parts[2] as string).buffer as ArrayBuffer,
+      encoder.encode(payload),
+    )
+    if (!valid) throw new ApprovalTokenInvalidError()
+    let claims: unknown
+    try {
+      claims = JSON.parse(decoder.decode(base64UrlToBytes(payload)))
+    } catch {
+      throw new ApprovalTokenInvalidError()
+    }
+    if (typeof claims !== "object" || claims === null) throw new ApprovalTokenInvalidError()
+    const candidate = claims as Partial<ResumeClaims>
+    if (
+      candidate.v !== 1 ||
+      typeof candidate.id !== "string" ||
+      typeof candidate.nonce !== "string" ||
+      !Number.isSafeInteger(candidate.exp)
+    ) {
+      throw new ApprovalTokenInvalidError()
+    }
+    assertToken(candidate.id, "approval id", 128)
+    assertToken(candidate.nonce, "approval nonce", 128)
+    if ((candidate.exp as number) <= now()) throw new ApprovalTokenExpiredError()
+    return candidate as ResumeClaims
+  }
+
+  const coordinator: ApprovalCoordinator = {
+    async authorize(input: Parameters<CapabilityApprovalGate["authorize"]>[0]) {
+      if (input.signal.aborted) throw input.signal.reason
+      assertToken(input.identity.tenantId, "approval tenantId")
+      assertToken(input.identity.principalId, "approval principalId")
+      if (input.resumeToken === undefined) {
+        const approvalId = crypto.randomUUID()
+        const nonce = bytesToBase64Url(crypto.getRandomValues(new Uint8Array(18)))
+        const issuedAt = now()
+        const expiresAt = addDuration(issuedAt, ttlMs, "approval expiry")
+        const resumeToken = await sign({ v: 1, id: approvalId, nonce, exp: expiresAt })
+        const accepted = await options.store.create(
+          Object.freeze({
+            approvalId,
+            effectId: input.effectId,
+            capability: input.capability,
+            ...(input.target === undefined ? {} : { target: input.target }),
+            ...(input.digest === undefined ? {} : { digest: input.digest }),
+            tenantId: input.identity.tenantId,
+            principalId: input.identity.principalId,
+            tokenHash: await sha256(resumeToken),
+            state: "pending" as const,
+            createdAt: issuedAt,
+            expiresAt,
+            updatedAt: issuedAt,
+            version: 1,
+          }),
+        )
+        if (!accepted) throw new Error("approval store rejected a unique approval id")
+        throw new ApprovalRequiredError(approvalId, input.effectId, resumeToken, expiresAt)
+      }
+      const claims = await verify(input.resumeToken)
+      const consumed = await options.store.consume({
+        approvalId: claims.id,
+        tenantId: input.identity.tenantId,
+        principalId: input.identity.principalId,
+        capability: input.capability,
+        ...(input.target === undefined ? {} : { target: input.target }),
+        ...(input.digest === undefined ? {} : { digest: input.digest }),
+        tokenHash: await sha256(input.resumeToken),
+        now: now(),
+      })
+      if (consumed.state === "consumed") return
+      if (consumed.state === "replay") throw new ApprovalTokenReplayError()
+      if (consumed.state === "binding") throw new ApprovalBindingError()
+      if (consumed.state === "expired") throw new ApprovalTokenExpiredError()
+      if (consumed.state === "pending") throw new ApprovalPendingError()
+      if (consumed.state === "denied") throw new ApprovalDeniedError()
+      throw new ApprovalTokenInvalidError()
+    },
+    async decide(input: Parameters<ApprovalCoordinator["decide"]>[0]) {
+      assertToken(input.approvalId, "approval id", 128)
+      assertToken(input.tenantId, "approval tenantId")
+      assertToken(input.decidedBy, "approval decidedBy")
+      const accepted = await options.store.decide({ ...input, now: now() })
+      if (!accepted) throw new Error("approval decision rejected")
+    },
+    async get(approvalId: string) {
+      assertToken(approvalId, "approval id", 128)
+      return await options.store.get(approvalId)
+    },
+  }
+  return Object.freeze(coordinator)
+}
+
+export class MemoryApprovalStore implements ApprovalStore {
+  readonly durability = "memory" as const
+  private readonly records = new Map<string, ApprovalRecord>()
+
+  create(record: ApprovalRecord): boolean {
+    if (this.records.has(record.approvalId)) return false
+    this.records.set(record.approvalId, Object.freeze(cloneValue(record)))
+    return true
+  }
+  get(approvalId: string): ApprovalRecord | undefined {
+    const record = this.records.get(approvalId)
+    return record === undefined ? undefined : Object.freeze(cloneValue(record))
+  }
+  decide(input: Parameters<ApprovalStore["decide"]>[0]): boolean {
+    const record = this.records.get(input.approvalId)
+    const next = durableApprovalProtocol.decide(record, input)
+    if (next === undefined) return false
+    this.records.set(input.approvalId, Object.freeze(next))
+    return true
+  }
+  consume(input: Parameters<ApprovalStore["consume"]>[0]): ApprovalConsumeResult {
+    const record = this.records.get(input.approvalId)
+    const transition = durableApprovalProtocol.consume(record, input)
+    if (transition.next !== undefined)
+      this.records.set(input.approvalId, Object.freeze(transition.next))
+    return transition.result
+  }
+  list(): readonly ApprovalRecord[] {
+    return Object.freeze(
+      [...this.records.values()].map((record) => Object.freeze(cloneValue(record))),
+    )
+  }
+}
+
+// -------------------------------------------------------------------------------------------------

package/src/durable-effect.ts

@@ -0,0 +1,300 @@
+import { type EffectLifecycleObserver, emitEffectLifecycle } from "./effect-lifecycle.ts"
+import type { CapabilityExecutionJournal } from "./internal/capability-runtime.ts"
+import { validCapabilityId } from "./internal/capability-runtime.ts"
+import { durableEffectProtocol } from "./internal/durable-effect-protocol.ts"
+import {
+  assertTimestamp,
+  assertToken,
+  bucketAdd,
+  bucketMove,
+  cloneValue,
+  ERROR_CODE,
+  indexedScan,
+  MAX_RECONCILIATION_LIMIT,
+  memoryScan,
+  readClock,
+  reconciliationLimit,
+} from "./internal/durable-shared.ts"
+import type {
+  DurableEffectRecord,
+  DurableEffectState,
+  DurableEffectStore,
+  ReconciliationPage,
+  ReconciliationScanOptions,
+  ReconciliationScanPage,
+} from "./internal/durable-types.ts"
+// Durable effect journal + reconciliation
+
+export class DurableEffectTransitionError extends Error {
+  constructor(
+    public readonly effectId: string,
+    public readonly transition: string,
+  ) {
+    super(`durable effect ${effectId}: ${transition} transition was rejected`)
+    this.name = "DurableEffectTransitionError"
+  }
+}
+
+export interface DurableEffectJournalOptions {
+  readonly store: DurableEffectStore
+  readonly now?: () => number
+  /** Tests/local development only. Production journals require `store.durability === "durable"`. */
+  readonly allowMemoryStore?: boolean
+}
+
+export function createDurableEffectJournal(
+  options: DurableEffectJournalOptions,
+): CapabilityExecutionJournal {
+  if (options.store.durability !== "durable" && options.allowMemoryStore !== true) {
+    throw new TypeError('durable effect journal requires store.durability === "durable"')
+  }
+  const clock = options.now ?? Date.now
+  const now = (): number => readClock(clock, "durable effect clock")
+
+  const current = async (effectId: string): Promise<DurableEffectRecord> => {
+    assertToken(effectId, "durable effect id", 64)
+    const record = await options.store.get(effectId)
+    if (record === undefined) throw new DurableEffectTransitionError(effectId, "missing")
+    if (
+      record.effectId !== effectId ||
+      !validCapabilityId(record.capability) ||
+      !["admission", "executing", "committed", "failed", "unknown"].includes(record.state) ||
+      !Number.isSafeInteger(record.version) ||
+      record.version < 1
+    ) {
+      throw new TypeError(`durable effect ${effectId}: store returned an invalid record`)
+    }
+    assertTimestamp(record.createdAt, "durable effect createdAt")
+    assertTimestamp(record.updatedAt, "durable effect updatedAt")
+    if (record.createdAt > record.updatedAt)
+      throw new TypeError(`durable effect ${effectId}: updatedAt precedes createdAt`)
+    if (record.target !== undefined) assertToken(record.target, "stored durable effect target", 128)
+    if (record.digest !== undefined && !/^[0-9a-f]{64}$/u.test(record.digest))
+      throw new TypeError(`durable effect ${effectId}: store returned an invalid digest`)
+    if (record.tenantId !== undefined)
+      assertToken(record.tenantId, "stored durable effect tenantId")
+    if (record.principalId !== undefined)
+      assertToken(record.principalId, "stored durable effect principalId")
+    if ((record.tenantId === undefined) !== (record.principalId === undefined))
+      throw new TypeError(`durable effect ${effectId}: store returned a partial identity`)
+    if (record.errorCode !== undefined && !ERROR_CODE.test(record.errorCode))
+      throw new TypeError(`durable effect ${effectId}: store returned an invalid error code`)
+    return record
+  }
+  const transition = async (
+    effectId: string,
+    from: DurableEffectState,
+    to: DurableEffectState,
+    errorCode?: string,
+  ): Promise<void> => {
+    const record = await current(effectId)
+    const next = durableEffectProtocol.transition(record, {
+      effectId,
+      version: record.version,
+      from,
+      to,
+      updatedAt: now(),
+      ...(errorCode === undefined ? {} : { errorCode }),
+    })
+    if (next === undefined) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
+    const accepted = await options.store.transition({
+      effectId,
+      version: record.version,
+      from,
+      to,
+      updatedAt: next.updatedAt,
+      ...(errorCode === undefined ? {} : { errorCode }),
+    })
+    if (!accepted) throw new DurableEffectTransitionError(effectId, `${from}->${to}`)
+  }
+
+  const journal: CapabilityExecutionJournal = {
+    async intent(input) {
+      assertToken(input.effectId, "durable effect id", 64)
+      if (!validCapabilityId(input.capability))
+        throw new TypeError("durable effect capability is invalid")
+      if (input.target !== undefined) assertToken(input.target, "durable effect target", 128)
+      if (input.digest !== undefined && !/^[0-9a-f]{64}$/u.test(input.digest))
+        throw new TypeError("durable effect digest is invalid")
+      if (input.identity !== undefined) {
+        assertToken(input.identity.tenantId, "durable effect tenantId")
+        assertToken(input.identity.principalId, "durable effect principalId")
+      }
+      const at = now()
+      const accepted = await options.store.create(
+        Object.freeze({
+          effectId: input.effectId,
+          capability: input.capability,
+          ...(input.target === undefined ? {} : { target: input.target }),
+          ...(input.digest === undefined ? {} : { digest: input.digest }),
+          ...(input.identity === undefined
+            ? {}
+            : { tenantId: input.identity.tenantId, principalId: input.identity.principalId }),
+          state: "admission" as const,
+          createdAt: at,
+          updatedAt: at,
+          version: 1,
+        }),
+      )
+      if (!accepted) throw new DurableEffectTransitionError(input.effectId, "create")
+    },
+    async executing(effectId) {
+      await transition(effectId, "admission", "executing")
+    },
+    async committed(effectId) {
+      await transition(effectId, "executing", "committed")
+    },
+    async failed(effectId, input) {
+      if (!ERROR_CODE.test(input.errorCode))
+        throw new TypeError("durable effect errorCode is invalid")
+      const record = await current(effectId)
+      const to = input.began ? "unknown" : "failed"
+      const next = durableEffectProtocol.transition(record, {
+        effectId,
+        version: record.version,
+        from: record.state,
+        to,
+        updatedAt: now(),
+        errorCode: input.errorCode,
+      })
+      if (next === undefined)
+        throw new DurableEffectTransitionError(effectId, `${record.state}->${to}`)
+      const accepted = await options.store.transition({
+        effectId,
+        version: record.version,
+        from: record.state,
+        to,
+        updatedAt: next.updatedAt,
+        errorCode: input.errorCode,
+      })
+      if (!accepted) throw new DurableEffectTransitionError(effectId, `${record.state}->${to}`)
+    },
+  }
+  return Object.freeze(journal)
+}
+
+export class MemoryDurableEffectStore implements DurableEffectStore {
+  readonly durability = "memory" as const
+  private readonly records = new Map<string, DurableEffectRecord>()
+  // Secondary index: effectIds grouped by state, so reconciliation scans only the requested (few,
+  // non-terminal) states instead of walking every retained record. See {@link indexedScan}.
+  private readonly byState = new Map<DurableEffectState, Set<string>>()
+
+  create(record: DurableEffectRecord): boolean {
+    if (this.records.has(record.effectId)) return false
+    this.records.set(record.effectId, Object.freeze(cloneValue(record)))
+    bucketAdd(this.byState, record.state, record.effectId)
+    return true
+  }
+
+  get(effectId: string): DurableEffectRecord | undefined {
+    const record = this.records.get(effectId)
+    return record === undefined ? undefined : Object.freeze(cloneValue(record))
+  }
+
+  transition(input: Parameters<DurableEffectStore["transition"]>[0]): boolean {
+    const current = this.records.get(input.effectId)
+    const next = durableEffectProtocol.transition(current, input)
+    if (next === undefined) return false
+    if (current === undefined) return false
+    this.records.set(input.effectId, Object.freeze(next))
+    bucketMove(this.byState, current.state, input.to, input.effectId)
+    return true
+  }
+
+  list(): readonly DurableEffectRecord[] {
+    return Object.freeze(
+      [...this.records.values()].map((record) => Object.freeze(cloneValue(record))),
+    )
+  }
+
+  scan(
+    input: ReconciliationScanOptions<DurableEffectState>,
+  ): ReconciliationScanPage<DurableEffectRecord> {
+    return indexedScan(this.byState, (id) => this.records.get(id), input)
+  }
+}
+
+export interface EffectReconciliationFinding {
+  readonly effectId: string
+  readonly capability: string
+  readonly state: "incomplete" | "ambiguous"
+  readonly updatedAt: number
+}
+
+async function scanEffectRecords(
+  store: DurableEffectStore,
+  input: ReconciliationScanOptions<DurableEffectState>,
+): Promise<ReconciliationScanPage<DurableEffectRecord>> {
+  if (store.scan !== undefined) return await store.scan(input)
+  if (store.list === undefined) throw new TypeError("effect store does not support reconciliation")
+  return memoryScan(await store.list(), input)
+}
+
+export async function reconcileEffectsPage(
+  store: DurableEffectStore,
+  options: {
+    readonly staleBefore: number
+    readonly observer?: EffectLifecycleObserver
+    readonly cursor?: string
+    readonly limit?: number
+  },
+): Promise<ReconciliationPage<EffectReconciliationFinding>> {
+  const findings: EffectReconciliationFinding[] = []
+  const page = await scanEffectRecords(store, {
+    states: ["admission", "executing", "unknown"],
+    updatedBefore: options.staleBefore,
+    ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+    limit: reconciliationLimit(options.limit),
+  })
+  for (const record of page.records) {
+    if (!validCapabilityId(record.capability) || !/^[!-~]{1,64}$/u.test(record.effectId)) continue
+    if (record.updatedAt > options.staleBefore) continue
+    const state =
+      record.state === "admission"
+        ? "incomplete"
+        : record.state === "executing" || record.state === "unknown"
+          ? "ambiguous"
+          : undefined
+    if (state === undefined) continue
+    findings.push(
+      Object.freeze({
+        effectId: record.effectId,
+        capability: record.capability,
+        state,
+        updatedAt: record.updatedAt,
+      }),
+    )
+    if (options.observer !== undefined) {
+      emitEffectLifecycle([options.observer], {
+        effectId: record.effectId,
+        capability: record.capability,
+        stage: "reconciliation",
+        phase: state === "ambiguous" ? "ambiguous" : "failed",
+        errorCode: state === "ambiguous" ? "effect_ambiguous" : "effect_incomplete",
+      })
+    }
+  }
+  return Object.freeze({
+    findings: Object.freeze(findings),
+    ...(page.cursor === undefined ? {} : { cursor: page.cursor }),
+  })
+}
+
+export async function reconcileEffects(
+  store: DurableEffectStore,
+  options: { readonly staleBefore: number; readonly observer?: EffectLifecycleObserver },
+): Promise<readonly EffectReconciliationFinding[]> {
+  const page = await reconcileEffectsPage(store, {
+    ...options,
+    limit: MAX_RECONCILIATION_LIMIT,
+  })
+  if (page.cursor !== undefined) {
+    throw new RangeError(
+      `effect reconciliation exceeds ${MAX_RECONCILIATION_LIMIT} records; use reconcileEffectsPage()`,
+    )
+  }
+  return page.findings
+}
+
+// -------------------------------------------------------------------------------------------------