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

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.7 @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,47 @@ 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 **Advertised MCP tools**, 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.

package/mcp.d.mts

@@ -21,6 +21,10 @@ 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.
+   * 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);
@@ -16,12 +18,40 @@ export function createProtectedMCPHandler(options) {
         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')])) : {};
+    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 +193,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 +229,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.7",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",