create-astram-app 0.11.0 → 0.12.0

package/template/frontend/src/pages/users/UserForm.jsx

@@ -4,7 +4,14 @@
  * via `useParams()` (a `:uuid` → edit, load first; else add). Closes via `navigate(-1)`;
  * on success toasts + calls the layout's `onRefresh`.
  *
- * Fields: Username (required) + Email. On edit, Status is also editable.
+ * Fields: Username (required) + Email + optional Sign-in name (`loginName`, auth capabilities
+ * R1.3, R1.7, R1.10). On edit, Status is also editable.
+ *
+ * Sign-in name: checked with the core rule (`loginName.js`) before saving; the server stays
+ * authoritative. It is saved in its own `updateUser({ loginName })` call after the other fields
+ * (on add: right after the user is created) so a 409 is known to be the name clash and shows the
+ * server's fixed text, "That sign-in name is already in use." (frontend-core's `createUser` sends
+ * only username and email). Clearing the field removes the name (`null`).
  *
  * ⛔ The `:uuid` is a route param only — never rendered as visible text.
  *
@@ -29,6 +36,7 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import AssignmentsEditor from './AssignmentsEditor';
+import { checkLoginNameInput, loginNamePatch, loginNameSaveError } from './loginName';
 
 export default function UserForm() {
   const { tokens, identity } = useAuth();
@@ -40,6 +48,8 @@ export default function UserForm() {
 
   const [username, setUsername] = useState('');
   const [email, setEmail] = useState('');
+  const [loginName, setLoginName] = useState('');
+  const [storedLoginName, setStoredLoginName] = useState(null);
   const [status, setStatus] = useState('active');
   const [loading, setLoading] = useState(isEdit);
   const [busy, setBusy] = useState(false);
@@ -55,6 +65,9 @@ export default function UserForm() {
       if (r.ok) {
         setUsername(r.record?.fields?.username || '');
         setEmail(r.record?.fields?.email || '');
+        const stored = r.record?.fields?.loginName;
+        setLoginName(typeof stored === 'string' ? stored : '');
+        setStoredLoginName(typeof stored === 'string' ? stored : null);
         setStatus(r.record?.fields?.status || 'active');
       } else {
         setError(r.error || 'Could not load the user.');
@@ -75,6 +88,12 @@ export default function UserForm() {
       setError('Enter a username.');
       return;
     }
+    const checkedName = checkLoginNameInput(loginName);
+    if (!checkedName.ok) {
+      setError(checkedName.error);
+      return;
+    }
+    const namePatch = loginNamePatch(isEdit ? storedLoginName : null, checkedName.value);
     setError('');
     setBusy(true);
     const r = isEdit
@@ -84,13 +103,35 @@ export default function UserForm() {
           status,
         })
       : await identity.createUser(token, { username: trimmedUser, email: trimmedEmail });
-    setBusy(false);
     if (!r.ok) {
+      setBusy(false);
       setError(r.error || 'Could not save the user.');
       return;
     }
-    toast.success(isEdit ? 'User updated' : 'User created');
+    const userUuid = isEdit ? uuid : r.id;
+    let nameError = null;
+    if (namePatch !== undefined) {
+      nameError = userUuid
+        ? loginNameSaveError(await identity.updateUser(token, userUuid, { loginName: namePatch }))
+        : 'Could not save the sign-in name.';
+    }
+    setBusy(false);
     onRefresh?.();
+    if (nameError) {
+      if (isEdit) {
+        // The other fields are saved; keep the form open on the sign-in name.
+        setError(`Other changes were saved. ${nameError}`);
+        return;
+      }
+      // The user exists now: continue on its edit form so a retry does not create a second one.
+      toast.success('User created');
+      toast.error(`${nameError} The user was created without a sign-in name.`);
+      if (userUuid) navigate(`/users/edit/${userUuid}`, { replace: true });
+      else close();
+      return;
+    }
+    if (namePatch !== undefined) setStoredLoginName(namePatch);
+    toast.success(isEdit ? 'User updated' : 'User created');
     close();
   };
 
@@ -136,6 +177,27 @@ export default function UserForm() {
         />
       </div>
 
+      <div className="space-y-1.5">
+        <Label htmlFor="user-login-name" variant="field">
+          Sign-in name (optional)
+        </Label>
+        <Input
+          id="user-login-name"
+          maxLength={64}
+          autoComplete="off"
+          autoCapitalize="none"
+          spellCheck={false}
+          placeholder="e.g. jsmith"
+          value={loginName}
+          disabled={loading}
+          onChange={(e) => setLoginName(e.target.value)}
+        />
+        <p className="text-xs text-muted-foreground">
+          Lets the user sign in with this name instead of their email, when the app allows it. 3–64
+          characters: letters a–z, digits, dot, underscore or hyphen. Leave empty for email only.
+        </p>
+      </div>
+
       {isEdit && (
         <div className="space-y-1.5">
           <Label htmlFor="user-status" variant="field">

package/template/frontend/src/pages/users/UsersPage.jsx

@@ -12,11 +12,17 @@
  * (`row.signInStatus`, computed server-side), with an Invite button for pending users when the
  * caller holds identity:user:invite (`inviteAction.js`; UX only, the server decides).
  *
+ * 2FA (auth capabilities R11, R13.4, AC-27): a "2FA" column shows `row.mfaStatus` (Enrolled /
+ * Required / Grace period / Not required, server-computed), with a menu of Reset 2FA, Unlock and
+ * End sessions, each shown only with its own `identity:user:<action>` key and never on the
+ * signed-in user's own row (`signInAdmin.js`). Each asks for the admin's own 6-digit code
+ * (`SignInActionDialog`); the server decides.
+ *
  * ⛔ No raw UUIDs: columns render username/email/status; `row.id` is a key/route param only.
  */
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { Outlet, useNavigate, useSearchParams } from 'react-router-dom';
-import { Send, Users } from 'lucide-react';
+import { KeyRound, LogOut, MoreHorizontal, Send, ShieldOff, Users } from 'lucide-react';
 import { toast } from 'sonner';
 import { useAuth, useCan } from '@/auth/AuthContext';
 import AppShell from '@/shell/AppShell';
@@ -25,7 +31,65 @@ import EntityList, { EntityListControls, EntityListPager } from '@/components/En
 import ConfirmDialog from '@/components/ConfirmDialog';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
 import { INVITE_PERMISSION, canInvite, inviteOutcome } from './inviteAction';
+import { mfaStatusLabel, mfaStatusVariant, visibleSignInActions } from './signInAdmin';
+import SignInActionDialog from './SignInActionDialog';
+
+const ACTION_ICON = { reset_mfa: ShieldOff, unlock: KeyRound, end_sessions: LogOut };
+
+/**
+ * The 2FA column: status badge + a menu of the admin sign-in actions the caller may use on this
+ * row (none on their own row). Not sortable (computed server-side, not a stored field).
+ */
+function mfaColumn(actionsFor, onAction) {
+  return {
+    key: 'mfaStatus',
+    label: '2FA',
+    sortable: false,
+    render: (row) => {
+      const actions = actionsFor(row);
+      const name = row.fields?.username || 'this user';
+      return (
+        <div className="flex items-center gap-2">
+          <Badge variant={mfaStatusVariant(row.mfaStatus)}>{mfaStatusLabel(row.mfaStatus)}</Badge>
+          {actions.length > 0 && (
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <button
+                  type="button"
+                  aria-label={`Sign-in actions for ${name}`}
+                  className="inline-flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <MoreHorizontal className="size-4" />
+                </button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="w-44">
+                {actions.map((a) => {
+                  const Icon = ACTION_ICON[a.key];
+                  return (
+                    <DropdownMenuItem
+                      key={a.key}
+                      variant={a.destructive ? 'destructive' : 'default'}
+                      onClick={() => onAction(a, row)}
+                    >
+                      <Icon className="size-4" /> {a.label}
+                    </DropdownMenuItem>
+                  );
+                })}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          )}
+        </div>
+      );
+    },
+  };
+}
 
 /** Compact absolute date — e.g. "13 Jul 2026"; '—' when missing/invalid. */
 function formatDate(v) {
@@ -133,7 +197,7 @@ function readQueryFromParams(sp) {
 }
 
 export default function UsersPage() {
-  const { tokens, identity } = useAuth();
+  const { tokens, identity, can, session, profile } = useAuth();
   const token = tokens?.accessToken;
   const navigate = useNavigate();
   const [searchParams, setSearchParams] = useSearchParams();
@@ -162,6 +226,16 @@ export default function UsersPage() {
   const holdsInvite = useCan(INVITE_PERMISSION);
   const [invitingId, setInvitingId] = useState(null);
 
+  // Admin sign-in actions (R11): `{ action, user }` while the code dialog is open.
+  const [signInAction, setSignInAction] = useState(null);
+  const selfId = session?.principalId ?? null;
+  const profileId = profile?.id ?? null;
+  const actionsFor = useCallback(
+    (row) => visibleSignInActions(row, { can, selfIds: [selfId, profileId] }),
+    [can, selfId, profileId],
+  );
+  const onSignInAction = useCallback((action, user) => setSignInAction({ action, user }), []);
+
   const [deleteTarget, setDeleteTarget] = useState(null);
   const [deleteBusy, setDeleteBusy] = useState(false);
 
@@ -224,8 +298,9 @@ export default function UsersPage() {
   const columns = useMemo(() => {
     const out = [...COLUMNS];
     out.splice(3, 0, signInColumn(holdsInvite, invitingId, onInvite));
+    out.splice(4, 0, mfaColumn(actionsFor, onSignInAction));
     return out;
-  }, [holdsInvite, invitingId, onInvite]);
+  }, [holdsInvite, invitingId, onInvite, actionsFor, onSignInAction]);
 
   const onConfirmDelete = async () => {
     if (!deleteTarget) return;
@@ -286,6 +361,19 @@ export default function UsersPage() {
 
       <Outlet context={{ onRefresh: load }} />
 
+      {signInAction && (
+        <SignInActionDialog
+          key={`${signInAction.action.key}:${signInAction.user.id}`}
+          action={signInAction.action}
+          user={signInAction.user}
+          onClose={() => setSignInAction(null)}
+          onDone={() => {
+            setSignInAction(null);
+            load();
+          }}
+        />
+      )}
+
       <ConfirmDialog
         open={!!deleteTarget}
         title={

package/template/frontend/src/pages/users/loginName.js

@@ -0,0 +1,108 @@
+// loginName.js — the Users form's optional sign-in name (auth capabilities R1.3, R1.7, R1.10).
+// Pure logic, tested by loginName.test.mjs. The check mirrors core's rule
+// (`@astram/core` normalizeLoginName / isValidLoginName) so the admin sees a mistake before
+// saving; the server stays authoritative and answers 400 / 409 itself.
+
+/** The stored form: lower-case `[a-z0-9._-]`, 3–64 characters (so never `@`). */
+const LOGIN_NAME_PATTERN = /^[a-z0-9._-]{3,64}$/;
+
+/** The server's fixed 409 for a sign-in name another user holds (no tenant named). */
+export const LOGIN_NAME_TAKEN = 'That sign-in name is already in use.';
+
+/** The rule, as the server words its 400. */
+export const LOGIN_NAME_INVALID =
+  'Enter a valid sign-in name: 3–64 characters, letters a–z, digits, dot, underscore or hyphen.';
+
+const LOGIN_NAME_HAS_AT =
+  'A sign-in name cannot contain @. Use the email field for an email address.';
+
+/**
+ * Copy of core's `LOGIN_NAME_CASES` (packages/core/test/login-name.test.ts). In the framework repo
+ * loginName.test.mjs checks this copy still equals the core table.
+ */
+export const LOGIN_NAME_CASES = [
+  { input: 'sonja', normalized: 'sonja', valid: true },
+  { input: 'SONJA', normalized: 'sonja', valid: true },
+  { input: '  Sonja  ', normalized: 'sonja', valid: true },
+  { input: 'sonja.strydom', normalized: 'sonja.strydom', valid: true },
+  { input: 'thabo_m-2', normalized: 'thabo_m-2', valid: true },
+  { input: 'abc', normalized: 'abc', valid: true },
+  { input: 'a'.repeat(64), normalized: 'a'.repeat(64), valid: true },
+  { input: '007', normalized: '007', valid: true },
+  { input: 'ab', normalized: 'ab', valid: false },
+  { input: '  ab  ', normalized: 'ab', valid: false },
+  { input: 'a'.repeat(65), normalized: 'a'.repeat(65), valid: false },
+  { input: '', normalized: '', valid: false },
+  { input: '   ', normalized: '', valid: false },
+  { input: 'sonja@example.com', normalized: 'sonja@example.com', valid: false },
+  { input: 'son@ja', normalized: 'son@ja', valid: false },
+  { input: 'son ja', normalized: 'son ja', valid: false },
+  { input: 'sonja!', normalized: 'sonja!', valid: false },
+  { input: 'sönja', normalized: 'sönja', valid: false },
+  { input: 'sonja\t', normalized: 'sonja', valid: true },
+  { input: 'so\nnja', normalized: 'so\nnja', valid: false },
+  { input: 'sonja+1', normalized: 'sonja+1', valid: false },
+  { input: 'ＳＯＮＪＡ', normalized: 'ＳＯＮＪＡ', valid: false },
+  { input: 'SONJA\u212A', normalized: 'SONJA\u212A', valid: false },
+  { input: '\u212Aim', normalized: '\u212Aim', valid: false },
+  { input: '\u0130van', normalized: '\u0130van', valid: false },
+  { input: ' sonja\u3000', normalized: ' sonja\u3000', valid: false },
+];
+
+/** Any character outside 7-bit ASCII (astral characters are surrogate pairs, in range). */
+const NON_ASCII = /[\u0080-\uffff]/;
+
+/**
+ * Trim and lower-case typed ASCII input; nothing else (as core). Non-ASCII input comes back
+ * unchanged and is never valid: Unicode case mapping can land on ASCII (U+212A → `k`).
+ */
+export function normalizeLoginName(input) {
+  const typed = String(input);
+  if (NON_ASCII.test(typed)) return typed;
+  return typed.trim().toLowerCase();
+}
+
+/** True when `value` (already normalized) is an allowed sign-in name. Never throws. */
+export function isValidLoginName(value) {
+  return typeof value === 'string' && LOGIN_NAME_PATTERN.test(value);
+}
+
+/**
+ * Check the form field. Empty means "no sign-in name" (`value: null`).
+ * @param {string | undefined | null} text
+ * @returns {{ ok: true, value: string | null } | { ok: false, error: string }}
+ */
+export function checkLoginNameInput(text) {
+  const name = normalizeLoginName(text ?? '');
+  if (name === '') return { ok: true, value: null };
+  if (name.includes('@')) return { ok: false, error: LOGIN_NAME_HAS_AT };
+  if (!isValidLoginName(name)) return { ok: false, error: LOGIN_NAME_INVALID };
+  return { ok: true, value: name };
+}
+
+/**
+ * What to send for `loginName`: `undefined` when unchanged (not sent), `null` to clear, else the
+ * new name.
+ * @param {string | null | undefined} stored the user's current sign-in name
+ * @param {string | null} next the checked form value
+ */
+export function loginNamePatch(stored, next) {
+  const before =
+    typeof stored === 'string' && stored.trim() !== '' ? normalizeLoginName(stored) : null;
+  if (before === next) return undefined;
+  return next;
+}
+
+/**
+ * The form error for a sign-in name save. frontend-core maps every non-403 failure of a user
+ * write to a generic text, so the fixed server texts are restored here by status: this call sends
+ * only `loginName`, so a 409 is the name clash and a 400 is the rule.
+ * @param {{ ok: boolean, status?: number, error?: string }} result
+ * @returns {string | null}
+ */
+export function loginNameSaveError(result) {
+  if (result && result.ok) return null;
+  if (result?.status === 409) return LOGIN_NAME_TAKEN;
+  if (result?.status === 400) return LOGIN_NAME_INVALID;
+  return (result && result.error) || 'Could not save the sign-in name.';
+}

package/template/frontend/src/pages/users/loginName.test.mjs

@@ -0,0 +1,133 @@
+// loginName.test.mjs — auth capabilities R1.3, R1.10, AC-4 (form): the Users form's optional
+// sign-in name. The client check mirrors core's rule; the server stays authoritative.
+//
+//   node --test src/pages/users/loginName.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { URL, fileURLToPath } from 'node:url';
+import {
+  LOGIN_NAME_CASES,
+  LOGIN_NAME_INVALID,
+  LOGIN_NAME_TAKEN,
+  checkLoginNameInput,
+  isValidLoginName,
+  loginNamePatch,
+  loginNameSaveError,
+  normalizeLoginName,
+} from './loginName.js';
+
+describe('login name rule (mirror of core LOGIN_NAME_CASES)', () => {
+  for (const { input, normalized, valid } of LOGIN_NAME_CASES) {
+    test(`${JSON.stringify(input)} → ${JSON.stringify(normalized)} ${valid ? 'valid' : 'invalid'}`, () => {
+      assert.equal(normalizeLoginName(input), normalized);
+      assert.equal(isValidLoginName(normalizeLoginName(input)), valid);
+    });
+  }
+
+  test('validates the stored form only', () => {
+    assert.equal(isValidLoginName('Sonja'), false);
+    assert.equal(isValidLoginName(' sonja'), false);
+    assert.equal(isValidLoginName(undefined), false);
+    assert.equal(isValidLoginName(42), false);
+  });
+
+  test('a valid name never contains @', () => {
+    for (const c of LOGIN_NAME_CASES) {
+      if (isValidLoginName(c.normalized)) assert.ok(!c.normalized.includes('@'));
+    }
+  });
+
+  // In this repo the core table sits at packages/core/test/login-name.test.ts; a scaffolded app
+  // has no such file, so the parity check is skipped there.
+  const coreTable = fileURLToPath(
+    new URL('../../../../../../packages/core/test/login-name.test.ts', import.meta.url),
+  );
+  test('the copy equals core LOGIN_NAME_CASES', { skip: !existsSync(coreTable) }, () => {
+    const src = readFileSync(coreTable, 'utf8');
+    const m = src.match(/export const LOGIN_NAME_CASES[^=]*=\s*(\[[\s\S]*?\n\]);/);
+    assert.ok(m, 'LOGIN_NAME_CASES literal not found in the core test');
+    // The literal holds only object literals, strings and 'a'.repeat(n): plain JS.
+    const coreCases = new Function(`return ${m[1]};`)();
+    assert.deepEqual(LOGIN_NAME_CASES, coreCases);
+  });
+});
+
+describe('checkLoginNameInput', () => {
+  test('empty or blank means "no sign-in name"', () => {
+    assert.deepEqual(checkLoginNameInput(''), { ok: true, value: null });
+    assert.deepEqual(checkLoginNameInput('   '), { ok: true, value: null });
+    assert.deepEqual(checkLoginNameInput(undefined), { ok: true, value: null });
+  });
+
+  test('a valid name comes back normalized', () => {
+    assert.deepEqual(checkLoginNameInput('  Sonja.S '), { ok: true, value: 'sonja.s' });
+  });
+
+  test('an email form gets its own message', () => {
+    const r = checkLoginNameInput('sonja@example.com');
+    assert.equal(r.ok, false);
+    assert.match(r.error, /cannot contain @/);
+  });
+
+  test('anything else outside the rule gets the rule text', () => {
+    for (const bad of ['ab', 'son ja', 'sönja', 'a'.repeat(65)]) {
+      assert.deepEqual(checkLoginNameInput(bad), { ok: false, error: LOGIN_NAME_INVALID });
+    }
+  });
+});
+
+describe('loginNamePatch', () => {
+  test('unchanged → undefined (not sent)', () => {
+    assert.equal(loginNamePatch('sonja', 'sonja'), undefined);
+    assert.equal(loginNamePatch(null, null), undefined);
+    assert.equal(loginNamePatch(undefined, null), undefined);
+    assert.equal(loginNamePatch('', null), undefined);
+  });
+
+  test('set or changed → the new name; cleared → null', () => {
+    assert.equal(loginNamePatch(null, 'sonja'), 'sonja');
+    assert.equal(loginNamePatch('sonja', 'sonja2'), 'sonja2');
+    assert.equal(loginNamePatch('sonja', null), null);
+  });
+
+  test('a stored name in another case is compared normalized', () => {
+    assert.equal(loginNamePatch('Sonja', 'sonja'), undefined);
+  });
+});
+
+describe('loginNameSaveError', () => {
+  test('409 → the server fixed text', () => {
+    assert.equal(LOGIN_NAME_TAKEN, 'That sign-in name is already in use.');
+    assert.equal(
+      loginNameSaveError({ ok: false, status: 409, error: 'Could not update the user.' }),
+      LOGIN_NAME_TAKEN,
+    );
+  });
+
+  test('400 → the rule text (the server refused the value)', () => {
+    assert.equal(
+      loginNameSaveError({ ok: false, status: 400, error: 'Could not update the user.' }),
+      LOGIN_NAME_INVALID,
+    );
+  });
+
+  test('anything else → the service message, or a generic one', () => {
+    assert.equal(
+      loginNameSaveError({
+        ok: false,
+        status: 403,
+        error: 'You need platform-admin access to do this.',
+      }),
+      'You need platform-admin access to do this.',
+    );
+    assert.equal(
+      loginNameSaveError({ ok: false, status: 500 }),
+      'Could not save the sign-in name.',
+    );
+  });
+
+  test('success → null', () => {
+    assert.equal(loginNameSaveError({ ok: true }), null);
+  });
+});

package/template/frontend/src/pages/users/signInAdmin.js

@@ -0,0 +1,122 @@
+// signInAdmin.js — the Users page "2FA" column and admin sign-in actions (auth capabilities
+// R11.1–R11.3, R13.4, AC-27). Pure logic, tested by signInAdmin.test.mjs; UsersPage renders from
+// it. Showing an action is UX only: the server checks the permission, the tenant wall, dominance,
+// self and the admin's own code on every call.
+
+/** `mfaStatus` (server-computed) → column label. */
+const MFA_STATUS_LABEL = {
+  enrolled: 'Enrolled',
+  required: 'Required',
+  grace: 'Grace period',
+  not_required: 'Not required',
+};
+
+const MFA_STATUS_VARIANT = {
+  enrolled: 'success',
+  required: 'destructive',
+  grace: 'warning',
+  not_required: 'secondary',
+};
+
+/** The 2FA column text; '—' when the server did not compute a status. */
+export function mfaStatusLabel(status) {
+  return Object.hasOwn(MFA_STATUS_LABEL, status) ? MFA_STATUS_LABEL[status] : '—';
+}
+
+/** The badge variant for a status. */
+export function mfaStatusVariant(status) {
+  return Object.hasOwn(MFA_STATUS_VARIANT, status) ? MFA_STATUS_VARIANT[status] : 'secondary';
+}
+
+/**
+ * The three admin actions: permission key, `identityService` method, menu label, dialog copy and
+ * the success toast.
+ */
+export const SIGN_IN_ACTIONS = [
+  {
+    key: 'reset_mfa',
+    permission: 'identity:user:reset_mfa',
+    method: 'resetUserMfa',
+    label: 'Reset 2FA',
+    title: (name) => `Reset 2FA for ${name}?`,
+    description:
+      'This removes their authenticator and recovery codes and signs them out everywhere. ' +
+      'If a policy requires 2FA, they set it up again at their next sign-in.',
+    confirmLabel: 'Reset 2FA',
+    destructive: true,
+    success: (name) =>
+      `2FA reset for ${name}. They will set it up again at their next sign-in if required.`,
+  },
+  {
+    key: 'unlock',
+    permission: 'identity:user:unlock',
+    method: 'unlockUser',
+    label: 'Unlock',
+    title: (name) => `Unlock ${name}?`,
+    description: 'This clears their failed sign-in and code attempts so they can try again now.',
+    confirmLabel: 'Unlock',
+    destructive: false,
+    success: (name) => `${name} can sign in again.`,
+  },
+  {
+    key: 'end_sessions',
+    permission: 'identity:user:end_sessions',
+    method: 'endUserSessions',
+    label: 'End sessions',
+    title: (name) => `End all sessions for ${name}?`,
+    description: 'They are signed out on every device and must sign in again.',
+    confirmLabel: 'End sessions',
+    destructive: true,
+    success: (name) => `All of ${name}’s sessions were ended.`,
+  },
+];
+
+/**
+ * The actions to offer on a row: each needs its own permission, and none on the caller's own row
+ * (the server refuses self for all three).
+ * @param {{ id?: string } | null | undefined} row
+ * @param {{ can: (key: string) => boolean, selfIds: Array<string | null | undefined> }} opts
+ */
+export function visibleSignInActions(row, { can, selfIds }) {
+  if (!row || !row.id) return [];
+  if ((selfIds || []).some((id) => typeof id === 'string' && id !== '' && id === row.id)) return [];
+  return SIGN_IN_ACTIONS.filter((a) => can(a.permission));
+}
+
+/** Drop spaces from a typed code. */
+export function normalizeAdminCode(text) {
+  return String(text ?? '').replace(/\s+/g, '');
+}
+
+/** Exactly six digits. */
+export function isAdminCode(text) {
+  return /^\d{6}$/.test(normalizeAdminCode(text));
+}
+
+/** Failure reason → [text, close the dialog?]. `null` text = use the service's fixed message. */
+const FAILURE = {
+  code_required: ['Enter the 6-digit code from your authenticator app.', false],
+  invalid_code: ['That code is not valid. Enter a new code from your authenticator app.', false],
+  admin_needs_mfa: ['Set up two-step verification on your own account first.', true],
+  partially_applied: ['Partly done — try again.', false],
+  rate_limited: ['Too many code attempts. Wait a few minutes and try again.', true],
+  forbidden: ['You cannot do this for this user.', true],
+  not_found: ['This user no longer exists.', true],
+  not_authenticated: [null, true],
+  unavailable: [null, false],
+  unreachable: [null, false],
+};
+
+/**
+ * The outcome of `identity.resetUserMfa` / `unlockUser` / `endUserSessions`.
+ * @param {(typeof SIGN_IN_ACTIONS)[number]} action
+ * @param {{ ok: boolean, reason?: string, error?: string }} result
+ * @param {string} [name] the user's display name
+ * @returns {{ kind: 'success' | 'error', text: string, close: boolean }}
+ */
+export function signInActionOutcome(action, result, name = 'this user') {
+  if (result && result.ok) return { kind: 'success', text: action.success(name), close: true };
+  const entry = Object.hasOwn(FAILURE, result?.reason) ? FAILURE[result.reason] : [null, false];
+  const text = entry[0] ?? ((result && result.error) || 'The action failed. Please try again.');
+  return { kind: 'error', text, close: entry[1] };
+}