shieldcortex 4.31.2 → 4.32.0

package/dist/scan-only.d.ts

@@ -0,0 +1,64 @@
+/**
+ * shieldcortex/scan — edge-safe, scan-only entry point.
+ *
+ * This module runs the PURE defence detection layers (sanitise → trust →
+ * firewall → sensitivity → fragmentation → credential-leak) with NO static
+ * dependency on:
+ *   - better-sqlite3 (the native binding)
+ *   - @huggingface/transformers (the ~349MB ML stack)
+ *   - the database layer, cloud sync, the events bus, or audit persistence
+ *
+ * It exists so CI runners, serverless/edge functions, and integrators who only
+ * need synchronous regex/heuristic scanning can `import { scan } from
+ * 'shieldcortex/scan'` without pulling a native build or the ML dependency.
+ *
+ * Differences vs the full `runDefencePipeline` (from 'shieldcortex/defence'):
+ *   - No audit row is written (auditId is always 0 — a sentinel).
+ *   - No cloud sync / defence events are emitted.
+ *   - The DB-backed custom firewall rules and custom injection patterns layers
+ *     are ABSENT. Scan-only callers have no local DB of rules to apply, so only
+ *     the built-in detection layers run. To use custom rules/patterns, use the
+ *     full pipeline (which requires the database) or the SaaS API.
+ *   - Fragmentation is always null: that layer correlates entities ACROSS
+ *     stored memories, which is impossible without a DB. A single, stateless
+ *     scan can never assemble a multi-memory fragmentation signal, so the layer
+ *     is a no-op here (matching `runDefencePipeline`'s own score-0 result when
+ *     no prior entities exist in the DB).
+ *
+ * CommonJS note: this package is ESM-only. CJS consumers can reach this entry
+ * with a dynamic import: `const { scan } = await import('shieldcortex/scan')`.
+ * A dedicated CJS build is a deliberate non-goal for this phase.
+ *
+ * IMPORTANT — DO NOT add imports that transitively pull the DB/ML stack:
+ *   - import `scoreSource` from './defence/trust/source-scorer.js' directly,
+ *     NOT from './defence/trust/index.js' (that re-exports resolve-tool-source,
+ *     which imports the audit logger → database/init → better-sqlite3).
+ *   - do NOT import './defence/pipeline.js', './defence/audit/*',
+ *     './defence/fragmentation/index.js', './api/events.js', './cloud/*',
+ *     './database/*', './defence/custom-rules/*', or './defence/custom-patterns/*'.
+ * The src/__tests__/scan-only-entry.test.ts import-graph assertion enforces this
+ * against the compiled dist output.
+ */
+import type { DefenceConfig, DefencePipelineResult, DefenceSource } from './defence/types.js';
+export interface ScanOptions {
+    /** Optional title/context scanned alongside the content. */
+    title?: string;
+    /** Source attribution for trust scoring. Defaults to a generic user source. */
+    source?: DefenceSource;
+    /** Override the default defence config (mode, thresholds, etc.). */
+    config?: DefenceConfig;
+}
+/**
+ * Run the pure defence pipeline on a piece of content.
+ *
+ * Returns a `DefencePipelineResult`-shaped object with the verdict, indicators,
+ * and per-layer results — minus persistence (auditId is always 0, fragmentation
+ * is always null, no DB-backed custom rules are applied).
+ *
+ * Fail-closed: if any layer throws, the result defaults to BLOCK.
+ */
+export declare function scan(content: string, options?: ScanOptions): DefencePipelineResult;
+/** Alias for {@link scan}. */
+export declare const scanText: typeof scan;
+export type { DefencePipelineResult, DefenceSource, DefenceConfig } from './defence/types.js';
+export { DEFAULT_DEFENCE_CONFIG } from './defence/types.js';

package/dist/scan-only.js

@@ -0,0 +1,173 @@
+/**
+ * shieldcortex/scan — edge-safe, scan-only entry point.
+ *
+ * This module runs the PURE defence detection layers (sanitise → trust →
+ * firewall → sensitivity → fragmentation → credential-leak) with NO static
+ * dependency on:
+ *   - better-sqlite3 (the native binding)
+ *   - @huggingface/transformers (the ~349MB ML stack)
+ *   - the database layer, cloud sync, the events bus, or audit persistence
+ *
+ * It exists so CI runners, serverless/edge functions, and integrators who only
+ * need synchronous regex/heuristic scanning can `import { scan } from
+ * 'shieldcortex/scan'` without pulling a native build or the ML dependency.
+ *
+ * Differences vs the full `runDefencePipeline` (from 'shieldcortex/defence'):
+ *   - No audit row is written (auditId is always 0 — a sentinel).
+ *   - No cloud sync / defence events are emitted.
+ *   - The DB-backed custom firewall rules and custom injection patterns layers
+ *     are ABSENT. Scan-only callers have no local DB of rules to apply, so only
+ *     the built-in detection layers run. To use custom rules/patterns, use the
+ *     full pipeline (which requires the database) or the SaaS API.
+ *   - Fragmentation is always null: that layer correlates entities ACROSS
+ *     stored memories, which is impossible without a DB. A single, stateless
+ *     scan can never assemble a multi-memory fragmentation signal, so the layer
+ *     is a no-op here (matching `runDefencePipeline`'s own score-0 result when
+ *     no prior entities exist in the DB).
+ *
+ * CommonJS note: this package is ESM-only. CJS consumers can reach this entry
+ * with a dynamic import: `const { scan } = await import('shieldcortex/scan')`.
+ * A dedicated CJS build is a deliberate non-goal for this phase.
+ *
+ * IMPORTANT — DO NOT add imports that transitively pull the DB/ML stack:
+ *   - import `scoreSource` from './defence/trust/source-scorer.js' directly,
+ *     NOT from './defence/trust/index.js' (that re-exports resolve-tool-source,
+ *     which imports the audit logger → database/init → better-sqlite3).
+ *   - do NOT import './defence/pipeline.js', './defence/audit/*',
+ *     './defence/fragmentation/index.js', './api/events.js', './cloud/*',
+ *     './database/*', './defence/custom-rules/*', or './defence/custom-patterns/*'.
+ * The src/__tests__/scan-only-entry.test.ts import-graph assertion enforces this
+ * against the compiled dist output.
+ */
+import { DEFAULT_DEFENCE_CONFIG } from './defence/types.js';
+import { sanitiseInput } from './defence/input-sanitisation/index.js';
+import { scoreSource } from './defence/trust/source-scorer.js';
+import { analyzeFirewall } from './defence/firewall/index.js';
+import { classifySensitivity } from './defence/sensitivity/index.js';
+import { scanForCredentials } from './defence/credential-leak/index.js';
+const DEFAULT_SOURCE = { type: 'user', identifier: 'scan-only' };
+/**
+ * Run the pure defence pipeline on a piece of content.
+ *
+ * Returns a `DefencePipelineResult`-shaped object with the verdict, indicators,
+ * and per-layer results — minus persistence (auditId is always 0, fragmentation
+ * is always null, no DB-backed custom rules are applied).
+ *
+ * Fail-closed: if any layer throws, the result defaults to BLOCK.
+ */
+export function scan(content, options = {}) {
+    const cfg = options.config ?? { ...DEFAULT_DEFENCE_CONFIG };
+    const title = options.title ?? '';
+    const source = options.source ?? DEFAULT_SOURCE;
+    try {
+        // 1. Input sanitisation (Layer 1) — strip dangerous bytes before analysis.
+        const sanitisation = sanitiseInput(content);
+        const cleanContent = sanitisation.sanitised;
+        // 2. Score trust.
+        const trust = scoreSource(source);
+        // 3. Run firewall on sanitised content, feeding back the strip categories so
+        // the encoding detector accounts for zero-width/bidi bytes the sanitiser
+        // already removed (same contract as runDefencePipeline).
+        const firewall = analyzeFirewall(cleanContent, title, source, trust.score, cfg, sanitisation.strippedCategories);
+        // Carry forward sanitisation threat indicators (deduped).
+        for (const indicator of sanitisation.threatIndicators) {
+            if (!firewall.threatIndicators.includes(indicator)) {
+                firewall.threatIndicators.push(indicator);
+            }
+        }
+        // 4. Classify sensitivity.
+        const sensitivity = classifySensitivity(cleanContent, title);
+        // 5. Fragmentation is omitted in scan-only: it correlates entities across
+        // stored memories, which requires a DB this entry deliberately avoids. With
+        // no prior memories there is nothing to correlate, so the layer is null —
+        // exactly what the full pipeline produces with an empty entity store.
+        // 6. Credential leak detection.
+        const credentialScan = scanForCredentials(cleanContent);
+        // 7. Determine final decision (mirrors runDefencePipeline's precedence,
+        // minus the DB-backed custom-rules/custom-patterns and fragmentation steps).
+        let allowed;
+        let reason;
+        const credentialBlocked = credentialScan.findings.some(f => f.action === 'blocked');
+        if (firewall.result === 'BLOCK') {
+            allowed = false;
+            reason = firewall.reason;
+        }
+        else if (credentialBlocked) {
+            allowed = false;
+            const blockedTypes = credentialScan.findings
+                .filter(f => f.action === 'blocked')
+                .map(f => (f.provider ? `${f.provider} ${f.type}` : f.type));
+            reason = `Blocked: credential leak detected (${blockedTypes.join(', ')})`;
+            firewall.result = 'BLOCK';
+            if (!firewall.threatIndicators.includes('credential_leak')) {
+                firewall.threatIndicators.push('credential_leak');
+            }
+        }
+        else if (firewall.result === 'QUARANTINE') {
+            allowed = false;
+            reason = `Quarantined: ${firewall.reason}`;
+        }
+        else if (sensitivity.level === 'RESTRICTED') {
+            allowed = false;
+            reason = `Blocked: content classified as RESTRICTED (${sensitivity.detectedPatterns.join(', ')})`;
+            firewall.result = 'BLOCK';
+            firewall.reason = reason;
+            if (!firewall.threatIndicators.includes('restricted_content')) {
+                firewall.threatIndicators.push('restricted_content');
+            }
+        }
+        else if (firewall.result !== 'ALLOW') {
+            allowed = false;
+            reason = `Unexpected firewall result: ${firewall.result}`;
+        }
+        else {
+            allowed = true;
+            reason = firewall.reason;
+        }
+        // Keep top-level reason and firewall.reason consistent for downstream callers.
+        firewall.reason = reason;
+        // Surface credential findings even when non-blocking.
+        if (credentialScan.leaked && !firewall.threatIndicators.includes('credential_leak')) {
+            firewall.threatIndicators.push('credential_leak');
+        }
+        return {
+            allowed,
+            firewall,
+            fragmentation: null,
+            sensitivity,
+            trust,
+            credentialScan: credentialScan.leaked ? credentialScan : undefined,
+            auditId: 0,
+        };
+    }
+    catch (err) {
+        // FAIL-CLOSED: on error, default to BLOCK for security.
+        console.error('[scan-only] Pipeline error, failing closed:', err);
+        return {
+            allowed: false,
+            firewall: {
+                result: 'BLOCK',
+                reason: 'Pipeline error — fail-closed for security',
+                threatIndicators: ['pipeline_error'],
+                anomalyScore: 1.0,
+                blockedPatterns: [],
+            },
+            fragmentation: null,
+            sensitivity: {
+                level: 'RESTRICTED',
+                confidence: 0,
+                detectedPatterns: [],
+                redactionRequired: true,
+            },
+            trust: {
+                score: 0,
+                source,
+                hierarchy: [],
+            },
+            auditId: 0,
+        };
+    }
+}
+/** Alias for {@link scan}. */
+export const scanText = scan;
+export { DEFAULT_DEFENCE_CONFIG } from './defence/types.js';

package/dist/server.d.ts

@@ -5,6 +5,11 @@
  * Solves context compaction and memory persistence issues.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Check text for kill phrase and trigger kill switch if detected.
+ * Returns true if kill switch was activated.
+ */
+export declare function checkAndTriggerKillSwitch(text: string, source: string): boolean;
 /**
  * Create and configure the MCP server
  */

package/dist/server.js

@@ -25,6 +25,7 @@ import { scanExistingMemories } from './defence/scanner/index.js';
 import { resolveToolSource as resolveToolSourceImpl } from './defence/trust/resolve-tool-source.js';
 import { scanToolResponse, shouldScanToolResponse } from './defence/tool-response-scanner.js';
 import { getToolResponseScanConfig } from './cloud/config.js';
+import { checkKillPhrase } from './defence/iron-dome/index.js';
 import { isKillSwitchActive, getKillSwitchMeta, assertOperationAllowed, activateKillSwitch, deactivateKillSwitch, KillSwitchError, } from './api/control.js';
 // Shared source schema for access control on MCP tools.
 // NOTE: 'user' is intentionally NOT accepted from MCP callers. MCP tools are
@@ -123,13 +124,14 @@ function withKillSwitchGuard(kind, handler) {
  * Check text for kill phrase and trigger kill switch if detected.
  * Returns true if kill switch was activated.
  */
-function checkAndTriggerKillSwitch(text, source) {
+export function checkAndTriggerKillSwitch(text, source) {
     if (isKillSwitchActive())
         return false; // already active
     try {
-        // Lazy import to avoid circular deps
-        const ironDome = require('./defence/iron-dome/index.js');
-        const result = ironDome.checkKillPhrase(text);
+        // Statically imported (see top of file) — no circular dep:
+        // iron-dome/index does not import server.ts. try/catch is purely
+        // defensive against a kill-phrase check failing at runtime.
+        const result = checkKillPhrase(text);
         return result.triggered;
     }
     catch {

package/dist/setup/claude-md.js

@@ -14,6 +14,7 @@ import os from 'os';
 import { execSync } from 'child_process';
 import { installOpenClawHook, findAllHooksDirs } from './openclaw.js';
 import { setupHooks } from './settings-hooks.js';
+import { readJsonConfigOrAbort, writeJsonConfigWithBackup, looksLikeShieldcortex } from './json-config.js';
 const MARKER = '# ShieldCortex — Memory System';
 const INSTRUCTIONS = `
 ${MARKER}
@@ -132,41 +133,45 @@ export function setupGlobalMcp() {
         args: ideal.args,
     };
     const isStablePath = ideal.command !== 'npx';
-    if (fs.existsSync(mcpPath)) {
-        try {
-            const existing = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
-            const servers = existing.mcpServers || {};
-            const current = servers.memory;
-            if (isIdealMcpEntry(current, idealEntry)) {
-                console.log(`✓ MCP: global server already configured in ~/.claude.json (stable binary: ${isStablePath ? ideal.command : 'npx'})`);
-                return;
-            }
-            // Detect whether this is a fresh add or an upgrade from the old
-            // `npx -y shieldcortex` form so we log the right message.
-            const currentIsShieldCortex = !!current && (current.command?.includes?.('shieldcortex') ||
-                current.args?.some?.((a) => typeof a === 'string' && a.includes('shieldcortex')));
-            existing.mcpServers = servers;
-            existing.mcpServers.memory = idealEntry;
-            fs.writeFileSync(mcpPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
-            if (currentIsShieldCortex && isStablePath) {
-                console.log(`✓ MCP: upgraded shieldcortex server to stable binary path (${ideal.command})`);
-                console.log('  Reason: `npx -y` resolution drift was causing periodic CLI session resets.');
-            }
-            else if (currentIsShieldCortex) {
-                console.log('✓ MCP: refreshed shieldcortex server registration');
-            }
-            else {
-                console.log(`✓ MCP: added shieldcortex server to ~/.claude.json (${ideal.command})`);
-            }
-            return;
-        }
-        catch {
-            // Parse error — fall through and create fresh below.
-        }
+    // ~/.claude.json is Claude Code's PRIMARY state file. A parse failure on an
+    // EXISTING file MUST abort (readJsonConfigOrAbort throws) — never overwrite
+    // it with a `{ mcpServers: { memory } }` stub, which would wipe the user's
+    // entire Claude Code state. A missing file legitimately yields {}.
+    const existing = readJsonConfigOrAbort(mcpPath);
+    const fileExisted = fs.existsSync(mcpPath);
+    const servers = existing.mcpServers || {};
+    const current = servers.memory;
+    if (isIdealMcpEntry(current, idealEntry)) {
+        console.log(`✓ MCP: global server already configured in ~/.claude.json (stable binary: ${isStablePath ? ideal.command : 'npx'})`);
+        return;
+    }
+    // Ownership guard (mirrors uninstall.ts): `memory` is a generic key the
+    // upstream @modelcontextprotocol/server-memory also uses. If an existing
+    // entry is NOT ShieldCortex-owned, leave it alone rather than clobber it.
+    if (current && !looksLikeShieldcortex(current)) {
+        console.warn('⚠ MCP: ~/.claude.json mcpServers.memory does not look ShieldCortex-owned — leaving it alone.');
+        console.warn('  Remove or rename that entry if you want ShieldCortex to register under `memory`.');
+        return;
+    }
+    // Detect whether this is a fresh add or an upgrade from the old
+    // `npx -y shieldcortex` form so we log the right message.
+    const currentIsShieldCortex = !!current && looksLikeShieldcortex(current);
+    existing.mcpServers = servers;
+    existing.mcpServers.memory = idealEntry;
+    writeJsonConfigWithBackup(mcpPath, existing);
+    if (!fileExisted) {
+        console.log(`✓ MCP: created global server config at ~/.claude.json (${ideal.command})`);
+    }
+    else if (currentIsShieldCortex && isStablePath) {
+        console.log(`✓ MCP: upgraded shieldcortex server to stable binary path (${ideal.command})`);
+        console.log('  Reason: `npx -y` resolution drift was causing periodic CLI session resets.');
+    }
+    else if (currentIsShieldCortex) {
+        console.log('✓ MCP: refreshed shieldcortex server registration');
+    }
+    else {
+        console.log(`✓ MCP: added shieldcortex server to ~/.claude.json (${ideal.command})`);
     }
-    const config = { mcpServers: { memory: idealEntry } };
-    fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-    console.log(`✓ MCP: created global server config at ~/.claude.json (${ideal.command})`);
 }
 export async function setupClaudeMd(options) {
     console.log('Setting up ShieldCortex...\n');

package/dist/setup/codex.js

@@ -9,6 +9,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { resolveMcpServerCommand } from './json-config.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const SERVER_NAME = 'shieldcortex-memory';
@@ -34,10 +35,16 @@ function escapeTomlString(value) {
     return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
 function buildServerBlock() {
+    // Prefer the absolute global binary (`which shieldcortex`); fall back to
+    // `node <absolute dist/index.js>`. Never `npx -y` — see resolveMcpServerCommand
+    // (the v4.11.1 fix: a dynamically-re-resolved command thrashes the editor's
+    // MCP-config hash and resets the active session).
+    const { command, args } = resolveMcpServerCommand(MCP_ENTRY);
+    const argsToml = args.map((a) => `"${escapeTomlString(a)}"`).join(', ');
     return [
         `[mcp_servers.${SERVER_NAME}]`,
-        'command = "node"',
-        `args = ["${escapeTomlString(MCP_ENTRY)}"]`,
+        `command = "${escapeTomlString(command)}"`,
+        `args = [${argsToml}]`,
         '',
     ].join('\n');
 }