Secrets

Rules

Never read .env.local

By convention in this repo, never read .env.local from code, tooling, or AI agents. It’s per-developer local secrets. Reference .env.example and ask the developer to confirm the value.

Never commit secrets

• .env, .env.* (except .env.example) are gitignored.
• infra/ and *.tfvars are gitignored although no such files exist — harmless, and already in place for whenever GCP provisioning writes the first IaC.
• deploy/.env, deploy/certs/ are gitignored.
• google-services.json is gitignored (placed in the Android app module locally / provided to builds as a secret).
• s3.json, *.pem, *.toml are gitignored.

If a secret leaks into a commit, rotate it immediately. Git history can be amended (locally, before push) — but rotation is what actually closes the breach.

Where secrets live

Environment	Storage	How they reach the running process
Local dev	.env.local in each app	Bun + Vite read at startup.
Dev (deployed)	Dokploy per-app Environment tabs (runtime) + the data-services Compose env; svelte-web build-time values go in Build Arguments (non-secret: PUBLIC_API_URL, Sentry DSN/org/project — SENTRY_AUTH_TOKEN is omitted in dev)	Dokploy injects on container boot; build args bake at image build.
Staging + Production	GCP Secret Manager, automatic (multi-region) replication; GCS access is Workload Identity, so no static storage keys exist in either tier	Injected into Cloud Run at deploy; rotation is a secret-version bump. Decided, not provisioned yet — see Production landscape.
Native mobile builds	Per-app build config (buildConfigField / build settings) + gitignored signing/keystore files	Compiled into the binary at native build time; client-safe values only.

Categories of secrets

Category	Server-only	Client-safe
Database	DATABASE_URL, DIRECT_URL	—
Auth	BETTER_AUTH_SECRET, GOOGLE_CLIENT_SECRET	GOOGLE_CLIENT_ID (public on OAuth consent)
Cache / queues	VALKEY_URL (incl. password)	—
Search	MEILISEARCH_ADMIN_API_KEY	MEILISEARCH_SEARCH_API_KEY (read-only, scoped to public indexes)
Storage	AWS_SECRET_ACCESS_KEY	—
Image proxy	IMGPROXY_KEY, IMGPROXY_SALT	imgproxy URLs (signed)
Email	RESEND_API_KEY	—
Chat	GETSTREAM_API_SECRET	PUBLIC_GETSTREAM_API_KEY (public-by-design, gated by server-issued user tokens)
Notifications	KNOCK_SECRET_API_KEY, KNOCK_FCM_CHANNEL_ID, KNOCK_APNS_CHANNEL_ID	PUBLIC_KNOCK_API_KEY, PUBLIC_KNOCK_FEED_CHANNEL_ID
Maps	GOOGLE_MAPS_API_KEY (server)	Android Maps key in the Android project (iOS uses MapKit — no key); restricted by package name + signing-cert SHA-1
Analytics	SENTRY_AUTH_TOKEN	SENTRY_DSN, PUBLIC_POSTHOG_KEY
AI	GEMINI_API_KEY, REPLICATE_API_TOKEN, REPLICATE_WEBHOOK_SIGNING_SECRET, AI_STAGING_USER_HASH_SECRET	—
Payments	STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SIGNING_SECRET	— (hosted Checkout, so no publishable key ships — there is no Stripe.js on the client)
Fiscal / CFDI	FACTURAPI_SECRET_KEY (the FACTURAPI_PRODUCT_KEY / _UNIT_KEY / _PAYMENT_FORM overrides are SAT catalog values, not secrets)	—
Fiscal data	PII_ENCRYPTION_KEY — non-re-issuable, see below	—

Non-re-issuable secrets

Every secret above this line can be replaced. Lose RESEND_API_KEY and you issue a new one; lose AI_STAGING_USER_HASH_SECRET and the old pseudonyms stop correlating, which costs nothing anyone can name. The rotation procedure below assumes exactly that, and its first step — “issue a new credential in the provider dashboard” — is meaningless for a key with no dashboard behind it.

PII_ENCRYPTION_KEY is the first secret in this repo that does not work that way.

It is a data-encrypting key. It is self-generated (openssl rand -base64 32), no provider holds a copy, and it is the only thing that can read tax_profiles.{taxId,legalName,zip,email} and cfdi_documents.{receiverTaxId,receiverLegalName} — the RFC, razón social and fiscal domicile of every paying customer (FSR-014, packages/api/src/services/pii-crypto.ts).

Losing this key destroys data, permanently

There is no recovery path. Not a support ticket, not a re-issue — the ciphertext is unreadable and the plaintext no longer exists anywhere.

The cfdi_documents receiver snapshot makes it worse than it sounds: those rows are deliberately kept past account deletion because a CFDI is a legal document whose trace must outlive the account (sql/0018_cfdi_facturacion.sql). Losing the key destroys records we are legally required to retain, for accounts whose owners are already gone.

The rotation procedure below does NOT apply to it. Rotating it is a data migration — decrypt every row with the old key, re-encrypt with the new, in one pass, with both keys available throughout. The enc:v1: envelope carries a version specifically so that migration is a format change rather than a rewrite; nothing implements it yet.

Consequences that follow from that, and are not optional:

• An escrowed copy must exist outside the deployment platform, before the first encrypted row does. Dokploy’s env UI is the live store today, and a platform account problem must not be the same event as permanent data loss.
• Record the vault and item name here — never the value. Escrowed copy lives in: ⚠️ NOT YET RECORDED. Left visibly blank rather than hidden in a comment: this is the one line that makes the escrow real rather than intended, and an unfinished sentence on the page is harder to overlook than a TODO nobody greps for.
• Never derive it from another secret, and never reuse it. Coupling it to something with a routine rotation cadence is exactly the mistake documented under BETTER_AUTH_SECRET below.
• Rows written before FSR-014 shipped are plaintext at rest and stay readable with or without the key, which is what makes a rollback safe — it does not make the key optional for anything written since.

Client-safe ≠ unrestricted

PUBLIC_GETSTREAM_API_KEY and PUBLIC_KNOCK_API_KEY are designed for client embedding but are gated by server-issued user identification tokens. The matching *_SECRET keys stay server-only. If you ever ship a client key without server token validation in front of it, rotate the secret-side key.

Rotation procedure

1. Issue a new credential in the provider dashboard (Better Auth, Resend, Knock, etc.).
2. Update the Dokploy env var on the dev environment first.
3. Redeploy and verify nothing breaks.
4. Update STG — a new Secret Manager version on the rec-stg secret, then redeploy and verify. Skipping STG defeats the reason it exists: rotation is exactly the class of change that should break on a rehearsal tier rather than in production.
5. Update production the same way (once it exists).
6. Revoke the old credential in the provider dashboard.

For BETTER_AUTH_SECRET rotation: rotating the secret invalidates all sessions. Coordinate with the team so users get a single sign-out event instead of a silent log-out mid-flow.

BETTER_AUTH_SECRET also encrypts stored OAuth tokens

The sign-out is the visible half. The other half is silent and unrecoverable.

packages/auth/src/index.ts sets account.encryptOAuthTokens: true, and better-auth encrypts those tokens with ctx.secretConfig (better-auth/dist/oauth2/utils.mjs). This repo passes neither secret nor secrets, and does not set BETTER_AUTH_SECRETS, so createContext takes the legacy branch and secretConfig is BETTER_AUTH_SECRET itself. Every stored Google access and refresh token is encrypted under the same value that signs session cookies.

Rotate it naively and those tokens stop decrypting. Users can sign in again — that repairs it — but any server-side use of a stored refresh token fails until they do, and nothing announces it.

Rotate through the versioned array instead. This does not avoid the sign-out — the first entry becomes the signing secret, so sessions still invalidate exactly as above. It repairs the other half, keeping the old tokens readable. better-auth 1.6.29 supports BETTER_AUTH_SECRETS as comma-separated <version>:<secret> entries, newest first; buildSecretConfig keeps the singular BETTER_AUTH_SECRET as legacySecret for decrypting anything written before versioning. So:

1. Set BETTER_AUTH_SECRETS="1:<new-secret>" and leave BETTER_AUTH_SECRET set to the old value.
2. Deploy. New writes use version 1; existing tokens still decrypt via the legacy secret.
3. Drop the old value only once you accept losing anything still encrypted under it.

Read from the installed 1.6.29 source, not from a rotation anyone has performed here — verify on dev before touching production.

For IMGPROXY_KEY / IMGPROXY_SALT rotation: all currently rendered HTML pages and SSR caches still hold URLs signed with the old key. Either (a) keep the old key alongside the new for an overlap window (imgproxy supports multiple keys), or (b) accept a short window of broken images while pages re-render.

For REPLICATE_WEBHOOK_SIGNING_SECRET rotation: fetch the current default secret from Replicate, update apps/api, and redeploy the API before creating new predictions. Webhooks are verified against the exact raw body with a five-minute replay window. REPLICATE_API_TOKEN belongs only on the worker; apps/api needs the webhook signing secret but not the API token.

Mobile-specific guardrails

Any client-side key compiled into a native binary ships to user devices. Anyone with the IPA / APK can extract these keys (via strings, decompilation, or sniffing the first network request).

Provider-side restrictions are mandatory before public ship. See Architecture → Deployment for the per-key restriction recipes.

Server-only secrets like GETSTREAM_API_SECRET and KNOCK_SECRET_API_KEY must never be shipped to a mobile bundle. They belong in apps/api’s env (repo-root .env.local locally, the Dokploy api app’s Environment tab on the deployed dev env) — never in any client app.

Audit checklist

• No .env* (except .env.example) committed.
• No *_vault.yml (decrypted) committed.
• No *.tfvars (real values) committed.
• No google-services.json committed.
• No *.pem / *.jks committed.
• CI logs scrubbed of secret values (Dokploy build logs stay on the VPS; GitHub Actions secrets are masked).
• Sentry beforeSend scrubber is installed in every Sentry init.
• Mobile builds have provider-side API key restrictions applied.