metal-kompanion/docs/backup-e2ee-spec.md

Encrypted Backup Format (Draft)

Cipher left open by design (to be decided: AES-GCM vs XChaCha20-Poly1305; key storage via OS keychain or passphrase vault).

Goals

• Client-side encrypted backups (no cleartext leaves device).
• Content-addressed chunks with manifest; resumable upload.
• Key rotation support and device enrollment flow.

Artifacts

• manifest.json — version, namespace(s), chunks, sizes, hashes, KDF params, encryption metadata.
• payload.tar.zst — concatenated content/chunks (encrypted).

Flow

1. Collect items/chunks for selected namespaces.
2. Serialize → compress → encrypt → write manifest.
3. Upload manifest + blob via provider adapter (e.g., Google Drive) as opaque objects.
4. Restore: download → decrypt → verify hashes → import.

Provider Adapters

• kom.local.v1.backup.export_encrypted / import_encrypted (local).
• kom.cloud.v1.backup.upload / restore (remote; encrypted blobs only).

Open Questions

• Final cipher/KDF choices, key wrapping and rotation UX, multi-namespace packaging.