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

Reassess SCOPE against the current revision

Browse source 
SCOPE.md declared itself reviewed against b989de4, 63 commits behind, with its
limits kept current by appending to bullets. That works until the header asserts
a review date that no longer describes what was reviewed -- the drift this file
exists to prevent, in the document whose only job is to be accurate.

Every claim was rechecked against source rather than carried forward: routes from
the mux registrations, subcommands from the dispatch, flags from the flag sets,
claim behaviour from token.go and userinfo.go. Three were false. Caller commands
omitted verify-client, the container was said to package only keycape (untrue
since KEY-WP-0026), and the issuer API row omitted /readyz. Capabilities that had
reached SCOPE only piecemeal are now in the capability table: the
authorization-code bindings, upstream token verification, readiness and drain, the
human tenant rules, authentication-time assurance, the shared verifier.

The substantive addition is a distinction SCOPE did not draw: source behaviour
and deployed behaviour are different claims with different evidence -- the test
suite and harness runs for one, committed receipts in docs/evidence/ for the
other. What is proven live is narrower and now stated exactly, including that the
issuer pin's pre-pin state did not match, so that risk was real rather than
hypothetical, and that the deployed image predates this revision so several
described behaviours are running nowhere yet.

That distinction is the fix for a repeated error: four times in two days a claim
about current state was written from a workplan paragraph or a partial view
instead of the authoritative artifact. A SCOPE that does not separate "the code
does this" from "this is running" invites the same mistake from the next reader.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NV9oijZukGyGbRQGGKnK4P

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 713576@bnt-lap001
Assistant-Session: 384c511d-9bce-4cb8-a676-2aef6c0c8df6
This commit is contained in:
tegwick 2026-09-09 20:06:38 +02:00
parent 7a73352368
commit d6ecb2b7aa
3 changed files with 210 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

49
SCOPE.md
View file

@ -1,6 +1,8 @@
# SCOPE
Reviewed 2026-09-05 against source revision `b989de4`.
Reviewed 2026-09-09 against source revision `5ae80d3`. The preceding review was
2026-09-05 against `b989de4`; the [reassessment](history/2026-09-09-scope-reassessment.md)
records what changed and how each claim below was checked.
## Purpose and boundary
@ -20,11 +22,11 @@ Keycloak interchangeability are not established.
| Surface | What the current source provides |
| --- | --- |
| Issuer HTTP API | Discovery, `/authorize` and its callback/registration-return routes, `/token`, `/jwks`, `/userinfo`, local `/logout`, and `/healthz`. |
| Human authentication | Authorization code with S256 PKCE, exact registered redirects, scope allow-lists, Authelia login, privacyIDEA MFA challenges, client-specific assurance requirements, browser session reuse, step-up/fresh-login handling, and configured registration/enrollment handoffs. |
| Issuer HTTP API | Discovery, `/authorize` and its callback/registration-return routes, `/token`, `/jwks`, `/userinfo`, local `/logout`, `/healthz` (liveness, probes nothing) and `/readyz` (probes LLDAP by bind, Authelia and privacyIDEA). |
| Human authentication | Authorization code with S256 PKCE, exact registered redirects, scope allow-lists, Authelia login, privacyIDEA MFA challenges, client-specific assurance requirements, browser session reuse, step-up/fresh-login handling, and configured registration/enrollment handoffs. The exchange is bound to the redirect URI the code was issued for, refused for clients not registered for the grant, authenticated for confidential clients, and the code is consumed atomically so exactly one exchange can succeed. Upstream Authelia ID tokens are verified — signature against the provider's published keys, expected issuer, own client ID in the audience, validity window — failing closed and independently of transport. |
| Service authentication | Static confidential `client_credentials` clients authenticated with form-encoded `client_secret_basic`; configured subject, tenant, roles, scopes and per-client token lifetime. Secrets are resolved from environment references at startup. |
| Tokens and identity | Locally signed RS256 JWTs; configurable access-token resource audience while ID tokens retain the client audience; human/service principal types, tenant, groups, roles, scope and assurance claims. UserInfo resolves canonical directory subjects and filters profile/email/groups by scope. |
| Caller commands | `keycape login` for public-client browser PKCE login and `keycape service-token` for service exchange. HTTPS discovery/JWKS verification and private JSON token-file delivery outside Git; no token output on stdout. |
| Tokens and identity | Locally signed RS256 JWTs; configurable access-token resource audience while ID tokens retain the client audience; human/service principal types, tenant, groups, roles, scope and assurance claims. A service tenant is bound at registration; a human tenant comes from the directory, or from a client-declared zone when the directory has placed the user nowhere, and issuance is refused when the two conflict. `assurance.at` is the authentication time, not the mint time. UserInfo verifies algorithm, issuer and access-token purpose, resolves canonical directory subjects, and filters profile/email/groups by scope. |
| Caller commands | `keycape login` for public-client browser PKCE login, `keycape service-token` for service exchange, and `keycape verify-client` to check a live registration's subject, tenant, roles, lifetime and scope refusals without emitting values. HTTPS discovery/JWKS verification and private JSON token-file delivery outside Git; no token output on stdout. |
| Validation and migration | Canonical snapshot checks; deterministic LLDAP user/group/membership export that records whether it enumerated the whole directory; basic Keycloak realm JSON; LDIF generation for OpenLDAP, 389 Directory Server and AD targets. These generate artifacts rather than execute a complete migration. |
| Diagnostics and packaging | Structured authentication/enforcement/migration events, liveness and dependency-probing readiness endpoints, Go build/test/vet targets, a container packaging the issuer and all four migration/validation binaries, and development/CI scaffolding. |
@ -92,6 +94,23 @@ Keycloak interchangeability are not established.
unexercised, and credential/MFA migration is not supplied at all, so no harness
can establish it. Subject continuity is explicitly not preserved: the canonical
ID survives as an attribute while Keycloak mints its own `sub`.
- **Source behaviour and deployed behaviour are not the same claim, and this
document describes source.** Everything above is what the code in this revision
does, established by 390 Go tests across 23 packages plus the harness runs
named. What has been demonstrated against the live deployment is narrower and is
recorded as committed receipts in `docs/evidence/`: the upstream issuer was
probed and then pinned in `sso/keycape-config`
(`2026-09-09-upstream-issuer-pin.json` — the pre-pin state did **not** match, so
this was a real fix), and both approval service clients were verified live in an
attended owner process, showing JWKS signature verification, exact claims,
excess-scope and wrong-secret denial at a 900s lifetime
(`2026-09-09-keycape-verifier-admission.json`). Those receipts also decline what
they did not test: no real predecessor rotation and no observed wall-clock
expiry. The deployed image is older than this revision, so the
authorization-code bindings, upstream verification, readiness, graceful
shutdown and the two tenant-related changes are **not yet running anywhere** —
see [operations](docs/operations.md), "Unreleased fail-closed startup changes".
Read `docs/evidence/` before describing any of this as proven live.
- The server listens on HTTP; HTTPS termination is deployment-owned.
`/healthz` is liveness and probes nothing; `/readyz` probes LLDAP, Authelia and
privacyIDEA and gates traffic. `SIGTERM` drains in-flight requests for 15s.
@ -124,23 +143,31 @@ or factor enrollment themselves.
Run the issuer with `keycape --config PATH`; `keycape server` and
`keycape migrate` are not implemented subcommands. Caller commands are
`keycape login` and `keycape service-token`.
`keycape login`, `keycape service-token` and `keycape verify-client`.
Separate binaries under `src/cmd/` are `validator`, `lldap-export`,
`keycape-to-keycloak`, and `lldap-to-ldap`. `make -C src build` places binaries in
root `bin/`; the container packages only `keycape`. Tests live under `src/tests/`
and alongside packages in `src/internal/`.
root `bin/` — the root `make build` only compiles and installs nothing. The
container packages all five binaries with the issuer as its entrypoint
(KEY-WP-0026). Tests live under `src/tests/` and alongside packages in
`src/internal/`.
`make test`, `make lint` (Go vet), `make build`, and `make contract-test` are the
root checks. The capability-contract check requires the sibling NetKingdom
validator. These checks passed for the reviewed revision in the preceding
implementation session; the scope assessment is a source/documentation review.
implementation session and were rerun for this one; `src/tests/conformance` is
additionally runnable against a live issuer via `KEYCAPE_TEST_ISSUER` and skips
when it is unset. The scope assessment is a source review: it establishes what
the code does, not what any deployment is currently running.
Use this repo for its bounded issuer, caller JWT acquisition, identity adapters
and migration preparation. Consult [INTENT.md](INTENT.md) for the architectural
target, [native authentication](docs/native-authentication.md) for caller
constraints, and the [scope/intent assessment](history/2026-09-05-011726-scope-intent-assessment.md)
for evidence, priorities and remaining gaps.
constraints, [operations](docs/operations.md) for the supported topology and the
unreleased fail-closed changes, `docs/evidence/` for what has been proven against
the live deployment, and the [reassessment](history/2026-09-09-scope-reassessment.md)
— with the [2026-09-05 assessment](history/2026-09-05-011726-scope-intent-assessment.md)
it supersedes — for evidence, priorities and remaining gaps.
## Provided capabilities