@kyaki/witness 0.1.0

package/dist/accountability.d.ts

@@ -0,0 +1,43 @@
+/**
+ * accountability.ts — witness accountability (Phase 7). Makes witness COLLUSION
+ * ACCOUNTABLE (never prevented): when co-signatures by the SAME witness over the SAME
+ * (logId, treeSize) with DIFFERENT roots are CO-LOCATED at one observer, it forms a
+ * non-repudiable `WitnessEquivocationProof` naming that witness.
+ *
+ * THE CO-LOCATION PRECONDITION (the honest boundary — same class as the operator monitor):
+ * a proof forms only if BOTH divergent co-signatures reach this corpus. A witness co-signs
+ * honestly via its durable store (which never co-signs two roots at one size), so the two
+ * divergent co-signatures come from a COMPROMISED key / faulty store and are observed by
+ * DIFFERENT relying parties (e.g. two victims that pollinated the same witness at the same
+ * size and got different roots) or via gossip. If a colluder never lets its two
+ * observations meet at one extractor, NO proof forms. Absence of a proof proves nothing.
+ * Quorum intersection (k > n/2) guarantees a successful two-quorum split SHARES a
+ * double-signer — but extraction still requires both quorums' co-signatures to co-locate.
+ *
+ * SPENDS NEVER DEPEND ON THIS — it is the same liveness-only, opportunistic aggregation as
+ * the operator equivocation monitor. The sole spend-time safety control stays
+ * verifyWitnessedTreeHead at quorum >= 2 fail-closed.
+ */
+import { type WitnessConflictStore, type WitnessCosigStore, type WitnessCosignature, type WitnessEquivocationProof } from '@kyaki/core';
+export interface WitnessAccountabilityConfig {
+    /** Durable corpus of observed witness co-signatures (keyed so two divergent roots coexist). */
+    observed: WitnessCosigStore;
+    /** Durable store of detected proofs (named, faulty witnesses). */
+    conflicts: WitnessConflictStore;
+}
+export declare class WitnessAccountabilityMonitor {
+    private readonly cfg;
+    constructor(cfg: WitnessAccountabilityConfig);
+    /**
+     * Ingest one observed witness co-signature (the store verifies it before recording) and,
+     * if it now completes a same-witness / same-size / different-root pair, form + persist the
+     * proof. Returns the proof iff one is available for that witness (newly formed or already
+     * recorded). Idempotent — re-observing the same co-signature never duplicates or errors.
+     */
+    observe(cosig: WitnessCosignature): Promise<WitnessEquivocationProof | undefined>;
+    /** Re-scan every observed witness and persist any equivocation proof. Returns the proofs held. */
+    sweep(): Promise<WitnessEquivocationProof[]>;
+    /** A witness's proof, re-detected from the corpus (and persisted) or read back from store. */
+    private detectFor;
+}
+//# sourceMappingURL=accountability.d.ts.map

package/dist/accountability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.d.ts","sourceRoot":"","sources":["../src/accountability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAEL,KAAK,oBAAoB,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC1G,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,2BAA2B;IAC1C,+FAA+F;IAC/F,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,kEAAkE;IAClE,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAED,qBAAa,4BAA4B;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,2BAA2B;IAE7D;;;;;OAKG;IACG,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC;IASvF,kGAAkG;IAC5F,KAAK,IAAI,OAAO,CAAC,wBAAwB,EAAE,CAAC;IASlD,8FAA8F;YAChF,SAAS;CAUxB"}

package/dist/accountability.js

@@ -0,0 +1,64 @@
+/**
+ * accountability.ts — witness accountability (Phase 7). Makes witness COLLUSION
+ * ACCOUNTABLE (never prevented): when co-signatures by the SAME witness over the SAME
+ * (logId, treeSize) with DIFFERENT roots are CO-LOCATED at one observer, it forms a
+ * non-repudiable `WitnessEquivocationProof` naming that witness.
+ *
+ * THE CO-LOCATION PRECONDITION (the honest boundary — same class as the operator monitor):
+ * a proof forms only if BOTH divergent co-signatures reach this corpus. A witness co-signs
+ * honestly via its durable store (which never co-signs two roots at one size), so the two
+ * divergent co-signatures come from a COMPROMISED key / faulty store and are observed by
+ * DIFFERENT relying parties (e.g. two victims that pollinated the same witness at the same
+ * size and got different roots) or via gossip. If a colluder never lets its two
+ * observations meet at one extractor, NO proof forms. Absence of a proof proves nothing.
+ * Quorum intersection (k > n/2) guarantees a successful two-quorum split SHARES a
+ * double-signer — but extraction still requires both quorums' co-signatures to co-locate.
+ *
+ * SPENDS NEVER DEPEND ON THIS — it is the same liveness-only, opportunistic aggregation as
+ * the operator equivocation monitor. The sole spend-time safety control stays
+ * verifyWitnessedTreeHead at quorum >= 2 fail-closed.
+ */
+import { detectWitnessEquivocation, verifyWitnessCosignature, verifyWitnessEquivocation, } from '@kyaki/core';
+export class WitnessAccountabilityMonitor {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /**
+     * Ingest one observed witness co-signature (the store verifies it before recording) and,
+     * if it now completes a same-witness / same-size / different-root pair, form + persist the
+     * proof. Returns the proof iff one is available for that witness (newly formed or already
+     * recorded). Idempotent — re-observing the same co-signature never duplicates or errors.
+     */
+    async observe(cosig) {
+        // Verify-before-record at the monitor TOO (defense in depth — a non-authentic co-signature
+        // must never reach the corpus, where it could PK-squat and shadow a genuine root). The store
+        // also re-verifies, so neither layer can be the single point that lets junk in.
+        if (!cosig || !verifyWitnessCosignature(cosig))
+            return undefined;
+        await this.cfg.observed.record(cosig);
+        return this.detectFor(cosig.witnessId);
+    }
+    /** Re-scan every observed witness and persist any equivocation proof. Returns the proofs held. */
+    async sweep() {
+        const out = [];
+        for (const w of await this.cfg.observed.witnesses()) {
+            const p = await this.detectFor(w);
+            if (p)
+                out.push(p);
+        }
+        return out;
+    }
+    /** A witness's proof, re-detected from the corpus (and persisted) or read back from store. */
+    async detectFor(witnessId) {
+        const cosigs = await this.cfg.observed.byWitness(witnessId);
+        const proof = detectWitnessEquivocation(cosigs, witnessId);
+        if (proof && verifyWitnessEquivocation(proof, witnessId)) {
+            await this.cfg.conflicts.record(proof); // monotone, idempotent
+            return proof;
+        }
+        // No fresh pair (or only one root seen so far) ⇒ surface any already-recorded proof.
+        return this.cfg.conflicts.forWitness(witnessId);
+    }
+}
+//# sourceMappingURL=accountability.js.map

package/dist/accountability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.js","sourceRoot":"","sources":["../src/accountability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,yBAAyB,EAAE,wBAAwB,EAAE,yBAAyB,GAE/E,MAAM,aAAa,CAAC;AASrB,MAAM,OAAO,4BAA4B;IACV;IAA7B,YAA6B,GAAgC;QAAhC,QAAG,GAAH,GAAG,CAA6B;IAAG,CAAC;IAEjE;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,KAAyB;QACrC,2FAA2F;QAC3F,6FAA6F;QAC7F,gFAAgF;QAChF,IAAI,CAAC,KAAK,IAAI,CAAC,wBAAwB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACjE,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC;IAED,kGAAkG;IAClG,KAAK,CAAC,KAAK;QACT,MAAM,GAAG,GAA+B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;YACpD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAClC,IAAI,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,8FAA8F;IACtF,KAAK,CAAC,SAAS,CAAC,SAAiB;QACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,yBAAyB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC3D,IAAI,KAAK,IAAI,yBAAyB,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAG,uBAAuB;YACjE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,qFAAqF;QACrF,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/adapters/monitor-http.d.ts

@@ -0,0 +1,31 @@
+/**
+ * adapters/monitor-http.ts — the WitnessMonitor's HTTP edge.
+ *
+ * One read route, `GET /conflict`, serving the durable EquivocationProof (the klaxon):
+ *   - 200 { version, proof }  — a detected, self-verifying proof. The CONSUMER MUST
+ *     re-verify it with verifyEquivocation(proof, PINNED_OPERATOR_DID); this endpoint is
+ *     an UNTRUSTED aggregator — a 200 status is not evidence, the proof bytes are.
+ *   - 204                      — no conflict OBSERVED by this monitor (NOT "no fork
+ *     exists" — absence proves nothing; detection is liveness-bounded).
+ *   - 500 { error }            — a monitor-internal fault.
+ *
+ * Mirrors witness-http hardening: a thrown store/DB fault becomes a WRITTEN response,
+ * never a hung socket; the served body is a single fixed-shape proof, not unbounded data.
+ */
+import { type Server } from 'node:http';
+import type { ConflictStore } from '@kyaki/core';
+/** Bumped if the wire shape of the /conflict body changes (consumer compatibility). */
+export declare const CONFLICT_WIRE_VERSION = 1;
+export interface MonitorHttpRequest {
+    method: string;
+    path: string;
+}
+export interface MonitorHttpResponse {
+    status: number;
+    body: unknown;
+}
+export type MonitorHttpHandler = (req: MonitorHttpRequest) => Promise<MonitorHttpResponse>;
+export declare function createMonitorHttpHandler(conflicts: ConflictStore): MonitorHttpHandler;
+/** Bind the pure handler to node:http. No request body is read (read-only routes). */
+export declare function createMonitorServer(conflicts: ConflictStore): Server;
+//# sourceMappingURL=monitor-http.d.ts.map

package/dist/adapters/monitor-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor-http.d.ts","sourceRoot":"","sources":["../../src/adapters/monitor-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAoC,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AACD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AACD,MAAM,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAE3F,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,aAAa,GAAG,kBAAkB,CAarF;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAsBpE"}

package/dist/adapters/monitor-http.js

@@ -0,0 +1,59 @@
+/**
+ * adapters/monitor-http.ts — the WitnessMonitor's HTTP edge.
+ *
+ * One read route, `GET /conflict`, serving the durable EquivocationProof (the klaxon):
+ *   - 200 { version, proof }  — a detected, self-verifying proof. The CONSUMER MUST
+ *     re-verify it with verifyEquivocation(proof, PINNED_OPERATOR_DID); this endpoint is
+ *     an UNTRUSTED aggregator — a 200 status is not evidence, the proof bytes are.
+ *   - 204                      — no conflict OBSERVED by this monitor (NOT "no fork
+ *     exists" — absence proves nothing; detection is liveness-bounded).
+ *   - 500 { error }            — a monitor-internal fault.
+ *
+ * Mirrors witness-http hardening: a thrown store/DB fault becomes a WRITTEN response,
+ * never a hung socket; the served body is a single fixed-shape proof, not unbounded data.
+ */
+import { createServer as nodeCreateServer } from 'node:http';
+/** Bumped if the wire shape of the /conflict body changes (consumer compatibility). */
+export const CONFLICT_WIRE_VERSION = 1;
+export function createMonitorHttpHandler(conflicts) {
+    return async (req) => {
+        if (req.method === 'GET' && req.path === '/conflict') {
+            try {
+                const proof = await conflicts.latest();
+                if (!proof)
+                    return { status: 204, body: undefined };
+                return { status: 200, body: { version: CONFLICT_WIRE_VERSION, proof } };
+            }
+            catch {
+                return { status: 500, body: { error: 'INTERNAL' } };
+            }
+        }
+        return { status: 404, body: { error: 'NOT_FOUND' } };
+    };
+}
+/** Bind the pure handler to node:http. No request body is read (read-only routes). */
+export function createMonitorServer(conflicts) {
+    const handle = createMonitorHttpHandler(conflicts);
+    return nodeCreateServer((req, res) => {
+        req.on('error', () => { });
+        res.on('error', () => { });
+        void (async () => {
+            const path = (req.url ?? '/').split('?')[0] ?? '/';
+            try {
+                const result = await handle({ method: req.method ?? 'GET', path });
+                if (result.status === 204) {
+                    res.writeHead(204);
+                    res.end();
+                    return;
+                }
+                res.writeHead(result.status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(result.body));
+            }
+            catch {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'INTERNAL' }));
+            }
+        })();
+    });
+}
+//# sourceMappingURL=monitor-http.js.map

package/dist/adapters/monitor-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor-http.js","sourceRoot":"","sources":["../../src/adapters/monitor-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAe,MAAM,WAAW,CAAC;AAG1E,uFAAuF;AACvF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAYvC,MAAM,UAAU,wBAAwB,CAAC,SAAwB;IAC/D,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE;QACnB,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACrD,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,CAAC;gBACvC,IAAI,CAAC,KAAK;oBAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;gBACpD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,qBAAqB,EAAE,KAAK,EAAE,EAAE,CAAC;YAC1E,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;YACtD,CAAC;QACH,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC;IACvD,CAAC,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,mBAAmB,CAAC,SAAwB;IAC1D,MAAM,MAAM,GAAG,wBAAwB,CAAC,SAAS,CAAC,CAAC;IACnD,OAAO,gBAAgB,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACnC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC1B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC1B,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;YACnD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACnE,IAAI,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;oBAC1B,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;oBACnB,GAAG,CAAC,GAAG,EAAE,CAAC;oBACV,OAAO;gBACT,CAAC;gBACD,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBACrE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;YACjD,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/adapters/witness-http.d.ts

@@ -0,0 +1,62 @@
+/**
+ * adapters/witness-http.ts — the witness's HTTP edge (a transport, not authority).
+ *
+ * A pure `(req) => Promise<res>` handler plus a node:http binding, mirroring
+ * @kyaki/api's adapter — but HARDENED per the design review, because a witness is a
+ * public-facing party an operator does not control:
+ *   - a request-body BYTE CAP in the binding (413) so an unbounded POST can't
+ *     exhaust heap before parsing;
+ *   - a consistency-proof LENGTH CAP in the handler (400) — a real proof is
+ *     O(log n) (≤ 64 nodes covers 2^64 entries), so a longer one is junk/abuse;
+ *   - a try/catch around dispatch so a thrown WITNESS_* error becomes a WRITTEN
+ *     response with the right status, never a hung socket / TCP reset;
+ *   - an error TAXONOMY that keeps the smoking gun loud: an operator-attributable
+ *     CONFLICT (equivocation / non-monotonic / non-consistent fork) is 409, an
+ *     input fault (bad signature / missing or mis-shaped proof / wrong log) is 400,
+ *     and only an unexpected internal fault is 500.
+ *
+ * NOTE (documented out-of-scope, per review): /cosign is unauthenticated. Any
+ * co-signature a replayer obtains is honest (the witness only ever endorses the
+ * operator's own signed heads), but advancing the anchor and the write path should
+ * be gated to the operator in production (private network / mTLS / a signed request
+ * envelope). The byte cap blunts the worst abuse; rate-limiting is a deployment concern.
+ */
+import { type Server } from 'node:http';
+import type { ConsistencyProof, SignedTreeHead, WitnessCosignature, WitnessHead } from '@kyaki/core';
+/** The witness surface the adapter needs (satisfied by DurableWitness). */
+export interface WitnessLike {
+    cosign(sth: SignedTreeHead, consistencyProof?: ConsistencyProof): Promise<WitnessCosignature>;
+    head(): Promise<WitnessHead | undefined>;
+    /** The operator-signed STH endorsed at `treeSize` (latest if omitted) — the gossip
+     *  source a WitnessMonitor pulls via `GET /sth`. */
+    signedHead(treeSize?: number): Promise<SignedTreeHead | undefined>;
+    /** This witness's endorsement (its endorsed STH + its own co-signature) at `treeSize`
+     *  (latest if omitted) — what a relying party pulls via `GET /cosig` to POLLINATE the
+     *  head it was served (confirm a quorum of trusted witnesses co-signed the exact root). */
+    endorsement(treeSize?: number): Promise<{
+        sth: SignedTreeHead;
+        cosignature: WitnessCosignature;
+    } | undefined>;
+}
+export interface HttpRequest {
+    method: string;
+    path: string;
+    query?: Record<string, string | undefined>;
+    body?: unknown;
+}
+export interface HttpResponse {
+    status: number;
+    body: unknown;
+}
+export type HttpHandler = (req: HttpRequest) => Promise<HttpResponse>;
+/**
+ * Routes:
+ *   POST /cosign  { sth, consistencyProof? }  → 200 WitnessCosignature
+ *                                               · 400 input fault · 409 operator conflict
+ *                                               · 400 PROOF_TOO_LARGE
+ *   GET  /head                                → 200 { head: WitnessHead | null }
+ */
+export declare function createWitnessHttpHandler(witness: WitnessLike): HttpHandler;
+/** Bind the pure handler to node:http, enforcing the request-body byte cap. */
+export declare function createWitnessServer(witness: WitnessLike): Server;
+//# sourceMappingURL=witness-http.d.ts.map

package/dist/adapters/witness-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness-http.d.ts","sourceRoot":"","sources":["../../src/adapters/witness-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAoC,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAErG,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,GAAG,EAAE,cAAc,EAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9F,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IACzC;wDACoD;IACpD,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACnE;;+FAE2F;IAC3F,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,kBAAkB,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;CAC/G;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAiCtE;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CA6E1E;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CA+DhE"}

package/dist/adapters/witness-http.js

@@ -0,0 +1,212 @@
+/**
+ * adapters/witness-http.ts — the witness's HTTP edge (a transport, not authority).
+ *
+ * A pure `(req) => Promise<res>` handler plus a node:http binding, mirroring
+ * @kyaki/api's adapter — but HARDENED per the design review, because a witness is a
+ * public-facing party an operator does not control:
+ *   - a request-body BYTE CAP in the binding (413) so an unbounded POST can't
+ *     exhaust heap before parsing;
+ *   - a consistency-proof LENGTH CAP in the handler (400) — a real proof is
+ *     O(log n) (≤ 64 nodes covers 2^64 entries), so a longer one is junk/abuse;
+ *   - a try/catch around dispatch so a thrown WITNESS_* error becomes a WRITTEN
+ *     response with the right status, never a hung socket / TCP reset;
+ *   - an error TAXONOMY that keeps the smoking gun loud: an operator-attributable
+ *     CONFLICT (equivocation / non-monotonic / non-consistent fork) is 409, an
+ *     input fault (bad signature / missing or mis-shaped proof / wrong log) is 400,
+ *     and only an unexpected internal fault is 500.
+ *
+ * NOTE (documented out-of-scope, per review): /cosign is unauthenticated. Any
+ * co-signature a replayer obtains is honest (the witness only ever endorses the
+ * operator's own signed heads), but advancing the anchor and the write path should
+ * be gated to the operator in production (private network / mTLS / a signed request
+ * envelope). The byte cap blunts the worst abuse; rate-limiting is a deployment concern.
+ */
+import { createServer as nodeCreateServer } from 'node:http';
+/** A real Merkle consistency proof is O(log n); anything longer is junk or abuse. */
+const MAX_PROOF_NODES = 64;
+/** Honest STH + proof is well under 1 KiB; cap the raw body far below heap-risk. */
+const MAX_BODY_BYTES = 64 * 1024;
+/** Operator-attributable conflicts → 409 (the alarm); input faults → 400. */
+const OPERATOR_CONFLICTS = new Set([
+    'WITNESS_NON_MONOTONIC', 'WITNESS_EQUIVOCATION', 'WITNESS_CONSISTENCY_INVALID',
+    'WITNESS_STORE_NON_MONOTONIC', 'WITNESS_STORE_EQUIVOCATION',
+]);
+const INPUT_FAULTS = new Set([
+    'WITNESS_STH_SIGNATURE_INVALID', 'WITNESS_CONSISTENCY_REQUIRED',
+    'WITNESS_CONSISTENCY_SIZE_MISMATCH', 'WITNESS_WRONG_LOG',
+]);
+/** The machine code is the message up to the first ':' or space. */
+function codeOf(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.split(/[:\s]/)[0] ?? 'INTERNAL';
+}
+function statusForCode(code) {
+    if (INPUT_FAULTS.has(code))
+        return 400;
+    if (OPERATOR_CONFLICTS.has(code))
+        return 409;
+    // Any OTHER integrity-prefixed code (e.g. a store backstop like WITNESS_STORE_LOG_MISMATCH,
+    // or a future WITNESS_*/COSIG_* fault) is operator-attributable — surface it LOUD as a 409,
+    // never let it fall through to 500 where the client would misread it as transport/liveness.
+    if (code.startsWith('WITNESS_') || code.startsWith('COSIG_'))
+        return 409;
+    return 500;
+}
+/**
+ * Routes:
+ *   POST /cosign  { sth, consistencyProof? }  → 200 WitnessCosignature
+ *                                               · 400 input fault · 409 operator conflict
+ *                                               · 400 PROOF_TOO_LARGE
+ *   GET  /head                                → 200 { head: WitnessHead | null }
+ */
+export function createWitnessHttpHandler(witness) {
+    return async (req) => {
+        const { method, path } = req;
+        if (method === 'POST' && path === '/cosign') {
+            const body = (req.body ?? {});
+            if (!body.sth) {
+                return { status: 400, body: { error: 'MISSING_STH' } };
+            }
+            if (body.consistencyProof && Array.isArray(body.consistencyProof.proof)
+                && body.consistencyProof.proof.length > MAX_PROOF_NODES) {
+                return { status: 400, body: { error: 'PROOF_TOO_LARGE', max: MAX_PROOF_NODES } };
+            }
+            try {
+                const cosignature = await witness.cosign(body.sth, body.consistencyProof);
+                return { status: 200, body: cosignature };
+            }
+            catch (err) {
+                const code = codeOf(err);
+                const status = statusForCode(code);
+                // A 500 is an unexpected internal fault — surface a generic body, never a hang.
+                return { status, body: { error: status === 500 ? 'INTERNAL' : code } };
+            }
+        }
+        if (method === 'GET' && path === '/head') {
+            try {
+                const head = await witness.head();
+                return { status: 200, body: { head: head ?? null } };
+            }
+            catch {
+                // Keep the "no thrown error escapes the handler" invariant uniform across routes —
+                // a store/DB fault in head() becomes a written 500, not an unhandled rejection for
+                // an in-process caller composing the pure handler without the node:http binding.
+                return { status: 500, body: { error: 'INTERNAL' } };
+            }
+        }
+        if (method === 'GET' && path === '/sth') {
+            // The gossip read a WitnessMonitor pulls. `?size=` selects a specific endorsed
+            // size (for cross-witness same-size comparison); omitted ⇒ the latest endorsed STH.
+            const raw = req.query?.['size'];
+            let treeSize;
+            if (raw !== undefined && raw !== '') {
+                treeSize = Number(raw);
+                if (!Number.isInteger(treeSize) || treeSize < 0) {
+                    return { status: 400, body: { error: 'BAD_SIZE' } };
+                }
+            }
+            try {
+                const sth = await witness.signedHead(treeSize);
+                return { status: 200, body: { sth: sth ?? null } };
+            }
+            catch {
+                return { status: 500, body: { error: 'INTERNAL' } };
+            }
+        }
+        if (method === 'GET' && path === '/cosig') {
+            // The relying-party POLLINATION read: this witness's endorsement (STH + its own
+            // co-signature) at `?size=`. A victim pulls this DIRECTLY from each trusted witness
+            // to confirm the head it was served — so the operator cannot withhold/cherry-pick.
+            const raw = req.query?.['size'];
+            let treeSize;
+            if (raw !== undefined && raw !== '') {
+                treeSize = Number(raw);
+                if (!Number.isInteger(treeSize) || treeSize < 0) {
+                    return { status: 400, body: { error: 'BAD_SIZE' } };
+                }
+            }
+            try {
+                const e = await witness.endorsement(treeSize);
+                return { status: 200, body: { sth: e?.sth ?? null, cosignature: e?.cosignature ?? null } };
+            }
+            catch {
+                return { status: 500, body: { error: 'INTERNAL' } };
+            }
+        }
+        return { status: 404, body: { error: 'NOT_FOUND' } };
+    };
+}
+/** Bind the pure handler to node:http, enforcing the request-body byte cap. */
+export function createWitnessServer(witness) {
+    const handle = createWitnessHttpHandler(witness);
+    return nodeCreateServer((req, res) => {
+        // A public-facing endpoint an operator does not control: a client that resets the
+        // connection mid-body makes the request stream emit 'error', which Node re-throws as
+        // an uncaught exception (crashing the witness) if unhandled. Swallow it on both streams.
+        req.on('error', () => { });
+        res.on('error', () => { });
+        const chunks = [];
+        let total = 0;
+        let aborted = false;
+        const fail = (status, error) => {
+            // Send the response and close the connection; the `aborted` flag stops further
+            // buffering. We do NOT req.destroy() here — destroying the socket before the body
+            // flushes can RST the connection and lose the response (e.g. the 413).
+            aborted = true;
+            res.writeHead(status, { 'Content-Type': 'application/json', 'Connection': 'close' });
+            res.end(JSON.stringify({ error }));
+        };
+        req.on('data', (c) => {
+            if (aborted)
+                return;
+            total += c.length;
+            if (total > MAX_BODY_BYTES) {
+                fail(413, 'PAYLOAD_TOO_LARGE');
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            if (aborted)
+                return;
+            const fail500 = () => {
+                try {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'INTERNAL' }));
+                }
+                catch { /* already responded */ }
+            };
+            void (async () => {
+                const raw = Buffer.concat(chunks).toString('utf8');
+                let body;
+                try {
+                    body = raw ? JSON.parse(raw) : undefined;
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'INVALID_JSON' }));
+                    return;
+                }
+                // Parse path + query WITHOUT new URL(): a raw target like `//` makes new URL() THROW
+                // ('Invalid URL'), which — before the dispatch try — would escape this voided async
+                // IIFE as an unhandled rejection, hanging the socket (and crashing under the default
+                // --unhandled-rejections=throw). split + URLSearchParams never throw on a bad target.
+                const [rawPath, qs] = (req.url ?? '/').split('?');
+                const query = {};
+                for (const [k, v] of new URLSearchParams(qs ?? ''))
+                    query[k] = v;
+                try {
+                    const result = await handle({ method: req.method ?? 'GET', path: rawPath || '/', query, body });
+                    res.writeHead(result.status, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(result.body));
+                }
+                catch {
+                    // The pure handler maps every expected rejection itself; anything escaping
+                    // here is a genuine internal fault — still write a body, never hang.
+                    fail500();
+                }
+            })().catch(fail500); // belt-and-suspenders: no throw can leave the socket hung
+        });
+    });
+}
+//# sourceMappingURL=witness-http.js.map

package/dist/adapters/witness-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"witness-http.js","sourceRoot":"","sources":["../../src/adapters/witness-http.ts"],"names":[],"mappings":"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"}

package/dist/durable-witness.d.ts

@@ -0,0 +1,101 @@
+/**
+ * durable-witness.ts — the DURABLE, independent witness party.
+ *
+ * `@kyaki/core`'s `Witness` is the verification ENGINE, but its remembered head is
+ * in-process: it forgets on restart, so it provides no cross-restart rollback
+ * defense and cannot be horizontally scaled. `DurableWitness` closes that — it is
+ * the leg of "anchored AND externally witnessed" the moat rests on.
+ *
+ * The cross-party guarantee lives in TWO places working together:
+ *   1. PERSIST-BEFORE-EMIT — a co-signature is returned only AFTER the head it
+ *      endorses is durably committed. Releasing a co-sig before recording it would
+ *      let the witness forget, after a crash, that it had endorsed head N and later
+ *      co-sign a forked N′ — exactly the equivocation it exists to prevent.
+ *   2. VERIFY-UNDER-LOCK against the DURABLE head — the append-only consistency
+ *      check (which the store cannot perform; it has no Merkle state) runs inside
+ *      the store's per-log lock against the head read FROM STORAGE, never an
+ *      in-memory cache. So two instances sharing one store can never co-sign a fork
+ *      from stale local state. In-process requests are additionally serialized per
+ *      log by a KeyedMutex so two concurrent /cosign calls cannot interleave across
+ *      the store await.
+ *
+ * What this does NOT defend (honest boundary, enforced at the relying party by
+ * `verifyWitnessedTreeHead`): a single witness does not defeat a general cross-party
+ * split-view, nor a compromised/colluding witness key — those need quorum ≥ 2 under
+ * disjoint control and, ultimately, witness-to-witness gossip (a documented follow-up).
+ */
+import { type ConsistencyProof, type EndorsedHead, type Identity, type SignedTreeHead, type WitnessCosignature, type WitnessHead, type WitnessStateStore } from '@kyaki/core';
+export declare class DurableWitness {
+    private readonly keys;
+    private readonly logId;
+    private readonly store;
+    private readonly mutex;
+    private constructor();
+    /**
+     * Build a witness pinned to one operator log. The durable store is the SOLE
+     * authority for the witness's last head — it is read under lock on every cosign,
+     * so there is no in-memory baseline to go stale. `create()` is the only
+     * constructor so a caller cannot bypass the store with a hand-seeded head.
+     */
+    static create(keys: Identity, logId: string, store: WitnessStateStore): Promise<DurableWitness>;
+    get id(): string;
+    /** The witness's durable last-co-signed head. The operator builds its next
+     *  consistency proof from THIS (reading storage, never a cache) so an honest
+     *  extension is never spuriously rejected for a size mismatch. */
+    head(): Promise<WitnessHead | undefined>;
+    /**
+     * Co-sign `sth` iff it is an append-only extension of the witness's durable head.
+     * Throws a named WITNESS_* error on rejection (the caller maps it to a status):
+     *   - WITNESS_WRONG_LOG          — sth is for a log this witness does not watch;
+     *   - WITNESS_STH_SIGNATURE_INVALID / _CONSISTENCY_REQUIRED / _SIZE_MISMATCH
+     *                                — input faults (the proof is missing/wrong shape);
+     *   - WITNESS_NON_MONOTONIC / _EQUIVOCATION / _CONSISTENCY_INVALID
+     *                                — operator-attributable conflicts (a fork attempt).
+     */
+    cosign(sth: SignedTreeHead, consistencyProof?: ConsistencyProof, now?: Date): Promise<WitnessCosignature>;
+    /** The operator-signed STH this witness endorsed at `treeSize` (its latest endorsed
+     *  STH if omitted), read straight from the durable store — the gossip source a
+     *  WitnessMonitor pulls to detect cross-witness equivocation. */
+    signedHead(treeSize?: number): Promise<SignedTreeHead | undefined>;
+    /**
+     * This witness's OWN endorsement at `treeSize` (its latest if omitted): the
+     * operator-signed STH it endorsed AND its co-signature over it. The co-signature is
+     * re-derived deterministically from the retained STH — its body is a pure function of
+     * (witnessId, logId, treeSize, rootHash), so this needs no extra stored state and is
+     * byte-identical to the one emitted at cosign time.
+     *
+     * This is what relying-party POLLINATION pulls DIRECTLY from each trusted witness: the
+     * victim asks the witnesses themselves "did you co-sign this exact root at this size?",
+     * so the operator cannot withhold or cherry-pick which witnesses endorsed which root,
+     * and the witness-signed co-signature cannot be forged by a man-in-the-middle.
+     * undefined if this witness retained no endorsement at that size.
+     */
+    endorsement(treeSize?: number): Promise<{
+        sth: SignedTreeHead;
+        cosignature: WitnessCosignature;
+    } | undefined>;
+}
+/**
+ * An in-memory `WitnessStateStore` for single-process tests and demos. It serializes
+ * `cosign` via a promise chain (mirroring the durable per-log lock) and applies the
+ * same monotonic + equivocation backstop the durable store does. It is NOT durable —
+ * it forgets on restart, so the cross-restart guarantee requires a durable store
+ * (`@kyaki/postgres` `PgWitnessStore`). Use it to exercise the witness LOGIC.
+ */
+export declare class MemoryWitnessStore implements WitnessStateStore {
+    private current;
+    private cosignature;
+    /** Append-only operator-signed STHs keyed by tree size (FIRST-write-wins, mirroring
+     *  the durable kya_endorsed_sth ON CONFLICT DO NOTHING). Retained so a past size
+     *  stays serveable for gossip after the witness advances beyond it. */
+    private readonly endorsed;
+    private chain;
+    load(): Promise<WitnessHead | undefined>;
+    /** The co-signature co-committed with the current head (for parity with the
+     *  durable store, which persists both in one transaction). */
+    latestCosignature(): Promise<WitnessCosignature | undefined>;
+    /** The endorsed operator STH at `treeSize` (latest if omitted). undefined if none. */
+    signedHead(treeSize?: number): Promise<SignedTreeHead | undefined>;
+    cosign(decide: (prior: WitnessHead | undefined) => EndorsedHead): Promise<WitnessCosignature>;
+}
+//# sourceMappingURL=durable-witness.d.ts.map

package/dist/durable-witness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-witness.d.ts","sourceRoot":"","sources":["../src/durable-witness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAEL,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAC5E,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAClE,MAAM,aAAa,CAAC;AAErB,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IALxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAE1C,OAAO;IAMP;;;;;OAKG;WACU,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIrG,IAAI,EAAE,IAAI,MAAM,CAEf;IAED;;sEAEkE;IAC5D,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAI9C;;;;;;;;OAQG;IACG,MAAM,CAAC,GAAG,EAAE,cAAc,EAAE,gBAAgB,CAAC,EAAE,gBAAgB,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAwB/G;;qEAEiE;IAC3D,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAIxE;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,kBAAkB,CAAA;KAAE,GAAG,SAAS,CAAC;CAKpH;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,WAAW,CAAiC;IACpD;;2EAEuE;IACvE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,KAAK,CAAuC;IAE9C,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAI9C;kEAC8D;IACxD,iBAAiB,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAIlE,sFAAsF;IAChF,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAOxE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,KAAK,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAiC9F"}