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