julian
d0841c8601
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
62 lines
3.9 KiB
Markdown
62 lines
3.9 KiB
Markdown
---
|
|
type: entity
|
|
tags: [parking, stack, auth, offline-first]
|
|
sources: [parking-system-architecture]
|
|
updated: 2026-06-15
|
|
---
|
|
|
|
# Local JWT Auth
|
|
|
|
Authentication and authorization, kept **fully local** — a direct consequence of
|
|
[[offline-first]] (an air-gapped park cannot reach an external identity provider; see
|
|
[[logto-zitadel-oidc]] for the rejected alternative). (See [[parking-system-architecture]] §2.)
|
|
|
|
- `@fastify/jwt` signs tokens with a **local secret** (symmetric HMAC). The server **refuses to
|
|
start** without a strong `JWT_SECRET` (≥32 chars, no placeholder) — there is deliberately no
|
|
insecure default.
|
|
- **Session lifetime: valid until explicit logout — no time expiry** (decision 2026-06-15, built).
|
|
Booth reality breaks any fixed clock: relief arrives late, fails to show, or one operator is
|
|
forced to work two shifts in a row — a token that expired mid-duty would strand an active
|
|
operator. So the login persists until logout; a **[[shift]] is a separate, explicit boundary**,
|
|
not tied to token lifetime. (Superseded the earlier "8h expiry, bound to a shift" assumption.)
|
|
The JWT carries no `exp`; the cookie has a long fixed `maxAge` (30 days) so a browser restart
|
|
doesn't log out an active operator, and `logout` clears it.
|
|
- A `users` table in [[sqlite]] holds **bcrypt** password hashes plus a **`role_id`** FK. The
|
|
first admin is seeded via `pnpm --filter @parking/server seed-admin` (no bootstrap endpoint);
|
|
every other user is created in-app (admin → Users screen).
|
|
- Authorization = **dynamic RBAC** (built 2026-06-18, replacing the old hardcoded
|
|
`admin/operator/cashier/readonly` enum — those are now ordinary seed roles). Roles are **data**:
|
|
`roles` + `role_permissions` tables, composed by an admin from a **code-defined permission grid**
|
|
(`@parking/shared` `PERMISSIONS` = `resource:action`, e.g. `tariff:update`, `payment:create`,
|
|
`event:void`). A `preHandler` `requirePermission(...)` per route checks a PERMISSION, not a role
|
|
name. The JWT carries `roleId` (not the permission list); the guard resolves the role's permission
|
|
set per-request from an **in-memory cache** (`bumpPermsCache()` on any role write), so editing a
|
|
role applies immediately — no re-login, no token bloat. No Casbin/engine needed at this scale.
|
|
- **Protected built-in `admin` role** (`id='admin'`, `builtin=1`): non-editable, non-deletable, and
|
|
always resolves to the FULL permission set in code. The app refuses to delete or downgrade the
|
|
**last user holding admin** — administration can never be locked out of the appliance.
|
|
- `event:void` is a permission, NOT a ledger delete: the append-only signed chain is untouched; the
|
|
permission only gates who may APPEND a void event (there is no void API route yet — forward seam).
|
|
|
|
## Cookie session (browser auth)
|
|
|
|
The SPA never sees the JWT. Login (`POST /api/auth/login`) verifies bcrypt and sets two cookies:
|
|
|
|
- **`parking_token`** — the JWT, **HttpOnly + SameSite=Strict** (+ `Secure` when
|
|
`NODE_ENV=production`). JS can't read it; `@fastify/jwt` reads it from the cookie, not the
|
|
`Authorization` header.
|
|
- **`parking_csrf`** — a random token, **readable** by JS. The JWT also carries a matching `csrf`
|
|
claim. On every mutation the SPA echoes the cookie in the **`X-CSRF-Token`** header; the guard
|
|
requires header == cookie == the signed claim (**double-submit CSRF**). Safe reads are exempt.
|
|
|
|
Routes: `login`, `logout` (clears cookies), `me` (bootstraps SPA session on load). The dev
|
|
[[react-vite-spa|Vite]] proxy and the prod **nginx** reverse proxy keep the SPA and API
|
|
**same-origin**, so the cookies work without CORS. (This replaced an earlier dev-only
|
|
`SETUP_AUTH_BYPASS` shim, now removed.)
|
|
|
|
> **Open decision:** moving from the symmetric secret to an **asymmetric key (RS256/EdDSA)** so
|
|
> verifying hosts hold only a public key — [[open-questions]] #7. Relevant before any
|
|
> multi-host/multi-lane deployment.
|
|
|
|
Part of the [[technology-stack]]. License: MIT.
|