unsupervised-scheduler/src/Auth/Invite.php

<?php
declare(strict_types=1);

namespace Unsupervised\Schedular\Auth;

use Unsupervised\Schedular\Val;

class Invite {

	public const STATUS_PENDING  = 'pending';
	public const STATUS_ACCEPTED = 'accepted';
	public const STATUS_REVOKED  = 'revoked';

	/** Single-use invite addressed to one email. */
	public const KIND_PERSONAL = 'personal';

	/** Multi-use shareable link (e.g. for a newsletter) with an explicit expiry. */
	public const KIND_GROUP = 'group';

	/**
	 * All valid invite statuses.
	 *
	 * @var list<string>
	 */
	public const VALID_STATUSES = [ self::STATUS_PENDING, self::STATUS_ACCEPTED, self::STATUS_REVOKED ];

	/**
	 * Days a pending invite remains usable after it is created. Limits the window
	 * in which a leaked or forwarded invitation link can be redeemed.
	 */
	public const EXPIRY_DAYS = 14;

	/**
	 * Hash a raw invitation token for storage and lookup. Only the hash is
	 * persisted, so a database leak (backup, SQL injection elsewhere) cannot be
	 * used to redeem pending invites; the raw token exists only in the emailed
	 * link and is shown to the admin once, at creation.
	 */
	public static function hashToken( string $rawToken ): string {
		return hash( 'sha256', $rawToken );
	}

	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 ?string $createdAt = null,
		public readonly string $kind = self::KIND_PERSONAL,
		public readonly ?string $expiresAt = null,
		public readonly ?int $offeringId = null,
		public readonly ?int $id = null,
	) {}

	public static function fromRow( \stdClass $row ): self {
		return new self(
			email:          Val::string( $row->email ),
			token:          Val::string( $row->token ),
			role:           Val::string( $row->role ),
			status:         Val::string( $row->status ),
			invitedBy:      Val::intOrNull( $row->invited_by ),
			acceptedUserId: Val::intOrNull( $row->accepted_user_id ),
			acceptedAt:     Val::stringOrNull( $row->accepted_at ),
			createdAt:      Val::stringOrNull( $row->created_at ?? null ),
			kind:           '' !== Val::string( $row->kind ?? '' ) ? Val::string( $row->kind ) : self::KIND_PERSONAL,
			expiresAt:      Val::stringOrNull( $row->expires_at ?? null ),
			offeringId:     Val::intOrNull( $row->offering_id ?? null ),
			id:             Val::int( $row->id ),
		);
	}

	public function isGroup(): bool {
		return self::KIND_GROUP === $this->kind;
	}

	public function isPending(): bool {
		return self::STATUS_PENDING === $this->status;
	}

	/**
	 * Whether the invite has expired, measured against the supplied current
	 * `Y-m-d H:i:s` timestamp. An explicit `expires_at` (set on every group
	 * link) wins; otherwise a personal invite expires {@see EXPIRY_DAYS} after
	 * creation. An invite with neither timestamp is treated as not expired.
	 */
	public function isExpired( string $now ): bool {
		$current = strtotime( $now );
		if ( false === $current ) {
			return false;
		}

		if ( null !== $this->expiresAt ) {
			$expires = strtotime( $this->expiresAt );

			return false !== $expires && $current > $expires;
		}

		if ( null === $this->createdAt ) {
			return false;
		}

		$created = strtotime( $this->createdAt );
		if ( false === $created ) {
			return false;
		}

		return ( $current - $created ) > self::EXPIRY_DAYS * 86400;
	}

	/**
	 * Whether this invite can still be redeemed: pending and not expired.
	 */
	public function isAcceptable( string $now ): bool {
		return $this->isPending() && ! $this->isExpired( $now );
	}

	/**
	 * 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,
			'kind'             => $this->kind,
			'status'           => $this->status,
			'invited_by'       => $this->invitedBy,
			'accepted_user_id' => $this->acceptedUserId,
			'accepted_at'      => $this->acceptedAt,
			'expires_at'       => $this->expiresAt,
			'offering_id'      => $this->offeringId,
		];
	}
}