@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/backup.js

@@ -1 +1,326 @@
-import{ok,err}from"./_deps/shared/index.js";import{toBase64,fromBase64}from"./crypto-utils.js";import{exportPKCS8,exportX25519PKCS8,importIdentity,exportMlKemSecretKey,exportMlKemPublicKey,exportMlDsaSecretKey,exportMlDsaPublicKey}from"./identity.js";const PBKDF2_ITERATIONS=31e4,SALT_LENGTH=16,IV_LENGTH=12,KEY_LENGTH=32;function toArrayBuffer(e){const t=new ArrayBuffer(e.byteLength);return new Uint8Array(t).set(e),t}async function deriveKey(e,t){try{if(16!==t.length)return err("INVALID_BACKUP");const r=await crypto.subtle.importKey("raw",(new TextEncoder).encode(e),"PBKDF2",!1,["deriveBits"]),a=new Uint8Array(await crypto.subtle.deriveBits({name:"PBKDF2",hash:"SHA-256",salt:toArrayBuffer(t),iterations:31e4},r,256)),o=await crypto.subtle.importKey("raw",toArrayBuffer(a),{name:"AES-GCM"},!1,["encrypt","decrypt"]);return ok(o)}catch{return err("PBKDF2_FAILED")}}async function serializeIdentity(e){try{const t=await exportPKCS8(e.privateKey);if(!t.ok)return err("EXPORT_FAILED");const r=await exportX25519PKCS8(e.x25519PrivateKey);if(!r.ok)return err("EXPORT_FAILED");const a=exportMlKemSecretKey(e),o=exportMlKemPublicKey(e),n=exportMlDsaSecretKey(e),i=exportMlDsaPublicKey(e),s=e.rotatedKeys?await Promise.all(e.rotatedKeys.map(async e=>{const t=await exportX25519PKCS8(e.x25519PrivateKey);if(!t.ok)throw new Error("Failed to export rotated X25519 key");return{rotatedAt:e.rotatedAt,x25519Pkcs8:toBase64(t.value),...e.mlKemSecretKey?{mlKemSecretKey:toBase64(e.mlKemSecretKey)}:{}}})):void 0;return ok({did:e.did,rawPublicKey:toBase64(e.rawPublicKey),ed25519Pkcs8:toBase64(t.value),x25519Pkcs8:toBase64(r.value),...a?{mlKemSecretKey:toBase64(a)}:{},...o?{mlKemPublicKey:toBase64(o)}:{},...n?{mlDsaSecretKey:toBase64(n)}:{},...i?{mlDsaPublicKey:toBase64(i)}:{},...s?{rotatedKeys:s}:{},exportedAt:Date.now()})}catch{return err("EXPORT_FAILED")}}export async function exportBackup(e,t){try{const r=await serializeIdentity(e);if(!r.ok)return r;const a=crypto.getRandomValues(new Uint8Array(16)),o=crypto.getRandomValues(new Uint8Array(12)),n=await deriveKey(t,a);if(!n.ok)return n;const i=JSON.stringify(r.value),s=(new TextEncoder).encode(i),c=await crypto.subtle.encrypt({name:"AES-GCM",iv:toArrayBuffer(o)},n.value,s),y=new Uint8Array(c);if(y.length<16)return err("ENCRYPTION_FAILED");const l=y.length-16,K=y.slice(0,l),m=y.slice(l);return ok({version:1,salt:toBase64(a),iv:toBase64(o),ciphertext:toBase64(K),tag:toBase64(m)})}catch{return err("ENCRYPTION_FAILED")}}export async function importBackup(e,t){try{if(1!==e.version)return err("INVALID_BACKUP");let r,a,o,n;try{r=fromBase64(e.salt),a=fromBase64(e.iv),o=fromBase64(e.ciphertext),n=fromBase64(e.tag)}catch{return err("INVALID_BACKUP")}if(16!==r.length||12!==a.length||16!==n.length)return err("INVALID_BACKUP");const i=await deriveKey(t,r);if(!i.ok)return i;const s=new Uint8Array(o.length+n.length);let c,y,l,K,m,u,d,f;s.set(o),s.set(n,o.length);try{c=await crypto.subtle.decrypt({name:"AES-GCM",iv:toArrayBuffer(a)},i.value,toArrayBuffer(s))}catch(e){return console.warn("[xBind] GCM verification failed:",e),err("INVALID_PASSWORD")}try{const e=(new TextDecoder).decode(c);y=JSON.parse(e)}catch{return err("INVALID_BACKUP")}if(!y.did||!y.ed25519Pkcs8||!y.x25519Pkcs8)return err("INVALID_BACKUP");try{l=fromBase64(y.ed25519Pkcs8),K=fromBase64(y.x25519Pkcs8),y.mlKemSecretKey&&(m=fromBase64(y.mlKemSecretKey)),y.mlKemPublicKey&&(u=fromBase64(y.mlKemPublicKey)),y.mlDsaSecretKey&&(d=fromBase64(y.mlDsaSecretKey)),y.mlDsaPublicKey&&(f=fromBase64(y.mlDsaPublicKey))}catch{return err("INVALID_BACKUP")}const B=await importIdentity(l,K,m,u,d,f);if(!B.ok)return err("IMPORT_FAILED");if(y.rotatedKeys&&y.rotatedKeys.length>0){const e=B.value,t=await Promise.all(y.rotatedKeys.map(async e=>{const t=fromBase64(e.x25519Pkcs8),r=await crypto.subtle.importKey("pkcs8",toArrayBuffer(t),{name:"X25519"},!0,["deriveBits"]),a=e.mlKemSecretKey?fromBase64(e.mlKemSecretKey):void 0;return{rotatedAt:e.rotatedAt,x25519PrivateKey:r,...a?{mlKemSecretKey:a}:{}}}));return ok({...e,rotatedKeys:t})}return B}catch(e){return console.warn("[xBind] Import backup failed:",e),err("DECRYPTION_FAILED")}}
+/**
+ * Encrypted Backup and Restore (RCV-3)
+ *
+ * Exports and imports encrypted identity and cryptographic state.
+ * Uses PBKDF2 (NIST SP 800-132) for key derivation and AES-256-GCM
+ * for authenticated encryption.
+ *
+ * @module backup
+ */
+import { ok, err } from"./_deps/shared/index.js";
+import { toBase64, fromBase64 } from './crypto-utils.js';
+import { exportPKCS8, exportX25519PKCS8, importIdentity, exportMlKemSecretKey, exportMlKemPublicKey, exportMlDsaSecretKey, exportMlDsaPublicKey, } from './identity.js';
+/* ── Constants ── */
+/** PBKDF2 iterations for key derivation (NIST SP 800-132 minimum: 100,000). */
+const PBKDF2_ITERATIONS = 310_000;
+/** PBKDF2 salt length in bytes. */
+const SALT_LENGTH = 16;
+/** AES-256-GCM IV length in bytes. */
+const IV_LENGTH = 12;
+/** AES-256-GCM key length in bytes. */
+const KEY_LENGTH = 32;
+/* ── Utility Functions ── */
+/**
+ * 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;
+}
+/**
+ * Derive a 256-bit AES key from password using PBKDF2-SHA256.
+ *
+ * Uses NIST SP 800-132 recommended parameters:
+ * - 310,000 iterations (as of 2025, recommended for 100ms delay on modern hardware)
+ * - SHA-256 as PRF
+ * - 16-byte salt
+ *
+ * @param password - User password (UTF-8 string).
+ * @param salt - 16-byte random salt.
+ * @returns AES-256 key or error.
+ */
+async function deriveKey(password, salt) {
+    try {
+        if (salt.length !== SALT_LENGTH) {
+            return err('INVALID_BACKUP');
+        }
+        // Import password as PBKDF2 base key
+        const baseKey = await crypto.subtle.importKey('raw', new TextEncoder().encode(password), 'PBKDF2', false, ['deriveBits']);
+        // Derive 256 bits (32 bytes) for AES-256
+        const derivedBits = new Uint8Array(await crypto.subtle.deriveBits({
+            name: 'PBKDF2',
+            hash: 'SHA-256',
+            salt: toArrayBuffer(salt),
+            iterations: PBKDF2_ITERATIONS,
+        }, baseKey, 256));
+        // Import derived key as AES-GCM key
+        const aesKey = await crypto.subtle.importKey('raw', toArrayBuffer(derivedBits), { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+        return ok(aesKey);
+    }
+    catch {
+        return err('PBKDF2_FAILED');
+    }
+}
+/**
+ * Serialize an AgentIdentity to a plaintext backup payload.
+ * (The payload is then encrypted before storage.)
+ */
+async function serializeIdentity(identity) {
+    try {
+        // Export Ed25519 and X25519 private keys as PKCS8
+        const ed25519PkResult = await exportPKCS8(identity.privateKey);
+        if (!ed25519PkResult.ok)
+            return err('EXPORT_FAILED');
+        const x25519PkResult = await exportX25519PKCS8(identity.x25519PrivateKey);
+        if (!x25519PkResult.ok)
+            return err('EXPORT_FAILED');
+        // Collect ML-KEM and ML-DSA keys if present
+        const mlKemSecretKey = exportMlKemSecretKey(identity);
+        const mlKemPublicKey = exportMlKemPublicKey(identity);
+        const mlDsaSecretKey = exportMlDsaSecretKey(identity);
+        const mlDsaPublicKey = exportMlDsaPublicKey(identity);
+        // Serialize rotated keys
+        const rotatedKeys = identity.rotatedKeys
+            ? await Promise.all(identity.rotatedKeys.map(async (rotated) => {
+                const x25519Pk = await exportX25519PKCS8(rotated.x25519PrivateKey);
+                if (!x25519Pk.ok)
+                    throw new Error('Failed to export rotated X25519 key');
+                return {
+                    rotatedAt: rotated.rotatedAt,
+                    x25519Pkcs8: toBase64(x25519Pk.value),
+                    ...(rotated.mlKemSecretKey ? { mlKemSecretKey: toBase64(rotated.mlKemSecretKey) } : {}),
+                };
+            }))
+            : undefined;
+        return ok({
+            did: identity.did,
+            rawPublicKey: toBase64(identity.rawPublicKey),
+            ed25519Pkcs8: toBase64(ed25519PkResult.value),
+            x25519Pkcs8: toBase64(x25519PkResult.value),
+            ...(mlKemSecretKey ? { mlKemSecretKey: toBase64(mlKemSecretKey) } : {}),
+            ...(mlKemPublicKey ? { mlKemPublicKey: toBase64(mlKemPublicKey) } : {}),
+            ...(mlDsaSecretKey ? { mlDsaSecretKey: toBase64(mlDsaSecretKey) } : {}),
+            ...(mlDsaPublicKey ? { mlDsaPublicKey: toBase64(mlDsaPublicKey) } : {}),
+            ...(rotatedKeys ? { rotatedKeys } : {}),
+            exportedAt: Date.now(),
+        });
+    }
+    catch {
+        return err('EXPORT_FAILED');
+    }
+}
+/* ── Export: Encrypt Identity to Backup ── */
+/**
+ * Export an identity as an encrypted backup blob.
+ *
+ * Encrypts the complete identity (Ed25519, X25519, ML-KEM, ML-DSA keys,
+ * rotated keys) with a password using PBKDF2 + AES-256-GCM.
+ *
+ * The backup can be stored safely in cloud storage, version control, or
+ * transmitted over untrusted channels. Only the password holder can decrypt.
+ *
+ * Security:
+ * - PBKDF2-SHA256 with 310,000 iterations (≈100ms on modern hardware)
+ * - AES-256-GCM for authenticated encryption
+ * - Random salt + IV for each backup (no two backups are identical)
+ * - 16-byte GCM tag prevents tampering
+ *
+ * @param identity - Agent identity to backup.
+ * @param password - User password (plaintext). Will be PBKDF2 derived.
+ * @returns Encrypted backup blob or error.
+ *
+ * @example
+ * ```typescript
+ * import { generateIdentity } from '@private.me/xbind';
+ * import { exportBackup } from '@private.me/xbind';
+ *
+ * const identity = await generateIdentity();
+ * if (!identity.ok) throw identity.error;
+ *
+ * const backup = await exportBackup(identity.value, 'user-password');
+ * if (!backup.ok) throw backup.error;
+ *
+ * // Store backup securely
+ * const json = JSON.stringify(backup.value);
+ * localStorage.setItem('backup', json);
+ * ```
+ */
+export async function exportBackup(identity, password) {
+    try {
+        // Serialize identity to plaintext payload
+        const payloadResult = await serializeIdentity(identity);
+        if (!payloadResult.ok)
+            return payloadResult;
+        // Generate random salt and IV
+        const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+        const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+        // Derive AES key from password
+        const keyResult = await deriveKey(password, salt);
+        if (!keyResult.ok)
+            return keyResult;
+        // Encrypt payload as JSON
+        const payloadJson = JSON.stringify(payloadResult.value);
+        const plaintext = new TextEncoder().encode(payloadJson);
+        // Encrypt with AES-256-GCM
+        const encryptResult = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: toArrayBuffer(iv) }, keyResult.value, plaintext);
+        const ciphertext = new Uint8Array(encryptResult);
+        // GCM includes authentication tag in the ciphertext.
+        // Split: ciphertext is everything except last 16 bytes, tag is last 16 bytes.
+        // (Web Crypto API appends the tag to the ciphertext)
+        if (ciphertext.length < 16) {
+            return err('ENCRYPTION_FAILED');
+        }
+        const ctLen = ciphertext.length - 16;
+        const ct = ciphertext.slice(0, ctLen);
+        const tag = ciphertext.slice(ctLen);
+        return ok({
+            version: 1,
+            salt: toBase64(salt),
+            iv: toBase64(iv),
+            ciphertext: toBase64(ct),
+            tag: toBase64(tag),
+        });
+    }
+    catch {
+        return err('ENCRYPTION_FAILED');
+    }
+}
+/* ── Import: Decrypt Backup to Identity ── */
+/**
+ * Restore an identity from an encrypted backup blob.
+ *
+ * Decrypts the backup using PBKDF2-derived AES key. Verifies authenticity
+ * with GCM tag before returning plaintext keys.
+ *
+ * @param backup - Encrypted backup blob.
+ * @param password - User password (plaintext). Will be PBKDF2 derived.
+ * @returns Restored AgentIdentity or error.
+ *
+ * @example
+ * ```typescript
+ * import { importBackup } from '@private.me/xbind';
+ *
+ * const json = localStorage.getItem('backup');
+ * const backup = JSON.parse(json);
+ *
+ * const identity = await importBackup(backup, 'user-password');
+ * if (!identity.ok) {
+ *   if (identity.error === 'INVALID_PASSWORD') {
+ *     console.error('Wrong password!');
+ *   } else {
+ *     throw identity.error;
+ *   }
+ * }
+ *
+ * // Now use restored identity
+ * const agent = new Agent(identity.value);
+ * ```
+ */
+export async function importBackup(backup, password) {
+    try {
+        // Validate version
+        if (backup.version !== 1) {
+            return err('INVALID_BACKUP');
+        }
+        // Decode base64 fields
+        let salt;
+        let iv;
+        let ciphertext;
+        let tag;
+        try {
+            salt = fromBase64(backup.salt);
+            iv = fromBase64(backup.iv);
+            ciphertext = fromBase64(backup.ciphertext);
+            tag = fromBase64(backup.tag);
+        }
+        catch {
+            return err('INVALID_BACKUP');
+        }
+        // Validate lengths
+        if (salt.length !== SALT_LENGTH || iv.length !== IV_LENGTH || tag.length !== 16) {
+            return err('INVALID_BACKUP');
+        }
+        // Derive AES key from password
+        const keyResult = await deriveKey(password, salt);
+        if (!keyResult.ok)
+            return keyResult;
+        // Reconstruct full GCM input (ciphertext + tag)
+        const gcmInput = new Uint8Array(ciphertext.length + tag.length);
+        gcmInput.set(ciphertext);
+        gcmInput.set(tag, ciphertext.length);
+        // Decrypt with AES-256-GCM
+        let plaintext;
+        try {
+            plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: toArrayBuffer(iv) }, keyResult.value, toArrayBuffer(gcmInput));
+        }
+        catch (decryptErr) {
+            // GCM authentication failure (wrong password or tampered backup)
+            console.warn('[xBind] GCM verification failed:', decryptErr);
+            return err('INVALID_PASSWORD');
+        }
+        // Parse JSON payload
+        let payload;
+        try {
+            const jsonStr = new TextDecoder().decode(plaintext);
+            payload = JSON.parse(jsonStr);
+        }
+        catch {
+            return err('INVALID_BACKUP');
+        }
+        // Validate payload structure
+        if (!payload.did || !payload.ed25519Pkcs8 || !payload.x25519Pkcs8) {
+            return err('INVALID_BACKUP');
+        }
+        // Decode base64 keys
+        let ed25519Pkcs8;
+        let x25519Pkcs8;
+        let mlKemSecretKey;
+        let mlKemPublicKey;
+        let mlDsaSecretKey;
+        let mlDsaPublicKey;
+        try {
+            ed25519Pkcs8 = fromBase64(payload.ed25519Pkcs8);
+            x25519Pkcs8 = fromBase64(payload.x25519Pkcs8);
+            if (payload.mlKemSecretKey)
+                mlKemSecretKey = fromBase64(payload.mlKemSecretKey);
+            if (payload.mlKemPublicKey)
+                mlKemPublicKey = fromBase64(payload.mlKemPublicKey);
+            if (payload.mlDsaSecretKey)
+                mlDsaSecretKey = fromBase64(payload.mlDsaSecretKey);
+            if (payload.mlDsaPublicKey)
+                mlDsaPublicKey = fromBase64(payload.mlDsaPublicKey);
+        }
+        catch {
+            return err('INVALID_BACKUP');
+        }
+        // Import identity from decoded keys
+        const identity = await importIdentity(ed25519Pkcs8, x25519Pkcs8, mlKemSecretKey, mlKemPublicKey, mlDsaSecretKey, mlDsaPublicKey);
+        if (!identity.ok)
+            return err('IMPORT_FAILED');
+        // Restore rotated keys if present
+        if (payload.rotatedKeys && payload.rotatedKeys.length > 0) {
+            const restored = identity.value;
+            const rotatedKeys = await Promise.all(payload.rotatedKeys.map(async (rk) => {
+                const x25519Pk = fromBase64(rk.x25519Pkcs8);
+                const x25519PrivateKey = await crypto.subtle.importKey('pkcs8', toArrayBuffer(x25519Pk), { name: 'X25519' }, true, ['deriveBits']);
+                const mlKemSecretKeyRk = rk.mlKemSecretKey ? fromBase64(rk.mlKemSecretKey) : undefined;
+                return {
+                    rotatedAt: rk.rotatedAt,
+                    x25519PrivateKey,
+                    ...(mlKemSecretKeyRk ? { mlKemSecretKey: mlKemSecretKeyRk } : {}),
+                };
+            }));
+            // Return identity with restored rotated keys
+            return ok({
+                ...restored,
+                rotatedKeys: rotatedKeys,
+            });
+        }
+        return identity;
+    }
+    catch (importErr) {
+        console.warn('[xBind] Import backup failed:', importErr);
+        return err('DECRYPTION_FAILED');
+    }
+}