aegis-bridge 0.1.0

package/dist/validation.d.ts

@@ -0,0 +1,406 @@
+/**
+ * validation.ts — Zod schemas for API request body validation.
+ *
+ * Issue #359: Centralized validation for all POST route bodies.
+ * Issue #435: Path traversal defense in validateWorkDir.
+ */
+import { z } from 'zod';
+/** Regex for UUID v4 format: 8-4-4-4-12 hex digits */
+export declare const UUID_REGEX: RegExp;
+/** POST /v1/auth/keys */
+export declare const authKeySchema: z.ZodObject<{
+    name: z.ZodString;
+    rateLimit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Maximum length for user-supplied prompts/commands (Issue #411). */
+export declare const MAX_INPUT_LENGTH = 10000;
+/** POST /v1/sessions/:id/send */
+export declare const sendMessageSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strict>;
+/** POST /v1/sessions/:id/command */
+export declare const commandSchema: z.ZodObject<{
+    command: z.ZodString;
+}, z.core.$strict>;
+/** POST /v1/sessions/:id/bash */
+export declare const bashSchema: z.ZodObject<{
+    command: z.ZodString;
+}, z.core.$strict>;
+/** POST /v1/sessions/:id/screenshot */
+export declare const screenshotSchema: z.ZodObject<{
+    url: z.ZodString;
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Webhook endpoint — validates structure of each webhook entry */
+export declare const webhookEndpointSchema: z.ZodObject<{
+    url: z.ZodString;
+    events: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** POST /v1/hooks/:eventName — CC hook event payload (Issue #665). */
+export declare const hookBodySchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    agent_name: z.ZodOptional<z.ZodString>;
+    agent_type: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    tool_input: z.ZodOptional<z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    tool_use_id: z.ZodOptional<z.ZodString>;
+    permission_prompt: z.ZodOptional<z.ZodString>;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    hook_event_name: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodString>;
+    stop_reason: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** POST /v1/sessions/:id/hooks/permission */
+export declare const permissionHookSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    tool_input: z.ZodOptional<z.ZodUnknown>;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    hook_event_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** POST /v1/sessions/:id/hooks/stop */
+export declare const stopHookSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    stop_reason: z.ZodOptional<z.ZodString>;
+    hook_event_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** POST /v1/sessions/batch — max 50 sessions per batch */
+export declare const batchSessionSchema: z.ZodObject<{
+    sessions: z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        workDir: z.ZodString;
+        prompt: z.ZodOptional<z.ZodString>;
+        permissionMode: z.ZodOptional<z.ZodEnum<{
+            bypassPermissions: "bypassPermissions";
+            default: "default";
+            plan: "plan";
+            acceptEdits: "acceptEdits";
+            dontAsk: "dontAsk";
+            auto: "auto";
+        }>>;
+        autoApprove: z.ZodOptional<z.ZodBoolean>;
+        stallThresholdMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+/** POST /v1/pipelines */
+export declare const pipelineSchema: z.ZodObject<{
+    name: z.ZodString;
+    workDir: z.ZodString;
+    stages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        workDir: z.ZodOptional<z.ZodString>;
+        prompt: z.ZodString;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        permissionMode: z.ZodOptional<z.ZodEnum<{
+            bypassPermissions: "bypassPermissions";
+            default: "default";
+            plan: "plan";
+            acceptEdits: "acceptEdits";
+            dontAsk: "dontAsk";
+            auto: "auto";
+        }>>;
+        autoApprove: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+/** POST /v1/handshake */
+export declare const handshakeRequestSchema: z.ZodObject<{
+    protocolVersion: z.ZodString;
+    clientCapabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    clientVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Clamp a numeric value to [min, max]. Returns default if input is NaN. */
+export declare function clamp(value: number, min: number, max: number, fallback: number): number;
+/** Parse an env string to integer with NaN/isFinite guard. Returns fallback on failure. */
+export declare function parseIntSafe(value: string | undefined, fallback: number): number;
+/** Validate that a string looks like a UUID. */
+export declare function isValidUUID(id: string): boolean;
+/** Issue #700: Permission Policy Schema */
+export declare const permissionRuleSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        userSettings: "userSettings";
+        projectSettings: "projectSettings";
+        localSettings: "localSettings";
+        flagSettings: "flagSettings";
+        aegisApi: "aegisApi";
+    }>;
+    ruleBehavior: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        ask: "ask";
+    }>;
+    toolName: z.ZodOptional<z.ZodString>;
+    commandPattern: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PermissionPolicy = z.infer<typeof permissionRuleSchema>[];
+/** Issue #742: richer per-session permission profile. */
+export declare const permissionConstraintSchema: z.ZodObject<{
+    readOnly: z.ZodOptional<z.ZodBoolean>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxFileSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const permissionProfileRuleSchema: z.ZodObject<{
+    tool: z.ZodString;
+    behavior: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        ask: "ask";
+    }>;
+    pattern: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodObject<{
+        readOnly: z.ZodOptional<z.ZodBoolean>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxFileSize: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const permissionProfileSchema: z.ZodObject<{
+    defaultBehavior: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+        ask: "ask";
+    }>;
+    rules: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        behavior: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            ask: "ask";
+        }>;
+        pattern: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodObject<{
+            readOnly: z.ZodOptional<z.ZodBoolean>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            maxFileSize: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PermissionProfile = z.infer<typeof permissionProfileSchema>;
+/** Schema for persisted SessionState (sessions: { [id]: SessionInfo }). */
+export declare const persistedStateSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    id: z.ZodString;
+    windowId: z.ZodString;
+    windowName: z.ZodString;
+    workDir: z.ZodString;
+    claudeSessionId: z.ZodOptional<z.ZodString>;
+    jsonlPath: z.ZodOptional<z.ZodString>;
+    byteOffset: z.ZodNumber;
+    monitorOffset: z.ZodNumber;
+    status: z.ZodEnum<{
+        idle: "idle";
+        working: "working";
+        compacting: "compacting";
+        context_warning: "context_warning";
+        waiting_for_input: "waiting_for_input";
+        permission_prompt: "permission_prompt";
+        plan_mode: "plan_mode";
+        ask_question: "ask_question";
+        bash_approval: "bash_approval";
+        settings: "settings";
+        error: "error";
+        unknown: "unknown";
+    }>;
+    createdAt: z.ZodNumber;
+    lastActivity: z.ZodNumber;
+    stallThresholdMs: z.ZodNumber;
+    permissionStallMs: z.ZodDefault<z.ZodNumber>;
+    permissionMode: z.ZodEnum<{
+        bypassPermissions: "bypassPermissions";
+        default: "default";
+        plan: "plan";
+        acceptEdits: "acceptEdits";
+        dontAsk: "dontAsk";
+        auto: "auto";
+    }>;
+    settingsPatched: z.ZodOptional<z.ZodBoolean>;
+    hookSettingsFile: z.ZodOptional<z.ZodString>;
+    lastHookAt: z.ZodOptional<z.ZodNumber>;
+    activeSubagents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    permissionPromptAt: z.ZodOptional<z.ZodNumber>;
+    permissionRespondedAt: z.ZodOptional<z.ZodNumber>;
+    lastHookReceivedAt: z.ZodOptional<z.ZodNumber>;
+    lastHookEventAt: z.ZodOptional<z.ZodNumber>;
+    model: z.ZodOptional<z.ZodString>;
+    lastDeadAt: z.ZodOptional<z.ZodNumber>;
+    ccPid: z.ZodOptional<z.ZodNumber>;
+    parentId: z.ZodOptional<z.ZodString>;
+    children: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    permissionPolicy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source: z.ZodEnum<{
+            userSettings: "userSettings";
+            projectSettings: "projectSettings";
+            localSettings: "localSettings";
+            flagSettings: "flagSettings";
+            aegisApi: "aegisApi";
+        }>;
+        ruleBehavior: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            ask: "ask";
+        }>;
+        toolName: z.ZodOptional<z.ZodString>;
+        commandPattern: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    permissionProfile: z.ZodOptional<z.ZodObject<{
+        defaultBehavior: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            ask: "ask";
+        }>;
+        rules: z.ZodArray<z.ZodObject<{
+            tool: z.ZodString;
+            behavior: z.ZodEnum<{
+                allow: "allow";
+                deny: "deny";
+                ask: "ask";
+            }>;
+            pattern: z.ZodOptional<z.ZodString>;
+            constraints: z.ZodOptional<z.ZodObject<{
+                readOnly: z.ZodOptional<z.ZodBoolean>;
+                paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                maxFileSize: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>>;
+/** Schema for a single continuation pointer entry in session_map.json (Issue #900). */
+export declare const sessionMapEntrySchema: z.ZodObject<{
+    session_id: z.ZodString;
+    cwd: z.ZodString;
+    window_name: z.ZodString;
+    transcript_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    permission_mode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    written_at: z.ZodNumber;
+    schema_version: z.ZodOptional<z.ZodNumber>;
+    expires_at: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Schema for session_map.json entries. */
+export declare const sessionMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    session_id: z.ZodString;
+    cwd: z.ZodString;
+    window_name: z.ZodString;
+    transcript_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    permission_mode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    agent_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    written_at: z.ZodNumber;
+    schema_version: z.ZodOptional<z.ZodNumber>;
+    expires_at: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+/** Incoming Stop/StopFailure hook payload (Issue #515). */
+export declare const stopPayloadSchema: z.ZodObject<{
+    error: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    error_details: z.ZodOptional<z.ZodUnknown>;
+    last_assistant_message: z.ZodOptional<z.ZodUnknown>;
+    agent_id: z.ZodOptional<z.ZodString>;
+    stop_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** Schema for stop_signals.json entries. */
+export declare const stopSignalsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    event: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodUnknown>;
+    error_details: z.ZodOptional<z.ZodUnknown>;
+    last_assistant_message: z.ZodOptional<z.ZodUnknown>;
+    agent_id: z.ZodOptional<z.ZodUnknown>;
+    stop_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/** Schema for persisted auth keys store (Issue #506). */
+export declare const authStoreSchema: z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        hash: z.ZodString;
+        createdAt: z.ZodNumber;
+        lastUsedAt: z.ZodNumber;
+        rateLimit: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Schema for sessions-index.json entries (Issue #506). */
+export declare const sessionsIndexSchema: z.ZodObject<{
+    entries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        sessionId: z.ZodString;
+        fullPath: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Schema for persisted metrics file (Issue #506). */
+export declare const metricsFileSchema: z.ZodObject<{
+    global: z.ZodOptional<z.ZodObject<{
+        sessionsCreated: z.ZodOptional<z.ZodNumber>;
+        sessionsCompleted: z.ZodOptional<z.ZodNumber>;
+        sessionsFailed: z.ZodOptional<z.ZodNumber>;
+        totalMessages: z.ZodOptional<z.ZodNumber>;
+        totalToolCalls: z.ZodOptional<z.ZodNumber>;
+        autoApprovals: z.ZodOptional<z.ZodNumber>;
+        webhooksSent: z.ZodOptional<z.ZodNumber>;
+        webhooksFailed: z.ZodOptional<z.ZodNumber>;
+        screenshotsTaken: z.ZodOptional<z.ZodNumber>;
+        pipelinesCreated: z.ZodOptional<z.ZodNumber>;
+        batchesCreated: z.ZodOptional<z.ZodNumber>;
+        promptsSent: z.ZodOptional<z.ZodNumber>;
+        promptsDelivered: z.ZodOptional<z.ZodNumber>;
+        promptsFailed: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    savedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+/** Schema for WebSocket inbound messages (Issue #506). */
+export declare const wsInboundMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"input">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"resize">;
+    cols: z.ZodOptional<z.ZodNumber>;
+    rows: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"auth">;
+    token: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+/** Schema for CC settings.json shape (Issue #506).
+ *  Permissive — only validates the fields Aegis cares about. */
+export declare const ccSettingsSchema: z.ZodObject<{
+    permissions: z.ZodOptional<z.ZodObject<{
+        defaultMode: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** Helper: extract error message from unknown catch value. */
+export declare function getErrorMessage(e: unknown): string;
+/** Minimum supported Claude Code version. */
+export declare const MIN_CC_VERSION = "2.1.80";
+/** Parse a semver string into [major, minor, patch], or null if invalid. */
+export declare function parseSemver(v: string): [number, number, number] | null;
+/**
+ * Compare two semver strings.
+ * Returns -1 if a < b, 0 if equal or either is unparseable (fails open), 1 if a > b.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/** Extract version number from `claude --version` output. */
+export declare function extractCCVersion(output: string): string | null;
+/** Returns true when any path segment resolves to "..".
+ *  Checks raw, separator-normalized, and percent-decoded forms to catch
+ *  encoded traversal like %2e%2e and mixed slash/backslash payloads. */
+export declare function containsTraversalSegment(inputPath: string): boolean;
+/** Validate workDir to prevent path traversal attacks (Issue #435).
+ *  1. Reject raw strings containing ".." before any normalization.
+ *  2. Resolve to absolute path and resolve symlinks via fs.realpath().
+ *  3. Verify the resolved path is under an allowed directory:
+ *     - If allowedWorkDirs is configured, use that list.
+ *     - Otherwise, use default safe dirs (home, /tmp, cwd).
+ *  Returns the resolved real path on success, or an error object on failure. */
+export declare function validateWorkDir(workDir: string, allowedWorkDirs?: readonly string[]): Promise<string | {
+    error: string;
+    code: string;
+}>;