@webdecoy/ai-protection 0.1.0-alpha.6 → 0.1.0-alpha.8

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.5 @modelcontextprotocol/sdk@1.31.0
+npm install @webdecoy/ai-protection@0.1.0-alpha.8 @modelcontextprotocol/sdk@1.31.0
 ```
 
 Requires Node 22.22.3+ and MCP SDK **1.31.0**. The MCP SDK is an optional peer, so
@@ -120,3 +120,73 @@ whole MCP server. See the [MCP transport specification](https://modelcontextprot
 and [authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
 
 For weighted search/export limits and tenant concurrency, see [bounded tool work](WORK.md).
+
+
+## Opt-in tool discovery (alpha.7+)
+
+Add these options alongside your existing `tools` and authentication configuration:
+
+```ts
+sharedRuntime: {
+  webdecoyUrl: 'https://ai-protection.webdecoy.com',
+  webdecoyKey: process.env.WEBDECOY_API_KEY!,
+  propertyId: process.env.WEBDECOY_PROPERTY_ID!,
+  subjectSecret: process.env.WEBDECOY_SUBJECT_SECRET!, // at least 32 bytes
+},
+discovery: { serverId: 'records-api' },
+```
+
+Use a stable, non-secret server label (1–96 letters, digits, `_`, `.`, `:`, `-`,
+starting with a letter or digit). Reuse it across replicas/releases of the same
+logical server. Give separate servers separate labels within a property. Do not
+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 **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.
+
+Hashes cover the JSON input schema with recursively sorted object keys; array
+order is preserved. Raw schemas, descriptions, arguments, results, credentials,
+caller identities and required scopes are not uploaded. A schema hash is a
+fingerprint, not encryption; someone with a candidate schema can compare it.
+Multiple hashes for one server/tool show reported variants in the seven-day
+receipt window. Rolling deployments and benign schema edits can cause variants.
+They do not establish an attack, breaking change, removal or missing permission.
+The UI uses the latest receipt's hash, not a claim about deployment order.
+
+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.
+
+
+### 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.

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.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,10 @@ 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 ToolSchemaEvidence { readonly serverId: string; readonly hash: string; }
 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 +67,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

@@ -72,7 +72,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});
+    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 +95,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,7 +4,7 @@ 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'];
   /** Await all protected work and return a complete MCP result, never a detached stream. */
@@ -21,6 +21,10 @@ export interface ProtectedMCPOptions {
   policyVersion: string;
   sharedRuntime?: ActionRuntime;
   tools: Record<string, ProtectedTool>;
+  /** 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 };
   /** Exact browser origins; requests without Origin are permitted after authentication. */
   allowedOrigins?: string[];
   /** Best-effort, sanitized action events. */
@@ -33,4 +37,7 @@ export interface ProtectedMCPOptions {
  * Does not wrap existing MCP servers, resources, prompts, tasks or alternate routes.
  */
 export function createProtectedMCPHandler(options: ProtectedMCPOptions):
-  (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+  ((request: IncomingMessage, response: ServerResponse) => Promise<void>) & {
+    /** Drain pending discovery reports at shutdown. Does not wait for running tools. */
+    flush(): Promise<void>;
+  };

package/mcp.mjs

@@ -2,6 +2,8 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { createActionProtection, ActionDenied } from './actions.mjs';
+import { createHash, randomUUID } from 'node:crypto';
+import { createReporter } from './reporting.mjs';
 const metadataPath = '/.well-known/oauth-protected-resource/mcp';
 export function createProtectedMCPHandler(options) {
     const resource = new URL(options.resource), issuer = new URL(options.authorizationServer);
@@ -9,19 +11,49 @@ 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, 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))
         for (const scope of tool.requiredScopes)
             if (!/^[\x21\x23-\x5b\x5d-\x7e]+$/.test(scope))
                 throw Error('Invalid OAuth scope');
+    // Opt-in metadata only. Never collect descriptions, raw schemas, scopes,
+    // credentials, arguments or resource URLs in discovery reports.
+    if (options.discovery !== undefined && (!options.sharedRuntime || !options.discovery ||
+        !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,95}$/.test(options.discovery.serverId)))
+        throw Error('Discovery requires sharedRuntime and a stable serverId');
+    const canonical = value => {
+        if (value === null || typeof value !== 'object') return JSON.stringify(value);
+        if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+        return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+    };
+    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]});
+    const runtime = options.sharedRuntime && { ...options.sharedRuntime };
+    const serverId = options.discovery?.serverId;
+    const catalogReporter = options.discovery ? createReporter({
+        reportingTimeoutMs: runtime.reportingTimeoutMs ?? 1000,
+        maxPendingReports: runtime.maxPendingReports ?? 100,
+        onObservation: async (names, { signal }) => {
+            const response = await fetch(new URL('/api/v1/sdk/ai-abuse/reports', runtime.webdecoyUrl), {
+                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] })) } })
+            });
+            await response.body?.cancel();
+            if (!response.ok) throw Error('Discovery reporting unavailable');
+        }
+    }) : null;
     const active = new Map();
     const scopes = [...new Set(Object.values(tools).flatMap(t => t.requiredScopes))];
     const origins = new Set(options.allowedOrigins ?? []);
     function respond(res, status, error, headers = {}) { res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', ...headers }); res.end(JSON.stringify({ error })); }
     function challenge(res, status, scope) { respond(res, status, status === 401 ? 'unauthorized' : 'insufficient_scope', { 'WWW-Authenticate': `Bearer resource_metadata="${metadataURL}"${status === 401 ? '' : `, error="insufficient_scope", scope="${scope.join(' ')}"`}` }); }
-    return async function handle(req, res) {
+    const handle = async function (req, res) {
         const disconnected = new AbortController();
         req.once('aborted', () => disconnected.abort());
         res.once('close', () => { if (!res.writableEnded)
@@ -163,9 +195,11 @@ export function createProtectedMCPHandler(options) {
             const server = new Server({ name: 'webdecoy-protected-tools', version: '0.1.0' }, { capabilities: { tools: {} } });
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: false });
             res.once('close', () => { void server.close().catch(() => { }); });
-            server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: Object.entries(tools)
-                    .filter(([, tool]) => tool.requiredScopes.every(s => caller.scopes.includes(s)))
-                    .map(([name, tool]) => ({ name, description: tool.description, inputSchema: tool.inputSchema })) }));
+            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 })) };
+            });
             server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
                 if (!Object.hasOwn(tools, request.params.name))
                     throw new McpError(ErrorCode.InvalidParams, 'Tool unavailable');
@@ -197,4 +231,5 @@ export function createProtectedMCPHandler(options) {
                 res.destroy();
         }
     };
+    return Object.assign(handle, { flush: async () => { await catalogReporter?.flush(); } });
 }

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