# @connexum/ai-governance

> Enterprise governance for AI agents. Enforcement, not monitoring.
> The runtime layer of the [My Compliance Center](https://my-cc.io) trust citadel.

[![status](https://img.shields.io/badge/status-PRODUCTION-brightgreen)]()
[![stripe](https://img.shields.io/badge/billing-LIVE%20on%20Stripe-635bff)]()
[![packs](https://img.shields.io/badge/compliance%20packs-156-blue)]()
[![tests](https://img.shields.io/badge/tests-passing-brightgreen)]()
[![license](https://img.shields.io/badge/license-SEE%20LICENSE-blue)](LICENSE.md)

## Production Status

**LIVE in production.** The platform is operational end-to-end: signup → agent registration → pack binding → runtime enforcement → audit chain → billing.

| Surface | State |
|---------|-------|
| Signup + agent registration | LIVE at [app.my-cc.io](https://app.my-cc.io) |
| Stripe billing | LIVE on `acct_1TAllpCPfEQAFBFQ` — 5 products, 11 prices, beta-comp coupons active through 2026-08-23 |
| First paying customer journey | VERIFIED OPERATIONAL (qty=1 and qty=5, 2026-05-25) |
| License server | `license.my-cc.io` — signed-token issuance with RSA keys |
| Runtime SDK | `npx @connexum/ai-governance init` — installs hooks + binds tenant in one command |
| Compliance pack catalog | 156 packs across 30+ jurisdictions, 152 with runtime CategoryClassifiers attached + invoked (99.3%) |
| Layer 3 pack-content-hash gate | FULLY CLOSED — pack files SHA-256-verified at load + TOCTOU re-verified at runtime |
| Audit chain | SHA-256 hash-linked (`cluster-audit-bridge.ts`); per-event HMAC-signed trust anchors; cross-tenant RLS at DB layer. RFC 3161 external TSA timestamping: **on roadmap** (`trust-anchor.ts:18`) — today's anchors are LocalFile + Webhook + HMAC-signed; external Time-Stamping Authority integration is future work |
| Dashboard | LIVE at [app.my-cc.io](https://app.my-cc.io) — fleet overview, agent profiles, compliance center, audit search, approval queue |
| Documentation portal | LIVE at [my-cc.io/docs](https://my-cc.io/docs) |
| OWASP Agentic Top 10 coverage | **LIVE in code** — 15 prompt-injection patterns (AGENT-TRAP + INSTR-OVERRIDE + AUTH-ESC + EXFIL families) extended to tool-role messages, catching the salutation- and keyword-based payloads described in the DeepMind workspace-file research. **Scope hedge**: pattern-based matching catches the demonstrated attack phrases; novel semantically-equivalent payloads that avoid known keyword markers may still pass — defense in depth via runtime guards + Capability Composition Risk scoring is the broader strategy. Also live: `owasp-agentic-scanner.ts` integrated into CLI gap-report + onAgentRegistered hook on `POST /api/v1/agents`; Step3 OWASP triage mandatory in wizard with CRITICAL gate; `MissingControl.fix.remediationByLicenseState` schema; `owasp_category` audit-chain tagging + `GET /api/v1/owasp/posture` query layer; `OwaspPostureTile` dashboard component. Honest scope hedges in `docs/cisos/07-owasp-agentic-top10.md` (A03 SDK-path-only, A06 proxy-only, A10 data-tenancy-only — not model extraction). |
| Trust Score 4-axis composite | **LIVE in code** — `FourAxisScore` = ThreeAxis × 0.75 + Interaction × 0.25; Interaction sub-signals: agentToTool (60%: sanctionedToolRatio + failureRecoveryRate + blastRadiusAdherence + purposeAlignmentRatio + capabilityCompositionRisk) + agentToAgent (40%: handshakeSuccessRatio + refusalRate + passportResolutionRate). 12-entry capability-composition conflict matrix (`web-scraping+decision-making` → FAIL, `read-secrets+ANY-external` → FAIL, etc.). `MCP_HANDSHAKE_OBSERVED` event type emitted from `mcp-server-trust/handleToolCall`. `POST /api/v1/trust-score/refresh` returns FourAxisScore. `TrustScoreFourAxisCard` dashboard component live. `interactionAxisComposite` exposed via `PublicAgentView` cross-org boundary (composite only — sub-signals stay private per Invariant 6). |
| Trust Score Report (12-dim Trust Genome) | **LIVE in code** — `TrustScoreReport` component renders dark-theme score circle + grade letter + HIGH RISK/UNINSURED badges + 12-dimension Trust Genome bars + Financial Exposure + Insurance Gap. New wizard step 3.5 (pre-injection baseline) + Step 9 (post-activation rescore + baseline-vs-rescore diff). Endpoints: `POST /api/v1/trust-score/baseline-snapshot` + `POST /api/v1/trust-score/rescore-after-activation`. Tables `trust_score_baseline_snapshots` + `trust_score_postactivation_snapshots` created on Postgres-SY7j with RLS. |
| RFC 3161 external TSA timestamping | **PARTIALLY LIVE** — DigiCert primary + GlobalSign fallback config in `getRfc3161Config()`; `Rfc3161TrustAnchorSink` wired via `clusterAppendObserver` fan-out array (per-entry semantics, never overwrites trust-score refresh observer); `verifyRfc3161Anchor` SDK helper exported from `@connexum/typescript-sdk` (offline DER validation, no API key needed); public verification endpoint `GET /api/v1/audit-chain/:entryId/rfc3161-verify` (rate-limited 30 req/10 min/IP); "Externally Verified by [TSA]" badge in dashboard audit views. **Note**: production `audit_chain_pointer` table doesn't have the `tsr_token` columns yet — sink falls back to in-memory token store per Invariant 2; SQL persistence pending schema work. |

**Latest production milestones (2026-05):**
- **2026-05-29/30 — OWASP Agentic (ASI) Top 10 parity program + platform-wide auth hardening**:
  - **ASI parity to the OWASP Agentic Top 10 (2026) — COMPLETE, 10 of 10 at full-tier.** The scanner was moved off the older OWASP-LLM A0x numbering onto the canonical Agentic ASI-0x items, each as a full-tier build (lib + scanner analyzer + registration manifest flag + dashboard + tests + Shield review). **All 10 merged to main:** ASI-01 Prompt Injection / Goal Hijack (`SemanticInjectionClassifier` — paraphrased indirect injection via injectable embeddings + cosine vs intent catalog, #1500), ASI-02 Tool Misuse, ASI-03 Identity & Privilege Abuse, ASI-04 Agentic Supply Chain (`generateAiBom` AI-BOM + SLSA/in-toto provenance with deterministic `bomHash`, #1501), ASI-05 Unsafe Code Execution (`evaluateSandboxedCommand` shell-sandbox: binary allowlist / no-network / no-priv-esc / path-confinement / injection-deny, #1503), ASI-06 Memory & Context Poisoning (`ContextWindowHasher` in-session context-integrity + keyed-HMAC persistent memory, #1496), ASI-07 Insecure Inter-Agent Communication (per-message Ed25519 `AgentMessageEnvelope` signing inherited by all 16 orchestrator adapters, #1493), ASI-08 Cascading Failures (CircuitBreaker in PreToolUse by default + per-agent kill-switch), ASI-09 Human-Agent Trust (`scoreOversight` oversight-effectiveness / rubber-stamp detection, #1502), ASI-10 Rogue Agents (operator hard-suspend API, proxy-tier + SDK-path zero-caveat). Parity matrix: `docs/decisions/owasp-agentic-AGT-parity-matrix-2026-05-29.md`.
  - **10-ASI coverage model (Trust Score build-axis correctness)** — `scanAgent` reports per-ASI-item coverage (`asiCoverage[]`, `asiAssessedCount`, `coverageComplete`). An item with no analyzer is reported `assessed:false`, never folded into "passed" — so a build-axis band can be **coverage-gated** ("Gold across the 10 AGTs" requires all 10 actually evaluated) instead of implying coverage it doesn't have. With ASI-05 merged, a fully-controlled agent now scans **`asiAssessedCount: 10`, `coverageComplete: true`** — the build axis is honestly assessed across all 10 canonical Agentic items.
  - **Platform-wide unauthenticated-route remediation — 32 routes closed** (PRs #1493/#1494/#1495, merged). A codebase-wide sweep found the governance-server `Router` has no global auth middleware (auth is per-handler); a single `PATCH /agents/:id/profile` gap expanded to **2 CRITICAL** (anonymous agent lifecycle `transition`; anonymous HIPAA `baa`-status falsification), plus HIGH mutation routes and **18 read routes** leaking tenant-scoped data unauthenticated (incl. the HIPAA §164.528 disclosure-accounting report, execution traces, full agent records, cross-tenant usage/cost). All closed with `requireOrgAdmin`/`requireOrgViewer` + cross-tenant `orgId`/`tenantId` RLS (Invariants 6/7), claims-driven (no hard-coded orgs). Sidecar push-ingestion routes (Invariant 10) tracked for per-agent service tokens as a Phase-E item.
  - **Trust Score spec** (`docs/decisions/2026-05-29_trust-score-SPEC.md`) — the 5-component base score: (1) build vs OWASP/AGT, (2) runtime vs company-pack rules, (3) compliance-pack coupling, (4) rule-following, (5) human-input compliance (catch human-error compliance breaks). Two hard rules: coverage-gated bands + versioned methodology.
- **2026-05-26 — OWASP Agentic Top 10 + Trust Score Report + RFC 3161 build plan: 36 PRs merged across 4 tiers**:
  - **BUNDLE-B1**: 15 prompt-injection patterns (AGENT-TRAP-{001,003,004,008,009} + INSTR-OVERRIDE-{001-005} + AUTH-ESC-{001-003} + EXFIL-{001-003}) extended to cover `['user', 'tool']` roles — catches the keyword-based payloads in the DeepMind workspace-file research. Hedge: pattern-based detection; novel semantic-equivalent payloads without trigger keywords may still pass.
  - **OWASP-B1-B6**: Scanner schema extension + `owasp-agentic-scanner.ts` integration into gap-report + CLI license-state remediation + Step3 mandatory gate + onAgentRegistered hook + audit-chain `owasp_category` tagging + posture query layer
  - **OWASP-B7-B8**: Pre-injection baseline + post-activation rescore Trust Score reports with 12-dimension Trust Genome (Fairness, Identity, Security, Oversight, Behavioral, Compliance, Resilience, Performance, Transparency, Authorization, Accountability, Data Integrity) + Financial Exposure + Insurance Gap
  - **AXIS-B1-B6**: 4th Trust Score axis (interaction) + FourAxisCard dashboard + PublicAgentView cross-org extension
  - **RFC-B1-B6**: RFC 3161 TSA env config + `Rfc3161TrustAnchorSink` + schema_v3 + public verify endpoint + SDK helper + dashboard badge
  - **BUG-QA-002**: `PATCH /api/v1/onboarding/journey` route + journey_type/install_track unconflation (migration applied to Postgres-SY7j)
- 2026-05-25 — Beta-tester comp coupons live: `BETA_FULL_ACCESS_3MO` + 10 single-use promo codes (90-day redemption, 3-month full access, then auto-convert to full price)
- 2026-05-25 — Layer 3 pack-content-hash gate fully closed (PRs #1357 + #1359)
- 2026-05-25 — Dashboard `/docs` portal live (8 sections) + public `my-cc.io/docs` mirror (install, register-agent, troubleshooting)
- 2026-05-25 — Pack distinction explainer + competitor comparison pages (vs Credo AI / Collibra / IBM watsonx) live
- 2026-05-24 — Stripe LIVE launch + Wave 3+4 (purchasedPackIds in JWT + tier upgrade re-mint + Hospital pack integration)
- 2026-05-22 — PII Shield v1 phase-gate fully closed + gate production-wired (POST /api/v1/agents + onboarding wizard); 7 src/ runtime callers

```bash
npx @connexum/ai-governance@latest init --vendor-code <YOUR_CODE>
```

That single command installs the runtime into the current project, exchanges your vendor code for a 1-year service token bound to your tenant, and wires 14 hook scripts into `.claude/hooks/` so every tool call your AI agent makes is intercepted before execution.

## Credit Agency for AI Agents

Equifax, TransUnion, and Experian do for human credit what My Compliance Center does for AI agents. The platform is the credit bureau. The Trust Score is the credit score. The Gold / Silver / Bronze Trust Signature is the credit-bureau seal. The Insurance and Compliance Report is the credit report. The Sovereignty Certificate is the regulatory credential. The Behavioral Signal ledger is the credit-history database. The Connector SDK and certified third-party plugins are how reporting data flows in.

**AI Trust Score.** Every governed agent accumulates a composite Trust Score on a 0-100 scale, computed continuously across three weighted axes. The score feeds a Trust Signature tier seal that any org can display or query:

| Tier | Threshold | Meaning |
|------|-----------|---------|
| Gold | composite >= 85 | Top-tier standing — sustained policy compliance, clean behavioral record, full build verification |
| Silver | composite >= 70 | Good standing — minor gaps or limited signal history |
| Bronze | composite >= 50 | Passing — active governance in place, early-stage signal accumulation |
| Unrated | composite < 50 | Insufficient signal or open compliance issues; no seal issued |

**Three-axis weighted scoring.** The composite is a blend of three independently computed dimensions. Weights default per pack profile; each org can supply its own weighting overrides when their regulatory context demands it (for example, a regulator that weights operator review activity higher, or an insurer that weights build structure higher for under-tested fleets).

1. **Agent Activity** — runtime behavioral signals: scope adherence, policy compliance rate, anomaly rate, incident history, and behavioral consistency across tool calls.
2. **Operator Activity** — human oversight signals: out-of-scope ingestion rate, scope violations by team, scope violations by data class, and human override frequency. This axis participates in the composite only when the agent declares human-in-the-loop (`has_human_in_loop: true`); agents without human review are scored on the remaining two axes so they are not structurally penalized for a dimension that does not apply.
3. **Agent Build Structure** — scan-time configuration signals: OWASP agentic score, hook coverage (pre-tool / post-tool / post-response), declared capability classes, human-in-loop gates, plugin integrity verification, and proxy routing status.

The composite score is recomputed on every meaningful input change — a new manifest, new audit entries, or a new human-review outcome — and emitted as a `TRUST_SCORE_UPDATED` event on the audit chain for real-time dashboard streaming.

**Pricing model (LIVE on Stripe 2026-05-24).** Two-layer pricing:

1. **Company Pack on-ramp**: **$3 / agent / month** (or annual equivalent with 10% off via `ANNUAL10_ALL` at checkout). Includes runtime governance, dashboard, audit chain, single-pack enforcement.
2. **Vertical Group Packs**: **$1,000 / pack** capped at **$7,000** total (4-pack $4k / 5-pack $5k / 6-pack $6k / 7+-pack $7k). At cap, the full 156-pack catalog unlocks. SOC 2 + GDPR + ISO 27001 bundle FREE with every Vertical Group Pack purchase.
3. **Add-ons**: $400 per additional pack after group purchase.
4. **Hard billing cap**: $7,000 / org / year.

**Categorical vertical floors** (Thomas 2026-05-24): Mental Health = 6-pack/$6k. Healthcare/Hospital = 7-pack/$7k. Financial Services = 6-pack/$6k.

**Beta-tester comp** (active through 2026-08-23): 10 single-use promo codes (`BETA_FULL_ACCESS_3MO`) give 100% off for 3 billing months, then auto-convert to full price.

## The Problem

Your AI agents can read files, execute code, and access sensitive data. Without governance, a single misconfigured agent is a compliance violation waiting to happen. Regulators do not accept "we told the AI not to" as a control.

## What This Package Does

@connexum/ai-governance intercepts every tool call your AI agents make and enforces policy **before execution**. Unauthorized actions are blocked, not logged after the fact. The SDK wraps any LLM platform (Claude, OpenAI, Gemini, DeepSeek, Microsoft, Amazon) or orchestrator (Paperclip, CrewAI, AutoGen, LangGraph) with rule-based governance, compliance pack validation, and tamper-proof audit trails. Default-deny enforcement means nothing runs without an explicit allow rule.

## Installation

Public on the npm registry — no `.npmrc` auth, no GitHub token. Node.js 18 or higher is required.

The runtime is harmless without a vendor code; what binds it to your tenant is the one-time vendor code from the [signup wizard](https://app.my-cc.io/start).

```bash
# Option A — install + initialize in one command (recommended for new projects)
npx @connexum/ai-governance@latest init --vendor-code cxni_v1_XXXXXXXXXXXXXX

# Option B — let your AI assistant install it for you (no-terminal path)
# Open the /onboarding wizard at https://app.my-cc.io and click
# "Let your AI assistant install it" — paste the generated prompt into
# Claude Code / Cursor / Copilot Chat / ChatGPT.

# Option C — explicit two-step
npm install @connexum/ai-governance
npx @connexum/ai-governance init --vendor-code cxni_v1_XXXXXXXXXXXXXX
```

## Quick Start (SDK usage)

If you would rather call the SDK directly instead of running the hook installer:

```typescript
import { createGovernedAgent, createActionContext } from '@connexum/ai-governance';

const agent = createGovernedAgent({
  name: 'research-assistant',
  platform: 'claude', // or 'openai' (pending platform testing)
  packs: ['soc2', 'hipaa'],
  rules: [
    { tool: 'Read', decision: 'allow', reason: 'File reads permitted' },
    { tool: 'Bash', decision: 'deny', reason: 'Shell access prohibited' },
    { tool: 'Write', decision: 'require_approval', reason: 'Writes need review' },
  ],
});

const decision = await agent.execute(
  createActionContext('Bash', { command: 'rm -rf /' }, { name: 'research-assistant' })
);

console.log(decision); // { type: 'DENY', reason: 'Shell access prohibited' }
```

## Setup

**Single canonical entry point for all setup: [`docs/SETUP.md`](./docs/SETUP.md).** It covers customer integration (SDK + connector + hosted proxy + browser extension + endpoint scanner), Claude Code setup (hooks + Tier 8.7 sub-agents), claude.ai / remote MCP setup, IDE setup (VS Code / JetBrains / Cursor), and building the application from source.

For production deployment: [`docs/RAILWAY_DEPLOYMENT_PLAN.md`](./docs/RAILWAY_DEPLOYMENT_PLAN.md).

## Repository Structure

```
@connexum/ai-governance (monorepo)
|
+-- src/                          Core governance SDK
|   +-- governance/               Runtime, bias monitor, policy tuning, partner manager
|   +-- adapters/                 Platform + orchestrator adapters
|   +-- security/                 Encryption, data classification, tamper detection
|   +-- packs/                    Compliance pack definitions (156 packs; full catalog: docs/PACK_CATALOG.md)
|   +-- audit-bots/               Automated audit scheduling
|   +-- reporting/                Governance event reporter (SaaS streaming)
|   +-- cli/                      npx @connexum/ai-governance init
|
+-- packages/
|   +-- governance-server/        REST API sidecar (HTTP + WebSocket)
|   |   +-- src/                  60+ route modules, event store, RBAC, rate limiting
|   |   +-- tests/                278+ tests (TAP format, node:test)
|   |
|   +-- auth/                     JWT auth service (register, login, RBAC, MFA/TOTP)
|   +-- connector-sdk/            Three-line integration SDK (LangChain/CrewAI/AutoGen/OpenAI Agents)
|   +-- database/                 Prisma schema + PostgreSQL storage adapter
|   +-- governance-proxy/         LLM-call proxy with HTTP evaluator
|   +-- license-server/           License key validation and management
|   +-- mcp-server-trust/         MCP transport for cross-org passport lookup
|   +-- python-sdk/               Python client for LangGraph, CrewAI, AutoGen
|   +-- scoring/                  Python statistical scoring service (advisory, Invariant 2)
|   +-- trust-api/                Trust & Sovereignty API (passport issuance + cross-org lookup)
|   +-- typescript-sdk/           TypeScript SDK with adapter wrappers
|
+-- apps/
|   +-- dashboard/                Next.js web dashboard (My Compliance Center)
|       +-- src/app/(dashboard)/  20 customer routes (agents, compliance, trust-score, etc.)
|       +-- src/components/       Sidebar, command palette, ThreeAxisCard, TrustSignatureBadge
|       +-- src/lib/              API client, auth context, scoring-api, audit-chain SSE
|
+-- tests/                        1,025 core SDK tests
+-- docs/                         Architecture docs, build plans, strategy
+-- examples/                     Demo enforcement scripts
```

## Features

**Enforcement**
- Default-deny governance. Every tool call requires an explicit allow rule.
- Pre-action blocking. Unauthorized actions never execute.
- Circuit breaker with automatic agent suspension on anomaly detection.
- Human-in-the-loop approval queue with timeout and HMAC-verified decisions.
- Session timeout enforcement with HIPAA/PCI presets.
- Agent lifecycle management (registered, shadow testing, active, suspended, under review, decommissioned).

**Compliance Packs (156 packs across 30+ jurisdictions)**

The runtime registry exports 156 compliance packs out of the box. Activate any subset via `packs: ['hipaa', 'soc2', ...]` when constructing your governed agent. Each pack ships pre-built classifiers, retention policies, incident workflows, and validators for its framework.

<details>
<summary><b>Click to expand: representative pack catalog (full list: docs/PACK_CATALOG.md)</b></summary>

#### AU (13 packs)

| Pack ID | Name |
|---|---|
| `au-aiethics-framework` | Australia AI Ethics Framework + Voluntary AI Safety Standard |
| `au-aml-ctf` | AML/CTF Act 2006 + 2024 DNFBP Amendments |
| `au-asic-rg-271` | ASIC RG 271 Internal Dispute Resolution |
| `au-asic-rg-274` | ASIC Design and Distribution Obligations (DDO) |
| `au-cdr` | Consumer Data Right (CDR) Act 2019 |
| `au-cps230` | APRA CPS 230 Operational Risk Management |
| `au-cps234` | APRA CPS 234 Information Security |
| `au-mandatory-ai-guardrails` | DISR Mandatory AI Guardrails (Proposals Paper Sep 2024) |
| `au-online-safety` | Online Safety Act 2021 (Cth) |
| `au-privacy-act` | Australian Privacy Act 1988 (Cth) — APPs + NDB |
| `au-soci-act` | Security of Critical Infrastructure Act 2018 |
| `au-spam-act` | Spam Act 2003 (Cth) |
| `au-tga-saimd` | TGA Software as a Medical Device (SaMD) |

#### AU-ACT (1 pack)

| Pack ID | Name |
|---|---|
| `au-act-hrpaa` | ACT Health Records (Privacy and Access) Act 1997 (HRPAA) |

#### AU-NSW (1 pack)

| Pack ID | Name |
|---|---|
| `au-nsw-hripa` | NSW Health Records and Information Privacy Act 2002 (HRIPA) |

#### AU-VIC (1 pack)

| Pack ID | Name |
|---|---|
| `au-vic-hra` | VIC Health Records Act 2001 (HRA) |

#### Brazil (1 pack)

| Pack ID | Name |
|---|---|
| `lgpd` | LGPD (Brazil) |

#### Canada (1 pack)

| Pack ID | Name |
|---|---|
| `ca-pipeda` | PIPEDA (Canada — Federal) |

#### Canada (Quebec) (1 pack)

| Pack ID | Name |
|---|---|
| `ca-qc-law25` | Quebec Law 25 |

#### China (1 pack)

| Pack ID | Name |
|---|---|
| `pipl` | PIPL (China) |

#### EU (5 packs)

| Pack ID | Name |
|---|---|
| `dora` | Digital Operational Resilience Act |
| `eu-ai-act` | EU AI Act |
| `eu-ai-liability` | EU AI Liability (PLD 2024) |
| `gdpr` | General Data Protection Regulation |
| `mifid2` | MiFID II / MiFIR |

#### Global (4 packs)

| Pack ID | Name |
|---|---|
| `iso_42001` | ISO/IEC 42001 |
| `iso-23894` | ISO/IEC 23894 (AI Risk Management) |
| `iso27001` | ISO/IEC 27001 |
| `pci-dss` | Payment Card Industry Data Security Standard |

#### Global (FDA, EMA, ICH) (1 pack)

| Pack ID | Name |
|---|---|
| `gxp` | GxP (GMP/GLP/GCP) |

#### Global (HK/UK primary) (1 pack)

| Pack ID | Name |
|---|---|
| `lpo2024` | LPO 2024 AI Disclosure (Legal Practitioners) |

#### Japan (1 pack)

| Pack ID | Name |
|---|---|
| `appi` | APPI (Japan) |

#### US (33 packs)

| Pack ID | Name |
|---|---|
| `bsa-aml` | BSA / AML |
| `cfpb-2023-03` | CFPB Circular 2023-03 |
| `cjis` | CJIS Security Policy v5.9.5 |
| `cmmc2` | CMMC 2.0 (Level 2) |
| `common-rule` | Common Rule (Human Subjects Research Protection) |
| `coppa` | COPPA (Children's Online Privacy Protection Act) |
| `ecoa` | ECOA / Regulation B (Equal Credit Opportunity Act) |
| `fcra` | Fair Credit Reporting Act |
| `fda-samd` | FDA SaMD (AI/ML) |
| `fedramp` | FedRAMP (Rev 5) |
| `ferpa` | FERPA (Student Privacy) |
| `foia` | FOIA (5 USC 552) |
| `frcp26` | FRCP Rule 26 (E-Discovery) |
| `ftc5` | FTC Act §5 |
| `glba` | Gramm-Leach-Bliley Act |
| `hipaa` | Health Insurance Portability and Accountability Act |
| `hitech` | HITECH Act |
| `hmda` | Home Mortgage Disclosure Act |
| `naic-mdl` | NAIC MDL-668 (Insurance Data Security) |
| `nist_ai_rmf` | NIST AI Risk Management Framework |
| `part2` | 42 CFR Part 2 (SUD Records) |
| `soc2` | SOC 2 Type II |
| `sox404` | SOX 404 |
| `sr11-7` | SR 11-7 Model Risk Management |
| `title-ix` | Title IX (Sex Discrimination in Federally-Funded Education) |
| `us-fda-21cfr56` | FDA 21 CFR Part 56 (IRB Regulations) |
| `us-nih-coc` | NIH Certificate of Confidentiality Policy |
| `us-nih-dms` | NIH Data Management and Sharing Policy (2023) |
| `us-nih-gds` | NIH Genomic Data Sharing Policy |
| `us-nih-it-security` | NIH IT Security Policy (FISMA Moderate) |
| `us-respa` | Real Estate Settlement Procedures Act |
| `us-tila` | TILA / Regulation Z (Non-TRID Provisions) |
| `us-trid` | TRID (TILA-RESPA Integrated Disclosure) |

#### US (California) (1 pack)

| Pack ID | Name |
|---|---|
| `ccpa` | CCPA / CPRA |

#### US (Colorado) (1 pack)

| Pack ID | Name |
|---|---|
| `colorado-ai` | Colorado AI Act |

#### US (FDA); EU Annex 11 equivalent (1 pack)

| Pack ID | Name |
|---|---|
| `part11` | 21 CFR Part 11 |

#### US (Florida) (1 pack)

| Pack ID | Name |
|---|---|
| `florida-student-privacy` | Florida Student Privacy (State Overlay) |

#### US (ISAE 3402 international equivalent) (1 pack)

| Pack ID | Name |
|---|---|
| `soc1` | SOC 1 / SSAE 18 |

#### US (Illinois, extraterritorial) (1 pack)

| Pack ID | Name |
|---|---|
| `bipa` | Illinois BIPA |

#### US (New York City) (1 pack)

| Pack ID | Name |
|---|---|
| `nyc-ll-144` | NYC LL 144 (AEDT Bias Audit) |

#### US (New York) (1 pack)

| Pack ID | Name |
|---|---|
| `nydfs500` | NY DFS 23 NYCRR Part 500 |

#### US (state bar adoption varies) (1 pack)

| Pack ID | Name |
|---|---|
| `aba` | ABA Model Rules (Opinion 512) |

#### US (state) (1 pack)

| Pack ID | Name |
|---|---|
| `stateramp` | StateRAMP |

</details>

Pack registry capabilities: activation, composition, shadow mode (test new policies without blocking), scoring, policy history timeline, automated JSON compliance report generation.

Full per-pack descriptions: [`docs/PACK_CATALOG.md`](./docs/PACK_CATALOG.md).

**Multi-LLM Adapter Architecture**
- Claude adapter is production-verified today. OpenAI, Gemini, DeepSeek, Microsoft, and Amazon adapters are interface-level and pending platform testing (see ROADMAP).
- Orchestrator adapters for Paperclip, CrewAI, AutoGen, and LangGraph.
- Python SDK (`connexum-governance`) with native integrations.
- Agent identity verification via HMAC-SHA256 tokens.

**Dashboard (19 Routes)**
- Fleet overview with real-time WebSocket event streaming.
- Agent profiles with health metrics, drift detection, and lifecycle controls.
- Risk heat map with drill-into detail panels.
- Compliance center with pack validation, evidence bundles, and report generation.
- BAA tracker for HIPAA Business Associate Agreement management.
- Vendor/provider compliance aggregation across platforms.
- Bias monitor (EU AI Act Art. 9) with OOD detection.
- State-level regulatory tracker (8 US state AI laws seeded).
- Governance maturity self-assessment scorecard (5 dimensions, 20 questions).
- Scheduled report delivery (daily/weekly/monthly/quarterly).
- Budget management with threshold-based alerts and projections.
- Audit log with full-text search, filtering, and pagination.
- Approval queue with real-time notifications.
- Settings (org, users, webhooks, notifications).
- Global search (Cmd+K) across agents and routes.
- Dynamic breadcrumbs and status bar.

**Audit**
- Tamper-proof audit chains with SHA-256 hash-linked entries.
- Chain verification endpoint for integrity checks.
- Evidence bundle generation with cryptographic proof.
- SIEM integration via webhooks (Splunk HEC, Datadog, Elastic, syslog RFC 5424).
- Event bus with typed event streaming.

**Security**
- AES-256-GCM encryption at rest with key versioning and rotation.
- SHA-256 tamper detection on governance configuration.
- SSRF guard on all outbound requests.
- Rate limiting on auth and governance endpoints.
- Input validation on all API payloads.
- CORS scoped to configured origins (not wildcard).
- JWT auth with refresh tokens and RBAC (viewer, operator, org_admin, super_admin).
- Cross-agent anomaly correlation.

**EU AI Act**
- Art. 5 prohibited practices detection.
- Art. 9 bias monitoring with chi-square analysis and out-of-distribution detection.
- Art. 13/50 transparency injection and content labeling.
- Art. 72 post-market performance monitoring and drift alerts.

## Compliance Packs

| Pack | Framework | Coverage |
|------|-----------|----------|
| `hipaa` | HIPAA | PHI detection, access audit trails, encryption requirements, BAA tracking, breach notification (60-day) |
| `soc2` | SOC 2 Type II | Access controls, audit logging, change management, incident response |
| `gdpr` | GDPR | Data subject rights (Art. 15-22), PII classification, retention policies, 72-hour breach notification |
| `pci-dss` | PCI DSS | PAN detection, encryption validation, access restrictions, transaction audit |
| `eu-ai-act` | EU AI Act | Risk classification, prohibited practices, transparency obligations, post-market monitoring |
| `iso27001` | ISO 27001 | Information security controls, risk assessment, access management, incident handling |
| `dora` | DORA | ICT risk management, incident reporting (4-hour), resilience testing, third-party oversight |
| `nist_ai_rmf` | NIST AI RMF | AI risk management, governance, mapping, measurement, management functions |
| `iso_42001` | ISO 42001 | AI management systems, responsible AI, organizational AI governance |

## Governance Server API

The governance server runs as an HTTP sidecar on port 3200 (configurable). Key endpoint groups:

| Group | Endpoints | Purpose |
|-------|-----------|---------|
| Governance | `check-action`, `check-task`, `check-plan`, `check-delegation` | Real-time policy enforcement |
| Agent Registry | CRUD, transitions, risk assessment, BAA, vendor aggregation | Agent lifecycle management |
| Compliance | Pack listing, validation, shadow mode, policy history | Framework compliance |
| Events | Search, stats, batch ingestion | Audit trail and analytics |
| Reports | Evidence bundles, compliance reports, scheduled delivery | Compliance reporting |
| Bias | Sample recording, assessment, OOD detection | EU AI Act Art. 9 |
| Regulatory | State law tracking, deadlines, agent-state mappings | US state AI law compliance |
| Budgets | Configuration, status, alerts, acknowledgment | Cost governance |
| Settings | Org, users, webhooks, notifications | Platform configuration |
| Auth | Register, login, refresh, RBAC | Identity and access |

## Python SDK

```bash
pip install connexum-governance
```

```python
from connexum_governance import GovernanceClient

client = GovernanceClient(base_url="http://localhost:3200")

decision = client.check_action(
    tool_name="execute_query",
    agent_name="data-analyst",
    input_data={"query": "SELECT * FROM users"}
)

if decision.allowed:
    # proceed with tool execution
    pass
```

Integrations for LangGraph, CrewAI, and AutoGen are included. See `packages/python-sdk/README.md`.

## Architecture

Three enforcement layers run on every agent tool call.

1. **Ingress** classifies inbound data and redacts / refuses PHI, PII, or PAN per the active pack. (`src/classification/`)
2. **Verification** verifies the on-disk governance policy against a SHA-256 manifest, enforces the per-agent tool allowlist, and enforces per-cycle token / time / cost budget. (`src/governance/governance-runtime.ts`)
3. **Egress** runs the **Nine Guards** on every outbound action. See [`docs/NINE-GUARDS.md`](./docs/NINE-GUARDS.md) for the canonical guard-by-guard reference.

**The Nine Guards (egress):**

| # | Guard | Fires on | Default verdict |
|---|---|---|---|
| 1 | Data Exfiltration Scanner | PHI / PII / PAN in output | BLOCK |
| 2 | Secret Leak Scanner | API keys, tokens, credentials in output | BLOCK |
| 3 | File Boundary Guard | Path traversal, governance-file writes | BLOCK |
| 4 | Destructive Command Guard | `rm -rf`, `DROP TABLE`, force-push | BLOCK |
| 5 | Web Access Gate | Disallowed host, SSRF, private-range | BLOCK |
| 6 | Cost and Budget Guard | Token / time / USD cap exceeded | BLOCK |
| 7 | Prohibited-Practices Guard | EU AI Act Art. 5, ECOA bases, pack forbidden | BLOCK |
| 8 | Confidence Gate | Confidence below pack floor | BLOCK or ROUTE_TO_APPROVAL |
| 9 | Approval Queue (HITL T2) | Flagged or mandatory-review action | WAIT for named reviewer |

Every guard outcome, allow or block or route, writes a SHA-256-linked event to the audit chain with `guardId`, `reasonCode`, `verdict`, `packBinding`, `retentionTier`, `prevHash`, and an HMAC signature.

**Deployment view:**

```
Your Agent Code (any language)
      |
      v
Governance Server (HTTP sidecar, port 3200)
      |
      +-- GovernedAgent engine (rules, packs, audit)
      +-- Platform Adapters (Claude, OpenAI, Gemini, etc.)
      +-- Orchestrator Adapters (Paperclip, CrewAI, AutoGen, LangGraph)
      +-- WebSocket server (real-time event streaming)
      +-- Event Store (in-memory or PostgreSQL)
      |
      v
Dashboard (Next.js, port 3000)
      |
      +-- 19 routes: agents, compliance, risk, audit, approvals, settings, budgets
      +-- Real-time updates via WebSocket
      +-- All data from API (zero hardcoded mock data)
```

## Development

```bash
# Install dependencies
npm install

# Run core tests (1,025 tests)
npx tsx --test tests/*.test.ts

# Run governance server tests (590 tests, includes 11 pentest suites)
npx tsx --test packages/governance-server/tests/*.test.ts

# Run auth tests (45 tests)
npx tsx --test packages/auth/tests/*.test.ts

# Run license server tests (9 tests)
npx tsx --test packages/license-server/tests/*.test.ts

# Build dashboard
cd apps/dashboard && npx next build

# Start governance server
cd packages/governance-server && npx tsx src/index.ts

# Start dashboard dev server
cd apps/dashboard && npx next dev
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORT` | No | `3200` | Governance server port |
| `API_TOKEN` | No | (empty) | Bearer token for API auth |
| `JWT_SECRET` | Yes (32+ chars) | (empty) | JWT signing secret. Must be distinct from all other secrets. |
| `TRUST_ANCHOR_HMAC` | Yes (32+ chars) | (empty) | HMAC key for audit-chain trust anchors. Must be distinct from all other secrets. |
| `ENCRYPTION_KEY` | Yes (32+ chars) | (empty) | AES-256-GCM master key for at-rest encryption. Must be distinct from all other secrets. |
| `APPROVAL_SECRET` | Required if any pack uses `approval-queue` | (empty) | HMAC key for HITL approval tokens. Boot fails if required but absent or under 32 chars. Must be distinct from all other secrets. |
| `LLM_LIST_REFRESH_KEY` | Yes (32+ chars) | (empty) | HMAC key for `DestinationsRefreshManager`. Boot fails if absent or under 32 chars. Must be distinct from all other secrets. |
| `DESTINATIONS_HMAC_SECRET` | Required for on-demand refresh | (empty) | HMAC key to verify incoming LLM manifest signatures. |
| `DESTINATIONS_MANIFEST_URL` | Required for on-demand refresh | (compile-time value) | URL of the signed destination manifest. Compile-time only, no runtime override. |
| `DESTINATIONS_STALE_THRESHOLD_MS` | No | `86400000` | Milliseconds before destination list is flagged stale. |
| `DATABASE_URL` | No (required for Phase 2A) | (empty) | PostgreSQL connection string. |
| `HIPAA_MODE` | No | `false` | Enforce HIPAA session timeouts (15-min). |
| `DEFAULT_DENY` | No | `true` | Block unmatched tool calls. |
| `HITL_ENABLED` | No | `true` | Enable human-in-the-loop approvals. |
| `ALLOWED_ORIGINS` | No | `localhost:3000,3100` | CORS allowed origins. |
| `NEXT_PUBLIC_API_URL` | No | `http://localhost:3200` | Dashboard API base URL. |

> **Secret distinctness rule (enforced at boot):** `JWT_SECRET`, `TRUST_ANCHOR_HMAC`, `ENCRYPTION_KEY`, `APPROVAL_SECRET`, and `LLM_LIST_REFRESH_KEY` must all be distinct values. The server refuses to start if any two of these five secrets share the same value.

## Test Summary

| Package | Tests | Status |
|---------|-------|--------|
| Core SDK (`tests/`) | 1,025 | Passing |
| Governance Server | 295 | Passing |
| Auth Service | 45 | Passing |
| License Server | 9 | Passing |
| **Total** | **1,374** | **All passing** |

## Dashboard Routes

| Route | Description |
|-------|-------------|
| `/` | Fleet overview with summary cards and event feed |
| `/agents` | Agent list with status, platform, risk tier |
| `/agents/[id]` | Agent profile with health, drift, governance, transitions |
| `/agents/registry` | Agent registration wizard |
| `/risk` | Risk heat map with drill-into panels |
| `/compliance` | Compliance center with pack scores and report generation |
| `/compliance/baa` | BAA tracker with inline status editing |
| `/compliance/bias` | Bias monitor (EU AI Act Art. 9) |
| `/compliance/vendors` | Vendor/provider compliance aggregation |
| `/compliance/maturity` | Governance maturity self-assessment |
| `/compliance/schedules` | Scheduled report delivery configuration |
| `/compliance/regulatory` | US state AI law tracker |
| `/budgets` | Budget management with alerts and projections |
| `/approvals` | Approval queue with real-time updates |
| `/audit` | Audit log with search and filtering |
| `/settings` | Org, users, webhooks, notifications |
| `/login` | Authentication |

## Pricing (LIVE on Stripe)

Two-layer model. Hard cap **$7,000 / org / year**. SOC 2 + GDPR + ISO 27001 bundle FREE with every Vertical Group Pack purchase.

| Tier | What's included | Price |
|------|------------------|-------|
| Free Scanner | Trust Score readout only — no full report, no enforcement | $0 |
| **Company Pack** (on-ramp) | Runtime governance, dashboard, audit chain, single-pack enforcement | **$3 / agent / month** (annual: 10% off via `ANNUAL10_ALL`) |
| Vertical Group Pack (4-pack) | Four packs in one vertical (e.g., Mental Health) | $4,000 / yr |
| Vertical Group Pack (5-pack) | Five packs in one vertical | $5,000 / yr |
| Vertical Group Pack (6-pack) | Six packs (Mental Health / Financial Services floor) | $6,000 / yr |
| **Vertical Group Pack (7+ pack)** | Seven or more packs (Healthcare/Hospital floor); **full 156-pack catalog unlocks at cap** | **$7,000 / yr** (cap) |
| Add-on pack | Additional pack after group purchase | $400 / pack |

**Beta-tester comp (active through 2026-08-23):** 10 single-use promo codes `BETA_FULL_ACCESS_3MO` give 100% off for the first 3 billing months, then auto-convert to full price. Contact [sales@my-cc.io](mailto:sales@my-cc.io) for a code.

The $7,000/yr ceiling means no surprise scaling bill — once you reach the cap you unlock everything; the price never moves up.

## Roadmap — Future Ideas (Above-the-Floor governance modules)

Beyond the compliance-pack "floor", a durable backlog of seven dependency-ordered
governance modules is captured in the **Future Ideas Register**
(`docs/decisions/FUTURE_IDEAS_REGISTER.md`), with full specs in
`docs/decisions/above-the-floor-governance-modules-SPECS.md`. These are
**captured, not yet approved for build** — each passes a gated intake before any
code is written.

**Intake process (capture → review → park or build):**
1. **Capture** — log the idea in the register with a one-line summary, source, and status.
2. **Pre-build review (3 lenses)** — Kai (Lead Engineer, feasibility vs the actual codebase) + Shield (CISO, security/compliance/tenant-isolation/claim-liability) + Devil's Advocate (kill questions: real buyer? dilutes the core?).
3. **Decision doc** — synthesize the three into a dated decision marked *Approved* or *Not approved for build*, with explicit gating conditions.
4. **Build plan** — if worth it later, a sliced plan with mandatory controls baked in (still not a work order until greenlit).
5. **Park or build** — parked ideas record the concrete *condition that unparks them* so they're revisited deliberately, not lost.

**The seven Above-the-Floor modules (dependency-ordered):**
1. **Model Provenance Pinning + Auto Re-Attestation** — bind exact model identity (provider, version, output-affecting config, prompt/policy hash) to every governed decision; detect drift → flag prior attestations `stale_pending_review` and re-run.
2. **Counterfactual / Suppressed-Action Logging** — record what the agent was about to do and didn't (blocked actions, suppressed recommendations, near-misses) per decision — the malpractice-defense "why didn't it flag this" record.
3. **Consent-Scoped PHI Lineage** (HIPAA wedge) — prove an agent's PHI use stayed inside the specific patient consent (purpose, data categories, time window), not merely that access policy allowed it.
4. **Litigation-Grade Audit (Chain of Custody)** — tamper-evident hash-chain + offline-verifiable evidence packages per decision/patient (consumes modules 1–3).
5. **Human-Oversight Effectiveness Scoring** — measure whether a reviewer exercised judgment, not just that a human was present (EU AI Act Art. 14); rubber-stamp detection.
6. **Pre-Deployment Regulatory Simulation** — dry-run a candidate agent against synthetic HIPAA / EU-AI-Act scenarios through the real policy engine before it touches production → predicted-risk report + launch gate.
7. **Insurer-Facing Risk Score Read-Model** (the "insurance report") — aggregate modules 1–5 into underwriting indicators + one versioned composite, seal each snapshot via module 4, and share only with the customer's explicit consent (module 3) — a verifiable evidence package, not a "trust our score" pitch.

A first register entry — **Governed AI Asset Inventory** — is currently **parked**
(unparks when the Trust Score is proven end-to-end with ~3 paying customers
carrying 60+ days of real audit data).

## Documentation

Full SDK reference, compliance guides, and integration tutorials at [docs.my-cc.io](https://docs.my-cc.io).

## License

SEE LICENSE IN [LICENSE.md](LICENSE.md)

Copyright 2026 Connexum Network Inc.
