@colophon-claims/verify 0.0.0 → 0.2.0

package/dist/manifest.js

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, } from "node:fs";
+import { isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { EvidenceNativeBundleManifestV5Schema } from "@jinn-network/benchmarking-protocol";
+import { canonicalJsonBytes } from "@jinn-network/trust-core";
+import { refuse } from "./profile/errors.js";
+export const BUNDLE_FORMAT = "benchmark-product-public-bundle/2";
+export const BUNDLE_V4_FORMAT = "benchmark-product-public-bundle/4";
+export const BUNDLE_V5_FORMAT = "benchmark-product-public-bundle/5";
+/** The anchored closure (anchor-evidence design §7.4). Additive: v2, v4, and v5 keep their check
+ * lists, byte shapes, and values; the `anchors/` member and the `integrity-anchors` check exist
+ * only here. */
+export const BUNDLE_V6_FORMAT = "benchmark-product-public-bundle/6";
+export const SUPPORTED_BUNDLE_FORMATS = [
+    BUNDLE_FORMAT,
+    BUNDLE_V4_FORMAT,
+    BUNDLE_V5_FORMAT,
+    BUNDLE_V6_FORMAT,
+];
+export const BUNDLE_MANIFEST_FILENAME = "bundle.json";
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+export const BundleManifestFileSchema = z.object({
+    path: z.string().min(1),
+    sha256: z.string().regex(SHA256_HEX),
+    bytes: z.number().int().nonnegative(),
+});
+const LegacyBundleManifestSchema = z.object({
+    format: z.union([
+        z.literal(BUNDLE_FORMAT),
+        z.literal(BUNDLE_V4_FORMAT),
+        z.literal(BUNDLE_V6_FORMAT),
+    ]),
+    files: z.array(BundleManifestFileSchema).min(1),
+});
+export const BundleManifestSchema = z.union([
+    LegacyBundleManifestSchema,
+    EvidenceNativeBundleManifestV5Schema,
+]);
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function equalBytes(left, right) {
+    return left.length === right.length && left.every((byte, index) => byte === right[index]);
+}
+function validateRelativePath(path) {
+    if (path === ""
+        || path === "."
+        || path === BUNDLE_MANIFEST_FILENAME
+        || isAbsolute(path)
+        || path.includes("\\")
+        || path.split("/").some((part) => part === "" || part === "." || part === "..")
+        || posix.normalize(path) !== path) {
+        refuse("record-integrity", "bundle.manifest.path", `unsafe or reserved bundle path "${path}"`);
+    }
+}
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function readRegularFile(bundleDir, path, allowManifest = false) {
+    if (allowManifest && path === BUNDLE_MANIFEST_FILENAME) {
+        // bundle.json is reserved from the file list but is itself authenticated by the same reader.
+    }
+    else {
+        validateRelativePath(path);
+    }
+    const absolute = join(bundleDir, ...path.split("/"));
+    let stat;
+    try {
+        stat = lstatSync(absolute);
+    }
+    catch {
+        refuse("record-integrity", path, `manifest entry "${path}" is missing`);
+    }
+    if (stat.isSymbolicLink()) {
+        refuse("record-integrity", path, `manifest entry "${path}" is a symbolic link`);
+    }
+    if (!stat.isFile()) {
+        refuse("record-integrity", path, `manifest entry "${path}" is not a regular file`);
+    }
+    if (stat.nlink !== 1) {
+        refuse("record-integrity", path, `manifest entry "${path}" must not be hard-linked`);
+    }
+    const root = realpathSync(bundleDir);
+    let resolved;
+    try {
+        resolved = realpathSync(absolute);
+    }
+    catch {
+        refuse("record-integrity", path, `manifest entry "${path}" cannot be resolved inside the bundle`);
+    }
+    if (!isInside(root, resolved)) {
+        refuse("record-integrity", path, `manifest entry "${path}" resolves outside the bundle`);
+    }
+    let fd;
+    try {
+        fd = openSync(absolute, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    }
+    catch {
+        refuse("record-integrity", path, `manifest entry "${path}" could not be opened without following links`);
+    }
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== stat.dev || opened.ino !== stat.ino) {
+            refuse("record-integrity", path, `manifest entry "${path}" changed identity while it was opened`);
+        }
+        const bytes = new Uint8Array(readFileSync(fd));
+        const after = fstatSync(fd);
+        if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size) {
+            refuse("record-integrity", path, `manifest entry "${path}" changed while it was authenticated`);
+        }
+        return bytes;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function walkTree(root, directory = root) {
+    const files = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const absolute = join(directory, entry.name);
+        const path = relative(root, absolute).split(sep).join("/");
+        const stat = lstatSync(absolute);
+        if (stat.isSymbolicLink()) {
+            refuse("record-integrity", path, `bundle contains symbolic link "${path}"`);
+        }
+        if (stat.isDirectory()) {
+            const resolvedRoot = realpathSync(root);
+            const resolvedDirectory = realpathSync(absolute);
+            if (!isInside(resolvedRoot, resolvedDirectory)) {
+                refuse("record-integrity", path, `bundle directory "${path}" resolves outside the bundle`);
+            }
+            files.push(...walkTree(root, absolute));
+        }
+        else if (stat.isFile()) {
+            files.push(path);
+        }
+        else {
+            refuse("record-integrity", path, `bundle contains non-regular entry "${path}"`);
+        }
+    }
+    return files;
+}
+export function buildBundleManifest(bundleDir, filePaths, options = {}) {
+    const seen = new Set();
+    const files = [...filePaths]
+        .map((path) => {
+        validateRelativePath(path);
+        if (seen.has(path)) {
+            refuse("record-integrity", "bundle.manifest.files", `duplicate bundle path "${path}"`);
+        }
+        seen.add(path);
+        const bytes = readRegularFile(bundleDir, path);
+        return { path, sha256: sha256(bytes), bytes: bytes.length };
+    })
+        .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    const manifest = BundleManifestSchema.parse({ format: options.format ?? BUNDLE_FORMAT, files });
+    const bytes = canonicalJsonBytes(manifest);
+    return { manifest, bytes, identity: sha256(bytes) };
+}
+export function verifyBundleManifest(bundleDir) {
+    const snapshot = verifyBundleSnapshot(bundleDir);
+    return { manifest: snapshot.manifest, bytes: snapshot.bytes, identity: snapshot.identity };
+}
+/** Authenticates the complete tree once and returns the exact immutable byte snapshot used by
+ * every semantic verifier. No consumer may reopen a pathname after this boundary. */
+export function verifyBundleSnapshot(bundleDir, deps = {}) {
+    const absoluteRoot = resolve(bundleDir);
+    let rootStat;
+    try {
+        rootStat = lstatSync(absoluteRoot);
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") {
+            refuse("record-integrity", "bundle", "bundle directory is missing");
+        }
+        throw cause;
+    }
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        refuse("record-integrity", "bundle", "bundle root must be a real directory");
+    }
+    const canonicalRoot = realpathSync(absoluteRoot);
+    const bytes = readRegularFile(canonicalRoot, BUNDLE_MANIFEST_FILENAME, true);
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        refuse("record-integrity", BUNDLE_MANIFEST_FILENAME, "bundle.json is not valid UTF-8 JSON");
+    }
+    const parsed = BundleManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        refuse("record-integrity", BUNDLE_MANIFEST_FILENAME, "bundle.json does not satisfy the manifest schema");
+    }
+    const canonical = canonicalJsonBytes(parsed.data);
+    if (!equalBytes(bytes, canonical)) {
+        refuse("record-integrity", BUNDLE_MANIFEST_FILENAME, "bundle.json bytes are not the exact canonical manifest encoding");
+    }
+    const seen = new Set();
+    let previous = "";
+    for (const entry of parsed.data.files) {
+        validateRelativePath(entry.path);
+        if (seen.has(entry.path)) {
+            refuse("record-integrity", "bundle.manifest.files", `duplicate bundle path "${entry.path}"`);
+        }
+        if (previous !== "" && entry.path <= previous) {
+            refuse("record-integrity", "bundle.manifest.files", "manifest files are not in strict path order");
+        }
+        seen.add(entry.path);
+        previous = entry.path;
+        const fileBytes = readRegularFile(canonicalRoot, entry.path);
+        if (fileBytes.length !== entry.bytes) {
+            refuse("record-integrity", entry.path, `byte length mismatch for "${entry.path}"`);
+        }
+        if (sha256(fileBytes) !== entry.sha256) {
+            refuse("record-integrity", entry.path, `digest mismatch for "${entry.path}"`);
+        }
+    }
+    const actual = new Set(walkTree(canonicalRoot));
+    const expected = new Set([BUNDLE_MANIFEST_FILENAME, ...seen]);
+    for (const path of expected) {
+        if (!actual.has(path))
+            refuse("record-integrity", path, `manifest entry "${path}" is missing`);
+    }
+    for (const path of actual) {
+        if (!expected.has(path))
+            refuse("record-integrity", path, `bundle contains unexpected file "${path}"`);
+    }
+    const fileBytes = new Map([[BUNDLE_MANIFEST_FILENAME, bytes]]);
+    for (const entry of parsed.data.files) {
+        const authenticated = readRegularFile(canonicalRoot, entry.path);
+        if (authenticated.length !== entry.bytes || sha256(authenticated) !== entry.sha256) {
+            refuse("record-integrity", entry.path, `manifest entry "${entry.path}" changed during snapshot authentication`);
+        }
+        fileBytes.set(entry.path, authenticated);
+    }
+    deps.afterManifestValidated?.();
+    return { manifest: parsed.data, bytes, identity: sha256(bytes), fileBytes };
+}

package/dist/materialize.d.ts

@@ -0,0 +1,4 @@
+/** Public bundle members required by the Colophon bundle profile. */
+export declare const PUBLIC_BUNDLE_FILES: readonly ["static-bundle.json", "benchmark.json", "run.json", "matrix.json", "report.json", "report-envelope.json", "claim-package.json", "verdicts.json", "evidence.json", "verification/assembly.jsonl", "trust/public-keys.json", "index.html", "badge.svg", "social-card.svg", "README.md", "share.txt"];
+/** V4 is the fixed v2 graph with exactly one canonical qualification projection added. */
+export declare const PUBLIC_BUNDLE_V4_FILES: readonly ("benchmark.json" | "run.json" | "matrix.json" | "report.json" | "report-envelope.json" | "claim-package.json" | "qualification.json" | "static-bundle.json" | "evidence.json" | "verdicts.json" | "verification/assembly.jsonl" | "trust/public-keys.json" | "index.html" | "badge.svg" | "social-card.svg" | "README.md" | "share.txt")[];

package/dist/materialize.js

@@ -0,0 +1,13 @@
+/** Public bundle members required by the Colophon bundle profile. */
+export const PUBLIC_BUNDLE_FILES = [
+    "static-bundle.json", "benchmark.json", "run.json", "matrix.json", "report.json",
+    "report-envelope.json", "claim-package.json", "verdicts.json", "evidence.json",
+    "verification/assembly.jsonl", "trust/public-keys.json", "index.html", "badge.svg",
+    "social-card.svg", "README.md", "share.txt",
+];
+/** V4 is the fixed v2 graph with exactly one canonical qualification projection added. */
+export const PUBLIC_BUNDLE_V4_FILES = [
+    ...PUBLIC_BUNDLE_FILES.slice(0, 7),
+    "qualification.json",
+    ...PUBLIC_BUNDLE_FILES.slice(7),
+];

package/dist/profile/admission-receipts.d.ts

@@ -0,0 +1,11 @@
+export interface LocalAdmissionReceiptFact {
+    readonly zeroReplayVariance: boolean;
+    readonly externalCapabilities: boolean;
+}
+export interface ParsedLocalAdmissionReceipt {
+    readonly sha256: string;
+    readonly taskSha256: string;
+    readonly fact: LocalAdmissionReceiptFact;
+}
+/** Parses the public, sealed prediction-snapshot admission receipt. */
+export declare function parsePredictionSnapshotAdmissionReceipt(bytes: Uint8Array, sha256?: string): ParsedLocalAdmissionReceipt | undefined;

package/dist/profile/admission-receipts.js

@@ -0,0 +1,24 @@
+import { ADMISSION_RECEIPT_MEDIA_TYPE, IN_TOTO_STATEMENT_TYPE, PREDICTION_SNAPSHOT_ADMISSION_POLICY_V1, } from "@jinn-network/task-admission";
+import { parseDsseEnvelope } from "@jinn-network/trust-core";
+/** Parses the public, sealed prediction-snapshot admission receipt. */
+export function parsePredictionSnapshotAdmissionReceipt(bytes, sha256 = "") {
+    let envelope;
+    try {
+        envelope = parseDsseEnvelope(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    if (envelope.payloadType !== ADMISSION_RECEIPT_MEDIA_TYPE)
+        return undefined;
+    try {
+        const statement = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(envelope.payloadBytes));
+        const digest = statement.predicate?.task?.documentDigest;
+        if (statement._type !== IN_TOTO_STATEMENT_TYPE || statement.predicateType !== PREDICTION_SNAPSHOT_ADMISSION_POLICY_V1.predicateType || typeof digest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(digest))
+            return undefined;
+        return { sha256, taskSha256: digest.slice("sha256:".length), fact: { zeroReplayVariance: true, externalCapabilities: false } };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/profile/anchor-claims.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The anchored-closure projection (anchor-evidence design §7.4 and §9.2): the pure function that
+ * turns a bundle's carried AnchorEvidence bytes into the claim package's `anchors` section, and
+ * the conditional honesty copy that section gates.
+ *
+ * This module is **single-sourced, not mirrored**. `@colophon-claims/core` already depends on this
+ * package (it takes `nodeCryptoAnchorPorts` and the reader instructions from here), so producer and
+ * verifier import the same function rather than two copies of it. §7.4 requires that "producer and
+ * verifier derive the section from the same bundle bytes by the same pure function, so
+ * claim-consistency remains an exact byte-compare" — one function is the strongest available form
+ * of that requirement, since two mirrored copies can drift and this one cannot.
+ *
+ * Four disciplines are load-bearing:
+ *
+ * - **Records are read only through `parseExactAnchorEvidence`, proof content only through
+ *   `decodeAnchorProofContent`.** Conformance is shape-level and admits alternate JSON spellings;
+ *   identity is byte-exactness. A record selected through the laxer door would have a digest other
+ *   than the one it is filed under.
+ * - **Subject selectors are digest-keyed.** The lock anchor is any carried anchor whose
+ *   `subject.digest` equals the digest of the bundle's exact `run.json` bytes; the matrix anchor is
+ *   any whose digest equals `matrix.json`'s. `subject.kind` is then required to equal the resolved
+ *   record's actual kind — it is checked, never used to route (§8 step 2). A digest that names no
+ *   bundle record, or a kind that misdescribes the one it names, is `invalid`: affirmative evidence
+ *   of substitution, reported louder than absence.
+ * - **Byte-embedded facts only.** `genTime`, `policyOid`, `serialNumber`,
+ *   `signerCertificateSha256` for RFC 3161; the attested block height (or `pending`) for
+ *   OpenTimestamps. Facts that need external data (block time) or lack a canonical rendering
+ *   (issuer distinguished names, accuracy intervals) never enter this section — they are
+ *   verifier-report and presentation content (§7.4).
+ * - **No trust material is supplied here.** This projection is a function of the bundle's bytes,
+ *   never of a verifier's configured roots, because the sealed claim text must be identical for
+ *   every reader (§8, "The honesty text keys on byte-facts"). Trust evaluation lives in the
+ *   `integrity-anchors` check's own report.
+ */
+import { z } from "zod";
+/** The two records this product anchors (§7.1). Both are whole sealed-record digests. */
+export type ClaimAnchorSubject = "lock" | "matrix";
+/** RFC 3161's four byte-embedded facts (§7.4). `accuracy` and the issuer DN are deliberately
+ * absent: the first has no canonical single rendering, the second is not canonically comparable
+ * across implementations. */
+export interface Rfc3161ClaimAnchorFacts {
+    readonly genTime: string;
+    readonly policyOid: string;
+    readonly serialNumber: string;
+    readonly signerCertificateSha256: string;
+}
+/** OpenTimestamps' one byte-embedded fact, or the calendar-only state. A `pending` proof carries no
+ * height because none has been attested yet — the two shapes are disjoint by construction so no
+ * reader can mistake a promise for a commitment (§13 item 5). */
+export type OpenTimestampsClaimAnchorFacts = {
+    readonly blockHeight: number;
+} | {
+    readonly pending: true;
+};
+export type ClaimAnchorFacts = Rfc3161ClaimAnchorFacts | OpenTimestampsClaimAnchorFacts;
+export interface ClaimAnchor {
+    readonly subject: ClaimAnchorSubject;
+    /** The resolved record's actual kind IRI — checked against `subject.kind`, never taken from it. */
+    readonly kind: string;
+    readonly provider: string;
+    readonly recordSha256: string;
+    /** Present only on the §6.2 upgraded form of a pending proof — see `upgradeEdge` below. */
+    readonly upgradesRecordSha256?: string;
+    readonly facts: ClaimAnchorFacts;
+}
+export interface CarriedAnchorRecord {
+    readonly recordSha256: string;
+    readonly bytes: Uint8Array;
+}
+export declare const ClaimAnchorSchema: z.ZodObject<{
+    subject: z.ZodEnum<{
+        lock: "lock";
+        matrix: "matrix";
+    }>;
+    kind: z.ZodString;
+    provider: z.ZodString;
+    recordSha256: z.ZodString;
+    upgradesRecordSha256: z.ZodOptional<z.ZodString>;
+    facts: z.ZodUnion<readonly [z.ZodObject<{
+        genTime: z.ZodString;
+        policyOid: z.ZodString;
+        serialNumber: z.ZodString;
+        signerCertificateSha256: z.ZodString;
+    }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+        blockHeight: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        pending: z.ZodLiteral<true>;
+    }, z.core.$strict>]>]>;
+}, z.core.$strict>;
+export interface DeriveClaimAnchorsInput {
+    readonly records: readonly CarriedAnchorRecord[];
+    /** sha256 hex of the bundle's exact `run.json` bytes. */
+    readonly runSha256: string;
+    /** sha256 hex of the bundle's exact `matrix.json` bytes. */
+    readonly matrixSha256: string;
+}
+/** A record this projection refuses. Every caller converts it into its own typed refusal
+ * (`record-integrity` on the producer side, an `invalid` anchor outcome on the verifier side), so
+ * the failure is never swallowed and never crosses a package boundary as an untyped throw. */
+export declare class ClaimAnchorProjectionError extends Error {
+    readonly name = "ClaimAnchorProjectionError";
+    readonly recordSha256: string;
+    constructor(recordSha256: string, message: string);
+}
+/**
+ * Projects the carried AnchorEvidence records into the claim package's `anchors` section.
+ *
+ * Ordered by record digest so the section has exactly one spelling for one carried set. Throws
+ * `ClaimAnchorProjectionError` on a record that is not exactly-sealed, does not parse, names a
+ * digest no bundle record has, misdescribes the kind of the record it does name, carries a provider
+ * profile no verifier implements, or carries a proof the rules reject.
+ */
+export declare function deriveClaimAnchors(input: DeriveClaimAnchorsInput): readonly ClaimAnchor[];
+/** The historical value every unanchored bundle keeps (§9.2, "Additive"). */
+export declare const STRUCTURAL_PRE_REGISTRATION: "structural-and-append-order-only";
+/** The widened value an anchored bundle carries. */
+export declare const ANCHORED_PRE_REGISTRATION: "structural-append-order-and-anchored-time";
+export declare const SELF_RUN_TRUST_ROOT = "Signatures verify against the bundle-carried public keys minted by this workspace; there is no third-party trust anchor on the self-run venue.";
+export declare const ANCHORED_TRUST_ROOT: string;
+/**
+ * A lock anchor gates copy only when it is carried, structurally complete for its class, and
+ * digest- and kind-matching (§9.2). The first and last are guaranteed by `deriveClaimAnchors`,
+ * which refuses everything else; completeness is the one condition readable off the section: a
+ * `pending`-only proof is not structurally complete and gates nothing.
+ */
+export declare function governingLockAnchors(anchors: readonly ClaimAnchor[]): readonly ClaimAnchor[];
+/** Complete matrix anchors, in record-digest order. A matrix anchor upgrades nothing (§9.2). */
+export declare function carriedMatrixAnchors(anchors: readonly ClaimAnchor[]): readonly ClaimAnchor[];
+/**
+ * The replacement for limitation sentence 2, rendered once from the governing anchor.
+ *
+ * The `authority-time` form asserts, because its cryptography is fully carried and the verifier
+ * re-verifies it unconditionally and fails loud on `invalid`. The `chain-time` form is attributive
+ * — it says what the proof asserts and what checking it requires — because structural completeness
+ * is not chain evaluation; the assertive chain-time statement lives only in the report of a
+ * verifier that evaluated headers (§8, §9.2).
+ */
+export declare function anchoredPreRegistrationSentence(governing: ClaimAnchor): string;
+/** One neutral line per additional lock anchor (§9.2). It upgrades nothing; it reports. */
+export declare function additionalLockAnchorLine(anchor: ClaimAnchor): string;
+/** One neutral line per carried matrix anchor (§9.2). It upgrades no claim. */
+export declare function matrixAnchorLine(anchor: ClaimAnchor): string;
+/**
+ * The complete venue-limits list for one anchor section: the unconditional list with sentence 2
+ * replaced by the governing anchor's form, followed by the neutral lines. Sentences 1, 3/3', 4, and
+ * 5 are untouched — anchors have nothing to say about operator control, pinning axes, self-reported
+ * cost, or agent distinctness (§9.2).
+ *
+ * With no governing lock anchor the unconditional list is returned unchanged, including when the
+ * bundle carries only pending or only matrix anchors: absent, pending, or invalid anchors change
+ * nothing.
+ */
+export declare function anchoredVenueLimits(unconditional: readonly string[], anchors: readonly ClaimAnchor[]): readonly string[];
+/** `venueHonesty.preRegistration` for one anchor section (§9.2). */
+export declare function anchoredPreRegistration(anchors: readonly ClaimAnchor[]): typeof STRUCTURAL_PRE_REGISTRATION | typeof ANCHORED_PRE_REGISTRATION;
+/** `claim.verification.trustRoot` for one anchor section (§9.2). */
+export declare function anchoredTrustRoot(anchors: readonly ClaimAnchor[]): string;