# `Ithibati.Web.Gate`
[🔗](https://github.com/oliverandrich/ithibati/blob/v0.6.2/lib/ithibati/web/gate.ex#L3)

Loads the current account from a session and optionally requires authentication.

Use it as a plug after `fetch_session`, and as an `on_mount` hook for LiveViews:

    pipeline :browser do
      plug :fetch_session
      plug Ithibati.Web.Gate, :current_account
    end

    live_session :members,
      on_mount: [{Ithibati.Web.Gate, {:require_account, to: "/sign-in"}}] do
      live "/inside", InsideLive
    end

Both forms assign `:current_account` to the account or `nil`.

  * `:current_account` always continues.
  * `:require_account` refuses unauthenticated access. The plug redirects when given `to:`
    and otherwise sends `401`. The LiveView hook requires `to:` and redirects there.

Unknown modes and options raise `ArgumentError`. The gate reads session tokens only;
application permissions and bearer-token authentication remain application concerns.

# `live_socket_id`

Returns the LiveView disconnect topic derived from a plaintext session token.

The topic contains a URL-safe encoding of the token's digest, so it does not expose the
plaintext token to PubSub subscribers or logs. It identifies one session, not every session
belonging to an account.

Use this when implementing a separate revocation path that holds the plaintext token and
needs to broadcast `"disconnect"`. Do not pass the digest stored in the database; it would
be hashed again and produce a different topic.

# `log_in`

Creates a session token, renews and clears the browser session, and returns the connection.

`account` must belong to the configured account schema and exist in the database. The new
token is stored under `session_key/0`. Existing session contents are cleared; retain anything
the next page needs only after this call.

When the connection's endpoint has a PubSub server, the session also receives the
`live_socket_id` used to disconnect this session's LiveViews on logout.

Complete sign-in with a full page load to refresh the CSRF token. The shipped browser hook
does this for a JSON response containing `%{redirect: path}`.

This call does not revoke the account's other session rows.

# `log_out`

Revokes the current session token, renews and clears the browser session, and returns the connection.

When the session has a live-socket topic and the endpoint has a PubSub server, this also
broadcasts `"disconnect"` to that topic. LiveView sockets must receive session information
through `connect_info` to subscribe to it. Without that setup, revocation affects subsequent
session lookups but does not disconnect existing sockets.

A missing token is harmless. Other sessions belonging to the account are unaffected.

# `log_out_all`

Revokes all sessions of the currently authenticated account and clears the browser session.

Resolves the account from the current token, not from connection assigns. Missing, unknown
or expired tokens only clear this browser's session. With endpoint PubSub configured,
broadcasts `"disconnect"` to every revoked session's LiveView topic after the database commits.
Sockets must receive the session through `connect_info`, as for `log_out/1`.

Call outside a database transaction; an outer transaction raises `ArgumentError` before any
revocation so notifications cannot precede commit. Database errors propagate without retries.
PubSub delivery is not atomic with the database commit: a delivery failure does not restore
revoked sessions. Accounts may sign in again, and concurrent new sessions may survive.

# `on_mount`

Loads `:current_account` during a LiveView mount and enforces the selected mode.

Returns `{:cont, socket}` in `:current_account` mode and for authenticated mounts in
`:require_account` mode. An unauthenticated required mount returns `{:halt, socket}` with a
redirect to the required `:to` path.

A missing `:to`, unknown mode or unknown option raises `ArgumentError`. Account assignment
uses `assign_new/3` so an account already loaded by the plug or parent LiveView can be reused.

# `session_key`

The session key Ithibati stores its token under.

---

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