flex-auth/examples/tenant-engine/policy_package.md

id	name	namespace	version	status	package	actions	owner	fixtures	caring	activation	metadata
tenant-engine.write-api.mutate	tenant-engine Write API authorization	tenant-engine:tenant	v1	ready	flexauth.tenant_engine.write_api	tenant.create tenant.role.grant tenant.role.revoke tenant.plan.assign tenant.update tenant.retire tenant.reactivate tenant.guardrail.read tenant.guardrail.set	team:platform-security	policy_fixtures.yaml	profile enforce canonical_roles organization_relations scopes planes capabilities exposure_modes conditions restrictions caring-0.4.0-rc2 false Operator ServiceProvider level id tenant Platform platform:tenant-engine tenant:platform Identity Policy Audit Create Grant Revoke Bind EditAny Archive Restore View Audit Metadata Logged PrivilegeEscalationBlocked	mode local	source flex_auth_contract examples/tenant-engine/policy_package.md 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

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

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"}
  }
}