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

NetKingdom target security architecture

Version 1, 16 October 2026. Implementation coordinator: CUST-WP-0080.

18 October delivery sequencing: the founder prioritized working Playwright human/agent access, then everyday Forgejo use. WP-80 now accepts those functional flows under their stated build profile. The full security acceptance contract below remains the target in CUST-WP-0082. This defers work; it does not establish conformance or change the target.

NetKingdom will provide a small set of reusable, independently verified security workflows. Identity, access decisions, approvals, credential custody and audit retain their existing owners. Consumers share adapters and case templates instead of reproducing those interfaces or deploying every capability as a service.

The founder requested implementation of this direction after the architecture review. This is the target and its acceptance contract; the implementation record tracks delivery. Source, deployed behavior and accepted consumer outcomes remain separate states. Existing scoped authorizations, human custody requirements and explicit rotation deferrals continue to govern execution.

Scope and current evidence

The target covers the review's 60 capability-owning repositories, 70 reusable boundaries and use cases U01–U14. The complete inventory remains the provider denominator. It does not require deploying all providers for every consumer. On 15 October, hosted discovery contained all 70 reviewed IDs exactly once; the local entries included 44 A2 CLI/source capabilities and six A0 informational capabilities. Discovery establishment is delivered. Maintaining truthful limits, source revisions and consumer evidence remains ongoing work.

The operational baseline remains integration stage: the signed-decision consumer, task-scoped protected effect, first reusable browser case, actual agent isolation, source reconciliation and independent root recovery retain acceptance gates. The gap register and owner files carry the detailed history. A missing assessment is an unknown, not evidence that a control is absent.

Authority and placement

Responsibility	Authoritative owner	Target placement and simplification
Security meaning and conformance	security-canon, net-kingdom, gate-house, info-tech-canon	Versioned source contracts, offline validators and published policy references; no mandatory runtime hop for document interpretation.
Authentication and assurance	key-cape; user-engine for account journeys	Existing identity stack and explicit relying-party adapters. Account, group and factor recovery must work end to end before considering an identity-provider replacement.
Tenant and other facts	tenant-engine and the relevant fact owner	Use only policy-required facts with explicit provenance and freshness. Zone and maturity reference tools are not implicitly live claim services.
Authorization	access-engine	One decision owner and contract, with independently admitted consumer pins. Shared deployment requires a measured isolation and availability case.
Approval and presentation	approval-engine; informed-decision	One bound approval lifecycle, separate presentation; no approval inferred from a report, case type or scheduler.
Credential lifecycle and custody	secrets-engine; railiance-platform/OpenBao	Native identity first, scoped short-lived credentials next, managed static credentials only where necessary. Secrets Engine remains a CLI/workflow capability.
Operational access and construction	ops-warden, ops-mason, ops-bridge	Reuse routing, case follow-through, reviewed structure and private transport; no general umbrella broker.
Independent evidence	audit-core	Durable custody and admitted reconciliation; original owner receipts stay authoritative. State Hub indexes references rather than becoming security custody.
Agent execution	glas-harness, sand-boxer, the selected rein	An admitted task identity and enforced profile; tools and inherited credentials count as effective authority.
Deployment and recovery	existing Railiance, rail, reef and rapp owners	Pinned packages, owner deployment paths, off-host recovery resources, measured headroom and declared rollback.
Discovery and improvement	reuse-surface, repo-manager, kings-guard, maturity-engine, activity-core, coordination-engine	Derived discovery and observations feed deduplicated owner work. Scheduling and scores never create permissions.

Consumer profiles

Application access

An application authenticates the caller using its admitted issuer, verifies the required identity/tenant/assurance claims, obtains an Access Engine decision, and enforces the exact authorized resource/action. User or tenant lookup is included only when required by that application's policy. Cached facts need an explicit freshness and revocation contract. Policy-required unavailable or stale facts cannot become a permissive default.

Identity token verification fixes accepted algorithms, issuer, audience, token type and lifetime. Decision verification independently authenticates the admitted PDP signer or channel and checks request, policy and validity bindings. A digest alone does not authenticate its producer. The current producer's signed envelope format remains authoritative; consumers must not invent another canonicalization.

2026-10-18 Forgejo profile selection: the user requires current KeyCape checks on every ongoing API/Git/SSH operation for NetKingdom-linked accounts, including access authenticated by native API tokens or SSH keys. The separate local break-glass account retains its existing path. A native credential does not replace current issuer identity; unavailable, revoked, expired or mismatched required facts cannot become a fallback. Bind the actor to the actual owner account/source/subject and the independently admitted application tenant, then enforce current groups and the exact resource/action policy on each declared entry path. Callback-only evidence does not satisfy this profile. This records the implementation choice, not native rollout or credential/package admission.

Protected operation

flowchart TD
    R[Exact action and execution readiness] --> H[Required human review]
    H --> A[Bound Approval Engine claim]
    A --> D[Authenticated Access Engine decision]
    D --> V[Consumer validates identity scope digests and lifetime]
    V --> J[Durable operation reservation and call intent]
    J --> C[Atomic approval consumption before effect]
    C --> F[Independent authoritative consumption confirmation]
    F --> E[Owner mediated exact effect]
    E --> Q[Verified outcome or retained uncertainty]
    Q --> X[Scoped cleanup and credential revocation]
    J --> O[Durable source evidence]
    Q --> O
    X --> O
    O --> U[Audit Core custody and independent reconciliation]

The first implementation is the existing narrow metadata execute-ccr contract in SECRETS-WP-0013 and RPF-WP-0035-T12. The request binds initiating identity, tenant, action, target, payload/source digest, policy revision, approval binding and catalog fingerprint. Exact envelope field names and canonical bytes come from the owner contracts, not a second Custodian schema.

When producer-owned enrichment changes the facts to be approved, obtain and authenticate those exact evaluated facts before human approval. A signed refusal may carry such preparation facts, but grants no effect or retry authority. Final evaluation must still bind the original request and approved facts, and refuse drift. Preserve producer numeric types and timestamp precision across languages; the Approval owner checks current validity after acquiring its consumption lock.

Readiness and durable reservation are established before spending the approval. The journal records consume and confirmation call intents before each request; independent authoritative confirmation precedes the protected effect. Approval single-use does not imply exactly-once execution at OpenBao: the durable ledger and target-specific preconditions must preserve unknown outcomes, reject competing or changed requests, and reconcile actual state before any authorized retry. A lost response never justifies replay.

Cleanup obligations are durable before resources are created. Business failure or uncertainty cannot erase cleanup duties. Cleanup is restricted to the operation's identified resources and cannot grant a new business effect. Recovery records retain the original outcome and any rescue. Credentials remain in the owner execution path; the requesting agent receives sanitized receipts.

Known browser case

Finish oidc-browser-relying-party with Forgejo under NK-WP-0048 before adding more type families. The selected type version, parameters, provider revisions, owner adapter receipts and rendered plan are pinned. Native structure, contained mint/delivery, successful sign-in, denied groups, revocation and rollback are verified independently. Acknowledged, implemented, materialized and live are distinct states. A case renderer always remains plan-only.

Admission binds the exact authenticated catalog snapshot and dispatch mode. Attended run, rollback and reconcile revalidate the current caller and session before journal writes or owner callbacks; a cached admission does not preserve expired or changed authority. An attended change resolves its establishing login in that same catalog. An unresolved owner login remains unavailable.

The owner configuration inverse remains reachable for public clients, unchanged secret delivery and failure before a hand-over receipt exists. Receipt deletion and created-only secret cleanup cannot substitute for that inverse. Its durable before/after provenance identifies the case's configuration change; it supplies no execution authority. A fresh authorized inverse session and exclusion of all release writers protect the current-state check and inverse. Where the target offers no compare-and-swap operation, a local advisory lock alone is insufficient.

After this case passes, a second consumer proves reuse of its adapters and contracts. Rapp Playwright's human/agent identity and connectivity remain an explicit consumer acceptance obligation under CUST-WP-0080-T05 and NK-WP-0050; a deployed browser package alone does not satisfy it.

Agent and runner execution

An admitted Glas/Sand-boxer/rein profile denies access to admin material through files, mounts, environment, subprocesses and available tool paths. Tasks use distinguishable scoped identities, bounded delegation, cancellation/expiry cleanup and no cross-task credential accumulation. The actual running assignment must pass; a sandbox fixture does not establish interactive-runtime isolation.

CI writers, runner execution and deployment credentials have separate scopes. Repository-controlled workflows cannot disable the independent receive scanner or reach unrelated deployment credentials. Required checks, artifact provenance, per-job identities and import/mirror scanning need their own acceptance evidence.

Recovery and operations

Inventory roots, ordinary credentials, copies and consumers using metadata. Each managed credential has owner, purpose, exact scope, issuer, delivery, consumers, expiry/rotation, revocation, recovery and an elimination condition. Replacement acceptance proves both successor adoption and predecessor refusal. The existing founder-deferred exposure rotation remains explicitly deferred.

Recovery succeeds with the ordinary issuer/cluster unavailable, using independently reachable encrypted custody and recovery access. Prove restore integrity, consumer reconnect, audit continuity and return to ordinary custody. Set scenario RTO/RPO and measure actual results. Single-node/shared-control-plane risk remains the accepted build-mode exception until its stated production gate; the target does not silently impose an HA migration or waive that gate.

Shared implementation surfaces

• Maintain the request/decision/approval verifier per supported language with producer-owned golden vectors. Any vendored producer code is pinned, attributable and checked for drift. Install/build behavior is part of adapter acceptance.
• Use existing SecurityCase templates to generate owner-specific plans, negative checks and rollback steps. Reuse accepted authority only within its exact scope; changes to authority or approved executable revisions follow their existing gates.
• Correlate approval, decision, admission, effect, cleanup and audit by stable references. Preserve failed attempts. Store original evidence once and link it from summary reports; independent audit custody is intentionally separate.
• Provider source owns capability facts, owner workplans own task status, and deployment receipts establish runtime state. Derived indexes report drift and unknowns instead of introducing another manually maintained status source.
• Use the existing coordination frame for explicitly adopted cadence consumers. Source adoption currently selects f=1h, registered wait 2f, effective missing-heartbeat deadline 3f. Verify runtime and receiver adoption. Credential TTLs, approval validity, transport retries and worker leases remain separate.
• Keep feedback proposal-only until the existing authorization path admits an action. Activate the existing security-flow schedule and verify unassisted operation; deduplicate findings by affected owner, control and evidence scope.

Acceptance contract

These gates are cumulative and bounded to their named denominators. Completing source changes cannot mark a native gate achieved. A requirement with an accepted exception records its actual governing decision and exit trigger; new exceptions require that authority and cannot be authored to improve completion statistics.

ID	Target outcome	Required evidence and owner work
TSA-01	Every inventoried privileged PEP authenticates its decision	PEP denominator; admitted signer/channel; forged, altered, wrong-key/pin, unsigned/downgrade, expired and rotation refusals. Start SECRETS-WP-0014.
TSA-02	Exact approval produces one bounded protected operation	SECRETS-WP-0013/RPF-WP-0035-T12 native effect; Approval T01/T05 issuer/tenant provenance; wrong actor/tenant/body, expiry, replay and unavailable refusal.
TSA-03	Crashes preserve uncertainty and cleanup	Actual ledger restart/concurrency, consumed-before-effect failure, target reconciliation, scoped cleanup and revocation evidence; no blind replay.
TSA-04	First reusable browser case is accepted	NK-WP-0048 and named Mason/Warden/KeyCape adapters; independent native structure, sign-in/denial, delivery, revocation and rollback.
TSA-05	Human and browser consumers can use the delivered identity	KEY-WP-0040/U08 real-factor recovery; User Engine journey; NK-WP-0050 and CUST-WP-0080-T05 human/agent Playwright acceptance.
TSA-06	Actual agent and runner authority is bounded	CUST-WP-0073/GLAS-WP-0012 admitted runtime read-denial/tool-effect proof; Forge/Platform per-job credential and repository-workflow abuse tests.
TSA-07	Credential lifecycle is inventoried and simplified	Current owner/consumer denominator, unknown/orphan findings, native-identity elimination candidates; sampled replacement/adoption/old-refusal and deletion semantics. G04/G09/G12.
TSA-08	Recovery is independent and measured	NK-WP-0049 plus platform/root owners; isolated recovery with ordinary issuer unavailable, restore/reconnect/audit continuity and measured RTO/RPO. G08/G11.
TSA-09	Security effects have independently reconciled evidence	Admitted source/class inventory, atomic outbox, receiver readback, lag/duplicate/boundary accounting and missing-class findings. Approval/Audit/Tenant/Secrets owners.
TSA-10	Source and delivery controls cover declared entry paths	FORGE-WP-0006/RMGR-WP-0021: denominator, SSH/HTTP/UI/new repo/import/mirror coverage, required checks/provenance, private synthetic finding through resolution.
TSA-11	Discovery remains accurate	All reviewed IDs exactly once, owner/index parity, usable source links, current limits/version aliases, drift checks and package-family disposition. Reuse/Repo Manager/provider owners.
TSA-12	Improvement operates without repeated manual polling	CUST-WP-0079/Activity accepted schedule, unassisted firing, checkpoint and changed-state notifications; adopted cadence runtime/receiver receipts; owner change and native remeasurement.
TSA-13	Shared adapters reduce per-consumer implementation	Producer-format cross-language fixtures, two real consumers, version compatibility, denied-path parity, upgrades and rollback; no second PDP.
TSA-14	Minimal profiles are independently reusable	Version/provider lock, dependency and optional-provider declaration, provider adapters, second clean installation, complete positive/negative journeys and upgrade/recovery instructions.
TSA-15	Optimization improves measured operations	Baseline and repeat measurements of onboarding time/touches, p50/p95 decision/effect latency, scanner throughput/failure, resources/headroom and owner effort with unchanged control coverage.
TSA-16	Governance and exceptions remain truthful	Existing SEC-DSM ledger and close-down controls reconciled to exact evidence; real authority for changes, explicit residual promotions, preserved deferrals and no invented owner assent.

Rollout and exit

Start authenticated decisions and the bounded metadata operation, with audit acceptance included. Agent isolation is a parallel priority. Finish the existing browser case rather than opening a third reference journey. Inventory, recovery preparation, discovery corrections and source checks may proceed alongside these two integrations. Package accepted interfaces and extend consumer coverage next.

Changes use owner repositories and their existing workplans. Scoped independent owner reviews precede required native activation. The standing build-mode rule already authorizes qualifying non-destructive changes with reviewed diff/dry-run, rollback, abort owner and receipts. Access/secret policy scope changes, destructive operations, new spend ceilings and public publication retain their explicit gates. Existing exact approvals are reused within scope, not requested again.

Rollback either restores the previously admitted behavior within its accepted exception or leaves the affected operation unavailable. It never silently accepts an unsigned decision, widens scope or resurrects a revoked credential. Native failure remains evidence and prevents further promotion until resolved.

The goal completes only when TSA-01 through TSA-16 have scope-matched acceptance evidence or an already applicable explicit governing exception, the second consumer/installation proves reuse, and no required work is left only in prose. Evidence review must inspect actual sources and outcomes; a green aggregate report or completed child agent is insufficient.