@forestrie/receipt-verify 0.5.1 → 0.6.0

package/dist/find-grant-leaf.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Offline grant-leaf lookup (FOR-344): locate a grant's sequenced leaf in a
+ * local massif blob using only the grant statement and the massif `.log`.
+ *
+ * The sequencer commits a grant to the log under its grant commitment hash
+ * (`grantCommitmentHashFromGrant` — the ContentHash enqueued in
+ * canopy-api `grant-sequencing.ts`), and the v2 urkle index region records that
+ * hash in each leaf's value column keyed by the leaf's 8-byte idtimestamp. So a
+ * client holding the owner-log massif can recover BOTH halves of the permanent
+ * entry id (`idtimestamp_be8 || mmrIndex_be8`) with no operator round-trip —
+ * the derivation that lets `forestrie complete-grant` build the completed grant
+ * header offline (grants are derivable from log data, not operator-issued).
+ *
+ * Pure over bytes; no network, no signing key. Browser-safe (ADR-0048).
+ *
+ * The lookup is a linear scan of the leaf-table value column. That is optimal
+ * here: recovering the entry id needs the leaf's *position* (ordinal → mmrIndex
+ * + idtimestamp key), and no content-hash→position index exists in the blob.
+ * The index region's bloom filter 0 IS keyed on the content hash, but a bloom
+ * only answers membership (maybe/definitely-not), never position — so it could
+ * at best short-circuit the not-present case, not the recovery; the positional
+ * structure (the urkle trie) is keyed by idtimestamp, which is exactly what we
+ * are recovering. Building a value→position map would itself be an O(n) scan.
+ */
+import { type LocatedLeaf } from "@forestrie/merklelog";
+import type { Grant } from "@forestrie/encoding";
+export type { LocatedLeaf };
+/**
+ * Find the grant's leaf in `massifBytes` and return its `mmrIndex` and the
+ * 8-byte idtimestamp key, or `null` when the grant's commitment hash is not
+ * present in this massif's index region (searched, not found).
+ *
+ * Throws `MissingIndexError` (from `@forestrie/merklelog`) when the blob has no
+ * populated index region at all — distinguishable from a not-found `null`.
+ */
+export declare function findGrantLeafInMassif(massifBytes: Uint8Array, grant: Grant): Promise<LocatedLeaf | null>;
+//# sourceMappingURL=find-grant-leaf.d.ts.map

package/dist/find-grant-leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-grant-leaf.d.ts","sourceRoot":"","sources":["../src/find-grant-leaf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAGjD,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,UAAU,EACvB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAI7B"}

package/dist/find-grant-leaf.js

@@ -0,0 +1,39 @@
+/**
+ * Offline grant-leaf lookup (FOR-344): locate a grant's sequenced leaf in a
+ * local massif blob using only the grant statement and the massif `.log`.
+ *
+ * The sequencer commits a grant to the log under its grant commitment hash
+ * (`grantCommitmentHashFromGrant` — the ContentHash enqueued in
+ * canopy-api `grant-sequencing.ts`), and the v2 urkle index region records that
+ * hash in each leaf's value column keyed by the leaf's 8-byte idtimestamp. So a
+ * client holding the owner-log massif can recover BOTH halves of the permanent
+ * entry id (`idtimestamp_be8 || mmrIndex_be8`) with no operator round-trip —
+ * the derivation that lets `forestrie complete-grant` build the completed grant
+ * header offline (grants are derivable from log data, not operator-issued).
+ *
+ * Pure over bytes; no network, no signing key. Browser-safe (ADR-0048).
+ *
+ * The lookup is a linear scan of the leaf-table value column. That is optimal
+ * here: recovering the entry id needs the leaf's *position* (ordinal → mmrIndex
+ * + idtimestamp key), and no content-hash→position index exists in the blob.
+ * The index region's bloom filter 0 IS keyed on the content hash, but a bloom
+ * only answers membership (maybe/definitely-not), never position — so it could
+ * at best short-circuit the not-present case, not the recovery; the positional
+ * structure (the urkle trie) is keyed by idtimestamp, which is exactly what we
+ * are recovering. Building a value→position map would itself be an O(n) scan.
+ */
+import { openMassifLeafIndex } from "@forestrie/merklelog";
+import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
+/**
+ * Find the grant's leaf in `massifBytes` and return its `mmrIndex` and the
+ * 8-byte idtimestamp key, or `null` when the grant's commitment hash is not
+ * present in this massif's index region (searched, not found).
+ *
+ * Throws `MissingIndexError` (from `@forestrie/merklelog`) when the blob has no
+ * populated index region at all — distinguishable from a not-found `null`.
+ */
+export async function findGrantLeafInMassif(massifBytes, grant) {
+    const inner = await grantCommitmentHashFromGrant(grant);
+    const index = openMassifLeafIndex(massifBytes);
+    return index.findLeafByContentHash(inner);
+}

package/dist/index.d.ts

@@ -18,4 +18,11 @@ export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 export { HEADER_RECEIPT, attachReceiptAndIdtimestampToTransparentStatement, } from "./attach-transparent-statement-receipt.js";
 export { decodeEntryIdHex, entryIdHexToIdtimestampBe8 } from "./entry-id.js";
 export type { DecodedEntryId } from "./entry-id.js";
+/** Grant commitment hash (ContentHash) — the value the sequencer commits. */
+export { grantCommitmentHashFromGrant } from "./grant-commitment.js";
+/** Offline grant-leaf lookup from a local massif blob (FOR-344). */
+export { findGrantLeafInMassif } from "./find-grant-leaf.js";
+export type { LocatedLeaf } from "./find-grant-leaf.js";
+/** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
+export { MissingIndexError } from "@forestrie/merklelog";
 //# 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":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,oFAAoF;AACpF,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,GACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,GAChB,MAAM,4BAA4B,CAAC;AACpC;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE3E,0EAA0E;AAC1E,OAAO,EACL,cAAc,EACd,iDAAiD,GAClD,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC7E,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,6EAA6E;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,oEAAoE;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -12,3 +12,9 @@ export { decodeGrantPayload, decodeGrantResponse } from "./grant-codec.js";
 /** Deterministic receipt construction (plan-2607-12 Phase 2, FOR-353). */
 export { HEADER_RECEIPT, attachReceiptAndIdtimestampToTransparentStatement, } from "./attach-transparent-statement-receipt.js";
 export { decodeEntryIdHex, entryIdHexToIdtimestampBe8 } from "./entry-id.js";
+/** Grant commitment hash (ContentHash) — the value the sequencer commits. */
+export { grantCommitmentHashFromGrant } from "./grant-commitment.js";
+/** Offline grant-leaf lookup from a local massif blob (FOR-344). */
+export { findGrantLeafInMassif } from "./find-grant-leaf.js";
+/** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
+export { MissingIndexError } from "@forestrie/merklelog";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/receipt-verify",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "license": "MIT",
   "type": "module",
   "description": "Offline SCITT grant receipt verification (ADR-0045)",
@@ -28,8 +28,8 @@
   ],
   "dependencies": {
     "@noble/hashes": "^1.7.1",
-    "@forestrie/merklelog": "0.1.0",
-    "@forestrie/encoding": "0.3.0"
+    "@forestrie/encoding": "0.3.0",
+    "@forestrie/merklelog": "0.1.1"
   },
   "devDependencies": {
     "esbuild": "^0.24.0",

package/src/find-grant-leaf.ts

@@ -0,0 +1,46 @@
+/**
+ * Offline grant-leaf lookup (FOR-344): locate a grant's sequenced leaf in a
+ * local massif blob using only the grant statement and the massif `.log`.
+ *
+ * The sequencer commits a grant to the log under its grant commitment hash
+ * (`grantCommitmentHashFromGrant` — the ContentHash enqueued in
+ * canopy-api `grant-sequencing.ts`), and the v2 urkle index region records that
+ * hash in each leaf's value column keyed by the leaf's 8-byte idtimestamp. So a
+ * client holding the owner-log massif can recover BOTH halves of the permanent
+ * entry id (`idtimestamp_be8 || mmrIndex_be8`) with no operator round-trip —
+ * the derivation that lets `forestrie complete-grant` build the completed grant
+ * header offline (grants are derivable from log data, not operator-issued).
+ *
+ * Pure over bytes; no network, no signing key. Browser-safe (ADR-0048).
+ *
+ * The lookup is a linear scan of the leaf-table value column. That is optimal
+ * here: recovering the entry id needs the leaf's *position* (ordinal → mmrIndex
+ * + idtimestamp key), and no content-hash→position index exists in the blob.
+ * The index region's bloom filter 0 IS keyed on the content hash, but a bloom
+ * only answers membership (maybe/definitely-not), never position — so it could
+ * at best short-circuit the not-present case, not the recovery; the positional
+ * structure (the urkle trie) is keyed by idtimestamp, which is exactly what we
+ * are recovering. Building a value→position map would itself be an O(n) scan.
+ */
+import { openMassifLeafIndex, type LocatedLeaf } from "@forestrie/merklelog";
+import type { Grant } from "@forestrie/encoding";
+import { grantCommitmentHashFromGrant } from "./grant-commitment.js";
+
+export type { LocatedLeaf };
+
+/**
+ * Find the grant's leaf in `massifBytes` and return its `mmrIndex` and the
+ * 8-byte idtimestamp key, or `null` when the grant's commitment hash is not
+ * present in this massif's index region (searched, not found).
+ *
+ * Throws `MissingIndexError` (from `@forestrie/merklelog`) when the blob has no
+ * populated index region at all — distinguishable from a not-found `null`.
+ */
+export async function findGrantLeafInMassif(
+  massifBytes: Uint8Array,
+  grant: Grant,
+): Promise<LocatedLeaf | null> {
+  const inner = await grantCommitmentHashFromGrant(grant);
+  const index = openMassifLeafIndex(massifBytes);
+  return index.findLeafByContentHash(inner);
+}

package/src/index.ts

@@ -35,3 +35,11 @@ export {
 } from "./attach-transparent-statement-receipt.js";
 export { decodeEntryIdHex, entryIdHexToIdtimestampBe8 } from "./entry-id.js";
 export type { DecodedEntryId } from "./entry-id.js";
+
+/** Grant commitment hash (ContentHash) — the value the sequencer commits. */
+export { grantCommitmentHashFromGrant } from "./grant-commitment.js";
+/** Offline grant-leaf lookup from a local massif blob (FOR-344). */
+export { findGrantLeafInMassif } from "./find-grant-leaf.js";
+export type { LocatedLeaf } from "./find-grant-leaf.js";
+/** Re-exported so callers of findGrantLeafInMassif can catch it (FOR-344). */
+export { MissingIndexError } from "@forestrie/merklelog";