mikser-io-auth 0.5.2 → 0.6.1

package/README.md

@@ -220,10 +220,36 @@ Authorization codes (60s, single-use) and refresh tokens (30d, rotated on
 every use) live in the engine's sqlite (ADR-0009), under `mikser_auth_*`.
 Identity stays in files; this is session bookkeeping.
 
-The engine wipes that database when its schema stamp changes, so **upgrading
-mikser signs everyone out**. Codes are irrelevant at 60 seconds; re-issuing
-refresh tokens after an engine upgrade is the price of not inventing a second
-persistence story.
+The engine wipes that database when its schema stamp or config checksum
+changes — an upgrade, or any deploy that edits `mikser.config.js`. These
+tables are registered `durable: true`, so the wipe drops table by table and
+keeps them: a registered client and its refresh token exist only because a
+human completed a sign-in once, and they are not something the working folder
+can rebuild.
+
+### When an access token expires
+
+Access tokens are short (`ttl`, default `1h`) and refresh tokens are long, so
+a client is expected to notice the expiry and exchange quietly. It can only do
+that if the resource server *says* which failure it hit, and the vocabulary is
+RFC 6750 §3.1:
+
+| Situation | Status | `WWW-Authenticate` | What a client should do |
+| --- | --- | --- | --- |
+| no credential presented | 401 | no `error` — the omission is the signal | start a sign-in |
+| access token expired | 401 | `error="invalid_token"`, `error_description="The access token expired"` | exchange the refresh token, retry |
+| token malformed, wrong audience, wrong key | 401 | `error="invalid_token"` | sign in again; refreshing will not help |
+| token valid, subject lacks the capability | 403 | `error="insufficient_scope"`, `scope="<capability>"` | do NOT refresh — a fresh token is refused identically |
+
+All four used to be one byte-identical 401. A client cannot tell "your token
+went stale" from "you have never authenticated here" in that state, so it does
+the safe thing and starts a whole new authorization flow — a human, a browser,
+mid-task, with a perfectly good refresh token in hand.
+
+The verifier reports which one it hit through `rejectionFor(req)`, an optional
+method on the engine's ADR-0012 verifier contract. It can only *narrow* a
+denial that has already happened; there is nothing it can return that turns a
+rejection into an acceptance.
 
 ## Not implemented
 

package/index.js

@@ -123,7 +123,19 @@ export function auth(options = {}) {
             router.use(express.urlencoded({ extended: false, limit: '8kb' }))
             router.use(express.json({ limit: '8kb' }))
 
-            const originOf = (req) => issuer ?? `${req.protocol}://${req.get('host')}`
+            // The deployment's identity, and it must be the SAME string the
+            // verifier was built with — a token minted for one issuer and
+            // checked against another fails verification, which from the
+            // outside is indistinguishable from an expired token. The
+            // verifier is pinned to `issuer ?? runtime.options.url` at load,
+            // so this resolves in that order too and only falls back to the
+            // request when neither is configured (a dev box with no --url).
+            //
+            // RFC 8414 §2 wants a stable issuer besides: clients cache the
+            // metadata document keyed by it, so deriving it per-request makes
+            // one deployment look like several.
+            const originOf = (req) =>
+                issuer ?? runtime.options.url ?? `${req.protocol}://${req.get('host')}`
 
             // What the sign-in page calls this deployment. Not a config
             // option: mikser already knows its external URL, and failing
@@ -231,7 +243,14 @@ export function auth(options = {}) {
     // one, which is rare.
     const composite = anyOf(plugin.basic(), plugin.jwt())
     plugin.verify    = (req) => composite.verify(req)
-    plugin.challenge = (req, res) => composite.challenge(req, res)
+    // Both forwarded WITH their arguments. Dropping either is silent: the
+    // endpoint still denies correctly, it just stops saying which denial it
+    // was — so an expiry a refresh token would have fixed reads as a fresh
+    // sign-in, which is the whole failure this vocabulary exists to prevent.
+    // `auth: identity` is the documented shape, so a gap here bypasses the
+    // signal in the configuration almost everyone uses.
+    plugin.rejectionFor = (req) => composite.rejectionFor?.(req)
+    plugin.challenge = (req, res, outcome) => composite.challenge(req, res, outcome)
     Object.defineProperties(plugin, {
         // A function's own `name` is non-writable, so plain assignment
         // throws in a module. defineProperty is the only way to give the

package/lib/verifiers.js

@@ -5,6 +5,23 @@
 // null  = no credential presented  (loopback may still apply)
 // false = presented and rejected   (never falls back to anything)
 
+// Build a Bearer challenge, appending the RFC 6750 §3.1 error parameters
+// when the request actually presented something.
+//
+// Omission is meaningful and is why `outcome` is consulted rather than
+// always writing an error: a challenge to a request that carried NO
+// credential must not claim the token was invalid — that is how a client
+// distinguishes "sign in" from "your token went stale".
+export function challengeHeader({ params = {}, outcome } = {}) {
+    const parts = Object.entries(params).map(([k, v]) => `${k}="${v}"`)
+    if (outcome?.code) {
+        parts.push(`error="${outcome.code}"`)
+        if (outcome.description) parts.push(`error_description="${outcome.description}"`)
+        if (outcome.scope) parts.push(`scope="${outcome.scope}"`)
+    }
+    return parts.length ? `Bearer, ${parts.join(', ')}` : 'Bearer'
+}
+
 // HTTP Basic against the htpasswd file. Browser-native, no flow, no tokens —
 // the right tool for the api/forms/decap surfaces, where the caller is a
 // person with a browser or a script with curl. Not for MCP: an MCP client
@@ -60,6 +77,22 @@ export function basic({ store, realm = 'mikser', logger } = {}) {
 export function jwt({ verifyToken, issuer, audience, resource, scopes = [], requiredCapability, logger } = {}) {
     if (!verifyToken) throw new Error('jwt({ verifyToken }) requires a token verifier')
 
+    // Why the last verify() on THIS request said no.
+    //
+    // The ADR-0012 contract is three-valued on purpose and `false` is all of
+    // it — but "expired" and "you are not allowed" are opposite instructions
+    // to a client, and only this function ever looked at the token. Kept on
+    // the request rather than in the closure because a verifier instance is
+    // shared across every concurrent request and a module-level slot would
+    // hand one request's reason to another.
+    const REASON = Symbol.for('mikser-io-auth.rejection')
+
+    const reject = (req, rejection, detail) => {
+        if (req) req[REASON] = rejection
+        logger?.debug?.('auth: jwt rejected — %s%s', rejection.code, detail ? ` (${detail})` : '')
+        return false
+    }
+
     return {
         name: 'jwt',
         authorizationServers: [issuer],
@@ -69,9 +102,13 @@ export function jwt({ verifyToken, issuer, audience, resource, scopes = [], requ
         async verify(req) {
             const header = req.headers?.authorization ?? req.get?.('authorization')
             if (!header) return null
+            if (req) delete req[REASON]
 
             const match = /^Bearer\s+(.+)$/i.exec(header)
-            if (!match) return false
+            if (!match) {
+                return reject(req, { status: 401, code: 'invalid_token',
+                                     description: 'Authorization header is not a Bearer token' })
+            }
 
             let principal
             try {
@@ -80,21 +117,52 @@ export function jwt({ verifyToken, issuer, audience, resource, scopes = [], requ
                 // An expired or malformed token is a rejection, not an error:
                 // failing loudly here would turn a routine token expiry into
                 // a 500 and mask it from the client's refresh logic.
-                logger?.debug?.('auth: jwt rejected — %s', err.code ?? err.message)
-                return false
+                //
+                // jose throws ERR_JWT_EXPIRED for the one case a client can
+                // fix by itself, so it is named. Everything else is a token
+                // this server will never accept, and saying "expired" there
+                // would send a client to burn its refresh token for nothing.
+                const expired = err.code === 'ERR_JWT_EXPIRED'
+                return reject(req, {
+                    status: 401,
+                    code: 'invalid_token',
+                    description: expired
+                        ? 'The access token expired'
+                        : 'The access token is not valid',
+                    expired,
+                }, err.code ?? err.message)
             }
 
             if (requiredCapability && !principal.capabilities.includes(requiredCapability)) {
-                logger?.debug?.('auth: %j lacks %j', principal.subject, requiredCapability)
-                return false
+                // 403, not 401: the token is perfectly good and a fresh one
+                // for the same subject would be refused identically. A client
+                // that reads this as an expiry refreshes in a loop.
+                return reject(req, {
+                    status: 403,
+                    code: 'insufficient_scope',
+                    description: `This token does not carry ${requiredCapability}`,
+                    scope: requiredCapability,
+                }, `${principal.subject} lacks ${requiredCapability}`)
             }
             return principal
         },
 
+        rejectionFor(req) {
+            return req?.[REASON]
+        },
+
         // Only used when a surface has no better idea; mikser-io-mcp
         // overrides this with a resource_metadata pointer of its own.
-        challenge(req, res) {
-            res.set('WWW-Authenticate', `Bearer${issuer ? `, authorization_uri="${issuer}"` : ''}`)
+        //
+        // `error` is the field a client's refresh logic reads (RFC 6750
+        // §3.1). Without it every denial looks the same from outside, and an
+        // expiry that a refresh token would have fixed silently becomes a
+        // fresh authorization flow — a human, a browser, mid-task.
+        challenge(req, res, outcome) {
+            res.set('WWW-Authenticate', challengeHeader({
+                params: issuer ? { authorization_uri: issuer } : {},
+                outcome,
+            }))
         },
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-auth",
-  "version": "0.5.2",
+  "version": "0.6.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.",
   "main": "index.js",
   "type": "module",

package/test/authorize.test.js

@@ -51,7 +51,19 @@ before(async () => {
     for (const hook of runtime.hooks.initialize) await hook()
     for (const hook of runtime.hooks.loaded) await hook()
 
-    runtime.options.url = 'https://test-mikser.example'
+    // Listen FIRST, then declare that origin as the deployment's URL.
+    //
+    // A deployment whose `url` is not where it actually serves is not a
+    // configuration anyone runs, and pretending otherwise hid a real
+    // asymmetry: the token minter derived issuer/audience from the request
+    // while the verifier was pinned to `runtime.options.url`. With the two
+    // disagreeing, every minted token failed verification — which from a
+    // client looks exactly like expiry.
+    server = await new Promise(resolve => {
+        const s = app.listen(0, () => resolve(s))
+    })
+    port = server.address().port
+    runtime.options.url = `http://127.0.0.1:${port}`
 
     const plugin = auth({
         capabilities: { editors: ['api:list', 'api:update'] },
@@ -69,10 +81,13 @@ before(async () => {
     for (const cb of load)   await cb()
     for (const cb of loaded) await cb()
 
-    server = await new Promise(resolve => {
-        const s = app.listen(0, () => resolve(s))
-    })
-    port = server.address().port
+    // A protected resource on the same app, gated by the plugin ITSELF —
+    // `auth: identity`, which is the documented shape. Gating with
+    // identity.jwt() instead would test a path most deployments do not take.
+    const { requireAuth } = await import('mikser-io')
+    app.get('/resource', requireAuth(plugin), (req, res) => res.json({ subject: req.principal.subject }))
+    app.get('/resource-admin', requireAuth(plugin.jwt({ requiredCapability: 'api:delete' })),
+        (req, res) => res.json({ ok: true }))
 
     const reg = await fetch(`http://127.0.0.1:${port}/auth/register`, {
         method: 'POST',
@@ -128,7 +143,9 @@ describe('GET /authorize — the login page', () => {
         assert.equal(res.status, 200)
         assert.match(res.headers.get('content-type'), /text\/html/)
         const html = await res.text()
-        assert.match(html, /Sign in to test-mikser\.example/)
+        // The deployment is named by its own declared URL's host, which the
+        // fixture now serves at rather than merely claiming.
+        assert.match(html, new RegExp(`Sign in to ${new URL(runtime.options.url).host.replace('.', '\\.')}`))
         assert.match(html, /to give <strong>Test Client<\/strong> access/)
         assert.match(html, /name="username"[^>]*autocomplete="username"/)
         assert.match(html, /autocomplete="current-password"/)
@@ -477,3 +494,110 @@ describe('POST /register — any agent, no operator config (RFC 7591)', () => {
         assert.equal(res.headers.get('location'), null)
     })
 })
+
+// The loop a real client runs, end to end. Rotation is covered above; this is
+// the part that was never exercised — whether a client can TELL that it should
+// rotate, and complete the round trip without a human.
+//
+// The failure this pins down: an access token expiring mid-task, between a
+// finished decision and the write that would apply it. Refresh tokens were
+// being issued the whole time; nothing told the client the moment to use one.
+describe('an expired access token is recoverable without a human', () => {
+    let refreshToken, key, issuer
+
+    before(async () => {
+        const { verifier, challenge } = pkcePair()
+        const res = await signIn(challenge, { username: 'alice', password: 'alice-pw' })
+        const code = new URL(res.headers.get('location')).searchParams.get('code')
+        const body = await (await token({
+            grant_type: 'authorization_code', code, redirect_uri: REDIRECT,
+            client_id: CLIENT, code_verifier: verifier,
+        })).json()
+        refreshToken = body.refresh_token
+        assert.ok(refreshToken, 'the authorization_code grant must issue a refresh token')
+
+        // Mint an already-expired token for the same subject with the same
+        // key — the state the client reaches an hour later, without waiting
+        // an hour for it.
+        const { loadOrCreateKey } = await import('../lib/keys.js')
+        // The same issuer the running deployment declares — a token minted
+        // for any other one fails verification rather than expiring, which is
+        // the confusion this whole block exists to rule out.
+        issuer = runtime.options.url
+        key = await loadOrCreateKey({ keyFile: path.join(dir, 'auth.key') })
+    })
+
+    const mintExpired = async () => {
+        const { issueToken } = await import('../lib/tokens.js')
+        return issueToken({
+            key, issuer, audience: issuer, subject: 'alice',
+            capabilities: ['api:list', 'api:update'], ttl: '-1s',
+        })
+    }
+
+    it('the resource says WHICH failure it was, not just that there was one', async () => {
+        const expired = await mintExpired()
+        const res = await fetch(url('/resource'), { headers: { authorization: `Bearer ${expired}` } })
+        assert.equal(res.status, 401)
+        const header = res.headers.get('www-authenticate')
+        // The one field a client's refresh logic reads.
+        assert.match(header, /error="invalid_token"/)
+        assert.match(header, /error_description="The access token expired"/)
+    })
+
+    it('and does NOT say it for a request that carried no credential', async () => {
+        // The omission is the signal for "you have never authenticated here".
+        // Claiming invalid_token would send a client to refresh a token it
+        // does not hold.
+        const res = await fetch(url('/resource'))
+        assert.equal(res.status, 401)
+        assert.doesNotMatch(res.headers.get('www-authenticate') ?? '', /error=/)
+    })
+
+    it('completes the whole loop: expire → read the signal → exchange → retry', async () => {
+        const expired = await mintExpired()
+
+        // 1. The call the agent actually wanted to make.
+        const denied = await fetch(url('/resource'), { headers: { authorization: `Bearer ${expired}` } })
+        assert.equal(denied.status, 401)
+
+        // 2. A client decides to refresh ONLY because of this.
+        assert.match(denied.headers.get('www-authenticate'), /error="invalid_token"/)
+
+        // 3. Exchange, with no human anywhere in it.
+        const refreshed = await token({
+            grant_type: 'refresh_token', refresh_token: refreshToken, client_id: CLIENT,
+        })
+        assert.equal(refreshed.status, 200)
+        const body = await refreshed.json()
+        assert.ok(body.access_token)
+        refreshToken = body.refresh_token
+
+        // 4. The retry the whole exercise is for.
+        const retried = await fetch(url('/resource'), {
+            headers: { authorization: `Bearer ${body.access_token}` },
+        })
+        assert.equal(retried.status, 200)
+        assert.equal((await retried.json()).subject, 'alice')
+    })
+
+    it('tells a client NOT to refresh when the token is fine but unauthorized', async () => {
+        // A fresh token for the same subject is refused identically, so a
+        // client that reads this as an expiry loops forever.
+        const { verifier, challenge } = pkcePair()
+        const res = await signIn(challenge, { username: 'alice', password: 'alice-pw' })
+        const code = new URL(res.headers.get('location')).searchParams.get('code')
+        const { access_token } = await (await token({
+            grant_type: 'authorization_code', code, redirect_uri: REDIRECT,
+            client_id: CLIENT, code_verifier: verifier,
+        })).json()
+
+        const denied = await fetch(url('/resource-admin'), {
+            headers: { authorization: `Bearer ${access_token}` },
+        })
+        assert.equal(denied.status, 403)
+        const header = denied.headers.get('www-authenticate')
+        assert.match(header, /error="insufficient_scope"/)
+        assert.match(header, /scope="api:delete"/)
+    })
+})

package/test/verifiers.test.js

@@ -152,6 +152,86 @@ describe('jwt verifier', () => {
         assert.deepEqual(v.authorizationServers, [issuer])
         assert.deepEqual(v.scopesSupported, ['mcp:use'])
     })
+
+    // An expired token and a request that never carried one both come back
+    // `false` — the ADR-0012 contract is three-valued and that is on purpose.
+    // But they are OPPOSITE instructions to a client: one is fixed silently
+    // with a refresh token, the other needs a human and a browser. Told apart
+    // through rejectionFor, which only ever refines a denial.
+    describe('rejectionFor tells the client what to do next', () => {
+        it('names an expired token as expired', async () => {
+            const v = verifier()
+            const r = req(`Bearer ${await mint({ ttl: '-1s' })}`)
+            assert.equal(await v.verify(r), false)
+            const rejection = v.rejectionFor(r)
+            assert.equal(rejection.status, 401)
+            assert.equal(rejection.code, 'invalid_token')
+            assert.equal(rejection.expired, true)
+        })
+
+        it('does NOT claim expiry for a token this server will never accept', async () => {
+            // A client that reads "expired" here burns its refresh token on a
+            // request that fails identically afterwards.
+            const v = verifier()
+            for (const header of ['Bearer not.a.jwt', `Bearer ${await mint({ audience: 'https://elsewhere' })}`]) {
+                const r = req(header)
+                assert.equal(await v.verify(r), false)
+                assert.equal(v.rejectionFor(r).code, 'invalid_token')
+                assert.notEqual(v.rejectionFor(r).expired, true)
+            }
+        })
+
+        it('answers 403 insufficient_scope when the token is good but unauthorized', async () => {
+            const v = verifier({ requiredCapability: 'api:delete' })
+            const r = req(`Bearer ${await mint()}`)
+            assert.equal(await v.verify(r), false)
+            const rejection = v.rejectionFor(r)
+            // Refreshing cannot fix this, and a client that tries loops.
+            assert.equal(rejection.status, 403)
+            assert.equal(rejection.code, 'insufficient_scope')
+            assert.equal(rejection.scope, 'api:delete')
+        })
+
+        it('leaves no rejection behind when the token is accepted', async () => {
+            const v = verifier()
+            const r = req(`Bearer ${await mint()}`)
+            assert.ok(await v.verify(r))
+            assert.equal(v.rejectionFor(r), undefined)
+        })
+
+        it('does not leak one request\'s reason to another', async () => {
+            // The verifier instance is shared across concurrent requests; a
+            // reason kept in its closure would answer for the wrong caller.
+            const v = verifier()
+            const bad = req(`Bearer ${await mint({ ttl: '-1s' })}`)
+            const good = req(`Bearer ${await mint()}`)
+            await v.verify(bad)
+            await v.verify(good)
+            assert.equal(v.rejectionFor(good), undefined)
+            assert.equal(v.rejectionFor(bad).expired, true)
+        })
+
+        it('carries the reason into the WWW-Authenticate header', async () => {
+            const v = verifier()
+            const r = req(`Bearer ${await mint({ ttl: '-1s' })}`)
+            await v.verify(r)
+            const res = { headers: {}, set(k, val) { this.headers[k] = val } }
+            v.challenge(r, res, { code: 'invalid_token', description: 'The access token expired' })
+            const header = res.headers['WWW-Authenticate']
+            assert.match(header, /error="invalid_token"/)
+            assert.match(header, /error_description="The access token expired"/)
+        })
+
+        it('omits error entirely when nothing was presented', async () => {
+            // The omission IS the signal for "you have never authenticated
+            // here" — writing invalid_token would send a client to refresh a
+            // token it does not have.
+            const v = verifier()
+            const res = { headers: {}, set(k, val) { this.headers[k] = val } }
+            v.challenge(req(null), res, { reason: 'missing' })
+            assert.doesNotMatch(res.headers['WWW-Authenticate'], /error=/)
+        })
+    })
 })
 
 describe('row scope survives the JWT round trip', () => {