Ithibati.Web.Gate (Ithibati v0.6.2)

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.

Summary

Functions

live_socket_id(token)

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

log_in(conn, account)

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

log_out(conn)

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

log_out_all(conn)

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

on_mount(mode, params, session, socket)

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

session_key()

The session key Ithibati stores its token under.

Functions

live_socket_id(token)

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(conn, account)

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(conn)

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(conn)

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(mode, params, session, socket)

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.