feat(sso): OIDC login service foundation — state cookie, callback flow, identity matching (V2-272 chunk A)

[Nic-dorman]

Summary

First of four PRs implementing the SSO login flow (V2-272). V2-272 was ~60% done on master — oidc_providers / oidc_identities tables + admin CRUD exist — this lands the missing service layer that handles authorize → IdP → callback + identity matching. Chunk B will mount HTTP handlers on top.

Deps

• github.com/coreos/go-oidc/v3 — OIDC discovery + ID-token verification
• golang.org/x/oauth2 — code exchange with PKCE-S256

Schema

Migration 004_oidc_provisioning.sql (sqlite + postgres):

• oidc_providers.default_group_id — FK → groups, nullable
• oidc_providers.auto_provision — bool, default false so a misconfigured provider can't silently grow the user table

Service layer (internal/services/oidc_login.go)

BuildAuthorizeURL(providerID, opts) → returns the IdP redirect URL + the opaque encrypted-cookie value the caller must set on the response. Generates state (32 random bytes hex), nonce (same), PKCE verifier via oauth2.GenerateVerifier(), runs OIDC discovery, builds the authorize URL with S256 challenge.

HandleCallback(cookieValue, queryState, code) → completes the exchange, validates the ID token (signature via JWKS, issuer, audience, nonce, exp), and resolves the identity. Returns a CallbackOutcome distinguishing login vs linking flows.

Identity matching tree (per V2-272 decisions):

1. (provider_id, sub) hit → log in as that user
2. users.external_id == sub → auto-link (SCIM correlation) + log in
3. auto_provision=false → ErrOIDCNoAccount
4. auto_provision=true + email already used → ErrOIDCEmailCollision (the explicit email-confusion guard — never auto-link by email)
5. auto_provision=true + email free → create user via CreateFromSCIM + LinkIdentity + AddMember(default_group_id), log in

Linking flow: when LinkToUserID is set on the cookie, the callback creates an oidc_identities row for that user and skips the login decision entirely.

UnlinkIdentity refuses to leave the user with no login method (no password AND only one identity).

State cookie

JSON payload {provider_id, state, nonce, code_verifier, redirect_url, link_to_user_id?, exp} → AES-256-GCM via existing internal/crypto (reuses wallet_encryption_key — no separate secret to provision) → base64url for the cookie value. 10-minute TTL. Tampering and wrong-key decryption both fail closed via the GCM auth tag.

Tests — 19 active + 1 skipped

Group	Tests
Cookie	round-trip, tampered rejected, wrong-key rejected
Helpers	splitScopes (auto-prepends openid), splitName fallbacks
LinkIdentity	idempotent, rejects-different-user
UnlinkIdentity	rejects-last, allows-with-password, allows-multiple-identities, rejects-foreign
HandleCallback	existing-identity login, SCIM auto-link by externalId, no_account when auto-provision off, email-collision guard, state mismatch, expired cookie, nonce mismatch, linking flow

The HandleCallback tests run against an in-memory fake IdP (httptest + go-jose RSA signer with JWKS) so they exercise the full discovery → exchange → verify pipeline without external deps. Chunk D layers a real Dex container on top of this for the handler+browser integration test.

TestHandleCallback_AutoProvisionsNewUserWithDefaultGroup is t.Skip-ped with a clear pointer to V2-273 (PR #27). The auto-provision path calls groupSvc.AddMember(..., 0) and on master that 0 trips a FK violation against users(id). V2-273 maps 0 → SQL NULL via nullableAddedBy(); once it merges, drop the skip.

Test plan

• go test ./internal/services/ — all green (19 new + skipped + existing)
• go test ./internal/handlers/ ./internal/worker/ — no regressions
• go build ./... clean
• CI Postgres matrix green (new migration applies cleanly on both dialects)

Next

• Chunk B — GET /api/v2/auth/oidc/{providers,authorize/{id},callback} + link/unlink handlers
• Chunk C — LoginView.vue SSO buttons, profile connected accounts, admin auto-provision toggle in SettingsView
• Chunk D — Dex CI service container + Playwright E2E for the happy path

🤖 Generated with Claude Code