Add multi-use group invite links with expiry and auto-approval on email confirmation

A studio admin can generate a shareable group invite link (e.g. for a
newsletter) from the Invites page, choosing a required expiry date. Anyone
with the link may register while it is valid, in any registration mode: the
form collects their own email, they must confirm it via the usual hashed
token, and confirming approves the account immediately — group signups never
enter the Pending Students queue.

- us_invites grows kind (personal/group) and expires_at; an explicit expiry
  wins over the personal 14-day window. Group links stay pending (multi-use)
  until revoked or expired.
- RegistrationPage: group signups create the account pending with the
  us_auto_approve marker and send the confirmation email; no auto-login.
- EmailConfirmationHandler: auto-approve accounts are approved on
  confirmation, emailed the approved notice, and redirected to a new
  us_confirmed=ready notice with a sign-in link.

Closes #77

Co-Authored-By: Claude Fable 5 <[email protected]>

tests/Unit/Auth/EmailConfirmationHandlerTest.php

@@ -4,9 +4,11 @@ declare(strict_types=1);
 namespace Unsupervised\Schedular\Tests\Unit\Auth;
 
 use Brain\Monkey\Functions;
+use Mockery;
 use Unsupervised\Schedular\Auth\EmailConfirmationHandler;
 use Unsupervised\Schedular\Auth\RegistrationController;
 use Unsupervised\Schedular\Auth\RegistrationMailer;
+use Unsupervised\Schedular\Auth\RegistrationStatus;
 use Unsupervised\Schedular\Payment\StudioSettings;
 use Unsupervised\Schedular\Tests\Unit\TestCase;
 
@@ -22,9 +24,84 @@ class EmailConfirmationHandlerTest extends TestCase
     protected function tearDown(): void
     {
         unset($_REQUEST['action']);
+        $_GET = [];
         parent::tearDown();
     }
 
+    /**
+     * Stub everything maybeConfirm() needs for a valid token belonging to user
+     * 9, with wp_safe_redirect throwing so the redirect URL can be asserted.
+     *
+     * @param bool $autoApprove Whether user 9 carries the auto-approve marker.
+     */
+    private function stubConfirmContext(bool $autoApprove): void
+    {
+        $this->stubMode(StudioSettings::MODE_INVITE);
+        Functions\when('is_admin')->justReturn(false);
+        Functions\when('sanitize_text_field')->returnArg();
+        Functions\when('get_permalink')->justReturn('http://wp/register/');
+        Functions\when('add_query_arg')->alias(static fn (string $k, string $v, string $u): string => $u . '?' . $k . '=' . $v);
+        Functions\when('get_users')->justReturn([9]);
+        Functions\when('get_user_meta')->alias(static function (int $id, string $key) use ($autoApprove) {
+            if ($key === RegistrationStatus::META_CONFIRM_EXPIRES) {
+                return '2030-01-01 00:00:00';
+            }
+            if ($key === RegistrationStatus::META_AUTO_APPROVE) {
+                return $autoApprove ? '1' : '';
+            }
+            return '';
+        });
+        Functions\when('update_user_meta')->justReturn(true);
+        Functions\when('delete_user_meta')->justReturn(true);
+        Functions\when('wp_safe_redirect')->alias(static function (string $url): void {
+            throw new \RuntimeException('redirect:' . $url);
+        });
+
+        $_GET['us_confirm'] = 'rawtoken';
+    }
+
+    public function testConfirmAutoApprovesGroupLinkSignupWithoutAdminReview(): void
+    {
+        $this->stubConfirmContext(true);
+
+        $user = Mockery::mock(\WP_User::class);
+        Functions\when('get_user_by')->justReturn($user);
+
+        $mailer = Mockery::mock(RegistrationMailer::class);
+        $mailer->shouldReceive('sendApproved')->once()->with($user)->andReturn(true);
+        $mailer->shouldNotReceive('notifyAdminsPending');
+
+        $handler = new EmailConfirmationHandler(new StudioSettings(), $mailer);
+
+        try {
+            $handler->maybeConfirm();
+            self::fail('Expected a redirect');
+        } catch (\RuntimeException $e) {
+            self::assertStringContainsString('us_confirmed=ready', $e->getMessage());
+        }
+    }
+
+    public function testConfirmWithoutAutoApproveNotifiesAdminsAndStaysPending(): void
+    {
+        $this->stubConfirmContext(false);
+
+        $user = Mockery::mock(\WP_User::class);
+        Functions\when('get_user_by')->justReturn($user);
+
+        $mailer = Mockery::mock(RegistrationMailer::class);
+        $mailer->shouldReceive('notifyAdminsPending')->once()->with($user)->andReturn(true);
+        $mailer->shouldNotReceive('sendApproved');
+
+        $handler = new EmailConfirmationHandler(new StudioSettings(), $mailer);
+
+        try {
+            $handler->maybeConfirm();
+            self::fail('Expected a redirect');
+        } catch (\RuntimeException $e) {
+            self::assertStringContainsString('us_confirmed=1', $e->getMessage());
+        }
+    }
+
     private function handler(): EmailConfirmationHandler
     {
         return new EmailConfirmationHandler(new StudioSettings(), new RegistrationMailer());

tests/Unit/Auth/InviteRepositoryTest.php

@@ -34,16 +34,40 @@ class InviteRepositoryTest extends TestCase
                 Mockery::on(static function (array $d): bool {
                     return $d['email'] === '[email protected]'
                         && $d['token'] === 'tok123'
+                        && $d['kind'] === Invite::KIND_PERSONAL
                         && $d['status'] === Invite::STATUS_PENDING
-                        && $d['invited_by'] === 2;
+                        && $d['invited_by'] === 2
+                        && $d['expires_at'] === null;
                 }),
-                ['%s', '%s', '%s', '%s', '%d', '%d', '%s', '%s']
+                ['%s', '%s', '%s', '%s', '%s', '%d', '%d', '%s', '%s', '%s']
             );
         $this->db->insert_id = 5;
 
         self::assertSame(5, $this->repo->insert(new Invite('[email protected]', 'tok123', invitedBy: 2)));
     }
 
+    public function testInsertPersistsGroupKindAndExpiry(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-02 09:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_invites',
+                Mockery::on(static function (array $d): bool {
+                    return $d['email'] === ''
+                        && $d['kind'] === Invite::KIND_GROUP
+                        && $d['expires_at'] === '2026-08-31 23:59:59';
+                }),
+                Mockery::type('array')
+            );
+        $this->db->insert_id = 6;
+
+        $invite = new Invite('', 'tok456', invitedBy: 2, kind: Invite::KIND_GROUP, expiresAt: '2026-08-31 23:59:59');
+
+        self::assertSame(6, $this->repo->insert($invite));
+    }
+
     public function testFindByTokenReturnsInvite(): void
     {
         $this->db->shouldReceive('prepare')

tests/Unit/Auth/InviteTest.php

@@ -95,6 +95,52 @@ class InviteTest extends TestCase
         self::assertFalse($invite->isAcceptable('2026-06-02 09:00:00'));
     }
 
+    public function testGroupInviteHonoursExplicitExpiry(): void
+    {
+        $invite = new Invite(
+            '',
+            'tok',
+            createdAt: '2026-06-01 09:00:00',
+            kind: Invite::KIND_GROUP,
+            expiresAt: '2026-08-31 23:59:59'
+        );
+
+        self::assertTrue($invite->isGroup());
+        // 19 days after creation — past the personal 14-day window, but the
+        // explicit expiry governs.
+        self::assertFalse($invite->isExpired('2026-06-20 09:00:00'));
+        self::assertTrue($invite->isAcceptable('2026-06-20 09:00:00'));
+
+        self::assertTrue($invite->isExpired('2026-09-01 00:00:00'));
+        self::assertFalse($invite->isAcceptable('2026-09-01 00:00:00'));
+    }
+
+    public function testExplicitExpiryWinsOverCreationWindowForPersonalInvites(): void
+    {
+        $invite = new Invite('[email protected]', 'tok', createdAt: '2026-06-01 09:00:00', expiresAt: '2026-06-02 23:59:59');
+
+        // One day old (inside the 14-day window) but past its explicit expiry.
+        self::assertTrue($invite->isExpired('2026-06-03 09:00:00'));
+    }
+
+    public function testFromRowDefaultsKindWhenColumnMissing(): void
+    {
+        $invite = Invite::fromRow((object) [
+            'id'               => '5',
+            'email'            => '[email protected]',
+            'token'            => 'tok123',
+            'role'             => RoleManager::STUDENT,
+            'status'           => Invite::STATUS_PENDING,
+            'invited_by'       => null,
+            'accepted_user_id' => null,
+            'accepted_at'      => null,
+        ]);
+
+        self::assertSame(Invite::KIND_PERSONAL, $invite->kind);
+        self::assertFalse($invite->isGroup());
+        self::assertNull($invite->expiresAt);
+    }
+
     public function testHashTokenIsDeterministicSha256(): void
     {
         $hash = Invite::hashToken('raw-token');
@@ -109,7 +155,7 @@ class InviteTest extends TestCase
     {
         $arr = (new Invite('[email protected]', 'tok', id: 1))->toArray();
 
-        foreach (['id', 'email', 'token', 'role', 'status', 'invited_by', 'accepted_user_id', 'accepted_at'] as $key) {
+        foreach (['id', 'email', 'token', 'role', 'kind', 'status', 'invited_by', 'accepted_user_id', 'accepted_at', 'expires_at'] as $key) {
             self::assertArrayHasKey($key, $arr);
         }
     }

tests/Unit/Auth/RegistrationPageTest.php

@@ -123,6 +123,79 @@ class RegistrationPageTest extends TestCase
         self::assertSame('confirm', $this->submit(null, true));
     }
 
+    public function testGroupInviteCreatesPendingAutoApproveAccountEvenWhenClosed(): void
+    {
+        $_POST = [ 'password' => 'password123', 'display_name' => 'Ada', 'email' => '[email protected]' ];
+
+        Functions\when('is_email')->justReturn(true);
+        Functions\when('email_exists')->justReturn(false);
+        Functions\when('wp_insert_user')->justReturn(42);
+        Functions\when('is_wp_error')->justReturn(false);
+        Functions\when('wp_generate_password')->justReturn('rawtok');
+        // confirmUrl internals
+        Functions\when('get_option')->justReturn(0);
+        Functions\when('home_url')->justReturn('http://home.test/');
+        Functions\when('add_query_arg')->alias(static fn (string $k, string $v, string $u): string => $u . '?' . $k . '=' . $v);
+
+        // The auto-approve marker must be set alongside the pending metas.
+        $metas = [];
+        Functions\when('update_user_meta')->alias(static function (int $id, string $key, $value) use (&$metas): bool {
+            $metas[$key] = $value;
+            return true;
+        });
+
+        $user = Mockery::mock(\WP_User::class);
+        Functions\when('get_user_by')->justReturn($user);
+
+        $this->ctx['mailer']->shouldReceive('sendConfirmation')->once()->with($user, Mockery::type('string'));
+        // The link is multi-use: never marked accepted, and no auto-login.
+        $this->ctx['invites']->shouldReceive('markAccepted')->never();
+        Functions\expect('wp_set_auth_cookie')->never();
+
+        $invite = new Invite(
+            email: '',
+            token: 'hash',
+            createdAt: '2024-01-01 00:00:00',
+            kind: Invite::KIND_GROUP,
+            expiresAt: '2024-02-01 23:59:59',
+            id: 9
+        );
+
+        // Registration mode is invite-only (open = false): the group link still works.
+        self::assertSame('confirm_group', $this->submit($invite, false));
+        self::assertSame('1', $metas['us_auto_approve'] ?? null);
+    }
+
+    public function testGroupInviteRendersEditableEmailField(): void
+    {
+        $_REQUEST = ['us_invite' => 'raw-token'];
+        Functions\when('is_user_logged_in')->justReturn(false);
+        Functions\when('sanitize_key')->alias(static fn ($v) => strtolower((string) $v));
+        Functions\when('wp_login_url')->justReturn('http://home.test/wp-login.php');
+        Functions\when('wp_nonce_field')->justReturn('');
+        // Invite-only mode: only the group link grants access to the form.
+        $this->ctx['settings']->shouldReceive('openRegistrationEnabled')->andReturn(false);
+
+        $invite = new Invite(
+            email: '',
+            token: 'hash',
+            createdAt: '2024-01-01 00:00:00',
+            kind: Invite::KIND_GROUP,
+            expiresAt: '2024-02-01 23:59:59',
+            id: 9
+        );
+        $this->ctx['invites']->shouldReceive('findByToken')
+            ->once()
+            ->with(Invite::hashToken('raw-token'))
+            ->andReturn($invite);
+
+        $html = $this->ctx['page']->render([]);
+
+        self::assertStringContainsString('<form', $html);
+        self::assertStringContainsString('name="email"', $html);
+        self::assertStringNotContainsString('readonly', $html);
+    }
+
     public function testClosedModeWithoutInviteReturnsError(): void
     {
         $result = $this->submit(null, false);

tests/Unit/Auth/RegistrationStatusTest.php

@@ -42,10 +42,41 @@ class RegistrationStatusTest extends TestCase
         Functions\expect('delete_user_meta')->once()->with(7, RegistrationStatus::META_AWAITING_APPROVAL);
         Functions\expect('delete_user_meta')->once()->with(7, RegistrationStatus::META_CONFIRM_TOKEN);
         Functions\expect('delete_user_meta')->once()->with(7, RegistrationStatus::META_CONFIRM_EXPIRES);
+        Functions\expect('delete_user_meta')->once()->with(7, RegistrationStatus::META_AUTO_APPROVE);
 
         RegistrationStatus::approve(7);
     }
 
+    public function testMarkPendingWithAutoApproveSetsMarkerMeta(): void
+    {
+        Functions\when('wp_generate_password')->justReturn('rawtoken');
+
+        Functions\expect('update_user_meta')
+            ->once()
+            ->with(7, RegistrationStatus::META_AWAITING_APPROVAL, '1');
+        Functions\expect('update_user_meta')
+            ->once()
+            ->with(7, RegistrationStatus::META_CONFIRM_TOKEN, hash('sha256', 'rawtoken'));
+        Functions\expect('update_user_meta')
+            ->once()
+            ->with(7, RegistrationStatus::META_CONFIRM_EXPIRES, \Mockery::type('string'));
+        Functions\expect('update_user_meta')
+            ->once()
+            ->with(7, RegistrationStatus::META_AUTO_APPROVE, '1');
+
+        self::assertSame('rawtoken', RegistrationStatus::markPending(7, true));
+    }
+
+    public function testIsAutoApproveReadsMeta(): void
+    {
+        Functions\when('get_user_meta')->alias(static function (int $id, string $key) {
+            return $key === RegistrationStatus::META_AUTO_APPROVE ? '1' : '';
+        });
+
+        self::assertTrue(RegistrationStatus::isAutoApprove(7));
+        self::assertFalse(RegistrationStatus::isAwaitingApproval(7));
+    }
+
     public function testAwaitingApprovalAndEmailConfirmedReadMeta(): void
     {
         Functions\when('get_user_meta')->alias(static function (int $id, string $key) {