@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/cjs/backup.js

@@ -1 +1,330 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.exportBackup=exportBackup,exports.importBackup=importBackup;const shared_1=require("../_deps/shared/index.js"),crypto_utils_js_1=require("./crypto-utils.js"),identity_js_1=require("./identity.js"),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(t.length!==SALT_LENGTH)return(0,shared_1.err)("INVALID_BACKUP");const r=await crypto.subtle.importKey("raw",(new TextEncoder).encode(e),"PBKDF2",!1,["deriveBits"]),s=new Uint8Array(await crypto.subtle.deriveBits({name:"PBKDF2",hash:"SHA-256",salt:toArrayBuffer(t),iterations:31e4},r,256)),a=await crypto.subtle.importKey("raw",toArrayBuffer(s),{name:"AES-GCM"},!1,["encrypt","decrypt"]);return(0,shared_1.ok)(a)}catch{return(0,shared_1.err)("PBKDF2_FAILED")}}async function serializeIdentity(e){try{const t=await(0,identity_js_1.exportPKCS8)(e.privateKey);if(!t.ok)return(0,shared_1.err)("EXPORT_FAILED");const r=await(0,identity_js_1.exportX25519PKCS8)(e.x25519PrivateKey);if(!r.ok)return(0,shared_1.err)("EXPORT_FAILED");const s=(0,identity_js_1.exportMlKemSecretKey)(e),a=(0,identity_js_1.exportMlKemPublicKey)(e),o=(0,identity_js_1.exportMlDsaSecretKey)(e),i=(0,identity_js_1.exportMlDsaPublicKey)(e),_=e.rotatedKeys?await Promise.all(e.rotatedKeys.map(async e=>{const t=await(0,identity_js_1.exportX25519PKCS8)(e.x25519PrivateKey);if(!t.ok)throw new Error("Failed to export rotated X25519 key");return{rotatedAt:e.rotatedAt,x25519Pkcs8:(0,crypto_utils_js_1.toBase64)(t.value),...e.mlKemSecretKey?{mlKemSecretKey:(0,crypto_utils_js_1.toBase64)(e.mlKemSecretKey)}:{}}})):void 0;return(0,shared_1.ok)({did:e.did,rawPublicKey:(0,crypto_utils_js_1.toBase64)(e.rawPublicKey),ed25519Pkcs8:(0,crypto_utils_js_1.toBase64)(t.value),x25519Pkcs8:(0,crypto_utils_js_1.toBase64)(r.value),...s?{mlKemSecretKey:(0,crypto_utils_js_1.toBase64)(s)}:{},...a?{mlKemPublicKey:(0,crypto_utils_js_1.toBase64)(a)}:{},...o?{mlDsaSecretKey:(0,crypto_utils_js_1.toBase64)(o)}:{},...i?{mlDsaPublicKey:(0,crypto_utils_js_1.toBase64)(i)}:{},..._?{rotatedKeys:_}:{},exportedAt:Date.now()})}catch{return(0,shared_1.err)("EXPORT_FAILED")}}async function exportBackup(e,t){try{const r=await serializeIdentity(e);if(!r.ok)return r;const s=crypto.getRandomValues(new Uint8Array(SALT_LENGTH)),a=crypto.getRandomValues(new Uint8Array(IV_LENGTH)),o=await deriveKey(t,s);if(!o.ok)return o;const i=JSON.stringify(r.value),_=(new TextEncoder).encode(i),c=await crypto.subtle.encrypt({name:"AES-GCM",iv:toArrayBuffer(a)},o.value,_),n=new Uint8Array(c);if(n.length<16)return(0,shared_1.err)("ENCRYPTION_FAILED");const y=n.length-16,u=n.slice(0,y),l=n.slice(y);return(0,shared_1.ok)({version:1,salt:(0,crypto_utils_js_1.toBase64)(s),iv:(0,crypto_utils_js_1.toBase64)(a),ciphertext:(0,crypto_utils_js_1.toBase64)(u),tag:(0,crypto_utils_js_1.toBase64)(l)})}catch{return(0,shared_1.err)("ENCRYPTION_FAILED")}}async function importBackup(e,t){try{if(1!==e.version)return(0,shared_1.err)("INVALID_BACKUP");let r,s,a,o;try{r=(0,crypto_utils_js_1.fromBase64)(e.salt),s=(0,crypto_utils_js_1.fromBase64)(e.iv),a=(0,crypto_utils_js_1.fromBase64)(e.ciphertext),o=(0,crypto_utils_js_1.fromBase64)(e.tag)}catch{return(0,shared_1.err)("INVALID_BACKUP")}if(r.length!==SALT_LENGTH||s.length!==IV_LENGTH||16!==o.length)return(0,shared_1.err)("INVALID_BACKUP");const i=await deriveKey(t,r);if(!i.ok)return i;const _=new Uint8Array(a.length+o.length);let c,n,y,u,l,d,p,K;_.set(a),_.set(o,a.length);try{c=await crypto.subtle.decrypt({name:"AES-GCM",iv:toArrayBuffer(s)},i.value,toArrayBuffer(_))}catch(e){return console.warn("[xBind] GCM verification failed:",e),(0,shared_1.err)("INVALID_PASSWORD")}try{const e=(new TextDecoder).decode(c);n=JSON.parse(e)}catch{return(0,shared_1.err)("INVALID_BACKUP")}if(!n.did||!n.ed25519Pkcs8||!n.x25519Pkcs8)return(0,shared_1.err)("INVALID_BACKUP");try{y=(0,crypto_utils_js_1.fromBase64)(n.ed25519Pkcs8),u=(0,crypto_utils_js_1.fromBase64)(n.x25519Pkcs8),n.mlKemSecretKey&&(l=(0,crypto_utils_js_1.fromBase64)(n.mlKemSecretKey)),n.mlKemPublicKey&&(d=(0,crypto_utils_js_1.fromBase64)(n.mlKemPublicKey)),n.mlDsaSecretKey&&(p=(0,crypto_utils_js_1.fromBase64)(n.mlDsaSecretKey)),n.mlDsaPublicKey&&(K=(0,crypto_utils_js_1.fromBase64)(n.mlDsaPublicKey))}catch{return(0,shared_1.err)("INVALID_BACKUP")}const m=await(0,identity_js_1.importIdentity)(y,u,l,d,p,K);if(!m.ok)return(0,shared_1.err)("IMPORT_FAILED");if(n.rotatedKeys&&n.rotatedKeys.length>0){const e=m.value,t=await Promise.all(n.rotatedKeys.map(async e=>{const t=(0,crypto_utils_js_1.fromBase64)(e.x25519Pkcs8),r=await crypto.subtle.importKey("pkcs8",toArrayBuffer(t),{name:"X25519"},!0,["deriveBits"]),s=e.mlKemSecretKey?(0,crypto_utils_js_1.fromBase64)(e.mlKemSecretKey):void 0;return{rotatedAt:e.rotatedAt,x25519PrivateKey:r,...s?{mlKemSecretKey:s}:{}}}));return(0,shared_1.ok)({...e,rotatedKeys:t})}return m}catch(e){return console.warn("[xBind] Import backup failed:",e),(0,shared_1.err)("DECRYPTION_FAILED")}}
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportBackup = exportBackup;
+exports.importBackup = importBackup;
+const shared_1 = require("../_deps/shared/index.js");
+const crypto_utils_js_1 = require("./crypto-utils.js");
+const identity_js_1 = require("./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 (0, shared_1.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 (0, shared_1.ok)(aesKey);
+    }
+    catch {
+        return (0, shared_1.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 (0, identity_js_1.exportPKCS8)(identity.privateKey);
+        if (!ed25519PkResult.ok)
+            return (0, shared_1.err)('EXPORT_FAILED');
+        const x25519PkResult = await (0, identity_js_1.exportX25519PKCS8)(identity.x25519PrivateKey);
+        if (!x25519PkResult.ok)
+            return (0, shared_1.err)('EXPORT_FAILED');
+        // Collect ML-KEM and ML-DSA keys if present
+        const mlKemSecretKey = (0, identity_js_1.exportMlKemSecretKey)(identity);
+        const mlKemPublicKey = (0, identity_js_1.exportMlKemPublicKey)(identity);
+        const mlDsaSecretKey = (0, identity_js_1.exportMlDsaSecretKey)(identity);
+        const mlDsaPublicKey = (0, identity_js_1.exportMlDsaPublicKey)(identity);
+        // Serialize rotated keys
+        const rotatedKeys = identity.rotatedKeys
+            ? await Promise.all(identity.rotatedKeys.map(async (rotated) => {
+                const x25519Pk = await (0, identity_js_1.exportX25519PKCS8)(rotated.x25519PrivateKey);
+                if (!x25519Pk.ok)
+                    throw new Error('Failed to export rotated X25519 key');
+                return {
+                    rotatedAt: rotated.rotatedAt,
+                    x25519Pkcs8: (0, crypto_utils_js_1.toBase64)(x25519Pk.value),
+                    ...(rotated.mlKemSecretKey ? { mlKemSecretKey: (0, crypto_utils_js_1.toBase64)(rotated.mlKemSecretKey) } : {}),
+                };
+            }))
+            : undefined;
+        return (0, shared_1.ok)({
+            did: identity.did,
+            rawPublicKey: (0, crypto_utils_js_1.toBase64)(identity.rawPublicKey),
+            ed25519Pkcs8: (0, crypto_utils_js_1.toBase64)(ed25519PkResult.value),
+            x25519Pkcs8: (0, crypto_utils_js_1.toBase64)(x25519PkResult.value),
+            ...(mlKemSecretKey ? { mlKemSecretKey: (0, crypto_utils_js_1.toBase64)(mlKemSecretKey) } : {}),
+            ...(mlKemPublicKey ? { mlKemPublicKey: (0, crypto_utils_js_1.toBase64)(mlKemPublicKey) } : {}),
+            ...(mlDsaSecretKey ? { mlDsaSecretKey: (0, crypto_utils_js_1.toBase64)(mlDsaSecretKey) } : {}),
+            ...(mlDsaPublicKey ? { mlDsaPublicKey: (0, crypto_utils_js_1.toBase64)(mlDsaPublicKey) } : {}),
+            ...(rotatedKeys ? { rotatedKeys } : {}),
+            exportedAt: Date.now(),
+        });
+    }
+    catch {
+        return (0, shared_1.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);
+ * ```
+ */
+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 (0, shared_1.err)('ENCRYPTION_FAILED');
+        }
+        const ctLen = ciphertext.length - 16;
+        const ct = ciphertext.slice(0, ctLen);
+        const tag = ciphertext.slice(ctLen);
+        return (0, shared_1.ok)({
+            version: 1,
+            salt: (0, crypto_utils_js_1.toBase64)(salt),
+            iv: (0, crypto_utils_js_1.toBase64)(iv),
+            ciphertext: (0, crypto_utils_js_1.toBase64)(ct),
+            tag: (0, crypto_utils_js_1.toBase64)(tag),
+        });
+    }
+    catch {
+        return (0, shared_1.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);
+ * ```
+ */
+async function importBackup(backup, password) {
+    try {
+        // Validate version
+        if (backup.version !== 1) {
+            return (0, shared_1.err)('INVALID_BACKUP');
+        }
+        // Decode base64 fields
+        let salt;
+        let iv;
+        let ciphertext;
+        let tag;
+        try {
+            salt = (0, crypto_utils_js_1.fromBase64)(backup.salt);
+            iv = (0, crypto_utils_js_1.fromBase64)(backup.iv);
+            ciphertext = (0, crypto_utils_js_1.fromBase64)(backup.ciphertext);
+            tag = (0, crypto_utils_js_1.fromBase64)(backup.tag);
+        }
+        catch {
+            return (0, shared_1.err)('INVALID_BACKUP');
+        }
+        // Validate lengths
+        if (salt.length !== SALT_LENGTH || iv.length !== IV_LENGTH || tag.length !== 16) {
+            return (0, shared_1.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 (0, shared_1.err)('INVALID_PASSWORD');
+        }
+        // Parse JSON payload
+        let payload;
+        try {
+            const jsonStr = new TextDecoder().decode(plaintext);
+            payload = JSON.parse(jsonStr);
+        }
+        catch {
+            return (0, shared_1.err)('INVALID_BACKUP');
+        }
+        // Validate payload structure
+        if (!payload.did || !payload.ed25519Pkcs8 || !payload.x25519Pkcs8) {
+            return (0, shared_1.err)('INVALID_BACKUP');
+        }
+        // Decode base64 keys
+        let ed25519Pkcs8;
+        let x25519Pkcs8;
+        let mlKemSecretKey;
+        let mlKemPublicKey;
+        let mlDsaSecretKey;
+        let mlDsaPublicKey;
+        try {
+            ed25519Pkcs8 = (0, crypto_utils_js_1.fromBase64)(payload.ed25519Pkcs8);
+            x25519Pkcs8 = (0, crypto_utils_js_1.fromBase64)(payload.x25519Pkcs8);
+            if (payload.mlKemSecretKey)
+                mlKemSecretKey = (0, crypto_utils_js_1.fromBase64)(payload.mlKemSecretKey);
+            if (payload.mlKemPublicKey)
+                mlKemPublicKey = (0, crypto_utils_js_1.fromBase64)(payload.mlKemPublicKey);
+            if (payload.mlDsaSecretKey)
+                mlDsaSecretKey = (0, crypto_utils_js_1.fromBase64)(payload.mlDsaSecretKey);
+            if (payload.mlDsaPublicKey)
+                mlDsaPublicKey = (0, crypto_utils_js_1.fromBase64)(payload.mlDsaPublicKey);
+        }
+        catch {
+            return (0, shared_1.err)('INVALID_BACKUP');
+        }
+        // Import identity from decoded keys
+        const identity = await (0, identity_js_1.importIdentity)(ed25519Pkcs8, x25519Pkcs8, mlKemSecretKey, mlKemPublicKey, mlDsaSecretKey, mlDsaPublicKey);
+        if (!identity.ok)
+            return (0, shared_1.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 = (0, crypto_utils_js_1.fromBase64)(rk.x25519Pkcs8);
+                const x25519PrivateKey = await crypto.subtle.importKey('pkcs8', toArrayBuffer(x25519Pk), { name: 'X25519' }, true, ['deriveBits']);
+                const mlKemSecretKeyRk = rk.mlKemSecretKey ? (0, crypto_utils_js_1.fromBase64)(rk.mlKemSecretKey) : undefined;
+                return {
+                    rotatedAt: rk.rotatedAt,
+                    x25519PrivateKey,
+                    ...(mlKemSecretKeyRk ? { mlKemSecretKey: mlKemSecretKeyRk } : {}),
+                };
+            }));
+            // Return identity with restored rotated keys
+            return (0, shared_1.ok)({
+                ...restored,
+                rotatedKeys: rotatedKeys,
+            });
+        }
+        return identity;
+    }
+    catch (importErr) {
+        console.warn('[xBind] Import backup failed:', importErr);
+        return (0, shared_1.err)('DECRYPTION_FAILED');
+    }
+}