Build and Publish Container Image / build-and-push (push) Successful in 46s

Details

Let a human token carry the zone it is issued into, without relabelling anyone

KEY-WP-0013-T05's tenant blocker did not need the decision it was waiting on. The
two proposed resolutions differ in where a human's tenant comes from -- the
directory record, or the client registration -- and an implementation exists that
is correct under either, so the choice can be made later without another
migration.

A client registration may now declare a tenant. humanTenant() resolves it by four
rules: no declaration keeps the directory answer unchanged; a declared zone
applies where the directory has placed the user nowhere; agreement passes; and a
declared zone conflicting with a directory assignment refuses issuance rather
than relabelling the user.

The refusal is the design, not an edge case. A registration can bind a zone for
unplaced users and can never move a placed one, so this gets the approval chain
its tenant:platform without writing a general cross-tenant override into the
issuer. It fails closed rather than picking a winner, because either answer would
be a silent cross-tenant assertion, and it reports 403 with
error_type: tenant_binding so an operator can tell a misconfigured registration
from a rejected login. If the owners later populate directory tenants, the same
code stops supplying the zone and starts enforcing agreement with it.

Safe only because client registrations are static and deployment-owned. The
tenant contract records that this rule must be revisited if dynamic client
registration is ever admitted.

Tests cover all four rules; neutering the conflict check fails the relabel test
rather than passing silently.

T05 now waits on one thing only: the client_id and callback URI from
informed-decision once it has a deployed origin.

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

2026-09-09 14:40:36 +02:00

6.8 KiB

Raw Blame History

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

It is safe only because client registrations are static and deployment-owned. KeyCape excludes dynamic client registration by design; a self-service client able to name its users' tenant would be a straightforward escalation, and this rule must be revisited if that exclusion is ever lifted.

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.

6.8 KiB Raw Blame History