@growth-labs/auth 0.11.0 → 0.12.0

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,
 	}
 }