@drakon-systems/shieldcortex-realtime 4.54.14 → 5.0.0

package/interceptor.ts

@@ -46,6 +46,14 @@ export interface ActionGuardConfig {
 /** Structural shape of a Tool Action Guard verdict (kept local to avoid a
  * compile-time dependency on the main package across the plugin build boundary;
  * the real `evaluateToolCall` from `shieldcortex/defence` is compatible). */
+/** A reviewed native contract grew fields ShieldCortex does not read. Names
+ *  only — the guard drops the values before any scanner sees them. */
+export interface ContractDriftLike {
+  contract: string;
+  droppedKeys: string[];
+  truncated?: boolean;
+}
+
 export interface ToolGuardVerdictLike {
   decision: 'allow' | 'require_approval' | 'block';
   severity: 'benign' | 'sensitive' | 'dangerous' | 'catastrophic' | string;
@@ -53,6 +61,8 @@ export interface ToolGuardVerdictLike {
   action: string;
   reason: string;
   signals: string[];
+  /** Present only when a reviewed contract drifted. Never a verdict input. */
+  contractDrift?: ContractDriftLike;
   /** Rule → matched-span evidence behind `signals` (issue #192).
    *  #184: optional source/line/chain when the match came from folded script. */
   matches?: Array<{
@@ -277,6 +287,15 @@ export interface InterceptAuditEntry {
   escalated?: { by: 'session-taint'; from: string; to: string; reason: string };
   /** Files the reviewed-script allowlist exempted from folding (#189). */
   reviewedScripts?: string[];
+  /**
+   * Native contract drift: a reviewed exact-name host contract carried fields
+   * ShieldCortex does not read, which the guard dropped before validation and
+   * before any extractor. Key NAMES only, bounded — an operator can see THAT a
+   * host schema moved and which fields moved, without the row ever carrying a
+   * value from them. Advisory: this rides on the call's own outcome and never
+   * gates, denies, or mints a card.
+   */
+  contractDrift?: ContractDriftLike;
   /** #260 — plane origin so the session-guard summariser can find this row. */
   origin?: 'openclaw-interceptor';
   sessionKey?: string;
@@ -316,13 +335,11 @@ const DEFAULT_CONFIG: InterceptorConfig = {
     high: 'deny',
     critical: 'deny',
   },
-  // Action Guard on by default: catastrophic ops are blocked out of the box;
-  // recognised-dangerous ops are ENFORCED by default (P1/WS1) — attended → prompt,
-  // unattended → fail closed on failurePolicy. Populate `autoApprove` per agent to
-  // pre-approve the dangerous ops it legitimately needs unattended; set
-  // `enforce:false` to opt back down to warn-and-allow.
+  // Action Guard OFF by default: false-card storms on live OpenClaw exec
+  // bags made default-on an uninstall risk. Catastrophic gating is also off
+  // until the operator signs `shieldcortex config --action-guard-enable`.
   actionGuard: {
-    enabled: true,
+    enabled: false,
     enforce: true,
     autoApprove: [],
     auditAllows: true,
@@ -466,6 +483,23 @@ export function formatApprovalPrompt(input: ApprovalPromptInput): string {
   ].join('\n');
 }
 
+/**
+ * The guard could not CLOSE this bag: the #412 tool-input schema rejected it,
+ * or the command-evidence walk ran out of budget before it had read all of it.
+ * Either way the call was never fully scanned, so no operator widening may
+ * apply to it — see `unscannedBlock` at the enforcement site.
+ *
+ * Read off the guard's own reason codes (`invalid_tool_input` /
+ * `invalid-tool-input`) rather than the decision tier, so it stays true
+ * whichever door the core decides this class deserves. Mirrored in
+ * `scripts/pre-tool-hook.mjs` (`isSchemaInvalid`) — the two enforcement
+ * surfaces must agree, and parity is asserted by the plane gate.
+ */
+function isSchemaInvalid(v: ToolGuardVerdictLike): boolean {
+  return v.action === 'invalid_tool_input'
+    || (Array.isArray(v.signals) && v.signals.includes('invalid-tool-input'));
+}
+
 // --- WS2 fail-closed fallback (guard load/eval failure) ---
 // Deliberately DUPLICATED from tool-action-guard.ts's CATASTROPHIC list, not
 // imported — this file already avoids a compile-time dependency on the main
@@ -946,7 +980,7 @@ export function createInterceptor(
   const bindAudit = options?.bindAudit;
   /** Args of the in-flight tool call — used only to mint #224 actionKey. */
   let lastCallArgs: Record<string, unknown> | undefined;
-  const actionGuardCfg: ActionGuardConfig = config.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] };
+  const actionGuardCfg: ActionGuardConfig = config.actionGuard ?? { enabled: false, enforce: true, autoApprove: [] };
   const evaluateToolCall = options?.evaluateToolCall;
   const broker = options?.broker;
   // The judge rides the operator's own model pool, so its calls are their cost
@@ -1304,31 +1338,73 @@ export function createInterceptor(
       }
     }
 
+    // ── Native contract drift observation ────────────────────────────────
+    // A reviewed host contract grew fields ShieldCortex does not read. The
+    // guard already dropped them before nested validation and before any
+    // extractor, so nothing here can change the verdict — this is the record
+    // that the drop HAPPENED, which is the only way an operator learns a host
+    // schema moved without a card storm telling them. It rides on the call's
+    // own outcome rather than minting a row of its own, so a drifted benign
+    // allow stays a single row and volume discipline holds. `auditAllows:false`
+    // opts out with the rest of the recognised-allow stream.
+    const drift = v.contractDrift && v.contractDrift.droppedKeys.length > 0
+      ? { contractDrift: v.contractDrift }
+      : undefined;
+    if (v.decision === 'allow' && drift && actionGuardCfg.auditAllows !== false) {
+      const d = drift.contractDrift;
+      log.warn(
+        `[shieldcortex] action-guard CONTRACT DRIFT ${context.toolName} (${d.contract}): dropped unread field(s) ${d.droppedKeys.join(', ')}${d.truncated ? ', …' : ''}`,
+      );
+    }
+
     if (v.decision === 'allow') {
       // Issue #95: a RECOGNISED allow (the guard evaluated a known operation
       // family and let it through — severity above benign) leaves an audit
       // entry, so forensics can distinguish "scanned & allowed" from "never
       // scanned". Benign allows stay unaudited by design (volume discipline);
       // `actionGuard.auditAllows: false` opts the recognised entries off too.
-      if (v.severity !== 'benign' && actionGuardCfg.auditAllows !== false) {
-        const allowPreview = `${context.toolName} :: ${summariseToolArgs(context.arguments)}`;
-        emitAudit({ ...guardAuditBase(context.toolName, v, allowPreview), action: 'allow', outcome: 'allowed' });
+      if (actionGuardCfg.auditAllows !== false) {
+        if (v.severity !== 'benign') {
+          const allowPreview = `${context.toolName} :: ${summariseToolArgs(context.arguments)}`;
+          emitAudit({ ...guardAuditBase(context.toolName, v, allowPreview), ...(drift ?? {}), action: 'allow', outcome: 'allowed' });
+        } else if (drift) {
+          // A benign allow is normally unaudited — but drift is the one thing
+          // about it worth keeping, so it rides on ONE row of its own rather
+          // than doubling the recognised-allow row above. The preview is the
+          // tool name and nothing else: a drifted field may hold a prompt or a
+          // token, and unlike `summariseToolArgs` this row must never be a
+          // channel for a value the guard just refused to read.
+          emitAudit({
+            ...guardAuditBase(context.toolName, v, `${context.toolName} :: contract-drift`),
+            ...drift,
+            action: 'allow',
+            outcome: 'allowed',
+          });
+        }
       }
       return;
     }
 
     const preview = `${context.toolName} :: ${summariseToolArgs(context.arguments)}`;
-    const base = { ...guardAuditBase(context.toolName, v, preview), ...(escalation ? { escalated: escalation } : {}) };
+    const base = { ...guardAuditBase(context.toolName, v, preview), ...(escalation ? { escalated: escalation } : {}), ...(drift ?? {}) };
     const severity: Severity = v.severity === 'catastrophic' ? 'critical' : 'high';
 
     // Catastrophic / exfil — hard block, always enforced when the guard is enabled.
-    // #436: the door-less throw is for that tier only. A sub-catastrophic `block`
-    // (schema rejection) falls through to requireApproval so the operator can
-    // still say yes. autoApprove and enforce:false must not widen an unscanned
-    // call — they skip below.
+    // #436: the door-less throw is for that tier only. A schema rejection falls
+    // through to requireApproval so the operator can still say yes. autoApprove
+    // and enforce:false must not widen an unscanned call — they skip below.
     const terminalBlock = v.decision === 'block'
       && (v.severity === 'catastrophic' || v.severity === 'critical');
-    const unscannedBlock = v.decision === 'block' && !terminalBlock;
+    // Derived from the guard's OWN schema signal, not from `decision`. The core
+    // answers a scanned-clean schema rejection with `require_approval` (so all
+    // three planes say the same word about the same call), which means
+    // `decision === 'block'` no longer identifies the class. Keying off the
+    // decision here would silently re-open exactly what #436 closed:
+    // `{command:'…', evil:'…'}` running unscanned on an `enforce:false` host,
+    // and `autoApprove: ['unknown-keys']` becoming a blanket bypass of the #412
+    // closed schema. The residual `decision === 'block' && !terminalBlock` arm
+    // is kept for any sub-catastrophic block a future rule mints.
+    const unscannedBlock = isSchemaInvalid(v) || (v.decision === 'block' && !terminalBlock);
     if (terminalBlock) {
       // #227: release any lease this call minted early — a blocked action must
       // not leave a hold on that scope (self-heals at TTL if release fails).

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.54.14",
+  "version": "5.0.0",
   "name": "ShieldCortex Real-time Scanner",
   "description": "Real-time defence scanning on LLM input, memory extraction on LLM output, and active tool call interception with approval gating.",
   "kind": null,
@@ -304,7 +304,7 @@
             "properties": {
               "enabled": {
                 "type": "boolean",
-                "default": true
+                "default": false
               },
               "enforce": {
                 "type": "boolean",
@@ -427,7 +427,7 @@
         "properties": {
           "enabled": {
             "type": "boolean",
-            "default": true
+            "default": false
           },
           "enforce": {
             "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "4.54.14",
+  "version": "5.0.0",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,7 @@
   "files": [
     "dist/",
     "index.ts",
+    "provenance.ts",
     "interceptor.ts",
     "intercept-ingest.ts",
     "cloud-sync.ts",
@@ -27,7 +28,7 @@
     "prepublishOnly": "node -e \"if(!require('fs').existsSync('dist/index.js'))throw new Error('plugin dist/index.js missing \u2014 run `npm run build:ts` from the repo root before publishing')\""
   },
   "peerDependencies": {
-    "shieldcortex": "^4.54.8",
+    "shieldcortex": "^5.0.0",
     "openclaw": ">=2026.3.22"
   },
   "peerDependenciesMeta": {
@@ -36,7 +37,7 @@
     }
   },
   "engines": {
-    "node": ">=20.0.0",
+    "node": "^22.14.0 || >=24.0.0",
     "openclaw": ">=2026.4.23"
   },
   "publishConfig": {

package/provenance.ts

@@ -0,0 +1,227 @@
+/**
+ * Provenance labelling for the OpenClaw realtime `llm_input` hook.
+ *
+ * The hook used to hand every text to the scanner with no origin attached:
+ * the operator's own prompt and a web page that arrived inside a tool result
+ * were judged by the identical detector. That is the wall the L2 policy
+ * exists to break — the same sentence is an instruction from the operator and
+ * an injection from a fetched document, and only the ORIGIN separates them.
+ *
+ * Two rules govern everything here:
+ *
+ *   1. NEVER GUESS UPWARDS. A shape this file does not recognise is labelled
+ *      `unknown`, which keeps exactly the pre-existing L1 path and is counted
+ *      so an operator can see that their host's event shape is not being
+ *      classified. Guessing `user` would silence L2 on real tool output;
+ *      guessing `tool_result` would apply an aggressive policy to the
+ *      operator's own words.
+ *
+ *   2. NEVER INVENT A DISTINCTION THE EVENT DOES NOT CARRY. The OpenClaw
+ *      `llm_input` event exposes `prompt`, `systemPrompt`, `historyMessages`
+ *      and counters — nothing in it says "this tool result was a fetched web
+ *      page" or "this was a file read". So this file emits `tool_result` for
+ *      all tool-origin content and never `web`/`document`. Those two labels
+ *      remain reachable from ingresses that genuinely know (the `scan` CLI's
+ *      --source), and adding them here later needs a host field to read, not
+ *      a heuristic.
+ *
+ * Pure and synchronous: no I/O, no config read, no defence module. The plugin
+ * calls it once per hook invocation before any scanning happens.
+ *
+ * The label vocabulary MIRRORS `ProvenanceLabel` in the main package
+ * (src/defence/types.ts). It is spelled out rather than imported because this
+ * plugin compiles against its own rootDir and must build without the package
+ * source on disk. Only the subset this hook can honestly emit appears here —
+ * a label this file cannot justify is a label it must not produce.
+ */
+
+export const PLUGIN_PROVENANCE_LABELS = ['user', 'tool_result', 'unknown'] as const;
+
+export type PluginProvenanceLabel = (typeof PLUGIN_PROVENANCE_LABELS)[number];
+
+export interface LabelledInput {
+  text: string;
+  label: PluginProvenanceLabel;
+}
+
+/**
+ * The result of labelling one event: the texts to scan, and how many
+ * tool-origin blocks carried no readable text.
+ *
+ * The second number exists because "dropped silently" is the one outcome a
+ * provenance layer must not have. A host that wraps its tool results in a
+ * shape this file cannot read produces no inputs AND no counter, so the
+ * operator sees a clean plane that is in fact looking at nothing. The count
+ * is of BLOCKS, never their content.
+ */
+export interface LabelledInputs {
+  inputs: LabelledInput[];
+  unreadableToolBlocks: number;
+}
+
+/**
+ * How many history texts the hook looks at. Unchanged from the pre-provenance
+ * behaviour (`extractUserContent(...).slice(-5)`): labelling widens WHICH
+ * messages are eligible, not how many are scanned per turn.
+ */
+export const HISTORY_SCAN_LIMIT = 5;
+
+/** Roles that carry tool output back to the model, across host encodings. */
+const TOOL_ROLES = new Set(['tool', 'tool_result', 'function', 'tool-result']);
+/** Roles that are the human speaking to the agent. */
+const USER_ROLES = new Set(['user', 'human']);
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function blockText(block: unknown): string | null {
+  const b = asRecord(block);
+  if (!b) return typeof block === 'string' ? block : null;
+  if (typeof b.text === 'string') return b.text;
+  if (typeof b.content === 'string') return b.content;
+  return null;
+}
+
+/** A content block that IS a tool result, by any of the encodings in use. */
+function isToolResultBlock(block: unknown): boolean {
+  const b = asRecord(block);
+  if (!b) return false;
+  if (typeof b.type === 'string' && TOOL_ROLES.has(b.type)) return true;
+  // Anthropic-shaped blocks correlate a result to its call; the presence of
+  // that correlation id is the structural tell, independent of `type`.
+  return typeof b.tool_use_id === 'string' || typeof b.toolUseId === 'string';
+}
+
+/** Nested tool-result content is flattened at most this deep. */
+const MAX_NESTING = 3;
+
+/**
+ * Pull every readable text out of one tool-result block, however the host
+ * nested it, and count the parts that carried none.
+ *
+ * Anthropic-shaped results are `{type:'tool_result', tool_use_id, content:[
+ * {type:'text', text}]}` — a content ARRAY, which the r1 `blockText` could
+ * not read, so the whole result was dropped before its tool-result structure
+ * was ever examined and no counter moved either. The established provenance
+ * is preserved through every child representation: once a block is
+ * tool-origin, everything inside it is too.
+ */
+function flattenToolResult(block: unknown, depth: number, out: string[]): number {
+  const direct = blockText(block);
+  if (direct) {
+    out.push(direct);
+    return 0;
+  }
+  const b = asRecord(block);
+  if (!b || depth >= MAX_NESTING) return 1;
+  const inner = b.content ?? b.result ?? b.output;
+  if (Array.isArray(inner)) {
+    if (inner.length === 0) return 1;
+    let unreadable = 0;
+    for (const child of inner) unreadable += flattenToolResult(child, depth + 1, out);
+    return unreadable;
+  }
+  if (inner && typeof inner === 'object') return flattenToolResult(inner, depth + 1, out);
+  return 1;
+}
+
+/**
+ * Label one history message.
+ *
+ * A user-role message is NOT automatically `user`: on Anthropic-shaped
+ * histories a tool result is delivered as a user-role message whose content
+ * blocks are tool results. That is precisely the indirect-injection path, so
+ * the BLOCK decides, not the role.
+ */
+export function labelHistoryMessage(msg: unknown): LabelledInputs {
+  const m = asRecord(msg);
+  if (!m) return { inputs: [], unreadableToolBlocks: 0 };
+  const role = typeof m.role === 'string' ? m.role.toLowerCase() : '';
+  const roleLabel: PluginProvenanceLabel | null = TOOL_ROLES.has(role)
+    ? 'tool_result'
+    : USER_ROLES.has(role)
+      ? 'user'
+      : null;
+
+  if (typeof m.content === 'string') {
+    // A bare string carries no block structure. A TOOL role still decides —
+    // the host declared the origin and inheriting it can only tighten. A USER
+    // role does not: rule #1 forbids guessing upwards, and a host that
+    // flattens tool results into user-role strings would otherwise turn L2
+    // off by accident. `unknown` costs nothing here (both labels are L2-off)
+    // and buys the honesty counter, so the operator sees that this host's
+    // history shape is not being classified rather than being told it is.
+    const label: PluginProvenanceLabel = roleLabel === 'tool_result' ? 'tool_result' : 'unknown';
+    return {
+      inputs: m.content ? [{ text: m.content, label }] : [],
+      unreadableToolBlocks: 0,
+    };
+  }
+
+  if (Array.isArray(m.content)) {
+    const inputs: LabelledInput[] = [];
+    let unreadableToolBlocks = 0;
+    for (const block of m.content) {
+      if (isToolResultBlock(block)) {
+        const texts: string[] = [];
+        unreadableToolBlocks += flattenToolResult(block, 0, texts);
+        for (const text of texts) inputs.push({ text, label: 'tool_result' });
+        continue;
+      }
+      const text = blockText(block);
+      if (!text) {
+        // Only tool-origin loss is counted: an image block in a user turn is
+        // not a gap in this layer, it is a thing this layer never judged.
+        if (roleLabel === 'tool_result') unreadableToolBlocks += 1;
+        continue;
+      }
+      const b = asRecord(block);
+      const isText = b && typeof b.type === 'string' && b.type === 'text';
+      // Established untrusted provenance is INHERITED: a string (or any
+      // shape) inside a tool-role message is tool output whatever its own
+      // block type says. Under any other role only a text block may inherit;
+      // anything else is a shape this file cannot account for.
+      const label: PluginProvenanceLabel = roleLabel === 'tool_result'
+        ? 'tool_result'
+        : isText && roleLabel
+          ? roleLabel
+          : 'unknown';
+      inputs.push({ text, label });
+    }
+    return { inputs, unreadableToolBlocks };
+  }
+
+  return { inputs: [], unreadableToolBlocks: 0 };
+}
+
+/**
+ * Every text this hook will scan for one `llm_input` event, each with the
+ * origin it was declared under.
+ *
+ * The live `prompt` is the turn the host attributes to the sender, so it is
+ * `user` — the same judgement the conversation-trust layer already makes
+ * about a turn. History is labelled per message and bounded to the last
+ * {@link HISTORY_SCAN_LIMIT}, as before.
+ */
+export function labelLlmInput(event: {
+  prompt?: unknown;
+  historyMessages?: unknown;
+}): LabelledInputs {
+  const out: LabelledInput[] = [];
+  if (typeof event?.prompt === 'string' && event.prompt) {
+    out.push({ text: event.prompt, label: 'user' });
+  }
+  const history = Array.isArray(event?.historyMessages) ? event.historyMessages : [];
+  const labelled: LabelledInput[] = [];
+  let unreadableToolBlocks = 0;
+  for (const msg of history) {
+    const one = labelHistoryMessage(msg);
+    labelled.push(...one.inputs);
+    unreadableToolBlocks += one.unreadableToolBlocks;
+  }
+  out.push(...labelled.slice(-HISTORY_SCAN_LIMIT));
+  return { inputs: out, unreadableToolBlocks };
+}