citadel0 1.0.0 → 1.0.1

package/README.md

@@ -1,124 +1,237 @@
 # Citadel 0
 
-Programmatic security gateway and policy engine for AI agents built on Convex and TypeScript.
+Programmatic security gateway and deterministic policy evaluation engine for AI agents and tool-call pipelines.
 
-Citadel 0 inspects tool calls and actions before execution. It provides deterministic policy evaluation, heuristic threat scanning (prompt injections and secret leaks), and asynchronous human-in-the-loop (HITL) approval queues.
+Citadel 0 intercepts, inspects, and validates AI agent actions and tool arguments before execution. It provides sub-millisecond in-memory rule evaluation, wildcard action matching, nested parameter traversal, risk scoring, automated telemetry batching, and function wrapping.
 
 ---
 
-## Capabilities
+## Highlights
 
-- **Hybrid Evaluation Pipeline**: Evaluates deterministic rules first, followed by heuristic regex threat scanning.
-- **Threat Scanner**: Detects prompt injection patterns, roleplay overrides, model token delimiters, and exposed API/private keys in parameters.
-- **Human-in-the-Loop Reviews**: Pauses execution on `REVIEW` policy verdicts, logging a pending state to Convex and polling until resolved.
-- **Tool Wrappers**: Adapters for wrapping function calls (`wrapTool` and `wrapToolWithReview`).
-- **Audit Logging**: Logs every execution attempt, latency, risk score, and matched policies to Convex.
-- **Dual Bundle**: Ships ESM and CommonJS builds with TypeScript declarations.
+- **Deterministic Evaluation**: Evaluates action payloads locally in-memory with sub-millisecond execution latency.
+- **Zero Runtime Dependencies**: Built with native runtime primitives and `fetch`—no external runtime dependencies required.
+- **Hierarchical Policy Precedence**: Prioritizes policies by numeric priority, short-circuiting on critical block conditions.
+- **Deep Dot-Path Extraction**: Safely traverses nested objects across action parameters, context, and metadata.
+- **Cached Pattern Matching**: Supports wildcard action routing and cached regular expression condition evaluations.
+- **Background Telemetry**: Non-blocking, auto-batching telemetry queue with Node.js unreferenced timers that do not hold event loops open.
+- **Dual Bundle**: Ships ESM and CommonJS builds with full TypeScript declarations.
 
 ---
 
 ## Installation
 
-```bash
+~~~bash
 npm install citadel0
-```
+~~~
 
-```bash
+~~~bash
 pnpm add citadel0
-```
+~~~
+
+---
+
+## Core Concepts
+
+### Evaluation Verdicts & Risk Scoring
+
+Every policy evaluation returns a `SecurityVerdict` containing a deterministic decision and calculated risk score:
+
+| Verdict | Risk Level | Score | Description |
+|---|---|---|---|
+| **`ALLOW`** | `LOW` | `5` | Payload passed all policies with zero rule violations. |
+| **`ALLOW`** | `MEDIUM` | `25` | Payload passed evaluation with non-blocking informational rule matches. |
+| **`REVIEW`** | `HIGH` | `65` | Action flagged for operator sign-off; halted before execution. |
+| **`BLOCK`** | `CRITICAL` | `95` | Disallowed execution signature detected; rejected immediately. |
+
+### Supported Condition Operators
+
+Rules can be configured with the following condition operators against any dotted field path:
+
+- `EQUALS` / `NOT_EQUALS`: Strict equality checks.
+- `GREATER_THAN` / `LESS_THAN`: Numeric threshold comparisons.
+- `IN` / `NOT_IN`: Array inclusion checks.
+- `CONTAINS`: Substring matching for strings, element inclusion for arrays.
+- `REGEX_MATCH`: Regular expression pattern matching with compiled regex caching.
 
 ---
 
 ## Usage
 
-### Client Initialization
+### 1. Wrapping Tool Functions (Recommended)
+
+Use `guardTool` to wrap execution functions. If a policy blocks the action or flags it for review, an error is thrown before your function is invoked:
 
-```typescript
-import { CitadelClient } from 'citadel0';
+~~~typescript
+import { Citadel_0, guardTool } from 'citadel0';
 
-const citadel = new CitadelClient({
-  baseUrl: '[https://energetic-starfish-637.convex.site](https://energetic-starfish-637.convex.site)',
-  agentToken: process.env.CITADEL_AGENT_TOKEN!,
+const citadel0 = new Citadel_0({
+  baseUrl: 'https://api.example.com',
+  agentToken: process.env.CITADEL0_AGENT_TOKEN!,
 });
-```
 
-### Action Check
+// Synchronize remote policies from gateway
+await citadel0.syncPolicies();
 
-```typescript
-const verdict = await citadel.check('web.search', {
-  query: 'Convex database tutorial',
-});
+const executeBash = guardTool(
+  citadel0,
+  'bash.exec',
+  async (args: { command: string }) => {
+    return runSystemProcess(args.command);
+  }
+);
 
-if (verdict.verdict.decision === 'ALLOW') {
-  await runSearch();
-}
-```
+// Runs normally if allowed; throws Error if BLOCK or REVIEW
+await executeBash({ command: 'ls -la' });
+~~~
 
-### Direct Tool Guard
+### 2. Standalone / Offline Evaluation
 
-```typescript
-import { CitadelClient, wrapTool } from 'citadel0';
+Initialize `Citadel_0` with local static policies without requiring network access:
 
-const citadel = new CitadelClient({
-  baseUrl: '[https://energetic-starfish-637.convex.site](https://energetic-starfish-637.convex.site)',
-  agentToken: process.env.CITADEL_AGENT_TOKEN!,
-});
+~~~typescript
+import { Citadel_0, SecurityPolicy } from 'citadel0';
 
-const executeCommand = wrapTool(citadel, {
-  name: 'system.bash',
-  execute: async (args: { command: string }) => {
-    return runCommand(args.command);
+const policies: SecurityPolicy[] = [
+  {
+    id: 'pol_block_destructive_bash',
+    name: 'Block Destructive Commands',
+    actionPattern: 'bash.*',
+    effect: 'BLOCK',
+    priority: 100,
+    isActive: true,
+    rules: [
+      {
+        field: 'params.command',
+        operator: 'REGEX_MATCH',
+        value: 'rm -rf|mkfs|dd|chmod 777',
+      },
+    ],
+  },
+  {
+    id: 'pol_review_high_spend',
+    name: 'Review Large Transactions',
+    actionPattern: 'stripe.transfer',
+    effect: 'REVIEW',
+    priority: 50,
+    isActive: true,
+    rules: [
+      {
+        field: 'params.amount',
+        operator: 'GREATER_THAN',
+        value: 1000,
+      },
+    ],
   },
+];
+
+const citadel0 = new Citadel_0({
+  baseUrl: 'https://api.example.com',
+  agentToken: 'c0_live_token',
+  policies,
 });
 
-const output = await executeCommand.execute({ command: 'ls -la' });
-```
+const verdict = citadel0.check('bash.exec', {
+  command: 'rm -rf /',
+});
 
-### Human-in-the-Loop (HITL) Review
+console.log(verdict.decision);  // 'BLOCK'
+console.log(verdict.riskScore); // 95
+console.log(verdict.reason);    // 'Blocked by policy: Block Destructive Commands'
+~~~
 
-```typescript
-import { CitadelClient, wrapToolWithReview } from 'citadel0';
+### 3. Context & Session Metadata
 
-const citadel = new CitadelClient({
-  baseUrl: '[https://energetic-starfish-637.convex.site](https://energetic-starfish-637.convex.site)',
-  agentToken: process.env.CITADEL_AGENT_TOKEN!,
-});
+Attach session IDs, runtime environment overrides, and custom metadata for policy inspection:
 
-const transferFunds = wrapToolWithReview(
-  citadel,
+~~~typescript
+const verdict = citadel0.check(
+  'db.drop_collection',
+  { collection: 'customers' },
   {
-    name: 'finance.transfer',
-    execute: async (args: { recipient: string; amount: number }) => {
-      return transfer(args.recipient, args.amount);
-    },
-  },
-  {
-    timeoutMs: 60000,
-    pollIntervalMs: 2000,
-    onReviewPending: (auditLogId) => {
-      console.log(`Pending approval: ${auditLogId}`);
-    },
+    sessionId: 'sess_user_981',
+    environment: 'production',
+    metadata: { initiatorRole: 'support_agent' },
   }
 );
+~~~
+
+### 4. Direct Engine Evaluation
 
-await transferFunds.execute({ recipient: 'alice@example.com', amount: 5000 });
-```
+Invoke the evaluation engine directly as a pure function:
+
+~~~typescript
+import { evaluatePolicies, ActionPayload, SecurityPolicy } from 'citadel0';
+
+const payload: ActionPayload = {
+  action: 'file.delete',
+  params: { path: '/etc/hosts' },
+};
+
+const verdict = evaluatePolicies(payload, policies);
+~~~
 
 ---
 
 ## API Reference
 
-### `CitadelClient`
+### `Citadel_0`
+
+#### Configuration (`Citadel_0_Config`)
 
-- `citadel.check(action, params, options)`: Evaluates policies against the gateway and returns `SecurityVerdict`.
-- `citadel.isAllowed(action, params, options)`: Returns boolean indicating if decision equals `ALLOW`.
-- `citadel.guard(action, params, callback, options)`: Runs callback if allowed; throws error if blocked or requiring review.
-- `citadel.guardWithReview(action, params, callback, options)`: Runs callback if allowed. If flagged for review, polls until approved or timed out.
-- `citadel.getReviewStatus(auditLogId)`: Checks resolution status of an audit log.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `baseUrl` | `string` | *required* | Base URL of the gateway endpoint. |
+| `agentToken` | `string` | *required* | Authentication Bearer token. |
+| `environment` | `'production' \| 'staging' \| 'development'` | `'production'` | Runtime environment tag. |
+| `defaultSessionId` | `string` | `undefined` | Fallback session identifier for actions. |
+| `policies` | `SecurityPolicy[]` | `[]` | In-memory initial policies list. |
+| `flushIntervalMs` | `number` | `3000` | Background telemetry flush interval. |
+| `batchSize` | `number` | `50` | Maximum queue length before auto-flush. |
+
+#### Methods
+
+- `check(action, params?, options?)`: Evaluates policies against the action payload, enqueues telemetry, and returns a `SecurityVerdict`.
+- `isAllowed(action, params?, options?)`: Returns `true` if evaluation decision equals `ALLOW`.
+- `guard(action, params, callback, options?)`: Executes `callback` if allowed; throws an error if blocked or flagged for review.
+- `setPolicies(policies)`: Sets and re-sorts local policies by priority descending.
+- `syncPolicies()`: Fetches active policies from `GET /api/v1/policies`. Supports both raw arrays and wrapped response objects.
+- `flush()`: Flushes batched telemetry traces to `POST /api/v1/telemetry`.
+- `destroy()`: Clears the background timer and executes a final telemetry flush.
+
+### Options & Verdict Types
+
+#### `CheckOptions`
+
+~~~typescript
+interface CheckOptions {
+  sessionId?: string;
+  environment?: 'production' | 'staging' | 'development';
+  metadata?: Record<string, unknown>;
+}
+~~~
+
+#### `SecurityVerdict`
+
+~~~typescript
+interface SecurityVerdict {
+  verdictId: string;
+  decision: 'ALLOW' | 'BLOCK' | 'REVIEW';
+  reason: string;
+  riskScore: number;
+  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  latencyMs: number;
+  matchedPolicies: Array<{
+    policyId: string;
+    policyName: string;
+    matched: boolean;
+    effect: 'ALLOW' | 'BLOCK' | 'REVIEW';
+  }>;
+  executedAt: number;
+}
+~~~
+
+---
 
-### Utilities
+## License
 
-- `wrapTool(client, toolDefinition)`: Guards an execution function with deterministic and semantic policy checks.
-- `wrapToolWithReview(client, toolDefinition, options)`: Guards an execution function with review polling.
-- `scanPayloadSemantics(params)`: Runs offline heuristic threat scanning against input parameters.
-- `evaluatePolicies(payload, policies)`: Runs local deterministic and semantic engine directly.
+MIT