@rapidmx/web-client 0.8.0 → 0.10.0

package/apps/www/settings/signatures/new/index.tsx

@@ -1,129 +1,134 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-import React, { FormEvent, useState } from "react";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { createMailSignature, listMailSignatures } from "@rapidmx/react-shared/mail/mailSignaturesApi.js";
-import { clearPreviousDefaults } from "../signatureDefaults.js";
-import SettingsShell, { SettingsShellProps, useSettingsShell } from "../../../../shared/components/settings/layout/SettingsShell.js";
-import RichTextEditor from "../../../../shared/components/mail/compose/RichTextEditor.js";
-import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
-import Button from "@rapidmx/react-shared/components/buttons/Button.js";
-import FormField from "@rapidmx/react-shared/components/forms/FormField.js";
-
-const INPUT_CLASS =
-    "w-full text-sm py-2.5 px-3 border border-border rounded-sm bg-surface text-text focus:outline-none focus:border-primary";
-
-export type NewSignaturePageProps = Omit<SettingsShellProps, "active">;
-
-export default function NewSignaturePage(props: NewSignaturePageProps) {
-    return (
-        <SettingsShell {...props} active="signatures">
-            <NewSignatureForm />
-        </SettingsShell>
-    );
-}
-
-/** Signatures aren't backed by a draft/attachment record the way Compose's own inline images are (see
- * `ComposeWindow.handleUploadImage()`) — inline images in a signature are out of scope for this phase
- * (`.claude/NOTES.md`'s Phase 12 entry), so this is a real, deliberate no-op, not a stub left unfinished. */
-async function handleUploadImage(): Promise<string | null> {
-    return null;
-}
-
-function NewSignatureForm() {
-    const { mailboxUid } = useSettingsShell();
-    const [name, setName] = useState("");
-    const [contentHtml, setContentHtml] = useState("");
-    const [isDefaultForNewMessages, setIsDefaultForNewMessages] = useState(false);
-    const [isDefaultForReplyForward, setIsDefaultForReplyForward] = useState(false);
-    const [error, setError] = useState<string | null>(null);
-    const [saving, setSaving] = useState(false);
-
-    async function handleSubmit(e: FormEvent) {
-        e.preventDefault();
-        setError(null);
-
-        if (!name.trim()) {
-            setError("A name is required.");
-            return;
-        }
-
-        setSaving(true);
-        try {
-            if (isDefaultForNewMessages || isDefaultForReplyForward) {
-                const existing = await listMailSignatures(mailboxUid!, { limit: 100 });
-                await clearPreviousDefaults(existing, undefined, isDefaultForNewMessages, isDefaultForReplyForward);
-            }
-            const created = await createMailSignature({
-                mailboxUid: mailboxUid!,
-                name: name.trim(),
-                contentHtml,
-                isDefaultForNewMessages,
-                isDefaultForReplyForward,
-            });
-            window.location.href = `/settings/signatures/${encodeURIComponent(created.uid)}?mailboxUid=${encodeURIComponent(mailboxUid!)}`;
-        } catch (err) {
-            setError(err instanceof ApiRequestError ? err.message : "Could not create the signature.");
-        } finally {
-            setSaving(false);
-        }
-    }
-
-    return (
-        <div className="flex-1 min-w-0 overflow-y-auto p-6">
-            <div className="max-w-3xl">
-                <h1 className="text-lg font-bold tracking-tight mb-5">New signature</h1>
-
-                {error && <Alert>{error}</Alert>}
-
-                <form onSubmit={handleSubmit} className="flex flex-col gap-5">
-                    <div className="bg-surface border border-border rounded-md p-6 flex flex-col gap-4">
-                        <FormField label="Name" htmlFor="name">
-                            <input
-                                id="name"
-                                type="text"
-                                className={INPUT_CLASS}
-                                value={name}
-                                onChange={(e) => setName(e.target.value)}
-                                placeholder="Work signature"
-                            />
-                        </FormField>
-                        <label className="flex items-center gap-2 text-sm">
-                            <input
-                                type="checkbox"
-                                checked={isDefaultForNewMessages}
-                                onChange={(e) => setIsDefaultForNewMessages(e.target.checked)}
-                            />
-                            Use for new messages
-                        </label>
-                        <label className="flex items-center gap-2 text-sm">
-                            <input
-                                type="checkbox"
-                                checked={isDefaultForReplyForward}
-                                onChange={(e) => setIsDefaultForReplyForward(e.target.checked)}
-                            />
-                            Use for replies and forwards
-                        </label>
-                    </div>
-
-                    <div className="h-64">
-                        <RichTextEditor value={contentHtml} onChange={setContentHtml} fill onUploadImage={handleUploadImage} />
-                    </div>
-
-                    <div className="flex gap-3">
-                        <Button type="submit" loading={saving} disabled={saving} className="!w-auto">
-                            Create signature
-                        </Button>
-                        <a href={`/settings/signatures?mailboxUid=${encodeURIComponent(mailboxUid!)}`}>
-                            <Button type="button" variant="secondary" className="!w-auto">
-                                Cancel
-                            </Button>
-                        </a>
-                    </div>
-                </form>
-            </div>
-        </div>
-    );
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { routedPage } from "../../../_routedPage.js";
+import { useNavigate } from "../../../../shared/navigation/AppRouter.js";
+import React, { FormEvent, useState } from "react";
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { createMailSignature, listMailSignatures } from "@rapidmx/react-shared/mail/mailSignaturesApi.js";
+import { clearPreviousDefaults } from "../signatureDefaults.js";
+import SettingsShell, { SettingsShellProps, useSettingsShell } from "../../../../shared/components/settings/layout/SettingsShell.js";
+import RichTextEditor from "../../../../shared/components/mail/compose/RichTextEditor.js";
+import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
+import Button from "@rapidmx/react-shared/components/buttons/Button.js";
+import FormField from "@rapidmx/react-shared/components/forms/FormField.js";
+
+const INPUT_CLASS =
+    "w-full text-sm py-2.5 px-3 border border-border rounded-sm bg-surface text-text focus:outline-none focus:border-primary";
+
+export type NewSignaturePageProps = Omit<SettingsShellProps, "active">;
+
+function NewSignaturePage(props: NewSignaturePageProps) {
+    return (
+        <SettingsShell {...props} active="signatures">
+            <NewSignatureForm />
+        </SettingsShell>
+    );
+}
+
+/** Signatures aren't backed by a draft/attachment record the way Compose's own inline images are (see
+ * `ComposeWindow.handleUploadImage()`) — inline images in a signature are out of scope for this phase
+ * (`.claude/NOTES.md`'s Phase 12 entry), so this is a real, deliberate no-op, not a stub left unfinished. */
+async function handleUploadImage(): Promise<string | null> {
+    return null;
+}
+
+function NewSignatureForm() {
+    const navigate = useNavigate();
+    const { mailboxUid } = useSettingsShell();
+    const [name, setName] = useState("");
+    const [contentHtml, setContentHtml] = useState("");
+    const [isDefaultForNewMessages, setIsDefaultForNewMessages] = useState(false);
+    const [isDefaultForReplyForward, setIsDefaultForReplyForward] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    const [saving, setSaving] = useState(false);
+
+    async function handleSubmit(e: FormEvent) {
+        e.preventDefault();
+        setError(null);
+
+        if (!name.trim()) {
+            setError("A name is required.");
+            return;
+        }
+
+        setSaving(true);
+        try {
+            if (isDefaultForNewMessages || isDefaultForReplyForward) {
+                const existing = await listMailSignatures(mailboxUid!, { limit: 100 });
+                await clearPreviousDefaults(existing, undefined, isDefaultForNewMessages, isDefaultForReplyForward);
+            }
+            const created = await createMailSignature({
+                mailboxUid: mailboxUid!,
+                name: name.trim(),
+                contentHtml,
+                isDefaultForNewMessages,
+                isDefaultForReplyForward,
+            });
+            navigate(`/settings/signatures/${encodeURIComponent(created.uid)}?mailboxUid=${encodeURIComponent(mailboxUid!)}`);
+        } catch (err) {
+            setError(err instanceof ApiRequestError ? err.message : "Could not create the signature.");
+        } finally {
+            setSaving(false);
+        }
+    }
+
+    return (
+        <div className="flex-1 min-w-0 overflow-y-auto p-6">
+            <div className="max-w-3xl">
+                <h1 className="text-lg font-bold tracking-tight mb-5">New signature</h1>
+
+                {error && <Alert>{error}</Alert>}
+
+                <form onSubmit={handleSubmit} className="flex flex-col gap-5">
+                    <div className="bg-surface border border-border rounded-md p-6 flex flex-col gap-4">
+                        <FormField label="Name" htmlFor="name">
+                            <input
+                                id="name"
+                                type="text"
+                                className={INPUT_CLASS}
+                                value={name}
+                                onChange={(e) => setName(e.target.value)}
+                                placeholder="Work signature"
+                            />
+                        </FormField>
+                        <label className="flex items-center gap-2 text-sm">
+                            <input
+                                type="checkbox"
+                                checked={isDefaultForNewMessages}
+                                onChange={(e) => setIsDefaultForNewMessages(e.target.checked)}
+                            />
+                            Use for new messages
+                        </label>
+                        <label className="flex items-center gap-2 text-sm">
+                            <input
+                                type="checkbox"
+                                checked={isDefaultForReplyForward}
+                                onChange={(e) => setIsDefaultForReplyForward(e.target.checked)}
+                            />
+                            Use for replies and forwards
+                        </label>
+                    </div>
+
+                    <div className="h-64">
+                        <RichTextEditor value={contentHtml} onChange={setContentHtml} fill onUploadImage={handleUploadImage} />
+                    </div>
+
+                    <div className="flex gap-3">
+                        <Button type="submit" loading={saving} disabled={saving} className="!w-auto">
+                            Create signature
+                        </Button>
+                        <a href={`/settings/signatures?mailboxUid=${encodeURIComponent(mailboxUid!)}`}>
+                            <Button type="button" variant="secondary" className="!w-auto">
+                                Cancel
+                            </Button>
+                        </a>
+                    </div>
+                </form>
+            </div>
+        </div>
+    );
+}
+
+export default routedPage("/settings/signatures/new", NewSignaturePage);

package/apps/www/tasks/index.tsx

@@ -2,7 +2,8 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import React, { FormEvent, useEffect, useMemo, useState } from "react";
+import { routedPage } from "../_routedPage.js";
+import React, { FormEvent, useEffect, useMemo, useRef, useState } from "react";
 import { endOfWeek, isAfter, isBefore, isToday, parseISO, startOfDay } from "date-fns";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import {
@@ -26,11 +27,14 @@ import Modal from "@rapidmx/react-shared/components/overlays/Modal.js";
 import { findWellKnownFolderUid } from "../../shared/mail/findWellKnownFolderUid.js";
 import { useWritableMailboxes } from "../../shared/components/mail/writableMailboxes.js";
 import { LIST_PAGE_SIZE, MAX_LIST_PAGES, listAllPages } from "../../shared/mail/listAllPages.js";
+import { SHORTCUTS } from "../../shared/keyboard/keymap.js";
+import { useShortcut } from "../../shared/keyboard/useShortcut.js";
+import { useShortcutProps } from "../../shared/keyboard/useShortcutProps.js";
 
 const INPUT_CLASS =
     "text-sm py-1.5 px-2 border border-border rounded-sm bg-surface text-text focus:outline-none focus:border-primary";
 
-export default function TasksPage(props: TasksShellProps) {
+function TasksPage(props: TasksShellProps) {
     return (
         <TasksShell {...props}>
             <TasksContent />
@@ -103,6 +107,14 @@ function TasksContent() {
     // checked task (the toolbar's Delete).
     const [pendingDelete, setPendingDelete] = useState<{ type: "single"; task: Task } | { type: "bulk" } | null>(null);
 
+    // "New task" from the keyboard: a task is made in the quick-add form, so this moves the caret to its title field (which the Flagged view,
+    // a list of flagged mail rather than tasks, doesn't have). A dialog open - the delete confirmation - silences it.
+    const addTaskRef = useRef<HTMLInputElement | null>(null);
+    const canAddTask = view.type !== "flagged";
+    // Registered only while the form is rendered (`canAddTask`), so its field is there.
+    useShortcut(SHORTCUTS.tasks.create, () => addTaskRef.current!.focus(), { enabled: canAddTask });
+    const addTaskHint = useShortcutProps("Add a task", SHORTCUTS.tasks.create, canAddTask);
+
     function reload(): Promise<void> {
         if (!folderUid) {
             setTasks([]);
@@ -344,8 +356,10 @@ function TasksContent() {
                         <>
                             <form onSubmit={handleCreate} className="flex items-center gap-2 bg-surface border border-border rounded-md p-2">
                                 <input
+                                    ref={addTaskRef}
                                     type="text"
                                     aria-label="Add a task"
+                                    {...addTaskHint}
                                     className={`${INPUT_CLASS} flex-1`}
                                     value={title}
                                     onChange={(e) => setTitle(e.target.value)}
@@ -636,3 +650,5 @@ function TaskTable({ tasks, checkedUids, onToggleChecked, onToggle, onDelete }:
         </div>
     );
 }
+
+export default routedPage("/tasks", TasksPage);

package/dist/apps/shared/auth/accountUrl.d.ts

@@ -0,0 +1,2 @@
+/** auth-server's account page, or `undefined` when no auth-server is configured. Tolerates a configured URL with a trailing slash. */
+export declare function accountUrlOf(authServerUrl: string | undefined): string | undefined;

package/dist/apps/shared/auth/accountUrl.js

@@ -0,0 +1,8 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** auth-server's account page, or `undefined` when no auth-server is configured. Tolerates a configured URL with a trailing slash. */
+export function accountUrlOf(authServerUrl) {
+    return authServerUrl ? `${authServerUrl.replace(/\/+$/, "")}/account` : undefined;
+}

package/dist/apps/shared/auth/adminAccess.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Whether the signed-in user holds an administrator role, learned without elevating.
+ *
+ * The JWT the browser carries can't say: auth-server strips every trusted role from a token that isn't elevated
+ * (`TokenUtils.resolveTokenUser()`), so `trusted` (from the JWT) is false for a real administrator until they confirm
+ * their identity on auth-server's elevation page. The role itself lives on the caller's own `User` record, which they may
+ * always read - `GET {authServerUrl}/api/users/me` (the same call auth-server's own UI makes "to check for admin access") -
+ * so the answer is read from there, with the same cross-origin credentials the profile lookups use.
+ *
+ * This only decides whether a menu item is shown. The `/admin` pages and API stay authoritative: they check the role and
+ * the elevation themselves, and the link only navigates (`/admin` then runs the elevation redirect), so a wrong answer
+ * - a stale cache, a tampered `sessionStorage` - can show a link that leads to "no administrator access", never more.
+ */
+/** The roles the server treats as trusted when it isn't configured otherwise (`trusted_roles`, default `["admin"]`). */
+export declare const DEFAULT_TRUSTED_ROLES: readonly string[];
+/** `sessionStorage` key prefix of a remembered answer; the user's uid follows, so another account signing in in the same
+ * tab never inherits it. */
+export declare const ADMIN_ACCESS_KEY_PREFIX = "rapidmx-admin-access:";
+/** How long a remembered answer is trusted - long enough that navigating between the apps costs no request, short enough
+ * that a role granted or removed shows up within the sitting. */
+export declare const ADMIN_ACCESS_TTL_MS: number;
+/** Forgets the lookups in flight (tests). */
+export declare function resetAdminAccessLookups(): void;
+/**
+ * Resolves `true` when `userUid`'s own `User` record on auth-server carries one of `trustedRoles`, `false` when it
+ * doesn't, and `undefined` when that couldn't be established (unreachable, blocked by CORS, not signed in, an unexpected
+ * body, or a record that isn't this user's). Only a real answer is remembered; a failure is asked again on the next page.
+ * Never rejects.
+ */
+export declare function lookUpAdminAccess(authServerUrl: string, userUid: string, trustedRoles?: readonly string[], now?: number): Promise<boolean | undefined>;

package/dist/apps/shared/auth/adminAccess.js

@@ -0,0 +1,89 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { authApiFetch } from "@rapidmx/react-shared/util/api.js";
+/**
+ * Whether the signed-in user holds an administrator role, learned without elevating.
+ *
+ * The JWT the browser carries can't say: auth-server strips every trusted role from a token that isn't elevated
+ * (`TokenUtils.resolveTokenUser()`), so `trusted` (from the JWT) is false for a real administrator until they confirm
+ * their identity on auth-server's elevation page. The role itself lives on the caller's own `User` record, which they may
+ * always read - `GET {authServerUrl}/api/users/me` (the same call auth-server's own UI makes "to check for admin access") -
+ * so the answer is read from there, with the same cross-origin credentials the profile lookups use.
+ *
+ * This only decides whether a menu item is shown. The `/admin` pages and API stay authoritative: they check the role and
+ * the elevation themselves, and the link only navigates (`/admin` then runs the elevation redirect), so a wrong answer
+ * - a stale cache, a tampered `sessionStorage` - can show a link that leads to "no administrator access", never more.
+ */
+/** The roles the server treats as trusted when it isn't configured otherwise (`trusted_roles`, default `["admin"]`). */
+export const DEFAULT_TRUSTED_ROLES = ["admin"];
+/** `sessionStorage` key prefix of a remembered answer; the user's uid follows, so another account signing in in the same
+ * tab never inherits it. */
+export const ADMIN_ACCESS_KEY_PREFIX = "rapidmx-admin-access:";
+/** How long a remembered answer is trusted - long enough that navigating between the apps costs no request, short enough
+ * that a role granted or removed shows up within the sitting. */
+export const ADMIN_ACCESS_TTL_MS = 30 * 60 * 1000;
+/** Lookups in flight, by key, so two components asking at once make one request. */
+const lookups = new Map();
+/** Forgets the lookups in flight (tests). */
+export function resetAdminAccessLookups() {
+    lookups.clear();
+}
+function readRemembered(key, now) {
+    try {
+        const stored = JSON.parse(sessionStorage.getItem(key) ?? "null");
+        if (typeof stored?.admin === "boolean" && typeof stored.at === "number" && now - stored.at >= 0 && now - stored.at < ADMIN_ACCESS_TTL_MS) {
+            return stored.admin;
+        }
+    }
+    catch {
+        // Unreadable, or storage unavailable - ask again.
+    }
+    return undefined;
+}
+function remember(key, admin, now) {
+    try {
+        sessionStorage.setItem(key, JSON.stringify({ admin, at: now }));
+    }
+    catch {
+        // Storage unavailable - the next page load asks again.
+    }
+}
+/**
+ * Resolves `true` when `userUid`'s own `User` record on auth-server carries one of `trustedRoles`, `false` when it
+ * doesn't, and `undefined` when that couldn't be established (unreachable, blocked by CORS, not signed in, an unexpected
+ * body, or a record that isn't this user's). Only a real answer is remembered; a failure is asked again on the next page.
+ * Never rejects.
+ */
+export function lookUpAdminAccess(authServerUrl, userUid, trustedRoles = DEFAULT_TRUSTED_ROLES, now = Date.now()) {
+    const key = `${ADMIN_ACCESS_KEY_PREFIX}${userUid}`;
+    const remembered = readRemembered(key, now);
+    if (remembered !== undefined) {
+        return Promise.resolve(remembered);
+    }
+    const inFlight = lookups.get(key);
+    if (inFlight) {
+        return inFlight;
+    }
+    const lookup = (async () => {
+        try {
+            const user = await authApiFetch(authServerUrl, "/users/me");
+            if (!user || user.uid !== userUid || !Array.isArray(user.roles)) {
+                return undefined;
+            }
+            const admin = user.roles.some((role) => typeof role === "string" && trustedRoles.includes(role));
+            remember(key, admin, now);
+            return admin;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            // Answered: what was learned is in storage; a failure may be asked again.
+            lookups.delete(key);
+        }
+    })();
+    lookups.set(key, lookup);
+    return lookup;
+}

package/dist/apps/shared/components/admin/elevation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `ApiRequestError.code` a `@RequiresElevation()` endpoint answers a caller whose token isn't elevated with
+ * (a 403 - `ApiErrors.AUTH_REQUIRES_ELEVATION` in `@rapidrest/service-core`). Distinct from `api-103` (the caller is
+ * elevated but lacks the trusted role), which no amount of elevating fixes.
+ */
+export declare const ELEVATION_REQUIRED_CODE = "api-104";
+/** `sessionStorage` key holding the time (`Date.now()`) the browser was last sent to auth-server to elevate. */
+export declare const ELEVATION_ATTEMPT_KEY = "rapidmx-admin-elevation-attempt";
+/** How long after sending the browser to elevate a second `api-104` is taken to mean the elevation didn't take
+ * effect (e.g. auth-server's elevated cookie never reaching this origin), rather than a fresh need to elevate. */
+export declare const ELEVATION_RETRY_WINDOW_MS: number;
+/** Whether `err` is a 403 from an elevation-gated endpoint for a caller whose token isn't elevated. */
+export declare function isElevationRequired(err: unknown): boolean;
+/** auth-server's elevation page: it sends the browser back to `returnTo` once the user has confirmed their
+ * identity, or to its own account page if they cancel. */
+export declare function elevationUrl(authServerUrl: string, returnTo: string): string;
+/** Whether the browser was sent to elevate within `ELEVATION_RETRY_WINDOW_MS` of `now`. `false` when nothing was
+ * recorded, the record is unreadable or from the future, or storage is unavailable. */
+export declare function elevationAttemptedRecently(now?: number): boolean;
+/** Remembers, for this tab, that the browser is about to be sent to elevate. A no-op where storage is unavailable
+ * (then only the first-round protection is lost - elevating needs the user to confirm each time round). */
+export declare function recordElevationAttempt(now?: number): void;
+/** Forgets any recorded attempt - once elevation has worked, or when the user asks to try again. */
+export declare function clearElevationAttempt(): void;

package/dist/apps/shared/components/admin/elevation.js

@@ -0,0 +1,56 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+/**
+ * The `ApiRequestError.code` a `@RequiresElevation()` endpoint answers a caller whose token isn't elevated with
+ * (a 403 - `ApiErrors.AUTH_REQUIRES_ELEVATION` in `@rapidrest/service-core`). Distinct from `api-103` (the caller is
+ * elevated but lacks the trusted role), which no amount of elevating fixes.
+ */
+export const ELEVATION_REQUIRED_CODE = "api-104";
+/** `sessionStorage` key holding the time (`Date.now()`) the browser was last sent to auth-server to elevate. */
+export const ELEVATION_ATTEMPT_KEY = "rapidmx-admin-elevation-attempt";
+/** How long after sending the browser to elevate a second `api-104` is taken to mean the elevation didn't take
+ * effect (e.g. auth-server's elevated cookie never reaching this origin), rather than a fresh need to elevate. */
+export const ELEVATION_RETRY_WINDOW_MS = 2 * 60 * 1000;
+/** Whether `err` is a 403 from an elevation-gated endpoint for a caller whose token isn't elevated. */
+export function isElevationRequired(err) {
+    return err instanceof ApiRequestError && err.status === 403 && err.code === ELEVATION_REQUIRED_CODE;
+}
+/** auth-server's elevation page: it sends the browser back to `returnTo` once the user has confirmed their
+ * identity, or to its own account page if they cancel. */
+export function elevationUrl(authServerUrl, returnTo) {
+    return `${authServerUrl}/auth/elevate?return_to=${encodeURIComponent(returnTo)}`;
+}
+/** Whether the browser was sent to elevate within `ELEVATION_RETRY_WINDOW_MS` of `now`. `false` when nothing was
+ * recorded, the record is unreadable or from the future, or storage is unavailable. */
+export function elevationAttemptedRecently(now = Date.now()) {
+    try {
+        const recorded = Number(sessionStorage.getItem(ELEVATION_ATTEMPT_KEY));
+        const elapsed = now - recorded;
+        return recorded > 0 && elapsed >= 0 && elapsed < ELEVATION_RETRY_WINDOW_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remembers, for this tab, that the browser is about to be sent to elevate. A no-op where storage is unavailable
+ * (then only the first-round protection is lost - elevating needs the user to confirm each time round). */
+export function recordElevationAttempt(now = Date.now()) {
+    try {
+        sessionStorage.setItem(ELEVATION_ATTEMPT_KEY, String(now));
+    }
+    catch {
+        // See the doc comment.
+    }
+}
+/** Forgets any recorded attempt - once elevation has worked, or when the user asks to try again. */
+export function clearElevationAttempt() {
+    try {
+        sessionStorage.removeItem(ELEVATION_ATTEMPT_KEY);
+    }
+    catch {
+        // Nothing was recorded.
+    }
+}

package/dist/apps/shared/components/admin/layout/AdminShell.d.ts

@@ -24,9 +24,17 @@ export interface AdminShellProps extends PluginNavProps {
  * off-rail sections' - see `mergePluginNavItems`. */
 export declare function adminNavItems(pluginNav?: PluginNav): NavItem[];
 /**
- * Gates every `apps/admin` page behind the `admin` trusted role. Uses `GET /api/admin/release-notes` (any
- * `BaseAdminRoute` endpoint works — this one is side-effect-free) purely as a canary: a 200 means the
- * caller's JWT carries a trusted role, a 403 means it doesn't. There is no local step-up/elevation flow
- * (that would need a cross-origin call to auth-server's own elevation endpoint — not wired up yet).
+ * Gates every `apps/admin` page behind the `admin` trusted role, and behind an elevated session. Uses
+ * `GET /api/admin/release-notes` (any `BaseAdminRoute` endpoint works — this one is side-effect-free) purely as a
+ * canary. The endpoint is class-level `@RequiresElevation()`, checked *before* the trusted-role check, so a 200 means the
+ * caller's JWT is elevated and carries a trusted role: show the console. Otherwise:
+ *
+ * 403 `api-104` means the JWT isn't elevated (an administrator's normal sign-in). There is no local step-up form; the
+ * browser is sent to auth-server's `/auth/elevate?return_to=<this page>`, which returns it here once the user has
+ * confirmed their identity (or to its own account page if they cancel). Sent at most once per
+ * `ELEVATION_RETRY_WINDOW_MS`, so an elevated cookie that never reaches this origin can't bounce the browser back
+ * and forth - see `elevation.ts`, and the "didn't take effect" alert with its own "Try again" below.
+ *
+ * 403 `api-103` (elevated, but not an administrator), any other 403, and 401 mean "no administrator access".
  */
 export default function AdminShell({ active, userUid, authServerUrl, pluginNav, children }: PropsWithChildren<AdminShellProps>): React.JSX.Element;