net-kingdom/SCOPE.md

SCOPE

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

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

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

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.
• Security Scenario Composition v0.1 for deterministic provider selection, trust ordering, responsibility mapping, and non-executing owner handoff.
• Posture Feedback v0.1 for deterministic, proposal-only routing of posture review, evidence-freshness, implementation, and declared-gap findings.
• 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, posture-feedback, custody, evidence, and bootstrap-policy validators.
• tools/security-scenario-composer/: fail-closed, plan-only composition of declared capabilities, parameters, trust transitions, responsibilities, and readiness obligations.
• tools/posture-feedback/: deterministic, time-explicit remediation proposals with authoritative owner resolution and no external or policy writes.
• 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.

---

Authority Boundaries

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, greenfield OpenBao init/unseal proof, and deterministic plan-only C0 composition	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, and deterministic owner-routed remediation proposals	First proposal-only feedback loop delivered; no autonomous policy mutation or 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. NK-WP-0030 has delivered the local C0 scenario-composition slice and waits for externally owned C1/C2 provider declarations before the lightweight SSO scenario can compose. NK-WP-0031 has delivered the local proposal-only feedback evaluator and waits for authoritative freshness adoption by audit-core.

---

Relevant When

• 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, posture feedback report, 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

• 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

type: governance
title: NetKingdom security canon
description: Provider-neutral IAM v0.3, user/tenant boundaries, credential, playbook and scenario composition, tenancy-posture, posture-feedback, and workload-zone standards with explicit ownership and conformance rules.
keywords: [iam, oidc, tenancy, workload-identity, security-zones, credentials, canon]

type: validation
title: Security contract conformance
description: Executable validation for IAM Profile issuers, playbook capability declarations, tenancy posture, deterministic proposal-only feedback, bootstrap custody, and non-secret evidence records.
keywords: [validation, conformance, iam, posture, feedback, evidence, playbooks]

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]

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

• 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, and tools/security-bootstrap-console/
• Executable surfaces: local-identity/, tools/iam-profile-conformance/, tools/playbook-capability-contract/, tools/security-scenario-composer/, tools/tenancy-posture/, and tools/posture-feedback/
• Work state: .custodian-brief.md and workplans/