Skip to main content

​
System overview

PassAgent is a monorepo application built on Next.js with three companion microservices, browser extensions for Chrome/Firefox/Safari, and a native iOS app. All vault operations happen client-side — the server never sees plaintext credentials.

​
Technology stack

​
Frontend

TechnologyVersionPurpose
Next.js16.1Full-stack React framework with App Router, Turbopack dev server, standalone output
React19UI library with React Compiler enabled (reactCompiler: true)
TypeScript5.9Strict mode, bundler module resolution, incremental builds
Tailwind CSS4.1Utility-first CSS with class-based dark mode and CSS variable color tokens
Radix UILatest25+ accessible, unstyled primitives (Dialog, Dropdown, Accordion, Toast, etc.)
shadcn/ui—Pre-built component library on top of Radix with Tailwind styling
Untitled UI0.1.52Icon system (@untitledui/icons, @untitledui/file-icons)
Motion (Framer)12.29Layout animations, page transitions, gesture handling
Recharts3.7Dashboard charts and security analytics visualizations
Three.js / R3F0.1823D elements on the marketing site (@react-three/fiber, @react-three/drei)
Tiptap3.18Rich text editor for secure notes (with image, placeholder, text align extensions)
React Hook Form7.71Form management with Zod schema validation
React Aria3.45Accessible UI primitives from Adobe for complex interactive components
cmdk1.0.4Command palette (⌘K) for quick vault search
Sonner2.0.7Toast notifications
Vaul1.1.2Drawer component for mobile UI
Embla Carousel8.6Touch-friendly carousels
Shiki3.22Syntax highlighting in secure notes code blocks

​
Backend

TechnologyVersionPurpose
Supabase2.95PostgreSQL 15 database, Auth (JWT + cookies), Row-Level Security, Realtime subscriptions
Redis (ioredis)5.6Session state, rate limiting (sliding window), alert counters, OPRF rate limits, agent state caching. In-memory fallback with TTL for environments without Redis
BullMQ5.67Background job queue for async password resets (orchestrator → worker pattern)
Express4.22HTTP server for microservices (orchestrator, worker, mailbox reader)
Stripe20.3Subscription billing, checkout, customer portal, webhook processing, promo codes
Nodemailer8.0Transactional email (sign-in notifications, family invites, dead man’s switch alerts)
React Email0.4Email template rendering with Tailwind + Handlebars
googleapis148.0Gmail OAuth2 for reading password reset emails and account discovery
jose5.9JWT signing, verification, and token management
Zod3.25Runtime schema validation for all API inputs
Cheerio1.0HTML parsing for email content extraction and link scraping
TypeORM0.3.20ORM for orchestrator service database operations
postgres3.4Lightweight PostgreSQL client for direct queries
Twilio5.12SMS delivery for 2FA codes
rate-limiter-flexible7.2Redis-backed rate limiting with sliding window counters

​
AI & browser automation

TechnologyVersionPurpose
Anthropic Claude SDK0.73Vision AI (screenshot analysis), reasoning (page state classification), chat routing (tool_use with 20+ vault tools)
Vercel AI SDK3.4Streaming chat responses (StreamingTextResponse), tool routing abstraction
LangChain0.3.19Agent orchestration framework, LangGraph state machines for multi-step reset flows
Hyperbrowser Agent1.1.2Cloud browser with AI sub-goal execution, live preview URLs, session sharing infrastructure
Playwright1.58Local headless browser automation, E2E testing, screenshot capture
Puppeteer24.17Chromium automation fallback for specific provider integrations
Browserless—Cloud browser service; BQL (Browserless Query Language) for scripted reset flows
OpenAI SDK3.0Alternative LLM provider for specific automation tasks via @ai-sdk/openai

​
Cryptography & security

TechnologyPurpose
Web Crypto APIAll client-side encryption: AES-256-GCM, RSA-OAEP, HKDF-SHA256, HMAC-SHA256, P-256 ECDSA. Non-extractable CryptoKey objects
Argon2id (hash-wasm)Master password KDF — 64 MiB memory, 3 iterations, 4 threads. Fallback: 32 MiB for low-memory devices
SimpleWebAuthn13.2WebAuthn server-side verification for passkeys and biometric unlock
AWS KMSServer-side DEK envelope encryption — KMS wraps the data encryption key; key never in plaintext on disk
HashiCorp VaultKey wrapping and secret management for the orchestrator microservice
AWS Secrets ManagerRuntime secret retrieval for microservices (DB passwords, API keys)
Cloudflare TurnstileBot protection on authentication endpoints
GF(256) ShamirCustom implementation of Shamir’s Secret Sharing over Galois Field 256 for threshold vault recovery

​
Cloud infrastructure

ServicePurpose
AWS ECSContainer orchestration for all services (Next.js app, orchestrator, worker, mailbox reader)
AWS S3 / MinIOEvidence storage (screenshots, DOM snapshots) and vault attachments
AWS SQSMessage queue between orchestrator and worker services
AWS KMSHardware security module for data encryption key management
Supabase CloudManaged PostgreSQL, Auth, Realtime, and Storage
SentryError tracking, performance monitoring, custom metrics. Tunnel via /monitoring to bypass ad blockers
Have I Been PwnedBreach monitoring API with k-anonymity (SHA-1 prefix)

​
DevOps & CI/CD

ToolPurpose
GitHub Actions8 workflows: CI (lint, type-check, test, security gates, perf smoke), deploy (staging auto, production canary), CodeQL, Semgrep, secret rotation, incident drills, monthly evidence rollups
Docker3-stage build (deps → builder → runner). Alpine Node 20, non-root user. Worker uses ghcr.io/microsoft/playwright:focal
docker-composeLocal dev: app + PostgreSQL 16 + Redis 7 + MinIO + HashiCorp Vault + MailHog
pnpm9.15Package manager with workspace monorepo support
HuskyPre-commit (lint-staged) and pre-push (test + coverage) hooks
lint-stagedPrettier + ESLint on staged .ts/.tsx files
Jest30.02715+ unit tests, 108 test suites, jsdom environment, coverage thresholds (84% statements, 75% branches, 88% lines, 80% functions)
Playwright TestE2E tests, sequential execution, trace/screenshot/video on failure
SemgrepSAST with OWASP Top 10 + Next.js + JWT + custom rules
CodeQLGitHub-native code analysis with security-extended queries
GitleaksSecret scanning in CI
Socket.devSupply chain security analysis on PRs
CycloneDXSBOM (Software Bill of Materials) generation

​
Testing & quality

CategoryDetails
Unit tests2715 tests across 108 suites — crypto roundtrips, API routes, security controls, AI guard, anomaly detection
Security testsDedicated test:security suite — phishing detection, spray detection, anomaly detection, AI guard (input/output/semantic), invariant checks
E2E testsPlaywright-based auth flow, vault operations, reset flows
Performance gatesCI smoke test: 60 requests, concurrency 6, p95 must be under 1200ms
Security CI scripts12 static analysis scripts: auth guard coverage, rate limit coverage, plaintext leak detection, fail-closed verification, privileged audit coverage, security claims validation
Property-based testingfast-check for fuzzing crypto operations
Coverage thresholdsEnforced in CI: 84% statements, 75% branches, 88% lines, 80% functions

​
Database schema

PassAgent uses Supabase (PostgreSQL 15) with Row-Level Security on every table. The schema evolved over 53 migrations.
Every table with user data has RLS policies scoped to auth.uid(). The server cannot query across users even with a database connection. Service-role access is used only for system operations (cron jobs, admin endpoints).

​
Deployment architecture

​
Production (AWS ECS)

​
Deployment pipeline

1

CI gates

Lint → Type check → 2715 unit tests → 12 security scripts → CodeQL + Semgrep → Performance smoke (p95 < 1200ms) → Production readiness gate
2

Docker build

3-stage Alpine build. Multi-arch (amd64). SHA-tagged + latest. GitHub Actions cache for layer reuse.
3

Staging deploy

Auto-deploys to staging.passagent.app on push to main. ECS update-service --force-new-deployment. Smoke test verifies HTTP 200.
4

Production deploy (manual)

Canary deployment: 45-second warm-up → 15 health probes at 2-second intervals → max 10% failure rate → max p95 1200ms. Then deploys orchestrator, worker, and mailbox services.

​
Local development (docker-compose)

ServiceImagePortPurpose
appDockerfile3000Next.js with Turbopack
postgrespostgres:165432Local database
redisredis:7-alpine6379Sessions, rate limits
miniominio/minio9000, 9001S3-compatible object storage
vaulthashicorp/vault:1.158200Key wrapping
mailhogmailhog:v1.0.11025, 8025SMTP trap for email testing

​
Security middleware

Every page request passes through Next.js middleware that:
  1. Generates a per-request UUID nonce for Content Security Policy
  2. Sets Content-Security-Policy with strict-dynamic + nonce-based script loading
  3. Sets X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin
  4. Restricts Permissions-Policy (no camera, microphone, geolocation)
  5. Reports CSP violations to /api/csp-report
  6. Allows frame-src only for Stripe.js and Cloudflare Turnstile
  7. Blocks all framing via frame-ancestors 'none'

​
Monorepo structure

passagent/
├── app/                     # Next.js App Router (pages + API routes)
│   ├── api/                 # 100+ API endpoints
│   ├── dashboard/           # Authenticated app pages
│   ├── admin/               # Admin panel
│   └── auth/                # Login, signup, OAuth callbacks
├── apps/
│   ├── chrome-extension/    # Chrome MV3 (side panel + content script)
│   ├── extension-firefox/   # Firefox MV3 (popup + content script)
│   ├── extension-safari/    # Safari app extension
│   ├── orchestrator/        # Express + BullMQ job server
│   ├── worker/              # Playwright reset worker
│   ├── mailbox-reader/      # OTP email extraction service
│   └── mobile/              # Mobile SDK stubs
├── components/              # React components (400+)
│   ├── chat/                # AI chat UI + card components
│   ├── family/              # Family vault components
│   └── tools/               # Service-specific automation tools
├── lib/                     # Core business logic
│   ├── agents/              # AI reset agents, orchestrator, state machine
│   ├── browser-providers/   # Multi-provider manager, action cache, success tracker
│   ├── security/            # Auth, crypto, anomaly detection, AI guard, posture
│   ├── session-sharing/     # Live session sharing engine
│   ├── travel-fortress/     # Cryptographic travel mode
│   ├── monitoring/          # Metrics, SLO, alerting rules
│   ├── notifications/       # Multi-channel notification dispatcher
│   ├── offline/             # IndexedDB sync, delta sync manager
│   └── family-recovery/     # Shamir threshold engine
├── packages/
│   ├── reset-engine-core/   # Shared: BQL compiler, playbooks, detection patterns
│   ├── reset-engine-runner-playwright/  # Playwright-based reset runner
│   ├── cli/                 # CLI tool (auth, generate, vault, ref)
│   └── otp/                 # TOTP/HOTP generation
├── ios/PassAgent/           # Native iOS app (SwiftUI)
├── marketing/               # Marketing site components
├── services/shared/         # Shared microservice utilities (audit, S3, SQS, secrets)
├── supabase/                # 53 migrations, config, seed data
├── data/                    # Action caches, playbooks, service annotations
├── e2e/                     # Playwright E2E tests
├── __tests__/               # 108 Jest test suites (2715 tests)
├── .github/workflows/       # 8 CI/CD workflows
└── documentation/           # Mintlify docs (70+ pages)

​
Browser extension architecture

Manifest V3 with service worker background script and side panel UI.Key capabilities:
  • Autofill via content script injection (domain-matched blind indexes)
  • WebAuthn proxy (webAuthenticationProxy permission) — extension acts as a software passkey authenticator
  • Side panel embeds the full AI chat interface
  • Action cache client prefetches golden scripts for fast resets
  • 4-layer phishing detection runs before every autofill
Permissions: storage, activeTab, scripting, contextMenus, notifications, tabs, alarms, cookies, sidePanel, webAuthenticationProxy, tabGroupsKeyboard shortcuts: ⌘⇧P (open), ⌘⇧L (autofill), ⌘⇧G (generate)CSP: script-src 'self' 'wasm-unsafe-eval' (required for Argon2id WASM)

​
iOS app architecture

ComponentTechnology
UI frameworkSwiftUI (iOS 17.0+, Swift 5.10)
AutoFillCredential Provider Extension (shares vault crypto code via App Group)
WidgetsWidgetKit extension
KeychainKeychainAccess library for secure storage
QR scanningCodeScanner library for TOTP setup
KDFArgon2Swift (native Argon2id implementation)
Build systemXcodeGen (project.yml) with 5 targets
App Groupgroup.com.passagent.shared for data sharing between app, AutoFill, and widget

​
Observability

  • Client + Server + Edge Sentry SDKs (v10.38)
  • 100% trace sampling in dev, 10% in production
  • Custom metrics: http.request.duration, reset_flow.success, auth.failure, security.spray_detected
  • CSP violation reporting at /api/csp-report
  • Tunnel route /monitoring to bypass ad blockers
  • Filtered: 4xx errors (except 429), ResizeObserver, ChunkLoadError, AbortError
  • Availability target: 99.9% (43 minutes/month error budget)
  • Latency targets: p95 < 1200ms, p99 < 3000ms
  • Google SRE multi-window burn rate alerting: >14x = critical (~2h budget exhaust), >6x = warning (~5h), >1x + <50% remaining = info
  • Cron: POST /api/cron/slo-burn-rate-check
Redis-backed counter alerting with sliding windows and cooldown deduplication:
SeverityAlertThresholdWindow
P15xx errors>105 min
P1Webhook failure>31 hour
P1Critical DB write failure>15 min
P1Redis failure>55 min
P2Auth failures>5010 min
P2Rate limit hits>10010 min
P2Spray detected>330 min
P3Access anomaly>51 hour