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

Returns all built-in, sub-permission, and custom permission keys as a list. See enabled_module_keys/0 for filtered MapSet variant.

@spec auto_grant_new_keys_to_admin() :: :ok

Grants every known built-in permission key (core sections, feature-module keys, sub-permission keys) to the Admin system role, skipping keys that were auto-granted before (per-key settings flag) so an Owner's later revocation is never overridden. Custom keys go through the same mechanism at register_custom_key/2 time.

Called after module discovery. This is also the repair path for installs whose V53 seeding predates newer modules: the first boot after upgrade fills the Admin role's missing keys, after which revocations stick per-key. Idempotent; safe when the table doesn't exist yet.

@spec auto_grant_to_admin_roles(String.t()) :: :ok

Auto-grants a permission key to the Admin system role. Stores a flag in phoenix_kit_settings so that if Owner later revokes the key, it won't be re-granted on next application restart.

@spec cache_custom_view_permission(module(), String.t()) :: :ok

Caches a LiveView module → permission key mapping for custom admin tabs. Used by the auth system to enforce permissions on custom admin LiveViews without reading Application config on every mount.

@spec can_edit_role_permissions?(
  PhoenixKit.Users.Auth.Scope.t() | nil,
  PhoenixKit.Users.Role.t()
) ::
  :ok | {:error, atom()}

Checks if the given scope can edit the target role's permissions.

Returns :ok if allowed, or {:error, reason} if not.

Rules:

• Owner role cannot be edited (always has full access)
• Users cannot edit their own role (prevents self-lockout)
• Only Owner can edit Admin role (prevents privilege escalation)

@spec clear_custom_keys() :: :ok

Clears all custom permission keys. For test isolation.

@spec copy_permissions(
  integer() | String.t(),
  integer() | String.t(),
  integer() | String.t() | nil
) :: :ok | {:error, term()}

Copies all permissions from one role to another.

The target role will end up with the exact same set of permissions as the source role. Existing permissions on the target that don't exist on the source will be revoked.

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

Returns the 5 core section keys.

@spec count_permissions_for_role(integer() | String.t()) :: non_neg_integer()

Returns the number of permission keys granted to a role. More efficient than length(get_permissions_for_role(role_uuid)).

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

Returns the list of custom permission key strings.

@spec custom_keys_map() :: %{required(String.t()) => map()}

Returns the map of registered custom permission keys and their metadata.

@spec custom_view_permissions() :: %{required(module()) => String.t()}

Returns the cached custom view → permission mapping.

@spec diff_permissions(integer() | String.t(), integer() | String.t()) :: %{
  only_a: MapSet.t(),
  only_b: MapSet.t(),
  common: MapSet.t()
}

Compares permissions between two roles and returns a diff map.

Returns %{only_a: MapSet.t(), only_b: MapSet.t(), common: MapSet.t()} where only_a are keys role_a has but role_b doesn't, only_b is the inverse, and common are keys both roles share.

@spec enabled_module_keys() :: MapSet.t()

Returns module keys that are currently enabled (core sections + enabled feature modules + custom keys) as a MapSet for efficient membership checks. Core sections and custom keys are always included. Feature modules are included only if their module reports enabled status.

Returns MapSet.t() unlike all_module_keys/0 which returns a list — callers use this primarily for MapSet.member?/2 and MapSet.intersection/2 checks.

@spec expand_with_parents(Enumerable.t()) :: MapSet.t()

Expands a set of permission keys with the base keys its sub-permissions imply (a sub-permission is meaningless without module access). Used by the grant paths to keep the "no orphan sub-key" invariant, and by the admin UIs to compute the full set a grant would create before authorizing it.

@spec feature_enabled?(String.t()) :: boolean()

Checks whether a feature module is currently enabled.

Core section keys always return true. Feature module keys return the result of calling the module's enabled?/0 (or equivalent) function. Sub-permission keys are enabled iff their parent module is enabled. Custom permission keys are always enabled (no module toggle). Returns false for unknown keys.

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

Returns the feature module keys from the registry.

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

Returns the list of module_keys granted to a specific role.

@spec get_permissions_for_user(PhoenixKit.Users.Auth.User.t() | nil) :: [String.t()]

Returns the list of module_keys the given user has access to. Joins through role_assignments → role_permissions.

@spec get_permissions_matrix() :: %{required(String.t()) => MapSet.t()}

Returns a matrix of role_uuid → MapSet of granted keys for all roles.

@spec grant_all_permissions(integer() | String.t(), integer() | String.t() | nil) ::
  :ok | {:error, term()}

Grants all permission keys (built-in + custom) to a role.

@spec grant_permission(
  integer() | String.t(),
  String.t(),
  integer() | String.t() | nil
) ::
  {:ok, PhoenixKit.Users.RolePermission.t()}
  | {:error, Ecto.Changeset.t() | :role_not_found}

Grants a single permission to a role. Uses upsert to be idempotent.

Granting a sub-permission key ("calendar.view_others") also grants its base module key in the same transaction — a sub-permission row must never exist without module access, regardless of which code path grants it.

@spec module_description(String.t()) :: String.t()

Returns a short description for a module key (sub-permission keys resolve to the sub's own description).

@spec module_icon(String.t()) :: String.t()

Returns a Heroicon name for a module key (sub-permission keys inherit the parent module's icon).

@spec module_label(String.t()) :: String.t()

Returns a human-readable label for a module key (sub-permission keys resolve to the sub's own label).

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

Returns the base module key a composed sub-permission key belongs to, or nil when the key is not a registered sub-permission. Registry-driven — never inferred by string splitting.

@spec permissions_table_ready?() :: boolean()

Whether the permissions table is present (migrated), regardless of how many rows it holds.

This is the ONLY signal that unlocks the Admin full-access fallback: a genuinely unmigrated install (pre-V53, table missing) returns false, and scope treats that as "not yet seeded → grant Admin everything". Once the table exists, zero rows for an Admin means an Owner deliberately revoked them — no access — and that must stick; row COUNT must never re-open the fallback (the old any_permissions_exist? did, so stripping every role bare ironically restored full access).

Fails CLOSED: a transient/other query error returns true (table assumed present), so a DB blip de-privileges an Admin to their explicit rows rather than escalating them to full access.

@spec register_custom_key(
  String.t(),
  keyword()
) :: :ok

Registers a custom permission key with metadata.

Custom keys extend the built-in 25 permission keys, allowing parent apps to define new permission scopes for custom admin tabs. Custom keys are always treated as "enabled" (no module toggle) and appear in the permission matrix UI under "Custom".

Raises ArgumentError if the key collides with a built-in key or has an invalid format. Logs a warning on duplicate override.

Options

• :label - Human-readable label (default: capitalized key)
• :icon - Heroicon name (default: "hero-squares-2x2")
• :description - Short description (default: "")

Examples

Permissions.register_custom_key("analytics", label: "Analytics", icon: "hero-chart-bar")

@spec revoke_all_permissions(integer() | String.t()) :: :ok | {:error, term()}

Revokes all permissions from a role.

@spec revoke_permission(integer() | String.t(), String.t(), keyword()) ::
  :ok | {:error, :not_found | :unauthorized}

Revokes a single permission from a role.

Revoking a base module key also revokes all of its sub-permission keys in the same statement — a sub-permission row must never outlive module access. Revoking a sub-permission key removes only that key.

Pass authorized_keys: MapSet.t() to restrict the revoke to keys the caller is allowed to manage: the role's currently-held keys among the cascade are read inside the transaction under an advisory lock, and if any falls outside authorized_keys the whole revoke is rejected with :unauthorized. This closes the race where a caller's cached view misses a concurrently granted sub-key it doesn't hold. Omitted (or :all) skips the check — for system/internal callers.

@spec role_has_permission?(String.t(), String.t()) :: boolean()

Checks if a specific role has a specific permission.

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

Returns a list of role_ids that have been granted the given module_key.

@spec set_permissions(
  integer() | String.t(),
  [String.t()],
  integer() | String.t() | nil
) ::
  :ok | {:error, term()}

Syncs permissions for a role: grants missing keys, revokes extras. Runs in a transaction.

The desired set is normalized before applying: every sub-permission key in it pulls in its base module key (a sub-permission implies module access), so no code path can persist an orphan sub-key row.

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

Returns all composed sub-permission keys ("calendar.view_others") declared by registered modules.

@spec sub_permissions_for(String.t()) :: [map()]

Returns the sub-permission metadata declared under a base module key. Each entry is %{key: composed_key, label: label, description: description}.

@spec unregister_custom_key(String.t()) :: :ok

Unregisters a custom permission key. Stale DB rows are harmless.

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

Returns a list of user_ids that have access to the given module_key (through any of their assigned roles).

@spec valid_module_key?(String.t()) :: boolean()

Checks whether key is a known permission key (built-in, sub-permission, or custom).