Files

CI / Build and Test (push) Has been cancelled

Details

docs: add SCOPE.md for rapid orientation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-17 23:10:44 +01:00

3.6 KiB

Raw Blame History

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

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

3.6 KiB Raw Blame History