@henosia/app-next 1.0.2 → 1.0.4

package/.agents/skills/henosia-app-next/assets/template/components/sign-in.tsx

@@ -0,0 +1,85 @@
+//@ts-nocheck (remove when using the template)
+"use client";
+
+import Link from "next/link";
+import {Button} from "@/components/ui/button";
+import {Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle,} from "@/components/ui/card";
+import {authClient} from "@/lib/auth-client";
+import {cn} from "@/lib/utils";
+import {useToast} from "@/hooks/use-toast";
+import {useState} from "react";
+
+export function SignIn() {
+
+	const {signIn} = authClient;
+  const [loading, setLoading] = useState(false);
+
+  const {toast} = useToast();
+
+	return (
+		<Card className="max-w-md rounded-none">
+			<CardHeader>
+				<CardTitle className="text-lg md:text-xl">Sign In</CardTitle>
+				<CardDescription className="text-xs md:text-sm">
+					Sign in for this app is provided by Henosia Auth.
+				</CardDescription>
+			</CardHeader>
+			<CardContent>
+				<div className="grid gap-4">
+
+					<div
+						className={cn(
+							"w-full gap-2 flex items-center",
+							"justify-between flex-col",
+						)}
+					>
+						<Button
+							variant="outline"
+							className={cn("w-full gap-2 flex relative data-[loading=true]:cursor-progress")}
+							data-henosia-auth-sign-in
+              data-loading={loading}
+							onClick={async () => {
+                if (loading) {
+                  return;
+                }
+                try {
+                  setLoading(true);
+                  const {error} = await signIn.social({
+                    provider: "henosia",
+                    callbackURL: "/",
+                  });
+                  if (error) {
+                    console.error('[Henosia Auth] Sign-in error', error);
+                    toast({ variant: "destructive", title: "Sign-in failed", description: error.message });
+                  }
+                } finally {
+                  setLoading(false)
+                }
+							}}
+						>
+							<span className={"relative"}>
+                Sign in with Henosia
+              </span>
+            </Button>
+          </div>
+        </div>
+      </CardContent>
+      <CardFooter>
+        <div className="flex justify-center w-full border-t pt-4">
+          <p className="text-center text-xs text-neutral-500">
+            Learn more about {" "}
+            <Link
+              href="https://docs.henosia.com"
+              className="underline"
+              target="_blank"
+            >
+							<span className="dark:text-white/70 cursor-pointer">
+								Henosia Auth.
+							</span>
+            </Link>
+          </p>
+        </div>
+      </CardFooter>
+    </Card>
+  );
+}

package/.agents/skills/henosia-app-next/assets/template/lib/auth-client.ts

@@ -0,0 +1,3 @@
+//@ts-nocheck (remove when using the template)
+"use client"
+export { authClient } from '@henosia/app-next/auth/client'

package/.agents/skills/henosia-app-next/assets/template/lib/supabase/client.ts

@@ -0,0 +1,2 @@
+//@ts-nocheck (remove when using the template)
+export { createClient } from '@henosia/app-next/supabase/client'

package/.agents/skills/henosia-app-next/assets/template/lib/supabase/server.ts

@@ -0,0 +1,2 @@
+//@ts-nocheck (remove when using the template)
+export { createClient } from '@henosia/app-next/supabase/server'

package/.agents/skills/henosia-app-next/assets/template/middleware.ts

@@ -0,0 +1,29 @@
+//@ts-nocheck (remove when using the template)
+// Template use guidance: Preserve comments verbatim from the line `// To Henosia assistant regarding this file:` and below
+import { type NextRequest } from 'next/server'
+import { createHenosiaAuthMiddleware } from '@henosia/app-next/auth/middleware'
+
+const henosiaAuthMiddleware = createHenosiaAuthMiddleware()
+
+export async function middleware(request: NextRequest) {
+  // App-specific pre-checks here, if any.
+  return await henosiaAuthMiddleware(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)$).*)',
+  ],
+}
+
+// To Henosia assistant regarding this file:
+// Henosia Auth is a managed solution that is outside your scope of work.
+// Henosia Auth flows must be preserved at all times.
+// Important: This middleware performs an auth *pre-check*. Authorization MUST still be performed at the relevant pages and route handlers using `requireHenosiaAuth` or `routeWithHenosiaAuth` from `@henosia/app-next`.
+// Any potential issues with Henosia Auth flows must be referred to Henosia technical support: https://docs.henosia.com/support

package/.agents/skills/henosia-app-next/assets/template/next.config.mjs

@@ -0,0 +1,65 @@
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Makes a webpack OutputFileSystem emit assets atomically.
+ * Fixes `Uncaught SyntaxError: Invalid or unexpected token` in the browser when the
+ * served layout.js is visibly cut off mid-string due to concurrent non-atomic writes.
+ */
+function patchWebpackOutputFileSystem(ofs) {
+  if (!ofs || ofs.__atomicEmitPatched) return;
+  if (typeof ofs.writeFile !== 'function' || typeof ofs.rename !== 'function') {
+    return;
+  }
+
+  const origWriteFile = ofs.writeFile.bind(ofs);
+  const origRename = ofs.rename.bind(ofs);
+  const origUnlink = typeof ofs.unlink === 'function' ? ofs.unlink.bind(ofs) : null;
+
+  ofs.writeFile = function patchedWriteFile(filePath, content, optionsOrCb, maybeCb) {
+    const hasOptions = typeof optionsOrCb !== 'function';
+    const options = hasOptions ? optionsOrCb : undefined;
+    const cb = hasOptions ? maybeCb : optionsOrCb;
+    const tmp = `${filePath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+
+    const done = (err) => {
+      if (err) {
+        if (origUnlink) origUnlink(tmp, () => cb(err));
+        else cb(err);
+        return;
+      }
+      origRename(tmp, filePath, cb);
+    };
+
+    if (hasOptions && options !== undefined) {
+      origWriteFile(tmp, content, options, done);
+    } else {
+      origWriteFile(tmp, content, done);
+    }
+  };
+
+  Object.defineProperty(ofs, '__atomicEmitPatched', { value: true, enumerable: false });
+}
+
+class AtomicEmitPlugin {
+  apply(compiler) {
+    // `outputFileSystem` may be assigned/replaced after `apply` runs (e.g. by
+    // Next.js or webpack-dev-middleware), so patch lazily right before each
+    // build's emit phase. This is idempotent thanks to `__atomicEmitPatched`.
+    const patch = () => patchWebpackOutputFileSystem(compiler.outputFileSystem);
+    compiler.hooks.beforeRun.tap('AtomicEmitPlugin', patch);
+    compiler.hooks.watchRun.tap('AtomicEmitPlugin', patch);
+    compiler.hooks.beforeCompile.tap('AtomicEmitPlugin', patch);
+  }
+}
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack: (config, { dev }) => {
+    if (dev) {
+      config.plugins.push(new AtomicEmitPlugin());
+    }
+    return config;
+  },
+};
+
+export default nextConfig;

package/.agents/skills/henosia-app-next/assets/template/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "nextjs-shadcn-henosia-auth",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "__add_these__:": "",
+    "@henosia/app-next": "^1.0.3",
+    "@tanstack/react-query": "^5.100.11",
+    "better-auth": "1.6.11",
+    "__others_omitted_for_brevity__": ""
+  },
+  "devDependencies": {
+    "__others_omitted_for_brevity__": ""
+  }
+}

package/.agents/skills/henosia-app-next/assets/template/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/.agents/skills/henosia-auth-guards/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: henosia-auth-guards
+description: >-
+  Enforce @henosia/app-next's server authorization guards on Next.js App Router
+  code before any per-user data is read or returned. Use this skill WHENEVER you
+  create, edit, or review a server-side handler: any app/**/page.tsx or
+  layout.tsx, any file with a "use server" directive or Server Action, and any
+  Route Handler (route.ts/route.js) exporting GET/POST/PUT/PATCH/DELETE — or any
+  file importing from @henosia/app-next. Trigger even when the user never mentions
+  auth, and EVEN IF Henosia auth middleware is present, since the middleware is a
+  pre-check only and does NOT satisfy a handler's own authorization requirement.
+  Do NOT use for middleware (guards are invalid there), Client Components ("use
+  client"), or purely presentational components with no server data access.
+---
+
+# Henosia Auth Guards
+
+Authorization guards for Next.js apps using `@henosia/app-next`. **Every
+protected page, layout, Server Action, and Route Handler MUST call one of these
+guards.** The Henosia Auth middleware (`createHenosiaAuthMiddleware`) is a fast
+*pre-check* only — it does not satisfy the authorization requirement of the
+underlying request handler.
+
+## Import
+
+```ts
+import {
+  requireHenosiaAuth,
+  getHenosiaAuth,
+  routeWithHenosiaAuth,
+  type HenosiaAuthContext,
+} from '@henosia/app-next/auth/server-guards'
+```
+
+## Pick the right guard
+
+| Context                                                                 | Use                          | Behavior on unauthorized                              |
+|-------------------------------------------------------------------------|------------------------------|-------------------------------------------------------|
+| Server Component / Page / Server Action / protected layout              | `requireHenosiaAuth()`       | `redirect()` to `/sign-in` (`HENOSIA_AUTH_SIGN_IN_PATH_NAME`) |
+| Route Handler (`app/api/**/route.ts`)                                   | `routeWithHenosiaAuth(handler)` | `401 Unauthorized` JSON (RFC 7235) — never a redirect |
+
+## Examples
+
+### Page / Server Component / Server Action
+
+```tsx
+// app/dashboard/page.tsx
+import { requireHenosiaAuth } from '@henosia/app-next/auth/server-guards'
+
+export default async function Page() {
+  const claims = await requireHenosiaAuth()
+  return <Dashboard org={claims['https://henosia.com/organization']} />
+}
+```
+
+```ts
+// Server Action
+'use server'
+import { requireHenosiaAuth } from '@henosia/app-next/auth/server-guards'
+
+export async function createWidget(formData: FormData) {
+  await requireHenosiaAuth() // throws-redirects to sign-in if unauthorized
+  // ...mutate
+}
+```
+
+### Route Handler
+
+```ts
+// app/api/me/route.ts
+import { routeWithHenosiaAuth } from '@henosia/app-next/auth/server-guards'
+
+export const GET = routeWithHenosiaAuth((_request, { payload }) => ({
+  organization: payload['https://henosia.com/organization'],
+  preview: payload['https://henosia.com/preview'],
+}))
+```
+
+## `routeWithHenosiaAuth` handler return values
+
+The handler may return any of:
+- A `Response` — returned verbatim (security headers applied automatically).
+- A JSON-serializable value — auto-wrapped with `NextResponse.json` (with security headers).
+- `undefined` / `void` — translated to a `204 No Content` response.
+
+Every response (success, 401, 500) gets these headers applied if not already set:
+- `Cache-Control: private, no-store`
+- `Vary: Cookie`
+
+Do not override these unless you have a specific reason; they keep auth-protected,
+per-user data out of shared and browser caches.
+
+## Security rules — must follow
+
+1. **`accessToken` is a bearer credential.** Treat it like a password.
+   - Do **not** log it, echo it back in a response body, embed it in error
+     messages, persist it, or send it to untrusted services.
+   - Forward over TLS to trusted downstream services only.
+2. **Never call guards from middleware.** The middleware path uses
+   `createHenosiaAuthMiddleware`, which is the lightweight pre-check.
+   `requireHenosiaAuth` / `getHenosiaAuth` rely on `next/headers` and
+   `next/navigation` and are valid only inside Server Components, layouts,
+   Server Actions, and Route Handlers.
+3. **Every protected handler must call a guard.** Don't rely on the middleware.
+   Even paths matched by the middleware can be reached without it (e.g. when
+   `matcher` excludes them, when running in tests, or when a future change
+   relaxes the matcher).
+
+## Common pitfalls
+
+- ❌ `const claims = requireHenosiaAuth()` — missing `await`. The guard returns a Promise.
+- ❌ Calling `requireHenosiaAuth()` from a Route Handler. It will redirect, which
+  is the wrong UX for an API. Use `routeWithHenosiaAuth(handler)` instead.
+- ❌ Using `getHenosiaAuth()` to "protect" a page. It returns `null` on
+  unauthorized — the page will render without auth. Use `requireHenosiaAuth()`
+  for actual protection; reserve `getHenosiaAuth()` for layouts that render
+  different UI for signed-in vs signed-out users.
+- ❌ Manually calling `verifyHenosiaAuthToken` and reinventing the
+  redirect/401/500 flow. Use the guards; they encode the canonical contract.
+- ❌ Setting `Cache-Control: public` or otherwise loosening cache headers on a
+  guard-wrapped response. Per-user JSON must remain `private, no-store`.

package/README.md

@@ -120,7 +120,19 @@ import {
 } from '@henosia/app-next'
 ```
 
-`verifyHenosiaAuthToken(request)` MUST be called from any protected page/route handler/server action — the
+## Server-side auth guards
+
+Methods to add authorization guards around pages, router handlers, and server actions.
+
+```ts
+import {
+  requireHenosiaAuth,
+  routeWithHenosiaAuth,
+  getHenosiaAuth
+} from '@henosia/app-next/auth/server-guards'
+```
+
+`requireHenosiaAuth` or `routeWithHenosiaAuth` MUST be called from any protected page/route handler/server action — the
 middleware only performs a fast pre-check.
 
 ## App-switcher hook
@@ -159,15 +171,16 @@ export function MyAppSwitcher() {
 
 ## 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                            |
+| 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/server-guards`    | Page and route auth guards (`requireHenosiaAuth`, `routeWithHenosiaAuth`, ...)  |
+| `@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/platform.mjs

@@ -1,5 +1,6 @@
 /*! Copyright (c) 2026 Henosia ApS. Licensed under the Henosia Commercial Source License v1.0. See LICENSE */
 import { henosiaAuthConfig, isUnauthorizedException, verifyHenosiaAuthToken } from "../auth/server.mjs";
+import { applySecurityHeaders } from "../auth/server-guards.mjs";
 //#region src/api/platform/v1/app-switcher.ts
 /**
 * Handler for the Henosia Platform `app-switcher` endpoint.
@@ -15,10 +16,10 @@ async function handleAppSwitcher(request) {
 			redirect: "error",
 			headers: { authorization: `Bearer ${accessTokenResponse.idToken}` }
 		});
-		return Response.json(await response.json(), {
+		return applySecurityHeaders(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);

package/dist/auth/middleware.mjs

@@ -25,6 +25,7 @@ function delayWithCancel(delayMs) {
 }
 //#endregion
 //#region src/auth/middleware.ts
+const INVALID_SESSION_BODY = { error: "Your session is invalid or expired. Please reload the page to sign in again." };
 /**
 * Creates a Next.js middleware function that performs the Henosia Auth pre-check.
 *
@@ -67,14 +68,17 @@ function createHenosiaAuthMiddleware(options = {}) {
 				transferBetterAuthCookiesToNext(request, response);
 			} catch (e) {
 				if (!isUnauthorizedException(e)) {
-					console.error("[Middleware]", e);
+					console.error("[Henosia Auth] Middleware error", 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));
+		if (!getSessionCookie(request, { cookiePrefix })) {
+			if (request.method !== "GET") return NextResponse.json(INVALID_SESSION_BODY, { status: 401 });
+			return NextResponse.redirect(new URL(HENOSIA_AUTH_SIGN_IN_PATH_NAME, request.url));
+		}
 		try {
 			const { accessTokenResponse, payload, transferBetterAuthCookiesToNext } = await verifyHenosiaAuthToken(request);
 			transferBetterAuthCookiesToNext(request, response);
@@ -84,12 +88,12 @@ function createHenosiaAuthMiddleware(options = {}) {
 			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 });
+				if (!isPageRequest(request)) return NextResponse.json(INVALID_SESSION_BODY, { 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);
+				console.error("[Henosia Auth] Middleware error", e);
 				throw e;
 			}
 		}

package/dist/auth/server-guards.d.mts

@@ -0,0 +1,116 @@
+
+import { HenosiaAuthTokenClaims } from "./server.mjs";
+import { NextRequest, NextResponse } from "next/server.js";
+
+//#region src/auth/server-guards.d.ts
+/**
+ * For Server Components, layouts, and Server Actions.
+ *
+ * Verifies the current user's Henosia Auth token and returns the verified
+ * claims. On unauthorized, redirects to the Henosia sign-in page (the canonical
+ * page-level UX); other errors propagate so Next.js' error boundaries / 500
+ * page take over.
+ *
+ * Wrapped in `React.cache` so multiple components in the same render share a
+ * single verification.
+ *
+ * @example
+ * ```tsx
+ * // app/dashboard/page.tsx
+ * import { requireHenosiaAuth } from '@/lib/henosia-auth'
+ *
+ * export default async function Page() {
+ *   const claims = await requireHenosiaAuth()
+ *   return <Dashboard org={claims['https://henosia.com/organization']} />
+ * }
+ * ```
+ */
+declare const requireHenosiaAuth: () => Promise<HenosiaAuthTokenClaims>;
+/**
+ * Non-redirecting variant of {@link requireHenosiaAuth} for layouts and
+ * conditional UI (e.g., navbars that need to render either a "Sign in" button
+ * or a user menu). Returns `null` when the user is not authenticated; other
+ * errors propagate.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { getHenosiaAuth } from '@/lib/henosia-auth'
+ *
+ * export default async function RootLayout({ children }) {
+ *   const claims = await getHenosiaAuth()
+ *   return <Shell user={claims?.['https://henosia.com/organization']}>{children}</Shell>
+ * }
+ * ```
+ */
+declare const getHenosiaAuth: () => Promise<HenosiaAuthTokenClaims | null>;
+/**
+ * Context object passed to a `routeWithHenosiaAuth` handler
+ */
+interface HenosiaAuthContext {
+  /** Verified Henosia Auth JWT claims (project, organization, preview flag). */
+  payload: HenosiaAuthTokenClaims;
+  /**
+   * OAuth 2.0 access token, e.g. for forwarding to a downstream API as a
+   * `Authorization: Bearer …` header.
+   *
+   * **Security:** this is a bearer credential. Do **not** log it, echo it back
+   * in a response body, embed it in error messages, or persist it. Forward
+   * over TLS to trusted downstream services only. Treat it like a password.
+   */
+  accessToken: string;
+}
+/**
+ * A JSON-serializable value that the wrapper will auto-wrap with `NextResponse.json`.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue | undefined;
+};
+/**
+ * Allowed return types from a `routeWithHenosiaAuth` handler:
+ *  - A `Response` (returned verbatim — caller controls status/headers/body).
+ *  - A JSON-serializable value (auto-wrapped via `NextResponse.json`).
+ *  - `void` / `undefined` → translated to a `204 No Content` response.
+ */
+type HandlerReturn = Response | JsonValue | void;
+type RouteParams<TParams> = TParams | Promise<TParams>;
+type Handler<TParams> = (request: NextRequest, ctx: HenosiaAuthContext & {
+  params: TParams;
+}) => HandlerReturn | Promise<HandlerReturn>;
+declare function applySecurityHeaders(response: Response): Response;
+declare function unauthorizedResponse(): NextResponse;
+/**
+ * For Next.js Route Handlers (`app/api/**\/route.ts`).
+ *
+ * Wraps a handler so that:
+ *   - The request is verified up front.
+ *   - On success, the handler receives `{ payload, accessToken, params }` and
+ *     may return either a `Response`, any JSON-serializable value
+ *     (auto-wrapped via `NextResponse.json`), or `undefined` (→ `204
+ *     No Content`).
+ *   - On unauthorized, returns a canonical HTTP `401 Unauthorized` response
+ *     (RFC 7235): never a redirect.
+ *   - On any other error (verifying the token *or* thrown by the handler),
+ *     it's logged with the request's pathname for traceability and a generic
+ *     `500 Internal Server Error` JSON response is returned (no stack /
+ *     internal details leaked) — the same OAuth-shaped contract regardless of
+ *     where the failure originated.
+ *
+ * Preserves the standard Next.js `(request, { params })` signature, including
+ * Next 15's promise-typed `params`.
+ *
+ * @example
+ * ```ts
+ * // app/api/me/route.ts
+ * import { routeWithHenosiaAuth } from '@/lib/henosia-auth'
+ *
+ * export const GET = routeWithHenosiaAuth((_req, { payload }) => ({
+ *   organization: payload['https://henosia.com/organization'],
+ * }))
+ * ```
+ */
+declare function routeWithHenosiaAuth<TParams = Record<string, string | string[] | undefined>>(handler: Handler<TParams>): (request: NextRequest, routeCtx: {
+  params: RouteParams<TParams>;
+}) => Promise<Response>;
+//#endregion
+export { HenosiaAuthContext, applySecurityHeaders, getHenosiaAuth, requireHenosiaAuth, routeWithHenosiaAuth, unauthorizedResponse };