key-cape/wiki/KeyCapeSpecification_v0.1.md

KeyCape

*Prepare for KeyCloak without KeyCloak*

# Keycape Specification v0.1

**Status:** Draft
**Project:** NetKingdom
**Component:** Keycape
**Purpose:** Lightweight IAM profile implementation for small and early production environments, with explicit replaceability by Keycloak in larger or federated environments.

---

## 1. Purpose

Keycape is a **profile-constrained IAM implementation** for NetKingdom.

It provides the **externally visible IAM contract** used by NetKingdom applications in lightweight environments, while being intentionally replaceable by **Keycloak** in larger environments.

Keycape is **not** a full IAM platform and **not** a full Keycloak clone.

Its role is to:

* implement the **NetKingdom IAM Profile**
* provide a slim production-capable setup for small environments
* enforce interface discipline from the beginning
* expose telemetry on demanded functionality
* support automated replacement tests to prove migration to Keycloak

---

## 2. Design Intent

The architecture shall support two valid production modes:

### 2.1 Lightweight mode

Uses lightweight components for lean production and development.

Typical implementation:

* **Keycape** as the externally visible profile implementation
* **Authelia** as lightweight OIDC-capable backend where useful
* **LLDAP** as lightweight directory backend where useful
* **privacyIDEA** as MFA authority

### 2.2 Expanded mode

Uses more feature-rich components for scale, federation, and enterprise IAM breadth.

Typical implementation:

* **Keycloak** as the externally visible IAM implementation
* **full LDAP directory** as identity backend where needed
* **privacyIDEA** as MFA authority

The critical idea is:

> Applications integrate against the **NetKingdom IAM Profile**, not against incidental behavior of Keycape, Authelia, LLDAP, or Keycloak.

---

## 3. Core Architectural Principle

Keycape shall be a **contract implementation**, not a platform clone.

That means:

* Keycape replicates only the **relevant external interfaces**
* Keycape may fulfill functionality by orchestrating underlying components
* unsupported functions must fail clearly and predictably
* profile violations must be observable through telemetry
* Keycape must remain small enough to be maintainable

---

## 4. Scope

## 4.1 In scope

Keycape is responsible for:

* implementing the **NetKingdom IAM Profile**
* exposing the external IAM endpoints required by profile-conformant clients
* normalizing identity and claims behavior across lightweight mode
* providing structured errors for unsupported functionality
* generating telemetry on requested functionality and profile drift
* supporting migration and replacement testing to Keycloak
* participating in automated data migration workflows

## 4.2 Out of scope

Keycape shall not attempt to provide broad parity with Keycloak in areas such as:

* identity brokering to arbitrary upstream IdPs
* general SAML platform parity
* Keycloak SPI/plugin parity
* Keycloak admin console parity
* Keycloak authorization services parity
* generic realm import/export parity
* broad compatibility with arbitrary Keycloak-specific admin APIs
* full LDAP server behavior
* enterprise IAM feature breadth beyond the defined profile

---

## 5. Terminology

### 5.1 NetKingdom IAM Profile

The explicit, versioned contract supported by both Keycape and Keycloak-mode deployments.

### 5.2 Profile implementation

A concrete runtime that implements the profile, such as Keycape or Keycloak.

### 5.3 Lightweight mode

Deployment mode using slim components and limited scope.

### 5.4 Expanded mode

Deployment mode using Keycloak and fuller directory/federation infrastructure.

### 5.5 Canonical identity model

A product-neutral representation of users, groups, roles, clients, and related metadata used for validation, provisioning, migration, and tests.

### 5.6 Canonical LDAP schema

A restricted LDAP-oriented schema profile derived from the canonical identity model and validated before provisioning or migration.

---

## 6. Functional Positioning of Components

## 6.1 Keycape

External contract implementation in lightweight mode.

Responsibilities:

* profile endpoints
* protocol normalization
* claim normalization
* config translation to underlying components
* unsupported-feature handling
* telemetry

## 6.2 Authelia

Optional lightweight backend for OIDC/session/auth flows.

Responsibilities may include:

* login/session handling
* token issuance
* client handling within supported subset

Authelia remains an internal implementation detail from the application point of view.

## 6.3 LLDAP

Optional lightweight LDAP-compatible identity backend.

Responsibilities may include:

* user storage
* group membership storage
* dev/bootstrap directory service
* lean production directory for small environments

LLDAP is not part of the application-facing contract.

## 6.4 privacyIDEA

Stable MFA and token-policy authority across both modes.

Responsibilities:

* MFA enforcement and policy
* token management where applicable
* stable security concept across migration paths

## 6.5 Keycloak

Replacement implementation for expanded mode.

Responsibilities:

* implement the same profile for applications
* provide wider IAM capability when needed
* optionally federate with larger directories

---

## 7. Keycape Objectives

Keycape shall satisfy the following objectives:

### 7.1 Contract stability

Applications should see a stable IAM surface.

### 7.2 Minimalism

Only the defined profile shall be implemented.

### 7.3 Replaceability

Replacement by Keycloak shall be continuously testable.

### 7.4 Observability

Demand for unsupported or non-profile functionality shall be measurable.

### 7.5 Migration readiness

Data and configuration required for replacement shall be exportable, transformable, and validated.

### 7.6 Production validity

The lightweight stack shall be considered valid production infrastructure where the required feature set stays within the profile.

---

## 8. NetKingdom IAM Profile

This section defines the initial minimum profile supported by the KeyCape v0.1
specification. The canonical NetKingdom profile has since moved to
`net-kingdom/canon/standards/iam-profile_v0.2.md`; KeyCape conformance should
be measured against that profile and the executable suite in
`net-kingdom/tools/iam-profile-conformance/`.

## 8.1 Supported authentication model

The initial profile shall support:

* OpenID Connect Authorization Code Flow
* PKCE
* confidential clients
* public clients only if explicitly allowed in a later profile revision
* fixed redirect URIs
* a small, stable claim set
* stable issuer behavior
* JWKS exposure
* discovery metadata

## 8.2 Supported endpoints

The initial profile shall define support for:

* discovery endpoint
* authorization endpoint
* token endpoint
* JWKS endpoint
* userinfo endpoint if required by supported clients
* logout endpoint only if its semantics are clearly defined in the profile

Optional endpoints such as introspection and revocation shall only be supported if there is a concrete application need.

## 8.3 Supported scopes

Initial mandatory scopes:

* `openid`

Optional initial scopes, if required:

* `profile`
* `email`
* `groups`

Custom scopes shall be explicitly versioned as part of the profile.

## 8.4 Supported claims

Initial standard claims may include:

* `sub`
* `iss`
* `aud`
* `exp`
* `iat`
* `preferred_username`
* `email` if present
* `name` if present

NetKingdom profile v0.2 requires these normalized claims before applications
or flex-auth consume a token:

* `tenant`
* `principal_type`
* `groups`
* `roles`
* `scope` or `scp`
* `assurance`

Claim names, types, and semantics must be fixed by the profile and validated in tests.

## 8.5 Supported client model

Clients shall be defined in a constrained way:

* immutable client identifier
* known redirect URIs
* known scopes
* known grant types within the profile
* predictable claim mapping behavior
* minimal client-secret handling rules
* no dynamic client registration in v0.1

## 8.6 MFA interaction

MFA behavior shall be treated as part of the authentication policy, not as ad hoc application logic.

The profile shall define:

* when MFA is required
* whether MFA state influences token claims
* whether step-up behavior is supported
* which user/account states are considered valid for issuance

The exact MFA mechanics may be delegated to privacyIDEA.

---

## 9. Unsupported Functionality Policy

Any request beyond the profile shall be handled explicitly.

## 9.1 Required behavior

Keycape shall never silently emulate unsupported features in an undefined way.

## 9.2 Error taxonomy

The following error classes shall exist:

### `feature_not_supported_by_profile`

The requested capability is outside the NetKingdom IAM Profile.

### `available_in_keycloak_mode_only`

The capability may exist in expanded mode but is intentionally absent in lightweight mode.

### `rejected_for_profile_safety`

The request is rejected because supporting it would weaken the profile’s guarantees or security discipline.

### `invalid_profile_usage`

The client uses a supported endpoint or feature incorrectly.

## 9.3 Error response requirements

Errors shall be:

* machine-readable
* human-readable
* loggable
* distinguishable by category
* stable enough for automated tests

---

## 10. Canonical Identity Model

Keycape development shall use a canonical identity model independent of product-specific storage schemas.

## 10.1 Purpose

The canonical identity model is the source of truth for:

* test fixtures
* provisioning
* migration
* validation
* replacement testing

## 10.2 Core entities

At minimum:

* User
* Group
* Membership
* Client
* Role
* ClientScopeAssignment
* MFAEnrollmentReference
* DirectoryAttributes
* ProfileVersion

## 10.3 Canonical user fields

Minimum user fields:

* stable internal identifier
* username
* display name
* email
* enabled/disabled state
* group memberships
* optional role memberships
* optional MFA linkage reference
* LDAP-oriented attributes required by the canonical LDAP schema

## 10.4 Canonical client fields

Minimum client fields:

* client ID
* display label
* allowed redirect URIs
* allowed scopes
* client type
* secret reference if applicable
* token/claim profile
* environment applicability

---

## 11. Canonical LDAP Schema

The canonical LDAP schema is the restricted LDAP expression of the canonical identity model.

It exists to ensure portability between:

* LLDAP
* larger LDAP implementations
* Keycloak federation targets where relevant

## 11.1 Goals

* keep LDAP usage intentionally small and portable
* prevent schema drift
* validate data before provisioning/migration
* ensure only approved attributes and structures are used

## 11.2 Validator requirement

A **canonical LDAP schema validator** is mandatory.

It shall validate:

* object class usage
* required and optional attributes
* DN placement rules
* naming rules
* group membership representation
* forbidden attributes or structures
* cross-entry consistency
* profile version compatibility

## 11.3 Validator modes

The validator should support:

* fixture validation
* pre-provision validation
* pre-migration validation
* post-migration verification
* drift detection in CI

---

## 12. Keycape Runtime Responsibilities

In lightweight mode Keycape shall be responsible for:

## 12.1 Profile endpoint exposure

Expose the agreed external endpoints.

## 12.2 Backend translation

Translate profile concepts into underlying Authelia/LLDAP/privacyIDEA configuration and behavior.

## 12.3 Claim normalization

Ensure tokens and userinfo behave according to profile definitions, regardless of backend quirks.

## 12.4 Unsupported-feature enforcement

Block non-profile usage with structured errors.

## 12.5 Telemetry

Emit data on requested behavior and unsupported demand.

## 12.6 Configuration export support

Produce the information needed for migration to expanded mode.

---

## 13. Telemetry Specification

Telemetry is a first-class feature of Keycape.

## 13.1 Purpose

Telemetry shall answer questions such as:

* which profile features are actually used
* which unsupported features are demanded
* which applications are creating pressure for expanded-mode features
* whether the current profile remains sufficient

## 13.2 Minimum telemetry events

Keycape shall emit events for:

* successful authentication flow start
* successful token issuance
* unsuccessful authentication attempt
* unsupported endpoint usage
* unsupported grant/scopes/claims usage
* invalid redirect or client usage
* logout attempts
* admin/config-related unsupported requests
* migration/export operations

## 13.3 Minimum telemetry fields

Each event should capture:

* timestamp
* environment
* deployment mode
* client ID
* endpoint
* feature category
* result status
* error class if applicable
* requested scopes
* requested grant type
* correlation ID / trace ID

## 13.4 Telemetry outputs

Telemetry should be usable for:

* logs
* metrics
* dashboards
* CI analysis
* migration planning

---

## 14. Migration Model

Replacement by Keycloak shall be an explicit, tested capability.

## 14.1 Migration dimensions

Migration has at least two independent dimensions:

### A. IAM implementation migration

Keycape/lightweight implementation → Keycloak

### B. Directory migration

LLDAP → full LDAP implementation

## 14.2 Migration principles

* migration shall be reproducible
* migration shall be test-driven
* migration shall use canonical data as the source of truth
* migration success shall be determined by application-facing contract tests
* migration shall include data validation before and after transfer

## 14.3 Supported migration paths

Initial required paths:

### Path 1

LLDAP + Keycape stack → Keycloak with same directory data semantics

### Path 2

LLDAP → full LDAP, then Keycloak federating with full LDAP

### Path 3

Lightweight stack → expanded stack with privacyIDEA remaining stable

## 14.4 Migration outputs

Migration tooling should generate:

* transformed directory data
* client definitions
* profile conformance reports
* validation results
* contract test results
* incompatibility reports

---

## 15. Replacement Test Strategy

Automated replacement testing is mandatory.

## 15.1 Goal

Prove that applications relying only on the profile behave acceptably after replacement.

## 15.2 Required test scenarios

### Scenario A: Lightweight baseline

Provision canonical fixtures into lightweight mode and run all profile integration tests.

### Scenario B: IAM replacement

Replace Keycape-based implementation with Keycloak and rerun the same app-facing tests.

### Scenario C: Full expansion

Migrate LLDAP data into full LDAP, connect Keycloak, and rerun tests.

### Scenario D: Negative profile tests

Attempt to use unsupported functionality and verify correct error behavior and telemetry.

## 15.3 Test categories

Required categories:

* discovery tests
* login flow tests
* token claim tests
* redirect validation tests
* client configuration tests
* logout tests if supported
* MFA policy tests
* migration data integrity tests
* canonical LDAP schema validation tests
* telemetry assertion tests

## 15.4 Acceptance rule

A migration path is acceptable only if:

* profile-conformant apps keep working
* required claims remain stable
* unsupported cases fail in expected ways
* canonical identity data remains valid
* telemetry remains available where expected

---

## 16. Security Requirements

## 16.1 General

Keycape shall prioritize narrowness and correctness over feature breadth.

## 16.2 Mandatory controls

* strict redirect URI validation
* strict issuer consistency
* strict client identity validation
* no handwritten cryptography
* no handwritten password hashing implementation
* use of established protocol and crypto libraries
* minimal and explicit scope handling
* explicit token lifetime policy
* auditability of authentication decisions

## 16.3 Safety through profile discipline

Feature restriction is a security control.

Any expansion of the profile must be reviewed for:

* protocol complexity increase
* migration complexity increase
* test burden increase
* security surface increase

---

## 17. Configuration Principles

Keycape configuration shall be declarative.

## 17.1 Configuration sources

Configuration may include:

* profile definition version
* client definitions
* backend connection settings
* LDAP schema rules
* privacyIDEA integration settings
* telemetry destinations
* environment-specific overrides

## 17.2 Configuration constraints

Configuration should be:

* version-controlled
* environment-promotable
* statically validated where possible
* linked to profile version
* convertible into migration/export artifacts

---

## 18. Operational Modes

## 18.1 Dev mode

Optimized for rapid local iteration and deterministic tests.

May use:

* local LLDAP
* local Authelia
* simplified privacyIDEA integration stubs or real integration depending on environment policy

## 18.2 Slim production mode

A real production mode for environments whose needs fit inside the profile.

May use:

* LLDAP
* Authelia
* privacyIDEA
* Keycape

## 18.3 Expanded production mode

Used when federation, admin breadth, or IAM complexity exceeds the profile’s lightweight implementation strategy.

May use:

* Keycloak
* full LDAP
* privacyIDEA

---

## 19. Non-Goals

Keycape shall not pursue these goals in v0.1:

* broad Keycloak API parity
* general-purpose enterprise IAM platform status
* support for arbitrary legacy LDAP consumers through Keycloak
* plugin ecosystem parity
* realm-level multi-tenancy complexity beyond explicit profile need
* bespoke app-specific exceptions outside the profile

---

## 20. Conformance

## 20.1 Keycape conformance

Keycape conforms if it:

* implements the required profile endpoints and behaviors
* produces correct claims and errors
* passes all lightweight profile tests
* emits required telemetry
* supports migration/export flows required by the specification

## 20.2 Expanded-mode conformance

A Keycloak-based deployment conforms if it:

* passes the same application-facing profile tests
* honors the same claim model and client behavior
* supports defined migration scenarios

## 20.3 Fixture conformance

Canonical fixtures conform if they pass canonical model and LDAP schema validation.

---

## 21. Initial Deliverables Derived from This Specification

The following implementation artifacts should be created next:

### 21.1 NetKingdom IAM Profile

A formal canonical profile document now exists in net-kingdom as
`canon/standards/iam-profile_v0.2.md`, with endpoint-by-endpoint detail,
tenant/principal/assurance claims, and executable conformance checks.

### 21.2 Canonical identity model schema

Machine-readable schema for canonical fixtures.

### 21.3 Canonical LDAP schema and validator spec

Formal validator rules and error codes.

### 21.4 Keycape component design

Internal architecture, adapters, translation logic, and runtime behavior.

### 21.5 Replacement test matrix

End-to-end scenarios and expected outcomes.

### 21.6 Migration design

LLDAP → full LDAP and lightweight IAM → Keycloak data/config mapping.


xxx