feat: Wrap Spring Security 7 MFA in simple user.mfa.* properties (#272)

* feat: wrap Spring Security 7 MFA in simple user.mfa.* properties (#268)

Add opt-in MFA configuration that wraps Spring Security 7's built-in
multi-factor authentication infrastructure behind simple user.mfa.*
properties, consistent with how passkeys are wrapped via user.webauthn.*.

New files:
- MfaConfigProperties: @ConfigurationProperties for user.mfa.* prefix
  with enabled toggle, factors list, and entry point URIs
- MfaConfiguration: unconditional config that registers properties;
  conditional DefaultAuthorizationManagerFactory bean with
  AllRequiredFactorsAuthorizationManager; startup validation via
  @eventlistener for factor/webauthn consistency checks
- MfaStatusResponse: DTO reporting required/satisfied/missing factors
- MfaAPI: REST controller at /user/mfa/status accessible to
  partially-authenticated users

Modified files:
- WebSecurityConfig: MFA config properties injection, setupMfa() method
  configuring DelegatingMissingAuthorityAccessDeniedHandler, /user/mfa/**
  added to unprotected URIs when MFA enabled
- dsspringuserconfig.properties: MFA default properties block

Includes unit tests (MfaConfigurationTest) and integration tests for
both enabled and disabled states (MfaFeatureEnabledIntegrationTest,
MfaFeatureDisabledIntegrationTest). All 15 new assertions pass.

* refactor(mfa): address code review feedback on MFA implementation

- Change MfaStatusResponse from @DaTa to @value for immutability
- Use method-injected Authentication instead of SecurityContextHolder
- Remove duplicate FACTOR_AUTHORITY_MAP from MfaAPI, delegate to
  MfaConfiguration.mapFactorToAuthority() (now public)
- Replace switch/case in WebSecurityConfig.setupMfa() with HashMap lookup
- Add default AccessDeniedHandlerImpl fallback for non-MFA access denied
- Add null/blank guards in mfaAuthorizationManagerFactory and validator
- Remove redundant @propertysource from MfaConfiguration (already loaded
  by WebAuthnConfiguration per PR #264 consolidation)
- Normalize requiredFactors to uppercase for consistent API response
  casing across requiredFactors, satisfiedFactors, and missingFactors
- Fix inaccurate JavaDoc on validateMfaConfiguration

* test(mfa): rename tests to follow naming convention and add enforcement test

Rename 11 test methods across MfaConfigurationTest and
MfaFeatureEnabledIntegrationTest to follow the project's
should[ExpectedBehavior]When[Condition] naming convention.

Add integration test verifying that the
DelegatingMissingAuthorityAccessDeniedHandler redirects to the
password entry-point URI when a user is missing the PASSWORD factor
authority.

* refactor(mfa): address second round of PR review feedback

- Remove redundant setDefaultAccessDeniedHandler call in setupMfa();
  the builder already initializes the default handler
- Replace mutable HashMap with immutable Map.of() for factor-to-URI map
- Tighten unprotected URI from /user/mfa/** wildcard to /user/mfa/status
  to avoid silently exposing future MFA endpoints
- Remove redundant toUpperCase() calls in MfaAPI.getMfaStatus() since
  requiredFactors is already uppercased during stream mapping
- Remove unused HashMap and AccessDeniedHandlerImpl imports

* test(mfa): add WEBAUTHN multi-factor integration test

Add MfaMultiFactorIntegrationTest that exercises the PASSWORD+WEBAUTHN
path through setupMfa, resolveFactorAuthorities, and the MFA status
endpoint. Verifies both factors appear in required/missing lists and
that the authorization manager factory is created for multi-factor
configurations.

* refactor(mfa): address third round of PR review feedback

- Remove blank lines in WebSecurityConfig import block
- Add clarifying comment in MfaConfiguration for silent skip behavior
- Add positive-path MFA tests verifying fullyAuthenticated: true
  when user has all required FactorGrantedAuthority entries

Author: devondragon

src/main/java/com/digitalsanctuary/spring/user/api/MfaAPI.java

@@ -0,0 +1,86 @@
+package com.digitalsanctuary.spring.user.api;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import com.digitalsanctuary.spring.user.dto.MfaStatusResponse;
+import com.digitalsanctuary.spring.user.security.MfaConfigProperties;
+import com.digitalsanctuary.spring.user.security.MfaConfiguration;
+import com.digitalsanctuary.spring.user.util.JSONResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * REST API for Multi-Factor Authentication status.
+ * <p>
+ * Provides an endpoint for checking the MFA status of the current session. This is accessible to
+ * partially-authenticated users so the UI can determine which factor challenge to show next.
+ * </p>
+ * <p>
+ * This controller is only registered when MFA is enabled ({@code user.mfa.enabled=true}).
+ * </p>
+ */
+@Slf4j
+@RestController
+@RequestMapping(path = "/user/mfa", produces = "application/json")
+@ConditionalOnProperty(name = "user.mfa.enabled", havingValue = "true", matchIfMissing = false)
+@RequiredArgsConstructor
+public class MfaAPI {
+
+	private final MfaConfigProperties mfaConfigProperties;
+
+	/**
+	 * Returns the MFA status for the current session.
+	 * <p>
+	 * Reports which factors are required, which have been satisfied, and which are still missing. This endpoint is
+	 * accessible to partially-authenticated users (added to unprotected URIs when MFA is enabled).
+	 * </p>
+	 *
+	 * @param authentication the current authentication, injected by Spring MVC (may be null)
+	 * @return a ResponseEntity containing the MFA status
+	 */
+	@GetMapping("/status")
+	public ResponseEntity<JSONResponse> getMfaStatus(Authentication authentication) {
+		List<String> requiredFactors = mfaConfigProperties.getFactors().stream()
+				.map(String::toUpperCase).toList();
+
+		List<String> satisfiedFactors = new ArrayList<>();
+		List<String> missingFactors = new ArrayList<>();
+
+		if (authentication != null && authentication.isAuthenticated()) {
+			Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities();
+
+			for (String factor : requiredFactors) {
+				String authorityString = MfaConfiguration.mapFactorToAuthority(factor);
+				if (authorityString != null && hasAuthority(authorities, authorityString)) {
+					satisfiedFactors.add(factor);
+				} else {
+					missingFactors.add(factor);
+				}
+			}
+		} else {
+			missingFactors.addAll(requiredFactors);
+		}
+
+		MfaStatusResponse status = MfaStatusResponse.builder()
+				.mfaEnabled(true)
+				.requiredFactors(requiredFactors)
+				.satisfiedFactors(satisfiedFactors)
+				.missingFactors(missingFactors)
+				.fullyAuthenticated(missingFactors.isEmpty())
+				.build();
+
+		return ResponseEntity.ok(JSONResponse.builder().success(true).data(status).build());
+	}
+
+	private boolean hasAuthority(Collection<? extends GrantedAuthority> authorities, String authorityString) {
+		return authorities.stream().anyMatch(a -> authorityString.equals(a.getAuthority()));
+	}
+}

src/main/java/com/digitalsanctuary/spring/user/dto/MfaStatusResponse.java

@@ -0,0 +1,34 @@
+package com.digitalsanctuary.spring.user.dto;
+
+import java.util.List;
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Response DTO for the MFA status endpoint.
+ * <p>
+ * Provides information about the MFA state of the current user session, including which factors are required, which
+ * have been satisfied, and which are still missing. This enables the UI to display the appropriate MFA challenge pages.
+ * </p>
+ *
+ * @see com.digitalsanctuary.spring.user.api.MfaAPI
+ */
+@Value
+@Builder
+public class MfaStatusResponse {
+
+	/** Whether MFA is enabled on the server. */
+	boolean mfaEnabled;
+
+	/** The list of required factor names (e.g., PASSWORD, WEBAUTHN). */
+	List<String> requiredFactors;
+
+	/** The list of factor names that the current session has satisfied. */
+	List<String> satisfiedFactors;
+
+	/** The list of factor names that the current session has not yet satisfied. */
+	List<String> missingFactors;
+
+	/** Whether the current session has satisfied all required factors. */
+	boolean fullyAuthenticated;
+}

src/main/java/com/digitalsanctuary/spring/user/security/MfaConfigProperties.java

@@ -0,0 +1,50 @@
+package com.digitalsanctuary.spring.user.security;
+
+import java.util.ArrayList;
+import java.util.List;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import lombok.Data;
+
+/**
+ * Configuration properties for Multi-Factor Authentication (MFA).
+ * <p>
+ * When enabled, all authenticated endpoints require all configured factors to be satisfied. Spring Security 7's built-in
+ * MFA infrastructure handles enforcement, redirection between factor login pages, and session management automatically.
+ * </p>
+ * <p>
+ * Example configuration:
+ * </p>
+ *
+ * <pre>
+ * user.mfa.enabled: true
+ * user.mfa.factors: PASSWORD, WEBAUTHN
+ * user.mfa.passwordEntryPointUri: /user/login.html
+ * user.mfa.webauthnEntryPointUri: /user/webauthn/login.html
+ * </pre>
+ *
+ * @see MfaConfiguration
+ */
+@Data
+@ConfigurationProperties(prefix = "user.mfa")
+public class MfaConfigProperties {
+
+	/**
+	 * Whether MFA is enabled. When true, all authenticated endpoints require all configured factors.
+	 */
+	private boolean enabled = false;
+
+	/**
+	 * The list of authentication factors required for MFA. Supported values: PASSWORD, WEBAUTHN.
+	 */
+	private List<String> factors = new ArrayList<>();
+
+	/**
+	 * The URI to redirect to when the PASSWORD factor is missing. This should point to the password login page.
+	 */
+	private String passwordEntryPointUri = "/user/login.html";
+
+	/**
+	 * The URI to redirect to when the WEBAUTHN factor is missing. This should point to the WebAuthn/passkey login page.
+	 */
+	private String webauthnEntryPointUri = "/user/webauthn/login.html";
+}

src/main/java/com/digitalsanctuary/spring/user/security/MfaConfiguration.java

@@ -0,0 +1,160 @@
+package com.digitalsanctuary.spring.user.security;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.event.ContextRefreshedEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.security.authorization.AllRequiredFactorsAuthorizationManager;
+import org.springframework.security.authorization.AuthorizationManager;
+import org.springframework.security.authorization.DefaultAuthorizationManagerFactory;
+import org.springframework.security.authorization.RequiredFactor;
+import org.springframework.security.core.authority.FactorGrantedAuthority;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Configuration that registers {@link MfaConfigProperties} and provides MFA-related beans.
+ * <p>
+ * This configuration is always active because {@code WebSecurityConfig} requires {@link MfaConfigProperties} regardless
+ * of whether MFA is enabled. The {@code DefaultAuthorizationManagerFactory} bean is only created when MFA is enabled.
+ * </p>
+ * <p>
+ * When enabled, the {@code DefaultAuthorizationManagerFactory} is configured with an
+ * {@link AllRequiredFactorsAuthorizationManager} that makes {@code .authenticated()} in
+ * {@code authorizeHttpRequests} additionally require all configured factor authorities. Spring Security 7's built-in
+ * infrastructure handles enforcement and session management automatically.
+ * </p>
+ *
+ * @see MfaConfigProperties
+ * @see WebSecurityConfig
+ */
+@Slf4j
+@Configuration
+@EnableConfigurationProperties(MfaConfigProperties.class)
+@RequiredArgsConstructor
+public class MfaConfiguration {
+
+	/**
+	 * Mapping from user-facing factor names to Spring Security {@link FactorGrantedAuthority} authority strings.
+	 */
+	private static final Map<String, String> FACTOR_AUTHORITY_MAP = Map.of(
+			"PASSWORD", FactorGrantedAuthority.PASSWORD_AUTHORITY,
+			"WEBAUTHN", FactorGrantedAuthority.WEBAUTHN_AUTHORITY);
+
+	private final MfaConfigProperties mfaConfigProperties;
+	private final WebAuthnConfigProperties webAuthnConfigProperties;
+
+	/**
+	 * Creates a {@link DefaultAuthorizationManagerFactory} with an additional authorization requirement for all
+	 * configured MFA factors. This makes {@code .authenticated()} in {@code authorizeHttpRequests} require all
+	 * configured factors to be satisfied.
+	 *
+	 * @return the authorization manager factory configured with required factor authorities
+	 */
+	@Bean
+	@ConditionalOnProperty(name = "user.mfa.enabled", havingValue = "true", matchIfMissing = false)
+	public DefaultAuthorizationManagerFactory<Object> mfaAuthorizationManagerFactory() {
+		AllRequiredFactorsAuthorizationManager.Builder<Object> factorsBuilder =
+				AllRequiredFactorsAuthorizationManager.builder();
+
+		// Unknown/blank factors are silently skipped here; validateMfaConfiguration() will
+		// throw before startup completes if the configuration is invalid.
+		for (String factor : mfaConfigProperties.getFactors()) {
+			if (factor == null || factor.isBlank()) {
+				continue;
+			}
+			String authority = FACTOR_AUTHORITY_MAP.get(factor.toUpperCase());
+			if (authority != null) {
+				factorsBuilder.requireFactor(RequiredFactor.withAuthority(authority).build());
+			}
+		}
+
+		AuthorizationManager<Object> factorsManager = factorsBuilder.build();
+
+		DefaultAuthorizationManagerFactory<Object> factory = new DefaultAuthorizationManagerFactory<>();
+		factory.setAdditionalAuthorization(factorsManager);
+
+		log.info("MFA enabled with required factors: {}", mfaConfigProperties.getFactors());
+		return factory;
+	}
+
+	/**
+	 * Validates MFA configuration on application startup. Performs validation only when MFA is enabled; returns
+	 * immediately otherwise.
+	 *
+	 * @param event the context refreshed event
+	 */
+	@EventListener(ContextRefreshedEvent.class)
+	public void validateMfaConfiguration(ContextRefreshedEvent event) {
+		if (!mfaConfigProperties.isEnabled()) {
+			return;
+		}
+
+		List<String> factors = mfaConfigProperties.getFactors();
+
+		if (factors == null || factors.isEmpty()) {
+			throw new IllegalStateException(
+					"MFA is enabled (user.mfa.enabled=true) but no factors are configured. "
+							+ "Set user.mfa.factors to a comma-separated list of factors (e.g., PASSWORD,WEBAUTHN).");
+		}
+
+		for (String factor : factors) {
+			if (factor == null || factor.isBlank()) {
+				throw new IllegalStateException(
+						"MFA factors list contains a null or blank entry. Check user.mfa.factors configuration.");
+			}
+			if (!FACTOR_AUTHORITY_MAP.containsKey(factor.toUpperCase())) {
+				throw new IllegalStateException(
+						"Unknown MFA factor: '" + factor + "'. Supported factors: " + FACTOR_AUTHORITY_MAP.keySet());
+			}
+		}
+
+		if (factors.stream().anyMatch(f -> "WEBAUTHN".equalsIgnoreCase(f)) && !webAuthnConfigProperties.isEnabled()) {
+			throw new IllegalStateException(
+					"MFA factor WEBAUTHN is configured but WebAuthn is disabled (user.webauthn.enabled=false). "
+							+ "Enable WebAuthn or remove WEBAUTHN from user.mfa.factors.");
+		}
+
+		if (factors.stream().anyMatch(f -> "PASSWORD".equalsIgnoreCase(f))) {
+			log.warn("MFA factor PASSWORD is configured. Users with passwordless (passkey-only) accounts "
+					+ "will not be able to satisfy the PASSWORD factor. Consider your account types carefully.");
+		}
+	}
+
+	/**
+	 * Resolves the configured factor names to Spring Security authority strings.
+	 * <p>
+	 * Package-private for testing via {@link MfaConfigurationTest}.
+	 * </p>
+	 *
+	 * @return list of Spring Security authority strings
+	 */
+	List<String> resolveFactorAuthorities() {
+		List<String> authorities = new ArrayList<>();
+		for (String factor : mfaConfigProperties.getFactors()) {
+			String authority = FACTOR_AUTHORITY_MAP.get(factor.toUpperCase());
+			if (authority != null) {
+				authorities.add(authority);
+			}
+		}
+		return authorities;
+	}
+
+	/**
+	 * Maps a user-facing factor name to a Spring Security authority string.
+	 *
+	 * @param factorName the factor name (e.g., "PASSWORD", "WEBAUTHN")
+	 * @return the corresponding Spring Security authority string, or null if unknown
+	 */
+	public static String mapFactorToAuthority(String factorName) {
+		if (factorName == null || factorName.isBlank()) {
+			return null;
+		}
+		return FACTOR_AUTHORITY_MAP.get(factorName.toUpperCase());
+	}
+}