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

package/MCP.md

@@ -11,7 +11,7 @@ resource authorization.
 Available in `0.1.0-alpha.5` and later compatible alpha releases:
 
 ```sh
-npm install @webdecoy/ai-protection@0.1.0-alpha.11 @modelcontextprotocol/sdk@1.31.0
+npm install @webdecoy/ai-protection@0.1.0-alpha.17 @modelcontextprotocol/sdk@1.31.0
 ```
 
 Requires Node 22.22.3+ and MCP SDK **1.31.0**. The MCP SDK is an optional peer, so
@@ -372,3 +372,40 @@ 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.
+
+### Per-tool pauses (alpha.16)
+
+Enable `sharedRuntime.toolPause: true` after updating the hosted runtime. Tool
+pauses cover the exact property, configured server ID and action/tool name,
+across callers and schema versions. MCP supplies tool metadata automatically;
+plain action integrations must provide `toolSchema` on every action. Renaming a
+server/tool changes this identity; an old pause does not cover the new name.
+Tool-only checks do not require `reportCaller` or send a caller pseudonym.
+
+Owners/admins manage a tool pause in AI Protection, with an explicit scope
+review, reason, expiry and audit history. Saved controls remain listed even if
+the tool disappears from recent inventory. Other server/tool names stay active.
+The tool remains discoverable; work already admitted is not cancelled.
+
+When both `callerPause` and `toolPause` are enabled, they share one online request
+and both checks are reported. Caller denial takes precedence if both deny.
+`callerPauseTimeoutMs` controls the shared deadline (default 1000 ms). There is
+no retry/cache; unavailable, timed-out or malformed checks fail open with explicit
+evidence. Application permissions still apply before this check. Saving is not
+an acknowledgment from every instance. Exact revision evidence permits the
+dashboard to show an SDK-reported tool denial separately from saved state.
+
+## Caller identity and secret rotation
+
+See the [schema-1 caller contract](https://github.com/WebDecoy/ai-protection/blob/main/CALLER_IDENTITY.md) for authenticated/claimed/unavailable distinctions, Node/Go bounds, OAuth client separation, unsupported delegation/signers and caller pseudonym retention/rotation.
+
+## Local reporting diagnostics (alpha.17)
+
+`sharedRuntime.onReport(receipt)` is an optional best-effort local callback for an
+HTTP report result. Receipts contain `schema: 1`, `eventId`, `actionId` and
+`status: 'accepted' | 'unavailable'`. Correlate with the same IDs in `onEvent`.
+Accepted means HTTP success; inspect dashboard evidence separately for retention.
+Missing receipts are unknown, including queue drops or shutdown. At most 100
+report observers can be pending per action guard; exceptions or hung observers do
+not rerun tool work or change its result. Do not put protected side effects in
+observers. See the source [setup diagnostics](examples/mcp/SETUP.md).

package/action-runtime.mjs

@@ -15,9 +15,20 @@ export function prepareActionRuntime(options, definitions) {
     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.toolPause !== undefined && typeof config.toolPause !== 'boolean')throw Error('Invalid tool pause option');
+  if(config.toolPause && [...definitions.values()].some(d=>!d.toolSchema))throw Error('Tool pause requires toolSchema on every action');
   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');
+  if(config.onReport !== undefined && typeof config.onReport !== 'function')throw Error('Invalid reporting observer');
+  const reportingObserver=config.onReport;
+  let pendingObservers=0;
+  const observeReport=(event,status)=>{
+    if(!reportingObserver||pendingObservers>=100)return;
+    pendingObservers++;
+    const receipt=Object.freeze({schema:1,eventId:event.eventId,actionId:event.actionId,status});
+    Promise.resolve().then(()=>reportingObserver(receipt)).catch(()=>{}).finally(()=>{pendingObservers--;});
+  };
   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){
@@ -45,9 +56,12 @@ export function prepareActionRuntime(options, definitions) {
         degraded:event.checks.some(c=>c.decision==='unavailable'),checks,handler_attempted:event.attempted,
         action:event.decision==='deny'?'denied':event.outcome==='unknown'?'handler_error':'forwarded',
         tool_action:{action_id:event.actionId,name:event.action,policy_version:event.policyVersion,outcome:event.outcome,...(event.toolSchema?{tool_schema:{server_id:event.toolSchema.serverId,hash:event.toolSchema.hash,...(event.toolSchema.decoy?{decoy:event.toolSchema.decoy}:{}),...(event.toolSchema.effect?{effect:event.toolSchema.effect}:{}),...(event.toolSchema.permissions?{permissions:event.toolSchema.permissions}:{})}}:{}),...(event.caller?{caller:event.caller}:{}),...(event.work?{work:event.work}:{})}};
-      const response=await fetch(new URL('/api/v1/sdk/ai-abuse/reports',url),{method:'POST',redirect:'error',signal,
-        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');
+      try {
+        const response=await fetch(new URL('/api/v1/sdk/ai-abuse/reports',url),{method:'POST',redirect:'error',signal,
+          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');
+        observeReport(event,'accepted');
+      } catch(error) { observeReport(event,'unavailable'); throw error; }
     }});
   const checkCallerPause = c.callerPause ? async (caller,signal) => {
     signal.throwIfAborted();const started=performance.now();
@@ -70,7 +84,35 @@ export function prepareActionRuntime(options, definitions) {
     } 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()};
+  const checkToolPause = c.toolPause ? async (caller,name,toolSchema,signal) => {
+    signal.throwIfAborted();const started=performance.now();
+    const kinds=c.callerPause?['caller','tool']:['tool'];
+    let checks=kinds.map(kind=>({id:kind+'_pause',source:'shared',mode:'enforce',decision:'unavailable',reason:kind+'_pause_unavailable',durationMs:0})),denial;
+    try {
+      const id=c.callerPause?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:2,caller:id,server_id:toolSchema.serverId,tool:name})
+      });
+      if(!response.ok){await response.body?.cancel();throw Error('Tool control unavailable');}
+      const value=await readJSON(response,4096);
+      if(value.schema!==2||value.property_id!==c.propertyId.toLowerCase()||value.caller!==id||value.server_id!==toolSchema.serverId||value.tool!==name||(!c.callerPause&&value.caller_control!==null))throw Error('Invalid tool control response');
+      // Validate the entire combined response before accepting either decision.
+      const checked=kinds.map(kind=>{
+        const control=value[kind+'_control'];
+        if(!control||typeof control.allowed!=='boolean'||control.reason!==kind+(control.allowed?'_allowed':'_paused')||
+          (control.control_revision!=null&&!validPropertyID(control.control_revision)))throw Error('Invalid control evidence');
+        return {id:kind+'_pause',source:'shared',mode:'enforce',decision:control.allowed?'allow':'deny',reason:control.reason,durationMs:0,
+          ...(control.control_revision?{controlRevision:control.control_revision.toLowerCase()}:{})};
+      });
+      checks=checked;const denied=checks.find(check=>check.decision==='deny');
+      if(denied)denial={reason:denied.reason,status:403};
+    } catch {signal.throwIfAborted();}
+    const durationMs=Math.max(0,performance.now()-started);
+    return {checks:checks.map(check=>({...check,durationMs})),denial};
+  }:null;
+  return {limits,checkCallerPause,checkToolPause,callerEvidence:caller=>actionCallerEvidence(c,caller),report:event=>reporter.send(event),flush:()=>reporter.flush()};
 }
 
 export function actionCallerEvidence(config,caller) {

package/actions.d.mts

@@ -66,19 +66,28 @@ export interface ActionLimits {
   tenantQuota?: ActionQuota;
   concurrency?: {ruleId:string;accountLimit:number;featureLimit:number;mode?:'observe'|'enforce';failureMode?:'open'|'closed';ttlSeconds?:number;maxSeconds?:number;timeoutMs?:number};
 }
+export interface ActionReportReceipt {
+ readonly schema:1;readonly eventId:string;readonly actionId:string;
+ /** HTTP success response only; not proof of retained dashboard evidence. */
+ readonly status:'accepted'|'unavailable';
+}
 export interface ActionRuntime {
+  /** Best-effort local HTTP reporting observer. Bounded to 100 pending calls; missing receipts remain unknown. Never contains raw response/error/identity data. */
+  onReport?(receipt:ActionReportReceipt):void|Promise<void>;
   /** 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. */
+  /** Opt-in tool pause by property/server/name across callers and schema versions. Requires toolSchema on each action; no caller reporting required. Combines with callerPause in one RPC and fails open on unavailable controls. */
+  toolPause?:boolean;
+  /** Caller/tool-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;
 }
 export interface ActionDefinition {
   /** Optional non-secret server label and canonical SHA-256 schema hash. MCP discovery fills this automatically.
-   * Requires a runtime supporting tool_schema evidence; does not change admission.
+   * Requires a runtime supporting tool_schema evidence. With toolPause enabled, serverId and the action name identify the control scope.
    */
   toolSchema?: ToolSchemaEvidence;
   limits?: ActionLimits;

package/actions.mjs

@@ -133,7 +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){
+      if(runtime?.checkToolPause){
+        const r=await runtime.checkToolPause(caller,name,action.toolSchema,admissionSignal);checks.push(...r.checks);
+        if(r.denial)deny(r.denial.reason,r.denial.status);
+      }else if(runtime?.checkCallerPause){
         const r=await runtime.checkCallerPause(caller,admissionSignal);checks.push(r.check);
         if(r.denial)deny(r.denial.reason,r.denial.status);
       }

package/mcp.mjs

@@ -31,7 +31,6 @@ export function createProtectedMCPHandler(options) {
         }
     }
     // Validate the closed registry at startup, not only after a client arrives.
-    createActionProtection({ policyVersion: options.policyVersion, authenticate: options.authenticate, actions: tools, sharedRuntime: options.sharedRuntime });
     for (const tool of Object.values(tools))
         for (const scope of tool.requiredScopes)
             if (!/^[\x21\x23-\x5b\x5d-\x7e]+$/.test(scope))
@@ -50,6 +49,8 @@ export function createProtectedMCPHandler(options) {
         [name, createHash('sha256').update(canonical(JSON.parse(JSON.stringify(tool.inputSchema)))).digest('hex')])) : {};
     if (options.discovery) for (const [name, tool] of Object.entries(tools))
         tool.toolSchema = Object.freeze({serverId:options.discovery.serverId,hash:hashes[name],...(decoys.has(name)?{decoy:decoys.get(name)}:{effect:inferToolEffect(name,tool.inputSchema,tool.annotations),permissions:Object.freeze({schema:1,required_scopes:tool.requiredScopes.length,application_authorization:true,additional_policy:typeof tool.policy==='function'})})});
+    // Validate after discovery supplies the schema required by tool pauses.
+    createActionProtection({ policyVersion: options.policyVersion, authenticate: options.authenticate, actions: tools, sharedRuntime: options.sharedRuntime });
     const runtime = options.sharedRuntime && { ...options.sharedRuntime };
     const serverId = options.discovery?.serverId;
     const catalogReporter = options.discovery ? createReporter({

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.15",
+  "version": "0.1.0-alpha.17",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",