# `Ithibati.Identity.Sessions`
[🔗](https://github.com/oliverandrich/ithibati/blob/v0.6.2/lib/ithibati/identity/sessions.ex#L1)

Issues, looks up and revokes server-side sessions.

`generate_session_token/1` returns a plaintext token while storage keeps its SHA-256 digest.
`get_user_by_session_token/1` returns the account only while that session remains valid.
`delete_session_token/1` revokes one token; `revoke_all/1` revokes an account's sessions.
`delete_expired/0` removes expired rows.

`Ithibati.Web.Gate` connects these calls to a browser session and LiveView sockets. Direct calls
here do not update cookies or broadcast socket disconnections. API tokens with scopes or
rotation are separate application concerns.

# `delete_expired`

Deletes expired sessions across all accounts and returns the number of deleted rows.

Uses the same `session_validity` setting as lookup, measured from creation. Invalid validity
raises `ArgumentError` before deletion. Applications choose when to run this maintenance;
Ithibati starts no scheduler. Cleanup does not broadcast LiveView disconnections.

# `delete_session_token`

Revokes one token and returns `:ok`, including for `nil` or an unknown token.

# `generate_session_token`

Stores a new session and returns its plaintext, URL-safe token.

The account must belong to the configured schema and exist in the database. The row stores
only a digest, so retain the returned token for the client. Invalid session validity raises
`ArgumentError`; an invalid insert raises `Ecto.InvalidChangesetError`.

This call does not revoke other sessions or update a browser cookie.

# `get_user_by_session_token`

Returns the account for a valid session token, or `nil`.

Unknown, revoked and expired tokens all return `nil`. A `nil` input also returns `nil` without
reading configuration or querying the database.

Validity is measured from session creation using `config :ithibati, session_validity:` and
defaults to `{60, :day}`. Lookup does not extend a session. Invalid validity settings raise
`ArgumentError` when looking up a string token.

# `revoke_all`

Revokes an account's sessions and returns their stored token digests, in no particular order.

Includes expired sessions. The account must belong to the configured schema. An account with
no sessions returns `[]`. This does not disable the account: concurrently created sessions may
survive, and the account can sign in again.

Selection and deletion share a transaction with row locks or SQLite's writer reservation.
Only digests of sessions deleted by this call are returned. Inside a caller's transaction,
revocation commits or rolls back with that transaction; defer external notifications until
it commits. Database errors propagate without retries. MySQL requires READ COMMITTED,
as for other identity transactions.

This call does not broadcast disconnections. For browser logout, use
`Ithibati.Web.Gate.log_out_all/1`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*