@provos/ironcurtain 0.7.2 → 0.9.0

package/dist/docker/package-types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Type definitions for the secure package installation proxy.
+ *
+ * These types are shared across the package validator, registry proxy,
+ * and MITM proxy integration layers.
+ */
+/**
+ * Supported package registry types.
+ * Each type determines how package names and versions are extracted
+ * from HTTP request paths, and how metadata responses are filtered.
+ */
+export type RegistryType = 'npm' | 'pypi' | 'debian';
+/**
+ * Configuration for a package registry host.
+ *
+ * Unlike ProviderConfig (which handles credential swap and endpoint
+ * filtering for LLM APIs), RegistryConfig handles package-level
+ * validation for software registries.
+ *
+ * No key injection is needed -- package registries are public.
+ */
+export interface RegistryConfig {
+    /** Registry hostname (e.g., 'registry.npmjs.org'). */
+    readonly host: string;
+    /** Human-readable name for logging. */
+    readonly displayName: string;
+    /** Registry type, determines URL parsing and metadata filtering strategy. */
+    readonly type: RegistryType;
+    /**
+     * Additional hosts that serve package tarballs for this registry.
+     * For PyPI, this includes 'files.pythonhosted.org'.
+     * These hosts are added to the MITM proxy's allowlist and their
+     * requests are validated using the same rules as the main host.
+     */
+    readonly mirrorHosts?: readonly string[];
+}
+/**
+ * Parsed package identity extracted from a registry HTTP request.
+ *
+ * Invariant: scope is only present for npm scoped packages
+ * (e.g., @types/node). PyPI packages never have a scope.
+ */
+export interface PackageIdentity {
+    /** Registry type this package belongs to. */
+    readonly registry: RegistryType;
+    /** Package name (e.g., 'express', 'numpy'). */
+    readonly name: string;
+    /** npm scope without @, if scoped (e.g., 'types' for @types/node). */
+    readonly scope?: string;
+    /** Package version, if parseable from the URL or metadata. */
+    readonly version?: string;
+}
+/**
+ * Result of a package validation check.
+ * Binary: allow or deny. No escalation.
+ */
+export type PackageDecision = {
+    readonly status: 'allow';
+    readonly reason: string;
+} | {
+    readonly status: 'deny';
+    readonly reason: string;
+};
+/**
+ * Per-version metadata from the registry, focused on the fields
+ * needed for security validation.
+ *
+ * Intentionally minimal -- we only extract what we check.
+ */
+export interface VersionMetadata {
+    /** When this specific version was published. */
+    readonly publishedAt?: Date;
+    /** Whether this version has been deprecated. */
+    readonly deprecated?: boolean;
+}
+/**
+ * Validates whether a package version should be allowed.
+ *
+ * Used in two contexts:
+ * 1. Metadata filtering: called per-version to decide which versions
+ *    to include in the filtered metadata response.
+ * 2. Tarball backstop: called when a tarball download is requested,
+ *    as a defense-in-depth check.
+ */
+export interface PackageValidator {
+    /**
+     * Validates a package version against configured rules.
+     *
+     * @param pkg - Parsed package identity (name, version, scope).
+     * @param metadata - Per-version metadata from the registry, if available.
+     *   Undefined when metadata could not be fetched (treated as deny).
+     * @returns Decision: allow or deny.
+     */
+    validate(pkg: PackageIdentity, metadata: VersionMetadata | undefined): PackageDecision;
+}
+/**
+ * In-memory cache of allowed versions per package.
+ * Populated during metadata filtering, consulted during tarball downloads.
+ *
+ * Keyed by canonical package identifier: 'npm:express', 'npm:@types/node',
+ * 'pypi:numpy'.
+ */
+export type AllowedVersionCache = Map<string, {
+    /** Set of version strings that passed validation. */
+    readonly allowedVersions: ReadonlySet<string>;
+    /** When this cache entry was populated. */
+    readonly cachedAt: Date;
+}>;
+/**
+ * Audit log entry for package installation decisions.
+ * Written to package-audit.jsonl in the session directory.
+ */
+export interface PackageAuditEntry {
+    readonly timestamp: string;
+    /** Package identity. */
+    readonly registry: RegistryType;
+    readonly packageName: string;
+    readonly packageVersion?: string;
+    readonly packageScope?: string;
+    /** Decision made by the validator. */
+    readonly decision: 'allow' | 'deny';
+    readonly reason: string;
+    /** Whether this was a metadata filter or tarball backstop decision. */
+    readonly source: 'metadata-filter' | 'tarball-backstop' | 'deb-backstop';
+    /** The HTTP request path that triggered this check. */
+    readonly requestPath: string;
+}

package/dist/docker/package-types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for the secure package installation proxy.
+ *
+ * These types are shared across the package validator, registry proxy,
+ * and MITM proxy integration layers.
+ */
+export {};
+//# sourceMappingURL=package-types.js.map

package/dist/docker/package-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-types.js","sourceRoot":"","sources":["../../src/docker/package-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/docker/package-validator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Package validation logic for the registry proxy.
+ *
+ * Evaluates packages against allowlist, denylist, and age gate rules.
+ * Decisions are binary: allow or deny. No escalation.
+ *
+ * Validation order (first match wins):
+ * 1. Denylist match    -> DENY
+ * 2. Allowlist match   -> ALLOW (bypasses age gate)
+ * 3. Version too new   -> DENY
+ * 4. No metadata       -> DENY (fail-closed)
+ * 5. Default           -> ALLOW
+ */
+import type { PackageIdentity, PackageValidator } from './package-types.js';
+/** Fallback validator that denies all packages. Used when no validator is configured. */
+export declare const DENY_ALL_VALIDATOR: PackageValidator;
+export interface PackageValidatorConfig {
+    /** Packages always allowed (bypass age gate). Supports glob patterns. */
+    readonly allowedPackages?: readonly string[];
+    /** Packages always denied. Takes precedence over allowedPackages. Supports glob patterns. */
+    readonly deniedPackages?: readonly string[];
+    /** Days a version must age before auto-allow. 0 disables age gate. */
+    readonly quarantineDays?: number;
+}
+/**
+ * Returns the canonical display name for a package.
+ * Scoped npm packages use '@scope/name' format.
+ */
+export declare function canonicalPackageName(pkg: PackageIdentity): string;
+/**
+ * Returns the canonical cache key for a package.
+ * Format: 'npm:express', 'npm:@types/node', 'pypi:numpy'.
+ */
+export declare function packageCacheKey(pkg: PackageIdentity): string;
+/**
+ * Creates a PackageValidator from configuration.
+ *
+ * The validator is stateless -- all configuration is captured at
+ * construction time. Thread-safe for concurrent use.
+ */
+export declare function createPackageValidator(config?: PackageValidatorConfig): PackageValidator;

package/dist/docker/package-validator.js

@@ -0,0 +1,90 @@
+/**
+ * Package validation logic for the registry proxy.
+ *
+ * Evaluates packages against allowlist, denylist, and age gate rules.
+ * Decisions are binary: allow or deny. No escalation.
+ *
+ * Validation order (first match wins):
+ * 1. Denylist match    -> DENY
+ * 2. Allowlist match   -> ALLOW (bypasses age gate)
+ * 3. Version too new   -> DENY
+ * 4. No metadata       -> DENY (fail-closed)
+ * 5. Default           -> ALLOW
+ */
+import { minimatch } from 'minimatch';
+/** Fallback validator that denies all packages. Used when no validator is configured. */
+export const DENY_ALL_VALIDATOR = {
+    validate: () => ({ status: 'deny', reason: 'No validator configured' }),
+};
+/** Default quarantine period in days. */
+const DEFAULT_QUARANTINE_DAYS = 2;
+/** Milliseconds per day, used for age calculations. */
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * Returns the canonical display name for a package.
+ * Scoped npm packages use '@scope/name' format.
+ */
+export function canonicalPackageName(pkg) {
+    return pkg.scope ? `@${pkg.scope}/${pkg.name}` : pkg.name;
+}
+/**
+ * Returns the canonical cache key for a package.
+ * Format: 'npm:express', 'npm:@types/node', 'pypi:numpy'.
+ */
+export function packageCacheKey(pkg) {
+    return `${pkg.registry}:${canonicalPackageName(pkg)}`;
+}
+/**
+ * Checks if a package name matches any pattern in the given list.
+ * Supports glob patterns via minimatch.
+ */
+function matchesPatternList(packageName, patterns) {
+    return patterns.some((pattern) => minimatch(packageName, pattern, { nocase: true }));
+}
+/**
+ * Creates a PackageValidator from configuration.
+ *
+ * The validator is stateless -- all configuration is captured at
+ * construction time. Thread-safe for concurrent use.
+ */
+export function createPackageValidator(config = {}) {
+    const allowedPackages = config.allowedPackages ?? [];
+    const deniedPackages = config.deniedPackages ?? [];
+    const quarantineDays = config.quarantineDays ?? DEFAULT_QUARANTINE_DAYS;
+    return {
+        validate(pkg, metadata) {
+            const name = canonicalPackageName(pkg);
+            // 1. Denylist (takes precedence over everything)
+            if (deniedPackages.length > 0 && matchesPatternList(name, deniedPackages)) {
+                return { status: 'deny', reason: `Package "${name}" is on the deny list` };
+            }
+            // 2. Allowlist (bypasses age gate)
+            if (allowedPackages.length > 0 && matchesPatternList(name, allowedPackages)) {
+                return { status: 'allow', reason: `Package "${name}" is on the allow list` };
+            }
+            // 3. Age gate (only when quarantineDays > 0)
+            if (quarantineDays > 0) {
+                if (!metadata) {
+                    // 4. No metadata -> fail-closed
+                    return { status: 'deny', reason: `No metadata available for "${name}" (fail-closed)` };
+                }
+                if (!metadata.publishedAt) {
+                    // No publish timestamp -> fail-closed
+                    return { status: 'deny', reason: `No publish timestamp for "${name}" (fail-closed)` };
+                }
+                const ageMs = Math.max(0, Date.now() - metadata.publishedAt.getTime());
+                const ageDays = ageMs / MS_PER_DAY;
+                if (ageDays < quarantineDays) {
+                    const daysOld = Math.floor(ageDays);
+                    return {
+                        status: 'deny',
+                        reason: `Version "${pkg.version ?? 'unknown'}" of "${name}" is only ${daysOld} day(s) old (quarantine: ${quarantineDays} days)`,
+                    };
+                }
+            }
+            // 5. Default -> allow
+            return { status: 'allow', reason: 'Passed all validation checks' };
+        },
+    };
+}
+//# sourceMappingURL=package-validator.js.map

package/dist/docker/package-validator.js.map

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

package/dist/docker/platform.d.ts

@@ -12,9 +12,9 @@
  * Docker Desktop's VirtioFS does not support UDS in bind mounts.
  */
 export declare function useTcpTransport(): boolean;
-/** Docker network name for the internal (no-egress) bridge used in TCP mode. */
-export declare const INTERNAL_NETWORK_NAME = "ironcurtain-internal";
-/** Subnet for the internal bridge network. */
-export declare const INTERNAL_NETWORK_SUBNET = "172.30.0.0/24";
-/** Gateway IP for the internal bridge network (host-side). */
-export declare const INTERNAL_NETWORK_GATEWAY = "172.30.0.1";
+/**
+ * Returns a per-session Docker network name for the internal (no-egress)
+ * bridge used in TCP mode. Each session gets its own network to avoid
+ * conflicts when multiple sessions run concurrently.
+ */
+export declare function getInternalNetworkName(shortId: string): string;

package/dist/docker/platform.js

@@ -15,10 +15,12 @@ import { platform } from 'node:os';
 export function useTcpTransport() {
     return platform() === 'darwin';
 }
-/** Docker network name for the internal (no-egress) bridge used in TCP mode. */
-export const INTERNAL_NETWORK_NAME = 'ironcurtain-internal';
-/** Subnet for the internal bridge network. */
-export const INTERNAL_NETWORK_SUBNET = '172.30.0.0/24';
-/** Gateway IP for the internal bridge network (host-side). */
-export const INTERNAL_NETWORK_GATEWAY = '172.30.0.1';
+/**
+ * Returns a per-session Docker network name for the internal (no-egress)
+ * bridge used in TCP mode. Each session gets its own network to avoid
+ * conflicts when multiple sessions run concurrently.
+ */
+export function getInternalNetworkName(shortId) {
+    return `ironcurtain-${shortId}`;
+}
 //# sourceMappingURL=platform.js.map

package/dist/docker/platform.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/docker/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,QAAQ,EAAE,KAAK,QAAQ,CAAC;AACjC,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAE5D,8CAA8C;AAC9C,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAEvD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC"}
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/docker/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,QAAQ,EAAE,KAAK,QAAQ,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,eAAe,OAAO,EAAE,CAAC;AAClC,CAAC"}

package/dist/docker/proxy-tools.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Proxy MCP Server tool definitions, annotations, and policy rules.
+ *
+ * These are hardcoded (not generated by the LLM pipeline) because the
+ * proxy tools have known, fixed semantics. The annotations and rules
+ * are injected into the PolicyEngine at startup so that domain
+ * management calls go through normal policy evaluation and audit logging.
+ */
+import type { CompiledRule, StoredToolAnnotation } from '../pipeline/types.js';
+/** Validates a domain string for use as a passthrough host. */
+export declare function validateDomain(domain: string): void;
+export interface DomainListing {
+    /** Statically configured LLM provider hosts (with key swap). */
+    readonly providers: readonly string[];
+    /** Dynamically added passthrough hosts (no key swap). */
+    readonly dynamic: readonly string[];
+}
+/** MCP tool definitions for the proxy server. */
+export declare const proxyToolDefinitions: readonly [{
+    readonly name: "add_proxy_domain";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly domain: {
+                readonly type: "string";
+                readonly description: "The exact domain name to allow (e.g., \"api.example.com\"). No wildcards.";
+            };
+            readonly justification: {
+                readonly type: "string";
+                readonly description: string;
+            };
+        };
+        readonly required: readonly ["domain", "justification"];
+    };
+}, {
+    readonly name: "remove_proxy_domain";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly domain: {
+                readonly type: "string";
+                readonly description: "The domain name to remove.";
+            };
+        };
+        readonly required: readonly ["domain"];
+    };
+}, {
+    readonly name: "list_proxy_domains";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+}];
+export declare const proxyAnnotations: StoredToolAnnotation[];
+export declare const proxyPolicyRules: CompiledRule[];
+export interface ControlApiClient {
+    addDomain(domain: string): Promise<{
+        added: boolean;
+    }>;
+    removeDomain(domain: string): Promise<{
+        removed: boolean;
+    }>;
+    listDomains(): Promise<DomainListing>;
+}
+/**
+ * Creates an HTTP client for the MITM proxy's domain control API.
+ *
+ * @param controlAddr - "unix:///path/to/socket" or "http://127.0.0.1:PORT"
+ */
+export declare function createControlApiClient(controlAddr: string): ControlApiClient;
+/**
+ * Dispatches a virtual proxy tool call to the control API.
+ * Called by mcp-proxy-server.ts when the tool belongs to the 'proxy' server.
+ */
+export declare function handleVirtualProxyTool(toolName: string, args: Record<string, unknown>, client: ControlApiClient): Promise<unknown>;
+/** Server names reserved for internal use that cannot be used in mcp-servers.json. */
+export declare const RESERVED_SERVER_NAMES: Set<string>;

package/dist/docker/proxy-tools.js

@@ -0,0 +1,248 @@
+/**
+ * Proxy MCP Server tool definitions, annotations, and policy rules.
+ *
+ * These are hardcoded (not generated by the LLM pipeline) because the
+ * proxy tools have known, fixed semantics. The annotations and rules
+ * are injected into the PolicyEngine at startup so that domain
+ * management calls go through normal policy evaluation and audit logging.
+ */
+import * as http from 'node:http';
+// ---------------------------------------------------------------------------
+// Domain validation
+// ---------------------------------------------------------------------------
+const DOMAIN_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+const IP_RE = /^\d{1,3}(\.\d{1,3}){3}$/;
+const DOCKER_INTERNAL_SUFFIX = '.docker.internal';
+/** Validates a domain string for use as a passthrough host. */
+export function validateDomain(domain) {
+    if (domain.length > 253)
+        throw new Error(`Domain too long (${domain.length} > 253)`);
+    if (domain.toLowerCase() === 'localhost') {
+        throw new Error(`Blocked host: "${domain}"`);
+    }
+    if (!DOMAIN_RE.test(domain))
+        throw new Error(`Invalid domain format: "${domain}"`);
+    if (IP_RE.test(domain))
+        throw new Error(`IP addresses are not allowed: "${domain}"`);
+    if (domain.toLowerCase().endsWith(DOCKER_INTERNAL_SUFFIX)) {
+        throw new Error(`Blocked host: "${domain}" (*.docker.internal is not allowed)`);
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP tool schemas
+// ---------------------------------------------------------------------------
+/** MCP tool definitions for the proxy server. */
+export const proxyToolDefinitions = [
+    {
+        name: 'add_proxy_domain',
+        description: 'Request access to an additional internet domain through the network proxy. ' +
+            'This will be reviewed by a human before being granted. ' +
+            'Provide a clear justification for why the domain is needed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                domain: {
+                    type: 'string',
+                    description: 'The exact domain name to allow (e.g., "api.example.com"). No wildcards.',
+                },
+                justification: {
+                    type: 'string',
+                    description: 'Explanation of why this domain is needed for the current task. ' +
+                        'This text is shown to the human reviewer.',
+                },
+            },
+            required: ['domain', 'justification'],
+        },
+    },
+    {
+        name: 'remove_proxy_domain',
+        description: 'Remove a previously approved domain from the proxy allowlist. ' +
+            'Only dynamically added domains can be removed; built-in provider domains cannot.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                domain: {
+                    type: 'string',
+                    description: 'The domain name to remove.',
+                },
+            },
+            required: ['domain'],
+        },
+    },
+    {
+        name: 'list_proxy_domains',
+        description: 'List all domains currently accessible through the network proxy. ' +
+            'Includes both built-in provider domains and dynamically added domains.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Tool annotations (hardcoded, not LLM-generated)
+// ---------------------------------------------------------------------------
+const schemaByName = Object.fromEntries(proxyToolDefinitions.map((t) => [t.name, t.inputSchema]));
+export const proxyAnnotations = [
+    {
+        toolName: 'add_proxy_domain',
+        serverName: 'proxy',
+        comment: 'Add a domain to the MITM proxy allowlist',
+        args: {
+            domain: ['none'],
+            justification: ['none'],
+        },
+        inputSchema: schemaByName.add_proxy_domain,
+    },
+    {
+        toolName: 'remove_proxy_domain',
+        serverName: 'proxy',
+        comment: 'Remove a domain from the MITM proxy allowlist',
+        args: {
+            domain: ['none'],
+        },
+        inputSchema: schemaByName.remove_proxy_domain,
+    },
+    {
+        toolName: 'list_proxy_domains',
+        serverName: 'proxy',
+        comment: 'List currently allowed proxy domains',
+        args: {},
+        inputSchema: schemaByName.list_proxy_domains,
+    },
+];
+// ---------------------------------------------------------------------------
+// Compiled policy rules (hardcoded)
+// ---------------------------------------------------------------------------
+export const proxyPolicyRules = [
+    {
+        name: 'proxy-add-domain-escalate',
+        description: 'Adding network domains requires human review',
+        principle: 'Human oversight',
+        if: { server: ['proxy'], tool: ['add_proxy_domain'] },
+        then: 'escalate',
+        reason: 'Adding network domains expands the container attack surface and requires human review',
+    },
+    {
+        name: 'proxy-remove-domain-allow',
+        description: 'Removing domains reduces attack surface',
+        principle: 'Least privilege',
+        if: { server: ['proxy'], tool: ['remove_proxy_domain'] },
+        then: 'allow',
+        reason: 'Removing domains reduces the attack surface',
+    },
+    {
+        name: 'proxy-list-domains-allow',
+        description: 'Listing domains is a read-only operation',
+        principle: 'Least privilege',
+        if: { server: ['proxy'], tool: ['list_proxy_domains'] },
+        then: 'allow',
+        reason: 'Read-only operation with no side effects',
+    },
+];
+/**
+ * Creates an HTTP client for the MITM proxy's domain control API.
+ *
+ * @param controlAddr - "unix:///path/to/socket" or "http://127.0.0.1:PORT"
+ */
+export function createControlApiClient(controlAddr) {
+    const isUnix = controlAddr.startsWith('unix://');
+    const socketPath = isUnix ? controlAddr.slice('unix://'.length) : undefined;
+    const baseUrl = isUnix ? 'http://localhost' : controlAddr;
+    function request(method, path, body) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(path, baseUrl);
+            const opts = {
+                method,
+                hostname: url.hostname,
+                port: url.port || undefined,
+                path: url.pathname,
+                headers: { 'Content-Type': 'application/json' },
+                ...(socketPath ? { socketPath } : {}),
+            };
+            const req = http.request(opts, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    const text = Buffer.concat(chunks).toString();
+                    if (res.statusCode && res.statusCode >= 400) {
+                        reject(new Error(`Control API ${res.statusCode}: ${text}`));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(text));
+                    }
+                    catch {
+                        resolve(text);
+                    }
+                });
+                res.on('error', reject);
+            });
+            req.on('error', reject);
+            if (body !== undefined) {
+                req.end(JSON.stringify(body));
+            }
+            else {
+                req.end();
+            }
+        });
+    }
+    return {
+        async addDomain(domain) {
+            return (await request('POST', '/__ironcurtain/domains/add', { domain }));
+        },
+        async removeDomain(domain) {
+            return (await request('POST', '/__ironcurtain/domains/remove', { domain }));
+        },
+        async listDomains() {
+            return (await request('GET', '/__ironcurtain/domains'));
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Argument validation
+// ---------------------------------------------------------------------------
+/** Extracts a required string argument, throwing if missing or wrong type. */
+function requireStringArg(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Missing or invalid required argument: ${name}`);
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Virtual tool handler
+// ---------------------------------------------------------------------------
+/**
+ * Dispatches a virtual proxy tool call to the control API.
+ * Called by mcp-proxy-server.ts when the tool belongs to the 'proxy' server.
+ */
+export async function handleVirtualProxyTool(toolName, args, client) {
+    switch (toolName) {
+        case 'add_proxy_domain': {
+            const domain = requireStringArg(args, 'domain');
+            requireStringArg(args, 'justification');
+            validateDomain(domain);
+            const result = await client.addDomain(domain);
+            if (!result.added) {
+                return { status: 'already_accessible', message: 'Domain is already accessible (built-in provider)' };
+            }
+            return { status: 'added', domain };
+        }
+        case 'remove_proxy_domain': {
+            const domain = requireStringArg(args, 'domain');
+            const result = await client.removeDomain(domain);
+            return { status: result.removed ? 'removed' : 'not_found', domain };
+        }
+        case 'list_proxy_domains':
+            return client.listDomains();
+        default:
+            throw new Error(`Unknown virtual proxy tool: ${toolName}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Reserved server names
+// ---------------------------------------------------------------------------
+/** Server names reserved for internal use that cannot be used in mcp-servers.json. */
+export const RESERVED_SERVER_NAMES = new Set(['proxy']);
+//# sourceMappingURL=proxy-tools.js.map

package/dist/docker/proxy-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-tools.js","sourceRoot":"","sources":["../../src/docker/proxy-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAGlC,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,MAAM,SAAS,GAAG,oEAAoE,CAAC;AACvF,MAAM,KAAK,GAAG,yBAAyB,CAAC;AACxC,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAElD,+DAA+D;AAC/D,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,CAAC,MAAM,SAAS,CAAC,CAAC;IACrF,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,WAAW,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,GAAG,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,GAAG,CAAC,CAAC;IACnF,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,GAAG,CAAC,CAAC;IACrF,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,sCAAsC,CAAC,CAAC;IAClF,CAAC;AACH,CAAC;AAaD,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,6EAA6E;YAC7E,yDAAyD;YACzD,6DAA6D;QAC/D,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yEAAyE;iBACvF;gBACD,aAAa,EAAE;oBACb,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,iEAAiE;wBACjE,2CAA2C;iBAC9C;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,CAAC;SACtC;KACF;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,gEAAgE;YAChE,kFAAkF;QACpF,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4BAA4B;iBAC1C;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;KACF;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EACT,mEAAmE;YACnE,wEAAwE;QAC1E,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE,EAAE;SACf;KACF;CACO,CAAC;AAEX,8EAA8E;AAC9E,kDAAkD;AAClD,8EAA8E;AAE9E,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,CACrC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAsC,CAAC,CAAC,CACF,CAAC;AAEpF,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD;QACE,QAAQ,EAAE,kBAAkB;QAC5B,UAAU,EAAE,OAAO;QACnB,OAAO,EAAE,0CAA0C;QACnD,IAAI,EAAE;YACJ,MAAM,EAAE,CAAC,MAAM,CAAC;YAChB,aAAa,EAAE,CAAC,MAAM,CAAC;SACxB;QACD,WAAW,EAAE,YAAY,CAAC,gBAAgB;KAC3C;IACD;QACE,QAAQ,EAAE,qBAAqB;QAC/B,UAAU,EAAE,OAAO;QACnB,OAAO,EAAE,+CAA+C;QACxD,IAAI,EAAE;YACJ,MAAM,EAAE,CAAC,MAAM,CAAC;SACjB;QACD,WAAW,EAAE,YAAY,CAAC,mBAAmB;KAC9C;IACD;QACE,QAAQ,EAAE,oBAAoB;QAC9B,UAAU,EAAE,OAAO;QACnB,OAAO,EAAE,sCAAsC;QAC/C,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,YAAY,CAAC,kBAAkB;KAC7C;CACF,CAAC;AAEF,8EAA8E;AAC9E,oCAAoC;AACpC,8EAA8E;AAE9E,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC9C;QACE,IAAI,EAAE,2BAA2B;QACjC,WAAW,EAAE,8CAA8C;QAC3D,SAAS,EAAE,iBAAiB;QAC5B,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,kBAAkB,CAAC,EAAE;QACrD,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,uFAAuF;KAChG;IACD;QACE,IAAI,EAAE,2BAA2B;QACjC,WAAW,EAAE,yCAAyC;QACtD,SAAS,EAAE,iBAAiB;QAC5B,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,qBAAqB,CAAC,EAAE;QACxD,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,6CAA6C;KACtD;IACD;QACE,IAAI,EAAE,0BAA0B;QAChC,WAAW,EAAE,0CAA0C;QACvD,SAAS,EAAE,iBAAiB;QAC5B,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE;QACvD,IAAI,EAAE,OAAO;QACb,MAAM,EAAE,0CAA0C;KACnD;CACF,CAAC;AAYF;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,WAAW,CAAC;IAE1D,SAAS,OAAO,CAAC,MAAc,EAAE,IAAY,EAAE,IAAc;QAC3D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACnC,MAAM,IAAI,GAAwB;gBAChC,MAAM;gBACN,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS;gBAC3B,IAAI,EAAE,GAAG,CAAC,QAAQ;gBAClB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtC,CAAC;YAEF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE;gBACrC,MAAM,MAAM,GAAa,EAAE,CAAC;gBAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;gBACtD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;oBACjB,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;oBAC9C,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;wBAC5C,MAAM,CAAC,IAAI,KAAK,CAAC,eAAe,GAAG,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;wBAC5D,OAAO;oBACT,CAAC;oBACD,IAAI,CAAC;wBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;oBAC5B,CAAC;oBAAC,MAAM,CAAC;wBACP,OAAO,CAAC,IAAI,CAAC,CAAC;oBAChB,CAAC;gBACH,CAAC,CAAC,CAAC;gBACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC1B,CAAC,CAAC,CAAC;YAEH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACxB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,MAAc;YAC5B,OAAO,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,4BAA4B,EAAE,EAAE,MAAM,EAAE,CAAC,CAAuB,CAAC;QACjG,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,MAAc;YAC/B,OAAO,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,+BAA+B,EAAE,EAAE,MAAM,EAAE,CAAC,CAAyB,CAAC;QACtG,CAAC;QACD,KAAK,CAAC,WAAW;YACf,OAAO,CAAC,MAAM,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,CAAkB,CAAC;QAC3E,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,8EAA8E;AAC9E,SAAS,gBAAgB,CAAC,IAA6B,EAAE,IAAY;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,yCAAyC,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,QAAgB,EAChB,IAA6B,EAC7B,MAAwB;IAExB,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChD,gBAAgB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;YACxC,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBAClB,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,kDAAkD,EAAE,CAAC;YACvG,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACrC,CAAC;QACD,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YACjD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;QACtE,CAAC;QACD,KAAK,oBAAoB;YACvB,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;QAC9B;YACE,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,EAAE,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,sFAAsF;AACtF,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC"}