Phase 1: identity, sessions, audit, frontend shell

AD sign-in over LDAPS (search with the service account, bind as the user,
nested groups through LDAP_MATCHING_RULE_IN_CHAIN, disabled accounts refused),
roles as the union of PS-* groups mapped by a table derived from the seeded
departments. Server-side sessions with idle, lock and absolute timeouts, Origin
and X-Requested-With check, step-up unlock. Optional Argon2id PIN set with the
domain password; PIN sign-in by employee ID on registered devices only; five
wrong attempts disable the PIN, three wrong at unlock or signature end the
session. Rate limits per account and per address before any bind. Devices,
signatures table and sign helper, audit rows for every identity event, SSE over
LISTEN/NOTIFY with presence. Account settings and Admin APIs and screens
(AD view, devices, PIN clearing, group map with missing-group flags, refresh
from AD now). CLI ad-groups --list and ad-refresh. Migration 0002.

Frontend: real sign-in (password tab, PIN keypad on registered devices), lock
screen, role switcher, Account settings, Admin shell, screen placeholders.

CI: Samba AD DC container (PSTEST.LOCAL) with a generated CA, 49 of the 50
groups plus one extra, 17 test users; wired into the CI compose overlay and
the Gitea workflow; Playwright sign-in scenario.

Verified on docker-1: 171 server tests green inside the CI stack against
PostgreSQL and the Samba DC, 48 frontend tests, 8 Playwright scenarios against
the live stack (password and PIN sign-in, lock and unlock, Admin group map).
Findings recorded in the docs: the DC needs CAP_SYS_ADMIN, a hidden tab locks
only after a minute as the old build did,
and the app uses the alias ps-app for Playwright because "app" is on
Chromium's HSTS preload list.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

frontend/src/lib/format.ts

@@ -0,0 +1,44 @@
+import { ApiError, retryAfter } from "../api/client";
+
+/** A short local date and time, or a dash. */
+export function fmtTime(iso: string | null | undefined): string {
+  if (!iso) return "-";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return d.toLocaleString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** An audit detail dict as "key: value, key: value". Never shows nested objects in full. */
+export function fmtDetail(detail: unknown): string {
+  if (detail === null || detail === undefined) return "";
+  if (typeof detail !== "object") return String(detail);
+  return Object.entries(detail as Record<string, unknown>)
+    .filter(([, v]) => v !== null && v !== undefined && v !== "")
+    .map(([k, v]) => `${k.replace(/_/g, " ")}: ${typeof v === "object" ? JSON.stringify(v) : String(v)}`)
+    .join(", ");
+}
+
+/** "Try again in N minutes." from a 429, rounded up, at least one. */
+export function retryText(err: unknown): string {
+  const secs = retryAfter(err) ?? 60;
+  const mins = Math.max(1, Math.ceil(secs / 60));
+  return `Try again in ${mins} ${mins === 1 ? "minute" : "minutes"}.`;
+}
+
+/** The message to show for a failed call. 429 adds the retry time. */
+export function errorText(err: unknown): string {
+  if (err instanceof ApiError) {
+    if (err.status === 429) return `Too many failed attempts. ${retryText(err)}`;
+    return err.message;
+  }
+  if (err instanceof Error) return err.message;
+  return "Something went wrong.";
+}
+
+export const DIGITS = /^\d+$/;

frontend/src/lib/keypad.ts

@@ -0,0 +1,9 @@
+// Keypad keys and how one press changes a field value.
+export type KeypadKey = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "clear" | "back";
+
+/** Applies one key press to a field value. Digits stop at `max` characters. */
+export function applyKey(value: string, key: KeypadKey, max = 64): string {
+  if (key === "clear") return "";
+  if (key === "back") return value.slice(0, -1);
+  return value.length >= max ? value : value + key;
+}

frontend/src/lib/pin.ts

@@ -0,0 +1,13 @@
+import { DIGITS } from "./format";
+
+export const PIN_MIN = 6;
+export const PIN_MAX = 12;
+
+/** Checks a new PIN the way the server does. Returns the message to show, or null. */
+export function pinProblem(pin: string, confirm: string, min = PIN_MIN, max = PIN_MAX): string | null {
+  if (!pin) return "Enter a new PIN.";
+  if (!DIGITS.test(pin)) return "The PIN must be digits only.";
+  if (pin.length < min || pin.length > max) return `The PIN must be ${min} to ${max} digits.`;
+  if (pin !== confirm) return "The two PINs do not match.";
+  return null;
+}

frontend/src/lib/useLoad.ts

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useState } from "react";
+import { errorText } from "./format";
+
+export type Load<T> =
+  | { state: "loading" }
+  | { state: "ok"; data: T }
+  | { state: "error"; message: string };
+
+/**
+ * Runs `fetcher` on mount and whenever `key` changes. `reload()` runs it again.
+ * Answers from an older run are dropped.
+ */
+export function useLoad<T>(fetcher: (signal: AbortSignal) => Promise<T>, key: string = ""): [Load<T>, () => void] {
+  const [load, setLoad] = useState<Load<T>>({ state: "loading" });
+  const [tick, setTick] = useState(0);
+
+  // The fetcher is read fresh on each run; callers pass inline arrows, and `key` says when to rerun.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const run = useCallback(fetcher, [key, tick]);
+
+  useEffect(() => {
+    const ctl = new AbortController();
+    run(ctl.signal)
+      .then((data) => {
+        if (!ctl.signal.aborted) setLoad({ state: "ok", data });
+      })
+      .catch((err: unknown) => {
+        if (!ctl.signal.aborted) setLoad({ state: "error", message: errorText(err) });
+      });
+    return () => ctl.abort();
+  }, [run]);
+
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+  return [load, reload];
+}