The Permission Catalog

A catalog is code or config versioned with your application; the library never reads it from a database. It is validated when built and immutable afterwards.

In code

catalog = PermissionCatalog.from_mapping(
    scopes=[ScopeKind("studio"), ScopeKind("global", hide_existence=False)],
    permissions=[
        PermissionSpec("design.read", "studio"),
        PermissionSpec("design.write", "studio"),
        PermissionSpec("platform.admin", "global", sensitive=True),
    ],
    roles={
        "EDITOR": ["design.read", "design.write"],
        "READER": ["design.read"],
        "PLATFORM_ADMIN": ["platform.admin"],
    },
)

StrEnum members are accepted anywhere a name is expected. from_mapping raises one CatalogError listing all problems: duplicate permissions, an undeclared scope kind, a role granting an undeclared permission, empty or malformed names.

From TOML or JSON

PermissionCatalog.from_file(path) reads the same shape (.toml through the standard library tomllib, or .json):

[[scopes]]
name = "studio"
hide_existence = true

[[permissions]]
name = "design.write"
scope = "studio"
sensitive = false

[roles]
TIT = ["design.write"]

Scope kinds and hide_existence

Every permission belongs to exactly one scope kind, and a guard checks a permission only against a scope of that kind (ScopeKindMismatchError otherwise; Authz.validate_routes finds it at startup). hide_existence=True turns “no assignment” into not visible (404); False into denied (403).

sensitive=True is metadata for audit and UIs (sensitive permissions are logged at INFO even when allowed); it does not change enforcement.

Useful lookups: permissions_for(role), roles_granting(permission), spec(permission), to_mapping() (round-trips with from_mapping).