mikser-io-auth 0.5.2 → 0.6.0

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/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.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",

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', () => {