@private.me/xbind 3.0.2 → 3.0.3

package/dist-standalone/cjs/graceful-degradation.js

@@ -1,403 +1 @@
-"use strict";
-/**
- * @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
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GracefulDegradationManager = void 0;
-exports.registryLookupWithFallback = registryLookupWithFallback;
-exports.sendWithTransportFallback = sendWithTransportFallback;
-exports.enhanceError = enhanceError;
-const shared_1 = require("../_deps/shared/index.js");
-const ux_helpers_1 = require("../_deps/ux-helpers/index.js");
-const DEFAULT_CACHE_CONFIG = {
-    defaultTTL: 300_000, // 5 minutes
-    maxSize: 1000,
-    allowStale: true,
-    maxStaleMs: 3600_000, // 1 hour
-};
-const DEFAULT_RETRY_CONFIG = {
-    maxAttempts: 3,
-    initialDelayMs: 1000,
-    backoffMultiplier: 2,
-    maxDelayMs: 30_000,
-    jitter: true,
-};
-/**
- * Graceful Degradation Manager
- *
- * Coordinates fallback mechanisms, caching, and retry logic across
- * registry, gateway, and transport layers.
- */
-class GracefulDegradationManager {
-    cacheConfig;
-    retryConfig;
-    cache = new Map();
-    serviceStatus = new Map();
-    constructor(cacheConfig, retryConfig) {
-        this.cacheConfig = { ...DEFAULT_CACHE_CONFIG, ...cacheConfig };
-        this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...retryConfig };
-    }
-    /* ── Cache Operations ── */
-    /**
-     * 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(key, qos) {
-        const entry = this.cache.get(key);
-        if (!entry)
-            return undefined;
-        const now = Date.now();
-        const age = now - entry.cachedAt;
-        const isFresh = age <= entry.ttl;
-        const isStale = age > entry.ttl && age <= this.cacheConfig.maxStaleMs;
-        // CRITICAL/HIGH: Only use fresh cache
-        if (qos === 'CRITICAL' || qos === 'HIGH') {
-            return isFresh ? entry.value : undefined;
-        }
-        // NORMAL/LOW: Use stale cache if allowed
-        if (this.cacheConfig.allowStale && (isFresh || isStale)) {
-            entry.usageCount++;
-            return entry.value;
-        }
-        return isFresh ? entry.value : 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(key, value, ttl) {
-        // Evict oldest entry if cache is full
-        if (this.cache.size >= this.cacheConfig.maxSize) {
-            const oldestKey = this.cache.keys().next().value;
-            if (oldestKey)
-                this.cache.delete(oldestKey);
-        }
-        this.cache.set(key, {
-            value,
-            cachedAt: Date.now(),
-            ttl: ttl ?? this.cacheConfig.defaultTTL,
-            usageCount: 0,
-        });
-    }
-    /**
-     * Invalidate cached entry.
-     *
-     * @param key Cache key
-     */
-    invalidate(key) {
-        this.cache.delete(key);
-    }
-    /**
-     * Clear all cached entries.
-     */
-    clearCache() {
-        this.cache.clear();
-    }
-    /**
-     * Get cache statistics.
-     */
-    getCacheStats() {
-        const now = Date.now();
-        const entries = Array.from(this.cache.entries()).map(([key, entry]) => ({
-            key,
-            age: now - entry.cachedAt,
-            usageCount: entry.usageCount,
-        }));
-        return {
-            size: this.cache.size,
-            maxSize: this.cacheConfig.maxSize,
-            entries,
-        };
-    }
-    /* ── Service Health Tracking ── */
-    /**
-     * Record successful operation for a service.
-     *
-     * @param serviceName Service identifier (e.g., 'registry', 'gateway', 'transport')
-     */
-    recordSuccess(serviceName) {
-        const existing = this.serviceStatus.get(serviceName);
-        const status = existing || {
-            health: 'HEALTHY',
-            lastSuccess: 0,
-            failureCount: 0,
-        };
-        status.health = 'HEALTHY';
-        status.lastSuccess = Date.now();
-        status.failureCount = 0;
-        status.lastError = undefined;
-        this.serviceStatus.set(serviceName, status);
-    }
-    /**
-     * Record failed operation for a service.
-     *
-     * @param serviceName Service identifier
-     * @param error Error message
-     */
-    recordFailure(serviceName, error) {
-        const existing = this.serviceStatus.get(serviceName);
-        const status = existing || {
-            health: 'HEALTHY',
-            lastSuccess: 0,
-            failureCount: 0,
-        };
-        status.failureCount++;
-        status.lastError = error;
-        // Update health based on consecutive failures
-        if (status.failureCount >= 5) {
-            status.health = 'UNAVAILABLE';
-        }
-        else if (status.failureCount >= 2) {
-            status.health = 'DEGRADED';
-        }
-        this.serviceStatus.set(serviceName, status);
-    }
-    /**
-     * Get service health status.
-     *
-     * @param serviceName Service identifier
-     * @returns Service health status
-     */
-    getServiceHealth(serviceName) {
-        return this.serviceStatus.get(serviceName)?.health ?? 'HEALTHY';
-    }
-    /**
-     * Get detailed service status.
-     *
-     * @param serviceName Service identifier
-     * @returns Service status or undefined if not tracked
-     */
-    getServiceStatus(serviceName) {
-        return this.serviceStatus.get(serviceName);
-    }
-    /**
-     * Reset service health tracking.
-     *
-     * @param serviceName Service identifier (all services if omitted)
-     */
-    resetServiceHealth(serviceName) {
-        if (serviceName) {
-            this.serviceStatus.delete(serviceName);
-        }
-        else {
-            this.serviceStatus.clear();
-        }
-    }
-    /* ── Retry Logic ── */
-    /**
-     * 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
-     */
-    async withRetry(operation, context) {
-        const maxAttempts = this.getMaxAttempts(context.qos);
-        let lastError;
-        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-            const result = await operation();
-            if (result.ok) {
-                return result;
-            }
-            lastError = result.error;
-            // Don't retry on last attempt
-            if (attempt < maxAttempts) {
-                const delay = this.calculateBackoff(attempt);
-                await this.sleep(delay);
-            }
-        }
-        // All retries exhausted
-        return (0, shared_1.err)(lastError);
-    }
-    /**
-     * Get maximum retry attempts for QoS level.
-     */
-    getMaxAttempts(qos) {
-        switch (qos) {
-            case 'CRITICAL':
-                return 1; // Fail fast
-            case 'HIGH':
-                return this.retryConfig.maxAttempts;
-            case 'NORMAL':
-                return Math.max(1, this.retryConfig.maxAttempts - 1);
-            case 'LOW':
-                return 1; // No retries
-        }
-    }
-    /**
-     * Calculate exponential backoff delay with optional jitter.
-     */
-    calculateBackoff(attempt) {
-        const base = this.retryConfig.initialDelayMs * Math.pow(this.retryConfig.backoffMultiplier, attempt - 1);
-        const capped = Math.min(base, this.retryConfig.maxDelayMs);
-        if (!this.retryConfig.jitter) {
-            return capped;
-        }
-        // Add ±25% jitter using cryptographically secure random
-        const randomBytes = new Uint8Array(4);
-        crypto.getRandomValues(randomBytes);
-        const randomValue = new DataView(randomBytes.buffer).getUint32(0) / 0xffffffff;
-        const jitterFactor = 0.75 + randomValue * 0.5;
-        return Math.floor(capped * jitterFactor);
-    }
-    /**
-     * Sleep for specified milliseconds.
-     */
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
-}
-exports.GracefulDegradationManager = GracefulDegradationManager;
-/* ── Registry Fallback ── */
-/**
- * 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
- */
-async function registryLookupWithFallback(registry, did, context, manager) {
-    const cacheKey = `registry:${did}`;
-    // Check cache first for LOW QoS
-    if (context.qos === 'LOW') {
-        const cached = manager.getCached(cacheKey, context.qos);
-        if (cached) {
-            return (0, shared_1.ok)(cached);
-        }
-    }
-    // Attempt registry lookup with retry
-    const lookupResult = await manager.withRetry(() => registry.getEntry(did), context);
-    if (lookupResult.ok) {
-        manager.recordSuccess('registry');
-        // Convert Uint8Array publicKey to base64 string for caching
-        const publicKeyStr = Buffer.from(lookupResult.value.publicKey).toString('base64');
-        const entryValue = { publicKey: publicKeyStr };
-        manager.setCached(cacheKey, entryValue);
-        return (0, shared_1.ok)(entryValue);
-    }
-    // Lookup failed - record failure
-    manager.recordFailure('registry', String(lookupResult.error));
-    // Try cache fallback for HIGH/NORMAL QoS
-    if (context.qos === 'HIGH' || context.qos === 'NORMAL') {
-        const cached = manager.getCached(cacheKey, context.qos);
-        if (cached) {
-            return (0, shared_1.ok)(cached);
-        }
-    }
-    // All fallbacks exhausted - return detailed error
-    return (0, shared_1.err)((0, ux_helpers_1.createDetailedError)('REGISTRY_UNAVAILABLE', `Failed to resolve DID: ${did}`, {
-        hint: manager.getServiceHealth('registry') === 'UNAVAILABLE'
-            ? 'Registry service is currently unavailable. Using cached data may help.'
-            : 'Registry lookup failed after retries. Check network connectivity.',
-        suggested_action: context.qos === 'CRITICAL'
-            ? '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: context.qos === 'CRITICAL' ? 'critical' : 'error',
-    }));
-}
-/* ── Transport Fallback ── */
-/**
- * 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
- */
-async function sendWithTransportFallback(transports, envelope, recipientDid, context, manager) {
-    if (transports.length === 0) {
-        return (0, shared_1.err)((0, ux_helpers_1.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 errors = [];
-    for (let i = 0; i < transports.length; i++) {
-        const transport = transports[i];
-        if (!transport)
-            continue;
-        const sendResult = await manager.withRetry(() => transport.send(envelope, recipientDid), context);
-        if (sendResult.ok) {
-            manager.recordSuccess(`transport:${i}`);
-            return (0, shared_1.ok)(undefined);
-        }
-        // Record failure and try next transport
-        errors.push({ transport: i, error: sendResult.error });
-        manager.recordFailure(`transport:${i}`, sendResult.error);
-    }
-    // All transports failed
-    const primaryError = errors[0]?.error ?? 'SEND_FAILED';
-    return (0, shared_1.err)((0, ux_helpers_1.createDetailedError)('TRANSPORT_EXHAUSTED', `All transport adapters failed: ${errors.map(e => e.error).join(', ')}`, {
-        hint: primaryError === 'NETWORK_ERROR'
-            ? 'Network connectivity issue detected. Check internet connection.'
-            : primaryError === 'TIMEOUT'
-                ? 'Transport timeout occurred. Recipient may be unreachable or overloaded.'
-                : primaryError === 'RECIPIENT_UNREACHABLE'
-                    ? '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: context.qos === 'CRITICAL' ? 'critical' : 'error',
-    }));
-}
-/* ── User-Friendly Error Messages ── */
-/**
- * Enhance error with QoS-appropriate messaging.
- *
- * @param error Original error
- * @param context Operation context
- * @param manager Degradation manager
- * @returns Enhanced error with actionable hints
- */
-function enhanceError(error, context, manager) {
-    const serviceHealth = manager.getServiceHealth(context.type.split(':')[0] ?? 'unknown');
-    // Add service health context to hint
-    const healthHint = serviceHealth === 'DEGRADED'
-        ? ' Service is experiencing degraded performance.'
-        : serviceHealth === 'UNAVAILABLE'
-            ? ' Service is currently unavailable.'
-            : '';
-    // Add QoS-specific suggestions
-    const qosHint = context.qos === 'CRITICAL'
-        ? ' Consider retrying when service recovers.'
-        : context.qos === 'HIGH'
-            ? ' Cached data may be used if available.'
-            : ' Using cached data regardless of staleness.';
-    return {
-        ...error,
-        hint: (error.hint ?? '') + healthHint + qosHint,
-    };
-}
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.GracefulDegradationManager=void 0,exports.registryLookupWithFallback=registryLookupWithFallback,exports.sendWithTransportFallback=sendWithTransportFallback,exports.enhanceError=enhanceError;const shared_1=require("../_deps/shared/index.js"),ux_helpers_1=require("../_deps/ux-helpers/index.js"),DEFAULT_CACHE_CONFIG={defaultTTL:3e5,maxSize:1e3,allowStale:!0,maxStaleMs:36e5},DEFAULT_RETRY_CONFIG={maxAttempts:3,initialDelayMs:1e3,backoffMultiplier:2,maxDelayMs:3e4,jitter:!0};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,s=a<=r.ttl,i=a>r.ttl&&a<=this.cacheConfig.maxStaleMs;return"CRITICAL"===t||"HIGH"===t?s?r.value:void 0:this.cacheConfig.allowStale&&(s||i)?(r.usageCount++,r.value):s?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 s=await e();if(s.ok)return s;if(a=s.error,t<r){const e=this.calculateBackoff(t);await this.sleep(e)}}return(0,shared_1.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 s=.75+.5*(new DataView(a.buffer).getUint32(0)/4294967295);return Math.floor(r*s)}sleep(e){return new Promise(t=>setTimeout(t,e))}}async function registryLookupWithFallback(e,t,r,a){const s=`registry:${t}`;if("LOW"===r.qos){const e=a.getCached(s,r.qos);if(e)return(0,shared_1.ok)(e)}const i=await a.withRetry(()=>e.getEntry(t),r);if(i.ok){a.recordSuccess("registry");const e={publicKey:Buffer.from(i.value.publicKey).toString("base64")};return a.setCached(s,e),(0,shared_1.ok)(e)}if(a.recordFailure("registry",String(i.error)),"HIGH"===r.qos||"NORMAL"===r.qos){const e=a.getCached(s,r.qos);if(e)return(0,shared_1.ok)(e)}return(0,shared_1.err)((0,ux_helpers_1.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"}))}async function sendWithTransportFallback(e,t,r,a,s){if(0===e.length)return(0,shared_1.err)((0,ux_helpers_1.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 i=[];for(let o=0;o<e.length;o++){const c=e[o];if(!c)continue;const n=await s.withRetry(()=>c.send(t,r),a);if(n.ok)return s.recordSuccess(`transport:${o}`),(0,shared_1.ok)(void 0);i.push({transport:o,error:n.error}),s.recordFailure(`transport:${o}`,n.error)}const o=i[0]?.error??"SEND_FAILED";return(0,shared_1.err)((0,ux_helpers_1.createDetailedError)("TRANSPORT_EXHAUSTED",`All transport adapters failed: ${i.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"}))}function enhanceError(e,t,r){const a=r.getServiceHealth(t.type.split(":")[0]??"unknown"),s="DEGRADED"===a?" Service is experiencing degraded performance.":"UNAVAILABLE"===a?" Service is currently unavailable.":"",i="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??"")+s+i}}exports.GracefulDegradationManager=GracefulDegradationManager;

package/dist-standalone/cjs/guardrails.js

@@ -1,223 +1 @@
-"use strict";
-/**
- * @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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Guardrails = exports.PolicyDenied = void 0;
-exports.extractSuggestion = extractSuggestion;
-exports.toPolicyDenied = toPolicyDenied;
-/**
- * Policy violation error with actionable suggestions
- */
-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);
-    }
-}
-exports.PolicyDenied = PolicyDenied;
-/**
- * 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
- * ```
- */
-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);
-    }
-}
-exports.Guardrails = Guardrails;
-/**
- * Helper: Extract actionable suggestion from AgentError details
- *
- * Used by agent.call() to convert PolicyViolationDetails into PolicyDenied
- */
-function extractSuggestion(details) {
-    return details.fix ?? 'Contact administrator to update policy';
-}
-/**
- * Helper: Convert PolicyViolationDetails to PolicyDenied
- */
-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);
-}
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.Guardrails=exports.PolicyDenied=void 0,exports.extractSuggestion=extractSuggestion,exports.toPolicyDenied=toPolicyDenied;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)}}exports.PolicyDenied=PolicyDenied;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)}}function extractSuggestion(e){return e.fix??"Contact administrator to update policy"}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)}exports.Guardrails=Guardrails;