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

package/MCP.md

@@ -320,3 +320,44 @@ rates, generate seeded names, record initialization events, remotely deliver dec
 configuration, or provide a labeled test-trigger flow. Configuration requires an
 application deployment. Those remain separate roadmap work. No low-false-positive
 or caller-containment guarantee is made.
+
+### Caller-attributed enumeration (alpha.13)
+
+With `discovery` and `sharedRuntime.reportCaller: true`, authenticated `tools/list`
+reports carry the same property-scoped pseudonym as tool calls. Raw identities,
+credentials and scopes are not uploaded. Attribution stays off by default.
+The hosted receiver must support caller-attributed catalogs before enabling this
+SDK version; older receivers reject the new optional field without interrupting
+tool listing. Listings with no visible tools also generate an empty catalog.
+
+Caller timelines show enumeration separately from calls and decoy trips. Listing
+is normal client behavior, not an enforcement decision. Large listings are split
+into batches of up to 64 tools; each batch is a report, not a distinct listing
+count. Unattributed older catalogs are never assigned to a caller retrospectively.
+Initialization and automatic containment remain outside this feature.
+
+### Manual caller pauses (alpha.14)
+
+Enable `sharedRuntime: { ...runtimeOptions, reportCaller: true, callerPause: true }`
+on each protected server after updating the hosted receiver. An organization owner
+or admin can then open a caller timeline and review a pause or resume for that
+property. A reason is required. Pauses can expire or remain until resumed.
+Concurrent stale edits are rejected and each successful change is audited.
+
+The check runs after application permissions and before shared limits or execution,
+for each admitted tool call. It adds one network request with a 1000 ms default deadline (`callerPauseTimeoutMs`, range 1–10000 ms),
+no retries and no decision cache. Very short deadlines can fail open during cold API-key authentication. A saved pause applies to subsequent successful
+checks; a call already admitted or running is not cancelled. Resuming needs no cache
+invalidation. A restart reads current state on the next check.
+
+Outages, timeouts, malformed responses and unavailable controls fail open with
+`caller_pause_unavailable` evidence; authorization and other limits still apply.
+A saved pause is not a delivery acknowledgment and cannot guarantee enforcement
+while disconnected. This control does not revoke OAuth credentials.
+
+Scope is the existing property-scoped pseudonym derived from issuer, tenant and
+subject. Keep `subjectSecret` consistent across replicas. Rotating it changes the
+pseudonym and existing pauses no longer match. Only opt-in Node action integrations
+are covered, including this MCP adapter; Python/Go and unwrapped tools are not.
+Listings and initialization remain available; this pauses new tool execution.
+No automatic pause is applied after a decoy call.

package/NEXTJS.md

@@ -13,8 +13,8 @@ Browser → customer's /api/chat → existing auth / input checks
 ```
 
 Install in the application server that owns the model call, not the browser,
-Next.js middleware, or the model provider. Node >=22.22.3 is required; Edge runtime
-is not supported. The application and provider traffic remain on customer
+Next.js middleware, or the model provider. Node >=22.22.3 is required; Next.js Edge runtime
+is not supported. For the experimental Cloudflare Workers adapter, use [the Workers guide](WORKERS.md). The application and provider traffic remain on customer
 infrastructure. WebDecoy receives the client IP, URL pathname (no query string),
 method, user agent, header names and accept-language/accept-encoding values.
 Request bodies, session cookies, authorization values and responses are not sent

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.3`.** Integration mechanics are tested;
+**Alpha release: `0.1.0-alpha.12`.** 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.
@@ -16,7 +16,9 @@ npm install @webdecoy/ai-protection@alpha
 ```
 
 Node.js 22.22.3 or newer is required. The SDK has no runtime npm dependencies.
-Edge runtimes are not supported. Licensed under [Apache-2.0](LICENSE).
+Experimental Cloudflare Workers admission support is available through the
+[`/workers` entry point](WORKERS.md), with Node compatibility enabled. Workers
+concurrency and budgets, and other Edge runtimes, are not supported. Licensed under [Apache-2.0](LICENSE).
 
 Set `WEBDECOY_URL=https://ai-protection.webdecoy.com` on your server.
 Create a property-scoped API key with Write Detections permission in WebDecoy,
@@ -24,7 +26,7 @@ then review results at [AI Protection](https://app.webdecoy.com/ai-protection).
 
 ## Integrate
 
-Create the instance once in a **server-only module**, then call it inside your
+For Node.js, create the instance once in a **server-only module**, then call it inside your
 existing authenticated and validated AI endpoint:
 
 ```ts

package/WORKERS.md

@@ -0,0 +1,117 @@
+# Cloudflare Workers
+
+The `@webdecoy/ai-protection/workers` entry point provides experimental Workers
+support for request admission, local rules, shared account/session quotas and
+best-effort reporting. Node compatibility is required. Control-plane requests use manual redirects and
+reject non-success responses without following redirects or forwarding credentials.
+Local workerd tests cover
+these features; a deployed staging canary remains required before production use.
+Concurrency leases and budget settlement are not supported by this entry point.
+
+## Integration
+
+Create a fresh protection object **inside `fetch()` for each incoming request**.
+It binds that request and execution context, so `protect()` and `check()` do not
+take a Request argument. Never store the returned object in module scope. This
+keeps account refresh promises, report queues and `ctx.waitUntil` request-scoped.
+Each request performs a fresh account lookup; the Node SDK's shared cache and
+shadow baseline are not shared between Worker invocations.
+
+```js
+import {createWorkerAIProtection} from '@webdecoy/ai-protection/workers';
+
+export default {
+  async fetch(request, env, ctx) {
+    // Authenticate and validate first. Derive this context from server state.
+    const user = await authenticateAndValidate(request);
+    const protect = createWorkerAIProtection(request, {
+      webdecoyUrl: env.WEBDECOY_URL,
+      webdecoyKey: env.WEBDECOY_KEY,
+      propertyId: env.WEBDECOY_PROPERTY_ID,
+      subjectSecret: env.WEBDECOY_SUBJECT_SECRET,
+      scopeId: 'support-chat', route: '/api/chat', protectionMode: 'observe',
+      resolveClientIP: trustedClientIP,
+      accountQuota: {
+        ruleId: 'chat', limit: 20, windowSeconds: 60, mode: 'enforce',
+        failureMode: 'closed', subject: context => ({accountId: context.accountId})
+      }
+    }, ctx);
+    return protect(() => callModel(request.signal), {accountId: user.id});
+  }
+};
+```
+
+`authenticateAndValidate`, `trustedClientIP` and `callModel` are application
+functions. The resolver must return an IP vouched for by your ingress, or `null`
+to skip detection with degraded coverage. On direct Cloudflare ingress you can
+use `request.headers.get('cf-connecting-ip')`; do not assume it identifies the
+original client on Worker/service subrequests. Do not trust arbitrary forwarded
+headers. See [Cloudflare's header behavior](https://developers.cloudflare.com/fundamentals/reference/http-request-headers/#cf-connecting-ip).
+
+Configure Wrangler with the tested baseline:
+
+```toml
+compatibility_date = "2026-01-01"
+compatibility_flags = ["nodejs_compat"]
+```
+
+Store API credentials and the random subject secret (at least 32 characters) as
+Worker secrets. Shared quota subjects must come from authenticated server state.
+For idempotent quotas, use `idempotency: true` only with a migrated runtime and
+persist a server-generated operation ID if recovery must survive request loss.
+`createQuotaOperationId` is also exported from the Workers entry point.
+
+## Streaming and lifecycle
+
+The wrapper returns the original Response and does not read or rewrite the model
+stream. Pass the application's cancellation signal to the provider. A successful
+admission report describes callback/response creation, **not** stream completion,
+final token usage or proof that upstream work stopped on disconnect.
+
+Reporting is automatically attached through `task => ctx.waitUntil(task)` and is
+bounded by the core reporting timeout (1000ms default, 10000ms maximum). Reporting
+is best-effort; `waitUntil` is not durable delivery. Cloudflare permits up to
+30 seconds of extension after the response completes or the client disconnects.
+Long-running background model work needs a separate execution design. See
+[Cloudflare execution context](https://developers.cloudflare.com/workers/runtime-apis/context/).
+
+For custom decisions, use `protect.check(trustedContext)` and report exactly once
+with `protect.report(decision, outcome)`. `flush()` waits only for this request's
+pending reports. The adapter rejects `concurrency` at construction; it exposes
+neither `.concurrent()` nor `createAIBudget`. Using the Node entry point directly
+does not establish Workers support for those features.
+
+## Run the fixture
+
+From this repository root:
+
+```sh
+npm ci
+npm exec -- wrangler secret put WEBDECOY_KEY --config examples/workers/wrangler.toml
+npm exec -- wrangler secret put WEBDECOY_PROPERTY_ID --config examples/workers/wrangler.toml
+npm exec -- wrangler secret put WEBDECOY_SUBJECT_SECRET --config examples/workers/wrangler.toml
+npm exec -- wrangler secret put EXAMPLE_TOKEN --config examples/workers/wrangler.toml
+npm exec -- wrangler dev --config examples/workers/wrangler.toml
+```
+
+For local development instead, put these four values in
+`examples/workers/.dev.vars` (gitignored); no remote secret provisioning is needed.
+The example imports the local SDK source. In your own project import the package
+subpath shown above. Send POST `/api/chat` with `Authorization: Bearer <EXAMPLE_TOKEN>`.
+The fixture returns text and invokes no model; replace its auth and callback with
+your application's integration. It starts in observation mode.
+
+## Validation and rollout
+
+`npm run test:workers` bundles the SDK and executes the Worker in Miniflare/workerd
+with a simulated WebDecoy service. It verifies local/cloud denial, original
+responses, stream passthrough, pre-cancelled requests, degraded detector outages,
+simultaneous requests, asynchronous report completion and idempotent quota retry.
+CI runs this alongside Node, type and package checks. Protocol fixtures do not
+prove remote connectivity, database contention or detection accuracy.
+
+Before production, deploy an owned staging Worker against the real service and
+verify report persistence, entitled enforcement, shared quota contention across
+invocations and service outages. Before adding concurrency/budgets, validate long
+streams, midstream client disconnects, provider cancellation, heartbeat failure,
+lease expiry and conservative settlement when usage is unknown.

package/account.mjs

@@ -13,7 +13,7 @@ export function createAccountBinding({webdecoyUrl, webdecoyKey, propertyId, dete
       let next = {status:'unavailable', enforce:false};
       try {
         const response = await fetch(new URL('/api/v1/sdk/ai-abuse/config', webdecoyUrl), {
-          headers:{Authorization:`Bearer ${webdecoyKey}`}, redirect:'error',
+          headers:{Authorization:`Bearer ${webdecoyKey}`}, redirect:'manual',
           signal:AbortSignal.any([signal, AbortSignal.timeout(detectorTimeoutMs)])
         });
         if (!response.ok) { await response.body?.cancel(); throw new Error('account_unavailable'); }

package/action-runtime.mjs

@@ -2,6 +2,7 @@ import {prepareWork} from './work.mjs';
 import {prepareQuota,quotaHash} from './quota.mjs';
 import {prepareConcurrency} from './concurrency.mjs';
 import {validPropertyID} from './account.mjs';
+import {readJSON} from './transport.mjs';
 import {createReporter} from './reporting.mjs';
 
 export function prepareActionRuntime(options, definitions) {
@@ -13,6 +14,10 @@ export function prepareActionRuntime(options, definitions) {
     typeof config.webdecoyKey!=='string'||!config.webdecoyKey||/[^\x21-\x7e]/.test(config.webdecoyKey)||
     typeof config.subjectSecret!=='string'||!config.subjectSecret.isWellFormed()||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
   if(config.reportCaller !== undefined && typeof config.reportCaller !== "boolean")throw Error("Invalid caller reporting option");
+  if(config.callerPause !== undefined && typeof config.callerPause !== 'boolean')throw Error('Invalid caller pause option');
+  if(config.callerPause && !config.reportCaller)throw Error('Caller pause requires caller reporting');
+  const pauseTimeout=config.callerPauseTimeoutMs??1000;
+  if(!Number.isInteger(pauseTimeout)||pauseTimeout<1||pauseTimeout>10000)throw Error('Invalid caller pause timeout');
   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){
@@ -44,5 +49,27 @@ export function prepareActionRuntime(options, definitions) {
         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,callerEvidence:caller=>c.reportCaller?Object.freeze({schema:1,source:'application_auth',id:quotaHash(c.subjectSecret,'webdecoy.actions.evidence.caller.v1',c.propertyId.toLowerCase(),caller.issuer,caller.tenant,caller.subject)}):undefined,report:event=>reporter.send(event),flush:()=>reporter.flush()};
+  const checkCallerPause = c.callerPause ? async (caller,signal) => {
+    signal.throwIfAborted();const started=performance.now();
+    const check={id:'caller_pause',source:'shared',mode:'enforce',decision:'unavailable',reason:'caller_pause_unavailable',durationMs:0};
+    let denial;
+    try {
+      const id=actionCallerEvidence(c,caller).id;
+      const response=await fetch(new URL('/api/v1/sdk/ai-abuse/caller-pause',c.webdecoyUrl),{
+        method:'POST',redirect:'error',signal:AbortSignal.any([signal,AbortSignal.timeout(pauseTimeout)]),
+        headers:{Authorization:`Bearer ${c.webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':c.propertyId},body:JSON.stringify({schema:1,caller:id})
+      });
+      if(!response.ok){await response.body?.cancel();throw Error('Caller control unavailable');}
+      const value=await readJSON(response,2048);
+      if(value.schema!==1||value.property_id!==c.propertyId.toLowerCase()||value.caller!==id||typeof value.allowed!=='boolean'||value.reason!==(value.allowed?'caller_allowed':'caller_paused'))throw Error('Invalid caller control response');
+      check.decision=value.allowed?'allow':'deny';check.reason=value.reason;
+      if(!value.allowed)denial={reason:'caller_paused',status:403};
+    } catch { signal.throwIfAborted(); }
+    check.durationMs=Math.max(0,performance.now()-started);return {check,denial};
+  }:null;
+  return {limits,checkCallerPause,callerEvidence:caller=>actionCallerEvidence(c,caller),report:event=>reporter.send(event),flush:()=>reporter.flush()};
+}
+
+export function actionCallerEvidence(config,caller) {
+  return config.reportCaller?Object.freeze({schema:1,source:'application_auth',id:quotaHash(config.subjectSecret,'webdecoy.actions.evidence.caller.v1',config.propertyId.toLowerCase(),caller.issuer,caller.tenant,caller.subject)}):undefined;
 }

package/actions.d.mts

@@ -69,6 +69,10 @@ export interface ActionLimits {
 export interface ActionRuntime {
   /** Opt in to scoped caller pseudonyms in reports. Requires a supporting runtime. Default false. */
   reportCaller?:boolean;
+  /** Opt-in online caller pause check before work. Requires reportCaller. Fails open on timeout (default 1000ms); no cache, retry or in-flight cancellation. */
+  callerPause?:boolean;
+  /** Caller-pause RPC deadline, 1–10000ms; default 1000ms. Short deadlines can fail open during cold authentication. */
+  callerPauseTimeoutMs?:number;
   webdecoyUrl:string;webdecoyKey:string;propertyId:string;subjectSecret:string;
   reportingTimeoutMs?:number;maxPendingReports?:number;
 }

package/actions.mjs

@@ -133,6 +133,10 @@ export function createActionProtection(options) {
       // Shared limits run only after application permission checks. Their own
       // RPC deadlines are separate from local admission and detector availability.
       clearTimeout(timer);
+      if(runtime?.checkCallerPause){
+        const r=await runtime.checkCallerPause(caller,admissionSignal);checks.push(r.check);
+        if(r.denial)deny(r.denial.reason,r.denial.status);
+      }
       const controls=runtime?.limits.get(name);
       for(const gate of controls?.gates??[]){
         const r=await gate(context,admissionSignal);checks.push(r.check);

package/admission.mjs

@@ -45,7 +45,7 @@ export function createAdmission(options) {
       let verdict;
       try {
         const response = await fetch(new URL('/api/v1/sdk/detect', c.webdecoyUrl), {
-          method: 'POST', redirect: 'error',
+          method: 'POST', redirect: 'manual',
           headers: {'Authorization': `Bearer ${c.webdecoyKey}`, 'Content-Type': 'application/json'},
           signal: AbortSignal.any([signal, AbortSignal.timeout(c.detectorTimeoutMs)]),
           body: JSON.stringify({

package/mcp.mjs

@@ -1,6 +1,7 @@
 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 { actionCallerEvidence } from './action-runtime.mjs';
 import { createActionProtection, ActionDenied } from './actions.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { createReporter } from './reporting.mjs';
@@ -54,12 +55,12 @@ export function createProtectedMCPHandler(options) {
     const catalogReporter = options.discovery ? createReporter({
         reportingTimeoutMs: runtime.reportingTimeoutMs ?? 1000,
         maxPendingReports: runtime.maxPendingReports ?? 100,
-        onObservation: async (names, { signal }) => {
+        onObservation: async ({names,caller}, { signal }) => {
             const response = await fetch(new URL('/api/v1/sdk/ai-abuse/reports', runtime.webdecoyUrl), {
                 method: 'POST', redirect: 'error', signal,
                 headers: { Authorization: `Bearer ${runtime.webdecoyKey}`, 'X-WebDecoy-Property-ID': runtime.propertyId, 'Content-Type': 'application/json' },
                 body: JSON.stringify({ schema: 3, request_id: randomUUID(), timestamp: new Date().toISOString(), action: 'tool_discovery',
-                    tool_catalog: { server_id: serverId, source: 'tools_list', tools: names.map(name => ({ name, schema_hash: hashes[name], effect: tools[name].toolSchema.effect, permissions: tools[name].toolSchema.permissions, ...(decoys.has(name)?{decoy:decoys.get(name)}:{}) })) } })
+                    tool_catalog: { server_id: serverId, source: 'tools_list', ...(caller?{caller}:{}), tools: names.map(name => ({ name, schema_hash: hashes[name], effect: tools[name].toolSchema.effect, permissions: tools[name].toolSchema.permissions, ...(decoys.has(name)?{decoy:decoys.get(name)}:{}) })) } })
             });
             await response.body?.cancel();
             if (!response.ok) throw Error('Discovery reporting unavailable');
@@ -214,7 +215,7 @@ export function createProtectedMCPHandler(options) {
             res.once('close', () => { void server.close().catch(() => { }); });
             server.setRequestHandler(ListToolsRequestSchema, async () => {
                 const visible = Object.entries(tools).filter(([name, tool]) => decoys.get(name) !== 'unadvertised' && tool.requiredScopes.every(s => caller.scopes.includes(s)));
-                for (let i=0;i<visible.length;i+=64) void catalogReporter?.send(visible.slice(i,i+64).map(([name]) => name));
+                for (let i=0;i<Math.max(1,visible.length);i+=64) void catalogReporter?.send({names:visible.slice(i,i+64).map(([name]) => name),caller:runtime? actionCallerEvidence(runtime,caller):undefined});
                 return { tools: visible.map(([name, tool]) => ({ name, description: tool.description, inputSchema: tool.inputSchema, ...(tool.annotations ? {annotations:tool.annotations} : {}) })) };
             });
             server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {

package/package.json

@@ -6,11 +6,12 @@
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "prepublishOnly": "npm test && npm run test:types && npm run check:package",
+    "prepublishOnly": "npm test && npm run test:workers && 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/mcp-types.mts"
+    "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts test/mcp-types.mts",
+    "test:workers": "node --test test/workers/*.test.mjs"
   },
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.14",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",
@@ -31,6 +32,10 @@
     "./mcp": {
       "types": "./mcp.d.mts",
       "import": "./mcp.mjs"
+    },
+    "./workers": {
+      "types": "./workers.d.mts",
+      "import": "./workers.mjs"
     }
   },
   "files": [
@@ -63,9 +68,12 @@
     "MCP.md",
     "work.mjs",
     "WORK.md",
-    "tool-effects.mjs"
+    "tool-effects.mjs",
+    "workers.mjs",
+    "workers.d.mts",
+    "WORKERS.md"
   ],
-  "description": "Bot and abuse protection for AI-powered applications. Server-side request admission for Node.js.",
+  "description": "Bot and abuse protection for AI-powered applications. Request admission for Node.js and experimental Cloudflare Workers.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -89,7 +97,10 @@
   "devDependencies": {
     "typescript": "6.0.3",
     "@modelcontextprotocol/sdk": "1.31.0",
-    "@types/node": "22.19.15"
+    "@types/node": "22.19.15",
+    "esbuild": "^0.28.2",
+    "miniflare": "^4.20260730.0",
+    "wrangler": "^4.147.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "1.31.0"

package/quota.mjs

@@ -48,7 +48,7 @@ export function prepareQuota(options) {
        signal.throwIfAborted();
        try {
       const response=await fetch(new URL('/api/v1/sdk/ai-abuse/quota',webdecoyUrl),{
-        method:'POST',redirect:'error',signal:AbortSignal.any([signal,AbortSignal.timeout(q.timeoutMs)]),
+        method:'POST',redirect:'manual',signal:AbortSignal.any([signal,AbortSignal.timeout(q.timeoutMs)]),
         headers:{Authorization:`Bearer ${webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':propertyId},body:JSON.stringify(payload)
       });
       if(!response.ok){await response.body?.cancel();const error=Error('Quota unavailable');error.terminal=response.status<500;throw error;}

package/telemetry.mjs

@@ -11,7 +11,7 @@ export function createTelemetry({webdecoyUrl, webdecoyKey, propertyId, reportToW
       ...(event.handler_status !== undefined ? {handler_status:event.handler_status} : {}),
       action:event.action};
     const response = await fetch(new URL('/api/v1/sdk/ai-abuse/reports',webdecoyUrl),{
-      method:'POST',redirect:'error',signal,
+      method:'POST',redirect:'manual',signal,
       headers:{Authorization:`Bearer ${webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':propertyId},
       body:JSON.stringify(payload)
     });

package/workers.d.mts

@@ -0,0 +1,19 @@
+import type {AIProtectionOptions, ProtectionDecision, ReportOutcome} from './fetch.mjs';
+export {createQuotaOperationId} from './fetch.mjs';
+/** Structural type; does not require Cloudflare types in Node consumers. */
+export interface WorkerExecutionContext {waitUntil(task: Promise<unknown>): void}
+export type WorkerAIProtectionOptions<Context = Record<string, unknown>> =
+  Omit<AIProtectionOptions<Context>, 'waitUntil' | 'concurrency'>;
+export interface WorkerAIProtection<Context> {
+  (handler: () => Response | Promise<Response>, context: Context): Promise<Response>;
+  check(context: Context): Promise<ProtectionDecision>;
+  report(decision: ProtectionDecision, outcome?: ReportOutcome): Promise<void>;
+  flush(): Promise<void>;
+}
+export interface ContextOptionalWorkerProtection extends WorkerAIProtection<Record<string, unknown>> {
+  (handler: () => Response | Promise<Response>, context?: Record<string, unknown>): Promise<Response>;
+  check(context?: Record<string, unknown>): Promise<ProtectionDecision>;
+}
+/** Create inside the Worker fetch handler; the returned object belongs to this request only. */
+export function createWorkerAIProtection(request: Request, options: WorkerAIProtectionOptions, ctx: WorkerExecutionContext): ContextOptionalWorkerProtection;
+export function createWorkerAIProtection<Context>(request: Request, options: WorkerAIProtectionOptions<Context>, ctx: WorkerExecutionContext): WorkerAIProtection<Context>;

package/workers.mjs

@@ -0,0 +1,17 @@
+import {createAIProtection} from './fetch.mjs';
+export {createQuotaOperationId} from './quota.mjs';
+
+// Call inside fetch(), once per incoming request. No request-owned I/O or ctx
+// escapes into a shared instance, including the core's pending config refresh.
+export function createWorkerAIProtection(request, options, ctx) {
+  if (!(request instanceof Request)) throw Error('Worker Request required');
+  if (!ctx || typeof ctx.waitUntil !== 'function') throw Error('Worker execution context required');
+  if (options.concurrency !== undefined) throw Error('Workers concurrency is not supported yet');
+  const core = createAIProtection({...options, waitUntil: task => ctx.waitUntil(task)});
+  const protect = (handler, context = {}) => core(request, handler, context);
+  return Object.assign(protect, {
+    check: (context = {}) => core.check(request, context),
+    report: core.report,
+    flush: core.flush
+  });
+}