nucleus-core-ts 0.9.708 → 0.9.709

package/dist/src/Client/Proxy/httpProxy.d.ts

@@ -1,4 +1,14 @@
-import type { HttpProxyConfig } from './types';
+import type { HttpProxyConfig, TokenRefreshConfig } from './types';
+interface RefreshResult {
+    accessToken: string;
+    setCookieHeaders: string[];
+}
+export declare function deduplicatedRefresh(refreshConfig: TokenRefreshConfig, refreshToken: string, logger: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}, originalCookieHeader?: string | null): Promise<RefreshResult | null>;
 export declare function createHttpProxyHandler(config: HttpProxyConfig): {
     handle(req: Request, clientIp?: string): Promise<Response | null>;
 };
+export {};

package/dist/src/Client/Proxy/httpProxy.js

@@ -1,4 +1,4 @@
-import { evaluateAccess, ManifestCache, resolveClaimsFromRoles, RoleClaimsCache, verifyJwtHS256 } from './authz';
+import { evaluateAccess, ManifestCache, RoleClaimsCache, resolveClaimsFromRoles, verifyJwtHS256 } from './authz';
 import { createProxyLogger, matchPath, parseCookies, rewritePath } from './utils';
 const pendingRefreshes = new Map();
 function extractAccessTokenFromSetCookie(setCookieHeaders, accessCookieName) {
@@ -89,7 +89,7 @@ async function performTokenRefresh(refreshConfig, refreshToken, logger, original
         return null;
     }
 }
-function deduplicatedRefresh(refreshConfig, refreshToken, logger, originalCookieHeader) {
+export function deduplicatedRefresh(refreshConfig, refreshToken, logger, originalCookieHeader) {
     const dedupeKey = refreshToken.slice(-16);
     const existing = pendingRefreshes.get(dedupeKey);
     if (existing) {

package/dist/src/Client/Proxy/server.js

@@ -39,7 +39,7 @@ export async function createProxyServer(config) {
         async fetch (req, server) {
             if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
                 if (wsHandler) {
-                    const result = wsHandler.upgrade(req, server);
+                    const result = await wsHandler.upgrade(req, server);
                     if (result === true) {
                         return undefined;
                     }

package/dist/src/Client/Proxy/types.d.ts

@@ -8,6 +8,16 @@ export interface WsProxyTarget {
         queryParam?: string;
         headerName?: string;
     };
+    /**
+     * Proactively refresh the access token before injecting it into the handshake.
+     * A WS handshake bearer MUST be the short-lived access token (the backend verifies
+     * it with the access-token secret) — a `refresh_token`/`session_token` fallback is
+     * signed with a DIFFERENT secret and always fails verification, producing a 4001
+     * reconnect storm once the access-token cookie ages out (e.g. after 30m idle on a
+     * sibling subdomain). When set, if the access cookie is missing/expiring and a
+     * refresh cookie is present, exchange it for a fresh access token and inject THAT.
+     */
+    tokenRefresh?: TokenRefreshConfig;
     headers?: Record<string, string>;
     changeOrigin?: boolean;
     secure?: boolean;

package/dist/src/Client/Proxy/wsProxy.d.ts

@@ -5,7 +5,7 @@ export declare function createWsProxyHandler(config: WsProxyConfig): {
         upgrade: (req: Request, options: {
             data: WsProxyState;
         }) => boolean;
-    }): boolean | Response;
+    }): Promise<boolean | Response>;
     websocket: {
         open(ws: ServerWebSocket<WsProxyState>): void;
         message(ws: ServerWebSocket<WsProxyState>, message: string | Buffer): void;

package/dist/src/Client/Proxy/wsProxy.js

@@ -1,4 +1,21 @@
+import { deduplicatedRefresh } from './httpProxy';
 import { addQueryParam, createProxyLogger, httpToWs, matchPath, parseCookies, rewritePath } from './utils';
+/**
+ * True when an access token is absent or within `skewMs` of expiring. Decodes the JWT
+ * exp WITHOUT verifying (verification happens at the backend) — this only decides whether
+ * to pre-emptively refresh before the WS handshake.
+ */ function accessTokenExpiringSoon(token, skewMs = 60000) {
+    if (!token) return true;
+    try {
+        const part = token.split('.')[1];
+        if (!part) return true;
+        const json = JSON.parse(Buffer.from(part.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+        if (typeof json.exp !== 'number') return false;
+        return json.exp * 1000 - Date.now() < skewMs;
+    } catch  {
+        return true;
+    }
+}
 export function createWsProxyHandler(config) {
     const logger = createProxyLogger('WS Proxy', config.debug ?? false);
     const pingIntervalMs = config.pingIntervalMs ?? 0;
@@ -10,7 +27,7 @@ export function createWsProxyHandler(config) {
         }
         return null;
     }
-    function buildBackendUrl(path, target, cookies, query) {
+    async function buildBackendUrl(path, target, cookies, query) {
         let baseUrl = target.url.replace(/\/$/, '');
         if (baseUrl.startsWith('http')) {
             baseUrl = httpToWs(baseUrl);
@@ -40,6 +57,25 @@ export function createWsProxyHandler(config) {
             } else {
                 let token = cookies[target.injectTokenFromCookie.cookieName];
                 let tokenSource = target.injectTokenFromCookie.cookieName;
+                // A WS handshake bearer MUST be the short-lived access token. If it's missing or
+                // about to expire and a refresh is configured, exchange the refresh cookie for a
+                // FRESH access token and inject that — NEVER fall through to a refresh/session
+                // cookie, which is signed with a different secret and guarantees a 4001 storm.
+                const refreshConfig = target.tokenRefresh;
+                const refreshToken = cookies[refreshConfig?.refreshCookieName ?? 'refresh_token'];
+                if (refreshConfig?.enabled && refreshToken && accessTokenExpiringSoon(token)) {
+                    const cookieHeader = Object.entries(cookies).map(([k, v])=>`${k}=${v}`).join('; ');
+                    const refreshed = await deduplicatedRefresh(refreshConfig, refreshToken, logger, cookieHeader);
+                    if (refreshed?.accessToken) {
+                        token = refreshed.accessToken;
+                        tokenSource = 'refreshed access_token';
+                        refreshConfig.onRefreshSuccess?.(path);
+                    } else {
+                        refreshConfig.onRefreshFailure?.(path, 'WS pre-handshake refresh failed');
+                    }
+                }
+                // Legacy fallback — reached only when refresh is NOT configured. Prefer configuring
+                // tokenRefresh: a refresh/session cookie here is not a valid handshake bearer.
                 if (!token && target.injectTokenFromCookie.fallbackCookieNames) {
                     for (const fallback of target.injectTokenFromCookie.fallbackCookieNames){
                         if (cookies[fallback]) {
@@ -60,7 +96,7 @@ export function createWsProxyHandler(config) {
         return url;
     }
     return {
-        upgrade (req, server) {
+        async upgrade (req, server) {
             const url = new URL(req.url);
             const path = url.pathname;
             if (config.allowHmr !== false && path.startsWith('/_next/webpack-hmr')) {
@@ -78,7 +114,7 @@ export function createWsProxyHandler(config) {
                 return false;
             }
             const cookies = parseCookies(req.headers.get('cookie'));
-            const backendUrl = buildBackendUrl(path, target, cookies, url.searchParams);
+            const backendUrl = await buildBackendUrl(path, target, cookies, url.searchParams);
             logger.info(`Upgrading: ${path} -> ${backendUrl}`);
             // Extract original request headers to forward to backend
             const originalHeaders = {};
@@ -224,8 +260,8 @@ export function startWsProxyServer(config) {
     const server = Bun.serve({
         port,
         hostname,
-        fetch (req, server) {
-            const result = handler.upgrade(req, server);
+        async fetch (req, server) {
+            const result = await handler.upgrade(req, server);
             if (result === true) {
                 return undefined;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.708",
+	"version": "0.9.709",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",