@webdecoy/ai-protection 0.1.0-alpha.1

package/budget.mjs

@@ -0,0 +1,105 @@
+import {createUsageReporter} from './usage.mjs';
+import {randomUUID} from 'node:crypto';
+import {quotaHash} from './quota.mjs';
+const code=/^[a-z][a-z0-9_]{0,63}$/;
+const uuid=/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const limitNames=['account_tokens','account_micros','tenant_tokens','tenant_micros','feature_tokens','feature_micros'];
+const integer=(v,max)=>Number.isSafeInteger(v)&&v>=0&&v<=max;
+export class BudgetDenied extends Error {
+ constructor(reason,status,retryAfterSeconds=0){super(reason);this.name='BudgetDenied';this.status=status;this.retryAfterSeconds=retryAfterSeconds;}
+}
+// Explicit catalog only. Rates are integer micro-USD per million tokens; never floats.
+export function budgetCost(price,inputTokens,outputTokens){
+ if(!integer(inputTokens,10000000)||!integer(outputTokens,10000000)||!integer(price.inputMicrosPerMillion,1000000000)||!integer(price.outputMicrosPerMillion,1000000000))throw Error('Invalid budget usage or price');
+ const total=BigInt(inputTokens)*BigInt(price.inputMicrosPerMillion)+BigInt(outputTokens)*BigInt(price.outputMicrosPerMillion);
+ return Number((total+999999n)/1000000n);
+}
+export function ollamaBudgetUsage(final){
+ if(final?.done!==true||typeof final.model!=='string'||!integer(final.prompt_eval_count,10000000)||!integer(final.eval_count,10000000))return null;
+ return {provider:'ollama',model:final.model,inputTokens:final.prompt_eval_count,outputTokens:final.eval_count};
+}
+export function createAIBudget(options){
+ const o={mode:'observe',failureMode:'open',timeoutMs:1000,maxRuntimeMs:300000,...options};
+ const url=new URL(o.webdecoyUrl);
+ if((url.protocol!=='https:'&&!(url.protocol==='http:'&&['localhost','127.0.0.1','[::1]'].includes(url.hostname)))||url.username||url.password||url.search||url.hash||url.pathname!=='/'||!uuid.test(o.propertyId??'')||o.propertyId==='00000000-0000-0000-0000-000000000000'||typeof o.webdecoyKey!=='string'||!o.webdecoyKey.trim()||/[\r\n]/.test(o.webdecoyKey)||!code.test(o.ruleId??'')||typeof o.subject!=='function'||typeof o.subjectSecret!=='string'||!o.subjectSecret.isWellFormed()||Buffer.byteLength(o.subjectSecret)<32||!['observe','enforce'].includes(o.mode)||!['open','closed'].includes(o.failureMode)||!integer(o.windowSeconds,86400)||o.windowSeconds<1||!integer(o.timeoutMs,10000)||o.timeoutMs<1||!integer(o.maxRuntimeMs,900000)||o.maxRuntimeMs<1)throw Error('Invalid budget configuration');
+ const limits=Object.fromEntries(limitNames.map(n=>[n,o.limits?.[n]??0]));
+ if(!Object.values(limits).every(v=>integer(v,1e12))||!Object.values(limits).some(v=>v>0))throw Error('Invalid budget limits');
+ const prices=new Map();
+ for(const [id,p] of Object.entries(o.prices??{})){
+  if(!code.test(id)||!code.test(p.provider??'')||typeof p.model!=='string'||!p.model.length||p.model.length>128||!p.model.isWellFormed())throw Error('Invalid budget price');
+  budgetCost(p,0,0);prices.set(id,Object.freeze({...p}));
+ }
+ if(!prices.size||prices.size>64)throw Error('Explicit bounded price catalog required');
+ const reporter=createUsageReporter(o);
+ async function rpc(body,signal){
+  const res=await fetch(new URL('/api/v1/sdk/ai-abuse/budget',url),{method:'POST',redirect:'error',signal:AbortSignal.any([signal,AbortSignal.timeout(o.timeoutMs)]),headers:{Authorization:`Bearer ${o.webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':o.propertyId},body:JSON.stringify(body)});
+  if(!res.ok){await res.body?.cancel();throw Error('Budget unavailable');}
+  const reader=res.body.getReader();const chunks=[];let size=0;
+  try{for(;;){const {done,value}=await reader.read();if(done)break;size+=value.length;if(size>2048)throw Error('Invalid budget response');chunks.push(value);}}finally{await reader.cancel().catch(()=>{});reader.releaseLock();}
+  const r=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if(r?.schema!==1||typeof r.allowed!=='boolean'||typeof r.granted!=='boolean'||typeof r.overrun!=='boolean'||!code.test(r.reason??'')||!integer(r.retry_after_seconds,86400)||(r.granted&&(!uuid.test(r.reservation_id??'')||r.reservation_id==='00000000-0000-0000-0000-000000000000')))throw Error('Invalid budget response');
+  return r;
+ }
+ return Object.freeze({flush:()=>reporter.flush(),async run(context,call,work,callerSignal=new AbortController().signal){
+  callerSignal.throwIfAborted();
+  const price=prices.get(call.priceId);
+  if(!price||!integer(call.maxInputTokens,10000000)||!integer(call.maxOutputTokens,10000000)||call.maxInputTokens+call.maxOutputTokens<1||typeof work!=='function')throw Error('Known price and conservative token bounds required');
+  if(call.requestId!==undefined&&(!uuid.test(call.requestId)||call.requestId==='00000000-0000-0000-0000-000000000000'))throw Error('Invalid requestId');
+  const bound=Object.freeze({provider:price.provider,model:price.model,maxInputTokens:call.maxInputTokens,maxOutputTokens:call.maxOutputTokens});
+  const micros=budgetCost(price,bound.maxInputTokens,bound.maxOutputTokens);
+  let body,grant,started=false,knownUsage;
+  const callId=randomUUID(),requestId=call.requestId,priceId=call.priceId;
+  const emit=(phase,reason)=>reporter.send({schema:1,call_id:callId,phase,timestamp:new Date().toISOString(),
+   ...(requestId?{request_id:requestId}:{}),...(grant?.granted?{reservation_id:grant.reservation_id}:{}),
+   rule_id:o.ruleId,mode:o.mode,reason,started,would_deny:grant?.allowed===false&&grant?.granted===true,
+   price_id:priceId,input_rate:price.inputMicrosPerMillion,output_rate:price.outputMicrosPerMillion,
+   reserved_tokens:bound.maxInputTokens+bound.maxOutputTokens,reserved_micros:micros,
+   ...(knownUsage??{})});
+  try{
+   const s=o.subject(context);
+   if(s&&typeof s.then==='function'){Promise.resolve(s).catch(()=>{});throw Error('Async subject');}
+   for(const id of [s?.accountId,s?.organizationId])if(typeof id!=='string'||!id.isWellFormed()||!id.length||Buffer.byteLength(id)>256)throw Error('Invalid budget subject');
+   body={schema:1,operation:'reserve',rule_id:o.ruleId,mode:o.mode,nonce:callId,subject:quotaHash(o.subjectSecret,'webdecoy.budget.v1',o.propertyId.toLowerCase(),o.ruleId,'account',s.accountId),tenant:quotaHash(o.subjectSecret,'webdecoy.budget.v1',o.propertyId.toLowerCase(),o.ruleId,'tenant',s.organizationId),window_seconds:o.windowSeconds,limits,tokens:bound.maxInputTokens+bound.maxOutputTokens,micros};
+   grant=await rpc(body,callerSignal);
+   if(grant.granted&&(!['budget_allowed','budget_exceeded'].includes(grant.reason)||(o.mode==='enforce'&&!grant.allowed)))throw Error('Invalid budget grant');
+   if(!grant.granted&&!['budget_exceeded','budget_replay'].includes(grant.reason))throw Error('Invalid budget denial');
+  }catch{
+   grant=null;
+   if(callerSignal.aborted){emit('finish','cancelled');callerSignal.throwIfAborted();}
+   if(o.mode==='enforce'&&o.failureMode==='closed'){emit('finish','budget_unavailable');throw new BudgetDenied('budget_unavailable',503);}
+   grant=null;
+  }
+  if(grant&&!grant.granted){emit('finish',grant.reason);throw new BudgetDenied(grant.reason,429,Math.max(1,grant.retry_after_seconds));}
+  const signal=AbortSignal.any([callerSignal,AbortSignal.timeout(o.maxRuntimeMs)]);
+  if(signal.aborted){emit('finish','cancelled');signal.throwIfAborted();}
+  // Provider errors propagate; the conservative reservation stays charged.
+  let result;
+  try {
+   started=true;emit('start','provider_attempt');
+   result=await work({...bound,signal});
+   if(!result||!result.finished||typeof result.finished.then!=='function')throw Error('Provider completion Promise required; reservation retained');
+  }catch(error){emit('finish',signal.aborted?'cancelled':'provider_error');throw error;}
+  const completion=Promise.resolve(result.finished);completion.catch(()=>{});
+  const outcome=(reason,overrun=false)=>({reason,overrun,reserved:!!grant,wouldDeny:grant?.allowed===false});
+  const accounting=(async()=>{
+   let listener;
+   try{
+    if(signal.aborted)return outcome(grant?'budget_usage_unknown':'budget_unavailable');
+    const stopped=new Promise((_,reject)=>{listener=()=>reject(Error('Provider stopped without confirmed usage'));if(signal.aborted)listener();else signal.addEventListener('abort',listener,{once:true});});
+    const usage=await Promise.race([completion,stopped]);
+    if(!usage||usage.provider!==price.provider||usage.model!==price.model||!integer(usage.inputTokens,10000000)||!integer(usage.outputTokens,10000000))return outcome('budget_usage_unknown');
+    const tokens=usage.inputTokens+usage.outputTokens,cost=budgetCost(price,usage.inputTokens,usage.outputTokens);
+    knownUsage={input_tokens:usage.inputTokens,output_tokens:usage.outputTokens,cost_micros:cost};
+    if(!grant)return outcome('budget_unavailable');
+    const overrun=usage.inputTokens>bound.maxInputTokens||usage.outputTokens>bound.maxOutputTokens;
+    const settle={...body,operation:'settle',reservation_id:grant.reservation_id,tokens,micros:cost};delete settle.nonce;
+    try{
+     const r=await rpc(settle,new AbortController().signal);
+     return outcome(r.allowed&&r.reason==='budget_settled'?'budget_settled':'budget_settlement_unavailable',overrun||r.overrun);
+    }catch{return outcome('budget_settlement_unavailable',overrun);}
+   }catch{return outcome(grant?'budget_usage_unknown':'budget_unavailable');}
+   finally{if(listener)signal.removeEventListener('abort',listener);}
+  })().then(async result=>{await emit('finish',result.reason);return result;});
+  return {value:result.value,accounting,callId};
+ }});
+}

package/concurrency.mjs

@@ -0,0 +1,72 @@
+import {randomUUID} from 'node:crypto';
+import {quotaHash} from './quota.mjs';
+const code=/^[a-z][a-z0-9_]{0,63}$/;
+const uuid=/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+export function prepareConcurrency(options){
+ if(options.concurrency===undefined)return null;
+ const {webdecoyUrl,webdecoyKey,propertyId}=options;
+ const q={mode:'observe',failureMode:'open',ttlSeconds:30,maxSeconds:300,timeoutMs:1000,subjectSecret:options.subjectSecret,...options.concurrency};
+ if(!code.test(q.ruleId??'')||typeof q.subject!=='function'||typeof q.subjectSecret!=='string'||!q.subjectSecret.isWellFormed()||Buffer.byteLength(q.subjectSecret)<32||
+ !['observe','enforce'].includes(q.mode)||!['open','closed'].includes(q.failureMode)||
+ !Number.isInteger(q.accountLimit)||q.accountLimit<1||q.accountLimit>1000||!Number.isInteger(q.featureLimit)||q.featureLimit<q.accountLimit||q.featureLimit>10000||
+ !Number.isInteger(q.ttlSeconds)||q.ttlSeconds<6||q.ttlSeconds>120||!Number.isInteger(q.maxSeconds)||q.maxSeconds<q.ttlSeconds||q.maxSeconds>900||
+ !Number.isInteger(q.timeoutMs)||q.timeoutMs<1||q.timeoutMs>q.ttlSeconds*1000/6)throw Error('Invalid concurrency configuration');
+ async function rpc(body,signal){
+  const res=await fetch(new URL('/api/v1/sdk/ai-abuse/concurrency',webdecoyUrl),{method:'POST',redirect:'error',signal:AbortSignal.any([signal,AbortSignal.timeout(q.timeoutMs)]),headers:{Authorization:`Bearer ${webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':propertyId},body:JSON.stringify(body)});
+  if(!res.ok){await res.body?.cancel();throw Error('Concurrency unavailable');}
+  const reader=res.body.getReader();const chunks=[];let size=0;
+  try{for(;;){const {done,value}=await reader.read();if(done)break;size+=value.length;if(size>2048)throw Error('Invalid concurrency response');chunks.push(value);}}finally{await reader.cancel().catch(()=>{});reader.releaseLock();}
+  const r=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if(r?.schema!==1||typeof r.allowed!=='boolean'||typeof r.granted!=='boolean'||!code.test(r.reason??'')||!Number.isInteger(r.retry_after_seconds)||r.retry_after_seconds<0||r.retry_after_seconds>q.maxSeconds||
+   (r.granted&&(!uuid.test(r.lease_id)||r.lease_id==='00000000-0000-0000-0000-000000000000'||!Number.isInteger(r.valid_for_ms)||r.valid_for_ms<=0||r.valid_for_ms>q.ttlSeconds*1000)))throw Error('Invalid concurrency response');
+  return r;
+ }
+ return async (context,callerSignal)=>{
+  callerSignal.throwIfAborted();const began=performance.now();
+  const check={id:'concurrency',source:'shared',mode:q.mode,decision:'unavailable',reason:'concurrency_unavailable',durationMs:0};
+  let body,grant;
+  try{
+   const subject=q.subject(context);
+   if(subject&&typeof subject.then==='function'){Promise.resolve(subject).catch(()=>{});throw Error('Async subject');}
+   if(typeof subject?.accountId!=='string'||!subject.accountId.isWellFormed()||!subject.accountId.length||Buffer.byteLength(subject.accountId)>256)throw Error('Invalid concurrency subject');
+   body={schema:1,operation:'acquire',rule_id:q.ruleId,mode:q.mode,nonce:randomUUID(),subject:quotaHash(q.subjectSecret,'webdecoy.account-quota.v1',propertyId.toLowerCase(),q.ruleId,'account',subject.accountId),account_limit:q.accountLimit,feature_limit:q.featureLimit,ttl_seconds:q.ttlSeconds,max_seconds:q.maxSeconds};
+   grant=await rpc(body,callerSignal);
+   if(grant.granted&&(!['concurrency_allowed','concurrency_exceeded'].includes(grant.reason)||(q.mode==='enforce'&&!grant.allowed)))throw Error('Invalid lease grant');
+   if(!grant.granted&&!['concurrency_exceeded','concurrency_replay'].includes(grant.reason))throw Error('Invalid denial');
+  }catch{
+   callerSignal.throwIfAborted();check.durationMs=performance.now()-began;
+   return {check,signal:callerSignal,finish:async()=>{},...(q.mode==='enforce'&&q.failureMode==='closed'?{denial:{reason:check.reason,status:503}}:{})};
+  }
+  callerSignal.throwIfAborted();check.durationMs=performance.now()-began;check.decision=grant.allowed?'allow':'deny';check.reason=grant.reason;
+  if(!grant.granted)return {check,denial:{reason:grant.reason,status:429,retryAfterSeconds:Math.max(1,grant.retry_after_seconds)}};
+  const controller=new AbortController();const signal=AbortSignal.any([callerSignal,controller.signal]);
+  let deadline=began+grant.valid_for_ms,stopped=false,renewTimer,renewing=Promise.resolve(),finishing;
+  const abort=()=>controller.abort(Error('Concurrency lease lost or expired'));
+  const hardTimer=setTimeout(abort,Math.max(0,began+q.maxSeconds*1000-performance.now()));
+  const owned={...body,lease_id:grant.lease_id};delete owned.nonce;
+  function schedule(){
+   if(stopped||signal.aborted)return;
+   const remaining=deadline-performance.now();if(remaining<=q.timeoutMs){abort();return;}
+   renewTimer=setTimeout(()=>{renewing=renew();},Math.min(q.ttlSeconds*1000/3,remaining/3));
+  }
+  async function renew(){
+   const sent=performance.now();
+   try{
+    const safeWindow=Math.floor(deadline-performance.now()-100);if(safeWindow<=0)throw Error('Expired');
+    const r=await rpc({...owned,operation:'renew'},AbortSignal.any([signal,AbortSignal.timeout(safeWindow)]));
+    if(!r.granted||!r.allowed||r.reason!=='concurrency_renewed'||r.lease_id!==grant.lease_id)throw Error('Lost');
+    deadline=sent+r.valid_for_ms;schedule();
+   }catch{abort();}
+  }
+  signal.addEventListener('abort',()=>{clearTimeout(renewTimer);clearTimeout(hardTimer)},{once:true});
+  schedule();
+  return {check,signal,finish(confirmed){
+   if(finishing)return finishing;
+   finishing=(async()=>{
+    const release=confirmed&&!signal.aborted;stopped=true;clearTimeout(renewTimer);clearTimeout(hardTimer);
+    controller.abort(Error('Protected work ended'));await renewing;
+    if(release){const r=await rpc({...owned,operation:'release'},new AbortController().signal);if(!r.allowed||r.reason!=='concurrency_released')throw Error('Concurrency release unavailable');}
+   })();return finishing;
+  }};
+ };
+}

package/fetch.d.mts

@@ -0,0 +1,140 @@
+export type Mode = 'observe' | 'enforce';
+export interface LocalRule<Context> {
+  /** Stable non-sensitive code: lowercase letter followed by <=63 letters/digits/underscores. */
+  id: string;
+  /** Defaults to observe. Independent of cloud mode/availability and dashboard setting. */
+  mode?: Mode;
+  /** Defaults to closed for an enforced rule error. Does not change detector failure mode. */
+  failureMode?: 'open' | 'closed';
+  /** Synchronous, deterministic. Use authenticated server state; never a client-supplied identity/plan. */
+  evaluate(context: Context): {allowed: boolean; reason?: string; status?: 403 | 429};
+}
+export interface CheckResult {
+  readonly id: string;
+  readonly source: 'local' | 'remote' | 'shared';
+  readonly mode: Mode;
+  readonly decision: 'allow' | 'deny' | 'challenge' | 'unavailable' | 'skipped';
+  readonly reason: string;
+  readonly durationMs: number;
+  /** Local recovery ID for opt-in v2 quota admissions; omitted from central report payload. */
+  readonly operationId?: string;
+}
+export interface ProtectionDecision {
+  readonly id: string;
+  readonly conclusion: 'allow' | 'deny';
+  readonly reason: string;
+  readonly status?: number;
+  readonly retryAfterSeconds?: number;
+  readonly degraded: boolean;
+  readonly checks: readonly CheckResult[];
+}
+export interface ReportOutcome {
+  handlerAttempted?: boolean;
+  status?: number;
+  cancelled?: boolean;
+  handlerError?: boolean;
+}
+export interface AIProtectionOptions<Context = Record<string, unknown>> {
+  webdecoyUrl: string;
+  webdecoyKey: string;
+  propertyId: string;
+  scopeId: string;
+  subjectSecret: string;
+  /** Return only an address vouched for by hosting ingress. Null skips cloud detection. */
+  resolveClientIP(request: Request, runtime: {signal: AbortSignal}): string | null | Promise<string | null>;
+  /** Bounds waiting for the trusted resolver; defaults to 1000ms, maximum 10000. */
+  clientIPTimeoutMs?: number;
+  /** Explicit route template when URL paths contain identifiers. Never derived from browser input. */
+  route?: string;
+  /** Applies to cloud bot detection only. */
+  protectionMode?: Mode;
+  /** Opt-in browser tag evidence. Exact first-party HTTPS origin; no API clients require cookies. */
+  browserEvidenceOrigin?: string;
+  detectorFailureMode?: 'open' | 'closed';
+  detectorTimeoutMs?: number;
+  baselineLimit?: number;
+  baselineWindowMs?: number;
+  concurrency?: {
+    ruleId: string; subjectSecret?: string; accountLimit: number; featureLimit: number;
+    ttlSeconds?: number; maxSeconds?: number; timeoutMs?: number;
+    mode?: Mode; failureMode?: 'open' | 'closed';
+    subject(context: Context): {accountId: string};
+  };
+  rules?: readonly LocalRule<Context>[];
+  /** Shared admission quota. Configure only from trusted server code. */
+  accountQuota?: {
+    ruleId: string;
+    /** Defaults to the existing subjectSecret. Must match across replicas. */
+    subjectSecret?: string;
+    limit: number;
+    windowSeconds: number;
+    /** Optional stricter session cap, always beneath the account cap. */
+    sessionLimit?: number;
+    mode?: Mode;
+    /** Defaults to open; closed is an explicit availability tradeoff. */
+    failureMode?: 'open' | 'closed';
+    /** Per attempt; v2 permits at most two attempts. */
+    timeoutMs?: number;
+    /** Opt-in schema 2; requires a migrated runtime. Never falls back to schema 1. */
+    idempotency?: boolean;
+    /** Stable ID from authenticated server state for recovery of the SAME logical admission. */
+    operationId?(context: Context): string;
+    subject(context: Context): {accountId: string; sessionId?: string};
+  };
+  /** Async best-effort sink. Context/body/raw exceptions are never included by the SDK. */
+  onObservation?(event: Record<string, unknown>, options: {signal: AbortSignal}): void | Promise<void>;
+  /** Use hosting waitUntil or Next.js after(() => task) inside a request scope. */
+  waitUntil?(task: Promise<void>): void;
+  /** Send bounded decision/outcome metadata to WebDecoy. Defaults to true; independent of the local sink. */
+  reportToWebDecoy?: boolean;
+  reportingTimeoutMs?: number;
+  maxPendingReports?: number;
+}
+export interface AIProtection<Context> {
+  (request: Request, handler: () => Response | Promise<Response>, context: Context): Promise<Response>;
+  concurrent(request: Request, handler: (runtime: {signal: AbortSignal}) =>
+    {response: Response; finished: Promise<void>} | Promise<{response: Response; finished: Promise<void>}>, context: Context): Promise<Response>;
+  check(request: Request, context: Context): Promise<ProtectionDecision>;
+  report(decision: ProtectionDecision, outcome?: ReportOutcome): Promise<void>;
+  /** Wait for currently pending reports, bounded by each report's timeout. */
+  flush(): Promise<void>;
+}
+/** Existing two-argument usage remains valid when no typed context is required. */
+export interface ContextOptionalProtection extends AIProtection<Record<string, unknown>> {
+  (request: Request, handler: () => Response | Promise<Response>, context?: Record<string, unknown>): Promise<Response>;
+  check(request: Request, context?: Record<string, unknown>): Promise<ProtectionDecision>;
+}
+export function createAIProtection(options: AIProtectionOptions): ContextOptionalProtection;
+export function createAIProtection<Context>(options: AIProtectionOptions<Context>): AIProtection<Context>;
+
+/** All monetary values use integer micro-USD. Zero limits disable that scope/unit. */
+export interface BudgetLimits {
+ account_tokens?: number; account_micros?: number;
+ tenant_tokens?: number; tenant_micros?: number;
+ feature_tokens?: number; feature_micros?: number;
+}
+export interface BudgetPrice {
+ provider: string; model: string;
+ inputMicrosPerMillion: number; outputMicrosPerMillion: number;
+}
+export interface BudgetUsage {provider:string; model:string; inputTokens:number; outputTokens:number}
+export interface BudgetOutcome {reason:string; overrun:boolean; reserved:boolean; wouldDeny:boolean}
+export interface BudgetOptions<T> {
+ webdecoyUrl:string; webdecoyKey:string; propertyId:string; ruleId:string;
+ subjectSecret:string; windowSeconds:number; limits:BudgetLimits;
+ mode?:Mode; failureMode?:'open'|'closed'; timeoutMs?:number; maxRuntimeMs?:number;
+ reportToWebDecoy?:boolean; waitUntil?:(task:Promise<void>)=>void; reportingTimeoutMs?:number; maxPendingReports?:number;
+ prices:Record<string,BudgetPrice>;
+ subject(context:T):{accountId:string; organizationId:string};
+}
+export interface BudgetCall {requestId?:string; priceId:string; maxInputTokens:number; maxOutputTokens:number}
+export class BudgetDenied extends Error {status:number;retryAfterSeconds:number}
+export function budgetCost(price:BudgetPrice,inputTokens:number,outputTokens:number):number;
+export function ollamaBudgetUsage(final:unknown):BudgetUsage|null;
+export function createAIBudget<T>(options:BudgetOptions<T>):{
+ flush():Promise<void>;
+ run<V>(context:T,call:BudgetCall,work:(runtime:{provider:string;model:string;maxInputTokens:number;maxOutputTokens:number;signal:AbortSignal})=>{value:V;finished:Promise<BudgetUsage|null>}|Promise<{value:V;finished:Promise<BudgetUsage|null>}>,signal?:AbortSignal):Promise<{value:V;accounting:Promise<BudgetOutcome>;callId:string}>;
+};
+
+/** Create on the server and persist if recovery must survive process/request loss. */
+export function createQuotaOperationId(): string;

package/fetch.mjs

@@ -0,0 +1,165 @@
+export {createQuotaOperationId} from './quota.mjs';
+import {abortable} from './transport.mjs';
+import {browserEvidenceCheck} from './browser-evidence.mjs';
+export {createAIBudget, BudgetDenied, budgetCost, ollamaBudgetUsage} from './budget.mjs';
+import { prepareConcurrency } from './concurrency.mjs';
+import { prepareQuota } from './quota.mjs';
+import { isIP } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { createAdmission } from './admission.mjs';
+import { prepareRules, evaluateRules } from './rules.mjs';
+import { createReporter } from './reporting.mjs';
+import { createTelemetry } from './telemetry.mjs';
+
+// Node runtime only. Authentication and input validation belong before this API.
+export function createAIProtection(options) {
+  if (typeof options.resolveClientIP !== 'function') throw new Error('resolveClientIP is required');
+  const clientIPTimeoutMs=options.clientIPTimeoutMs??1000;
+  if(!Number.isInteger(clientIPTimeoutMs)||clientIPTimeoutMs<1||clientIPTimeoutMs>10000)throw Error('Invalid clientIPTimeoutMs');
+  if(options.route!==undefined&&(typeof options.route!=='string'||!options.route.startsWith('/')||options.route.length>512||/[?#\r\n]/.test(options.route)))throw Error('Invalid normalized route');
+  const admission = createAdmission(options);
+  const rules = prepareRules(options.rules);
+  const quota=prepareQuota(options);
+  const concurrency=prepareConcurrency(options);
+  const telemetry = createTelemetry(options);
+  const localSink = options.onObservation ?? (event => console.log(JSON.stringify(event)));
+  const reporter = createReporter({...options, onObservation:async (event, runtime) => {
+    // Start telemetry before handing a separate event copy to the customer's sink.
+    // A sink cannot mutate the wire payload or prevent the other destination running.
+    const deliveries = await Promise.allSettled([
+      telemetry(event, runtime), Promise.resolve().then(() => localSink(structuredClone(event), runtime))
+    ]);
+    if (deliveries.some(result => result.status === 'rejected')) throw new Error('Report delivery failed');
+  }});
+  // Private bookkeeping: no context, Request, body or raw rule errors retained.
+  const observations = new WeakMap();
+  function finish(observation, checks, denial) {
+    const decision = Object.freeze({id:observation.request_id,
+      conclusion:denial ? 'deny' : 'allow', reason:denial?.reason ?? 'allowed',
+      ...(denial ? {status:denial.status,...(denial.retryAfterSeconds ? {retryAfterSeconds:denial.retryAfterSeconds} : {})} : {}),
+      degraded:checks.some(c => c.decision === 'unavailable' || c.reason === 'client_ip_unavailable'),
+      checks:Object.freeze(checks.map(c => Object.freeze(c)))});
+    observations.set(decision, {...observation, handler_attempted:false, decision:decision.conclusion,
+      reason:decision.reason === 'allowed' && observation.reason ? observation.reason : decision.reason,
+      degraded:decision.degraded, checks:decision.checks});
+    return decision;
+  }
+  async function check(request, context = {}) {
+    request.signal.throwIfAborted();
+    // Only caller-supplied SERVER context enters rules. Never infer identity or
+    // account plan from body/header values, and never serialize context remotely.
+    const local = evaluateRules(rules, context, request.signal);
+    const skipped = reason => ({event:'webdecoy_admission_skipped', schema:1,
+      request_id:randomUUID(), property_id:options.propertyId, timestamp:new Date().toISOString(),
+      reason, action:local.denial ? 'denied' : 'forwarded', upstream_attempted:false});
+    if (local.denial) {
+      return finish(skipped('local_denial'), [...local.checks,
+        {id:'webdecoy',source:'remote',mode:options.protectionMode ?? 'enforce',decision:'skipped',reason:'local_denial',durationMs:0}], local.denial);
+    }
+    const shared=await quota(context,request.signal);
+    if(shared.check)local.checks.push(shared.check);
+    if(shared.denial) return finish({...skipped('quota_denial'),action:shared.denial.status===503?'denied_unavailable':'denied'}, [...local.checks,
+      {id:'webdecoy',source:'remote',mode:options.protectionMode ?? 'enforce',decision:'skipped',reason:'quota_denial',durationMs:0}],shared.denial);
+    const resolverController=new AbortController();
+    const resolverSignal=AbortSignal.any([request.signal,resolverController.signal]);
+    const timer=setTimeout(()=>resolverController.abort(),clientIPTimeoutMs);
+    let ip;
+    try {
+      ip=await abortable(Promise.resolve().then(()=>{resolverSignal.throwIfAborted();return options.resolveClientIP(request,{signal:resolverSignal});}),resolverSignal);
+    } catch(error) {
+      request.signal.throwIfAborted();
+      if(!resolverController.signal.aborted)throw error;
+      ip=null; // Resolver timeout is degraded coverage, never an abuse verdict.
+    } finally {clearTimeout(timer);}
+
+    request.signal.throwIfAborted();
+    if (typeof ip !== 'string' || !isIP(ip)) {
+      return finish(skipped('client_ip_unavailable'), [...local.checks,
+        {id:'webdecoy',source:'remote',mode:options.protectionMode ?? 'enforce',decision:'skipped',reason:'client_ip_unavailable',durationMs:0}]);
+    }
+    const result = await admission.check({ip, method:request.method,
+      path:options.route??new URL(request.url).pathname,
+      headers:Object.fromEntries(request.headers), signal:request.signal});
+    const observation = result.observation;
+    const remote = {id:'webdecoy',source:'remote',mode:observation.mode,
+      decision:observation.detector_decision === 'block' ? 'deny' : observation.detector_decision,
+      reason:observation.account_status !== 'verified' ? observation.account_status
+        : observation.detector_decision === 'unavailable' ? 'detector_unavailable' : `detector_${observation.detector_decision}`,
+      durationMs:observation.account_ms + observation.detector_ms};
+    const browserChecks=options.browserEvidenceOrigin?[browserEvidenceCheck(observation.browser_evidence,observation.mode)]:[];
+    const decision = finish(observation, [...local.checks, remote,...browserChecks],
+      result.allowed ? undefined : {reason:result.error,status:result.status});
+    if (request.signal.aborted) {
+      // No usable decision on cancellation; still emit a best-effort outcome.
+      void report(decision, {cancelled:true});
+      request.signal.throwIfAborted();
+    }
+    return decision;
+  }
+  function report(decision, outcome = {}) {
+    const event = observations.get(decision);
+    if (!event) return Promise.resolve(); // Once per decision; foreign decisions cannot inject events.
+    observations.delete(decision);
+    // Explicit fields only. Never spread application objects into telemetry.
+    event.handler_attempted = outcome.handlerAttempted === true;
+    if (Number.isInteger(outcome.status) && outcome.status >= 100 && outcome.status <= 599) event.handler_status = outcome.status;
+    if (outcome.cancelled === true) event.action = 'cancelled';
+    else if (outcome.handlerError === true) event.action = 'handler_error';
+    return reporter.send(event);
+  }
+  async function protect(request, handler, context = {}) {
+    if(concurrency)throw Error("Use protect.concurrent with an explicit completion promise when concurrency is configured");
+    const decision = await check(request, context);
+    const outcome = {handlerAttempted:false};
+    try {
+      request.signal.throwIfAborted();
+      if (decision.conclusion === 'deny') return Response.json({error:decision.reason, request_id:decision.id}, {
+        status:decision.status, headers:{'Cache-Control':'no-store', 'X-WebDecoy-Request-ID':decision.id,...(decision.retryAfterSeconds?{'Retry-After':String(decision.retryAfterSeconds)}:{})}
+      });
+      outcome.handlerAttempted = true;
+      const response = await handler();
+      outcome.status = response.status;
+      return response; // Original response/body: no stream reader or rewriting.
+    } catch (error) {
+      outcome.cancelled = request.signal.aborted;
+      outcome.handlerError = !outcome.cancelled;
+      throw error;
+    } finally { void report(decision, outcome); }
+  }
+  async function untilStopped(value,signal){
+    let stop;
+    const aborted=new Promise((_,reject)=>{stop=()=>reject(signal.reason??Error('Protected work cancelled'));if(signal.aborted)stop();else signal.addEventListener('abort',stop,{once:true});});
+    try{return await Promise.race([Promise.resolve(value),aborted]);}finally{signal.removeEventListener('abort',stop);}
+  }
+  async function concurrent(request,handler,context={}) {
+    if(!concurrency)throw Error('Concurrency configuration required');
+    const admitted=await check(request,context);
+    if(admitted.conclusion==='deny'){
+      void report(admitted,{handlerAttempted:false});
+      return Response.json({error:admitted.reason,request_id:admitted.id},{status:admitted.status,headers:{'Cache-Control':'no-store',...(admitted.retryAfterSeconds?{'Retry-After':String(admitted.retryAfterSeconds)}:{})}});
+    }
+    const lease=await concurrency(context,request.signal);
+    const event=observations.get(admitted);observations.delete(admitted);
+    const decision=finish({...event,action:lease.denial?'denied':'forwarded'},[...admitted.checks,lease.check],lease.denial);
+    if(lease.denial){void report(decision,{handlerAttempted:false});return Response.json({error:decision.reason,request_id:decision.id},{status:decision.status,headers:{'Cache-Control':'no-store',...(decision.retryAfterSeconds?{'Retry-After':String(decision.retryAfterSeconds)}:{})}});}
+    let attempted=false;
+    try {
+      lease.signal.throwIfAborted();attempted=true;
+      const result=await untilStopped(handler({signal:lease.signal}),lease.signal);
+      if(!(result?.response instanceof Response)||!result.finished||typeof result.finished.then!=='function')throw Error('Return {response, finished}: finished must track provider/stream completion');
+      const completion=(async()=>{
+        let completed=false;
+        try{await untilStopped(result.finished,lease.signal);completed=!lease.signal.aborted;}catch{}
+        try{await lease.finish(completed);}catch{completed=false;}
+        await report(decision,{handlerAttempted:true,status:result.response.status,cancelled:request.signal.aborted,handlerError:!completed});
+      })();
+      completion.catch(()=>{});
+      if(options.waitUntil)options.waitUntil(completion);
+      return result.response; // Unchanged stream; app supplies the actual lifecycle.
+    }catch(error){
+      await lease.finish(false).catch(()=>{});
+      void report(decision,{handlerAttempted:attempted,cancelled:request.signal.aborted,handlerError:true});throw error;
+    }
+  }
+  return Object.assign(protect, {check, report, concurrent, flush:reporter.flush});
+}

package/observation.mjs

@@ -0,0 +1,68 @@
+import { createHmac } from 'node:crypto';
+
+// Shadow-only fixed window per IP. Bounded state; saturation is reported as
+// unknown, never as an allow or block. This is not a production rate limiter.
+export function createBaseline({limit, windowMs, maxKeys = 10000}) {
+  const buckets = new Map();
+  let currentWindow;
+  return (key, now = Date.now()) => {
+    const window = Math.floor(now / windowMs);
+    if (window !== currentWindow) { buckets.clear(); currentWindow = window; }
+    if (!buckets.has(key) && buckets.size >= maxKeys) return 'unknown';
+    const count = (buckets.get(key) ?? 0) + 1;
+    buckets.set(key, count);
+    return count > limit ? 'block' : 'allow';
+  };
+}
+
+export function observationSubject(secret, scopeId, ip) {
+  // Rotate daily; never put raw IPs, prompts, user agents or session tokens in logs.
+  return createHmac('sha256', secret).update(`observation:${scopeId}:${new Date().toISOString().slice(0, 10)}:${ip}`).digest('hex');
+}
+
+export function summarize(events, labels) {
+  const byID = new Map();
+  for (const label of labels) {
+    if (!label.request_id || !['legitimate', 'abuse'].includes(label.label) || byID.has(label.request_id)) throw new Error('Invalid or duplicate independent label');
+    byID.set(label.request_id, label.label);
+  }
+  const records = events.filter(e => e.event === 'webdecoy_admission');
+  for (const e of records) {
+    if (typeof e.request_id !== 'string' || !e.request_id ||
+        !['allow','block','challenge','unavailable'].includes(e.detector_decision) ||
+        !['allow','block','unknown'].includes(e.baseline_decision) ||
+        !Number.isFinite(e.detector_ms) || e.detector_ms < 0) throw new Error('Invalid admission event');
+  }
+  const eventIDs = new Set(records.map(e => e.request_id));
+  if (eventIDs.size !== records.length) throw new Error('Duplicate admission events');
+  const matched = records.filter(e => byID.has(e.request_id));
+  const policies = {};
+  for (const policy of ['rate_limit', 'webdecoy', 'combined']) {
+    const counts = {legitimate: 0, false_blocks: 0, abuse: 0, detected_abuse: 0, unknown: 0};
+    for (const e of matched) {
+      const rate = e.baseline_decision === 'unknown' ? null : e.baseline_decision === 'block';
+      // Fail-open policy: unavailable detections do not block. Track them separately.
+      const detected = ['block', 'challenge'].includes(e.detector_decision);
+      const blocked = policy === 'rate_limit' ? rate : policy === 'webdecoy' ? detected : (detected || rate);
+      if (blocked === null) { counts.unknown++; continue; }
+      if (byID.get(e.request_id) === 'legitimate') { counts.legitimate++; if (blocked) counts.false_blocks++; }
+      else { counts.abuse++; if (blocked) counts.detected_abuse++; }
+    }
+    policies[policy] = {...counts,
+      false_block_rate: counts.legitimate ? counts.false_blocks / counts.legitimate : null,
+      abuse_detection_rate: counts.abuse ? counts.detected_abuse / counts.abuse : null};
+  }
+  const latency = records.map(e => e.detector_ms).filter(Number.isFinite).sort((a,b) => a-b);
+  const admissionLatency = records.map(e => e.detector_ms + (e.account_ms ?? 0)).sort((a,b) => a-b);
+  return {requests: records.length, labeled_requests: matched.length,
+    unmatched_labels: [...byID.keys()].filter(id => !eventIDs.has(id)).length,
+    account_unavailable: records.filter(e => e.account_status && e.account_status !== 'verified').length,
+    effective_modes: {observe: records.filter(e => e.mode === 'observe').length, enforce: records.filter(e => e.mode === 'enforce').length},
+    unavailable_checks: records.filter(e => e.detector_decision === 'unavailable').length,
+    admission_p95_ms: admissionLatency.length ? admissionLatency[Math.ceil(admissionLatency.length * .95) - 1] : null,
+    detector_p95_ms: latency.length ? latency[Math.ceil(latency.length * .95) - 1] : null,
+    baseline_unknown: records.filter(e => e.baseline_decision === 'unknown').length,
+    additional_abuse_caught: matched.filter(e => byID.get(e.request_id) === 'abuse' && e.baseline_decision === 'allow' && ['block','challenge'].includes(e.detector_decision)).length,
+    policies, savings: 'Not measured: requires actual model usage and pricing; blocked counts are not dollar savings.',
+    limitations: ['Per-request metrics; labels must be independent of verdicts.', 'Shadow fixed-window per-IP baseline, one gateway process; not application-native controls.', 'No statistical confidence or production accuracy claim from a synthetic sample.']};
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@webdecoy/ai-protection",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm test && npm run test:types && npm run check:package",
+    "check:package": "node scripts/check-package.mjs",
+    "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts"
+  },
+  "version": "0.1.0-alpha.1",
+  "exports": {
+    "./fetch": {
+      "types": "./fetch.d.mts",
+      "import": "./fetch.mjs"
+    },
+    ".": {
+      "types": "./fetch.d.mts",
+      "import": "./fetch.mjs"
+    },
+    "./browser": {
+      "types": "./browser.d.mts",
+      "import": "./browser.mjs"
+    }
+  },
+  "files": [
+    "fetch.mjs",
+    "fetch.d.mts",
+    "admission.mjs",
+    "account.mjs",
+    "observation.mjs",
+    "README.md",
+    "NEXTJS.md",
+    "LICENSE",
+    "rules.mjs",
+    "reporting.mjs",
+    "ARCHITECTURE.md",
+    "telemetry.mjs",
+    "quota.mjs",
+    "concurrency.mjs",
+    "budget.mjs",
+    "browser.mjs",
+    "browser.d.mts",
+    "browser-evidence.mjs",
+    "usage.mjs",
+    "transport.mjs",
+    "RELEASE.md",
+    "NOTICE"
+  ],
+  "description": "Bot and abuse protection for AI-powered applications. Server-side request admission for Node.js.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WebDecoy/ai-protection.git"
+  },
+  "homepage": "https://github.com/WebDecoy/ai-protection#readme",
+  "bugs": {
+    "url": "https://github.com/WebDecoy/ai-protection/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "keywords": [
+    "ai",
+    "security",
+    "bot-protection",
+    "nextjs",
+    "webdecoy"
+  ],
+  "devDependencies": {
+    "typescript": "6.0.3"
+  }
+}