portal-mojo 0.2.19 → 0.2.21

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/client.md

@@ -458,3 +458,10 @@ now **rejects** a flat HTTP-200 refusal (top-level `success:false`) with
 - `err.errorCode` carries the refusal code and `err.data` the full reply, so
   the server's reason is no longer lost.
 - `defineModel` actions and `mojoAction` behave as before.
+
+`mojoCall` accepts optional `idempotencyKey` for a reviewed operation receipt. The
+transport validates 1–128 ASCII receipt characters (`A-Z`, `a-z`, `0-9`, `.`, `_`,
+`:`, `-`) and emits only the `Idempotency-Key` header. It does not expose arbitrary
+custom headers or record the key with sensitive bodies. Preserve the same receipt
+for a deliberate retry of the same operation; observe uncertain outcomes before
+creating another operation.

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/docs/combobox.md

@@ -19,6 +19,7 @@ interface ComboOption {
     value: ComboValue;
     label: string;          // what the input displays
     description?: string;   // muted second line in the list
+    disabled?: boolean;    // shown but never committed
     meta?: Record<string, unknown>;  // opaque; returned via onSelect
 }
 
@@ -32,6 +33,8 @@ interface ComboOption {
     minChars={0}    // typing auto-opens the list only at ≥ N chars
     maxSuggestions={10}  // caps the rendered list AND keyboard wraparound
     placeholder disabled readOnly required id className
+    inputRef={fieldRef} // input focus target for form validation
+    aria-label="Output" aria-describedby="output-help" aria-invalid={invalid}
 />
 ```
 
@@ -103,3 +106,18 @@ strings.
   containers and native dialogs do not clip it.
 - Styles live in `packages/portal-mojo/src/styles/components/combobox.css` (tokens only, both
   themes) and ship in `portal-mojo/styles.css`.
+
+## Fixed-choice dropdowns
+
+Use `allowCustom={false}` for enums and filters. Pass the same string/number
+type to `value` and each option. Disabled options remain visible (including
+a saved, unavailable selection); pointer, typed settlement and arrow navigation
+cannot commit them. Permission loss closes the list and discards the draft.
+Use `id` with a label or `aria-label`/`aria-labelledby`; description and validation
+attributes reach the input. `inputRef` supports validation focus.
+
+For short fixed lists that must show every choice, set `maxSuggestions` to the
+list length; searchable catalogs may retain the default cap. Shared tables,
+chart settings, filters and schema select fields use this same component.
+
+The chevron is a pointer shortcut for the input. It is hidden from assistive technology so a wrapping field label does not include redundant button text; the combobox input owns the name and keyboard interaction.

package/docs/popover.md

@@ -95,9 +95,10 @@ that here would close both layers on one keypress.)
 Outside-mousedown does NOT stop propagation: the click still activates
 whatever was under it (click a second trigger → this popover closes and
 that one opens). Clicks on the anchor are never "outside" — the anchor's
-own click handler owns its toggle. The listener attach is deferred one
-tick so the interaction that opened the popover can't immediately close
-it (source parity).
+own click handler owns its toggle. Outside-click registration waits one tick so the opener cannot close its own
+menu. Escape registration runs in a layout effect, before the opening frame
+paints. Only the most recently opened popover handles Escape; a dialog opened
+above its owner keeps its own dismissal behavior.
 
 ## Styling
 
@@ -125,7 +126,7 @@ baked in 20px padding + 260px min-width for its one tenant, the calendar
   to the consuming control.
 - The opening interaction can be `click` or `mousedown`-driven; both are
   safe. But if you open programmatically and simultaneously flip other
-  document state, remember listeners attach a tick later.
+  document state, only outside-click registration waits a tick. Escape protection is immediate.
 - Placement flips only bottom→top (per source). If content can be taller
   than the viewport, cap and scroll it in YOUR content styles.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.19",
+    "version": "0.2.21",
     "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/core/OperationsHelp.tsx

@@ -0,0 +1,10 @@
+import { useId, useRef, useState, type ReactNode } from 'react';
+import { Popover } from '../../ui/Popover';
+
+/** Keep explanatory copy one deliberate action away from the working surface. */
+export function OperationsHelp({ label, children }: { label: string; children: ReactNode }) {
+    const anchor = useRef<HTMLButtonElement>(null);
+    const [open, setOpen] = useState(false);
+    const id = useId();
+    return <><button ref={anchor} type="button" className="ops-help" aria-label={`About ${label}`} aria-expanded={open} aria-controls={open ? id : undefined} onClick={event => { event.preventDefault(); setOpen(value => !value); }}><i className="bi bi-question-circle" aria-hidden="true" /></button><Popover anchorRef={anchor} open={open} onClose={() => setOpen(false)} id={id} aria-label={`About ${label}`} className="ops-help-content">{children}</Popover></>;
+}

package/src/admin/core/index.ts

@@ -7,6 +7,7 @@ import { isChunkLoadError } from '../../ui/route-error';
 import { GroupContext } from '../../client/group-context';
 import { hasPermission, useMe } from '../../client/me';
 import type { PermSpec } from '../../client/model';
+import { AdminRouteContext, type AdminRouteContextValue } from './route-context';
 import { Guarded } from '../../ui/Guarded';
 import type { MenuConfig, MenuItem } from '../../ui/menu-registry';
 
@@ -127,7 +128,7 @@ function routeElement(route: AdminRoute): ReactNode {
         : createElement(route.component);
 }
 
-function guardedElement(section: AdminSection, route: AdminRoute, sections: readonly AdminSection[], mount: string): ReactNode {
+function guardedElement(section: AdminSection, route: AdminRoute, sections: readonly AdminSection[], mount: string, context: AdminRouteContextValue): ReactNode {
     const fallback = route.fallbackToFirstVisible
         ? createElement(AdminMountLanding, { sections: sections.filter((candidate) => candidate !== section), mount })
         : createElement(AdminDenied);
@@ -146,9 +147,9 @@ function guardedElement(section: AdminSection, route: AdminRoute, sections: read
     // navigation between packaged admin pages silently stopped rendering
     // (reproduced in both the reference portal and a consumer). The key
     // forces a fresh mount, and a fresh Suspense, per route.
-    return createElement(AdminGlobalScope, { key: relativePath(mount, section.basePath ?? section.id, route.path), children: createElement(Guarded, {
+    return createElement(AdminRouteContext.Provider, { key: relativePath(mount, section.basePath ?? section.id, route.path), value: context, children: createElement(AdminGlobalScope, { children: createElement(Guarded, {
         permission: section.permissions, fallback, children: routeGuarded,
-    }) });
+    }) }) });
 }
 
 /** Admin is global even when embedded beneath a product portal's provider. */
@@ -182,6 +183,7 @@ function AdminMountLanding({ sections, mount }: { sections: readonly AdminSectio
 export function adminSectionRoutes(sections: readonly AdminSection[], opts: { mount?: string } = {}): RouteObject[] {
     const mount = relativePath(opts.mount ?? '');
     const routes: RouteObject[] = [];
+    const context: AdminRouteContextValue = { mount: absolutePath(mount), paths: sections.flatMap((section) => section.routes.map((route) => absolutePath(mount, section.basePath ?? section.id, route.path))) };
     const rootSections = sections.filter((section) => relativePath(section.basePath ?? section.id) === '');
     const rootHasIndex = rootSections.some((section) => section.routes.some((route) => relativePath(route.path) === ''));
     if (mount && rootSections.length > 0 && !rootHasIndex) routes.push({
@@ -198,7 +200,7 @@ export function adminSectionRoutes(sections: readonly AdminSection[], opts: { mo
         });
         for (const route of section.routes) routes.push({
             path: relativePath(mount, base, route.path),
-            element: guardedElement(section, route, sections, mount),
+            element: guardedElement(section, route, sections, mount, context),
         });
     }
     return routes;

package/src/admin/core/route-context.ts

@@ -0,0 +1,6 @@
+import { createContext, useContext } from 'react';
+
+/** Internal registration facts for mount-aware links; never an authority decision. */
+export interface AdminRouteContextValue { mount: string; paths: readonly string[] }
+export const AdminRouteContext = createContext<AdminRouteContextValue | null>(null);
+export const useAdminRouteContext = () => useContext(AdminRouteContext);

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;
+}

package/src/admin/credentials/group-api-keys.tsx

@@ -1,5 +1,5 @@
 import { useQueryClient } from '@tanstack/react-query';
-import { useContext, useSyncExternalStore } from 'react';
+import { lazy, Suspense, useContext, useSyncExternalStore } from 'react';
 import {
     GroupContext,
     hasPermission,
@@ -42,6 +42,7 @@ import {
     type GroupApiKeyRow,
 } from './models';
 import { showSecretDialog } from './secret-dialog';
+const ProtectedKeyButton = lazy(() => import('./AcmeConsumerKeyDialog').then((m) => ({ default: m.AcmeConsumerKeyButton })));
 
 function groupLabel(group: GroupApiKeyRow['group']): string {
     if (group && typeof group === 'object') return group.name;
@@ -362,6 +363,7 @@ function GroupApiKeysContent({ group, permission }: { group: CredentialGroup; pe
                     <button className="btn btn-primary btn-compact" onClick={() => void actions.createKey(group)}>
                         <i className="bi bi-key" /> Create Key
                     </button>
+                    <Suspense fallback={null}><ProtectedKeyButton group={group} /></Suspense>
                 </div>
             )}
             {!isPending && rows.length === 0 && <p className="dim-italic">No API keys yet.</p>}
@@ -489,7 +491,7 @@ export function GroupApiKeysPage() {
         void modal.detail((close) => <GroupApiKeyDetail id={row.id} onClose={() => close(null)} />);
     };
     return (
-        <ModelTable<GroupApiKeyRow>
+        <><Suspense fallback={null}><ProtectedKeyButton /></Suspense><ModelTable<GroupApiKeyRow>
             model={GroupApiKeyModel}
             eyebrow="Account"
             title="Group API Keys"
@@ -507,6 +509,6 @@ export function GroupApiKeysPage() {
             onRowClick={openDetail}
             addLabel="New API Key"
             onAdd={actions.canManage ? () => void actions.createKey() : undefined}
-        />
+        /></>
     );
 }

package/src/admin/deployments/ApiDeploymentDetail.tsx

@@ -0,0 +1,58 @@
+import { useEffect, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useMe } from '../../client/runtime';
+import { Tabs } from '../../ui/Tabs';
+import { datetime } from '../../ui/format';
+import { modal } from '../../ui/modal';
+import { canReadApi, canRecoverApi, isInteractive, assertOwner } from './permissions';
+import { getPlatform, recoverApi } from './api';
+import { apiActions, platformProof } from './deployment-state';
+import { makeReceipt, settleReceipt } from './receipts';
+import { useDeploymentObservation, useDeploymentOwner } from './useDeploymentObservation';
+import { DeploymentHelp, ErrorNotice, Facts, Status, useCloseOnOwnerChange, useWrite } from './shared';
+import type { ApiAction } from './types';
+export function ApiDeploymentDetail({ id, onClose }: {
+    id: string;
+    onClose: () => void;
+}) {
+    const me = useMe(), s = useDeploymentOwner(), queryClient = useQueryClient();
+    const [tracking, setTracking] = useState<string | null>(null);
+    useCloseOnOwnerChange(s.key, onClose);
+    const q = useQuery({
+        queryKey: ['deployments', s.key, 'api-detail', id], queryFn: ({ signal }) => getPlatform(s.owner, signal), enabled: canReadApi(me.data) && isInteractive(), retry: false
+    });
+    const selected = q.data?.deployments.data?.items.find(x => x.id === id);
+    const identity = tracking ?? (selected && ['requested', 'queued', 'canary', 'fleet', 'deploying'].includes(selected.status) ? id : null);
+    const observed = useDeploymentObservation(s.owner, identity, async (signal) => { const p = await getPlatform(s.owner, signal); const a = p.deployments.data?.items.find(x => x.id === identity); if (!a)
+        throw new Error('Tracked deployment not observed'); return a; }, a => ['converged', 'failed', 'superseded', 'verified', 'partial', 'unknown'].includes(a.status));
+    const row = observed.value ?? selected, latest = q.data?.deployments.data?.items[0]?.id === row?.id, can = canRecoverApi(me.data) && isInteractive();
+    useEffect(() => { if (observed.state === 'terminal') void queryClient.invalidateQueries({ queryKey: ['deployments', s.key] }); }, [observed.state, observed.value?.id, observed.value?.status, queryClient, s.key]);
+    const openRecovery = async (action: ApiAction) => { let busy = false; await modal.open(close => <ApiRecoveryDialog id={row!.id} action={action} onBusy={value => { busy = value; }} onClose={() => close(null)} onResult={result => { setTracking(result); void q.refetch(); }}/>, { signal: s.signal, canDismiss: () => !busy }); };
+    if (!canReadApi(me.data) || !isInteractive())
+        return <div className="modal-pad"><p>API authority is no longer available.</p><button className="btn" onClick={onClose}>Close</button></div>;
+    return <div className="modal-pad admin-deployments deployment-dialog"><header className="deployment-dialog-header"><div><h2 className="modal-title">API deployment {row && <DeploymentHelp label="API attempt information"><Facts rows={[["Attempt", row.id], ["Source", row.source], ["Actor", row.actor], ["Retry of", row.retry_of]]}/><p>Reported success and restart proof are separate. Recovery applies to the latest attempt and does not accept an arbitrary commit.</p></DeploymentHelp>}</h2><p className="dim mono">{row?.sha.slice(0, 12) || 'Attempt details'}</p></div><div className="deployment-actions"><button className="btn" disabled={q.isFetching} onClick={() => { void q.refetch(); observed.refresh(); }}>Refresh evidence</button><button className="btn" aria-label="Close API deployment" onClick={onClose}>Close</button></div></header>
+        {q.isError && <ErrorNotice>Deployment observation unavailable. {q.data ? 'Previous evidence is shown.' : 'Refresh to try again.'}</ErrorNotice>}
+        {row && <div className="deployment-toolbar"><Status value={row.status}/>{can && latest && <div className="deployment-actions">{apiActions(row.status).map(action => <button key={action} className="btn" onClick={() => void openRecovery(action)}>{action === 'retry' ? 'Retry same commit' : action === 'verify' ? 'Verify nodes' : 'Converge fleet'}</button>)}</div>}</div>}
+        <Tabs ariaLabel="API deployment details" items={[
+            {key:'overview',label:'Overview',panel:<div className="deployment-tab-content">{row ? <><Facts rows={[["Commit", <code>{row.sha}</code>], ['Evidence', platformProof(row)], ['Started', row.started ? datetime(row.started) : row.created ? datetime(row.created) : 'Time unavailable'], ['Finished', row.finished ? datetime(row.finished) : 'Not finished']]}/>{row.detail && <p>{row.detail}</p>}</> : <p>{q.isPending ? 'Loading attempt…' : q.data?.deployments.data ? 'Attempt unavailable in the latest 50 records.' : 'The collector did not return deployment evidence.'}</p>}</div>},
+            {key:'nodes',label:'Nodes',panel:<div className="deployment-tab-content">{row?.node_evidence.length ? row.node_evidence.map((n,i)=><article className="deployment-evidence" key={i}><strong>{n.runner}</strong><Status value={n.status}/>{n.sha && <p className="mono">{n.sha}</p>}{n.detail && <p>{n.detail}</p>}</article>) : <p>No node proof observed.</p>}</div>},
+            {key:'activity',label:'Activity',panel:<div className="deployment-tab-content">{row?.diagnosis.length ? <><h3>Failure diagnosis</h3>{row.diagnosis.map((d,i)=><article className="deployment-evidence" key={i}><strong>{d.runner}</strong><Status value={d.status}/><p>{d.detail}</p>{d.stderr_tail && <pre className="deployment-code">{d.stderr_tail}</pre>}</article>)}</> : <p>No failure diagnosis recorded.</p>}{!!row?.transitions.length && <><h3>Activity</h3>{row.transitions.map((t,i)=><p key={i}>{t.runner} · {t.status}{t.detail && ` · ${t.detail}`}</p>)}</>}</div>}
+        ]}/>
+        {identity && <p className="dim" role="status">{observed.state === 'observing' ? 'Observing this attempt…' : observed.state === 'terminal' ? 'Observation complete.' : 'Observation stopped; outcome may be unknown. Refresh to observe again.'}</p>}
+    </div>;
+}
+function ApiRecoveryDialog({ id, action, onClose, onBusy, onResult }: {
+    id: string;
+    action: ApiAction;
+    onClose: () => void;
+    onBusy: (v: boolean) => void;
+    onResult: (id: string) => void;
+}) {
+    const me = useMe(), s = useDeploymentOwner(), w = useWrite(s.owner, s.signal, onBusy);
+    const execute = () => w.run(async () => { if (!canRecoverApi(me.data) || !isInteractive())
+        throw new Error('API recovery authority unavailable'); const fresh = await getPlatform(s.owner, s.signal), source = fresh.deployments.data?.items.find(x => x.id === id); if (!source || !apiActions(source.status).includes(action) || fresh.deployments.data?.items[0]?.id !== id)
+        throw new Error('Attempt was replaced or changed. Refresh and review again.'); assertOwner(s.owner, s.signal); const receipt = makeReceipt(s.owner, 'api', `${id}:${action}`, 0, id); const result = await recoverApi(s.owner, receipt, id, action, s.signal); if (action === 'retry' && result.sha !== source.sha)
+        throw new Error('Retry did not preserve source SHA'); settleReceipt(receipt); onResult(result.id); onClose(); });
+    const label = { retry: 'Retry same commit', verify: 'Verify nodes', converge: 'Converge fleet' }[action];
+    return <div className="modal-pad admin-deployments"><h2 className="modal-title">{label} <DeploymentHelp label="API recovery target">Attempt <code>{id}</code>. The latest attempt and authority are checked before sending. A retry preserves its commit and tracks a new attempt.</DeploymentHelp></h2><p className="modal-message">{action === 'retry' ? 'Deploy the same commit as a new attempt.' : action === 'verify' ? 'Refresh runtime proof from the nodes in this attempt.' : 'Apply the current desired serving configuration across the fleet, then verify it.'}</p>{w.error && <ErrorNotice>{w.error}</ErrorNotice>}<div className="modal-actions"><button className="btn" disabled={w.busy} onClick={onClose}>Cancel</button><button className="btn btn-primary" disabled={w.busy} onClick={() => void execute()}>{label}</button></div></div>;
+}

package/src/admin/deployments/DeploymentsPage.tsx

@@ -0,0 +1,73 @@
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useSearchParams } from 'react-router-dom';
+import { registerNonFilterParams, useMe } from '../../client/runtime';
+import { Tabs } from '../../ui/Tabs';
+import { datetime } from '../../ui/format';
+import { modal } from '../../ui/modal';
+import { backendGlobalCan } from '../fleet/access';
+import { useAdminRouteContext } from '../core/route-context';
+import { canOnboard, canReadApi, canReadBootstrap, canReadWebApps, isInteractive, assertOwner } from './permissions';
+import { getBootstrap, getPlatform, getWebApps } from './api';
+import { useDeploymentOwner } from './useDeploymentObservation';
+import { DeploymentHelp, ErrorNotice, Facts, Status } from './shared';
+import type { DeploymentsDestinations } from './types';
+import { platformProof } from './deployment-state';
+registerNonFilterParams('deployment_lane', 'deployment_app', 'deployment_tab');
+export function DeploymentsPage({ destinations }: {
+    destinations?: DeploymentsDestinations;
+} = {}) {
+    const me = useMe(), scope = useDeploymentOwner(), queryClient = useQueryClient(), [params, setParams] = useSearchParams();
+    const registered = useAdminRouteContext();
+    const mount = registered?.mount === '/' ? '' : registered?.mount;
+    const candidates = destinations ?? (mount !== undefined ? { domains: `${mount}/dns/domains`, serving: `${mount}/edge/vhosts` } : {});
+    const admittedDestinations: DeploymentsDestinations = {};
+    if (backendGlobalCan(me.data, ['view_dns', 'manage_dns', 'security'])) for (const key of ['domains', 'serving'] as const) {
+        const path = candidates[key];
+        if (path && (!registered || registered.paths.includes(path))) admittedDestinations[key] = path;
+    }
+    const interactive = isInteractive(), api = interactive && canReadApi(me.data), web = interactive && canReadWebApps(me.data);
+    const lane = params.get('deployment_lane') === 'webapps' && web ? 'webapps' : api ? 'api' : 'webapps';
+    const bootstrap = useQuery({
+        queryKey: ['deployments', scope.key, 'bootstrap'], queryFn: ({ signal }) => getBootstrap(scope.owner, signal), enabled: web && lane === 'webapps' && canReadBootstrap(me.data), retry: false
+    });
+    const select = (lane: string) => { setParams({ ...Object.fromEntries([...params].filter(([name]) => name === 'demo')), deployment_lane: lane }, { replace: true }); };
+    const newApp = async () => { const { WebAppOnboardingDialog } = await import('./WebAppOnboardingDialog'); assertOwner(scope.owner, scope.signal); let busy = false; await modal.open(close => <WebAppOnboardingDialog destinations={admittedDestinations} bootstrap={bootstrap.data!} onChanged={() => { void queryClient.invalidateQueries({ queryKey: ['deployments', scope.key] }); }} onClose={() => close(null)} onBusy={value => { busy = value; }}/>, {
+        signal: scope.signal, canDismiss: () => !busy, size: 'lg'
+    }); await queryClient.invalidateQueries({ queryKey: ['deployments', scope.key] }); };
+    if (!api && !web)
+        return <div className="panel panel-pad"><h1>Deployments</h1><p>API or WebApp read authority in this global Admin workspace is required.</p></div>;
+    const items = [...(api ? [{
+                key: 'api', label: 'API', panel: <ApiLane key={scope.key}/>
+            }] : []), ...(web ? [{
+                key: 'webapps', label: 'WebApps', panel: <WebAppsLane key={scope.key} destinations={admittedDestinations}/>
+            }] : [])];
+    return <div className="admin-deployments"><header className="page-header"><div><h1>Deployments</h1><p className="dim">Review releases and deployment progress.</p></div>{lane === 'webapps' && web && canOnboard(bootstrap.data) && <button className="btn btn-primary" onClick={() => void newApp()}>New WebApp</button>}</header>{items.length === 1 ? items[0]!.panel : <Tabs ariaLabel="Deployment type" items={items} activeKey={lane} onActiveKeyChange={select}/>}</div>;
+}
+function ApiLane() {
+    const me = useMe(), s = useDeploymentOwner();
+    const q = useQuery({
+        queryKey: ['deployments', s.key, 'platform', 'deployments,api'], queryFn: ({ signal }) => getPlatform(s.owner, signal), enabled: canReadApi(me.data) && isInteractive(), retry: false
+    });
+    const inspect = async (id: string) => { const { ApiDeploymentDetail } = await import('./ApiDeploymentDetail'); assertOwner(s.owner, s.signal); await modal.open(close => <ApiDeploymentDetail id={id} onClose={() => close(null)}/>, { signal: s.signal, size: 'lg' }); };
+    const d = q.data?.deployments, serving = d?.data?.currently_serving;
+    const stale = d?.status === 'stale' || !!d?.stale_after && Date.parse(d.stale_after) <= Date.now();
+    return <section><div className="deployment-toolbar"><h2>API</h2><button className="btn" disabled={q.isFetching} onClick={() => void q.refetch()}>Refresh API</button></div>
+        {q.isError && <ErrorNotice>API observation unavailable. {q.data ? 'Previous evidence is shown below.' : 'Refresh to try again.'}</ErrorNotice>}
+        {q.isPending ? <p role="status">Loading API evidence…</p> : !d?.data ? <div className="panel panel-pad"><h3>Deployment observation unavailable</h3><p>{d?.reason || 'The collector did not return deployment evidence. Refresh to try again.'}</p><Status value={d?.status ?? 'unknown'}/></div> : <>
+            {stale && <p className="text-warn" role="status">This deployment observation is stale. Refresh before acting.</p>}
+            <div className="deployment-current"><div className="deployment-toolbar"><div className="eyebrow">Last convergence</div><DeploymentHelp label="API convergence"><Facts rows={[["Collector", <Status value={d.status}/>], ["Observed", d.observed_at ? datetime(d.observed_at) : 'Time unavailable'], ['Framework', serving?.framework_version], ['Framework mode', d.data.framework_pin.mode], ['Coordination', d.data.coordination.state]]}/><p>Last convergence is dated evidence, not fresh proof for every current node. Framework changes belong to Maintenance.</p></DeploymentHelp></div><strong className="mono" title={serving?.sha}>{serving?.sha.slice(0, 12) ?? 'No convergence recorded'}</strong><p className="dim">{serving?.converged_at ? datetime(serving.converged_at) : 'Convergence time unknown'}</p></div>
+            <h3>Latest attempts</h3>{d.data.items.map((row, i) => <button className="deployment-record" key={row.id} onClick={() => void inspect(row.id)}><span><strong>{i === 0 ? 'Latest · ' : ''}{row.sha.slice(0, 12)}</strong><small>{platformProof(row)}</small></span><Status value={row.status}/></button>)}{!d.data.items.length && <p>No deployment attempts recorded.</p>}
+            {d.data.items.length >= d.data.limit && d.data.limit > 0 && <p className="dim">Showing the latest {d.data.limit} attempts.</p>}
+        </>}
+    </section>;
+}
+function WebAppsLane({ destinations }: {
+    destinations?: DeploymentsDestinations;
+}) {
+    const me = useMe(), s = useDeploymentOwner();
+    const q = useQuery({
+        queryKey: ['deployments', s.key, 'summaries'], queryFn: ({ signal }) => getWebApps(s.owner, signal), enabled: canReadWebApps(me.data) && isInteractive(), retry: false
+    });
+    const inspect = async (id: number) => { const { WebAppDetail } = await import('./WebAppDetail'); assertOwner(s.owner, s.signal); await modal.open(close => <WebAppDetail id={id} destinations={destinations} onClose={() => close(null)}/>, { signal: s.signal, size: 'lg' }); };
+    return <section><div className="deployment-toolbar"><h2>WebApps</h2><button className="btn" disabled={q.isFetching} onClick={() => void q.refetch()}>Refresh WebApps</button></div>{q.isError ? <ErrorNotice>WebApp summary unavailable. Refresh to try again.</ErrorNotice> : q.isPending ? <p>Loading WebApps…</p> : <>{q.data?.truncated && <p className="text-warn">More apps exist; this list is truncated.</p>}{q.data?.items.map(row => <button className="deployment-record" key={row.webapp.id} onClick={() => void inspect(row.webapp.id)}><span><strong>{row.webapp.display_name || row.webapp.slug}</strong><small>{row.address?.hostname || 'No public address'}</small><small>Desired version: {row.current_release?.version ?? 'No release'}</small></span><span className="deployment-attempt-summary"><small>Latest attempt{row.latest_deployment?.release?.version && row.latest_deployment.release.version !== row.current_release?.version ? ` · ${row.latest_deployment.release.version}` : ''}</small><Status value={row.latest_deployment?.status ?? 'not started'}/></span></button>)}{!q.data?.items.length && <p>No WebApps yet.</p>}</>}</section>;
+}