palaryn 0.1.0

package/README.md

@@ -0,0 +1,716 @@
+# Palaryn
+
+**A model-agnostic infrastructure layer that gives AI agents safe, auditable, and cost-controlled access to the outside world.**
+
+---
+
+## Overview
+
+As AI agents increasingly interact with external services -- sending HTTP requests, posting to Slack, committing to Git, querying databases -- the central challenge shifts from model intelligence to **execution control**. Without guardrails, agents can leak secrets, overspend budgets, trigger unintended writes, and leave no trace of what happened. Enterprise procurement teams will not approve agent deployments that lack policy enforcement, cost controls, and auditable logs.
+
+Palaryn solves this by sitting as a single choke point between AI agents and the external world. Every tool call -- whether it targets a SaaS API, a database, a Git provider, Slack, or a headless browser -- is intercepted, evaluated against security policies, checked for sensitive data, metered against budgets, and logged immutably. The gateway is completely model-agnostic: it works with Claude, OpenAI, LangGraph, n8n, or any custom orchestrator. Integration requires nothing more than swapping an endpoint or embedding the SDK.
+
+The product is built around three pillars: **Security and DLP** to prevent data exfiltration and enforce least-privilege access; **Cost and Budget Controls** to stop runaway spending from agent loops and retries; and **Audit and Observability** to provide full traceability, replay capability, and compliance-ready export to SIEM and GRC platforms.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- npm
+
+### Install, Build, and Run
+
+```bash
+# Clone the repository
+git clone <repo-url> && cd palaryn
+
+# Install dependencies
+npm install
+
+# Build the TypeScript project
+npm run build
+
+# Start the gateway
+npm start
+```
+
+The gateway starts on **port 3000** by default. Verify it is running:
+
+```bash
+curl http://localhost:3000/health
+```
+
+### Execute Your First Tool Call
+
+Send a tool call through the gateway using the default API key (`dev-key-001`):
+
+```bash
+curl -X POST http://localhost:3000/v1/tool/execute \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: dev-key-001" \
+  -d '{
+    "tool_call_id": "tc-001",
+    "task_id": "task-001",
+    "actor": { "type": "agent", "id": "agent-1" },
+    "source": { "platform": "custom" },
+    "tool": { "name": "http.request", "capability": "read" },
+    "args": { "method": "GET", "url": "https://httpbin.org/get" }
+  }'
+```
+
+The response includes the policy decision, DLP scan results, budget report, and the tool output -- all in a single `ToolResult` envelope.
+
+---
+
+## Project Structure
+
+```
+/
+├── src/
+│   ├── types/              # Canonical schemas (ToolCall, ToolResult, Policy, Events, Budget, Config)
+│   ├── policy/             # Policy engine (YAML DSL evaluation)
+│   ├── dlp/                # DLP scanner (secrets + PII detection, redaction)
+│   ├── budget/             # Budget manager (per-task/user/org budgets, hard stops)
+│   ├── audit/              # Audit logger (immutable event log, trace reconstruction)
+│   ├── executor/           # HTTP executor (retries, backoff, caching)
+│   ├── approval/           # Approval manager (JWT tokens, time-bound approvals)
+│   ├── server/             # Express gateway server + request orchestration
+│   ├── middleware/         # Auth and validation middleware
+│   ├── config/             # Default configuration + startup validation
+│   └── index.ts            # Package exports
+├── sdk/typescript/         # TypeScript SDK client
+│   └── src/
+│       ├── client.ts       # PalarynClient class with full API coverage
+│       └── index.ts        # SDK exports
+├── policy-packs/           # Pre-built YAML policy configurations
+│   ├── default.yaml        # Default safe (reads allowed, writes need approval)
+│   ├── dev_fast.yaml       # Development (permissive reads + writes)
+│   └── prod_strict.yaml    # Production strict (minimal permissions)
+├── tests/
+│   ├── unit/               # 1551 unit tests across 37 suites
+│   └── integration/        # 123 integration tests (65 run + 58 auto-skip without Redis/Postgres)
+├── examples/               # Usage examples
+├── docs/                   # Product documentation (13 markdown files)
+├── Dockerfile              # Multi-stage production Docker build
+├── docker-compose.yaml     # Docker Compose with dev and prod services
+├── tsconfig.json           # TypeScript configuration
+└── package.json
+```
+
+---
+
+## Development
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `npm install` | Install dependencies |
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm start` | Start the gateway in production mode (requires build) |
+| `npm run dev` | Start the gateway in development mode (ts-node, no build needed) |
+| `npm test` | Run all 1616 tests (40 suites) |
+| `npm run test:unit` | Run 1551 unit tests (37 suites) |
+| `npm run test:integration` | Run 123 integration tests (65 + 58 auto-skip without services) |
+| `npm run lint` | Run ESLint on `src/` and `tests/` |
+| `npm run clean` | Remove `dist/` build output |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `3000` | HTTP server port |
+| `HOST` | `0.0.0.0` | HTTP server bind address |
+| `NODE_ENV` | `development` | Environment (development / production) |
+| `AUTH_ENABLED` | `true` | Enable/disable API key authentication |
+| `POLICY_PACK_PATH` | `./policy-packs/default.yaml` | Path to the active policy pack |
+| `AUDIT_LOG_DIR` | `./logs` | Directory for immutable audit logs |
+| `JWT_SECRET` | -- | Secret for signing approval JWT tokens |
+| `APPROVAL_SECRET` | -- | Secret for signing approval workflow tokens |
+| `REDIS_URL` | -- | Redis connection URL (e.g. `redis://redis:6379`) |
+| `DATABASE_URL` | -- | PostgreSQL connection URL |
+
+### Running in Development
+
+```bash
+# Start with hot-reload via ts-node
+npm run dev
+
+# Run tests in watch mode
+npx jest --watch
+```
+
+---
+
+## Testing
+
+The test suite covers all core components with 1616 tests across 40 suites (unit + integration).
+
+```bash
+# Run everything
+npm test
+
+# Run unit tests only (1551 tests across 37 suites)
+npm run test:unit
+
+# Run integration tests only (123 tests, 65 run + 58 auto-skip without Redis/Postgres)
+npm run test:integration
+
+# Run a specific test file
+npx jest tests/unit/policy.test.ts
+```
+
+Unit test suites cover the policy engine, DLP scanner (regex, TruffleHog, composite backends), budget manager, audit logger, executor registry (HTTP, Slack, no-op), approval manager, rate limiter, all storage backends (memory, PostgreSQL, Redis), Prometheus metrics, OpenTelemetry tracing, JWT/OIDC auth with RBAC, admin dashboard, MCP bridge, anomaly detector, OPA/Rego engine, TypeScript SDK, SaaS routes, and full gateway features. Integration tests exercise the full gateway server end-to-end through the HTTP API, plus Redis/Postgres storage integration tests that auto-skip without running services.
+
+---
+
+## Docker
+
+### Production
+
+Build and run the gateway with the multi-stage Dockerfile (Node.js 20 Alpine, non-root user):
+
+```bash
+# Build and start with Docker Compose
+docker compose up gateway
+
+# Or build the image directly
+docker build -t palaryn .
+docker run -p 3000:3000 palaryn
+```
+
+The production image runs as a non-root `palaryn` user, includes a health check, and ships with the compiled JavaScript and policy packs only (no source or dev dependencies).
+
+### Development
+
+The Compose file includes a `gateway-dev` service that mounts the source directory for live editing:
+
+```bash
+docker compose --profile dev up gateway-dev
+```
+
+### Docker Compose Environment
+
+The `docker-compose.yaml` configures both services with sensible defaults. Policy packs are mounted as a read-only volume so you can edit them on the host and restart the gateway to pick up changes.
+
+```yaml
+# Key environment defaults (override as needed)
+NODE_ENV=production
+PORT=3000
+AUTH_ENABLED=true
+POLICY_PACK_PATH=./policy-packs/default.yaml
+```
+
+---
+
+## SDK
+
+### TypeScript SDK
+
+The TypeScript SDK (`sdk/typescript/`) provides a `PalarynClient` class for programmatic access to the gateway from any Node.js application or agent orchestrator.
+
+```typescript
+import { PalarynClient } from './sdk/typescript/src';
+
+// Set defaults once -- no need to repeat actor/platform on every call
+const client = new PalarynClient({
+  gateway_url: 'http://localhost:3000',
+  api_key: 'dev-key-001',
+  timeout_ms: 30000,
+  defaults: {
+    actor: { type: 'agent', id: 'my-agent' },
+    platform: 'langgraph',
+  },
+});
+
+// Convenience methods use defaults automatically
+const getResult = await client.httpGet('task-001', 'https://httpbin.org/get');
+const postResult = await client.httpPost('task-002', 'https://httpbin.org/post', { key: 'value' });
+
+// Override defaults per-call when needed
+const customResult = await client.httpGet('task-003', 'https://httpbin.org/get',
+  { type: 'user', id: 'admin-1' }, 'custom');
+
+// Execute a full tool call
+const result = await client.executeTool({
+  task_id: 'task-004',
+  actor: { type: 'agent', id: 'my-agent' },
+  source: { platform: 'langgraph' },
+  tool: { name: 'http.request', capability: 'read' },
+  args: { method: 'GET', url: 'https://api.github.com/repos/owner/repo' },
+});
+
+// Approval workflows
+const pending = await client.getPendingApprovals();
+await client.approve(approvalToken, 'approver-1');
+await client.deny(approvalToken, 'approver-1', 'Not authorized');
+
+// Observability
+const trace = await client.getTaskTrace('task-001');
+const policy = await client.getCurrentPolicy();
+```
+
+The client covers all gateway endpoints: `executeTool`, `approve`, `deny`, `getTaskTrace`, `getCurrentPolicy`, `validatePolicy`, `getPendingApprovals`, and `health`.
+
+---
+
+## Policy Packs
+
+Policy packs are YAML files that define security rules, domain allowlists, and approval requirements. Three pre-built packs are included (see [`policy-packs/README.md`](policy-packs/README.md) for a detailed comparison):
+
+| Pack | File | Description |
+|---|---|---|
+| **Default Safe** | `policy-packs/default.yaml` | SSRF protection, reads allowed, writes need approval, deny delete/admin |
+| **Dev Fast** | `policy-packs/dev_fast.yaml` | Permissive reads and writes for development |
+| **Prod Strict** | `policy-packs/prod_strict.yaml` | Minimal permissions for production workloads |
+
+### Example Policy Rule
+
+```yaml
+rules:
+  - name: "Require approval for write operations"
+    description: "All write/delete/admin operations require human approval"
+    effect: REQUIRE_APPROVAL
+    priority: 20
+    conditions:
+      capabilities:
+        - "write"
+        - "delete"
+        - "admin"
+    approval:
+      scope: "team_lead"
+      ttl_seconds: 3600
+      reason: "Write/delete/admin operations require approval"
+```
+
+Set the active policy pack with the `POLICY_PACK_PATH` environment variable or at startup.
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/health` | Health check (status, version, timestamp -- always returns 200) |
+| `GET` | `/ready` | Readiness probe (returns 503 when unhealthy, for K8s) |
+| `GET` | `/metrics` | Prometheus metrics (no auth required) |
+| `POST` | `/v1/tool/execute` | Execute a tool call through the gateway |
+| `POST` | `/v1/tool/approve` | Approve or deny a pending action |
+| `GET` | `/v1/tasks/{task_id}/trace` | Retrieve the full trace for a task |
+| `GET` | `/v1/policies/current` | Get the active policy configuration |
+| `POST` | `/v1/policies/validate` | Validate a policy configuration before deployment |
+| `GET` | `/v1/config/active` | Get active configuration (admin-only, secrets redacted) |
+| `GET` | `/v1/approvals/pending` | List pending approval requests |
+
+All endpoints (except `/health`, `/ready`, `/metrics`) require authentication via the `X-API-Key` header when `AUTH_ENABLED=true`.
+
+### Error Responses
+
+All error responses follow a standardized format with machine-readable error codes and actionable hints:
+
+```json
+{
+  "error": "Rate limit exceeded for actor agent-1",
+  "error_code": "RATE_LIMIT_EXCEEDED",
+  "details": { "retry_after_ms": 5000 },
+  "hint": "Retry after the reset time or increase rate_limit config"
+}
+```
+
+Error codes: `VALIDATION_FAILED`, `AUTH_REQUIRED`, `AUTH_INVALID_KEY`, `AUTH_KEY_EXPIRED`, `AUTH_KEY_REVOKED`, `AUTH_INSUFFICIENT_PERMS`, `RATE_LIMIT_EXCEEDED`, `POLICY_DENIED`, `BUDGET_EXCEEDED`, `APPROVAL_REQUIRED`, `TOOL_EXECUTION_ERROR`, `INTERNAL_ERROR`, `NOT_FOUND`, `REQUEST_TIMEOUT`.
+
+---
+
+## Key Features
+
+### Security & DLP
+
+- **Least-privilege enforcement** -- Tools declare capabilities (read/write/delete/admin); policies gate access by capability level, with write operations requiring approval by default
+- **Destination allowlists** -- Domain-level allowlisting with no wildcards by default; IP literals blocked; optional path-level control
+- **DLP scanning** -- Entropy-based and pattern-based detection of secrets (API keys, JWTs, OAuth tokens) and PII (emails, phone numbers, addresses) in both request arguments and response outputs
+- **Redaction strategies** -- Mask (preserve shape), hash (stable for correlation), drop (remove entirely), or tokenize (replace with placeholders)
+- **Incident handling** -- Severity scoring based on destination, data type, and capability; automatic notifications via Slack or webhook; auto-quarantine of keys on severe exfiltration attempts
+- **Approval workflows** -- Asynchronous, signed, time-bound approvals for risky actions; approver scopes include team lead, security, and admin roles
+- **Compliance posture** -- SOC2-friendly logging, configurable data retention, encryption at rest and in transit
+
+### Cost & Budget Controls
+
+- **Granular budgets** -- Set spending limits per task, per user/agent, per workspace, and per tool type (e.g., higher limits for HTTP, tighter limits for browserless)
+- **Hard stops** -- Maximum steps per task, maximum retries per tool call, and maximum wall-clock time per task
+- **Response caching** -- Optional TTL-based caching of GET responses and deduplication of idempotent calls to reduce costs
+- **Anomaly detection** -- Rolling baselines per workspace and tool; alerts triggered when costs or retry rates exceed configurable thresholds
+- **Cost reporting** -- Dashboards showing top spenders, noisiest tools, and blocked actions; CSV/JSON export for finance teams
+
+### Audit & Observability
+
+- **Append-only event log** -- Immutable storage with optional WORM (Write Once Read Many) support for compliance
+- **Structured event schema** -- Events for every stage: `TOOL_CALL_RECEIVED`, `POLICY_DECIDED`, `DLP_SCANNED`, `BUDGET_CHECKED`, `TOOL_EXECUTED`, `TOOL_RESULT_RETURNED`, `APPROVAL_REQUESTED`, `INCIDENT_RAISED`, and more
+- **Correlation IDs** -- Full traceability via `task_id` and `tool_call_id` across the entire tool call lifecycle
+- **Replayable traces** -- Reconstruct any task timeline; optionally re-run tool calls in a sandbox environment (enterprise feature)
+- **OpenTelemetry integration** -- Spans per tool call; metrics for latency, error rate, block rate, approvals, and cost
+- **SIEM/GRC export** -- Webhook sinks, Splunk/Elastic format templates, and daily digest reports
+
+## Architecture Summary
+
+```
+Agents / Orchestrators
+  (Claude Code, LangGraph, n8n, custom control rooms, vendor platforms)
+            |
+            |  ToolCall: toolName + args + context
+            v
++------------------------------+
+|          Palaryn              |
++------------------------------+
+  |   |     |      |      |
+  |   |     |      |      +--> Audit Store (immutable logs)
+  |   |     |      +---------> Metrics / Tracing (OpenTelemetry)
+  |   |     +----------------> Policy Engine (OPA / custom YAML DSL)
+  |   +----------------------> DLP Engine (PII / secrets detection)
+  +--------------------------> Tool Executors (HTTP, Slack, Git, DB, Browserless)
+            |
+            v
+External World / Internal Services
+  (SaaS APIs, databases, Git providers, Slack/Teams, microservices)
+```
+
+**Core principle: all agent I/O goes through a single choke point.** Even if an agent is highly capable, it never gets direct, unmediated access to external services.
+
+### Runtime Path (per tool call)
+
+1. **Authenticate** the request (API key, JWT, or mTLS)
+2. **Normalize** the ToolCall into a canonical schema
+3. **Evaluate policy** -- allow, deny, transform, or require approval
+4. **Scan for DLP** -- detect secrets and PII in arguments and outputs; apply redaction
+5. **Check budget** -- verify per-task/user/org limits; enforce rate limiting
+6. **Execute** the tool call (with retries and backoff)
+7. **Log** an immutable trace event
+8. **Return** the ToolResult with metadata (cost, policy decision, warnings)
+
+### Design Non-Negotiables
+
+- Deterministic behavior: policy decides, the model cannot override
+- No bypass path
+- Clear audit trail for every action
+- Safe defaults: deny-by-default for unknown tools and domains
+
+## Integration Patterns
+
+Palaryn has a single pipeline (auth → rate limit → policy → DLP → budget → execute → audit) with **4 entry points**. Each environment picks the one that requires the least change.
+
+### Entry Points
+
+| Entry Point | Protocol | Code Change | Best For |
+|---|---|---|---|
+| **Direct API** (`POST /v1/tool/execute`) | HTTP | Minimal — send JSON | Any HTTP-capable system |
+| **SDK** (TypeScript / Python) | HTTP (wrapped) | Import + wrapper | Custom agents, orchestrators |
+| **Forward Proxy** (`:3128`) | `HTTP_PROXY` env var | Zero | Containers, K8s, sandbox |
+| **MCP Bridge** | JSON-RPC over stdio | Zero — config only | Claude Code, Cursor, IDE agents |
+| **MCP HTTP** (`/mcp`) | Streamable HTTP | Zero — URL only | Hosted/remote MCP server |
+
+### Agent Frameworks (LangGraph, CrewAI, custom)
+
+Use the Python or TypeScript SDK as a wrapper around tool calls:
+
+```python
+from palaryn import PalarynClient, Actor
+
+palaryn = PalarynClient(
+    gateway_url="http://palaryn:3000",
+    api_key="key-001",
+    default_actor=Actor(type="agent", id="research-agent"),
+    default_platform="langgraph",
+)
+
+# Instead of direct requests.get():
+def safe_http_tool(url: str, task_id: str) -> dict:
+    result = palaryn.http_get(task_id, url)
+    if result.status == "blocked":
+        return {"error": result.error}
+    return result.output
+```
+
+### Workflow Engines (n8n, Temporal, Airflow)
+
+**Option A — HTTP Node:** Point the HTTP Request node at `http://palaryn:3000/v1/tool/execute` with a ToolCall JSON body. Route on the `status` field in the response.
+
+**Option B — Forward Proxy:** Set `HTTP_PROXY=http://palaryn:3128` on the workflow container. All outbound HTTP flows through Palaryn automatically — zero workflow changes.
+
+### LLM Gateways (LiteLLM, Portkey)
+
+Palaryn **complements** LLM gateways — it does not replace them:
+
+```
+Agent → LLM Gateway (model routing, token budget) → LLM returns tool_call
+  → Orchestrator catches tool_call → Palaryn (policy, DLP, budget) → External API
+```
+
+- **LLM Gateway** = control over models (routing, cost, rate limiting on tokens)
+- **Palaryn** = control over tools (policy, DLP, budget on real-world actions)
+
+### Mobile & Web Apps (Android, iOS, React, Next.js)
+
+Client apps **never connect to Palaryn directly** — the backend mediates. The Palaryn API key stays server-side.
+
+```
+┌──────────────┐   HTTPS    ┌─────────────────┐  Palaryn SDK  ┌──────────┐     ┌──────────────┐
+│ Mobile / Web │ ────────→  │  Your Backend   │ ────────────→ │ Palaryn  │ ──→ │ External API │
+│ Client       │ ←───────── │  (Node/Kotlin)  │ ←──────────── │          │ ←── │              │
+└──────────────┘            └─────────────────┘               └──────────┘     └──────────────┘
+```
+
+### IDE Agents (Claude Code, Cursor)
+
+Use the MCP Bridge — zero code changes, just configure the MCP server:
+
+```
+┌──────────────┐   stdio JSON-RPC   ┌────────────────┐    ┌──────────────┐
+│  Claude Code │ ──────────────────→ │ MCP Bridge     │ ──→│ External API │
+│  / Cursor    │ ←─────────────────  │ (Palaryn)      │ ←──│              │
+└──────────────┘                     └────────────────┘    └──────────────┘
+```
+
+**Hosted (remote MCP server — no local build required):**
+
+```bash
+claude mcp add palaryn --url https://palaryn.com/mcp
+```
+
+**Local (stdio MCP server):**
+
+```bash
+# Build first
+npm run build
+
+# Add as MCP server
+claude mcp add palaryn -- node /absolute/path/to/dist/src/mcp/server.js
+
+# Or with a custom policy pack
+claude mcp add palaryn -e POLICY_PACK_PATH=./policy-packs/prod_strict.yaml -- node /absolute/path/to/dist/src/mcp/server.js
+```
+
+**Project-level config (`.mcp.json` in project root):**
+
+```json
+{
+  "mcpServers": {
+    "palaryn": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["dist/src/mcp/server.js"],
+      "env": {
+        "POLICY_PACK_PATH": "./policy-packs/default.yaml"
+      }
+    }
+  }
+}
+```
+
+**Environment variables for MCP mode:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `PALARYN_MCP_WORKSPACE` | `ws-claude-code` | Workspace ID |
+| `PALARYN_MCP_ACTOR` | `claude-code` | Actor ID |
+| `PALARYN_MCP_PLATFORM` | `claude_code` | Platform identifier |
+| `POLICY_PACK_PATH` | `./policy-packs/default.yaml` | Policy pack to enforce |
+
+Tools exposed: `http_request`, `http_get`, `http_post` — all routed through the full Palaryn pipeline (policy, DLP, budget, rate limiting).
+
+### Kubernetes
+
+Three deployment models:
+
+**Sidecar proxy (per-pod):** One Palaryn container per agent pod. Agent sets `HTTP_PROXY=http://localhost:3128`. Implicit auth via `PALARYN_WORKSPACE_ID` / `PALARYN_ACTOR_ID` env vars. Zero code changes.
+
+**Shared gateway (centralized):** One Palaryn instance, multiple agents with separate API keys and workspaces. Agents use the SDK or Direct API.
+
+**Network-enforced:** K8s NetworkPolicy blocks direct egress from agent pods, forcing all traffic through the Palaryn proxy. Agents **cannot** bypass policy enforcement.
+
+```yaml
+# Block direct egress — force proxy
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+spec:
+  podSelector:
+    matchLabels: { role: agent }
+  policyTypes: [Egress]
+  egress:
+    - to:
+        - podSelector:
+            matchLabels: { app: palaryn }
+      ports:
+        - port: 3128
+```
+
+### Quick Reference
+
+| Environment | Method | Code Change |
+|---|---|---|
+| **LangGraph / CrewAI / custom agent** | Python/TS SDK | Minimal — wrapper on tool calls |
+| **n8n / Temporal / Airflow** | HTTP Node → API or `HTTP_PROXY` | Zero (proxy) or URL change (API) |
+| **Claude Code / Cursor** | MCP Bridge | Zero — configure MCP server |
+| **Android / iOS app** | Backend → SDK | Backend mediates |
+| **Web app (React / Next.js)** | API Route → SDK | Backend mediates |
+| **K8s microservices** | Sidecar proxy + NetworkPolicy | Zero — env var + NetworkPolicy |
+| **LLM Gateway (LiteLLM / Portkey)** | SDK in orchestrator | Orchestrator delegates tool calls |
+| **Bare metal / VM** | `HTTP_PROXY` env var | Zero — global env var |
+| **Serverless (Lambda)** | SDK in handler | Minimal — import + wrapper |
+
+### Integration Kit
+
+| Component | Path | Status |
+|---|---|---|
+| TypeScript SDK | `sdk/typescript/` | Implemented |
+| Python SDK | `sdk/python/` | Implemented (sync + async clients, 102 tests) |
+| Policy Packs | `policy-packs/` | Implemented (3 packs: default, dev, prod) |
+| Usage Examples | `examples/` | Implemented |
+| MCP Bridge | `src/mcp/` | Implemented (stdio + HTTP Streamable transport) |
+| n8n Node | `n8n-node/` | Planned |
+
+## Canonical Schemas
+
+### ToolCall
+
+Every tool call is normalized into a canonical format containing:
+
+- **Actor** -- Agent, user, or system identity with display name
+- **Source** -- Platform identifier (e.g., `langgraph`, `claude_code`, `n8n`, `custom`) and session ID
+- **Tool** -- Name, version, and capability level (`read`, `write`, `delete`, `admin`)
+- **Args** -- Tool-specific arguments (method, URL, headers, body, query, etc.)
+- **Constraints** -- Per-call cost limit and timeout
+- **Context** -- Purpose description and classification labels
+
+### ToolResult
+
+Every response includes:
+
+- **Policy decision** -- Allow/deny/transform/require_approval with the matched rule ID and reasons
+- **DLP report** -- Detected items, redactions applied, and severity
+- **Budget report** -- Estimated cost, spent-to-date for the task, and remaining budget
+- **Output** -- The actual tool response (with redactions applied)
+- **Timing** -- Start timestamp and duration in milliseconds
+
+### Authentication
+
+- **API keys** for quick-start and development
+- **mTLS + JWT** for enterprise deployments
+- **Per-workspace keys** with scoped permissions
+- **Idempotency** via required `tool_call_id` (UUID) for safe retry deduplication
+
+## Deployment
+
+### Tech Stack
+
+| Layer | Technology |
+|---|---|
+| **Gateway** | Node.js / TypeScript with Express 5 |
+| **Policy DSL** | YAML with JSON Schema validation + OPA/Rego engine (remote + local eval) |
+| **Immutable logs** | File-based append-only log + in-memory event store for trace queries |
+| **Storage** | In-memory (dev), PostgreSQL (production), Redis (rate limiting + caching) |
+| **Auth** | API keys + JWT/OIDC + RBAC with role-based permissions |
+| **Observability** | OpenTelemetry tracing (OTLP HTTP exporter) + Prometheus metrics (9 metric types) |
+| **Anomaly detection** | Rolling baseline statistics with z-score anomaly flagging |
+| **MCP** | JSON-RPC 2.0 over stdio bridge + HTTP Streamable transport (`/mcp`) |
+| **SDKs** | TypeScript SDK + Python SDK (sync + async) |
+| **Deployment** | Docker / Docker Compose (Gateway + Redis + Postgres + Jaeger) |
+
+### Deployment Models
+
+**SaaS (Multi-Tenant)**
+- Kubernetes-based with per-tenant keys and logical isolation
+- Optional dedicated clusters for large customers
+
+**Enterprise (Single-Tenant)**
+- Helm chart deployment
+- Bring-your-own storage (PostgreSQL, S3)
+- Private networking with mTLS
+
+### Security Hardening
+
+- Encryption at rest via KMS
+- mTLS for all executor communication
+- Secret-less deployments using OIDC federation to cloud providers
+- WAF and rate limiting at the edge
+- Configurable data retention policies
+- Non-root Docker container with minimal Alpine image
+
+### SLOs
+
+- **Latency overhead**: p95 < 50 ms for policy + DLP evaluation (excluding downstream tool latency)
+- **Availability**: 99.9%+
+
+### Rollout Strategy
+
+1. **Shadow mode** -- Log-only with no blocking for the first week
+2. **Enforce mode** -- Start by denying only high-risk actions
+3. **Full mode** -- Enable approvals, budgets, and transformations
+
+## Pricing Tiers
+
+| | Free / Dev | Pro | Business | Enterprise |
+|---|---|---|---|---|
+| **Tool calls / month** | 50,000 | 1,000,000 | 10,000,000 | Unlimited / negotiated |
+| **Log retention** | 7 days | 30 days | 180 days | Custom + WORM |
+| **Security** | Basic allowlists + secrets scan | Approvals + budgets + basic anomaly | SIEM export + SSO (SAML/OIDC) + policy packs | Custom policy engine (OPA) + private deployment |
+| **Support** | Community | Standard | Priority | Dedicated + SLAs |
+| **Price** | Free | $99 -- $299 / mo | $999 -- $2,999 / mo | $25,000+ / year |
+
+### Add-ons
+
+- ClickHouse analytics for high-volume event querying
+- Sandbox replay runner for post-incident investigation
+- Advanced DLP with NER and custom dictionaries
+- Browserless executor for headless browser automation
+
+Pricing is usage-based (per tool call) rather than seat-based, directly mapping to the real work agents perform.
+
+## Roadmap Highlights
+
+### MVP (2-3 weeks)
+
+- HTTP executor with domain allowlists and secrets detection
+- Structured audit log with immutable storage
+- Task and workspace budgets
+- Simple web-based approval workflow
+- MCP router and SDK adapters
+
+### v1 (6-8 weeks)
+
+- PII detection with configurable redaction strategies
+- SIEM export (Splunk, Elastic)
+- Cost and governance dashboard (top spenders, blocked actions)
+- Pre-built policy packs for dev, prod, and ads workflows
+
+### v2 (3-6 months)
+
+- Anomaly detection v2 with advanced baselines
+- Replay sandbox for post-mortem analysis
+- Additional executors: Git, read-only database, browserless
+- Policy simulator with diff and dry-run capabilities
+
+## Documentation
+
+The full product documentation is available in the [`docs/`](docs/) directory:
+
+| Document | Description |
+|---|---|
+| [00_overview.md](docs/00_overview.md) | Product overview, value proposition, and adoption modes |
+| [01_market_problem.md](docs/01_market_problem.md) | Market problem analysis and target buyers |
+| [02_architecture.md](docs/02_architecture.md) | System architecture, runtime path, and deployment model |
+| [03_core_components.md](docs/03_core_components.md) | Core components: Policy Engine, DLP, Budgeting, Executors, Audit |
+| [04_api_contracts.md](docs/04_api_contracts.md) | Canonical ToolCall/ToolResult schemas and API endpoints |
+| [05_policy_engine.md](docs/05_policy_engine.md) | Policy engine design, decision model, and rule examples |
+| [06_security_dlp.md](docs/06_security_dlp.md) | Security threat model, DLP scanning, redaction, and compliance |
+| [07_cost_budgeting.md](docs/07_cost_budgeting.md) | Cost tracking, budgets, hard stops, and anomaly detection |
+| [08_audit_observability.md](docs/08_audit_observability.md) | Audit log schema, OpenTelemetry, replay, and SIEM export |
+| [09_adapters_integrations.md](docs/09_adapters_integrations.md) | Adapter types and integration kit deliverables |
+| [10_deployment_prod.md](docs/10_deployment_prod.md) | Tech stack, deployment models, security hardening, and SLOs |
+| [11_pricing_packaging.md](docs/11_pricing_packaging.md) | Pricing tiers, add-ons, and packaging strategy |
+| [12_roadmap_gtm.md](docs/12_roadmap_gtm.md) | Roadmap (MVP through v2), GTM strategy, and positioning |
+
+---
+
+*"Your agents can use tools. Safely."*