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

@@ -324,7 +324,7 @@ 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.

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.4",
   "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,10 @@
     "NOTICE",
     "actions.mjs",
     "actions.d.mts",
-    "action-runtime.mjs"
+    "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",
@@ -77,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
+    }
   }
 }