@private.me/xcontinuity 2.1.0

package/dist/cjs/reverse-xorida.js

@@ -0,0 +1,506 @@
+"use strict";
+/**
+ * @private.me/xcontinuity — Reverse-XorIDA Core Crypto Layer
+ *
+ * The novel primitive: exploits XorIDA's linearity over GF(2) to perform
+ * incremental state updates at O(delta) cost instead of re-splitting entire state.
+ *
+ * Key insight: split(A XOR B) = split(A) XOR split(B)
+ *
+ * Therefore: newShares = oldShares XOR split(oldPadded XOR newPadded)
+ *
+ * HMAC must be recomputed fresh for the new state (not derived from delta).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.padForSplit = padForSplit;
+exports.splitState = splitState;
+exports.reconstructState = reconstructState;
+exports.computeDelta = computeDelta;
+exports.applyDeltaShares = applyDeltaShares;
+exports.incrementalUpdate = incrementalUpdate;
+exports.undoDelta = undoDelta;
+exports.branchState = branchState;
+exports.squashDeltas = squashDeltas;
+exports.blindUpdateShare = blindUpdateShare;
+exports.refreshShares = refreshShares;
+exports.blindEqual = blindEqual;
+exports.networkCodeShares = networkCodeShares;
+exports.networkDecodeShare = networkDecodeShare;
+const shared_1 = require("@private.me/shared");
+const crypto_1 = require("@private.me/crypto");
+const types_js_1 = require("./types.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Pad data for XorIDA splitting.
+ * Block size = nextOddPrime(n) - 1.
+ */
+function padForSplit(data, n) {
+    const p = (0, crypto_1.nextOddPrime)(n);
+    const blockSize = p - 1;
+    return (0, crypto_1.pkcs7Pad)(data, blockSize);
+}
+/**
+ * Split a state snapshot into XorIDA threshold shares.
+ *
+ * Pipeline: pad -> HMAC -> split -> package as StateShare[]
+ *
+ * @param snapshot - Serialized state with checksum
+ * @param config - Split configuration (n, k)
+ * @returns SplitState containing all shares
+ */
+async function splitState(snapshot, config = types_js_1.DEFAULT_SPLIT_CONFIG) {
+    try {
+        const { n, k } = config;
+        if (n < 2 || k < 2 || k > n) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('SPLIT_FAILED', `Invalid config: n=${n}, k=${k}`));
+        }
+        const padded = padForSplit(snapshot.serializedBytes, n);
+        const { key: hmacKey, signature: hmacSignature } = await (0, crypto_1.generateHMAC)(padded);
+        const rawShares = (0, crypto_1.splitXorIDA)(padded, n, k);
+        const shares = rawShares.map((data, index) => ({
+            stateId: snapshot.stateId,
+            index,
+            n,
+            k,
+            data,
+            hmacKey,
+            hmacSignature,
+        }));
+        return (0, shared_1.ok)({
+            stateId: snapshot.stateId,
+            metadata: snapshot.metadata,
+            shares,
+            n,
+            k,
+            paddedLength: padded.length,
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : 'Split failed';
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('SPLIT_FAILED', msg));
+    }
+}
+/**
+ * Reconstruct a state snapshot from threshold shares.
+ *
+ * Pipeline: validate -> reconstruct -> verify HMAC -> unpad -> return snapshot bytes
+ *
+ * @param shares - Array of k or more StateShares (uses first k)
+ * @returns Reconstructed StateSnapshot serialized bytes and checksum
+ */
+async function reconstructState(shares) {
+    try {
+        if (shares.length === 0) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('INSUFFICIENT_SHARES', 'No shares provided'));
+        }
+        const first = shares[0];
+        const k = first.k;
+        const n = first.n;
+        if (shares.length < k) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('INSUFFICIENT_SHARES', `Need ${k} shares, got ${shares.length}`));
+        }
+        // Verify all shares have same stateId
+        const stateId = first.stateId;
+        for (const share of shares) {
+            if (share.stateId !== stateId) {
+                return (0, shared_1.err)((0, errors_js_1.continuityError)('INVALID_SHARES', 'Share stateId mismatch'));
+            }
+        }
+        // Take first k shares
+        const subset = shares.slice(0, k);
+        const shareData = subset.map(s => s.data);
+        const indices = subset.map(s => s.index);
+        const reconstructed = (0, crypto_1.reconstructXorIDA)(shareData, indices, n, k);
+        // Verify HMAC using the key from the first share
+        const hmacValid = await (0, crypto_1.verifyHMAC)(first.hmacKey, reconstructed, first.hmacSignature);
+        if (!hmacValid) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('HMAC_FAILURE', 'HMAC verification failed after reconstruction'));
+        }
+        // Unpad
+        const p = (0, crypto_1.nextOddPrime)(n);
+        const blockSize = p - 1;
+        const unpadResult = (0, crypto_1.pkcs7Unpad)(reconstructed, blockSize);
+        if (!unpadResult.ok) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('PADDING_ERROR', 'Failed to remove padding after reconstruction'));
+        }
+        return (0, shared_1.ok)({ serializedBytes: unpadResult.value, stateId });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : 'Reconstruction failed';
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('RECONSTRUCT_FAILED', msg));
+    }
+}
+/**
+ * Compute the byte-level delta between two padded state arrays.
+ * Both arrays must be the same length.
+ *
+ * delta[i] = oldPadded[i] XOR newPadded[i]
+ */
+function computeDelta(oldPadded, newPadded, fromStateId, toStateId, fromChecksum, toChecksum) {
+    if (oldPadded.length !== newPadded.length) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', `Padded sizes differ: ${oldPadded.length} vs ${newPadded.length}`));
+    }
+    const deltaBytes = new Uint8Array(oldPadded.length);
+    for (let i = 0; i < oldPadded.length; i++) {
+        deltaBytes[i] = oldPadded[i] ^ newPadded[i];
+    }
+    return (0, shared_1.ok)({ fromStateId, toStateId, deltaBytes, fromChecksum, toChecksum });
+}
+/**
+ * Apply delta shares to old split state via XOR.
+ *
+ * newShares[i].data = oldShares[i].data XOR deltaShares[i].data
+ *
+ * @param oldShares - Original shares
+ * @param deltaShares - Delta shares (from splitting the delta)
+ * @param newStateId - State ID for the new split state
+ * @param newMetadata - Metadata for the new state
+ * @param newHmacKey - Fresh HMAC key for the new state
+ * @param newHmacSignature - Fresh HMAC signature for the new padded state
+ */
+function applyDeltaShares(oldShares, deltaShares, newStateId, newHmacKey, newHmacSignature) {
+    if (oldShares.length !== deltaShares.length) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('INVALID_SHARES', `Share count mismatch: ${oldShares.length} vs ${deltaShares.length}`));
+    }
+    const newShares = [];
+    for (let i = 0; i < oldShares.length; i++) {
+        const oldShare = oldShares[i];
+        const deltaData = deltaShares[i];
+        if (oldShare.data.length !== deltaData.length) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', `Share ${i} size mismatch: ${oldShare.data.length} vs ${deltaData.length}`));
+        }
+        const newData = new Uint8Array(oldShare.data.length);
+        for (let j = 0; j < oldShare.data.length; j++) {
+            newData[j] = oldShare.data[j] ^ deltaData[j];
+        }
+        newShares.push({
+            stateId: newStateId,
+            index: oldShare.index,
+            n: oldShare.n,
+            k: oldShare.k,
+            data: newData,
+            hmacKey: newHmacKey,
+            hmacSignature: newHmacSignature,
+        });
+    }
+    return (0, shared_1.ok)(newShares);
+}
+/**
+ * Perform an incremental state update using Reverse-XorIDA.
+ *
+ * Instead of re-splitting the entire new state:
+ * 1. Pad both old and new to the same block-aligned size
+ * 2. Compute delta = oldPadded XOR newPadded
+ * 3. Split the delta
+ * 4. XOR each old share with the corresponding delta share
+ * 5. Recompute HMAC fresh for the new padded state
+ *
+ * Falls back to fresh split when sizes differ significantly
+ * (incremental update only works when padded lengths match).
+ *
+ * @param oldSplitState - Previous split state
+ * @param oldSnapshot - Previous state snapshot
+ * @param newSnapshot - New state snapshot
+ * @returns Updated SplitState with new shares
+ */
+async function incrementalUpdate(oldSplitState, oldSnapshot, newSnapshot) {
+    try {
+        const { n, k } = oldSplitState;
+        // Pad both to the same block boundary
+        const oldPadded = padForSplit(oldSnapshot.serializedBytes, n);
+        const newPadded = padForSplit(newSnapshot.serializedBytes, n);
+        // If padded lengths differ, fall back to fresh split
+        if (oldPadded.length !== newPadded.length) {
+            return splitState(newSnapshot, { n, k });
+        }
+        // Compute delta
+        const deltaBytes = new Uint8Array(oldPadded.length);
+        for (let i = 0; i < oldPadded.length; i++) {
+            deltaBytes[i] = oldPadded[i] ^ newPadded[i];
+        }
+        // Split the delta
+        const deltaShares = (0, crypto_1.splitXorIDA)(deltaBytes, n, k);
+        // Fresh HMAC for the new padded state
+        const { key: newHmacKey, signature: newHmacSignature } = await (0, crypto_1.generateHMAC)(newPadded);
+        // XOR old shares with delta shares
+        const applyResult = applyDeltaShares(oldSplitState.shares, deltaShares, newSnapshot.stateId, newHmacKey, newHmacSignature);
+        if (!applyResult.ok)
+            return applyResult;
+        return (0, shared_1.ok)({
+            stateId: newSnapshot.stateId,
+            metadata: newSnapshot.metadata,
+            shares: applyResult.value,
+            n,
+            k,
+            paddedLength: newPadded.length,
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : 'Incremental update failed';
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('SPLIT_FAILED', msg));
+    }
+}
+/* ══════════════════════════════════════════════════════════════════
+ * Algebraic Extensions (v2.0.0)
+ *
+ * All extensions exploit XorIDA's linearity over GF(2):
+ *   split(A ⊕ B) = split(A) ⊕ split(B)
+ *
+ * This property enables O(δ) operations on encrypted shares
+ * without ever reconstructing the plaintext.
+ * ══════════════════════════════════════════════════════════════════ */
+/**
+ * Extension 1: Undo / Time-Travel
+ *
+ * Reverse a delta by re-applying it (XOR is its own inverse in GF(2)).
+ * Given shares at state B and the delta A→B, produces shares at state A.
+ *
+ * Math: shares_A = shares_B ⊕ deltaShares(A→B)
+ *       because: (A ⊕ Δ) ⊕ Δ = A  (XOR self-inverse)
+ */
+function undoDelta(currentShares, deltaShares, previousStateId, hmacKey, hmacSignature) {
+    // Undo is identical to apply — XOR is self-inverse
+    return applyDeltaShares(currentShares, deltaShares, previousStateId, hmacKey, hmacSignature);
+}
+/**
+ * Extension 2: Branch
+ *
+ * Fork a split state into an independent branch by copying shares.
+ * The branch can diverge independently from the original.
+ *
+ * @param source - The split state to branch from
+ * @param branchStateId - New stateId for the branch
+ * @returns Independent copy of the split state
+ */
+function branchState(source, branchStateId) {
+    const branchedShares = source.shares.map(share => ({
+        stateId: branchStateId,
+        index: share.index,
+        n: share.n,
+        k: share.k,
+        data: new Uint8Array(share.data),
+        hmacKey: new Uint8Array(share.hmacKey),
+        hmacSignature: new Uint8Array(share.hmacSignature),
+    }));
+    return {
+        stateId: branchStateId,
+        metadata: source.metadata,
+        shares: branchedShares,
+        n: source.n,
+        k: source.k,
+        paddedLength: source.paddedLength,
+    };
+}
+/**
+ * Extension 3: Delta Squashing
+ *
+ * Combine multiple sequential deltas into a single delta.
+ * Exploits GF(2) associativity: Δ_total = Δ₁ ⊕ Δ₂ ⊕ ... ⊕ Δₙ
+ *
+ * @param deltas - Ordered array of deltas to squash (must form a chain)
+ * @returns Single squashed delta from first.fromStateId to last.toStateId
+ */
+function squashDeltas(deltas) {
+    if (deltas.length === 0) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', 'No deltas to squash'));
+    }
+    if (deltas.length === 1) {
+        return (0, shared_1.ok)(deltas[0]);
+    }
+    const first = deltas[0];
+    const last = deltas[deltas.length - 1];
+    // Verify chain continuity
+    for (let i = 1; i < deltas.length; i++) {
+        if (deltas[i].fromStateId !== deltas[i - 1].toStateId) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', `Delta chain broken at index ${i}: expected from=${deltas[i - 1].toStateId}, got from=${deltas[i].fromStateId}`));
+        }
+    }
+    // Verify all deltas have the same length
+    const len = first.deltaBytes.length;
+    for (const d of deltas) {
+        if (d.deltaBytes.length !== len) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', `Delta size mismatch: expected ${len}, got ${d.deltaBytes.length}`));
+        }
+    }
+    // XOR all deltas together
+    const squashed = new Uint8Array(len);
+    for (const d of deltas) {
+        for (let i = 0; i < len; i++) {
+            squashed[i] ^= d.deltaBytes[i];
+        }
+    }
+    return (0, shared_1.ok)({
+        fromStateId: first.fromStateId,
+        toStateId: last.toStateId,
+        deltaBytes: squashed,
+        fromChecksum: first.fromChecksum,
+        toChecksum: last.toChecksum,
+    });
+}
+/**
+ * Extension 4: Blind Update
+ *
+ * Apply a delta to shares without seeing the plaintext state.
+ * The share holder never reconstructs the full state.
+ *
+ * Math: newShare_i = oldShare_i ⊕ deltaShare_i
+ *
+ * @param share - A single share to update
+ * @param deltaShareData - The corresponding delta share data
+ * @param newStateId - New state identifier
+ * @param newHmacKey - Fresh HMAC key
+ * @param newHmacSignature - Fresh HMAC signature
+ */
+function blindUpdateShare(share, deltaShareData, newStateId, newHmacKey, newHmacSignature) {
+    if (share.data.length !== deltaShareData.length) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', `Share data length ${share.data.length} != delta length ${deltaShareData.length}`));
+    }
+    const newData = new Uint8Array(share.data.length);
+    for (let i = 0; i < share.data.length; i++) {
+        newData[i] = share.data[i] ^ deltaShareData[i];
+    }
+    return (0, shared_1.ok)({
+        stateId: newStateId,
+        index: share.index,
+        n: share.n,
+        k: share.k,
+        data: newData,
+        hmacKey: newHmacKey,
+        hmacSignature: newHmacSignature,
+    });
+}
+/**
+ * Extension 5: Proactive Share Refresh
+ *
+ * Re-randomize shares while preserving reconstruction correctness.
+ * Generates a random mask, splits it, XORs with existing shares.
+ * The mask XORs to zero upon reconstruction, so the plaintext is unchanged.
+ *
+ * @param splitState - Current split state
+ * @returns Refreshed split state with re-randomized shares (same plaintext)
+ */
+async function refreshShares(state) {
+    try {
+        const { n, k, paddedLength } = state;
+        // Generate random mask of the same padded length
+        const mask = new Uint8Array(paddedLength);
+        crypto.getRandomValues(mask);
+        // Split the mask
+        const maskShares = (0, crypto_1.splitXorIDA)(mask, n, k);
+        // XOR each share with its mask share
+        const refreshedShares = [];
+        for (let i = 0; i < state.shares.length; i++) {
+            const share = state.shares[i];
+            const maskData = maskShares[i];
+            const newData = new Uint8Array(share.data.length);
+            for (let j = 0; j < share.data.length; j++) {
+                newData[j] = share.data[j] ^ maskData[j];
+            }
+            refreshedShares.push({
+                ...share,
+                data: newData,
+            });
+        }
+        // Recompute HMAC for the refreshed state
+        // Note: the plaintext doesn't change, so we reconstruct and verify
+        const refreshedData = refreshedShares.map(s => s.data);
+        const indices = refreshedShares.map(s => s.index);
+        const reconstructed = (0, crypto_1.reconstructXorIDA)(refreshedData.slice(0, k), indices.slice(0, k), n, k);
+        const { key: newHmacKey, signature: newHmacSignature } = await (0, crypto_1.generateHMAC)(reconstructed);
+        const finalShares = refreshedShares.map(s => ({
+            ...s,
+            hmacKey: newHmacKey,
+            hmacSignature: newHmacSignature,
+        }));
+        return (0, shared_1.ok)({
+            ...state,
+            shares: finalShares,
+        });
+    }
+    catch (e) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('SPLIT_FAILED', `Share refresh failed: ${e instanceof Error ? e.message : String(e)}`));
+    }
+}
+/**
+ * Extension 6: Blind Equality Check
+ *
+ * Compare two split states for equality without reconstructing plaintext.
+ * Computes delta between corresponding shares — if all delta bytes are zero,
+ * the states are equal.
+ *
+ * @param a - First split state
+ * @param b - Second split state
+ * @returns true if both states encode the same plaintext
+ */
+function blindEqual(a, b) {
+    if (a.n !== b.n || a.k !== b.k) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('INVALID_SHARES', 'Split configs differ'));
+    }
+    if (a.shares.length !== b.shares.length) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('INVALID_SHARES', 'Share count differs'));
+    }
+    // Check if all corresponding share data XOR to zero
+    for (let i = 0; i < a.shares.length; i++) {
+        const aShare = a.shares[i];
+        const bShare = b.shares[i];
+        if (aShare.data.length !== bShare.data.length) {
+            return (0, shared_1.ok)(false);
+        }
+        for (let j = 0; j < aShare.data.length; j++) {
+            if ((aShare.data[j] ^ bShare.data[j]) !== 0) {
+                return (0, shared_1.ok)(false);
+            }
+        }
+    }
+    return (0, shared_1.ok)(true);
+}
+/**
+ * Extension 7: Network-Coded Sync
+ *
+ * Combine multiple shares during transit using XOR for bandwidth efficiency.
+ * The receiver can extract individual shares if they hold the complementary shares.
+ *
+ * coded = share_i ⊕ share_j
+ * share_i = coded ⊕ share_j  (if receiver already holds share_j)
+ *
+ * @param shares - Array of shares to combine
+ * @returns Single coded block (XOR of all input shares)
+ */
+function networkCodeShares(shares) {
+    if (shares.length === 0) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('INSUFFICIENT_SHARES', 'No shares to code'));
+    }
+    const len = shares[0].data.length;
+    for (const s of shares) {
+        if (s.data.length !== len) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', 'Share data lengths differ'));
+        }
+    }
+    const coded = new Uint8Array(len);
+    for (const s of shares) {
+        for (let i = 0; i < len; i++) {
+            coded[i] ^= s.data[i];
+        }
+    }
+    return (0, shared_1.ok)(coded);
+}
+/**
+ * Decode a network-coded block using a held share.
+ *
+ * If coded = share_i ⊕ share_j, and you hold share_j:
+ *   share_i = coded ⊕ share_j
+ *
+ * @param codedBlock - The network-coded block
+ * @param heldShare - The share the receiver already holds
+ * @returns The extracted share data
+ */
+function networkDecodeShare(codedBlock, heldShare) {
+    if (codedBlock.length !== heldShare.data.length) {
+        return (0, shared_1.err)((0, errors_js_1.continuityError)('DELTA_SIZE_MISMATCH', 'Coded block and share lengths differ'));
+    }
+    const decoded = new Uint8Array(codedBlock.length);
+    for (let i = 0; i < codedBlock.length; i++) {
+        decoded[i] = codedBlock[i] ^ heldShare.data[i];
+    }
+    return (0, shared_1.ok)(decoded);
+}