04 — E2E Encryption Architecture (WAFINE BFF + Frontend)

                          ┌─────────────────────────────────────────────┐
                          │              White-labeled Next.js            │
                          │              (Vercel, app/web)               │
                          │  ┌─────────┐  ┌──────────┐  ┌────────────┐  │
                          │  │ React   │  │ Client   │  │ White-label│  │
                          │  │ Server  │  │ crypto   │  │ theme      │  │
                          │  │ Comp.   │  │ (XChaCha)│  │ (CSS vars) │  │
                          │  └────┬────┘  └────┬─────┘  └────────────┘  │
                          └───────┼─────────────┼───────────────────────┘
                                  │ HTTPS       │ HTTPS
                                  ▼             ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                          BFF (Hono + oRPC + Bun)                              │
│                          app/bff — hexagonal                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────────┐  │
│  │ Auth     │ │ Rate     │ │ Cache    │ │ Crypto   │ │ Storage adapter   │  │
│  │ middleware│ │ limit    │ │ (Bun KV) │ │ service  │ │ (R2 ciphertext)   │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────────┬─────────┘  │
│       └─────────────┴─────────────┴─────────────┴────────────────┘            │
│  ┌──────────────────────────────────────────────────────────────────────┐    │
│  │  Domain layer: entities, ports, key management, encryption           │    │
│  ├──────────────────────────────────────────────────────────────────────┤    │
│  │  Application layer: use cases (send, receive, search, rotate)        │    │
│  ├──────────────────────────────────────────────────────────────────────┤    │
│  │  Infrastructure layer: Drizzle + Supabase, R2, auth proxy, cache     │    │
│  └──────────────────────────────────────────────────────────────────────┘    │
└────────────────────────────────┬─────────────────────────────────────────────┘
                                 │ TLS (Supabase pooler)
                                 ▼
                    ┌────────────────────────────┐
                    │  Supabase Postgres          │
                    │  (ciphertext + blind idx)  │
                    └────────────────────────────┘
                                 │
                    ┌────────────┴────────────┐
                    │                         │
              ┌─────▼─────┐           ┌───────▼───────┐
              │ Cloudflare │           │  OpenWA gateway│
              │ R2         │           │  (OCI A1)      │
              │ (ciphertext│           │  port 2785     │
              │  media)    │           │  X-API-Key     │
              └───────────┘           └────────────────┘

URK (User Root Key)  — 32 random bytes, never leaves device
  │  wrapped by: Argon2id(passphrase) + device_secret  (1Password pattern)
  │
  └─ Tenant KEK — 32 random bytes, per tenant
       │  stored wrapped per-device in tenant_keys
       │
       ├─ CK (message content key)  — per-message random 32B
       ├─ IK (identity key)         — per-column blind-index key
       ├─ MK (media key)            — per-object random 32B
       └─ SK (search key)           — reserved

blind_index = HMAC-SHA256(HKDF(IK, "idx/<col>/v1"), normalize(value))[:16]

app/bff/src/
  domain/            # Pure business logic, zero I/O
    entities/        # Message, Contact, Tenant, Device, RecoveryKey
    ports/           # Interfaces: IMessageRepository, ICryptoService, IKeyService, IStorageAdapter
    services/        # EncryptionService, KeyManagementService, BlindIndexService
    value-objects/   # EncryptedPayload, WrappedKey, KeyVersion

  application/       # Use cases, orchestration
    usecases/        # SendMessage, ReceiveMessage, SearchContacts, RotateKey, EnrollDevice
    dto/             # Request/response DTOs with validation
    mappers/         # Entity ↔ DTO mapping

  infrastructure/    # Adapters, external services
    db/              # Drizzle schema, migrations, repository implementations
      schema/        # Drizzle table definitions
      migrations/    # SQL migrations
      repositories/  # IMessageRepository impl, etc.
    crypto/          # XChaCha20-Poly1305, secretstream, blind index, Argon2id
      xchacha20.ts
      secretstream.ts
      blind-index.ts
      argon2id.ts
    auth/            # Custom auth: middleware, proxy, web-workers, cache, rate-limit
      middleware.ts  # Hono middleware: session validation, key unwrapping
      proxy.ts       # Auth proxy for upstream OpenWA
      web-workers.ts # Web Crypto workers for client-side key operations
      cache.ts       # Session/key cache (Bun KV or in-memory)
      rate-limit.ts  # Token-bucket rate limiter
    storage/         # R2 ciphertext storage adapter
      r2-client.ts
      presigned.ts   # Ciphertext-only presigned URLs
    config/          # Env validation, feature flags

  adapters/          # HTTP interface
    http/
      app.ts         # Hono app assembly
      routers/       # oRPC routers: messages, contacts, tenants, health
      middleware/    # Auth, rate-limit, error-handler, request-logger
    rpc/             # oRPC client (for frontend consumption)

  index.ts           # Entry point: Bun.serve with Hono

Client → HTTPS → BFF (Hono)
  1. Auth middleware: validate session/JWT, unwrap tenant KEK (short-TTL)
  2. Rate-limit middleware: token-bucket per tenant+endpoint
  3. Cache middleware: check Bun KV for decrypted response cache
  4. oRPC router → use case
  5. Use case:
     a. Unwrap DEK (if needed)
     b. Decrypt/encrypt via domain service
     c. Call infrastructure port (DB, R2)
     d. Map entity → DTO
  6. Response middleware: encrypt sensitive fields, set cache headers
  7. Audit log: unwrap event (who, what, when, TTL)

app/web/src/
  app/
    [tenant]/          # Dynamic tenant slug
      layout.tsx       # Tenant-specific layout (logo, colors, fonts)
      page.tsx         # Dashboard
      messages/
        page.tsx       # Message list
        [id]/
          page.tsx     # Message detail
      contacts/
        page.tsx       # Contact list
      settings/
        page.tsx       # Tenant settings (key management, recovery)
  components/
    ui/                # Button, Input, Card, Modal, etc.
    crypto/            # Client-side crypto components
    white-label/       # Logo, ThemeProvider, FontLoader
  lib/
    api-client.ts      # oRPC client
    crypto.ts          # Client-side XChaCha20-Poly1305, Argon2id
    key-management.ts  # Device enrollment, key wrapping/unwrapping
    session.ts         # Session management, JWT refresh
  styles/
    white-label.css    # CSS custom properties for theming
    globals.css        # Base styles

Client → BFF: { plaintext, recipient_jid }
  1. Auth: validate session, unwrap tenant KEK
  2. Rate-limit: check token bucket
  3. Generate message DEK (random 32B)
  4. Encrypt plaintext with DEK (XChaCha20-Poly1305, AAD = tenant_id|messages|row_id|v1)
  5. Wrap DEK with tenant KEK
  6. Generate blind index for recipient_jid
  7. Store: { ciphertext, wrapped_dek, dek_nonce, dek_version, blind_index } in Supabase
  8. Forward to OpenWA gateway (via auth proxy) for actual WhatsApp delivery
  9. Return: { message_id, timestamp } (no plaintext)

OpenWA webhook → BFF: { plaintext, sender_jid, timestamp }
  1. Validate webhook signature (API key + HMAC)
  2. Look up tenant by sender_jid (blind index match)
  3. Generate message DEK, encrypt, wrap, store (same as send)
  4. If client is online: push notification (WebSocket) with encrypted payload
  5. Client decrypts locally with its DEK (unwrapped from tenant KEK)

Client → BFF: { query: "+212612345678" }
  1. Auth: validate session
  2. Normalize query (E.164, NFC, trim)
  3. Compute blind_index = HMAC-SHA256(IK, normalize(query))[:16]
  4. Query Supabase: SELECT * FROM contacts WHERE blind_index = $1
  5. Decrypt contact names (if client has key)
  6. Return: [{ contact_id, display_name, ... }]

-- Tenant key management
CREATE TABLE tenant_keys (
  tenant_id UUID PRIMARY KEY,
  wrapped_kek BYTEA NOT NULL,
  kek_nonce BYTEA NOT NULL,
  kek_version INT NOT NULL DEFAULT 1,
  alg_id TEXT NOT NULL DEFAULT 'xchacha20poly1305',
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Device enrollment
CREATE TABLE devices (
  device_id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL REFERENCES tenant_keys(tenant_id),
  wrapped_kek BYTEA NOT NULL,  -- KEK wrapped for this device
  device_public_key BYTEA NOT NULL,  -- X25519 public key
  device_name TEXT,
  last_seen_at TIMESTAMPTZ,
  revoked_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Messages (ciphertext only)
CREATE TABLE messages (
  message_id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  sender_ref TEXT NOT NULL,  -- blind index or opaque ID
  recipient_ref TEXT NOT NULL,
  ciphertext BYTEA NOT NULL,
  wrapped_dek BYTEA NOT NULL,
  dek_nonce BYTEA NOT NULL,
  dek_version INT NOT NULL DEFAULT 1,
  alg_id TEXT NOT NULL DEFAULT 'xchacha20poly1305',
  sent_at TIMESTAMPTZ NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_messages_tenant_sent ON messages(tenant_id, sent_at DESC);
CREATE INDEX idx_messages_sender ON messages(sender_ref);
CREATE INDEX idx_messages_recipient ON messages(recipient_ref);

-- Contacts (ciphertext + blind index)
CREATE TABLE contacts (
  contact_id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  phone_blind_index BYTEA,  -- HMAC-SHA256, nullable if no phone
  jid_blind_index BYTEA NOT NULL,  -- HMAC-SHA256
  name_ciphertext BYTEA,
  name_wrapped_dek BYTEA,
  name_dek_nonce BYTEA,
  name_dek_version INT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_contacts_tenant_phone ON contacts(tenant_id, phone_blind_index);
CREATE INDEX idx_contacts_tenant_jid ON contacts(tenant_id, jid_blind_index);

-- Media objects (ciphertext in R2, metadata in Postgres)
CREATE TABLE media_objects (
  media_id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  message_id UUID REFERENCES messages(message_id),
  r2_object_key TEXT NOT NULL,  -- opaque UUID, no metadata leakage
  ciphertext_size BIGINT NOT NULL,
  wrapped_dek BYTEA NOT NULL,
  dek_nonce BYTEA NOT NULL,
  dek_version INT NOT NULL DEFAULT 1,
  secretstream_header BYTEA,  -- for streaming decryption
  mime_type TEXT,  -- plaintext, needed for Content-Type
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Key rotation jobs
CREATE TABLE key_rotation_jobs (
  job_id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  key_type TEXT NOT NULL,  -- 'kek' | 'dek' | 'urk'
  old_version INT NOT NULL,
  new_version INT NOT NULL,
  cursor_position UUID,  -- last processed row
  status TEXT NOT NULL DEFAULT 'running',  -- 'running' | 'paused' | 'completed' | 'failed'
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  completed_at TIMESTAMPTZ
);

-- Recovery keys
CREATE TABLE user_recovery (
  recovery_id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  wrapped_urk BYTEA NOT NULL,  -- URK wrapped by recovery mnemonic
  recovery_nonce BYTEA NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Audit log (unwrap events)
CREATE TABLE audit_log (
  audit_id UUID PRIMARY KEY,
  tenant_id UUID NOT NULL,
  actor_type TEXT NOT NULL,  -- 'user' | 'agent' | 'system'
  actor_id TEXT NOT NULL,
  action TEXT NOT NULL,  -- 'unwrap' | 'rotate' | 'enroll' | 'revoke'
  resource_type TEXT NOT NULL,  -- 'message' | 'contact' | 'media' | 'kek'
  resource_id TEXT,
  success BOOLEAN NOT NULL,
  detail JSONB,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_audit_tenant_created ON audit_log(tenant_id, created_at DESC);

-- Tenant themes (white-label, public)
CREATE TABLE tenant_themes (
  tenant_id UUID PRIMARY KEY,
  slug TEXT NOT NULL UNIQUE,
  logo_url TEXT,
  primary_color TEXT NOT NULL DEFAULT '#1a73e8',
  font_family TEXT NOT NULL DEFAULT 'Inter',
  custom_css TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);