@fide.work/fcp 0.0.1-alpha.0

package/dist/experimental/attestation/verify.js

@@ -0,0 +1,94 @@
+/**
+ * FCP SDK Attestation Verification Utilities
+ *
+ * Full verification functions that combine Merkle proof and signature verification.
+ */
+import { verifyStatementInAttestation, parseAttestationData } from "./create.js";
+import { verifyEd25519 } from "../signing/ed25519.js";
+import { verifyEip712 } from "../signing/eip712.js";
+import { verifyEip191 } from "../signing/eip191.js";
+/**
+ * Verify a complete attestation (both Merkle proof and signature)
+ *
+ * This function performs full verification:
+ * 1. Verifies the Merkle proof (statement is in the batch)
+ * 2. Verifies the signature (signer authorized the batch)
+ *
+ * @param statementFideId - The leaf value to verify in Merkle tree
+ * @param proof - The Merkle proof path (array of hashes from leaf to root)
+ * @param attestationData - The attestation data structure
+ * @param options - Configuration options for operation (method, public key/address, etc.)
+ * @returns True if both Merkle proof and signature are valid
+ *
+ * @example
+ * ```ts
+ * // With Ed25519
+ * const isValid = await verifyAttestation(
+ *   statementFideId,
+ *   proof,
+ *   attestationData,
+ *   {
+ *     method: 'ed25519',
+ *     publicKeyOrAddress: publicKey
+ *   }
+ * );
+ *
+ * // With EIP-712
+ * const isValid = await verifyAttestation(
+ *   statementFideId,
+ *   proof,
+ *   attestationData,
+ *   {
+ *     method: 'eip712',
+ *     publicKeyOrAddress: address
+ *   }
+ * );
+ * ```
+ */
+export async function verifyAttestation(statementFideId, proof, attestationData, options) {
+    // Parse attestation data if it's a string
+    const data = typeof attestationData === 'string'
+        ? parseAttestationData(attestationData)
+        : attestationData;
+    // 1. Verify Merkle proof
+    const merkleValid = await verifyStatementInAttestation(statementFideId, proof, data);
+    if (!merkleValid) {
+        return false;
+    }
+    // 2. Verify signature based on method
+    let signatureValid = false;
+    if (options.method === 'ed25519') {
+        if (typeof options.publicKeyOrAddress === 'string') {
+            throw new Error('Ed25519 verification requires a CryptoKey, not an address string');
+        }
+        signatureValid = await verifyEd25519(data.r, // merkle root
+        data.s, // signature
+        options.publicKeyOrAddress);
+    }
+    else if (options.method === 'eip712') {
+        if (typeof options.publicKeyOrAddress !== 'string') {
+            throw new Error('EIP-712 verification requires an address string, not a CryptoKey');
+        }
+        if (!data.s.startsWith('0x')) {
+            throw new Error('EIP-712 signature must be hex-encoded (0x prefix)');
+        }
+        signatureValid = await verifyEip712(data.r, // merkle root
+        data.s, // signature
+        options.publicKeyOrAddress);
+    }
+    else if (options.method === 'eip191') {
+        if (typeof options.publicKeyOrAddress !== 'string') {
+            throw new Error('EIP-191 verification requires an address string, not a CryptoKey');
+        }
+        if (!data.s.startsWith('0x')) {
+            throw new Error('EIP-191 signature must be hex-encoded (0x prefix)');
+        }
+        signatureValid = await verifyEip191(data.r, // merkle root
+        data.s, // signature
+        options.publicKeyOrAddress);
+    }
+    else {
+        throw new Error(`Unsupported signing method: ${options.method}`);
+    }
+    return signatureValid;
+}

package/dist/experimental/broadcasting/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * FCP Registry Configuration
+ *
+ * Allows registries to specify where attestations are located
+ * and other registry metadata.
+ */
+export interface FCPRegistryConfig {
+    /** Path to attestations directory (relative to repo root) */
+    attestationsPath?: string;
+    /** Optional registry metadata */
+    metadata?: {
+        name?: string;
+        description?: string;
+    };
+}
+/**
+ * Default attestation paths to check if no config file exists
+ */
+export declare const DEFAULT_ATTESTATION_PATHS: string[];
+/**
+ * Default attestations path (used when generating paths)
+ */
+export declare const DEFAULT_ATTESTATIONS_PATH = "attestations";
+/**
+ * Registry config filename
+ */
+export declare const REGISTRY_CONFIG_FILENAME = ".fcp-registry.json";

package/dist/experimental/broadcasting/config.js

@@ -0,0 +1,22 @@
+/**
+ * FCP Registry Configuration
+ *
+ * Allows registries to specify where attestations are located
+ * and other registry metadata.
+ */
+/**
+ * Default attestation paths to check if no config file exists
+ */
+export const DEFAULT_ATTESTATION_PATHS = [
+    'attestations',
+    'fcp-attestations',
+    '.fcp/attestations'
+];
+/**
+ * Default attestations path (used when generating paths)
+ */
+export const DEFAULT_ATTESTATIONS_PATH = 'attestations';
+/**
+ * Registry config filename
+ */
+export const REGISTRY_CONFIG_FILENAME = '.fcp-registry.json';

package/dist/experimental/broadcasting/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * FCP SDK - Broadcasting Module
+ *
+ * Re-exports all broadcasting utilities.
+ */
+export { formatAttestationForJSONL, generateRegistryPath, generateJSONLFilename, type JSONLAttestation, type JSONLStatement } from "./registry.js";
+export { DEFAULT_ATTESTATION_PATHS, DEFAULT_ATTESTATIONS_PATH, REGISTRY_CONFIG_FILENAME, type FCPRegistryConfig } from "./config.js";

package/dist/experimental/broadcasting/index.js

@@ -0,0 +1,7 @@
+/**
+ * FCP SDK - Broadcasting Module
+ *
+ * Re-exports all broadcasting utilities.
+ */
+export { formatAttestationForJSONL, generateRegistryPath, generateJSONLFilename } from "./registry.js";
+export { DEFAULT_ATTESTATION_PATHS, DEFAULT_ATTESTATIONS_PATH, REGISTRY_CONFIG_FILENAME } from "./config.js";

package/dist/experimental/broadcasting/registry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * FCP SDK Broadcasting Utilities
+ *
+ * Helpers for formatting attestations for JSONL registry files.
+ *
+ * Note: This module provides formatting helpers. Actual Git operations
+ * (commit, push) should be handled by your application using libraries
+ * like `simple-git` or `isomorphic-git`.
+ */
+import type { AttestationResult } from "../attestation/index.js";
+import type { Statement } from "../../statement/build.js";
+/**
+ * Statement object in lean JSONL format
+ * Uses short keys for efficiency: s/sr, p/pr, o/or
+ */
+export interface JSONLStatement {
+    /** Subject Fide ID (full did:fide:0x... format) */
+    s: string;
+    /** Subject raw identifier */
+    sr: string;
+    /** Predicate Fide ID (full did:fide:0x... format) */
+    p: string;
+    /** Predicate raw identifier */
+    pr: string;
+    /** Object Fide ID (full did:fide:0x... format) */
+    o: string;
+    /** Object raw identifier */
+    or: string;
+}
+/**
+ * Lean attestation format for JSONL registry files
+ *
+ * Optimized for indexers: minimal verbosity, all data needed for verification
+ * and materialization. Each line is one attestation batch.
+ *
+ * Format matches canonical attestation data structure: {m, r, s, u}
+ * Indexer derives attestation Fide ID from these fields.
+ */
+export interface JSONLAttestation {
+    /** Method: Signing method (e.g., "ed25519", "eip712", "eip191") */
+    m: string;
+    /** User: CAIP-10 signer identifier */
+    u: string;
+    /** Root: Merkle root commitment */
+    r: string;
+    /** Signature: Cryptographic signature */
+    s: string;
+    /** Timestamp: ISO 8601 UTC timestamp */
+    t: string;
+    /** Data: Array of statements in this batch */
+    d: JSONLStatement[];
+}
+/**
+ * Format an attestation result for JSONL output
+ *
+ * Converts an AttestationResult into the lean JSONL format optimized for indexers.
+ * Each line in the JSONL file should be one attestation batch (one signature covering
+ * multiple statements via Merkle root).
+ *
+ * Format uses short keys (m, u, r, s, t, d) matching the canonical attestation
+ * data structure. Indexer derives attestation Fide ID from {m, r, s, u}.
+ *
+ * @param attestationResult - The result from createAttestation
+ * @param statements - The original statements that were attested (must match statementFideIds order)
+ * @param signedAt - ISO timestamp when the attestation was signed (defaults to current time)
+ * @returns Formatted attestation ready for JSONL output
+ *
+ * @example
+ * ```ts
+ * const { statements } = await batchStatementsWithRoot([...]);
+ * const attestation = await createAttestation(statementFideIds, options);
+ * const jsonlAttestation = formatAttestationForJSONL(attestation, statements);
+ *
+ * // Write to JSONL file (one line per batch)
+ * fs.appendFileSync('attestation.jsonl', JSON.stringify(jsonlAttestation) + '\n');
+ * ```
+ */
+export declare function formatAttestationForJSONL(attestationResult: AttestationResult, statements: Statement[], signedAt?: string): JSONLAttestation;
+/**
+ * Generate the registry directory path for a given date
+ *
+ * Follows the YYYY/MM/DD structure required for Fide attestation registries.
+ * Uses UTC timezone for consistency across timezones.
+ *
+ * @param date - Date object (defaults to current UTC date)
+ * @returns Directory path (e.g., "2024/01/15")
+ *
+ * @example
+ * ```ts
+ * const path = generateRegistryPath(new Date('2024-01-15T00:00:00Z'));
+ * // Result: "2024/01/15"
+ * ```
+ */
+export declare function generateRegistryPath(date?: Date): string;
+/**
+ * Generate a JSONL filename following the registry convention
+ *
+ * Format: YYYY-MM-DD-{HHmm}-{sequence}.jsonl
+ * Uses UTC timezone for consistency across timezones.
+ *
+ * @param date - Date object (defaults to current UTC date)
+ * @param sequence - Sequence number (defaults to 1)
+ * @returns Filename (e.g., "2024-01-15-1400-1.jsonl")
+ *
+ * @example
+ * ```ts
+ * const filename = generateJSONLFilename(new Date('2024-01-15T14:00:00Z'), 1);
+ * // Result: "2024-01-15-1400-1.jsonl"
+ * ```
+ */
+export declare function generateJSONLFilename(date?: Date, sequence?: number): string;

package/dist/experimental/broadcasting/registry.js

@@ -0,0 +1,99 @@
+/**
+ * FCP SDK Broadcasting Utilities
+ *
+ * Helpers for formatting attestations for JSONL registry files.
+ *
+ * Note: This module provides formatting helpers. Actual Git operations
+ * (commit, push) should be handled by your application using libraries
+ * like `simple-git` or `isomorphic-git`.
+ */
+/**
+ * Format an attestation result for JSONL output
+ *
+ * Converts an AttestationResult into the lean JSONL format optimized for indexers.
+ * Each line in the JSONL file should be one attestation batch (one signature covering
+ * multiple statements via Merkle root).
+ *
+ * Format uses short keys (m, u, r, s, t, d) matching the canonical attestation
+ * data structure. Indexer derives attestation Fide ID from {m, r, s, u}.
+ *
+ * @param attestationResult - The result from createAttestation
+ * @param statements - The original statements that were attested (must match statementFideIds order)
+ * @param signedAt - ISO timestamp when the attestation was signed (defaults to current time)
+ * @returns Formatted attestation ready for JSONL output
+ *
+ * @example
+ * ```ts
+ * const { statements } = await batchStatementsWithRoot([...]);
+ * const attestation = await createAttestation(statementFideIds, options);
+ * const jsonlAttestation = formatAttestationForJSONL(attestation, statements);
+ *
+ * // Write to JSONL file (one line per batch)
+ * fs.appendFileSync('attestation.jsonl', JSON.stringify(jsonlAttestation) + '\n');
+ * ```
+ */
+export function formatAttestationForJSONL(attestationResult, statements, signedAt = new Date().toISOString()) {
+    // Convert statements to lean JSONL format with short keys
+    const jsonlStatements = statements.map(stmt => ({
+        s: stmt.subjectFideId,
+        sr: stmt.subjectRawIdentifier,
+        p: stmt.predicateFideId,
+        pr: stmt.predicateRawIdentifier,
+        o: stmt.objectFideId,
+        or: stmt.objectRawIdentifier
+    }));
+    return {
+        m: attestationResult.attestationData.m,
+        u: attestationResult.attestationData.u,
+        r: attestationResult.merkleRoot,
+        s: attestationResult.attestationData.s,
+        t: signedAt,
+        d: jsonlStatements
+    };
+}
+/**
+ * Generate the registry directory path for a given date
+ *
+ * Follows the YYYY/MM/DD structure required for Fide attestation registries.
+ * Uses UTC timezone for consistency across timezones.
+ *
+ * @param date - Date object (defaults to current UTC date)
+ * @returns Directory path (e.g., "2024/01/15")
+ *
+ * @example
+ * ```ts
+ * const path = generateRegistryPath(new Date('2024-01-15T00:00:00Z'));
+ * // Result: "2024/01/15"
+ * ```
+ */
+export function generateRegistryPath(date = new Date()) {
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    return `${year}/${month}/${day}`;
+}
+/**
+ * Generate a JSONL filename following the registry convention
+ *
+ * Format: YYYY-MM-DD-{HHmm}-{sequence}.jsonl
+ * Uses UTC timezone for consistency across timezones.
+ *
+ * @param date - Date object (defaults to current UTC date)
+ * @param sequence - Sequence number (defaults to 1)
+ * @returns Filename (e.g., "2024-01-15-1400-1.jsonl")
+ *
+ * @example
+ * ```ts
+ * const filename = generateJSONLFilename(new Date('2024-01-15T14:00:00Z'), 1);
+ * // Result: "2024-01-15-1400-1.jsonl"
+ * ```
+ */
+export function generateJSONLFilename(date = new Date(), sequence = 1) {
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    const hours = String(date.getUTCHours()).padStart(2, '0');
+    const minutes = String(date.getUTCMinutes()).padStart(2, '0');
+    const timeWindow = `${hours}${minutes}`;
+    return `${year}-${month}-${day}-${timeWindow}-${sequence}.jsonl`;
+}

package/dist/experimental/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fide.work/fcp experimental helpers
+ *
+ * These APIs are intentionally non-core and may change.
+ */
+export { generateEd25519KeyPair, exportEd25519Keys, importEd25519Keys, signEd25519, verifyEd25519, getEthereumAddress, signEip712, verifyEip712, createEthereumCaip10, FCP_EIP712_DOMAIN, signEip191, verifyEip191, type Ed25519KeyPair, type ExportedEd25519Keys, type Eip712Domain, } from "./signing/index.js";
+export { buildMerkleTree, verifyMerkleProof, type MerkleProofElement, type MerkleProof, type MerkleTreeResult, } from "./merkle/index.js";
+export { createAttestation, createProvenanceStatements, verifyStatementInAttestation, verifyAttestation, parseAttestationData, verifyAttestationFideId, type SigningMethod, type AttestationData, type AttestationResult, type CreateAttestationOptions, type ProvenanceStatement, type VerifyAttestationOptions, } from "./attestation/index.js";
+export { formatAttestationForJSONL, generateRegistryPath, generateJSONLFilename, DEFAULT_ATTESTATION_PATHS, DEFAULT_ATTESTATIONS_PATH, REGISTRY_CONFIG_FILENAME, type JSONLAttestation, type JSONLStatement, type FCPRegistryConfig, } from "./broadcasting/index.js";

package/dist/experimental/index.js

@@ -0,0 +1,13 @@
+/**
+ * @fide.work/fcp experimental helpers
+ *
+ * These APIs are intentionally non-core and may change.
+ */
+// Signing helpers
+export { generateEd25519KeyPair, exportEd25519Keys, importEd25519Keys, signEd25519, verifyEd25519, getEthereumAddress, signEip712, verifyEip712, createEthereumCaip10, FCP_EIP712_DOMAIN, signEip191, verifyEip191, } from "./signing/index.js";
+// Merkle helpers
+export { buildMerkleTree, verifyMerkleProof, } from "./merkle/index.js";
+// Attestation helpers
+export { createAttestation, createProvenanceStatements, verifyStatementInAttestation, verifyAttestation, parseAttestationData, verifyAttestationFideId, } from "./attestation/index.js";
+// Broadcasting helpers
+export { formatAttestationForJSONL, generateRegistryPath, generateJSONLFilename, DEFAULT_ATTESTATION_PATHS, DEFAULT_ATTESTATIONS_PATH, REGISTRY_CONFIG_FILENAME, } from "./broadcasting/index.js";

package/dist/experimental/merkle/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * FCP SDK - Merkle Tree Module
+ *
+ * Re-exports all Merkle tree utilities.
+ */
+export { buildMerkleTree, verifyMerkleProof, type MerkleProofElement, type MerkleProof, type MerkleTreeResult } from "./tree.js";

package/dist/experimental/merkle/index.js

@@ -0,0 +1,6 @@
+/**
+ * FCP SDK - Merkle Tree Module
+ *
+ * Re-exports all Merkle tree utilities.
+ */
+export { buildMerkleTree, verifyMerkleProof } from "./tree.js";

package/dist/experimental/merkle/tree.d.ts

@@ -0,0 +1,72 @@
+/**
+ * FCP SDK Merkle Tree Utilities
+ * Build and verify Merkle trees for batch attestations
+ *
+ * Uses SHA-256 for hashing (same as Fide ID derivation).
+ * Zero external dependencies - uses native Web Crypto API.
+ */
+/**
+ * Merkle proof element
+ */
+export interface MerkleProofElement {
+    /** The sibling hash at this level */
+    hash: string;
+    /** Position of the sibling: 'left' or 'right' */
+    position: 'left' | 'right';
+}
+/**
+ * Merkle proof for a specific leaf
+ */
+export type MerkleProof = MerkleProofElement[];
+/**
+ * Result from building a Merkle tree
+ */
+export interface MerkleTreeResult {
+    /** The Merkle root (hex string) */
+    root: string;
+    /** Proofs for each leaf, indexed by leaf value */
+    proofs: Map<string, MerkleProof>;
+    /** The leaves used to build the tree (normalized) */
+    leaves: string[];
+}
+/**
+ * Build a Merkle tree from an array of Fide IDs
+ *
+ * The tree is built bottom-up by iteratively hashing pairs of nodes.
+ * If there's an odd number of nodes, the last node is duplicated.
+ *
+ * @param leaves - Array of statement Fide IDs to include in the tree
+ * @returns MerkleTreeResult with root and proofs for each leaf
+ * @throws Error if leaves array is empty
+ *
+ * @example
+ * ```ts
+ * const result = await buildMerkleTree([
+ *   'did:fide:0x00abc...',
+ *   'did:fide:0x00def...',
+ *   'did:fide:0x00ghi...'
+ * ]);
+ *
+ * console.log('Root:', result.root);
+ * console.log('Proof for first leaf:', result.proofs.get('did:fide:0x00abc...'));
+ * ```
+ */
+export declare function buildMerkleTree(leaves: string[]): Promise<MerkleTreeResult>;
+/**
+ * Verify that a leaf is part of a Merkle tree given its proof
+ *
+ * @param leaf - The leaf value to verify in Merkle tree
+ * @param proof - The Merkle proof path (array of hashes from leaf to root)
+ * @param root - The Merkle tree root hash (0x-prefixed hex)
+ * @returns True if the proof is valid
+ *
+ * @example
+ * ```ts
+ * const isValid = await verifyMerkleProof(
+ *   'did:fide:0x00abc...',
+ *   proof,
+ *   root
+ * );
+ * ```
+ */
+export declare function verifyMerkleProof(leaf: string, proof: MerkleProof, root: string): Promise<boolean>;

package/dist/experimental/merkle/tree.js

@@ -0,0 +1,154 @@
+/**
+ * FCP SDK Merkle Tree Utilities
+ * Build and verify Merkle trees for batch attestations
+ *
+ * Uses SHA-256 for hashing (same as Fide ID derivation).
+ * Zero external dependencies - uses native Web Crypto API.
+ */
+/**
+ * Get the Web Crypto API (works in browsers and Node.js)
+ */
+async function getSubtleCrypto() {
+    if (globalThis.crypto?.subtle) {
+        return globalThis.crypto.subtle;
+    }
+    const { webcrypto } = await import("node:crypto");
+    return webcrypto.subtle;
+}
+/**
+ * Hash two values together using SHA-256
+ * Sorts inputs to ensure consistent ordering
+ */
+async function hashPair(left, right) {
+    const subtle = await getSubtleCrypto();
+    // Concatenate left + right (already sorted at construction time)
+    const combined = left + right;
+    const encoder = new TextEncoder();
+    const data = encoder.encode(combined);
+    const hashBuffer = await subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Normalize a Fide ID to a consistent hex format for hashing
+ * Accepts: "did:fide:0x..." or "0x..."
+ * Returns: lowercase hex without prefix
+ */
+function normalizeLeaf(fideId) {
+    const trimmed = fideId.trim().toLowerCase();
+    if (trimmed.startsWith('did:fide:0x')) {
+        return trimmed.slice('did:fide:0x'.length);
+    }
+    if (trimmed.startsWith('0x')) {
+        return trimmed.slice(2);
+    }
+    return trimmed;
+}
+/**
+ * Build a Merkle tree from an array of Fide IDs
+ *
+ * The tree is built bottom-up by iteratively hashing pairs of nodes.
+ * If there's an odd number of nodes, the last node is duplicated.
+ *
+ * @param leaves - Array of statement Fide IDs to include in the tree
+ * @returns MerkleTreeResult with root and proofs for each leaf
+ * @throws Error if leaves array is empty
+ *
+ * @example
+ * ```ts
+ * const result = await buildMerkleTree([
+ *   'did:fide:0x00abc...',
+ *   'did:fide:0x00def...',
+ *   'did:fide:0x00ghi...'
+ * ]);
+ *
+ * console.log('Root:', result.root);
+ * console.log('Proof for first leaf:', result.proofs.get('did:fide:0x00abc...'));
+ * ```
+ */
+export async function buildMerkleTree(leaves) {
+    if (leaves.length === 0) {
+        throw new Error('Cannot build Merkle tree from empty array');
+    }
+    // Normalize all leaves
+    const normalizedLeaves = leaves.map(normalizeLeaf);
+    // Initialize proofs map (keyed by original leaf value)
+    const proofs = new Map();
+    leaves.forEach(leaf => proofs.set(leaf, []));
+    // Also map normalized → original for lookup
+    const normalizedToOriginal = new Map();
+    leaves.forEach((original, i) => {
+        normalizedToOriginal.set(normalizedLeaves[i], original);
+    });
+    // Build tree level by level
+    let currentLevel = [...normalizedLeaves];
+    // Track which original leaves each node represents
+    // At level 0, each node represents itself
+    let nodeToLeaves = new Map();
+    normalizedLeaves.forEach(leaf => nodeToLeaves.set(leaf, [leaf]));
+    while (currentLevel.length > 1) {
+        const nextLevel = [];
+        const nextNodeToLeaves = new Map();
+        for (let i = 0; i < currentLevel.length; i += 2) {
+            const left = currentLevel[i];
+            const right = i + 1 < currentLevel.length ? currentLevel[i + 1] : left; // Duplicate if odd
+            const parent = await hashPair(left, right);
+            nextLevel.push(parent);
+            // Track which leaves this parent represents
+            const leftLeaves = nodeToLeaves.get(left) || [];
+            const rightLeaves = nodeToLeaves.get(right) || [];
+            nextNodeToLeaves.set(parent, [...leftLeaves, ...rightLeaves]);
+            // Add proof elements for all leaves on each side
+            // Leaves on the left get right sibling, leaves on the right get left sibling
+            for (const leafNorm of leftLeaves) {
+                const original = normalizedToOriginal.get(leafNorm);
+                const proof = proofs.get(original);
+                proof.push({ hash: right, position: 'right' });
+            }
+            // Only add if right != left (not a duplicate)
+            if (left !== right) {
+                for (const leafNorm of rightLeaves) {
+                    const original = normalizedToOriginal.get(leafNorm);
+                    const proof = proofs.get(original);
+                    proof.push({ hash: left, position: 'left' });
+                }
+            }
+        }
+        currentLevel = nextLevel;
+        nodeToLeaves = nextNodeToLeaves;
+    }
+    return {
+        root: currentLevel[0],
+        proofs,
+        leaves
+    };
+}
+/**
+ * Verify that a leaf is part of a Merkle tree given its proof
+ *
+ * @param leaf - The leaf value to verify in Merkle tree
+ * @param proof - The Merkle proof path (array of hashes from leaf to root)
+ * @param root - The Merkle tree root hash (0x-prefixed hex)
+ * @returns True if the proof is valid
+ *
+ * @example
+ * ```ts
+ * const isValid = await verifyMerkleProof(
+ *   'did:fide:0x00abc...',
+ *   proof,
+ *   root
+ * );
+ * ```
+ */
+export async function verifyMerkleProof(leaf, proof, root) {
+    let currentHash = normalizeLeaf(leaf);
+    for (const element of proof) {
+        if (element.position === 'left') {
+            currentHash = await hashPair(element.hash, currentHash);
+        }
+        else {
+            currentHash = await hashPair(currentHash, element.hash);
+        }
+    }
+    return currentHash === root;
+}