@relayplane/proxy 1.8.35 → 1.8.38

package/dist/tool-router.d.ts

@@ -0,0 +1,163 @@
+/**
+ * ToolRouter — deny-by-default tool authorization with named scope packs.
+ *
+ * CAP 2: Hierarchical Tool Routing (Phase 2, Session 3)
+ *
+ * Authorization flow (highest-priority last wins):
+ *   1. Default deny all
+ *   2. Apply active packs (based on X-Task-Type header)
+ *   3. Apply agent-level overrides (based on X-Agent-Id header)
+ *   4. Apply explicit deny list (always wins)
+ *
+ * Lazy schema loading: schemas fetched only when a tool is (a) allowed AND (b) actually called.
+ */
+export interface ToolRateLimit {
+    maxCallsPerSession: number;
+    maxCallsPerMinute: number;
+}
+export interface ToolEntry {
+    name: string;
+    /** Optional URL or file path to a JSON schema for this tool */
+    schemaRef?: string;
+    /** 'inherit' defers to the pack's defaultPolicy */
+    policy: 'allow' | 'deny' | 'inherit';
+    requiresConfirmation?: boolean;
+    rateLimit?: ToolRateLimit;
+}
+export interface ToolPack {
+    name: string;
+    description: string;
+    tools: ToolEntry[];
+    /** Policy applied to tools NOT listed in this pack */
+    defaultPolicy: 'allow' | 'deny';
+    version: string;
+    /** True for the three built-in packs — cannot be deleted */
+    builtIn?: boolean;
+}
+export interface AgentAuthConfig {
+    agentId: string;
+    allowPacks: string[];
+    denyPacks: string[];
+    /** Per-tool overrides: tool name → 'allow' | 'deny' */
+    toolOverrides: Record<string, 'allow' | 'deny'>;
+}
+export interface ToolAuthContext {
+    sessionId: string;
+    agentId?: string;
+    taskType?: string;
+    activePacks: string[];
+    denyList: string[];
+    requestedTools: string[];
+}
+export interface ToolAuthResult {
+    /** Tools explicitly allowed by the active packs */
+    allowed: string[];
+    /** Tools denied (not in any active pack, or explicitly denied) */
+    denied: string[];
+    /** Comma-separated list for the X-Relay-Tools-Denied response header */
+    deniedHeader: string;
+    /** Tools that require user confirmation before being called */
+    requireConfirmation: string[];
+}
+export interface ToolCallRecord {
+    toolName: string;
+    sessionId: string;
+    calledAt: number;
+}
+export interface RateLimitCheckResult {
+    allowed: boolean;
+    reason?: 'session_limit' | 'minute_limit';
+    sessionCount: number;
+    minuteCount: number;
+}
+export interface ToolRouterConfig {
+    enabled: boolean;
+    /** Extra packs directory (user can place JSON pack files here) */
+    packsDir?: string;
+    /** Agent configs keyed by agentId */
+    agentConfigs?: Record<string, AgentAuthConfig>;
+}
+export declare const DEFAULT_TOOL_ROUTER_CONFIG: ToolRouterConfig;
+export declare const BUILTIN_PACKS: ToolPack[];
+export interface ToolSchema {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+export declare class ToolRouter {
+    private static _instance;
+    private config;
+    /** All packs (built-in + custom) keyed by name */
+    private packs;
+    /** Lazy schema cache: toolName → schema */
+    private schemaCache;
+    /** Rate limit state: `${sessionId}:${toolName}` → usage */
+    private usageState;
+    constructor(config?: Partial<ToolRouterConfig>);
+    static getInstance(config?: Partial<ToolRouterConfig>): ToolRouter;
+    static reset(): void;
+    private _loadPacks;
+    private _loadPacksFromDir;
+    /** Persist a custom pack to the packs directory */
+    private _persistPack;
+    private _deletePersisted;
+    listPacks(): ToolPack[];
+    getPack(name: string): ToolPack | undefined;
+    createPack(pack: Omit<ToolPack, 'builtIn'>): ToolPack;
+    updatePack(name: string, updates: Partial<Omit<ToolPack, 'name' | 'builtIn'>>): ToolPack;
+    deletePack(name: string): void;
+    /**
+     * Determine which packs are active for the current request.
+     *
+     * X-Task-Type header format:
+     *   - "code" | "search" | "file-ops"  → named built-in pack
+     *   - "custom:{pack-name}"             → custom pack
+     *   - undefined                        → no packs active (deny all)
+     */
+    resolveActivePacks(taskType?: string, agentId?: string): string[];
+    /**
+     * Check which of the requested tools are allowed given active packs and agent config.
+     * Does NOT enforce rate limits (call checkRateLimit separately).
+     */
+    checkTools(ctx: ToolAuthContext): ToolAuthResult;
+    /**
+     * Resolve the effective policy for every known tool, given the active packs,
+     * agent overrides, and explicit deny list.
+     */
+    private _resolveEffectivePolicies;
+    private _findToolEntry;
+    /**
+     * Check rate limit for a specific tool call.
+     * Updates internal state on success (i.e. calling this IS the "record call" step).
+     */
+    checkRateLimit(sessionId: string, toolName: string, activePacks: string[]): RateLimitCheckResult;
+    /** Reset rate limit state for a session (call on session end) */
+    clearSessionRateLimits(sessionId: string): void;
+    /**
+     * Get the schema for a tool. Only fetches on first call (lazy).
+     * Returns undefined if no schemaRef configured or fetch fails.
+     */
+    getToolSchema(toolName: string, activePacks: string[]): Promise<ToolSchema | undefined>;
+    /** In-memory log of denied tool calls keyed by sessionId */
+    private deniedLog;
+    recordDenied(sessionId: string, toolName: string, reason: string): void;
+    getDeniedForSession(sessionId: string): {
+        toolName: string;
+        ts: number;
+        reason: string;
+    }[];
+    clearDeniedLog(sessionId: string): void;
+    mcpToolPackList(): ToolPack[];
+    mcpToolPackGet(name: string): ToolPack | undefined;
+    mcpToolAuthCheck(ctx: ToolAuthContext): ToolAuthResult;
+    getConfig(): ToolRouterConfig;
+    updateConfig(updates: Partial<ToolRouterConfig>): void;
+}
+export declare function getToolRouter(config?: Partial<ToolRouterConfig>): ToolRouter;
+export declare function resetToolRouter(): void;
+/**
+ * Extract tool routing context from request headers.
+ * Returns activePacks and denyList ready for checkTools().
+ */
+export declare function extractToolContext(headers: Record<string, string | string[] | undefined>, sessionId: string, requestedTools: string[], router?: ToolRouter): ToolAuthContext;
+//# sourceMappingURL=tool-router.d.ts.map

package/dist/tool-router.d.ts.map

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