the-custodian/docs/netkingdom-security-architecture-review.md

NetKingdom security architecture and framework reuse review

Assessed 14 October 2026 under CUST-WP-0081.

NetKingdom is a credible modular security architecture with working components, but the assembled security framework is still at an integration stage. Its strongest design decision is the separation of identity, authorization, approval, credential lifecycle and evidence. The highest-return work is to prove and package the interfaces between these components, then use measured operational feedback to improve them. Building another coordinating security service would increase the integration burden.

The review covers 60 capability-owning repositories and 70 reusable capability boundaries, plus two inspected nonproviders, listed in the capability inventory. The inventory records each capability's owner, interface, supported use cases, maturity vector, operational estimate, limitations and source links. Source revisions and hashes bind this assessment to the inspected worktrees, including their pre-existing changes.

Scope and evidence

Included repositories either define NetKingdom security semantics, implement a security responsibility, host a security component, or provide a direct execution, detection, recovery or improvement dependency. “All relevant” means this architectural dependency boundary, not every application that logs in. A capability is a separately consumable contract or tool surface; individual functions and endpoints are grouped where they share a lifecycle and owner.

The principal consumers are humans, workload operators, developers, security reviewers, coding agents and framework adopters. Forgejo, Markitect and Qonto Assistant are integration examples, not additional security authorities. CommerceCanon and role-engine are not identity or access-control engines; role-engine is included explicitly to resolve that misleading name. Keycloak is an expanded-mode option; the present KeyCape stack uses Authelia, LLDAP and privacyIDEA. OpenBao and those upstream products are dependencies, not additional local repositories. Helm/ArgoCD/ESO/CNPG/Gitleaks similarly appear under their local owners. The derived rail-knative execution contract and rapp-sbom-nexus runtime package are included. rapp-secrets-engine is retired; rapp-forgejo is a placeholder with no family declaration. Neither contributes a delivered capability. Optional business application packages, external-tracker packaging, generic hub implementation dependencies and unrelated business systems are outside the denominator.

Evidence precedence is executable owner source and specific dated acceptance receipts, then current workplans and scope declarations, then registry metadata. An implemented API, a deployed service and a verified consumer journey are separate claims. No new live penetration test, credential read, recovery drill or deployment is implied by this review. The previous blueprint, gap analysis and owner plans supply detailed native evidence. Their dated progress must be read as a timeline: the blueprint's original 22-repository scanner observation is superseded by the October 13 forge expansion evidence.

The Emergent Security orientation check returned package 0.2.6, digest 8d1d6a9d4d07fec7b619618de7dfe2be2254c1790f85f4198c7fe19db9751c02, with the start card withheld for source drift. Owner sources were therefore inspected directly. Withholding is a useful integrity control; the stale orientation still causes avoidable integration effort.

Architectural responsibilities

Plane	Owners	Reusable contract and boundary
Semantics and doctrine	security-canon, info-tech-canon, net-kingdom, gate-house	Vocabulary, IAM and security layer standards, case types, authority context and conformance criteria. Doctrine enters runtime as claims or versioned policy.
Identity and facts	key-cape, user-engine, tenant-engine, zone-engine, maturity-engine	Identity/assurance and bounded facts. Zone Engine is an offline reference; Maturity Engine has source/library delivery, not an asserted production service.
Authorization and approval	access-engine, approval-engine, informed-decision	Access Engine owns policy decisions. Approval Engine owns bound approval state and atomic consumption. Informed Decision presents human choices and preserves their disposition.
Credential and operation lifecycle	secrets-engine, ops-warden, ops-mason, ops-bridge	Catalog and lifecycle, access routing/SSH issuance, reviewed structure construction and private transport. These are distinct authorities.
Evidence and improvement	audit-core, kings-guard, whitehat-security, risk-nexus, railiance-telemetry	Independent custody, posture evaluation, authorized adversarial proof, risk judgments and operational signals. Detection and proposals do not authorize containment.
Agent execution	glas-harness, sand-boxer, reins, agentic-resources	Profile selection, isolation, actual tool execution and measured learning. Effective authority includes credentials reachable through tools.
Platform realization	Railiance owners, rail-kubernetes, reef-railiance and rapp packages	Concrete hosts, cluster, custody, packages, deployment, backup and recovery. Package readiness does not certify an entire security workflow.
Discovery and coordination	reuse-surface, repo-manager, state-hub, the-custodian, coordination-engine, activity-core	Find existing capabilities, retain owner-backed work records and schedule bounded work. None substitutes for runtime approval or independent audit custody.

“One PDP” means one decision-owning engine and contract, not one global process. Access Engine deliberately uses consumer-specific deployment pins. Consolidating all pins into a shared availability and trust domain without measurements would weaken the current isolation design. The flex-auth name persists in runtime audiences and endpoints during the source rename; that is migration compatibility, not another decision engine.

flowchart LR
    I[KeyCape identity and assurance] --> P[Consumer enforcement point]
    F[User tenant zone and maturity facts] --> D[Access Engine decision]
    H[Human via Informed Decision] --> A[Approval Engine bound approval]
    A --> D
    P --> D
    D --> P
    P --> C[Consume required approval]
    C --> N[Native target identity or scoped credential lifecycle]
    N --> S[Secrets Engine and OpenBao]
    S --> T[Exact protected operation]
    P --> E[Durable source emission]
    T --> E
    E --> U[Audit Core custody and reconciliation]
    U --> K[Posture and risk findings]
    K --> R[Owner review and bounded improvement]
    R --> H

The diagram is the composition contract, not an assertion that every connection has native acceptance. Direct native identity should avoid credential issuance where possible; it does not bypass the applicable authorization or evidence obligations.

Supported use cases

“Available” identifies a bounded delivered surface with owner evidence. “Partial” means useful components exist while the integrated outcome retains named gates. “Reference” means local planning or validation, without a live enforcement claim.

ID	Actor and outcome	Support today	Composition and decisive limit
U01	Architect composes a new service's security model	Available for contracts and reference planning	NetKingdom conformance, scenario composer, case types, Gate House and reuse-surface. Provider selection and trust ordering are deterministic; execution remains explicitly disabled in the composer.
U02	Human signs in, steps up MFA and manages account/factor recovery	Available sign-in; partial recovery and automated browser access	KeyCape + User Engine + relying-party enforcement. Real-factor recovery acceptance remains KEY-WP-0040/U08. Rapp Playwright has a deployed pilot, but human/agent self-service identity and connectivity are pending.
U03	Application applies tenant-aware, resource-specific access	Available components; partial uniform enforcement	KeyCape/User/Tenant facts → Access Engine → application PEP. Wrong tenant, stale claims, replay and unavailable dependencies must be tested per consumer. Offline zone reference cannot supply a live claim service.
U04	Approver authorizes an exact protected action once	Partial integrated journey	Informed Decision → Approval Engine claim → PDP decision → atomic consume → PEP effect. Approval service deployment exists; named PEP execution and exact native issuer/tenant acceptance remain APPROVAL-WP-0002 gates.
U05	Operator provisions and delivers a narrow workload credential	Available bounded legacy lanes; partial task-scoped path	Warden route → Mason structure → Secrets Engine lifecycle → OpenBao. CCR38 service login is identity-only. SECRETS-WP-0013 and platform entitlement acceptance still govern protected execution.
U06	Human or automation obtains SSH access and private connectivity	Available bounded paths	Warden certificates, host principal mapping and Bridge tunnel lifecycle. A tunnel or valid certificate does not establish application authorization. Operator-only MFA/login acts remain attended.
U07	Owner inventories credentials, rotates/revokes them and detects exposure	Partial lifecycle and estate coverage	Secrets Engine catalog + platform custody + owner consumer inventory + Repo Manager/Forge scanning. Rotation needs adoption and predecessor refusal, not merely a changed KV value. Import/mirror and detection-to-response gaps remain.
U08	Producer retains attributable security events and detects missing evidence	Available custody and local contracts; partial source coverage	Source outbox → Audit Core → cadence/heartbeat/reconciliation → telemetry/Guard. Independent arrival integrity cannot establish events a compromised source omitted. Sender and emission-class admission stay explicit.
U09	Maintainer improves posture from recurring evidence	Available assessment/proposal tools; partial closed loop	Posture Feedback, Maturity Engine, Guard, Risk Nexus, Activity Core and owner work records. Unassisted schedule, owner adoption and verified outcome feedback are not uniformly established. No adaptive component may grant new authority.
U10	Operator restores identity, roots or platform data	Available scoped procedures and some data restore evidence; partial estate recovery	Owner runbooks, encrypted custody, Rapp OpenBao/Postgres and independent recovery resources. Full root inventory, independent issuer bootstrap and estate-native recovery gates remain NK-WP-0049 and the close-down checklist.
U11	Coding agent performs a bounded attributable task	Available source/runtime pieces; partial privileged isolation	Glas + Sand-boxer + rein + supervision receipts. CUST-WP-0073/GLAS-WP-0012 do not yet establish this interactive agent's enforced credential separation or autopilot.
U12	Developer builds and publishes with source and dependency controls	Available components; partial supply-chain boundary	Forge + Repo Manager + SBOM Nexus + Enablement + Apps. Hosted runners remain a privileged shared boundary; scanning, required checks, artifact provenance and per-job credentials have different coverage.
U13	Platform owner deploys, observes and rolls back a security workload	Available owner/package paths	Infra → Cluster → Platform → rail/rapp/reef bindings. Current single-node and headroom limits affect availability and rollout; a package declaration alone proves no consumer acceptance.
U14	Adopter builds a security framework from reusable parts	Available contracts/tools; partial portable product	Start with the profile below and independently validate each adapter. There is no proven estate-independent one-command distribution or measured second installation.

Use-case mapping is many-to-many in the inventory and registry entries. A listed supporting capability inherits neither the whole journey's maturity nor its authorization.

Maturity estimate

This review uses a local operational scale: M1 described, M2 implemented/reference, M3 repeatedly operated for a bounded scope, M4 measured integrated operation with lifecycle/failure coverage, M5 improvement validated across repeated cycles. These are estimates, not certification or NIST tiers. NIST distinguishes CSF implementation tiers from maturity levels. NIST guidance.

The separate reuse-surface D/A/C/R vector means discovery, availability form, consumer completeness and consumer reliability. A0 can be the correct destination for a standard; A4 API availability does not imply mature operations. Existing C/R claims are retained as owner assessments where present, not independently recertified. New entries use conservative C1/R0 until consumer evidence supports more. See the registry maturity standard.

Dimension	Estimate	Basis and evidence needed to advance
Responsibility model and governance	M3; medium-high confidence	Accepted layer model and concrete owner boundaries, with explicit exceptions. Advance through continuously checked implementation/standard correspondence and bounded exception retirement.
Individual identity/PDP/custody components	M3 for bounded operated paths; medium confidence	Working source and dated deployments/consumer receipts. Uniform negative tests, key rotation, outages and revocation evidence are needed for M4.
End-to-end privileged authorization	M2; high confidence in the limit	Approval, PDP provenance and task-bound execution gaps remain named owner work. A complete protected operation with denial, replay, expiry, failure and recovery proof is the gate.
Detection, audit and response	M2 overall; some custody/scanner paths M3	Native scanner expansion and audit service exist; source emission completeness, import paths and private response handling remain incomplete.
Recovery and resilience	M2 overall; scoped database/package recovery M3	Restore procedures and selected proofs exist; independent root recovery and estate-wide loss scenarios remain unproven. Single-node risk is explicitly accepted for build mode.
Agent authority and isolation	M2; medium-high confidence	Supervised record and source isolation mechanisms exist; the active assignment has no verified runtime isolation or autopilot grant.
Reuse as an independent framework	M2; medium confidence	Useful APIs, contracts and local tools; heterogeneous packaging, stale metadata and estate coupling prevent an M3 portability claim.
Self-optimization	M2; high confidence in the limit	Deterministic findings and proposals exist; regular native collection, authorized change, verified improvement and rollback do not form a uniformly accepted loop.

Overall: M2 integration stage, with several M3 components. The weakest mandatory trust boundary limits the integrated claim; averaging component scores would hide it. There is no defensible percentage “complete” or forecast incident rate from the available evidence. The SEC-DSM ledger records 116 numbered entries: 20 anti-pattern references, 12 incomplete assessments and 84 unverified entries, with none marked conformant. This is assessment coverage, not a claim that 84 controls are absent. Requirement ledger.

SWOT

	Assessment
Strengths	Clear single-owner boundaries for decisions, approvals, identity, custody and audit. Deterministic composition and proposal-only feedback tools. Explicit exceptions and source/native proof separation. Working identity, policy, audit, platform and operational access components. Repo-native evidence and existing discovery/coordination infrastructure reduce the need for new services.
Weaknesses	Interface acceptance lags component delivery. Stale SCOPE/registry descriptions can direct consumers incorrectly: Secrets Engine still describes a missing approval endpoint while Approval Engine records deployment and consumer-specific acceptance gates. Several capabilities were invisible or malformed in reuse-surface. Runtime/source renames and split package ownership add discovery friction. The package family check fails because the rapp-forgejo placeholder has no family declaration; the telemetry package itself renders successfully. Credential recovery, adoption-tested rotation, agent isolation and source completeness retain gaps.
Opportunities	Publish a versioned minimal profile, reusable conformance suite and provider adapters. Measure one complete protected-operation path and one second installation. Connect current posture and maturity tools to existing scheduling/work records with verified outcome feedback. Make capability discovery describe exact interfaces and limits, so consumers can reuse a small subset rather than reproduce the estate.
Threats	A forged or stale decision reaching an incompletely verifying PEP; confused actor/principal/tenant bindings; privileged tools outside agent isolation; runner or repository-write authority reaching credentials; omitted source events; bootstrap/recovery roots depending on the failed issuer; operator bottlenecks and single-node failure; documentation or build-mode exceptions being mistaken for production acceptance.

Ranked improvements

Rank reflects risk reduction first, shared dependency removal second, then reuse benefit per implementation effort. The order is an engineering judgment, not a calculated ROI. Effort bands are planning estimates for a focused engineer with available owner inputs: S 1–3 days, M 4–10 days, L 2–6 weeks. Attended windows and cross-owner review can add calendar time. These are suggestions; they do not authorize production changes or promote deferred residuals.

Rank	Improvement and owner	Benefit and effort	Dependency and acceptance criterion
1	Authenticate PDP decisions at every enforcing consumer. Access Engine + Secrets Engine, then each PEP.	Removes a trust gap shared by all privileged reuse. M, high risk reduction and reuse value.	SECRETS-WP-0014; independently admitted verification keys or authenticated channel, exact request/lifetime binding. Refuse forged/unsigned/unknown-key responses and prove key rotation and outage behavior in the native path.
2	Finish one exact approval-to-effect integration and make it the executable reference. Approval Engine + Secrets Engine + KeyCape + Platform.	Removes the largest integration uncertainty and repeated owner negotiation. L, high operational/reuse value.	APPROVAL-WP-0002, SECRETS-WP-0013, RPF-WP-0035-T12. Prove claim/check/consume-before-effect, distinct identities, tenant binding, expiry/replay refusal, uncertain-outcome reconciliation, cleanup and independent evidence.
3	Enforce agent and runner credential boundaries. Glas/Sand-boxer/rein owners, Platform and Forge.	Bounds exposure from a tool or job compromise. L, high risk reduction.	CUST-WP-0073/GLAS-WP-0012 and FORGE-WP-0006. Test real read denial for admin material, task-specific identity, constrained delegated action, teardown/revocation and repository-controlled workflow abuse. Preserve founder-deferred rotation decisions.
4	Complete inventory and credential lifecycle evidence. Secrets Engine + Platform + consumer owners.	Eliminates unknown consumers and manual rotation ambiguity. M–L, high risk reduction and operational efficiency.	Reuse existing catalog, CCRs and G04/G09/G12 owner work. Every credential has owner, consumers, scope, delivery, expiry/rotation, revocation and elimination trigger; sample rotation proves new adoption and old refusal.
5	Close detection-to-response and non-receive coverage. Repo Manager + Forge + Risk Nexus/credential owner.	Converts preventive scans into a usable incident workflow. M, high operational value.	RMGR-WP-0021/FORGE-WP-0006. Reconcile exact repository denominator, imports/mirrors/history and mandatory CI; deliver a private synthetic finding through triage, owner action and retained resolution without content disclosure.
6	Complete independent recovery and exception retirement. Platform + NetKingdom + Infra + package owners.	Reduces correlated issuer/cluster loss and operator dependence. L, high resilience value.	NK-WP-0049, G11 and close-down checklist. Inventory roots; prove isolated restore without the failed issuer, consumer reconnect, audit continuity and ordinary custody restoration; give each exception a review/elimination trigger.
7	Package the proven interfaces as a minimal framework profile and conformance kit. NetKingdom + provider owners + Railiance Master.	Largest direct reduction in framework adoption cost. M after ranks 1–2; high reuse value.	Reuse existing case/composer/validator tools. Pin contract and provider versions; test a second clean installation and publish a compatibility matrix, positive/negative journeys, upgrade and rollback instructions.
8	Make discovery continuously truthful. Reuse Surface + Repo Manager + each owner.	Removes repeated rediscovery and incorrect integration plans. S–M, broad efficiency gain.	This review establishes the capability denominator. Require valid owner entries, exact index/entry parity, resolvable relations, drift/freshness checks, valid package-family declarations (including a disposition for rapp-forgejo) and hosted round-trip discovery; fix stale endpoint and runtime-name claims at their source.
9	Admit security event sources and measure missing evidence. Audit Core + Approval/Tenant/Secrets owners + Telemetry.	Gives optimization trustworthy inputs and reveals silent controls. M, prerequisite for measured improvement.	Existing outbox/cadence work. Verify source transition → durable outbox → receiver → independent readback; include lag, duplicates, downtime, rare-event heartbeats and revocation of sender access.
10	Close the existing improvement loop with outcome verification. NetKingdom + Guard + Maturity + Activity Core + coordination owners.	Reduces manual follow-up and prevents recurring findings. M after rank 9.	CUST-WP-0079 cadence and owner contracts. First unassisted observation → deduplicated finding → ranked owner work → approved change → native remeasurement → retained result; failure retains finding and rollback.
11	Standardize consumer adapters and error/evidence contracts. Access/Approval/Secrets owners with NetKingdom.	Reduces per-consumer binding, retry, freshness and transport bugs. M, high reuse value.	Extract only behavior proven by ranks 1–2 into a small SDK/contract test kit. Preserve owner authority, no embedded second PDP; demonstrate two consumers and version compatibility.
12	Optimize operational cost from measurements. Resource Control + Fin Hub + Platform + Telemetry.	Avoids unnecessary service hops, replicas and deploy-per-lane work. S measurement then M changes.	Measure p50/p95 decision and protected-operation latency, approval touches, queue age, replica cost, headroom and failure rates. Batch compatible owner work and prefer native identity; retain security invariants and demonstrate improvement against a baseline.

Ranks 1–6 establish trustworthy operations. Registry cleanup can proceed alongside them because it is low risk. Ranks 7 and 11 should package the accepted reference, while ranks 9–10 make improvement measurable. These recommendations reference existing owner work instead of creating another parallel security backlog.

Reusable framework shape

A first adopter should choose a small profile from the inventory:

1. Contracts and offline verification: SecurityCanon practice, NetKingdom IAM/layer/case contracts, conformance validators and scenario composer. This is useful today even when using different runtime providers.
2. Application access: an IAM-profile-compatible identity provider, Access Engine and a consumer enforcement adapter; add User/Tenant facts only where the application needs them. Do not require the offline Zone Engine as a service dependency.
3. Privileged operations: Approval Engine and a proven consume-before-effect adapter; use Secrets Engine/OpenBao only when target-native identity is insufficient. Warden/Bridge/Mason apply when operational access or structure construction is needed.
4. Evidence and operations: source outbox and Audit Core, then owner-specific rollout/recovery contracts. Railiance is the current reference substrate; its hostnames, local tunnels and admin procedures should be configuration/adapters, not framework requirements.
5. Improvement: posture feedback, Guard/Maturity claims and existing work scheduling. Add learning only after stable source provenance and native outcome measurement.

Stable reuse surfaces should be schemas, versioned request/claim/decision/receipt contracts, package entry points, fixtures and provider adapters. No new umbrella broker is needed. A framework distribution should publish its dependency lock, supported versions, migration rules, sample consumer and explicit unsupported scenarios. Commercial licensing and redistribution rights need their own artifact-by-artifact review before an external distribution; this assessment establishes technical reuse, not a blanket redistribution grant.

Optimization measurements

Outcome	Measure and owner	Comparison that would demonstrate improvement
Faster onboarding	Time and human touches from accepted case to natively verified consumer; Warden/Mason/Platform	Same case class before/after templates, with negative tests unchanged
Lower execution overhead	Policy and complete protected-operation latency, failure rate and issuer calls; PEP/Access/Secrets	Representative p50/p95 and throughput under the same authority and failure requirements
Lower recurring work	Reopened/duplicate findings, overdue owner work and manual handoffs; Guard/Activity/State Hub	Repeat observation windows with stable source denominator
Better security coverage	Credentials, PEPs, repositories and event classes with complete evidence divided by explicitly inventoried totals	Unknowns reported separately; no denominator shrink to improve a score
Cheaper operation	Resource requests versus measured demand, recovery storage and operator effort; Resource Control/Fin Hub	Native capacity/recovery checks and error rate remain within the agreed bounds
Reliable preventive checks	Scan duration, objects per push and unverified refusals; Forge/Repo Manager	Representative evidence publication passes within declared bounds while introduced-history and negative-secret checks remain enforced
Better reuse	Successful second installation, time to integrate, adapter-specific code and upgrade failures; NetKingdom/Reuse Surface	Independent consumer acceptance against pinned contracts

A useful automatic loop observes and proposes. Any actuation still passes existing authority, cost/risk, approval and rollback controls. A maturity score, performance lesson or optimization target must never manufacture a permission.

Publication of this review exposed a concrete efficiency issue: the normal receive scanner refused the large evidence push with scanner-failed after 135–138 objects, while its source declares a 90-second total budget. Smaller batches passed the same scanner. This supports measuring startup/per-object overhead and testing representative publication sizes under rank 12; it does not prove the precise failure cause or justify weakening detection. The publication receipt retains accepted batch results and final tree parity.

Capability establishment status

All 70 reviewed capabilities are established in owner registries, local discovery and hosted reuse-surface. The final forced hosted composition on 2026-10-15 exposes every reviewed ID exactly once, with the correct source repository, no missing IDs and no federation warnings. The hub composes 114 total capabilities from 99 sources, preserving unrelated capabilities. Final hosted verification, fresh hosted federation.

All 60 owner repositories published their registry changes with verified remote revisions. Valid stable IDs were retained, missing entries added, the copied Secrets Engine template removed and malformed metadata normalized. Each reviewed capability maps to supported use cases and conservative maturity estimates. Local native federation and normal CLI discovery also verify all reviewed IDs; existing unrelated staging and unpublished owner changes were preserved. Provider publication, additional providers, local verification, normal CLI discovery.

The 31 public registrations and seven private registrations passed independent full-field readback. The seven private packages use immutable source revisions and the founder's explicit metadata disclosure consent. A dedicated reader has verified code-read access to exactly those seven repositories; the hub binds its credential to fourteen exact HTTPS metadata URLs before credential lookup and rejects authenticated redirects. The hardened image, runtime source/helper hashes, ESO delivery and actual seven-index/seven-entry native fetches were verified without cache fallback. Production source declarations match the deployed image and delivery configuration. Public verification, private registration receipts, native fetch proof, runtime verification, owner execution.

The founder approved the exact supervised execution packet and its one-line writer CLI flag-order amendment. Admin custody and final member writer sessions were revoked; failed attempts remain recorded. The static reader's manual 90-day maintenance deadline is 2027-01-13 03:06:09 UTC, tracked in RPF-WP-0058-T05; it has no automatic expiry or reminder claim. The observed incorrect-OTP return-path issue is handed off as residual CUST-IN-0018 for owner triage. Exact execution approval, approved amendment, admin revocation, writer session receipts, maintenance binding.

Verification passed 25 private registration/transport tests, 84 focused Warden tests, the earlier 23 scenario/posture tests, 11 User Engine package tests, nine policy-package tests and Helm lint. Broader Warden suite completion was not verified; its first observed failure reproduces on the unchanged baseline under a read-only filesystem. The telemetry package rendered 93 resources, while its estate family check retains the pre-existing rapp-forgejo declaration gap. Registry establishment does not establish whole-estate security conformance or raise the architecture's M2 integration estimate. Source checks, dependency review, requirement audit.