diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..2630c8a --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,97 @@ +# 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. + +--- + +## One-liner + +Lightweight IAM implementation of the NetKingdom IAM Profile — orchestrates Authelia, LLDAP, and privacyIDEA to provide OIDC/PKCE authentication as a drop-in Keycloak alternative. + +--- + +## Core Idea + +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. + +--- + +## In Scope + +- 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) + +--- + +## Out of Scope + +- 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) + +--- + +## Relevant When + +- 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 Repositories + +- `net-kingdom` — parent platform domain; KeyCape is the lightweight IAM implementation of its IAM Profile + +--- + +## 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