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, 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 proposed
• 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/
• Open: NK-WP-0009 (security pattern tutorials) and NK-WP-0011 (enterprise federation / SAML) are proposed, 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

---

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

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]

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]

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]

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/)
• Entry points: workplans/NK-WP-0009-netkingdom-security-pattern-tutorials.md and workplans/NK-WP-0011-enterprise-federation-saml.md (proposed next work); 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