blockyard 0.0.1 → 0.0.9

package/scripts/ui.js

@@ -0,0 +1,174 @@
+// THE INSTALLER'S TERMINAL DRESS (scripts/setup.js, scripts/check.js): colour that steps aside when
+// there is no terminal or NO_COLOR is set, a banner, numbered steps, marks for check results, a
+// spinner, a progress bar that redraws in place, and a box for the summary. Pure formatting,
+// exported so the pieces with arithmetic in them (the bar, the ETA) are tested without a terminal.
+import { stdout } from 'node:process';
+
+export const COLOUR = !!((stdout.isTTY || process.env.FORCE_COLOR) && !process.env.NO_COLOR && process.env.TERM !== 'dumb');
+const wrap = (open, close) => (s) => (COLOUR ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+export const c = {
+  bold: wrap('1', '22'), dim: wrap('2', '22'), italic: wrap('3', '23'),
+  accent: wrap('38;5;214', '39'), ok: wrap('38;5;78', '39'), warn: wrap('38;5;221', '39'), bad: wrap('38;5;203', '39'),
+  cyan: wrap('38;5;80', '39'), white: wrap('97', '39'),
+};
+
+export const MARK = {
+  ok: () => c.ok('✓'), warn: () => c.warn('!'), fail: () => c.bad('✗'), info: () => c.dim('·'),
+};
+
+// THE MONOGRAM, IN PIXELS (operator, 2026-09-14: "I want the installer to have amazing ANSI Art here
+// for the BY logo"). The same tile the favicon is: a rounded orange tile shaded light to dark
+// across the diagonal, a dark B and Y with uprights two cells wide (a cell is twice as tall as it is
+// wide, so a two-cell upright and a one-row crossbar are the same thickness on screen -- operator:
+// "The black letters need to be thicker"), and three courses of blocks along the foot. One character
+// cell per pixel, painted as a background colour, from the 256-colour table -- solid in every
+// terminal font; without colour it falls back to three lines of box drawing.
+const ART = [
+  '  ......................  ',
+  ' ........................ ',
+  '...#######...##......##...',
+  '...##....##..##......##...',
+  '...##....##...##....##....',
+  '...#######.....##..##.....',
+  '...##....##.....####......',
+  '...##....##......##.......',
+  '...##....##......##.......',
+  '...#######.......##.......',
+  ' .ooooooo.oooooo.ooooooo. ',
+  '  ......................  ',
+];
+const TILE = [223, 222, 215, 214, 208, 172, 166];   // light to dark, the favicon's gradient in 256 colours
+const INK = 233;
+function pixel(ch, x, y) {
+  if (ch === ' ') return null;
+  const t = (x / (ART[0].length - 1) + y / (ART.length - 1)) / 2;
+  const tone = TILE[Math.min(TILE.length - 1, Math.floor(t * TILE.length))];
+  if (ch === '#') return INK;
+  if (ch === 'o') return TILE[Math.min(TILE.length - 1, Math.floor(t * TILE.length) + 1)];
+  return tone;
+}
+export function monogram() {
+  if (!COLOUR) return [`${c.accent('▗▄▖')}`, `${c.accent('▐BY')}`, `${c.accent('▝▀▘')}`];
+  // ONE CELL PER PIXEL, painted as a background colour under a space. The first cut used the
+  // half-block (two pixels per row) and the Mac's Terminal drew every seam between them
+  // (operator: "What is this garbage?!"): a font decides how a half-block glyph sits in its cell,
+  // and a background colour fills the cell whatever the font.
+  return ART.map((row, y) => {
+    let line = '', open = null;
+    for (let x = 0; x < row.length; x++) {
+      const tone = pixel(row[x], x, y);
+      if (tone !== open) { line += open == null ? '' : '\x1b[49m'; line += tone == null ? '' : `\x1b[48;5;${tone}m`; open = tone; }
+      line += ' ';
+    }
+    return line + (open == null ? '' : '\x1b[49m');
+  });
+}
+
+/** The banner: the monogram beside the name, the version and what this is; below it when narrow. */
+export function banner(version, what = 'setup', width = cols()) {
+  const art = monogram();
+  const head = `${c.bold('Block')}${c.accent(c.bold('Yard'))}  ${c.dim(version)}   ${c.dim('·')}   ${c.bold(what)}`;
+  // every line fits beside the tile in 80 columns (operator: "It needs to fit in 80 character space. Standard CRT")
+  const about = ['Live monitor, block explorer, markets and 3D', 'block-space viewer for Bitcoin Core.', '', 'Zero dependencies, self-hosted, read-only.', 'Apache-2.0.'].map((l) => c.dim(l));
+  if (!COLOUR) return `\n${art.map((r, i) => `${r} ${i === 0 ? head : i === 1 ? about[0] : i === 2 ? about[1] : ''}`).join('\n')}\n`;
+  const artW = strip(art[0]).length;
+  const beside = width >= artW + 3 + 49 + 2;   // 26 + 3 + 49 + 2 = 80
+  if (!beside) return '\n' + art.map((r) => `  ${r}`).join('\n') + `\n\n  ${head}\n  ${about.join('\n  ')}\n`;
+  const text = ['', '', head, ...about];
+  return '\n' + art.map((row, i) => `  ${row}   ${text[i] ?? ''}`).join('\n') + '\n';
+}
+
+/** A numbered step heading with a rule out to the right. */
+export function step(n, total, title, width = cols()) {
+  const head = `  ${c.accent(c.bold(`${n}`))}${c.dim(`/${total}`)}  ${c.bold(title)}  `;
+  const plain = `  ${n}/${total}  ${title}  `;
+  return `\n${head}${c.dim('─'.repeat(Math.max(4, width - plain.length - 2)))}\n`;
+}
+
+/** One check result, as a line. */
+export function checkLine(status, name, detail, width = cols()) {
+  const mark = (MARK[status] ?? MARK.info)();
+  const label = status === 'fail' ? c.bad(name) : status === 'warn' ? c.warn(name) : status === 'info' ? c.dim(name) : name;
+  const room = Math.max(20, width - 26);
+  return `    ${mark} ${label.padEnd(name.length > 18 ? 0 : 18 + (label.length - name.length))} ${wrapText(detail, room, 25)}`;
+}
+
+/** Wrap a detail string so continuation lines sit under its first character. */
+export function wrapText(text, width, indent) {
+  const words = String(text).split(' ');
+  const lines = [];
+  let line = '';
+  // widths are measured on what is seen, not on the colour codes around it
+  for (const w of words) {
+    if (line && strip(line).length + 1 + strip(w).length > width) { lines.push(line); line = w; } else line = line ? `${line} ${w}` : w;
+  }
+  if (line) lines.push(line);
+  return lines.join('\n' + ' '.repeat(indent));
+}
+
+/** Text in a rounded box. */
+export function box(lines, { title = null, pad = 1, width = null, max = cols() - 6 } = {}) {
+  // NOTHING WIDER THAN THE TERMINAL (operator, 2026-09-14, of a box whose one long line broke its
+  // frame on an 80-column Mac): a line past the room is cut with an ellipsis -- a body line keeps
+  // its start, a title (a path) keeps its end
+  const room = Math.max(20, max - pad * 2);
+  const cut = (l, keepEnd) => { const r = strip(l); if (r.length <= room) return l; return keepEnd ? `…${r.slice(r.length - room + 1)}` : `${r.slice(0, room - 1)}…`; };
+  lines = lines.map((l) => cut(l, false));
+  if (title != null) title = cut(title, true);
+  const raw = lines.map((l) => strip(l));
+  const inner = width ?? Math.max(...raw.map((l) => l.length), title ? strip(title).length + 2 : 0) + pad * 2;
+  const top = title ? `╭─ ${title} ${'─'.repeat(Math.max(0, inner - strip(title).length - 3))}╮` : `╭${'─'.repeat(inner)}╮`;
+  const body = lines.map((l, i) => `│${' '.repeat(pad)}${l}${' '.repeat(Math.max(0, inner - pad - raw[i].length))}│`);
+  return [c.dim(top[0]) + top.slice(1, -1) + c.dim(top.slice(-1)), ...body.map((b) => c.dim('│') + b.slice(1, -1) + c.dim('│')), c.dim(`╰${'─'.repeat(inner)}╯`)].join('\n');
+}
+
+export function strip(s) { return String(s).replace(/\x1b\[[0-9;]*m/g, ''); }
+export function cols() { return Math.min(100, Math.max(60, stdout.columns ?? 80)); }
+
+/** A spinner on a TTY; a single line otherwise. stop() erases it. */
+export function spinner(text) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0, timer = null;
+  if (stdout.isTTY) {
+    const draw = () => stdout.write(`\r    ${c.accent(frames[i++ % frames.length])} ${text}`);
+    draw(); timer = setInterval(draw, 80);
+  } else stdout.write(`    … ${text}\n`);
+  return { stop() { if (timer) { clearInterval(timer); stdout.write(`\r${' '.repeat(text.length + 8)}\r`); } } };
+}
+
+const HMS = (s) => (s < 90 ? `${Math.round(s)} s` : s < 5400 ? `${Math.round(s / 60)} min` : `${(s / 3600).toFixed(1)} h`);
+const G = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(2)} B` : n >= 1e6 ? `${(n / 1e6).toFixed(1)} M` : n >= 1e3 ? `${(n / 1e3).toFixed(0)} k` : String(n));
+
+/**
+ * One line of a progress bar: `phase ████░░ done/total · rows · rate · ETA`. `elapsed` in seconds
+ * since the phase began; the ETA assumes the rate so far holds. Pure, so it is tested.
+ */
+export function progressLine({ phase, done, total, rows = null, elapsed = 0 }, width = cols()) {
+  const frac = total > 0 ? Math.min(1, done / total) : 0;
+  const barW = Math.max(10, Math.min(30, width - 62));
+  const filled = Math.round(frac * barW);
+  const bar = c.accent('█'.repeat(filled)) + c.dim('░'.repeat(barW - filled));
+  const rate = elapsed > 0 && done > 0 ? done / elapsed : 0;
+  const eta = rate > 0 && total > done ? HMS((total - done) / rate) : null;
+  const bits = [`${String(done).padStart(String(total).length)}/${total}`, `${Math.round(frac * 100)}%`];
+  if (rows != null) bits.push(`${G(rows)} rows`);
+  if (eta) bits.push(`about ${eta} left`);
+  else if (frac >= 1) bits.push(`done in ${HMS(elapsed)}`);
+  return `  ${c.bold(phase.padEnd(7))} ${bar}  ${c.dim(bits.join(' · '))}`;
+}
+
+/** Draws progress lines in place on a TTY; on a pipe, one line each time the percentage moves. */
+export function progress() {
+  let lastPct = -1, lastPhase = null;
+  return {
+    update(p) {
+      const line = progressLine(p);
+      if (stdout.isTTY) { stdout.write(`\r\x1b[2K${line}`); return; }
+      const pct = p.total > 0 ? Math.floor((p.done / p.total) * 20) : 0;
+      if (p.phase !== lastPhase || pct !== lastPct) { lastPhase = p.phase; lastPct = pct; stdout.write(`${strip(line)}\n`); }
+    },
+    done(line) { if (stdout.isTTY) stdout.write(`\r\x1b[2K`); if (line) stdout.write(`${line}\n`); },
+  };
+}
+
+export const fmt = { hms: HMS, big: G };

package/server/auth/sessions.js

@@ -0,0 +1,221 @@
+// Sessions, CSRF and rate limiting.
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+function hashToken(token) {
+  return crypto.createHash('sha256').update(String(token)).digest('hex');
+}
+
+export class SessionStore {
+  constructor(file, cfg) {
+    this.file = file;
+    this.cfg = cfg;
+    this.sessions = new Map(); // tokenHash -> session
+    this.loaded = false;
+    this.dirty = false;
+  }
+
+  async load() {
+    try {
+      const data = JSON.parse(await fsp.readFile(this.file, 'utf8'));
+      for (const s of data.sessions ?? []) this.sessions.set(s.tokenHash, s);
+      this.loaded = true;
+      this.sweep();
+      return { loaded: true, count: this.sessions.size };
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw new Error(`sessions file ${this.file} unreadable (${err.message})`);
+      return { loaded: false, count: 0 };
+    }
+  }
+
+  async save() {
+    if (!this.dirty) return;
+    await fsp.mkdir(path.dirname(this.file), { recursive: true });
+    const tmp = `${this.file}.tmp`;
+    const fh = await fsp.open(tmp, 'w', 0o600);
+    await fh.writeFile(JSON.stringify({ version: 1, savedAt: Date.now(), sessions: [...this.sessions.values()] }, null, 2));
+    await fh.sync();
+    await fh.close();
+    await fsp.rename(tmp, this.file);
+    this.dirty = false;
+  }
+
+  create(user, { ip = null, userAgent = null } = {}) {
+    const token = crypto.randomBytes(32).toString('base64url');
+    const csrf = crypto.randomBytes(24).toString('base64url');
+    const now = Date.now();
+    const session = {
+      tokenHash: hashToken(token),
+      userId: user.id,
+      username: user.username,
+      role: user.role,
+      csrf,
+      createdAt: now,
+      lastSeenAt: now,
+      ip,
+      // Stored truncated and never echoed back: useful for "sign out everywhere
+      // else", and it must not turn into a place the app leaks device detail.
+      userAgent: userAgent ? String(userAgent).slice(0, 120) : null,
+    };
+    this.sessions.set(session.tokenHash, session);
+    this.dirty = true;
+    return { token, session };
+  }
+
+  get(token) {
+    if (!token) return null;
+    const s = this.sessions.get(hashToken(token));
+    if (!s) return null;
+    const now = Date.now();
+    if (now - s.createdAt > this.cfg.sessionTtlMs) { this.sessions.delete(s.tokenHash); this.dirty = true; return null; }
+    if (now - s.lastSeenAt > this.cfg.idleTtlMs) { this.sessions.delete(s.tokenHash); this.dirty = true; return null; }
+    // Touch at most every 30s: writing a timestamp on every request would make
+    // every SSE heartbeat a state mutation.
+    if (now - s.lastSeenAt > 30_000) { s.lastSeenAt = now; this.dirty = true; }
+    return s;
+  }
+
+  destroy(token) {
+    const hit = this.sessions.delete(hashToken(token));
+    if (hit) this.dirty = true;
+    return hit;
+  }
+
+  destroyForUser(userId) {
+    let n = 0;
+    for (const [k, s] of this.sessions) if (s.userId === userId) { this.sessions.delete(k); n += 1; }
+    if (n) this.dirty = true;
+    return n;
+  }
+
+  sweep() {
+    const now = Date.now();
+    let n = 0;
+    for (const [k, s] of this.sessions) {
+      if (now - s.createdAt > this.cfg.sessionTtlMs || now - s.lastSeenAt > this.cfg.idleTtlMs) { this.sessions.delete(k); n += 1; }
+    }
+    if (n) this.dirty = true;
+    return n;
+  }
+
+  active() {
+    const byUser = new Map();
+    for (const s of this.sessions.values()) byUser.set(s.userId, (byUser.get(s.userId) ?? 0) + 1);
+    return { sessions: this.sessions.size, users: byUser.size };
+  }
+
+  listFor(userId) {
+    return [...this.sessions.values()]
+      .filter((s) => s.userId === userId)
+      .map((s) => ({ createdAt: s.createdAt, lastSeenAt: s.lastSeenAt, ip: s.ip, userAgent: s.userAgent, current: false }));
+  }
+}
+
+// Token bucket: a burst is fine, a sustained flood is not.
+export class RateLimiter {
+  constructor({ capacity = 30, perSec = 10 } = {}) {
+    this.capacity = capacity;
+    this.perSec = perSec;
+    this.buckets = new Map();
+  }
+
+  check(key, cost = 1) {
+    const now = Date.now();
+    let b = this.buckets.get(key);
+    if (!b) { b = { tokens: this.capacity, at: now }; this.buckets.set(key, b); }
+    b.tokens = Math.min(this.capacity, b.tokens + ((now - b.at) / 1000) * this.perSec);
+    b.at = now;
+    if (b.tokens < cost) {
+      const need = cost - b.tokens;
+      return { ok: false, retryAfterMs: Math.ceil((need / this.perSec) * 1000), remaining: 0 };
+    }
+    b.tokens -= cost;
+    // Keep the map from growing without bound on a chatty LAN.
+    if (this.buckets.size > 5000) {
+      const cutoff = now - 600_000;
+      for (const [k, v] of this.buckets) if (v.at < cutoff) this.buckets.delete(k);
+    }
+    return { ok: true, remaining: Math.floor(b.tokens) };
+  }
+}
+
+// Failed-login tracking, keyed on BOTH username and address: a spray across many
+// usernames from one host and a grind on one username from many hosts are
+// different attacks and both need to be visible.
+export class LoginGuard {
+  constructor({ maxAttempts = 8, windowMs = 300000, lockoutMs = 600000 } = {}) {
+    this.maxAttempts = maxAttempts;
+    this.windowMs = windowMs;
+    this.lockoutMs = lockoutMs;
+    this.attempts = new Map();
+  }
+
+  _entry(key) {
+    let e = this.attempts.get(key);
+    if (!e) { e = { hits: [], lockedUntil: 0 }; this.attempts.set(key, e); }
+    const cutoff = Date.now() - this.windowMs;
+    e.hits = e.hits.filter((t) => t > cutoff);
+    return e;
+  }
+
+  status(username, ip) {
+    const a = this._entry(`u:${username}`);
+    const b = this._entry(`i:${ip}`);
+    const locked = Math.max(a.lockedUntil, b.lockedUntil);
+    if (locked > Date.now()) return { blocked: true, retryAfterMs: locked - Date.now() };
+    const worst = Math.max(a.hits.length, b.hits.length);
+    return { blocked: false, attempts: worst, remaining: Math.max(0, this.maxAttempts - worst) };
+  }
+
+  noteFailure(username, ip) {
+    const out = [];
+    for (const key of [`u:${username}`, `i:${ip}`]) {
+      const e = this._entry(key);
+      e.hits.push(Date.now());
+      if (e.hits.length >= this.maxAttempts) {
+        e.lockedUntil = Date.now() + this.lockoutMs;
+        e.hits = [];
+        out.push(key);
+      }
+      this.attempts.set(key, e);
+    }
+    return { locked: out };
+  }
+
+  noteSuccess(username, ip) {
+    this.attempts.delete(`u:${username}`);
+    this.attempts.delete(`i:${ip}`);
+  }
+}
+
+export function parseCookies(header = '') {
+  const out = {};
+  for (const part of String(header).split(';')) {
+    const i = part.indexOf('=');
+    if (i < 0) continue;
+    const k = part.slice(0, i).trim();
+    if (!k) continue;
+    try { out[k] = decodeURIComponent(part.slice(i + 1).trim()); } catch { out[k] = part.slice(i + 1).trim(); }
+  }
+  return out;
+}
+
+export function serializeCookie(name, value, { maxAgeMs, httpOnly = true, secure = false, sameSite = 'Strict', path: p = '/' } = {}) {
+  const bits = [`${name}=${encodeURIComponent(value)}`, `Path=${p}`, `SameSite=${sameSite}`];
+  if (httpOnly) bits.push('HttpOnly');
+  if (secure) bits.push('Secure');
+  if (maxAgeMs != null) bits.push(`Max-Age=${Math.floor(maxAgeMs / 1000)}`);
+  return bits.join('; ');
+}
+
+// CSRF: the session cookie is HttpOnly + SameSite=Strict already; this adds the
+// double-submit check on top so a cross-origin POST cannot slip past a browser
+// that relaxed SameSite for some reason.
+export function csrfOk(session, headerValue) {
+  if (!session?.csrf) return false;
+  if (!headerValue) return false;
+  const a = Buffer.from(String(session.csrf));
+  const b = Buffer.from(String(headerValue));
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}

package/server/auth/users.js

@@ -0,0 +1,243 @@
+// Users: scrypt-hashed passwords in a JSON store, atomic writes.
+//
+// Threat model note: this is a multi-user webserver on a LAN that can read the
+// secrets of a bitcoin node (the RPC cookie is readable by this process). So the
+// credential store must not be the soft spot. scrypt at the default parameters costs
+// 20 ms and 16.0 MB per guess, measured on this box on 2026-09-09 (128·r·N; the
+// "~50 ms" this comment previously claimed was an estimate and is corrected here).
+// That is what makes an offline crack of a leaked users.json expensive rather than
+// trivial -- and also why an unthrottled login endpoint is a CPU denial of service
+// (see app.loginLimiter in server/main.js and MEASUREMENTS §22). Never logged, never
+// returned by any API, never sent to the browser.
+import fsp from 'node:fs/promises';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const USERNAME_RE = /^[a-z0-9][a-z0-9._-]{1,30}$/;
+export const ROLES = ['viewer', 'operator', 'admin'];
+
+export class UserStore {
+  constructor(file, cfg) {
+    this.file = file;
+    this.cfg = cfg;
+    this.users = [];
+    this.loaded = false;
+  }
+
+  async load() {
+    try {
+      const raw = await fsp.readFile(this.file, 'utf8');
+      const data = JSON.parse(raw);
+      this.users = Array.isArray(data.users) ? data.users : [];
+      this.loaded = true;
+      return { loaded: true, count: this.users.length };
+    } catch (err) {
+      if (err.code === 'ENOENT') return { loaded: false, count: 0 };
+      // A corrupt user file must not silently mean "no users", because the
+      // bootstrap path would then create a second admin and a later save would
+      // erase whoever was there. Refuse loudly instead.
+      throw new Error(`users store at ${this.file} is unreadable (${err.message}); refusing to start rather than overwrite it`);
+    }
+  }
+
+  async save() {
+    await fsp.mkdir(path.dirname(this.file), { recursive: true });
+    const tmp = `${this.file}.tmp`;
+    const fh = await fsp.open(tmp, 'w', 0o600);
+    await fh.writeFile(JSON.stringify({ version: 1, updatedAt: Date.now(), users: this.users }, null, 2));
+    await fh.sync();
+    await fh.close();
+    await fsp.rename(tmp, this.file);
+    try { await fsp.chmod(this.file, 0o600); } catch { /* filesystem may not support it */ }
+  }
+
+  get count() { return this.users.length; }
+  list() {
+    return this.users.map((u) => ({
+      id: u.id, username: u.username, role: u.role, createdAt: u.createdAt,
+      updatedAt: u.updatedAt, lastLoginAt: u.lastLoginAt ?? null, disabled: !!u.disabled,
+      scheme: u.params?.scheme ?? 'scrypt',
+      // Visible so raising auth.scrypt is a change with an observable effect: the
+      // admin page can say "2 of 5 accounts still use N=16384" instead of the
+      // operator wondering whether the new number took.
+      kdf: u.params ? { N: u.params.N, r: u.params.r, p: u.params.p, keylen: u.params.keylen } : null,
+      kdfNeedsUpgrade: !!u.params && needsRehash(u, this.cfg?.scrypt),
+    }));
+  }
+
+  find(username) {
+    const want = String(username ?? '').toLowerCase();
+    return this.users.find((u) => u.username === want) ?? null;
+  }
+
+  byId(id) { return this.users.find((u) => u.id === id) ?? null; }
+
+  async createUser(username, password, { role = 'viewer' } = {}) {
+    const uname = String(username ?? '').toLowerCase().trim();
+    if (!USERNAME_RE.test(uname)) throw new Error('username must be 2-31 chars: lowercase letters, digits, dot, dash, underscore');
+    if (this.find(uname)) throw new Error(`user "${uname}" already exists`);
+    if (!ROLES.includes(role)) throw new Error(`role must be one of ${ROLES.join(', ')}`);
+    this.checkPasswordStrength(password, uname);
+    const { hash, params } = await hashPassword(password, this.cfg.scrypt);
+    const user = {
+      id: crypto.randomBytes(8).toString('hex'),
+      username: uname,
+      salt: params.salt.toString('hex'),
+      hash: hash.toString('hex'),
+      params: { N: params.N, r: params.r, p: params.p, keylen: params.keylen, scheme: 'scrypt' },
+      role,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      lastLoginAt: null,
+      disabled: false,
+    };
+    this.users.push(user);
+    await this.save();
+    return { id: user.id, username: user.username, role: user.role };
+  }
+
+  checkPasswordStrength(password, uname) {
+    const pw = String(password ?? '');
+    const min = this.cfg.minPasswordChars;
+    if (pw.length < min) throw new Error(`password must be at least ${min} characters`);
+    const lower = pw.toLowerCase();
+    if (uname && lower.includes(uname)) throw new Error('password must not contain the username');
+    // No composition rules (they push people to "Password123!"), but a few
+    // shapes that appear in every breach corpus are simply refused.
+    const weak = /^(password|letmein|admin|welcome|qwerty|123456|changeme|bitcoin|btc)/i.test(pw);
+    if (weak) throw new Error('password starts from a shape that appears in every breach corpus; pick something else');
+    if (/^(.)\1+$/.test(pw)) throw new Error('password is a single repeated character');
+  }
+
+  /**
+   * Verify a password, and quietly bring the stored hash up to date.
+   *
+   * The upgrade path is the reason the parameters are stored per user rather than
+   * globally: a KDF cost is not a constant, it is a guess about next year's
+   * hardware, and an installation that never rehashes keeps verifying against
+   * 2026's choice forever. Doing it here — at the one moment the plaintext is in
+   * hand — means raising `auth.scrypt` in the config actually raises it for every
+   * account, one login at a time, with no forced password resets.
+   *
+   * An unknown `scheme` is refused rather than assumed to be scrypt: if this store
+   * ever gains a second scheme, silently interpreting it wrong would mean every
+   * password under it stops working (worse: starts working under weaker rules).
+   */
+  async verify(username, password) {
+    const user = this.find(username);
+    // Always do the KDF work, even for an unknown username, so response time
+    // does not tell an attacker whether the account exists.
+    const target = user ?? { salt: crypto.randomBytes(16).toString('hex'), hash: Buffer.alloc(32), params: { N: this.cfg.scrypt.N, r: this.cfg.scrypt.r, p: this.cfg.scrypt.p, keylen: this.cfg.scrypt.keylen } };
+    const params = { N: target.params?.N ?? 16384, r: target.params?.r ?? 8, p: target.params?.p ?? 1, keylen: target.params?.keylen ?? 32 };
+    const scheme = target.params?.scheme ?? 'scrypt';
+    if (scheme !== 'scrypt') {
+      if (!user) return { ok: false, user: null, reason: 'no such user' };
+      return { ok: false, user, reason: `unsupported hash scheme "${scheme}"; reset this password` };
+    }
+    const derived = await scrypt(String(password ?? ''), Buffer.from(target.salt, 'hex'), params);
+    const known = Buffer.from(target.hash, 'hex');
+    const ok = known.length === derived.length && crypto.timingSafeEqual(known, derived);
+    if (!user) return { ok: false, user: null, reason: 'no such user' };
+    if (user.disabled) return { ok: false, user, reason: 'account disabled' };
+    if (!ok) return { ok: false, user, reason: 'bad password' };
+    user.lastLoginAt = Date.now();
+    let upgraded = null;
+    if (needsRehash(user, this.cfg.scrypt)) {
+      // Only on a verified password: rehashing a wrong password would store a hash
+      // of the wrong secret. Re-derived with the CURRENT configured cost, new salt.
+      const { hash, params: np } = await hashPassword(String(password ?? ''), this.cfg.scrypt);
+      upgraded = { from: { ...params }, to: { N: np.N, r: np.r, p: np.p, keylen: np.keylen } };
+      user.salt = np.salt.toString('hex');
+      user.hash = hash.toString('hex');
+      user.params = { N: np.N, r: np.r, p: np.p, keylen: np.keylen, scheme: 'scrypt' };
+      user.updatedAt = Date.now();
+    }
+    await this.save().catch(() => {});
+    return { ok: true, user, upgraded };
+  }
+
+  async setPassword(username, password) {
+    const user = this.find(username);
+    if (!user) throw new Error('no such user');
+    this.checkPasswordStrength(password, user.username);
+    const { hash, params } = await hashPassword(password, this.cfg.scrypt);
+    user.salt = params.salt.toString('hex');
+    user.hash = hash.toString('hex');
+    user.params = { N: params.N, r: params.r, p: params.p, keylen: params.keylen, scheme: 'scrypt' };
+    user.updatedAt = Date.now();
+    await this.save();
+    return { id: user.id, username: user.username };
+  }
+
+  async setRole(username, role) {
+    if (!ROLES.includes(role)) throw new Error(`role must be one of ${ROLES.join(', ')}`);
+    const user = this.find(username);
+    if (!user) throw new Error('no such user');
+    const admins = this.users.filter((u) => u.role === 'admin' && !u.disabled);
+    if (user.role === 'admin' && role !== 'admin' && admins.length <= 1) {
+      // Losing the last admin leaves nobody able to administer; refuse rather
+      // than talk the operator out of their own tool.
+      throw new Error('refusing to demote the last enabled admin');
+    }
+    user.role = role;
+    user.updatedAt = Date.now();
+    await this.save();
+    return { id: user.id, username: user.username, role };
+  }
+
+  async setDisabled(username, disabled) {
+    const user = this.find(username);
+    if (!user) throw new Error('no such user');
+    const admins = this.users.filter((u) => u.role === 'admin' && !u.disabled);
+    if (user.role === 'admin' && disabled && admins.length <= 1) throw new Error('refusing to disable the last enabled admin');
+    user.disabled = !!disabled;
+    user.updatedAt = Date.now();
+    await this.save();
+    return { id: user.id, username: user.username, disabled: user.disabled };
+  }
+
+  async deleteUser(username) {
+    const user = this.find(username);
+    if (!user) throw new Error('no such user');
+    const admins = this.users.filter((u) => u.role === 'admin' && !u.disabled);
+    if (user.role === 'admin' && admins.length <= 1) throw new Error('refusing to delete the last enabled admin');
+    this.users = this.users.filter((u) => u.id !== user.id);
+    await this.save();
+    return { deleted: user.username };
+  }
+}
+
+function scrypt(password, salt, { N, r, p, keylen }) {
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(password, salt, keylen, { N, r, p, maxmem: Math.max(64 * 1024 * 1024, 128 * r * N + 1024 * 1024) }, (err, dk) => (err ? reject(err) : resolve(dk)));
+  });
+}
+
+/** Would this hash be derived differently under the currently configured cost? */
+export function needsRehash(user, cfgScrypt) {
+  if (!user?.params || !cfgScrypt) return false;
+  const p = user.params;
+  return p.N !== cfgScrypt.N || p.r !== cfgScrypt.r || p.p !== cfgScrypt.p || p.keylen !== cfgScrypt.keylen;
+}
+
+async function hashPassword(password, base) {
+  const salt = crypto.randomBytes(16);
+  const params = { ...base, salt };
+  const hash = await scrypt(password, salt, base);
+  return { hash, params };
+}
+
+// One-time bootstrap credential. Printed once to stdout and never stored in
+// plaintext anywhere, so there is nothing to go looking for afterwards.
+export function randomPassword(len = 20) {
+  const alphabet = 'abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%*-+=';
+  // crypto.randomInt, NOT randomBytes()%n. The alphabet is 66 long and 256 % 66 = 58, so the
+  // modulo form drew the first 58 characters slightly more often than the rest -- a small bias,
+  // in the one function whose entire job is to be an unguessable bootstrap credential. randomInt
+  // rejection-samples internally, so the distribution is flat. (Audit, 2026-09-13.)
+  let out = '';
+  for (let i = 0; i < len; i++) out += alphabet[crypto.randomInt(alphabet.length)];
+  return out;
+}
+