visitor-signin/.claude-context/sessions/2026-09-23-visitor-kiosk-build.md

# Visitor sign-in kiosk: build, HTTPS, and server-side label printing

**Date:** 2026-09-23
**Project:** visitor-signin
**Status:** ongoing
**Tags:** node, express, sqlite, docker, kiosk, tls, jamf, brother-ql, ql-820nwb, label-printing, google-sheets, multi-site, 2fa, dithering

## Context
Built an internally hosted visitor sign-in/out kiosk for school campuses from scratch: guest and
recurring-visitor sign in with photo capture and WWCC/VIT recording, an admin console, and a
Google Sheet mirror for evacuation use. The session then iterated through multi-site support,
per-admin accounts with 2FA, self-signed HTTPS for iPad kiosks deployed via Jamf Pro, and
moving badge printing off the iPad onto the server, driving a Brother QL-820NWB directly. It
closed on getting two-colour (DK-22251) printing accepted by the printer and on photo halftoning.

## Key Decisions
- **Node/Express + SQLite + vanilla JS in one container, no front-end build step.** Simple to
  run on a single docker host; no database server to manage. Rejected a React/SPA build as
  unnecessary weight for a kiosk.
- **Recurring-visitor PINs are encrypted (AES-256-GCM keyed from `APP_SECRET`), not hashed.**
  A 4-digit PIN has 10,000 values, so hashing gives no protection against someone holding the
  DB file; encryption lets admins reprint a lost card. Real protection is the lockout (5 wrong
  PINs = 15 min). Consequence: changing `APP_SECRET` makes every PIN unreadable.
- **Phone, email and PIN must each be unique.** PINs use a keyed HMAC column (`pin_lookup`)
  because the ciphertext has a random IV and cannot be compared. Enforced in app code *and* by
  partial unique indexes; migration backfills `pin_lookup` and names existing duplicates rather
  than failing startup.
- **A stored recurring-visitor photo is copied onto each visit, not referenced.** Keeps the visit
  log a true snapshot, and stops photo-retention purging from deleting a live profile photo.
- **"Remove" on a recurring visitor is a hard delete that keeps visit history.** Visits
  denormalise name/contact/host, so history survives; identifiers are freed for reuse. "Active"
  untick is offered as the reversible alternative.
- **TLS: a 10-year local CA plus a 398-day server certificate, auto-renewed.** Apple/Chrome reject
  server certs over ~398 days, so a single self-signed cert would need reinstalling on every
  tablet yearly. The server cert renews inside 30 days and hot-swaps via `setSecureContext`;
  the CA never changes, so devices are configured once. Rejected: single long-lived self-signed
  cert; reverse proxy (still supported as an option).
- **Cert change detection tracks configured names via a sidecar file, not the full SAN list.**
  The container's docker bridge IP is included automatically and changes on restart; comparing
  full SANs would reissue the cert on every boot.
- **Plain-HTTP helper port serves the CA (`/ca.crt`, `/ca.cer`, `/ca.zip`) and redirects the
  rest to HTTPS.** Solves the chicken-and-egg of downloading a cert you don't yet trust.
- **CA offered as DER `.cer` and as a zip bundle.** Jamf's certificate payload rejects PEM `.crt`
  on extension; browsers block bare `.crt/.cer` downloads. The zip (all encodings + README with
  fingerprint and install steps) is written by an in-repo ZIP writer rather than a dependency,
  validated against Python's `zipfile`.
- **Google Sheet holds only who is currently on site.** One tab, rewritten in full on every sign
  in/out (never patched, so it can't hold stale names). The earlier append-only history tab was
  dropped at the user's request; full history stays in the app (Visit log + CSV). Keeps visitor
  contact/movement history off the cloud.
- **Server-side printing: render the badge to a bitmap with `@napi-rs/canvas`, send via
  `brother_ql` over TCP 9100.** Takes the iPad out of the print path (it was mangling label
  format). Chose `brother_ql` over hand-rolling Brother's raster protocol for hardware
  reliability. Sign-in awaits the print briefly; on failure the kiosk falls back to browser print.
- **Roll type is an explicit per-site setting (`printer_label`), decoupled from the red styling
  option.** Originally the media id was inferred from the "print in red" checkbox, which caused
  unexplainable "Wrong Roll Type" refusals. See *Technical Details* for the `--red` finding.
- **Photo halftoning happens in the renderer (Floyd–Steinberg), not in the printer driver.** The
  printer is 1-bit; `brother_ql`'s default threshold turned faces into solid blocks. Doing it
  server-side makes the preview and the printed label the same image.
- **Admin login is a separate document at `/admin/login`.** Replaced an embedded panel that
  "unfolded" inside the console. Routes are declared before `express.static` so the redirect
  guard can't be bypassed.
- **Branding: four settable colours; everything else derived.** Text on coloured backgrounds is
  chosen by WCAG luminance; the muted label colour is mixed toward the background only as far as
  it can go while staying ≥4.5:1. A fixed grey was the cause of "text blending in". SVG banners
  rejected (can carry script, served to every kiosk).
- **Kiosk has no admin link and no author credit.** A kiosk is a public terminal. Credit line
  remains on staff-facing pages only.
- **Company is recorded, not printed.** Adding it to the badge overflowed 62×90 mm labels.

## Technical Details
**Ports / env:** container `3000` (HTTPS app) and `3001` (HTTP helper); host `HOST_PORT=8443`,
`HOST_HTTP_PORT=8080`. Key env: `HTTPS_ENABLED`, `HTTPS_HOSTNAMES` (comma list of names/IPs
the kiosks use), `HTTPS_PUBLIC_PORT` (must equal `HOST_PORT`), `APP_SECRET`,
`ADMIN_BOOTSTRAP_EMAIL`/`ADMIN_BOOTSTRAP_PASSWORD` (first account only; `ADMIN_PASSWORD` is
dead), `ADMIN_REQUIRE_2FA`, `ADMIN_ALLOWED_DOMAINS`, `EXPIRY_WARNING_DAYS`,
`SHEETS_ONSITE_TAB`, `PRINT_TIMEOUT_MS`, `PRINT_SIGNIN_WAIT_MS`.

**Operational gotchas (all hit during this session):**
- After editing `.env`, use `docker compose up -d`, **not** `docker compose restart` — restart
  keeps the old environment. Symptom: cert covers only `localhost`, `visitors.local` and a
  `172.x` bridge IP. Server now warns at boot when `HTTPS_HOSTNAMES` is at its default.
- Host `.env` predates many settings; compare with `diff <(grep -oE '^[A-Z_]+=' .env | tr -d '=' | sort -u) <(grep -oE '^[A-Z_]+=' .env.example | tr -d '=' | sort -u)`.
- Bind-mounted `./data` is created root-owned; `docker-entrypoint.sh` starts as root, chowns
  `/data` only if ownership is wrong, then drops to `node` via `setpriv` (`util-linux` installed
  explicitly).
- `pull_policy: build` in compose — the image is never pulled from a registry.
- `.gitattributes` forces LF (CRLF only for `.ps1`/`.bat`) so shell scripts survive Windows.
- `data/`, `.env`, `secrets/` are gitignored and survive `git reset --hard` (verified).

**Deploy flow (host):** branch is **`deploy`**.
`git fetch origin && git reset --hard origin/deploy && docker compose up -d --build`
then `docker compose exec visitor-signin npm run version` (reports which features are present).

**Printer — QL-820NWB findings (hard-won):**
- Head width on a 62 mm roll is **696 dots** at 300 dpi; bitmap is always 696 wide. 90 mm = 1063
  raster lines. Rotation is applied to the finished image, not the layout.
- **DK-22251 (black/red) requires `brother_ql ... --label 62red --red` — even for an all-black
  badge.** Proven on the wire: `--label 62red` alone is byte-identical to `--label 62` (1063
  mono `g` lines, `ESC i K` mode byte `0x08`); adding `--red` produces 2126 two-plane `w` lines
  and mode byte `0x09`. Printer message when missing: *"Black/Red on White paper is installed
  now. Change it to Monochrome media."* Mismatch fails in both directions.
- `brother_ql`'s network backend **only writes; it never reads**, so it reports success even when
  the printer refuses the job.
- The QL-820NWB **does not answer status requests on port 9100** (write-only print server).
  **Brother Status Monitor on a connected Windows PC** gives the real refusal reason — use it
  first.
- `62` = continuous roll; `62x100` etc. = die-cut. Sending one to the other is "Wrong Roll Type".

**Schema (SQLite, `src/db.js`, idempotent `addColumn` migrations):** tables `sites`, `hosts`,
`frequent_visitors`, `visits`, `admin_users`, `login_attempts`, `pin_attempts`, `settings`,
`sheet_queue` (now unused). Notable additions this session: `sites.printer_{enabled,host,port,
model,rotate,label}`, `sites.photo_{mode,threshold,contrast}`, `sites.badge_*`,
`sites.banner_{path,height,align}`, `sites.colour_{brand,signout,page,text}`,
`frequent_visitors.{pin_lookup,photo_path,company,site_id}`, `visits.{company,site_id,site_name}`.

**Diagnostic scripts (run inside the container):** `scripts/version.mjs` (`npm run version`),
`scripts/print-test.mjs [--dry] [--label ID] [--rotate DEG]`, `scripts/printer-status.mjs`
(won't work on the QL-820NWB — see above), `scripts/print-probe.mjs` (interactive, needs
`docker compose exec -it`), `scripts/make-cert.mjs [--force]`, `scripts/gen-cert.sh`.

**Push scripts:** `push-to-gitea.ps1/.bat/.sh`. Bugs fixed in-session: PowerShell functions
return their whole output stream (a wrapper made every git call look failed); branch was
hard-coded to `main` while work was on `deploy`; now detects unfinished rebases, checks git
identity, uses the checked-out branch, and verifies `$LASTEXITCODE` after each call.

## Code Changes
Whole project created this session. Principal files:
- `src/server.js` — Express app, HTTPS listener with cert hot-swap, HTTP helper (CA downloads +
  redirect), admin page routing before static, `Cache-Control: no-cache` on html/js/css, jobs.
- `src/db.js` — schema, migrations, default site, `pin_lookup` backfill, duplicate reporting.
- `src/config.js` — env parsing incl. `https`, `sheets`, `printing`, `admin` groups.
- `src/auth.js` — scrypt passwords, RFC 6238 TOTP (verified against RFC vectors), recovery codes.
- `src/users.js` — admin accounts, domain restriction, lockout, bootstrap.
- `src/pins.js` — PIN encrypt/decrypt, keyed `pinLookup`, collision-aware `generatePin`.
- `src/photos.js` — save/copy/purge visit and profile photos.
- `src/sites.js` — site helpers, HTML badge renderer (browser fallback).
- `src/branding.js` — theme derivation, WCAG contrast, banner storage.
- `src/tls.js` — CA + server cert lifecycle, DER export, zip bundle.
- `src/zip.js` — dependency-free ZIP writer.
- `src/sheets.js` — single-tab "On site now" rewrite, human-readable Google error mapping.
- `src/printer.js` — canvas badge render, Floyd–Steinberg halftone, `brother_ql` invocation with
  `--red` for `62red`, photo preview sheet, error translation.
- `src/routes/kiosk.js` — sign in/out, PIN auth, site scoping, server-print with fallback.
- `src/routes/admin.js` — auth/2FA, users, sites, hosts, recurring visitors, visits, printer
  diagnostics/test/preview, TLS endpoints, status.
- `public/index.html`, `public/js/kiosk.js`, `public/css/kiosk.css` — kiosk flow (filter input
  above host dropdown, square photo capture, badge fallback).
- `public/login.html`, `public/js/login.js`, `public/css/login.css` — standalone paged login.
- `public/admin.html`, `public/js/admin.js`, `public/css/admin.css` — console.
- `Dockerfile`, `docker-compose.yml`, `docker-entrypoint.sh`, `.gitattributes`, `.env.example`.
- `scripts/*` — diagnostics and cert tooling listed above.

## Open Questions / Next Steps
- **Confirm the `--red` fix prints on real hardware.** Pending: deploy, then **Test print**. The
  site's roll setting is already `62red` with red on.
- **Latest changes exist only in the handed-over tarball, not in git:** CA zip bundle, printer
  diagnostics/probe scripts, `--red` flag, photo halftoning. Next: extract over the Windows
  working copy → commit → push `deploy` → host `reset --hard origin/deploy` → rebuild.
- **Tune photo halftoning from a printed label** (defaults: error diffusion, threshold 50,
  contrast 20). 300 dpi dithering reads differently in the hand than on screen.
- Physical print output not yet verified: margins, cut position, rotation on the roll, red plane.
- Host `.env` is stale; recommend rebuilding from `.env.example`, preserving `APP_SECRET` exactly.
- Google Sheet returned 403 "caller does not have permission" — fix is sharing the sheet with the
  service account (shown in Admin → System). Outcome not confirmed.
- Recommend a DNS name for the kiosk instead of a bare IP (IP-only certs are unreliable on
  Android; DHCP changes break everything).
- Consider making `deploy` the default branch in Gitea / retiring the tangled `main`.
- Offered, not built: die-cut roll options in the roll dropdown; an admin field for
  `HTTPS_HOSTNAMES`; banner/logo on the printed pass; theming the admin console.
- Housekeeping: `sheet_queue` table is unused; `brother_ql==0.9.4` is unmaintained (fork
  `brother_ql_next` exists).

## Artifacts
- Repository: `<redacted-gitea-host>/<redacted-owner>/visitor-signin`, working branch `deploy`.
- Commits on `deploy`: `8bc7179` Server-side printing, roll type setting, cache headers;
  `eb98658` Printing Debug; `b1a7933` Printer Debug 2.
- `brother_ql` 0.9.4 (PyPI) — `print --help` documents the `--red` requirement.
- Brother QL-820NWB specification: 12–62 mm media, 60.96 mm max print width, 300×300 dpi.
- RFC 6238 (TOTP) — test vectors used to verify `src/auth.js`.

---

## Addendum — 2026-09-23, PIN reset bug

**Symptom:** after changing a recurring visitor's PIN, phone + PIN was rejected at the kiosk.

**Cause:** the Edit form carried a "PIN" field whose value `PATCH /admin/api/frequent/:id`
never read. The record saved, the field was silently discarded, and the admin handed out a PIN
the system had never stored. (`POST /admin/api/frequent/:id/pin`, the "New PIN" button, was
always correct — verified by reproduction.)

**Fix:** `PATCH` now honours a supplied `pin`: 4 digits, checked for collisions via
`allocatePin(pin, row.id)`, written to `pin_enc` and `pin_lookup`. Blank keeps the current PIN.
A malformed or already-used PIN is rejected with a message instead of ignored. The response
carries `pinChanged`, and the console shows the printable card when it is true. Saving a record
also clears `pin_attempts` for both the old and new phone number, so a changed number cannot
leave a stale lockout.

**Files:** `src/routes/admin.js` (PATCH handler), `public/js/admin.js` (edit modal shows the
current PIN, relabelled field, shows the card after a change), `public/css/admin.css`, `README.md`.

---

## Addendum — iPad trust troubleshooting

Reported: Safari and Chrome on a Jamf-managed iPad still report an insecure connection after the
certificate was imported into Jamf.

**Found:** the server certificate was being issued for *exactly* 398 days — Apple's ceiling, with
zero margin for rounding or clock skew. `SERVER_DAYS` in `src/tls.js` reduced 398 → 396.

**Added:** `scripts/tls-check.mjs` (`npm run tls-check`), which connects to a given URL and checks
what iOS requires: address covered by a SAN, validity span, SAN present, `serverAuth` EKU,
signature algorithm, key size, and that the served leaf was issued by this server's CA. It prints
the authority and leaf fingerprints side by side.

Note: Node's `X509Certificate` does not expose extended key usage and `toString()` returns PEM,
so the EKU and signature checks shell out to `openssl x509 -noout -text`.

**Most likely causes, still unconfirmed on the device:** the *served* certificate was uploaded to
Jamf instead of the *authority*; or the address the iPad uses is not in `HTTPS_HOSTNAMES` (the
host `.env` was previously missing that line entirely).

---

## Addendum — promote a guest to a recurring visitor

Added **Make regular** to the On site list for any visit with a mobile number that is not already
a recurring visitor.

`POST /admin/api/visits/:id/make-regular` copies name, company, phone, email, check type/number/
expiry, host (as their default) and site from the visit, issues a random unique PIN via
`allocatePin(null)`, and copies the visit photo into a separate profile photo with
`copyStoredPhoto` so retention purging the visit cannot delete it. Returns the shaped record plus
`pin` and `photoCarriedOver`; the console opens the printable card.

Refusals: no mobile number on the visit (the number is the sign in name); phone or email already
belongs to a recurring visitor (error names them and returns `existingId`). Site-scoped admins are
checked with `assertSiteAllowed`. The visit row is deliberately not modified or relinked.

**Files:** `src/routes/admin.js`, `public/js/admin.js`, `README.md`.