pediatric-ai-scribe-v3/docs/authentication.md

# Authentication & security

## Sign-in is SSO-only

The front door is `sso.pedshub.com` (Authentik, `/home/danvics/docker/authentik-pedshub`).
`oidc.enabled` and `oidc.disable_local_auth` are both `true`, so `/api/auth/login`,
`/register`, `/forgot-password`, `/reset-password`, `/change-password` and the 2FA
routes answer 403 (`requireLocalAuth`). The OIDC client is `src/routes/oidc.js`:
signed state cookie, PKCE, nonce, `email_verified` required before an existing
local account is linked, `sub` mismatch refused, session row written before the
cookie is set. New accounts are created at the SSO from an invitation link
(`invite.py` there); an SSO account whose email matches a local one signs into
that account. Roles follow the SSO's groups on every sign-in when
`oidc.admin_groups` / `oidc.moderator_groups` name them (production:
`pedshub-admins`, `pedshub-moderators`; anyone in neither is a user); the last
admin is never demoted by a claim. The sections below describe the local
machinery that remains behind the switch.

## Signed in at PedsHub means signed in here

A visitor with no session here is not shown the sign-in page straight away.
The page first asks the provider silently (`/api/auth/oidc?silent=1`,
which adds `prompt=none`): someone already signed in at sso.pedshub.com — from
the quiz app, say, following a deck link — arrives signed in without a click,
the way a Kerberos ticket carries across services. Someone not signed in there
gets the provider's refusal, which the callback turns into the ordinary
sign-in page (`?sso=none`, no message). The attempt happens once per browser
session, never after an explicit sign-out and never inside the mobile shell,
and the URL fragment (a share link, a tab) is kept across the round trip.

## Signing out signs you out of PedsHub

Sign out ends this app's session and then the PedsHub (Authentik) session:
the server answers the sign-out with the provider's end-session address
(`end_session_endpoint` from discovery, with `post_logout_redirect_uri` back
to this app and the client id), and the browser goes there and returns. So
"sign out" means signed out — on a shared ward computer the next person is not
one click from the account — and because the two PedsHub apps share the one
provider session, signing out of either signs you out of both. The app's
landing page must be in the provider's redirect list for the return to work;
without it Authentik shows its own "you've logged out" page, which still ends
the session. The mobile shell only signs out locally.

## Lockdown: the admin panel as view-only

`ADMIN_LOCKDOWN=true` in the environment (never a setting, so no admin can
switch it off) makes every setting that changes how the service behaves
read-only: prompts, model policy, the Clinical Assistant's models and limits,
speech and transcription, SMTP and mail templates, the SSO provider, and any
key added later that nobody has explicitly listed as day-to-day. The server
refuses the write with 403 (`src/utils/adminLockdown.js`; the gate at the top
of `src/routes/adminConfig.js`, and `PUT /api/auth/oidc/config` checks it
itself). The panel greys the fields and says why, but the refusal is the
control. Still editable under lockdown: the announcement banner,
`registration_enabled`, `feature.*` switches, `site.*`, and the test buttons.
Lifting it takes a host change and a restart.

## Password hashing

- Primary: **argon2id**, memory cost 19 MiB, time cost 2, parallelism 1
  (OWASP 2023 recommended profile).
- Fallback: **bcryptjs** (12 rounds) for legacy rows.
- Transparent migration: on successful login against a bcrypt hash, the
  password is rehashed as argon2id and the row updated. Users migrate without
  any action.
- The `argon2` package is loaded optionally — if not installed, registration
  and password changes fall back to bcrypt without breaking.

## Token transport

Hybrid, chosen at request time by `src/utils/platform.js` based on User-Agent
and optional `X-Client` header:

| Client | Transport | Storage | JWT lifetime |
|---|---|---|---|
| Web browser | `ped_auth` httpOnly + `sameSite=lax` cookie | — (no client storage) | 30 d (sliding 24 h idle enforced server-side) |
| Capacitor app | `Authorization: Bearer <jwt>` | iOS Keychain / Android EncryptedSharedPreferences | 365 d (no idle check) |

`authMiddleware` reads Bearer first, falls back to cookie. An empty Bearer
string falls through to cookie parsing — fixes clients that always emit the
header.

## Session table

`user_sessions` is the authoritative source. Each row holds `token_hash`
(SHA-256 of the JWT), `user_id`, `ip_address`, `device_label`, `last_activity`.

Middleware on every authenticated request:

1. Verify JWT signature and expiry.
2. Look up `token_hash` in `user_sessions`. If missing and the user has any
   other sessions → 401 "Session revoked". No sessions at all → fail open
   (pre-migration users).
3. Compute idle (`NOW() - last_activity`).
   - Web (`!isMobileClient`): if idle > 24 h → delete the session row, clear
     cookie, return 401 with `idleTimeout: true`.
   - Mobile: skip idle check.
4. On POST / PUT / DELETE / PATCH only, if idle > 10 min (throttle), update
   `last_activity = NOW()` and re-set the cookie with a fresh 30-day maxAge
   (cookie slides with activity). GET / HEAD do NOT extend the session —
   prevents polling from defeating the idle policy.

Idle-timeout kicks write an `audit_log` entry with
`action='session_idle_timeout'` and the minute count, plus a `console.warn`
for Loki.

## Two-factor authentication

TOTP via `speakeasy`, 30-second step, verification window ±1 step.

### Backup codes

- Generated automatically on first 2FA enable (10 codes, 10 characters,
  `XXXXX-XXXXX` format, excluded-characters alphabet: no `0/O/1/I`).
- Stored as bcrypt hashes in `users.totp_backup_codes` (JSON array).
- Consumed atomically on login via `SELECT … FOR UPDATE` transaction — race
  between parallel attempts serializes correctly, a code can only succeed once.
- `POST /api/auth/2fa/backup-codes` regenerates the full set (requires current
  password). `GET /api/auth/2fa/backup-codes/count` returns remaining count.
- Consumed codes are also logged in `audit_log` (`2fa_backup_code_used`).
- Cleared when 2FA is disabled.

## OIDC (Authorization Code + PKCE)

- Implemented with `openid-client`.
- State + PKCE verifier + nonce are bundled into an HMAC-signed token
  (signed with `JWT_SECRET`) — stateless, survives restarts and scales
  horizontally. 5-minute TTL.
- SSRF guard: issuer URL must use `https://` and not resolve to any private /
  loopback / link-local IP. Blocks attacks like issuer set to
  `http://169.254.169.254/` (AWS metadata).
- First-time link: requires `email_verified: true` claim from the IdP.
  Missing or false → 401 with `error=email_unverified`. Prevents an
  unverified-email SSO account from taking over an existing local account.
- Already-linked users with a DIFFERENT `oidc_sub` are refused
  (`error=sub_mismatch`).
- Auto-create on first SSO: new user row, `email_verified=true`, password
  column holds a random 32-byte hex string (not a hash). `canLocalAuth=false`
  hides password/2FA/sessions UI for these users. Server-side endpoints
  (`/change-password`, `/setup-2fa`) also reject with an SSO-aware message.

Providers tested: Authentik, Azure AD, Okta, Keycloak, Google, PocketID.

## Logout and cross-tab sync

- `POST /api/auth/logout` deletes the current session row and clears the
  cookie.
- Frontend broadcasts `{type:'logout'}` on `BroadcastChannel('pedscribe-auth')`;
  sibling tabs drop UI and reload.
- `authFetch.js` installs a global `fetch` interceptor; any 401 on an
  authenticated `/api/*` request triggers the same logout path.
- Service-worker caches are cleared on every logout (`caches.keys()` →
  `caches.delete`).

## Rate limits

| Endpoint | Limit |
|---|---|
| `/api/*` general | 200 req / min / IP |
| `/api/auth/login` | 10 / 15 min |
| `/api/auth/register` | 5 / hour |
| `/api/auth/forgot-password` | 5 / hour |
| `/api/auth/resend-verification` | 3 / 15 min |
| `/api/auth/change-password`, `/setup-2fa`, `/verify-2fa`, `/disable-2fa` | 20 / 15 min |

Limits are per-IP (`express-rate-limit`). A clinic behind a single NAT shares
the bucket; increase or switch to per-user keying if that becomes a problem.

## Login enumeration resistance

`/api/auth/login` returns `"Invalid credentials"` for:
- unknown email (runs a bcrypt compare against a fixed dummy hash to equalize timing)
- wrong password
- disabled account

`"Email not verified"` is still returned for unverified accounts — deemed a
necessary UX tradeoff over perfect indistinguishability.

## Sign-in codes and invitations

Both live at the SSO (`sso.pedshub.com`, Authentik) rather than in this app:
sign-in is email → code, and new accounts come from an invitation link minted
with `authentik-pedshub/invite.py`. The app's own sign-in codes and
registration invites were removed once sign-in became SSO-only.

## Turnstile (Cloudflare bot protection)

Applied to `/api/auth/register` and `/api/auth/forgot-password` when
`TURNSTILE_SECRET_KEY` is set. No-op when unset (dev mode).

`/api/auth/login` is deliberately **not** gated: the widget could not
reliably complete a challenge inside the Capacitor WebView, which locked
mobile users out of the app. Login is covered instead by its per-IP rate
limit (10 / 15 min), the constant-time credential check, and TOTP 2FA.

The two remaining widgets are rendered explicitly (`api.js?render=explicit`)
the first time their form becomes visible — Turnstile does not reliably
complete a challenge inside a `display:none` container, and both forms start
hidden. Tokens are captured from the render callback, not read back out of
the injected `[name="cf-turnstile-response"]` input.

Note that the site key is currently **hardcoded** in `public/index.html`.
`TURNSTILE_SITE_KEY` exists in OpenBao but is not read by any code.

## Encryption at rest

`src/utils/crypto.js` provides AES-256-GCM helpers. Key loaded from
`DATA_ENCRYPTION_KEY` env var (64 hex chars = 32 bytes; any other string is
SHA-256-derived with a warning). In production mode the server refuses to
start without it.

| Data | Encryption |
|---|---|
| Nextcloud access tokens (`users.nextcloud_token`) | AES-256-GCM via `encryptString`; legacy plaintext rows are detected and re-encrypted on next use |
| Audio backups (`audio_backups.audio_data`) | Gzipped, then AES-256-GCM with a `0x01` version byte prefix; legacy rows (no prefix) pass through unchanged |
| PHI in audit details | Redacted via `src/utils/redact.js` (SSN, phone, email, DoB regex patterns; 500-char cap; note-body heuristic truncation) before insert |

## HTTP security headers

Helmet defaults plus:

- `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`
- Content-Security-Policy:
  - `script-src 'self' 'wasm-unsafe-eval' 'unsafe-eval' cdn.jsdelivr.net cdnjs.cloudflare.com challenges.cloudflare.com`
    (do not add `unsafe-eval` unless a reviewed dependency requires it)
  - `script-src-attr 'none'` (blocks inline event handlers)
  - `frame-src 'self' challenges.cloudflare.com`
  - `object-src 'none'`
- `X-Content-Type-Options: nosniff`
- Response bodies on 5xx use generic `'Request failed'`; full error stays
  server-side in `logger.error` / Loki.

## File uploads

`src/routes/documents.js` accepts document uploads after:
1. Extension / MIME check.
2. Magic-byte sniff via `src/utils/fileType.js` — refuses mismatches (e.g., a
   `.jpg` with a PHP payload).

## CORS

- Production (`NODE_ENV=production` or `APP_URL` set): refuses to start if
  neither `APP_URL` nor `CORS_ORIGINS` is configured.
- Origin whitelist = union of `APP_URL` and comma-separated `CORS_ORIGINS`.
- Requests with no Origin header always pass (mobile, curl, server-to-server).
- `credentials: true` so the cookie travels on cross-origin web requests
  from permitted origins.

## Roles

| Role | Access |
|---|---|
| `admin` | Everything. First registered user auto-promoted. |
| `moderator` | Standard user features. The role is still assignable but no longer grants anything of its own — it gated the Learning Hub CMS, which has been removed. |
| `user` | Clinical features, no admin routes. |

## Audit logging

Every auth-adjacent event is written to `audit_log` via a batched writer
(`src/utils/auditQueue.js`) — 1-second flush interval or 50-entry batch.
Drained on SIGTERM before pool close. Sent to Loki in parallel (fire-and-forget).

Common `action` values: `register`, `login`, `login_failed`, `login_blocked`,
`login_oidc`, `logout`, `email_verified`, `password_changed`,
`password_reset`, `2fa_enabled`, `2fa_backup_code_used`,
`2fa_backup_codes_regenerated`, `oidc_linked`, `session_idle_timeout`.

## Maintenance

`scripts/maintenance.js`:
- `npm run maint:check` — reports collation drift, row counts, index list
- `npm run maint:reindex` — `REINDEX DATABASE` + `ALTER DATABASE … REFRESH COLLATION VERSION` + `ANALYZE`

Run after any Postgres image upgrade. The startup drift check runs this
automatically when `pg_database.datcollversion` diverges from the library's
actual version.