mikser-io-auth 0.10.1 → 0.12.0

package/README.md

@@ -131,8 +131,33 @@ lazily; plugin order doesn't matter, and forgetting to add `identity` to
     auth.key            {"kid":…,"privateJwk":…}   generated on first run, 0600
 ```
 
-Keep `auth.key` out of version control — losing it invalidates every issued
-token; leaking it lets anyone mint one.
+`auth.key` is ONE key for the whole deployment, not one per user — every token
+for every subject is signed with it. It is written `0600` on first run and
+never rewritten.
+
+**Back it up.** Nothing can reproduce it. If it goes missing, the next start
+generates a new one and everyone who was signed in has to authorise again — and
+mikser says so rather than leaving you to infer it from a wave of 401s: the
+`kid` is recorded in the durable store, and one that no longer matches raises
+the `auth-signing-key-changed` fault, which appears in `mikser_ping`. Restoring
+the file from backup is what brings those sessions back; leaving it means every
+client re-registers.
+
+Whether to commit it is **your call, and mikser does not touch your
+`.gitignore`**. In a private repo, committing it is a legitimate backup for the
+one file nothing else can reproduce, and it is written once so it adds no churn.
+Against that, git history does not forget: if the repo's audience ever widens,
+rotating the key does not remove the old one from history. Weigh those for your
+own setup — the engine is in no position to.
+
+(The engine does gitignore its own `mikser.data.sqlite`, for a different reason
+that holds regardless: that file is rewritten on every write, so committing it
+means a binary diff and a conflict every time.)
+
+Keep it a file. A single instance is safer with the key on disk, where it never
+leaves the box. Only a multi-instance deployment behind a load balancer needs it
+shared — instances signing with different keys reject each other's tokens, which
+from a client looks exactly like random expiry.
 
 ### Endpoints
 

package/index.js

@@ -1,8 +1,8 @@
 import path from 'node:path'
-import { registerRoute, anyOf } from 'mikser-io'
+import { registerRoute, anyOf, useDurableDatabase } from 'mikser-io'
 
 import { createIdentityStore, parseHtpasswd, parseHtgroup, verifyPassword } from './lib/htpasswd.js'
-import { loadOrCreateKey, jwks, ALG } from './lib/keys.js'
+import { loadOrCreateKey, checkKeyContinuity, jwks, ALG } from './lib/keys.js'
 import { issueToken, createTokenVerifier } from './lib/tokens.js'
 import { basic, jwt } from './lib/verifiers.js'
 import { redirectUriAllowed, validateRedirectUri, registerDynamicClient } from './lib/clients.js'
@@ -86,6 +86,17 @@ export function auth(options = {}) {
     }
 
     const plugin = ({ runtime, onLoad, onLoaded, useLogger }) => {
+        // Deliberately NOT in onLoad below.
+        //
+        // The durable store opens at onLoaded, so this check ran against no
+        // database at all and returned null — which the call site ignored.
+        // A guard against a silent failure that fails silently itself is
+        // worse than none: it reads as covered.
+        onLoaded(async () => {
+            if (!state?.key?.kid) return
+            await checkKeyContinuity({ kid: state.key.kid, db: useDurableDatabase(), logger: state.logger })
+        })
+
         onLoad(async () => {
             const logger = useLogger()
             // Published so any transport can say which role is acting and
@@ -200,7 +211,7 @@ export function auth(options = {}) {
             // for a build tool — the checks that matter (expiry, single use)
             // are enforced on read, not by the sweep.
             try {
-                const swept = grants.sweepExpired()
+                const swept = await grants.sweepExpired()
                 if (swept.codes || swept.refresh) {
                     logger?.debug?.('auth: swept %d expired code(s), %d refresh token(s)',
                         swept.codes, swept.refresh)
@@ -211,7 +222,7 @@ export function auth(options = {}) {
                 // signed in with are dropped; a config-declared client is
                 // never touched, because it lives in config, not this table.
                 if (pruneClientsAfterDays) {
-                    const pruned = grants.pruneUnusedClients({
+                    const pruned = await grants.pruneUnusedClients({
                         olderThanMs: pruneClientsAfterDays * 24 * 60 * 60 * 1000,
                     })
                     if (pruned) logger?.info?.('auth: pruned %d unused client registration(s)', pruned)

package/lib/clients.js

@@ -82,7 +82,7 @@ export function validateRedirectUri(value) {
 // What is at risk is table volume, not access. `maxClients` bounds it in the
 // durable place — a rate limiter lives in process memory and does not survive
 // a restart, while rows do.
-export function registerDynamicClient({ name, redirectUris, maxClients, store }) {
+export async function registerDynamicClient({ name, redirectUris, maxClients, store }) {
     if (!Array.isArray(redirectUris) || !redirectUris.length) {
         throw new RegistrationError('invalid_redirect_uri', 'redirect_uris must be a non-empty array')
     }
@@ -96,7 +96,7 @@ export function registerDynamicClient({ name, redirectUris, maxClients, store })
         }
     }
 
-    if (maxClients != null && store.countDynamicClients() >= maxClients) {
+    if (maxClients != null && await store.countDynamicClients() >= maxClients) {
         throw new RegistrationError('invalid_client_metadata',
             'this server is not accepting new client registrations right now')
     }

package/lib/grants.js

@@ -1,117 +1,124 @@
-import { registerSchema, useDatabase } from 'mikser-io'
+import { registerMigrations, useDurableDatabase } 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).
+// bookkeeping.
+//
+// DURABLE, which since 9.56 means a database of its own rather than a flag on
+// a table in the cache. A registered OAuth client and its refresh token exist
+// only because a human completed a sign-in once, and no file can reproduce
+// them — so they live in `mikser.data.sqlite`, which the cache wipe cannot
+// reach and `--clear` does not touch. Upgrading mikser no longer signs
+// everyone out.
+//
+// Migrations rather than an idempotent CREATE, because a durable table is the
+// only kind that is never recreated: `CREATE TABLE IF NOT EXISTS` can never
+// give it a column it has grown, and it goes stale silently.
 //
 // 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
-    );
-`, {
-    // Durable: these tables are not derived from anything on disk.
-    //
-    // The engine wipes its database whenever the schema version or the
-    // config checksum changes — an upgrade, or any deploy that edits
-    // mikser.config.js. That is correct for a cache the files can rebuild,
-    // and wrong here: a registered OAuth client and its refresh token exist
-    // only because a human completed a sign-in once. Losing them logs every
-    // connected agent out, and the operator's first sign of it is being
-    // asked to authorize again after an unrelated deploy.
-    //
-    // Codes are 60s and swept anyway; they ride along because they share the
-    // schema, and a stale one is rejected on expiry rather than trusted.
-    durable: true,
-})
-
-const db = () => useDatabase().handle
-
-export function createCode({ clientId, subject, redirectUri, codeChallenge, scope, ttlSec = 60 }) {
+registerMigrations('auth', [
+    {
+        name: '001-grants',
+        up: async (knex) => {
+            await knex.schema.createTable('mikser_auth_codes', (table) => {
+                table.string('code').primary()
+                table.string('client_id').notNullable()
+                table.string('subject').notNullable()
+                table.text('redirect_uri').notNullable()
+                table.text('code_challenge').notNullable()
+                table.text('scope').notNullable().defaultTo('')
+                table.bigInteger('expires_at').notNullable()
+                table.bigInteger('used_at')
+                table.index(['expires_at'], 'idx_mikser_auth_codes_expiry')
+            })
+
+            await knex.schema.createTable('mikser_auth_refresh', (table) => {
+                table.string('token').primary()
+                table.string('client_id').notNullable()
+                table.string('subject').notNullable()
+                table.bigInteger('expires_at').notNullable()
+                table.bigInteger('revoked_at')
+                table.index(['subject'], 'idx_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.
+            await knex.schema.createTable('mikser_auth_clients', (table) => {
+                table.string('client_id').primary()
+                table.string('name').notNullable()
+                table.text('redirect_uris').notNullable()
+                table.bigInteger('created_at').notNullable()
+                table.bigInteger('last_used_at')
+            })
+        },
+    },
+    {
+        // Which signing key was in force. A history rather than one row: when
+        // it changes, the useful sentence names both, and "was X, now Y" is
+        // what tells an operator whether they replaced it on purpose.
+        //
+        // Appended as its own migration rather than edited into 001 — a
+        // migration that has run is permanent, and changing it would mean it
+        // never runs against the databases that already applied it.
+        name: '002-signing-key',
+        up: async (knex) => {
+            await knex.schema.createTable('mikser_auth_signing_key', (table) => {
+                table.string('kid').primary()
+                table.string('alg').notNullable()
+                table.bigInteger('recorded_at').notNullable()
+                table.index(['recorded_at'], 'idx_mikser_auth_signing_key_recorded')
+            })
+        },
+    },
+])
+
+const db = () => useDurableDatabase()
+
+export async 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)
+    await db()('mikser_auth_codes').insert({
+        code, client_id: clientId, subject, redirect_uri: redirectUri,
+        code_challenge: codeChallenge, scope: scope ?? '', expires_at: Date.now() + ttlSec * 1000,
+    })
     return code
 }
 
-export function getCode(code) {
-    return db().prepare('SELECT * FROM mikser_auth_codes WHERE code = ?').get(code)
+export async function getCode(code) {
+    return db()('mikser_auth_codes').where({ code }).first()
 }
 
 // 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 async function redeemCode(code) {
+    const changed = await db()('mikser_auth_codes')
+        .where({ code }).whereNull('used_at').update({ used_at: Date.now() })
+    return changed === 1
 }
 
-export function createRefreshToken({ clientId, subject, ttlSec }) {
+export async 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)
+    await db()('mikser_auth_refresh').insert({
+        token, client_id: clientId, subject, expires_at: Date.now() + ttlSec * 1000,
+    })
     return token
 }
 
-export function getRefreshToken(token) {
-    return db().prepare('SELECT * FROM mikser_auth_refresh WHERE token = ?').get(token)
+export async function getRefreshToken(token) {
+    return db()('mikser_auth_refresh').where({ token }).first()
 }
 
 // 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
+export async function revokeRefreshToken(token) {
+    const changed = await db()('mikser_auth_refresh')
+        .where({ token }).whereNull('revoked_at').update({ revoked_at: Date.now() })
+    return changed === 1
 }
 
 // Everything a subject holds, for a sign-out-everywhere. Also what an
@@ -119,36 +126,35 @@ export function revokeRefreshToken(token) {
 // 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 async function revokeAllForSubject(subject) {
+    return db()('mikser_auth_refresh')
+        .where({ subject }).whereNull('revoked_at').update({ revoked_at: Date.now() })
 }
 
-export function sweepExpired() {
+export async 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
+    const codes = await db()('mikser_auth_codes').where('expires_at', '<', now - 60_000).delete()
+    const refresh = await db()('mikser_auth_refresh').where('expires_at', '<', now).delete()
     return { codes, refresh }
 }
 
 // ── self-registered clients ─────────────────────────────────────────────
 
-export function countDynamicClients() {
-    return db().prepare('SELECT COUNT(*) AS n FROM mikser_auth_clients').get().n
+export async function countDynamicClients() {
+    const [{ n }] = await db()('mikser_auth_clients').count({ n: '*' })
+    return Number(n)
 }
 
-export function insertDynamicClient({ clientId, name, redirectUris }) {
+export async 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)
+    await db()('mikser_auth_clients').insert({
+        client_id: clientId, name, redirect_uris: JSON.stringify(redirectUris), created_at: createdAt,
+    })
     return { clientId, name, redirectUris, createdAt }
 }
 
-export function getDynamicClient(clientId) {
-    const row = db().prepare('SELECT * FROM mikser_auth_clients WHERE client_id = ?').get(clientId)
+export async function getDynamicClient(clientId) {
+    const row = await db()('mikser_auth_clients').where({ client_id: clientId }).first()
     if (!row) return null
     return {
         clientId:     row.client_id,
@@ -160,17 +166,14 @@ export function getDynamicClient(clientId) {
     }
 }
 
-export function touchClient(clientId) {
-    db().prepare('UPDATE mikser_auth_clients SET last_used_at = ? WHERE client_id = ?')
-        .run(Date.now(), clientId)
+export async function touchClient(clientId) {
+    await db()('mikser_auth_clients').where({ client_id: clientId }).update({ last_used_at: Date.now() })
 }
 
 // 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
+export async function pruneUnusedClients({ olderThanMs }) {
+    return db()('mikser_auth_clients')
+        .whereNull('last_used_at').where('created_at', '<', Date.now() - olderThanMs).delete()
 }

package/lib/keys.js

@@ -11,6 +11,18 @@ import { generateKeyPair, exportJWK, importJWK, calculateJwkThumbprint } from 'j
 // 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.
+//
+// Deliberately NOT added to .gitignore, unlike the engine's durable database.
+// That file is rewritten on every write, so committing it means a binary diff
+// and a conflict every time — a reason that holds whatever it contains. This
+// one is written once and never again, so there is no such reason, and what
+// would be left is a guess about the operator's threat model that the engine
+// is in no position to make. Committing it to a private repo is a legitimate
+// choice and a real backup; keeping it out is also legitimate. What is not
+// legitimate is mikser editing a .gitignore to enforce either.
+//
+// Losing it is the failure that actually happens — a rebuilt container, an
+// `rm -rf` — and checkKeyContinuity below is what makes that sayable.
 export const ALG = 'ES256'
 
 export async function loadOrCreateKey({ keyFile, logger }) {
@@ -51,6 +63,52 @@ export async function loadOrCreateKey({ keyFile, logger }) {
     return { privateKey, publicKey, publicJwk, kid }
 }
 
+// Has the signing key changed since last time?
+//
+// Creating a key logs a warning either way, and on a first run that is routine
+// — so the alarming case and the normal one produce the same line, and the
+// difference only shows up later as every agent being asked to authorise
+// again. That is the shape of failure this whole codebase keeps finding: two
+// states, one output.
+//
+// The kid is recorded in the durable store, which survives the cache wipe that
+// the key file survives, so the two stay in step. A recorded kid that no
+// longer matches means the file was replaced or lost — and every access and
+// refresh token ever issued under the old one is now unverifiable.
+//
+// Returns null when there is nothing to compare against, which is not the same
+// as "unchanged" and must not be reported as such.
+export async function checkKeyContinuity({ kid, db, logger }) {
+    if (!db || !kid) return null
+    try {
+        const [previous] = await db(SIGNING_KEY_TABLE).orderBy('recorded_at', 'desc').limit(1)
+
+        if (!previous) {
+            // First run, or the first boot after this check was added. Either
+            // way there is no prior claim to contradict.
+            await db(SIGNING_KEY_TABLE).insert({ kid, alg: ALG, recorded_at: Date.now() })
+            return { recorded: true }
+        }
+        if (previous.kid === kid) return { unchanged: true }
+
+        await db(SIGNING_KEY_TABLE).insert({ kid, alg: ALG, recorded_at: Date.now() })
+        logger?.error?.({ code: 'auth-signing-key-changed' },
+            'The signing key changed (was %s, now %s). Every access and refresh token issued under the old key '
+            + 'is unverifiable, so everyone who was signed in must authorise again. If %s was not replaced on '
+            + 'purpose it was LOST — restoring it from backup is what brings those sessions back; leaving it '
+            + 'means every client re-registers.',
+            previous.kid, kid, 'auth.key')
+        return { changed: true, previous: previous.kid }
+    } catch (err) {
+        logger?.error?.({ code: 'auth-signing-key-changed' },
+            'Could not check whether the signing key changed: %s. A silently replaced key looks exactly like '
+            + 'tokens expiring at random, so this check not running is worth knowing about.', err.message)
+        return null
+    }
+}
+
+export const SIGNING_KEY_TABLE = 'mikser_auth_signing_key'
+
 // 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.

package/lib/routes.js

@@ -75,7 +75,7 @@ export function mountRoutes(router, ctx) {
     })
 
     // ── discovery ────────────────────────────────────────────────────────
-    router.get('/jwks.json', (req, res) => {
+    router.get('/jwks.json', async (req, res) => {
         res.json(jwks({ publicJwk: ready().key.publicJwk }))
     })
 
@@ -87,8 +87,8 @@ export function mountRoutes(router, ctx) {
     // error directly rather than redirecting. Redirecting to an unvalidated
     // URI is itself the vulnerability — an open redirect through the
     // authorization endpoint.
-    function resolveClient(params, res) {
-        const client = params.client_id ? grants.getDynamicClient(params.client_id) : null
+    async function resolveClient(params, res) {
+        const client = params.client_id ? await grants.getDynamicClient(params.client_id) : null
         if (!client) { res.status(400).send('Unknown client_id'); return null }
         if (!redirectUriAllowed(client, params.redirect_uri)) {
             res.status(400).send('redirect_uri is not registered for this client')
@@ -117,9 +117,9 @@ export function mountRoutes(router, ctx) {
         return true
     }
 
-    router.get('/authorize', (req, res) => {
+    router.get('/authorize', async (req, res) => {
         const params = authParams(req.query)
-        const client = resolveClient(params, res)
+        const client = await resolveClient(params, res)
         if (!client) return
         if (!checkRequest(params, res)) return
         res.type('html').send(loginPage({ params, client, appName: nameOf(req), logoUrl }))
@@ -127,7 +127,7 @@ export function mountRoutes(router, ctx) {
 
     router.post('/authorize', async (req, res) => {
         const params = authParams(req.body)
-        const client = resolveClient(params, res)
+        const client = await resolveClient(params, res)
         if (!client) return
         if (!checkRequest(params, res)) return
 
@@ -149,14 +149,14 @@ export function mountRoutes(router, ctx) {
         // params.scope is what the CLIENT asked for. It is recorded and never
         // trusted: the token's real scope is recomputed from the files at
         // issue time, so a forged request cannot mint itself more access.
-        const code = grants.createCode({
+        const code = await grants.createCode({
             clientId: client.clientId, subject: principal.subject,
             redirectUri: params.redirect_uri, codeChallenge: params.code_challenge,
             scope: params.scope, ttlSec: CODE_TTL_SEC,
         })
         // Marks the registration as live, so pruning can tell a client
         // somebody actually uses from one left behind by a reinstall.
-        grants.touchClient(client.clientId)
+        await grants.touchClient(client.clientId)
         logger?.info?.('auth: authorization granted to %j for %j', client.clientId, principal.subject)
 
         const url = new URL(params.redirect_uri)
@@ -190,7 +190,7 @@ export function mountRoutes(router, ctx) {
             scope:        capabilities.join(' '),
         }
         if (withRefresh) {
-            body.refresh_token = grants.createRefreshToken({
+            body.refresh_token = await grants.createRefreshToken({
                 clientId, subject, ttlSec: REFRESH_TTL_SEC,
             })
             // Say that unattended renewal was granted, not just hand over the
@@ -207,7 +207,7 @@ export function mountRoutes(router, ctx) {
 
     async function authorizationCodeGrant(req, res) {
         const { code, redirect_uri: redirectUri, code_verifier: verifier, client_id: clientId } = req.body
-        const row = code && grants.getCode(code)
+        const row = code && await grants.getCode(code)
         if (!row) return res.status(400).json({ error: 'invalid_grant' })
         if (row.used_at || row.expires_at < Date.now()) {
             return res.status(400).json({ error: 'invalid_grant' })
@@ -223,14 +223,14 @@ export function mountRoutes(router, ctx) {
         }
         // Single-use, decided by the UPDATE itself — two simultaneous
         // redemptions both pass every check above, and only one wins here.
-        if (!grants.redeemCode(code)) return res.status(400).json({ error: 'invalid_grant' })
+        if (!await grants.redeemCode(code)) return res.status(400).json({ error: 'invalid_grant' })
 
         return issueTokens(res, { clientId: row.client_id, subject: row.subject, withRefresh: true })
     }
 
     async function refreshGrant(req, res) {
         const { refresh_token: token, client_id: clientId } = req.body
-        const row = token && grants.getRefreshToken(token)
+        const row = token && await grants.getRefreshToken(token)
         if (!row) return res.status(400).json({ error: 'invalid_grant' })
         if (row.revoked_at || row.expires_at < Date.now()) {
             return res.status(400).json({ error: 'invalid_grant' })
@@ -240,7 +240,7 @@ export function mountRoutes(router, ctx) {
         // Revoke BEFORE minting the replacement: losing this race means
         // having created nothing, rather than leaving a valid token that
         // nobody holds.
-        if (!grants.revokeRefreshToken(token)) return res.status(400).json({ error: 'invalid_grant' })
+        if (!await grants.revokeRefreshToken(token)) return res.status(400).json({ error: 'invalid_grant' })
 
         // Recomputed from the files, not carried over from the old token —
         // this is what makes an htgroup edit take effect on the next refresh
@@ -290,7 +290,7 @@ export function mountRoutes(router, ctx) {
     {
         const recent = new Map()   // ip -> timestamps[]
 
-        router.post('/register', (req, res) => {
+        router.post('/register', async (req, res) => {
             const now = Date.now()
             const ip = req.ip || 'unknown'
             const hits = (recent.get(ip) || []).filter(t => now - t < windowMs)
@@ -313,7 +313,7 @@ export function mountRoutes(router, ctx) {
             }
 
             try {
-                const row = registerDynamicClient({
+                const row = await registerDynamicClient({
                     name:         req.body?.client_name,
                     redirectUris: req.body?.redirect_uris,
                     maxClients,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mikser-io-auth",
-  "version": "0.10.1",
-  "description": "Authentication for mikser-io: an OAuth 2.1 authorization server (self-registering clients, authorization code + PKCE, refresh rotation) and HTTP Basic / JWT verifiers over Apache-format htpasswd and htgroup files in the working folder. Implements the ADR-0012 verifier contract, so it plugs in wherever a static token does — api, mcp, forms.",
+  "version": "0.12.0",
+  "description": "Authentication for mikser-io: an OAuth 2.1 authorization server (self-registering clients, authorization code + PKCE, refresh rotation) and HTTP Basic / JWT verifiers over Apache-format htpasswd and htgroup files in the working folder. Implements the ADR-0012 verifier contract, so it plugs in wherever a static token does \u2014 api, mcp, forms.",
   "main": "index.js",
   "type": "module",
   "scripts": {
@@ -26,7 +26,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-auth#readme",
   "peerDependencies": {
-    "mikser-io": "^9.50.0"
+    "mikser-io": "^9.57.0"
   },
   "dependencies": {
     "bcryptjs": "^3.0.0",

package/test/authorize.test.js

@@ -6,7 +6,7 @@ import path from 'node:path'
 import { createHash, randomBytes } from 'node:crypto'
 import bcrypt from 'bcryptjs'
 
-import { runtime } from 'mikser-io'
+import { runtime , closeDurableDatabase } from 'mikser-io'
 import { auth } from '../index.js'
 
 // Boot the plugin against a REAL express app and a REAL mikser database, by
@@ -98,6 +98,8 @@ before(async () => {
 })
 
 after(async () => {
+    // knex holds a pool reaper timer; without this the runner never exits.
+    await closeDurableDatabase()
     await new Promise(r => server?.close(r))
     await rm(dir, { recursive: true, force: true })
 })

package/test/clients.test.js

@@ -6,78 +6,78 @@ import {
     registerDynamicClient, RegistrationError,
 } from '../lib/clients.js'
 
-describe('redirectUriAllowed', () => {
+describe('redirectUriAllowed', async () => {
     const client = { redirectUris: ['http://127.0.0.1/callback', 'https://agent.example.com/cb'] }
 
-    it('matches exactly', () => {
+    it('matches exactly', async () => {
         assert.equal(redirectUriAllowed(client, 'https://agent.example.com/cb'), true)
         assert.equal(redirectUriAllowed(client, 'https://agent.example.com/other'), false)
     })
 
-    it('ignores the port on loopback (RFC 8252 §7.3) — native agents bind an ephemeral one', () => {
+    it('ignores the port on loopback (RFC 8252 §7.3) — native agents bind an ephemeral one', async () => {
         assert.equal(redirectUriAllowed(client, 'http://127.0.0.1:49821/callback'), true)
         assert.equal(redirectUriAllowed(client, 'http://127.0.0.1:1/callback'), true)
     })
 
-    it('does not let the loopback exception loosen anything else', () => {
+    it('does not let the loopback exception loosen anything else', async () => {
         assert.equal(redirectUriAllowed(client, 'http://127.0.0.1:49821/evil'), false, 'path must still match')
         assert.equal(redirectUriAllowed(client, 'https://127.0.0.1:49821/callback'), false, 'scheme must still match')
         assert.equal(redirectUriAllowed(client, 'http://evil.example.com:49821/callback'), false)
         assert.equal(redirectUriAllowed(client, 'https://agent.example.com:8443/cb'), false, 'non-loopback keeps its port')
     })
 
-    it('refuses junk without throwing', () => {
+    it('refuses junk without throwing', async () => {
         assert.equal(redirectUriAllowed(client, undefined), false)
         assert.equal(redirectUriAllowed(client, 'not-a-uri'), false)
     })
 })
 
-describe('validateRedirectUri', () => {
-    it('allows https anywhere and http only on loopback', () => {
+describe('validateRedirectUri', async () => {
+    it('allows https anywhere and http only on loopback', async () => {
         assert.equal(validateRedirectUri('https://agent.example.com/cb'), null)
         assert.equal(validateRedirectUri('http://127.0.0.1:1234/cb'), null)
         assert.equal(validateRedirectUri('http://localhost/cb'), null)
         assert.match(validateRedirectUri('http://evil.example.com/cb'), /https, except on loopback/)
     })
 
-    it('refuses a fragment and an unknown scheme', () => {
+    it('refuses a fragment and an unknown scheme', async () => {
         assert.match(validateRedirectUri('https://a/cb#x'), /fragment/)
         assert.match(validateRedirectUri('ftp://a/cb'), /is not allowed/)
     })
 })
 
-describe('registerDynamicClient bounds', () => {
+describe('registerDynamicClient bounds', async () => {
     const fakeStore = (count = 0) => ({
         countDynamicClients: () => count,
         insertDynamicClient: (c) => ({ ...c, createdAt: 1 }),
     })
 
-    it('caps the number of redirect URIs', () => {
+    it('caps the number of redirect URIs', async () => {
         const many = Array.from({ length: 11 }, (_, i) => `https://a/cb${i}`)
-        assert.throws(() => registerDynamicClient({ redirectUris: many, store: fakeStore() }),
-                      (e) => e instanceof RegistrationError && e.code === 'invalid_redirect_uri')
+        await assert.rejects(() => registerDynamicClient({ redirectUris: many, store: fakeStore() }),
+                             (e) => e instanceof RegistrationError && e.code === 'invalid_redirect_uri')
     })
 
-    it('caps the name, because it renders on the sign-in page', () => {
-        const out = registerDynamicClient({
+    it('caps the name, because it renders on the sign-in page', async () => {
+        const out = await registerDynamicClient({
             name: 'x'.repeat(500), redirectUris: ['https://a/cb'], store: fakeStore(),
         })
         assert.equal(out.name.length, 80)
     })
 
-    it('refuses once the table is full — the durable bound, not the rate limiter', () => {
+    it('refuses once the table is full — the durable bound, not the rate limiter', async () => {
         // The per-IP limiter lives in process memory and does not survive a
         // restart; rows do. This is what actually bounds the table.
-        assert.throws(
+        await assert.rejects(
             () => registerDynamicClient({ redirectUris: ['https://a/cb'], maxClients: 10, store: fakeStore(10) }),
             (e) => e.code === 'invalid_client_metadata',
         )
     })
 
-    it('mints a distinct client_id every time — RFC 7591 has no get-or-create', () => {
+    it('mints a distinct client_id every time — RFC 7591 has no get-or-create', async () => {
         const store = fakeStore()
-        const a = registerDynamicClient({ redirectUris: ['https://a/cb'], store })
-        const b = registerDynamicClient({ redirectUris: ['https://a/cb'], store })
+        const a = await registerDynamicClient({ redirectUris: ['https://a/cb'], store })
+        const b = await registerDynamicClient({ redirectUris: ['https://a/cb'], store })
         assert.notEqual(a.clientId, b.clientId)
     })
 })

package/test/signing-key.test.js

@@ -0,0 +1,105 @@
+// The signing key: kept out of the repo, and never replaced quietly.
+//
+// It is ONE key for the whole deployment — every token for every user is
+// signed with it. Losing it invalidates all of them at once; leaking it lets
+// anyone mint one for any subject. Both failures are silent by default, which
+// is what these two guards are for.
+
+import { describe, it, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, rm, mkdir, readFile, writeFile, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import knexFactory from 'knex'
+
+import { runMigrations } from 'mikser-io'
+import { loadOrCreateKey, checkKeyContinuity } from '../lib/keys.js'
+import '../lib/grants.js'   // registers the auth migrations
+
+let dir, db
+const quiet = { warn() {}, info() {}, notice() {}, error() {} }
+const loud = () => { const seen = []; return { warn() {}, info() {}, notice() {}, error: (o) => seen.push(o), seen } }
+
+beforeEach(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-key-'))
+    db = knexFactory({ client: 'better-sqlite3', connection: { filename: path.join(dir, 'd.sqlite') }, useNullAsDefault: true })
+    await runMigrations(db, quiet)
+})
+afterEach(async () => {
+    await db.destroy()
+    await rm(dir, { recursive: true, force: true })
+})
+
+const keyFile = () => path.join(dir, 'auth.key')
+const gitignore = () => path.join(dir, '.gitignore')
+
+describe('writing the key', () => {
+    it('writes it 0600', async () => {
+        await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        assert.equal((await stat(keyFile())).mode & 0o777, 0o600)
+    })
+
+    it('leaves .gitignore alone', async () => {
+        // Whether this file is committed is the operator's call: it is written
+        // once, so there is no churn argument, and a private repo is a real
+        // backup for the one thing nothing else can reproduce. The engine
+        // ignores its own database because that one is rewritten constantly —
+        // a reason that does not transfer.
+        await mkdir(path.join(dir, '.git'), { recursive: true })
+        await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        assert.equal(existsSync(gitignore()), false)
+    })
+})
+
+describe('noticing that the key changed', () => {
+    it('records the kid on a first run without complaining', async () => {
+        const key = await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        const logger = loud()
+        const result = await checkKeyContinuity({ kid: key.kid, db, logger })
+        assert.deepEqual(result, { recorded: true })
+        assert.deepEqual(logger.seen, [], 'a first run is routine and must be silent')
+    })
+
+    it('says nothing on a restart with the same key', async () => {
+        const key = await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        await checkKeyContinuity({ kid: key.kid, db, logger: quiet })
+        const logger = loud()
+        assert.deepEqual(await checkKeyContinuity({ kid: key.kid, db, logger }), { unchanged: true })
+        assert.deepEqual(logger.seen, [])
+    })
+
+    it('raises a fault when the key was replaced', async () => {
+        // The case that matters: auth.key deleted, regenerated on the next
+        // boot. Every token anyone holds is now unverifiable, and the creation
+        // warning alone reads exactly like a first run.
+        const first = await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        await checkKeyContinuity({ kid: first.kid, db, logger: quiet })
+
+        await rm(keyFile())
+        const second = await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        assert.notEqual(second.kid, first.kid, 'a regenerated key is a different key')
+
+        const logger = loud()
+        const result = await checkKeyContinuity({ kid: second.kid, db, logger })
+        assert.equal(result.changed, true)
+        assert.equal(result.previous, first.kid)
+        assert.equal(logger.seen[0]?.code, 'auth-signing-key-changed',
+            'it has to be a fault, or ping cannot say why everyone was signed out')
+    })
+
+    it('reports null rather than "unchanged" with no store to compare against', async () => {
+        // Absence of a comparison is not evidence the key is the same, and
+        // returning `unchanged` here would be inventing the reassurance.
+        const key = await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        assert.equal(await checkKeyContinuity({ kid: key.kid, db: null, logger: quiet }), null)
+    })
+
+    it('is a fault when the check itself cannot run', async () => {
+        const key = await loadOrCreateKey({ keyFile: keyFile(), logger: quiet })
+        await db.schema.dropTable('mikser_auth_signing_key')
+        const logger = loud()
+        assert.equal(await checkKeyContinuity({ kid: key.kid, db, logger }), null)
+        assert.equal(logger.seen[0]?.code, 'auth-signing-key-changed')
+    })
+})