paygate-mcp 9.9.0 → 10.1.0

package/README.md

@@ -11,7 +11,7 @@ Monetize any MCP server with one command. Add API key auth, per-tool pricing, ra
 - [Quick Start](#quick-start)
 - [What It Does](#what-it-does)
 - [Usage](#usage) — Local stdio, remote HTTP, multi-server, client SDK
-- [API Reference](#api-reference) — All 178+ endpoints
+- [API Reference](#api-reference) — All 196+ endpoints
 - [CLI Options](#cli-options)
 - [Deployment](#deployment) — Docker, docker-compose, systemd, PM2
 - [Load Testing](#load-testing) — k6 benchmarking for production
@@ -66,7 +66,7 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **SSE Streaming** — Full MCP Streamable HTTP transport (POST SSE, GET notifications, DELETE sessions)
 - **Audit Log** — Structured audit trail with retention policies, query API, CSV/JSON export
 - **Registry/Discovery** — Agent-discoverable pricing via `/.well-known/mcp-payment`, `/pricing`, and `/.well-known/mcp.json` identity card
-- **OpenAPI 3.1 + Interactive Docs** — Auto-generated spec at `/openapi.json`, Swagger UI at `/docs` — all 178+ endpoints documented
+- **OpenAPI 3.1 + Interactive Docs** — Auto-generated spec at `/openapi.json`, Swagger UI at `/docs` — all 196+ endpoints documented
 - **Public Endpoint Rate Limiting** — Configurable per-IP rate limit (default 300/min) on `/health`, `/info`, `/pricing`, `/docs`, `/openapi.json`, `/.well-known/*`, `/robots.txt`, `/` — 429 with Retry-After header
 - **Robots.txt + HEAD Support** — Standard `/robots.txt` (allow public, disallow admin/keys), HEAD method on all public endpoints for uptime monitoring
 - **Prometheus Metrics** — `/metrics` endpoint with counters, gauges, and uptime in standard text format
@@ -174,6 +174,12 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **IP Access Control** — Fine-grained IP-based access control with CIDR notation support — global allow/deny lists, per-key IP binding, automatic blocking after configurable violation thresholds, X-Forwarded-For/X-Real-IP trusted proxy depth, IPv6-mapped IPv4 normalization, manage via `GET/POST/DELETE /admin/ip-access`
 - **Request Signing (HMAC-SHA256)** — Cryptographic request authentication with replay protection — `X-Signature: t=<ts>,n=<nonce>,s=<sig>` header, timestamp tolerance with nonce dedup, per-key signing secrets with rotation, timing-safe comparison, manage via `GET/POST/DELETE /admin/signing`
 - **Multi-Tenant Isolation** — Full tenant isolation for platform operators — per-tenant rate limits, credit pools, usage tracking, API key binding, tenant suspension/activation, cross-tenant reporting, configurable limits (10K tenants, 1K keys/tenant), manage via `GET/POST/DELETE /admin/tenants`
+- **Request Tracing** — End-to-end structured tracing with span recording at gate, backend, and transform stages — trace/request ID lookup, timing breakdown (gateMs/backendMs/transformMs), configurable sample rate, retention limits, P95 latency tracking, JSON export, manage via `GET/POST/DELETE /admin/tracing`
+- **Budget Policy Engine** — Burn rate monitoring with progressive throttling — daily/monthly budget enforcement, credits/minute burn rate tracking over configurable windows, three actions (alert/throttle/deny), per-namespace and per-key targeting, budget remaining forecast, automatic daily/monthly reset, manage via `GET/POST/DELETE /admin/budget-policies`
+- **Tool Dependency Graph** — DAG-based workflow validation — register tool dependencies, enforce execution order, failure propagation (upstream failure blocks downstream), topological sort, cycle detection, per-workflow execution tracking, hard vs soft dependencies, group scoping, manage via `GET/POST/DELETE /admin/tool-deps`
+- **Quota Management** — Granular daily/weekly/monthly hard caps per API key — per-tool or global quotas, calls or credits metric, burst allowance (temporary over-limit percentage), three overage actions (deny/warn/throttle), UTC-based period boundaries (daily midnight, weekly Monday, monthly 1st), automatic period rollover, manage via `GET/POST/DELETE /admin/quota-rules`
+- **Webhook Replay (DLQ)** — Dead letter queue management for failed webhook deliveries — record failures with full request context (URL, headers, body, HMAC signature), replay individual or bulk failed deliveries, status tracking (pending → retrying → succeeded/exhausted), configurable max retries with timeout, purge by ID or status, age-based expiry, manage via `GET/POST/DELETE /admin/webhook-replay`
+- **Config Profiles** — Named configuration presets with save/activate/rollback — profile inheritance chains (base → child merging), SHA-256 checksums, flat-key diffing for comparison (onlyInA/onlyInB/changed/unchanged), import/export as JSON with merge or replace mode, activation history, circular inheritance detection, manage via `GET/POST/DELETE /admin/config-profiles`
 - **Anomaly Detection** — `GET /admin/anomalies` identifies unusual patterns: keys with high denial rates, rapid credit depletion, low remaining credits, with severity ratings and detailed descriptions
 - **Usage Forecasting** — `GET /admin/forecast` predicts future credit consumption with per-key depletion estimates, calls remaining, at-risk key identification, system-wide consumption aggregates, and per-tool cost breakdown
 - **Compliance Report** — `GET /admin/compliance` generates compliance-ready report with key governance (expiry coverage), access control (ACL/IP/spending limit coverage), audit trail completeness, weighted overall score, and actionable recommendations
@@ -487,7 +493,7 @@ A real-time admin UI for managing keys, viewing usage, and monitoring tool calls
 | `/.well-known/mcp-payment` | GET | None | Server payment metadata (SEP-2007) |
 | `/.well-known/mcp.json` | GET | None | MCP Server Identity card (discovery) |
 | `/pricing` | GET | None | Full per-tool pricing breakdown |
-| `/openapi.json` | GET | None | OpenAPI 3.1 spec (all 178+ endpoints) |
+| `/openapi.json` | GET | None | OpenAPI 3.1 spec (all 196+ endpoints) |
 | `/docs` | GET | None | Interactive API docs (Swagger UI) |
 | `/robots.txt` | GET | None | Crawler directives (allow public, disallow admin/keys) |
 | `/portal` | GET | None | Self-service API key portal (browser UI, auth via X-API-Key prompt) |

package/dist/budget-policy.d.ts

@@ -0,0 +1,130 @@
+/**
+ * BudgetPolicyEngine — Spend governance and burn rate control.
+ *
+ * Protects against unexpected cost explosions from leaked tokens,
+ * runaway agents, or usage pattern changes. Monitors burn rates
+ * and enforces daily/monthly budgets with progressive throttling.
+ *
+ * Features:
+ *   - Burn rate monitoring with configurable window and threshold
+ *   - Progressive throttling (auto-reduce rate limits on overspend)
+ *   - Daily and monthly budget enforcement
+ *   - Budget remaining forecast via X-Budget-Remaining header
+ *   - Per-namespace and per-group policy targeting
+ *   - Stats: budget utilization, burn rate, throttle events
+ *
+ * Zero external dependencies.
+ */
+export interface BudgetPolicy {
+    policyId: string;
+    name: string;
+    /** Target namespace. Null = global. */
+    targetNamespace?: string;
+    /** Target API key. Null = all keys in namespace. */
+    targetApiKey?: string;
+    /** Credits per minute threshold to trigger alert. Default 100. */
+    burnRateThreshold: number;
+    /** Window in seconds to measure burn rate. Default 60. */
+    burnRateWindowSec: number;
+    /** Daily budget in credits. 0 = unlimited. */
+    dailyBudget: number;
+    /** Monthly budget in credits. 0 = unlimited. */
+    monthlyBudget: number;
+    /** Action when burn rate exceeded. */
+    onBurnRateExceeded: 'alert' | 'throttle' | 'deny';
+    /** Throttle reduction percent. Default 50. */
+    throttleReductionPercent: number;
+    /** Throttle cooldown in seconds. Default 300 (5 min). */
+    throttleCooldownSec: number;
+    active: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface BudgetState {
+    policyId: string;
+    /** Rolling window spend entries. */
+    windowSpend: {
+        time: number;
+        credits: number;
+    }[];
+    /** Is currently throttled? */
+    isThrottled: boolean;
+    /** Throttle expires at (epoch ms). */
+    throttledUntil: number;
+    /** Today's spend. */
+    dailySpent: number;
+    /** This month's spend. */
+    monthlySpent: number;
+    /** Day boundary (epoch ms). */
+    dailyResetAt: number;
+    /** Month boundary (epoch ms). */
+    monthlyResetAt: number;
+    /** Total burn rate alerts triggered. */
+    burnRateAlerts: number;
+    /** Total throttle events. */
+    throttleEvents: number;
+}
+export interface BudgetCheckResult {
+    allowed: boolean;
+    reason?: string;
+    burnRateExceeded: boolean;
+    isThrottled: boolean;
+    dailyRemaining?: number;
+    monthlyRemaining?: number;
+    currentBurnRate: number;
+    /** Estimated hours until budget exhaustion at current rate. */
+    hoursRemaining?: number;
+}
+export interface BudgetPolicyStats {
+    totalPolicies: number;
+    activePolicies: number;
+    totalBurnRateAlerts: number;
+    totalThrottleEvents: number;
+    policies: Array<{
+        policyId: string;
+        name: string;
+        dailyUtilization: number;
+        monthlyUtilization: number;
+        currentBurnRate: number;
+        isThrottled: boolean;
+    }>;
+}
+export type BudgetPolicyCreateParams = Omit<BudgetPolicy, 'policyId' | 'createdAt' | 'updatedAt'>;
+export declare class BudgetPolicyEngine {
+    private policies;
+    private state;
+    /**
+     * Create a new budget policy.
+     */
+    createPolicy(params: BudgetPolicyCreateParams): BudgetPolicy;
+    /**
+     * Get a policy by ID.
+     */
+    getPolicy(policyId: string): BudgetPolicy | undefined;
+    /**
+     * List all policies.
+     */
+    listPolicies(): BudgetPolicy[];
+    /**
+     * Delete a policy.
+     */
+    deletePolicy(policyId: string): boolean;
+    /**
+     * Record spending and check against budget policies.
+     * Returns the most restrictive result from all applicable policies.
+     */
+    recordSpend(namespace: string | undefined, apiKey: string | undefined, credits: number): BudgetCheckResult;
+    /**
+     * Get stats across all policies.
+     */
+    stats(): BudgetPolicyStats;
+    /**
+     * Clear all policies and state.
+     */
+    clear(): void;
+    private findApplicable;
+    private checkPolicy;
+    private computeBurnRate;
+    private resetIfNeeded;
+}
+//# sourceMappingURL=budget-policy.d.ts.map

package/dist/budget-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-policy.d.ts","sourceRoot":"","sources":["../src/budget-policy.ts"],"names":[],"mappings":"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"}

package/dist/budget-policy.js

@@ -0,0 +1,326 @@
+"use strict";
+/**
+ * BudgetPolicyEngine — Spend governance and burn rate control.
+ *
+ * Protects against unexpected cost explosions from leaked tokens,
+ * runaway agents, or usage pattern changes. Monitors burn rates
+ * and enforces daily/monthly budgets with progressive throttling.
+ *
+ * Features:
+ *   - Burn rate monitoring with configurable window and threshold
+ *   - Progressive throttling (auto-reduce rate limits on overspend)
+ *   - Daily and monthly budget enforcement
+ *   - Budget remaining forecast via X-Budget-Remaining header
+ *   - Per-namespace and per-group policy targeting
+ *   - Stats: budget utilization, burn rate, throttle events
+ *
+ * Zero external dependencies.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetPolicyEngine = void 0;
+const crypto = __importStar(require("crypto"));
+// ─── Default values ─────────────────────────────────────────────────────────
+function generatePolicyId() {
+    return 'bpol_' + crypto.randomBytes(8).toString('hex');
+}
+function nextDayStart() {
+    const d = new Date();
+    d.setUTCHours(0, 0, 0, 0);
+    d.setUTCDate(d.getUTCDate() + 1);
+    return d.getTime();
+}
+function nextMonthStart() {
+    const d = new Date();
+    d.setUTCDate(1);
+    d.setUTCHours(0, 0, 0, 0);
+    d.setUTCMonth(d.getUTCMonth() + 1);
+    return d.getTime();
+}
+// ─── BudgetPolicyEngine Class ───────────────────────────────────────────────
+class BudgetPolicyEngine {
+    policies = new Map();
+    state = new Map();
+    /**
+     * Create a new budget policy.
+     */
+    createPolicy(params) {
+        const policyId = generatePolicyId();
+        const now = Date.now();
+        const policy = {
+            policyId,
+            name: params.name,
+            targetNamespace: params.targetNamespace,
+            targetApiKey: params.targetApiKey,
+            burnRateThreshold: params.burnRateThreshold ?? 100,
+            burnRateWindowSec: params.burnRateWindowSec ?? 60,
+            dailyBudget: params.dailyBudget ?? 0,
+            monthlyBudget: params.monthlyBudget ?? 0,
+            onBurnRateExceeded: params.onBurnRateExceeded ?? 'alert',
+            throttleReductionPercent: params.throttleReductionPercent ?? 50,
+            throttleCooldownSec: params.throttleCooldownSec ?? 300,
+            active: params.active ?? true,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.policies.set(policyId, policy);
+        this.state.set(policyId, {
+            policyId,
+            windowSpend: [],
+            isThrottled: false,
+            throttledUntil: 0,
+            dailySpent: 0,
+            monthlySpent: 0,
+            dailyResetAt: nextDayStart(),
+            monthlyResetAt: nextMonthStart(),
+            burnRateAlerts: 0,
+            throttleEvents: 0,
+        });
+        return { ...policy };
+    }
+    /**
+     * Get a policy by ID.
+     */
+    getPolicy(policyId) {
+        const p = this.policies.get(policyId);
+        return p ? { ...p } : undefined;
+    }
+    /**
+     * List all policies.
+     */
+    listPolicies() {
+        return Array.from(this.policies.values()).map(p => ({ ...p }));
+    }
+    /**
+     * Delete a policy.
+     */
+    deletePolicy(policyId) {
+        this.state.delete(policyId);
+        return this.policies.delete(policyId);
+    }
+    /**
+     * Record spending and check against budget policies.
+     * Returns the most restrictive result from all applicable policies.
+     */
+    recordSpend(namespace, apiKey, credits) {
+        const applicablePolicies = this.findApplicable(namespace, apiKey);
+        if (applicablePolicies.length === 0) {
+            return { allowed: true, burnRateExceeded: false, isThrottled: false, currentBurnRate: 0 };
+        }
+        let mostRestrictive = {
+            allowed: true,
+            burnRateExceeded: false,
+            isThrottled: false,
+            currentBurnRate: 0,
+        };
+        for (const policy of applicablePolicies) {
+            const result = this.checkPolicy(policy, credits);
+            if (!result.allowed) {
+                mostRestrictive = result;
+                break;
+            }
+            if (result.burnRateExceeded)
+                mostRestrictive.burnRateExceeded = true;
+            if (result.isThrottled)
+                mostRestrictive.isThrottled = true;
+            if (result.currentBurnRate > mostRestrictive.currentBurnRate) {
+                mostRestrictive.currentBurnRate = result.currentBurnRate;
+            }
+            if (result.dailyRemaining !== undefined) {
+                mostRestrictive.dailyRemaining = Math.min(mostRestrictive.dailyRemaining ?? Infinity, result.dailyRemaining);
+            }
+            if (result.monthlyRemaining !== undefined) {
+                mostRestrictive.monthlyRemaining = Math.min(mostRestrictive.monthlyRemaining ?? Infinity, result.monthlyRemaining);
+            }
+            if (result.hoursRemaining !== undefined) {
+                mostRestrictive.hoursRemaining = Math.min(mostRestrictive.hoursRemaining ?? Infinity, result.hoursRemaining);
+            }
+        }
+        return mostRestrictive;
+    }
+    /**
+     * Get stats across all policies.
+     */
+    stats() {
+        let totalAlerts = 0;
+        let totalThrottles = 0;
+        const policyStats = [];
+        for (const policy of this.policies.values()) {
+            const st = this.state.get(policy.policyId);
+            if (!st)
+                continue;
+            this.resetIfNeeded(st);
+            totalAlerts += st.burnRateAlerts;
+            totalThrottles += st.throttleEvents;
+            const burnRate = this.computeBurnRate(st, policy);
+            policyStats.push({
+                policyId: policy.policyId,
+                name: policy.name,
+                dailyUtilization: policy.dailyBudget > 0 ? Math.round((st.dailySpent / policy.dailyBudget) * 100) : 0,
+                monthlyUtilization: policy.monthlyBudget > 0 ? Math.round((st.monthlySpent / policy.monthlyBudget) * 100) : 0,
+                currentBurnRate: burnRate,
+                isThrottled: st.isThrottled && st.throttledUntil > Date.now(),
+            });
+        }
+        return {
+            totalPolicies: this.policies.size,
+            activePolicies: Array.from(this.policies.values()).filter(p => p.active).length,
+            totalBurnRateAlerts: totalAlerts,
+            totalThrottleEvents: totalThrottles,
+            policies: policyStats,
+        };
+    }
+    /**
+     * Clear all policies and state.
+     */
+    clear() {
+        this.policies.clear();
+        this.state.clear();
+    }
+    // ─── Private ───────────────────────────────────────────────────────────────
+    findApplicable(namespace, apiKey) {
+        const results = [];
+        for (const policy of this.policies.values()) {
+            if (!policy.active)
+                continue;
+            // Check targeting: most specific match wins
+            if (policy.targetApiKey && policy.targetApiKey !== apiKey)
+                continue;
+            if (policy.targetNamespace && policy.targetNamespace !== namespace)
+                continue;
+            results.push(policy);
+        }
+        return results;
+    }
+    checkPolicy(policy, credits) {
+        const st = this.state.get(policy.policyId);
+        this.resetIfNeeded(st);
+        const now = Date.now();
+        // Record spend
+        st.dailySpent += credits;
+        st.monthlySpent += credits;
+        st.windowSpend.push({ time: now, credits });
+        // Prune old window entries
+        const windowCutoff = now - (policy.burnRateWindowSec * 1000);
+        st.windowSpend = st.windowSpend.filter(e => e.time >= windowCutoff);
+        // Compute burn rate (credits/minute)
+        const burnRate = this.computeBurnRate(st, policy);
+        const burnRateExceeded = burnRate > policy.burnRateThreshold;
+        // Check daily budget
+        if (policy.dailyBudget > 0 && st.dailySpent > policy.dailyBudget) {
+            return {
+                allowed: false,
+                reason: 'daily-budget-exceeded',
+                burnRateExceeded,
+                isThrottled: false,
+                dailyRemaining: 0,
+                monthlyRemaining: policy.monthlyBudget > 0 ? Math.max(0, policy.monthlyBudget - st.monthlySpent) : undefined,
+                currentBurnRate: burnRate,
+            };
+        }
+        // Check monthly budget
+        if (policy.monthlyBudget > 0 && st.monthlySpent > policy.monthlyBudget) {
+            return {
+                allowed: false,
+                reason: 'monthly-budget-exceeded',
+                burnRateExceeded,
+                isThrottled: false,
+                dailyRemaining: policy.dailyBudget > 0 ? Math.max(0, policy.dailyBudget - st.dailySpent) : undefined,
+                monthlyRemaining: 0,
+                currentBurnRate: burnRate,
+            };
+        }
+        // Handle burn rate exceedance
+        if (burnRateExceeded) {
+            st.burnRateAlerts++;
+            if (policy.onBurnRateExceeded === 'deny') {
+                return {
+                    allowed: false,
+                    reason: 'burn-rate-exceeded',
+                    burnRateExceeded: true,
+                    isThrottled: false,
+                    currentBurnRate: burnRate,
+                };
+            }
+            if (policy.onBurnRateExceeded === 'throttle' && !st.isThrottled) {
+                st.isThrottled = true;
+                st.throttledUntil = now + (policy.throttleCooldownSec * 1000);
+                st.throttleEvents++;
+            }
+        }
+        // Check if throttle expired
+        if (st.isThrottled && now > st.throttledUntil) {
+            st.isThrottled = false;
+        }
+        // Compute remaining
+        const dailyRemaining = policy.dailyBudget > 0 ? Math.max(0, policy.dailyBudget - st.dailySpent) : undefined;
+        const monthlyRemaining = policy.monthlyBudget > 0 ? Math.max(0, policy.monthlyBudget - st.monthlySpent) : undefined;
+        const remaining = dailyRemaining !== undefined ? dailyRemaining : monthlyRemaining;
+        const hoursRemaining = remaining !== undefined && burnRate > 0
+            ? Math.round((remaining / burnRate) * 60) / 60 // convert from minutes
+            : undefined;
+        return {
+            allowed: true,
+            burnRateExceeded,
+            isThrottled: st.isThrottled,
+            dailyRemaining,
+            monthlyRemaining,
+            currentBurnRate: burnRate,
+            hoursRemaining,
+        };
+    }
+    computeBurnRate(st, policy) {
+        const now = Date.now();
+        const windowCutoff = now - (policy.burnRateWindowSec * 1000);
+        const windowCredits = st.windowSpend
+            .filter(e => e.time >= windowCutoff)
+            .reduce((sum, e) => sum + e.credits, 0);
+        // Credits per minute
+        return (windowCredits / policy.burnRateWindowSec) * 60;
+    }
+    resetIfNeeded(st) {
+        const now = Date.now();
+        if (now >= st.dailyResetAt) {
+            st.dailySpent = 0;
+            st.dailyResetAt = nextDayStart();
+        }
+        if (now >= st.monthlyResetAt) {
+            st.monthlySpent = 0;
+            st.monthlyResetAt = nextMonthStart();
+        }
+    }
+}
+exports.BudgetPolicyEngine = BudgetPolicyEngine;
+//# sourceMappingURL=budget-policy.js.map

package/dist/budget-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-policy.js","sourceRoot":"","sources":["../src/budget-policy.ts"],"names":[],"mappings":"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"}

package/dist/config-profiles.d.ts

@@ -0,0 +1,126 @@
+/**
+ * ConfigProfileManager — Named configuration presets.
+ *
+ * Store and switch between named configuration profiles for different
+ * environments (dev, staging, production) or use cases:
+ *   - Save current config as a named profile
+ *   - Switch between profiles at runtime
+ *   - Compare profiles to see differences
+ *   - Import/export profiles as JSON
+ *   - Profile inheritance (extend a base profile)
+ *   - Rollback to previous profile
+ *
+ * Zero external dependencies.
+ */
+export interface ConfigProfile {
+    id: string;
+    name: string;
+    /** Optional description of what this profile is for. */
+    description?: string;
+    /** The configuration snapshot. */
+    config: Record<string, unknown>;
+    /** Profile this extends (inherits values from). */
+    extendsProfile?: string;
+    /** SHA-256 checksum of the config JSON. */
+    checksum: string;
+    /** Whether this is the currently active profile. */
+    active: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ProfileDiff {
+    /** Keys only in profile A. */
+    onlyInA: string[];
+    /** Keys only in profile B. */
+    onlyInB: string[];
+    /** Keys present in both but with different values. */
+    changed: Array<{
+        key: string;
+        valueA: unknown;
+        valueB: unknown;
+    }>;
+    /** Keys with identical values in both. */
+    unchanged: string[];
+}
+export interface ProfileStats {
+    totalProfiles: number;
+    activeProfile: string | null;
+    switchCount: number;
+    lastSwitchAt: number | null;
+    rollbackAvailable: boolean;
+}
+export interface ConfigProfileManagerConfig {
+    enabled: boolean;
+    maxProfiles: number;
+    /** Max config size in bytes. Default 1MB. */
+    maxConfigSize: number;
+}
+export declare class ConfigProfileManager {
+    private config;
+    private profiles;
+    private activeProfileId;
+    private previousProfileId;
+    private _switchCount;
+    private _lastSwitchAt;
+    private counter;
+    constructor(config?: Partial<ConfigProfileManagerConfig>);
+    /**
+     * Save a configuration as a named profile.
+     */
+    saveProfile(params: {
+        name: string;
+        config: Record<string, unknown>;
+        description?: string;
+        extendsProfile?: string;
+        activate?: boolean;
+    }): ConfigProfile;
+    /**
+     * Get a profile by ID.
+     */
+    getProfile(id: string): ConfigProfile | undefined;
+    /**
+     * Get a profile by name.
+     */
+    getProfileByName(name: string): ConfigProfile | undefined;
+    /**
+     * List all profiles.
+     */
+    listProfiles(): ConfigProfile[];
+    /**
+     * Delete a profile.
+     */
+    deleteProfile(id: string): boolean;
+    /**
+     * Activate a profile (makes it the current active profile).
+     * Returns the resolved configuration (with inheritance applied).
+     */
+    activateProfile(id: string): Record<string, unknown>;
+    /**
+     * Rollback to the previously active profile.
+     */
+    rollback(): Record<string, unknown> | null;
+    /**
+     * Get the currently active profile.
+     */
+    getActive(): ConfigProfile | null;
+    /**
+     * Resolve configuration for a profile, applying inheritance.
+     */
+    resolveConfig(id: string): Record<string, unknown>;
+    /**
+     * Compare two profiles and return the differences.
+     */
+    compare(idA: string, idB: string): ProfileDiff;
+    /**
+     * Export all profiles as JSON.
+     */
+    exportProfiles(): string;
+    /**
+     * Import profiles from JSON. Returns count imported.
+     */
+    importProfiles(json: string, mode?: 'merge' | 'replace'): number;
+    configure(updates: Partial<ConfigProfileManagerConfig>): ConfigProfileManagerConfig;
+    stats(): ProfileStats;
+    clear(): void;
+}
+//# sourceMappingURL=config-profiles.d.ts.map

package/dist/config-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-profiles.d.ts","sourceRoot":"","sources":["../src/config-profiles.ts"],"names":[],"mappings":"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"}