@fide.work/fcp 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,18 @@
+# `@fide.work/fcp`
+
+SDK docs: [https://fide.work/fcp/docs/sdks/js/](https://fide.work/fcp/docs/sdks/js/)
+
+## Scripts
+
+- `pnpm run build`
+- `pnpm test`
+- `pnpm run test:verbose`
+- `pnpm run example`
+- `pnpm run example:fide-id`
+- `pnpm run example:statement`
+- `pnpm run example:schema`
+
+## Predicate Format
+
+Predicates must use canonical full URLs (for example, `https://schema.org/name`).
+Shorthand identifiers such as `schema:name` and `schema.org/name` are rejected.

package/dist/attestation/create.d.ts

@@ -0,0 +1,173 @@
+/**
+ * FCP SDK Attestation Utilities
+ *
+ * High-level helpers for creating and verifying attestations.
+ * Combines Fide ID calculation, Merkle trees, and signing.
+ */
+import type { FideId } from "../fide-id/types.js";
+import { type MerkleProof } from "../merkle/index.js";
+/**
+ * Signing method identifier
+ *
+ * `ed25519` has no external dependency.
+ * `eip712` and `eip191` require the optional `viem` peer dependency.
+ */
+export type SigningMethod = 'ed25519' | 'eip712' | 'eip191';
+/**
+ * Attestation data structure (baked into Fide ID)
+ * Uses short keys to match protocol: m, u, r, s
+ */
+export interface AttestationData {
+    /** Method: Signing standard used */
+    m: SigningMethod;
+    /** User: CAIP-10 signer identifier */
+    u: string;
+    /** Root: Merkle tree commitment */
+    r: string;
+    /** Signature: Cryptographic proof */
+    s: string;
+}
+/**
+ * Full attestation result
+ */
+export interface AttestationResult {
+    /** The Attestation Fide ID */
+    attestationFideId: FideId;
+    /** The raw attestation data */
+    attestationData: AttestationData;
+    /** The normalized JSON string (raw identifier) */
+    rawIdentifier: string;
+    /** The Merkle root */
+    merkleRoot: string;
+    /** Proofs for each statement, keyed by statement Fide ID */
+    proofs: Map<string, MerkleProof>;
+}
+/**
+ * Options for creating an attestation
+ */
+export interface CreateAttestationOptions {
+    /** The signing method to use (`eip712`/`eip191` require `viem` to be installed). */
+    method: SigningMethod;
+    /** CAIP-10 identifier for the signer (e.g., "eip155:1:0x...") */
+    caip10User: string;
+    /** Signing function - takes merkle root string, returns signature hex string */
+    sign: (merkleRoot: string) => Promise<string>;
+}
+/**
+ * Provenance statement linking a statement to its attestation
+ */
+export interface ProvenanceStatement {
+    subjectFideId: string;
+    predicateFideId: string;
+    objectFideId: string;
+    predicateRawIdentifier: string;
+    objectRawIdentifier: string;
+}
+/**
+ * Create an attestation for a batch of statement Fide IDs
+ *
+ * This function:
+ * 1. Builds a Merkle tree from the statement Fide IDs
+ * 2. Signs the Merkle root using the provided signing function
+ * 3. Creates the attestation data structure
+ * 4. Derives the Attestation Fide ID
+ *
+ * @param statementFideIds - Array of statement Fide IDs.
+ * @param options - Configuration options for operation.
+ * @paramDefault statementFideIds ["did:fide:0x10...", "did:fide:0x10..."]
+ * @paramDefault options {"method":"ed25519","caip10User":"ed25519:123...","sign":"async (root) => 'signature'"}
+ * @returns Full attestation result including ID, data, and proofs
+ *
+ * @example
+ * ```ts
+ * import { createAttestation, signEd25519 } from '@fide.work/fcp';
+ *
+ * const result = await createAttestation(
+ *   [statement1FideId, statement2FideId],
+ *   {
+ *     method: 'ed25519',
+ *     caip10User: 'ed25519::abc123...',
+ *     sign: (root) => signEd25519(root, privateKey)
+ *   }
+ * );
+ *
+ * console.log('Attestation ID:', result.attestationFideId);
+ * ```
+ */
+export declare function createAttestation(statementFideIds: string[], options: CreateAttestationOptions): Promise<AttestationResult>;
+/**
+ * Create provenance statements linking each statement to the attestation
+ *
+ * These are the "Statement → prov:wasGeneratedBy → Attestation" triples
+ * that connect content statements to their attestation.
+ *
+ * @param statementFideIds - Array of statement Fide IDs to include in attestation
+ * @param attestationResult - The attestation data structure
+ * @returns Array of provenance statements to publish
+ *
+ * @example
+ * ```ts
+ * const provenance = await createProvenanceStatements(
+ *   statementFideIds,
+ *   attestationResult
+ * );
+ * // Each provenance statement links a content statement to the attestation
+ * ```
+ */
+export declare function createProvenanceStatements(statementFideIds: string[], attestationResult: AttestationResult): Promise<ProvenanceStatement[]>;
+/**
+ * Verify that a statement is part of an attestation
+ *
+ * This verifies the Merkle proof but does NOT verify the signature.
+ * Signature verification depends on the signing method and should
+ * be done separately using verifyEd25519 or verifyEip712.
+ *
+ * @param statementFideId - The leaf value to verify.
+ * @param proof - The Merkle proof path.
+ * @param attestationData - The attestation data.
+ * @paramDefault statementFideId did:fide:0x10...
+ * @paramDefault proof ["hash1", "hash2"]
+ * @paramDefault attestationData {"r":"root-hash"}
+ * @returns True if the statement is in the attestation
+ *
+ * @example
+ * ```ts
+ * const isInBatch = await verifyStatementInAttestation(
+ *   statementFideId,
+ *   proof,
+ *   attestationData
+ * );
+ * ```
+ */
+export declare function verifyStatementInAttestation(statementFideId: string, proof: MerkleProof, attestationData: AttestationData | {
+    r: string;
+}): Promise<boolean>;
+/**
+ * Parse attestation data from a raw identifier string
+ *
+ * @param rawIdentifier - The JSON string from objectRawIdentifier
+ * @returns Parsed attestation data
+ * @throws Error if JSON is invalid
+ *
+ * @example
+ * ```ts
+ * const attestationData = parseAttestationData(provenanceStatement.objectRawIdentifier);
+ * ```
+ */
+export declare function parseAttestationData(rawIdentifier: string): AttestationData;
+/**
+ * Verify that an attestation's Fide ID is correctly derived
+ *
+ * @param attestationFideId - The claimed attestation Fide ID
+ * @param rawIdentifier - The raw identifier JSON string
+ * @returns True if the Fide ID is correctly derived
+ *
+ * @example
+ * ```ts
+ * const isValidId = await verifyAttestationFideId(
+ *   provenanceStatement.objectFideId,
+ *   provenanceStatement.objectRawIdentifier
+ * );
+ * ```
+ */
+export declare function verifyAttestationFideId(attestationFideId: string, rawIdentifier: string): Promise<boolean>;

package/dist/attestation/create.js

@@ -0,0 +1,179 @@
+/**
+ * FCP SDK Attestation Utilities
+ *
+ * High-level helpers for creating and verifying attestations.
+ * Combines Fide ID calculation, Merkle trees, and signing.
+ */
+import { calculateFideId } from "../fide-id/index.js";
+import { buildMerkleTree, verifyMerkleProof } from "../merkle/index.js";
+// ============================================================================
+// ATTESTATION CREATION
+// ============================================================================
+/**
+ * Create an attestation for a batch of statement Fide IDs
+ *
+ * This function:
+ * 1. Builds a Merkle tree from the statement Fide IDs
+ * 2. Signs the Merkle root using the provided signing function
+ * 3. Creates the attestation data structure
+ * 4. Derives the Attestation Fide ID
+ *
+ * @param statementFideIds - Array of statement Fide IDs.
+ * @param options - Configuration options for operation.
+ * @paramDefault statementFideIds ["did:fide:0x10...", "did:fide:0x10..."]
+ * @paramDefault options {"method":"ed25519","caip10User":"ed25519:123...","sign":"async (root) => 'signature'"}
+ * @returns Full attestation result including ID, data, and proofs
+ *
+ * @example
+ * ```ts
+ * import { createAttestation, signEd25519 } from '@fide.work/fcp';
+ *
+ * const result = await createAttestation(
+ *   [statement1FideId, statement2FideId],
+ *   {
+ *     method: 'ed25519',
+ *     caip10User: 'ed25519::abc123...',
+ *     sign: (root) => signEd25519(root, privateKey)
+ *   }
+ * );
+ *
+ * console.log('Attestation ID:', result.attestationFideId);
+ * ```
+ */
+export async function createAttestation(statementFideIds, options) {
+    if (statementFideIds.length === 0) {
+        throw new Error('Cannot create attestation from empty statement list');
+    }
+    // 1. Build Merkle tree
+    const merkleResult = await buildMerkleTree(statementFideIds);
+    const merkleRoot = merkleResult.root;
+    // 2. Sign the Merkle root
+    const signature = await options.sign(merkleRoot);
+    // 3. Create attestation data (with short keys, alphabetically ordered)
+    const attestationData = {
+        m: options.method,
+        r: merkleRoot,
+        s: signature,
+        u: options.caip10User
+    };
+    // 4. Create normalized JSON string (alphabetically ordered for determinism)
+    // IMPORTANT: Keys MUST be in alphabetical order (m, r, s, u) for deterministic hashing
+    const rawIdentifier = JSON.stringify({
+        m: attestationData.m,
+        r: attestationData.r,
+        s: attestationData.s,
+        u: attestationData.u
+    });
+    // 5. Derive Attestation Fide ID
+    const attestationFideId = await calculateFideId('Attestation', 'Attestation', rawIdentifier);
+    return {
+        attestationFideId,
+        attestationData,
+        rawIdentifier,
+        merkleRoot,
+        proofs: merkleResult.proofs
+    };
+}
+/**
+ * Create provenance statements linking each statement to the attestation
+ *
+ * These are the "Statement → prov:wasGeneratedBy → Attestation" triples
+ * that connect content statements to their attestation.
+ *
+ * @param statementFideIds - Array of statement Fide IDs to include in attestation
+ * @param attestationResult - The attestation data structure
+ * @returns Array of provenance statements to publish
+ *
+ * @example
+ * ```ts
+ * const provenance = await createProvenanceStatements(
+ *   statementFideIds,
+ *   attestationResult
+ * );
+ * // Each provenance statement links a content statement to the attestation
+ * ```
+ */
+export async function createProvenanceStatements(statementFideIds, attestationResult) {
+    // Get the prov:wasGeneratedBy predicate ID
+    const wasGeneratedByPredicateId = await calculateFideId('CreativeWork', 'CreativeWork', 'prov:wasGeneratedBy');
+    return statementFideIds.map(statementFideId => ({
+        subjectFideId: statementFideId,
+        predicateFideId: wasGeneratedByPredicateId,
+        objectFideId: attestationResult.attestationFideId,
+        predicateRawIdentifier: 'prov:wasGeneratedBy',
+        objectRawIdentifier: attestationResult.rawIdentifier
+    }));
+}
+// ============================================================================
+// ATTESTATION VERIFICATION
+// ============================================================================
+/**
+ * Verify that a statement is part of an attestation
+ *
+ * This verifies the Merkle proof but does NOT verify the signature.
+ * Signature verification depends on the signing method and should
+ * be done separately using verifyEd25519 or verifyEip712.
+ *
+ * @param statementFideId - The leaf value to verify.
+ * @param proof - The Merkle proof path.
+ * @param attestationData - The attestation data.
+ * @paramDefault statementFideId did:fide:0x10...
+ * @paramDefault proof ["hash1", "hash2"]
+ * @paramDefault attestationData {"r":"root-hash"}
+ * @returns True if the statement is in the attestation
+ *
+ * @example
+ * ```ts
+ * const isInBatch = await verifyStatementInAttestation(
+ *   statementFideId,
+ *   proof,
+ *   attestationData
+ * );
+ * ```
+ */
+export async function verifyStatementInAttestation(statementFideId, proof, attestationData) {
+    return await verifyMerkleProof(statementFideId, proof, attestationData.r);
+}
+/**
+ * Parse attestation data from a raw identifier string
+ *
+ * @param rawIdentifier - The JSON string from objectRawIdentifier
+ * @returns Parsed attestation data
+ * @throws Error if JSON is invalid
+ *
+ * @example
+ * ```ts
+ * const attestationData = parseAttestationData(provenanceStatement.objectRawIdentifier);
+ * ```
+ */
+export function parseAttestationData(rawIdentifier) {
+    const parsed = JSON.parse(rawIdentifier);
+    if (!parsed.m || !parsed.u || !parsed.r || !parsed.s) {
+        throw new Error('Invalid attestation data: missing required fields (m, u, r, s)');
+    }
+    return {
+        m: parsed.m,
+        u: parsed.u,
+        r: parsed.r,
+        s: parsed.s
+    };
+}
+/**
+ * Verify that an attestation's Fide ID is correctly derived
+ *
+ * @param attestationFideId - The claimed attestation Fide ID
+ * @param rawIdentifier - The raw identifier JSON string
+ * @returns True if the Fide ID is correctly derived
+ *
+ * @example
+ * ```ts
+ * const isValidId = await verifyAttestationFideId(
+ *   provenanceStatement.objectFideId,
+ *   provenanceStatement.objectRawIdentifier
+ * );
+ * ```
+ */
+export async function verifyAttestationFideId(attestationFideId, rawIdentifier) {
+    const expectedId = await calculateFideId('Attestation', 'Attestation', rawIdentifier);
+    return attestationFideId.toLowerCase() === expectedId.toLowerCase();
+}

package/dist/attestation/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * FCP SDK - Attestation Module
+ *
+ * Re-exports all attestation utilities.
+ */
+export { createAttestation, createProvenanceStatements, verifyStatementInAttestation, parseAttestationData, verifyAttestationFideId, type SigningMethod, type AttestationData, type AttestationResult, type CreateAttestationOptions, type ProvenanceStatement } from "./create.js";
+export { verifyAttestation, type VerifyAttestationOptions } from "./verify.js";

package/dist/attestation/index.js

@@ -0,0 +1,7 @@
+/**
+ * FCP SDK - Attestation Module
+ *
+ * Re-exports all attestation utilities.
+ */
+export { createAttestation, createProvenanceStatements, verifyStatementInAttestation, parseAttestationData, verifyAttestationFideId } from "./create.js";
+export { verifyAttestation } from "./verify.js";

package/dist/attestation/verify.d.ts

@@ -0,0 +1,56 @@
+/**
+ * FCP SDK Attestation Verification Utilities
+ *
+ * Full verification functions that combine Merkle proof and signature verification.
+ */
+import { type AttestationData } from "./create.js";
+import type { MerkleProof } from "../merkle/index.js";
+import type { SigningMethod } from "./create.js";
+/**
+ * Options for verifying an attestation
+ */
+export interface VerifyAttestationOptions {
+    /** The signing method used (`eip712`/`eip191` require `viem` to be installed). */
+    method: SigningMethod;
+    /** Public key or address for signature verification */
+    publicKeyOrAddress: CryptoKey | `0x${string}`;
+}
+/**
+ * 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 declare function verifyAttestation(statementFideId: string, proof: MerkleProof, attestationData: AttestationData | string, options: VerifyAttestationOptions): Promise<boolean>;

package/dist/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/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/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/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/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";