@fide.work/fcp 0.0.1-alpha.0

package/dist/experimental/signing/eip712.js

@@ -0,0 +1,187 @@
+/**
+ * FCP SDK EIP-712 Signing Utilities
+ * Ethereum-compatible signing using viem (optional peer dependency)
+ */
+/**
+ * Default FCP EIP-712 Domain
+ */
+export const FCP_EIP712_DOMAIN = {
+    name: 'Fide Context Protocol',
+    version: '1',
+    chainId: 1, // Mainnet (should be configured per chain)
+    verifyingContract: '0x0000000000000000000000000000000000000000'
+};
+/**
+ * Detect which package manager is being used
+ */
+function detectPackageManager() {
+    // Check for package manager environment variables
+    const userAgent = process.env.npm_config_user_agent || '';
+    if (userAgent.includes('pnpm'))
+        return 'pnpm add viem';
+    if (userAgent.includes('yarn'))
+        return 'yarn add viem';
+    if (userAgent.includes('bun'))
+        return 'bun add viem';
+    if (userAgent.includes('npm'))
+        return 'npm install viem';
+    // Default to npm if we can't detect
+    return 'npm install viem';
+}
+/**
+ * Check if viem is installed
+ */
+async function checkViemInstalled() {
+    try {
+        await import('viem');
+    }
+    catch (error) {
+        const installCommand = detectPackageManager();
+        throw new Error('EIP-712 signing requires viem to be installed.\n\n' +
+            `Install it with: ${installCommand}\n\n` +
+            'Or use the zero-dependency Ed25519 signing instead:\n' +
+            '  import { generateEd25519KeyPair, signEd25519 } from \'@fide.work/fcp\'');
+    }
+}
+/**
+ * Get Ethereum address from private key
+ *
+ * Requires viem to be installed as a peer dependency.
+ *
+ * @param privateKey - The private key for signing (0x-prefixed hex)
+ * @returns Ethereum address
+ * @throws Error if viem is not installed
+ *
+ * @remarks
+ * Derives the Ethereum address from the private key using:
+ * - ECDSA public key derivation
+ * - Keccak256 hashing
+ * - Last 20 bytes as the address
+ *
+ * @example
+ * ```ts
+ * const address = await getEthereumAddress(privateKey);
+ * // Result: "0x742d35Cc6634C0532925a3b844Bc9e7595f42e"
+ * ```
+ */
+export async function getEthereumAddress(privateKey) {
+    await checkViemInstalled();
+    const { privateKeyToAddress } = await import('viem/accounts');
+    return privateKeyToAddress(privateKey);
+}
+/**
+ * Sign data using EIP-712 typed data signing
+ *
+ * Requires viem to be installed as a peer dependency.
+ *
+ * @param data - The data/message to sign or verify (hex string for EIP standards, plaintext for EIP-191)
+ * @param privateKey - The private key for signing (0x-prefixed hex)
+ * @param domain - EIP-712 domain (defaults to FCP domain)
+ * @returns Hex-encoded signature
+ * @throws Error if viem is not installed
+ *
+ * @remarks
+ * This function signs data using EIP-712 typed data signing:
+ * - Structures the message in FideAttestation format
+ * - Uses the provided domain (or defaults to FCP_EIP712_DOMAIN)
+ * - Returns an ECDSA signature over the structured hash
+ *
+ * Supports custom domains for integration with different smart contracts.
+ *
+ * @example
+ * ```ts
+ * const signature = await signEip712(merkleRoot, privateKey);
+ * ```
+ */
+export async function signEip712(data, privateKey, domain = FCP_EIP712_DOMAIN) {
+    await checkViemInstalled();
+    const { privateKeyToAccount } = await import('viem/accounts');
+    const { hashTypedData, keccak256, toHex } = await import('viem');
+    const account = privateKeyToAccount(privateKey);
+    // Define the EIP-712 typed data structure
+    const types = {
+        FideAttestation: [
+            { name: 'data', type: 'string' }
+        ]
+    };
+    const message = {
+        data
+    };
+    // Sign using EIP-712
+    const signature = await account.signTypedData({
+        domain,
+        types,
+        primaryType: 'FideAttestation',
+        message
+    });
+    return signature;
+}
+/**
+ * Verify an EIP-712 signature
+ *
+ * Requires viem to be installed as a peer dependency.
+ *
+ * @param data - The data/message to sign or verify (hex string for EIP standards, plaintext for EIP-191)
+ * @param signature - The cryptographic signature (0x-prefixed hex string)
+ * @param address - The signer's Ethereum address (0x-prefixed hex)
+ * @param domain - EIP-712 domain (defaults to FCP domain)
+ * @returns True if signature is valid
+ * @throws Error if viem is not installed
+ *
+ * @remarks
+ * This function verifies an EIP-712 typed data signature by:
+ * - Reconstructing the FideAttestation message structure
+ * - Using the provided domain (or defaults to FCP_EIP712_DOMAIN)
+ * - Verifying the ECDSA signature against the expected signer address
+ *
+ * @example
+ * ```ts
+ * const isValid = await verifyEip712(merkleRoot, signature, address);
+ * ```
+ */
+export async function verifyEip712(data, signature, address, domain = FCP_EIP712_DOMAIN) {
+    await checkViemInstalled();
+    const { verifyTypedData } = await import('viem');
+    const types = {
+        FideAttestation: [
+            { name: 'data', type: 'string' }
+        ]
+    };
+    const message = {
+        data
+    };
+    return await verifyTypedData({
+        address,
+        domain,
+        types,
+        primaryType: 'FideAttestation',
+        message,
+        signature
+    });
+}
+/**
+ * Create a CAIP-10 identifier for an Ethereum address
+ *
+ * @param address - The signer's Ethereum address (0x-prefixed hex)
+ * @param chainId - Chain ID (defaults to 1 for mainnet)
+ * @returns CAIP-10 identifier (e.g., "eip155:1:0x...")
+ *
+ * @remarks
+ * CAIP-10 (Chain Agnostic Improvement Proposal 10) is a standard format for
+ * representing blockchain addresses across different chains. This function creates
+ * identifiers in the format: `eip155:{chainId}:{address}`
+ *
+ * Common chainIds:
+ * - 1: Ethereum Mainnet
+ * - 5: Goerli Testnet
+ * - 11155111: Sepolia Testnet
+ *
+ * @example
+ * ```ts
+ * const caip10 = createEthereumCaip10(address, 1);
+ * // Result: "eip155:1:0x742d35cc6634c0532925a3b844bc9e7595f42e"
+ * ```
+ */
+export function createEthereumCaip10(address, chainId = 1) {
+    return `eip155:${chainId}:${address.toLowerCase()}`;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * FCP SDK - Signing Module
+ *
+ * Re-exports all signing utilities from submodules.
+ */
+export { generateEd25519KeyPair, exportEd25519Keys, importEd25519Keys, signEd25519, verifyEd25519, type Ed25519KeyPair, type ExportedEd25519Keys } from "./ed25519.js";
+export { getEthereumAddress, signEip712, verifyEip712, createEthereumCaip10, FCP_EIP712_DOMAIN, type Eip712Domain } from "./eip712.js";
+export { signEip191, verifyEip191 } from "./eip191.js";

package/dist/experimental/signing/index.js

@@ -0,0 +1,11 @@
+/**
+ * FCP SDK - Signing Module
+ *
+ * Re-exports all signing utilities from submodules.
+ */
+// Ed25519 Signing (native, zero-dependency)
+export { generateEd25519KeyPair, exportEd25519Keys, importEd25519Keys, signEd25519, verifyEd25519 } from "./ed25519.js";
+// EIP-712 Signing (requires viem peer dependency)
+export { getEthereumAddress, signEip712, verifyEip712, createEthereumCaip10, FCP_EIP712_DOMAIN } from "./eip712.js";
+// EIP-191 Signing (requires viem peer dependency)
+export { signEip191, verifyEip191 } from "./eip191.js";

package/dist/fide-id/calculateFideId.d.ts

@@ -0,0 +1,21 @@
+import { FIDE_ENTITY_TYPE_MAP } from "./constants.js";
+import type { FideEntityType } from "./types.js";
+export { FIDE_ENTITY_TYPE_MAP };
+export type { FideEntityType };
+/**
+ * Calculate a Fide ID for an entity from its type, source type, and raw identifier.
+ *
+ * Generates a unique identifier by creating a SHA-256 hash of the raw identifier,
+ * then constructing a Fide ID with type and source characters followed by the last 38 hex characters.
+ *
+ * @param entityType The entity type.
+ * @param sourceEntityType The source entity type.
+ * @param rawIdentifier The raw identifier string to hash.
+ * @paramDefault entityType Person
+ * @paramDefault sourceEntityType Product
+ * @paramDefault rawIdentifier https://x.com/alice
+ * @returns Promise resolving to the calculated Fide ID with format `did:fide:0x{typeChar}{sourceChar}{fingerprint}`
+ * @throws TypeError if rawIdentifier is not a string
+ * @throws Error if entityType or sourceEntityType are invalid, or if protocol constraints are violated
+ */
+export declare function calculateFideId(entityType: FideEntityType, sourceEntityType: FideEntityType, rawIdentifier: string): Promise<`did:fide:0x${string}`>;

package/dist/fide-id/calculateFideId.js

@@ -0,0 +1,53 @@
+import { FIDE_ENTITY_TYPE_MAP } from "./constants.js";
+// Re-export for backward compatibility
+export { FIDE_ENTITY_TYPE_MAP };
+async function getSubtleCrypto() {
+    if (globalThis.crypto?.subtle) {
+        return globalThis.crypto.subtle;
+    }
+    const { webcrypto } = await import("node:crypto");
+    return webcrypto.subtle;
+}
+/**
+ * Calculate a Fide ID for an entity from its type, source type, and raw identifier.
+ *
+ * Generates a unique identifier by creating a SHA-256 hash of the raw identifier,
+ * then constructing a Fide ID with type and source characters followed by the last 38 hex characters.
+ *
+ * @param entityType The entity type.
+ * @param sourceEntityType The source entity type.
+ * @param rawIdentifier The raw identifier string to hash.
+ * @paramDefault entityType Person
+ * @paramDefault sourceEntityType Product
+ * @paramDefault rawIdentifier https://x.com/alice
+ * @returns Promise resolving to the calculated Fide ID with format `did:fide:0x{typeChar}{sourceChar}{fingerprint}`
+ * @throws TypeError if rawIdentifier is not a string
+ * @throws Error if entityType or sourceEntityType are invalid, or if protocol constraints are violated
+ */
+export async function calculateFideId(entityType, sourceEntityType, rawIdentifier) {
+    if (typeof rawIdentifier !== "string") {
+        throw new TypeError(`Invalid rawIdentifier: expected string, got ${typeof rawIdentifier}`);
+    }
+    if (entityType === "Statement" && sourceEntityType !== "Statement") {
+        throw new Error(`Protocol entity ${entityType} must be self-sourced. Expected source type: ${entityType}, got: ${sourceEntityType}`);
+    }
+    if (sourceEntityType === "Statement" && entityType !== "Statement") {
+        throw new Error(`Invalid Statement source for ${entityType}: protocol disallows 0xX0 (Statement-derived) IDs for non-Statement entities. Use a concrete source (e.g. Product, Organization) instead.`);
+    }
+    const entityTypeCode = FIDE_ENTITY_TYPE_MAP[entityType];
+    if (!entityTypeCode) {
+        throw new Error(`Invalid entityType: ${String(entityType)}`);
+    }
+    const sourceEntityTypeCode = FIDE_ENTITY_TYPE_MAP[sourceEntityType];
+    if (!sourceEntityTypeCode) {
+        throw new Error(`Invalid sourceEntityType: ${String(sourceEntityType)}`);
+    }
+    const subtle = await getSubtleCrypto();
+    const bytes = new TextEncoder().encode(rawIdentifier);
+    const digest = await subtle.digest("SHA-256", bytes);
+    const hashHex = Array.from(new Uint8Array(digest))
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+    const fingerprint = hashHex.slice(-38);
+    return `did:fide:0x${entityTypeCode}${sourceEntityTypeCode}${fingerprint}`;
+}

package/dist/fide-id/calculateStatementFideId.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Calculate a Fide ID for a Statement from its RDF triple components.
+ *
+ * Creates a statement Fide ID by hashing a canonical JSON representation of the subject-predicate-object triple.
+ * The resulting Fide ID always has type and source both set to Statement (0x00...).
+ *
+ * @param subjectFideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @param predicateFideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @param objectFideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @paramDefault subjectFideId did:fide:0x152f02f1d1c1e62b2e569e11818420c1968be3d9
+ * @paramDefault predicateFideId did:fide:0x6524b049fa7069dd318c44531214a955c3f1fa37
+ * @paramDefault objectFideId did:fide:0x66a023246354ad7e064b1e4e009ec8a0699a3043
+ * @returns Promise resolving to the calculated statement Fide ID with format `did:fide:0x00{fingerprint}`
+ * @throws TypeError if any Fide ID is not a string
+ * @throws Error if any Fide ID format is invalid or not in canonical form
+ * @remarks
+ * This function only validates Fide ID format and canonicalizes triple hashing.
+ * It does not enforce statement role policy (for example allowed predicate entity/source combos).
+ * Role policy checks are enforced by `createStatement`.
+ */
+export declare function calculateStatementFideId(subjectFideId: string, predicateFideId: string, objectFideId: string): Promise<`did:fide:0x${string}`>;

package/dist/fide-id/calculateStatementFideId.js

@@ -0,0 +1,38 @@
+import { calculateFideId } from "./calculateFideId.js";
+function assertFideId(value) {
+    if (typeof value !== "string") {
+        throw new TypeError(`Invalid Fide ID: expected string, got ${typeof value}`);
+    }
+    if (/^did:fide:0x[0-9a-f]{40}$/.test(value)) {
+        return value;
+    }
+    throw new Error(`Invalid Fide ID format: ${value}. Expected full Fide ID (e.g., did:fide:0x...)`);
+}
+/**
+ * Calculate a Fide ID for a Statement from its RDF triple components.
+ *
+ * Creates a statement Fide ID by hashing a canonical JSON representation of the subject-predicate-object triple.
+ * The resulting Fide ID always has type and source both set to Statement (0x00...).
+ *
+ * @param subjectFideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @param predicateFideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @param objectFideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @paramDefault subjectFideId did:fide:0x152f02f1d1c1e62b2e569e11818420c1968be3d9
+ * @paramDefault predicateFideId did:fide:0x6524b049fa7069dd318c44531214a955c3f1fa37
+ * @paramDefault objectFideId did:fide:0x66a023246354ad7e064b1e4e009ec8a0699a3043
+ * @returns Promise resolving to the calculated statement Fide ID with format `did:fide:0x00{fingerprint}`
+ * @throws TypeError if any Fide ID is not a string
+ * @throws Error if any Fide ID format is invalid or not in canonical form
+ * @remarks
+ * This function only validates Fide ID format and canonicalizes triple hashing.
+ * It does not enforce statement role policy (for example allowed predicate entity/source combos).
+ * Role policy checks are enforced by `createStatement`.
+ */
+export async function calculateStatementFideId(subjectFideId, predicateFideId, objectFideId) {
+    const rawIdentifier = JSON.stringify({
+        o: assertFideId(objectFideId),
+        p: assertFideId(predicateFideId),
+        s: assertFideId(subjectFideId)
+    });
+    return calculateFideId("Statement", "Statement", rawIdentifier);
+}

package/dist/fide-id/constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * FCP SDK Constants
+ * Central location for all protocol constants
+ */
+/**
+ * Entity Type Map
+ * Maps FCP entity type names to their single-character hex codes.
+ * Used as both Part 1 (Entity Type) and Part 2 (Identifier Source) in Fide IDs.
+ */
+export declare const FIDE_ENTITY_TYPE_MAP: {
+    readonly Statement: "0";
+    readonly Person: "1";
+    readonly Organization: "2";
+    readonly AutonomousAgent: "7";
+    readonly Place: "3";
+    readonly Event: "4";
+    readonly Product: "5";
+    readonly CreativeWork: "6";
+};
+/**
+ * Reverse lookup: character code to entity type name
+ */
+export declare const FIDE_CHAR_TO_ENTITY_TYPE: Record<string, keyof typeof FIDE_ENTITY_TYPE_MAP>;
+/**
+ * Fide ID Prefix
+ * All Fide IDs start with this constant prefix (W3C DID format)
+ */
+export declare const FIDE_ID_PREFIX: "did:fide:0x";
+/**
+ * Fide ID Length (excluding prefix)
+ * 40 hex characters: 1 (type) + 1 (source) + 38 (fingerprint)
+ */
+export declare const FIDE_ID_HEX_LENGTH = 40;
+/**
+ * Fide ID Length (including prefix)
+ * "did:fide:0x" (11) + 40 hex = 51 characters
+ */
+export declare const FIDE_ID_LENGTH: number;
+/**
+ * Fingerprint Length
+ * Last 38 hex characters (19 bytes) of SHA-256 hash
+ */
+export declare const FIDE_ID_FINGERPRINT_LENGTH = 38;

package/dist/fide-id/constants.js

@@ -0,0 +1,55 @@
+/**
+ * FCP SDK Constants
+ * Central location for all protocol constants
+ */
+/**
+ * Entity Type Map
+ * Maps FCP entity type names to their single-character hex codes.
+ * Used as both Part 1 (Entity Type) and Part 2 (Identifier Source) in Fide IDs.
+ */
+export const FIDE_ENTITY_TYPE_MAP = {
+    // Fide Context Protocol Types
+    Statement: "0",
+    // Active Entities
+    Person: "1",
+    Organization: "2",
+    AutonomousAgent: "7",
+    // Inactive Entities
+    Place: "3",
+    Event: "4",
+    Product: "5",
+    CreativeWork: "6"
+};
+/**
+ * Reverse lookup: character code to entity type name
+ */
+export const FIDE_CHAR_TO_ENTITY_TYPE = {
+    "0": "Statement",
+    "1": "Person",
+    "2": "Organization",
+    "7": "AutonomousAgent",
+    "3": "Place",
+    "4": "Event",
+    "5": "Product",
+    "6": "CreativeWork"
+};
+/**
+ * Fide ID Prefix
+ * All Fide IDs start with this constant prefix (W3C DID format)
+ */
+export const FIDE_ID_PREFIX = "did:fide:0x";
+/**
+ * Fide ID Length (excluding prefix)
+ * 40 hex characters: 1 (type) + 1 (source) + 38 (fingerprint)
+ */
+export const FIDE_ID_HEX_LENGTH = 40;
+/**
+ * Fide ID Length (including prefix)
+ * "did:fide:0x" (11) + 40 hex = 51 characters
+ */
+export const FIDE_ID_LENGTH = FIDE_ID_PREFIX.length + FIDE_ID_HEX_LENGTH;
+/**
+ * Fingerprint Length
+ * Last 38 hex characters (19 bytes) of SHA-256 hash
+ */
+export const FIDE_ID_FINGERPRINT_LENGTH = 38;

package/dist/fide-id/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * FCP SDK - Fide ID Module
+ *
+ * Re-exports all Fide ID utilities from submodules.
+ */
+export { calculateFideId } from "./calculateFideId.js";
+export { calculateStatementFideId } from "./calculateStatementFideId.js";
+export { assertFideId, parseFideId, } from "./utils.js";
+export { FIDE_ENTITY_TYPE_MAP, FIDE_CHAR_TO_ENTITY_TYPE, FIDE_ID_PREFIX, FIDE_ID_HEX_LENGTH, FIDE_ID_LENGTH, FIDE_ID_FINGERPRINT_LENGTH } from "./constants.js";
+export type { FideEntityType, FideStatementPredicateEntityType, FideStatementPredicateSourceType, FideEntityTypeChar, FideId, FideFingerprint, ParsedFideId } from "./types.js";

package/dist/fide-id/index.js

@@ -0,0 +1,12 @@
+/**
+ * FCP SDK - Fide ID Module
+ *
+ * Re-exports all Fide ID utilities from submodules.
+ */
+// Core calculation functions
+export { calculateFideId } from "./calculateFideId.js";
+export { calculateStatementFideId } from "./calculateStatementFideId.js";
+// Utility functions
+export { assertFideId, parseFideId, } from "./utils.js";
+// Constants
+export { FIDE_ENTITY_TYPE_MAP, FIDE_CHAR_TO_ENTITY_TYPE, FIDE_ID_PREFIX, FIDE_ID_HEX_LENGTH, FIDE_ID_LENGTH, FIDE_ID_FINGERPRINT_LENGTH } from "./constants.js";

package/dist/fide-id/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * FCP SDK Types
+ * Central location for all TypeScript type definitions
+ */
+import { FIDE_ENTITY_TYPE_MAP } from "./constants.js";
+/**
+ * Valid FCP entity type names derived from `FIDE_ENTITY_TYPE_MAP`.
+ * @docs /fcp/docs/entities
+ */
+export type FideEntityType = keyof typeof FIDE_ENTITY_TYPE_MAP;
+/**
+ * Allowed entity types for statement predicates.
+ *
+ * - `CreativeWork`: schema/ontology predicate IRIs
+ * @docs /fcp/docs/schema/#predicate
+*/
+export type FideStatementPredicateEntityType = "CreativeWork";
+/**
+ * Allowed source types for statement predicates.
+ *
+ * - `Product`: predicate IRIs are treated as product-sourced vocabulary terms
+ */
+export type FideStatementPredicateSourceType = "Product";
+/**
+ * Single-character FCP type codes (hex) derived from `FIDE_ENTITY_TYPE_MAP`.
+ */
+export type FideEntityTypeChar = typeof FIDE_ENTITY_TYPE_MAP[FideEntityType];
+/**
+ * Full Fide ID format (with did:fide:0x prefix)
+ */
+export type FideId = `did:fide:0x${string}`;
+/**
+ * Fide ID fingerprint segment (38 hex characters, 19 bytes).
+ */
+export type FideFingerprint = string;
+/**
+ * Parsed Fide ID components.
+ */
+export interface ParsedFideId {
+    /** The full Fide ID string */
+    fideId: FideId;
+    /** Entity type code (1 hex char from Part 1 of the Fide ID). */
+    typeChar: FideEntityTypeChar;
+    /** Source type code (1 hex char from Part 2 of the Fide ID). */
+    sourceChar: FideEntityTypeChar;
+    /** Resolved entity type name from `FIDE_CHAR_TO_ENTITY_TYPE[typeChar]`. */
+    entityType: FideEntityType;
+    /** Resolved source type name from `FIDE_CHAR_TO_ENTITY_TYPE[sourceChar]`. */
+    sourceType: FideEntityType;
+    /** Fingerprint segment (Part 3, 38 hex chars). */
+    fingerprint: FideFingerprint;
+}

package/dist/fide-id/types.js

@@ -0,0 +1,5 @@
+/**
+ * FCP SDK Types
+ * Central location for all TypeScript type definitions
+ */
+export {};

package/dist/fide-id/utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * FCP SDK Utilities
+ * Helper functions for working with Fide IDs
+ */
+import type { FideId, ParsedFideId } from "./types.js";
+/**
+ * Assert that a value is a properly formatted Fide ID.
+ *
+ * Valid format is:
+ * `did:fide:0x` prefix followed by exactly 40 hexadecimal characters (case-insensitive).
+ *
+ * @param value The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @paramDefault value did:fide:0x152f02f1d1c1e62b2e569e11818420c1968be3d9
+ * @returns void
+ * @throws TypeError if value is not a string
+ * @throws Error if value is not a valid Fide ID format
+ */
+export declare function assertFideId(value: string): asserts value is FideId;
+/**
+ * Parse a Fide ID into its constituent components.
+ *
+ * Decomposes a Fide ID into entity type, source type, and fingerprint, converting hex characters
+ * to their corresponding entity type names.
+ *
+ * @param fideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @paramDefault fideId did:fide:0x152f02f1d1c1e62b2e569e11818420c1968be3d9
+ * @returns Parsed Fide ID components. `entityType` and `sourceType` are resolved via `FIDE_CHAR_TO_ENTITY_TYPE`.
+ * @throws Error if invalid Fide ID format or if type characters do not map to known entity types
+ */
+export declare function parseFideId(fideId: FideId): ParsedFideId;

package/dist/fide-id/utils.js

@@ -0,0 +1,65 @@
+/**
+ * FCP SDK Utilities
+ * Helper functions for working with Fide IDs
+ */
+import { FIDE_ID_PREFIX, FIDE_ID_LENGTH, FIDE_CHAR_TO_ENTITY_TYPE } from "./constants.js";
+/**
+ * Assert that a value is a properly formatted Fide ID.
+ *
+ * Valid format is:
+ * `did:fide:0x` prefix followed by exactly 40 hexadecimal characters (case-insensitive).
+ *
+ * @param value The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @paramDefault value did:fide:0x152f02f1d1c1e62b2e569e11818420c1968be3d9
+ * @returns void
+ * @throws TypeError if value is not a string
+ * @throws Error if value is not a valid Fide ID format
+ */
+export function assertFideId(value) {
+    if (typeof value !== "string") {
+        throw new TypeError(`Invalid Fide ID: expected string, got ${typeof value}`);
+    }
+    if (value.length !== FIDE_ID_LENGTH) {
+        throw new Error(`Invalid Fide ID format: ${value}. Expected ${FIDE_ID_PREFIX}... (${FIDE_ID_LENGTH} chars)`);
+    }
+    if (!value.startsWith(FIDE_ID_PREFIX)) {
+        throw new Error(`Invalid Fide ID format: ${value}. Expected ${FIDE_ID_PREFIX}... (${FIDE_ID_LENGTH} chars)`);
+    }
+    const hex = value.slice(FIDE_ID_PREFIX.length);
+    if (!/^[0-9a-f]{40}$/i.test(hex)) {
+        throw new Error(`Invalid Fide ID format: ${value}. Expected ${FIDE_ID_PREFIX}... (${FIDE_ID_LENGTH} chars)`);
+    }
+}
+/**
+ * Parse a Fide ID into its constituent components.
+ *
+ * Decomposes a Fide ID into entity type, source type, and fingerprint, converting hex characters
+ * to their corresponding entity type names.
+ *
+ * @param fideId The Fide ID reference (format: did:fide:0x... or 0x...)
+ * @paramDefault fideId did:fide:0x152f02f1d1c1e62b2e569e11818420c1968be3d9
+ * @returns Parsed Fide ID components. `entityType` and `sourceType` are resolved via `FIDE_CHAR_TO_ENTITY_TYPE`.
+ * @throws Error if invalid Fide ID format or if type characters do not map to known entity types
+ */
+export function parseFideId(fideId) {
+    assertFideId(fideId);
+    const typeChar = fideId[FIDE_ID_PREFIX.length];
+    const sourceChar = fideId[FIDE_ID_PREFIX.length + 1];
+    const fingerprint = fideId.slice(FIDE_ID_PREFIX.length + 2);
+    const entityType = FIDE_CHAR_TO_ENTITY_TYPE[typeChar];
+    const sourceType = FIDE_CHAR_TO_ENTITY_TYPE[sourceChar];
+    if (!entityType) {
+        throw new Error(`Unknown entity type character: ${typeChar}`);
+    }
+    if (!sourceType) {
+        throw new Error(`Unknown source type character: ${sourceChar}`);
+    }
+    return {
+        fideId,
+        typeChar,
+        sourceChar,
+        entityType,
+        sourceType,
+        fingerprint
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fide.work/fcp - Fide Context Protocol SDK
+ *
+ * Core functions for calculating Fide IDs and working with
+ * the FCP protocol in JavaScript/TypeScript.
+ */
+export { calculateFideId, calculateStatementFideId } from "./fide-id/index.js";
+export { assertFideId, parseFideId, } from "./fide-id/index.js";
+export { FIDE_ENTITY_TYPE_MAP, FIDE_CHAR_TO_ENTITY_TYPE, FIDE_ID_PREFIX, FIDE_ID_HEX_LENGTH, FIDE_ID_LENGTH, FIDE_ID_FINGERPRINT_LENGTH } from "./fide-id/index.js";
+export type { FideEntityType, FideStatementPredicateEntityType, FideStatementPredicateSourceType, FideEntityTypeChar, FideId, FideFingerprint, ParsedFideId } from "./fide-id/index.js";
+export { createStatement, batchStatementsWithRoot, type StatementInput, type Statement, type StatementBatchWithRoot } from "./statement/index.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @fide.work/fcp - Fide Context Protocol SDK
+ *
+ * Core functions for calculating Fide IDs and working with
+ * the FCP protocol in JavaScript/TypeScript.
+ */
+// ============================================================================
+// FIDE ID MODULE
+// ============================================================================
+// Core calculation functions
+export { calculateFideId, calculateStatementFideId } from "./fide-id/index.js";
+// Utility functions
+export { assertFideId, parseFideId, } from "./fide-id/index.js";
+// Constants
+export { FIDE_ENTITY_TYPE_MAP, FIDE_CHAR_TO_ENTITY_TYPE, FIDE_ID_PREFIX, FIDE_ID_HEX_LENGTH, FIDE_ID_LENGTH, FIDE_ID_FINGERPRINT_LENGTH } from "./fide-id/index.js";
+// ============================================================================
+// STATEMENT MODULE
+// ============================================================================
+export { createStatement, batchStatementsWithRoot } from "./statement/index.js";

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