portal-mojo 0.2.20 → 0.2.21

package/docs/admin-edge.md

@@ -1,210 +1,214 @@
-# Edge Admin
+# Edge Admin · Serving
 
 ```ts
 import {
     EDGE_ADMIN_SECTION, VhostsPage, VhostDetail, VhostWizard, openVhostWizard,
     UpstreamsPage, BlocklistPage, EdgeVhostModel, EdgeRouteModel,
     EdgeUpstreamModel, EdgeBlocklistModel, buildVhostPayload,
-} from 'portal-mojo/admin';
+} from 'portal-mojo/admin'; // also portal-mojo/admin/infrastructure
 ```
 
-The same names are on `portal-mojo/admin/infrastructure`.
-
-`EDGE_ADMIN_SECTION` contributes Infrastructure routes at `edge/vhosts` and
-`edge/upstreams` (or the same paths under an embedded `/system` mount). The
-fleet blocklist is a route of Network Security, at
-`security/network/edge-blocklist`. There are no record routes: a vhost opens in
-`modal.detail`.
-
-Consumer contract: django-mojo `mojo/apps/edge/`. The mock in
-`client/mock.ts` returns the same graphs and the same refusals, word for word
-where the server has words.
-
-## Permissions
-
-- Vhosts, routes, upstreams — view: `sys.view_dns | sys.manage_dns | sys.security`.
-- Vhosts, routes — change or delete: `sys.manage_dns | sys.security`.
-- Upstreams — switch on or off: `sys.manage_dns | sys.security`.
-- Upstreams — declare or retire: `me.is_superuser === true`. The server gate
-  is `require_platform_admin`, which also refuses API keys.
-- Blocklist — view: `sys.view_security | sys.manage_security | sys.security`
-  (`EDGE_BLOCKLIST_VIEW_PERMS`). This is wider than `SECURITY_VIEW_PERMS`: the
-  server lets `manage_security` view, and manage does not imply view on the
-  client, so the clause is spelled out.
-- Blocklist — change or delete: `sys.manage_security | sys.security`.
-
-A section gate and a route gate both apply. A security-only operator is denied
-every DNS-gated section, which is why the blocklist does not live under Edge.
-The blocklist has no group: a member-scoped grant and `?group=` open nothing.
-
-**House rows.** A vhost on a group-less domain is platform property. It never
-appears in a non-superuser's list, even with a global grant, and its detail,
-its routes and creating one are refused to everyone else. The vhost graphs
-carry `domain: basic`, which has no `group`, so house-ness cannot be read off a
-vhost row. The wizard's domain picker passes `group__isnull: false` for
-non-superusers so a house domain is never offered to someone who would be
-refused at Finish.
+`EDGE_ADMIN_SECTION` contributes Infrastructure routes `edge/vhosts` and
+`edge/upstreams`, relative to the standalone or embedded `/system` mount.
+Network Security owns `security/network/edge-blocklist`. Records open in
+native modals, not record routes. Consumer source: django-mojo `mojo/apps/edge/`;
+`client/mock.ts` mirrors its graphs and refusals, with wording limits below.
+
+## Permissions and ownership
+
+All clauses are global; section and route gates both apply.
+
+| Resource/action | Authority |
+|---|---|
+| Vhost, route, upstream view | `sys.view_dns OR sys.manage_dns OR sys.security` |
+| Vhost/route change or delete; upstream enabled switch | `sys.manage_dns OR sys.security` |
+| Upstream declare/retire | Literal `me.is_superuser`; server `require_platform_admin` also refuses API keys |
+| Blocklist view | `sys.view_security OR sys.manage_security OR sys.security` |
+| Blocklist change/delete | `sys.manage_security OR sys.security` |
+
+`EDGE_BLOCKLIST_VIEW_PERMS` deliberately includes `manage_security`: manage does
+not imply view in the client. Security-only operators cannot enter DNS-gated
+Edge, hence the separate blocklist route. Member grants and `?group=` do not
+open the fleet-wide blocklist.
+
+A vhost on a group-less domain is a **house row**: non-superusers cannot list,
+inspect or create it or its routes, even with global DNS grants. Vhost graphs'
+`domain: basic` omits group, so never infer ownership there. Non-superuser domain
+choices use `group__isnull: false`. Resolve the domain's own graph before offering
+enabled upstreams: `group=<owner>` includes owned and shared rows; platform domains
+use `group__isnull: true`. Unresolved ownership disables selection.
 
 ## Endpoints
 
-| Address | Verbs | Notes |
-|---|---|---|
-| `/api/edge/vhost` (+`/<id>`) | list, read, create, update, delete | `list` graph for tables, `default` for one row |
-| `/api/edge/route` (+`/<id>`) | list, read, create, update, delete | `site_api` vhosts only; filter `vhost` |
-| `/api/edge/upstream` (+`/<id>`) | list, read, update | update writes `is_enabled` only; no create, no delete |
-| `/api/edge/upstream/declare` | POST | `{name, kind, host+port \| socket_path, group?}`; platform administrators |
-| `/api/edge/upstream/retire` | POST | `{upstream}`; disables, keeps the row; platform administrators |
-| `/api/edge/blocklist` (+`/<id>`) | list, read, create, update, delete | fleet-wide |
-
-## The four kinds
-
-The wizard never shows a kind dropdown over one long form. Its first step is
-four cards in plain words; the following steps show only that shape's settings.
-
-| Kind | Card | Needs | May carry | Refuses |
-|---|---|---|---|---|
-| `api` | API host | `upstream` | `quiet_paths`, `serve_static` | `spa`, `redirect_to` |
-| `site` | Static site or SPA | — | `spa` | `upstream`, `quiet_paths`, `serve_static`, `redirect_to` |
-| `site_api` | Site + API paths | routes | `spa`, `serve_static`, `quiet_paths` | whole-host `upstream`, `redirect_to` |
-| `redirect` | Redirect | `redirect_to` | — | everything else |
-
-`buildVhostPayload(draft, { create })` is the one place a draft becomes a
-request. It sends each knob the chosen kind does not carry as its empty value,
-so a draft that visited another shape cannot leak that shape's settings, and
-an edit that changes kind clears what the old kind held. It never sends
-`mojosec_policy`. A vhost that carries an edge evidence policy therefore cannot
-change kind, or its single-page-app switch on a `site`, from here: the server
-requires the policy's response class to match and refuses, and its message is
-shown.
-
-Shared rules, each mirrored by a validator in `edge/models.ts`:
-
-- `label`: empty serves the bare domain, `*` the wildcard, otherwise one DNS
-  label. The address (`server_name`) is derived, never typed.
-- `body_size_mb`: whole number, 1 to 4096, default 50. Not offered for a
-  redirect.
-- `pool`: must be one the deployment declares (`EDGE_POOLS`, default
-  `["default"]`). The refusal names the declared set.
-- `domain`: set once. An edit shows it read-only and never sends it.
-- `redirect_to`: a host name. No scheme, path, port or wildcard.
-- A route prefix or quiet path starts with `/`, uses letters, digits, `.`,
-  `_`, `-` and `/`, and has no `//` or `..`. A route prefix cannot be `/`.
-
-## What is checked when
-
-The server checks most things on every save. Two things are checked **only
-when the row is enabled**:
-
-- the certificate belongs to the vhost's domain and covers its address;
-- no other enabled row has the same domain and label.
-
-So a disabled row may hold a certificate that does not cover it yet, and may
-share a name with a live row. That is how a replacement is staged: create it
-disabled, then disable the old one and enable the new one. The wizard warns
-when the chosen certificate does not cover the address (`certificateCovers`,
-which knows that a wildcard covers exactly one label and never the apex) and
-still lets the row be saved disabled.
-
-## The create order for `site_api`
-
-A quiet path on a `site_api` vhost must sit under one of its route prefixes,
-and the server reads those prefixes from the stored row. A create that carries
-quiet paths is therefore always refused with "none declared". The only order
-that works is:
-
-1. create the vhost, **disabled** and without quiet paths;
-2. create its routes, one at a time;
-3. save the vhost once more with the quiet paths and the enablement the user
-   chose.
-
-The wizard does exactly this. Step 3 always runs, so the enable-time checks
-happen at the end and a failure part-way never leaves a live vhost with no
-routes. If a step is refused the wizard stays open and says which step and
-what already exists. Finishing again continues from there: it never posts the
-vhost a second time and never repeats a route that landed.
-
-The server will store an enabled `site_api` vhost with no routes. The wizard
-does not: at least one valid route is required at the settings step and again
-at review.
-
-In edit mode routes are read-only, with a pointer to the detail view, which
-owns adding, changing and deleting them. Changing a `site_api` vhost to
-another kind while it has routes is blocked with the count; the server refuses
-it too. Until the stored routes have been read, or if that read fails, the
-wizard does not judge quiet paths against them and leaves that to the server.
-
-## Vhost detail
-
-The detail follows the admin modal contract (`admin-modals.md`). The header
-switch enables and disables. Edit and Delete are in the header menu, shown
-only with the manage grant. Delete asks for confirmation, names the address,
-says its routes go with it, and points at Disable as the choice that can be
-undone. A refused enable shows the server's message in the overview. Routes
-are content: the Routes section lists them and owns add, change and delete.
-
-## Upstreams
-
-An upstream is a destination a vhost may proxy to. Only `is_enabled` can be
-written on one; its name and destination are fixed when it is declared. The
-list shows the active group's upstreams and the shared ones. Retiring disables
-the row and keeps it: vhosts and routes that reach it stop being served and
-are not repointed. The retire control names that consequence before it acts.
-The wizard's upstream pickers list enabled upstreams only.
-
-## Blocklist
-
-An entry matches an IP network or a user-agent pattern, in one of four modes:
-`log` (recorded, still served — the default), `enforce` (refused), `allow` (an
-exemption) and `off`. Create an entry in `log`, watch the edge watch log for
-it, then switch it to `enforce`. A change reaches the fleet in about ten
-minutes.
-
-An `ip` value is stored as its network: `10.1.2.3/8` is saved as `10.0.0.0/8`.
-The editor shows the saved value from the response.
-
-## Not built here
-
-- **Claim-reserved.** The plan for this page asked for a superuser control to
-  claim a reserved name. django-mojo removed the reserved-name mechanism, its
-  field and its action (commit `bc2c57b1`, in every release since v1.7.1), so
-  there is nothing for such a control to call.
-- **`mojosec_policy`.** Shown read-only on the vhost detail. It is set by the
-  platform and never sent from here.
-- **Web apps, releases and alias addresses.** An alias address appears in the
-  vhost list like any other row; `alias_of` is in no graph, so it cannot be
-  told apart, and a refused edit shows the server's message.
-
-## Pitfalls
-
-- Do not send `quiet_paths` on a `site_api` create. See the create order.
-- Do not treat a saved, enabled row as proof the certificate covers it from
-  the client check alone; the server's answer on save is the proof.
-- The mock's messages for database uniqueness (a second enabled vhost on one
-  name, a repeated route prefix, a repeated blocklist value, a repeated
-  upstream name) are the mock's own words. The server reports these from a
-  database constraint, and its wording was not measured.
-- The server parses a blocklist address with Python's `ipaddress` and compiles
-  a user-agent pattern with Python's `re`, and the mock follows Python, not
-  JavaScript: `010.1.2.3` and `\q` are refused, `10.0.0.0/255.0.0.0`,
-  `(?i)bot` and `a*+` are accepted. The reason after "does not compile" is the
-  mock's own wording. The editor's own check is only a first pass and never
-  compiles the pattern; the server's answer on save is the verdict.
-- A vhost update that names an upstream or certificate that does not exist is
-  refused by the mock with the same words as a missing one. The server's
-  wording for an unknown id was not measured.
-- The declare-upstream dialog and the blocklist editor refuse Escape and the
-  backdrop while their write is in flight, and the editor's save and delete
-  share one pending state. `npm run verify:admin-edge` holds each write open
-  and checks this.
+| `/api/edge/…` | Contract |
+|---|---|
+| `vhost`, `vhost/<id>` | list/read/create/update/delete; table graph `list`, record graph `default` |
+| `route`, `route/<id>` | list/read/create/update/delete; `site_api` only; filter `vhost` |
+| `upstream`, `upstream/<id>` | list/read/update `is_enabled`; no collection create/delete |
+| `upstream/declare` | POST `{name, kind, host+port OR socket_path, group?}` |
+| `upstream/retire` | POST `{upstream}`; disables and retains row |
+| `blocklist`, `blocklist/<id>` | list/read/create/update/delete; fleet-wide |
+
+Refused saves reject at the one client boundary. Public save/delete helpers
+accept an optional `beforeWrite` guard, invoked before **every** fresh-auth attempt.
+
+## Serving tasks
+
+The lean table shows hostname/domain, type and enabled intent. Pool and timestamps
+belong in inspection. The Domain picker writes URL filter state; search supports
+label/type/pool, not derived full hostnames. Persisted key remains
+`admin:edge:vhosts`; public `Vhost*` exports and `/edge/vhosts` remain compatible.
+
+- **Add hostname:** Hostname → Certificate → Review. Name, type and destination
+  belong to one Hostname task. Compact type choice,
+  only relevant destination controls, visible action footer. Other settings holds
+  pool/body/static/quiet paths without an accordion. Success opens the saved row.
+- **Edit:** Hostname / Certificate / Settings share one controlled draft.
+  Validation selects the relevant tab and focuses the invalid input. Saving retains
+  the active panel. Domain is immutable. Info-icon popovers carry secondary help.
+- **Inspect:** Overview / Routes / Settings; Routes only for Site + API.
+  Overview shows actual redirect/API destination first, followed by the certificate
+  name, stored status/expiry and direct Change certificate action. Settings holds other knobs, timestamps and
+  read-only platform policy. Header owns enable/disable, Edit and Delete.
+- **Routes:** paginated local table, focused Add/Edit dialogs and explicit removal
+  confirmation. Before rename/removal, inspect current quiet paths and complete
+  bounded routes. Block orphaning a quiet path and identify what to repair in
+  Settings first; no atomic multi-row operation is implied.
+
+Styles are scoped to these surfaces; shared Tabs/DetailView and Dashboard behavior
+are unchanged. See [presentation QA](admin-presentation.md).
+
+## Kinds, payloads and validation
+
+| Kind | Required | Supported options | Refused |
+|---|---|---|---|
+| `api` | `upstream` | quiet paths, static files | SPA, redirect |
+| `site` | — | SPA | upstream, quiet paths, static, redirect |
+| `site_api` | explicit routes on create | SPA, quiet paths, static | whole-host upstream, redirect |
+| `redirect` | `redirect_to` | — | other kind-specific knobs |
+
+`buildVhostPayload(draft, {create})` allowlists the chosen kind and sends empty
+values for its unsupported knobs, clearing values from a former kind. It never
+sends `mojosec_policy`. The server can refuse kind/SPA changes that conflict with
+that policy's response class; show its refusal.
+
+Client mirrors in `edge/models.ts`; server remains authoritative:
+
+- Label: empty apex, `*` wildcard or one lowercase DNS label. Derive `server_name`.
+- Body: integer 1–4096 MB, default 50; absent for redirect.
+- Pool: deployment-declared `EDGE_POOLS`, default `["default"]`; no client catalog.
+- Redirect: hostname only; no scheme/path/port/wildcard.
+- Route/quiet path: leading `/`, letters/digits/`._-/`, at most 128 characters,
+  no `//` or `..` segment. A route cannot be `/`.
+
+Only enabled rows require a certificate belonging to the domain and covering the
+address, and a unique enabled domain/label. Stage a replacement disabled, disable
+the old row, then enable the replacement. `certificateCovers` knows a wildcard
+covers one label and never the apex. Coverage stays Unknown until the full
+certificate graph (including SANs) is read; disabled staging remains available.
+
+## Staging and uncertain writes
+
+`site_api` quiet paths require stored route prefixes, so create in this order:
+
+1. Vhost disabled, without quiet paths.
+2. Routes sequentially.
+3. Final vhost save with quiet paths and chosen enabled intent; always perform this
+   step so enable-time validation runs last.
+
+The wizard requires at least one valid create route, though the server accepts
+route-less enabled rows. Edits and Site → Site + API conversion may remain
+route-less; author routes in detail. Existing routes block conversion away from
+Site + API. Unread routes defer quiet-path validation to the server.
+
+Retain acknowledged steps on explicit refusals. Transport loss, malformed receipts
+and 5xx may follow committed writes and stay **unconfirmed**, never “refused” or
+“still disabled”. An unacknowledged create cannot replay: close and inspect Serving.
+An acknowledged partial create offers **Inspect saved hostname**.
+
+**Observe outcome** reads only. Route continuation requires the matching stored
+prefix/upstream; absence stays blocked. Edit/final-save observation compares the
+exact normalized submitted payload, including FK IDs and arrays; unchanged or
+conflicting fields retain the guard and show differences. Only an exact match
+clears it. Continuing requires explicit **Add hostname** or **Save changes**;
+observation never automatically replays a mutation.
+
+Detail edits, route writes, enablement and deletion serialize through one pending
+state. Lock Escape/backdrop/X during preflight and writes. Before each write and
+fresh-auth attempt, check original session/current permission; owner disposal
+closes nested dialogs and prevents later staged writes. Closing cannot cancel an
+already submitted server operation or prove its outcome.
+
+Route safety reads paginate to at most 2,000 rows and reject changed counts,
+duplicate IDs, incomplete pages and excess inventory. Same-count concurrent edits
+cannot all be detected; there is no atomic snapshot guarantee.
+
+Delete confirms the address, stopped serving and route cascade, warns linked sites
+can stop serving, retains domain/certificate and offers Disable as reversible.
+
+## Serving evidence
+
+Read-only `ServingReadiness.tsx`/`serving-data.ts` keep positive projections outside
+Query. `GET /api/account/admin/bootstrap` requires an authenticated matching global
+identity with `view_admin OR manage_users OR manage_settings OR admin` (literal
+superuser bypass); DNS grants alone never request it. Retain only matching user
+ID/superuser, setup capability and edge available/HTTP/issuance fields.
+
+`GET /api/account/admin/setup/readiness?section=hosting_vhosts` additionally requires
+successful same-identity bootstrap with setup capability and literal superuser in
+both Me and bootstrap. Server still refuses key-backed/noninteractive sessions;
+client invents no provenance flag. Schema 1 validates status/time/count/coverage,
+keeps the selected section only, caps checks at 64 and scalar details at 16 keys.
+
+The unboxed summary sits within the page header and keeps timestamp and
+partial-report warning visible. DNS-only sessions that cannot request bootstrap
+see no global checks summary; admitted observation failures remain visible. Check
+details holds technical evidence. HTTP is a file-rendering setting; DNS-01 is an
+issuance method. Checks cover enabled rows' domain/certificate status, **not** live
+serving, expiry/coverage/material installation, fleet convergence/nodes/generation.
+An omitted hostname has no individual verdict. Enabled/saved is configuration intent.
+
+Errors, denied attempted reads, old-backend 404s and malformed responses show Unavailable or
+Unknown. Failed refresh clears old evidence. UID/session revision fence reads;
+same-session loss of admission/bootstrap/superuser/setup authority disposes report
+modals. Reads occur only while mounted/admitted, without polling; configuration
+changes refresh the panel.
+
+## Upstreams and blocklist
+
+An upstream's name/destination are fixed at declaration; only enabled is editable.
+Lists include owned and shared rows. Retiring disables and retains it: reaching
+vhosts/routes stop serving and are not repointed. Confirm that consequence.
+
+Blocklist modes: `log` (default, still served), `enforce` (refused), `allow`
+(exemption), `off` (retained inactive). Start in log, inspect the watch log, then
+enforce. Propagation takes about ten minutes. Save IPs as canonical networks:
+`10.1.2.3/8` becomes `10.0.0.0/8`; show the returned value. Declare and blocklist
+editors guard native dismissal; blocklist save/delete share pending state.
+
+## Boundaries and pitfalls
+
+- No claim-reserved action: django-mojo removed it in `bc2c57b1` (v1.7.1 onward).
+  Platform-owned `mojosec_policy` is read-only; never send it.
+- No owning-WebApp/alias graph, pool catalog, route-disable flag, atomic multi-route
+  write or per-host live readiness. Aliases look like other rows; show refusals.
+- Mock uniqueness wording (enabled hostname, route prefix, blocklist value,
+  upstream name) and missing-relation wording were not measured on the server.
+- Blocklist parsing follows Python `ipaddress`/`re`, not JS RegExp: reject
+  `010.1.2.3` and `\q`; accept `10.0.0.0/255.0.0.0`, `(?i)bot`, `a*+`.
+  Compilation reason text is mock-specific; local validation is only a first pass.
+- Client certificate checks are advisory; only the server validates a save.
 
 ## Themes and showcase
 
-Styles live in `src/styles/components/admin-edge.css` and ship in
-`portal-mojo/styles.css`; the app declares the tokens. They are built from
-tokens only, so both themes render from one sheet. The showcase still carries
-its own identical copy until it adopts the package stylesheet. The showcase
-demo (Develop → Components → Admin → Edge) runs the shipped pages against the
-mock under five identities: platform administrator, DNS manager, DNS viewer,
-security manager and security viewer.
-
-`npm run verify:admin-edge` is the executable contract.
+Canonical token-only `src/styles/components/admin-edge.css` ships through
+`portal-mojo/styles.css`, imported by Admin and Showcase. Demo: Components → Admin
+→ Edge, under platform administrator, DNS manager/viewer and security manager/viewer.
+Verify both themes, desktop/390px, opened dialogs, keyboard/help, busy and error states.
+
+Contracts: `npm run verify:admin-edge` (API plus held dialog writes),
+`node scripts/verify-admin-serving-mounted.mjs` (all shapes, staging, draft/focus,
+conversion, partial inspection, uncertainty, route guards/session races),
+`node scripts/verify-admin-serving-mounted-evidence.mjs` (DTO bounds, exact gates,
+unknown evidence, failed refresh, auth/permission replacement). Mounted tests do
+not establish native layout; actual browser QA remains required.

package/docs/admin-geolocation.md

@@ -0,0 +1,100 @@
+# GeoLocation provider setup
+
+`GeoLocationPage` (`portal-mojo/admin/operations`) is the global Operations →
+GeoLocation surface. GeoIP Cache inspects IPs; Fleet Configuration applies
+published settings. Dashboard is unchanged. Hosts may override the mount-derived Fleet link with
+`fleetConfigurationPath`; Showcase opens the actual Fleet Configuration page with a return link.
+
+Admission requires literal `is_superuser === true` and a current interactive
+session. The backend also rejects key-backed sessions, requires same-origin
+POSTs and authentication within 600 seconds. Global/group grants do not replace
+these checks. `usePrivateOperator` remounts on session change, aborts requests and
+owned dialogs, and rechecks authority before sending and accepting responses.
+
+## Tasks
+
+Primary, fallback and ordered additional providers form one visible configuration task,
+with add, remove and move controls. MojoVerify credentials and threat sharing sit
+below the chain. One retained draft and Save/Discard footer cover the form; there
+is no tab navigation for parts of the same task. The uncontrolled password element
+stays mounted while editing, and shared Tabs is unchanged.
+
+MojoVerify always uses `https://api.mojoverify.com`; no URL control is shown.
+Older origins remain readable, but this page stages the hosted URL and warns
+that switching requires a replacement key. Provider names are human-readable;
+unknown configured identifiers are retained. New additional rows exclude primary,
+fallback and existing rows. Runtime deduplicates the chain; existing overlaps are
+not silently rewritten. Non-Mojo credentials are configured outside this endpoint.
+The server's values are authoritative: setup defaults differ from runtime defaults.
+
+No key shows **Add key**; a configured key shows **Replace key** and **Remove
+key**. Test key sits with the credential. Blank replacement preserves the stored
+key; confirmed removal is staged until Save changes and does not revoke remotely.
+Save/Discard reflect actual draft changes. Refresh and the page-owned Open Fleet Configuration link confirm before discarding an
+unsaved draft. Keep editing preserves both provider selections and the entered key;
+explicit departure wipes the key before navigation. An in-flight operation cannot
+be interrupted through that link. Info popovers hold secondary explanations; Configuration information
+opens a focused native dialog for revision and publication facts. No disclosure
+sections or sidebar modal are used.
+
+Last stored-key check shows its historical outcome and timestamp separately from
+the draft result. Pending activation and Open Fleet Configuration remain visible.
+A false pending flag concerns only this request node, never proves fleet health.
+
+## Private protocol
+
+`readGeoLocation()` positively projects only `provider_setup` from schema-v1
+`/api/account/admin/settings`. Catalog, SMS, unknown fields and raw credentials
+are discarded. Form state is imperative, outside Query/Mutation caches.
+
+`buildGeoPayload(action, configuration_revision, draft, keyEdit)` sends exactly
+`{action,topic:'geoip',providers:{expected_revision,geoip}}`. The revision is sent
+even when null. The five static keys are primary, fallback, additional, Mojo URL
+and sync. Untouched/blank replacement omits credentials; nonempty replacement
+adds `GEOIP_API_KEY_MOJO`; confirmed removal adds `clear_api_key:true`.
+Additional providers are unique and ordered, at most 16. Identifiers match
+`^[a-z][a-z0-9_-]{0,31}$`. HTTPS origins permit no credentials, path, query,
+fragment or alternate port (443 allowed); keys are at most 4096 characters.
+
+Secrets stay only in the password DOM and short-lived request objects, whose
+raw key is deleted in `finally`. They never enter React/Query/Mutation state,
+URLs, storage, logs or mock observations. Editing retains the element and candidate;
+Save attempts, explicit discard, fresh-auth refusal, session change and unmount
+clear it. A stable ref callback wipes the password element before detachment;
+removing the DOM node alone is insufficient. Writes are single-flight. A 440 invokes fresh authentication without
+replaying; Refresh and a deliberate retry are required. Stale revisions
+(400 “changed; reload before publishing”, or 409), unreadable state and uncertain
+saves require authoritative Refresh before another write.
+
+Test verifies **only MojoVerify credentials**, regardless of primary. It requires
+the five delegated descriptor keys but not Fleet bucket/object/KMS/restart
+availability; Save requires the publishing plane. Sharing requires the remote
+key's `geoip_sync` permission. The current backend also verifies Mojo on every
+Save except explicit removal: selecting another primary does not enable an
+independent no-Mojo setup. This page does not invent provider-chain testing,
+other-provider key editing, provisioning, revocation or an Apply endpoint.
+
+A draft-key test does not rewrite stored verification. The backend's stored-test
+predicate is no replacement plus the node-loaded origin and sync value; chain
+changes do not affect it. Tests reread stored evidence without rebasing the
+draft's revision. Revision changes or lost normalization authority block retry;
+publishing-only unavailability does not block diagnostics. Loaded/desired origin
+drift can prevent stored-key reuse until Fleet apply or explicit replacement.
+
+Save rereads authoritative configuration. `published:true` means static
+publication with restart pending; `unchanged:true` can still mean the database
+credential changed. Neither result proves activation. Failed, stale and uncertain
+requests keep errors actionable and never become successful saves.
+
+## Verification
+
+`geo-provider-mock.ts` supplies isolated safe observations (action, key action,
+stored-test predicate, expected revision), with no submitted key retained.
+Scenarios include no-key setup, real registry names, unknown/empty registry,
+publishing unavailable, stale/fresh-auth/uncertain outcomes and loaded-origin drift.
+Showcase's GeoLocation demo mounts the actual page. Run
+`npm run verify:admin-geolocation` and `npm run verify:admin-geolocation-mounted`;
+JSDOM behavior does not establish native focus or layout. Inspect both apps,
+light/dark, desktop/390px, opened dialogs and error recovery per
+[Admin presentation](admin-presentation.md). The scoped stylesheet is included
+through `portal-mojo/styles.css`.