@startsimpli/auth 0.4.11 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.11",
+  "version": "0.4.14",
   "description": "Shared authentication package for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/middleware.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for createAuthMiddleware (raise-simpli-qcw).
+ *
+ * The bug: middleware redirects to /signin whenever the access-token cookie
+ * is missing or expired, even when a refresh_token cookie is still present.
+ * That's the wrong call — the client AuthProvider can transparently refresh
+ * via the refresh_token cookie. By bouncing to /signin we force the user
+ * into a 3-refresh dance to recover (signin redirects back to /dashboard
+ * once bootstrapFromCookies completes).
+ *
+ * The fix: if access_token/auth_session is missing or expired but
+ * refresh_token is present, let the request through. Pages then handle
+ * the JWT refresh client-side via authFetch / AuthProvider bootstrap.
+ *
+ * If NO cookies at all (or only an expired refresh_token) — still redirect
+ * to /signin. That's the genuinely-unauthenticated case.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NextRequest } from 'next/server';
+import { createAuthMiddleware } from '../server/middleware';
+
+// JWT factory: build a token with arbitrary exp
+function makeJwt(expSecondsFromNow: number): string {
+  const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).replace(/=/g, '');
+  const exp = Math.floor(Date.now() / 1000) + expSecondsFromNow;
+  const payload = btoa(JSON.stringify({ exp, sub: 'test-user' })).replace(/=/g, '');
+  return `${header}.${payload}.fake-signature`;
+}
+
+function makeRequest(
+  pathname: string,
+  cookies: Record<string, string> = {}
+): NextRequest {
+  const url = new URL(`http://localhost:4001${pathname}`);
+  const cookieHeader = Object.entries(cookies)
+    .map(([k, v]) => `${k}=${v}`)
+    .join('; ');
+  const init: RequestInit = cookieHeader ? { headers: { cookie: cookieHeader } } : {};
+  return new NextRequest(url, init);
+}
+
+describe('createAuthMiddleware — JWT refresh tolerance', () => {
+  let middleware: ReturnType<typeof createAuthMiddleware>;
+
+  beforeEach(() => {
+    middleware = createAuthMiddleware({
+      publicPaths: ['/auth/signin', '/auth/signup'],
+      loginPath: '/auth/signin',
+      callbackParam: 'callbackUrl',
+    });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('valid access token', () => {
+    it('lets the request through when auth_session is fresh', () => {
+      const fresh = makeJwt(60 * 30); // 30 min from now
+      const req = makeRequest('/dashboard', { auth_session: fresh });
+      const res = middleware(req);
+      // NextResponse.next() has no Location header
+      expect(res.headers.get('location')).toBeNull();
+    });
+
+    it('lets the request through when access_token is fresh (legacy cookie name)', () => {
+      const fresh = makeJwt(60 * 30);
+      const req = makeRequest('/dashboard', { access_token: fresh });
+      const res = middleware(req);
+      expect(res.headers.get('location')).toBeNull();
+    });
+  });
+
+  describe('expired access token + valid refresh token', () => {
+    it('lets the request through (does NOT redirect to /signin) — raise-simpli-qcw fix', () => {
+      // The auth_session cookie expired (30-min JWT) but the user is still
+      // logged in via their longer-lived refresh_token cookie. Middleware
+      // must let this request pass so the page can refresh client-side.
+      const expired = makeJwt(-60); // 1 min ago
+      const req = makeRequest('/dashboard', {
+        auth_session: expired,
+        refresh_token: 'opaque-refresh-jwt',
+      });
+      const res = middleware(req);
+      expect(res.headers.get('location')).toBeNull();
+    });
+
+    it('lets the request through when only refresh_token is present (no access cookies)', () => {
+      // The auth_session cookie was already dropped by the browser after
+      // expiry. Only refresh_token (HttpOnly, longer-lived) survives.
+      const req = makeRequest('/dashboard', {
+        refresh_token: 'opaque-refresh-jwt',
+      });
+      const res = middleware(req);
+      expect(res.headers.get('location')).toBeNull();
+    });
+  });
+
+  describe('genuinely unauthenticated', () => {
+    it('redirects to /signin when no cookies are set', () => {
+      const req = makeRequest('/dashboard');
+      const res = middleware(req);
+      expect(res.headers.get('location')).toContain('/auth/signin');
+      expect(res.headers.get('location')).toContain('callbackUrl=%2Fdashboard');
+    });
+
+    it('redirects to /signin when access_token is expired and no refresh_token', () => {
+      const expired = makeJwt(-60);
+      const req = makeRequest('/dashboard', { auth_session: expired });
+      const res = middleware(req);
+      expect(res.headers.get('location')).toContain('/auth/signin');
+    });
+  });
+
+  describe('public paths', () => {
+    it('lets unauthenticated users access /auth/signin', () => {
+      const req = makeRequest('/auth/signin');
+      const res = middleware(req);
+      expect(res.headers.get('location')).toBeNull();
+    });
+
+    it('redirects authenticated users away from /auth/signin to /dashboard', () => {
+      const fresh = makeJwt(60 * 30);
+      const req = makeRequest('/auth/signin', { auth_session: fresh });
+      const res = middleware(req);
+      expect(res.headers.get('location')).toContain('/dashboard');
+    });
+  });
+});

package/src/client/auth-client.ts

@@ -53,6 +53,8 @@ export class AuthClient {
       tokenRefreshInterval: 4 * 60 * 1000, // 4 minutes
       onSessionExpired: () => {},
       onUnauthorized: () => {},
+      loginPath: '',
+      callbackParam: 'callbackUrl',
       ...config,
     };
   }

package/src/client/auth-context.tsx

@@ -110,13 +110,30 @@ export function AuthProvider({
 
   // Session expiration handler — covers both AuthClient timer and authFetch 401
   useEffect(() => {
+    // Capture the consumer's onSessionExpired before we overwrite it below.
+    const consumerCallback = config.onSessionExpired;
+    const loginPath = config.loginPath;
+    const callbackParam = config.callbackParam ?? 'callbackUrl';
+
     const handleExpired = () => {
       setState({
         session: null,
         isLoading: false,
         isAuthenticated: false,
       });
-      config.onSessionExpired?.();
+      consumerCallback?.();
+
+      // Redirect to login if configured. Done after state reset + consumer
+      // callback so any cleanup runs first. window.location avoids pulling
+      // a router dep into the shared package — works in any framework.
+      if (loginPath && typeof window !== 'undefined') {
+        const here = window.location.pathname + window.location.search;
+        const isOnLogin = window.location.pathname.startsWith(loginPath);
+        if (!isOnLogin) {
+          const callback = encodeURIComponent(here);
+          window.location.href = `${loginPath}?${callbackParam}=${callback}`;
+        }
+      }
     };
 
     config.onSessionExpired = handleExpired;

package/src/server/middleware.ts

@@ -1,16 +1,23 @@
 /**
  * Next.js middleware helpers for authentication.
  *
- * Checks client-managed access-token cookies:
- *   1. `auth_session`  – non-HttpOnly cookie the client writes after login.
- *   2. `access_token`  – legacy/alternative cookie name for the same.
+ * Two-tier check:
+ *   1. Access cookies (`auth_session`, `access_token`) — non-HttpOnly,
+ *      written client-side after login. Validates JWT exp claim.
+ *   2. Refresh cookie (`refresh_token`) — HttpOnly, server-managed, longer-
+ *      lived. Treated as a "the client can probably refresh" signal that
+ *      lets the request pass to the page; AuthProvider then runs
+ *      bootstrapFromCookies to mint a fresh access token before any data
+ *      fetch fires.
  *
- * We intentionally do NOT treat the HttpOnly `refresh_token` cookie as
- * proof of authentication. The refresh token survives client-side logout
- * (Chromium can drop server-issued delete-cookie responses when attributes
- * diverge), which would let a "logged out" user bounce back into protected
- * routes via the middleware. Access tokens are short-lived and kept in
- * sync with the in-memory session, so they're the correct signal here.
+ * Why not treat refresh_token alone as full auth? It survives client-side
+ * logout (Chromium can drop server-issued delete-cookie responses when
+ * attributes diverge). Logout proper is enforced by `setLoggedOutFlag()`
+ * in the client + the server-side blacklist; middleware just needs to
+ * decide whether to bounce the request. Bouncing on every JWT expiry
+ * (every 30 min by default — see SIMPLE_JWT.ACCESS_TOKEN_LIFETIME) forces
+ * users into a 3-refresh dance instead of letting authFetch refresh
+ * transparently. See raise-simpli-qcw.
  */
 
 import { NextRequest, NextResponse } from 'next/server';
@@ -19,6 +26,9 @@ import { isTokenExpired } from '../utils';
 /** Cookie names checked for a valid JWT, in priority order. */
 const AUTH_COOKIE_NAMES = ['auth_session', 'access_token'] as const;
 
+/** Cookie name for the refresh token (HttpOnly, server-managed). */
+const REFRESH_COOKIE_NAME = 'refresh_token';
+
 /** Find the first valid (non-expired) JWT from known auth cookies. */
 function findValidToken(request: NextRequest): string | null {
   for (const name of AUTH_COOKIE_NAMES) {
@@ -28,6 +38,12 @@ function findValidToken(request: NextRequest): string | null {
   return null;
 }
 
+/** Whether the request carries a refresh_token cookie (existence-only). */
+function hasRefreshCookie(request: NextRequest): boolean {
+  const value = request.cookies.get(REFRESH_COOKIE_NAME)?.value;
+  return !!value && value.length > 0;
+}
+
 export interface AuthMiddlewareConfig {
   publicPaths?: string[];
   loginPath?: string;
@@ -52,7 +68,10 @@ export function createAuthMiddleware(config: AuthMiddlewareConfig = {}) {
     );
 
     if (isPublicPath) {
-      // Redirect authenticated users away from login/signup
+      // Redirect authenticated users away from login/signup. We only
+      // bounce them off /signin if they have a *fresh* access cookie —
+      // a lone refresh_token isn't enough, because we don't trust it as
+      // proof of being logged in (see module docstring).
       if (findValidToken(request) && (pathname.startsWith(loginPath) || pathname === '/auth/signup')) {
         const url = request.nextUrl.clone();
         url.pathname = '/dashboard';
@@ -61,7 +80,13 @@ export function createAuthMiddleware(config: AuthMiddlewareConfig = {}) {
       return NextResponse.next();
     }
 
-    if (!findValidToken(request)) {
+    // Protected route. Allow if either:
+    //   (a) there's a fresh access JWT cookie, or
+    //   (b) there's a refresh_token cookie — the client AuthProvider will
+    //       refresh on mount and authFetch will retry any 401 that races
+    //       the refresh. Bouncing here would force the user into a
+    //       redirect-to-/signin-then-back dance every 30 minutes.
+    if (!findValidToken(request) && !hasRefreshCookie(request)) {
       const url = request.nextUrl.clone();
       url.pathname = loginPath;
       url.searchParams.set(callbackParam, pathname);

package/src/types/index.ts

@@ -111,6 +111,21 @@ export interface AuthConfig {
   tokenRefreshInterval?: number; // milliseconds, default 4 minutes
   onSessionExpired?: () => void;
   onUnauthorized?: () => void;
+  /**
+   * If set, AuthProvider redirects the browser here when the session is
+   * lost (refresh-token rejected, manual logout, etc.). The current path
+   * is appended as a query param so the login page can return the user.
+   * Same value the server-side middleware uses, e.g. `/auth/signin`.
+   * Without this set, session loss only resets React state and the user
+   * can be left on a page where every subsequent request silently 403s
+   * (raise-simpli-lxv).
+   */
+  loginPath?: string;
+  /**
+   * Query-param name appended to `loginPath` to carry the return URL.
+   * Defaults to `callbackUrl` to match the shared server middleware.
+   */
+  callbackParam?: string;
 }
 
 /**