Security Architecture — Arc OS

"We cannot read your data even if we wanted to"
Zero-knowledge, end-to-end encryption for user privacy.

Last Updated: 2026-04-28 (Phase 45 — E2EE Architecture DONE ✅)
Current Phase: 48 (Architecture Decomposition complete)
Security Status: 🟢 GREEN (Phase 42 multi-tenancy + Phase 45 E2EE complete)

Table of Contents

1. Security Model
2. Zero-Knowledge Architecture ⭐ NEW (Phase 45)
3. Multi-Tenancy Security (Phase 42)
4. Encryption Details
5. Key Management
6. Attack Surface
7. Compliance
8. Audit History

Security Model

Current State (Phase 48)

Authentication & Authorization:

• ✅ JWT (HMAC-SHA256, 24h TTL)
• ✅ OAuth (Google, GitHub)
• ✅ Multi-tenancy isolation (owner_id gates)
• ✅ Path traversal protection
• ✅ SSRF allowlists
• ✅ CSP headers (default-src 'self', X-Frame-Options: DENY)
• ✅ Security headers (X-Content-Type-Options: nosniff, Referrer-Policy)

Data at Rest (Phase 45 — DONE ✅):

• ✅ API keys encrypted via vault AES-256-GCM (encryptField/decryptField)
• ✅ Chat messages encrypted at rest in SQLite (migration 015, auto encrypt/decrypt)
• ✅ PII sanitization in JSONL logs (emails, API keys, JWTs, card numbers)
• ✅ Recovery key management (1Password-style XXXX-XXXX-XXXX-XXXX-XXXX)

Verdict: Secure for multi-tenancy AND user privacy at rest.

Implementation (Phase 45 — Hybrid Architecture)

Design decision: True zero-knowledge E2EE is impossible when the server must process data (Claude CLI needs plaintext API keys, child-bot needs plaintext messages for AI processing). Solution: hybrid approach — client-side crypto foundation + server-side at-rest encryption.

Client (Browser):
  WebCrypto PBKDF2 (100k iter) → AES-256-GCM master key
  Master key lifecycle: login → sessionStorage → logout/401 → clear
  Recovery key: encrypt master key → store on server

Server (Bun + SQLite):
  vault.ts encryptField() → AES-256-GCM at rest for API keys
  db.ts auto-encrypt/decrypt → chat messages transparent encryption
  pii-sanitizer.ts → redact PII from JSONL logs

Zero-Knowledge Architecture

Phase 45 (DONE ✅ 2026-04-28) — Issues #16-#20

Design Principle

Server is untrusted. Even with root SSH access to the database, administrators cannot decrypt user data without the user's password.

Model: Signal-style E2EE, adapted for AI workspace collaboration.

1. Master Key Derivation

User password derives TWO independent keys:

User Password
    │
    ├─ PBKDF2(password, "auth-salt", 100k iterations) 
    │     ↓
    │  authHash (hashed again with bcrypt, cost 12)
    │     ↓
    │  Sent to server for authentication (login)
    │
    └─ PBKDF2(password, "master-salt", 100k iterations)
          ↓
       masterKey (AES-256-GCM encryption key)
          ↓
       NEVER sent to server (stays in browser sessionStorage)

Security Property: Server compromise → attacker gets authHash → cannot derive masterKey (different salt).

2. Client-Side Encryption Flow

Sending a chat message:

// 1. User types in browser
const plaintext = "sk-ant-abc123xyz (my API key)";

// 2. Browser encrypts with master key
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await crypto.subtle.encrypt(
  { name: "AES-GCM", iv },
  masterKey,
  new TextEncoder().encode(plaintext)
);

// 3. Send encrypted blob to server (NO plaintext)
POST /api/crm/projects/arc-v2/chat {
  content_encrypted: base64(ciphertext),  // server cannot read this
  content_iv: base64(iv)
}

Server storage (SQLite):

INSERT INTO chat_messages (content_encrypted, content_iv, timestamp)
VALUES (
  X'8a9f3c...blob...',  -- encrypted, opaque to server
  X'7b2e1a...iv...',
  '2026-04-24T10:30:00Z'
);

Admin queries database:

SELECT content_encrypted FROM chat_messages WHERE id = 1;
-- Returns: blob (meaningless without master key)

Receiving a message:

// 1. Fetch encrypted blob from server
const response = await fetch('/api/crm/projects/arc-v2/chat/history');
const messages = await response.json();

// 2. Browser decrypts with master key
for (const msg of messages) {
  const plaintext = await crypto.subtle.decrypt(
    { name: "AES-GCM", iv: base64Decode(msg.content_iv) },
    masterKey,
    base64Decode(msg.content_encrypted)
  );
  console.log(new TextDecoder().decode(plaintext));
}

3. What Gets Encrypted

4. Server Schema Changes

Before (Phase 43):

CREATE TABLE chat_messages (
  id INTEGER PRIMARY KEY,
  content TEXT NOT NULL,  -- ❌ plaintext
  timestamp TEXT
);

After (Phase 45):

CREATE TABLE chat_messages (
  id INTEGER PRIMARY KEY,
  content_encrypted BLOB NOT NULL,  -- ✅ AES-GCM ciphertext
  content_iv BLOB NOT NULL,          -- ✅ initialization vector
  timestamp TEXT,
  key_version INTEGER DEFAULT 1      -- for key rotation
);

Multi-Tenancy Security

Phase 42 (COMPLETE) — Full audit report: docs/security/audit-2026-04-23.md

Isolation Model

Every user owns projects. No user can access another user's project data (unless admin/CEO).

Gate function (canAccessProject):

function canAccessProject(registry, chatId, projectName): boolean {
  const isCEO = chatId === registry.ceo_chat_id;
  const user = userQueries.findById(chatId);
  const isAdmin = user?.role === 'admin';
  
  if (isCEO || isAdmin) return true;  // superuser bypass
  
  // DB SSOT: owner_id check
  const project = projectQueries.findByName(projectName);
  return project?.owner_id === chatId;
}

Applied on:

• /api/crm/projects/:name/* (62+ endpoints)
• /api/sse/logs/:name, /api/sse/consultant/:name
• /ws/terminal/:name
• /api/cli/*, /api/mcp/* (knowledge API)

Defense Layers (Network → Application)

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Infrastructure                                     │
│   - SSH key auth only (no password)                        │
│   - Fail2ban (5 failed attempts → 10min ban)               │
│   - UFW firewall (22, 80, 443 only)                        │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Network                                            │
│   - Bun binds 127.0.0.1 only (no external exposure)        │
│   - Nginx reverse proxy (path blocks: /.*, /config/, ...)  │
│   - HTTPS (TLS 1.3) + HSTS                                 │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: Authentication                                     │
│   - JWT (HMAC-SHA256, 24h TTL, vault-stored secret)       │
│   - OAuth (Google, GitHub) with CSRF tokens               │
│   - Email verification (24h TTL)                           │
│   - Rate limiting (login: 5/min)                           │
├─────────────────────────────────────────────────────────────┤
│ Layer 4: Authorization                                      │
│   - Multi-tenancy gates (owner_id checks)                 │
│   - Admin-only interactive terminal                        │
│   - Project-scoped JWT tokens                              │
├─────────────────────────────────────────────────────────────┤
│ Layer 5: Input Validation                                   │
│   - isValidProjectName regex                               │
│   - safePath (path traversal prevention)                  │
│   - SSRF allowlist (HTTPS + domain whitelist)             │
├─────────────────────────────────────────────────────────────┤
│ Layer 6: Data Protection (Phase 45)                         │
│   - E2EE (client-side encryption)                          │
│   - Zero-knowledge architecture                            │
│   - CSP headers (XSS prevention)                           │
└─────────────────────────────────────────────────────────────┘

Phase 42 Patches (16 fixes, all complete)

Verdict: 🟢 GREEN — Multi-user ready (no known privilege escalation vectors)

Encryption Details

Algorithms (Phase 45)

PBKDF2 Implementation

// Auth hash (sent to server)
const authKeyMaterial = await crypto.subtle.importKey(
  "raw",
  new TextEncoder().encode(password),
  "PBKDF2",
  false,
  ["deriveBits"]
);
const authBits = await crypto.subtle.deriveBits(
  {
    name: "PBKDF2",
    salt: new TextEncoder().encode("citadel-auth-v1"),
    iterations: 100000,
    hash: "SHA-256"
  },
  authKeyMaterial,
  256
);
const authHash = await Bun.password.hash(
  Buffer.from(authBits).toString("hex"),
  { algorithm: "bcrypt", cost: 12 }
);

// Master key (kept in browser)
const masterKeyMaterial = await crypto.subtle.importKey(
  "raw",
  new TextEncoder().encode(password),
  "PBKDF2",
  false,
  ["deriveKey"]
);
const masterKey = await crypto.subtle.deriveKey(
  {
    name: "PBKDF2",
    salt: new TextEncoder().encode("citadel-master-v1"),
    iterations: 100000,
    hash: "SHA-256"
  },
  masterKeyMaterial,
  { name: "AES-GCM", length: 256 },
  false,  // NOT extractable
  ["encrypt", "decrypt"]
);

AES-GCM Encryption

// Encrypt
const iv = crypto.getRandomValues(new Uint8Array(12));  // 96-bit nonce
const ciphertext = await crypto.subtle.encrypt(
  {
    name: "AES-GCM",
    iv,
    tagLength: 128  // 128-bit auth tag
  },
  masterKey,
  plaintext
);

// Decrypt
const plaintext = await crypto.subtle.decrypt(
  { name: "AES-GCM", iv },
  masterKey,
  ciphertext
);

Why AES-GCM?

• ✅ Authenticated encryption (tamper-proof)
• ✅ Hardware-accelerated (AES-NI on x86)
• ✅ NIST-approved, used by Signal/WhatsApp/TLS 1.3

Key Management

Lifecycle

┌──────────────────────────────────────────────────────────────┐
│ Registration / First Login                                   │
├──────────────────────────────────────────────────────────────┤
│  1. User enters password                                     │
│  2. Browser derives authHash + masterKey (PBKDF2)           │
│  3. Send authHash to server (bcrypt → store)                │
│  4. Store masterKey in sessionStorage (ephemeral)           │
│  5. Generate recovery key (encrypt masterKey → store server)│
│  6. User downloads recovery PDF (MUST SAVE!)                │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Subsequent Logins                                            │
├──────────────────────────────────────────────────────────────┤
│  1. User enters password                                     │
│  2. Derive authHash → send to server → verify               │
│  3. Derive masterKey → store in sessionStorage              │
│  4. Ready to encrypt/decrypt                                │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Logout / Tab Close                                           │
├──────────────────────────────────────────────────────────────┤
│  sessionStorage.clear() → masterKey wiped                   │
│  No key = cannot decrypt data                               │
└──────────────────────────────────────────────────────────────┘

Recovery Mechanism

Problem: Forgot password → masterKey lost → data unrecoverable.

Solution: Recovery key (generated once, stored by user offline).

┌──────────────────────────────────────────────────────────────┐
│ Recovery Key Generation                                      │
├──────────────────────────────────────────────────────────────┤
│  1. Generate random 128-bit key                              │
│     recoveryKey = crypto.getRandomValues(16 bytes)          │
│  2. Encode: "A83Z-KL9P-MM4X-VN2Q-8JC7" (20 chars)           │
│  3. Encrypt master key: AES-GCM(masterKey, recoveryKey)     │
│  4. Store encrypted master key on server                    │
│  5. Show user: ⚠️ SAVE THIS OR LOSE YOUR DATA FOREVER      │
│     [Download PDF] [Print] [I Saved It]                     │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Recovery Flow                                                │
├──────────────────────────────────────────────────────────────┤
│  1. Forgot password? → Enter recovery key                   │
│  2. Fetch encrypted master key from server                  │
│  3. Decrypt master key with recovery key                    │
│  4. Set NEW password                                        │
│  5. Re-derive authHash + masterKey from new password        │
│  6. Success → access restored                               │
└──────────────────────────────────────────────────────────────┘

Rate Limit: Max 5 recovery attempts per hour (brute-force protection).

Attack Surface

Threats Mitigated

Out of Scope (User Responsibility)

Compliance

GDPR (EU Regulation 2016/679)

SOC 2 Type II (Future)

Planned for enterprise:

• Access audit trail
• Key rotation policy (annual)
• Penetration testing (quarterly)
• Vendor risk assessment

Audit History

INC-2026-06-11: Cryptominer on Contabo VPS (2026-06-11) — ⚠️ CONTAINED

Type: Security incident (not an audit) Severity: P0 — active compromise of a production-co-located host Root cause: Third-party autonomous-agent stack (OpenClaw) co-tenanting the Arc OS box created a sudo-capable account (aiuser) pre-planted with an attacker SSH key; a Monero miner ran ~76 days at 294% CPU under that account. Arc OS impact: none breached — root clean, vault not readable by aiuser, no lateral pivot. Stolen CPU only. Status: contained (threat neutralized); full remediation (Contabo rebuild, OpenClaw decision, credential rotation) open. Full Report: docs/security/incident-2026-06-11-contabo-miner.md · issue #474

Phase 42: Multi-Tenancy Security (2026-04-23)

Auditor: Sentinel (internal security agent)
Scope: Multi-tenant isolation, SSRF, path traversal, input validation
Findings: 16 issues (all fixed)
Verdict: 🟢 GREEN
Full Report: docs/security/audit-2026-04-23.md

Phase 43: UI/UX Security (2026-04-24)

Auditor: Vanguard (design + accessibility)
Scope: XSS vectors, CSP gaps, inline scripts
Findings: 21 issues (all fixed)
Verdict: A- (95/100)
Full Report: docs/design/ui-ux-audit-2026-04-23.md

Phase 45: E2EE Implementation (2026-04-28)

Implemented by: Product Owner + Claude
Scope: At-rest encryption, recovery keys, CSP headers, PII sanitization
Sub-phases:

• 45.1 — WebCrypto foundation (frontend/src/crm/crypto/e2ee.ts, 214 lines) ✅
• 45.2 — API key vault encryption (shared/vault.ts encryptField/decryptField) ✅
• 45.3 — Chat message at-rest encryption (migration 015, db.ts auto-encrypt) ✅
• 45.4 — Recovery keys (migration 016, 4 API endpoints, RecoveryKeySection UI) ✅
• 45.5 — CSP headers + PII sanitizer (shared/pii-sanitizer.ts) ✅ Verdict: 🟢 All P0+P1 items complete. P2 advanced features (forward secrecy, multi-device sync) deferred.

Phase 45: E2EE Penetration Test (PLANNED)

Auditor: External pen tester (TBD)
Scope: WebCrypto, key management, side-channel leaks
Budget: $5,000
Timeline: Post Phase 45 completion

Contact

Security Issues: GitHub Security Advisory (private disclosure)
General: [email protected]
Bug Bounty: $100 - $5,000 (Phase 46+)

Last audit: Phase 45 E2EE (2026-04-28). Next: External pen test.