Encrypt OAuth2 tokens and PATs at rest in Firestore

[jodeleeuw]

Summary

• Adds AES-256-GCM encryption for osfToken, authToken, and refreshToken fields stored in Firestore user documents
• Tokens are encrypted on write and decrypted on read by Cloud Functions, so plaintext tokens never sit in the database
• New Cloud Function endpoints (/api/saveosftoken, /api/getosftoken) replace direct Firestore reads/writes from the frontend, keeping the encryption key server-side only
• Firestore rules tightened to remove client-side OAuth token write permissions
• Migration script included for encrypting existing plaintext tokens
• decrypt() has a plaintext fallback — values not starting with v1: are returned as-is, so existing tokens continue working before migration

Pre-deployment checklist

These steps must be completed before merging/deploying:

1. Generate encryption keys (one per environment):

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

2. Add GitHub Actions secrets:

   • PROD_TOKEN_ENCRYPTION_KEY — for production deployments
   • TEST_TOKEN_ENCRYPTION_KEY — for test deployments

3. Update local functions/.env — replace the placeholder 000... key with a real 64-char hex key for local development

Deployment sequence

Order matters — deploy in this sequence:

1. Deploy backend first — the decrypt() plaintext fallback means existing unencrypted tokens keep working. New writes will be encrypted.
2. Deploy frontend — after the new /api/saveosftoken and /api/getosftoken endpoints are live.
3. Run migration — encrypts all existing plaintext tokens in Firestore:

   TOKEN_ENCRYPTION_KEY=<key> node migrations/encrypt-tokens.cjs

4. Deploy Firestore rules last — only after confirming migration success and that the frontend no longer writes tokens directly. The updated rules remove isUpdateRefreshToken() and isUpdateAuthToken() client write permissions.

Test plan

• Local emulator: create user, set PAT via /api/saveosftoken, create experiment, submit data — full flow works
• Local emulator: OAuth sign-up flow — tokens stored encrypted, data submission works
• Verify decrypt() plaintext fallback — pre-existing plaintext tokens still work before migration
• Run migration on emulator with seeded plaintext tokens, verify they start with v1:
• After migration, verify data submission still works with encrypted tokens
• Check Firestore console — token fields show v1:... ciphertext, not plaintext

🤖 Generated with Claude Code