@agenticprimitives/provenance 0.0.0-alpha.5 → 0.0.0-alpha.6

package/dist/index.d.ts

@@ -12,4 +12,6 @@ export { projectPublicProvenance } from './public.js';
 export type { PublicProvenanceRowV1, PublicProvenanceProjection } from './public.js';
 export { recordDigest } from './ports.js';
 export type { ProvenanceRecordRefV1, ProvenanceReadV1, ProvenanceWriteV1, ProvenanceStorePort, ProvenanceFormatV1, ProvenanceAccessPort, GraphQueryPort, RdfCanonicalizer, RecordDigestV1, } from './ports.js';
+export { integrityOf } from './integrity.js';
+export type { IntegrityLevelV1, IntegrityReportV1, IntegrityOpts } from './integrity.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,YAAY,kCAAkC,CAAC;AAC5D,eAAO,MAAM,cAAc,EAAG,cAAuB,CAAC;AACtD,eAAO,MAAM,QAAQ,4CAA4C,CAAC;AAElE,YAAY,EACV,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,SAAS,EACT,SAAS,EACT,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,yBAAyB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,2BAA2B,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,yBAAyB,EAAE,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClK,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEvI,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAGrF,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,YAAY,kCAAkC,CAAC;AAC5D,eAAO,MAAM,cAAc,EAAG,cAAuB,CAAC;AACtD,eAAO,MAAM,QAAQ,4CAA4C,CAAC;AAElE,YAAY,EACV,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,SAAS,EACT,SAAS,EACT,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,yBAAyB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,2BAA2B,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,yBAAyB,EAAE,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClK,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEvI,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAGrF,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -14,4 +14,6 @@ export { isPublicProjectionSafe, assertPublicProjectionSafe, } from './firewall.
 export { projectPublicProvenance } from './public.js';
 // Spec 414 §5 (A0) — the ports: the standard is the contract, a store is a binding. Leaf: no binding here.
 export { recordDigest } from './ports.js';
+// Spec 438 §4 — the integrity ladder: how far anyone has actually gone in checking a bundle's bytes.
+export { integrityOf } from './integrity.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,8GAA8G;AAC9G,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG,+BAA+B,CAAC;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,cAAuB,CAAC;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAG,yCAAyC,CAAC;AAelE,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GAGrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,yBAAyB,GAM1B,MAAM,eAAe,CAAC;AAEvB,mGAAmG;AACnG,OAAO,EAAE,2BAA2B,EAAE,QAAQ,EAAE,UAAU,EAAmF,MAAM,cAAc,CAAC;AAClK,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAsB,MAAM,gBAAgB,CAAC;AAIvI,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAG3B,MAAM,eAAe,CAAC;AACvB,wEAAwE;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtD,2GAA2G;AAC3G,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4GAA4G;AAC5G,8GAA8G;AAC9G,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG,+BAA+B,CAAC;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,cAAuB,CAAC;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAG,yCAAyC,CAAC;AAelE,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GAGrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,yBAAyB,GAM1B,MAAM,eAAe,CAAC;AAEvB,mGAAmG;AACnG,OAAO,EAAE,2BAA2B,EAAE,QAAQ,EAAE,UAAU,EAAmF,MAAM,cAAc,CAAC;AAClK,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAsB,MAAM,gBAAgB,CAAC;AAIvI,OAAO,EACL,sBAAsB,EACtB,0BAA0B,GAG3B,MAAM,eAAe,CAAC;AACvB,wEAAwE;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtD,2GAA2G;AAC3G,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAa1C,qGAAqG;AACrG,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/integrity.d.ts

@@ -0,0 +1,33 @@
+import type { RdfCanonicalizer, RecordDigestV1 } from './ports.js';
+export type IntegrityLevelV1 = 'unchecked' | 'hash-validated' | 'signature-validated' | 'anchored';
+export interface IntegrityReportV1 {
+    level: IntegrityLevelV1;
+    /** The digest the bundle actually canonicalizes to, when it was computed. */
+    computedDigest?: RecordDigestV1;
+    /** What the caller said it should be, when they said. */
+    claimedDigest?: string;
+    /** Why the ladder stopped where it did — in words, always present when it stopped below `anchored`.
+     *  A reader who sees `unchecked` must be able to tell "nobody looked" from "we looked and it did not match". */
+    reason: string;
+    /** True only when a digest was recomputed AND matched. */
+    digestMatches?: boolean;
+}
+export interface IntegrityOpts {
+    /** The digest the holder claims for this bundle (from the record, the anchor citation, or a peer). */
+    claimedDigest?: string;
+    /** Required to reach `hash-validated`: the RDFC-1.0 canonicalizer this deployment binds. */
+    canonicalize?: RdfCanonicalizer;
+    /** Required to reach `signature-validated`: verifies a signature over the digest. Returns false rather than
+     *  throwing for an invalid one; a throw is reported as a failed check, never as "unsigned". */
+    verifySignature?: (digest: RecordDigestV1) => Promise<boolean>;
+    /** Required to reach `anchored`: a READ-ONLY lookup in the receipt-anchor registry. */
+    lookupAnchor?: (digest: RecordDigestV1) => Promise<boolean>;
+}
+/**
+ * Climb the ladder as far as the supplied checks allow, and report where it stopped and why.
+ *
+ * Each rung depends on the one below: a signature over a digest that does not match the bundle proves only
+ * that someone signed a different document, so a hash mismatch stops the climb rather than being skipped past.
+ */
+export declare function integrityOf(bundle: Record<string, unknown>, opts?: IntegrityOpts): Promise<IntegrityReportV1>;
+//# sourceMappingURL=integrity.d.ts.map

package/dist/integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../src/integrity.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGnE,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,gBAAgB,GAAG,qBAAqB,GAAG,UAAU,CAAC;AAEnG,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,gBAAgB,CAAC;IACxB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;oHACgH;IAChH,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,sGAAsG;IACtG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;mGAC+F;IAC/F,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAkD5B"}

package/dist/integrity.js

@@ -0,0 +1,56 @@
+import { recordDigest } from './ports.js';
+/**
+ * Climb the ladder as far as the supplied checks allow, and report where it stopped and why.
+ *
+ * Each rung depends on the one below: a signature over a digest that does not match the bundle proves only
+ * that someone signed a different document, so a hash mismatch stops the climb rather than being skipped past.
+ */
+export async function integrityOf(bundle, opts = {}) {
+    if (!opts.canonicalize) {
+        return { level: 'unchecked', reason: 'no canonicalizer was supplied — nothing was recomputed', ...(opts.claimedDigest ? { claimedDigest: opts.claimedDigest } : {}) };
+    }
+    let computedDigest;
+    try {
+        computedDigest = await recordDigest(bundle, opts.canonicalize);
+    }
+    catch (e) {
+        return {
+            level: 'unchecked',
+            reason: `the bundle could not be canonicalized: ${e instanceof Error ? e.message : String(e)}`,
+            ...(opts.claimedDigest ? { claimedDigest: opts.claimedDigest } : {}),
+        };
+    }
+    const base = { computedDigest, ...(opts.claimedDigest ? { claimedDigest: opts.claimedDigest } : {}) };
+    if (opts.claimedDigest && opts.claimedDigest !== computedDigest) {
+        // The loudest possible answer. This is not "unchecked" in the sense of nobody looking — the reason says so.
+        return { ...base, level: 'unchecked', digestMatches: false, reason: 'the bundle does not canonicalize to the digest claimed for it' };
+    }
+    const hashRung = { ...base, level: 'hash-validated', digestMatches: true, reason: 'the bundle canonicalizes to its digest; nobody has signed or anchored it here' };
+    if (opts.verifySignature) {
+        let signed = false;
+        try {
+            signed = await opts.verifySignature(computedDigest);
+        }
+        catch (e) {
+            return { ...base, level: 'hash-validated', digestMatches: true, reason: `the signature check failed to run: ${e instanceof Error ? e.message : String(e)}` };
+        }
+        if (!signed)
+            return { ...base, level: 'hash-validated', digestMatches: true, reason: 'a signature was checked and did not verify' };
+    }
+    const signedRung = opts.verifySignature
+        ? { ...base, level: 'signature-validated', digestMatches: true, reason: 'a signature over this digest verified; it is not anchored here' }
+        : hashRung;
+    if (!opts.lookupAnchor)
+        return signedRung;
+    let anchored = false;
+    try {
+        anchored = await opts.lookupAnchor(computedDigest);
+    }
+    catch (e) {
+        return { ...signedRung, reason: `${signedRung.reason} (the anchor lookup failed to run: ${e instanceof Error ? e.message : String(e)})` };
+    }
+    if (!anchored)
+        return { ...signedRung, reason: `${signedRung.reason} (the registry does not hold this digest)` };
+    return { ...base, level: 'anchored', digestMatches: true, reason: 'the digest is held by the receipt-anchor registry' };
+}
+//# sourceMappingURL=integrity.js.map

package/dist/integrity.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticprimitives/provenance",
-  "version": "0.0.0-alpha.5",
+  "version": "0.0.0-alpha.6",
   "description": "The Ring-0 provenance projector (spec 316 §6): maps fabric exchanges + orchestration runs to a PRIVATE PROV-O / P-Plan A-box, and enforces the ADR-0040 public-projection firewall (S1). Sole writer of the private vault A-box; NEVER writes the public KB.",
   "homepage": "https://agenticprimitives.dev",
   "bugs": {
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.11",
     "@types/node": "^22.7.0"
   },
   "keywords": [