julian
66c1291578
Documents the deploy-time requirement that the cookie fail-safe fix (7629d5d)
introduced: the LAN appliance serves the SPA same-origin over plain http, where a
Secure cookie is never sent — so it MUST set COOKIE_SECURE=0 or operators can't log
in. A TLS deploy leaves it unset.
- wiki/concepts/disk-os-hardening.md: new "Deploy-time server configuration (runbook)"
section listing the security-load-bearing env (JWT_SECRET, EVENT_SIGNING_KEY,
COOKIE_SECURE=0) with the why + the network-scoped justification.
- wiki/entities/local-jwt-auth.md: corrected the stale "Secure when NODE_ENV=production"
cookie line to the Secure-by-default / opt-out model.
- wiki/log.md: entry.
Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
75 lines
5.1 KiB
Markdown
75 lines
5.1 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).
|
|
- The grid is **extensible** — adding a feature adds its `resource:action` rows. Latest: **`log:read`**
|
|
(a new `log` resource) gates the diagnostic-log viewer (`GET /api/logs`); admin holds it, and it's
|
|
grantable to a diagnostic role. See [[app-logs]].
|
|
- **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
|
|
[[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.
|