@webdecoy/ai-protection 0.1.0-alpha.10 → 0.1.0-alpha.11

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.10 @modelcontextprotocol/sdk@1.31.0
+npm install @webdecoy/ai-protection@0.1.0-alpha.11 @modelcontextprotocol/sdk@1.31.0
 ```
 
 Requires Node 22.22.3+ and MCP SDK **1.31.0**. The MCP SDK is an optional peer, so
@@ -269,3 +269,54 @@ can include both sides of a rolling deployment; it does not certify the latest
 running configuration or prove that unwrapped routes are protected. A changed
 scope or callback does not change the input-schema hash. No enforcement behavior
 changes when discovery is enabled.
+
+## Explicit decoy tools (Alpha)
+
+Decoys are off by default. Node alpha.11 supports up to eight explicitly named
+synthetic tools in the protected registry; requires `discovery` and `sharedRuntime`.
+The combined real/decoy registry still has a 128-tool limit. Deploy a compatible
+runtime before upgrading an integration that enables decoys.
+
+```js
+discovery: {serverId: 'billing'},
+decoys: {
+  billing_export_ledger: {
+    description: 'Internal ledger export',
+    visibility: 'advertised',
+  },
+  admin_rotate_keys: {
+    description: 'Internal key rotation',
+    visibility: 'unadvertised',
+  },
+},
+```
+
+Choose names and descriptions outside legitimate workflows; examples are not a
+recommended universal decoy set. Collisions with real tools, callback fields and
+invalid definitions fail startup. Definitions are snapshotted. The SDK provides a
+generic object schema; no custom execution, validation or authorization callbacks
+are accepted for decoys. Advertised decoys appear to authenticated listing clients;
+unadvertised decoys never appear in tools/list. Both accept direct authenticated
+calls only to return the ordinary permission-denied error. Customer code is never
+executed, including when shared telemetry is unavailable. Real tools retain their
+normal authorization and behavior.
+
+Only reported calls count as decoy calls; listing is not a trip. Discovery and
+call reports carry a fixed decoy visibility marker, not arguments, hashes of
+arguments, descriptions or generated identities. Existing opt-in caller attribution
+can associate calls with application-reported pseudonyms. Invalid unauthenticated
+requests, over-limit transport bodies and unwrapped routes are not covered by this
+trip evidence. Delivery remains best effort. A marker is SDK-reported evidence,
+not independently verified server configuration.
+
+The dashboard labels decoys and mixed real/decoy evidence, counts deduplicated
+calls, and excludes synthetic entries from normal permission/advertisement review
+findings. Name-aggregated activity is labeled when it includes decoys. Reusing a
+name for a real tool can yield mixed evidence until retained reports expire.
+
+A decoy call can come from legitimate exploration or a naive agent; it is not proof
+of malicious intent. This slice does not auto-block callers, measure false-positive
+rates, generate seeded names, record initialization events, remotely deliver decoy
+configuration, or provide a labeled test-trigger flow. Configuration requires an
+application deployment. Those remain separate roadmap work. No low-false-positive
+or caller-containment guarantee is made.

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.toolSchema.effect?{effect:event.toolSchema.effect}:{}),...(event.toolSchema.permissions?{permissions:event.toolSchema.permissions}:{})}}:{}),...(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.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');

package/actions.d.mts

@@ -39,7 +39,7 @@ export interface ToolEffectEvidence {
  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 ToolPermissionEvidence { readonly schema: 1; readonly required_scopes: number; readonly application_authorization: true; readonly additional_policy: boolean; }
-export interface ToolSchemaEvidence { readonly permissions?: ToolPermissionEvidence; readonly serverId: string; readonly hash: string; readonly effect?: ToolEffectEvidence; }
+export interface ToolSchemaEvidence { readonly decoy?: 'advertised' | 'unadvertised'; readonly permissions?: ToolPermissionEvidence; 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

@@ -75,8 +75,8 @@ export function createActionProtection(options) {
         (definition.policy !== undefined && typeof definition.policy !== 'function')) throw Error('Invalid action definition');
     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)}),...(t.permissions===undefined?{}:{permissions:snapshotToolPermissions(t.permissions)})});
+        (t.decoy!==undefined && !['advertised','unadvertised'].includes(t.decoy)) || 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.decoy?{decoy:t.decoy}:{}),...(t.effect===undefined?{}:{effect:snapshotToolEffect(t.effect)}),...(t.permissions===undefined?{}:{permissions:snapshotToolPermissions(t.permissions)})});
     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

@@ -23,6 +23,10 @@ export interface ProtectedMCPOptions {
   policyVersion: string;
   sharedRuntime?: ActionRuntime;
   tools: Record<string, ProtectedTool>;
+  /** Opt-in, at most eight named decoys. Requires discovery + sharedRuntime.
+   * Never accepts customer execution callbacks. Combined real/decoy registry <=128.
+   */
+  decoys?: Record<string, {description: string; visibility: 'advertised' | 'unadvertised'}>;
   /** 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.
    */

package/mcp.mjs

@@ -13,6 +13,22 @@ export function createProtectedMCPHandler(options) {
         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, annotations: snapshotToolHints(t.annotations), requiredScopes: [...t.requiredScopes], inputSchema: structuredClone(t.inputSchema) }]));
+    const decoys = new Map();
+    if (options.decoys !== undefined) {
+        if (!options.discovery || !options.sharedRuntime || !options.decoys || typeof options.decoys !== 'object' || Array.isArray(options.decoys)) throw Error('Decoys require discovery and sharedRuntime');
+        const entries = Object.entries(options.decoys);
+        if (entries.length > 8) throw Error('At most 8 decoys are supported');
+        for (const [name, definition] of entries) {
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,95}$/.test(name) || Object.hasOwn(tools, name) || !definition ||
+                Object.keys(definition).some(k => !['description', 'visibility'].includes(k)) ||
+                typeof definition.description !== 'string' || !definition.description.trim() || definition.description.length > 512 ||
+                !['advertised', 'unadvertised'].includes(definition.visibility)) throw Error('Invalid or colliding decoy definition');
+            decoys.set(name, definition.visibility);
+            tools[name] = { description: definition.description, inputSchema: {type:'object'}, requiredScopes:[],
+                validate: () => true, authorize: () => false,
+                execute: () => { throw Error('Decoy dispatch invariant violated'); } };
+        }
+    }
     // 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))
@@ -32,7 +48,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],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'})});
+        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'})})});
     const runtime = options.sharedRuntime && { ...options.sharedRuntime };
     const serverId = options.discovery?.serverId;
     const catalogReporter = options.discovery ? createReporter({
@@ -43,7 +59,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], effect: tools[name].toolSchema.effect, permissions: tools[name].toolSchema.permissions })) } })
+                    tool_catalog: { server_id: serverId, source: 'tools_list', tools: names.map(name => ({ name, schema_hash: hashes[name], effect: tools[name].toolSchema.effect, permissions: tools[name].toolSchema.permissions, ...(decoys.has(name)?{decoy:decoys.get(name)}:{}) })) } })
             });
             await response.body?.cancel();
             if (!response.ok) throw Error('Discovery reporting unavailable');
@@ -197,7 +213,7 @@ export function createProtectedMCPHandler(options) {
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: false });
             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)));
+                const visible = Object.entries(tools).filter(([name, tool]) => decoys.get(name) !== 'unadvertised' && tool.requiredScopes.every(s => caller.scopes.includes(s)));
                 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} : {}) })) };
             });

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