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).