RFC-0042 · Reference catalog
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Generated reference catalog. This page renders structured Lean data for RFC-0042: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0042.This page is generated from the
lean/Gnomon/Spec/module for RFC-0042. Edit that source and regenerate this catalog.
Title: Predicate Policy and Authorization
Status: draft
Owners: Graph Platform, Security
Diagnostic range: M42000-M42099
Depends on: RFC-0001, RFC-0006, RFC-0007, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040
Extended by: RFC-0043, RFC-0048
Proof citations in source: 13 / 13. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Match mode | How the policy’s predicate field is matched against statement predicates: subtree (ltree <@) or exact (=). |
| Permission level | One of read, write, admin, owner (RFC-0036 §5). Hierarchical bitmask. |
| Predicate policy | A rule of the form: presence of a statement (subject, predicate, resource) grants permissionLevel to subject on resource. |
| Preset | A named handle (app.read, teams.member.read) that lets operations reference a policy by name. |
| Priority | An integer 0–100 that breaks ties when multiple policies match the same (subject, resource) pair. |
| Resource | The target Resource being accessed; the RHS. |
| Scope | Optional narrowing: resourceKind filters by Resource kind; resourceId filters to a single Resource. |
| Subject | The Resource (typically a user or service principal) on the LHS of an authorization relationship. |
| when expression | An optional policy expression evaluated at decision time; the policy only applies when the expression is true. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M42010 | Error | resourceId declared without resourceKind — scope is invalid |
M42011 | Error | priority outside the legal 0..100 range |
M42012 | Error | permissionLevel is not one of read, write, admin, owner |
M42013 | Error | matchMode is not one of exact, subtree |
M42020 | Error | predicate references a path that is not declared by any installed module (orphan predicate reference) |
M42021 | Warning | predicate is declared but no statements use it; policy is dormant |
M42030 | Error | Permission cache used for write-side authorization decision; defect — re-evaluation required |
M42031 | Warning | Permission cache invalidation skipped a transitively-affected entry; cache may be stale until next refresh |
M42040 | Error | Preset name collision: two predicate policies declare the same preset name |
M42041 | Warning | Preset declared but never referenced by any operation |
M42050 | Error | when expression failed to evaluate (parse error, undefined reference, type mismatch) |
M42051 | Warning | when expression has high evaluation cost; consider memoization or simpler form |
M42060 | Error | sameAs value is not a syntactically-valid CURIE or URI |
M42070 | Error | Subtree match attempted on a backend without ltree support and no fallback path index configured |
Dependency neighborhood
graph LR
nRFC_0042["RFC-0042"]
nRFC_0001["RFC-0001"]
nRFC_0042 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0042 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0042 --> nRFC_0007
nRFC_0036["RFC-0036"]
nRFC_0042 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0042 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0042 --> nRFC_0038
nRFC_0039["RFC-0039"]
nRFC_0042 --> nRFC_0039
nRFC_0040["RFC-0040"]
nRFC_0042 --> nRFC_0040
nRFC_0043["RFC-0043"]
nRFC_0043 --> nRFC_0042
nRFC_0048["RFC-0048"]
nRFC_0048 --> nRFC_0042
Invariants
- A predicate policy with resourceId but no resourceKind MUST be rejected with M42010. (enforced by: install-time)
- Every predicate policy MUST declare both predicate and permissionLevel. (enforced by: install-time)
- Permission accumulation across matching policies is set-union with no deny rule; absence of grant is denial. (enforced by: runtime)
- Preset names MUST be unique within a runtime; collisions are M42040. (enforced by: install-time)
- Subtree matching is the default match mode and backends without ltree MUST simulate it via prefix index. (enforced by: runtime)
- The permission cache MUST be invalidated on statement create, validTo set, policy change, or subject/resource soft-delete. (enforced by: runtime)
- The sameAs alignment is informational and MUST NOT influence runtime evaluation. (enforced by: runtime)
- The templates permissions: shorthand expands deterministically to predicate_policy objects with documented default priorities. (enforced by: compile-time)
- When-expression results MUST be memoized within a single request and MUST NOT be cached across requests. (enforced by: runtime)
- Write-side authorization decisions MUST re-evaluate inside the write transaction; cache reads alone are M42030. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Authorization on API Surfaces
- MUST — If requiresAuth is true, the request must be authenticated (proof citation:
rfc0042_b3_grounded; verification pending) - MUST — The principal must have all named requiresPermissions (proof citation:
rfc0042_b25_grounded; verification pending) - MUST — The principal must have at least one of the declared requiresRoles (proof citation:
rfc0042_b21_grounded; verification pending)
Compatibility and Migration
- RECOMMENDED — Migration of legacy ResourcePolicy/StatementPolicy to predicate-policy form is recommended but not required
Invariants
- MUST — Permission cache must be invalidated on any of the four trigger conditions (proof citation:
rfc0042_b29_grounded; verification pending) - MUST — Preset names must be unique within a runtime
- MUST — Write-side permission decisions must re-evaluate inside the write transaction (proof citation:
rfc0042_b9_grounded; verification pending) - MUST — resourceId without resourceKind must be rejected (proof citation:
rfc0042_b31_grounded; verification pending) - MUST_NOT — sameAs must not influence runtime evaluation
Permission Cache
- MUST — Backends must document whether invalidation is eager or lazy
- MUST_NOT — Permission queries must not trust the cache for write-side decisions (proof citation:
rfc0042_b11_grounded; verification pending) - MUST — The permission cache must be invalidated on the four documented trigger conditions (proof citation:
rfc0042_b5_grounded; verification pending) - MUST — Writes depending on a permission check must re-evaluate the policy chain inside the write transaction (proof citation:
rfc0042_b23_grounded; verification pending)
Predicate Policy Declaration
- MUST — predicate and permissionLevel are required on every policy
- MUST — resourceId without resourceKind must produce M42010 (proof citation:
rfc0042_b19_grounded; verification pending)
Resource and Statement Policies (Legacy)
- MAY — Implementations may treat resource and statement policies as a separate path or unify under predicate policy evaluation (proof citation:
rfc0042_b13_grounded; verification pending) - SHOULD — New policy authoring should use predicate_policy for clarity
Runtime Evaluation
- MUST — Backends without native ltree must implement subtree matching via prefix index and equality
- MUST_NOT — Implementations must not cache when-expression results across requests (proof citation:
rfc0042_b0_grounded; verification pending) - MUST — when-expression results must be memoized within a single request scope
Templates and Permissions Shorthand
- MAY — Templates may declare a permissions shorthand that expands to predicate_policy objects (proof citation:
rfc0042_b17_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Depends on | RFC-0040 |
| Extended by | RFC-0043 |
| Extended by | RFC-0048 |