portal-mojo 0.1.0

package/docs/admin-network-security.md

@@ -0,0 +1,393 @@
+# Admin: network security — blocks, IP sets, geofencing
+
+```ts
+import {
+    // the section (registered in ADMIN_SECTIONS — no app wiring needed)
+    NETWORK_SECURITY_ADMIN_SECTION,
+    // pages
+    BlockedIPsPage, FirewallLogPage, IPSetsPage, GeofencingPage,
+    // KISS detail modals (#1425)
+    showBlockedIpDetail, showIPSetDetail,
+    // the SHARED rule editor — platform page and group panel render this one
+    GeofenceRuleEditor, makeRuleEditorValue, ruleFromEditorValue, toggleRuleEditorMode,
+    // models
+    IPSetModel, GeofenceEventModel,
+    // permission clauses
+    IPSET_VIEW_PERMS, IPSET_MANAGE_PERMS, IPSET_DELETE_PERMS,
+    GEOFENCE_VIEW_PERMS, GEOFENCE_MANAGE_PERMS, SECURITY_EVENTS_PERMS,
+    METRICS_GLOBAL_VIEW_PERMS, GROUP_GEOFENCE_EDIT_PERMS,
+    // the geofence projection (one module, two scopes)
+    isAdvancedRule, ruleToForm, formToRule, describeRule, diffRules,
+    describeDecision, describeWouldBlock, buildSimulateBody, buildGroupRulePayload,
+    coerceRuleInput, collectScopes, scopeLabel, regionName,
+    ABUSE_FLAGS, US_STATES, COUNTRY_OPTIONS, countryName,
+    // config-plane hooks (all `enabled`-gated — a denied surface issues NO request)
+    useGeoConfig, useGeoAllowlist, useBypassHolders, useGeoSimulate,
+    useSaveGeoRules, useRemoveGeoRulesOverride, useSaveGeoAllowlist,
+    useGeofenceCountryTotals, useIPSetCidrData,
+    isGeofenceApiMissing, GEOFENCE_API_MISSING_MESSAGE,
+} from 'portal-mojo/admin';
+```
+
+Perimeter control: block an abusive IP right now, whitelist a customer's NAT,
+maintain country and datacenter CIDR sets synced to the firewall fleet, set
+geographic policy — and prove the policy does what you think with a built-in
+simulator before it bites real traffic. Demo: showcase → Admin → **Network
+security**. Styles: `apps/{portal,showcase}/src/theme/admin-network.css`
+(byte-identical).
+
+## Surfaces
+
+One section, `network-security` at `security/network`, under the **Security**
+navigation group beside Security Operations, Bouncer, Devices & Logins and IP
+Intelligence.
+
+| Route | Presentation | Gate |
+|---|---|---|
+| `blocked-ips` | page + `modal.detail` | `GEOIP_VIEW_PERMS` |
+| `firewall-log` | page + the shipped `LogInspector` | `FIREWALL_LOG_PERMS` |
+| `ip-sets` | page + a two-tab `modal.detail` | `IPSET_VIEW_PERMS` |
+| `geofencing` | **page**: posture header over 4 tabs | `GEOFENCE_VIEW_PERMS` |
+
+Geofencing is the one surface that stays a page. That is the explicitly
+requested presentation: a config page that states what is in force and lets you
+test it before it bites.
+
+The section gate is the ANY-of **union** of the four route gates (the
+`MONITORING_ADMIN_SECTION` pattern), and each route then carries its exact
+backend gate. A geofence-only operator (`sys.view_geofence` alone) reaches
+Geofencing and is denied everywhere else; the engine's landing redirect resolves
+to the first route they can see, so nobody lands on a denial.
+
+## Permissions — `sys.`-pinned global grants only, fail-closed
+
+`@md.requires_global_perms` authorizes against global `User.permissions` or
+superuser **only** — no group fallback, and a `GroupScopedToken` is refused
+outright. Every clause here is therefore `sys.`-pinned: a member grant must
+never open platform enforcement config.
+
+| Constant | Value | Backend source |
+|---|---|---|
+| `GEOIP_VIEW_PERMS` | (imported from #1291) | `GeoLocatedIP.RestMeta.VIEW_PERMS` |
+| `GEOIP_MANAGE_PERMS` | (imported from #1291) | `GeoLocatedIP.RestMeta.SAVE_PERMS` |
+| `IPSET_VIEW_PERMS` | `sys.view_security`, `sys.security` | `IPSet.RestMeta.VIEW_PERMS` |
+| `IPSET_MANAGE_PERMS` | `sys.manage_security`, `sys.security` | `IPSet.RestMeta.SAVE_PERMS` |
+| `IPSET_DELETE_PERMS` | `sys.manage_security` **only** | `IPSet.RestMeta.DELETE_PERMS` |
+| `FIREWALL_LOG_PERMS` | `LOGS_ADMIN_PERMISSIONS` (reused) | `logit.Log.RestMeta.VIEW_PERMS` |
+| `GEOFENCE_VIEW_PERMS` | `sys.view_geofence`, `sys.manage_geofence`, `sys.security` | `@requires_global_perms` on `GET /api/geo/rules` |
+| `GEOFENCE_MANAGE_PERMS` | `sys.manage_geofence`, `sys.security` | `POST`/`DELETE /api/geo/rules` |
+| `SECURITY_EVENTS_PERMS` | `SECURITY_VIEW_PERMS` (reused) | `incident.Event.RestMeta.VIEW_PERMS` |
+| `METRICS_GLOBAL_VIEW_PERMS` | `sys.view_metrics`, `sys.metrics` | `metrics/rest/helpers.check_view_permissions` for `account="global"` |
+
+Note the two traps the table encodes:
+
+- **`IPSET_DELETE_PERMS` is narrower than manage.** The broad `security` grant
+  saves an IP set but cannot delete one.
+- **`manage_metrics` does NOT imply `view_metrics`.** An operator holding only
+  the manage grant is denied `account="global"` reads, so the blocks tab's
+  metrics strip gates on the view clause rather than firing and catching a 403.
+
+A permission-disabled query passes `enabled: false`. **No denied surface in this
+module issues a request** — not the metrics strip, not the blocks table, not the
+change history, not the posture header's Last-change chip.
+
+## Endpoints
+
+| Endpoint | Gate | Notes |
+|---|---|---|
+| `GET/POST /api/incident/ipset` `(+/<pk>)` | model `VIEW`/`SAVE`/`DELETE_PERMS` | graphs `default` · `detailed`; actions `sync`, `enable`, `disable`, `refresh_source` |
+| `GET /api/system/geoip` `(+/<pk>)` | #1291's model | Blocked IPs is the `is_blocked=true` projection |
+| `GET /api/logs` | `logit.Log` | filtered `kind__startswith=firewall:` |
+| `GET/POST/DELETE /api/geo/rules` | global geofence grants | `POST` body is `{rule}`, a FULL REPLACE |
+| `POST /api/geo/simulate` | global geofence view | body keys `ip`, `geo`, `scope`, `group_uuid` |
+| `GET/POST /api/geo/allowlist` | view / manage | `POST` body is `{entries}`, a FULL REPLACE |
+| `GET /api/geo/bypass_holders` | global geofence view | read-only, capped at 200 |
+| `GET /api/incident/event` | `SECURITY_EVENTS_PERMS` | `category=geofence_block\|geofence_exempt\|geofence_config` |
+| `GET /api/metrics/category_slugs` | `check_view_permissions` | **flat envelope — no `data` wrapper** |
+| `GET /api/metrics/fetch` | same | `account="global"` |
+
+### `GET /api/geo/rules` — the config payload, key for key
+
+```jsonc
+{
+  "system": { "rule": {…}, "source": "setting|conf|none", "modified": "ISO|null" },
+  "group":  { "id", "uuid", "is_active", "rule", "strict_posture", "strict_posture_effective" },
+  "posture": {
+    "enabled", "fail_closed", "fail_closed_scopes",
+    "allow_private_ips", "strict_posture", "cache_ttl"
+  },
+  "allowlist_summary": { "setting_entries", "geoip_active" },
+  "evaluation_order": ["system", "group"],
+  "enforced_endpoints": [{ "endpoint", "scope", "after_auth?" }]
+}
+```
+
+`group` is present **only** when the request carried `group_uuid`; an unknown
+uuid is a 400, and an *inactive* group is deliberately returned and evaluated.
+`after_auth` appears only when truthy.
+
+### The decision shape
+
+`_build_decision` writes `allowed`, `reason`, `detail`, `ip`, `country`,
+`country_code`, `region`, `region_code`, `abuse`, `checked_at`, `rule_level`,
+`strict_posture`. `country` and `country_code` carry the **same** value, as do
+`region` and `region_code`.
+
+**`enabled` sits at the TOP level of a simulate decision** (`engine.py:473`) and
+is absent from `check()` decisions entirely. `would_block`, `would_block_reason`,
+`allowlist_source`, `allowlist_reason` and `allowlist_until` appear **only** when
+the IP matched the allowlist — and `would_block` is `null` (not `false`) when the
+shadow decision was itself a `lookup_failed`, because the engine genuinely does
+not know. `_allowlisted_decision` never copies `rule_level`, so an exempt
+decision's rule level is always `null`.
+
+### `/api/metrics/category_slugs` — the flat-envelope exception
+
+This route returns a raw `JsonResponse`, so the payload is **not** nested under
+`data`:
+
+```jsonc
+{ "slugs": [...], "category": "geofence", "account": "global", "status": true }
+```
+
+The `account` default is `"public"` while `metrics.record()` defaults to
+`"global"` — so a geofence slug is invisible unless `account=global` is asked
+for explicitly. `get_category_slugs` returns a **set**, so slug order is
+nondeterministic and no consumer may depend on it.
+
+## The rule DSL and the guided↔advanced projection
+
+Top-level keys `{country, region, abuse}`; operators `{in, not_in, eq}`; abuse
+flags `{tor, vpn, datacenter, proxy}`. Abuse semantics: `false` blocks when the
+flag is detected, `true` REQUIRES the flag (rare), absent/`null` means don't
+care.
+
+`geofence-data.ts` is the ONE definition of the lossy projection between that
+DSL and the friendly form. `apps/portal/src/pages/group-sections/geofence-data.ts`
+is a re-export shim over it, so the platform page and the group panel cannot
+drift. `GeofenceRuleEditor` is the ONE editor both render.
+
+The projection's contract:
+
+- `isAdvancedRule(rule)` — true for anything the guided form cannot represent:
+  unknown top keys, non-dict bodies, `country.eq`, multiple operators, an
+  allow+block mix, any `region` shape other than a single `not_in` of US state
+  codes, and any abuse `true` or unknown flag.
+- An advanced-forced rule **opens in JSON with no toggle** — flipping to guided
+  would silently drop clauses.
+- The toggle back to guided **refuses** invalid JSON and unrepresentable shapes;
+  the guided→JSON direction carries unsaved edits across.
+- `buildGroupRulePayload(old, new)` — GROUP layer only. django deep-merges
+  JSONFields (`null` deletes a key; nested `__replace` is NOT supported), so the
+  payload is the new value for every kept key plus explicit `null`s for anything
+  removed. Sub-keys are **allowlisted**, so a `__replace` typed into the advanced
+  editor is dropped rather than PATCHed into stored metadata.
+- The platform layer never merges: `POST /api/geo/rules` is a full replace, and
+  the two surfaces share no save path. **The group surface can only tighten and
+  can never write platform rules; the global surface never writes group
+  metadata.**
+
+Every reason code in `engine._DETAIL_MAP` has plain-language copy, including
+**`no_rules_strict`** — the strict-posture denial web-mojo had no text for.
+An unknown code degrades to a readable fallback **and warns once**.
+
+## Event metadata keys
+
+`services/geofence/evidence.py` writes, for `geofence_block`: `reason`,
+`rule_level`, **`geofence_scope`**, `country_code`, `region_code`, `abuse`,
+`detail`, and `username` when the request was authenticated. For
+`geofence_exempt`: `reason`, `geofence_scope`, `allowlist_source`,
+`allowlist_reason`, `would_block_reason`, `country_code`, `region_code`. For
+`geofence_config`: `target`, `old`, `new`, **`changed_by`**, `changed_by_id`.
+
+Two keys this module reads that web-mojo got wrong:
+
+- It is **`metadata.geofence_scope`**, never `metadata.scope`. The reporter
+  never passes the reporter's `scope=` argument, so the top-level `Event.scope`
+  column stays `"global"` for every geofence row.
+- The config "who" is **`metadata.changed_by`** (a username), falling back to
+  `metadata.user_name` (the display name, written by
+  `reporter._create_event_dict`). `metadata.username` is written by neither.
+
+`Event.country_code` is a real indexed column — `Event.sync_metadata` fills it
+from the geolocated source IP — so country filtering uses the column, not the
+metadata copy.
+
+`_block_level`: **7** rule_invalid (a broken rule is denying traffic; the default
+incident threshold auto-creates an Incident) · **6** lookup failure while failing
+open (enforcement silently is not happening) · **5** abuse-flag block, a block on
+a fail-closed scope, or any block under strict posture · **3** ordinary
+jurisdiction block, exemption used, or config change.
+
+## IP sets
+
+`KIND_CHOICES` are `country · datacenter · abuse · custom`. `SOURCE_CHOICES` has
+**five** members — `ipdeny`, `abuseipdb`, `tor`, `blocklist_de`, `manual`.
+web-mojo listed three, so the two cache-only rows showed a raw slug and could not
+be filtered.
+
+### Records are created disabled, and `is_enabled` is never a plain field
+
+`on_action_enable` is the **only** path that runs the cache-only rejection.
+Writing `is_enabled` as a plain field produces a row that reads "Enabled" and
+silently never syncs, because `sync()` no-ops for a cache-only set without
+raising. So:
+
+- the create form has no enable switch and the POST body carries no
+  `is_enabled` — a set is created **staged**;
+- the edit form has no `is_enabled` either;
+- enabling and disabling are armed **actions**.
+
+Direct #1097 lineage; the verifier asserts it against source.
+
+### `tor_exits` and `blocklist_de` are cache-only
+
+`IPSet.THREAT_CACHE_SETS`. They exist to feed GeoIP threat *detection*, not the
+kernel firewall. `enable` answers a 400 that names the set:
+
+> `'tor_exits' is a cache-only threat list for geoip detection — enabling it
+> would kernel-block every listed IP fleet-wide and is not permitted`
+
+The UI surfaces that message verbatim, chips the rows **CACHE-ONLY**, and
+excludes them from the batch Enable and Sync eligibility so a mixed selection
+still succeeds for the rest.
+
+### `data` must be posted as a LIST
+
+`IPSet` defines `set_data(cidr_list)` = `"\n".join(cidr_list)`, and
+`on_rest_save_field` prefers a `set_<key>` method over a plain assignment. So a
+posted `data` runs through the setter:
+
+- a **JSON list** is correct, and `cidr_count` is recomputed from it;
+- a **string** gets a newline interleaved between every *character* and
+  `cidr_count` becomes the character count.
+
+web-mojo posted the raw textarea string. `parseCidrLines()` is the boundary here;
+the mock reproduces both behaviours so the trap stays executable.
+
+This also corrects a claim recorded during scoping: `cidr_count` is **not**
+frozen at 0 for manual sets forever. It is stale only until the list is next
+*written* — by a source refresh, or by saving the list from the editor.
+`refresh_from_source()` really does return `False` immediately for
+`source == 'manual'`, so the *refresh* path alone can never update it. The CIDR
+Data tab shows the parsed line count beside the stored one whenever they differ.
+
+## Firewall log — column honesty
+
+`GeoLocatedIP` writes these rows through `MojoModel.log`, which fills `path`,
+`ip`, `username` and `uid` from the **ambient request** — the admin's endpoint
+and the admin's address. The blocked address lives only in `payload.ip`.
+web-mojo labelled `path` as "IP / Path", which was never either.
+
+The four `kind` values are exact, and the payload shape is **not** uniform:
+
+| kind | payload keys |
+|---|---|
+| `firewall:block` | `ip, reason, ttl, blocked_until, block_count, trigger` |
+| `firewall:unblock` | `ip, reason, trigger` |
+| `firewall:whitelist` | `ip, reason, until, was_blocked, trigger` |
+| `firewall:unwhitelist` | `ip, trigger` |
+
+## Blocked IPs
+
+The `is_blocked=true` projection over #1291's `GeoLocatedIPModel`. This module
+defines **no** model for `/api/system/geoip` — one endpoint, one `defineModel`,
+one cache key.
+
+- **Enforcement is computed.** `block_active` and `whitelist_active` are Python
+  properties serialized only on the `basic` graph, so `blockActive(row)` /
+  `whitelistActive(row)` (#1291's helpers) decide the State column: a whitelist
+  beats a block, an expired block stops enforcing, and `is_blocked` stays set
+  either way.
+- **`blocked_until = null` means PERMANENT** and renders "Never", not blank.
+- The threat filter is a multiselect over the four real values plus an explicit
+  `threat_level__isnull` filter. web-mojo offered a literal `none` value that
+  matched no row on any deployment.
+- The search placeholder names the model's real `SEARCH_FIELDS`
+  (ip / city / country name / ASN org / ISP). There is no rule text on this model.
+- Batch **Unblock** and **Whitelist** collect one reason per batch through
+  `prepare`; whitelist sends the DICT form `{reason, until}` so the audit trail
+  and `whitelisted_until` are both real (the source sent a bare string).
+
+## Exemptions and the full-replace race
+
+`POST /api/geo/allowlist` replaces the whole `GEOFENCE_ALLOWLIST` setting, so a
+stale local copy silently deletes a concurrent editor's entry. Every write here
+**refetches and compares first** and aborts with an explanatory message when the
+server list has moved (`AllowlistRaceError`). An empty list is a legitimate
+CLEAR, not "no change" — removing the last entry asks explicitly.
+
+Expired entries are listed with `active: false` and rendered inactive, never
+hidden: an auditor needs to see that an exemption existed.
+
+Removing an individual IP whitelist resolves the record through a **cached read**
+(`?ip_address=`), not `/geoip/lookup` — the row exists by definition, so removal
+costs no provider call and no rate-limit budget. Adding one does use `/lookup`,
+because the address may never have been seen.
+
+## Degrading on a backend without the config plane
+
+`/api/geo/*` is simply **not registered** on an older django-mojo, so the wire
+answer is a **404**, not an error envelope. `isGeofenceApiMissing(error)` is the
+branch; the copy names the documented floor (v1.2.42) as prose and asserts no
+version the client can verify — there is no version endpoint. Any other status
+shows the server's own message.
+
+## Armed confirmation
+
+Anything that reaches the fleet is an `ArmedButton` whose armed label names the
+blast radius: the rules replace (with a plain-language clause diff), override
+removal, ipset enable / disable / sync / refresh / delete, allowlist removal and
+whitelist removal. Operations that need input (a reason, an expiry) use
+`formModal` instead — an armed button cannot collect input.
+
+## Absent by design
+
+Do not add these back.
+
+1. **Batch delete of IP sets.** Multi-selecting kernel firewall sets and deleting
+   them in one irreversible action is exactly the shape #1097 warned about.
+   Delete is single-record and armed, from the detail modal.
+2. **Creating a block from the Blocked IPs table.** The backend supports it and
+   web-mojo did not expose it either. Unblock and whitelist — both *relaxing* —
+   are exposed.
+3. **Editing geofence posture.** `GEOFENCE_ENABLED`, `GEOFENCE_FAIL_CLOSED`,
+   `GEOFENCE_FAIL_CLOSED_SCOPES`, `GEOFENCE_CACHE_TTL` and
+   `GEOFENCE_STRICT_POSTURE` are plain `Setting` rows with no validated
+   geofence-specific endpoint. The header is read-only and points at Runtime
+   Settings.
+4. **Granting or revoking `bypass_geofence`.** The backend's own comment says
+   grants are managed on user records, and the endpoint returns id/username only
+   to avoid leaking user PII through a geofence-only grant.
+5. **A world map / choropleth.** Owned by #1426 and reserved. The ranked country
+   list ships instead and is the same server-derived dataset.
+6. **A general GeoLocatedIP administration table.** That is #1291's IP
+   Intelligence section; the Blocked IP modal links to its dossier.
+7. **`geoip_sync` / federation controls.** Fleet-peer plumbing, not perimeter
+   operation.
+8. **Event deletion or editing from the blocks log.** The evidence plane is
+   append-only by design.
+9. **A client-side "top blocked countries" computed from the visible page.** It
+   would lie about totals whenever the page did not cover the window.
+
+## Verification
+
+```bash
+node scripts/verify-admin-network.mjs   # or: npm run verify:admin-network
+```
+
+Headless assertions over the nine permission clauses, section registration and
+route generation for both mounts, the full `geofence-data` mapping table
+(`isAdvancedRule` truth table, form round trip, `buildGroupRulePayload` null-out
+and sub-key allowlist, `coerceRuleInput`, `collectScopes`, `describeDecision`
+over every `_DETAIL_MAP` code, `describeWouldBlock` including the nullable
+shadow, `buildSimulateBody`, `diffRules`), the editor's two refusals, the app
+shim proving ONE module by identity, the source-shape rules (no route/right-panel
+inspection, `modal.detail` present, no `is_enabled` write, no batch delete, no
+block creation, a read-only posture header), the persona 403 matrix across
+`/api/geo/*`, `/api/incident/ipset` and `/api/system/geoip`, and the mock wire:
+graph exclusions, the cache-only 400, the create-disabled default, the
+list-vs-string `data` trap, name uniqueness, delete-perm narrowness, DSL and
+allowlist validation, the empty-list clear, top-level `enabled`, the exempt
+shadow fields, the firewall Log trail with its per-kind payload shape, and the
+flat `category_slugs` envelope. Plus theme byte-identity and tokens-only CSS.

package/docs/admin-phonehub.md

@@ -0,0 +1,27 @@
+# Phone Hub admin (#1295)
+
+Import `PhoneHubPage`, the three individual pages, models, permission clauses, and API helpers from `portal-mojo/admin`. `PHONE_HUB_ADMIN_SECTION` registers one global `/phonehub` route in Communications; the page exposes only the Phone Numbers, SMS, and Provider Config tabs the caller may view. Admin global scope masks any outer product group.
+
+## Wire contracts
+
+- `POST /api/phonehub/number/normalize` is public. `normalizePhoneNumber()` accepts the backend result only when it is strict E.164.
+- `POST /api/phonehub/number/lookup` requires authentication and is offered only under `PHONE_LOOKUP_UI_PERMISSIONS`. The helper always normalizes first. For a new or expired record it omits `force_refresh` so the backend's normal lookup path refreshes once. For a known-fresh record it requires confirmation, then sends `force_refresh: true`. A successful response must provide a first lookup timestamp/count or advance one of them relative to the prior row; a 2xx stale row is rejected as provider failure evidence.
+- `PhoneNumberModel` requests the default graph but positively sanitizes every row before Query. Raw `lookup_data` is never retained or exported.
+- `SmsModel` is an audit-only surface. It requests the default graph and positively projects known display fields before Query; raw metadata, provider payloads, and provider message ids are discarded. Its client exporter is bounded and omits message bodies, errors, user/group details, and raw fields. There is no send UI.
+- `PhoneConfigModel` reads sanitized scalar/default-graph rows. Saves and `test_connection` use imperative, cache-free calls. 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. Responses are allowlisted before cache reconciliation. This surface edits existing provider credentials; it does not provision Django user/group API keys.
+
+## 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`. The server remains authoritative.
+
+Group choices are fetched only with a separate global group-directory clause and are capped at 100 basic rows. Without that grant the editor does not issue a group-directory request and preserves the existing scope (or creates a system default).
+
+## 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.
+
+An active group config wins; otherwise `PhoneConfig.get_for_group` falls back to the first active system default. Deleting or deactivating a group config restores that fallback. 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.
+
+## Reuse rules
+
+Use KISS detail modals, not `:id` routes. Never add provider payloads to a model graph, cache, error, export, or request history. Never reuse `PhoneConfigModel.useSave()` for credentials. Do not add SMS sending or API-key provisioning to this admin area without a new reviewed contract.

package/docs/admin-push.md

@@ -0,0 +1,36 @@
+# Push Notifications admin (#1296)
+
+Import `PushPage`, its individual panels/pages, the canonical push models, API helpers, and `PUSH_ADMIN_SECTION` from `portal-mojo/admin`. The section contributes one global/no-group Communications route at `/push`; there are no record routes. KISS detail modals own record inspection.
+
+## Tabs and URL state
+
+The page has six possible tabs: Your stats, Global metrics, Devices, Deliveries, Templates, and Config. Stats are authenticated caller data. Every other tab is independently filtered by its exact permission clause, and only the active authorized panel mounts, so hidden/inactive surfaces issue no requests.
+
+`push_surface` is registered with `registerNonFilterParams` at module load. It survives table writes but never becomes a Django lookup or filter pill. Changing tabs replaces the flat URL params with only `push_surface`, intentionally clearing search, sort, paging, and filters that belong to the prior model.
+
+## Exact permissions
+
+All UI clauses carry the `sys.` namespace and are ANY-of:
+
+- Devices view: `view_devices | manage_devices | comms | owner | manage_users`; save: `manage_devices | comms | owner`.
+- Deliveries view: `view_notifications | manage_notifications | comms | owner | manage_users`; save: `manage_notifications | comms`.
+- Templates view: `manage_notifications | manage_groups | comms | owner | manage_users`; save: `manage_notifications | manage_groups | comms`.
+- Config view/save: `manage_push_config | manage_groups | comms`.
+- Config connection test: `manage_push_config | comms`.
+- Global metrics: `view_metrics | metrics`, with `account="global"`.
+
+`sys.users` is deliberately absent: it is not in `RegisteredDevice.RestMeta.VIEW_PERMS`. The Stats endpoint requires authentication only and always scopes all five keys to `request.user`.
+
+## Projection and ownership boundaries
+
+Every model pins a `basic` or `default` graph, allowlists list params, and positively projects rows before Query or Mutation cache reconciliation. RegisteredDevice never retains `device_token`; Delivery never retains `platform_data`, and its arbitrary `data_payload` is not retained by the UI projection. Related users are reduced to id plus a short display label—never email, phone, metadata, or an expanded user graph. Template JSON objects accept only a bounded shallow scalar projection on reads.
+
+`PushDeviceModel` now lives canonically in `admin/messaging/push`. The former `admin/identity/users/models.ts` definition is a compatibility re-export of the same object, so User Detail and the global Push page share one endpoint definition and Query key.
+
+## FCM credentials and actions
+
+FCM writes are imperative and cache-free. A service account textarea is an uncontrolled DOM ref and never prefills. Blank means untouched and is omitted. Replacement must parse to an object with `type="service_account"`, `project_id`, `client_email`, and a PEM `private_key`. Clear sends `null` only after explicit confirmation. Empty replacement is impossible, and server responses are sanitized before cache reconciliation.
+
+Connection testing calls only `POST /api/account/devices/push/config/<id>/test` with an empty body. The backend uses its dummy token to validate credentials. The portal never accepts a device token. It also does not expose `/send`, caller `/test`, delivery retry, device registration/unregistration, or any delete action.
+
+All four REST models have live `CAN_DELETE = false`; the mock returns 403 without removing or cascading anything. Templates/configs can be created and edited under their save clauses. Devices and deliveries remain investigative here.

package/docs/admin-rules.md

@@ -0,0 +1,87 @@
+# Rule Engine admin
+
+Import models, routes, transforms, and the builder from `portal-mojo/admin`:
+
+```tsx
+import {
+  RuleSetModel, RuleModel, HandlerChainBuilder,
+  parseHandlerChain, runtimeEffectiveHandlerChain,
+} from 'portal-mojo/admin';
+```
+
+The shared Security Operations section mounts the `rules` table after Tickets,
+Incidents, and Events. Selecting a RuleSet opens its DetailView through the
+shared KISS `modal.detail` surface; there is no `rules/:id` child route, so the
+table URL and query state remain unchanged. The mount-relative table works at
+`#/security/rules` in the standalone Admin and `#/system/security/rules` when
+embedded. Reads require
+`sys.view_security|sys.security`; mutations require
+`sys.manage_security|sys.security`. These are system-pinned clauses: active
+group grants do not satisfy them, and the server remains authoritative.
+
+## Wire models and safety boundary
+
+`RuleSetModel` uses `/api/incident/event/ruleset`; `RuleModel` uses
+`/api/incident/event/ruleset/rule`. Row types intentionally remain open and
+fetched rows are not reconstructed, so future top-level fields, metadata,
+enum values, comparators, and value types remain in TanStack Query unchanged.
+
+Rule-set creation always sends `is_active:false`, regardless of form input.
+An empty active RuleSet is a category catch-all and can preempt later
+priorities, so enabling a zero-condition set is a separate warning that names
+its category and priority. The create defaults are priority 10, ALL matching,
+SOURCE_IP bundling for 30 minutes, and an empty handler. `bundle_minutes=0`
+disables time bundling; `null` means the current backend's unbounded window.
+Count thresholds require effective bundling, trigger/retrigger windows require
+a count, and a finite trigger window cannot exceed the finite bundle window.
+
+Rule transforms reject leading-underscore fields and validate integer/float
+comparison values. Existing `bool` rules are visible and preservable, but
+creating or changing a bool comparison is blocked: the backend currently
+applies Python `bool()` to stored strings, so the string `"false"` is true.
+
+## Handler grammar and preservation
+
+Supported runtime schemes are `job`, `email`, `sms`, `notify`, `block`,
+`ticket`, `maestro`, `llm`, and `resolve`. Notification targets may contain
+commas (`perm@…`, `protected@…`, usernames). The editor recognizes a chain
+boundary only at comma + URI scheme, preserving target commas.
+
+There are deliberately two projections:
+
+- The editor projection exposes any URI scheme so unsupported content is
+  visible and movable/removable only by explicit operator action.
+- The runtime-effective projection exactly mirrors django-mojo's split:
+  comma immediately followed by a *known* scheme. Leading unknown segments
+  are skipped; unknown or whitespace-prefixed segments after a known handler
+  can be swallowed into that handler's spec. The builder warns about both.
+
+Every step retains its raw bytes and preceding separator. Parsing then
+serializing an untouched chain is byte-for-byte exact. Structured changes are
+surgical: ordered query entries and unknown parameters remain, duplicate keys
+remain, and the first duplicate is the runtime-effective value that edits
+target. Moving/editing/removing skipped or swallowed content requires an
+explicit high-severity behavior-change confirmation. An empty string is valid:
+the incident is recorded and no action is dispatched.
+
+Handler order is publication/dispatch order. Jobs run asynchronously, so the
+UI does not promise completion order. Structural validation covers URI shape,
+percent encoding, required targets/module paths, integer/range values, blank
+parameter keys, and resolve statuses. It cannot prove target or permission
+existence, job importability, Maestro board existence, runtime settings, or
+Python regex semantics; failed server mutations reject visibly and leave the
+editor open.
+
+## Reordering limits
+
+The whole handler chain is one RuleSet text field, so a chain edit/reorder is
+one atomic save. RuleSet priorities and child Rule indexes are separate rows;
+django-mojo exposes no atomic multi-row reorder action and `CAN_BATCH` is
+false. Drag reorder is therefore absent. Operators edit one numeric value at
+a time, and duplicate priorities/indexes are flagged because tie order is
+undefined.
+
+The showcase demo is under **Admin → Rule Engine** and includes supported
+steps, notification target commas, duplicate/extra parameters, unsupported
+content, structural errors, move/remove actions, exact raw serialization, and
+the empty-chain case.

package/docs/admin-security-tickets.md

@@ -0,0 +1,40 @@
+# Admin Security Tickets
+
+`SECURITY_OPERATIONS_ADMIN_SECTION` adds the mount-relative `security/tickets` route to the shared admin registry. Consumers normally mount it through `ADMIN_SECTIONS`; direct imports are available from `portal-mojo/admin`.
+
+## Permissions
+
+The section and route use `sys.view_security` or `sys.security`. Mutating controls require `sys.manage_security` or `sys.security`; delete uses `sys.manage_security`. Assignee lookup is offered only with `sys.view_users`, `sys.manage_users`, or `sys.users`. These are UI gates only—the server remains authoritative for every request.
+
+## Wire contracts
+
+- Ticket collection/detail: `/api/incident/ticket`. List state uses the standard Django lookups, graph relations, paging, sorting, search, and `download_format=csv|json`. Saves accept title, description, arbitrary status/category strings, integer priority 1–10, and a nullable assignee ID.
+- Notes: `/api/incident/ticket/note`, always scoped with the ticket `parent` and, for grouped tickets, the ticket's own `group`. Operator notes require text and may atomically add one completed existing File id as `media`. Responses expose only File's reference graph. A status save creates a structured note with `metadata.type=status_change`, `old_status`, and `new_status`.
+- Ticket actions: detail POST bodies use `enable_llm`, `disable_llm`, or `push_to_maestro`. Push success means queued, not linked.
+- Maestro links: `/api/incident/maestro/item-link?ticket=<id>`. The detail modal polls for at most 30 seconds after a queued push and always offers a manual check.
+
+Unknown status/category values are appended to the known UI options and are never coerced away. Relation values may be a graph object, a bare ID, or null.
+
+## Cache and approval boundaries
+
+Every ticket mutation invalidates the Ticket model root, the record-scoped TicketNote feed prefix, and Maestro link lists. Approval and denial are new TicketNote rows with `metadata.action_response`. The response copies the pending action's `handler` and `context` without reconstructing or exposing editable JSON. Unknown handlers render a generic informational action card; the client never executes handler-specific navigation or code.
+
+Resolved actions, terminal tickets, missing manage permission, and in-flight responses disable approval controls. The server still owns replay protection and handler authorization.
+
+## Detail modal behavior
+
+Ticket titles are real buttons and both title clicks and row clicks open the
+shared KISS `modal.detail` surface without changing the current route or table
+params. The modal fetches the authoritative detail row and uses `DetailView`
+sections for Overview, permission-gated Manage controls, and Activity.
+Nested edit and confirmation modals use the native dialog stack, and closing
+the detail returns to the unchanged queue. `RecordFeed` uses compact mode and
+receives `showInput={canManage}`.
+
+Activity notes offer the shared capacity-one upload queue only while manage
+permission and an authoritative ticket/group are current. Grouped uploads use
+the ticket's group, groupless uploads use personal storage, and the completed
+manager/group lifecycle response must match before `media` can be sent. Queue
+removal never deletes File. Assistant chat and incident-detail navigation
+remain separate, and a remote Maestro URL becomes a link only when it parses as
+HTTP or HTTPS.