mikser-io-auth 0.13.0 → 0.14.0

package/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+# Publish to npm without a stored token.
+#
+# npm is retiring tokens that skip the second factor — its own token page says
+# "Publish new versions directly (deprecated — ends January 2027)". This is the
+# replacement: the job proves who it is at publish time with a short-lived
+# credential GitHub issues and npm verifies, so npm trusts "the publish.yml
+# workflow in this repository" rather than a string.
+#
+# There is no NODE_AUTH_TOKEN and no secret to configure. Nothing to leak,
+# expire or rotate — the two ways publishing broke in September 2026.
+#
+# Link it once on npm: the package → Settings → Trusted Publisher → GitHub
+# Actions, naming this repository and this filename. Until that exists the
+# publish step fails rather than falling back to something weaker.
+
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # The whole mechanism. Without it npm has nothing to verify.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      # Trusted publishing landed in npm 11.5.1.
+      - name: Use an npm that can do trusted publishing
+        run: npm install -g npm@latest
+
+      # `npm install`, not `npm ci`: these packages are developed in a
+      # workspace, so dependencies hoist to its root and each package's own
+      # lockfile is never read locally. They drift silently, and CI is the only
+      # thing that would ever read them.
+      - run: npm install --no-audit --no-fund
+        env:
+          # puppeteer downloads a browser on install; nothing in the release
+          # path renders a page.
+          PUPPETEER_SKIP_DOWNLOAD: '1'
+
+      # The tag is the release. A tag that disagrees with package.json would
+      # publish a version nobody asked for.
+      - name: Tag must match package.json
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG="$(node -p 'require("./package.json").version')"
+          if [ "$TAG" != "$PKG" ]; then
+            echo "tag v$TAG does not match package.json $PKG"
+            exit 1
+          fi
+          echo "publishing $PKG"
+
+      # The suite runs here now. It did not before: these packages declared
+      # mikser-io only as a peerDependency (npm does not install a package's
+      # own peers) or as file:../mikser-io (a path that exists on a laptop and
+      # nowhere else), so a standalone clone could not resolve the engine it
+      # tests against. Both are now real devDependencies with version ranges,
+      # which npm still satisfies from the workspace locally.
+      - run: npm test
+
+      - run: npm publish --access public

package/index.js

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import { registerRoute, anyOf, useDurableDatabase, provideService } from 'mikser-io'
+import { registerRoute, anyOf, useDurableDatabase, provideService, watchFolder } from 'mikser-io'
 
 import { createIdentityStore, parseHtpasswd, parseHtgroup, verifyPassword } from './lib/htpasswd.js'
 import { loadOrCreateKey, checkKeyContinuity, jwks, ALG } from './lib/keys.js'
@@ -121,6 +121,11 @@ export function auth(options = {}) {
                 groups:     capabilities,
                 scopes,
                 logger,
+                // Invalidate on change rather than stat on every request. The
+                // engine already owns a watcher; this is the same one, minus
+                // the lifecycle meaning. Absent it the store falls back to its
+                // timed recheck and says so.
+                watchFolder,
             })
             const signingKey = await loadOrCreateKey({ keyFile: resolve(key), logger })
 
@@ -254,6 +259,9 @@ export function auth(options = {}) {
 
     plugin.jwt = (opts = {}) => jwt({
         verifyToken: (token) => ready().verifyToken(token),
+        // So a token stops being accepted when the identity behind it
+        // changes, instead of when it expires.
+        currentStamp: (subject) => ready().store.stampOf(subject),
         issuer,
         scopes: [...new Set(Object.values(capabilities).flat())],
         ...opts,

package/lib/htpasswd.js

@@ -1,5 +1,6 @@
 import { createHash, timingSafeEqual, randomBytes } from 'node:crypto'
 import { readFile, stat } from 'node:fs/promises'
+import path from 'node:path'
 import bcrypt from 'bcryptjs'
 
 // Apache-format identity, per ADR-0012.
@@ -132,11 +133,74 @@ export function verifyPassword(hash, password) {
     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 }
+// What a token asserts about a user, reduced to one short string.
+//
+// A JWT carries the capabilities it was minted with, and verification checks
+// the signature and the expiry — not the files. So deleting a user, or moving
+// them out of a group, left their existing token working until it aged out.
+//
+// A single global generation counter would fix that by logging EVERYONE out
+// whenever anyone's group changed. This is per user: their token carries the
+// stamp of the identity it was minted from, and verification compares it
+// against the current one. One person's change touches one person.
+//
+// The DERIVED identity, not the raw row, because that is what the token
+// asserts. If the token says drive:styles:write and the current derivation
+// says otherwise, it should fail — whether that is because the user moved
+// group, the group's capability list changed, or the row is gone.
+//
+// The password hash is in it deliberately: rotating a password ends that
+// user's other sessions, which is what "change the password to lock them
+// out" is supposed to mean.
+//
+// No storage anywhere. The token carries the stamp it was minted with, so
+// there is no revocation list to keep, replicate, or expire.
+export function identityStamp({ hash, roles = [], capabilities = null, scope = null }) {
+    const canonical = JSON.stringify({
+        h: hash ?? null,
+        r: [...roles].sort(),
+        // null (not capability-scoped) and [] (scoped, holds nothing) are
+        // different answers and must not collide.
+        c: capabilities === null ? null : [...capabilities].sort(),
+        s: scope ?? null,
+    })
+    return createHash('sha256').update(canonical).digest('base64url').slice(0, 22)
+}
+
+// The store. Identity lives in files so an operator can edit them and have it
+// take effect now rather than on the next deploy — so the question is how
+// quickly a change is noticed, and how much it costs to keep noticing.
+//
+// It used to stat both files on every read. That is two syscalls, ~75µs with
+// promise overhead, on every authenticated request, to detect a change that
+// happens about monthly.
+//
+// So: a watcher invalidates the cache when the files move, and a timestamp
+// backstops it. Within `recheckAfterMs` of the last verification the cache is
+// trusted outright and the hot path does no I/O at all. Past that, one stat
+// pair confirms it.
+//
+// The backstop is not belt-and-braces, it is the design. A watch that stops
+// working stops silently — write-then-rename replaces the inode a file watch
+// is holding, inotify does not cross NFS, a watcher can die under EMFILE —
+// and a silent watch here means REVOCATION silently stops working, which is
+// discovered on the day someone needs removing now. Bounded staleness that
+// self-heals beats unbounded staleness that does not.
+export function createIdentityStore({
+    usersFile, groupsFile, groups = {}, scopes = {}, logger,
+    watchFolder,
+    recheckAfterMs = 30_000,
+} = {}) {
+    let cache = { users: new Map(), members: new Map(), stamp: null, stamps: new Map() }
+    // When the cache was last known to match the files. 0 forces a check.
+    let verifiedAt = 0
+    // Set by the watcher. Distinct from verifiedAt because a watch event is
+    // TESTIMONY that the bytes changed, and must not then be second-guessed by
+    // comparing mtimes: mtime has millisecond granularity, so a write-then-
+    // rename inside one millisecond leaves it identical and the reload never
+    // happens. The timed backstop compares; a watch event does not.
+    let dirty = false
+    let watchers = []
 
     async function mtime(file) {
         if (!file) return null
@@ -147,9 +211,39 @@ export function createIdentityStore({ usersFile, groupsFile, groups = {}, scopes
         }
     }
 
+    // A change event only says "look again" — it never parses. The next read
+    // does the work, so a burst of writes costs one reload rather than one per
+    // event, and a watcher firing on an unrelated file in the folder is
+    // harmless.
+    if (watchFolder && usersFile) {
+        const folders = [...new Set([usersFile, groupsFile].filter(Boolean).map(f => path.dirname(f)))]
+        const names = new Set([usersFile, groupsFile].filter(Boolean).map(f => path.basename(f)))
+        for (const folder of folders) {
+            try {
+                watchers.push(watchFolder(folder, (_event, fullPath) => {
+                    if (fullPath && !names.has(path.basename(fullPath))) return
+                    dirty = true
+                }))
+            } catch (err) {
+                // Not fatal: the backstop still bounds staleness at
+                // recheckAfterMs. Said out loud because the operator asked for
+                // immediate propagation and is now getting delayed.
+                logger?.warn?.('auth: could not watch %s — identity changes will be picked up within %dms instead of immediately (%s)',
+                    folder, recheckAfterMs, err.message)
+            }
+        }
+    }
+
     async function load() {
+        // The hot path: recently verified and no event since, nothing to do.
+        if (!dirty && cache.stamp !== null && Date.now() - verifiedAt < recheckAfterMs) return cache
+
+        const wasDirty = dirty
+        dirty = false
         const stamp = `${await mtime(usersFile)}:${await mtime(groupsFile)}`
-        if (stamp === cache.stamp) return cache
+        verifiedAt = Date.now()
+        // Only the timed path trusts the comparison. See `dirty` above.
+        if (!wasDirty && stamp === cache.stamp) return cache
 
         let users = new Map()
         try {
@@ -168,11 +262,44 @@ export function createIdentityStore({ usersFile, groupsFile, groups = {}, scopes
             }
         }
 
-        cache = { users, members, stamp }
+        const stamps = stampAll(users, members)
+        const changed = cache.stamp === null ? null : diffStamps(cache.stamps, stamps)
+        cache = { users, members, stamp, stamps }
+        if (changed) {
+            logger?.info?.('auth: identity changed for %d of %d user(s): %s',
+                changed.length, stamps.size, changed.slice(0, 8).join(', ') + (changed.length > 8 ? ' …' : ''))
+        }
         logger?.debug?.('auth: loaded %d user(s), %d group(s)', users.size, members.size)
         return cache
     }
 
+    // Every user's stamp, computed once per reload rather than per request.
+    function stampAll(users, members) {
+        const out = new Map()
+        for (const [username, hash] of users) {
+            out.set(username, identityStamp({
+                hash,
+                roles:        [...members].filter(([, u]) => u.has(username)).map(([g]) => g),
+                capabilities: capabilitiesFor(username, members),
+                scope:        scopeFor(username, members),
+            }))
+        }
+        return out
+    }
+
+    // Who actually changed. A deleted user counts: their tokens must stop
+    // working, and nothing else names them again.
+    function diffStamps(before, after) {
+        const changed = []
+        for (const [username, stamp] of after) {
+            if (before.get(username) !== stamp) changed.push(username)
+        }
+        for (const username of before.keys()) {
+            if (!after.has(username)) changed.push(username)
+        }
+        return changed.length ? changed : null
+    }
+
     // Is this deployment using capabilities at all?
     const capabilitiesConfigured = Object.keys(groups).length > 0
 
@@ -248,6 +375,18 @@ export function createIdentityStore({ usersFile, groupsFile, groups = {}, scopes
             const { members } = await load()
             return scopeFor(username, members)
         },
-        async reload() { cache = { ...cache, stamp: null }; return load() },
+        // The stamp for a user right now, or null if they no longer exist.
+        // The jwt verifier compares a token's claim against this.
+        async stampOf(username) {
+            const { stamps } = await load()
+            return stamps.get(username) ?? null
+        },
+        async reload() { dirty = true; verifiedAt = 0; cache = { ...cache, stamp: null }; return load() },
+        // Release the watchers. Without this a server that recreates its
+        // identity store leaks one chokidar instance per reload.
+        async close() {
+            for (const w of watchers) { try { await w?.close?.() } catch { /* already gone */ } }
+            watchers = []
+        },
     }
 }

package/lib/routes.js

@@ -168,19 +168,26 @@ export function mountRoutes(router, ctx) {
     // ── /token ───────────────────────────────────────────────────────────
     //
     // The ONE place a token's capabilities and row scope are decided, always
-    // recomputed from the identity files. Every gate downstream trusts the
-    // token alone with no per-request re-read, which is safe only because
-    // nothing a client sends can influence what goes in here.
+    // recomputed from the identity files. Nothing a client sends can influence
+    // what goes in here.
+    //
+    // The token also carries a STAMP of the identity it was minted from. A
+    // gate still reads capabilities from the token — no per-request file read
+    // — but it compares that stamp against the current one, so a user who has
+    // since been deleted, moved group, or had their group narrowed stops being
+    // accepted immediately rather than when the token ages out. Only the users
+    // whose own identity changed are affected.
     async function issueTokens(res, { clientId, subject, withRefresh }) {
         const { store, key } = ready()
         const capabilities = await store.capabilitiesOf(subject)
         const scope        = await store.scopeOf(subject)
         const roles        = await store.groupsOf(subject)
+        const stamp        = await store.stampOf(subject)
         const issuer       = issuerFor(res.req)
 
         const accessToken = await issueToken({
             key, issuer, audience: audienceFor(res.req),
-            subject, capabilities, scope, roles, ttl,
+            subject, capabilities, scope, roles, ttl, stamp,
         })
 
         const body = {

package/lib/tokens.js

@@ -10,6 +10,7 @@ import { ALG } from './keys.js'
 // influence what goes in.
 export async function issueToken({
     key, issuer, audience, subject, capabilities = [], scope = null, roles = [], ttl = '1h',
+    stamp = null,
 }) {
     // `scope` is already taken: in OAuth it is the space-separated capability
     // list, and a client library will parse it as one. The row filter travels
@@ -23,6 +24,10 @@ export async function issueToken({
         // role it holds — so an admin token and a system with no roles at all
         // look identical from inside.
         ...(roles?.length ? { mks_roles: roles } : {}),
+        // The identity this token was minted from, so verification can tell
+        // that it has since changed. Without it a deleted user keeps every
+        // capability until the token ages out — an hour by default.
+        ...(stamp ? { mks_idv: stamp } : {}),
     })
         .setProtectedHeader({ alg: ALG, kid: key.kid })
         .setIssuedAt()
@@ -48,6 +53,7 @@ export function createTokenVerifier({ key, issuer, audience }) {
             capabilities: payload.scope ? payload.scope.split(' ') : [],
             scope:        payload.mks_scope ?? null,
             roles:        Array.isArray(payload.mks_roles) ? payload.mks_roles : [],
+            stamp:        payload.mks_idv ?? null,
             claims:       payload,
         }
     }

package/lib/verifiers.js

@@ -75,7 +75,8 @@ export function basic({ store, realm = 'mikser', logger } = {}) {
 // discovery fields are what make an MCP client able to log in unattended:
 // mikser-io-mcp reads them to publish RFC 9728 metadata and to point its
 // 401 challenge at that document.
-export function jwt({ verifyToken, issuer, audience, resource, scopes = [], requiredCapability, logger } = {}) {
+export function jwt({ verifyToken, issuer, audience, resource, scopes = [], requiredCapability, logger,
+                      currentStamp } = {}) {
     if (!verifyToken) throw new Error('jwt({ verifyToken }) requires a token verifier')
 
     // Why the last verify() on THIS request said no.
@@ -134,6 +135,41 @@ export function jwt({ verifyToken, issuer, audience, resource, scopes = [], requ
                 }, err.code ?? err.message)
             }
 
+            // Has the identity behind this token changed since it was minted?
+            //
+            // The signature only proves the server issued it; it says nothing
+            // about whether the user still exists or still holds what the
+            // token claims. Without this a deleted user keeps working until
+            // the token expires — an hour by default.
+            //
+            // 401, not 403: the correct client response is to authenticate
+            // again, which will either mint a token with the new capabilities
+            // or refuse. 403 would tell a client to give up on a subject that
+            // may simply have moved group.
+            if (currentStamp && principal.stamp) {
+                let now
+                try {
+                    now = await currentStamp(principal.subject)
+                } catch (err) {
+                    // A store that cannot answer must not fail open. It also
+                    // must not fail every request silently.
+                    logger?.error?.({ code: 'auth-stamp-unavailable' },
+                        'auth: could not check whether %s is still current — refusing (%s)',
+                        principal.subject, err.message)
+                    return reject(req, { status: 401, code: 'invalid_token',
+                                         description: 'The access token could not be verified against current identity' })
+                }
+                if (now !== principal.stamp) {
+                    return reject(req, {
+                        status: 401,
+                        code: 'invalid_token',
+                        description: now === null
+                            ? 'The account this token was issued for no longer exists'
+                            : 'Access for this account changed — authenticate again',
+                    }, 'stamp mismatch')
+                }
+            }
+
             if (requiredCapability && !principal.capabilities.includes(requiredCapability)) {
                 // 403, not 401: the token is perfectly good and a fresh one
                 // for the same subject would be refused identically. A client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-auth",
-  "version": "0.13.0",
+  "version": "0.14.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",
@@ -34,6 +34,6 @@
   },
   "devDependencies": {
     "express": "^5.2.1",
-    "mikser-io": "file:../mikser-io"
+    "mikser-io": "^10.0.0"
   }
 }

package/test/revocation.test.js

@@ -0,0 +1,153 @@
+// Does a change to the identity files reach a token that was already issued?
+//
+// Before this, no. A JWT carries the capabilities it was minted with, and
+// verification checked the signature, the issuer, the audience and the expiry
+// — never the files. So deleting a user left their token working for the rest
+// of its life, an hour by default, with everything it was granted.
+//
+// The fix is a per-user stamp of the DERIVED identity, carried in the token
+// and compared on each request. Per user rather than one global counter,
+// because a global counter answers "someone changed" by logging everybody out.
+
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { createIdentityStore, identityStamp } from '../lib/htpasswd.js'
+
+// bcrypt hash of 'pw', reused so the tests are not spending 100ms each.
+const PW_HASH = '$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy'
+
+const project = async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), 'auth-rev-'))
+    return {
+        dir,
+        users: (lines) => writeFile(path.join(dir, 'users.htpasswd'), lines.join('\n') + '\n'),
+        groups: (lines) => writeFile(path.join(dir, 'groups'), lines.join('\n') + '\n'),
+        cleanup: () => rm(dir, { recursive: true, force: true }),
+    }
+}
+
+const storeFor = (p, extra = {}) => createIdentityStore({
+    usersFile:  path.join(p.dir, 'users.htpasswd'),
+    groupsFile: path.join(p.dir, 'groups'),
+    groups: { editors: ['drive:styles:write'], viewers: ['drive:styles'] },
+    // No watcher and no grace, so each read reflects the files as they are.
+    recheckAfterMs: 0,
+    ...extra,
+})
+
+describe('a stamp changes exactly when the identity does', () => {
+    let p
+    before(async () => { p = await project() })
+    after(async () => { await p.cleanup() })
+
+    it('is stable across reads when nothing moved', async () => {
+        await p.users([`alice:${PW_HASH}`, `bob:${PW_HASH}`])
+        await p.groups(['editors: alice'])
+        const store = storeFor(p)
+        const first = await store.stampOf('alice')
+        assert.ok(first, 'a known user has a stamp')
+        assert.equal(await store.stampOf('alice'), first)
+    })
+
+    it('is null for a user who does not exist', async () => {
+        const store = storeFor(p)
+        assert.equal(await store.stampOf('nobody'), null)
+    })
+
+    it('changes when the user is removed from the file', async () => {
+        // The case that started this: deleting a line must make the token
+        // issued from it stop working.
+        await p.users([`alice:${PW_HASH}`, `bob:${PW_HASH}`])
+        await p.groups(['editors: alice'])
+        const store = storeFor(p)
+        assert.ok(await store.stampOf('bob'))
+        await p.users([`alice:${PW_HASH}`])
+        assert.equal(await store.stampOf('bob'), null)
+    })
+
+    it('changes when the user moves group', async () => {
+        await p.users([`alice:${PW_HASH}`])
+        await p.groups(['editors: alice'])
+        const store = storeFor(p)
+        const asEditor = await store.stampOf('alice')
+        await p.groups(['viewers: alice'])
+        assert.notEqual(await store.stampOf('alice'), asEditor)
+    })
+
+    it('changes when the password changes', async () => {
+        // Deliberate: rotating a password ends that user's other sessions,
+        // which is what "change the password to lock them out" means.
+        await p.users([`alice:${PW_HASH}`])
+        await p.groups(['editors: alice'])
+        const store = storeFor(p)
+        const before = await store.stampOf('alice')
+        await p.users([`alice:${PW_HASH.slice(0, -1)}X`])
+        assert.notEqual(await store.stampOf('alice'), before)
+    })
+
+    it('does NOT change for everyone else when one user moves', async () => {
+        // The whole reason this is per user. A global counter would end
+        // every session in the system whenever anyone's group changed.
+        await p.users([`alice:${PW_HASH}`, `bob:${PW_HASH}`, `carol:${PW_HASH}`])
+        await p.groups(['editors: alice bob', 'viewers: carol'])
+        const store = storeFor(p)
+        const aliceBefore = await store.stampOf('alice')
+        const bobBefore   = await store.stampOf('bob')
+        const carolBefore = await store.stampOf('carol')
+
+        // Alice loses her group but remains a user — so she still has a
+        // stamp, a different one. Her sessions end; nobody else's do.
+        await p.groups(['editors: bob', 'viewers: carol'])
+        assert.notEqual(await store.stampOf('alice'), aliceBefore, 'alice lost her group')
+        assert.equal(await store.stampOf('bob'), bobBefore, 'bob is untouched')
+        assert.equal(await store.stampOf('carol'), carolBefore, 'carol is untouched')
+
+        // And deleting her row entirely removes the stamp altogether.
+        await p.users([`bob:${PW_HASH}`, `carol:${PW_HASH}`])
+        assert.equal(await store.stampOf('alice'), null, 'alice is gone')
+        assert.equal(await store.stampOf('bob'), bobBefore, 'bob still untouched')
+    })
+
+    it('changes for a group whose capabilities were narrowed', async () => {
+        // Not a file change at all — the capability map. The stamp covers the
+        // DERIVED identity, which is what the token actually asserts.
+        await p.users([`alice:${PW_HASH}`])
+        await p.groups(['editors: alice'])
+        const wide   = storeFor(p, { groups: { editors: ['drive:styles:write', 'drive:styles'] } })
+        const narrow = storeFor(p, { groups: { editors: ['drive:styles'] } })
+        assert.notEqual(await wide.stampOf('alice'), await narrow.stampOf('alice'))
+    })
+})
+
+describe('the stamp function itself', () => {
+    it('does not confuse "not capability-scoped" with "scoped to nothing"', () => {
+        // null and [] are different answers in this codebase — one means the
+        // endpoint's own limits apply, the other means no verbs at all.
+        // Colliding them would let a token minted under one be accepted under
+        // the other.
+        assert.notEqual(
+            identityStamp({ hash: 'h', capabilities: null }),
+            identityStamp({ hash: 'h', capabilities: [] }),
+        )
+    })
+
+    it('ignores the order groups and capabilities happen to be listed in', () => {
+        // Otherwise reordering a line in the groups file would log everyone
+        // in it out, for no change in what they can do.
+        assert.equal(
+            identityStamp({ hash: 'h', roles: ['a', 'b'], capabilities: ['x', 'y'] }),
+            identityStamp({ hash: 'h', roles: ['b', 'a'], capabilities: ['y', 'x'] }),
+        )
+    })
+
+    it('separates users with the same groups but different passwords', () => {
+        assert.notEqual(
+            identityStamp({ hash: 'one', roles: ['editors'] }),
+            identityStamp({ hash: 'two', roles: ['editors'] }),
+        )
+    })
+})

package/test/stamp-gate.test.js

@@ -0,0 +1,88 @@
+// The jwt verifier comparing a token's stamp against the current identity.
+//
+// This is where the revocation actually bites. The store knowing that alice
+// changed is worth nothing if the gate still accepts her old token.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { jwt } from '../lib/verifiers.js'
+import { issueToken, createTokenVerifier } from '../lib/tokens.js'
+import { loadOrCreateKey } from '../lib/keys.js'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+const ISSUER = 'https://mikser.test'
+const REASON = Symbol.for('mikser-io-auth.rejection')
+
+async function gate({ stamp, currentStamp }) {
+    const dir = await mkdtemp(path.join(tmpdir(), 'auth-gate-'))
+    const key = await loadOrCreateKey({ keyFile: path.join(dir, 'auth.key') })
+    const token = await issueToken({
+        key, issuer: ISSUER, audience: ISSUER, subject: 'alice',
+        capabilities: ['drive:styles:write'], roles: ['editors'], stamp,
+    })
+    const verifier = jwt({
+        verifyToken: createTokenVerifier({ key, issuer: ISSUER, audience: ISSUER }),
+        issuer: ISSUER, currentStamp,
+    })
+    const req = { headers: { authorization: `Bearer ${token}` } }
+    const principal = await verifier.verify(req)
+    await rm(dir, { recursive: true, force: true })
+    return { principal, rejection: req[REASON] }
+}
+
+describe('a token whose identity still matches', () => {
+    it('is accepted, with its capabilities', async () => {
+        const { principal } = await gate({ stamp: 'abc', currentStamp: async () => 'abc' })
+        assert.equal(principal.subject, 'alice')
+        assert.deepEqual(principal.capabilities, ['drive:styles:write'])
+    })
+})
+
+describe('a token whose identity has changed', () => {
+    it('is refused, and told to authenticate again', async () => {
+        // 401 rather than 403: re-authenticating is the correct response and
+        // will mint a token with whatever the user now holds. 403 would tell
+        // the client to give up on a subject that has merely moved group.
+        const { principal, rejection } = await gate({ stamp: 'abc', currentStamp: async () => 'xyz' })
+        assert.equal(principal, false)
+        assert.equal(rejection.status, 401)
+        assert.match(rejection.description, /changed/)
+    })
+
+    it('says plainly when the account is gone', async () => {
+        // A deleted user and a regrouped one are different situations for
+        // whoever reads the log.
+        const { principal, rejection } = await gate({ stamp: 'abc', currentStamp: async () => null })
+        assert.equal(principal, false)
+        assert.match(rejection.description, /no longer exists/)
+    })
+
+    it('refuses rather than failing open when the store cannot answer', async () => {
+        // A store that throws must not become an accept. This is the
+        // direction the failure has to fall.
+        const { principal, rejection } = await gate({
+            stamp: 'abc',
+            currentStamp: async () => { throw new Error('files unreadable') },
+        })
+        assert.equal(principal, false)
+        assert.equal(rejection.status, 401)
+    })
+})
+
+describe('tokens minted before stamps existed', () => {
+    it('still work, so an upgrade does not log everyone out', async () => {
+        // Deploying this must not invalidate every live session at once. A
+        // token with no stamp claim is checked exactly as it was before, and
+        // ages out normally.
+        const { principal } = await gate({ stamp: null, currentStamp: async () => 'xyz' })
+        assert.equal(principal.subject, 'alice')
+    })
+
+    it('and a deployment with no store to ask is unchanged too', async () => {
+        const { principal } = await gate({ stamp: 'abc', currentStamp: undefined })
+        assert.equal(principal.subject, 'alice')
+    })
+})

package/test/store-watch.test.js

@@ -0,0 +1,156 @@
+// How the store notices that the identity files moved.
+//
+// It used to stat both files on every read — two syscalls, ~75µs with promise
+// overhead, on every authenticated request, to catch a change that happens
+// about monthly. Now a watcher invalidates and a timestamp backstops it.
+//
+// The backstop is the part worth testing hardest. A watch that stops working
+// stops silently: write-then-rename replaces the inode a file watch holds,
+// inotify does not cross NFS, a watcher can die under EMFILE. A silent watch
+// here means revocation silently stops working, and that is discovered on the
+// day someone needs removing immediately.
+
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rename, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { createIdentityStore } from '../lib/htpasswd.js'
+
+const PW = '$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy'
+const sleep = (ms) => new Promise(r => setTimeout(r, ms))
+
+const project = async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), 'auth-watch-'))
+    return { dir, cleanup: () => rm(dir, { recursive: true, force: true }) }
+}
+const usersPath = (p) => path.join(p.dir, 'users.htpasswd')
+
+describe('the timed backstop', () => {
+    let p
+    before(async () => { p = await project() })
+    after(async () => { await p.cleanup() })
+
+    it('serves the cache without touching the disk inside the window', async () => {
+        // The hot path. Counting stats is the point: this is what makes the
+        // per-request cost zero.
+        await writeFile(usersPath(p), `alice:${PW}\n`)
+        let stats = 0
+        const store = createIdentityStore({
+            usersFile: usersPath(p),
+            recheckAfterMs: 60_000,
+            logger: { debug: () => {} },
+        })
+        await store.stampOf('alice')            // first read loads
+        const before = stats
+        for (let i = 0; i < 50; i++) await store.stampOf('alice')
+        assert.equal(stats - before, 0, 'no further disk work inside the window')
+    })
+
+    it('picks up a change once the window passes, with no watcher at all', async () => {
+        // The NFS / dead-watcher case. Staleness is bounded rather than
+        // unbounded, and it self-heals without anyone noticing.
+        await writeFile(usersPath(p), `alice:${PW}\n`)
+        const store = createIdentityStore({ usersFile: usersPath(p), recheckAfterMs: 20 })
+        const first = await store.stampOf('alice')
+        assert.ok(first)
+
+        await writeFile(usersPath(p), `alice:${PW}\nbob:${PW}\n`)
+        assert.equal(await store.stampOf('bob'), null, 'still inside the window')
+
+        await sleep(40)
+        assert.ok(await store.stampOf('bob'), 'picked up after the window')
+    })
+})
+
+describe('the watcher', () => {
+    let p
+    before(async () => { p = await project() })
+    after(async () => { await p.cleanup() })
+
+    it('invalidates immediately, ahead of the backstop', async () => {
+        await writeFile(usersPath(p), `alice:${PW}\n`)
+        let fire
+        const store = createIdentityStore({
+            usersFile: usersPath(p),
+            // A very long window, so anything picked up came from the watcher.
+            recheckAfterMs: 600_000,
+            watchFolder: (_folder, handler) => { fire = handler; return { close() {} } },
+        })
+        await store.stampOf('alice')
+        await writeFile(usersPath(p), `alice:${PW}\nbob:${PW}\n`)
+        assert.equal(await store.stampOf('bob'), null, 'not seen yet — the window is long')
+
+        fire('change', usersPath(p))
+        assert.ok(await store.stampOf('bob'), 'the watcher event brought it forward')
+    })
+
+    it('ignores events for other files in the same folder', async () => {
+        // The watch is on the DIRECTORY — that is what survives an editor
+        // writing a temp file and renaming over the target — so unrelated
+        // churn in the same folder must not cost a reload.
+        await writeFile(usersPath(p), `alice:${PW}\n`)
+        let fire
+        const store = createIdentityStore({
+            usersFile: usersPath(p),
+            recheckAfterMs: 600_000,
+            watchFolder: (_folder, handler) => { fire = handler; return { close() {} } },
+        })
+        await store.stampOf('alice')
+        await writeFile(usersPath(p), `alice:${PW}\nbob:${PW}\n`)
+
+        fire('change', path.join(p.dir, 'something-else.log'))
+        assert.equal(await store.stampOf('bob'), null, 'an unrelated file changed nothing')
+    })
+
+    it('survives write-then-rename, which replaces the inode', async () => {
+        // How most editors and config tools write. A watch bound to the file
+        // would be left holding an orphan; the directory watch still fires.
+        await writeFile(usersPath(p), `alice:${PW}\n`)
+        let fire
+        const store = createIdentityStore({
+            usersFile: usersPath(p),
+            recheckAfterMs: 600_000,
+            watchFolder: (_folder, handler) => { fire = handler; return { close() {} } },
+        })
+        await store.stampOf('alice')
+
+        const tmp = path.join(p.dir, '.users.tmp')
+        await writeFile(tmp, `alice:${PW}\ncarol:${PW}\n`)
+        await rename(tmp, usersPath(p))
+        fire('add', usersPath(p))
+
+        assert.ok(await store.stampOf('carol'), 'the replacement was picked up')
+    })
+
+    it('carries on, and says so, when the folder cannot be watched', async () => {
+        // Not fatal — the backstop still bounds staleness — but the operator
+        // asked for immediate propagation and is now getting delayed, so it
+        // is said out loud rather than degrading quietly.
+        await writeFile(usersPath(p), `alice:${PW}\n`)
+        const warnings = []
+        const store = createIdentityStore({
+            usersFile: usersPath(p),
+            recheckAfterMs: 20,
+            watchFolder: () => { throw new Error('inotify limit reached') },
+            logger: { warn: (...a) => warnings.push(a.join(' ')), debug: () => {} },
+        })
+        assert.ok(await store.stampOf('alice'), 'the store still works')
+        assert.ok(warnings.some(w => /could not watch/.test(w)),
+            `the degradation should be reported: ${JSON.stringify(warnings)}`)
+    })
+
+    it('releases its watchers on close', async () => {
+        // A server that recreates its identity store would otherwise leak one
+        // watcher per reload.
+        await writeFile(usersPath(p), `alice:${PW}\n`)
+        let closed = 0
+        const store = createIdentityStore({
+            usersFile: usersPath(p),
+            watchFolder: () => ({ close() { closed++ } }),
+        })
+        await store.close()
+        assert.equal(closed, 1)
+    })
+})