@private.me/xbind 1.3.5 → 3.0.0

package/dist-standalone/cancellation.d.ts

@@ -0,0 +1,301 @@
+/**
+ * @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 });
+ * ```
+ */
+import type { Result } from '@private.me/shared';
+/**
+ * Cancellation error thrown when operation is aborted
+ */
+export declare class CancellationError extends Error {
+    reason?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+    constructor(message: string, reason?: string | undefined, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Cleanup callback type for resource disposal
+ */
+export type CleanupCallback = () => void | Promise<void>;
+/**
+ * Timeout signal controller with cleanup
+ */
+export interface TimeoutController {
+    /** Abort signal that triggers on timeout */
+    signal: AbortSignal;
+    /** Clear timeout (prevents abort) */
+    clear: () => void;
+    /** Remaining time in milliseconds */
+    remaining: () => number;
+}
+/**
+ * Options for creating timeout signals
+ */
+export interface TimeoutOptions {
+    /** Timeout in milliseconds */
+    timeout: number;
+    /** Optional reason message */
+    reason?: string;
+    /** Optional context for debugging */
+    context?: Record<string, unknown>;
+}
+/**
+ * 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
+ * }
+ * ```
+ */
+export declare function createTimeoutSignal(timeout: number, options?: Omit<TimeoutOptions, 'timeout'>): TimeoutController;
+/**
+ * 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 });
+ * ```
+ */
+export declare function combineSignals(signals: AbortSignal[]): AbortSignal;
+/**
+ * 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
+ * ```
+ */
+export declare function onCancellation(signal: AbortSignal, cleanup: CleanupCallback): void;
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+export declare function throwIfAborted(signal?: AbortSignal, context?: Record<string, unknown>): void;
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare function withCancellation<T>(promise: Promise<T>, signal?: AbortSignal): Promise<Result<T, CancellationError>>;
+/**
+ * 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');
+ * }
+ * ```
+ */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * 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,
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: {
+    maxAttempts?: number;
+    initialDelay?: number;
+    multiplier?: number;
+    signal?: AbortSignal;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+}): Promise<Result<T, Error>>;
+/**
+ * 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');
+ * }
+ * ```
+ */
+export declare function createCancellationController(): {
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+    /** True if operation has been cancelled */
+    readonly isCancelled: boolean;
+    /** Reason for cancellation (if any) */
+    readonly reason: string | undefined;
+    /** Cancel the operation with optional reason */
+    cancel(reason?: string): void;
+    /** Throw if cancelled */
+    throwIfCancelled(context?: Record<string, unknown>): void;
+};
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+export declare function isCancellationError(error: unknown): error is CancellationError;

package/dist-standalone/cancellation.js

@@ -0,0 +1 @@
+import{ok,err}from"./_deps/shared/index.js";export class CancellationError extends Error{reason;context;constructor(r,e,n){super(r),this.reason=e,this.context=n,this.name="CancellationError"}}export function createTimeoutSignal(r,e){const n=new AbortController,t=Date.now(),o=setTimeout(()=>{const t=e?.reason||`Operation timed out after ${r}ms`;n.abort(new CancellationError(t,"timeout",e?.context))},r);return{signal:n.signal,clear:()=>{clearTimeout(o)},remaining:()=>{const e=Date.now()-t;return Math.max(0,r-e)}}}export function combineSignals(r){const e=r.filter(r=>r&&!r.aborted);if(0===e.length){const e=r.find(r=>r?.aborted);return e||(new AbortController).signal}if(1===e.length)return e[0];if("function"==typeof AbortSignal.any)return AbortSignal.any(e);const n=new AbortController,t=[];for(const r of e){const e=()=>{n.abort(r.reason),t.forEach(r=>r())};r.addEventListener("abort",e,{once:!0}),t.push(()=>{r.removeEventListener("abort",e)})}return n.signal}export function onCancellation(r,e){r.aborted?Promise.resolve().then(()=>e()).catch(()=>{}):r.addEventListener("abort",()=>{Promise.resolve().then(()=>e()).catch(()=>{})},{once:!0})}export function throwIfAborted(r,e){if(r?.aborted){const n=r.reason instanceof Error?r.reason.message:String(r.reason||"Operation was cancelled");throw new CancellationError(n,"aborted",e)}}export async function withCancellation(r,e){if(!e)try{const e=await r;return ok(e)}catch(r){return err(new CancellationError(r instanceof Error?r.message:String(r),"promise_rejected"))}if(e.aborted){const r=e.reason instanceof Error?e.reason.message:String(e.reason||"Operation was cancelled");return err(new CancellationError(r,"aborted"))}return new Promise(n=>{const t=()=>{const r=e.reason instanceof Error?e.reason.message:String(e.reason||"Operation was cancelled");n(err(new CancellationError(r,"aborted")))};e.addEventListener("abort",t,{once:!0}),r.then(r=>{e.removeEventListener("abort",t),n(ok(r))}).catch(r=>{e.removeEventListener("abort",t),n(err(new CancellationError(r instanceof Error?r.message:String(r),"promise_rejected")))})})}export function delay(r,e){return new Promise((n,t)=>{if(e?.aborted){const r=e.reason instanceof Error?e.reason.message:String(e.reason||"Delay cancelled");return void t(new CancellationError(r,"aborted"))}const o=setTimeout(()=>{e&&e.removeEventListener("abort",a),n()},r),a=()=>{clearTimeout(o);const r=e.reason instanceof Error?e.reason.message:String(e.reason||"Delay cancelled");t(new CancellationError(r,"aborted"))};e&&e.addEventListener("abort",a,{once:!0})})}export async function withRetry(r,e){const n=e?.maxAttempts??3,t=e?.initialDelay??1e3,o=e?.multiplier??2,a=e?.signal,i=e?.shouldRetry??(()=>!0);let s,c=t;for(let e=1;e<=n;e++){if(a?.aborted){const r=a.reason instanceof Error?a.reason.message:String(a.reason||"Operation was cancelled");return err(new CancellationError(r,"aborted",{attempt:e}))}try{const e=await r();return ok(e)}catch(r){if(s=r instanceof Error?r:new Error(String(r)),e>=n||!i(r,e))break;try{await delay(c,a),c*=o}catch(r){if(r instanceof CancellationError)return err(r);throw r}}}return err(s||new Error("Operation failed after retries"))}export function createCancellationController(){const r=new AbortController;let e;return{signal:r.signal,get isCancelled(){return r.signal.aborted},get reason(){return e},cancel(n){e=n||"Operation cancelled",r.abort(new CancellationError(e,"manual"))},throwIfCancelled(e){throwIfAborted(r.signal,e)}}}export function isCancellationError(r){return r instanceof CancellationError||r instanceof Error&&"AbortError"===r.name||r instanceof Error&&"CancellationError"===r.name}

package/dist-standalone/checkpoint.js

@@ -1,186 +1 @@
-import { ok, err } from"./_deps/shared/index.js";
-import { signMlDsa65, verifyMlDsa65 } from './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);
- * }
- * ```
- */
-export 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 signMlDsa65(gatewayPrivateKey, messageBytes);
-    if (!sigResult.ok) {
-        return err('SIGN_FAILED');
-    }
-    return 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
- *   }
- * }
- * ```
- */
-export async function verifyCheckpoint(checkpoint, gatewayPublicKey) {
-    // Validate checkpoint format
-    if (checkpoint.type !== 'DIDStateCheckpoint') {
-        return err('INVALID_FORMAT');
-    }
-    if (checkpoint.version !== '1.0') {
-        return err('INVALID_FORMAT');
-    }
-    if (!checkpoint.subject || !checkpoint.current_public_key) {
-        return err('INVALID_FORMAT');
-    }
-    if (typeof checkpoint.rotation_sequence !== 'number' || checkpoint.rotation_sequence < 0) {
-        return err('INVALID_FORMAT');
-    }
-    if (typeof checkpoint.timestamp !== 'number' || checkpoint.timestamp <= 0) {
-        return err('INVALID_TIMESTAMP');
-    }
-    if (checkpoint.checkpoint_signature_algorithm !== 'ML-DSA-65') {
-        return 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 err('INVALID_SIGNATURE');
-    }
-    // Verify signature using gateway public key
-    const verifyResult = await verifyMlDsa65(gatewayPublicKey, signature, messageBytes);
-    if (!verifyResult.ok) {
-        return err('VERIFY_FAILED');
-    }
-    return 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);
- * }
- * ```
- */
-export 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
- */
-export function encodeCheckpoint(checkpoint) {
-    return JSON.stringify(checkpoint);
-}
-/**
- * Decode checkpoint from JSON string.
- *
- * @param encoded - JSON string
- * @returns Parsed checkpoint or error
- */
-export function decodeCheckpoint(encoded) {
-    try {
-        const parsed = JSON.parse(encoded);
-        // Basic validation
-        if (parsed.type !== 'DIDStateCheckpoint') {
-            return err('INVALID_FORMAT');
-        }
-        if (parsed.version !== '1.0') {
-            return err('INVALID_FORMAT');
-        }
-        if (!parsed.subject || !parsed.current_public_key || !parsed.checkpoint_signature) {
-            return err('INVALID_FORMAT');
-        }
-        return ok(parsed);
-    }
-    catch {
-        return err('INVALID_FORMAT');
-    }
-}
+import{ok,err}from"./_deps/shared/index.js";import{signMlDsa65,verifyMlDsa65}from"./identity.js";export async function createCheckpoint(e,r,t,n,o){const i=Date.now(),c=Buffer.from(r).toString("base64"),u=`DIDStateCheckpoint||1.0||${e}||${c}||${t}||${n}||${i}`,a=(new TextEncoder).encode(u),s=await signMlDsa65(o,a);return s.ok?ok({type:"DIDStateCheckpoint",version:"1.0",subject:e,current_public_key:c,revoked:t,rotation_sequence:n,timestamp:i,checkpoint_signature_algorithm:"ML-DSA-65",checkpoint_signature:Buffer.from(s.value).toString("base64")}):err("SIGN_FAILED")}export async function verifyCheckpoint(e,r){if("DIDStateCheckpoint"!==e.type)return err("INVALID_FORMAT");if("1.0"!==e.version)return err("INVALID_FORMAT");if(!e.subject||!e.current_public_key)return err("INVALID_FORMAT");if("number"!=typeof e.rotation_sequence||e.rotation_sequence<0)return err("INVALID_FORMAT");if("number"!=typeof e.timestamp||e.timestamp<=0)return err("INVALID_TIMESTAMP");if("ML-DSA-65"!==e.checkpoint_signature_algorithm)return 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 o;try{o=Buffer.from(e.checkpoint_signature,"base64")}catch{return err("INVALID_SIGNATURE")}const i=await verifyMlDsa65(r,o,n);return i.ok?ok(i.value):err("VERIFY_FAILED")}export 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)}export function encodeCheckpoint(e){return JSON.stringify(e)}export function decodeCheckpoint(e){try{const r=JSON.parse(e);return"DIDStateCheckpoint"!==r.type||"1.0"!==r.version?err("INVALID_FORMAT"):r.subject&&r.current_public_key&&r.checkpoint_signature?ok(r):err("INVALID_FORMAT")}catch{return err("INVALID_FORMAT")}}