@exfil/canary 1.0.0

package/dist/persistence.js

@@ -0,0 +1,296 @@
+/**
+ * State persistence — atomic writes, 0o600 file mode, no sequence storage.
+ *
+ * SECURITY (RC-1): The `sequence` field is intentionally omitted from the
+ * persisted representation.  After a server restart, existing token metadata
+ * (ID, expiry, leakage history) is recovered, but the invisible Unicode
+ * payload is lost.  Tokens recovered from disk cannot re-detect their
+ * embedded sequence in new data; they are useful only for historical
+ * reporting.  This is a known limitation — see SECURITY.md.
+ *
+ * SECURITY (RC-7): All recovered records are validated through manual type
+ * guards.  Invalid records are discarded with a warning; the server never
+ * throws on malformed persistence data.
+ */
+import { promises as fs } from 'fs';
+import { isValidTokenId } from './scanner.js';
+import { log } from './logger.js';
+const CURRENT_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Persistence entry point
+// ---------------------------------------------------------------------------
+/**
+ * Atomically persists session state to disk (sequence field omitted).
+ *
+ * Writes to a `.tmp` sibling file first, then renames to the target path
+ * so the on-disk file is never observed in a partial state.  File mode is
+ * set to 0o600 (owner read/write only).
+ *
+ * @param state   Current session state.
+ * @param config  Server configuration (provides `persist_path`).
+ */
+export async function persistState(state, config) {
+    if (!config.persist_path)
+        return;
+    const persistedTokens = [];
+    for (const token of state.tokens.values()) {
+        // RC-1: sequence intentionally excluded.
+        // v1.1: entity values intentionally excluded — same RC-1 treatment.
+        const persistedEntities = token.entity_canaries.map((ec) => ({
+            entity_type: ec.entity_type,
+            context_hint: ec.context_hint,
+        }));
+        persistedTokens.push({
+            token_id: token.token_id,
+            source_type: token.source_type,
+            source_server: token.source_server,
+            source_tool: token.source_tool,
+            source_call_id: token.source_call_id,
+            embed_position: token.embed_position,
+            created_at: token.created_at,
+            expires_at: token.expires_at,
+            leaked: token.leaked,
+            leakage_event_ids: [...token.leakage_event_ids],
+            entity_canaries: persistedEntities,
+        });
+    }
+    const leakageEvents = [...state.leakage_events.values()];
+    const payload = {
+        version: CURRENT_VERSION,
+        session_id: state.session_id,
+        created_at: state.created_at,
+        token_counter: state.token_counter,
+        tokens: persistedTokens,
+        leakage_events: leakageEvents,
+    };
+    const json = JSON.stringify(payload, null, 2);
+    const tmpPath = config.persist_path + '.tmp';
+    try {
+        await fs.writeFile(tmpPath, json, { encoding: 'utf8', mode: 0o600 });
+        // chmod the tmp file BEFORE rename so the secure mode is set atomically —
+        // there is no window where the target file exists with looser permissions.
+        await fs.chmod(tmpPath, 0o600);
+        await fs.rename(tmpPath, config.persist_path);
+    }
+    catch (err) {
+        log('warn', `Persistence write failed: ${err.message}`);
+        // Clean up orphaned tmp file if rename failed.
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Attempts to recover session state from the persistence file.
+ *
+ * Returns `null` when:
+ * - No path is configured.
+ * - The file does not exist.
+ * - Top-level validation fails (the whole file is malformed).
+ *
+ * Individual token or event records that fail validation are discarded with
+ * a warning rather than crashing the server (RC-7).
+ *
+ * @param config  Server configuration.
+ * @returns Recovered `SessionState`, or `null` to start fresh.
+ */
+export async function recoverState(config) {
+    if (!config.persist_path)
+        return null;
+    let raw;
+    try {
+        const json = await fs.readFile(config.persist_path, 'utf8');
+        raw = JSON.parse(json);
+    }
+    catch (err) {
+        const msg = err.code === 'ENOENT'
+            ? 'No persistence file found — starting fresh.'
+            : `Failed to read/parse persistence file: ${err.message}`;
+        log('info', msg);
+        return null;
+    }
+    if (!validatePersistedState(raw)) {
+        log('warn', 'Persistence file failed top-level validation — starting fresh.');
+        return null;
+    }
+    const persisted = raw;
+    const state = {
+        session_id: persisted.session_id,
+        created_at: persisted.created_at,
+        tokens: new Map(),
+        leakage_events: new Map(),
+        token_counter: persisted.token_counter,
+    };
+    let skippedTokens = 0;
+    for (const raw_token of persisted.tokens) {
+        if (!validatePersistedToken(raw_token)) {
+            skippedTokens += 1;
+            continue;
+        }
+        // Recovered tokens have no sequence or entity values — cannot re-detect.
+        const token = {
+            token_id: raw_token.token_id,
+            sequence: '', // RC-1: sequence not stored; cannot re-detect.
+            source_type: raw_token.source_type,
+            source_server: raw_token.source_server,
+            source_tool: raw_token.source_tool,
+            source_call_id: raw_token.source_call_id,
+            embed_position: raw_token.embed_position,
+            created_at: raw_token.created_at,
+            expires_at: raw_token.expires_at,
+            leaked: raw_token.leaked,
+            leakage_event_ids: [...raw_token.leakage_event_ids],
+            // v1.1: values not stored; null signals "cannot re-detect after restart".
+            entity_canaries: (raw_token.entity_canaries ?? []).map((pe) => ({
+                entity_type: pe.entity_type,
+                value: null, // RC-1: not stored; cannot re-detect after restart
+                context_hint: pe.context_hint,
+            })),
+            simhash: null, // v1.6: not stored; cannot fingerprint after restart
+        };
+        state.tokens.set(token.token_id, token);
+    }
+    let skippedEvents = 0;
+    for (const raw_event of persisted.leakage_events) {
+        if (!validateLeakageEvent(raw_event)) {
+            skippedEvents += 1;
+            continue;
+        }
+        state.leakage_events.set(raw_event.event_id, raw_event);
+    }
+    if (skippedTokens > 0 || skippedEvents > 0) {
+        log('warn', `State recovery: discarded ${skippedTokens} invalid token(s) and ${skippedEvents} invalid event(s).`);
+    }
+    log('info', `Recovered ${state.tokens.size} token(s) and ${state.leakage_events.size} event(s) from persistence.`);
+    return state;
+}
+// ---------------------------------------------------------------------------
+// Runtime type guards (RC-7)
+// ---------------------------------------------------------------------------
+const SOURCE_TYPES = new Set([
+    'tool_result', 'file_read', 'api_response', 'database_row', 'user_message', 'other',
+]);
+const EMBED_POSITIONS = new Set([
+    'prefix', 'suffix', 'both', 'random_word_boundary',
+]);
+const DETECTION_METHODS = new Set(['check_leakage', 'scan_outbound']);
+const ACTIONS_TAKEN = new Set(['logged', 'halted', 'alerted', 'none']);
+function isString(v) {
+    return typeof v === 'string';
+}
+function isNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+function isBoolean(v) {
+    return typeof v === 'boolean';
+}
+function isObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function isArray(v) {
+    return Array.isArray(v);
+}
+function isStringArray(v) {
+    return isArray(v) && v.every(isString);
+}
+/**
+ * Top-level validation of the raw parsed JSON from the persistence file.
+ *
+ * @param raw  Parsed JSON value.
+ */
+export function validatePersistedState(raw) {
+    if (!isObject(raw))
+        return false;
+    if (raw['version'] !== CURRENT_VERSION)
+        return false;
+    if (!isString(raw['session_id']) || !isValidTokenId(raw['session_id']))
+        return false;
+    if (!isNumber(raw['created_at']) || raw['created_at'] <= 0)
+        return false;
+    if (!isNumber(raw['token_counter']) || raw['token_counter'] < 0)
+        return false;
+    if (!isArray(raw['tokens']))
+        return false;
+    if (!isArray(raw['leakage_events']))
+        return false;
+    return true;
+}
+/**
+ * Validates a single persisted token record (RC-7).
+ *
+ * @param raw  Candidate token object.
+ */
+function validatePersistedToken(raw) {
+    if (!isObject(raw))
+        return false;
+    if (!isString(raw['token_id']) || !isValidTokenId(raw['token_id']))
+        return false;
+    if (!isString(raw['source_type']) || !SOURCE_TYPES.has(raw['source_type']))
+        return false;
+    if (!isString(raw['embed_position']) || !EMBED_POSITIONS.has(raw['embed_position']))
+        return false;
+    if (!isNumber(raw['created_at']) || raw['created_at'] <= 0)
+        return false;
+    if (!isNumber(raw['expires_at']) || raw['expires_at'] <= 0)
+        return false;
+    if (!isBoolean(raw['leaked']))
+        return false;
+    if (!isStringArray(raw['leakage_event_ids']))
+        return false;
+    // Optional string fields
+    if ('source_server' in raw && raw['source_server'] !== undefined && !isString(raw['source_server']))
+        return false;
+    if ('source_tool' in raw && raw['source_tool'] !== undefined && !isString(raw['source_tool']))
+        return false;
+    if ('source_call_id' in raw && raw['source_call_id'] !== undefined && !isString(raw['source_call_id']))
+        return false;
+    // v1.1: entity_canaries is optional (absent in files written by v1.0)
+    if ('entity_canaries' in raw && raw['entity_canaries'] !== undefined) {
+        if (!isArray(raw['entity_canaries']))
+            return false;
+        for (const ec of raw['entity_canaries']) {
+            if (!isObject(ec))
+                return false;
+            if (!isString(ec['entity_type']))
+                return false;
+            if (!isString(ec['context_hint']))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Validates a single leakage event record (RC-7).
+ *
+ * @param raw  Candidate event object.
+ */
+function validateLeakageEvent(raw) {
+    if (!isObject(raw))
+        return false;
+    if (!isString(raw['event_id']) || !isValidTokenId(raw['event_id']))
+        return false;
+    if (!isString(raw['token_id']) || !isValidTokenId(raw['token_id']))
+        return false;
+    if (!isNumber(raw['detected_at']) || raw['detected_at'] <= 0)
+        return false;
+    if (!isString(raw['detection_method']) || !DETECTION_METHODS.has(raw['detection_method']))
+        return false;
+    if (!isString(raw['action_taken']) || !ACTIONS_TAKEN.has(raw['action_taken']))
+        return false;
+    if (!isBoolean(raw['webhook_attempted']))
+        return false;
+    if (raw['webhook_delivered'] !== null && !isBoolean(raw['webhook_delivered']))
+        return false;
+    // Optional string fields
+    if ('target_server' in raw && raw['target_server'] !== undefined && !isString(raw['target_server']))
+        return false;
+    if ('target_tool' in raw && raw['target_tool'] !== undefined && !isString(raw['target_tool']))
+        return false;
+    if ('target_call_id' in raw && raw['target_call_id'] !== undefined && !isString(raw['target_call_id']))
+        return false;
+    if ('turn_number' in raw && raw['turn_number'] !== undefined && !isNumber(raw['turn_number']))
+        return false;
+    return true;
+}
+//# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

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

package/dist/proxy/DownstreamManager.d.ts

@@ -0,0 +1,55 @@
+/**
+ * DownstreamManager — connects to and manages all downstream MCP servers.
+ *
+ * Each downstream server is spawned as a subprocess via StdioClientTransport.
+ * Tools from every server are aggregated and namespaced as `{server_id}__{tool_name}`
+ * so the agent sees a flat, unambiguous tool list even when multiple servers
+ * expose tools with the same name.
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ProxyConfig } from './types.js';
+/** A resolved tool entry: the namespaced name, original name, and owning server. */
+export interface DownstreamTool {
+    /** Namespaced name exposed to the agent: `{server_id}__{original_name}`. */
+    namespaced_name: string;
+    /** Original tool name on the downstream server. */
+    original_name: string;
+    /** Server that owns this tool. */
+    server_id: string;
+    /** Full SDK Tool definition with the namespaced name substituted in. */
+    tool: Tool;
+}
+export declare class DownstreamManager {
+    private servers;
+    /**
+     * Connects to every downstream server listed in `proxyConfig`.
+     * Failures on individual servers are logged but do not abort the others.
+     */
+    connect(proxyConfig: ProxyConfig): Promise<void>;
+    private connectOne;
+    /** Returns all namespaced tools across all connected downstream servers. */
+    listAllTools(): DownstreamTool[];
+    /**
+     * Looks up which server and original tool name correspond to a namespaced name.
+     * Returns null if not found.
+     */
+    resolveTool(namespacedName: string): {
+        server_id: string;
+        original_name: string;
+    } | null;
+    /**
+     * Forwards a tool call to the appropriate downstream server.
+     *
+     * @param server_id     The downstream server id.
+     * @param original_name The original (non-namespaced) tool name.
+     * @param args          Arguments to forward.
+     * @returns The raw SDK response.
+     */
+    callTool(server_id: string, original_name: string, args: Record<string, unknown>): Promise<{
+        content: unknown[];
+        isError?: boolean;
+    }>;
+    /** Disconnects all downstream clients. */
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=DownstreamManager.d.ts.map

package/dist/proxy/DownstreamManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DownstreamManager.d.ts","sourceRoot":"","sources":["../../src/proxy/DownstreamManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,KAAK,EAA0B,WAAW,EAAE,MAAM,YAAY,CAAC;AAGtE,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,IAAI,EAAE,IAAI,CAAC;CACZ;AASD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAkC;IAEjD;;;OAGG;IACG,OAAO,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;YAOxC,UAAU;IA+CxB,4EAA4E;IAC5E,YAAY,IAAI,cAAc,EAAE;IAQhC;;;OAGG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAQxF;;;;;;;OAOG;IACG,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IASrD,0CAA0C;IACpC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAWlC"}

package/dist/proxy/DownstreamManager.js

@@ -0,0 +1,110 @@
+/**
+ * DownstreamManager — connects to and manages all downstream MCP servers.
+ *
+ * Each downstream server is spawned as a subprocess via StdioClientTransport.
+ * Tools from every server are aggregated and namespaced as `{server_id}__{tool_name}`
+ * so the agent sees a flat, unambiguous tool list even when multiple servers
+ * expose tools with the same name.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { log } from '../logger.js';
+export class DownstreamManager {
+    servers = new Map();
+    /**
+     * Connects to every downstream server listed in `proxyConfig`.
+     * Failures on individual servers are logged but do not abort the others.
+     */
+    async connect(proxyConfig) {
+        for (const serverConfig of proxyConfig.servers) {
+            await this.connectOne(serverConfig);
+        }
+        log('info', `DownstreamManager: connected to ${this.servers.size}/${proxyConfig.servers.length} server(s).`);
+    }
+    async connectOne(serverConfig) {
+        const { id, command, args = [], env } = serverConfig;
+        if (!/^[a-z][a-z0-9_-]*$/.test(id)) {
+            throw new Error(`Downstream server id "${id}" is invalid. ` +
+                'Must match /^[a-z][a-z0-9_-]*$/ (lowercase, start with a letter, no spaces).');
+        }
+        const transport = new StdioClientTransport({
+            command,
+            args,
+            env: env ? { ...process.env, ...env } : undefined,
+        });
+        const client = new Client({ name: 'exfil/canary-proxy', version: '1.0.0' }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+        }
+        catch (err) {
+            log('warn', `DownstreamManager: failed to connect to "${id}": ${err.message}`);
+            return;
+        }
+        let sdkTools = [];
+        try {
+            const response = await client.listTools();
+            sdkTools = response.tools ?? [];
+        }
+        catch (err) {
+            log('warn', `DownstreamManager: listTools failed for "${id}": ${err.message}`);
+        }
+        const tools = sdkTools.map((t) => ({
+            namespaced_name: `${id}__${t.name}`,
+            original_name: t.name,
+            server_id: id,
+            tool: { ...t, name: `${id}__${t.name}` },
+        }));
+        this.servers.set(id, { config: serverConfig, client, tools });
+        log('info', `DownstreamManager: "${id}" ready — ${tools.length} tool(s).`);
+    }
+    /** Returns all namespaced tools across all connected downstream servers. */
+    listAllTools() {
+        const all = [];
+        for (const entry of this.servers.values()) {
+            all.push(...entry.tools);
+        }
+        return all;
+    }
+    /**
+     * Looks up which server and original tool name correspond to a namespaced name.
+     * Returns null if not found.
+     */
+    resolveTool(namespacedName) {
+        for (const [server_id, entry] of this.servers.entries()) {
+            const dt = entry.tools.find((t) => t.namespaced_name === namespacedName);
+            if (dt)
+                return { server_id, original_name: dt.original_name };
+        }
+        return null;
+    }
+    /**
+     * Forwards a tool call to the appropriate downstream server.
+     *
+     * @param server_id     The downstream server id.
+     * @param original_name The original (non-namespaced) tool name.
+     * @param args          Arguments to forward.
+     * @returns The raw SDK response.
+     */
+    async callTool(server_id, original_name, args) {
+        const entry = this.servers.get(server_id);
+        if (!entry) {
+            throw new Error(`No connected downstream server with id "${server_id}".`);
+        }
+        const result = await entry.client.callTool({ name: original_name, arguments: args });
+        return result;
+    }
+    /** Disconnects all downstream clients. */
+    async disconnect() {
+        for (const [id, entry] of this.servers.entries()) {
+            try {
+                await entry.client.close();
+                log('debug', `DownstreamManager: closed "${id}".`);
+            }
+            catch (err) {
+                log('warn', `DownstreamManager: error closing "${id}": ${err.message}`);
+            }
+        }
+        this.servers.clear();
+    }
+}
+//# sourceMappingURL=DownstreamManager.js.map

package/dist/proxy/DownstreamManager.js.map

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

package/dist/proxy/ProxyServer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ProxyServer — transparent canary-token proxy for MCP tool calls.
+ *
+ * The agent connects to ProxyServer as its only MCP server.  ProxyServer:
+ *
+ *   1. Aggregates all tools from downstream servers (namespaced as `{id}__{tool}`).
+ *   2. On every tool call:
+ *      a. Serialises the arguments and scans for active canary sequences.
+ *         → Blocks (or logs/alerts) if a token is found in outbound args.
+ *      b. Forwards the call to the downstream server.
+ *      c. Walks the response, wrapping every text string ≥ MIN_WRAP_CHARS
+ *         with a freshly generated canary token registered in session state.
+ *   3. Exposes a single built-in tool `canary__get_report` for operator use.
+ *
+ * The agent never needs to explicitly call wrap_content or scan_outbound —
+ * interception happens transparently on every I/O crossing.
+ */
+import type { CanaryConfig, SessionState } from '../types.js';
+import type { ProxyConfig } from './types.js';
+export declare class ProxyServer {
+    private readonly upstream;
+    private readonly downstream;
+    private readonly config;
+    private state;
+    /** Accumulated tool results for auditor context (ring-buffered to 50). */
+    private storedResults;
+    private resultCounter;
+    /** Dual-auditor instance, or null if not configured. */
+    private readonly auditor;
+    /** Number of detections made by the LLM auditor layer (for report). */
+    private auditorDetections;
+    constructor(state: SessionState, config: CanaryConfig, proxyConfig: ProxyConfig);
+    private _proxyConfig;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    sweepExpiredTokens(): void;
+    private registerHandlers;
+    /**
+     * Scans serialised tool arguments for any active canary tokens.
+     * Fires resolveAction (which may throw McpError to halt) if a token is found.
+     */
+    private scanInboundArgs;
+    /**
+     * Walks the content array from a downstream response.
+     * For every text item with ≥ MIN_WRAP_CHARS characters, embeds a new
+     * canary token and registers it in session state.
+     *
+     * Non-text content (images, etc.) is passed through unchanged.
+     */
+    private wrapResponseContent;
+    private handleGetReport;
+    /**
+     * Fires response_mode action for an auditor DERIVED verdict.
+     * Unlike resolveAction, there may be no specific token_id — the auditor
+     * detected derived content without matching a canary marker.
+     */
+    private resolveAuditorAction;
+    private resolveAction;
+}
+//# sourceMappingURL=ProxyServer.d.ts.map

package/dist/proxy/ProxyServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyServer.d.ts","sourceRoot":"","sources":["../../src/proxy/ProxyServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AAkB3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgF9C,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,KAAK,CAAe;IAC5B,0EAA0E;IAC1E,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,aAAa,CAAK;IAC1B,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,uEAAuE;IACvE,OAAO,CAAC,iBAAiB,CAAK;gBAElB,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW;IAyB/E,OAAO,CAAC,YAAY,CAAc;IAM5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAO/B,kBAAkB,IAAI,IAAI;IAY1B,OAAO,CAAC,gBAAgB;IAoFxB;;;OAGG;YACW,eAAe;IAgH7B;;;;;;OAMG;YACW,mBAAmB;IAgEjC,OAAO,CAAC,eAAe;IAgEvB;;;;OAIG;YACW,oBAAoB;YAiCpB,aAAa;CAkC5B"}