portal-mojo 0.1.0

package/docs/admin-members.md

@@ -0,0 +1,112 @@
+# Admin Members
+
+Reusable global membership administration for django-mojo. Import from
+`portal-mojo/admin`:
+
+```tsx
+import {
+  MembersPage,
+  MemberDetail,
+  GroupMembersPanel,
+  MemberModel,
+  MEMBERS_ADMIN_SECTION,
+  openMemberAdmissionDialog,
+  registerMemberPermissions,
+} from 'portal-mojo/admin';
+```
+
+## Wire contract
+
+`MemberModel` speaks `/api/group/member`. Its default row is:
+
+```ts
+{
+  id, created, modified, is_active,
+  permissions: Record<string, unknown>,
+  metadata: { role?: string, ... },
+  user: User | null,
+  group: Group | null,
+}
+```
+
+There is no top-level `role` or `status`: the presentation label is
+`metadata.role`, and state is `is_active`. Relation columns are rendered but
+not sortable. The model normalizes list state to verified parameters only:
+search, paging, `id|created|modified|is_active` ordering, exact group/user and
+active filters, `__icontains` lookups for user email/display name, group name
+and role metadata, plus created/modified date ranges.
+
+Supported mutations are collection create `{group,user}`, detail update, and
+the `resend_invite` POST_SAVE_ACTION. Resend returns a payload (`{status:true}`),
+not a refreshed member row. GroupMember declares neither delete nor generic
+batch support, and has no move action. Remove and Move are intentionally absent:
+a generic `{group:newId}` update is not a target-authorized move contract.
+
+Audit rows filter `/api/logs` with `model_name=account.GroupMember` and the
+membership `model_id`. `account.Member` is the obsolete web-mojo value.
+
+## Admission and the no-oracle boundary
+
+`openMemberAdmissionDialog` makes Invite and Add-existing separate choices.
+Global Members selects a group first; `GroupMembersPanel` already has a fixed
+group. Invite posts the supplied email directly to
+`/api/group/member/invite`—it never probes `/api/user`. The confirmation is
+the same whether the address is new, existing, or already associated.
+
+Add-existing is deliberately directory-backed. It appears only when the
+operator has both the Member create gate and the global user-directory gate;
+only then does the `/api/user` picker run before collection POST.
+
+## Permission tiers
+
+Every global Admin clause is system-pinned:
+
+- read: `sys.view_members | sys.view_groups | sys.manage_groups |
+  sys.manage_group | sys.groups`
+- save/create: `sys.manage_groups | sys.manage_group | sys.groups`
+- invite: `sys.manage_users | sys.manage_members | sys.manage_group |
+  sys.manage_groups`
+- directory: `sys.view_users | sys.manage_users | sys.users`
+
+Literal member `sys.*` keys always fail `memberHasPermission`, including a
+malformed dictionary containing the exact requested key. User-level system
+grants and superuser behavior in `hasPermission` are unchanged.
+
+Three permission views must remain distinct:
+
+1. Raw stored grants are the truthy keys in the JSON dictionary.
+2. Effective member grants omit literal `sys.*`, stored `full_member`, and
+   legacy `admin`; `member` is intrinsic and `full_member` is derived when
+   `guest` is false.
+3. User-level `sys.*` grants come only from the User permission dictionary.
+
+The client retains the historical non-system member `admin` wildcard for
+product portals, but django-mojo GroupMember does not honor it server-side.
+Admin is labeled as client compatibility only and is never an editable grant.
+`metadata.role` is also display-only and confers no authority.
+
+## Extensible editable grants
+
+The safe baseline includes ordinary group grants and the `guest` marker.
+Products register additional controls:
+
+```ts
+registerMemberPermissions([
+  { name: 'view_orders', label: 'View orders' },
+  { name: 'manage_orders', label: 'Manage orders' },
+]);
+```
+
+`sys.*`, `admin`, `member`, and `full_member` registrations are rejected.
+Stored deployment-specific grants without a registered editor stay visible
+and read-only rather than disappearing. Permission switches autosave through
+`FormView`; a deployment's `MEMBER_PERMS_PROTECTION` remains authoritative,
+and rejected changes revert with the server error shown.
+
+## Composition
+
+`MEMBERS_ADMIN_SECTION` is root-relative and dual-mounts as `/members` in the
+standalone Admin and `/system/members` when embedded. It never consumes active
+group context. `GroupMembersPanel` is the reusable Group-detail composition;
+pass optional `onNavigateUser` and `onNavigateGroup` callbacks to connect
+sibling identity details without coupling the package to an app.

package/docs/admin-messaging.md

@@ -0,0 +1,56 @@
+# Communications Admin
+
+```ts
+import {
+  EMAIL_ADMIN_SECTION, PUBLIC_MESSAGES_ADMIN_SECTION,
+  EmailDomainModel, MailboxModel, SentMessageModel,
+  EmailTemplateModel, PublicMessageModel,
+} from 'portal-mojo/admin';
+```
+
+The global, no-group Communications workspace mounts at `email/domains`,
+`email/mailboxes`, `email/sent`, `email/templates`, and
+`messaging/public-messages` (or under `/system` in an embedded portal). Every
+record opens in a native KISS detail modal; there are no record-detail routes
+or drawers.
+
+Email uses global `sys.manage_aws | sys.comms` for both view and mutation,
+matching django-mojo's current single tier. Contact-message view uses
+`sys.view_support | sys.security | sys.support`, status mutation uses
+`sys.manage_support | sys.security | sys.support`, and delete uses only
+`sys.manage_support`. A granular manager must also hold a view grant to open
+the page. Active-group membership never satisfies a global Admin gate.
+
+Domain credentials are write-only. Secret-bearing saves, onboarding, audit,
+reconcile, and send are imperative and never use MutationCache. Audit is POST,
+has no automatic retry, and always refreshes because it persists readiness.
+Create reports only that the row was created: django-mojo's best-effort
+create-time audit/reconcile can fail after the row exists. Delete warns that
+local mailboxes and sent audit history disappear while SES/SNS/S3/DNS
+resources may remain.
+
+Onboarding composes the shared `FormWizard`. Managed mode is available only
+when the optional DNS Admin integration resolves the normalized domain and
+uses its one record store; no provider key is submitted. Manual mode always
+shows the complete returned verification, DKIM, and MAIL-FROM records. Managed
+failure never silently retries manually because SES-side work may already
+have occurred.
+
+Sent-message and template HTML is untrusted. `SandboxedEmailPreview` uses a
+bare iframe sandbox, `referrerPolicy="no-referrer"`, an offline CSP, removed
+meta refresh, and neutralized links. Safe exports are explicit projections:
+template bodies, message bodies, BCC, template context, provider metadata,
+contact-message body/IP/user-agent/metadata, and credential masks never leave.
+
+Stable mock identities (password `mojo`):
+
+- `email.operator@nativemojo.com` — email only (`comms`).
+- `support.viewer@nativemojo.com` — contact read only.
+- `support.manager@nativemojo.com` — contact read/update/delete.
+- `support.manage-only@nativemojo.com` — delete authority but intentionally no page view.
+- `showcase.operator@nativemojo.com` — executable showcase coverage.
+
+Live verification is read-only by default. Never create/edit/delete a domain,
+replace credentials, audit, onboard, reconcile, or send without explicit
+authorization for that exact live action. SES quota is intentionally absent;
+django-mojo #1310 tracks the missing backend endpoint.

package/docs/admin-metrics-explorer.md

@@ -0,0 +1,63 @@
+# Admin Metrics Explorer
+
+`MetricsExplorerPage` is the read-only, global Admin workspace for django-mojo's recorded time-series metrics. Import it, its route contribution, or its exact adapters from `portal-mojo/admin`; import the reusable chart seam from `portal-mojo/charts`.
+
+```tsx
+import { MONITORING_ADMIN_SECTION, MetricsExplorerPage } from 'portal-mojo/admin';
+
+<MetricsExplorerPage />
+```
+
+The registered route is `/metrics/explorer` standalone and `/system/metrics/explorer` when `adminSectionRoutes()` is mounted below `/system`. Its exact any-of gate is `sys.view_metrics | sys.metrics`. That clause stays separate from the existing metrics-permission editor gate; `sys.manage_metrics` alone does not imply read access.
+
+## Discovery wire
+
+The page consumes only django-mojo #1438:
+
+```text
+GET /api/metrics/discover?resource=accounts|categories|slugs
+```
+
+`discoverMetrics()` uses `mojoCall`, because the stable response fields `resource`, `filters`, `count`, `page_count`, and `next_start` are top-level envelope metadata that `mojoList` would discard. It validates the exact resource/filter echo and internally consistent paging before returning a `MetricsDiscoveryPage`. Permission failures reject; they never become an empty authorized catalog.
+
+Account entry accepts exact `public`, `global`, `group-<positive-id>`, `user-<positive-id>`, or a bounded opaque custom account. Invalid reserved forms do not fall back to custom interpretation. Registry selection is URL-backed, with one repeated `slug` parameter per full slug. Comma-bearing slugs are reported as unaddressable because history endpoints use a comma-delimited request grammar.
+
+Group and User `CollectionSelect` conveniences are separate capabilities. They mount only under `sys.view_groups|sys.manage_groups|sys.groups` and `sys.view_users|sys.manage_users|sys.users`, respectively. Without those clauses the exact account input remains available and no directory picker request can start.
+
+## Full-slug identity
+
+Full colon-bearing strings are the client identity. The backend responses are deliberately asymmetric:
+
+- `/api/metrics/fetch` and fan-out sum key each dataset by the last colon segment;
+- `/api/metrics/series?with_delta=true` preserves full keys;
+- `/api/metrics/value/get` again truncates to the last segment.
+
+`loadExactMetricSeries()` repairs history at the boundary. It batches globally unique tails, splits every member of a duplicate-tail group into its own request, validates exact response keys and compatible labels, and reassembles datasets in original request order. It rejects missing, extra, or ambiguous results. Fan-out breakdown requires one slug and preserves the returned child labels plus required `groups` map. `fetchMetricPoints()` validates full-key current/previous/delta maps, including the valid previous-zero case where `delta_pct` is absent. `readMetricValue()` reads one exact full slug per request.
+
+History uses `dt_start` and `dt_end` epoch seconds. `dr_*` belongs to model-list aggregation and is never emitted here. The explorer has no record, value-set, permission mutation, or arbitrary `_mode` surface.
+
+## Chart seam and cache
+
+`MetricsChart` adds these optional props without changing existing callers:
+
+```ts
+loadSeries?: MetricsSeriesLoader;
+seriesCacheKey?: string;
+childKind?: string;
+breakdown?: boolean;
+preserveSeriesLabels?: boolean;
+```
+
+The default loader remains `mojoMetrics` and repairs a tail-only response key when the configured full-slug set makes that mapping unique; ambiguous duplicate tails still require the exact loader. A custom loader must supply a stable namespace through `seriesCacheKey`; the namespace is part of the TanStack key so exact explorer data cannot reuse a cached lossy default response. The explorer namespace and every discovery/KPI/scalar key use the synchronous auth-token uid. Protected reads stay disabled until the async `me` identity agrees with that uid, preventing boot or direct identity switches from caching authenticated data under a shared placeholder.
+
+## Fan-out, KPI, scalar, and export
+
+Fan-out appears only for a parsed group account. Sum supports multiple selected slugs through the collision-safe adapter. Breakdown limits selection to one slug and requires an explicit child kind. KPI tiles issue one `/series?with_delta=true` request at an explicit `when` and granularity.
+
+The scalar card reads a known exact slug and opens the standard KISS native-dialog detail. Its optional scale changes presentation only; raw values remain visible. There is no gauge catalog or fabricated health classification.
+
+Chart CSV export flows through shared `csvEscape()`. String cells beginning with `=`, `+`, `-`, `@`, tab, or carriage return gain a leading apostrophe before normal RFC quoting. Numeric negatives remain numeric.
+
+## Styling
+
+The explorer extends the semantic `admin-monitoring.css` token stylesheet used by the Portal and showcase. It adds no UI or chart dependency. Consumers already including the Monitoring section stylesheet need no additional CSS entry.

package/docs/admin-monitoring.md

@@ -0,0 +1,99 @@
+# Admin monitoring
+
+`portal-mojo/admin` packages the immutable Logs feed, one-record log inspector,
+read-only Metrics Explorer, and metrics-permission administration for standalone
+or embedded admin portals. See [admin-metrics-explorer.md](admin-metrics-explorer.md)
+for the discovery, identity, KPI, fan-out, scalar, and cache contracts.
+
+## Admin registration and gates
+
+`MONITORING_ADMIN_SECTION` contributes three root-relative routes:
+
+| Route | Component | Any-of gate |
+|---|---|---|
+| `/logs` | `LogsPage` | `sys.manage_logs`, `sys.view_logs`, `sys.security` |
+| `/metrics/explorer` | `MetricsExplorerPage` | `sys.view_metrics`, `sys.metrics` |
+| `/metrics/permissions` | `MetricsPermissionsPage` | `sys.manage_incidents`, `sys.metrics`, `sys.manage_metrics` |
+
+The section clause is the union of these route audiences, while each route
+retains its exact clause. In particular, `sys.view_metrics` reveals only the
+explorer, `sys.metrics` reveals explorer and editor, and `sys.manage_metrics`
+reveals only the editor. The `sys.` prefix is intentional: these are global operator surfaces and must
+not inherit a similarly named active-group permission. `adminSectionRoutes()`
+wraps each component before it mounts, so a denied direct route cannot fetch.
+The backend remains authoritative.
+
+```tsx
+import {
+  MONITORING_ADMIN_SECTION,
+  adminSectionRoutes,
+  adminSectionsMenu,
+} from 'portal-mojo/admin';
+
+const sections = [MONITORING_ADMIN_SECTION];
+const routes = adminSectionRoutes(sections, { mount: '/system' });
+const menu = adminSectionsMenu(sections, { mount: '/system' });
+```
+
+## Logs and inspector
+
+```tsx
+import { LogsPage, LogInspector, LogModel, type LogRow } from 'portal-mojo/admin';
+
+<LogInspector log={row} />
+```
+
+`LogsPage` is the canonical `/api/logs` table: server search/filter/sort,
+day grouping, column persistence, export, quick-look chevron, and a full-size
+row-click inspector. The table is read-only because log rows are immutable
+records. The chevron cell stops propagation in `ModelTable`, so expanding a
+quick look does not also open the inspector.
+
+`LogModel` therefore publishes only its exact view gate. Although the backend
+has separate `security|admin` save and `admin` delete gates, this immutable
+package surface advertises no `manage` contract or mutation control. The
+client's normal admin/superuser wildcard remains separate from `sys.security`.
+
+The inspector recognizes explicit request and response `kind` tokens. All
+other kinds are messages. The `log` field is the primary stored content and is
+labelled “Stored request content,” “Stored response content,” or “Message” from
+that kind. `payload` is always labelled “Auxiliary payload”; it is never
+presented as the response body. The inspector also renders request context,
+user, device, IP, related model, and user agent. Valid JSON goes through
+`JsonBlock`; everything else is a React text child in a `<pre>`. HTML-looking
+stored data is never an HTML rendering boundary. Clipboard absence and rejected
+writes surface an error toast instead of reporting false success.
+
+A response row is only a stored response row. `/api/logs` exposes no request
+correlation key, so the inspector never searches for or claims a paired request.
+
+## Metrics permission wire
+
+The endpoint is Redis-backed and intentionally not modeled as a paged
+`ModelTable`:
+
+- `GET /api/metrics/permissions` returns a normal `{data, count}` envelope.
+  The complete set is normalized and sorted by account in the client because
+  Redis ordering is nondeterministic.
+- A permission value may be a single string, an array, or `null`; all normalize
+  to `string[]` for the controlled `TagInput` fields.
+- `POST /api/metrics/permissions/<encoded-account>` sends
+  `view_permissions` and `write_permissions` as CSV strings.
+- The POST result is asymmetric: `account`, `view_permissions`, and
+  `write_permissions` are top-level envelope fields, not nested under `data`.
+- `DELETE /api/metrics/permissions/<encoded-account>` clears both permission
+  keys. It does not delete the metrics account registry entry, so the table
+  refetches authoritatively and retains the row with empty tags.
+
+Accounts are immutable in this surface. There is no fake add, search, paging,
+or client table framework. Every save and clear refetches the authoritative
+list. Empty tags are submitted as empty CSV strings, matching the backend's
+current contract.
+
+## Styling and showcase
+
+Monitoring components use semantic `monitoring-*` classes and application
+tokens only. A consuming app must include `admin-monitoring.css`. This repo's
+portal and showcase theme entries do so. The showcase's Admin Monitoring demo
+contains static request, response, JSON, and HTML-looking plain-text cases for
+both-theme verification without mutating a backend.