diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..725a174 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,93 @@ +# 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) +- 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) +- Security bootstrapping: credential management, SOPS/age integration, KeePassXC/Vault progression +- 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 +- 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 Repositories + +- `key-cape` — lightweight IAM implementation (KeyCape orchestrates Authelia+LLDAP+privacyIDEA) +- `railiance-platform` — net-kingdom identity services integrate at the platform services layer + +--- + +## Getting Oriented + +- Start with: `wiki/` (specifications and decisions), `DECISIONS.md` (key architectural choices D1–D5) +- Key files / directories: `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