---
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.
  **The token's `roleId` is only a hint (2026-09-05):** after every `jwtVerify` the guard replaces it
  with the user's CURRENT role from the DB (`refreshRole()`; cached per user, cleared by the same
  `bumpPermsCache()`, which user update/delete now call), so REASSIGNING a user's role — or deleting
  the user (→ 401 on their next request) — applies immediately too. Found when a user moved to a new
  wash role kept the old role's rights until logout.
  **Role edits are signed (2026-09-06):** every create/update/delete of a role appends a
  `config_change` (`role.<id>`, before/after shape, operator) to the ledger, and a role remembers
  the manifest JOBS it was composed from (`role_jobs`) so a job that grows in a later release can
  be re-applied with one click rather than expanding silently — [[venue-modules]] §Permissions
  matrix.
- **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).
- The grid is **extensible** — adding a feature adds its `resource:action` rows. Recent additions:
  **`log:read`** (gates the diagnostic-log viewer, `GET /api/logs`; see [[app-logs]]); **`report:read`**
  (the admin Reports dashboard; see [[reporting-analytics]]); and **`recyclebin:read/update/delete`**
  (view / restore / purge soft-deleted master data; see [[soft-delete]]). Admin holds them all; each is
  grantable to a scoped role.
- **Soft-deleted users can't authenticate.** The login route rejects a user whose `deleted_at` is set
  (with the same generic "invalid credentials" so a deleted account isn't enumerable). The no-lockout
  "last admin" check counts only LIVE admins, so soft-deleting can't strand administration. See
  [[soft-delete]].
- **No privilege escalation through the RBAC system itself.** `role:create`/`role:update` and
  `user:create`/`user:update` are themselves grantable, so a non-admin could otherwise self-escalate.
  Guards (`routes/roles.ts`, `routes/users.ts`): a caller may only put permissions on a role that
  they *already hold*, and may only assign/modify users whose role is a SUBSET of the caller's own
  (so no minting a privileged role, handing out the admin role, or resetting/deleting a more-
  privileged account). An admin holds the full set, so it is unrestricted — the intended behaviour.

## 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**, and **`Secure` by default**
  (fail-safe — a forgotten env can only make cookies more restrictive, never drop the flag).
  `Secure` is dropped ONLY for a deliberate opt-out: `COOKIE_SECURE=0` (the plain-HTTP LAN
  appliance — see [[disk-os-hardening]] deploy checklist) or `NODE_ENV=development`. (Was keyed
  off `NODE_ENV=production`, which silently leaked cookies on an appliance that forgot to set it
  — corrected 2026-06-21.) 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

**Self-service profile (added 2026-06-24).** Alongside the admin user-manager (`routes/users.ts`,
gated on `user:*`), any signed-in user has two **self-only** routes (no permission needed — they
act solely on `req.user.sub`):
- `PUT /api/auth/profile` — edit own `fullName` / `email` (`""` clears → null). Returns the
  refreshed session (so the SPA header updates). **Cannot** touch `username` or `role` — those stay
  admin-only, so this is not a privilege-escalation surface.
- `PUT /api/auth/password` — change own password, but **must prove the current one** first
  (`bcrypt.compare`) → defends a walked-up, already-logged-in booth from a silent re-key. New
  password ≥ 8 chars. Distinct from the admin reset (`PUT /api/users/:id/password`), which needs no
  current password but DOES need `user:update` + the no-escalation guard.
Both are still CSRF-guarded (mutations). The SPA surfaces them at `/profile` (`apps/web/src/Profile.tsx`),
reachable from the header username chip. Covered by `apps/server/src/routes/profile.test.ts`.

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.