agentgate-runtime-control 2.13.8

package/bin/agentgate.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { evaluate } from '../src/policy-engine.js';
+import { createAgentGate } from '../src/agentgate.js';
+import { createControlPlane } from '../src/control-plane.js';
+import { runGatewayAttackLab, summarizeAttackResults } from '../src/attack-lab.js';
+import { createMCPGateway } from '../src/mcp-gateway.js';
+import { generateSecurityReport, renderSecurityReportHTML } from '../src/security-report.js';
+import { createPolicyRegistry } from '../src/policy-registry.js';
+import { TenantRegistry } from '../src/multi-tenant.js';
+import { scanMCPTools, createToolTrustStore } from '../src/mcp-scanner.js';
+import { guardEgress } from '../src/egress-guard.js';
+import { validateAgentGateConfig, simulatePolicyMatrix, runDoctorChecks } from '../src/local-experience.js';
+import { runSecurityValidation } from '../src/security-validation.js';
+import { listPolicyPacks, getPolicyPack, getDefaultPolicyPack } from '../src/policy-packs.js';
+import { analyzeShadowEvents } from '../src/shadow-mode.js';
+
+const require = createRequire(import.meta.url);
+const PACKAGE_VERSION = require('../package.json').version;
+
+const [cmd, action='read', amount='0'] = process.argv.slice(2);
+const showHelp = () => console.log(`AgentGate ${PACKAGE_VERSION} — Runtime Control Plane
+
+Usage:
+  agentgate init
+  agentgate dev [--port <port>]
+  agentgate test <action> [amount]
+  agentgate attack
+  agentgate attack-ci
+  agentgate report
+  agentgate scan <tools.json> [--strict]
+  agentgate egress <response.json> [--strict]
+  agentgate policy <create|list|test|activate|rollback|diff> <name> ...
+  agentgate tenant <create|list|key|revoke|rotate> ...
+  agentgate --help
+  agentgate doctor
+  agentgate simulate
+  agentgate validate-security
+  agentgate pack <list|show|init|test> [pack-id]
+  agentgate shadow <events.json>
+  agentgate partner init [pack]
+  agentgate partner check <report.json>
+  agentgate demo refund
+  agentgate --help
+  agentgate --version`);
+if (cmd === '--help' || cmd === '-h' || cmd === 'help') { showHelp(); process.exit(0); }
+if (cmd === '--version' || cmd === '-v' || cmd === 'version') { console.log(PACKAGE_VERSION); process.exit(0); }
+
+if (cmd === 'pack') {
+  const sub = process.argv[3] || 'list';
+  if (sub === 'list') console.log(JSON.stringify(listPolicyPacks(), null, 2));
+  else if (sub === 'show') {
+    const id = process.argv[4] || 'support-refund-safety';
+    const pack = getPolicyPack(id);
+    if (!pack) { console.error(`Unknown policy pack: ${id}`); process.exitCode = 1; }
+    else console.log(JSON.stringify(pack, null, 2));
+  } else if (sub === 'init') {
+    const id = process.argv[4] || 'support-refund-safety';
+    const pack = getPolicyPack(id);
+    if (!pack) { console.error(`Unknown policy pack: ${id}`); process.exitCode = 1; }
+    else {
+      const file = path.resolve(process.cwd(), 'agentgate.config.mjs');
+      const content = `import { createAgentGate, getPolicyPack } from 'agentgate-runtime-control';
+
+const pack = getPolicyPack('${pack.id}');
+
+export const agentgate = createAgentGate({
+  agent: 'SupportAgent',
+  mode: 'enforce',
+  policies: pack.policies
+});
+
+export { pack };
+`;
+      try { await fs.access(file); console.error('agentgate.config.mjs already exists'); process.exitCode = 1; }
+      catch { await fs.writeFile(file, content, 'utf8'); console.log(`Created ${file} from ${pack.name} (enforce mode)`); }
+    }
+  } else if (sub === 'test') {
+    const id = process.argv[4] || 'support-refund-safety';
+    const pack = getPolicyPack(id);
+    if (!pack) { console.error(`Unknown policy pack: ${id}`); process.exitCode = 1; }
+    else {
+      const results = simulatePolicyMatrix({ policies: pack.policies, cases: pack.cases });
+      const passed = results.filter((x, i) => x.decision === pack.cases[i].expected).length;
+      console.log(JSON.stringify({ pack: pack.id, total: results.length, passed, failed: results.length - passed, results }, null, 2));
+      if (passed !== results.length) process.exitCode = 2;
+    }
+  } else { console.error('Usage: agentgate pack <list|show|init|test> [pack-id]'); process.exitCode = 1; }
+} else if (cmd === 'demo' && process.argv[3] === 'refund') {
+  const pack = getDefaultPolicyPack();
+  const gate = createAgentGate({ agent: 'SupportAgent', mode: 'enforce', policies: pack.policies });
+  let executions = 0;
+  const refund = gate.protect(async input => { executions += 1; return { refunded: input.amount, customerId: input.customerId }; }, { tool: 'refund', action: 'refund' });
+  console.log(`\nAgentGate — ${pack.name} v${pack.version}`);
+  console.log('Policy: refund → ASK | > $5,000 → BLOCK | invalid amounts → BLOCK');
+  for (const [amount, label] of [[250, 'small-refund'], [1200, 'review-refund'], [5000.01, 'over-ceiling'], ['5000.01', 'invalid-string']]) {
+    try {
+      const result = await refund({ amount, customerId: 'demo_customer' }, { amount });
+      console.log(JSON.stringify({ case: label, amount, status: result.status, decision: result.agentgate?.decision, winningRule: result.agentgate?.winningRule, executionCount: executions }));
+    } catch (error) {
+      console.log(JSON.stringify({ case: label, amount, status: 'blocked', decision: error.agentgate?.decision, winningRule: error.agentgate?.winningRule, executionCount: executions }));
+    }
+  }
+  console.log(JSON.stringify({ proof: 'blocked actions did not execute', refundExecutions: executions }, null, 2));
+} else if (cmd === 'doctor') {
+  const configPath = path.resolve(process.cwd(), 'agentgate.config.mjs');
+  let config = { mode: 'enforce', policies: { productionBlock: true, autoApproveAmount: 500, approvalAmount: 5000 }, authRequired: true };
+  try { const mod = await import(`file://${configPath}?doctor=${Date.now()}`); const gate = mod.agentgate || {}; config = { ...config, ...(mod.config || {}), ...(gate.config || {}), ...(gate.mode ? { mode: gate.mode } : {}), ...(gate.policies ? { policies: gate.policies } : {}) }; } catch {}
+  const report = runDoctorChecks({ config });
+  console.log(JSON.stringify(report, null, 2)); process.exitCode = report.ok ? 0 : 2;
+} else if (cmd === 'simulate') {
+  const policy = { productionBlock: true, autoApproveAmount: 500, approvalAmount: 5000 };
+  console.log(JSON.stringify(simulatePolicyMatrix({ policies: policy }), null, 2));
+} else if (cmd === 'partner') {
+  const sub = process.argv[3] || 'help';
+  if (sub === 'init') {
+    const packId = process.argv[4] || 'support-refund-safety';
+    const pack = getPolicyPack(packId);
+    if (!pack) { console.error(`Unknown policy pack: ${packId}`); process.exitCode = 1; }
+    else {
+      const dir = path.resolve(process.cwd(), 'design-partner');
+      await fs.mkdir(dir, { recursive: true });
+      const files = {
+        'partner-intake.md': `# Design Partner Intake\n\n- Partner: \n- Agent: \n- Sensitive tool: \n- Environment: sandbox / replay / production\n- Identity/tenant model: \n- Existing authorization: \n- Side effects: \n- Contact: \n\n## Success criteria\n- BLOCK -> 0 handler execution\n- ASK -> 0 pre-approval execution\n- Approved ASK -> exactly 1 execution\n- Cross-tenant access -> 0 leaks\n- Egress secret leakage -> 0 undetected test cases\n- Audit mismatch -> 0\n`,
+        'pilot-plan.md': `# Design Partner Pilot Plan\n\n## Phase 1 — Sandbox / Replay\nInstall the real AgentGate package and replay representative traffic.\n\n## Phase 2 — Shadow\nRecord proposed ALLOW/ASK/BLOCK decisions while existing execution continues. Review every mismatch.\n\n## Phase 3 — Enforce one tool\nEnable enforcement only after the shadow report is safe and the approval boundary has been tested.\n\n## Phase 4 — Evidence\nPreserve Run, winningRule, ruleTrace, execution outcome, egress findings, and Replay evidence.\n\n## Exit\nMove to production only when all acceptance criteria are green and the partner approves the evidence.\n`,
+        'acceptance-scorecard.md': `# Design Partner Acceptance Scorecard\n\n| Gate | Target | Result |\n|---|---|---|\n| BLOCK side effects | 0 | |\n| ASK pre-approval execution | 0 | |\n| Approved execution | exactly 1 | |\n| Cross-tenant leaks | 0 | |\n| Undetected egress secrets | 0 | |\n| Audit mismatch | 0 | |\n| Restart/Replay | PASS | |\n| First protected tool | < 10 min target | |\n\nDo not mark the pilot production-ready while any critical gate is unresolved.\n`,
+        'exit-report.md': `# Design Partner Exit Report\n\n## Outcome\n- Status: pending / ready / blocked\n- Policy Pack: ${pack.id}\n- Agent: \n- Sensitive tool: \n\n## Evidence\n- Shadow report: \n- Attack report: \n- Replay run IDs: \n- Restart verification: \n\n## Before / After\n| Metric | Before | AgentGate |\n|---|---:|---:|\n| Dangerous actions reaching handler | | |\n| Pre-approval executions | | |\n| Duplicate approvals | | |\n| Audit mismatches | | |\n| Undetected egress findings | | |\n\n## Limitations\n\n`
+      };
+      for (const [name, content] of Object.entries(files)) await fs.writeFile(path.join(dir, name), content, 'utf8');
+      console.log(`Created ${dir} for ${pack.name}`);
+    }
+  } else if (sub === 'check') {
+    const file = process.argv[4];
+    if (!file) { console.error('Usage: agentgate partner check <report.json>'); process.exitCode = 1; }
+    else {
+      const report = JSON.parse(await fs.readFile(path.resolve(file), 'utf8'));
+      const gates = {
+        blockSideEffectsZero: report.blockSideEffects === 0,
+        askPreApprovalZero: report.askPreApprovalExecutions === 0,
+        approvedExactlyOnce: report.approvedExecutions === 1,
+        crossTenantZero: report.crossTenantLeaks === 0,
+        egressUndetectedZero: report.undetectedEgressSecrets === 0,
+        auditMismatchZero: report.auditMismatches === 0,
+        replayAfterRestart: report.replayAfterRestart === true
+      };
+      const failed = Object.entries(gates).filter(([, ok]) => !ok).map(([name]) => name);
+      console.log(JSON.stringify({ ready: failed.length === 0, gates, failed }, null, 2));
+      process.exitCode = failed.length ? 2 : 0;
+    }
+  } else {
+    console.error('Usage: agentgate partner <init|check> ...'); process.exitCode = 1;
+  }
+} else if (cmd === 'shadow') {
+  const file = process.argv[3];
+  if (!file) { console.error('Usage: agentgate shadow <events.json>'); process.exitCode = 1; }
+  else {
+    const input = JSON.parse(await fs.readFile(path.resolve(file), 'utf8'));
+    const events = Array.isArray(input) ? input : (input.events || []);
+    const report = analyzeShadowEvents(events);
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.safeForEnforcement) process.exitCode = 2;
+  }
+} else if (cmd === 'validate-security') {
+  const report = await runSecurityValidation();
+  console.log(JSON.stringify(report, null, 2)); process.exitCode = report.ok ? 0 : 2;
+} else if (cmd === 'scan') {
+  const file = process.argv[3];
+  if (!file) { console.error('Usage: agentgate scan <tools.json> [--strict]'); process.exitCode=1; }
+  else { const input=JSON.parse(await fs.readFile(path.resolve(file),'utf8')); const result=scanMCPTools(Array.isArray(input)?input:(input.tools||[])); console.log(JSON.stringify(result,null,2)); if(process.argv.includes('--strict') && result.summary.high>0) process.exitCode=2; }
+} else if (cmd === 'egress') {
+  const file = process.argv[3];
+  if (!file) { console.error('Usage: agentgate egress <response.json> [--strict]'); process.exitCode = 1; }
+  else {
+    const input = JSON.parse(await fs.readFile(path.resolve(file), 'utf8'));
+    const result = guardEgress(input);
+    console.log(JSON.stringify(result, null, 2));
+    if (process.argv.includes('--strict') && result.action === 'BLOCK') process.exitCode = 2;
+  }
+} else if (cmd === 'attack-ci') {
+  const gateway = createMCPGateway({ mode:'enforce', policies:{productionBlock:true}, tools:[{name:'export_all',handler:async()=>({})},{name:'update_production',handler:async()=>({})},{name:'delete',handler:async()=>({})},{name:'refund',handler:async()=>({})},{name:'publish',handler:async()=>({})}] });
+  const results=await runGatewayAttackLab(gateway); const summary=summarizeAttackResults(results); console.log(JSON.stringify({summary,results},null,2)); process.exitCode=summary.failed?2:0;
+} else if (cmd === 'test' || cmd === 'check') {
+  console.log(JSON.stringify(evaluate({ action, amount: Number(amount) }), null, 2));
+} else if (cmd === 'attack') {
+  const gateway = createMCPGateway({
+    mode: 'enforce',
+    policies: { productionBlock: true },
+    tools: [
+      { name: 'export_all', handler: async () => ({ executed: true }) },
+      { name: 'update_production', handler: async () => ({ executed: true }) },
+      { name: 'delete', handler: async () => ({ executed: true }) },
+      { name: 'refund', handler: async args => ({ refunded: args.amount }) },
+      { name: 'publish', handler: async () => ({ executed: true }) }
+    ]
+  });
+  const results = await runGatewayAttackLab(gateway);
+  const summary = summarizeAttackResults(results);
+  console.log('\nAgentGate Attack Runner');
+  console.table(results.map(x => ({ test: x.name, decision: x.decision, risk: x.risk, passed: x.passed, runId: x.runId })));
+  console.log('Summary:', JSON.stringify(summary));
+  process.exitCode = summary.failed ? 2 : 0;
+} else if (cmd === 'report') {
+  const gateway = createMCPGateway({
+    mode: 'enforce',
+    policies: { productionBlock: true },
+    tools: [
+      { name: 'export_all', handler: async () => ({ executed: true }) },
+      { name: 'update_production', handler: async () => ({ executed: true }) },
+      { name: 'delete', handler: async () => ({ executed: true }) },
+      { name: 'refund', handler: async args => ({ refunded: args.amount }) },
+      { name: 'publish', handler: async () => ({ executed: true }) }
+    ]
+  });
+  const attacks = await runGatewayAttackLab(gateway);
+  const report = generateSecurityReport({ attackResults: attacks, runs: gateway.runs(), policies: { productionBlock: true }, metadata: { agent: 'Attack Runner', environment: 'production' } });
+  const jsonPath = path.resolve(process.cwd(), 'agentgate-security-report.json');
+  const htmlPath = path.resolve(process.cwd(), 'agentgate-security-report.html');
+  await fs.writeFile(jsonPath, JSON.stringify(report, null, 2), 'utf8');
+  await fs.writeFile(htmlPath, renderSecurityReportHTML(report), 'utf8');
+  console.log(`Security report: ${report.summary.status}`);
+  console.log(`JSON: ${jsonPath}`);
+  console.log(`HTML: ${htmlPath}`);
+  process.exitCode = report.summary.failed ? 2 : 0;
+} else if (cmd === 'policy') {
+  const sub = process.argv[3] || 'list';
+  const name = process.argv[4] || 'default';
+  const registry = createPolicyRegistry({ filePath: path.resolve(process.cwd(), '.agentgate/policies.json') });
+  if (sub === 'create') {
+    const policy = JSON.parse(process.argv[5] || '{}');
+    console.log(JSON.stringify(registry.create(name, policy), null, 2));
+  } else if (sub === 'list') {
+    console.log(JSON.stringify(registry.list(name), null, 2));
+  } else if (sub === 'diff') {
+    console.log(JSON.stringify(registry.diff(name, Number(process.argv[5]), Number(process.argv[6])), null, 2));
+  } else if (sub === 'test') {
+    const version = Number(process.argv[5]);
+    const cases = JSON.parse(process.argv[6] || '[]');
+    console.log(JSON.stringify(registry.test(name, version, cases), null, 2));
+  } else if (sub === 'activate' || sub === 'rollback') {
+    const version = Number(process.argv[5]);
+    const result = sub === 'activate' ? registry.activate(name, version) : registry.rollback(name, version);
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.error('Usage: agentgate policy <create|list|test|activate|rollback|diff> <name> ...');
+    process.exitCode = 1;
+  }
+} else if (cmd === 'tenant') {
+  const sub = process.argv[3] || 'list';
+  const registry = new TenantRegistry({ filePath: path.resolve(process.cwd(), '.agentgate/tenants.json'), keyPath: path.resolve(process.cwd(), '.agentgate/api-keys.json') });
+  if (sub === 'create') console.log(JSON.stringify(registry.create(process.argv[4] || 'workspace'), null, 2));
+  else if (sub === 'list') console.log(JSON.stringify(registry.list(), null, 2));
+  else if (sub === 'key') {
+    const tenantId = process.argv[4]; const scopes = (process.argv[5] || 'runs:read').split(',');
+    console.log(JSON.stringify(registry.issueKey(tenantId, { scopes }), null, 2));
+  } else if (sub === 'revoke') console.log(JSON.stringify(registry.revoke(process.argv[4]), null, 2));
+  else if (sub === 'rotate') console.log(JSON.stringify(registry.rotate(process.argv[4]), null, 2));
+  else { console.error('Usage: agentgate tenant <create|list|key|revoke|rotate> ...'); process.exitCode = 1; }
+} else if (cmd === 'init') {
+  const packIndex = process.argv.indexOf('--pack');
+  const packId = packIndex >= 0 ? process.argv[packIndex + 1] : null;
+  const pack = packId ? getPolicyPack(packId) : null;
+  if (packId && !pack) { console.error(`Unknown policy pack: ${packId}`); process.exitCode = 1; }
+  else {
+    const file = path.resolve(process.cwd(), 'agentgate.config.mjs');
+    const content = pack
+      ? `import { createAgentGate, getPolicyPack } from 'agentgate-runtime-control';\n\nconst pack = getPolicyPack('${pack.id}');\n\nexport const agentgate = createAgentGate({\n  agent: 'SupportAgent',\n  mode: 'observe',\n  policies: pack.policies\n});\n\nexport { pack };\n`
+      : `import { createAgentGate } from 'agentgate-runtime-control';\n\nexport const agentgate = createAgentGate({\n  agent: 'MyAgent',\n  mode: 'enforce',\n  policies: {\n    productionBlock: true,\n    autoApproveAmount: 500,\n    approvalAmount: 5000\n  }\n});\n`;
+    try { await fs.access(file); console.error('agentgate.config.mjs already exists'); process.exitCode = 1; }
+    catch { await fs.writeFile(file, content, 'utf8'); console.log(`Created ${file}${pack ? ` from ${pack.name} (enforce mode)` : ''}`); }
+  }
+} else if (cmd === 'dev') {
+  const htmlPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../standalone.html');
+  const html = await fs.readFile(htmlPath, 'utf8');
+  const gate = createAgentGate({ agent: 'DemoAgent', mode: 'enforce', policies: { productionBlock: true } });
+  const gateway = gate.withMCP({ tools: [
+    { name: 'read', handler: async args => ({ ok: true, data: args, simulated: true, environment: 'demo' }) },
+    { name: 'refund', handler: async args => ({ refunded: args.amount, simulated: true, environment: 'demo' }) },
+    { name: 'delete', handler: async args => ({ deleted: args.id, simulated: true, environment: 'demo' }) },
+    { name: 'export_all', handler: async args => ({ simulated: true, environment: 'demo', action: 'export_all', args }) },
+    { name: 'update_production', handler: async args => ({ simulated: true, environment: 'demo', action: 'update_production', args }) },
+    { name: 'publish', handler: async args => ({ simulated: true, environment: 'demo', action: 'publish', args }) }
+  ]});
+  await gateway.handle({ jsonrpc:'2.0', id:1, method:'tools/call', params:{ name:'read', arguments:{ id:'demo_customer' }, agent:'DemoAgent', action:'read', environment:'development' }});
+  await gateway.handle({ jsonrpc:'2.0', id:2, method:'tools/call', params:{ name:'refund', arguments:{ amount:1200, customerId:'demo_customer' }, agent:'DemoAgent', action:'refund', environment:'development' }});
+  await gateway.handle({ jsonrpc:'2.0', id:3, method:'tools/call', params:{ name:'delete', arguments:{ id:'demo_customer' }, agent:'DemoAgent', action:'delete', environment:'production' }});
+  const portArgIndex = process.argv.indexOf('--port');
+  const port = Number(portArgIndex >= 0 ? process.argv[portArgIndex + 1] : process.env.PORT || 8787);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) { console.error('Invalid port. Use --port <1-65535> or PORT=<port>.'); process.exitCode = 1; }
+  else {
+    const { server } = createControlPlane({ gateway, html, localDevSession: true });
+    server.on('error', error => {
+      if (error?.code === 'EADDRINUSE') console.error(`Port ${port} is already in use. Use agentgate dev --port <port> or PORT=<port>.`);
+      else console.error(`AgentGate dev server error: ${error?.message || error}`);
+      process.exitCode = 1;
+    });
+    server.listen(port, () => console.log(`AgentGate Control Plane: http://localhost:${port}`));
+  }
+} else {
+  showHelp();
+}

package/docs/case-study-technical-validation.md

@@ -0,0 +1,25 @@
+# AgentGate Technical Validation — 2.13.0
+
+> This is a technical validation report, not a customer case study. It must not be presented as customer evidence.
+
+> The 2.13.6 release retains this validated runtime baseline and adds first-client hardening; this document describes the historical 2.13.0 validation evidence.
+
+## Scope
+AgentGate 2.13.0 was tested from an independent consumer project using a real npm tarball, without relying on the package source tree.
+
+## Results
+- Design Partner workflow: 19/19 checks passed.
+- Three Policy Packs were discoverable and contained policies/test cases.
+- Shadow mode recorded proposed decisions and mismatch/readiness fields.
+- ASK produced zero pre-approval executions; approved ASK executed exactly once.
+- Live, Run and Replay evidence matched on `winningRule` and `ruleTrace`.
+- Restart preserved blocked Run and Replay evidence.
+- Cross-tenant access returned 403.
+- Egress controls blocked raw credentials and applied configured redaction.
+- 10,000 concurrent destructive attempts produced 10,000 BLOCK decisions and zero executions.
+
+## What this proves
+The tested runtime control boundary can be demonstrated with deterministic evidence. It does not prove that AgentGate prevents every AI security failure, replaces IAM, or provides legal/compliance certification.
+
+## Customer case study policy
+A customer case study must only be published after a real partner has completed Shadow → Enforce and approved publication of the relevant metrics and quotes.

package/docs/case-study-template.md

@@ -0,0 +1,37 @@
+# AgentGate Case Study Template
+
+## 1. Agent and workflow
+- Agent:
+- Sensitive tool:
+- Environment:
+- Existing authorization:
+
+## 2. Baseline
+- Requests tested:
+- Risky actions observed:
+- Existing approval path:
+- Existing audit evidence:
+
+## 3. AgentGate deployment
+- Policy Pack:
+- Mode: shadow / enforce
+- Integration time:
+- Policies changed during pilot:
+
+## 4. Results
+| Metric | Before | With AgentGate |
+|---|---:|---:|
+| Dangerous actions reaching handler | | |
+| Pre-approval executions | | |
+| Duplicate approvals | | |
+| Audit mismatches | | |
+| Undetected egress findings | | |
+
+## 5. Evidence
+- Replay run IDs:
+- Winning rules:
+- Attack scenarios:
+- Partner-approved screenshots/logs:
+
+## 6. Limitations
+Document what AgentGate did not protect and what remained under application/IAM/provider controls.

package/docs/data-protection.md

@@ -0,0 +1,49 @@
+# Data Protection, Retention, Backup and Restore
+
+## Scope
+
+AgentGate can persist runs, approvals, policy metadata and audit evidence. The application owner is responsible for classifying the data and choosing the retention period appropriate to the workload.
+
+## Retention
+
+The in-process/local stores enforce bounded retention. Configure the production database retention separately; do not treat the local `maxRuns` limit as a compliance retention policy.
+
+Recommended operational baseline for a pilot:
+
+- Hot audit/run data: 30 days.
+- Exported security evidence: retain according to the customer's compliance requirement.
+- Approvals: retain with the associated audit record for the same period unless a stricter requirement applies.
+
+These are deployment defaults, not legal advice; customers must set their own policy.
+
+## Encryption
+
+- TLS for AgentGate-to-database and user-to-Control-Plane traffic.
+- Encrypt database storage using the cloud/database provider's encryption-at-rest controls.
+- Encrypt backups using provider-managed or customer-managed keys according to the customer's requirements.
+- Never put API keys, bearer tokens, database credentials, or private keys into policy definitions, browser bundles, or exported audit files unless explicitly required and protected.
+
+## Backup
+
+For PostgreSQL, enable automated provider backups and point-in-time recovery where available. For higher assurance, keep an independent backup/export according to the customer's RPO.
+
+Minimum pilot procedure:
+
+1. Take/verify a database backup.
+2. Record backup timestamp and database schema version.
+3. Restore into an isolated database.
+4. Run tenant-isolation, replay, approval, and audit-read tests.
+5. Record restore duration.
+
+## Restore acceptance targets
+
+The deployment owner should explicitly choose:
+
+- RPO: maximum acceptable data loss.
+- RTO: maximum acceptable recovery time.
+
+AgentGate does not claim a universal RPO/RTO because those values depend on the customer's database and infrastructure.
+
+## Deletion
+
+Customer data deletion must be performed at the database layer according to the tenant/data-retention policy. Verify that backups and exported evidence follow the same contractual deletion requirements.

package/docs/design-partner-checklist.md

@@ -0,0 +1,32 @@
+# Design Partner Checklist
+
+## Before integration
+- [ ] One real agent selected
+- [ ] One sensitive tool selected
+- [ ] Tool side effects documented
+- [ ] Identity/tenant model documented
+- [ ] Sandbox or replay data available
+- [ ] Success criteria agreed
+
+## Shadow phase
+- [ ] AgentGate installed from a real package
+- [ ] Policy Pack selected
+- [ ] Decisions recorded
+- [ ] Actual outcomes captured
+- [ ] Would-block executions reviewed
+- [ ] False positives reviewed
+- [ ] False negatives reviewed
+
+## Enforcement phase
+- [ ] Low-risk tool passed shadow review
+- [ ] Sensitive tool has explicit approval boundary
+- [ ] BLOCK execution = 0 in test
+- [ ] ASK pre-approval execution = 0 in test
+- [ ] Approved execution = 1 in test
+- [ ] Replay survives restart
+
+## Exit criteria
+- [ ] Partner accepts production use
+- [ ] Second workflow requested or demonstrated
+- [ ] Evidence can support a case study
+- [ ] No unresolved critical audit mismatch

package/docs/design-partner-kit.md

@@ -0,0 +1,51 @@
+# AgentGate Design Partner Kit
+
+This kit is the controlled operating package for a 3–5 partner pilot. It is not a general security or compliance program.
+
+## 1. Select one workflow
+
+Start with one agent and one side-effecting tool. Recommended first workflow: Support Refund Safety.
+
+- Agent: support/operations agent
+- Sensitive tool: `refund`
+- Initial environment: sandbox or replay
+- Policy Pack: `support-refund-safety`
+
+## 2. Run the five-step pilot
+
+1. **Intake** — document the agent, tool, side effects, identity/tenant model, and existing authorization.
+2. **Sandbox / replay** — install AgentGate from the real package and replay representative traffic.
+3. **Shadow** — record proposed decisions and compare them with actual execution. Do not enforce until mismatches are reviewed.
+4. **Enforce** — enable one sensitive tool only after the acceptance gates pass.
+5. **Evidence / exit** — preserve Run, winningRule, ruleTrace, execution result, egress findings, and Replay evidence; complete the exit report.
+
+## 3. Acceptance gates
+
+- `BLOCK -> handler execution = 0`
+- `ASK -> pre-approval execution = 0`
+- approved `ASK -> exactly 1 execution`
+- cross-tenant access -> `0` leaks
+- undetected egress secret findings -> `0`
+- audit mismatch -> `0`
+- restart/replay -> PASS
+- first protected tool -> target under 10 minutes
+
+## 4. Partner evidence package
+
+Every pilot should produce:
+
+- policy pack and test cases
+- shadow report
+- attack results
+- enforcement results
+- approval evidence
+- replay run IDs
+- restart verification
+- before/after metrics
+- limitations and unresolved controls
+
+## 5. Exit decision
+
+A pilot is **ready** only when every critical gate is green and the partner explicitly accepts the evidence. Otherwise keep the tool in shadow mode and resolve the failing gate.
+
+AgentGate does not claim to prevent every prompt-injection technique and does not replace application authorization, IAM, network isolation, or provider controls.

package/docs/design-partner-rollout.md

@@ -0,0 +1,35 @@
+# AgentGate Design Partner Rollout
+
+This is the controlled path from a tested AgentGate build to a production candidate.
+It is intentionally narrower than a general AI-security launch.
+
+## Ten-stage rollout
+
+1. **Freeze a tested baseline** — start from a release that passed an external consumer-project test.
+2. **Fast first protection** — install, initialize, simulate, attack, and protect one tool without building a control plane first.
+3. **Policy Pack** — start with one job-specific pack and declared test cases.
+4. **Shadow Mode** — record what AgentGate would ALLOW/ASK/BLOCK while the existing tool still executes.
+5. **Design Partner** — use 3–5 partners, one agent and one sensitive tool per partner initially.
+6. **Enforce** — move one validated sensitive tool from shadow to enforcement.
+7. **Evidence** — require request, decision, winning rule, rule trace, execution outcome, and replay evidence.
+8. **Case Study** — measure before/after outcomes using partner-approved data.
+9. **Productize** — extract repeated policy patterns, integrations, and onboarding friction into the product.
+10. **Commercialize** — only after repeatable protection and onboarding evidence exists.
+
+## Partner acceptance gates
+
+- `BLOCK -> handler execution = 0`
+- `ASK -> pre-approval execution = 0`
+- Approved `ASK -> exactly 1 execution`
+- Cross-tenant access -> `0` leaks
+- Egress secret leakage -> `0` undetected test cases
+- Audit mismatch -> `0`
+- Restart/replay -> evidence remains available
+- Time to first protected tool -> target under 10 minutes
+
+## Rollout sequence
+
+`replay/sandbox -> shadow -> low-risk enforce -> sensitive-tool enforce`
+
+Do not start with sensitive production data. Review the partner's tool contract,
+identity model, and existing authorization before enforcement.

package/docs/design-partner.md

@@ -0,0 +1,67 @@
+# AgentGate Design Partner Program
+
+AgentGate is introduced to a design partner around one measurable runtime boundary, not as a general-purpose AI security replacement.
+
+## First use case: Support Refund Safety
+
+Start with one side-effecting tool such as `refund`.
+
+```text
+Agent request
+    ↓
+AgentGate
+    ↓
+ALLOW / ASK / BLOCK
+    ↓
+Tool execution
+    ↓
+Audit + Replay evidence
+```
+
+The default Support Refund Safety Pack uses:
+
+- refunds → `ASK`
+- `> $5,000` → `BLOCK`
+- the pack's `autoApproveAmount` remains available for policy evolution, but this conservative pack does not bypass the runtime's destructive-action approval boundary
+- invalid amount types → fail closed through the runtime policy engine
+- `export_all` → `BLOCK`
+
+The pack is a starting point, not a compliance guarantee. Review thresholds and tool semantics before enforcement.
+
+## 10-minute first protection
+
+```bash
+npm install agentgate-runtime-control
+npx agentgate pack list
+npx agentgate pack init support-refund-safety
+npx agentgate simulate
+npx agentgate attack
+```
+
+For a focused demonstration:
+
+```bash
+npx agentgate demo refund
+```
+
+The generated configuration starts in `enforce` mode for the packaged safety default. If a team wants Shadow/Observe, it must explicitly set `mode: 'observe'` and treat that configuration as non-enforcing.
+
+## Rollout
+
+1. Use sandbox or replay traffic.
+2. Start in `observe` mode.
+3. Compare AgentGate's proposed decisions with actual tool behavior.
+4. Run normal and adversarial cases.
+5. Move one tool to `enforce` only after review.
+6. Preserve replayable evidence for every sensitive decision.
+
+## Acceptance criteria
+
+- `BLOCK → handler execution = 0`
+- `ASK → pre-approval execution = 0`
+- approved action executes exactly once
+- cross-tenant access = 0
+- egress secret leakage = 0
+- audit mismatch = 0
+
+AgentGate does not claim to prevent every prompt-injection technique and does not replace application authorization, IAM, network isolation, or provider controls.