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

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	related	state_hub_workstream_id
HUB-WP-0012	workplan	NetKingdom identity and tenant integration: platform-root first	infotech	hub-core	active	implementation	codex	infotech	2026-09-28	2026-09-28	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	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 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

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 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

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

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

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

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)

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

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)

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

Owner integration continuation — 2026-09-28

Committed and synced the initial foundation as 3e38614. The follow-up owner integration review 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.

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.

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

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 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

• 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.