najm-auth 2.0.4 → 2.0.5

package/README.md

@@ -167,6 +167,7 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 | `POST` | `/auth/register` | Register new user | None |
 | `POST` | `/auth/login` | Login with email/password | None |
 | `POST` | `/auth/refresh` | Refresh access token (cookie) | None (uses refresh cookie) |
+| `POST` | `/auth/session/recover` | Reissue signed session without token rotation | Refresh cookie + recovery header |
 | `POST` | `/auth/logout` | Logout and revoke tokens | ✅ Required |
 | `GET` | `/auth/me` | Get current user profile | ✅ Required |
 | `POST` | `/auth/forgot-password` | Request password reset | None |
@@ -600,6 +601,7 @@ limits are active when `auth()` is registered.
 | `POST /auth/register` | 5 | 15 minutes | IP |
 | `POST /auth/login` | 5 | 15 minutes | IP |
 | `POST /auth/refresh` | 15 | 15 minutes | Cookie fingerprint |
+| `POST /auth/session/recover` | 120 | 1 minute | Cookie fingerprint |
 | `POST /auth/logout` | 10 | 15 minutes | User ID |
 | `GET /auth/me` | 30 | 1 minute | User ID |
 | `POST /auth/forgot-password` | 3 | 15 minutes | IP |
@@ -675,8 +677,12 @@ throw new HttpError(403, 'Insufficient permissions for this action');
 - Login uses a dummy password hash for missing users to reduce timing leaks.
 - Forgot-password responses avoid email enumeration.
 - Auth routes register `najm-rate` and ship route-level brute-force limits.
-- Session cookies are signed, short-lived, and checked against session version
-  invalidation.
+- Session cookies are signed and short-lived; server auth resolution checks
+  their session version.
+- Expired signed sessions recover through authoritative, non-rotating refresh
+  validation; middleware verifies the reissued HMAC before using its claims.
+- `verifyAlways` forces that authoritative check on every protected request;
+  the default bounds cached role/status staleness to `session.maxAge`.
 
 ### Password Reset Tokens
 

package/dist/client/edge.d.ts

@@ -11,6 +11,10 @@ interface AuthMiddlewareConfig {
     roleRoutes?: Record<string, string[]>;
     /** Refresh token cookie name (default: 'refreshToken') */
     cookieName?: string;
+    /** API base URL used by session recovery (default: '/api'). */
+    apiBaseURL?: string;
+    /** Auth endpoint prefix used by session recovery (default: '/auth'). */
+    authPrefix?: string;
     /** Signed session cookie name (default: 'najm.session') */
     sessionCookieName?: string;
     /** @deprecated Session cookies are verified locally at the Edge. */
@@ -20,10 +24,16 @@ interface AuthMiddlewareConfig {
     /** Must match the auth plugin's session.maxAge. Default: 300 seconds. */
     sessionMaxAge?: number;
     /**
-     * Retained for compatibility. Every protected route now verifies the signed
-     * session cookie locally, so enabling this never calls `/auth/me`.
+     * Force authoritative refresh-session validation on every protected request.
+     * This reissues the signed session cookie without rotating refresh tokens.
      */
     verifyAlways?: boolean;
+    /**
+     * Session-recovery endpoint. Relative values resolve against the request
+     * origin. Defaults to `${apiBaseURL}${authPrefix}/session/recover`.
+     * Set to false to disable automatic recovery.
+     */
+    recoveryURL?: string | false;
 }
 /**
  * Create a Next.js middleware function that protects routes based on auth state.

package/dist/client/edge.js

@@ -131,6 +131,99 @@ function isStringArray(value) {
 }
 __name(isStringArray, "isStringArray");
 
+// src/client/sessionRecovery.ts
+async function requestSessionRecovery(options) {
+  if (!isCookieName(options.refreshCookieName) || !isCookieName(options.sessionCookieName)) {
+    return { status: "unavailable" };
+  }
+  if (!isCookieValue(options.refreshCookieValue)) {
+    return { status: "invalid" };
+  }
+  if (!isSafeRecoveryEndpoint(options.endpoint)) {
+    return { status: "unavailable" };
+  }
+  let response;
+  try {
+    response = await fetch(options.endpoint, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        Cookie: `${options.refreshCookieName}=${options.refreshCookieValue}`,
+        "X-Najm-Session-Recovery": "1"
+      },
+      cache: "no-store",
+      redirect: "manual"
+    });
+  } catch {
+    return { status: "unavailable" };
+  }
+  if (!response.ok) {
+    const status = response.status;
+    return {
+      status: status === 400 || status === 401 || status === 403 ? "invalid" : "unavailable",
+      httpStatus: status
+    };
+  }
+  const setCookie = response.headers.get("set-cookie");
+  if (!setCookie) return { status: "unavailable", httpStatus: response.status };
+  const sessionCookieValue = readSetCookieValue(setCookie, options.sessionCookieName);
+  if (!sessionCookieValue) {
+    return { status: "unavailable", httpStatus: response.status };
+  }
+  const claims = await verifySessionCookie(sessionCookieValue, {
+    secret: options.sessionSecret,
+    maxAgeSeconds: options.sessionMaxAge
+  });
+  if (!claims) return { status: "unavailable", httpStatus: response.status };
+  return {
+    status: "recovered",
+    claims,
+    setCookie,
+    sessionCookieValue
+  };
+}
+__name(requestSessionRecovery, "requestSessionRecovery");
+function authEndpoint(baseURL, authPrefix, suffix, requestURL) {
+  const normalizedBase = baseURL.replace(/\/+$/, "");
+  const normalizedPrefix = `/${authPrefix.replace(/^\/+|\/+$/g, "")}`;
+  const normalizedSuffix = `/${suffix.replace(/^\/+/, "")}`;
+  const value = `${normalizedBase}${normalizedPrefix}${normalizedSuffix}`;
+  return requestURL ? new URL(value, requestURL).toString() : value;
+}
+__name(authEndpoint, "authEndpoint");
+function replaceCookieValue(cookieHeader, name, value) {
+  const parts = cookieHeader.split(";").map((part) => part.trim()).filter(Boolean).filter((part) => part.slice(0, part.indexOf("=")).trim() !== name);
+  parts.push(`${name}=${value}`);
+  return parts.join("; ");
+}
+__name(replaceCookieValue, "replaceCookieValue");
+function readSetCookieValue(setCookie, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = setCookie.match(new RegExp(`(?:^|,\\s*)${escaped}=([^;]*)`));
+  return match?.[1] || void 0;
+}
+__name(readSetCookieValue, "readSetCookieValue");
+function isCookieName(value) {
+  return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(value);
+}
+__name(isCookieName, "isCookieName");
+function isCookieValue(value) {
+  return value.length > 0 && !/[\r\n;]/.test(value);
+}
+__name(isCookieValue, "isCookieValue");
+function isSafeRecoveryEndpoint(value) {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) return false;
+    if (url.protocol === "https:") return true;
+    if (url.protocol !== "http:") return false;
+    return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+__name(isSafeRecoveryEndpoint, "isSafeRecoveryEndpoint");
+
 // src/client/server/withAuthMiddleware.ts
 function withAuthMiddleware(config) {
   const {
@@ -139,26 +232,31 @@ function withAuthMiddleware(config) {
     loginRoute = "/login",
     roleRoutes = {},
     cookieName = "refreshToken",
+    apiBaseURL = "/api",
+    authPrefix = "/auth",
     sessionCookieName = "najm.session",
     sessionSecret,
     sessionMaxAge,
-    verifyAlways = false
+    verifyAlways = false,
+    recoveryURL
   } = config;
-  void verifyAlways;
   return /* @__PURE__ */ __name(async function middleware(request) {
     const { NextResponse } = await import("next/server");
-    const redirectToLogin = /* @__PURE__ */ __name((pathname2, clearCookies) => {
+    const redirectToLogin = /* @__PURE__ */ __name((returnPath2, clearCookies) => {
       const loginUrl = new URL(loginRoute, request.url);
-      loginUrl.searchParams.set("from", pathname2);
+      loginUrl.searchParams.set("from", returnPath2);
       const res = NextResponse.redirect(loginUrl);
-      if (clearCookies) {
+      if (clearCookies.includes("refresh")) {
         res.cookies.delete(cookieName);
+      }
+      if (clearCookies.includes("session")) {
         res.cookies.delete(sessionCookieName);
       }
       return res;
     }, "redirectToLogin");
     const url = new URL(request.url);
     const pathname = url.pathname;
+    const returnPath = `${url.pathname}${url.search}`;
     if (matchesAny(pathname, publicRoutes)) {
       return NextResponse.next();
     }
@@ -167,19 +265,53 @@ function withAuthMiddleware(config) {
     const cookie = request.headers.get("cookie") ?? "";
     const sessionCookie = readCookieValue(cookie, sessionCookieName);
     const secret = resolveSessionSecret(sessionSecret);
-    if (!sessionCookie || !secret) {
-      return redirectToLogin(pathname, true);
+    if (!secret) {
+      return redirectToLogin(returnPath, ["session"]);
     }
-    const session = await verifySessionCookie(sessionCookie, {
+    let session = sessionCookie ? await verifySessionCookie(sessionCookie, {
       secret,
       maxAgeSeconds: sessionMaxAge
-    });
-    if (!session) {
-      return redirectToLogin(pathname, true);
+    }) : null;
+    let recovery = null;
+    if (!session || verifyAlways) {
+      const refreshCookie = readCookieValue(cookie, cookieName);
+      if (!refreshCookie || recoveryURL === false) {
+        return redirectToLogin(returnPath, ["refresh", "session"]);
+      }
+      const endpoint = recoveryURL ? new URL(recoveryURL, request.url).toString() : authEndpoint(apiBaseURL, authPrefix, "/session/recover", request.url);
+      recovery = await requestSessionRecovery({
+        endpoint,
+        refreshCookieName: cookieName,
+        refreshCookieValue: refreshCookie,
+        sessionCookieName,
+        sessionSecret: secret,
+        sessionMaxAge
+      });
+      if (recovery.status !== "recovered") {
+        return redirectToLogin(
+          returnPath,
+          recovery.status === "invalid" ? ["refresh", "session"] : ["session"]
+        );
+      }
+      session = recovery.claims;
     }
     const requiredRoles = findMatchingRoles(pathname, roleRoutes);
     if (requiredRoles && !session.roles.some((role) => requiredRoles.includes(role))) {
-      return new NextResponse(null, { status: 403 });
+      const forbidden = new NextResponse(null, { status: 403 });
+      if (recovery?.status === "recovered") {
+        forbidden.headers.append("Set-Cookie", recovery.setCookie);
+      }
+      return forbidden;
+    }
+    if (recovery?.status === "recovered") {
+      const requestHeaders = new Headers(request.headers);
+      requestHeaders.set(
+        "cookie",
+        replaceCookieValue(cookie, sessionCookieName, recovery.sessionCookieValue)
+      );
+      const response = NextResponse.next({ request: { headers: requestHeaders } });
+      response.headers.append("Set-Cookie", recovery.setCookie);
+      return response;
     }
     return NextResponse.next();
   }, "middleware");

package/dist/client/server/index.d.ts

@@ -75,24 +75,14 @@ interface GetSessionConfig {
      * Defaults to `${NEXT_PUBLIC_API_URL || http://localhost:${PORT||3000}}/api`.
      */
     baseURL?: string;
-    /**
-     * Auth route prefix appended to baseURL (default: '/auth').
-     */
+    /** Auth route prefix appended to baseURL (default: '/auth'). */
     authPrefix?: string;
-    /**
-     * Refresh token cookie name to check before making the network call.
-     * If absent we skip and return null immediately.
-     * Default: 'refreshToken'
-     */
+    /** Refresh token cookie name (default: 'refreshToken'). */
     cookieName?: string;
-    /**
-     * Session cookie name (default: 'najm.session').
-     * When present and valid, skips the /auth/me fetch entirely.
-     */
+    /** Signed session cookie name (default: 'najm.session'). */
     sessionCookieName?: string;
     /**
      * Secret used to verify the session cookie HMAC signature.
-     * Must match the `jwt.accessSecret` used by the auth plugin.
      * Falls back to NAJM_SESSION_SECRET or JWT_ACCESS_SECRET env vars.
      */
     sessionSecret?: string;
@@ -101,6 +91,11 @@ interface GetSessionConfig {
      * Must match the auth plugin's `session.maxAge`. Default: 300.
      */
     sessionMaxAge?: number;
+    /**
+     * Session-recovery endpoint. Defaults to
+     * `${baseURL}${authPrefix}/session/recover`. Set to false to disable fallback.
+     */
+    recoveryURL?: string | false;
     /**
      * Error handling mode:
      * - 'nullable' (default): returns null on any failure
@@ -122,29 +117,10 @@ declare class AuthTransportError extends Error {
     constructor(message: string, status?: number);
 }
 /**
- * Resolve the current session inside a Next.js Server Component, Route Handler,
- * or Server Action.
- *
- * **Fast path**: If a signed `najm.session` cookie exists and is valid,
- * returns the session instantly with zero network calls.
- *
- * **Fallback**: Checks the refresh token cookie and calls `/auth/me`.
- *
- * @example
- * ```tsx
- * import { getSession } from 'najm-auth/client/server';
- *
- * export default async function RootLayout({ children }) {
- *   const session = await getSession();
- *   return (
- *     <html><body>
- *       <AuthProvider client={authClient} initialSession={session}>
- *         {children}
- *       </AuthProvider>
- *     </body></html>
- *   );
- * }
- * ```
+ * Resolve a session in a Next.js Server Component, Route Handler, or Server
+ * Action. Recovery returns claims for the current render but cannot persist
+ * response cookies during Server Component rendering; middleware performs that
+ * persistence for protected navigation.
  */
 declare function getSession(config?: GetSessionConfig): Promise<ServerSession | null>;
 
@@ -200,11 +176,16 @@ interface DefineAuthConfig {
     sessionSecret?: string;
     /** Must match the auth plugin's session.maxAge. Default: 300 seconds. */
     sessionMaxAge?: number;
+    /**
+     * Session-recovery endpoint. Defaults to
+     * `${apiBaseURL}${authPrefix}/session/recover`; false disables recovery.
+     */
+    recoveryURL?: string | false;
     /** Next.js middleware matcher (default: exclude _next, favicon, api) */
     matcher?: string[];
     /**
-     * Retained for compatibility. Every protected route verifies the signed
-     * session cookie locally without an `/auth/me` request.
+     * Force authoritative refresh-session validation on every protected request.
+     * Recovery reissues the signed cookie without rotating refresh tokens.
      */
     verifyAlways?: boolean;
 }
@@ -218,7 +199,7 @@ interface AuthKit {
     readonly client: NajmAuthClient;
     /** Shortcut for `client.api` — the underlying FetchClient with auth attached. */
     readonly api: FetchClient;
-    /** Resolve session — reads signed cookie first (instant), falls back to /auth/me */
+    /** Resolve session — signed-cookie first, then non-rotating recovery. */
     getSession: (opts?: Pick<GetSessionConfig, 'mode'>) => Promise<ServerSession | null>;
     /** Require session — throws if unauthenticated */
     requireSession: () => Promise<ServerSession>;

package/dist/client/server/index.js

@@ -144,6 +144,104 @@ var init_sessionCookie = __esm({
   }
 });
 
+// src/client/sessionRecovery.ts
+async function requestSessionRecovery(options) {
+  if (!isCookieName(options.refreshCookieName) || !isCookieName(options.sessionCookieName)) {
+    return { status: "unavailable" };
+  }
+  if (!isCookieValue(options.refreshCookieValue)) {
+    return { status: "invalid" };
+  }
+  if (!isSafeRecoveryEndpoint(options.endpoint)) {
+    return { status: "unavailable" };
+  }
+  let response;
+  try {
+    response = await fetch(options.endpoint, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        Cookie: `${options.refreshCookieName}=${options.refreshCookieValue}`,
+        "X-Najm-Session-Recovery": "1"
+      },
+      cache: "no-store",
+      redirect: "manual"
+    });
+  } catch {
+    return { status: "unavailable" };
+  }
+  if (!response.ok) {
+    const status = response.status;
+    return {
+      status: status === 400 || status === 401 || status === 403 ? "invalid" : "unavailable",
+      httpStatus: status
+    };
+  }
+  const setCookie = response.headers.get("set-cookie");
+  if (!setCookie) return { status: "unavailable", httpStatus: response.status };
+  const sessionCookieValue = readSetCookieValue(setCookie, options.sessionCookieName);
+  if (!sessionCookieValue) {
+    return { status: "unavailable", httpStatus: response.status };
+  }
+  const claims = await verifySessionCookie(sessionCookieValue, {
+    secret: options.sessionSecret,
+    maxAgeSeconds: options.sessionMaxAge
+  });
+  if (!claims) return { status: "unavailable", httpStatus: response.status };
+  return {
+    status: "recovered",
+    claims,
+    setCookie,
+    sessionCookieValue
+  };
+}
+function authEndpoint(baseURL, authPrefix, suffix, requestURL) {
+  const normalizedBase = baseURL.replace(/\/+$/, "");
+  const normalizedPrefix = `/${authPrefix.replace(/^\/+|\/+$/g, "")}`;
+  const normalizedSuffix = `/${suffix.replace(/^\/+/, "")}`;
+  const value = `${normalizedBase}${normalizedPrefix}${normalizedSuffix}`;
+  return requestURL ? new URL(value, requestURL).toString() : value;
+}
+function replaceCookieValue(cookieHeader, name, value) {
+  const parts = cookieHeader.split(";").map((part) => part.trim()).filter(Boolean).filter((part) => part.slice(0, part.indexOf("=")).trim() !== name);
+  parts.push(`${name}=${value}`);
+  return parts.join("; ");
+}
+function readSetCookieValue(setCookie, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = setCookie.match(new RegExp(`(?:^|,\\s*)${escaped}=([^;]*)`));
+  return match?.[1] || void 0;
+}
+function isCookieName(value) {
+  return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(value);
+}
+function isCookieValue(value) {
+  return value.length > 0 && !/[\r\n;]/.test(value);
+}
+function isSafeRecoveryEndpoint(value) {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) return false;
+    if (url.protocol === "https:") return true;
+    if (url.protocol !== "http:") return false;
+    return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+var init_sessionRecovery = __esm({
+  "src/client/sessionRecovery.ts"() {
+    init_sessionCookie();
+    __name(requestSessionRecovery, "requestSessionRecovery");
+    __name(authEndpoint, "authEndpoint");
+    __name(replaceCookieValue, "replaceCookieValue");
+    __name(readSetCookieValue, "readSetCookieValue");
+    __name(isCookieName, "isCookieName");
+    __name(isCookieValue, "isCookieValue");
+    __name(isSafeRecoveryEndpoint, "isSafeRecoveryEndpoint");
+  }
+});
+
 // src/client/server/getSession.ts
 var getSession_exports = {};
 __export(getSession_exports, {
@@ -158,88 +256,77 @@ function defaultBaseURL() {
   const origin = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_API_URL ?? `http://localhost:${process.env.PORT ?? 3e3}` : "http://localhost:3000";
   return `${origin.replace(/\/$/, "")}/api`;
 }
-function buildSession(body) {
-  if (!body?.data) return null;
-  const { roles, permissions, ...user } = body.data;
-  return {
-    user,
-    roles: roles ?? (user.role ? [user.role] : void 0),
-    permissions: permissions ?? user.permissions
-  };
-}
 async function getSession(config = {}) {
   const cookieName = config.cookieName ?? "refreshToken";
   const sessionCookieName = config.sessionCookieName ?? "najm.session";
   const baseURL = config.baseURL ?? defaultBaseURL();
   const prefix = config.authPrefix ?? "/auth";
   const strict = config.mode === "strict";
-  let cookieHeader = "";
   let sessionCookieValue;
-  let hasRefreshCookie = false;
+  let refreshCookieValue;
   try {
     const mod = await import("next/headers");
     const cookieStore = await mod.cookies();
-    const sessionCookie = cookieStore.get(sessionCookieName);
-    if (sessionCookie) sessionCookieValue = sessionCookie.value;
-    if (typeof cookieStore.get === "function") {
-      hasRefreshCookie = !!cookieStore.get(cookieName);
-    }
-    cookieHeader = cookieStore.getAll().map((c) => `${c.name}=${c.value}`).join("; ");
-  } catch (err) {
+    sessionCookieValue = cookieStore.get(sessionCookieName)?.value;
+    refreshCookieValue = cookieStore.get(cookieName)?.value;
+  } catch {
     if (strict) throw new AuthConfigError("Failed to read cookies from Next.js headers()");
     return null;
   }
-  if (sessionCookieValue) {
-    const secret = resolveSessionSecret(config.sessionSecret);
-    if (!secret) {
-      if (strict) throw new AuthConfigError("Session cookie secret is not configured");
-      return null;
-    }
+  const secret = resolveSessionSecret(config.sessionSecret);
+  if (sessionCookieValue && secret) {
     const claims = await verifySessionCookie(sessionCookieValue, {
       secret,
       maxAgeSeconds: config.sessionMaxAge
     });
-    if (!claims) {
-      if (strict) throw new NoSessionError("Invalid or expired session cookie");
-      return null;
+    if (claims) {
+      return {
+        user: claims.user,
+        roles: claims.roles,
+        permissions: claims.permissions
+      };
     }
-    return {
-      user: claims.user,
-      roles: claims.roles,
-      permissions: claims.permissions
-    };
   }
-  if (!hasRefreshCookie) {
-    if (strict) throw new NoSessionError("No refresh token cookie");
+  if (!secret) {
+    if (strict) throw new AuthConfigError("Session cookie secret is not configured");
     return null;
   }
-  if (!cookieHeader) {
-    if (strict) throw new NoSessionError("Empty cookie header");
+  if (!refreshCookieValue || config.recoveryURL === false) {
+    if (strict) throw new NoSessionError("No recoverable refresh session");
     return null;
   }
-  try {
-    const res = await fetch(`${baseURL}${prefix}/me`, {
-      headers: { Cookie: cookieHeader, Accept: "application/json" },
-      cache: "no-store"
-    });
-    if (!res.ok) {
-      if (strict) throw new AuthTransportError(`/auth/me returned ${res.status}`, res.status);
-      return null;
+  const endpoint = config.recoveryURL ? new URL(config.recoveryURL, baseURL).toString() : authEndpoint(baseURL, prefix, "/session/recover");
+  const recovery = await requestSessionRecovery({
+    endpoint,
+    refreshCookieName: cookieName,
+    refreshCookieValue,
+    sessionCookieName,
+    sessionSecret: secret,
+    sessionMaxAge: config.sessionMaxAge
+  });
+  if (recovery.status === "recovered") {
+    return {
+      user: recovery.claims.user,
+      roles: recovery.claims.roles,
+      permissions: recovery.claims.permissions
+    };
+  }
+  if (strict) {
+    if (recovery.status === "invalid") {
+      throw new NoSessionError("Refresh session is invalid or revoked");
     }
-    const body = await res.json();
-    const session = buildSession(body);
-    if (!session && strict) throw new NoSessionError("No user data in /auth/me response");
-    return session;
-  } catch (err) {
-    if (err instanceof NoSessionError || err instanceof AuthTransportError) throw err;
-    if (strict) throw new AuthTransportError(`Failed to fetch /auth/me: ${err.message}`);
-    return null;
+    throw new AuthTransportError(
+      "Session recovery endpoint was unavailable or returned an invalid session",
+      recovery.httpStatus
+    );
   }
+  return null;
 }
 var NoSessionError, AuthConfigError, AuthTransportError;
 var init_getSession = __esm({
   "src/client/server/getSession.ts"() {
     init_sessionCookie();
+    init_sessionRecovery();
     NoSessionError = class extends Error {
       static {
         __name(this, "NoSessionError");
@@ -272,7 +359,6 @@ var init_getSession = __esm({
       code = "AUTH_TRANSPORT_ERROR";
     };
     __name(defaultBaseURL, "defaultBaseURL");
-    __name(buildSession, "buildSession");
     __name(getSession, "getSession");
   }
 });
@@ -468,6 +554,7 @@ __name(createServerClient, "createServerClient");
 
 // src/client/server/withAuthMiddleware.ts
 init_sessionCookie();
+init_sessionRecovery();
 function withAuthMiddleware(config) {
   const {
     protectedRoutes = [],
@@ -475,26 +562,31 @@ function withAuthMiddleware(config) {
     loginRoute = "/login",
     roleRoutes = {},
     cookieName = "refreshToken",
+    apiBaseURL = "/api",
+    authPrefix = "/auth",
     sessionCookieName = "najm.session",
     sessionSecret,
     sessionMaxAge,
-    verifyAlways = false
+    verifyAlways = false,
+    recoveryURL
   } = config;
-  void verifyAlways;
   return /* @__PURE__ */ __name(async function middleware(request) {
     const { NextResponse } = await import("next/server");
-    const redirectToLogin = /* @__PURE__ */ __name((pathname2, clearCookies) => {
+    const redirectToLogin = /* @__PURE__ */ __name((returnPath2, clearCookies) => {
       const loginUrl = new URL(loginRoute, request.url);
-      loginUrl.searchParams.set("from", pathname2);
+      loginUrl.searchParams.set("from", returnPath2);
       const res = NextResponse.redirect(loginUrl);
-      if (clearCookies) {
+      if (clearCookies.includes("refresh")) {
         res.cookies.delete(cookieName);
+      }
+      if (clearCookies.includes("session")) {
         res.cookies.delete(sessionCookieName);
       }
       return res;
     }, "redirectToLogin");
     const url = new URL(request.url);
     const pathname = url.pathname;
+    const returnPath = `${url.pathname}${url.search}`;
     if (matchesAny(pathname, publicRoutes)) {
       return NextResponse.next();
     }
@@ -503,19 +595,53 @@ function withAuthMiddleware(config) {
     const cookie = request.headers.get("cookie") ?? "";
     const sessionCookie = readCookieValue(cookie, sessionCookieName);
     const secret = resolveSessionSecret(sessionSecret);
-    if (!sessionCookie || !secret) {
-      return redirectToLogin(pathname, true);
+    if (!secret) {
+      return redirectToLogin(returnPath, ["session"]);
     }
-    const session = await verifySessionCookie(sessionCookie, {
+    let session = sessionCookie ? await verifySessionCookie(sessionCookie, {
       secret,
       maxAgeSeconds: sessionMaxAge
-    });
-    if (!session) {
-      return redirectToLogin(pathname, true);
+    }) : null;
+    let recovery = null;
+    if (!session || verifyAlways) {
+      const refreshCookie = readCookieValue(cookie, cookieName);
+      if (!refreshCookie || recoveryURL === false) {
+        return redirectToLogin(returnPath, ["refresh", "session"]);
+      }
+      const endpoint = recoveryURL ? new URL(recoveryURL, request.url).toString() : authEndpoint(apiBaseURL, authPrefix, "/session/recover", request.url);
+      recovery = await requestSessionRecovery({
+        endpoint,
+        refreshCookieName: cookieName,
+        refreshCookieValue: refreshCookie,
+        sessionCookieName,
+        sessionSecret: secret,
+        sessionMaxAge
+      });
+      if (recovery.status !== "recovered") {
+        return redirectToLogin(
+          returnPath,
+          recovery.status === "invalid" ? ["refresh", "session"] : ["session"]
+        );
+      }
+      session = recovery.claims;
     }
     const requiredRoles = findMatchingRoles(pathname, roleRoutes);
     if (requiredRoles && !session.roles.some((role) => requiredRoles.includes(role))) {
-      return new NextResponse(null, { status: 403 });
+      const forbidden = new NextResponse(null, { status: 403 });
+      if (recovery?.status === "recovered") {
+        forbidden.headers.append("Set-Cookie", recovery.setCookie);
+      }
+      return forbidden;
+    }
+    if (recovery?.status === "recovered") {
+      const requestHeaders = new Headers(request.headers);
+      requestHeaders.set(
+        "cookie",
+        replaceCookieValue(cookie, sessionCookieName, recovery.sessionCookieValue)
+      );
+      const response = NextResponse.next({ request: { headers: requestHeaders } });
+      response.headers.append("Set-Cookie", recovery.setCookie);
+      return response;
     }
     return NextResponse.next();
   }, "middleware");
@@ -1049,6 +1175,7 @@ function defineAuth(authConfig = {}) {
     sessionCookieName = "najm.session",
     sessionSecret,
     sessionMaxAge,
+    recoveryURL,
     matcher = ["/((?!_next/static|_next/image|favicon.ico|api).*)"],
     verifyAlways = false,
     refreshThreshold,
@@ -1064,7 +1191,8 @@ function defineAuth(authConfig = {}) {
     cookieName,
     sessionCookieName,
     sessionSecret,
-    sessionMaxAge
+    sessionMaxAge,
+    recoveryURL
   };
   let _client = null;
   const getClient = /* @__PURE__ */ __name(() => {
@@ -1112,9 +1240,12 @@ function defineAuth(authConfig = {}) {
     loginRoute,
     roleRoutes,
     cookieName,
+    apiBaseURL,
+    authPrefix,
     sessionCookieName,
     sessionSecret,
     sessionMaxAge,
+    recoveryURL,
     verifyAlways
   });
   const protect = /* @__PURE__ */ __name((Page, options) => {

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { User, NewUser, RoleEntity, NewRoleEntity, Permission, NewPermission, Ro
 export { NewOAuthAccount, NewRolePermission, NewToken, OAuthAccount, Token, authSchema, baseFields, oauthAccountsTable, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } from './schema/pg.js';
 import { CacheService } from 'najm-cache';
 import { z } from 'zod';
+import { Context } from 'hono';
 import { GuardResult } from 'najm-guard';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
@@ -279,6 +280,7 @@ var auth = {
 		passwordReset: "Password has been reset successfully",
 		accountInviteSent: "Invitation sent successfully",
 		tokenRefreshed: "Token refreshed successfully",
+		sessionRecovered: "Session recovered successfully",
 		oauthLogin: "Google sign-in successful",
 		oauthLinked: "Google account linked successfully"
 	},
@@ -396,6 +398,7 @@ declare const AUTH_LOCALES: {
                 passwordReset: string;
                 accountInviteSent: string;
                 tokenRefreshed: string;
+                sessionRecovered: string;
                 oauthLogin: string;
                 oauthLinked: string;
             };
@@ -932,7 +935,21 @@ declare class TokenService {
      * the active session. Reuse detection and revocation belong to the
      * rotation path only.
      */
+    private resolveRefreshSessionFromCookie;
     resolveUserFromCookie(): Promise<string>;
+    /**
+     * Resolve authoritative claims for signed-session recovery.
+     *
+     * This deliberately bypasses the 30-second user cache so status, role, and
+     * permission changes are reflected when the short session snapshot expires.
+     * It validates but never rotates or consumes the refresh token.
+     */
+    recoverSessionFromCookie(): Promise<{
+        user: any;
+        roles: any[];
+        permissions: any;
+        sessionVersion: number;
+    }>;
     getUser(auth: string): Promise<any>;
     getUserById(userId: string): Promise<any>;
     private hashToken;
@@ -1009,6 +1026,7 @@ declare class TokenService {
         accessTokenExpiresAt: number;
         refreshTokenExpiresAt: number;
     }>;
+    private requireActiveRefreshUser;
     /** Revoke every refresh session for a user (password change/reset, logout-all). */
     revokeAllForUser(userId: string): Promise<any>;
     /** Revoke a single refresh session (one family). */
@@ -1242,6 +1260,14 @@ declare class AuthService {
         user: SanitizedUser;
     }>;
     refreshTokens(): Promise<TokenPair>;
+    /**
+     * Reissue the short-lived signed session snapshot from a fully validated
+     * refresh session. This path never creates or returns access/refresh tokens
+     * and never rotates the refresh family.
+     */
+    recoverSession(): Promise<{
+        recovered: true;
+    }>;
     logoutUser(userId: string, authorization?: string): Promise<{
         data: any;
         message: string;
@@ -1310,6 +1336,9 @@ declare class AuthController {
         emailSent: boolean;
     }>;
     refreshTokens(): Promise<TokenPair>;
+    recoverSession(recoveryRequest: string | undefined, ctx: Context): Promise<{
+        recovered: true;
+    }>;
     logoutUser(userId: string, authorization?: string): Promise<{
         data: any;
         message: string;

package/dist/index.js

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 };
 
 // src/AuthPlugin.ts
-import { Err as Err10, plugin } from "najm-core";
+import { Err as Err11, plugin } from "najm-core";
 import { cache } from "najm-cache";
 
 // src/auth.tokens.ts
@@ -431,9 +431,9 @@ CookieManager = __decorate2([
 ], CookieManager);
 
 // src/auth/AuthController.ts
-import { Controller } from "najm-core";
+import { Controller, Err as Err9 } from "najm-core";
 import { Get, Post, ResMsg } from "najm-core";
-import { Body, User as User2, Headers } from "najm-core";
+import { Body, User as User2, Headers, Ctx } from "najm-core";
 
 // src/auth/AuthService.ts
 import { Injectable as Injectable8, Inject as Inject8 } from "najm-core";
@@ -1638,7 +1638,7 @@ var TokenService = class TokenService2 {
    * the active session. Reuse detection and revocation belong to the
    * rotation path only.
    */
-  async resolveUserFromCookie() {
+  async resolveRefreshSessionFromCookie() {
     const refreshToken = this.cookieManager.getRefreshToken();
     if (!refreshToken) {
       Err6(this.t("errors.refreshTokenMissing"));
@@ -1650,14 +1650,35 @@ var TokenService = class TokenService2 {
     }
     const presentedHash = this.hashToken(refreshToken);
     if (presentedHash === stored.token) {
-      return userId;
+      return { userId, tokenFamily };
     }
     const canRecover = stored.previousHash && presentedHash === stored.previousHash && stored.previousValidUntil && new Date(stored.previousValidUntil).getTime() > Date.now() && !stored.previousUsedAt;
     if (canRecover) {
-      return userId;
+      return { userId, tokenFamily };
     }
     Err6(this.t("errors.refreshTokenInvalid"));
   }
+  async resolveUserFromCookie() {
+    return (await this.resolveRefreshSessionFromCookie()).userId;
+  }
+  /**
+   * Resolve authoritative claims for signed-session recovery.
+   *
+   * This deliberately bypasses the 30-second user cache so status, role, and
+   * permission changes are reflected when the short session snapshot expires.
+   * It validates but never rotates or consumes the refresh token.
+   */
+  async recoverSessionFromCookie() {
+    const { userId, tokenFamily } = await this.resolveRefreshSessionFromCookie();
+    const user = await this.requireActiveRefreshUser(userId, tokenFamily);
+    const sessionVersion = await this.getUserSessionVersion(userId);
+    return {
+      user,
+      roles: user.role ? [user.role] : [],
+      permissions: Array.isArray(user.permissions) ? user.permissions : [],
+      sessionVersion
+    };
+  }
   // ============ USER RETRIEVAL (MAIN METHOD) ============
   async getUser(auth2) {
     if (!auth2)
@@ -1820,6 +1841,7 @@ var TokenService = class TokenService2 {
       Err6(this.t("errors.refreshTokenInvalid"));
     }
     const presentedHash = this.hashToken(refreshToken);
+    await this.requireActiveRefreshUser(userId, tokenFamily);
     if (presentedHash === stored.token) {
       return this.generateTokens(userId, tokenFamily);
     }
@@ -1834,6 +1856,14 @@ var TokenService = class TokenService2 {
     await this.revokeSuspectRefreshFamily(userId, tokenFamily);
     Err6(this.t("errors.refreshTokenInvalid"));
   }
+  async requireActiveRefreshUser(userId, tokenFamily) {
+    const user = await this.tokenRepository.getUser(userId);
+    if (!user || user.status !== "active") {
+      await this.revokeFamily(tokenFamily);
+      Err6(this.t("errors.refreshTokenInvalid"));
+    }
+    return user;
+  }
   /** Revoke every refresh session for a user (password change/reset, logout-all). */
   async revokeAllForUser(userId) {
     return this.tokenRepository.revokeAllForUser(userId);
@@ -2276,6 +2306,27 @@ var AuthService = class AuthService2 {
     const { userId: _userId, tokenFamily: _tokenFamily, roles: _roles, permissions: _permissions, sessionVersion: _sv, ...tokens } = generated;
     return tokens;
   }
+  /**
+   * Reissue the short-lived signed session snapshot from a fully validated
+   * refresh session. This path never creates or returns access/refresh tokens
+   * and never rotates the refresh family.
+   */
+  async recoverSession() {
+    const recovered = await this.tokenService.recoverSessionFromCookie();
+    this.cookieManager.setSessionCookie({
+      user: {
+        id: recovered.user.id,
+        email: recovered.user.email,
+        name: recovered.user.name,
+        role: recovered.user.role ?? void 0,
+        status: recovered.user.status ?? void 0
+      },
+      roles: recovered.roles,
+      permissions: recovered.permissions,
+      sessionVersion: recovered.sessionVersion
+    });
+    return { recovered: true };
+  }
   async logoutUser(userId, authorization) {
     await this.tokenService.logout(userId, authorization);
     this.cookieManager.clearRefreshToken();
@@ -2604,6 +2655,14 @@ var AuthController = class AuthController2 {
   async refreshTokens() {
     return this.authService.refreshTokens();
   }
+  async recoverSession(recoveryRequest, ctx) {
+    if (recoveryRequest !== "1") {
+      Err9("Invalid session recovery request", 400);
+    }
+    ctx.header("Cache-Control", "private, no-store");
+    ctx.header("Vary", "Cookie");
+    return this.authService.recoverSession();
+  }
   async logoutUser(userId, authorization) {
     return this.authService.logoutUser(userId, authorization);
   }
@@ -2659,6 +2718,16 @@ __decorate15([
   __metadata15("design:paramtypes", []),
   __metadata15("design:returntype", Promise)
 ], AuthController.prototype, "refreshTokens", null);
+__decorate15([
+  Post("/session/recover"),
+  RateLimit({ limit: 120, window: "1m", key: cookieFingerprint() }),
+  ResMsg("auth.success.sessionRecovered"),
+  __param5(0, Headers("x-najm-session-recovery")),
+  __param5(1, Ctx()),
+  __metadata15("design:type", Function),
+  __metadata15("design:paramtypes", [String, Object]),
+  __metadata15("design:returntype", Promise)
+], AuthController.prototype, "recoverSession", null);
 __decorate15([
   Post("/logout"),
   isAuth(),
@@ -3471,7 +3540,7 @@ import { Injectable as Injectable11 } from "najm-core";
 // src/permissions/PermissionValidator.ts
 import { Injectable as Injectable10 } from "najm-core";
 import { I18n as I18n7 } from "najm-i18n";
-import { Err as Err9 } from "najm-core";
+import { Err as Err10 } from "najm-core";
 var __decorate21 = function(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -3500,7 +3569,7 @@ var PermissionValidator = class PermissionValidator2 {
   async checkPermissionExists(id) {
     const permission = await this.permissionRepository.getById(id);
     if (!permission) {
-      Err9(this.t("errors.notFound"), 404);
+      Err10(this.t("errors.notFound"), 404);
     }
     return permission;
   }
@@ -3510,7 +3579,7 @@ var PermissionValidator = class PermissionValidator2 {
   async checkPermissionExistsByName(name) {
     const permission = await this.permissionRepository.getByName(name);
     if (!permission) {
-      Err9(this.t("errors.notFound"), 404);
+      Err10(this.t("errors.notFound"), 404);
     }
     return permission;
   }
@@ -3522,7 +3591,7 @@ var PermissionValidator = class PermissionValidator2 {
       return;
     const existingPermission = await this.permissionRepository.getByName(name);
     if (existingPermission && existingPermission.id !== excludeId) {
-      Err9(this.t("errors.nameExists"), 409);
+      Err10(this.t("errors.nameExists"), 409);
     }
   }
   /**
@@ -3545,7 +3614,7 @@ var PermissionValidator = class PermissionValidator2 {
     await this.checkPermissionExists(permissionId);
     const hasPermission = await this.permissionRepository.checkRoleHasPermission(roleId, permissionId);
     if (hasPermission) {
-      Err9(this.t("errors.roleAlreadyHasPermission"), 409);
+      Err10(this.t("errors.roleAlreadyHasPermission"), 409);
     }
   }
 };
@@ -4594,6 +4663,7 @@ var en_default = {
       passwordReset: "Password has been reset successfully",
       accountInviteSent: "Invitation sent successfully",
       tokenRefreshed: "Token refreshed successfully",
+      sessionRecovered: "Session recovered successfully",
       oauthLogin: "Google sign-in successful",
       oauthLinked: "Google account linked successfully"
     },
@@ -5010,7 +5080,7 @@ OAuthAccountService = __decorate29([
 
 // src/oauth/OAuthController.ts
 import { createHash as createHash4 } from "crypto";
-import { Controller as Controller5, Ctx, Get as Get5, Post as Post5, Query as Query2, User as User5 } from "najm-core";
+import { Controller as Controller5, Ctx as Ctx2, Get as Get5, Post as Post5, Query as Query2, User as User5 } from "najm-core";
 import { RateLimit as RateLimit2 } from "najm-rate";
 
 // src/oauth/OAuthService.ts
@@ -5296,7 +5366,7 @@ var OAuthController = class OAuthController2 {
 __decorate32([
   Get5("/start"),
   RateLimit2({ limit: 20, window: "15m", key: "ip" }),
-  __param11(0, Ctx()),
+  __param11(0, Ctx2()),
   __param11(1, Query2("returnTo")),
   __metadata32("design:type", Function),
   __metadata32("design:paramtypes", [Object, String]),
@@ -5305,7 +5375,7 @@ __decorate32([
 __decorate32([
   Get5("/callback"),
   RateLimit2({ limit: 20, window: "15m", key: callbackKey }),
-  __param11(0, Ctx()),
+  __param11(0, Ctx2()),
   __param11(1, Query2("code")),
   __param11(2, Query2("state")),
   __param11(3, Query2("error")),
@@ -5360,9 +5430,9 @@ var resolveGoogleConfig = /* @__PURE__ */ __name((config) => {
   const clientId = google.clientId ?? process.env.GOOGLE_CLIENT_ID ?? "";
   const clientSecret = google.clientSecret ?? process.env.GOOGLE_CLIENT_SECRET ?? "";
   if (!clientId)
-    throw Err10.configRequired("auth.oauth.google", "GOOGLE_CLIENT_ID");
+    throw Err11.configRequired("auth.oauth.google", "GOOGLE_CLIENT_ID");
   if (!clientSecret)
-    throw Err10.configRequired("auth.oauth.google", "GOOGLE_CLIENT_SECRET");
+    throw Err11.configRequired("auth.oauth.google", "GOOGLE_CLIENT_SECRET");
   const frontendUrl = config?.frontendUrl ?? process.env.FRONTEND_URL ?? "http://localhost:3000";
   const callbackUrl = google.callbackUrl ?? process.env.GOOGLE_CALLBACK_URL ?? `${frontendUrl.replace(/\/$/, "")}/api/auth/oauth/google/callback`;
   let callback;
@@ -5421,10 +5491,10 @@ var resolveAuthConfig = /* @__PURE__ */ __name((config) => {
     }
   };
   if (!finalConfig.jwt.accessSecret) {
-    throw Err10.configRequired("auth", "JWT_ACCESS_SECRET");
+    throw Err11.configRequired("auth", "JWT_ACCESS_SECRET");
   }
   if (!finalConfig.jwt.refreshSecret) {
-    throw Err10.configRequired("auth", "JWT_REFRESH_SECRET");
+    throw Err11.configRequired("auth", "JWT_REFRESH_SECRET");
   }
   return finalConfig;
 }, "resolveAuthConfig");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Authentication and authorization library for najm framework",
   "type": "module",
   "files": [