@growth-labs/auth 0.12.0 → 0.14.0

package/README.md

@@ -50,6 +50,7 @@ auth({
 2. Verifies access token JWT against the internal issuer's JWKS (`{issuerInternal ?? issuer}/.well-known/jwks.json`, cached in Worker memory)
 3. Requires the access token `aud` to match `resource`; wrong or missing audiences remain unauthenticated
 4. If expired but refresh token valid → silent refresh, verify the new access token audience, then set new cookies
+   — one exchange per token per isolate, and never on a beacon or a prefetch (those are answered as a guest / `425`, and the next real request refreshes)
 5. Populates `context.locals.user` as `User | null`
 6. If path matches `gatedPaths` and `user` is null → redirect to `loginPath`
 

package/dist/middleware/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AACA,OAAO,sBAAsB,CAAA;AAc7B,wBAAsB,SAAS,CAC9B,OAAO,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACxE,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAsGnB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AACA,OAAO,sBAAsB,CAAA;AAmB7B,wBAAsB,SAAS,CAC9B,OAAO,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EACxE,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAC3B,OAAO,CAAC,QAAQ,CAAC,CA0KnB"}

package/dist/middleware/auth.js

@@ -4,6 +4,7 @@ import { resolveClientSecret } from '../utils/client-secret.js';
 import { getCookie, setTokenCookies } from '../utils/cookies.js';
 import { secretResolutionFailureResponse } from '../utils/fail-closed.js';
 import { resolveInternalIssuer } from '../utils/issuer.js';
+import { classifyRefreshCarrier, prefetchDeferredResponse, } from '../utils/refresh-carrier.js';
 import { refreshTokens, verifyAccessToken } from '../utils/tokens.js';
 const PRIVATE_NO_STORE_HEADERS = [
     'Cache-Control',
@@ -54,9 +55,22 @@ export async function onRequest(context, next) {
             }
         }
     }
+    // A refresh rotates the token, and only a response the browser is waiting
+    // for can deliver the successor. A beacon or a prefetch that would need one
+    // does not get it: the request is answered as `deferred` and the next
+    // consumable request refreshes instead (refresh-carrier.ts says why).
+    let refreshFailure = null;
+    let deferredCarrier = null;
     if (!user && refreshToken) {
+        const carrier = classifyRefreshCarrier(request);
+        if (carrier !== 'consumable')
+            deferredCarrier = carrier;
+    }
+    if (!user && refreshToken && deferredCarrier === null) {
         const clientId = options.clientId || context.url.hostname;
-        refreshed = await refreshTokens(issuer, refreshToken, clientId, resolvedClientSecret, options.resource);
+        refreshed = await refreshTokens(issuer, refreshToken, clientId, resolvedClientSecret, options.resource, (failure) => {
+            refreshFailure = failure;
+        });
         if (refreshed) {
             user = {
                 id: refreshed.claims.sub,
@@ -66,11 +80,66 @@ export async function onRequest(context, next) {
             };
         }
     }
-    // 3. Populate context.locals.user
+    // 3. Populate context.locals.user and say HOW the session resolved. A site
+    // cannot act on `user === null` alone: an anonymous visitor, a member whose
+    // refresh token the issuer has definitively rejected, and a member caught by
+    // a passing issuer fault all look the same, and the second one was being
+    // rendered the locked page with dead cookies he could only fix by logging
+    // out and back in.
     context.locals.user = user;
+    const session = resolveSessionState({
+        user,
+        refreshed: refreshed !== null,
+        hadAccessToken: accessToken !== null,
+        hadRefreshToken: refreshToken !== null,
+        refreshFailure,
+        deferred: deferredCarrier !== null,
+    });
+    context.locals.authSession = session;
+    // The cookies are deliberately left alone, even when the state is `expired`.
+    // The issuer keeps refresh tokens in an eventually consistent store, so a
+    // token only seconds old can read as missing from another location and be
+    // answered invalid_grant; today that costs one anonymous page and heals on
+    // the next navigation, and clearing would turn it into a forced sign-in.
+    // Recovery never needed the clear: signing in again overwrites them.
+    const documentNavigation = isDocumentNavigation(request);
+    if (deferredCarrier !== null) {
+        try {
+            console.info('[auth] session refresh deferred', {
+                carrier: deferredCarrier,
+                pathname: context.url.pathname,
+            });
+        }
+        catch {
+            /* a patched console must not turn a guest page into a 500 */
+        }
+        // A prefetched document rendered as a guest would be shown to the member
+        // on navigation as if they had signed out; a non-2xx is dropped instead.
+        if (deferredCarrier === 'prefetch')
+            return prefetchDeferredResponse();
+    }
+    else if (!user && refreshToken) {
+        const failure = refreshFailure ?? { reason: 'unreported' };
+        try {
+            console.warn('[auth] session refresh failed', {
+                ...failure,
+                pathname: context.url.pathname,
+                documentNavigation,
+                session,
+            });
+        }
+        catch {
+            /* a patched console must not turn a guest page into a 500 */
+        }
+    }
     // 4. Gate protected paths
     if (!user && isGatedPath(context.url.pathname, options.gatedPaths)) {
-        const loginUrl = new URL(`${options.loginPath}?redirect=${encodeURIComponent(context.url.pathname)}`, context.url.origin);
+        // Only the issuer ending the session earns the error code, which is the
+        // one the login renderer already knows how to explain. A rejected access
+        // token with no refresh token beside it (wrong audience, say) is not a
+        // session that ended, and its redirect stays exactly as it always was.
+        const sessionEnded = refreshFailure?.reason === 'invalid_grant';
+        const loginUrl = new URL(`${options.loginPath}?redirect=${encodeURIComponent(context.url.pathname)}${sessionEnded ? '&error=session_expired' : ''}`, context.url.origin);
         return Response.redirect(loginUrl.toString(), 302);
     }
     // 5. Continue to the page
@@ -94,6 +163,30 @@ export async function onRequest(context, next) {
     }
     return response;
 }
+function resolveSessionState(input) {
+    if (input.user)
+        return input.refreshed ? 'refreshed' : 'verified';
+    if (!input.hadAccessToken && !input.hadRefreshToken)
+        return 'anonymous';
+    if (input.deferred)
+        return 'deferred';
+    // A rejected access token with no refresh token beside it cannot be revived.
+    if (!input.hadRefreshToken)
+        return 'expired';
+    return input.refreshFailure?.reason === 'invalid_grant' ? 'expired' : 'refresh_failed';
+}
+/** Sec-Fetch-* is authoritative where the browser sends it; Accept is the fallback. */
+function isDocumentNavigation(request) {
+    if (request.method !== 'GET')
+        return false;
+    const dest = request.headers.get('sec-fetch-dest');
+    if (dest)
+        return dest === 'document';
+    const mode = request.headers.get('sec-fetch-mode');
+    if (mode)
+        return mode === 'navigate';
+    return (request.headers.get('accept') ?? '').includes('text/html');
+}
 function isGatedPath(pathname, gatedPaths) {
     return gatedPaths.some((pattern) => {
         if (pattern.endsWith('/*')) {

package/dist/middleware/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,sBAAsB,CAAA;AAE7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAChE,OAAO,EAAE,+BAA+B,EAAE,MAAM,yBAAyB,CAAA;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,OAAO,EACN,sBAAsB,EACtB,wBAAwB,GAExB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAuB,aAAa,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAE1F,MAAM,wBAAwB,GAAG;IAChC,eAAe;IACf,mBAAmB;IACnB,8BAA8B;CACrB,CAAA;AAEV,MAAM,CAAC,KAAK,UAAU,SAAS,CAC9B,OAAwE,EACxE,IAA6B;IAE7B,MAAM,OAAO,GAAG,SAAS,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;IAC7C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAA;IAE3B,8BAA8B;IAC9B,MAAM,WAAW,GAAG,SAAS,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,YAAY,KAAK,CAAC,CAAA;IACpE,MAAM,YAAY,GAAG,SAAS,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,YAAY,KAAK,CAAC,CAAA;IAErE,6BAA6B;IAC7B,IAAI,IAAI,GAAgB,IAAI,CAAA;IAC5B,IAAI,SAAS,GAA8C,IAAI,CAAA;IAC/D,IAAI,oBAAwC,CAAA;IAE5C,uEAAuE;IACvE,0EAA0E;IAC1E,wEAAwE;IACxE,0EAA0E;IAC1E,4EAA4E;IAC5E,2EAA2E;IAC3E,0EAA0E;IAC1E,uEAAuE;IACvE,IAAI,YAAY,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACxD,MAAM,YAAY,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;QAC7E,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;YACtB,OAAO,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;YAC1B,OAAO,+BAA+B,CAAC,OAAO,EAAE;gBAC/C,OAAO,EAAE,oBAAoB;gBAC7B,IAAI,EAAE,YAAY,CAAC,IAAI;aACvB,CAAC,CAAA;QACH,CAAC;QACD,oBAAoB,GAAG,YAAY,CAAC,MAAM,IAAI,SAAS,CAAA;IACxD,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QACjB,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC7F,IAAI,QAAQ,EAAE,CAAC;YACd,IAAI,GAAG;gBACN,EAAE,EAAE,QAAQ,CAAC,GAAG;gBAChB,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,IAAI;gBAC3B,SAAS,EAAE,QAAQ,CAAC,KAAK,IAAI,IAAI;aACjC,CAAA;YACD,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,IAAI,QAAQ,CAAC,OAAO,KAAK,YAAY,EAAE,CAAC;gBACtE,OAAO,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAA;YAChC,CAAC;QACF,CAAC;IACF,CAAC;IAED,0EAA0E;IAC1E,4EAA4E;IAC5E,sEAAsE;IACtE,sEAAsE;IACtE,IAAI,cAAc,GAAG,IAA6B,CAAA;IAClD,IAAI,eAAe,GAA0B,IAAI,CAAA;IACjD,IAAI,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAA;QAC/C,IAAI,OAAO,KAAK,YAAY;YAAE,eAAe,GAAG,OAAO,CAAA;IACxD,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,YAAY,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAA;QACzD,SAAS,GAAG,MAAM,aAAa,CAC9B,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,oBAAoB,EACpB,OAAO,CAAC,QAAQ,EAChB,CAAC,OAAO,EAAE,EAAE;YACX,cAAc,GAAG,OAAO,CAAA;QACzB,CAAC,CACD,CAAA;QACD,IAAI,SAAS,EAAE,CAAC;YACf,IAAI,GAAG;gBACN,EAAE,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG;gBACxB,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK;gBAC7B,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI;gBACnC,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI;aACzC,CAAA;QACF,CAAC;IACF,CAAC;IAED,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,yEAAyE;IACzE,0EAA0E;IAC1E,mBAAmB;IACnB,OAAO,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;IAC1B,MAAM,OAAO,GAAG,mBAAmB,CAAC;QACnC,IAAI;QACJ,SAAS,EAAE,SAAS,KAAK,IAAI;QAC7B,cAAc,EAAE,WAAW,KAAK,IAAI;QACpC,eAAe,EAAE,YAAY,KAAK,IAAI;QACtC,cAAc;QACd,QAAQ,EAAE,eAAe,KAAK,IAAI;KAClC,CAAC,CAAA;IACF,OAAO,CAAC,MAAM,CAAC,WAAW,GAAG,OAAO,CAAA;IAEpC,6EAA6E;IAC7E,0EAA0E;IAC1E,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,qEAAqE;IACrE,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAA;IAExD,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC;YACJ,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE;gBAC/C,OAAO,EAAE,eAAe;gBACxB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ;aAC9B,CAAC,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACR,6DAA6D;QAC9D,CAAC;QACD,yEAAyE;QACzE,yEAAyE;QACzE,IAAI,eAAe,KAAK,UAAU;YAAE,OAAO,wBAAwB,EAAE,CAAA;IACtE,CAAC;SAAM,IAAI,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;QAClC,MAAM,OAAO,GAAmB,cAAc,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;QAC1E,IAAI,CAAC;YACJ,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE;gBAC7C,GAAG,OAAO;gBACV,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ;gBAC9B,kBAAkB;gBAClB,OAAO;aACP,CAAC,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACR,6DAA6D;QAC9D,CAAC;IACF,CAAC;IAED,0BAA0B;IAC1B,IAAI,CAAC,IAAI,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACpE,wEAAwE;QACxE,yEAAyE;QACzE,uEAAuE;QACvE,uEAAuE;QACvE,MAAM,YAAY,GAAG,cAAc,EAAE,MAAM,KAAK,eAAe,CAAA;QAC/D,MAAM,QAAQ,GAAG,IAAI,GAAG,CACvB,GAAG,OAAO,CAAC,SAAS,aAAa,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GACxE,YAAY,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAC3C,EAAE,EACF,OAAO,CAAC,GAAG,CAAC,MAAM,CAClB,CAAA;QACD,OAAO,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAA;IACnD,CAAC;IAED,0BAA0B;IAC1B,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAA;IAE7B,oFAAoF;IACpF,IAAI,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QACpD,MAAM,gBAAgB,GAAG,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE;YACpD,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,OAAO,EAAE,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;SACtC,CAAC,CAAA;QACF,IAAI,SAAS,EAAE,CAAC;YACf,eAAe,CAAC,gBAAgB,EAAE,OAAO,EAAE,SAAS,CAAC,WAAW,EAAE,SAAS,CAAC,YAAY,CAAC,CAAA;QAC1F,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YACvC,KAAK,MAAM,MAAM,IAAI,wBAAwB,EAAE,CAAC;gBAC/C,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;YAC1D,CAAC;QACF,CAAC;QACD,OAAO,gBAAgB,CAAA;IACxB,CAAC;IAED,OAAO,QAAQ,CAAA;AAChB,CAAC;AAED,SAAS,mBAAmB,CAAC,KAO5B;IACA,IAAI,KAAK,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAA;IACjE,IAAI,CAAC,KAAK,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,eAAe;QAAE,OAAO,WAAW,CAAA;IACvE,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,UAAU,CAAA;IACrC,6EAA6E;IAC7E,IAAI,CAAC,KAAK,CAAC,eAAe;QAAE,OAAO,SAAS,CAAA;IAC5C,OAAO,KAAK,CAAC,cAAc,EAAE,MAAM,KAAK,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAA;AACvF,CAAC;AAED,uFAAuF;AACvF,SAAS,oBAAoB,CAAC,OAAgB;IAC7C,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK;QAAE,OAAO,KAAK,CAAA;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAA;IAClD,IAAI,IAAI;QAAE,OAAO,IAAI,KAAK,UAAU,CAAA;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAA;IAClD,IAAI,IAAI;QAAE,OAAO,IAAI,KAAK,UAAU,CAAA;IACpC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;AACnE,CAAC;AAED,SAAS,WAAW,CAAC,QAAgB,EAAE,UAAoB;IAC1D,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAClC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA,CAAC,6BAA6B;YACjE,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;QACnC,CAAC;QACD,OAAO,QAAQ,KAAK,OAAO,CAAA;IAC5B,CAAC,CAAC,CAAA;AACH,CAAC"}

package/dist/routes/logout.js

@@ -36,7 +36,7 @@ export async function GET(context) {
     }
     // Emit auth_logout (non-blocking) when the consumer has @growth-labs/analytics
     // wired. Without analytics installed this is a no-op (analyticsAvailable
-    // returns false). Documented in packages-docs/event-registry.md.
+    // returns false). Documented in packages/analytics/EVENT_REGISTRY.md (growth-labs/publishing).
     if (analyticsAvailable(context)) {
         const promise = emitAuthEvent(context, 'auth_logout', {
             revoked: refreshToken ? 'true' : 'false',

package/dist/routes/logout.js.map

@@ -1 +1 @@
-{"version":3,"file":"logout.js","sourceRoot":"","sources":["../../src/routes/logout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logout.js","sourceRoot":"","sources":["../../src/routes/logout.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -131,10 +131,26 @@ export interface TokenExchangeResult {
         image?: string;
     };
 }
+/**
+ * How the request's session resolved. `user === null` alone cannot tell a site
+ * what to do: `anonymous` never signed in; `expired` holds credentials that
+ * could not be revived on this request — the issuer answered the refresh token
+ * `invalid_grant`, or a rejected access token arrived with no refresh token
+ * beside it — so offer a sign-in-again path; `refresh_failed` hit a fault that
+ * may pass; `deferred` holds a refresh token this request deliberately did not
+ * spend, because it is a beacon or a prefetch whose response the browser would
+ * not apply (0.14.0) — the next consumable request refreshes, so treat it as a
+ * guest request and nothing more. NONE is proof the session is dead (the
+ * issuer's token store is eventually consistent), so never clear cookies on
+ * them: signing in again overwrites the cookies, and the middleware itself
+ * clears nothing.
+ */
+export type AuthSessionState = 'anonymous' | 'verified' | 'refreshed' | 'expired' | 'refresh_failed' | 'deferred';
 declare global {
     namespace App {
         interface Locals {
             user: User | null;
+            authSession?: AuthSessionState;
             synthetic?: boolean;
         }
     }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -7,6 +7,7 @@ export { type BridgeMigrationOptions, type BridgeMigrationStatement, buildLegacy
 export { signIdentityCookie, verifyIdentityCookie } from './identity-cookie.js';
 export { EXCHANGE_SECRET_FAILURE, type ExchangeSecretFailure, getAuthorizationUrl, getMagicLinkUrl, getPasswordLoginUrl, } from './openauth.js';
 export { createPKCEChallenge, generatePKCE } from './pkce.js';
+export { classifyRefreshCarrier, prefetchDeferredResponse, type RefreshCarrier, } from './refresh-carrier.js';
 export { generateState, verifyState } from './state.js';
-export type { VerifiedClaims } from './tokens.js';
+export type { RefreshFailure, RefreshFailureReason, VerifiedClaims } from './tokens.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACd,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACX,mBAAmB,EACnB,+BAA+B,EAC/B,kBAAkB,GAClB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC/E,OAAO,EACN,kBAAkB,EAClB,KAAK,OAAO,EACZ,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,aAAa,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EACN,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,gCAAgC,EAChC,mCAAmC,EACnC,wBAAwB,EACxB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,6BAA6B,GAC7B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EACN,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,eAAe,EACf,mBAAmB,GACnB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACd,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACX,mBAAmB,EACnB,+BAA+B,EAC/B,kBAAkB,GAClB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC/E,OAAO,EACN,kBAAkB,EAClB,KAAK,OAAO,EACZ,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,aAAa,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EACN,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,gCAAgC,EAChC,mCAAmC,EACnC,wBAAwB,EACxB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,6BAA6B,GAC7B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EACN,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,mBAAmB,EACnB,eAAe,EACf,mBAAmB,GACnB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EACN,sBAAsB,EACtB,wBAAwB,EACxB,KAAK,cAAc,GACnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACvD,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/utils/index.js

@@ -6,5 +6,6 @@ export { buildLegacyIdentitySubjectCanary, buildLegacyIdentitySubjectMigration,
 export { signIdentityCookie, verifyIdentityCookie } from './identity-cookie.js';
 export { EXCHANGE_SECRET_FAILURE, getAuthorizationUrl, getMagicLinkUrl, getPasswordLoginUrl, } from './openauth.js';
 export { createPKCEChallenge, generatePKCE } from './pkce.js';
+export { classifyRefreshCarrier, prefetchDeferredResponse, } from './refresh-carrier.js';
 export { generateState, verifyState } from './state.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACd,MAAM,gBAAgB,CAAA;AAMvB,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC/E,OAAO,EACN,kBAAkB,EAElB,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,aAAa,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAGN,gCAAgC,EAChC,mCAAmC,EACnC,wBAAwB,EACxB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,6BAA6B,GAC7B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EACN,uBAAuB,EAEvB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,GACnB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACd,MAAM,gBAAgB,CAAA;AAMvB,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC/E,OAAO,EACN,kBAAkB,EAElB,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,aAAa,GACb,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAGN,gCAAgC,EAChC,mCAAmC,EACnC,wBAAwB,EACxB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,6BAA6B,GAC7B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EACN,uBAAuB,EAEvB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,GACnB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EACN,sBAAsB,EACtB,wBAAwB,GAExB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/utils/refresh-carrier.d.ts

@@ -0,0 +1,10 @@
+export type RefreshCarrier = 'consumable' | 'beacon' | 'prefetch';
+export declare function classifyRefreshCarrier(request: Request): RefreshCarrier;
+/**
+ * The answer to a prefetch that would have needed a refresh. Non-2xx, so the
+ * browser drops it and navigates for real; 425 because the server declines a
+ * request it may never be asked to honour. `Vary` keeps a shared cache from
+ * serving it to the navigation.
+ */
+export declare function prefetchDeferredResponse(): Response;
+//# sourceMappingURL=refresh-carrier.d.ts.map

package/dist/utils/refresh-carrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-carrier.d.ts","sourceRoot":"","sources":["../../src/utils/refresh-carrier.ts"],"names":[],"mappings":"AA2BA,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAA;AAyBjE,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAIvE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,QAAQ,CASnD"}

package/dist/utils/refresh-carrier.js

@@ -0,0 +1,76 @@
+// Which requests may spend a refresh token.
+//
+// A refresh rotates the token: the issuer retires the one presented and the
+// response carries its successor as a Set-Cookie. If that response is never
+// applied, the browser keeps presenting a token nothing will accept again, and
+// the member is locked out until they sign in again (fronts, 2026-09: the
+// issuer's `oauth.token_refresh.rejected` with disposition `rotated` and an
+// `unused` successor is exactly this shape). So a refresh belongs only on a
+// request whose response the browser is waiting for and will apply:
+//
+// - A beacon (`navigator.sendBeacon`, `fetch` with `mode: 'no-cors'`, an
+//   `<a ping>`, a Reporting API upload) is fire-and-forget. Its response is
+//   discarded, often after the document that sent it is gone. Refreshing on
+//   one spends the token for nobody. The request proceeds as a guest and the
+//   next consumable request refreshes instead.
+//
+// - A prefetch or prerender (speculation rules, `<link rel="prefetch">`) is
+//   speculative: it is the request class the browser cancels most (fronts:
+//   6.5% of prefetches end `canceled` against 1.4% of all requests), and a
+//   prefetched document rendered as a guest would be shown to the member on
+//   navigation as if they had been signed out. The request is answered with a
+//   non-2xx the browser will not use, so the real navigation refreshes.
+//
+// Sec-Fetch-* and Sec-Purpose are browser-set and cannot be forged by page
+// script. Where a client sends none of them, the request is treated as
+// consumable, which is exactly the pre-0.14 behaviour.
+function headerLower(request, name) {
+    return (request.headers.get(name) ?? '').toLowerCase();
+}
+/** Speculation-rules and legacy prefetch/prerender markers. */
+function isPrefetch(request) {
+    const secPurpose = headerLower(request, 'sec-purpose');
+    if (secPurpose.includes('prefetch') || secPurpose.includes('prerender'))
+        return true;
+    if (headerLower(request, 'purpose') === 'prefetch')
+        return true;
+    const xPurpose = headerLower(request, 'x-purpose');
+    if (xPurpose === 'prefetch' || xPurpose === 'preview')
+        return true;
+    return headerLower(request, 'x-moz') === 'prefetch';
+}
+/** Fire-and-forget requests whose response nobody reads. */
+function isBeacon(request) {
+    const dest = headerLower(request, 'sec-fetch-dest');
+    if (dest === 'report')
+        return true;
+    if (dest === 'empty' && headerLower(request, 'sec-fetch-mode') === 'no-cors')
+        return true;
+    if (headerLower(request, 'content-type').startsWith('text/ping'))
+        return true;
+    return request.headers.has('ping-to');
+}
+export function classifyRefreshCarrier(request) {
+    if (isPrefetch(request))
+        return 'prefetch';
+    if (isBeacon(request))
+        return 'beacon';
+    return 'consumable';
+}
+/**
+ * The answer to a prefetch that would have needed a refresh. Non-2xx, so the
+ * browser drops it and navigates for real; 425 because the server declines a
+ * request it may never be asked to honour. `Vary` keeps a shared cache from
+ * serving it to the navigation.
+ */
+export function prefetchDeferredResponse() {
+    return new Response(null, {
+        status: 425,
+        statusText: 'Too Early',
+        headers: {
+            'Cache-Control': 'private, no-store',
+            Vary: 'Sec-Purpose, Cookie',
+        },
+    });
+}
+//# sourceMappingURL=refresh-carrier.js.map

package/dist/utils/refresh-carrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-carrier.js","sourceRoot":"","sources":["../../src/utils/refresh-carrier.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,oEAAoE;AACpE,EAAE;AACF,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,6EAA6E;AAC7E,+CAA+C;AAC/C,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAC9E,wEAAwE;AACxE,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,uDAAuD;AAIvD,SAAS,WAAW,CAAC,OAAgB,EAAE,IAAY;IAClD,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;AACvD,CAAC;AAED,+DAA+D;AAC/D,SAAS,UAAU,CAAC,OAAgB;IACnC,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IACtD,IAAI,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAA;IACpF,IAAI,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,KAAK,UAAU;QAAE,OAAO,IAAI,CAAA;IAC/D,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,CAAA;IAClD,IAAI,QAAQ,KAAK,UAAU,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAClE,OAAO,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,UAAU,CAAA;AACpD,CAAC;AAED,4DAA4D;AAC5D,SAAS,QAAQ,CAAC,OAAgB;IACjC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAA;IACnD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAClC,IAAI,IAAI,KAAK,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACzF,IAAI,WAAW,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAA;IAC7E,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACtD,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,UAAU,CAAA;IAC1C,IAAI,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,QAAQ,CAAA;IACtC,OAAO,YAAY,CAAA;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB;IACvC,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACzB,MAAM,EAAE,GAAG;QACX,UAAU,EAAE,WAAW;QACvB,OAAO,EAAE;YACR,eAAe,EAAE,mBAAmB;YACpC,IAAI,EAAE,qBAAqB;SAC3B;KACD,CAAC,CAAA;AACH,CAAC"}

package/dist/utils/refresh-flight.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Run `exchange` unless an identical exchange is already in flight in this
+ * isolate, in which case share its promise. `parts` identify the exchange:
+ * issuer, client, resource and the refresh token.
+ */
+export declare function singleFlightRefresh<T>(parts: readonly string[], exchange: () => Promise<T>): Promise<T>;
+/** @internal Test-only. Reports how many refreshes are in flight right now. */
+export declare function _refreshFlightsInProgress(): number;
+//# sourceMappingURL=refresh-flight.d.ts.map

package/dist/utils/refresh-flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-flight.d.ts","sourceRoot":"","sources":["../../src/utils/refresh-flight.ts"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACpC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,IAAI,MAAM,CAElD"}

package/dist/utils/refresh-flight.js

@@ -0,0 +1,55 @@
+// One in-flight refresh per refresh token, per isolate.
+//
+// A page whose access token has just expired does not send one request: the
+// document, its same-origin fetches, images and prefetches all arrive within
+// the same second, every one carrying the same refresh token, and every one
+// used to POST /token on its own. The issuer converges them — inside its
+// reuse window (identity-platform: 600s) a re-presented token gets the same
+// successor back — so the race was never a rejection, but it was N exchanges,
+// N JWKS verifications and N marker writes for one rotation. Callers that
+// arrive while an exchange for the same token is in flight now await that
+// exchange and receive its outcome, success or failure alike.
+//
+// Scope is deliberately the isolate. Two tabs are two documents but one
+// cookie jar, so their concurrent refreshes carry the same token and land, in
+// practice, on the same colo and usually the same isolate; where they do not,
+// the issuer's reuse window already converges them, and a cross-isolate lock
+// (KV, Durable Object) would put a network round trip and a new dependency on
+// every refresh to solve a case that is already solved. Nothing is retained
+// after the flight settles for the same reason: a client-side successor cache
+// would be a weaker copy of the issuer's reuse window.
+//
+// The map lives only in this isolate's memory and is keyed on the token
+// together with its client context. Keying synchronously is what makes the
+// guarantee hold: a caller that arrives while a flight is registered shares it,
+// with no asynchronous gap between "look" and "register" for a second caller
+// to slip through. The token is already held as a string by the request that
+// carried it, so the key adds nothing a heap dump did not have.
+const inFlight = new Map();
+function flightKey(parts) {
+    return parts.join('\u001f');
+}
+/**
+ * Run `exchange` unless an identical exchange is already in flight in this
+ * isolate, in which case share its promise. `parts` identify the exchange:
+ * issuer, client, resource and the refresh token.
+ */
+export function singleFlightRefresh(parts, exchange) {
+    const key = flightKey(parts);
+    const existing = inFlight.get(key);
+    if (existing)
+        return existing;
+    const flight = Promise.resolve()
+        .then(exchange)
+        .finally(() => {
+        if (inFlight.get(key) === flight)
+            inFlight.delete(key);
+    });
+    inFlight.set(key, flight);
+    return flight;
+}
+/** @internal Test-only. Reports how many refreshes are in flight right now. */
+export function _refreshFlightsInProgress() {
+    return inFlight.size;
+}
+//# sourceMappingURL=refresh-flight.js.map

package/dist/utils/refresh-flight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-flight.js","sourceRoot":"","sources":["../../src/utils/refresh-flight.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,yEAAyE;AACzE,4EAA4E;AAC5E,8EAA8E;AAC9E,0EAA0E;AAC1E,0EAA0E;AAC1E,8DAA8D;AAC9D,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,uDAAuD;AACvD,EAAE;AACF,wEAAwE;AACxE,2EAA2E;AAC3E,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,gEAAgE;AAEhE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAA;AAEpD,SAAS,SAAS,CAAC,KAAwB;IAC1C,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAClC,KAAwB,EACxB,QAA0B;IAE1B,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC5B,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAClC,IAAI,QAAQ;QAAE,OAAO,QAAsB,CAAA;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE;SAC9B,IAAI,CAAC,QAAQ,CAAC;SACd,OAAO,CAAC,GAAG,EAAE;QACb,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM;YAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IACH,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IACzB,OAAO,MAAM,CAAA;AACd,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,yBAAyB;IACxC,OAAO,QAAQ,CAAC,IAAI,CAAA;AACrB,CAAC"}

package/dist/utils/tokens.d.ts

@@ -28,7 +28,32 @@ export interface VerifyAccessTokenOptions {
 }
 export declare function verifyAccessToken(issuer: string, token: string, options?: VerifyAccessTokenOptions): Promise<VerifiedClaims | null>;
 export declare function verifyIssuedAccessTokenClaims(issuer: string, token: string, audience: string | undefined): Promise<TokenPayloadClaims | null>;
-export declare function refreshTokens(issuer: string, refreshToken: string, clientId?: string, clientSecret?: string, resource?: string): Promise<TokenRefreshResult | null>;
+/**
+ * Why a refresh produced no tokens. `invalid_grant` is the issuer saying it does
+ * not recognise this refresh token — the strongest signal there is, but NOT
+ * proof: the issuer's token store is eventually consistent, so a token only
+ * seconds old can read as missing from another location. Every other reason may
+ * simply pass on a later request. A caller must never discard the session on
+ * any of them; signing in again overwrites the cookies without help.
+ */
+export type RefreshFailureReason = 'invalid_grant' | 'issuer_rejected' | 'issuer_error' | 'malformed_response' | 'claims_rejected' | 'network' | 'not_configured'
+/** The refresher returned nothing and did not say why. */
+ | 'unreported';
+export interface RefreshFailure {
+    reason: RefreshFailureReason;
+    /** HTTP status of the issuer's answer, when there was one. */
+    status?: number;
+    /** The OAuth `error` code the issuer returned, when it was readable. */
+    error?: string;
+}
+/**
+ * Exchange a refresh token for new tokens. Concurrent calls for the same token
+ * (same issuer, client and resource) within one isolate share a single
+ * exchange and receive its outcome — see `refresh-flight.ts` for why the scope
+ * is the isolate and nothing is cached once the flight settles. `onFailure` is
+ * this caller's own reporter and fires for followers as well as the leader.
+ */
+export declare function refreshTokens(issuer: string, refreshToken: string, clientId?: string, clientSecret?: string, resource?: string, onFailure?: (failure: RefreshFailure) => void): Promise<TokenRefreshResult | null>;
 export declare function decodeJwtPayload(jwt: string): Record<string, unknown>;
 /** @internal Test-only helper. Not exported from @growth-labs/auth/utils. */
 export declare function _resetJwksCache(): void;

package/dist/utils/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/utils/tokens.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AA+DrD,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD,SAAS,EAAE,OAAO,CAAA;CAClB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,CAWvF;AAYD,MAAM,WAAW,wBAAwB;IACxC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC5B,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAmDD,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,wBAA6B,GACpC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAuBhC;AAED,wBAAsB,6BAA6B,CAClD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAKpC;AA6BD,wBAAsB,aAAa,CAClC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAmCpC;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/utils/tokens.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAgErD,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACzD,SAAS,EAAE,OAAO,CAAA;CAClB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,CAWvF;AAYD,MAAM,WAAW,wBAAwB;IACxC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC5B,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAmDD,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,wBAA6B,GACpC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAuBhC;AAED,wBAAsB,6BAA6B,CAClD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAKpC;AA6BD;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAC7B,eAAe,GACf,iBAAiB,GACjB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,SAAS,GACT,gBAAgB;AAClB,0DAA0D;GACxD,YAAY,CAAA;AAEf,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,oBAAoB,CAAA;IAC5B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;CACd;AA8ED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAClC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAC3C,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAkBpC;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/utils/tokens.js

@@ -2,6 +2,7 @@ import { createLocalJWKSet, jwtVerify } from 'jose';
 import { JWTExpired } from 'jose/errors';
 import { createClientSecretBasicAuthHeader } from './client-secret-header.js';
 import { extractIdentityId } from './identity.js';
+import { singleFlightRefresh } from './refresh-flight.js';
 const JWKS_TTL = 600_000; // 10 minutes in ms
 const jwksCache = new Map();
 async function getJWKS(issuer, requiredKid) {
@@ -159,9 +160,17 @@ function tokenResultFromClaims(accessToken, refreshToken, claims) {
         },
     };
 }
-export async function refreshTokens(issuer, refreshToken, clientId, clientSecret, resource) {
-    if (!resource)
-        return null;
+async function oauthErrorCode(response) {
+    try {
+        const body = await response.json();
+        const code = body?.error;
+        return typeof code === 'string' ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function exchangeRefreshToken(issuer, refreshToken, clientId, clientSecret, resource) {
     try {
         const params = new URLSearchParams({
             grant_type: 'refresh_token',
@@ -181,19 +190,60 @@ export async function refreshTokens(issuer, refreshToken, clientId, clientSecret
             headers,
             body: params.toString(),
         });
-        if (!response.ok)
-            return null;
-        const data = await response.json();
-        if (!tokenResponseHasTokens(data))
-            return null;
+        if (!response.ok) {
+            const error = await oauthErrorCode(response);
+            const reason = error === 'invalid_grant'
+                ? 'invalid_grant'
+                : response.status >= 500
+                    ? 'issuer_error'
+                    : 'issuer_rejected';
+            return {
+                result: null,
+                failure: { reason, status: response.status, ...(error ? { error } : {}) },
+            };
+        }
+        const data = await response.json().catch(() => null);
+        if (!tokenResponseHasTokens(data)) {
+            return { result: null, failure: { reason: 'malformed_response', status: response.status } };
+        }
         const claims = await verifyIssuedAccessTokenClaims(issuer, data.access_token, resource);
-        if (!claims)
-            return null;
-        return tokenResultFromClaims(data.access_token, data.refresh_token, claims);
+        if (!claims) {
+            return { result: null, failure: { reason: 'claims_rejected', status: response.status } };
+        }
+        return {
+            result: tokenResultFromClaims(data.access_token, data.refresh_token, claims),
+            failure: null,
+        };
     }
     catch {
+        return { result: null, failure: { reason: 'network' } };
+    }
+}
+/**
+ * Exchange a refresh token for new tokens. Concurrent calls for the same token
+ * (same issuer, client and resource) within one isolate share a single
+ * exchange and receive its outcome — see `refresh-flight.ts` for why the scope
+ * is the isolate and nothing is cached once the flight settles. `onFailure` is
+ * this caller's own reporter and fires for followers as well as the leader.
+ */
+export async function refreshTokens(issuer, refreshToken, clientId, clientSecret, resource, onFailure) {
+    // Reporting is advisory: a callback that throws must not change the outcome.
+    const report = (failure) => {
+        try {
+            onFailure?.(failure);
+        }
+        catch {
+            /* the caller's reporter is not this function's failure */
+        }
+    };
+    if (!resource) {
+        report({ reason: 'not_configured' });
         return null;
     }
+    const exchange = await singleFlightRefresh([issuer, clientId ?? '', resource, refreshToken], () => exchangeRefreshToken(issuer, refreshToken, clientId, clientSecret, resource));
+    if (exchange.failure)
+        report(exchange.failure);
+    return exchange.result;
 }
 export function decodeJwtPayload(jwt) {
     return decodeJwtSegment(jwt, 1) ?? {};