@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/identity.js

@@ -1 +1,619 @@
-import{ok,err}from"./_deps/shared/index.js";import{fromBase64Url}from"./crypto-utils.js";import{createMlKem768}from"mlkem";import mldsa from"./_deps/mldsa-wasm/dist/mldsa.js";const ED25519_MULTICODEC=new Uint8Array([237,1]),BASE58_ALPHABET="123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";function toArrayBuffer(e){const r=new ArrayBuffer(e.byteLength);return new Uint8Array(r).set(e),r}export async function generateIdentity(e){try{const r=await crypto.subtle.generateKey("Ed25519",!0,["sign","verify"]),t=new Uint8Array(await crypto.subtle.exportKey("raw",r.publicKey)),n=publicKeyToDid(t),a=await crypto.subtle.generateKey({name:"X25519"},!0,["deriveBits"]),i=new Uint8Array(await crypto.subtle.exportKey("raw",a.publicKey));let o,c,y,s;try{const e=await createMlKem768(),[r,t]=e.generateKeyPair();o=r,c=t}catch(e){console.warn("[xBind] ML-KEM-768 keygen failed, using classical crypto only:",e)}if(e?.postQuantumSig)try{const e=await mldsa.generateKey("ML-DSA-65",!0,["sign","verify"]),r=await mldsa.exportKey("raw-public",e.publicKey),t=await mldsa.exportKey("raw-seed",e.privateKey);y=new Uint8Array(r),s=new Uint8Array(t)}catch(e){console.warn("[xBind] ML-DSA-65 keygen failed, using classical crypto only:",e)}return ok({did:n,publicKey:r.publicKey,privateKey:r.privateKey,rawPublicKey:t,x25519PrivateKey:a.privateKey,x25519PublicKey:a.publicKey,rawX25519PublicKey:i,...o?{mlKemPublicKey:o}:{},...c?{mlKemSecretKey:c}:{},...y?{mlDsaPublicKey:y}:{},...s?{mlDsaSecretKey:s}:{}})}catch{return err("KEYGEN_FAILED")}}export async function sign(e,r){try{const t=new Uint8Array(await crypto.subtle.sign("Ed25519",e,toArrayBuffer(r)));return ok(t)}catch{return err("SIGN_FAILED")}}export async function verify(e,r,t){try{const n=await crypto.subtle.verify("Ed25519",e,toArrayBuffer(r),toArrayBuffer(t));return ok(n)}catch{return err("VERIFY_FAILED")}}export async function importPublicKey(e){if(32!==e.length)return err("INVALID_KEY_LENGTH");try{const r=await crypto.subtle.importKey("raw",toArrayBuffer(e),"Ed25519",!0,["verify"]);return ok(r)}catch{return err("KEYGEN_FAILED")}}export function publicKeyToDid(e){const r=new Uint8Array(2+e.length);return r.set(ED25519_MULTICODEC),r.set(e,2),`did:key:z${base58btcEncode(r)}`}export function didToPublicKeyBytes(e){if(!e.startsWith("did:key:z"))return err("INVALID_DID");try{const r=base58btcDecode(e.slice(9));return 237!==r[0]||1!==r[1]||34!==r.length?err("INVALID_DID"):ok(r.slice(2))}catch{return err("INVALID_DID")}}export async function exportPKCS8(e){try{const r=await crypto.subtle.exportKey("pkcs8",e);return ok(new Uint8Array(r))}catch{return err("EXPORT_FAILED")}}export async function exportX25519PKCS8(e){try{const r=await crypto.subtle.exportKey("pkcs8",e);return ok(new Uint8Array(r))}catch{return err("EXPORT_FAILED")}}export async function importFromPKCS8(e){try{const r=await crypto.subtle.importKey("pkcs8",toArrayBuffer(e),"Ed25519",!0,["sign"]),t=await crypto.subtle.exportKey("jwk",r);if(!t.x)return err("IMPORT_FAILED");const n=fromBase64Url(t.x),a=await crypto.subtle.importKey("raw",toArrayBuffer(n),"Ed25519",!0,["verify"]),i=publicKeyToDid(n),o=await crypto.subtle.generateKey({name:"X25519"},!0,["deriveBits"]),c=new Uint8Array(await crypto.subtle.exportKey("raw",o.publicKey));return ok({did:i,publicKey:a,privateKey:r,rawPublicKey:n,x25519PrivateKey:o.privateKey,x25519PublicKey:o.publicKey,rawX25519PublicKey:c})}catch{return err("IMPORT_FAILED")}}export async function importIdentity(e,r,t,n,a,i){try{const o=await crypto.subtle.importKey("pkcs8",toArrayBuffer(e),"Ed25519",!0,["sign"]),c=await crypto.subtle.exportKey("jwk",o);if(!c.x)return err("IMPORT_FAILED");const y=fromBase64Url(c.x),s=await crypto.subtle.importKey("raw",toArrayBuffer(y),"Ed25519",!0,["verify"]),l=publicKeyToDid(y),u=await crypto.subtle.importKey("pkcs8",toArrayBuffer(r),{name:"X25519"},!0,["deriveBits"]),K=await crypto.subtle.exportKey("jwk",u);if(!K.x)return err("IMPORT_FAILED");const p=fromBase64Url(K.x),f=await crypto.subtle.importKey("raw",toArrayBuffer(p),{name:"X25519"},!0,[]);return ok({did:l,publicKey:s,privateKey:o,rawPublicKey:y,x25519PrivateKey:u,x25519PublicKey:f,rawX25519PublicKey:p,...t?{mlKemSecretKey:t}:{},...n?{mlKemPublicKey:n}:{},...a?{mlDsaSecretKey:a}:{},...i?{mlDsaPublicKey:i}:{}})}catch{return err("IMPORT_FAILED")}}export function exportMlKemSecretKey(e){return e.mlKemSecretKey}export function exportMlKemPublicKey(e){return e.mlKemPublicKey}export const ML_DSA65_SIG_BYTES=3309;export const ML_DSA65_PK_BYTES=1952;export const ML_DSA65_SK_BYTES=32;export async function signMlDsa65(e,r){try{const t=await mldsa.importKey("raw-seed",toArrayBuffer(e),"ML-DSA-65",!1,["sign"]),n=await mldsa.sign("ML-DSA-65",t,toArrayBuffer(r));return ok(new Uint8Array(n))}catch{return err("SIGN_FAILED")}}export async function verifyMlDsa65(e,r,t){try{const n=await mldsa.importKey("raw-public",toArrayBuffer(e),"ML-DSA-65",!1,["verify"]),a=await mldsa.verify("ML-DSA-65",n,toArrayBuffer(r),toArrayBuffer(t));return ok(a)}catch{return err("VERIFY_FAILED")}}export function exportMlDsaSecretKey(e){return e.mlDsaSecretKey}export function exportMlDsaPublicKey(e){return e.mlDsaPublicKey}const ED25519_PKCS8_PREFIX=new Uint8Array([48,46,2,1,0,48,5,6,3,43,101,112,4,34,4,32]),X25519_PKCS8_PREFIX=new Uint8Array([48,46,2,1,0,48,5,6,3,43,101,110,4,34,4,32]);export async function identityFromSeed(e,r){if(32!==e.length)return err("INVALID_KEY_LENGTH");try{const t=await crypto.subtle.importKey("raw",toArrayBuffer(e),"HKDF",!1,["deriveBits"]),n=new Uint8Array(await crypto.subtle.deriveBits({name:"HKDF",hash:"SHA-256",salt:new Uint8Array(32),info:(new TextEncoder).encode("ed25519")},t,256)),a=new Uint8Array(await crypto.subtle.deriveBits({name:"HKDF",hash:"SHA-256",salt:new Uint8Array(32),info:(new TextEncoder).encode("x25519")},t,256)),i=new Uint8Array(await crypto.subtle.deriveBits({name:"HKDF",hash:"SHA-256",salt:new Uint8Array(32),info:(new TextEncoder).encode("ml-kem-768")},t,512)),o=new Uint8Array(ED25519_PKCS8_PREFIX.length+n.length);o.set(ED25519_PKCS8_PREFIX),o.set(n,ED25519_PKCS8_PREFIX.length);const c=new Uint8Array(X25519_PKCS8_PREFIX.length+a.length);let y,s,l,u;c.set(X25519_PKCS8_PREFIX),c.set(a,X25519_PKCS8_PREFIX.length);try{const e=await createMlKem768(),[r,t]=e.deriveKeyPair(i);y=r,s=t}catch(e){console.warn("[xBind] ML-KEM-768 keygen failed, using classical crypto only:",e)}if(r?.postQuantumSig)try{const e=new Uint8Array(await crypto.subtle.deriveBits({name:"HKDF",hash:"SHA-256",salt:new Uint8Array(32),info:(new TextEncoder).encode("ml-dsa-65")},t,256)),r=await mldsa.importKey("raw-seed",e,"ML-DSA-65",!0,["sign"]),n=await mldsa.getPublicKey(r,["verify"]),a=await mldsa.exportKey("raw-public",n);u=new Uint8Array(a),l=e}catch(e){console.warn("[xBind] ML-DSA-65 keygen failed, using classical crypto only:",e)}return importIdentity(o,c,s,y,l,u)}catch{return err("KEYGEN_FAILED")}}export function extractRawEd25519(e){if(e.length!==ED25519_PKCS8_PREFIX.length+32)return err("INVALID_KEY_LENGTH");for(let r=0;r<ED25519_PKCS8_PREFIX.length;r++)if(e[r]!==ED25519_PKCS8_PREFIX[r])return err("IMPORT_FAILED");return ok(e.slice(ED25519_PKCS8_PREFIX.length))}export function extractRawX25519(e){if(e.length!==X25519_PKCS8_PREFIX.length+32)return err("INVALID_KEY_LENGTH");for(let r=0;r<X25519_PKCS8_PREFIX.length;r++)if(e[r]!==X25519_PKCS8_PREFIX[r])return err("IMPORT_FAILED");return ok(e.slice(X25519_PKCS8_PREFIX.length))}export async function rotateKeys(e){try{const r=e.rotatedKeys??[],t={rotatedAt:Date.now(),x25519PrivateKey:e.x25519PrivateKey,mlKemSecretKey:e.mlKemSecretKey},n=await crypto.subtle.generateKey({name:"X25519"},!0,["deriveBits"]),a=new Uint8Array(await crypto.subtle.exportKey("raw",n.publicKey));let i,o;if(e.mlKemPublicKey||e.mlKemSecretKey)try{const e=await createMlKem768(),[r,t]=e.generateKeyPair();i=r,o=t}catch(e){console.warn("[xBind] ML-KEM-768 rotation failed, using X25519 only:",e)}const c=[t,...r].slice(0,10);return ok({did:e.did,publicKey:e.publicKey,privateKey:e.privateKey,rawPublicKey:e.rawPublicKey,x25519PrivateKey:n.privateKey,x25519PublicKey:n.publicKey,rawX25519PublicKey:a,mlKemPublicKey:i,mlKemSecretKey:o,mlDsaPublicKey:e.mlDsaPublicKey,mlDsaSecretKey:e.mlDsaSecretKey,rotatedKeys:c})}catch{return err("ROTATION_FAILED")}}function base58btcEncode(e){let r=0;for(const t of e){if(0!==t)break;r++}let t=0n;for(const r of e)t=256n*t+BigInt(r);const n=[];for(;t>0n;){const e=BASE58_ALPHABET[Number(t%58n)];void 0!==e&&n.unshift(e),t/=58n}for(let e=0;e<r;e++)n.unshift("1");return n.join("")}function base58btcDecode(e){let r=0;for(const t of e){if("1"!==t)break;r++}let t=0n;for(const r of e){const e=BASE58_ALPHABET.indexOf(r);if(-1===e)throw new Error("Invalid base58 character");t=58n*t+BigInt(e)}if(0n===t)return new Uint8Array(r);const n=t.toString(16),a=n.length%2?"0"+n:n,i=a.length/2,o=new Uint8Array(r+i);for(let e=0;e<i;e++)o[r+e]=parseInt(a.slice(2*e,2*e+2),16);return o}
+import { ok, err } from"./_deps/shared/index.js";
+import { fromBase64Url } from './crypto-utils.js';
+import { createMlKem768 } from 'mlkem';
+import mldsa from"./_deps/mldsa-wasm/dist/mldsa.js";
+/** Ed25519 multicodec varint prefix. */
+const ED25519_MULTICODEC = new Uint8Array([0xed, 0x01]);
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** Copy Uint8Array to fresh ArrayBuffer (avoids SharedArrayBuffer type issues). */
+function toArrayBuffer(data) {
+    const buf = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buf).set(data);
+    return buf;
+}
+/* ── Key Generation ── */
+/**
+ * Generate a new Ed25519 agent identity.
+ * Creates keypair via Web Crypto API, derives did:key DID.
+ *
+ * @param opts - Optional configuration
+ * @param opts.postQuantumSig - Enable ML-DSA-65 post-quantum signatures (default: false)
+ * @returns Result containing the agent identity or error
+ *
+ * @example
+ * ```typescript
+ * import { generateIdentity } from '@private.me/xbind';
+ *
+ * // Generate identity with classical cryptography only
+ * const identity = await generateIdentity();
+ * if (!identity.ok) {
+ *   throw new Error(`Failed to generate identity: ${identity.error}`);
+ * }
+ * console.log('DID:', identity.value.did);
+ *
+ * // Generate identity with post-quantum signatures
+ * const pqIdentity = await generateIdentity({ postQuantumSig: true });
+ * if (pqIdentity.ok) {
+ *   console.log('Post-quantum DID:', pqIdentity.value.did);
+ *   console.log('Has ML-DSA key:', !!pqIdentity.value.mlDsaPublicKey);
+ * }
+ * ```
+ */
+export async function generateIdentity(opts) {
+    try {
+        // SAFETY: Ed25519 generateKey always returns CryptoKeyPair
+        const keyPair = await crypto.subtle.generateKey('Ed25519', true, ['sign', 'verify']);
+        const rawPub = new Uint8Array(await crypto.subtle.exportKey('raw', keyPair.publicKey));
+        const did = publicKeyToDid(rawPub);
+        // SAFETY: X25519 generateKey always returns CryptoKeyPair
+        const x25519Pair = await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits']);
+        const rawX25519Pub = new Uint8Array(await crypto.subtle.exportKey('raw', x25519Pair.publicKey));
+        // Generate ML-KEM-768 keypair for hybrid post-quantum KEM (always-on)
+        let mlKemPublicKey;
+        let mlKemSecretKey;
+        try {
+            const mlkem = await createMlKem768();
+            const [publicKey, secretKey] = mlkem.generateKeyPair();
+            mlKemPublicKey = publicKey;
+            mlKemSecretKey = secretKey;
+        }
+        catch (err) {
+            console.warn('[xBind] ML-KEM-768 keygen failed, using classical crypto only:', err);
+        }
+        // Generate ML-DSA-65 keypair only when opt-in flag is set
+        let mlDsaPublicKey;
+        let mlDsaSecretKey;
+        if (opts?.postQuantumSig) {
+            try {
+                const keypair = await mldsa.generateKey('ML-DSA-65', true, ['sign', 'verify']);
+                const publicKeyRaw = await mldsa.exportKey('raw-public', keypair.publicKey);
+                const secretKeySeed = await mldsa.exportKey('raw-seed', keypair.privateKey);
+                mlDsaPublicKey = new Uint8Array(publicKeyRaw);
+                // For storage, we need the full secret key, not just the seed
+                // We'll store the seed and regenerate when needed
+                mlDsaSecretKey = new Uint8Array(secretKeySeed);
+            }
+            catch (err) {
+                console.warn('[xBind] ML-DSA-65 keygen failed, using classical crypto only:', err);
+            }
+        }
+        return ok({
+            did,
+            publicKey: keyPair.publicKey,
+            privateKey: keyPair.privateKey,
+            rawPublicKey: rawPub,
+            x25519PrivateKey: x25519Pair.privateKey,
+            x25519PublicKey: x25519Pair.publicKey,
+            rawX25519PublicKey: rawX25519Pub,
+            ...(mlKemPublicKey ? { mlKemPublicKey } : {}),
+            ...(mlKemSecretKey ? { mlKemSecretKey } : {}),
+            ...(mlDsaPublicKey ? { mlDsaPublicKey } : {}),
+            ...(mlDsaSecretKey ? { mlDsaSecretKey } : {}),
+        });
+    }
+    catch {
+        return err('KEYGEN_FAILED');
+    }
+}
+/* ── Sign / Verify ── */
+/**
+ * Sign data with an Ed25519 private key.
+ * @returns 64-byte Ed25519 signature.
+ */
+export async function sign(privateKey, data) {
+    try {
+        const sig = new Uint8Array(await crypto.subtle.sign('Ed25519', privateKey, toArrayBuffer(data)));
+        return ok(sig);
+    }
+    catch {
+        return err('SIGN_FAILED');
+    }
+}
+/**
+ * Verify an Ed25519 signature.
+ * @returns true if valid, false if invalid (not an error).
+ */
+export async function verify(publicKey, signature, data) {
+    try {
+        const valid = await crypto.subtle.verify('Ed25519', publicKey, toArrayBuffer(signature), toArrayBuffer(data));
+        return ok(valid);
+    }
+    catch {
+        return err('VERIFY_FAILED');
+    }
+}
+/* ── Key Import ── */
+/**
+ * Import a raw 32-byte Ed25519 public key into a CryptoKey.
+ */
+export async function importPublicKey(rawPublicKey) {
+    if (rawPublicKey.length !== 32)
+        return err('INVALID_KEY_LENGTH');
+    try {
+        const key = await crypto.subtle.importKey('raw', toArrayBuffer(rawPublicKey), 'Ed25519', true, ['verify']);
+        return ok(key);
+    }
+    catch {
+        return err('KEYGEN_FAILED');
+    }
+}
+/* ── DID Conversion ── */
+/**
+ * Convert 32-byte Ed25519 public key to did:key DID.
+ * Format: did:key:z + base58btc(0xed01 || publicKey).
+ */
+export function publicKeyToDid(rawPublicKey) {
+    const prefixed = new Uint8Array(2 + rawPublicKey.length);
+    prefixed.set(ED25519_MULTICODEC);
+    prefixed.set(rawPublicKey, 2);
+    return `did:key:z${base58btcEncode(prefixed)}`;
+}
+/**
+ * Extract raw 32-byte public key bytes from a did:key DID.
+ */
+export function didToPublicKeyBytes(did) {
+    if (!did.startsWith('did:key:z'))
+        return err('INVALID_DID');
+    try {
+        const encoded = did.slice('did:key:z'.length);
+        const bytes = base58btcDecode(encoded);
+        if (bytes[0] !== 0xed || bytes[1] !== 0x01)
+            return err('INVALID_DID');
+        if (bytes.length !== 34)
+            return err('INVALID_DID');
+        return ok(bytes.slice(2));
+    }
+    catch {
+        return err('INVALID_DID');
+    }
+}
+/* ── PKCS8 Export/Import ── */
+/**
+ * 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 async function exportPKCS8(privateKey) {
+    try {
+        const buf = await crypto.subtle.exportKey('pkcs8', privateKey);
+        return ok(new Uint8Array(buf));
+    }
+    catch {
+        return err('EXPORT_FAILED');
+    }
+}
+/**
+ * Export an X25519 private key as PKCS8 DER bytes.
+ *
+ * @param privateKey - X25519 CryptoKey (must be extractable).
+ * @returns PKCS8 DER bytes or error.
+ */
+export async function exportX25519PKCS8(privateKey) {
+    try {
+        const buf = await crypto.subtle.exportKey('pkcs8', privateKey);
+        return ok(new Uint8Array(buf));
+    }
+    catch {
+        return err('EXPORT_FAILED');
+    }
+}
+/**
+ * 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 async function importFromPKCS8(pkcs8) {
+    try {
+        const privateKey = await crypto.subtle.importKey('pkcs8', toArrayBuffer(pkcs8), 'Ed25519', true, ['sign']);
+        // Extract public key from JWK (PKCS8 import returns only private key)
+        const jwk = await crypto.subtle.exportKey('jwk', privateKey);
+        if (!jwk.x)
+            return err('IMPORT_FAILED');
+        // JWK x field is base64url-encoded raw public key
+        const rawPub = fromBase64Url(jwk.x);
+        const publicKey = await crypto.subtle.importKey('raw', toArrayBuffer(rawPub), 'Ed25519', true, ['verify']);
+        const did = publicKeyToDid(rawPub);
+        // Generate fresh X25519 keypair for forward secrecy
+        // SAFETY: X25519 generateKey always returns CryptoKeyPair
+        const x25519Pair = await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits']);
+        const rawX25519Pub = new Uint8Array(await crypto.subtle.exportKey('raw', x25519Pair.publicKey));
+        return ok({
+            did,
+            publicKey,
+            privateKey,
+            rawPublicKey: rawPub,
+            x25519PrivateKey: x25519Pair.privateKey,
+            x25519PublicKey: x25519Pair.publicKey,
+            rawX25519PublicKey: rawX25519Pub,
+        });
+    }
+    catch {
+        return err('IMPORT_FAILED');
+    }
+}
+/**
+ * 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 async function importIdentity(ed25519Pkcs8, x25519Pkcs8, mlKemSecretKey, mlKemPublicKey, mlDsaSecretKey, mlDsaPublicKey) {
+    try {
+        const privateKey = await crypto.subtle.importKey('pkcs8', toArrayBuffer(ed25519Pkcs8), 'Ed25519', true, ['sign']);
+        const jwk = await crypto.subtle.exportKey('jwk', privateKey);
+        if (!jwk.x)
+            return err('IMPORT_FAILED');
+        const rawPub = fromBase64Url(jwk.x);
+        const publicKey = await crypto.subtle.importKey('raw', toArrayBuffer(rawPub), 'Ed25519', true, ['verify']);
+        const did = publicKeyToDid(rawPub);
+        const x25519PrivateKey = await crypto.subtle.importKey('pkcs8', toArrayBuffer(x25519Pkcs8), { name: 'X25519' }, true, ['deriveBits']);
+        const x25519Jwk = await crypto.subtle.exportKey('jwk', x25519PrivateKey);
+        if (!x25519Jwk.x)
+            return err('IMPORT_FAILED');
+        const rawX25519Pub = fromBase64Url(x25519Jwk.x);
+        const x25519PublicKey = await crypto.subtle.importKey('raw', toArrayBuffer(rawX25519Pub), { name: 'X25519' }, true, []);
+        return ok({
+            did,
+            publicKey,
+            privateKey,
+            rawPublicKey: rawPub,
+            x25519PrivateKey,
+            x25519PublicKey,
+            rawX25519PublicKey: rawX25519Pub,
+            ...(mlKemSecretKey ? { mlKemSecretKey } : {}),
+            ...(mlKemPublicKey ? { mlKemPublicKey } : {}),
+            ...(mlDsaSecretKey ? { mlDsaSecretKey } : {}),
+            ...(mlDsaPublicKey ? { mlDsaPublicKey } : {}),
+        });
+    }
+    catch {
+        return err('IMPORT_FAILED');
+    }
+}
+/* ── ML-KEM Key Export ── */
+/**
+ * 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 function exportMlKemSecretKey(identity) {
+    return identity.mlKemSecretKey;
+}
+/**
+ * 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 function exportMlKemPublicKey(identity) {
+    return identity.mlKemPublicKey;
+}
+/* ── ML-DSA-65 Sign / Verify ── */
+/** ML-DSA-65 signature length in bytes. */
+export const ML_DSA65_SIG_BYTES = 3309;
+/** ML-DSA-65 public key length in bytes. */
+export const ML_DSA65_PK_BYTES = 1952;
+/** ML-DSA-65 secret key seed length in bytes (using seed format for storage). */
+export 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 async function signMlDsa65(secretKey, data) {
+    try {
+        // Import secret key seed as CryptoKey
+        const privateKey = await mldsa.importKey('raw-seed', toArrayBuffer(secretKey), 'ML-DSA-65', false, ['sign']);
+        // Sign using mldsa-wasm API
+        const signature = await mldsa.sign('ML-DSA-65', privateKey, toArrayBuffer(data));
+        return ok(new Uint8Array(signature));
+    }
+    catch {
+        return err('SIGN_FAILED');
+    }
+}
+/**
+ * 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 async function verifyMlDsa65(publicKey, signature, data) {
+    try {
+        // Import public key as CryptoKey
+        const pubKey = await mldsa.importKey('raw-public', toArrayBuffer(publicKey), 'ML-DSA-65', false, ['verify']);
+        // Verify using mldsa-wasm API
+        const valid = await mldsa.verify('ML-DSA-65', pubKey, toArrayBuffer(signature), toArrayBuffer(data));
+        return ok(valid);
+    }
+    catch {
+        return err('VERIFY_FAILED');
+    }
+}
+/* ── ML-DSA Key Export ── */
+/**
+ * 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 function exportMlDsaSecretKey(identity) {
+    return identity.mlDsaSecretKey;
+}
+/**
+ * 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 function exportMlDsaPublicKey(identity) {
+    return identity.mlDsaPublicKey;
+}
+/* ── PKCS8 ASN.1 Prefixes ── */
+/**
+ * PKCS8 ASN.1 DER header for Ed25519 private keys (16 bytes).
+ * Structure: SEQUENCE { INTEGER(0), SEQUENCE { OID(1.3.101.112) }, OCTET STRING header }
+ * The 32-byte raw seed follows immediately after this prefix.
+ */
+const ED25519_PKCS8_PREFIX = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06,
+    0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+/**
+ * PKCS8 ASN.1 DER header for X25519 private keys (16 bytes).
+ * Structure: SEQUENCE { INTEGER(0), SEQUENCE { OID(1.3.101.110) }, OCTET STRING header }
+ * The 32-byte raw seed follows immediately after this prefix.
+ */
+const X25519_PKCS8_PREFIX = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06,
+    0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20,
+]);
+/* ── Deterministic Identity from Seed ── */
+/**
+ * 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 async function identityFromSeed(seed, opts) {
+    if (seed.length !== 32)
+        return err('INVALID_KEY_LENGTH');
+    try {
+        // Import seed as HKDF base key
+        const baseKey = await crypto.subtle.importKey('raw', toArrayBuffer(seed), 'HKDF', false, ['deriveBits']);
+        // Derive 32 bytes for Ed25519
+        const edBits = new Uint8Array(await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), info: new TextEncoder().encode('ed25519') }, baseKey, 256));
+        // Derive 32 bytes for X25519
+        const x25519Bits = new Uint8Array(await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), info: new TextEncoder().encode('x25519') }, baseKey, 256));
+        // Derive 64 bytes for ML-KEM-768
+        const mlKemBits = new Uint8Array(await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), info: new TextEncoder().encode('ml-kem-768') }, baseKey, 512));
+        // Wrap as PKCS8 and import
+        const edPkcs8 = new Uint8Array(ED25519_PKCS8_PREFIX.length + edBits.length);
+        edPkcs8.set(ED25519_PKCS8_PREFIX);
+        edPkcs8.set(edBits, ED25519_PKCS8_PREFIX.length);
+        const x25519Pkcs8 = new Uint8Array(X25519_PKCS8_PREFIX.length + x25519Bits.length);
+        x25519Pkcs8.set(X25519_PKCS8_PREFIX);
+        x25519Pkcs8.set(x25519Bits, X25519_PKCS8_PREFIX.length);
+        // Generate deterministic ML-KEM-768 keypair from derived seed (always-on)
+        let mlKemPublicKey;
+        let mlKemSecretKey;
+        try {
+            // Use deterministic key generation from 64-byte seed (FIPS 203 compliant)
+            const mlkem = await createMlKem768();
+            const [publicKey, secretKey] = mlkem.deriveKeyPair(mlKemBits);
+            mlKemPublicKey = publicKey;
+            mlKemSecretKey = secretKey;
+        }
+        catch (err) {
+            console.warn('[xBind] ML-KEM-768 keygen failed, using classical crypto only:', err);
+        }
+        // Generate ML-DSA-65 keypair only when opt-in flag is set
+        let mlDsaSecretKey;
+        let mlDsaPublicKey;
+        if (opts?.postQuantumSig) {
+            try {
+                const mlDsaBits = new Uint8Array(await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), info: new TextEncoder().encode('ml-dsa-65') }, baseKey, 256));
+                // Import seed and generate deterministic keypair
+                const privateKey = await mldsa.importKey('raw-seed', mlDsaBits, 'ML-DSA-65', true, ['sign']);
+                const publicKey = await mldsa.getPublicKey(privateKey, ['verify']);
+                const publicKeyRaw = await mldsa.exportKey('raw-public', publicKey);
+                mlDsaPublicKey = new Uint8Array(publicKeyRaw);
+                mlDsaSecretKey = mlDsaBits; // Store the seed for later use
+            }
+            catch (err) {
+                console.warn('[xBind] ML-DSA-65 keygen failed, using classical crypto only:', err);
+            }
+        }
+        return importIdentity(edPkcs8, x25519Pkcs8, mlKemSecretKey, mlKemPublicKey, mlDsaSecretKey, mlDsaPublicKey);
+    }
+    catch {
+        return err('KEYGEN_FAILED');
+    }
+}
+/**
+ * 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 function extractRawEd25519(pkcs8) {
+    if (pkcs8.length !== ED25519_PKCS8_PREFIX.length + 32) {
+        return err('INVALID_KEY_LENGTH');
+    }
+    for (let i = 0; i < ED25519_PKCS8_PREFIX.length; i++) {
+        if (pkcs8[i] !== ED25519_PKCS8_PREFIX[i])
+            return err('IMPORT_FAILED');
+    }
+    return ok(pkcs8.slice(ED25519_PKCS8_PREFIX.length));
+}
+/**
+ * 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 function extractRawX25519(pkcs8) {
+    if (pkcs8.length !== X25519_PKCS8_PREFIX.length + 32) {
+        return err('INVALID_KEY_LENGTH');
+    }
+    for (let i = 0; i < X25519_PKCS8_PREFIX.length; i++) {
+        if (pkcs8[i] !== X25519_PKCS8_PREFIX[i])
+            return err('IMPORT_FAILED');
+    }
+    return ok(pkcs8.slice(X25519_PKCS8_PREFIX.length));
+}
+/* ── Key Rotation (ROT-1) ── */
+/**
+ * Rotate ML-KEM + X25519 keys while preserving old keys for decryption.
+ *
+ * Generates new X25519 and ML-KEM-768 keypairs. Saves the old keys
+ * in rotatedKeys array (with timestamp) for backward-compatible decryption
+ * of messages encrypted with the old keys. Ed25519 keys (for signing) are
+ * NOT rotated — they remain constant for persistent identity.
+ *
+ * After rotation:
+ * - New messages use the new X25519 + ML-KEM keys
+ * - Old messages decrypt using preserved rotatedKeys
+ * - DID remains unchanged (anchored to Ed25519 public key)
+ * - Registry must be updated with new X25519 + ML-KEM public keys
+ *
+ * @param identity - Current identity with keys to rotate
+ * @returns Updated identity with new keys + old keys in rotatedKeys array, or error
+ *
+ * @example
+ * ```ts
+ * const rotated = await identity.rotateKeys();
+ * if (rotated.ok) {
+ *   // New keys are active; old keys preserved for decryption
+ *   console.log('Rotated at:', rotated.value.rotatedKeys?.[0]?.rotatedAt);
+ *   // Update registry with new X25519 + ML-KEM public keys
+ *   await registry.updateKeys(rotated.value.did, rotated.value.rawX25519PublicKey, rotated.value.mlKemPublicKey);
+ * }
+ * ```
+ */
+export async function rotateKeys(identity) {
+    try {
+        // Preserve old keys in rotatedKeys array
+        const oldRotatedKeys = identity.rotatedKeys ?? [];
+        const currentRotation = {
+            rotatedAt: Date.now(),
+            x25519PrivateKey: identity.x25519PrivateKey,
+            mlKemSecretKey: identity.mlKemSecretKey,
+        };
+        // Generate new X25519 keypair for forward secrecy
+        // SAFETY: X25519 generateKey always returns CryptoKeyPair
+        const newX25519Pair = await crypto.subtle.generateKey({ name: 'X25519' }, true, ['deriveBits']);
+        const newRawX25519Pub = new Uint8Array(await crypto.subtle.exportKey('raw', newX25519Pair.publicKey));
+        // Generate new ML-KEM-768 keypair (only if original identity had ML-KEM)
+        let newMlKemPublicKey;
+        let newMlKemSecretKey;
+        if (identity.mlKemPublicKey || identity.mlKemSecretKey) {
+            try {
+                const mlkem = await createMlKem768();
+                const [publicKey, secretKey] = mlkem.generateKeyPair();
+                newMlKemPublicKey = publicKey;
+                newMlKemSecretKey = secretKey;
+            }
+            catch (err) {
+                console.warn('[xBind] ML-KEM-768 rotation failed, using X25519 only:', err);
+            }
+        }
+        // Preserve rotation history (keep up to 10 old key sets for decryption)
+        const maxRotationHistory = 10;
+        const rotatedKeys = [
+            currentRotation,
+            ...oldRotatedKeys,
+        ].slice(0, maxRotationHistory);
+        return ok({
+            did: identity.did,
+            publicKey: identity.publicKey,
+            privateKey: identity.privateKey,
+            rawPublicKey: identity.rawPublicKey,
+            x25519PrivateKey: newX25519Pair.privateKey,
+            x25519PublicKey: newX25519Pair.publicKey,
+            rawX25519PublicKey: newRawX25519Pub,
+            mlKemPublicKey: newMlKemPublicKey,
+            mlKemSecretKey: newMlKemSecretKey,
+            mlDsaPublicKey: identity.mlDsaPublicKey,
+            mlDsaSecretKey: identity.mlDsaSecretKey,
+            rotatedKeys,
+        });
+    }
+    catch {
+        return err('ROTATION_FAILED');
+    }
+}
+/* ── Base58btc (internal) ── */
+/** Encode bytes to base58btc string. */
+function base58btcEncode(bytes) {
+    let zeros = 0;
+    for (const b of bytes) {
+        if (b !== 0)
+            break;
+        zeros++;
+    }
+    let num = 0n;
+    for (const b of bytes) {
+        num = num * 256n + BigInt(b);
+    }
+    const chars = [];
+    while (num > 0n) {
+        const ch = BASE58_ALPHABET[Number(num % 58n)];
+        if (ch !== undefined)
+            chars.unshift(ch);
+        num = num / 58n;
+    }
+    for (let i = 0; i < zeros; i++) {
+        chars.unshift('1');
+    }
+    return chars.join('');
+}
+/** Decode base58btc string to bytes. */
+function base58btcDecode(str) {
+    let zeros = 0;
+    for (const c of str) {
+        if (c !== '1')
+            break;
+        zeros++;
+    }
+    let num = 0n;
+    for (const c of str) {
+        const idx = BASE58_ALPHABET.indexOf(c);
+        if (idx === -1)
+            throw new Error('Invalid base58 character');
+        num = num * 58n + BigInt(idx);
+    }
+    if (num === 0n)
+        return new Uint8Array(zeros);
+    const hex = num.toString(16);
+    const paddedHex = hex.length % 2 ? '0' + hex : hex;
+    const byteLen = paddedHex.length / 2;
+    const result = new Uint8Array(zeros + byteLen);
+    for (let i = 0; i < byteLen; i++) {
+        result[zeros + i] = parseInt(paddedHex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return result;
+}