najm-auth 2.0.5 → 2.0.9

package/README.md

@@ -681,6 +681,13 @@ throw new HttpError(403, 'Insufficient permissions for this action');
   their session version.
 - Expired signed sessions recover through authoritative, non-rotating refresh
   validation; middleware verifies the reissued HMAC before using its claims.
+- 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/{NajmAuthClient-B9dGk9MH.d.ts → NajmAuthClient-0yzFb9CR.d.ts}

@@ -247,4 +247,4 @@ declare class NajmAuthClient {
  */
 declare function createAuthClient(config: AuthClientConfig): NajmAuthClient;
 
-export { AuthError as A, type DecodedToken as D, FetchClient as F, type HydrateSession as H, NajmAuthClient as N, type OAuthProvider as O, type RetryConfig as R, type SyncPayload as S, type TabSyncMessage as T, type AuthClientConfig as a, type AuthEventMap as b, createAuthClient as c, type AuthState as d, type AuthUser as e, type AuthEvent as f, type AuthEventHandler as g, type ServerResponse as h, type TokenPair as i, type RequestOptions as j, type OAuthLoginOptions as k };
+export { type AuthClientConfig as A, type DecodedToken as D, FetchClient as F, type HydrateSession as H, NajmAuthClient as N, type OAuthLoginOptions as O, type RequestOptions as R, type SyncPayload as S, type TabSyncMessage as T, AuthError as a, type AuthEvent as b, type AuthEventHandler as c, type AuthEventMap as d, type AuthState as e, type AuthUser as f, type OAuthProvider as g, type RetryConfig as h, type ServerResponse as i, type TokenPair as j, createAuthClient as k };

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,19 +146,33 @@ 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" };
   }
-  if (!isSafeRecoveryEndpoint(options.endpoint)) {
+  const endpoint = sameOriginRecoveryEndpoint(
+    options.endpoint,
+    options.requestOrigin,
+    options.allowLoopbackEndpoint
+  );
+  if (!endpoint) {
+    reportFailure(options, { reason: "invalid-endpoint" });
     return { status: "unavailable" };
   }
   let response;
   try {
-    response = await fetch(options.endpoint, {
+    response = await fetch(endpoint, {
       method: "POST",
       headers: {
         Accept: "application/json",
@@ -154,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
   };
@@ -208,21 +257,71 @@ function isCookieName(value) {
 }
 __name(isCookieName, "isCookieName");
 function isCookieValue(value) {
-  return value.length > 0 && !/[\r\n;]/.test(value);
+  return value.length > 0 && /^[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]+$/.test(value);
 }
 __name(isCookieValue, "isCookieValue");
-function isSafeRecoveryEndpoint(value) {
+function sameOriginRecoveryEndpoint(endpoint, requestOrigin, allowLoopback = false) {
   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";
+    const trusted = new URL(requestOrigin);
+    if (trusted.protocol !== "https:" && trusted.protocol !== "http:" || trusted.username || trusted.password) {
+      return void 0;
+    }
+    const resolved = new URL(endpoint, trusted.origin);
+    if (resolved.username || resolved.password) return void 0;
+    if (resolved.origin !== trusted.origin && (!allowLoopback || !isLoopbackURL(resolved))) {
+      return void 0;
+    }
+    return resolved.toString();
   } catch {
-    return false;
+    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(isSafeRecoveryEndpoint, "isSafeRecoveryEndpoint");
+__name(isRecord2, "isRecord");
 
 // src/client/server/withAuthMiddleware.ts
 function withAuthMiddleware(config) {
@@ -238,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) => {
@@ -275,17 +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/index.d.ts

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

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

@@ -1,7 +1,7 @@
 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, d as AuthState, e as AuthUser, A as AuthError, k as OAuthLoginOptions, f as AuthEvent, b as AuthEventMap } from '../../NajmAuthClient-B9dGk9MH.js';
+import { N as NajmAuthClient, H as HydrateSession, e as AuthState, f as AuthUser, a as AuthError, O as OAuthLoginOptions, b as AuthEvent, d as AuthEventMap } from '../../NajmAuthClient-0yzFb9CR.js';
 
 interface AuthProviderProps {
     client: NajmAuthClient;

package/dist/client/react/index.js

@@ -7,7 +7,7 @@ import { useEffect, useRef } from "react";
 
 // src/client/react/context.ts
 import { createContext, useContext } from "react";
-var KEY = /* @__PURE__ */ Symbol.for("najm:auth:client:context");
+var KEY = Symbol.for("najm:auth:client:context");
 var contextStore = globalThis;
 function getAuthClientContext() {
   const existing = contextStore[KEY];

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

@@ -1,5 +1,6 @@
-import { e as AuthUser, F as FetchClient, R as RetryConfig, N as NajmAuthClient } from '../../NajmAuthClient-B9dGk9MH.js';
-export { withAuthMiddleware } from '../edge.js';
+import { f as AuthUser, F as FetchClient, N as NajmAuthClient, h as RetryConfig } from '../../NajmAuthClient-0yzFb9CR.js';
+import { SessionRecoveryFailure } from '../edge.js';
+export { SessionRecoveryErrorDetails, SessionRecoveryFailureReason, withAuthMiddleware } from '../edge.js';
 import 'next/server';
 
 interface GetServerSessionOptions {
@@ -72,7 +73,7 @@ interface ServerSession {
 interface GetSessionConfig {
     /**
      * Base URL for auth endpoints.
-     * Defaults to `${NEXT_PUBLIC_API_URL || http://localhost:${PORT||3000}}/api`.
+     * Defaults to `NEXT_PUBLIC_API_URL` or the same-origin `/api` path.
      */
     baseURL?: string;
     /** Auth route prefix appended to baseURL (default: '/auth'). */
@@ -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,19 +159,32 @@ 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" };
   }
-  if (!isSafeRecoveryEndpoint(options.endpoint)) {
+  const endpoint = sameOriginRecoveryEndpoint(
+    options.endpoint,
+    options.requestOrigin,
+    options.allowLoopbackEndpoint
+  );
+  if (!endpoint) {
+    reportFailure(options, { reason: "invalid-endpoint" });
     return { status: "unavailable" };
   }
   let response;
   try {
-    response = await fetch(options.endpoint, {
+    response = await fetch(endpoint, {
       method: "POST",
       headers: {
         Accept: "application/json",
@@ -167,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
   };
@@ -216,29 +264,80 @@ function isCookieName(value) {
   return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(value);
 }
 function isCookieValue(value) {
-  return value.length > 0 && !/[\r\n;]/.test(value);
+  return value.length > 0 && /^[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]+$/.test(value);
 }
-function isSafeRecoveryEndpoint(value) {
+function sameOriginRecoveryEndpoint(endpoint, requestOrigin, allowLoopback = false) {
   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";
+    const trusted = new URL(requestOrigin);
+    if (trusted.protocol !== "https:" && trusted.protocol !== "http:" || trusted.username || trusted.password) {
+      return void 0;
+    }
+    const resolved = new URL(endpoint, trusted.origin);
+    if (resolved.username || resolved.password) return void 0;
+    if (resolved.origin !== trusted.origin && (!allowLoopback || !isLoopbackURL(resolved))) {
+      return void 0;
+    }
+    return resolved.toString();
   } catch {
-    return false;
+    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");
     __name(readSetCookieValue, "readSetCookieValue");
     __name(isCookieName, "isCookieName");
     __name(isCookieValue, "isCookieValue");
-    __name(isSafeRecoveryEndpoint, "isSafeRecoveryEndpoint");
+    __name(sameOriginRecoveryEndpoint, "sameOriginRecoveryEndpoint");
+    __name(isLoopbackURL, "isLoopbackURL");
+    __name(reportFailure, "reportFailure");
+    __name(safeErrorDetails, "safeErrorDetails");
+    __name(safeText, "safeText");
+    __name(safeOptionalText, "safeOptionalText");
+    __name(isRecord2, "isRecord");
   }
 });
 
@@ -253,8 +352,25 @@ __export(getSession_exports, {
 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`;
+  const publicUrl = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_API_URL : void 0;
+  return publicUrl || "/api";
+}
+function firstForwardedValue(value) {
+  const first = value?.split(",")[0]?.trim();
+  return first || void 0;
+}
+function requestOriginFromHeaders(headers) {
+  const host = firstForwardedValue(headers.get("x-forwarded-host")) ?? firstForwardedValue(headers.get("host"));
+  if (!host) return void 0;
+  const protocol = firstForwardedValue(headers.get("x-forwarded-proto")) ?? "https";
+  if (protocol !== "https" && protocol !== "http") return void 0;
+  try {
+    const url = new URL(`${protocol}://${host}`);
+    if (url.username || url.password) return void 0;
+    return url.origin;
+  } catch {
+    return void 0;
+  }
 }
 async function getSession(config = {}) {
   const cookieName = config.cookieName ?? "refreshToken";
@@ -262,13 +378,18 @@ 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;
   try {
     const mod = await import("next/headers");
     const cookieStore = await mod.cookies();
     sessionCookieValue = cookieStore.get(sessionCookieName)?.value;
     refreshCookieValue = cookieStore.get(cookieName)?.value;
+    if (typeof mod.headers === "function") {
+      requestOrigin = requestOriginFromHeaders(await mod.headers());
+    }
   } catch {
     if (strict) throw new AuthConfigError("Failed to read cookies from Next.js headers()");
     return null;
@@ -291,18 +412,25 @@ 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;
   }
-  const endpoint = config.recoveryURL ? new URL(config.recoveryURL, baseURL).toString() : authEndpoint(baseURL, prefix, "/session/recover");
+  if (!requestOrigin) {
+    if (strict) throw new AuthConfigError("Incoming request origin is unavailable");
+    return null;
+  }
+  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 {
@@ -359,6 +487,8 @@ var init_getSession = __esm({
       code = "AUTH_TRANSPORT_ERROR";
     };
     __name(defaultBaseURL, "defaultBaseURL");
+    __name(firstForwardedValue, "firstForwardedValue");
+    __name(requestOriginFromHeaders, "requestOriginFromHeaders");
     __name(getSession, "getSession");
   }
 });
@@ -568,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) => {
@@ -605,17 +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(
@@ -1176,8 +1312,10 @@ function defineAuth(authConfig = {}) {
     sessionSecret,
     sessionMaxAge,
     recoveryURL,
+    internalRecoveryURL,
     matcher = ["/((?!_next/static|_next/image|favicon.ico|api).*)"],
     verifyAlways = false,
+    onRecoveryFailure,
     refreshThreshold,
     tabSync,
     channelName,
@@ -1185,14 +1323,15 @@ function defineAuth(authConfig = {}) {
     retry
   } = authConfig;
   const sessionConfig = {
-    baseURL: void 0,
-    // resolved at call time from env/defaults
+    baseURL: apiBaseURL,
     authPrefix,
     cookieName,
     sessionCookieName,
     sessionSecret,
     sessionMaxAge,
-    recoveryURL
+    recoveryURL,
+    internalRecoveryURL,
+    onRecoveryFailure
   };
   let _client = null;
   const getClient = /* @__PURE__ */ __name(() => {
@@ -1246,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/dist/index.js

@@ -10,12 +10,12 @@ import { Err as Err11, plugin } from "najm-core";
 import { cache } from "najm-cache";
 
 // src/auth.tokens.ts
-var AUTH_CONFIG = /* @__PURE__ */ Symbol.for("najm:auth:config");
-var AUTH_SCHEMA = /* @__PURE__ */ Symbol.for("najm:auth:schema");
-var AUTH_USER = /* @__PURE__ */ Symbol.for("najm:auth:user");
-var AUTH_ROLE = /* @__PURE__ */ Symbol.for("najm:auth:role");
-var AUTH_PERMISSIONS = /* @__PURE__ */ Symbol.for("najm:auth:permissions");
-var AUTH_ENCRYPTION_KEY = /* @__PURE__ */ Symbol.for("najm:auth:encryption-key");
+var AUTH_CONFIG = Symbol.for("najm:auth:config");
+var AUTH_SCHEMA = Symbol.for("najm:auth:schema");
+var AUTH_USER = Symbol.for("najm:auth:user");
+var AUTH_ROLE = Symbol.for("najm:auth:role");
+var AUTH_PERMISSIONS = Symbol.for("najm:auth:permissions");
+var AUTH_ENCRYPTION_KEY = Symbol.for("najm:auth:encryption-key");
 
 // src/schema/pg.ts
 import { pgTable, text, boolean, timestamp, pgEnum, primaryKey, integer, index, uniqueIndex } from "drizzle-orm/pg-core";
@@ -3980,9 +3980,9 @@ var revokeTokenDto = z4.object({
 // src/ownership/scopedOwnership.ts
 import { aliasedTable, eq as eq6, getTableColumns, sql as sql4 } from "drizzle-orm";
 var DEFAULT_ADMIN_ROLES = ["admin"];
-var DRIZZLE_NAME = /* @__PURE__ */ Symbol.for("drizzle:Name");
-var DRIZZLE_BASE_NAME = /* @__PURE__ */ Symbol.for("drizzle:BaseName");
-var DRIZZLE_IS_ALIAS = /* @__PURE__ */ Symbol.for("drizzle:IsAlias");
+var DRIZZLE_NAME = Symbol.for("drizzle:Name");
+var DRIZZLE_BASE_NAME = Symbol.for("drizzle:BaseName");
+var DRIZZLE_IS_ALIAS = Symbol.for("drizzle:IsAlias");
 function join2(left, right) {
   const table = right.table;
   if (!table)
@@ -4430,9 +4430,9 @@ __name(configureOwnership, "configureOwnership");
 // src/ownership/ScopeGuard.ts
 import "reflect-metadata";
 import { composeGuards as composeGuards5 } from "najm-guard";
-var ACTION_KEY = /* @__PURE__ */ Symbol.for("najm:guard:action");
-var TOKEN_KEY = /* @__PURE__ */ Symbol.for("najm:guard:token");
-var POLICY_KEY = /* @__PURE__ */ Symbol.for("najm:policy:token");
+var ACTION_KEY = Symbol.for("najm:guard:action");
+var TOKEN_KEY = Symbol.for("najm:guard:token");
+var POLICY_KEY = Symbol.for("najm:policy:token");
 var PERM = {
   list: /* @__PURE__ */ __name((n) => `read:${n}`, "list"),
   read: /* @__PURE__ */ __name((n) => `read:${n}`, "read"),
@@ -4502,7 +4502,7 @@ var __metadata25 = function(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 var _a16;
-var OWNED_META = /* @__PURE__ */ Symbol.for("najm:owned");
+var OWNED_META = Symbol.for("najm:owned");
 var ScopeContext = class ScopeContext2 {
   static {
     __name(this, "ScopeContext");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "2.0.5",
+  "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"
@@ -67,9 +68,10 @@
     "@testing-library/react": "^16.3.2",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^25.0.2",
-    "drizzle-kit": "^0.31.8",
-    "drizzle-orm": "^0.45.1",
-    "happy-dom": "^17.6.3",
+    "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"
   },
@@ -93,8 +95,8 @@
     "zod": "^4.2.1"
   },
   "peerDependencies": {
-    "drizzle-orm": "^0.45.1",
-    "hono": "^4.0.0",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.12.18",
     "react": ">=18",
     "next": ">=14"
   },