@forestrie/merklelog 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { Massif } from "./massifs/massif.js";
 export type { MassifStart, LeafComponent, LeafEnumeratorSpec, LeafEntry, } from "./massifs/types.js";
 export { MassifStartFmt } from "./massifs/types.js";
 export { LogFormat, Urkle, Bloom, IndexV2, leafCountForMassifHeight, leafTableBytes, nodeCountMax, nodeStoreBytes, bloomMBits, bloomBitsetBytes, bloomRegionBytes, indexDataBytesV2, peakStackEnd, massifLogEntries, urkleLeafTableStartFieldIndex, urkleLeafTableStartByteOffset, createLeafEnumerator, leafComponentByteOffset, leafComponentSize, computeLastMMRIndex, isMassifFull, } from "./massifs/types.js";
-export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
+export { formatMassifObjectIndex, MASSIF_OBJECT_INDEX_DIGITS, MAX_MASSIF_INDEX, parseV2StorageObjectPath, v2CheckpointObjectKey, v2MassifObjectKey, } from "./massifs/v2storagepaths.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 export type { MassifNodeStore } from "./massifs/nodestore.js";
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,SAAS,EACT,KAAK,EACL,KAAK,EACL,OAAO,EACP,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG3E,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,SAAS,EACT,KAAK,EACL,KAAK,EACL,OAAO,EACP,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG3E,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -12,7 +12,7 @@ export { Uint64 } from "./uint64/index.js";
 export { Massif } from "./massifs/massif.js";
 export { MassifStartFmt } from "./massifs/types.js";
 export { LogFormat, Urkle, Bloom, IndexV2, leafCountForMassifHeight, leafTableBytes, nodeCountMax, nodeStoreBytes, bloomMBits, bloomBitsetBytes, bloomRegionBytes, indexDataBytesV2, peakStackEnd, massifLogEntries, urkleLeafTableStartFieldIndex, urkleLeafTableStartByteOffset, createLeafEnumerator, leafComponentByteOffset, leafComponentSize, computeLastMMRIndex, isMassifFull, } from "./massifs/types.js";
-export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
+export { formatMassifObjectIndex, MASSIF_OBJECT_INDEX_DIGITS, MAX_MASSIF_INDEX, parseV2StorageObjectPath, v2CheckpointObjectKey, v2MassifObjectKey, } from "./massifs/v2storagepaths.js";
 // Massif blob node access for MMR proof building (plan-2607-15 §4)
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 // Content-hash leaf lookup over the massif index region (FOR-373)

package/dist/massifs/v2storagepaths.d.ts

@@ -1,17 +1,57 @@
 /**
- * Parse an R2 object path to extract log ID, massif height, and massif index.
+ * Merklelog v2 R2 object layout:
  *
  * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
  * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
  *
- * @param path - The object path path from the R2 notification
+ * `{massifIndex}` is a zero-padded, 16-digit DECIMAL integer. The Go writer
+ * owns this convention: go-merklelog
+ * [massifs/storage/const.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/const.go)
+ * (`V1MMRBlobNameFmt = "%016d.log"`, `V1MMRSignedTreeHeadBlobNameFmt =
+ * "%016d.sth"`) and its reader
+ * [objectindexfrompath.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/objectindexfrompath.go)
+ * (`strconv.Atoi`). canopy-api builds its R2 keys through the functions
+ * here (FOR-621: an earlier reader parsed hex, which agrees with the writer
+ * only for indices 0-9). Code outside this package that spells a key by hand
+ * (delegation-coordinator `seal-hint.ts`, test fixtures, demos) uses only
+ * index 0, which reads the same in any radix; anything that needs another
+ * index must use these helpers.
+ */
+/** Width of the massif index segment in an object key. */
+export declare const MASSIF_OBJECT_INDEX_DIGITS = 16;
+/**
+ * Largest massif index the Go side can represent. go-merklelog
+ * `FmtMassifPath(prefix, massifIndex uint32)` and arbor's publisher
+ * (`strconv.ParseUint(base, 10, 32)`) use `uint32`; a larger index would be
+ * silently truncated by `ObjectIndexFromPath`, so it is rejected here.
+ */
+export declare const MAX_MASSIF_INDEX = 4294967295n;
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * @param path - The object path from the R2 notification
  * @returns Parsed components including logId, massifHeight, and massifIndex
  * @throws Error if the path doesn't match expected format or if parsing fails
  */
 export declare function parseV2StorageObjectPath(path: string): {
     logId: string;
     massifHeight: number;
-    massifIndex: number;
+    massifIndex: bigint;
     type: string;
 };
+/**
+ * Build the massif `.log` object key for a log.
+ */
+export declare function v2MassifObjectKey(massifHeight: number, logId: string, massifIndex: bigint | number): string;
+/**
+ * Build the signed checkpoint `.sth` object key for a log.
+ */
+export declare function v2CheckpointObjectKey(massifHeight: number, logId: string, massifIndex: bigint | number): string;
+/**
+ * Format a massif index as the 16-digit decimal key segment (Go `%016d`).
+ *
+ * @throws Error if the index is negative, not an integer, not a safe integer
+ *   (number input), or exceeds {@link MAX_MASSIF_INDEX}.
+ */
+export declare function formatMassifObjectIndex(massifIndex: bigint | number): string;
 //# sourceMappingURL=v2storagepaths.d.ts.map

package/dist/massifs/v2storagepaths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v2storagepaths.d.ts","sourceRoot":"","sources":["../../src/massifs/v2storagepaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM;;;;;EAkDpD"}
+{"version":3,"file":"v2storagepaths.d.ts","sourceRoot":"","sources":["../../src/massifs/v2storagepaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAiB5C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM;;;;;EAyDpD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,MAAM,CAGR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAW5E"}

package/dist/massifs/v2storagepaths.js

@@ -1,42 +1,84 @@
 /**
- * Parse an R2 object path to extract log ID, massif height, and massif index.
+ * Merklelog v2 R2 object layout:
  *
  * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
  * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
  *
- * @param path - The object path path from the R2 notification
+ * `{massifIndex}` is a zero-padded, 16-digit DECIMAL integer. The Go writer
+ * owns this convention: go-merklelog
+ * [massifs/storage/const.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/const.go)
+ * (`V1MMRBlobNameFmt = "%016d.log"`, `V1MMRSignedTreeHeadBlobNameFmt =
+ * "%016d.sth"`) and its reader
+ * [objectindexfrompath.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/objectindexfrompath.go)
+ * (`strconv.Atoi`). canopy-api builds its R2 keys through the functions
+ * here (FOR-621: an earlier reader parsed hex, which agrees with the writer
+ * only for indices 0-9). Code outside this package that spells a key by hand
+ * (delegation-coordinator `seal-hint.ts`, test fixtures, demos) uses only
+ * index 0, which reads the same in any radix; anything that needs another
+ * index must use these helpers.
+ */
+/** Width of the massif index segment in an object key. */
+export const MASSIF_OBJECT_INDEX_DIGITS = 16;
+/**
+ * Largest massif index the Go side can represent. go-merklelog
+ * `FmtMassifPath(prefix, massifIndex uint32)` and arbor's publisher
+ * (`strconv.ParseUint(base, 10, 32)`) use `uint32`; a larger index would be
+ * silently truncated by `ObjectIndexFromPath`, so it is rejected here.
+ */
+export const MAX_MASSIF_INDEX = 0xffffffffn;
+/**
+ * Massif height bounds. Go writes height as `%d` of a `uint8` and arbor's
+ * publisher `ParseCheckpointKey` rejects 0, so valid heights are 1..255 with
+ * no leading zeros.
+ */
+const MIN_MASSIF_HEIGHT = 1;
+const MAX_MASSIF_HEIGHT = 255;
+const MASSIF_OBJECT_INDEX_RE = /^[0-9]{16}$/;
+const MASSIF_HEIGHT_RE = /^[1-9][0-9]{0,2}$/;
+const OBJECT_EXTENSIONS = {
+    massifs: ".log",
+    checkpoints: ".sth",
+};
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * @param path - The object path from the R2 notification
  * @returns Parsed components including logId, massifHeight, and massifIndex
  * @throws Error if the path doesn't match expected format or if parsing fails
  */
 export function parseV2StorageObjectPath(path) {
     const parts = path.split("/");
-    if (parts.length < 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
+    if (parts.length !== 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
         throw new Error(`Unrecognized path format: ${path}`);
-    // Check for new v2 format: v2/merklelog/massifs/{massifHeight}/{logId}/{index}.log
-    // or v2/merklelog/checkpoints/{massifHeight}/{logId}/{index}.sth
-    const typePart = parts[2]; // "massifs" or "checkpoints"
+    const typePart = parts[2];
     const massifHeightStr = parts[3];
     const logId = parts[4];
     const filename = parts[5];
-    // Validate extension
-    const expectedExt = typePart === "massifs" ? ".log" : ".sth";
+    const expectedExt = Object.hasOwn(OBJECT_EXTENSIONS, typePart)
+        ? OBJECT_EXTENSIONS[typePart]
+        : undefined;
+    if (expectedExt === undefined) {
+        throw new Error(`Object type must be massifs or checkpoints, got: ${typePart}`);
+    }
+    if (logId.length === 0) {
+        throw new Error(`Log id segment is empty: ${path}`);
+    }
     if (!filename.endsWith(expectedExt)) {
         throw new Error(`Expected ${expectedExt} extension for ${typePart}, got: ${filename}`);
     }
-    // Parse massif index (hex, 16 digits)
     const massifIndexStr = filename.slice(0, -expectedExt.length);
-    if (massifIndexStr.length !== 16) {
-        throw new Error(`Massif index must be 16 hex digits, got ${massifIndexStr.length}: ${massifIndexStr}`);
+    if (!MASSIF_OBJECT_INDEX_RE.test(massifIndexStr)) {
+        throw new Error(`Massif index must be 16 decimal digits, got: ${massifIndexStr}`);
     }
-    const massifIndex = Number.parseInt(massifIndexStr, 16);
-    if (!Number.isFinite(massifIndex)) {
-        throw new Error(`Failed to parse massif index as hex number: ${massifIndexStr}`);
+    const massifIndex = BigInt(massifIndexStr);
+    if (massifIndex > MAX_MASSIF_INDEX) {
+        throw new Error(`Massif index must be 0..${MAX_MASSIF_INDEX}, got ${massifIndex}`);
     }
-    // Parse massifHeight
-    const massifHeight = Number.parseInt(massifHeightStr, 10);
-    if (!Number.isFinite(massifHeight)) {
+    if (!MASSIF_HEIGHT_RE.test(massifHeightStr) ||
+        Number(massifHeightStr) > MAX_MASSIF_HEIGHT) {
         throw new Error(`Failed to parse massif height as number: ${massifHeightStr}`);
     }
+    const massifHeight = Number(massifHeightStr);
     return {
         logId,
         massifHeight,
@@ -44,3 +86,48 @@ export function parseV2StorageObjectPath(path) {
         type: typePart,
     };
 }
+/**
+ * Build the massif `.log` object key for a log.
+ */
+export function v2MassifObjectKey(massifHeight, logId, massifIndex) {
+    assertKeyHeightAndLogId(massifHeight, logId);
+    return `v2/merklelog/massifs/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.log`;
+}
+/**
+ * Build the signed checkpoint `.sth` object key for a log.
+ */
+export function v2CheckpointObjectKey(massifHeight, logId, massifIndex) {
+    assertKeyHeightAndLogId(massifHeight, logId);
+    return `v2/merklelog/checkpoints/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.sth`;
+}
+/**
+ * Format a massif index as the 16-digit decimal key segment (Go `%016d`).
+ *
+ * @throws Error if the index is negative, not an integer, not a safe integer
+ *   (number input), or exceeds {@link MAX_MASSIF_INDEX}.
+ */
+export function formatMassifObjectIndex(massifIndex) {
+    if (typeof massifIndex === "number" && !Number.isSafeInteger(massifIndex)) {
+        throw new Error(`Massif index must be a safe integer, got ${massifIndex}`);
+    }
+    const index = BigInt(massifIndex);
+    if (index < 0n || index > MAX_MASSIF_INDEX) {
+        throw new Error(`Massif index must be 0..${MAX_MASSIF_INDEX}, got ${index}`);
+    }
+    return index.toString(10).padStart(MASSIF_OBJECT_INDEX_DIGITS, "0");
+}
+/**
+ * Reject a massif height or log id that would build a key Go cannot read:
+ * height outside 1..255 or non-integer, or a log id that is empty or would
+ * add path segments.
+ */
+function assertKeyHeightAndLogId(massifHeight, logId) {
+    if (!Number.isInteger(massifHeight) ||
+        massifHeight < MIN_MASSIF_HEIGHT ||
+        massifHeight > MAX_MASSIF_HEIGHT) {
+        throw new Error(`Massif height must be an integer ${MIN_MASSIF_HEIGHT}..${MAX_MASSIF_HEIGHT}, got ${massifHeight}`);
+    }
+    if (logId.length === 0 || logId.includes("/")) {
+        throw new Error(`Log id must be a non-empty path segment, got: ${JSON.stringify(logId)}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/merklelog",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "type": "module",
   "description": "MMR (merkle mountain range) proofs and massif storage format for Forestrie transparency logs",

package/src/index.ts

@@ -43,7 +43,14 @@ export {
   isMassifFull,
 } from "./massifs/types.js";
 
-export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
+export {
+  formatMassifObjectIndex,
+  MASSIF_OBJECT_INDEX_DIGITS,
+  MAX_MASSIF_INDEX,
+  parseV2StorageObjectPath,
+  v2CheckpointObjectKey,
+  v2MassifObjectKey,
+} from "./massifs/v2storagepaths.js";
 
 // Massif blob node access for MMR proof building (plan-2607-15 §4)
 export { openMassifNodeStore } from "./massifs/nodestore.js";

package/src/massifs/v2storagepaths.ts

@@ -1,56 +1,106 @@
 /**
- * Parse an R2 object path to extract log ID, massif height, and massif index.
+ * Merklelog v2 R2 object layout:
  *
  * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
  * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
  *
- * @param path - The object path path from the R2 notification
+ * `{massifIndex}` is a zero-padded, 16-digit DECIMAL integer. The Go writer
+ * owns this convention: go-merklelog
+ * [massifs/storage/const.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/const.go)
+ * (`V1MMRBlobNameFmt = "%016d.log"`, `V1MMRSignedTreeHeadBlobNameFmt =
+ * "%016d.sth"`) and its reader
+ * [objectindexfrompath.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/objectindexfrompath.go)
+ * (`strconv.Atoi`). canopy-api builds its R2 keys through the functions
+ * here (FOR-621: an earlier reader parsed hex, which agrees with the writer
+ * only for indices 0-9). Code outside this package that spells a key by hand
+ * (delegation-coordinator `seal-hint.ts`, test fixtures, demos) uses only
+ * index 0, which reads the same in any radix; anything that needs another
+ * index must use these helpers.
+ */
+
+/** Width of the massif index segment in an object key. */
+export const MASSIF_OBJECT_INDEX_DIGITS = 16;
+
+/**
+ * Largest massif index the Go side can represent. go-merklelog
+ * `FmtMassifPath(prefix, massifIndex uint32)` and arbor's publisher
+ * (`strconv.ParseUint(base, 10, 32)`) use `uint32`; a larger index would be
+ * silently truncated by `ObjectIndexFromPath`, so it is rejected here.
+ */
+export const MAX_MASSIF_INDEX = 0xffffffffn;
+
+/**
+ * Massif height bounds. Go writes height as `%d` of a `uint8` and arbor's
+ * publisher `ParseCheckpointKey` rejects 0, so valid heights are 1..255 with
+ * no leading zeros.
+ */
+const MIN_MASSIF_HEIGHT = 1;
+const MAX_MASSIF_HEIGHT = 255;
+
+const MASSIF_OBJECT_INDEX_RE = /^[0-9]{16}$/;
+const MASSIF_HEIGHT_RE = /^[1-9][0-9]{0,2}$/;
+const OBJECT_EXTENSIONS: Readonly<Record<string, string>> = {
+  massifs: ".log",
+  checkpoints: ".sth",
+};
+
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * @param path - The object path from the R2 notification
  * @returns Parsed components including logId, massifHeight, and massifIndex
  * @throws Error if the path doesn't match expected format or if parsing fails
  */
 export function parseV2StorageObjectPath(path: string) {
   const parts = path.split("/");
 
-  if (parts.length < 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
+  if (parts.length !== 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
     throw new Error(`Unrecognized path format: ${path}`);
 
-  // Check for new v2 format: v2/merklelog/massifs/{massifHeight}/{logId}/{index}.log
-  // or v2/merklelog/checkpoints/{massifHeight}/{logId}/{index}.sth
-  const typePart = parts[2]; // "massifs" or "checkpoints"
+  const typePart = parts[2];
   const massifHeightStr = parts[3];
   const logId = parts[4];
   const filename = parts[5];
 
-  // Validate extension
-  const expectedExt = typePart === "massifs" ? ".log" : ".sth";
+  const expectedExt = Object.hasOwn(OBJECT_EXTENSIONS, typePart)
+    ? OBJECT_EXTENSIONS[typePart]
+    : undefined;
+  if (expectedExt === undefined) {
+    throw new Error(
+      `Object type must be massifs or checkpoints, got: ${typePart}`,
+    );
+  }
+  if (logId.length === 0) {
+    throw new Error(`Log id segment is empty: ${path}`);
+  }
   if (!filename.endsWith(expectedExt)) {
     throw new Error(
       `Expected ${expectedExt} extension for ${typePart}, got: ${filename}`,
     );
   }
 
-  // Parse massif index (hex, 16 digits)
   const massifIndexStr = filename.slice(0, -expectedExt.length);
-  if (massifIndexStr.length !== 16) {
+  if (!MASSIF_OBJECT_INDEX_RE.test(massifIndexStr)) {
     throw new Error(
-      `Massif index must be 16 hex digits, got ${massifIndexStr.length}: ${massifIndexStr}`,
+      `Massif index must be 16 decimal digits, got: ${massifIndexStr}`,
     );
   }
-
-  const massifIndex = Number.parseInt(massifIndexStr, 16);
-  if (!Number.isFinite(massifIndex)) {
+  const massifIndex = BigInt(massifIndexStr);
+  if (massifIndex > MAX_MASSIF_INDEX) {
     throw new Error(
-      `Failed to parse massif index as hex number: ${massifIndexStr}`,
+      `Massif index must be 0..${MAX_MASSIF_INDEX}, got ${massifIndex}`,
     );
   }
 
-  // Parse massifHeight
-  const massifHeight = Number.parseInt(massifHeightStr, 10);
-  if (!Number.isFinite(massifHeight)) {
+  if (
+    !MASSIF_HEIGHT_RE.test(massifHeightStr) ||
+    Number(massifHeightStr) > MAX_MASSIF_HEIGHT
+  ) {
     throw new Error(
       `Failed to parse massif height as number: ${massifHeightStr}`,
     );
   }
+  const massifHeight = Number(massifHeightStr);
 
   return {
     logId,
@@ -59,3 +109,68 @@ export function parseV2StorageObjectPath(path: string) {
     type: typePart,
   };
 }
+
+/**
+ * Build the massif `.log` object key for a log.
+ */
+export function v2MassifObjectKey(
+  massifHeight: number,
+  logId: string,
+  massifIndex: bigint | number,
+): string {
+  assertKeyHeightAndLogId(massifHeight, logId);
+  return `v2/merklelog/massifs/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.log`;
+}
+
+/**
+ * Build the signed checkpoint `.sth` object key for a log.
+ */
+export function v2CheckpointObjectKey(
+  massifHeight: number,
+  logId: string,
+  massifIndex: bigint | number,
+): string {
+  assertKeyHeightAndLogId(massifHeight, logId);
+  return `v2/merklelog/checkpoints/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.sth`;
+}
+
+/**
+ * Format a massif index as the 16-digit decimal key segment (Go `%016d`).
+ *
+ * @throws Error if the index is negative, not an integer, not a safe integer
+ *   (number input), or exceeds {@link MAX_MASSIF_INDEX}.
+ */
+export function formatMassifObjectIndex(massifIndex: bigint | number): string {
+  if (typeof massifIndex === "number" && !Number.isSafeInteger(massifIndex)) {
+    throw new Error(`Massif index must be a safe integer, got ${massifIndex}`);
+  }
+  const index = BigInt(massifIndex);
+  if (index < 0n || index > MAX_MASSIF_INDEX) {
+    throw new Error(
+      `Massif index must be 0..${MAX_MASSIF_INDEX}, got ${index}`,
+    );
+  }
+  return index.toString(10).padStart(MASSIF_OBJECT_INDEX_DIGITS, "0");
+}
+
+/**
+ * Reject a massif height or log id that would build a key Go cannot read:
+ * height outside 1..255 or non-integer, or a log id that is empty or would
+ * add path segments.
+ */
+function assertKeyHeightAndLogId(massifHeight: number, logId: string): void {
+  if (
+    !Number.isInteger(massifHeight) ||
+    massifHeight < MIN_MASSIF_HEIGHT ||
+    massifHeight > MAX_MASSIF_HEIGHT
+  ) {
+    throw new Error(
+      `Massif height must be an integer ${MIN_MASSIF_HEIGHT}..${MAX_MASSIF_HEIGHT}, got ${massifHeight}`,
+    );
+  }
+  if (logId.length === 0 || logId.includes("/")) {
+    throw new Error(
+      `Log id must be a non-empty path segment, got: ${JSON.stringify(logId)}`,
+    );
+  }
+}