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

package/MCP.md

@@ -8,10 +8,10 @@ resource authorization.
 
 ## Install
 
-Available in `0.1.0-alpha.4` and later compatible alpha releases:
+Available in `0.1.0-alpha.5` and later compatible alpha releases:
 
 ```sh
-npm install @webdecoy/ai-protection@0.1.0-alpha.4 @modelcontextprotocol/sdk@1.31.0
+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
@@ -111,9 +111,12 @@ have unknown work. Never retry writes without application/provider idempotency.
   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.
+  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

@@ -328,3 +328,35 @@ and maps tenant membership. The [MCP adapter](MCP.md) provides a separate `/mcp`
 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.
+
+### Opt-in tool caller attribution
+
+With a runtime supporting caller evidence, set `sharedRuntime.reportCaller: true`
+on `createActionProtection`. It defaults to false. Hosted reports and `onEvent`
+then include `caller: {schema: 1, source: 'application_auth', id: '<digest>'}`
+after successful authentication, including subsequent permission denials.
+Failed authentication, rejected arguments before authentication, and unknown tools
+have no caller attribution. Existing request admission reporting is unchanged.
+
+The SDK derives this HMAC-SHA256 pseudonym from the server-owned `subjectSecret`,
+a dedicated versioned domain, property ID, issuer, application tenant and subject.
+Replicas must use the same secret to correlate callers. Raw subjects, issuers,
+tenants, scopes, tokens and tool arguments are not added to reports. OAuth clients
+and agent signers are not treated as the authenticated subject. Your authentication
+hook must verify credentials and tenant membership; WebDecoy does not independently
+verify those credentials from this report, and a pseudonym is not a unique person.
+
+Use a randomly generated secret of at least 32 bytes and store it server-side.
+Rotating it changes pseudonyms and also changes existing shared-limit identities
+that use this secret; coordinate rotation because it can reset quota continuity.
+Historical pseudonyms are not relinked. AI Protection displays a seven-day receipt
+window and existing report retention purges expired records in bounded background
+sweeps. Counts cover reported, consistently attributed actions only; dropped reports,
+older SDKs and conflicting bindings leave gaps. Install server support before
+enabling this option: older runtimes reject the additional field.

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';
@@ -10,7 +11,8 @@ export function prepareActionRuntime(options, definitions) {
   if(!['https:','http:'].includes(url.protocol)||url.username||url.password||url.pathname!=='/'||url.search||url.hash||
     (url.protocol==='http:'&&!['localhost','127.0.0.1','[::1]'].includes(url.hostname))||!validPropertyID(config.propertyId)||
     typeof config.webdecoyKey!=='string'||!config.webdecoyKey||/[^\x21-\x7e]/.test(config.webdecoyKey)||
-    typeof config.subjectSecret!=='string'||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
+    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");
   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){
@@ -20,10 +22,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,10 +39,10 @@ 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.caller?{caller:event.caller}:{}),...(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');
     }});
-  return {limits,report:event=>reporter.send(event),flush:()=>reporter.flush()};
+  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()};
 }

package/actions.d.mts

@@ -13,11 +13,29 @@ 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 {
+  /** Pseudonymous application-authenticated subject, not WebDecoy-verified agent identity. */
+  readonly caller?: {readonly schema:1;readonly source:'application_auth';readonly id:string};
+  readonly work?:ActionWorkEvidence;
   readonly schema: 1;
   readonly eventId: string;
   readonly timestamp: string;
@@ -33,11 +51,15 @@ 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};
 }
 export interface ActionRuntime {
+  /** Opt in to scoped caller pseudonyms in reports. Requires a supporting runtime. Default false. */
+  reportCaller?:boolean;
   webdecoyUrl:string;webdecoyKey:string;propertyId:string;subjectSecret:string;
   reportingTimeoutMs?:number;maxPendingReports?:number;
 }

package/actions.mjs

@@ -3,7 +3,7 @@ import {abortable} from './transport.mjs';
 import {prepareActionRuntime} from './action-runtime.mjs';
 
 const token = /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,95}$/;
-const bounded = value => typeof value === 'string' && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
+const bounded = value => typeof value === 'string' && value.isWellFormed() && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
 const freeze = value => {
   if (value && typeof value === 'object') { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }
   return value;
@@ -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,callerEvidence;
+    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})))});
+        ...(callerEvidence?{caller:callerEvidence}:{}),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++;
@@ -106,6 +107,7 @@ export function createActionProtection(options) {
       let caller;
       try { caller = callerSnapshot(await evaluate(() => authenticate(authenticationContext, {signal:admissionSignal}))); }
       catch { cancelled(); deny('authentication_required',401); }
+      callerEvidence=runtime?.callerEvidence(caller);
       cancelled();
       if (action.requiredScopes.some(scope => !caller.scopes.includes(scope))) deny('missing_scope',403);
       const context = Object.freeze({caller, args, signal:admissionSignal});
@@ -131,38 +133,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/package.json

@@ -10,7 +10,7 @@
     "check:package": "node scripts/check-package.mjs",
     "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts test/mcp-types.mts"
   },
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",
@@ -60,7 +60,9 @@
     "action-runtime.mjs",
     "mcp.mjs",
     "mcp.d.mts",
-    "MCP.md"
+    "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",

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};}
+  }};
+ };
+}