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

package/README.md

@@ -334,3 +334,29 @@ action events are documented in the action guide and use the hosted AI Protectio
 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/action-runtime.mjs

@@ -11,7 +11,8 @@ export function prepareActionRuntime(options, definitions) {
   if(!['https:','http:'].includes(url.protocol)||url.username||url.password||url.pathname!=='/'||url.search||url.hash||
     (url.protocol==='http:'&&!['localhost','127.0.0.1','[::1]'].includes(url.hostname))||!validPropertyID(config.propertyId)||
     typeof config.webdecoyKey!=='string'||!config.webdecoyKey||/[^\x21-\x7e]/.test(config.webdecoyKey)||
-    typeof config.subjectSecret!=='string'||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
+    typeof config.subjectSecret!=='string'||!config.subjectSecret.isWellFormed()||Buffer.byteLength(config.subjectSecret)<32)throw Error('Invalid action runtime');
+  if(config.reportCaller !== undefined && typeof config.reportCaller !== "boolean")throw Error("Invalid caller reporting option");
   const c={...config};const limits=new Map(),ruleIDs=new Set();
   const subject=(ctx,tenant)=>({accountId:tenant?quotaHash(c.subjectSecret,'webdecoy.actions.tenant.v1',ctx.caller.tenant):quotaHash(c.subjectSecret,'webdecoy.actions.caller.v1',ctx.caller.issuer,ctx.caller.tenant,ctx.caller.subject)});
   for(const [name,d] of definitions){
@@ -38,10 +39,10 @@ export function prepareActionRuntime(options, definitions) {
       const payload={schema:2,request_id:event.eventId,timestamp:event.timestamp,decision:event.decision,reason:event.reason,
         degraded:event.checks.some(c=>c.decision==='unavailable'),checks,handler_attempted:event.attempted,
         action:event.decision==='deny'?'denied':event.outcome==='unknown'?'handler_error':'forwarded',
-        tool_action:{action_id:event.actionId,name:event.action,policy_version:event.policyVersion,outcome:event.outcome,...(event.work?{work:event.work}:{})}};
+        tool_action:{action_id:event.actionId,name:event.action,policy_version:event.policyVersion,outcome:event.outcome,...(event.caller?{caller:event.caller}:{}),...(event.work?{work:event.work}:{})}};
       const response=await fetch(new URL('/api/v1/sdk/ai-abuse/reports',url),{method:'POST',redirect:'error',signal,
         headers:{Authorization:`Bearer ${c.webdecoyKey}`,'X-WebDecoy-Property-ID':c.propertyId,'Content-Type':'application/json'},body:JSON.stringify(payload)});
       await response.body?.cancel();if(!response.ok)throw Error('Action reporting unavailable');
     }});
-  return {limits,report:event=>reporter.send(event),flush:()=>reporter.flush()};
+  return {limits,callerEvidence:caller=>c.reportCaller?Object.freeze({schema:1,source:'application_auth',id:quotaHash(c.subjectSecret,'webdecoy.actions.evidence.caller.v1',c.propertyId.toLowerCase(),caller.issuer,caller.tenant,caller.subject)}):undefined,report:event=>reporter.send(event),flush:()=>reporter.flush()};
 }

package/actions.d.mts

@@ -33,6 +33,8 @@ export interface ActionWork {
  measure?(result:unknown,context:ActionContext):number;
 }
 export interface ActionEvent {
+  /** Pseudonymous application-authenticated subject, not WebDecoy-verified agent identity. */
+  readonly caller?: {readonly schema:1;readonly source:'application_auth';readonly id:string};
   readonly work?:ActionWorkEvidence;
   readonly schema: 1;
   readonly eventId: string;
@@ -56,6 +58,8 @@ export interface ActionLimits {
   concurrency?: {ruleId:string;accountLimit:number;featureLimit:number;mode?:'observe'|'enforce';failureMode?:'open'|'closed';ttlSeconds?:number;maxSeconds?:number;timeoutMs?:number};
 }
 export interface ActionRuntime {
+  /** Opt in to scoped caller pseudonyms in reports. Requires a supporting runtime. Default false. */
+  reportCaller?:boolean;
   webdecoyUrl:string;webdecoyKey:string;propertyId:string;subjectSecret:string;
   reportingTimeoutMs?:number;maxPendingReports?:number;
 }

package/actions.mjs

@@ -3,7 +3,7 @@ import {abortable} from './transport.mjs';
 import {prepareActionRuntime} from './action-runtime.mjs';
 
 const token = /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,95}$/;
-const bounded = value => typeof value === 'string' && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
+const bounded = value => typeof value === 'string' && value.isWellFormed() && value.length > 0 && value.length <= 512 && !/[\x00-\x1f\x7f]/.test(value);
 const freeze = value => {
   if (value && typeof value === 'object') { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }
   return value;
@@ -81,7 +81,7 @@ export function createActionProtection(options) {
     const actionId = randomUUID();
     // Unknown caller-controlled action strings are never placed in evidence.
     const action = actions.get(name), eventAction = action ? name : 'unregistered';
-    let attempted = false,completed=false,lease,work;
+    let attempted = false,completed=false,lease,work,callerEvidence;
     const leases=[];
     const checks=[];
     const deadline = new AbortController();
@@ -91,7 +91,7 @@ export function createActionProtection(options) {
     function emit(decision, reason, outcome) {
 
       const event = Object.freeze({schema:1, eventId:randomUUID(), timestamp:new Date().toISOString(), actionId, action:eventAction, policyVersion,
-        evaluation:'local', decision, reason, attempted, outcome,...(work?{work:Object.freeze({...work.evidence})}:{}),checks:Object.freeze(checks.map(c=>Object.freeze({...c})))});
+        ...(callerEvidence?{caller:callerEvidence}:{}),evaluation:'local', decision, reason, attempted, outcome,...(work?{work:Object.freeze({...work.evidence})}:{}),checks:Object.freeze(checks.map(c=>Object.freeze({...c})))});
       if(runtime)void runtime.report(event);
       if(!sink||pendingEvents>=100)return;
       pendingEvents++;
@@ -107,6 +107,7 @@ export function createActionProtection(options) {
       let caller;
       try { caller = callerSnapshot(await evaluate(() => authenticate(authenticationContext, {signal:admissionSignal}))); }
       catch { cancelled(); deny('authentication_required',401); }
+      callerEvidence=runtime?.callerEvidence(caller);
       cancelled();
       if (action.requiredScopes.some(scope => !caller.scopes.includes(scope))) deny('missing_scope',403);
       const context = Object.freeze({caller, args, signal:admissionSignal});

package/package.json

@@ -10,7 +10,7 @@
     "check:package": "node scripts/check-package.mjs",
     "test:types": "tsc --strict --noEmit --module nodenext --target es2022 test/types.mts test/mcp-types.mts"
   },
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "exports": {
     "./fetch": {
       "types": "./fetch.d.mts",