@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/runtime/edge.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Edge Runtime Support for xBind
+ *
+ * Enables xBind to run on edge compute platforms:
+ * - Cloudflare Workers
+ * - Vercel Edge Functions
+ * - Deno Deploy
+ *
+ * Key Features:
+ * - Edge-compatible crypto operations (Web Crypto API only)
+ * - KV storage integration for nonce stores and trust registry
+ * - Size-optimized build (<1MB constraint)
+ * - No Node.js dependencies (no fs, crypto, process)
+ */
+import type { Result } from '@private.me/shared';
+import type { NonceStore, ShareContext } from '../nonce-store.js';
+import type { TrustRegistry, RegistryError } from '../trust-registry.js';
+import type { XailTransportAdapter, EnvelopeHandler, TransportError } from '../transport.js';
+import type { AnyTransportEnvelope } from '../envelope.js';
+/**
+ * Detected edge runtime environment.
+ */
+export type EdgeRuntime = 'cloudflare' | 'vercel' | 'deno' | 'node' | 'unknown';
+/**
+ * Detect the current edge runtime environment.
+ *
+ * Detection order:
+ * 1. Cloudflare Workers: globalThis.caches + EdgeRuntime
+ * 2. Vercel Edge: process.env.VERCEL + EdgeRuntime
+ * 3. Deno Deploy: globalThis.Deno
+ * 4. Node.js: process.versions.node
+ * 5. Unknown: fallback
+ */
+export declare function detectRuntime(): EdgeRuntime;
+/**
+ * Check if the current runtime is an edge environment.
+ */
+export declare function isEdgeRuntime(): boolean;
+/**
+ * Validate that the runtime supports required Web Crypto APIs.
+ *
+ * Edge runtimes MUST provide:
+ * - crypto.subtle (Ed25519, X25519, AES-GCM, HMAC)
+ * - crypto.getRandomValues()
+ * - TextEncoder/TextDecoder
+ */
+export declare function validateEdgeRuntime(): Result<void, string>;
+/**
+ * Generic KV storage interface for edge runtimes.
+ *
+ * Implementations:
+ * - Cloudflare KV
+ * - Vercel KV (Redis)
+ * - Deno KV
+ */
+export interface EdgeKVStore {
+    /**
+     * Get a value by key.
+     * @returns value or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a value with optional TTL.
+     * @param key Storage key
+     * @param value String value
+     * @param ttlSeconds Time-to-live in seconds (optional)
+     */
+    put(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    /**
+     * Delete a key.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List keys with optional prefix.
+     * @param prefix Key prefix for filtering
+     * @param limit Maximum number of keys to return
+     * @returns Array of matching keys
+     */
+    list(prefix?: string, limit?: number): Promise<string[]>;
+}
+/**
+ * Cloudflare Workers KV namespace binding.
+ * Available via env.NAMESPACE in Workers.
+ */
+export interface CloudflareKVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+    }): Promise<{
+        keys: Array<{
+            name: string;
+        }>;
+    }>;
+}
+/**
+ * Adapter for Cloudflare Workers KV.
+ */
+export declare class CloudflareKVAdapter implements EdgeKVStore {
+    private readonly namespace;
+    constructor(namespace: CloudflareKVNamespace);
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number): Promise<string[]>;
+}
+/**
+ * Vercel KV client interface (Redis-compatible).
+ */
+export interface VercelKVClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        ex?: number;
+    }): Promise<void>;
+    del(key: string): Promise<void>;
+    keys(pattern: string): Promise<string[]>;
+}
+/**
+ * Adapter for Vercel KV (Redis).
+ */
+export declare class VercelKVAdapter implements EdgeKVStore {
+    private readonly client;
+    constructor(client: VercelKVClient);
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number): Promise<string[]>;
+}
+/**
+ * Deno KV interface.
+ */
+export interface DenoKV {
+    get(key: string[]): Promise<{
+        value: string | null;
+    }>;
+    set(key: string[], value: string, options?: {
+        expireIn?: number;
+    }): Promise<void>;
+    delete(key: string[]): Promise<void>;
+    list(selector: {
+        prefix: string[];
+    }): AsyncIterableIterator<{
+        key: string[];
+        value: string;
+    }>;
+}
+/**
+ * Adapter for Deno KV.
+ */
+export declare class DenoKVAdapter implements EdgeKVStore {
+    private readonly kv;
+    constructor(kv: DenoKV);
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, limit?: number): Promise<string[]>;
+}
+/**
+ * Nonce store implementation using KV storage.
+ *
+ * Suitable for edge runtimes where in-memory storage
+ * is ephemeral across invocations.
+ */
+export declare class KVNonceStore implements NonceStore {
+    private readonly kv;
+    private readonly ttlSeconds;
+    constructor(kv: EdgeKVStore, ttlMs?: number);
+    /**
+     * Build composite key: xbind:nonce:{senderDid}:{nonce}:{shareGroupId}:{shareIndex}
+     */
+    private buildKey;
+    check(nonce: string, senderDid: string, shareContext?: ShareContext): Promise<boolean>;
+    cleanup(): void;
+    dispose(): void;
+}
+/**
+ * Trust registry implementation using KV storage.
+ *
+ * Stores DID registrations in edge KV for distributed lookups.
+ * Simplified version suitable for edge runtimes - stores minimal metadata.
+ */
+export declare class KVTrustRegistry implements TrustRegistry {
+    private readonly kv;
+    constructor(kv: EdgeKVStore);
+    /**
+     * Build key: xbind:trust:{did}
+     */
+    private buildKey;
+    register(did: string, publicKey: Uint8Array, name: string, scopes?: string[], x25519PublicKey?: Uint8Array, mlKemPublicKey?: Uint8Array, mlDsaPublicKey?: Uint8Array, xchange?: boolean, receiveScopes?: string[], sdkVersion?: string, minEnvelopeVersion?: number, maxEnvelopeVersion?: number, ttlMs?: number): Promise<Result<void, RegistryError>>;
+    resolve(did: string): Promise<Result<Uint8Array, RegistryError>>;
+    hasScope(did: string, scope: string): Promise<boolean>;
+    hasReceiveScope(did: string, scope: string): Promise<boolean>;
+    revoke(did: string): Promise<Result<void, RegistryError>>;
+    list(): Promise<string[]>;
+    getEntry(did: string): Promise<Result<import('../trust-registry.js').RegistryEntry, RegistryError>>;
+    /** Additional methods for edge compatibility */
+    getFullEntry(did: string): Promise<Result<Record<string, unknown>, RegistryError>>;
+    dispose(): void;
+}
+/**
+ * Edge-compatible HTTPS transport adapter.
+ *
+ * Uses standard fetch API (available in all edge runtimes).
+ * Optimized for edge constraints:
+ * - No Node.js http/https modules
+ * - No setTimeout (uses AbortSignal.timeout)
+ * - Minimal allocations
+ */
+export declare class EdgeTransportAdapter implements XailTransportAdapter {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private handlers;
+    constructor(opts: {
+        baseUrl: string;
+        timeoutMs?: number;
+    });
+    send(envelope: AnyTransportEnvelope, recipientDid: string): Promise<Result<void, TransportError>>;
+    onReceive(handler: EnvelopeHandler): void;
+    /**
+     * Dispatch received envelope to all handlers.
+     * Called by edge function handler when processing incoming requests.
+     */
+    dispatch(envelope: AnyTransportEnvelope): void;
+    dispose(): void;
+}
+/**
+ * Options for creating an edge-compatible agent.
+ */
+export interface EdgeAgentOptions {
+    /** KV store for nonce deduplication and trust registry */
+    readonly kv: EdgeKVStore;
+    /** Base URL for message transport */
+    readonly baseUrl: string;
+    /** Request timeout in milliseconds */
+    readonly timeoutMs?: number;
+    /** Nonce TTL in milliseconds */
+    readonly nonceTtlMs?: number;
+}
+/**
+ * Create edge-compatible xBind components.
+ *
+ * Returns nonce store, trust registry, and transport adapter
+ * configured for the edge runtime.
+ *
+ * @example
+ * ```typescript
+ * // Cloudflare Workers
+ * const kv = new CloudflareKVAdapter(env.XBIND_KV);
+ * const { nonceStore, trustRegistry, transport } = createEdgeAgent({
+ *   kv,
+ *   baseUrl: 'https://private.me/relay',
+ * });
+ *
+ * const agent = new Agent({
+ *   identity: 'persistent',
+ *   nonceStore,
+ *   trustRegistry,
+ *   transport,
+ * });
+ * ```
+ */
+export declare function createEdgeAgent(opts: EdgeAgentOptions): {
+    nonceStore: KVNonceStore;
+    trustRegistry: KVTrustRegistry;
+    transport: EdgeTransportAdapter;
+};
+/**
+ * Check if the bundled size is within edge runtime limits.
+ *
+ * Cloudflare Workers: 1MB compressed limit
+ * Vercel Edge: 1MB limit
+ * Deno Deploy: 1MB limit
+ */
+export declare function checkBundleSize(bundleSizeBytes: number): Result<void, string>;
+/**
+ * Get edge-optimized build recommendations.
+ */
+export declare function getOptimizationTips(): string[];