Skip to content

AUTH_SECRET and production fail-fast

Kywi refuses to start in production when AUTH_SECRET is missing or set to one of two known dev fallbacks, because tokens signed with it would be forgeable.

This is the message, and it is fixed — there is no variant, so it is worth recognising on sight in a deploy log:

the refusal, verbatimtext
AUTH_SECRET is not set (or is the insecure dev fallback) in production.

  Set a strong random secret before deploying:
    export AUTH_SECRET=$(openssl rand -base64 32)

  Refusing to start: tokens signed with a known secret can be forged.

Run that openssl line, set the result on the service, and deploy again. The first deploy of this documentation's own host failed here and nowhere else.

What counts as insecure

Exactly three cases: missing, empty, or equal to one of two literals — dev-secret and dev-secret-change-in-production. Every other non-empty string passes. There is no length check, no entropy check, and no character class requirement anywhere in the policy, so AUTH_SECRET=x starts a production deploy cleanly. The assertion is a floor against the two placeholders that ship in scaffolds and docs, not a strength meter.

It fails at module scope, so it looks like a build failure

The assertion runs at import, in two places. Core's middleware calls it at the top level of the edge bundle, and the generated kywi.config.ts calls it again on its own first line. So a production next build or next start is what breaks — no request is ever served with a bad secret, and there is no half-working state to debug. The config copy has a second consequence operators hit later: kywi migrate and kywi seed import that config too, so a CLI run with NODE_ENV=production and no secret refuses for the same reason, on a machine where the only intent was to touch the database.

Rotating it

The secret signs session JWTs, so changing it invalidates every issued session at once: every logged-in person is signed out on their next request, and there is no grace period or dual-secret verification. There is nothing to run afterwards — the new value takes effect when the process restarts with it. In development the same resolver does not rotate anything on its own: an explicitly set AUTH_SECRET, dev fallback or not, is kept as-is on every resolve — the built-in dev-secret-change-in-production value only fills in when the variable is unset entirely.

API keys are unaffected. A token beginning kywi_ is resolved against the database and returns before the signature path is reached, so it never touches the secret. Cron jobs, CI runners, page scripts and anything else authenticating with a key keep working across a rotation — which also means rotating the secret is not a way to cut off a leaked key. That is a key revocation, and the key's scopes cap what it could do in the first place (API keys: scopes are a role ceiling).

Where this assertion sits among the other things that can fail a boot is Startup assertions; the rest of the deploy environment is Deploying a host app.