Engineering Architecture

Developer & Systems Architecture

Architecture Decision Records (ADRs), Post-Quantum Cryptography engine specifications, Model Context Protocol (MCP) clients, and SDK quickstarts.

ADR-001: Decoupling of Reasoning Plane from Execution Plane

ACCEPTED2026-09-26
Context & Problem Statement:

Large Language Models and autonomous reasoning agents are non-deterministic and susceptible to prompt injection, hallucination, or adversarial payload generation. Directly granting LLMs database credentials, shell access, or raw API keys presents catastrophic security risks.

Architectural Decision:

We enforce strict architectural decoupling into three isolated planes: 1. Reasoning Plane (LLMs outputting only schema-validated ActionIntents), 2. Execution Plane (Action Gateway enforcing validation, tenant boundaries, blast radius, and risk tiers), and 3. Infrastructure Plane (internal microservices). No AI agent ever connects directly to infrastructure.

Consequences & Guarantees:

Guaranteed zero unauthorized mutations. Autonomous workflows can be safely enabled. Step-up authentication and human staff approval queues prevent destructive operational accidents.

ADR-002: Dual Post-Quantum Cryptography (PQC) Hybrid Mode

ACCEPTED2026-09-26
Context & Problem Statement:

Quantum computing advancements threaten classical public-key cryptography (RSA, ECC, Diffie-Hellman). Transitioning purely to experimental PQC algorithms introduces algorithmic regression risk.

Architectural Decision:

Adopt NIST FIPS 203 (ML-KEM-768) and FIPS 204 (ML-DSA-65) in dual hybrid mode alongside classical X25519 and Ed25519. Key exchange derives shared secrets via HKDF-SHA256 from both classical and post-quantum keys. Digital signatures require both Ed25519 and ML-DSA-65 validity.

Consequences & Guarantees:

Resilient against Store-Now-Decrypt-Later (SNDL) attacks. Full backwards compatibility with classical cryptographic hardware.

ADR-003: Model Context Protocol (MCP) as Exclusive External Integration Standard

ACCEPTED2026-09-26
Context & Problem Statement:

Integrating third-party SaaS services (GitHub, Slack, Datadog, Stripe) often leads to brittle web scraping or ad-hoc custom API integrations that violate terms of service.

Architectural Decision:

VaultHost mandates Model Context Protocol (MCP) for all external integrations. Zero scraping is permitted. VaultHost acts as an MCP Client connecting strictly via delegated OAuth tokens, and acts as an MCP Server exposing scoped cloud tools with embedded @risk_tier metadata.

Consequences & Guarantees:

Deterministic, permissioned interactions. User-granted delegation tokens ensure strict accountability and auditability.

ADR-004: Tamper-Evident Chained Audit Trail with HMAC-SHA256 & Merkle Proofs

ACCEPTED2026-09-26
Context & Problem Statement:

Cloud infrastructure audits require mathematical proof that historical logs have not been manipulated or truncated following security incidents.

Architectural Decision:

Every Action Gateway operation emits an audit entry cryptographically hashed and linked to the previous entry signature via HMAC-SHA256 and PQC signatures, creating an append-only verifiable ledger.

Consequences & Guarantees:

Meets SOC 2 Type II, ISO 27001, and FedRAMP high compliance standards. Instant mathematical detection of log tampering.

1