Document actual capabilities and assess scope against intent
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a06e87-e039-7ed2-b85c-20ad37f8a21b
This commit is contained in:
parent
b989de4e90
commit
30fa8570aa
3 changed files with 394 additions and 89 deletions
173
SCOPE.md
173
SCOPE.md
|
|
@ -1,115 +1,110 @@
|
|||
# SCOPE
|
||||
|
||||
> This file helps you quickly understand what this repository is about,
|
||||
> when it is relevant, and when it is not.
|
||||
> It is intentionally lightweight and may be incomplete.
|
||||
Reviewed 2026-09-05 against source revision `b989de4`.
|
||||
|
||||
---
|
||||
## Purpose and boundary
|
||||
|
||||
## One-liner
|
||||
KeyCape is Go identity **Tooling** for NetKingdom's lightweight IAM deployment.
|
||||
It runs its own OIDC-style issuer, uses Authelia for upstream browser
|
||||
authentication, reads identities from LLDAP, and delegates factor checks to
|
||||
privacyIDEA. It also provides caller authentication commands, directory snapshot
|
||||
validation, and migration artifact generators.
|
||||
|
||||
Lightweight IAM implementation of the NetKingdom IAM Profile — orchestrates Authelia, LLDAP, and privacyIDEA to provide OIDC/PKCE authentication as a drop-in Keycloak alternative.
|
||||
It issues identity, role, scope and assurance claims. Resource authorization
|
||||
belongs to access-engine and consuming services; secret custody and OpenBao
|
||||
policy/token enforcement belong to their platform owners. The implemented subset
|
||||
supports NetKingdom integrations, but complete profile conformance and drop-in
|
||||
Keycloak interchangeability are not established.
|
||||
|
||||
---
|
||||
## Implemented capabilities
|
||||
|
||||
## Core Idea
|
||||
| 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. |
|
||||
| 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. |
|
||||
| Validation and migration | Canonical snapshot checks; LLDAP user/group/membership export; 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, a process health response, Go build/test/vet targets, a container containing the KeyCape binary, and development/CI scaffolding. |
|
||||
|
||||
NetKingdom applications target the "NetKingdom IAM Profile" — a versioned OIDC/PKCE contract. KeyCape implements that profile in lightweight mode (Authelia + LLDAP + privacyIDEA) with intentional constraints: no implicit flow, no wildcard redirects, no dynamic client registration. The same profile is implemented in expanded mode by Keycloak, so applications can migrate between modes without code changes.
|
||||
## Material limits
|
||||
|
||||
---
|
||||
- Client registrations, service secrets and the signing key are loaded at startup.
|
||||
Login, authorization and handoff state are process-local. There is no shared
|
||||
session store, general refresh-token flow, token introspection/revocation API,
|
||||
or automatic signing-key/client-secret rotation service. Logout clears the
|
||||
local KeyCape session, not every upstream or downstream session/token.
|
||||
- The optional tenant-engine `tenant_roles` adapter and handler support exist,
|
||||
but the server entry point does not configure them. That claim is not an
|
||||
enabled capability of the stock executable.
|
||||
- The Keycloak CLI exports users/groups through the basic transformer and has
|
||||
no client-list input. Library-level client mapping does not preserve the full
|
||||
current service-identity, audience, tenant/role, MFA and lifetime contract.
|
||||
Password and MFA credential migration is not supplied.
|
||||
- Snapshot validation is a limited Go rule set, not full machine-readable schema
|
||||
enforcement. The canonical YAML model and discovery metadata lag newer runtime
|
||||
capabilities. Protocol hardening gaps remain; see the assessment below.
|
||||
- Tests cover local handlers, adapters, transformations and CLI protocol behavior.
|
||||
They do not establish complete replacement against a running Keycloak/full-LDAP
|
||||
stack. The Scenario B/C shell harnesses are incomplete.
|
||||
- The server listens on HTTP; HTTPS termination is deployment-owned.
|
||||
`/healthz` reports process status without probing dependencies. Development
|
||||
Compose needs configuration/key material absent from the checkout. Production
|
||||
deployment and custody are external; a source implementation or example client
|
||||
fragment does not prove live registration or consumer cutover.
|
||||
- Approval-client provisioning, coordinated Qonto rotation, native consumer
|
||||
handoffs and notification receipt closure remain open in KEY-WP-0009/0013/0014.
|
||||
|
||||
## In Scope
|
||||
## Deliberate exclusions
|
||||
|
||||
- OIDC profile endpoints (discovery, authorization, token, JWKS, userinfo) per NetKingdom IAM Profile
|
||||
- Canonical identity model: users, groups, clients, MFA
|
||||
- Claim normalization across Authelia/LLDAP/privacyIDEA backend quirks
|
||||
- Profile enforcement with structured error taxonomy (no silent emulation of unsupported features)
|
||||
- Telemetry for unsupported-feature requests
|
||||
- Migration tooling: LLDAP export, Keycloak import, LDIF generation
|
||||
- LDAP schema validation
|
||||
- Full acceptance test suite (profile baseline, migration scenarios, negative tests)
|
||||
General-purpose IAM, dynamic client registration, implicit/password grants,
|
||||
wildcard redirects, arbitrary identity brokering, resource authorization policy,
|
||||
OpenBao credential custody, and Keycloak operations are outside this repository's
|
||||
ownership. Registration/enrollment handoffs do not implement user provisioning
|
||||
or factor enrollment themselves.
|
||||
|
||||
---
|
||||
## Entry points and verification
|
||||
|
||||
## Out of Scope
|
||||
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`.
|
||||
|
||||
- General-purpose IAM (profile-specific only; no out-of-profile extensions)
|
||||
- Dynamic client registration
|
||||
- Implicit flow
|
||||
- Wildcard redirect URIs
|
||||
- Identity brokering beyond OIDC
|
||||
- Keycloak operations (KeyCape is the lightweight alternative, not a Keycloak wrapper)
|
||||
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/`.
|
||||
|
||||
---
|
||||
`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.
|
||||
|
||||
## Relevant When
|
||||
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.
|
||||
|
||||
- Deploying NetKingdom IAM in lightweight mode (no Keycloak license/resources needed)
|
||||
- Applications need OIDC authentication with MFA in a constrained environment
|
||||
- Migrating from lightweight (KeyCape) to expanded (Keycloak) mode
|
||||
- Validating LDAP schema or generating migration artifacts
|
||||
|
||||
---
|
||||
|
||||
## Not Relevant When
|
||||
|
||||
- Expanded-mode Keycloak is already running (applications use the same profile; no code changes needed)
|
||||
- Need out-of-profile IAM features (dynamic client registration, implicit flow, etc.)
|
||||
- Non-NetKingdom OIDC deployments
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
- Status: stable (v0.1 complete)
|
||||
- Implementation: complete — all 23 workplan tasks implemented and tested
|
||||
- Stability: high — profile-constrained; no silent failures; acceptance tests passing
|
||||
- Usage: internal NetKingdom stack; replaces Keycloak in lightweight deployments
|
||||
|
||||
---
|
||||
|
||||
## How It Fits
|
||||
|
||||
- Upstream dependencies: Authelia (OIDC provider/sessions), LLDAP (identity directory), privacyIDEA (MFA)
|
||||
- Downstream consumers: all NetKingdom applications; net-kingdom (parent domain)
|
||||
- Often used with: net-kingdom (SSO/MFA workplan), railiance (deployed on Railiance infrastructure)
|
||||
|
||||
---
|
||||
|
||||
## Terminology
|
||||
|
||||
- Preferred terms: NetKingdom IAM Profile, lightweight mode, expanded mode, profile enforcement, canonical model
|
||||
- Also known as: "KeyCape", "key-cape"
|
||||
- Potentially confusing terms: "lightweight mode" = KeyCape stack; "expanded mode" = Keycloak stack; both implement the same OIDC profile
|
||||
|
||||
---
|
||||
|
||||
## Related / Overlapping
|
||||
|
||||
- `net-kingdom` — parent platform domain; KeyCape is the lightweight IAM implementation of its IAM Profile
|
||||
|
||||
---
|
||||
|
||||
## Provided Capabilities
|
||||
## Provided capabilities
|
||||
|
||||
```capability
|
||||
type: security
|
||||
title: OIDC/PKCE authentication (lightweight mode)
|
||||
description: Provides OIDC/PKCE endpoints conforming to the NetKingdom IAM Profile via Authelia + LLDAP + privacyIDEA — a drop-in Keycloak alternative for constrained environments.
|
||||
keywords: [oidc, pkce, authentication, iam, sso, authelia, lldap, mfa, identity]
|
||||
title: Bounded OIDC and service-token issuance
|
||||
description: Implements static-client browser PKCE and client-credentials authentication with RS256 identity claims through Authelia, LLDAP and privacyIDEA; complete Keycloak interchangeability remains unproven.
|
||||
keywords: [oidc, pkce, authentication, iam, sso, mfa, identity, service-token]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: security
|
||||
title: Identity migration tooling
|
||||
description: Migrate identities between lightweight (KeyCape) and expanded (Keycloak) IAM modes — LLDAP export, Keycloak import, LDIF generation.
|
||||
keywords: [migration, identity, lldap, keycloak, ldif, iam]
|
||||
title: Verified caller JWT acquisition
|
||||
description: Provides native browser login and service-token exchange commands with HTTPS discovery, JWKS verification and private token-file delivery.
|
||||
keywords: [oidc, pkce, jwt, cli, authentication, jwks]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Oriented
|
||||
|
||||
- Start with: `wiki/KeyCapeSpecification_v0.1.md` (architecture and design intent)
|
||||
- Key files / directories: `wiki/KeyCapeSpecificationPack_v0.1.md` (normative spec), `src/cmd/` (binary entrypoints), `src/internal/` (implementation), `tests/` (acceptance suite)
|
||||
- Entry points: `keycape server` binary; `keycape migrate` for migration tooling
|
||||
```capability
|
||||
type: security
|
||||
title: Directory validation and migration artifact generation
|
||||
description: Checks canonical snapshots and produces LLDAP exports, basic Keycloak realm JSON and target-specific LDIF; does not perform or prove a complete live migration.
|
||||
keywords: [migration, identity, lldap, keycloak, ldif, validation]
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue