Architecture

Vault is built as a monorepo with multiple packages that work together to deliver a secure, cross-platform password management solution.

System Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                              Clients                                     │
├─────────────────┬─────────────────────┬─────────────────────────────────┤
│   Web (React)   │   CLI (Node.js)     │   Mobile (React Native)         │
│   Vite + PWA    │   Commander.js      │   Expo                          │
└────────┬────────┴──────────┬──────────┴────────────────┬────────────────┘
         │                   │                            │
         │         ┌─────────┴─────────┐                  │
         │         │  Browser Delegate │                  │
         │         │  (Passkey Auth)   │                  │
         │         └─────────┬─────────┘                  │
         │                   │                            │
         └─────────┬─────────┴────────────────────────────┘
                   │
         ┌─────────┴─────────┐
         │   Cloudflare API  │
         │   (Hono Workers)  │
         └─────────┬─────────┘
                   │
         ┌─────────┴─────────┐
         │   Cloudflare KV   │
         │   (Encrypted)     │
         └───────────────────┘

Package Structure

packages/
├── api/          # Cloudflare Workers API (Hono)
├── web/          # React Frontend (Vite + Cloudflare Pages)
├── cli/          # Commander.js CLI tool
├── mobile/       # React Native (Expo)
├── cdn/          # Static assets (Cloudflare Worker)
├── docs/         # Documentation (Vocs)
└── shared/       # Shared types, crypto, schemas

Package Dependencies

Package	Dependencies	Description
`@pwm/api`	`@pwm/shared`	Backend API server
`@pwm/web`	`@pwm/api`, `@pwm/shared`	Web application
`@pwm/cli`	`@pwm/api`, `@pwm/shared`	Command-line interface
`@pwm/mobile`	`@pwm/api`, `@pwm/shared`	Mobile app
`@pwm/shared`	-	Shared utilities (crypto, types)

Technology Stack

Backend

Runtime: Cloudflare Workers (edge computing)
Framework: Hono - lightweight web framework
Database: Cloudflare KV (key-value storage)
Authentication: WebAuthn/Passkeys

Web Frontend

Framework: React 18 with TypeScript
Build: Vite + PWA plugin
State: Zustand (client) + TanStack Query (server)
Styling: Tailwind CSS + Radix UI
Hosting: Cloudflare Pages

CLI

Runtime: Node.js
Framework: Commander.js
Prompts: Inquirer.js
Biometrics: macOS Touch ID integration

Mobile

Framework: React Native with Expo
Navigation: Expo Router
Auth: Expo Local Authentication

Data Flow

1. User Registration

User → Web/Mobile → WebAuthn Registration → API → Store Credential → KV

2. Vault Creation

User → Enter Master Password → Derive KEK (PBKDF2)
     → Generate Vault Key → Wrap with KEK
     → API → Store Wrapped Key + Empty Vault → KV

3. Entry Operations

User → Unlock Vault (Master Password/Biometric)
     → Decrypt Vault Key → Decrypt Entries
     → Modify Entry → Re-encrypt → API → KV

4. CLI Authentication

CLI → Request Session → API → Open Browser
    → User Auth (WebAuthn) → Complete Session
    → CLI Polls → Receives Token

Storage Architecture

Cloudflare KV Schema

users:{userId}           → User profile + WebAuthn credentials
vaults:{userId}:{name}   → Encrypted vault data
shared:{ownerId}:{name}:{userId} → Shared vault access
invitations:{id}         → Pending share invitations
cli-sessions:{id}        → Temporary CLI auth sessions

Client Storage

Client	Storage	Data
Web	localStorage	JWT token, user info
Web	Memory only	Master password, vault key
Web	IndexedDB	Offline encrypted cache
CLI	`~/.pwm/config.json`	Token, user ID
CLI	macOS Keychain	Master password (with Touch ID)
Mobile	Secure Store	Token, encrypted master password

Security Boundaries

Never Leaves Client

Master password
Plaintext vault key
Decrypted entries

Server-Side Only

WebAuthn credentials
Wrapped (encrypted) vault keys
Encrypted vault data

E2E Encrypted

All vault content
Entry passwords, notes, URLs
Shared vault keys (ECDH)

Deployment Architecture

                    ┌──────────────────┐
                    │   Cloudflare     │
                    │   DNS/CDN        │
                    └────────┬─────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
   ┌────┴────┐         ┌────┴────┐         ┌────┴────┐
   │  Pages  │         │ Workers │         │   KV    │
   │  (Web)  │         │  (API)  │         │  (DB)   │
   └─────────┘         └─────────┘         └─────────┘

Environments

Environment	Web URL	API URL
Staging	`vault-staging.pages.dev`	`vault-api-staging.workers.dev`
Production	`vault.oxc.sh`	`vault-api.workers.dev`

Next Steps

Security Model - Zero-knowledge architecture details
API Reference - Complete API documentation
Development Guide - Contributing to Vault