@mikeargento/bitgraph-audit 0.1.0

package/dist/cli.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+/**
+ * bitgraph-audit CLI: run the full offline audit pipeline over a bundle
+ * and write audit-report.json and/or audit-report.md.
+ *
+ * Report content goes to files only; stdout carries a short completion
+ * line naming the written files and the exit meaning. The CLI performs
+ * no network access. Arguments are parsed with plain process.argv
+ * handling, no dependency.
+ *
+ * Exit codes are bit flags (documented in --help and on the ExitFlags
+ * type): 0 clean, 1 verification failures (including unsupported-version
+ * rejections), 2 chain or authority anomalies, divergences between valid
+ * proofs, or anchor witness verification failures, 3 both, 64 usage or
+ * input error (no report was produced).
+ */
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { auditToolVersion, computeExitFlags, runAudit } from "./audit.js";
+import { buildJsonReport } from "./report-json.js";
+import { buildMarkdownReport } from "./report-md.js";
+const USAGE_EXIT_CODE = 64;
+/** The 14 fields of the canonical VerificationPolicy (verify package, G7). */
+const KNOWN_POLICY_FIELDS = [
+    "requireEnforcement",
+    "allowedMeasurements",
+    "allowedPublicKeys",
+    "requireAttestation",
+    "requireAttestationFormat",
+    "minCounter",
+    "maxCounter",
+    "minTime",
+    "maxTime",
+    "requireEpochId",
+    "requireActor",
+    "allowedActorKeyIds",
+    "allowedActorProviders",
+    "requireSlot",
+];
+class UsageError extends Error {
+}
+const USAGE_LINE = "Usage: bitgraph-audit <path-to-bundle> [--out <dir>] [--format json,md] [--trust-policy <path>]";
+function helpText() {
+    return [
+        `bitgraph-audit ${auditToolVersion()}: offline audit of BitGraph proof bundles.`,
+        "",
+        USAGE_LINE,
+        "",
+        "The bundle may be a directory, a .tar archive, or a .tar.gz/.tgz",
+        "archive. The audit runs entirely offline: no RPC, no HTTP, no DNS.",
+        "",
+        "Options:",
+        "  --out <dir>            Directory to write the report files into",
+        "                         (default: current directory; created if missing).",
+        "  --format <list>        Comma-separated formats to write: json, md",
+        "                         (default: json,md). json writes audit-report.json;",
+        "                         md writes audit-report.md.",
+        "  --trust-policy <path>  JSON file parsed as the canonical",
+        "                         VerificationPolicy and applied at both",
+        "                         verification tiers. Valid fields:",
+        `                         ${KNOWN_POLICY_FIELDS.join(", ")}.`,
+        "                         Any other field is an error.",
+        "  --help, -h             Print this help and exit 0.",
+        "",
+        "Exit codes (bit flags):",
+        "  0   Clean: no verification failures, no chain anomalies, no",
+        "      divergences.",
+        "  1   Verification failures: at least one proof failed its canonical",
+        "      cryptographic checks at either tier, or at least one",
+        "      proof-shaped input was rejected as an unsupported version",
+        "      (only bitgraph/1 is supported). A proof whose artifact bytes",
+        "      are absent from the bundle is NOT a failure by itself: its",
+        "      bytes-free checks decide, unless a supplied trust policy makes",
+        "      them fail (for example requireSlot), in which case it counts",
+        "      here.",
+        "  2   Chain or authority anomalies, divergences between valid proofs,",
+        "      or anchor witness verification failures: unexplained counter",
+        "      positions, chain breaks, collisions, cross-kind position reuse,",
+        "      forks, authority changes inside an epoch, epoch link anomalies,",
+        "      or a supplied anchor witness that fails its offline verification",
+        "      (block-hash mismatch, digest binding, block number, header or",
+        "      RLP malformation, an invalid candidate anchor, or an unmatched",
+        "      witness). Benign findings are reported but never set exit bits:",
+        "      duplicate copies, manifest advisories, unsafe paths, embedded",
+        "      proofHash mismatches, and informational anchor findings (unsigned",
+        "      metadata disagreements, metadata-only anchor claims, and",
+        "      unparseable anchor titles, all overridden by the signed body).",
+        "  3   Both 1 and 2.",
+        "  64  Usage or input error: unknown option, unreadable bundle, or",
+        "      invalid trust policy. No report was produced.",
+        "",
+        "Attestation validation results are always reported in full but never",
+        "change the exit code on their own: an invalid attestation document on",
+        "an otherwise verified proof is reported without affecting the exit",
+        "code, and counts under exit bit 1 only when a supplied trust policy",
+        "made verification itself fail.",
+    ].join("\n");
+}
+function parseArgs(argv) {
+    let bundlePath;
+    let outDir = ".";
+    let formats = new Set(["json", "md"]);
+    let trustPolicyPath;
+    const takeValue = (flag, index) => {
+        const value = argv[index + 1];
+        if (value === undefined)
+            throw new UsageError(`${flag} requires a value.`);
+        return value;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h")
+            return "help";
+        if (arg === "--out") {
+            outDir = takeValue(arg, i);
+            i++;
+        }
+        else if (arg === "--format") {
+            const raw = takeValue(arg, i);
+            i++;
+            const parts = raw
+                .split(",")
+                .map((p) => p.trim())
+                .filter((p) => p.length > 0);
+            if (parts.length === 0)
+                throw new UsageError("--format requires at least one of: json, md.");
+            formats = new Set();
+            for (const part of parts) {
+                if (part !== "json" && part !== "md") {
+                    throw new UsageError(`unknown format "${part}". Valid formats: json, md.`);
+                }
+                formats.add(part);
+            }
+        }
+        else if (arg === "--trust-policy") {
+            trustPolicyPath = takeValue(arg, i);
+            i++;
+        }
+        else if (arg.startsWith("-")) {
+            throw new UsageError(`unknown option "${arg}".`);
+        }
+        else if (bundlePath === undefined) {
+            bundlePath = arg;
+        }
+        else {
+            throw new UsageError("more than one bundle path was given.");
+        }
+    }
+    if (bundlePath === undefined)
+        throw new UsageError("missing bundle path.");
+    return {
+        bundlePath,
+        outDir,
+        formats,
+        ...(trustPolicyPath !== undefined ? { trustPolicyPath } : {}),
+    };
+}
+function loadTrustPolicy(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new UsageError(`cannot read trust policy file "${path}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError(`trust policy file "${path}" is not valid JSON.`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new UsageError("trust policy must be a JSON object.");
+    }
+    const unknown = Object.keys(parsed).filter((key) => !KNOWN_POLICY_FIELDS.includes(key));
+    if (unknown.length > 0) {
+        throw new UsageError(`unknown trust policy ${unknown.length === 1 ? "field" : "fields"}: ` +
+            `${unknown.join(", ")}. Valid fields: ${KNOWN_POLICY_FIELDS.join(", ")}.`);
+    }
+    return parsed;
+}
+function exitMeaning(flags) {
+    if (flags.code === 0)
+        return "clean: no verification failures, no chain anomalies, no divergences";
+    const parts = [];
+    if (flags.verificationFailures)
+        parts.push("verification failures");
+    if (flags.chainAnomaliesOrDivergences) {
+        parts.push("chain anomalies, divergences, or anchor witness verification failures");
+    }
+    return parts.join("; ");
+}
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`bitgraph-audit: ${err.message}\n${USAGE_LINE}\nSee --help for details.\n`);
+            return USAGE_EXIT_CODE;
+        }
+        throw err;
+    }
+    if (parsed === "help") {
+        process.stdout.write(helpText() + "\n");
+        return 0;
+    }
+    let trustAnchors;
+    try {
+        if (parsed.trustPolicyPath !== undefined) {
+            trustAnchors = loadTrustPolicy(parsed.trustPolicyPath);
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`bitgraph-audit: ${err.message}\n${USAGE_LINE}\nSee --help for details.\n`);
+            return USAGE_EXIT_CODE;
+        }
+        throw err;
+    }
+    let result;
+    try {
+        result = await runAudit(parsed.bundlePath, trustAnchors !== undefined ? { trustAnchors } : undefined);
+    }
+    catch (err) {
+        process.stderr.write(`bitgraph-audit: cannot audit "${parsed.bundlePath}": ` +
+            `${err instanceof Error ? err.message : String(err)}\n`);
+        return USAGE_EXIT_CODE;
+    }
+    await mkdir(parsed.outDir, { recursive: true });
+    const written = [];
+    if (parsed.formats.has("json")) {
+        const path = join(parsed.outDir, "audit-report.json");
+        await writeFile(path, JSON.stringify(buildJsonReport(result), null, 2) + "\n", "utf8");
+        written.push(path);
+    }
+    if (parsed.formats.has("md")) {
+        const path = join(parsed.outDir, "audit-report.md");
+        await writeFile(path, buildMarkdownReport(result), "utf8");
+        written.push(path);
+    }
+    const flags = computeExitFlags(result);
+    process.stdout.write(`bitgraph-audit ${auditToolVersion()}: wrote ${written.join(", ")}\n` +
+        `exit ${flags.code}: ${exitMeaning(flags)}\n`);
+    return flags.code;
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`bitgraph-audit: unexpected error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exitCode = USAGE_EXIT_CODE;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/contents-hash.d.ts

@@ -0,0 +1,30 @@
+/** An in-memory bundle entry for one-shot hashing (producers, tests). */
+export interface ContentsHashEntry {
+    /** Bundle-root-relative path: "/" separators, no leading "/" or "./". */
+    path: string;
+    /** Raw content bytes exactly as stored. */
+    content: Uint8Array;
+}
+/** A precomputed per-entry digest, for streaming consumers that hashed content incrementally. */
+export interface ContentsHashEntryDigest {
+    path: string;
+    /** SHA-256(UTF-8(path) || 0x00 || content), 32 bytes. */
+    entryDigest: Uint8Array;
+}
+/**
+ * Compute the per-entry digest e = SHA-256(UTF-8(path) || 0x00 || content).
+ */
+export declare function computeEntryDigest(path: string, content: Uint8Array): Uint8Array;
+/**
+ * One-shot contents hash over an in-memory entry set.
+ *
+ * @throws {TypeError} if any path contains a NUL byte.
+ */
+export declare function computeContentsHashB64(entries: Iterable<ContentsHashEntry>): string;
+/**
+ * Combine precomputed per-entry digests into the final contents hash:
+ * sort by raw UTF-8 path bytes, concatenate the 32-byte digests, SHA-256,
+ * base64-standard encode.
+ */
+export declare function combineEntryDigests(entries: Iterable<ContentsHashEntryDigest>): string;
+//# sourceMappingURL=contents-hash.d.ts.map

package/dist/contents-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contents-hash.d.ts","sourceRoot":"","sources":["../src/contents-hash.ts"],"names":[],"mappings":"AAsBA,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,iGAAiG;AACjG,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,WAAW,EAAE,UAAU,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,UAAU,CAMhF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,MAAM,CAMnF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,uBAAuB,CAAC,GAAG,MAAM,CAYtF"}

package/dist/contents-hash.js

@@ -0,0 +1,73 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+/**
+ * Deterministic bundle contents hash, per docs/BUNDLE-FORMAT.md section 8.
+ *
+ * The hash is a file-level fixity value with no interpretation of any file:
+ *
+ *   1. Per entry: e = SHA-256(UTF-8(path) || 0x00 || contentBytes).
+ *      Paths cannot contain NUL, so the separator is unambiguous.
+ *   2. Sort entries by raw UTF-8 path bytes (unsigned byte-wise comparison,
+ *      no locale, no Unicode normalization).
+ *   3. contentsHashB64 = base64(SHA-256(concatenated 32-byte entry digests)).
+ *
+ * The hashed set is every bundle entry except the root manifest.json
+ * itself (which cannot cover its own hash). That exclusion is applied by
+ * callers; this module hashes exactly what it is given.
+ */
+import { sha256 } from "@noble/hashes/sha256";
+const NUL = new Uint8Array([0]);
+/**
+ * Compute the per-entry digest e = SHA-256(UTF-8(path) || 0x00 || content).
+ */
+export function computeEntryDigest(path, content) {
+    const hasher = sha256.create();
+    hasher.update(encodePath(path));
+    hasher.update(NUL);
+    hasher.update(content);
+    return hasher.digest();
+}
+/**
+ * One-shot contents hash over an in-memory entry set.
+ *
+ * @throws {TypeError} if any path contains a NUL byte.
+ */
+export function computeContentsHashB64(entries) {
+    const digests = [];
+    for (const entry of entries) {
+        digests.push({ path: entry.path, entryDigest: computeEntryDigest(entry.path, entry.content) });
+    }
+    return combineEntryDigests(digests);
+}
+/**
+ * Combine precomputed per-entry digests into the final contents hash:
+ * sort by raw UTF-8 path bytes, concatenate the 32-byte digests, SHA-256,
+ * base64-standard encode.
+ */
+export function combineEntryDigests(entries) {
+    const withPathBytes = Array.from(entries, (entry) => ({
+        pathBytes: encodePath(entry.path),
+        entryDigest: entry.entryDigest,
+    }));
+    withPathBytes.sort((a, b) => compareBytes(a.pathBytes, b.pathBytes));
+    const outer = sha256.create();
+    for (const entry of withPathBytes) {
+        outer.update(entry.entryDigest);
+    }
+    return Buffer.from(outer.digest()).toString("base64");
+}
+function encodePath(path) {
+    if (path.includes("\0")) {
+        throw new TypeError("bitgraph-audit: bundle entry paths must not contain NUL bytes");
+    }
+    return new TextEncoder().encode(path);
+}
+function compareBytes(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const d = a[i] - b[i];
+        if (d !== 0)
+            return d;
+    }
+    return a.length - b.length;
+}
+//# sourceMappingURL=contents-hash.js.map

package/dist/contents-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contents-hash.js","sourceRoot":"","sources":["../src/contents-hash.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAiBhC;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAmB;IAClE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;IAC/B,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IAChC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAoC;IACzE,MAAM,OAAO,GAA8B,EAAE,CAAC;IAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,kBAAkB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA0C;IAC5E,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACpD,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;QACjC,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC,CAAC,CAAC;IACJ,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAErE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,+DAA+D,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,YAAY,CAAC,CAAa,EAAE,CAAa;IAChD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;AAC7B,CAAC"}

package/dist/export.d.ts

@@ -0,0 +1,64 @@
+/** One member proof to include. */
+export interface BundleArchiveProofEntry {
+    /** The proof object (wire form or stored form). Must be version "bitgraph/1". */
+    proof: Record<string, unknown>;
+    /**
+     * The stored proofHash to append as a trailing field (ledger stored form).
+     * Must equal the computed canonical proof hash; a mismatch throws, because
+     * shipping it would produce a proofhash-mismatch finding in every audit.
+     * Omit to serialize the proof object as given.
+     */
+    storedProofHash?: string;
+}
+/** One anchor witness file to include (spec section 10.2). */
+export interface BundleArchiveWitnessEntry {
+    /** Bundle-root-relative path, e.g. "witnesses/123456.json" per the advisory layout. */
+    path: string;
+    /** The witness object, serialized verbatim as compact JSON. */
+    witness: Record<string, unknown>;
+}
+/** Original artifact bytes to include. */
+export interface BundleArchiveArtifactFile {
+    /** File name (may contain subdirectories); placed under "artifacts/". Advisory, never load-bearing. */
+    name: string;
+    bytes: Uint8Array;
+}
+export interface BundleArchiveInput {
+    /** Member proofs, placed under proofs/ per the advisory layout. */
+    proofs: BundleArchiveProofEntry[];
+    /**
+     * Anchor proofs, placed under anchors/ per the advisory layout. They are
+     * ordinary bitgraph/1 members; the separate group only controls placement.
+     * A proof must appear in exactly one group (duplicates throw).
+     */
+    anchors?: BundleArchiveProofEntry[];
+    witnesses?: BundleArchiveWitnessEntry[];
+    artifactFiles?: BundleArchiveArtifactFile[];
+    /** Advisory manifest field: distinct commit.epochId values, raw base64 form. */
+    epochIds: string[];
+    /** Advisory manifest field: distinct chain ids ("global" for the default chain). */
+    chainIds: string[];
+    /** Advisory manifest field: open-epoch snapshot declaration. Emitted only when non-empty. */
+    openEpochs?: Array<{
+        epochId: string;
+        counterAtSnapshot: string;
+    }>;
+    /**
+     * Advisory manifest field: ISO 8601 UTC generation time, supplied BY THE
+     * CALLER. This function never reads the clock, so the same input always
+     * produces the same archive.
+     */
+    generatedAt?: string;
+}
+/**
+ * Assemble a spec-conformant bitgraph-bundle/1 .tar.gz archive.
+ *
+ * @returns the gzipped tar bytes.
+ * @throws {TypeError} on producer-conformance violations: a proof whose
+ *   version is not exactly "bitgraph/1", a storedProofHash that does not
+ *   match the computed canonical hash, duplicate canonical proof identities,
+ *   unsafe or colliding entry paths, or a witness placed at the reserved
+ *   root manifest.json path.
+ */
+export declare function buildBundleArchive(input: BundleArchiveInput): Uint8Array;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAkCA,mCAAmC;AACnC,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,8DAA8D;AAC9D,MAAM,WAAW,yBAAyB;IACxC,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACpC,SAAS,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACxC,aAAa,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAC5C,gFAAgF;IAChF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oFAAoF;IACpF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU,CAyIxE"}

package/dist/export.js

@@ -0,0 +1,192 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+/**
+ * Bundle archive builder: the producer counterpart of ingest.
+ *
+ * buildBundleArchive() assembles a spec-conformant bitgraph-bundle/1
+ * .tar.gz archive (docs/BUNDLE-FORMAT.md) from in-memory proofs, anchor
+ * proofs, anchor witnesses, and optional artifact bytes. This is generic,
+ * read-side-safe bundle assembly: it never talks to a ledger, never reads
+ * the clock (the advisory generatedAt string is passed in by the caller),
+ * and never touches the network.
+ *
+ * Deterministic by construction: entries are written in raw-UTF-8-path-byte
+ * order, tar header metadata is fixed (mtime 0, mode 0644, uid/gid 0), and
+ * the manifest is serialized with a fixed field order. The same input
+ * produces a byte-identical archive on the same runtime (the gzip layer's
+ * bytes are fixed by zlib for a given input, so cross-runtime identity
+ * additionally assumes the same zlib).
+ *
+ * Producer conformance (spec section 12.1) is enforced, not advised:
+ * non-bitgraph/1 proofs, duplicate canonical identities, unsafe paths, and
+ * a storedProofHash that disagrees with the computed canonical hash all
+ * throw instead of producing a bundle that would audit dirty.
+ */
+import { gzipSync } from "node:zlib";
+import { computeProofHash } from "@mikeargento/bitgraph-verify";
+import { computeContentsHashB64 } from "./contents-hash.js";
+import { writeTarArchive } from "./tar.js";
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+/**
+ * Assemble a spec-conformant bitgraph-bundle/1 .tar.gz archive.
+ *
+ * @returns the gzipped tar bytes.
+ * @throws {TypeError} on producer-conformance violations: a proof whose
+ *   version is not exactly "bitgraph/1", a storedProofHash that does not
+ *   match the computed canonical hash, duplicate canonical proof identities,
+ *   unsafe or colliding entry paths, or a witness placed at the reserved
+ *   root manifest.json path.
+ */
+export function buildBundleArchive(input) {
+    const entries = [];
+    const usedPaths = new Set();
+    const seenProofHashes = new Set();
+    const partitions = new Map();
+    const addEntry = (path, content) => {
+        assertSafePath(path);
+        if (path === "manifest.json") {
+            throw new TypeError('bitgraph-audit: "manifest.json" is the reserved root manifest path; entries may not claim it');
+        }
+        if (usedPaths.has(path)) {
+            throw new TypeError(`bitgraph-audit: duplicate bundle entry path "${path}"`);
+        }
+        usedPaths.add(path);
+        entries.push({ path, content });
+    };
+    const addProofGroup = (group, prefix) => {
+        for (const entry of group) {
+            const proof = entry.proof;
+            if (proof["version"] !== "bitgraph/1") {
+                throw new TypeError(`bitgraph-audit: only bitgraph/1 proofs are bundle members; got version ${JSON.stringify(proof["version"])}`);
+            }
+            const canonicalHash = computeProofHash(proof);
+            if (entry.storedProofHash !== undefined && entry.storedProofHash !== canonicalHash) {
+                throw new TypeError("bitgraph-audit: storedProofHash does not match the computed canonical proof hash; " +
+                    "refusing to produce a bundle that would carry a proofhash-mismatch finding");
+            }
+            if (seenProofHashes.has(canonicalHash)) {
+                throw new TypeError(`bitgraph-audit: duplicate proof (canonical hash ${canonicalHash}); ` +
+                    "each member must appear exactly once or the bundle audits with duplicate findings");
+            }
+            seenProofHashes.add(canonicalHash);
+            const commit = isPlainObject(proof["commit"]) ? proof["commit"] : {};
+            const epochId = typeof commit["epochId"] === "string" && commit["epochId"].length > 0
+                ? commit["epochId"]
+                : undefined;
+            const counter = typeof commit["counter"] === "string" && commit["counter"].length > 0
+                ? commit["counter"]
+                : undefined;
+            const chainId = typeof commit["chainId"] === "string" && commit["chainId"].length > 0
+                ? commit["chainId"]
+                : "global";
+            const path = epochId !== undefined && counter !== undefined
+                ? `${prefix}/${toSafeId(epochId)}/${counter.padStart(12, "0")}-${toSafeId(canonicalHash)}.json`
+                : `${prefix}/unpositioned/${toSafeId(canonicalHash)}.json`;
+            const body = entry.storedProofHash !== undefined
+                ? { ...proof, proofHash: entry.storedProofHash }
+                : proof;
+            addEntry(path, utf8(JSON.stringify(body)));
+            if (epochId !== undefined && counter !== undefined) {
+                let value;
+                try {
+                    value = BigInt(counter);
+                }
+                catch {
+                    value = undefined;
+                }
+                if (value !== undefined && value >= 0n) {
+                    const key = `${epochId}\u0000${chainId}`;
+                    const existing = partitions.get(key);
+                    if (existing === undefined) {
+                        partitions.set(key, { epochId, chainId, min: value, max: value });
+                    }
+                    else {
+                        if (value < existing.min)
+                            existing.min = value;
+                        if (value > existing.max)
+                            existing.max = value;
+                    }
+                }
+            }
+        }
+    };
+    addProofGroup(input.proofs, "proofs");
+    addProofGroup(input.anchors ?? [], "anchors");
+    for (const witness of input.witnesses ?? []) {
+        addEntry(witness.path, utf8(JSON.stringify(witness.witness)));
+    }
+    for (const artifact of input.artifactFiles ?? []) {
+        if (artifact.name.length === 0) {
+            throw new TypeError("bitgraph-audit: artifact file names must be non-empty");
+        }
+        addEntry(`artifacts/${artifact.name}`, artifact.bytes);
+    }
+    // Contents hash over every entry except the manifest itself (spec section 8).
+    const contentsHashB64 = computeContentsHashB64(entries);
+    // Manifest with a fixed field order (spec section 7.1). Compact JSON.
+    const counterRanges = Array.from(partitions.values())
+        .sort((a, b) => a.epochId < b.epochId ? -1 : a.epochId > b.epochId ? 1 : a.chainId < b.chainId ? -1 : a.chainId > b.chainId ? 1 : 0)
+        .map((p) => ({ epochId: p.epochId, chainId: p.chainId, min: p.min.toString(), max: p.max.toString() }));
+    const manifest = { version: "bitgraph-bundle/1" };
+    manifest["epochIds"] = input.epochIds;
+    manifest["chainIds"] = input.chainIds;
+    manifest["proofCount"] = seenProofHashes.size;
+    manifest["counterRanges"] = counterRanges;
+    if (input.generatedAt !== undefined)
+        manifest["generatedAt"] = input.generatedAt;
+    manifest["contentsHashB64"] = contentsHashB64;
+    manifest["artifactsIncluded"] = (input.artifactFiles?.length ?? 0) > 0;
+    if (input.openEpochs !== undefined && input.openEpochs.length > 0) {
+        manifest["openEpochs"] = input.openEpochs;
+    }
+    const manifestPath = "manifest.json";
+    assertSafePath(manifestPath);
+    entries.push({ path: manifestPath, content: utf8(JSON.stringify(manifest)) });
+    // Fixed entry ordering: raw UTF-8 path bytes, unsigned byte-wise.
+    const sorted = entries
+        .map((entry) => ({ entry, pathBytes: utf8(entry.path) }))
+        .sort((a, b) => compareBytes(a.pathBytes, b.pathBytes))
+        .map(({ entry }) => ({ path: entry.path, content: entry.content }));
+    const tarBytes = writeTarArchive(sorted);
+    const gz = gzipSync(tarBytes, { level: 9 });
+    return new Uint8Array(gz.buffer, gz.byteOffset, gz.byteLength);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Path-safe transform for base64 values in file names (spec section 9). */
+function toSafeId(b64) {
+    return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Spec section 4.1: relative, no NUL, no "..", no leading "/" or "./", no empty segments. */
+function assertSafePath(path) {
+    if (path.length === 0)
+        throw new TypeError("bitgraph-audit: bundle entry paths must be non-empty");
+    if (path.includes("\0"))
+        throw new TypeError("bitgraph-audit: bundle entry paths must not contain NUL bytes");
+    if (path.startsWith("/"))
+        throw new TypeError(`bitgraph-audit: bundle entry path "${path}" must be relative`);
+    const segments = path.split("/");
+    for (const segment of segments) {
+        if (segment === "" || segment === "." || segment === "..") {
+            throw new TypeError(`bitgraph-audit: bundle entry path "${path}" contains an unsafe component`);
+        }
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function utf8(text) {
+    return new TextEncoder().encode(text);
+}
+function compareBytes(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const d = a[i] - b[i];
+        if (d !== 0)
+            return d;
+    }
+    return a.length - b.length;
+}
+//# sourceMappingURL=export.js.map