@private.me/xbind 1.2.0

package/dist-standalone/cjs/backup-config.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * XorIDA Backup Configuration for Key Splitting
+ *
+ * Provides default backup configuration (k=2, n=3) and utilities for
+ * splitting cryptographic keys across multiple shares using information-
+ * theoretic threshold secret sharing.
+ *
+ * @module backup-config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BACKUP_CONFIG = void 0;
+exports.validateBackupConfig = validateBackupConfig;
+exports.splitKeyWithBackup = splitKeyWithBackup;
+exports.reconstructKeyFromBackup = reconstructKeyFromBackup;
+const shared_1 = require("../_deps/shared/index.js");
+const crypto_1 = require("../_deps/crypto/index.js");
+/* ── Constants ── */
+/**
+ * Default backup configuration: 2-of-3 threshold sharing.
+ *
+ * - 3 shares generated
+ * - Any 2 shares can reconstruct the key
+ * - Lose 1 share and still recover (fault tolerance)
+ * - Information-theoretic security (each share reveals zero information)
+ */
+exports.DEFAULT_BACKUP_CONFIG = {
+    threshold: 2,
+    totalShares: 3,
+};
+/* ── Validation ── */
+/**
+ * Validate backup configuration parameters.
+ *
+ * Rules:
+ * - threshold must be >= 2 (single share = no threshold)
+ * - totalShares must be >= threshold
+ * - totalShares must be <= 255 (XorIDA limit)
+ *
+ * @param config - Backup configuration to validate.
+ * @returns Ok if valid, error otherwise.
+ */
+function validateBackupConfig(config) {
+    if (config.threshold < 2) {
+        return (0, shared_1.err)('INVALID_CONFIG');
+    }
+    if (config.totalShares < config.threshold) {
+        return (0, shared_1.err)('INVALID_CONFIG');
+    }
+    if (config.totalShares > 255) {
+        return (0, shared_1.err)('INVALID_CONFIG');
+    }
+    return (0, shared_1.ok)(undefined);
+}
+/* ── Key Splitting ── */
+/**
+ * Split a cryptographic key into backup shares using XorIDA.
+ *
+ * The key is padded, split via information-theoretic threshold sharing,
+ * and returned as BackupShare objects with HMAC integrity protection.
+ *
+ * Any `threshold` shares can reconstruct the original key. Each share
+ * reveals zero information about the key (information-theoretic security).
+ *
+ * @param key - The key to split (32 or 64 bytes typical).
+ * @param config - Backup configuration (defaults to 2-of-3).
+ * @returns Array of backup shares or error.
+ *
+ * @example
+ * ```typescript
+ * import { splitKeyWithBackup, DEFAULT_BACKUP_CONFIG } from '@private.me/xbind';
+ *
+ * const key = crypto.getRandomValues(new Uint8Array(32));
+ *
+ * // Use defaults (2-of-3)
+ * const shares = await splitKeyWithBackup(key);
+ *
+ * // Custom config (3-of-5)
+ * const shares2 = await splitKeyWithBackup(key, {
+ *   threshold: 3,
+ *   totalShares: 5
+ * });
+ *
+ * if (shares.ok) {
+ *   // Store shares in separate locations
+ *   shares.value.forEach((share, i) => {
+ *     storeShare(`backup-${i}.json`, JSON.stringify(share));
+ *   });
+ * }
+ * ```
+ */
+async function splitKeyWithBackup(key, config = exports.DEFAULT_BACKUP_CONFIG) {
+    const validation = validateBackupConfig(config);
+    if (!validation.ok)
+        return validation;
+    if (key.length === 0) {
+        return (0, shared_1.err)('INVALID_KEY_LENGTH');
+    }
+    const n = config.totalShares;
+    const k = config.threshold;
+    const p = (0, crypto_1.nextOddPrime)(n);
+    const blockSize = p - 1;
+    // Pad to block size
+    const padded = (0, crypto_1.pkcs7Pad)(key, blockSize);
+    // Generate HMAC for integrity verification
+    const { key: hmacKey, signature: hmacSig } = await (0, crypto_1.generateHMAC)(padded);
+    const hmacKeyB64 = (0, crypto_1.toBase64)(hmacKey);
+    const hmacSigB64 = (0, crypto_1.toBase64)(hmacSig);
+    // Split via XorIDA
+    let shareArrays;
+    try {
+        shareArrays = (0, crypto_1.splitXorIDA)(padded, n, k);
+    }
+    catch {
+        return (0, shared_1.err)('SPLIT_FAILED');
+    }
+    // Package as BackupShare objects
+    const shares = shareArrays.map((data, index) => ({
+        index,
+        data: (0, crypto_1.toBase64)(data),
+        total: n,
+        threshold: k,
+        hmacKey: hmacKeyB64,
+        hmacSig: hmacSigB64,
+    }));
+    return (0, shared_1.ok)(shares);
+}
+/* ── Key Reconstruction ── */
+/**
+ * Reconstruct a cryptographic key from backup shares.
+ *
+ * Requires at least `threshold` shares. Verifies HMAC before returning
+ * the reconstructed key to prevent tampering.
+ *
+ * @param shares - Backup shares (must be >= threshold).
+ * @returns Reconstructed key or error.
+ *
+ * @example
+ * ```typescript
+ * import { reconstructKeyFromBackup } from '@private.me/xbind';
+ *
+ * // Load shares from storage
+ * const share0 = JSON.parse(loadShare('backup-0.json'));
+ * const share1 = JSON.parse(loadShare('backup-1.json'));
+ *
+ * // Reconstruct from any 2 shares (threshold=2)
+ * const key = await reconstructKeyFromBackup([share0, share1]);
+ *
+ * if (key.ok) {
+ *   // Use reconstructed key
+ *   const agent = await Agent.fromSeed(key.value, opts);
+ * } else {
+ *   console.error('Reconstruction failed:', key.error);
+ * }
+ * ```
+ */
+async function reconstructKeyFromBackup(shares) {
+    if (shares.length === 0) {
+        return (0, shared_1.err)('INSUFFICIENT_SHARES');
+    }
+    const threshold = shares[0].threshold;
+    const total = shares[0].total;
+    if (shares.length < threshold) {
+        return (0, shared_1.err)('INSUFFICIENT_SHARES');
+    }
+    // Use first `threshold` shares
+    const usedShares = shares.slice(0, threshold);
+    // Decode share data
+    let shareData;
+    try {
+        shareData = usedShares.map((s) => (0, crypto_1.fromBase64)(s.data));
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_SHARE_DATA');
+    }
+    const indices = usedShares.map((s) => s.index);
+    // Reconstruct padded key
+    let padded;
+    try {
+        padded = (0, crypto_1.reconstructXorIDA)(shareData, indices, total, threshold);
+    }
+    catch {
+        return (0, shared_1.err)('RECONSTRUCT_FAILED');
+    }
+    // Verify HMAC
+    let hmacKey;
+    let hmacSig;
+    try {
+        hmacKey = (0, crypto_1.fromBase64)(usedShares[0].hmacKey);
+        hmacSig = (0, crypto_1.fromBase64)(usedShares[0].hmacSig);
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_SHARE_DATA');
+    }
+    const hmacValid = await (0, crypto_1.verifyHMAC)(hmacKey, padded, hmacSig);
+    if (!hmacValid) {
+        return (0, shared_1.err)('HMAC_VERIFICATION_FAILED');
+    }
+    // Unpad to recover original key
+    const p = (0, crypto_1.nextOddPrime)(total);
+    const blockSize = p - 1;
+    const unpadResult = (0, crypto_1.pkcs7Unpad)(padded, blockSize);
+    if (!unpadResult.ok) {
+        return (0, shared_1.err)('RECONSTRUCT_FAILED');
+    }
+    return (0, shared_1.ok)(unpadResult.value);
+}

package/dist-standalone/cjs/checkpoint.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCheckpoint = createCheckpoint;
+exports.verifyCheckpoint = verifyCheckpoint;
+exports.isCacheStale = isCacheStale;
+exports.encodeCheckpoint = encodeCheckpoint;
+exports.decodeCheckpoint = decodeCheckpoint;
+const shared_1 = require("../_deps/shared/index.js");
+const identity_js_1 = require("./identity.js");
+/* ── Checkpoint Creation (Gateway-side) ── */
+/**
+ * Create a signed checkpoint for a DID (gateway-side operation).
+ *
+ * Gateway signs the DID state snapshot using its ML-DSA-65 private key.
+ * Clients verify this signature using the gateway's published public key.
+ *
+ * @param subject - DID being checkpointed
+ * @param publicKey - Current public key bytes
+ * @param revoked - Current revocation status
+ * @param rotationSequence - Current rotation sequence counter
+ * @param gatewayPrivateKey - Gateway's ML-DSA-65 secret key (32-byte seed or 4032-byte expanded)
+ * @returns Signed checkpoint or error
+ *
+ * @example
+ * ```typescript
+ * const checkpoint = await createCheckpoint(
+ *   'did:key:z6Mk...',
+ *   publicKeyBytes,
+ *   false,
+ *   5,
+ *   gatewaySecretKey
+ * );
+ * if (checkpoint.ok) {
+ *   // Send checkpoint to client for staleness detection
+ *   sendToClient(checkpoint.value);
+ * }
+ * ```
+ */
+async function createCheckpoint(subject, publicKey, revoked, rotationSequence, gatewayPrivateKey) {
+    const timestamp = Date.now();
+    // Construct canonical message to sign
+    const publicKeyB64 = Buffer.from(publicKey).toString('base64');
+    const message = `DIDStateCheckpoint||1.0||${subject}||${publicKeyB64}||${revoked}||${rotationSequence}||${timestamp}`;
+    const messageBytes = new TextEncoder().encode(message);
+    // Sign using gateway's ML-DSA-65 key
+    const sigResult = await (0, identity_js_1.signMlDsa65)(gatewayPrivateKey, messageBytes);
+    if (!sigResult.ok) {
+        return (0, shared_1.err)('SIGN_FAILED');
+    }
+    return (0, shared_1.ok)({
+        type: 'DIDStateCheckpoint',
+        version: '1.0',
+        subject,
+        current_public_key: publicKeyB64,
+        revoked,
+        rotation_sequence: rotationSequence,
+        timestamp,
+        checkpoint_signature_algorithm: 'ML-DSA-65',
+        checkpoint_signature: Buffer.from(sigResult.value).toString('base64')
+    });
+}
+/* ── Checkpoint Verification (Client-side) ── */
+/**
+ * Verify a checkpoint signature (client-side operation).
+ *
+ * Clients MUST verify checkpoint signatures before trusting the state.
+ * Uses gateway's published ML-DSA-65 public key to verify signature.
+ *
+ * @param checkpoint - Checkpoint to verify
+ * @param gatewayPublicKey - Gateway's ML-DSA-65 public key (1952 bytes)
+ * @returns true if signature valid, false if invalid, error if verification fails
+ *
+ * @example
+ * ```typescript
+ * const valid = await verifyCheckpoint(checkpoint, gatewayPubKey);
+ * if (valid.ok && valid.value) {
+ *   // Checkpoint is authentic - safe to use for staleness detection
+ *   if (isCacheStale(localCache, checkpoint)) {
+ *     // Refresh local cache
+ *   }
+ * }
+ * ```
+ */
+async function verifyCheckpoint(checkpoint, gatewayPublicKey) {
+    // Validate checkpoint format
+    if (checkpoint.type !== 'DIDStateCheckpoint') {
+        return (0, shared_1.err)('INVALID_FORMAT');
+    }
+    if (checkpoint.version !== '1.0') {
+        return (0, shared_1.err)('INVALID_FORMAT');
+    }
+    if (!checkpoint.subject || !checkpoint.current_public_key) {
+        return (0, shared_1.err)('INVALID_FORMAT');
+    }
+    if (typeof checkpoint.rotation_sequence !== 'number' || checkpoint.rotation_sequence < 0) {
+        return (0, shared_1.err)('INVALID_FORMAT');
+    }
+    if (typeof checkpoint.timestamp !== 'number' || checkpoint.timestamp <= 0) {
+        return (0, shared_1.err)('INVALID_TIMESTAMP');
+    }
+    if (checkpoint.checkpoint_signature_algorithm !== 'ML-DSA-65') {
+        return (0, shared_1.err)('INVALID_FORMAT');
+    }
+    // Reconstruct canonical message
+    const message = `DIDStateCheckpoint||1.0||${checkpoint.subject}||${checkpoint.current_public_key}||${checkpoint.revoked}||${checkpoint.rotation_sequence}||${checkpoint.timestamp}`;
+    const messageBytes = new TextEncoder().encode(message);
+    // Decode signature
+    let signature;
+    try {
+        signature = Buffer.from(checkpoint.checkpoint_signature, 'base64');
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_SIGNATURE');
+    }
+    // Verify signature using gateway public key
+    const verifyResult = await (0, identity_js_1.verifyMlDsa65)(gatewayPublicKey, signature, messageBytes);
+    if (!verifyResult.ok) {
+        return (0, shared_1.err)('VERIFY_FAILED');
+    }
+    return (0, shared_1.ok)(verifyResult.value);
+}
+/* ── Staleness Detection ── */
+/**
+ * Detect if local cache is stale compared to gateway checkpoint.
+ *
+ * Cache is stale if:
+ * 1. Checkpoint rotation_sequence > local rotationSequence (key rotated)
+ * 2. Checkpoint revoked !== local revoked (revocation status changed)
+ * 3. Checkpoint public key !== local publicKey (state drift)
+ *
+ * @param localCache - Local cache entry for DID
+ * @param checkpoint - Verified checkpoint from gateway
+ * @returns true if cache needs refresh, false if cache is current
+ *
+ * @example
+ * ```typescript
+ * if (isCacheStale(localCache, checkpoint)) {
+ *   // Local cache is outdated - fetch fresh state from gateway
+ *   const freshState = await registry.getEntry(did);
+ * }
+ * ```
+ */
+function isCacheStale(localCache, checkpoint) {
+    // Sequence number mismatch indicates key rotation
+    if (checkpoint.rotation_sequence > localCache.rotationSequence) {
+        return true;
+    }
+    // Revocation status changed
+    if (checkpoint.revoked !== localCache.revoked) {
+        return true;
+    }
+    // Public key mismatch indicates state drift
+    const checkpointPubKey = Buffer.from(checkpoint.current_public_key, 'base64');
+    if (!Buffer.from(localCache.publicKey).equals(checkpointPubKey)) {
+        return true;
+    }
+    return false;
+}
+/* ── Encoding/Decoding ── */
+/**
+ * Encode checkpoint to JSON string for wire transport.
+ *
+ * @param checkpoint - Checkpoint to encode
+ * @returns JSON string
+ */
+function encodeCheckpoint(checkpoint) {
+    return JSON.stringify(checkpoint);
+}
+/**
+ * Decode checkpoint from JSON string.
+ *
+ * @param encoded - JSON string
+ * @returns Parsed checkpoint or error
+ */
+function decodeCheckpoint(encoded) {
+    try {
+        const parsed = JSON.parse(encoded);
+        // Basic validation
+        if (parsed.type !== 'DIDStateCheckpoint') {
+            return (0, shared_1.err)('INVALID_FORMAT');
+        }
+        if (parsed.version !== '1.0') {
+            return (0, shared_1.err)('INVALID_FORMAT');
+        }
+        if (!parsed.subject || !parsed.current_public_key || !parsed.checkpoint_signature) {
+            return (0, shared_1.err)('INVALID_FORMAT');
+        }
+        return (0, shared_1.ok)(parsed);
+    }
+    catch {
+        return (0, shared_1.err)('INVALID_FORMAT');
+    }
+}