@fide.work/fcp 0.0.1-alpha.0

package/dist/signing/ed25519.js

@@ -0,0 +1,161 @@
+/**
+ * FCP SDK Signing Utilities
+ * Ed25519 key generation and signing using native Web Crypto API
+ */
+/**
+ * Get the Web Crypto API (works in browsers and Node.js)
+ */
+async function getWebCrypto() {
+    if (globalThis.crypto) {
+        return globalThis.crypto;
+    }
+    // Node.js fallback
+    const { webcrypto } = await import("node:crypto");
+    return webcrypto;
+}
+/**
+ * Generate a new Ed25519 key pair for signing
+ *
+ * Uses native Web Crypto API - no external dependencies required.
+ *
+ * @returns Promise resolving to a CryptoKey pair
+ *
+ * @remarks
+ * This is a zero-dependency function that works in both Node.js and browsers.
+ * The generated key pair can be exported as hex strings using {@link exportEd25519Keys}.
+ *
+ * @example
+ * ```ts
+ * const keyPair = await generateEd25519KeyPair();
+ * const exported = await exportEd25519Keys(keyPair);
+ * console.log('Address:', exported.address);
+ * ```
+ */
+export async function generateEd25519KeyPair() {
+    const crypto = await getWebCrypto();
+    const keyPair = await crypto.subtle.generateKey({
+        name: "Ed25519",
+    }, true, // extractable
+    ["sign", "verify"]);
+    return {
+        publicKey: keyPair.publicKey,
+        privateKey: keyPair.privateKey
+    };
+}
+/**
+ * Export Ed25519 keys as hex strings
+ *
+ * @param keyPair - The Ed25519 key pair (JWK format)
+ * @returns Exported keys with public key, private key, and derived address
+ *
+ * @remarks
+ * Keys are exported in standard formats:
+ * - Public key: SubjectPublicKeyInfo (SPKI) format as hex
+ * - Private key: PKCS8 format as hex
+ * - Address: Derived from the raw public key bytes (last 32 bytes of SPKI key)
+ *
+ * @example
+ * ```ts
+ * const keyPair = await generateEd25519KeyPair();
+ * const { publicKeyHex, privateKeyHex, address } = await exportEd25519Keys(keyPair);
+ * ```
+ */
+export async function exportEd25519Keys(keyPair) {
+    const crypto = await getWebCrypto();
+    // Export public key (SubjectPublicKeyInfo format)
+    const publicKeyBuffer = await crypto.subtle.exportKey("spki", keyPair.publicKey);
+    const publicKeyHex = Buffer.from(publicKeyBuffer).toString("hex");
+    // Export private key (PKCS8 format)
+    const privateKeyBuffer = await crypto.subtle.exportKey("pkcs8", keyPair.privateKey);
+    const privateKeyHex = Buffer.from(privateKeyBuffer).toString("hex");
+    // Derive address from public key (last 32 bytes of public key in hex)
+    // Ed25519 public keys are 32 bytes, but SPKI format adds metadata
+    const publicKeyBytes = new Uint8Array(publicKeyBuffer);
+    const rawPublicKey = publicKeyBytes.slice(-32); // Last 32 bytes are the actual key
+    const address = Buffer.from(rawPublicKey).toString("hex");
+    return {
+        publicKeyHex,
+        privateKeyHex,
+        address
+    };
+}
+/**
+ * Import Ed25519 keys from hex strings
+ *
+ * @param publicKeyHex - Public key in hex format (SPKI)
+ * @param privateKeyHex - Private key in hex format (PKCS8)
+ * @returns Imported CryptoKey pair
+ *
+ * @remarks
+ * Keys must be in standard formats:
+ * - Public key: SubjectPublicKeyInfo (SPKI) format as hex
+ * - Private key: PKCS8 format as hex
+ *
+ * Use this to restore keys previously exported with {@link exportEd25519Keys}.
+ *
+ * @example
+ * ```ts
+ * const keyPair = await importEd25519Keys(publicKeyHex, privateKeyHex);
+ * ```
+ */
+export async function importEd25519Keys(publicKeyHex, privateKeyHex) {
+    const crypto = await getWebCrypto();
+    const publicKeyBuffer = Buffer.from(publicKeyHex, "hex");
+    const privateKeyBuffer = Buffer.from(privateKeyHex, "hex");
+    const publicKey = await crypto.subtle.importKey("spki", publicKeyBuffer, {
+        name: "Ed25519",
+    }, true, ["verify"]);
+    const privateKey = await crypto.subtle.importKey("pkcs8", privateKeyBuffer, {
+        name: "Ed25519",
+    }, true, ["sign"]);
+    return { publicKey, privateKey };
+}
+/**
+ * Sign data using Ed25519 private key
+ *
+ * @param data - The data/message to sign or verify (hex string for EIP standards, plaintext for EIP-191)
+ * @param privateKey - The Ed25519 key pair (JWK format)
+ * @returns Hex-encoded signature
+ *
+ * @remarks
+ * This function:
+ * - UTF-8 encodes the input data
+ * - Signs using the Ed25519 algorithm
+ * - Returns the signature as a hex string
+ *
+ * @example
+ * ```ts
+ * const signature = await signEd25519("Hello, world!", keyPair.privateKey);
+ * ```
+ */
+export async function signEd25519(data, privateKey) {
+    const crypto = await getWebCrypto();
+    const encoder = new TextEncoder();
+    const signature = await crypto.subtle.sign("Ed25519", privateKey, encoder.encode(data));
+    return Buffer.from(signature).toString("hex");
+}
+/**
+ * Verify an Ed25519 signature
+ *
+ * @param data - The data/message to sign or verify (hex string for EIP standards, plaintext for EIP-191)
+ * @param signatureHex - The cryptographic signature (0x-prefixed hex string)
+ * @param publicKey - The Ed25519 key pair (JWK format)
+ * @returns True if signature is valid
+ *
+ * @remarks
+ * This function:
+ * - UTF-8 encodes the input data
+ * - Verifies the hex-encoded signature using the Ed25519 algorithm
+ * - Returns true only if the signature is cryptographically valid
+ *
+ * @example
+ * ```ts
+ * const isValid = await verifyEd25519("Hello, world!", signature, keyPair.publicKey);
+ * ```
+ */
+export async function verifyEd25519(data, signatureHex, publicKey) {
+    const crypto = await getWebCrypto();
+    const encoder = new TextEncoder();
+    const signature = Buffer.from(signatureHex, "hex");
+    return await crypto.subtle.verify("Ed25519", publicKey, signature, encoder.encode(data));
+}

package/dist/signing/eip191.d.ts

@@ -0,0 +1,50 @@
+/**
+ * FCP SDK EIP-191 Signing Utilities
+ * Ethereum-compatible signing using EIP-191 Personal Sign (requires viem peer dependency)
+ */
+/**
+ * Sign data using EIP-191 Personal Sign
+ *
+ * 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)
+ * @returns Hex-encoded signature
+ * @throws Error if viem is not installed
+ *
+ * @remarks
+ * This function implements EIP-191 Personal Sign, which:
+ * - Prefixes the data with the Ethereum signed message header
+ * - Hashes the prefixed data with Keccak256
+ * - Signs using the Ethereum private key
+ *
+ * Commonly used for Ethereum wallet signatures.
+ *
+ * @example
+ * ```ts
+ * const signature = await signEip191(merkleRoot, privateKey);
+ * ```
+ */
+export declare function signEip191(data: string, privateKey: `0x${string}`): Promise<`0x${string}`>;
+/**
+ * Verify an EIP-191 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)
+ * @returns True if signature is valid
+ * @throws Error if viem is not installed
+ *
+ * @remarks
+ * This function verifies an EIP-191 Personal Sign signature by:
+ * - Reconstructing the signed message with the Ethereum header
+ * - Checking that the signature matches the expected signer address
+ *
+ * @example
+ * ```ts
+ * const isValid = await verifyEip191(merkleRoot, signature, address);
+ * ```
+ */
+export declare function verifyEip191(data: string, signature: `0x${string}`, address: `0x${string}`): Promise<boolean>;

package/dist/signing/eip191.js

@@ -0,0 +1,96 @@
+/**
+ * FCP SDK EIP-191 Signing Utilities
+ * Ethereum-compatible signing using EIP-191 Personal Sign (requires viem peer dependency)
+ */
+/**
+ * Detect which package manager is being used
+ */
+function detectPackageManager() {
+    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';
+    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-191 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\'');
+    }
+}
+/**
+ * Sign data using EIP-191 Personal Sign
+ *
+ * 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)
+ * @returns Hex-encoded signature
+ * @throws Error if viem is not installed
+ *
+ * @remarks
+ * This function implements EIP-191 Personal Sign, which:
+ * - Prefixes the data with the Ethereum signed message header
+ * - Hashes the prefixed data with Keccak256
+ * - Signs using the Ethereum private key
+ *
+ * Commonly used for Ethereum wallet signatures.
+ *
+ * @example
+ * ```ts
+ * const signature = await signEip191(merkleRoot, privateKey);
+ * ```
+ */
+export async function signEip191(data, privateKey) {
+    await checkViemInstalled();
+    const { privateKeyToAccount } = await import('viem/accounts');
+    const account = privateKeyToAccount(privateKey);
+    const signature = await account.signMessage({
+        message: data
+    });
+    return signature;
+}
+/**
+ * Verify an EIP-191 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)
+ * @returns True if signature is valid
+ * @throws Error if viem is not installed
+ *
+ * @remarks
+ * This function verifies an EIP-191 Personal Sign signature by:
+ * - Reconstructing the signed message with the Ethereum header
+ * - Checking that the signature matches the expected signer address
+ *
+ * @example
+ * ```ts
+ * const isValid = await verifyEip191(merkleRoot, signature, address);
+ * ```
+ */
+export async function verifyEip191(data, signature, address) {
+    await checkViemInstalled();
+    const { verifyMessage } = await import('viem');
+    return await verifyMessage({
+        address,
+        message: data,
+        signature
+    });
+}

package/dist/signing/eip712.d.ts

@@ -0,0 +1,112 @@
+/**
+ * FCP SDK EIP-712 Signing Utilities
+ * Ethereum-compatible signing using viem (optional peer dependency)
+ */
+/**
+ * EIP-712 Domain for Fide Context Protocol
+ */
+export interface Eip712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+}
+/**
+ * Default FCP EIP-712 Domain
+ */
+export declare const FCP_EIP712_DOMAIN: Eip712Domain;
+/**
+ * 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 declare function getEthereumAddress(privateKey: `0x${string}`): Promise<`0x${string}`>;
+/**
+ * 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 declare function signEip712(data: string, privateKey: `0x${string}`, domain?: Eip712Domain): Promise<`0x${string}`>;
+/**
+ * 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 declare function verifyEip712(data: string, signature: `0x${string}`, address: `0x${string}`, domain?: Eip712Domain): Promise<boolean>;
+/**
+ * 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 declare function createEthereumCaip10(address: `0x${string}`, chainId?: number): string;

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