Validates credentials and appends a real session for that user to the stack, making it the active account. The new account may be any role; the gate is enforced by the caller (controller) against the root account.

Returns {:error, :already_in_stack} if the user is already present.

Appends an already-authenticated (active) user to the session stack and makes them the active account. Shares all invariants with add_account/3:

• Stack-limit check (:stack_full)
• Dedup check — returns {:error, :already_in_stack} if the user is already present
• Session-fixation protection via renew_and_put_active_token/2

Used by the OAuth add-account callback so the same logic applies whether the user was authenticated via password or via OAuth.

event names the activity-feed action written on success. It exists so impersonate/2 can record what actually happened instead of a second row saying session.account_added — in the feed those two are the same sentence, and one of them is a user adding an account of their own.

Deletes every stack token from the DB (used by 'Log out all').

True when the root session belongs to ANY authenticated user AND the multi_session_enabled setting is on. Evaluated against the root so the switcher stays visible even when a secondary account is active.

Anonymous (no root token / no valid user) always returns false.

@spec impersonable?(
  PhoenixKit.Users.Auth.User.t() | nil,
  PhoenixKit.Users.Auth.User.t()
) :: boolean()

True when actor may borrow target's account.

Answers with the same rules impersonate/2 enforces — it calls the very same private predicate — so a menu built on this cannot offer an action the request would then refuse, and cannot hide one it would have allowed.

A deactivated target answers false. That refusal (:inactive) is raised by add_authenticated_user/2 rather than by the authority rules, so asking the rules alone would put the offer on every deactivated row in the admin list — where the status is displayed next to it — and every click would come back "That account is deactivated."

The remaining reasons impersonate/2 may still decline (the stack being full, or the target already sitting in it) depend on session state at request time, are recoverable, and report themselves through the controller's flash rather than by silently removing the option.

Target roles come from the :roles preload when the caller has one — the user detail page loads its user through get_user_with_roles/1 — and from a lookup otherwise.

@spec impersonable_uuids(PhoenixKit.Users.Auth.User.t() | nil, [
  PhoenixKit.Users.Auth.User.t()
]) ::
  MapSet.t()

The subset of users the actor may sign in as, as a MapSet of uuids.

impersonable?/2 reads roles from the database — three lookups per call, once the staff?/1 check is counted — which is fine for one user but is an N+1 per row in a list. This reads the actor's roles once and each target's from the :roles preload the caller already has, falling back to a lookup only for a row that arrives without one. Decisions come from the same private predicate impersonate/2 uses, so the two cannot diverge.

Deactivated rows are left out for the reason given on impersonable?/2.

assign(socket, :impersonable_uuids, MultiSession.impersonable_uuids(actor, users))

and in the template :if={user.uuid in @impersonable_uuids}.

@spec impersonate(Plug.Conn.t(), PhoenixKit.Users.Auth.User.t()) ::
  {:ok, Plug.Conn.t()}
  | {:error,
     :not_allowed
     | :target_is_owner
     | :target_is_staff
     | :stack_full
     | :already_in_stack
     | :inactive
     | :self}

Adds target to the session stack on an administrator's authority, without their password — "log in as this user".

Shares every invariant of add_authenticated_user/2 and adds the authority checks that separate support access from account takeover:

• the root account decides, never the active one. Otherwise an administrator could impersonate a user and, from inside that session, impersonate someone the user could never reach;
• the root must hold the Owner or Admin role. Deliberately not can_access_admin_area?/1: that is true for any permission holder, so a customer granted one self-service permission would qualify — and could then borrow another customer's account;
• an Owner is never a target. The one account that can undo anything must not be reachable by borrowing it;
• an Admin root cannot take another Admin either — support access is for the people being supported, not sideways between staff. An Owner root may, because there is nothing above it to escalate to.

A success is logged as session.impersonated — one row, written in place of the session.account_added the stack append would otherwise have written. A refusal is logged as session.impersonation_refused with the deciding rule in metadata["reason"]: an impersonation nobody can see afterwards is the thing that makes this feature dangerous, and a rejected attempt to borrow the owner's account is the entry whoever watches the feed most wants to find.

Refusal rows carry no target_uuid on purpose. Activity.log/1 fans a row with one out to that user's notification inbox, and a refused attempt is a signal for the feed, not a message to the person it named.

@spec impersonation_actor(map()) :: PhoenixKit.Users.Auth.User.t() | nil

The account an impersonation would be judged against — the session's ROOT, never the account currently active.

Returns nil when gate_allowed?/1 is false, which makes impersonable?/2 answer false for every target and takes the offer off the menu. That check belongs here rather than at the call sites: the controller opens with the same gate (with_gate), so without it a menu could offer impersonation while multi_session_enabled is off and the POST would bounce to the home page with "Multi-account switching is not available." The authority rules in authorize_impersonation/2 never see the setting, so asking them alone is not enough to predict the outcome.

Pair with impersonable?/2 to offer the action only where it would succeed. A LiveView can hold the result across a mount safely: it is a User struct, so nothing keeps a session token in the socket.

Resolves each stack token to a render struct: %{ref, user, email, role, active?, root?}. Tokens that no longer resolve to a user (expired/deleted) are dropped.

@spec log_impersonation_refusal(Plug.Conn.t(), String.t()) :: :ok

Records an impersonation attempt refused before a target was resolved, so the controller's authority-first ordering does not cost the feed an entry.

Logs out the active account. When a non-root account is active, deletes it and switches back to root ({:switched, conn, root_user}). When the root account is active, signals a full logout ({:full, conn}) for the caller to run.

Maximum number of accounts allowed in one stack.

@spec may_impersonate?(map()) :: boolean()

True when the session's ROOT account holds the authority impersonate/2 requires before it will look at a target at all.

Exposed so the controller can refuse an unauthorized actor before it resolves the uuid: resolving first answers "does this account exist?" with a distinct message, and this endpoint is reachable by every signed-in user, not only by staff. Shares staff?/1 with authorize_impersonation/2 so the two rules cannot drift apart.

Removes a non-root token from the stack and deletes it from the DB.

Returns the user's most descriptive display role name.

Priority: Owner > Admin > first custom (non-"User") role > "User". This correctly labels custom roles (e.g. "Manager", "Client") instead of bucketing all permission-holders as "Admin".

Use this for any "what is this account?" label. In particular do not derive one from Scope.can_access_admin_area?/1: that gate is true for Owner, Admin or any single permission holder, so a Client — who holds client_portal — reads back as "Admin".

Reads role names straight from User.get_roles/1 rather than building a full Scope — the scope carries an opaque MapSet of permissions we don't need here (and constructing it tripped a Dialyzer opaqueness warning).

@spec role_label_from_roles([String.t()]) :: String.t()

role_label/1 for callers that already hold the role names.

Auth.User.get_roles/1 queries, so a render path with the names in hand — Scope's cached_roles, loaded once at Scope.for_user/1 — should pass them here instead of handing over the user and paying for the lookup again.

Resolves the two transient Scope fields {multi_session_allowed?, multi_session_accounts} for a session in one call.

Crucially, the (DB-heavy) account stack is resolved ONLY when the setting is on. When multi_session_enabled is off — the default — this short-circuits to {false, []} without touching the DB, so the hot auth path (plug + every LiveView mount) pays nothing for a feature that is disabled.

When it IS on, allowed? is derived from the resolved stack (a surviving root account) rather than a separate gate_allowed?/1 call, which would re-resolve the root token in its own query on top of the list_accounts/1 walk.

The list of raw session tokens in the stack. Falls back to the single active token when no explicit stack is stored, and [] when there is no active token.

Activates a token already present in the stack, identified by ref.