@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/cjs/cancellation.js

@@ -1 +1,490 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.CancellationError=void 0,exports.createTimeoutSignal=createTimeoutSignal,exports.combineSignals=combineSignals,exports.onCancellation=onCancellation,exports.throwIfAborted=throwIfAborted,exports.withCancellation=withCancellation,exports.delay=delay,exports.withRetry=withRetry,exports.createCancellationController=createCancellationController,exports.isCancellationError=isCancellationError;const shared_1=require("../_deps/shared/index.js");class CancellationError extends Error{reason;context;constructor(e,r,n){super(e),this.reason=r,this.context=n,this.name="CancellationError"}}function createTimeoutSignal(e,r){const n=new AbortController,t=Date.now(),o=setTimeout(()=>{const t=r?.reason||`Operation timed out after ${e}ms`;n.abort(new CancellationError(t,"timeout",r?.context))},e);return{signal:n.signal,clear:()=>{clearTimeout(o)},remaining:()=>{const r=Date.now()-t;return Math.max(0,e-r)}}}function combineSignals(e){const r=e.filter(e=>e&&!e.aborted);if(0===r.length){const r=e.find(e=>e?.aborted);return r||(new AbortController).signal}if(1===r.length)return r[0];if("function"==typeof AbortSignal.any)return AbortSignal.any(r);const n=new AbortController,t=[];for(const e of r){const r=()=>{n.abort(e.reason),t.forEach(e=>e())};e.addEventListener("abort",r,{once:!0}),t.push(()=>{e.removeEventListener("abort",r)})}return n.signal}function onCancellation(e,r){e.aborted?Promise.resolve().then(()=>r()).catch(()=>{}):e.addEventListener("abort",()=>{Promise.resolve().then(()=>r()).catch(()=>{})},{once:!0})}function throwIfAborted(e,r){if(e?.aborted){const n=e.reason instanceof Error?e.reason.message:String(e.reason||"Operation was cancelled");throw new CancellationError(n,"aborted",r)}}async function withCancellation(e,r){if(!r)try{const r=await e;return(0,shared_1.ok)(r)}catch(e){return(0,shared_1.err)(new CancellationError(e instanceof Error?e.message:String(e),"promise_rejected"))}if(r.aborted){const e=r.reason instanceof Error?r.reason.message:String(r.reason||"Operation was cancelled");return(0,shared_1.err)(new CancellationError(e,"aborted"))}return new Promise(n=>{const t=()=>{const e=r.reason instanceof Error?r.reason.message:String(r.reason||"Operation was cancelled");n((0,shared_1.err)(new CancellationError(e,"aborted")))};r.addEventListener("abort",t,{once:!0}),e.then(e=>{r.removeEventListener("abort",t),n((0,shared_1.ok)(e))}).catch(e=>{r.removeEventListener("abort",t),n((0,shared_1.err)(new CancellationError(e instanceof Error?e.message:String(e),"promise_rejected")))})})}function delay(e,r){return new Promise((n,t)=>{if(r?.aborted){const e=r.reason instanceof Error?r.reason.message:String(r.reason||"Delay cancelled");return void t(new CancellationError(e,"aborted"))}const o=setTimeout(()=>{r&&r.removeEventListener("abort",a),n()},e),a=()=>{clearTimeout(o);const e=r.reason instanceof Error?r.reason.message:String(r.reason||"Delay cancelled");t(new CancellationError(e,"aborted"))};r&&r.addEventListener("abort",a,{once:!0})})}async function withRetry(e,r){const n=r?.maxAttempts??3,t=r?.initialDelay??1e3,o=r?.multiplier??2,a=r?.signal,i=r?.shouldRetry??(()=>!0);let s,l=t;for(let r=1;r<=n;r++){if(a?.aborted){const e=a.reason instanceof Error?a.reason.message:String(a.reason||"Operation was cancelled");return(0,shared_1.err)(new CancellationError(e,"aborted",{attempt:r}))}try{const r=await e();return(0,shared_1.ok)(r)}catch(e){if(s=e instanceof Error?e:new Error(String(e)),r>=n||!i(e,r))break;try{await delay(l,a),l*=o}catch(e){if(e instanceof CancellationError)return(0,shared_1.err)(e);throw e}}}return(0,shared_1.err)(s||new Error("Operation failed after retries"))}function createCancellationController(){const e=new AbortController;let r;return{signal:e.signal,get isCancelled(){return e.signal.aborted},get reason(){return r},cancel(n){r=n||"Operation cancelled",e.abort(new CancellationError(r,"manual"))},throwIfCancelled(r){throwIfAborted(e.signal,r)}}}function isCancellationError(e){return e instanceof CancellationError||e instanceof Error&&"AbortError"===e.name||e instanceof Error&&"CancellationError"===e.name}exports.CancellationError=CancellationError;
+"use strict";
+/**
+ * @module cancellation
+ * Cancellation token support for xBind operations
+ *
+ * Provides AbortController/AbortSignal integration for enhanced operation control:
+ * - Cancellable async operations (fetch, agent.call, transport)
+ * - Timeout management with automatic cleanup
+ * - Composite signals (multiple cancellation sources)
+ * - Resource cleanup on cancellation
+ *
+ * Architecture:
+ * - Uses standard AbortController/AbortSignal (Web API + Node.js)
+ * - Timeout wrapper creates time-limited signals
+ * - Composite signals combine multiple cancellation sources
+ * - Cleanup callbacks ensure proper resource disposal
+ *
+ * @example
+ * ```typescript
+ * // Timeout with cancellation
+ * const signal = createTimeoutSignal(5000);
+ * await xfetch('https://api.example.com', { signal });
+ *
+ * // Manual cancellation
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 1000);
+ * await agent.call('tool:action', params, { signal: controller.signal });
+ *
+ * // Composite signals
+ * const timeout = createTimeoutSignal(10000);
+ * const manual = new AbortController();
+ * const combined = combineSignals([timeout.signal, manual.signal]);
+ * await operation({ signal: combined });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CancellationError = void 0;
+exports.createTimeoutSignal = createTimeoutSignal;
+exports.combineSignals = combineSignals;
+exports.onCancellation = onCancellation;
+exports.throwIfAborted = throwIfAborted;
+exports.withCancellation = withCancellation;
+exports.delay = delay;
+exports.withRetry = withRetry;
+exports.createCancellationController = createCancellationController;
+exports.isCancellationError = isCancellationError;
+const shared_1 = require("../_deps/shared/index.js");
+/**
+ * Cancellation error thrown when operation is aborted
+ */
+class CancellationError extends Error {
+    reason;
+    context;
+    constructor(message, reason, context) {
+        super(message);
+        this.reason = reason;
+        this.context = context;
+        this.name = 'CancellationError';
+    }
+}
+exports.CancellationError = CancellationError;
+/**
+ * Create an AbortSignal that triggers after a timeout
+ *
+ * Automatically aborts the signal after the specified duration.
+ * Useful for setting time limits on async operations.
+ *
+ * @param timeout - Timeout in milliseconds
+ * @param options - Optional reason and context
+ * @returns TimeoutController with signal and clear function
+ *
+ * @example
+ * ```typescript
+ * const timeout = createTimeoutSignal(5000);
+ * try {
+ *   await fetch('https://api.example.com', { signal: timeout.signal });
+ * } catch (error) {
+ *   if (error.name === 'AbortError') {
+ *     console.log('Request timed out after 5s');
+ *   }
+ * } finally {
+ *   timeout.clear(); // Clean up timer
+ * }
+ * ```
+ */
+function createTimeoutSignal(timeout, options) {
+    const controller = new AbortController();
+    const startTime = Date.now();
+    const timeoutId = setTimeout(() => {
+        const reason = options?.reason || `Operation timed out after ${timeout}ms`;
+        controller.abort(new CancellationError(reason, 'timeout', options?.context));
+    }, timeout);
+    return {
+        signal: controller.signal,
+        clear: () => {
+            clearTimeout(timeoutId);
+        },
+        remaining: () => {
+            const elapsed = Date.now() - startTime;
+            return Math.max(0, timeout - elapsed);
+        },
+    };
+}
+/**
+ * Combine multiple AbortSignals into a single signal
+ *
+ * The combined signal aborts when ANY of the source signals abort.
+ * Useful for operations with multiple cancellation sources (timeout, user action, etc.).
+ *
+ * @param signals - Array of signals to combine
+ * @returns Combined AbortSignal
+ *
+ * @example
+ * ```typescript
+ * const timeout = createTimeoutSignal(10000);
+ * const userCancel = new AbortController();
+ * const combined = combineSignals([timeout.signal, userCancel.signal]);
+ *
+ * // Either timeout OR user cancellation will abort
+ * await fetch('https://api.example.com', { signal: combined });
+ * ```
+ */
+function combineSignals(signals) {
+    // Filter out already-aborted signals and undefined
+    const activeSignals = signals.filter(s => s && !s.aborted);
+    // If all signals are already aborted, return an aborted signal
+    if (activeSignals.length === 0) {
+        const alreadyAborted = signals.find(s => s?.aborted);
+        if (alreadyAborted) {
+            // Return already-aborted signal
+            return alreadyAborted;
+        }
+        // No signals provided - return never-aborts signal
+        return new AbortController().signal;
+    }
+    // If only one active signal, return it directly
+    if (activeSignals.length === 1) {
+        return activeSignals[0];
+    }
+    // Use AbortSignal.any() if available (Node 20+, modern browsers)
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any(activeSignals);
+    }
+    // Fallback: manually combine signals
+    const controller = new AbortController();
+    const abortListeners = [];
+    for (const signal of activeSignals) {
+        const listener = () => {
+            controller.abort(signal.reason);
+            // Remove all listeners after first abort
+            abortListeners.forEach((remove) => remove());
+        };
+        signal.addEventListener('abort', listener, { once: true });
+        // Store cleanup function
+        abortListeners.push(() => {
+            signal.removeEventListener('abort', listener);
+        });
+    }
+    return controller.signal;
+}
+/**
+ * Register cleanup callback to run when signal is aborted
+ *
+ * Ensures resources are properly disposed when operation is cancelled.
+ * Cleanup runs immediately if signal is already aborted.
+ *
+ * @param signal - AbortSignal to monitor
+ * @param cleanup - Cleanup callback
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * const connection = await openConnection();
+ *
+ * onCancellation(controller.signal, async () => {
+ *   console.log('Cleaning up connection...');
+ *   await connection.close();
+ * });
+ *
+ * // Later...
+ * controller.abort(); // Cleanup runs automatically
+ * ```
+ */
+function onCancellation(signal, cleanup) {
+    // If already aborted, run cleanup immediately
+    if (signal.aborted) {
+        void Promise.resolve().then(() => cleanup()).catch(() => {
+            // Cleanup errors are handled silently to avoid unhandled rejections
+        });
+        return;
+    }
+    // Register cleanup to run on abort
+    signal.addEventListener('abort', () => {
+        // Run cleanup and catch errors silently to avoid unhandled rejections
+        void Promise.resolve().then(() => cleanup()).catch(() => {
+            // Cleanup errors are expected and handled silently
+            // (test can spy on this if needed, but we don't log by default)
+        });
+    }, { once: true });
+}
+/**
+ * Check if signal is aborted and throw CancellationError if so
+ *
+ * Useful for checking cancellation at specific points in long-running operations.
+ *
+ * @param signal - AbortSignal to check
+ * @param context - Optional context for error
+ * @throws CancellationError if signal is aborted
+ *
+ * @example
+ * ```typescript
+ * async function processLargeDataset(data: unknown[], signal?: AbortSignal) {
+ *   for (const item of data) {
+ *     throwIfAborted(signal, { item: item.id });
+ *     await processItem(item);
+ *   }
+ * }
+ * ```
+ */
+function throwIfAborted(signal, context) {
+    if (signal?.aborted) {
+        const reason = signal.reason instanceof Error
+            ? signal.reason.message
+            : String(signal.reason || 'Operation was cancelled');
+        throw new CancellationError(reason, 'aborted', context);
+    }
+}
+/**
+ * Wrap a promise with cancellation support
+ *
+ * If signal aborts before promise resolves, returns error result.
+ * Otherwise returns the promise's result.
+ *
+ * @param promise - Promise to wrap
+ * @param signal - AbortSignal for cancellation
+ * @returns Result wrapper around promise
+ *
+ * @example
+ * ```typescript
+ * const timeout = createTimeoutSignal(5000);
+ * const result = await withCancellation(
+ *   fetch('https://api.example.com'),
+ *   timeout.signal
+ * );
+ *
+ * if (!result.ok) {
+ *   console.error('Request cancelled:', result.error.message);
+ * }
+ * ```
+ */
+async function withCancellation(promise, signal) {
+    if (!signal) {
+        // No signal - just await promise
+        try {
+            const value = await promise;
+            return (0, shared_1.ok)(value);
+        }
+        catch (error) {
+            return (0, shared_1.err)(new CancellationError(error instanceof Error ? error.message : String(error), 'promise_rejected'));
+        }
+    }
+    // If already aborted, return immediately
+    if (signal.aborted) {
+        const reason = signal.reason instanceof Error
+            ? signal.reason.message
+            : String(signal.reason || 'Operation was cancelled');
+        return (0, shared_1.err)(new CancellationError(reason, 'aborted'));
+    }
+    // Race promise against abort signal
+    return new Promise((resolve) => {
+        // Handle abort
+        const onAbort = () => {
+            const reason = signal.reason instanceof Error
+                ? signal.reason.message
+                : String(signal.reason || 'Operation was cancelled');
+            resolve((0, shared_1.err)(new CancellationError(reason, 'aborted')));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        // Handle promise resolution
+        promise
+            .then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve((0, shared_1.ok)(value));
+        })
+            .catch((error) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve((0, shared_1.err)(new CancellationError(error instanceof Error ? error.message : String(error), 'promise_rejected')));
+        });
+    });
+}
+/**
+ * Create a cancellable delay
+ *
+ * Returns a promise that resolves after the specified duration,
+ * but can be cancelled early via signal.
+ *
+ * @param ms - Delay in milliseconds
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Promise that resolves after delay or rejects on cancellation
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * // Start 10s delay
+ * const delayPromise = delay(10000, controller.signal);
+ *
+ * // Cancel after 2s
+ * setTimeout(() => controller.abort(), 2000);
+ *
+ * try {
+ *   await delayPromise; // Throws CancellationError after 2s
+ * } catch (error) {
+ *   console.log('Delay cancelled');
+ * }
+ * ```
+ */
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        // Check if already aborted
+        if (signal?.aborted) {
+            const reason = signal.reason instanceof Error
+                ? signal.reason.message
+                : String(signal.reason || 'Delay cancelled');
+            reject(new CancellationError(reason, 'aborted'));
+            return;
+        }
+        const timeoutId = setTimeout(() => {
+            if (signal) {
+                signal.removeEventListener('abort', onAbort);
+            }
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeoutId);
+            const reason = signal.reason instanceof Error
+                ? signal.reason.message
+                : String(signal.reason || 'Delay cancelled');
+            reject(new CancellationError(reason, 'aborted'));
+        };
+        if (signal) {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+/**
+ * Retry an operation with cancellation support
+ *
+ * Attempts operation multiple times with exponential backoff.
+ * Respects cancellation signal between retry attempts.
+ *
+ * @param operation - Async operation to retry
+ * @param options - Retry configuration
+ * @returns Result of operation
+ *
+ * @example
+ * ```typescript
+ * const timeout = createTimeoutSignal(30000);
+ *
+ * const result = await withRetry(
+ *   async () => {
+ *     const res = await fetch('https://api.example.com');
+ *     if (!res.ok) throw new Error('Request failed');
+ *     return res.json();
+ *   },
+ *   {
+ *     maxAttempts: 5,
+ *     initialDelay: 1000,
+ *     multiplier: 2,
+ *     signal: timeout.signal,
+ *   }
+ * );
+ * ```
+ */
+async function withRetry(operation, options) {
+    const maxAttempts = options?.maxAttempts ?? 3;
+    const initialDelay = options?.initialDelay ?? 1000;
+    const multiplier = options?.multiplier ?? 2;
+    const signal = options?.signal;
+    const shouldRetry = options?.shouldRetry ?? (() => true);
+    let lastError;
+    let delayMs = initialDelay;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        // Check cancellation before attempt
+        if (signal?.aborted) {
+            const reason = signal.reason instanceof Error
+                ? signal.reason.message
+                : String(signal.reason || 'Operation was cancelled');
+            return (0, shared_1.err)(new CancellationError(reason, 'aborted', { attempt }));
+        }
+        try {
+            const value = await operation();
+            return (0, shared_1.ok)(value);
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // On last attempt or if shouldRetry returns false, don't retry
+            if (attempt >= maxAttempts || !shouldRetry(error, attempt)) {
+                // No more attempts or predicate said no
+                break;
+            }
+            // Wait before retry (with cancellation support)
+            try {
+                await delay(delayMs, signal);
+                delayMs *= multiplier;
+            }
+            catch (cancelError) {
+                // Cancelled during delay
+                if (cancelError instanceof CancellationError) {
+                    return (0, shared_1.err)(cancelError);
+                }
+                throw cancelError;
+            }
+        }
+    }
+    // All attempts failed
+    return (0, shared_1.err)(lastError || new Error('Operation failed after retries'));
+}
+/**
+ * Create a manual cancellation controller with helper methods
+ *
+ * Extends AbortController with additional utilities for common patterns.
+ *
+ * @returns Enhanced controller with helper methods
+ *
+ * @example
+ * ```typescript
+ * const controller = createCancellationController();
+ *
+ * // Start operation
+ * const promise = longRunningOperation({ signal: controller.signal });
+ *
+ * // Cancel with custom reason
+ * controller.cancel('User requested cancellation');
+ *
+ * // Check if cancelled
+ * if (controller.isCancelled) {
+ *   console.log('Operation was cancelled');
+ * }
+ * ```
+ */
+function createCancellationController() {
+    const controller = new AbortController();
+    let cancelledReason;
+    return {
+        /** Abort signal for cancellation */
+        signal: controller.signal,
+        /** True if operation has been cancelled */
+        get isCancelled() {
+            return controller.signal.aborted;
+        },
+        /** Reason for cancellation (if any) */
+        get reason() {
+            return cancelledReason;
+        },
+        /** Cancel the operation with optional reason */
+        cancel(reason) {
+            cancelledReason = reason || 'Operation cancelled';
+            controller.abort(new CancellationError(cancelledReason, 'manual'));
+        },
+        /** Throw if cancelled */
+        throwIfCancelled(context) {
+            throwIfAborted(controller.signal, context);
+        },
+    };
+}
+/**
+ * Check if an error is a cancellation error
+ *
+ * @param error - Error to check
+ * @returns True if error is from cancellation
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await operation({ signal });
+ * } catch (error) {
+ *   if (isCancellationError(error)) {
+ *     console.log('Operation was cancelled');
+ *   } else {
+ *     console.error('Operation failed:', error);
+ *   }
+ * }
+ * ```
+ */
+function isCancellationError(error) {
+    return error instanceof CancellationError ||
+        (error instanceof Error && error.name === 'AbortError') ||
+        (error instanceof Error && error.name === 'CancellationError');
+}

package/dist-standalone/cjs/checkpoint.js

@@ -1 +1,193 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.createCheckpoint=createCheckpoint,exports.verifyCheckpoint=verifyCheckpoint,exports.isCacheStale=isCacheStale,exports.encodeCheckpoint=encodeCheckpoint,exports.decodeCheckpoint=decodeCheckpoint;const shared_1=require("../_deps/shared/index.js"),identity_js_1=require("./identity.js");async function createCheckpoint(e,r,t,n,i){const o=Date.now(),c=Buffer.from(r).toString("base64"),s=`DIDStateCheckpoint||1.0||${e}||${c}||${t}||${n}||${o}`,a=(new TextEncoder).encode(s),u=await(0,identity_js_1.signMlDsa65)(i,a);return u.ok?(0,shared_1.ok)({type:"DIDStateCheckpoint",version:"1.0",subject:e,current_public_key:c,revoked:t,rotation_sequence:n,timestamp:o,checkpoint_signature_algorithm:"ML-DSA-65",checkpoint_signature:Buffer.from(u.value).toString("base64")}):(0,shared_1.err)("SIGN_FAILED")}async function verifyCheckpoint(e,r){if("DIDStateCheckpoint"!==e.type)return(0,shared_1.err)("INVALID_FORMAT");if("1.0"!==e.version)return(0,shared_1.err)("INVALID_FORMAT");if(!e.subject||!e.current_public_key)return(0,shared_1.err)("INVALID_FORMAT");if("number"!=typeof e.rotation_sequence||e.rotation_sequence<0)return(0,shared_1.err)("INVALID_FORMAT");if("number"!=typeof e.timestamp||e.timestamp<=0)return(0,shared_1.err)("INVALID_TIMESTAMP");if("ML-DSA-65"!==e.checkpoint_signature_algorithm)return(0,shared_1.err)("INVALID_FORMAT");const t=`DIDStateCheckpoint||1.0||${e.subject}||${e.current_public_key}||${e.revoked}||${e.rotation_sequence}||${e.timestamp}`,n=(new TextEncoder).encode(t);let i;try{i=Buffer.from(e.checkpoint_signature,"base64")}catch{return(0,shared_1.err)("INVALID_SIGNATURE")}const o=await(0,identity_js_1.verifyMlDsa65)(r,i,n);return o.ok?(0,shared_1.ok)(o.value):(0,shared_1.err)("VERIFY_FAILED")}function isCacheStale(e,r){if(r.rotation_sequence>e.rotationSequence)return!0;if(r.revoked!==e.revoked)return!0;const t=Buffer.from(r.current_public_key,"base64");return!Buffer.from(e.publicKey).equals(t)}function encodeCheckpoint(e){return JSON.stringify(e)}function decodeCheckpoint(e){try{const r=JSON.parse(e);return"DIDStateCheckpoint"!==r.type||"1.0"!==r.version?(0,shared_1.err)("INVALID_FORMAT"):r.subject&&r.current_public_key&&r.checkpoint_signature?(0,shared_1.ok)(r):(0,shared_1.err)("INVALID_FORMAT")}catch{return(0,shared_1.err)("INVALID_FORMAT")}}
+"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');
+    }
+}