create-astram-app 0.11.0 → 0.12.0

package/template/frontend/src/pages/roles/roleRules.js

@@ -0,0 +1,104 @@
+// roleRules.js — the Roles page's pure logic (G-013): permission keys, the role name rule, the
+// company and role option mapping (names only, never ids) and the toast text. Tested by
+// roleRules.test.mjs; RolesPage, RoleForm and the posting editor's role picker render from it.
+// Showing, hiding or disabling a button is UX only: the server decides every write (permission,
+// subtree wall, duplicate name in the company, role owned by the posting's company).
+
+/** Permission keys of the role routes (`identity:role:<action>`). */
+export const ROLE_PERMISSIONS = {
+  read: 'identity:role:read',
+  create: 'identity:role:create',
+  update: 'identity:role:update',
+  delete: 'identity:role:delete',
+};
+
+/** The longest role name the server stores (spec §10, the G-012 name rule). */
+export const MAX_ROLE_NAME_LENGTH = 150;
+
+/** The list's empty state for a company with no roles. */
+export const EMPTY_ROLES_LABEL = 'No roles yet';
+
+/**
+ * What the caller may do with roles, from the auth-facts `can(key)`. UX only.
+ * @param {(key: string) => boolean} can
+ * @returns {{ read: boolean, create: boolean, rename: boolean, remove: boolean }}
+ */
+export function canManageRoles(can) {
+  if (typeof can !== 'function')
+    return { read: false, create: false, rename: false, remove: false };
+  return {
+    read: can(ROLE_PERMISSIONS.read) === true,
+    create: can(ROLE_PERMISSIONS.create) === true,
+    rename: can(ROLE_PERMISSIONS.update) === true,
+    remove: can(ROLE_PERMISSIONS.delete) === true,
+  };
+}
+
+// U+0000–U+001F and U+007F–U+009F.
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/**
+ * The server's role name rule (spec §10), checked before sending so the user sees the problem at
+ * once, in the same order as the server: NFC, trim and collapse whitespace, refuse control
+ * characters and an empty result, 1–150 characters. The server applies the same rule and
+ * decides; `value` is what it will store.
+ * @param {unknown} name
+ * @returns {{ ok: true, value: string } | { ok: false, error: string }}
+ */
+export function validateRoleName(name) {
+  const value = String(name ?? '')
+    .normalize('NFC')
+    .trim()
+    .replace(/\s+/g, ' ');
+  if (CONTROL.test(value)) {
+    return { ok: false, error: 'The role name cannot contain control characters.' };
+  }
+  if (value.length === 0) return { ok: false, error: 'Enter a role name.' };
+  if ([...value].length > MAX_ROLE_NAME_LENGTH) {
+    return {
+      ok: false,
+      error: `The role name can be at most ${MAX_ROLE_NAME_LENGTH} characters.`,
+    };
+  }
+  return { ok: true, value };
+}
+
+/**
+ * Engine RecordView rows (`{ id, fields: { name } }`, from `listCompanies` or `listCompanyRoles`)
+ * → SearchableSelect options. The id is the option value only; the label is the name, or
+ * "(unnamed)", never the id. Rows without an id are dropped.
+ * @param {Array<{ id?: string, fields?: { name?: string } }> | null | undefined} rows
+ * @returns {Array<{ value: string, label: string }>}
+ */
+export function nameOptions(rows) {
+  return (rows || [])
+    .filter((row) => row && typeof row.id === 'string' && row.id.length > 0)
+    .map((row) => ({
+      value: row.id,
+      label:
+        typeof row.fields?.name === 'string' && row.fields.name.length > 0
+          ? row.fields.name
+          : '(unnamed)',
+    }));
+}
+
+const DONE = { create: 'created', rename: 'renamed', delete: 'deleted' };
+const VERB = { create: 'create', rename: 'rename', delete: 'delete' };
+
+/**
+ * The toast for a create / rename / delete result: success text, or the server's message on a
+ * refusal (duplicate name in this company, bad name, out of reach), else a fixed fallback.
+ * @param {{ ok: boolean, error?: string } | null | undefined} result
+ * @param {'create' | 'rename' | 'delete'} action
+ * @returns {{ kind: 'success' | 'error', text: string }}
+ */
+export function roleOutcome(result, action) {
+  if (!result || !result.ok) {
+    return {
+      kind: 'error',
+      text: (result && result.error) || `Could not ${VERB[action] ?? 'save'} the role.`,
+    };
+  }
+  return { kind: 'success', text: `Role ${DONE[action] ?? 'saved'}` };
+}

package/template/frontend/src/pages/roles/roleRules.test.mjs

@@ -0,0 +1,178 @@
+// roleRules.test.mjs — G-013: the Roles page's permission keys, role name rule (spec §10), option
+// mapping (names only, never ids) and toast text.
+//
+//   node --test src/pages/roles/roleRules.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  EMPTY_ROLES_LABEL,
+  MAX_ROLE_NAME_LENGTH,
+  ROLE_PERMISSIONS,
+  canManageRoles,
+  nameOptions,
+  roleOutcome,
+  validateRoleName,
+} from './roleRules.js';
+
+describe('permission keys', () => {
+  test('match the server role routes', () => {
+    assert.deepEqual(ROLE_PERMISSIONS, {
+      read: 'identity:role:read',
+      create: 'identity:role:create',
+      update: 'identity:role:update',
+      delete: 'identity:role:delete',
+    });
+  });
+});
+
+describe('canManageRoles', () => {
+  const holding =
+    (...keys) =>
+    (k) =>
+      keys.includes(k);
+
+  test('read only: no write actions', () => {
+    assert.deepEqual(canManageRoles(holding('identity:role:read')), {
+      read: true,
+      create: false,
+      rename: false,
+      remove: false,
+    });
+  });
+
+  test('every key: every action', () => {
+    assert.deepEqual(canManageRoles(holding(...Object.values(ROLE_PERMISSIONS))), {
+      read: true,
+      create: true,
+      rename: true,
+      remove: true,
+    });
+  });
+
+  test('a non-boolean answer or no can() denies', () => {
+    assert.deepEqual(
+      canManageRoles(() => 'yes'),
+      {
+        read: false,
+        create: false,
+        rename: false,
+        remove: false,
+      },
+    );
+    assert.deepEqual(canManageRoles(undefined), {
+      read: false,
+      create: false,
+      rename: false,
+      remove: false,
+    });
+  });
+});
+
+describe('validateRoleName', () => {
+  test('trims, collapses whitespace and returns the stored value', () => {
+    assert.deepEqual(validateRoleName('  Shift \t  Lead  '), { ok: true, value: 'Shift Lead' });
+  });
+
+  test('normalises to NFC before measuring', () => {
+    const decomposed = 'Café';
+    const r = validateRoleName(decomposed);
+    assert.equal(r.ok, true);
+    assert.equal(r.value, 'Café');
+    assert.equal(r.value.length, 4);
+  });
+
+  test('refuses empty and whitespace-only names', () => {
+    for (const v of ['', '   ', null, undefined]) {
+      assert.deepEqual(validateRoleName(v), { ok: false, error: 'Enter a role name.' });
+    }
+  });
+
+  test('refuses C0 and C1 control characters (not whitespace)', () => {
+    for (const ch of ['\u0000', '\u0007', '\u001b', '\u007f', '\u0085', '\u009f']) {
+      assert.deepEqual(validateRoleName(`Man${ch}ager`), {
+        ok: false,
+        error: 'The role name cannot contain control characters.',
+      });
+    }
+  });
+
+  test('whitespace controls (tab, newline) are collapsed before the control check', () => {
+    assert.deepEqual(validateRoleName('Shift\nLead'), { ok: true, value: 'Shift Lead' });
+  });
+
+  test('allows 150 characters, refuses 151 (code points, not UTF-16 units)', () => {
+    assert.equal(MAX_ROLE_NAME_LENGTH, 150);
+    assert.equal(validateRoleName('a'.repeat(150)).ok, true);
+    assert.deepEqual(validateRoleName('a'.repeat(151)), {
+      ok: false,
+      error: 'The role name can be at most 150 characters.',
+    });
+    assert.equal(validateRoleName('\u{1F600}'.repeat(150)).ok, true);
+  });
+});
+
+describe('nameOptions', () => {
+  test('maps rows to { value: id, label: name }, never showing the id', () => {
+    const rows = [
+      { id: 'r-1', fields: { uuid: 'r-1', name: 'Manager', ownerCompanyUuid: 'co-1' } },
+      { id: 'r-2', fields: { uuid: 'r-2', name: '' } },
+      { id: 'r-3' },
+      { fields: { name: 'No id' } },
+      null,
+    ];
+    const options = nameOptions(rows);
+    assert.deepEqual(options, [
+      { value: 'r-1', label: 'Manager' },
+      { value: 'r-2', label: '(unnamed)' },
+      { value: 'r-3', label: '(unnamed)' },
+    ]);
+    for (const o of options) assert.notEqual(o.label, o.value);
+  });
+
+  test('no rows ⇒ no options', () => {
+    assert.deepEqual(nameOptions(undefined), []);
+    assert.deepEqual(nameOptions([]), []);
+  });
+});
+
+describe('roleOutcome', () => {
+  test('success texts', () => {
+    assert.deepEqual(roleOutcome({ ok: true }, 'create'), {
+      kind: 'success',
+      text: 'Role created',
+    });
+    assert.deepEqual(roleOutcome({ ok: true }, 'rename'), {
+      kind: 'success',
+      text: 'Role renamed',
+    });
+    assert.deepEqual(roleOutcome({ ok: true }, 'delete'), {
+      kind: 'success',
+      text: 'Role deleted',
+    });
+  });
+
+  test('a refusal shows the server message', () => {
+    const error = 'A role named "Manager" already exists in this company.';
+    assert.deepEqual(roleOutcome({ ok: false, status: 409, error }, 'create'), {
+      kind: 'error',
+      text: error,
+    });
+  });
+
+  test('no message ⇒ the fixed fallback', () => {
+    assert.deepEqual(roleOutcome({ ok: false, status: 0 }, 'create'), {
+      kind: 'error',
+      text: 'Could not create the role.',
+    });
+    assert.deepEqual(roleOutcome(null, 'delete'), {
+      kind: 'error',
+      text: 'Could not delete the role.',
+    });
+  });
+});
+
+describe('empty state', () => {
+  test('reads "No roles yet"', () => {
+    assert.equal(EMPTY_ROLES_LABEL, 'No roles yet');
+  });
+});

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

@@ -0,0 +1,243 @@
+/**
+ * PolicyFormDialog — add or edit one mandatory-2FA policy (auth capabilities R2.1, R2.2, R2.4).
+ *
+ * Add: organisation (a company you can see, or the platform minimum), who it covers (everyone /
+ * a role / a permission key), and the grace period. Edit: only the role or permission and the
+ * grace period change; the organisation and kind are fixed at create (a different one is a delete
+ * plus an add), so they are shown as text.
+ *
+ * Validation lives in `securityPolicies.js`; the server stays authoritative (R2.6: lowering a
+ * policy needs more access than tightening it, the platform minimum is root only) and its fixed
+ * refusal is shown as the form error. Ids are picker values only; the user sees names.
+ */
+import { useCallback, useState } from 'react';
+import { useAuth } from '@/auth/AuthContext';
+import EntityFormModal from '@/components/EntityFormModal';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { SearchableSelect } from '@/components/ui/searchable-select';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import {
+  KIND_OPTIONS,
+  MAX_GRACE_DAYS,
+  PLATFORM_LABEL,
+  PLATFORM_SCOPE,
+  describePolicy,
+  policyFailureText,
+  policyFormFromRow,
+  validatePolicyForm,
+} from './securityPolicies';
+
+const PLATFORM_OPTION = {
+  value: PLATFORM_SCOPE,
+  label: `${PLATFORM_LABEL} (platform administrators only)`,
+};
+
+export default function PolicyFormDialog({ policy, labels, onClose, onSaved }) {
+  const { tokens, identity, profile, securityPolicy } = useAuth();
+  const token = tokens?.accessToken;
+  const isEdit = Boolean(policy);
+  const shown = isEdit ? describePolicy(policy, labels) : null;
+
+  const [form, setForm] = useState(() =>
+    isEdit
+      ? policyFormFromRow(policy)
+      : {
+          scope: profile?.company?.id ?? null,
+          kind: 'tenant',
+          role: null,
+          permission: '',
+          graceDays: '0',
+        },
+  );
+  const [scopeLabel, setScopeLabel] = useState(() => profile?.company?.name ?? null);
+  const [roleLabel, setRoleLabel] = useState(() => (isEdit ? shown.target : null));
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+
+  const set = (patch) => setForm((f) => ({ ...f, ...patch }));
+
+  const fetchScopes = useCallback(
+    async ({ search, page, limit }) => {
+      const r = await identity.listCompanies(token, {
+        page,
+        limit,
+        search,
+        sortBy: 'name',
+        sortOrder: 'asc',
+      });
+      const companies = r.ok
+        ? (r.rows || []).map((row) => ({ value: row.id, label: row.fields?.name || '(unnamed)' }))
+        : [];
+      // The platform minimum is offered at the top of the first unfiltered page. Only a root
+      // account may save it; the server refuses anyone else with a fixed message.
+      const withFloor = page === 1 && !search ? [PLATFORM_OPTION, ...companies] : companies;
+      return { options: withFloor, total: r.ok ? (r.total ?? 0) : 0, page: r.page ?? page };
+    },
+    [identity, token],
+  );
+
+  const fetchRoles = useCallback(
+    async ({ search, page, limit }) => {
+      const r = await identity.listRoles(token, {
+        page,
+        limit,
+        search,
+        sortBy: 'name',
+        sortOrder: 'asc',
+      });
+      if (!r.ok) return { options: [], total: 0, page };
+      return {
+        options: (r.rows || []).map((row) => ({
+          value: row.id,
+          label: row.fields?.name || '(unnamed)',
+        })),
+        total: r.total ?? 0,
+        page: r.page ?? page,
+      };
+    },
+    [identity, token],
+  );
+
+  const onSubmit = async () => {
+    const checked = validatePolicyForm(form, { isEdit });
+    if (!checked.ok) {
+      setError(checked.error);
+      return;
+    }
+    if (!securityPolicy) {
+      setError('Security policies are not available in this app.');
+      return;
+    }
+    setError('');
+    setBusy(true);
+    const r = isEdit
+      ? await securityPolicy.update(token, policy.id, checked.body)
+      : await securityPolicy.create(token, checked.body);
+    setBusy(false);
+    if (!r.ok) {
+      setError(policyFailureText(r, 'save'));
+      return;
+    }
+    onSaved(isEdit ? 'Policy updated' : 'Policy added');
+  };
+
+  return (
+    <EntityFormModal
+      title={isEdit ? 'Edit 2FA policy' : 'Add 2FA policy'}
+      description="Users this policy covers must set up two-step verification to sign in."
+      open
+      onClose={onClose}
+      onSubmit={onSubmit}
+      submitLabel={isEdit ? 'Save changes' : 'Add policy'}
+      busy={busy}
+      error={error}
+      expandable={false}
+    >
+      <div className="space-y-1.5">
+        <Label variant="field">Organisation</Label>
+        {isEdit ? (
+          <p className="text-sm">{shown.scope}</p>
+        ) : (
+          <SearchableSelect
+            value={form.scope}
+            selectedLabel={scopeLabel}
+            onChange={(scope) => set({ scope })}
+            onLabelChange={setScopeLabel}
+            fetchPage={fetchScopes}
+            placeholder="Select an organisation"
+            searchPlaceholder="Search organisations"
+          />
+        )}
+        {!isEdit && form.scope !== PLATFORM_SCOPE && (
+          <p className="text-xs text-muted-foreground">
+            Applies to this organisation and every organisation under it.
+          </p>
+        )}
+      </div>
+
+      <div className="space-y-1.5">
+        <Label htmlFor="policy-kind" variant="field">
+          Who must use 2FA
+        </Label>
+        {isEdit ? (
+          <p className="text-sm">{shown.kind}</p>
+        ) : (
+          <Select value={form.kind} onValueChange={(kind) => set({ kind })}>
+            <SelectTrigger id="policy-kind">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {KIND_OPTIONS.map((k) => (
+                <SelectItem key={k.value} value={k.value}>
+                  {k.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        )}
+      </div>
+
+      {form.kind === 'role' && (
+        <div className="space-y-1.5">
+          <Label variant="field">Role</Label>
+          <SearchableSelect
+            value={form.role}
+            selectedLabel={roleLabel}
+            onChange={(role) => set({ role })}
+            onLabelChange={setRoleLabel}
+            fetchPage={fetchRoles}
+            placeholder="Select a role"
+            searchPlaceholder="Search roles"
+          />
+        </div>
+      )}
+
+      {form.kind === 'permission' && (
+        <div className="space-y-1.5">
+          <Label htmlFor="policy-permission" variant="field">
+            Permission
+          </Label>
+          <Input
+            id="policy-permission"
+            maxLength={255}
+            autoComplete="off"
+            spellCheck={false}
+            placeholder="e.g. identity:user:update or identity:*"
+            value={form.permission}
+            onChange={(e) => set({ permission: e.target.value })}
+          />
+          <p className="text-xs text-muted-foreground">
+            Anyone holding this permission, or any permission a wildcard covers.
+          </p>
+        </div>
+      )}
+
+      <div className="space-y-1.5">
+        <Label htmlFor="policy-grace" variant="field">
+          Grace period (days)
+        </Label>
+        <Input
+          id="policy-grace"
+          type="number"
+          inputMode="numeric"
+          min={0}
+          max={MAX_GRACE_DAYS}
+          step={1}
+          value={form.graceDays}
+          onChange={(e) => set({ graceDays: e.target.value })}
+        />
+        <p className="text-xs text-muted-foreground">
+          0 to {MAX_GRACE_DAYS}. Each user gets this many days to set up 2FA from when the policy
+          first applies to them. 0 means they must set it up at their next sign-in.
+        </p>
+      </div>
+    </EntityFormModal>
+  );
+}