Phase 012: Depth Audit — Crypto, Forensics, Connectors, MCP, Guardrails, Approvals, Memory, Cache

2026-03-12

cryptographyforensicsconnectorsmcpguardrailsapprovalsmemorysemantic-cache

What We Built

Phase 012 addresses depth audit gaps across 8 systems, covering all 13 spec iterations. The depth audit identified 7 PARTIAL areas where code existed but internals were hollow — stubs, silent fallbacks, or unwired integrations. Every area was either fixed or verified already fixed by prior phases.

Key fixes: HMAC-SHA256 audit signing with per-tenant key derivation, session timeline reconstruction from real event data, KMS envelope encryption for connector credentials (bearer/basic/OAuth2/api-key), OAuth2 token expiry tracking with 401 retry, unified approval queue with MCP tool handlers for agent-driven HITL workflows, guardrail metrics backed by security_events with per-scanner feedback summary, memory write-approval configuration API, and pgvector persistent semantic cache wired into the router via per-tenant factory pattern.

Why It Matters

Before this phase, features looked complete on the surface but had hollow internals. Audit trails weren't signed. Guardrail metrics vanished on restart. Connector credentials were stored in plaintext. MCP servers with expired OAuth tokens silently failed. The semantic cache existed only in-memory with no persistent backing. Approval workflows had no MCP surface for agents. Memory write-approval config had no API to set it. This phase ensures every feature meets the depth required for enterprise deployment.

How It Works

Cryptography (J): signAuditEntry() throws AuditSigningError when LOCAL_KEK_SECRET is not configured. Uses timingSafeEqual for constant-time comparison. Per-tenant key derivation via SHA-256(secret || "audit-hmac" || tenantId).

Forensics (L): Session timeline merges usage_events and security_events into chronological spans. Export produces HMAC-signed bundles; returns 503 when signing is unavailable. Replay comparison uses real endpoint stats from database, not synthetic multipliers.

Connectors (P): Credentials encrypted via KMS envelope (getEnvelopeEncryptionService). Test endpoint decrypts credentials and injects proper auth headers (bearer/basic/OAuth2/api-key). Custom header names supported via description hint.

MCP (C): OAuth2 client credentials grant with token expiry tracking (30s safety margin). 401 responses trigger token refresh + retry. Health polling at 5-minute intervals via mcp-service.ts.

Guardrails (D+G): Each scan writes a guardrail_scan event to security_events. Metrics endpoint aggregates from the database with per-scanner feedback summary (total, false_positives, false_negatives). Auth bridge mirrors main route behavior.

Approvals (O): Unified approval queue with deferred action execution. Actions execute before marking approved (502 on failure for safe retry). Three new MCP tools (br_list_pending_approvals, br_approve_request, br_reject_request) enable agent-driven HITL workflows with original caller context preservation.

Memory (K): Write-approval configuration exposed via GET/PUT /v1/memory/approval-config. Tenant-scoped ConfigStore backend. Approval records stored as approval:{id} in ConfigStore.

Semantic Cache (Q): SemanticCache now supports a PersistentStoreFactory pattern for pgvector-backed durable cache. On in-memory miss, falls through to per-tenant persistent store. Cache writes are dual-tracked (in-memory + fire-and-forget pgvector persist). Factory wired in model-router-init.ts with graceful degradation when Postgres is not configured.

The Numbers

13 of 13 spec iterations complete (5 already fixed by prior phases, 8 verified/implemented)
123+ tests passing across target test files
16 files modified across API, MCP, router, security, and docs
5 new MCP tools added to discovery surface (62 total)
2 new API endpoints for memory approval config

Competitive Edge

Every audited system now has real implementations behind its claims. The semantic cache has a persistent backing store. Approval workflows are agent-accessible via MCP. Memory governance is configurable via API. The evidence ledger is correctly documented as planned (not falsely claimed as shipped). No other AI gateway combines this level of operational depth across routing, memory, security, and agent governance.