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

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

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 -- <reviewed-command>`
+   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.

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.