<?php
/**
 * Enforces the session policy: idle timeout and concurrent-session limit (#6).
 *
 * @package ActivityLog404
 */

namespace ActivityLog404\Sessions;

defined( 'ABSPATH' ) || exit;

/**
 * The idle timeout is enforced AT REQUEST TIME, on `init`, not by cron.
 *
 * A session can only be used by a request, and every WordPress request --
 * page, wp-admin, admin-ajax, admin-post, REST -- runs `init` with the
 * cookie's user already resolvable. So checking there is complete: no idle
 * session can act without first being checked. A cron sweep (WP Activity
 * Log's documented design runs one hourly) would add a schedule to manage
 * and could only ever be as precise as its interval; this is precise to the
 * write throttle (see SessionPolicy::throttle_seconds()). What it gives up:
 * an idle session that never makes another request is not removed from
 * storage until it expires on its own. It can do nothing in that state,
 * and the Sessions screen labels it "idle -- ends on next use".
 *
 * Last-activity is recorded only for users an idle timeout applies to, and
 * only while one is configured: no policy, no tracking. It is stored inside
 * core's own session record (SessionStore::LAST_ACTIVITY_KEY) through
 * core's PUBLIC API -- WP_Session_Tokens::get()/update() by the raw token
 * this request holds -- so it works under any session manager, and it goes
 * wherever the session goes.
 *
 * WordPress's Heartbeat (an open wp-admin tab polls admin-ajax every 15-60
 * seconds) is checked but never counted as activity: otherwise a tab left
 * open over a weekend would keep its session alive forever, which is the
 * exact case an idle timeout exists for. When the check ends a session
 * during a heartbeat, core's own auth-check shows its re-login dialog.
 *
 * The concurrent-session limit is enforced when a session is CREATED, on
 * `set_logged_in_cookie`, and it LOGS OUT THE OLDEST session rather than
 * refusing the new login. Both designs exist in the market (WP Activity
 * Log offers "block" and "override"); this plugin picks one, because:
 *  - refusing new logins hands the account to whoever signed in first. A
 *    stolen session, or one left open on a library computer, then locks
 *    the real owner out until an administrator intervenes;
 *  - evicting the oldest favours the person who has just proved they hold
 *    the password, needs no administrator, and cannot lock anyone out;
 *  - the cost -- someone else with the password can push the owner out --
 *    is not a new capability (a password holder can already change the
 *    password), and every eviction is written to the log.
 * The limit uses SessionStore, so it needs core's default session storage;
 * under a custom manager it is inert, and the Sessions screen says so.
 */
final class Enforcer {

	/** The login screen's query flag that shows the idle-logout message. */
	public const LOGIN_FLAG = 'ops404_al_idle';

	/** check_current_request() outcomes. */
	public const NOT_APPLICABLE = 'not_applicable';
	public const ACTIVE         = 'active';
	public const TOUCHED        = 'touched';
	public const EXPIRED        = 'expired';

	/**
	 * Hook registration, from Plugin::boot() -- on EVERY request, not just
	 * admin ones, since the front end uses sessions too.
	 */
	public static function register(): void {
		// Priority 1: before anything else on init acts as this user.
		add_action( 'init', array( __CLASS__, 'on_init' ), 1 );
		add_action( 'set_logged_in_cookie', array( __CLASS__, 'on_logged_in_cookie' ), 10, 6 );
		add_filter( 'wp_login_errors', array( __CLASS__, 'login_message' ) );
	}

	/**
	 * The `init` callback: the decision is check_current_request(); this
	 * only acts on its answer. Kept apart because a redirect ends in exit,
	 * which would end a PHPUnit run mid-test (OPERATIONS.md §4).
	 */
	public static function on_init(): void {
		if ( self::EXPIRED !== self::check_current_request( time(), self::is_heartbeat() ) ) {
			return;
		}

		if ( ! headers_sent() ) {
			wp_clear_auth_cookie();
		}

		// A wp-admin page gets the login screen with the reason on it. The
		// front end continues as a signed-out visitor (its pages are public;
		// redirecting a reader to a login form would be the wrong answer),
		// and ajax/REST answer as signed out, which is what their callers
		// already handle.
		if ( is_admin() && ! wp_doing_ajax() && ! ( \defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
			wp_safe_redirect( add_query_arg( self::LOGIN_FLAG, '1', wp_login_url() ) );
			exit;
		}
	}

	/**
	 * Check the signed-in session against the idle timeout: end it, or
	 * record activity (throttled), or leave it be.
	 *
	 * @param int  $now     The current Unix time (a parameter so the boundary is testable).
	 * @param bool $passive True for a request that is not the user's own activity (Heartbeat): checked, never recorded.
	 * @return string One of the outcome constants.
	 */
	public static function check_current_request( int $now, bool $passive = false ): string {
		$user = wp_get_current_user();
		if ( ! $user->exists() ) {
			return self::NOT_APPLICABLE;
		}

		$token = wp_get_session_token();
		if ( '' === $token ) {
			// Application passwords, XML-RPC, WP-CLI: no browser session.
			return self::NOT_APPLICABLE;
		}

		$idle_seconds = SessionPolicy::idle_seconds_for( $user );
		if ( $idle_seconds <= 0 ) {
			return self::NOT_APPLICABLE;
		}

		$manager = \WP_Session_Tokens::get_instance( $user->ID );
		$session = $manager->get( $token );
		if ( ! is_array( $session ) ) {
			return self::NOT_APPLICABLE;
		}

		$last = isset( $session[ SessionStore::LAST_ACTIVITY_KEY ] ) && is_numeric( $session[ SessionStore::LAST_ACTIVITY_KEY ] )
			? (int) $session[ SessionStore::LAST_ACTIVITY_KEY ]
			: null;

		// A session that predates the policy (or its user's timeout) starts
		// its clock now. Measuring it from its login time instead would end,
		// the moment a policy is saved, every long session that is in use
		// right now -- including the administrator's who saved it.
		if ( null === $last ) {
			$session[ SessionStore::LAST_ACTIVITY_KEY ] = $now;
			$manager->update( $token, $session );
			return self::TOUCHED;
		}

		$throttle = SessionPolicy::throttle_seconds( $idle_seconds );

		// Never early: see SessionPolicy::throttle_seconds().
		if ( $now - $last >= $idle_seconds + $throttle ) {
			$manager->destroy( $token );
			SessionLog::idle_expired( $user, $session, $idle_seconds );
			wp_set_current_user( 0 );
			return self::EXPIRED;
		}

		if ( $passive || $now - $last < $throttle ) {
			return self::ACTIVE;
		}

		$session[ SessionStore::LAST_ACTIVITY_KEY ] = $now;
		$manager->update( $token, $session );

		return self::TOUCHED;
	}

	/**
	 * `set_logged_in_cookie`: a session was just created (or re-issued) for
	 * this user; enforce the limit around it.
	 *
	 * @param string $logged_in_cookie Unused.
	 * @param int    $expire           Unused.
	 * @param int    $expiration       Unused.
	 * @param int    $user_id          The user.
	 * @param string $scheme           Unused.
	 * @param string $token            The new session's token.
	 */
	public static function on_logged_in_cookie( $logged_in_cookie, $expire, $expiration, $user_id, $scheme = '', $token = '' ): void {
		unset( $logged_in_cookie, $expire, $expiration, $scheme );
		self::enforce_limit( (int) $user_id, (string) $token );
	}

	/**
	 * End the user's oldest sessions until at most their limit remain,
	 * never the one named by $token. Returns how many were ended.
	 *
	 * @param int    $user_id The user.
	 * @param string $token   The session to keep (just created).
	 */
	public static function enforce_limit( int $user_id, string $token ): int {
		$user = get_userdata( $user_id );
		if ( ! $user instanceof \WP_User || '' === $token || ! SessionStore::supported() ) {
			return 0;
		}

		$limit = SessionPolicy::session_limit_for( $user );
		if ( $limit <= 0 ) {
			return 0;
		}

		$keep     = hash( 'sha256', $token );
		$sessions = SessionStore::sessions( $user_id );
		$excess   = count( $sessions ) - $limit;
		if ( $excess <= 0 ) {
			return 0;
		}

		// sessions() is newest-first; the oldest are at the end.
		$oldest_first = array_reverse( $sessions, true );
		$ended        = 0;
		foreach ( $oldest_first as $verifier => $session ) {
			if ( $ended >= $excess ) {
				break;
			}
			if ( hash_equals( $keep, (string) $verifier ) ) {
				continue;
			}
			if ( SessionStore::destroy( $user_id, (string) $verifier ) ) {
				SessionLog::limit_evicted( $user, $session, $limit );
				++$ended;
			}
		}

		return $ended;
	}

	/**
	 * `wp_login_errors`: say why, on the login screen an idle logout lands
	 * on. The flag carries no data -- anyone can add it to a URL and see
	 * only this sentence.
	 *
	 * @param mixed $errors Core's WP_Error of login messages.
	 * @return mixed
	 */
	public static function login_message( $errors ) {
		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- a display-only flag; no state changes.
		if ( ! $errors instanceof \WP_Error || ! isset( $_GET[ self::LOGIN_FLAG ] ) ) {
			return $errors;
		}

		$errors->add(
			'ops404_al_idle',
			__( 'You were logged out because your session was inactive for too long. Please log in again.', '404ops-activity-log' ),
			'message'
		);

		return $errors;
	}

	/**
	 * Whether this request is WordPress's Heartbeat poll.
	 */
	private static function is_heartbeat(): bool {
		// phpcs:ignore WordPress.Security.NonceVerification.Missing -- read to classify the request, never to act on it.
		return wp_doing_ajax() && isset( $_POST['action'] ) && 'heartbeat' === $_POST['action'];
	}
}