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.2.md`)
- SSO/MFA Platform: Keycloak with LDAP/Entra federation, enterprise identity (NK-WP-0001)
- Local Identity: file-based user store + minimal OIDC server for bootstrap phase (NK-WP-0002)
- 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
- 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 (design phase complete, implementation ongoing)
- Implementation: emerging — NK-WP-0001 (SSO/MFA) and NK-WP-0002 (local identity) both in active development
- Stability: evolving
- Usage: foundational authentication layer for all NetKingdom deployments

---

## 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: 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/`
  (NK-WP-0001 active workplan), `local-identity/` (NK-WP-0002),
  `workplans/`
- Entry points: `workplans/NK-WP-0001-sso-mfa-platform.md` and `NK-WP-0002-local-identity.md` for current work
- 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`,
  `workplans/NET-WP-0015-platform-root-custody-and-openbao-identity-bootstrap.md`,
  and `workplans/NET-WP-0016-guided-security-bootstrap-experience.md`