@private.me/xbind 1.2.0

package/dist-standalone/http-compat.js

@@ -0,0 +1,267 @@
+/**
+ * @module http-compat
+ * HTTP client compatibility adapters for xBind auto-upgrade
+ *
+ * Provides drop-in replacements for popular HTTP clients (fetch, axios, got)
+ * that transparently upgrade to xBind when both parties support it.
+ */
+import { xfetch } from './xfetch.js';
+/**
+ * Create axios-compatible HTTP client with xBind auto-upgrade
+ *
+ * Drop-in replacement for axios that transparently upgrades to xBind.
+ *
+ * @returns Axios-compatible client
+ *
+ * @example
+ * ```typescript
+ * import { createAxiosCompat } from '@private.me/xbind/http-compat';
+ *
+ * const axios = createAxiosCompat();
+ *
+ * // Auto-upgrades to xBind if supported
+ * const response = await axios.get('https://api.example.com/data');
+ * console.log('Used xBind?', response.xbind?.used);
+ * console.log('Data:', response.data);
+ * ```
+ */
+export function createAxiosCompat() {
+    async function request(config) {
+        // Normalize config
+        const cfg = typeof config === 'string' ? { url: config } : config;
+        const method = cfg.method?.toUpperCase() ?? 'GET';
+        const url = cfg.baseURL
+            ? new URL(cfg.url ?? '', cfg.baseURL).toString()
+            : cfg.url ?? '';
+        // Build headers
+        const headers = { ...cfg.headers };
+        // Build URL with query params
+        let finalUrl = url;
+        if (cfg.params) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(cfg.params)) {
+                params.append(key, String(value));
+            }
+            finalUrl = `${url}?${params.toString()}`;
+        }
+        // Build request body
+        let body;
+        if (cfg.data) {
+            if (typeof cfg.data === 'string') {
+                body = cfg.data;
+            }
+            else {
+                body = JSON.stringify(cfg.data);
+                headers['Content-Type'] = 'application/json';
+            }
+        }
+        // Convert to xfetch options
+        const xfetchOpts = {
+            method,
+            headers,
+            body,
+            timeout: cfg.timeout,
+            forceXBind: cfg.forceXBind,
+            disableXBind: cfg.disableXBind,
+        };
+        // Make request via xfetch
+        const response = await xfetch(finalUrl, xfetchOpts);
+        // Parse response body based on responseType
+        let data;
+        const responseType = cfg.responseType ?? 'json';
+        switch (responseType) {
+            case 'json':
+                data = (await response.json());
+                break;
+            case 'text':
+                data = (await response.text());
+                break;
+            case 'blob':
+                data = (await response.blob());
+                break;
+            case 'arraybuffer':
+                data = (await response.arrayBuffer());
+                break;
+            default:
+                data = (await response.json());
+        }
+        // Validate status if custom validator provided
+        if (cfg.validateStatus && !cfg.validateStatus(response.status)) {
+            throw new Error(`Request failed with status ${response.status}`);
+        }
+        // Convert headers to object
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            data,
+            status: response.status,
+            statusText: response.statusText,
+            headers: responseHeaders,
+            config: cfg,
+            xbind: {
+                used: response.usedXBind,
+                protocol: response.transport.protocol,
+                latency: response.transport.latency,
+                peerDID: response.transport.peerDID,
+            },
+        };
+    }
+    // Convenience methods
+    async function get(url, config) {
+        return request({ ...config, url, method: 'GET' });
+    }
+    async function post(url, data, config) {
+        return request({ ...config, url, method: 'POST', data });
+    }
+    async function put(url, data, config) {
+        return request({ ...config, url, method: 'PUT', data });
+    }
+    async function patch(url, data, config) {
+        return request({ ...config, url, method: 'PATCH', data });
+    }
+    async function del(url, config) {
+        return request({ ...config, url, method: 'DELETE' });
+    }
+    return {
+        request,
+        get,
+        post,
+        put,
+        patch,
+        delete: del,
+    };
+}
+/**
+ * Create got-compatible HTTP client with xBind auto-upgrade
+ *
+ * Drop-in replacement for got that transparently upgrades to xBind.
+ *
+ * @returns Got-compatible client
+ *
+ * @example
+ * ```typescript
+ * import { createGotCompat } from '@private.me/xbind/http-compat';
+ *
+ * const got = createGotCompat();
+ *
+ * // Auto-upgrades to xBind if supported
+ * const response = await got('https://api.example.com/data', {
+ *   responseType: 'json',
+ * });
+ * console.log('Used xBind?', response.xbind?.used);
+ * console.log('Body:', response.body);
+ * ```
+ */
+export function createGotCompat() {
+    async function got(url, options) {
+        // Normalize options
+        const opts = typeof url === 'string' ? { ...options, url } : url;
+        const method = opts.method?.toUpperCase() ?? 'GET';
+        const finalUrl = opts.url ?? '';
+        // Build headers
+        const headers = { ...opts.headers };
+        // Build URL with search params
+        let urlWithParams = finalUrl;
+        if (opts.searchParams) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(opts.searchParams)) {
+                params.append(key, String(value));
+            }
+            urlWithParams = `${finalUrl}?${params.toString()}`;
+        }
+        // Build request body
+        let body;
+        if (opts.json) {
+            body = JSON.stringify(opts.json);
+            headers['Content-Type'] = 'application/json';
+        }
+        else if (opts.body) {
+            // Convert Buffer to string for compatibility with xfetch
+            // SAFETY: After instanceof check, both branches produce string type
+            body = (opts.body instanceof Buffer ? opts.body.toString() : opts.body);
+        }
+        // Extract timeout
+        const timeout = typeof opts.timeout === 'number'
+            ? opts.timeout
+            : opts.timeout?.request;
+        // Convert to xfetch options
+        const xfetchOpts = {
+            method,
+            headers,
+            body,
+            timeout,
+            forceXBind: opts.forceXBind,
+            disableXBind: opts.disableXBind,
+        };
+        // Make request via xfetch
+        const response = await xfetch(urlWithParams, xfetchOpts);
+        // Parse response body based on responseType
+        let responseBody;
+        const responseType = opts.responseType ?? 'text';
+        switch (responseType) {
+            case 'json':
+                responseBody = (await response.json());
+                break;
+            case 'text':
+                responseBody = (await response.text());
+                break;
+            case 'buffer':
+                const arrayBuffer = await response.arrayBuffer();
+                responseBody = Buffer.from(arrayBuffer);
+                break;
+            default:
+                responseBody = (await response.text());
+        }
+        // Convert headers to object
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            body: responseBody,
+            statusCode: response.status,
+            headers: responseHeaders,
+            url: response.url,
+            requestUrl: urlWithParams,
+            xbind: {
+                used: response.usedXBind,
+                protocol: response.transport.protocol,
+                latency: response.transport.latency,
+                peerDID: response.transport.peerDID,
+            },
+        };
+    }
+    // Convenience methods
+    got.get = (url, options) => got(url, { ...options, method: 'GET' });
+    got.post = (url, options) => got(url, { ...options, method: 'POST' });
+    got.put = (url, options) => got(url, { ...options, method: 'PUT' });
+    got.patch = (url, options) => got(url, { ...options, method: 'PATCH' });
+    got.delete = (url, options) => got(url, { ...options, method: 'DELETE' });
+    return got;
+}
+/**
+ * Wrap existing fetch implementation with xBind auto-upgrade
+ *
+ * Use this to upgrade an existing fetch instance (like node-fetch, cross-fetch, etc.)
+ *
+ * @param fetchImpl - Fetch implementation to wrap
+ * @returns Wrapped fetch with xBind support
+ *
+ * @example
+ * ```typescript
+ * import { wrapFetch } from '@private.me/xbind/http-compat';
+ * import nodeFetch from 'node-fetch';
+ *
+ * const fetch = wrapFetch(nodeFetch);
+ *
+ * // Uses xBind if supported, falls back to node-fetch
+ * const response = await fetch('https://api.example.com/data');
+ * ```
+ */
+export function wrapFetch(fetchImpl) {
+    // Return xfetch (which already handles auto-upgrade and fallback)
+    // The original fetchImpl is not used because xfetch uses global fetch
+    return xfetch;
+}

package/dist-standalone/identity.d.ts

@@ -0,0 +1,176 @@
+import type { Result } from '@private.me/shared';
+/** Agent cryptographic identity backed by Ed25519 keypair. */
+export interface AgentIdentity {
+    /** Decentralized identifier: did:key:z6Mk... */
+    readonly did: string;
+    /** Web Crypto public key handle */
+    readonly publicKey: CryptoKey;
+    /** Web Crypto private key handle */
+    readonly privateKey: CryptoKey;
+    /** Raw 32-byte Ed25519 public key */
+    readonly rawPublicKey: Uint8Array;
+    /** Web Crypto X25519 private key for ECDH forward secrecy. */
+    readonly x25519PrivateKey: CryptoKey;
+    /** Web Crypto X25519 public key for ECDH forward secrecy. */
+    readonly x25519PublicKey: CryptoKey;
+    /** Raw 32-byte X25519 public key for wire transport. */
+    readonly rawX25519PublicKey: Uint8Array;
+    /** ML-KEM-768 public key (1184 bytes) for hybrid post-quantum KEM. */
+    readonly mlKemPublicKey?: Uint8Array;
+    /** ML-KEM-768 secret key (2400 bytes) for hybrid post-quantum KEM. */
+    readonly mlKemSecretKey?: Uint8Array;
+    /** ML-DSA-65 public key (1952 bytes) for hybrid post-quantum signatures. */
+    readonly mlDsaPublicKey?: Uint8Array;
+    /** ML-DSA-65 secret key (4032 bytes) for hybrid post-quantum signatures. */
+    readonly mlDsaSecretKey?: Uint8Array;
+}
+/** Error codes for identity operations. */
+export type IdentityError = 'KEYGEN_FAILED' | 'SIGN_FAILED' | 'VERIFY_FAILED' | 'INVALID_DID' | 'INVALID_KEY_LENGTH' | 'EXPORT_FAILED' | 'IMPORT_FAILED';
+/**
+ * Generate a new Ed25519 agent identity.
+ * Creates keypair via Web Crypto API, derives did:key DID.
+ */
+export declare function generateIdentity(opts?: {
+    postQuantumSig?: boolean;
+}): Promise<Result<AgentIdentity, IdentityError>>;
+/**
+ * Sign data with an Ed25519 private key.
+ * @returns 64-byte Ed25519 signature.
+ */
+export declare function sign(privateKey: CryptoKey, data: Uint8Array): Promise<Result<Uint8Array, IdentityError>>;
+/**
+ * Verify an Ed25519 signature.
+ * @returns true if valid, false if invalid (not an error).
+ */
+export declare function verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean, IdentityError>>;
+/**
+ * Import a raw 32-byte Ed25519 public key into a CryptoKey.
+ */
+export declare function importPublicKey(rawPublicKey: Uint8Array): Promise<Result<CryptoKey, IdentityError>>;
+/**
+ * Convert 32-byte Ed25519 public key to did:key DID.
+ * Format: did:key:z + base58btc(0xed01 || publicKey).
+ */
+export declare function publicKeyToDid(rawPublicKey: Uint8Array): string;
+/**
+ * Extract raw 32-byte public key bytes from a did:key DID.
+ */
+export declare function didToPublicKeyBytes(did: string): Result<Uint8Array, IdentityError>;
+/**
+ * Export an Ed25519 private key as PKCS8 DER bytes.
+ *
+ * Use this to persist an agent identity across restarts.
+ * Node 20 does not support raw export for Ed25519 private keys —
+ * PKCS8 is the portable format.
+ *
+ * @param privateKey - Ed25519 CryptoKey (must be extractable).
+ * @returns PKCS8 DER bytes or error.
+ */
+export declare function exportPKCS8(privateKey: CryptoKey): Promise<Result<Uint8Array, IdentityError>>;
+/**
+ * Export an X25519 private key as PKCS8 DER bytes.
+ *
+ * @param privateKey - X25519 CryptoKey (must be extractable).
+ * @returns PKCS8 DER bytes or error.
+ */
+export declare function exportX25519PKCS8(privateKey: CryptoKey): Promise<Result<Uint8Array, IdentityError>>;
+/**
+ * Import an Ed25519 identity from PKCS8 DER bytes.
+ *
+ * Generates a new X25519 keypair for forward secrecy.
+ * Use this when you only persisted the Ed25519 key.
+ *
+ * @param pkcs8 - PKCS8-encoded Ed25519 private key bytes.
+ * @returns Full AgentIdentity or error.
+ */
+export declare function importFromPKCS8(pkcs8: Uint8Array): Promise<Result<AgentIdentity, IdentityError>>;
+/**
+ * Import a full identity from both PKCS8 blobs (Ed25519 + X25519).
+ *
+ * Use this when you persisted both keys for full identity restoration
+ * including the original X25519 key (preserves registered key agreement).
+ *
+ * @param ed25519Pkcs8 - PKCS8-encoded Ed25519 private key bytes.
+ * @param x25519Pkcs8 - PKCS8-encoded X25519 private key bytes.
+ * @returns Full AgentIdentity or error.
+ */
+export declare function importIdentity(ed25519Pkcs8: Uint8Array, x25519Pkcs8: Uint8Array, mlKemSecretKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaSecretKey?: Uint8Array, mlDsaPublicKey?: Uint8Array): Promise<Result<AgentIdentity, IdentityError>>;
+/**
+ * Export ML-KEM-768 secret key bytes from an identity.
+ *
+ * @param identity - Agent identity with ML-KEM keys.
+ * @returns Raw 2400-byte ML-KEM secret key or undefined if not available.
+ */
+export declare function exportMlKemSecretKey(identity: AgentIdentity): Uint8Array | undefined;
+/**
+ * Export ML-KEM-768 public key bytes from an identity.
+ *
+ * @param identity - Agent identity with ML-KEM keys.
+ * @returns Raw 1184-byte ML-KEM public key or undefined if not available.
+ */
+export declare function exportMlKemPublicKey(identity: AgentIdentity): Uint8Array | undefined;
+/** ML-DSA-65 signature length in bytes. */
+export declare const ML_DSA65_SIG_BYTES = 3309;
+/** ML-DSA-65 public key length in bytes. */
+export declare const ML_DSA65_PK_BYTES = 1952;
+/** ML-DSA-65 secret key seed length in bytes (using seed format for storage). */
+export declare const ML_DSA65_SK_BYTES = 32;
+/**
+ * Sign data with an ML-DSA-65 secret key (FIPS 204).
+ * @param secretKey - 32-byte ML-DSA-65 secret key seed.
+ * @param data - Data to sign.
+ * @returns 3309-byte ML-DSA-65 signature.
+ */
+export declare function signMlDsa65(secretKey: Uint8Array, data: Uint8Array): Promise<Result<Uint8Array, IdentityError>>;
+/**
+ * Verify an ML-DSA-65 signature (FIPS 204).
+ * @param publicKey - 1952-byte ML-DSA-65 public key.
+ * @param signature - 3309-byte ML-DSA-65 signature.
+ * @param data - Data that was signed.
+ * @returns true if valid, false if invalid (not an error).
+ */
+export declare function verifyMlDsa65(publicKey: Uint8Array, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean, IdentityError>>;
+/**
+ * Export ML-DSA-65 secret key bytes from an identity.
+ *
+ * @param identity - Agent identity with ML-DSA keys.
+ * @returns Raw 4032-byte ML-DSA-65 secret key or undefined if not available.
+ */
+export declare function exportMlDsaSecretKey(identity: AgentIdentity): Uint8Array | undefined;
+/**
+ * Export ML-DSA-65 public key bytes from an identity.
+ *
+ * @param identity - Agent identity with ML-DSA keys.
+ * @returns Raw 1952-byte ML-DSA-65 public key or undefined if not available.
+ */
+export declare function exportMlDsaPublicKey(identity: AgentIdentity): Uint8Array | undefined;
+/**
+ * Derive a deterministic AgentIdentity from a 32-byte seed.
+ *
+ * Uses HKDF-SHA256 to derive separate Ed25519 and X25519 private keys
+ * from the seed. The same seed always produces the same identity (same DID).
+ *
+ * @param seed - Exactly 32 bytes of high-entropy key material.
+ * @returns Full AgentIdentity or error.
+ */
+export declare function identityFromSeed(seed: Uint8Array, opts?: {
+    postQuantumSig?: boolean;
+}): Promise<Result<AgentIdentity, IdentityError>>;
+/**
+ * Extract the raw 32-byte Ed25519 private key from a PKCS8 DER blob.
+ *
+ * Strips the 16-byte ASN.1 header. Validates prefix matches Ed25519 OID.
+ *
+ * @param pkcs8 - 48-byte PKCS8 DER for Ed25519.
+ * @returns 32-byte raw private key or error.
+ */
+export declare function extractRawEd25519(pkcs8: Uint8Array): Result<Uint8Array, IdentityError>;
+/**
+ * Extract the raw 32-byte X25519 private key from a PKCS8 DER blob.
+ *
+ * Strips the 16-byte ASN.1 header. Validates prefix matches X25519 OID.
+ *
+ * @param pkcs8 - 48-byte PKCS8 DER for X25519.
+ * @returns 32-byte raw private key or error.
+ */
+export declare function extractRawX25519(pkcs8: Uint8Array): Result<Uint8Array, IdentityError>;