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:
```yaml
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.