@webdecoy/ai-protection 0.1.0-alpha.13 → 0.1.0-alpha.15

package/MCP.md

@@ -335,3 +335,40 @@ is normal client behavior, not an enforcement decision. Large listings are split
 into batches of up to 64 tools; each batch is a report, not a distinct listing
 count. Unattributed older catalogs are never assigned to a caller retrospectively.
 Initialization and automatic containment remain outside this feature.
+
+### Manual caller pauses (alpha.14)
+
+Enable `sharedRuntime: { ...runtimeOptions, reportCaller: true, callerPause: true }`
+on each protected server after updating the hosted receiver. An organization owner
+or admin can then open a caller timeline and review a pause or resume for that
+property. A reason is required. Pauses can expire or remain until resumed.
+Concurrent stale edits are rejected and each successful change is audited.
+
+The check runs after application permissions and before shared limits or execution,
+for each admitted tool call. It adds one network request with a 1000 ms default deadline (`callerPauseTimeoutMs`, range 1–10000 ms),
+no retries and no decision cache. Very short deadlines can fail open during cold API-key authentication. A saved pause applies to subsequent successful
+checks; a call already admitted or running is not cancelled. Resuming needs no cache
+invalidation. A restart reads current state on the next check.
+
+Outages, timeouts, malformed responses and unavailable controls fail open with
+`caller_pause_unavailable` evidence; authorization and other limits still apply.
+A saved pause is not a delivery acknowledgment and cannot guarantee enforcement
+while disconnected. This control does not revoke OAuth credentials.
+
+Scope is the existing property-scoped pseudonym derived from issuer, tenant and
+subject. Keep `subjectSecret` consistent across replicas. Rotating it changes the
+pseudonym and existing pauses no longer match. Only opt-in Node action integrations
+are covered, including this MCP adapter; Python/Go and unwrapped tools are not.
+Listings and initialization remain available; this pauses new tool execution.
+No automatic pause is applied after a decoy call.
+
+#### Pause feedback (alpha.15)
+
+The SDK includes the runtime's control revision in action check reports when
+available. The dashboard can then distinguish a saved pause from an SDK-reported
+denial for that exact revision, with server receipt time and request ID. Delayed
+reports from an earlier pause do not confirm a later save. Older runtimes omit
+the revision; enforcement still works but revision feedback remains unknown.
+Report delivery is best effort and requires the normal reporting queue/flush.
+This evidence is not acknowledgment from every replica, provider revocation, or
+independent proof of execution. Outage behavior remains fail open.

package/action-runtime.mjs

@@ -2,6 +2,7 @@ import {prepareWork} from './work.mjs';
 import {prepareQuota,quotaHash} from './quota.mjs';
 import {prepareConcurrency} from './concurrency.mjs';
 import {validPropertyID} from './account.mjs';
+import {readJSON} from './transport.mjs';
 import {createReporter} from './reporting.mjs';
 
 export function prepareActionRuntime(options, definitions) {
@@ -13,6 +14,10 @@ export function prepareActionRuntime(options, definitions) {
     typeof config.webdecoyKey!=='string'||!config.webdecoyKey||/[^\x21-\x7e]/.test(config.webdecoyKey)||
     typeof config.subjectSecret!=='string'||!config.subjectSecret.isWellFormed()||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
   if(config.reportCaller !== undefined && typeof config.reportCaller !== "boolean")throw Error("Invalid caller reporting option");
+  if(config.callerPause !== undefined && typeof config.callerPause !== 'boolean')throw Error('Invalid caller pause option');
+  if(config.callerPause && !config.reportCaller)throw Error('Caller pause requires caller reporting');
+  const pauseTimeout=config.callerPauseTimeoutMs??1000;
+  if(!Number.isInteger(pauseTimeout)||pauseTimeout<1||pauseTimeout>10000)throw Error('Invalid caller pause timeout');
   const c={...config};const limits=new Map(),ruleIDs=new Set();
   const subject=(ctx,tenant)=>({accountId:tenant?quotaHash(c.subjectSecret,'webdecoy.actions.tenant.v1',ctx.caller.tenant):quotaHash(c.subjectSecret,'webdecoy.actions.caller.v1',ctx.caller.issuer,ctx.caller.tenant,ctx.caller.subject)});
   for(const [name,d] of definitions){
@@ -35,7 +40,7 @@ export function prepareActionRuntime(options, definitions) {
   const reporter=createReporter({reportingTimeoutMs:c.reportingTimeoutMs??1000,maxPendingReports:c.maxPendingReports??100,
     onObservation:async(event,{signal})=>{
       const checks=[{id:'action_boundary',source:'local',mode:'enforce',decision:event.decision,reason:event.reason,duration_ms:0},
-        ...event.checks.map(check=>({id:check.id,source:check.source,mode:check.mode,decision:check.decision,reason:check.reason,duration_ms:check.durationMs}))];
+        ...event.checks.map(check=>({id:check.id,source:check.source,mode:check.mode,decision:check.decision,reason:check.reason,duration_ms:check.durationMs,...(check.controlRevision?{control_revision:check.controlRevision}:{})}))];
       const payload={schema:2,request_id:event.eventId,timestamp:event.timestamp,decision:event.decision,reason:event.reason,
         degraded:event.checks.some(c=>c.decision==='unavailable'),checks,handler_attempted:event.attempted,
         action:event.decision==='deny'?'denied':event.outcome==='unknown'?'handler_error':'forwarded',
@@ -44,7 +49,28 @@ export function prepareActionRuntime(options, definitions) {
         headers:{Authorization:`Bearer ${c.webdecoyKey}`,'X-WebDecoy-Property-ID':c.propertyId,'Content-Type':'application/json'},body:JSON.stringify(payload)});
       await response.body?.cancel();if(!response.ok)throw Error('Action reporting unavailable');
     }});
-  return {limits,callerEvidence:caller=>actionCallerEvidence(c,caller),report:event=>reporter.send(event),flush:()=>reporter.flush()};
+  const checkCallerPause = c.callerPause ? async (caller,signal) => {
+    signal.throwIfAborted();const started=performance.now();
+    const check={id:'caller_pause',source:'shared',mode:'enforce',decision:'unavailable',reason:'caller_pause_unavailable',durationMs:0};
+    let denial;
+    try {
+      const id=actionCallerEvidence(c,caller).id;
+      const response=await fetch(new URL('/api/v1/sdk/ai-abuse/caller-pause',c.webdecoyUrl),{
+        method:'POST',redirect:'error',signal:AbortSignal.any([signal,AbortSignal.timeout(pauseTimeout)]),
+        headers:{Authorization:`Bearer ${c.webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':c.propertyId},body:JSON.stringify({schema:1,caller:id})
+      });
+      if(!response.ok){await response.body?.cancel();throw Error('Caller control unavailable');}
+      const value=await readJSON(response,2048);
+      if(value.schema!==1||value.property_id!==c.propertyId.toLowerCase()||value.caller!==id||typeof value.allowed!=='boolean'||value.reason!==(value.allowed?'caller_allowed':'caller_paused'))throw Error('Invalid caller control response');
+      // Older runtimes omit revision evidence. Never invent it from receipt time.
+      if(value.control_revision != null && (!validPropertyID(value.control_revision)||value.control_revision==='00000000-0000-0000-0000-000000000000'))throw Error('Invalid caller control revision');
+      check.decision=value.allowed?'allow':'deny';check.reason=value.reason;
+      if(value.control_revision != null)check.controlRevision=value.control_revision.toLowerCase();
+      if(!value.allowed)denial={reason:'caller_paused',status:403};
+    } catch { signal.throwIfAborted(); }
+    check.durationMs=Math.max(0,performance.now()-started);return {check,denial};
+  }:null;
+  return {limits,checkCallerPause,callerEvidence:caller=>actionCallerEvidence(c,caller),report:event=>reporter.send(event),flush:()=>reporter.flush()};
 }
 
 export function actionCallerEvidence(config,caller) {

package/actions.d.mts

@@ -48,7 +48,7 @@ export interface ActionEvent {
   readonly schema: 1;
   readonly eventId: string;
   readonly timestamp: string;
-  readonly checks: readonly {id:string;source:string;mode:string;decision:string;reason:string;durationMs:number}[];
+  readonly checks: readonly {id:string;source:string;mode:string;decision:string;reason:string;durationMs:number;controlRevision?:string}[];
   readonly actionId: string;
   readonly action: string;
   readonly policyVersion: string;
@@ -69,6 +69,10 @@ export interface ActionLimits {
 export interface ActionRuntime {
   /** Opt in to scoped caller pseudonyms in reports. Requires a supporting runtime. Default false. */
   reportCaller?:boolean;
+  /** Opt-in online caller pause check before work. Requires reportCaller. Fails open on timeout (default 1000ms); no cache, retry or in-flight cancellation. */
+  callerPause?:boolean;
+  /** Caller-pause RPC deadline, 1–10000ms; default 1000ms. Short deadlines can fail open during cold authentication. */
+  callerPauseTimeoutMs?:number;
   webdecoyUrl:string;webdecoyKey:string;propertyId:string;subjectSecret:string;
   reportingTimeoutMs?:number;maxPendingReports?:number;
 }

package/actions.mjs

@@ -133,6 +133,10 @@ export function createActionProtection(options) {
       // Shared limits run only after application permission checks. Their own
       // RPC deadlines are separate from local admission and detector availability.
       clearTimeout(timer);
+      if(runtime?.checkCallerPause){
+        const r=await runtime.checkCallerPause(caller,admissionSignal);checks.push(r.check);
+        if(r.denial)deny(r.denial.reason,r.denial.status);
+      }
       const controls=runtime?.limits.get(name);
       for(const gate of controls?.gates??[]){
         const r=await gate(context,admissionSignal);checks.push(r.check);

package/package.json

@@ -11,7 +11,7 @@
     "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts test/mcp-types.mts",
     "test:workers": "node --test test/workers/*.test.mjs"
   },
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",