@webdecoy/ai-protection 0.1.0-alpha.7 → 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.7 @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
@@ -143,7 +143,7 @@ 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
+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.
@@ -164,3 +164,29 @@ never blocks authorization, and does not retry. Call `await handler.flush()` at
 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,7 +21,7 @@ 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.
+  /** 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 };

package/mcp.mjs

@@ -11,7 +11,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, 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))
@@ -30,6 +30,8 @@ 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]});
     const runtime = options.sharedRuntime && { ...options.sharedRuntime };
     const serverId = options.discovery?.serverId;
     const catalogReporter = options.discovery ? createReporter({

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