docs(scope): reconcile capability with intent
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02929-244b-7391-b933-c04010e8eedb
This commit is contained in:
parent
2c8a296c3a
commit
6204184930
4 changed files with 351 additions and 117 deletions
254
SCOPE.md
254
SCOPE.md
|
|
@ -1,168 +1,188 @@
|
|||
# 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.
|
||||
> This file describes the repository's current capability and authority.
|
||||
> `INTENT.md` remains the aspirational direction; the difference is assessed in
|
||||
> `history/2026-08-23-scope-intent-gap-assessment.md`.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Canonical security architecture and bootstrap/reference implementation for
|
||||
NetKingdom: defines identity, tenancy, workload-zone, credential, and
|
||||
orchestration contracts; supplies conformance and bootstrap tooling; and
|
||||
coordinates their realization across KeyCape, flex-auth, OpenBao, and
|
||||
Railiance.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
This repository is NetKingdom's security canon and integration hub. It defines
|
||||
provider-neutral contracts and responsibility boundaries, provides executable
|
||||
validators and bootstrap/reference tooling, and records how independently owned
|
||||
services compose into a security control plane.
|
||||
|
||||
It does not own every runtime that realizes those contracts. Service
|
||||
implementations, Kubernetes infrastructure, platform data services, and managed
|
||||
deployment packages remain in their respective repositories. The dynamic,
|
||||
self-optimizing platform in `INTENT.md` is the direction of travel, not a claim
|
||||
about the current implementation.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
### Canon and architecture
|
||||
|
||||
- NetKingdom IAM Profile v0.3: the accepted provider-neutral OIDC/PKCE,
|
||||
principal, tenant, workload-identity, assurance, and flex-auth input contract.
|
||||
- Accepted user-engine and tenant-engine boundary contracts.
|
||||
- Credential Management Standard v0.2 and the platform-root/OpenBao custody
|
||||
model.
|
||||
- Playbook Capability Contract v0.1 for the boundary between NetKingdom
|
||||
selection/parameterization and Railiance execution.
|
||||
- Tenancy Posture v0.1 and Security Zones v0.1 proposed standards, their schemas,
|
||||
validators, evidence rules, and publication stewardship. Zone semantics are
|
||||
owned by `zone-engine`; NetKingdom owns their canon publication.
|
||||
- Architecture decisions and the cross-repository responsibility map for
|
||||
identity, authorization, credentials, tenancy, and bootstrap trust.
|
||||
|
||||
### Executable reference and verification surfaces
|
||||
|
||||
- `local-identity/`: minimal file-backed OIDC identity for bootstrap,
|
||||
development, test, and sandbox use.
|
||||
- IAM Profile, playbook-capability, tenancy-posture, custody, evidence, and
|
||||
bootstrap-policy validators.
|
||||
- `tools/security-bootstrap-console/`: guarded platform-root and OpenBao
|
||||
bootstrap workflow, including refusal of unsafe live initialization.
|
||||
- SOPS/age bootstrap integration, credential-generation and rotation helpers,
|
||||
and documented attended, automated-lab, and auto-unseal custody paths.
|
||||
- Reference and migration-stage manifests/runbooks for the current lightweight
|
||||
identity stack: KeyCape, Authelia, LLDAP, and privacyIDEA.
|
||||
|
||||
### Integration and meta-orchestration contracts
|
||||
|
||||
- Capability selection, safe parameterization, trust-state requirements, and
|
||||
responsibility assignment across Railiance playbooks.
|
||||
- User/tenant onboarding boundaries, issuer/client registration patterns,
|
||||
caller identity, workload identity, authorization inputs, and audit evidence.
|
||||
- Cross-repository workplans and decision records needed to converge security
|
||||
providers without absorbing their implementations into this repository.
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
## Authority Boundaries
|
||||
|
||||
- Kubernetes runtime concerns → railiance-cluster
|
||||
- Platform services (PostgreSQL, storage, caches) → railiance-platform
|
||||
- Application deployments → railiance-apps
|
||||
- KeyCape implementation details → key-cape
|
||||
This repository owns security semantics and composition rules. It does not own:
|
||||
|
||||
- KeyCape's implementation (`key-cape`)
|
||||
- authorization service implementation or policy evaluation (`flex-auth` and
|
||||
its PDP adapters)
|
||||
- runtime secret-service deployment (`railiance-platform` / OpenBao)
|
||||
- Kubernetes and host infrastructure (`railiance-cluster`,
|
||||
`railiance-infra`)
|
||||
- SSH certificate issuance or tunnels (`ops-warden`, `ops-bridge`)
|
||||
- user or tenant service implementation (`user-engine`, `tenant-engine`)
|
||||
- managed application packages (`rapp-*` repositories)
|
||||
- generic platform data services such as PostgreSQL and storage
|
||||
(`railiance-platform`)
|
||||
|
||||
The material under `sso-mfa/k8s/` includes live-proven integration history and
|
||||
migration inputs. It is not blanket authority for managed runtime deployment.
|
||||
ADR-0015 moves package/application ownership to the relevant `rapp-*`
|
||||
repositories while NetKingdom retains the contracts and reference evidence.
|
||||
|
||||
---
|
||||
|
||||
## Current Capability
|
||||
|
||||
| Tier | Current repository/estate capability | Delivery state |
|
||||
| --- | --- | --- |
|
||||
| C0 — Bootstrap identity | Local OIDC identity, SOPS/age bootstrap, guarded credential workflow, and greenfield OpenBao init/unseal proof | Implemented as reference/bootstrap tooling |
|
||||
| C1 — Lightweight SSO | IAM-profile-based KeyCape composition using Authelia and LLDAP | Live-proven integration; implementation externally owned |
|
||||
| C2 — MFA/token authority | Authelia factors and privacyIDEA integration | Live-proven integration; implementation externally owned |
|
||||
| C3 — Runtime secrets | OpenBao custody, bootstrap, policy, delivery, and recovery contracts | Integrated with an externally deployed runtime; production evidence remains gated |
|
||||
| C4 — Fine-grained authorization | flex-auth caller identity and boundary integration | Partially delivered; full estate/PDP readiness is not established here |
|
||||
| C5 — Enterprise federation | Keycloak/SAML/enterprise-IdP design | Backlog; not a current provided runtime capability |
|
||||
| C6 — Self-optimizing security | Declarations, validators, evidence freshness, workplans, and drift surfacing | Early governance mechanisms only; no autonomous closed loop |
|
||||
|
||||
Current open work as of 2026-08-23 is either externally blocked, date-gated, or
|
||||
explicit backlog: reef carrier/public-classification decisions in NK-WP-0027,
|
||||
the NK-WP-0022 retirement gate, security tutorials in NK-WP-0009, and
|
||||
enterprise federation in NK-WP-0011.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
- Defining or reviewing identity, tenancy, workload-zone, credential, and
|
||||
security-composition canon.
|
||||
- Bootstrapping identity and trust before the normal platform is available.
|
||||
- Validating an IAM issuer, posture declaration, or Railiance capability
|
||||
declaration against NetKingdom contracts.
|
||||
- Integrating KeyCape, flex-auth, OpenBao, user-engine, tenant-engine, or a
|
||||
Railiance package across an explicit security boundary.
|
||||
- Deciding which repository owns a security semantic, runtime, deployment, or
|
||||
evidence obligation.
|
||||
|
||||
## 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
|
||||
- Implementing a provider's internal service behavior: work in that service's
|
||||
repository.
|
||||
- Provisioning hosts or Kubernetes: use `railiance-infra` and
|
||||
`railiance-cluster`.
|
||||
- Operating generic platform services: use `railiance-platform`.
|
||||
- Shipping a managed application package: use its `rapp-*` repository.
|
||||
- Treating the proposed Keycloak expanded mode or autonomous adaptation as an
|
||||
already delivered feature.
|
||||
|
||||
---
|
||||
|
||||
## 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]
|
||||
type: governance
|
||||
title: NetKingdom security canon
|
||||
description: Provider-neutral IAM v0.3, user/tenant boundaries, credential, playbook-composition, tenancy-posture, and workload-zone standards with explicit ownership and conformance rules.
|
||||
keywords: [iam, oidc, tenancy, workload-identity, security-zones, credentials, canon]
|
||||
```
|
||||
|
||||
```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]
|
||||
type: validation
|
||||
title: Security contract conformance
|
||||
description: Executable validation for IAM Profile issuers, playbook capability declarations, tenancy posture, bootstrap custody, and non-secret evidence records.
|
||||
keywords: [validation, conformance, iam, posture, evidence, playbooks]
|
||||
```
|
||||
|
||||
```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]
|
||||
type: tooling
|
||||
title: Guarded security bootstrap
|
||||
description: Local bootstrap identity plus SOPS/age and OpenBao custody workflows that establish trust while refusing unsafe or unevidenced live initialization.
|
||||
keywords: [bootstrap, local-identity, openbao, sops, age, custody, recovery]
|
||||
```
|
||||
|
||||
```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]
|
||||
type: governance
|
||||
title: Security meta-orchestration boundary
|
||||
description: Contracts and responsibility maps for selecting and parameterizing externally executed Railiance security capabilities without reimplementing their deployment mechanics.
|
||||
keywords: [meta-orchestration, railiance, responsibility, capability, trust-state]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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`,
|
||||
- Direction: `INTENT.md`
|
||||
- Current-vs-intended assessment:
|
||||
`history/2026-08-23-scope-intent-gap-assessment.md`
|
||||
- Canon: `canon/standards/`, `canon/schemas/`, and `docs/adr/`
|
||||
- Architecture and ownership: `docs/platform-identity-security-architecture.md`
|
||||
and `docs/responsibility-map.md`
|
||||
- Bootstrap/custody: `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`
|
||||
`docs/openbao-unseal-custody-models.md`, and
|
||||
`tools/security-bootstrap-console/`
|
||||
- Executable surfaces: `local-identity/`, `tools/iam-profile-conformance/`,
|
||||
`tools/playbook-capability-contract/`, and `tools/tenancy-posture/`
|
||||
- Work state: `.custodian-brief.md` and `workplans/`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue