@kyaki/witness 0.1.0

package/dist/durable-witness.js

@@ -0,0 +1,179 @@
+/**
+ * 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 { KeyedMutex, buildWitnessCosignature, checkWitnessAdvance, } from '@kyaki/core';
+export class DurableWitness {
+    keys;
+    logId;
+    store;
+    mutex = new KeyedMutex();
+    constructor(keys, logId, store) {
+        this.keys = keys;
+        this.logId = logId;
+        this.store = store;
+    }
+    /**
+     * 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 async create(keys, logId, store) {
+        return new DurableWitness(keys, logId, store);
+    }
+    get id() {
+        return this.keys.did;
+    }
+    /** 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. */
+    async head() {
+        return this.store.load();
+    }
+    /**
+     * 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).
+     */
+    async cosign(sth, consistencyProof, now) {
+        if (sth.logId !== this.logId) {
+            throw new Error(`WITNESS_WRONG_LOG: this witness is pinned to ${this.logId}, not ${sth.logId}`);
+        }
+        const at = (now ?? new Date()).toISOString();
+        return this.mutex.runExclusive(this.logId, () => this.store.cosign((prior) => {
+            // The append-only check runs HERE — inside the store's per-log lock, against
+            // the DURABLE prior head. This is the load-bearing placement: a stale cache
+            // is never the baseline, so a scaled-out witness cannot co-sign a fork.
+            checkWitnessAdvance(prior, sth, consistencyProof);
+            const head = { logId: sth.logId, treeSize: sth.treeSize, rootHash: sth.rootHash, at };
+            const cosignature = buildWitnessCosignature(this.keys, sth);
+            // Retain the OPERATOR-signed STH (verbatim) + the consistency proof we just
+            // verified, so this witness can later serve the exact head it endorsed at THIS
+            // size for gossip — even after advancing far beyond it. checkWitnessAdvance
+            // already validated sth's operator signature before we reach here.
+            const endorsed = { head, cosignature, endorsedSth: sth };
+            if (consistencyProof)
+                endorsed.prefixProof = consistencyProof;
+            return endorsed;
+        }));
+    }
+    /** 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. */
+    async signedHead(treeSize) {
+        return this.store.signedHead(treeSize);
+    }
+    /**
+     * 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.
+     */
+    async endorsement(treeSize) {
+        const sth = await this.store.signedHead(treeSize);
+        if (!sth)
+            return undefined;
+        return { sth, cosignature: buildWitnessCosignature(this.keys, sth) };
+    }
+}
+/**
+ * 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 class MemoryWitnessStore {
+    current;
+    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. */
+    endorsed = new Map();
+    chain = Promise.resolve();
+    async load() {
+        return this.current ? { ...this.current } : undefined;
+    }
+    /** The co-signature co-committed with the current head (for parity with the
+     *  durable store, which persists both in one transaction). */
+    async latestCosignature() {
+        return this.cosignature ? { ...this.cosignature } : undefined;
+    }
+    /** The endorsed operator STH at `treeSize` (latest if omitted). undefined if none. */
+    async signedHead(treeSize) {
+        const size = treeSize ?? (this.endorsed.size > 0 ? Math.max(...this.endorsed.keys()) : undefined);
+        if (size === undefined)
+            return undefined;
+        const sth = this.endorsed.get(size);
+        return sth ? { ...sth } : undefined;
+    }
+    cosign(decide) {
+        const run = this.chain.then(() => {
+            const prior = this.current ? { ...this.current } : undefined;
+            const { head, cosignature, endorsedSth } = decide(prior); // throws ⇒ rejection, state untouched
+            // Parity with PgWitnessStore: the head and the co-signature it endorses must name the
+            // same log (a mis-targeted decide() from a non-tree composer fails closed here too).
+            if (head.logId !== cosignature.logId) {
+                throw new Error('WITNESS_STORE_LOG_MISMATCH: head/cosig logId disagree');
+            }
+            // The retained STH must be the very head being endorsed (same size+root), or a
+            // monitor would serve an STH that does not match the co-signature.
+            if (endorsedSth.treeSize !== head.treeSize || endorsedSth.rootHash !== head.rootHash) {
+                throw new Error('WITNESS_STORE_STH_MISMATCH: endorsed STH does not match the head');
+            }
+            // Defense-in-depth backstop (the store cannot check Merkle consistency, but it
+            // can refuse a non-monotonic or same-size-equivocating head outright).
+            if (prior) {
+                if (head.treeSize < prior.treeSize) {
+                    throw new Error('WITNESS_STORE_NON_MONOTONIC: refusing a head smaller than the durable one');
+                }
+                if (head.treeSize === prior.treeSize && head.rootHash !== prior.rootHash) {
+                    throw new Error('WITNESS_STORE_EQUIVOCATION: a different root at an already-recorded size');
+                }
+            }
+            this.current = { ...head }; // co-commit: head + co-signature + endorsed STH together
+            this.cosignature = { ...cosignature };
+            if (!this.endorsed.has(endorsedSth.treeSize))
+                this.endorsed.set(endorsedSth.treeSize, { ...endorsedSth });
+            return cosignature;
+        });
+        // Keep the chain alive after a rejection so one bad request can't wedge the lock.
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+//# sourceMappingURL=durable-witness.js.map

package/dist/durable-witness.js.map

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

package/dist/fan-out.d.ts

@@ -0,0 +1,20 @@
+/**
+ * fan-out.ts — bounded-concurrency fan-out over a list (RULES §5.12 / §5.16).
+ *
+ * Pulls every item concurrently but never more than `concurrency` in flight, so a large
+ * pinned source set cannot open unbounded sockets or buffer unbounded heap in a single tick
+ * (a relying-party / monitor self-DoS). Per-item settle (`Promise.allSettled`): one
+ * rejecting or slow item never rejects the whole call, and worst-case wall-clock is one
+ * timeout PER BATCH, not the sum. Shared by the WitnessMonitor gossip poll and relying-party
+ * pollination so the two stay symmetric (the same bound the monitor was hardened to has to
+ * hold for the victim's pull too).
+ */
+/** Default in-flight cap. A handful of concurrent pulls is plenty for a witness/clearinghouse
+ *  set; the bound exists to stop a large set from exhausting sockets/FDs, not to maximize throughput. */
+export declare const POLL_CONCURRENCY = 8;
+/**
+ * Run `fn` over every item, at most `concurrency` in flight at a time. Never rejects — each
+ * item's outcome is returned as a settled result in input order, so callers classify per item.
+ */
+export declare function boundedFanOut<S, T>(items: readonly S[], fn: (item: S, index: number) => Promise<T>, concurrency?: number): Promise<PromiseSettledResult<T>[]>;
+//# sourceMappingURL=fan-out.d.ts.map

package/dist/fan-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.d.ts","sourceRoot":"","sources":["../src/fan-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;yGACyG;AACzG,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,EACtC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,WAAW,GAAE,MAAyB,GACrC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,CASpC"}

package/dist/fan-out.js

@@ -0,0 +1,30 @@
+/**
+ * fan-out.ts — bounded-concurrency fan-out over a list (RULES §5.12 / §5.16).
+ *
+ * Pulls every item concurrently but never more than `concurrency` in flight, so a large
+ * pinned source set cannot open unbounded sockets or buffer unbounded heap in a single tick
+ * (a relying-party / monitor self-DoS). Per-item settle (`Promise.allSettled`): one
+ * rejecting or slow item never rejects the whole call, and worst-case wall-clock is one
+ * timeout PER BATCH, not the sum. Shared by the WitnessMonitor gossip poll and relying-party
+ * pollination so the two stay symmetric (the same bound the monitor was hardened to has to
+ * hold for the victim's pull too).
+ */
+/** Default in-flight cap. A handful of concurrent pulls is plenty for a witness/clearinghouse
+ *  set; the bound exists to stop a large set from exhausting sockets/FDs, not to maximize throughput. */
+export const POLL_CONCURRENCY = 8;
+/**
+ * Run `fn` over every item, at most `concurrency` in flight at a time. Never rejects — each
+ * item's outcome is returned as a settled result in input order, so callers classify per item.
+ */
+export async function boundedFanOut(items, fn, concurrency = POLL_CONCURRENCY) {
+    const width = Number.isInteger(concurrency) && concurrency > 0 ? concurrency : POLL_CONCURRENCY;
+    const out = new Array(items.length);
+    for (let i = 0; i < items.length; i += width) {
+        const batch = items.slice(i, i + width);
+        const settled = await Promise.allSettled(batch.map((s, j) => fn(s, i + j)));
+        for (let j = 0; j < settled.length; j++)
+            out[i + j] = settled[j];
+    }
+    return out;
+}
+//# sourceMappingURL=fan-out.js.map

package/dist/fan-out.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.js","sourceRoot":"","sources":["../src/fan-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;yGACyG;AACzG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAmB,EACnB,EAA0C,EAC1C,cAAsB,gBAAgB;IAEtC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAChG,MAAM,GAAG,GAA8B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;IACpE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @kyaki/witness — the independent, durable witness party.
+ *
+ * A separate party from the operator: it depends ONLY on @kyaki/core (it can never
+ * reach the operator's audit log), holds its own key, and remembers the last head
+ * it endorsed OUT OF BAND in its own WitnessStateStore — so it refuses to
+ * contradict that head even across its own restart or horizontal scaling. This is
+ * the cross-party rollback defense the Mandate Transparency Log rests on.
+ */
+export { DurableWitness, MemoryWitnessStore } from './durable-witness.js';
+export { createWitnessHttpHandler, createWitnessServer, type WitnessLike, type HttpHandler, type HttpRequest, type HttpResponse, } from './adapters/witness-http.js';
+export { WitnessMonitor, HttpGossipSource, type WitnessGossipSource, type WitnessMonitorConfig, type PollResult, } from './monitor.js';
+export { assertSafeUrl, safeFetchJson, isPrivateIp, type SsrfPolicy } from './ssrf.js';
+export { pollinate, HttpPollinationSource, type PollinationSource, type PollinationResult, type PollinateOptions, } from './pollination.js';
+export { WitnessAccountabilityMonitor, type WitnessAccountabilityConfig } from './accountability.js';
+export { createMonitorHttpHandler, createMonitorServer, CONFLICT_WIRE_VERSION, type MonitorHttpHandler, type MonitorHttpRequest, type MonitorHttpResponse, } from './adapters/monitor-http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EACL,wBAAwB,EAAE,mBAAmB,EAC7C,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,GACxE,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,cAAc,EAAE,gBAAgB,EAChC,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,UAAU,GACrE,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,SAAS,EAAE,qBAAqB,EAChC,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,GACtE,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,4BAA4B,EAAE,KAAK,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AACrG,OAAO,EACL,wBAAwB,EAAE,mBAAmB,EAAE,qBAAqB,EACpE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,GAC3E,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @kyaki/witness — the independent, durable witness party.
+ *
+ * A separate party from the operator: it depends ONLY on @kyaki/core (it can never
+ * reach the operator's audit log), holds its own key, and remembers the last head
+ * it endorsed OUT OF BAND in its own WitnessStateStore — so it refuses to
+ * contradict that head even across its own restart or horizontal scaling. This is
+ * the cross-party rollback defense the Mandate Transparency Log rests on.
+ */
+export { DurableWitness, MemoryWitnessStore } from './durable-witness.js';
+export { createWitnessHttpHandler, createWitnessServer, } from './adapters/witness-http.js';
+export { WitnessMonitor, HttpGossipSource, } from './monitor.js';
+export { assertSafeUrl, safeFetchJson, isPrivateIp } from './ssrf.js';
+export { pollinate, HttpPollinationSource, } from './pollination.js';
+export { WitnessAccountabilityMonitor } from './accountability.js';
+export { createMonitorHttpHandler, createMonitorServer, CONFLICT_WIRE_VERSION, } from './adapters/monitor-http.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EACL,wBAAwB,EAAE,mBAAmB,GAE9C,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,cAAc,EAAE,gBAAgB,GAEjC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAmB,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,SAAS,EAAE,qBAAqB,GAEjC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,4BAA4B,EAAoC,MAAM,qBAAqB,CAAC;AACrG,OAAO,EACL,wBAAwB,EAAE,mBAAmB,EAAE,qBAAqB,GAErE,MAAM,4BAA4B,CAAC"}

package/dist/monitor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * monitor.ts — the WitnessMonitor: an INDEPENDENT aggregator that gossips operator-
+ * signed STHs from a config-pinned witness set and surfaces a portable EquivocationProof
+ * when two witnesses disagree at one tree size.
+ *
+ * TRUST MODEL (read this — the monitor needs NO trust): it only ever relays
+ * self-verifying artifacts. Every STH it ingests is re-checked with verifySignedTreeHead
+ * against the operator key before it is retained, and every proof it emits is a pair of
+ * operator-signed STHs any third party re-verifies with verifyEquivocation against the
+ * pinned operator DID. A malicious monitor therefore cannot FABRICATE a false alarm
+ * (it cannot forge the operator's signature) — it can only WITHHOLD one. That makes the
+ * monitor a LIVENESS party, not a safety party.
+ *
+ * WHAT IT DOES AND DOES NOT CLOSE (§9 honesty — do not overstate):
+ *   - It produces an irrefutable proof WHEN two conflicting operator-signed heads at one
+ *     size both reach its corpus. The actual SAFETY control against a split-view remains
+ *     verifyWitnessedTreeHead at quorum ≥ 2 (fail-closed at the relying party).
+ *   - Detection is best-effort and operator-suppressible: an operator that never lets the
+ *     monitor observe both forks (targeted split-view), or DDoSes/partitions it, yields no
+ *     proof. ABSENCE OF A PROOF PROVES NOTHING.
+ *   - SPENDS NEVER DEPEND ON THE MONITOR. It is read-only gossip + detection; the spend
+ *     path (submit/approve) never calls it.
+ */
+import { type ConflictStore, type EquivocationProof, type ObservedSthStore, type SignedTreeHead } from '@kyaki/core';
+import { type SsrfPolicy } from './ssrf.js';
+/** A gossip source the monitor pulls STHs from. Satisfied in-process by `DurableWitness`
+ *  (it has `id` + `signedHead`) and over the wire by `HttpGossipSource`. */
+export interface WitnessGossipSource {
+    /** The witness DID — used to attribute and key the observed-STH corpus. */
+    readonly id?: string;
+    /** The operator-signed STH the witness endorsed at `treeSize` (its latest if omitted). */
+    signedHead(treeSize?: number): Promise<SignedTreeHead | undefined>;
+}
+/** Outcome of one gossip round. `proof` is set the first round a conflict is detected
+ *  (it is then durably recorded and re-served by ConflictStore). `unreachable` lists
+ *  sources that errored — a LIVENESS signal, never blocking. */
+export interface PollResult {
+    observed: number;
+    proof?: EquivocationProof;
+    unreachable: string[];
+}
+export interface WitnessMonitorConfig {
+    /** The operator log this monitor watches (the pinned operator DID). REQUIRED. */
+    logId: string;
+    /** The operator-INDEPENDENT, config-pinned witness set to gossip. */
+    sources: WitnessGossipSource[];
+    /** Durable observed-STH corpus (the detection window). */
+    observed: ObservedSthStore;
+    /** Durable klaxon store for detected proofs. */
+    conflicts: ConflictStore;
+}
+export declare class WitnessMonitor {
+    private readonly cfg;
+    constructor(cfg: WitnessMonitorConfig);
+    /** One gossip round: pull each source's latest head, back-fill each source at the
+     *  sizes the others reached (so a same-size fork across witnesses is observable),
+     *  retain only authentic operator STHs, then run same-size detection over the corpus
+     *  and durably record any proof. Returns the proof the first round it forms.
+     *
+     *  Idempotent and append-only: re-running never loses or fabricates evidence. Source
+     *  errors are tolerated (collected in `unreachable`) — detection is liveness, not safety. */
+    poll(): Promise<PollResult>;
+    /** Verify-before-retain: only an authentic STH for the watched log enters the corpus,
+     *  so junk/forged input can never form a pair. Returns whether it was NEWLY recorded
+     *  (a duplicate re-observation returns false), so the caller counts distinct heads. */
+    private retain;
+    /** Bounded-concurrency fan-out over sources; never throws (per-source settle).
+     *  Delegates to the shared `boundedFanOut` so the monitor and relying-party pollination
+     *  enforce the SAME in-flight cap (POLL_CONCURRENCY). */
+    private fanOut;
+}
+/**
+ * HttpGossipSource — pulls a witness's endorsed STHs over the wire via `GET /sth?size`,
+ * through the SSRF-safe fetch. `id` is the witness DID (for corpus attribution).
+ */
+export declare class HttpGossipSource implements WitnessGossipSource {
+    private readonly baseUrl;
+    readonly id: string;
+    private readonly ssrf;
+    constructor(baseUrl: string, id: string, ssrf: SsrfPolicy);
+    signedHead(treeSize?: number): Promise<SignedTreeHead | undefined>;
+}
+//# sourceMappingURL=monitor.d.ts.map

package/dist/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../src/monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAEL,KAAK,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EACvF,MAAM,aAAa,CAAC;AAErB,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D;4EAC4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;CACpE;AAED;;gEAEgE;AAChE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAMD,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,gDAAgD;IAChD,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,oBAAoB;IAEtD;;;;;;iGAM6F;IACvF,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAkDjC;;2FAEuF;YACzE,MAAM;IAKpB;;6DAEyD;IACzD,OAAO,CAAC,MAAM;CAMf;AAED;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,mBAAmB;IAExD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAFJ,OAAO,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACF,IAAI,EAAE,UAAU;IAG7B,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;CAKzE"}

package/dist/monitor.js

@@ -0,0 +1,133 @@
+/**
+ * monitor.ts — the WitnessMonitor: an INDEPENDENT aggregator that gossips operator-
+ * signed STHs from a config-pinned witness set and surfaces a portable EquivocationProof
+ * when two witnesses disagree at one tree size.
+ *
+ * TRUST MODEL (read this — the monitor needs NO trust): it only ever relays
+ * self-verifying artifacts. Every STH it ingests is re-checked with verifySignedTreeHead
+ * against the operator key before it is retained, and every proof it emits is a pair of
+ * operator-signed STHs any third party re-verifies with verifyEquivocation against the
+ * pinned operator DID. A malicious monitor therefore cannot FABRICATE a false alarm
+ * (it cannot forge the operator's signature) — it can only WITHHOLD one. That makes the
+ * monitor a LIVENESS party, not a safety party.
+ *
+ * WHAT IT DOES AND DOES NOT CLOSE (§9 honesty — do not overstate):
+ *   - It produces an irrefutable proof WHEN two conflicting operator-signed heads at one
+ *     size both reach its corpus. The actual SAFETY control against a split-view remains
+ *     verifyWitnessedTreeHead at quorum ≥ 2 (fail-closed at the relying party).
+ *   - Detection is best-effort and operator-suppressible: an operator that never lets the
+ *     monitor observe both forks (targeted split-view), or DDoSes/partitions it, yields no
+ *     proof. ABSENCE OF A PROOF PROVES NOTHING.
+ *   - SPENDS NEVER DEPEND ON THE MONITOR. It is read-only gossip + detection; the spend
+ *     path (submit/approve) never calls it.
+ */
+import { detectEquivocation, verifyEquivocation, verifySignedTreeHead, } from '@kyaki/core';
+import { boundedFanOut } from './fan-out.js';
+import { safeFetchJson } from './ssrf.js';
+/** Cap on distinct sizes back-filled per round, so a hostile source advertising a huge
+ *  size cannot blow up the per-round fan-out. */
+const MAX_BACKFILL_SIZES = 64;
+export class WitnessMonitor {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** One gossip round: pull each source's latest head, back-fill each source at the
+     *  sizes the others reached (so a same-size fork across witnesses is observable),
+     *  retain only authentic operator STHs, then run same-size detection over the corpus
+     *  and durably record any proof. Returns the proof the first round it forms.
+     *
+     *  Idempotent and append-only: re-running never loses or fabricates evidence. Source
+     *  errors are tolerated (collected in `unreachable`) — detection is liveness, not safety. */
+    async poll() {
+        const { logId, sources, observed, conflicts } = this.cfg;
+        const unreachable = new Set();
+        const pulled = new Set(); // `${i}:${size}` already fetched this round (skip re-pulls)
+        let observedCount = 0; // counts DISTINCT newly-recorded heads, not re-observations
+        // Pass 1: latest head from every source.
+        const latests = await this.fanOut(sources, (s) => s.signedHead());
+        const sizes = new Set();
+        for (let i = 0; i < sources.length; i++) {
+            const r = latests[i];
+            const label = sources[i].id ?? `source#${i}`;
+            if (r.status === 'rejected') {
+                unreachable.add(label);
+                continue;
+            }
+            if (!r.value)
+                continue;
+            pulled.add(`${i}:${r.value.treeSize}`);
+            sizes.add(r.value.treeSize);
+            if (await this.retain(label, r.value))
+                observedCount++;
+        }
+        // Pass 2: back-fill each source at the sizes OTHER sources reached (skipping a
+        // (source, size) already pulled in pass 1) — this is what makes a same-size fork
+        // (W1@n on fork A, W2@n on fork B) land as two corpus rows for detection.
+        const backfillSizes = [...sizes].sort((a, b) => a - b).slice(0, MAX_BACKFILL_SIZES);
+        for (const size of backfillSizes) {
+            const targets = sources
+                .map((s, i) => ({ s, i }))
+                .filter(({ i }) => !pulled.has(`${i}:${size}`));
+            if (targets.length === 0)
+                continue;
+            const got = await this.fanOut(targets.map((t) => t.s), (s) => s.signedHead(size));
+            for (let j = 0; j < targets.length; j++) {
+                const { i } = targets[j];
+                const r = got[j];
+                const label = sources[i].id ?? `source#${i}`;
+                if (r.status === 'rejected') {
+                    unreachable.add(label);
+                    continue;
+                }
+                if (!r.value)
+                    continue;
+                pulled.add(`${i}:${size}`);
+                if (await this.retain(label, r.value))
+                    observedCount++;
+            }
+        }
+        // Detect over the deduped corpus; a proof is SELF-verifying, but re-check before
+        // persisting (belt and suspenders — the store must never hold a non-proof).
+        const proof = detectEquivocation(await observed.distinct(), logId);
+        if (proof && verifyEquivocation(proof, logId)) {
+            await conflicts.record(proof);
+            return { observed: observedCount, proof, unreachable: [...unreachable] };
+        }
+        return { observed: observedCount, unreachable: [...unreachable] };
+    }
+    /** Verify-before-retain: only an authentic STH for the watched log enters the corpus,
+     *  so junk/forged input can never form a pair. Returns whether it was NEWLY recorded
+     *  (a duplicate re-observation returns false), so the caller counts distinct heads. */
+    async retain(witnessId, sth) {
+        if (sth.logId !== this.cfg.logId || !verifySignedTreeHead(sth))
+            return false;
+        return this.cfg.observed.record(witnessId, sth);
+    }
+    /** Bounded-concurrency fan-out over sources; never throws (per-source settle).
+     *  Delegates to the shared `boundedFanOut` so the monitor and relying-party pollination
+     *  enforce the SAME in-flight cap (POLL_CONCURRENCY). */
+    fanOut(sources, fn) {
+        return boundedFanOut(sources, (s) => fn(s));
+    }
+}
+/**
+ * HttpGossipSource — pulls a witness's endorsed STHs over the wire via `GET /sth?size`,
+ * through the SSRF-safe fetch. `id` is the witness DID (for corpus attribution).
+ */
+export class HttpGossipSource {
+    baseUrl;
+    id;
+    ssrf;
+    constructor(baseUrl, id, ssrf) {
+        this.baseUrl = baseUrl;
+        this.id = id;
+        this.ssrf = ssrf;
+    }
+    async signedHead(treeSize) {
+        const url = treeSize === undefined ? `${this.baseUrl}/sth` : `${this.baseUrl}/sth?size=${treeSize}`;
+        const body = (await safeFetchJson(url, { method: 'GET' }, this.ssrf));
+        return body?.sth ?? undefined;
+    }
+}
+//# sourceMappingURL=monitor.js.map

package/dist/monitor.js.map

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

package/dist/pollination.d.ts

@@ -0,0 +1,109 @@
+/**
+ * pollination.ts — relying-party STH pollination (Phase 6).
+ *
+ * The one sound defense against a TARGETED split-view — an operator that shows a victim a
+ * root B@n it never shows any honest witness. The monitor cannot see B (it never enters the
+ * witnessed world), and quorum verification over the operator's OWN co-signature bundle can
+ * be cherry-picked by the operator. Pollination closes it by having the VICTIM pull each
+ * trusted witness's co-signature DIRECTLY (operator-independent, SSRF-safe) and run the
+ * audited `verifyWitnessedTreeHead`, FAIL-CLOSED: unless >= quorum distinct trusted witnesses
+ * co-signed the EXACT served root, the victim refuses.
+ *
+ * Why it is sound: a witness co-signature is WITNESS-signed over (logId, treeSize, rootHash),
+ * so neither a MITM nor the operator can forge "W endorsed B". The victim asks the witnesses
+ * themselves, so the operator cannot turn suppression into a false ACCEPT — if it withholds the
+ * witness responses the victim simply FAILS CLOSED (detection of the contradiction requires the
+ * victim to actually reach >= quorum honest witnesses directly). It does NOT defeat COLLUSION
+ * (>= quorum witnesses lying together — quorum >= 2 under disjoint control remains the only
+ * in-band lever). And SPENDS NEVER DEPEND ON WITNESS LIVENESS: pollination is an ADDITIONAL
+ * relying-party fail-closed check layered on quorum, not the kernel's safety gate; an
+ * unreachable witness is reported and simply does not count toward the quorum.
+ *
+ * DISPLAY ↔ VERDICT (load-bearing, do not weaken): `confirmed` is taken SOLELY from the audited
+ * `verifyWitnessedTreeHead` — never a hand-ported quorum rule. The display fields
+ * (matched/revoked/unreachable) are a MIRROR of that verdict's own accounting, gated on the
+ * SAME pre-count refusals the verifier applies (the policy.logId pin, the quorum-validity bound,
+ * and STH authenticity). So `matched` can never be reported under a basis the verdict already
+ * rejected — `matched >= quorum` if and only if `confirmed` (see the gate below). The two were
+ * once allowed to diverge on a malformed policy (a §4 over-claim caught by the Phase-6 review);
+ * that is now closed by computing the display under the verifier's exact gates.
+ */
+import { type SignedTreeHead, type WitnessCosignature, type WitnessPolicy } from '@kyaki/core';
+import { type SsrfPolicy } from './ssrf.js';
+/** A trusted witness a relying party pulls a co-signature from. Satisfied in-process by
+ *  `DurableWitness` (it has `id` + `endorsement`) and over the wire by `HttpPollinationSource`.
+ *  `id` SHOULD be set (both built-in implementations set it): a source may only contribute the
+ *  endorsement of the witness it claims to be — see the identity binding in `pollinate`. */
+export interface PollinationSource {
+    /** The witness DID — must be in the relying party's `trustedWitnesses` to count, and must
+     *  match the `witnessId` of the co-signature this source returns. */
+    readonly id?: string;
+    /** This witness's endorsement (its endorsed STH + its own co-signature) at `treeSize`.
+     *  MUST be self-bounding (its own timeout) for a hard liveness guarantee; `pollinate` also
+     *  applies a backstop per-source timeout so a hung source can never wedge the whole call. */
+    endorsement(treeSize?: number): Promise<{
+        sth: SignedTreeHead;
+        cosignature: WitnessCosignature;
+    } | undefined>;
+}
+export interface PollinationResult {
+    /** Fail-closed verdict: did >= quorum DISTINCT trusted, non-revoked witnesses co-sign the
+     *  EXACT (logId, treeSize, rootHash) served? Driven SOLELY by `verifyWitnessedTreeHead`.
+     *
+     *  What `confirmed=true` MEANS — and does NOT: a quorum of the relying party's OWN trusted set
+     *  co-signed the exact served root. It is NOT proof of honesty: COLLUSION of >= quorum trusted
+     *  witnesses is out of scope (raise the bar only with quorum >= 2 under disjoint control, or
+     *  threshold signatures). `confirmed=false` with witnesses `unreachable` is INCONCLUSIVE
+     *  (a liveness gap), not proof of a fork — distinguish it from `confirmed=false` with all
+     *  witnesses reached (corroboration genuinely refused). */
+    confirmed: boolean;
+    /** Distinct trusted, NON-REVOKED witnesses whose co-signature authentically binds the served head.
+     *  Counted exactly as the verdict counts — a revoked witness is never included, and on any input
+     *  the verdict rejects pre-count (wrong operator / invalid quorum / non-authentic STH) `matched`
+     *  is 0, so it can never contradict `confirmed` (e.g. show matched >= quorum while confirmed=false). */
+    matched: number;
+    /** Size of the trusted-witness set (the ORIGINAL allowlist; `revoked` is reported separately so the
+     *  UI can render "N of T, R revoked" transparently rather than silently shrinking the denominator). */
+    total: number;
+    /** Distinct trusted witnesses whose co-signature bound the head but were NOT counted because they
+     *  are revoked (Phase 7 v1b) — a transparency signal, never part of the quorum. */
+    revoked: number;
+    /** Distinct TRUSTED witnesses that could not be reached and did not end up matched or revoked —
+     *  a LIVENESS signal (they never count toward the quorum). Keyed to the trusted set and excludes
+     *  any witness already counted, so matched + revoked + unreachable <= total (a coherent partition);
+     *  a non-trusted source that failed is not surfaced here (it could never have counted anyway). */
+    unreachable: string[];
+}
+/** Optional knobs for `pollinate`. */
+export interface PollinateOptions {
+    /** Backstop timeout (ms) applied to EACH source pull, so a hung source (e.g. an in-process
+     *  durable witness blocked on a store lock) can never wedge the whole call — the "worst-case
+     *  one timeout" liveness guarantee is a property of `pollinate`, not delegated to the source
+     *  type. Set above an HTTP source's own SSRF timeout so it only bites a genuinely hung source.
+     *  Default 10000. */
+    sourceTimeoutMs?: number;
+}
+/**
+ * Pollinate: pull each trusted witness's co-signature at the served head's size and confirm,
+ * fail-closed, that >= quorum distinct trusted witnesses co-signed the EXACT (logId, treeSize,
+ * rootHash) the relying party was served. The verdict is the audited `verifyWitnessedTreeHead`
+ * (never a hand-ported quorum rule). An unreachable witness is reported and never makes the
+ * check pass. Liveness-independent: the fan-out is concurrency-bounded and per-source
+ * timeout-bounded, so neither a large pinned witness set nor a hung source can DoS the victim,
+ * and a pollination failure never blocks a spend (it is an additional relying-party check).
+ */
+export declare function pollinate(servedSth: SignedTreeHead, sources: readonly PollinationSource[], policy: WitnessPolicy, opts?: PollinateOptions): Promise<PollinationResult>;
+/** Pulls a witness's endorsement over the wire via `GET /cosig?size`, SSRF-guarded.
+ *  The load-bearing object is the returned `cosignature` (witness-signed over the exact tuple);
+ *  the returned `sth` is informational and not re-trusted by `pollinate`. */
+export declare class HttpPollinationSource implements PollinationSource {
+    private readonly baseUrl;
+    readonly id: string;
+    private readonly ssrf;
+    constructor(baseUrl: string, id: string, ssrf: SsrfPolicy);
+    endorsement(treeSize?: number): Promise<{
+        sth: SignedTreeHead;
+        cosignature: WitnessCosignature;
+    } | undefined>;
+}
+//# sourceMappingURL=pollination.d.ts.map