coulomb/net-kingdom
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
net-kingdom/SCOPE.md
tegwick 9026d7f904
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 5s
Details
ADR-0014 + tenant-engine boundary contract + IAM Profile v0.3 
Ratifies the tenant capability-role model (PLTF/IAM/VEN/CUS, non-exclusive,
independent of ADR-0013's grouping axis), a hybrid carrying mechanism
(tenant-engine authoritative, key-cape caches a tenant_roles claim at
issuance, flex-auth re-validates live for aal2-class decisions), and
tenant-engine as a new, separate service owning tenant existence, grouping,
capability roles, and plan/subscription assignment -- not a module inside
user-engine, whose own boundary contract already scopes it to consuming
tenant identifiers, not owning them.

canon/standards/tenant-engine-boundary-contract_v0.1.md defines that
ownership boundary before the repo exists, mirroring how
user-engine-boundary-contract_v0.1.md was sequenced.

canon/standards/iam-profile_v0.3.md (minor version per ADR-0011's own
governance -- optional claim addition, no breaking change) adds the
tenant_roles claim, folds in ADR-0013's tenant-identifier vocabulary, and
documents the live-revalidation requirement. docs/platform-identity-
security-architecture.md's Tenant Model section and SCOPE.md's canonical
spec pointer updated to match; other historical citations of v0.2 left as
version-pinned references, not bulk-updated.

Records Bernd's trial-tenant policy: trial-grouped tenants may hold any
capability role (showcase/test/explore), with safety enforced through
tenant-engine-owned resource guardrails (spend limits, entity/action
counts) rather than role gating -- guardrail design is reserved, explicitly
not specified by this change.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-23 21:45:37 +02:00

7.4 KiB
Raw Blame History

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 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

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/)
  • 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