key-cape/workplans/KEY-WP-0013-approval-engine-resource-audience.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
KEY-WP-0013	workplan	Approval-engine resource audience and client registrations	infotech	key-cape	blocked	codex	approval-engine-resource-audience	2026-09-05	2026-09-09	6e815d88-b0e3-5ce0-be5d-13ab15917f7f

Source: approval-engine inbox request 5583e896-52f2-45bd-895f-02f227b7e836, reviewed against its local registration and caller-authentication contracts.

Implement static resource audiences

id: KEY-WP-0013-T01
status: done
priority: high
state_hub_task_id: "a92432a2-4e92-5b90-be2b-d82b784bf8f0"

Added optional static audience configuration for access tokens in both grants; ID tokens retain the relying-party audience. Added human access-token scope. Published bounded approval service fragments and the human registration contract. Regression tests cover the default audience, request override resistance, JWKS signature validation, ID-token separation and service registration scope isolation. Browser requests and token exchanges now enforce the client scope allow-list, including grants removed after authorization.

Provision and prove live registrations

id: KEY-WP-0013-T02
status: done
priority: high
state_hub_task_id: "607897c5-bad9-55e5-86df-7802f592d6e8"

Needs deployment-owned custody for both new service secret references and the compatible image/configuration rollout. The upstream issuer is now verified and pinned by NetKingdom (2026-09-09). Deploy the implementation and service registrations together, then prove live JWKS verification and denied excess scopes without logging values. Local signature proof is not live rollout evidence. See docs/approval-engine-auth-contract.md. The separate human UI callback gate is retained in T05; a bearer-only resource server does not own a redirect and its absence does not block these service clients.

2026-09-05 follow-up: read-only deployment metadata shows the current image is forgejo.coulomb.social/coulomb/key-cape:main-153258b and only the Qonto service secret environment reference is present. The two approval clients are not materialized through deployment environment references. Published a concrete non-secret admission packet at docs/approval-engine-provisioning-request.yaml. Custody routing has no exact admitted lane for these two clients. warden plan returned founder_required but matched an unrelated generic database lane; that mismatch is not authority to provision. Human callback clarification is pending. No secrets were read or production resources changed.

2026-09-08: the two blocking requests were sent and their receipts are readable back via GET /messages/?from_agent=key-cape.

• 278a3ebe-b529-49f6-bd1a-e3ebcf318260 -> railiance-platform. Custody admission for both clients, quoting docs/approval-engine-provisioning-request.yaml verbatim: exact OpenBao paths and client_secret field, the two Kubernetes delivery references, the two KEYCAPE_*_CLIENT_SECRET environment names, tenant:platform per decision 5ed3fb35-eca9-413a-82b9-95171ba85bf6, and the 15m lifetime. It asks for four things explicitly: confirm/correct the paths and fields, confirm the delivery references, name the authority for the attended first provision, and agree a rollout window in which registrations and the KeyCape version that reads them deploy together. It restates that the warden plan founder_required result matched an unrelated generic database lane and is not being treated as authorization.
• 43fbd997-6e22-4859-8433-58b784c2df6c -> approval-engine. Requests the two missing human-registration inputs — the exact client_id and the full callback URI — noting redirects are matched exactly and a near-miss fails closed at /authorize. Restates the human client shape (public, S256 PKCE, audience: approval-engine, allowedScopes: [openid, approval:approve], mfaRequired: true, no consume grant) and asks approval-engine to confirm it validates the access token, not the ID token, against the deployed /jwks.

Deployment state is unchanged from the 2026-09-05 observation: neither approval client is materialized. Task remains wait — the two admissions are owned by railiance-platform and approval-engine respectively, and live provisioning proof cannot begin until both land. Still no secret read and no production resource changed.

2026-09-08, second pass. Custody and the human callback are still owed, but one part of this task was ours all along and was not built: the task requires proving "live JWKS verification and denied excess scopes without logging values", and there was no way to do that except by hand, against production, at the moment custody lands — which is the worst time to be improvising a check.

Shipped keycape verify-client (src/internal/authclient/verify.go, documented in docs/native-authentication.md). Per registration it verifies discovery origin, the client_credentials exchange and its RS256 signature against the deployed JWKS, exact sub/tenant/roles/principal_type, that every -deny-scope is refused, and that the token carries no scope that was not requested — the last being a gap the caller commands do not cover, since they prove requested scopes were granted and not that nothing extra came back. Failures name the claim, never the observed value, and nothing is written to disk, so it is safe to run against production. The exact invocation for each of the two clients is now recorded in the verification: block of docs/approval-engine-provisioning-request.yaml, so admission hands back a command rather than a description.

Tests: src/internal/authclient/verify_test.go covers the passing case, an over-broad registration, a live predecessor secret, an identical "rotation" and output non-disclosure. Verified with teeth — neutering mustFail makes the suite fail rather than pass silently.

Task stays wait. What is owed from elsewhere is unchanged and unreduced: the two secret values through an admitted custody path, and the exact human client_id and callback URI. Nothing here provisions anything.

2026-09-08 attended upstream issuer proof — T02 return

The user explicitly admitted the prepared temporary probe. At 21:44:44 UTC its actual Authelia authorization-code exchange verified the signed issuer https://auth.coulomb.social, including signature, keycape audience, validity window and browser-bound nonce. The pinned Job exited 0. No token or user claim was retained, and no downstream credential was issued.

All five temporary resources and the Pod were removed with scoped cleanup; KeyCape Deployment and config Secret metadata remained unchanged. Receipt: docs/evidence/2026-09-08-upstream-issuer-live-proof.json.

This closes the actual-token issuer observation gate. T02 remains wait for the configuration owner to ensure authelia.issuer is pinned to the verified HTTPS value, named CCR-2026-0017/0018 reviews, custody delivery and compatible rollout. The diagnostic did not prove downstream KeyCape MFA/application login and did not activate custody. Do not repeat discovery or request another observation unless the provider/configuration or proof context changes.

2026-09-09 configuration-owner return: NetKingdom's exercised, revision-guarded issuer-only helper inserted authelia.issuer: https://auth.coulomb.social into sso/keycape-config; resourceVersion 51346058 -> 58713343. Independent readback matches. Every other configuration byte and Secret data entry, including the private key, was preserved. Thirteen tests passed. Receipt: docs/evidence/2026-09-09-upstream-issuer-pin.json.

The stored issuer configuration prerequisite is closed. No process restart, image rollout, custody activation or downstream login proof occurred. T02 stays wait for the named CCR reviews, attended custody and compatible rollout. The single-instance replacement and existing-human-login checks remain mandatory.

2026-09-09 completion: both named CCR reviews are recorded. Verifier-side custody, ESO delivery and the compatible pinned image/config are now live. Both service clients passed the pinned verifier plus independent live signature and exact claim/lifetime checks; wrong-secret and excess-scope requests were rejected. The existing OpenBao human login passed before and after replacement; each attended session self-revoked. Receipt: docs/evidence/2026-09-09-keycape-verifier-admission.json.

The deployment owner exercised compatible rollback and version-preserving resume. The final helper checks containerd imageID against the pinned manifest and uses the existing 30-second future-iat bound without extending token expiry. The pinned native verifier runs in the contained owner process because workload network policy excludes public issuer HTTPS. No network grant was broadened.

Live residual ownership remains KEY-WP-0013-T05 for the approval UI callback/MFA; RPF-WP-0035-T05 for separate client-side delivery; AUDIT-WP-0009-T09 for audit custody; APPROVAL-WP-0002 and SECRETS-WP-0009-T03 for end-to-end claim/consume, expiry/revocation and native delivery. Natural JWT expiry and real predecessor rotation were not exercised by initial provisioning.

Reconcile tenant vocabularies across approval layers

id: KEY-WP-0013-T03
status: done
priority: high
state_hub_task_id: "e98da2eb-1f05-5c7f-bc84-711fa38b8c4a"

Source: glas-harness inbox message 356f6977-d361-4e3b-83ab-b2c7f4759286 (GLAS-WP-0015), which asks for the exact store tenant, JWT tenant, CheckRequest tenant, any permitted mapping and wrong-tenant denial evidence.

Published docs/tenant-claim-contract.md. The KeyCape-owned JWT tenant for all four reviewed service registrations is tenant:coulomb, bound at registration and required by config validation. Approval store platform and policy tenant:platform are owned by approval-engine and flex-auth; KeyCape performs no normalization or aliasing, so exact comparison does not match today. No mapping was invented and no live registration or policy subject was changed — the two admissible resolutions are recorded for the owning parties to decide.

Added src/internal/server/oidc/tenant_test.go: request-supplied tenant and tenant_hint cannot alter the claim; two registrations never carry each other's tenant (the wrong-tenant denial basis); human tokens default to tenant:coulomb rather than an empty claim. Local issuance proof only, not live-rollout evidence.

Align approval registrations to tenant:platform

id: KEY-WP-0013-T04
status: done
priority: high
state_hub_task_id: "d93e21cc-a422-5e78-981f-9c00f3161375"

Source: glas-harness inbox message f487c63a-dd7e-4ad8-9188-eec9fbea59c6, operator decision 5ed3fb35-eca9-413a-82b9-95171ba85bf6 ("Use tenant:platform for the Glas approval dependency chain", verified resolved in the hub). This closed resolution 2 of the two options recorded in KEY-WP-0013-T03.

Changed the tenant field on exactly secrets-engine-approval and approval-engine-operator in config/service-clients.example.yaml and the two matching entries in docs/approval-engine-provisioning-request.yaml to tenant:platform, each annotated with the decision id. codex-railiance-platform, secrets-engine-openbao and the human directory default keep tenant:coulomb. No audience, scope, subject, role, lifetime or MFA change; no cross-tenant grant.

Evidence: TestApprovalClientIssuesExactPlatformTenantAndRejectsAliases (exact tenant:platform with aud=approval-engine even when the caller requests platform, tenant:coulomb or TENANT:PLATFORM), TestUnrelatedServiceClientKeepsCoulombTenant, and TestServiceRegistrationTenantsAreExactPerDecision, which pins every reviewed client's tenant against the real fixture so a reintroduced alias fails the build. Full go test ./... and go vet ./... pass. Choice only — live provisioning and the other admission gates remain with KEY-WP-0013-T02.

2026-09-09 observation, read-only. Custody has been admitted since the 2026-09-08 record and the deployment now carries the pieces T02 was waiting for: sso/keycape-config registers secrets-engine-approval and approval-engine-operator alongside the existing clients; the secrets keycape-secrets-engine-approval-client and keycape-approval-engine-operator-client exist in the namespace; both KEYCAPE_SECRETS_ENGINE_APPROVAL_CLIENT_SECRET and KEYCAPE_APPROVAL_ENGINE_OPERATOR_CLIENT_SECRET are wired into the pod; and the image is pinned by digest to sha256:7ff54c54e63ee172ae9e6e7fd2da96e427352f712343d74626ee6fe0f6f82611, the candidate T06 published.

What that does and does not establish. The live issuer passes every conformance check that needs no credential — it advertises itself, offers the profile authorization surface, publishes usable RS256 keys and advertises no excluded grant (src/tests/conformance, run against https://kc.coulomb.social). It does not establish the claim contract: subject, tenant, roles, scopes, lifetime and excess-scope denial per client are exactly what keycape verify-client exists to prove, and that needs the client secret in the environment.

Deliberately not done here. Reading either secret to run the verifier is client-side retrieval, which the provisioning packet records as not admitted (custody_return.scope: verifier-side copies only). So the remaining proof is an attended operator action, not something to take by reading the secret. T02 stays wait on that run, not on custody.

Correction, same day. The refusal above was right; the conclusion drawn from it was not. The attended run had already happened, on 2026-09-09T00:10Z, and its receipt is committed in this repository at docs/evidence/2026-09-09-keycape-verifier-admission.json. Per client — both secrets-engine-approval and approval-engine-operator — live_jwks_signature_verified: true, exact_claims_verified: true, excess_scope_denied: true, wrong_secret_denied: true, lifetime_seconds: 900, maximum_future_iat_seconds: 30, pinned_artifact_verifier_passed: true, verifier_location: "attended owner process". credential_values_emitted: false and client_side_read_admitted: false throughout, so it was run the admitted way. The claim contract is established and T02's status: done is correct; it does not revert to wait.

The reasoning error is worth naming because it is the third of its kind here in two days: "not admitted for me" was read as "not done by anyone", without checking docs/evidence/. The preceding paragraph's read-only observations are sound and its restraint about not reading the secret is exactly right — only the final sentence was wrong, and it is retained above rather than deleted so the correction has something to point at.

What the receipt itself declines to claim, which is the honest residual and matches this task's earlier record: real_predecessor_rotation_tested: false, observed_wall_clock_expiry: false, and under limits, actual_predecessor_rotation_observed: false and wall_clock_jwt_expiry_observed: false. Natural expiry and a real predecessor rotation were not exercised by initial provisioning and are not claimed by anyone. Predecessor rejection is implemented and unit-tested in keycape verify-client; it has not been run against a real rotation, which is KEY-WP-0014-T04's territory and still has no admitted execution authority.

Independently confirmed by the custody owner, 2026-09-09 (railiance-platform ae6ff4bc, 570e6746). They reached the same reading from their own side and add one datum this record did not carry: human_client_consume_denied: true for both clients, alongside the signature, exact-claim, lifetime, excess-scope and wrong-secret results. They confirm the verifier ran twice — once during activation and again after rollout — at deployment generation 38, single ready replica, signing key unchanged, no credential values emitted, and state that T02 can be closed against that receipt rather than against a run KeyCape cannot make.

They also correct one thing in our framing, and they are right: the packet says client-side retrieval is unadmitted, which remains true, but the attended operator path is not a client-side read and never required one. The two are distinct and this task had been treating them as the same constraint.

Do not cite this receipt as rotation evidence. Both owners now state the same two gaps independently: real_predecessor_rotation_tested: false and observed_wall_clock_expiry: false. Neither is a T02 acceptance criterion, and neither is closed by anything recorded here — see KEY-WP-0014-T04.

Client-side retrieval is prepared but still unadmitted. CCR-2026-0019 (secrets-engine reader) and CCR-2026-0020 (approval-engine-operator reader) are in_flight under RPF-WP-0035-T06. 0020 has no named presenting actor in any owner source, and railiance-platform left it undetermined rather than guessing — correctly. KeyCape's view, asked for as the issuer of the identity and recorded in docs/approval-engine-provisioning-request.yaml, is that the registration as issued carries both approval:create and approval:approve, so a single presenter can create and then approve the same entry. That is a separation-of-duties question about who may hold the credential, not a defect in the token: KeyCape issues the grants approval-engine requested. The decision is approval-engine's and the doctrine question is gate-house's.

Assign and register the human approver browser client

id: KEY-WP-0013-T05
status: wait
priority: high
assignee: the-custodian
blocking_reason: "Client ID and deployed callback pending INFD-WP-0001-T07 from informed-decision. The tenant blocker is resolved in code."
state_hub_task_id: "9a782909-91db-59fa-aae7-83766f4fbb0d"

Own the residual human registration separately from service-client T02. Reuse an existing accepted UI if available; do not invent a callback on approval-engine. Require public S256 PKCE, exact redirect, MFA, approval:approve without consume, and a real human access-token proof. No service credential substitutes for this. HFACT-WP-0001-T03 consumes the acceptance where a human approval is required.

2026-09-09. The owner exists: informed-decision (hub repo cf4c7da8) claims the approver surface and owns the two strings. approval-engine was right that a bearer-only resource server never owned them. Both wrote in asking to be told early about problems with the registration shape rather than at handover, so their requested shape was checked against the source rather than agreed on paper. Three results.

Scope gap — accepted, theirs was right. [openid, approval:approve] cannot render a decision: GET /v1/approvals/{id} and /claim both need approval:read, so the surface could submit an entry it was never able to display. Published [openid, approval:read, approval:approve] in docs/approval-engine-auth-contract.md and the provisioning packet. Reading through a service identity was the alternative and is worse: it weakens the evidence-of-what-this-person-saw claim the component exists to make. approval:consume stays excluded.

Assurance shape — published, and a defect fixed. Both asked for a documented shape; KeyCape already emitted one, so it is written down rather than renegotiated: level (aal1|aal2, ~acr), methods (~amr), mfa, source, at. Writing it down surfaced that at was the token mint time, not the authentication time. Those differ by hours whenever a browser session is reused, and approval-engine persists this object verbatim as the only downstream record that MFA happened — so a stored approval could have evidenced MFA at a moment the person proved nothing. PKCESession.AuthTime now carries the original login instant through session reuse, with mint time as the fallback for sessions predating the field. Covered by src/internal/server/oidc/assurance_time_test.go.

Blocker found before anyone built on it — a human token cannot carry tenant:platform. effectiveTenant resolves the human tenant from the directory user, not the client registration, and no adapter populates domain.User.Tenant, so every human token defaults to tenant:coulomb. The per-client tenant field that carries tenant:platform on the two service clients is read only on the client_credentials path. approval-engine compares tenant by exact string equality and pins near-miss spellings as refused, so an approver token issued today would be rejected — and it would present as a failed approval, not as a registration defect.

Two resolutions, sent to both owners (67132ddc, a6a070a1, pointer 42d435e8) rather than chosen here, because the choice decides what a human's tenant means: (1) directory-sourced, approvers carry tenant:platform on their LLDAP record — keeps tenant a property of the person, needs a directory attribute and an owner, and changes those users everywhere; (2) registration-bound and fail-closed, symmetric with the service clients and with decision 5ed3fb35-eca9-413a-82b9-95171ba85bf6 — defensible only because registrations are static and deployment-owned, since dynamic registration is excluded by design. KeyCape leans to (2) and deliberately implemented neither: (1) is a directory-ownership question and (2) writes a cross-tenant capability into the issuer.

Tenant blocker resolved in code, 2026-09-09. On review the choice did not have to be made to unblock: the two resolutions differ in where a human's tenant comes from, and an implementation exists that is correct under either. A client registration may now declare a tenant, and humanTenant() resolves it by four rules — no declaration keeps the directory answer unchanged; a declared zone applies when the directory has placed the user nowhere; agreement passes; and a declared zone that conflicts with a directory assignment refuses issuance (403, error_type: tenant_binding) rather than relabelling the user.

That refusal is the whole design. A registration can bind a zone for unplaced users and can never move a placed one, so option (2) is available now without writing a general cross-tenant override into the issuer, and if the owners prefer option (1) the same code stops supplying the zone and starts enforcing agreement with it — no second migration and no window where a stale registration silently wins. It is safe only because registrations are static and deployment-owned; docs/tenant-claim-contract.md records that this rule must be revisited if dynamic client registration is ever admitted.

Evidence: src/internal/server/oidc/human_tenant_test.go, four cases including the relabel refusal. Verified with teeth — neutering the conflict check makes TestHumanTenantRefusesToRelabelAPlacedUser fail rather than pass silently. docs/tenant-claim-contract.md carries the resolution table, docs/approval-engine-auth-contract.md states the requirement on the approver client, and the provisioning packet now declares tenant: tenant:platform.

Task stays wait on one thing only: client_id and callback URI from INFD-WP-0001-T07, once informed-decision has a deployed origin. The owners were asked which resolution they prefer and have not answered; that answer is no longer blocking, and this implementation is compatible with either.

Make negative rollout evidence discriminate actual issuer refusal

id: KEY-WP-0013-T06
status: done
priority: high
assignee: the-custodian
state_hub_task_id: "65132e1d-10db-5915-a664-83beaf30365a"

Critical-path review found mustFail accepted any Exchange error: timeout, HTTP 5xx, invalid token or JWKS failure could falsely prove excess-scope denial or predecessor rejection after a successful positive exchange. Preserve a bounded typed provider refusal, require the exact token endpoint/status/error/feature, and prove the checker rejects unrelated failures without exposing provider bodies. Publish the verified image candidate and return its immutable digest to T02.

Platform's 2026-09-08 return is RPF-WP-0035-T05 and proposed CCR-2026-0017/0018. The custody field is CLIENT_SECRET; Kubernetes key client-secret and both env names remain as requested. These records cover verifier-side delivery only. Owner approval, client-side retrieval and the actual upstream ID-token issuer proof remain distinct gates. Public discovery currently advertises https://auth.coulomb.social; that alone is not the signed-token observation.

T06 completion: full Go suite and vet passed; published code dcebd46 and pulled the image by digest sha256:7ff54c54e63ee172ae9e6e7fd2da96e427352f712343d74626ee6fe0f6f82611. Container keycape verify-client --help confirms the command is present. docs/approval-clients-rollout.md and its proposed deployment patch record configuration/issuer, first-provision, single-instance rollout, acceptance and rollback. This closes verifier preparation only; T02 and T05 retain the explicit live dependencies.

Prepare a bounded upstream issuer observation before client rollout

id: KEY-WP-0013-T07
status: done
priority: high
assignee: the-custodian
state_hub_task_id: "62bc6d8e-dbb2-57b6-a30b-472ffd06b497"

2026-09-08: T02's actual upstream signed-token issuer gate had no executable observation path. A downstream OpenBao/KeyCape login cannot return the upstream Authelia token; it remains inside the adapter. Prepare probe-upstream-issuer and an exact-state temporary route so one attended flow can be verified before changing the normal KeyCape Deployment or its configuration.

Acceptance: signed issuer/audience/time/nonce proof without token or user-claim output; browser/state binding and one-shot refusal; finite issuer allowlist; ten-minute bound; no downstream credential; current Traefik route isolation; immutable image; reviewed temporary Job/config projection, network policies and owner-reference cleanup. Normal callbacks and the production issuer stay on the existing Deployment. The probe mounts only config.yaml, not key.pem, and has no Kubernetes API token. That file contains existing credential data; its use by the temporary diagnostic needs deployment-owner admission.

Source tests, image and deployment packet close this preparation task. The attended live receipt and issuer pin remain in T02, alongside the named CCR reviews and custody/rollout acceptance. Preparing the diagnostic does not approve CCR-2026-0017/0018 or close any live factory gate.

T07 preparation complete: source 6f33abd, immutable image sha256:0c85ed377cae7ae6ca5b5c56b1a52930e706b3cb78009747e42f551e869a22e4. Complete Go race suite and vet passed; five renderer/collector checks, seven real Traefik 3.6.7 route cases and Railiance server dry-run passed. The packaged command ran as UID 65534 with no network and a read-only filesystem and produced the expected bounded idle-timeout receipt. See docs/upstream-issuer-proof.md and docs/evidence/upstream-issuer-probe.json. T02 retains the live proof and configuration-owner admission; no production resource or custody value changed.