generated from coulomb/repo-seed
tegwick
3780190456
- CLAUDE.md: session protocol, architecture overview, spec pointers, workplan convention, state-hub repo ID (8a99bb74, netkingdom domain) - README.md: replace repo-seed placeholder with KeyCape description Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
# 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:
|
|
```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.
|