Appends a JWT audit insert step to the given Ecto.Multi.

Delegates to Sigra.Audit.log_multi_safe/3 (no-op when :audit_schema is nil).

For internal composition from Sigra.JWT.refresh/3 when :audit_schema is set. Host applications should not compose arbitrary multis unless they own the outer Repo.transaction/1.

@spec audit_jwt_refresh(Sigra.Config.t(), term()) :: :ok

Emit api.jwt_refresh audit row (called from Sigra.JWT refresh flow).

When :audit_schema is configured, the row is written inside Repo.transaction/1 via audit-only Ecto.Multi + Audit.log_multi_safe/3 (same durability posture as verify-failure auditing).

Returns :ok even when auditing is disabled or when the audit insert is rejected or rolled back after the host transaction has already committed elsewhere. :ok does not prove the audit row exists; monitor [:sigra, :audit, :log_safe_error] for reason: :invalid_changeset or :constraint_violation.

This is exposed so the JWT refresh implementation (potentially a separate module) can write a consistent audit row through this module's helpers.

@spec audit_jwt_refresh_reuse(Sigra.Config.t(), term()) :: :ok

Emit api.jwt_refresh_reuse audit row (detected refresh-token reuse).

When :audit_schema is configured, uses the same transactional Multi + log_multi_safe path as audit_jwt_refresh/2.

Returns :ok regardless of whether a durable audit row was persisted; see audit_jwt_refresh/2 and [:sigra, :audit, :log_safe_error] for operational honesty.

@spec can?(map(), [String.t()], keyword()) :: boolean()

Checks whether a token or scope struct has the required scopes.

Accepts either a map with :scopes (token struct) or :token_scopes (scope struct from conn.assigns).

Options

• :match - :all (default) requires all scopes, :any requires at least one

Examples

Sigra.APIToken.can?(token, ["profile:read"])
#=> true

Sigra.APIToken.can?(token, ["admin:write"], match: :any)
#=> false

@spec create(Sigra.Config.t(), map(), map()) ::
  {:ok, String.t(), map()} | {:error, term()}

Creates a new API token for the given user.

Returns {:ok, raw_key, token_record} on success. The raw_key includes the configured prefix and should be shown to the user exactly once.

Parameters

• config - A %Sigra.Config{} struct
• user - The user struct (must have an :id field)
• attrs - A map with:
  • :name (required) - Human-readable token name, max 255 chars
  • :scopes (required) - List of scope strings
  • :expires_at (optional) - Expiration datetime

Examples

{:ok, raw_key, token} = Sigra.APIToken.create(config, user, %{
  name: "CI Deploy Key",
  scopes: ["profile:read", "api_tokens:read"]
})

@spec decode_cursor(String.t()) :: {DateTime.t(), integer()}

Decodes an opaque cursor string into {inserted_at, id}.

@spec encode_cursor(DateTime.t(), term()) :: String.t()

Encodes an inserted_at timestamp and ID into an opaque cursor string.

@spec list_active(Sigra.Config.t(), term(), keyword()) :: {[map()], String.t() | nil}

Lists active (non-revoked, non-expired) API tokens for a user with cursor pagination.

Returns {tokens, next_cursor} where next_cursor is nil on the last page.

Options

• :limit - Page size (default from config, max from config)
• :cursor - Opaque cursor string from a previous call

Examples

{tokens, cursor} = Sigra.APIToken.list_active(config, user_id)
{more_tokens, nil} = Sigra.APIToken.list_active(config, user_id, cursor: cursor)

@spec list_scopes(Sigra.Config.t()) :: [String.t()]

Returns all registered scopes (built-in + custom).

Delegates to Sigra.APIToken.ScopeRegistry.all_scopes/1.

Examples

scopes = Sigra.APIToken.list_scopes(config)
#=> ["profile:read", "profile:write", ...]

@spec revoke(Sigra.Config.t(), term()) ::
  {:ok, map()} | {:error, :not_found} | {:error, Ecto.Changeset.t()}

Revokes a single API token by ID.

Sets revoked_at to the current UTC time. Returns {:ok, token} on success or {:error, :not_found} if the token does not exist.

Examples

{:ok, revoked_token} = Sigra.APIToken.revoke(config, token_id)

@spec revoke_all(Sigra.Config.t(), map()) :: {:ok, non_neg_integer()}

Revokes all active API tokens for a user.

Sets revoked_at on all tokens where revoked_at IS NULL for the given user. Returns {:ok, count} with the number of tokens revoked.

Examples

{:ok, 3} = Sigra.APIToken.revoke_all(config, user)

@spec verify(Sigra.Config.t(), String.t()) ::
  {:ok, map()} | {:error, :invalid_token | :token_revoked | :token_expired}

Verifies a raw API token string.

Hashes the token and looks up the hash in the database. Returns {:ok, token} for valid active tokens, or an error tuple.

Error Returns

• {:error, :invalid_token} - Token not found
• {:error, :token_revoked} - Token has been revoked
• {:error, :token_expired} - Token has expired

Examples

case Sigra.APIToken.verify(config, raw_token) do
  {:ok, token} -> # authenticated
  {:error, reason} -> # rejected
end