create-astram-app 0.11.0 → 0.12.0

package/template/frontend/src/pages/security/SecuritySettingsPage.jsx

@@ -0,0 +1,229 @@
+/**
+ * SecuritySettingsPage — the tenant Security settings page (auth capabilities R11.4, R13.4,
+ * AC-26). Phase 1 covers mandatory-2FA policies (R2): list, add, edit, delete. Later phases add
+ * more sections here.
+ *
+ * Gating (UX only; `/identity/security-policies` is `@Classified` per action and the server
+ * applies the R2.6 authority rules): the route and nav need `identity:security_policy:read`; Add,
+ * Edit and Delete each need their own key. A refusal the UI could not predict (lowering a policy
+ * without enough access, the platform minimum for a non-root admin) shows the server's fixed
+ * message.
+ *
+ * Platform-minimum rows are visible to root only; everyone else sees a note that one may also
+ * apply.
+ *
+ * ⛔ No raw ids: the organisation, role and author of each policy are resolved to names
+ * (`resolvePolicyLabels`) with "Deleted company" / "Deleted role" / "Unknown user" fallbacks;
+ * `row.id` is a key only.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { Info, Lock } from 'lucide-react';
+import { toast } from 'sonner';
+import { useAuth } from '@/auth/AuthContext';
+import AppShell from '@/shell/AppShell';
+import PageHeader from '@/components/PageHeader';
+import EntityList, { EntityListControls, EntityListPager } from '@/components/EntityList';
+import ConfirmDialog from '@/components/ConfirmDialog';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Badge } from '@/components/ui/badge';
+import PolicyFormDialog from './PolicyFormDialog';
+import {
+  PLATFORM_LABEL,
+  describePolicy,
+  policyActions,
+  policyFailureText,
+  resolvePolicyLabels,
+  showFloorNote,
+} from './securityPolicies';
+
+const DEFAULT_LIMIT = 25;
+
+function columns(labels) {
+  const d = (row) => describePolicy(row, labels);
+  return [
+    {
+      key: 'scope',
+      label: 'Organisation',
+      render: (row) => {
+        const scope = d(row).scope;
+        return scope === PLATFORM_LABEL ? <Badge variant="info">{scope}</Badge> : scope;
+      },
+    },
+    { key: 'kind', label: 'Who must use 2FA', render: (row) => d(row).kind },
+    {
+      key: 'target',
+      label: 'Role or permission',
+      render: (row) =>
+        row.fields?.targetKind === 'permission' ? (
+          <code className="text-xs">{d(row).target}</code>
+        ) : (
+          d(row).target
+        ),
+    },
+    { key: 'grace', label: 'Grace period', render: (row) => d(row).grace },
+    { key: 'createdBy', label: 'Added by', render: (row) => d(row).createdBy },
+  ];
+}
+
+export default function SecuritySettingsPage() {
+  const { tokens, identity, securityPolicy, can } = useAuth();
+  const token = tokens?.accessToken;
+  const actions = policyActions(can);
+
+  const [rows, setRows] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const [limit, setLimit] = useState(DEFAULT_LIMIT);
+  const [labels, setLabels] = useState(undefined);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  // `null` = closed, `{ policy: null }` = add, `{ policy: row }` = edit.
+  const [dialog, setDialog] = useState(null);
+  const [deleteTarget, setDeleteTarget] = useState(null);
+  const [deleteBusy, setDeleteBusy] = useState(false);
+
+  const load = useCallback(async () => {
+    if (!token) return;
+    if (!securityPolicy) {
+      setError('Security policies are not available in this app.');
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    const r = await securityPolicy.list(token, { page, limit });
+    if (!r.ok) {
+      setRows([]);
+      setTotal(0);
+      setError(policyFailureText(r, 'load'));
+      setLoading(false);
+      return;
+    }
+    setRows(r.rows);
+    setTotal(r.total);
+    setError('');
+    setLabels(undefined);
+    setLoading(false);
+    // Names for the ids on this page (one lookup per unique id; fallbacks when gone or walled).
+    setLabels(
+      await resolvePolicyLabels(r.rows, {
+        getCompany: (id) => identity.getCompany(token, id),
+        getRole: (id) => identity.getRole(token, id),
+        getUser: (id) => identity.getUser(token, id),
+      }),
+    );
+  }, [securityPolicy, identity, token, page, limit]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const cols = useMemo(() => columns(labels), [labels]);
+
+  const onSaved = (message) => {
+    setDialog(null);
+    toast.success(message);
+    load();
+  };
+
+  const onConfirmDelete = async () => {
+    if (!deleteTarget || !securityPolicy) return;
+    setDeleteBusy(true);
+    const r = await securityPolicy.remove(token, deleteTarget.id);
+    setDeleteBusy(false);
+    if (!r.ok) {
+      toast.error(policyFailureText(r, 'delete'));
+      return;
+    }
+    setDeleteTarget(null);
+    toast.success('Policy deleted');
+    await load();
+  };
+
+  const deleteShown = deleteTarget ? describePolicy(deleteTarget, labels) : null;
+
+  return (
+    <AppShell section="Settings" title="Security">
+      <div className="space-y-4 p-4">
+        <PageHeader
+          section="Settings"
+          title="Security"
+          icon={Lock}
+          actions={
+            <EntityListControls
+              addLabel="Add 2FA policy"
+              onAdd={actions.add ? () => setDialog({ policy: null }) : undefined}
+            />
+          }
+        />
+
+        <div className="space-y-1">
+          <h2 className="text-sm font-semibold">Two-step verification policies</h2>
+          <p className="text-sm text-muted-foreground">
+            Require two-step verification (2FA) for everyone in an organisation, for holders of a
+            role, or for holders of a permission. Users without 2FA can only set it up until they
+            do, once their grace period ends.
+          </p>
+        </div>
+
+        {!loading && !error && showFloorNote(rows) && (
+          <Alert>
+            <Info className="size-4" />
+            <AlertDescription>
+              A platform-wide minimum set by the platform administrator may also apply. It is not
+              listed here.
+            </AlertDescription>
+          </Alert>
+        )}
+
+        <EntityList
+          columns={cols}
+          rows={rows}
+          loading={loading}
+          error={error}
+          emptyLabel="No 2FA policies yet. Users choose for themselves whether to use 2FA."
+          onEdit={actions.edit ? (row) => setDialog({ policy: row }) : undefined}
+          onDelete={actions.remove ? (row) => setDeleteTarget(row) : undefined}
+        />
+
+        <EntityListPager
+          total={total}
+          page={page}
+          limit={limit}
+          loading={loading}
+          error={error}
+          onPageChange={setPage}
+          onLimitChange={(l) => {
+            setLimit(l);
+            setPage(1);
+          }}
+        />
+      </div>
+
+      {dialog && (
+        <PolicyFormDialog
+          key={dialog.policy?.id ?? 'new'}
+          policy={dialog.policy}
+          labels={labels}
+          onClose={() => setDialog(null)}
+          onSaved={onSaved}
+        />
+      )}
+
+      <ConfirmDialog
+        open={!!deleteTarget}
+        title="Delete this 2FA policy?"
+        message={
+          deleteShown
+            ? `${deleteShown.kind} (${deleteShown.scope}) will no longer need 2FA because of this policy. Other policies still apply. This cannot be undone.`
+            : ''
+        }
+        confirmLabel="Delete"
+        destructive
+        busy={deleteBusy}
+        onConfirm={onConfirmDelete}
+        onCancel={() => setDeleteTarget(null)}
+      />
+    </AppShell>
+  );
+}

package/template/frontend/src/pages/security/securityPolicies.js

@@ -0,0 +1,246 @@
+// securityPolicies.js — the Security settings page's mandatory-2FA policies (auth capabilities
+// R2.1, R2.2, R2.6, R2.9, R11.4, R13.4, AC-26). Pure logic, tested by securityPolicies.test.mjs;
+// SecuritySettingsPage renders from it.
+//
+// Hiding an action is UX only: `/identity/security-policies` is `@Classified` per action and the
+// service applies the R2.6 authority rules (tighten vs lower, platform floor root only). A policy
+// carries ids (company node, role, author); they are resolved to names here, with a fallback label
+// for a deleted or unreadable record, and never rendered.
+
+/** The permission keys the routes are gated on. */
+export const SECURITY_POLICY_PERMISSIONS = {
+  read: 'identity:security_policy:read',
+  create: 'identity:security_policy:create',
+  update: 'identity:security_policy:update',
+  delete: 'identity:security_policy:delete',
+};
+
+/** Who a policy covers. */
+export const KIND_OPTIONS = [
+  { value: 'tenant', label: 'Everyone in this organisation' },
+  { value: 'role', label: 'Holders of a role' },
+  { value: 'permission', label: 'Holders of a permission' },
+];
+
+/** The longest grace period a policy can give (R2.4). */
+export const MAX_GRACE_DAYS = 14;
+
+/** The scope picker's value for the root-only platform minimum (not a company id). */
+export const PLATFORM_SCOPE = '__platform__';
+
+export const PLATFORM_LABEL = 'Platform minimum';
+
+const FALLBACK = {
+  company: 'Deleted company',
+  role: 'Deleted role',
+  user: 'Unknown user',
+};
+
+const PENDING = '…';
+
+// Mirror of core `isSecurityPolicyPermissionTarget`: a key `feature:object:action`, or a grant
+// wildcard `feature`, `feature:*`, `feature:object:*`.
+const SEGMENT = '[a-z][a-z0-9_]*';
+const PERMISSION_TARGET = new RegExp(
+  `^${SEGMENT}(?::\\*|:${SEGMENT}:\\*|:${SEGMENT}:${SEGMENT})?$`,
+);
+
+/** True for a permission key or grant wildcard the server accepts as a policy target. */
+export function isPermissionTarget(key) {
+  return typeof key === 'string' && key.length <= 255 && PERMISSION_TARGET.test(key);
+}
+
+const KIND_LABEL = Object.fromEntries(KIND_OPTIONS.map((k) => [k.value, k.label]));
+
+/** Which actions to show, from `can(permissionKey)`. */
+export function policyActions(can) {
+  return {
+    add: can(SECURITY_POLICY_PERMISSIONS.create),
+    edit: can(SECURITY_POLICY_PERMISSIONS.update),
+    remove: can(SECURITY_POLICY_PERMISSIONS.delete),
+  };
+}
+
+function isPlatform(row) {
+  return row?.fields?.platform === true || row?.fields?.platform === 1;
+}
+
+/** True when a platform-minimum row is listed; the server shows those to root only. */
+export function hasPlatformRow(rows) {
+  return Array.isArray(rows) && rows.some(isPlatform);
+}
+
+/** Show the "a platform minimum may also apply" note (non-root callers cannot see floor rows). */
+export function showFloorNote(rows) {
+  return !hasPlatformRow(rows);
+}
+
+/** The form state for a stored policy (edit). */
+export function policyFormFromRow(row) {
+  const f = row?.fields ?? {};
+  const kind = typeof f.targetKind === 'string' ? f.targetKind : 'tenant';
+  return {
+    scope: isPlatform(row) ? PLATFORM_SCOPE : (f.scopeNodeUuid ?? null),
+    kind,
+    role: kind === 'role' ? (f.targetValue ?? null) : null,
+    permission: kind === 'permission' ? (f.targetValue ?? '') : '',
+    graceDays: String(Number.isInteger(f.graceDays) ? f.graceDays : 0),
+  };
+}
+
+const GRACE_ERROR = `Grace period must be a whole number of days from 0 to ${MAX_GRACE_DAYS}.`;
+
+/**
+ * Check the form and build the request body: the create body, or on edit only the fields the
+ * server lets change (target value and grace; scope and kind are fixed at create).
+ * @param {{ scope: string | null, kind: string, role: string | null, permission: string, graceDays: string }} form
+ * @param {{ isEdit: boolean }} opts
+ * @returns {{ ok: true, body: object } | { ok: false, error: string }}
+ */
+export function validatePolicyForm(form, { isEdit }) {
+  const { scope, kind } = form;
+  if (!KIND_LABEL[kind]) return { ok: false, error: 'Choose who the policy covers.' };
+  if (!isEdit && !scope) return { ok: false, error: 'Choose an organisation.' };
+
+  let targetValue;
+  if (kind === 'role') {
+    if (!form.role) return { ok: false, error: 'Choose a role.' };
+    targetValue = form.role;
+  } else if (kind === 'permission') {
+    const key = String(form.permission ?? '').trim();
+    if (!isPermissionTarget(key)) {
+      return {
+        ok: false,
+        error:
+          'Enter a permission key such as identity:user:update, or a wildcard such as identity:*.',
+      };
+    }
+    targetValue = key;
+  }
+
+  const graceText = String(form.graceDays ?? '').trim();
+  const graceDays = /^\d+$/.test(graceText) ? Number(graceText) : NaN;
+  if (!Number.isInteger(graceDays) || graceDays < 0 || graceDays > MAX_GRACE_DAYS) {
+    return { ok: false, error: GRACE_ERROR };
+  }
+
+  if (isEdit) {
+    return {
+      ok: true,
+      body: { ...(targetValue !== undefined ? { targetValue } : {}), graceDays },
+    };
+  }
+  return {
+    ok: true,
+    body: {
+      ...(scope === PLATFORM_SCOPE ? { platform: true } : { scopeNodeUuid: scope }),
+      targetKind: kind,
+      ...(targetValue !== undefined ? { targetValue } : {}),
+      graceDays,
+    },
+  };
+}
+
+/** The unique company, role and user ids on these rows (a permission key is not an id). */
+export function collectLabelIds(rows) {
+  const companies = new Set();
+  const roles = new Set();
+  const users = new Set();
+  for (const row of rows || []) {
+    const f = row?.fields ?? {};
+    if (!isPlatform(row) && typeof f.scopeNodeUuid === 'string' && f.scopeNodeUuid) {
+      companies.add(f.scopeNodeUuid);
+    }
+    if (f.targetKind === 'role' && typeof f.targetValue === 'string' && f.targetValue) {
+      roles.add(f.targetValue);
+    }
+    if (typeof f.createdBy === 'string' && f.createdBy) users.add(f.createdBy);
+  }
+  return { companies, roles, users };
+}
+
+async function labelOf(lookup, id, pick, fallback) {
+  try {
+    const r = await lookup(id);
+    const name = r && r.ok && r.record ? pick(r.record.fields ?? {}) : '';
+    return typeof name === 'string' && name.trim() !== '' ? name : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+async function resolveAll(ids, lookup, pick, fallback) {
+  const out = new Map();
+  await Promise.all(
+    [...ids].map(async (id) => out.set(id, await labelOf(lookup, id, pick, fallback))),
+  );
+  return out;
+}
+
+/**
+ * Resolve every id on these rows to a name, one lookup per unique id (the page lists at most one
+ * page of policies). A record that is gone, walled or unreadable gets the fallback label.
+ * @param {Array<{ fields?: object }>} rows
+ * @param {{ getCompany: Function, getRole: Function, getUser: Function }} lookups each `(id) =>
+ *   Promise<{ ok, record }>` (frontend-core `identity.getCompany/getRole/getUser` bound to a token)
+ */
+export async function resolvePolicyLabels(rows, { getCompany, getRole, getUser }) {
+  const ids = collectLabelIds(rows);
+  const [companies, roles, users] = await Promise.all([
+    resolveAll(ids.companies, getCompany, (f) => f.name, FALLBACK.company),
+    resolveAll(ids.roles, getRole, (f) => f.name, FALLBACK.role),
+    resolveAll(ids.users, getUser, (f) => f.username || f.email, FALLBACK.user),
+  ]);
+  return { companies, roles, users };
+}
+
+function label(map, id, fallback) {
+  if (!map) return PENDING;
+  if (typeof id !== 'string' || id === '') return fallback;
+  return map.get(id) ?? fallback;
+}
+
+function graceText(days) {
+  const n = Number(days);
+  if (!Number.isInteger(n) || n <= 0) return 'None';
+  return n === 1 ? '1 day' : `${n} days`;
+}
+
+/**
+ * The display strings for one policy row — names only, never an id.
+ * @param {{ fields?: object }} row
+ * @param {{ companies: Map, roles: Map, users: Map } | undefined} labels undefined while loading
+ */
+export function describePolicy(row, labels) {
+  const f = row?.fields ?? {};
+  const kind = f.targetKind;
+  let target;
+  if (kind === 'tenant') target = 'Everyone';
+  else if (kind === 'role') target = label(labels?.roles, f.targetValue, FALLBACK.role);
+  else target = typeof f.targetValue === 'string' ? f.targetValue : '—';
+  return {
+    scope: isPlatform(row)
+      ? PLATFORM_LABEL
+      : label(labels?.companies, f.scopeNodeUuid, FALLBACK.company),
+    kind: KIND_LABEL[kind] ?? '—',
+    target,
+    grace: graceText(f.graceDays),
+    createdBy: label(labels?.users, f.createdBy, FALLBACK.user),
+  };
+}
+
+const GENERIC = {
+  load: 'Could not load security policies.',
+  save: 'Could not save the policy.',
+  delete: 'Could not delete the policy.',
+};
+
+/**
+ * The text for a failed service call. The service already passes the server's fixed 400/403/409
+ * message through (e.g. "Only a platform administrator can set a platform-wide policy.").
+ * @param {{ error?: string } | undefined} result
+ * @param {'load' | 'save' | 'delete'} verb
+ */
+export function policyFailureText(result, verb) {
+  return (result && result.error) || GENERIC[verb];
+}