@datacules/agent-identity-anomaly 0.9.0 → 0.11.0

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="../../../assets/logo.svg" alt="Agent Identity — by Datacules LLC" width="360"/>
+</p>
+
 # `@datacules/agent-identity-anomaly`
 
 Behavioral baseline and anomaly detection for [`@datacules/agent-identity`](../../core). Wraps your audit pipeline with zero routing config changes — each agent builds a rolling baseline and deviations trigger `credential.anomaly` audit events.
@@ -11,26 +15,29 @@ npm install @datacules/agent-identity-anomaly
 ## Usage
 
 ```typescript
-import { AnomalyDetector } from '@datacules/agent-identity-anomaly';
-
-const detector = new AnomalyDetector({
-  logger,
-  policy: {
-    lowAction: 'warn',      // emit audit event only
-    mediumAction: 'warn',   // same
-    highAction: 'block',    // return null — credential denied
-    baselineSamples: 20,    // collect 20 resolutions before scoring starts
-    rateSpikeThreshold: 3.0, // flag if current rate > 3x rolling average
-  },
-  onAnomaly: (event) => {
-    alertingService.send(`Anomaly detected: ${event.signal} (${event.severity}) for ${event.userId}`);
-  },
-});
-
-// Wrap your resolveAsync call
-const resolved = await detector.observe(ctx, () => router.resolveAsync(ctx));
+import { withAnomalyDetection } from '@datacules/agent-identity-anomaly';
+import { createRouter } from '@datacules/agent-identity';
+
+const router = withAnomalyDetection(
+  createRouter(credentials, rules, auditLogger),
+  {
+    policies: [
+      { severity: 'low',    action: 'warn' },     // emit credential.anomaly audit event
+      { severity: 'medium', action: 'throttle' }, // rate-limit to 10% of normal
+      { severity: 'high',   action: 'block' },    // return null — deny the resolution
+    ],
+    onAnomaly: (event) => {
+      alertingService.send(
+        `Anomaly: ${event.signal} (${event.severity}) for agent ${event.userId}`
+      );
+    },
+  }
+);
+
+// Use router exactly as before — anomaly detection is transparent
+const resolved = await router.resolveAsync(ctx);
 if (!resolved) {
-  // anomaly detected + policy was 'block' — the model layer should not proceed
+  // null means either no rule matched OR anomaly policy was 'block'
 }
 ```
 
@@ -38,7 +45,7 @@ if (!resolved) {
 
 | Signal | Severity | Description |
 |--------|----------|-------------|
-| `rate_spike` | high | Call rate 3x the hourly EWMA |
+| `rate_spike` | high | Call rate 3× the hourly EWMA |
 | `new_credential_type` | medium | Credential kind never seen before |
 | `new_action_type` | medium | Action (`read`/`write`/etc.) never seen before |
 | `new_resource_kind` | medium | Resource kind (`shared`/`personal`) never seen before |
@@ -47,7 +54,7 @@ if (!resolved) {
 
 ## Audit event format
 
-Every anomaly emits a `credential.anomaly` audit entry with additional fields:
+Every anomaly emits a `credential.anomaly` audit entry:
 
 ```json
 {
@@ -59,3 +66,15 @@ Every anomaly emits a `credential.anomaly` audit entry with additional fields:
   "userId": "agent-orders"
 }
 ```
+
+## Response policies
+
+| Action | Behaviour |
+|--------|-----------|
+| `warn` | Emit `credential.anomaly` audit event; return credential normally |
+| `throttle` | Emit event; allow only 10% of requests through (random sampling) |
+| `block` | Emit event; return `null` so the caller must abort or escalate to human review |
+
+---
+
+Part of the [agent-identity monorepo](https://github.com/hvrcharon1/agent-identity) by [Datacules LLC](https://datacules.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datacules/agent-identity-anomaly",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "private": false,
   "description": "Anomaly detection and behavioral baseline for @datacules/agent-identity — statistical detection of unusual credential usage patterns",
   "author": "Datacules LLC",