refactor: reduce mid-tier oversized functions across services (#2028)

* refactor(current-account): reduce oversized functions

Extract helpers from 15 oversized functions in the current-account
service layer including saga handlers, valuation engine, orchestrators,
and gRPC endpoints.

* refactor(payment-order): reduce oversized functions

Extract helpers from saga handlers, orchestrator ledger/lien/saga,
gRPC lifecycle and update endpoints, and invoice generator.

* refactor(position-keeping): reduce oversized functions

Extract helpers from persistence repositories, balance service,
gRPC log endpoints, and initiation handlers.

* refactor(reconciliation): reduce oversized functions

Extract helpers from gRPC endpoints, pipeline service, balance
assertor, variance detector, settlement ingestor, and snapshot capturer.

* refactor(control-plane): reduce oversized functions

Extract helpers from applier, generator, manifest handler, validators,
staff service, stripe webhook/reconciliation, and balance sheet.

* refactor(internal-account): reduce oversized functions

Extract helpers from persistence mappers/repository, gRPC endpoints,
lien service, valuation engine, and valuation feature service.

* refactor(tenant): reduce oversized functions

Extract helpers from provisioner, gRPC endpoints, alerting worker,
and provisioning worker.

* refactor(shared): reduce oversized functions

Extract helpers from saga executor, step execution, causation tree,
starlark runner, valuation runtime, audit, and auth config.

* refactor(services): reduce oversized functions in smaller services

Extract helpers from mcp-server, audit-worker, event-router,
financial-accounting, financial-gateway, forecasting, identity,
and party services.

* refactor(control-plane): fix build errors and reduce more oversized functions

Fix type references in export.go and webhook.go, add missing fmt import,
and reduce additional oversized functions in validators and generators.

* refactor: reduce oversized functions in remaining services

Extract helpers from payment-order, position-keeping, reference-data,
party, and shared/platform packages.

* fix: resolve lint errors and additional oversized function reductions

- Fix gofmt formatting in 3 files
- Fix unused parameters (revive)
- Fix context-as-argument ordering (revive)
- Replace dynamic errors with sentinels (err113)
- Add nolint directives for intentional nil returns (nilerr, nilnil)
- Fix unchecked error returns (errcheck)
- Add nolint:contextcheck for false positives from helper extraction
- Remove stale nolint directives (nolintlint)
- Fix indent-error-flow (revive)
- Fix syntax error in api-gateway (func type)
- Fix type mismatch in api-gateway health init
- Additional function size reductions across services

Violations reduced from 284 to 196 (additional 88 eliminated).

* fix: resolve test failures and remaining lint issues

Test fixes (restore original behavior after helper extraction):
- payment-order: restore per-posting error message prefixes
- operational-gateway: add nil guard after route resolution failure
- position-keeping: propagate account validation errors properly
- tenant: preserve capitalized alert type names in log messages
- financial-accounting: use distinct error for idempotency re-check
- kafka: check context cancellation before DLQ on retry failure

Lint fixes:
- Add sentinel errors for dynamic error strings (err113)
- Fix context-as-argument parameter ordering (revive)
- Add missing switch case for StatusFailed (exhaustive)
- Fix defer-in-loop pattern (gocritic)
- Apply De Morgan's law and loop condition lift (staticcheck)
- Add nolint directives for intentional nil returns (nilnil)
- Fix nolint placement and gofmt formatting

* fix: resolve remaining lint issues

- Add nolint:nilnil for intentional nil,nil returns in payment-order
- Fix context-as-argument ordering in api-gateway auth handler
- Rename unused 'key' parameter to '_' in position-keeping migration

* fix: add nolint:nilnil for remaining intentional nil returns

* fix: restore review-critical behavioral regressions in refactored code

- Fix CancelFunc leak in buildFreshContext: return CancelFunc so callers
  can defer cancel(), preventing distributed locks held until timeout expiry
- Restore per-flow RECONCILIATION_REQUIRED log fields lost during
  capturePosting unification: debtor_account, contra_account,
  clearing_account, and has_*_posting progress booleans needed for
  incident response
- Fix LedgerEntryCount semantic change in reconciliation: use raw entry
  count (pre-dedup) instead of deduplicated map length to match original

* fix: preallocate log field slices to satisfy prealloc lint

* chore: trigger re-review after thread resolution

* docs: clarify buildFreshContext godoc on why fresh context is needed

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

services/api-gateway/auth_handler.go

@@ -1,10 +1,13 @@
 package gateway
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"log/slog"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/meridianhub/meridian/services/identity/connector"
@@ -116,28 +119,35 @@ func (h *AuthHandler) HandleLogin(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Validate credentials via the identity connector.
-	identity, valid, err := h.connector.Login(ctx, nil, req.Email, req.Password)
+	// Validate credentials and sign JWT.
+	tokenStr, identity, err := h.authenticateAndSign(ctx, tenantID, req)
 	if err != nil {
-		h.logger.ErrorContext(ctx, "auth: login error",
-			"tenant_id", tenantID,
-			"error", err)
-		writeJSON(w, http.StatusInternalServerError, map[string]string{
-			"error": "authentication service error",
-		})
+		h.handleLoginError(ctx, w, tenantID, err)
 		return
 	}
+
+	h.logger.InfoContext(ctx, "auth: login successful",
+		"tenant_id", tenantID,
+		"identity_id", identity.UserID)
+
+	writeJSON(w, http.StatusOK, loginResponse{
+		AccessToken: tokenStr,
+		TokenType:   "Bearer",
+		ExpiresIn:   int(h.tokenTTL.Seconds()),
+	})
+}
+
+// authenticateAndSign validates credentials and returns a signed JWT token.
+func (h *AuthHandler) authenticateAndSign(ctx context.Context, tenantID tenant.TenantID, req loginRequest) (string, connector.Identity, error) {
+	identity, valid, err := h.connector.Login(ctx, nil, req.Email, req.Password)
+	if err != nil {
+		return "", connector.Identity{}, fmt.Errorf("login: %w", err)
+	}
 	if !valid {
-		writeJSON(w, http.StatusUnauthorized, map[string]string{
-			"error": "invalid email or password",
-		})
-		return
+		return "", connector.Identity{}, errInvalidCredentials
 	}
 
-	// Build claims and sign JWT.
 	claims := connector.BuildClaims(identity, tenantID)
-	// Include the tenant slug for frontend subdomain routing. The slug differs
-	// from the tenant ID (e.g. slug "volterra-energy" vs ID "volterra_energy").
 	if slug, ok := tenant.SlugFromContext(ctx); ok && slug != "" {
 		claims[tenant.TenantSlugKey] = slug
 	}
@@ -146,24 +156,35 @@ func (h *AuthHandler) HandleLogin(w http.ResponseWriter, r *http.Request) {
 	}
 	tokenStr, err := h.signer.SignClaims(claims, h.tokenTTL)
 	if err != nil {
+		return "", identity, fmt.Errorf("sign: %w", err)
+	}
+
+	return tokenStr, identity, nil
+}
+
+// errInvalidCredentials is a sentinel for invalid email/password.
+var errInvalidCredentials = errors.New("invalid credentials")
+
+// handleLoginError maps authenticateAndSign errors to HTTP responses.
+func (h *AuthHandler) handleLoginError(ctx context.Context, w http.ResponseWriter, tenantID tenant.TenantID, err error) {
+	if errors.Is(err, errInvalidCredentials) {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{
+			"error": "invalid email or password",
+		})
+		return
+	}
+	if strings.HasPrefix(err.Error(), "sign:") {
 		h.logger.ErrorContext(ctx, "auth: failed to sign token",
-			"tenant_id", tenantID,
-			"identity_id", identity.UserID,
-			"error", err)
+			"tenant_id", tenantID, "error", err)
 		writeJSON(w, http.StatusInternalServerError, map[string]string{
 			"error": "failed to create session",
 		})
 		return
 	}
-
-	h.logger.InfoContext(ctx, "auth: login successful",
-		"tenant_id", tenantID,
-		"identity_id", identity.UserID)
-
-	writeJSON(w, http.StatusOK, loginResponse{
-		AccessToken: tokenStr,
-		TokenType:   "Bearer",
-		ExpiresIn:   int(h.tokenTTL.Seconds()),
+	h.logger.ErrorContext(ctx, "auth: login error",
+		"tenant_id", tenantID, "error", err)
+	writeJSON(w, http.StatusInternalServerError, map[string]string{
+		"error": "authentication service error",
 	})
 }
 

services/api-gateway/auth_sso_handler.go

@@ -47,6 +47,9 @@ var (
 	ErrSSOCallbackURLInvalid = errors.New("sso handler: callback URL must be a valid absolute URL")
 	// ErrSSODexIssuerInvalid is returned when the Dex issuer URL is not a valid absolute URL.
 	ErrSSODexIssuerInvalid = errors.New("sso handler: dex issuer URL must be an absolute URL with scheme and host")
+
+	// errNoMatchingAccount is returned when SSO identity resolution finds no matching account.
+	errNoMatchingAccount = errors.New("no matching account")
 )
 
 // IdentityResolver resolves an identity by email without password validation.
@@ -200,18 +203,34 @@ func (h *SSOHandler) HandleInitiate(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Generate PKCE code verifier (43-128 chars of unreserved URI chars per RFC 7636).
-	codeVerifier, err := generateCodeVerifier()
+	stateKey, codeChallenge, err := h.generatePKCEState(ctx, r, tenantID)
 	if err != nil {
-		h.logger.ErrorContext(ctx, "sso: failed to generate code verifier", "error", err)
+		h.logger.ErrorContext(ctx, "sso: failed to generate PKCE state", "error", err)
 		writeJSON(w, http.StatusInternalServerError, map[string]string{
 			"error": "failed to initiate SSO",
 		})
 		return
 	}
 
-	codeChallenge := computeCodeChallenge(codeVerifier)
+	tenantSlug, _ := tenant.SlugFromContext(ctx)
+	redirectURL := h.buildInitiateRedirectURL(tenantSlug, connectorID, stateKey, codeChallenge)
 
+	h.logger.InfoContext(ctx, "sso: initiating SSO flow",
+		"tenant_id", tenantID,
+		"connector_id", connectorID)
+
+	http.Redirect(w, r, redirectURL, http.StatusFound)
+}
+
+// generatePKCEState generates PKCE parameters and stores the SSO state.
+// Returns the state key, code challenge, or an error.
+func (h *SSOHandler) generatePKCEState(ctx context.Context, r *http.Request, tenantID tenant.TenantID) (string, string, error) {
+	codeVerifier, err := generateCodeVerifier()
+	if err != nil {
+		return "", "", fmt.Errorf("generate code verifier: %w", err)
+	}
+
+	codeChallenge := computeCodeChallenge(codeVerifier)
 	returnURL := sanitizeReturnURL(r.URL.Query().Get("return_url"))
 
 	tenantSlug, _ := tenant.SlugFromContext(ctx)
@@ -224,17 +243,15 @@ func (h *SSOHandler) HandleInitiate(w http.ResponseWriter, r *http.Request) {
 		ReturnURL:         returnURL,
 	})
 	if err != nil {
-		h.logger.ErrorContext(ctx, "sso: failed to store state", "error", err)
-		writeJSON(w, http.StatusInternalServerError, map[string]string{
-			"error": "failed to initiate SSO",
-		})
-		return
+		return "", "", fmt.Errorf("store state: %w", err)
 	}
 
-	// Build Dex authorization URL. When baseDomain is configured, the redirect
-	// uses a tenant-scoped URL so that the Dex MeridianConnector receives tenant
-	// context via the subdomain. Path-escape the connector ID to prevent
-	// path traversal (e.g., "../../admin" → "%2E%2E%2Fadmin").
+	return stateKey, codeChallenge, nil
+}
+
+// buildInitiateRedirectURL constructs the full Dex authorization redirect URL
+// with PKCE parameters, state, and scopes.
+func (h *SSOHandler) buildInitiateRedirectURL(tenantSlug, connectorID, stateKey, codeChallenge string) string {
 	authURL := h.buildDexAuthURL(tenantSlug, connectorID)
 	params := url.Values{
 		"client_id":             {h.clientID},
@@ -245,14 +262,7 @@ func (h *SSOHandler) HandleInitiate(w http.ResponseWriter, r *http.Request) {
 		"code_challenge":        {codeChallenge},
 		"code_challenge_method": {"S256"},
 	}
-
-	redirectURL := authURL + "?" + params.Encode()
-
-	h.logger.InfoContext(ctx, "sso: initiating SSO flow",
-		"tenant_id", tenantID,
-		"connector_id", connectorID)
-
-	http.Redirect(w, r, redirectURL, http.StatusFound)
+	return authURL + "?" + params.Encode()
 }
 
 // HandleCallback handles GET /api/auth/callback.
@@ -298,69 +308,10 @@ func (h *SSOHandler) HandleCallback(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Exchange authorization code for tokens with Dex.
-	idToken, err := h.exchangeCode(ctx, code, stateData.CodeVerifier)
-	if err != nil {
-		h.logger.ErrorContext(ctx, "sso: token exchange failed",
-			"tenant_id", stateData.TenantID,
-			"error", err)
-		writeJSON(w, http.StatusBadGateway, map[string]string{
-			"error": "SSO token exchange failed",
-		})
-		return
-	}
-
-	// Parse the email from Dex's ID token (we trust the claims since we got them
-	// directly from the token endpoint over a server-to-server connection).
-	email, err := extractEmailFromIDToken(idToken)
-	if err != nil {
-		h.logger.ErrorContext(ctx, "sso: failed to extract email from ID token",
-			"tenant_id", stateData.TenantID,
-			"error", err)
-		writeJSON(w, http.StatusBadGateway, map[string]string{
-			"error": "failed to process SSO identity",
-		})
-		return
-	}
-
-	// Resolve the identity in Meridian's identity store to get roles and tenant context.
-	tenantCtx := tenant.WithTenant(ctx, stateData.TenantID)
-	identity, found, err := h.resolver.Resolve(tenantCtx, email)
-	if err != nil {
-		h.logger.ErrorContext(ctx, "sso: identity resolution error",
-			"tenant_id", stateData.TenantID,
-			"error", err)
-		writeJSON(w, http.StatusInternalServerError, map[string]string{
-			"error": "failed to resolve identity",
-		})
-		return
-	}
-	if !found {
-		h.logger.WarnContext(ctx, "sso: no matching identity for SSO email",
-			"tenant_id", stateData.TenantID)
-		writeJSON(w, http.StatusForbidden, map[string]string{
-			"error": "no matching account for this SSO identity",
-		})
-		return
-	}
-
-	// Sign Meridian JWT.
-	claims := connector.BuildClaims(identity, stateData.TenantID)
-	if stateData.TenantSlug != "" {
-		claims[tenant.TenantSlugKey] = stateData.TenantSlug
-	}
-	if stateData.TenantDisplayName != "" {
-		claims[tenant.TenantDisplayNameKey] = stateData.TenantDisplayName
-	}
-	tokenStr, err := h.signer.SignClaims(claims, h.tokenTTL)
+	// Exchange code, resolve identity, and sign JWT.
+	identity, tokenStr, err := h.exchangeAndResolve(ctx, code, stateData)
 	if err != nil {
-		h.logger.ErrorContext(ctx, "sso: failed to sign token",
-			"tenant_id", stateData.TenantID,
-			"identity_id", identity.UserID,
-			"error", err)
-		writeJSON(w, http.StatusInternalServerError, map[string]string{
-			"error": "failed to create session",
-		})
+		h.handleCallbackError(ctx, w, stateData, err)
 		return
 	}
 
@@ -387,6 +338,99 @@ func (h *SSOHandler) HandleCallback(w http.ResponseWriter, r *http.Request) {
 	http.Redirect(w, r, redirectURL, http.StatusFound)
 }
 
+// callbackStage identifies which step of the SSO callback failed.
+type callbackStage int
+
+const (
+	callbackStageTokenExchange callbackStage = iota
+	callbackStageEmailExtract
+	callbackStageIdentityResolve
+	callbackStageIdentityNotFound
+	callbackStageSignToken
+)
+
+// callbackError wraps an error with the stage at which the callback failed.
+type callbackError struct {
+	stage callbackStage
+	err   error
+}
+
+func (e *callbackError) Error() string { return e.err.Error() }
+func (e *callbackError) Unwrap() error { return e.err }
+
+// exchangeAndResolve exchanges the authorization code for tokens, extracts the
+// email from the ID token, resolves the identity, and signs a Meridian JWT.
+func (h *SSOHandler) exchangeAndResolve(ctx context.Context, code string, state StateData) (connector.Identity, string, error) {
+	idToken, err := h.exchangeCode(ctx, code, state.CodeVerifier)
+	if err != nil {
+		return connector.Identity{}, "", &callbackError{stage: callbackStageTokenExchange, err: err}
+	}
+
+	email, err := extractEmailFromIDToken(idToken)
+	if err != nil {
+		return connector.Identity{}, "", &callbackError{stage: callbackStageEmailExtract, err: err}
+	}
+
+	tenantCtx := tenant.WithTenant(ctx, state.TenantID)
+	identity, found, err := h.resolver.Resolve(tenantCtx, email)
+	if err != nil {
+		return connector.Identity{}, "", &callbackError{stage: callbackStageIdentityResolve, err: err}
+	}
+	if !found {
+		return connector.Identity{}, "", &callbackError{stage: callbackStageIdentityNotFound, err: errNoMatchingAccount}
+	}
+
+	tokenStr, err := h.signCallbackToken(identity, state)
+	if err != nil {
+		return connector.Identity{}, "", &callbackError{stage: callbackStageSignToken, err: err}
+	}
+
+	return identity, tokenStr, nil
+}
+
+// signCallbackToken builds claims and signs a Meridian JWT for the SSO callback.
+func (h *SSOHandler) signCallbackToken(identity connector.Identity, state StateData) (string, error) {
+	claims := connector.BuildClaims(identity, state.TenantID)
+	if state.TenantSlug != "" {
+		claims[tenant.TenantSlugKey] = state.TenantSlug
+	}
+	if state.TenantDisplayName != "" {
+		claims[tenant.TenantDisplayNameKey] = state.TenantDisplayName
+	}
+	return h.signer.SignClaims(claims, h.tokenTTL)
+}
+
+// handleCallbackError maps a callbackError to the appropriate HTTP response.
+func (h *SSOHandler) handleCallbackError(ctx context.Context, w http.ResponseWriter, state StateData, err error) {
+	var cbErr *callbackError
+	if !errors.As(err, &cbErr) {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "internal error"})
+		return
+	}
+	switch cbErr.stage {
+	case callbackStageTokenExchange:
+		h.logger.ErrorContext(ctx, "sso: token exchange failed",
+			"tenant_id", state.TenantID, "error", cbErr.err)
+		writeJSON(w, http.StatusBadGateway, map[string]string{"error": "SSO token exchange failed"})
+	case callbackStageEmailExtract:
+		h.logger.ErrorContext(ctx, "sso: failed to extract email from ID token",
+			"tenant_id", state.TenantID, "error", cbErr.err)
+		writeJSON(w, http.StatusBadGateway, map[string]string{"error": "failed to process SSO identity"})
+	case callbackStageIdentityResolve:
+		h.logger.ErrorContext(ctx, "sso: identity resolution error",
+			"tenant_id", state.TenantID, "error", cbErr.err)
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "failed to resolve identity"})
+	case callbackStageIdentityNotFound:
+		h.logger.WarnContext(ctx, "sso: no matching identity for SSO email",
+			"tenant_id", state.TenantID)
+		writeJSON(w, http.StatusForbidden, map[string]string{"error": "no matching account for this SSO identity"})
+	case callbackStageSignToken:
+		h.logger.ErrorContext(ctx, "sso: failed to sign token",
+			"tenant_id", state.TenantID, "error", cbErr.err)
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "failed to create session"})
+	}
+}
+
 // buildDexAuthURL constructs the Dex authorization URL. When baseDomain is
 // configured and a slug is provided, the URL includes the tenant slug as a
 // subdomain prefix so that the MeridianConnector can resolve tenant context