portal-mojo 0.2.19 → 0.2.21

package/docs/README.md

@@ -14,11 +14,17 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [realtime.md](realtime.md) | Auth-challenged WebSocket lifecycle, heartbeat/backoff, refcounted topics, typed event projection, deterministic mock |
 | [auth-pages.md](auth-pages.md) | The in-app auth pages: routes + guard, `VITE_MOJO_AUTH` switch, fresh-auth (440 step-up) modal, MFA panel, password tools |
 | [admin-credentials.md](admin-credentials.md) | Group API keys and webhook subscriptions — dual-mount pages, lossless per-endpoint rate limits, permission registry, secret-safe create/reveal/rotation |
+| [admin-presentation.md](admin-presentation.md) | KISS presentation rules, shared styles and required rendered visual QA |
 | [admin-dashboard.md](admin-dashboard.md) | Package-owned global Admin landing, authoritative signals, independent gates, caller-isolated caches, and root fallback |
 | [admin-cloudwatch.md](admin-cloudwatch.md) | Global EC2/RDS/Redis CloudWatch charts, exact resource/fetch wires, constrained controls, refresh ownership, and modal details |
 | [admin-monitoring.md](admin-monitoring.md) | Monitoring Admin registration, logs, and exact Redis-backed metrics-permission mutations |
 | [admin-metrics-explorer.md](admin-metrics-explorer.md) | Read-only recorded-metrics discovery, full-slug adapters, KPI/fan-out/scalar contracts, and cache identity |
 | [admin-settings.md](admin-settings.md) | Runtime settings admin — direction-aware atomic writes, write-only secrets, and global/group scope |
+| [admin-deployments.md](admin-deployments.md) | API serving/attempt evidence, WebApp release recovery, durable onboarding, transient CI keys and real uploads |
+| [admin-dns-domains.md](admin-dns-domains.md) | Simple domain inventory, exact-name registration/adoption/purchase, focused registrar settings and DNS links |
+| [admin-maintenance.md](admin-maintenance.md) | Independent AWS upgrade scans and framework policy, exact confirmation, observation and uncertain operation guards |
+| [admin-geolocation.md](admin-geolocation.md) | Owner-only GeoIP provider setup, ordered fallbacks, transient credential verification and publishing |
+| [admin-operational-fleet.md](admin-operational-fleet.md) | Operational health matrix, exact backend grants, reviewed stored capacity plans and bounded batch observation |
 | [admin-fleet-configuration.md](admin-fleet-configuration.md) | Superuser structured configuration publishing, version restore and per-node application evidence |
 | [admin-bouncer.md](admin-bouncer.md) | Bouncer decisions, device investigations, and bot-signature administration with token-safe caching |
 | [admin-security-tickets.md](admin-security-tickets.md) | Ticket queue, KISS detail modal, notes, approvals, and Maestro sync contract |
@@ -36,7 +42,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [admin-dns-registrar.md](admin-dns-registrar.md) | Domain search/quote/purchase, one-use token custody, durable-ledger reconciliation, scoped registrant PII, and manual House adoption |
 | [admin-storage.md](admin-storage.md) | Global S3 buckets, masked storage backends, explicit policy-backed File uploads, capability-safe FileView/shares, and finite rendition convergence |
 | [admin-media-rendering.md](admin-media-rendering.md) | Storage → Media rendering: the three FILEMAN_RENDITIONS_* settings as a descriptor-driven form — delta-from-defaults writes, inline 400 routing, reset by writing `{}` |
-| [admin-edge.md](admin-edge.md) | Edge vhosts by template kind with a shape-first wizard, `site_api` routes and their create order, declared upstreams, and the fleet blocklist with log-first modes. |
+| [admin-edge.md](admin-edge.md) | Serving hostname configuration with Address → Routing → Certificate → Review creation, independently admitted node posture and bounded hosting readiness, `site_api` routes and their create order, declared upstreams, and the fleet blocklist with log-first modes. |
 | [admin-shortlinks.md](admin-shortlinks.md) | Global shortlink operations, destination-free caches, bounded click history, and reconciled one-shot mutations |
 | [admin-messaging.md](admin-messaging.md) | SES domains/mailboxes/sent/templates plus public contact requests, with write-only credentials and offline HTML previews |
 | [admin-phonehub.md](admin-phonehub.md) | Global Phone Hub: evidence-backed lookup, sanitized SMS audits, and write-only provider configuration |

package/docs/admin-credentials.md

@@ -206,3 +206,30 @@ See [Admin modal policy](admin-modals.md) for header actions, content-only
 sections, supported lifecycle fields and retained irreversible exceptions.
 Group API keys and webhook subscriptions deactivate/reactivate; their built-in
 Delete controls are removed. Reveal, secret rotation and cache boundaries remain.
+
+## Protected ACME consumer purpose
+
+Literal deployment operators can open **Create ACME consumer key** from the
+existing fixed-Group or cross-Group API-key inventory. This lazy form resolves
+the selected original hub Group through the private shared-validation recipient
+endpoint. It displays the actual active Group name/UUID, the named ACME validation
+consumer purpose and the fixed `dnsman_acme_federation` consequence. A tenant or
+acting user cannot substitute for the original recipient. It has no freeform
+permission or JSON input. The server rechecks Group activity, expected label and
+protected grant at issuance and rejects key-backed sessions.
+
+Issue is separately confirmed, single-flight and session-bound. Its response is
+split before presentation: safe key metadata may be displayed; the transient
+token stays outside Query/Mutation caches, URL/history and storage. Closing the
+native token dialog drops that display. The existing explicit, audited
+`/api/group/apikey/<id>?graph=token` reveal remains the recovery route. A timeout
+may follow successful issuance: inspect the exact Group's recent inventory and
+use audited reveal before creating another successor. The form blocks automatic
+reissue and never retries after fresh authentication.
+
+Create a replacement, enter it normally in the receiving deployment's protected
+connection form, Preview/Publish, Apply and verify every expected node. Only then
+explicitly review/deactivate the old hub key using existing key controls. This
+form neither rotates nor retires keys, grants allocation trust, activates hub
+sharing or asserts cross-deployment verification. Existing in-place key rotation
+semantics remain unchanged and can invalidate the previous token immediately.

package/docs/admin-deployments.md

@@ -0,0 +1,201 @@
+# Deployments
+
+`DeploymentsPage` contributes one global Operations workspace. The Admin section
+singleton belongs to `admin/domains/operations.ts`; its route lazily imports the
+page. `WebAppDetail({id,onClose})` is a focused `modal.open` task dialog.
+Import these through `portal-mojo/admin/operations` after central registration.
+The domain's owned stylesheet is `styles/components/admin-deployments.css`.
+
+API and WebApp lanes are independently admitted. API sections require exact global
+`view_platform|manage_platform|admin`; `view_platform_security` alone never fetches
+deployments. WebApps require exact global `view_dns|manage_dns|security` in this
+Admin workspace. The finite Fleet `backendGlobalCan` helper reproduces backend
+category expansion; the frontend's broader admin wildcard does not admit reads.
+Inactive lanes and denied identities mount no domain query. No active group is
+inherited. Explicit owning-group action scope is separate from page scope.
+
+API uses `GET /api/account/admin/platform?sections=deployments,api`. The last
+converged serving SHA and its observation date remain separate from the latest
+attempt. Server node summary distinguishes restart proof, reported success,
+dispatched and failed nodes. Durable diagnosis is separate from replaceable node
+observations. Unknown and stale states remain visible. Recovery supports retry
+same SHA, verify and converge according to the exact attempt status matrix; each
+confirmation refreshes the attempt first. Retry sends a stable bounded
+`Idempotency-Key`, then watches its returned attempt ID. There is no arbitrary SHA
+input, API rollback, framework update or pin editor.
+
+WebApp summary lists are bounded to 50 with honest truncation disclosure. Full
+summary, default graph ownership, registered release history and deployment
+attempt history are separate reads. The default graph is positively projected:
+no bucket, prefix, key, unrelated group data or raw metadata reaches Query.
+Full summary's latest attempt has no release identity; the detail resolves its
+exact app/attempt-filtered generic history record before naming the version.
+Generic attempt graphs omit the parent, so the request binds both `webapp` and
+`id`, asks for one row, and validates the returned attempt and release IDs.
+Ordinary viewers are never sent to the stronger rollout-status endpoint: it
+requires WebApp SAVE authority. Admitted operators can inspect node evidence
+through that endpoint. Selected active attempts use bounded, owner-fenced
+observation; terminal outcomes invalidate the owning summary and history.
+The current release pointer is desired content, never proof of fleet convergence.
+HTTPS health and active certificates are independent observations.
+
+Rollback requires `manage_webapp` plus the owning object's SAVE authority (`manage_dns|security`).
+Current-user membership may be resolved only for that known app's owning group;
+global grants bypass unnecessary membership reads. Bootstrap eligible groups do
+not grant or narrow existing-app custom actions. Manual release registration has
+its own exact object SAVE predicate (`manage_dns|security`); read-only `view_dns` does not grant release registration; workflow generation requires security or
+both WebApp and DNS management. A 403 removes app mutation controls for that
+session. The backend remains authoritative for all object, actor, origin,
+interactive and freshness rules.
+
+Release and deployment history have separate paged views. Eligible release rows
+open a preselected rollback; the focused chooser also pages beyond the first 25.
+Rollback selects a concrete noncurrent release in `uploaded|live|superseded`,
+requires typed `app/version`, refreshes ownership/current pointer and the exact app/target-filtered release, then
+sends `{webapp,release,group}`. It watches the exact returned deployment through
+`/api/edge/release/deployment/ID`, validating deployment/app/release identities.
+Only `live` is success. `rolled_back` means the attempted version was unsuccessful;
+a failed rollout can leave mixed nodes. An uncertain rollback is not replayed on
+remount. Its safe receipt blocks conflicting app mutations while it is unsettled.
+
+Before creation, App and Build options share one retained draft. After creation,
+only the current server task appears beside noninteractive App → Address →
+Repository → HTTPS progress; operation/revision/activity live in Setup details.
+Closing preserves setup; cancelling server setup requires explicit confirmation.
+New WebApp uses separately admitted bootstrap eligibility and server onboarding
+options/precheck. Missing destination or allowed bucket blocks creation with a concrete prerequisite. Existing workspaces precheck their concrete address before create. New-workspace intent deliberately has no domain before create and does not require an invented ready verdict. Defaults are production, main,
+dist and the first allowed bucket. The durable server operation owns cursor,
+revision, status, activity and resources. Choose/cancel use its latest observation;
+a revision/lease refusal requires another detail read, never repeated POST.
+Unknown cursors and parked waiting states stop automatic reads. Optional GitHub
+verification preserves `unavailable` versus explicit attestation. Closing does not
+cancel server work. A matching actor/origin safe receipt resumes by operation UUID;
+an app without such a receipt shows unfinished diagnostics without creating a
+replacement resource. An uncertain create can be deliberately retried only with
+its immutable profile and UUID after an exact 404 observation.
+
+Deploy opens its GitHub, Upload and Other CI methods directly. Workflow and
+Other CI instructions use focused dialogs. Linked-key controls follow observed
+state: create when unlinked; rotate when linked; revoke only an active key. Both
+CI methods expose these controls. Deploy setup lazy-loads key/upload surfaces.
+Generated YAML stays outside
+Query and references one repository secret named `MOJO_DEPLOY_KEY`. Copy/download
+instructions leave installation to the operator. Keys are revealed in one focused
+transient dialog, cleared on close, authority/session replacement or unmount.
+Receipt replay with `token:null` says the secret is unavailable and requires an
+explicit new rotation. Rotate/revoke explain CI impact; existing content remains
+independent. Revoke's backend freshness window is 300 seconds; other sensitive
+custom actions use 600. A 440 prompts through `requestFreshAuth` but never replays
+the POST; refresh and renewed explicit consent are required.
+
+Built artifact upload is register → anonymous checksum-bound PUT → complete →
+exact deployment observation. Files are normalized relative paths, reject
+traversal/collisions, and are hashed with SHA-256 before registration. Defaults
+are 5000 files and 1 GiB; backend limits may be lower. Signed destinations and File
+objects stay transient. Each PUT uses only the returned exact checksum header,
+raw bytes, `credentials:omit`, `redirect:error` and no API bearer. A failed/CORS
+PUT stops completion. Resume requires reselecting and hashing an identical
+manifest before registration remints URLs; a verified release with no uploads is
+handled. Saved receipts contain only actor/origin, finite IDs, immutable safe
+profile/address or normalized manifest, never key material or signed URLs.
+
+`useDeploymentObservation` reads only known identities, stops on terminal,
+parked/unknown cursor, failure, owner disposal or a bounded deadline, and skips
+hidden or blurred documents. Refresh/Resume resets the read budget without
+creating a new server operation. Native Escape/backdrop dismissal and repeated
+submission are locked during HTTP writes. Observations can stop after close;
+submitted server work persists and is reconciled from safe receipts.
+
+Mock integration uses `deploymentsMock(path,opts,{user,keyBacked,authTime,group?,
+interactive?})`, returning `undefined` for unrelated paths. The central bootstrap
+composer consumes `readDeploymentBootstrapFacts(caller)` and merges only its
+explicit WebApp fields. `deploymentMockStorageFetch` is an explicit mock-only
+secondary PUT simulator; real deployments use browser fetch. Scenario controls
+and `AdminDeploymentsDemo` exercise authority splits, current-A/failed-B,
+reported/partial/unknown/stale evidence, same-SHA retry, rolled-back/mixed WebApps,
+setup prerequisites, cursor/lease refusal, uncertain create, key replay, upload
+failure and bounded observation. Fixtures establish UI contracts, not live rollout.
+
+The supported profile editor writes only `display_name`, `environment`,
+`github_repository`, `deployment_ref` and `build_output` through the existing
+WebApp model save. It requires exact SAVE authority independently of
+`manage_webapp`; owner, bucket, release pointer, slug and credential fields are
+not editable here. The API wire field is `github_repository`, while the display
+DTO calls it `repository`. Save re-reads ownership and all baseline values,
+refuses observed drift, then reads back the saved profile. This is a client
+stale-value check, not an atomic server revision condition. Profile changes do
+not deploy content or update a workflow already installed in GitHub.
+
+A lost profile-save response retains its submitted receipt and blocks another
+save. Reload shows current values but does not prove the earlier writer finished.
+Only after that read may an operator explicitly acknowledge the unknown prior
+writer with the app-specific phrase. Acknowledgment sends no POST; a new change
+and fresh preflight are still required. A late observed commit refuses the next
+save. Known profile 440 refusal settles its unsent receipt and never replays the
+POST. No profile patch or secret is retained in the receipt.
+
+Run `node scripts/verify-admin-deployments.mjs` and
+`node scripts/verify-admin-deployments-mounted.mjs`, then repository typecheck.
+The first covers positive projection, authority/status/receipt/wire contracts and
+actual client idempotency headers in both transports. Mounted StrictMode tests
+hold responses to exercise single-flight, unsettled rollback remounts, owner
+replacement, fresh auth without replay, one-time key replay, denied no-request
+lanes, safe operation resume, terminal/parked/error/timeout and observer disposal.
+The additional `verify:admin-deployments-setup-mounted` and
+`verify:admin-webapp-inspection-mounted` commands cover state-aware setup,
+later-page target preflight, ordinary CI viewers/observation, scoped refresh and
+profile stale/unknown/fresh-auth journeys. The integration owner runs the
+reviewed modal inventories and actual
+light/dark, narrow and native-dialog browser verification.
+
+
+New workspace continuation uses the exact `operation.group.id` returned by durable
+create. That group identity is saved separately from the immutable create profile;
+resuming never rewrites `group_intent:new` into another create body. The address
+cursor reads options for that concrete group and explicitly links to the host's
+registered Domains destination when configured and independently admitted. A new
+workspace starts without an own/ancestor domain; configure or connect one for the
+named group, refresh options, then precheck the address and submit the returned
+`domain`/normalized `label` with the latest operation revision. Continue stays
+unavailable with a concrete prerequisite until an actual address choice exists.
+The frontend never borrows an installation-wide or unrelated workspace domain.
+
+A WebApp deployment marked `superseded` with `terminal:true` stops observation and
+settles its receipt, with `success:false`. It is not a successful rollout.
+
+Upload receipts durably record `completion_submitted`, the completion timestamp,
+and bounded prior deployment IDs before sending completion. Completion is a new
+promotion request: after an earlier failed, rolled-back or superseded attempt,
+repeating it can create another deployment. A lost response therefore blocks
+implicit registration/completion even after remount or same-manifest reselection.
+Reconcile reads the owning app summary/history and validates exact app, release,
+version and newly observed deployment identity before observing terminal outcome.
+Ambiguity remains unknown. Only a separately typed, freshly rechecked new deployment
+consent permits resetting the local upload phase; that consent sends no POST and
+requires a subsequent deliberate reselect/upload/deploy action. It neither erases
+an earlier attempt nor silently replays it. The mock follows the backend's narrow
+reuse rule: current release plus an active/live attempt, not permanent reuse for
+every release ID.
+
+
+Owner lifetimes survive React development StrictMode's setup/cleanup/setup replay.
+Query closures keep a stable identity/scope handle whose live signal is renewed
+before read effects resume; they do not retain an aborted first-render controller.
+Actual unmount, actor/session replacement and authority or active-state changes
+abort the old lifetime and discard late results. The mounted harness places
+StrictMode above the providers/router so React 19 actually replays initial effects,
+and verifies cold authorized bootstrap/platform reads through an asynchronous
+transport gate as well as real owner cancellation.
+
+### KISS presentation
+
+API and WebApps are distinct tasks; hosts admitting only one lane show no tab
+strip. Creation appears only in WebApps. The API lane shows last convergence and
+attempts, keeps unavailable/stale evidence visible, and puts secondary collector
+facts behind an info icon. API inspection separates Overview, Nodes and Activity
+and offers recovery only on the latest applicable attempt. WebApp inspection
+separates Overview, Deployments, Releases, Deploy and Settings; wholly read-only
+viewers omit Deploy. Useful node evidence adds tabs to an attempt dialog only
+when there is more than one content area. No single-item side rail or long
+collapsible section is introduced. Admin Dashboard stays unchanged. See
+[visual QA](admin-presentation.md).

package/docs/admin-dns-certificates.md

@@ -120,3 +120,163 @@ npm run verify:admin-dns-records
 
 Live verification is read-only. Do not request or revoke a real certificate
 without separate operator authorization.
+
+## Shared validation setup
+
+Use **Domains → Advanced → Shared validation setup**, or **Set up shared validation** in a
+group-managed Domain or Certificate header menu. Domain **Advanced validation** and
+Certificate **Delegation** show the same read-only facts. No new route or sidebar
+resource is added. The flow never reads certificate material.
+
+1. Select an authorized existing local Domain, or an eligible group and exact
+   apex name. Group selection uses `/api/dnsman/delegation/group-choice`, bounded
+   `search/start/size` and explicit `?id=` hydration. Product active-group context
+   and credential group choices do not authorize shared setup.
+2. Enter the existing public allocation target supplied by its controller and
+   **Inspect plan**. Inspection creates no connection or reference.
+3. **Prepare connection** and confirm the displayed domain/profile/target.
+   Preparation pauses direct local validation and renewal until authorization
+   and checking finish. Existing valid certificate material remains available.
+4. **Download request** saves `shared-validation-request.json`. Send it to the
+   allocation controller using your normal coordination channel. **Share request**
+   uses native file sharing when supported; **Copy request** is optional. Download
+   stays available after copy/share denial or cancellation. The canonical file is
+   at most 2048 UTF-8 bytes and has exactly `version:1`, `consumer_project_uuid`,
+   `client_ref`, `domain`, `allocation_ref`, with no wrapper, key, token or scope.
+5. The controller opens their deployment’s **Domains → Advanced → Shared validation setup →
+   Controller review**, checks access and uses **Import request**. There is no JSON
+   editor or controller URL. Empty, oversized, malformed, noncanonical or extra-field
+   files are refused before installation. Import alone grants nothing. The named
+   public fields fill the exact domain query; **Find allocations**, page if needed
+   and select the exact existing target. Only a matching request and resolved active
+   exact recipient enable **Review grant**, then **Allow issuance** after consent
+   names both apex and wildcard authority. No allocation is created.
+6. Back in the project, **Refresh**, **Connect approved validation**, then
+   **Check validation**. These are separate deliberate actions. Check requires
+   the approved existing one-hop `_acme-challenge.<apex>` CNAME.
+7. **Request wildcard certificate** issues this deployment's own apex-plus-
+   wildcard certificate. Existing valid exact-profile certificates remain in
+   place; queued work stays queued and due renewal reuses its lineage. Watch
+   the local certificate and separate renewal status, or Refresh after timeout.
+
+Only global DNS managers (`sys.manage_dns | sys.security`) see local mutation
+controls, and every action also requires the backend's current per-target flag.
+Controller operations additionally require v2 `shared_validation` and
+`can_manage_trust`, then exact-allocation authority. A human controller can have
+`can_consume:false`; local project setup uses the server-held project identity
+independently. Ordinary DNS managers cannot grant themselves trust. Groupless
+house domains are read-only and ineligible in this rollout; direct operation
+remains available and Portal never assigns a group automatically.
+
+### Local API and safe state
+
+| Method | Local route under `/api/dnsman` | Input |
+|---|---|---|
+| GET | `delegation/plan` | `{domain}` or `{group,name}`, optional `allocation_ref` |
+| POST | `delegation/connect` | Same target plus `allocation_ref`, optional explicit `restart:true` |
+| POST | `delegation/check` | `{delegation:<local id>}` |
+| POST | `delegation/request` | `{delegation:<local id>}`; no custom SANs, force or keys |
+| GET | `delegation/group-choice` | `id` or bounded `search/start/size` |
+
+All setup actions return Readiness v1. Portal strictly projects only public
+metadata and validates version, selected identity, source/target, fixed profile,
+booleans and enums. Expected 409s can include the same safe readiness DTO.
+Unknown containers and provider error text are discarded before state. Plans,
+descriptors and controller identities are modal-local; no draft is persisted or
+written to URLs, diagnostics or logs. Writes are imperative and non-retrying,
+freeze the scope, recheck auth/session/permission before send, and reject late
+responses after scope loss. After every attempted write, safe Domain,
+Certificate and legacy delegation caches are invalidated and plan/trust is
+refreshed. Ambiguous results require successful Refresh before another write.
+A 440 prompts authentication but never automatically repeats the operation.
+Every explicit session replacement, including the same user signing in again,
+clears controller capabilities, recipients and participant facts. Check controller
+access and select an authorized allocation again. A new grant also requires a matching imported request and freshly resolved active recipient.
+Closing a view cannot cancel a write already submitted.
+
+Controller POSTs use only the local `/api/dnsman/acme` endpoints:
+`capabilities {}`, `allocation/list {domain,cursor?}`,
+`trust/list {allocation_ref,cursor?}`,
+`trust/recipient {allocation_ref,consumer_project_uuid}`,
+`trust/grant {connection_request}` and
+`trust/revoke {allocation_ref,participant_ref}`. Each page contains at most 20
+rows. Only a capability-approved controller probes the allocation/trust routes;
+there is no arbitrary project directory, remote hub call, key provisioning or
+consumer/status call from a human JWT. Recipient and allocation authorization
+are repeated server-side on every operation.
+
+### Operator setup and mixed versions
+
+If the local plan says the hub is unconfigured or misconfigured, a deployment
+operator uses the existing server configuration delivery to set
+`DNSMAN_ACME_HUB_URL` to the already-used Maestro hub and
+`DNSMAN_ACME_HUB_API_KEY` to the already-provisioned protected project key in
+Django settings, normally `VAR_ROOT/django.conf`. Upgrade the hub first, then
+project API and every certificate worker; drain/restart old issuance workers
+before shared connections are accepted. Restart application and worker
+processes and **Refresh Portal**. A responsive API does not prove that workers
+were restarted; worker version is unknown unless authoritative telemetry exists.
+These settings are static deployment configuration, never DB Setting overrides,
+browser fields, arbitrary per-site URLs or values copied into descriptors.
+
+404/405 and unsupported new versions disable only shared setup; existing strict
+DNS config, direct-provider and legacy single-consumer certificate paths retain
+their contracts. 401/403 report access refusal instead of suggesting an upgrade.
+Disabled sharing, unconfigured/auth-rejected/unavailable hubs and unknown proof
+never display setup as complete. Portal does not bypass backend activation.
+
+### Repair and revocation
+
+ACME validation and traffic routing are separate. The validation CNAME does not
+route apex/www/API/app traffic. Follow the deployment's separate A/AAAA/CNAME
+traffic instructions. Missing, changed or chained validation proof shows the
+expected and bounded observed target and its check time. Ask the domain owner
+to restore the approved one-hop route after checking other consumers. Portal
+does not replace/remove that CNAME or rotate the allocation as a default repair.
+
+Controller maintenance starts cold with **Check controller access**, an **Exact
+ domain** and **Find allocations**. Native choices show target and owner UUID.
+**Next allocation page** / **First allocation page** and **Next project page** /
+**First project page** navigate bounded 20-row pages. Select an allocation to
+inspect participants, role, state, exact scope and revoked time. No request file
+or recipient lookup is needed for this path. An imported inactive consumer can
+fail recipient lookup while participant inspection, revoke and cleanup remain
+available. Owner participants cannot be revoked. **Refresh trust** checks current
+capabilities; an unsuccessful reconciliation blocks mutation until refresh succeeds.
+
+Controller revocation stops future DNS-01 validation for that project. Already-
+issued certificates remain valid until expiry or separate certificate revocation,
+and other trusted projects keep working. A 503 may occur after revocation was
+persisted; refreshed trust can say revoked while DNS cleanup remains unconfirmed.
+Retrying cleanup never regrants the reference. A revoked reference cannot be
+revived: the project must explicitly confirm **Prepare fresh request**, keep
+the existing target, and obtain a new exact controller grant.
+
+A valid local certificate with blocked/failed/retrying renewal is shown as
+“valid until …; renewal needs attention.” It is not labeled expired or revoked
+as a repair. Material custody is API-node evidence, not proof that any serving
+host installed that certificate. Shared pending/broken/revoked routing never
+permits fallback TXT writes through the direct provider. Private keys stay in
+each deployment.
+
+The mock showcase includes deterministic controller-maintenance pages and an inactive consumer, plus the complete project/controller handshake, viewer,
+revoked, pending/changed/chained DNS, disconnected/unconfigured/disabled hub,
+older API, failed renewal and 390px embedded-content scenarios. Scenario changes
+reset mock shared state; identity changes preserve it. Leaving the demo restores
+its default mock identity and scenario. `verify:admin-dns-shared-validation`
+runs API/projection and React StrictMode mounted contracts. Real browser proof
+remains required for focus, native-dialog stacking, clipboard and both themes.
+
+Owner and consumer project identities preserve existing lowercase16hex Group
+IDs as well as the previously supported32hex and canonical UUID forms. They
+are compared exactly and never padded, regenerated or rewritten. Client and
+participant references retain their strict UUID validation; a short project ID
+cannot stand in for either reference.
+
+
+Shared setup prerequisites now link literal deployment operators to the actual
+mount-aware Fleet shared-validation connection topic. It owns named approved
+profiles, write-only protected keys, expected/observed identity and revision-bound
+Preview/Publish/Apply. Ordinary DNS managers receive a concrete domain, next
+action and checked-time handoff with no private inputs or private API background
+calls. This route does not perform the protected hub activation ceremony.

package/docs/admin-dns-domains.md

@@ -0,0 +1,92 @@
+# Domains
+
+`DomainsPage` is the everyday global DNS inventory at `/dns/domains`, under the
+host Admin mount. Import it from `portal-mojo/admin/infrastructure`. It keeps
+`DomainModel`, the `admin:dns:domains` table persistence key and server search,
+provider/status filters, sorting and paging. Scope comes from each row's group
+or Platform; the active product group is never used.
+
+The header exposes **Register existing**, **Adopt**, and **Buy domain**. Register
+and Buy need global `sys.manage_dns | sys.security`. Adopt also needs literal
+`me.is_superuser === true`; the backend independently refuses noninteractive
+and key-backed authority. Viewer sessions can inspect domains, DNS records and
+certificates without mutation controls.
+
+## Explicit onboarding
+
+`showDomainOnboarding()` preserves its original menu. An optional
+`{ initialMode: 'menu' | 'register' | 'adopt' | 'purchase' }` opens a workflow
+directly. The page imports the dialog only after a button click.
+
+Register existing selects one authorized group from bounded
+`/api/dnsman/credential/group-choice`, then an active verified GoDaddy
+credential queried through `DnsCredentialModel` with exact group/provider and
+verification filters. No credential selector mounts before an explicit group.
+The selector remounts by group, clears its selection on group change and rejects
+resolved credentials from another group or unsupported/unusable credentials.
+There is no `/api/group` read, free-form group id, provider-secret input or
+provider-account enumeration. The exact normalized name is probed for ownership
+without spending money. The only body is `{ group, domain, credential }`.
+
+Adopt takes one normalized existing public zone name, then explicitly reviews
+that name and Platform scope before posting `{ domain }`. It never supplies
+`group` or `create_zone`, discovers inventory or assigns a tenant. Review and
+mutation guard native dialog dismissal; Cancel review performs no mutation.
+Registration/adoption use an immediate single-flight ref. An unknown outcome
+invalidates inventory and requires operator review before starting another flow.
+
+Buy preserves the bounded typed-TLD, prerequisite, tri-state search and durable
+ledger flow documented in [the registrar reference](admin-dns-registrar.md).
+The purchase body is exactly `{ group, purchase, confirm_token, confirm_domain,
+confirm_price }`. Name and decimal price come from the immutable validated quote,
+not editable confirmation inputs. The quote token is removed from its mounted
+ref before the operation and kept transient through `withFreshAuth`; only a 440
+may resume the identical body once. Cancelled step-up and other failures never
+replay. An attempted purchase is terminal in that mounted wizard and reconciles
+against the durable ledger, including ambiguous provider outcomes.
+
+## Inspection and registrar settings
+
+A row opens the standard `modal.detail` overview. Server-owned name, provider,
+status, scope, registration/expiry dates and redacted failure remain read-only.
+DNS Records is a direct shortcut for Route 53 and GoDaddy; Mojo explains its
+certificate-only limitation. Shortcuts derive their mount from the observed DNS
+route, so root, `/admin` and embedded prefixes work. Serving links explicitly
+navigate to the mount's sibling `/edge/vhosts`; they are outside the registry
+whose routes are relative to `/dns`.
+
+Only Route 53 managers receive **Registrar settings**. Its focused guarded native
+modal sends only changed boolean `auto_renew`/`privacy` fields to the existing
+generic domain save endpoint. It never edits group, credentials, raw metadata,
+protected fields or registrar contacts. Every attempted save authoritatively
+refetches and invalidates DomainModel, including rejection. HTTP success alone
+is not registrar success: a nonempty `last_error` stays visible with a historical
+warning and instructions to inspect the registrar. Uncertain writes keep the
+modal open, disable additional writes and require review. There is no automatic
+retry. GoDaddy registrar/privacy/WHOIS management remains in GoDaddy; Mojo is
+certificate-only. Unknown providers remain labeled and read-only.
+
+## Advanced validation
+
+**Domains → Advanced → Shared validation setup** opens without an existing
+domain, preserving external-domain consumer setup and controller review.
+Domain detail retains Advanced validation, DNS Records and Certificates sections,
+existing registered related links and the permission/readiness-gated setup action.
+Descriptor import/export, TLS paths and shared-validation protocol are unchanged.
+
+## Verification and showcase
+
+`verify-admin-domains.mjs` exercises the independent strict purchase peer,
+fresh-auth continuation/cancellation and ambiguous no-replay. Its central mock
+contract leg requires missing/mismatched name and decimal-price tuples to leave
+the quote unspent. `verify-admin-domains-mounted.mjs` mounts real wizard, picker,
+page and editor components to prove scope isolation, action authority, deliberate
+adoption, registrar reconciliation and mount-aware navigation. The closing browser
+pass supplies native focus, responsive layout and light/dark evidence.
+
+The focused **Admin → Domains** showcase uses mock manager, platform and viewer
+identities and preserves every earlier DNS showcase.
+
+### KISS presentation
+
+Domain/provider share one table cell. The page header owns registration/adoption/purchase; technical registrar facts are in Registration details. Provider warnings remain visible. See [visual QA](admin-presentation.md).

package/docs/admin-dns.md

@@ -37,6 +37,8 @@ domain includes registration/hosted-zone presence, safe zone metadata,
 tracking/adoption state, and a reason. `untracked=true` returns only untracked
 rows; discovery and assignment remain interactive-superuser operations.
 
+The everyday inventory and three onboarding actions are documented in [admin-dns-domains.md](admin-dns-domains.md).
+
 The operator registrar workflow is documented in [admin-dns-registrar.md](admin-dns-registrar.md). It does not use discovery: House adoption is manual exact-name only. Purchase tokens remain transient, all post-confirmation outcomes reconcile through the read-only ledger, and contact PII remains imperative/local.
 
 These responses require local call-flow handling and must never enter Query or
@@ -84,3 +86,19 @@ See [Admin modal policy](admin-modals.md) for header actions, content-only
 sections, supported lifecycle fields and retained irreversible exceptions.
 Provider credentials retire/reactivate through `is_active`, keeping history;
 rotation remains write-only and imperative. Built-in credential Delete is absent.
+
+## Shared wildcard validation
+
+Domains offers **Advanced → Shared validation setup** to global DNS
+managers even when server setup needs an operator. Domain detail includes
+read-only **Advanced validation**; its context action and Certificate Delegation compose
+the same focused flow. See [the human walkthrough and exact
+contracts](admin-dns-certificates.md#shared-validation-setup).
+
+Shared setup uses independent Readiness v1/hub v2 adapters. It never changes the
+strict legacy `/config` response contract. A controller grant is explicit
+apex/wildcard certificate issuance authority; local DNS management alone cannot
+supply it. Only public five-field connection requests are copied. No private
+key, PEM, DNS credential or protected hub key is requested, read, persisted or
+logged. Deployment operators deliver static hub settings server-side and restart
+API/workers. Validation CNAME routing remains separate from traffic routing.