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

# NetKingdom target security architecture

Version 1, 16 October 2026. Implementation coordinator: [CUST-WP-0080](../workplans/CUST-WP-0080-netkingdom-security-blueprint-and-gap-closure.md).

**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](../workplans/CUST-WP-0082-netkingdom-security-hardening.md).
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](netkingdom-security-architecture-review.md). This is the
target and its acceptance contract; the [implementation record](netkingdom-target-implementation.md)
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](assessments/netkingdom-2026-10-14/capability-inventory.md)
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](netkingdom-security-gaps.md) 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

```mermaid
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.