# Plan: Client-Side Encryption of R2 Tenant Backups

**Status:** In implementation (WS1-WS4) | **Date:** 2026-07-26

## 1. Goal & Threat Model

Ensure Cloudflare account administrators (anyone with dashboard/R2 browse access)
cannot read tenant data at rest. Per PRIVACY.md, message content, transcripts,
API keys, and personal conversations are "never collected, stored, or transmitted" -
but they are persisted as plaintext squashfs snapshots in BACKUP_BUCKET. This plan closes that gap.

## 2. What Must Be Encrypted (mapped to PRIVACY.md)

| R2 object                                                         | Contents                                                                                                                                                    | Sensitive?                            | Action                                     |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------ |
| `backups/<id>/data.sqsh`                                          | Full `/home/openclaw` snapshot: OpenClaw memories, session transcripts, SQLite DBs, `auth-profiles.json` (API keys/OAuth tokens), workspace/knowledge files | Yes - primary target                  | Encrypt (streaming)                        |
| `configs/<ts>.json`                                               | `openclaw.json` versions (secret-free by moltlazy design, but private config)                                                                               | Moderate                              | Encrypt (single-shot)                      |
| `backups/<id>/meta.json`                                          | id, dir, sizeBytes, ttl, createdAt                                                                                                                          | No - SDK restore requires it readable | Keep plaintext, add `encrypted: true` flag |
| `backup-handle.json`, `backup-lock`, `restore-needed`, cron store | Operational metadata                                                                                                                                        | No                                    | Leave plaintext                            |

## 3. Key Architectural Finding (verified in SDK source)

`@cloudflare/sandbox` production `createBackup`/`restoreBackup` transfer `data.sqsh`
via presigned URLs directly between container and R2 - the Worker's R2 binding cannot
transparently intercept. `doRestoreBackup` also requires plaintext `data.sqsh` to exist
(heads it for size) and validates `meta.json` TTL.

**Chosen design:** Worker-side post-encryption with transient decrypt-before-restore:

- Backup: `createBackup()` returns -> Worker streams `data.sqsh` -> chunked AES-256-GCM ->
  writes `data.sqsh.enc` -> patches `meta.json` (`encrypted: true`, original fields preserved)
  -> deletes plaintext.
- Restore: if `meta.encrypted` -> decrypt `.enc` -> write plaintext `data.sqsh` ->
  `sandbox.restoreBackup()` -> delete plaintext in `finally`.
- Residual risk (documented): two short plaintext windows - (a) between SDK upload and
  post-encryption (~seconds per backup cycle), (b) during restore. Phase 2 (future) closes
  (a) via container-side encrypt-before-upload replacing the SDK presigned flow.

## 4. Crypto Format & Key Management

- Algorithm: AES-256-GCM (WebCrypto), 4 MiB chunks, nonce = 8-byte random base || u32 BE
  counter per chunk. Streaming via TransformStream (Worker memory is bounded).
- Header (17 B): magic `F4E1` (4B) | version u8=1 | baseNonce (8B) | chunkSize u32 BE.
- Key: `BACKUP_ENCRYPTION_KEY` Worker secret (base64 32 B). Per-object key via
  HKDF-SHA256(salt=objectId, info="fouria-r2-encryption/v1"). Key never enters the
  container, R2, or logs.
- Missing key: encrypt when key present; otherwise legacy plaintext + loud warning.
  `BACKUP_ENCRYPTION_REQUIRED=true` fails closed (recommended for prod).

## 5. Workstreams

| WS  | Scope                                                                                                        | Tests                                                                                                                                 |
| --- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| WS1 | `src/crypto/backup-encryption.ts`                                                                            | `backup-encryption.test.ts`: roundtrip, chunk boundaries, tamper/wrong-key/truncation -> throw, HKDF determinism, streaming           |
| WS2 | `src/persistence.ts` + `src/crypto/r2-backup.ts`                                                             | plaintext deleted after backup; meta flag; restore writes+deletes plaintext even on failure; legacy plaintext restore; `.enc` cleanup |
| WS3 | `saveConfigVersion`/`getConfigVersion`                                                                       | roundtrip; legacy plaintext readable; API shape unchanged                                                                             |
| WS4 | types, `.dev.vars.example`, ENV-VARIABLES.md, secrets manifest, PRIVACY.md, AGENTS.md, business-rules corpus | `test/business-rules/backup-encryption.txt`                                                                                           |
| WS5 | E2E (deployed/local container)                                                                               | snapshot object starts with `F4E1`, not mountable; restore works - deferred to deployed env validation                                |

## 6. Validation

`bun run typecheck` | `bun run lint` | `bun run test` | `cctr apps/fouria/test/business-rules/`