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

package/actions.d.mts

@@ -0,0 +1,105 @@
+/** Contract supplied by verified server authentication, never parsed from tool arguments. */
+export interface TrustedCaller {
+  readonly schema: 1;
+  readonly subject: string;
+  readonly tenant: string;
+  readonly issuer: string;
+  readonly authenticationMethod: string;
+  /** Unix milliseconds; checked again immediately before execution. */
+  readonly expiresAt: number;
+  readonly scopes: readonly string[];
+  /** OAuth client identity, separate from subject; not an agent signer. */
+  readonly clientId?: string;
+}
+export type ActionInput = null | boolean | number | string | readonly ActionInput[] | {readonly [key:string]: ActionInput};
+export interface ActionContext {
+  readonly work?: {readonly maxUnits:number};
+  readonly caller: TrustedCaller;
+  readonly args: ActionInput;
+  readonly signal?: AbortSignal;
+}
+export interface ActionWorkEvidence {
+ readonly rule_id:string;readonly mode:'observe'|'enforce';
+ readonly status:'reserved'|'settled'|'unknown'|'unavailable'|'denied'|'replay';
+ readonly reserved_units:number;readonly charged_units?:number;readonly remaining_units?:number;
+}
+export interface ActionWork {
+ ruleId:string;windowSeconds:number;maxUnits:number;
+ limits:{caller?:number;tenant?:number;tool?:number};
+ mode?:'observe'|'enforce';failureMode?:'open'|'closed';timeoutMs?:number;
+ /** Trusted server-generated persisted ID. Never use MCP request/session IDs or raw user input. */
+ operationId?(context:ActionContext):string;
+ /** 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 ToolEffectEvidence {
+ readonly schema: 1;
+ readonly level: 'unknown' | 'read_only' | 'mutating' | 'destructive';
+ 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 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. */
+  readonly caller?: {readonly schema:1;readonly source:'application_auth';readonly id:string};
+  readonly work?:ActionWorkEvidence;
+  readonly schema: 1;
+  readonly eventId: string;
+  readonly timestamp: string;
+  readonly checks: readonly {id:string;source:string;mode:string;decision:string;reason:string;durationMs:number}[];
+  readonly actionId: string;
+  readonly action: string;
+  readonly policyVersion: string;
+  readonly evaluation: 'local';
+  readonly decision: 'allow' | 'deny';
+  readonly reason: string;
+  readonly attempted: boolean;
+  readonly outcome: 'not_attempted' | 'attempted' | 'completed' | 'unknown';
+}
+export interface ActionQuota {ruleId:string;limit:number;windowSeconds:number;mode?:'observe'|'enforce';failureMode?:'open'|'closed';timeoutMs?:number}
+export interface ActionLimits {
+  tenantConcurrency?: ActionLimits['concurrency'];
+  work?:ActionWork;
+  callerQuota?: ActionQuota;
+  tenantQuota?: ActionQuota;
+  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;
+}
+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>;
+  authorize(context: ActionContext): boolean | Promise<boolean>;
+  /** Additional restrictive policy; cannot override application authorization. */
+  policy?(context: ActionContext): boolean | Promise<boolean>;
+  /** Await all protected work. Do not return a live stream or detached task. */
+  execute(context: ActionContext): unknown | Promise<unknown>;
+}
+export class ActionDenied extends Error {
+  readonly reason: string;
+  readonly status: number;
+  readonly actionId: string;
+  readonly retryAfterSeconds?: number;
+  constructor(reason: string, status: number, actionId: string);
+}
+export function createActionProtection<T>(options: {
+  policyVersion: string;
+  sharedRuntime?: ActionRuntime;
+  /** Bounds local admission checks; shared controls have their own RPC deadlines. Default 1000 ms, max 10000. */
+  admissionTimeoutMs?: number;
+  authenticate(context: T, options: {signal?: AbortSignal}): TrustedCaller | Promise<TrustedCaller>;
+  actions: Record<string, ActionDefinition>;
+  /** Local best-effort observer. sharedRuntime enables independent hosted reporting. */
+  onEvent?(event: ActionEvent): void | Promise<void>;
+}): {flush():Promise<void>;run(action: string, args: ActionInput, authenticationContext: T, options?: {signal?: AbortSignal}): Promise<unknown>};

package/actions.mjs

@@ -0,0 +1,181 @@
+import {randomUUID} from 'node:crypto';
+import {abortable} from './transport.mjs';
+import {prepareActionRuntime} from './action-runtime.mjs';
+
+import { snapshotToolEffect, snapshotToolPermissions } from './tool-effects.mjs';
+const token = /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,95}$/;
+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;
+};
+
+export class ActionDenied extends Error {
+  constructor(reason, status, actionId) {
+    super(reason); this.name = 'ActionDenied'; this.reason = reason; this.status = status; this.actionId = actionId;
+  }
+}
+
+// Authentication is owned by the application's server integration. This validates
+// its contract; it does not verify a bearer token, signer, or model-supplied claim.
+function callerSnapshot(value) {
+  if (!value || value.schema !== 1 || !bounded(value.subject) || !bounded(value.tenant) ||
+      !bounded(value.issuer) || !bounded(value.authenticationMethod) ||
+      !Number.isSafeInteger(value.expiresAt) || value.expiresAt <= Date.now() ||
+      !Array.isArray(value.scopes) || value.scopes.length > 64 || value.scopes.some(s => !bounded(s)) ||
+      (value.clientId !== undefined && !bounded(value.clientId))) throw Error('Invalid authenticated caller');
+  return freeze({schema:1, subject:value.subject, tenant:value.tenant, issuer:value.issuer,
+    authenticationMethod:value.authenticationMethod, expiresAt:value.expiresAt,
+    scopes:[...new Set(value.scopes)], ...(value.clientId === undefined ? {} : {clientId:value.clientId})});
+}
+
+// No accessors, class instances, cycles, non-finite numbers, or unbounded trees.
+// Copy before any await so a caller cannot swap arguments while policy runs.
+function inputSnapshot(input) {
+  let nodes = 0;
+  const seen = new Set();
+  function copy(value, depth) {
+    if (++nodes > 2048 || depth > 12) throw Error('Input too complex');
+    if (value === null || typeof value === 'boolean') return value;
+    if (typeof value === 'string') { if (value.length > 16384) throw Error('Input too large'); return value; }
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (!value || typeof value !== 'object' || seen.has(value) ||
+        (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) throw Error('Invalid JSON input');
+    if (Array.isArray(value) && value.length > 2048) throw Error('Input array too large');
+    const keys = Object.keys(value);
+    if (keys.length > 2048) throw Error('Input too complex');
+    seen.add(value);
+    const out = Array.isArray(value) ? [] : Object.create(null);
+    for (const key of keys) {
+      if (Array.isArray(value) && !/^(0|[1-9][0-9]*)$/.test(key)) throw Error('Invalid array key');
+      const d = Object.getOwnPropertyDescriptor(value, key);
+      if (!d || !('value' in d) || key.length > 512 || ['__proto__','constructor','prototype'].includes(key)) throw Error('Invalid input key');
+      out[key] = copy(d.value, depth + 1);
+    }
+    seen.delete(value);
+    return Object.freeze(out);
+  }
+  const result = copy(input, 0);
+  if (Buffer.byteLength(JSON.stringify(result)) > 16384) throw Error('Input too large');
+  return result;
+}
+
+/** Protected dispatch with local permissions and optional shared controls. Never retries execution. */
+export function createActionProtection(options) {
+  if (!options || typeof options.authenticate !== 'function' || (typeof options.policyVersion !== 'string' || !token.test(options.policyVersion))) throw Error('Invalid action configuration');
+  const authenticate = options.authenticate, policyVersion = options.policyVersion, sink = options.onEvent;
+  if (sink !== undefined && typeof sink !== 'function') throw Error('Invalid event sink');
+  const admissionTimeoutMs = options.admissionTimeoutMs ?? 1000;
+  if (!Number.isInteger(admissionTimeoutMs) || admissionTimeoutMs < 1 || admissionTimeoutMs > 10000) throw Error('Invalid admission timeout');
+  const actions = new Map();
+  for (const [name, definition] of Object.entries(options.actions ?? {})) {
+    if (!token.test(name) || !definition || !Array.isArray(definition.requiredScopes) || definition.requiredScopes.length > 64 ||
+        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');
+    const t = definition.toolSchema;
+    if (t !== undefined && (!t || typeof t.serverId !== 'string' || !token.test(t.serverId) ||
+        (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');
+  const runtime=prepareActionRuntime(options,actions);
+  let pendingEvents = 0;
+  return Object.freeze({flush:async()=>{await runtime?.flush();},async run(name, input, authenticationContext, {signal} = {}) {
+    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,callerEvidence;
+    const leases=[];
+    const checks=[];
+    const deadline = new AbortController();
+    const admissionSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    const timer = setTimeout(() => deadline.abort(new DOMException('Action admission timed out','TimeoutError')), admissionTimeoutMs);
+    const evaluate = fn => abortable(Promise.resolve().then(() => { admissionSignal.throwIfAborted(); return fn(); }), admissionSignal);
+    function emit(decision, reason, outcome) {
+
+      const event = Object.freeze({schema:1, eventId:randomUUID(), timestamp:new Date().toISOString(), actionId, action:eventAction, policyVersion,
+        ...(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++;
+      Promise.resolve().then(() => sink(event)).catch(() => {}).finally(() => { pendingEvents--; });
+    }
+    function deny(reason, status, retryAfterSeconds) { emit('deny', reason, 'not_attempted'); const e=new ActionDenied(reason,status,actionId);if(retryAfterSeconds)e.retryAfterSeconds=retryAfterSeconds;throw e; }
+    function cancelled() { (attempted ? signal : admissionSignal)?.throwIfAborted(); }
+    try {
+      cancelled();
+      if (!action) deny('action_not_registered',403);
+      let args;
+      try { args = inputSnapshot(input); } catch { deny('invalid_arguments',400); }
+      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});
+      let valid;
+      try { valid = await evaluate(() => action.validate(args)); } catch { cancelled(); deny('invalid_arguments',400); }
+      cancelled();
+      if (valid !== true) deny('invalid_arguments',400);
+      let authorized;
+      try { authorized = await evaluate(() => action.authorize(context)); } catch { cancelled(); deny('authorization_unavailable',503); }
+      cancelled();
+      if (authorized !== true) deny('permission_denied',403);
+      if (action.policy) {
+        let permitted;
+        try { permitted = await evaluate(() => action.policy(context)); } catch { cancelled(); deny('policy_unavailable',503); }
+        cancelled();
+        if (permitted !== true) deny('policy_denied',403);
+      }
+      // Shared limits run only after application permission checks. Their own
+      // RPC deadlines are separate from local admission and detector availability.
+      clearTimeout(timer);
+      const controls=runtime?.limits.get(name);
+      for(const gate of controls?.gates??[]){
+        const r=await gate(context,admissionSignal);checks.push(r.check);
+        if(r.denial)deny(r.denial.reason,r.denial.status,r.denial.retryAfterSeconds);
+      }
+      for(const gate of controls?.concurrencies??[]){
+        lease=await gate(context,lease?.signal??admissionSignal);leases.push(lease);checks.push(lease.check);
+        if(lease.denial)deny(lease.denial.reason,lease.denial.status,lease.denial.retryAfterSeconds);
+        lease.signal.throwIfAborted();
+      }
+      if(controls?.work){
+        work=await controls.work(context,lease?.signal??admissionSignal);checks.push(work.check);
+        if(work.denial)deny(work.denial.reason,work.denial.status,work.denial.retryAfterSeconds);
+      }
+      // Authentication may expire while ownership/policy checks are running.
+      if (caller.expiresAt <= Date.now()) deny('authentication_expired',401);
+      cancelled();
+      clearTimeout(timer);
+      attempted = true;
+      emit('allow','authorized','attempted');
+      const execution=Object.freeze({...context,...(work?{work:work.bound}:{}),signal:lease?.signal??context.signal});
+      const result = await action.execute(execution);
+      execution.signal.throwIfAborted();
+      // Resolution is application completion, not proof of an external side effect.
+      cancelled();
+      completed=true;
+      if(work){const check=await work.finish(result,true);if(check)checks.push(check);}
+      for(const lease of [...leases].reverse())if(!lease.denial){
+        const began=performance.now();
+        try{await lease.finish(true);}catch{checks.push({id:lease.check.id==='tenant_concurrency'?'tenant_concurrency_release':'concurrency_release',source:'shared',mode:lease.check.mode,decision:'unavailable',reason:'concurrency_release_unavailable',durationMs:performance.now()-began});}
+      }
+      emit('allow','authorized','completed');
+      return result;
+    } catch (error) {
+      if (!attempted && deadline.signal.aborted && !signal?.aborted) deny('admission_timeout',503);
+      if(work&&!completed)await work.finish(undefined,false);
+      if (attempted) emit('allow',signal?.aborted ? 'execution_cancelled' : 'execution_failed','unknown');
+      else if (!(error instanceof ActionDenied)) emit('deny','admission_cancelled','not_attempted');
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      // Only confirmed completion (or no callback) releases; uncertain work holds.
+      for(const lease of [...leases].reverse())if(!lease.denial)await lease.finish(!attempted||completed).catch(()=>{});
+    }
+  }});
+}

package/mcp.d.mts

@@ -0,0 +1,49 @@
+/// <reference types="node" />
+import type {IncomingMessage, ServerResponse} from 'node:http';
+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 Omit<ActionDefinition, 'toolSchema'> {
+  description: string;
+  inputSchema: Tool['inputSchema'];
+  /** Behavioral hints, never authorization or verified guarantees. */
+  annotations?: Pick<NonNullable<Tool['annotations']>, 'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+  /** Await all protected work and return a complete MCP result, never a detached stream. */
+  execute(context: ActionContext): CallToolResult | Promise<CallToolResult>;
+}
+
+export interface ProtectedMCPOptions {
+  /** Exact external /mcp URL. HTTPS required except on loopback. */
+  resource: string;
+  /** HTTPS issuer URL used in protected-resource metadata. */
+  authorizationServer: string;
+  /** Verify each request's credential and resolve membership from trusted application state. */
+  authenticate(request: Request, options: {signal: AbortSignal}): Promise<TrustedCaller>;
+  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.
+   */
+  discovery?: { serverId: string };
+  /** Exact browser origins; requests without Origin are permitted after authentication. */
+  allowedOrigins?: string[];
+  /** Best-effort, sanitized action events. */
+  onEvent?(event: ActionEvent): void | Promise<void>;
+}
+
+/**
+ * Stateless Node HTTP handler for a closed MCP tool registry.
+ * Requires the optional @modelcontextprotocol/sdk peer (tested/pinned 1.31.0).
+ * Does not wrap existing MCP servers, resources, prompts, tasks or alternate routes.
+ */
+export function createProtectedMCPHandler(options: ProtectedMCPOptions):
+  ((request: IncomingMessage, response: ServerResponse) => Promise<void>) & {
+    /** Drain pending discovery reports at shutdown. Does not wait for running tools. */
+    flush(): Promise<void>;
+  };

package/mcp.mjs

@@ -0,0 +1,252 @@
+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';
+import { inferToolEffect, snapshotToolHints } from './tool-effects.mjs';
+const metadataPath = '/.well-known/oauth-protected-resource/mcp';
+export function createProtectedMCPHandler(options) {
+    const resource = new URL(options.resource), issuer = new URL(options.authorizationServer);
+    const loopback = ['127.0.0.1', 'localhost', '[::1]'].includes(resource.hostname);
+    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, 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))
+        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],...(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({
+        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], 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');
+        }
+    }) : 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(' ')}"`}` }); }
+    const handle = async function (req, res) {
+        const disconnected = new AbortController();
+        req.once('aborted', () => disconnected.abort());
+        res.once('close', () => { if (!res.writableEnded)
+            disconnected.abort(); });
+        try {
+            if (req.headers.host !== resource.host) {
+                respond(res, 403, 'invalid_host');
+                return;
+            }
+            if (req.headers.origin && !origins.has(req.headers.origin)) {
+                respond(res, 403, 'invalid_origin');
+                return;
+            }
+            if (req.url === metadataPath && req.method === 'GET') {
+                res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                res.end(JSON.stringify({ resource: resource.href, authorization_servers: [issuer.href], scopes_supported: scopes, bearer_methods_supported: ['header'] }));
+                return;
+            }
+            if (req.url !== '/mcp') {
+                respond(res, 404, 'not_found');
+                return;
+            }
+            if (req.method !== 'POST') {
+                respond(res, 405, 'method_not_allowed', { 'Allow': 'POST' });
+                return;
+            }
+            // Stateless operation: no session resurrection, replay store or standalone SSE.
+            if (req.headers['mcp-session-id'] || req.headers['last-event-id']) {
+                respond(res, 400, 'sessions_not_supported');
+                return;
+            }
+            if (req.headers['content-type']?.split(';')[0].trim().toLowerCase() !== 'application/json') {
+                respond(res, 415, 'application_json_required');
+                return;
+            }
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(req.headers))
+                if (value !== undefined)
+                    headers.set(key, Array.isArray(value) ? value.join(',') : value);
+            const original = new Request(resource, { method: 'POST', headers, signal: disconnected.signal });
+            let caller;
+            const authDeadline = AbortSignal.timeout(1000), authSignal = AbortSignal.any([disconnected.signal, authDeadline]);
+            // The action boundary also rechecks expiry before tool execution.
+            try {
+                caller = await Promise.race([options.authenticate(original, { signal: authSignal }), new Promise((_, reject) => {
+                        if (authSignal.aborted)
+                            reject(authSignal.reason);
+                        else
+                            authSignal.addEventListener('abort', () => reject(authSignal.reason), { once: true });
+                    })]);
+                authSignal.throwIfAborted();
+                if (caller.schema !== 1 || !caller.subject || !caller.tenant || !Array.isArray(caller.scopes) || caller.expiresAt <= Date.now())
+                    throw Error('Invalid identity');
+                caller = Object.freeze({ ...caller, scopes: Object.freeze([...caller.scopes]) });
+            }
+            catch {
+                if (!disconnected.signal.aborted)
+                    challenge(res, 401);
+                return;
+            }
+            let body;
+            const bodyTimer = setTimeout(() => req.destroy(), 5000);
+            try {
+                let size = 0;
+                const chunks = [];
+                for await (const chunk of req) {
+                    size += chunk.length;
+                    if (size > 16384) {
+                        respond(res, 413, 'request_too_large');
+                        return;
+                    }
+                    chunks.push(Buffer.from(chunk));
+                }
+                body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            }
+            catch {
+                if (!res.destroyed)
+                    respond(res, 400, 'invalid_json');
+                return;
+            }
+            finally {
+                clearTimeout(bodyTimer);
+            }
+            if (!body || typeof body !== 'object' || Array.isArray(body)) {
+                respond(res, 400, 'single_message_required');
+                return;
+            }
+            if (caller.expiresAt <= Date.now()) {
+                challenge(res, 401);
+                return;
+            }
+            const message = body;
+            const validID = (id) => typeof id === 'string' ? id.length > 0 && id.length <= 512 : typeof id === 'number' && Number.isSafeInteger(id);
+            const callKey = (id) => JSON.stringify([caller.issuer, caller.subject, caller.tenant, caller.clientId ?? null, id]);
+            if (message.jsonrpc === '2.0' && message.method === 'notifications/cancelled' && message.id === undefined) {
+                if (!validID(message.params?.requestId)) {
+                    respond(res, 400, 'invalid_cancellation');
+                    return;
+                }
+                active.get(callKey(message.params.requestId))?.controller.abort();
+                res.writeHead(202, { 'Cache-Control': 'no-store' });
+                res.end();
+                return;
+            }
+            const guard = createActionProtection({ policyVersion: options.policyVersion, authenticate: () => caller, actions: tools, sharedRuntime: options.sharedRuntime, onEvent: options.onEvent });
+            // Scope escalation belongs at HTTP level, before the SDK opens an SSE stream.
+            if (message.method === 'tools/call' && typeof message.params?.name === 'string') {
+                const definition = Object.hasOwn(tools, message.params.name) ? tools[message.params.name] : undefined;
+                if (definition && definition.requiredScopes.some(s => !caller.scopes.includes(s))) {
+                    // Run the same admission path for its sanitized denial evidence. It cannot
+                    // dispatch with a missing required scope, regardless of discovery results.
+                    try {
+                        await guard.run(message.params.name, {}, null, { signal: disconnected.signal });
+                    }
+                    catch (e) {
+                        if (!(e instanceof ActionDenied))
+                            throw e;
+                    }
+                    challenge(res, 403, definition.requiredScopes);
+                    return;
+                }
+            }
+            const key = message.method === 'tools/call' && typeof message.params?.name === 'string' && Object.hasOwn(tools, message.params.name) && validID(message.id) ? callKey(message.id) : null;
+            if (key && active.has(key)) {
+                respond(res, 409, 'request_id_in_use');
+                return;
+            }
+            if (key && active.size >= 128) {
+                respond(res, 503, 'dispatch_capacity_unavailable');
+                return;
+            }
+            const running = { controller: new AbortController(), started: false };
+            if (key)
+                active.set(key, running);
+            const cleanup = () => { if (key && active.get(key) === running)
+                active.delete(key); };
+            res.once('close', () => { if (!running.started)
+                cleanup(); });
+            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 () => {
+                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} : {}) })) };
+            });
+            server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+                if (!Object.hasOwn(tools, request.params.name))
+                    throw new McpError(ErrorCode.InvalidParams, 'Tool unavailable');
+                running.started = true;
+                const signal = AbortSignal.any([extra.signal, disconnected.signal, running.controller.signal]);
+                try {
+                    return await guard.run(request.params.name, (request.params.arguments ?? {}), null, { signal });
+                }
+                catch (e) {
+                    if (signal.aborted)
+                        throw new McpError(ErrorCode.InternalError, 'Request cancelled');
+                    if (e instanceof ActionDenied)
+                        return { isError: true, content: [{ type: 'text', text: `Action denied: ${e.reason}` }],
+                            _meta: { 'webdecoy.com/action-error': { reason: e.reason, status: e.status, ...(e.retryAfterSeconds ? { retryAfterSeconds: e.retryAfterSeconds } : {}) } } };
+                    return { isError: true, content: [{ type: 'text', text: 'Action failed; outcome may be unknown' }] };
+                }
+                finally {
+                    cleanup();
+                    void guard.flush();
+                }
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch {
+            if (!res.headersSent && !res.destroyed)
+                respond(res, 500, 'request_failed');
+            else
+                res.destroy();
+        }
+    };
+    return Object.assign(handle, { flush: async () => { await catalogReporter?.flush(); } });
+}

package/package.json

@@ -8,9 +8,9 @@
     "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm test && npm run test:types && npm run check:package",
     "check:package": "node scripts/check-package.mjs",
-    "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts"
+    "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts test/mcp-types.mts"
   },
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.11",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",
@@ -23,6 +23,14 @@
     "./browser": {
       "types": "./browser.d.mts",
       "import": "./browser.mjs"
+    },
+    "./actions": {
+      "types": "./actions.d.mts",
+      "import": "./actions.mjs"
+    },
+    "./mcp": {
+      "types": "./mcp.d.mts",
+      "import": "./mcp.mjs"
     }
   },
   "files": [
@@ -46,8 +54,16 @@
     "browser-evidence.mjs",
     "usage.mjs",
     "transport.mjs",
-    "RELEASE.md",
-    "NOTICE"
+    "NOTICE",
+    "actions.mjs",
+    "actions.d.mts",
+    "action-runtime.mjs",
+    "mcp.mjs",
+    "mcp.d.mts",
+    "MCP.md",
+    "work.mjs",
+    "WORK.md",
+    "tool-effects.mjs"
   ],
   "description": "Bot and abuse protection for AI-powered applications. Server-side request admission for Node.js.",
   "license": "Apache-2.0",
@@ -71,6 +87,16 @@
     "webdecoy"
   ],
   "devDependencies": {
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "@modelcontextprotocol/sdk": "1.31.0",
+    "@types/node": "22.19.15"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "1.31.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
   }
 }