# 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

- `net-kingdom` — parent platform domain; KeyCape is the lightweight IAM implementation of its IAM Profile

---

## 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]
```

```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]
```

---

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