najm-auth 2.0.3 → 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,16 +11,29 @@ interface AuthMiddlewareConfig {
     roleRoutes?: Record<string, string[]>;
     /** Refresh token cookie name (default: 'refreshToken') */
     cookieName?: string;
-    /** Session cookie name to clear on redirect (default: 'najm.session') */
+    /** 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;
-    /** URL of the verify endpoint (default: derived from request) */
+    /** @deprecated Session cookies are verified locally at the Edge. */
     verifyURL?: string;
+    /** Secret for verifying the session cookie HMAC. Falls back to env vars. */
+    sessionSecret?: string;
+    /** Must match the auth plugin's session.maxAge. Default: 300 seconds. */
+    sessionMaxAge?: number;
     /**
-     * When true, call the verify endpoint on EVERY protected route (not just
-     * roleRoutes). Redirects to loginRoute if the session is invalid. Adds one
-     * fetch per navigation — trade latency for stronger guarantees.
+     * 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.
@@ -28,7 +41,7 @@ interface AuthMiddlewareConfig {
  * @example
  * ```ts
  * // middleware.ts
- * import { withAuthMiddleware } from 'najm-auth/client/server';
+   * import { withAuthMiddleware } from 'najm-auth/client/edge';
  *
  * export default withAuthMiddleware({
  *   protectedRoutes: ['/dashboard/:path*', '/admin/:path*'],

package/dist/client/edge.js

@@ -1,6 +1,229 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
+// src/client/sessionCookie.ts
+var DEFAULT_SESSION_MAX_AGE_SECONDS = 300;
+var MAX_CLOCK_SKEW_MS = 3e4;
+var HMAC_SHA256_BASE64URL_LENGTH = 43;
+var BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function resolveSessionSecret(explicit) {
+  if (explicit !== void 0) return explicit || void 0;
+  if (typeof process === "undefined") return void 0;
+  return process.env.NAJM_SESSION_SECRET || process.env.JWT_ACCESS_SECRET || void 0;
+}
+__name(resolveSessionSecret, "resolveSessionSecret");
+function parseSessionCookiePayload(payload, maxAgeSeconds = DEFAULT_SESSION_MAX_AGE_SECONDS, now = Date.now()) {
+  if (!Number.isFinite(maxAgeSeconds) || maxAgeSeconds <= 0) return null;
+  try {
+    const data = JSON.parse(payload);
+    if (!isRecord(data) || !isValidUser(data.user)) return null;
+    if (!isStringArray(data.roles) || !isStringArray(data.permissions)) return null;
+    if (!Number.isInteger(data.sessionVersion) || data.sessionVersion < 0) return null;
+    if (!Number.isFinite(data.iat) || !Number.isInteger(data.iat) || data.iat <= 0) return null;
+    const issuedAt = data.iat;
+    if (issuedAt > now + MAX_CLOCK_SKEW_MS) return null;
+    if (now - issuedAt >= maxAgeSeconds * 1e3) return null;
+    return {
+      user: data.user,
+      roles: [...data.roles],
+      permissions: [...data.permissions],
+      sessionVersion: data.sessionVersion,
+      iat: issuedAt
+    };
+  } catch {
+    return null;
+  }
+}
+__name(parseSessionCookiePayload, "parseSessionCookiePayload");
+async function verifySessionCookie(rawCookieValue, options) {
+  if (!rawCookieValue || !options.secret || !globalThis.crypto?.subtle) return null;
+  for (const signedValue of cookieValueCandidates(rawCookieValue)) {
+    const lastDot = signedValue.lastIndexOf(".");
+    if (lastDot <= 0 || lastDot === signedValue.length - 1) continue;
+    const payload = signedValue.slice(0, lastDot);
+    const signature = signedValue.slice(lastDot + 1);
+    if (!await verifyHmac(payload, signature, options.secret)) continue;
+    return parseSessionCookiePayload(
+      payload,
+      options.maxAgeSeconds ?? DEFAULT_SESSION_MAX_AGE_SECONDS,
+      options.now
+    );
+  }
+  return null;
+}
+__name(verifySessionCookie, "verifySessionCookie");
+function readCookieValue(cookieHeader, name) {
+  for (const part of cookieHeader.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator === -1) continue;
+    if (part.slice(0, separator).trim() === name) {
+      const value = part.slice(separator + 1).trim();
+      return value || void 0;
+    }
+  }
+  return void 0;
+}
+__name(readCookieValue, "readCookieValue");
+async function verifyHmac(payload, signature, secret) {
+  if (signature.length !== HMAC_SHA256_BASE64URL_LENGTH) return false;
+  const signatureBytes = decodeBase64Url(signature);
+  if (!signatureBytes || signatureBytes.length !== 32) return false;
+  try {
+    const encoder = new TextEncoder();
+    const key = await globalThis.crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"]
+    );
+    return await globalThis.crypto.subtle.verify(
+      "HMAC",
+      key,
+      signatureBytes,
+      encoder.encode(payload)
+    );
+  } catch {
+    return false;
+  }
+}
+__name(verifyHmac, "verifyHmac");
+function cookieValueCandidates(raw) {
+  const candidates = [raw];
+  try {
+    const decoded = decodeURIComponent(raw);
+    if (decoded !== raw) candidates.push(decoded);
+  } catch {
+  }
+  return candidates;
+}
+__name(cookieValueCandidates, "cookieValueCandidates");
+function decodeBase64Url(value) {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) return null;
+  const bytes = [];
+  let accumulator = 0;
+  let bits = 0;
+  for (const char of value) {
+    const digit = BASE64URL_ALPHABET.indexOf(char);
+    if (digit === -1) return null;
+    accumulator = accumulator << 6 | digit;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push(accumulator >> bits & 255);
+      accumulator &= (1 << bits) - 1;
+    }
+  }
+  if (bits > 0 && accumulator !== 0) return null;
+  return new Uint8Array(bytes);
+}
+__name(decodeBase64Url, "decodeBase64Url");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isRecord, "isRecord");
+function isValidUser(value) {
+  return isRecord(value) && typeof value.id === "string" && value.id.length > 0 && typeof value.email === "string" && value.email.length > 0 && (value.role === void 0 || value.role === null || typeof value.role === "string");
+}
+__name(isValidUser, "isValidUser");
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+__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 {
@@ -9,54 +232,86 @@ function withAuthMiddleware(config) {
     loginRoute = "/login",
     roleRoutes = {},
     cookieName = "refreshToken",
+    apiBaseURL = "/api",
+    authPrefix = "/auth",
     sessionCookieName = "najm.session",
-    verifyAlways = false
+    sessionSecret,
+    sessionMaxAge,
+    verifyAlways = false,
+    recoveryURL
   } = config;
   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();
     }
     const isProtected = protectedRoutes.length === 0 || matchesAny(pathname, protectedRoutes);
     if (!isProtected) return NextResponse.next();
     const cookie = request.headers.get("cookie") ?? "";
-    const hasToken = cookieRegex(cookieName).test(cookie);
-    if (!hasToken) {
-      return redirectToLogin(pathname, true);
+    const sessionCookie = readCookieValue(cookie, sessionCookieName);
+    const secret = resolveSessionSecret(sessionSecret);
+    if (!secret) {
+      return redirectToLogin(returnPath, ["session"]);
+    }
+    let session = sessionCookie ? await verifySessionCookie(sessionCookie, {
+      secret,
+      maxAgeSeconds: sessionMaxAge
+    }) : 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);
-    const needsVerify = verifyAlways || !!requiredRoles;
-    if (needsVerify) {
-      const verifyURL = config.verifyURL ?? `${url.origin}/api/auth/me`;
-      try {
-        const res = await fetch(verifyURL, {
-          headers: { "Cookie": cookie, "Accept": "application/json" }
-        });
-        if (!res.ok) {
-          return redirectToLogin(pathname, true);
-        }
-        if (requiredRoles) {
-          const body = await res.json();
-          const userRole = body?.data?.role;
-          if (!userRole || !requiredRoles.includes(userRole)) {
-            return new NextResponse(null, { status: 403 });
-          }
-        }
-      } catch {
-        return redirectToLogin(pathname, true);
+    if (requiredRoles && !session.roles.some((role) => requiredRoles.includes(role))) {
+      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");
@@ -72,10 +327,6 @@ function matchPattern(pathname, pattern) {
   return new RegExp(`^${regex}$`).test(pathname);
 }
 __name(matchPattern, "matchPattern");
-function cookieRegex(name) {
-  return new RegExp(`(?:^|;\\s*)${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=[^;]`);
-}
-__name(cookieRegex, "cookieRegex");
 function findMatchingRoles(pathname, roleRoutes) {
   for (const [pattern, roles] of Object.entries(roleRoutes)) {
     if (matchPattern(pathname, pattern)) return roles;

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

@@ -75,27 +75,27 @@ 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;
+    /**
+     * Maximum accepted session-cookie age in seconds.
+     * 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
@@ -117,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>;
 
@@ -193,12 +174,18 @@ interface DefineAuthConfig {
     sessionCookieName?: string;
     /** Secret for verifying session cookie HMAC. Falls back to env vars. */
     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[];
     /**
-     * When true, call the verify endpoint on every protected route (not just
-     * roleRoutes). Redirects to loginRoute if the session is invalid. One extra
-     * fetch per navigation in exchange for guaranteed fresh auth state.
+     * Force authoritative refresh-session validation on every protected request.
+     * Recovery reissues the signed cookie without rotating refresh tokens.
      */
     verifyAlways?: boolean;
 }
@@ -212,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>;