@kashscript/hudhud 0.1.0

package/src/adapters/prisma.ts

@@ -0,0 +1,310 @@
+// ============================================================================
+// @kashscript/hudhud/adapters/prisma — durable store adapters (schema-free)
+// ----------------------------------------------------------------------------
+// hudhud ships the STORE INTERFACES (ledger, anchor-receipt, exception, DID);
+// the in-memory references live beside them. This subpath ships the DURABLE
+// adapters WITHOUT a `@prisma/client` dependency: each adapter is constructed
+// over a NARROW STRUCTURAL DELEGATE — the small `{ create, findFirst, findMany,
+// count }` surface hudhud actually calls, typed over the row shape hudhud
+// needs. A venture's generated `PrismaClient.<model>` (with matching columns +
+// a `Json` payload column) satisfies the delegate, so the venture wires:
+//
+//     new PrismaLedgerStore(prisma.ledgerBlock)
+//
+// The concrete Prisma SCHEMA (migrations, indexes, column types) is venture-side
+// and lands at the swap. Keeping hudhud schema-free is deliberate (guard b):
+// the protocol owns the CONTRACT; the venture owns the storage.
+// ============================================================================
+
+import type { LedgerBlockInput, LedgerBlockRecord, LedgerStore } from "../ledger/store";
+import type {
+  AnchorRecord,
+  AnchorReceiptRecord,
+  AnchorReceiptStore,
+  AnchorWitness,
+  ChainTip,
+} from "../anchor";
+import type {
+  ExceptionClassificationRecord,
+  ExceptionClassificationStore,
+  FailureClass,
+} from "../exception";
+import type { DidPublicKey, DidRegistry } from "../did-registry";
+
+/** A JSON scalar as Prisma surfaces it (`Json` column). */
+type Json = unknown;
+
+/** Prisma's model methods return `PrismaPromise<T>` (a `Promise<T>`); the
+ *  narrow delegates below type only the arg subset hudhud passes + a `Promise`
+ *  return, so a generated delegate is assignable. */
+
+// ── Ledger ──────────────────────────────────────────────────────────────────
+
+export interface LedgerBlockRow {
+  readonly sessionId: string;
+  readonly stepIndex: number;
+  readonly previousBlockHash: string;
+  readonly currentTransactionBlockHash: string;
+  readonly actorDid: string;
+  readonly payloadMutation: Json;
+  readonly signature: string;
+  readonly emittedAt: string;
+  readonly localId: number;
+}
+
+/** The subset of `PrismaClient.ledgerBlock` hudhud calls. `localId`/`emittedAt`
+ *  are DB-assigned (autoincrement + default now()), so `create` omits them and
+ *  the created row carries them back. */
+export interface PrismaLedgerDelegate {
+  create(args: {
+    data: Omit<LedgerBlockRow, "localId" | "emittedAt"> & { emittedAt?: string };
+  }): Promise<LedgerBlockRow>;
+  findFirst(args: {
+    where: { sessionId: string };
+    orderBy: { stepIndex: "asc" | "desc" };
+  }): Promise<LedgerBlockRow | null>;
+  findMany(args: {
+    where: { sessionId: string };
+    orderBy: { stepIndex: "asc" | "desc" };
+  }): Promise<ReadonlyArray<LedgerBlockRow>>;
+  count(args: { where: { sessionId: string } }): Promise<number>;
+}
+
+function rowToLedgerRecord(row: LedgerBlockRow): LedgerBlockRecord {
+  return {
+    sessionId: row.sessionId,
+    stepIndex: row.stepIndex,
+    previousBlockHash: row.previousBlockHash,
+    currentTransactionBlockHash: row.currentTransactionBlockHash,
+    actorDid: row.actorDid,
+    payloadMutation: (row.payloadMutation ?? {}) as Readonly<Record<string, unknown>>,
+    signature: row.signature,
+    emittedAt: row.emittedAt,
+    localId: row.localId,
+  };
+}
+
+/** {@link LedgerStore} over a Prisma `ledgerBlock` delegate. Append-only; the
+ *  DB's `(sessionId, stepIndex)` UNIQUE constraint is what enforces the gap-free
+ *  chain under concurrency (the in-memory store checks it in JS). */
+export class PrismaLedgerStore implements LedgerStore {
+  constructor(private readonly delegate: PrismaLedgerDelegate) {}
+
+  async appendBlock(input: LedgerBlockInput): Promise<LedgerBlockRecord> {
+    const row = await this.delegate.create({
+      data: {
+        sessionId: input.sessionId,
+        stepIndex: input.stepIndex,
+        previousBlockHash: input.previousBlockHash,
+        currentTransactionBlockHash: input.currentTransactionBlockHash,
+        actorDid: input.actorDid,
+        payloadMutation: input.payloadMutation as Json,
+        signature: input.signature,
+      },
+    });
+    return rowToLedgerRecord(row);
+  }
+
+  async latestBlockForSession(sessionId: string): Promise<LedgerBlockRecord | null> {
+    const row = await this.delegate.findFirst({ where: { sessionId }, orderBy: { stepIndex: "desc" } });
+    return row === null ? null : rowToLedgerRecord(row);
+  }
+
+  async countBlocksForSession(sessionId: string): Promise<number> {
+    return this.delegate.count({ where: { sessionId } });
+  }
+
+  async listBlocksForSession(sessionId: string): Promise<ReadonlyArray<LedgerBlockRecord>> {
+    const rows = await this.delegate.findMany({ where: { sessionId }, orderBy: { stepIndex: "asc" } });
+    return rows.map(rowToLedgerRecord);
+  }
+}
+
+// ── Anchor receipts ───────────────────────────────────────────────────────────
+
+export interface AnchorReceiptRow {
+  readonly id: string;
+  readonly publishedAt: string;
+  readonly merkleRoot: string;
+  readonly tipCount: number;
+  readonly tips: Json;
+  readonly witness: Json;
+  readonly createdAt: string;
+}
+
+export interface PrismaAnchorReceiptDelegate {
+  create(args: { data: Omit<AnchorReceiptRow, "id" | "createdAt"> & { id?: string; createdAt?: string } }): Promise<AnchorReceiptRow>;
+  findFirst(args: {
+    where?: { merkleRoot?: string };
+    orderBy: { createdAt: "asc" | "desc" };
+  }): Promise<AnchorReceiptRow | null>;
+  findMany(args: { orderBy: { createdAt: "asc" | "desc" } }): Promise<ReadonlyArray<AnchorReceiptRow>>;
+}
+
+function rowToAnchorReceipt(row: AnchorReceiptRow): AnchorReceiptRecord {
+  return {
+    id: row.id,
+    publishedAt: row.publishedAt,
+    merkleRoot: row.merkleRoot,
+    tipCount: row.tipCount,
+    tips: (row.tips ?? []) as ReadonlyArray<ChainTip>,
+    createdAt: row.createdAt,
+    ...(row.witness ? { witness: row.witness as AnchorWitness } : {}),
+  };
+}
+
+/** {@link AnchorReceiptStore} over a Prisma `anchorReceipt` delegate. */
+export class PrismaAnchorReceiptStore implements AnchorReceiptStore {
+  constructor(private readonly delegate: PrismaAnchorReceiptDelegate) {}
+
+  async append(record: AnchorRecord): Promise<AnchorReceiptRecord> {
+    const row = await this.delegate.create({
+      data: {
+        publishedAt: record.publishedAt,
+        merkleRoot: record.merkleRoot,
+        tipCount: record.tipCount,
+        tips: record.tips as Json,
+        witness: (record.witness ?? null) as Json,
+      },
+    });
+    return rowToAnchorReceipt(row);
+  }
+
+  async latest(): Promise<AnchorReceiptRecord | null> {
+    const row = await this.delegate.findFirst({ orderBy: { createdAt: "desc" } });
+    return row === null ? null : rowToAnchorReceipt(row);
+  }
+
+  async history(): Promise<ReadonlyArray<AnchorReceiptRecord>> {
+    const rows = await this.delegate.findMany({ orderBy: { createdAt: "asc" } });
+    return rows.map(rowToAnchorReceipt);
+  }
+
+  async latestForRoot(merkleRoot: string): Promise<AnchorReceiptRecord | null> {
+    const row = await this.delegate.findFirst({ where: { merkleRoot }, orderBy: { createdAt: "desc" } });
+    return row === null ? null : rowToAnchorReceipt(row);
+  }
+}
+
+// ── Exception classifications ─────────────────────────────────────────────────
+
+export interface ExceptionClassificationRow {
+  readonly id: string;
+  readonly schemaVersion: string;
+  readonly timestampIso: string;
+  readonly workflowId: string;
+  readonly sopVersion: string;
+  readonly inputRef: string;
+  readonly contentHash: string;
+  readonly model: string;
+  readonly modelVersion: string;
+  readonly failureClass: string;
+  readonly failureTag: string;
+  readonly operatorDid: string;
+  readonly resolutionSummary: string;
+  readonly resolutionActionRefs: Json;
+  readonly escalationId: string | null;
+  readonly signoffLedgerStepIndex: number | null;
+  readonly signedEnvelope: Json;
+}
+
+export interface PrismaExceptionClassificationDelegate {
+  create(args: { data: ExceptionClassificationRow }): Promise<unknown>;
+  findMany(args: {
+    where?: { workflowId?: string };
+    orderBy: { timestampIso: "asc" | "desc" };
+  }): Promise<ReadonlyArray<ExceptionClassificationRow>>;
+  findFirst(args: { orderBy: { timestampIso: "asc" | "desc" } }): Promise<ExceptionClassificationRow | null>;
+}
+
+function rowToClassification(row: ExceptionClassificationRow): ExceptionClassificationRecord {
+  return {
+    id: row.id,
+    schemaVersion: row.schemaVersion,
+    timestampIso: row.timestampIso,
+    workflowId: row.workflowId,
+    sopVersion: row.sopVersion,
+    inputRef: row.inputRef,
+    contentHash: row.contentHash,
+    model: row.model,
+    modelVersion: row.modelVersion,
+    failureClass: row.failureClass as FailureClass,
+    failureTag: row.failureTag,
+    operatorDid: row.operatorDid,
+    resolutionSummary: row.resolutionSummary,
+    resolutionActionRefs: (row.resolutionActionRefs ?? []) as ReadonlyArray<string>,
+    escalationId: row.escalationId,
+    signoffLedgerStepIndex: row.signoffLedgerStepIndex,
+    signedEnvelope: row.signedEnvelope as ExceptionClassificationRecord["signedEnvelope"],
+  };
+}
+
+/** {@link ExceptionClassificationStore} over a Prisma delegate. Signatures live
+ *  in the row (`signedEnvelope` JSON), so verification survives the round-trip. */
+export class PrismaExceptionClassificationStore implements ExceptionClassificationStore {
+  constructor(private readonly delegate: PrismaExceptionClassificationDelegate) {}
+
+  async append(record: ExceptionClassificationRecord): Promise<void> {
+    await this.delegate.create({
+      data: {
+        id: record.id,
+        schemaVersion: record.schemaVersion,
+        timestampIso: record.timestampIso,
+        workflowId: record.workflowId,
+        sopVersion: record.sopVersion,
+        inputRef: record.inputRef,
+        contentHash: record.contentHash,
+        model: record.model,
+        modelVersion: record.modelVersion,
+        failureClass: record.failureClass,
+        failureTag: record.failureTag,
+        operatorDid: record.operatorDid,
+        resolutionSummary: record.resolutionSummary,
+        resolutionActionRefs: record.resolutionActionRefs as Json,
+        escalationId: record.escalationId,
+        signoffLedgerStepIndex: record.signoffLedgerStepIndex,
+        signedEnvelope: record.signedEnvelope as Json,
+      },
+    });
+  }
+
+  async history(): Promise<ReadonlyArray<ExceptionClassificationRecord>> {
+    const rows = await this.delegate.findMany({ orderBy: { timestampIso: "asc" } });
+    return rows.map(rowToClassification);
+  }
+
+  async latest(): Promise<ExceptionClassificationRecord | null> {
+    const row = await this.delegate.findFirst({ orderBy: { timestampIso: "desc" } });
+    return row === null ? null : rowToClassification(row);
+  }
+
+  async byWorkflow(workflowId: string): Promise<ReadonlyArray<ExceptionClassificationRecord>> {
+    const rows = await this.delegate.findMany({ where: { workflowId }, orderBy: { timestampIso: "asc" } });
+    return rows.map(rowToClassification);
+  }
+}
+
+// ── DID registry ──────────────────────────────────────────────────────────────
+
+export interface DidKeyRow {
+  readonly did: string;
+  /** 32-byte Ed25519 public key. Prisma `Bytes` surfaces as a `Uint8Array`. */
+  readonly publicKeyBytes: Uint8Array;
+  readonly algorithm: string;
+}
+
+export interface PrismaDidKeyDelegate {
+  findUnique(args: { where: { did: string } }): Promise<DidKeyRow | null>;
+}
+
+/** {@link DidRegistry} over a Prisma `didKey` delegate — resolve-only (the ledger
+ *  needs only the read side; registration/PDS resolution is venture-side). */
+export class PrismaDidRegistry implements DidRegistry {
+  constructor(private readonly delegate: PrismaDidKeyDelegate) {}
+
+  async resolve(did: string): Promise<DidPublicKey | null> {
+    const row = await this.delegate.findUnique({ where: { did } });
+    if (row === null) return null;
+    return { did: row.did, publicKeyBytes: new Uint8Array(row.publicKeyBytes), algorithm: "ed25519" };
+  }
+}

package/src/anchor/index.ts

@@ -0,0 +1,149 @@
+// ============================================================================
+// @kashscript/hudhud/anchor — external chain-tip anchoring + receipt store
+// ----------------------------------------------------------------------------
+// Periodic out-of-band publication of session chain tips: an attacker who
+// rewrites the whole ledger consistently still can't rewrite an anchor
+// published OUTSIDE the DB, so the auditor cross-checks the DB chain's latest
+// hash against the anchor. Ships the interface + a merkle-root helper + an
+// in-memory anchor and receipt store; the public witness (Rekor/OTS) is
+// attest's `witness`, and the node-fs FileChainAnchor is a deployment adapter
+// (kept out to keep hudhud edge-safe). Ported from the oreoasis-core-host engine.
+// ============================================================================
+
+import { sha256Hex } from "@kashscript/attest";
+
+export interface ChainTip {
+  readonly sessionId: string;
+  readonly latestHash: string;
+  readonly latestStepIndex: number;
+}
+
+export type AnchorWitnessBackend = "rekor" | "opentimestamps" | "none";
+
+export interface AnchorWitness {
+  readonly backend: AnchorWitnessBackend;
+  readonly receipt: Readonly<Record<string, unknown>>;
+  readonly witnessedAt: string | null;
+}
+
+export interface AnchorRecord {
+  readonly publishedAt: string;
+  /** Merkle root over (sessionId, latestHash, stepIndex) triples, sorted by sessionId. */
+  readonly merkleRoot: string;
+  readonly tipCount: number;
+  readonly tips: ReadonlyArray<ChainTip>;
+  readonly witness?: AnchorWitness;
+}
+
+export interface ChainAnchor {
+  publish(tips: ReadonlyArray<ChainTip>): Promise<AnchorRecord>;
+  history(): Promise<ReadonlyArray<AnchorRecord>>;
+  latest(): Promise<AnchorRecord | null>;
+}
+
+/** Deterministic SHA-256-over-sorted-tip-triples root. Simpler than a binary
+ *  Merkle tree — the anchor's job is just to be unrewritable; the cross-check
+ *  against the per-session chain hash is what proves tamper. */
+export async function computeAnchorMerkleRoot(tips: ReadonlyArray<ChainTip>): Promise<string> {
+  const sorted = [...tips].sort((a, b) => (a.sessionId < b.sessionId ? -1 : 1));
+  const enc = new TextEncoder();
+  let acc = new Uint8Array(0);
+  // ⚠️ audit r1 F1 (KNOWN, deferred, wire-compatible with attest's witness anchor):
+  // this newline join is not injective. The injective fix is a wire-format change
+  // that would invalidate anchors a venture has already witnessed, so it lands
+  // behind a coordinated anchor-format v2 at the venture swap — see
+  // specs/hudhud-audit-r1.md. Kept byte-identical to attest for now.
+  for (const t of sorted) {
+    const segment = enc.encode(`${t.sessionId}\n${t.latestHash}\n${t.latestStepIndex}\n`);
+    const next = new Uint8Array(acc.length + segment.length);
+    next.set(acc);
+    next.set(segment, acc.length);
+    acc = next;
+  }
+  return sha256Hex(acc);
+}
+
+function frozenRecord(tips: ReadonlyArray<ChainTip>, merkleRoot: string, publishedAt: string): AnchorRecord {
+  return Object.freeze({
+    publishedAt,
+    merkleRoot,
+    tipCount: tips.length,
+    tips: Object.freeze(tips.map((t) => Object.freeze({ ...t }))),
+  });
+}
+
+/** In-memory anchor — records publications for inspection. A legitimate
+ *  dev/test backend (the anchor is then witnessed for the process lifetime). */
+export class NullChainAnchor implements ChainAnchor {
+  private readonly records: AnchorRecord[] = [];
+
+  async publish(tips: ReadonlyArray<ChainTip>): Promise<AnchorRecord> {
+    const record = frozenRecord(tips, await computeAnchorMerkleRoot(tips), new Date().toISOString());
+    this.records.push(record);
+    return record;
+  }
+
+  async history(): Promise<ReadonlyArray<AnchorRecord>> {
+    return [...this.records];
+  }
+
+  async latest(): Promise<AnchorRecord | null> {
+    return this.records.length === 0 ? null : this.records[this.records.length - 1]!;
+  }
+}
+
+// ── Anchor receipt store (persistence of witnessed anchors) ────────────────
+
+export interface AnchorReceiptRecord extends AnchorRecord {
+  readonly id: string;
+  readonly createdAt: string;
+}
+
+export interface AnchorReceiptStore {
+  append(record: AnchorRecord): Promise<AnchorReceiptRecord>;
+  latest(): Promise<AnchorReceiptRecord | null>;
+  history(): Promise<ReadonlyArray<AnchorReceiptRecord>>;
+  latestForRoot(merkleRoot: string): Promise<AnchorReceiptRecord | null>;
+}
+
+let lastIdMicros = 0;
+function newReceiptId(): string {
+  let micros = Date.now() * 1000;
+  if (micros <= lastIdMicros) micros = lastIdMicros + 1;
+  lastIdMicros = micros;
+  const rand = crypto.getRandomValues(new Uint8Array(6));
+  let hex = "";
+  for (const b of rand) hex += b.toString(16).padStart(2, "0");
+  return `anchor_${micros.toString(36)}_${hex}`;
+}
+
+/** In-memory receipt store — the no-DB / test profile. */
+export class InMemoryAnchorReceiptStore implements AnchorReceiptStore {
+  private readonly rows: AnchorReceiptRecord[] = [];
+
+  async append(record: AnchorRecord): Promise<AnchorReceiptRecord> {
+    const stored: AnchorReceiptRecord = Object.freeze({
+      ...record,
+      tips: Object.freeze(record.tips.map((t) => Object.freeze({ ...t }))),
+      id: newReceiptId(),
+      createdAt: new Date().toISOString(),
+    });
+    this.rows.push(stored);
+    return stored;
+  }
+
+  async latest(): Promise<AnchorReceiptRecord | null> {
+    return this.rows.length === 0 ? null : this.rows[this.rows.length - 1]!;
+  }
+
+  async history(): Promise<ReadonlyArray<AnchorReceiptRecord>> {
+    return [...this.rows];
+  }
+
+  async latestForRoot(merkleRoot: string): Promise<AnchorReceiptRecord | null> {
+    for (let i = this.rows.length - 1; i >= 0; i--) {
+      if (this.rows[i]!.merkleRoot === merkleRoot) return this.rows[i]!;
+    }
+    return null;
+  }
+}