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

package/ARCHITECTURE.md

@@ -119,15 +119,13 @@ values in rule IDs/reason codes.
 
 Ingest deduplicates by organization/property/request ID: the first accepted report
 wins, including its receipt time. There are no automatic retries. Reports are
-bounded to 32 KiB and 36 checks (32 local rules, quota, concurrency, cloud and browser evidence). The pilot endpoint
-limits traffic to 6000 reports/minute per source IP with a burst of 200; excess
-reports are dropped by this SDK after a generic warning, without affecting chat.
+bounded to 32 KiB and 36 checks (32 local rules, quota, concurrency, cloud and browser evidence). Rate-limited reports are dropped by this SDK after a generic warning, without affecting chat.
 
 The dashboard presents these as **SDK-reported application decisions**, separate
 from server-derived detector evidence. They are not summed into detection counts,
 charged as detections, or treated as proof of blocked inference or savings. The
 same request ID lets users correlate the two sources. Counts use receipt time;
-reports have a seven-day window and hourly retention cleanup. A prolonged outage
+report availability depends on service retention. A prolonged outage
 can prevent delivery, so this is not complete audit coverage.
 
 `onObservation(event, {signal})` can return a promise. `report()` catches rejection,
@@ -162,5 +160,4 @@ provider attempt; it is not an automatic middleware spending cap. Both controls
 default to observe/open; enforce/closed is an explicit state-availability tradeoff.
 Usage events are separate from schema-1 request reports and include numeric rates,
 tokens and call/request/reservation UUIDs. They do not include raw identities or
-model content. See README and RELEASE.md; backend contracts are maintained in the
-private app repository's integrations/ai-abuse documentation.
+model content. See the README for configuration and integration examples.

package/MCP.md

@@ -0,0 +1,322 @@
+# 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.11 @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).
+
+
+## Opt-in tool discovery (alpha.7+)
+
+Add these options alongside your existing `tools` and authentication configuration:
+
+```ts
+sharedRuntime: {
+  webdecoyUrl: 'https://ai-protection.webdecoy.com',
+  webdecoyKey: process.env.WEBDECOY_API_KEY!,
+  propertyId: process.env.WEBDECOY_PROPERTY_ID!,
+  subjectSecret: process.env.WEBDECOY_SUBJECT_SECRET!, // at least 32 bytes
+},
+discovery: { serverId: 'records-api' },
+```
+
+Use a stable, non-secret server label (1–96 letters, digits, `_`, `.`, `:`, `-`,
+starting with a letter or digit). Reuse it across replicas/releases of the same
+logical server. Give separate servers separate labels within a property. Do not
+include tenant IDs, hostnames containing secrets, or customer information.
+
+An authenticated MCP client calls `tools/list`. Each nonempty response queues a
+best-effort advertisement of the visible tool names and SHA-256 input-schema
+hashes. The AI Protection dashboard shows **MCP tool inventory**, including
+tools that have never executed. This does not scan unwrapped servers, hidden tools,
+resources, prompts or alternate routes. No network request is made at handler
+construction. Discovery is off unless configured and requires sharedRuntime.
+
+Hashes cover the JSON input schema with recursively sorted object keys; array
+order is preserved. Raw schemas, descriptions, arguments, results, credentials,
+caller identities and required scopes are not uploaded. A schema hash is a
+fingerprint, not encryption; someone with a candidate schema can compare it.
+Multiple hashes for one server/tool show reported variants in the seven-day
+receipt window. Rolling deployments and benign schema edits can cause variants.
+They do not establish an attack, breaking change, removal or missing permission.
+The UI uses the latest receipt's hash, not a claim about deployment order.
+
+Discovery uses schema-3 reports on the existing reporting endpoint; deploy a
+compatible hosted runtime first. Old runtimes reject these optional reports
+without affecting tool listing. Reporting has bounded pending work and a deadline,
+never blocks authorization, and does not retry. Call `await handler.flush()` at a
+host shutdown/lifecycle boundary to drain pending discovery reports; it does not
+wait for active tool calls or action reports. Abruptly terminated hosts can lose
+reports. Discovery advertisements never increment tool action or request counts.
+
+
+### Calls before discovery (alpha.8+)
+
+With `discovery` enabled, the adapter also attaches the registered server label
+and schema fingerprint to each `tools/call` action report. This includes local
+permission/scope denials for registered tools. It works before a client calls
+`tools/list`; no listing round trip is required to execute an authorized tool.
+Unknown tool names and requests rejected before authentication do not gain
+registry metadata. Turning discovery off omits the new call metadata too.
+
+The inventory combines advertisements and action evidence by property, server
+label and tool name. Attempt/start/completion reports sharing an action ID count
+once. Counts include denied attempts, so they are not successful-execution totals.
+“Call evidence only” means no advertisement was captured in the bounded seven-day
+sample. Clients can call directly; hidden scopes, sampling and missing telemetry
+also limit coverage. This is not an attack or permission-gap verdict. Older action
+reports without metadata still appear in the general activity table, aggregated
+by tool name across servers; their server/schema association remains unknown.
+
+Deploy a runtime accepting optional `tool_action.tool_schema` before upgrading an
+integration with discovery enabled. Older runtimes reject affected action reports
+without changing admission. The action API also supports optional `toolSchema:
+{serverId, hash}` on trusted registered definitions; it is snapshotted and validated,
+never read from tool arguments. This is SDK-reported metadata, not authorization
+or independent verification of a schema.
+
+
+### Advisory side effects (alpha.9+)
+
+With discovery enabled, the SDK adds a fixed classification and reason code to
+catalog/call metadata: `unknown`, `read_only`, `mutating`, or `destructive`.
+This is heuristic inference, not a prompt scanner, authorization policy, verified
+behavior or proof that side effects occurred. Classification never allows or
+blocks a request. Existing validate/authorize/scopes/limits still control dispatch.
+
+You may supply MCP boolean hints on a protected tool:
+
+```ts
+annotations: { readOnlyHint: true, destructiveHint: false },
+```
+
+Supported annotations are readOnlyHint, destructiveHint, idempotentHint and
+openWorldHint. The adapter snapshots those booleans and includes them in scoped
+MCP listing responses. Only classification codes enter WebDecoy reports; raw
+annotations, schemas and descriptions are not uploaded. The schema fingerprint
+continues to cover inputSchema, not annotations or implementation code.
+
+The classifier checks tokenized tool names and explicit top-level `action`,
+`operation` or `method` selectors (`const`/up to 64 enum values). It does not
+resolve schema references, scan arbitrary text/arguments, execute tools, or call a
+model. Destructive/mutating signals take precedence over a contradictory read-only
+hint and are labeled conflicting. With no useful signals it reports unknown.
+Name heuristics can be wrong (for example, a status tool named after deletion).
+As the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
+requires, annotations must not be treated as guarantees from an untrusted server.
+
+The dashboard shows inferred evidence separately from a customer classification.
+Use **Review classification** to select a label or return to SDK inference.
+Overrides are property/server/tool settings bound to the current input-schema
+hash; a different hash falls back to inference and prompts review. Changes to
+annotations or implementation without a schema change do not invalidate an
+override, so review those changes yourself. A saved classification changes only
+the dashboard label; it is not read by runtime enforcement. Overrides persist as
+customer settings until reset or property deletion; SDK evidence retains its
+seven-day window. Where evidence disagrees for the latest received schema, the
+review order is destructive, mutating, unknown, then read-only. Older SDKs without
+classification metadata remain unknown, though customers can label their tools.
+
+Requires a runtime accepting optional `effect` evidence. Deploy it before
+upgrading a discovery-enabled integration. Large registries are split into
+bounded catalog batches so added metadata stays within report body limits.
+
+## Reviewing tool permissions
+
+Discovery reports configuration evidence for each registered tool: the number of
+`requiredScopes`, the presence of the mandatory `authorize` callback, and whether
+an additional `policy` callback is configured. It never reports scope names or
+callback code. These are SDK-reported settings, not verified authorization quality.
+This metadata starts in Node alpha.10. Deploy a compatible runtime before upgrading.
+
+The inventory asks you to review a potentially mutating/destructive tool with no
+required scopes. This does **not** mean it is unprotected: application authorization
+may already provide sufficient protection. Review the named server/tool in your
+registry and check the application's tenant/resource ownership checks. Where your
+OAuth model uses per-tool scopes, configure them on that tool, for example:
+
+```js
+requiredScopes: ['records:write'],
+authorize: ({caller, args, signal}) =>
+  canModifyRecord(caller.tenant, caller.subject, args.id, {signal}),
+```
+
+`canModifyRecord` is your application's authorization function. Preserve ownership
+checks at the database transaction that performs the write. After deploying, make
+an authenticated tools/list or tools/call request and refresh the inventory.
+The dashboard cannot edit or inspect your application callback. An additional
+policy cannot override a deny from application authorization.
+
+Older/missing evidence remains unknown. Conflicting reported configurations for
+the selected input-schema hash remain conflicting. The seven-day bounded sample
+can include both sides of a rolling deployment; it does not certify the latest
+running configuration or prove that unwrapped routes are protected. A changed
+scope or callback does not change the input-schema hash. No enforcement behavior
+changes when discovery is enabled.
+
+## Explicit decoy tools (Alpha)
+
+Decoys are off by default. Node alpha.11 supports up to eight explicitly named
+synthetic tools in the protected registry; requires `discovery` and `sharedRuntime`.
+The combined real/decoy registry still has a 128-tool limit. Deploy a compatible
+runtime before upgrading an integration that enables decoys.
+
+```js
+discovery: {serverId: 'billing'},
+decoys: {
+  billing_export_ledger: {
+    description: 'Internal ledger export',
+    visibility: 'advertised',
+  },
+  admin_rotate_keys: {
+    description: 'Internal key rotation',
+    visibility: 'unadvertised',
+  },
+},
+```
+
+Choose names and descriptions outside legitimate workflows; examples are not a
+recommended universal decoy set. Collisions with real tools, callback fields and
+invalid definitions fail startup. Definitions are snapshotted. The SDK provides a
+generic object schema; no custom execution, validation or authorization callbacks
+are accepted for decoys. Advertised decoys appear to authenticated listing clients;
+unadvertised decoys never appear in tools/list. Both accept direct authenticated
+calls only to return the ordinary permission-denied error. Customer code is never
+executed, including when shared telemetry is unavailable. Real tools retain their
+normal authorization and behavior.
+
+Only reported calls count as decoy calls; listing is not a trip. Discovery and
+call reports carry a fixed decoy visibility marker, not arguments, hashes of
+arguments, descriptions or generated identities. Existing opt-in caller attribution
+can associate calls with application-reported pseudonyms. Invalid unauthenticated
+requests, over-limit transport bodies and unwrapped routes are not covered by this
+trip evidence. Delivery remains best effort. A marker is SDK-reported evidence,
+not independently verified server configuration.
+
+The dashboard labels decoys and mixed real/decoy evidence, counts deduplicated
+calls, and excludes synthetic entries from normal permission/advertisement review
+findings. Name-aggregated activity is labeled when it includes decoys. Reusing a
+name for a real tool can yield mixed evidence until retained reports expire.
+
+A decoy call can come from legitimate exploration or a naive agent; it is not proof
+of malicious intent. This slice does not auto-block callers, measure false-positive
+rates, generate seeded names, record initialization events, remotely deliver decoy
+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.

package/NEXTJS.md

@@ -132,7 +132,7 @@ enabling the pilot; absent/unavailable reporting never changes request decisions
   `upstream_attempted` remains false: this adapter cannot observe model activity.
 - Account policy caches and per-call timeouts are documented in README. Cold remote admission can wait roughly two seconds with defaults, plus up to
   one second of IP resolution. Optional quota, lease acquisition and reservation
-  each add their own deadline. See RELEASE.md.
+  each add their own deadline. See the README configuration section.
 
 Use the AI SDK's documented `consumeSseStream: consumeStream` handling alongside
 `abortSignal` when returning UI streams. Provider cancellation/billing remains

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.1`.** Integration mechanics are tested;
+**Alpha release: `0.1.0-alpha.3`.** Integration mechanics are tested;
 real-world detection accuracy and provider cost savings have not been established.
 Requires a WebDecoy property, a property-scoped API key, and a compatible WebDecoy
 service deployment. This repository contains the SDK, not the detection service.
@@ -129,7 +129,7 @@ npm test
 ```
 
 Tests use a local detector and local AI model; no live keys or paid inference.
-[Release instructions](RELEASING.md) cover publishing the public npm package.
+Source and release history are available in this public repository.
 
 ## Shared account quotas (opt-in)
 
@@ -153,7 +153,7 @@ observation, with a one-second timeout and fail-open for state errors. Use
 Enforced exhaustion returns 429 and `Retry-After`; explicit `check` callers use
 `decision.retryAfterSeconds` and must enforce the decision themselves.
 
-This needs the shared quota backend (migration 78 and `/api/v1/sdk/ai-abuse/quota`).
+This uses the hosted `/api/v1/sdk/ai-abuse/quota` endpoint.
 Observation and enforcement share counters. In default schema 1, each allowed
 admission consumes a unit, including retries and requests later cancelled/blocked
 by another check; there are no automatic retries or refunds. Opt-in schema 2
@@ -179,7 +179,7 @@ capacity limits do not change the detector's separate failure policy. State can
 commit just before a timeout, so a failed check does not prove no unit was used.
 
 
-## Distributed concurrency (unpublished, #1373)
+## Distributed concurrency
 
 Optional concurrency policy shares per-account and property/feature capacity
 across app replicas. Defaults are observe/open; detector failure policy is
@@ -202,11 +202,9 @@ proof a remote provider stopped. Upstream work must honor cancellation and have
 a real runtime bound. Fail-open outages cannot guarantee a concurrency cap.
 Released replay tombstones remain 24 hours: the pilot cap is 10,000 granted
 acquisitions/day/property and 32 policies/property. This is not a throughput SLA.
-The private app repository's `integrations/ai-abuse/CONCURRENCY.md` documents the
-wire contract, failure behavior, deployment order and validation evidence.
 
 
-## Upstream model budgets (unpublished, #1374)
+## Upstream model budgets
 
 Opt-in token and integer micro-USD budgets reserve a conservative maximum before
 each provider attempt and reconcile only confirmed usage. Configure account,
@@ -234,8 +232,7 @@ is based on admission time, not the provider's invoice period.
 There is an Ollama final-usage normalizer for native generate/chat metadata;
 other provider clients need a reviewed application adapter. The SDK never parses
 or stores prompts/outputs to meter usage. This does not change WebDecoy plans or
-create a subscription meter. The private app's `integrations/ai-abuse/BUDGETS.md`
-contains examples, supported workloads, privacy, capacity and release gates.
+create a subscription meter.
 
 ## Optional browser evidence
 
@@ -292,7 +289,7 @@ metadata values still leave the app; never place secrets in those values.
 Reporting timeouts and queue capacity each have a maximum of 10000 (ms/events).
 Application rules and hooks must not block the event loop. There is no unconditional
 wall-clock SLA for arbitrary customer code or uncooperative hosting runtimes.
-See RELEASE.md for supported versions, installation and release checks.
+See the installation and configuration sections above for supported versions and setup.
 
 ### Recovering an uncertain quota admission (opt-in)
 
@@ -319,5 +316,47 @@ unknown operation blindly. The stored quota count/retry hint is an original-wind
 snapshot, not current quota state.
 
 Only admission is deduplicated. Repeated application/model calls still require
-application-level idempotency. Deploy migration 83, grants and runtime support
-before enabling this option; no package publication is required for local testing.
+application-level idempotency. The hosted runtime must support quota schema 2 before enabling this option.
+
+## Action authorization (Alpha)
+
+Version `0.1.0-alpha.3` includes an action boundary at `@webdecoy/ai-protection/actions`. See the
+[record-action example and integration contract](examples/actions/README.md).
+This API requires your server authentication and application authorization.
+An [Auth0 access-token example](examples/auth0/README.md) verifies signed tokens
+and maps tenant membership. The [MCP adapter](MCP.md) provides a separate `/mcp` entrypoint for stateless
+HTTP tool dispatch starting in `0.1.0-alpha.4`.
+It requires the optional, pinned MCP SDK peer. Optional shared quotas, concurrency and hosted
+action events are documented in the action guide and use the hosted AI Protection runtime and dashboard.
+
+## 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

@@ -0,0 +1,48 @@
+import {prepareWork} from './work.mjs';
+import {prepareQuota,quotaHash} from './quota.mjs';
+import {prepareConcurrency} from './concurrency.mjs';
+import {validPropertyID} from './account.mjs';
+import {createReporter} from './reporting.mjs';
+
+export function prepareActionRuntime(options, definitions) {
+  const config=options.sharedRuntime;
+  if(!config){if([...definitions.values()].some(d=>d.limits))throw Error('Action limits require sharedRuntime');return null;}
+  const url=new URL(config.webdecoyUrl);
+  if(!['https:','http:'].includes(url.protocol)||url.username||url.password||url.pathname!=='/'||url.search||url.hash||
+    (url.protocol==='http:'&&!['localhost','127.0.0.1','[::1]'].includes(url.hostname))||!validPropertyID(config.propertyId)||
+    typeof config.webdecoyKey!=='string'||!config.webdecoyKey||/[^\x21-\x7e]/.test(config.webdecoyKey)||
+    typeof config.subjectSecret!=='string'||!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){
+    const l=d.limits??{},gates=[];
+    for(const [key,tenant]of [['callerQuota',false],['tenantQuota',true]])if(l[key]){
+      const q=l[key];if(ruleIDs.has(q.ruleId))throw Error('Action limits require distinct rule IDs');ruleIDs.add(q.ruleId);
+      const gate=prepareQuota({...c,accountQuota:{...q,idempotency:false,operationId:undefined,sessionLimit:0,subject:ctx=>subject(ctx,tenant)}});
+      gates.push(async(ctx,signal)=>{const r=await gate(ctx,signal);if(r.check)r.check.id=tenant?'tenant_quota':'caller_quota';return r;});
+    }
+    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})=>{
+      const checks=[{id:'action_boundary',source:'local',mode:'enforce',decision:event.decision,reason:event.reason,duration_ms:0},
+        ...event.checks.map(check=>({id:check.id,source:check.source,mode:check.mode,decision:check.decision,reason:check.reason,duration_ms:check.durationMs}))];
+      const payload={schema:2,request_id:event.eventId,timestamp:event.timestamp,decision:event.decision,reason:event.reason,
+        degraded:event.checks.some(c=>c.decision==='unavailable'),checks,handler_attempted:event.attempted,
+        action:event.decision==='deny'?'denied':event.outcome==='unknown'?'handler_error':'forwarded',
+        tool_action:{action_id:event.actionId,name:event.action,policy_version:event.policyVersion,outcome:event.outcome,...(event.toolSchema?{tool_schema:{server_id:event.toolSchema.serverId,hash:event.toolSchema.hash,...(event.toolSchema.decoy?{decoy:event.toolSchema.decoy}:{}),...(event.toolSchema.effect?{effect:event.toolSchema.effect}:{}),...(event.toolSchema.permissions?{permissions:event.toolSchema.permissions}:{})}}:{}),...(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,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()};
+}