@private.me/xbind 3.0.0 → 3.0.1

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[];

package/dist-standalone/runtime/edge.js

@@ -0,0 +1 @@
+import{ok,err}from"../_deps/shared/index.js";export function detectRuntime(){const e=globalThis;return void 0!==e.caches&&"string"==typeof e.EdgeRuntime?"cloudflare":"string"==typeof e.EdgeRuntime&&"undefined"!=typeof process&&"1"===process.env?.VERCEL?"vercel":void 0!==e.Deno?"deno":"undefined"!=typeof process&&"string"==typeof process.versions?.node?"node":"unknown"}export function isEdgeRuntime(){const e=detectRuntime();return"cloudflare"===e||"vercel"===e||"deno"===e}export function validateEdgeRuntime(){if(void 0===globalThis.crypto)return err("Missing globalThis.crypto");if(void 0===globalThis.crypto.subtle)return err("Missing crypto.subtle");if("function"!=typeof globalThis.crypto.getRandomValues)return err("Missing crypto.getRandomValues");const e=["generateKey","sign","verify","encrypt","decrypt","deriveBits","importKey","exportKey"];for(const t of e)if("function"!=typeof globalThis.crypto.subtle[t])return err(`Missing crypto.subtle.${t}`);return void 0===globalThis.TextEncoder?err("Missing TextEncoder"):void 0===globalThis.TextDecoder?err("Missing TextDecoder"):"function"!=typeof globalThis.fetch?err("Missing fetch API"):ok(void 0)}export class CloudflareKVAdapter{namespace;constructor(e){this.namespace=e}async get(e){return await this.namespace.get(e)}async put(e,t,r){const s=r?{expirationTtl:r}:void 0;await this.namespace.put(e,t,s)}async delete(e){await this.namespace.delete(e)}async list(e,t){return(await this.namespace.list({prefix:e,limit:t})).keys.map(e=>e.name)}}export class VercelKVAdapter{client;constructor(e){this.client=e}async get(e){return await this.client.get(e)}async put(e,t,r){const s=r?{ex:r}:void 0;await this.client.set(e,t,s)}async delete(e){await this.client.del(e)}async list(e,t){const r=e?`${e}*`:"*",s=await this.client.keys(r);return t?s.slice(0,t):s}}export class DenoKVAdapter{kv;constructor(e){this.kv=e}async get(e){return(await this.kv.get([e])).value}async put(e,t,r){const s=r?{expireIn:1e3*r}:void 0;await this.kv.set([e],t,s)}async delete(e){await this.kv.delete([e])}async list(e,t){const r={prefix:e?[e]:[]},s=[];for await(const e of this.kv.list(r))if(s.push(e.key.join("/")),t&&s.length>=t)break;return s}}export class KVNonceStore{kv;ttlSeconds;constructor(e,t=6e5){this.kv=e,this.ttlSeconds=Math.floor(t/1e3)}buildKey(e,t,r){const s=`xbind:nonce:${t}:${e}`;if(!r)return s;return`${s}:${r.shareGroupId??""}:${void 0!==r.shareIndex?String(r.shareIndex):""}`}async check(e,t,r){const s=this.buildKey(e,t,r);return null===await this.kv.get(s)&&(await this.kv.put(s,Date.now().toString(),this.ttlSeconds),!0)}cleanup(){}dispose(){}}export class KVTrustRegistry{kv;constructor(e){this.kv=e}buildKey(e){return`xbind:trust:${e}`}async register(e,t,r,s,n,i,o,c,a,l,u,d,p){const y=this.buildKey(e),h=e=>btoa(String.fromCharCode(...Array.from(e))),m={did:e,publicKey:h(t),name:r,scopes:s??[],x25519PublicKey:n?h(n):void 0,mlKemPublicKey:i?h(i):void 0,mlDsaPublicKey:o?h(o):void 0,xchange:c??!1,receiveScopes:a??[],sdkVersion:l,minEnvelopeVersion:u,maxEnvelopeVersion:d,registeredAt:Date.now(),rotation_sequence:0};try{const e=p?Math.floor(p/1e3):void 0;return await this.kv.put(y,JSON.stringify(m),e),ok(void 0)}catch(e){return err("NETWORK_ERROR")}}async resolve(e){const t=this.buildKey(e);try{const e=await this.kv.get(t);if(null===e)return err("NOT_FOUND");const r=JSON.parse(e);return ok((e=>Uint8Array.from(atob(e),e=>e.charCodeAt(0)))(r.publicKey))}catch(e){return err("NETWORK_ERROR")}}async hasScope(e,t){const r=this.buildKey(e);try{const e=await this.kv.get(r);if(null===e)return!1;const s=JSON.parse(e);return s.scopes?.includes(t)??!1}catch{return!1}}async hasReceiveScope(e,t){const r=this.buildKey(e);try{const e=await this.kv.get(r);if(null===e)return!1;const s=JSON.parse(e);return s.receiveScopes?.includes(t)??!1}catch{return!1}}async revoke(e){const t=this.buildKey(e);try{return await this.kv.delete(t),ok(void 0)}catch(e){return err("NETWORK_ERROR")}}async list(){try{return(await this.kv.list("xbind:trust:",1e3)).map(e=>e.replace("xbind:trust:",""))}catch{return[]}}async getEntry(e){const t=this.buildKey(e);try{const e=await this.kv.get(t);if(null===e)return err("NOT_FOUND");const r=JSON.parse(e),s=e=>Uint8Array.from(atob(e),e=>e.charCodeAt(0)),n={did:r.did,publicKey:s(r.publicKey),name:r.name,scopes:new Set(r.scopes),receiveScopes:r.receiveScopes?new Set(r.receiveScopes):void 0,revoked:!1,x25519PublicKey:r.x25519PublicKey?s(r.x25519PublicKey):void 0,mlKemPublicKey:r.mlKemPublicKey?s(r.mlKemPublicKey):void 0,mlDsaPublicKey:r.mlDsaPublicKey?s(r.mlDsaPublicKey):void 0,xchange:r.xchange,rotation_sequence:r.rotation_sequence,sdkVersion:r.sdkVersion,minEnvelopeVersion:r.minEnvelopeVersion,maxEnvelopeVersion:r.maxEnvelopeVersion};return ok(n)}catch(e){return err("NETWORK_ERROR")}}async getFullEntry(e){const t=this.buildKey(e);try{const e=await this.kv.get(t);if(null===e)return err("NOT_FOUND");const r=JSON.parse(e);return ok(r)}catch(e){return err("NETWORK_ERROR")}}dispose(){}}export class EdgeTransportAdapter{baseUrl;timeoutMs;handlers=[];constructor(e){this.baseUrl=e.baseUrl.replace(/\/$/,""),this.timeoutMs=e.timeoutMs??1e4}async send(e,t){const r=`${this.baseUrl}/deliver/${encodeURIComponent(t)}`;try{const t=new AbortController,s=setTimeout(()=>t.abort(),this.timeoutMs),n=await globalThis.fetch(r,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(e),signal:t.signal});return clearTimeout(s),n.ok?ok(void 0):err(404===n.status?"RECIPIENT_UNREACHABLE":"SEND_FAILED")}catch(e){return e instanceof DOMException&&"AbortError"===e.name?err("TIMEOUT"):err("NETWORK_ERROR")}}onReceive(e){this.handlers.push(e)}dispatch(e){for(const t of this.handlers)t(e)}dispose(){this.handlers=[]}}export function createEdgeAgent(e){return{nonceStore:new KVNonceStore(e.kv,e.nonceTtlMs),trustRegistry:new KVTrustRegistry(e.kv),transport:new EdgeTransportAdapter({baseUrl:e.baseUrl,timeoutMs:e.timeoutMs})}}export function checkBundleSize(e){const t=1048576;if(e>t){const t=(e/1024/1024).toFixed(2),r=1..toFixed(2);return err(`Bundle size ${t}MB exceeds edge runtime limit of ${r}MB. Consider using tree-shaking or dynamic imports.`)}return ok(void 0)}export function getOptimizationTips(){return["1. Use tree-shaking: Import only required functions","2. Enable minification in bundler config","3. Use dynamic imports for large dependencies (mlkem, mldsa)","4. Exclude Node.js polyfills (crypto, fs, process)","5. Use Brotli compression for Cloudflare Workers","6. Consider splitting post-quantum crypto into separate bundle","7. Use KV storage instead of in-memory caches"]}

package/dist-standalone/runtime/react-native.d.ts

@@ -0,0 +1,157 @@
+/**
+ * React Native Runtime Support for xBind
+ *
+ * Provides compatibility layer for React Native environments:
+ * - Polyfills for missing Node.js APIs
+ * - AsyncStorage adapter for persistence
+ * - Native crypto module integration
+ * - Cross-platform crypto primitives
+ *
+ * @module runtime/react-native
+ */
+import type { Result } from '@private.me/shared';
+/**
+ * React Native AsyncStorage interface
+ */
+export interface AsyncStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+    multiGet(keys: string[]): Promise<Array<[string, string | null]>>;
+    multiSet(keyValuePairs: Array<[string, string]>): Promise<void>;
+    multiRemove(keys: string[]): Promise<void>;
+}
+/**
+ * React Native crypto capabilities
+ */
+export interface ReactNativeCrypto {
+    getRandomValues(array: Uint8Array): void;
+    subtle?: {
+        digest(algorithm: string, data: BufferSource): Promise<ArrayBuffer>;
+        encrypt(algorithm: AlgorithmIdentifier, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+        decrypt(algorithm: AlgorithmIdentifier, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+        sign(algorithm: AlgorithmIdentifier, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
+        verify(algorithm: AlgorithmIdentifier, key: CryptoKey, signature: BufferSource, data: BufferSource): Promise<boolean>;
+        generateKey(algorithm: AlgorithmIdentifier, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey | CryptoKeyPair>;
+        importKey(format: KeyFormat, keyData: BufferSource | JsonWebKey, algorithm: AlgorithmIdentifier, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>;
+        exportKey(format: KeyFormat, key: CryptoKey): Promise<ArrayBuffer | JsonWebKey>;
+    };
+}
+/**
+ * React Native runtime configuration
+ */
+export interface ReactNativeConfig {
+    /**
+     * AsyncStorage instance (required for persistence)
+     */
+    storage: AsyncStorage;
+    /**
+     * Crypto implementation (defaults to global.crypto or react-native-quick-crypto)
+     */
+    crypto?: ReactNativeCrypto;
+    /**
+     * Storage key prefix (prevents collisions)
+     */
+    storagePrefix?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * AsyncStorage adapter for xBind persistence
+ *
+ * Provides cross-platform storage for:
+ * - Agent identities (Ed25519/X25519 keys)
+ * - Nonce store (replay protection)
+ * - Trust registry cache
+ * - Connection metadata
+ */
+export declare class AsyncStorageAdapter {
+    private readonly storage;
+    private readonly prefix;
+    private readonly debug;
+    constructor(config: ReactNativeConfig);
+    /**
+     * Get value by key
+     */
+    get(key: string): Promise<Result<string | null, Error>>;
+    /**
+     * Set key-value pair
+     */
+    set(key: string, value: string): Promise<Result<void, Error>>;
+    /**
+     * Remove key
+     */
+    remove(key: string): Promise<Result<void, Error>>;
+    /**
+     * Get all keys with prefix
+     */
+    keys(): Promise<Result<string[], Error>>;
+    /**
+     * Get multiple keys (batch operation)
+     */
+    multiGet(keys: string[]): Promise<Result<Array<[string, string | null]>, Error>>;
+    /**
+     * Set multiple key-value pairs (batch operation)
+     */
+    multiSet(pairs: Array<[string, string]>): Promise<Result<void, Error>>;
+    /**
+     * Clear all xBind data
+     */
+    clear(): Promise<Result<void, Error>>;
+}
+/**
+ * Detect available crypto implementation
+ */
+export declare function detectCrypto(): ReactNativeCrypto | null;
+/**
+ * Get random bytes (cross-platform)
+ */
+export declare function getRandomBytes(length: number, crypto?: ReactNativeCrypto): Uint8Array;
+/**
+ * SHA-256 hash (cross-platform)
+ */
+export declare function sha256(data: Uint8Array, crypto?: ReactNativeCrypto): Promise<Uint8Array>;
+/**
+ * Buffer polyfill for React Native
+ *
+ * Uses global Buffer if available, otherwise provides minimal implementation
+ */
+export declare class BufferPolyfill {
+    static isBuffer(obj: any): boolean;
+    static from(data: string | Uint8Array | number[], encoding?: string): Uint8Array;
+    static toString(buffer: Uint8Array, encoding?: string): string;
+    static concat(buffers: Uint8Array[]): Uint8Array;
+    static alloc(size: number, fill?: number): Uint8Array;
+    private static fromBase64;
+    private static toBase64;
+    private static fromHex;
+    private static toHex;
+}
+/**
+ * Detect React Native runtime
+ */
+export declare function isReactNative(): boolean;
+/**
+ * Detect platform (iOS/Android)
+ */
+export declare function detectPlatform(): 'ios' | 'android' | 'unknown';
+/**
+ * Initialize React Native runtime environment
+ *
+ * Sets up polyfills and validates required dependencies
+ */
+export declare function initializeReactNative(config: ReactNativeConfig): Result<void, Error>;
+declare const _default: {
+    AsyncStorageAdapter: typeof AsyncStorageAdapter;
+    detectCrypto: typeof detectCrypto;
+    getRandomBytes: typeof getRandomBytes;
+    sha256: typeof sha256;
+    BufferPolyfill: typeof BufferPolyfill;
+    isReactNative: typeof isReactNative;
+    detectPlatform: typeof detectPlatform;
+    initializeReactNative: typeof initializeReactNative;
+};
+export default _default;

package/dist-standalone/runtime/react-native.js

@@ -0,0 +1 @@
+import{ok,err}from"../_deps/shared/index.js";export class AsyncStorageAdapter{storage;prefix;debug;constructor(t){this.storage=t.storage,this.prefix=t.storagePrefix||"@xbind:",this.debug=t.debug||!1}async get(t){try{const e=this.prefix+t,r=await this.storage.getItem(e);return this.debug&&console.log(`[AsyncStorage] GET ${e}:`,r?"found":"not found"),ok(r)}catch(t){return err(new Error(`AsyncStorage get failed: ${t}`))}}async set(t,e){try{const r=this.prefix+t;return await this.storage.setItem(r,e),this.debug&&console.log(`[AsyncStorage] SET ${r}:`,e.length,"bytes"),ok(void 0)}catch(t){return err(new Error(`AsyncStorage set failed: ${t}`))}}async remove(t){try{const e=this.prefix+t;return await this.storage.removeItem(e),this.debug&&console.log(`[AsyncStorage] REMOVE ${e}`),ok(void 0)}catch(t){return err(new Error(`AsyncStorage remove failed: ${t}`))}}async keys(){try{const t=(await this.storage.getAllKeys()).filter(t=>t.startsWith(this.prefix)).map(t=>t.substring(this.prefix.length));return this.debug&&console.log("[AsyncStorage] KEYS:",t.length,"items"),ok(t)}catch(t){return err(new Error(`AsyncStorage keys failed: ${t}`))}}async multiGet(t){try{const e=t.map(t=>this.prefix+t),r=(await this.storage.multiGet(e)).map(([t,e])=>[t.substring(this.prefix.length),e]);return this.debug&&console.log("[AsyncStorage] MULTI_GET:",t.length,"keys"),ok(r)}catch(t){return err(new Error(`AsyncStorage multiGet failed: ${t}`))}}async multiSet(t){try{const e=t.map(([t,e])=>[this.prefix+t,e]);return await this.storage.multiSet(e),this.debug&&console.log("[AsyncStorage] MULTI_SET:",t.length,"pairs"),ok(void 0)}catch(t){return err(new Error(`AsyncStorage multiSet failed: ${t}`))}}async clear(){try{const t=await this.keys();if(!t.ok)return err(t.error);const e=t.value.map(t=>this.prefix+t);return e.length>0&&await this.storage.multiRemove(e),this.debug&&console.log("[AsyncStorage] CLEAR:",e.length,"items removed"),ok(void 0)}catch(t){return err(new Error(`AsyncStorage clear failed: ${t}`))}}}export function detectCrypto(){if("undefined"!=typeof global&&global.crypto)return global.crypto;try{return require("react-native-quick-crypto")}catch{}try{const t=require("expo-crypto");return{getRandomValues:e=>{const r=t.getRandomBytes(e.length);e.set(r)}}}catch{}return null}export function getRandomBytes(t,e){const r=e||detectCrypto();if(!r)throw new Error("No crypto implementation available. Install react-native-quick-crypto or expo-crypto.");const o=new Uint8Array(t);return r.getRandomValues(o),o}export async function sha256(t,e){const r=e||detectCrypto();if(!r?.subtle)throw new Error("No SubtleCrypto implementation available. Install react-native-quick-crypto.");const o=new Uint8Array(t).buffer,n=await r.subtle.digest("SHA-256",o);return new Uint8Array(n)}export class BufferPolyfill{static isBuffer(t){return t instanceof Uint8Array}static from(t,e){if("string"==typeof t){if("base64"===e)return this.fromBase64(t);if("hex"===e)return this.fromHex(t);return(new TextEncoder).encode(t)}return Array.isArray(t),new Uint8Array(t)}static toString(t,e){if("base64"===e)return this.toBase64(t);if("hex"===e)return this.toHex(t);return(new TextDecoder).decode(t)}static concat(t){const e=t.reduce((t,e)=>t+e.length,0),r=new Uint8Array(e);let o=0;for(const e of t)r.set(e,o),o+=e.length;return r}static alloc(t,e){const r=new Uint8Array(t);return void 0!==e&&r.fill(e),r}static fromBase64(t){const e=atob(t),r=new Uint8Array(e.length);for(let t=0;t<e.length;t++)r[t]=e.charCodeAt(t);return r}static toBase64(t){let e="";for(let r=0;r<t.length;r++){const o=t[r];void 0!==o&&(e+=String.fromCharCode(o))}return btoa(e)}static fromHex(t){const e=new Uint8Array(t.length/2);for(let r=0;r<e.length;r++)e[r]=parseInt(t.substr(2*r,2),16);return e}static toHex(t){return Array.from(t).map(t=>t.toString(16).padStart(2,"0")).join("")}}export function isReactNative(){return"undefined"!=typeof navigator&&"ReactNative"===navigator.product}export function detectPlatform(){if("undefined"==typeof navigator)return"unknown";const t=navigator.userAgent||"";return/iPhone|iPad|iPod/.test(t)?"ios":/Android/.test(t)?"android":"unknown"}export function initializeReactNative(t){try{if(!t.storage)return err(new Error("AsyncStorage is required for React Native runtime"));const e=t.crypto||detectCrypto();return e?(global.crypto||(global.crypto=e),global.Buffer||(global.Buffer=BufferPolyfill),t.debug&&console.log("[xBind] React Native runtime initialized:",{platform:detectPlatform(),crypto:e.subtle?"full":"basic",storage:"AsyncStorage",prefix:t.storagePrefix||"@xbind:"}),ok(void 0)):err(new Error("No crypto implementation found. Install react-native-quick-crypto or expo-crypto."))}catch(t){return err(new Error(`React Native initialization failed: ${t}`))}}export default{AsyncStorageAdapter:AsyncStorageAdapter,detectCrypto:detectCrypto,getRandomBytes:getRandomBytes,sha256:sha256,BufferPolyfill:BufferPolyfill,isReactNative:isReactNative,detectPlatform:detectPlatform,initializeReactNative:initializeReactNative};

package/dist-standalone/types/error-response.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Error Response Types
+ *
+ * Dual-code error response system supporting both AWS standard codes
+ * and legacy xBind codes for backward compatibility.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Standardized error response structure with dual-code support
+ *
+ * Supports multiple code formats:
+ * - AWS standard codes (primary): InvalidParameterException, UnauthorizedException
+ * - Legacy xBind codes (deprecated): XBIND_INVALID_SIGNATURE, XBIND_AUTH_FAILED
+ * - gRPC status codes: INVALID_ARGUMENT, UNAUTHENTICATED
+ * - HTTP status codes: 400, 401, 403, etc.
+ *
+ * @example
+ * ```typescript
+ * const error: ErrorResponse = {
+ *   code: 'UnauthorizedException',
+ *   legacyCode: 'XBIND_AUTH_FAILED',
+ *   httpStatus: 401,
+ *   grpcCode: 'UNAUTHENTICATED',
+ *   message: 'Invalid signature',
+ *   hint: 'Ensure DID signature is correct',
+ *   docs: 'https://private.me/docs/xbind#authentication',
+ *   requestId: 'req_abc123',
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
+export interface ErrorResponse {
+    /**
+     * AWS standard error code (primary)
+     *
+     * Examples:
+     * - InvalidParameterException
+     * - UnauthorizedException
+     * - ResourceNotFoundException
+     * - InternalServerException
+     * - ServiceUnavailableException
+     * - ThrottlingException
+     *
+     * This is the primary code format. All new integrations should use this.
+     */
+    code: string;
+    /**
+     * Legacy xBind error code (deprecated)
+     *
+     * Examples:
+     * - XBIND_INVALID_SIGNATURE
+     * - XBIND_AUTH_FAILED
+     * - XBIND_DID_NOT_FOUND
+     * - XBIND_RATE_LIMIT
+     *
+     * Provided for backward compatibility only.
+     * Will be removed in future major version.
+     *
+     * @deprecated Use `code` field instead
+     */
+    legacyCode?: string;
+    /**
+     * HTTP status code
+     *
+     * Standard HTTP status codes:
+     * - 400: Bad Request (InvalidParameterException)
+     * - 401: Unauthorized (UnauthorizedException)
+     * - 403: Forbidden (AccessDeniedException)
+     * - 404: Not Found (ResourceNotFoundException)
+     * - 429: Too Many Requests (ThrottlingException)
+     * - 500: Internal Server Error (InternalServerException)
+     * - 503: Service Unavailable (ServiceUnavailableException)
+     */
+    httpStatus: number;
+    /**
+     * gRPC status code (optional)
+     *
+     * Examples:
+     * - INVALID_ARGUMENT
+     * - UNAUTHENTICATED
+     * - PERMISSION_DENIED
+     * - NOT_FOUND
+     * - RESOURCE_EXHAUSTED
+     * - INTERNAL
+     * - UNAVAILABLE
+     *
+     * Provided for gRPC-based integrations.
+     */
+    grpcCode?: string;
+    /**
+     * Human-readable error message
+     *
+     * Should be clear and actionable. Avoid technical jargon where possible.
+     *
+     * Example: "Invalid signature" instead of "ECDSA verification failed"
+     */
+    message: string;
+    /**
+     * Developer hint for resolving the error (optional)
+     *
+     * Provides actionable guidance for fixing the issue.
+     *
+     * Example: "Ensure DID signature is correct and not expired"
+     */
+    hint?: string;
+    /**
+     * Documentation URL for detailed error information (optional)
+     *
+     * Links to relevant documentation section for this error type.
+     *
+     * Example: "https://private.me/docs/xbind#authentication"
+     */
+    docs?: string;
+    /**
+     * Request ID for correlation and debugging (optional)
+     *
+     * Unique identifier for this request. Used for:
+     * - Log correlation across distributed systems
+     * - Customer support troubleshooting
+     * - Audit trail tracking
+     *
+     * Format: "req_" + random alphanumeric (e.g., "req_abc123def456")
+     */
+    requestId?: string;
+    /**
+     * Error timestamp in milliseconds since Unix epoch (optional)
+     *
+     * When the error occurred. Useful for:
+     * - Time-based debugging
+     * - Rate limit tracking
+     * - Audit logs
+     *
+     * Format: Unix timestamp in milliseconds (Date.now())
+     */
+    timestamp?: number;
+    /**
+     * Correlation ID for distributed tracing (optional)
+     *
+     * Tracks a single logical operation across multiple services.
+     * Different from requestId (per-request) - this spans multiple requests.
+     *
+     * Format: UUID or similar distributed trace ID
+     *
+     * Example: "trace_789xyz" spans: Auth request → DID lookup → Billing check
+     */
+    correlationId?: string;
+}
+/**
+ * Error response with additional metadata for internal use
+ *
+ * Extends ErrorResponse with internal fields that should NOT be
+ * exposed to external clients.
+ *
+ * @internal
+ */
+export interface InternalErrorResponse extends ErrorResponse {
+    /**
+     * Stack trace (internal only, never exposed externally)
+     *
+     * @internal
+     */
+    stack?: string;
+    /**
+     * Internal error code for debugging (internal only)
+     *
+     * @internal
+     */
+    internalCode?: string;
+    /**
+     * Service name that generated the error
+     *
+     * @internal
+     */
+    service?: string;
+}
+/**
+ * Type guard to check if a value is an ErrorResponse
+ *
+ * @param value - Value to check
+ * @returns True if value is an ErrorResponse
+ *
+ * @example
+ * ```typescript
+ * if (isErrorResponse(result)) {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export declare function isErrorResponse(value: unknown): value is ErrorResponse;
+/**
+ * Create a standardized error response
+ *
+ * @param params - Error response parameters
+ * @returns Standardized ErrorResponse object
+ *
+ * @example
+ * ```typescript
+ * const error = createErrorResponse({
+ *   code: 'UnauthorizedException',
+ *   legacyCode: 'XBIND_AUTH_FAILED',
+ *   httpStatus: 401,
+ *   message: 'Invalid signature'
+ * });
+ * ```
+ */
+export declare function createErrorResponse(params: Omit<ErrorResponse, 'timestamp'> & {
+    timestamp?: number;
+}): ErrorResponse;

package/dist-standalone/types/error-response.js

@@ -0,0 +1 @@
+export function isErrorResponse(t){if(!t||"object"!=typeof t)return!1;const e=t;return"string"==typeof e.code&&"number"==typeof e.httpStatus&&"string"==typeof e.message}export function createErrorResponse(t){return{...t,timestamp:t.timestamp??Date.now()}}