Encrypting customer secret API keys

Connecting a Supabase project to UndoBase.io requires a secret API key (sb_secret_...). That key can read and write your data with elevated privileges (same class as the legacy service role). Treating it carefully is non-negotiable.

Here is how we store and use those keys.

What never touches the browser

When an org admin connects a project:

1. The key is sent over HTTPS to the UndoBase.io API (authenticated with your UndoBase.io session JWT).
2. The API validates the key format (sb_secret_... only — not publishable keys).
3. The API tests connectivity against your Supabase URL.
4. The key is encrypted and stored as api_key_encrypted in our app database.

The browser never receives the decrypted key. Teammates use UndoBase.io accounts and roles — they do not need the secret key pasted in chat.

Encryption at rest

We use AES-256-GCM with a random IV per encryption. The master secret is ENCRYPTION_KEY — a 64-character hex value you generate for your deployment (openssl rand -hex 32). It lives only on the server (Next.js SSR and the Fastify API), never in client bundles.

Decryption happens only when the API needs to call your Supabase project (list tables, read rows, apply edits, undo). Keys are not logged, not returned from API responses, and not included in error reports.

Threat model (practical)

We protect against:

• Casual leakage via the UI or browser storage
• Teammates sharing one super-key instead of using UndoBase.io access controls
• Database dumps exposing plaintext Supabase keys (ciphertext only in projects)

We do not replace:

• Your responsibility to rotate a key if it was pasted into the wrong tool
• Compromise of your Supabase project itself
• A malicious admin inside your UndoBase.io org (they can already edit data through the product)

Use a dedicated secret key in Supabase (Settings → API Keys → Secret keys) named for UndoBase.io. Rotate it from project settings if you suspect exposure.

Why secret keys, not publishable keys

Publishable keys (sb_publishable_...) are for client apps with Row Level Security. UndoBase.io acts as a trusted server-side editor across your tables with full audit and undo — that requires an elevated secret key, stored server-side only.

We do not accept legacy JWT service_role strings or publishable keys at connect time. New projects on Supabase are moving to opaque secret keys; aligning early avoids a painful migration later.

Operational checklist

• Only workspace owners/admins connect or rotate keys
• Invite editors and viewers to UndoBase.io — do not distribute the secret key
• Set ENCRYPTION_KEY in production via your host's secret manager (Vercel, Fly, etc.)
• Use the same key in the API and web app so encrypt/decrypt stays consistent

Security is a process. Encryption at rest is the baseline; team workflow is what keeps prod safe day to day.