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

The 2026-09-28 infrastructure review records the current evidence baseline: one Railiance node, ready lightweight identity services, six flex-auth consumers enforcing caller authentication, and private OpenBao access. Readiness and replica counts do not establish HA, user acceptance, or complete recovery. Keycloak remains backlog.

OpenBao callback/login admission (NK-WP-0032) is complete from the platform's September receipts. Operators use the named openbao-ui-railiance01 tunnel; bao.coulomb.social is retired. Scoped optional-enrollment policy and privileged MFA guards are delivered for the portal and Vergabe demo clients; NK-WP-0042 still needs a workload pilot agreement and accepted step-up/recovery journey. IAM v0.4 and Playbook Capability v0.2 remain proposed amendments.

The current owner/evidence gates are:

• NK-WP-0022: final identity-resource retirement needs recovery evidence and explicit deletion approval; its August 29 retention minimum has elapsed.
• NK-WP-0027: reef provider carrier/ceiling agreement and the authoritative public-classification maturity mapping remain external dependencies.
• NK-WP-0031: the implemented proposal-only evaluator still needs Audit Core's machine-readable authoritative ownership and E2 freshness metadata.
• NK-WP-0035: corrected candidate contract pins do not resolve source migration, local-identity's missing heartbeat, or the absent source/observer proof.
• NK-WP-0039: obsolete flex-auth reference objects have been removed; remaining tenant-engine references and repository-rename pointers await their owners.
• NK-WP-0040: execution-attribution receipt emission, custody and schema require owner agreement before an end-to-end implementation claim.
• NK-WP-0042: reuse delivered enrollment/policy components for the agreed pilot; generic workload step-up is not established by those two scoped clients.

Tutorials (NK-WP-0009) and enterprise federation (NK-WP-0011) remain backlog. NK-WP-0030's deterministic composition and NK-WP-0031's local feedback tooling are implemented; neither autonomously changes policy. Use the workplan files and generated WORK-RECORDS.md for changing task state, rather than treating this dated operating baseline as a live health report.

---

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/