flex-auth/workplans/FLEX-WP-0010-tenant-lifecycle-policy-actions.md

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	related_workplans	created	updated
FLEX-WP-0010	workplan	Authorize tenant-engine lifecycle actions	infotech	flex-auth	ready	codex	netkingdom	P1	100	FLEX-WP-0008	TEN-WP-0005 USER-WP-0021	2026-08-10	2026-08-10

FLEX-WP-0010 - Authorize tenant-engine lifecycle actions

Extend the existing tenant-engine policy package (FLEX-WP-0008-T02) with the three tenant lifecycle actions TEN-WP-0005 introduced. Until they exist here, every lifecycle mutation resolves to deny with unknown_action — correct fail-closed behaviour, not a defect, but it means tenant-engine's new update and retirement endpoints cannot perform a single write in production.

Requested by: tenant-engine (TEN-WP-0005, T01–T04 complete and merged). Blocks: TEN-WP-0005-T05 (production rollout), and through it USER-WP-0021 (user-engine platform operator UI/API).

Requirements from tenant-engine

Three new actions, all on the existing tenant resource type, all against system: "tenant-engine":

Action	Resource type	HTTP surface
tenant.update	tenant	PATCH /tenants/{tenant_id}
tenant.retire	tenant	POST /tenants/{tenant_id}/retire
tenant.reactivate	tenant	POST /tenants/{tenant_id}/reactivate

These strings are already live in tenant-engine/src/tenant_engine/authz.py's _RESOURCE_TYPES mapping — they are the exact values FlexAuthWriteAuthorizer sends. Match them verbatim; do not let the two repos invent different strings for the same action (the coordination rule FLEX-WP-0008-T01 already established).

The CheckRequest shape is unchanged from FLEX-WP-0008: same FlexAuthCheckClient, same subject_type: "service", resource_id = tenant_id. No new request fields, no schema change.

Why three actions rather than one tenant.write: tenant-engine deliberately separated them so policy can permit an operator to rename a tenant without thereby permitting them to retire it. Consumer contract: tenant-engine/docs/tenant-lifecycle-api.md.

Honest caveat on what this buys today: under FLEX-WP-0008-T02's current model there is exactly one known operator (the tenant-engine service identity) and no assurance claim, so all three actions will resolve identically once added. The separation is a seam for later, not differentiated authorization now. Adding the actions is what unblocks production; differentiating them is T02 below, and may well close as "not yet, and here is why".

T01 - Extend the policy package with the lifecycle actions

id: FLEX-WP-0010-T01
status: todo
priority: high

Add tenant.update, tenant.retire, and tenant.reactivate to examples/tenant-engine/policy_package.md's valid_actions set and to the frontmatter actions: list. Extend the caring.capabilities list if the existing vocabulary (Create/Grant/Revoke/Bind/Audit) does not already cover an update/retire/reactivate shape — a judgement call for this repo, not pre-specified here.

Update examples/tenant-engine/subject_manifest.yaml's subject metadata description, which currently enumerates the original four actions.

Update docs/tenant-engine-action-vocabulary.md with the three actions, their resource type, and the HTTP surface each gates. Keep the existing note that this policy governs who may call tenant-engine's admin API, not a tenant's own PLTF/IAM/VEN/CUS capability roles — the lifecycle actions do not change that boundary and should not be read as doing so.

Rebuild examples/tenant-engine/registry_snapshot.json.

Done when valid_actions carries all seven actions and the vocabulary doc and subject manifest no longer describe only four.

T02 - Decide whether retirement warrants stricter authorization

id: FLEX-WP-0010-T02
status: todo
priority: medium

tenant.retire is the highest-consequence action in the set: it suspends a tenant's ability to receive new capability grants and plan changes across the whole platform. Decide whether it should require anything tenant.update does not — a distinct subject, group, or (once available) assurance level.

Record the decision with its reasoning, in the style of FLEX-WP-0008-T02's closure note. "No, not until KEY-WP-0005 gives callers a real assurance-bearing identity to check" is a perfectly good outcome — the point is that the decision is explicit and recorded rather than defaulted into by treating all seven actions as interchangeable.

Note that retirement is reversible by design (tenant.reactivate), and that tenant-engine hard-deletes nothing — so the blast radius of a wrongly allowed retirement is recoverable, which is legitimate input to this decision.

Done when the decision and its reasoning are recorded in policy_package.md, and implemented if the answer is "yes, stricter".

T03 - Fixtures and verification

id: FLEX-WP-0010-T03
status: todo
priority: high

Add allow/deny fixture pairs to examples/tenant-engine/policy_fixtures.yaml for each of the three actions, mirroring the existing eight pairs' shape. Cover at minimum: authorized service subject → allow; unknown subject → deny unknown_subject; and a misspelled lifecycle action → deny unknown_action (the case that guards against the two repos drifting apart on action strings).

Verify the way FLEX-WP-0008-T02 did, against the real binary rather than in isolation: go build ./cmd/flex-auth, then test-policy (all Rego tests and fixtures), load-registry, and check against standalone request files.

Then close the loop end-to-end, which is what TEN-WP-0005-T05 actually needs evidence of: run a live flex-auth serve with this registry and point a real tenant-engine at it (TENANT_ENGINE_FLEX_AUTH_URL), then exercise PATCH /tenants/{id}, POST .../retire, and POST .../reactivate through the unmodified FlexAuthWriteAuthorizer. tenant-engine's lifecycle endpoints require Idempotency-Key and If-Match headers — read the record first and echo its ETag back; tenant-engine/docs/tenant-lifecycle-api.md has the call shapes.

Done when all three lifecycle mutations return a real allow from the real Rego engine over real HTTP, go test ./... is green across the repo, and gofmt/go vet are clean.

T04 - Closure and handoff

id: FLEX-WP-0010-T04
status: todo
priority: low

Confirm T01–T03. Run statehub fix-consistency. Notify tenant-engine that TEN-WP-0005-T05 is unblocked, naming the policy revision — T05's own done-criteria require the handoff to name the authorization policy revision alongside the immutable image and API version.