tegwick
d29032d6c4
approval-engine answered the presenting-actor question we put to them and the answer withdrew the client: nobody presents approval-engine-operator. Nothing in their repository obtains an OAuth token, and scope by scope the bundle never described a single actor -- approve belongs to the human client, emit is redundant, and no requester identity was ever settled for create. Annotated as withdrawn in the example config and the packet rather than deleted, because they asked for it to stay authenticable under CCR-2026-0018 if a presenter appears. The separation-of-duties observation is kept because it constrains the re-request: approve must not travel with the operational scopes. Raised rather than filed: "do not provision" cannot undo a provision. The client went live in the 2026-09-09 attended rollout, so the estate now holds a confidential credential that can create and approve approvals, that nobody presents, and that no consumer awaits. Standing capability with no counterparty is a worse resting state than either provisioning it for a named presenter or disabling it. Disablement is KeyCape's to execute and not KeyCape's to decide alone, so it goes to the owners rather than into a commit. Also records GH-DEC-2026-013 conditions (a) and (b) in the tenant contract, both of which strengthen what we had written about ourselves. Row four is normative, and in the direction we would not have guessed: a future change preferring the DIRECTORY is also void, because "the directory won" is still a winner and picking any winner turns a refusal into a silent cross-tenant assertion. And lifting the dynamic-registration exclusion now VOIDS the registration-bound shape that day rather than reopening it for review -- our "must be revisited" was too weak. The shape is recorded as a declared bounded gap, not the terminal state. Verification note: the Go suite could not be run green for this commit because a peer session is mid-edit on token.go and human_tenant_test.go for the §5 provenance work. Every file in this commit is YAML or Markdown; both YAML files were parsed and the example config's scope set and tenant were asserted unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016uV8zoCKpA1WRAxsKRYbdH Assistant: claude-code Assistant-Model: opus Assistant-Process: 1182213@bnt-lap001 Assistant-Session: 966597b9-ae61-46a4-8b9e-1594ab3ec4ad
175 lines
9.5 KiB
Markdown
175 lines
9.5 KiB
Markdown
# Tenant claim contract
|
|
|
|
States what KeyCape owns and emits for the `tenant` claim. Raised by glas-harness
|
|
message `356f6977-d361-4e3b-83ab-b2c7f4759286` (GLAS-WP-0015) and resolved by
|
|
operator decision `5ed3fb35-eca9-413a-82b9-95171ba85bf6` — "Use tenant:platform
|
|
for the Glas approval dependency chain", recorded in
|
|
`glas-harness/docs/platform-tenant-decision.md`.
|
|
|
|
`tenant:platform` is the platform management, administration and services tenant
|
|
(the landlord zone). KeyCape emits it verbatim for the two approval clients and
|
|
still creates no mapping between tenant vocabularies: no alias to `platform` or
|
|
`tenant:coulomb`, and no implicit cross-tenant grant.
|
|
|
|
## What KeyCape emits
|
|
|
|
The `tenant` claim is bound at registration or directory-resolution time and is
|
|
never influenced by request parameters.
|
|
|
|
| Principal | Source of `tenant` | Value in the reviewed registrations |
|
|
| --- | --- | --- |
|
|
| Service (`client_credentials`) | The client's `tenant` field. Required by config validation — a `client_credentials` client without `serviceSubject` and `tenant` fails startup validation. | In `config/service-clients.example.yaml`: `tenant:platform` for `secrets-engine-approval` and `approval-engine-operator`; `tenant:coulomb` for `codex-railiance-platform` and `secrets-engine-openbao`. |
|
|
| Human (`authorization_code`) | The directory user's tenant, falling back to the platform default when unset. | Directory value, else `tenant:coulomb`. |
|
|
|
|
`tenant`, `tenant_hint`, `audience` and `resource` request parameters cannot
|
|
change the claim. `tenant_hint` on `/authorize` reaches registration/enrollment
|
|
handoffs only; it is not a claim input.
|
|
|
|
## The approval chain, after the decision
|
|
|
|
All three layers now use one exact spelling, `tenant:platform`:
|
|
|
|
| Layer | Value | Owner |
|
|
| --- | --- | --- |
|
|
| Approval store tenant | `tenant:platform` | approval-engine |
|
|
| Service-client JWT `tenant` claim | `tenant:platform` | KeyCape (this repo) |
|
|
| Lifecycle CheckRequest tenant | `tenant:platform` | flex-auth |
|
|
|
|
KeyCape performs **no** normalization, prefix-stripping or aliasing, so a
|
|
resource server compares `tenant` as an exact string. The previously observed
|
|
`platform` and `tenant:coulomb` spellings are **not** accepted aliases for
|
|
`tenant:platform`; a token carrying either must be denied by the resource server.
|
|
|
|
## Scope of the alignment
|
|
|
|
The decision changed the `tenant` field on exactly two registrations,
|
|
`secrets-engine-approval` and `approval-engine-operator`, plus the matching
|
|
entries in `docs/approval-engine-provisioning-request.yaml`. Deliberately
|
|
unchanged:
|
|
|
|
- `codex-railiance-platform` and `secrets-engine-openbao` keep `tenant:coulomb`.
|
|
- Human directory resolution keeps its `tenant:coulomb` default.
|
|
- No cross-tenant grant is implied: a `tenant:platform` token conveys no reach
|
|
into `tenant:coulomb` resources, and audiences, scopes, subjects, roles,
|
|
lifetimes and MFA requirements are untouched.
|
|
|
|
This resolves the *choice* of tenant only. Live provisioning of the two clients
|
|
remains gated on deployment-owned custody and the separate verification gates in
|
|
KEY-WP-0013-T02; KeyCape changed no live registration or policy subject.
|
|
|
|
## Evidence
|
|
|
|
`src/internal/server/oidc/tenant_test.go`:
|
|
|
|
- `TestServiceTenantIsBoundToRegistrationAndIgnoresRequestParameters` — a request
|
|
supplying `tenant=tenant:platform` and `tenant_hint=platform` still yields the
|
|
registered `tenant`, signature-verified against `/jwks`.
|
|
- `TestServiceTenantsAreDistinctPerRegistration` — two registrations with
|
|
different tenants yield their own values and never each other's; this is the
|
|
wrong-tenant denial basis for an exact-comparison resource server.
|
|
- `TestHumanTenantClaimUsesDirectoryValueThenPlatformDefault` — human tokens carry
|
|
the directory tenant, defaulting to `tenant:coulomb` rather than an empty claim.
|
|
- `TestApprovalClientIssuesExactPlatformTenantAndRejectsAliases` — the
|
|
approval-client shape issues `tenant:platform` exactly, with
|
|
`aud=approval-engine`, even when the caller asks for `platform`,
|
|
`tenant:coulomb` or `TENANT:PLATFORM`.
|
|
- `TestUnrelatedServiceClientKeepsCoulombTenant` — the OpenBao login client keeps
|
|
`tenant:coulomb` even when the request asks for `tenant:platform`, so the
|
|
alignment grants no cross-tenant reach.
|
|
|
|
`src/cmd/keycape/clients_test.go`:
|
|
|
|
- `TestServiceRegistrationTenantsAreExactPerDecision` — loads the real
|
|
registration fixture and pins the exact tenant of every reviewed client, so
|
|
drift or an alias reintroduced into `config/service-clients.example.yaml` fails
|
|
the build.
|
|
|
|
## How a human token's tenant is resolved (KEY-WP-0013-T05)
|
|
|
|
A human's tenant is normally a property of the person, read from the directory
|
|
record. That alone could not serve the approval chain: decision
|
|
`5ed3fb35-eca9-413a-82b9-95171ba85bf6` binds it to the landlord zone,
|
|
approval-engine compares the claim by exact string equality, and no adapter
|
|
populates `domain.User.Tenant` — so every human token fell back to
|
|
`tenant:coulomb` and an approver token would have been refused downstream. It
|
|
would have presented as a failed approval rather than as a registration defect.
|
|
|
|
A client registration may therefore declare a `tenant`, and `humanTenant` in
|
|
`src/internal/server/oidc/token.go` resolves it by these four rules:
|
|
|
|
| Client declares | Directory assigns | Result |
|
|
| --- | --- | --- |
|
|
| nothing | anything | the directory answer, or `tenant:coulomb` — unchanged |
|
|
| a zone | nothing | the declared zone |
|
|
| a zone | the same zone | that zone; client and directory agree |
|
|
| a zone | a **different** zone | **issuance is refused** |
|
|
|
|
The last row is the point, and it is **normative** — GH-DEC-2026-013 condition
|
|
(a). A registration can bind a zone for users the directory has not placed, and
|
|
can never relabel a user it *has* placed. That case fails closed rather than
|
|
picking a winner, because either answer would be a silent cross-tenant
|
|
assertion.
|
|
|
|
Note the direction that cuts, which is not the intuitive one: **a future change
|
|
preferring the directory is also void.** "The directory won" is still a winner,
|
|
and picking any winner converts a refusal into a silent cross-tenant assertion.
|
|
Row four is not a design choice available for later optimisation in either
|
|
direction.
|
|
|
|
This shape is a **declared bounded gap**, not the terminal state. Directory-
|
|
sourced is (GH-DEC-2026-013 §1): a registration is a statement about the *actor*,
|
|
a tenant is a property of the *principal*, and sourcing the second from the first
|
|
collapses two identities in the direction that widens. It was granted because the
|
|
one case distinguishing it from the correct resolution fails closed, and because
|
|
it converges on the terminal state by subtraction rather than needing to be
|
|
unwound — the same code stops supplying the zone and starts enforcing agreement
|
|
with it the day the directory carries tenants. On that day §2 is *spent*, not
|
|
merely unused. Registered as a §13 gap at `net-kingdom@f9e1611`; the directory
|
|
adapter has no named owner yet. The refusal is a `403` with
|
|
`error_type: tenant_binding`, distinct from an authentication failure, so an
|
|
operator can tell a misconfigured registration from a rejected login.
|
|
|
|
This also means the design survives the other resolution. If the directory later
|
|
carries tenants, the same code stops supplying the zone and starts enforcing
|
|
agreement with it — no second migration, and no window in which a stale
|
|
registration silently wins.
|
|
|
|
### Condition of the capability
|
|
|
|
This is not a caveat on the reasoning; it is a condition of the capability, and
|
|
it is stated here so a future change to registration policy has to confront it.
|
|
|
|
> **A client-declared tenant is safe only while client registrations are static
|
|
> and deployment-owned.** If KeyCape ever admits dynamic client registration,
|
|
> anyone able to register a client can name its users' tenant and relabel
|
|
> unplaced users into a zone. The deliberate binding becomes an escalation.
|
|
>
|
|
> **Lifting the exclusion voids this rule rather than reopening it**
|
|
> (GH-DEC-2026-013 condition (b)). This document previously said the rule "must
|
|
> be revisited", and gate-house strengthened that against us: *revisited* implies
|
|
> the answer might survive review, and it would not. If dynamic client
|
|
> registration is ever admitted, the registration-bound shape is void **that
|
|
> day** and the directory becomes the only source, whatever state the adapter is
|
|
> in. Removing this paragraph is not the decision.
|
|
|
|
Recorded at the request of informed-decision, who will hold the approver
|
|
registration and asked for it in the contract rather than in a message.
|
|
|
|
A document can be missed, so the condition is also enforced.
|
|
`TestRegistrationBoundTenantRequiresStaticRegistration`
|
|
(`src/internal/server/oidc/tenant_precondition_test.go`, KEY-WP-0030) asserts
|
|
both halves together: that a client-declared tenant still issues, and that
|
|
discovery advertises no registration endpoint. Whichever is removed first, the
|
|
failure points at the other — which is the part that matters, since
|
|
`tests/profile` has long asserted the endpoint's absence on its own and that
|
|
assertion reads as discovery metadata rather than as a warning about relabelling
|
|
users. Dynamic client registration is a deliberate exclusion in
|
|
[SCOPE](../SCOPE.md); this ties the tenant capability to that exclusion so the
|
|
two cannot drift apart silently.
|
|
|
|
Covered by `src/internal/server/oidc/human_tenant_test.go`, including the
|
|
relabel refusal.
|
|
|
|
These are local issuance proofs. They are not live-rollout evidence; see
|
|
`docs/approval-engine-auth-contract.md` and KEY-WP-0013-T02 for the deployment
|
|
boundary. No token or secret values appear in this document or in test output.
|