@webdecoy/ai-protection 0.1.0-alpha.5 → 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/README.md

@@ -334,3 +334,29 @@ action events are documented in the action guide and use the hosted AI Protectio
 Node alpha.5 adds weighted tool-work reservations and tenant concurrency. See
 [bounded tool work](WORK.md) for installation, enforced application bounds and
 retry/unknown-outcome semantics. These units are separate from model usage and billing.
+
+### Opt-in tool caller attribution
+
+With a runtime supporting caller evidence, set `sharedRuntime.reportCaller: true`
+on `createActionProtection`. It defaults to false. Hosted reports and `onEvent`
+then include `caller: {schema: 1, source: 'application_auth', id: '<digest>'}`
+after successful authentication, including subsequent permission denials.
+Failed authentication, rejected arguments before authentication, and unknown tools
+have no caller attribution. Existing request admission reporting is unchanged.
+
+The SDK derives this HMAC-SHA256 pseudonym from the server-owned `subjectSecret`,
+a dedicated versioned domain, property ID, issuer, application tenant and subject.
+Replicas must use the same secret to correlate callers. Raw subjects, issuers,
+tenants, scopes, tokens and tool arguments are not added to reports. OAuth clients
+and agent signers are not treated as the authenticated subject. Your authentication
+hook must verify credentials and tenant membership; WebDecoy does not independently
+verify those credentials from this report, and a pseudonym is not a unique person.
+
+Use a randomly generated secret of at least 32 bytes and store it server-side.
+Rotating it changes pseudonyms and also changes existing shared-limit identities
+that use this secret; coordinate rotation because it can reset quota continuity.
+Historical pseudonyms are not relinked. AI Protection displays a seven-day receipt
+window and existing report retention purges expired records in bounded background
+sweeps. Counts cover reported, consistently attributed actions only; dropped reports,
+older SDKs and conflicting bindings leave gaps. Install server support before
+enabling this option: older runtimes reject the additional field.

package/action-runtime.mjs

@@ -11,7 +11,8 @@ export function prepareActionRuntime(options, definitions) {
   if(!['https:','http:'].includes(url.protocol)||url.username||url.password||url.pathname!=='/'||url.search||url.hash||
     (url.protocol==='http:'&&!['localhost','127.0.0.1','[::1]'].includes(url.hostname))||!validPropertyID(config.propertyId)||
     typeof config.webdecoyKey!=='string'||!config.webdecoyKey||/[^\x21-\x7e]/.test(config.webdecoyKey)||
-    typeof config.subjectSecret!=='string'||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
+    typeof config.subjectSecret!=='string'||!config.subjectSecret.isWellFormed()||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
+  if(config.reportCaller !== undefined && typeof config.reportCaller !== "boolean")throw Error("Invalid caller reporting option");
   const c={...config};const limits=new Map(),ruleIDs=new Set();
   const subject=(ctx,tenant)=>({accountId:tenant?quotaHash(c.subjectSecret,'webdecoy.actions.tenant.v1',ctx.caller.tenant):quotaHash(c.subjectSecret,'webdecoy.actions.caller.v1',ctx.caller.issuer,ctx.caller.tenant,ctx.caller.subject)});
   for(const [name,d] of definitions){
@@ -38,10 +39,10 @@ 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.work?{work:event.work}:{})}};
+        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}:{})}};
       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');
     }});
-  return {limits,report:event=>reporter.send(event),flush:()=>reporter.flush()};
+  return {limits,callerEvidence:caller=>c.reportCaller?Object.freeze({schema:1,source:'application_auth',id:quotaHash(c.subjectSecret,'webdecoy.actions.evidence.caller.v1',c.propertyId.toLowerCase(),caller.issuer,caller.tenant,caller.subject)}):undefined,report:event=>reporter.send(event),flush:()=>reporter.flush()};
 }

package/actions.d.mts

@@ -33,6 +33,8 @@ export interface ActionWork {
  measure?(result:unknown,context:ActionContext):number;
 }
 export interface ActionEvent {
+  /** Pseudonymous application-authenticated subject, not WebDecoy-verified agent identity. */
+  readonly caller?: {readonly schema:1;readonly source:'application_auth';readonly id:string};
   readonly work?:ActionWorkEvidence;
   readonly schema: 1;
   readonly eventId: string;
@@ -56,6 +58,8 @@ export interface ActionLimits {
   concurrency?: {ruleId:string;accountLimit:number;featureLimit:number;mode?:'observe'|'enforce';failureMode?:'open'|'closed';ttlSeconds?:number;maxSeconds?:number;timeoutMs?:number};
 }
 export interface ActionRuntime {
+  /** Opt in to scoped caller pseudonyms in reports. Requires a supporting runtime. Default false. */
+  reportCaller?:boolean;
   webdecoyUrl:string;webdecoyKey:string;propertyId:string;subjectSecret:string;
   reportingTimeoutMs?:number;maxPendingReports?:number;
 }

package/actions.mjs

@@ -3,7 +3,7 @@ import {abortable} from './transport.mjs';
 import {prepareActionRuntime} from './action-runtime.mjs';
 
 const token = /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,95}$/;
-const bounded = value => typeof value === 'string' && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
+const bounded = value => typeof value === 'string' && value.isWellFormed() && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
 const freeze = value => {
   if (value && typeof value === 'object') { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }
   return value;
@@ -81,7 +81,7 @@ export function createActionProtection(options) {
     const actionId = randomUUID();
     // Unknown caller-controlled action strings are never placed in evidence.
     const action = actions.get(name), eventAction = action ? name : 'unregistered';
-    let attempted = false,completed=false,lease,work;
+    let attempted = false,completed=false,lease,work,callerEvidence;
     const leases=[];
     const checks=[];
     const deadline = new AbortController();
@@ -91,7 +91,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,
-        evaluation:'local', decision, reason, attempted, outcome,...(work?{work:Object.freeze({...work.evidence})}:{}),checks:Object.freeze(checks.map(c=>Object.freeze({...c})))});
+        ...(callerEvidence?{caller:callerEvidence}:{}),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++;
@@ -107,6 +107,7 @@ export function createActionProtection(options) {
       let caller;
       try { caller = callerSnapshot(await evaluate(() => authenticate(authenticationContext, {signal:admissionSignal}))); }
       catch { cancelled(); deny('authentication_required',401); }
+      callerEvidence=runtime?.callerEvidence(caller);
       cancelled();
       if (action.requiredScopes.some(scope => !caller.scopes.includes(scope))) deny('missing_scope',403);
       const context = Object.freeze({caller, args, signal:admissionSignal});

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