FLEX-WP-0008 T01-T02: tenant-engine resource/action vocabulary + policy package
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
CI Smoke / container-smoke (push) Successful in 3s

docs/tenant-engine-{resource-namespace,action-vocabulary}.md: four actions
(tenant.create, tenant.role.grant, tenant.role.revoke, tenant.plan.assign)
matching tenant_engine/src/tenant_engine/authz.py's _RESOURCE_TYPES mapping
exactly. No resource_manifest.yaml -- tenant-engine's resources are created
dynamically, unlike ops-warden's fixed SSH-certificate inventory; documented
as a deliberate deviation.

examples/tenant-engine/: protected_system_manifest.yaml, subject_manifest.yaml
(one registered caller: tenant-engine's own service identity),
policy_package.md (Rego rules + embedded tests), policy_fixtures.yaml (8
allow/deny pairs), assembled registry_snapshot.json, two standalone
check_request examples, README.

Design decision made explicit in the workplan: operator/service-identity
authorization (one known subject, four known actions), not aal2+assurance +
tenant-capability-role checking -- CheckRequest carries no assurance claim
yet (TEN-WP-0003 already flagged actor as a plain request-body field, not a
real auth context), and a tenant's capability roles are the tenant's own
state, not a property of who may call tenant-engine's admin API. Revisit
once KEY-WP-0005 gives callers a real assurance-bearing identity.

Verified for real: built ./cmd/flex-auth, ran test-policy (6 tests + 8
fixtures, all pass), load-registry, check against both example requests.
Then ran a live flex-auth serve with this exact registry+policy and pointed
tenant-engine's real, unmodified FlexAuthCheckClient/FlexAuthWriteAuthorizer
at it over real HTTP: unknown subject -> 403, tenant-engine -> 201. go test
./... still green across the whole repo.

T03 (live-lookup context adapter for other protected systems) stays open --
new Go adapter package, tracked separately.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-07-23 23:05:57 +02:00
parent ab0125193f
commit 49de2f40ff
11 changed files with 744 additions and 2 deletions

View file

@ -0,0 +1,58 @@
# tenant-engine Consumer Integration Fixtures
`FLEX-WP-0008-T01`/`T02`. Registers `tenant-engine` as a flex-auth
protected-system consumer, gating its own write API
(`TEN-WP-0003`'s `authz.FlexAuthWriteAuthorizer`).
## Files
| File | Purpose |
| --- | --- |
| `protected_system_manifest.yaml` | Resource types (`tenant`, `role-grant`, `plan-assignment`) and actions (`tenant.create`, `tenant.role.grant`, `tenant.role.revoke`, `tenant.plan.assign`) |
| `subject_manifest.yaml` | The one registered caller: `tenant-engine`'s own service identity |
| `policy_package.md` | Rego rules + embedded tests gating the write API |
| `policy_fixtures.yaml` | Allow/deny request/decision pairs, referenced by `policy_package.md`'s frontmatter |
| `registry_snapshot.json` | Merged `systems`/`subjects`/`groups` snapshot assembled from the two manifests above, loadable by `flex-auth serve`/`check`/`load-registry` |
| `check_request_allow_create.json`, `check_request_deny_unknown_subject.json` | Standalone example requests for `flex-auth check` |
**No `resource_manifest.yaml`** — unlike ops-warden's fixed SSH-certificate
inventory, `tenant-engine`'s resources (tenants) are created dynamically.
See `docs/tenant-engine-resource-namespace.md` for why that's a deliberate
omission, not an oversight.
## Verified
```bash
go build -o bin/flex-auth ./cmd/flex-auth
# Rego rules + embedded tests + fixtures, all pass:
bin/flex-auth test-policy -file examples/tenant-engine/policy_package.md
# Registry loads cleanly:
bin/flex-auth load-registry -file examples/tenant-engine/registry_snapshot.json
# Individual requests via the CLI:
bin/flex-auth check \
-registry examples/tenant-engine/registry_snapshot.json \
-policy examples/tenant-engine/policy_package.md \
-request examples/tenant-engine/check_request_allow_create.json
# End-to-end over real HTTP: a live `flex-auth serve` loaded with this
# exact registry+policy, hit by tenant-engine's actual
# FlexAuthCheckClient/FlexAuthWriteAuthorizer (not a mock) --
# POST /tenants with actor="ops" -> 403 (unknown_subject);
# actor="tenant-engine" -> 201 (write_api_policy_matched).
bin/flex-auth serve -addr 127.0.0.1:9098 \
-registry examples/tenant-engine/registry_snapshot.json \
-policy examples/tenant-engine/policy_package.md
# (from tenant-engine's own checkout)
TENANT_ENGINE_FLEX_AUTH_URL=http://127.0.0.1:9098 make run
```
## Related
- `docs/tenant-engine-resource-namespace.md`
- `docs/tenant-engine-action-vocabulary.md`
- `tenant-engine/docs/flex-auth-integration.md` — the client side of this
integration
- `net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`

View file

@ -0,0 +1,15 @@
{
"id": "check:tenant-engine-create-t1",
"tenant": "tenant:friendly:binky",
"subject": {
"id": "tenant-engine",
"type": "service"
},
"action": "tenant.create",
"resource": {
"id": "t-1",
"type": "tenant",
"system": "tenant-engine"
},
"context": {}
}

View file

@ -0,0 +1,15 @@
{
"id": "check:tenant-engine-create-t1",
"tenant": "tenant:friendly:binky",
"subject": {
"id": "some-other-service",
"type": "service"
},
"action": "tenant.create",
"resource": {
"id": "t-1",
"type": "tenant",
"system": "tenant-engine"
},
"context": {}
}

View file

@ -0,0 +1,98 @@
[
{
"id": "fixture:tenant-engine-create-allow",
"request": {
"id": "check:tenant-engine-create-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "tenant-engine", "type": "service"},
"action": "tenant.create",
"resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"},
"context": {}
},
"expect": {"effect": "allow", "reason": "write_api_policy_matched"}
},
{
"id": "fixture:tenant-engine-role-grant-allow",
"request": {
"id": "check:tenant-engine-role-grant-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "tenant-engine", "type": "service"},
"action": "tenant.role.grant",
"resource": {"id": "t-1", "type": "role-grant", "system": "tenant-engine"},
"context": {}
},
"expect": {"effect": "allow", "reason": "write_api_policy_matched"}
},
{
"id": "fixture:tenant-engine-role-revoke-allow",
"request": {
"id": "check:tenant-engine-role-revoke-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "tenant-engine", "type": "service"},
"action": "tenant.role.revoke",
"resource": {"id": "t-1", "type": "role-grant", "system": "tenant-engine"},
"context": {}
},
"expect": {"effect": "allow", "reason": "write_api_policy_matched"}
},
{
"id": "fixture:tenant-engine-plan-assign-allow",
"request": {
"id": "check:tenant-engine-plan-assign-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "tenant-engine", "type": "service"},
"action": "tenant.plan.assign",
"resource": {"id": "t-1", "type": "plan-assignment", "system": "tenant-engine"},
"context": {}
},
"expect": {"effect": "allow", "reason": "write_api_policy_matched"}
},
{
"id": "fixture:tenant-engine-unknown-subject-deny",
"request": {
"id": "check:tenant-engine-create-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "some-other-service", "type": "service"},
"action": "tenant.create",
"resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"},
"context": {}
},
"expect": {"effect": "deny", "reason": "unknown_subject"}
},
{
"id": "fixture:tenant-engine-wrong-system-deny",
"request": {
"id": "check:tenant-engine-create-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "tenant-engine", "type": "service"},
"action": "tenant.create",
"resource": {"id": "t-1", "type": "tenant", "system": "some-other-system"},
"context": {}
},
"expect": {"effect": "deny", "reason": "wrong_system"}
},
{
"id": "fixture:tenant-engine-unknown-action-deny",
"request": {
"id": "check:tenant-engine-delete-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "tenant-engine", "type": "service"},
"action": "tenant.delete",
"resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"},
"context": {}
},
"expect": {"effect": "deny", "reason": "unknown_action"}
},
{
"id": "fixture:tenant-engine-wrong-subject-type-deny",
"request": {
"id": "check:tenant-engine-create-t1",
"tenant": "tenant:friendly:binky",
"subject": {"id": "tenant-engine", "type": "human"},
"action": "tenant.create",
"resource": {"id": "t-1", "type": "tenant", "system": "tenant-engine"},
"context": {}
},
"expect": {"effect": "deny", "reason": "wrong_subject_type"}
}
]

View file

@ -0,0 +1,165 @@
---
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
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
- 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.
## 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",
}
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_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"}
}
}
```

View file

@ -0,0 +1,77 @@
id: tenant-engine
name: Tenant Engine
resource_types:
- name: tenant
scope_level: Resource
planes:
- Identity
- Audit
metadata:
description: A tenant record (existence, onboarding grouping).
- name: role-grant
scope_level: Resource
planes:
- Identity
- Policy
- Audit
metadata:
description: A capability-role grant or revocation (PLTF/IAM/VEN/CUS).
- name: plan-assignment
scope_level: Resource
planes:
- Identity
- Audit
metadata:
description: A tenant's plan/subscription assignment (by reference id).
actions:
- name: tenant.create
capabilities:
- Create
- Audit
planes:
- Identity
- Audit
exposure_modes:
- Metadata
metadata:
required_context: []
- name: tenant.role.grant
capabilities:
- Grant
- Audit
planes:
- Identity
- Policy
- Audit
exposure_modes:
- Metadata
metadata:
required_context: []
- name: tenant.role.revoke
capabilities:
- Revoke
- Audit
planes:
- Identity
- Policy
- Audit
exposure_modes:
- Metadata
metadata:
required_context: []
- name: tenant.plan.assign
capabilities:
- Bind
- Audit
planes:
- Identity
- Audit
exposure_modes:
- Metadata
metadata:
required_context: []
caring_profiles:
- caring-0.4.0-rc2
metadata:
flex_auth_contract: protected-system-v0
boundary_contract: net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md

View file

@ -0,0 +1,159 @@
{
"systems": [
{
"id": "tenant-engine",
"name": "Tenant Engine",
"resource_types": [
{
"name": "tenant",
"scope_level": "Resource",
"planes": [
"Identity",
"Audit"
],
"metadata": {
"description": "A tenant record (existence, onboarding grouping)."
}
},
{
"name": "role-grant",
"scope_level": "Resource",
"planes": [
"Identity",
"Policy",
"Audit"
],
"metadata": {
"description": "A capability-role grant or revocation (PLTF/IAM/VEN/CUS)."
}
},
{
"name": "plan-assignment",
"scope_level": "Resource",
"planes": [
"Identity",
"Audit"
],
"metadata": {
"description": "A tenant's plan/subscription assignment (by reference id)."
}
}
],
"actions": [
{
"name": "tenant.create",
"capabilities": [
"Create",
"Audit"
],
"planes": [
"Identity",
"Audit"
],
"exposure_modes": [
"Metadata"
],
"metadata": {
"required_context": []
}
},
{
"name": "tenant.role.grant",
"capabilities": [
"Grant",
"Audit"
],
"planes": [
"Identity",
"Policy",
"Audit"
],
"exposure_modes": [
"Metadata"
],
"metadata": {
"required_context": []
}
},
{
"name": "tenant.role.revoke",
"capabilities": [
"Revoke",
"Audit"
],
"planes": [
"Identity",
"Policy",
"Audit"
],
"exposure_modes": [
"Metadata"
],
"metadata": {
"required_context": []
}
},
{
"name": "tenant.plan.assign",
"capabilities": [
"Bind",
"Audit"
],
"planes": [
"Identity",
"Audit"
],
"exposure_modes": [
"Metadata"
],
"metadata": {
"required_context": []
}
}
],
"caring_profiles": [
"caring-0.4.0-rc2"
],
"metadata": {
"flex_auth_contract": "protected-system-v0",
"boundary_contract": "net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md"
}
}
],
"resource_manifests": [],
"tenants": [
{
"id": "tenant:platform",
"name": "Platform Tenant"
}
],
"subjects": [
{
"id": "tenant-engine",
"type": "Service",
"display_name": "tenant-engine service principal",
"organization_relation": "ServiceProvider",
"roles": [
"Operator"
],
"groups": [
"group:tenant-engine-writers"
],
"tenant": "tenant:platform",
"metadata": {
"description": "tenant-engine's own service identity, used for the tenant.create / tenant.role.grant / tenant.role.revoke / tenant.plan.assign actions it sends to POST /v1/check (authz.FlexAuthWriteAuthorizer)."
}
}
],
"groups": [
{
"id": "group:tenant-engine-writers",
"display_name": "tenant-engine Write API Callers",
"members": [
"tenant-engine"
],
"tenant": "tenant:platform"
}
],
"relationships": []
}

View file

@ -0,0 +1,25 @@
id: subjects:tenant-engine-operators
tenants:
- id: tenant:platform
name: Platform Tenant
subjects:
- id: tenant-engine
type: Service
display_name: tenant-engine service principal
organization_relation: ServiceProvider
roles:
- Operator
groups:
- group:tenant-engine-writers
tenant: tenant:platform
metadata:
description: >-
tenant-engine's own service identity, used for the tenant.create /
tenant.role.grant / tenant.role.revoke / tenant.plan.assign actions
it sends to POST /v1/check (authz.FlexAuthWriteAuthorizer).
groups:
- id: group:tenant-engine-writers
display_name: tenant-engine Write API Callers
members:
- tenant-engine
tenant: tenant:platform