@henosia/app-next 1.0.2

package/LICENSE

@@ -0,0 +1,183 @@
+HENOSIA COMMERCIAL SOURCE LICENSE
+Version 1.0, May 20, 2026
+
+Copyright (c) 2026 Henosia ApS. All rights reserved.
+
+1. DEFINITIONS
+
+   "Licensor" means Henosia ApS, a Danish private limited company
+   (anpartsselskab) registered in Denmark as no. 42120014.
+
+   "Software" means the source code, object code, documentation, and any
+   other materials contained in this package, including any updates or
+   modifications provided by Licensor.
+
+   "Henosia Platform" means the software development and hosting platform
+   operated by Licensor at henosia.com (and successor domains).
+
+   "Authorized Customer" means a natural or legal person who holds an
+   active, paid subscription to the Henosia Platform and is in good
+   standing under Licensor's then-current terms of service as described
+   at https://www.henosia.com/terms-of-service.
+
+   "Customer Application" means an application developed by an Authorized
+   Customer on the Henosia Platform that incorporates the Software solely
+   to provide authentication functionality to that application's end
+   users.
+
+   "End User" means a natural person who interacts with a Customer
+   Application (for example, to sign in or authenticate) without
+   themselves redistributing or repackaging the Software.
+
+   "Competing Service" means any product, service, or platform that
+   provides, in whole or in part: (a) AI-assisted application generation;
+   (b) AI-assisted coding environments or IDEs; or (c) AI agent platforms
+   that produce, modify, or deploy software on behalf of users. This
+   includes any service that competes, directly or indirectly, with the
+   Henosia Platform.
+
+2. GRANT OF LICENSE
+
+   Subject to the restrictions in Section 3 and continued compliance with
+   this License, Licensor grants Authorized Customers a worldwide,
+   non-exclusive, non-transferable, non-sublicensable, royalty-free,
+   revocable license to:
+
+   (a) install and use the Software, in unmodified form, solely as a
+       dependency of Customer Applications;
+
+   (b) distribute the Software, in unmodified form and only as bundled
+       within a Customer Application, to End Users to the extent
+       necessary for those End Users to use the Customer Application.
+
+   End Users receive no separate license to the Software and may use it
+   only as embedded in a Customer Application.
+
+3. RESTRICTIONS
+
+   Except as expressly permitted in Section 2, you may not:
+
+   (a) use, install, copy, execute, or distribute the Software unless
+       you are an Authorized Customer or an End User of a Customer
+       Application;
+
+   (b) modify, adapt, translate, fork, or create derivative works of the
+       Software;
+
+   (c) use, incorporate, or make the Software available in connection
+       with the development, operation, training, or improvement of any
+       Competing Service;
+
+   (d) reverse engineer, decompile, disassemble, or otherwise attempt to
+       derive the source code, structure, or internal logic of the
+       Software, except and only to the extent that such activity is
+       expressly permitted by applicable mandatory law (including, where
+       applicable, Article 6 of EU Directive 2009/24/EC on the legal
+       protection of computer programs) notwithstanding this limitation;
+
+   (e) sublicense, sell, rent, lease, lend, or otherwise transfer the
+       Software to any third party except as part of a Customer
+       Application as permitted in Section 2;
+
+   (f) remove, alter, or obscure any copyright, trademark, or other
+       proprietary notices contained in the Software;
+
+   (g) use the name "Henosia," any Henosia logo, or any confusingly
+       similar mark, except as required to comply with the notice
+       requirements of this License.
+
+4. OWNERSHIP
+
+   The Software is licensed, not sold. Licensor retains all right, title,
+   and interest in and to the Software, including all intellectual
+   property rights. No rights are granted by implication, estoppel, or
+   otherwise except as expressly set forth in this License. No patent
+   rights are granted under this License.
+
+5. CUSTOMER APPLICATION CODE
+
+   For the avoidance of doubt, this License governs only the Software.
+   Code authored by an Authorized Customer for a Customer Application
+   using the Henosia Platform remains the property of that Authorized
+   Customer, subject to the Henosia Platform terms of service.
+
+6. TERMINATION
+
+   This License terminates automatically and immediately, without notice,
+   if:
+
+   (a) you cease to be an Authorized Customer (for example, by
+       cancellation, non-payment, or suspension of your Henosia
+       subscription); or
+
+   (b) you breach any term of this License.
+
+   Upon termination, your rights under Section 2 cease. You must, within
+   thirty (30) days of termination ("Wind-Down Period"), remove the
+   Software from all Customer Applications, including from all source
+   code repositories, build artifacts, deployments, and dependency
+   manifests under your control. After the Wind-Down Period, you may
+   not install, execute, distribute, or otherwise use the Software in
+   any form.
+
+   For the avoidance of doubt, this License does not affect your
+   ownership of, or your right to continue using, the application code
+   you authored for a Customer Application. You remain free to replace
+   the functionality previously provided by the Software with your own
+   implementation or with a third-party alternative.
+
+   During the Wind-Down Period only, End Users may continue to use
+   Customer Applications into which the Software has already been
+   incorporated and deployed. After the Wind-Down Period, the former
+   Authorized Customer must ensure the Software is no longer present in
+   any deployed Customer Application.
+
+   Sections 3, 4, 7, 8, 9, and 10 survive termination.
+
+7. DISCLAIMER OF WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT. LICENSOR DOES NOT WARRANT THAT THE SOFTWARE WILL BE
+   ERROR-FREE OR UNINTERRUPTED.
+
+8. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+   CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS, REVENUE,
+   DATA, OR GOODWILL, ARISING OUT OF OR IN CONNECTION WITH THIS LICENSE
+   OR THE USE OF OR INABILITY TO USE THE SOFTWARE, WHETHER BASED ON
+   CONTRACT, TORT, OR ANY OTHER LEGAL THEORY, EVEN IF LICENSOR HAS BEEN
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. LICENSOR'S TOTAL AGGREGATE
+   LIABILITY UNDER THIS LICENSE SHALL NOT EXCEED THE TOTAL SUBSCRIPTION
+   FEES PAID BY THE AUTHORIZED CUSTOMER TO LICENSOR FOR THE HENOSIA
+   PLATFORM DURING THE TWELVE (12) MONTHS IMMEDIATELY PRECEDING THE EVENT
+   GIVING RISE TO THE CLAIM, OR EUR 100, WHICHEVER IS GREATER.
+
+   Nothing in this License limits or excludes liability that cannot be
+   limited or excluded under applicable mandatory law.
+
+9. GOVERNING LAW AND JURISDICTION
+
+   This License is governed by and construed in accordance with the laws
+   of Denmark, excluding its conflict-of-laws rules and excluding the
+   United Nations Convention on Contracts for the International Sale of
+   Goods. The exclusive venue for any dispute arising out of or relating
+   to this License shall be the courts of Copenhagen, Denmark.
+
+10. GENERAL
+
+    If any provision of this License is held to be unenforceable, the
+    remaining provisions shall remain in full force and effect. Failure
+    to enforce any provision is not a waiver of future enforcement.
+    Licensor may publish updated versions of this License for future
+    releases of the Software. The version of this License accompanying a
+    given release of the Software governs that release; updates do not
+    retroactively apply to releases made before the update. This License
+    constitutes the entire agreement between you and Licensor regarding
+    the Software and supersedes any prior agreements relating to its
+    subject matter.
+
+For licensing inquiries: hello@henosia.com

package/README.md

@@ -0,0 +1,173 @@
+# @henosia/app-next
+
+Henosia integration for Next.js apps: Provides middleware and better-auth setup for Henosia Auth, Henosia Platform API route handlers, and (optionally) automatic Supabase sign in.
+
+## Installation
+
+```sh
+pnpm add @henosia/app-next better-auth next react react-dom @tanstack/react-query
+# Optional, only if your app uses Supabase
+pnpm add @supabase/ssr @supabase/supabase-js
+```
+
+### Peer dependencies
+
+| Package                  | Required range          | Notes                                     |
+|--------------------------|-------------------------|-------------------------------------------|
+| `next`                   | `14.x \| 15.x \| 16.x`  |                                           |
+| `better-auth`            | `>=1.6.0 <2`            |                                           |
+| `react` / `react-dom`    | `^18 \| ^19`            | Required by `better-auth/react`           |
+| `@tanstack/react-query`  | `^5.0.0`                | Required by the app switcher              |
+| `@supabase/ssr`          | `^0.10.2`               | Optional — only when integrating Supabase |
+| `@supabase/supabase-js`  | `^2.103.0`              | Optional — only when integrating Supabase |
+
+## Required environment variables
+
+| Variable                              | Description                                           |
+|---------------------------------------|-------------------------------------------------------|
+| `BETTER_AUTH_URL`                     | The consuming app's deployment/preview base URL       |
+| `BETTER_AUTH_SECRET`                  | The consuming app's better-auth secret                |
+| `HENOSIA_AUTH_SERVICE_BASE_URL`       | Henosia auth/platform service base URL                |
+| `HENOSIA_AUTH_CLIENT_ID`              | OAuth client ID for this project                      |
+| `HENOSIA_AUTH_CLIENT_SECRET`          | OAuth client secret for this project                  |
+| `HENOSIA_AUTH_PROJECT_ID`             | Project ID validated against the JWT project claim    |
+| `HENOSIA_AUTH_SUPABASE_PROVIDER`      | Optional — defaults to `custom:henosia-auth:platform` |
+| `NEXT_PUBLIC_SUPABASE_URL`            | Optional — enables Supabase session exchange when set |
+| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`| Required when `NEXT_PUBLIC_SUPABASE_URL` is set       |
+
+## Setup
+
+### 1. Middleware
+
+Create (or edit) `middleware.ts` in your app root:
+
+```ts
+// middleware.ts
+import { type NextRequest } from 'next/server'
+import { createHenosiaAuthMiddleware } from '@henosia/app-next/auth/middleware'
+
+const henosiaAuth = createHenosiaAuthMiddleware()
+
+export async function middleware(request: NextRequest) {
+  // App-specific pre-checks here, if any.
+  return await henosiaAuth(request)
+}
+
+export const config = {
+  matcher: [
+    /*
+     * Match all request paths except for the ones starting with:
+     * - _next/static (static files)
+     * - _next/image (image optimization files)
+     * - favicon.ico (favicon file)
+     */
+    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+  ],
+}
+```
+
+If you want to add additional public paths that should bypass the auth pre-check:
+
+```ts
+const henosiaAuth = createHenosiaAuthMiddleware({
+  additionalUnauthenticatedPathNames: ['/health'],
+  additionalUnauthenticatedPathNamePrefixes: ['/public/'],
+})
+```
+
+### 2. better-auth catch-all route
+
+Create `app/api/auth/[...all]/route.ts`:
+
+```ts
+export { GET, POST } from '@henosia/app-next/api/auth'
+```
+
+### 3. Henosia Platform catch-all route
+
+Create `app/api/henosia-platform/[...all]/route.ts`:
+
+```ts
+export { GET } from '@henosia/app-next/api/platform'
+```
+
+### 4. React auth client
+
+```ts
+// e.g. lib/auth-client.ts
+export { authClient } from '@henosia/app-next/auth/client'
+```
+
+### 5. (Optional) Supabase helpers
+
+```ts
+// Server Components / Route Handlers
+import { createClient } from '@henosia/app-next/supabase/server'
+
+// Client Components
+import { createClient } from '@henosia/app-next/supabase/client'
+```
+
+## Server-side helpers
+
+```ts
+import {
+  auth,
+  verifyHenosiaAuthToken,
+  isUnauthorizedException,
+  isPageRequest,
+  HENOSIA_AUTH_SIGN_IN_PATH_NAME,
+} from '@henosia/app-next'
+```
+
+`verifyHenosiaAuthToken(request)` MUST be called from any protected page/route handler/server action — the
+middleware only performs a fast pre-check.
+
+## App-switcher hook
+
+`@henosia/app-next/platform/app-switcher` exposes the `useAppSwitcher` React hook used to build a custom
+app-switcher UI. It reads the current organization context from the cookie set by the middleware and queries
+the catch-all platform route mounted in [step 3](#3-henosia-platform-catch-all-route).
+
+Requires a `@tanstack/react-query` `QueryClientProvider` higher up in the tree.
+
+```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/menu UI using `organization`, `groupedApps`,
+  // `isLoading`, and `error`.
+  return (
+    <button onClick={() => setOpen((v) => !v)}>
+      {organization?.name ?? 'Loading…'}
+    </button>
+  )
+}
+```
+
+| Option        | Type          | Default | Description                                                                                                                |
+|---------------|---------------|---------|----------------------------------------------------------------------------------------------------------------------------|
+| `enabled`     | `boolean`     | `true`  | Whether the underlying query should run. Wire to e.g. a popover's open state to defer it.                                  |
+
+## Subpath exports
+
+| Subpath                                        | Purpose                                                    |
+|------------------------------------------------|------------------------------------------------------------|
+| `@henosia/app-next`                            | Server-side helpers (`auth`, `verifyHenosiaAuthToken`, …)  |
+| `@henosia/app-next/shared`                     | Shared constants & types (no runtime deps)                 |
+| `@henosia/app-next/auth/middleware`            | `createHenosiaAuthMiddleware`                              |
+| `@henosia/app-next/auth/server`                | Lower-level server-side auth surface (re-exported by root) |
+| `@henosia/app-next/auth/client`                | Better-auth `authClient` for React                         |
+| `@henosia/app-next/api/auth`                   | `GET`, `POST` for `/api/auth/[...all]`                     |
+| `@henosia/app-next/api/platform`               | `GET` for `/api/henosia-platform/[...all]`                 |
+| `@henosia/app-next/platform/app-switcher`      | `useAppSwitcher` React hook                                |
+| `@henosia/app-next/supabase/server`            | Server-side Supabase client factory                        |
+| `@henosia/app-next/supabase/client`            | Browser Supabase client factory                            |

package/dist/api/auth.d.mts

@@ -0,0 +1,6 @@
+
+//#region src/api/auth.d.ts
+declare const GET: (request: Request) => Promise<Response>;
+declare const POST: (request: Request) => Promise<Response>;
+//#endregion
+export { GET, POST };

package/dist/api/auth.mjs

@@ -0,0 +1,18 @@
+/*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
+import { auth } from "../auth/server.mjs";
+import { toNextJsHandler } from "better-auth/next-js";
+//#region src/api/auth.ts
+/**
+* Catch-all Next.js route handler for better-auth.
+*
+* Mount as a catch-all route at `app/api/auth/[...all]/route.ts`:
+*
+* ```ts
+* export { GET, POST } from '@henosia/app-next/api/auth'
+* ```
+*/
+const handlers = toNextJsHandler(auth);
+const GET = handlers.GET;
+const POST = handlers.POST;
+//#endregion
+export { GET, POST };

package/dist/api/platform.d.mts

@@ -0,0 +1,19 @@
+
+import { NextRequest } from "next/server.js";
+
+//#region src/api/platform.d.ts
+/**
+ * Catch-all Next.js route handler for the Henosia Platform API routes.
+ *
+ * Mount as a catch-all route at `app/api/henosia-platform/[...all]/route.ts`:
+ *
+ * ```ts
+ * export { GET } from '@henosia/app-next/api/platform'
+ * ```
+ *
+ * Currently routes:
+ * - `GET /api/henosia-platform/v1/app-switcher` → `handleAppSwitcher`
+ */
+declare function GET(request: NextRequest): Promise<Response>;
+//#endregion
+export { GET };

package/dist/api/platform.mjs

@@ -0,0 +1,48 @@
+/*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
+import { henosiaAuthConfig, isUnauthorizedException, verifyHenosiaAuthToken } from "../auth/server.mjs";
+//#region src/api/platform/v1/app-switcher.ts
+/**
+* Handler for the Henosia Platform `app-switcher` endpoint.
+* Proxies the authenticated request to the Henosia Auth platform service using the verified id token.
+*/
+async function handleAppSwitcher(request) {
+	try {
+		const { accessTokenResponse } = await verifyHenosiaAuthToken(request);
+		const fetchUrl = new URL(henosiaAuthConfig.henosiaAuthPlatformServiceBaseUrl.get());
+		fetchUrl.pathname = request.nextUrl.pathname;
+		const response = await fetch(fetchUrl, {
+			method: "GET",
+			redirect: "error",
+			headers: { authorization: `Bearer ${accessTokenResponse.idToken}` }
+		});
+		return Response.json(await response.json(), {
+			status: response.status,
+			statusText: response.statusText
+		});
+	} catch (e) {
+		if (isUnauthorizedException(e)) return Response.json({ error: "Your session is invalid or expired. Please reload the page to sign in again." }, { status: 401 });
+		console.error("[Henosia Platform] App Switcher API error", e);
+		return Response.json({ error: "Server error" }, { status: 500 });
+	}
+}
+//#endregion
+//#region src/api/platform.ts
+/**
+* Catch-all Next.js route handler for the Henosia Platform API routes.
+*
+* Mount as a catch-all route at `app/api/henosia-platform/[...all]/route.ts`:
+*
+* ```ts
+* export { GET } from '@henosia/app-next/api/platform'
+* ```
+*
+* Currently routes:
+* - `GET /api/henosia-platform/v1/app-switcher` → `handleAppSwitcher`
+*/
+async function GET(request) {
+	const { pathname } = request.nextUrl;
+	if (pathname === "/api/henosia-platform/v1/app-switcher") return handleAppSwitcher(request);
+	return Response.json({ error: `Not found: ${pathname}` }, { status: 404 });
+}
+//#endregion
+export { GET };

package/dist/auth/client.d.mts

@@ -0,0 +1,25 @@
+
+import { createAuthClient } from "better-auth/react";
+
+//#region src/auth/client.d.ts
+/**
+ * Minimal React auth client type, derived from `createAuthClient` with no plugins.
+ *
+ * The full plugin-aware return type of `createAuthClient<Option>()` is a deeply-inferred graph that
+ * references non-portable internals from `better-auth` and `zod` and cannot be named in published
+ * declarations (TS2883). By widening to the no-plugin shape we keep the supported public surface
+ * (`signIn`, `signOut`, `useSession`, `getSession`, `$Infer`, `$fetch`, etc.) strongly typed at the
+ * package boundary while keeping the emitted `.d.mts` portable.
+ */
+type HenosiaAuthClient = ReturnType<typeof createAuthClient>;
+/**
+ * The Henosia Auth client for use in browser/React contexts.
+ *
+ * Uses better-auth's React client with the Henosia Auth plugins (OAuth + JWT).
+ *
+ * Typed as the minimal {@link HenosiaAuthClient} (the no-plugin React client shape) so consumers get
+ * proper IntelliSense for the standard better-auth methods/hooks.
+ */
+declare const authClient: HenosiaAuthClient;
+//#endregion
+export { HenosiaAuthClient, authClient };

package/dist/auth/client.mjs

@@ -0,0 +1,19 @@
+/*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
+"use client";
+import { createAuthClient } from "better-auth/react";
+import { genericOAuthClient, jwtClient } from "better-auth/client/plugins";
+//#region src/auth/client.ts
+/**
+* The Henosia Auth client for use in browser/React contexts.
+*
+* Uses better-auth's React client with the Henosia Auth plugins (OAuth + JWT).
+*
+* Typed as the minimal {@link HenosiaAuthClient} (the no-plugin React client shape) so consumers get
+* proper IntelliSense for the standard better-auth methods/hooks.
+*/
+const authClient = createAuthClient({
+	plugins: [jwtClient(), genericOAuthClient()],
+	sessionOptions: { refetchInterval: 600 }
+});
+//#endregion
+export { authClient };

package/dist/auth/middleware.d.mts

@@ -0,0 +1,54 @@
+
+import { NextRequest, NextResponse } from "next/server.js";
+
+//#region src/auth/middleware.d.ts
+/**
+ * Options for {@link createHenosiaAuthMiddleware}.
+ */
+interface HenosiaAuthMiddlewareOptions {
+  /**
+   * Additional URL pathname values that should not check for auth in middleware.
+   * These are merged with the default {@link HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAMES}.
+   *
+   * Use ONLY for paths that should not be intercepted by the middleware auth pre-check and redirect.
+   */
+  additionalUnauthenticatedPathNames?: ReadonlyArray<string>;
+  /**
+   * Additional URL pathname prefixes that should not be blocked by auth in middleware.
+   * Each value must end with `/` to prevent unexpected partial route matches.
+   * These are merged with the default {@link HENOSIA_AUTH_MIDDLEWARE_UNAUTHENTICATED_PATH_NAME_PREFIXES}.
+   *
+   * Use ONLY for paths that should not be intercepted by the middleware auth pre-check and redirect.
+   */
+  additionalUnauthenticatedPathNamePrefixes?: ReadonlyArray<string>;
+}
+/**
+ * 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)
+ * }
+ *
+ * ```
+ */
+declare function createHenosiaAuthMiddleware(options?: HenosiaAuthMiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;
+//#endregion
+export { HenosiaAuthMiddlewareOptions, createHenosiaAuthMiddleware };