portal-mojo 0.2.3 → 0.2.5

package/README.md

@@ -67,6 +67,9 @@ are identical in both forms.
   (`panel`, `chip`, `tbl`, …) styled by the app's `theme.css` under
   `data-theme="light"` **and** `"dark"` (reference set:
   `apps/portal/src/theme.css`).
+  This includes the `.guardrail*` rules behind `confirmGuardrail`
+  (reference: `apps/portal/src/theme/guardrail.css`) — the package ships no
+  CSS, so an app that opens a guardrail must carry that block.
 - **Tailwind scan of this package.** In an installed app's CSS:
   `@source "../node_modules/portal-mojo/src";` (adjust the relative path from
   that CSS file). Utility classes used in package components are generated by

package/docs/ModelTable.md

@@ -110,6 +110,32 @@ passed to every run — e.g. collect ONE disable reason) →
 / `"N succeeded, M failed"` (warning) / `"failed for all N"` → always
 clear selection + invalidate.
 
+`confirm` is the permission step and takes three forms:
+
+| `confirm` | Behaviour |
+|---|---|
+| `string` (default `"<label> N item(s)?"`) | `modal.confirm` with that copy; `danger` styles the button. |
+| `false` | No prompt. |
+| `(rows) => Promise<boolean>` | **Replaces** the built-in confirm — resolve `false` to cancel. `prepare` still runs after it. Open a `confirmGuardrail` here for a batch that takes a tenant dark or can't be undone. |
+
+Ask permission in `confirm`, collect input in `prepare` — don't fold a
+guardrail into `prepare` and return `null` to cancel; that conflates
+"nothing collected" with "declined".
+
+```tsx
+{
+    key: 'revoke', label: 'Remove access', danger: true,
+    confirm: (rows) => confirmGuardrail({
+        title: `Remove access for ${rows.length} members?`,
+        effect: <>They lose all access the moment each call lands.</>,
+        why: [<>Accounts stay; grants go — re-inviting restores a fresh preset, not the old unlocks.</>],
+        confirmText: `Remove ${rows.length}`,
+        typeToConfirm: rows.length >= 5 ? String(rows.length) : undefined,
+    }),
+    run: (row) => revoke(row),
+}
+```
+
 `runBatch` executes exactly once for selection-wide operations such as incident
 merge. A rejection produces one actionable error; cancellation mutates
 nothing. Selection clears and the endpoint invalidates after a non-cancelled

package/docs/README.md

@@ -19,12 +19,14 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [admin-monitoring.md](admin-monitoring.md) | Monitoring Admin registration, logs, and exact Redis-backed metrics-permission mutations |
 | [admin-metrics-explorer.md](admin-metrics-explorer.md) | Read-only recorded-metrics discovery, full-slug adapters, KPI/fan-out/scalar contracts, and cache identity |
 | [admin-settings.md](admin-settings.md) | Runtime settings admin — direction-aware atomic writes, write-only secrets, and global/group scope |
+| [admin-fleet-configuration.md](admin-fleet-configuration.md) | Superuser structured configuration publishing, version restore and per-node application evidence |
 | [admin-bouncer.md](admin-bouncer.md) | Bouncer decisions, device investigations, and bot-signature administration with token-safe caching |
 | [admin-security-tickets.md](admin-security-tickets.md) | Ticket queue, KISS detail modal, notes, approvals, and Maestro sync contract |
 | [admin-incidents.md](admin-incidents.md) | Incident/event triage, forensic detail, merge semantics, and sanitized export boundary |
 | [admin-rules.md](admin-rules.md) | Always-inactive RuleSet authoring and the lossless, runtime-effective handler-chain builder |
 | [admin-members.md](admin-members.md) | Global membership table/detail, no-oracle admission, extensible grants, Group-detail composition, and unsupported-operation boundaries |
 | [admin-identity-users.md](admin-identity-users.md) | Global Users table and 14-section detail, system gates, action contracts, and one-time credential invariants |
+| [admin-signin.md](admin-signin.md) | System sign-in page look & feel plus Google/Apple/GitHub provider credentials — one endpoint, changed-paths saves, write-only secrets |
 | [admin-devices-geoip.md](admin-devices-geoip.md) | Fleet device triage, the login-location world map with country drill-down, and the GeoIP dossier — expiry-aware enforcement, the never-cached raw provider record, and the backend traps the port encodes |
 | [admin-jobs.md](admin-jobs.md) | Jobs engine — runner fleet, per-channel queue depth, the segmented job table with armed cancel and republishing retry, the dry-run-first control plane, scheduled tasks with a global-only gate, and the thirteen backend corrections the port encodes |
 | [admin-network-security.md](admin-network-security.md) | Perimeter control — blocked IPs, the firewall log, kernel IP sets and the geofencing page (posture, rules, simulator, evidence, exemptions), with the DSL projection and every backend correction the port encodes |
@@ -43,7 +45,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [tabs-and-form-wizard.md](tabs-and-form-wizard.md) | Accessible Tabs variants and shared-state FormWizard, async finish, reset/roster semantics, modal helper |
 | [admin-modals.md](admin-modals.md) | Admin modal inventory, presentation, resource lifecycle and retained exception policy |
 | [DetailView.md](DetailView.md) | The UserView-style detail surface + row/section primitives |
-| [feedback.md](feedback.md) | Awaitable `modal.*`, `toast.*` |
+| [feedback.md](feedback.md) | Awaitable `modal.*`, `toast.*`, `confirmGuardrail` (the are-you-sure-and-here-is-why stop) |
 | [idioms.md](idioms.md) | ArmedButton (two-step confirm), `undoToast` (grace-period undo), `progressToast` — the dangerous-action trio |
 | [file-upload-ux.md](file-upload-ux.md) | Pure file validation, accessible picker/drop controls, bounded component-local upload queues, recovery, and completion callbacks |
 | [image-editor.md](image-editor.md) | Full-resolution crop/transform/filter composition, bounded history, PNG Blob results, modal helper, and ImageField pre-upload editing |

package/docs/admin-fleet-configuration.md

@@ -0,0 +1,50 @@
+# Fleet Configuration
+
+The Operations → Fleet Configuration page uses `/api/account/admin/fleet`.
+Only literal superusers see the section. An empty permission any-of array uses
+the existing superuser bypass and refuses even the global `admin` grant; the
+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
+and Remove published override are explicit actions. Clearing falls back to base
+configuration/default; it does not promise erasure of a bootstrap secret.
+
+Secret inputs start blank, never hold masked placeholders, and blank replacement
+preserves the existing secret. Values stay in the form until an imperative POST;
+secret-bearing writes bypass TanStack MutationCache. Secret current/default fields
+are removed before Query cache storage. The revision-bound publish/restore/apply
+POSTs use `withFreshAuth` and show failures without claiming success. Schema/type
+validation is repeated by the server; browser validation is only feedback.
+
+Publication means published to S3, never applied. Apply now starts a fixed
+asynchronous sync operation and polls its ID until terminal operation status. The
+short job completes after dispatching sync; completed job status does not stop
+polling. Each operation read freshly observes activation until healthy or timed
+out; failed, expired or canceled jobs also stop polling. The expected
+node roster includes missing nodes. Installed, restart requested, restarted and
+healthy remain separate evidence. Only positive installed + restarted + health
+results from every expected node with the explicit
+`request_service_jobs_and_dependencies` health scope justify fleet completion.
+Missing or older health scopes remain unconfirmed, including per-node health and
+restart confirmation, and prompt a backend upgrade. Health covers the
+request service and dependencies where enabled, plus the job engine and scheduler
+with their startup-loaded revision. Worker-only nodes need no request service.
+Draining an old engine is not proof that its replacement has loaded the revision.
+Timed-out, failed, superseded and unknown results stay visible. Refresh status observes the
+normal timer workflow even when Apply now was not used.
+
+History contains only version IDs and timestamps. Restore publishes the selected
+version as a new revision using the current expected revision. Secrets are neither
+shown nor compared. Concurrent publication rejects the stale revision; refresh
+before retrying. Settings edits are tied to their loaded publication revision.
+
+Verify with `npm run verify:admin-fleet`, `npm run typecheck`, `npm run build`, and
+browser checks of both themes. The Settings showcase includes a partial-convergence
+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.

package/docs/admin-phonehub.md

@@ -12,6 +12,16 @@ Import `PhoneHubPage`, the three individual pages, models, permission clauses, a
 - A successful HTTP envelope can contain a `failed` or `undelivered` SMS record: render that status as failure. Other returned statuses remain literal; only `delivered` confirms delivery. The default graph does not expose `is_test`, so a `sent` receipt does not claim a real delivery. Transport/malformed-receipt failures retain the draft and ask the operator to check SMS Audit before retrying. Every attempted send invalidates the audit list; refresh failure cannot turn a completed send into a retry. Provider refusal is demonstrated in the mock with a recipient ending in `0000`; no mock request contacts a provider.
 - `PhoneConfigModel` reads sanitized scalar/default-graph rows. Saves and `test_connection` use imperative, cache-free calls. The editor follows web-mojo's provider-conditional layout: selecting Twilio, AWS SNS, or Mojo Remote shows and submits only that provider's connection fields. Mojo Remote uses `https://api.mojoverify.com` when the saved URL is unset or the editor is switched to Mojo; an explicitly configured custom URL is preserved. Secret inputs are DOM refs, not React or Query state: blank means untouched and is omitted; replacement must be non-empty; clear sends `null` only after a separate confirmation. Switching providers resets pending clears, and hidden provider credentials remain untouched. Responses are allowlisted before cache reconciliation. This surface edits existing provider credentials; it does not provision Django user/group API keys.
 
+Connection tests read the provider's `success` verdict, not the outer REST
+`status`. A failed or missing verdict is an error; `test_mode` is a warning
+that the provider was not contacted. Results persist inside the detail modal
+on both sections, alongside a toast. Scope is labeled in the header and
+Connection section. Editing is disabled while a connection test is pending, so an old response
+cannot certify replacement credentials. Saving clears the previous test result.
+The stored URL is shown literally; a saved URL plus `missing_credentials` for
+Mojo means the API key is absent. Re-enter it in Edit configuration and save;
+blank password inputs preserve existing values and do not prove a key exists.
+
 ## Exact permissions
 
 Every exported array is an ANY-of clause and retains the `sys.` UI namespace. Number view is `view_phone_numbers | manage_phone_numbers | comms | manage_users`; save is `manage_phone_numbers | comms | manage_users`; delete is only `manage_phone_numbers`. SMS view is `view_sms | manage_sms | comms | owner | manage_notifications`; save is `manage_sms | comms | manage_notifications`; delete is `manage_sms | manage_notifications`. Config view/save is `manage_phone_config | manage_groups | comms`; delete is `manage_phone_config | manage_groups`. These delete clauses describe low-level API compatibility; built-in number,
@@ -24,7 +34,7 @@ Group choices are fetched only with a separate global group-directory clause and
 
 ## Provider and deletion reality
 
-Phone lookup is always the global Twilio Lookup integration; it is not group-configured. Stored Twilio and AWS credentials can be tested, but the current SMS send implementation only consults a per-group configuration for `provider="mojo"`. Twilio/AWS configurations otherwise fall through to global Twilio send settings, and AWS sending is not wired. `test_mode` only short-circuits connection testing; it does not block sending.
+Phone lookup uses the global Twilio Lookup integration. Mojo SMS delivery uses the selected PhoneConfig’s saved remote URL and encrypted API key. Twilio SMS delivery uses a complete saved credential pair from the selected config, rejects a partial pair, and falls back to global settings only when neither credential is stored. Its sender uses the config’s from number when set, otherwise the global default. AWS credentials can be stored and tested, but AWS delivery is not wired. `test_mode` only short-circuits connection testing; it does not block sending.
 
 An active group config wins; otherwise `PhoneConfig.get_for_group` falls back to the first active system default. Deactivating a group config restores that fallback; Admin exposes this reversible lifecycle. Deleting a group cascades its config and SMS rows. Deleting a user cascades their SMS rows. Deleting a config does not delete SMS audit rows. Deleting an SMS row affects only local audit storage and cannot recall provider delivery.
 

package/docs/admin-push.md

@@ -6,38 +6,117 @@ Import `PushPage`, its individual panels/pages, the canonical push models, API h
 
 The page has six possible tabs: Your stats, Global metrics, Devices, Deliveries, Templates, and Config. Stats are authenticated caller data. Every other tab is independently filtered by its exact permission clause, and only the active authorized panel mounts, so hidden/inactive surfaces issue no requests.
 
-`push_surface` is registered with `registerNonFilterParams` at module load. It survives table writes but never becomes a Django lookup or filter pill. Changing tabs replaces the flat URL params with only `push_surface`, intentionally clearing search, sort, paging, and filters that belong to the prior model.
+`push_surface` is registered with `registerNonFilterParams` at module load. It survives table writes but never becomes a Django lookup or filter pill. Changing tabs retains only `push_surface` and the showcase host's `demo` selector, clearing search, sort, paging, and filters belonging to the prior model. Showcase registers `demo` as a non-filter param at boot, so table writes keep the selected demo without sending it as a model lookup.
 
 ## Exact permissions
 
-All UI clauses carry the `sys.` namespace and are ANY-of:
+All UI clauses carry the `sys.` namespace. Alternatives within a clause are ANY-of:
 
 - Devices view: `view_devices | manage_devices | comms | owner | manage_users`; save: `manage_devices | comms | owner`.
 - Deliveries view: `view_notifications | manage_notifications | comms | owner | manage_users`; save: `manage_notifications | comms`.
 - Templates view: `manage_notifications | manage_groups | comms | owner | manage_users`; save: `manage_notifications | manage_groups | comms`.
 - Config view/save: `manage_push_config | manage_groups | comms`.
 - Config connection test: `manage_push_config | comms`.
+- Device test: `send_notifications | comms` **AND** the Devices view clause above.
 - Global metrics: `view_metrics | metrics`, with `account="global"`.
 
 `sys.users` is deliberately absent: it is not in `RegisteredDevice.RestMeta.VIEW_PERMS`. The Stats endpoint requires authentication only and always scopes all five keys to `request.user`.
 
+Device inspection or config management alone never enables a test send. The backend separately enforces global `send_notifications | comms` and visibility of the selected registration; invisible and missing devices both return 404. Config checks require global `manage_push_config | comms`, independently of config editing. Group/member grants, API keys, and key-backed sessions cannot satisfy these test-action gates.
+
 ## Projection and ownership boundaries
 
 Every model pins a `basic` or `default` graph, allowlists list params, and positively projects rows before Query or Mutation cache reconciliation. RegisteredDevice never retains `device_token`; Delivery never retains `platform_data`, and its arbitrary `data_payload` is not retained by the UI projection. Related users are reduced to id plus a short display label—never email, phone, metadata, or an expanded user graph. Template JSON objects accept only a bounded shallow scalar projection on reads.
 
+The additional evidence retained by the UI is:
+
+| Model / result | Retained fields and fallback |
+|---|---|
+| `PushDeviceRow` | `is_active` is boolean or null; an older backend with no field shows “Activity unknown”. |
+| `PushConfigRow` | `fcm_project_id` (max 200 characters), `fcm_client_email` (max 254), and boolean/null `has_fcm_credentials`. Missing metadata is “Not reported” / “Presence not reported”; credential presence is not verification. |
+| `PushDeliveryRow` | `push_outcome` allowlists `accepted`, `delivered`, `simulated`, `rejected`, `blocked`, `unknown`, `pending`, `sent`, and `failed`; otherwise null, with display falling back to stored `status`. |
+| `PushTestConfig` | Positive safe-integer `id`, `name` (max 100), `group` (safe-integer id/name up to 120 characters, or explicit null for system default), `fcm_project_id` (max 200), `test_mode`, `is_active`, `has_fcm_credentials`. No service-account email or secret material. |
+| `PushTestResult` | `success`, `outcome`, local `message`, allowlisted/null `error_code`, success-only `message_id` (max 500), positive safe-integer/null `delivery_id` and `device_id`, and projected/null `config`. |
+
+Test results live in the open dialog, outside Query and Mutation caches. Provider messages and raw error bodies are replaced by local copy; unknown error codes are discarded. `PushReadiness` retains only `ready`, local `message`, `device_id`, and projected `config`.
+
 `PushDeviceModel` now lives canonically in `admin/messaging/push`. The former `admin/identity/users/models.ts` definition is a compatibility re-export of the same object, so User Detail and the global Push page share one endpoint definition and Query key.
 
 ## FCM credentials and actions
 
 FCM writes are imperative and cache-free. A service account textarea is an uncontrolled DOM ref and never prefills. Blank means untouched and is omitted. Replacement must parse to an object with `type="service_account"`, `project_id`, `client_email`, and a PEM `private_key`. Clear sends `null` only after explicit confirmation. Empty replacement is impossible, and server responses are sanitized before cache reconciliation.
 
-Connection testing calls only `POST /api/account/devices/push/config/<id>/test` with an empty body. The backend uses its dummy token to validate credentials. The portal never accepts a device token. It also does not expose `/send`, caller `/test`, delivery retry, device registration/unregistration, or any delete action.
+### Saved configuration check
+
+`testPushConfigConnection(id)` calls `POST /api/account/devices/push/config/<id>/test` with `{}`. The backend authenticates with FCM and submits a validation-only message, including when `test_mode=true` or the selected config is inactive. It sends no device notification and does not activate the config. The portal never accepts a raw device token.
+
+The adapter accepts success only when the envelope has not failed, `success === true`, `outcome === "validated"`, `validation_only === true`, and `message_id` matches `projects/<project>/messages/<reference>`. Missing/malformed verdicts, simulated legacy responses, and provider rejections cannot display a verified connection. Backend HTTP 400 failures retain safe diagnostic data; the adapter returns a failed `PushTestResult` for the dialog to display.
+
+“Check FCM connection” lives in the config header menu. The result and check time remain visible in Overview and Connection for that saved record/revision. Checks lock duplicate checks, editing, and active-state changes while pending. Editing or changing active state clears the result; record revision, permission, caller, or mount changes invalidate late completions. This is evidence from the current view, not a persisted credential-verification flag.
+
+### One registered device
+
+The device header's “Send test push” opens a focused dialog. The API helpers use the existing test endpoint:
+
+| Helper | Request | Purpose |
+|---|---|---|
+| `fetchPushDeviceReadiness(42)` | `GET /api/account/devices/push/test?device_id=42` | Local readiness; no FCM traffic. |
+| `sendPushDeviceTest(42, title, message)` | `POST /api/account/devices/push/test` with `{"device_id":42,"title":"Push test","message":"This is a test notification."}` | One real notification to the selected registration. |
+
+`device_id` here is the numeric database `id`, not the app-provided string `device_id` used for registration. The portal never calls the caller-wide POST variant without a selector. The backend resolves the device owner's active org config, falling back to the active system default; the dialog shows the device, user, config ID/name, scope, and FCM project actually reported by readiness or the send result.
+
+Readiness must explicitly match the requested device and include an active config with credentials present and simulation disabled. Inactive registration, push disabled, an opted-out `test` category, missing token/config/credentials, or simulation prevents sending. Readiness does not verify provider credentials or device reachability. Unknown/malformed readiness disables Send rather than guessing.
+
+The dialog defaults to title `Push test` and message `This is a test notification.`; inputs must be nonblank and fit 200/1000 characters. A single pending guard prevents duplicate submissions and locks fields, Cancel, Escape, and backdrop dismissal during sending. Each dialog permits one completed attempt; reopen it to obtain fresh readiness before another. Permission loss hides stale results; settled requests still unlock dismissal. Every attempt invalidates device, delivery, and caller-stat queries in `finally`.
+
+Device results require explicit `success === true`, `outcome === "accepted"`, a provider message reference, and the requested `device_id`. Handled backend failures may be HTTP 200 with `data.success=false`; inspect the projected result. A failed envelope cannot establish success. Uncertain transport/malformed responses become `unknown`, and known HTTP 400/401/403/404 refusals without structured evidence become blocked. There is no automatic resend.
+
+The portal exposes no general `/send`, caller-wide test, delivery retry, device registration/unregistration, or delete action.
+
+All four REST models have live `CAN_DELETE = false`; the mock returns 403 without removing or cascading anything. Templates/configs can be created and edited under their save clauses. Device record editing and delivery mutation remain absent from this page.
+
+## Outcomes and delivery evidence
+
+Test dialogs keep a visible result label, local explanation, check time, and delivery record ID when available:
+
+| Outcome | Meaning |
+|---|---|
+| `validated` | FCM connection verified; no notification delivered. |
+| `accepted` | FCM accepted the notification; the operator must check the selected device for receipt. |
+| `rejected` | FCM refused the request; show the safe diagnostic. |
+| `blocked` | Readiness, credentials, authentication, or request refusal prevented a successful test. |
+| `unknown` | Acceptance is uncertain. Check the device and delivery history before another test; do not label it failed or retry automatically. |
 
-All four REST models have live `CAN_DELETE = false`; the mock returns 403 without removing or cascading anything. Templates/configs can be created and edited under their save clauses. Devices and deliveries remain investigative here.
+Delivery lists/details prefer `push_outcome` over `status`. `simulated` is explicitly shown as no FCM send, even though the stored status is `sent`. `unknown` remains pending; provider acceptance alone does not mark a record delivered. Older `sent` records are described as lacking acceptance/receipt evidence. Status filtering and sorting still use the stored status field, not the derived outcome. The caller-stat tile is “Recorded sent” because its count may include simulations.
 
 ## Modal lifecycle convention
 
 See [Admin modal policy](admin-modals.md) for header actions, content-only
 sections, supported lifecycle fields and retained irreversible exceptions.
-Config/template active-state controls live in the detail header. Config saves
-retain write-only credential handling, and test sends keep their separate gate.
+Config/template active-state controls live in the detail header. Device details
+use Overview/Preferences with active and push-state chips; delivery details use
+Notification/Delivery with outcome explanations. Templates use
+Overview/Notification/Variables; configs use Overview/Connection with scope,
+send-mode, credential-presence, and service-account metadata.
+
+Config/template editors keep one pending save guard and protect Escape/backdrop
+dismissal as well as Cancel. Config saves retain write-only credential handling;
+device test sends use their separate permission AND and dismissal lock.
+
+## Showcase and verification
+
+Open `#/?demo=admin-push` in Showcase. Its banner explicitly identifies
+local fixtures: connection checks and test pushes there never contact FCM or
+deliver notifications. Fixtures exercise system/org config selection, disabled
+push, simulation blockers, safe metadata, and a selected-device accepted result
+with a delivery row and no delivered timestamp. Switching Push tabs preserves
+`demo=admin-push`; model filtering never consumes that host selector.
+
+`npm run verify:admin-push` runs both `scripts/verify-admin-push.mjs` (mock wire,
+permissions, projections, credentials, and target selection) and
+`scripts/verify-push-tests.mjs` (mounted dialog/adapters). The latter covers strict
+provider verdicts, malformed/mismatched responses, revision/permission ownership,
+persistent results, duplicate-send prevention, pending dismissal, and cache
+isolation. JSDOM assertions do not prove native dialog layout or stacking;
+complete browser verification in both themes and a narrow viewport, including
+the device test, configuration check, and nested editors.

package/docs/admin-settings.md

@@ -33,6 +33,16 @@ queries `/api/group`, and preserves that scope on save. New settings default to
 Global. Delete is intentionally absent because live `Setting.RestMeta` does not
 declare deletion.
 
+## Viewing values
+
+JSON objects and arrays show a compact type/count summary in the list. Long or
+multiline text shows a single-line preview, capped at 80 characters. Select the
+row to open the full value in the existing detail
+modal. JSON uses the shared `JsonBlock` viewer, expanded initially, with syntax
+highlighting, Show/Hide, Copy, and a scrollable body. Other text preserves line
+breaks in a scrollable area; invalid JSON remains plain text. Secret values stay
+masked in both views.
+
 ## Atomic write contract
 
 Use `saveSettingAtomic()` / `buildSettingPayload()` rather than a generic

package/docs/admin-signin.md

@@ -0,0 +1,73 @@
+# Sign-in admin (#5547)
+
+Import `SigninPage`, `SIGNIN_ADMIN_SECTION`, the permission clause and the API
+helpers from `portal-mojo/admin` (or `portal-mojo/admin/identity`). The section
+registers one global route, `/system/sign-in`, under **Identity & Access**,
+gated by `SIGNIN_ADMIN_PERMISSIONS` = `['sys.manage_settings', 'sys.admin']`
+(superusers pass). Admin global scope masks any outer product group.
+
+The page has two parts:
+
+- **Look & feel** — the SYSTEM hosted login/registration page: branding,
+  layout/appearance/accent color, hero panel, sign-in heading/copy/methods,
+  registration, custom CSS. It edits the same keys a group admin edits in the
+  group **Configure Auth** dialog; a group's own settings still override these.
+- **Providers** — one card each for Google, Apple and GitHub: an Enabled
+  switch, a read-only callback URL with a Copy button, the credential fields,
+  a Ready / Needs setup badge, and a link to the provider's console.
+
+KISS by design: trusted admins, no step-up auth, no confirmation beyond a
+browser `confirm()` before clearing a stored value.
+
+## Wire contract
+
+One endpoint, both methods, django-mojo envelope.
+
+`GET /api/account/admin/signin` → `{schema_version, auth, editable, options, providers}`
+
+- `auth` is `public_auth_config` of the resolved system config
+  (`{theme, login, registration}`).
+- `editable` lists the flat dotted paths the POST accepts. The page renders
+  only fields whose path is listed, so the backend can narrow it.
+- `options` carries the allowed tokens for methods, layouts, appearances,
+  hero image positions and passkey prompts. Legacy layouts `card` /
+  `fullscreen` display as `compact` / `branded-panel`; any other unknown select
+  value falls back to the first option with a `console.warn`.
+- `providers[]`: `{name, label, enabled, ready, missing, callback_url,
+  console_url, help, fields[]}`; each field is `{key, label, secret,
+  multiline, configured, source, value, hint}`. `source` is `admin`,
+  `deployment` (shown as "Set in server config") or `none`. Secret fields
+  never carry `value`; `hint` (e.g. `…a1b2`) is shown when present.
+
+`POST /api/account/admin/signin` returns the same full payload, which the page
+writes straight into its query cache (`SIGNIN_QUERY_KEY`).
+
+- Look & feel: `{auth: {"theme.app_title": "…", "login.methods": […]}}` —
+  only the paths whose value differs from the loaded payload, sent by the
+  explicit **Save** button. Password is locked on in the sign-in methods picker;
+  the server rejects a list without it (400).
+- Provider: `{provider, values, enabled}`. In `values`, an omitted key or
+  `""` keeps the stored value and `null` clears it. The card's **Save** sends
+  only fields the admin typed into; **Clear…** (shown for `source: "admin"`)
+  confirms, then sends `null` at once. The **Enabled** switch saves
+  immediately with `{provider, enabled}`, which adds/removes the provider from
+  both `login.methods` and `registration.methods`.
+- Errors are `{status: false, error}` (HTTP 400). The client rejects them; the
+  page shows the message inline and as a toast and keeps the unsaved edits.
+
+Secrets are entered in password inputs (the Apple `.p8` key in a textarea)
+and cleared from local state after a successful save.
+
+## Mock
+
+`src/client/mock.ts` implements the endpoint: global `manage_settings` /
+`admin` gate (401 anonymous, 403 otherwise), `editable`-only writes with the
+option and password rules, and credential storage. Seed: Apple has Team ID and
+Services ID stored in the Admin (missing Key ID and private key), Google has
+nothing, GitHub is configured by the deployment. Saved look & feel lands in a
+system override that `/api/auth/config` layers between the deployment config
+and group overrides, so the public config reflects saves. An Admin-stored
+credential wins over the deployment value; clearing it falls back to the
+deployment value.
+
+Verify with `npm run verify:admin-signin`.

package/docs/detail-primitives.md

@@ -109,6 +109,7 @@ value. They coexist happily — `<DataView data={record} />` for the record,
 <MetadataSection
     endpoint="/api/user" id={user.id} metadata={user.metadata}
     onSaved={(next) => qc.setQueryData<User>(['/api/user', 'one', user.id], (p) => p && { ...p, metadata: next })}
+    beforeSave={async (next, prev) => …}   // optional owner gate — see below
 />
 ```
 
@@ -133,7 +134,17 @@ Invariants:
    Object values then display **read-only** — a string editor round-trips
    them lossily; remove and re-add to change one.
 
-Deletion confirms through `modal.confirm`; success toasts.
+**Removing a top-level key stops on a guardrail** (`confirmGuardrail`), not a
+plain confirm: the POST carries the whole blob, so one write can wipe
+`auth_config` / `geofence` / `redemption_policy`. The stop names every key
+about to leave and how many remain; removing more than one key at once asks
+the operator to type the count. `commit()` computes the removed set from
+`metadata` vs `next` — every write path, not just the trash button, hits it.
+
+`beforeSave(next, prev)` runs after that built-in stop and before the POST.
+Resolve `false` to cancel — nothing posts, no error, the editor keeps its
+draft. Owners diff their own protected keys here (a `changedKeys`-style
+compare on the values of `auth_config`, say). Success toasts.
 
 ## StackTraceView — JS **and** Python tracebacks
 

package/docs/feedback.md

@@ -1,7 +1,7 @@
 # feedback — awaitable modals + toasts
 
 ```ts
-import { modal, formModal, toast, ModalHost, ToastHost } from 'portal-mojo/ui';
+import { modal, formModal, toast, confirmGuardrail, ModalHost, ToastHost } from 'portal-mojo/ui';
 ```
 
 Mount `<ModalHost />` and `<ToastHost />` once in the app shell. Modals are
@@ -24,6 +24,51 @@ Patterns:
   input; resolve null to cancel the whole thing.
 - Stacked dialogs are fine (disable-reason form over a detail modal).
 
+## confirmGuardrail — the "are you sure, and here is why" stop
+
+```tsx
+if (!(await confirmGuardrail({
+    title: 'Disable webhook to hooks.example.com?',        // question form, names the target
+    effect: <>Deliveries of <b>order.paid</b> stop the moment this saves.</>,
+    why: [                                                  // one concrete consequence per bullet
+        <>Nothing re-registers them — it stays off until someone turns it back on.</>,
+        <>Consumers see silence, not an error.</>,
+    ],
+    undo: 'Re-enable it here to resume deliveries.',        // or say that you can't
+    confirmText: 'Disable webhook',
+    typeToConfirm: 'DISABLE',                               // optional: button disabled until typed
+    danger: true,                                           // default; false = primary button + warn tint
+}))) return;
+```
+
+Resolves `true` only on the armed confirm button — `false` on Escape,
+backdrop and Cancel. Opens on `modal.open(…, { size: 'sm' })`, so it stacks
+over a `formModal` that is still open. `typeToConfirm` compares trimmed and
+case-insensitively; Enter in that input confirms once it matches.
+
+**Which stop.** Three idioms, one rule each:
+
+| Idiom | When |
+|---|---|
+| `modal.confirm` | Reversible / low blast radius: a yes-no is enough. |
+| `ArmedButton` | Irreversible, needs no input, inline (row actions) — see idioms.md. |
+| `confirmGuardrail` | Anything that **takes a tenant dark, moves money, or can't be undone** — the operator must read *why* before the button arms. |
+
+Copy is written from what the backend does, not adjectives: "every
+integration holding this key gets 401 on its next call", not "this is
+dangerous". Where it is wired in the package: API-key deactivate, webhook
+disable, member `manage_group` / `manage_members` grants (through
+`FormView.beforeSave`), and MetadataSection's removed-key stop.
+
+`changedKeys(initial, next, watch)` is the diff helper for config-form saves:
+which of the watched keys changed (null/'' normalised), so a save confirms
+ONLY the fields that break things and passes silently otherwise.
+
+Styles: `apps/portal/src/theme/guardrail.css` (`.guardrail`,
+`.guardrail-effect/-why/-why-head/-undo/-type`, `.guardrail-icon`) over
+`--bad/--bad-soft` (danger) and `--warn/--warn-soft` (`danger: false`). The
+package ships no CSS — a consuming app carries that block (README).
+
 ## modal.drawer
 
 ```ts
@@ -79,6 +124,20 @@ bottom-right cards, max 5, 3.5s. Conventions:
 - `response: 'payload'` actions toast the SERVER's payload message
   (`outcome.body.message`), not client copy.
 
+`ToastHost` uses a manual native popover above dialog backdrops. Its stable
+portal target follows the most recently opened modal (including nested dialogs
+and drawers), then returns to the page when the last modal closes. Modal-local
+ancestry keeps Undo and progress Cancel usable despite native dialog inertness.
+Moving the host preserves card state and timers and does not focus the toast.
+Mount it once; do not add per-dialog toast hosts or solve this with `z-index`.
+Custom app themes must include the updated toast CSS from
+`apps/portal/src/theme.css`: reset the popover's UA inset/margin/border/padding
+and background, hide closed popovers, and keep only the cards pointer-active.
+Updating the TypeScript package alone does not update a consumer's own theme.
+The showcase's **Toasts inside modal** demo covers errors, Undo, progress,
+and nested opening/closing. `node scripts/verify-toast-modal.mjs` checks the
+mounted lifecycle; native visibility and interaction require browser checks.
+
 ## Pitfall
 
 An open `<dialog>` pauses ModelTable's autoRefresh by design — don't build

package/docs/forms.md

@@ -105,10 +105,51 @@ if (!data) return;   // cancelled → null
     savedFlashMs={1500}        // saved-check duration (default 1500)
     onSaved={({ changes, fields, row }) => …}
     onSaveError={({ changes, fields, error }) => …}
+    beforeSave={({ changes, names, row }) => …}   // once per batch, BEFORE the POST (below)
     onPendingChange={(uploading) => setDetailDismissLocked(uploading)}
 />
 ```
 
+### `beforeSave` — the pre-save gate
+
+```tsx
+beforeSave={({ changes, names, row }) => {
+    // changes: the wire body (dotted names expanded: {permissions: {manage_group: true}})
+    // names:   the flat field names in the batch ('permissions.manage_group')
+    const perms = changes.permissions as Record<string, unknown> | undefined;
+    if (perms?.manage_group !== true) return true;            // proceed
+    return confirmGuardrail({ title: `Grant Manage Group to ${row.email}?`, … }); // false → drop
+}}
+```
+
+Runs once per batch with the body about to POST. Three results:
+
+| Return | Effect |
+|---|---|
+| `false` | **Drop the batch.** Its fields revert to the server snapshot and go idle — no error, no toast. A guardrail the operator declined is not a failure. |
+| an object | **Replace the body.** The object POSTs instead of `changes` (`onSaved.changes` reports what was sent). |
+| `true` / `undefined` | Proceed unchanged. |
+
+While it awaits, the batch is **in flight**: the 300ms window cannot re-fire
+and a commit made meanwhile joins the **next** batch (which gets its own
+`beforeSave`). A `false` reverts only the names this batch carried — a field
+re-committed during the await keeps its new value for the next batch. A hook
+that throws or rejects is a bug, not a veto: it surfaces exactly like a
+failed save (revert + pinned error + `onSaveError` toast). Without the prop
+the path is the pre-existing one, unchanged.
+
+Each batch captures its save target and result callbacks before confirmation.
+Rerendering with another record while the gate awaits cannot redirect that
+approved write or its callbacks to the new record.
+FormView also isolates its mutation observer and draft state by model and row
+ID. Switching either starts a fresh form; a refetch of the same row preserves
+pending edits. Pass a stable model definition, as returned by `defineModel`.
+
+Use it for the fields where a typo takes a tenant dark and there is no save
+button to hesitate over: identity fields (`uuid`, `auth_domain`), escalating
+grants (MemberDetail guards `manage_group` / `manage_members` this way). The
+contract is pinned by `npm run verify:form-autosave`.
+
 ### The autosave lifecycle (the machine: `useFormAutosave`)
 
 1. **Commit, never keystroke.** Text/textarea update the draft per keystroke

package/docs/loading.md

@@ -238,5 +238,6 @@ clicked away mid-save, they keep where they went.
 - **The overlay is `dialog[open]`.** ModelTable's `autoRefresh` skips ticks
   while any `dialog[open]` exists, so auto-refresh politely pauses during a
   busy operation. That is intended; don't "fix" it.
-- **Toasts render under the overlay** (`.toast-host` is z-index 60, the
-  overlay is in the top layer). Toast *after* closing the handle, not during.
+- **Toasts remain above the overlay.** The single [ToastHost](feedback.md#toast)
+  follows the active native dialog, keeping notifications and their actions
+  available during a blocking operation.

package/docs/popover.md

@@ -117,9 +117,9 @@ baked in 20px padding + 260px min-width for its one tenant, the calendar
 - **Don't wrap the shell in `overflow: hidden` styling assumptions** —
   it's in the top layer; nothing ancestral clips or covers it. Anything
   that must paint ABOVE an open popover has to join the top layer later.
-- **Toasts render under open modals** (`.toast-host` is z-index 60, not
-  top layer). Don't signal from popover content inside a modal via toast;
-  show it in the modal body.
+- **Use the single ToastHost for modal notifications.** It follows the active
+  dialog into the native top layer; see [feedback](feedback.md#toast). Keep
+  actionable errors in the modal body too when they need to outlast a toast.
 - **One value pipeline:** the popover is presentation only. Commit
   semantics (`change` on select/Enter/blur, never per keystroke) belong
   to the consuming control.

package/docs/realtime.md

@@ -19,6 +19,11 @@ disable this shared provider.
   `auth_success`. An auth error closes and suspends the connection until the
   token value changes.
 - Heartbeat is a `ping` every 20 seconds with a 10-second `pong` deadline.
+  A server-initiated `{type:'ping'}` (django-mojo 1.32+ sends one every 20
+  seconds and culls a socket silent for 90) is answered at once with
+  `{type:'pong'}` while ready, clears the pending `pong` deadline, and is never
+  dispatched to consumers. Answering from the message handler keeps the socket
+  alive while a background tab throttles the client's own ping timer.
   Reconnect uses capped jittered backoff. Pre-accept close code 4429 enforces at
   least 60 seconds, and focus/visibility cannot bypass that deadline.
 - Desired topics are refcounted and replay after authentication. Operations are

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.3",
+    "version": "0.2.5",
     "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/group-api-keys.tsx

@@ -14,6 +14,7 @@ import {
     FlatRow,
     ModelTable,
     SchemaForm,
+    confirmGuardrail,
     fmt,
     modal,
     toast,
@@ -112,6 +113,20 @@ function TokenFooter({ permissions }: { permissions: string[] }) {
     );
 }
 
+/** The stop in front of `is_active: false` — copy states what the backend does. */
+function confirmDeactivateKey(row: GroupApiKeyRow): Promise<boolean> {
+    return confirmGuardrail({
+        title: `Deactivate API key "${row.name}"?`,
+        effect: <>The key stops authenticating the moment this saves.</>,
+        why: [
+            <>Every integration holding this key gets <b>401</b> on its next call — the caller sees an auth failure, not a notice.</>,
+            <>The key is <b>not rotated</b>: the same secret stays on file, so anyone who holds it regains access the instant it is re-enabled.</>,
+        ],
+        undo: 'Re-enabling restores the same key; no integration needs a new secret.',
+        confirmText: 'Deactivate key',
+    });
+}
+
 function useGroupApiKeyActions(permission: PermSpec) {
     const renderedPermissions = useRenderedPermissions();
     const create = useCreateGroupApiKey();
@@ -241,6 +256,11 @@ function useGroupApiKeyActions(permission: PermSpec) {
         if (Object.keys(permissionChanges).length) changes.permissions = permissionChanges;
         if (!Object.keys(changes).length) return;
 
+        // Flipping a key inactive is the one edit here with a blast radius
+        // outside this portal — every caller holding the key. Guardrail it;
+        // the other edits in the same form ride along only if it is confirmed.
+        if (changes.is_active === false && !(await confirmDeactivateKey(row))) return;
+
         try {
             await save.mutateAsync({ id: row.id, changes });
             toast.success('API key updated');