@neondatabase/auth 0.1.0-beta.8 → 0.2.0-beta.1

package/dist/next/server/index.mjs

@@ -0,0 +1,1373 @@
+import { o as NEON_AUTH_SESSION_VERIFIER_PARAM_NAME } from "../../constants-Cupc_bln.mjs";
+import { SignJWT, jwtVerify } from "jose";
+import { parseCookies, parseSetCookieHeader } from "better-auth/cookies";
+import { cookies, headers } from "next/headers";
+import { NextRequest, NextResponse } from "next/server";
+
+//#region src/server/request-context.ts
+/**
+* Header name used to identify server-side proxy requests.
+* The value will be the framework name (e.g., 'nextjs', 'remix').
+*/
+const NEON_AUTH_SERVER_PROXY_HEADER = "x-neon-auth-proxy";
+
+//#endregion
+//#region src/server/endpoints.ts
+const API_ENDPOINTS = {
+	getSession: {
+		path: "get-session",
+		method: "GET"
+	},
+	getAccessToken: {
+		path: "get-access-token",
+		method: "GET"
+	},
+	listSessions: {
+		path: "list-sessions",
+		method: "GET"
+	},
+	revokeSession: {
+		path: "revoke-session",
+		method: "POST"
+	},
+	revokeSessions: {
+		path: "revoke-sessions",
+		method: "POST"
+	},
+	revokeOtherSessions: {
+		path: "revoke-all-sessions",
+		method: "POST"
+	},
+	refreshToken: {
+		path: "refresh-token",
+		method: "POST"
+	},
+	signIn: {
+		email: {
+			path: "sign-in/email",
+			method: "POST"
+		},
+		social: {
+			path: "sign-in/social",
+			method: "POST"
+		},
+		emailOtp: {
+			path: "sign-in/email-otp",
+			method: "POST"
+		}
+	},
+	signUp: { email: {
+		path: "sign-up/email",
+		method: "POST"
+	} },
+	signOut: {
+		path: "sign-out",
+		method: "POST"
+	},
+	listAccounts: {
+		path: "list-accounts",
+		method: "GET"
+	},
+	accountInfo: {
+		path: "account-info",
+		method: "GET"
+	},
+	updateUser: {
+		path: "update-user",
+		method: "POST"
+	},
+	deleteUser: {
+		path: "delete-user",
+		method: "POST"
+	},
+	changePassword: {
+		path: "change-password",
+		method: "POST"
+	},
+	sendVerificationEmail: {
+		path: "send-verification-email",
+		method: "POST"
+	},
+	verifyEmail: {
+		path: "verify-email",
+		method: "POST"
+	},
+	resetPassword: {
+		path: "reset-password",
+		method: "POST"
+	},
+	requestPasswordReset: {
+		path: "request-password-reset",
+		method: "POST"
+	},
+	token: {
+		path: "token",
+		method: "GET"
+	},
+	jwks: {
+		path: "jwt",
+		method: "GET"
+	},
+	getAnonymousToken: {
+		path: "token/anonymous",
+		method: "GET"
+	},
+	admin: {
+		createUser: {
+			path: "admin/create-user",
+			method: "POST"
+		},
+		listUsers: {
+			path: "admin/list-users",
+			method: "GET"
+		},
+		setRole: {
+			path: "admin/set-role",
+			method: "POST"
+		},
+		setUserPassword: {
+			path: "admin/set-user-password",
+			method: "POST"
+		},
+		updateUser: {
+			path: "admin/update-user",
+			method: "POST"
+		},
+		banUser: {
+			path: "admin/ban-user",
+			method: "POST"
+		},
+		unbanUser: {
+			path: "admin/unban-user",
+			method: "POST"
+		},
+		listUserSessions: {
+			path: "admin/list-user-sessions",
+			method: "GET"
+		},
+		revokeUserSession: {
+			path: "admin/revoke-user-session",
+			method: "POST"
+		},
+		revokeUserSessions: {
+			path: "admin/revoke-user-sessions",
+			method: "POST"
+		},
+		impersonateUser: {
+			path: "admin/impersonate-user",
+			method: "POST"
+		},
+		stopImpersonating: {
+			path: "admin/stop-impersonating",
+			method: "POST"
+		},
+		removeUser: {
+			path: "admin/remove-user",
+			method: "POST"
+		},
+		hasPermission: {
+			path: "admin/has-permission",
+			method: "POST"
+		}
+	},
+	organization: {
+		create: {
+			path: "organization/create",
+			method: "POST"
+		},
+		update: {
+			path: "organization/update",
+			method: "POST"
+		},
+		delete: {
+			path: "organization/delete",
+			method: "POST"
+		},
+		list: {
+			path: "organization/list",
+			method: "GET"
+		},
+		getFullOrganization: {
+			path: "organization/get-full-organization",
+			method: "GET"
+		},
+		setActive: {
+			path: "organization/set-active",
+			method: "POST"
+		},
+		checkSlug: {
+			path: "organization/check-slug",
+			method: "GET"
+		},
+		listMembers: {
+			path: "organization/list-members",
+			method: "GET"
+		},
+		removeMember: {
+			path: "organization/remove-member",
+			method: "POST"
+		},
+		updateMemberRole: {
+			path: "organization/update-member-role",
+			method: "POST"
+		},
+		leave: {
+			path: "organization/leave",
+			method: "POST"
+		},
+		getActiveMember: {
+			path: "organization/get-active-member",
+			method: "GET"
+		},
+		getActiveMemberRole: {
+			path: "organization/get-active-member-role",
+			method: "GET"
+		},
+		inviteMember: {
+			path: "organization/invite-member",
+			method: "POST"
+		},
+		acceptInvitation: {
+			path: "organization/accept-invitation",
+			method: "POST"
+		},
+		rejectInvitation: {
+			path: "organization/reject-invitation",
+			method: "POST"
+		},
+		cancelInvitation: {
+			path: "organization/cancel-invitation",
+			method: "POST"
+		},
+		getInvitation: {
+			path: "organization/get-invitation",
+			method: "GET"
+		},
+		listInvitations: {
+			path: "organization/list-invitations",
+			method: "GET"
+		},
+		listUserInvitations: {
+			path: "organization/list-user-invitations",
+			method: "GET"
+		},
+		hasPermission: {
+			path: "organization/has-permission",
+			method: "POST"
+		}
+	},
+	emailOtp: {
+		sendVerificationOtp: {
+			path: "email-otp/send-verification-otp",
+			method: "POST"
+		},
+		verifyEmail: {
+			path: "email-otp/verify-email",
+			method: "POST"
+		},
+		checkVerificationOtp: {
+			path: "email-otp/check-verification-otp",
+			method: "POST"
+		},
+		resetPassword: {
+			path: "email-otp/passcode",
+			method: "POST"
+		}
+	}
+};
+
+//#endregion
+//#region src/server/constants.ts
+/** Prefix for all Neon Auth cookies */
+const NEON_AUTH_COOKIE_PREFIX = "__Secure-neon-auth";
+/** Cookie name for cached session data (signed JWT) - used for server-side session caching */
+const NEON_AUTH_SESSION_DATA_COOKIE_NAME = `${NEON_AUTH_COOKIE_PREFIX}.local.session_data`;
+/** Cookie name for OAuth session challenge - used for OAuth flow security */
+const NEON_AUTH_SESSION_CHALLENGE_COOKIE_NAME = `${NEON_AUTH_COOKIE_PREFIX}.session_challange`;
+/** Cookie name for session token - the primary authentication cookie */
+const NEON_AUTH_SESSION_COOKIE_NAME = `${NEON_AUTH_COOKIE_PREFIX}.session_token`;
+
+//#endregion
+//#region src/server/utils/cookies.ts
+/**
+* Extract the Neon Auth cookies from the request headers.
+* Only returns cookies that start with the NEON_AUTH_COOKIE_PREFIX.
+*
+* @param headers - The request headers or cookie header string.
+* @returns The cookie string with all Neon Auth cookies (e.g., "name=value; name2=value2").
+*/
+const extractNeonAuthCookies = (headers$1) => {
+	const cookieHeader = typeof headers$1 === "string" ? headers$1 : headers$1.get("cookie");
+	if (!cookieHeader) return "";
+	const parsedCookies = parseCookies(cookieHeader);
+	const result = [];
+	for (const [name, value] of parsedCookies.entries()) if (name.startsWith(NEON_AUTH_COOKIE_PREFIX)) result.push(`${name}=${value}`);
+	return result.join("; ");
+};
+/**
+* Parses the `set-cookie` header from Neon Auth response into a list of cookies.
+*
+* @param setCookieHeader - The `set-cookie` header from Neon Auth response.
+* @returns The list of parsed cookies with their options.
+*/
+const parseSetCookies = (setCookieHeader) => {
+	const parsedCookies = parseSetCookieHeader(setCookieHeader);
+	const cookies$1 = [];
+	for (const entry of parsedCookies.entries()) {
+		const [name, parsedCookie] = entry;
+		cookies$1.push({
+			name,
+			value: decodeURIComponent(parsedCookie.value),
+			path: parsedCookie.path,
+			domain: parsedCookie.domain,
+			maxAge: parsedCookie["max-age"] ?? parsedCookie.maxAge,
+			httpOnly: parsedCookie.httponly ?? true,
+			secure: parsedCookie.secure ?? true,
+			sameSite: parsedCookie.samesite ?? "lax",
+			partitioned: parsedCookie.partitioned
+		});
+	}
+	return cookies$1;
+};
+/**
+* Serializes a parsed cookie object back into a Set-Cookie header string
+*
+* @param cookie - The parsed cookie object
+* @returns The Set-Cookie header string
+*/
+const serializeSetCookie = (cookie) => {
+	let result = `${cookie.name}=${encodeURIComponent(cookie.value)}`;
+	if (cookie.path) result += `; Path=${cookie.path}`;
+	if (cookie.domain) result += `; Domain=${cookie.domain}`;
+	if (cookie.maxAge !== void 0) result += `; Max-Age=${cookie.maxAge}`;
+	if (cookie.expires) result += `; Expires=${cookie.expires.toUTCString()}`;
+	if (cookie.httpOnly) result += "; HttpOnly";
+	if (cookie.secure) result += "; Secure";
+	if (cookie.sameSite) {
+		const sameSite = cookie.sameSite.charAt(0).toUpperCase() + cookie.sameSite.slice(1);
+		result += `; SameSite=${sameSite}`;
+	}
+	if (cookie.partitioned) result += "; Partitioned";
+	return result;
+};
+/**
+* Extract a single cookie value by name from a cookie header string
+*
+* @param cookieString - The cookie header string (e.g., "name=value; name2=value2")
+* @param name - The cookie name to extract
+* @returns The cookie value or null if not found
+*/
+const parseCookieValue = (cookieString, name) => {
+	if (!cookieString) return null;
+	return parseCookies(cookieString).get(name) ?? null;
+};
+
+//#endregion
+//#region src/server/session/operations.ts
+const DEFAULT_SESSION_CACHE_TTL_SECONDS = 300;
+const JWS_ALGO = "HS256";
+/**
+* Parse and validate date value, throwing descriptive error on failure
+* @internal
+*/
+function parseDate(dateValue, fieldName) {
+	const date = new Date(dateValue);
+	if (Number.isNaN(date.getTime())) throw new TypeError(`Invalid date value for ${fieldName}: ${JSON.stringify(dateValue)}`);
+	return date;
+}
+/**
+* Convert session data from /get-session into a signed cookie
+* @param sessionData - Session and user data from Auth server
+* @param secret - Secret for signing the cookie
+* @param ttlSeconds - Time-to-live in seconds (default: 300 = 5 minutes)
+* @returns Signed session data cookie
+*/
+async function signSessionDataCookie(sessionData, secret, ttlSeconds = DEFAULT_SESSION_CACHE_TTL_SECONDS) {
+	const ttlMs = ttlSeconds * 1e3;
+	const expiresAt = Math.min(sessionData.session.expiresAt.getTime(), Date.now() + ttlMs);
+	return {
+		value: await signPayload(sessionData, expiresAt, secret),
+		expiresAt: new Date(expiresAt)
+	};
+}
+function signPayload(sessionData, expiresAt, secret) {
+	const encodedSecret = new TextEncoder().encode(secret);
+	const expSeconds = Math.floor(expiresAt / 1e3);
+	return new SignJWT(sessionData).setProtectedHeader({
+		alg: JWS_ALGO,
+		typ: "JWT"
+	}).setIssuedAt().setExpirationTime(expSeconds).setSubject(sessionData.user?.id ?? "anonymous").sign(encodedSecret);
+}
+/**
+* Parse session data from JSON, converting date strings to Date objects
+*
+* Note: Better Auth API returns ISO 8601 date strings. JSON.parse() does not
+* automatically convert these to Date objects, so manual conversion is required.
+*
+* @internal Exported for internal use by auth handler
+*/
+function parseSessionData(json) {
+	if (!json || typeof json !== "object") return {
+		session: null,
+		user: null
+	};
+	const data = json;
+	if (!data.session || !data.user) return {
+		session: null,
+		user: null
+	};
+	try {
+		return {
+			session: {
+				...data.session,
+				expiresAt: parseDate(data.session.expiresAt, "session.expiresAt"),
+				createdAt: parseDate(data.session.createdAt, "session.createdAt"),
+				updatedAt: parseDate(data.session.updatedAt, "session.updatedAt")
+			},
+			user: {
+				...data.user,
+				createdAt: parseDate(data.user.createdAt, "user.createdAt"),
+				updatedAt: parseDate(data.user.updatedAt, "user.updatedAt")
+			}
+		};
+	} catch (error) {
+		console.error("[parseSessionData] Failed to parse session dates:", {
+			error: error instanceof Error ? error.message : String(error),
+			hasSession: !!data.session,
+			hasUser: !!data.user
+		});
+		return {
+			session: null,
+			user: null
+		};
+	}
+}
+/**
+* Extract and validate session data from cookie header
+* Falls back to null on any error (caller should fetch from API)
+*
+* @param request - Request object with cookie header
+* @param cookieName - Name of session data cookie
+* @param cookieSecret - cookie secret for validation
+* @returns SessionData or null on validation failure
+*/
+async function getSessionDataFromCookie(request, cookieName, cookieSecret) {
+	try {
+		const cookieHeader = request.headers.get("cookie");
+		if (!cookieHeader) return null;
+		const sessionDataCookie = parseCookies(cookieHeader).get(cookieName);
+		if (!sessionDataCookie) return null;
+		const result = await validateSessionData(sessionDataCookie, cookieSecret);
+		if (result.valid && result.payload) return result.payload;
+		console.warn("[getSessionDataFromCookie] Invalid session cookie:", {
+			error: result.error,
+			cookieName
+		});
+		return null;
+	} catch (error) {
+		console.error("[getSessionDataFromCookie] Unexpected validation error:", {
+			error: error instanceof Error ? error.message : String(error),
+			cookieName,
+			...process.env.NODE_ENV !== "production" && { stack: error instanceof Error ? error.stack : void 0 }
+		});
+		return null;
+	}
+}
+
+//#endregion
+//#region src/server/errors.ts
+const ERRORS = {
+	MISSING_AUTH_BASE_URL: "Missing required config: baseUrl. You must provide the auth URL of your Neon Auth instance in the config object.",
+	MISSING_COOKIE_SECRET: "Missing required config: cookies.secret. You must provide the cookie secret in the config object.",
+	COOKIE_SECRET_TOO_SHORT: "cookies.secret must be at least 32 characters long for security. Generate a secure secret with: openssl rand -base64 32",
+	INVALID_SESSION_DATA_TTL: "cookies.sessionDataTtl must be a positive number (in seconds)"
+};
+
+//#endregion
+//#region src/server/session/validator.ts
+/**
+* Validate session data signature and expiry using jose
+* @param sessionDataString - Session data string to validate
+* @param cookieSecret - cookie secret for validation
+* @returns Validation result with payload if valid
+*/
+async function validateSessionData(sessionDataString, cookieSecret) {
+	try {
+		const { payload } = await jwtVerify(sessionDataString, new TextEncoder().encode(cookieSecret), { algorithms: ["HS256"] });
+		return {
+			valid: true,
+			payload: parseSessionData(payload)
+		};
+	} catch (error) {
+		return {
+			valid: false,
+			error: error instanceof Error ? error.message : "Invalid session data"
+		};
+	}
+}
+
+//#endregion
+//#region src/server/proxy/request.ts
+const PROXY_HEADERS = [
+	"user-agent",
+	"authorization",
+	"referer",
+	"content-type"
+];
+/**
+* Proxy header constant - indicates request went through Neon Auth middleware/handler
+* This is framework-agnostic and can be used by any server framework
+*/
+const NEON_AUTH_HEADER_MIDDLEWARE_NAME = "x-neon-auth-middleware";
+/**
+* Handles proxying authentication requests to the upstream Neon Auth server
+*
+* @param baseUrl - Base URL of the Neon Auth server
+* @param request - Standard Web API Request object
+* @param path - API path to proxy to (e.g., 'get-session', 'sign-in')
+* @returns Response from upstream server or error response
+*/
+const handleAuthRequest = async (baseUrl, request, path) => {
+	const headers$1 = prepareRequestHeaders(request);
+	const body = await parseRequestBody(request);
+	try {
+		const upstreamURL = getUpstreamURL(baseUrl, path, { originalUrl: new URL(request.url) });
+		return await fetch(upstreamURL.toString(), {
+			method: request.method,
+			headers: headers$1,
+			body
+		});
+	} catch (error) {
+		if (error instanceof Error && error.name === "TypeError" && error.message.includes("fetch")) return Response.json({
+			error: "Unable to connect to authentication server",
+			code: "NETWORK_ERROR"
+		}, {
+			status: 502,
+			headers: { "Content-Type": "application/json" }
+		});
+		const message = error instanceof Error ? error.message : "Internal Server Error";
+		console.error(`[AuthError] ${message}`, error);
+		return Response.json({
+			error: message,
+			code: "INTERNAL_ERROR"
+		}, {
+			status: 500,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+};
+/**
+* Constructs the upstream URL for proxying to Neon Auth server
+*
+* @param baseUrl - Base URL of the Neon Auth server
+* @param path - API path (e.g., 'get-session')
+* @param options - Options including original URL for preserving query params
+* @returns Constructed upstream URL
+*/
+const getUpstreamURL = (baseUrl, path, { originalUrl }) => {
+	const url = new URL(`${baseUrl}/${path}`);
+	if (originalUrl) {
+		url.search = originalUrl.search;
+		return url;
+	}
+	return url;
+};
+const prepareRequestHeaders = (request) => {
+	const headers$1 = new Headers();
+	for (const header of PROXY_HEADERS) if (request.headers.get(header)) headers$1.set(header, request.headers.get(header));
+	headers$1.set("Origin", getOrigin(request));
+	headers$1.set("Cookie", extractNeonAuthCookies(request.headers));
+	headers$1.set(NEON_AUTH_HEADER_MIDDLEWARE_NAME, "true");
+	return headers$1;
+};
+const getOrigin = (request) => {
+	return request.headers.get("origin") || request.headers.get("referer")?.split("/").slice(0, 3).join("/") || new URL(request.url).origin;
+};
+const parseRequestBody = async (request) => {
+	if (request.body) return request.text();
+};
+
+//#endregion
+//#region src/server/proxy/response.ts
+const RESPONSE_HEADERS_ALLOWLIST = [
+	"content-type",
+	"content-length",
+	"content-encoding",
+	"transfer-encoding",
+	"connection",
+	"date",
+	"set-cookie",
+	"set-auth-jwt",
+	"set-auth-token",
+	"x-neon-ret-request-id"
+];
+/**
+* Handles responses from upstream Neon Auth server
+* - Proxies allowed headers to client
+* - Mints session data cookie if session token is present
+*
+* @param response - Response from upstream Neon Auth server
+* @param baseUrl - Base URL of Neon Auth server
+* @param cookieConfig - Session cookie configuration
+* @returns New Response with proxied headers and session data cookie
+*/
+const handleAuthResponse = async (response, baseUrl, cookieConfig) => {
+	const responseHeaders = prepareResponseHeaders(response, cookieConfig.domain);
+	const sessionDataCookie = await mintSessionData(response.headers, baseUrl, cookieConfig);
+	if (sessionDataCookie) responseHeaders.append("Set-Cookie", sessionDataCookie);
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: responseHeaders
+	});
+};
+const prepareResponseHeaders = (response, domain) => {
+	const headers$1 = new Headers();
+	for (const header of RESPONSE_HEADERS_ALLOWLIST) if (header === "set-cookie") {
+		const cookies$1 = response.headers.getSetCookie();
+		for (const cookieHeader of cookies$1) if (domain) {
+			const parsedCookies = parseSetCookies(cookieHeader);
+			for (const parsedCookie of parsedCookies) {
+				parsedCookie.domain = domain;
+				headers$1.append("Set-Cookie", serializeSetCookie(parsedCookie));
+			}
+		} else headers$1.append("Set-Cookie", cookieHeader);
+	} else {
+		const value = response.headers.get(header);
+		if (value) headers$1.set(header, value);
+	}
+	return headers$1;
+};
+async function mintSessionData(headers$1, baseUrl, cookieConfig) {
+	const { secret, sessionDataTtl, domain } = cookieConfig;
+	const sessionToken = headers$1.getSetCookie().find((cookie) => cookie.includes("session_token"));
+	if (!sessionToken) return null;
+	if (sessionToken.toLowerCase().includes("max-age=0")) return serializeSetCookie({
+		name: NEON_AUTH_SESSION_DATA_COOKIE_NAME,
+		value: "",
+		path: "/",
+		domain,
+		httpOnly: true,
+		secure: true,
+		sameSite: "lax",
+		maxAge: 0
+	});
+	try {
+		const sessionData = await fetchSessionWithCookie(sessionToken, baseUrl);
+		if (sessionData.session) {
+			const { value: signedData, expiresAt } = await signSessionDataCookie(sessionData, secret, sessionDataTtl);
+			return serializeSetCookie({
+				name: NEON_AUTH_SESSION_DATA_COOKIE_NAME,
+				value: signedData,
+				path: "/",
+				domain,
+				httpOnly: true,
+				secure: true,
+				sameSite: "lax",
+				maxAge: Math.floor((expiresAt.getTime() - Date.now()) / 1e3)
+			});
+		}
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		const errorContext = {
+			error: errorMessage,
+			setCookieHeaderLength: sessionToken?.length || 0
+		};
+		if (errorMessage.includes("session_token not found")) console.warn("[mintSessionData] Session token missing in set-cookie:", errorContext);
+		else if (errorMessage.includes("Failed to fetch session data")) console.error("[mintSessionData] Upstream /get-session request failed:", errorContext);
+		else if (errorMessage.includes("NEON_AUTH_COOKIE_SECRET")) console.error("[mintSessionData] Cookie secret configuration error:", errorContext);
+		else if (errorMessage.includes("Invalid date")) console.error("[mintSessionData] Date parsing error:", errorContext);
+		else console.error("[mintSessionData] Unexpected error:", {
+			...errorContext,
+			...process.env.NODE_ENV !== "production" && { stack: error instanceof Error ? error.stack : void 0 }
+		});
+	}
+	return null;
+}
+async function fetchSessionWithCookie(setCookieHeader, baseUrl) {
+	const sessionToken = parseSetCookies(setCookieHeader).find((c) => c.name.includes("session_token"));
+	if (!sessionToken) throw new Error("session_token not found in set-cookie header");
+	const response = await fetch(`${baseUrl}/get-session`, {
+		headers: { Cookie: `${sessionToken.name}=${sessionToken.value}` },
+		signal: AbortSignal.timeout(3e3)
+	});
+	if (!response.ok) throw new Error(`Failed to fetch session data: ${response.status} ${response.statusText}`);
+	let body;
+	try {
+		body = await response.json();
+	} catch (error) {
+		throw new Error(`Failed to parse /get-session response as JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return parseSessionData(body);
+}
+
+//#endregion
+//#region src/server/session/cache-handler.ts
+/**
+* Attempts to retrieve session data from cookie cache
+* Returns Response with session data if cache hit, null otherwise
+*
+* This is the framework-agnostic session cache optimization used by API handlers.
+*
+* @param request - Standard Web API Request object
+* @param cookieSecret - Secret for validating signed session cookies
+* @returns Response with session data JSON if cache hit, null if miss/disabled
+*/
+async function trySessionCache(request, cookieSecret) {
+	if (new URL(request.url).searchParams.get("disableCookieCache") === "true") return null;
+	if (!(request.headers.get("cookie") || "").includes(NEON_AUTH_SESSION_COOKIE_NAME)) return null;
+	try {
+		const sessionData = await getSessionDataFromCookie(request, NEON_AUTH_SESSION_DATA_COOKIE_NAME, cookieSecret);
+		if (sessionData && sessionData.session) return Response.json(sessionData);
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		const errorName = error instanceof Error ? error.name : "Unknown";
+		if (errorName === "JWTExpired") console.debug("[trySessionCache] Session cookie expired (expected):", {
+			error: errorMessage,
+			errorType: errorName,
+			url: request.url
+		});
+		else if (errorName === "JWTInvalid" || errorName === "JWTClaimValidationFailed") console.warn("[trySessionCache] Invalid session cookie (possible tampering):", {
+			error: errorMessage,
+			errorType: errorName,
+			url: request.url
+		});
+		else console.error("[trySessionCache] Unexpected cookie validation error:", {
+			error: errorMessage,
+			errorType: errorName,
+			url: request.url
+		});
+	}
+	return null;
+}
+
+//#endregion
+//#region src/server/proxy/handler.ts
+/**
+* Generic authentication proxy handler (framework-agnostic)
+*
+* Handles the complete flow:
+* 1. Check if request is for getSession endpoint
+* 2. Try session cache if applicable (< 1ms fast path)
+* 3. Call upstream Neon Auth API
+* 4. Handle response with cookie minting
+*
+* This is framework-agnostic and can be used by any server framework.
+*
+* @param config - Proxy configuration
+* @returns Standard Web API Response
+*/
+async function handleAuthProxyRequest(config) {
+	const { request, path, baseUrl, cookieSecret, sessionDataTtl, domain } = config;
+	if (path === API_ENDPOINTS.getSession.path && request.method === API_ENDPOINTS.getSession.method) {
+		const cachedResponse = await trySessionCache(request, cookieSecret);
+		if (cachedResponse) return cachedResponse;
+	}
+	return await handleAuthResponse(await handleAuthRequest(baseUrl, request, path), baseUrl, {
+		secret: cookieSecret,
+		sessionDataTtl,
+		domain
+	});
+}
+
+//#endregion
+//#region src/server/client-factory.ts
+function createAuthServerInternal(config) {
+	const { baseUrl, context: getContext, cookieSecret, sessionDataTtl, domain } = config;
+	const fetchWithAuth = async (path, method, args) => {
+		const ctx = await getContext();
+		const cookies$1 = await ctx.getCookies();
+		const origin = await ctx.getOrigin();
+		const framework = ctx.getFramework();
+		const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+		const { query, fetchOptions: _fetchOptions, ...body } = args || {};
+		if (query && typeof query === "object") {
+			const queryParams = query;
+			for (const [key, value] of Object.entries(queryParams)) if (value !== void 0 && value !== null) url.searchParams.set(key, String(value));
+		}
+		const headers$1 = {
+			Cookie: cookies$1,
+			Origin: origin,
+			[NEON_AUTH_SERVER_PROXY_HEADER]: framework
+		};
+		let requestBody;
+		if (method === "POST") {
+			headers$1["Content-Type"] = "application/json";
+			requestBody = JSON.stringify(Object.keys(body).length > 0 ? body : {});
+		}
+		const response = await fetch(url.toString(), {
+			method,
+			headers: headers$1,
+			body: requestBody
+		});
+		const setCookieHeaders = response.headers.getSetCookie();
+		if (setCookieHeaders.length > 0) {
+			for (const setCookieHeader of setCookieHeaders) {
+				const parsedCookies = parseSetCookies(setCookieHeader);
+				for (const cookie of parsedCookies) {
+					const cookieOptions = domain ? {
+						...cookie,
+						domain
+					} : cookie;
+					await ctx.setCookie(cookie.name, cookie.value, cookieOptions);
+				}
+			}
+			try {
+				const sessionDataCookie = await mintSessionData(response.headers, baseUrl, {
+					secret: cookieSecret,
+					sessionDataTtl,
+					domain
+				});
+				if (sessionDataCookie) {
+					const [parsedSessionData] = parseSetCookies(sessionDataCookie);
+					if (parsedSessionData) await ctx.setCookie(parsedSessionData.name, parsedSessionData.value, parsedSessionData);
+				}
+			} catch (error) {
+				console.error("[fetchWithAuth] Failed to mint session data cookie:", error);
+			}
+		}
+		const responseData = await response.json().catch(() => null);
+		if (!response.ok) return {
+			data: null,
+			error: {
+				message: responseData?.message || response.statusText,
+				status: response.status,
+				statusText: response.statusText
+			}
+		};
+		return {
+			data: responseData,
+			error: null
+		};
+	};
+	const baseServer = createApiProxy(API_ENDPOINTS, fetchWithAuth);
+	const originalGetSession = baseServer.getSession;
+	baseServer.getSession = async (...args) => {
+		const [data] = args;
+		if (!(data?.query?.disableCookieCache === "true")) try {
+			const cookiesString = await (await getContext()).getCookies();
+			const hasSessionToken = cookiesString.includes(NEON_AUTH_SESSION_COOKIE_NAME);
+			const sessionDataCookie = parseCookieValue(cookiesString, NEON_AUTH_SESSION_DATA_COOKIE_NAME);
+			if (sessionDataCookie && hasSessionToken) {
+				const result = await validateSessionData(sessionDataCookie, cookieSecret);
+				if (result.valid && result.payload) return {
+					data: result.payload,
+					error: null
+				};
+			}
+		} catch (error) {
+			console.error("[auth.getSession] Cookie validation error:", error);
+		}
+		return originalGetSession(...args);
+	};
+	return baseServer;
+}
+function isEndpointConfig(value) {
+	return typeof value === "object" && value !== null && "path" in value && "method" in value;
+}
+function createApiProxy(endpoints, fetchFn) {
+	return new Proxy({}, {
+		get(target, prop) {
+			if (prop in target) return target[prop];
+			const endpoint = endpoints[prop];
+			if (!endpoint) return;
+			if (isEndpointConfig(endpoint)) return (args) => fetchFn(endpoint.path, endpoint.method, args);
+			return createApiProxy(endpoint, fetchFn);
+		},
+		set(target, prop, value) {
+			target[prop] = value;
+			return true;
+		}
+	});
+}
+
+//#endregion
+//#region src/next/server/adapter.ts
+/**
+* Creates a Next.js-specific RequestContext that reads cookies and headers
+* from next/headers and handles cookie setting.
+*/
+async function createNextRequestContext() {
+	const cookieStore = await cookies();
+	const headerStore = await headers();
+	return {
+		getCookies() {
+			return extractNeonAuthCookies(headerStore);
+		},
+		setCookie(name, value, options) {
+			cookieStore.set(name, value, options);
+		},
+		getHeader(name) {
+			return headerStore.get(name) ?? null;
+		},
+		getOrigin() {
+			return headerStore.get("origin") || headerStore.get("referer")?.split("/").slice(0, 3).join("/") || "";
+		},
+		getFramework() {
+			return "nextjs";
+		}
+	};
+}
+
+//#endregion
+//#region src/server/config.ts
+/**
+* Framework-agnostic configuration types for Neon Auth
+*/
+/**
+* Validates cookie configuration meets security requirements
+* @param cookies - The cookie configuration to validate
+* @throws Error if secret is too short (< 32 characters)
+*/
+function validateCookieConfig(cookies$1) {
+	if (!cookies$1.secret) throw new Error(ERRORS.MISSING_COOKIE_SECRET);
+	if (cookies$1.secret.length < 32) throw new Error(ERRORS.COOKIE_SECRET_TOO_SHORT);
+	if (cookies$1.sessionDataTtl !== void 0 && cookies$1.sessionDataTtl <= 0) throw new Error(ERRORS.INVALID_SESSION_DATA_TTL);
+}
+
+//#endregion
+//#region src/next/server/handler.ts
+/**
+* An API route handler to handle the auth requests from the client and proxy them to the Neon Auth.
+*
+* @param config - Required configuration
+* @param config.baseUrl - Base URL of your Neon Auth instance
+* @param config.cookies - Cookie configuration
+* @param config.cookies.secret - Secret for signing session cookies (minimum 32 characters)
+* @param config.cookies.sessionDataTtl - Optional TTL for session cache in seconds (default: 300)
+* @returns A Next.js API handler functions that can be used in a Next.js route.
+* @throws Error if `cookies.secret` is less than 32 characters
+*
+* @example
+* Mount the `authApiHandler` to an API route. Create a route file inside `/api/auth/[...all]/route.ts` directory.
+* And add the following code:
+*
+* ```ts
+* // app/api/auth/[...all]/route.ts
+* import { authApiHandler } from '@neondatabase/auth/next';
+*
+* export const { GET, POST } = authApiHandler({
+*   baseUrl: process.env.NEON_AUTH_BASE_URL!,
+*   cookies: {
+*     secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+*   },
+* });
+* ```
+*/
+function authApiHandler(config) {
+	const { baseUrl, cookies: cookies$1 } = config;
+	validateCookieConfig(cookies$1);
+	const handler = async (request, { params }) => {
+		return handleAuthProxyRequest({
+			request,
+			path: (await params).path.join("/"),
+			baseUrl,
+			cookieSecret: cookies$1.secret,
+			sessionDataTtl: cookies$1.sessionDataTtl,
+			domain: cookies$1.domain
+		});
+	};
+	return {
+		GET: handler,
+		POST: handler,
+		PUT: handler,
+		DELETE: handler,
+		PATCH: handler
+	};
+}
+
+//#endregion
+//#region src/server/middleware/oauth.ts
+/**
+* Checks if the current request needs OAuth session verification
+* This happens when returning from OAuth provider with a verifier token
+*
+* @param request - Standard Web API Request object
+* @returns true if session verification is needed
+*/
+function needsSessionVerification(request) {
+	const hasVerifier = new URL(request.url).searchParams.has(NEON_AUTH_SESSION_VERIFIER_PARAM_NAME);
+	const cookieHeader = request.headers.get("cookie");
+	if (!cookieHeader) return false;
+	const hasChallenge = parseCookies(cookieHeader).has(NEON_AUTH_SESSION_CHALLENGE_COOKIE_NAME);
+	return hasVerifier && hasChallenge;
+}
+/**
+* Exchanges OAuth verifier token for session cookie
+* This completes the OAuth flow by verifying the session challenge
+*
+* @param request - Standard Web API Request object
+* @param baseUrl - Base URL of Neon Auth server
+* @param cookieSecret - Secret for signing session cookies
+* @param sessionDataTtl - Optional TTL for session data cache
+* @param domain - Optional cookie domain
+* @returns Exchange result with redirect URL and cookies, or null if exchange not needed/failed
+*/
+async function exchangeOAuthToken(request, baseUrl, cookieSecret, sessionDataTtl, domain) {
+	const url = new URL(request.url);
+	const verifier = url.searchParams.get(NEON_AUTH_SESSION_VERIFIER_PARAM_NAME);
+	const cookieHeader = request.headers.get("cookie");
+	if (!cookieHeader) return null;
+	const challenge = parseCookies(cookieHeader).get(NEON_AUTH_SESSION_CHALLENGE_COOKIE_NAME);
+	if (!verifier || !challenge) return null;
+	const response = await handleAuthResponse(await handleAuthRequest(baseUrl, new Request(request.url, {
+		method: "GET",
+		headers: request.headers
+	}), "get-session"), baseUrl, {
+		secret: cookieSecret,
+		sessionDataTtl,
+		domain
+	});
+	if (response.ok) {
+		const setCookieHeaders = response.headers.getSetCookie();
+		url.searchParams.delete(NEON_AUTH_SESSION_VERIFIER_PARAM_NAME);
+		return {
+			redirectUrl: url,
+			cookies: setCookieHeaders,
+			success: true
+		};
+	}
+	return null;
+}
+
+//#endregion
+//#region src/server/middleware/route-protection.ts
+/**
+* Checks if a given pathname should be protected (require authentication)
+*
+* @param pathname - URL pathname to check
+* @param skipRoutes - Array of route prefixes to skip protection
+* @returns true if route should be protected, false if it should be skipped
+*/
+function shouldProtectRoute(pathname, skipRoutes) {
+	return !skipRoutes.some((route) => pathname.startsWith(route));
+}
+/**
+* Checks if the current request requires a valid session
+* Returns result indicating if request should proceed, redirect, or continue
+*
+* @param pathname - URL pathname being accessed
+* @param skipRoutes - Routes that don't require authentication
+* @param loginUrl - URL to redirect to for login (if applicable)
+* @param session - Current session data (null if not authenticated)
+* @returns Session check result
+*/
+function checkSessionRequired(pathname, skipRoutes, loginUrl, session) {
+	if (pathname.startsWith(loginUrl)) return {
+		allowed: true,
+		requiresRedirect: false
+	};
+	if (!shouldProtectRoute(pathname, skipRoutes)) return {
+		allowed: true,
+		requiresRedirect: false
+	};
+	if (!session || session.session === null) return {
+		allowed: false,
+		requiresRedirect: true
+	};
+	return {
+		allowed: true,
+		session,
+		requiresRedirect: false
+	};
+}
+
+//#endregion
+//#region src/server/middleware/processor.ts
+/**
+* Generic authentication middleware processor (framework-agnostic)
+*
+* Handles the complete middleware flow:
+* 1. Check if login URL (skip auth)
+* 2. Check OAuth verification (exchange token)
+* 3. Get session (delegates to handleAuthProxyRequest for cookie cache + upstream fallback)
+* 4. Check if route requires protection
+* 5. Return decision object
+*
+* This is framework-agnostic - it returns a decision, NOT a framework-specific response.
+* The calling framework converts the decision to its response type (NextResponse, etc.)
+*
+* @param config - Middleware configuration
+* @returns Decision object indicating what action to take
+*/
+async function processAuthMiddleware(config) {
+	const { request, pathname, skipRoutes, loginUrl, baseUrl, cookieSecret, sessionDataTtl, domain } = config;
+	if (pathname.startsWith(loginUrl)) return { action: "allow" };
+	if (needsSessionVerification(request)) {
+		const exchangeResult = await exchangeOAuthToken(request, baseUrl, cookieSecret, sessionDataTtl, domain);
+		if (exchangeResult !== null) return {
+			action: "redirect_oauth",
+			redirectUrl: exchangeResult.redirectUrl,
+			cookies: exchangeResult.cookies
+		};
+	}
+	const cookieHeader = request.headers.get("cookie") || "";
+	const hasSessionToken = cookieHeader.includes(NEON_AUTH_SESSION_COOKIE_NAME);
+	const hasStaleSessionData = parseCookies(cookieHeader).has(NEON_AUTH_SESSION_DATA_COOKIE_NAME) && !hasSessionToken;
+	let sessionData = {
+		session: null,
+		user: null
+	};
+	if (hasSessionToken) {
+		const sessionResponse = await handleAuthProxyRequest({
+			request,
+			path: "get-session",
+			baseUrl,
+			cookieSecret,
+			sessionDataTtl,
+			domain
+		});
+		if (sessionResponse.ok) {
+			const data = await sessionResponse.json().catch(() => null);
+			if (data) sessionData = data;
+		}
+	}
+	if (checkSessionRequired(pathname, skipRoutes, loginUrl, sessionData).allowed) return {
+		action: "allow",
+		headers: { [NEON_AUTH_HEADER_MIDDLEWARE_NAME]: "true" }
+	};
+	const cookies$1 = [];
+	if (hasStaleSessionData) cookies$1.push(serializeSetCookie({
+		name: NEON_AUTH_SESSION_DATA_COOKIE_NAME,
+		value: "",
+		path: "/",
+		domain,
+		httpOnly: true,
+		secure: true,
+		sameSite: "lax",
+		maxAge: 0
+	}));
+	return {
+		action: "redirect_login",
+		redirectUrl: new URL(loginUrl, request.url),
+		cookies: cookies$1.length > 0 ? cookies$1 : void 0
+	};
+}
+
+//#endregion
+//#region src/next/server/middleware.ts
+const SKIP_ROUTES = [
+	"/api/auth",
+	"/auth/callback",
+	"/auth/sign-in",
+	"/auth/sign-up",
+	"/auth/magic-link",
+	"/auth/email-otp",
+	"/auth/forgot-password"
+];
+/**
+* A Next.js middleware to protect routes from unauthenticated requests and refresh the session if required.
+*
+* @param config - Required middleware configuration
+* @param config.baseUrl - Base URL of your Neon Auth instance
+* @param config.cookies - Cookie configuration
+* @param config.cookies.secret - Secret for signing session cookies (minimum 32 characters)
+* @param config.cookies.sessionDataTtl - Optional TTL for session cache in seconds (default: 300)
+* @param config.loginUrl - The URL to redirect to when the user is not authenticated (default: '/auth/sign-in')
+* @returns A middleware function that can be used in the Next.js app.
+* @throws Error if `cookies.secret` is less than 32 characters
+*
+* @example
+* ```ts
+* import { neonAuthMiddleware } from "@neondatabase/auth/next"
+*
+* export default neonAuthMiddleware({
+*   baseUrl: process.env.NEON_AUTH_BASE_URL!,
+*   cookies: {
+*     secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+*   },
+*   loginUrl: '/auth/sign-in',
+* });
+* ```
+*/
+function neonAuthMiddleware(config) {
+	const { baseUrl, cookies: cookies$1, loginUrl = "/auth/sign-in" } = config;
+	validateCookieConfig(cookies$1);
+	return async (request) => {
+		const pathname = request.nextUrl.pathname;
+		const result = await processAuthMiddleware({
+			request,
+			pathname,
+			skipRoutes: SKIP_ROUTES,
+			loginUrl,
+			baseUrl,
+			cookieSecret: cookies$1.secret,
+			sessionDataTtl: cookies$1.sessionDataTtl,
+			domain: cookies$1.domain
+		});
+		switch (result.action) {
+			case "allow": {
+				const headers$1 = new Headers(request.headers);
+				if (result.headers) for (const [key, value] of Object.entries(result.headers)) headers$1.set(key, value);
+				return NextResponse.next({ request: { headers: headers$1 } });
+			}
+			case "redirect_oauth": {
+				const oauthHeaders = new Headers();
+				for (const cookie of result.cookies) oauthHeaders.append("Set-Cookie", cookie);
+				return NextResponse.redirect(result.redirectUrl, { headers: oauthHeaders });
+			}
+			case "redirect_login":
+				if (result.cookies && result.cookies.length > 0) {
+					const loginHeaders = new Headers();
+					for (const cookie of result.cookies) loginHeaders.append("Set-Cookie", cookie);
+					return NextResponse.redirect(result.redirectUrl, { headers: loginHeaders });
+				}
+				return NextResponse.redirect(result.redirectUrl);
+		}
+	};
+}
+
+//#endregion
+//#region src/next/server/index.ts
+/**
+* Unified entry point for Neon Auth in Next.js
+*
+* This is the recommended way to use Neon Auth in Next.js. It provides a single
+* entry point that combines all server-side functionality.
+*
+* **Features:**
+* - All Better Auth server methods (signIn, signUp, getSession, etc.)
+* - `.handler()` - API route handler for `/api/auth/[...path]`
+* - `.middleware(config?)` - Middleware for route protection
+*
+* **Where to use:**
+* - React Server Components
+* - Server Actions
+* - Route Handlers
+* - Middleware
+*
+* @param config - Required configuration
+* @param config.baseUrl - Base URL of your Neon Auth instance
+* @param config.cookies - Cookie configuration
+* @param config.cookies.secret - Secret for signing session cookies (minimum 32 characters)
+* @param config.cookies.sessionDataTtl - Optional TTL for session cache in seconds (default: 300)
+* @param config.cookies.domain - Optional cookie domain (default: current domain)
+* @returns Unified auth instance with server methods, handler, and middleware
+* @throws Error if `cookies.secret` is less than 32 characters
+*
+* @example
+* ```typescript
+* // lib/auth.ts - Create a singleton instance
+* import { createNeonAuth } from '@neondatabase/auth/next/server';
+*
+* export const auth = createNeonAuth({
+*   baseUrl: process.env.NEON_AUTH_BASE_URL!,
+*   cookies: {
+*     secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+*     sessionDataTtl: 300, // 5 minutes (default)
+*   },
+* });
+* ```
+*
+* @example
+* ```typescript
+* // app/api/auth/[...path]/route.ts - API handler
+* import { auth } from '@/lib/auth';
+*
+* export const { GET, POST } = auth.handler();
+* ```
+*
+* @example
+* ```typescript
+* // middleware.ts - Route protection
+* import { auth } from '@/lib/auth';
+*
+* export default auth.middleware({ loginUrl: '/auth/sign-in' });
+*
+* export const config = {
+*   matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+* };
+* ```
+*
+* @example
+* ```typescript
+* // app/page.tsx - Server Component
+* import { auth } from '@/lib/auth';
+*
+* // Server components using `auth` methods must be rendered dynamically
+* export const dynamic = 'force-dynamic'
+*
+* export default async function Page() {
+*   const { data: session } = await auth.getSession();
+*   if (!session?.user) return <div>Not logged in</div>;
+*   return <div>Hello {session.user.name}</div>;
+* }
+* ```
+*
+* @example
+* ```typescript
+* // app/actions.ts - Server Action
+* 'use server';
+* import { auth } from '@/lib/auth';
+* import { redirect } from 'next/navigation';
+*
+* export async function signIn(formData: FormData) {
+*   const { error } = await auth.signIn.email({
+*     email: formData.get('email') as string,
+*     password: formData.get('password') as string,
+*   });
+*   if (error) return { error: error.message };
+*   redirect('/dashboard');
+* }
+* ```
+*/
+function createNeonAuth(config) {
+	const { baseUrl, cookies: cookies$1 } = config;
+	validateCookieConfig(cookies$1);
+	const server = createAuthServerInternal({
+		baseUrl,
+		context: createNextRequestContext,
+		cookieSecret: cookies$1.secret,
+		sessionDataTtl: cookies$1.sessionDataTtl,
+		domain: cookies$1.domain
+	});
+	/**
+	* Creates API route handlers for Next.js
+	*
+	* Mount this in your API routes to handle auth requests:
+	* - `/api/auth/[...path]/route.ts`
+	*
+	* @returns Object with GET, POST, PUT, DELETE, PATCH handlers
+	*
+	* @example
+	* ```typescript
+	* // app/api/auth/[...path]/route.ts
+	* import { auth } from '@/lib/auth';
+	*
+	* export const { GET, POST } = auth.handler();
+	* ```
+	*/
+	server.handler = () => authApiHandler(config);
+	/**
+	* Creates middleware for route protection
+	*
+	* Protects routes from unauthenticated access and handles:
+	* - Session validation and refresh
+	* - OAuth callback processing
+	* - Login redirects
+	*
+	* @param middlewareConfig - Optional middleware configuration
+	* @param middlewareConfig.loginUrl - URL to redirect to when not authenticated (default: '/auth/sign-in')
+	* @returns Middleware function for Next.js
+	*
+	* @example
+	* ```typescript
+	* // middleware.ts
+	* import { auth } from '@/lib/auth';
+	*
+	* export default auth.middleware({ loginUrl: '/auth/sign-in' });
+	*
+	* export const config = {
+	*   matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+	* };
+	* ```
+	*/
+	server.middleware = (middlewareConfig) => neonAuthMiddleware({
+		...config,
+		...middlewareConfig
+	});
+	return server;
+}
+
+//#endregion
+export { createNeonAuth };