mikser-io-auth 0.5.0

package/lib/grants.js

@@ -0,0 +1,162 @@
+import { registerSchema, useDatabase } from 'mikser-io'
+import { opaqueToken } from './pkce.js'
+
+// Authorization codes and refresh tokens — the only server-side state this
+// package keeps. Identity stays in files (ADR-0012); this is session
+// bookkeeping, which is exactly what the engine's sqlite substrate is for
+// (ADR-0009).
+//
+// Table prefix follows the cross-repo convention: `mikser-io-auth` →
+// `mikser_auth_*`.
+//
+// One consequence worth knowing: the engine wipes this database when its
+// schema stamp changes, so upgrading mikser signs everyone out. Codes live
+// 60 seconds so they are irrelevant; refresh tokens are the real cost, and
+// re-authenticating after an engine upgrade is a fair price for not
+// inventing a second persistence story.
+registerSchema('auth', `
+    CREATE TABLE IF NOT EXISTS mikser_auth_codes (
+        code           TEXT PRIMARY KEY,
+        client_id      TEXT NOT NULL,
+        subject        TEXT NOT NULL,
+        redirect_uri   TEXT NOT NULL,
+        code_challenge TEXT NOT NULL,
+        scope          TEXT,
+        expires_at     INTEGER NOT NULL,
+        used_at        INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_mikser_auth_codes_expiry
+        ON mikser_auth_codes (expires_at);
+
+    CREATE TABLE IF NOT EXISTS mikser_auth_refresh (
+        token      TEXT PRIMARY KEY,
+        client_id  TEXT NOT NULL,
+        subject    TEXT NOT NULL,
+        expires_at INTEGER NOT NULL,
+        revoked_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_mikser_auth_refresh_subject
+        ON mikser_auth_refresh (subject);
+
+    -- Self-registered clients (RFC 7591). Config-declared clients are NOT
+    -- here: they live in config, are not prunable, and always win a lookup.
+    -- Keeping the two apart is what makes pruning safe — an operator's
+    -- client that has not been used yet is not garbage.
+    CREATE TABLE IF NOT EXISTS mikser_auth_clients (
+        client_id     TEXT PRIMARY KEY,
+        name          TEXT NOT NULL,
+        redirect_uris TEXT NOT NULL,
+        created_at    INTEGER NOT NULL,
+        last_used_at  INTEGER
+    );
+`)
+
+const db = () => useDatabase().handle
+
+export function createCode({ clientId, subject, redirectUri, codeChallenge, scope, ttlSec = 60 }) {
+    const code = opaqueToken()
+    db().prepare(`
+        INSERT INTO mikser_auth_codes
+            (code, client_id, subject, redirect_uri, code_challenge, scope, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(code, clientId, subject, redirectUri, codeChallenge, scope ?? '', Date.now() + ttlSec * 1000)
+    return code
+}
+
+export function getCode(code) {
+    return db().prepare('SELECT * FROM mikser_auth_codes WHERE code = ?').get(code)
+}
+
+// Single-use, enforced by the UPDATE's own WHERE rather than by a read
+// followed by a write: two simultaneous redemptions of the same code both
+// pass a prior SELECT, and only one can win this.
+export function redeemCode(code) {
+    const result = db()
+        .prepare('UPDATE mikser_auth_codes SET used_at = ? WHERE code = ? AND used_at IS NULL')
+        .run(Date.now(), code)
+    return result.changes === 1
+}
+
+export function createRefreshToken({ clientId, subject, ttlSec }) {
+    const token = opaqueToken()
+    db().prepare(`
+        INSERT INTO mikser_auth_refresh (token, client_id, subject, expires_at)
+        VALUES (?, ?, ?, ?)
+    `).run(token, clientId, subject, Date.now() + ttlSec * 1000)
+    return token
+}
+
+export function getRefreshToken(token) {
+    return db().prepare('SELECT * FROM mikser_auth_refresh WHERE token = ?').get(token)
+}
+
+// Same race-safe shape as redeemCode. Rotation revokes BEFORE minting the
+// replacement, so losing the race means creating nothing at all rather than
+// leaving a valid token nobody holds.
+export function revokeRefreshToken(token) {
+    const result = db()
+        .prepare('UPDATE mikser_auth_refresh SET revoked_at = ? WHERE token = ? AND revoked_at IS NULL')
+        .run(Date.now(), token)
+    return result.changes === 1
+}
+
+// Everything a subject holds, for a sign-out-everywhere. Also what an
+// operator gets implicitly by deleting the user from users.htpasswd —
+// except that revoking here is immediate, where an htpasswd edit only
+// stops the NEXT login and leaves live access tokens valid until they
+// expire.
+export function revokeAllForSubject(subject) {
+    return db()
+        .prepare('UPDATE mikser_auth_refresh SET revoked_at = ? WHERE subject = ? AND revoked_at IS NULL')
+        .run(Date.now(), subject).changes
+}
+
+export function sweepExpired() {
+    const now = Date.now()
+    const codes = db().prepare('DELETE FROM mikser_auth_codes WHERE expires_at < ?').run(now - 60_000).changes
+    const refresh = db().prepare('DELETE FROM mikser_auth_refresh WHERE expires_at < ?').run(now).changes
+    return { codes, refresh }
+}
+
+// ── self-registered clients ─────────────────────────────────────────────
+
+export function countDynamicClients() {
+    return db().prepare('SELECT COUNT(*) AS n FROM mikser_auth_clients').get().n
+}
+
+export function insertDynamicClient({ clientId, name, redirectUris }) {
+    const createdAt = Date.now()
+    db().prepare(`
+        INSERT INTO mikser_auth_clients (client_id, name, redirect_uris, created_at)
+        VALUES (?, ?, ?, ?)
+    `).run(clientId, name, JSON.stringify(redirectUris), createdAt)
+    return { clientId, name, redirectUris, createdAt }
+}
+
+export function getDynamicClient(clientId) {
+    const row = db().prepare('SELECT * FROM mikser_auth_clients WHERE client_id = ?').get(clientId)
+    if (!row) return null
+    return {
+        clientId:     row.client_id,
+        name:         row.name,
+        redirectUris: JSON.parse(row.redirect_uris),
+        createdAt:    row.created_at,
+        lastUsedAt:   row.last_used_at,
+        dynamic:      true,
+    }
+}
+
+export function touchClient(clientId) {
+    db().prepare('UPDATE mikser_auth_clients SET last_used_at = ? WHERE client_id = ?')
+        .run(Date.now(), clientId)
+}
+
+// DCR has no "get or create" — every registration mints a NEW client_id, so
+// a reinstall, a cleared cache or a second machine each leave another row
+// behind. Prune the ones nobody ever signed in with.
+export function pruneUnusedClients({ olderThanMs }) {
+    return db().prepare(`
+        DELETE FROM mikser_auth_clients
+        WHERE last_used_at IS NULL AND created_at < ?
+    `).run(Date.now() - olderThanMs).changes
+}

package/lib/htpasswd.js

@@ -0,0 +1,253 @@
+import { createHash, timingSafeEqual, randomBytes } from 'node:crypto'
+import { readFile, stat } from 'node:fs/promises'
+import bcrypt from 'bcryptjs'
+
+// Apache-format identity, per ADR-0012.
+//
+//   users.htpasswd    alice:$2y$10$…
+//   groups.htgroup    editors: alice bob
+//
+// Read-only, always. Mikser provisions these files; it never writes them.
+// The moment a running server writes an htpasswd file it has a locking
+// problem and a database it won't admit to.
+
+// One `user:hash` per line. `#` comments and blank lines are skipped, and a
+// hash containing `:` (crypt output never does, but be exact) survives
+// because only the FIRST colon separates.
+export function parseHtpasswd(text) {
+    const users = new Map()
+    for (const raw of text.split('\n')) {
+        const line = raw.trim()
+        if (!line || line.startsWith('#')) continue
+        const i = line.indexOf(':')
+        if (i < 1) continue
+        users.set(line.slice(0, i), line.slice(i + 1))
+    }
+    return users
+}
+
+// `groupname: user1 user2`. Apache allows a group to be repeated across
+// lines, so members accumulate rather than replace.
+export function parseHtgroup(text) {
+    const groups = new Map()
+    for (const raw of text.split('\n')) {
+        const line = raw.trim()
+        if (!line || line.startsWith('#')) continue
+        const i = line.indexOf(':')
+        if (i < 1) continue
+        const name = line.slice(0, i).trim()
+        const members = line.slice(i + 1).trim().split(/\s+/).filter(Boolean)
+        const set = groups.get(name) ?? new Set()
+        for (const m of members) set.add(m)
+        groups.set(name, set)
+    }
+    return groups
+}
+
+// Apache's own MD5 variant ($apr1$). Supported because `htpasswd` emits it
+// by default on some platforms and an operator shouldn't have to care —
+// but it is MD5-based and weak. Prefer bcrypt (`htpasswd -B`).
+function apr1(password, salt) {
+    const pw = Buffer.from(password, 'utf8')
+    const sa = Buffer.from(salt, 'utf8')
+
+    // The inner digest, folded into the outer one password-length bytes at
+    // a time, then one bit per bit of the password length: NUL for a 1-bit,
+    // the password's first byte for a 0-bit. That last step is the part
+    // every reimplementation gets backwards.
+    const inner = createHash('md5').update(pw).update(sa).update(pw).digest()
+
+    const ctx = createHash('md5').update(pw).update('$apr1$').update(sa)
+    for (let i = pw.length; i > 0; i -= 16) ctx.update(inner.subarray(0, Math.min(16, i)))
+    for (let i = pw.length; i !== 0; i >>= 1) {
+        ctx.update(i & 1 ? Buffer.from([0]) : pw.subarray(0, 1))
+    }
+    let final = ctx.digest()
+
+    // 1000 rounds of deliberate slowness — by 2026 standards, not nearly
+    // enough. This format is here for compatibility, not because it's good.
+    for (let i = 0; i < 1000; i++) {
+        const round = createHash('md5')
+        round.update(i & 1 ? pw : final)
+        if (i % 3) round.update(sa)
+        if (i % 7) round.update(pw)
+        round.update(i & 1 ? final : pw)
+        final = round.digest()
+    }
+
+    // Apache's own base64 alphabet, and its own byte order.
+    const ITOA = './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+    let out = ''
+    for (const [a, b, c] of [[0, 6, 12], [1, 7, 13], [2, 8, 14], [3, 9, 15], [4, 10, 5]]) {
+        let v = (final[a] << 16) | (final[b] << 8) | final[c]
+        for (let i = 0; i < 4; i++) { out += ITOA[v & 0x3f]; v >>= 6 }
+    }
+    let v = final[11]
+    for (let i = 0; i < 2; i++) { out += ITOA[v & 0x3f]; v >>= 6 }
+    return `$apr1$${salt}$${out}`
+}
+
+function safeEqual(a, b) {
+    const ba = Buffer.from(a, 'utf8')
+    const bb = Buffer.from(b, 'utf8')
+    return ba.length === bb.length && timingSafeEqual(ba, bb)
+}
+
+// Verify a plaintext password against one htpasswd hash.
+//
+// bcrypt ($2a/$2b/$2y) is the only format here worth trusting; the others
+// exist because `htpasswd` can produce them and an operator's existing file
+// should keep working. $2y is PHP's prefix for a hash that is byte-identical
+// to $2a — bcryptjs doesn't know it, so it's rewritten before comparison.
+export function verifyPassword(hash, password) {
+    if (!hash || typeof password !== 'string') return false
+
+    if (/^\$2[aby]\$/.test(hash)) {
+        try {
+            return bcrypt.compareSync(password, hash.replace(/^\$2y\$/, '$2a$'))
+        } catch {
+            return false
+        }
+    }
+
+    if (hash.startsWith('$apr1$')) {
+        const salt = hash.split('$')[2] ?? ''
+        return safeEqual(hash, apr1(password, salt))
+    }
+
+    if (hash.startsWith('{SHA}')) {
+        const digest = createHash('sha1').update(password, 'utf8').digest('base64')
+        return safeEqual(hash, `{SHA}${digest}`)
+    }
+
+    if (hash.startsWith('$2') || hash.startsWith('$1$') || hash.length === 13) {
+        // MD5-crypt and DES-crypt. Deliberately unsupported rather than
+        // half-supported: both are broken, and silently rejecting is safer
+        // than a subtly wrong implementation that accepts something.
+        return false
+    }
+
+    // A plaintext htpasswd file (Windows/Netware Apache) — compared in
+    // constant time, still a terrible idea, still someone's existing file.
+    return safeEqual(hash, password)
+}
+
+// The store. Files are re-read when their mtime moves, so an operator who
+// edits users.htpasswd sees it take effect on the next request rather than
+// on the next deploy — which is the whole reason identity lives in files.
+export function createIdentityStore({ usersFile, groupsFile, groups = {}, scopes = {}, logger } = {}) {
+    let cache = { users: new Map(), members: new Map(), stamp: null }
+
+    async function mtime(file) {
+        if (!file) return null
+        try {
+            return (await stat(file)).mtimeMs
+        } catch {
+            return null
+        }
+    }
+
+    async function load() {
+        const stamp = `${await mtime(usersFile)}:${await mtime(groupsFile)}`
+        if (stamp === cache.stamp) return cache
+
+        let users = new Map()
+        try {
+            users = parseHtpasswd(await readFile(usersFile, 'utf8'))
+        } catch (err) {
+            if (err.code !== 'ENOENT') throw err
+            logger?.warn?.('auth: no users file at %s — every login will be refused', usersFile)
+        }
+
+        let members = new Map()
+        if (groupsFile) {
+            try {
+                members = parseHtgroup(await readFile(groupsFile, 'utf8'))
+            } catch (err) {
+                if (err.code !== 'ENOENT') throw err
+            }
+        }
+
+        cache = { users, members, stamp }
+        logger?.debug?.('auth: loaded %d user(s), %d group(s)', users.size, members.size)
+        return cache
+    }
+
+    // Is this deployment using capabilities at all?
+    const capabilitiesConfigured = Object.keys(groups).length > 0
+
+    // Which capabilities does this user hold, via group membership?
+    //
+    // With NO capability map configured the answer is null — "not
+    // capability-scoped" — which is exactly what a bare static token
+    // reports, and means the endpoint's own `operations` list is the only
+    // limit. Returning [] instead would grant nothing to anybody, so the
+    // simplest possible setup (a users file and nothing else) would
+    // authenticate people and then refuse them everything.
+    //
+    // Once a map EXISTS, a user whose groups grant nothing gets [] — an
+    // explicit "no verbs", because at that point the operator is using
+    // capabilities and silence means denial rather than absence.
+    function capabilitiesFor(username, members) {
+        if (!capabilitiesConfigured) return null
+        const caps = new Set()
+        for (const [group, users] of members) {
+            if (!users.has(username)) continue
+            for (const cap of groups[group] ?? []) caps.add(cap)
+        }
+        return [...caps]
+    }
+
+    // Which ROWS may this user see? A per-group sift filter, combined with
+    // $or across the groups they belong to — capabilities union, and so does
+    // reach: being in two groups shows you the union of what each group
+    // sees, not the intersection (which would make every extra group make a
+    // user LESS able, and is never what an operator means).
+    //
+    // No matching group with a scope → null, meaning "unscoped": the
+    // endpoint's own query is the only limit. That is the pre-existing
+    // behaviour for every credential that carries no scope.
+    function scopeFor(username, members) {
+        const filters = []
+        for (const [group, users] of members) {
+            if (!users.has(username)) continue
+            const filter = scopes[group]
+            if (filter) filters.push(filter)
+        }
+        if (!filters.length) return null
+        return filters.length === 1 ? filters[0] : { $or: filters }
+    }
+
+    return {
+        async authenticate(username, password) {
+            const { users, members } = await load()
+            const hash = users.get(username)
+            if (!hash) {
+                // Spend the time anyway: returning early on an unknown user
+                // makes username enumeration a timing measurement.
+                verifyPassword('$2a$10$' + randomBytes(16).toString('base64url').slice(0, 53), password)
+                return null
+            }
+            if (!verifyPassword(hash, password)) return null
+            return {
+                subject:      username,
+                groups:       [...members].filter(([, u]) => u.has(username)).map(([g]) => g),
+                capabilities: capabilitiesFor(username, members),
+                scope:        scopeFor(username, members),
+            }
+        },
+        async groupsOf(username) {
+            const { members } = await load()
+            return [...members].filter(([, u]) => u.has(username)).map(([g]) => g)
+        },
+        async capabilitiesOf(username) {
+            const { members } = await load()
+            return capabilitiesFor(username, members)
+        },
+        async scopeOf(username) {
+            const { members } = await load()
+            return scopeFor(username, members)
+        },
+        async reload() { cache = { ...cache, stamp: null }; return load() },
+    }
+}

package/lib/keys.js

@@ -0,0 +1,64 @@
+import { readFile, writeFile, chmod, mkdir } from 'node:fs/promises'
+import path from 'node:path'
+import { generateKeyPair, exportJWK, importJWK, calculateJwkThumbprint } from 'jose'
+
+// The signing key lives in a file in the working folder, alongside the
+// identity it signs for (ADR-0012). ES256 — the most broadly interoperable
+// asymmetric alg for OAuth clients, and small enough that the key file
+// stays readable.
+//
+// A key file rather than a generated-on-boot key because tokens have to
+// survive a restart: regenerating on boot silently invalidates every token
+// the moment the process cycles, which looks exactly like an intermittent
+// auth bug and is miserable to diagnose.
+export const ALG = 'ES256'
+
+export async function loadOrCreateKey({ keyFile, logger }) {
+    let stored
+    try {
+        stored = JSON.parse(await readFile(keyFile, 'utf8'))
+    } catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw new Error(`auth: key file ${keyFile} is unreadable or not JSON — ${err.message}`)
+        }
+    }
+
+    if (stored) {
+        const privateKey = await importJWK(stored.privateJwk, ALG)
+        const publicKey  = await importJWK(stored.publicJwk, ALG)
+        return { privateKey, publicKey, publicJwk: stored.publicJwk, kid: stored.kid }
+    }
+
+    const { publicKey, privateKey } = await generateKeyPair(ALG, { extractable: true })
+    const privateJwk = await exportJWK(privateKey)
+    const publicJwk  = await exportJWK(publicKey)
+    const kid = await calculateJwkThumbprint(publicJwk)
+    publicJwk.kid = kid
+    publicJwk.alg = ALG
+    publicJwk.use = 'sig'
+
+    await mkdir(path.dirname(keyFile), { recursive: true })
+    await writeFile(keyFile, JSON.stringify({ kid, alg: ALG, privateJwk, publicJwk }, null, 2), { mode: 0o600 })
+    // writeFile's mode is only applied on create; be explicit for the case
+    // where an empty file already existed with looser permissions.
+    await chmod(keyFile, 0o600).catch(() => {})
+
+    logger?.warn?.(
+        'auth: generated a new signing key at %s (kid=%s). Back it up and keep it out of version control — ' +
+        'losing it invalidates every issued token; leaking it lets anyone mint one.',
+        keyFile, kid)
+
+    return { privateKey, publicKey, publicJwk, kid }
+}
+
+// The JWKS document an OAuth client fetches to verify our tokens. Public
+// half only — if a private component ever appears here, that is the whole
+// system compromised, so it is asserted rather than trusted.
+export function jwks({ publicJwk }) {
+    for (const secret of ['d', 'p', 'q', 'dp', 'dq', 'qi', 'k']) {
+        if (secret in publicJwk) {
+            throw new Error(`auth: refusing to publish a JWKS containing the private component "${secret}"`)
+        }
+    }
+    return { keys: [publicJwk] }
+}

package/lib/login-page.js

@@ -0,0 +1,116 @@
+const escapeHtml = (value) => String(value)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+// The sign-in page.
+//
+// Deliberately identical to WhiteBox's — same layout, same type scale, same
+// tokens, same pending state — because mikser and WhiteBox are the same
+// company's products and a person who administers both should not have to
+// wonder whether they are on the right one. The mark is the only difference.
+//
+// Two things the page must say, and WhiteBox learned the second the hard way:
+//
+//   appName — WHICH deployment. A page showing only a logo could be any
+//             mikser, or a convincing copy of one.
+//   client  — WHO gets your access. Without it, signing in to your own site
+//             and handing an agent your permissions looked identical.
+export function loginPage({ params, client, appName, logoUrl, error }) {
+    const hidden = Object.entries(params)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`)
+        .join('\n')
+
+    const subtitle = client
+        ? `<p class="sub">to give <strong>${escapeHtml(client.name || client.clientId)}</strong> access</p>`
+        : ''
+
+    const notice = error ? `<p class="err">${escapeHtml(error)}</p>` : ''
+
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Sign in</title>
+<style>
+/* Values measured off WhiteBox's running console login, not copied from its
+   stylesheet fallbacks — its PrimeVue theme overrides --accent, --text and
+   --radius at runtime, so the source would have produced a page that looked
+   adjacent to it rather than identical.
+   Light only, also deliberately: WhiteBox's login stays light under
+   prefers-color-scheme: dark, so a dark block here would create exactly the
+   mismatch it looks like it prevents. */
+:root{
+  --bg:#f1f5f9; --panel:#fff; --border:#e2e8f0; --border-2:#cbd5e1;
+  --text:#334155; --text-strong:#0f172a; --accent:#09090b;
+  --radius:6px; --shadow:0 6px 18px rgba(15,23,42,.10);
+}
+*{box-sizing:border-box}
+body{
+  margin:0; min-height:100vh; display:grid; place-items:center; background:var(--bg);
+  color:var(--text); font:14px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+}
+form{
+  width:320px; padding:32px; display:flex; flex-direction:column; align-items:center; gap:10px;
+  background:var(--panel); border:1px solid var(--border);
+  border-radius:var(--radius); box-shadow:var(--shadow);
+}
+img{width:36px;height:36px;margin-bottom:2px}
+h1{font-size:17px;font-weight:700;margin:0 0 6px;color:var(--text-strong)}
+.sub{margin:-4px 0 4px;font-size:13px;text-align:center;opacity:.8}
+.sub strong{color:var(--text-strong);font-weight:600}
+.err{
+  width:100%; margin:0 0 2px; padding:8px 10px; border-radius:8px; font-size:13px;
+  background:#fef2f2; border:1px solid #fecaca; color:#b91c1c; text-align:center;
+}
+/* 8px on the fields against the card's 6px is WhiteBox's own combination, not a slip. */
+input{
+  width:100%; padding:9px 10px; border:1px solid var(--border-2); border-radius:8px;
+  font-size:14px; background:var(--panel); color:var(--text);
+}
+input:focus{outline:2px solid color-mix(in srgb,var(--accent) 25%,transparent);border-color:var(--accent)}
+button{
+  width:100%; margin-top:6px; padding:9px; border:none; border-radius:8px;
+  background:var(--accent); color:#fff; font-size:14px; font-weight:500; cursor:pointer;
+}
+button:hover{opacity:.92}
+button[disabled]{opacity:.65;cursor:default}
+</style>
+</head><body>
+<form method="post">
+${hidden}
+<img src="${escapeHtml(logoUrl)}" alt="" onerror="this.remove()">
+<h1>Sign in${appName ? ` to ${escapeHtml(appName)}` : ''}</h1>
+${subtitle}
+${notice}
+<!-- autocomplete hints are load-bearing: without them a password manager
+     guesses, and a saved credential for a different app on the same host
+     gets filled instead. -->
+<input type="text" name="username" placeholder="Username" autocomplete="username" required autofocus>
+<input type="password" name="password" placeholder="Password" autocomplete="current-password" required>
+<button type="submit">Sign in</button>
+</form>
+<!-- Feedback while the POST is in flight, which is longer than it looks:
+     bcrypt is deliberately slow, that being the point of a KDF, plus a round
+     trip and a redirect. Without this the button does not move, the page
+     looks inert, and the honest reading is "nothing happened" — so people
+     click again.
+     Progressive enhancement: with JS blocked the form still submits exactly
+     as before, it just has no pending state. -->
+<script>
+(function () {
+  var form = document.querySelector('form')
+  var button = form.querySelector('button')
+  form.addEventListener('submit', function () {
+    // Runs AFTER the form data is collected, so disabling here cannot drop a
+    // field. The button carries no name or value, so it has nothing of its
+    // own to lose either.
+    button.disabled = true
+    button.textContent = 'Signing in…'
+    form.setAttribute('aria-busy', 'true')
+  })
+})()
+</script>
+</body></html>`
+}
+
+export { escapeHtml }

package/lib/pkce.js

@@ -0,0 +1,23 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+
+// PKCE (RFC 7636), S256 only. `plain` exists in the spec for clients that
+// cannot compute SHA-256, which describes nothing that will ever talk to a
+// mikser build server — and accepting it would let anyone who captured the
+// authorization request replay the code without ever holding the verifier.
+
+const base64url = (buf) => buf.toString('base64url')
+
+export function challengeFromVerifier(verifier) {
+    return base64url(createHash('sha256').update(verifier).digest())
+}
+
+export function verifyPkce(verifier, challenge) {
+    if (!verifier || !challenge) return false
+    const a = Buffer.from(challengeFromVerifier(verifier), 'utf8')
+    const b = Buffer.from(challenge, 'utf8')
+    return a.length === b.length && timingSafeEqual(a, b)
+}
+
+// Opaque, unguessable, and URL-safe: authorization codes and refresh tokens
+// are bearer strings, so entropy is the only thing protecting them.
+export const opaqueToken = () => base64url(randomBytes(32))