@fide.work/fcp 0.0.1-alpha.0

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

@@ -0,0 +1,116 @@
+/**
+ * FCP SDK Signing Utilities
+ * Ed25519 key generation and signing using native Web Crypto API
+ */
+/**
+ * Ed25519 Key Pair
+ */
+export interface Ed25519KeyPair {
+    publicKey: CryptoKey;
+    privateKey: CryptoKey;
+}
+/**
+ * Exported Ed25519 Keys (hex strings)
+ */
+export interface ExportedEd25519Keys {
+    publicKeyHex: string;
+    privateKeyHex: string;
+    address: string;
+}
+/**
+ * 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 declare function generateEd25519KeyPair(): Promise<Ed25519KeyPair>;
+/**
+ * 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 declare function exportEd25519Keys(keyPair: Ed25519KeyPair): Promise<ExportedEd25519Keys>;
+/**
+ * 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 declare function importEd25519Keys(publicKeyHex: string, privateKeyHex: string): Promise<Ed25519KeyPair>;
+/**
+ * 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 declare function signEd25519(data: string, privateKey: CryptoKey): Promise<string>;
+/**
+ * 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 declare function verifyEd25519(data: string, signatureHex: string, publicKey: CryptoKey): Promise<boolean>;

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