najm-auth 1.1.19 → 1.1.21

package/dist/{FetchClient-aatsED1a.d.ts → FetchClient-DadnuVF7.d.ts}

@@ -83,6 +83,8 @@ interface AuthClientConfig {
 interface AuthEventMap {
     login: AuthUser;
     logout: null;
+    /** Emitted when server-side logout invalidation fails (state was already cleared) */
+    logoutError: unknown;
     tokenRefresh: null;
     sessionExpired: null;
     stateChange: AuthState;

package/dist/{NajmAuthClient-FCwA8LIg.d.ts → NajmAuthClient-CZHKl4ri.d.ts}

@@ -1,4 +1,4 @@
-import { F as FetchClient, a as AuthClientConfig, d as AuthUser, c as AuthState, e as AuthEvent, f as AuthEventHandler } from './FetchClient-aatsED1a.js';
+import { F as FetchClient, a as AuthClientConfig, d as AuthUser, c as AuthState, e as AuthEvent, f as AuthEventHandler } from './FetchClient-DadnuVF7.js';
 
 interface HydrateSession {
     user: AuthUser | null;

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
-export { H as HydrateSession, N as NajmAuthClient, c as createAuthClient } from '../NajmAuthClient-FCwA8LIg.js';
-import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../FetchClient-aatsED1a.js';
-export { a as AuthClientConfig, A as AuthError, e as AuthEvent, f as AuthEventHandler, b as AuthEventMap, c as AuthState, d as AuthUser, F as FetchClient, i as RequestOptions, R as RetryConfig, g as ServerResponse, h as TokenPair } from '../FetchClient-aatsED1a.js';
+export { H as HydrateSession, N as NajmAuthClient, c as createAuthClient } from '../NajmAuthClient-CZHKl4ri.js';
+import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../FetchClient-DadnuVF7.js';
+export { a as AuthClientConfig, A as AuthError, e as AuthEvent, f as AuthEventHandler, b as AuthEventMap, c as AuthState, d as AuthUser, F as FetchClient, i as RequestOptions, R as RetryConfig, g as ServerResponse, h as TokenPair } from '../FetchClient-DadnuVF7.js';
 
 /**
  * Decode a JWT token payload without verification.

package/dist/client/index.js

@@ -265,13 +265,14 @@ var NajmAuthClient = class _NajmAuthClient {
     return res.data;
   }
   async logout() {
-    try {
-      await this.api.post(`${this.prefix}/logout`);
-    } catch {
-    }
     this.resetState();
     this.tabSync?.broadcastLogout();
     this.emit("logout", null);
+    try {
+      await this.api.post(`${this.prefix}/logout`);
+    } catch (err) {
+      this.emit("logoutError", err);
+    }
   }
   async refresh() {
     if (this.refreshFailures >= _NajmAuthClient.MAX_REFRESH_FAILURES) {

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

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, ReactElement } from 'react';
-import { N as NajmAuthClient, H as HydrateSession } from '../../NajmAuthClient-FCwA8LIg.js';
-import { c as AuthState, d as AuthUser, A as AuthError, e as AuthEvent, b as AuthEventMap } from '../../FetchClient-aatsED1a.js';
+import { N as NajmAuthClient, H as HydrateSession } from '../../NajmAuthClient-CZHKl4ri.js';
+import { c as AuthState, d as AuthUser, A as AuthError, e as AuthEvent, b as AuthEventMap } from '../../FetchClient-DadnuVF7.js';
 
 interface AuthProviderProps {
     client: NajmAuthClient;
@@ -91,6 +91,8 @@ interface UseRegisterReturn {
 declare function useRegister(opts?: UseRegisterOptions): UseRegisterReturn;
 
 interface UseLogoutOptions {
+    /** URL to redirect to after logout (uses window.location for full page reload) */
+    redirectTo?: string;
     onSuccess?: () => void;
     onError?: (error: Error) => void;
 }
@@ -317,9 +319,9 @@ interface ProtectedProps {
     role?: string;
     /** Require a specific permission */
     permission?: string;
-    /** Shown while session is loading */
+    /** Shown while session is loading (defaults to fallback) */
     loadingFallback?: ReactNode;
-    /** Shown when access is denied */
+    /** Shown when access is denied (defaults to loadingFallback) */
     fallback?: ReactNode;
 }
 /**
@@ -338,6 +340,36 @@ interface ProtectedProps {
  */
 declare function Protected({ children, redirectTo, onUnauthenticated, role, permission, loadingFallback, fallback, }: ProtectedProps): react_jsx_runtime.JSX.Element;
 
+interface AuthGateProps {
+    children: ReactNode;
+    /** Full-page loader shown while resolving auth on hard reload */
+    loader?: ReactNode;
+    /** Where to redirect when unauthenticated (uses window.location for full reload) */
+    redirectTo?: string;
+    /** Callback when unauthenticated (overrides redirectTo) */
+    onUnauthenticated?: () => void;
+    /** Required role — renders `denied` if user lacks it */
+    role?: string;
+    /** Required permission — renders `denied` if user lacks it */
+    permission?: string;
+    /** Shown when role/permission check fails (defaults to null) */
+    denied?: ReactNode;
+}
+/**
+ * Full-page authentication gate.
+ *
+ * **Key difference from hooks**: AuthGate never renders `children` until
+ * auth is confirmed. No conditional rendering bugs, no layout shift,
+ * no flash of protected content.
+ *
+ * **With SSR hydration**: If `AuthProvider` was hydrated with `initialSession`,
+ * the gate opens immediately on first render — no loader flash.
+ *
+ * **Without SSR hydration** (client-side nav, hard reload without initialSession):
+ * Shows `loader` while attempting a token refresh, then either opens or redirects.
+ */
+declare function AuthGate({ children, loader, redirectTo, onUnauthenticated, role, permission, denied, }: AuthGateProps): react_jsx_runtime.JSX.Element;
+
 interface UserNameProps {
     /** Optional fallback shown when no user is loaded */
     fallback?: string;
@@ -492,4 +524,4 @@ interface RedirectToLoginProps {
  */
 declare function RedirectToLogin({ to, preserveFrom }: RedirectToLoginProps): any;
 
-export { type AuthEventEntry, AuthLoading, AuthProvider, Can, IfAuth, LoginButton, PermissionList, Protected, RedirectToLogin, Role, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserEmail, UserName, UserRole, useAuth, useAuthClient, useAuthEvent, useAuthEvents, useChangePassword, useForgotPassword, useLogin, useLogout, usePermissions, useRegister, useResetPassword, useSession, useUser };
+export { type AuthEventEntry, AuthGate, AuthLoading, AuthProvider, Can, IfAuth, LoginButton, PermissionList, Protected, RedirectToLogin, Role, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserEmail, UserName, UserRole, useAuth, useAuthClient, useAuthEvent, useAuthEvents, useChangePassword, useForgotPassword, useLogin, useLogout, usePermissions, useRegister, useResetPassword, useSession, useUser };

package/dist/client/react/index.js

@@ -152,6 +152,10 @@ function useLogout(opts) {
     setIsLoading(true);
     try {
       await client.logout();
+      if (opts?.redirectTo && typeof window !== "undefined") {
+        window.location.href = opts.redirectTo;
+        return;
+      }
       opts?.onSuccess?.();
     } catch (err) {
       const e = err instanceof Error ? err : new Error(String(err));
@@ -159,7 +163,7 @@ function useLogout(opts) {
     } finally {
       setIsLoading(false);
     }
-  }, [client, opts?.onSuccess, opts?.onError]);
+  }, [client, opts?.onSuccess, opts?.onError, opts?.redirectTo]);
   return { logout, isLoading };
 }
 __name(useLogout, "useLogout");
@@ -276,6 +280,7 @@ import { useEffect as useEffect3, useRef as useRef4, useState as useState8 } fro
 var ALL_EVENTS = [
   "login",
   "logout",
+  "logoutError",
   "tokenRefresh",
   "sessionExpired",
   "stateChange",
@@ -372,51 +377,98 @@ function Protected({
   onUnauthenticated,
   role,
   permission,
-  loadingFallback = null,
-  fallback = null
+  loadingFallback,
+  fallback
 }) {
+  const resolvedLoading = loadingFallback ?? fallback ?? null;
+  const resolvedFallback = fallback ?? loadingFallback ?? null;
   const { isLoading, isAuthenticated } = useSession({
     required: true,
     redirectTo,
     onUnauthenticated
   });
   const { can, hasRole } = usePermissions();
-  if (isLoading) return /* @__PURE__ */ jsx8(Fragment7, { children: loadingFallback });
-  if (!isAuthenticated) return /* @__PURE__ */ jsx8(Fragment7, { children: fallback });
-  if (role && !hasRole(role)) return /* @__PURE__ */ jsx8(Fragment7, { children: fallback });
-  if (permission && !can(permission)) return /* @__PURE__ */ jsx8(Fragment7, { children: fallback });
+  if (isLoading) return /* @__PURE__ */ jsx8(Fragment7, { children: resolvedLoading });
+  if (!isAuthenticated) return /* @__PURE__ */ jsx8(Fragment7, { children: resolvedFallback });
+  if (role && !hasRole(role)) return /* @__PURE__ */ jsx8(Fragment7, { children: resolvedFallback });
+  if (permission && !can(permission)) return /* @__PURE__ */ jsx8(Fragment7, { children: resolvedFallback });
   return /* @__PURE__ */ jsx8(Fragment7, { children });
 }
 __name(Protected, "Protected");
 
-// src/client/react/UserName.tsx
+// src/client/react/AuthGate.tsx
+import { useEffect as useEffect4, useSyncExternalStore as useSyncExternalStore2 } from "react";
 import { Fragment as Fragment8, jsx as jsx9 } from "react/jsx-runtime";
+function AuthGate({
+  children,
+  loader = null,
+  redirectTo,
+  onUnauthenticated,
+  role,
+  permission,
+  denied = null
+}) {
+  const client = useAuthClient();
+  const state = useSyncExternalStore2(
+    (cb) => client.subscribe(cb),
+    () => client.getState(),
+    () => client.getState()
+  );
+  const hydrated = client.isHydrated();
+  useEffect4(() => {
+    if (hydrated) return;
+    client.refresh().then(() => client.fetchUser()).catch(() => {
+    });
+  }, [client, hydrated]);
+  if (!hydrated && !state.isAuthenticated) {
+    return /* @__PURE__ */ jsx9(Fragment8, { children: loader });
+  }
+  if (!state.isAuthenticated) {
+    if (onUnauthenticated) {
+      onUnauthenticated();
+    } else if (redirectTo && typeof window !== "undefined") {
+      window.location.href = redirectTo;
+    }
+    return /* @__PURE__ */ jsx9(Fragment8, { children: loader });
+  }
+  if (role && !client.hasRole(role)) {
+    return /* @__PURE__ */ jsx9(Fragment8, { children: denied });
+  }
+  if (permission && !client.can(permission)) {
+    return /* @__PURE__ */ jsx9(Fragment8, { children: denied });
+  }
+  return /* @__PURE__ */ jsx9(Fragment8, { children });
+}
+__name(AuthGate, "AuthGate");
+
+// src/client/react/UserName.tsx
+import { Fragment as Fragment9, jsx as jsx10 } from "react/jsx-runtime";
 function UserName({ fallback = "" }) {
   const user = useUser();
-  if (!user) return /* @__PURE__ */ jsx9(Fragment8, { children: fallback });
+  if (!user) return /* @__PURE__ */ jsx10(Fragment9, { children: fallback });
   const name = user.name ?? user.email ?? fallback;
-  return /* @__PURE__ */ jsx9(Fragment8, { children: name });
+  return /* @__PURE__ */ jsx10(Fragment9, { children: name });
 }
 __name(UserName, "UserName");
 
 // src/client/react/UserEmail.tsx
-import { Fragment as Fragment9, jsx as jsx10 } from "react/jsx-runtime";
+import { Fragment as Fragment10, jsx as jsx11 } from "react/jsx-runtime";
 function UserEmail({ fallback = "" }) {
   const user = useUser();
-  return /* @__PURE__ */ jsx10(Fragment9, { children: user?.email ?? fallback });
+  return /* @__PURE__ */ jsx11(Fragment10, { children: user?.email ?? fallback });
 }
 __name(UserEmail, "UserEmail");
 
 // src/client/react/UserRole.tsx
-import { Fragment as Fragment10, jsx as jsx11 } from "react/jsx-runtime";
+import { Fragment as Fragment11, jsx as jsx12 } from "react/jsx-runtime";
 function UserRole({ fallback = "" }) {
   const { roles } = usePermissions();
-  return /* @__PURE__ */ jsx11(Fragment10, { children: roles[0] ?? fallback });
+  return /* @__PURE__ */ jsx12(Fragment11, { children: roles[0] ?? fallback });
 }
 __name(UserRole, "UserRole");
 
 // src/client/react/UserAvatar.tsx
-import { jsx as jsx12 } from "react/jsx-runtime";
+import { jsx as jsx13 } from "react/jsx-runtime";
 function UserAvatar({ size = 32, className, style, alt }) {
   const user = useUser();
   const baseStyle = {
@@ -439,7 +491,7 @@ function UserAvatar({ size = 32, className, style, alt }) {
   const initial = label ? label[0].toUpperCase() : "?";
   const altText = alt ?? label ?? "User avatar";
   if (src) {
-    return /* @__PURE__ */ jsx12(
+    return /* @__PURE__ */ jsx13(
       "img",
       {
         src,
@@ -451,7 +503,7 @@ function UserAvatar({ size = 32, className, style, alt }) {
       }
     );
   }
-  return /* @__PURE__ */ jsx12(
+  return /* @__PURE__ */ jsx13(
     "span",
     {
       role: "img",
@@ -465,11 +517,11 @@ function UserAvatar({ size = 32, className, style, alt }) {
 __name(UserAvatar, "UserAvatar");
 
 // src/client/react/PermissionList.tsx
-import { Fragment as Fragment11, jsx as jsx13 } from "react/jsx-runtime";
+import { Fragment as Fragment12, jsx as jsx14 } from "react/jsx-runtime";
 function PermissionList({ children, fallback = null }) {
   const { permissions } = usePermissions();
-  if (permissions.length === 0) return /* @__PURE__ */ jsx13(Fragment11, { children: fallback });
-  return /* @__PURE__ */ jsx13(Fragment11, { children: permissions.map((perm, i) => children(perm, i)) });
+  if (permissions.length === 0) return /* @__PURE__ */ jsx14(Fragment12, { children: fallback });
+  return /* @__PURE__ */ jsx14(Fragment12, { children: permissions.map((perm, i) => children(perm, i)) });
 }
 __name(PermissionList, "PermissionList");
 
@@ -508,9 +560,9 @@ function LoginButton({ href = "/login", children }) {
 __name(LoginButton, "LoginButton");
 
 // src/client/react/RedirectToLogin.tsx
-import { useEffect as useEffect4 } from "react";
+import { useEffect as useEffect5 } from "react";
 function RedirectToLogin({ to = "/login", preserveFrom = true }) {
-  useEffect4(() => {
+  useEffect5(() => {
     if (typeof window === "undefined") return;
     const target = preserveFrom ? `${to}?from=${encodeURIComponent(window.location.pathname + window.location.search)}` : to;
     window.location.href = target;
@@ -519,6 +571,7 @@ function RedirectToLogin({ to = "/login", preserveFrom = true }) {
 }
 __name(RedirectToLogin, "RedirectToLogin");
 export {
+  AuthGate,
   AuthLoading,
   AuthProvider,
   Can,

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

@@ -1,4 +1,4 @@
-import { d as AuthUser, F as FetchClient } from '../../FetchClient-aatsED1a.js';
+import { d as AuthUser, F as FetchClient } from '../../FetchClient-DadnuVF7.js';
 import * as next_server from 'next/server';
 
 interface GetServerSessionOptions {
@@ -115,19 +115,53 @@ interface GetSessionConfig {
      */
     authPrefix?: string;
     /**
-     * Cookie name to check before making the network call.
+     * Refresh token cookie name to check before making the network call.
      * If absent we skip and return null immediately.
      * Default: 'refreshToken'
      */
     cookieName?: string;
+    /**
+     * Session cookie name (default: 'najm.session').
+     * When present and valid, skips the /auth/me fetch entirely.
+     */
+    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;
+    /**
+     * Error handling mode:
+     * - 'nullable' (default): returns null on any failure
+     * - 'strict': throws typed errors for debugging
+     */
+    mode?: 'nullable' | 'strict';
+}
+declare class NoSessionError extends Error {
+    readonly code = "NO_SESSION";
+    constructor(message?: string);
+}
+declare class AuthConfigError extends Error {
+    readonly code = "AUTH_CONFIG_ERROR";
+    constructor(message: string);
+}
+declare class AuthTransportError extends Error {
+    readonly status?: number;
+    readonly code = "AUTH_TRANSPORT_ERROR";
+    constructor(message: string, status?: number);
 }
 /**
  * Resolve the current session inside a Next.js Server Component, Route Handler,
- * or Server Action. Returns `null` if the user is not authenticated.
+ * 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
- * // app/layout.tsx
  * import { getSession } from 'najm-auth/client/server';
  *
  * export default async function RootLayout({ children }) {
@@ -163,4 +197,53 @@ interface WithAuthProps<P> {
  */
 declare function withAuth<P extends Record<string, unknown> = Record<string, unknown>>(Page: (args: WithAuthProps<P>) => Promise<unknown> | unknown, options?: WithAuthOptions): (props: P) => Promise<unknown>;
 
-export { type GetSessionConfig, type ServerSession, type WithAuthOptions, type WithAuthProps, createServerClient, getServerSession, getSession, withAuth, withAuthMiddleware };
+interface DefineAuthConfig {
+    /** API base URL (default: '/api') */
+    apiBaseURL?: string;
+    /** Auth prefix appended to apiBaseURL (default: '/auth') */
+    authPrefix?: string;
+    /** Route to redirect unauthenticated users (default: '/login') */
+    loginRoute?: string;
+    /** Route to redirect after login (default: '/dashboard') */
+    afterLoginRoute?: string;
+    /** Routes that are always public (glob patterns) */
+    publicRoutes?: string[];
+    /** Routes that require authentication (glob patterns) */
+    protectedRoutes?: string[];
+    /** Routes restricted to specific roles: { '/admin/:path*': ['admin'] } */
+    roleRoutes?: Record<string, string[]>;
+    /** Refresh token cookie name (default: 'refreshToken') */
+    cookieName?: string;
+    /** Session cookie name (default: 'najm.session') */
+    sessionCookieName?: string;
+    /** Secret for verifying session cookie HMAC. Falls back to env vars. */
+    sessionSecret?: string;
+    /** Next.js middleware matcher (default: exclude _next, favicon, api) */
+    matcher?: string[];
+}
+interface AuthKit {
+    /** Resolve session — reads signed cookie first (instant), falls back to /auth/me */
+    getSession: (opts?: Pick<GetSessionConfig, 'mode'>) => Promise<ServerSession | null>;
+    /** Require session — throws if unauthenticated */
+    requireSession: () => Promise<ServerSession>;
+    /** Generated Next.js middleware function */
+    middleware: (request: Request) => Promise<Response>;
+    /** Next.js middleware config with matcher */
+    config: {
+        matcher: string[];
+    };
+    /**
+     * Protect a server component — redirects to loginRoute if unauthenticated.
+     * Passes session to the wrapped component.
+     */
+    protect: <P extends Record<string, unknown> = Record<string, unknown>>(Page: (args: {
+        session: ServerSession;
+        children?: unknown;
+    } & P) => Promise<unknown> | unknown, options?: {
+        role?: string;
+        permission?: string;
+    }) => (props: P) => Promise<unknown>;
+}
+declare function defineAuth(authConfig?: DefineAuthConfig): AuthKit;
+
+export { AuthConfigError, type AuthKit, AuthTransportError, type DefineAuthConfig, type GetSessionConfig, NoSessionError, type ServerSession, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getServerSession, getSession, withAuth, withAuthMiddleware };

package/dist/client/server/index.js

@@ -1,5 +1,199 @@
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/client/server/getSession.ts
+var getSession_exports = {};
+__export(getSession_exports, {
+  AuthConfigError: () => AuthConfigError,
+  AuthTransportError: () => AuthTransportError,
+  NoSessionError: () => NoSessionError,
+  getSession: () => getSession
+});
+import { createHmac, timingSafeEqual } from "crypto";
+function defaultBaseURL() {
+  const explicit = typeof process !== "undefined" ? process.env.NAJM_AUTH_BASE_URL : void 0;
+  if (explicit) return explicit;
+  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 getSessionSecret(config) {
+  return config.sessionSecret ?? (typeof process !== "undefined" ? process.env.NAJM_SESSION_SECRET : void 0) ?? (typeof process !== "undefined" ? process.env.JWT_ACCESS_SECRET : void 0);
+}
+function verifyHmac(payload, signature, secret) {
+  const expected = createHmac("sha256", secret).update(payload).digest("base64url");
+  if (expected.length !== signature.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+  } catch {
+    return false;
+  }
+}
+function parseSessionCookie(raw, secret) {
+  const lastDot = raw.lastIndexOf(".");
+  if (lastDot === -1) return null;
+  const payload = raw.substring(0, lastDot);
+  const signature = raw.substring(lastDot + 1);
+  if (!verifyHmac(payload, signature, secret)) return null;
+  try {
+    const decoded = decodeURIComponent(payload);
+    const data = JSON.parse(decoded);
+    if (Date.now() - data.iat > SESSION_COOKIE_MAX_AGE_MS) return null;
+    const { user, roles, permissions } = data;
+    return {
+      user,
+      roles: roles ?? (user.role ? [user.role] : void 0),
+      permissions: permissions ?? void 0
+    };
+  } catch {
+    return null;
+  }
+}
+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;
+  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) {
+    if (strict) throw new AuthConfigError("Failed to read cookies from Next.js headers()");
+    return null;
+  }
+  if (sessionCookieValue) {
+    const secret = getSessionSecret(config);
+    if (secret) {
+      const session = parseSessionCookie(sessionCookieValue, secret);
+      if (session) return session;
+    }
+  }
+  if (!hasRefreshCookie) {
+    if (strict) throw new NoSessionError("No refresh token cookie");
+    return null;
+  }
+  if (!cookieHeader) {
+    if (strict) throw new NoSessionError("Empty cookie header");
+    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 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;
+  }
+}
+var NoSessionError, AuthConfigError, AuthTransportError, SESSION_COOKIE_MAX_AGE_MS;
+var init_getSession = __esm({
+  "src/client/server/getSession.ts"() {
+    NoSessionError = class extends Error {
+      static {
+        __name(this, "NoSessionError");
+      }
+      code = "NO_SESSION";
+      constructor(message = "No active session") {
+        super(message);
+        this.name = "NoSessionError";
+      }
+    };
+    AuthConfigError = class extends Error {
+      static {
+        __name(this, "AuthConfigError");
+      }
+      code = "AUTH_CONFIG_ERROR";
+      constructor(message) {
+        super(message);
+        this.name = "AuthConfigError";
+      }
+    };
+    AuthTransportError = class extends Error {
+      constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "AuthTransportError";
+      }
+      static {
+        __name(this, "AuthTransportError");
+      }
+      code = "AUTH_TRANSPORT_ERROR";
+    };
+    __name(defaultBaseURL, "defaultBaseURL");
+    __name(getSessionSecret, "getSessionSecret");
+    __name(verifyHmac, "verifyHmac");
+    SESSION_COOKIE_MAX_AGE_MS = 3e5;
+    __name(parseSessionCookie, "parseSessionCookie");
+    __name(buildSession, "buildSession");
+    __name(getSession, "getSession");
+  }
+});
+
+// src/client/permissions.ts
+var permissions_exports = {};
+__export(permissions_exports, {
+  hasAnyRole: () => hasAnyRole,
+  hasRole: () => hasRole,
+  matchPermission: () => matchPermission
+});
+function matchPermission(userPermissions, required) {
+  if (userPermissions.includes("*:*")) return true;
+  if (userPermissions.includes(required)) return true;
+  const sep = required.indexOf(":");
+  if (sep === -1) return false;
+  const action = required.slice(0, sep);
+  const resource = required.slice(sep + 1);
+  return userPermissions.includes(`${action}:*`) || userPermissions.includes(`*:${resource}`);
+}
+function hasRole(userRoles, role) {
+  return userRoles.includes(role);
+}
+function hasAnyRole(userRoles, roles) {
+  return roles.some((r) => userRoles.includes(r));
+}
+var init_permissions = __esm({
+  "src/client/permissions.ts"() {
+    __name(matchPermission, "matchPermission");
+    __name(hasRole, "hasRole");
+    __name(hasAnyRole, "hasAnyRole");
+  }
+});
 
 // src/client/server/getServerSession.ts
 async function getServerSession(opts) {
@@ -233,63 +427,12 @@ function findMatchingRoles(pathname, roleRoutes) {
 }
 __name(findMatchingRoles, "findMatchingRoles");
 
-// src/client/server/getSession.ts
-function defaultBaseURL() {
-  const explicit = typeof process !== "undefined" ? process.env.NAJM_AUTH_BASE_URL : void 0;
-  if (explicit) return explicit;
-  const origin = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_API_URL ?? `http://localhost:${process.env.PORT ?? 3e3}` : "http://localhost:3000";
-  return `${origin.replace(/\/$/, "")}/api`;
-}
-__name(defaultBaseURL, "defaultBaseURL");
-async function getSession(config = {}) {
-  const cookieName = config.cookieName ?? "refreshToken";
-  const baseURL = config.baseURL ?? defaultBaseURL();
-  const prefix = config.authPrefix ?? "/auth";
-  let cookieHeader = "";
-  try {
-    const mod = await import("next/headers");
-    const cookieStore = await mod.cookies();
-    if (typeof cookieStore.get === "function" && !cookieStore.get(cookieName)) {
-      return null;
-    }
-    cookieHeader = cookieStore.getAll().map((c) => `${c.name}=${c.value}`).join("; ");
-  } catch {
-    return null;
-  }
-  if (!cookieHeader) return null;
-  try {
-    const res = await fetch(`${baseURL}${prefix}/me`, {
-      headers: { Cookie: cookieHeader, Accept: "application/json" },
-      cache: "no-store"
-    });
-    if (!res.ok) return null;
-    const body = await res.json();
-    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
-    };
-  } catch {
-    return null;
-  }
-}
-__name(getSession, "getSession");
-
-// src/client/permissions.ts
-function matchPermission(userPermissions, required) {
-  if (userPermissions.includes("*:*")) return true;
-  if (userPermissions.includes(required)) return true;
-  const sep = required.indexOf(":");
-  if (sep === -1) return false;
-  const action = required.slice(0, sep);
-  const resource = required.slice(sep + 1);
-  return userPermissions.includes(`${action}:*`) || userPermissions.includes(`*:${resource}`);
-}
-__name(matchPermission, "matchPermission");
+// src/client/server/index.ts
+init_getSession();
 
 // src/client/server/withAuth.ts
+init_getSession();
+init_permissions();
 function withAuth(Page, options = {}) {
   const { redirectTo = "/login", role, permission, ...sessionConfig } = options;
   return /* @__PURE__ */ __name(async function ProtectedPage(props) {
@@ -316,8 +459,157 @@ function withAuth(Page, options = {}) {
   }, "ProtectedPage");
 }
 __name(withAuth, "withAuth");
+
+// src/client/server/defineAuth.ts
+function matchesAny2(pathname, patterns) {
+  return patterns.some((p) => matchPattern2(pathname, p));
+}
+__name(matchesAny2, "matchesAny");
+function matchPattern2(pathname, pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const regex = escaped.replace(/\/:[^/]+\*/g, "(?:/.*)?").replace(/\/\\\*$/g, "(?:/.*)?").replace(/\\\*/g, "(?:/.*)?").replace(/\//g, "\\/");
+  return new RegExp(`^${regex}$`).test(pathname);
+}
+__name(matchPattern2, "matchPattern");
+function cookieRegex2(name) {
+  return new RegExp(`(?:^|;\\s*)${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=[^;]`);
+}
+__name(cookieRegex2, "cookieRegex");
+function findMatchingRoles2(pathname, roleRoutes) {
+  for (const [pattern, roles] of Object.entries(roleRoutes)) {
+    if (matchPattern2(pathname, pattern)) return roles;
+  }
+  return null;
+}
+__name(findMatchingRoles2, "findMatchingRoles");
+function defineAuth(authConfig = {}) {
+  const {
+    apiBaseURL = "/api",
+    authPrefix = "/auth",
+    loginRoute = "/login",
+    publicRoutes = [],
+    protectedRoutes = [],
+    roleRoutes = {},
+    cookieName = "refreshToken",
+    sessionCookieName = "najm.session",
+    sessionSecret,
+    matcher = ["/((?!_next/static|_next/image|favicon.ico|api).*)"]
+  } = authConfig;
+  const sessionConfig = {
+    baseURL: void 0,
+    // resolved at call time from env/defaults
+    authPrefix,
+    cookieName,
+    sessionCookieName,
+    sessionSecret
+  };
+  const getSession2 = /* @__PURE__ */ __name(async (opts) => {
+    const { getSession: resolveSession } = await Promise.resolve().then(() => (init_getSession(), getSession_exports));
+    return resolveSession({ ...sessionConfig, ...opts });
+  }, "getSession");
+  const requireSession = /* @__PURE__ */ __name(async () => {
+    const sessionModule = await Promise.resolve().then(() => (init_getSession(), getSession_exports));
+    const {
+      getSession: resolveSession,
+      NoSessionError: NoSessionError2,
+      AuthTransportError: AuthTransportError2
+    } = sessionModule;
+    try {
+      const session = await resolveSession({ ...sessionConfig, mode: "strict" });
+      return session;
+    } catch (err) {
+      if (err instanceof NoSessionError2) {
+        const { redirect } = await import("next/navigation");
+        redirect(loginRoute);
+      }
+      if (err instanceof AuthTransportError2 && (err.status === 401 || err.status === 403)) {
+        const { redirect } = await import("next/navigation");
+        redirect(loginRoute);
+      }
+      throw err;
+    }
+  }, "requireSession");
+  const middleware = /* @__PURE__ */ __name(async (request) => {
+    const { NextResponse } = await import("next/server");
+    const url = new URL(request.url);
+    const pathname = url.pathname;
+    if (matchesAny2(pathname, publicRoutes)) {
+      return NextResponse.next();
+    }
+    const isProtected = protectedRoutes.length === 0 || matchesAny2(pathname, protectedRoutes);
+    if (!isProtected) return NextResponse.next();
+    const cookie = request.headers.get("cookie") ?? "";
+    const hasToken = cookieRegex2(cookieName).test(cookie);
+    if (!hasToken) {
+      const loginUrl = new URL(loginRoute, request.url);
+      loginUrl.searchParams.set("from", pathname);
+      return NextResponse.redirect(loginUrl);
+    }
+    const requiredRoles = findMatchingRoles2(pathname, roleRoutes);
+    if (requiredRoles) {
+      const verifyURL = `${url.origin}${apiBaseURL}${authPrefix}/me`;
+      try {
+        const res = await fetch(verifyURL, {
+          headers: { Cookie: cookie, Accept: "application/json" }
+        });
+        if (!res.ok) {
+          const loginUrl = new URL(loginRoute, request.url);
+          loginUrl.searchParams.set("from", pathname);
+          return NextResponse.redirect(loginUrl);
+        }
+        const body = await res.json();
+        const userRole = body?.data?.role;
+        if (!userRole || !requiredRoles.includes(userRole)) {
+          return new NextResponse(null, { status: 403 });
+        }
+      } catch {
+        const loginUrl = new URL(loginRoute, request.url);
+        loginUrl.searchParams.set("from", pathname);
+        return NextResponse.redirect(loginUrl);
+      }
+    }
+    return NextResponse.next();
+  }, "middleware");
+  const protect = /* @__PURE__ */ __name((Page, options) => {
+    return /* @__PURE__ */ __name(async function ProtectedPage(props) {
+      const session = await getSession2();
+      if (!session) {
+        const { redirect } = await import("next/navigation");
+        redirect(loginRoute);
+      }
+      if (options?.role) {
+        const userRoles = session.roles ?? (session.user.role ? [session.user.role] : []);
+        if (!userRoles.includes(options.role)) {
+          const { redirect } = await import("next/navigation");
+          redirect(loginRoute);
+        }
+      }
+      if (options?.permission) {
+        const { matchPermission: matchPermission2 } = await Promise.resolve().then(() => (init_permissions(), permissions_exports));
+        const perms = session.permissions ?? session.user.permissions ?? [];
+        if (!matchPermission2(perms, options.permission)) {
+          const { redirect } = await import("next/navigation");
+          redirect(loginRoute);
+        }
+      }
+      return Page({ session, ...props });
+    }, "ProtectedPage");
+  }, "protect");
+  return {
+    getSession: getSession2,
+    requireSession,
+    middleware,
+    config: { matcher },
+    protect
+  };
+}
+__name(defineAuth, "defineAuth");
 export {
+  AuthConfigError,
+  AuthTransportError,
+  NoSessionError,
   createServerClient,
+  defineAuth,
   getServerSession,
   getSession,
   withAuth,

package/dist/index.d.ts

@@ -31,6 +31,19 @@ interface LockoutConfig {
     /** Lockout duration (e.g. '15m') */
     duration: string;
 }
+/**
+ * Session cookie cache configuration.
+ * A short-lived, HMAC-signed cookie that caches user/roles/permissions for
+ * instant SSR reads (skips the /auth/me round-trip).
+ */
+interface SessionCookieConfig {
+    /** Cookie name (default: 'najm.session') */
+    name: string;
+    /** Max age in seconds (default: 300 = 5 min) */
+    maxAge: number;
+    /** Secret used to HMAC-sign the cookie. Defaults to jwt.accessSecret. */
+    secret?: string;
+}
 /**
  * Complete auth plugin configuration (internal)
  */
@@ -51,6 +64,8 @@ interface AuthConfig {
     registrationMode: 'active' | 'pending';
     /** Per-account lockout settings */
     lockout: LockoutConfig;
+    /** Session cookie cache settings */
+    session: SessionCookieConfig;
 }
 /**
  * Auth plugin configuration options
@@ -88,6 +103,8 @@ type AuthPluginConfig = {
     registrationMode?: 'active' | 'pending';
     /** Per-account lockout settings */
     lockout?: Partial<LockoutConfig>;
+    /** Session cookie cache settings (optional — sensible defaults applied) */
+    session?: Partial<SessionCookieConfig>;
     /** Optional config forwarded to validation() dependency */
     validation?: ValidationPluginConfig;
     /** Optional config forwarded to rateLimit() dependency */
@@ -332,15 +349,45 @@ declare class EncryptionService {
     comparePassword(password: string, hashedPassword: string): Promise<boolean>;
 }
 
+interface SessionCookieData {
+    user: {
+        id: string;
+        email: string;
+        name?: string | null;
+        role?: string;
+    };
+    roles: string[];
+    permissions: string[];
+    /** Epoch ms when the cookie was written */
+    iat: number;
+}
 declare class CookieManager {
     private config;
     private cookieService;
     private get cookieName();
+    private get sessionCookieName();
+    private get sessionMaxAge();
+    private get sessionSecret();
     setRefreshToken(refreshToken: string): void;
     clearRefreshToken(): void;
     getRefreshToken(): string | undefined;
     hasRefreshToken(): boolean;
     getCookieName(): string;
+    /**
+     * Write a signed session cookie containing user data, roles, and permissions.
+     * The cookie is HMAC-signed with the access secret so it is tamper-proof
+     * but readable without a database query. Short TTL (5 min) ensures freshness.
+     */
+    setSessionCookie(data: Omit<SessionCookieData, 'iat'>): void;
+    /**
+     * Read and verify the session cookie. Returns null if missing, expired,
+     * or signature verification fails.
+     */
+    getSessionCookie(): SessionCookieData | null;
+    /**
+     * Clear the session cookie (on logout, password change, etc.)
+     */
+    clearSessionCookie(): void;
 }
 
 interface UserWithPermissions extends Omit<User, 'password'> {
@@ -683,8 +730,10 @@ declare class TokenService {
     validateRefreshSession(refreshToken: string): Promise<string>;
     /**
      * Read the refresh cookie and return the userId it belongs to.
-     * Validates against DB to ensure the session is still active.
-     * Throws if the cookie is missing, invalid, or revoked.
+     * Lightweight check: verifies JWT signature and ensures the user
+     * has an active session in the DB. Does NOT compare token hashes,
+     * so it is safe to call concurrently with token rotation.
+     * Throws if the cookie is missing, invalid, or the session was revoked.
      */
     resolveUserFromCookie(): Promise<string>;
     getUser(auth: string): Promise<any>;
@@ -845,6 +894,11 @@ declare class AuthService {
     constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService);
     private isLockoutActive;
     private nextLockoutUntil;
+    /**
+     * Decode JWT payload without verification (token was just generated by us).
+     * Used to extract accurate roles/permissions for the session cookie cache.
+     */
+    private decodeAccessToken;
     registerUser(body: CreateUserDto): Promise<SanitizedUser>;
     loginUser(body: LoginDto): Promise<TokenPair & {
         user: SanitizedUser;
@@ -863,6 +917,12 @@ declare class AuthService {
     /**
      * Get current user — prefer access token (no cookie rotation risk),
      * fall back to cookie when no Authorization header is present.
+     *
+     * Refreshes the session cookie cache only when authoritative roles/permissions
+     * are available (from the access token JWT). When called via the refresh-cookie
+     * fallback, we cannot reliably populate permissions without a DB round-trip,
+     * so we leave the existing cache alone — it will be refreshed by the next
+     * login/refresh cycle.
      */
     getMe(authorization?: string): Promise<SanitizedUser & {
         language: string;
@@ -1834,4 +1894,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type DefineRolesOptions, type EmailParam, EncryptionService, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, seedAuthData, setConfiguredCookieName, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, verifyTokenDto, where };
+export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type DefineRolesOptions, type EmailParam, EncryptionService, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, seedAuthData, setConfiguredCookieName, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, verifyTokenDto, where };

package/dist/index.js

@@ -1183,6 +1183,18 @@ var CookieManager = class CookieManager2 {
   get cookieName() {
     return this.config.refreshCookieName || "refreshToken";
   }
+  get sessionCookieName() {
+    return this.config.session.name;
+  }
+  get sessionMaxAge() {
+    return this.config.session.maxAge;
+  }
+  get sessionSecret() {
+    return this.config.session.secret || this.config.jwt.accessSecret;
+  }
+  // =========================================================================
+  // Refresh Token Cookie
+  // =========================================================================
   setRefreshToken(refreshToken) {
     const maxAge = timestring(this.config.jwt.refreshExpiresIn, "s");
     this.cookieService.set(this.cookieName, refreshToken, { maxAge });
@@ -1199,6 +1211,47 @@ var CookieManager = class CookieManager2 {
   getCookieName() {
     return this.cookieName;
   }
+  // =========================================================================
+  // Session Cookie Cache (HMAC-signed, short-lived)
+  // =========================================================================
+  /**
+   * Write a signed session cookie containing user data, roles, and permissions.
+   * The cookie is HMAC-signed with the access secret so it is tamper-proof
+   * but readable without a database query. Short TTL (5 min) ensures freshness.
+   */
+  setSessionCookie(data) {
+    const payload = { ...data, iat: Date.now() };
+    this.cookieService.setSigned(this.sessionCookieName, JSON.stringify(payload), this.sessionSecret, {
+      maxAge: this.sessionMaxAge,
+      httpOnly: true,
+      sameSite: "Lax",
+      path: "/"
+    });
+  }
+  /**
+   * Read and verify the session cookie. Returns null if missing, expired,
+   * or signature verification fails.
+   */
+  getSessionCookie() {
+    const raw = this.cookieService.getSigned(this.sessionCookieName, this.sessionSecret);
+    if (!raw)
+      return null;
+    try {
+      const data = JSON.parse(raw);
+      const age = Date.now() - data.iat;
+      if (age > this.sessionMaxAge * 1e3)
+        return null;
+      return data;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Clear the session cookie (on logout, password change, etc.)
+   */
+  clearSessionCookie() {
+    this.cookieService.delete(this.sessionCookieName);
+  }
 };
 __decorate8([
   Inject4(AUTH_CONFIG),
@@ -1408,24 +1461,28 @@ var TokenService = class TokenService2 {
     }
     const isValid = this.hashToken(refreshToken) === stored.token;
     if (!isValid) {
-      if (stored.tokenFamily) {
-        await this.tokenRepository.revokeByFamily(stored.tokenFamily);
-      }
       Err5(this.t("errors.refreshTokenInvalid"));
     }
     return userId;
   }
   /**
    * Read the refresh cookie and return the userId it belongs to.
-   * Validates against DB to ensure the session is still active.
-   * Throws if the cookie is missing, invalid, or revoked.
+   * Lightweight check: verifies JWT signature and ensures the user
+   * has an active session in the DB. Does NOT compare token hashes,
+   * so it is safe to call concurrently with token rotation.
+   * Throws if the cookie is missing, invalid, or the session was revoked.
    */
   async resolveUserFromCookie() {
     const refreshToken = this.cookieManager.getRefreshToken();
     if (!refreshToken) {
       Err5(this.t("errors.refreshTokenMissing"));
     }
-    return this.validateRefreshSession(refreshToken);
+    const userId = this.verifyRefreshToken(refreshToken);
+    const stored = await this.tokenRepository.getRefreshTokenWithFamily(userId);
+    if (!stored) {
+      Err5(this.t("errors.refreshTokenInvalid"));
+    }
+    return userId;
   }
   // ============ USER RETRIEVAL (MAIN METHOD) ============
   async getUser(auth2) {
@@ -1552,9 +1609,6 @@ var TokenService = class TokenService2 {
     }
     const isValid = this.hashToken(refreshToken) === stored.token;
     if (!isValid) {
-      if (stored.tokenFamily) {
-        await this.tokenRepository.revokeByFamily(stored.tokenFamily);
-      }
       Err5(this.t("errors.refreshTokenInvalid"));
     }
     return this.generateTokens(userId, stored.tokenFamily ?? void 0);
@@ -1646,6 +1700,7 @@ TokenService = __decorate10([
 
 // src/auth/AuthService.ts
 import timestring3 from "timestring";
+import jwt2 from "jsonwebtoken";
 var __decorate11 = 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);
@@ -1696,6 +1751,21 @@ var AuthService = class AuthService2 {
     const durationMs = timestring3(this.config.lockout.duration, "ms");
     return new Date(Date.now() + durationMs).toISOString();
   }
+  /**
+   * Decode JWT payload without verification (token was just generated by us).
+   * Used to extract accurate roles/permissions for the session cookie cache.
+   */
+  decodeAccessToken(accessToken) {
+    try {
+      const decoded = jwt2.decode(accessToken);
+      return {
+        roles: decoded?.roles ?? [],
+        permissions: decoded?.permissions ?? []
+      };
+    } catch {
+      return { roles: [], permissions: [] };
+    }
+  }
   async registerUser(body) {
     return await this.userService.create(body);
   }
@@ -1732,17 +1802,33 @@ var AuthService = class AuthService2 {
     this.cookieManager.setRefreshToken(data.refreshToken);
     await this.userService.updateLastLogin(user.id);
     const { password: _, failedLoginAttempts: __, lockoutUntil: ___, ...sanitized } = user;
+    const { roles, permissions } = this.decodeAccessToken(data.accessToken);
+    this.cookieManager.setSessionCookie({
+      user: { id: sanitized.id, email: sanitized.email, name: sanitized.name, role: sanitized.role },
+      roles,
+      permissions
+    });
     return { ...data, user: sanitized };
   }
   async refreshTokens() {
     const data = await this.tokenService.refreshTokens();
     this.cookieManager.setRefreshToken(data.refreshToken);
+    const user = await this.tokenService.getUser(`Bearer ${data.accessToken}`);
+    if (user) {
+      const { roles, permissions } = this.decodeAccessToken(data.accessToken);
+      this.cookieManager.setSessionCookie({
+        user: { id: user.id, email: user.email, name: user.name, role: user.role },
+        roles,
+        permissions
+      });
+    }
     return data;
   }
   async logoutUser(userId, authorization) {
     await this.userValidator.checkUserExists(userId);
     await this.tokenService.logout(userId, authorization);
     this.cookieManager.clearRefreshToken();
+    this.cookieManager.clearSessionCookie();
     return { data: null, message: this.t("auth.success.logout") };
   }
   async getUserProfile(userData) {
@@ -1761,16 +1847,37 @@ var AuthService = class AuthService2 {
   /**
    * Get current user — prefer access token (no cookie rotation risk),
    * fall back to cookie when no Authorization header is present.
+   *
+   * Refreshes the session cookie cache only when authoritative roles/permissions
+   * are available (from the access token JWT). When called via the refresh-cookie
+   * fallback, we cannot reliably populate permissions without a DB round-trip,
+   * so we leave the existing cache alone — it will be refreshed by the next
+   * login/refresh cycle.
    */
   async getMe(authorization) {
+    let result;
+    let cachePayload = null;
     if (authorization) {
       const user = await this.tokenService.getUser(authorization);
       if (user) {
         const lang = this.i18nService.getCurrentLanguage();
-        return { ...user, language: lang };
+        result = { ...user, language: lang };
+        const token = authorization.replace(/^Bearer\s+/i, "");
+        cachePayload = this.decodeAccessToken(token);
+      } else {
+        result = await this.getUserFromCookie();
       }
+    } else {
+      result = await this.getUserFromCookie();
     }
-    return this.getUserFromCookie();
+    if (cachePayload) {
+      this.cookieManager.setSessionCookie({
+        user: { id: result.id, email: result.email, name: result.name, role: result.role },
+        roles: cachePayload.roles,
+        permissions: cachePayload.permissions
+      });
+    }
+    return result;
   }
   async forgotPassword(email2) {
     const user = await this.userService.findByEmail(email2);
@@ -1802,6 +1909,7 @@ var AuthService = class AuthService2 {
     await this.tokenService.invalidateUserAccessTokens(userId);
     await this.tokenService.revokeToken(userId);
     this.cookieManager.clearRefreshToken();
+    this.cookieManager.clearSessionCookie();
     return { message: this.t("success.passwordChanged") };
   }
   async resetPassword(token, newPassword) {
@@ -1811,6 +1919,7 @@ var AuthService = class AuthService2 {
     await this.tokenService.invalidateUserAccessTokens(userId);
     await this.tokenService.revokeToken(userId);
     this.cookieManager.clearRefreshToken();
+    this.cookieManager.clearSessionCookie();
     return { message: this.t("success.passwordReset") };
   }
 };
@@ -4037,6 +4146,12 @@ var mergeConfig = /* @__PURE__ */ __name((config) => {
     lockout: {
       maxAttempts: config?.lockout?.maxAttempts ?? 5,
       duration: config?.lockout?.duration ?? "15m"
+    },
+    session: {
+      name: config?.session?.name ?? "najm.session",
+      maxAge: config?.session?.maxAge ?? 300,
+      secret: config?.session?.secret
+      // fallback to jwt.accessSecret at use site
     }
   };
   if (!finalConfig.jwt.accessSecret) {

package/package.json

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