feat: Add RegistrationGuard SPI for pre-registration hook

Add a Service Provider Interface that gates all four registration paths
(form, passwordless, OAuth2, OIDC) with a single evaluate() call. The
guard uses bean-presence activation — consumers implement RegistrationGuard
and the default permit-all fallback is replaced via @ConditionalOnMissingBean.

Core types: RegistrationGuard (interface), RegistrationContext (record),
RegistrationDecision (record with allow/deny factories), RegistrationSource
(enum), DefaultRegistrationGuard (permit-all fallback).

Includes REGISTRATION-GUARD.md documentation and updates CLAUDE.md
related docs section.

Closes #271

Author: devondragon

CLAUDE.md

@@ -192,6 +192,7 @@ Integration tests use `TestApplication` (in `test.app` package) as their Spring
 
 - `TESTING.md` - Comprehensive testing guide with patterns and troubleshooting
 - `PROFILE.md` - User profile extension framework
+- `REGISTRATION-GUARD.md` - Registration Guard SPI for pre-registration hooks
 - `CONFIG.md` - Configuration reference
 - `MIGRATION.md` - Version migration guide
 - `CONTRIBUTING.md` - Contributor guidelines (fork/branch/PR workflow)

REGISTRATION-GUARD.md

@@ -0,0 +1,202 @@
+# Registration Guard SPI
+
+This guide explains how to use the Registration Guard SPI in Spring User Framework to control who can register in your application.
+
+## Table of Contents
+- [Registration Guard SPI](#registration-guard-spi)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [When to Use](#when-to-use)
+  - [Core Components](#core-components)
+  - [Implementation Guide](#implementation-guide)
+  - [Usage Examples](#usage-examples)
+    - [Domain Restriction](#domain-restriction)
+    - [Invite-Only with OAuth2 Bypass](#invite-only-with-oauth2-bypass)
+    - [Beta Access / Waitlist](#beta-access--waitlist)
+  - [Denial Behavior](#denial-behavior)
+  - [Key Constraints](#key-constraints)
+  - [Troubleshooting](#troubleshooting)
+
+## Overview
+
+The Registration Guard is a pre-registration hook that gates all four registration paths: form, passwordless, OAuth2, and OIDC. It allows you to accept or reject registration attempts before a user account is created.
+
+The guard requires zero configuration — it activates by bean presence alone. When no custom guard is defined, a built-in permit-all default is used automatically.
+
+## When to Use
+
+Consider implementing a Registration Guard when you need to:
+
+- Restrict registration to specific email domains (e.g., corporate apps)
+- Implement invite-only or beta access registration
+- Enforce waitlist-based onboarding
+- Apply compliance or legal gates before account creation
+- Allow social login but restrict form-based registration (or vice versa)
+
+If your application allows open registration with no restrictions, you do not need to implement a guard.
+
+## Core Components
+
+The Registration Guard SPI consists of these types in the `com.digitalsanctuary.spring.user.registration` package:
+
+1. **`RegistrationGuard`** — The interface you implement. Has a single method: `evaluate(RegistrationContext)` returning a `RegistrationDecision`.
+
+2. **`RegistrationContext`** — An immutable record describing the registration attempt:
+   - `email` — the email address of the user attempting to register
+   - `source` — the registration path (`FORM`, `PASSWORDLESS`, `OAUTH2`, or `OIDC`)
+   - `providerName` — the OAuth2/OIDC provider registration ID (e.g. `"google"`, `"keycloak"`), or `null` for form/passwordless
+
+3. **`RegistrationDecision`** — An immutable record with the guard's verdict:
+   - `allowed` — whether the registration is permitted
+   - `reason` — a human-readable denial reason (may be `null` when allowed)
+   - `allow()` — static factory for an allowing decision
+   - `deny(String reason)` — static factory for a denying decision
+
+4. **`RegistrationSource`** — Enum identifying the registration path: `FORM`, `PASSWORDLESS`, `OAUTH2`, `OIDC`
+
+5. **`DefaultRegistrationGuard`** — The built-in permit-all fallback. Automatically registered via `@ConditionalOnMissingBean` when no custom guard bean exists.
+
+## Implementation Guide
+
+Create a `@Component` that implements `RegistrationGuard`. That's it — the default guard is automatically replaced.
+
+```java
+@Component
+public class MyRegistrationGuard implements RegistrationGuard {
+
+    @Override
+    public RegistrationDecision evaluate(RegistrationContext context) {
+        // Your logic here
+        return RegistrationDecision.allow();
+    }
+}
+```
+
+No additional configuration, properties, or wiring is needed. The library detects your bean and uses it in place of the default.
+
+## Usage Examples
+
+### Domain Restriction
+
+Allow only users with a specific email domain:
+
+```java
+@Component
+public class DomainGuard implements RegistrationGuard {
+
+    @Override
+    public RegistrationDecision evaluate(RegistrationContext context) {
+        if (context.email().endsWith("@mycompany.com")) {
+            return RegistrationDecision.allow();
+        }
+        return RegistrationDecision.deny("Registration is restricted to @mycompany.com email addresses.");
+    }
+}
+```
+
+### Invite-Only with OAuth2 Bypass
+
+Require an invite for form/passwordless registration but allow all OAuth2/OIDC users:
+
+```java
+@Component
+@RequiredArgsConstructor
+public class InviteOnlyGuard implements RegistrationGuard {
+
+    private final InviteCodeRepository inviteCodeRepository;
+
+    @Override
+    public RegistrationDecision evaluate(RegistrationContext context) {
+        // Allow all OAuth2/OIDC registrations
+        if (context.source() == RegistrationSource.OAUTH2
+                || context.source() == RegistrationSource.OIDC) {
+            return RegistrationDecision.allow();
+        }
+        // For form/passwordless, check invite list
+        if (inviteCodeRepository.existsByEmail(context.email())) {
+            return RegistrationDecision.allow();
+        }
+        return RegistrationDecision.deny("Registration is by invitation only.");
+    }
+}
+```
+
+### Beta Access / Waitlist
+
+Check a beta-users table before allowing registration:
+
+```java
+@Component
+@RequiredArgsConstructor
+public class BetaAccessGuard implements RegistrationGuard {
+
+    private final BetaUserRepository betaUserRepository;
+
+    @Override
+    public RegistrationDecision evaluate(RegistrationContext context) {
+        if (betaUserRepository.existsByEmail(context.email())) {
+            return RegistrationDecision.allow();
+        }
+        return RegistrationDecision.deny("Registration is currently limited to beta users. "
+                + "Please join the waitlist.");
+    }
+}
+```
+
+## Denial Behavior
+
+When a guard denies a registration, the behavior depends on the registration path:
+
+| Registration Path | Denial Response |
+|---|---|
+| **Form** | HTTP 403 Forbidden with JSON: `{"success": false, "code": 6, "messages": ["<reason>"]}` |
+| **Passwordless** | HTTP 403 Forbidden with JSON: `{"success": false, "code": 6, "messages": ["<reason>"]}` |
+| **OAuth2** | `OAuth2AuthenticationException` with error code `"registration_denied"` — handled by Spring Security's OAuth2 failure handler |
+| **OIDC** | `OAuth2AuthenticationException` with error code `"registration_denied"` — handled by Spring Security's OAuth2 failure handler |
+
+For OAuth2/OIDC denials, customize the user experience by configuring Spring Security's OAuth2 login failure handler to inspect the error code and display an appropriate message.
+
+## Key Constraints
+
+- **Single-bean SPI** — Only one `RegistrationGuard` bean may be active at a time. This is not a chain or filter pattern; define exactly one guard.
+- **Thread safety required** — The guard may be invoked concurrently from multiple request threads. Ensure your implementation is thread-safe.
+- **No configuration properties** — The guard is activated entirely by bean presence. There are no `user.*` properties involved.
+- **Existing users unaffected** — The guard only runs for new registrations. Existing users logging in via OAuth2/OIDC are not evaluated.
+
+## Troubleshooting
+
+**Guard Not Activating**
+- Ensure your guard class is annotated with `@Component` (or otherwise registered as a Spring bean)
+- Verify the class is within a package that is component-scanned by your application
+- Check that `DefaultRegistrationGuard` is being replaced — enable debug logging:
+  ```yaml
+  logging:
+    level:
+      com.digitalsanctuary.spring.user.registration: DEBUG
+  ```
+
+**Multiple Guards Defined**
+- Only one `RegistrationGuard` bean is allowed. If multiple beans are defined, Spring will throw a `NoUniqueBeanDefinitionException` at startup.
+- If you need to compose multiple rules, implement a single guard that delegates internally.
+
+**OAuth2/OIDC Denial UX**
+- By default, OAuth2/OIDC denials redirect to Spring Security's default failure URL with a generic error.
+- To show a custom message, configure an `AuthenticationFailureHandler` on your OAuth2 login that checks for the `"registration_denied"` error code:
+  ```java
+  http.oauth2Login(oauth2 -> oauth2
+      .failureHandler((request, response, exception) -> {
+          if (exception instanceof OAuth2AuthenticationException oauthEx
+                  && "registration_denied".equals(oauthEx.getError().getErrorCode())) {
+              response.sendRedirect("/registration-denied");
+          } else {
+              response.sendRedirect("/login?error");
+          }
+      })
+  );
+  ```
+
+---
+
+This SPI provides a clean extension point for controlling registration without modifying framework internals. Implement a single bean, return allow or deny, and the framework handles the rest across all registration paths.
+
+For a complete working example, refer to the [Spring User Framework Demo Application](https://github.com/devondragon/SpringUserFrameworkDemoApp).

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

@@ -31,6 +31,10 @@
 import com.digitalsanctuary.spring.user.exceptions.InvalidOldPasswordException;
 import com.digitalsanctuary.spring.user.exceptions.UserAlreadyExistException;
 import com.digitalsanctuary.spring.user.persistence.model.User;
+import com.digitalsanctuary.spring.user.registration.RegistrationContext;
+import com.digitalsanctuary.spring.user.registration.RegistrationDecision;
+import com.digitalsanctuary.spring.user.registration.RegistrationGuard;
+import com.digitalsanctuary.spring.user.registration.RegistrationSource;
 import com.digitalsanctuary.spring.user.service.DSUserDetails;
 import com.digitalsanctuary.spring.user.service.PasswordPolicyService;
 import com.digitalsanctuary.spring.user.service.UserEmailService;
@@ -67,6 +71,7 @@ public class UserAPI {
 	private final ApplicationEventPublisher eventPublisher;
 	private final PasswordPolicyService passwordPolicyService;
 	private final ObjectProvider<WebAuthnCredentialManagementService> webAuthnCredentialManagementServiceProvider;
+	private final RegistrationGuard registrationGuard;
 
 	@Value("${user.security.registrationPendingURI}")
 	private String registrationPendingURI;
@@ -104,6 +109,12 @@ public ResponseEntity<JSONResponse> registerUserAccount(@Valid @RequestBody User
 				return buildErrorResponse(String.join(" ", errors), 1, HttpStatus.BAD_REQUEST);
 			}
 
+			RegistrationDecision decision = registrationGuard.evaluate(
+					new RegistrationContext(userDto.getEmail(), RegistrationSource.FORM, null));
+			if (!decision.allowed()) {
+				return buildErrorResponse(decision.reason(), 6, HttpStatus.FORBIDDEN);
+			}
+
 			User registeredUser = userService.registerNewUserAccount(userDto);
 			publishRegistrationEvent(registeredUser, request);
 			logAuditEvent("Registration", "Success", "Registration Successful", registeredUser, request);
@@ -395,6 +406,12 @@ public ResponseEntity<JSONResponse> registerPasswordlessAccount(@Valid @RequestB
 			return buildErrorResponse("Passwordless registration is not available", 1, HttpStatus.BAD_REQUEST);
 		}
 		try {
+			RegistrationDecision decision = registrationGuard.evaluate(
+					new RegistrationContext(dto.getEmail(), RegistrationSource.PASSWORDLESS, null));
+			if (!decision.allowed()) {
+				return buildErrorResponse(decision.reason(), 6, HttpStatus.FORBIDDEN);
+			}
+
 			User registeredUser = userService.registerPasswordlessAccount(dto);
 			publishRegistrationEvent(registeredUser, request);
 			logAuditEvent("PasswordlessRegistration", "Success", "Passwordless registration successful", registeredUser, request);

src/main/java/com/digitalsanctuary/spring/user/registration/DefaultRegistrationGuard.java

@@ -0,0 +1,19 @@
+package com.digitalsanctuary.spring.user.registration;
+
+/**
+ * Default {@link RegistrationGuard} that permits all registrations.
+ *
+ * <p>This implementation is automatically registered when the consuming application does not
+ * define its own {@link RegistrationGuard} bean. To restrict registration, declare
+ * a custom {@link RegistrationGuard} bean in your application context.</p>
+ *
+ * @see RegistrationGuard
+ * @see RegistrationGuardConfiguration
+ */
+public class DefaultRegistrationGuard implements RegistrationGuard {
+
+    @Override
+    public RegistrationDecision evaluate(RegistrationContext context) {
+        return RegistrationDecision.allow();
+    }
+}

src/main/java/com/digitalsanctuary/spring/user/registration/RegistrationContext.java

@@ -0,0 +1,13 @@
+package com.digitalsanctuary.spring.user.registration;
+
+/**
+ * Immutable context passed to {@link RegistrationGuard#evaluate(RegistrationContext)}
+ * describing the registration attempt being evaluated.
+ *
+ * @param email        the email address of the user attempting to register
+ * @param source       the registration path (form, passwordless, OAuth2, or OIDC)
+ * @param providerName the OAuth2/OIDC provider registration ID (e.g. {@code "google"},
+ *                     {@code "keycloak"}), or {@code null} for form/passwordless registrations
+ */
+public record RegistrationContext(String email, RegistrationSource source, String providerName) {
+}

src/main/java/com/digitalsanctuary/spring/user/registration/RegistrationDecision.java

@@ -0,0 +1,30 @@
+package com.digitalsanctuary.spring.user.registration;
+
+/**
+ * The result of a {@link RegistrationGuard} evaluation indicating whether
+ * a registration attempt should be allowed or denied.
+ *
+ * @param allowed whether the registration is permitted
+ * @param reason  a human-readable denial reason (may be {@code null} when allowed)
+ */
+public record RegistrationDecision(boolean allowed, String reason) {
+
+    /**
+     * Creates a decision that allows the registration to proceed.
+     *
+     * @return an allowing decision with no reason
+     */
+    public static RegistrationDecision allow() {
+        return new RegistrationDecision(true, null);
+    }
+
+    /**
+     * Creates a decision that denies the registration.
+     *
+     * @param reason a human-readable explanation for the denial
+     * @return a denying decision with the given reason
+     */
+    public static RegistrationDecision deny(String reason) {
+        return new RegistrationDecision(false, reason);
+    }
+}

src/main/java/com/digitalsanctuary/spring/user/registration/RegistrationGuard.java

@@ -0,0 +1,52 @@
+package com.digitalsanctuary.spring.user.registration;
+
+/**
+ * Service Provider Interface (SPI) for gating user registration.
+ *
+ * <p>Implementations are called before a new user account is created across all
+ * registration paths (form, passwordless, OAuth2, OIDC). If the guard denies a
+ * registration, the user is not created and an appropriate error is returned.</p>
+ *
+ * <p>To activate a custom guard, declare a Spring bean that implements this interface.
+ * The library's default (permit-all) guard is automatically replaced via
+ * {@link org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean}.</p>
+ *
+ * <h2>Usage Example</h2>
+ * <pre>{@code
+ * @Component
+ * public class InviteOnlyGuard implements RegistrationGuard {
+ *     private final InviteCodeRepository inviteCodeRepository;
+ *
+ *     public InviteOnlyGuard(InviteCodeRepository inviteCodeRepository) {
+ *         this.inviteCodeRepository = inviteCodeRepository;
+ *     }
+ *
+ *     @Override
+ *     public RegistrationDecision evaluate(RegistrationContext context) {
+ *         // Allow all OAuth2/OIDC registrations
+ *         if (context.source() == RegistrationSource.OAUTH2 || context.source() == RegistrationSource.OIDC) {
+ *             return RegistrationDecision.allow();
+ *         }
+ *         // Require invite code for form/passwordless
+ *         return RegistrationDecision.deny("Registration is by invitation only.");
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p><strong>Thread Safety:</strong> Implementations must be thread-safe as they may
+ * be invoked concurrently from multiple request threads.</p>
+ *
+ * @see RegistrationContext
+ * @see RegistrationDecision
+ * @see DefaultRegistrationGuard
+ */
+public interface RegistrationGuard {
+
+    /**
+     * Evaluates whether a registration attempt should be allowed.
+     *
+     * @param context the registration context describing the attempt
+     * @return a {@link RegistrationDecision} indicating whether registration is permitted
+     */
+    RegistrationDecision evaluate(RegistrationContext context);
+}

src/main/java/com/digitalsanctuary/spring/user/registration/RegistrationGuardConfiguration.java

@@ -0,0 +1,21 @@
+package com.digitalsanctuary.spring.user.registration;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Auto-configuration for the {@link RegistrationGuard} SPI.
+ *
+ * <p>Registers a {@link DefaultRegistrationGuard} (permit-all) when no custom
+ * {@link RegistrationGuard} bean is defined by the consuming application.</p>
+ */
+@Configuration
+public class RegistrationGuardConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean(RegistrationGuard.class)
+    public RegistrationGuard registrationGuard() {
+        return new DefaultRegistrationGuard();
+    }
+}