@mikeargento/bitgraph-player 0.3.0 → 0.5.0

package/dist/check.d.ts

@@ -0,0 +1,156 @@
+/**
+ * `check`: what a bundle establishes about the recordings it holds, said
+ * plainly, offline, in the Player's three values.
+ *
+ * This is a SPEC section 8 convenience: a distinct subcommand that never
+ * touches evaluation semantics. It asks no rule-author question ("was A
+ * before B"); it asks the reader's question ("is this recording sound, and
+ * what bounds it"), over the audit pipeline's canonical interpretation of
+ * the bundle, and answers per line with TRUE, FALSE, or UNDETERMINED.
+ *
+ * The vocabulary, and the line it lives or dies on:
+ *
+ *   TRUE          evidence in hand establishes the property.
+ *   FALSE         evidence in hand CONTRADICTS the property: bytes that do
+ *                 not hash to the digest they sit beside, a signature that
+ *                 fails, an attestation whose user_data is not this proof, a
+ *                 block header that does not hash to its anchor's block hash,
+ *                 two recordings that cannot both be right.
+ *   UNDETERMINED  the evidence does not decide. Missing bytes, a missing
+ *                 witness, an environment that cannot run a check, a
+ *                 measurement this verifier does not know. Absence is never
+ *                 a verdict, and this command never degrades a failed or
+ *                 missing check into a FALSE (project rule: a failed read is
+ *                 never a verdict).
+ *
+ * The overall result is the strong-Kleene `all` over every line the report
+ * emits: each recording's lines, each anchor's lines, and each structural
+ * contradiction. Ethereum BOUNDS are reported descriptively per recording
+ * and never enter the conjunction: a bundle without an anchor has an
+ * unbounded recording, not an unsound one. A witness that is PRESENT and
+ * fails is a contradiction and does enter.
+ *
+ * Excerpt honesty. A single export is an excerpt of a chain: its recording
+ * links to a predecessor that is not in the bundle, and the counter
+ * positions between its anchors are absent. The audit reports those as
+ * anomalies because it is built to audit whole epochs; here they are
+ * expected and are reported as notes, never as verdicts. Real
+ * contradictions (collisions, forks, malformed links, signer changes)
+ * still surface as FALSE.
+ *
+ * Enclave identity. An attestation proves that SOME AWS Nitro enclave
+ * running code with the attested PCR0 signed this proof's key. Whether
+ * that PCR0 is a published BitGraph enclave measurement is a fact this
+ * verifier carries as DECLARED knowledge (KNOWN_ENCLAVE_MEASUREMENTS, from
+ * server/commit-service/reproducible-build/PINS.md). A measurement outside
+ * that list is UNDETERMINED, never FALSE: it is beyond what this build of
+ * the verifier knows, which is exactly how an offline verifier should age.
+ *
+ * Determinism. The report contains no wall-clock time, no machine path, and
+ * no run-local value; bundle-relative entry paths are bundle content and
+ * are allowed. Same bundle bytes, same report bytes.
+ */
+import type { AuditResult, IngestResult } from "@mikeargento/bitgraph-audit";
+import type { ThreeValued } from "./types.js";
+/**
+ * Published BitGraph enclave PCR0 measurements, per PINS.md, oldest first.
+ * Each remains correct for proofs minted during its own period; a proof
+ * carries its own measurement, so nothing here needs to be "current" for
+ * an old proof to check. Lowercase hex, exactly as attestations report.
+ */
+export declare const KNOWN_ENCLAVE_MEASUREMENTS: ReadonlyArray<{
+    pcr0: string;
+    label: string;
+    period: string;
+}>;
+/** One checked property, three-valued, with a plain-language reason. */
+export interface CheckLine {
+    name: "file" | "signature" | "attestation" | "enclave" | "witness" | "contradiction";
+    result: ThreeValued;
+    detail: string;
+}
+/** A verified Ethereum bound on a recording, from a witness in the bundle. */
+export interface CheckBound {
+    blockNumber?: string;
+    blockHash: string;
+    /** Unix seconds from the verified block header. */
+    timestamp: number;
+    anchorProofHash: string;
+    evidence: "chain-link" | "counter-order";
+    weaker: boolean;
+}
+export interface CheckBounds {
+    status: "bracketed" | "lower-bounded" | "upper-bounded" | "unanchored";
+    notBefore?: CheckBound;
+    notAfter?: CheckBound;
+    detail: string;
+}
+/** A non-anchor recording in the bundle. */
+export interface CheckRecording {
+    proofHash: string;
+    digestB64: string;
+    epochId?: string;
+    chainId: string;
+    counter?: string;
+    slotCounter?: string;
+    publicKeyB64?: string;
+    /** Bundle-relative path of the matched artifact, when its bytes were present. */
+    filePath?: string;
+    lines: CheckLine[];
+    /** Kleene all over `lines`. */
+    result: ThreeValued;
+    bounds: CheckBounds;
+}
+/** An Ethereum anchor recording in the bundle. */
+export interface CheckAnchor {
+    proofHash: string;
+    epochId?: string;
+    chainId: string;
+    counter?: string;
+    blockNumber?: string;
+    blockHash?: string;
+    /** Bundle-relative path of the witness file, when one matched this anchor. */
+    witnessPath?: string;
+    lines: CheckLine[];
+    result: ThreeValued;
+}
+export interface CheckReport {
+    check: "bitgraph-check/1";
+    result: ThreeValued;
+    /** One-sentence plain-language conclusion, deterministic. */
+    summary: string;
+    recordings: CheckRecording[];
+    anchors: CheckAnchor[];
+    /** Structural findings the bundle contradicts itself on. Every entry is FALSE. */
+    contradictions: CheckLine[];
+    /** Informational: excerpt gaps, unmatched files, duplicates. Never verdicts. */
+    notes: string[];
+    /** What no offline check can establish, stated rather than implied. */
+    notChecked: string[];
+    evaluator: {
+        name: "bitgraph-player";
+        version: string;
+        audit: string;
+    };
+    network: "none";
+}
+export interface CheckOptions {
+    /**
+     * False when the environment cannot run the attestation's ECDSA P-384
+     * verification (no WebCrypto). Attestation lines are then UNDETERMINED
+     * with that reason instead of a false FALSE. Defaults to true.
+     */
+    webCryptoAvailable?: boolean;
+}
+/**
+ * Check an already-ingested bundle: runs the audit's pure tail (no
+ * filesystem, no network) and builds the report. Both the CLI and the
+ * browser page call this, so they cannot drift.
+ */
+export declare function checkIngest(ingest: IngestResult, options?: CheckOptions): Promise<CheckReport>;
+/** The pure report builder over an AuditResult. */
+export declare function buildCheckReport(audit: AuditResult, options?: CheckOptions): CheckReport;
+export declare function renderCheckText(report: CheckReport): string;
+/** Deterministic JSON bytes for the report: two-space indent, one trailing newline. */
+export declare function serializeCheckReport(report: CheckReport): string;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

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