@payez/next-mvp 4.1.1 → 4.1.2

package/dist/auth/better-auth.d.ts

@@ -18,6 +18,9 @@ export interface BetterAuthSocialProvider {
     clientId: string;
     clientSecret: string;
     scope?: string[];
+    prompt?: string;
+    accessType?: 'offline' | 'online';
+    hd?: string;
 }
 /**
  * Build Better Auth social providers from IDP config.

package/dist/auth/better-auth.js

@@ -69,10 +69,28 @@ function buildBetterAuthProviders(config) {
         if (!oauth.enabled)
             continue;
         const name = oauth.provider.toLowerCase();
+        const additionalParams = oauth.additionalParams ?? {};
+        const rawPrompt = additionalParams.prompt;
+        const rawAccessType = additionalParams.accessType ?? additionalParams.access_type;
+        const rawHostedDomain = additionalParams.hd;
+        // Ensure profile scope is present for Google so avatar image is returned
+        const scopes = oauth.scopes?.split(' ') || [];
+        if (name === 'google' && !scopes.includes('profile')) {
+            scopes.push('profile');
+        }
         providers[name] = {
             clientId: oauth.clientId,
             clientSecret: oauth.clientSecret,
-            scope: oauth.scopes?.split(' '),
+            scope: scopes.length > 0 ? scopes : undefined,
+            // Google is overly eager to reuse the last account unless we
+            // explicitly ask for account selection on each social login.
+            prompt: typeof rawPrompt === 'string'
+                ? rawPrompt
+                : name === 'google'
+                    ? 'select_account'
+                    : undefined,
+            accessType: rawAccessType === 'online' ? 'online' : rawAccessType === 'offline' ? 'offline' : undefined,
+            hd: typeof rawHostedDomain === 'string' ? rawHostedDomain : undefined,
         };
     }
     return providers;
@@ -301,8 +319,11 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
             userId: String(result.user?.user_id || result.user?.id || result.user_id || baUserId),
             email: result.user?.email || result.email || email,
             name: result.user?.full_name || result.user?.name || result.name || name,
+            image: image,
             roles: result.user?.roles || result.roles || [],
             mfaVerified: !requiresTwoFactor,
+            idpClientId: result.client_id ? String(result.client_id) : undefined,
+            merchantId: result.merchant_id ? String(result.merchant_id) : undefined,
         };
         // Store in BA Redis session (for decodeSession)
         baData.idpTokens = idpTokenData;

package/dist/lib/ensure-fresh-access-token.d.ts

@@ -0,0 +1,30 @@
+export interface EnsureFreshConfig {
+    idpBaseUrl: string;
+    clientId: string;
+    refreshEndpoint?: string;
+}
+export interface EnsureFreshOptions {
+    /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
+    safetyWindowMs?: number;
+    /** Max wait while another caller holds the refresh lock. Default 5000. */
+    lockWaitMs?: number;
+    /** Optional caller request id for lock attribution. */
+    requestId?: string;
+}
+export type EnsureFreshResult = {
+    ok: true;
+    accessToken: string;
+    accessTokenExpires: number;
+    /** True if we refreshed (or a concurrent refresh completed); false if the stored token was already fresh. */
+    refreshed: boolean;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    status: number;
+    terminal?: boolean;
+    discardToken?: boolean;
+    retryable?: boolean;
+    resolution?: string;
+};
+export declare function ensureFreshAccessToken(sessionToken: string, config: EnsureFreshConfig, options?: EnsureFreshOptions): Promise<EnsureFreshResult>;

package/dist/lib/ensure-fresh-access-token.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureFreshAccessToken = ensureFreshAccessToken;
+/**
+ * ensureFreshAccessToken — server-side preflight refresh.
+ *
+ * Returns a non-expired IDP access token for a given session. Refreshes
+ * proactively when the stored token is within the safety window of expiry,
+ * using the same Redis lock and IDP wire shape as `createRefreshHandler`.
+ *
+ * Designed for proxy-route auth helpers that today read the stored token
+ * blindly and let the backend reject it with a 401. Calling this instead of
+ * `getSession(...).idpAccessToken` means a good token client never sends
+ * credentials it already knows are invalid.
+ *
+ * Single-use refresh-token semantics are preserved via Redis-backed
+ * single-flight locking (see `acquireRefreshLock`).
+ */
+const session_store_1 = require("./session-store");
+const token_expiry_1 = require("./token-expiry");
+const token_utils_1 = require("../auth/utils/token-utils");
+const DEFAULT_SAFETY_WINDOW_MS = 60_000;
+const DEFAULT_LOCK_WAIT_MS = 5000;
+function decodeJwtExp(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return -1;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+        return (payload.exp || 0) * 1000;
+    }
+    catch {
+        return -1;
+    }
+}
+async function ensureFreshAccessToken(sessionToken, config, options = {}) {
+    const { idpBaseUrl, clientId, refreshEndpoint = '/api/ExternalAuth/refresh' } = config;
+    const safetyWindowMs = options.safetyWindowMs ?? DEFAULT_SAFETY_WINDOW_MS;
+    const lockWaitMs = options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS;
+    const requestId = options.requestId ?? `ensure_fresh_${Date.now()}`;
+    const session = await (0, session_store_1.getSession)(sessionToken);
+    if (!session) {
+        return { ok: false, code: 'NO_SESSION', message: 'No session for token', status: 401, terminal: true };
+    }
+    const storedToken = session.idpAccessToken;
+    if (!storedToken) {
+        return { ok: false, code: 'NO_TOKEN', message: 'No IDP access token in session', status: 401, terminal: true };
+    }
+    const now = Date.now();
+    const redisExpires = session.idpAccessTokenExpires ?? 0;
+    const jwtExpires = decodeJwtExp(storedToken);
+    // Use the smaller of the two to be conservative — Redis can be stale, JWT exp is authoritative.
+    const effectiveExpires = jwtExpires > 0 ? Math.min(redisExpires || jwtExpires, jwtExpires) : redisExpires;
+    const msUntilExpiry = effectiveExpires - now;
+    if (msUntilExpiry > safetyWindowMs) {
+        return { ok: true, accessToken: storedToken, accessTokenExpires: effectiveExpires, refreshed: false };
+    }
+    if (!session.idpRefreshToken) {
+        return {
+            ok: false,
+            code: 'NO_REFRESH_TOKEN',
+            message: 'Access token expired and no refresh token available',
+            status: 401,
+            terminal: true,
+            resolution: 'User must re-authenticate',
+        };
+    }
+    const lock = await (0, session_store_1.acquireRefreshLock)(sessionToken, requestId, lockWaitMs);
+    let weHoldLock = false;
+    let releaseVersion;
+    if (!lock.acquired) {
+        const existing = await (0, session_store_1.checkRefreshLock)(sessionToken);
+        if (!existing || existing.acquiredBy !== requestId) {
+            const startWait = Date.now();
+            while (Date.now() - startWait < lockWaitMs) {
+                await new Promise(r => setTimeout(r, 200));
+                const stillLocked = await (0, session_store_1.checkRefreshLock)(sessionToken);
+                if (!stillLocked) {
+                    const after = await (0, session_store_1.getSession)(sessionToken);
+                    if (after?.idpAccessToken && after.idpAccessTokenExpires) {
+                        const remaining = after.idpAccessTokenExpires - Date.now();
+                        if (remaining > safetyWindowMs) {
+                            return {
+                                ok: true,
+                                accessToken: after.idpAccessToken,
+                                accessTokenExpires: after.idpAccessTokenExpires,
+                                refreshed: true,
+                            };
+                        }
+                    }
+                    break;
+                }
+            }
+            return {
+                ok: false,
+                code: 'CONFLICT',
+                message: 'Refresh already in progress',
+                status: 409,
+                retryable: true,
+            };
+        }
+    }
+    else {
+        weHoldLock = true;
+        releaseVersion = lock.lockInfo?.lockVersion;
+    }
+    try {
+        // Re-check after lock — another caller may have already refreshed.
+        const latest = await (0, session_store_1.getSession)(sessionToken);
+        if (latest?.idpAccessToken && latest.idpAccessTokenExpires) {
+            const latestRemaining = latest.idpAccessTokenExpires - Date.now();
+            const latestJwtExp = decodeJwtExp(latest.idpAccessToken);
+            const stillStale = latestRemaining <= safetyWindowMs || (latestJwtExp > 0 && latestJwtExp <= Date.now());
+            if (!stillStale) {
+                return {
+                    ok: true,
+                    accessToken: latest.idpAccessToken,
+                    accessTokenExpires: latest.idpAccessTokenExpires,
+                    refreshed: true,
+                };
+            }
+        }
+        // Build refresh request body — wire shape must match what the IDP expects.
+        let authMethods = [];
+        if (Array.isArray(session.authenticationMethods)) {
+            authMethods = session.authenticationMethods;
+        }
+        else if (typeof session.authenticationMethods === 'string') {
+            try {
+                authMethods = JSON.parse(session.authenticationMethods);
+            }
+            catch { /* fall through */ }
+        }
+        const isOAuthSession = !!session.oauthProvider;
+        if (authMethods.length === 0 && isOAuthSession) {
+            authMethods = ['pwd', 'mfa'];
+        }
+        const twoFactorMethod = authMethods.find(m => ['sms', 'totp', 'email'].includes(m)) ||
+            session.mfaMethod ||
+            (isOAuthSession ? 'oauth' : null);
+        let acrValue = String(session.authenticationLevel ?? '1');
+        if (isOAuthSession && session.mfaVerified && acrValue === '1') {
+            acrValue = '2';
+        }
+        const body = {
+            refresh_token: session.idpRefreshToken,
+            amr: authMethods,
+            acr: acrValue,
+        };
+        if (session.mfaVerified)
+            body.two_factor_verified = true;
+        if (twoFactorMethod)
+            body.two_factor_method = twoFactorMethod;
+        if (session.mfaCompletedAt)
+            body.two_factor_completed_at = new Date(session.mfaCompletedAt).toISOString();
+        let idpResponse;
+        try {
+            idpResponse = await fetch(`${idpBaseUrl}${refreshEndpoint}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'X-Client-Id': clientId },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                code: 'UPSTREAM_SERVICE_UNAVAILABLE',
+                message: err instanceof Error ? err.message : 'IDP unreachable',
+                status: 503,
+                retryable: true,
+            };
+        }
+        let responseData;
+        try {
+            const text = await idpResponse.text();
+            if (!text.trim()) {
+                return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Empty response from IDP', status: 502, retryable: true };
+            }
+            responseData = JSON.parse(text);
+        }
+        catch (err) {
+            return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Invalid JSON from IDP', status: 502, retryable: true };
+        }
+        if (!idpResponse.ok) {
+            const idpError = responseData?.error || {};
+            const code = idpError.code || 'UNKNOWN_ERROR';
+            const discardToken = idpResponse.status === 401 || idpError.discard_token === true;
+            const retryable = idpResponse.status !== 401 && idpError.retryable === true;
+            if (discardToken) {
+                await (0, session_store_1.updateSession)(sessionToken, {
+                    idpRefreshToken: '',
+                    idpRefreshTokenExpires: undefined,
+                    refreshTokenClearedAt: Date.now(),
+                    refreshTokenClearedReason: `IDP_DISCARD_TOKEN:${code}`,
+                });
+            }
+            return {
+                ok: false,
+                code,
+                message: idpError.message || 'Token refresh failed',
+                status: idpResponse.status,
+                discardToken,
+                retryable,
+                resolution: idpError.resolution,
+                terminal: discardToken,
+            };
+        }
+        // Validate canonical envelope.
+        if (!responseData ||
+            typeof responseData !== 'object' ||
+            responseData.success !== true ||
+            !responseData.data) {
+            return { ok: false, code: 'UPSTREAM_SERVICE_ERROR', message: 'Non-compliant IDP envelope', status: 502, retryable: true };
+        }
+        const newAccess = responseData.data.access_token;
+        const newRefresh = responseData.data.refresh_token;
+        if (!newAccess) {
+            return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Missing access token in IDP response', status: 500 };
+        }
+        let accessTokenExpires;
+        let refreshTokenExpires;
+        let decoded;
+        try {
+            const r = (0, token_expiry_1.computeTokenExpiries)({ accessToken: newAccess, refreshToken: newRefresh, preferJwt: true });
+            decoded = r.decodedAccessToken;
+            accessTokenExpires = r.accessTokenExpires;
+            refreshTokenExpires = r.refreshTokenExpires;
+        }
+        catch {
+            return { ok: false, code: 'INTERNAL_SERVER_ERROR', message: 'Failed to decode new tokens', status: 500 };
+        }
+        let amrClaims = [];
+        if (decoded?.amr) {
+            try {
+                amrClaims = typeof decoded.amr === 'string' ? JSON.parse(decoded.amr) : decoded.amr;
+            }
+            catch {
+                amrClaims = session.authenticationMethods || [];
+            }
+        }
+        else {
+            amrClaims = session.authenticationMethods || [];
+        }
+        const acrLevel = String(decoded?.acr || session.authenticationLevel || '1');
+        const hasNewRefresh = typeof newRefresh === 'string' && newRefresh.length > 0;
+        const newKid = (0, token_utils_1.extractKidFromToken)(newAccess);
+        await (0, session_store_1.updateSession)(sessionToken, {
+            ...session,
+            idpAccessToken: newAccess,
+            idpAccessTokenExpires: accessTokenExpires,
+            idpRefreshToken: hasNewRefresh ? newRefresh : session.idpRefreshToken,
+            idpRefreshTokenExpires: hasNewRefresh ? refreshTokenExpires : session.idpRefreshTokenExpires,
+            decodedAccessToken: decoded,
+            bearerKeyId: newKid || session.bearerKeyId,
+            authenticationMethods: amrClaims,
+            authenticationLevel: acrLevel,
+            mfaVerified: amrClaims.includes('mfa') || session.mfaVerified,
+            mfaCompletedAt: decoded?.mfa_time ? parseInt(decoded.mfa_time) * 1000 : session.mfaCompletedAt,
+            mfaExpiresAt: decoded?.mfa_expires ? parseInt(decoded.mfa_expires) * 1000 : session.mfaExpiresAt,
+            mfaValidityHours: decoded?.mfa_validity_hours ? parseInt(decoded.mfa_validity_hours) : session.mfaValidityHours,
+        });
+        return { ok: true, accessToken: newAccess, accessTokenExpires, refreshed: true };
+    }
+    finally {
+        if (weHoldLock) {
+            await (0, session_store_1.releaseRefreshLock)(sessionToken, requestId, releaseVersion);
+        }
+    }
+}

package/dist/lib/session-store.js

@@ -126,11 +126,14 @@ async function getBetterAuthSession(sessionToken, appSlug) {
                 userId: data.user.id || data.user.email,
                 email: data.user.email,
                 name: data.user.name,
+                image: data.user.image,
                 idpAccessToken: data.idpTokens?.idpAccessToken,
                 idpRefreshToken: data.idpTokens?.idpRefreshToken,
                 idpAccessTokenExpires: data.idpTokens?.idpAccessTokenExpires,
                 mfaVerified: data.idpTokens?.mfaVerified ?? false,
                 roles: data.idpTokens?.roles || [],
+                idpClientId: data.idpTokens?.idpClientId ?? data.idpTokens?.clientId ?? data.idpClientId,
+                merchantId: data.idpTokens?.merchantId ?? data.merchantId,
             };
         }
         return data;
@@ -482,27 +485,27 @@ async function releaseRefreshLock(sessionToken, requestId, lockVersion) {
     const lockKey = getRefreshLockKey(sessionToken);
     try {
         // Lua script for atomic lock validation and release
-        const luaScript = `
-      local lockKey = KEYS[1]
-      local expectedRequestId = ARGV[1]
-      local expectedVersion = ARGV[2]
-
-      local lockData = redis.call('GET', lockKey)
-      if not lockData then
-        return 0  -- Lock doesn't exist
-      end
-
-      local lockInfo = cjson.decode(lockData)
-      if lockInfo.acquiredBy == expectedRequestId then
-        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
-          redis.call('DEL', lockKey)
-          return 1  -- Successfully released
-        else
-          return -2  -- Version mismatch
-        end
-      else
-        return -1  -- Wrong owner
-      end
+        const luaScript = `
+      local lockKey = KEYS[1]
+      local expectedRequestId = ARGV[1]
+      local expectedVersion = ARGV[2]
+
+      local lockData = redis.call('GET', lockKey)
+      if not lockData then
+        return 0  -- Lock doesn't exist
+      end
+
+      local lockInfo = cjson.decode(lockData)
+      if lockInfo.acquiredBy == expectedRequestId then
+        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
+          redis.call('DEL', lockKey)
+          return 1  -- Successfully released
+        else
+          return -2  -- Version mismatch
+        end
+      else
+        return -1  -- Wrong owner
+      end
     `;
         const result = await redis_1.default.eval(luaScript, 1, lockKey, requestId, lockVersion ? lockVersion.toString() : '');
         if (result === 1) {

package/dist/lib/token-lifecycle.js

@@ -243,6 +243,8 @@ async function ensureFreshToken(request) {
                             || (baSession.session?.expiresAt ? new Date(baSession.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
                         mfaVerified: true,
                         oauthProvider: 'google',
+                        idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId ?? baSession.idpClientId,
+                        merchantId: idpTokens?.merchantId ?? baSession.merchantId,
                     };
                 }
             }

package/dist/models/SessionModel.d.ts

@@ -26,6 +26,8 @@ export interface SessionData {
     email: string;
     /** Display name (from OAuth profile or IDP) */
     name?: string;
+    /** Avatar image URL (from OAuth profile) */
+    image?: string;
     /** User's roles/permissions */
     roles: string[];
     /** IDP access token (JWT) - used for API calls to PayEz services */
@@ -83,6 +85,7 @@ export declare class SessionModel {
     userId: string;
     email: string;
     name?: string;
+    image?: string;
     roles: string[];
     idpAccessToken?: string;
     idpRefreshToken?: string;

package/dist/models/SessionModel.js

@@ -29,6 +29,7 @@ class SessionModel {
     userId;
     email;
     name;
+    image;
     roles;
     // IDP Tokens
     idpAccessToken;
@@ -57,6 +58,7 @@ class SessionModel {
         this.userId = data.userId;
         this.email = data.email;
         this.name = data.name;
+        this.image = data.image;
         this.roles = data.roles || [];
         // IDP Tokens
         this.idpAccessToken = data.idpAccessToken;
@@ -111,6 +113,7 @@ class SessionModel {
             userId: this.userId,
             email: this.email,
             name: this.name,
+            image: this.image,
             roles: this.roles,
             idpAccessToken: this.idpAccessToken,
             idpRefreshToken: this.idpRefreshToken,

package/dist/routes/auth/session.js

@@ -59,7 +59,7 @@ async function GET(req) {
                 id: session?.userId || authSession.user?.id,
                 email: session?.email || authSession.user?.email,
                 name: session?.name || authSession.user?.name,
-                image: authSession.user?.image || null,
+                image: authSession.user?.image || session?.image || null,
                 // Redis session data
                 roles: session?.roles || [],
                 twoFactorSessionVerified: session?.mfaVerified || false,

package/dist/server/auth.d.ts

@@ -5,6 +5,16 @@
  * getAuthInstance(); use getSession(req) for the request-scoped session.
  */
 import 'server-only';
+import { type SessionData } from '../lib/session-store';
+export type IdpTokenResult = {
+    success: true;
+    accessToken: string;
+    sessionData: SessionData;
+} | {
+    success: false;
+    error: 'NO_SESSION' | 'NO_TOKEN';
+    terminal: true;
+};
 /**
  * Get the initialized Better Auth instance (singleton).
  */
@@ -149,6 +159,55 @@ export declare function getAuthInstance(): Promise<import("better-auth/types").A
  * Returns the session object or null if not authenticated.
  */
 export declare function getSession(request?: Request): Promise<any>;
+/**
+ * Get normalized session data for the current request.
+ *
+ * This prefers the app's Redis session because it carries the canonical
+ * IDP token, roles, and tenant-specific user identity used by app routes.
+ */
+export declare function getSessionData(request?: Request): Promise<SessionData | null>;
+/**
+ * Get the current request's IDP access token without triggering a refresh.
+ *
+ * Use this for routes that only need the currently-issued bearer token and
+ * should fail closed instead of performing token lifecycle work. For backend
+ * proxy routes that forward the token to a downstream API, prefer
+ * `getFreshIdpToken` — it preflights expiry and refreshes single-flight, so
+ * the proxy never sends a credential it already knows is invalid.
+ */
+export declare function getIdpToken(request?: Request): Promise<IdpTokenResult>;
+export type FreshIdpTokenResult = {
+    success: true;
+    accessToken: string;
+    sessionData: SessionData;
+    refreshed: boolean;
+} | {
+    success: false;
+    error: string;
+    status: number;
+    terminal?: boolean;
+    discardToken?: boolean;
+    retryable?: boolean;
+    resolution?: string;
+};
+export interface FreshIdpTokenConfig {
+    idpBaseUrl: string;
+    clientId: string;
+    refreshEndpoint?: string;
+    /** Refresh if the access token is within this many ms of expiry. Default 60_000. */
+    safetyWindowMs?: number;
+}
+/**
+ * Get the current request's IDP access token, preflight-refreshing if it is
+ * expired or within the safety window. Single-flight via Redis lock, so
+ * concurrent calls on the same session share one IDP round-trip and one
+ * single-use refresh-token consumption.
+ *
+ * Use this in proxy routes. The returned `accessToken` is safe to forward to
+ * a downstream API without expecting a 401. If `success` is false, surface a
+ * 401/redirect — there is no recoverable token for this session.
+ */
+export declare function getFreshIdpToken(request: Request | undefined, config: FreshIdpTokenConfig): Promise<FreshIdpTokenResult>;
 /**
  * Get the current session, throwing if not authenticated.
  * Use in API handlers that require auth.