portal-mojo 0.1.0

package/docs/admin-devices-geoip.md

@@ -0,0 +1,284 @@
+# Admin: devices, login locations & GeoIP
+
+```ts
+import {
+    // sections (registered in ADMIN_SECTIONS — no app wiring needed)
+    DEVICE_INTEL_ADMIN_SECTION, GEOIP_ADMIN_SECTION,
+    // pages
+    UserDevicesPage, LoginLocationsPage, GeoIpCachePage,
+    // the map binding
+    LoginLocationMap,
+    // KISS detail modals (#1425)
+    showUserDeviceDetail, showUserDeviceDetailByDuid,
+    showUserDeviceLocationDetail, showLoginEventDetail,
+    showGeoIpDossier, showGeoIpDossierForAddress,
+    // models — ONE defineModel per endpoint, package-wide
+    UserDeviceModel, UserDeviceLocationModel, LoginEventModel, GeoLocatedIPModel,
+    // permission clauses
+    USER_DEVICE_VIEW_PERMS, DEVICE_LOCATION_VIEW_PERMS,
+    LOGIN_EVENT_VIEW_PERMS, LOGIN_SUMMARY_PERMS,
+    GEOIP_VIEW_PERMS, GEOIP_MANAGE_PERMS,
+    // enforcement + presentation helpers
+    blockActive, whitelistActive, blockExpired, whitelistExpired,
+    threatTone, riskScoreOf, countryFlag, THREAT_LEVEL_ORDER,
+    loginRiskTone, LOGIN_RISK_LEGEND,
+    deviceIcon, browserLabel, osLabel, deviceLabel, daysActive, presenceOf,
+    // data hooks
+    useLoginLocationSummary, useLoginLocationList,
+    useUserDeviceSessions, useDeviceSiblings,
+    useGeoIpByAddress, useGeoIpRawRecord, lookupGeoIp,
+    geoIpSafeExporter, sanitizeGeoIpRow,
+} from 'portal-mojo/admin';
+```
+
+Account-security triage: who logged in from a new country, what is this IP,
+and is this device shared across accounts. Demo: showcase → Admin →
+**Devices, logins & GeoIP**. Styles:
+`apps/{portal,showcase}/src/theme/admin-devices.css` (byte-identical).
+
+## Sections
+
+Two siblings under the **Security** navigation group, beside Bouncer — so the
+PRE-auth (`BouncerDevice.muid`) and POST-auth (`UserDevice.muid`) views of the
+same physical browser sit next to each other.
+
+| Section | id / basePath | Routes |
+|---|---|---|
+| Devices & Logins | `device-intel` / `security/devices` | `user-devices` · `login-locations` |
+| IP Intelligence | `geoip` / `security/geoip` | `cache` |
+
+All three surfaces are fleet-wide and **groupless** — `GeoLocatedIP` has no
+group FK at all, and the device/login lists are only global with a `sys.`
+grant. The *user-scoped* views stay inside `UserDetail`'s Devices and Logins
+sections, which this module extends rather than forks.
+
+`#1287`'s network-security pages (Blocked IPs, firewall log, IP sets,
+geofencing) live in their OWN section at `security/network`; this module
+reserves no space for them and exposes no extension seam. It does export
+everything they import.
+
+## Permissions
+
+Every clause is `sys.`-pinned, so an active-member grant can never satisfy it.
+A permission-disabled query passes `enabled: false` — a denied surface issues
+**no** request.
+
+| Constant | Value | Backend source |
+|---|---|---|
+| `USER_DEVICE_VIEW_PERMS` | `sys.manage_users`, `sys.users` | `UserDevice.VIEW_PERMS` minus `owner` |
+| `DEVICE_LOCATION_VIEW_PERMS` | `sys.manage_users`, `sys.users` | URL decorator ∩ `UserDeviceLocation.VIEW_PERMS` |
+| `LOGIN_EVENT_VIEW_PERMS` | `sys.manage_users`, `sys.security`, `sys.users` | `UserLoginEvent.VIEW_PERMS` minus `owner` |
+| `LOGIN_SUMMARY_PERMS` | `sys.manage_users`, `sys.security`, `sys.users` | `@requires_global_perms` on `/summary` + `/user` |
+| `GEOIP_VIEW_PERMS` | `sys.manage_users`, `sys.view_security`, `sys.manage_security`, `sys.security`, `sys.users` | `GeoLocatedIP.VIEW_PERMS` |
+| `GEOIP_MANAGE_PERMS` | `sys.manage_users`, `sys.manage_security`, `sys.security` | `GeoLocatedIP.SAVE_PERMS` |
+
+**`sys.manage_devices` is deliberately absent everywhere.** It passes the
+`@requires_global_perms` decorator on `/user/device/location` and
+`/user/device/lookup`, then fails the *model's* `VIEW_PERMS`
+(`manage_users | users`). Alone it opens nothing, so offering it as an
+affordance would promise access the server refuses.
+
+`UserDevice` and `UserLoginEvent` both carry `owner` in `VIEW_PERMS`: without
+a global grant those endpoints return only the caller's own rows. The admin
+pages are gated so that is never what an operator sees; the mock reproduces it
+so the verifier can assert it.
+
+## Endpoints
+
+| Endpoint | Gate | Notes |
+|---|---|---|
+| `GET /api/user/device` `(+/<pk>)` | model `VIEW_PERMS` incl. `owner` | graphs `default` · `basic` · `locations` · `sessions` |
+| `GET /api/user/device/lookup?duid=` | `@requires_global_perms(manage_users, manage_devices, users)` | cross-tenant; `on_rest_get` does not re-gate |
+| `GET /api/user/device/location` `(+/<pk>)` | URL decorator **and** model `VIEW_PERMS` | |
+| `GET /api/account/logins` `(+/<pk>)` | model `VIEW_PERMS` incl. `owner` | `CAN_CREATE/UPDATE/DELETE` all False |
+| `GET /api/account/logins/summary` | `@requires_global_perms(manage_users, security, users)` | country aggregation |
+| `GET /api/account/logins/user?user_id=` | same, `@requires_params('user_id')` | per-user aggregation |
+| `GET /api/system/geoip` `(+/<pk>)` | `GeoLocatedIP.VIEW_PERMS` / `SAVE_PERMS` | graphs `default` · `basic` · `detailed` · `federation` |
+| `GET /api/system/geoip/lookup?ip=` | `@requires_auth()` only, rate-limited 30/ip | see the graph downgrade below |
+
+**No model here declares `CAN_DELETE`,** and `rest.py` defaults it to False.
+There is no delete path for a device, a device location, a login event or a
+GeoIP record — the source's "Forget device", "Delete record" and "Delete
+Location Record" items could never have worked.
+
+## Model field shapes
+
+`UserDeviceRow` is the `default` graph. It has **no** `is_trusted` and **no**
+`is_blocked` — web-mojo's active toggle, "Mark trusted/untrusted" kebab item,
+Trusted/Blocked chips and trust timeline row all wrote a field the model never
+had.
+
+`UserDeviceSessionsRow` is the `sessions` graph, keyed separately in the query
+cache (`[endpoint, 'one', id, {graph:'sessions'}]`) so a sparse `default` row
+cannot satisfy it. Its three `extra` properties are real:
+
+- `bouncer_device` — the pre-auth `BouncerDevice` for this `muid`.
+- `active_sessions[]` — 24h of `BouncerSignal` grouped by `msid`, each with a
+  per-`mtab` breakdown.
+- `recent_locations[]` — the last ten `UserDeviceLocation` rows, flattened.
+
+`LoginEventRow` has **no** `event_type`. `GeoLocatedIPRow` has **no**
+`reverse_dns`, **no** `ip_version` and **no** `metadata`, and its `provider`
+and `data` fields are excluded from the `default` graph.
+
+## `LoginLocationMap`
+
+```tsx
+<LoginLocationMap
+    userId={user.id}          // scoped → /account/logins/user; omit → /summary
+    height={360}
+    drStart="2026-07-07" drEnd="2026-08-06"   // YYYY-MM-DD, see the two wires
+    defaultMode="summary"     // 'summary' | 'list'
+    showModeToggle
+    enabled={can}             // false ⇒ no request at all
+    onCountrySelect={(cc) => …}
+    onOpenLogin={(id) => …}
+    onOpenUser={(id) => …}    // list mode, global scope only
+/>
+```
+
+Rendering belongs entirely to [`WorldMap`](worldmap.md) (#1426). One import
+line — `from 'portal-mojo/charts'` — is the whole coupling surface, so
+reconciling with the map component touches exactly one file. No projection,
+SVG, marker geometry or colour ramp lives here.
+
+- **Summary mode** — one sized marker per country, or per region after a
+  drill-down. Position comes from `COUNTRY_CENTROIDS` first and the server's
+  `Avg(latitude)`/`Avg(longitude)` only as a fallback: for a country spanning
+  the antimeridian that average lands in the wrong ocean. Region rows have no
+  centroid and always use the average.
+- **List mode** — one dot per login, bounded at 500, coloured by
+  `loginRiskTone(row)`.
+- **Drill-down** is *double-click*, on country markers, in summary mode only.
+  A single click fires `onCountrySelect` after WorldMap's 250 ms
+  double-click-cancellation window — that quarter-second delay is by design.
+- **Coastlines come from `useWorldLand()`.** The checked-in
+  public-domain Natural Earth 110m outlines, no CDN and no tile server (see
+  `worldmap.md` → "The `land` seam"). The hook loads them in a separate chunk,
+  so pages without a map never carry the geometry. Rendering
+  correctly *without* it stays a hard requirement: drop the prop and the ocean +
+  graticule fallback still carries the markers, legend, tooltips, drill bar and
+  status line.
+
+### `loginRiskTone` — and the helper that was deleted
+
+`loginRiskTone(row)` reads fields the wire actually sends: `is_new_country` →
+`bad`, `is_new_region` → `warn`, otherwise `ok`.
+
+It replaced `loginEventTone(eventType)`, which `portal-mojo/charts` briefly
+exported after being ported from web-mojo. That helper mapped a login
+event-type vocabulary (`success_login`, `failed_login`, `suspicious`, …) — and
+**`UserLoginEvent` has never had an `event_type` field**, so a real row returned
+`'mute'` every time. That is precisely the web-mojo bug where every dot on the
+login map rendered grey.
+
+It was **removed from the package 2026-08-06** rather than kept beside this one:
+a plausible-looking name that silently greys out every marker is a trap, and
+there is no series in django-mojo that carries an event type for it to be
+correct about. `verify-worldmap.mjs` asserts both old names stay gone.
+
+## The two different date wires
+
+They are not interchangeable, and mixing them silently returns everything.
+
+| Endpoint | Wire | Format |
+|---|---|---|
+| `/api/account/logins` (list) | `dr_field` + `dr_start` + `dr_end` | always name `dr_field` explicitly |
+| `/summary` and `/user` | `dr_start` + `dr_end` only | `YYYY-MM-DD`, parsed by `dates.parse` |
+
+## Backend traps encoded here
+
+- **`region=false` is truthy.** `login_event.py` reads
+  `request.DATA.get('region')` with no string coercion, so the *string*
+  `"false"` drills. `region=1` is sent only while drilling, never `region=false`.
+- **`user_id` must parse as an int** on `/logins/user`, or the endpoint
+  answers `{status: false, code: 400}`.
+- **`country_code` must match `^[A-Z]{2,3}$`** uppercase or it is silently
+  ignored — an invalid code falls back to the country branch rather than erroring.
+- **The region drill caps at 500 rows** (`MAX_REGION_RESULTS`).
+- **`/summary` excludes null and empty `country_code`,** and private-range
+  logins carry no coordinates — so those logins are invisible on the map *by
+  construction*. The status line says so; the Logins tab is where they appear.
+- **The embedded `user_device` graph is `basic` and carries no `id`.**
+  Cross-links from a location or login row resolve the device by `duid`
+  (`showUserDeviceDetailByDuid`).
+- **`_param_is_true`**: query params arrive verbatim, so `auto_refresh=false`
+  would be truthy read naively. `lookupGeoIp` sends `1`/`0`.
+
+## Enforcement expiry is STATE
+
+`GeoLocatedIP` exposes `block_active` and `whitelist_active` as Python
+properties, but they are serialized only on the `basic` graph — the `default`
+graph carries the raw booleans. `blockActive(row)` / `whitelistActive(row)`
+mirror the model exactly:
+
+- a whitelist **wins** over a block;
+- a `blocked_until` in the past means **not blocked**;
+- a `whitelisted_until` in the past means **not whitelisted**.
+
+`blockExpired` / `whitelistExpired` surface the lapsed-but-still-flagged state
+as its own badge. web-mojo rendered raw `is_blocked`, so an expired block
+still read "Blocked" and a whitelisted-but-flagged IP read blocked when it was
+not.
+
+`block()` on the backend always escalates `threat_level` to at least `high`
+and increments `block_count`; whitelisting clears an active block. The UI
+re-reads the row from the action response rather than optimistically toggling,
+because the backend block is idempotent and race-safe.
+
+## Scrubbing rules
+
+1. **The raw provider blob never enters the Query cache.** `sanitizeGeoIpRow`
+   deletes `data` before any list/detail/save write and runs the shared
+   `sanitizeSecurityValue` over the rest.
+2. **The only reader of `graph=detailed`** is `useGeoIpRawRecord` — an
+   explicit, `GEOIP_MANAGE_PERMS`-gated, `gcTime: 0` / `staleTime: 0` fetch
+   whose payload is sanitized and length-bounded before it is returned. It is
+   behind a "Show raw provider record" reveal that is collapsed by default.
+3. **Exports go through `geoIpSafeExporter`** (`createSafeExporter`) with a
+   declared field projection, so a crafted `graph` param cannot smuggle
+   `data` or `provider` into a CSV.
+4. **Inspecting an IP costs no provider call.** `showGeoIpDossierForAddress`
+   resolves through `?ip_address=` on the cache list — read-only, unmetered.
+   `/system/geoip/lookup` CREATES and REFRESHES records and is rate-limited
+   30/ip, so it runs only on the explicit "Look up IP" action; a 429 surfaces
+   as a toast, never a silent no-op.
+5. **`/geoip/lookup` downgrades the graph, not the access.** The endpoint is
+   open to any authenticated identity (that is how a downstream instance uses
+   this one as its GeoIP provider), but a caller without `VIEW_PERMS` is
+   served the `federation` graph whatever it asked for — no enforcement state,
+   no raw blob.
+
+## Absent by design
+
+Do not add these back; each was verified against the backend.
+
+- The **trust toggle** and "Mark trusted/untrusted" — `is_trusted` does not exist.
+- **"Forget device"**, "Delete GeoIP record", "Delete location record" — no
+  `CAN_DELETE` anywhere.
+- Any **write** to a login event — `CAN_CREATE/UPDATE/DELETE` are all False.
+- The six phantom KPI fields (`event_count`, `incident_count`,
+  `login_attempts`, `login_count`, `session_count`, `location_count`), which
+  existed on no model and rendered "—" forever. They are replaced with
+  `size: 0` count queries against endpoints that do exist.
+- The `reverse_dns` / `ip_version` Network rows and the `provider` row on the
+  default graph — all three were permanently blank.
+- A `user` **select** filter on either table: neither endpoint can enumerate
+  the directory, so the filter is the FK id.
+- A search placeholder promising user or IP search on `/api/user/device` —
+  that model declares no `SEARCH_FIELDS` at all.
+
+## Verification
+
+```bash
+node scripts/verify-admin-devices.mjs   # or: npm run verify:admin-devices
+```
+
+Headless assertions over the six permission clauses (`sys.`-pinning,
+member-grant rejection, `manage_devices` absence), route generation for both
+mounts, expiry semantics, the risk tone, the scrubber and the export
+projection, one-`defineModel`-per-endpoint package-wide, the absent-by-design
+list, theme byte-identity and tokens-only CSS, and the full mock wire:
+owner scoping, anonymous denial, all four GeoIP graphs, the `/lookup` graph
+downgrade, every POST_SAVE_ACTION, the verb refusals, the aggregation shape,
+the region drill, the 500 cap, the `user_id` 400 and the `region=false` trap.

package/docs/admin-dns-certificates.md

@@ -0,0 +1,122 @@
+# Admin DNS certificates and ACME lifecycle
+
+Import from `portal-mojo/admin`:
+
+```tsx
+import {
+  CertificatesPage, CertificateDetail, CertificateRequestDialog,
+  DomainCertificatesSection, CertificateLifecyclePoller,
+  CertificateModel, deriveCertificateRenewalHealth,
+  deriveCertificateReadiness,
+} from 'portal-mojo/admin';
+```
+
+## Route, gates, and presentation
+
+`DNS_ADMIN_SECTION` contributes `dns/certificates` between DNS Records and
+Provider Credentials. Like the rest of Admin it is global and no-group:
+`sys.view_dns | sys.manage_dns | sys.security` opens the route and
+`sys.manage_dns | sys.security` offers request/revoke. Tables own search,
+status/domain filters, paging, and sort in the URL.
+
+Row inspection uses `modal.detail`; requesting and confirming revocation use
+small native KISS modals. `DomainDetail` composes the bounded
+`DomainCertificatesSection` rather than adding a child route.
+
+Certificate detail and revoke have an extra backend rule: when the hydrated
+owning Domain has `group=null`, only a literal interactive superuser may open
+or revoke it. A global `manage_dns` grant is not enough. The client hydrates
+the Domain before fetching certificate detail, checks `me.is_superuser ===
+true`, and gives a generic unavailable answer on denial so it does not become
+an additional house-inventory oracle. The server remains authoritative.
+
+## Wire contract and cache boundary
+
+```text
+GET  /api/dnsman/certificate?graph=default
+GET  /api/dnsman/certificate/<id>
+POST /api/dnsman/certificate/request {domain, names?}
+POST /api/dnsman/certificate/revoke  {certificate}
+GET  /api/dnsman/delegation?domain=<id>
+```
+
+Only `graph=default` is accepted. Certificate export/download params are
+rejected, not silently forwarded. The graph carries lifecycle metadata and a
+basic Domain relation; it carries no `cert_pem`, `chain_pem`, private key,
+ACME order URL, secret container, or arbitrary metadata. There is deliberately
+no client helper or mock handler for `certificate/material/<id>`.
+
+All list/detail rows pass through `sanitizeCertificateRow` in the Query
+function, before TanStack Query stores them. It normalizes lifecycle status,
+lowercase/trailing-dot-free SANs, finite timestamps/counts, a small Domain
+projection, and a bounded/redacted `last_error`. Unknown/equivalent private
+containers drop by construction. Delegation payloads retain only the backend's
+public status shape; credential readiness uses the already-sanitized masked
+credential model.
+
+Request and revoke are imperative, single-flight, and non-retrying so an
+ambiguous transport cannot duplicate an external CA operation. They do not use
+MutationCache. A `finally` reconciliation invalidates/refetches active
+certificate queries after success or failure. If authoritative refresh also
+fails, repeat is blocked by an explicit “may have persisted; refresh first”
+error.
+
+## Names and readiness
+
+The request dialog normalizes names to lowercase ASCII without trailing dots,
+deduplicates them, permits a wildcard only as the leading `*.`, and requires
+every SAN to be the selected zone or a descendant. Empty names intentionally
+omit `names`, letting the backend request the apex plus wildcard.
+
+Readiness is backend-authoritative:
+
+- ACME must be configured and the Domain active.
+- Route 53 uses direct DNS-01.
+- GoDaddy direct DNS-01 also needs its active, verified masked credential.
+- `provider="mojo"` needs a verified delegated-ACME row.
+- Once a delegation has `verified_at`, it is sticky. A later `broken` row
+  blocks issuance; the UI never claims direct-provider fallback.
+
+`config.acme.staging` describes the deployment's current directory only. The
+certificate model stores no historical staging provenance, so existing rows
+are never labeled trusted or staging from that flag. New staging requests get
+an explicit “not publicly trusted” warning.
+
+## Renewal and polling
+
+`renew_after` is the authoritative renewal trigger. `days_remaining` is only
+display. `CertificateLifecyclePoller` owns one timer per mounted certificate
+surface, at 10 seconds and at most 36 ticks:
+
+- new issuance follows `pending | issuing` to active/failed/revoked;
+- a due active renewal records attempts/validity/error baseline, waits through
+  the initial active state and optional `issuing`, then stops on an observable
+  success or failure;
+- an already-active row with `last_error` is a terminal renewal error and does
+  not start ordinary polling;
+- timeout, unmount, and terminal state clear the timer.
+
+This avoids one interval per row and avoids an endless poll on the backend's
+valid “renewal failed but still-valid certificate remains active” behavior.
+
+## Mock, themes, and verification
+
+The central mock contains pending, issuing, healthy active, due renewal,
+active renewal-error, failed, revoked, house, verified delegation, broken
+sticky delegation, staging, unconfigured, and malformed-response evidence.
+Its only custody fixture is a private `material_present` boolean; no PEM is
+stored or serialized.
+
+Portal and Showcase both import `theme/admin-dns-certificates.css`, which uses
+semantic tokens only. The executable demo is **Develop → Components → DNS
+certificates & ACME** with manager, viewer, platform-house, and unconfigured
+legs. Run:
+
+```bash
+npm run verify:admin-dns-certificates
+npm run verify:admin-dns
+npm run verify:admin-dns-records
+```
+
+Live verification is read-only. Do not request or revoke a real certificate
+without separate operator authorization.

package/docs/admin-dns-records.md

@@ -0,0 +1,65 @@
+# DNS domains and live records
+
+Import from `portal-mojo/admin`:
+
+```tsx
+import {
+  DNS_ADMIN_SECTION, DomainsPage, DnsRecordsPage, DnsRecordsPanel,
+  DnsRecordEditor, DNS_VIEW_PERMISSIONS, DNS_MANAGE_PERMISSIONS,
+  registerDnsAdminIntegration, registerDnsDomainLinks,
+} from 'portal-mojo/admin';
+```
+
+## Routes and permissions
+
+The one canonical DNS section is `id: "dns"`, `basePath: "dns"`, in Infrastructure. Its routes are ordered `domains`, `records`, `certificates`, `purchases`, `registrant`, `credentials`. The read surfaces accept the global, system-pinned any-of view clause `sys.view_dns | sys.manage_dns | sys.security`; registrant and record mutation controls use `sys.manage_dns | sys.security`. Group/member grants never open Admin.
+
+Domains uses the server-backed `DomainModel` list and `modal.detail`. Detail composes Overview, DNS Records, and the bounded Certificates section; Records is the same `DnsRecordsPanel` used by the standalone page. That page owns only `domain` and `record_type` in the URL. It may select the first active domain only when `domain` is absent. Invalid, denied, missing, and inactive deep links are preserved and shown as errors.
+
+## Wire contract
+
+Domain list/default reads are standard model envelopes. List asks only for paging, search, sort, provider, status, group and the `list` graph. Live records are deliberately not a model:
+
+```text
+GET /api/dnsman/dns?domain=8201
+{status:true,data:{domain:"acme.example",provider:"route53",
+records:[{type:"A",name:"acme.example",record_values:["192.0.2.10"],ttl:300}]}}
+```
+
+Records have no database id, paging, search, or graph. The parser fails closed on malformed payloads or an invented `id`. Local identity is `TYPE|normalized-fqdn`.
+
+Upsert replaces the complete ordered set and sends exactly
+`{domain,type,name,record_values,ttl}`. Whole-set deletion sends only
+`{domain,type,name}`. Removing some values is an upsert of all survivors,
+never a partial delete.
+
+Both write endpoints answer at the top level as
+`{status:true,change_id:string|null,provider:string}`. Route 53 supplies a
+change id; GoDaddy may return `null`. There is no nested `data` write payload.
+
+## Editor invariants
+
+A, AAAA, CNAME, TXT, MX, SRV, CAA, and delegated non-apex NS use controlled structured rows, intersected with `allowed_record_types`. Unknown types remain readable and have no editor. Existing type/name are immutable.
+
+Paste and blur may correct invisible characters, NBSP, curly quotes, URL/path/trailing dots, hostname case, bracketed IPs, and surrounding TXT/CAA quotes. Every correction records field, before, after, and message. Existing TXT values, including meaningful leading, trailing, and repeated whitespace, parse, format, edit, and submit losslessly unless the operator explicitly triggers and acknowledges a paste/blur correction. Submit never trims, dequotes, lowercases, normalizes, or deduplicates unacknowledged state. Blank/duplicate values, incomplete structured rows, invalid IPv4/full IPv6, hostname/range/TTL errors, out-of-zone or malformed names, invalid wildcards, apex NS/SOA/CNAME, and CNAME coexistence fail before the request. Server refusal remains authoritative.
+
+Confirmation shows identity, TTL, unchanged/removed/added values, and contextual warnings from the editor opening snapshot. After confirmation the coordinator performs an uncached read, compares the exact set and every same-owner record (including CNAME coexistence), and writes immediately only when unchanged. A `finally` read reconciles cache after success, rejection, or an ambiguous response, and the zone query is invalidated unconditionally even when that read fails so stale cache is never authoritative. The draft and original error survive. This is best-effort preflight: no ETag/CAS exists, so a narrow GET-to-POST race remains.
+
+## Provider behavior
+
+- Route 53 supports complete-set upsert and separately confirmed whole-set delete.
+- GoDaddy manages DNS here; registrar operations stay in its account. The server clamps refreshed TTLs to 600 and cannot express whole-set deletion. Exact `_acme-challenge.* TXT ["retired"]` rows are spent/inert only for GoDaddy.
+- `provider="mojo"` is certificate-only and fails closed for general DNS.
+- Pending/registering domains, unknown providers, and missing/inactive/unverified credentials render explicit blocked states.
+
+## Composition seams
+
+`dns-integration.ts` is dependency-free and HMR-safe. Partial registrations merge: production supplies exact-name resolution and `dns/records?domain=<id>`; the central mock supplies `applyManagedDnsRecords` against its sole DNS store. Absence is `null`, so permission is never mistaken for feature availability.
+
+`registerDnsDomainLinks` is the reverse registry for certificate, WHOIS, or purchase children. Stable keys replace on HMR. Each entry owns label/icon, mount-relative route, optional system permission, capability/domain predicate, and optional order. Built-in related links are deterministically ordered Domains, DNS Records, Certificates, Provider Credentials.
+
+## Mock and verification
+
+The central mock is the only DNS state owner and mirrors id-less envelopes, global-versus-tenant authorization, active/provider/credential gates, complete replacement, Route 53 delete, GoDaddy floor/refusal/spent placeholders, Mojo, unknown records, and structured types. Mutation verification is mock-only. Live verification may read a zone and open/cancel an editor, but must never POST or DELETE DNS records.
+
+Both Portal and Showcase import `theme/admin-dns.css`; all colors use theme tokens. Run `npm run verify:admin-dns-records` with the orchestration-owned typecheck/build/browser pass.

package/docs/admin-dns-registrar.md

@@ -0,0 +1,33 @@
+# Admin DNS registrar and registrant contact
+
+Import `DomainPurchasesPage`, `DomainPurchaseWizard`, `showDomainOnboarding`, and `RegistrantContactPage` from `portal-mojo/admin`.
+
+The global, no-active-group DNS workspace mounts `purchases` and `registrant` between Certificates and Provider Credentials. Purchase-ledger viewing uses the global DNS view clause. Search is read-only; quote, purchase, adoption, and registrant writes require DNS manage authority. House contact and manual House adoption additionally require the literal interactive `is_superuser` identity.
+
+## Search, quote, and purchase
+
+The wizard asks for one explicit group through bounded `/api/dnsman/credential/group-choice` search. It never reads `/api/group`, active-group state, or free-form group ids. TLDs are operator-typed and bounded by `config.search_batch_limit`; the client has no invented supported-TLD catalog. Search availability stays tri-state: `true`, `false`, or `null` (registry did not answer). Only literal `true` advances.
+
+`POST /registrar/quote` returns `{purchase,name,price,currency,years,token,expires,privacy_supported}`. The raw token lives only in an immutable ref in the mounted wizard. It is never state, URL data, Query/Mutation cache data, mock request history, or durable mock data. The exact tuple binds purchase id, token, group, normalized domain, years, decimal price, currency, and expiry. Any upstream change or expiry clears it.
+
+The operator types the exact normalized domain before the single-flight, nonretry `POST /registrar/purchase`. The token is removed from the ref before the request. Success and every exception reconcile through an imperative `GET /purchase/<id>?graph=default`; one non-overlapping bounded-backoff loop follows `submitted` to a durable terminal row. Timeout hands the operator to the ledger.
+
+After purchase is attempted, the wizard cannot retry or requote. A failed, ambiguous, or timed-out result always says that money may have moved and directs the operator to the AWS Route 53 Domains operation console and durable ledger first.
+
+## Purchase ledger
+
+`DomainPurchaseModel` lists only `graph=basic`: id, domain, status, price, and currency. Export/download and alternate graphs are rejected. Clicking a row performs an imperative default-graph read into a KISS modal; the detail response and redacted error are modal-local and never Query-cached.
+
+## Registrant PII
+
+The contact page starts with no scope and no contact. Operators explicitly choose one authorized group, or literal superusers may choose House. Reads and writes are imperative; generation guards discard late responses after scope changes/unmount, and local contact state is cleared immediately.
+
+An inherited group response renders a blank form and only the backend-authored boolean status; inherited values are never disclosed. Normal editable values may seed from that scope's database row or the House settings-file response. `Fax` and opaque `ExtraParams` are preserved only when the original response is a direct database row for the exact same scope. They are never carried across scope, inheritance, or deployment-file override boundaries.
+
+## House adoption
+
+House adoption is a separate, literal-superuser-only menu option. The operator types one exact existing name and submits `/registrar/adopt` without `group`. The UI never calls `/registrar/discover`, auto-discovers account domains, or silently assigns the adopted asset to a tenant.
+
+## Themes, showcase, and verification
+
+Both themes import the same token-only `admin-dns-registrar.css`. The showcase has manager-ready, missing-contact, viewer-ledger, and platform-House legs. `npm run verify:admin-dns-registrar` is mock-only and performs no real registrar quote or purchase.

package/docs/admin-dns.md

@@ -0,0 +1,80 @@
+# Admin DNS
+
+Import from `portal-mojo/admin`.
+
+`DNS_ADMIN_SECTION` mounts Domains, DNS Records, Certificates, Domain Purchases,
+Registrant Contact, and Provider Credentials under `dns/` (or `system/dns/` embedded). Its global view gate is the ANY-of
+clause `sys.view_dns | sys.manage_dns | sys.security`; mutations use
+`sys.manage_dns | sys.security`. Member grants cannot satisfy either clause.
+
+## Capability gate
+
+`useDnsCapabilities(group?)` reads `/api/dnsman/config`. The parser is strict:
+every flag, limit, provider capability, ACME field, and delegated-ACME field
+must be present with the correct type. There are no provider or feature
+defaults. Until that contract succeeds, dependent controls do not render and
+the page shows **DNS administration unavailable**.
+
+Provider controls are derived only from the response. A provider is offered
+for credential linking only when it reports `requires_credential: true`.
+
+## Safe models and operations
+
+The package defines `DomainModel`, `DnsCredentialModel`,
+`DomainPurchaseModel`, and `CertificateModel`. Their endpoints and graphs are
+pinned and list params are allowlisted; export params are not accepted.
+Defence-in-depth sanitizers are explicit safe-graph projectors. Only approved
+scalar fields and approved sub-fields of group, user, credential, and domain
+relations survive; unknown or equivalent secret containers drop by default
+before data reaches TanStack Query.
+
+DNS records, registrar search/suggest/quote/purchase, house-domain adoption,
+registrant contact, WHOIS, and certificate request/revoke use typed imperative
+helpers. There is deliberately no certificate-material helper.
+
+House discovery returns the live `{count,truncated,domains}` contract. Each
+domain includes registration/hosted-zone presence, safe zone metadata,
+tracking/adoption state, and a reason. `untracked=true` returns only untracked
+rows; discovery and assignment remain interactive-superuser operations.
+
+The operator registrar workflow is documented in [admin-dns-registrar.md](admin-dns-registrar.md). It does not use discovery: House adoption is manual exact-name only. Purchase tokens remain transient, all post-confirmation outcomes reconcile through the read-only ledger, and contact PII remains imperative/local.
+
+These responses require local call-flow handling and must never enter Query or
+Mutation cache, logs, URL state, or mock state:
+
+- provider API keys and secrets;
+- registrar confirmation tokens;
+- registrant and WHOIS contact PII;
+- certificate PEM, chains, and private keys.
+
+## Provider credentials
+
+`ProviderCredentialsPage` is a server-driven `ModelTable`. Search, filters,
+sorting, and paging go to django-mojo. It has no export and no detail route.
+Clicking a row opens a compact `modal.detail`-style KISS surface showing only
+masked key/secret values and verification health.
+
+Link and rotation submit raw values through a fresh-auth imperative POST to
+`/api/dnsman/credential/link`. They are held in uncontrolled password refs,
+cleared after every attempt, sanitized before any explicit cache write, and
+the credential queries are invalidated in `finally`.
+
+The link picker uses only `/api/dnsman/credential/group-choice` with bounded
+`search/start/size` listing. A stored ID is hydrated through the exact
+`?id=<id>` form. The full selected object is held by `CollectionSelect`, so it
+never invents `/group-choice/<id>`, reads an active group context, calls
+`/api/group`, or accepts a free-form ID.
+
+Verification is transactional at the UI boundary: a failed first link adds
+nothing; a failed rotation rejects, preserves the previous masks/encrypted
+pair, and refetches the now-unverified row with its provider error. Successful
+verification replaces the masks and marks the row verified. Viewer-only users
+can inspect safe rows; managers can link, rotate, activate/retire, and arm
+deletion.
+
+## Themes and showcase
+
+The page composes existing portal primitives and semantic tokens; it adds no
+fixed colors or theme-specific stylesheet. The executable three-leg showcase
+is **Develop → Components → Admin → DNS**: live manager lifecycle,
+viewer-only contract, and malformed-capability unavailable state.