@webdecoy/ai-protection 0.1.0-alpha.16 → 0.1.0-alpha.18

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.18 @modelcontextprotocol/sdk@1.31.0
 ```
 
 Requires Node 22.22.3+ and MCP SDK **1.31.0**. The MCP SDK is an optional peer, so
@@ -161,9 +161,17 @@ Discovery uses schema-3 reports on the existing reporting endpoint; deploy a
 compatible hosted runtime first. Old runtimes reject these optional reports
 without affecting tool listing. Reporting has bounded pending work and a deadline,
 never blocks authorization, and does not retry. Call `await handler.flush()` at a
-host shutdown/lifecycle boundary to drain pending discovery reports; it does not
-wait for active tool calls or action reports. Abruptly terminated hosts can lose
-reports. Discovery advertisements never increment tool action or request counts.
+host shutdown/lifecycle boundary to drain discovery and tool-action reports already
+queued when flush begins. From alpha.18, the action reporting queue is shared by
+all calls on one handler and is bounded by `sharedRuntime.maxPendingReports`
+(default 100); discovery uses a separately bounded queue. Full queues drop reports
+without retrying or blocking tool execution.
+
+Stop accepting new requests and let active tools complete or cancel before the
+final flush. Flush does not wait for running tools, future reports, arbitrary
+`onEvent`/`onReport` callbacks or dashboard persistence. Reporting deadlines still
+apply; an unavailable/timeout/drop is not delivery success. Abruptly terminated
+hosts can lose reports. Discovery advertisements never increment tool action or request counts.
 
 
 ### Calls before discovery (alpha.8+)
@@ -394,3 +402,18 @@ no retry/cache; unavailable, timed-out or malformed checks fail open with explic
 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

@@ -20,6 +20,15 @@ export function prepareActionRuntime(options, definitions) {
   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){
@@ -47,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();

package/actions.d.mts

@@ -66,7 +66,14 @@ 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. */

package/mcp.d.mts

@@ -44,6 +44,6 @@ export interface ProtectedMCPOptions {
  */
 export function createProtectedMCPHandler(options: ProtectedMCPOptions):
   ((request: IncomingMessage, response: ServerResponse) => Promise<void>) & {
-    /** Drain pending discovery reports at shutdown. Does not wait for running tools. */
+    /** Drain already queued discovery/action reports within reporting deadlines. Does not wait for running tools, future reports or observer callbacks. */
     flush(): Promise<void>;
   };

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,12 @@ 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.
+    if (typeof options.authenticate !== 'function') throw Error('Invalid MCP authenticator');
+    // One bounded reporting runtime per handler. The caller is passed per run,
+    // never held in mutable shared request state. HTTP authentication stays above
+    // dispatch; the action boundary independently validates and snapshots it.
+    const guard = createActionProtection({ policyVersion: options.policyVersion, authenticate: caller => caller, actions: tools, sharedRuntime: options.sharedRuntime, onEvent: options.onEvent });
     const runtime = options.sharedRuntime && { ...options.sharedRuntime };
     const serverId = options.discovery?.serverId;
     const catalogReporter = options.discovery ? createReporter({
@@ -176,7 +181,6 @@ export function createProtectedMCPHandler(options) {
                 res.end();
                 return;
             }
-            const guard = createActionProtection({ policyVersion: options.policyVersion, authenticate: () => caller, actions: tools, sharedRuntime: options.sharedRuntime, onEvent: options.onEvent });
             // Scope escalation belongs at HTTP level, before the SDK opens an SSE stream.
             if (message.method === 'tools/call' && typeof message.params?.name === 'string') {
                 const definition = Object.hasOwn(tools, message.params.name) ? tools[message.params.name] : undefined;
@@ -184,7 +188,7 @@ export function createProtectedMCPHandler(options) {
                     // Run the same admission path for its sanitized denial evidence. It cannot
                     // dispatch with a missing required scope, regardless of discovery results.
                     try {
-                        await guard.run(message.params.name, {}, null, { signal: disconnected.signal });
+                        await guard.run(message.params.name, {}, caller, { signal: disconnected.signal });
                     }
                     catch (e) {
                         if (!(e instanceof ActionDenied))
@@ -224,7 +228,7 @@ export function createProtectedMCPHandler(options) {
                 running.started = true;
                 const signal = AbortSignal.any([extra.signal, disconnected.signal, running.controller.signal]);
                 try {
-                    return await guard.run(request.params.name, (request.params.arguments ?? {}), null, { signal });
+                    return await guard.run(request.params.name, (request.params.arguments ?? {}), caller, { signal });
                 }
                 catch (e) {
                     if (signal.aborted)
@@ -236,7 +240,6 @@ export function createProtectedMCPHandler(options) {
                 }
                 finally {
                     cleanup();
-                    void guard.flush();
                 }
             });
             await server.connect(transport);
@@ -249,5 +252,5 @@ export function createProtectedMCPHandler(options) {
                 res.destroy();
         }
     };
-    return Object.assign(handle, { flush: async () => { await catalogReporter?.flush(); } });
+    return Object.assign(handle, { flush: async () => { await Promise.all([catalogReporter?.flush(), guard.flush()]); } });
 }

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