@kyaki/witness 0.1.0

package/src/adapters/witness-http.ts

@@ -0,0 +1,235 @@
+/**
+ * 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, 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>;
+
+/** 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: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err);
+  return msg.split(/[:\s]/)[0] ?? 'INTERNAL';
+}
+
+function statusForCode(code: string): number {
+  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: WitnessLike): HttpHandler {
+  return async (req) => {
+    const { method, path } = req;
+
+    if (method === 'POST' && path === '/cosign') {
+      const body = (req.body ?? {}) as { sth?: SignedTreeHead; consistencyProof?: ConsistencyProof };
+      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: number | undefined;
+      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: number | undefined;
+      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: WitnessLike): Server {
+  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: Buffer[] = [];
+    let total = 0;
+    let aborted = false;
+    const fail = (status: number, error: string): void => {
+      // 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: Buffer) => {
+      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 = (): void => {
+        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: unknown;
+        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: Record<string, string> = {};
+        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
+    });
+  });
+}

package/src/durable-witness.ts

@@ -0,0 +1,190 @@
+/**
+ * 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,
+  type ConsistencyProof, type EndorsedHead, type Identity, type SignedTreeHead,
+  type WitnessCosignature, type WitnessHead, type WitnessStateStore,
+} from '@kyaki/core';
+
+export class DurableWitness {
+  private readonly mutex = new KeyedMutex();
+
+  private constructor(
+    private readonly keys: Identity,
+    private readonly logId: string,
+    private readonly store: WitnessStateStore,
+  ) {}
+
+  /**
+   * 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: Identity, logId: string, store: WitnessStateStore): Promise<DurableWitness> {
+    return new DurableWitness(keys, logId, store);
+  }
+
+  get id(): string {
+    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(): Promise<WitnessHead | undefined> {
+    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: SignedTreeHead, consistencyProof?: ConsistencyProof, now?: Date): Promise<WitnessCosignature> {
+    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: WitnessHead = { 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: EndorsedHead = { 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?: number): Promise<SignedTreeHead | undefined> {
+    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?: number): Promise<{ sth: SignedTreeHead; cosignature: WitnessCosignature } | undefined> {
+    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 implements WitnessStateStore {
+  private current: WitnessHead | undefined;
+  private cosignature: WitnessCosignature | undefined;
+  /** 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 = new Map<number, SignedTreeHead>();
+  private chain: Promise<unknown> = Promise.resolve();
+
+  async load(): Promise<WitnessHead | undefined> {
+    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(): Promise<WitnessCosignature | undefined> {
+    return this.cosignature ? { ...this.cosignature } : undefined;
+  }
+
+  /** The endorsed operator STH at `treeSize` (latest if omitted). undefined if none. */
+  async signedHead(treeSize?: number): Promise<SignedTreeHead | undefined> {
+    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: (prior: WitnessHead | undefined) => EndorsedHead): Promise<WitnessCosignature> {
+    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;
+  }
+}

package/src/fan-out.ts

@@ -0,0 +1,34 @@
+/**
+ * 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<S, T>(
+  items: readonly S[],
+  fn: (item: S, index: number) => Promise<T>,
+  concurrency: number = POLL_CONCURRENCY,
+): Promise<PromiseSettledResult<T>[]> {
+  const width = Number.isInteger(concurrency) && concurrency > 0 ? concurrency : POLL_CONCURRENCY;
+  const out: PromiseSettledResult<T>[] = 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;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @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';

package/src/monitor.ts

@@ -0,0 +1,159 @@
+/**
+ * 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,
+  type ConflictStore, type EquivocationProof, type ObservedSthStore, type SignedTreeHead,
+} from '@kyaki/core';
+import { boundedFanOut } from './fan-out.js';
+import { safeFetchJson, 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[];
+}
+
+/** 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 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 class WitnessMonitor {
+  constructor(private readonly 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. */
+  async poll(): Promise<PollResult> {
+    const { logId, sources, observed, conflicts } = this.cfg;
+    const unreachable = new Set<string>();
+    const pulled = new Set<string>();   // `${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<number>();
+    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. */
+  private async retain(witnessId: string, sth: SignedTreeHead): Promise<boolean> {
+    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). */
+  private fanOut<T>(
+    sources: WitnessGossipSource[],
+    fn: (s: WitnessGossipSource) => Promise<T>,
+  ): Promise<PromiseSettledResult<T>[]> {
+    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 implements WitnessGossipSource {
+  constructor(
+    private readonly baseUrl: string,
+    readonly id: string,
+    private readonly ssrf: SsrfPolicy,
+  ) {}
+
+  async signedHead(treeSize?: number): Promise<SignedTreeHead | undefined> {
+    const url = treeSize === undefined ? `${this.baseUrl}/sth` : `${this.baseUrl}/sth?size=${treeSize}`;
+    const body = (await safeFetchJson(url, { method: 'GET' }, this.ssrf)) as { sth?: SignedTreeHead | null } | undefined;
+    return body?.sth ?? undefined;
+  }
+}