portal-mojo 0.2.19 → 0.2.20

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-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 → Shared validation setup**, or **Set up shared validation** in a
+group-managed Domain or Certificate header menu. Domain **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 → 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.md

@@ -84,3 +84,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
+
+The existing Domains header offers **Shared validation setup** to global DNS
+managers even when server setup needs an operator. Domain detail includes
+read-only **Validation**; its header 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.

package/docs/admin-fleet-configuration.md

@@ -7,8 +7,9 @@ page checks `is_superuser === true` before fetching. Backend authority remains
 mandatory, including rejection of diagnostic/key-backed sessions and fresh auth.
 
 Applications register their schema in django-mojo. The page renders the returned
-section, label, description, default, type and restart requirement; no application
-setting names are hardcoded. Each field defaults to Keep current value. Set value
+section, label, description, default, type and restart requirement; application schemas remain server-owned. The three managed shared-validation
+connection fields route to the dedicated topic below, rather than appearing as
+independently editable generic fields. Each field defaults to Keep current value. Set value
 and Remove published override are explicit actions. Clearing falls back to base
 configuration/default; it does not promise erasure of a bootstrap secret.
 
@@ -48,3 +49,98 @@ example. Mock Portal uses representative registered settings and an offline node
 Django receives this page only after a canonical Portal artifact is built and
 vendored; follow `docs/admin-artifact.md` and the Django vendor tool. Ordinary
 Vite build output is not the canonical artifact.
+
+## Shared validation connection
+
+Operations → Fleet Configuration → Shared validation connection is a private, lazy
+route. It requires a current literal superuser; the server additionally requires
+an active interactive session, same-origin writes and fresh authentication.
+Key-backed sessions are rejected by the server even when their user is an owner.
+
+On the validation hub, update every expected node using the existing Deployments
+controls, then use **Enable shared validation** once. The compact hub section is
+independent of consumer connection configuration and uses the same Portal login,
+fresh authentication and native confirmation as the existing page. No separate
+operator service, login or wizard is required. Missing or incompatible deployment
+proof shows the ordinary prerequisite instead of an enabled action. Each issuer
+keeps its own ACME account, certificates and private keys; allocation trust still
+requires explicit approval in the DNS setup screen. Renewal remains automatic.
+
+`GET /api/account/admin/fleet/shared-validation/hub` returns
+`{version:1, enabled, configured, deployment_uuid, can_enable, reason}`.
+The deployment UUID is canonical lowercase with hyphens, unlike consumer project
+UUIDs. `POST` takes only `{deployment_uuid}` after confirmation. The backend
+rechecks the complete deployed roster and framework version atomically before
+enabling. A stale deployment, failed read or fresh-auth refusal requires Refresh
+and another deliberate review; mutations are never replayed. Keep the compatible
+framework on every node after enabling sharing.
+
+The panel consumes the private `/api/account/admin/fleet/shared-validation`
+contract. Choose a named approved hub profile, inspect its exact origin and
+original project UUID, then Keep, Replace or Disable the connection. Replacement
+is a normal write-only password field; blank preserves the existing credential.
+The approved catalog fixes the origin. Arbitrary URLs and raw JSON are not inputs.
+
+Project identity fields also accept existing lowercase16hex Group IDs, preserving
+the exact value through profiles, observations and protected key issuance. Fleet
+revisions/operation IDs remain32hex and deployment IDs remain canonical UUIDs.
+The legacy identity showcase fixture changes wire data only; no Group identity
+is migrated or rewritten.
+
+Preview probes the candidate without saving it. Publication has a separate
+confirmation, frozen against the preview and auth session. Publishing revalidates
+the catalog and expected revision; it does not Apply. Apply has another
+confirmation and targets the exact current revision. Every expected node must
+report installed, restarted and combined request-service/job-engine/scheduler
+health at that revision and the expected topic profile/project identity. Offline,
+draining, stale, partial and missing-node results remain unconfirmed. The UI
+polls at most120 observations and offers deliberate Refresh afterward. Verified
+connection identity with `sharing_ready=false` still needs sharing enabled on the
+approved hub. Refresh the connection after enabling it there.
+
+Create the replacement on the approved hub with the named **ACME validation
+consumer** key form. Preview/Publish, Apply, verify every expected node, then
+explicitly review and deactivate the old key in the hub inventory. Issuance,
+publication and successful dispatch never retire keys. Disable masks the whole
+connection tuple and base credential without deleting base settings or revoking
+remote trust; retained/shared identities can make disabling ineligible.
+
+Secrets remain in an uncontrolled mounted password input and a short-lived
+imperative request draft. They never enter Query/Mutation caches, URL/history,
+storage, receipts or logs. These new writes call `requestFreshAuth` without
+replaying the attempted action; the existing generic Fleet helpers keep their
+prior behavior. Auth/session change or unmount invalidates drafts and closes
+owned confirmations. Double activation is single-flight. A409 revision/catalog
+conflict or `configuration_busy` requires Refresh and a deliberate retry. An
+uncertain publication or issuance may have persisted; read authoritative status
+or exact Group inventory before another attempt.
+
+Unavailable APIs, missing DNSMan/publisher/delegation/schema/enrollment or an empty
+approved catalog render a concrete blocked state. Bootstrap supplies `admin_path`
+and permission facts for existing legacy System Setup, Deployments, topology and
+Fleet Scaling links. Links are same-origin and capability-gated. The backend's
+semantic `capacity` hint maps to the actual registered `#/fleet` route. These
+legacy destinations retain their protected confirmations, policy, release holds
+and IaC restrictions. This React topic reuses those controls without a new
+deployment or root authority service.
+
+The Runtime settings showcase mounts the actual connection panel with central
+mock scenarios and operator/ordinary-manager identities. The named
+`verify:admin-shared-validation-config` gate includes private DTO/API and mounted
+StrictMode contracts, and is included once by `verify:admin-contracts`. Browser
+proof remains necessary for real native dialogs, keyboard/focus and390px in both
+themes. Mock receipts are fixtures, never live configuration evidence.
+
+The private form uses an inline-size container: fact labels stack above UUIDs and
+revision values below420px of available content, including a narrow embedded
+Admin host. The existing Admin sidebar's Collapse control supplies its normal
+compact host at390px; the topic does not change global navigation behavior.
+
+Every successful authoritative refresh invalidates a preview when revision,
+catalog, profile, identity or credential facts change. Late preview/operation
+responses cannot restore spent consent or overwrite a newer observation. After
+the automatic observation limit, explicit Refresh re-observes the tracked exact
+operation and resets the read budget; it never dispatches another Apply. Only
+known healthy report/node statuses with no top-level or node error can turn the
+combined proof green. Apply/read replies remain bound to their exact operation
+ID and requested/tracked revision.

package/docs/admin-identity-directories.md

@@ -35,6 +35,18 @@ existing system permission gate and conditional queries. Parent, child, member
 and user navigation opens native detail modals while keeping the directory
 underneath.
 
+The Sub-Groups section carries the "Administrators can create sub-groups"
+switch for `sys.groups | sys.manage_groups` holders only; nobody else sees it.
+It reads `metadata.protected.allow_member_subgroups === true` (anything else
+is off) and changes it only through the django-mojo Group action
+`POST /api/group/<id> {"allow_member_subgroups": true|false}`, which answers
+`{"status": true, "allow_member_subgroups": <bool>}`. Never write
+`metadata.protected` directly: that path refuses `manage_groups` admins. The
+action needs django-mojo with #9126; the server refuses a caller without the
+global grant with 403 and a non-boolean with 400. While on, people who manage
+the group as members can create groups directly under it; the setting is not
+inherited by the new groups, and turning it off leaves existing groups alone.
+
 The group model and section code are adapted from the reference portal at
 `v0.2.5` commit `93c7fdfeb3096d33010e72bd4483cf9ca6e3d6f5`. The source hashes
 and corresponding package hashes are recorded in

package/docs/admin-modals.md

@@ -135,3 +135,31 @@ browser interactions for all family bodies, both themes, desktop/narrow,
 keyboard navigation and console checks. The lazy Showcase **Admin modal audit**
 demo supplies long-title, rich/zero/dot badges, nested editor, lifecycle-cancel and
 embedded-host cases. Existing ToastHost top-layer visibility work remains separate.
+
+## Shared validation confirmations
+
+The DNS shared-validation editor freezes the target group/domain, existing
+allocation and session while an operation is pending. Grant additionally freezes
+the imported request, active exact recipient UUID and client reference. Participant
+revoke/cleanup freezes the selected current-page participant independently of any
+request or recipient lookup; cleanup retry leaves the reference revoked.
+Its owner AbortSignal closes only its confirmation on unmount, scope loss or
+auth/session replacement; submitted writes can still persist. Escape/backdrop
+and Close are unavailable while the outer operation is pending.
+
+Prepare explains the pause of direct validation/renewal while valid material
+remains available. Grant names the exact project and apex/wildcard issuance
+authority and independent private-key custody. Revoke explains that future
+validation stops, already-issued certificates remain valid and other consumers
+keep working. Revoked references require a fresh, explicitly prepared request.
+No confirmation is inferred from a copied descriptor. Fresh authentication
+prompts without replay; every submitted result reconciles before another write.
+
+
+The protected connection topic separately confirms Publish and Apply, naming
+profile/project and exact revision consequences. The ACME consumer key form
+confirms the current original Group name/UUID and fixed protected purpose before
+issuance; its token display is transient and the existing audited reveal is
+available for recovery. Every owned nested dialog receives the auth-owner abort
+signal. Session replacement, scope loss and unmount close those dialogs; submitted
+writes may still persist and are never replayed after fresh authentication.

package/docs/auth-pages.md

@@ -124,12 +124,18 @@ Client surface (`portal-mojo/client`):
 - `withFreshAuth(fn)` — run fn; on a 440 prompt, then retry **once** after a
   successful re-login; a dismissed prompt rejects with the ORIGINAL error.
 
-The modal re-prompts credentials OVER the current screen — page state
-survives. It pins the identity to the current session's email (step-up is
-"prove you are still you"), offers password + passkey + the MFA step, and
-keeps the session in its original storage (`sessionIsPersistent()` →
-`remember`). Dev affordance: `__mojo.requestFreshAuth()` in the console
-exercises the modal without a 440.
+In hosted mode (including packaged Admin), the native dialog offers Cancel
+and Continue to sign-in. Continue opens the existing configured sign-in page
+with `force_reauth=1`, so Google-only deployments can use Google. It preserves
+the exact return route and original storage choice. The pending challenge
+resolves false before unloading: after returning, re-read and deliberately
+retry the action. Picking another account starts a new session and screen;
+the former account's operation is never carried over.
+
+In explicit in-app/mock mode the modal re-prompts credentials over the current
+screen, pins the current email when available, and keeps the existing
+password/passkey/MFA and storage behavior. Dev affordance:
+`__mojo.requestFreshAuth()` exercises the modal without a 440.
 
 Call-site pattern:
 
@@ -172,6 +178,12 @@ bouncer-enforcing deployments.
 
 ## Mock affordances
 
+`npm run verify:hosted-reauth` covers the mounted hosted confirmation and
+return/storage paths. For native dialog, responsive and theme checks, run
+`node scripts/serve-hosted-reauth.mjs` and open its printed local URL. The
+fixture uses the actual Portal host/bridge and a simulated Google-only sign-in
+page; it does not prove a live OAuth provider exchange.
+
 Under the mock transport the pages show inline dev hints: password `mojo`
 for any seeded user (e.g. `ian@mojoverify.com`); Maya (seeded user 2) requires
 MFA; TOTP `123456`, recovery `mock-recovery`, and SMS `654321`; reset code

package/docs/auth.md

@@ -102,11 +102,25 @@ its bot-check interstitial). Flow:
    `<origin>/auth?redirect=<HASH-FREE current url>`. Hash-free is
    load-bearing: the page string-appends `?auth_code=<code>` to the
    redirect, and a `#` in it would swallow the code.
-2. User signs in on the hosted page; it mints a single-use 60s handoff code
+2. User signs in using that page's configured methods (Google, password,
+   passkey, etc.). Same-origin return uses its existing stored session;
+   a cross-origin return mints a single-use 60s handoff code
    (`POST /api/auth/handoff`) and navigates back with `?auth_code=`.
 3. `handleAuthCodeFromURL()` (boot) exchanges it (`POST /api/auth/exchange`),
    scrubs the code from the URL synchronously, restores the stashed route.
-   Handles a hash-embedded `#/route?auth_code=` landing too.
+   It also restores same-origin returns without a code. Handles a
+   hash-embedded `#/route?auth_code=` landing too. Await this at boot before
+   creating the router.
+
+`redirectToHostedAuth({forceReauth: true})` uses the same page with
+`force_reauth=1`, bypassing its automatic existing-session check. It retains
+the initiating persistent/session-only choice, including when the hosted
+page writes localStorage. `remember` may explicitly supply the choice captured
+when the challenge opened. Tab-local return metadata contains only the route,
+destination, time and storage choice; it is consumed once, expires after 30
+minutes, and applies only at the matching origin/path/query. It never carries
+an operation or establishes freshness. The server still enforces `auth_time`.
+When storage cannot retain the choice, step-up navigation returns false.
 
 `hostedAuthUrl()` returns null under the mock transport — there is no page
 to host; the UI should fall back to a dev affordance (`__mojo.login(...)`).

package/docs/collection-select.md

@@ -130,3 +130,17 @@ too — there is no parallel fetch path.
   handed a picker that says to pick a group they can't pick there.
 - Don't wire `onChange` to a per-keystroke autosave expectation — it fires
   on commit (that is the point; see the B3 autosave contract).
+
+### Optional ingress projection
+
+`sanitizeRow={(row) => publicProjection(row)}` projects list and one-record
+responses before Query cache storage. Such pickers use a separate cache keyed
+by the sanitizer identity, auth UID and session revision; they never scan or
+reuse raw endpoint caches. Keep the callback stable. Default consumers retain
+the existing shared model keys and behavior. The callback must return only the
+approved fields or reject malformed input. Full selected objects also need to
+be projected by the caller before passing them in.
+
+An endpoint with query-based hydration should hydrate through its own safe
+`?id=` helper and pass the full selected object; do not pass a bare id that
+would invent a `/<id>` record route.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.19",
+    "version": "0.2.20",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/admin/credentials/AcmeConsumerKeyDialog.tsx

@@ -0,0 +1,88 @@
+import { useEffect, useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { requestFreshAuth } from '../../client/runtime';
+import { CollectionSelect, FlatRow, modal } from '../../ui';
+import { SecretBox } from './secret-dialog';
+import { OperatorError, usePrivateOperator, projectIdentity } from '../fleet-configuration/shared-validation-data';
+import { issueAcmeKey, projectKeyGroup, readAcmeRecipient, readKeyGroup, readRecipientKeyInventory, revealRecipientKey, type AcmeRecipient, type KeyGroup, type KeySummary } from './acme-consumer-key';
+import { GroupApiKeyModel, type CredentialGroup } from './models';
+
+
+export function AcmeConsumerKeyButton({ group }: { group?: CredentialGroup }) {
+    const owner = usePrivateOperator();
+    return owner.allowed ? <button className="btn btn-compact" onClick={() => void openAcmeConsumerKey(group)}>Create ACME consumer key</button> : null;
+}
+
+export function openAcmeConsumerKey(group?: CredentialGroup) {
+    let pending = false;
+    return modal.open((close) => <AcmeConsumerKeyDialog group={group} close={() => close(null)} onBusy={(busy) => { pending = busy; }} />, { size: 'lg', canDismiss: () => !pending });
+}
+export function AcmeConsumerKeyDialog({ group: fixedGroup, close, onBusy }: { group?: CredentialGroup; close: () => void; onBusy?: (busy: boolean) => void }) {
+    const owner = usePrivateOperator(), qc = useQueryClient();
+    const [group, setGroup] = useState<KeyGroup | null>(null), [recipient, setRecipient] = useState<AcmeRecipient | null>(null);
+    const [inventory, setInventory] = useState<KeySummary[] | null>(null), [blocked, setBlocked] = useState(false), [busy, setBusy] = useState(false), [error, setError] = useState(''), [notice, setNotice] = useState('');
+    const name = useRef<HTMLInputElement>(null), flight = useRef(false), generation = useRef(0), recipientOwner = useRef('');
+    const selected = useRef(group?.id); selected.current = group?.id;
+    const opener = useRef<HTMLElement | null>(null);
+    const pending = (value: boolean) => {
+        if (value) opener.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+        flight.current = value; setBusy(value); onBusy?.(value);
+        if (!value) { const fence = owner.fence(), target = opener.current; requestAnimationFrame(() => { try { fence.beforeSend(); if (target?.isConnected) target.focus(); } catch { /* Former owner cannot regain focus. */ } }); }
+    };
+    useEffect(() => () => { generation.current++; onBusy?.(false); }, []);
+    useEffect(() => { setRecipient(null); setInventory(null); setBlocked(true); if (name.current) name.current.value = ''; }, [owner.key]);
+    const failure = async (reason: unknown) => { const safe = reason instanceof OperatorError ? reason : new OperatorError('unavailable'); setError(safe.message); setBlocked(true); if (safe.kind === 'fresh') await requestFreshAuth(); };
+    useEffect(() => {
+        if (!fixedGroup || !owner.allowed) return;
+        const fence = owner.fence(); void readKeyGroup(fixedGroup.id, fence).then((g) => { fence.beforeSend(); setGroup(g); }).catch((e) => { if (!fence.signal?.aborted) void failure(e); });
+    }, [fixedGroup?.id, owner.key]);
+    useEffect(() => { setRecipient(null); setInventory(null); setError(''); setBlocked(false); generation.current++; }, [group?.id]);
+    const refresh = async () => {
+        if (flight.current || !group || !owner.allowed) return;
+        const fence = owner.fence(), id = group.id, run = ++generation.current; pending(true); setError(''); setRecipient(null);
+        try {
+            const current = await readKeyGroup(id, fence); fence.beforeSend();
+            if (selected.current !== id || generation.current !== run) return;
+            if (!current.uuid) throw new OperatorError('invalid'); projectIdentity(current.uuid);
+            const [person, keys] = await Promise.all([readAcmeRecipient(current.uuid, fence), readRecipientKeyInventory(id, fence)]); fence.beforeSend();
+            if (selected.current !== id || generation.current !== run) return;
+            recipientOwner.current = owner.key; setGroup(current); setRecipient(person); setInventory(keys); setBlocked(false);
+        } catch (e) { if (!fence.signal?.aborted && generation.current === run) await failure(e); }
+        finally { if (!fence.signal?.aborted) pending(false); }
+    };
+    const displaySecret = async (value: string, title: string) => {
+        const fence = owner.fence(); let secret: string | null = value;
+        try { fence.beforeSend(); await modal.open((done) => <div className="modal-pad"><h2 className="modal-title">{title}</h2><p>This transient display is not stored in Portal. A later explicit Token reveal in the key inventory is audited and remains available.</p><SecretBox secret={secret ?? ''} ariaLabel="ACME consumer token" /><p>Enter the replacement normally in the receiving deployment’s protected connection form. Publish, Apply and verify every expected node before explicitly deactivating the old hub key. Issuance alone grants no allocation trust or hub activation.</p><div className="modal-actions"><button className="btn" onClick={() => done(null)}>Close token</button></div></div>, { size: 'lg', signal: fence.signal }); }
+        finally { secret = null; value = ''; }
+    };
+    const issue = async () => {
+        if (flight.current || !owner.allowed || recipientOwner.current !== owner.key || !recipient?.can_issue || !group || blocked) return;
+        const fence = owner.fence(), person = recipient, id = group.id, keyName = name.current?.value.trim() ?? ''; if (!keyName) { setError('Name this replacement key.'); return; }
+        const run = generation.current; pending(true); setError(''); let attempted = false;
+        try {
+            const confirmed = await modal.open<boolean>((done) => <div className="modal-pad"><h2 className="modal-title">Issue protected ACME consumer key?</h2><div className="modal-message"><p>{person.consumer_label} · <code>{person.consumer_project_uuid}</code></p><p>Key: {keyName}</p><p>Grant this exact original hub project the protected ACME validation consumer purpose. The fixed grant is dnsman_acme_federation, with no linked user or override. This does not grant allocation trust or enable shared validation. The existing key stays active.</p></div><div className="modal-actions"><button className="btn" onClick={() => done(false)}>Cancel</button><button className="btn btn-primary" onClick={() => done(true)}>Issue replacement key</button></div></div>, { size: 'md', signal: fence.signal });
+            if (!confirmed) return; fence.beforeSend(); if (selected.current !== id || generation.current !== run) throw new OperatorError('conflict');
+            attempted = true; const result = await issueAcmeKey(person, keyName, fence); fence.beforeSend();
+            if (selected.current !== id || generation.current !== run) { result.token = ''; return; }
+            setNotice(`Key ${result.key.name} issued. The old key was not retired.`);
+            try { await displaySecret(result.token, 'ACME consumer key issued'); } finally { result.token = ''; }
+        } catch (e) { if (!fence.signal?.aborted) await failure(e); }
+        finally {
+            if (attempted) { if (name.current) name.current.value = ''; await GroupApiKeyModel.invalidate(qc); if (!fence.signal?.aborted && selected.current === id) { try { const keys = await readRecipientKeyInventory(id, fence); fence.beforeSend(); setInventory(keys); } catch { setBlocked(true); setError('Issuance may have persisted. Refresh the Group key inventory before issuing another key.'); } } }
+            if (!fence.signal?.aborted) pending(false);
+        }
+    };
+    const reveal = async (row: KeySummary) => {
+        if (flight.current || !owner.allowed || recipientOwner.current !== owner.key) return; const fence = owner.fence(); pending(true);
+        try { const value = await revealRecipientKey(row.id, fence); fence.beforeSend(); await displaySecret(value, `Audited token — ${row.name}`); }
+        catch (e) { if (!fence.signal?.aborted) await failure(e); } finally { if (!fence.signal?.aborted) pending(false); }
+    };
+    if (!owner.allowed) return <div className="modal-pad"><h2>Protected key access unavailable</h2><p>A current interactive literal superuser is required.</p><button className="btn" onClick={close}>Close</button></div>;
+    return <div className="modal-pad shared-validation-operator" style={{ minWidth: 0, overflowWrap: 'anywhere' }}><h2 className="modal-title">Create ACME consumer key</h2><p>Run this form on the approved hub. Choose its original recipient Group by name; a downstream tenant or acting user is not that identity.</p>
+        {fixedGroup ? <FlatRow label="Selected hub Group">{group?.name ?? fixedGroup.name}</FlatRow> : <CollectionSelect<KeyGroup> endpoint="/api/group" sanitizeRow={projectKeyGroup} value={group} label="Original hub recipient Group" disabled={busy} onChange={(_id, row) => setGroup(row ?? null)} />}
+        {group && <><FlatRow label="Group UUID"><code>{group.uuid ?? 'No valid UUID reported'}</code></FlatRow><button className="btn" disabled={busy} onClick={() => void refresh()}>Resolve recipient and refresh keys</button></>}
+        {error && <p className="form-alert" role="alert">{error}</p>}{notice && <p role="status">{notice}</p>}
+        {recipient && <div className="dns-shared-request"><FlatRow label="Actual active hub project">{recipient.consumer_label}</FlatRow><FlatRow label="Exact UUID"><code>{recipient.consumer_project_uuid}</code></FlatRow><FlatRow label="Purpose">ACME validation consumer</FlatRow><FlatRow label="Fixed protected grant"><code>{recipient.permission}</code></FlatRow><p>{recipient.grant_explanation}</p><p>Issuing a key does not grant allocation trust or activate the hub.</p><label className="field"><span className="field-label">Replacement key name</span><input className="input" ref={name} maxLength={200} disabled={busy || blocked || !recipient.can_issue} placeholder="Project shared validation" /></label><button className="btn btn-primary" disabled={busy || blocked || !recipient.can_issue} onClick={() => void issue()}>Review protected key issuance</button>{!recipient.can_issue && <p>Protected issuance is unavailable for this operator.</p>}</div>}
+        <h3>Recent Group key inventory</h3><p>After an uncertain response, Refresh this inventory and use audited reveal before creating another successor. Up to 100 recent keys are shown; generic key management remains in the existing inventory.</p>{inventory?.map((row) => <div className="dns-shared-request" key={row.id}><strong>{row.name} · #{row.id}</strong><p>{row.is_active ? 'Active' : 'Inactive'}</p><button className="btn" disabled={busy} onClick={() => void reveal(row)}>Reveal audited token</button></div>)}
+        <p>Replacement → protected connection Preview/Publish → Apply → verify every expected node → explicitly review/deactivate the old hub key. No key is rotated or retired by this form.</p><div className="modal-actions"><button className="btn" disabled={busy} onClick={close}>{busy ? 'Operation pending…' : 'Close'}</button></div></div>;
+}

package/src/admin/credentials/acme-consumer-key.ts

@@ -0,0 +1,34 @@
+import { choice, flag, label, nullable, object, OperatorError, positive, privateCall, projectIdentity, type PrivateScope } from '../fleet-configuration/shared-validation-data';
+import { GroupApiKeyModel } from './models';
+export const ACME_RECIPIENT_ENDPOINT = '/api/account/admin/fleet/shared-validation/recipient';
+export type KeyGroup = { id: number; name: string; uuid: string | null };
+export interface AcmeRecipient { purpose: 'acme_validation_consumer'; consumer_project_uuid: string; consumer_label: string; permission: 'dnsman_acme_federation'; can_issue: boolean; grant_explanation: string }
+export interface KeySummary { id: number; name: string; is_active: boolean }
+export function projectKeyGroup(v: unknown): KeyGroup { const r = object(v); return { id: positive(r.id), name: label(r.name), uuid: r.uuid == null ? null : label(r.uuid, 36) }; }
+export async function readKeyGroup(id: number, scope?: PrivateScope) { const g = projectKeyGroup(await privateCall(`/api/group/${positive(id)}`, null, scope)); if (g.id !== id) throw new OperatorError('invalid'); return g; }
+export function parseAcmeRecipient(v: unknown, expected: string): AcmeRecipient {
+    const r = object(v); const out = { purpose: choice(r.purpose, ['acme_validation_consumer']), consumer_project_uuid: projectIdentity(r.consumer_project_uuid), consumer_label: label(r.consumer_label), permission: choice(r.permission, ['dnsman_acme_federation']), can_issue: flag(r.can_issue), grant_explanation: label(r.grant_explanation, 300) };
+    if (out.consumer_project_uuid !== expected) throw new OperatorError('invalid'); return out;
+}
+export const readAcmeRecipient = async (consumer: string, scope?: PrivateScope) => parseAcmeRecipient(await privateCall(ACME_RECIPIENT_ENDPOINT, null, scope, { consumer_project_uuid: projectIdentity(consumer) }), consumer);
+export async function issueAcmeKey(recipient: AcmeRecipient, name: string, scope?: PrivateScope): Promise<{ key: KeySummary; token: string }> {
+    if (!recipient.can_issue || !name.trim()) throw new OperatorError('denied');
+    const r = object(await privateCall(ACME_RECIPIENT_ENDPOINT, { consumer_project_uuid: projectIdentity(recipient.consumer_project_uuid), expected_consumer_label: recipient.consumer_label, label: label(name.trim()), purpose: 'acme_validation_consumer' }, scope));
+    let secret = r.token; delete r.token;
+    try {
+        if (r.purpose !== 'acme_validation_consumer' || r.consumer_project_uuid !== recipient.consumer_project_uuid || r.consumer_label !== recipient.consumer_label) throw new OperatorError('invalid');
+        const key = object(r.api_key); if (key.permission !== 'dnsman_acme_federation' || key.is_active !== true || typeof secret !== 'string' || !secret || secret.length > 4096 || /\s/.test(secret)) throw new OperatorError('invalid');
+        return { key: { id: positive(key.id), name: label(key.name), is_active: true }, token: secret };
+    } finally { secret = null; }
+}
+export async function readRecipientKeyInventory(group: number, scope?: PrivateScope): Promise<KeySummary[]> {
+    const rows = await privateCall(GroupApiKeyModel.endpoint, null, scope, { group: positive(group), size: 100, sort: '-created', graph: 'default' });
+    if (!Array.isArray(rows) || rows.length > 100) throw new OperatorError('invalid');
+    return rows.map((v) => { const r = object(v), g = r.group && typeof r.group === 'object' ? object(r.group).id : r.group; if (g !== group) throw new OperatorError('invalid'); return { id: positive(r.id), name: label(r.name), is_active: flag(r.is_active) }; });
+}
+/** Same explicit audited graph as the existing Token control; no Query cache. */
+export async function revealRecipientKey(id: number, scope?: PrivateScope): Promise<string> {
+    const r = object(await privateCall(`${GroupApiKeyModel.endpoint}/${positive(id)}`, null, scope, { graph: 'token' }));
+    const value = nullable(r.token, (v) => label(v, 4096)); delete r.token;
+    if (!value) throw new OperatorError('unavailable'); return value;
+}