Add POST /auth/wxyc/station-signup, the passcode-gated self-signup endpoint

[jakebromberg]

Summary

Mounts POST /auth/wxyc/station-signup ahead of the better-auth handler (alongside lookup-email and complete-onboarding, already under /auth/wxyc/): the public endpoint a DJ walks up to and uses to self-provision a dj-role account behind a station passcode.

Flow

The handler runs strictly in this order, and the ordering is the security argument for the whole PR:

0. Pure env preconditions. The STATION_SIGNUP_ENABLED gate, then DEFAULT_ORG_SLUG. Both are env reads with nothing to learn from the request, so they run before any DB work. DEFAULT_ORG_SLUG in particular must not be checked after the claim: a deploy that forgot it would burn one use per attempt and brick the code inside 25 requests, which is the control-room lockout epic Epic: passcode-gated DJ self-signup for holiday breaks (server) #2365 forbids.
1. All shape validation. validateUsername (on the normalized value), isValidEmail from @wxyc/shared/validation, the 8-character password floor mirroring minPasswordLength, and explicit maximum lengths: email/realName/djName at 255 to fit their varchar(255) columns, password at 128 to match better-auth's own maxPasswordLength default. No over-length value can reach provisionUser after a use has been claimed.
2. The passcode MATCH. matchStationPasscode — cooldown check, decrypt every active row, constant-time compare, no early exit. Claims nothing. Failure is a generic 401 regardless of anything else in the request; cooldown is a 429 with a wait-time message.
3. The email/username existence checks. internalAdapter.findUserByEmail plus a username lookup, now genuinely behind the gate. The 409s here are the enumeration oracle the issue body accepts by name — observable only to a caller who has already proven they hold a live code, on the same footing as /auth/wxyc/lookup-email.
4. The passcode CLAIM. claimStationPasscode — the single atomic conditional UPDATE … WHERE use_count < max_uses AND revoked_at IS NULL AND expires_at > now() RETURNING id.
5. provisionUser, then a best-effort SES deliverability probe.

Why the phases are split. The endpoint owes two properties that a fused match-and-claim cannot deliver at once: an unauthenticated caller must learn nothing (not even whether an email is registered) until they hold a live code, so the gate has to run before the existence checks; and a typo must never burn one of a code's 25 uses, so the claim has to run after them. verifyStationPasscode is therefore split in shared/authentication/src/station-passcode.ts into matchStationPasscode and claimStationPasscode, with the fused function kept as a thin wrapper over the two so its existing callers and tests keep binding the shared logic. The match/claim pair writes exactly one station_signup_attempt row per verification on every path — the match is deliberately quiet on success and the claim always writes one, so a successful signup never produces two rows.

Accepted residual: a code can reach its cap, be revoked, or expire between the match and the claim. The claim's own conditional UPDATE catches that, the caller gets the same generic 401 as any other refusal, and no use is burned. That race already existed inside the fused call; splitting the phases widens it by two indexed reads.

Other properties

• Username case is normalized once, at the top of the handler, and the normalized value is used for validation, the existence lookup, provisionUser, and the response. better-auth's username plugin lowercases on store and duplicate-checks the lowercased value, so a raw-case pre-check let NewDJ sail past a stored newdj, claim a use, and then die inside the plugin's create hook. provisionUser's duplicate heuristic now also matches already taken (better-auth's own wording), and the 201 body reads the username back off the created row rather than echoing the request, as the email already did.
• Role is a server-side constant ('dj') — never read from the request body.
• Provisions with sendSetupInvite: false, hasCompletedOnboarding: true, and selfSignupAt stamped, mirroring provisionUser's BS#2360 groundwork.
• The deliverability probe is precisely that: the account is already emailVerified: true (set unconditionally by provisionUser), so clicking the link changes no state — it's bounce detection ahead of the manager review that is the real check. Calls sendVerificationEmailMessage directly rather than better-auth's own sendVerificationEmail endpoint, which no-ops for an already-verified account.
• Mints no session. The DJ signs in normally with the password they just chose.
• The response stays generic on an invalid passcode (wrong/expired/revoked/exhausted are indistinguishable to the caller). ProvisionError messages are mapped to curated client-safe strings rather than forwarded verbatim — the org-slug 404 embeds DEFAULT_ORG_SLUG.
• Dedicated 60s/120 rate limiter, not the shared 10/15min brute-force tier — every legitimate caller of this endpoint shares one IP (the control-room computer), so the brute-force tier would let a few fumbled codes lock the whole room out for fifteen minutes.
• STATION_SIGNUP_ENABLED off does not mount the route or its limiter at all, so the path falls through to better-auth's catch-all and a disabled deployment is indistinguishable from one that never shipped the feature. The handler keeps its own 404 guard for direct callers.

Also plumbs STATION_SIGNUP_ENABLED and STATION_PASSCODE_KEY through dev_env/docker-compose.yml (ci auth + e2e-auth), .github/workflows/test.yml, .github/workflows/set-ec2-env-var.yml's allowlist, and .env.example, so the feature is actually reachable end to end (production light-up still requires an operator to push the real secrets).

Test plan

• tests/unit/auth/station-signup.test.ts — feature-off 404; the full validation-before-passcode ordering including every length bound; the gate-before-enumeration property (a bad passcode yields an identical status/message/code whether the email is registered or not, and never queries the user table at all); duplicate email/username rejected after the match but before the claim; the claim losing its race after a good match; cooldown and invalid-passcode responses; username case normalization and the case-variant duplicate; the username read back off the created row; role-pinning; DEFAULT_ORG_SLUG unset failing before either passcode phase is invoked; curated ProvisionError messages; and the verification-probe send.
• tests/unit/auth/rate-limiting.test.ts — source-text assertions pinning the limiter's 60s/120 shape, its exact path and rateLimitKeyFromRequest key generator, its absence from rateLimitedPaths, and the isStationSignupEnabled() gate on both the limiter and the route. isTestEnv disables every mounted limiter, so source text is the only thing that can catch a regression here.
• tests/unit/auth/provision-user.test.ts — better-auth's own Username is already taken. Please try another. now maps to a 409 instead of escaping as an unhandled 500.
• tests/integration/station-signup.spec.js — golden path (role, hasCompletedOnboarding, selfSignupAt, use-claim, no setup invite minted, exactly one passcode_ok attempt row); wrong/expired/revoked/exhausted passcode (each asserting use_count is unchanged); cooldown refusal; duplicate email/username and the case-variant duplicate (each asserting no use claimed); over-length realName; weak password; lowercased storage and echo; a client-supplied role being ignored; a self-signed-up DJ session being unable to self-approve via POST /update-user; and the ordering regression — a garbage passcode returns a byte-identical status and body for a registered and an unregistered email, and logs the passcode_fail row the old order skipped entirely.
• npm run typecheck clean across all workspaces
• npm run lint clean (0 errors; only pre-existing warnings elsewhere in the repo)
• npm run format:check clean
• tests/unit/scripts/ci-env-surface-parity.test.ts updated and passing (the two new auth-only env vars are allow-listed as workflow-only, mirroring DEFAULT_ORG_SLUG/EMAIL_ENABLED)

Follow-up

• station-passcode: write cooldown_refused at most once per cooldown window #2377 — cooldown_refused is written per refused request rather than at most once per cooldown window (BS#2361 step 4). Pre-existing in the lifecycle module from Harden the additionalFields write-protection guard: OIDC rationale is inaccurate and the lock assertion is substring-based #2367; not introduced here.

Closes #2361