portal-mojo 0.2.3 → 0.2.4

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

@@ -43,7 +43,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-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/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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.3",
+    "version": "0.2.4",
     "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');

package/src/admin/credentials/webhook-subscriptions.tsx

@@ -8,6 +8,7 @@ import {
     FlatRow,
     ModelTable,
     SchemaForm,
+    confirmGuardrail,
     fmt,
     modal,
     toast,
@@ -135,6 +136,23 @@ const WEBHOOK_FIELDS: Field[] = [
     { name: 'is_active', type: 'switch', label: 'Active', help: 'Inactive subscriptions are skipped.' },
 ];
 
+/** The stop in front of `is_active: false` — copy states what the backend does. */
+function confirmDisableSubscription(row: WebhookSubscriptionRow): Promise<boolean> {
+    let host = row.url;
+    try { host = new URL(row.url).host || row.url; } catch { /* keep the raw url */ }
+    const events = row.events.length ? row.events.join(', ') : 'all events';
+    return confirmGuardrail({
+        title: `Disable webhook to ${host}?`,
+        effect: <>Deliveries of <b>{events}</b> to <b>{row.url}</b> stop the moment this saves.</>,
+        why: [
+            <>Deliveries stop for these events and nothing re-registers them — the subscription stays off until someone switches it back on here.</>,
+            <>Consumers see <b>silence, not an error</b>: the receiver gets no failed delivery and no notice, so anything downstream that depends on these events degrades quietly.</>,
+        ],
+        undo: 'Re-enable it here to resume deliveries for new events.',
+        confirmText: 'Disable webhook',
+    });
+}
+
 function useWebhookActions(permission: PermSpec) {
     const save = WebhookSubscriptionModel.useSave();
 
@@ -206,6 +224,7 @@ function useWebhookActions(permission: PermSpec) {
         if (events.join('\u0000') !== row.events.join('\u0000')) changes.events = events;
         if (isActive !== row.is_active) changes.is_active = isActive;
         if (!Object.keys(changes).length) return;
+        if (changes.is_active === false && !(await confirmDisableSubscription(row))) return;
         try {
             await save.mutateAsync({ id: row.id, changes });
             toast.success('Webhook subscription updated');
@@ -216,6 +235,8 @@ function useWebhookActions(permission: PermSpec) {
 
     const toggleSubscription = async (row: WebhookSubscriptionRow, next: boolean) => {
         if (!can) return;
+        // Only the OFF direction is guarded — re-enabling restores deliveries.
+        if (!next && !(await confirmDisableSubscription(row))) return;
         try {
             await save.mutateAsync({ id: row.id, changes: { is_active: next } });
         } catch (error) {

package/src/admin/identity/members/MemberDetail.tsx

@@ -1,9 +1,9 @@
-import { useSyncExternalStore } from 'react';
+import { useSyncExternalStore, type ReactNode } from 'react';
 import { useQueryClient } from '@tanstack/react-query';
 import { useCan, type PermSpec } from '../../../client/runtime';
 import {
     Badge, DetailView, Eyebrow, FlatRow, FormView, JsonBlock, MetricCard,
-    ModelTable, fmt, formModal, toast, type Column, type DetailMenuEntry,
+    ModelTable, confirmGuardrail, fmt, formModal, toast, type Column, type DetailMenuEntry,
 } from '../../../ui';
 import { LOGS_ADMIN_PERMISSIONS, LogModel, type LogRow } from '../../monitoring';
 import {
@@ -51,6 +51,43 @@ function AuditTable({ memberId }: { memberId: number }) {
     );
 }
 
+/**
+ * The two grants that let a member reach past its own row. A switch flip
+ * autosaves with no save button, so the stop lives in FormView's
+ * `beforeSave`: only these keys, only the ON direction — everything else
+ * stays one click. (`admin` is not an editable member grant here —
+ * `isEditableMemberPermission` excludes it — so it cannot be flipped from
+ * this form and needs no guard.)
+ */
+const ESCALATING_GRANTS: Record<string, { label: string; why: ReactNode }> = {
+    manage_group: {
+        label: 'Manage Group',
+        why: <><code>manage_group</code> unlocks the group record itself — its settings and policy metadata, its API keys, webhook subscriptions and integrations — every write the group's credential and identity panels gate on.</>,
+    },
+    manage_members: {
+        label: 'Manage Members',
+        why: <><code>manage_members</code> lets the holder change any member's grants, including its own, and admit or remove members — a grant that can reproduce itself.</>,
+    },
+};
+
+/** beforeSave gate: stops only when an escalating grant flips ON. */
+function confirmGrantEscalation(member: MemberRow, changes: Record<string, unknown>): Promise<boolean> | true {
+    const perms = changes.permissions;
+    if (!perms || typeof perms !== 'object') return true;
+    const granting = Object.keys(ESCALATING_GRANTS).filter((key) => (perms as Record<string, unknown>)[key] === true);
+    if (granting.length === 0) return true;
+    const who = member.user?.display_name || member.user?.email || member.user?.username || `User #${member.user?.id ?? member.id}`;
+    const group = member.group?.name || 'this group';
+    const labels = granting.map((key) => ESCALATING_GRANTS[key]!.label).join(' + ');
+    return confirmGuardrail({
+        title: `Grant ${labels} to ${who}?`,
+        effect: <><b>{who}</b> holds <b>{granting.join(' and ')}</b> in <b>{group}</b> the moment this saves — there is no save button and no second step.</>,
+        why: granting.map((key) => ESCALATING_GRANTS[key]!.why),
+        undo: 'Switch it off here to revoke. Anything done while the grant was held stays done.',
+        confirmText: `Grant ${labels}`,
+    });
+}
+
 function GrantSummary({ member }: { member: MemberRow }) {
     const raw = rawMemberGrants(member.permissions);
     const effective = effectiveMemberGrants(member.permissions);
@@ -201,7 +238,15 @@ export function MemberDetail({
                             <Eyebrow>Per-group authorization</Eyebrow>
                             <p className="dim">Role labels are not authorization. Protected changes may be rejected by <code>MEMBER_PERMS_PROTECTION</code>; failed autosaves revert and show the server error.</p>
                             {canSave
-                                ? <FormView model={MemberModel} row={member} fields={memberPermissionFields()} onSaved={() => { void MemberModel.invalidate(qc); }} />
+                                ? (
+                                    <FormView
+                                        model={MemberModel}
+                                        row={member}
+                                        fields={memberPermissionFields()}
+                                        beforeSave={({ changes }) => confirmGrantEscalation(member, changes)}
+                                        onSaved={() => { void MemberModel.invalidate(qc); }}
+                                    />
+                                )
                                 : <GrantSummary member={member} />}
                             {deploymentOnly.length > 0 && (
                                 <p className="dim">Deployment-specific stored grants without registered editors remain read-only: <code>{deploymentOnly.join(', ')}</code>.</p>

package/src/admin/phonehub/PhoneHubPage.tsx

@@ -82,7 +82,7 @@ const providerCredentialFields: Record<PhoneProvider, PhoneSecretField[]> = {
 function providerOperationalNote(provider: PhoneProvider): string {
     if (provider === 'mojo') return 'Mojo Remote is used by the group-aware SMS delivery path.';
     if (provider === 'aws') return 'Stored AWS credentials can be tested here. AWS outbound delivery is not wired yet.';
-    return 'Stored Twilio credentials can be tested here. Outbound delivery currently uses the global Twilio settings.';
+    return 'SMS delivery uses the saved Twilio credential pair, or global settings when neither credential is stored.';
 }
 
 function providerVisibleRows(row: PhoneConfigRow): Array<[string, string]> {
@@ -276,6 +276,7 @@ function ConfigDetail({ id, onClose }: { id: number; onClose: () => void }) {
 
 
     const [testing, setTesting] = useState(false);
+    const [testResult, setTestResult] = useState<Awaited<ReturnType<typeof testPhoneConfigImperative>> | null>(null);
     if (!query.data) return <div className="modal-pad">{query.isLoading ? 'Loading provider configuration…' : 'Configuration unavailable'}<button className="btn" onClick={onClose}>Close</button></div>;
     const row = query.data;
     const toggle = async (next: boolean) => {
@@ -286,30 +287,40 @@ function ConfigDetail({ id, onClose }: { id: number; onClose: () => void }) {
         finally { setSaving(false); }
     };
     const meta = providerMeta[row.provider];
-    const edit = () => void modal.open((close) => <ConfigEditor row={row} close={async (saved) => { close(saved); if (saved) await query.refetch(); }} />, { size: 'lg' });
+    const edit = () => void modal.open((close) => <ConfigEditor row={row} close={async (saved) => { close(saved); if (saved) { setTestResult(null); await query.refetch(); } }} />, { size: 'lg' });
     const test = async () => {
         setTesting(true);
+        setTestResult(null);
         try {
             const result = await testPhoneConfigImperative(id);
-            toast[result.status ? 'success' : 'error'](result.message);
+            setTestResult(result);
+            toast[result.testMode ? 'warning' : result.status ? 'success' : 'error'](result.message);
         } catch (reason) {
-            toast.error(reason instanceof Error ? reason.message : 'Connection test failed');
+            const message = reason instanceof Error ? reason.message : 'Connection test failed';
+            setTestResult({ status: false, message, testMode: false, errorCode: null });
+            toast.error(message);
         } finally {
             setTesting(false);
         }
     };
 
+    const resultNotice = testResult && <div className={testResult.status && !testResult.testMode ? 'known-card' : 'form-alert'} role={testResult.status ? 'status' : 'alert'}>
+        <h3>Connection test: {testResult.testMode ? 'Not tested' : testResult.status ? 'Passed' : 'Failed'}</h3>
+        <p>{testResult.message}</p>
+        {testResult.errorCode === 'missing_credentials' && <p>Use Edit configuration to save the provider credentials, then test again. Blank credential fields keep any saved value unchanged.</p>}
+    </div>;
+
     return <DetailView
         title={row.name}
-        subtitle={relationLabel(row.group)}
+        subtitle={`Scope: ${relationLabel(row.group)}`}
         icon={meta.icon}
         chips={[{ text: meta.label, tone: 'info' }, { text: row.is_active ? 'Active' : 'Inactive', tone: row.is_active ? 'success' : 'muted' }, ...(row.test_mode ? [{ text: 'Test mode', tone: 'warning' as const }] : [])]}
         onClose={onClose}
         active={canManage ? { value: row.is_active, disabled: saving, onChange: next => void toggle(next) } : undefined}
-        contextMenu={canManage ? [{ label: 'Edit configuration', onSelect: edit }, { label: 'Test stored connection', disabled: testing, onSelect: () => void test() }, { label: row.is_active ? 'Deactivate' : 'Reactivate', disabled: saving, onSelect: () => void toggle(!row.is_active) }] : []}
+        contextMenu={canManage ? [{ label: 'Edit configuration', disabled: testing, onSelect: edit }, { label: 'Test stored connection', disabled: testing, onSelect: () => void test() }, { label: row.is_active ? 'Deactivate' : 'Reactivate', disabled: saving, onSelect: () => void toggle(!row.is_active) }] : []}
         sections={[
-            { key: 'overview', label: 'Overview', icon: 'bi-sliders', render: () => <div className="detail-section"><div className="phonehub-provider-summary"><i className={`bi ${meta.icon}`} /><div><span className="eyebrow">Provider</span><h3>{meta.label}</h3><p>{meta.description}</p></div></div><div className="phonehub-summary-grid"><div className="known-card"><span>Scope</span><strong>{relationLabel(row.group)}</strong></div><div className="known-card"><span>Automatic lookup</span><strong>{row.lookup_enabled ? `Enabled · ${row.lookup_cache_days} days` : 'Disabled'}</strong></div><div className="known-card"><span>Last modified</span><strong>{fmt.datetime(row.modified)}</strong></div></div><p className="dim">An active group configuration wins; otherwise Phone Hub falls back to the first active system default.</p></div> },
-            { key: 'connection', label: 'Connection', icon: 'bi-plug', render: () => <div className="detail-section"><div className="section-eyebrow">{meta.label} settings</div>{providerVisibleRows(row).map(([label, value]) => <FlatRow key={label} label={label}>{value}</FlatRow>)}<FlatRow label="Credentials"><span><i className="bi bi-shield-lock" /> Write-only; edit to replace or clear</span></FlatRow><div className={`phonehub-provider-note${row.provider === 'mojo' ? '' : ' is-warning'}`}><i className={`bi ${row.provider === 'mojo' ? 'bi-info-circle' : 'bi-exclamation-triangle'}`} /><span>{providerOperationalNote(row.provider)}</span></div>{row.test_mode && <div className="phonehub-provider-note is-warning"><i className="bi bi-beaker" /><span>Test mode only short-circuits the connection test. It does not prevent SMS delivery.</span></div>}<FlatRow label="Created">{fmt.datetime(row.created)}</FlatRow></div> }
+            { key: 'overview', label: 'Overview', icon: 'bi-sliders', render: () => <div className="detail-section">{resultNotice}<div className="phonehub-provider-summary"><i className={`bi ${meta.icon}`} /><div><span className="eyebrow">Provider</span><h3>{meta.label}</h3><p>{meta.description}</p></div></div><div className="phonehub-summary-grid"><div className="known-card"><span>Scope</span><strong>{relationLabel(row.group)}</strong></div><div className="known-card"><span>Automatic lookup</span><strong>{row.lookup_enabled ? `Enabled · ${row.lookup_cache_days} days` : 'Disabled'}</strong></div><div className="known-card"><span>Last modified</span><strong>{fmt.datetime(row.modified)}</strong></div></div><p className="dim">An active group configuration wins; otherwise Phone Hub falls back to the first active system default.</p></div> },
+            { key: 'connection', label: 'Connection', icon: 'bi-plug', render: () => <div className="detail-section">{resultNotice}<FlatRow label="Scope">{relationLabel(row.group)}</FlatRow><div className="section-eyebrow">{meta.label} settings</div>{providerVisibleRows(row).map(([label, value]) => <FlatRow key={label} label={label}>{value}</FlatRow>)}<FlatRow label="Credentials"><span><i className="bi bi-shield-lock" /> Write-only; edit to replace or clear</span></FlatRow><div className={`phonehub-provider-note${row.provider === 'mojo' ? '' : ' is-warning'}`}><i className={`bi ${row.provider === 'mojo' ? 'bi-info-circle' : 'bi-exclamation-triangle'}`} /><span>{providerOperationalNote(row.provider)}</span></div>{row.test_mode && <div className="phonehub-provider-note is-warning"><i className="bi bi-beaker" /><span>Test mode only short-circuits the connection test. It does not prevent SMS delivery.</span></div>}<FlatRow label="Created">{fmt.datetime(row.created)}</FlatRow></div> }
         ]}
     />;
 }

package/src/admin/phonehub/api.ts

@@ -42,13 +42,13 @@ export async function savePhoneConfigImperative(qc:QueryClient,id:number|null,sc
     const row=sanitizePhoneConfigRow(response.data as PhoneConfigRow);
     qc.setQueryData(PhoneConfigModel.keys.one(row.id),row);await qc.invalidateQueries({queryKey:PhoneConfigModel.keys.root});return row;
 }
-// Deliberately NOT client/action-result's `mojoAction`: `status` here is the
-// connection test's VERDICT (a result datum), not an action refusal — a failed
-// test must resolve so the panel can render it.
-export async function testPhoneConfigImperative(id:number):Promise<{status:boolean;message:string}>{
+// PhoneConfig returns `success` as its provider verdict; envelope `status`
+// only says the REST action ran. A failed test resolves for inline display.
+export async function testPhoneConfigImperative(id:number):Promise<{status:boolean;message:string;testMode:boolean;errorCode:string|null}>{
     const response=await mojoCall(`${PhoneConfigModel.endpoint}/${id}`,{method:'POST',body:{test_connection:1}});
     const data=(response.data??response) as Record<string,unknown>;
-    return {status:data.status!==false,message:typeof data.message==='string'?data.message:'Connection test completed.'};
+    const status=data.success===true;
+    return {status,testMode:data.test_mode===true,errorCode:typeof data.error==='string'?data.error:null,message:typeof data.message==='string'?data.message:status?'Connection verified.':'The server did not confirm the provider connection.'};
 }
 export async function fetchPhoneGroupChoices():Promise<PhoneRelation[]>{
     const result=await mojoList<Record<string,unknown>>('/api/group',{graph:'basic',sort:'name',start:0,size:PHONE_GROUP_CHOICE_LIMIT});

package/src/client/mock.ts

@@ -7676,7 +7676,7 @@ async function phoneHubFetch(path:string,opts:MockFetchOpts):Promise<unknown|und
     const smsMatch=path.match(/^\/api\/phonehub\/sms(?:\/(\d+))?$/);
     if(smsMatch){const id=smsMatch[1]?Number(smsMatch[1]):null;if(method==='DELETE'){if(!hasGlobalPermission(caller,SMS_DELETE_GRANTS))return permissionDenied();if(id==null)return {status:false,error:'Method not allowed',error_code:405};db.sms=db.sms.filter(row=>row.id!==id);return {status:'deleted'};}if(method==='POST'&&!hasGlobalPermission(caller,SMS_SAVE_GRANTS))return permissionDenied();if(method==='GET'&&!hasGlobalPermission(caller,SMS_VIEW_GRANTS))return permissionDenied();if(id!=null){const row=db.sms.find(item=>item.id===id);if(!row)return {status:false,error:'SMS not found',error_code:404};if(method==='POST'){for(const key of ['status','error_message','delivered_at'] as const)if(key in (opts.body??{}))(row as unknown as Record<string,unknown>)[key]=opts.body?.[key];row.modified=Math.floor(Date.now()/1000);}return {status:true,data:smsWire(row),graph:'default'};}if(method==='POST'){const body=opts.body??{};const now=Math.floor(Date.now()/1000);const row:MockSms={id:Math.max(0,...db.sms.map(item=>item.id))+1,created:now,modified:now,direction:String(body.direction??'outbound'),from_number:String(body.from_number??''),to_number:String(body.to_number??''),body:String(body.body??''),status:String(body.status??'queued'),provider:body.provider?String(body.provider):null,provider_message_id:null,error_code:null,error_message:null,metadata:{},is_test:Boolean(body.is_test),sent_at:null,delivered_at:null,user:body.user==null?null:Number(body.user),group:body.group==null?null:Number(body.group)};db.sms.unshift(row);return {status:true,data:smsWire(row),graph:'default'};}if(method!=='GET')return {status:false,error:'Method not allowed',error_code:405};const params=messagingParams(opts.params??{},['direction','status','provider','group','user'],['created','direction','status','provider','sent_at','delivered_at'],'default','-created',true);return messagingList(db.sms as unknown as Record<string,unknown>[],params,row=>`${row.from_number} ${row.to_number} ${row.body}`,'default',row=>smsWire(row as unknown as MockSms),'-created');}
     const configMatch=path.match(/^\/api\/phonehub\/config(?:\/(\d+))?$/);
-    if(configMatch){const id=configMatch[1]?Number(configMatch[1]):null;if(method==='DELETE'){if(!hasGlobalPermission(caller,PHONE_CONFIG_DELETE_GRANTS))return permissionDenied();if(id==null)return {status:false,error:'Method not allowed',error_code:405};db.phoneConfigs=db.phoneConfigs.filter(row=>row.id!==id);db.phoneConfigSecrets.delete(id);return {status:'deleted'};}if(!hasGlobalPermission(caller,PHONE_CONFIG_VIEW_GRANTS))return permissionDenied();if(id!=null){const row=db.phoneConfigs.find(item=>item.id===id);if(!row)return {status:false,error:'Phone config not found',error_code:404};if(method==='POST'&&opts.body?.test_connection){if(row.test_mode)return {status:true,message:'Config is in test mode - provider not tested'};const secrets=db.phoneConfigSecrets.get(id)??{};const ready=row.provider==='twilio'?Boolean(secrets.twilio_account_sid&&secrets.twilio_auth_token):row.provider==='aws'?Boolean(secrets.aws_access_key_id&&secrets.aws_secret_access_key):Boolean(secrets.mojo_api_key&&row.mojo_remote_url);return ready?{status:true,message:`${row.provider} connection succeeded`}:{status:false,error:`${row.provider} credentials are incomplete`,error_code:400};}if(method==='POST'){const nextGroup='group'in(opts.body??{})?(opts.body?.group==null?null:Number(opts.body.group)):row.group;if(nextGroup!=null&&db.phoneConfigs.some(item=>item.id!==id&&item.group===nextGroup))return {status:false,error:'A configuration already exists for this group',error_code:400};applyPhoneConfig(row,opts.body??{});saveMockPhoneSecrets(id,opts.body??{});}else if(method!=='GET')return {status:false,error:'Method not allowed',error_code:405};return {status:true,data:phoneConfigWire(row),graph:'default'};}if(method==='POST'){const body=opts.body??{};const group=body.group==null?null:Number(body.group);if(group!=null&&!db.groups.some(item=>item.id===group))return {status:false,error:'Group not found',error_code:404};if(group!=null&&db.phoneConfigs.some(item=>item.group===group))return {status:false,error:'A configuration already exists for this group',error_code:400};const now=Math.floor(Date.now()/1000);const row:MockPhoneConfig={id:Math.max(0,...db.phoneConfigs.map(item=>item.id))+1,created:now,modified:now,group,name:String(body.name??''),is_active:body.is_active!==false,provider:['twilio','aws','mojo'].includes(String(body.provider))?String(body.provider) as MockPhoneConfig['provider']:'twilio',twilio_from_number:null,aws_region:null,aws_sender_id:null,mojo_remote_url:null,lookup_enabled:body.lookup_enabled!==false,lookup_cache_days:Number(body.lookup_cache_days??90),test_mode:Boolean(body.test_mode)};applyPhoneConfig(row,body);db.phoneConfigs.push(row);saveMockPhoneSecrets(row.id,body);return {status:true,data:phoneConfigWire(row),graph:'default'};}if(method!=='GET')return {status:false,error:'Method not allowed',error_code:405};const params=messagingParams(opts.params??{},['provider','is_active','group','test_mode'],['name','provider','is_active','created','modified'],'default','name');return messagingList(db.phoneConfigs as unknown as Record<string,unknown>[],params,row=>String(row.name),'default',row=>phoneConfigWire(row as unknown as MockPhoneConfig),'name');}
+    if(configMatch){const id=configMatch[1]?Number(configMatch[1]):null;if(method==='DELETE'){if(!hasGlobalPermission(caller,PHONE_CONFIG_DELETE_GRANTS))return permissionDenied();if(id==null)return {status:false,error:'Method not allowed',error_code:405};db.phoneConfigs=db.phoneConfigs.filter(row=>row.id!==id);db.phoneConfigSecrets.delete(id);return {status:'deleted'};}if(!hasGlobalPermission(caller,PHONE_CONFIG_VIEW_GRANTS))return permissionDenied();if(id!=null){const row=db.phoneConfigs.find(item=>item.id===id);if(!row)return {status:false,error:'Phone config not found',error_code:404};if(method==='POST'&&opts.body?.test_connection){if(row.test_mode)return {status:true,data:{success:true,test_mode:true,message:'Config is in test mode - provider not tested'}};const secrets=db.phoneConfigSecrets.get(id)??{};const ready=row.provider==='twilio'?Boolean(secrets.twilio_account_sid&&secrets.twilio_auth_token):row.provider==='aws'?Boolean(secrets.aws_access_key_id&&secrets.aws_secret_access_key):Boolean(secrets.mojo_api_key&&row.mojo_remote_url);return {status:true,data:ready?{success:true,message:`${row.provider} connection succeeded`}:{success:false,message:`${row.provider} credentials are incomplete`,error:'missing_credentials'}};}if(method==='POST'){const nextGroup='group'in(opts.body??{})?(opts.body?.group==null?null:Number(opts.body.group)):row.group;if(nextGroup!=null&&db.phoneConfigs.some(item=>item.id!==id&&item.group===nextGroup))return {status:false,error:'A configuration already exists for this group',error_code:400};applyPhoneConfig(row,opts.body??{});saveMockPhoneSecrets(id,opts.body??{});}else if(method!=='GET')return {status:false,error:'Method not allowed',error_code:405};return {status:true,data:phoneConfigWire(row),graph:'default'};}if(method==='POST'){const body=opts.body??{};const group=body.group==null?null:Number(body.group);if(group!=null&&!db.groups.some(item=>item.id===group))return {status:false,error:'Group not found',error_code:404};if(group!=null&&db.phoneConfigs.some(item=>item.group===group))return {status:false,error:'A configuration already exists for this group',error_code:400};const now=Math.floor(Date.now()/1000);const row:MockPhoneConfig={id:Math.max(0,...db.phoneConfigs.map(item=>item.id))+1,created:now,modified:now,group,name:String(body.name??''),is_active:body.is_active!==false,provider:['twilio','aws','mojo'].includes(String(body.provider))?String(body.provider) as MockPhoneConfig['provider']:'twilio',twilio_from_number:null,aws_region:null,aws_sender_id:null,mojo_remote_url:null,lookup_enabled:body.lookup_enabled!==false,lookup_cache_days:Number(body.lookup_cache_days??90),test_mode:Boolean(body.test_mode)};applyPhoneConfig(row,body);db.phoneConfigs.push(row);saveMockPhoneSecrets(row.id,body);return {status:true,data:phoneConfigWire(row),graph:'default'};}if(method!=='GET')return {status:false,error:'Method not allowed',error_code:405};const params=messagingParams(opts.params??{},['provider','is_active','group','test_mode'],['name','provider','is_active','created','modified'],'default','name');return messagingList(db.phoneConfigs as unknown as Record<string,unknown>[],params,row=>String(row.name),'default',row=>phoneConfigWire(row as unknown as MockPhoneConfig),'name');}
     return undefined;
 }
 async function messagingFetch(path:string,opts:MockFetchOpts):Promise<unknown|undefined>{

package/src/ui/FormView.tsx

@@ -26,6 +26,7 @@ import { toast } from './toast';
 import {
     useFormAutosave,
     type AutosaveBatchInfo,
+    type AutosaveBeforeSave,
     type FieldStatus,
     type FormAutosaveApi,
 } from './form-autosave';
@@ -104,13 +105,34 @@ export interface FormViewProps<T extends { id: number | string }> {
     savedFlashMs?: number;
     onSaved?: (info: AutosaveBatchInfo & { row: T }) => void;
     onSaveError?: (info: AutosaveBatchInfo & { error: Error }) => void;
+    /**
+     * Pre-save gate, once per batch. `false` drops the batch (its fields
+     * revert, no toast); an object replaces the wire body; true/undefined
+     * proceeds. Put a `confirmGuardrail` here for grants/identity fields.
+     */
+    beforeSave?: AutosaveBeforeSave<T>;
     /** True while any FileField transfer is active. Owners can block dismissal. */
     onPendingChange?: (pending: boolean) => void;
     className?: string;
 }
 
+const saveOwnerIds = new WeakMap<object, number>();
+let nextSaveOwnerId = 0;
+
 export function FormView<T extends { id: number | string }>(props: FormViewProps<T>) {
-    const { model, row, fields, tabs, debounceMs, savedFlashMs, onSaved, onSaveError, className } = props;
+    // A TanStack mutation observer updates its mutationFn on rerender.
+    // Keep the observer and reducer with the model/record that created them,
+    // so a confirmation already in flight cannot migrate to another owner.
+    let modelId = saveOwnerIds.get(props.model.useSave);
+    if (modelId === undefined) {
+        modelId = ++nextSaveOwnerId;
+        saveOwnerIds.set(props.model.useSave, modelId);
+    }
+    return <OwnedFormView key={JSON.stringify([modelId, props.row.id])} {...props} />;
+}
+
+function OwnedFormView<T extends { id: number | string }>(props: FormViewProps<T>) {
+    const { model, row, fields, tabs, debounceMs, savedFlashMs, onSaved, onSaveError, beforeSave, className } = props;
     const save = model.useSave();
 
     // Registry-named tabsets re-render on registration; inline defs pass through.
@@ -164,6 +186,7 @@ export function FormView<T extends { id: number | string }>(props: FormViewProps
         save: (changes) => save.mutateAsync({ id: row.id, changes } satisfies SaveVars),
         debounceMs,
         savedFlashMs,
+        beforeSave,
         onSaved: (info) => {
             publishOwnerResult(info.fields, 'success', info.changes, info.row);
             onSaved?.(info);

package/src/ui/ModelTable.tsx

@@ -56,12 +56,18 @@ interface BatchActionBase<T> {
     danger?: boolean;
     /** Row-state eligibility. Ineligible selected rows are never submitted. */
     eligible?: (row: T) => boolean;
-    /** Confirm copy; false skips the prompt. Default: "<label> N item(s)?" */
-    confirm?: string | false;
+    /**
+     * The permission step. A string is the `modal.confirm` copy; false skips
+     * the prompt; a function REPLACES the built-in confirm — resolve false
+     * to cancel (open a `confirmGuardrail` here for batches that take a
+     * tenant dark or can't be undone). Default: "<label> N item(s)?"
+     */
+    confirm?: string | false | ((rows: T[]) => Promise<boolean>);
     /**
      * Optional once-per-batch step (collect a reason, pick a value…) run
      * AFTER the confirm. Resolve null to cancel the batch; the resolved
-     * value is passed to every run() call.
+     * value is passed to every run() call. Ask permission in `confirm`,
+     * not here — a null from prepare means "nothing collected".
      */
     prepare?: (rows: T[]) => Promise<unknown | null>;
 }
@@ -449,7 +455,9 @@ export function ModelTable<T extends { id: RowId }>({
     const runBatch = async (action: BatchAction<T>) => {
         const targets = rows.filter((r) => selected.has(r.id) && (!action.eligible || action.eligible(r)));
         if (targets.length === 0) return;
-        if (action.confirm !== false) {
+        if (typeof action.confirm === 'function') {
+            if (!(await action.confirm(targets))) return;
+        } else if (action.confirm !== false) {
             const ok = await modal.confirm({
                 title: action.label,
                 message: action.confirm ?? `${action.label} ${targets.length} item(s)?`,

package/src/ui/detail/MetadataSection.tsx

@@ -18,9 +18,14 @@
 //   · Controlled on `metadata` (architecture rule 5): the component never
 //     mirrors server state. `onSaved` is REQUIRED — it is how the owner
 //     (TanStack cache, parent state) learns about the write.
+//   · Every save posts the WHOLE blob, so one bad write can wipe a protected
+//     key (auth_config / geofence / redemption_policy) in a single POST.
+//     Removing a top-level key therefore stops on a guardrail that lists
+//     the keys about to vanish; owners add `beforeSave(next, prev)` to diff
+//     their own protected keys on top.
 import { useState } from 'react';
 import { mojoCall } from '../../client/client';
-import { modal } from '../modal';
+import { confirmGuardrail } from '../guardrail';
 import { toast } from '../toast';
 
 type Draft =
@@ -49,13 +54,42 @@ function parseValue(raw: string): unknown {
     }
 }
 
-export function MetadataSection({ endpoint, id, metadata, onSaved, title = 'Metadata' }: {
+/**
+ * Default stop: a top-level key is about to leave the blob. Names every key
+ * so a wipe of `auth_config` reads as exactly that, not "Remove entry?".
+ */
+function confirmRemovedKeys(removed: string[], next: Record<string, unknown>): Promise<boolean> {
+    const one = removed.length === 1;
+    const remaining = Object.keys(next).length;
+    return confirmGuardrail({
+        title: one ? `Remove metadata key ${removed[0]}?` : `Remove ${removed.length} metadata keys?`,
+        effect: <>
+            {removed.map((key, i) => <span key={key}>{i > 0 ? ', ' : ''}<code>{key}</code></span>)}
+            {one ? ' leaves' : ' leave'} the record the moment this saves — the POST carries the whole blob, {remaining === 0 ? 'and it will be empty' : `${remaining} key${remaining === 1 ? '' : 's'} remain`}.
+        </>,
+        why: [
+            <>Anything that reads {one ? 'this key' : 'these keys'} (policy, auth configuration, geofences, redemption rules) sees it missing on its next read, with no error raised here.</>,
+            <>The value is not kept anywhere in this portal — re-adding the key means re-entering it by hand.</>,
+        ],
+        undo: 'There is no undo; re-add the key with its previous value.',
+        confirmText: one ? 'Remove key' : `Remove ${removed.length} keys`,
+        typeToConfirm: removed.length > 1 ? String(removed.length) : undefined,
+    });
+}
+
+export function MetadataSection({ endpoint, id, metadata, onSaved, beforeSave, title = 'Metadata' }: {
     /** Collection endpoint — the save posts to `<endpoint>/<id>`. */
     endpoint: string;
     id: number | string;
     metadata: Record<string, unknown>;
     /** Called with the new blob after the server accepted it. */
     onSaved: (next: Record<string, unknown>) => void;
+    /**
+     * Owner gate, after the built-in removed-key stop: resolve false to
+     * cancel the write (no error, editor state kept). Diff protected keys
+     * between `next` and `prev` here.
+     */
+    beforeSave?: (next: Record<string, unknown>, prev: Record<string, unknown>) => Promise<boolean> | boolean;
     title?: string;
 }) {
     const [draft, setDraft] = useState<Draft>(null);
@@ -65,8 +99,16 @@ export function MetadataSection({ endpoint, id, metadata, onSaved, title = 'Meta
     const keys = Object.keys(metadata).sort();
     const busy = pending !== null;
 
-    /** The one write path. Resolves true only when the server accepted it. */
+    /**
+     * The one write path. Resolves true only when the server accepted it;
+     * false when a gate declined (nothing posted, no error) or the POST
+     * rejected (banner). Gates run BEFORE pending so the dialog is not
+     * stacked over disabled controls.
+     */
     async function commit(next: Record<string, unknown>, token: string, message: string): Promise<boolean> {
+        const removed = Object.keys(metadata).filter((key) => !Object.prototype.hasOwnProperty.call(next, key));
+        if (removed.length > 0 && !(await confirmRemovedKeys(removed, next))) return false;
+        if (beforeSave && !(await beforeSave(next, metadata))) return false;
         setPending(token);
         setError(null);
         try {
@@ -101,13 +143,7 @@ export function MetadataSection({ endpoint, id, metadata, onSaved, title = 'Meta
     }
 
     async function removeKey(key: string) {
-        const confirmed = await modal.confirm({
-            title: 'Remove entry',
-            message: <>Remove metadata key <b>{key}</b>?</>,
-            confirmText: 'Remove',
-            danger: true,
-        });
-        if (!confirmed) return;
+        // The removed-key guardrail inside commit() is the confirm.
         const next = { ...metadata };
         delete next[key];
         await commit(next, `delete:${key}`, 'Metadata entry removed');

package/src/ui/form-autosave.ts

@@ -20,6 +20,12 @@
 //   · zod failure: the save of that field is blocked client-side; the message
 //     occupies the same error slot. Hidden (showWhen) fields never queue and
 //     their transient state clears.
+//   · beforeSave (optional): runs once per batch BEFORE the POST, with the
+//     wire body. While it awaits the batch counts as in flight (the timer
+//     cannot re-fire; a commit meanwhile joins the NEXT batch). `false`
+//     DROPS the batch: its names revert to the server snapshot and go idle
+//     — no error, no toast (a guardrail the operator declined is not a
+//     failure). An object REPLACES the body. true/undefined proceeds.
 //
 // Shape: ALL machine state lives in ONE reducer (draft values, server
 // snapshot, per-field status, the pending batch, the in-flight flag) so every
@@ -168,6 +174,8 @@ export type AutosaveAction =
     | { type: 'SAVE_OK'; names: string[]; sent: Record<string, FieldValue>; server: FieldValues }
     /** Batch rejected: REVERT names to the snapshot, pin the server message. */
     | { type: 'SAVE_FAIL'; names: string[]; error: string }
+    /** beforeSave vetoed: REVERT names to the snapshot, status idle, no error. */
+    | { type: 'BATCH_DROP'; names: string[] }
     /** The ~1.5s saved flash ended. */
     | { type: 'FLASH_DONE'; name: string }
     /** The row prop changed (refetch/invalidate) or fields arrived late. */
@@ -366,6 +374,22 @@ export function autosaveReducer(state: AutosaveState, action: AutosaveAction): A
             return { ...state, draft, pending, fieldState, fieldError, inflight: false };
         }
 
+        case 'BATCH_DROP': {
+            const draft = { ...state.draft };
+            const fieldState = { ...state.fieldState };
+            const fieldError = { ...state.fieldError };
+            for (const n of action.names) {
+                // A field re-committed while beforeSave awaited belongs to the
+                // NEXT batch (SAVE_OK precedent) — the veto covers only what
+                // this batch carried.
+                if (n in state.pending) continue;
+                if (n in state.server) draft[n] = state.server[n]!;
+                fieldState[n] = 'idle';
+                fieldError[n] = null;
+            }
+            return { ...state, draft, fieldState, fieldError, inflight: false };
+        }
+
         case 'FLASH_DONE': {
             if (state.fieldState[action.name] !== 'saved') return state;
             return { ...state, fieldState: { ...state.fieldState, [action.name]: 'idle' } };
@@ -387,6 +411,83 @@ export function autosaveReducer(state: AutosaveState, action: AutosaveAction): A
     }
 }
 
+// ── The batch runner ──────────────────────────────────────────────────
+// Pure orchestration over the reducer — exported so the contract (veto /
+// amend / concurrent commit / no-hook parity) is unit-testable without a
+// DOM (scripts/verify-form-autosave.mjs). The hook binds it to its refs.
+
+export interface AutosaveBatchRunnerDeps<T> {
+    /** The state snapshot at fire time. */
+    state: AutosaveState;
+    /** Current options, captured once for this batch and its settlement. */
+    opts: () => Pick<UseFormAutosaveOptions<T>, 'fields' | 'row' | 'save' | 'beforeSave' | 'onSaved' | 'onSaveError'>;
+    dispatch: (action: AutosaveAction) => void;
+    /** Re-arm the batch window (drain anything committed mid-flight). */
+    armBatchTimer: () => void;
+    /** Start a field's saved flash. */
+    armFlashTimer: (name: string) => void;
+}
+
+/**
+ * Fire one batch from `state.pending`. Resolves when the batch has settled
+ * (saved, failed, or dropped); resolves immediately when nothing fires
+ * (in flight, or nothing pending).
+ */
+export function runAutosaveBatch<T>(deps: AutosaveBatchRunnerDeps<T>): Promise<void> {
+    const { state: s, opts, dispatch, armBatchTimer, armFlashTimer } = deps;
+    if (s.inflight) return Promise.resolve(); // completion re-arms the timer (serialize)
+    const names = Object.keys(s.pending);
+    if (names.length === 0) return Promise.resolve();
+    const sent: Record<string, FieldValue> = { ...s.pending };
+    const changes = expandDotted(sent);
+    // The approval, write target and callbacks belong to the same batch.
+    // Reading opts again after a gate can redirect an approved write to a
+    // different row/model rendered while the confirmation was open.
+    const batch = opts();
+    dispatch({ type: 'BATCH_START', names });
+
+    const post = (body: Record<string, unknown>): Promise<void> => batch.save(body).then(
+        (savedRow) => {
+            const server = serverValuesFor(batch.fields, savedRow);
+            dispatch({ type: 'SAVE_OK', names, sent, server });
+            for (const n of names) armFlashTimer(n);
+            batch.onSaved?.({ changes: body, fields: names, row: savedRow });
+            armBatchTimer(); // drain anything committed mid-flight
+        },
+        (err: unknown) => fail(body, err),
+    );
+    const fail = (body: Record<string, unknown>, err: unknown) => {
+        const error = err instanceof Error ? err : new Error('Save failed');
+        dispatch({ type: 'SAVE_FAIL', names, error: error.message });
+        batch.onSaveError?.({ changes: body, fields: names, error });
+        armBatchTimer();
+    };
+
+    const beforeSave = batch.beforeSave;
+    if (!beforeSave) return post(changes); // no hook: the pre-existing path, unchanged
+
+    // The gate. BATCH_START already flagged inflight, so the window cannot
+    // re-fire while this awaits and commits meanwhile queue the NEXT batch.
+    let verdict: Promise<boolean | void | Record<string, unknown>>;
+    try {
+        verdict = Promise.resolve(beforeSave({ changes, names, row: batch.row }));
+    } catch (err) {
+        verdict = Promise.reject(err);
+    }
+    return verdict.then(
+        (v) => {
+            if (v === false) {
+                dispatch({ type: 'BATCH_DROP', names });
+                armBatchTimer(); // a commit made during the await fires next
+                return;
+            }
+            const body = v !== null && typeof v === 'object' ? v : changes;
+            return post(body);
+        },
+        (err: unknown) => fail(changes, err),
+    );
+}
+
 // ── The hook ──────────────────────────────────────────────────────────
 
 export interface AutosaveBatchInfo {
@@ -396,6 +497,24 @@ export interface AutosaveBatchInfo {
     fields: string[];
 }
 
+export interface AutosaveBeforeSaveInfo<T> {
+    /** The wire body about to POST (dotted names expanded). */
+    changes: Record<string, unknown>;
+    /** Flat field names the batch carries (`permissions.manage_group`, …). */
+    names: string[];
+    /** The server row the batch edits. */
+    row: T;
+}
+
+/**
+ * Pre-save gate. `false` drops the batch (fields revert to server values,
+ * status → idle, no error toast); an object replaces `changes`; `true` /
+ * `undefined` proceeds. A thrown/rejected hook is a bug, not a veto — it is
+ * surfaced like a failed save (revert + pinned error + onSaveError).
+ */
+export type AutosaveBeforeSave<T> = (info: AutosaveBeforeSaveInfo<T>) =>
+    boolean | void | Record<string, unknown> | Promise<boolean | void | Record<string, unknown>>;
+
 export interface UseFormAutosaveOptions<T> {
     /** EVERY saveable field — flat fields plus every tab's fields. */
     fields: Field[];
@@ -403,6 +522,14 @@ export interface UseFormAutosaveOptions<T> {
     row: T;
     /** One batch POST. MUST reject on failure (defineModel useSave contract). */
     save: (changes: Record<string, unknown>) => Promise<T>;
+    /**
+     * Runs before a batch POSTs. Return false to drop the batch (fields
+     * revert to server values, status → idle, no error toast); return an
+     * object to replace `changes`; true/undefined to proceed. While it awaits
+     * the batch is in flight: the timer cannot re-fire and a commit meanwhile
+     * joins the NEXT batch.
+     */
+    beforeSave?: AutosaveBeforeSave<T>;
     /** Batch window after the last commit (web-mojo: 300). */
     debounceMs?: number;
     /** How long the 'saved' check shows before returning to idle. */
@@ -485,29 +612,13 @@ export function useFormAutosave<T>(opts: UseFormAutosaveOptions<T>): FormAutosav
 
     // ── the batch runner ──────────────────────────────────────────────
     const fireBatch = useCallback(() => {
-        const s = stateRef.current;
-        if (s.inflight) return; // completion re-arms the timer (serialize)
-        const names = Object.keys(s.pending);
-        if (names.length === 0) return;
-        const sent: Record<string, FieldValue> = { ...s.pending };
-        const changes = expandDotted(sent);
-        dispatch({ type: 'BATCH_START', names });
-
-        optsRef.current.save(changes).then(
-            (savedRow) => {
-                const server = serverValuesFor(optsRef.current.fields, savedRow);
-                dispatch({ type: 'SAVE_OK', names, sent, server });
-                for (const n of names) armFlashTimer(n);
-                optsRef.current.onSaved?.({ changes, fields: names, row: savedRow });
-                armBatchTimer(); // drain anything committed mid-flight
-            },
-            (err: unknown) => {
-                const error = err instanceof Error ? err : new Error('Save failed');
-                dispatch({ type: 'SAVE_FAIL', names, error: error.message });
-                optsRef.current.onSaveError?.({ changes, fields: names, error });
-                armBatchTimer();
-            },
-        );
+        void runAutosaveBatch<T>({
+            state: stateRef.current,
+            opts: () => optsRef.current,
+            dispatch,
+            armBatchTimer,
+            armFlashTimer,
+        });
     }, [armBatchTimer, armFlashTimer]);
     fireBatchRef.current = fireBatch;
 

package/src/ui/guardrail.tsx

@@ -0,0 +1,125 @@
+// Guardrail — the "are you sure, and here is WHY" stop in front of a change
+// that takes a tenant dark, moves money, or cannot be undone if made by
+// accident. One shape for every breaking knob so the operator learns to read
+// it: what happens the moment it lands, why that is dangerous (concrete
+// consequences, not adjectives), how to get back — and, for the sharpest
+// knobs, a typed literal before the button arms.
+//
+// Promoted from wmx-admin-v2 `src/lib/guardrail.tsx` (bc3e900) verbatim in
+// contract and markup so the app's copy keeps working when it swaps the
+// import. Built on the native-<dialog> `modal.open` stack, so it stacks
+// correctly over a formModal that is still open.
+//
+// Which stop to reach for:
+//   · `modal.confirm`    — reversible / low blast radius; a yes-no.
+//   · `ArmedButton`      — irreversible, needs no input, inline (row actions).
+//   · `confirmGuardrail` — anything that takes a tenant dark, moves money, or
+//                          can't be undone — the operator must read WHY.
+//
+// Usage — `if (!(await confirmGuardrail({...}))) return;` before the mutation.
+// The dialog resolves false on Escape / backdrop / Cancel, true only on the
+// armed confirm button.
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { modal } from './modal';
+
+export interface Guardrail {
+    /** Question form, naming the target: "Disable Alea for Club Axo?" */
+    title: string;
+    /** What happens the moment this lands — present tense, one or two sentences. */
+    effect: ReactNode;
+    /** Why it is dangerous — each item one concrete consequence. */
+    why: ReactNode[];
+    /** How to get back, or that you can't. */
+    undo?: ReactNode;
+    confirmText: string;
+    cancelText?: string;
+    /**
+     * Highest tier: the operator must type this literal (the brand name, a
+     * count, "DISABLE") before the confirm button arms. Compared trimmed and
+     * case-insensitively.
+     */
+    typeToConfirm?: string;
+    /** false = primary button + warn tint for a stop that is not destructive. Default true. */
+    danger?: boolean;
+}
+
+function GuardrailBody({ g, close }: { g: Guardrail; close: (v: boolean) => void }) {
+    const [typed, setTyped] = useState('');
+    const inputRef = useRef<HTMLInputElement>(null);
+    const needsTyping = Boolean(g.typeToConfirm);
+    const armed = !needsTyping || typed.trim().toLowerCase() === g.typeToConfirm!.trim().toLowerCase();
+    const danger = g.danger !== false;
+
+    useEffect(() => {
+        if (needsTyping) inputRef.current?.focus();
+    }, [needsTyping]);
+
+    return (
+        <div className={danger ? 'modal-pad guardrail' : 'modal-pad guardrail guardrail-warn'}>
+            <h2 className="modal-title">
+                <i className={`bi ${danger ? 'bi-exclamation-octagon-fill' : 'bi-exclamation-triangle-fill'} guardrail-icon`} /> {g.title}
+            </h2>
+            <div className="modal-message">
+                <p className="guardrail-effect">{g.effect}</p>
+                <div className="guardrail-why">
+                    <div className="guardrail-why-head">Why this is dangerous</div>
+                    <ul>
+                        {g.why.map((w, i) => <li key={i}>{w}</li>)}
+                    </ul>
+                </div>
+                {g.undo && (
+                    <p className="guardrail-undo"><i className="bi bi-arrow-counterclockwise" /> {g.undo}</p>
+                )}
+                {needsTyping && (
+                    <label className="guardrail-type">
+                        <span>Type <b>{g.typeToConfirm}</b> to confirm</span>
+                        <input
+                            ref={inputRef}
+                            className="input"
+                            value={typed}
+                            autoComplete="off"
+                            spellCheck={false}
+                            onChange={(e) => setTyped(e.target.value)}
+                            onKeyDown={(e) => { if (e.key === 'Enter' && armed) close(true); }}
+                        />
+                    </label>
+                )}
+            </div>
+            <div className="modal-actions">
+                <button type="button" className="btn" onClick={() => close(false)}>{g.cancelText ?? 'Cancel'}</button>
+                <button
+                    type="button"
+                    className={danger ? 'btn btn-danger' : 'btn btn-primary'}
+                    disabled={!armed}
+                    onClick={() => close(true)}
+                >
+                    {g.confirmText}
+                </button>
+            </div>
+        </div>
+    );
+}
+
+/** Open the guardrail and resolve true only when the operator confirms. */
+export function confirmGuardrail(g: Guardrail): Promise<boolean> {
+    return modal.open<boolean>((close) => <GuardrailBody g={g} close={close} />, { size: 'sm' })
+        .then((v) => v === true);
+}
+
+/**
+ * Diff helper for config-form saves: which of the watched keys changed
+ * between what the form was seeded with and what came back. Lets a save
+ * confirm ONLY the fields that break things (environment, currency codes…)
+ * and pass silently otherwise.
+ */
+export function changedKeys(
+    initial: Record<string, unknown>,
+    next: Record<string, unknown>,
+    watch: readonly string[],
+): string[] {
+    return watch.filter((k) => {
+        const a = initial[k]; const b = next[k];
+        const norm = (v: unknown) => (v == null || v === '' ? '' : String(v));
+        return norm(a) !== norm(b);
+    });
+}

package/src/ui/index.ts

@@ -9,6 +9,7 @@ export * from './RequiresGroup';
 export * from './menu-registry';
 export * from './SidebarNav';
 export * from './armed-button';
+export * from './guardrail';
 export * from './loading';
 export * from './CollectionMultiSelect';
 export * from './CollectionSelect';

package/src/ui/toast.tsx

@@ -18,7 +18,8 @@
 // Visual spec from web-mojo's toast.css (left accent bar, compact card,
 // bottom-right); idiom styles live in the app's theme/idioms.css — tokens
 // only, both themes.
-import { useSyncExternalStore } from 'react';
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
 
 type Level = 'success' | 'error' | 'info' | 'warning';
 
@@ -187,8 +188,50 @@ export function ToastHost() {
         (cb) => { listeners.add(cb); return () => listeners.delete(cb); },
         () => toasts,
     );
-    return (
-        <div className="toast-host" role="status" aria-live="polite">
+    // Keep one portal target so moving above a new modal preserves live cards.
+    const [host] = useState(() => typeof document === 'undefined' ? null : document.createElement('div'));
+    const visible = useRef(false);
+    visible.current = items.length > 0;
+    const syncHost = useRef<() => void>(() => {});
+    useLayoutEffect(() => {
+        if (!host) return;
+        host.className = 'toast-host';
+        host.setAttribute('role', 'status');
+        host.setAttribute('aria-live', 'polite');
+        const supportsPopover = typeof host.showPopover === 'function';
+        if (supportsPopover) host.setAttribute('popover', 'manual');
+        let dialogs: HTMLDialogElement[] = [];
+        const sync = (records: MutationRecord[] = []) => {
+            const open = Array.from(document.querySelectorAll('dialog')).filter(dialog => dialog.matches(':modal'));
+            dialogs = dialogs.filter(dialog => open.includes(dialog));
+            for (const dialog of open) if (!dialogs.includes(dialog)) dialogs.push(dialog);
+            // Opening order, not DOM order, determines the active native modal.
+            for (const record of records) {
+                if (record.type !== 'attributes' || record.oldValue !== null || !(record.target instanceof HTMLDialogElement) || !open.includes(record.target)) continue;
+                dialogs = [...dialogs.filter(dialog => dialog !== record.target), record.target];
+            }
+            const parent = dialogs.at(-1) ?? document.body;
+            const moved = host.parentElement !== parent;
+            if (supportsPopover && host.matches(':popover-open') && (moved || !visible.current)) host.hidePopover();
+            // A body-level popover paints above dialogs but remains inert.
+            // Modal-local ancestry is required for Undo/Cancel and keyboard use.
+            if (moved) parent.appendChild(host);
+            if (supportsPopover && visible.current && !host.matches(':popover-open')) host.showPopover();
+        };
+        syncHost.current = sync;
+        const observer = new MutationObserver(sync);
+        observer.observe(document.body, { subtree: true, childList: true, attributes: true, attributeFilter: ['open'], attributeOldValue: true });
+        sync();
+        return () => {
+            observer.disconnect();
+            syncHost.current = () => {};
+            if (supportsPopover && host.matches(':popover-open')) host.hidePopover();
+            host.remove();
+        };
+    }, [host]);
+    useLayoutEffect(() => { syncHost.current(); }, [items.length > 0]);
+    return host ? createPortal(
+        <>
             {items.map((t) => {
                 if (t.kind === 'basic') {
                     return (
@@ -214,6 +257,6 @@ export function ToastHost() {
                 }
                 return <ProgressCard key={t.id} t={t} />;
             })}
-        </div>
-    );
+        </>, host,
+    ) : null;
 }