Executive Summary
The Air-Gapped AI Vault (Vault-OS) is an ultra-secure, multi-tenant Intelligence Platform engineered for "Absolute Zero" internet environments. It is designed to serve as a hardened, black-box cognitive appliance that runs large-language-model inference and retrieval-augmented generation entirely behind an air gap, with no internet egress by design. Every model executes locally against on-host accelerators.
This revision documents the platform through Phase 27.1.3, whose headline capability is the **Autonomous Workflow & Agent Engine (Agent DAG)**: a directed-acyclic-graph runtime that lets cleared operators compose local LLM agents, vector search, sandboxed code, and database actions into scheduled, event-driven automations—without ever breaching the air-gap.
Tech Stack Snapshot
Design Philosophy & Threat Posture
Vault-OS assumes a hostile environment: a stolen drive, a cloned VM image, a terminated insider with a still-valid token, or a compromised endpoint on the LAN. Every design decision answer defeats a specific adversary.
| Principle | Mechanism | Adversary Defeated |
|---|---|---|
| Air-Gapped | Local-only inference; internal-only workflow nodes; no telemetry phone-home; CORS anchored to localhost only. | Data exfiltration; cloud provider exposure. |
| Zero-Trust | Per-request JWT verify + DB status + `token_version` check; RBAC filtered retrieval; ephemeral dropzone storage. | Replayed tokens; terminated insiders; lateral movement. |
| Fail-Deadly | Absent `JWT_SECRET`, `AES_SECRET_KEY` or `AUDIT_PRIVATE_KEY` leads to immediate `process.exit(1)`. Decorators fail closed. | Misconfiguration; silent degradation. |
| Hardware-Tethered | SHA-256 fingerprint of machine UUID + MAC + TPM endorsement key checked against `LICENSE.vault` before services start. | Drive theft; image cloning; unlicensed redeployment. |
System Architecture
Vault-OS is a three-tier appliance: a React command console, a Fastify control plane, and a Postgres + pgvector knowledge store, fronting a pluggable local inference fabric. All tiers are co-residing on a single air-gapped host or isolated internal segment.
React 19 + Vite + Zustand single page application. Provides Vault chat, overseer panel, workflow DAG editor, and live SSE hardware monitor.
Fastify 5 (Node.js) HTTP API and hooks. Enforces RBAC decorators, manages RAG pipelines, executes the workflow DAG engine, and broadcasts HAL telemetry.
PostgreSQL with pgvector for AES-encrypted chunks. Pluggable inference fabric handles Ollama, vLLM, and TensorRT-LLM local model adapters.
Secure Boot & Hardware Tethering
Vault-OS does not start as a normal Node process. The entrypoint `index.js` is a **sealed bootloader** that performs hardware attestation and decrypts the environment in memory before a single line of server code runs:
// Boot chain: index.js -> src/server.js 1. ATTEST: HW fingerprint vs LICENSE.vault 2. UNSEAL: Prompt master password -> scrypt -> AES key 3. DECRYPT: .env.vault GCM -> process.env 4. VERIFY: Confirm secrets present or exit(1) 5. BOOT: Start Fastify and run migrations
Silicon Lock attestation
The Hardware Abstraction Layer reads Motherboard UUID, MAC address, and TPM 2.0 endorsement key hash. The composite fingerprint is compared to `LICENSE.vault`. A missing license is fatal. Sealing to new hardware requires `VAULT_PROVISION_LICENSE=true` during initial deployment.
Environment Sealing: Critical secrets are encrypted using AES-256-GCM with a key derived from the operator master password via scrypt. Payload format: `SALT:IV:AUTHTAG:CIPHERTEXT` (all hex).
Cryptographic Subsystem
Three independent cryptographic domains protect the vault: the sealed environment (boot), data at rest (knowledge), and the tamper-evident audit ledger. Each uses a distinct key, so compromise of one does not cascade.
Document chunks and chat messages are encrypted with AES-256-GCM. The key is the SHA-256 digest of `AES_SECRET_KEY`. Vector embeddings remain plaintext to perform cosine math.
Privileged actions are written to `security_logs` via a hash chain. Each entry hashes `prevHash | user | action | details`. Hash is signed with `AUDIT_PRIVATE_KEY` (ECDSA) and mirrored to `logs/audit.log`.
The backup subsystem streams `pg_dump` through AES-256-GCM under a separate `MASTER_RECOVERY_KEY` (32-byte hex key). Recovery key is stored only inside the sealed memory environment.
Identity, Authentication & RBAC
Authentication is stateless in transport but stateful in trust: a signed JWT carries the claim, but every protected request re-confirms that the user is active, not terminated, and matches the live database `token_version`.
Two-Factor Login with Pre-Auth Tickets
Login is a two-stage exchange. `POST /auth/verify` validates the credentials and returns a short-lived `totp_pending` token. The user must call `POST /auth/totp-verify` with the OTP to receive a full session JWT. All routing decorators reject `totp_pending` tokens.
Machine-to-Machine API Gateway
Inbound service keys are hashed using bcrypt. gateway calls traverse the identical zero-trust chain as a human session (revocation, RBAC, rate limits) and are written to the signed ledger. The gateway is inbound-only and never originates outbound traffic.
Knowledge Ingestion Pipeline
Documents enter the vault through an autonomous, fault-tolerant pipeline that parses, enriches, vectorizes, and encrypts content—then **securely destroys** the original dropzone file. Nothing transient lingers on disk.
`chokidar` watcher monitors `vault_dropzone/`. New files are instantly SHA-256 hashed and enqueued in `ingestion_jobs` for idempotency check.
Workers claim jobs using `FOR UPDATE SKIP LOCKED`, allowing up to 4 concurrent parser threads with zero double-processing races.
Text is parsed and split with semantic chunking (~1000 chars, 200 overlap). Images are routed to the local `llava` vision model to generate text descriptions.
Chunks are vectorized (nomic-embed-text) and encrypted (AES-256-GCM) into Postgres. The original dropzone file is instantly `unlink`ed.
Retrieval & Inference Fabric
Answers are grounded in the vault's own documents through a hybrid retrieval pipeline, then generated by a pluggable local inference engine under strict, role-bound hardware VRAM governance.
searchSimilar() Hybrid RAG
Fuses two signals: a fast lexical pass (ILIKE over the entity table) finds named entities, and a vector pass ranks chunks by cosine distance (`embedding <=> query`). Direct entity hits receive a **+0.3 relevance boost**, followed by decryption and SHA-256 redundancy checks.
Every query is scoped to the caller's clearance. Non-privileged roles only retrieve chunks where `department` matches (or is `All`) and the file's `clearance_tier` is at or below the user's tier. Documents owned by terminated users are filtered out ("ghost-query" suppression).
Autonomous Workflow & Agent Engine
Phase 27.1.3 elevates Vault-OS to an **autonomous orchestration platform**. Cleared operators visually compose directed acyclic graphs (DAGs) of agents, tools, and conditions that execute entirely inside the air-gap.
The entire engine sits behind `requireNeuralClearance`. Only `admin` and `Chairman` roles may author, execute, or inspect workflows. Violation triggers: "IronGap Protocol Violation. Only sysadmins can access the autonomous agent network."
The DAG Execution Model
On execution, the engine performs a **Kahn topological sort** on the workflow's nodes and edges; cycles are rejected. Nodes run in dependency order against a shared, JSON-interpolated `executionState`. Runs are wrapped in a 300s timeout and logged to `agent_executions`.
| Node Type | Function | Security Control |
|---|---|---|
| trigger_* | Manual, cron, webhook, file-drop, or pg-event entrypoints | Requires Neural clearance to author |
| llm_agent / agent_react | ReAct reasoning loop with tools (pgvector_search, internal_ner, final_answer) | 15-iteration loop cap (VRAM guard) |
| pgvector_search | Department-scoped vector retrieval | Owner department filter enforced |
| postgres_query | Read-only SQL query | SELECT-only; denies users/api_keys/config tables |
| js_sandbox | Inline JS transformation | 2s timeout; Node VM sandbox |
| file_system_write | Write artifact to dropzone | Path-traversal jailed to vault_dropzone/ |
| run_docker_container | Execute whitelisted Docker container | Image allowlist; --network=none; spawnSync argv |
| vram_purge / notify | Free model VRAM / internal outbox alert | No external dispatch permitted |
Eventing, Triggers & Telemetry
Vault-OS is event-driven internally while remaining silent externally. A transactional outbox, database event bus, and live hardware-telemetry stream coordinate the platform without a single outbound connection.
Transactional Outbox
Domain events are written to `webhook_outbox` inside the same database transaction. The dispatcher claims rows with `SKIP LOCKED`, logs them to the signed internal ledger, and purges them. No remote callback is triggered; the outbox stays strictly within the perimeter.
Live Telemetry & HAL
The Hardware Abstraction Layer broadcasts real-time telemetry every 2 seconds via Server-Sent-Events (SSE). Cheap fast-path telemetry pulls CPU/RAM state; a throttled slow-path polls GPU metrics via async `nvidia-smi` on an 8-second cycle. Telemetry is visible solely to cleared operators.
Data Lifecycle, Burn & Self-Update
A nightly cron job (`0 0 * * *`) automatically deletes chat sessions older than 30 days, cascading deletions to corresponding message history tables.
`DELETE /admin/burn` performs a NIST-compliant multi-pass shred of the dropzone, archive, and model weights folders, and drops all database tables.
Patches are staged on disk by the operator. `POST /system/update` starts a secondary instance on port 3001 and proxies connections, achieving hot-swap cut-over.
Operator Console (Frontend)
The console is a React 19 + Vite single-page application utilizing Zustand stores, designed as a dark, high-fidelity command deck for vault operators.
Vault Chat & Sessions
RAG-grounded conversation with source citations, optional incognito threads, generator-critic pipeline controls, and auto-titled session history.
Workflow DAG Editor
React-Flow canvas with typed handles, dynamic node properties, Dagre auto-layout positioning, and real-time execution log streaming.
API Surface Reference
Served under `/api/v1`. The clearance column indicates the security decorator gating the route.
| Method | Endpoint | Clearance Gating |
|---|---|---|
| POST | /auth/verify · /auth/totp-verify · /auth/reset-initial | Public (Login Exchange) |
| POST | /auth/change-password · /auth/resolve | authenticate |
| PUT | /admin/users/:id | requireAdmin |
| POST | /gateway/ingest | verifyApiKey (M2M Key) |
| GET | /files · /files/dropzone · /files/:id/download | authenticate (RBAC Filtered) |
| DELETE | /files/:id | requireAdmin |
| POST | /search · /ask | authenticate |
| GET | /hardware · /models · /security-logs · /system/diagnostics | requireAdmin |
| POST | /system/update | requireAdmin |
| POST | /system/update/confirm | requireChairman |
| DELETE | /admin/burn | requireBoardOrVIP |
| GET/POST | /workflows · /workflows/:id · /workflows/:id/execute | requireNeuralClearance |
| POST | /workflows/webhook/:id | verifyApiKey (+ Neural clearance check) |
Security Posture & Hardening Roadmap
Controls in Force
- Hardware license is fail-deadly; no auto-minting.
- PostgreSQL bound exclusively to 127.0.0.1.
- CORS origin regex fully anchored against look-alike hosts.
- Docker execution node prevents command injection (argv mapping, no shell).
- Workflow file writes are path-traversal jailed to the dropzone.
Tracked Constraints
- js_sandbox: Uses Node `vm` module (not a hard security boundary). Slated for `isolated-vm` replacement.
- Burn Authority: Reachable at VIP. Candidate for Chairman-only gating with confirmation token.
- Self-Update: Spawns child server. Slated to require cryptographically signed update bundles.
Appendix A — Schema & Env
Core Data Model
- users: Identities, roles, status, token_version, TOTP data
- files / documents: Encrypted chunks + metadata + embeddings
- entities: Extracted named entities (PERSON/ORG/DATE)
- sessions / chat_messages: Conversations + metrics
- workflows / nodes / edges: DAG configuration schemas
- agent_executions: Immutable per-run execution logs
- security_logs: Cryptographically signed audit chain
Required secrets
- JWT_SECRET: Session signing (FAIL-DEADLY)
- AES_SECRET_KEY: At-rest chunk encryption (FAIL-DEADLY)
- AUDIT_PRIVATE_KEY: ECDSA signature key (FAIL-DEADLY)
- MASTER_RECOVERY_KEY: Encrypted backup key
- LICENSE.vault: Cryptographic node signature file
Vault-OS is a proprietary enterprise appliance developed and maintained by IronGap Technologies. Available for private PoC deployments, enterprise integrations, and government-grade security consultancy.
For licensing inquiries or system acquisition, contact the secure operations mailbox.