coulomb/flex-auth
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
flex-auth/examples/tenant-engine/README.md

126 lines
6.6 KiB
Markdown
Raw Normal View History

FLEX-WP-0008 T01-T02: tenant-engine resource/action vocabulary + policy package 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>
2026-07-23 23:05:57 +02:00
# 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 |
| --- | --- |
Authorize tenant-engine guardrail read and set actions 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.
2026-08-16 02:46:25 +02:00
| `protected_system_manifest.yaml` | Resource types (`tenant`, `role-grant`, `plan-assignment`, `guardrail`) and the nine actions: the original four, the `FLEX-WP-0010` lifecycle trio, and the `FLEX-WP-0014` guardrail pair `tenant.guardrail.read` / `tenant.guardrail.set` |
| `subject_manifest.yaml` | Two registered callers: `tenant-engine` (all nine actions) and `flex-auth` (read-only on `tenant.guardrail.read`) |
FLEX-WP-0008 T01-T02: tenant-engine resource/action vocabulary + policy package 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>
2026-07-23 23:05:57 +02:00
| `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` |
Authorize tenant-engine guardrail read and set actions 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.
2026-08-16 02:46:25 +02:00
| `check_request_allow_create.json`, `check_request_deny_unknown_subject.json`, `check_request_allow_retire.json`, `check_request_deny_misspelled_lifecycle.json`, `check_request_allow_guardrail_read.json`, `check_request_allow_guardrail_set.json`, `check_request_deny_guardrail_set_as_reader.json`, `check_request_deny_misspelled_guardrail.json` | Standalone example requests for `flex-auth check` |
FLEX-WP-0008 T01-T02: tenant-engine resource/action vocabulary + policy package 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>
2026-07-23 23:05:57 +02:00
**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
```
Authorize tenant-engine lifecycle actions (FLEX-WP-0010) Extend the tenant-engine write-API policy package with tenant.update, tenant.retire, and tenant.reactivate, the three actions TEN-WP-0005 introduced. Until now every lifecycle mutation resolved to deny unknown_action, blocking TEN-WP-0005-T05 production rollout. - policy_package.md: three actions in valid_actions and frontmatter; CARING capabilities extended with EditAny/Archive/Restore - protected_system_manifest.yaml, subject_manifest.yaml, and the rebuilt registry_snapshot.json carry all seven actions - docs/tenant-engine-action-vocabulary.md documents the HTTP surfaces - 8 new fixture pairs and 5 new Rego tests, including action-drift guards (tenant.retired, tenant_update -> unknown_action) T02 decision, recorded in policy_package.md: tenant.retire does NOT get stricter authorization yet. With one service subject and no assurance claim in the CheckRequest there is nothing stricter to check, and a condition the sole caller always satisfies would falsely read as separate control. Retirement is reversible and non-destructive. Revisit on KEY-WP-0005 assurance claims or a second operator subject. Verified: 11/11 Rego tests, 16/16 fixtures, go test ./... green, gofmt and go vet clean. End-to-end against a live serve with a real tenant-engine through the unmodified FlexAuthWriteAuthorizer: update 6176c39c2f4d7b15, retire 8a801b8ee8455080, reactivate c64cf3713cecd970 all allow; unregistered actor denied unknown_subject (59d3e99c6416be89, 403 write_denied). Handoff revision for TEN-WP-0005-T05: package tenant-engine.write-api.mutate v1 (ready, caring-0.4.0-rc2). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 20:52:10 +02:00
## Verified — lifecycle actions (FLEX-WP-0010-T03, 2026-08-10)
`test-policy` reports **11/11 Rego tests and 16/16 fixtures passing**, the
registry loads, and `go test ./...` / `gofmt` / `go vet` are clean.
End-to-end over real HTTP: a live `flex-auth serve` on `127.0.0.1:9098`
loaded with this registry and policy, and a real `tenant-engine`
(`TENANT_ENGINE_FLEX_AUTH_URL=http://127.0.0.1:9098`) driven through its
unmodified `FlexAuthWriteAuthorizer` with `Idempotency-Key` and an `If-Match`
echoed from a prior `GET`:
| Call | tenant-engine | flex-auth decision |
| --- | --- | --- |
| `POST /tenants` | 201 | `decision:174dc9ecb03ed9e5` allow `write_api_policy_matched` |
| `PATCH /tenants/t-e2e-1` | 200 `active` | `decision:6176c39c2f4d7b15` allow `write_api_policy_matched` |
| `POST /tenants/t-e2e-1/retire` | 200 `retired` | `decision:8a801b8ee8455080` allow `write_api_policy_matched` |
| `POST /tenants/t-e2e-1/reactivate` | 200 `active` | `decision:c64cf3713cecd970` allow `write_api_policy_matched` |
| `POST .../retire` as `actor: ops` | 403 `write_denied` | `decision:59d3e99c6416be89` deny `unknown_subject` |
The misspelled-action guard (`tenant.retired` → deny `unknown_action`) is
covered by fixture and by
`check -request check_request_deny_misspelled_lifecycle.json`; it cannot be
driven through the client, which only ever emits the seven registered strings
— which is the property the guard exists to protect.
Restore flex-auth-tenant-engine to the seven-action policy image FLEX-WP-0013. Production had been rolled back to sha256:c25fc34a (four actions), so tenant.update / tenant.retire / tenant.reactivate denied unknown_action. Re-pin and apply the previously-live sha256:9320df39 image (e9911eb). Live probe after restore: all seven actions allow; misspelled action and unknown subject still deny. user-engine pin unchanged. TEN-WP-0006 guardrail actions not added.
2026-08-16 02:36:56 +02:00
**In production as of FLEX-WP-0013 (2026-08-16).** The live
`flex-auth-tenant-engine` Deployment on railiance01 runs
`sha256:9320df394a642eff24da8af4a0ee8886a7bb78b0f14d8ee1deeb30ea8eeeaba7`
(CI-built from `e9911eb`). Probed against the Service after restore:
| Action | Effect | Decision |
| --- | --- | --- |
| `tenant.create` | allow `write_api_policy_matched` | `decision:2a94b9ee0dcb4050` |
| `tenant.update` | allow `write_api_policy_matched` | `decision:422fe875467610fb` |
| `tenant.retire` | allow `write_api_policy_matched` | `decision:799301d3443fd6a4` |
| `tenant.reactivate` | allow `write_api_policy_matched` | `decision:4160478ca5499457` |
| `tenant.retired` (typo) | deny `unknown_action` | `decision:30946c43cbe80bfc` |
| unregistered subject | deny `unknown_subject` | `decision:7b107e73cf16fab9` |
Authorize tenant-engine guardrail read and set actions 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.
2026-08-16 02:46:25 +02:00
Rollback target is `sha256:c25fc34a…` (four-action).
## Verified — guardrail actions (FLEX-WP-0014-T03, 2026-08-16)
`test-policy` reports **17/17 Rego tests and 23/23 fixtures passing**, the
registry loads (2 subjects, 2 groups), and `go test ./...` / `gofmt` /
`go vet` are clean.
End-to-end over real HTTP: a live `flex-auth serve` on `127.0.0.1:9098`
loaded with this registry and policy, and a real `tenant-engine`
(`TENANT_ENGINE_FLEX_AUTH_URL=http://127.0.0.1:9098`) driven through its
unmodified `FlexAuthWriteAuthorizer`:
| Call | tenant-engine | flex-auth decision |
| --- | --- | --- |
| `POST /tenants` actor=`tenant-engine` | 201 | allow `write_api_policy_matched` |
| `GET .../guardrails?actor=flex-auth` | 200 grouping `spend.monthly=25000` | allow |
| `GET .../guardrails?actor=ops` | 403 `write_denied` | deny `unknown_subject` |
| `PUT .../guardrails/spend.monthly` actor=`tenant-engine` | 200 override `9000` v2 | allow |
| `PUT ...` actor=`flex-auth` | 403 `write_denied` | deny `action_not_granted` |
| `PUT ...` actor=`ops` | 403 `write_denied` | deny `unknown_subject` |
**In source, not yet in the production image.** The live
`flex-auth-tenant-engine` Deployment still serves the seven-action
`sha256:9320df39` pin. A CI-built image from this commit plus a pin
restore is the remaining step before a live guardrail check succeeds
against the cluster Service.
Record production gap for FLEX-WP-0010 and re-probe FLEX-WP-0009 FLEX-WP-0010-T04: the deployed flex-auth-tenant-engine Deployment bakes the policy package into its image, so production still serves the four-action policy -- probed live, tenant.retire returns deny unknown_action there while tenant.create allows. TEN-WP-0005-T05 is unblocked in source but needs an image build from 8e127e5 and a rollout, which this workplan does not scope. Stated in the workplan and in examples/tenant-engine/README.md rather than left implied. FLEX-WP-0009-T04: replayed all six user-engine fixtures against the deployed flex-auth-user-engine service; all six matched expected effect and reason, confirming the deployed failure matrix is still fail-closed. T04 stays in progress -- the criterion also requires user-engine to retire its local bridge, which is not flex-auth's to close. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 20:55:41 +02:00
FLEX-WP-0008 T01-T02: tenant-engine resource/action vocabulary + policy package 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>
2026-07-23 23:05:57 +02:00
## 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`
Reference in a new issue Copy permalink