@henosia/app-next 1.0.2

package/dist/auth/middleware.mjs

@@ -0,0 +1,152 @@
+/*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
+import { HENOSIA_AUTH_SIGN_IN_PATH_NAME, HENOSIA_ORGANIZATION_CTX_COOKIE } from "../shared.mjs";
+import { HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, cookiePrefix, henosiaAuthConfig, isPageRequest, isUnauthorizedException, verifyHenosiaAuthToken } from "./server.mjs";
+import { getSessionCookie } from "better-auth/cookies";
+import { NextResponse } from "next/server.js";
+//#region src/auth/utils.ts
+function delayWithCancel(delayMs) {
+	let timer;
+	let reject = null;
+	const promise = new Promise((resolve, _reject) => {
+		reject = _reject;
+		timer = setTimeout(() => resolve(), delayMs);
+	});
+	const cancel = () => {
+		clearTimeout(timer);
+		queueMicrotask(() => {
+			reject();
+			reject = null;
+		});
+	};
+	return {
+		promise,
+		cancel
+	};
+}
+//#endregion
+//#region src/auth/middleware.ts
+/**
+* Creates a Next.js middleware function that performs the Henosia Auth pre-check.
+*
+* The returned function:
+* - Returns a redirect to the sign-in page when no valid session cookie is present.
+* - Verifies the Henosia Auth JWT, transferring any refreshed cookies onto the response.
+* - Optionally exchanges the Henosia Auth token for a Supabase session if `NEXT_PUBLIC_SUPABASE_URL` is set.
+* - Returns the resulting `NextResponse` (a `NextResponse.next({ request })` when authenticated, a redirect or
+*   401 JSON response otherwise) so the caller can compose additional logic on top.
+*
+* **Important**: this middleware performs an auth *pre-check*. Authorization MUST still be performed at the
+* relevant pages and route handlers using {@link verifyHenosiaAuthToken}.
+*
+* @example Composing with custom logic
+* ```ts
+* import { type NextRequest, NextResponse } from 'next/server'
+* import { createHenosiaAuthMiddleware } from '@henosia/app-next/middleware'
+*
+* const henosiaAuth = createHenosiaAuthMiddleware()
+*
+* export async function middleware(request: NextRequest) {
+*   // Add app-specific logic here ...
+*   return await henosiaAuth(request)
+* }
+*
+* ```
+*/
+function createHenosiaAuthMiddleware(options = {}) {
+	const unauthenticatedPathNames = new Set([...HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, ...options.additionalUnauthenticatedPathNames ?? []]);
+	const unauthenticatedPathNamePrefixes = [...HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, ...options.additionalUnauthenticatedPathNamePrefixes ?? []];
+	if (unauthenticatedPathNamePrefixes.find((p) => p === "/" || !p.trim() || !p.endsWith("/"))) throw new Error("[Henosia Auth] Invalid path name prefixes in additionalUnauthenticatedPathNamePrefixes. Values must be non-empty sub paths ending with slash");
+	if (unauthenticatedPathNames.has("/")) throw new Error(`[Henosia Auth] Invalid path name '/' in additionalUnauthenticatedPathNames. Values must be non-root paths`);
+	return async function henosiaAuthMiddleware(request) {
+		const response = NextResponse.next({ request });
+		const { pathname } = request.nextUrl;
+		if (pathname === "/sign-in") removeCachedAccountData(response);
+		if (pathname === "/api/auth/get-session") {
+			try {
+				const { transferBetterAuthCookiesToNext } = await verifyHenosiaAuthToken(request);
+				transferBetterAuthCookiesToNext(request, response);
+			} catch (e) {
+				if (!isUnauthorizedException(e)) {
+					console.error("[Middleware]", e);
+					throw e;
+				}
+			}
+			return response;
+		}
+		if (unauthenticatedPathNames.has(pathname) || !!unauthenticatedPathNamePrefixes.find((p) => pathname.startsWith(p))) return response;
+		if (!getSessionCookie(request, { cookiePrefix })) return NextResponse.redirect(new URL(HENOSIA_AUTH_SIGN_IN_PATH_NAME, request.url));
+		try {
+			const { accessTokenResponse, payload, transferBetterAuthCookiesToNext } = await verifyHenosiaAuthToken(request);
+			transferBetterAuthCookiesToNext(request, response);
+			const cachedOrg = JSON.stringify(request.cookies.get("henosia.org")?.value ?? null);
+			const org = JSON.stringify(payload["https://henosia.com/organization"]);
+			if (cachedOrg !== org) response.cookies.set(HENOSIA_ORGANIZATION_CTX_COOKIE, org);
+			if (process.env.NEXT_PUBLIC_SUPABASE_URL) await exchangeHenosiaTokenForSupabaseSession(request, response, accessTokenResponse.idToken);
+		} catch (e) {
+			if (isUnauthorizedException(e)) {
+				if (!isPageRequest(request)) return NextResponse.json({ error: "Your session is invalid or expired. Please reload the page to sign in again." }, { status: e.statusCode ?? 401 });
+				const redirectResponse = NextResponse.redirect(new URL(HENOSIA_AUTH_SIGN_IN_PATH_NAME, request.url));
+				removeCachedAccountData(redirectResponse);
+				return redirectResponse;
+			} else {
+				console.error("[Middleware]", e);
+				throw e;
+			}
+		}
+		return response;
+	};
+}
+/**
+* Lazy-load `@supabase/ssr` so apps that don't use Supabase don't have to install it.
+*/
+async function exchangeHenosiaTokenForSupabaseSession(request, response, idToken) {
+	let createServerClient;
+	try {
+		({createServerClient} = await import("@supabase/ssr"));
+	} catch (e) {
+		console.error("[Henosia Auth] NEXT_PUBLIC_SUPABASE_URL is set but `@supabase/ssr` is not installed. Install it as a peer dependency to enable Supabase session exchange.", e);
+		return;
+	}
+	const supabase = createServerClient(process.env.NEXT_PUBLIC_SUPABASE_URL, process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, { cookies: {
+		getAll() {
+			return request.cookies.getAll();
+		},
+		setAll(cookiesToSet) {
+			cookiesToSet.forEach(({ name, value }) => request.cookies.set(name, value));
+			try {
+				cookiesToSet.forEach(({ name, value, options }) => response.cookies.set(name, value, options));
+			} catch {}
+		}
+	} });
+	const { promise: supabaseTimeout, cancel } = delayWithCancel(5e3);
+	await Promise.race([supabaseTimeout.then(() => {
+		console.error(`[Supabase] Timed out getting a valid Supabase session: ${process.env.NEXT_PUBLIC_SUPABASE_URL} may be paused or down.`);
+	}), (async () => {
+		try {
+			const { data } = await supabase.auth.getSession();
+			if (!data.session) await supabase.auth.signInWithIdToken({
+				provider: henosiaAuthConfig.henosiaAuthSupabaseProvider.get(),
+				token: idToken
+			});
+		} catch (error) {
+			console.error("[Supabase] Unable to get valid Supabase session", error);
+		} finally {
+			cancel();
+		}
+	})()]);
+}
+/**
+* Removes potentially invalid cached account data from cookies before the next better-auth sign in attempt
+*/
+function removeCachedAccountData(response) {
+	const secure = henosiaAuthConfig.baseURL.get().startsWith("https");
+	const name = `${secure ? "__Secure-" : ""}${cookiePrefix}.account_data`;
+	response.cookies.delete({
+		name,
+		secure,
+		httpOnly: true,
+		domain: new URL(henosiaAuthConfig.baseURL.get()).hostname
+	});
+}
+//#endregion
+export { createHenosiaAuthMiddleware };

package/dist/auth/server.d.mts

@@ -0,0 +1,108 @@
+
+import { HenosiaOrganizationContext } from "../shared.mjs";
+import { Auth } from "better-auth";
+import { NextRequest, NextResponse } from "next/server.js";
+
+//#region src/auth/server.d.ts
+/**
+ * URL pathname values that should not check for auth in middleware, e.g. the sign-in page.
+ * Additional pathname values can be added for public paths, but ONLY if they should not be intercepted by the
+ * middleware auth pre-check and redirect.
+ */
+declare const HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES: Set<string>;
+/**
+ * URL pathname prefixes that should not be blocked by auth in middleware, e.g. the better-auth API routes used to sign in.
+ * Additional pathname prefixes can be added for public paths, but ONLY if they should not be intercepted by the
+ * middleware auth pre-check and redirect. Include the relevant `/` ending character to prevent unexpected partial
+ * route matches.
+ */
+declare const HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES: string[];
+type EnvLiveGetString = {
+  get(): string;
+};
+interface HenosiaAuthConfig {
+  /** Name of the Henosia Auth OAuth2 provider */
+  provider: 'henosia';
+  /** The consuming app's own deployment or preview browser URL. Used as the better-auth base url */
+  baseURL: EnvLiveGetString;
+  /** The consuming app's own deployment or preview auth secret. Used as the better-auth secret */
+  secret: EnvLiveGetString;
+  /** OAuth client ID from HenosiaAuthClientService */
+  clientId: EnvLiveGetString;
+  /** OAuth client secret from HenosiaAuthClientService */
+  clientSecret: EnvLiveGetString;
+  /** The Henosia auth and platform service base URL, under which the OAuth client is registered */
+  henosiaAuthPlatformServiceBaseUrl: EnvLiveGetString;
+  /** The provider identifier that Henosia Auth is registered with as a OIDC-based Custom Provider in Supabase Auth */
+  henosiaAuthSupabaseProvider: EnvLiveGetString;
+  /**
+   * The project id that the JWT project claim should match in HenosiaAuthTokenClaims.
+   * Ensures that signed-in Henosia users cannot access projects that they have not been granted access to,
+   * for example that User A from Org A cannot access User B from Org B's project.
+   * */
+  projectId: EnvLiveGetString;
+}
+/**
+ * Environment-provided configuration for Henosia Auth.
+ * When the consuming app runs in the Henosia preview, the env vars are provided by the runtime environment and should not be
+ * hard-coded or present in the `.env.local` file. The Henosia Publish feature automatically sets production versions of
+ * the values on the deployed app. For self-publish flows or local development, see the `Environment settings`
+ * in the Henosia builder navbar for the relevant values. The preview values cannot be used for production deployments.
+ */
+declare const henosiaAuthConfig: HenosiaAuthConfig;
+interface HenosiaAuthTokenClaims {
+  /** The project id that the claim is associated with. A `null` value indicates no project access was granted. */
+  'https://henosia.com/project': string | null;
+  /** Whether the claim is associated with Henosia's preview browser in the builder */
+  'https://henosia.com/preview': boolean;
+  /** The organization that the app belongs to */
+  'https://henosia.com/organization': HenosiaOrganizationContext;
+}
+/**
+ * Gets whether the specified request is for a page (a top level page or iframe page)
+ */
+declare function isPageRequest(request: Request): boolean;
+/**
+ * Gets whether the specified request is allowed to spend the single-use OIDC refresh token to obtain a new
+ * access token.
+ *
+ */
+declare function isPageOrRefreshTokenRequest(request: Request): boolean;
+declare const cookiePrefix: `henosia-auth-${string}`;
+/**
+ * The Henosia Auth instance.
+ *
+ * Typed as the minimal {@link Auth} type from better-auth (which is parameterised on the default
+ * {@link BetterAuthOptions}) rather than the deeply-inferred concrete type returned by {@link betterAuth}.
+ * The deeply-inferred graph references non-portable internals from `better-auth` and `zod` that cannot be
+ * named in published declarations (TS2883).
+ */
+declare const auth: Auth;
+/**
+ * Verifies the Henosia Auth JWT on the current request, or throws in case it's missing or invalid.
+ * This method must be called before allowing access to any protected pages or routes,
+ * and before accessing data in server side page methods or actions.
+ * @param request the current request which provides auth headers
+ * @return the better-auth `getAccessToken` response, the verified token `payload` (a {@link HenosiaAuthTokenClaims}),
+ *         the `Set-Cookie` headers produced while obtaining/refreshing the token, and a
+ *         `transferBetterAuthCookiesToNext` helper that forwards those cookies onto a Next.js request/response pair
+ * @throws APIError when the current credentials are missing or invalid
+ */
+declare function verifyHenosiaAuthToken(request: Request): Promise<{
+  accessTokenResponse: {
+    accessToken: string;
+    accessTokenExpiresAt: Date | undefined;
+    scopes: string[];
+    idToken: string | undefined;
+  };
+  payload: HenosiaAuthTokenClaims;
+  setCookieHeaders: string[];
+  transferBetterAuthCookiesToNext: (nextRequest: NextRequest, response: NextResponse) => void;
+}>;
+/**
+ * Determines whether the specified exception should start the sign-in flow to authenticate the user
+ * @param error the error thrown by `verifyHenosiaAuthToken`
+ */
+declare function isUnauthorizedException(error: unknown): boolean;
+//#endregion
+export { HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, HenosiaAuthConfig, HenosiaAuthTokenClaims, auth, cookiePrefix, henosiaAuthConfig, isPageOrRefreshTokenRequest, isPageRequest, isUnauthorizedException, verifyHenosiaAuthToken };

package/dist/auth/server.mjs

@@ -0,0 +1,214 @@
+/*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
+import { HENOSIA_AUTH_GET_SESSION_PATH_NAME, HENOSIA_AUTH_SIGN_IN_PATH_NAME } from "../shared.mjs";
+import { APIError, betterAuth } from "better-auth";
+import { createAuthMiddleware } from "better-auth/api";
+import { bearer, genericOAuth, jwt } from "better-auth/plugins";
+import { nextCookies } from "better-auth/next-js";
+import { verifyAccessToken } from "better-auth/oauth2";
+import { parseSetCookieHeader } from "better-auth/cookies";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { headers } from "next/headers.js";
+//#region src/auth/server.ts
+/**
+* URL pathname values that should not check for auth in middleware, e.g. the sign-in page.
+* Additional pathname values can be added for public paths, but ONLY if they should not be intercepted by the
+* middleware auth pre-check and redirect.
+*/
+const HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES = new Set([HENOSIA_AUTH_SIGN_IN_PATH_NAME]);
+if (HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES.has("/")) throw new Error(`[Henosia Auth] Invalid path name '/'. Values must be non-root paths`);
+/**
+* URL pathname prefixes that should not be blocked by auth in middleware, e.g. the better-auth API routes used to sign in.
+* Additional pathname prefixes can be added for public paths, but ONLY if they should not be intercepted by the
+* middleware auth pre-check and redirect. Include the relevant `/` ending character to prevent unexpected partial
+* route matches.
+*/
+const HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES = ["/api/auth/", "/.well-known/"];
+if (HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES.find((p) => p === "/" || !p.trim() || !p.endsWith("/"))) throw new Error("[Henosia Auth] Invalid path name prefixes. Values must be non-empty sub paths ending with slash");
+const requiredEnvProxy = new Proxy(process.env, { get(target, property, receiver) {
+	const value = Reflect.get(target, property, receiver);
+	if (!value || typeof value !== "string") throw new Error(`[Henosia Auth] Missing required env var: ${property.toString()}`);
+	return value;
+} });
+function getRequiredEnvValue(getter, fallback) {
+	try {
+		return { get: () => getter(requiredEnvProxy) };
+	} catch (e) {
+		if (fallback) return { get: () => fallback };
+		console.log(e.message);
+		throw e;
+	}
+}
+/**
+* Environment-provided configuration for Henosia Auth.
+* When the consuming app runs in the Henosia preview, the env vars are provided by the runtime environment and should not be
+* hard-coded or present in the `.env.local` file. The Henosia Publish feature automatically sets production versions of
+* the values on the deployed app. For self-publish flows or local development, see the `Environment settings`
+* in the Henosia builder navbar for the relevant values. The preview values cannot be used for production deployments.
+*/
+const henosiaAuthConfig = {
+	provider: "henosia",
+	baseURL: getRequiredEnvValue((env) => env.BETTER_AUTH_URL),
+	secret: getRequiredEnvValue((env) => env.BETTER_AUTH_SECRET),
+	henosiaAuthPlatformServiceBaseUrl: getRequiredEnvValue((env) => env.HENOSIA_AUTH_SERVICE_BASE_URL),
+	henosiaAuthSupabaseProvider: getRequiredEnvValue((env) => env.HENOSIA_AUTH_SUPABASE_PROVIDER, "custom:henosia-auth:platform"),
+	clientSecret: getRequiredEnvValue((env) => env.HENOSIA_AUTH_CLIENT_SECRET),
+	clientId: getRequiredEnvValue((env) => env.HENOSIA_AUTH_CLIENT_ID),
+	projectId: getRequiredEnvValue((env) => env.HENOSIA_AUTH_PROJECT_ID)
+};
+/**
+* Gets whether the specified request is for a page (a top level page or iframe page)
+*/
+function isPageRequest(request) {
+	const dest = request.headers.get("Sec-Fetch-Dest");
+	if (dest === "document" || dest === "iframe" || dest === "fencedframe") return true;
+	const isRsc = request.headers.get("RSC") === "1";
+	const isPrefetch = request.headers.get("Next-Router-Prefetch") === "1";
+	return isRsc && !isPrefetch;
+}
+/**
+* Gets whether the specified request is allowed to spend the single-use OIDC refresh token to obtain a new
+* access token.
+*
+*/
+function isPageOrRefreshTokenRequest(request) {
+	if (isPageRequest(request)) return true;
+	return new URL(request.url).pathname === HENOSIA_AUTH_GET_SESSION_PATH_NAME;
+}
+const currentRequestStorage = new AsyncLocalStorage();
+let henosiaOAuthProviderInitialized = false;
+const cookiePrefix = `henosia-auth-${henosiaAuthConfig.projectId.get()}`;
+const authInstance = betterAuth({
+	baseURL: henosiaAuthConfig.baseURL.get(),
+	secret: henosiaAuthConfig.secret.get(),
+	advanced: { cookiePrefix },
+	plugins: [
+		bearer(),
+		jwt(),
+		genericOAuth({ config: [{
+			providerId: henosiaAuthConfig.provider,
+			discoveryUrl: `${henosiaAuthConfig.henosiaAuthPlatformServiceBaseUrl.get()}/.well-known/openid-configuration`,
+			clientId: henosiaAuthConfig.clientId.get(),
+			clientSecret: henosiaAuthConfig.clientSecret.get(),
+			scopes: [
+				"openid",
+				"profile",
+				"email",
+				"offline_access"
+			],
+			pkce: true,
+			mapProfileToUser: (profile) => {
+				if (!profile.name) profile.name = profile.email;
+				return profile;
+			}
+		}] }),
+		nextCookies()
+	],
+	hooks: { before: createAuthMiddleware(async (ctx) => {
+		if (henosiaOAuthProviderInitialized) return;
+		for (const provider of ctx.context.socialProviders) {
+			const { refreshAccessToken } = provider;
+			if (!refreshAccessToken || provider.id !== henosiaAuthConfig.provider) continue;
+			provider.refreshAccessToken = async (refreshToken) => {
+				const request = currentRequestStorage.getStore();
+				if (!request) throw new APIError("INTERNAL_SERVER_ERROR", { message: `Expected a current request during refreshAccessToken` });
+				if (!isPageOrRefreshTokenRequest(request)) throw new APIError("UNAUTHORIZED", {
+					statusCode: 401,
+					message: "Fetching a refresh access token is only allowed for page or refresh token requests"
+				});
+				return await refreshAccessToken(refreshToken);
+			};
+			henosiaOAuthProviderInitialized = true;
+			break;
+		}
+	}) },
+	session: { cookieCache: {
+		enabled: true,
+		version: "1",
+		maxAge: 720 * 60 * 60,
+		strategy: "jwe",
+		refreshCache: true
+	} },
+	account: {
+		storeStateStrategy: "cookie",
+		storeAccountCookie: true
+	},
+	databaseHooks: { user: { create: { before: async (data) => {
+		const stableId = data.sub;
+		if (!stableId) throw new APIError("INTERNAL_SERVER_ERROR", { message: `Expected '.sub' to be defined but got '${stableId}' for '${data.email}'` });
+		return { data: {
+			...data,
+			id: stableId
+		} };
+	} } } },
+	trustedOrigins: [henosiaAuthConfig.henosiaAuthPlatformServiceBaseUrl.get()]
+});
+/**
+* The Henosia Auth instance.
+*
+* Typed as the minimal {@link Auth} type from better-auth (which is parameterised on the default
+* {@link BetterAuthOptions}) rather than the deeply-inferred concrete type returned by {@link betterAuth}.
+* The deeply-inferred graph references non-portable internals from `better-auth` and `zod` that cannot be
+* named in published declarations (TS2883).
+*/
+const auth = authInstance;
+/**
+* Verifies the Henosia Auth JWT on the current request, or throws in case it's missing or invalid.
+* This method must be called before allowing access to any protected pages or routes,
+* and before accessing data in server side page methods or actions.
+* @param request the current request which provides auth headers
+* @return the better-auth `getAccessToken` response, the verified token `payload` (a {@link HenosiaAuthTokenClaims}),
+*         the `Set-Cookie` headers produced while obtaining/refreshing the token, and a
+*         `transferBetterAuthCookiesToNext` helper that forwards those cookies onto a Next.js request/response pair
+* @throws APIError when the current credentials are missing or invalid
+*/
+async function verifyHenosiaAuthToken(request) {
+	currentRequestStorage.enterWith(request);
+	const { response: accessTokenResponse, headers: accessTokenResponseHeaders } = await authInstance.api.getAccessToken({
+		body: { providerId: henosiaAuthConfig.provider },
+		headers: await headers(),
+		returnHeaders: true
+	});
+	if (!accessTokenResponse.idToken) throw new APIError("UNAUTHORIZED", { message: "No id_token returned for openid scope" });
+	const payload = await verifyAccessToken(accessTokenResponse.idToken, {
+		jwksUrl: `${henosiaAuthConfig.henosiaAuthPlatformServiceBaseUrl.get()}/api/auth/jwks`,
+		verifyOptions: {
+			audience: henosiaAuthConfig.clientId.get(),
+			issuer: `${henosiaAuthConfig.henosiaAuthPlatformServiceBaseUrl.get()}/api/auth`
+		}
+	});
+	const { "https://henosia.com/project": projectId } = payload;
+	if (!projectId) throw new APIError("UNAUTHORIZED", { message: "token does not grant access" });
+	if (!henosiaAuthConfig.projectId) throw new APIError("INTERNAL_SERVER_ERROR", { message: "HENOSIA_AUTH_PROJECT_ID env var has not been set" });
+	if (henosiaAuthConfig.projectId.get() !== projectId) throw new APIError("UNAUTHORIZED", { message: "token has invalid projectId" });
+	const setCookieHeaders = accessTokenResponseHeaders.getSetCookie();
+	const transferBetterAuthCookiesToNext = (nextRequest, response) => {
+		for (const cookie of setCookieHeaders) parseSetCookieHeader(cookie).forEach((attributes, name) => {
+			const { value, ...betterOptions } = attributes;
+			const options = {
+				...betterOptions,
+				maxAge: betterOptions["max-age"],
+				httpOnly: betterOptions.httponly,
+				sameSite: betterOptions.samesite
+			};
+			nextRequest.cookies.set(name, value);
+			response.cookies.set(name, value, options);
+		});
+	};
+	return {
+		accessTokenResponse,
+		payload,
+		setCookieHeaders,
+		transferBetterAuthCookiesToNext
+	};
+}
+const unauthorizedExceptionCodes = new Set(["ACCOUNT_NOT_FOUND", "FAILED_TO_GET_ACCESS_TOKEN"]);
+/**
+* Determines whether the specified exception should start the sign-in flow to authenticate the user
+* @param error the error thrown by `verifyHenosiaAuthToken`
+*/
+function isUnauthorizedException(error) {
+	const apiError = error ?? {};
+	return unauthorizedExceptionCodes.has(apiError.body?.code ?? "") || apiError.status === "UNAUTHORIZED" || apiError.statusCode === 401;
+}
+//#endregion
+export { HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, auth, cookiePrefix, henosiaAuthConfig, isPageOrRefreshTokenRequest, isPageRequest, isUnauthorizedException, verifyHenosiaAuthToken };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+
+import { HENOSIA_AUTH_GET_SESSION_PATH_NAME, HENOSIA_AUTH_SIGN_IN_PATH_NAME, HENOSIA_ORGANIZATION_CTX_COOKIE, HenosiaOrganizationContext } from "./shared.mjs";
+import { HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, HenosiaAuthConfig, HenosiaAuthTokenClaims, auth, cookiePrefix, henosiaAuthConfig, isPageOrRefreshTokenRequest, isPageRequest, isUnauthorizedException, verifyHenosiaAuthToken } from "./auth/server.mjs";
+export { HENOSIA_AUTH_GET_SESSION_PATH_NAME, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, HENOSIA_AUTH_SIGN_IN_PATH_NAME, HENOSIA_ORGANIZATION_CTX_COOKIE, type HenosiaAuthConfig, type HenosiaAuthTokenClaims, type HenosiaOrganizationContext, auth, cookiePrefix, henosiaAuthConfig, isPageOrRefreshTokenRequest, isPageRequest, isUnauthorizedException, verifyHenosiaAuthToken };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+/*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
+import { HENOSIA_AUTH_GET_SESSION_PATH_NAME, HENOSIA_AUTH_SIGN_IN_PATH_NAME, HENOSIA_ORGANIZATION_CTX_COOKIE } from "./shared.mjs";
+import { HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, auth, cookiePrefix, henosiaAuthConfig, isPageOrRefreshTokenRequest, isPageRequest, isUnauthorizedException, verifyHenosiaAuthToken } from "./auth/server.mjs";
+export { HENOSIA_AUTH_GET_SESSION_PATH_NAME, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES, HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES, HENOSIA_AUTH_SIGN_IN_PATH_NAME, HENOSIA_ORGANIZATION_CTX_COOKIE, auth, cookiePrefix, henosiaAuthConfig, isPageOrRefreshTokenRequest, isPageRequest, isUnauthorizedException, verifyHenosiaAuthToken };

package/dist/platform/app-switcher.d.mts

@@ -0,0 +1,96 @@
+
+import { HenosiaOrganizationContext } from "../shared.mjs";
+
+//#region src/platform/app-switcher.d.ts
+/**
+ * A single app surfaced by the Henosia Platform app-switcher endpoint.
+ */
+interface AppSwitcherApp {
+  id: string;
+  name: string;
+  group: string;
+  url: string;
+}
+/**
+ * A group of {@link AppSwitcherApp}s under a common heading.
+ */
+interface AppSwitcherAppGroup {
+  group: string;
+  apps: AppSwitcherApp[];
+}
+/**
+ * Successful response shape returned by `/api/henosia-platform/v1/app-switcher`.
+ */
+interface AppSwitcherSuccessResponse {
+  groupedApps: AppSwitcherAppGroup[];
+  organization: {
+    id: string;
+    name: string;
+  };
+}
+/**
+ * Error response shape returned by `/api/henosia-platform/v1/app-switcher`.
+ */
+interface AppSwitcherErrorResponse {
+  error: string;
+}
+/**
+ * Options for {@link useAppSwitcher}.
+ */
+interface UseAppSwitcherOptions {
+  /**
+   * Whether the underlying query should run. Defaults to `true`.
+   *
+   * Set this to a state value (e.g. the open state of a popover) to defer the network request until the
+   * UI surfacing the app switcher is actually being shown.
+   */
+  enabled?: boolean;
+}
+/**
+ * Result of {@link useAppSwitcher}.
+ */
+interface UseAppSwitcherResult {
+  /**
+   * The current organization context, derived from the {@link HENOSIA_ORGANIZATION_CTX_COOKIE} cookie set by the
+   * Henosia Auth middleware. `null` until the cookie has been read (or if no organization is in context).
+   */
+  organization: HenosiaOrganizationContext;
+  /**
+   * The grouped apps available to the current user. Empty until the query has loaded.
+   */
+  groupedApps: AppSwitcherAppGroup[];
+  /**
+   * The error from the most recent failed query, if any.
+   */
+  error: Error | null;
+  /**
+   * Whether the query is currently loading.
+   */
+  isLoading: boolean;
+}
+/**
+ * React hook backing the Henosia app-switcher UI.
+ *
+ * Reads the current organization context from the {@link HENOSIA_ORGANIZATION_CTX_COOKIE} cookie and queries
+ * the Henosia Platform `app-switcher` endpoint mounted at `/api/henosia-platform/v1/app-switcher` (provided by
+ * `@henosia/app-next/api/platform`).
+ *
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { useState } from 'react';
+ * import { useAppSwitcher } from '@henosia/app-next/platform/app-switcher';
+ *
+ * export function MyAppSwitcher() {
+ *   const [open, setOpen] = useState(false);
+ *   const { organization, groupedApps, isLoading, error } = useAppSwitcher({
+ *     enabled: open
+ *   });
+ *   // ... render your own Popover/Command UI using the data above
+ * }
+ * ```
+ */
+declare function useAppSwitcher(options: UseAppSwitcherOptions): UseAppSwitcherResult;
+//#endregion
+export { AppSwitcherApp, AppSwitcherAppGroup, AppSwitcherErrorResponse, AppSwitcherSuccessResponse, UseAppSwitcherOptions, UseAppSwitcherResult, useAppSwitcher };

package/dist/platform/app-switcher.mjs

@@ -0,0 +1,74 @@
+/*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
+"use client";
+import { HENOSIA_ORGANIZATION_CTX_COOKIE } from "../shared.mjs";
+import { useEffect, useLayoutEffect, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+//#region src/platform/app-switcher.ts
+/**
+* Use {@link useLayoutEffect} on the client (so cookie reads happen before paint and we don't show a stale
+* organization placeholder), and fall back to {@link useEffect} on the server to avoid the React SSR warning.
+*/
+const useFastEffect = typeof document === "object" ? useLayoutEffect : useEffect;
+async function fetchAppSwitcher() {
+	const response = await fetch("/api/henosia-platform/v1/app-switcher");
+	let body = null;
+	try {
+		body = await response.json();
+	} catch {}
+	if (!response.ok || !body || "error" in body && body.error) {
+		const message = body && "error" in body && body.error ? body.error : `Request failed: ${response.status} ${response.statusText}`;
+		throw new Error(message);
+	}
+	return body;
+}
+/**
+* React hook backing the Henosia app-switcher UI.
+*
+* Reads the current organization context from the {@link HENOSIA_ORGANIZATION_CTX_COOKIE} cookie and queries
+* the Henosia Platform `app-switcher` endpoint mounted at `/api/henosia-platform/v1/app-switcher` (provided by
+* `@henosia/app-next/api/platform`).
+*
+*
+* @example
+* ```tsx
+* 'use client';
+* import { useState } from 'react';
+* import { useAppSwitcher } from '@henosia/app-next/platform/app-switcher';
+*
+* export function MyAppSwitcher() {
+*   const [open, setOpen] = useState(false);
+*   const { organization, groupedApps, isLoading, error } = useAppSwitcher({
+*     enabled: open
+*   });
+*   // ... render your own Popover/Command UI using the data above
+* }
+* ```
+*/
+function useAppSwitcher(options) {
+	const { enabled = true } = options;
+	const [organization, setOrganization] = useState(null);
+	useFastEffect(() => {
+		if (typeof document !== "object") return;
+		const orgIdx = document.cookie.indexOf(`${HENOSIA_ORGANIZATION_CTX_COOKIE}=`);
+		if (orgIdx === -1) return;
+		const cookie = document.cookie.substring(orgIdx).split(/[=;]/g)[1];
+		try {
+			setOrganization(JSON.parse(decodeURIComponent(cookie)));
+		} catch (e) {
+			console.warn("Invalid org cookie", cookie, e);
+		}
+	}, []);
+	const { data, error, isLoading } = useQuery({
+		queryKey: ["henosia-platform", "app-switcher"],
+		queryFn: fetchAppSwitcher,
+		enabled
+	});
+	return {
+		organization,
+		groupedApps: data?.groupedApps ?? [],
+		error,
+		isLoading
+	};
+}
+//#endregion
+export { useAppSwitcher };

package/dist/shared.d.mts

@@ -0,0 +1,19 @@
+
+//#region src/shared.d.ts
+declare const HENOSIA_AUTH_SIGN_IN_PATH_NAME = "/sign-in";
+/**
+ * The pathname for better-auth's `/get-session` endpoint, used by the React `useSession` hook.
+ *
+ * `useSession` automatically refetches this endpoint on browser tab focus (and optionally on a polling
+ * interval), which we leverage as a built-in keep-alive for the OIDC access/refresh tokens — see
+ * `isPageOrRefreshTokenRequest` and the middleware special-case for this path.
+ */
+declare const HENOSIA_AUTH_GET_SESSION_PATH_NAME = "/api/auth/get-session";
+type HenosiaOrganizationContext = {
+  id: string;
+  name: string;
+  logoUrl: string | null;
+} | null;
+declare const HENOSIA_ORGANIZATION_CTX_COOKIE = "henosia.org";
+//#endregion
+export { HENOSIA_AUTH_GET_SESSION_PATH_NAME, HENOSIA_AUTH_SIGN_IN_PATH_NAME, HENOSIA_ORGANIZATION_CTX_COOKIE, HenosiaOrganizationContext };