@totemsdk/raster-proof 0.1.0

package/dist/index.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * @module @totemsdk/raster-proof
+ *
+ * Edge-capable raster and visual evidence proof primitives for Totem Edge.
+ *
+ * This package proves bytes, manifests, provenance, windows and declared
+ * relationships. It does NOT prove that a visual interpretation is correct
+ * unless a reviewer or downstream model proof says so.
+ *
+ * Pipeline:
+ *
+ *   bytes + asset metadata + spatial context + provenance
+ *   → chunk hashes / Merkle root
+ *   → deterministic raster manifest
+ *   → window proof (optional)
+ *   → Totem proof envelope
+ *   → proofgraph linkage
+ *
+ * This is NOT a raster-processing engine: no GDAL, no GeoTIFF parsing, no
+ * satellite provider APIs, no STAC, no cloud masking, no NDVI, no ML
+ * segmentation, no orthomosaic generation, no tile server, no storage.
+ *
+ * No network, no storage, no map rendering, no GIS engine dependency.
+ * SHA3-256 everywhere, safe to run on edge devices.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addRasterManifestToGraph = exports.rasterWindowProofToGraphEdges = exports.rasterManifestToGraphEdges = exports.rasterWindowProofToProofGraphNode = exports.rasterManifestToProofGraphNode = exports.verifyRasterProof = exports.signRasterProof = exports.createUnsignedRasterProof = exports.rasterEvidenceRefs = exports.createRasterSpatialRelation = exports.rasterFootprintToSpatialObject = exports.verifyRasterDerivation = exports.createDerivedRasterManifest = exports.rasterWindowProofToEvidenceRef = exports.createRasterWindowProof = exports.rasterManifestToEvidenceRef = exports.validateRasterManifest = exports.createRasterManifest = exports.createRasterMerkleSummary = exports.verifyMerkleProof = exports.createMerkleProof = exports.merkleLeafHash = exports.computeMerkleRoot = exports.chunkBytes = exports.DEFAULT_CHUNK_SIZE_BYTES = exports.hashSubarray = exports.hashString = exports.hashBytes = exports.hashRasterWindowProof = exports.computeRasterWindowProofId = exports.hashRasterManifest = exports.computeRasterManifestId = exports.toHex = exports.canonicalJson = void 0;
+var canonical_js_1 = require("./canonical.js");
+Object.defineProperty(exports, "canonicalJson", { enumerable: true, get: function () { return canonical_js_1.canonicalJson; } });
+Object.defineProperty(exports, "toHex", { enumerable: true, get: function () { return canonical_js_1.toHex; } });
+var canonical_js_2 = require("./canonical.js");
+Object.defineProperty(exports, "computeRasterManifestId", { enumerable: true, get: function () { return canonical_js_2.computeRasterManifestId; } });
+Object.defineProperty(exports, "hashRasterManifest", { enumerable: true, get: function () { return canonical_js_2.hashRasterManifest; } });
+Object.defineProperty(exports, "computeRasterWindowProofId", { enumerable: true, get: function () { return canonical_js_2.computeRasterWindowProofId; } });
+Object.defineProperty(exports, "hashRasterWindowProof", { enumerable: true, get: function () { return canonical_js_2.hashRasterWindowProof; } });
+var hash_js_1 = require("./hash.js");
+Object.defineProperty(exports, "hashBytes", { enumerable: true, get: function () { return hash_js_1.hashBytes; } });
+Object.defineProperty(exports, "hashString", { enumerable: true, get: function () { return hash_js_1.hashString; } });
+Object.defineProperty(exports, "hashSubarray", { enumerable: true, get: function () { return hash_js_1.hashSubarray; } });
+var merkle_js_1 = require("./merkle.js");
+Object.defineProperty(exports, "DEFAULT_CHUNK_SIZE_BYTES", { enumerable: true, get: function () { return merkle_js_1.DEFAULT_CHUNK_SIZE_BYTES; } });
+Object.defineProperty(exports, "chunkBytes", { enumerable: true, get: function () { return merkle_js_1.chunkBytes; } });
+Object.defineProperty(exports, "computeMerkleRoot", { enumerable: true, get: function () { return merkle_js_1.computeMerkleRoot; } });
+Object.defineProperty(exports, "merkleLeafHash", { enumerable: true, get: function () { return merkle_js_1.merkleLeafHash; } });
+Object.defineProperty(exports, "createMerkleProof", { enumerable: true, get: function () { return merkle_js_1.createMerkleProof; } });
+Object.defineProperty(exports, "verifyMerkleProof", { enumerable: true, get: function () { return merkle_js_1.verifyMerkleProof; } });
+Object.defineProperty(exports, "createRasterMerkleSummary", { enumerable: true, get: function () { return merkle_js_1.createRasterMerkleSummary; } });
+var manifest_js_1 = require("./manifest.js");
+Object.defineProperty(exports, "createRasterManifest", { enumerable: true, get: function () { return manifest_js_1.createRasterManifest; } });
+Object.defineProperty(exports, "validateRasterManifest", { enumerable: true, get: function () { return manifest_js_1.validateRasterManifest; } });
+Object.defineProperty(exports, "rasterManifestToEvidenceRef", { enumerable: true, get: function () { return manifest_js_1.rasterManifestToEvidenceRef; } });
+var window_js_1 = require("./window.js");
+Object.defineProperty(exports, "createRasterWindowProof", { enumerable: true, get: function () { return window_js_1.createRasterWindowProof; } });
+Object.defineProperty(exports, "rasterWindowProofToEvidenceRef", { enumerable: true, get: function () { return window_js_1.rasterWindowProofToEvidenceRef; } });
+var provenance_js_1 = require("./provenance.js");
+Object.defineProperty(exports, "createDerivedRasterManifest", { enumerable: true, get: function () { return provenance_js_1.createDerivedRasterManifest; } });
+Object.defineProperty(exports, "verifyRasterDerivation", { enumerable: true, get: function () { return provenance_js_1.verifyRasterDerivation; } });
+var spatial_js_1 = require("./spatial.js");
+Object.defineProperty(exports, "rasterFootprintToSpatialObject", { enumerable: true, get: function () { return spatial_js_1.rasterFootprintToSpatialObject; } });
+Object.defineProperty(exports, "createRasterSpatialRelation", { enumerable: true, get: function () { return spatial_js_1.createRasterSpatialRelation; } });
+var proof_js_1 = require("./proof.js");
+Object.defineProperty(exports, "rasterEvidenceRefs", { enumerable: true, get: function () { return proof_js_1.rasterEvidenceRefs; } });
+Object.defineProperty(exports, "createUnsignedRasterProof", { enumerable: true, get: function () { return proof_js_1.createUnsignedRasterProof; } });
+Object.defineProperty(exports, "signRasterProof", { enumerable: true, get: function () { return proof_js_1.signRasterProof; } });
+Object.defineProperty(exports, "verifyRasterProof", { enumerable: true, get: function () { return proof_js_1.verifyRasterProof; } });
+var proofgraph_js_1 = require("./proofgraph.js");
+Object.defineProperty(exports, "rasterManifestToProofGraphNode", { enumerable: true, get: function () { return proofgraph_js_1.rasterManifestToProofGraphNode; } });
+Object.defineProperty(exports, "rasterWindowProofToProofGraphNode", { enumerable: true, get: function () { return proofgraph_js_1.rasterWindowProofToProofGraphNode; } });
+Object.defineProperty(exports, "rasterManifestToGraphEdges", { enumerable: true, get: function () { return proofgraph_js_1.rasterManifestToGraphEdges; } });
+Object.defineProperty(exports, "rasterWindowProofToGraphEdges", { enumerable: true, get: function () { return proofgraph_js_1.rasterWindowProofToGraphEdges; } });
+Object.defineProperty(exports, "addRasterManifestToGraph", { enumerable: true, get: function () { return proofgraph_js_1.addRasterManifestToGraph; } });

package/dist/manifest.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Raster manifest construction and validation for @totemsdk/raster-proof.
+ *
+ * A RasterManifest is the deterministic, content-addressed record of "what
+ * this raster is, where it came from, what bytes back it, and what spatial
+ * context it has". Creation is pure — no I/O, no format sniffing.
+ */
+import type { EvidenceRef } from '@totemsdk/proof';
+import type { CreateRasterManifestParams, RasterManifest, RasterValidationResult } from './types.js';
+/**
+ * Create a deterministic RasterManifest. rasterId is computed from stable
+ * fields (everything except rasterId and metadata).
+ */
+export declare function createRasterManifest(params: CreateRasterManifestParams): RasterManifest;
+/**
+ * Validate the structure of a RasterManifest. Structural only — does not
+ * re-hash bytes (verification of a proof envelope also recomputes the ID and
+ * manifest hash).
+ */
+export declare function validateRasterManifest(manifest: RasterManifest): RasterValidationResult;
+/**
+ * Convert a RasterManifest into an EvidenceRef for inclusion in a proof.
+ */
+export declare function rasterManifestToEvidenceRef(manifest: RasterManifest): EvidenceRef;

package/dist/manifest.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Raster manifest construction and validation for @totemsdk/raster-proof.
+ *
+ * A RasterManifest is the deterministic, content-addressed record of "what
+ * this raster is, where it came from, what bytes back it, and what spatial
+ * context it has". Creation is pure — no I/O, no format sniffing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRasterManifest = createRasterManifest;
+exports.validateRasterManifest = validateRasterManifest;
+exports.rasterManifestToEvidenceRef = rasterManifestToEvidenceRef;
+const canonical_js_1 = require("./canonical.js");
+const CAPTURE_SKEW_MS = 24 * 60 * 60 * 1000; // capturedAt may lag createdAt by ≤ 24h
+function inLonRange(v) {
+    return Number.isFinite(v) && v >= -180 && v <= 180;
+}
+function inLatRange(v) {
+    return Number.isFinite(v) && v >= -90 && v <= 90;
+}
+/**
+ * Create a deterministic RasterManifest. rasterId is computed from stable
+ * fields (everything except rasterId and metadata).
+ */
+function createRasterManifest(params) {
+    const createdAt = params.createdAt ?? Date.now();
+    const body = {
+        sourceType: params.sourceType,
+        layerType: params.layerType,
+        ...(params.capturedAt !== undefined ? { capturedAt: params.capturedAt } : {}),
+        createdAt,
+        ...(params.deviceId !== undefined ? { deviceId: params.deviceId } : {}),
+        ...(params.operatorId !== undefined ? { operatorId: params.operatorId } : {}),
+        ...(params.missionId !== undefined ? { missionId: params.missionId } : {}),
+        ...(params.providerId !== undefined ? { providerId: params.providerId } : {}),
+        ...(params.sceneId !== undefined ? { sceneId: params.sceneId } : {}),
+        asset: params.asset,
+        ...(params.spatial !== undefined ? { spatial: params.spatial } : {}),
+        ...(params.provenance !== undefined ? { provenance: params.provenance } : {}),
+        ...(params.metadata !== undefined ? { metadata: params.metadata } : {}),
+    };
+    return { ...body, rasterId: (0, canonical_js_1.computeRasterManifestId)(body) };
+}
+/**
+ * Validate the structure of a RasterManifest. Structural only — does not
+ * re-hash bytes (verification of a proof envelope also recomputes the ID and
+ * manifest hash).
+ */
+function validateRasterManifest(manifest) {
+    const errors = [];
+    const warnings = [];
+    if (typeof manifest.rasterId !== 'string' || manifest.rasterId.length === 0) {
+        errors.push('rasterId is required');
+    }
+    if (!manifest.sourceType) {
+        errors.push('sourceType is required');
+    }
+    if (!manifest.layerType) {
+        errors.push('layerType is required');
+    }
+    if (!manifest.asset || typeof manifest.asset !== 'object') {
+        errors.push('asset is required');
+    }
+    if (manifest.asset && !manifest.asset.format) {
+        errors.push('asset.format is required');
+    }
+    if (manifest.asset && (typeof manifest.asset.contentHash !== 'string' || manifest.asset.contentHash.length === 0)) {
+        errors.push('asset.contentHash is required');
+    }
+    if (manifest.asset && manifest.asset.hashAlgorithm !== 'sha3-256') {
+        errors.push('asset.hashAlgorithm must be sha3-256');
+    }
+    if (manifest.asset && manifest.asset.byteSize !== undefined && manifest.asset.byteSize < 0) {
+        errors.push('asset.byteSize must be non-negative');
+    }
+    if (manifest.asset && manifest.asset.merkleRoot !== undefined && !/^[a-f0-9]{64}$/.test(manifest.asset.merkleRoot)) {
+        errors.push('asset.merkleRoot must be 64-char lowercase hex (sha3-256)');
+    }
+    if (manifest.asset && manifest.asset.chunkSizeBytes !== undefined && manifest.asset.chunkSizeBytes <= 0) {
+        errors.push('asset.chunkSizeBytes must be positive');
+    }
+    if (!Number.isFinite(manifest.createdAt) || manifest.createdAt <= 0) {
+        errors.push('createdAt must be finite and positive');
+    }
+    if (manifest.capturedAt !== undefined) {
+        if (!Number.isFinite(manifest.capturedAt) || manifest.capturedAt <= 0) {
+            errors.push('capturedAt must be finite and positive');
+        }
+        else if (manifest.capturedAt > manifest.createdAt + CAPTURE_SKEW_MS) {
+            const allowed = manifest.metadata?.['allowFutureCapture'] === true;
+            if (!allowed) {
+                errors.push('capturedAt is far after createdAt; set metadata.allowFutureCapture = true to allow');
+            }
+            else {
+                warnings.push('capturedAt is far after createdAt (explicitly allowed by metadata.allowFutureCapture)');
+            }
+        }
+    }
+    if (manifest.spatial) {
+        if (manifest.spatial.bounds !== undefined) {
+            const b = manifest.spatial.bounds;
+            if (b.length !== 4) {
+                errors.push('spatial.bounds must be [minLon, minLat, maxLon, maxLat]');
+            }
+            else {
+                const [minLon, minLat, maxLon, maxLat] = b;
+                if (!inLonRange(minLon) || !inLonRange(maxLon)) {
+                    errors.push('spatial.bounds longitudes must be in [-180, 180]');
+                }
+                if (!inLatRange(minLat) || !inLatRange(maxLat)) {
+                    errors.push('spatial.bounds latitudes must be in [-90, 90]');
+                }
+                if (minLon > maxLon)
+                    errors.push('spatial.bounds minLon must be <= maxLon');
+                if (minLat > maxLat)
+                    errors.push('spatial.bounds minLat must be <= maxLat');
+            }
+        }
+        if (manifest.spatial.widthPx !== undefined && (!Number.isInteger(manifest.spatial.widthPx) || manifest.spatial.widthPx <= 0)) {
+            errors.push('spatial.widthPx must be a positive integer');
+        }
+        if (manifest.spatial.heightPx !== undefined && (!Number.isInteger(manifest.spatial.heightPx) || manifest.spatial.heightPx <= 0)) {
+            errors.push('spatial.heightPx must be a positive integer');
+        }
+        if (manifest.spatial.resolutionM !== undefined && (!Number.isFinite(manifest.spatial.resolutionM) || manifest.spatial.resolutionM <= 0)) {
+            errors.push('spatial.resolutionM must be positive');
+        }
+    }
+    if (manifest.sourceType === 'derived') {
+        const derivedFrom = manifest.provenance?.derivedFrom ?? [];
+        if (derivedFrom.length === 0) {
+            warnings.push('derived raster should declare provenance.derivedFrom source raster IDs');
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/**
+ * Convert a RasterManifest into an EvidenceRef for inclusion in a proof.
+ */
+function rasterManifestToEvidenceRef(manifest) {
+    return {
+        id: manifest.rasterId,
+        kind: 'raster-manifest',
+        hash: (0, canonical_js_1.hashRasterManifest)(manifest),
+    };
+}

package/dist/merkle.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Edge-safe Merkle chunking and proof for @totemsdk/raster-proof.
+ *
+ * DOMAIN SEPARATION: chunk content hashes are SHA3-256 of the raw bytes;
+ * Merkle leaves and internal nodes are domain-separated so a chunk hash can
+ * never be confused with a node hash:
+ *   leaf = sha3_256("totem-raster-leaf" + chunk.hash)
+ *   node = sha3_256("totem-raster-node" + left + right)
+ *
+ * ODD-LAYER RULE (deterministic): when a Merkle level has an odd number of
+ * hashes, the last hash is PROMOTED unchanged to the next level (it is NOT
+ * duplicated/hashed with itself). This is the standard RFC 6962-style rule
+ * and keeps the tree compact and deterministic.
+ *
+ * Empty byte arrays are rejected — a raster asset must have bytes.
+ */
+import type { RasterChunk, RasterMerkleOptions, RasterMerkleProof, RasterMerkleSummary } from './types.js';
+export declare const DEFAULT_CHUNK_SIZE_BYTES: number;
+/**
+ * Domain-separated Merkle leaf hash for a chunk. A user proving "this chunk
+ * is in this tree" recomputes merkleLeafHash(chunk) and compares it to
+ * RasterMerkleProof.leafHash before verifying the sibling chain.
+ */
+export declare function merkleLeafHash(chunk: RasterChunk): string;
+/**
+ * Split bytes into fixed-size chunks (default 64 KiB). Each chunk carries a
+ * content hash of its raw bytes. Empty input is rejected.
+ */
+export declare function chunkBytes(bytes: Uint8Array, chunkSizeBytes?: number): RasterChunk[];
+/**
+ * Compute the Merkle root over chunk hashes (deterministic). Odd layers
+ * promote the last hash unchanged.
+ */
+export declare function computeMerkleRoot(chunks: RasterChunk[]): string;
+/**
+ * Build a Merkle inclusion proof for one chunk. The proof's leafHash is the
+ * domain-separated leaf hash of that chunk. Callers can reproduce it with
+ * merkleLeafHash(chunks[leafIndex]).
+ */
+export declare function createMerkleProof(chunks: RasterChunk[], leafIndex: number): RasterMerkleProof;
+/**
+ * Verify a Merkle inclusion proof against its own root. Structural check —
+ * recomputes the root from leafHash + siblings and compares.
+ */
+export declare function verifyMerkleProof(proof: RasterMerkleProof): boolean;
+/**
+ * Hash bytes, chunk them, and summarize in one edge-safe pass.
+ */
+export declare function createRasterMerkleSummary(bytes: Uint8Array, options?: RasterMerkleOptions): RasterMerkleSummary;

package/dist/merkle.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Edge-safe Merkle chunking and proof for @totemsdk/raster-proof.
+ *
+ * DOMAIN SEPARATION: chunk content hashes are SHA3-256 of the raw bytes;
+ * Merkle leaves and internal nodes are domain-separated so a chunk hash can
+ * never be confused with a node hash:
+ *   leaf = sha3_256("totem-raster-leaf" + chunk.hash)
+ *   node = sha3_256("totem-raster-node" + left + right)
+ *
+ * ODD-LAYER RULE (deterministic): when a Merkle level has an odd number of
+ * hashes, the last hash is PROMOTED unchanged to the next level (it is NOT
+ * duplicated/hashed with itself). This is the standard RFC 6962-style rule
+ * and keeps the tree compact and deterministic.
+ *
+ * Empty byte arrays are rejected — a raster asset must have bytes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CHUNK_SIZE_BYTES = void 0;
+exports.merkleLeafHash = merkleLeafHash;
+exports.chunkBytes = chunkBytes;
+exports.computeMerkleRoot = computeMerkleRoot;
+exports.createMerkleProof = createMerkleProof;
+exports.verifyMerkleProof = verifyMerkleProof;
+exports.createRasterMerkleSummary = createRasterMerkleSummary;
+const core_1 = require("@totemsdk/core");
+const canonical_js_1 = require("./canonical.js");
+const hash_js_1 = require("./hash.js");
+const LEAF_PREFIX = 'totem-raster-leaf';
+const NODE_PREFIX = 'totem-raster-node';
+exports.DEFAULT_CHUNK_SIZE_BYTES = 64 * 1024; // 64 KiB
+function domainHash(prefix, a, b) {
+    const encoder = new TextEncoder();
+    const payload = b === undefined ? prefix + a : prefix + a + b;
+    return (0, canonical_js_1.toHex)((0, core_1.sha3_256)(encoder.encode(payload)));
+}
+/**
+ * Domain-separated Merkle leaf hash for a chunk. A user proving "this chunk
+ * is in this tree" recomputes merkleLeafHash(chunk) and compares it to
+ * RasterMerkleProof.leafHash before verifying the sibling chain.
+ */
+function merkleLeafHash(chunk) {
+    return domainHash(LEAF_PREFIX, chunk.hash);
+}
+function merkleNodeHash(left, right) {
+    return domainHash(NODE_PREFIX, left, right);
+}
+/**
+ * Split bytes into fixed-size chunks (default 64 KiB). Each chunk carries a
+ * content hash of its raw bytes. Empty input is rejected.
+ */
+function chunkBytes(bytes, chunkSizeBytes = exports.DEFAULT_CHUNK_SIZE_BYTES) {
+    if (bytes.length === 0) {
+        throw new Error('cannot chunk empty bytes; a raster asset must have content');
+    }
+    if (!Number.isInteger(chunkSizeBytes) || chunkSizeBytes <= 0) {
+        throw new Error('chunk size must be a positive integer');
+    }
+    const chunks = [];
+    for (let offset = 0; offset < bytes.length; offset += chunkSizeBytes) {
+        const length = Math.min(chunkSizeBytes, bytes.length - offset);
+        chunks.push({
+            index: chunks.length,
+            offset,
+            length,
+            hash: (0, hash_js_1.hashBytes)(bytes.subarray(offset, offset + length)),
+        });
+    }
+    return chunks;
+}
+function buildLevels(leafHashes) {
+    const levels = [leafHashes];
+    while (levels[levels.length - 1].length > 1) {
+        const cur = levels[levels.length - 1];
+        const next = [];
+        for (let i = 0; i < cur.length; i += 2) {
+            if (i + 1 < cur.length) {
+                next.push(merkleNodeHash(cur[i], cur[i + 1]));
+            }
+            else {
+                next.push(cur[i]); // promote the odd last hash unchanged
+            }
+        }
+        levels.push(next);
+    }
+    return levels;
+}
+/**
+ * Compute the Merkle root over chunk hashes (deterministic). Odd layers
+ * promote the last hash unchanged.
+ */
+function computeMerkleRoot(chunks) {
+    if (chunks.length === 0) {
+        throw new Error('cannot compute a Merkle root over zero chunks');
+    }
+    const levels = buildLevels(chunks.map((c) => merkleLeafHash(c)));
+    return levels[levels.length - 1][0];
+}
+/**
+ * Build a Merkle inclusion proof for one chunk. The proof's leafHash is the
+ * domain-separated leaf hash of that chunk. Callers can reproduce it with
+ * merkleLeafHash(chunks[leafIndex]).
+ */
+function createMerkleProof(chunks, leafIndex) {
+    if (chunks.length === 0) {
+        throw new Error('cannot create a Merkle proof over zero chunks');
+    }
+    if (!Number.isInteger(leafIndex) || leafIndex < 0 || leafIndex >= chunks.length) {
+        throw new Error(`leafIndex ${leafIndex} out of range [0, ${chunks.length})`);
+    }
+    const levels = buildLevels(chunks.map((c) => merkleLeafHash(c)));
+    const siblings = [];
+    let idx = leafIndex;
+    for (let level = 0; level < levels.length - 1; level++) {
+        const cur = levels[level];
+        const odd = cur.length % 2 === 1;
+        if (odd && idx === cur.length - 1) {
+            // Last element of an odd level is promoted unchanged — no sibling here,
+            // the node itself moves up one level.
+            idx = Math.floor(cur.length / 2);
+            continue;
+        }
+        const siblingIndex = idx % 2 === 0 ? idx + 1 : idx - 1;
+        siblings.push({
+            position: idx % 2 === 0 ? 'right' : 'left',
+            hash: cur[siblingIndex],
+        });
+        idx = Math.floor(idx / 2);
+    }
+    return {
+        root: levels[levels.length - 1][0],
+        leafHash: merkleLeafHash(chunks[leafIndex]),
+        leafIndex,
+        siblings,
+        hashAlgorithm: 'sha3-256',
+    };
+}
+/**
+ * Verify a Merkle inclusion proof against its own root. Structural check —
+ * recomputes the root from leafHash + siblings and compares.
+ */
+function verifyMerkleProof(proof) {
+    if (proof.hashAlgorithm !== 'sha3-256')
+        return false;
+    if (!proof.root || !proof.leafHash || proof.leafIndex < 0)
+        return false;
+    if (!/^[a-f0-9]{64}$/.test(proof.root) || !/^[a-f0-9]{64}$/.test(proof.leafHash))
+        return false;
+    let h = proof.leafHash;
+    for (const sibling of proof.siblings) {
+        if (!/^[a-f0-9]{64}$/.test(sibling.hash))
+            return false;
+        h = sibling.position === 'left' ? merkleNodeHash(sibling.hash, h) : merkleNodeHash(h, sibling.hash);
+    }
+    return h === proof.root;
+}
+/**
+ * Hash bytes, chunk them, and summarize in one edge-safe pass.
+ */
+function createRasterMerkleSummary(bytes, options = {}) {
+    const chunkSizeBytes = options.chunkSizeBytes ?? exports.DEFAULT_CHUNK_SIZE_BYTES;
+    const contentHash = (0, hash_js_1.hashBytes)(bytes);
+    const chunks = chunkBytes(bytes, chunkSizeBytes);
+    return {
+        contentHash,
+        merkleRoot: computeMerkleRoot(chunks),
+        chunkSizeBytes,
+        chunkCount: chunks.length,
+        byteSize: bytes.length,
+    };
+}

package/dist/proof.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Proof envelope integration for @totemsdk/raster-proof.
+ *
+ * Bridges raster manifests, window proofs and Merkle proofs into
+ * @totemsdk/proof evidence refs and signed proof envelopes. Signing and
+ * verification delegate to @totemsdk/proof. Anchoring is deliberately NOT
+ * required for verification.
+ */
+import type { EvidenceRef, SignedProof, UnsignedProof } from '@totemsdk/proof';
+import type { CreateRasterProofParams, RasterManifest, RasterProofVerifyResult, RasterWindowProof } from './types.js';
+/**
+ * Build the evidence ref list for a raster proof:
+ *   - raster manifest hash
+ *   - content hash
+ *   - Merkle root when present
+ *   - window proof hash when present
+ *   - source raster IDs when derived
+ *   - spatial object ID when present
+ */
+export declare function rasterEvidenceRefs(manifest: RasterManifest, windowProof?: RasterWindowProof, spatialObjectId?: string): EvidenceRef[];
+/**
+ * Create an unsigned attestation proof for a raster manifest.
+ *
+ * The proof claims: "this manifest describes this asset, produced by this
+ * source, at this time, with this content hash / Merkle root". It does NOT
+ * claim the visual interpretation is correct — interpretation is an
+ * operator / model / reviewer claim made elsewhere.
+ */
+export declare function createUnsignedRasterProof(params: CreateRasterProofParams): UnsignedProof;
+/**
+ * Sign an unsigned raster proof with a WOTS key.
+ *
+ * The caller is responsible for reserving the WOTS key index (see
+ * @totemsdk/wots-lease) before calling — one-time key warning applies.
+ */
+export declare function signRasterProof(unsigned: UnsignedProof, seed: Uint8Array, keyIndex: number): SignedProof;
+/**
+ * Verify a signed raster proof end to end.
+ *
+ * Checks:
+ *   1. the underlying @totemsdk/proof verification (signature, proofId, expiry)
+ *   2. payload contains a structurally valid RasterManifest
+ *   3. the manifest rasterId matches a recomputation from its fields
+ *   4. the manifest evidence hash matches the payload manifest
+ *   5. content hash and Merkle root evidence refs are present when declared
+ *   6. window proof (when supplied) has a recomputable ID, matches the
+ *      manifest's Merkle root, and any supplied Merkle proofs verify
+ *   7. provenance structure is valid for derived rasters
+ *
+ * Anchoring is not required. Source raster manifests are not supplied inside
+ * the proof, so derivation checks are structural only (full cross-source
+ * verification is @totemsdk/raster-proof's verifyRasterDerivation).
+ */
+export declare function verifyRasterProof(signed: SignedProof): RasterProofVerifyResult;