# 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 and externally declared KeyCape C1+C2b plan-only composition slices. 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 ```capability 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] ``` ```capability 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] ``` ```capability 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: 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/`