--- id: tenant-engine.write-api.mutate name: tenant-engine Write API authorization namespace: tenant-engine:tenant version: v1 status: ready package: flexauth.tenant_engine.write_api actions: - tenant.create - tenant.role.grant - tenant.role.revoke - tenant.plan.assign - tenant.update - tenant.retire - tenant.reactivate owner: team:platform-security fixtures: - policy_fixtures.yaml caring: profile: caring-0.4.0-rc2 enforce: false canonical_roles: - Operator organization_relations: - ServiceProvider scopes: - level: Platform id: platform:tenant-engine tenant: tenant:platform planes: - Identity - Policy - Audit capabilities: - Create - Grant - Revoke - Bind - EditAny - Archive - Restore - Audit exposure_modes: - Metadata conditions: - Logged restrictions: - PrivilegeEscalationBlocked activation: mode: local metadata: source: examples/tenant-engine/policy_package.md flex_auth_contract: protected-system-v0 --- # tenant-engine Write API authorization This package authorizes `tenant-engine`'s write API (`TEN-WP-0003`'s `authz.FlexAuthWriteAuthorizer`). `tenant-engine` keeps custody of tenant records, role-grant audit trails, and plan assignments; flex-auth decides whether a specific write is allowed now. **Scope note:** this policy governs *who may call tenant-engine's admin API* (an operator/service-identity question) — it does not evaluate a *tenant's* capability roles (`PLTF`/`IAM`/`VEN`/`CUS`, ADR-0014). Those are tenant state a *different* protected system's policy might consult via `tenant-engine`'s live-lookup endpoint (`FLEX-WP-0008-T03`); conflating the two would authorize the wrong thing. ## Lifecycle actions (FLEX-WP-0010) `tenant.update`, `tenant.retire`, and `tenant.reactivate` gate `tenant-engine`'s lifecycle endpoints (`PATCH /tenants/{id}`, `POST /tenants/{id}/retire`, `POST /tenants/{id}/reactivate`). The action strings are the exact values `authz.FlexAuthWriteAuthorizer` sends; they are coordinated between the two repos, not independently chosen here. They are three actions rather than one `tenant.write` because tenant-engine deliberately separated them so policy *can* one day permit renaming a tenant without permitting retiring it. Under the current model that separation is a seam, not a difference — see the decision below. ### Decision: `tenant.retire` does not require stricter authorization yet **Decision (FLEX-WP-0010-T02, 2026-08-10): no.** `tenant.retire` is authorized by the same rule as the other six actions. Reasoning: 1. **There is nothing stricter to check.** The subject set is exactly one service identity (`tenant-engine`), there is no second operator to distinguish from, and requests carry no `assurance` claim — the `CheckRequest` shape from FLEX-WP-0008 has no field that could differentiate retirement from an update. A "stricter" rule today could only be stricter in name. 2. **A rule that cannot fail is worse than no rule.** Adding a condition that the single known caller always satisfies would read, to a later reviewer, as though retirement were separately controlled when it is not. That is a false assurance in a policy package whose job is to be inspectable. 3. **The blast radius is recoverable.** Retirement is reversible by design via `tenant.reactivate`, and tenant-engine hard-deletes nothing. A wrongly allowed retirement suspends new grants and plan changes until reactivated; it does not destroy tenant state. 4. **The seam is already cut.** Because the three actions are distinct strings in `valid_actions`, tightening `tenant.retire` later is an additive change to this package — no consumer change, no request-shape change, no coordination round with tenant-engine. **Revisit when** `KEY-WP-0005` gives callers an `assurance`-bearing identity, **or** when a second operator subject is registered against `system: "tenant-engine"` — whichever comes first. At that point the honest 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. ## Rules ```rego import future.keywords.contains import future.keywords.if import future.keywords.in valid_actions := { "tenant.create", "tenant.role.grant", "tenant.role.revoke", "tenant.plan.assign", "tenant.update", "tenant.retire", "tenant.reactivate", } known_operators := {"tenant-engine"} decision := {"effect": "allow", "reason": "write_api_policy_matched"} if { allowed } else := {"effect": "deny", "reason": first_denial} if { true } allowed if { input.resource.system == "tenant-engine" input.action in valid_actions input.subject.type == "service" input.subject.id in known_operators } default first_denial := "no_matching_rule" first_denial := "wrong_system" if { input.resource.system != "tenant-engine" } else := "unknown_action" if { not input.action in valid_actions } else := "wrong_subject_type" if { input.subject.type != "service" } else := "unknown_subject" if { not input.subject.id in known_operators } ``` ## Tests ```rego test package flexauth.tenant_engine.write_api_test import future.keywords.if import data.flexauth.tenant_engine.write_api base_request := { "id": "check:tenant-engine-create", "tenant": "tenant:friendly:binky", "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.create", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } test_known_operator_create_allowed if { write_api.decision.effect == "allow" with input as base_request } test_role_grant_allowed if { write_api.decision.effect == "allow" with input as { "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.role.grant", "resource": {"id": "t-1", "type": "role-grant", "system": "tenant-engine"} } } test_tenant_update_allowed if { write_api.decision.effect == "allow" with input as { "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.update", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } test_tenant_retire_allowed if { write_api.decision.effect == "allow" with input as { "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.retire", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } test_tenant_reactivate_allowed if { write_api.decision.effect == "allow" with input as { "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.reactivate", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } test_misspelled_lifecycle_action_denied if { write_api.decision.reason == "unknown_action" with input as { "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.retired", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } test_unknown_subject_retire_denied if { write_api.decision.reason == "unknown_subject" with input as { "subject": {"id": "some-other-service", "type": "service"}, "action": "tenant.retire", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } test_unknown_subject_denied if { write_api.decision.reason == "unknown_subject" with input as { "subject": {"id": "some-other-service", "type": "service"}, "action": "tenant.create", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } test_wrong_system_denied if { write_api.decision.reason == "wrong_system" with input as { "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.create", "resource": {"id": "t-1", "type": "tenant", "system": "some-other-system"} } } test_unknown_action_denied if { write_api.decision.reason == "unknown_action" with input as { "subject": {"id": "tenant-engine", "type": "service"}, "action": "tenant.delete", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } test_wrong_subject_type_denied if { write_api.decision.reason == "wrong_subject_type" with input as { "subject": {"id": "tenant-engine", "type": "human"}, "action": "tenant.create", "resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"} } } ```