Session.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Session - Session
 *
 * @package Italix\Session
 */

declare(strict_types=1);

namespace Italix\Session;

use Italix\Session\Stores\NativeSessionStore;

/**
 * The session of the request being served — global state with a declared
 * beginning and end.
 *
 * **Why static, when a session on the PSR-7 request is the better
 * architecture.** Because of one call site shape that is extremely common: a
 * static helper reached from deep inside a base controller, where no request is
 * in scope. Threading a request down through a whole CRUD hierarchy to reach it
 * is a refactor of the application, not an adoption of a library. The bargain
 * here is the same one `Italix\Mvc\Translator` took: state that is global but
 * **explicitly scoped and reset**, with `end()` in a `finally` so a thrown
 * controller cannot leave the next request holding this one's identity.
 *
 * That last sentence is the whole reason this class exists. The code it
 * replaces reads:
 *
 *     if (session_status() === PHP_SESSION_NONE) {
 *         session_start();
 *     }
 *
 * Under PHP-FPM that is correct defensive code. Under a resident worker it *is*
 * the defect: request A opens the session and never closes it, request B finds
 * the status still active, the guard returns early, and B is served A's
 * `$_SESSION` — a different person's identity, not merely stale data. It is not
 * the careless code that breaks on the move to a worker; it is the code written
 * with caution.
 *
 * **Strict mode is structural.** PHP's `session.use_strict_mode` exists because
 * PHP will create a session for any identifier a client invents. Here an
 * identifier that the store has never issued simply finds no record, which is
 * `ABSENT`, and a fresh identifier is minted — so an attacker-chosen id is
 * never adopted and there is no setting to forget.
 *
 * Sound under a worker that serves one request at a time (RoadRunner,
 * FrankenPHP). **Not** sound under coroutines, where several requests share one
 * memory space at the same instant; that is a bridge to cross only if it is
 * ever reached, and it would mean moving to a session carried on the request.
 */
final class Session
{
    private static ?SessionStore $store = null;

    private static ?CookieSpec $cookie = null;

    private static ?SessionPolicy $policy = null;

    private static ?SessionRecord $record = null;

    private static ?SessionData $data = null;

    private static string $state_c = SessionState::ABSENT;

    private static bool $begun_flag = false;

    private static bool $cookie_dirty_flag = false;

    private static bool $destroy_flag = false;

    /**
     * Whether this request decided the tenant.
     *
     * A flag rather than a null check, because unlike the subject the tenant can
     * legitimately be set **back to null** — a staff member ending a support
     * session. Copying "only when not null" onto the stored row, the way the
     * subject is copied, would make leaving impersonation a no-op that persists
     * across requests.
     */
    private static bool $tenant_dirty_flag = false;

    /** The subject of a session that was refused, so a caller can revoke it. */
    private static ?string $refused_subject_c = null;

    /** @var array{0: string, 1: string}|null device details recorded before a record exists */
    private static ?array $pending_device = null;

    /** @var callable():int */
    private static $clock;

    /** Follow at most this many rotation hops before giving up on a cycle. */
    private const ROTATION_HOPS_N = 8;

    // =========================================================================
    // Lifecycle — called by the middleware, and by nothing else
    // =========================================================================

    /**
     * Load the session named by the cookie, or start an empty one.
     *
     * Returns the resulting state so a middleware can act on it without a
     * second call. Nothing is written and no identifier is minted here: an
     * anonymous request that never touches the session leaves no row and gets
     * no cookie, which is what keeps a crawler from filling the table.
     *
     * @param string|null $id_c the value of the session cookie, if any
     */
    public static function begin(
        SessionStore $store,
        CookieSpec $cookie,
        ?string $id_c = null,
        ?SessionPolicy $policy = null
    ): string {
        $cookie->validate();

        $policy = $policy ?? new SessionPolicy();

        // A limit the store cannot enforce is refused here rather than ignored
        // per login. Accepting it would mean an application configured to allow
        // two sessions per user allows any number, and nothing ever says so.
        if ($policy->has_concurrency_cap() && !$store->can_find_by_subject()) {
            throw new SessionException(
                'SessionPolicy::max_concurrent() needs a store that can find sessions by subject, and '
                . get_class($store) . ' cannot. Use PdoSessionStore, or drop the cap.'
            );
        }

        self::reset();

        self::$store      = $store;
        self::$cookie     = $cookie;
        self::$policy     = $policy;
        self::$data       = SessionData::empty();
        self::$begun_flag = true;
        self::$state_c    = SessionState::ABSENT;

        if ($id_c === null || !self::is_well_formed($id_c)) {
            return self::$state_c;
        }

        $record = self::resolve($store->find($id_c), self::now_t());

        if ($record === null) {
            return self::$state_c;
        }

        self::$record  = $record;
        self::$data    = SessionData::from_array($record->payload());
        self::$state_c = SessionState::ACTIVE;

        $record->touch(self::now_t());

        return self::$state_c;
    }

    /**
     * Adopt PHP's own session as the store — the transition path.
     *
     * This exists so an application can move its call sites through one door
     * **before** moving its data. Everything below keeps working, the storage
     * does not change, nobody is signed out, and the switch to a real store is
     * afterwards a line of configuration. What it cannot offer is the register:
     * `$_SESSION` has no index, so `can_find_by_subject()` is false and the
     * revocation methods refuse.
     *
     * A `CookieSpec` given here **is** applied, even though PHP owns the cookie:
     * the adapter pushes it into `session_set_cookie_params()` before starting.
     * That is what lets an application fix `HttpOnly`, `SameSite` and `Secure` at
     * step one, before its storage moves anywhere. Pass nothing and PHP's own
     * parameters are left exactly as they were.
     */
    public static function begin_native(?CookieSpec $cookie = null, ?SessionPolicy $policy = null): string
    {
        // Validate before starting: a contradiction has to surface as a message
        // naming it, not as a session cookie that silently never arrives.
        if ($cookie !== null) {
            $cookie->validate();
        }

        $store = new NativeSessionStore();
        $store->start($cookie);

        return self::begin(
            $store,
            $cookie ?? new CookieSpec((string) (session_name() ?: 'PHPSESSID')),
            $store->current_token(),
            $policy
        );
    }

    /**
     * Persist if anything changed, reset the static state, and hand back the
     * cookie for the middleware to put on the response.
     *
     * Safe to call when `begin()` never ran, and safe to call twice: both
     * return an inert outcome. That matters because the correct place for this
     * call is a `finally`.
     */
    public static function end(): Outcome
    {
        if (!self::$begun_flag) {
            return new Outcome(SessionState::ABSENT);
        }

        $now_t   = self::now_t();
        $cookie  = self::$cookie;
        $state_c = self::$state_c;

        if (self::$destroy_flag) {
            if (self::$record !== null) {
                self::$store->destroy(self::$record->token());
            }

            $expiry_c = self::$store->manages_cookie() ? null : $cookie->expiry_header();

            self::reset();

            return new Outcome($state_c, null, $expiry_c, true);
        }

        // An anonymous request that read nothing and wrote nothing: no row, no
        // identifier, no Set-Cookie. Most requests to a public page are this.
        if (self::$record === null && !self::$data->is_dirty()) {
            self::reset();

            return new Outcome($state_c);
        }

        if (self::$record === null) {
            self::ensure_record($now_t);
        }

        $local         = self::$record;
        $data          = self::$data;
        $id_c          = $local->token();
        $tenant_dirty_flag = self::$tenant_dirty_flag;

        $written = self::$store->transact($id_c, static function (?SessionRecord $fresh) use ($local, $data, $now_t, $tenant_dirty_flag): ?SessionRecord {
            // Revoked or rotated while this request was running: the other
            // decision is newer and wins. Writing here would resurrect a session
            // somebody has just signed out of.
            if ($fresh !== null && ($fresh->is_revoked() || $fresh->is_rotated())) {
                return $fresh;
            }

            $target = $fresh ?? $local;

            $target->set_payload($data->reconcile($fresh !== null ? $fresh->payload() : []));
            $target->touch($now_t);

            // Metadata decided by *this* request is copied onto whatever row is
            // actually there, so a concurrent write does not undo a login.
            if ($local->subject() !== null) {
                $target->set_subject($local->subject());
            }

            // The tenant is copied on the flag rather than on "not null",
            // because clearing it is a real decision — a support session ending.
            if ($tenant_dirty_flag) {
                $target->set_tenant($local->tenant());
            }

            if ($local->authenticated_t() !== null) {
                $target->set_authenticated($local->authenticated_t());
            }

            if ($local->expires_t() !== null) {
                $target->set_expires($local->expires_t());
            }

            if ($local->ip() !== '') {
                $target->set_device($local->ip(), $local->agent());
            }

            return $target;
        });

        $header_c = self::$cookie_dirty_flag && !self::$store->manages_cookie()
            ? $cookie->header_for($id_c, $now_t)
            : null;

        self::reset();

        return new Outcome($state_c, $id_c, $header_c, $written !== null);
    }

    /** Drop everything without persisting. For a test, or a request that must leave no trace. */
    public static function abandon(): void
    {
        self::reset();
    }

    public static function is_begun(): bool
    {
        return self::$begun_flag;
    }

    // =========================================================================
    // State
    // =========================================================================

    /** One of `SessionState`'s six constants. */
    public static function state(): string
    {
        return self::$state_c;
    }

    public static function is_active(): bool
    {
        return self::$state_c === SessionState::ACTIVE;
    }

    public static function token(): ?string
    {
        return self::$record !== null ? self::$record->token() : null;
    }

    public static function subject(): ?string
    {
        return self::$record !== null ? self::$record->subject() : null;
    }

    /**
     * The subject of the session that was just refused — revoked, expired or
     * replayed.
     *
     * The reason this is exposed: on `ROTATED` the right response is to revoke
     * **every** session of that subject, because the identifier was copied and
     * the thief may be holding the current one rather than the stale one. That
     * needs a subject, and the refused record is the only place it exists.
     */
    public static function refused_subject(): ?string
    {
        return self::$refused_subject_c;
    }

    public static function record(): ?SessionRecord
    {
        return self::$record;
    }

    // =========================================================================
    // Data
    // =========================================================================

    public static function current(): SessionData
    {
        self::require_begun();

        return self::$data;
    }

    /** Store a typed payload. See `SessionPayload` for why this is not five string keys. */
    public static function put(SessionPayload $payload): void
    {
        self::current()->put($payload);
    }

    /**
     * The payload of that class, or null.
     *
     * **Null does not mean "the other kind of actor". It means nobody.** An
     * application that infers a role from the *absence* of a value has written
     * the failure mode this library exists to remove: the same missing value
     * fails closed in an authentication check and fails open in a tenant scope.
     */
    public static function typed(string $class_c): ?SessionPayload
    {
        return self::current()->typed($class_c);
    }

    // =========================================================================
    // Identity
    // =========================================================================

    /**
     * Record that this session now belongs to a subject, rotating the
     * identifier because the privileges changed.
     *
     * The payload is carried across a rotation on purpose. That is the case
     * which breaks in every implementation that *destroys* the session at
     * login instead of rotating it: a storefront's guest cart disappears at
     * exactly the moment the customer decided to buy.
     *
     * The exception is a session that already belonged to **someone else** —
     * signing in as B over A's session keeps nothing, because none of it was
     * about B.
     *
     * @param string      $subject_c opaque and application-shaped: `"account:12"`.
     *        The library never parses it; it is the string the register indexes
     *        on, so changing its format later means old revocations stop
     *        matching.
     * @param string|null $tenant_c the organisation this person is signing in to,
     *        for an application that sells seats to organisations rather than to
     *        people. Indexed separately, so suspending a subscription can sign
     *        out everybody inside it at once.
     *
     * @return int how many other sessions were signed out to honour
     *         `SessionPolicy::max_concurrent()` — zero when there is no cap.
     *         Returned rather than swallowed so the application can say
     *         *"you were signed out on 1 other device"* instead of leaving
     *         somebody to discover it on their phone.
     */
    public static function authenticate(
        string $subject_c,
        ?SessionPayload $payload = null,
        ?string $tenant_c = null
    ): int {
        self::require_begun();

        if ($subject_c === '') {
            throw new SessionException('A subject cannot be an empty string; use forget() to sign out.');
        }

        $now_t = self::now_t();

        if (self::$record === null) {
            self::ensure_record($now_t);
        } else {
            $previous_c = self::$record->subject();

            if ($previous_c !== null && $previous_c !== $subject_c) {
                self::$data->clear();
            }

            self::regenerate();
        }

        self::$record->set_subject($subject_c)->set_authenticated($now_t);
        self::$state_c = SessionState::ACTIVE;

        if ($tenant_c !== null) {
            self::set_tenant($tenant_c);
        }

        if ($payload !== null) {
            self::$data->put($payload);
        }

        return self::enforce_concurrency($subject_c);
    }

    /**
     * Put this session inside an organisation, or take it out of one.
     *
     * Separate from `authenticate()` because the two happen at different
     * moments, and the case that proves it is support impersonation: a staff
     * member steps into a customer's account without proving an identity that
     * never changed, so `authenticated_t` must not move and a step-up window
     * must not silently restart. Their `subject_c` stays their own — which is
     * what keeps the audit trail true, keeps *their* password change able to
     * end the session, and keeps the customer's seat count honest.
     *
     * Rotating the identifier afterwards is the caller's decision and usually
     * the right one, because the privileges did change:
     *
     *     Session::set_tenant('tenant:7');
     *     Session::regenerate();
     */
    public static function set_tenant(?string $tenant_c): void
    {
        self::require_begun();

        if ($tenant_c === '') {
            throw new SessionException('A tenant cannot be an empty string; pass null to leave one.');
        }

        if (self::$record === null) {
            self::ensure_record(self::now_t());
        }

        self::$record->set_tenant($tenant_c);
        self::$tenant_dirty_flag = true;
    }

    /** The organisation this session is inside, or null. */
    public static function tenant(): ?string
    {
        return self::$record !== null ? self::$record->tenant() : null;
    }

    /**
     * Refresh the proof of identity without rotating the identifier.
     *
     * Deliberately different from `authenticate()`: privileges have not
     * changed, only the freshness of the proof, and rotating on every step-up
     * would discard the device list every time somebody pays.
     */
    public static function reauthenticate(): void
    {
        self::require_begun();

        if (self::$record === null || self::$record->subject() === null) {
            throw new SessionException('reauthenticate() needs a session that has authenticated at least once.');
        }

        self::$record->set_authenticated(self::now_t());
    }

    /** When identity was last proved, or null if it never was. */
    public static function authenticated_t(): ?int
    {
        return self::$record !== null ? self::$record->authenticated_t() : null;
    }

    /**
     * Whether the proof of identity is younger than this.
     *
     *     if (!Session::authenticated_within(900)) {
     *         return $this->redirect_to('/step-up');
     *     }
     *
     * A session that never authenticated returns **false** — the null fails
     * closed, which is the opposite of what a bag of string keys does.
     */
    public static function authenticated_within(int $seconds_n): bool
    {
        $authenticated_t = self::authenticated_t();

        return $authenticated_t !== null && (self::now_t() - $authenticated_t) <= $seconds_n;
    }

    /**
     * Issue a new identifier for the same session, keeping the data.
     *
     * The control against session fixation, and the thing every hand-rolled
     * session layer forgets. The old identifier is kept as a tombstone pointing
     * at this one, which is what makes a later replay detectable rather than
     * merely absent.
     */
    public static function regenerate(): void
    {
        self::require_begun();

        $now_t = self::now_t();

        if (self::$record === null) {
            // Nothing has been stored yet, so there is no identifier to retire;
            // end() will mint one.
            self::$cookie_dirty_flag = true;

            return;
        }

        $previous = self::$record;

        // A store that owns the identifier does the whole rotation itself, and
        // there is then no tombstone to write — PHP's `session_regenerate_id()`
        // deletes the old row, which is why replay detection arrives with a real
        // store rather than with the native adapter.
        $store_rotated_c = self::$store->rotate($previous->token());

        if ($store_rotated_c !== null) {
            $successor_c = $store_rotated_c;
        } else {
            $successor_c = self::successor_token();

            self::$store->transact($previous->token(), static function (?SessionRecord $fresh) use ($previous, $successor_c, $now_t): ?SessionRecord {
                $target = $fresh ?? $previous;

                return $target->rotate_to($successor_c, $now_t);
            });
        }

        // The successor's row is empty, so everything this request can see has
        // to be written wholesale — otherwise the untouched half of the payload
        // would be reconciled against nothing and silently lost.
        self::$data->promote_all();

        self::$record            = SessionRecord::successor_of($previous, $successor_c, $now_t);
        self::$cookie_dirty_flag = true;
    }

    /** Sign out: destroy this session and expire its cookie. Other devices are untouched. */
    public static function forget(): void
    {
        self::require_begun();

        self::$destroy_flag = true;
        self::$data         = SessionData::empty();
    }

    // =========================================================================
    // The register
    // =========================================================================

    /** A register over the store this request is using. */
    public static function register(): SessionRegister
    {
        self::require_begun();

        return new SessionRegister(self::$store, self::$clock, self::$policy);
    }

    // =========================================================================
    // CSRF and flash
    // =========================================================================

    /*
     * These four live on the facade rather than in `Italix\Mvc` for a practical
     * reason and are documented here so the decision is visible: a CSRF token is
     * an HTTP concern and belongs with the middleware that checks it, but moving
     * it would rewrite every template in every project for no behavioural gain.
     * They are thin: the storage is the ordinary bag, under the same key names
     * `Italix\Mvc\Session` already used, so an application adopting
     * `begin_native()` keeps every signed-in user's existing token rather than
     * failing their next form post.
     */

    public const CSRF_KEY = '_csrf_token';

    public const FLASH_KEY = '_flash';

    public static function csrf_token(): string
    {
        $token_c = self::current()->get(self::CSRF_KEY);

        if (!is_string($token_c) || $token_c === '') {
            $token_c = bin2hex(random_bytes(32));

            self::current()->set(self::CSRF_KEY, $token_c);
        }

        return $token_c;
    }

    /**
     * A ready-to-embed hidden input.
     *
     * `htmlspecialchars()` is called here rather than through `Italix\Encode`
     * because house rule 13 makes a library a leaf: this package may depend on
     * nothing but `Italix\Contracts`. The guarantee is duplicated and therefore
     * has to be *covered* — there is a test that a payload cannot escape this
     * attribute.
     */
    public static function csrf_field(): string
    {
        return '<input type="hidden" name="' . self::CSRF_KEY . '" value="'
            . htmlspecialchars(self::csrf_token(), ENT_QUOTES, 'UTF-8') . '">';
    }

    public static function validate_csrf(string $token_c): bool
    {
        $stored_c = self::current()->get(self::CSRF_KEY);

        return is_string($stored_c) && $stored_c !== '' && hash_equals($stored_c, $token_c);
    }

    public static function flash(string $type_c, string $message_c): void
    {
        // merge() rather than set(): two requests can both flash, and losing one
        // of the two messages is the small version of the same defect.
        self::current()->merge(self::FLASH_KEY, static function ($messages) use ($type_c, $message_c): array {
            $messages   = is_array($messages) ? $messages : [];
            $messages[] = ['type' => $type_c, 'message' => $message_c];

            return $messages;
        }, []);
    }

    /** @return array<int, array{type: string, message: string}> */
    public static function pull_flash(): array
    {
        $messages = self::current()->pull(self::FLASH_KEY, []);

        return is_array($messages) ? $messages : [];
    }

    public static function has_flash(): bool
    {
        $messages = self::current()->get(self::FLASH_KEY, []);

        return is_array($messages) && $messages !== [];
    }

    // =========================================================================
    // Wiring
    // =========================================================================

    /** Record where the request came from, for the device list and the audit trail. */
    public static function device(string $ip_c, string $agent_c): void
    {
        self::require_begun();

        if (self::$record !== null) {
            self::$record->set_device($ip_c, $agent_c);

            return;
        }

        // No record yet: remember it so ensure_record() can apply it if this
        // request turns out to write something.
        self::$pending_device = [$ip_c, $agent_c];
    }

    /**
     * Replace the clock. For tests only — everything here decides expiry by
     * comparison, so a suite can age a session by a day without sleeping.
     *
     * @param callable():int $clock
     */
    public static function use_clock(callable $clock): void
    {
        self::$clock = $clock;
    }

    public static function use_system_clock(): void
    {
        self::$clock = null;
    }

    // =========================================================================
    // Internals
    // =========================================================================

    /**
     * Decide what a stored record means right now: follow a rotation inside the
     * grace window, and set the state when it means nothing usable.
     */
    private static function resolve(?SessionRecord $record, int $now_t): ?SessionRecord
    {
        if ($record === null) {
            return null;
        }

        for ($hop_n = 0; $record->is_rotated(); $hop_n++) {
            self::$refused_subject_c = $record->subject();

            $within_grace_flag = ($now_t - (int) $record->rotated_t()) <= self::$policy->get_rotation_grace_n();

            if (!$within_grace_flag || $record->successor_token() === null || $hop_n >= self::ROTATION_HOPS_N) {
                self::$state_c = SessionState::ROTATED;

                // Whose replay this is has to be answered from the *successor*,
                // not from the tombstone. A guest session that rotated at login
                // was anonymous at the moment it was retired, so its own row
                // names nobody — and "revoke every session of nobody" is not a
                // response to a stolen cookie.
                self::$refused_subject_c = self::subject_of_successor($record);

                return null;
            }

            $next = self::$store->find((string) $record->successor_token());

            if ($next === null) {
                // The successor was destroyed — a sign-out that raced this
                // request. Absent, not stolen.
                self::$state_c = SessionState::ABSENT;

                return null;
            }

            $record = $next;
        }

        self::$refused_subject_c = $record->subject();

        if ($record->is_revoked()) {
            self::$state_c = SessionState::REVOKED;

            return null;
        }

        if ($record->expires_t() !== null && $now_t > (int) $record->expires_t()) {
            self::$state_c = SessionState::EXPIRED_ABSOLUTE;

            return null;
        }

        if (self::$policy->has_idle_window()
            && ($now_t - $record->last_seen_t()) > self::$policy->get_idle_ttl_n()) {
            self::$state_c = SessionState::EXPIRED_IDLE;

            return null;
        }

        self::$refused_subject_c = null;

        return $record;
    }

    /**
     * Follow the rotation chain forward to find who the session became.
     *
     * Bounded, because a corrupt store could describe a cycle and a session
     * lookup is not a place to hang.
     */
    private static function subject_of_successor(SessionRecord $tombstone): ?string
    {
        $record = $tombstone;

        for ($hop_n = 0; $hop_n < self::ROTATION_HOPS_N; $hop_n++) {
            if ($record->subject() !== null) {
                return $record->subject();
            }

            if ($record->successor_token() === null) {
                return null;
            }

            $next = self::$store->find((string) $record->successor_token());

            if ($next === null) {
                return null;
            }

            $record = $next;
        }

        return null;
    }

    /**
     * Sign out the least recently used sessions until this subject is inside the
     * configured cap, counting the one being created now.
     *
     * The session this request is opening is deliberately **not** in the list
     * `of_subject()` returns: it is either brand new and unwritten, or it has
     * just rotated and its predecessor is a tombstone. So the target is one
     * below the cap — leaving room for the login in progress — and the current
     * identifier is spared anyway, because a store that behaved differently
     * would otherwise sign the user out of the browser they are looking at.
     *
     * @return int how many fell
     */
    private static function enforce_concurrency(string $subject_c): int
    {
        if (!self::$policy->has_concurrency_cap()) {
            return 0;
        }

        // begin() refuses a cap the store cannot enforce, so reaching here with
        // an unindexed store is not possible. Checked anyway: this is the branch
        // where being wrong means a limit that quietly does nothing.
        if (!self::$store->can_find_by_subject()) {
            return 0;
        }

        $current_c = self::$record !== null ? self::$record->token() : null;
        $keep_n    = max(0, self::$policy->get_max_concurrent_n() - 1);

        // Newest first, so the ones to evict are at the end.
        $live = array_values(array_filter(
            self::$store->of_subject($subject_c),
            static function (SessionRecord $record) use ($current_c): bool {
                return $record->token() !== $current_c;
            }
        ));

        $evicted_n = 0;

        for ($index_n = count($live) - 1; $index_n >= $keep_n; $index_n--) {
            if (self::$store->revoke($live[$index_n]->token(), 'concurrent_limit')) {
                $evicted_n++;
            }
        }

        return $evicted_n;
    }

    private static function ensure_record(int $now_t): void
    {
        $record = SessionRecord::create(self::successor_token(), $now_t);

        if (self::$policy->has_absolute_cap()) {
            $record->set_expires($now_t + self::$policy->get_absolute_ttl_n());
        }

        if (self::$pending_device !== null) {
            $record->set_device(self::$pending_device[0], self::$pending_device[1]);
        }

        self::$record            = $record;
        self::$cookie_dirty_flag = true;
    }

    private static function successor_token(): string
    {
        return bin2hex(random_bytes(32));
    }

    /**
     * Reject an identifier that cannot have been issued here before it reaches
     * a store — a filesystem path, a SQL fragment, a megabyte of text.
     *
     * Deliberately permissive about length and alphabet so PHP's own session
     * ids pass under `begin_native()`. It is not a security control: the
     * security control is that an unknown identifier finds no record.
     */
    private static function is_well_formed(string $id_c): bool
    {
        return preg_match('/^[A-Za-z0-9_-]{16,128}$/', $id_c) === 1;
    }

    private static function now_t(): int
    {
        if (self::$clock !== null) {
            return (int) call_user_func(self::$clock);
        }

        return time();
    }

    private static function require_begun(): void
    {
        if (!self::$begun_flag) {
            throw new SessionException(
                'Session::begin() has not run. The middleware owns the lifecycle; '
                . 'reaching the facade outside it means the request has no session to speak of.'
            );
        }
    }

    private static function reset(): void
    {
        self::$store             = null;
        self::$cookie            = null;
        self::$policy            = null;
        self::$record            = null;
        self::$data              = null;
        self::$state_c           = SessionState::ABSENT;
        self::$begun_flag        = false;
        self::$cookie_dirty_flag = false;
        self::$destroy_flag      = false;
        self::$tenant_dirty_flag = false;
        self::$refused_subject_c = null;
        self::$pending_device    = null;
    }
}