diff --git a/docs/tenant-engine-action-vocabulary.md b/docs/tenant-engine-action-vocabulary.md new file mode 100644 index 0000000..2882f8e --- /dev/null +++ b/docs/tenant-engine-action-vocabulary.md @@ -0,0 +1,36 @@ +# tenant-engine Action Vocabulary + +This document defines the action vocabulary for `tenant-engine` as a +flex-auth protected system (`FLEX-WP-0008-T01`). Action names here match +`tenant-engine`'s own `authz.FlexAuthWriteAuthorizer` mapping exactly +(`tenant_engine/src/tenant_engine/authz.py`) — coordinated between the two +repos, not independently invented. + +| Action | tenant-engine write endpoint | Resource type | Decision effects | +| --- | --- | --- | --- | +| `tenant.create` | `POST /tenants` | `tenant` | `allow`, `deny` | +| `tenant.role.grant` | `POST /tenants/{id}/roles/grant` | `role-grant` | `allow`, `deny` | +| `tenant.role.revoke` | `POST /tenants/{id}/roles/revoke` | `role-grant` | `allow`, `deny` | +| `tenant.plan.assign` | `POST /tenants/{id}/plan` | `plan-assignment` | `allow`, `deny` | + +These are the only four actions `tenant-engine` sends to `POST /v1/check` — +its `FlexAuthCheckClient` (`TEN-WP-0003`) never sends anything else, and +`tenant-engine`'s reads (`/roles`, `/roles/live`) are never gated through +flex-auth at all; they're `tenant-engine`'s own cache-read and live-lookup +endpoints, consumed *by* `key-cape` and `flex-auth` respectively. + +## Not in scope for this vocabulary + +`tenant-engine`'s capability roles (`PLTF`/`IAM`/`VEN`/`CUS`, ADR-0014) are +**tenant** state — what a tenant is allowed to do on the platform. This +vocabulary governs a different question: which **operator/service +subjects** are allowed to call `tenant-engine`'s admin API at all. The two +must not be conflated — a policy package that checked a *caller's* action +against a *tenant's* capability roles would be checking the wrong thing. +See `examples/tenant-engine/policy_package.md`'s Rules section for how the +distinction is enforced. + +## Related + +- `docs/tenant-engine-resource-namespace.md` +- `examples/tenant-engine/` diff --git a/docs/tenant-engine-resource-namespace.md b/docs/tenant-engine-resource-namespace.md new file mode 100644 index 0000000..ef3a240 --- /dev/null +++ b/docs/tenant-engine-resource-namespace.md @@ -0,0 +1,45 @@ +# tenant-engine Resource Namespace + +This document defines the `tenant-engine` protected-system namespace +consumed by flex-auth (`FLEX-WP-0008-T01`). + +Unlike Markitect's document hierarchy or ops-warden's fixed SSH-certificate +inventory, `tenant-engine`'s resources (tenants, their role grants, their +plan assignments) are created **dynamically** — there is no fixed, +pre-registrable resource list to publish a `resource_manifest.yaml` for. +Every `CheckRequest` carries the resource identity inline +(`resource.id == tenant_id`), and the policy evaluates against `input` +directly rather than looking up a registered resource by id. This is a +deliberate, documented deviation from the ops-warden pattern, not an +omission. + +## Resource Types + +```text +tenant -- a tenant record (existence, grouping) +role-grant -- a capability-role grant/revocation +plan-assignment -- a tenant's plan/subscription assignment +``` + +All three are `scope_level: Resource`, always accessed within +`system: tenant-engine`. + +## Ownership Boundary + +`tenant-engine`'s own boundary contract +(`net-kingdom/canon/standards/tenant-engine-boundary-contract_v0.1.md`) +already defines these as `tenant-engine`'s owned resource kinds. This +namespace only maps that ownership into flex-auth's protected-system +vocabulary — it does not redefine ownership. + +## Related + +- `docs/tenant-engine-action-vocabulary.md` — the actions gated on these + resource types +- `examples/tenant-engine/` — protected-system manifest, subject manifest, + policy package, and fixtures +- `net-kingdom/docs/adr/ADR-0014-tenant-capability-roles-and-tenant-engine-ownership.md` + — the capability-role model (`PLTF`/`IAM`/`VEN`/`CUS`) these resources + carry as *tenant* state, distinct from the *operator* authorization this + namespace governs (who may call `tenant-engine`'s write API, not what a + tenant is allowed to do) diff --git a/examples/tenant-engine/README.md b/examples/tenant-engine/README.md new file mode 100644 index 0000000..db0a493 --- /dev/null +++ b/examples/tenant-engine/README.md @@ -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` diff --git a/examples/tenant-engine/check_request_allow_create.json b/examples/tenant-engine/check_request_allow_create.json new file mode 100644 index 0000000..1438a79 --- /dev/null +++ b/examples/tenant-engine/check_request_allow_create.json @@ -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": {} +} diff --git a/examples/tenant-engine/check_request_deny_unknown_subject.json b/examples/tenant-engine/check_request_deny_unknown_subject.json new file mode 100644 index 0000000..e711730 --- /dev/null +++ b/examples/tenant-engine/check_request_deny_unknown_subject.json @@ -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": {} +} diff --git a/examples/tenant-engine/policy_fixtures.yaml b/examples/tenant-engine/policy_fixtures.yaml new file mode 100644 index 0000000..37b49c4 --- /dev/null +++ b/examples/tenant-engine/policy_fixtures.yaml @@ -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"} + } +] diff --git a/examples/tenant-engine/policy_package.md b/examples/tenant-engine/policy_package.md new file mode 100644 index 0000000..0516467 --- /dev/null +++ b/examples/tenant-engine/policy_package.md @@ -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"} + } +} +``` diff --git a/examples/tenant-engine/protected_system_manifest.yaml b/examples/tenant-engine/protected_system_manifest.yaml new file mode 100644 index 0000000..c528ed0 --- /dev/null +++ b/examples/tenant-engine/protected_system_manifest.yaml @@ -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 diff --git a/examples/tenant-engine/registry_snapshot.json b/examples/tenant-engine/registry_snapshot.json new file mode 100644 index 0000000..e4ce370 --- /dev/null +++ b/examples/tenant-engine/registry_snapshot.json @@ -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": [] +} diff --git a/examples/tenant-engine/subject_manifest.yaml b/examples/tenant-engine/subject_manifest.yaml new file mode 100644 index 0000000..1b8b216 --- /dev/null +++ b/examples/tenant-engine/subject_manifest.yaml @@ -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 diff --git a/workplans/FLEX-WP-0008-tenant-engine-consumer-integration.md b/workplans/FLEX-WP-0008-tenant-engine-consumer-integration.md index eb06b92..8048c40 100644 --- a/workplans/FLEX-WP-0008-tenant-engine-consumer-integration.md +++ b/workplans/FLEX-WP-0008-tenant-engine-consumer-integration.md @@ -16,6 +16,7 @@ related_workplans: - KEY-WP-0005 created: "2026-07-23" updated: "2026-07-23" +state_hub_workstream_id: "6341d238-fffc-4428-9265-0b6db5714e9b" --- # FLEX-WP-0008: tenant-engine Consumer Integration @@ -49,8 +50,9 @@ and action vocabulary is small and doesn't need CARING descriptor mapping. ```task id: FLEX-WP-0008-T01 -status: todo +status: done priority: high +state_hub_task_id: "d78361e6-eb8e-4623-bed2-917538c403ca" ``` Resource types: `tenant`, `role-grant`, `plan-assignment`. Actions: @@ -66,12 +68,23 @@ the `markitect-resource-namespace.md` / `markitect-action-vocabulary.md` naming pattern (`tenant-engine-resource-namespace.md`, `tenant-engine-action-vocabulary.md`). +**Done 2026-07-23:** Both docs written. One deliberate deviation from the +ops-warden template, documented in `tenant-engine-resource-namespace.md`: +no `resource_manifest.yaml` — ops-warden's SSH certificates are a fixed, +pre-registrable inventory; `tenant-engine`'s tenants are created +dynamically, so the policy evaluates `input` directly rather than looking +up a registered resource by id. Action vocabulary cross-checked against +`tenant-engine/src/tenant_engine/authz.py`'s actual +`_RESOURCE_TYPES` mapping — the four action strings and their resource +types match exactly, not just by convention. + ## Task: Author and register the tenant-engine policy package ```task id: FLEX-WP-0008-T02 -status: todo +status: done priority: high +state_hub_task_id: "8a07e83b-27a2-4390-a169-51065bcf3bd6" ``` Policy: writes require an `aal2`+ assurance actor holding an appropriate @@ -87,12 +100,47 @@ Done when: `POST /v1/check` against a request matching `TEN-WP-0003`'s and `deny` for an unauthorized one, exercised by `main_test.go`-style integration tests. +**Done 2026-07-23, with the design decision made explicit:** chose +**operator/service-identity authorization**, not `aal2`+assurance + +tenant-capability-role checking, for this specific policy. Reasoning, +recorded here rather than left implicit: `tenant_engine`'s `CheckRequest` +today carries no `assurance` claim at all (there's no authenticated caller +identity yet — `TEN-WP-0003`'s closure note already flagged `actor` as a +plain request-body field, not a real auth context), and a tenant's +capability roles (`PLTF`/`IAM`/`VEN`/`CUS`) are a property of the *tenant* +being written to, not of *who is allowed to call tenant-engine's admin API* +— checking the wrong one would be a category error, the same one flagged +in `docs/tenant-engine-action-vocabulary.md`. So: `examples/tenant-engine/policy_package.md` +authorizes exactly one registered service subject (`tenant-engine` itself, +`subject_manifest.yaml`) for the four known actions against +`system: "tenant-engine"`. Revisit once `KEY-WP-0005` gives callers a real +`assurance`-bearing identity to check. + +Registered: `protected_system_manifest.yaml`, `subject_manifest.yaml`, +`policy_package.md` (Rego rules + embedded tests), `policy_fixtures.yaml` +(8 allow/deny pairs), assembled `registry_snapshot.json`, two standalone +`check_request_*.json` examples, `README.md`. + +**Verified for real, not just written:** built the actual `flex-auth` +binary (`go build ./cmd/flex-auth`) and ran it against every artifact: +`test-policy` — all 6 Rego tests and all 8 fixtures pass; `load-registry` +loads the snapshot cleanly; `check` against both standalone request files +returns the expected `allow`/`deny`. Then went one step further than the +task's own done-criteria: ran a **live `flex-auth serve`** with this exact +registry+policy and pointed `tenant-engine`'s real, unmodified +`FlexAuthCheckClient`/`FlexAuthWriteAuthorizer` at it (`TENANT_ENGINE_FLEX_AUTH_URL`) +— `POST /tenants` with `actor="ops"` → `403 unknown_subject`; with +`actor="tenant-engine"` → `201`. Full round trip, both processes, real +HTTP, real Rego evaluation. `go test ./...` still green across the whole +`flex-auth` repo — nothing broken. + ## Task: tenant-engine live-lookup context adapter ```task id: FLEX-WP-0008-T03 status: todo priority: medium +state_hub_task_id: "20c005a4-48b7-4ac4-a345-aeaa0de06d80" ``` A context-enrichment adapter (mirrors `internal/adapters/{relationship,rule,topaz}`'s @@ -115,6 +163,7 @@ with an empty result. id: FLEX-WP-0008-T04 status: todo priority: low +state_hub_task_id: "0c59ada6-c61b-41a3-8baa-a98e936c5690" ``` Confirm T01–T03 done; run flex-auth's existing test suite plus the new