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

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.2`.** 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.
@@ -317,3 +317,14 @@ snapshot, not current quota state.
 
 Only admission is deduplicated. Repeated application/model calls still require
 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 [TypeScript MCP integration](examples/mcp/README.md)
+protects stateless HTTP tool dispatch in a source-only example; an exported MCP
+package entrypoint remains a follow-up. Optional shared quotas, concurrency and hosted
+action events are documented in the action guide and use the hosted AI Protection runtime and dashboard.

package/action-runtime.mjs

@@ -0,0 +1,41 @@
+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'||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
+  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;});
+    }
+    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 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}};
+      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()};
+}

package/actions.d.mts

@@ -0,0 +1,70 @@
+/** Contract supplied by verified server authentication, never parsed from tool arguments. */
+export interface TrustedCaller {
+  readonly schema: 1;
+  readonly subject: string;
+  readonly tenant: string;
+  readonly issuer: string;
+  readonly authenticationMethod: string;
+  /** Unix milliseconds; checked again immediately before execution. */
+  readonly expiresAt: number;
+  readonly scopes: readonly string[];
+  /** OAuth client identity, separate from subject; not an agent signer. */
+  readonly clientId?: string;
+}
+export type ActionInput = null | boolean | number | string | readonly ActionInput[] | {readonly [key:string]: ActionInput};
+export interface ActionContext {
+  readonly caller: TrustedCaller;
+  readonly args: ActionInput;
+  readonly signal?: AbortSignal;
+}
+export interface ActionEvent {
+  readonly schema: 1;
+  readonly eventId: string;
+  readonly timestamp: string;
+  readonly checks: readonly {id:string;source:string;mode:string;decision:string;reason:string;durationMs:number}[];
+  readonly actionId: string;
+  readonly action: string;
+  readonly policyVersion: string;
+  readonly evaluation: 'local';
+  readonly decision: 'allow' | 'deny';
+  readonly reason: string;
+  readonly attempted: boolean;
+  readonly outcome: 'not_attempted' | 'attempted' | 'completed' | 'unknown';
+}
+export interface ActionQuota {ruleId:string;limit:number;windowSeconds:number;mode?:'observe'|'enforce';failureMode?:'open'|'closed';timeoutMs?:number}
+export interface ActionLimits {
+  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 {
+  webdecoyUrl:string;webdecoyKey:string;propertyId:string;subjectSecret:string;
+  reportingTimeoutMs?:number;maxPendingReports?:number;
+}
+export interface ActionDefinition {
+  limits?: ActionLimits;
+  requiredScopes: readonly string[];
+  validate(args: ActionInput): boolean | Promise<boolean>;
+  authorize(context: ActionContext): boolean | Promise<boolean>;
+  /** Additional restrictive policy; cannot override application authorization. */
+  policy?(context: ActionContext): boolean | Promise<boolean>;
+  /** Await all protected work. Do not return a live stream or detached task. */
+  execute(context: ActionContext): unknown | Promise<unknown>;
+}
+export class ActionDenied extends Error {
+  readonly reason: string;
+  readonly status: number;
+  readonly actionId: string;
+  readonly retryAfterSeconds?: number;
+  constructor(reason: string, status: number, actionId: string);
+}
+export function createActionProtection<T>(options: {
+  policyVersion: string;
+  sharedRuntime?: ActionRuntime;
+  /** Bounds local admission checks; shared controls have their own RPC deadlines. Default 1000 ms, max 10000. */
+  admissionTimeoutMs?: number;
+  authenticate(context: T, options: {signal?: AbortSignal}): TrustedCaller | Promise<TrustedCaller>;
+  actions: Record<string, ActionDefinition>;
+  /** Local best-effort observer. sharedRuntime enables independent hosted reporting. */
+  onEvent?(event: ActionEvent): void | Promise<void>;
+}): {flush():Promise<void>;run(action: string, args: ActionInput, authenticationContext: T, options?: {signal?: AbortSignal}): Promise<unknown>};

package/actions.mjs

@@ -0,0 +1,168 @@
+import {randomUUID} from 'node:crypto';
+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 freeze = value => {
+  if (value && typeof value === 'object') { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }
+  return value;
+};
+
+export class ActionDenied extends Error {
+  constructor(reason, status, actionId) {
+    super(reason); this.name = 'ActionDenied'; this.reason = reason; this.status = status; this.actionId = actionId;
+  }
+}
+
+// Authentication is owned by the application's server integration. This validates
+// its contract; it does not verify a bearer token, signer, or model-supplied claim.
+function callerSnapshot(value) {
+  if (!value || value.schema !== 1 || !bounded(value.subject) || !bounded(value.tenant) ||
+      !bounded(value.issuer) || !bounded(value.authenticationMethod) ||
+      !Number.isSafeInteger(value.expiresAt) || value.expiresAt <= Date.now() ||
+      !Array.isArray(value.scopes) || value.scopes.length > 64 || value.scopes.some(s => !bounded(s)) ||
+      (value.clientId !== undefined && !bounded(value.clientId))) throw Error('Invalid authenticated caller');
+  return freeze({schema:1, subject:value.subject, tenant:value.tenant, issuer:value.issuer,
+    authenticationMethod:value.authenticationMethod, expiresAt:value.expiresAt,
+    scopes:[...new Set(value.scopes)], ...(value.clientId === undefined ? {} : {clientId:value.clientId})});
+}
+
+// No accessors, class instances, cycles, non-finite numbers, or unbounded trees.
+// Copy before any await so a caller cannot swap arguments while policy runs.
+function inputSnapshot(input) {
+  let nodes = 0;
+  const seen = new Set();
+  function copy(value, depth) {
+    if (++nodes > 2048 || depth > 12) throw Error('Input too complex');
+    if (value === null || typeof value === 'boolean') return value;
+    if (typeof value === 'string') { if (value.length > 16384) throw Error('Input too large'); return value; }
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (!value || typeof value !== 'object' || seen.has(value) ||
+        (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) throw Error('Invalid JSON input');
+    if (Array.isArray(value) && value.length > 2048) throw Error('Input array too large');
+    const keys = Object.keys(value);
+    if (keys.length > 2048) throw Error('Input too complex');
+    seen.add(value);
+    const out = Array.isArray(value) ? [] : Object.create(null);
+    for (const key of keys) {
+      if (Array.isArray(value) && !/^(0|[1-9][0-9]*)$/.test(key)) throw Error('Invalid array key');
+      const d = Object.getOwnPropertyDescriptor(value, key);
+      if (!d || !('value' in d) || key.length > 512 || ['__proto__','constructor','prototype'].includes(key)) throw Error('Invalid input key');
+      out[key] = copy(d.value, depth + 1);
+    }
+    seen.delete(value);
+    return Object.freeze(out);
+  }
+  const result = copy(input, 0);
+  if (Buffer.byteLength(JSON.stringify(result)) > 16384) throw Error('Input too large');
+  return result;
+}
+
+/** Local protected dispatch. No network calls, cloud override, or automatic retry. */
+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;
+  if (sink !== undefined && typeof sink !== 'function') throw Error('Invalid event sink');
+  const admissionTimeoutMs = options.admissionTimeoutMs ?? 1000;
+  if (!Number.isInteger(admissionTimeoutMs) || admissionTimeoutMs < 1 || admissionTimeoutMs > 10000) throw Error('Invalid admission timeout');
+  const actions = new Map();
+  for (const [name, definition] of Object.entries(options.actions ?? {})) {
+    if (!token.test(name) || !definition || !Array.isArray(definition.requiredScopes) || definition.requiredScopes.length > 64 ||
+        definition.requiredScopes.some(s => !bounded(s)) ||
+        ['validate','authorize','execute'].some(k => typeof definition[k] !== 'function') ||
+        (definition.policy !== undefined && typeof definition.policy !== 'function')) throw Error('Invalid action definition');
+    actions.set(name, Object.freeze({...definition,requiredScopes:Object.freeze([...definition.requiredScopes])}));
+  }
+  if (!actions.size || actions.size > 128) throw Error('Expected 1–128 actions');
+  const runtime=prepareActionRuntime(options,actions);
+  let pendingEvents = 0;
+  return Object.freeze({flush:async()=>{await runtime?.flush();},async run(name, input, authenticationContext, {signal} = {}) {
+    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;
+    const checks=[];
+    const deadline = new AbortController();
+    const admissionSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    const timer = setTimeout(() => deadline.abort(new DOMException('Action admission timed out','TimeoutError')), admissionTimeoutMs);
+    const evaluate = fn => abortable(Promise.resolve().then(() => { admissionSignal.throwIfAborted(); return fn(); }), admissionSignal);
+    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})))});
+      if(runtime)void runtime.report(event);
+      if(!sink||pendingEvents>=100)return;
+      pendingEvents++;
+      Promise.resolve().then(() => sink(event)).catch(() => {}).finally(() => { pendingEvents--; });
+    }
+    function deny(reason, status, retryAfterSeconds) { emit('deny', reason, 'not_attempted'); const e=new ActionDenied(reason,status,actionId);if(retryAfterSeconds)e.retryAfterSeconds=retryAfterSeconds;throw e; }
+    function cancelled() { (attempted ? signal : admissionSignal)?.throwIfAborted(); }
+    try {
+      cancelled();
+      if (!action) deny('action_not_registered',403);
+      let args;
+      try { args = inputSnapshot(input); } catch { deny('invalid_arguments',400); }
+      let caller;
+      try { caller = callerSnapshot(await evaluate(() => authenticate(authenticationContext, {signal:admissionSignal}))); }
+      catch { cancelled(); deny('authentication_required',401); }
+      cancelled();
+      if (action.requiredScopes.some(scope => !caller.scopes.includes(scope))) deny('missing_scope',403);
+      const context = Object.freeze({caller, args, signal:admissionSignal});
+      let valid;
+      try { valid = await evaluate(() => action.validate(args)); } catch { cancelled(); deny('invalid_arguments',400); }
+      cancelled();
+      if (valid !== true) deny('invalid_arguments',400);
+      let authorized;
+      try { authorized = await evaluate(() => action.authorize(context)); } catch { cancelled(); deny('authorization_unavailable',503); }
+      cancelled();
+      if (authorized !== true) deny('permission_denied',403);
+      if (action.policy) {
+        let permitted;
+        try { permitted = await evaluate(() => action.policy(context)); } catch { cancelled(); deny('policy_unavailable',503); }
+        cancelled();
+        if (permitted !== true) deny('policy_denied',403);
+      }
+      // Shared limits run only after application permission checks. Their own
+      // RPC deadlines are separate from local admission and detector availability.
+      clearTimeout(timer);
+      const controls=runtime?.limits.get(name);
+      for(const gate of controls?.gates??[]){
+        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);
+        if(lease.denial)deny(lease.denial.reason,lease.denial.status,lease.denial.retryAfterSeconds);
+        lease.signal.throwIfAborted();
+      }
+      // 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 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){
+        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});}
+      }
+      emit('allow','authorized','completed');
+      return result;
+    } catch (error) {
+      if (!attempted && deadline.signal.aborted && !signal?.aborted) deny('admission_timeout',503);
+      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(()=>{});
+    }
+  }});
+}

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"
   },
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",
@@ -23,6 +23,10 @@
     "./browser": {
       "types": "./browser.d.mts",
       "import": "./browser.mjs"
+    },
+    "./actions": {
+      "types": "./actions.d.mts",
+      "import": "./actions.mjs"
     }
   },
   "files": [
@@ -46,7 +50,10 @@
     "browser-evidence.mjs",
     "usage.mjs",
     "transport.mjs",
-    "NOTICE"
+    "NOTICE",
+    "actions.mjs",
+    "actions.d.mts",
+    "action-runtime.mjs"
   ],
   "description": "Bot and abuse protection for AI-powered applications. Server-side request admission for Node.js.",
   "license": "Apache-2.0",