@webdecoy/ai-protection 0.1.0-alpha.1

package/quota.mjs

@@ -0,0 +1,78 @@
+import {createHmac,randomUUID} from 'node:crypto';
+export function createQuotaOperationId() { return `${Math.floor(Date.now()/1000)}.${randomUUID()}`; }
+const operationPattern=/^[1-9][0-9]{9}\.[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const code = /^[a-z][a-z0-9_]{0,63}$/;
+export function quotaHash(secret, ...parts) {
+  const h = createHmac('sha256', secret);
+  for (const part of parts) {
+    const bytes = Buffer.from(part, 'utf8');
+    const length = Buffer.alloc(4); length.writeUInt32BE(bytes.length);
+    h.update(length); h.update(bytes);
+  }
+  return h.digest('hex');
+}
+export function prepareQuota(options) {
+  if (options.accountQuota === undefined) return async () => ({});
+  const {webdecoyUrl,webdecoyKey,propertyId}=options;
+  const q = {mode:'observe',failureMode:'open',timeoutMs:1000,sessionLimit:0,idempotency:false,
+    subjectSecret:options.subjectSecret,...options.accountQuota};
+  if (typeof q.idempotency!=='boolean' || (q.operationId!==undefined&&(!q.idempotency||typeof q.operationId!=='function')) || !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.limit) || q.limit<1 || q.limit>1000000 ||
+      !Number.isInteger(q.windowSeconds) || q.windowSeconds<1 || q.windowSeconds>86400 ||
+      !Number.isInteger(q.sessionLimit) || q.sessionLimit<0 || q.sessionLimit>q.limit ||
+      !Number.isInteger(q.timeoutMs) || q.timeoutMs<1 || q.timeoutMs>10000) throw Error('Invalid account quota configuration');
+  return async (context, signal) => {
+    signal.throwIfAborted(); const started=performance.now();
+    const check={id:'account_quota',source:'shared',mode:q.mode,decision:'unavailable',reason:'account_quota_unavailable',durationMs:0};
+    let denial;
+    try {
+      const subject=q.subject(context);
+      if (subject && typeof subject.then==='function') {Promise.resolve(subject).catch(()=>{});throw Error('Async subject');}
+      const valid=value=>typeof value==='string'&&value.length>0&&value.isWellFormed()&&Buffer.byteLength(value)<=256;
+      if (!valid(subject?.accountId) || (subject.sessionId!==undefined&&subject.sessionId!==''&&!valid(subject.sessionId)) || (q.sessionLimit>0&&!valid(subject.sessionId))) throw Error('Invalid subject');
+      const parts=['webdecoy.account-quota.v1',propertyId.toLowerCase(),q.ruleId];
+      let operationId;
+      if(q.idempotency){
+        operationId=q.operationId?q.operationId(context):createQuotaOperationId();
+        if(operationId&&typeof operationId.then==='function'){Promise.resolve(operationId).catch(()=>{});throw Error('Async operation ID');}
+        if(typeof operationId!=='string'||!operationPattern.test(operationId))throw Error('Invalid operation ID');
+        check.operationId=operationId;
+      }
+      const payload={schema:q.idempotency?2:1,...(operationId?{operation_id:operationId}:{}),rule_id:q.ruleId,subject:quotaHash(q.subjectSecret,...parts,'account',subject.accountId),
+        limit:q.limit,window_seconds:q.windowSeconds,session_limit:q.sessionLimit};
+      if(q.sessionLimit>0)payload.session=quotaHash(q.subjectSecret,...parts,'session',subject.accountId,subject.sessionId);
+      let result;
+      for(let attempt=0;attempt<(q.idempotency?2:1);attempt++){
+       signal.throwIfAborted();
+       try {
+      const response=await fetch(new URL('/api/v1/sdk/ai-abuse/quota',webdecoyUrl),{
+        method:'POST',redirect:'error',signal:AbortSignal.any([signal,AbortSignal.timeout(q.timeoutMs)]),
+        headers:{Authorization:`Bearer ${webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':propertyId},body:JSON.stringify(payload)
+      });
+      if(!response.ok){await response.body?.cancel();const error=Error('Quota unavailable');error.terminal=response.status<500;throw error;}
+      const reader=response.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 quota response');chunks.push(value);}}
+      finally {await reader.cancel().catch(()=>{});reader.releaseLock();}
+      result=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      if(result?.schema!==(q.idempotency?2:1)||(q.idempotency&&result.operation_id!==operationId)||typeof result.allowed!=='boolean'||!Number.isInteger(result.remaining)||result.remaining<0||result.remaining>q.limit||
+         !Number.isInteger(result.reset_at)||result.reset_at<=0||!Number.isInteger(result.retry_after_seconds)||
+         (result.allowed&&(result.reason!=='account_quota_allowed'||result.retry_after_seconds!==0))||
+         (!result.allowed&&(result.reason!=='account_quota_exceeded'||result.retry_after_seconds<1||result.retry_after_seconds>q.windowSeconds)))throw Error('Invalid quota response');
+       break;
+       } catch(error) {
+         signal.throwIfAborted();
+         if(q.idempotency&&!error.terminal)check.reason='account_quota_outcome_unknown';
+         if(!q.idempotency||attempt===1||error.terminal)throw error;
+       }
+      }
+      check.decision=result.allowed?'allow':'deny';check.reason=result.reason;
+      if(!result.allowed&&q.mode==='enforce')denial={reason:result.reason,status:429,retryAfterSeconds:result.retry_after_seconds};
+    } catch {
+      if(q.mode==='enforce'&&q.failureMode==='closed')denial={reason:check.reason,status:503};
+    }
+    signal.throwIfAborted();check.durationMs=performance.now()-started;
+    return {check,denial};
+  };
+}

package/reporting.mjs

@@ -0,0 +1,43 @@
+// Best-effort reporting is independent of admission. Sinks must honor the signal
+// and avoid synchronous CPU work. A host lifecycle hook keeps serverless work alive.
+export function createReporter({onObservation = event => console.log(JSON.stringify(event)),
+  waitUntil, reportingTimeoutMs = 1000, maxPendingReports = 100}) {
+  if (typeof onObservation !== 'function' || (waitUntil !== undefined && typeof waitUntil !== 'function'))
+    throw new Error('Invalid reporting hooks');
+  for (const value of [reportingTimeoutMs, maxPendingReports])
+    if (!Number.isSafeInteger(value) || value <= 0) throw new Error('Invalid reporting bounds');
+  if(reportingTimeoutMs>10000||maxPendingReports>10000)throw Error('Reporting bounds exceed maximum');
+  const pending = new Set();
+  return {
+    send(event) {
+      if (pending.size >= maxPendingReports) {
+        console.warn('WebDecoy report dropped: queue full');
+        return Promise.resolve();
+      }
+      const controller = new AbortController();
+      let timer;
+      const timeout = new Promise(resolve => {
+        timer = setTimeout(() => {
+          controller.abort();
+          console.warn('WebDecoy report timed out');
+          resolve();
+        }, reportingTimeoutMs);
+      });
+      const delivery = Promise.resolve().then(() => onObservation(event, {signal:controller.signal})).catch(() => {
+        console.warn('WebDecoy report failed');
+      });
+      const task = Promise.race([delivery, timeout]).finally(() => {
+        clearTimeout(timer);
+        pending.delete(task);
+      });
+      pending.add(task);
+      try {
+        const scheduled = waitUntil?.(task);
+        if (scheduled && typeof scheduled.then === 'function')
+          Promise.resolve(scheduled).catch(() => console.warn('WebDecoy reporting lifecycle hook failed'));
+      } catch { console.warn('WebDecoy reporting lifecycle hook failed'); }
+      return task;
+    },
+    async flush() { await Promise.all([...pending]); }
+  };
+}

package/rules.mjs

@@ -0,0 +1,46 @@
+const code = /^[a-z][a-z0-9_]{0,63}$/;
+export function prepareRules(rules = []) {
+  if (!Array.isArray(rules) || rules.length > 32) throw new Error('rules must be an array of at most 32 rules');
+  const ids = new Set(['webdecoy','account_quota','concurrency','browser_evidence']);
+  return rules.map(rule => {
+    if (!rule || typeof rule.id !== 'string' || !code.test(rule.id) || ids.has(rule.id) || typeof rule.evaluate !== 'function')
+      throw new Error('Local rules require unique stable IDs and evaluate functions');
+    const mode = rule.mode ?? 'observe';
+    const failureMode = rule.failureMode ?? 'closed';
+    if (!['observe','enforce'].includes(mode) || !['open','closed'].includes(failureMode)) throw new Error('Invalid local rule mode');
+    ids.add(rule.id);
+    return {id:rule.id, mode, failureMode, evaluate:rule.evaluate};
+  });
+}
+
+export function evaluateRules(rules, context, signal) {
+  const checks = [];
+  let denial;
+  for (const rule of rules) {
+    signal.throwIfAborted();
+    const started = performance.now();
+    let result;
+    try {
+      const value = rule.evaluate(context);
+      // Local checks are synchronous and deterministic. Never leave a rejected
+      // promise unhandled if an async rule is accidentally supplied.
+      if (value && typeof value.then === 'function') {
+        Promise.resolve(value).catch(() => {});
+        throw new Error('Async local rule');
+      }
+      if (!value || typeof value.allowed !== 'boolean' ||
+          (value.reason !== undefined && (typeof value.reason !== 'string' || !code.test(value.reason))) ||
+          (value.status !== undefined && ![403,429].includes(value.status))) throw new Error('Invalid local rule result');
+      result = {id:rule.id, source:'local', mode:rule.mode, decision:value.allowed ? 'allow' : 'deny',
+        reason:value.reason ?? (value.allowed ? 'rule_allowed' : 'rule_denied')};
+      if (!value.allowed && rule.mode === 'enforce') denial ??= {reason:result.reason,status:value.status ?? 403};
+    } catch {
+      result = {id:rule.id, source:'local', mode:rule.mode, decision:'unavailable', reason:'local_rule_error'};
+      if (rule.mode === 'enforce' && rule.failureMode === 'closed') denial ??= {reason:'local_rule_error',status:503};
+    }
+    result.durationMs = Math.round((performance.now() - started) * 100) / 100;
+    checks.push(result);
+  }
+  signal.throwIfAborted();
+  return {checks, denial};
+}

package/telemetry.mjs

@@ -0,0 +1,21 @@
+// Explicit wire schema. Never serialize the full observation or application context.
+export function createTelemetry({webdecoyUrl, webdecoyKey, propertyId, reportToWebDecoy = true}) {
+  if (typeof reportToWebDecoy !== 'boolean') throw new Error('Invalid reportToWebDecoy');
+  return async (event, {signal}) => {
+    if (!reportToWebDecoy) return;
+    const payload = {schema:1, request_id:event.request_id, timestamp:event.timestamp,
+      decision:event.decision, reason:event.reason, degraded:event.degraded,
+      checks:event.checks.map(check => ({id:check.id,source:check.source,mode:check.mode,
+        decision:check.decision,reason:check.reason,duration_ms:check.durationMs})),
+      handler_attempted:event.handler_attempted,
+      ...(event.handler_status !== undefined ? {handler_status:event.handler_status} : {}),
+      action:event.action};
+    const response = await fetch(new URL('/api/v1/sdk/ai-abuse/reports',webdecoyUrl),{
+      method:'POST',redirect:'error',signal,
+      headers:{Authorization:`Bearer ${webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':propertyId},
+      body:JSON.stringify(payload)
+    });
+    await response.body?.cancel();
+    if (!response.ok) throw new Error('WebDecoy reporting unavailable');
+  };
+}

package/transport.mjs

@@ -0,0 +1,20 @@
+// Bound control-plane responses independently of the customer's model stream.
+export async function readJSON(response, maxBytes = 65536) {
+ const reader=response.body?.getReader();
+ if(!reader)throw Error('Missing WebDecoy response');
+ let size=0;const chunks=[];
+ try {
+  for(;;){const {done,value}=await reader.read();if(done)break;size+=value.length;
+   if(size>maxBytes)throw Error('Oversized WebDecoy response');chunks.push(value);}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+ } finally {await reader.cancel().catch(()=>{});reader.releaseLock();}
+}
+
+// Each waiter owns cancellation, even when an account refresh is shared.
+export async function abortable(promise, signal) {
+ if(signal.aborted){Promise.resolve(promise).catch(()=>{});signal.throwIfAborted();}
+ let listener;
+ const aborted=new Promise((_,reject)=>{listener=()=>reject(signal.reason);signal.addEventListener('abort',listener,{once:true});});
+ try{return await Promise.race([promise,aborted]);}
+ finally{signal.removeEventListener('abort',listener);}
+}

package/usage.mjs

@@ -0,0 +1,17 @@
+import {createReporter} from './reporting.mjs';
+
+// Events are constructed internally from bounded numeric fields, never application
+// context, prompts, responses, provider errors or credentials.
+export function createUsageReporter(options) {
+ if(options.reportToWebDecoy!==undefined&&typeof options.reportToWebDecoy!=='boolean')throw Error('Invalid reportToWebDecoy');
+ return createReporter({...options,onObservation:async(event,{signal})=>{
+  if(options.reportToWebDecoy===false)return;
+  const response=await fetch(new URL('/api/v1/sdk/ai-abuse/usage',options.webdecoyUrl),{
+   method:'POST',redirect:'error',signal,
+   headers:{Authorization:`Bearer ${options.webdecoyKey}`,'Content-Type':'application/json','X-WebDecoy-Property-ID':options.propertyId},
+   body:JSON.stringify(event)
+  });
+  await response.body?.cancel();
+  if(!response.ok)throw Error('Usage reporting unavailable');
+ }});
+}