@private.me/xbind 3.0.2 → 3.0.4

package/dist-standalone/backup.js

@@ -1,326 +1 @@
-/**
- * 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');
-    }
-}
+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;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),s=exportMlDsaPublicKey(e),i=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)}:{},...s?{mlDsaPublicKey:toBase64(s)}:{},...i?{rotatedKeys:i}:{},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 s=JSON.stringify(r.value),i=(new TextEncoder).encode(s),c=await crypto.subtle.encrypt({name:"AES-GCM",iv:toArrayBuffer(o)},n.value,i),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 s=await deriveKey(t,r);if(!s.ok)return s;const i=new Uint8Array(o.length+n.length);let c,y,l,K,m,u,f,B;i.set(o),i.set(n,o.length);try{c=await crypto.subtle.decrypt({name:"AES-GCM",iv:toArrayBuffer(a)},s.value,toArrayBuffer(i))}catch{return 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&&(f=fromBase64(y.mlDsaSecretKey)),y.mlDsaPublicKey&&(B=fromBase64(y.mlDsaPublicKey))}catch{return err("INVALID_BACKUP")}const d=await importIdentity(l,K,m,u,f,B);if(!d.ok)return err("IMPORT_FAILED");if(y.rotatedKeys&&y.rotatedKeys.length>0){const e=d.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 d}catch{return err("DECRYPTION_FAILED")}}