FileSessionStore

A session ledger on disk — the persistent counterpart of {@see InMemorySessionStore}, so a session minted in one request is still there in the next. {@see InMemorySessionStore} is enough within a single process (a test, a long-lived worker); a real HTTP login spans separate PHP processes, and needs its sessions to outlive the request that made them. This holds the same fail-closed contract — an expired or revoked record reads as absent, never as a live actor — over a JSON file with locked writes, mirroring the framework's other file stores. THE FILE KEYS A SESSION BY A DIGEST OF ITS ID, NEVER THE ID ITSELF. The session id is a bearer credential: it is exactly the value the browser sends back in the session cookie, and presenting it authenticates. So this store never writes it down — it keys each record by `hash('sha256', $id)` and {@see read()}/{@see destroy()} hash the id the caller presents before looking it up. A read of the file on disk then yields only digests, which open nothing: this is what the sibling stores already do (an API token and an invitation are kept as their sha256). A record carries no id field of its own; {@see read()} hydrates it with the raw id the caller passed, so the cookie keeps carrying the id and nothing downstream changes. One consequence, by design: a sessions file written by an older version — keyed by the raw id — is no longer found by its digest, so sessions open before an upgrade stop resolving and their owners sign in again (a one-time re-authentication, not a loss of any grant).

public function __construct(string $path, ?callable $clock = null):

Parameters

public function read(string $sessionId): ?Milpa\Auth\SessionRecord

The live session under this id, or null when none is stored, or it is expired or revoked (fail-closed).

Parameters

public function write(Milpa\Auth\SessionRecord $session): void

Persist a session on disk, keyed by a digest of its id, under an exclusive lock.

Parameters

public function destroy(string $sessionId): void

Remove the session under this id; a no-op when none is stored.

Parameters