feat: serve the BYOS device API

The panel now pairs, fetches its image and files its logs against this
application rather than against the TRMNL cloud.

Four endpoints: /api/setup issues a token on first contact,
/api/display hands back an image and a wake interval, /api/log stores
firmware diagnostics, and /api/device/image/<hash> serves the bytes.

The wake interval is where freshness and battery are traded off. In BYOS
nothing can be pushed: the device sleeps, wakes, asks and sleeps again.
So the interval is short while the shop trades and long overnight, and
it is shortened further whenever a change of state falls inside it —
the door opening in twenty minutes means waking in twenty-one,
whatever the base interval says.

The image filename is the hash of its own bytes. The firmware skips the
redraw when the name is unchanged, which is the whole battery strategy,
and the URL is immutable, unguessable and safe to cache forever. Two
integration tests pin this: unchanged data must yield the same filename
and store one row, changed hours must yield a different one.

MAC addresses are normalised before use. They are a primary key here,
and firmwares are inconsistent about case and separators; without this a
panel could register twice by capitalising itself differently. Header
names are read in both the hyphen and underscore spellings for the same
reason — the TRMNL docs and the Seeed sources disagree, and being
liberal costs nothing while being wrong costs a blank shop window.

Pairing is deliberately made to survive a rendering failure. The token
is issued once and only its digest is kept, so a device stranded by a
failed response would be registered yet hold no credential, and unable
to register again. The welcome image is worth far less than that. This
was found by running the flow, not by reading it.

satori, yoga and harfbuzz are marked external: bundling rewrites the
relative path satori uses to load its WebAssembly, and the renderer dies
on a missing hb.wasm.

The integration tests run against a real Postgres, in CI too. Mocking
Prisma here would only prove the mock works.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012cSY9pVhZmJUKNN7wf1Myd

lib/device/auth.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  generateDeviceToken,
+  generateFriendlyId,
+  hashToken,
+  normaliseMac,
+  tokenMatches,
+} from './auth';
+
+describe('generateDeviceToken', () => {
+  it('is URL-safe and long enough to be worth nothing to a guesser', () => {
+    const token = generateDeviceToken();
+    expect(token).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(token.length).toBeGreaterThanOrEqual(43);
+  });
+
+  it('never repeats', () => {
+    const tokens = new Set(Array.from({ length: 50 }, generateDeviceToken));
+    expect(tokens.size).toBe(50);
+  });
+});
+
+describe('hashToken / tokenMatches', () => {
+  it('accepts the right token', () => {
+    const token = generateDeviceToken();
+    expect(tokenMatches(token, hashToken(token))).toBe(true);
+  });
+
+  it('rejects the wrong token', () => {
+    expect(tokenMatches('wrong', hashToken(generateDeviceToken()))).toBe(false);
+  });
+
+  it('rejects an empty token', () => {
+    expect(tokenMatches('', hashToken('something'))).toBe(false);
+  });
+
+  it('rejects a stored digest of the wrong length without throwing', () => {
+    // A truncated or corrupted column must fail closed, not crash the route.
+    expect(tokenMatches('token', 'abcd')).toBe(false);
+  });
+
+  it('rejects a stored digest that is not hex without throwing', () => {
+    expect(tokenMatches('token', 'not-hex-at-all')).toBe(false);
+  });
+
+  it('produces a 64-character hex digest', () => {
+    expect(hashToken('token')).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+describe('generateFriendlyId', () => {
+  it('uses only characters that survive being read aloud', () => {
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+      expect(generateFriendlyId()).toMatch(/^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{6}$/);
+    }
+  });
+
+  it('honours a requested length', () => {
+    expect(generateFriendlyId(10)).toHaveLength(10);
+  });
+});
+
+describe('normaliseMac', () => {
+  it('accepts the colon form', () => {
+    expect(normaliseMac('FE:68:44:CE:CA:C3')).toBe('FE:68:44:CE:CA:C3');
+  });
+
+  it('accepts lower case, dashes and bare hex', () => {
+    // A device must not be able to register twice by spelling itself
+    // differently; the address is a primary key here.
+    expect(normaliseMac('fe:68:44:ce:ca:c3')).toBe('FE:68:44:CE:CA:C3');
+    expect(normaliseMac('fe-68-44-ce-ca-c3')).toBe('FE:68:44:CE:CA:C3');
+    expect(normaliseMac('fe6844ceCAc3')).toBe('FE:68:44:CE:CA:C3');
+  });
+
+  it('rejects anything that is not twelve hex digits', () => {
+    expect(normaliseMac('FE:68:44:CE:CA')).toBeNull();
+    expect(normaliseMac('not a mac')).toBeNull();
+    expect(normaliseMac('')).toBeNull();
+    expect(normaliseMac(null)).toBeNull();
+    expect(normaliseMac(undefined)).toBeNull();
+  });
+});

lib/device/auth.ts

@@ -0,0 +1,66 @@
+/**
+ * Device credentials.
+ *
+ * The panel cannot sign in through the identity provider, so it carries a
+ * static bearer token instead. That makes two things non-negotiable: only the
+ * digest is ever stored, and comparisons run in constant time — an endpoint
+ * that leaks timing is an endpoint that leaks the token.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+
+/** Unambiguous in print: no O/0, no I/1. Friendly ids get read aloud. */
+const FRIENDLY_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+
+/** 256 bits of entropy, URL-safe so it survives a captive-portal form. */
+export function generateDeviceToken(): string {
+  return randomBytes(32).toString('base64url');
+}
+
+export function hashToken(token: string): string {
+  return createHash('sha256').update(token, 'utf8').digest('hex');
+}
+
+/**
+ * Constant-time comparison of a presented token against a stored digest.
+ *
+ * Both sides are hashed first, so the buffers always have the same length and
+ * `timingSafeEqual` can never throw on a length mismatch — which would itself
+ * be an observable signal.
+ */
+export function tokenMatches(presented: string, storedHash: string): boolean {
+  const presentedDigest = Buffer.from(hashToken(presented), 'hex');
+  let storedDigest: Buffer;
+  try {
+    storedDigest = Buffer.from(storedHash, 'hex');
+  } catch {
+    return false;
+  }
+  if (storedDigest.length !== presentedDigest.length) {
+    return false;
+  }
+  return timingSafeEqual(presentedDigest, storedDigest);
+}
+
+export function generateFriendlyId(length = 6): string {
+  const bytes = randomBytes(length);
+  return Array.from(bytes, (byte) => FRIENDLY_ALPHABET[byte % FRIENDLY_ALPHABET.length]).join('');
+}
+
+/**
+ * Normalises a MAC address to upper-case colon-separated form.
+ *
+ * Firmwares are not consistent about separators or case, and the address is a
+ * primary key here, so a device must not be able to register twice by
+ * capitalising itself differently.
+ */
+export function normaliseMac(value: string | null | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+  const hex = value.replace(/[^0-9a-fA-F]/g, '').toUpperCase();
+  if (hex.length !== 12) {
+    return null;
+  }
+  return (hex.match(/.{2}/g) ?? []).join(':');
+}

lib/device/headers.ts

@@ -0,0 +1,33 @@
+/**
+ * Header reading for the device API.
+ *
+ * The firmwares are not consistent: the TRMNL documentation shows
+ * `ACCESS_TOKEN` and `BATTERY_VOLTAGE`, the Seeed sources show `Access-Token`
+ * and `Battery-Voltage`. HTTP header names are case-insensitive but underscores
+ * and hyphens are different names, so every field is read under both spellings.
+ * Being liberal here costs nothing; being wrong costs a blank shop window.
+ */
+
+export function deviceHeader(request: Request, name: string): string | null {
+  const hyphen = name.replace(/_/g, '-');
+  const underscore = name.replace(/-/g, '_');
+  return request.headers.get(hyphen) ?? request.headers.get(underscore);
+}
+
+export function deviceNumber(request: Request, name: string): number | null {
+  const raw = deviceHeader(request, name);
+  if (raw === null || raw.trim() === '') {
+    return null;
+  }
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+
+/** The caller's address, as seen through whatever proxy is in front of us. */
+export function clientIp(request: Request): string {
+  const forwarded = request.headers.get('x-forwarded-for');
+  if (forwarded) {
+    return forwarded.split(',')[0]?.trim() ?? 'unknown';
+  }
+  return request.headers.get('x-real-ip') ?? 'unknown';
+}

lib/device/refresh.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ResolvedDay, ShopStatus, ShopStatusKind } from '@/lib/schedule/types';
+
+import {
+  CHANGE_MARGIN_SEC,
+  MAX_REFRESH_SEC,
+  MIN_REFRESH_SEC,
+  computeRefreshRate,
+} from './refresh';
+
+const ZURICH = 'Europe/Zurich';
+const OPEN_SEC = 600;
+const CLOSED_SEC = 7200;
+
+const DAY: ResolvedDay = {
+  date: '2026-09-22',
+  dayOfWeek: 2,
+  isOpen: true,
+  slots: [],
+  isException: false,
+  exceptionKind: null,
+  noteFr: null,
+  noteEn: null,
+};
+
+function status(
+  kind: ShopStatusKind,
+  nextChangeAt: ShopStatus['nextChangeAt'] = null,
+): ShopStatus {
+  return { status: kind, today: DAY, nextChangeAt, nextOpening: nextChangeAt };
+}
+
+function rate(now: string, value: ShopStatus): number {
+  return computeRefreshRate({
+    now: new Date(now),
+    status: value,
+    timezone: ZURICH,
+    openSec: OPEN_SEC,
+    closedSec: CLOSED_SEC,
+  });
+}
+
+describe('computeRefreshRate', () => {
+  it('uses the short interval while the shop is trading', () => {
+    // 12:00 local, closing at 18:30: far from any change, so the base wins.
+    expect(rate('2026-09-22T10:00:00Z', status('OPEN', { date: '2026-09-22', time: '18:30' }))).toBe(
+      OPEN_SEC,
+    );
+  });
+
+  it('uses the long interval overnight', () => {
+    expect(
+      rate('2026-09-22T21:00:00Z', status('CLOSED', { date: '2026-09-23', time: '10:00' })),
+    ).toBe(CLOSED_SEC);
+  });
+
+  it('treats opening soon as a trading moment', () => {
+    // Someone is standing at the window right now; the screen must not be stale.
+    expect(
+      rate('2026-09-22T07:40:00Z', status('OPENING_SOON', { date: '2026-09-22', time: '10:00' })),
+    ).toBeLessThanOrEqual(OPEN_SEC);
+  });
+
+  it('never sleeps through a change of state', () => {
+    // 17:00 local, closing at 18:30 is 90 minutes away, well inside the long
+    // interval. The device must still wake just after the change.
+    const seconds = rate(
+      '2026-09-22T15:00:00Z',
+      status('CLOSED', { date: '2026-09-22', time: '18:30' }),
+    );
+    expect(seconds).toBe(Math.min(CLOSED_SEC, 90 * 60 + CHANGE_MARGIN_SEC));
+  });
+
+  it('wakes just after the change rather than exactly on it', () => {
+    // Closing in ten minutes: waking at the stroke of 18:30 risks redrawing
+    // the old state, so add the margin.
+    const seconds = rate(
+      '2026-09-22T16:20:00Z',
+      status('OPEN', { date: '2026-09-22', time: '18:30' }),
+    );
+    expect(seconds).toBe(130 * 60 > OPEN_SEC ? OPEN_SEC : 130 * 60 + CHANGE_MARGIN_SEC);
+  });
+
+  it('shortens the long interval for a change that falls inside it', () => {
+    // Closed, reopening in 30 minutes, base interval 2 hours.
+    const seconds = rate(
+      '2026-09-22T07:30:00Z',
+      status('CLOSED', { date: '2026-09-22', time: '10:00' }),
+    );
+    expect(seconds).toBe(30 * 60 + CHANGE_MARGIN_SEC);
+  });
+
+  it('falls back to the base interval when nothing is scheduled ahead', () => {
+    expect(rate('2026-09-22T10:00:00Z', status('CLOSED', null))).toBe(CLOSED_SEC);
+  });
+
+  it('ignores a change that has already passed', () => {
+    // A stale next-change must not produce a negative or zero interval.
+    expect(
+      rate('2026-09-22T16:00:00Z', status('CLOSED', { date: '2026-09-22', time: '10:00' })),
+    ).toBe(CLOSED_SEC);
+  });
+
+  it('never returns less than the floor', () => {
+    const seconds = rate(
+      '2026-09-22T10:00:00Z',
+      status('OPEN', { date: '2026-09-22', time: '12:00' }),
+    );
+    expect(seconds).toBeGreaterThanOrEqual(MIN_REFRESH_SEC);
+  });
+
+  it('never returns more than the ceiling', () => {
+    expect(
+      computeRefreshRate({
+        now: new Date('2026-09-22T10:00:00Z'),
+        status: status('CLOSED', null),
+        timezone: ZURICH,
+        openSec: OPEN_SEC,
+        closedSec: 999_999,
+      }),
+    ).toBe(MAX_REFRESH_SEC);
+  });
+
+  it('handles a change several days out without overflowing', () => {
+    expect(
+      rate('2026-09-26T17:00:00Z', status('CLOSED', { date: '2026-09-29', time: '10:00' })),
+    ).toBe(CLOSED_SEC);
+  });
+});

lib/device/refresh.ts

@@ -0,0 +1,76 @@
+/**
+ * How long to let the panel sleep.
+ *
+ * In BYOS there is no way to push: the device sleeps, wakes, asks, and sleeps
+ * again. The only lever is how long it sleeps for, so this is the entire
+ * freshness-versus-battery trade-off of the product, in one function.
+ *
+ * Two rules:
+ *   - sleep briefly while the shop is trading, and at length overnight;
+ *   - never sleep through a change of state. If the door opens in twenty
+ *     minutes, wake in twenty-one, whatever the base interval says.
+ */
+
+import { civilDaysBetween, minutesOfTime, toCivilDate, toCivilTime } from '@/lib/schedule/civil';
+import type { ShopStatus } from '@/lib/schedule/types';
+
+/** Below this the panel would spend its life awake. */
+export const MIN_REFRESH_SEC = 60;
+
+/** A panel that has not checked in for six hours is indistinguishable from a dead one. */
+export const MAX_REFRESH_SEC = 21_600;
+
+/** Wake just after the change, not exactly on it. */
+export const CHANGE_MARGIN_SEC = 60;
+
+export type RefreshInput = {
+  now: Date;
+  status: ShopStatus;
+  timezone: string;
+  openSec: number;
+  closedSec: number;
+};
+
+export function computeRefreshRate({
+  now,
+  status,
+  timezone,
+  openSec,
+  closedSec,
+}: RefreshInput): number {
+  // "Opening soon" gets the short interval too: that is the moment the screen
+  // is about to be wrong, and the moment someone is standing at the window.
+  const busy =
+    status.status === 'OPEN' || status.status === 'CLOSING_SOON' || status.status === 'OPENING_SOON';
+
+  let seconds = busy ? openSec : closedSec;
+
+  if (status.nextChangeAt) {
+    const untilChange = secondsUntil(now, status.nextChangeAt, timezone);
+    if (untilChange > 0) {
+      seconds = Math.min(seconds, untilChange + CHANGE_MARGIN_SEC);
+    }
+  }
+
+  return clamp(Math.round(seconds));
+}
+
+function clamp(seconds: number): number {
+  return Math.min(MAX_REFRESH_SEC, Math.max(MIN_REFRESH_SEC, seconds));
+}
+
+/**
+ * Seconds from now until a wall-clock moment.
+ *
+ * Measured on the wall clock, which is off by an hour on the two nights a year
+ * the clocks change. That only shifts one wake-up, and the alternative — a
+ * real timezone conversion back to an instant — buys nothing the panel can
+ * perceive.
+ */
+function secondsUntil(now: Date, target: { date: string; time: string }, timezone: string): number {
+  const today = toCivilDate(now, timezone);
+  const nowMinutes = minutesOfTime(toCivilTime(now, timezone));
+  const days = civilDaysBetween(today, target.date);
+  const minutes = days * 1440 + minutesOfTime(target.time) - nowMinutes;
+  return minutes * 60 - now.getUTCSeconds();
+}

lib/device/session.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolving which device is calling.
+ *
+ * The panel cannot sign in through the identity provider, so these routes are
+ * the only ones outside OIDC. They are kept narrow on purpose: a bearer token
+ * compared in constant time, and nothing else.
+ */
+
+import { prisma } from '@/lib/db';
+
+import { hashToken, normaliseMac, tokenMatches } from './auth';
+import { deviceHeader } from './headers';
+
+export type DeviceRow = Awaited<ReturnType<typeof prisma.device.findFirst>>;
+
+export async function authenticateDevice(request: Request): Promise<NonNullable<DeviceRow> | null> {
+  const token = deviceHeader(request, 'access-token') ?? bearer(request);
+  if (!token) {
+    return null;
+  }
+
+  // When the firmware sends its MAC, look the device up by it and compare the
+  // token in constant time. That is the path the spec asks for.
+  const mac = normaliseMac(deviceHeader(request, 'id'));
+  if (mac) {
+    const device = await prisma.device.findUnique({ where: { macAddress: mac } });
+    if (device && device.isActive && tokenMatches(token, device.apiKeyHash)) {
+      return device;
+    }
+    // Fall through: some firmware revisions omit ID on /api/log.
+  }
+
+  // Looking the row up by the digest reveals nothing the digest does not
+  // already contain, and the database index does the work.
+  const device = await prisma.device.findFirst({ where: { apiKeyHash: hashToken(token) } });
+  return device && device.isActive ? device : null;
+}
+
+function bearer(request: Request): string | null {
+  const header = request.headers.get('authorization');
+  if (!header?.toLowerCase().startsWith('bearer ')) {
+    return null;
+  }
+  return header.slice(7).trim() || null;
+}