@webdecoy/ai-protection 0.1.0-alpha.2 → 0.1.0-alpha.4

package/MCP.md

@@ -0,0 +1,119 @@
+# MCP tool protection (Alpha)
+
+`@webdecoy/ai-protection/mcp` is a Node HTTP handler for a closed registry of
+protected tools. It runs in your application's backend. Your MCP traffic stays
+on your server; configured shared limits and sanitized action reports use the
+WebDecoy runtime. Your application owns authentication, tenant membership and
+resource authorization.
+
+## Install
+
+Available in `0.1.0-alpha.4` and later compatible alpha releases:
+
+```sh
+npm install @webdecoy/ai-protection@0.1.0-alpha.4 @modelcontextprotocol/sdk@1.31.0
+```
+
+Requires Node 22.22.3+ and MCP SDK **1.31.0**. The MCP SDK is an optional peer, so
+ordinary request/action SDK installs do not install it. Only `/mcp` imports it.
+TypeScript Node applications also need their usual `@types/node` development
+dependency. Tests exercise MCP protocol **2025-11-25** with the official client.
+
+## Connect your application
+
+```ts
+import {createServer} from 'node:http';
+import {createProtectedMCPHandler} from '@webdecoy/ai-protection/mcp';
+import {verifyAccessToken, records} from './your-application.js';
+
+const handler = createProtectedMCPHandler({
+  resource: 'https://api.example.com/mcp',
+  authorizationServer: 'https://your-issuer.example.com/',
+  policyVersion: 'records_v1',
+  // Your verifier validates issuer, audience/resource, signature and expiry,
+  // then resolves tenant membership from trusted application state.
+  authenticate: (request, {signal}) => verifyAccessToken(request, {signal}),
+  tools: {
+    'records.read': {
+      description: 'Read an owned record',
+      inputSchema: {
+        type: 'object', properties: {id: {type: 'string'}},
+        required: ['id'], additionalProperties: false,
+      },
+      requiredScopes: ['records:read'],
+      validate: args => args !== null && typeof args === 'object'
+        && !Array.isArray(args) && Object.keys(args).length === 1
+        && 'id' in args && typeof args.id === 'string',
+      authorize: ({caller, args}) => records.canRead(caller, args),
+      // The database query must scope by the trusted tenant, even after authorize.
+      // Await all work; return a complete MCP result, not a detached stream/task.
+      execute: ({caller, args, signal}) => records.readForTenant(caller.tenant, args, signal),
+    },
+  },
+});
+const server = createServer((req, res) => { void handler(req, res); });
+server.requestTimeout = 10000;
+server.headersTimeout = 10000;
+server.listen(8093, '127.0.0.1'); // Put your existing HTTPS proxy in front.
+```
+
+The application imports above are integration hooks, not exports from this SDK.
+See the [runnable Auth0-backed example](examples/mcp/README.md) for a concrete
+verifier and test registry. The verifier returns the [trusted caller contract](actions.d.mts):
+schema, subject, tenant, issuer, authentication method, expiry and scopes. Never
+derive tenant or permissions from tool arguments, a session ID, agent name or a
+WebDecoy API key. A separate WebDecoy-owned Auth0 account is not required.
+
+`inputSchema` advertises the tool shape; the application `validate` hook enforces
+it before dispatch. Tool listing is filtered by scopes, while every tool call
+independently checks scopes, validation and application permissions. Do not expose
+the same operation through an unguarded alternate handler.
+
+## Shared controls and evidence
+
+Supply `sharedRuntime` with the server-only WebDecoy URL, API key, property ID and
+stable subject secret. Add `limits.callerQuota`, `limits.tenantQuota` and/or
+`limits.concurrency` to each protected tool. These use the same configuration as
+the [action API](examples/actions/README.md#shared-limits-and-hosted-evidence).
+Limits follow verified identities, not MCP connection/session identifiers.
+
+Authentication and explicit permission denials always stop dispatch. Shared-state
+failure follows each limit's configured `failureMode`; use enforce/closed for a
+hard admission limit. Observe/open does not establish a hard ceiling. This adapter
+does not itself run request bot detection or a prompt scanner. If you add detector
+checks elsewhere, keep their default fail-open behavior separate from permissions.
+
+Optional `onEvent` receives sanitized action outcomes. Shared-runtime reporting is
+best effort. Events omit tokens, raw identities, tool arguments and result content.
+A completed event means the callback resolved; independently check your own
+database/provider for side-effect confirmation. A failed/disconnected call may
+have unknown work. Never retry writes without application/provider idempotency.
+
+## Supported boundary
+
+- Stateless Streamable HTTP at `/mcp`: initialize, ping, scoped `tools/list`,
+  protected `tools/call`, and caller-bound cancellation notifications.
+- Protected-resource metadata at `/.well-known/oauth-protected-resource/mcp`;
+  missing/invalid credentials get HTTP 401, missing scopes get HTTP 403 challenges.
+  Permission/limit denials after admission use MCP tool errors with bounded retry
+  guidance in `_meta["webdecoy.com/action-error"]`.
+- Host must match `resource`; present Origin headers must be explicitly allowed.
+  Non-browser clients can omit Origin. Preserve Host through your trusted proxy.
+- At most 16 KiB per JSON message, five-second body read, one-second authentication
+  deadline and at most 128 active tool calls per handler. These local bounds are
+  distinct from shared caller quotas.
+- SSE carries the final MCP response. Tools must await completion; arbitrary live
+  tool-result streams are unsupported. A disconnect requests cooperative abort;
+  explicit cancellation is scoped to the authenticated caller/client/request ID.
+  Uncooperative work retains its local active slot until it settles.
+- No session store, replay/resumption, automatic retry or exactly-once execution.
+  Supplied session/replay IDs are rejected; standalone SSE GET and DELETE return
+  405. Reconnects do not grant fresh identity allowances.
+- Resources, prompts, tasks, sampling, elicitation, other routes and pre-existing
+  MCP handlers are not wrapped. Unregistered methods/tools do not dispatch.
+  Weighted operation budgets and complete cross-replica lifecycle acceptance
+  remain separate work.
+
+This is an explicit tools integration, not transparent protection of an existing
+whole MCP server. See the [MCP transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
+and [authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).

package/README.md

@@ -4,7 +4,7 @@ Bot and abuse protection for AI-powered applications. A small Node.js SDK that
 checks requests before your application invokes a model. Customer-defined rules run
 locally; proprietary bot detection runs in WebDecoy. See [architecture](ARCHITECTURE.md).
 
-**Alpha release: `0.1.0-alpha.2`.** Integration mechanics are tested;
+**Alpha release: `0.1.0-alpha.3`.** Integration mechanics are tested;
 real-world detection accuracy and provider cost savings have not been established.
 Requires a WebDecoy property, a property-scoped API key, and a compatible WebDecoy
 service deployment. This repository contains the SDK, not the detection service.
@@ -317,3 +317,14 @@ snapshot, not current quota state.
 
 Only admission is deduplicated. Repeated application/model calls still require
 application-level idempotency. The hosted runtime must support quota schema 2 before enabling this option.
+
+## Action authorization (Alpha)
+
+Version `0.1.0-alpha.3` includes an action boundary at `@webdecoy/ai-protection/actions`. See the
+[record-action example and integration contract](examples/actions/README.md).
+This API requires your server authentication and application authorization.
+An [Auth0 access-token example](examples/auth0/README.md) verifies signed tokens
+and maps tenant membership. The [MCP adapter](MCP.md) provides a separate `/mcp` entrypoint for stateless
+HTTP tool dispatch starting in `0.1.0-alpha.4`.
+It requires the optional, pinned MCP SDK peer. Optional shared quotas, concurrency and hosted
+action events are documented in the action guide and use the hosted AI Protection runtime and dashboard.

package/action-runtime.mjs

@@ -0,0 +1,41 @@
+import {prepareQuota,quotaHash} from './quota.mjs';
+import {prepareConcurrency} from './concurrency.mjs';
+import {validPropertyID} from './account.mjs';
+import {createReporter} from './reporting.mjs';
+
+export function prepareActionRuntime(options, definitions) {
+  const config=options.sharedRuntime;
+  if(!config){if([...definitions.values()].some(d=>d.limits))throw Error('Action limits require sharedRuntime');return null;}
+  const url=new URL(config.webdecoyUrl);
+  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');
+  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){
+    const l=d.limits??{},gates=[];
+    for(const [key,tenant]of [['callerQuota',false],['tenantQuota',true]])if(l[key]){
+      const q=l[key];if(ruleIDs.has(q.ruleId))throw Error('Action limits require distinct rule IDs');ruleIDs.add(q.ruleId);
+      const gate=prepareQuota({...c,accountQuota:{...q,idempotency:false,operationId:undefined,sessionLimit:0,subject:ctx=>subject(ctx,tenant)}});
+      gates.push(async(ctx,signal)=>{const r=await gate(ctx,signal);if(r.check)r.check.id=tenant?'tenant_quota':'caller_quota';return r;});
+    }
+    let concurrency=null;
+    if(l.concurrency){if(ruleIDs.has(l.concurrency.ruleId))throw Error('Action limits require distinct rule IDs');ruleIDs.add(l.concurrency.ruleId);
+      concurrency=prepareConcurrency({...c,concurrency:{...l.concurrency,subject:ctx=>subject(ctx,false)}});}
+    limits.set(name,{gates,concurrency});
+  }
+  const reporter=createReporter({reportingTimeoutMs:c.reportingTimeoutMs??1000,maxPendingReports:c.maxPendingReports??100,
+    onObservation:async(event,{signal})=>{
+      const checks=[{id:'action_boundary',source:'local',mode:'enforce',decision:event.decision,reason:event.reason,duration_ms:0},
+        ...event.checks.map(check=>({id:check.id,source:check.source,mode:check.mode,decision:check.decision,reason:check.reason,duration_ms:check.durationMs}))];
+      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}};
+      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()};
+}

package/actions.d.mts

@@ -0,0 +1,70 @@
+/** 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 caller: TrustedCaller;
+  readonly args: ActionInput;
+  readonly signal?: AbortSignal;
+}
+export interface ActionEvent {
+  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 {
+  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 {
+  webdecoyUrl:string;webdecoyKey:string;propertyId:string;subjectSecret:string;
+  reportingTimeoutMs?:number;maxPendingReports?:number;
+}
+export interface ActionDefinition {
+  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,168 @@
+import {randomUUID} from 'node:crypto';
+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 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;
+}
+
+/** Local protected dispatch. No network calls, cloud override, or automatic retry. */
+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');
+    actions.set(name, Object.freeze({...definition,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;
+    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,
+        evaluation:'local', decision, reason, attempted, outcome,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); }
+      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);
+      }
+      if(controls?.concurrency){
+        lease=await controls.concurrency(context,admissionSignal);checks.push(lease.check);
+        if(lease.denial)deny(lease.denial.reason,lease.denial.status,lease.denial.retryAfterSeconds);
+        lease.signal.throwIfAborted();
+      }
+      // 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,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(lease&&!lease.denial){
+        const began=performance.now();
+        try{await lease.finish(true);}catch{checks.push({id:'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 (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.
+      if(lease&&!lease.denial)await lease.finish(!attempted||completed).catch(()=>{});
+    }
+  }});
+}

package/mcp.d.mts

@@ -0,0 +1,36 @@
+/// <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 ActionDefinition {
+  description: string;
+  inputSchema: Tool['inputSchema'];
+  /** 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>;
+  /** 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>;

package/mcp.mjs

@@ -0,0 +1,200 @@
+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';
+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, 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');
+    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 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 () => ({ 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(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();
+        }
+    };
+}

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.2",
+  "version": "0.1.0-alpha.4",
   "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,7 +54,13 @@
     "browser-evidence.mjs",
     "usage.mjs",
     "transport.mjs",
-    "NOTICE"
+    "NOTICE",
+    "actions.mjs",
+    "actions.d.mts",
+    "action-runtime.mjs",
+    "mcp.mjs",
+    "mcp.d.mts",
+    "MCP.md"
   ],
   "description": "Bot and abuse protection for AI-powered applications. Server-side request admission for Node.js.",
   "license": "Apache-2.0",
@@ -70,6 +84,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
+    }
   }
 }