mikser-io-auth 0.11.0 → 0.13.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, provideService } 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,16 +86,31 @@ 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
+            // Offered so any transport can say which role is acting and
             // which others exist. The catalogue is not secret — naming the
             // role that could do something is what makes a handoff possible,
             // and it reveals nothing about how to obtain one.
-            runtime.options.roles = {
+            //
+            // A service rather than runtime.options.roles: mikser-io-mcp is
+            // the consumer, and it should not have to know this package
+            // exists to ask what roles there are.
+            provideService('roles', {
                 catalogue: capabilities,
                 summaries: roleSummaries,
-            }
+            }, { plugin: 'mikser-io-auth' })
 
             const workingFolder = runtime.options.workingFolder
             const resolve = (f) => (path.isAbsolute(f) ? f : path.join(workingFolder, f))

package/lib/grants.js

@@ -56,6 +56,24 @@ registerMigrations('auth', [
             })
         },
     },
+    {
+        // 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()

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mikser-io-auth",
-  "version": "0.11.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.",
+  "version": "0.13.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 — 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.57.0"
+    "mikser-io": "^10.0.0"
   },
   "dependencies": {
     "bcryptjs": "^3.0.0",

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')
+    })
+})