Native headless authentication

ENG-2842  and PR #11358  transfer the first-party headless WorkOS flow from Rails to API2. Rails keeps the same endpoints during observation for code-revert rollback; hosted AuthKit is the runtime fallback whenever the existing headless_auth Flipper gate is off or unavailable.

Owned contracts

• GET /accounts/auth/headless and GET /accounts/auth/csrf
• POST /accounts/auth/method and POST /accounts/auth/magic_auth
• POST /accounts/auth/magic_auth/verify
• POST /accounts/auth/password and POST /accounts/auth/signup
• POST /accounts/auth/email_verification/{verify,resend,cancel}
• POST /accounts/auth/password_reset and POST /accounts/auth/password_reset/confirm

The auth feature’s existing client module sends only these requests to API2. No route or navigation behavior changes.

Security and parity contract

• Persist anonymous attempts in public.sessions under Rack’s private session ID, while the browser receives only the random raw ID. Use Rails’ real-token, global-HMAC and one-time-pad CSRF format so retained Rails mutations accept a session created by API2.
• Require the exact configured Origin, the readable XSRF-TOKEN cookie, the matching X-CSRF-TOKEN header and the persisted real token before provider access. The rollout gate protects CSRF setup and every mutation.
• Limit credential/code verification to 10 attempts per IP per minute. Limit Magic Auth, verification resend and password-reset email sends to five per IP plus hashed normalized email per minute. Redis failure fails closed.
• Reuse native hosted-login’s transaction for identity resolution, invited membership provisioning, default organization behavior and atomic session rotation. Deep-link organization slugs are resolved locally, then scoped with the WorkOS refresh token.
• Preserve generic credential errors and enumeration-safe reset requests. Pending email-verification tokens live only in the server session. Duplicate Magic Auth and email-verification code requests recover the session already created by the winning request.
• Preserve Rails cookie names, the shared .rulebase.co domain, staging and production lifetimes and Rails’ 30-day created-at session retention bound. Keep session cookies Secure and HttpOnly; keep the JavaScript-readable XSRF-TOKEN cookie Secure but not HttpOnly.

Structured native_headless_* events may contain a provider error code but never email, password, code, cookie, CSRF value, token, serialized session or provider response.

Rollout and rollback

Deploy API2 and UI from the same revision. UI-first deployment is fail-safe: an absent API2 feature probe selects hosted AuthKit. Before expanding traffic, confirm the regional WorkOS client/cookie configuration and Redis connectivity. Require actual Magic Auth, password fallback, signup, email verification, password reset, tenantless and organization-scoped login evidence in both regions; no Rails headless request; bounded 4xx/5xx and rate limiting; valid subsequent /session; logout/revocation; and 24 clean hours.

For immediate rollback, disable headless_auth so new users use hosted AuthKit. For a code rollback, revert the client/server revision while compatible Rails sessions and endpoints remain. Do not purge sessions or queues, edit account or membership rows, or change provider configuration as part of rollback. Remove the Rails headless actions only after the clean regional bake.