net-kingdom/SCOPE.md

# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Platform domain for NetKingdom identity and security services — owns the IAM Profile specification, SSO/MFA platform (Keycloak), and bootstrap local-identity infrastructure for Kubernetes deployments.

---

## Core Idea

NetKingdom is a self-optimizing security platform for Kubernetes-based IT infrastructure. This repo owns identity at the platform level: the NetKingdom IAM Profile specification (the versioned OIDC/PKCE contract all applications target), the enterprise Keycloak-based SSO/MFA platform, and a lightweight file-based local-identity service for bootstrap environments before the full cluster is available.

---

## In Scope

- NetKingdom IAM Profile specification (versioned OIDC/PKCE contract;
  canonical spec: `canon/standards/iam-profile_v0.3.md`)
- SSO/MFA Platform: Keycloak with LDAP/Entra federation, enterprise identity (NK-WP-0001, finished)
- Local Identity: file-based user store + minimal OIDC server for bootstrap phase (NK-WP-0002, finished)
- User Engine Boundary Contract: source-of-truth, membership,
  application-onboarding, projection, authorization, and audit contracts for
  `user-engine` integration (`canon/standards/user-engine-boundary-contract_v0.1.md`)
- Security bootstrapping: credential management, SOPS/age integration,
  platform-root custody, OpenBao runtime secret authority
- OpenBao init/unseal custody models (NET-WP-0020): `sops-held-automation`
  (lab, unattended greenfield rebuilds via `creds-bootstrap-agent` Phase 7b),
  `attended-ceremony` (production, runbook + non-secret evidence records), and
  `auto-unseal-transit` (production HA; seal stanza lives in
  railiance-platform) — all gated by the security bootstrap console and a
  lab/production deployment profile
- Security bootstrap console (`tools/security-bootstrap-console/`): custody
  gates, roster, evidence validators, refuse-live-init boundary
- Architectural decisions (DECISIONS.md): identity source, secrets, GitOps, bootstrap user store

---

## Out of Scope

- Kubernetes runtime concerns → railiance-cluster
- Platform services (PostgreSQL, storage, caches) → railiance-platform
- Application deployments → railiance-apps
- KeyCape implementation details → key-cape

---

## Relevant When

- Setting up identity for a NetKingdom/Railiance deployment
- Designing or using the guided security bootstrap experience
- Applications need OIDC authentication; deciding between lightweight (KeyCape) and expanded (Keycloak) modes
- Bootstrap scenario: cluster not yet available, need minimal OIDC for dev/test/sandbox
- Reviewing IAM Profile specification or architectural identity decisions

---

## Not Relevant When

- Infrastructure provisioning (use railiance-infra)
- Platform services configuration (use railiance-platform)
- Application-level auth code (use the IAM Profile spec as reference only)

---

## Current State

- Status: active — core identity and bootstrap phases delivered; follow-on work
  in backlog
- Implementation: NK-WP-0001 (SSO/MFA), NK-WP-0002 (local identity), the
  security bootstrap arc (NET-WP-0015–0017, 0019), the IAM Profile spec
  (NK-WP-0012), user-engine boundary contracts (NK-WP-0014), and OpenBao
  unseal custody + SSH automation (NET-WP-0020) are all finished — see
  `workplans/archived/`
- Backlog: NK-WP-0009 (security pattern tutorials) and NK-WP-0011 (enterprise
  federation / SAML) — postponed, not yet started
- Stability: stabilizing — bootstrap/custody tooling is live-proven (greenfield
  OpenBao init/unseal proof 2026-07-02); production custody models are gated
  by evidence
- Usage: foundational authentication layer for all NetKingdom deployments
- Sister-repo maturity: [reuse.coulomb.social](https://reuse.coulomb.social)
  federated capability registry

---

## How It Fits

- Upstream dependencies: KeyCape (lightweight IAM implementation), Authelia, Keycloak, LLDAP, privacyIDEA
- Downstream consumers: railiance (all Railiance deployments), applications targeting the NetKingdom IAM Profile
- Often used with: key-cape (lightweight mode), railiance-platform (identity services integration), railiance-cluster (deployed on Kubernetes)

---

## Terminology

- Preferred terms: NetKingdom IAM Profile, local identity, SSO/MFA platform, bootstrap, lightweight mode, expanded mode
- Also known as: "net-kingdom"
- Potentially confusing terms: "local identity" = file-based bootstrap store (not a full LDAP); "SSO/MFA platform" = production Keycloak deployment

---

## Related / Overlapping

- `key-cape` — lightweight IAM implementation (KeyCape orchestrates Authelia+LLDAP+privacyIDEA)
- `railiance-platform` — net-kingdom identity services integrate at the platform services layer

---

## Provided Capabilities

```capability
type: security
title: NetKingdom IAM Profile specification
description: Versioned OIDC/PKCE contract that all NetKingdom applications target — canonical v0.2 defines discovery, PKCE, token, JWKS, tenant, principal-type, assurance, and flex-auth claim inputs.
keywords: [iam, oidc, pkce, profile, specification, identity, authentication]
```

```capability
type: security
title: SSO/MFA platform (Keycloak)
description: Enterprise-grade Keycloak-based SSO with LDAP/Entra federation, MFA, and full OIDC/PKCE support for production deployments.
keywords: [sso, mfa, keycloak, ldap, entra, federation, oidc, enterprise]
```

```capability
type: security
title: OpenBao unseal custody models and bootstrap automation
description: Three gated init/unseal custody models — SOPS-held automation for unattended lab rebuilds (greenfield-proven), attended ceremony with non-secret evidence records for production, and transit/KMS auto-unseal for production HA — enforced by the security bootstrap console and a lab/production deployment profile.
keywords: [openbao, unseal, custody, bootstrap, sops, age, ceremony, transit, auto-unseal, console]
```

```capability
type: security
title: Bootstrap local identity service
description: Minimal file-based OIDC server for environments where the full cluster is not yet available — covers dev, test, and sandbox bootstrapping scenarios.
keywords: [bootstrap, local-identity, oidc, minimal, dev, sandbox]
```

---

## Getting Oriented

- Start with: `wiki/` (specifications and decisions), `DECISIONS.md` (key
  architectural choices D1–D5)
- Key files / directories: `docs/platform-root-custody.md`, `sso-mfa/`
  (SSO/MFA platform + bootstrap scripts), `local-identity/`,
  `tools/security-bootstrap-console/`, `workplans/` (finished plans in
  `workplans/archived/`)
- Backlog entry points: `workplans/NK-WP-0009-netkingdom-security-pattern-tutorials.md`
  and `workplans/NK-WP-0011-enterprise-federation-saml.md`; finished context
  in `workplans/archived/`
- User-domain boundary contract:
  `canon/standards/user-engine-boundary-contract_v0.1.md`
- User-engine integration assessment (intent/scope fit, gaps, and recommendations):
  `docs/user-engine-netkingdom-integration-assessment.md`
- Bootstrap/custody entry points:
  `docs/platform-root-custody.md`,
  `docs/security-bootstrap-use-cases.md`,
  `docs/openbao-unseal-custody-models.md` (three custody models + deployment
  profile), and `docs/openbao-attended-ceremony-runbook.md` (production
  ceremony); history of the custody/bootstrap arc in `workplans/archived/`
  (NET-WP-0015–0017, 0019) and
  `workplans/NET-WP-0020-openbao-unseal-custody-and-ssh-automation.md`