# Design Proposal: Zero-Knowledge Secrets Manager

## 1. Architectural Overview

**Philosophy:** "Thick Client, Blind Server."
The system relies on a **Zero-Knowledge Architecture**. The server (Node.js/PostgREST) and the database never see unencrypted secrets; they act solely as a synchronization engine for encrypted blobs. All encryption/decryption occurs on the client device (Tauri/Flutter) using keys that never leave the device.

### High-Level Data Flow

1. **Client:** Derives Master Key from (Password + Salt). Encrypts data locally.
2. **Transport:** Sends encrypted blob (text/bytea) over HTTPS.
3. **Gateway:** Nginx/Traefik handles SSL termination and routing.
4. **Auth:** Node.js verifies identity (SRP-6a) and issues JWT.
5. **Persistence:** PostgREST accepts JWT, enforces Row-Level Security (RLS), and writes blob to PostgreSQL.

---

## 2. Component Design

### A. Database Layer (PostgreSQL v18+)

* **Role:** Storage and Authorization Engine.
* **Logic:** Heavily utilizes Row-Level Security (RLS) policies.
* **Schema Strategy:**
  * `users`: Stores `verifier` (SRP-6a) or hashed credentials (Argon2id).
  * `secrets`: Stores `encrypted_data` (bytea), `iv`, `auth_tag`, `owner_id`, `type` (manual/rotated).
  * `access_policies`: Join table mapping users/groups to secrets.
* **Security:** RLS policies ensure `SELECT * FROM secrets` only returns rows where `auth.uid() IN (access_policies)`.

### B. Backend API (Node.js v24 + PostgREST)

* **Node.js Service:**
  * **Auth:** Implements SRP-6a (Secure Remote Password) protocol.
  * **Business Logic:** Handling billing, email alerts, secret rotation jobs, and external webhooks.
  * **Orchestration:** Manages Redis interactions for ephemeral state.
* **PostgREST:**
  * High-performance CRUD layer.
  * Directly exposes secure views/tables.
  * Consumes JWTs issued by the Node.js service for authorization.

### C. Caching & State (Redis Cluster v8)

* **Image Source:** Official `redis:alpine` (replacing deprecated Bitnami images).
* **Revocation Lists:** Stores revoked JWT JTI claims.
* **Rate Limiting:** Distributed counters to block brute-force attacks.
* **Pub/Sub:** Real-time event bus to trigger client syncs (e.g., "Vault Updated").

### D. Clients (Tauri & Flutter)

* **Desktop (Tauri):**
  * **Security:** Encryption logic (AES-256-GCM / XChaCha20-Poly1305) runs in the Rust backend to prevent memory dumping attacks via browser dev tools.
  * **Offline:** Encrypted SQLite local replica.
* **Mobile (Flutter):**
  * **Storage:** Uses `flutter_secure_storage` for session tokens.
  * **Bio-auth:** Integrates FaceID/Fingerprint to unlock the local vault key.

---

## 3. Workflows

### A. Manual Secret Entry (Core Feature)

This is the standard workflow for storing static API keys, passwords, or notes.

1. **User Input:** User enters data (e.g., `API_KEY=12345`) into the client form.
2. **Client Encryption:** The App (Tauri/Flutter) generates a random IV and encrypts the payload using the user's Master Key *in memory*.
3. **Payload Construction:** Client creates a JSON payload: `{"iv": "...", "data": "encrypted_blob...", "type": "manual"}`.
4. **Sync:** Client POSTs the payload to PostgREST.
5. **Storage:** Database stores the blob. The server never sees `12345`.

### B. Automated Rotation (Enhancement)

1. **Trigger:** Cron job in Node.js wakes up.
2. **Execution:** Connects to provider (e.g., AWS), generates new keys.
3. **Encryption:** *Note: This requires a separate "Server-Side Vault" mechanism or Public Key encryption if the server needs to write secrets readable by the user.*
4. **Update:** Updates the `secrets` row with the new encrypted blob.

---

## 4. Cryptography Standards

* **KDF:** Argon2id (memory-hard) for deriving Master Key.
* **Symmetric:** AES-256-GCM or XChaCha20-Poly1305 for vault data.
* **Asymmetric:** RSA-4096 or ECC (Curve25519) for sharing secrets between users.
* **Transport:** TLS 1.3 only.

---

## 5. Infrastructure (Docker Compose Prototype)

*Note: Switched to official Redis images due to Bitnami Docker Hub deprecation.*

```yaml
version: '3.9'
services:
  # Load Balancer / SSL Termination
  gateway:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - api
      - postgrest

  # The Logic Core
  api:
    image: node:24-alpine
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/secrets_db
      - REDIS_URL=redis://redis:6379
      - JWT_SECRET=${JWT_SECRET}

  # The Data Interface
  postgrest:
    image: postgrest/postgrest:latest
    environment:
      - PGRST_DB_URI=postgres://user:pass@db:5432/secrets_db
      - PGRST_JWT_SECRET=${JWT_SECRET}
      - PGRST_DB_SCHEMA=api
      - PGRST_DB_ANON_ROLE=web_anon

  # The Vault
  db:
    image: postgres:18
    volumes:
      - pg_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=secrets_db
      - POSTGRES_PASSWORD=${DB_PASSWORD}

  # The High-Speed State (Official Image)
  # For a full cluster in dev, you may need a custom entrypoint or sidecar
  # to bootstrap the slots. For simplicity here, we use a standalone instance
  # that mimics the interface.
  redis:
    image: redis:alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data