key-cape/INTENT.md

---
# NetKingdom security layer declaration (§11), in key-cape's own voice.
#
# This frontmatter is the declaration. The prose sentence under "# INTENT"
# is not: §11 says prose cannot distinguish a declaration from a transcribed
# review. The §4 catalog row, gate-house (GH-WP-0004-T08) and access-engine
# (FLEX-WP-0030, B2) all name key-cape Tooling; none of that is a declaration,
# and this value was worked out against §3 from key-cape's own character.
#
# Form per GH-DEC-2026-017: INTENT.md governs, no layer.yaml sidecar, no
# standard version in any key or value (A12, reach per GH-DEC-2026-020).
layer: Tooling
role: —
repository: key-cape
declared_by: INTENT.md
declared_at: "2026-09-21"
ruling: GH-DEC-2026-017
# Why Tooling. key-cape is deterministic identity infrastructure: it packages
# Authelia, LLDAP and privacyIDEA and keeps the authentication state they hold
# (directory entries, second factors, sessions, client registrations, signing
# keys), and its own server issues tokens under the IAM profile. It does not
# model the user or tenant as an authoritative concept (user-engine and
# tenant-engine do), and it renders no authorization decision (access-engine
# does, §6). Agreement with §4: yes.
#
# Stated tension, not a disagreement: key-cape's token endpoint is an estate-
# authored deterministic API whose claims access-engine consumes as facts,
# which is how §3.3 describes a PIP, and authentication enforcement (MFA,
# PKCE, exact redirect URIs) sits here although §3.3 places enforcement
# boundaries in Engines. key-cape reads this as Tooling behaviour today and
# does not claim Engine permissions; any move would go through §10.
tooling_contacts:
  - target: authelia, lldap, privacyidea
    shape: packaged-backend
    rationale: >-
      Implementation dependencies inside key-cape's own tooling boundary, not
      separately owned estate capabilities.
  - target: kubernetes-secret (secretRef)
    shape: delivered-reference
    rationale: >-
      Confidential client secrets arrive as env secretRefs from a separate
      Secret delivered by the platform owner; key-cape holds no OpenBao client
      and never carries secret values in config.
# §11 non-Tooling clients, recorded so the check is total.
non_tooling_clients:
  - target: state-hub
    layer: not-catalogued
    rationale: Work records, workplans and progress events only.
# Boundary with access-engine, stated from this side. key-cape establishes
# authentication and issues verified identity claims under the IAM profile;
# it owns login, MFA, PKCE, token issuance and lifecycle. access-engine
# consumes those claims as normative input and decides what the actor may do.
# key-cape relies on access-engine for no validation of a claim beyond
# standard token verification (signature, issuer, audience, expiry); a role or
# scope claim is an input to a decision, never the decision.
---
# INTENT

KeyCape's layer is **Tooling** under the NetKingdom security layer model; the
machine-readable declaration is the frontmatter above, and this sentence is not. It provides deterministic authentication and identity claims through
the versioned IAM profile, packaging Authelia, LLDAP, and privacyIDEA.
Authorization decisions belong to access-engine; KeyCape is not an authorization
decision point. Issuing a role or scope claim does not decide access to a resource.

These backend components are implementation dependencies of KeyCape's tooling
boundary. Separate catalog entries are unnecessary until they expose independently
owned estate capabilities. Staff integration follows engine APIs as required by
the layer model; this declaration does not certify every existing caller path.

## Purpose

This repository exists to provide a **lightweight, profile-conformant identity and access management (IAM) system**.

It ensures that applications can rely on a **stable, versioned authentication contract** independent of the underlying IAM implementation.

---

## Primary Utility

The repository provides an implementation of a **versioned IAM profile** that:

* Delivers OIDC/PKCE-based authentication with strong security constraints
* Normalizes identity data across heterogeneous backend systems
* Enforces strict adherence to the defined IAM contract
* Enables seamless migration between lightweight and expanded IAM modes

It transforms IAM from a system dependency into a **replaceable, contract-driven capability**.

---

## Intended Users

* Application developers integrating against the IAM profile
* Infrastructure operators (`adm`) deploying IAM in constrained environments
* Automation systems (`atm`) managing identity, migration, and validation workflows
* LLM agents (`agt`) interacting with authenticated services

---

## Strategic Role in the System

This repository serves as the **lightweight IAM layer**:

* It provides a **resource-efficient implementation** of the IAM profile for environments with limited resources
* It anchors IAM around a **profile contract rather than a specific implementation**
* It enables a **two-mode architecture**:

  * Lightweight mode (this implementation)
  * Expanded mode (a heavier, full-featured implementation)

The profile ensures that both modes are **interchangeable without application changes**.

---

## Strategic Boundaries

This repository is **not** intended to:

* Become a full-featured, general-purpose IAM platform
* Extend beyond the defined IAM profile
* Support features that weaken security guarantees (e.g., implicit flow, wildcard redirects)
* Replace or wrap the heavier expanded-mode implementation

Its responsibility is limited to **strict, secure, and transparent profile implementation**.

---

## Design Principles

* **Contract over implementation**
  Applications depend on the IAM profile, not on KeyCape internals

* **Security through constraint**
  Only explicitly allowed features are supported; unsafe patterns are rejected

* **Explicitness over convenience**
  Unsupported features must fail clearly and predictably

* **Replaceability by design**
  The system must be swappable with a heavier profile implementation without breaking integrations

* **Canonical identity model**
  Identity data must be normalized and consistent across all backends

---

## Maturity Target

A mature version of this repository should:

* Fully implement and enforce the **IAM profile** with zero ambiguity
* Provide **complete migration pathways** between lightweight and expanded modes
* Offer **deterministic and testable behavior** across all supported scenarios
* Act as a **reference implementation** of the IAM profile
* Enable IAM deployments that are **minimal, secure, and operationally efficient**

---

## Stability Note

Changes to this file represent a **deliberate shift in the IAM contract, scope, or architectural role** of this repository.

Such changes must be made with explicit intent, as they directly affect all dependent applications.