@webdecoy/ai-protection 0.1.0-alpha.8 → 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.8 @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
@@ -190,3 +190,49 @@ 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.toolSchema?{tool_schema:{server_id:event.toolSchema.serverId,hash:event.toolSchema.hash}}:{}),...(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

@@ -33,7 +33,12 @@ export interface ActionWork {
  measure?(result:unknown,context:ActionContext):number;
 }
 /** Server-supplied metadata, not proof of a verified schema or authorization. */
-export interface ToolSchemaEvidence { readonly serverId: string; readonly hash: string; }
+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. */

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 => {
@@ -75,7 +76,7 @@ export function createActionProtection(options) {
     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});
+    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');

package/mcp.d.mts

@@ -7,6 +7,8 @@ import type {ActionContext, ActionDefinition, ActionEvent, ActionRuntime, Truste
 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>;
 }

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, toolSchema: undefined, 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))
@@ -31,7 +32,7 @@ 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]});
+        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({
@@ -42,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');
@@ -197,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.8",
+  "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});
+}