hub-core/workplans/HUB-WP-0012-netkingdom-platform-root-access.md

---
id: HUB-WP-0012
type: workplan
title: "NetKingdom identity and tenant integration: platform-root first"
domain: infotech
repo: hub-core
status: active
flavor: implementation
owner: codex
topic_slug: infotech
created: "2026-09-28"
updated: "2026-09-28"
related:
  - HUB-WP-0009
  - HUB-WP-0011
  - STATE-WP-0079
  - CORE-WP-0010
  - RAPPCOREHUB-WP-0002
  - RAPPCOREHUB-WP-0003
  - NK-WP-0038
  - NK-WP-0039
  - NK-WP-0042
  - USER-WP-0030
  - TEN-WP-0012
  - FLEX-WP-0024
  - FLEX-WP-0025
  - SHR-WP-0001
state_hub_workstream_id: "e61ce290-c5ec-516c-8589-ef9a55cf3aa3"
---

# NetKingdom integration, platform-root first

## Outcome and boundaries

The existing platform-root login receives full Hub Core, extension and platform
access, including Railiance, through verified NetKingdom identity and the
owners' enforcement paths. Other human users are denied initially. Public
exposure waits for access-control evidence and a separate approved rollout.

[Architecture blueprint](../docs/netkingdom-access-blueprint.md) defines the
contract and reviewed baseline. This is the single new integration workplan;
existing retirement and rollout plans retain their tasks. Core Hub receives no
new product feature work. The 2026-09-28 implementation session is authorized
for source implementation and verification. Live grant/factor/policy delivery,
public exposure and retirement retain their concrete owner acceptance gates.

Inventory and local enforcement implementation are active. Cross-owner policy, root identity binding and live
acceptance are not yet reviewed. The user has selected the root-first scope;
there is no need to reopen that product decision. Dependencies below are
per-task sequencing, not a blanket wait for every related workplan to finish.

## T01 — Freeze the integration contract and platform coverage matrix

```task
id: HUB-WP-0012-T01
status: progress
priority: high
state_hub_task_id: "204f4fb0-e240-5558-8790-5985517b85e0"
```

Owner: hub-core; contract reviewers: NetKingdom, user-engine, tenant-engine,
flex-auth and affected extension/platform owners. Review the blueprint and
inventory every HTTP route, alias, MCP tool, embedded router and active platform
service/management surface. Record audience, action/resource, actor/target
tenant, enforcement point and test owner for each. Include Railiance Kubernetes,
GitOps/deployments, SSH, observability and platform identity/secret administration.
Confirm root's explicit cross-tenant administrative coverage and existing
approval obligations. Set the versioned security-profile and migration contract.

Done when no published route/tool or active platform surface lacks a row and
owner, contract reviewers' decisions are recorded, and M1 success/deny cases
are executable specifications. Unknown/disputed rows remain visible blockers.

2026-09-28: the [access inventory](../docs/platform-access-inventory.md) now
enumerates 161 Hub source surfaces and 48 platform/extension boundaries, covering
250 observed cluster objects. Its machine-readable profiles specify owners,
audiences, actor/target tenants, enforcement and acceptance cases; the checker
detects source drift and incomplete object mappings. Duplicate docs handlers,
legacy MCP targets and unresolved native/extension paths are explicit findings.
Owner review, effective host/per-service route expansion, policy vocabulary and
authenticated acceptance remain open, so T01 is `progress`, not `done`. No
platform-root login or enforcement test is claimed by inventory validation.

## T02 — Bind platform-root identity, login, tenant and revocation

```task
id: HUB-WP-0012-T02
status: progress
priority: high
state_hub_task_id: "9a955fbf-f289-51b7-9682-bbe471694595"
```

Live admission depends on T01; independently testable source may proceed. Owners: NetKingdom/KeyCape, user-engine and tenant-engine;
hub-core owns consumption. Resolve the existing root account to `(iss, sub)`
without recording credentials. Establish its explicit platform entitlement,
map existing platform-operator vocabulary, register Hub clients/audiences and
exact redirects, and implement PKCE sessions and API token validation. No
username comparison or first-login promotion. Require the existing AAL2 floor
and accepted enrollment/recovery; do not assume proposed IAM v0.4 step-up works.
Fix measurable session/token/assurance lifetimes and revocation bounds; include
live authoritative tenant/account checks for privileged actions.

Done when attended root login succeeds privately, an ordinary account and a
forged same-name account fail, MFA/recovery/logout/key rotation work, and
suspension/grant withdrawal deny within the agreed bound. Record immutable
identity references and sanitized receipts only. Reuse NK-WP-0042 if additional
step-up implementation is actually required.

## T03 — Deliver root policy and authenticated decision evaluation

```task
id: HUB-WP-0012-T03
status: progress
priority: high
state_hub_task_id: "feea8f20-aad4-583b-958a-a8efeb9c133c"
```

Depends on T01; live acceptance also needs T02. flex-auth owns the protected
system, complete action/resource grant and service deployment; platform owners
own credential/signing-key delivery. Hub Core owns enforcement integration.
Authenticate the calling workload separately from the end user, validate fact
provenance, signed decision origin, request binding and obligations. Root gets
all registered platform actions; non-root humans deny; callers get explicit
workload grants only. Fail closed on unsigned/untrusted, stale, mismatched,
unavailable or obligation-incomplete decisions. Prove audit durability and key
rotation. No token/PDP credential reuse from another protected system.

Done when a private pinned deployment passes positive root decisions and the
tampered-signature, wrong actor/action/resource/tenant, expired decision,
untrusted caller and policy-outage matrix. Finished signing source work is not
substituted for evidence of production custody and delivery.

## T04 — Enforce the boundary across Hub Core and its clients

```task
id: HUB-WP-0012-T04
status: progress
priority: high
state_hub_task_id: "15bc3cae-4575-56c9-afd2-e1e348109ca9"
```

Live admission depends on T02/T03; the default-deny source seam may proceed. Add the reusable verified actor/tenant context and local
enforcement seam to all native ports, projections, compatibility routes/aliases,
catalogs/docs, browser, MCP and embedded router paths. Minimal liveness and
login mechanics are the only public exceptions. Bind messaging/event producer
identity to the caller; prevent direct-Service bypass. Remove shared root
credentials from normal clients and confine unavoidable migration keys to
named private lanes. Add readiness checks for configured identity/policy
dependencies. Root can administer every Hub Core function; an ordinary logged-in
user cannot. Include revocation, concurrency, cache and audit-failure tests.

Done when the route/tool inventory is covered by automated allow/deny tests,
private full-root browser/API/MCP journeys pass, and legacy callers have tested
bounded migration/rollback paths without a public bypass.

## T05 — Admit extensions and State Hub migration callers

```task
id: HUB-WP-0012-T05
status: todo
priority: high
state_hub_task_id: "6d29854e-e894-5340-9e13-8866e80246f4"
```

Depends on T04. Publish the versioned extension security profile and harness.
Use ops-hub as first extension, then all inventoried exposed extensions;
activity-core, Repo Manager and inbox readers receive separate workload
identities. Each extension enforces audience/action/tenant and authenticates
delegation; no forwarding root tokens across audiences. Preserve domain/Fabric
authority and explicit unsupported/deferred surfaces.

Done when root succeeds and anonymous/non-root/wrong-tenant/wrong-audience
callers fail across extension boundaries; calls and audit retain actor plus
workload identities. HUB-WP-0011-T02 consumes this contract, while its T01/T03
retain freshness and reader cutover. STATE-WP-0079 keeps each slice's writer,
parity, retention and zero-traffic gates. This task does not claim retirement.

## T06 — Prove full platform-root coverage, including Railiance (M1)

```task
id: HUB-WP-0012-T06
status: todo
priority: high
state_hub_task_id: "97b0b242-e9a7-53cd-941f-a1822fcf93a5"
```

Depends on T04/T05 and the external owners for each T01 row. Integrate the same
root identity/entitlement with all inventoried platform management surfaces.
Use native owner paths for SSH certificates, Kubernetes/RBAC, GitOps,
credentials and approvals; Hub Core is not an unrestricted execution proxy.
Keep caller and human attribution distinct and preserve existing confirmation
and approval obligations. Test allowed administration with reversible or
isolated operations and independently verify denied non-root attempts.

M1 is accepted only when every coverage row has an attended/live receipt,
including full Hub Core access and Railiance administration, revocation and
audit. A navigation link or Hub Core token alone is not evidence of access to
another service. Any missing backend integration keeps M1 open.

## T07 — Package and gate public exposure

```task
id: HUB-WP-0012-T07
status: todo
priority: high
state_hub_task_id: "0c15cb82-7c59-5a44-8bf0-857ea4438642"
```

Depends on M1. Owner: rapp-core-hub through existing RAPPCOREHUB-WP-0002-T05,
with NetKingdom/platform/reef owners. Pin the verified image, credential
references, policy boundary and explicit release exposure setting. Run local,
server-dry-run, private root/deny, TLS and consumer gates. Resolve the existing
publisher failures in RAPPCOREHUB-WP-0003 separately where required by smoke.
Obtain the concrete public-enable approval only after evidence is reviewable.
Routine upgrades preserve approved exposure; fresh installs stay private.
Rollback retracts public access before any pre-enforcement image is restored.

Done when the approved public surface passes root access, non-root/anonymous
denial, no bypass, trusted TLS, revocation and rollback checks. Never enable
Ingress just to repair the old public stabilization check ahead of this gate.

## T08 — Refine roles, tenant isolation and delegation (Phase 2)

```task
id: HUB-WP-0012-T08
status: todo
priority: medium
state_hub_task_id: "59a0672c-560e-5b43-9d83-9f90d498698f"
```

Deferred until M1; not an M1 dependency. Hub Core with NetKingdom, User/Tenant
Engine, policy and extension owners define tenant admins, ordinary users,
recipient rules, delegated agents and per-action/extension permissions. Migrate
legacy data with explicit tenant provenance; test query/export/cache/event and
MCP isolation before admitting any non-root tenant users. Root's platform grant
remains explicit and auditable. Do not create a second workplan merely to defer
this task; this plan stays open after M1 until Phase 2 is completed or explicitly
re-scoped with a durable owner.

## Implementation review — 2026-09-28

The [candidate security profile](../docs/access-profile-v1.md) records the concrete
contract, configuration, source evidence and owner integration gaps. Source changes
are executable preparation; dependencies above gate live admission, not isolated
implementation against explicit test doubles. No root subject or entitlement was
invented and no live service, grant or public listener was changed.

- T01: retained all 161 source surfaces/48 platform rows/250 objects; added a
  packaged runtime action catalog and drift/anonymous-denial tests. This does not
  complete per-service routes or substitute for the named owners' review.
- T02: implemented IAM v0.3 access-token verification with discovery, signature,
  audience/type/lifetime/assurance validation and rotating keys. Live root binding,
  issuer MFA/registration acceptance and authoritative account/tenant adapters remain open.
  Local PKCE/session/logout implementation is covered in the continuation below.
- T03: implemented authenticated workload PDP calls, trusted rotating public keys,
  signed envelope, submitted request digest, caller/structured binding/lifetime
  checks and fail-closed obligations. Real Go fixtures prove interoperability.
  Hub policy, fact provenance approval, key delivery and durable audit remain open.
- T04: production/enforce defaults protect runtime routes and refuse missing
  dependencies. Shared-key fallback is removed in that mode. Added verified event
  attribution, sender binding, per-invocation MCP credentials and an embedded-host
  seam. Normal production CLI requests remain closed until an admitted composition
  factory supplies real owners. Do not promote this candidate as an ordinary upgrade.
- T05–T08 remain open: no actual extension, full platform/Railiance, public or
  multi-tenant acceptance receipt exists. Source-only tests cannot close them.

Review corrections: flex-auth's consumer join is `submitted_request_digest`;
its Go serializer preserves struct declaration order (sorting every JSON key is
incorrect). Root decisions need live tenant/account facts on **every** access,
including reads, rather than a five-minute cached root grant. Unsupported decision
obligations refuse access. Existing test fixtures for legacy behavior now identify
themselves as `test`, since production no longer permits anonymous durable ports.

Validation results are recorded in [implementation evidence](../docs/evidence/hub-wp-0012-source-20260928.md).

## Owner integration continuation — 2026-09-28

Committed and synced the initial foundation as `3e38614`. The follow-up
[owner integration review](../docs/owner-access-integration.md) documents source
contracts and delivers a real Audit Core sender plus explicit runtime composition.
The sender verifies operational durable custody and exact receiver acknowledgements,
rereads its own credential, and blocks execution on lost receipts or rejection.
Signed decisions survive archive serialization for independent verification.
The runtime owns the composed HTTP client's lifecycle; configuration alone cannot
activate missing authority adapters.

Owner-source tests exercise the actual Audit Core receiver/storage, a complete
fixture JWT→policy→audit→Hub write, and grant withdrawal denial. Their local SQLite
operational-readiness override is explicitly synthetic, not a live custody claim.

Two T01/T02 contract gaps now have concrete source evidence: User Engine's
`platform:root` requires an explicit mapping to canonical `tenant:platform`, and
`GET /api/v1/me` may provision an unknown account. It must not be used as Hub's
read-only account/entitlement oracle. Tenant Engine's live role endpoint also
needs an admitted authenticated Hub caller, not just an asserted actor query.
The existing `audit-core-senders` routing entry points to ops-mason/OpenBao and
is unresolved; no Hub sender credential was minted or retrieved.

Validation: **304 full-suite tests pass**, plus the final seven owner/denial checks;
wheel build and inventory validation pass.
[Continuation evidence](../docs/evidence/hub-wp-0012-owner-integration-20260928.md).

T01–T04 remain `progress`; live owner acceptance and the later milestones remain
open. No production deployment, entitlement or public listener changed.

## Browser and enforcement continuation — 2026-09-28

Closed two local enforcement gaps: injecting a controller into a development
runtime now fails startup instead of silently ignoring it, and request bodies
have a bounded receive deadline before authority evaluation.

Added explicit confidential OIDC browser composition with S256 PKCE, one-time
browser-bound state, nonce and ID-token checks, fresh MFA/root authorization,
opaque short-lived server-side sessions, CSRF protection and local logout.
Every protected session request retains live owner/policy/audit checks, including
a second session-validity check after authority awaits. Tokens never appear in
browser responses. Session/process lifetime, proxy logging and multiworker limits
are documented in the [integration guide](../docs/owner-access-integration.md).

Browser source tests cover actual RSA signatures and code exchange with mocked
owner endpoints; they are not live owner acceptance. The source inventory now
contains 165 Hub surfaces, including four optional browser protocol routes.
[Validation evidence](../docs/evidence/hub-wp-0012-browser-20260928.md).
T01–T04 remain `progress`; issuer registration/MFA, owner-facts composition,
MCP consumer adoption, operation-outcome auditing and platform conformance remain
open. No production listener or entitlement changed.

## Conformance and CI continuation — 2026-09-28

Added enforcement-mode Tier 2/3 conformance journeys with signed IAM tokens and
explicit synthetic owners. Denial/revocation/outage cases exercise reads and
writes and verify unchanged business state after restoring access. Event
attribution is joined to recorded authorization decisions.

Forgejo now runs `make ci-check`: the complete ordinary test suite, access
inventory drift checks, distribution builds and an isolated installed-wheel
resource/import check. CI checks out the full commit into a unique temporary
directory and installs locked development/runtime dependencies. The optional
owner-source interoperability suite remains separately identified.

See [conformance documentation](../docs/conformance.md#access-enforcement-and-ci-gates).
Validation: local `make ci-check` passed with **330 tests**, one explicitly
optional owner-source module skipped, inventory coverage (165 Hub surfaces),
distribution builds and installed-wheel checks. Final locked runtime dependency
sync and workflow YAML/shell syntax checks also pass.

These are local source/release gates, not live platform or remote CI acceptance;
T01–T04 remain `progress` and T06 remains open.

## MCP caller continuation — 2026-09-28

The standalone MCP runtime profile now advertises the four tools whose GET
routes exist in the runtime. The other 27 remain explicit embedded-host tools;
no legacy message/progress semantics are silently translated to native ports.

Added rotating, bounded single-principal stdio credential-file composition.
Enforced CLI network transports refuse startup pending an authenticated host;
credential files cannot be attached to a shared network listener. SDK hosts
retain per-invocation providers. Credential-bearing requests require HTTPS,
disable redirects and ignore proxy environment variables. Facet arguments cannot
inject paths or queries. Inventory rows record each tool's backend profiles.

Actual tool-invocation tests cover concurrent caller isolation, credential
rotation/removal, all four runtime route mappings and enforced backend denial.
See the [MCP composition contract](../docs/owner-access-integration.md#mcp-caller-composition-and-backend-mapping).
Validation: **350 tests pass** (one optional owner-source module skipped);
inventory drift, distribution builds and isolated installed-wheel checks pass.
The package gate caught reuse of an older same-version uv installation; it now
forces a fresh environment and refreshes the Hub package, and the rerun passed.
No credential was issued or retrieved and no consumer was switched. T04 remains
`progress`; host authentication/exchange, real caller admission and T05 remain open.

## Transaction outcome continuation — 2026-09-28

Native durable registry/message/progress/interaction mutations now atomically
store verified authorization attribution, their existing ledger row and an
immutable committed-outcome envelope. Added migration `0006_outcome_outbox`,
retry/backoff delivery with stable receiver idempotency keys, lifecycle-owned
dispatch and protected backlog readiness. Rollback creates no outcome; a lost
receipt can replay after restart. Downgrade refuses undelivered rows.

[Outcome contract and evidence scope](../docs/operation-outcome-audit.md).
Local SQLite tests and real Audit Core receiver-source checks cover this slice;
production PostgreSQL lock scheduling, grants, receiver admission and retention
remain open. Compatibility/embedded/external writes and background projection
refreshes are not claimed as covered. T03/T04 remain `progress`.
Validation: **366 tests passed**, including the opt-in Audit Core owner-source
suite. Inventory drift, distribution builds, isolated installed-wheel checks
and current migration/context/store wheel contents pass.
No database migration or deployment was applied to a live service.

## Real PostgreSQL verification — 2026-09-28

Added a required `make postgres-test` gate to `make ci-check` and therefore the
existing Forgejo workflow. A digest-pinned, loopback-only disposable PostgreSQL
container hosts isolated test databases. Operator database URLs are not accepted;
the fixture removes its own databases and container after the run.

Five integration tests exercise the full Alembic chain to `0006`, guarded
schema downgrade/re-upgrade, two concurrent `SKIP LOCKED` delivery workers,
atomic rollback, persisted retry state and replay after an actual child worker
process exits after a synthetic custody receipt but before local acknowledgement.

Final `make ci-check` passed: **360 ordinary tests** (two optional modules
skipped in that phase), inventory/build/installed-wheel checks, then **five real
PostgreSQL tests** with the opt-in enabled. Fixture-container cleanup was verified.
Production grants, deployment and live receiver acceptance remain open; no live
database was contacted or migrated.
See [test details](../docs/conformance.md#disposable-postgresql-gate).

## Access readiness continuation — 2026-09-28

Replaced controller-presence readiness with named identity/facts/policy/audit
observations and an aggregate. Missing, failed or stale observations fail
readiness. Observations come from verified operations and never replace access
checks; invalid tokens cannot poison/refresh dependency health and verified
policy denials remain healthy evaluations. The controller itself now bounds
all callers to ten seconds. Readiness remains protected and liveness minimal.

Flex-auth source exposes only liveness; no admitted independent facts health API
exists. The [readiness contract](../docs/access-readiness.md) explicitly describes
recent usability rather than inventing an owner probe or claiming reachability.
Updated conformance to include access and outcome-delivery dependencies.
T04 remains `progress`; independent owner monitoring and live acceptance remain
open. Validation: **372 ordinary tests**, **five real PostgreSQL tests** and
**six owner-source Audit Core tests** pass; inventory, package build and isolated
wheel validation pass. No deployment or external owner contract changed.

## Acceptance checkpoints

- [x] Architecture/source/runtime review captured; new implementation owner is hub-core
- [ ] T01 contract review and complete platform surface inventory accepted
- [ ] M1: T02–T06 full platform-root access and denial/revocation evidence accepted
- [ ] T07: authenticated public exposure separately approved and verified
- [ ] Phase 2: T08 delegated and tenant-scoped access accepted

Planning completion is not implementation completion. No live authenticated root
session or entitlement was tested in the 2026-09-28 review.