feat(auth): add OIDC/SSO login support (e.g. Authentik)

[KeplerAeroIT]

Summary

Adds OpenID Connect (OIDC) login as an alternative/companion to the existing local email+password auth, so ConvertX can be deployed behind an identity provider such as Authentik, Keycloak, Zitadel, or any standards-compliant OIDC issuer — useful for orgs that want centralized login/SSO instead of managing separate ConvertX accounts.

It uses the standard authorization-code flow with PKCE (via openid-client) and slots in alongside the existing session system: a successful OIDC login mints the exact same JWT cookie that password login does, so every existing authenticated route (history, conversions, account, etc.) works completely unchanged.

How it works

• GET /login/oidc — starts the flow (PKCE verifier/state/nonce stored in a short-lived, scoped cookie) and redirects to the provider.
• GET /login/oidc/callback — exchanges the code, validates state/nonce, reads the ID token claims (falling back to the userinfo endpoint if the email claim isn't in the ID token), then:
  • looks up the local user by OIDC sub,
  • auto-links to an existing local account with a matching email if one exists,
  • otherwise auto-provisions a new local user (with an unusable random password, since local password login stays disabled for that account).
• The /login page shows a "Login with {OIDC_NAME}" button below the existing form (separated by a divider) whenever OIDC is configured.

Configuration

All new behavior is opt-in and controlled entirely by environment variables — nothing changes for existing deployments that don't set them.

Name	Default	Description
OIDC_ISSUER		The provider's issuer URL, e.g. https://authentik.example.com/application/o/convertx/
OIDC_CLIENT_ID		OAuth2/OIDC client ID
OIDC_CLIENT_SECRET		OAuth2/OIDC client secret
OIDC_REDIRECT_URI		Public callback URL registered with the provider, e.g. https://convertx.example.com/login/oidc/callback
OIDC_SCOPES	openid profile email	Scopes requested from the provider
OIDC_NAME	SSO	Button label, e.g. Authentik
OIDC_ONLY	false	Hides local email/password login and registration entirely, so OIDC is the only way in

Setting OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_REDIRECT_URI together enables the button; nothing else needs to change.

Example (Authentik)

1. Create an OAuth2/OpenID Provider in Authentik (confidential client), set its redirect URI to https://convertx.example.com/login/oidc/callback, and bind it to an Application.
2. Set the env vars above using the client ID/secret from that provider and the provider's issuer URL.
3. Restart ConvertX — the login page now shows a "Login with Authentik" button.

Full walkthrough and the env var table are added to the README.

Database

Adds a nullable oidc_sub column to the users table (schema version bumped to 2, with an automatic migration for existing installs — no action needed on upgrade).

Testing

• tsc --noEmit / eslint — no new errors introduced (verified against the existing pre-existing warnings/errors baseline).
• Built and ran the full Docker image locally against a real Authentik instance: verified OIDC discovery succeeds at startup, GET /login/oidc redirects to Authentik with correct client_id/PKCE challenge/state/nonce/redirect_uri, and a full login round-trip (including auto-provisioning the first user) works end-to-end.
• Verified the OIDC_ONLY gate hides local login/registration and bypasses the first-run local setup page, and that the hybrid case (local form + SSO button, separated by a divider) renders correctly.

Notes

• Local password login is unaffected when OIDC isn't configured.
• When OIDC_ONLY is not set, existing local accounts keep working alongside SSO, and accounts are linked by email on first SSO login.

---

Summary by cubic

Add OpenID Connect (OIDC) SSO login alongside email/password using Authorization Code + PKCE via openid-client. It issues the same JWT cookie, auto-migrates the DB to v3, and adds a prod compose + .env.example for simpler config.

• New Features

  • OIDC routes: GET /login/oidc and /login/oidc/callback.
  • Login page shows “Login with {OIDC_NAME}”; OIDC_ONLY=true hides the local form and Register links.
  • Account handling: match by (issuer, sub); auto-link by verified email; auto-provision on first SSO login.
  • Deployment: added .env.example and docker-compose.prod.yml; README documents OIDC setup and env vars.

• Bug Fixes

  • Fix redirect_uri mismatches behind reverse proxies by building the callback URL from OIDC_REDIRECT_URI.
  • Make OIDC discovery non-blocking with auto-retry; only show the SSO button when discovery succeeds.
  • Hardened auth: safe cookie format/validation for the OIDC flow; link by verified email only; prevent duplicate first-logins with a unique (issuer, sub) identity and ON CONFLICT insert.
  • Correct TZ example in compose.yaml (Asia/Kolkata) to avoid runtime errors.

^{Written for commit eede2cb. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 12 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[KeplerAeroIT]

Addressed all findings from @cubic-dev-ai's review in ba87632:

• compose.yaml TZ typo (P1): fixed Asia/Koltaka -> Asia/Kolkata. Confirmed the invalid zone does throw at runtime and breaks the history page's date formatting.
• Dead Register link under OIDC_ONLY (P3): accountRegistration is now ACCOUNT_REGISTRATION && !OIDC_ONLY everywhere Header is rendered.
• SSO button shown even when discovery failed (P3): moved discovery into a shared helper exposing isOidcReady(), and the login page now gates the button/divider on actual discovery success instead of just env-var presence.
• Malformed oidcFlow cookie could 500 (P2): this was actually the same bug hit in real-world testing - Elysia's cookie parser auto-JSON.parses any cookie value shaped like {...}/[...], so the JSON-encoded flow cookie was silently turned into an object and rejected by its own schema before the handler ever ran. Switched to a dot-delimited string (PKCE verifier/state/nonce are base64url, so . is a safe delimiter) with explicit shape validation instead of a bare JSON.parse.
• Cross-issuer sub collision (P1): identity is now keyed on the (issuer, sub) pair, not sub alone.
• Unverified-email account takeover (P1): auto-linking to an existing local account by email now requires the provider to have asserted email_verified.
• Race condition on concurrent first logins (P2): added a unique index on (oidc_issuer, oidc_sub) and switched provisioning to INSERT ... ON CONFLICT DO NOTHING + re-select, so concurrent logins for the same new identity can't create duplicate rows.

Also added docker-compose.prod.yml + a fully documented .env.example for a single-file production config workflow.

All changes verified with tsc --noEmit/eslint (no new errors) and a live end-to-end run against a real Authentik instance, including reproducing the exact cookie-validation crash from testing and confirming it's now a clean redirect.

[cubic-dev-ai]

All reported issues were addressed across 10 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[KeplerAeroIT]

Two more fixes in e62830c:

• Redirect URI mismatch behind reverse proxies/tunnels: found this live while deploying through a Cloudflare Tunnel. openid-client derives the redirect_uri it sends to the token endpoint from the callback request's own URL (stripped of query/hash), not from the configured OIDC_REDIRECT_URI. Behind any proxy/tunnel that terminates TLS and forwards to the origin over plain HTTP, the app saw http:// even though the browser used https://, so the token exchange's redirect_uri never matched what's registered with the provider (confirmed via the provider's own server-side logs: expected https://..., got http://...). Now the callback URL passed to authorizationCodeGrant is built from the trusted OIDC_REDIRECT_URI, with only the query string (code, state) taken from the actual request.
• @cubic-dev-ai: valid finding on oidcClient.ts - discovery was on a top-level await, and discovery()'s own default timeout is 30s, so an unreachable/stalled issuer delayed the whole server from binding its port (and failing health checks), even for deployments not otherwise depending on OIDC yet. Moved it to a fire-and-forget retry loop; verified by starting a container with an intentionally unreachable issuer - the server now responds in ~2s instead of blocking, and discovery retries in the background until it succeeds.

Both verified against a real Authentik instance / real proxy setup, plus tsc --noEmit/eslint clean.

[cubic-dev-ai]

Two more fixes in e62830c:

• Redirect URI mismatch behind reverse proxies/tunnels: found this live while deploying through a Cloudflare Tunnel. openid-client derives the redirect_uri it sends to the token endpoint from the callback request's own URL (stripped of query/hash), not from the configured OIDC_REDIRECT_URI. Behind any proxy/tunnel that terminates TLS and forwards to the origin over plain HTTP, the app saw http:// even though the browser used https://, so the token exchange's redirect_uri never matched what's registered with the provider (confirmed via the provider's own server-side logs: expected https://..., got http://...). Now the callback URL passed to authorizationCodeGrant is built from the trusted OIDC_REDIRECT_URI, with only the query string (code, state) taken from the actual request.
• @cubic-dev-ai: valid finding on oidcClient.ts - discovery was on a top-level await, and discovery()'s own default timeout is 30s, so an unreachable/stalled issuer delayed the whole server from binding its port (and failing health checks), even for deployments not otherwise depending on OIDC yet. Moved it to a fire-and-forget retry loop; verified by starting a container with an intentionally unreachable issuer - the server now responds in ~2s instead of blocking, and discovery retries in the background until it succeeds.

...

@KeplerAeroIT Both look right to me. The redirect_URI fix is the kind of thing you only catch when you actually run it through a real TLS-terminating proxy — openid-client's default behavior makes sense for a non-proxied setup but it's a footgun behind a tunnel. Building the callback URL from the configured URI with the real request's query string is the correct approach.

The discovery fix is also solid. Blocking server startup on a 30s timeout (the default for discovery()) is a hard no for production, especially for deployments that don't even use OIDC but have the env vars set. The fire-and-forget retry loop with a shared isOidcReady() guard handles both cases cleanly.

Good catches, clean fixes.

_{Tip: get faster answers by chatting with cubic’s review copilot in the review UI}