RFC: Migrating Authentication to Clerk

Date: 2026-06-23

Status: Accepted (2026-07-02); Revised (2026-07-03) — reworked to the Clerk-blessed client-side integration and invite-code retirement, superseding the BFF/dual-stack decisions. See §Decisions for what changed and why.

Related: Lazy Account Provisioning, Multi-Accounts (A-3402, §2f authorization & API keys — migration complete, plan retired)

AX runs a fully homerolled authentication (authN) stack. It works, but it makes us the maintainers of credential security and — the immediate pain — it gives us a 2FA implementation we have to build, test, and own end to end. We want to lift user creation and human authentication onto Clerk (clerk.com) to get a real, maintained MFA (TOTP + SMS + backup codes) without writing it ourselves, while keeping authorization (authZ) homerolled — the account_permissions ACL the Multi-Accounts work just finished building is ours and stays ours.

This is not greenfield. The codebase already carries a partially-built Clerk integration:

• A Clerk Frontend API (FAPI) client under rs/api-gateway/src/clerk_fapi/ (create_sign_in, create_sign_up, attempt_second_factor, TOTP ops, end_session, change_password), built for the original BFF shape. Under this revision it is retired — the browser talks to Clerk directly, so the server never drives FAPI.
• A Clerk Backend API (BAPI) client under rs/api-gateway/src/clerk/ (#2846): create_user (incl. the password_digest + password_hasher: "argon2id" import form), delete_user, mark_email_verified. Kept — this is the bulk-import and admin surface.
• ClerkConfig (secret_key, frontend_key, frontend_domain, rs/api-gateway/src/clerk/mod.rs), loaded from CLERK_SECRET_KEY / CLERK_PUBLISHABLE_KEY / CLERK_FRONTEND_DOMAIN and threaded through service.rs → state.rs.
• A clerk_id: Option<String> column already on DbUser (rs/sdk-internal/db/src/entities.rs:20, persisted at :83), None for every user today.

The revised shape is Clerk's blessed path: ClerkJS runs in the browser and drives sign-in/sign-up/MFA/reset against Clerk's Frontend API directly, using custom flows (useSignIn/useSignUp hooks) underneath our existing themed auth pages — Clerk owns the protocol, we own every pixel. The only new server-side authN surface is a token-exchange endpoint: the GUI presents a Clerk session JWT once, api-gateway verifies it (JWKS) and mints the AX session token exactly as today. Everything per-request stays AX-owned.

• Clerk owns human credentials and MFA. Password (and optionally social / passkey) login plus a real, maintained 2FA/MFA — TOTP, SMS, backup codes — out of the box. This is the deliverable.
• AX stays the identity-of-record and the authZ authority. The AX users row (keyed by an AX-minted UserId/ULID) remains canonical; Clerk is a linked credential provider via users.clerk_id. Every downstream system — account_id derivation, EP3 username, TigerBeetle ledger ids, every money row — keys on the AX UserId, so it cannot move to Clerk.
• Stay on Clerk's blessed path. The browser integrates ClerkJS directly, so we get Clerk's bot protection, client trust, device tracking, and (fast-follow) social/passkey logins for free instead of re-implementing the sign-in state machine server-side.
• Keep our themed auth pages. Sign-in/sign-up/MFA/reset use Clerk custom flows (headless useSignIn/useSignUp) under the existing GUI screens — no visual regression to Clerk-hosted pages or stock widgets.
• Keep API keys homerolled. Machine auth is out of Clerk's scope and unchanged.
• Migrate existing users without a forced password reset — their Argon2id hashes import directly into Clerk (§7). MFA is disabled today, so there is no enrolled second-factor population to migrate.

• Moving authZ to Clerk. No Clerk Orgs/Roles for permissions; the account_permissions ACL stays ours (Multi-Accounts A-3402 §2f).
• Replacing API keys. Clerk is not a machine-credential system.
• Changing UserId/AccountId derivation. UserId stays an AX ULID; clerk_id is a side-link, not a replacement.
• Account provisioning lifecycle. When the trading account is created is the Lazy Account Provisioning RFC; this RFC governs only user/credential creation and authN. They compose cleanly — and under this revision they depend on each other: open identity signup is acceptable precisely because an identity-only user has no trading account (§3).

Clerk answers "is this human who they say they are (incl. second factor)?" — and under this revision it answers it directly to the browser. AX answers "which AX user is that, and what may they do?" The link is users.clerk_id, established at the token exchange.

Every authenticated request resolves identity through one trait: AuthState::decode_token (token → UserId) and get_user (UserId → DbUser), implemented for AppState at auth.rs:51-66.

§2a stands: Clerk at the auth event, AX session per request. What the revision changes is only where the auth event happens: in the browser via ClerkJS instead of proxied through api-gateway. The handshake:

1. GUI completes a Clerk sign-in (custom flow); ClerkJS holds a Clerk session.
2. GUI calls session.getToken() and POSTs the short-lived Clerk session JWT to a new /login/clerk endpoint.
3. api-gateway verifies the JWT against Clerk's JWKS (cached; iss/azp checked against frontend_domain/publishable key), extracts the Clerk user id (sub), resolves users.clerk_id → UserId (materializing an identity-only row on first touch, §3), and mints the AX opaque session token via the existing TokenManager, setting the ax_token cookie exactly as today.

decode_token is unchanged; there is still no per-request runtime dependency on Clerk — JWKS verification happens only at the exchange moment. API keys, logout/bulk-revocation (session:user:*), IP allowlists, and middleware keep working as-is. The rejected alternative — trusting Clerk JWTs per request — remains rejected for the same reasons as before.

Signup moves entirely into the browser: the GUI's themed sign-up page drives Clerk's useSignUp custom flow (email + password, then Clerk's email verification step; the page renders the clerk-captcha element so Clerk's bot protection applies). There is no AX signup endpoint anymore.

Invite codes retire. They gated identity creation; under the lazy-provisioning RFC the scarce, risk-bearing resource is the funded trading account, which is materialized only at funding/onboarding with its own gates. An identity-only user can log in and look at walls; they cannot trade, deposit, or withdraw. If marketing ever wants scarcity back, Clerk's restricted/invitation-only signup modes can express it at the Clerk layer — no AX tables needed.

AX user materialization happens at first token exchange. When /login/clerk sees a verified Clerk JWT whose sub matches no users.clerk_id, it mints a UserId locally and writes an identity-only DbUser (per the lazy-provisioning RFC — no trading account, no EP3 round-trip) with clerk_id, email, and username from the verified Clerk claims. This replaces the old signup transaction entirely: there is no invite-decrement/Clerk-create/AX-write compensation dance because there is nothing to compensate — Clerk signup and AX materialization are decoupled and each idempotent (clerk_id is unique; a retried exchange converges).

Email verification is enforced by Clerk instance settings (verified email required to complete sign-up), not by AX endpoints. The exchange endpoint additionally refuses JWTs whose email is unverified as a backstop. Imported users are marked verified at import time (§7).

A backstop reconciler (BAPI list-users vs users.clerk_id) sweeps for Clerk-users-never-exchanged and AX-rows-with-dangling-clerk_id; a Clerk user.created/user.deleted webhook is an optional optimization, not load-bearing.

• The GUI's themed login page drives Clerk's useSignIn custom flow: password first factor, then whatever second factor the user has enrolled (TOTP, SMS, backup code) — the flow's needs_second_factor status drives our existing 2FA challenge UI. On completion the GUI performs the token exchange (§2) and the app proceeds with the ax_token cookie exactly as today.
• MFA enrollment is likewise a browser flow (Clerk's TOTP QR provisioning, SMS enrollment, backup-code generation) under our themed settings screens. Where a stock widget is acceptable (e.g. the QR/backup-code modal), Clerk's prebuilt components with the appearance API are permitted; primary auth screens stay fully custom.
• Delete the entire homerolled 2FA path: totp_manager.rs, the enabled_2fa/totp_cipher/nonce columns, the setup_2fa/confirm_2fa/ disable_2fa routes (auth_routes.rs:451-699), the login verify_2fa_if_enabled check (auth.rs:120-152), and the require_2fa/Needs2fa-redirect machinery. This is the working 2FA deliverable. Because MFA is disabled today (no user has an enrolled second factor), this retirement is a pure deletion; Clerk MFA is then switched on as net-new capability.

The AuthenticationMethod::ApiKeySecret path (auth.rs:200-241), key provisioning (provision_api_key), DbApiKey, the read-only/full-access split, and IP allowlists are untouched. Clerk is human-auth; machine credentials remain AX-issued and AX-verified.

AuthenticationMethod::UsernamePassword is deprecated at cutover for programmatic use: once hashed_password verification retires, the gateway can no longer check a password itself, and headless clients cannot drive a browser flow. Machine access is API keys, full stop. If telemetry shows real programmatic username/password usage that cannot move to API keys, the fallback is a thin BAPI verify_password bridge — a decision to make on evidence, not preemptively.

Password reset (forgot-password emailed code) and password change become Clerk custom flows on our themed screens. Retire password_reset_codes and the reset_password route (public_routes.rs:347-442) at cutover. Note: after cutover the server never sees plaintext passwords, so AX's stored hashed_password goes stale as users change passwords — this bounds the rollback window (§7) and is accepted.

Passwords import directly — no reset, no re-hash. hash_secret (rs/sdk-internal/crypto/src/secrets.rs:6-17) is Argon2::default(), which emits a standard Argon2id, v=19, PHC-format digest ($argon2id$v=19$m=…,t=…,p=…$salt$hash). Clerk's Backend API CreateUser accepts exactly this via password_digest + password_hasher: "argon2id", so we feed each user's existing hash verbatim (client already merged, #2846).

The revision replaces the per-user dual-stack window with a per-environment hard cut behind a GUI/env flag:

1. Bulk import (complete, verified). Import every current user with their stored Argon2id digest, mark emails verified, write back clerk_id. Gate on zero unimported rows and spot-check logins in sandbox. Re-run the import diff until clean — the import is idempotent on external_id.
2. Flip the flag (sandbox → demo → prod): the GUI serves the ClerkJS login/ signup flows and the exchange endpoint; homerolled login/signup routes stay deployed but unreached.
3. Rollback = flip the flag back. The homerolled path still works because hashed_password is still populated. The window's known leak: passwords changed via Clerk during the window are not mirrored back to AX, so those users would need a support reset on rollback. Keep the window short and the population informed.
4. Retire (§8) once each environment has run clean.

MFA migration is a non-issue. MFA is disabled today — nothing in totp_cipher/nonce to port. Clerk MFA comes up as net-new after cutover.

• clerk_config presence (backend) + publishable key & flow flag (GUI env) are the switches, per environment (sandbox → demo → prod).
• Post-cutover retirement, in order: homerolled login/signup/reset routes and validate_password; totp_manager.rs + 2FA routes/columns; password_reset_codes; the server-side FAPI client (clerk_fapi/, dead under this shape); invite_codes (table + signup consumption + admin create); finally hashed_password.
• Per CLAUDE.md's lifecycle directive, test the full matrix: signup (Clerk flow
  • first-exchange materialization), login with/without MFA, MFA enrollment, password reset, session revocation/logout (AX-side, unchanged), API-key auth (must remain Clerk-independent), Clerk-down behavior (login/signup unavailable in-browser; exchange 503s; existing AX sessions and API keys keep working), exchange-endpoint abuse (rate limiting, replayed/expired JWTs, unverified email), and flag-flip rollback in sandbox.

• Session model: §2a. AX session tokens stay the per-request credential; Clerk is consulted only at the auth event. AuthState/TokenManager unchanged.
• Email verification: adopted as a requirement for new signups, owned by Clerk. Imported users are marked verified at import.
• Lifecycle parity: none. is_frozen (and freeze/close-only generally) is an AX authZ concern only — we do not mirror it into Clerk suspension. No sync job, no second source of truth.
• Clerk as a hard dependency: accepted. Login/signup fail closed during a Clerk outage; existing AX sessions and API keys are unaffected.
• FAPI BFF and Backend API: both. Superseded 2026-07-03.

• Client-side ClerkJS, not BFF. The browser drives Clerk directly via custom flows; api-gateway's only authN addition is the token exchange. The BFF's justifications fell away: the invite gate is retired (below), the dual-stack per-user branch is replaced by a per-env flag flip, and §2a never actually required proxying — only an exchange. What we gain: Clerk's bot protection/client trust (impossible server-side), a supported integration instead of headless-FAPI fragility, and a clean runway to social/passkeys.
• Invite codes: retired. Identity signup opens; the gate moves to account materialization per the lazy-provisioning RFC. Clerk restrictions remain available if gating at the identity layer is ever wanted again.
• Hard cut, not dual-stack. Bulk import is complete and verified before the flip; rollback is the flag, bounded by the password-change leak (§7.3). The dual-stack login branch (PR #2850) is superseded and not merged.
• Custom flows over prebuilt widgets for primary auth screens (login, signup, reset, MFA challenge) — our themed pages persist unchanged in look. Prebuilt + appearance theming is acceptable for secondary surfaces (MFA enrollment modals) at implementer's discretion.
• UsernamePassword programmatic auth: deprecated at cutover (§5); machine auth is API keys. BAPI verify_password bridge only if usage evidence demands it.

• Social / passkey logins. Now nearly free on the blessed path — fast-follow after cutover: enable providers in Clerk, add buttons to the custom flow.
• Institutional / treasurer accounts. The multi-account "one human, several accounts" pattern (Multi-Accounts A-3402 §2e) could later map to Clerk Orgs, but authZ stays in account_permissions. Out of scope; noted.
• Clerk Elements. If the custom-flow hook surface proves verbose, Clerk Elements (styleable primitives) is a middle path worth evaluating for the reset/enrollment screens.