@webdecoy/ai-protection 0.1.0-alpha.7 → 0.1.0-alpha.9

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.7 @modelcontextprotocol/sdk@1.31.0
+npm install @webdecoy/ai-protection@0.1.0-alpha.9 @modelcontextprotocol/sdk@1.31.0
 ```
 
 Requires Node 22.22.3+ and MCP SDK **1.31.0**. The MCP SDK is an optional peer, so
@@ -143,7 +143,7 @@ include tenant IDs, hostnames containing secrets, or customer information.
 
 An authenticated MCP client calls `tools/list`. Each nonempty response queues a
 best-effort advertisement of the visible tool names and SHA-256 input-schema
-hashes. The AI Protection dashboard shows **Advertised MCP tools**, including
+hashes. The AI Protection dashboard shows **MCP tool inventory**, including
 tools that have never executed. This does not scan unwrapped servers, hidden tools,
 resources, prompts or alternate routes. No network request is made at handler
 construction. Discovery is off unless configured and requires sharedRuntime.
@@ -164,3 +164,75 @@ never blocks authorization, and does not retry. Call `await handler.flush()` at
 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.
+
+
+### Calls before discovery (alpha.8+)
+
+With `discovery` enabled, the adapter also attaches the registered server label
+and schema fingerprint to each `tools/call` action report. This includes local
+permission/scope denials for registered tools. It works before a client calls
+`tools/list`; no listing round trip is required to execute an authorized tool.
+Unknown tool names and requests rejected before authentication do not gain
+registry metadata. Turning discovery off omits the new call metadata too.
+
+The inventory combines advertisements and action evidence by property, server
+label and tool name. Attempt/start/completion reports sharing an action ID count
+once. Counts include denied attempts, so they are not successful-execution totals.
+“Call evidence only” means no advertisement was captured in the bounded seven-day
+sample. Clients can call directly; hidden scopes, sampling and missing telemetry
+also limit coverage. This is not an attack or permission-gap verdict. Older action
+reports without metadata still appear in the general activity table, aggregated
+by tool name across servers; their server/schema association remains unknown.
+
+Deploy a runtime accepting optional `tool_action.tool_schema` before upgrading an
+integration with discovery enabled. Older runtimes reject affected action reports
+without changing admission. The action API also supports optional `toolSchema:
+{serverId, hash}` on trusted registered definitions; it is snapshotted and validated,
+never read from tool arguments. This is SDK-reported metadata, not authorization
+or independent verification of a schema.
+
+
+### Advisory side effects (alpha.9+)
+
+With discovery enabled, the SDK adds a fixed classification and reason code to
+catalog/call metadata: `unknown`, `read_only`, `mutating`, or `destructive`.
+This is heuristic inference, not a prompt scanner, authorization policy, verified
+behavior or proof that side effects occurred. Classification never allows or
+blocks a request. Existing validate/authorize/scopes/limits still control dispatch.
+
+You may supply MCP boolean hints on a protected tool:
+
+```ts
+annotations: { readOnlyHint: true, destructiveHint: false },
+```
+
+Supported annotations are readOnlyHint, destructiveHint, idempotentHint and
+openWorldHint. The adapter snapshots those booleans and includes them in scoped
+MCP listing responses. Only classification codes enter WebDecoy reports; raw
+annotations, schemas and descriptions are not uploaded. The schema fingerprint
+continues to cover inputSchema, not annotations or implementation code.
+
+The classifier checks tokenized tool names and explicit top-level `action`,
+`operation` or `method` selectors (`const`/up to 64 enum values). It does not
+resolve schema references, scan arbitrary text/arguments, execute tools, or call a
+model. Destructive/mutating signals take precedence over a contradictory read-only
+hint and are labeled conflicting. With no useful signals it reports unknown.
+Name heuristics can be wrong (for example, a status tool named after deletion).
+As the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+requires, annotations must not be treated as guarantees from an untrusted server.
+
+The dashboard shows inferred evidence separately from a customer classification.
+Use **Review classification** to select a label or return to SDK inference.
+Overrides are property/server/tool settings bound to the current input-schema
+hash; a different hash falls back to inference and prompts review. Changes to
+annotations or implementation without a schema change do not invalidate an
+override, so review those changes yourself. A saved classification changes only
+the dashboard label; it is not read by runtime enforcement. Overrides persist as
+customer settings until reset or property deletion; SDK evidence retains its
+seven-day window. Where evidence disagrees for the latest received schema, the
+review order is destructive, mutating, unknown, then read-only. Older SDKs without
+classification metadata remain unknown, though customers can label their tools.
+
+Requires a runtime accepting optional `effect` evidence. Deploy it before
+upgrading a discovery-enabled integration. Large registries are split into
+bounded catalog batches so added metadata stays within report body limits.

package/action-runtime.mjs

@@ -39,7 +39,7 @@ export function prepareActionRuntime(options, definitions) {
       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',
-        tool_action:{action_id:event.actionId,name:event.action,policy_version:event.policyVersion,outcome:event.outcome,...(event.caller?{caller:event.caller}:{}),...(event.work?{work:event.work}:{})}};
+        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.effect?{effect:event.toolSchema.effect}:{})}}:{}),...(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');

package/actions.d.mts

@@ -32,7 +32,15 @@ export interface ActionWork {
  /** Confirmed work after completed execution. No async/detached measurement; excess/unknown retains maximum. */
  measure?(result:unknown,context:ActionContext):number;
 }
+/** Server-supplied metadata, not proof of a verified schema or authorization. */
+export interface ToolEffectEvidence {
+ readonly schema: 1;
+ readonly level: 'unknown' | 'read_only' | 'mutating' | 'destructive';
+ readonly reason: 'insufficient_signals' | 'annotation_read_only' | 'name_read_only' | 'annotation_mutating' | 'name_mutating' | 'schema_mutating' | 'annotation_destructive' | 'name_destructive' | 'schema_destructive' | 'conflicting_hints';
+}
+export interface ToolSchemaEvidence { readonly serverId: string; readonly hash: string; readonly effect?: ToolEffectEvidence; }
 export interface ActionEvent {
+  readonly toolSchema?: ToolSchemaEvidence;
   /** Pseudonymous application-authenticated subject, not WebDecoy-verified agent identity. */
   readonly caller?: {readonly schema:1;readonly source:'application_auth';readonly id:string};
   readonly work?:ActionWorkEvidence;
@@ -64,6 +72,10 @@ export interface ActionRuntime {
   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.
+   */
+  toolSchema?: ToolSchemaEvidence;
   limits?: ActionLimits;
   requiredScopes: readonly string[];
   validate(args: ActionInput): boolean | Promise<boolean>;

package/actions.mjs

@@ -2,6 +2,7 @@ import {randomUUID} from 'node:crypto';
 import {abortable} from './transport.mjs';
 import {prepareActionRuntime} from './action-runtime.mjs';
 
+import { snapshotToolEffect } from './tool-effects.mjs';
 const token = /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,95}$/;
 const bounded = value => typeof value === 'string' && value.isWellFormed() && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
 const freeze = value => {
@@ -72,7 +73,11 @@ export function createActionProtection(options) {
         definition.requiredScopes.some(s => !bounded(s)) ||
         ['validate','authorize','execute'].some(k => typeof definition[k] !== 'function') ||
         (definition.policy !== undefined && typeof definition.policy !== 'function')) throw Error('Invalid action definition');
-    actions.set(name, Object.freeze({...definition,requiredScopes:Object.freeze([...definition.requiredScopes])}));
+    const t = definition.toolSchema;
+    if (t !== undefined && (!t || typeof t.serverId !== 'string' || !token.test(t.serverId) ||
+        typeof t.hash !== 'string' || !/^[a-f0-9]{64}$/.test(t.hash))) throw Error('Invalid tool schema evidence');
+    const toolSchema = t === undefined ? undefined : Object.freeze({serverId:t.serverId,hash:t.hash,...(t.effect===undefined?{}:{effect:snapshotToolEffect(t.effect)})});
+    actions.set(name, Object.freeze({...definition,toolSchema,requiredScopes:Object.freeze([...definition.requiredScopes])}));
   }
   if (!actions.size || actions.size > 128) throw Error('Expected 1–128 actions');
   const runtime=prepareActionRuntime(options,actions);
@@ -91,7 +96,7 @@ export function createActionProtection(options) {
     function emit(decision, reason, outcome) {
 
       const event = Object.freeze({schema:1, eventId:randomUUID(), timestamp:new Date().toISOString(), actionId, action:eventAction, policyVersion,
-        ...(callerEvidence?{caller:callerEvidence}:{}),evaluation:'local', decision, reason, attempted, outcome,...(work?{work:Object.freeze({...work.evidence})}:{}),checks:Object.freeze(checks.map(c=>Object.freeze({...c})))});
+        ...(callerEvidence?{caller:callerEvidence}:{}),...(action?.toolSchema?{toolSchema:action.toolSchema}:{}),evaluation:'local', decision, reason, attempted, outcome,...(work?{work:Object.freeze({...work.evidence})}:{}),checks:Object.freeze(checks.map(c=>Object.freeze({...c})))});
       if(runtime)void runtime.report(event);
       if(!sink||pendingEvents>=100)return;
       pendingEvents++;

package/mcp.d.mts

@@ -4,9 +4,11 @@ import type {CallToolResult, Tool} from '@modelcontextprotocol/sdk/types.js';
 import type {ActionContext, ActionDefinition, ActionEvent, ActionRuntime, TrustedCaller} from './actions.mjs';
 
 /** Explicitly registered tool; inputSchema describes discovery, validate enforces input. */
-export interface ProtectedTool extends ActionDefinition {
+export interface ProtectedTool extends Omit<ActionDefinition, 'toolSchema'> {
   description: string;
   inputSchema: Tool['inputSchema'];
+  /** Behavioral hints, never authorization or verified guarantees. */
+  annotations?: Pick<NonNullable<Tool['annotations']>, 'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
   /** Await all protected work and return a complete MCP result, never a detached stream. */
   execute(context: ActionContext): CallToolResult | Promise<CallToolResult>;
 }
@@ -21,7 +23,7 @@ export interface ProtectedMCPOptions {
   policyVersion: string;
   sharedRuntime?: ActionRuntime;
   tools: Record<string, ProtectedTool>;
-  /** Opt-in tools/list metadata: stable non-secret server label and SHA-256 input-schema hashes.
+  /** Opt-in tools/list and tools/call metadata: stable non-secret server label and SHA-256 input-schema hashes.
    * Requires sharedRuntime. Reuse serverId across replicas; separate different servers.
    */
   discovery?: { serverId: string };

package/mcp.mjs

@@ -4,6 +4,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError } fr
 import { createActionProtection, ActionDenied } from './actions.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { createReporter } from './reporting.mjs';
+import { inferToolEffect, snapshotToolHints } from './tool-effects.mjs';
 const metadataPath = '/.well-known/oauth-protected-resource/mcp';
 export function createProtectedMCPHandler(options) {
     const resource = new URL(options.resource), issuer = new URL(options.authorizationServer);
@@ -11,7 +12,7 @@ export function createProtectedMCPHandler(options) {
     if ((resource.protocol !== 'https:' && !(loopback && resource.protocol === 'http:')) || resource.pathname !== '/mcp' || resource.search || resource.hash || resource.username || resource.password || issuer.protocol !== 'https:' || issuer.search || issuer.hash || issuer.username || issuer.password)
         throw Error('Invalid MCP resource configuration');
     const metadataURL = new URL(metadataPath, resource).href;
-    const tools = Object.fromEntries(Object.entries(options.tools).map(([name, t]) => [name, { ...t, requiredScopes: [...t.requiredScopes], inputSchema: structuredClone(t.inputSchema) }]));
+    const tools = Object.fromEntries(Object.entries(options.tools).map(([name, t]) => [name, { ...t, toolSchema: undefined, annotations: snapshotToolHints(t.annotations), requiredScopes: [...t.requiredScopes], inputSchema: structuredClone(t.inputSchema) }]));
     // 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))
@@ -30,6 +31,8 @@ export function createProtectedMCPHandler(options) {
     };
     const hashes = options.discovery ? Object.fromEntries(Object.entries(tools).map(([name, tool]) =>
         [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],effect:inferToolEffect(name,tool.inputSchema,tool.annotations)});
     const runtime = options.sharedRuntime && { ...options.sharedRuntime };
     const serverId = options.discovery?.serverId;
     const catalogReporter = options.discovery ? createReporter({
@@ -40,7 +43,7 @@ export function createProtectedMCPHandler(options) {
                 method: 'POST', redirect: 'error', signal,
                 headers: { Authorization: `Bearer ${runtime.webdecoyKey}`, 'X-WebDecoy-Property-ID': runtime.propertyId, 'Content-Type': 'application/json' },
                 body: JSON.stringify({ schema: 3, request_id: randomUUID(), timestamp: new Date().toISOString(), action: 'tool_discovery',
-                    tool_catalog: { server_id: serverId, source: 'tools_list', tools: names.map(name => ({ name, schema_hash: hashes[name] })) } })
+                    tool_catalog: { server_id: serverId, source: 'tools_list', tools: names.map(name => ({ name, schema_hash: hashes[name], effect: tools[name].toolSchema.effect })) } })
             });
             await response.body?.cancel();
             if (!response.ok) throw Error('Discovery reporting unavailable');
@@ -195,8 +198,8 @@ export function createProtectedMCPHandler(options) {
             res.once('close', () => { void server.close().catch(() => { }); });
             server.setRequestHandler(ListToolsRequestSchema, async () => {
                 const visible = Object.entries(tools).filter(([, tool]) => tool.requiredScopes.every(s => caller.scopes.includes(s)));
-                if (visible.length) void catalogReporter?.send(visible.map(([name]) => name));
-                return { tools: visible.map(([name, tool]) => ({ name, description: tool.description, inputSchema: tool.inputSchema })) };
+                for (let i=0;i<visible.length;i+=64) void catalogReporter?.send(visible.slice(i,i+64).map(([name]) => name));
+                return { tools: visible.map(([name, tool]) => ({ name, description: tool.description, inputSchema: tool.inputSchema, ...(tool.annotations ? {annotations:tool.annotations} : {}) })) };
             });
             server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
                 if (!Object.hasOwn(tools, request.params.name))

package/package.json

@@ -10,7 +10,7 @@
     "check:package": "node scripts/check-package.mjs",
     "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts test/mcp-types.mts"
   },
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",
@@ -62,7 +62,8 @@
     "mcp.d.mts",
     "MCP.md",
     "work.mjs",
-    "WORK.md"
+    "WORK.md",
+    "tool-effects.mjs"
   ],
   "description": "Bot and abuse protection for AI-powered applications. Server-side request admission for Node.js.",
   "license": "Apache-2.0",

package/tool-effects.mjs

@@ -0,0 +1,45 @@
+// Advisory inference only. Never used for permission or execution decisions.
+const destructive = new Set(['delete','remove','destroy','drop','truncate','revoke','purge','wipe']);
+const mutating = new Set(['create','update','write','set','send','publish','execute','run','export','charge','pay','transfer','deploy','install','invite','approve','refund']);
+const reading = new Set(['get','fetch','read','list','search','inspect','find','describe','count','lookup']);
+const tokens = value => typeof value === 'string' ? value.replace(/([a-z0-9])([A-Z])/g,'$1 $2').toLowerCase().split(/[^a-z0-9]+/) : [];
+export function snapshotToolHints(value) {
+  if(value === undefined)return undefined;
+  if(!value || typeof value !== 'object' || Array.isArray(value))throw Error('Invalid tool annotations');
+  const out={};
+  for(const key of ['readOnlyHint','destructiveHint','idempotentHint','openWorldHint'])if(value[key]!==undefined){
+    if(typeof value[key]!=='boolean')throw Error('Invalid tool annotation hint');out[key]=value[key];
+  }
+  return Object.freeze(out);
+}
+const reasons={unknown:['insufficient_signals'],read_only:['annotation_read_only','name_read_only'],mutating:['annotation_mutating','name_mutating','schema_mutating','conflicting_hints'],destructive:['annotation_destructive','name_destructive','schema_destructive','conflicting_hints']};
+export function snapshotToolEffect(value) {
+  if(value===undefined)return undefined;
+  if(!value || value.schema!==1 || !Object.hasOwn(reasons,value.level) || !reasons[value.level].includes(value.reason))throw Error('Invalid tool effect evidence');
+  return Object.freeze({schema:1,level:value.level,reason:value.reason});
+}
+export function inferToolEffect(name,schema,hints) {
+  const nameTokens=tokens(name);
+  const schemaTokens=[];
+  // Only inspect explicit operation selectors, never descriptions or free text.
+  // No refs, nested schema resolution, arguments, network or model calls.
+  for(const key of ['action','operation','method']){
+    const selector=schema?.properties?.[key];
+    for(const value of [selector?.const,...(Array.isArray(selector?.enum)?selector.enum.slice(0,64):[])]){
+      if(typeof value!=='string'||value.length>128)continue;
+      schemaTokens.push(...tokens(value));
+      if(key==='method'&&['POST','PUT','PATCH'].includes(value.toUpperCase()))schemaTokens.push('write');
+    }
+  }
+  let level='unknown',reason='insufficient_signals';
+  if(nameTokens.some(t=>destructive.has(t))){level='destructive';reason='name_destructive';}
+  else if(schemaTokens.some(t=>destructive.has(t))){level='destructive';reason='schema_destructive';}
+  else if(hints?.readOnlyHint!==true&&hints?.destructiveHint===true){level='destructive';reason='annotation_destructive';}
+  else if(nameTokens.some(t=>mutating.has(t))){level='mutating';reason='name_mutating';}
+  else if(schemaTokens.some(t=>mutating.has(t))){level='mutating';reason='schema_mutating';}
+  else if(hints?.readOnlyHint===false){level='mutating';reason='annotation_mutating';}
+  else if(hints?.readOnlyHint===true){level='read_only';reason='annotation_read_only';}
+  else if(nameTokens.some(t=>reading.has(t))){level='read_only';reason='name_read_only';}
+  if(hints?.readOnlyHint===true&&['mutating','destructive'].includes(level))reason='conflicting_hints';
+  return snapshotToolEffect({schema:1,level,reason});
+}