mikser-io-auth 0.6.1 → 0.7.0

package/index.js

@@ -159,6 +159,7 @@ export function auth(options = {}) {
                 issuerFor:   originOf,
                 audienceFor: (req) => audience ?? originOf(req),
                 dcr,
+                scopes: [...new Set(Object.values(capabilities).flat())],
                 logger,
             })
 
@@ -177,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

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.1",
+  "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

@@ -242,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')
@@ -450,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 () => {
@@ -601,3 +607,79 @@ describe('an expired access token is recoverable without a human', () => {
         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'))
+    })
+})