@exfil/canary 1.0.0

package/dist/entities.js

@@ -0,0 +1,218 @@
+/**
+ * v1.1 — Named entity extraction for structural canary injection.
+ *
+ * Extracts identifiable values from content at wrap time and stores them as
+ * EntityCanary records alongside the Unicode sequence marker.  When scanning
+ * outbound data, exfil/canary checks for the presence of these extracted values
+ * in addition to the Unicode marker — catching exfiltration that involves
+ * paraphrasing or rewriting, as long as the underlying identifier (e.g. an
+ * API key, email address, or UUID) is reproduced verbatim.
+ *
+ * SECURITY: Extracted values are treated with the same sensitivity as the
+ * Unicode sequence — they are never returned in tool outputs, never logged,
+ * and never persisted in plaintext.
+ *
+ * Detection coverage added by v1.1 vs v1.0:
+ *   - Agent reads "API key: sk-abc123" and writes "key=sk-abc123" → DETECTED
+ *   - Agent reads email content and includes recipient addr in forward → DETECTED
+ *   - Raw copy-paste / direct forwarding                             → DETECTED (v1.0)
+ *   - Agent summarises with different phrasing, no literal value     → NOT detected (v2.0)
+ */
+// ---------------------------------------------------------------------------
+// Shannon entropy (used to filter high-entropy strings)
+// ---------------------------------------------------------------------------
+/**
+ * Computes the Shannon entropy of a string in bits per character.
+ * A random 32-char hex string has entropy ≈ 4.0. English prose ≈ 2.5–3.0.
+ */
+function shannonEntropy(s) {
+    const freq = new Map();
+    for (const ch of s) {
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    }
+    let entropy = 0;
+    for (const count of freq.values()) {
+        const p = count / s.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+/** Returns true if the string looks like a secret (entropy ≥ 3.5 bits/char). */
+function isHighEntropy(s) {
+    return shannonEntropy(s) >= 3.5;
+}
+/**
+ * Patterns ordered from most-specific (lowest false positive rate) to
+ * least-specific.  Processing stops adding an entity once it has been seen.
+ */
+const PATTERNS = [
+    // ── API keys — well-known vendor formats ────────────────────────────────
+    // OpenAI
+    { type: 'api_key', pattern: /sk-proj-[A-Za-z0-9_-]{40,}/g },
+    { type: 'api_key', pattern: /sk-[A-Za-z0-9]{20,}/g },
+    // Anthropic
+    { type: 'api_key', pattern: /sk-ant-[A-Za-z0-9_-]{30,}/g },
+    // GitHub
+    { type: 'api_key', pattern: /ghp_[A-Za-z0-9]{36}/g },
+    { type: 'api_key', pattern: /github_pat_[A-Za-z0-9_]{82}/g },
+    // GitLab
+    { type: 'api_key', pattern: /glpat-[A-Za-z0-9_-]{20,}/g },
+    // Slack
+    { type: 'api_key', pattern: /xox[baprs]-[0-9A-Za-z-]{10,}/g },
+    // AWS access key ID
+    { type: 'api_key', pattern: /(?:AKIA|ASIA)[0-9A-Z]{16}/g },
+    // Stripe
+    { type: 'api_key', pattern: /(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{24,}/g },
+    // npm
+    { type: 'api_key', pattern: /npm_[A-Za-z0-9]{36}/g },
+    // Twilio
+    { type: 'api_key', pattern: /SK[0-9a-f]{32}/g },
+    // SendGrid
+    { type: 'api_key', pattern: /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/g },
+    // ── Bearer tokens ────────────────────────────────────────────────────────
+    {
+        type: 'bearer_token',
+        pattern: /Bearer\s+([-A-Za-z0-9._~+/=]{20,})/g,
+        useGroup: true,
+        validate: isHighEntropy,
+    },
+    // ── Credential assignment patterns ───────────────────────────────────────
+    // Matches: password=X, api_key=X, secret=X, token=X, auth=X, key=X
+    // Also JSON: "password": "X"
+    {
+        type: 'credential_pair',
+        pattern: /(?:password|passwd|api[_-]?key|secret|token|auth(?:_token)?|access[_-]?key)\s*[=:]\s*["']?([A-Za-z0-9!@#$%^&*()_+\-=\[\]{};':"\\|,.<>/?`~]{8,})["']?/gi,
+        useGroup: true,
+        validate: isHighEntropy,
+    },
+    // ── Email addresses ──────────────────────────────────────────────────────
+    {
+        type: 'email',
+        pattern: /[A-Za-z0-9._%+-]+@[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?\.[A-Za-z]{2,}/g,
+        minLength: 6,
+    },
+    // ── URLs ─────────────────────────────────────────────────────────────────
+    // Only capture URLs ≥ 20 chars to avoid short/common ones like http://x.com
+    {
+        type: 'url',
+        pattern: /https?:\/\/[^\s"'<>\]){,}]{20,}/g,
+        minLength: 20,
+    },
+    // ── IP addresses ─────────────────────────────────────────────────────────
+    {
+        type: 'ip_address',
+        // Strict: each octet 0-255
+        pattern: /\b(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)){3}\b/g,
+        minLength: 7,
+        // Ignore loopback and link-local — not sensitive
+        validate: (v) => !v.startsWith('127.') &&
+            !v.startsWith('169.254.') &&
+            v !== '0.0.0.0' &&
+            v !== '255.255.255.255',
+    },
+    // ── UUIDs ────────────────────────────────────────────────────────────────
+    {
+        type: 'uuid',
+        pattern: /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi,
+        minLength: 36,
+    },
+    // ── High-entropy strings ─────────────────────────────────────────────────
+    // Long hex runs (hashes, raw keys)
+    {
+        type: 'high_entropy_string',
+        pattern: /\b[0-9a-f]{32,}\b/g,
+        validate: isHighEntropy,
+    },
+    // Base64-like strings (JWT segments, encoded tokens)
+    {
+        type: 'high_entropy_string',
+        pattern: /[A-Za-z0-9+/]{40,}={0,2}/g,
+        validate: isHighEntropy,
+    },
+];
+// ---------------------------------------------------------------------------
+// Context window
+// ---------------------------------------------------------------------------
+/** Characters of surrounding text to keep in the context hint. */
+const CONTEXT_WINDOW = 24;
+function buildContextHint(content, matchStart, value) {
+    const start = Math.max(0, matchStart - CONTEXT_WINDOW);
+    const end = Math.min(content.length, matchStart + value.length + CONTEXT_WINDOW);
+    const snippet = content.slice(start, end);
+    // Use index-based replacement so we always redact the correct occurrence,
+    // even if the same value appears elsewhere in the snippet.
+    const valueOffset = matchStart - start;
+    return (snippet.slice(0, valueOffset) +
+        '[ENTITY]' +
+        snippet.slice(valueOffset + value.length));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Extracts named entities from `content` for use as structural canary markers.
+ *
+ * Each unique entity value is returned at most once, even if it appears
+ * multiple times in the content.  Values are de-duplicated case-sensitively
+ * for exact matching.
+ *
+ * @param content  The raw content to analyse (before embedding the Unicode token).
+ * @returns Array of EntityCanary records.  May be empty if no entities found.
+ */
+export function extractEntities(content) {
+    const results = [];
+    const seen = new Set();
+    for (const desc of PATTERNS) {
+        const { type, pattern, useGroup, validate, minLength = 8 } = desc;
+        // Reset the global regex's lastIndex before each use.
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            // For patterns that capture the secret in group 1, prefer group 1.
+            const raw = useGroup ? (match[1] ?? match[0]) : match[0];
+            // Trim surrounding whitespace/quotes that may have bled in.
+            const value = raw.trimEnd().replace(/^["'\s]+|["'\s]+$/g, '');
+            if (value.length < minLength)
+                continue;
+            if (validate && !validate(value))
+                continue;
+            if (seen.has(value))
+                continue;
+            seen.add(value);
+            // Compute the match start position in the original string.
+            // When useGroup, the capture group starts after any prefix in group 0.
+            const groupOffset = useGroup
+                ? match[0].indexOf(raw)
+                : 0;
+            const matchStart = match.index + groupOffset;
+            results.push({
+                entity_type: type,
+                value,
+                context_hint: buildContextHint(content, matchStart, value),
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Checks whether any of the provided entity values appear in `data`.
+ * Returns the matching entity canaries (values excluded from returned objects
+ * — callers receive entity_type + context_hint only when building reports).
+ *
+ * @param data      The outbound string to scan.
+ * @param canaries  Entity canaries to check for.
+ * @returns Array of matched canaries (values intact for internal use only).
+ */
+export function scanForEntityValues(data, canaries) {
+    const matches = [];
+    for (const canary of canaries) {
+        // Empty value = recovered from persistence, cannot re-detect.
+        if (!canary.value)
+            continue;
+        if (data.includes(canary.value)) {
+            matches.push(canary);
+        }
+    }
+    return matches;
+}
+//# sourceMappingURL=entities.js.map

package/dist/entities.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * exfil/canary entry point.
+ *
+ * Responsibilities:
+ *  1. Read and validate all environment variables (fast-fail on bad config).
+ *  2. Attempt state recovery from persistence file.
+ *  3. Construct and start the CanaryMcpServer.
+ *  4. Register SIGTERM / SIGINT handlers for graceful shutdown.
+ *  5. Start a 60-second expiry sweep interval (unref'd so it does not keep
+ *     the Node process alive past the server lifecycle).
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}

package/dist/index.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * exfil/canary entry point.
+ *
+ * Responsibilities:
+ *  1. Read and validate all environment variables (fast-fail on bad config).
+ *  2. Attempt state recovery from persistence file.
+ *  3. Construct and start the CanaryMcpServer.
+ *  4. Register SIGTERM / SIGINT handlers for graceful shutdown.
+ *  5. Start a 60-second expiry sweep interval (unref'd so it does not keep
+ *     the Node process alive past the server lifecycle).
+ */
+import { readFileSync } from 'fs';
+import { validateWebhookUrl } from './server.js';
+import { CanaryMcpServer } from './server.js';
+import { recoverState } from './persistence.js';
+import { createSession } from './state.js';
+import { setLogLevel, log } from './logger.js';
+import { ProxyServer } from './proxy/ProxyServer.js';
+// ---------------------------------------------------------------------------
+// Environment variable parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parses and validates all environment variables.
+ * Throws a descriptive error on any misconfiguration (fast-fail, RC-2).
+ *
+ * @returns Validated `CanaryConfig`.
+ */
+function loadConfig() {
+    // Log level — set early so subsequent validation errors are visible.
+    const rawLogLevel = process.env['CANARY_MCP_LOG_LEVEL'] ?? 'info';
+    const validLogLevels = ['debug', 'info', 'warn', 'error'];
+    if (!validLogLevels.includes(rawLogLevel)) {
+        throw new Error(`CANARY_MCP_LOG_LEVEL must be one of ${validLogLevels.join(', ')} — got "${rawLogLevel}"`);
+    }
+    const log_level = rawLogLevel;
+    setLogLevel(log_level);
+    // Token TTL.
+    const rawTtl = process.env['CANARY_MCP_TOKEN_TTL'] ?? '3600';
+    const token_ttl_seconds = parseInt(rawTtl, 10);
+    if (!Number.isInteger(token_ttl_seconds) || token_ttl_seconds < 60 || token_ttl_seconds > 86400) {
+        throw new Error(`CANARY_MCP_TOKEN_TTL must be an integer between 60 and 86400 — got "${rawTtl}"`);
+    }
+    // Response mode.
+    const rawMode = process.env['CANARY_MCP_RESPONSE_MODE'] ?? 'log';
+    const validModes = ['log', 'halt', 'alert'];
+    if (!validModes.includes(rawMode)) {
+        throw new Error(`CANARY_MCP_RESPONSE_MODE must be one of ${validModes.join(', ')} — got "${rawMode}"`);
+    }
+    const response_mode = rawMode;
+    // Webhook URL (RC-6: HTTPS-only + SSRF check at startup).
+    const rawWebhook = process.env['CANARY_MCP_ALERT_WEBHOOK'];
+    let alert_webhook = null;
+    if (rawWebhook) {
+        alert_webhook = validateWebhookUrl(rawWebhook); // throws on invalid
+    }
+    if (response_mode === 'alert' && !alert_webhook) {
+        throw new Error('CANARY_MCP_RESPONSE_MODE is "alert" but CANARY_MCP_ALERT_WEBHOOK is not set.');
+    }
+    // Webhook secret (optional).
+    const webhook_secret = process.env['CANARY_MCP_WEBHOOK_SECRET'] ?? null;
+    // Persistence path (optional).
+    const persist_path = process.env['CANARY_MCP_PERSIST_PATH'] ?? null;
+    return {
+        persist_path,
+        token_ttl_seconds,
+        alert_webhook,
+        webhook_secret,
+        response_mode,
+        log_level,
+    };
+}
+/**
+ * Loads and parses the proxy config JSON file at the given path.
+ * Throws a descriptive error on parse failure or missing required fields.
+ */
+function loadProxyConfig(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`Cannot read CANARY_MCP_PROXY_CONFIG file "${filePath}": ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`CANARY_MCP_PROXY_CONFIG file is not valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !Array.isArray(parsed.servers)) {
+        throw new Error('CANARY_MCP_PROXY_CONFIG must be a JSON object with a "servers" array.');
+    }
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        // Log to stderr before the logger is fully initialised.
+        process.stderr.write(JSON.stringify({ level: 'error', msg: `Startup configuration error: ${err.message}` }) + '\n');
+        process.exit(1);
+    }
+    log('info', 'exfil/canary initialising.', {
+        response_mode: config.response_mode,
+        token_ttl_seconds: config.token_ttl_seconds,
+        persist: config.persist_path !== null,
+        webhook: config.alert_webhook !== null,
+    });
+    // Attempt state recovery; fall back to fresh session.
+    let state = await recoverState(config);
+    if (!state) {
+        state = createSession();
+        log('info', 'Starting fresh session.', { session_id: state.session_id });
+    }
+    // ---------------------------------------------------------------------------
+    // Choose mode: proxy (CANARY_MCP_PROXY_CONFIG set) or standalone
+    // ---------------------------------------------------------------------------
+    const proxyConfigPath = process.env['CANARY_MCP_PROXY_CONFIG'] ?? null;
+    let server;
+    if (proxyConfigPath) {
+        let proxyConfig;
+        try {
+            proxyConfig = loadProxyConfig(proxyConfigPath);
+        }
+        catch (err) {
+            process.stderr.write(JSON.stringify({ level: 'error', msg: `Proxy config error: ${err.message}` }) + '\n');
+            process.exit(1);
+        }
+        log('info', 'exfil/canary starting in proxy mode.', {
+            proxy_config: proxyConfigPath,
+            downstream_servers: proxyConfig.servers.length,
+        });
+        server = new ProxyServer(state, config, proxyConfig);
+    }
+    else {
+        log('info', 'exfil/canary starting in standalone mode.');
+        server = new CanaryMcpServer(state, config);
+    }
+    // ---------------------------------------------------------------------------
+    // Graceful shutdown handlers
+    // ---------------------------------------------------------------------------
+    let shuttingDown = false;
+    async function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log('info', `Received ${signal} — shutting down.`);
+        try {
+            await server.shutdown();
+        }
+        catch (err) {
+            log('error', `Error during shutdown: ${err.message}`);
+        }
+        process.exit(0);
+    }
+    process.on('SIGTERM', () => { shutdown('SIGTERM').catch(() => process.exit(1)); });
+    process.on('SIGINT', () => { shutdown('SIGINT').catch(() => process.exit(1)); });
+    // ---------------------------------------------------------------------------
+    // Background expiry sweep — every 60s, unref'd (RC-2 / spec requirement)
+    // ---------------------------------------------------------------------------
+    const sweepInterval = setInterval(() => {
+        server.sweepExpiredTokens();
+    }, 60_000);
+    sweepInterval.unref();
+    // ---------------------------------------------------------------------------
+    // Start server
+    // ---------------------------------------------------------------------------
+    await server.start();
+}
+main().catch((err) => {
+    process.stderr.write(JSON.stringify({ level: 'error', msg: `Fatal: ${err.message}` }) + '\n');
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal structured logger.
+ *
+ * SECURITY: This module must NEVER log the `sequence` field of a CanaryToken,
+ * nor the raw `data` argument of scan_outbound.  Callers are responsible for
+ * not passing sensitive values; this module provides no automatic redaction.
+ *
+ * Output goes to stderr so it does not interfere with the MCP stdio transport
+ * (which uses stdout).
+ */
+import type { LogLevel } from './types.js';
+/**
+ * Sets the minimum log level.  Messages below this level are suppressed.
+ *
+ * @param level  New minimum level.
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Emits a log line to stderr.
+ *
+ * Fields are serialised as JSON; the message string is NOT interpolated to
+ * avoid accidental inclusion of raw data.
+ *
+ * @param level    Severity.
+ * @param message  Human-readable description.  MUST NOT contain token sequences or raw scan data.
+ * @param meta     Optional additional structured fields (MUST be pre-redacted by caller).
+ */
+export declare function log(level: LogLevel, message: string, meta?: Record<string, unknown>): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAY3C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CACjB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAaN"}

package/dist/logger.js

@@ -0,0 +1,50 @@
+/**
+ * Minimal structured logger.
+ *
+ * SECURITY: This module must NEVER log the `sequence` field of a CanaryToken,
+ * nor the raw `data` argument of scan_outbound.  Callers are responsible for
+ * not passing sensitive values; this module provides no automatic redaction.
+ *
+ * Output goes to stderr so it does not interfere with the MCP stdio transport
+ * (which uses stdout).
+ */
+const LEVEL_RANK = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/** The minimum level to emit.  Set once at startup via `setLogLevel`. */
+let currentLevel = 'info';
+/**
+ * Sets the minimum log level.  Messages below this level are suppressed.
+ *
+ * @param level  New minimum level.
+ */
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+/**
+ * Emits a log line to stderr.
+ *
+ * Fields are serialised as JSON; the message string is NOT interpolated to
+ * avoid accidental inclusion of raw data.
+ *
+ * @param level    Severity.
+ * @param message  Human-readable description.  MUST NOT contain token sequences or raw scan data.
+ * @param meta     Optional additional structured fields (MUST be pre-redacted by caller).
+ */
+export function log(level, message, meta) {
+    if (LEVEL_RANK[level] < LEVEL_RANK[currentLevel])
+        return;
+    const entry = {
+        ts: new Date().toISOString(),
+        level,
+        msg: message,
+    };
+    if (meta) {
+        Object.assign(entry, meta);
+    }
+    process.stderr.write(JSON.stringify(entry) + '\n');
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,yEAAyE;AACzE,IAAI,YAAY,GAAa,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,YAAY,GAAG,KAAK,CAAC;AACvB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,GAAG,CACjB,KAAe,EACf,OAAe,EACf,IAA8B;IAE9B,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO;IAEzD,MAAM,KAAK,GAA4B;QACrC,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,KAAK;QACL,GAAG,EAAE,OAAO;KACb,CAAC;IACF,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC"}

package/dist/persistence.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 type { CanaryConfig, SessionState } from './types.js';
+/**
+ * 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 declare function persistState(state: SessionState, config: CanaryConfig): Promise<void>;
+/**
+ * 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 declare function recoverState(config: CanaryConfig): Promise<SessionState | null>;
+/**
+ * Top-level validation of the raw parsed JSON from the persistence file.
+ *
+ * @param raw  Parsed JSON value.
+ */
+export declare function validatePersistedState(raw: unknown): boolean;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EACV,YAAY,EAMZ,YAAY,EACb,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAmDf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAiF9B;AAkCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAS5D"}