key-cape/docs/tenant-claim-contract.md

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; 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.

The claim carries its provenance

GH-DEC-2026-013 §5 found what the rules above leave unsaid: tenant is a bare string, so a consumer cannot tell a zone the directory asserted about the person from one a registration supplied about the client they came through. approval-engine admits an approver by exact-matching that string while its contract reads as though it relies on the first. The check is sound; the property a reader infers from it is absent. gate-house named the property and left the mechanism to us.

Every token therefore carries tenant_source alongside tenant:

tenant_source	Meaning
directory	The identity layer asserted this zone about this person. Includes the agreement case — if a registration declared the same zone the directory did, the directory still asserted it, so the stronger provenance is the true one.
registration	Supplied by the client registration for a person the directory has placed nowhere. A fact about the client, not about the person. Always the value on service tokens: there is no directory principal behind one.
default	Nobody asserted a zone. This is the profile's non-empty default.

The third value is not padding. The ruling names two sources, but the code has three states, and labelling an unasserted default as directory would reproduce the same defect one level down — a consumer reading an assertion the identity layer never made. That is the unknown-versus-absent distinction GH-DEC-2026-011 §3 requires, applied to our own fallback rather than only to the case we were asked about.

For consumers. Do not treat the three as equivalent for any decision that turns on a fact about the person. registration and default are not weaker evidence of the same thing; they are evidence of a different thing. What follows from that is the consumer's call — gate-house explicitly did not rule on whether approval-engine's exact-match admission is the right gate. Carrying provenance makes that question answerable; it does not answer it.

tenant_source is advertised in claims_supported, and TestIssuedTokensCarryTenantProvenance asserts it reaches issued tokens on both grants, including the unasserted-default case.

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.