@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/cjs/backup.js

@@ -1,330 +1 @@
-"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');
-    }
-}
+"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;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,_),y=new Uint8Array(c);if(y.length<16)return(0,shared_1.err)("ENCRYPTION_FAILED");const n=y.length-16,u=y.slice(0,n),l=y.slice(n);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,y,n,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{return(0,shared_1.err)("INVALID_PASSWORD")}try{const e=(new TextDecoder).decode(c);y=JSON.parse(e)}catch{return(0,shared_1.err)("INVALID_BACKUP")}if(!y.did||!y.ed25519Pkcs8||!y.x25519Pkcs8)return(0,shared_1.err)("INVALID_BACKUP");try{n=(0,crypto_utils_js_1.fromBase64)(y.ed25519Pkcs8),u=(0,crypto_utils_js_1.fromBase64)(y.x25519Pkcs8),y.mlKemSecretKey&&(l=(0,crypto_utils_js_1.fromBase64)(y.mlKemSecretKey)),y.mlKemPublicKey&&(d=(0,crypto_utils_js_1.fromBase64)(y.mlKemPublicKey)),y.mlDsaSecretKey&&(p=(0,crypto_utils_js_1.fromBase64)(y.mlDsaSecretKey)),y.mlDsaPublicKey&&(K=(0,crypto_utils_js_1.fromBase64)(y.mlDsaPublicKey))}catch{return(0,shared_1.err)("INVALID_BACKUP")}const m=await(0,identity_js_1.importIdentity)(n,u,l,d,p,K);if(!m.ok)return(0,shared_1.err)("IMPORT_FAILED");if(y.rotatedKeys&&y.rotatedKeys.length>0){const e=m.value,t=await Promise.all(y.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{return(0,shared_1.err)("DECRYPTION_FAILED")}}