mikser-io-auth 0.6.0 → 0.7.0

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
@@ -147,6 +159,7 @@ export function auth(options = {}) {
                 issuerFor:   originOf,
                 audienceFor: (req) => audience ?? originOf(req),
                 dcr,
+                scopes: [...new Set(Object.values(capabilities).flat())],
                 logger,
             })
 
@@ -165,7 +178,8 @@ export function auth(options = {}) {
             // rather than insert the well-known segment find it there.
             if (base && base !== '/') {
                 app.get('/.well-known/oauth-authorization-server',
-                    metadataHandler({ base, issuerFor: originOf }))
+                    metadataHandler({ base, issuerFor: originOf,
+                        scopes: [...new Set(Object.values(capabilities).flat())] }))
             }
 
             // Codes are 60s and refresh tokens 30d; without a sweep the rows
@@ -231,7 +245,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/routes.js

@@ -12,6 +12,12 @@ import * as grants from './grants.js'
 const CODE_TTL_SEC    = 60
 const REFRESH_TTL_SEC = 30 * 24 * 60 * 60
 
+// RFC 6749 §3.3 / OIDC's name for "this client may hold a refresh token and use
+// it without the user present". It is not one of this deployment's capabilities
+// — it grants no access to anything — but it is the only standard way to TELL a
+// client that unattended renewal is available to it.
+const OFFLINE_ACCESS = 'offline_access'
+
 // The subset of an authorization request threaded through the login form's
 // hidden fields, untouched.
 function authParams(src) {
@@ -28,11 +34,16 @@ function authParams(src) {
 // under `base`, so its own copy answers one level down — where a client that
 // appends to the issuer looks, and nowhere a client following RFC 8414 does.
 // index.js mounts this at the root as well; both paths return this document.
-export function metadataHandler({ base, issuerFor }) {
+export function metadataHandler({ base, issuerFor, scopes = [] }) {
     return (req, res) => {
         const issuer = issuerFor(req)
         res.json({
             issuer,
+            // RECOMMENDED by RFC 8414 §2 and load-bearing here: without it a
+            // client cannot discover that offline_access is available, so it
+            // never asks, so it never learns it may renew unattended — while a
+            // refresh token sits unused in every token response.
+            scopes_supported: [...new Set([...scopes, OFFLINE_ACCESS])],
             authorization_endpoint:                `${issuer}${base}/authorize`,
             token_endpoint:                        `${issuer}${base}/token`,
             jwks_uri:                              `${issuer}${base}/jwks.json`,
@@ -47,7 +58,7 @@ export function metadataHandler({ base, issuerFor }) {
 }
 
 export function mountRoutes(router, ctx) {
-    const { base, nameOf, ready, logoUrl, ttl, issuerFor, audienceFor, dcr, logger } = ctx
+    const { base, nameOf, ready, logoUrl, ttl, issuerFor, audienceFor, dcr, scopes = [], logger } = ctx
 
     const { windowMs = 60 * 60 * 1000, maxPerIp = 5, maxClients = 1000 } = dcr ?? {}
 
@@ -68,7 +79,7 @@ export function mountRoutes(router, ctx) {
         res.json(jwks({ publicJwk: ready().key.publicJwk }))
     })
 
-    router.get('/.well-known/oauth-authorization-server', metadataHandler({ base, issuerFor }))
+    router.get('/.well-known/oauth-authorization-server', metadataHandler({ base, issuerFor, scopes }))
 
     // ── /authorize ───────────────────────────────────────────────────────
     //
@@ -181,6 +192,14 @@ export function mountRoutes(router, ctx) {
             body.refresh_token = grants.createRefreshToken({
                 clientId, subject, ttlSec: REFRESH_TTL_SEC,
             })
+            // Say that unattended renewal was granted, not just hand over the
+            // means to do it. Per RFC 6749 §5.1 the response scope is what the
+            // client was actually granted; returning the capability list alone
+            // told a client that asked for offline_access that it had been
+            // REFUSED, so a conforming one would not use the refresh token it
+            // had just been given. Measured symptom: a fixed one-hour window
+            // that never renewed, and a human re-authorizing by hand.
+            body.scope = [...capabilities, OFFLINE_ACCESS].join(' ')
         }
         res.json(body)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-auth",
-  "version": "0.6.0",
+  "version": "0.7.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/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"/)
@@ -225,7 +242,13 @@ describe('POST /token — authorization_code', () => {
         const body = await res.json()
         assert.equal(body.token_type, 'Bearer')
         assert.ok(body.refresh_token)
-        assert.equal(body.scope, 'api:list api:update')
+        // offline_access rides along BECAUSE a refresh token was issued. Per
+        // RFC 6749 §5.1 the response scope is what the client was granted, and
+        // handing over a refresh token while reporting a scope without
+        // offline_access tells a conforming client it was refused — so it does
+        // not renew, and the window becomes a hard one-hour cliff.
+        assert.equal(body.scope, 'api:list api:update offline_access')
+        assert.ok(body.refresh_token, 'the grant that says offline_access must actually issue one')
 
         const claims = JSON.parse(Buffer.from(body.access_token.split('.')[1], 'base64url').toString())
         assert.equal(claims.sub, 'alice')
@@ -433,7 +456,7 @@ describe('POST /register — any agent, no operator config (RFC 7591)', () => {
             redirect_uri: 'http://127.0.0.1:7788/cb',
             code_verifier: verifier, client_id: reg.client_id,
         })).json()
-        assert.equal(tok.scope, 'api:list api:update')
+        assert.equal(tok.scope, 'api:list api:update offline_access')
     })
 
     it('escapes a client name — it is attacker-controlled and lands on the page', async () => {
@@ -477,3 +500,186 @@ 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"/)
+    })
+})
+
+// A fixed one-hour window that never renewed, and a human re-authorizing by
+// hand — twice in one working session, the second time between a finished
+// decision and the write that would have applied it.
+//
+// The refresh token was there the whole time. What was missing was the sentence
+// that tells a client it may use one.
+describe('unattended renewal is granted out loud, not just made possible', () => {
+    it('advertises offline_access, so a client can discover it exists', async () => {
+        const meta = await (await fetch(url('/auth/.well-known/oauth-authorization-server'))).json()
+        assert.ok(meta.scopes_supported, 'RFC 8414 §2 RECOMMENDS scopes_supported; without it nothing is discoverable')
+        assert.ok(meta.scopes_supported.includes('offline_access'))
+        // The deployment's real capabilities are listed too, so a client can
+        // see what it is allowed to ask for rather than guessing.
+        assert.ok(meta.scopes_supported.includes('api:update'))
+        assert.ok(meta.grant_types_supported.includes('refresh_token'))
+    })
+
+    it('grants offline_access exactly when it hands over a refresh token', 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()
+        assert.ok(body.refresh_token)
+        assert.ok(body.scope.split(' ').includes('offline_access'),
+            'handing over a refresh token while reporting a scope without offline_access tells a '
+            + 'conforming client it was REFUSED, so it never renews')
+    })
+
+    it('does NOT claim it for a grant that issues no refresh token', async () => {
+        // The password grant deliberately issues none — a caller that can
+        // replay the password does not need one. Claiming offline_access there
+        // would promise renewal that cannot happen.
+        const body = await (await token({
+            grant_type: 'password', username: 'alice', password: 'alice-pw',
+        })).json()
+        assert.equal(body.refresh_token, undefined)
+        assert.equal(body.scope.split(' ').includes('offline_access'), false)
+    })
+
+    it('keeps offline_access OUT of the token claims, because it grants no access', async () => {
+        // It is a property of the grant, not a capability. A resource server
+        // checking capabilities must never see it in the list, or it becomes a
+        // permission nobody meant to give.
+        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()
+        const claims = JSON.parse(Buffer.from(body.access_token.split('.')[1], 'base64url').toString())
+        assert.equal(claims.scope, 'api:list api:update')
+        assert.equal(String(claims.scope).includes('offline_access'), false)
+    })
+
+    it('keeps granting it on refresh, so renewal does not decay after one hop', async () => {
+        // A rotated refresh token that came back without offline_access would
+        // renew exactly once and then look refused.
+        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 first = await (await token({
+            grant_type: 'authorization_code', code, redirect_uri: REDIRECT,
+            client_id: CLIENT, code_verifier: verifier,
+        })).json()
+        const second = await (await token({
+            grant_type: 'refresh_token', refresh_token: first.refresh_token, client_id: CLIENT,
+        })).json()
+        assert.ok(second.refresh_token)
+        assert.ok(second.scope.split(' ').includes('offline_access'))
+    })
+})