Authorize tenant-engine guardrail read and set actions

FLEX-WP-0014. Package tenant-engine.write-api.mutate v1 now carries
nine actions: tenant.guardrail.read and tenant.guardrail.set on
resource type guardrail, verbatim from tenant-engine's mapping.

The read/write split is used now: flex-auth may read ceilings and is
denied action_not_granted on set; tenant-engine may do both. 17/17
Rego tests and 23/23 fixtures pass. Live e2e against a real
tenant-engine FlexAuthWriteAuthorizer matches.

In source only; production still serves the seven-action 9320df39 pin.

examples/tenant-engine/policy_package.md

@@ -13,6 +13,8 @@ actions:
   - tenant.update
   - tenant.retire
   - tenant.reactivate
+  - tenant.guardrail.read
+  - tenant.guardrail.set
 owner: team:platform-security
 fixtures:
   - policy_fixtures.yaml
@@ -39,6 +41,7 @@ caring:
     - EditAny
     - Archive
     - Restore
+    - View
     - Audit
   exposure_modes:
     - Metadata
@@ -114,6 +117,46 @@ options are an assurance floor on `tenant.retire` or a distinct
 `group:tenant-engine-lifecycle` membership requirement; both are one rule in
 `allowed` plus a `first_denial` branch.
 
+## Guardrail actions (FLEX-WP-0014)
+
+`tenant.guardrail.read` and `tenant.guardrail.set` gate tenant-engine's
+ceiling surface (`GET /tenants/{id}/guardrails`,
+`PUT`/`DELETE /tenants/{id}/guardrails/{limit_key}`). The strings are the
+exact values `authz.FlexAuthWriteAuthorizer` sends. Resource type is
+`guardrail`; `resource.id` is still the tenant id.
+
+They are two actions because a PDP must be able to read ceilings without
+being able to change them. tenant-engine is a data source, never a decision
+maker; flex-auth is the intended reader.
+
+### Decision: use the read/write split now
+
+**Decision (FLEX-WP-0014-T02, 2026-08-16): yes.** `flex-auth` may
+`tenant.guardrail.read` and may not `tenant.guardrail.set`.
+`tenant-engine` may do both. Nobody else may do either.
+
+Reasoning:
+
+1. **The second subject exists and is named.** TEN-WP-0006 split the
+   actions so "policy can grant you [flex-auth] the read without granting
+   anything the write." Their own HTTP tests call the read as
+   `actor=flex-auth`. Leaving both actions on the single `tenant-engine`
+   subject would keep the seam unused and leave the intended reader
+   failing `unknown_subject`.
+2. **This is a real difference, not a named no-op.** Unlike
+   FLEX-WP-0010-T02, there is a second service identity to distinguish
+   from, and a check the reader can fail (`tenant.guardrail.set` as
+   `flex-auth` → `action_not_granted`).
+3. **Do not invent an `ops` write subject.** Production writes already
+   authorize only the `tenant-engine` service identity. Guardrail
+   mutations stay on that same identity. Adding `ops` would widen the
+   write set without a registered operator.
+4. **Do not grant flex-auth any mutate action.** A PDP that can raise a
+   ceiling is no longer only a decision maker.
+
+**Revisit when** a second human/operator subject is registered, or when
+flex-auth itself needs to read as a different subject id than `flex-auth`.
+
 ## Rules
 
 ```rego
@@ -129,9 +172,19 @@ valid_actions := {
   "tenant.update",
   "tenant.retire",
   "tenant.reactivate",
+  "tenant.guardrail.read",
+  "tenant.guardrail.set",
 }
 
-known_operators := {"tenant-engine"}
+read_actions := {"tenant.guardrail.read"}
+
+mutate_actions := valid_actions - read_actions
+
+known_subjects := {"tenant-engine", "flex-auth"}
+
+read_subjects := {"tenant-engine", "flex-auth"}
+
+mutate_subjects := {"tenant-engine"}
 
 decision := {"effect": "allow", "reason": "write_api_policy_matched"} if {
   allowed
@@ -141,9 +194,16 @@ decision := {"effect": "allow", "reason": "write_api_policy_matched"} if {
 
 allowed if {
   input.resource.system == "tenant-engine"
-  input.action in valid_actions
+  input.action in read_actions
   input.subject.type == "service"
-  input.subject.id in known_operators
+  input.subject.id in read_subjects
+}
+
+allowed if {
+  input.resource.system == "tenant-engine"
+  input.action in mutate_actions
+  input.subject.type == "service"
+  input.subject.id in mutate_subjects
 }
 
 default first_denial := "no_matching_rule"
@@ -155,7 +215,9 @@ first_denial := "wrong_system" if {
 } else := "wrong_subject_type" if {
   input.subject.type != "service"
 } else := "unknown_subject" if {
-  not input.subject.id in known_operators
+  not input.subject.id in known_subjects
+} else := "action_not_granted" if {
+  input.subject.id in known_subjects
 }
 ```
 
@@ -258,4 +320,52 @@ test_wrong_subject_type_denied if {
     "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"}
   }
 }
+
+test_guardrail_read_by_pdp_allowed if {
+  write_api.decision.effect == "allow" with input as {
+    "subject": {"id": "flex-auth", "type": "service"},
+    "action": "tenant.guardrail.read",
+    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
+  }
+}
+
+test_guardrail_read_by_writer_allowed if {
+  write_api.decision.effect == "allow" with input as {
+    "subject": {"id": "tenant-engine", "type": "service"},
+    "action": "tenant.guardrail.read",
+    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
+  }
+}
+
+test_guardrail_set_by_writer_allowed if {
+  write_api.decision.effect == "allow" with input as {
+    "subject": {"id": "tenant-engine", "type": "service"},
+    "action": "tenant.guardrail.set",
+    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
+  }
+}
+
+test_guardrail_set_by_pdp_denied if {
+  write_api.decision.reason == "action_not_granted" with input as {
+    "subject": {"id": "flex-auth", "type": "service"},
+    "action": "tenant.guardrail.set",
+    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
+  }
+}
+
+test_guardrail_read_unknown_subject_denied if {
+  write_api.decision.reason == "unknown_subject" with input as {
+    "subject": {"id": "ops", "type": "service"},
+    "action": "tenant.guardrail.read",
+    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
+  }
+}
+
+test_misspelled_guardrail_action_denied if {
+  write_api.decision.reason == "unknown_action" with input as {
+    "subject": {"id": "flex-auth", "type": "service"},
+    "action": "tenant.guardrail.get",
+    "resource": {"id": "t-1", "type": "guardrail", "system": "tenant-engine"}
+  }
+}
 ```