Add open student registration with email confirmation and approval

Students could previously join by invite only. Add an optional
self-approval mode, toggled from Studio Settings → Registration: anyone
may sign up on the existing [us_student_register] page, confirm their
email via a tokenised link, and then be approved by a studio admin
before the account is usable.

- Enabling the toggle mirrors WordPress's own membership settings
  (users_can_register + default_role = us_student) and snapshots their
  previous values so disabling restores them.
- WordPress's native registration form is blocked while open
  registration is on (login_init redirect + registration_errors
  fail-safe + register_url) so it cannot bypass signup policy acceptance.
- Pending accounts: unconfirmed email cannot log in; confirmed but
  unapproved can log in but the booking capability is withheld and the
  booking page shows an "awaiting approval" screen.
- Approve/reject from Students → Pending Students; reject hard-deletes
  the account so the email is freed to re-apply.
- Invite registration is unchanged; both modes coexist.

Account lifecycle lives in user meta (RegistrationStatus); no new tables.

Closes #63

Co-Authored-By: Claude Opus 4.8 <[email protected]>

src/Auth/RegistrationPage.php

@@ -3,6 +3,7 @@ declare(strict_types=1);
 
 namespace Unsupervised\Schedular\Auth;
 
+use Unsupervised\Schedular\Payment\StudioSettings;
 use Unsupervised\Schedular\Policy\AcceptanceRepository;
 use Unsupervised\Schedular\Policy\Policy;
 use Unsupervised\Schedular\Policy\PolicyAcceptance;
@@ -12,11 +13,19 @@ use Unsupervised\Schedular\Val;
 
 class RegistrationPage {
 
+	/** Success signal: an invited student was created and logged in. */
+	private const RESULT_INVITE = 'invite';
+
+	/** Success signal: a self-signup was created and must confirm their email. */
+	private const RESULT_CONFIRM = 'confirm';
+
 	public function __construct(
 		private InviteRepository $invites,
 		private PolicyRepository $policies,
 		private PolicyVersionRepository $versions,
 		private AcceptanceRepository $acceptances,
+		private StudioSettings $settings,
+		private RegistrationMailer $mailer,
 	) {}
 
 	/**
@@ -33,21 +42,26 @@ class RegistrationPage {
 		$token = sanitize_text_field( Val::string( wp_unslash( $_REQUEST['us_invite'] ?? '' ) ) );
 		// Only the token's hash is stored, so hash the submitted token for lookup.
 		$invite = '' !== $token ? $this->invites->findByToken( Invite::hashToken( $token ) ) : null;
+		$open   = $this->settings->openRegistrationEnabled();
 
-		$error   = '';
-		$success = false;
+		$error       = '';
+		$successType = '';
 
 		if ( isset( $_POST['us_register'] ) && check_admin_referer( 'us_student_register' ) ) {
-			$result = $this->handleSubmit( $invite );
-			if ( true === $result ) {
-				$success = true;
+			$result = $this->handleSubmit( $invite, $open );
+			if ( in_array( $result, [ self::RESULT_INVITE, self::RESULT_CONFIRM ], true ) ) {
+				$successType = $result;
 			} else {
 				$error = $result;
 			}
 		}
 
+		// Result of an email-confirmation link (set by EmailConfirmationHandler's redirect).
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only display flag, not a state change.
+		$confirmResult = sanitize_key( Val::string( wp_unslash( $_GET['us_confirmed'] ?? '' ) ) );
+
 		$policyForms = $this->signupPolicies();
-		$canRegister = null !== $invite && $invite->isAcceptable( current_time( 'mysql' ) );
+		$canRegister = $open || ( null !== $invite && $invite->isAcceptable( current_time( 'mysql' ) ) );
 
 		ob_start();
 		include USC_PLUGIN_DIR . 'templates/frontend/register-page.php';
@@ -80,11 +94,17 @@ class RegistrationPage {
 	}
 
 	/**
-	 * Process the submitted registration. Returns true on success or an error
-	 * message string on failure.
+	 * Process the submitted registration. Returns a success signal
+	 * ({@see RESULT_INVITE} or {@see RESULT_CONFIRM}) or an error message string
+	 * on failure.
+	 *
+	 * The invite branch is tried first, so an invited student always completes
+	 * signup regardless of whether open registration is enabled.
 	 */
-	private function handleSubmit( ?Invite $invite ): string|bool {
-		if ( null === $invite || ! $invite->isAcceptable( current_time( 'mysql' ) ) ) {
+	private function handleSubmit( ?Invite $invite, bool $open ): string {
+		$inviteValid = null !== $invite && $invite->isAcceptable( current_time( 'mysql' ) );
+
+		if ( ! $inviteValid && ! $open ) {
 			return esc_html__( 'This invitation is invalid, expired, or has already been used.', 'unsupervised-schedular' );
 		}
 
@@ -98,6 +118,16 @@ class RegistrationPage {
 			return esc_html__( 'Please choose a password of at least 8 characters.', 'unsupervised-schedular' );
 		}
 
+		// The email is fixed by the invite when there is one; self-signups supply it.
+		if ( $inviteValid ) {
+			$email = $invite->email;
+		} else {
+			$email = sanitize_email( Val::string( wp_unslash( $_POST['email'] ?? '' ) ) );
+			if ( ! is_email( $email ) ) {
+				return esc_html__( 'Please enter a valid email address.', 'unsupervised-schedular' );
+			}
+		}
+
 		$policyForms = $this->signupPolicies();
 		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.MissingUnslash, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- each element is coerced to a positive int in the array_map callback; slashes cannot survive integer coercion.
 		$accepted = array_map( static fn( mixed $v ): int => absint( Val::int( $v ) ), (array) ( $_POST['accept'] ?? [] ) );
@@ -109,17 +139,17 @@ class RegistrationPage {
 			}
 		}
 
-		if ( email_exists( $invite->email ) ) {
+		if ( email_exists( $email ) ) {
 			return esc_html__( 'An account already exists for this email.', 'unsupervised-schedular' );
 		}
 
 		$userId = wp_insert_user(
 			[
-				'user_login'   => $invite->email,
-				'user_email'   => $invite->email,
+				'user_login'   => $email,
+				'user_email'   => $email,
 				'user_pass'    => $password,
-				'display_name' => '' !== $displayName ? $displayName : $invite->email,
-				'role'         => $invite->role,
+				'display_name' => '' !== $displayName ? $displayName : $email,
+				'role'         => $inviteValid ? $invite->role : RoleManager::STUDENT,
 			]
 		);
 
@@ -128,12 +158,36 @@ class RegistrationPage {
 		}
 
 		$this->recordAcceptances( $policyForms, (int) $userId );
-		$this->invites->markAccepted( (int) $invite->id, (int) $userId );
 
-		wp_set_current_user( (int) $userId );
-		wp_set_auth_cookie( (int) $userId );
+		if ( $inviteValid ) {
+			$this->invites->markAccepted( (int) $invite->id, (int) $userId );
 
-		return true;
+			wp_set_current_user( (int) $userId );
+			wp_set_auth_cookie( (int) $userId );
+
+			return self::RESULT_INVITE;
+		}
+
+		// Self-approval: hold the account pending, email a confirmation link, and
+		// do NOT log the user in — they must confirm and be approved first.
+		$rawToken = RegistrationStatus::markPending( (int) $userId );
+		$user     = get_user_by( 'id', (int) $userId );
+		if ( $user instanceof \WP_User ) {
+			$this->mailer->sendConfirmation( $user, $this->confirmUrl( $rawToken ) );
+		}
+
+		return self::RESULT_CONFIRM;
+	}
+
+	/**
+	 * Build the email-confirmation URL for a raw token: the configured
+	 * registration page (falling back to the home page) with `?us_confirm=`.
+	 */
+	private function confirmUrl( string $rawToken ): string {
+		$pageId = Val::int( get_option( RegistrationController::OPTION_PAGE, 0 ) );
+		$base   = $pageId > 0 ? (string) get_permalink( $pageId ) : home_url( '/' );
+
+		return add_query_arg( 'us_confirm', rawurlencode( $rawToken ), $base );
 	}
 
 	/**