portal-mojo 0.1.0

package/docs/admin-settings.md

@@ -0,0 +1,78 @@
+# Admin settings
+
+`portal-mojo/admin` provides a real django-mojo runtime-settings administrator
+for standalone and embedded portals. It replaces static settings-demo data with
+the `/api/settings` model while keeping write-only values out of client caches.
+
+## Routes and access
+
+Register `SettingsPage` at the section index. Selecting a row opens
+`SettingDetail` through the shared KISS modal; there is no `:id` child route.
+The route and sidebar contribution require either `sys.manage_settings`
+or `sys.groups`, mirroring `Setting.RestMeta` while ensuring active-group member
+permissions cannot open a fleet-wide settings surface.
+
+```tsx
+{
+  id: 'settings',
+  title: 'Settings',
+  icon: 'bi-gear',
+  permissions: SETTINGS_PERMISSIONS,
+  routes: [
+    { path: '', component: SettingsPage, permissions: SETTINGS_PERMISSIONS },
+  ],
+}
+```
+
+`SettingsPage` searches only the key (the backend's sole `SEARCH_FIELDS`
+entry), and offers server filters for `is_secret` and `group__isnull`. Keys are
+immutable after creation. Operators with `sys.groups` may change scope, sending
+a group id or explicit `null` for Global. A `sys.manage_settings`-only operator
+sees the current scope read-only; the editor never mounts the group picker or
+queries `/api/group`, and preserves that scope on save. New settings default to
+Global. Delete is intentionally absent because live `Setting.RestMeta` does not
+declare deletion.
+
+## Atomic write contract
+
+Use `saveSettingAtomic()` / `buildSettingPayload()` rather than a generic
+autosave. django-mojo processes fields against the model's current secrecy
+state in request insertion order. Create-secret remains `is_secret → value`.
+An existing Plain→Secret transition must be `value → is_secret`, so the current
+plain row still holds the replacement when the flag flips and the pre-save hook
+encrypts it. Secret→Plain is the reverse: `is_secret → value`, so the explicit
+replacement lands as plain text. Same-secret replacement sends only `value`.
+
+Both transitions require an explicit replacement; a new secret or a
+Plain→Secret transition requires a non-empty secret, while Secret→Plain may
+explicitly replace it with an empty plain value. An unchanged secret with a
+blank replacement omits `value`; an unchanged plain setting may intentionally
+save an empty string. A no-op makes no request.
+
+The custom save bypasses TanStack MutationCache because mutation variables
+retain submitted bodies. Its response passes through `SettingModel` sanitation
+before it may enter Query cache. For secret rows, the cache contains only the
+masked `display_value`; the `value` property is removed. Success toasts are
+generic and backend failures stay in the form; neither interpolates a submitted
+value.
+
+## Editor behavior
+
+The replacement textarea is deliberately uncontrolled. Existing secret rows
+seed it with an empty string—never `******`—and switching secret status clears
+the control and marks it as needing an explicit replacement. Backend collision
+and registered-key validation messages stay visible in the modal.
+
+## Exports
+
+```ts
+import {
+  SettingModel,
+  SettingsPage,
+  SettingDetail,
+  SETTINGS_PERMISSIONS,
+  SETTINGS_ADMIN_SECTION,
+  buildSettingPayload,
+  saveSettingAtomic,
+} from 'portal-mojo/admin';
+```

package/docs/admin-shortlinks.md

@@ -0,0 +1,32 @@
+# Shortlinks Admin
+
+Import from `portal-mojo/admin`. `SHORTLINKS_ADMIN_SECTION` contributes
+`shortlinks/links` and `shortlinks/history` to the global, no-group
+Communications navigation. Both routes require `sys.manage_shortlinks`.
+
+## Privacy boundary
+
+django-mojo's `graph=list` includes the destination `url`. `ShortlinkModel`
+therefore applies a positive row projection inside the query function before
+TanStack Query receives a row. Destinations and metadata are omitted.
+
+Click history is manage-only and projects raw records into: click id, shortlink
+id/code, bot classification, timestamp, a bounded browser/bot summary, and an
+HTTP(S) referrer origin. IP addresses, raw user-agent strings, referrer
+path/query/fragment, metadata, and nested `shortlink.url` are never cached.
+Neither table supports search or export, and list parameters are allowlisted.
+
+## Mutations and short URLs
+
+Create, active-state changes, and delete are imperative one-shot requests. They
+do not claim fresh-auth protection the backend does not provide and do not use
+retrying mutation hooks. Every outcome runs an authoritative reconciliation in
+`finally` semantics. If reconciliation itself fails, the UI warns that the
+change may have persisted and blocks retry until a successful refresh.
+
+Short URLs are `${apiOrigin()}/s/{code}` (or `/s/{code}` for the same-origin
+mock). The package makes no canonical-host claim.
+
+Human and bot totals are counts of retained tracking records. The displayed
+remainder is `max(0, hit_count - human - bot)`; `hit_count` also includes hits
+made while tracking was disabled.

package/docs/admin-storage.md

@@ -0,0 +1,141 @@
+# Storage Admin
+
+```ts
+import {
+    STORAGE_ADMIN_SECTION, BucketsPage, BackendsPage, FilesPage, FileView,
+    FileUploadSurface, FileManagerModel, FileManagerUploadPolicyModel, FileModel,
+} from 'portal-mojo/admin';
+```
+
+`STORAGE_ADMIN_SECTION` contributes global/no-group Infrastructure routes at
+`storage/buckets`, `storage/backends`, and `storage/files` (or the same paths
+under an embedded `/system` mount). There are no record routes: buckets,
+backends, nested files, and files use `modal.detail`.
+
+## Permissions
+
+- Buckets: `sys.manage_aws | sys.files`.
+- Backends/Files view: `sys.view_fileman | sys.manage_files | sys.files`.
+- Backend/File mutations: `sys.manage_files | sys.files`.
+- Add File, its whole-page drop surface, and upload destination requests mount
+  only with the File mutation grant.
+- Group and user selectors mount only with their respective system-pinned
+  directory grants. Admin never reads an active group.
+
+The section audience is the union of child audiences; each route retains its
+exact clause. A member-only grant cannot satisfy any Storage route.
+
+## Buckets
+
+`GET /api/aws/s3/bucket` is one complete account inventory, rendered with
+explicitly local name search/order and no paging claims. Failed inventory is
+an Error/Retry state, never “No buckets.”
+
+All writes are `POST /api/aws/s3/bucket/<encoded-name>`:
+
+- create: `{}` → `{id,name,created_new:true|false|null}`;
+- access: `{set_public:boolean}` → verified `is_public`, `complete:true`,
+  `mutation_state:'complete'`;
+- empty: `{empty:{confirm_name:name}}` under `withFreshAuth`, after an
+  `ArmedButton` and exact case-sensitive UI confirmation.
+
+Every POST invalidates and actively refetches in `finally`. A primary failure
+is preserved if refresh also fails. HTTP 409
+`s3_operation_incomplete` retains finite `none|partial|unknown` evidence,
+acknowledged counts, classified failures, nullable remaining values, and the
+access safety-lock posture without fabricating zeros or atomic completion.
+Bucket DELETE is absent.
+
+## Backends
+
+`FileManagerModel` forces `graph=list` and allowlists graph fields before any
+cache write. Readable credentials are masks only. Credential inputs begin
+blank; blank means preserve. `saveFileManagerAtomic` runs imperatively outside
+MutationCache, strips masks and blank secrets, fresh-auth retries the same
+closure, refetches authoritatively, and compares requested owner FKs.
+
+Creation supports runtime backends `file` and `s3`, explicitly starts private,
+and requires an authorized group/user owner unless the caller is superuser and
+chooses System. Supported payload actions are `test_connection`, `check_cors`,
+`fix_cors`, and `clone`; inner `{status:false}` rejects. CORS is S3-only.
+FileManager DELETE and `check_public_access` are absent.
+
+## Files and capability URLs
+
+`FileModel` forces the list graph and normal saves to `filename`, `is_public`,
+and explicit `group`. Group moves refetch and compare the authoritative FK.
+Selection supports public/private, explicit prepared group move, safe
+same-gesture download, and all-settled confirmed delete. Authorized operators
+also get **Add File** and a drag-only whole-page drop overlay. Both open one
+configuration modal; the bounded queue lives above it, so closing the modal
+does not cancel work or discard outcomes.
+
+Every batch chooses an explicit manager. System choices request only active
+`graph=upload_policy` rows with null group/user owners. Group choices first use
+the independently gated active-group directory, then request null-user policy
+rows for that exact group. User-owned and dual-owned managers never enter these
+Admin lists. The safe policy projection contains only name/use, size,
+extension/MIME guidance, and transfer-route support. A false
+`supports_direct_upload` means a local API target, not an unavailable manager.
+
+The queue caps at six files and three concurrent transfers. It reports actual
+byte progress, truthful cancel/retry/recovery, partial acceptance, and uncertain
+remote state. Permission loss closes the destination modal, stops its queries,
+and best-effort cancels queued transfers. Completion compares authoritative
+scalar `file_manager_id`/`group_id` with the immutable destination. Terminal
+changes coalesce into one authoritative active Files refetch plus one trailing
+pass; refresh failure remains visible and current filters may hide the new row.
+
+Each task owns a private strict `idempotency_key`. A lost initiation response
+reuses it to recover the same File. A server-proven failed/expired lifecycle
+rotates it and creates a fresh attempt on the same Retry click. Keys, browser
+`File` objects, targets/tokens, and completion payloads never enter Query or
+persistent storage.
+
+File, thumbnail, rendition, and share URLs are bearer capabilities. The shared
+validator accepts ordinary relative paths or explicit `http:`/`https:` URLs
+without userinfo, and rejects protocol-relative, malformed, `javascript:`, and
+`data:` values. Open/Download uses an anchor with `rel=noreferrer`. Safe exports
+omit every URL, storage path, mask, metadata object, token, and transient.
+
+`FileView` sections are Overview, Preview, Details, Renditions, Shares, and
+Metadata. Category precedes MIME fallback: image inline; native audio/video;
+PDF open; office-like documents use the best safe image rendition; archive
+downloads; text/CSV/unknown remain generic. No returned HTML is embedded.
+`StableMediaPreview` captures its safe source for the mounted File id so normal
+query refreshes do not replace the media node; reopening refreshes policy.
+
+## Renditions and shares
+
+Role-keyed rendition objects normalize to stable rows. Signatures include
+role, rendition id, status, modified, width, height, and size. Recursive
+non-overlapping polling waits five seconds, makes at most 12 fetch attempts,
+and stops on signature change/arrival, failed or expired upload, close/id
+change, or timeout. Timeout leaves manual Refresh.
+
+Regeneration sends `{regenerate_renditions:true|string[]}` with deduped roles
+capped at 20. Share creation sends `{share:true|options}` imperatively; options
+and the newly returned capability URL stay in one modal-local result and never
+enter Query/Mutation caches. The response parser uses the collision-safe
+`shortlink_code` key and validates the ISO `expires_at`. Separately authorized
+rows are labeled “Visible shares”; the backend owner fallback remains available
+without granting global Shortlinks Admin. Safe `track_clicks` and bounded note
+values are retained, and operators can use the live active toggle or permanent
+DELETE contract.
+
+## Mock and verification
+
+The central mock owns bucket, FileManager, File, upload attempts/byte sessions,
+canonical rendition, and shortlink rows. It implements the safe policy graph,
+flat lifecycle/target response, idempotent replay, terminal retry, and local or
+provider paths. Credential writes derive masks and discard raw values. Stable
+personas are `storage.viewer@nativemojo.com`,
+`storage.manager@nativemojo.com`, `bucket.manager@nativemojo.com`, and
+`storage.member@nativemojo.com` (password `mojo`); the showcase operator has
+the broad demo grants.
+
+Run `npm run verify:admin-storage`, `npm run verify:file-upload`, and
+`npm run verify:upload-ux` for the focused route, permission, upload,
+cache-safety, URL, FK-reconciliation, and bounded-polling contracts. Browser
+evidence belongs in the Portal mock for viewer/member gates and in Showcase
+for the exported surface, in both themes.

package/docs/auth-pages.md

@@ -0,0 +1,212 @@
+# auth-pages — in-app sign-in surfaces, step-up challenges, password tools
+
+The C3 layer over [auth.md](auth.md)'s client: the portal's own login /
+forgot / reset / magic-link pages (for deployments serving the portal
+same-origin with the API), the fresh-auth (step-up) modal, and the password
+strength/generator pieces. Board #1259.
+
+```ts
+// The package pieces
+import {
+    // MFA completion (consumes the mfa_token from login()'s 'mfa' result)
+    completeMfaTotp, completeMfaRecovery, sendMfaSms, completeMfaSms,
+    // Fresh-auth (step-up) challenge surface
+    REAUTH_STATUS, isReauthRequired, setFreshAuthHandler, requestFreshAuth,
+    withFreshAuth, sessionIsPersistent,
+    type MfaChallenge, type FreshAuthHandler, type MfaCompletionOptions,
+} from 'portal-mojo/client';
+
+import {
+    checkPasswordStrength, generatePassword, PasswordStrengthMeter,
+    type PasswordStrength, type PasswordStrengthClass, type GeneratePasswordOptions,
+} from 'portal-mojo/ui';
+```
+
+The pages themselves are APP surfaces (`apps/portal/src/pages/auth/`):
+`LoginPage`, `ForgotPage`, `ResetPage`, `MagicPage`, `MfaPanel`,
+`FreshAuthHost`, `AuthLayout` — wired through `routes.tsx`, which exports
+`authRoutes`, `RequireAuth`, and `handleAuthTokenLanding()`.
+
+## Config switch
+
+`VITE_MOJO_AUTH` (env, same idiom as `VITE_MOJO_API`):
+
+| Value | Behavior |
+|---|---|
+| `inapp` | Unauthenticated visits route to `#/auth/login` (these pages) |
+| `hosted` | Unauthenticated visits bounce to the django-mojo hosted `/auth` pages (bouncer pages, incl. the bot-check interstitial — which exists on the hosted path ONLY) |
+| unset | **hosted when `VITE_MOJO_API` is set** (the default for real deployments), in-app under the mock (there is no hosted page to bounce to) |
+
+Unknown values fall back to the unset default WITH a `console.warn`.
+`hosted` + mock also warns and falls back to in-app. Resolution lives in
+`pages/auth/config.ts` (`authMode()` / `inAppAuthEnabled()`).
+
+## Route guard
+
+`RequireAuth` wraps the App route element (`<RequireAuth><App/></RequireAuth>`;
+`authRoutes` mount as top-level SIBLINGS — auth pages are full-screen, no app
+chrome). Unauthenticated (per the A1 snapshot: no valid access OR refresh
+token) → in-app login (intended route stashed in
+`sessionStorage['portal:auth-return']`, restored after any successful flow)
+or the hosted redirect (which keeps auth.ts's own stash). Authenticated →
+children plus `<FreshAuthHost/>`. A signed-in visit to `#/auth/login`
+bounces to `/` (web-mojo AuthApp guard parity); the forgot/reset/magic pages
+stay reachable signed-in — completing them re-logs-in by design (the server
+answers with a full TokenGrant).
+
+## Flows (all on the A1 client — no new wire code in pages)
+
+- **Password**: `login()` → tokens stored, or `{kind:'mfa'}` → `MfaPanel`.
+  Remember-me checkbox maps to `LoginOptions.remember` (localStorage vs
+  sessionStorage).
+- **MFA step** (`MfaPanel`, shared with the fresh-auth modal). Methods from
+  the server: `totp` (code → `completeMfaTotp`; recovery-code toggle →
+  `completeMfaRecovery`), `sms` (`sendMfaSms` **consumes and re-issues the
+  mfa_token — always replace your stored token with the returned one**, then
+  `completeMfaSms`), `passkey` (a full `loginWithPasskey()` ceremony IS the
+  second factor — django-mojo's passkey login never routes through the MFA
+  gate). Unknown methods are dropped with a `console.warn`. The challenge
+  expiry (`expiresIn`, default 300s) is counted down visibly.
+- **Forgot/reset**: `forgotPassword(email, 'code'|'link')`; code → ResetPage
+  code mode (email carried via router state + a sessionStorage stash so
+  reloads survive); link → lands on ResetPage token mode. Both resets log
+  the user in on success. The reset form carries the live
+  `PasswordStrengthMeter` + a generator affordance (fills both fields,
+  reveals the value). Strength is ADVISORY — submission is never blocked on
+  it; the server owns password policy.
+- **Magic link**: request via `sendMagicLink`; the landing auto-exchanges
+  `loginWithMagicToken` ONCE (StrictMode-proof ref guard — `ml:` tokens are
+  single-use) with progress/error UI.
+- **Passkey**: `loginWithPasskey(username?, {remember})` behind `isPasskeySupported()`;
+  no username → discoverable-credential prompt. The ceremony is fully built;
+  REAL-authenticator verification is deferred (mock validates shape only).
+  The remember choice is explicit because MFA and fresh-auth passkey paths
+  must not promote a sessionStorage session into localStorage.
+
+## Token-landing URL shapes
+
+django-mojo's `build_token_url` produces
+`{WEBAPP_BASE_URL}{WEBAPP_AUTH_PATH}?flow=<flow>&token=<tok>` with `pr:`
+(password_reset) / `ml:` (magic_login) token prefixes. Both landing shapes
+work:
+
+- **Real search** (`/?flow=password_reset&token=pr:…` — WEBAPP_AUTH_PATH
+  points at the portal root): `handleAuthTokenLanding()` at boot scrubs
+  flow/token from the real URL **synchronously, before any network call**
+  (the auth_code discipline) and hash-routes to the landing page.
+- **Hash query** (`/#/auth?flow=…&token=…` — WEBAPP_AUTH_PATH points at
+  `/#/auth`): the `/auth` index route dispatches by token prefix, then flow.
+
+The landing pages capture the token once at mount and scrub it from the
+hash query before exchanging.
+
+## Fresh-auth (step-up) challenges
+
+django-mojo's freshness gate (`account/services/fresh_auth.py`,
+`FRESH_AUTH_WINDOW`, default off): sensitive operations answer **HTTP 440 /
+`reauth_required`** when the JWT's `auth_time` is too old. A token refresh
+can NEVER satisfy it — refreshes carry `auth_time` forward unchanged; only
+a genuine re-login mints a new one. That is why 440 is not 401: it must not
+trigger the refresh path.
+
+Client surface (`portal-mojo/client`):
+
+- `isReauthRequired(error)` — MojoError with status/`error_code` 440 or
+  message `reauth_required`.
+- `setFreshAuthHandler(handler)` — the app registers ONE UI handler;
+  `FreshAuthHost` (mounted by `RequireAuth`) does this.
+- `requestFreshAuth()` — single-flight prompt: a burst of gated calls
+  shares one modal. No handler → `console.warn` + resolve false.
+- `withFreshAuth(fn)` — run fn; on a 440 prompt, then retry **once** after a
+  successful re-login; a dismissed prompt rejects with the ORIGINAL error.
+
+The modal re-prompts credentials OVER the current screen — page state
+survives. It pins the identity to the current session's email (step-up is
+"prove you are still you"), offers password + passkey + the MFA step, and
+keeps the session in its original storage (`sessionIsPersistent()` →
+`remember`). Dev affordance: `__mojo.requestFreshAuth()` in the console
+exercises the modal without a 440.
+
+Call-site pattern:
+
+```ts
+await withFreshAuth(() => save(changes));   // a 440 prompts + retries once
+```
+
+`defineModel().useSave()` and `.useAction()` wrap their mutation functions in
+this flow globally. Mutation variables are closed over unchanged and the
+normal success/cache path runs only after the retry succeeds. `useDelete()`
+and direct `mojoCall()` calls remain explicit opt-ins: their sensitivity and
+retry safety are endpoint-specific.
+
+Deployment note: a deployment enforcing `BOUNCER_REQUIRE_TOKEN` gates
+`/api/login` behind the bouncer token, which in-app surfaces do not carry
+(`LoginOptions.extra.bouncer_token` is the seam) — the modal will surface
+the server's 403 verbatim there; hosted mode is the supported posture for
+bouncer-enforcing deployments.
+
+## Password tools (`portal-mojo/ui`)
+
+- `checkPasswordStrength(password)` → `{score, strength, feedback, details}`
+  — web-mojo MOJOUtils scoring, EXACT: length bands (+1/+3/+4), variety
+  (+1 lower, +1 upper, +1 digits, +2 special), one -1 common-pattern
+  penalty, common-password `max(0, score-3)`, thresholds <2/<4/<6/<8 →
+  very-weak/weak/fair/good/strong, same feedback strings. 22 headless
+  assertion groups verified the port (entropy classes, floors, praise
+  lines, edge inputs).
+- `generatePassword(options?)` — same option surface and guarantees
+  (defaults incl. length 12, one char per included class, `customChars`
+  override skips the guarantee, `excludeAmbiguous` strips i/l · I/O/L ·
+  0/1 · |, length < 4 throws, empty pool throws). ONE documented deviation:
+  crypto.getRandomValues + Fisher–Yates replaces web-mojo's Math.random and
+  biased sort-shuffle — a non-crypto RNG in a password generator is a trap,
+  not a feature.
+- `<PasswordStrengthMeter password showFeedback? />` — 5-segment bar +
+  label + feedback, colored via tokens through `data-strength`
+  (bad/warn/info/ok), both themes free. Empty input renders an idle unlit
+  state instead of the scorer's non-empty-string complaint.
+
+## Mock affordances
+
+Under the mock transport the pages show inline dev hints: password `mojo`
+for any seeded user (e.g. `ian@mojoverify.com`); Maya (seeded user 2) requires
+MFA; TOTP `123456`, recovery `mock-recovery`, and SMS `654321`; reset code
+`123456`; token formats `pr:mock-<id>` / `ml:mock-<id>`. MFA tokens are
+expiring and single-use. The mock follows the measured runtime behavior:
+TOTP/recovery/SMS attempts burn the token before code validation, and
+`sms/send` burns then re-issues it (older web docs claiming otherwise are
+stale). Login's mock-only `__mock_mfa_ttl` can make expiry immediate.
+
+Arm a real one-shot 440 path from the dev console with
+`__mojo.armMockReauth('POST', '/api/user/1')`. Matching includes method and
+exact path, runs after bearer authentication, and is consumed only by the
+first authenticated match. This makes anonymous 401, unrelated requests,
+the first matching 440, retry success, and later normal calls reproducible.
+
+## Deferred (explicitly)
+
+- **OAuth redirect flows** — re-deferred with a code-level seam
+  (`TODO(C3-deferred)` in auth.ts documents the full verified wire:
+  `GET /api/auth/oauth/<provider>/begin` → `{auth_url, state}` → provider →
+  backend callback → 302 to the frontend with `?code=&state=` →
+  `POST …/complete`). Blocked on: server-side redirect-uri allowlisting,
+  deployment-specific providers (`GET /api/auth/config` → `login.methods`),
+  and no way to exercise the round-trip against the mock or without real
+  provider credentials. Hosted pages cover OAuth deployments today.
+- **Passkey real-authenticator verification** — the ceremony is fully
+  built on auth.ts; verifying against a real authenticator + a live
+  django-mojo passkey registration is Ian's post-merge pass.
+
+## Pitfalls
+
+- `auth/sms/send` BURNS the mfa_token it received and returns a new one —
+  verifying with the old token fails. MfaPanel handles this; any new UI
+  must too.
+- Never route a 440 into the token-refresh path; the server chose 440
+  precisely so 401-refresh machinery ignores it.
+- `ml:`/`pr:` tokens are single-use: exchange exactly once (StrictMode
+  double-effects will burn them — use a ref guard, as MagicPage does).
+- The auth pages must stay OUTSIDE `RequireAuth` and OUTSIDE the App shell
+  (they are route siblings, not children).
+- Keep the `?auth_code=` scrub-before-network behavior in auth.ts intact —
+  `handleAuthTokenLanding()` follows the same discipline for `?token=`.

package/docs/auth.md

@@ -0,0 +1,58 @@
+# auth — session client + hosted-auth bridge
+
+```ts
+import {
+    initAuth, login, logout, onAuth, useAuthSnapshot,
+    handleAuthCodeFromURL, hostedAuthUrl, redirectToHostedAuth,
+    sendMagicLink, loginWithMagicToken, handleMagicTokenFromURL,
+    forgotPassword, resetPasswordWithCode, resetPasswordWithToken,
+    loginWithPasskey, isPasskeySupported,
+} from 'portal-mojo/client';
+```
+
+## Boot (once, before render)
+
+```ts
+initAuth();                       // installs the pre-request gate + Authorization header + refresh watcher
+void handleAuthCodeFromURL();     // returning from the hosted /auth pages (no-op otherwise)
+onAuth('login',  () => queryClient.invalidateQueries());   // identity changed →
+onAuth('logout', () => queryClient.invalidateQueries());   // every cached answer is suspect
+```
+
+## Session mechanics
+
+- JWT pair (`access_token`/`refresh_token`); single-flight refresh (3
+  concurrent 401s → ONE refresh POST); pre-request gate throws a synthetic
+  `AuthRequiredError` instead of firing doomed requests.
+- `useAuthSnapshot()` → `{authenticated, uid, email}` — live, cross-tab.
+- `logout()` is client-side (django-mojo has no logout endpoint) and emits
+  `'logout'`.
+- Events for `onAuth`: `'login' | 'logout' | 'refreshed' | 'refresh-failed'
+  | 'unauthorized'`.
+
+## Hosted auth pages (the django-mojo "bouncer" pages)
+
+The backend serves themed login/register pages at `<origin>/auth` (behind
+its bot-check interstitial). Flow:
+
+1. `redirectToHostedAuth()` — stashes the current hash route in
+   sessionStorage, then navigates to
+   `<origin>/auth?redirect=<HASH-FREE current url>`. Hash-free is
+   load-bearing: the page string-appends `?auth_code=<code>` to the
+   redirect, and a `#` in it would swallow the code.
+2. User signs in on the hosted page; it mints a single-use 60s handoff code
+   (`POST /api/auth/handoff`) and navigates back with `?auth_code=`.
+3. `handleAuthCodeFromURL()` (boot) exchanges it (`POST /api/auth/exchange`),
+   scrubs the code from the URL synchronously, restores the stashed route.
+   Handles a hash-embedded `#/route?auth_code=` landing too.
+
+`hostedAuthUrl()` returns null under the mock transport — there is no page
+to host; the UI should fall back to a dev affordance (`__mojo.login(...)`).
+
+## Direct flows (for in-app auth pages)
+
+`login(username, password)` → `{kind: 'authenticated', user}` or an MFA challenge;
+magic-link (`sendMagicLink` → `loginWithMagicToken`), password reset (code
+and token variants), passkeys (`loginWithPasskey`; ceremony fully ported,
+mock validates shape only). All reject with the server's message on
+failure.

package/docs/calendar.md

@@ -0,0 +1,122 @@
+# Calendar engine + date fns
+
+The picker core ported from web-mojo's dependency-free calendar
+(`calendar/Calendar.js` + `utils/dateFns.js`): ONE engine covering
+day/month/year precisions, single + range selection, drill-down zoom, and
+1–2 day panes. Popover, trigger inputs, and preset rails are separate
+components built ON this — the engine renders inline and owns no
+positioning.
+
+```ts
+import { Calendar } from 'portal-mojo/ui';
+import { dateFns } from 'portal-mojo/ui';   // namespace, like fmt
+```
+
+## Value shapes (the contract)
+
+- Canonical strings at each precision: `YYYY-MM-DD` / `YYYY-MM` / `YYYY`.
+  Everything the engine emits and accepts (`value`, `startValue`, `min`,
+  `disabledDates`, callback payloads) speaks these.
+- Parsed shapes are plain int objects — `{y}`, `{y,m}`, `{y,m,d}`
+  (`ParsedYear/ParsedYm/ParsedYmd`, union `ParsedDate`). `Date` objects
+  never leak out of the fns; all math is browser-local (DST-safe), never
+  UTC.
+
+## `<Calendar>` API
+
+| Prop | Notes |
+|---|---|
+| `precision` | `'day' \| 'month' \| 'year'` (default `day`) — the grid that COMMITS. Unknown values warn + fall back to `day`. |
+| `mode` | `'single' \| 'range'` (default `single`) |
+| `months` | `1 \| 2` day-view panes (default 1; clamped) |
+| `value` | single mode — controlled canonical string (or null) |
+| `startValue` / `endValue` | range mode — controlled canonical strings |
+| `min` / `max` | bounds, compared at the PANE precision being painted: with `min="2026-03-15"` the March-2026 month tile and 2026 year tile stay enabled; only cells wholly out of bounds disable |
+| `disabledDates` | `YYYY-MM-DD[]`, day grids only |
+| `firstDay` | 0=Sun … (default 1=Mon); reorders weekday header + grid offsets |
+| `locale` | BCP-47 for month/weekday names (default `en-US`) |
+| `year` / `month` | initial page override (otherwise the selection, else today) |
+| `onSelect` | `{value, parsed}` — single-mode commit at precision |
+| `onRangeSelect` | `{start, end}` — ordered (ends swap if picked backwards) |
+| `onRangeStart` | `{anchor}` — first range click; nothing committed yet |
+| `onRangeCancel` | Escape pressed with an anchor in progress |
+| `onViewChange` | `{view}` — zoom changed (drill-down or header click) |
+| `onNavigate` | `{delta}` — page changed (buttons or PageUp/PageDown) |
+
+**Selection is controlled.** A commit fires the callback; the cell paints
+selected only after the owner writes the prop back. Prop writes carry the
+source's programmatic semantics: a new `value` re-pages the calendar to it;
+a new `startValue`/`endValue` pair cancels any in-progress anchor
+(`setRange`). View, page, anchor and hover are internal state — paging and
+zooming never round-trip through the owner.
+
+## Behavior invariants (from source, keep them true)
+
+- **Drill-down zoom:** header label zooms out day→month→year (a `<button>`;
+  inert at the year grid). A tile ABOVE precision drills down
+  (year→month→day); a tile AT precision commits. Reaching day view is only
+  possible when `precision='day'`, so range/selected tint on month/year
+  grids paints only at matching precision.
+- **Range machine:** first commit places the anchor (`onRangeStart`),
+  second commits the ordered pair (`onRangeSelect`). The anchor SURVIVES
+  paging/zooming — commit a start, page forward, commit the end elsewhere.
+  Hover paints a live preview from anchor to cursor; preview cells use
+  `-in-preview` classes, DISTINCT from committed `-in-range`, with
+  `-anchor-start/-anchor-end/-anchor-solo` end caps (day grids add
+  directional chevrons; solo hides them).
+- While an anchor is active the committed range is suppressed from painting
+  (source parity). **Deviation from source:** after Escape the committed
+  props paint again — web-mojo left the calendar blank until the next
+  commit (nothing consumed `range:cancel`). Corollary: do NOT write range
+  props from `onRangeStart` — a range prop write means `setRange` and kills
+  the anchor.
+- **Keyboard:** every cell is a real `<button>` (focusable, Enter/Space
+  commit). With focus anywhere inside: PageUp/PageDown page, Escape cancels
+  an in-progress anchor. There is no roving arrow-key focus — that was not
+  in the source engine either.
+- **Today** wears `-today` (red, day grids only). `disabledDates` are
+  unclickable and skipped by hover preview painting (the span still covers
+  them — `excludeDisabledFromRange` was accepted-but-unused in source and
+  is not carried).
+- Blank leading cells are inert `<div>`s, not buttons.
+
+## dateFns (`dateFns.*`)
+
+Pure, framework-free, `Date`-free shapes. The tuned edge cases are the
+point — do not "simplify":
+
+| Group | Functions |
+|---|---|
+| parse/format | `parseYmd/parseYm/parseYear` (+`parseByPrecision`), `formatYmd/formatYm/formatYear` (+`formatByPrecision`), `formatForDisplay(parsed, 'MMM D, YYYY')` |
+| calendar math | `daysInMonth(y,m)` (1-indexed), `weekdayWithFirstDay(y,m,d,firstDay)`, `addMonths/addYears` (shape-preserving, day CLAMPS: Jan 31 +1mo → Feb 28/29) |
+| compare | `compareYmd/Ym/Year/ByPrecision` (−1/0/1; cross-precision compares shared parts — how min/max pane-gating works), `isSameDay/Month/Year` |
+| counts | `daysBetweenInclusive` (1 for same day), `monthsBetweenInclusive`, `yearsBetweenInclusive`, `unitsBetweenInclusive` |
+| time | `parseTime` ("14:30", "2:30 pm", seconds/TZ tails dropped; strict 12h: hour 1–12 with am/pm, else null), `formatTime(t, '24h'\|'12h')`, `compareTime`, `addMinutes` (wraps 24h) |
+| datetime | `parseDateTime` (ISO±offset / "date time IANA" / date-only→00:00), `formatDateTime` ("YYYY-MM-DD HH:MM[ TZ]"), `formatDateTimeForDisplay`, `ianaOffset(zone, refDate)` (DST-aware "+05:30", null on bad zone) |
+| names/now | `monthNames(locale, 'short'\|'long')`, `weekdayNames(locale, firstDay, len)` (Intl-backed, cached, static-English fast path), `today()`, `_setFrozenToday(p)` test hook |
+
+Parse fns return `null` on invalid input, never throw; format fns return
+`''` for null. `parseYmd` range-checks day 1–31 but not month length
+(source behavior; the engine never emits an out-of-month day).
+
+## Styling
+
+`apps/portal/src/theme/calendar.css` — engine anatomy only
+(`mojo-calendar-*`: pane/head/nav/grid/weekday/cell + state classes), all
+colors via theme tokens; component tokens `--mojo-cal-anchor-fill`,
+`--mojo-cal-range-fill`, `--mojo-cal-range-fill-hover` (accent tints:
+10%/18% light, 18%/30% dark). The calendar fills its container's width —
+give it a sized wrapper (~300px per pane; the popover shells do this for
+you later).
+
+## Pitfalls
+
+- Don't parse engine output with `new Date('YYYY-MM-DD')` — that's UTC
+  midnight and shifts a day in western zones. Use `dateFns.parseYmd`.
+- `min`/`max` are compared at pane precision — a `min` mid-month still
+  allows that month's tile; check day-level rules at day level.
+- Escape/PageUp/PageDown require focus inside the calendar (click one cell
+  first); the demo copy says so too.
+- The wire's daterange triple (`dr_field/dr_start/dr_end`) and epoch-second
+  datetimes are PICKER-shell concerns — the engine only speaks canonical
+  local strings.