najm-auth 2.0.14 → 2.0.15

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

@@ -169,6 +169,16 @@ interface DefineAuthConfig {
     loginRoute?: string;
     /** Route to redirect after login (default: '/dashboard') */
     afterLoginRoute?: string;
+    /**
+     * Where an *authenticated* user goes when their role is not allowed
+     * (default: '/forbidden').
+     *
+     * Distinct from `loginRoute` on purpose. Sending them to the login form says
+     * "prove who you are" to someone who already has; they log in again, land
+     * back on the same page, and get bounced again. A forbidden page is the only
+     * response that terminates.
+     */
+    forbiddenRoute?: string;
     /** Routes that are always public (glob patterns) */
     publicRoutes?: string[];
     /** Routes that require authentication (glob patterns) */
@@ -212,6 +222,15 @@ interface AuthKit {
     getSession: (opts?: Pick<GetSessionConfig, 'mode'>) => Promise<ServerSession | null>;
     /** Require session — throws if unauthenticated */
     requireSession: () => Promise<ServerSession>;
+    /**
+     * Require one of `roles` — redirects to `loginRoute` when unauthenticated and
+     * to `forbiddenRoute` when authenticated as the wrong role.
+     *
+     * ```ts
+     * const session = await auth.requireRole(['admin', 'operator']);
+     * ```
+     */
+    requireRole: (roles: string[]) => Promise<ServerSession>;
     /** Generated Next.js middleware function */
     middleware: (request: Request) => Promise<Response>;
     /** Next.js middleware config with matcher */
@@ -232,4 +251,78 @@ interface AuthKit {
 }
 declare function defineAuth(authConfig?: DefineAuthConfig): AuthKit;
 
-export { AuthConfigError, type AuthKit, AuthTransportError, type DefineAuthConfig, type GetSessionConfig, NoSessionError, type ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getServerSession, getSession, withAuth };
+interface SafeRedirectOptions {
+    /** Where to send anything rejected. Defaults to `/dashboard`. */
+    fallback?: string;
+    /**
+     * Path prefixes that are never a valid destination. Defaults to `/api`,
+     * `/login` and `/_next`.
+     *
+     * `/login` is on the list because bouncing back to it is the redirect loop
+     * this parameter causes most often: a user who just authenticated is sent
+     * straight back to the form they came from.
+     */
+    blockedPrefixes?: string[];
+}
+/**
+ * Reduces an untrusted `?next=` value to a path that is safe to redirect to.
+ *
+ * Only same-origin *paths* survive. An absolute URL is rejected outright rather
+ * than parsed and compared, because the comparison is where this goes wrong:
+ * `//evil.test` is a protocol-relative URL that browsers resolve off-site while
+ * a naive `startsWith('/')` check reads it as local. Anything that is not a
+ * single leading slash followed by a path is refused.
+ *
+ * ```ts
+ * redirect(getSafeRedirectPath(searchParams.next, { fallback: '/home' }));
+ * ```
+ */
+declare function getSafeRedirectPath(value: string | string[] | undefined | null, options?: SafeRedirectOptions | string): string;
+
+type RequestHandler = (request: Request) => Promise<Response>;
+interface AuthCookiePersistenceOptions {
+    /**
+     * Cookies whose lifetime this rewrites. Defaults to the two najm-auth issues.
+     * Anything not named here is passed through untouched.
+     */
+    authCookieNames?: string[];
+    /** Where the one-bit choice is stored. Defaults to `najm.remember`. */
+    rememberCookieName?: string;
+    /** How long a remembered choice lasts. Defaults to 7 days. */
+    maxAgeSeconds?: number;
+    /** Paths whose JSON body carries `rememberMe`. Defaults to `/api/auth/login`. */
+    loginPaths?: string[];
+    /** Paths that end a session and clear the choice. Defaults to `/api/auth/logout`. */
+    logoutPaths?: string[];
+    /** Paths that reissue cookies and must reapply the stored choice. */
+    refreshPaths?: string[];
+    /**
+     * Recognizes a response that has *not* issued a usable session because the
+     * user must still set up credentials.
+     *
+     * Such a response may carry auth cookies anyway, and persisting them would
+     * leave a half-authenticated browser that skips the setup step on reload.
+     * Returning `true` strips them and clears the stored choice.
+     */
+    isSetupResponse?: (payload: unknown) => boolean;
+}
+/**
+ * Strips the lifetime attributes so the browser drops the cookie when it closes.
+ *
+ * Only the named auth cookies are touched — rewriting an unrelated `Set-Cookie`
+ * from the same response would be a silent side effect on someone else's state.
+ */
+declare function makeSessionCookie(setCookie: string, authCookieNames?: string[]): string;
+/**
+ * Wraps a request handler so the auth cookies it issues match the user's
+ * "remember me" choice.
+ *
+ * ```ts
+ * // app/api/[...route]/route.ts
+ * const handler = withAuthCookiePersistence((req) => server.fetch(req));
+ * export { handler as GET, handler as POST };
+ * ```
+ */
+declare function withAuthCookiePersistence(handler: RequestHandler, options?: AuthCookiePersistenceOptions): RequestHandler;
+
+export { AuthConfigError, type AuthCookiePersistenceOptions, type AuthKit, AuthTransportError, type DefineAuthConfig, type GetSessionConfig, NoSessionError, type SafeRedirectOptions, type ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getSafeRedirectPath, getServerSession, getSession, makeSessionCookie, withAuth, withAuthCookiePersistence };

package/dist/client/server/index.js

@@ -382,7 +382,7 @@ function requestOriginFromHeaders(headers) {
   }
 }
 async function getSession(config = {}) {
-  const cookieName = config.cookieName ?? "refreshToken";
+  const cookieName2 = config.cookieName ?? "refreshToken";
   const sessionCookieName = config.sessionCookieName ?? "najm.session";
   const baseURL = config.baseURL ?? defaultBaseURL();
   const prefix = config.authPrefix ?? "/auth";
@@ -395,7 +395,7 @@ async function getSession(config = {}) {
     const mod = await import("next/headers");
     const cookieStore = await mod.cookies();
     sessionCookieValue = cookieStore.get(sessionCookieName)?.value;
-    refreshCookieValue = cookieStore.get(cookieName)?.value;
+    refreshCookieValue = cookieStore.get(cookieName2)?.value;
     if (typeof mod.headers === "function") {
       requestOrigin = requestOriginFromHeaders(await mod.headers());
     }
@@ -434,7 +434,7 @@ async function getSession(config = {}) {
     endpoint,
     requestOrigin,
     allowLoopbackEndpoint: internalRecoveryURL !== void 0,
-    refreshCookieName: cookieName,
+    refreshCookieName: cookieName2,
     refreshCookieValue,
     sessionCookieName,
     sessionSecret: secret,
@@ -700,7 +700,7 @@ function withAuthMiddleware(config) {
     publicRoutes = [],
     loginRoute = "/login",
     roleRoutes = {},
-    cookieName = "refreshToken",
+    cookieName: cookieName2 = "refreshToken",
     apiBaseURL = "/api",
     authPrefix = "/auth",
     sessionCookieName = "najm.session",
@@ -719,7 +719,7 @@ function withAuthMiddleware(config) {
       loginUrl.searchParams.set("from", returnPath2);
       const res = NextResponse.redirect(loginUrl);
       if (clearCookies.includes("refresh")) {
-        res.cookies.delete(cookieName);
+        res.cookies.delete(cookieName2);
       }
       if (clearCookies.includes("session")) {
         res.cookies.delete(sessionCookieName);
@@ -746,7 +746,7 @@ function withAuthMiddleware(config) {
     }) : null;
     let recovery = null;
     if (!session || verifyAlways) {
-      const refreshCookie = readCookieValue(cookie, cookieName);
+      const refreshCookie = readCookieValue(cookie, cookieName2);
       if (!refreshCookie || recoveryURL === false && !resolvedInternalRecoveryURL) {
         return redirectToLogin(returnPath, ["refresh", "session"]);
       }
@@ -755,7 +755,7 @@ function withAuthMiddleware(config) {
         endpoint,
         requestOrigin: url.origin,
         allowLoopbackEndpoint: resolvedInternalRecoveryURL !== void 0,
-        refreshCookieName: cookieName,
+        refreshCookieName: cookieName2,
         refreshCookieValue: refreshCookie,
         sessionCookieName,
         sessionSecret: secret,
@@ -1324,10 +1324,11 @@ function defineAuth(authConfig = {}) {
     apiBaseURL = "/api",
     authPrefix = "/auth",
     loginRoute = "/login",
+    forbiddenRoute = "/forbidden",
     publicRoutes = [],
     protectedRoutes = [],
     roleRoutes = {},
-    cookieName = "refreshToken",
+    cookieName: cookieName2 = "refreshToken",
     sessionCookieName = "najm.session",
     sessionSecret,
     sessionMaxAge,
@@ -1345,7 +1346,7 @@ function defineAuth(authConfig = {}) {
   const sessionConfig = {
     baseURL: apiBaseURL,
     authPrefix,
-    cookieName,
+    cookieName: cookieName2,
     sessionCookieName,
     sessionSecret,
     sessionMaxAge,
@@ -1393,12 +1394,21 @@ function defineAuth(authConfig = {}) {
       throw err;
     }
   }, "requireSession");
+  const requireRole = /* @__PURE__ */ __name(async (roles) => {
+    const session = await requireSession();
+    const held = session.roles ?? (session.user.role ? [session.user.role] : []);
+    if (!held.some((role) => roles.includes(role))) {
+      const { redirect } = await import("next/navigation");
+      redirect(forbiddenRoute);
+    }
+    return session;
+  }, "requireRole");
   const middleware = withAuthMiddleware({
     protectedRoutes,
     publicRoutes,
     loginRoute,
     roleRoutes,
-    cookieName,
+    cookieName: cookieName2,
     apiBaseURL,
     authPrefix,
     sessionCookieName,
@@ -1420,7 +1430,7 @@ function defineAuth(authConfig = {}) {
         const userRoles = session.roles ?? (session.user.role ? [session.user.role] : []);
         if (!userRoles.includes(options.role)) {
           const { redirect } = await import("next/navigation");
-          redirect(loginRoute);
+          redirect(forbiddenRoute);
         }
       }
       if (options?.permission) {
@@ -1428,7 +1438,7 @@ function defineAuth(authConfig = {}) {
         const perms = session.permissions ?? session.user.permissions ?? [];
         if (!matchPermission2(perms, options.permission)) {
           const { redirect } = await import("next/navigation");
-          redirect(loginRoute);
+          redirect(forbiddenRoute);
         }
       }
       return Page({ session, ...props });
@@ -1443,20 +1453,173 @@ function defineAuth(authConfig = {}) {
     },
     getSession: getSession2,
     requireSession,
+    requireRole,
     middleware,
     config: { matcher },
     protect
   };
 }
 __name(defineAuth, "defineAuth");
+
+// src/client/server/safeRedirect.ts
+var DEFAULT_BLOCKED_PREFIXES = ["/api", "/login", "/_next"];
+var ASSET_EXTENSIONS = /\.(?:css|gif|ico|jpe?g|js|json|map|png|svg|webmanifest|webp)$/i;
+function getSafeRedirectPath(value, options = {}) {
+  const {
+    fallback = "/dashboard",
+    blockedPrefixes = DEFAULT_BLOCKED_PREFIXES
+  } = typeof options === "string" ? { fallback: options } : options;
+  const path = Array.isArray(value) ? value[0] : value;
+  if (!path || !path.startsWith("/") || // Protocol-relative: the browser treats `//host/x` as off-site.
+  path.startsWith("//") || // A backslash is normalized to a forward slash by some browsers, so
+  // `/\evil.test` is another way to spell the case above.
+  path.startsWith("/\\") || blockedPrefixes.some((prefix) => path.startsWith(prefix)) || ASSET_EXTENSIONS.test(path.split("?")[0] ?? path)) {
+    return fallback;
+  }
+  return path;
+}
+__name(getSafeRedirectPath, "getSafeRedirectPath");
+
+// src/client/server/authCookiePersistence.ts
+var DEFAULTS = {
+  authCookieNames: ["refreshToken", "najm.session"],
+  rememberCookieName: "najm.remember",
+  maxAgeSeconds: 7 * 24 * 60 * 60,
+  loginPaths: ["/api/auth/login"],
+  logoutPaths: ["/api/auth/logout"],
+  refreshPaths: ["/api/auth/refresh", "/api/auth/session/recover"]
+};
+function cookieValue(header, name) {
+  for (const part of header.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator < 0) continue;
+    if (part.slice(0, separator).trim() !== name) continue;
+    return part.slice(separator + 1).trim();
+  }
+  return void 0;
+}
+__name(cookieValue, "cookieValue");
+function cookieName(setCookie) {
+  const separator = setCookie.indexOf("=");
+  return separator < 0 ? "" : setCookie.slice(0, separator).trim();
+}
+__name(cookieName, "cookieName");
+function makeSessionCookie(setCookie, authCookieNames = DEFAULTS.authCookieNames) {
+  if (!authCookieNames.includes(cookieName(setCookie))) return setCookie;
+  return setCookie.split(";").filter((part) => !/^\s*(?:expires|max-age)=/i.test(part)).join(";");
+}
+__name(makeSessionCookie, "makeSessionCookie");
+function isDeletionCookie(setCookie) {
+  if (/^[^=]+=\s*(?:;|$)/.test(setCookie)) return true;
+  if (/(?:^|;)\s*max-age=0(?:;|$)/i.test(setCookie)) return true;
+  const expires = /(?:^|;)\s*expires=([^;]+)/i.exec(setCookie)?.[1];
+  return expires ? new Date(expires).getTime() <= Date.now() : false;
+}
+__name(isDeletionCookie, "isDeletionCookie");
+function rememberCookie(name, mode, secure, maxAgeSeconds) {
+  const attributes = [
+    `${name}=${mode === "persistent" ? "1" : "0"}`,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Lax"
+  ];
+  if (secure) attributes.push("Secure");
+  if (mode === "persistent") attributes.push(`Max-Age=${maxAgeSeconds}`);
+  return attributes.join("; ");
+}
+__name(rememberCookie, "rememberCookie");
+function clearedRememberCookie(name, secure) {
+  return [
+    `${name}=`,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Lax",
+    ...secure ? ["Secure"] : [],
+    "Max-Age=0"
+  ].join("; ");
+}
+__name(clearedRememberCookie, "clearedRememberCookie");
+function withAuthCookiePersistence(handler, options = {}) {
+  const {
+    authCookieNames = DEFAULTS.authCookieNames,
+    rememberCookieName = DEFAULTS.rememberCookieName,
+    maxAgeSeconds = DEFAULTS.maxAgeSeconds,
+    loginPaths = DEFAULTS.loginPaths,
+    logoutPaths = DEFAULTS.logoutPaths,
+    refreshPaths = DEFAULTS.refreshPaths,
+    isSetupResponse
+  } = options;
+  const resolveAction = /* @__PURE__ */ __name(async (request) => {
+    const { pathname } = new URL(request.url);
+    if (loginPaths.includes(pathname)) {
+      const body = await request.clone().json().catch(() => null);
+      return {
+        type: "apply",
+        mode: body?.rememberMe === true ? "persistent" : "session"
+      };
+    }
+    if (logoutPaths.includes(pathname)) return { type: "clear" };
+    if (refreshPaths.includes(pathname)) {
+      const remembered = cookieValue(
+        request.headers.get("cookie") ?? "",
+        rememberCookieName
+      );
+      if (remembered === "0") return { type: "apply", mode: "session" };
+      if (remembered === "1") return { type: "apply", mode: "persistent" };
+    }
+    return null;
+  }, "resolveAction");
+  const applyAction = /* @__PURE__ */ __name((response, action, secure) => {
+    const headers = new Headers(response.headers);
+    const setCookies = headers.getSetCookie();
+    headers.delete("set-cookie");
+    for (const setCookie of setCookies) {
+      if (action.type === "setup" && authCookieNames.includes(cookieName(setCookie)) && !isDeletionCookie(setCookie)) {
+        continue;
+      }
+      headers.append(
+        "set-cookie",
+        action.type === "apply" && action.mode === "session" ? makeSessionCookie(setCookie, authCookieNames) : setCookie
+      );
+    }
+    headers.append(
+      "set-cookie",
+      action.type === "clear" || action.type === "setup" ? clearedRememberCookie(rememberCookieName, secure) : rememberCookie(rememberCookieName, action.mode, secure, maxAgeSeconds)
+    );
+    return new Response(response.body, {
+      headers,
+      status: response.status,
+      statusText: response.statusText
+    });
+  }, "applyAction");
+  return async (request) => {
+    let action = await resolveAction(request);
+    const response = await handler(request);
+    if (!response.ok) return response;
+    if (action?.type === "apply" && isSetupResponse) {
+      const payload = await response.clone().json().catch(() => null);
+      if (isSetupResponse(payload)) action = { type: "setup" };
+    }
+    if (!action) return response;
+    return applyAction(
+      response,
+      action,
+      new URL(request.url).protocol === "https:"
+    );
+  };
+}
+__name(withAuthCookiePersistence, "withAuthCookiePersistence");
 export {
   AuthConfigError,
   AuthTransportError,
   NoSessionError,
   createServerClient,
   defineAuth,
+  getSafeRedirectPath,
   getServerSession,
   getSession,
+  makeSessionCookie,
   withAuth,
+  withAuthCookiePersistence,
   withAuthMiddleware
 };

package/package.json

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