approval-engine/docs/keycape-service-registrations.md

Requested KeyCape registrations

Status: requested by APPROVAL-WP-0002-T01. Non-secret. KeyCape owns issuance, client disablement, and the exact claim contract. This file is a consumer request, not a live registration.

Tokens presented to approval-engine MUST use resource-server audience approval-engine. Do not reuse the OpenBao service-auth pattern that sets aud to the OAuth clientId.

Required claims remain those in docs/caller-authentication.md: iss, sub, aud, exp, iat, principal_type, tenant, roles, scope, assurance. principal_type for consume callers must be service or agent.

Resource server

Field	Value
Audience	approval-engine
Issuer	the deployed KeyCape issuer (manifest uses https://kc.coulomb.social)
JWKS	GET /jwks on the KeyCape service
Scopes	approval:create, approval:read, approval:approve, approval:revoke, approval:supersede, approval:consume, approval:observe, approval:emit

Tenant — resolved: exact tenant:platform

The operator accepted tenant:platform as the platform management, administration and services tenant (the landlord zone). Decision 5ed3fb35-eca9-413a-82b9-95171ba85bf6, recorded in glas-harness/docs/platform-tenant-decision.md and relayed by glas-harness 2026-09-06.

The spelling is the contract. ApiApplication.identity compares the verified JWT tenant claim to the engine's configured store tenant with exact string equality and raises Forbidden before any object lookup (approval_engine/api.py:66). There is no mapping table, no normalisation, and no prefix handling anywhere in this engine — deliberately. platform is not an accepted alias for tenant:platform, and neither is tenant:coulomb.

Rendered values, all three now exactly tenant:platform:

Value	Where it is set	Content
Store tenant	deploy/approval-engine.yaml --tenant	tenant:platform
Store tenant default	approval_engine/cli.py --tenant, Engine(tenant=…)	tenant:platform
JWT tenant claim	the client registrations below	tenant:platform
CheckRequest tenant	flex-auth policy subject	tenant:platform

The CLI and Engine defaults were moved off platform in the same change. A default that differs from the sanctioned value is a trap: a serve invocation that omits --tenant would have come up healthy and then refused every authenticated call, which is the failure this decision exists to prevent.

The flex-auth CheckRequest tenant now matches by spelling, but note it still does not participate in this comparison — it is a PDP policy subject this engine never reads. Alignment there is a property of the decision, not a mechanism here.

Denial evidence:

• tests/test_auth.py::test_wrong_tenant_is_forbidden — a signature-valid token whose tenant differs from the store tenant is refused 403 without mutation.
• tests/test_auth.py::test_near_miss_tenant_spellings_are_forbidden — pins the decision's "no alias" clause directly: platform, tenant:coulomb, TENANT:PLATFORM, tenant:platform (trailing space) and `` (empty) are each refused against a tenant:platform store, while the exact spelling is admitted. Without a test that varies the tenant, a suite of fixtures all carrying the sanctioned value proves nothing about the field.

This resolves the choice of value only. Verification and the remaining admission gates — KeyCape actually owning these registrations, credential materialization, and the T03 rollout evidence — are unchanged and still open.

Tracked against APPROVAL-WP-0002-T01; related KEY-WP-0013-T02, SECRETS-WP-0009-T03, GLAS-WP-0015.

Clients

Confidential client secrets stay in OpenBao/operator custody. secretRef names below are placeholders for that custody path.

clients:
  - clientId: secrets-engine-approval
    displayName: secrets-engine PEP consume client
    audience: approval-engine
    allowedScopes: [approval:read, approval:consume]
    grantTypes: [client_credentials]
    clientType: confidential
    secretRef: env:KEYCAPE_SECRETS_ENGINE_APPROVAL_CLIENT_SECRET
    serviceSubject: service:secrets-engine
    principal_type: service
    tenant: tenant:platform
    roles: [secrets-engine]
    tokenLifetime: 15m

  - clientId: approval-engine-operator
    displayName: approval-engine lifecycle operator
    audience: approval-engine
    allowedScopes:
      - approval:create
      - approval:read
      - approval:approve
      - approval:revoke
      - approval:supersede
      - approval:observe
      - approval:emit
    grantTypes: [client_credentials]
    clientType: confidential
    secretRef: env:KEYCAPE_APPROVAL_ENGINE_OPERATOR_CLIENT_SECRET
    serviceSubject: service:approval-engine-operator
    principal_type: service
    tenant: tenant:platform
    roles: [approval-operator]
    tokenLifetime: 15m

Human approvers use the existing KeyCape human flow with approval:approve only, still with aud=approval-engine. They must not receive approval:consume. As of 2026-09-09 that flow is informed-decision's (INFD-WP-0001); see docs/approver-surface-requirements.md.

approval-engine-operator — requested, unpresented, do not provision

Answering railiance-platform (RPF-WP-0035-T06, CCR-2026-0020) 2026-09-09. Their question was the right one and we could not answer it from this source either, because the answer is nobody.

Nothing in this repository presents this client, and nothing is deployed that could. This engine only verifies bearer tokens; it never obtains one. The sole outbound credential it holds is the mounted audit-token used for audit-core delivery (approval_engine/audit.py), which is not an OAuth client. approval_engine/pep.py is a consumer-side helper for PEPs such as secrets-engine, which present their own tokens. There is no client-credentials grant anywhere in the package, and deploy/approval-engine.yaml is unapplied.

Scope by scope, the bundle we originally requested does not describe one actor:

Scope	Who would present it
approval:create	whoever requests an approval. Not named anywhere in the estate today; gate-house doctrine says which acts need one, but no requester identity has been settled
approval:approve	informed-decision's human client, per its own registration. A service principal holding this is exactly the question gate-house has not ruled on — see the principal_type note below
approval:read	anything rendering or inspecting an approval
approval:revoke, approval:supersede	attended lifecycle operations
approval:observe	monitoring and operations
approval:emit	redundant in normal operation — the running server emits its own heartbeat on --heartbeat-seconds with no token; the route exists only to force one

So this was a convenience bundle written when this repo assumed a single "lifecycle operator" would exist, and it aged badly: it now carries the widest scope set in the pair, including approval:approve, for an identity nobody has named.

Decision, option (b): cancel CCR-2026-0020. No client-side reader is wanted, because there is no presenter. This is an owner decision and not a deferral — recorded here so the request does not rot in_flight. Verifier custody (CCR-2026-0018) is unaffected and remains correct: KeyCape must be able to authenticate this client if it is ever presented.

When a presenter is actually named, the registration should be re-requested narrowed to that presenter's scopes, not reinstated as this bundle. In particular approval:approve should not travel with the operational scopes: schema v4 records entries.principal_type so a service bind is legible, but legibility is not permission, and whether a non-human may supply approver evidence at all is gate-house's to rule on.

secrets-engine-approval above is unaffected — it has a real presenter, a narrow scope pair, and is the client that unblocks T05.

It was already live — disable the registration, keep the custody

2026-09-10: key-cape reports the withdrawal came too late. The client was provisioned in the 2026-09-09 attended custody window and verified there (docs/evidence/2026-09-09-keycape-verifier-admission.json records exact_claims_verified and a working exchange for approval-engine-operator), its secret is in the namespace and wired into a pod.

So the estate holds a live confidential credential that can create and approve approvals, that nobody presents, and that no consumer is waiting on. Standing capability with no counterparty is a worse resting state than either extreme: it serves no one, and it is the shape found later by someone other than its owner.

Decision, as requesting owner: disable the registration, keep the custody. Not delete. CCR-2026-0018 verifier custody stands, so the client remains authenticable and restorable the moment a presenter is named; the re-request constraint above still applies — narrowed to that presenter, and approval:approve must not travel with the operational scopes. key-cape executes the disablement with railiance-platform as the deployment change.

The middle option — leaving it standing with a recorded expiry — was rejected deliberately. An expiry is a promise to act later on a capability that is dangerous now, and the thing it protects against is precisely the case where nobody is watching.

Human approver client — not supplied (2026-09-08)

KEY-WP-0013-T02 asked for two exact strings for the human approver registration (public client, authorization code + S256 PKCE, exact redirect, aud=approval-engine, allowedScopes: [openid, approval:approve], mfaRequired: true): the client_id and the full callback URI.

This repository cannot supply either, and must not guess one. Redirects are matched exactly at /authorize, so a fabricated value fails closed — or, worse, registers a redirect no deployed component owns.

Why there is nothing to give:

• approval-engine is a bearer-token resource server only. approval_engine/api.py is a WSGI app whose every non-health route reads Authorization: Bearer … (approval_engine/auth.py). There is no /callback, no redirect handling, no authorization-code or PKCE code anywhere in the package.
• Nothing here is a browser client. The requested registrations above are both client_credentials confidential service clients.
• The service is not publicly addressable: deploy/approval-engine.yaml has a Namespace, ClusterIP Service and StatefulSet — no Ingress, no external hostname — so no https://…/callback origin exists to register.

The human approver flow therefore belongs to whichever browser-facing approver UI presents approval:approve tokens to this engine. That component is not in this repo and is not named in APPROVAL-WP-0002. The two strings must come from its owner once it exists and has a deployed origin; approval-engine only needs the resulting access token to carry aud=approval-engine, principal_type: human, tenant: tenant:platform and scope approval:approve.

Token confirmed: access token, never the ID token

ApiApplication.identity verifies the access token presented as Authorization: Bearer at this resource — RS256 against the deployed issuer's /jwks, checking iss, aud=approval-engine, exp/iat (30s leeway), sub, principal_type, tenant (exact equality with the store tenant), roles, scope and assurance. id_token appears nowhere in the codebase; the ID token belongs to the login client and is never evidence here. Human principals are additionally refused approval:consume.