# `PhoenixKit.Users.Permissions`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.164/lib/phoenix_kit/users/permissions.ex#L1)

Context for module-level permissions in PhoenixKit.

Controls which roles can access which admin sections and feature modules.
Uses an allowlist model: row present = granted, absent = denied.
Owner role always has full access (enforced in code, no DB rows needed).

## Permission Keys

Core sections: dashboard, users, media, settings, modules
Feature modules: billing, shop, emails, entities, tickets, posts, comments,
  ai, publishing, referrals, sitemap, seo, maintenance, storage,
  languages, connections, legal, db, jobs

## Constants & Metadata

    Permissions.all_module_keys()        # 25 built-in + any custom keys
    Permissions.core_section_keys()      # 5 core keys
    Permissions.feature_module_keys()    # 20 feature keys
    Permissions.enabled_module_keys()    # Core + enabled features + custom keys
    Permissions.valid_module_key?("ai")  # true
    Permissions.feature_enabled?("ai")   # true/false based on module status
    Permissions.module_label("shop")     # "E-Commerce"
    Permissions.module_icon("shop")      # "hero-shopping-cart"
    Permissions.module_description("shop") # "Product catalog, orders, ..."

## Query API

    Permissions.get_permissions_for_user(user)          # User's keys via roles
    Permissions.get_permissions_for_role(role_uuid)      # Keys for a role
    Permissions.role_has_permission?(role_uuid, "billing") # Single check
    Permissions.get_permissions_matrix()                 # All roles → MapSet
    Permissions.roles_with_permission("billing")         # Role UUIDs with key
    Permissions.users_with_permission("billing")         # User UUIDs with key
    Permissions.count_permissions_for_role(role_uuid)    # Efficient count
    Permissions.diff_permissions(role_a, role_b)        # Compare two roles

## Mutation API

    Permissions.grant_permission(role_uuid, "billing", granted_by_uuid)
    Permissions.revoke_permission(role_uuid, "billing")
    Permissions.set_permissions(role_uuid, ["dashboard", "users"], granted_by_uuid)
    Permissions.grant_all_permissions(role_uuid, granted_by_uuid)
    Permissions.revoke_all_permissions(role_uuid)
    Permissions.copy_permissions(source_role_uuid, target_role_uuid, granted_by_uuid)

## Custom Keys API

Parent apps can register custom permission keys for custom admin tabs:

    Permissions.register_custom_key("analytics", label: "Analytics", icon: "hero-chart-bar")
    Permissions.unregister_custom_key("analytics")
    Permissions.custom_keys()              # List of registered custom key strings
    Permissions.custom_view_permissions()   # %{ViewModule => "key"} mapping

Custom keys are always treated as "enabled" (no module toggle) and appear
in the permission matrix UI under a "Custom" group.

## Edit Protection

    Permissions.can_edit_role_permissions?(scope, role) :: :ok | {:error, String.t()}

Enforces: users cannot edit their own role, only Owner can edit Admin,
system roles cannot have `is_system_role` changed.

# `all_module_keys`

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

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

# `auto_grant_to_admin_roles`

```elixir
@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.

# `cache_custom_view_permission`

```elixir
@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.

# `can_edit_role_permissions?`

```elixir
@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)

# `clear_custom_keys`

```elixir
@spec clear_custom_keys() :: :ok
```

Clears all custom permission keys. For test isolation.

# `copy_permissions`

```elixir
@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.

# `core_section_keys`

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

Returns the 5 core section keys.

# `count_permissions_for_role`

```elixir
@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))`.

# `custom_keys`

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

Returns the list of custom permission key strings.

# `custom_keys_map`

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

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

# `custom_view_permissions`

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

Returns the cached custom view → permission mapping.

# `diff_permissions`

```elixir
@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.

# `enabled_module_keys`

```elixir
@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.

# `feature_enabled?`

```elixir
@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.
Custom permission keys are always enabled (no module toggle).
Returns `false` for unknown keys.

# `feature_module_keys`

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

Returns the feature module keys from the registry.

# `get_permissions_for_role`

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

Returns the list of module_keys granted to a specific role.

# `get_permissions_for_user`

```elixir
@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.

# `get_permissions_matrix`

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

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

# `grant_all_permissions`

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

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

# `grant_permission`

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

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

# `module_description`

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

Returns a short description for a module key.

# `module_icon`

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

Returns a Heroicon name for a module key.

# `module_label`

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

Returns a human-readable label for a module key.

# `register_custom_key`

```elixir
@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")

# `revoke_all_permissions`

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

Revokes all permissions from a role.

# `revoke_permission`

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

Revokes a single permission from a role.

# `role_has_permission?`

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

Checks if a specific role has a specific permission.

# `roles_with_permission`

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

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

# `set_permissions`

```elixir
@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.

# `unregister_custom_key`

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

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

# `users_with_permission`

```elixir
@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).

# `valid_module_key?`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*