@drakon-systems/shieldcortex-realtime 4.54.5 → 4.54.8

package/dist/index.js

@@ -2776,6 +2776,18 @@ function truncateApprovalText(text, maxLength) {
         return normalized;
     return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 }
+/** A held command can itself contain the credential that tripped the guard, and
+ *  an approval card is a chat surface. Same rule, same phrasing and same
+ *  trade as the Telegram card path (isSecretEgress / buildCardFields in
+ *  src/defence/iron-dome/openclaw-approval-channel.ts): the operator keeps the
+ *  tool, the signals and the severity, and loses exactly the text that must not
+ *  be forwarded. */
+const SECRET_EGRESS_PROMPT = /secret|credential/iu;
+const WITHHELD_COMMAND_TEXT = "(command withheld — contains credential material)";
+/** Prompt lines safe to forward on a secret-egress hold — label-only metadata.
+ *  `Reason:` (action guard) and `Content:` (memory write) are the two lines
+ *  that quote the payload, so anything not on this list is dropped. */
+const SAFE_APPROVAL_LINE = /^(?:Tool|Action|Risk|Signals|Threats):/iu;
 function buildTypedApprovalRequest(message) {
     const lines = message
         .split(/\r?\n/u)
@@ -2783,7 +2795,11 @@ function buildTypedApprovalRequest(message) {
         .filter(Boolean)
         .filter((line) => !/^\[(?:Approve|Deny)\]/i.test(line));
     const rawTitle = (lines[0] || "ShieldCortex approval required").replace(/^🛡️\s*/u, "");
-    const details = lines.slice(1).join(" | ") || rawTitle;
+    const detailLines = lines.slice(1);
+    const withholdPayload = SECRET_EGRESS_PROMPT.test(message);
+    const details = (withholdPayload
+        ? [WITHHELD_COMMAND_TEXT, ...detailLines.filter((line) => SAFE_APPROVAL_LINE.test(line))]
+        : detailLines).join(" | ") || rawTitle;
     const riskText = message.toLowerCase();
     const severity = /\b(?:critical|catastrophic|auto[-_\s]?deny|exfil|rm\s+-rf)\b/u.test(riskText)
         ? "critical"
@@ -2794,20 +2810,36 @@ function buildTypedApprovalRequest(message) {
         title: truncateApprovalText(rawTitle, 80),
         description: truncateApprovalText(details, 256),
         severity,
-        timeoutMs: 120_000,
+        // The host's own ceiling (MAX_PLUGIN_APPROVAL_TIMEOUT_MS), matching
+        // CARD_TIMEOUT_MS on the Telegram card path. 120s was the old bridge's
+        // number and it expired cards the operator was still walking back to.
+        timeoutMs: 600_000,
         timeoutBehavior: "deny",
         allowedDecisions: ["allow-once", "deny"],
     };
 }
-async function handleTypedBeforeToolCall(event, interceptor, logger, sessionId) {
+export const __buildTypedApprovalRequestForTest = buildTypedApprovalRequest;
+async function handleTypedBeforeToolCall(event, interceptor, logger, ctx) {
+    const sessionId = resolveHookSessionId(event, ctx);
+    // #310: a card is only worth minting when a human is there to tap it. Cron
+    // and heartbeat runs are host-keyed automation with no operator attached, so
+    // offering OpenClaw an approval request there recreates #112 exactly — the
+    // turn waits out the timeout on a decision nobody can give. Withholding
+    // `requireApproval` puts the interceptor on its unattended branch instead,
+    // which denies on the failure policy immediately and loudly.
+    const attended = !isTrustedAutomationSession(sessionId);
     try {
         await interceptor.handleToolCall({
             toolName: event.toolName,
             arguments: event.params ?? {},
             sessionId,
-            requireApproval: async (message) => {
-                throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
-            },
+            ...(attended
+                ? {
+                    requireApproval: async (message) => {
+                        throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
+                    },
+                }
+                : {}),
         });
     }
     catch (err) {
@@ -3100,7 +3132,10 @@ export default {
                     // #233: the host supplies the session on the tool CONTEXT, not the
                     // event. Without it a taint cannot be matched to the call it should
                     // gate, so the escalation would silently never fire.
-                    return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx?.sessionId);
+                    // #310: the WHOLE context, not just `sessionId` — resolveHookSessionId
+                    // also reads `sessionKey`, which is where a cron/heartbeat run's key
+                    // actually arrives, and that key decides whether a card is minted.
+                    return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx);
                 }, { priority: 80, timeoutMs: 30_000 });
                 _beforeToolCallRegistered = true;
                 // NOTE: session_end is NOT registered here — it moved out of this guard

package/dist/interceptor.js

@@ -274,6 +274,22 @@ export function formatActionGuardPrompt(toolName, v) {
         '[Approve]  [Deny]',
     ].join('\n');
 }
+/**
+ * #310: the OpenClaw-native approval card is delivered by THROWING out of the
+ * injected `requireApproval` — the plugin's typed-hook bridge catches that
+ * throw and hands `{ requireApproval }` back to the host, which draws the card.
+ * So this particular rejection is control flow, not a failure, and the catch
+ * blocks below must let it pass straight through.
+ *
+ * Matched by NAME, not by class: the class lives in the plugin entrypoint
+ * (index.ts) and this file is deliberately free of a compile-time dependency on
+ * it, the same discipline as ToolGuardVerdictLike. Swallowing it as an approval
+ * error is exactly what turned every native card into a `failure_denied` the
+ * operator never saw.
+ */
+function isTypedApprovalRequest(err) {
+    return err instanceof Error && err.name === 'TypedApprovalRequest';
+}
 // --- Audit Logging (local JSONL) ---
 /** Resolve per write so isolated tests can redirect every realtime audit path.
  * The conversation hook already honours this variable; the interceptor did not,
@@ -912,6 +928,11 @@ export function createInterceptor(config, pipeline, options) {
             approved = await withApprovalDeadline(context.requireApproval(formatActionGuardPrompt(context.toolName, v)), brokered ? brokerApprovalTimeoutMs(v.severity) : 0);
         }
         catch (err) {
+            // #310: a minted approval card, not an error. Re-thrown untouched so the
+            // typed-hook bridge can turn it into the operator's card; auditing it
+            // here would write a denial for a decision nobody has made yet.
+            if (isTypedApprovalRequest(err))
+                throw err;
             if (brokered && err instanceof ApprovalTimeout) {
                 // The asymmetric path. Silence is only ever a yes for something the
                 // broker already pre-cleared — and that returned long before here — so
@@ -1080,6 +1101,10 @@ export function createInterceptor(config, pipeline, options) {
             approved = await context.requireApproval(message);
         }
         catch (err) {
+            // #310: same bridge, same rule — the card request is not an approval
+            // failure. Everything else below stays fail-closed.
+            if (isTypedApprovalRequest(err))
+                throw err;
             const failAction = config.failurePolicy[severity];
             log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
             const entry = {

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.54.5",
+  "version": "4.54.8",
   "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,
@@ -121,7 +121,7 @@
     },
     "interceptor.conversation.posture": {
       "label": "Conversation Firewall",
-      "description": "What the conversation firewall does with a detection on the input path. off = do not scan; observe = scan, audit and alert the operator but never stop the turn (default); enforce = block the run via before_agent_run. Requires plugins.entries.shieldcortex-realtime.hooks.allowConversationAccess=true on this host — OpenClaw refuses conversation hooks without that operator grant, and ShieldCortex will never set it for you.",
+      "description": "What the conversation firewall does with a detection on the input path. off = do not scan; observe = scan, audit and alert the operator but never stop the turn (default); enforce = block the run via before_agent_run. Requires plugins.entries.shieldcortex-realtime.hooks.allowConversationAccess=true on this host \u2014 OpenClaw refuses conversation hooks without that operator grant, and ShieldCortex will never set it for you.",
       "type": "string"
     },
     "interceptor.actionGuard.notify.enabled": {
@@ -132,7 +132,7 @@
     },
     "interceptor.actionGuard.notify.webhookUrl": {
       "label": "Notify Webhook URL",
-      "description": "http(s) endpoint the notification is POSTed to. Conversation-firewall alerts carry no approve/deny affordance — there is nothing to approve.",
+      "description": "http(s) endpoint the notification is POSTed to. Conversation-firewall alerts carry no approve/deny affordance \u2014 there is nothing to approve.",
       "type": "string",
       "advanced": true
     },
@@ -156,7 +156,7 @@
     "properties": {
       "enabled": {
         "type": "boolean",
-        "description": "Unused — plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value. See #115."
+        "description": "Unused \u2014 plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value. See #115."
       },
       "binaryPath": {
         "type": "string"
@@ -190,7 +190,7 @@
           "trustOwnerInput": {
             "type": "boolean",
             "default": true,
-            "description": "Default true: a message the host attributes to the gateway OWNER is an instruction, so a detection in it is audited and alerted but never taints the session or blocks the turn. Set false on a host where the owner routinely pastes untrusted content and you would rather have the caution than the quiet. Content from anyone else — including another agent on a trusted channel — is data regardless of this setting."
+            "description": "Default true: a message the host attributes to the gateway OWNER is an instruction, so a detection in it is audited and alerted but never taints the session or blocks the turn. Set false on a host where the owner routinely pastes untrusted content and you would rather have the caution than the quiet. Content from anyone else \u2014 including another agent on a trusted channel \u2014 is data regardless of this setting."
           }
         }
       },
@@ -368,7 +368,7 @@
               "notify": {
                 "type": "object",
                 "additionalProperties": false,
-                "description": "Operator-notify transport (#143), also used by the conversation firewall’s detection sink (#225). Off unless enabled is exactly true.",
+                "description": "Operator-notify transport (#143), also used by the conversation firewall\u2019s detection sink (#225). Off unless enabled is exactly true.",
                 "properties": {
                   "enabled": {
                     "type": "boolean",
@@ -491,7 +491,7 @@
           "notify": {
             "type": "object",
             "additionalProperties": false,
-            "description": "Operator-notify transport (#143), also used by the conversation firewall’s detection sink (#225). Off unless enabled is exactly true.",
+            "description": "Operator-notify transport (#143), also used by the conversation firewall\u2019s detection sink (#225). Off unless enabled is exactly true.",
             "properties": {
               "enabled": {
                 "type": "boolean",

package/index.ts

@@ -400,6 +400,10 @@ type AgentCtx = {
 type TypedBeforeToolCallEvent = {
   toolName: string;
   params?: Record<string, unknown>;
+  // Not supplied by today's OpenClaw (the session rides on the tool context —
+  // see #233), but resolveHookSessionId prefers the event when a host does
+  // send one, and every other hook's event carries it.
+  sessionId?: string;
 };
 type TypedBeforeToolCallResult = {
   block?: boolean;
@@ -3302,6 +3306,19 @@ function truncateApprovalText(text: string, maxLength: number): string {
   return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 }
 
+/** A held command can itself contain the credential that tripped the guard, and
+ *  an approval card is a chat surface. Same rule, same phrasing and same
+ *  trade as the Telegram card path (isSecretEgress / buildCardFields in
+ *  src/defence/iron-dome/openclaw-approval-channel.ts): the operator keeps the
+ *  tool, the signals and the severity, and loses exactly the text that must not
+ *  be forwarded. */
+const SECRET_EGRESS_PROMPT = /secret|credential/iu;
+const WITHHELD_COMMAND_TEXT = "(command withheld — contains credential material)";
+/** Prompt lines safe to forward on a secret-egress hold — label-only metadata.
+ *  `Reason:` (action guard) and `Content:` (memory write) are the two lines
+ *  that quote the payload, so anything not on this list is dropped. */
+const SAFE_APPROVAL_LINE = /^(?:Tool|Action|Risk|Signals|Threats):/iu;
+
 function buildTypedApprovalRequest(message: string): NonNullable<TypedBeforeToolCallResult["requireApproval"]> {
   const lines = message
     .split(/\r?\n/u)
@@ -3309,7 +3326,13 @@ function buildTypedApprovalRequest(message: string): NonNullable<TypedBeforeTool
     .filter(Boolean)
     .filter((line) => !/^\[(?:Approve|Deny)\]/i.test(line));
   const rawTitle = (lines[0] || "ShieldCortex approval required").replace(/^🛡️\s*/u, "");
-  const details = lines.slice(1).join(" | ") || rawTitle;
+  const detailLines = lines.slice(1);
+  const withholdPayload = SECRET_EGRESS_PROMPT.test(message);
+  const details = (
+    withholdPayload
+      ? [WITHHELD_COMMAND_TEXT, ...detailLines.filter((line) => SAFE_APPROVAL_LINE.test(line))]
+      : detailLines
+  ).join(" | ") || rawTitle;
   const riskText = message.toLowerCase();
   const severity = /\b(?:critical|catastrophic|auto[-_\s]?deny|exfil|rm\s+-rf)\b/u.test(riskText)
     ? "critical"
@@ -3321,26 +3344,43 @@ function buildTypedApprovalRequest(message: string): NonNullable<TypedBeforeTool
     title: truncateApprovalText(rawTitle, 80),
     description: truncateApprovalText(details, 256),
     severity,
-    timeoutMs: 120_000,
+    // The host's own ceiling (MAX_PLUGIN_APPROVAL_TIMEOUT_MS), matching
+    // CARD_TIMEOUT_MS on the Telegram card path. 120s was the old bridge's
+    // number and it expired cards the operator was still walking back to.
+    timeoutMs: 600_000,
     timeoutBehavior: "deny",
     allowedDecisions: ["allow-once", "deny"],
   };
 }
 
+export const __buildTypedApprovalRequestForTest = buildTypedApprovalRequest;
+
 async function handleTypedBeforeToolCall(
   event: TypedBeforeToolCallEvent,
   interceptor: ReturnType<typeof createInterceptor>,
   logger: PluginApi["logger"],
-  sessionId?: string,
+  ctx?: AgentCtx,
 ): Promise<TypedBeforeToolCallResult | void> {
+  const sessionId = resolveHookSessionId(event, ctx);
+  // #310: a card is only worth minting when a human is there to tap it. Cron
+  // and heartbeat runs are host-keyed automation with no operator attached, so
+  // offering OpenClaw an approval request there recreates #112 exactly — the
+  // turn waits out the timeout on a decision nobody can give. Withholding
+  // `requireApproval` puts the interceptor on its unattended branch instead,
+  // which denies on the failure policy immediately and loudly.
+  const attended = !isTrustedAutomationSession(sessionId);
   try {
     await interceptor.handleToolCall({
       toolName: event.toolName,
       arguments: event.params ?? {},
       sessionId,
-      requireApproval: async (message: string) => {
-        throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
-      },
+      ...(attended
+        ? {
+            requireApproval: async (message: string) => {
+              throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
+            },
+          }
+        : {}),
     });
   } catch (err) {
     if (err instanceof TypedApprovalRequest) {
@@ -3648,13 +3688,16 @@ export default {
     if (!interceptorDisabledInHostConfig) {
       // Typed before_tool_call hook: this is the OpenClaw agent-loop gate that
       // can block or require approval before the selected tool executes.
-      api.on('before_tool_call', async (event: TypedBeforeToolCallEvent, ctx?: { sessionId?: string }) => {
+      api.on('before_tool_call', async (event: TypedBeforeToolCallEvent, ctx?: AgentCtx) => {
         const interceptor = await initInterceptor();
         if (!interceptor) return;
         // #233: the host supplies the session on the tool CONTEXT, not the
         // event. Without it a taint cannot be matched to the call it should
         // gate, so the escalation would silently never fire.
-        return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx?.sessionId);
+        // #310: the WHOLE context, not just `sessionId` — resolveHookSessionId
+        // also reads `sessionKey`, which is where a cron/heartbeat run's key
+        // actually arrives, and that key decides whether a card is minted.
+        return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx);
       }, { priority: 80, timeoutMs: 30_000 });
       _beforeToolCallRegistered = true;
       // NOTE: session_end is NOT registered here — it moved out of this guard

package/interceptor.ts

@@ -547,6 +547,23 @@ export function formatActionGuardPrompt(toolName: string, v: ToolGuardVerdictLik
   ].join('\n');
 }
 
+/**
+ * #310: the OpenClaw-native approval card is delivered by THROWING out of the
+ * injected `requireApproval` — the plugin's typed-hook bridge catches that
+ * throw and hands `{ requireApproval }` back to the host, which draws the card.
+ * So this particular rejection is control flow, not a failure, and the catch
+ * blocks below must let it pass straight through.
+ *
+ * Matched by NAME, not by class: the class lives in the plugin entrypoint
+ * (index.ts) and this file is deliberately free of a compile-time dependency on
+ * it, the same discipline as ToolGuardVerdictLike. Swallowing it as an approval
+ * error is exactly what turned every native card into a `failure_denied` the
+ * operator never saw.
+ */
+function isTypedApprovalRequest(err: unknown): boolean {
+  return err instanceof Error && err.name === 'TypedApprovalRequest';
+}
+
 // --- Audit Logging (local JSONL) ---
 
 /** Resolve per write so isolated tests can redirect every realtime audit path.
@@ -1297,6 +1314,10 @@ export function createInterceptor(
         brokered ? brokerApprovalTimeoutMs(v.severity) : 0,
       );
     } catch (err) {
+      // #310: a minted approval card, not an error. Re-thrown untouched so the
+      // typed-hook bridge can turn it into the operator's card; auditing it
+      // here would write a denial for a decision nobody has made yet.
+      if (isTypedApprovalRequest(err)) throw err;
       if (brokered && err instanceof ApprovalTimeout) {
         // The asymmetric path. Silence is only ever a yes for something the
         // broker already pre-cleared — and that returned long before here — so
@@ -1477,6 +1498,9 @@ export function createInterceptor(
     try {
       approved = await context.requireApproval(message);
     } catch (err) {
+      // #310: same bridge, same rule — the card request is not an approval
+      // failure. Everything else below stays fail-closed.
+      if (isTypedApprovalRequest(err)) throw err;
       const failAction = config.failurePolicy[severity];
       log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
       const entry: InterceptAuditEntry = {

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.54.5",
+  "version": "4.54.8",
   "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,
@@ -121,7 +121,7 @@
     },
     "interceptor.conversation.posture": {
       "label": "Conversation Firewall",
-      "description": "What the conversation firewall does with a detection on the input path. off = do not scan; observe = scan, audit and alert the operator but never stop the turn (default); enforce = block the run via before_agent_run. Requires plugins.entries.shieldcortex-realtime.hooks.allowConversationAccess=true on this host — OpenClaw refuses conversation hooks without that operator grant, and ShieldCortex will never set it for you.",
+      "description": "What the conversation firewall does with a detection on the input path. off = do not scan; observe = scan, audit and alert the operator but never stop the turn (default); enforce = block the run via before_agent_run. Requires plugins.entries.shieldcortex-realtime.hooks.allowConversationAccess=true on this host \u2014 OpenClaw refuses conversation hooks without that operator grant, and ShieldCortex will never set it for you.",
       "type": "string"
     },
     "interceptor.actionGuard.notify.enabled": {
@@ -132,7 +132,7 @@
     },
     "interceptor.actionGuard.notify.webhookUrl": {
       "label": "Notify Webhook URL",
-      "description": "http(s) endpoint the notification is POSTed to. Conversation-firewall alerts carry no approve/deny affordance — there is nothing to approve.",
+      "description": "http(s) endpoint the notification is POSTed to. Conversation-firewall alerts carry no approve/deny affordance \u2014 there is nothing to approve.",
       "type": "string",
       "advanced": true
     },
@@ -156,7 +156,7 @@
     "properties": {
       "enabled": {
         "type": "boolean",
-        "description": "Unused — plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value. See #115."
+        "description": "Unused \u2014 plugin on/off is controlled by plugins.entries[id].enabled on the host, not this nested config value. See #115."
       },
       "binaryPath": {
         "type": "string"
@@ -190,7 +190,7 @@
           "trustOwnerInput": {
             "type": "boolean",
             "default": true,
-            "description": "Default true: a message the host attributes to the gateway OWNER is an instruction, so a detection in it is audited and alerted but never taints the session or blocks the turn. Set false on a host where the owner routinely pastes untrusted content and you would rather have the caution than the quiet. Content from anyone else — including another agent on a trusted channel — is data regardless of this setting."
+            "description": "Default true: a message the host attributes to the gateway OWNER is an instruction, so a detection in it is audited and alerted but never taints the session or blocks the turn. Set false on a host where the owner routinely pastes untrusted content and you would rather have the caution than the quiet. Content from anyone else \u2014 including another agent on a trusted channel \u2014 is data regardless of this setting."
           }
         }
       },
@@ -368,7 +368,7 @@
               "notify": {
                 "type": "object",
                 "additionalProperties": false,
-                "description": "Operator-notify transport (#143), also used by the conversation firewall’s detection sink (#225). Off unless enabled is exactly true.",
+                "description": "Operator-notify transport (#143), also used by the conversation firewall\u2019s detection sink (#225). Off unless enabled is exactly true.",
                 "properties": {
                   "enabled": {
                     "type": "boolean",
@@ -491,7 +491,7 @@
           "notify": {
             "type": "object",
             "additionalProperties": false,
-            "description": "Operator-notify transport (#143), also used by the conversation firewall’s detection sink (#225). Off unless enabled is exactly true.",
+            "description": "Operator-notify transport (#143), also used by the conversation firewall\u2019s detection sink (#225). Off unless enabled is exactly true.",
             "properties": {
               "enabled": {
                 "type": "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "4.54.5",
+  "version": "4.54.8",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,10 +24,10 @@
   ],
   "scripts": {
     "pack:verify": "npm pack --dry-run",
-    "prepublishOnly": "node -e \"if(!require('fs').existsSync('dist/index.js'))throw new Error('plugin dist/index.js missing — run `npm run build:ts` from the repo root before publishing')\""
+    "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.18.3 <5.0.0",
+    "shieldcortex": "^4.54.8",
     "openclaw": ">=2026.3.22"
   },
   "peerDependenciesMeta": {