tegwick
f304688d72
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.
371 lines
12 KiB
Markdown
371 lines
12 KiB
Markdown
---
|
|
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
|
|
- tenant.guardrail.read
|
|
- tenant.guardrail.set
|
|
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
|
|
- View
|
|
- 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.
|
|
|
|
## 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
|
|
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",
|
|
"tenant.guardrail.read",
|
|
"tenant.guardrail.set",
|
|
}
|
|
|
|
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
|
|
} else := {"effect": "deny", "reason": first_denial} if {
|
|
true
|
|
}
|
|
|
|
allowed if {
|
|
input.resource.system == "tenant-engine"
|
|
input.action in read_actions
|
|
input.subject.type == "service"
|
|
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"
|
|
|
|
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_subjects
|
|
} else := "action_not_granted" if {
|
|
input.subject.id in known_subjects
|
|
}
|
|
```
|
|
|
|
## 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"}
|
|
}
|
|
}
|
|
|
|
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"}
|
|
}
|
|
}
|
|
```
|