Secrets

The system reads ~60 environment variables. About half are public (NEXT_PUBLIC_*); the other half are secrets (Clerk keys, MongoDB URI, WordPress webhook secret, AWS SES creds, …).

Storage#

Local load order#

Next.js natively loads .env and .env.local. On top of that, each app's config loader pulls in production secrets from a file kept outside the repo, on the same machine — so real production values never sit inside the working tree. The order (first existing file wins for the prod override; .env.secrets is always layered on top):

1. ~/.envs/.matters-ai/.env.<app>.prod — the canonical store, resolved via os.homedir() so it works identically on macOS, Linux, and Windows. <app> is the project name:
   • .env.web.prod — public website / anything consuming @matters/lib (packages/lib/src/config/env.ts:26)
   • .env.memo.prod — memo (apps/memo/astro.config.mjs, apps/memo/drizzle.config.ts)
   • .env.partners.prod — partners portal (apps/partners/drizzle.config.ts)
2. Fallback: if the out-of-repo file doesn't exist, <repo>/.env.prod is loaded instead.
3. <repo>/.env.secrets is then layered on top for any additional super-secrets.

All of this runs server-side only (typeof window === "undefined") and is wrapped in a try/catch that silently no-ops where Node's fs isn't available (e.g. the edge runtime — see the proxy.ts note below).

The canonical Zod schema is at packages/lib/src/config/env.ts (re-exported via @/lib/config/env). It validates at boot — missing required vars cause loud startup failures, not silent runtime errors.

Access#

Never use process.env.X directly in app code. Always:

import { env } from "@/lib/config/env";

const url = env.WORDPRESS_URL;          // typed, validated
const secret = env.WORDPRESS_WEBHOOK_SECRET;

The env object is a typed, parsed z.infer<typeof envSchema>. Direct process.env.X access bypasses validation and gives you string | undefined.

The only exception is proxy.ts which runs in the edge runtime and currently reads FRASE_WEBHOOK_API_KEY directly. Edge runtime can't import the full env module because Zod's validator opens .env.secrets via Node's fs. Acceptable for that one variable; any further edge-runtime secrets should follow the same pattern with a clear comment.

Rotation#

Clerk keys#

1. In Clerk dashboard → API Keys → rotate the secret key.
2. Update CLERK_SECRET_KEY on both Vercel projects (matters-web + matters-workspace) at the same time. There is a brief window where one app has the new key and the other has the old; calls to clerkClient().users.* from the old key will start 401-ing.
3. Redeploy both projects.
4. Webhook secret (CLERK_WEBHOOK_SECRET) is rotated independently in Clerk → Webhooks → roll secret. Update the corresponding Vercel env var.

WordPress webhook secret#

1. Generate a new secret: openssl rand -hex 32 (must be ≥32 chars).
2. Update WORDPRESS_WEBHOOK_SECRET on matters-web Vercel project.
3. Update the WordPress plugin's webhook secret to match.
4. Trigger a publish on a test page to confirm revalidation still fires.

MongoDB connection string#

1. In Atlas → Database Users → rotate the password (or create a new user).
2. Build the new connection URI.
3. Update MONGODB_CONNECTION_STRING on both Vercel projects.
4. Redeploy both. Live connections drain over ~30s.

AWS SES credentials#

1. In AWS IAM → User → Security credentials → rotate access key.
2. Update AWS_SES_ACCESS_KEY_ID + AWS_SES_SECRET_ACCESS_KEY on matters-workspace (the public site doesn't send transactional email).
3. Redeploy workspace.
4. Verify next bulk-invite or transactional send.

Salesforce credentials#

1. In Salesforce → Web-to-Lead form → regenerate.
2. Update SALESFORCE_WEB_TO_LEAD_URL, SALESFORCE_ORG_ID, etc. on both Vercel projects (public marketing forms use the same Salesforce intake).
3. Redeploy.

Detection#

If you accidentally commit a secret:

1. Immediately rotate the leaked secret following the playbooks above.
2. Force-push to remove the commit from history (or use BFG / git filter-repo).
3. Notify security@matters.ai.

Don't trust "the commit was reverted" — assume scrapers indexed the public branch within seconds. Rotation is the only safe response.

GitHub's secret scanning catches the obvious ones (AWS access keys, GitHub tokens). It does NOT catch arbitrary 32-char strings like WORDPRESS_WEBHOOK_SECRET.

What's never in env#

• PII — leads, audit logs, user profiles. Lives in MongoDB.
• Per-tenant configuration — handled via WordPress pages (read by lib/downloads-config.ts and similar).
• Feature flags — currently coded directly; if/when we need a flag service, route via a thin wrapper in packages/lib.