najm-auth 2.0.6 → 2.0.9

package/README.md

@@ -684,6 +684,10 @@ throw new HttpError(403, 'Insufficient permissions for this action');
 - Server-side recovery sends only the configured refresh cookie and accepts
   relative or exact same-origin endpoints. URL credentials and any
   scheme/hostname/port change are rejected before the network request.
+- Self-hosted apps may explicitly use a loopback-only `internalRecoveryURL`
+  when their public reverse-proxy origin is not reachable from the app process.
+- `onRecoveryFailure` exposes structured, secret-free recovery diagnostics
+  without logging anything by default.
 - `verifyAlways` forces that authoritative check on every protected request;
   the default bounds cached role/status staleness to `session.maxAge`.
 

package/dist/client/edge.d.ts

@@ -1,5 +1,22 @@
 import * as next_server from 'next/server';
 
+type SessionRecoveryFailureReason = 'invalid-cookie-name' | 'invalid-refresh-cookie' | 'invalid-endpoint' | 'fetch-error' | 'http-status' | 'missing-set-cookie' | 'session-cookie-parse' | 'session-cookie-hmac' | 'session-cookie-payload';
+interface SessionRecoveryErrorDetails {
+    name: string;
+    message: string;
+    code?: string;
+    cause?: {
+        name: string;
+        message: string;
+        code?: string;
+    };
+}
+interface SessionRecoveryFailure {
+    reason: SessionRecoveryFailureReason;
+    httpStatus?: number;
+    error?: SessionRecoveryErrorDetails;
+}
+
 interface AuthMiddlewareConfig {
     /** Routes that require authentication (glob patterns) */
     protectedRoutes?: string[];
@@ -34,6 +51,14 @@ interface AuthMiddlewareConfig {
      * Set to false to disable automatic recovery.
      */
     recoveryURL?: string | false;
+    /**
+     * Optional loopback-only endpoint for self-hosted apps whose public origin
+     * cannot be reached from the app container. Takes precedence over
+     * `recoveryURL` for the server-side recovery request.
+     */
+    internalRecoveryURL?: string;
+    /** Secret-free diagnostic hook for failed authoritative recovery attempts. */
+    onRecoveryFailure?: (failure: SessionRecoveryFailure) => void;
 }
 /**
  * Create a Next.js middleware function that protects routes based on auth state.
@@ -57,4 +82,4 @@ interface AuthMiddlewareConfig {
  */
 declare function withAuthMiddleware(config: AuthMiddlewareConfig): (request: Request) => Promise<next_server.NextResponse<unknown>>;
 
-export { type AuthMiddlewareConfig, withAuthMiddleware };
+export { type AuthMiddlewareConfig, type SessionRecoveryErrorDetails, type SessionRecoveryFailure, type SessionRecoveryFailureReason, withAuthMiddleware };

package/dist/client/edge.js

@@ -36,22 +36,36 @@ function parseSessionCookiePayload(payload, maxAgeSeconds = DEFAULT_SESSION_MAX_
 }
 __name(parseSessionCookiePayload, "parseSessionCookiePayload");
 async function verifySessionCookie(rawCookieValue, options) {
-  if (!rawCookieValue || !options.secret || !globalThis.crypto?.subtle) return null;
+  const result = await verifySessionCookieDetailed(rawCookieValue, options);
+  return result.status === "valid" ? result.claims : null;
+}
+__name(verifySessionCookie, "verifySessionCookie");
+async function verifySessionCookieDetailed(rawCookieValue, options) {
+  if (!rawCookieValue || !options.secret || !globalThis.crypto?.subtle) {
+    return { status: "invalid", reason: "format" };
+  }
+  let sawSignedFormat = false;
+  let sawValidHmac = false;
   for (const signedValue of cookieValueCandidates(rawCookieValue)) {
     const lastDot = signedValue.lastIndexOf(".");
     if (lastDot <= 0 || lastDot === signedValue.length - 1) continue;
+    sawSignedFormat = true;
     const payload = signedValue.slice(0, lastDot);
     const signature = signedValue.slice(lastDot + 1);
     if (!await verifyHmac(payload, signature, options.secret)) continue;
-    return parseSessionCookiePayload(
+    sawValidHmac = true;
+    const claims = parseSessionCookiePayload(
       payload,
       options.maxAgeSeconds ?? DEFAULT_SESSION_MAX_AGE_SECONDS,
       options.now
     );
+    if (claims) return { status: "valid", claims };
   }
-  return null;
+  if (sawValidHmac) return { status: "invalid", reason: "payload" };
+  if (sawSignedFormat) return { status: "invalid", reason: "hmac" };
+  return { status: "invalid", reason: "format" };
 }
-__name(verifySessionCookie, "verifySessionCookie");
+__name(verifySessionCookieDetailed, "verifySessionCookieDetailed");
 function readCookieValue(cookieHeader, name) {
   for (const part of cookieHeader.split(";")) {
     const separator = part.indexOf("=");
@@ -132,18 +146,28 @@ function isStringArray(value) {
 __name(isStringArray, "isStringArray");
 
 // src/client/sessionRecovery.ts
+function resolveInternalRecoveryURL(explicit) {
+  if (explicit !== void 0) return explicit || void 0;
+  if (typeof process === "undefined") return void 0;
+  return process.env.NAJM_AUTH_INTERNAL_URL || void 0;
+}
+__name(resolveInternalRecoveryURL, "resolveInternalRecoveryURL");
 async function requestSessionRecovery(options) {
   if (!isCookieName(options.refreshCookieName) || !isCookieName(options.sessionCookieName)) {
+    reportFailure(options, { reason: "invalid-cookie-name" });
     return { status: "unavailable" };
   }
   if (!isCookieValue(options.refreshCookieValue)) {
+    reportFailure(options, { reason: "invalid-refresh-cookie" });
     return { status: "invalid" };
   }
   const endpoint = sameOriginRecoveryEndpoint(
     options.endpoint,
-    options.requestOrigin
+    options.requestOrigin,
+    options.allowLoopbackEndpoint
   );
   if (!endpoint) {
+    reportFailure(options, { reason: "invalid-endpoint" });
     return { status: "unavailable" };
   }
   let response;
@@ -158,30 +182,51 @@ async function requestSessionRecovery(options) {
       cache: "no-store",
       redirect: "manual"
     });
-  } catch {
+  } catch (error) {
+    reportFailure(options, {
+      reason: "fetch-error",
+      error: safeErrorDetails(error)
+    });
     return { status: "unavailable" };
   }
   if (!response.ok) {
     const status = response.status;
+    reportFailure(options, { reason: "http-status", httpStatus: 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 };
+  if (!setCookie) {
+    reportFailure(options, {
+      reason: "missing-set-cookie",
+      httpStatus: response.status
+    });
+    return { status: "unavailable", httpStatus: response.status };
+  }
   const sessionCookieValue = readSetCookieValue(setCookie, options.sessionCookieName);
   if (!sessionCookieValue) {
+    reportFailure(options, {
+      reason: "session-cookie-parse",
+      httpStatus: response.status
+    });
     return { status: "unavailable", httpStatus: response.status };
   }
-  const claims = await verifySessionCookie(sessionCookieValue, {
+  const verification = await verifySessionCookieDetailed(sessionCookieValue, {
     secret: options.sessionSecret,
     maxAgeSeconds: options.sessionMaxAge
   });
-  if (!claims) return { status: "unavailable", httpStatus: response.status };
+  if (verification.status === "invalid") {
+    reportFailure(options, {
+      reason: verification.reason === "hmac" ? "session-cookie-hmac" : verification.reason === "payload" ? "session-cookie-payload" : "session-cookie-parse",
+      httpStatus: response.status
+    });
+    return { status: "unavailable", httpStatus: response.status };
+  }
   return {
     status: "recovered",
-    claims,
+    claims: verification.claims,
     setCookie,
     sessionCookieValue
   };
@@ -215,7 +260,7 @@ function isCookieValue(value) {
   return value.length > 0 && /^[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]+$/.test(value);
 }
 __name(isCookieValue, "isCookieValue");
-function sameOriginRecoveryEndpoint(endpoint, requestOrigin) {
+function sameOriginRecoveryEndpoint(endpoint, requestOrigin, allowLoopback = false) {
   try {
     const trusted = new URL(requestOrigin);
     if (trusted.protocol !== "https:" && trusted.protocol !== "http:" || trusted.username || trusted.password) {
@@ -223,13 +268,60 @@ function sameOriginRecoveryEndpoint(endpoint, requestOrigin) {
     }
     const resolved = new URL(endpoint, trusted.origin);
     if (resolved.username || resolved.password) return void 0;
-    if (resolved.origin !== trusted.origin) return void 0;
+    if (resolved.origin !== trusted.origin && (!allowLoopback || !isLoopbackURL(resolved))) {
+      return void 0;
+    }
     return resolved.toString();
   } catch {
     return void 0;
   }
 }
 __name(sameOriginRecoveryEndpoint, "sameOriginRecoveryEndpoint");
+function isLoopbackURL(url) {
+  if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+}
+__name(isLoopbackURL, "isLoopbackURL");
+function reportFailure(options, failure) {
+  try {
+    options.onFailure?.(failure);
+  } catch {
+  }
+}
+__name(reportFailure, "reportFailure");
+function safeErrorDetails(value) {
+  const error = isRecord2(value) ? value : {};
+  const details = {
+    name: safeText(error.name, "Error"),
+    message: safeText(error.message, "Session recovery fetch failed")
+  };
+  const code = safeOptionalText(error.code);
+  if (code) details.code = code;
+  if (isRecord2(error.cause)) {
+    const causeCode = safeOptionalText(error.cause.code);
+    details.cause = {
+      name: safeText(error.cause.name, "Error"),
+      message: safeText(error.cause.message, "Session recovery fetch failed"),
+      ...causeCode ? { code: causeCode } : {}
+    };
+  }
+  return details;
+}
+__name(safeErrorDetails, "safeErrorDetails");
+function safeText(value, fallback) {
+  if (typeof value !== "string" || !value) return fallback;
+  return value.replace(/[\u0000-\u001F\u007F]/g, " ").slice(0, 300);
+}
+__name(safeText, "safeText");
+function safeOptionalText(value) {
+  if (typeof value !== "string" && typeof value !== "number") return void 0;
+  return safeText(String(value), "");
+}
+__name(safeOptionalText, "safeOptionalText");
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+__name(isRecord2, "isRecord");
 
 // src/client/server/withAuthMiddleware.ts
 function withAuthMiddleware(config) {
@@ -245,8 +337,11 @@ function withAuthMiddleware(config) {
     sessionSecret,
     sessionMaxAge,
     verifyAlways = false,
-    recoveryURL
+    recoveryURL,
+    internalRecoveryURL,
+    onRecoveryFailure
   } = config;
+  const resolvedInternalRecoveryURL = resolveInternalRecoveryURL(internalRecoveryURL);
   return /* @__PURE__ */ __name(async function middleware(request) {
     const { NextResponse } = await import("next/server");
     const redirectToLogin = /* @__PURE__ */ __name((returnPath2, clearCookies) => {
@@ -282,18 +377,20 @@ function withAuthMiddleware(config) {
     let recovery = null;
     if (!session || verifyAlways) {
       const refreshCookie = readCookieValue(cookie, cookieName);
-      if (!refreshCookie || recoveryURL === false) {
+      if (!refreshCookie || recoveryURL === false && !resolvedInternalRecoveryURL) {
         return redirectToLogin(returnPath, ["refresh", "session"]);
       }
-      const endpoint = recoveryURL ? new URL(recoveryURL, request.url).toString() : authEndpoint(apiBaseURL, authPrefix, "/session/recover", request.url);
+      const endpoint = resolvedInternalRecoveryURL ?? (recoveryURL ? new URL(recoveryURL, request.url).toString() : authEndpoint(apiBaseURL, authPrefix, "/session/recover", request.url));
       recovery = await requestSessionRecovery({
         endpoint,
         requestOrigin: url.origin,
+        allowLoopbackEndpoint: resolvedInternalRecoveryURL !== void 0,
         refreshCookieName: cookieName,
         refreshCookieValue: refreshCookie,
         sessionCookieName,
         sessionSecret: secret,
-        sessionMaxAge
+        sessionMaxAge,
+        onFailure: onRecoveryFailure
       });
       if (recovery.status !== "recovered") {
         return redirectToLogin(

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

@@ -1,5 +1,6 @@
 import { f as AuthUser, F as FetchClient, N as NajmAuthClient, h as RetryConfig } from '../../NajmAuthClient-0yzFb9CR.js';
-export { withAuthMiddleware } from '../edge.js';
+import { SessionRecoveryFailure } from '../edge.js';
+export { SessionRecoveryErrorDetails, SessionRecoveryFailureReason, withAuthMiddleware } from '../edge.js';
 import 'next/server';
 
 interface GetServerSessionOptions {
@@ -96,12 +97,16 @@ interface GetSessionConfig {
      * `${baseURL}${authPrefix}/session/recover`. Set to false to disable fallback.
      */
     recoveryURL?: string | false;
+    /** Loopback-only recovery endpoint for self-hosted reverse-proxy setups. */
+    internalRecoveryURL?: string;
     /**
      * Error handling mode:
      * - 'nullable' (default): returns null on any failure
      * - 'strict': throws typed errors for debugging
      */
     mode?: 'nullable' | 'strict';
+    /** Secret-free diagnostic hook for failed recovery attempts. */
+    onRecoveryFailure?: (failure: SessionRecoveryFailure) => void;
 }
 declare class NoSessionError extends Error {
     readonly code = "NO_SESSION";
@@ -181,6 +186,8 @@ interface DefineAuthConfig {
      * `${apiBaseURL}${authPrefix}/session/recover`; false disables recovery.
      */
     recoveryURL?: string | false;
+    /** Loopback-only recovery endpoint for self-hosted reverse-proxy setups. */
+    internalRecoveryURL?: string;
     /** Next.js middleware matcher (default: exclude _next, favicon, api) */
     matcher?: string[];
     /**
@@ -188,6 +195,8 @@ interface DefineAuthConfig {
      * Recovery reissues the signed cookie without rotating refresh tokens.
      */
     verifyAlways?: boolean;
+    /** Secret-free diagnostic hook for failed server or proxy recovery. */
+    onRecoveryFailure?: (failure: SessionRecoveryFailure) => void;
 }
 interface AuthKit {
     /**
@@ -223,4 +232,4 @@ interface AuthKit {
 }
 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 };
+export { AuthConfigError, type AuthKit, AuthTransportError, type DefineAuthConfig, type GetSessionConfig, NoSessionError, type ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getServerSession, getSession, withAuth };

package/dist/client/server/index.js

@@ -38,20 +38,33 @@ function parseSessionCookiePayload(payload, maxAgeSeconds = DEFAULT_SESSION_MAX_
   }
 }
 async function verifySessionCookie(rawCookieValue, options) {
-  if (!rawCookieValue || !options.secret || !globalThis.crypto?.subtle) return null;
+  const result = await verifySessionCookieDetailed(rawCookieValue, options);
+  return result.status === "valid" ? result.claims : null;
+}
+async function verifySessionCookieDetailed(rawCookieValue, options) {
+  if (!rawCookieValue || !options.secret || !globalThis.crypto?.subtle) {
+    return { status: "invalid", reason: "format" };
+  }
+  let sawSignedFormat = false;
+  let sawValidHmac = false;
   for (const signedValue of cookieValueCandidates(rawCookieValue)) {
     const lastDot = signedValue.lastIndexOf(".");
     if (lastDot <= 0 || lastDot === signedValue.length - 1) continue;
+    sawSignedFormat = true;
     const payload = signedValue.slice(0, lastDot);
     const signature = signedValue.slice(lastDot + 1);
     if (!await verifyHmac(payload, signature, options.secret)) continue;
-    return parseSessionCookiePayload(
+    sawValidHmac = true;
+    const claims = parseSessionCookiePayload(
       payload,
       options.maxAgeSeconds ?? DEFAULT_SESSION_MAX_AGE_SECONDS,
       options.now
     );
+    if (claims) return { status: "valid", claims };
   }
-  return null;
+  if (sawValidHmac) return { status: "invalid", reason: "payload" };
+  if (sawSignedFormat) return { status: "invalid", reason: "hmac" };
+  return { status: "invalid", reason: "format" };
 }
 function readCookieValue(cookieHeader, name) {
   for (const part of cookieHeader.split(";")) {
@@ -134,6 +147,7 @@ var init_sessionCookie = __esm({
     __name(resolveSessionSecret, "resolveSessionSecret");
     __name(parseSessionCookiePayload, "parseSessionCookiePayload");
     __name(verifySessionCookie, "verifySessionCookie");
+    __name(verifySessionCookieDetailed, "verifySessionCookieDetailed");
     __name(readCookieValue, "readCookieValue");
     __name(verifyHmac, "verifyHmac");
     __name(cookieValueCandidates, "cookieValueCandidates");
@@ -145,18 +159,27 @@ var init_sessionCookie = __esm({
 });
 
 // src/client/sessionRecovery.ts
+function resolveInternalRecoveryURL(explicit) {
+  if (explicit !== void 0) return explicit || void 0;
+  if (typeof process === "undefined") return void 0;
+  return process.env.NAJM_AUTH_INTERNAL_URL || void 0;
+}
 async function requestSessionRecovery(options) {
   if (!isCookieName(options.refreshCookieName) || !isCookieName(options.sessionCookieName)) {
+    reportFailure(options, { reason: "invalid-cookie-name" });
     return { status: "unavailable" };
   }
   if (!isCookieValue(options.refreshCookieValue)) {
+    reportFailure(options, { reason: "invalid-refresh-cookie" });
     return { status: "invalid" };
   }
   const endpoint = sameOriginRecoveryEndpoint(
     options.endpoint,
-    options.requestOrigin
+    options.requestOrigin,
+    options.allowLoopbackEndpoint
   );
   if (!endpoint) {
+    reportFailure(options, { reason: "invalid-endpoint" });
     return { status: "unavailable" };
   }
   let response;
@@ -171,30 +194,51 @@ async function requestSessionRecovery(options) {
       cache: "no-store",
       redirect: "manual"
     });
-  } catch {
+  } catch (error) {
+    reportFailure(options, {
+      reason: "fetch-error",
+      error: safeErrorDetails(error)
+    });
     return { status: "unavailable" };
   }
   if (!response.ok) {
     const status = response.status;
+    reportFailure(options, { reason: "http-status", httpStatus: 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 };
+  if (!setCookie) {
+    reportFailure(options, {
+      reason: "missing-set-cookie",
+      httpStatus: response.status
+    });
+    return { status: "unavailable", httpStatus: response.status };
+  }
   const sessionCookieValue = readSetCookieValue(setCookie, options.sessionCookieName);
   if (!sessionCookieValue) {
+    reportFailure(options, {
+      reason: "session-cookie-parse",
+      httpStatus: response.status
+    });
     return { status: "unavailable", httpStatus: response.status };
   }
-  const claims = await verifySessionCookie(sessionCookieValue, {
+  const verification = await verifySessionCookieDetailed(sessionCookieValue, {
     secret: options.sessionSecret,
     maxAgeSeconds: options.sessionMaxAge
   });
-  if (!claims) return { status: "unavailable", httpStatus: response.status };
+  if (verification.status === "invalid") {
+    reportFailure(options, {
+      reason: verification.reason === "hmac" ? "session-cookie-hmac" : verification.reason === "payload" ? "session-cookie-payload" : "session-cookie-parse",
+      httpStatus: response.status
+    });
+    return { status: "unavailable", httpStatus: response.status };
+  }
   return {
     status: "recovered",
-    claims,
+    claims: verification.claims,
     setCookie,
     sessionCookieValue
   };
@@ -222,7 +266,7 @@ function isCookieName(value) {
 function isCookieValue(value) {
   return value.length > 0 && /^[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]+$/.test(value);
 }
-function sameOriginRecoveryEndpoint(endpoint, requestOrigin) {
+function sameOriginRecoveryEndpoint(endpoint, requestOrigin, allowLoopback = false) {
   try {
     const trusted = new URL(requestOrigin);
     if (trusted.protocol !== "https:" && trusted.protocol !== "http:" || trusted.username || trusted.password) {
@@ -230,15 +274,57 @@ function sameOriginRecoveryEndpoint(endpoint, requestOrigin) {
     }
     const resolved = new URL(endpoint, trusted.origin);
     if (resolved.username || resolved.password) return void 0;
-    if (resolved.origin !== trusted.origin) return void 0;
+    if (resolved.origin !== trusted.origin && (!allowLoopback || !isLoopbackURL(resolved))) {
+      return void 0;
+    }
     return resolved.toString();
   } catch {
     return void 0;
   }
 }
+function isLoopbackURL(url) {
+  if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+}
+function reportFailure(options, failure) {
+  try {
+    options.onFailure?.(failure);
+  } catch {
+  }
+}
+function safeErrorDetails(value) {
+  const error = isRecord2(value) ? value : {};
+  const details = {
+    name: safeText(error.name, "Error"),
+    message: safeText(error.message, "Session recovery fetch failed")
+  };
+  const code = safeOptionalText(error.code);
+  if (code) details.code = code;
+  if (isRecord2(error.cause)) {
+    const causeCode = safeOptionalText(error.cause.code);
+    details.cause = {
+      name: safeText(error.cause.name, "Error"),
+      message: safeText(error.cause.message, "Session recovery fetch failed"),
+      ...causeCode ? { code: causeCode } : {}
+    };
+  }
+  return details;
+}
+function safeText(value, fallback) {
+  if (typeof value !== "string" || !value) return fallback;
+  return value.replace(/[\u0000-\u001F\u007F]/g, " ").slice(0, 300);
+}
+function safeOptionalText(value) {
+  if (typeof value !== "string" && typeof value !== "number") return void 0;
+  return safeText(String(value), "");
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
 var init_sessionRecovery = __esm({
   "src/client/sessionRecovery.ts"() {
     init_sessionCookie();
+    __name(resolveInternalRecoveryURL, "resolveInternalRecoveryURL");
     __name(requestSessionRecovery, "requestSessionRecovery");
     __name(authEndpoint, "authEndpoint");
     __name(replaceCookieValue, "replaceCookieValue");
@@ -246,6 +332,12 @@ var init_sessionRecovery = __esm({
     __name(isCookieName, "isCookieName");
     __name(isCookieValue, "isCookieValue");
     __name(sameOriginRecoveryEndpoint, "sameOriginRecoveryEndpoint");
+    __name(isLoopbackURL, "isLoopbackURL");
+    __name(reportFailure, "reportFailure");
+    __name(safeErrorDetails, "safeErrorDetails");
+    __name(safeText, "safeText");
+    __name(safeOptionalText, "safeOptionalText");
+    __name(isRecord2, "isRecord");
   }
 });
 
@@ -286,6 +378,7 @@ async function getSession(config = {}) {
   const baseURL = config.baseURL ?? defaultBaseURL();
   const prefix = config.authPrefix ?? "/auth";
   const strict = config.mode === "strict";
+  const internalRecoveryURL = resolveInternalRecoveryURL(config.internalRecoveryURL);
   let sessionCookieValue;
   let refreshCookieValue;
   let requestOrigin;
@@ -319,7 +412,7 @@ async function getSession(config = {}) {
     if (strict) throw new AuthConfigError("Session cookie secret is not configured");
     return null;
   }
-  if (!refreshCookieValue || config.recoveryURL === false) {
+  if (!refreshCookieValue || config.recoveryURL === false && !internalRecoveryURL) {
     if (strict) throw new NoSessionError("No recoverable refresh session");
     return null;
   }
@@ -327,15 +420,17 @@ async function getSession(config = {}) {
     if (strict) throw new AuthConfigError("Incoming request origin is unavailable");
     return null;
   }
-  const endpoint = config.recoveryURL ? new URL(config.recoveryURL, requestOrigin).toString() : authEndpoint(baseURL, prefix, "/session/recover", requestOrigin);
+  const endpoint = internalRecoveryURL ?? (config.recoveryURL ? new URL(config.recoveryURL, requestOrigin).toString() : authEndpoint(baseURL, prefix, "/session/recover", requestOrigin));
   const recovery = await requestSessionRecovery({
     endpoint,
     requestOrigin,
+    allowLoopbackEndpoint: internalRecoveryURL !== void 0,
     refreshCookieName: cookieName,
     refreshCookieValue,
     sessionCookieName,
     sessionSecret: secret,
-    sessionMaxAge: config.sessionMaxAge
+    sessionMaxAge: config.sessionMaxAge,
+    onFailure: config.onRecoveryFailure
   });
   if (recovery.status === "recovered") {
     return {
@@ -603,8 +698,11 @@ function withAuthMiddleware(config) {
     sessionSecret,
     sessionMaxAge,
     verifyAlways = false,
-    recoveryURL
+    recoveryURL,
+    internalRecoveryURL,
+    onRecoveryFailure
   } = config;
+  const resolvedInternalRecoveryURL = resolveInternalRecoveryURL(internalRecoveryURL);
   return /* @__PURE__ */ __name(async function middleware(request) {
     const { NextResponse } = await import("next/server");
     const redirectToLogin = /* @__PURE__ */ __name((returnPath2, clearCookies) => {
@@ -640,18 +738,20 @@ function withAuthMiddleware(config) {
     let recovery = null;
     if (!session || verifyAlways) {
       const refreshCookie = readCookieValue(cookie, cookieName);
-      if (!refreshCookie || recoveryURL === false) {
+      if (!refreshCookie || recoveryURL === false && !resolvedInternalRecoveryURL) {
         return redirectToLogin(returnPath, ["refresh", "session"]);
       }
-      const endpoint = recoveryURL ? new URL(recoveryURL, request.url).toString() : authEndpoint(apiBaseURL, authPrefix, "/session/recover", request.url);
+      const endpoint = resolvedInternalRecoveryURL ?? (recoveryURL ? new URL(recoveryURL, request.url).toString() : authEndpoint(apiBaseURL, authPrefix, "/session/recover", request.url));
       recovery = await requestSessionRecovery({
         endpoint,
         requestOrigin: url.origin,
+        allowLoopbackEndpoint: resolvedInternalRecoveryURL !== void 0,
         refreshCookieName: cookieName,
         refreshCookieValue: refreshCookie,
         sessionCookieName,
         sessionSecret: secret,
-        sessionMaxAge
+        sessionMaxAge,
+        onFailure: onRecoveryFailure
       });
       if (recovery.status !== "recovered") {
         return redirectToLogin(
@@ -1212,8 +1312,10 @@ function defineAuth(authConfig = {}) {
     sessionSecret,
     sessionMaxAge,
     recoveryURL,
+    internalRecoveryURL,
     matcher = ["/((?!_next/static|_next/image|favicon.ico|api).*)"],
     verifyAlways = false,
+    onRecoveryFailure,
     refreshThreshold,
     tabSync,
     channelName,
@@ -1227,7 +1329,9 @@ function defineAuth(authConfig = {}) {
     sessionCookieName,
     sessionSecret,
     sessionMaxAge,
-    recoveryURL
+    recoveryURL,
+    internalRecoveryURL,
+    onRecoveryFailure
   };
   let _client = null;
   const getClient = /* @__PURE__ */ __name(() => {
@@ -1281,7 +1385,9 @@ function defineAuth(authConfig = {}) {
     sessionSecret,
     sessionMaxAge,
     recoveryURL,
-    verifyAlways
+    internalRecoveryURL,
+    verifyAlways,
+    onRecoveryFailure
   });
   const protect = /* @__PURE__ */ __name((Page, options) => {
     return /* @__PURE__ */ __name(async function ProtectedPage(props) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "2.0.6",
+  "version": "2.0.9",
   "description": "Authentication and authorization library for najm framework",
   "type": "module",
   "files": [
@@ -48,6 +48,7 @@
   "scripts": {
     "build": "tsup",
     "test": "bun test",
+    "test:next16": "bun run build && bun integration/next16-proxy/run.ts",
     "test:watch": "bun test --watch",
     "start": "bun --watch src/main.ts",
     "clean": "rimraf dist tsconfig.tsbuildinfo"
@@ -70,6 +71,7 @@
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.45.2",
     "happy-dom": "^20.11.1",
+    "next": "16.2.11",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },