agentgate-runtime-control 2.13.8

package/docs/external-security-review-test-pack.md

@@ -0,0 +1,132 @@
+# AgentGate — External Security Review Test Pack
+
+## Status
+
+This is a test package for an **independent reviewer**. It is not an internal audit and must not be described as an external security review until an independent reviewer returns a dated report.
+
+## Evidence baseline
+
+Reviewer should record:
+
+- AgentGate version and SHA-256 of the release ZIP.
+- Node.js version and OS.
+- `npm test` result.
+- `npm audit --omit=dev` result.
+- `node bin/agentgate.js doctor`.
+- `node bin/agentgate.js validate-security`.
+- `node bin/agentgate.js attack-ci`.
+- HTTP Control Plane authentication mode.
+- PostgreSQL version and RLS configuration when persistence is in scope.
+
+## Required security tests
+
+### A. Authentication / Authorization
+
+1. Access every protected Control Plane endpoint without credentials.
+2. Use an invalid API key.
+3. Use a valid key belonging to Tenant A against Tenant B resources.
+4. Attempt approval with a key that cannot approve that tenant/run.
+5. Attempt replay with a key from another tenant.
+6. Verify failures are fail-closed (`401`/`403`) and do not leak data.
+
+Expected: no unauthorized action or cross-tenant data exposure.
+
+### B. Runtime enforcement
+
+Run the built-in Attack Lab and verify:
+
+- Prompt injection → BLOCK, execution 0.
+- Privilege escalation → BLOCK, execution 0.
+- Destructive tool → BLOCK, execution 0.
+- High-value refund → BLOCK, execution 0.
+- Unsafe tool chaining → BLOCK, execution 0.
+
+### C. Approval security
+
+1. Create an ASK request.
+2. Verify execution is 0 before approval.
+3. Approve once and verify exactly one execution.
+4. Replay the same approval request concurrently 10 times.
+5. Verify only one approval wins and only one execution occurs.
+6. Try approval from another tenant.
+
+Expected: one successful resolution, no duplicate execution, no cross-tenant approval.
+
+### D. Egress / secret leakage
+
+Send representative outputs containing:
+
+- `secret`
+- `password`
+- `passphrase`
+- `private_key`
+- `access_token`
+- `refresh_token`
+- `authorization`
+- `client_secret`
+- JWT
+- API keys
+- cloud access keys
+- PEM private keys
+- email and phone PII
+
+Expected: sensitive values are REDACTED or BLOCKED according to policy and never appear in the returned output/audit preview where policy says they must not.
+
+### E. Input robustness
+
+Try malformed JSON, missing fields, wrong types, arrays where objects are expected, extremely long strings, nulls, duplicated fields, unexpected action/tool names, and invalid approval IDs.
+
+Expected: controlled error; no process crash; no bypass to tool execution.
+
+### F. MCP / tool boundary
+
+1. Call an unregistered tool.
+2. Call a registered destructive tool with a policy bypass attempt.
+3. Attempt tool chaining where the second action is privileged.
+4. Attempt to alter tool identity/action through user-controlled arguments.
+
+Expected: authorization is based on trusted runtime context/policy, not merely model-provided text.
+
+### G. Replay / audit integrity
+
+Verify a blocked run contains:
+
+- runId
+- decision
+- tool/action
+- request/arguments as permitted by logging policy
+- winningRule
+- ruleTrace
+- execution outcome
+- approval state when applicable
+
+Attempt to read or modify another tenant's run.
+
+Expected: complete evidence for authorized users and no unauthorized access/modification.
+
+### H. Persistence / PostgreSQL
+
+Use the managed PostgreSQL acceptance pack in `docs/managed-postgres-acceptance-test.md`.
+
+### I. Availability / abuse controls
+
+Test rate limits, oversized requests, repeated authentication failures, approval floods, and run-retention pressure in a production-like environment.
+
+Expected: bounded resource usage, controlled errors, and no security boundary bypass.
+
+## Reviewer report format
+
+The independent reviewer should return:
+
+1. Scope and exclusions.
+2. Environment and versions.
+3. Methodology.
+4. Test cases executed.
+5. Findings with severity (Critical/High/Medium/Low/Informational).
+6. Reproduction steps for each finding.
+7. Evidence.
+8. Remediation status.
+9. Retest results.
+10. Date and reviewer identity/organization.
+
+Only after this report exists should AgentGate state that an external security review was completed.

package/docs/external-security-review.md

@@ -0,0 +1,33 @@
+# External Security Review Package
+
+## Status
+
+**Not completed.** This repository contains a preparation package only. No third-party security audit, penetration test, SOC 2 assessment, or certification is claimed by AgentGate.
+
+## Scope for an external reviewer
+
+1. Runtime policy enforcement and pre-execution boundary.
+2. Approval lifecycle and concurrent approval race.
+3. MCP Gateway and tool registration.
+4. HTTP Control Plane authentication and authorization.
+5. Tenant isolation and replay access control.
+6. Egress inspection/redaction/blocking.
+7. Persistence and Postgres/Supabase RLS assumptions.
+8. Audit integrity and export.
+9. Local/dev authentication boundaries.
+10. Dependency and supply-chain exposure.
+
+## Evidence to provide
+
+- Release ZIP and SHA-256.
+- `npm pack --dry-run` output.
+- Automated test report.
+- Threat model.
+- Production deployment architecture.
+- Database schema/RLS policy.
+- Incident-response runbook.
+- Backup/restore evidence.
+
+## Acceptance
+
+The review is considered complete only when an independent reviewer supplies a dated report with scope, methodology, findings, severity, and remediation status.

package/docs/incident-response.md

@@ -0,0 +1,54 @@
+# Incident Response Runbook
+
+This runbook is an operational template for AgentGate deployments. It does not replace the customer's incident-response policy.
+
+## Severity
+
+### SEV-1
+Confirmed or suspected unauthorized side effect, cross-tenant data exposure, credential compromise, or bypass of an enforced security boundary.
+
+### SEV-2
+Security control degradation without confirmed unauthorized side effect, persistent service failure, or material audit/replay loss.
+
+### SEV-3
+Non-security defect, degraded dashboard, reporting issue, or recoverable integration problem.
+
+## Immediate containment
+
+1. Preserve relevant run IDs, approval IDs, policy versions, timestamps, and request metadata.
+2. Activate the kill switch or move affected tools to Block/Observe as appropriate.
+3. Revoke or rotate compromised credentials.
+4. Isolate the affected tenant/tool/integration.
+5. Preserve database and application logs before cleanup.
+
+## Investigation
+
+Correlate:
+
+```text
+runId
+approvalId
+tenantId
+agent
+policy version
+winningRule
+ruleTrace
+tool/action
+time window
+egress findings
+```
+
+Use Replay and Audit Export before modifying historical records.
+
+## Recovery
+
+1. Patch or roll back the affected runtime/policy.
+2. Re-run the relevant Attack Lab and customer-specific abuse cases.
+3. Verify tenant isolation.
+4. Verify approval single-execution behavior.
+5. Restore from backup if data integrity is affected.
+6. Document the exact recovery point and customer impact.
+
+## Post-incident
+
+Record root cause, affected versions, scope, evidence, containment, customer notification decision, corrective action, and regression tests. Add a regression test for every confirmed bypass or operational failure.

package/docs/integration-matrix.md

@@ -0,0 +1,17 @@
+# Integration Matrix
+
+| Integration | Status | Primary path | Notes |
+|---|---|---|---|
+| Node.js SDK | Supported | `createAgentGate`, `protect`, `createRuntime` | Primary developer experience |
+| TypeScript | Supported via Node API | SDK exports | Types can be layered by the consuming project |
+| MCP | Supported | MCP Gateway | Runtime enforcement + approval |
+| HTTP Control Plane | Supported | `/api/*` | Auth/tenant scoping required in production |
+| PostgreSQL | Supported | `PostgresStoreAdapter` | RLS + tenant scope |
+| Supabase | Supported | `createSupabaseAdapter` | Use RLS and tenant predicates |
+| OpenAI Agents | Integration pattern | Protect the side-effecting tool | No vendor lock-in claim |
+| Anthropic agents | Integration pattern | Protect the side-effecting tool/MCP path | Validate SDK/tool adapter in pilot |
+| LangChain | Integration pattern | Protect the tool boundary | Validate in pilot |
+| Vercel AI | Integration pattern | Protect server-side tool handlers | Do not expose server secrets to browser |
+| Python/.NET/Go | Not first-class SDKs | HTTP/MCP boundary | Use Control Plane/MCP until native SDK exists |
+
+AgentGate should not claim native framework support unless the integration has a maintained example and release test.

package/docs/managed-postgres-acceptance-test.md

@@ -0,0 +1,138 @@
+# AgentGate — Managed PostgreSQL Production Acceptance Test
+
+## Purpose
+
+Run this against a **managed PostgreSQL test/staging database** (for example a managed PostgreSQL provider), not a local developer database. Do not use production customer data for destructive restore testing.
+
+## Preconditions
+
+- PostgreSQL endpoint and database credentials.
+- Application role with only the permissions required by AgentGate.
+- Separate migration/admin role.
+- TLS enabled for database connections.
+- `schema/postgres.sql` applied.
+- RLS enabled and forced on `agentgate_records`.
+- At least two tenants: `tenant-a` and `tenant-b`.
+
+## Test 1 — Schema and RLS
+
+Verify:
+
+```sql
+SELECT relrowsecurity, relforcerowsecurity
+FROM pg_class
+WHERE oid = 'agentgate_records'::regclass;
+```
+
+Expected: both values are `true`.
+
+Verify the policy:
+
+```sql
+SELECT policyname, permissive, roles, cmd
+FROM pg_policies
+WHERE tablename = 'agentgate_records';
+```
+
+Expected: tenant isolation policy exists.
+
+## Test 2 — Tenant A isolation
+
+In an application connection:
+
+```sql
+BEGIN;
+SELECT set_config('agentgate.tenant_id', 'tenant-a', true);
+```
+
+Create/read Tenant A records through `PostgresStoreAdapter`.
+
+Then attempt to read Tenant B by ID/list query.
+
+Expected: zero Tenant B rows.
+
+## Test 3 — Cross-tenant write
+
+With `agentgate.tenant_id = tenant-a`, attempt to insert a row with `tenant_id = tenant-b`.
+
+Expected: PostgreSQL rejects it with an RLS policy violation.
+
+## Test 4 — Backup
+
+Create known test records:
+
+- Tenant A Run: BLOCK, execution 0.
+- Tenant A Approval: pending.
+- Tenant B Run: ASK.
+- Tenant B Approval: approved.
+
+Run a provider-native backup or `pg_dump` where permitted.
+
+Record backup identifier, timestamp, size, and checksum if available.
+
+## Test 5 — Restore drill
+
+Restore into an isolated staging database/clone.
+
+Verify:
+
+- Tenant A Run exists.
+- Tenant A Approval exists.
+- Tenant B Run exists.
+- Tenant B Approval exists.
+- Replay fields survive.
+- `winningRule` survives.
+- `ruleTrace` survives.
+- execution count/state survives.
+- RLS remains enabled and forced.
+- cross-tenant read remains blocked.
+
+## Test 6 — Application role boundaries
+
+Verify the application role cannot:
+
+- `DROP DATABASE`
+- create/drop arbitrary databases
+- become superuser
+- disable RLS
+- alter security policies
+- perform unrestricted cross-tenant reads
+
+Migration/admin credentials must be separate.
+
+## Test 7 — TLS
+
+Verify the application connection uses TLS and certificate verification appropriate to the provider.
+
+Record the provider, TLS mode, and certificate verification configuration.
+
+## Test 8 — Backup recovery objective
+
+Record:
+
+- backup frequency
+- retention
+- last successful backup timestamp
+- restore start/end time
+- RPO achieved
+- RTO achieved
+- whether restore verification is automated
+
+## Acceptance criteria
+
+| Gate | Required result |
+|---|---|
+| RLS enabled | PASS |
+| RLS forced | PASS |
+| Cross-tenant read | 0 rows / denied |
+| Cross-tenant write | denied |
+| Backup | successful |
+| Restore | successful |
+| Runs restored | PASS |
+| Approvals restored | PASS |
+| Replay restored | PASS |
+| Tenant isolation after restore | PASS |
+| App role least privilege | PASS |
+| TLS | PASS |
+
+A single failure in tenant isolation or unauthorized application privilege is a security blocker and should be remediated before production use.

package/docs/marketing-plan.md

@@ -0,0 +1,33 @@
+# AgentGate Marketing Plan — After Design Partner Readiness
+
+## Phase 1 — Evidence
+Secure 3–5 design partners and publish only partner-approved results.
+
+## Phase 2 — Positioning
+Use one category statement:
+
+> AgentGate is the runtime control plane for AI agent actions.
+
+Core promise:
+
+> Stop dangerous agent actions before they execute — and prove what happened.
+
+## Phase 3 — Content
+1. Technical demo: refund agent.
+2. Attack Lab demonstration.
+3. Shadow → Enforce walkthrough.
+4. Replay evidence walkthrough.
+5. Partner case study when approved.
+
+## Phase 4 — Distribution
+- GitHub / npm developer funnel.
+- Founder-led technical outreach.
+- AI engineering/security communities.
+- Short technical videos demonstrating real decisions.
+- Documentation and integration examples.
+
+## Phase 5 — Conversion funnel
+Content → Quickstart → protected tool → Attack Lab → Shadow → Design Partner → Production → Paid plan.
+
+## Claims policy
+Prefer measured statements. Avoid absolute claims such as “makes agents safe,” “prevents all prompt injection,” or “replaces IAM/SIEM.”

package/docs/observability-alerting.md

@@ -0,0 +1,44 @@
+# Observability and Alerting Runbook
+
+## Health
+
+Probe:
+
+```text
+GET /api/health
+GET /api/ready
+```
+
+## Security alerts
+
+Alert on:
+
+- unexpected increase in BLOCK/ASK volume for a production tool;
+- cross-tenant authorization failures;
+- repeated egress secret findings;
+- approval failures or abnormal approval volume;
+- kill-switch activation;
+- policy activation/rollback events;
+- audit persistence failures.
+
+## Performance alerts
+
+Alert on sustained P95/P99 latency above the deployment's tested baseline, error rate, and database connection failures. Do not use the development benchmark as an SLA.
+
+## Operational dashboards
+
+At minimum track:
+
+```text
+requests
+ALLOW / ASK / BLOCK
+handler executions
+approval resolution latency
+policy version
+run persistence failures
+API errors
+P50 / P95 / P99
+active tenants
+```
+
+Use `/api/metrics`, `/api/observability`, `/api/security-report`, and `/api/audit/export` as evidence sources where appropriate.

package/docs/outreach.md

@@ -0,0 +1,26 @@
+# AgentGate Outreach — Design Partner Draft
+
+## Target
+AI SaaS/startup teams with agents that can execute real side effects: refunds, cancellations, production changes, exports, or CRM mutations.
+
+## Short message
+I built AgentGate, a runtime control plane for AI agent actions. It sits between an agent and its tools and can deterministically ALLOW, ASK, or BLOCK sensitive actions, with replayable audit evidence.
+
+I’m looking for 3–5 design partners. We start in sandbox/replay or Shadow Mode, then protect one sensitive tool. The goal is to prove one thing: a blocked action produces zero side effects.
+
+Would you be open to testing one real agent/tool workflow with us?
+
+## Technical follow-up
+The integration is designed to start with one tool and one Policy Pack. We provide the pilot checklist, acceptance gates, Attack Lab scenarios, and evidence/replay workflow.
+
+## Follow-up 1
+The pilot does not require production enforcement at the start. We can replay representative traffic first, show would-ALLOW/ASK/BLOCK decisions, review mismatches, then enforce one sensitive tool.
+
+## Follow-up 2
+If useful, I can run the first test with your refund/export/deployment tool and leave the decision evidence with your team.
+
+## Outreach rules
+- Do not claim customer results before a customer exists.
+- Do not claim prevention of every prompt injection.
+- Do not claim compliance certification.
+- Lead with a concrete side-effecting tool, not generic AI security.

package/docs/partner-intake-template.md

@@ -0,0 +1,26 @@
+# Partner Intake Template
+
+- Partner:
+- Agent:
+- Sensitive tool:
+- Environment:
+- Tool side effects:
+- Identity model:
+- Tenant model:
+- Existing authorization:
+- Existing approval path:
+- Existing audit evidence:
+- Sandbox/replay source:
+- Technical owner:
+- Pilot start:
+- Pilot target end:
+
+## Success criteria
+
+- BLOCK -> 0 handler execution
+- ASK -> 0 pre-approval execution
+- Approved ASK -> exactly 1 execution
+- Cross-tenant access -> 0 leaks
+- Undetected egress secrets -> 0
+- Audit mismatch -> 0
+- Replay after restart -> PASS

package/docs/performance-baseline.md

@@ -0,0 +1,23 @@
+# Performance Baseline — 2.13.8
+
+Measured with `npm run benchmark` on the release build.
+
+Environment:
+
+```text
+Node: v22.16.0
+OS/arch: linux-x64
+CPU: Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz
+Memory: 5.81 GB
+Samples: 5,000 per workload
+Concurrency: 100
+Policy: productionBlock=true, approvalAmount=5000, autoApproveAmount=500
+```
+
+| Workload | P50 | P95 | P99 | Throughput |
+|---|---:|---:|---:|---:|
+| ALLOW check | 2.323 ms | 5.225 ms | 7.570 ms | 35,915.98 ops/s |
+| BLOCK check | 2.239 ms | 5.168 ms | 8.393 ms | 40,660.09 ops/s |
+| ALLOW execute | 1.577 ms | 6.573 ms | 28.485 ms | 39,524.91 ops/s |
+
+These figures are an environment-specific baseline, not an SLA. Database persistence, network calls, model latency, egress inspection configuration, policy size and deployment topology can materially change end-to-end latency.

package/docs/performance.md

@@ -0,0 +1,27 @@
+# Performance Benchmark
+
+AgentGate security tests and performance benchmarks are separate concerns. A concurrency/security test proves correctness under load; it is not a latency SLA.
+
+Run:
+
+```bash
+npm run benchmark
+```
+
+The benchmark reports P50/P95/P99 latency and throughput for deterministic `check()` decisions and an execution path. Results are environment-specific and must be rerun on the customer's target infrastructure before publishing an SLA.
+
+## What to record
+
+- Node version
+- CPU / memory
+- AgentGate version
+- policy size/type
+- concurrency
+- sample count
+- P50/P95/P99
+- throughput
+- error count
+
+## Release policy
+
+No universal latency number is promised by AgentGate. A customer-facing performance claim must cite the exact benchmark environment and policy workload.

package/docs/pricing.md

@@ -0,0 +1,53 @@
+# AgentGate Pricing — Initial Test Model
+
+This is a proposed pricing experiment, not a claim of validated market pricing. Do not publish these numbers as final until at least 3 design-partner conversations test willingness to pay.
+
+## Free / Developer
+**$0**
+
+For local evaluation and open-source adoption.
+
+- SDK / runtime
+- Policy Packs
+- Simulate + Attack Lab
+- Local Replay
+- Shadow Mode
+- Community support
+
+## Pro
+**$99/month** starting point
+
+For one production team that needs centralized controls.
+
+- Everything in Developer
+- Hosted Control Plane
+- Team access
+- Central policy management
+- Approval workflows
+- Replayable audit evidence
+- Runtime monitoring
+- Usage limits to be finalized from partner data
+
+## Team / Production
+**$499/month** starting point
+
+For teams operating multiple agents or tenants.
+
+- Everything in Pro
+- Multi-tenant controls
+- Advanced policy bundles
+- Egress protection
+- Security reporting
+- Higher usage limits
+- Priority support
+
+## Enterprise
+**Custom**
+
+For organizations requiring deployment, identity, retention, support, or contractual requirements beyond the standard plans.
+
+### Pricing principles
+- Do not charge for a dashboard alone.
+- Price around protected runtime usage and control-plane value.
+- Keep local evaluation friction low.
+- Revisit price after design-partner evidence.

package/docs/production-deployment.md

@@ -0,0 +1,70 @@
+# Production Deployment Reference
+
+## Recommended topology
+
+```text
+Agent / Worker
+      |
+      v
+AgentGate Runtime / MCP Gateway
+      |
+      +---- PostgreSQL (durable runs, approvals, policy metadata)
+      |
+      +---- Control Plane (private network)
+      |
+      +---- HTTPS / OIDC / reverse proxy
+```
+
+### Development vs production
+
+- Development may use the built-in file persistence and local browser session.
+- Production should use a durable PostgreSQL/Supabase-backed store, tenant-scoped authentication, HTTPS, and a private Control Plane network.
+- Do not expose the service-role database credential or other server secrets to the browser.
+- Keep the Control Plane separate from untrusted agent traffic where practical.
+
+## PostgreSQL
+
+Apply `schema/postgres.sql` to a dedicated database. The schema enables RLS and requires a tenant scope for reads/writes.
+
+For pooled PostgreSQL clients, AgentGate scopes each transaction with `SET LOCAL agentgate.tenant_id`. The adapter also keeps explicit `tenant_id` predicates as defense in depth.
+
+### Connection requirements
+
+- TLS enabled between AgentGate and PostgreSQL.
+- Least-privilege database role.
+- Connection pool sized for the actual workload.
+- Statement and connection timeouts configured by the deployment platform.
+- Backups enabled at the database layer.
+
+### Readiness
+
+Use:
+
+```text
+GET /api/health
+GET /api/ready
+```
+
+`/api/ready` should be used by orchestrators for readiness, while liveness should remain lightweight.
+
+## Container deployment
+
+The repository includes a Node 20 Alpine `Dockerfile`. Build and run it behind an HTTPS reverse proxy. Set `NODE_ENV=production` and a durable persistence configuration; do not use local JSON persistence as the authoritative store for a multi-instance production deployment.
+
+## Rollout
+
+1. Install the exact package version and retain the lockfile.
+2. Run `npm test` and `node scripts/release-check.mjs`.
+3. Apply database migrations/schema and verify RLS.
+4. Start one canary instance in Observe/Shadow mode.
+5. Run Attack Lab and application-specific abuse cases.
+6. Verify audit export, replay, approval, and backup/restore procedures.
+7. Switch only the reviewed tools to Enforce.
+8. Expand tool-by-tool after acceptance criteria are met.
+
+## Rollback
+
+- Keep the previous application image/package available.
+- Never roll back the database blindly: check schema compatibility first.
+- Disable newly activated policies before reverting runtime code when policy/runtime compatibility is uncertain.
+- Preserve exported audit evidence before destructive rollback operations.