From e534e1d5e8095afed718baf490c09c5144160b92 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 8 Sep 2026 17:03:59 +0200 Subject: [PATCH] docs(keycape): prepare pinned approval-client rollout and recovery Assistant: codex Assistant-Model: gpt-5.6-luna Assistant-Session: 01a07ff8-19d0-7820-b4d0-1353833cb7fc --- docs/approval-clients-deployment.patch.yaml | 27 ++++++ docs/approval-clients-rollout.md | 86 +++++++++++++++++++ ...-0013-approval-engine-resource-audience.md | 4 +- 3 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 docs/approval-clients-deployment.patch.yaml create mode 100644 docs/approval-clients-rollout.md diff --git a/docs/approval-clients-deployment.patch.yaml b/docs/approval-clients-deployment.patch.yaml new file mode 100644 index 0000000..f42bfba --- /dev/null +++ b/docs/approval-clients-deployment.patch.yaml @@ -0,0 +1,27 @@ +# Proposed strategic merge patch for net-kingdom's sso/keycape Deployment. +# Apply only after the admission gates in approval-clients-rollout.md pass. +spec: + replicas: 1 + strategy: + type: Recreate + rollingUpdate: null + template: + spec: + containers: + - name: keycape + image: forgejo.coulomb.social/coulomb/key-cape@sha256:7ff54c54e63ee172ae9e6e7fd2da96e427352f712343d74626ee6fe0f6f82611 + env: + - name: KEYCAPE_SECRETS_ENGINE_APPROVAL_CLIENT_SECRET + valueFrom: + secretKeyRef: + name: keycape-secrets-engine-approval-client + key: client-secret + - name: KEYCAPE_APPROVAL_ENGINE_OPERATOR_CLIENT_SECRET + valueFrom: + secretKeyRef: + name: keycape-approval-engine-operator-client + key: client-secret + readinessProbe: + httpGet: + path: /readyz + port: 8080 diff --git a/docs/approval-clients-rollout.md b/docs/approval-clients-rollout.md new file mode 100644 index 0000000..659070b --- /dev/null +++ b/docs/approval-clients-rollout.md @@ -0,0 +1,86 @@ +# Approval service clients: prepared rollout + +`KEY-WP-0013-T02/T06`, 2026-09-08. Prepared candidate; **not deployed**. + +The implementation and verification correction are published at `dcebd46`. +Forgejo's image is `main-dcebd46`, with immutable manifest digest +`sha256:7ff54c54e63ee172ae9e6e7fd2da96e427352f712343d74626ee6fe0f6f82611`. +The complete Go suite and `go vet ./...` passed. The registry image was pulled +by digest and its `/keycape verify-client --help` command enumerated the expected +verification options (the Go flag help path exits 1). The verifier is a keycape +subcommand, not a separate `/verify-client` executable. No live credential was +used in these checks. + +Negative evidence now requires the exact token endpoint, issuer error and +feature: scope rejection is HTTP 400 / `invalid_profile_usage` / `scope`; +predecessor rejection is HTTP 401 / `invalid_profile_usage` / `Authorization`. +A timeout, server error, invalid token, JWKS failure or unrelated refusal fails +verification. Provider response bodies and tokens are never printed. + +## Admission inputs + +1. Platform `CCR-2026-0017` and `CCR-2026-0018` remain proposed. Their named + platform-operator and key-cape-owner reviews precede any activation. + [provisioning request](approval-engine-provisioning-request.yaml) records the + exact paths, `CLIENT_SECRET` field and Kubernetes/env mappings. +2. NetKingdom must observe and verify the **actual signed upstream ID token** + from the existing human flow, recording only the issuer claim and proof + metadata. Pin that exact value in `authelia.issuer` through the configuration + owner's contained path. Public discovery currently advertises + `https://auth.coulomb.social`; discovery alone does not satisfy this gate. + Preserve the existing signing key and client registrations. Prove an existing + human login before and after cutover; this image also includes stricter + authorization-code redirect and grant binding. +3. The platform-owned attended first-provision command uses only + `warden access openbao-platform-admin-login --exec -- ` + with its unique metadata-only receipt. It must follow the two CCRs and the + platform rollout document. Do not execute the child directly. The unrelated + interim credential proxy's explicit policy 403 remains WARDEN-WP-0039-T03; + an outage fallback is not permission to get credentials for this rollout. + +## Prepared deployment change + +[approval-clients-deployment.patch.yaml](approval-clients-deployment.patch.yaml) +is a strategic merge patch for `sso/keycape`, whose deployment source remains +`net-kingdom/sso-mfa/k8s/keycape/deployment.yaml`. Transfer the reviewed changes +into that owning source at the admitted cutover; this file is a preparation, +not a second deployment authority. + +It pins the image, adds the two exact Secret references and uses `/readyz` for +traffic readiness while retaining `/healthz` for liveness. `Recreate` ensures +one issuer instance during replacement: [operations.md](operations.md) states +that login sessions and authorization codes are process-local. The old manifest's +default rolling surge can briefly create two instances. Expect a short login +interruption and loss of in-flight login sessions during replacement. + +Apply the platform policies/roles, CAS=0 initial custody, two stores and two +ExternalSecrets in their owner-prescribed order; require Valid/SecretSynced +before deploying the reading image and updated client config together. Do not +pre-create ESO-owned Secrets. A dry-run of this patch proves API acceptance of +the object shape only; it cannot prove the referenced Secrets or configuration. + +## Acceptance and rollback + +Run the two `verify-client` commands from the provisioning request through the +admitted protected delivery. In addition to the tool's checked signature, +issuer, audience, subject, tenant, scopes and required roles, record independent +verification of the exact role set and `exp - iat = 900`: the tool's +`expect-roles` checks inclusion and does not itself establish the 15-minute +lifetime. Initial provisioning has no real predecessor to revoke; test a wrong +secret and retain predecessor rejection for an actual subsequent rotation. +Retain expiry/revocation and excessive-scope evidence, and platform cross-path, +wrong-service-account, outside-namespace and parent-listing denials. + +Before mutation the deployment/configuration owner retains the previous image, +configuration revision and Secret metadata through its protected recovery path. +On failed readiness or existing-human-login regression, restore that compatible +configuration/image pair (`main-153258b` is the observed prior image), then +follow the platform document's ExternalSecret/policy rollback. An image-only +revert does not restore the changed client configuration. Keep custody versions +until registrations are explicitly disabled; never destroy as incidental cleanup. + +These CCRs supply **verifier-side copies only**. Client-side read lanes, the +approval audit sender credential and live claim/consume proof remain open in +RPF-WP-0035-T05, AUDIT-WP-0009-T09, APPROVAL-WP-0002 and GLAS-WP-0015's +existing coordination chain. The human UI's real callback and MFA proof remain +KEY-WP-0013-T05; they do not block these independent service registrations. diff --git a/workplans/KEY-WP-0013-approval-engine-resource-audience.md b/workplans/KEY-WP-0013-approval-engine-resource-audience.md index 8b267df..6c24605 100644 --- a/workplans/KEY-WP-0013-approval-engine-resource-audience.md +++ b/workplans/KEY-WP-0013-approval-engine-resource-audience.md @@ -191,7 +191,7 @@ HFACT-WP-0001-T03 consumes the acceptance where a human approval is required. ```task id: KEY-WP-0013-T06 -status: progress +status: done priority: high assignee: the-custodian ``` @@ -209,3 +209,5 @@ 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.