@spec active?(PhoenixKit.API.Keys.Key.t()) :: boolean()

Token-less check that a key may be used now: the key is neither revoked nor expired (dead_reason/1 is nil) and its owner is an active user (Auth.get_user/1 |> Auth.ensure_active_user/1, the same lookup verify/2 uses). A caller that needs the reason, or the key's effective scopes, uses Confirm.live_actor/1. The owner is read only when the row itself is alive.

@spec active_owner(PhoenixKit.API.Keys.Key.t()) ::
  {:ok, PhoenixKit.Users.Auth.User.t()}
  | {:error, :owner_inactive | :personal_keys_not_allowed}

The active owner of a key, {:error, :owner_inactive} when the user is gone, blocked or not confirmed, and {:error, :personal_keys_not_allowed} for a personal key whose owner holds neither api_personal_keys nor api right now. Behind active?/1 and Confirm.live_actor/1. verify/2 goes through the same private check (checked_owner/1), so the two cannot disagree.

@spec actor(
  PhoenixKit.API.Keys.Key.t(),
  PhoenixKit.Users.Auth.User.t(),
  String.t() | nil
) ::
  PhoenixKit.API.Actor.t()

The Actor of key held by its (already loaded, active) owner, with the effective scopes (none for a personal key whose owner lacks the permission). It and verify/2 share one private builder, so a field added to the actor reaches the request path and an approved operation (Confirm.live_actor/1) alike.

@spec allowed_scopes_for(PhoenixKit.Users.Auth.User.t()) :: [String.t()]

Every scope the owner could be given: a scope of the enabled admin tools, provided the owner holds the permission of every one of those tools that declares it.

@spec allowed_scopes_for(
  PhoenixKit.Users.Auth.User.t(),
  PhoenixKit.Users.Auth.Scope.t()
) :: [
  String.t()
]

The scopes editor_scope may hand to owner's keys: allowed_scopes_for/1 of the owner, narrowed to the scopes whose tool permissions the editor holds too. Editing one's own keys needs no narrowing (the owner is the editor).

@spec can_manage?(PhoenixKit.Users.Auth.Scope.t(), PhoenixKit.API.Keys.Key.t()) ::
  boolean()

Whether the person behind scope may revoke, rotate or edit the scopes of key: they hold api and are an Owner or created the key. A personal key is managed by its owner alone, while they hold api_personal_keys or api (an Owner included: see can_revoke?/2).

@spec can_revoke?(PhoenixKit.Users.Auth.Scope.t(), PhoenixKit.API.Keys.Key.t()) ::
  boolean()

Whether the person behind scope may revoke key: can_manage?/2, and an Owner for anyone's personal key too (revoking hands out no token). Callers of revoke/2 check this first.

@spec create_key(
  PhoenixKit.Users.Auth.User.t(),
  PhoenixKit.Users.Auth.Scope.t(),
  map(),
  keyword()
) ::
  {:ok, PhoenixKit.API.Keys.Key.t(), String.t()}
  | {:error, Ecto.Changeset.t() | atom()}

Creates a key for owner on behalf of the person behind creator_scope.

attrs takes name (required), scopes, requires_approval, allowed_ips (CIDR blocks or bare addresses; stored in canonical form) and expires_at, with atom or string keys (not mixed).

Returns the stored key and the token, which exists nowhere else and is never shown again.

opts[:impersonated]: a caller that knows the session is borrowed (PhoenixKitWeb.Users.MultiSession.impersonated?/1) passes true and gets {:error, :impersonated} — no token is minted in the name of an account someone acts in. Omitted, nothing is assumed (a mix task, a seed, a test).

@spec create_personal_key(PhoenixKit.Users.Auth.Scope.t() | nil, map(), keyword()) ::
  {:ok, PhoenixKit.API.Keys.Key.t(), String.t()}
  | {:error, Ecto.Changeset.t() | atom()}

Creates a personal key for the person behind creator_scope, who is also its owner (see "Personal keys" in the moduledoc).

creator_scope should be the person's full scope read again for this event (PhoenixKit.API.Access.fresh_scope/2); the person is read again here as well and must hold api_personal_keys or api in both. attrs takes name (required), scopes, allowed_ips and expires_at (required, at most PersonalKeysConfig.latest_expiry/0), as create_key/3; requires_approval: true is a changeset error, not dropped.

opts must say impersonated: true | false (no default): a missing or non-boolean value is {:error, :impersonation_unknown}, true is {:error, :impersonated}. Other failures: :forbidden (neither permission), :owner_inactive, :owner_not_allowed (a service user), :invalid_scopes, :personal_key_limit (the person already has PersonalKeysConfig.max_count/0 live personal keys), or a changeset.

@spec dead_reason(PhoenixKit.API.Keys.Key.t()) :: :revoked | :expired | nil

Why a key row cannot be used now: :revoked (revoked_at has been reached), :expired (expires_at has been reached), or nil. A time in the future has not been reached: a revocation in the future is a scheduled one (the grace period of a rotation) and the key still works until then. When both have been reached the answer is :revoked.

@spec effective_scopes(PhoenixKit.API.Keys.Key.t() | PhoenixKit.API.Actor.t()) :: [
  String.t()
]

The scopes of a key (or of an Actor) that its owner may use right now.

Empty when the owner is blocked or deleted, and for a personal key (or the actor of one) whose owner holds neither api_personal_keys nor api. For code that holds a Key row or an old Actor (the Settings page, tests). A request does not need it: the Actor returned by verify/2 already carries these scopes and the Executor trusts them.

@spec get_key(String.t()) :: PhoenixKit.API.Keys.Key.t() | nil

Fetches a key by uuid; nil for an unknown or malformed uuid.

@spec held_scopes_of(PhoenixKit.Users.Auth.Scope.t()) :: [String.t()]

The scopes scope holds: those of the enabled admin tools, provided scope holds the permission of every one of those tools that declares it (the rule of allowed_scopes_for/1), sorted.

allowed_scopes_for/1 asks it of the owner's full scope (narrow: false); a caller acting through a live session (PhoenixKit.API.Executor.execute_as/5) asks it of the session's scope, which is narrowed to the session's active role.

@spec list_keys(PhoenixKit.Users.Auth.Scope.t()) :: [PhoenixKit.API.Keys.Key.t()]

The keys the person behind scope may see: all of them for an Owner, the keys they created themselves for any other holder of api, none otherwise. Newest first.

@spec list_personal_keys(PhoenixKit.Users.Auth.Scope.t() | nil) :: [
  PhoenixKit.API.Keys.Key.t()
]

The personal keys of the person behind scope (personal = true and owned by them), newest first; [] unless they hold api_personal_keys or api. An Owner sees only their own here (list_keys/1 lists everyone's).

@spec personal_keys_full?(PhoenixKit.Users.Auth.Scope.t() | nil) :: boolean()

Whether the person behind scope already has PersonalKeysConfig.max_count/0 live personal keys (a key in a grace period included): then a new key, and a rotation with a grace period, are refused with :personal_key_limit. For the pages, which offer a grace period of 0 in that case; the decision itself is made again under the lock.

@spec revoke(PhoenixKit.API.Keys.Key.t(), String.t() | nil) ::
  {:ok, PhoenixKit.API.Keys.Key.t()} | {:error, term()}

Revokes a key now. Revoking a key that is already revoked changes nothing. The row is read again, so a stale struct neither overwrites an earlier revocation nor fails; a key that no longer exists is {:error, :not_found}.

Unlike rotate/3 and update_scopes/3, which take the person's scope and authorize it, this takes a bare actor_uuid (only for the activity entry) and checks nothing: the CALLER must authorize with can_revoke?/2 first (the Settings page does, on the key it found through list_keys/1; "My API keys" on one it found through list_personal_keys/1).

@spec rotate(
  PhoenixKit.API.Keys.Key.t(),
  0..24,
  PhoenixKit.Users.Auth.Scope.t(),
  keyword()
) ::
  {:ok, PhoenixKit.API.Keys.Key.t(), String.t()} | {:error, term()}

Issues a new key with the same owner, scopes, flags, IP list and expiry, and retires the old one after grace_hours (0 to 24; 0 revokes it now).

A personal key is rotated by its owner only (can_manage?/2), with opts[:impersonated] given and false (:impersonation_unknown / :impersonated, as in create_personal_key/3; rotate/3 passes no opts, so it refuses a personal key). Any other key is refused with :impersonated when opts[:impersonated] is true (the new token would act as the borrowed account); omitted, nothing is assumed. The new key stays personal, never needs approval and expires at PersonalKeysConfig.latest_expiry/0, not at the old key's expiry.

A rotation of a personal key takes the same per-person advisory lock as a creation, before the row lock. With a grace period (grace_hours > 0) the old key stays alive next to the new one, so it is refused with {:error, :personal_key_limit} while the person already has PersonalKeysConfig.max_count/0 live personal keys (a key in a grace period included), checked under that lock. Without one (0) the swap is one for one and always allowed.

The old key keeps working until then, so a client can switch over without downtime. The creator must be able to manage the key (can_manage?/2) and, when the owner is a service user, still hold every permission the service user holds ({:error, :owner_not_allowed}, as in create_key/3). Returns the new key and its token.

The row is locked and read again first. A key that is gone is {:error, :not_found}, one that is revoked or expired :revoked / :expired (also through a stale struct), and one whose retirement is already scheduled :rotation_pending.

@spec token_prefix(String.t()) :: String.t() | nil

The prefix of a token ("pk_<prefix>_<secret>" gives prefix), or nil. Safe to log: the prefix is not secret.

@spec update_scopes(
  PhoenixKit.API.Keys.Key.t(),
  [String.t()],
  PhoenixKit.Users.Auth.Scope.t()
) ::
  {:ok, PhoenixKit.API.Keys.Key.t()}
  | {:error,
     :forbidden
     | :invalid_scopes
     | :scopes_not_narrowing
     | :revoked
     | :not_found}

Replaces the scopes of a live key.

• editor_scope must be able to manage the key (can_manage?/2), else {:error, :forbidden}; an Owner who may not manage someone else's personal key may still remove scopes from it: every scope of new_scopes must already be on the stored row, else {:error, :scopes_not_narrowing} (no token changes hands, and the key can only lose rights). In that case the saved list is exactly new_scopes: inactive scopes are not kept (the rule below does not apply), so any scope can go;
• the key is re-read: gone gives {:error, :not_found}, revoked (even if the struct passed in is stale) {:error, :revoked};
• new_scopes is the desired list of active scopes: a list of strings, and every scope that is not on the key yet must be in allowed_scopes_for/1 of the key's owner and, unless the editor is the owner, in allowed_scopes_for/2 (the editor holds the permissions of its tools too), else {:error, :invalid_scopes}. Blank entries and duplicates are dropped; an empty list is allowed;
• scopes already on the key that the owner cannot use right now are kept untouched: their module is switched off, their tool is hidden, the owner lost the permission, or the owner is blocked or deleted (then every scope is inactive and saving [] changes nothing). Saving never drops them, whether or not new_scopes names them. A named inactive scope keeps the position requested for it; the others are appended after the requested scopes. An inactive scope cannot be removed while it is inactive: only revoke/2 removes it (rotate/3 copies it). It grants nothing meanwhile (effective_scopes/1) and works again once the owner can use it.

On success the cached row is dropped on every node and a permanent api.key_scopes_updated entry (from / to) is written. Saving the scopes the key already has, in any order, changes and logs nothing.

@spec verify(term(), String.t() | nil) ::
  {:ok, PhoenixKit.API.Actor.t()}
  | {:error,
     :invalid_token
     | :revoked
     | :expired
     | :ip_not_allowed
     | :owner_inactive
     | :personal_keys_not_allowed}

Verifies a bearer token presented from ip.

Checks, in order: the token's shape and secret, revocation, expiry, the IP allow-list, that the owner exists and is active, and, for a personal key, that the owner holds api_personal_keys or api (:personal_keys_not_allowed; the API answers the same 401 for every reason). On success returns an Actor whose scopes are the key's effective scopes for this request.

Never raises on bad input, whatever its type (a missing header arrives as nil); a malformed token is :invalid_token, the same answer as an unknown key, so the response does not tell the two apart.

The returned Actor already carries the effective scopes of this request (the key's scopes filtered by the owner's live permissions and by the tools that are enabled right now), and verify/2 itself writes last_used_at / last_used_ip. The Executor therefore trusts actor.scopes and does not call effective_scopes/1 again for the same request: the owner lookup, the Scope.for_user/2 build and the tool-registry scan happen once, here.