@intyga/verify 0.0.0-bootstrap.0 → 1.0.0

package/dist/ledger-chain.d.ts

@@ -0,0 +1,58 @@
+export declare const CHAIN_TAG = 4;
+/** The genesis predecessor. No real chain hash can collide: those are always 64 hex characters. */
+export declare const GENESIS_PREV_CHAIN_HASH = "";
+/** One line of a published `roots.jsonl` (v2), as far as chain verification is concerned. */
+export interface RootsChainEntry {
+    seqStart: string;
+    seqEnd: string;
+    entryCount: number;
+    root: string;
+    anchoredAt: string;
+    prevChainHash?: string;
+    chainHash?: string;
+}
+export interface ChainInput {
+    prevChainHash: string;
+    root: string;
+    seqStart: string;
+    seqEnd: string;
+    entryCount: number;
+    anchoredAt: string;
+}
+/**
+ * The canonical chain preimage: RFC 8785 JCS of a 6-element array of STRINGS. Every element is
+ * stringified — including counts — so JCS reduces to plain `JSON.stringify` and no verifier has to
+ * implement RFC 8785 number canonicalization. `anchorPreimage` makes the same trade.
+ */
+export declare function chainPreimage(c: ChainInput): string;
+/** The chain hash: `SHA-256(0x04 || UTF8(chainPreimage))`, hex. */
+export declare function chainHash(c: ChainInput): string;
+export interface ChainVerification {
+    ok: boolean;
+    /** Entries whose chain hash recomputed AND linked to their predecessor. */
+    verifiedCount: number;
+    /** Index of the first entry that failed, or -1 when everything verified. */
+    brokenAt: number;
+    /**
+     * True when the entries carry no chain fields at all — a pre-chain (v1) roots file. Reported
+     * separately from a broken chain because "this file is older than the chain" and "someone edited
+     * this file" are completely different findings and must never be conflated in an alert.
+     */
+    unchained: boolean;
+    reason?: string;
+}
+/**
+ * Verify a published roots sequence: recompute every chain hash, check each entry links to its
+ * predecessor, and check the covered seq ranges advance without overlapping.
+ *
+ * On global seq: `AuditLog.seq` is a Postgres `autoincrement()` sequence, and Postgres sequences are
+ * NON-transactional — a rolled-back audit insert burns its value permanently. Global seq therefore
+ * has legitimate holes in healthy operation, which is exactly why DEWP uses the transactionally
+ * allocated per-tenant `tenantSeq` for gapless completeness and calls global `seq` "ordering only".
+ * So this checks `seqStart(N+1) > seqEnd(N)` (monotonic, non-overlapping) and NOT `== seqEnd(N) + 1`:
+ * the strict form would fire on ordinary rollbacks and train operators to ignore the alarm. Deletion
+ * of an entry is caught by the chain link, which is the mechanism that actually detects it.
+ *
+ * `entries` MUST be in published order (ascending `seqEnd`), which is the order they appear in the file.
+ */
+export declare function verifyRootsChain(entries: RootsChainEntry[]): ChainVerification;

package/dist/ledger-chain.js

@@ -0,0 +1,121 @@
+import crypto from "node:crypto";
+// Checkpoint continuity chain (DEWP §5.4) — the verification half. Zero deps beyond node:crypto.
+//
+// An inclusion proof says "this event is under daily root R". It says nothing about whether the
+// SEQUENCE of daily roots was rewritten — a published roots file with one day silently replaced or
+// removed is internally consistent and verifies fine. The chain closes that hole: each checkpoint
+// commits to its predecessor under the 0x04 domain tag, so the sequence can be extended but not
+// edited or reordered without breaking every link after the edit.
+//
+// SCOPE — read this before quoting it as a consistency proof. This is NOT an RFC 6962 consistency
+// proof. It proves the root SEQUENCE is unrewritten. It does not prove the leaves under an earlier
+// root are unchanged; that comes from each root being independently anchored to an external log
+// (Rekor / RFC 3161) that the producer cannot edit. Chain + external anchors together are what make
+// history-rewriting detectable — neither alone is sufficient.
+//
+// MUST stay byte-identical to the producer in @intyga/db (chain.ts).
+export const CHAIN_TAG = 0x04;
+/** The genesis predecessor. No real chain hash can collide: those are always 64 hex characters. */
+export const GENESIS_PREV_CHAIN_HASH = "";
+/**
+ * The canonical chain preimage: RFC 8785 JCS of a 6-element array of STRINGS. Every element is
+ * stringified — including counts — so JCS reduces to plain `JSON.stringify` and no verifier has to
+ * implement RFC 8785 number canonicalization. `anchorPreimage` makes the same trade.
+ */
+export function chainPreimage(c) {
+    return JSON.stringify([c.prevChainHash, c.root, c.seqStart, c.seqEnd, String(c.entryCount), c.anchoredAt]);
+}
+/** The chain hash: `SHA-256(0x04 || UTF8(chainPreimage))`, hex. */
+export function chainHash(c) {
+    return crypto
+        .createHash("sha256")
+        .update(Buffer.from([CHAIN_TAG]))
+        .update(Buffer.from(chainPreimage(c), "utf8"))
+        .digest("hex");
+}
+function fail(brokenAt, reason, verifiedCount) {
+    return { ok: false, verifiedCount, brokenAt, unchained: false, reason };
+}
+/**
+ * Verify a published roots sequence: recompute every chain hash, check each entry links to its
+ * predecessor, and check the covered seq ranges advance without overlapping.
+ *
+ * On global seq: `AuditLog.seq` is a Postgres `autoincrement()` sequence, and Postgres sequences are
+ * NON-transactional — a rolled-back audit insert burns its value permanently. Global seq therefore
+ * has legitimate holes in healthy operation, which is exactly why DEWP uses the transactionally
+ * allocated per-tenant `tenantSeq` for gapless completeness and calls global `seq` "ordering only".
+ * So this checks `seqStart(N+1) > seqEnd(N)` (monotonic, non-overlapping) and NOT `== seqEnd(N) + 1`:
+ * the strict form would fire on ordinary rollbacks and train operators to ignore the alarm. Deletion
+ * of an entry is caught by the chain link, which is the mechanism that actually detects it.
+ *
+ * `entries` MUST be in published order (ascending `seqEnd`), which is the order they appear in the file.
+ */
+export function verifyRootsChain(entries) {
+    if (entries.length === 0) {
+        return { ok: true, verifiedCount: 0, brokenAt: -1, unchained: false };
+    }
+    const chained = entries.filter((e) => e.chainHash !== undefined);
+    if (chained.length === 0) {
+        return {
+            ok: false,
+            verifiedCount: 0,
+            brokenAt: -1,
+            unchained: true,
+            reason: "roots file carries no chain hashes (pre-DEWP-5.4 v1 file); continuity cannot be checked",
+        };
+    }
+    if (chained.length !== entries.length) {
+        // A partially chained file means someone spliced old and new lines together. Refuse to guess
+        // which half is authentic.
+        return fail(entries.findIndex((e) => e.chainHash === undefined), "roots file mixes chained and unchained entries", 0);
+    }
+    let verifiedCount = 0;
+    let prev;
+    let prevEnd;
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        if (e === undefined)
+            return fail(i, "roots entry missing", verifiedCount);
+        const expectedPrev = prev === undefined ? GENESIS_PREV_CHAIN_HASH : (prev.chainHash ?? "");
+        const declaredPrev = e.prevChainHash ?? GENESIS_PREV_CHAIN_HASH;
+        if (declaredPrev !== expectedPrev) {
+            return fail(i, `chain link broken at seqEnd=${e.seqEnd}: prevChainHash ${declaredPrev || "(genesis)"} does not match predecessor ${expectedPrev || "(genesis)"}`, verifiedCount);
+        }
+        const recomputed = chainHash({
+            prevChainHash: declaredPrev,
+            root: e.root,
+            seqStart: e.seqStart,
+            seqEnd: e.seqEnd,
+            entryCount: e.entryCount,
+            anchoredAt: e.anchoredAt,
+        });
+        if (recomputed !== e.chainHash) {
+            return fail(i, `chain hash mismatch at seqEnd=${e.seqEnd}: recomputed ${recomputed}, file says ${e.chainHash}`, verifiedCount);
+        }
+        // The entry's OWN range is checked unconditionally. A non-integer or self-inverted range is
+        // malformed wherever it sits, and gating this on having a predecessor let the FIRST entry
+        // through unvalidated — so a single-entry roots file (a new tenant, or the first day after a
+        // truncation) was never range-checked at all. Only the overlap check is relational, because
+        // only it needs a predecessor. Go and Rust always did it this way; TS, Java and Python did not,
+        // which meant the same roots.jsonl verified clean in three ports and was refused by two.
+        let thisStart;
+        let thisEnd;
+        try {
+            thisStart = BigInt(e.seqStart);
+            thisEnd = BigInt(e.seqEnd);
+        }
+        catch {
+            return fail(i, `non-integer seq range at index ${i}`, verifiedCount);
+        }
+        if (thisEnd < thisStart) {
+            return fail(i, `seq range inverted: seqStart=${thisStart} > seqEnd=${thisEnd}`, verifiedCount);
+        }
+        if (prevEnd !== undefined && thisStart <= prevEnd) {
+            return fail(i, `seq ranges overlap or regress: entry starts at ${thisStart} but predecessor ended at ${prevEnd}`, verifiedCount);
+        }
+        verifiedCount++;
+        prev = e;
+        prevEnd = thisEnd;
+    }
+    return { ok: true, verifiedCount, brokenAt: -1, unchained: false };
+}

package/dist/ledger-evidence.d.ts

@@ -0,0 +1,193 @@
+import { type AnchorKeyResolver, type AnchorPolicy, type ExternalAnchorKeys, type SignedAnchor } from "./ledger-anchor.js";
+import { type AlgorithmRegistry, type TrustedCheckpoint } from "./ledger-bundle.js";
+import { type AuditSignaturePolicy, type AuditSignatureCheck } from "./ledger-signature.js";
+import { type AuditLeaf } from "./ledger-leaf.js";
+import { type InclusionProof } from "./ledger-proof.js";
+export declare const EVIDENCE_BUNDLE_KIND = "dewp.audit.evidence-bundle";
+/**
+ * DEWP §6.3/§16 redaction record. `COMMITMENT_ONLY` means content was lawfully purged under a
+ * retention or erasure policy while the Merkle commitment was preserved — recording *that* it was
+ * purged and *why* is what lets an auditor tell lawful redaction from tampering.
+ */
+export interface RedactionRecord {
+    mode: "NONE" | "COMMITMENT_ONLY";
+    removedFields?: string[];
+    redactedAt?: string;
+    reason?: string;
+    commitment?: {
+        leaf: string;
+        tenantSeq?: string | null;
+    };
+}
+export interface EvidenceEntry {
+    event: {
+        seq: string;
+        createdAt: string;
+        type: string;
+        outcome: string;
+        /** DEWP §6.3 redaction record. Preferred over the legacy `redacted` boolean below. */
+        redaction?: RedactionRecord;
+        /** Legacy boolean form, still read so bundles exported before `redaction` keep verifying. */
+        redacted?: boolean;
+        /**
+         * Per-tenant monotonic counter, present on redacted entries too (DEWP §16).
+         *
+         * DISPLAY COPY. It is a sibling of `canonical` and is covered by nothing — not the leaf, not the
+         * root, not any anchor. The gapless check reads `canonical.tenantSeq` whenever a preimage is
+         * present, and falls back to the redaction record or this copy only for an entry with no preimage
+         * (a COMMITMENT_ONLY redaction), saying so in the verdict notes (DEWP §7.2).
+         */
+        tenantSeq?: string | null;
+        signerDid: string | null;
+        sigAlg: string | null;
+        /** Full canonical preimage — present only for unredacted entries. */
+        canonical?: AuditLeaf;
+    };
+    proof: InclusionProof;
+}
+export interface EvidenceBundle {
+    /** DEWP §6.3 envelope. Absent on bundles exported before the envelope was added. */
+    protocol?: string;
+    kind: typeof EVIDENCE_BUNDLE_KIND;
+    version: string | number;
+    /** Canonical-preimage Application Profile (§4.5). */
+    profile?: string;
+    algorithmRegistry?: AlgorithmRegistry;
+    exportedAt: string;
+    /**
+     * The tenant the bundle is for. Every content-verified entry must carry this `tenantId` (or none),
+     * so `tenantSeq` contiguity is judged over ONE tenant's counter. Absent or null, any entry that
+     * names a tenant is refused (DEWP §7.2).
+     */
+    tenant?: {
+        id: string | null;
+        name: string | null;
+    } | null;
+    range: {
+        from: string;
+        to: string;
+    };
+    /**
+     * The contiguous committed tenantSeq range this bundle CLAIMS to cover (§6.3). Checking the entries
+     * against it is what turns "these entries happen to be contiguous" into "nothing was dropped from
+     * the range that was asked for" — without it, a producer could silently narrow the export.
+     */
+    tenantSequenceCommitment?: {
+        tenantId: string;
+        firstTenantSeq: string;
+        lastTenantSeq: string;
+    };
+    entries: EvidenceEntry[];
+    checkpoints: {
+        id: string;
+        root: string;
+        anchorRef: string | null;
+        anchoredAt: string | null;
+        seqStart: string;
+        seqEnd: string;
+        /**
+         * The §5.4 chain fields. With them the verifier recomputes `chainHash`, and every anchor must bind
+         * that chain hash — which commits to the checkpoint's range, commit time and every earlier root.
+         * Absent on exports made before anchors bound position.
+         */
+        entryCount?: number;
+        prevChainHash?: string | null;
+        chainHash?: string | null;
+        /**
+         * The §5.2 signed anchors over this checkpoint's root — the set the §5.3 quorum rule is
+         * evaluated over (§6.3). Used as quorum candidates when the caller supplies none of its own;
+         * they still verify only under keys the CALLER trusts, so a bundle cannot vouch for itself.
+         */
+        anchors?: SignedAnchor[];
+        /** Producer claim of §5.3 quorum (distinct INDEPENDENT issuers). Display only — never trusted. */
+        externallyAnchored?: boolean;
+        /** The quorum size that claim was evaluated against (§6.3). Absent on older exports. */
+        externallyAnchoredRequired?: number;
+    }[];
+}
+export interface EvidenceVerification {
+    ok: boolean;
+    total: number;
+    contentVerified: number;
+    commitmentOnly: number;
+    failed: {
+        seq: string;
+        reason: string;
+    }[];
+    /**
+     * Distinct daily roots the entries chain up to. `anchorVerified` is true only when a quorum of
+     * trusted issuers signed that root (requires anchors + policy + resolver in the options); it is
+     * null when no policy was supplied, i.e. nobody checked.
+     */
+    roots: {
+        root: string;
+        anchorRef: string | null;
+        anchorVerified: boolean | null;
+        verifiedIssuers: string[];
+        /** Authenticated external witness time per issuer, Unix seconds (see AnchorQuorumResult). */
+        witnessTimes: Record<string, number>;
+    }[];
+    /**
+     * Per-event mathematical signature checks, with explicit status and caller-key trust.
+     * WebAuthn uses committed metadata.webauthn plus caller-selected keys, origin and RP ID.
+     * No authorization/quorum is inferred; use verifyApprovalReceipt for the full approval policy.
+     * By default an invalid signature is reported without treating the ledger inclusion as invalid.
+     * requireSignatures additionally fails the bundle unless EVERY entry has a trusted signature.
+     */
+    signatures: {
+        checks?: Array<AuditSignatureCheck & {
+            seq: string;
+        }>;
+        verified: number;
+        invalid: {
+            seq: string;
+        }[];
+        notCheckable: number;
+    };
+    notes: string[];
+}
+/**
+ * Caller-fetched anchors, either flat or attributed to the checkpoint each one vouches for.
+ *
+ * The keyed form maps a checkpoint's `id` OR its `root` (as the bundle states it) to the anchors YOU
+ * fetched for that checkpoint. Attribution is what makes a DIVERGENCE verdict meaningful on a bundle
+ * spanning more than one day. An anchor's signed seq range now names its checkpoint too, and one
+ * naming a different range than the checkpoint it is keyed to is discarded as divergence evidence;
+ * attribution still decides which checkpoint a caller vouches it was fetched for.
+ */
+export type EvidenceAnchorSet = SignedAnchor[] | Record<string, SignedAnchor[]>;
+export interface EvidenceVerifyOptions {
+    signaturePolicy?: AuditSignaturePolicy;
+    requireSignatures?: boolean;
+    /**
+     * Daily roots to verify against (root hex strings). When supplied, every entry must chain to one of
+     * them. They are only as independent as their source: roots recorded earlier or taken from the
+     * published roots file are; roots copied out of this bundle are not. (An external anchor cannot
+     * supply one — Rekor stores a hash of the anchor digest and a TSA the digest, not the root.)
+     */
+    trustedRoots?: string[];
+    /**
+     * Checkpoint records YOU hold — normally the chain-verified lines of the published roots file
+     * (DEWP §5.4.1). Their roots count as trusted roots. For a bundle checkpoint over one of these roots,
+     * every field both carry must agree, or the bundle fails; and anchors are held to YOUR record's
+     * range, chain hash and claimed time rather than to the bundle's, so a producer cannot re-date a
+     * checkpoint to make a late witness look prompt (§5.3). A record's `entryCount` also bounds the
+     * proofs' leaf counts.
+     */
+    trustedCheckpoints?: TrustedCheckpoint[];
+    /**
+     * Signed anchors for the roots below, fetched by YOU from each issuer (DEWP §5.3). When omitted,
+     * quorum falls back to the anchors carried in the bundle's own `checkpoints[].anchors` — still
+     * checked under YOUR keys via `resolveAnchorKey`, but see the divergence carve-out at the quorum
+     * loop: only caller-fetched anchors can establish divergence.
+     *
+     * Prefer the `EvidenceAnchorSet` keyed form on a multi-checkpoint bundle (a date-range export
+     * routinely is one): a flat list cannot say which checkpoint each anchor was fetched for.
+     */
+    anchors?: EvidenceAnchorSet;
+    anchorPolicy?: AnchorPolicy;
+    resolveAnchorKey?: AnchorKeyResolver;
+    /** Pinned external-log keys (Rekor). Unpinned ⇒ that anchor is unverifiable ⇒ it does not count. */
+    externalKeys?: ExternalAnchorKeys;
+}
+export declare function verifyEvidenceBundle(bundle: EvidenceBundle, opts?: EvidenceVerifyOptions): EvidenceVerification;