@private.me/xcontinuity 2.1.0

package/dist/reverse-xorida.js

@@ -0,0 +1,490 @@
+/**
+ * @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).
+ */
+import { ok, err } from '@private.me/shared';
+import { splitXorIDA, reconstructXorIDA, nextOddPrime, pkcs7Pad, pkcs7Unpad, generateHMAC, verifyHMAC, } from '@private.me/crypto';
+import { DEFAULT_SPLIT_CONFIG } from './types.js';
+import { continuityError } from './errors.js';
+/**
+ * Pad data for XorIDA splitting.
+ * Block size = nextOddPrime(n) - 1.
+ */
+export function padForSplit(data, n) {
+    const p = nextOddPrime(n);
+    const blockSize = p - 1;
+    return 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
+ */
+export async function splitState(snapshot, config = DEFAULT_SPLIT_CONFIG) {
+    try {
+        const { n, k } = config;
+        if (n < 2 || k < 2 || k > n) {
+            return err(continuityError('SPLIT_FAILED', `Invalid config: n=${n}, k=${k}`));
+        }
+        const padded = padForSplit(snapshot.serializedBytes, n);
+        const { key: hmacKey, signature: hmacSignature } = await generateHMAC(padded);
+        const rawShares = splitXorIDA(padded, n, k);
+        const shares = rawShares.map((data, index) => ({
+            stateId: snapshot.stateId,
+            index,
+            n,
+            k,
+            data,
+            hmacKey,
+            hmacSignature,
+        }));
+        return 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 err(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
+ */
+export async function reconstructState(shares) {
+    try {
+        if (shares.length === 0) {
+            return err(continuityError('INSUFFICIENT_SHARES', 'No shares provided'));
+        }
+        const first = shares[0];
+        const k = first.k;
+        const n = first.n;
+        if (shares.length < k) {
+            return err(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 err(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 = reconstructXorIDA(shareData, indices, n, k);
+        // Verify HMAC using the key from the first share
+        const hmacValid = await verifyHMAC(first.hmacKey, reconstructed, first.hmacSignature);
+        if (!hmacValid) {
+            return err(continuityError('HMAC_FAILURE', 'HMAC verification failed after reconstruction'));
+        }
+        // Unpad
+        const p = nextOddPrime(n);
+        const blockSize = p - 1;
+        const unpadResult = pkcs7Unpad(reconstructed, blockSize);
+        if (!unpadResult.ok) {
+            return err(continuityError('PADDING_ERROR', 'Failed to remove padding after reconstruction'));
+        }
+        return ok({ serializedBytes: unpadResult.value, stateId });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : 'Reconstruction failed';
+        return err(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]
+ */
+export function computeDelta(oldPadded, newPadded, fromStateId, toStateId, fromChecksum, toChecksum) {
+    if (oldPadded.length !== newPadded.length) {
+        return err(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 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
+ */
+export function applyDeltaShares(oldShares, deltaShares, newStateId, newHmacKey, newHmacSignature) {
+    if (oldShares.length !== deltaShares.length) {
+        return err(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 err(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 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
+ */
+export 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 = splitXorIDA(deltaBytes, n, k);
+        // Fresh HMAC for the new padded state
+        const { key: newHmacKey, signature: newHmacSignature } = await generateHMAC(newPadded);
+        // XOR old shares with delta shares
+        const applyResult = applyDeltaShares(oldSplitState.shares, deltaShares, newSnapshot.stateId, newHmacKey, newHmacSignature);
+        if (!applyResult.ok)
+            return applyResult;
+        return 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 err(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)
+ */
+export 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
+ */
+export 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
+ */
+export function squashDeltas(deltas) {
+    if (deltas.length === 0) {
+        return err(continuityError('DELTA_SIZE_MISMATCH', 'No deltas to squash'));
+    }
+    if (deltas.length === 1) {
+        return 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 err(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 err(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 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
+ */
+export function blindUpdateShare(share, deltaShareData, newStateId, newHmacKey, newHmacSignature) {
+    if (share.data.length !== deltaShareData.length) {
+        return err(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 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)
+ */
+export 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 = 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 = reconstructXorIDA(refreshedData.slice(0, k), indices.slice(0, k), n, k);
+        const { key: newHmacKey, signature: newHmacSignature } = await generateHMAC(reconstructed);
+        const finalShares = refreshedShares.map(s => ({
+            ...s,
+            hmacKey: newHmacKey,
+            hmacSignature: newHmacSignature,
+        }));
+        return ok({
+            ...state,
+            shares: finalShares,
+        });
+    }
+    catch (e) {
+        return err(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
+ */
+export function blindEqual(a, b) {
+    if (a.n !== b.n || a.k !== b.k) {
+        return err(continuityError('INVALID_SHARES', 'Split configs differ'));
+    }
+    if (a.shares.length !== b.shares.length) {
+        return err(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 ok(false);
+        }
+        for (let j = 0; j < aShare.data.length; j++) {
+            if ((aShare.data[j] ^ bShare.data[j]) !== 0) {
+                return ok(false);
+            }
+        }
+    }
+    return 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)
+ */
+export function networkCodeShares(shares) {
+    if (shares.length === 0) {
+        return err(continuityError('INSUFFICIENT_SHARES', 'No shares to code'));
+    }
+    const len = shares[0].data.length;
+    for (const s of shares) {
+        if (s.data.length !== len) {
+            return err(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 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
+ */
+export function networkDecodeShare(codedBlock, heldShare) {
+    if (codedBlock.length !== heldShare.data.length) {
+        return err(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 ok(decoded);
+}

package/dist/session.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @private.me/xcontinuity — Session Manager
+ *
+ * Stateful controller combining all layers:
+ * - RuntimeMemory for ephemeral in-process state
+ * - SessionMemory for XorIDA-persisted state
+ * - Chronicle for ordered state history
+ *
+ * Status transitions: active -> suspended -> active (resume), active -> closed (terminal).
+ */
+import type { Result } from '@private.me/shared';
+import type { AgentState, StateSnapshot, ContinuitySession, SessionConfig } from './types.js';
+import type { ContinuityError } from './errors.js';
+import { Chronicle } from './chronicle.js';
+import type { TrustStore } from './ratification.js';
+import type { MissionGuard } from './mission.js';
+import type { EnforcementLoop } from './enforcement.js';
+/** Extended session config with optional trust substrate. */
+export interface TrustSessionConfig extends SessionConfig {
+    /** Optional TrustStore for trust-annotated state management. */
+    readonly trustStore?: TrustStore;
+    /** Optional MissionGuard for constraint checking on state writes. */
+    readonly missionGuard?: MissionGuard;
+    /** Optional EnforcementLoop for violation tracking. */
+    readonly enforcementLoop?: EnforcementLoop;
+}
+export declare class SessionManager {
+    private sessionRecord;
+    private state;
+    private readonly memory;
+    private readonly chronicle;
+    private readonly trustStore?;
+    private readonly missionGuard?;
+    private readonly enforcementLoop?;
+    private sequenceCounter;
+    private constructor();
+    /**
+     * Create a new continuity session.
+     *
+     * @param config - Session configuration (agentId, store, optional splitConfig)
+     * @returns SessionManager instance
+     */
+    static create(config: SessionConfig | TrustSessionConfig): SessionManager;
+    /** Get the current session record. */
+    get session(): ContinuitySession;
+    /** Get a copy of the current agent state. */
+    get currentState(): AgentState;
+    /**
+     * Merge a partial update into the current state.
+     * Only works when session is active.
+     */
+    updateState(patch: AgentState): Result<void, ContinuityError>;
+    /**
+     * Replace the entire current state.
+     * Only works when session is active.
+     */
+    setState(state: AgentState): Result<void, ContinuityError>;
+    /**
+     * Persist current state as a XorIDA-split snapshot.
+     * Adds a chronicle entry for the snapshot.
+     *
+     * @param description - Optional human-readable description
+     * @param tags - Optional tags for filtering
+     * @returns StateSnapshot with stateId for later retrieval
+     */
+    snapshot(description?: string, tags?: string[]): Promise<Result<StateSnapshot, ContinuityError>>;
+    /**
+     * Restore state from a specific snapshot.
+     * Sets the current state to the reconstructed state.
+     *
+     * @param stateId - The state ID to restore
+     * @returns Reconstructed AgentState
+     */
+    restore(stateId: string): Promise<Result<AgentState, ContinuityError>>;
+    /**
+     * Restore the latest snapshot.
+     * Convenience method for restoring the most recent state.
+     */
+    restoreLatest(): Promise<Result<AgentState, ContinuityError>>;
+    /**
+     * Suspend the session. Persists current state before suspending.
+     * Can be resumed later.
+     */
+    suspend(): Promise<Result<void, ContinuityError>>;
+    /**
+     * Resume a suspended session. Restores the latest snapshot.
+     */
+    resume(): Promise<Result<AgentState, ContinuityError>>;
+    /**
+     * Close the session permanently. No further operations allowed.
+     */
+    close(): Result<void, ContinuityError>;
+    /** Get the chronicle for state history navigation. */
+    getChronicle(): Chronicle;
+    /** Get the trust store (if configured). */
+    getTrustStore(): TrustStore | undefined;
+    /** Get the mission guard (if configured). */
+    getMissionGuard(): MissionGuard | undefined;
+    /** Get the enforcement loop (if configured). */
+    getEnforcementLoop(): EnforcementLoop | undefined;
+    private updateTimestamp;
+}