the-custodian/docs/netkingdom-security-blueprint.md

# NetKingdom security architecture blueprint

Reviewed 2026-10-12. Implementation tracking: CUST-WP-0080 and the existing owner
plans in [the gap analysis](netkingdom-security-gaps.md). This is an estate
architecture assessment, not a new standard or an assertion of production
conformance. `ops-waren` in the request is interpreted as `ops-warden`.

NetKingdom realizes security through separate identity, authorization, approval,
credential lifecycle and evidence boundaries. Its main weakness is incomplete
integration between those boundaries: a successful login, an accepted design or
a passing local verifier does not establish a working protected operation.

## Governing sources

- [SecurityCanon SEC-DSM 1.0](../../security-canon/infospace/standards/devops-secrets-management/SecurityCanonDevOpsSecretsManagementStandard.md)
  defines the credential lifecycle and preference for native identity, federation,
  ephemeral credentials, automatic rotation, then governed static exceptions.
- [NetKingdom layer model v0.8](../../net-kingdom/canon/standards/security-layer-model_v0.8.md)
  is accepted. v0.9 is proposed; its bounded doctrine approval does not constitute
  acceptance of the whole revision. The [companion](../../net-kingdom/SECURITY-COMPANION.md)
  is derived operational guidance.
- [SecurityCaseTypes](../../net-kingdom/canon/standards/security-case-types_v0.1.md)
  defines reusable types, instance acceptance, structural materialization and
  follow-through. Type acknowledgment, case acceptance and native verification
  are distinct gates.
- [Build-mode authorization](../canon/standards/build-mode-change-authorization_v0.1.md)
  permits reversible live changes with reviewed diff, rollback, abort owner and
  receipt. Scope expansion and public publication remain founder-gated; acts
  requiring the founder's identity remain attended. Neither tool availability nor
  this blueprint expands an agent's authority.

## Responsibility and trust boundaries

| Component | Security responsibility | Boundary |
| --- | --- | --- |
| security-canon | General secrets practice, authority vocabulary | Does not operate estate security |
| net-kingdom | Estate standards, IAM profile, case schemas and compositions | Taxonomy; retained bootstrap runtime code is declared residue |
| gate-house | Doctrine, interpretation, teaching and review | Staff; no operational PDP or credential issuer |
| key-cape | Authentication and signed identity/assurance | Current lightweight stack uses Authelia, LLDAP and privacyIDEA; Keycloak is an expanded-mode option |
| user-engine | User facts and account, MFA and recovery journeys | Advisory application readback does not enforce access at the application |
| tenant-engine | Tenant facts and governance within platform limits | PIP; tenant authority can narrow, never widen the platform envelope |
| zone-engine | Zone identity, membership and control-profile reference | Offline conformance implementation, not a live zone service |
| approval-engine | Authenticated, bound, expiring, consumable approval objects | PIP; approval is an input to authorization, not permission itself |
| access-engine | Operational policy decision point | Repository/binary renamed; live namespaces, audiences and pins still include `flex-auth` |
| maturity-engine | Evidence-based progression and conformance facts | PIP; consumers must not turn a grade into a second authorization decision |
| secrets-engine | Deterministic credential lifecycle and delivery | Consumes decisions; OpenBao holds custody and enforces native scope |
| ops-mason | Reviewed structural construction | Staff and PEP-shaped; founder plan gate is an accepted exception, not PDP conformance |
| ops-warden | Lane discovery, SSH certificate issuance and case follow-through | Staff and PEP-shaped; route discovery grants no access; declared direct-tooling gaps remain |
| ops-bridge | Private transport | A tunnel is neither authentication nor authorization |
| audit-core | Independent event custody and integrity | Custody proves integrity after arrival, not completeness of source emission |
| kings-guard / whitehat-security | Observation / scoped adversarial evidence | Findings and proposed containment; not direct arbitrary actuation |
| informed-decision / policy-nexus | Human disposition / publication | Presentation and publication neither ratify policy nor enforce it |
| glas-harness / sand-boxer / reins | Agent execution, tool access and isolation | Effective authority includes actions reachable through hidden tool credentials |
| Railiance owners and `rapp-*` packages | Deployments, OpenBao operation, delivery and recovery | Concrete scope, runtime receipts and rollback stay with the owner |
| role-engine | Organizational role definitions | Documentation catalog, not IAM roles or a runtime authorization engine |

Repository INTENT declarations govern layers. The table describes responsibilities
from current INTENT/README files and owner plans; it is not a fleet readiness claim.

## Runtime path

```mermaid
flowchart TD
    H[Human with MFA] --> I[KeyCape identity]
    W[Workload or CI identity] --> P[Protected operation and enforcement point]
    I --> P
    A[Approval Engine] -->|bound approval claim| D[Access Engine PDP]
    F[User and tenant facts; admitted zone and maturity claims] --> D
    P -->|canonical request and authenticated caller| D
    D -->|bound decision and lifetime| P
    P -->|when identity is sufficient| N[Native identity target]
    P -->|when a credential is required| S[Secrets Engine lifecycle]
    S --> B[OpenBao custody and native policy]
    B --> C[Direct or ephemeral delivery]
    B --> E[ESO compatibility projection]
    C --> T[Exact consumer]
    E --> T
    P --> O[Local durable emission]
    S --> O
    O --> U[Audit Core custody]
    U --> K[Independent reconciliation and monitoring]
```

This is the intended integrated path. It does not imply that every arrow has a
live implementation. In particular, task-scoped OpenBao execution, agent runtime
isolation and complete source-to-archive evidence remain open owner work.
Native target authentication avoids unnecessary credential issuance while retaining
the estate's policy and evidence obligations; it is not a PDP bypass.

An operation binds initiating actor, represented principal, tenant, environment,
resource, action, purpose, policy revision, canonical request digest and lifetime.
The enforcing component checks those bindings and consumes a required approval
before the effect. Persisted intent and idempotency distinguish safe retry from
an uncertain effect. An uncertain outcome requires reconciliation; it cannot be
silently replayed. Each PEP publishes its actual unreachable-engine stance, and
records its application. A blanket fail-closed claim would misdescribe currently
accepted per-zone stances and Mason's explicit construction exception.

Decision provenance requires independently trusted issuer authentication as well
as a matching request digest. Access Engine implements optional Ed25519 envelope
signing (FLEX-WP-0024), but an unconfigured signer explicitly emits unsigned
decisions. Secrets Engine now confines Check requests to literal loopback origins,
refuses redirects and disables ambient proxies, including the approval-flow call
site. Its response size/encoding bounds fail closed. Those transport controls
are not signature verification. SECRETS-WP-0014 owns the remaining trust work.
Full producer configuration, trusted key distribution and consumer
verification therefore remain a distinct gap; a digest over public inputs cannot
authenticate an allow response.

## DevOps credential paths

| Use | Preferred realization | Current limitation or proof boundary |
| --- | --- | --- |
| Kubernetes workload reads exact secret | Projected ServiceAccount → exact OpenBao role/policy → consumer | Per-consumer namespace, audience, TTL and path checks; ESO is a delivery copy |
| Service uses protected OpenBao action | Service identity plus exact task approval/PDP → bounded owner entitlement | CCR38 login is identity-only. SECRETS-WP-0013 and RPF-WP-0035-T12 still own protected execution |
| CI builds or publishes | Execution identity → narrowly scoped capability | Repository/pipeline writers can affect credential access; whole-fleet federation and scanning coverage are unverified |
| Browser application sign-in | IAM profile → relying party → application enforcement | Forgejo reference case still lacks full native materialization/follow-through proof |
| Operator access | Attended identity and MFA → reviewed contained command → confirmed revocation | Founder presence remains required for the native login; no secret values in receipts |
| SSH automation | Warden decision-bound signing → bounded SSH certificate | Direct OpenBao signing is a declared engine gap; transport is owned by ops-bridge |
| Legacy SaaS or static client credential | OpenBao authority → exact consumer projection → adoption-tested rotation | Every remaining credential needs owner, consumers, scope, rotation, revocation and elimination trigger |
| Agent execution | Distinguishable task identity → deterministic tool gate → bounded capability | Current Custodian supervision is not enforced credential isolation; CUST-WP-0073/GLAS-WP-0012 remain open |

Bootstrap preparation now encrypts with an independently registered public age
recipient. The compatibility bootstrap command requires an attended operator
terminal; encrypted resume uses only an explicitly supplied temporary matching
custody key. Recovery handoff emits the encrypted artifact's location/digest and
a non-secret guide, never the private key. Its acknowledgment is not a recovery
proof. Remaining direct custody callers and native recovery are NK-WP-0049; tty
presence itself establishes neither caller identity nor agent isolation.

The current KeyCape profile does not require the old Keycloak trigger-admin
bootstrap credential. Source bootstrap now provisions/verifies only pi-admin and
its scoped local-admin policy; existing accounts/policies are never overwritten.
Legacy live objects still require consumer inventory and approved revocation.
KeyCape's separate pi-admin token path remains a privileged static compatibility
path: its authority, duplicated projections, refresh, custody and revocation are
not closed by this bootstrap repair. Native policy/MFA acceptance remains distinct
from successful account/password verification. [Source proof and limits](evidence/2026-10-12-netkingdom-security/admin-bootstrap.json).

Response wrapping reduces delivery exposure and supports one-time retrieval.
It does not decide who may obtain a grant, restrict the authority of the unwrapped
credential, or revoke that credential. The reviewed wrapped-delivery primitive
therefore cannot substitute for the missing protected-execution entitlement.

Rotation completes only after replacement issuance, delivery, consumer adoption,
positive validation and predecessor refusal/revocation. OpenBao KV version change
or an ESO Ready condition alone is insufficient. Startup-only consumers need a
controlled reload/restart and rollback strategy; restoring an old value is safe
only if its authority remains valid and unexposed.

Repository prevention uses Repo Manager as a control adapter, with the external
scanner owning detection rules and Forge owning independent push/CI enforcement.
The reviewed shared hook and Custodian local hook now compose generated-only
commit rejection with pinned, content-silent staged-blob scanning for 22 exact
workstation checkout paths. Actual hooks passed clean, disposable-key rejection
and scanner-failure checks; other hooks/routing and unreviewed checkout behavior
were preserved. RMGR-WP-0021-T02 records local activation; independent forge/CI
enforcement and response remain open. [Activation receipt](evidence/2026-10-12-netkingdom-security/secret-hook-activation.json). FORGE-WP-0006 now supplies the independent introduced-history adapter in source;
its disposable push tests do not establish server activation or complete repository
coverage. A local hook is bypassable,
so it cannot substitute for independent introduced-history checks or governed
incident response. [Coverage evidence](evidence/2026-10-12-netkingdom-security/secret-detection.json).

## Roots, outages and recovery

The root register must cover OpenBao unseal/recovery authority, age/SOPS decryption,
identity signing and directory administration, SSH CA, Kubernetes control-plane
authority, provider/host console and backup decryption. These are candidates
identified from credential-management v0.2 and platform procedures, not a complete
discovered root inventory. The issuer and its backups must be recoverable without
first obtaining a credential from that same unavailable issuer.

The founder's October 11 decision retains single-holder unseal/recovery custody
during build mode and requires quorum review before customers. Single-node/shared
control-plane risk is accepted for build mode. Neither decision proves a restore
drill, establishes independent audit administration, nor grants routine agent
access to roots. Native recovery must verify isolated restore, consumer
reconnection, audit continuity, expiry/revocation and return to ordinary custody.

Issuer outages need explicit bounded behavior: continue only already-valid leases
where policy permits, stop renewal-dependent effects when they expire, surface
failure without credential content, and use a separately governed recovery path.
No indefinite cache or fallback to an ambient admin token is an acceptable
implicit recovery mechanism.

## Architecture inspection and optimizations

| Inspection finding | Optimization incorporated | Verification |
| --- | --- | --- |
| Brokerage could be inserted for every operation | Evaluate SEC-DSM Q1–Q5 for each integration; prefer direct/federated identity | Record target capability and reason for every remaining persistent credential |
| Mason materialization and Warden execution could wait on one another | Structural receipt precedes credential mint and follow-through | No mint/session success required to label structure complete; no execution before authenticated structure receipt |
| Login success could be mistaken for authority | Keep identity-only CCR38 separate from task-bound execution grant | Wrong actor/action/body/path, expiry, replay and unavailable-owner negative checks |
| Every service could implement its own policy decision | Keep one PDP; approval, tenant, maturity and zone engines supply facts | Bound claim verification and cross-tenant/cross-request denial tests |
| Public request digests could be mistaken for PDP authentication | Require independently trusted channel or signed decision verification at each consumer | Forged allow, altered envelope, unknown/retired key and unsigned downgrade refusals |
| Reusable types could conceal version drift | Pin type, case, provider interfaces and accepted digests | Reject changed/unimplemented types and stale acceptance; reconcile uncertainty before replay |
| Local tests could masquerade as deployment proof | Distinguish source, materialized, executed and natively verified evidence | Each gap closes only on its own named evidence; no inherited consumer completion |
| Audit durability could masquerade as completeness | Durable local emission plus admitted sender, heartbeat and reconciliation | Crash/failure test, archive readback and source-transition reconciliation |
| Static custody metadata omits lifecycle obligations | Extend existing owner inventory rather than create another vault | Coverage denominator, unknown owner findings, rotation/adoption and revocation evidence |
| Security controls make recovery unusable | Repair real MFA recovery and provide reachable lost-factor help | DN-shaped actor regression, value-free diagnostics and attended U08 acceptance |
| Production policy could be inferred from build defaults | Keep accepted exceptions and close-down obligations explicit | Requirement, system, owner, risk, controls, approval and expiry/review trigger |

The inspection rejects a new umbrella broker, a second PDP, automatic maturity
gates and blanket new infrastructure. Existing owner contracts supply the needed
seams. The fastest useful implementation sequence is the real identity recovery
defect, one complete SecurityCase, then reusable task-scoped credentials and
consumer lifecycle proof. Inventory, detection and exception reconciliation proceed
alongside this sequence because they expose risks beyond the pilot.

## Evidence and completion

The [gap analysis](netkingdom-security-gaps.md) maps SEC-DSM families to current
evidence and exact owner plans. The source inventory records repository revisions
and open tasks, including separately identified residuals. Residuals are not
silently promoted. A gap is addressed only by verified implementation or an
explicitly approved, fully specified exception; a new plan alone does not close it.