coulomb/key-cape
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(keycape): prepare pinned approval-client rollout and recovery

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-luna
Assistant-Session: 01a07ff8-19d0-7820-b4d0-1353833cb7fc
This commit is contained in:
tegwick 2026-09-08 17:03:59 +02:00
parent dcebd46fa6
commit e534e1d5e8
3 changed files with 116 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

27
docs/approval-clients-deployment.patch.yaml Normal file
View file

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

86
docs/approval-clients-rollout.md Normal file
View file

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

4
workplans/KEY-WP-0013-approval-engine-resource-audience.md
View file

@ -191,7 +191,7 @@ HFACT-WP-0001-T03 consumes the acceptance where a human approval is required.
```task ```task
id: KEY-WP-0013-T06 id: KEY-WP-0013-T06
status: progress status: done
priority: high priority: high
assignee: the-custodian 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 Owner approval, client-side retrieval and the actual upstream ID-token issuer
proof remain distinct gates. Public discovery currently advertises proof remain distinct gates. Public discovery currently advertises
`https://auth.coulomb.social`; that alone is not the signed-token observation. `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.