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 v1.0.9.1. Since the workflow engine landed, the platform has gained an encrypted enclave built with the customer's own master password, a natively bundled PostgreSQL that removed the last container dependency, multi-party group collaboration with the assistant as a participant, local speech-to-text, an internal folder explorer, and a dedicated client application that is now the only way in. Each is covered in its own section below.
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
0. RECLAIM: Lock any volume a forced kill left attached
(refuses to continue if it cannot)
1. ATTEST: HW fingerprint vs LICENSE.vault
2. UNSEAL: Master password -> scrypt -> AES key
3. DECRYPT: .env.vault GCM -> process.env
4. MOUNT: BitLocker enclave -> ACL'd directory
(never a drive letter, at any point)
5. DB: Start bundled PostgreSQL + pgvector
6. SERVE: Start Fastify, then CONFIRM it answers
its own health check before handing over
// One socket serves the whole pre-boot phase and is
// released only once the application is confirmed up.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).
One continuous surface
First-run setup, master-password unlock and the startup that follows are a single page over a single socket, held open until the application is confirmed answering on its own listener. Earlier builds closed it first, leaving several minutes — mounting the enclave, initialising PostgreSQL, starting the engine — with nothing listening anywhere. The browser tab was not slow during that window; it was dead.
Every stage reports itself: what is happening, how far through the whole startup it is, and whether it is working or waiting for you. A stage that can measure itself shows real progress; one that cannot shows that it cannot, rather than a bar sitting at zero that reads as stuck.
Interrupted installs resume
First run unpacks roughly 22GB into the encrypted volume. Losing power partway does not discard it: the volume and its completed encryption are kept, and only entries that did not finish are written again — compared by size, so a file cut off mid-write is redone rather than trusted. Completion is recorded only after the final entry lands, so an existing volume is never mistaken for a finished installation.
Shutdown is verified, not assumed: BitLocker tracks the unlocked state on the volume rather than the attachment, so detaching is not locking. Shutdown locks, detaches, then re-checks, retrying once. If the enclave is still readable it reports that plainly instead of claiming a clean exit.
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
Cleared operators visually compose directed acyclic graphs (DAGs) of agents, tools, and conditions that execute entirely inside the air-gap — scheduled, event-driven, or gated on human approval.
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_isolated_task | Execute a bounded, isolated sub-task | No shell; argv mapping; no network namespace |
| switch_router / data_transform | Multi-way branching; in-graph data reshaping | Pure functions over prior node output |
| approval_gate / time_window_gate | Human sign-off; time-of-day execution bounds | Blocks the branch until satisfied |
| 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 across 33 node types.
Secure Group Collaboration
Encrypted multi-party conversations with group-local roles, per-member restrictions and slow mode, reactions, pinned messages, polls, scheduled sends, server-enforced auto-delete, and the assistant as a participant that answers only when explicitly summoned — and asks how much of the room it may read before it does.
Vault Explorer & Ingestion
Department-scoped folder tree over the encrypted corpus with per-node clearance, dropzone ingestion with entity extraction, and offline speech-to-text for dictation that never leaves the appliance.
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 runs as an ACL-locked native service, never a container.
- CORS origin regex fully anchored against look-alike hosts.
- Execution nodes map arguments as argv, never through a 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.