@growth-labs/auth 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/auth",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -16,6 +16,10 @@
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js"
     },
+    "./workers": {
+      "types": "./dist/workers.d.ts",
+      "import": "./dist/workers.js"
+    },
     "./middleware/*": {
       "types": "./dist/middleware/*.d.ts",
       "import": "./dist/middleware/*.js",
@@ -46,22 +50,37 @@
   },
   "peerDependencies": {
     "@growth-labs/analytics": ">=0.5.1",
-    "astro": "^6.1.10 || ^7.0.0"
+    "astro": "^6.1.10 || ^7.0.0",
+    "hono": "^4.12.25"
+  },
+  "peerDependenciesMeta": {
+    "@growth-labs/analytics": {
+      "optional": true
+    },
+    "astro": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
   },
   "dependencies": {
     "jose": "^6.0.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "astro": "^6.4.6",
+    "astro": "7.3.1",
+    "hono": "^4.12.25",
     "typescript": "^5.8.0",
-    "vite": "^7.3.5",
+    "vite": "8.0.16",
     "vitest": "^4.1.8",
-    "@growth-labs/analytics": "0.18.4"
+    "wrangler": "^4.92.0",
+    "@growth-labs/analytics": "0.20.4"
   },
   "scripts": {
     "build": "tsc",
     "check": "biome check src/",
+    "spike:hono-worker": "wrangler deploy --dry-run --config __tests__/fixtures/hono-worker-subpaths/wrangler.jsonc --outdir .wrangler/hono-worker-subpaths --metafile",
     "test": "vitest run",
     "test:watch": "vitest"
   }

package/src/middleware/auth.ts

@@ -1,11 +1,11 @@
 import { getConfig } from '../config-store.js'
 import '../runtime-bridge.js'
-import type { User } from '../types.js'
+import type { AuthSessionState, User } from '../types.js'
 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 { refreshTokens, verifyAccessToken } from '../utils/tokens.js'
+import { type RefreshFailure, refreshTokens, verifyAccessToken } from '../utils/tokens.js'
 
 const PRIVATE_NO_STORE_HEADERS = [
 	'Cache-Control',
@@ -65,6 +65,7 @@ export async function onRequest(
 		}
 	}
 
+	let refreshFailure = null as RefreshFailure | null
 	if (!user && refreshToken) {
 		const clientId = options.clientId || context.url.hostname
 		refreshed = await refreshTokens(
@@ -73,6 +74,9 @@ export async function onRequest(
 			clientId,
 			resolvedClientSecret,
 			options.resource,
+			(failure) => {
+				refreshFailure = failure
+			},
 		)
 		if (refreshed) {
 			user = {
@@ -84,13 +88,55 @@ export async function onRequest(
 		}
 	}
 
-	// 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,
+	})
+	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 (!user && refreshToken) {
+		const failure: RefreshFailure = 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)) {
+		// 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)}`,
+			`${options.loginPath}?redirect=${encodeURIComponent(context.url.pathname)}${
+				sessionEnded ? '&error=session_expired' : ''
+			}`,
 			context.url.origin,
 		)
 		return Response.redirect(loginUrl.toString(), 302)
@@ -120,6 +166,30 @@ export async function onRequest(
 	return response
 }
 
+function resolveSessionState(input: {
+	user: User | null
+	refreshed: boolean
+	hadAccessToken: boolean
+	hadRefreshToken: boolean
+	refreshFailure: RefreshFailure | null
+}): AuthSessionState {
+	if (input.user) return input.refreshed ? 'refreshed' : 'verified'
+	if (!input.hadAccessToken && !input.hadRefreshToken) return 'anonymous'
+	// 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: Request): boolean {
+	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: string, gatedPaths: string[]): boolean {
 	return gatedPaths.some((pattern) => {
 		if (pattern.endsWith('/*')) {

package/src/types.ts

@@ -149,11 +149,24 @@ export interface TokenExchangeResult {
 	}
 }
 
+/**
+ * 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. NEITHER 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'
+
 // Augment Astro's locals
 declare global {
 	namespace App {
 		interface Locals {
 			user: User | null
+			authSession?: AuthSessionState
 			synthetic?: boolean
 		}
 	}

package/src/utils/client-secret-header.ts

@@ -0,0 +1,8 @@
+export function createClientSecretBasicAuthHeader(clientId: string, clientSecret: string): string {
+	return `Basic ${btoa(`${formEncode(clientId)}:${formEncode(clientSecret)}`)}`
+}
+
+function formEncode(value: string): string {
+	const params = new URLSearchParams({ value })
+	return params.toString().slice('value='.length)
+}

package/src/utils/client-secret.ts

@@ -5,6 +5,7 @@ import {
 	literalClientSecret,
 } from './client-secret-literal.js'
 
+export { createClientSecretBasicAuthHeader } from './client-secret-header.js'
 export type { ClientSecretLiteral }
 export { isClientSecretLiteral, literalClientSecret }
 
@@ -140,12 +141,3 @@ export async function resolveClientSecret(
 	// No Request context: resolve without caching (test or internal call).
 	return doResolve(clientSecret)
 }
-
-export function createClientSecretBasicAuthHeader(clientId: string, clientSecret: string): string {
-	return `Basic ${btoa(`${formEncode(clientId)}:${formEncode(clientSecret)}`)}`
-}
-
-function formEncode(value: string): string {
-	const params = new URLSearchParams({ value })
-	return params.toString().slice('value='.length)
-}

package/src/utils/cookies.ts

@@ -16,7 +16,12 @@ export function getCookie(request: Request, name: string): string | null {
 	const header = request.headers.get('cookie')
 	if (!header) return null
 	const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`))
-	return match ? decodeURIComponent(match[1]) : null
+	if (!match) return null
+	try {
+		return decodeURIComponent(match[1])
+	} catch {
+		return null
+	}
 }
 
 export function setCookie(

package/src/utils/index.ts

@@ -49,4 +49,4 @@ export {
 } from './openauth.js'
 export { createPKCEChallenge, generatePKCE } from './pkce.js'
 export { generateState, verifyState } from './state.js'
-export type { VerifiedClaims } from './tokens.js'
+export type { RefreshFailure, RefreshFailureReason, VerifiedClaims } from './tokens.js'

package/src/utils/tokens.ts

@@ -1,7 +1,8 @@
 import { createLocalJWKSet, jwtVerify } from 'jose'
 import { JWTExpired } from 'jose/errors'
 import type { TokenRefreshResult } from '../types.js'
-import { createClientSecretBasicAuthHeader } from './client-secret.js'
+import { createClientSecretBasicAuthHeader } from './client-secret-header.js'
+import { extractIdentityId } from './identity.js'
 
 type JWKSFunction = ReturnType<typeof createLocalJWKSet>
 
@@ -69,6 +70,9 @@ export interface VerifiedClaims {
 	image?: string
 	synthetic?: boolean
 	purpose?: string
+	userId?: string
+	roles?: string[]
+	audiences?: string[]
 }
 
 export interface TokenPayloadClaims extends VerifiedClaims {
@@ -103,6 +107,12 @@ export interface VerifyAccessTokenOptions {
 	audience?: string | string[]
 	/** Signature algorithms to accept. Defaults to `['ES256']` (identity-platform's signing alg). */
 	algorithms?: string[]
+	/** Fetch signing keys from this backchannel base while still enforcing `issuer`. */
+	jwksIssuer?: string
+	/** Enforce the identity-platform user access-token claim contract. */
+	requireUserToken?: boolean
+	/** Permitted JWT clock skew in seconds for strict user-token validation. */
+	clockSkew?: number
 }
 
 async function verifyAccessTokenPayload(
@@ -113,15 +123,38 @@ async function verifyAccessTokenPayload(
 	try {
 		const header = decodeJwtHeader(token)
 		const kid = typeof header.kid === 'string' ? header.kid : undefined
-		const jwks = await getJWKS(issuer, kid)
+		const jwks = await getJWKS(options.jwksIssuer ?? issuer, kid)
 		const { payload } = await jwtVerify(token, jwks, {
 			issuer,
 			audience: options.audience,
 			algorithms: options.algorithms ?? ['ES256'],
+			clockTolerance: options.clockSkew,
 		})
 		if (payload.mode !== 'access') {
 			throw new Error(`unexpected token mode: ${String(payload.mode)}`)
 		}
+		if (options.requireUserToken) {
+			const properties = payload.properties
+			if (
+				payload.type !== 'user' ||
+				typeof payload.iat !== 'number' ||
+				typeof payload.exp !== 'number' ||
+				typeof payload.sub !== 'string' ||
+				typeof properties !== 'object' ||
+				properties === null
+			) {
+				throw new Error('required user access-token claims are missing')
+			}
+			const userId = extractIdentityId(payload.sub)
+			if (
+				payload.iat > Math.floor(Date.now() / 1000) + (options.clockSkew ?? 0) ||
+				(properties as Record<string, unknown>).userId !== userId ||
+				typeof (properties as Record<string, unknown>).email !== 'string' ||
+				(properties as Record<string, unknown>).email === ''
+			) {
+				throw new Error('access-token identity claims are inconsistent')
+			}
+		}
 		return payload as Record<string, unknown>
 	} catch (err) {
 		if (!isExpiredJwtError(err)) {
@@ -139,6 +172,12 @@ export async function verifyAccessToken(
 	const payload = await verifyAccessTokenPayload(issuer, token, options)
 	if (!payload) return null
 	const claims = extractTokenClaims(payload)
+	const properties = (payload.properties ?? {}) as Record<string, unknown>
+	const audience = Array.isArray(payload.aud)
+		? payload.aud.filter((value): value is string => typeof value === 'string')
+		: typeof payload.aud === 'string'
+			? [payload.aud]
+			: []
 	return {
 		sub: claims.sub,
 		email: claims.email,
@@ -146,6 +185,11 @@ export async function verifyAccessToken(
 		image: claims.image,
 		synthetic: payload.synthetic === true ? true : undefined,
 		purpose: typeof payload.purpose === 'string' ? payload.purpose : undefined,
+		userId: typeof properties.userId === 'string' ? properties.userId : undefined,
+		roles: Array.isArray(payload.roles)
+			? payload.roles.filter((value): value is string => typeof value === 'string')
+			: undefined,
+		audiences: audience,
 	}
 }
 
@@ -187,14 +231,67 @@ function tokenResultFromClaims(
 	}
 }
 
+/**
+ * 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
+}
+
+async function oauthErrorCode(response: Response): Promise<string | undefined> {
+	try {
+		const body: unknown = await response.json()
+		const code = (body as { error?: unknown } | null)?.error
+		return typeof code === 'string' ? code : undefined
+	} catch {
+		return undefined
+	}
+}
+
 export async function refreshTokens(
 	issuer: string,
 	refreshToken: string,
 	clientId?: string,
 	clientSecret?: string,
 	resource?: string,
+	onFailure?: (failure: RefreshFailure) => void,
 ): Promise<TokenRefreshResult | null> {
-	if (!resource) return null
+	// Reporting is advisory: a callback that throws must not change the outcome,
+	// and the catch below must not report a second time on its behalf.
+	let reported = false
+	const report = (failure: RefreshFailure): void => {
+		if (reported) return
+		reported = true
+		try {
+			onFailure?.(failure)
+		} catch {
+			/* the caller's reporter is not this function's failure */
+		}
+	}
+	if (!resource) {
+		report({ reason: 'not_configured' })
+		return null
+	}
 	try {
 		const params = new URLSearchParams({
 			grant_type: 'refresh_token',
@@ -216,16 +313,33 @@ export async function refreshTokens(
 			body: params.toString(),
 		})
 
-		if (!response.ok) return null
+		if (!response.ok) {
+			const error = await oauthErrorCode(response)
+			const reason: RefreshFailureReason =
+				error === 'invalid_grant'
+					? 'invalid_grant'
+					: response.status >= 500
+						? 'issuer_error'
+						: 'issuer_rejected'
+			report({ reason, status: response.status, ...(error ? { error } : {}) })
+			return null
+		}
 
-		const data = await response.json()
-		if (!tokenResponseHasTokens(data)) return null
+		const data: unknown = await response.json().catch(() => null)
+		if (!tokenResponseHasTokens(data)) {
+			report({ reason: 'malformed_response', status: response.status })
+			return null
+		}
 
 		const claims = await verifyIssuedAccessTokenClaims(issuer, data.access_token, resource)
-		if (!claims) return null
+		if (!claims) {
+			report({ reason: 'claims_rejected', status: response.status })
+			return null
+		}
 
 		return tokenResultFromClaims(data.access_token, data.refresh_token, claims)
 	} catch {
+		report({ reason: 'network' })
 		return null
 	}
 }