Policy & Authorization¶

Cedar-based authorization checks on capability invocations.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

Decorator¶

Symbol	Signature	Description
`@policy`	`@policy(policy_ref: str)`	Attach Cedar policy metadata to a capability handler. Format: `"file.cedar::rule_name"` or `"file.cedar"`. Must be applied BELOW `@capability`

Symbol	Signature	Description
`evaluate_policies`	`evaluate_policies(policies: list[dict], context: PolicyContext) -> PolicyDecision`	Evaluate a list of Cedar-subset policies against a context. First applicable policy wins; default deny
`load_cedar_file`	`load_cedar_file(path: Path) -> list[dict]`	Read a `.cedar` file and return a list of parsed policy dicts

Symbol	Signature	Description
`PolicyContext`	`PolicyContext(principal: str, action: str, resource: dict = {}, environment: dict = {}, principal_attrs: dict = {})`	Frozen dataclass for Cedar policy evaluation context
`PolicyDecision`	`PolicyDecision.ALLOW \\| PolicyDecision.DENY`	Enum result of a policy evaluation

Symbol	Signature	Description
`register_principal_attrs`	`register_principal_attrs(principal: str, attrs: dict) -> None`	Register attributes (role, etc.) for a principal id
`get_principal_attrs`	`get_principal_attrs(principal: str) -> dict`	Return a copy of the registered attribute dict (or `{}`)
`clear_principal_attrs`	`clear_principal_attrs() -> None`	Wipe the registry (test helper)

Symbol	Signature	Description
`resource_from_subject`	`resource_from_subject(subject_iri: str, store, *, trace_id: str = "", extra: dict \\| None = None) -> dict`	Build the `resource` dict for a PolicyContext from a subject's strongest-available type