Add account registration with signup policy acceptance

Implements #16: invite-only student self-registration through a front-end
page, accepting signup-scoped policies at account creation.

Policy domain:
- us_policies.acceptance_scope (signup/booking/both); Policy::appliesTo();
  PolicyRepository::findForScope(); scope threaded through PolicyService,
  the REST create, the admin controller, and the Policies form.
- PolicyAcceptance::REG_ACCOUNT (registration_id = the new user's ID).

Auth:
- Invite value object + InviteRepository; us_invites table.
- RegistrationController + Invites admin page (manage_students): invite an
  email, share the registration link, revoke.
- RegistrationPage ([us_student_register] shortcode): validates the invite
  token, collects name/password, renders signup-scoped published policies
  with required acceptance, creates the us_student user, records account-type
  acceptances, marks the invite accepted, and logs the user in.
- RoleManager: manage_students cap added to STUDIO_ADMIN_CAPS.

Invite-only is implemented; the us_registration_mode self_approval path is a
documented future seam.

Docs: docs/features/account-registration.md; policies.md updated.
Tests: tests/Unit/Auth/ (Invite, InviteRepository) plus Policy scope
updates. composer test (104), cs, and PHPStan level 6 all pass.

Refs #16

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

src/Auth/Invite.php

@@ -0,0 +1,64 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Auth;
+
+class Invite {
+
+	public const STATUS_PENDING  = 'pending';
+	public const STATUS_ACCEPTED = 'accepted';
+	public const STATUS_REVOKED  = 'revoked';
+
+	/**
+	 * All valid invite statuses.
+	 *
+	 * @var list<string>
+	 */
+	public const VALID_STATUSES = [ self::STATUS_PENDING, self::STATUS_ACCEPTED, self::STATUS_REVOKED ];
+
+	public function __construct(
+		public readonly string $email,
+		public readonly string $token,
+		public readonly string $role = RoleManager::STUDENT,
+		public readonly string $status = self::STATUS_PENDING,
+		public readonly ?int $invitedBy = null,
+		public readonly ?int $acceptedUserId = null,
+		public readonly ?string $acceptedAt = null,
+		public readonly ?int $id = null,
+	) {}
+
+	public static function fromRow( object $row ): self {
+		return new self(
+			email:          $row->email,
+			token:          $row->token,
+			role:           $row->role,
+			status:         $row->status,
+			invitedBy:      null !== $row->invited_by ? (int) $row->invited_by : null,
+			acceptedUserId: null !== $row->accepted_user_id ? (int) $row->accepted_user_id : null,
+			acceptedAt:     $row->accepted_at,
+			id:             (int) $row->id,
+		);
+	}
+
+	public function isPending(): bool {
+		return self::STATUS_PENDING === $this->status;
+	}
+
+	/**
+	 * Returns a plain array representation of the invite.
+	 *
+	 * @return array<string, mixed>
+	 */
+	public function toArray(): array {
+		return [
+			'id'               => $this->id,
+			'email'            => $this->email,
+			'token'            => $this->token,
+			'role'             => $this->role,
+			'status'           => $this->status,
+			'invited_by'       => $this->invitedBy,
+			'accepted_user_id' => $this->acceptedUserId,
+			'accepted_at'      => $this->acceptedAt,
+		];
+	}
+}

src/Auth/InviteRepository.php

@@ -0,0 +1,103 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Auth;
+
+class InviteRepository {
+
+	private string $table;
+
+	public function __construct( private \wpdb $db ) {
+		$this->table = $db->prefix . 'us_invites';
+	}
+
+	public function insert( Invite $invite ): int {
+		$this->db->insert(
+			$this->table,
+			[
+				'email'            => $invite->email,
+				'token'            => $invite->token,
+				'role'             => $invite->role,
+				'status'           => $invite->status,
+				'invited_by'       => $invite->invitedBy,
+				'accepted_user_id' => $invite->acceptedUserId,
+				'created_at'       => current_time( 'mysql' ),
+				'accepted_at'      => $invite->acceptedAt,
+			],
+			[ '%s', '%s', '%s', '%s', '%d', '%d', '%s', '%s' ]
+		);
+
+		return $this->db->insert_id;
+	}
+
+	public function findByToken( string $token ): ?Invite {
+		$row = $this->db->get_row(
+			$this->db->prepare( "SELECT * FROM {$this->table} WHERE token = %s", $token )
+		);
+
+		return $row ? Invite::fromRow( $row ) : null;
+	}
+
+	public function findById( int $id ): ?Invite {
+		$row = $this->db->get_row(
+			$this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id )
+		);
+
+		return $row ? Invite::fromRow( $row ) : null;
+	}
+
+	/**
+	 * The most recent pending invite for an email, if any.
+	 */
+	public function findPendingByEmail( string $email ): ?Invite {
+		$row = $this->db->get_row(
+			$this->db->prepare(
+				"SELECT * FROM {$this->table} WHERE email = %s AND status = %s ORDER BY id DESC LIMIT 1",
+				$email,
+				Invite::STATUS_PENDING
+			)
+		);
+
+		return $row ? Invite::fromRow( $row ) : null;
+	}
+
+	/**
+	 * All invites awaiting acceptance, newest first.
+	 *
+	 * @return list<Invite>
+	 */
+	public function findPending(): array {
+		$rows = $this->db->get_results(
+			$this->db->prepare(
+				"SELECT * FROM {$this->table} WHERE status = %s ORDER BY created_at DESC",
+				Invite::STATUS_PENDING
+			)
+		);
+
+		return array_map( Invite::fromRow( ... ), $rows ?? [] );
+	}
+
+	public function markAccepted( int $id, int $userId ): bool {
+		return false !== $this->db->update(
+			$this->table,
+			[
+				'status'           => Invite::STATUS_ACCEPTED,
+				'accepted_user_id' => $userId,
+				'accepted_at'      => current_time( 'mysql' ),
+			],
+			[ 'id' => $id ],
+			[ '%s', '%d', '%s' ],
+			[ '%d' ]
+		);
+	}
+
+	public function revoke( int $id ): bool {
+		return false !== $this->db->update(
+			$this->table,
+			[ 'status' => Invite::STATUS_REVOKED ],
+			[ 'id' => $id ],
+			[ '%s' ],
+			[ '%d' ]
+		);
+	}
+}

src/Auth/RegistrationController.php

@@ -0,0 +1,55 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Auth;
+
+class RegistrationController {
+
+	public function __construct( private InviteRepository $invites ) {}
+
+	public function renderPage(): void {
+		if ( ! current_user_can( RoleManager::CAP_MANAGE_STUDENTS ) ) {
+			wp_die( esc_html__( 'You do not have permission to manage invites.', 'unsupervised-schedular' ) );
+		}
+
+		if ( isset( $_POST['usc_action'] ) && check_admin_referer( 'usc_invite_action' ) ) {
+			$this->handleFormAction();
+		}
+
+		$pendingInvites = $this->invites->findPending();
+
+		include USC_PLUGIN_DIR . 'templates/admin/invites.php';
+	}
+
+	private function handleFormAction(): void {
+		// Nonce is verified by the caller (renderPage) before this method runs.
+		// phpcs:disable WordPress.Security.NonceVerification.Missing
+		$action = sanitize_key( wp_unslash( $_POST['usc_action'] ?? '' ) );
+
+		if ( 'invite' === $action ) {
+			$email = sanitize_email( wp_unslash( $_POST['email'] ?? '' ) );
+
+			if (
+				is_email( $email )
+				&& false === email_exists( $email )
+				&& null === $this->invites->findPendingByEmail( $email )
+			) {
+				$this->invites->insert(
+					new Invite(
+						email:     $email,
+						token:     wp_generate_password( 32, false ),
+						invitedBy: get_current_user_id(),
+					)
+				);
+			}
+		}
+
+		if ( 'revoke' === $action ) {
+			$inviteId = absint( $_POST['invite_id'] ?? 0 );
+			if ( $inviteId > 0 ) {
+				$this->invites->revoke( $inviteId );
+			}
+		}
+		// phpcs:enable WordPress.Security.NonceVerification.Missing
+	}
+}

src/Auth/RegistrationPage.php

@@ -0,0 +1,159 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Auth;
+
+use Unsupervised\Schedular\Policy\AcceptanceRepository;
+use Unsupervised\Schedular\Policy\Policy;
+use Unsupervised\Schedular\Policy\PolicyAcceptance;
+use Unsupervised\Schedular\Policy\PolicyRepository;
+use Unsupervised\Schedular\Policy\PolicyVersionRepository;
+
+class RegistrationPage {
+
+	public function __construct(
+		private InviteRepository $invites,
+		private PolicyRepository $policies,
+		private PolicyVersionRepository $versions,
+		private AcceptanceRepository $acceptances,
+	) {}
+
+	/**
+	 * Renders the student registration shortcode output.
+	 *
+	 * @param array<string, string> $atts Shortcode attributes (unused — reserved for future options).
+	 */
+	public function render( array $atts ): string { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found
+		if ( is_user_logged_in() ) {
+			return '<p>' . esc_html__( 'You already have an account and are logged in.', 'unsupervised-schedular' ) . '</p>';
+		}
+
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- token identifies the invite; the form submit is nonce-checked below.
+		$token  = sanitize_text_field( wp_unslash( $_REQUEST['us_invite'] ?? '' ) );
+		$invite = '' !== $token ? $this->invites->findByToken( $token ) : null;
+
+		$error   = '';
+		$success = false;
+
+		if ( isset( $_POST['us_register'] ) && check_admin_referer( 'us_student_register' ) ) {
+			$result = $this->handleSubmit( $invite );
+			if ( true === $result ) {
+				$success = true;
+			} else {
+				$error = $result;
+			}
+		}
+
+		$policyForms = $this->signupPolicies();
+		$canRegister = null !== $invite && $invite->isPending();
+
+		ob_start();
+		include USC_PLUGIN_DIR . 'templates/frontend/register-page.php';
+		return (string) ob_get_clean();
+	}
+
+	/**
+	 * Process the submitted registration. Returns true on success or an error
+	 * message string on failure.
+	 */
+	private function handleSubmit( ?Invite $invite ): string|bool {
+		if ( null === $invite || ! $invite->isPending() ) {
+			return esc_html__( 'This invitation is invalid or has already been used.', 'unsupervised-schedular' );
+		}
+
+		// The submit nonce is verified by the caller (render) before this runs.
+		// phpcs:disable WordPress.Security.NonceVerification.Missing
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- passwords must not be sanitized.
+		$password    = (string) wp_unslash( $_POST['password'] ?? '' );
+		$displayName = sanitize_text_field( wp_unslash( $_POST['display_name'] ?? '' ) );
+
+		if ( strlen( $password ) < 8 ) {
+			return esc_html__( 'Please choose a password of at least 8 characters.', 'unsupervised-schedular' );
+		}
+
+		$policyForms = $this->signupPolicies();
+		$accepted    = array_map( 'absint', (array) ( $_POST['accept'] ?? [] ) );
+		// phpcs:enable WordPress.Security.NonceVerification.Missing
+
+		foreach ( $policyForms as $form ) {
+			if ( ! in_array( (int) $form['version']->id, $accepted, true ) ) {
+				return esc_html__( 'You must accept all required policies to register.', 'unsupervised-schedular' );
+			}
+		}
+
+		if ( email_exists( $invite->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_pass'    => $password,
+				'display_name' => '' !== $displayName ? $displayName : $invite->email,
+				'role'         => $invite->role,
+			]
+		);
+
+		if ( is_wp_error( $userId ) ) {
+			return esc_html__( 'Could not create the account. Please contact the studio.', 'unsupervised-schedular' );
+		}
+
+		$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 );
+
+		return true;
+	}
+
+	/**
+	 * Record account-time acceptances for each signup policy version.
+	 *
+	 * @param list<array{policy: Policy, version: \Unsupervised\Schedular\Policy\PolicyVersion}> $policyForms
+	 */
+	private function recordAcceptances( array $policyForms, int $userId ): void {
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- IP is stored verbatim for audit.
+		$ip = sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ?? '' ) );
+
+		foreach ( $policyForms as $form ) {
+			$this->acceptances->insert(
+				new PolicyAcceptance(
+					policyVersionId:  (int) $form['version']->id,
+					studentId:        $userId,
+					registrationType: PolicyAcceptance::REG_ACCOUNT,
+					registrationId:   $userId,
+					ipAddress:        '' !== $ip ? $ip : null,
+				)
+			);
+		}
+	}
+
+	/**
+	 * Signup-scoped policies that have a current published version.
+	 *
+	 * @return list<array{policy: Policy, version: \Unsupervised\Schedular\Policy\PolicyVersion}>
+	 */
+	private function signupPolicies(): array {
+		$out = [];
+
+		foreach ( $this->policies->findForScope( Policy::SCOPE_SIGNUP ) as $policy ) {
+			if ( null === $policy->currentVersionId ) {
+				continue;
+			}
+
+			$version = $this->versions->findById( $policy->currentVersionId );
+			if ( null === $version || ! $version->isPublished() ) {
+				continue;
+			}
+
+			$out[] = [
+				'policy'  => $policy,
+				'version' => $version,
+			];
+		}
+
+		return $out;
+	}
+}

src/Auth/RoleManager.php

@@ -14,6 +14,7 @@ class RoleManager {
 	public const CAP_BOOK_LESSON         = 'book_lesson';
 
 	public const CAP_MANAGE_INSTRUCTORS = 'manage_instructors';
+	public const CAP_MANAGE_STUDENTS    = 'manage_students';
 	public const CAP_MANAGE_OFFERINGS   = 'manage_offerings';
 	public const CAP_MANAGE_QUESTIONS   = 'manage_questions';
 	public const CAP_MANAGE_POLICIES    = 'manage_policies';
@@ -31,6 +32,7 @@ class RoleManager {
 	 */
 	public const STUDIO_ADMIN_CAPS = [
 		self::CAP_MANAGE_INSTRUCTORS,
+		self::CAP_MANAGE_STUDENTS,
 		self::CAP_MANAGE_OFFERINGS,
 		self::CAP_MANAGE_QUESTIONS,
 		self::CAP_MANAGE_POLICIES,