chore: track specification documents

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-13 00:30:46 +01:00
parent 3780190456
commit f3b1cdcba4
2 changed files with 1544 additions and 0 deletions
--- a/wiki/KeyCapeSpecificationPack_v0.1.md
+++ b/wiki/KeyCapeSpecificationPack_v0.1.md
@@ -0,0 +1,730 @@
+KeyCapeSpecPac
+
+*Implementation guidane for  keycape*
+
+Below is the **Normative Specification Pack v0.1** for **Keycape**.
+This version is structured so that a **coding agent can implement it**.
+
+The pack contains the seven components we discussed:
+
+1. Normative Specification
+2. Canonical Identity Schema
+3. Canonical LDAP Schema + Validator Rules
+4. Error Taxonomy
+5. Telemetry Schema
+6. Migration Contract
+7. Acceptance Test Matrix
+
+This document is written **normatively where required** (MUST / SHOULD / MAY).
+
+---
+
+# Keycape Normative Specification Pack v0.1
+
+**Project:** NetKingdom
+**Component:** Keycape
+**Status:** Normative Draft
+**Audience:** Developers, architecture engineers, coding agents
+
+---
+
+# 1. Normative Specification
+
+## 1.1 Purpose
+
+Keycape is a **lightweight implementation of the NetKingdom IAM Profile**.
+
+Keycape provides:
+
+* a stable **OIDC-based IAM contract**
+* a **lightweight runtime implementation**
+* strict **profile enforcement**
+* **telemetry** about demanded IAM functionality
+* **automated migration readiness** for Keycloak replacement
+
+Keycape is **not a Keycloak clone**.
+
+---
+
+## 1.2 Architectural Role
+
+Keycape is the **external IAM contract provider** in lightweight mode.
+
+Applications interact only with the **NetKingdom IAM Profile**.
+
+Keycape internally orchestrates:
+
+| Component   | Responsibility        |
+| ----------- | --------------------- |
+| Authelia    | OIDC provider backend |
+| LLDAP       | identity directory    |
+| privacyIDEA | MFA authority         |
+
+Expanded mode replaces Keycape with **Keycloak**.
+
+---
+
+## 1.3 Supported Protocol
+
+Keycape MUST implement:
+
+**OpenID Connect 1.0**
+
+Using:
+
+**Authorization Code Flow + PKCE**
+
+Reference model:
+
+```
+Application
+      |
+      v
+Keycape (profile contract)
+      |
+      v
+Authelia + LLDAP + privacyIDEA
+```
+
+Expanded mode:
+
+```
+Application
+      |
+      v
+Keycloak
+      |
+      v
+LDAP + privacyIDEA
+```
+
+---
+
+## 1.4 Mandatory Endpoints
+
+Keycape MUST expose the following endpoints.
+
+| Endpoint                            | Required |
+| ----------------------------------- | -------- |
+| `/.well-known/openid-configuration` | YES      |
+| `/authorize`                        | YES      |
+| `/token`                            | YES      |
+| `/jwks`                             | YES      |
+| `/userinfo`                         | OPTIONAL |
+| `/logout`                           | OPTIONAL |
+| `/introspect`                       | OPTIONAL |
+
+Discovery MUST correctly advertise supported features.
+
+---
+
+## 1.5 Authentication Flow
+
+Supported flow:
+
+Authorization Code + PKCE
+
+Requirements:
+
+Client MUST supply:
+
+```
+client_id
+redirect_uri
+response_type=code
+scope=openid
+code_challenge
+code_challenge_method=S256
+```
+
+Keycape MUST validate:
+
+* redirect URI
+* client configuration
+* PKCE challenge
+
+---
+
+## 1.6 Token Requirements
+
+Tokens MUST be JWT.
+
+Minimum claims:
+
+```
+iss
+sub
+aud
+exp
+iat
+```
+
+Optional claims:
+
+```
+preferred_username
+email
+groups
+roles
+```
+
+Signature MUST use:
+
+```
+RS256
+```
+
+JWKS MUST be available at `/jwks`.
+
+---
+
+## 1.7 Client Model
+
+Client registration is **static** in v0.1.
+
+Client fields:
+
+```
+client_id
+client_secret (optional for public)
+redirect_uris[]
+allowed_scopes[]
+allowed_grants[]
+```
+
+Dynamic registration is **NOT allowed**.
+
+---
+
+## 1.8 MFA Behavior
+
+MFA enforcement is delegated to **privacyIDEA**.
+
+Keycape MUST:
+
+* detect MFA requirement
+* enforce MFA before token issuance
+* fail authentication if MFA fails
+
+Keycape MUST NOT implement MFA logic itself.
+
+---
+
+## 1.9 Claims Model
+
+Claims MUST follow the **Canonical Identity Model**.
+
+Mapping example:
+
+| Claim              | Source                 |
+| ------------------ | ---------------------- |
+| sub                | canonical user ID      |
+| preferred_username | LDAP uid               |
+| email              | LDAP mail              |
+| groups             | LDAP groupOfNames      |
+| roles              | canonical role mapping |
+
+---
+
+# 2. Canonical Identity Model
+
+The canonical model is the **source of truth** for identities.
+
+All provisioning, tests, and migrations derive from it.
+
+---
+
+## 2.1 Canonical Entities
+
+Entities:
+
+```
+User
+Group
+Role
+Client
+Membership
+MFAEnrollment
+```
+
+---
+
+## 2.2 Canonical User Schema
+
+```yaml
+User:
+  id: string
+  username: string
+  displayName: string
+  email: string
+  enabled: boolean
+  groups:
+    - group_id
+  roles:
+    - role_id
+  attributes:
+    key: value
+```
+
+---
+
+## 2.3 Canonical Group Schema
+
+```yaml
+Group:
+  id: string
+  name: string
+  description: string
+```
+
+---
+
+## 2.4 Canonical Client Schema
+
+```yaml
+Client:
+  client_id: string
+  display_name: string
+  redirect_uris:
+    - uri
+  allowed_scopes:
+    - scope
+  grant_types:
+    - authorization_code
+```
+
+---
+
+## 2.5 Canonical MFA Schema
+
+```yaml
+MFAEnrollment:
+  user_id: string
+  provider: privacyidea
+  state: enabled
+```
+
+---
+
+# 3. Canonical LDAP Schema
+
+The canonical LDAP schema expresses the identity model in LDAP.
+
+This ensures portability across:
+
+* LLDAP
+* OpenLDAP
+* 389DS
+* Active Directory
+
+---
+
+## 3.1 LDAP Tree Layout
+
+```
+dc=netkingdom,dc=local
+
+ou=users
+ou=groups
+ou=clients
+```
+
+---
+
+## 3.2 User Entry
+
+Object classes:
+
+```
+inetOrgPerson
+organizationalPerson
+person
+top
+```
+
+Attributes:
+
+```
+uid
+cn
+sn
+mail
+memberOf
+```
+
+Example:
+
+```
+dn: uid=alice,ou=users,dc=netkingdom,dc=local
+uid: alice
+cn: Alice
+sn: Example
+mail: alice@example.com
+```
+
+---
+
+## 3.3 Group Entry
+
+Object classes:
+
+```
+groupOfNames
+top
+```
+
+Attributes:
+
+```
+cn
+member
+```
+
+---
+
+# 4. LDAP Schema Validator
+
+Validator MUST verify:
+
+### Structural Rules
+
+* valid DN structure
+* required attributes present
+* no unknown attributes
+* valid group memberships
+
+### Semantic Rules
+
+* referenced users exist
+* groups are not cyclic
+* usernames unique
+* email format valid
+
+Validator MUST run in:
+
+```
+CI
+Provisioning
+Migration
+```
+
+---
+
+# 5. Error Taxonomy
+
+Keycape MUST implement structured errors.
+
+---
+
+## 5.1 Error Types
+
+### feature_not_supported_by_profile
+
+Requested functionality outside the profile.
+
+Example:
+
+```
+dynamic_client_registration
+```
+
+---
+
+### available_in_keycloak_mode_only
+
+Feature exists only in expanded mode.
+
+Example:
+
+```
+identity_broker
+```
+
+---
+
+### rejected_for_profile_safety
+
+Feature intentionally blocked.
+
+Example:
+
+```
+wildcard_redirect_uri
+```
+
+---
+
+### invalid_profile_usage
+
+Client misused the profile.
+
+Example:
+
+```
+missing_pkce
+```
+
+---
+
+## 5.2 Error Format
+
+```
+{
+  "error": "feature_not_supported_by_profile",
+  "description": "...",
+  "feature": "identity_broker"
+}
+```
+
+---
+
+# 6. Telemetry Schema
+
+Keycape MUST emit telemetry events.
+
+---
+
+## 6.1 Telemetry Event Types
+
+```
+auth_start
+auth_success
+auth_failure
+token_issued
+unsupported_feature
+invalid_request
+migration_event
+```
+
+---
+
+## 6.2 Telemetry Fields
+
+```json
+{
+  "timestamp": "...",
+  "client_id": "...",
+  "endpoint": "...",
+  "feature": "...",
+  "result": "...",
+  "error_type": "...",
+  "scopes": [],
+  "grant_type": "...",
+  "environment": "...",
+  "trace_id": "..."
+}
+```
+
+---
+
+## 6.3 Telemetry Outputs
+
+Telemetry MUST support:
+
+```
+logs
+metrics
+dashboards
+analysis
+```
+
+---
+
+# 7. Migration Contract
+
+Migration must support two dimensions.
+
+---
+
+## 7.1 IAM Migration
+
+```
+Keycape → Keycloak
+```
+
+Requirements:
+
+* same issuer behavior
+* same claims
+* same scopes
+* same client behavior
+
+---
+
+## 7.2 Directory Migration
+
+```
+LLDAP → Full LDAP
+```
+
+Supported targets:
+
+```
+OpenLDAP
+389 Directory Server
+Active Directory
+```
+
+Migration MUST include:
+
+```
+users
+groups
+memberships
+attributes
+```
+
+---
+
+# 8. Replacement Testing
+
+Replacement must be continuously verified.
+
+---
+
+## 8.1 Scenario A — Lightweight
+
+```
+LLDAP + Authelia + Keycape
+```
+
+Run all profile tests.
+
+---
+
+## 8.2 Scenario B — IAM Replacement
+
+```
+Keycloak + same directory
+```
+
+Run same tests.
+
+---
+
+## 8.3 Scenario C — Full Expansion
+
+```
+LLDAP → LDAP
+Keycloak
+```
+
+Run tests again.
+
+---
+
+## 8.4 Scenario D — Negative Tests
+
+Attempt:
+
+```
+unsupported scopes
+dynamic clients
+wildcard redirects
+identity brokering
+```
+
+Verify errors and telemetry.
+
+---
+
+# 9. Acceptance Criteria
+
+Replacement is successful if:
+
+* apps continue to work
+* claims remain stable
+* login flow unchanged
+* migration data valid
+* telemetry preserved
+
+---
+
+# 10. Security Requirements
+
+Keycape MUST enforce:
+
+```
+strict redirect URI validation
+PKCE mandatory
+no dynamic client registration
+JWT signing via standard library
+no custom crypto
+issuer consistency
+short token lifetime
+```
+
+---
+
+# 11. Implementation Requirements
+
+Keycape SHOULD be implemented in:
+
+```
+Go or Rust
+```
+
+Key requirements:
+
+```
+stateless
+small memory footprint
+simple deployment
+clear logging
+structured telemetry
+```
+
+---
+
+# 12. Recommended Repository Structure
+
+```
+keycape/
+ ├── spec/
+ │    ├── iam-profile.md
+ │    ├── canonical-model.yaml
+ │    ├── ldap-schema.yaml
+ │
+ ├── validator/
+ │    └── ldap-validator
+ │
+ ├── adapters/
+ │    ├── authelia
+ │    ├── lldap
+ │    └── privacyidea
+ │
+ ├── server/
+ │    ├── oidc
+ │    ├── telemetry
+ │    └── errors
+ │
+ ├── migration/
+ │    ├── lldap-to-ldap
+ │    └── keycape-to-keycloak
+ │
+ └── tests/
+      ├── profile
+      ├── migration
+      └── negative
+```
+
+---
+
+# 13. Next Step
+
+The next step is creating the **Keycape Implementation Workplan**.
+
+This will include:
+
+* system architecture
+* internal modules
+* adapter design
+* telemetry pipeline
+* coding-agent instructions
+* milestone roadmap
+* estimated code size (~15–20k lines)
+
+If you want, I can generate that next.
+
+
+xxx
--- a/wiki/KeyCapeSpecification_v0.1.md
+++ b/wiki/KeyCapeSpecification_v0.1.md
@@ -0,0 +1,814 @@
+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 v0.1
+
+This section defines the initial minimum profile to be supported.
+
+## 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
+
+Optional NetKingdom-specific claims may include:
+
+* groups
+* roles
+* tenant or environment markers if explicitly defined
+
+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 v0.1
+
+A more formal profile document with endpoint-by-endpoint detail.
+
+### 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