feat(auth): dynamic RBAC — composable roles + resource×CRUD permissions

Replace the hardcoded role enum (admin/operator/cashier/readonly, checked
literally as requireRole("admin",...) across ~15 routes) with dynamic RBAC:
roles are DATA, route guards check a PERMISSION.

@parking/shared defines a code-defined grid: RESOURCES (user/role/tariff/
subscription/site/device/shift/payment/session/event/report) × Action
(create/read/update/delete + domain verbs void/cash) -> PERMISSIONS
(resource:action, e.g. tariff:update, payment:create, event:void).

DB: new roles + role_permissions tables; users.role enum -> role_id FK;
migration 0007_rbac (create tables, seed the builtin admin role + all 26
perms, seed operator/cashier/readonly composable roles matching old
behaviour, rebuild users to swap the column copying all rows).

auth.ts: JWT payload role -> roleId; permissionsFor(roleId) with an
in-memory cache + bumpPermsCache(); requirePermission(...perms) preHandler;
requireAuth for /me & /language; initAuth(db) wires the resolver once. Every
route guard mapped to a permission; device ingress (devices/qr-reader) stays
auth-free by design. New routes/users.ts (user:* CRUD, bcrypt 12, last-admin
guard) + routes/roles.ts (role:* CRUD, builtin-protected, perms validated
against the grid, cache bump on write). auth/me + /login return
{roleId, roleName, permissions, language}. seed-admin -> roleId:'admin'.

Frontend: SessionUser carries permissions + can() helper; router nav/route
guards gate by permission (requirePerm replaces adminOnly); SiteSettings
edit gated by site:update; new UsersManager + RolesManager (permission
checkbox grid; admin role locked); i18n nav.users/roles + blocks (sq+en).

Decisions: one role per user; protected built-in admin (no-lockout: the last
admin can't be deleted/downgraded); JWT carries roleId, perms resolved
per-request so role edits apply immediately (no re-login).

Verified: full build green; 20-assertion inject test passes (cashier 403s on
tariff publish + user list, admin passes, granting a perm applies on the next
request, last-admin + builtin-role protections return 409); migration 0007
applied to a copy of the live DB (incl WAL/shm) — existing admin maps to
role_id='admin', all rows preserved. Append-only event chain untouched
(event:void gates appending a void, not a delete).

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

apps/server/src/auth.ts

@@ -1,16 +1,22 @@
 import { randomBytes } from "node:crypto";
 import type { FastifyReply, FastifyRequest } from "fastify";
-import type { Role } from "@parking/shared";
+import { eq, rolePermissions, type Db } from "@parking/db";
+import { ADMIN_ROLE_ID, PERMISSIONS, type Permission } from "@parking/shared";
 
 // Local JWT auth helpers — fully local, no external identity provider
 // (offline-first). The JWT is carried in an HttpOnly cookie (JS can't read it);
 // a separate readable CSRF cookie + matching header defends mutations
 // (double-submit). See wiki/entities/local-jwt-auth.md.
+//
+// Authorization is DYNAMIC RBAC: the token carries the user's `roleId`, and each
+// guarded route resolves that role's PERMISSION SET (cached in memory) and checks
+// the permission it requires. Editing a role takes effect on the next request —
+// no re-login, no token bloat, no stale perms. See @parking/shared PERMISSIONS.
 
 declare module "@fastify/jwt" {
   interface FastifyJWT {
-    payload: { sub: string; username: string; role: Role; csrf: string };
-    user: { sub: string; username: string; role: Role; csrf: string };
+    payload: { sub: string; username: string; roleId: string; csrf: string };
+    user: { sub: string; username: string; roleId: string; csrf: string };
   }
 }
 
@@ -96,17 +102,84 @@ function assertCsrf(req: FastifyRequest): void {
   }
 }
 
+// --- Permission resolution + cache -------------------------------------------
+// A role's permission set is read from `role_permissions` and cached in memory.
+// SQLite is single-writer/single-process here, so a module-level Map is a correct
+// cache: every role / role-permission mutation calls bumpPermsCache() to clear it,
+// and the next request re-reads. The built-in `admin` role always resolves to the
+// FULL permission set in code (never trusts the DB rows for it), so administration
+// can't be accidentally narrowed.
+
+const ADMIN_PERMS: ReadonlySet<Permission> = new Set(PERMISSIONS);
+const permsCache = new Map<string, ReadonlySet<Permission>>();
+
+// The DB handle the permission resolver reads from. Set ONCE at startup via
+// initAuth() so route guards don't each have to thread `db` (several route
+// modules only receive a monitor/service, not the db). Single-process server.
+let authDb: Db | null = null;
+
+/** Wire the permission resolver to the app's DB. Call once in buildServer(). */
+export function initAuth(db: Db): void {
+  authDb = db;
+  permsCache.clear();
+}
+
+/** Clear the permission cache. Call after ANY write to roles / role_permissions
+ *  (or a user's roleId) so the change takes effect on the next request. */
+export function bumpPermsCache(): void {
+  permsCache.clear();
+}
+
+/** The permission set for a role id, cached. `admin` is always the full set. */
+export function permissionsFor(roleId: string): ReadonlySet<Permission> {
+  if (roleId === ADMIN_ROLE_ID) return ADMIN_PERMS;
+  const hit = permsCache.get(roleId);
+  if (hit) return hit;
+  if (!authDb) throw new Error("auth not initialised (call initAuth)");
+  const rows = authDb
+    .select({ permission: rolePermissions.permission })
+    .from(rolePermissions)
+    .where(eq(rolePermissions.roleId, roleId))
+    .all();
+  const set = new Set(rows.map((r) => r.permission as Permission));
+  permsCache.set(roleId, set);
+  return set;
+}
+
+/** True if the role grants every listed permission. */
+export function roleHasPermissions(
+  roleId: string,
+  required: readonly Permission[],
+): boolean {
+  const granted = permissionsFor(roleId);
+  return required.every((p) => granted.has(p));
+}
+
 /**
- * preHandler role guard. Verifies the JWT (from the HttpOnly cookie), enforces
- * CSRF on mutations, then checks the role. Authorization is a simple per-route
- * role check — no Casbin/RBAC engine needed at this scale.
+ * preHandler permission guard. Verifies the JWT (from the HttpOnly cookie),
+ * enforces CSRF on mutations, then requires the user's role to grant ALL of the
+ * listed permissions. Authorization is a per-route permission check against the
+ * dynamic, admin-composed role grid — no Casbin/RBAC engine needed at this scale.
  */
-export function requireRole(...allowed: Role[]) {
+export function requirePermission(...required: Permission[]) {
   return async (req: FastifyRequest, _reply: FastifyReply) => {
     await req.jwtVerify(); // reads the token cookie (configured in server.ts)
     assertCsrf(req);
-    if (!req.user || !allowed.includes(req.user.role)) {
+    if (!req.user || !roleHasPermissions(req.user.roleId, required)) {
       throw Object.assign(new Error("forbidden"), { statusCode: 403 });
     }
   };
 }
+
+/**
+ * preHandler that requires a valid signed-in session but NO specific permission —
+ * for "about me" routes (/me, change own language) every authenticated user may
+ * call regardless of role. Still enforces CSRF on mutations.
+ */
+export async function requireAuth(
+  req: FastifyRequest,
+  _reply: FastifyReply,
+): Promise<void> {
+  await req.jwtVerify();
+  assertCsrf(req);
+}

apps/server/src/routes/auth.ts

@@ -1,10 +1,11 @@
 import bcrypt from "bcrypt";
 import type { FastifyInstance } from "fastify";
-import { eq, users, type Db } from "@parking/db";
+import { eq, roles, users, type Db } from "@parking/db";
 import {
   clearAuthCookies,
   newCsrfToken,
-  requireRole,
+  permissionsFor,
+  requireAuth,
   setAuthCookies,
 } from "../auth.js";
 
@@ -22,6 +23,22 @@ interface LanguageBody {
   language: Lang;
 }
 
+/** The session shape the SPA bootstraps from: identity + role + its permission
+ *  list (so the UI can gate nav/routes) + language. Role NAME is for display; the
+ *  permissions are the source of truth. */
+function sessionView(db: Db, user: { id: string; username: string; roleId: string; language: string }) {
+  const role = db.select().from(roles).where(eq(roles.id, user.roleId)).get();
+  const permissions = [...permissionsFor(user.roleId)];
+  return {
+    id: user.id,
+    username: user.username,
+    roleId: user.roleId,
+    roleName: role?.name ?? user.roleId,
+    permissions,
+    language: user.language,
+  };
+}
+
 export async function authRoutes(app: FastifyInstance, db: Db): Promise<void> {
   app.post<{ Body: LoginBody }>("/api/auth/login", async (req, reply) => {
     const { username, password } = req.body ?? {};
@@ -39,17 +56,19 @@ export async function authRoutes(app: FastifyInstance, db: Db): Promise<void> {
     }
 
     const csrf = newCsrfToken();
-    // No expiresIn: the token is valid until explicit logout (see auth.ts).
+    // No expiresIn: the token is valid until explicit logout (see auth.ts). The
+    // token carries roleId (not the permission list) — perms resolve per-request,
+    // so a role edit applies immediately with no re-login.
     const token = await reply.jwtSign({
       sub: user.id,
       username: user.username,
-      role: user.role,
+      roleId: user.roleId,
       csrf,
     });
     setAuthCookies(reply, token, csrf);
     // `language` is NOT in the JWT (identity/role only) — it's a mutable preference
     // read from the DB, so changing it needs no token refresh.
-    return { id: user.id, username: user.username, role: user.role, language: user.language };
+    return sessionView(db, user);
   });
 
   app.post("/api/auth/logout", async (_req, reply) => {
@@ -61,11 +80,15 @@ export async function authRoutes(app: FastifyInstance, db: Db): Promise<void> {
   // `language` preference from the DB (not the token).
   app.get(
     "/api/auth/me",
-    { preHandler: requireRole("admin", "operator", "cashier", "readonly") },
-    async (req) => {
-      const { sub, username, role } = req.user;
-      const row = await db.select().from(users).where(eq(users.id, sub)).get();
-      return { id: sub, username, role, language: row?.language ?? "sq" };
+    { preHandler: requireAuth },
+    async (req, reply) => {
+      const row = await db.select().from(users).where(eq(users.id, req.user.sub)).get();
+      if (!row) {
+        // The user was deleted while their cookie was still valid — clear it.
+        clearAuthCookies(reply);
+        return reply.code(401).send({ error: "session no longer valid" });
+      }
+      return sessionView(db, row);
     },
   );
 
@@ -73,7 +96,7 @@ export async function authRoutes(app: FastifyInstance, db: Db): Promise<void> {
   // users row so it's restored on the next login, from any booth. See i18n.md.
   app.put<{ Body: LanguageBody }>(
     "/api/auth/language",
-    { preHandler: requireRole("admin", "operator", "cashier", "readonly") },
+    { preHandler: requireAuth },
     async (req, reply) => {
       const language = req.body?.language;
       if (!language || !LANGS.includes(language)) {

apps/server/src/routes/device-status.ts

@@ -1,5 +1,5 @@
 import type { FastifyInstance } from "fastify";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import type { DeviceMonitor } from "../device-monitor.js";
 
 // Unified device-status snapshot for the booth footer. The DeviceMonitor polls all
@@ -13,7 +13,7 @@ export async function deviceStatusRoutes(
   app: FastifyInstance,
   monitor: DeviceMonitor,
 ): Promise<void> {
-  const guard = requireRole("admin", "operator", "cashier", "readonly");
+  const guard = requirePermission("device:read");
 
   app.get("/api/devices/status", { preHandler: guard }, async () => ({
     devices: monitor.snapshot(),

apps/server/src/routes/events.ts

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from "fastify";
 import { desc, gte, ledgerEvents, type Db } from "@parking/db";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import type { EventLog } from "../event-log.js";
 
 // Read access to the append-only signed event log. NO write/update/delete routes
@@ -13,8 +13,8 @@ export async function eventRoutes(
   db: Db,
   eventLog: EventLog,
 ): Promise<void> {
-  // Any authenticated role may read the log (it's the audit trail).
-  const guard = requireRole("admin", "operator", "cashier", "readonly");
+  // Reading the log (the audit trail).
+  const guard = requirePermission("event:read");
 
   // Recent events, newest first. `limit` caps the page (default 100, max 1000).
   // Optional `since` (ISO) scopes the page to events at/after that instant — the
@@ -42,7 +42,7 @@ export async function eventRoutes(
   // reconciliation job / "is the log intact?" check calls.
   app.get(
     "/api/events/verify",
-    { preHandler: requireRole("admin") },
+    { preHandler: requirePermission("event:read") },
     async () => eventLog.verifyChain(),
   );
 }

apps/server/src/routes/pay.ts

@@ -1,7 +1,7 @@
 import type { FastifyInstance } from "fastify";
 import type { Db } from "@parking/db";
 import { NoPrinterAvailableError } from "@parking/devices";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import {
   NoOpenSessionError,
   NoTariffError,
@@ -44,8 +44,12 @@ export async function payRoutes(
   exitFlow: ExitFlow,
   shift: ShiftService,
 ): Promise<void> {
-  // Cashier/operator/admin operate the booth; readonly may not.
-  const guard = requireRole("admin", "operator", "cashier");
+  // Reads (lookup, active sessions, quote) need session/payment read; the booth
+  // money actions (pay, exit, voucher, receipt, reopen) need payment:create. A
+  // single guard covers the whole booth flow — anyone who takes payment also reads
+  // sessions. Read-only callers (a viewer role) get the reads but not the actions.
+  const guard = requirePermission("payment:create");
+  const readGuard = requirePermission("session:read");
 
   // Money-path gate: a shift must be open site-wide before any payment/exit/voucher/
   // re-open is processed, so every taking is attributed to a shift (one operator's
@@ -70,7 +74,7 @@ export async function payRoutes(
   // Active sessions for the booth list: still-open OR exited-but-within-grace
   // (barrier unconfirmed → a paid/exited car is presumed possibly-present until
   // grace expires). Read-only. See wiki/concepts/booth-exit-flow.md.
-  app.get("/api/sessions/active", { preHandler: guard }, async () => ({
+  app.get("/api/sessions/active", { preHandler: readGuard }, async () => ({
     sessions: payStation.activeSessions(),
   }));
 
@@ -78,7 +82,7 @@ export async function payRoutes(
   // amount owed now, walk-back-grace status. Read-only (no side effect).
   app.get<{ Params: { identity: string } }>(
     "/api/session/:identity",
-    { preHandler: guard },
+    { preHandler: readGuard },
     async (req, reply) => {
       const identity = (req.params.identity ?? "").trim();
       if (!identity) return reply.code(400).send({ error: "identity required" });
@@ -124,7 +128,7 @@ export async function payRoutes(
   // Quote: what does this session owe right now? (No side effect.)
   app.get<{ Querystring: QuoteQuery }>(
     "/api/pay/quote",
-    { preHandler: guard },
+    { preHandler: readGuard },
     async (req, reply) => {
       const identity = (req.query.identity ?? "").trim();
       if (!identity) return reply.code(400).send({ error: "identity required" });

apps/server/src/routes/printers.ts

@@ -1,5 +1,5 @@
 import type { FastifyInstance } from "fastify";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import { deviceEvents } from "../device-events.js";
 import type { PrinterMonitor } from "../printer-monitor.js";
 
@@ -12,7 +12,7 @@ export async function printerRoutes(
   app: FastifyInstance,
   monitor: PrinterMonitor,
 ): Promise<void> {
-  const guard = requireRole("admin", "operator", "cashier", "readonly");
+  const guard = requirePermission("device:read");
 
   // Current status of every monitored printer (cached — no device round-trip).
   app.get("/api/printers/status", { preHandler: guard }, async () => ({

apps/server/src/routes/roles.ts

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import type { FastifyInstance } from "fastify";
+import { eq, rolePermissions, roles, users, type Db } from "@parking/db";
+import { ADMIN_ROLE_ID, PERMISSIONS, type Permission } from "@parking/shared";
+import { bumpPermsCache, requirePermission } from "../auth.js";
+
+// Role management (admin). Roles are DATA: an admin composes a role from the
+// code-defined PERMISSIONS grid (resource:action), and users are assigned one
+// role. The built-in `admin` role (id ADMIN_ROLE_ID) is PROTECTED — it can't be
+// edited or deleted and always resolves to every permission in code. Every write
+// here bumps the in-memory permission cache so changes take effect on the next
+// request. See @parking/shared PERMISSIONS and ../auth.ts.
+
+interface RoleBody {
+  name: string;
+  permissions: string[];
+}
+interface UpdateBody {
+  name?: string;
+  permissions?: string[];
+}
+
+const VALID = new Set<string>(PERMISSIONS);
+
+/** Validate + dedupe a requested permission list against the code-defined grid. */
+function cleanPermissions(input: unknown): { ok: true; perms: Permission[] } | { ok: false; bad: string } {
+  if (!Array.isArray(input)) return { ok: false, bad: "permissions must be an array" };
+  const out = new Set<Permission>();
+  for (const p of input) {
+    if (typeof p !== "string" || !VALID.has(p)) return { ok: false, bad: `unknown permission: ${String(p)}` };
+    out.add(p as Permission);
+  }
+  return { ok: true, perms: [...out] };
+}
+
+export async function roleRoutes(app: FastifyInstance, db: Db): Promise<void> {
+  const readGuard = requirePermission("role:read");
+  const createGuard = requirePermission("role:create");
+  const updateGuard = requirePermission("role:update");
+  const deleteGuard = requirePermission("role:delete");
+
+  /** A role + its permission list + how many users hold it. */
+  function roleView(roleId: string) {
+    const role = db.select().from(roles).where(eq(roles.id, roleId)).get();
+    if (!role) return null;
+    const perms = db
+      .select({ permission: rolePermissions.permission })
+      .from(rolePermissions)
+      .where(eq(rolePermissions.roleId, roleId))
+      .all()
+      .map((r) => r.permission);
+    const userCount = db.select().from(users).where(eq(users.roleId, roleId)).all().length;
+    // The admin role always reports the full grid (it's enforced in code).
+    return {
+      id: role.id,
+      name: role.name,
+      builtin: role.builtin === 1,
+      permissions: role.id === ADMIN_ROLE_ID ? [...PERMISSIONS] : perms,
+      userCount,
+    };
+  }
+
+  /** Replace a role's permission rows with `perms` (in a single pass). */
+  function setPermissions(roleId: string, perms: Permission[]): void {
+    db.delete(rolePermissions).where(eq(rolePermissions.roleId, roleId)).run();
+    for (const p of perms) {
+      db.insert(rolePermissions).values({ roleId, permission: p }).run();
+    }
+  }
+
+  // The full permission grid (for the role-composer checkbox UI) + every role.
+  app.get("/api/roles", { preHandler: readGuard }, async () => {
+    const all = db.select().from(roles).all();
+    return {
+      catalog: PERMISSIONS,
+      roles: all.map((r) => roleView(r.id)).filter((r) => r != null),
+    };
+  });
+
+  // Create a composable role from a name + a permission set.
+  app.post<{ Body: RoleBody }>("/api/roles", { preHandler: createGuard }, async (req, reply) => {
+    const name = (req.body?.name ?? "").trim();
+    if (!name) return reply.code(400).send({ error: "name required" });
+    if (db.select().from(roles).where(eq(roles.name, name)).get()) {
+      return reply.code(409).send({ error: "a role with that name already exists" });
+    }
+    const cleaned = cleanPermissions(req.body?.permissions ?? []);
+    if (!cleaned.ok) return reply.code(400).send({ error: cleaned.bad });
+
+    const id = randomUUID();
+    db.insert(roles).values({ id, name, builtin: 0 }).run();
+    setPermissions(id, cleaned.perms);
+    bumpPermsCache();
+    return reply.code(201).send(roleView(id));
+  });
+
+  // Edit a role's name and/or permission set. The built-in admin role is locked.
+  app.put<{ Params: { id: string }; Body: UpdateBody }>(
+    "/api/roles/:id",
+    { preHandler: updateGuard },
+    async (req, reply) => {
+      const id = req.params.id;
+      const role = db.select().from(roles).where(eq(roles.id, id)).get();
+      if (!role) return reply.code(404).send({ error: "role not found" });
+      if (role.builtin === 1) {
+        return reply.code(409).send({ error: "the built-in admin role cannot be edited" });
+      }
+
+      if (req.body?.name != null) {
+        const name = req.body.name.trim();
+        if (!name) return reply.code(400).send({ error: "name cannot be empty" });
+        const clash = db.select().from(roles).where(eq(roles.name, name)).get();
+        if (clash && clash.id !== id) return reply.code(409).send({ error: "a role with that name already exists" });
+        db.update(roles).set({ name }).where(eq(roles.id, id)).run();
+      }
+      if (req.body?.permissions != null) {
+        const cleaned = cleanPermissions(req.body.permissions);
+        if (!cleaned.ok) return reply.code(400).send({ error: cleaned.bad });
+        setPermissions(id, cleaned.perms);
+      }
+      bumpPermsCache();
+      return roleView(id);
+    },
+  );
+
+  // Delete a role. Refused if it's built-in or any user still holds it.
+  app.delete<{ Params: { id: string } }>(
+    "/api/roles/:id",
+    { preHandler: deleteGuard },
+    async (req, reply) => {
+      const id = req.params.id;
+      const role = db.select().from(roles).where(eq(roles.id, id)).get();
+      if (!role) return reply.code(404).send({ error: "role not found" });
+      if (role.builtin === 1) {
+        return reply.code(409).send({ error: "the built-in admin role cannot be deleted" });
+      }
+      const holders = db.select().from(users).where(eq(users.roleId, id)).all().length;
+      if (holders > 0) {
+        return reply.code(409).send({ error: `cannot delete a role still assigned to ${holders} user(s)` });
+      }
+      db.delete(rolePermissions).where(eq(rolePermissions.roleId, id)).run();
+      db.delete(roles).where(eq(roles.id, id)).run();
+      bumpPermsCache();
+      return { ok: true };
+    },
+  );
+}

apps/server/src/routes/setup.ts

@@ -12,7 +12,7 @@ import {
   type DeviceCategory,
   type DeviceConfig,
 } from "@parking/devices";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import { backendIpCandidates, backendIpForDevice, backendPort } from "../net.js";
 
 // First-run setup API. The admin reads the driver catalog and assigns devices
@@ -176,8 +176,9 @@ export async function setupRoutes(app: FastifyInstance, db: Db): Promise<void> {
   registerBuiltinDrivers();
   setDeviceLogSink((line) => app.log.info(line));
 
-  // Setup endpoints require an admin (cookie-based JWT — see ../auth.ts).
-  const adminGuard = requireRole("admin");
+  // Device setup is site administration — it changes which hardware the site runs
+  // and how readers bind to relays. Gated on site:update. See ../auth.ts.
+  const adminGuard = requirePermission("site:update");
 
   // Catalog of selectable drivers per category (no secrets — schema only).
   // `discoverable` flags drivers that can scan the LAN; `pushCapable` flags

apps/server/src/routes/shift.ts

@@ -1,5 +1,5 @@
 import type { FastifyInstance } from "fastify";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import {
   InvalidCashMovementError,
   NoOpenShiftError,
@@ -19,8 +19,9 @@ interface CashMovementBody {
 // local-jwt-auth.md "until logout"). End Shift signs a shift_z_report + prints it.
 
 export async function shiftRoutes(app: FastifyInstance, shift: ShiftService): Promise<void> {
-  // Cashier/operator/admin run shifts; readonly can't.
-  const guard = requireRole("admin", "operator", "cashier");
+  // Reading the shift state vs. opening/closing one's own shift.
+  const readGuard = requirePermission("shift:read");
+  const guard = requirePermission("shift:create");
 
   // The SITE-WIDE shift state (at most one shift open at a time). The UI uses this
   // to render the header control: no shift → "Open"; my shift → "Close" (enabled);
@@ -28,7 +29,7 @@ export async function shiftRoutes(app: FastifyInstance, shift: ShiftService): Pr
   //  - open:    the open shift { startedAt, operator } or null (site-wide)
   //  - isMine:  true iff the open shift belongs to the requesting operator
   //  - operator: the requesting user (for the UI's own identity)
-  app.get("/api/shift/current", { preHandler: guard }, async (req) => {
+  app.get("/api/shift/current", { preHandler: readGuard }, async (req) => {
     const me = req.user.username;
     const open = shift.currentOpenShift();
     const heldBy = open?.identity ?? null;
@@ -47,7 +48,7 @@ export async function shiftRoutes(app: FastifyInstance, shift: ShiftService): Pr
   // amountMinor is signed: + load IN, − remove OUT. See wiki/concepts/shift.md.
   app.post<{ Body: CashMovementBody }>(
     "/api/cash-movement",
-    { preHandler: requireRole("admin") },
+    { preHandler: requirePermission("shift:cash") },
     async (req, reply) => {
       const { amountMinor, reason, currency } = req.body ?? ({} as CashMovementBody);
       try {

apps/server/src/routes/site.ts

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from "fastify";
 import { eq, siteConfig, type Db } from "@parking/db";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import { getOccupancy } from "../occupancy.js";
 
 // Site config (capacity) + live occupancy. Occupancy is a fold over the signed
@@ -57,8 +57,8 @@ function normText(v: unknown): string | null {
 }
 
 export async function siteRoutes(app: FastifyInstance, db: Db): Promise<void> {
-  const readGuard = requireRole("admin", "operator", "cashier", "readonly");
-  const writeGuard = requireRole("admin");
+  const readGuard = requirePermission("site:read");
+  const writeGuard = requirePermission("site:update");
 
   // Live occupancy: cars inside, capacity, free, full. Any signed-in role.
   app.get("/api/occupancy", { preHandler: readGuard }, async () => getOccupancy(db));

apps/server/src/routes/snapshots.ts

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from "fastify";
 import { desc, eq, snapshots, type Db } from "@parking/db";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 
 // Read access to captured entry/exit snapshots (the BLOB-in-DB image store, see
 // packages/db schema + wiki/concepts/lane-direction.md). Snapshots are evidence
@@ -9,7 +9,7 @@ import { requireRole } from "../auth.js";
 // never via the API.
 
 export async function snapshotRoutes(app: FastifyInstance, db: Db): Promise<void> {
-  const guard = requireRole("admin", "operator", "cashier", "readonly");
+  const guard = requirePermission("session:read");
 
   // Snapshot metadata for one session/credential identity (NOT the bytes), newest
   // first — lets the UI show "entry/exit image" links beside an event.

apps/server/src/routes/subscriptions.ts

@@ -2,7 +2,7 @@ import { randomBytes, randomUUID } from "node:crypto";
 import type { FastifyInstance } from "fastify";
 import { eq, devices, subscriptionCredentials, subscriptionPlates, subscriptions, type Db } from "@parking/db";
 import { NoPrinterAvailableError } from "@parking/devices";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 import { printSubscriptionCard } from "../booth-print.js";
 import type { CredentialCapture } from "../credential-capture.js";
 import { directionOf } from "../device-resolve.js";
@@ -71,9 +71,11 @@ export async function subscriptionRoutes(
   db: Db,
   capture: CredentialCapture,
 ): Promise<void> {
-  // Admin manages subscriptions; operator/cashier/readonly may LIST (to look one up).
-  const readGuard = requireRole("admin", "operator", "cashier", "readonly");
-  const writeGuard = requireRole("admin");
+  // Reading/looking up subscriptions vs. managing them. Revoke folds into update.
+  const readGuard = requirePermission("subscription:read");
+  const createGuard = requirePermission("subscription:create");
+  const updateGuard = requirePermission("subscription:update");
+  const deleteGuard = requirePermission("subscription:delete");
 
   // Validate the body; returns problems (empty = ok). Shared by create + update.
   function validate(b: SubscriptionBody): string[] {
@@ -223,7 +225,7 @@ export async function subscriptionRoutes(
   });
 
   // Create a subscription.
-  app.post<{ Body: SubscriptionBody }>("/api/subscriptions", { preHandler: writeGuard }, async (req, reply) => {
+  app.post<{ Body: SubscriptionBody }>("/api/subscriptions", { preHandler: createGuard }, async (req, reply) => {
     const b = req.body ?? {};
     const problems = validate(b);
     if (problems.length) return reply.code(400).send({ error: "invalid subscription", problems });
@@ -281,7 +283,7 @@ export async function subscriptionRoutes(
   // Update a subscription (replaces fields + child sets).
   app.put<{ Params: { id: string }; Body: SubscriptionBody }>(
     "/api/subscriptions/:id",
-    { preHandler: writeGuard },
+    { preHandler: updateGuard },
     async (req, reply) => {
       const existing = db.select().from(subscriptions).where(eq(subscriptions.id, req.params.id)).get();
       if (!existing) return reply.code(404).send({ error: "subscription not found" });
@@ -342,7 +344,7 @@ export async function subscriptionRoutes(
   // DELETE only to fully remove one created in error.
   app.post<{ Params: { id: string } }>(
     "/api/subscriptions/:id/revoke",
-    { preHandler: writeGuard },
+    { preHandler: updateGuard },
     async (req, reply) => {
       const r = db.update(subscriptions).set({ status: "revoked" }).where(eq(subscriptions.id, req.params.id)).run();
       if (r.changes === 0) return reply.code(404).send({ error: "subscription not found" });
@@ -354,7 +356,7 @@ export async function subscriptionRoutes(
   // are untouched — the audit trail is append-only and independent of this row.)
   app.delete<{ Params: { id: string } }>(
     "/api/subscriptions/:id",
-    { preHandler: writeGuard },
+    { preHandler: deleteGuard },
     async (req, reply) => {
       const r = db.delete(subscriptions).where(eq(subscriptions.id, req.params.id)).run();
       if (r.changes === 0) return reply.code(404).send({ error: "subscription not found" });

apps/server/src/routes/tariffs.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import type { FastifyInstance } from "fastify";
 import { desc, eq, siteConfig, tariffVersions, tariffs, type Db } from "@parking/db";
 import { isTariffV2, validateTariffStructure, type TariffStructure } from "@parking/shared";
-import { requireRole } from "../auth.js";
+import { requirePermission } from "../auth.js";
 
 /** Default site timezone for wall-clock tariff windows when none is configured. */
 const DEFAULT_TZ = "Europe/Tirane";
@@ -23,10 +23,10 @@ interface PublishBody {
 const SITE_TARIFF_NAME = "Site tariff";
 
 export async function tariffRoutes(app: FastifyInstance, db: Db): Promise<void> {
-  // Any signed-in role may READ the tariff (the pay station / operator UI needs it).
-  const readGuard = requireRole("admin", "operator", "cashier", "readonly");
-  // Only an admin may PUBLISH a new version (it changes what customers are charged).
-  const writeGuard = requireRole("admin");
+  // Reading the rate card (pay station / operator UI needs it).
+  const readGuard = requirePermission("tariff:read");
+  // Publishing a new version changes what customers are charged.
+  const writeGuard = requirePermission("tariff:update");
 
   // The single site tariff row, created on first read/publish.
   function ensureSiteTariff(): string {

apps/server/src/routes/users.ts

@@ -0,0 +1,159 @@
+import { randomUUID } from "node:crypto";
+import bcrypt from "bcrypt";
+import type { FastifyInstance } from "fastify";
+import { eq, roles, users, type Db } from "@parking/db";
+import { ADMIN_ROLE_ID } from "@parking/shared";
+import { requirePermission } from "../auth.js";
+
+// User management (admin). Users are created/edited at runtime here — the
+// install-time seed-admin.mjs only bootstraps the FIRST admin. Each user has one
+// role (RBAC); the role resolves to a permission set at request time. Passwords
+// are bcrypt-hashed (cost 12) and never returned. See @parking/shared PERMISSIONS.
+//
+// NO-LOCKOUT INVARIANT: the app refuses to delete, or move off the `admin` role,
+// the LAST user still holding `admin`. Administration can therefore never be
+// locked out of the appliance. See wiki/entities/local-jwt-auth.md.
+
+interface CreateBody {
+  username: string;
+  password: string;
+  roleId: string;
+}
+interface UpdateBody {
+  username?: string;
+  roleId?: string;
+}
+interface PasswordBody {
+  password: string;
+}
+
+const MIN_PASSWORD = 8;
+
+export async function userRoutes(app: FastifyInstance, db: Db): Promise<void> {
+  const readGuard = requirePermission("user:read");
+  const createGuard = requirePermission("user:create");
+  const updateGuard = requirePermission("user:update");
+  const deleteGuard = requirePermission("user:delete");
+
+  /** Count users currently holding the protected admin role. */
+  function adminCount(): number {
+    return db.select().from(users).where(eq(users.roleId, ADMIN_ROLE_ID)).all().length;
+  }
+
+  /** True if removing/relocating `userId` from admin would leave zero admins. */
+  function isLastAdmin(userId: string): boolean {
+    const u = db.select().from(users).where(eq(users.id, userId)).get();
+    return u?.roleId === ADMIN_ROLE_ID && adminCount() <= 1;
+  }
+
+  /** A user row safe to return — never the password hash. */
+  function publicUser(u: { id: string; username: string; roleId: string; language: string; createdAt: string }) {
+    return { id: u.id, username: u.username, roleId: u.roleId, language: u.language, createdAt: u.createdAt };
+  }
+
+  // List all users (no password hashes) + their role names for display.
+  app.get("/api/users", { preHandler: readGuard }, async () => {
+    const rows = db.select().from(users).all();
+    const roleRows = db.select().from(roles).all();
+    const roleName = new Map(roleRows.map((r) => [r.id, r.name]));
+    return {
+      users: rows.map((u) => ({ ...publicUser(u), roleName: roleName.get(u.roleId) ?? u.roleId })),
+    };
+  });
+
+  // Create a user. Username unique; password >= 8 chars; roleId must exist.
+  app.post<{ Body: CreateBody }>("/api/users", { preHandler: createGuard }, async (req, reply) => {
+    const username = (req.body?.username ?? "").trim();
+    const password = req.body?.password ?? "";
+    const roleId = (req.body?.roleId ?? "").trim();
+    if (!username || !roleId) {
+      return reply.code(400).send({ error: "username and roleId required" });
+    }
+    if (password.length < MIN_PASSWORD) {
+      return reply.code(400).send({ error: `password must be at least ${MIN_PASSWORD} characters` });
+    }
+    if (!db.select().from(roles).where(eq(roles.id, roleId)).get()) {
+      return reply.code(400).send({ error: "unknown roleId" });
+    }
+    if (db.select().from(users).where(eq(users.username, username)).get()) {
+      return reply.code(409).send({ error: "username already exists" });
+    }
+    const id = randomUUID();
+    const passwordHash = await bcrypt.hash(password, 12);
+    db.insert(users).values({ id, username, passwordHash, roleId }).run();
+    const created = db.select().from(users).where(eq(users.id, id)).get()!;
+    return reply.code(201).send(publicUser(created));
+  });
+
+  // Update a user's username and/or role. Guarded against orphaning admin.
+  app.put<{ Params: { id: string }; Body: UpdateBody }>(
+    "/api/users/:id",
+    { preHandler: updateGuard },
+    async (req, reply) => {
+      const id = req.params.id;
+      const existing = db.select().from(users).where(eq(users.id, id)).get();
+      if (!existing) return reply.code(404).send({ error: "user not found" });
+
+      const next: { username?: string; roleId?: string } = {};
+      if (req.body?.username != null) {
+        const username = req.body.username.trim();
+        if (!username) return reply.code(400).send({ error: "username cannot be empty" });
+        const clash = db.select().from(users).where(eq(users.username, username)).get();
+        if (clash && clash.id !== id) return reply.code(409).send({ error: "username already exists" });
+        next.username = username;
+      }
+      if (req.body?.roleId != null) {
+        const roleId = req.body.roleId.trim();
+        if (!db.select().from(roles).where(eq(roles.id, roleId)).get()) {
+          return reply.code(400).send({ error: "unknown roleId" });
+        }
+        // No-lockout: don't move the last admin off the admin role.
+        if (roleId !== ADMIN_ROLE_ID && isLastAdmin(id)) {
+          return reply.code(409).send({ error: "cannot change the role of the last admin" });
+        }
+        next.roleId = roleId;
+      }
+      if (Object.keys(next).length === 0) {
+        return reply.code(400).send({ error: "nothing to update" });
+      }
+      db.update(users).set(next).where(eq(users.id, id)).run();
+      return publicUser(db.select().from(users).where(eq(users.id, id)).get()!);
+    },
+  );
+
+  // Reset a user's password (admin sets a new one; >= 8 chars).
+  app.put<{ Params: { id: string }; Body: PasswordBody }>(
+    "/api/users/:id/password",
+    { preHandler: updateGuard },
+    async (req, reply) => {
+      const id = req.params.id;
+      if (!db.select().from(users).where(eq(users.id, id)).get()) {
+        return reply.code(404).send({ error: "user not found" });
+      }
+      const password = req.body?.password ?? "";
+      if (password.length < MIN_PASSWORD) {
+        return reply.code(400).send({ error: `password must be at least ${MIN_PASSWORD} characters` });
+      }
+      const passwordHash = await bcrypt.hash(password, 12);
+      db.update(users).set({ passwordHash }).where(eq(users.id, id)).run();
+      return { ok: true };
+    },
+  );
+
+  // Delete a user. Refused if it's the last admin (no-lockout).
+  app.delete<{ Params: { id: string } }>(
+    "/api/users/:id",
+    { preHandler: deleteGuard },
+    async (req, reply) => {
+      const id = req.params.id;
+      if (!db.select().from(users).where(eq(users.id, id)).get()) {
+        return reply.code(404).send({ error: "user not found" });
+      }
+      if (isLastAdmin(id)) {
+        return reply.code(409).send({ error: "cannot delete the last admin" });
+      }
+      db.delete(users).where(eq(users.id, id)).run();
+      return { ok: true };
+    },
+  );
+}

apps/server/src/routes/ws.ts

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from "fastify";
 import type { Db } from "@parking/db";
-import type { Role } from "@parking/shared";
+import { roleHasPermissions } from "../auth.js";
 import { deviceEvents } from "../device-events.js";
 import type { DeviceMonitor } from "../device-monitor.js";
 import { getOccupancy } from "../occupancy.js";
@@ -23,9 +23,9 @@ import { getOccupancy } from "../occupancy.js";
 // allowed booth UI origin). Non-browser clients (no Origin) are rejected too.
 // See auth.ts, event-log.ts (emitLedger), capacity-occupancy.md.
 
-/** Roles allowed to watch the live feed (everyone signed in; readonly included —
- *  it's a read-only stream). */
-const WATCH_ROLES: Role[] = ["admin", "operator", "cashier", "readonly"];
+/** Permission required to watch the live feed (a read-only stream of ledger +
+ *  device status). Any role granted `report:read` may watch. */
+const WATCH_PERMISSION = "report:read" as const;
 
 /**
  * Is the handshake's Origin trusted? Same-origin (Origin host === Host header) is
@@ -68,7 +68,7 @@ export async function wsRoutes(app: FastifyInstance, db: Db, deviceMonitor: Devi
           throw Object.assign(new Error("forbidden origin"), { statusCode: 403 });
         }
         await req.jwtVerify();
-        if (!req.user || !WATCH_ROLES.includes(req.user.role)) {
+        if (!req.user || !roleHasPermissions(req.user.roleId, [WATCH_PERMISSION])) {
           throw Object.assign(new Error("forbidden"), { statusCode: 403 });
         }
       },

apps/server/src/server.ts

@@ -4,7 +4,7 @@ import websocket from "@fastify/websocket";
 import Fastify, { type FastifyInstance } from "fastify";
 import { randomUUID } from "node:crypto";
 import { createDb, deviceEvents as deviceEventsTable, type Db } from "@parking/db";
-import { TOKEN_COOKIE, requireJwtSecret } from "./auth.js";
+import { TOKEN_COOKIE, requireJwtSecret, initAuth } from "./auth.js";
 import { deviceEvents } from "./device-events.js";
 import { EntryFlow } from "./entry-flow.js";
 import { EventLog } from "./event-log.js";
@@ -18,6 +18,8 @@ import { PrinterMonitor } from "./printer-monitor.js";
 import { DeviceMonitor } from "./device-monitor.js";
 import { buildSigner, buildVerifier } from "./signer.js";
 import { authRoutes } from "./routes/auth.js";
+import { userRoutes } from "./routes/users.js";
+import { roleRoutes } from "./routes/roles.js";
 import { deviceRoutes } from "./routes/devices.js";
 import { eventRoutes } from "./routes/events.js";
 import { payRoutes } from "./routes/pay.js";
@@ -47,6 +49,10 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
 
   const db = opts.db ?? createDb();
 
+  // Wire the RBAC permission resolver to this DB (route guards resolve a user's
+  // role → permission set through it). See auth.ts.
+  initAuth(db);
+
   await app.register(cookie);
 
   // WebSocket support for the live booth feed (/api/ws). Registered before the
@@ -70,6 +76,11 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
   // Local username/password login → JWT in an HttpOnly cookie + CSRF cookie.
   await authRoutes(app, db);
 
+  // RBAC administration: compose roles (role:*) + manage users (user:*). The
+  // built-in admin role is protected; the last admin can't be removed. See auth.ts.
+  await userRoutes(app, db);
+  await roleRoutes(app, db);
+
   // Device-agnostic setup: the admin adds controllers (with their relays + entry
   // button) and binds readers/cameras to a controller relay at first-run. There is
   // no lane — a parking lot is one pool with a flexible set of entry/exit points.