Module policy_annotations 

Policy annotation parser for Cedar policies.

This module parses rustdoc-style annotations from Cedar policy comments to extract metadata for UI display and policy management.

Annotation Format

/// @title Allow Write Operations
/// @description Permits adding and updating states in the policy database.
/// These operations are considered safe for automated execution.
/// @category write
/// @risk medium
/// @editable true
permit(
  principal,
  action == Action::"executeMutation",
  resource
) when {
  resource.mutation in ["addState", "updateState"]
};

Supported Annotations

Annotation	Required	Description
@title	Yes	Short display name for the policy
@description	Yes	Multi-line description (continuation lines without @)
@category	Yes	One of: read, write, delete, fields, admin
@risk	Yes	One of: low, medium, high, critical
@editable	No	Whether admins can modify (default: true)
@reason	No	Why the policy exists or is non-editable
@author	No	Who created or last modified
@modified	No	ISO date of last modification

Category Mapping

The unified categories work across all server types:

• read: Queries (GraphQL), GET (OpenAPI), SELECT (SQL)
• write: Create/update mutations, POST/PUT/PATCH, INSERT/UPDATE
• delete: Delete mutations, DELETE, DELETE/TRUNCATE
• admin: Introspection, schema access, DDL
• fields: Field-level access control

Legacy category names are still supported for parsing: queries → read, mutations → write, introspection → admin.

Structs

PolicyMetadata

Parsed policy metadata from Cedar doc comments.

Enums

PolicyCategory

Unified policy category for grouping in the UI. Works consistently across GraphQL, OpenAPI, and SQL servers.

PolicyRiskLevel

Risk level for visual indication in the UI.

PolicyValidationError

Validation error for policy annotations.

Functions

generate_policy_cedar

Generate Cedar policy text with annotations from metadata.

infer_category_and_risk_from_cedar

Infer category and risk from Cedar policy content when annotations are missing.

parse_policy_annotations

Parse Cedar policy annotations from doc comments.