key-cape/CLAUDE.md

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

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.