POST /auth/signup  { email, password }
  → validate email format + password strength
  → check duplicate email (409 if exists)
  → rate-limit: 3 signups per email per hour
  → captcha verification (hCaptcha / Cloudflare Turnstile)
  → Argon2id hash password (time=3, mem=64MB, p=4)
  → INSERT np_users (email_verified = FALSE)
  → generate email verification JWT (15-min TTL)
  → send verification email via D4/Postmark (template: signup-verify)
  ← 201 { message: "Check your email to verify your account" }

GET /auth/verify-email?token=<signed JWT>
  → verify JWT signature + TTL (15 min)
  → verify token is single-use (used_at check)
  → UPDATE np_users SET email_verified = TRUE
  → mark token used
  ← 200 redirect to /account

POST /auth/resend-verify  { email }
  → rate-limit: 1 per 60s (dev: 1 per 5s)
  → generate new verification token
  → send email
  ← 200 { message: "Verification email sent" }

POST /auth/signin  { email, password }
  → check email_verified (403 if false)
  → check account lockout (403 if locked: 5 failed attempts → 15-min lockout)
  → Argon2id verify password
  → on success: INSERT np_sessions (expires_at = now + 7 days)
  → issue JWT (RS256, kid = AUTH_JWT_KEY_ID)
      payload: { sub: user_id, email, tenant_id?, source_account_id, exp, iat, session_id }
      Hasura claims namespace: https://hasura.io/jwt/claims
        X-Hasura-User-Id, X-Hasura-Default-Role, X-Hasura-Allowed-Roles
        X-Hasura-Source-Account-Id, X-Hasura-Tenant-Id (if Cloud)
  → set cookie: HttpOnly; SameSite=Lax; Secure; Path=/; Max-Age=604800; Domain=.nself.org
  ← 200 { user: { id, email, email_verified } }

POST /auth/forgot-password  { email }
  → always return 200 (no email enumeration)
  → generate code_verifier (32 random bytes, base64url)
  → code_challenge = BASE64URL(SHA256(code_verifier))
  → INSERT np_password_reset_tokens (code_challenge, expires_at = now + 15 min)
  → send reset email with link containing code_verifier
  ← 200 { message: "If that email is registered, a reset link was sent" }

POST /auth/reset-password  { code_verifier, new_password }
  → recompute code_challenge = BASE64URL(SHA256(code_verifier))
  → look up token WHERE code_challenge = $1 AND used_at IS NULL AND expires_at > now
  → validate (400 if not found, expired, or already used)
  → Argon2id hash new_password
  → UPDATE np_users SET hashed_password = new_hash
  → UPDATE np_password_reset_tokens SET used_at = NOW()
  → REVOKE ALL SESSIONS: UPDATE np_sessions SET revoked_at = NOW() WHERE user_id = $1 AND revoked_at IS NULL
  ← 200 { message: "Password reset. Please sign in with your new password." }

POST /auth/mfa/enroll  (authenticated)
  → generate base32 TOTP secret
  → AES-256-GCM encrypt secret
  → INSERT np_mfa_devices (device_type='totp', totp_secret_enc, verified_at=NULL)
  → generate 8 backup codes; hash each; AES-256-GCM encrypt array
  → INSERT np_mfa_devices (device_type='backup_codes', backup_codes_enc)
  ← 200 { qr_code_url, secret_b32, backup_codes_plaintext }

POST /auth/mfa/verify  (during signin challenge)
  → lookup active TOTP device for user (disabled_at IS NULL, verified_at IS NOT NULL)
  → verify submitted TOTP code against decrypted secret (RFC 6238, ±30s window)
  → rate-limit: 5 failures → 5-min lockout
  → on first verify after enrollment: set verified_at = NOW()
  ← 200 (session elevated to MFA-verified)

POST /auth/mfa/disable  (authenticated, re-auth required)
  → verify current password or valid TOTP
  → UPDATE np_mfa_devices SET disabled_at = NOW() WHERE user_id = $1
  ← 200 { message: "MFA disabled" }

GET /auth/oauth/google   (or /auth/oauth/github)
  → generate state = 32 random bytes
  → state_hash = SHA256(state), hex-encoded
  → INSERT np_oauth_states (state_hash, provider, expires_at = now + 10 min)
  → redirect to provider with state param

GET /auth/callback/:provider?code=...&state=...
  → recompute state_hash = SHA256(state)
  → SELECT from np_oauth_states WHERE state_hash = $1 AND expires_at > now
  → 400 "CSRF validation failed" if not found or expired
  → exchange code for OAuth tokens
  → upsert np_users (email from provider, email_verified = TRUE for verified providers)
  → issue session + JWT (same flow as signin)
  ← redirect to AUTH_MAGIC_LINK_BASE_URL (allowlisted paths only)