@private.me/xbind 1.3.0 → 2.3.4

package/dist-standalone/graceful-degradation.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @module graceful-degradation
+ * Enhanced Reliability Capabilities for xBind
+ *
+ * Provides graceful degradation mechanisms to maintain service continuity
+ * when external services (registry, gateway, transport) experience issues.
+ *
+ * Features:
+ * - Quality-of-Service (QoS) tiers for operation prioritization
+ * - Fallback mechanisms with exponential backoff
+ * - Intelligent caching with TTL
+ * - User-friendly error messages with actionable recovery hints
+ */
+import type { Result } from '@private.me/shared';
+import type { ACIErrorDetail } from '@private.me/ux-helpers';
+import type { TrustRegistry } from './trust-registry.js';
+import type { XailTransportAdapter } from './transport.js';
+/**
+ * Quality of Service levels for operations.
+ *
+ * Determines behavior when services are degraded:
+ * - CRITICAL: Must succeed, fail fast if unavailable
+ * - HIGH: Retry with aggressive backoff, use cache if fresh
+ * - NORMAL: Retry with standard backoff, use stale cache if necessary
+ * - LOW: Skip retries, use cache regardless of staleness
+ */
+export type QoSLevel = 'CRITICAL' | 'HIGH' | 'NORMAL' | 'LOW';
+/**
+ * Operation metadata for QoS decisions.
+ */
+export interface OperationContext {
+    /** Unique operation identifier for correlation. */
+    readonly operationId: string;
+    /** Quality of service level. */
+    readonly qos: QoSLevel;
+    /** Operation type (e.g., 'registry:lookup', 'gateway:call', 'transport:send'). */
+    readonly type: string;
+    /** Optional timeout override in milliseconds. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Cache entry with TTL and staleness tracking.
+ */
+interface CacheEntry<T> {
+    /** Cached value. */
+    readonly value: T;
+    /** Timestamp when entry was created (ms since epoch). */
+    readonly cachedAt: number;
+    /** Time-to-live in milliseconds. */
+    readonly ttl: number;
+    /** Number of times this stale entry has been used. */
+    usageCount: number;
+}
+/**
+ * Cache configuration options.
+ */
+export interface CacheConfig {
+    /** Default TTL for cache entries (milliseconds). Default: 300000 (5 minutes). */
+    readonly defaultTTL?: number;
+    /** Maximum cache size (entries). Default: 1000. */
+    readonly maxSize?: number;
+    /** Allow stale cache usage for LOW/NORMAL QoS. Default: true. */
+    readonly allowStale?: boolean;
+    /** Maximum staleness allowed (milliseconds). Default: 3600000 (1 hour). */
+    readonly maxStaleMs?: number;
+}
+/**
+ * Retry configuration for fallback operations.
+ */
+export interface RetryConfig {
+    /** Maximum retry attempts. Default: 3. */
+    readonly maxAttempts?: number;
+    /** Initial delay in milliseconds. Default: 1000. */
+    readonly initialDelayMs?: number;
+    /** Backoff multiplier. Default: 2. */
+    readonly backoffMultiplier?: number;
+    /** Maximum delay in milliseconds. Default: 30000. */
+    readonly maxDelayMs?: number;
+    /** Enable jitter (randomize delays). Default: true. */
+    readonly jitter?: boolean;
+}
+/**
+ * Service health status.
+ */
+type ServiceHealth = 'HEALTHY' | 'DEGRADED' | 'UNAVAILABLE';
+/**
+ * Service health tracking.
+ */
+interface ServiceStatus {
+    /** Current health status. */
+    health: ServiceHealth;
+    /** Last successful operation timestamp. */
+    lastSuccess: number;
+    /** Consecutive failure count. */
+    failureCount: number;
+    /** Last error encountered. */
+    lastError?: string;
+}
+/**
+ * Graceful Degradation Manager
+ *
+ * Coordinates fallback mechanisms, caching, and retry logic across
+ * registry, gateway, and transport layers.
+ */
+export declare class GracefulDegradationManager {
+    private readonly cacheConfig;
+    private readonly retryConfig;
+    private readonly cache;
+    private readonly serviceStatus;
+    constructor(cacheConfig?: CacheConfig, retryConfig?: RetryConfig);
+    /**
+     * Get cached value if available and valid for the given QoS level.
+     *
+     * @param key Cache key
+     * @param qos Quality of service level
+     * @returns Cached value or undefined
+     */
+    getCached<T>(key: string, qos: QoSLevel): T | undefined;
+    /**
+     * Store value in cache with TTL.
+     *
+     * @param key Cache key
+     * @param value Value to cache
+     * @param ttl Time-to-live in milliseconds (uses default if omitted)
+     */
+    setCached<T>(key: string, value: T, ttl?: number): void;
+    /**
+     * Invalidate cached entry.
+     *
+     * @param key Cache key
+     */
+    invalidate(key: string): void;
+    /**
+     * Clear all cached entries.
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        entries: Array<{
+            key: string;
+            age: number;
+            usageCount: number;
+        }>;
+    };
+    /**
+     * Record successful operation for a service.
+     *
+     * @param serviceName Service identifier (e.g., 'registry', 'gateway', 'transport')
+     */
+    recordSuccess(serviceName: string): void;
+    /**
+     * Record failed operation for a service.
+     *
+     * @param serviceName Service identifier
+     * @param error Error message
+     */
+    recordFailure(serviceName: string, error: string): void;
+    /**
+     * Get service health status.
+     *
+     * @param serviceName Service identifier
+     * @returns Service health status
+     */
+    getServiceHealth(serviceName: string): ServiceHealth;
+    /**
+     * Get detailed service status.
+     *
+     * @param serviceName Service identifier
+     * @returns Service status or undefined if not tracked
+     */
+    getServiceStatus(serviceName: string): ServiceStatus | undefined;
+    /**
+     * Reset service health tracking.
+     *
+     * @param serviceName Service identifier (all services if omitted)
+     */
+    resetServiceHealth(serviceName?: string): void;
+    /**
+     * Execute operation with retry logic based on QoS level.
+     *
+     * @param operation Async operation to execute
+     * @param context Operation context with QoS level
+     * @returns Result of operation
+     */
+    withRetry<T, E>(operation: () => Promise<Result<T, E>>, context: OperationContext): Promise<Result<T, E>>;
+    /**
+     * Get maximum retry attempts for QoS level.
+     */
+    private getMaxAttempts;
+    /**
+     * Calculate exponential backoff delay with optional jitter.
+     */
+    private calculateBackoff;
+    /**
+     * Sleep for specified milliseconds.
+     */
+    private sleep;
+}
+/**
+ * Registry lookup with graceful degradation.
+ *
+ * Provides intelligent fallback for DID resolution:
+ * 1. Try primary registry lookup
+ * 2. On failure, check cache based on QoS level
+ * 3. Return user-friendly error if all fallbacks exhausted
+ *
+ * @param registry Trust registry instance
+ * @param did DID to resolve
+ * @param context Operation context
+ * @param manager Degradation manager
+ * @returns Registry lookup result
+ */
+export declare function registryLookupWithFallback(registry: TrustRegistry, did: string, context: OperationContext, manager: GracefulDegradationManager): Promise<Result<{
+    publicKey: string;
+    endpoint?: string;
+}, ACIErrorDetail>>;
+/**
+ * Send envelope with transport fallback.
+ *
+ * Tries multiple transports in order until one succeeds:
+ * 1. Primary transport with retry
+ * 2. Fallback transports (if configured)
+ * 3. Return detailed error if all transports fail
+ *
+ * @param transports Array of transport adapters
+ * @param envelope Envelope to send
+ * @param recipientDid Recipient DID
+ * @param context Operation context
+ * @param manager Degradation manager
+ * @returns Send result
+ */
+export declare function sendWithTransportFallback(transports: XailTransportAdapter[], envelope: unknown, recipientDid: string, context: OperationContext, manager: GracefulDegradationManager): Promise<Result<void, ACIErrorDetail>>;
+/**
+ * Enhance error with QoS-appropriate messaging.
+ *
+ * @param error Original error
+ * @param context Operation context
+ * @param manager Degradation manager
+ * @returns Enhanced error with actionable hints
+ */
+export declare function enhanceError(error: ACIErrorDetail, context: OperationContext, manager: GracefulDegradationManager): ACIErrorDetail;
+export type { CacheEntry, ServiceStatus };

package/dist-standalone/graceful-degradation.js

@@ -0,0 +1 @@
+import{ok,err}from"./_deps/shared/index.js";import{createDetailedError}from"./_deps/ux-helpers/index.js";const DEFAULT_CACHE_CONFIG={defaultTTL:3e5,maxSize:1e3,allowStale:!0,maxStaleMs:36e5},DEFAULT_RETRY_CONFIG={maxAttempts:3,initialDelayMs:1e3,backoffMultiplier:2,maxDelayMs:3e4,jitter:!0};export class GracefulDegradationManager{cacheConfig;retryConfig;cache=new Map;serviceStatus=new Map;constructor(e,t){this.cacheConfig={...DEFAULT_CACHE_CONFIG,...e},this.retryConfig={...DEFAULT_RETRY_CONFIG,...t}}getCached(e,t){const r=this.cache.get(e);if(!r)return;const a=Date.now()-r.cachedAt,i=a<=r.ttl,s=a>r.ttl&&a<=this.cacheConfig.maxStaleMs;return"CRITICAL"===t||"HIGH"===t?i?r.value:void 0:this.cacheConfig.allowStale&&(i||s)?(r.usageCount++,r.value):i?r.value:void 0}setCached(e,t,r){if(this.cache.size>=this.cacheConfig.maxSize){const e=this.cache.keys().next().value;e&&this.cache.delete(e)}this.cache.set(e,{value:t,cachedAt:Date.now(),ttl:r??this.cacheConfig.defaultTTL,usageCount:0})}invalidate(e){this.cache.delete(e)}clearCache(){this.cache.clear()}getCacheStats(){const e=Date.now(),t=Array.from(this.cache.entries()).map(([t,r])=>({key:t,age:e-r.cachedAt,usageCount:r.usageCount}));return{size:this.cache.size,maxSize:this.cacheConfig.maxSize,entries:t}}recordSuccess(e){const t=this.serviceStatus.get(e)||{health:"HEALTHY",lastSuccess:0,failureCount:0};t.health="HEALTHY",t.lastSuccess=Date.now(),t.failureCount=0,t.lastError=void 0,this.serviceStatus.set(e,t)}recordFailure(e,t){const r=this.serviceStatus.get(e)||{health:"HEALTHY",lastSuccess:0,failureCount:0};r.failureCount++,r.lastError=t,r.failureCount>=5?r.health="UNAVAILABLE":r.failureCount>=2&&(r.health="DEGRADED"),this.serviceStatus.set(e,r)}getServiceHealth(e){return this.serviceStatus.get(e)?.health??"HEALTHY"}getServiceStatus(e){return this.serviceStatus.get(e)}resetServiceHealth(e){e?this.serviceStatus.delete(e):this.serviceStatus.clear()}async withRetry(e,t){const r=this.getMaxAttempts(t.qos);let a;for(let t=1;t<=r;t++){const i=await e();if(i.ok)return i;if(a=i.error,t<r){const e=this.calculateBackoff(t);await this.sleep(e)}}return err(a)}getMaxAttempts(e){switch(e){case"CRITICAL":case"LOW":return 1;case"HIGH":return this.retryConfig.maxAttempts;case"NORMAL":return Math.max(1,this.retryConfig.maxAttempts-1)}}calculateBackoff(e){const t=this.retryConfig.initialDelayMs*Math.pow(this.retryConfig.backoffMultiplier,e-1),r=Math.min(t,this.retryConfig.maxDelayMs);if(!this.retryConfig.jitter)return r;const a=new Uint8Array(4);crypto.getRandomValues(a);const i=.75+.5*(new DataView(a.buffer).getUint32(0)/4294967295);return Math.floor(r*i)}sleep(e){return new Promise(t=>setTimeout(t,e))}}export async function registryLookupWithFallback(e,t,r,a){const i=`registry:${t}`;if("LOW"===r.qos){const e=a.getCached(i,r.qos);if(e)return ok(e)}const s=await a.withRetry(()=>e.getEntry(t),r);if(s.ok){a.recordSuccess("registry");const e={publicKey:Buffer.from(s.value.publicKey).toString("base64")};return a.setCached(i,e),ok(e)}if(a.recordFailure("registry",String(s.error)),"HIGH"===r.qos||"NORMAL"===r.qos){const e=a.getCached(i,r.qos);if(e)return ok(e)}return err(createDetailedError("REGISTRY_UNAVAILABLE",`Failed to resolve DID: ${t}`,{hint:"UNAVAILABLE"===a.getServiceHealth("registry")?"Registry service is currently unavailable. Using cached data may help.":"Registry lookup failed after retries. Check network connectivity.",suggested_action:"CRITICAL"===r.qos?"Wait for registry service to recover before retrying critical operations.":"Lower QoS level to NORMAL or LOW to use cached data.",docs:"https://private.me/docs/xbind/registry-fallback",severity:"CRITICAL"===r.qos?"critical":"error"}))}export async function sendWithTransportFallback(e,t,r,a,i){if(0===e.length)return err(createDetailedError("NO_TRANSPORT","No transport adapters configured",{hint:"Configure at least one transport adapter for envelope delivery.",suggested_action:"Add HttpsTransportAdapter or custom transport to agent configuration.",docs:"https://private.me/docs/xbind/transport",severity:"critical"}));const s=[];for(let o=0;o<e.length;o++){const c=e[o];if(!c)continue;const n=await i.withRetry(()=>c.send(t,r),a);if(n.ok)return i.recordSuccess(`transport:${o}`),ok(void 0);s.push({transport:o,error:n.error}),i.recordFailure(`transport:${o}`,n.error)}const o=s[0]?.error??"SEND_FAILED";return err(createDetailedError("TRANSPORT_EXHAUSTED",`All transport adapters failed: ${s.map(e=>e.error).join(", ")}`,{hint:"NETWORK_ERROR"===o?"Network connectivity issue detected. Check internet connection.":"TIMEOUT"===o?"Transport timeout occurred. Recipient may be unreachable or overloaded.":"RECIPIENT_UNREACHABLE"===o?"Recipient DID not found or offline.":"Transport layer failure. Check transport configuration.",suggested_action:"Verify recipient endpoint and network connectivity. Consider increasing timeout or adding fallback transports.",docs:"https://private.me/docs/xbind/transport-fallback",severity:"CRITICAL"===a.qos?"critical":"error"}))}export function enhanceError(e,t,r){const a=r.getServiceHealth(t.type.split(":")[0]??"unknown"),i="DEGRADED"===a?" Service is experiencing degraded performance.":"UNAVAILABLE"===a?" Service is currently unavailable.":"",s="CRITICAL"===t.qos?" Consider retrying when service recovers.":"HIGH"===t.qos?" Cached data may be used if available.":" Using cached data regardless of staleness.";return{...e,hint:(e.hint??"")+i+s}}

package/dist-standalone/guardrails.js

@@ -1,216 +1 @@
-/**
- * @module guardrails
- * Enhanced error messages with actionable suggestions for policy violations
- *
- * When policies deny requests, guardrails provide specific, actionable
- * guidance on how to fix the issue or what to request from admins.
- */
-/**
- * Policy violation error with actionable suggestions
- */
-export class PolicyDenied extends Error {
-    rule;
-    allowed;
-    requested;
-    suggestion;
-    details;
-    constructor(
-    /** Which policy rule was violated */
-    rule, 
-    /** What the policy allows */
-    allowed, 
-    /** What was requested */
-    requested, 
-    /** Actionable suggestion for how to fix */
-    suggestion, 
-    /** Full policy violation details */
-    details) {
-        super(`Policy violation: ${rule}`);
-        this.rule = rule;
-        this.allowed = allowed;
-        this.requested = requested;
-        this.suggestion = suggestion;
-        this.details = details;
-        this.name = 'PolicyDenied';
-    }
-    /**
-     * Format error for AI agent consumption
-     *
-     * Structured format optimized for LLM parsing
-     */
-    toAgentFormat() {
-        return [
-            `POLICY_VIOLATION: ${this.rule}`,
-            `REQUESTED: ${JSON.stringify(this.requested)}`,
-            `ALLOWED: ${JSON.stringify(this.allowed)}`,
-            `SUGGESTION: ${this.suggestion}`,
-        ].join('\n');
-    }
-    /**
-     * Format error for human consumption
-     *
-     * User-friendly format with clear next steps
-     */
-    toUserFormat() {
-        return [
-            `❌ Policy Violation: ${this.rule}`,
-            '',
-            `You requested: ${this.formatValue(this.requested)}`,
-            `Policy allows: ${this.formatValue(this.allowed)}`,
-            '',
-            `💡 Suggestion: ${this.suggestion}`,
-        ].join('\n');
-    }
-    /**
-     * Format error for logs (structured JSON)
-     */
-    toLogFormat() {
-        return {
-            error: 'PolicyDenied',
-            rule: this.rule,
-            allowed: this.allowed,
-            requested: this.requested,
-            suggestion: this.suggestion,
-            details: this.details,
-            timestamp: new Date().toISOString(),
-        };
-    }
-    formatValue(value) {
-        if (typeof value === 'number') {
-            // Format currency if it looks like money
-            if (this.rule.includes('amount') || this.rule.includes('Amount')) {
-                return `$${value.toLocaleString()}`;
-            }
-            return value.toLocaleString();
-        }
-        if (Array.isArray(value)) {
-            return value.map((v) => `"${String(v)}"`).join(', ');
-        }
-        return JSON.stringify(value);
-    }
-}
-/**
- * Guardrail builder - fluent API for creating policy errors with suggestions
- *
- * @example
- * ```typescript
- * const error = Guardrails.amountExceeded({
- *   requested: 5000,
- *   limit: 1000,
- *   type: 'per-transaction'
- * });
- *
- * throw error;
- * // ❌ Policy Violation: maxAmount
- * // You requested: $5,000
- * // Policy allows: $1,000
- * // 💡 Suggestion: Reduce amount to $1,000 or request policy update from admin
- * ```
- */
-export class Guardrails {
-    /**
-     * Amount exceeded (per-transaction limit)
-     */
-    static amountExceeded(options) {
-        let rule;
-        let suggestion;
-        switch (options.type) {
-            case 'per-transaction':
-                rule = 'maxAmount';
-                suggestion = `Reduce amount to $${options.limit.toLocaleString()} or request policy update from admin`;
-                break;
-            case 'daily':
-                rule = 'dailyAmount';
-                suggestion = `Reduce amount to stay within daily limit of $${options.limit.toLocaleString()}, or wait until tomorrow`;
-                break;
-            case 'monthly':
-                rule = 'monthlyAmount';
-                suggestion = `Reduce amount to stay within monthly limit of $${options.limit.toLocaleString()}, or wait until next month`;
-                break;
-        }
-        return new PolicyDenied(rule, options.limit, options.requested, suggestion);
-    }
-    /**
-     * Rate limit exceeded
-     */
-    static rateLimitExceeded(options) {
-        const windowSec = options.windowMs / 1000;
-        const suggestion = windowSec >= 60
-            ? `Wait ${Math.ceil(windowSec / 60)} minutes before making additional calls`
-            : `Wait ${windowSec} seconds before making additional calls`;
-        return new PolicyDenied('callsPerMinute', options.limit, options.current + 1, suggestion);
-    }
-    /**
-     * Tool not allowed
-     */
-    static toolDenied(options) {
-        const [service] = options.tool.split(':');
-        const suggestion = options.allowed.length === 0
-            ? `No tools are currently allowed. Request approval from admin to enable "${options.tool}"`
-            : `Request approval from admin to add "${options.tool}" or "${service}:*" to allowed tools`;
-        return new PolicyDenied('allowedTools', options.allowed, options.tool, suggestion);
-    }
-    /**
-     * Scope not allowed
-     */
-    static scopeDenied(options) {
-        const suggestion = options.allowed.length === 0
-            ? `No scopes are currently allowed. Request approval from admin to enable "${options.scope}"`
-            : `Request approval from admin to add "${options.scope}" to allowed scopes`;
-        return new PolicyDenied('allowedScopes', options.allowed, options.scope, suggestion);
-    }
-    /**
-     * Field filter denied (data access restriction)
-     */
-    static fieldDenied(options) {
-        const suggestion = `Field "${options.field}" is restricted. Contact admin to update policy.fieldFilters for "${options.tool}"`;
-        return new PolicyDenied('fieldFilters', options.allowed, options.field, suggestion);
-    }
-    /**
-     * Time window restriction
-     */
-    static timeWindowDenied(options) {
-        const suggestion = `Actions are only allowed between ${options.allowedStart} and ${options.allowedEnd}. Current time is ${options.current.toTimeString()}`;
-        return new PolicyDenied('timeWindow', `${options.allowedStart} - ${options.allowedEnd}`, options.current.toTimeString(), suggestion);
-    }
-    /**
-     * Generic policy violation
-     */
-    static custom(options) {
-        return new PolicyDenied(options.rule, options.allowed, options.requested, options.suggestion);
-    }
-}
-/**
- * Helper: Extract actionable suggestion from AgentError details
- *
- * Used by agent.call() to convert PolicyViolationDetails into PolicyDenied
- */
-export function extractSuggestion(details) {
-    return details.fix ?? 'Contact administrator to update policy';
-}
-/**
- * Helper: Convert PolicyViolationDetails to PolicyDenied
- */
-export function toPolicyDenied(details) {
-    let rule;
-    switch (details.constraint) {
-        case 'amountPerTxn':
-            rule = 'maxAmount';
-            break;
-        case 'dailyAmount':
-            rule = 'dailyAmount';
-            break;
-        case 'callsPerMinute':
-            rule = 'callsPerMinute';
-            break;
-        case 'scope':
-            rule = 'allowedScopes';
-            break;
-        case 'tool':
-            rule = 'allowedTools';
-            break;
-        default:
-            rule = String(details.constraint);
-    }
-    return new PolicyDenied(rule, details.allowed, details.requested, details.fix, details);
-}
+export class PolicyDenied extends Error{rule;allowed;requested;suggestion;details;constructor(e,t,o,i,l){super(`Policy violation: ${e}`),this.rule=e,this.allowed=t,this.requested=o,this.suggestion=i,this.details=l,this.name="PolicyDenied"}toAgentFormat(){return[`POLICY_VIOLATION: ${this.rule}`,`REQUESTED: ${JSON.stringify(this.requested)}`,`ALLOWED: ${JSON.stringify(this.allowed)}`,`SUGGESTION: ${this.suggestion}`].join("\n")}toUserFormat(){return[`❌ Policy Violation: ${this.rule}`,"",`You requested: ${this.formatValue(this.requested)}`,`Policy allows: ${this.formatValue(this.allowed)}`,"",`💡 Suggestion: ${this.suggestion}`].join("\n")}toLogFormat(){return{error:"PolicyDenied",rule:this.rule,allowed:this.allowed,requested:this.requested,suggestion:this.suggestion,details:this.details,timestamp:(new Date).toISOString()}}formatValue(e){return"number"==typeof e?this.rule.includes("amount")||this.rule.includes("Amount")?`$${e.toLocaleString()}`:e.toLocaleString():Array.isArray(e)?e.map(e=>`"${String(e)}"`).join(", "):JSON.stringify(e)}}export class Guardrails{static amountExceeded(e){let t,o;switch(e.type){case"per-transaction":t="maxAmount",o=`Reduce amount to $${e.limit.toLocaleString()} or request policy update from admin`;break;case"daily":t="dailyAmount",o=`Reduce amount to stay within daily limit of $${e.limit.toLocaleString()}, or wait until tomorrow`;break;case"monthly":t="monthlyAmount",o=`Reduce amount to stay within monthly limit of $${e.limit.toLocaleString()}, or wait until next month`}return new PolicyDenied(t,e.limit,e.requested,o)}static rateLimitExceeded(e){const t=e.windowMs/1e3,o=t>=60?`Wait ${Math.ceil(t/60)} minutes before making additional calls`:`Wait ${t} seconds before making additional calls`;return new PolicyDenied("callsPerMinute",e.limit,e.current+1,o)}static toolDenied(e){const[t]=e.tool.split(":"),o=0===e.allowed.length?`No tools are currently allowed. Request approval from admin to enable "${e.tool}"`:`Request approval from admin to add "${e.tool}" or "${t}:*" to allowed tools`;return new PolicyDenied("allowedTools",e.allowed,e.tool,o)}static scopeDenied(e){const t=0===e.allowed.length?`No scopes are currently allowed. Request approval from admin to enable "${e.scope}"`:`Request approval from admin to add "${e.scope}" to allowed scopes`;return new PolicyDenied("allowedScopes",e.allowed,e.scope,t)}static fieldDenied(e){const t=`Field "${e.field}" is restricted. Contact admin to update policy.fieldFilters for "${e.tool}"`;return new PolicyDenied("fieldFilters",e.allowed,e.field,t)}static timeWindowDenied(e){const t=`Actions are only allowed between ${e.allowedStart} and ${e.allowedEnd}. Current time is ${e.current.toTimeString()}`;return new PolicyDenied("timeWindow",`${e.allowedStart} - ${e.allowedEnd}`,e.current.toTimeString(),t)}static custom(e){return new PolicyDenied(e.rule,e.allowed,e.requested,e.suggestion)}}export function extractSuggestion(e){return e.fix??"Contact administrator to update policy"}export function toPolicyDenied(e){let t;switch(e.constraint){case"amountPerTxn":t="maxAmount";break;case"dailyAmount":t="dailyAmount";break;case"callsPerMinute":t="callsPerMinute";break;case"scope":t="allowedScopes";break;case"tool":t="allowedTools";break;default:t=String(e.constraint)}return new PolicyDenied(t,e.allowed,e.requested,e.fix,e)}

package/dist-standalone/health-check.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @module health-check
+ * Health check endpoint for operational monitoring and load balancer probes.
+ *
+ * Provides three probe types following Kubernetes health check patterns:
+ * - **Startup probe**: Verify initialization complete (one-time check)
+ * - **Readiness probe**: Verify dependencies ready (registry, transport)
+ * - **Liveness probe**: Verify service responsive (self-check)
+ *
+ * @example
+ * ```typescript
+ * import { createHealthChecker } from '@private.me/xbind';
+ *
+ * const checker = createHealthChecker({
+ *   registry: myTrustRegistry,
+ *   transport: myTransport
+ * });
+ *
+ * // Load balancer endpoint
+ * app.get('/health', async (req, res) => {
+ *   const status = await checker.check();
+ *   res.status(status.healthy ? 200 : 503).json(status);
+ * });
+ * ```
+ */
+import type { TrustRegistry } from './trust-registry.js';
+import type { XailTransportAdapter } from './transport.js';
+/**
+ * Health check probe type.
+ */
+export type ProbeType = 'startup' | 'readiness' | 'liveness';
+/**
+ * Health status for individual component.
+ */
+export interface ComponentHealth {
+    /** Component name (e.g., 'registry', 'transport') */
+    readonly name: string;
+    /** Component status: 'healthy', 'degraded', 'unhealthy' */
+    readonly status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Human-readable status message */
+    readonly message?: string;
+    /** Response time in milliseconds */
+    readonly latencyMs?: number;
+    /** Last check timestamp (ISO 8601) */
+    readonly lastCheck: string;
+}
+/**
+ * Overall health check result.
+ */
+export interface HealthStatus {
+    /** Overall health: true if all components healthy, false otherwise */
+    readonly healthy: boolean;
+    /** Timestamp of health check (ISO 8601) */
+    readonly timestamp: string;
+    /** Uptime in seconds since checker created */
+    readonly uptimeSeconds: number;
+    /** Individual component health statuses */
+    readonly components: ComponentHealth[];
+    /** Additional metadata */
+    readonly metadata?: {
+        /** Service name */
+        readonly service?: string;
+        /** Service version */
+        readonly version?: string;
+        /** Environment (development, staging, production) */
+        readonly environment?: string;
+    };
+}
+/**
+ * Configuration for health checker.
+ */
+export interface HealthCheckerOptions {
+    /** Trust registry to check (optional) */
+    readonly registry?: TrustRegistry;
+    /** Transport adapter to check (optional) */
+    readonly transport?: XailTransportAdapter;
+    /** Service name for metadata */
+    readonly serviceName?: string;
+    /** Service version for metadata */
+    readonly version?: string;
+    /** Environment name for metadata */
+    readonly environment?: string;
+    /** Timeout for component checks in milliseconds (default: 5000) */
+    readonly timeoutMs?: number;
+    /** Enable startup probe tracking (default: true) */
+    readonly enableStartupProbe?: boolean;
+}
+/**
+ * Health checker instance.
+ */
+export interface HealthChecker {
+    /**
+     * Perform health check on all configured components.
+     * @param probe - Probe type (defaults to 'readiness')
+     */
+    check(probe?: ProbeType): Promise<HealthStatus>;
+    /**
+     * Mark startup probe as complete.
+     * Call after initialization finishes (e.g., after agent.register()).
+     */
+    markStartupComplete(): void;
+    /**
+     * Check if startup probe is complete.
+     */
+    isStartupComplete(): boolean;
+}
+/**
+ * Create a health checker instance.
+ *
+ * @param options - Configuration options
+ * @returns Health checker instance
+ *
+ * @example
+ * ```typescript
+ * const checker = createHealthChecker({
+ *   registry: agent.registry,
+ *   transport: agent.transport,
+ *   serviceName: 'my-service',
+ *   version: '1.0.0'
+ * });
+ *
+ * // Mark startup complete after initialization
+ * await agent.register();
+ * checker.markStartupComplete();
+ *
+ * // Check health
+ * const status = await checker.check('readiness');
+ * console.log(status.healthy ? 'Ready' : 'Not ready');
+ * ```
+ */
+export declare function createHealthChecker(options?: HealthCheckerOptions): HealthChecker;
+/**
+ * Express/Fastify middleware helper for health endpoint.
+ *
+ * @param checker - Health checker instance
+ * @param probe - Probe type (default: 'readiness')
+ * @returns Request handler
+ *
+ * @example
+ * ```typescript
+ * const checker = createHealthChecker({ registry, transport });
+ *
+ * // Express
+ * app.get('/health', healthEndpoint(checker));
+ * app.get('/health/startup', healthEndpoint(checker, 'startup'));
+ * app.get('/health/liveness', healthEndpoint(checker, 'liveness'));
+ * app.get('/health/readiness', healthEndpoint(checker, 'readiness'));
+ * ```
+ */
+export declare function healthEndpoint(checker: HealthChecker, probe?: ProbeType): (req: any, res: any) => Promise<void>;

package/dist-standalone/health-check.js

@@ -0,0 +1 @@
+class HealthCheckerImpl{startTime;registry;transport;serviceName;version;environment;timeoutMs;enableStartupProbe;startupComplete=!1;constructor(t={}){this.startTime=Date.now(),this.registry=t.registry,this.transport=t.transport,this.serviceName=t.serviceName,this.version=t.version,this.environment=t.environment,this.timeoutMs=t.timeoutMs??5e3,this.enableStartupProbe=t.enableStartupProbe??!0}markStartupComplete(){this.startupComplete=!0}isStartupComplete(){return this.startupComplete}async check(t="readiness"){const e=(new Date).toISOString(),s=Math.floor((Date.now()-this.startTime)/1e3);if("startup"===t&&this.enableStartupProbe){const t=[{name:"startup",status:this.startupComplete?"healthy":"unhealthy",message:this.startupComplete?"Initialization complete":"Waiting for startup completion (call markStartupComplete())",lastCheck:e}];return{healthy:this.startupComplete,timestamp:e,uptimeSeconds:s,components:t,metadata:this.buildMetadata()}}if("liveness"===t){return{healthy:!0,timestamp:e,uptimeSeconds:s,components:[{name:"self",status:"healthy",message:"Service responsive",lastCheck:e}],metadata:this.buildMetadata()}}const a=[];if(this.registry){const t=await this.checkRegistry();a.push(t)}if(this.transport){const t=await this.checkTransport();a.push(t)}0===a.length&&a.push({name:"self",status:"healthy",message:"No dependencies configured",lastCheck:e});return{healthy:a.every(t=>"healthy"===t.status),timestamp:e,uptimeSeconds:s,components:a,metadata:this.buildMetadata()}}buildMetadata(){const t={};return this.serviceName&&(t.service=this.serviceName),this.version&&(t.version=this.version),this.environment&&(t.environment=this.environment),Object.keys(t).length>0?t:void 0}async checkRegistry(){const t=Date.now(),e=(new Date).toISOString();try{if(!this.registry)return{name:"registry",status:"unhealthy",message:"Registry not configured",lastCheck:e};const s=await this.withTimeout(this.registry.resolve("did:xail:health_check_probe"),this.timeoutMs),a=Date.now()-t;if(s&&"object"==typeof s&&"ok"in s){if(s.ok)return{name:"registry",status:"healthy",message:"Registry responding",latencyMs:a,lastCheck:e};{const t="string"==typeof s.error?s.error:"UNKNOWN";return t.includes("NOT_FOUND")?{name:"registry",status:"healthy",message:"Registry responding",latencyMs:a,lastCheck:e}:{name:"registry",status:"unhealthy",message:`Registry error: ${t}`,latencyMs:a,lastCheck:e}}}return{name:"registry",status:"healthy",message:"Registry responding",latencyMs:a,lastCheck:e}}catch(s){const a=Date.now()-t,r=s instanceof Error?s.message:"Unknown error";return r.toLowerCase().includes("timeout")?{name:"registry",status:"degraded",message:`Registry slow (>${this.timeoutMs}ms)`,latencyMs:a,lastCheck:e}:{name:"registry",status:"unhealthy",message:`Registry error: ${r}`,latencyMs:a,lastCheck:e}}}async checkTransport(){const t=Date.now(),e=(new Date).toISOString();try{if(!this.transport)return{name:"transport",status:"unhealthy",message:"Transport not configured",lastCheck:e};return{name:"transport",status:"healthy",message:"Transport adapter available",latencyMs:Date.now()-t,lastCheck:e}}catch(s){const a=Date.now()-t;return{name:"transport",status:"unhealthy",message:`Transport error: ${s instanceof Error?s.message:"Unknown error"}`,latencyMs:a,lastCheck:e}}}async withTimeout(t,e){return Promise.race([t,new Promise((t,s)=>setTimeout(()=>s(new Error("Health check timeout")),e))])}}export function createHealthChecker(t){return new HealthCheckerImpl(t)}export function healthEndpoint(t,e="readiness"){return async(s,a)=>{try{const s=await t.check(e),r=s.healthy?200:503;a.status(r).json(s)}catch(t){const e=t instanceof Error?t.message:"Unknown error";a.status(503).json({healthy:!1,timestamp:(new Date).toISOString(),uptimeSeconds:0,components:[{name:"health-check",status:"unhealthy",message:`Health check failed: ${e}`,lastCheck:(new Date).toISOString()}]})}}}