@kyaki/witness 0.1.0

package/dist/pollination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollination.d.ts","sourceRoot":"","sources":["../src/pollination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAEL,KAAK,cAAc,EAAE,KAAK,kBAAkB,EAA0B,KAAK,aAAa,EACzF,MAAM,aAAa,CAAC;AAErB,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAE3D;;;4FAG4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC;yEACqE;IACrE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB;;iGAE6F;IAC7F,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,iBAAiB;IAChC;;;;;;;;+DAQ2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB;;;4GAGwG;IACxG,OAAO,EAAE,MAAM,CAAC;IAChB;2GACuG;IACvG,KAAK,EAAE,MAAM,CAAC;IACd;uFACmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB;;;sGAGkG;IAClG,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B;;;;yBAIqB;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAkBD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAuF5B;AAQD;;6EAE6E;AAC7E,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAU,QAAQ,CAAC,EAAE,EAAE,MAAM;IAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAA3D,OAAO,EAAE,MAAM,EAAW,EAAE,EAAE,MAAM,EAAmB,IAAI,EAAE,UAAU;IAE9F,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,cAAc,CAAC;QAAC,WAAW,EAAE,kBAAkB,CAAA;KAAE,GAAG,SAAS,CAAC;CAOpH"}

package/dist/pollination.js

@@ -0,0 +1,170 @@
+/**
+ * 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 { verifyWitnessedTreeHead, verifyWitnessCosignature, verifySignedTreeHead, } from '@kyaki/core';
+import { boundedFanOut } from './fan-out.js';
+import { safeFetchJson } from './ssrf.js';
+const DEFAULT_SOURCE_TIMEOUT_MS = 10_000;
+/** Resolve `p`, or reject with POLLINATION_SOURCE_TIMEOUT after `ms`. The underlying work may
+ *  continue (an in-process op is not cancellable) but its result is ignored — what is bounded is
+ *  how long the caller WAITS, which is the liveness property that matters. ms<=0 disables the bound. */
+function withTimeout(p, ms) {
+    if (!Number.isFinite(ms) || ms <= 0)
+        return p;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('POLLINATION_SOURCE_TIMEOUT')), ms);
+        p.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+/**
+ * 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 async function pollinate(servedSth, sources, policy, opts) {
+    const trusted = new Set(policy.trustedWitnesses ?? []);
+    const revoked = new Set(policy.revokedWitnesses ?? []); // Phase 7 v1b — proven equivocators
+    const timeoutMs = opts?.sourceTimeoutMs ?? DEFAULT_SOURCE_TIMEOUT_MS;
+    // Guard the served size at the boundary: a non-integer/negative treeSize can only come from a
+    // malformed STH (which `verifyWitnessedTreeHead` rejects anyway) and would build a junk
+    // `?size=NaN` query. Skip the fetch entirely in that case — but STILL derive `confirmed` from
+    // the audited verifier below (never hand-decide it).
+    const validSize = Number.isInteger(servedSth.treeSize) && servedSth.treeSize >= 0;
+    const cosignatures = [];
+    const downLabels = [];
+    if (validSize) {
+        // Pull every source with a BOUNDED in-flight cap (a large pinned set can't exhaust sockets/heap)
+        // and a per-source backstop timeout. Each branch catches its OWN failure — including a null/
+        // malformed source entry (the label is computed defensively) — so a dead source lands in
+        // `unreachable` and never rejects the whole call. Worst-case wall-clock is one timeout per batch.
+        const settled = await boundedFanOut(sources, async (src, i) => {
+            const label = src?.id ?? `witness#${i}`;
+            try {
+                const e = await withTimeout(src.endorsement(servedSth.treeSize), timeoutMs);
+                const cosig = e?.cosignature;
+                if (!cosig)
+                    return { down: label }; // no endorsement ⇒ cannot corroborate
+                // Bind the source's claimed identity to the co-signature it returns: a source may only
+                // ever contribute its OWN endorsement, so a single (possibly operator-controlled) endpoint
+                // cannot stand in for the quorum by replaying several witnesses' public co-signatures — the
+                // operator-INDEPENDENCE the mechanism rests on. A mismatch ⇒ this source did not return its
+                // own endorsement ⇒ treat it as no corroboration (it never counts toward quorum).
+                if (src?.id !== undefined && cosig.witnessId !== src.id)
+                    return { down: label };
+                return { cosig };
+            }
+            catch {
+                return { down: label }; // transport failure / timeout ⇒ liveness
+            }
+        });
+        for (const r of settled) {
+            if (r.status !== 'fulfilled')
+                continue; // boundedFanOut settles per item and never throws; defensive
+            if ('cosig' in r.value)
+                cosignatures.push(r.value.cosig);
+            else
+                downLabels.push(r.value.down);
+        }
+    }
+    const wth = { sth: servedSth, cosignatures };
+    const confirmed = verifyWitnessedTreeHead(wth, policy); // the AUTHORITATIVE fail-closed verdict
+    // DISPLAY-NEVER-CONTRADICTS-VERDICT. The display fields must mirror EXACTLY what the verdict
+    // counts. `verifyWitnessedTreeHead` refuses BEFORE counting any endorser when the served head is
+    // not the pinned operator's authentic STH (its logId != policy.logId, or the operator signature is
+    // invalid), the trusted set is empty, or the quorum is structurally invalid. On ANY of those the
+    // honest display is "0 corroborated" — never a parallel count under a basis the verdict already
+    // rejected. Mirror those exact pre-count gates (transparency.ts verifyWitnessedTreeHead) here.
+    const quorum = policy.quorum ?? trusted.size;
+    const quorumValid = Number.isInteger(quorum) && quorum >= 1 && quorum <= trusted.size;
+    const structurallyValid = validSize
+        && trusted.size > 0
+        && quorumValid
+        && servedSth.logId === policy.logId // the policy.logId PIN — NOT the served head's own logId
+        && verifySignedTreeHead(servedSth); // authentic operator STH (catches a forged sig over a real root)
+    if (!structurallyValid) {
+        return { confirmed, matched: 0, total: trusted.size, revoked: 0, unreachable: trustedDistinct(downLabels, trusted) };
+    }
+    // On the structurally-valid path these per-cosig filters are byte-identical to
+    // `verifyWitnessedTreeHead`'s (self-witness exclusion, trusted membership, exact tuple, authentic
+    // cosig, revocation skip, distinct-by-witnessId), so `endorsers.size === the verifier's count` and
+    // `matched >= quorum  <=>  confirmed`. This is a DISPLAY mirror of the verdict, never a substitute.
+    const endorsers = new Set();
+    const revokedSeen = new Set(); // DISTINCT revoked witnesses that bound the head (never counted)
+    for (const c of cosignatures) {
+        if (!c || c.witnessId === policy.logId)
+            continue; // no operator self-witness (policy.logId == servedSth.logId here)
+        if (!trusted.has(c.witnessId))
+            continue;
+        if (c.logId !== policy.logId || c.treeSize !== servedSth.treeSize || c.rootHash !== servedSth.rootHash)
+            continue;
+        if (!verifyWitnessCosignature(c))
+            continue;
+        if (revoked.has(c.witnessId)) {
+            revokedSeen.add(c.witnessId);
+            continue;
+        } // bound the head, but NOT counted (v1b)
+        endorsers.add(c.witnessId);
+    }
+    // `unreachable`: distinct TRUSTED witnesses whose source(s) failed, EXCLUDING any that ended up
+    // matched or revoked (a witness reachable on one endpoint and down on another is NOT "unreachable").
+    // Keyed to the trusted set so matched + revoked + unreachable <= total — a coherent partition.
+    const unreachable = [...new Set(downLabels)].filter((id) => trusted.has(id) && !endorsers.has(id) && !revokedSeen.has(id));
+    return { confirmed, matched: endorsers.size, total: trusted.size, revoked: revokedSeen.size, unreachable };
+}
+/** Distinct TRUSTED labels from a down-source list — the `unreachable` field on a structurally
+ *  refused head (no witness can have counted, so there is nothing to exclude). */
+function trustedDistinct(labels, trusted) {
+    return [...new Set(labels)].filter((id) => trusted.has(id));
+}
+/** 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 class HttpPollinationSource {
+    baseUrl;
+    id;
+    ssrf;
+    constructor(baseUrl, id, ssrf) {
+        this.baseUrl = baseUrl;
+        this.id = id;
+        this.ssrf = ssrf;
+    }
+    async endorsement(treeSize) {
+        const url = treeSize === undefined ? `${this.baseUrl}/cosig` : `${this.baseUrl}/cosig?size=${treeSize}`;
+        const body = (await safeFetchJson(url, { method: 'GET' }, this.ssrf));
+        if (!body?.sth || !body.cosignature)
+            return undefined;
+        return { sth: body.sth, cosignature: body.cosignature };
+    }
+}
+//# sourceMappingURL=pollination.js.map

package/dist/pollination.js.map

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

package/dist/ssrf.d.ts

@@ -0,0 +1,20 @@
+export interface SsrfPolicy {
+    /** Exact hostnames (lowercased) the monitor may connect to — the pinned witness set.
+     *  REQUIRED and non-empty: an empty allowlist refuses everything (fail-closed). */
+    allowHosts: string[];
+    /** Permit plain http and loopback/private targets — loopback dev & tests ONLY.
+     *  Default false ⇒ https required and every internal range is refused. */
+    allowHttp?: boolean;
+    /** Max response body bytes. Default 64 KiB (an STH/proof is well under 1 KiB). */
+    maxBytes?: number;
+    /** Per-request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+}
+/** Is `ip` (a valid v4/v6 literal) in a loopback/private/link-local/ULA/CGNAT/NAT64 range? */
+export declare function isPrivateIp(ip: string): boolean;
+/** Validate a URL against the policy; throws a named `SSRF_*` error on any violation. */
+export declare function assertSafeUrl(rawUrl: string, policy: SsrfPolicy): Promise<void>;
+/** A fetch that enforces the SSRF policy, blocks redirects, and caps body + time.
+ *  Returns the parsed JSON body (or throws on a non-2xx / oversize / timeout). */
+export declare function safeFetchJson(rawUrl: string, init: RequestInit, policy: SsrfPolicy): Promise<unknown>;
+//# sourceMappingURL=ssrf.d.ts.map

package/dist/ssrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf.d.ts","sourceRoot":"","sources":["../src/ssrf.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,UAAU;IACzB;uFACmF;IACnF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;8EAC0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAqC/C;AAED,yFAAyF;AACzF,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCrF;AAoCD;kFACkF;AAClF,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA0B3G"}

package/dist/ssrf.js

@@ -0,0 +1,205 @@
+/**
+ * ssrf.ts — an SSRF-safe outbound fetch for the WitnessMonitor (RULES §5.3).
+ *
+ * The monitor PULLS operator-signed STHs from witness URLs. Left unguarded, a witness
+ * base URL of `http://169.254.169.254/` (cloud metadata) or `http://localhost:5432`
+ * (an internal service) turns the monitor into a server-side request forgery primitive.
+ * §0 ranks security above correctness, so this is a build-blocking control, not a
+ * deployment afterthought. The layered defense:
+ *   1. HOST ALLOWLIST — the monitor may only connect to the hostnames of its
+ *      CONFIG-PINNED witness set; a request to any other host is refused. (The witness
+ *      set is operator-INDEPENDENT and not attacker-registerable — that is the whole
+ *      basis of the cross-party guarantee, so pinning it here is free.)
+ *   2. SCHEME — https only, unless `allowHttp` is set for loopback dev/tests.
+ *   3. NO INTERNAL TARGETS — reject IP-literal hosts in loopback/RFC1918/link-local/ULA
+ *      ranges, AND resolve hostnames and reject any answer in those ranges
+ *      (resolve-then-check defeats a DNS-rebinding allowlisted name pointing inward).
+ *   4. NO REDIRECTS — `redirect: 'error'` so a 3xx to an internal target cannot smuggle
+ *      past the checks; BODY CAP + TIMEOUT so a hostile/slow endpoint cannot exhaust
+ *      heap or wedge a polling round.
+ *
+ * Residual (documented): a TOCTOU between resolve-check and connect remains (the OS may
+ * re-resolve to a different IP). The host allowlist is the primary control; full IP
+ * pinning of the connection is the further hardening if the monitor is ever pointed at
+ * untrusted-DNS hosts. For a pinned, operator-independent witness set this is sufficient.
+ */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const DEFAULT_MAX_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Map a pair of 16-bit hex groups (the low 32 bits of a v6 address) to dotted v4. */
+function hexPairToV4(hiHex, loHex) {
+    const hi = parseInt(hiHex, 16), lo = parseInt(loHex, 16);
+    return `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
+}
+/** Is `ip` (a valid v4/v6 literal) in a loopback/private/link-local/ULA/CGNAT/NAT64 range? */
+export function isPrivateIp(ip) {
+    const v = isIP(ip);
+    if (v === 4) {
+        const p = ip.split('.').map(Number);
+        if (p.length !== 4 || p.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+            return true; // malformed ⇒ unsafe
+        const [a, b] = p;
+        if (a === 10)
+            return true; // 10.0.0.0/8
+        if (a === 127)
+            return true; // loopback
+        if (a === 0)
+            return true; // 0.0.0.0/8 unspecified
+        if (a === 169 && b === 254)
+            return true; // link-local
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // 172.16.0.0/12
+        if (a === 192 && b === 168)
+            return true; // 192.168.0.0/16
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // 100.64.0.0/10 carrier-grade NAT (RFC 6598)
+        if (a === 198 && (b === 18 || b === 19))
+            return true; // 198.18.0.0/15 benchmarking
+        if (a >= 224)
+            return true; // multicast / reserved
+        return false;
+    }
+    if (v === 6) {
+        const ip6 = ip.toLowerCase().replace(/^\[|\]$/g, '');
+        if (ip6 === '::1' || ip6 === '::')
+            return true; // loopback / unspecified
+        if (ip6.startsWith('fe80'))
+            return true; // link-local
+        if (ip6.startsWith('fc') || ip6.startsWith('fd'))
+            return true; // ULA fc00::/7
+        // IPv4-mapped (::ffff:a.b.c.d AND its hex-quad form ::ffff:7f00:1) — re-check the v4.
+        const mapped = ip6.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+        if (mapped)
+            return isPrivateIp(mapped[1]);
+        const hexMapped = ip6.match(/::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+        if (hexMapped)
+            return isPrivateIp(hexPairToV4(hexMapped[1], hexMapped[2]));
+        // NAT64 well-known prefix (64:ff9b::/96) embeds an arbitrary v4 destination — a gateway
+        // forwards 64:ff9b::7f00:1 to 127.0.0.1, so the embedded v4 must be re-checked too.
+        const nat64Dotted = ip6.match(/^64:ff9b::(\d+\.\d+\.\d+\.\d+)$/);
+        if (nat64Dotted)
+            return isPrivateIp(nat64Dotted[1]);
+        const nat64Hex = ip6.match(/^64:ff9b::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+        if (nat64Hex)
+            return isPrivateIp(hexPairToV4(nat64Hex[1], nat64Hex[2]));
+        if (ip6 === '64:ff9b::')
+            return true; // the bare NAT64 prefix
+        return false;
+    }
+    return true; // not a recognizable IP ⇒ treat as unsafe
+}
+/** Validate a URL against the policy; throws a named `SSRF_*` error on any violation. */
+export async function assertSafeUrl(rawUrl, policy) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error('SSRF_INVALID_URL');
+    }
+    const allowHttp = policy.allowHttp === true;
+    if (url.protocol !== 'https:' && !(allowHttp && url.protocol === 'http:')) {
+        throw new Error(`SSRF_SCHEME_FORBIDDEN: ${url.protocol}`);
+    }
+    const host = url.hostname.toLowerCase();
+    const allow = new Set((policy.allowHosts ?? []).map((h) => h.toLowerCase()));
+    if (allow.size === 0 || !allow.has(host)) {
+        throw new Error(`SSRF_HOST_NOT_ALLOWED: ${host}`);
+    }
+    // An IP-literal host: check the literal directly.
+    if (isIP(host)) {
+        if (isPrivateIp(host) && !allowHttp)
+            throw new Error(`SSRF_PRIVATE_IP: ${host}`);
+        return;
+    }
+    // A hostname: resolve and reject any answer in an internal range (DNS-rebinding guard).
+    if (!allowHttp) {
+        let addrs;
+        try {
+            addrs = await lookup(host, { all: true });
+        }
+        catch {
+            throw new Error(`SSRF_DNS_FAILED: ${host}`);
+        }
+        if (addrs.length === 0)
+            throw new Error(`SSRF_DNS_EMPTY: ${host}`);
+        for (const { address } of addrs) {
+            if (isPrivateIp(address))
+                throw new Error(`SSRF_RESOLVES_PRIVATE: ${host} -> ${address}`);
+        }
+    }
+}
+/**
+ * Read a response body, aborting the moment the running byte total exceeds `maxBytes`.
+ * NEVER trusts Content-Length (a hostile/chunked endpoint omits it): the cap is enforced
+ * while STREAMING, so heap is bounded to maxBytes + one chunk regardless of the header or
+ * transfer encoding. `res.text()` would buffer the whole body BEFORE any size check — the
+ * exact DoS this avoids.
+ */
+async function readCappedText(res, maxBytes, controller) {
+    const reader = res.body?.getReader();
+    if (!reader) { // no stream available — still cap, never unbounded
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length > maxBytes)
+            throw new Error(`SSRF_BODY_TOO_LARGE: > ${maxBytes}`);
+        return buf.toString('utf8');
+    }
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                controller.abort(); // stop the transfer immediately
+                throw new Error(`SSRF_BODY_TOO_LARGE: > ${maxBytes}`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch { /* already released on abort */ }
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** A fetch that enforces the SSRF policy, blocks redirects, and caps body + time.
+ *  Returns the parsed JSON body (or throws on a non-2xx / oversize / timeout). */
+export async function safeFetchJson(rawUrl, init, policy) {
+    const maxBytes = policy.maxBytes ?? DEFAULT_MAX_BYTES;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), policy.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        // The DNS resolve inside assertSafeUrl is NOT abortable (node:dns/promises.lookup ignores
+        // AbortSignal), so race it against the SAME timeout — otherwise a slow-resolving (but
+        // allowlisted) host blows past the per-request ceiling before fetch even starts.
+        const aborted = new Promise((_, reject) => {
+            controller.signal.addEventListener('abort', () => reject(new Error('SSRF_TIMEOUT')), { once: true });
+        });
+        await Promise.race([assertSafeUrl(rawUrl, policy), aborted]);
+        const res = await fetch(rawUrl, { ...init, redirect: 'error', signal: controller.signal });
+        if (res.status === 204)
+            return undefined;
+        if (!res.ok)
+            throw new Error(`HTTP_${res.status}`);
+        // A declared oversized Content-Length is a cheap fast-fail; but a MISSING/zero header is
+        // "unknown size", NOT "safe" — the streaming reader enforces the real cap either way.
+        const declared = Number(res.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            throw new Error(`SSRF_BODY_TOO_LARGE: ${declared} > ${maxBytes}`);
+        }
+        const text = await readCappedText(res, maxBytes, controller);
+        return text ? JSON.parse(text) : undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=ssrf.js.map

package/dist/ssrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf.js","sourceRoot":"","sources":["../src/ssrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAehC,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,CAAC;AACpC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,sFAAsF;AACtF,SAAS,WAAW,CAAC,KAAa,EAAE,KAAa;IAC/C,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;AACzE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACZ,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,qBAAqB;QACjH,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAqC,CAAC;QACrD,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC,CAAyB,aAAa;QAChE,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC,CAAwB,WAAW;QAC9D,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAA0B,wBAAwB;QAC3E,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC,CAAW,aAAa;QAChE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YAAE,OAAO,IAAI,CAAC,CAAE,gBAAgB;QACnE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC,CAAW,iBAAiB;QACpE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,GAAG;YAAE,OAAO,IAAI,CAAC,CAAC,6CAA6C;QAChG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,6BAA6B;QACnF,IAAI,CAAC,IAAI,GAAG;YAAE,OAAO,IAAI,CAAC,CAAyB,uBAAuB;QAC1E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACZ,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACrD,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,CAAuB,yBAAyB;QAC/F,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,CAA6B,aAAa;QAClF,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,CAAO,eAAe;QACpF,sFAAsF;QACtF,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;QACzD,IAAI,MAAM;YAAE,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACvE,IAAI,SAAS;YAAE,OAAO,WAAW,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAE,EAAE,SAAS,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;QAC7E,wFAAwF;QACxF,oFAAoF;QACpF,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACjE,IAAI,WAAW;YAAE,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;QACzE,IAAI,QAAQ;YAAE,OAAO,WAAW,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC;QAC1E,IAAI,GAAG,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC,CAAgC,wBAAwB;QAC7F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,0CAA0C;AACzD,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,MAAkB;IACpE,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,KAAK,IAAI,CAAC;IAC5C,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC7E,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,kDAAkD;IAClD,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACf,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;QACjF,OAAO;IACT,CAAC;IACD,wFAAwF;IACxF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,IAAI,KAA4B,CAAC;QACjC,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QACnE,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,KAAK,EAAE,CAAC;YAChC,IAAI,WAAW,CAAC,OAAO,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,OAAO,OAAO,EAAE,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,cAAc,CAAC,GAAa,EAAE,QAAgB,EAAE,UAA2B;IACxF,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;IACrC,IAAI,CAAC,MAAM,EAAE,CAAC,CAA8B,mDAAmD;QAC7F,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;QACjD,IAAI,GAAG,CAAC,MAAM,GAAG,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,EAAE,CAAC,CAAC;QACjF,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC;YAC1B,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;gBACrB,UAAU,CAAC,KAAK,EAAE,CAAC,CAAmB,gCAAgC;gBACtE,MAAM,IAAI,KAAK,CAAC,0BAA0B,QAAQ,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,+BAA+B,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;kFACkF;AAClF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,IAAiB,EAAE,MAAkB;IACvF,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAC;IAC3F,IAAI,CAAC;QACH,0FAA0F;QAC1F,sFAAsF;QACtF,iFAAiF;QACjF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;YAC/C,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACvG,CAAC,CAAC,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7D,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3F,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,SAAS,CAAC;QACzC,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACnD,yFAAyF;QACzF,sFAAsF;QACtF,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAC3D,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,MAAM,QAAQ,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7C,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@kyaki/witness",
+  "version": "0.1.0",
+  "description": "KYA external witness — a durable, independent co-signing party; gossip monitor, pollination, accountability, and SSRF-safe transport.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@kyaki/core": "^0.1.0"
+  }
+}

package/src/accountability.ts

@@ -0,0 +1,72 @@
+/**
+ * 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,
+  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 class WitnessAccountabilityMonitor {
+  constructor(private readonly 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.
+   */
+  async observe(cosig: WitnessCosignature): Promise<WitnessEquivocationProof | undefined> {
+    // 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(): Promise<WitnessEquivocationProof[]> {
+    const out: WitnessEquivocationProof[] = [];
+    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. */
+  private async detectFor(witnessId: string): Promise<WitnessEquivocationProof | undefined> {
+    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);
+  }
+}

package/src/adapters/monitor-http.ts

@@ -0,0 +1,69 @@
+/**
+ * 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, type Server } from 'node:http';
+import type { ConflictStore } from '@kyaki/core';
+
+/** Bumped if the wire shape of the /conflict body changes (consumer compatibility). */
+export 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 function createMonitorHttpHandler(conflicts: ConflictStore): MonitorHttpHandler {
+  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: ConflictStore): Server {
+  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' }));
+      }
+    })();
+  });
+}