key-cape/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

KeyCape — Claude Code Instructions

What This Repo Is

KeyCape is the lightweight IAM component of NetKingdom.

"Prepare for Keycloak without Keycloak"

KeyCape implements the NetKingdom IAM Profile — a versioned OIDC/PKCE contract that NetKingdom applications integrate against. It orchestrates:

Component	Role
Authelia	OIDC provider / session / tokens
LLDAP	Lightweight identity directory
privacyIDEA	MFA authority

Keycape is intentionally replaceable by Keycloak in expanded mode. All apps must target the profile, not Keycape or Keycloak incidentals.

Custodian State Hub Integration

• Domain: netkingdom
• Repo ID: 8a99bb74-1ec0-4478-ac70-35a7cddb0e3c
• State Hub API: http://127.0.0.1:8000 (run cd ~/the-custodian/state-hub && make api if offline)

Session Protocol

Start of every session:

get_domain_summary("netkingdom")

This gives the full picture of active workstreams, blocking decisions, and recent progress for the NetKingdom domain at ~10% of the cost of get_state_summary().

During work:

• record_decision() for any architectural choice (profile extensions, backend selection, etc.)
• add_progress_event() for milestones, blockers, discoveries
• resolve_decision() once a decision is closed

End of every session:

add_progress_event(summary="...", event_type="...", workstream_id="<active ws id>")

After modifying workplan files, run:

cd ~/the-custodian/state-hub && make fix-consistency REPO=key-cape

Key Documents

Document	Path	Purpose
Keycape Specification v0.1	wiki/KeyCapeSpecification_v0.1.md	Architecture, design intent, objectives
Normative Specification Pack v0.1	wiki/KeyCapeSpecificationPack_v0.1.md	Normative spec for implementation agents: identity model, LDAP schema, error taxonomy, telemetry, migration contract, acceptance test matrix

Architecture

key-cape/
  wiki/               # Specifications (read before implementing)
  workplans/          # Implementation workplans (ADR-001 convention)
  src/                # Implementation (to be created)
  tests/              # Test suite (to be created)

Lightweight mode stack

Application ──→ NetKingdom IAM Profile
                      │
                   KeyCape  ←── config translation, claim normalization
                   /   |  \
           Authelia  LLDAP  privacyIDEA

Expanded mode stack (Keycape → Keycloak)

Application ──→ NetKingdom IAM Profile
                      │
                  Keycloak  (same profile, different runtime)
                   /   \
             LDAP      privacyIDEA

Implementation Priorities (from spec)

1. Profile endpoints — OIDC discovery, authorization, token, JWKS, userinfo
2. Canonical identity model — product-neutral user/group/client schema
3. Claim normalization — stable claim set regardless of backend quirks
4. Unsupported-feature enforcement — structured errors, never silent emulation
5. Telemetry — demand visibility for unsupported features and auth events
6. Migration tooling — export/validate for LLDAP → Keycloak path

Normative Constraints (from spec — binding on implementation)

Never silently emulate unsupported features. Any request outside the profile MUST fail with a structured error from this taxonomy:

• feature_not_supported_by_profile — outside the NetKingdom IAM Profile entirely
• available_in_keycloak_mode_only — exists in expanded mode, absent here by design
• rejected_for_profile_safety — would weaken profile guarantees or security discipline
• invalid_profile_usage — supported endpoint/feature used incorrectly

Security hard rules: No handwritten cryptography. No handwritten password hashing. Use established protocol and crypto libraries. Strict redirect URI validation. Strict issuer consistency.

Canonical identity model is the source of truth for test fixtures, provisioning, migration, and validation — not any backend's native schema.

Spec Pack structure (wiki/KeyCapeSpecificationPack_v0.1.md) contains 7 normative components agents must read before implementing:

1. Normative Specification — OIDC/PKCE contract, endpoints, scopes, claims, client model, MFA
2. Canonical Identity Schema — User, Group, Membership, Client, Role, MFAEnrollmentReference, etc.
3. Canonical LDAP Schema + Validator Rules — restricted LDAP expression of identity model
4. Error Taxonomy — machine-readable/human-readable/loggable structured errors
5. Telemetry Schema — event types, required fields (timestamp, env, client_id, endpoint, feature_category, correlation_id, …)
6. Migration Contract — LLDAP → full LDAP, KeyCape → Keycloak migration paths
7. Acceptance Test Matrix — lightweight baseline, IAM replacement, full expansion, negative profile tests

Workplan Convention (ADR-001)

Workplans live in workplans/<id>-<slug>.md with YAML frontmatter:

id: KEY-WP-0001
type: workplan
title: "..."
domain: netkingdom
repo: key-cape
status: todo|active|done
owner: Bernd
topic_slug: netkingdom

Tasks are embedded as ## Task Title\n```task\nid: ...\nstatus: todo\n```\n blocks.