@webdecoy/ai-protection 0.1.0-alpha.3 → 0.1.0-alpha.5

package/MCP.md

@@ -0,0 +1,122 @@
+# 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.5` and later compatible alpha releases:
+
+```sh
+npm install @webdecoy/ai-protection@0.1.0-alpha.5 @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 tool work is available in the alpha API; see [bounded work](WORK.md)
+  for its runtime prerequisite and application-enforced bounds. Full product
+  acceptance remains separate from this adapter's tested contract.
+
+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).
+
+For weighted search/export limits and tenant concurrency, see [bounded tool work](WORK.md).

package/README.md

@@ -324,7 +324,13 @@ Version `0.1.0-alpha.3` includes an action boundary at `@webdecoy/ai-protection/
 [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 [TypeScript MCP integration](examples/mcp/README.md)
-protects stateless HTTP tool dispatch in a source-only example; an exported MCP
-package entrypoint remains a follow-up. Optional shared quotas, concurrency and hosted
+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.
+
+## Weighted tool work (Alpha)
+
+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.

package/WORK.md

@@ -0,0 +1,123 @@
+# Bounded tool work (Alpha)
+
+The Node action and MCP APIs support optional weighted tool-work reservations.
+Available in `@webdecoy/ai-protection@0.1.0-alpha.5`. Requires the
+`/api/v1/sdk/ai-abuse/work` contract enabled on the hosted runtime. Go/Python model budgets
+and invocation controls remain available, but do not expose this new weighted
+operation API. The first integration is the TypeScript MCP tools adapter.
+
+## Configure at the action, before execution
+
+```js
+limits: {
+  work: {
+    ruleId: 'search_work_v1',
+    windowSeconds: 60,
+    maxUnits: 11, // one fixed unit plus at most five rows at two units each
+    limits: {caller: 22, tenant: 44, tool: 88},
+    mode: 'enforce',
+    failureMode: 'closed',
+    measure: result => result.workUnits, // server-computed, synchronous, confirmed
+  },
+  concurrency: {
+    ruleId: 'search_parallel_v1', accountLimit: 1, featureLimit: 10,
+    mode: 'enforce', failureMode: 'closed',
+  },
+  tenantConcurrency: {
+    ruleId: 'tenant_search_parallel_v1', accountLimit: 2, featureLimit: 10,
+    mode: 'enforce', failureMode: 'closed',
+  },
+}
+```
+
+Use `sharedRuntime` on the action/MCP handler. No browser credentials, prompts,
+arguments or results are sent to the work service. Verified caller identity and
+tenant are hashed; an HMAC binds the action, policy version and canonical arguments
+to the operation. Use a stable server-only subject secret. Changing that secret or
+rule IDs creates new accounting identities; rotate/drain deliberately.
+
+All three unit allowances are evaluated atomically across runtime replicas before
+callback dispatch. `caller` is scoped to issuer/tenant/subject, `tenant` is scoped
+to issuer/tenant, and `tool` is shared within this property's rule. Zero/omitted
+limits disable that dimension; at least one positive limit is required. Distinct
+tools need distinct rule IDs. Reconnecting or creating a new MCP session does not
+reset the identity allowance. Invocation quotas count attempts separately; model
+budgets count tokens separately. These units never become a WebDecoy billing meter.
+
+Existing `concurrency.accountLimit` is per caller; `tenantConcurrency.accountLimit`
+is per tenant. Each `featureLimit` is property/rule-wide. Admission denial releases
+already acquired slots; unconfirmed work keeps its slots until lease expiry.
+Lease expiry requests cooperative cancellation, not proof a remote operation stopped.
+
+## Enforce resource bounds in the application
+
+`maxUnits` must be a conservative upper bound you actually enforce. The SDK provides
+`context.work.maxUnits` to the callback, but cannot constrain arbitrary database or
+storage work. Validate requested bounds before dispatch, apply tenant predicates and
+row limits at the data source, and check byte lengths **before** appending/sending
+export payload. Do not fetch an unbounded result and trim it afterward.
+
+The [bounded search/export example](examples/mcp/work-tools.mjs) implements:
+
+- Search: at most five rows, weight `1 + 2 × returned rows`, reserve 11 units.
+- Export: at most 256 UTF-8 payload bytes, weight `16 + payload bytes`, reserve 272.
+  Transport framing/JSON encoding are not included in that payload-byte allowance.
+- Forbidden admin: application authorization denies before any callback.
+
+The synthetic source contains fixed small records. A real data source must enforce
+its own database scan, CPU/time and storage-read bounds too; a row limit is not a
+claim that a query scans only those rows. The separate weights use separate rules,
+not interchangeable token or monetary estimates.
+
+Run `node examples/mcp/start-work.mjs` after configuring the existing Auth0 example
+variables and `WEBDECOY_URL`, `WEBDECOY_KEY`, `WEBDECOY_PROPERTY_ID`, and
+`WEBDECOY_SUBJECT_SECRET`. The fixture binds to loopback and makes no model calls.
+It requires an updated runtime. Replace its single-subject allowlist with current
+application membership for an actual customer deployment.
+
+## Settlement, failures and retries
+
+After a completed callback, a synchronous `measure(result, context)` may report
+confirmed integer usage between zero and `maxUnits`. Without it, the fixed maximum
+weight is charged. Confirmed lower usage releases the difference in the original
+admission window. Never measure from untrusted request claims. Errors, cancellation,
+crashes, asynchronous/invalid measurement, excess usage and missing/failed settlement
+keep the conservative maximum charged. Successful results survive reporting or
+settlement failure and expose unknown accounting evidence.
+
+Unknown work is never refunded just because a lease or settlement deadline expires.
+A hard ceiling depends on application-enforced maximum work, enforce/closed settings,
+and bounded completion. Observe/open can execute without a confirmed reservation and
+must not claim a ceiling. Detector fail-open is separate from work-state failure.
+
+A reservation has a server-generated timestamp/UUID operation ID. For recovery across
+application retries, persist an ID from `createQuotaOperationId` (exported from
+`@webdecoy/ai-protection/fetch`) in trusted application state, and provide it through
+`work.operationId(context)`. Do not accept an arbitrary client ID or use MCP message,
+agent or session IDs as this key. Reuse requires the same caller/tenant/tool, bounds,
+policy and argument binding. Conflicts deny even in open mode.
+
+The SDK makes no automatic work-RPC or callback retries. An identical reserve replay
+returns accounting evidence but **never grants another dispatch**; the SDK returns
+`work_replay` (409). Lost admission replies may therefore consume capacity without
+executing work. A changed retry returns `work_conflict` (409). Return stored business
+results through your own idempotency layer when appropriate. Never mint a new ID to
+retry an unknown write blindly. Application/provider idempotency remains necessary;
+this is not an exactly-once side-effect guarantee. Identical settlement is idempotent;
+conflicting or over-bound settlement is rejected without lowering the charge.
+
+## Windows and evidence
+
+- Fixed UTC-aligned windows: 1–86,400 seconds. Boundary bursts are possible; use
+  concurrency controls separately. Limits/maxima: integer units up to 10^12.
+- IDs: ten-minute admission lifetime, at most 30 seconds future skew; expired IDs
+  remain invalid even after receipts are purged. Settlement deadline: one hour.
+- Receipts retained through the window end plus 24 hours. Unknown charge persists
+  for its admission window; this is not a lifetime allowance or infinite ledger.
+- At most 32 work rules and 10,000 retained operations per property, including denials.
+  Capacity failures follow state-failure policy. Existing replay works at capacity.
+  These are operational bounds, not commercial plan changes.
+- Reports show reserved/charged units, remaining allowance at admission and
+  reserved/settled/unknown/unavailable/denied/replay status. Remaining is a snapshot,
+  not current balance. Delivery is best effort; missing reports do not imply no work.
+  Local callback completion is not independent proof of a remote side effect.

package/action-runtime.mjs

@@ -1,3 +1,4 @@
+import {prepareWork} from './work.mjs';
 import {prepareQuota,quotaHash} from './quota.mjs';
 import {prepareConcurrency} from './concurrency.mjs';
 import {validPropertyID} from './account.mjs';
@@ -20,10 +21,15 @@ export function prepareActionRuntime(options, definitions) {
       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 concurrencies=[];
+    for(const [key,tenant] of [['concurrency',false],['tenantConcurrency',true]])if(l[key]){
+      const option=l[key];if(ruleIDs.has(option.ruleId))throw Error('Action limits require distinct rule IDs');ruleIDs.add(option.ruleId);
+      const gate=prepareConcurrency({...c,concurrency:{...option,subject:ctx=>subject(ctx,tenant)}});
+      concurrencies.push(async(ctx,signal)=>{const r=await gate(ctx,signal);if(tenant)r.check.id='tenant_concurrency';return r;});
+    }
+    let work=null;
+    if(l.work){if(ruleIDs.has(l.work.ruleId))throw Error('Action limits require distinct rule IDs');ruleIDs.add(l.work.ruleId);work=prepareWork(c,l.work,name,options.policyVersion);}
+    limits.set(name,{gates,concurrencies,work});
   }
   const reporter=createReporter({reportingTimeoutMs:c.reportingTimeoutMs??1000,maxPendingReports:c.maxPendingReports??100,
     onObservation:async(event,{signal})=>{
@@ -32,7 +38,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}};
+        tool_action:{action_id:event.actionId,name:event.action,policy_version:event.policyVersion,outcome:event.outcome,...(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

@@ -13,11 +13,27 @@ export interface TrustedCaller {
 }
 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;
+}
 export interface ActionEvent {
+  readonly work?:ActionWorkEvidence;
   readonly schema: 1;
   readonly eventId: string;
   readonly timestamp: string;
@@ -33,6 +49,8 @@ export interface ActionEvent {
 }
 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};

package/actions.mjs

@@ -59,7 +59,7 @@ function inputSnapshot(input) {
   return result;
 }
 
-/** Local protected dispatch. No network calls, cloud override, or automatic retry. */
+/** 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;
@@ -81,7 +81,8 @@ 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;
+    let attempted = false,completed=false,lease,work;
+    const leases=[];
     const checks=[];
     const deadline = new AbortController();
     const admissionSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
@@ -90,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,checks:Object.freeze(checks.map(c=>Object.freeze({...c})))});
+        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++;
@@ -131,38 +132,44 @@ export function createActionProtection(options) {
         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);
+      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,signal:lease?.signal??context.signal});
+      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(lease&&!lease.denial){
+      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:'concurrency_release',source:'shared',mode:lease.check.mode,decision:'unavailable',reason:'concurrency_release_unavailable',durationMs:performance.now()-began});}
+        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.
-      if(lease&&!lease.denial)await lease.finish(!attempted||completed).catch(()=>{});
+      for(const lease of [...leases].reverse())if(!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.3",
+  "version": "0.1.0-alpha.5",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",
@@ -27,6 +27,10 @@
     "./actions": {
       "types": "./actions.d.mts",
       "import": "./actions.mjs"
+    },
+    "./mcp": {
+      "types": "./mcp.d.mts",
+      "import": "./mcp.mjs"
     }
   },
   "files": [
@@ -53,7 +57,12 @@
     "NOTICE",
     "actions.mjs",
     "actions.d.mts",
-    "action-runtime.mjs"
+    "action-runtime.mjs",
+    "mcp.mjs",
+    "mcp.d.mts",
+    "MCP.md",
+    "work.mjs",
+    "WORK.md"
   ],
   "description": "Bot and abuse protection for AI-powered applications. Server-side request admission for Node.js.",
   "license": "Apache-2.0",
@@ -77,6 +86,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
+    }
   }
 }

package/work.mjs

@@ -0,0 +1,53 @@
+import {createQuotaOperationId,quotaHash} from './quota.mjs';
+import {readJSON} from './transport.mjs';
+const code=/^[a-z][a-z0-9_]{0,63}$/;
+const integer=n=>Number.isSafeInteger(n)&&n>=0&&n<=1e12;
+const canonical=value=>JSON.stringify(value===null||typeof value!=='object'?value:Array.isArray(value)?value.map(v=>JSON.parse(canonical(v))):Object.fromEntries(Object.keys(value).sort().map(k=>[k,JSON.parse(canonical(value[k]))])));
+export function prepareWork(config,definition,name,policyVersion){
+ const w={mode:'observe',failureMode:'open',timeoutMs:1000,...definition};
+ const limits=Object.fromEntries(['caller','tenant','tool'].map(k=>[k,w.limits?.[k]??0]));
+ if(!code.test(w.ruleId??'')||!integer(w.maxUnits)||w.maxUnits<1||!integer(w.windowSeconds)||w.windowSeconds<1||w.windowSeconds>86400||!integer(w.timeoutMs)||w.timeoutMs<1||w.timeoutMs>10000||!['observe','enforce'].includes(w.mode)||!['open','closed'].includes(w.failureMode)||!Object.values(limits).every(integer)||!Object.values(limits).some(n=>n>0)||(w.measure!==undefined&&typeof w.measure!=='function')||(w.operationId!==undefined&&typeof w.operationId!=='function'))throw Error('Invalid tool work policy');
+ async function rpc(body,signal){
+  const response=await fetch(new URL('/api/v1/sdk/ai-abuse/work',config.webdecoyUrl),{method:'POST',redirect:'error',signal:AbortSignal.any([signal??new AbortController().signal,AbortSignal.timeout(w.timeoutMs)]),headers:{Authorization:`Bearer ${config.webdecoyKey}`,'X-WebDecoy-Property-ID':config.propertyId,'Content-Type':'application/json'},body:JSON.stringify(body)});
+  if(!response.ok){await response.body?.cancel();const e=Error('Work unavailable');e.status=response.status;throw e;}
+  const r=await readJSON(response,2048);
+  if(r?.schema!==1||!['allowed','granted','replay','settled'].every(k=>typeof r[k]==='boolean')||!['reserved_units','charged_units','remaining_units','retry_after_seconds'].every(k=>integer(r[k]))||r.retry_after_seconds>86400||!code.test(r.reason??''))throw Error('Invalid work response');
+  return r;
+ }
+ return async(ctx,signal)=>{
+  let operationId=w.operationId?w.operationId(ctx):createQuotaOperationId();
+  if(operationId&&typeof operationId.then==='function')Promise.resolve(operationId).catch(()=>{});
+  if(typeof operationId!=='string'||! /^[1-9][0-9]{9}\.[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(operationId))throw Error('Invalid trusted work operation ID');
+  const body={schema:1,operation:'reserve',operation_id:operationId,rule_id:w.ruleId,mode:w.mode,window_seconds:w.windowSeconds,limits,units:w.maxUnits,
+   subject:quotaHash(config.subjectSecret,'webdecoy.work.caller.v1',ctx.caller.issuer,ctx.caller.tenant,ctx.caller.subject),tenant:quotaHash(config.subjectSecret,'webdecoy.work.tenant.v1',ctx.caller.issuer,ctx.caller.tenant),binding:quotaHash(config.subjectSecret,'webdecoy.work.arguments.v1',name,policyVersion,canonical(ctx.args))};
+  const evidence={rule_id:w.ruleId,mode:w.mode,status:'unknown',reserved_units:w.maxUnits};
+  const check={id:'tool_work',source:'shared',mode:w.mode,decision:'allow',reason:'work_allowed',durationMs:0};
+  const began=performance.now();let grant,denial;
+  try{
+   grant=await rpc(body,signal);
+   if(grant.replay){denial={reason:'work_replay',status:409};evidence.status='replay';}
+   else if(!grant.granted){if(grant.reason!=='work_exceeded')throw Error('Invalid work denial');denial={reason:'work_exceeded',status:429,retryAfterSeconds:grant.retry_after_seconds};evidence.status='denied';}
+   else {if(!['work_allowed','work_exceeded'].includes(grant.reason)||(!grant.allowed&&w.mode==='enforce')||grant.reserved_units!==w.maxUnits||grant.charged_units!==w.maxUnits)throw Error('Invalid work grant');evidence.status='reserved';}
+   evidence.reserved_units=grant.reserved_units;evidence.charged_units=grant.charged_units;evidence.remaining_units=grant.remaining_units;
+   check.reason=grant.reason;check.decision=grant.allowed&&!grant.replay?'allow':'deny';
+  }catch(e){
+   grant=undefined;
+   signal?.throwIfAborted();check.decision='unavailable';check.reason='work_outcome_unknown';evidence.status='unavailable';
+   if([400,403,409,410].includes(e.status)){denial={reason:e.status===409?'work_conflict':'work_operation_rejected',status:e.status};check.decision='deny';check.reason=denial.reason;}
+   else if(w.mode==='enforce'&&w.failureMode==='closed')denial={reason:'work_outcome_unknown',status:503};
+  }
+  check.durationMs=performance.now()-began;
+  return {check,denial,evidence,bound:Object.freeze({maxUnits:w.maxUnits}),async finish(result,completed){
+   if(!grant?.granted||grant.replay)return;
+   if(!completed){evidence.status='unknown';return;}
+   try{
+    const units=w.measure?w.measure(result,ctx):w.maxUnits;
+    if(units&&typeof units.then==='function')Promise.resolve(units).catch(()=>{});
+    if(!integer(units)||units>w.maxUnits)throw Error('Unconfirmed or excess work');
+    const settled=await rpc({...body,operation:'settle',units});
+    if(!settled.settled||settled.reason!=='work_settled'||settled.charged_units!==units)throw Error('Work settlement unavailable');
+    evidence.status='settled';evidence.charged_units=units;
+   }catch{evidence.status='unknown';return {id:'tool_work_settlement',source:'shared',mode:w.mode,decision:'unavailable',reason:'work_usage_unknown',durationMs:0};}
+  }};
+ };
+}