@henosia/app-next 1.0.3 → 1.0.5

package/.agents/skills/henosia-app-next/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: henosia-app-next
+description: |
+  Integrate the `@henosia/app-next` package into a Next.js app: install,
+  configure middleware, mount the better-auth and Henosia Platform catch-all
+  routes, wire up the sign-in page, and (optionally) add the app switcher and
+  Supabase helpers. Load this skill when adding `@henosia/app-next` to a
+  project, scaffolding a new Henosia-Auth-backed Next.js app, or troubleshooting
+  the integration scaffolding (middleware, sign-in route, providers,
+  re-exports). For per-page / per-route authorization once integration is in
+  place, use the `henosia-auth-guards` skill instead.
+enabled: false # flip to true to enable during Henosia Auth integration in projects with legacy auth
+---
+
+# Integrating `@henosia/app-next`
+
+`@henosia/app-next` is the Henosia integration for Next.js apps. It provides:
+
+- Henosia Auth middleware (pre-check + token refresh + optional Supabase session exchange).
+- better-auth and Henosia Platform catch-all Route Handlers.
+- A React `authClient` (better-auth) and a `useAppSwitcher` hook.
+- Optional Supabase server/browser client factories.
+- Server-side auth guards — see the **`henosia-auth-guards` skill** for those
+  (this skill covers the one-time integration; that skill covers the per-route
+  authorization work an agent does on every protected page/route/server action).
+
+## Authoritative reference
+
+For complete and up-to-date package usage details (peer dependencies, subpath
+exports, Supabase exchange behavior, app-switcher hook options), read:
+
+- `node_modules/@henosia/app-next/README.md`
+
+The README is the source of truth. This skill summarizes the integration
+workflow and explains how to use the bundled reference template.
+
+## Environment variables — do not edit
+
+`@henosia/app-next` requires several env vars (`BETTER_AUTH_URL`,
+`BETTER_AUTH_SECRET`, `HENOSIA_AUTH_*`, optional `NEXT_PUBLIC_SUPABASE_*`). In
+the consuming app, **these are provided automatically by the Henosia builder
+environment** which is where this skill is invoked from.
+
+- ❌ Do **not** add Henosia env vars to `.env.local`, deployment
+  config, or CI scripts.
+- ❌ Do **not** read or echo their values back to the user.
+- ✅ Treat the env as a managed contract. If a value is missing at runtime, the
+  package surfaces a `[Henosia Auth] Missing required env var: …` error — that
+  is a Henosia environment issue, not a code change.
+- See the README "Required environment variables" section for the full list and
+  what each one is for, but you should not need to set any of them yourself.
+
+## Reference template (use this as the starting point)
+
+The package ships a working reference template at:
+
+```
+node_modules/@henosia/app-next/.agents/skills/henosia-app-next/assets/template/
+```
+
+Use it as the source for all integration files. **Always copy or merge from the
+template — do not re-derive these files from scratch.**
+
+### File-to-target-path map
+
+| Template file                                | Target in consuming app                      | Required?                                  |
+|----------------------------------------------|----------------------------------------------|--------------------------------------------|
+| `middleware.ts`                              | `middleware.ts` (app root)                   | Required                                   |
+| `app/api/auth/[...all]/route.ts`             | Same path                                    | Required                                   |
+| `app/api/henosia-platform/[...all]/route.ts` | Same path                                    | Required                                   |
+| `lib/auth-client.ts`                         | `lib/auth-client.ts` (or app's equivalent)   | Required                                   |
+| `app/(auth)/sign-in/page.tsx`                | A route that resolves to `/sign-in`          | Required                                   |
+| `app/(auth)/sign-in/loading.tsx`             | Same folder as the sign-in page              | Recommended                                |
+| `components/sign-in.tsx`                     | `components/sign-in.tsx`                     | Required (used by the sign-in page)        |
+| `app/layout.tsx`                             | Merge into existing root layout              | Required (partial merge)                   |
+| `components/query-provider.tsx`              | `components/query-provider.tsx`              | Required if using the app switcher         |
+| `components/app-switcher.tsx`                | `components/app-switcher.tsx`                | Optional (only if surfacing the switcher)  |
+| `components/nav-user.tsx`                    | `components/nav-user.tsx`                    | Optional (only if surfacing user identity) |
+| `lib/supabase/server.ts`                     | `lib/supabase/server.ts`                     | Optional (only if using Supabase)          |
+| `lib/supabase/client.ts`                     | `lib/supabase/client.ts`                     | Optional (only if using Supabase)          |
+| `package.json`                               | Additive merge into existing `package.json`  | Required (additive)                        |
+| `tsconfig.json`                              | Additive merge into existing `tsconfig.json` | Required (additive)                        |
+| `next.config.mjs`                            | Additive merge into existing `next.config.*` | Required (additive)                        |
+
+The sign-in page lives under the `(auth)` Next.js route group in the template.
+The route group itself is an organization choice; what matters is that the
+URL path resolves to `/sign-in` (the value of `HENOSIA_AUTH_SIGN_IN_PATH_NAME`).
+
+### Template conventions — follow exactly
+
+When copying a template file into the consuming app, apply these rules:
+
+1. **Strip `//@ts-nocheck (remove when using the template)`** from the first
+   line of every copied file. It exists only so the template files type-check
+   in isolation here.
+2. **Strip `// Template use guidance: …`** lines. They are instructions for the
+   integrating agent (you), not for the consuming app.
+3. **Preserve verbatim** every comment from `// To Henosia assistant regarding
+   this file:` to end-of-file. These currently appear in `middleware.ts` and
+   `app/api/auth/[...all]/route.ts`. They protect the Henosia Auth flows from
+   well-intentioned future edits and **must remain in the consuming app's
+   files**, byte-for-byte.
+4. **`package.json` is an additive merge.** The template uses
+   `"__add_these__:"` and `"__others_omitted_for_brevity__"` sentinel keys to
+   mark merge boundaries. Add the listed deps to the consuming app's existing
+   `dependencies` (preserve everything already there). Use the template's
+   pinned versions for `@henosia/app-next`, `@tanstack/react-query`, and
+   `better-auth` unless the consuming app already has a newer compatible
+   version. Drop the sentinel keys when merging.
+5. **`tsconfig.json` is an additive merge.** Ensure the consuming app has the
+   `@/*` path alias under `compilerOptions.paths` and the `next` plugin under
+   `compilerOptions.plugins`; the template's other settings are typical Next.js
+   defaults — only fold them in if missing.
+6. **`app/layout.tsx` is a partial merge.** Preserve the host app's existing
+   layout structure (fonts, metadata, theming, providers, slots, etc.). Fold
+   in only:
+   - The `usePathname()` import + `path !== HENOSIA_AUTH_SIGN_IN_PATH_NAME`
+     branching, so the sign-in page renders without the host app's chrome.
+   - The `<QueryProvider>` wrap (required for the app switcher and any other
+     `@tanstack/react-query` consumer).
+   The template comment `// Preserve the existing layout elements as it stands
+   today when using this template` is the directive — follow it.
+7. **`components/sign-in.tsx`, `app-switcher.tsx`, `nav-user.tsx` are
+   reference UIs.** Adapt the visuals to the host app's design system, but
+   **preserve the Henosia-specific behavior**:
+   - `sign-in.tsx`: keep `signIn.social({ provider: "henosia", callbackURL: "/" })`,
+     the `data-henosia-auth-sign-in` attribute on the trigger, and the
+     `loading` UX around the call.
+   - `app-switcher.tsx`: keep the `useAppSwitcher({ enabled: open })` hook
+     usage, the `groupedApps` rendering, and the `error` / `isLoading` paths.
+   - `nav-user.tsx`: keep `authClient.useSession()`, and on sign-out keep the
+     `router.push(HENOSIA_AUTH_SIGN_IN_PATH_NAME)` + `router.refresh()`
+     sequence inside `authClient.signOut`'s `onSuccess`.
+8. **The thin re-export files** (`lib/auth-client.ts`, `lib/supabase/server.ts`,
+   `lib/supabase/client.ts`) exist so the rest of the consuming app imports
+   from `@/lib/...` and the `@henosia/app-next` subpaths are referenced from
+   exactly one place. Keep them as one-line re-exports.
+
+## Integration checklist
+
+Work through these in order. Most steps map directly to a template file or a
+README section.
+
+1. **Install the package and peer dependencies.** See README "Installation".
+   Use `pnpm`/`npm`/`yarn` per the host app's convention. Install
+   `@supabase/ssr` and `@supabase/supabase-js` only if the app uses Supabase.
+2. **Do not configure env vars.** They are provided by the Henosia builder
+   environment (see "Environment variables — do not edit" above).
+3. **Add `middleware.ts`** at the app root. Copy from the template, applying
+   the template-conventions rules. Keep the `// To Henosia assistant…` block.
+4. **Mount `app/api/auth/[...all]/route.ts`** by re-exporting `GET, POST` from
+   `@henosia/app-next/api/auth`. Copy from the template; keep the `// To
+   Henosia assistant…` block.
+5. **Mount `app/api/henosia-platform/[...all]/route.ts`** by re-exporting `GET`
+   from `@henosia/app-next/api/platform`. Copy from the template.
+6. **Add the React auth client re-export** at `lib/auth-client.ts`.
+7. **Create the sign-in route at `/sign-in`.** Copy `app/(auth)/sign-in/page.tsx`,
+   `app/(auth)/sign-in/loading.tsx`, and `components/sign-in.tsx`. The
+   route group is optional; the resolved URL must be `/sign-in`.
+8. **Merge `app/layout.tsx`** per the partial-merge rule. Wrap the tree with
+   `<QueryProvider>` and skip the host app's chrome on
+   `HENOSIA_AUTH_SIGN_IN_PATH_NAME`.
+9. **Add `<QueryProvider>`** (`components/query-provider.tsx`) if you don't
+   already have a `QueryClientProvider` higher in the tree. Required for
+   `useAppSwitcher` and any other `@tanstack/react-query` consumer.
+10. **(Optional) Add the app switcher.** Copy `components/app-switcher.tsx`
+    where you want it in your shell (e.g. inside a `<Sidebar>`). It depends on
+    shadcn/ui primitives — install the ones it imports if missing.
+11. **(Optional) Add the user nav / sign-out menu.** Copy
+    `components/nav-user.tsx`. Adapt visuals; keep the Henosia behavior.
+12. **(Optional) Add Supabase helpers.** When `NEXT_PUBLIC_SUPABASE_URL` is
+    set in the Henosia builder env, install the Supabase peer deps and copy
+    `lib/supabase/server.ts` and `lib/supabase/client.ts` from the template.
+    The middleware automatically exchanges the Henosia Auth token for a
+    Supabase session — no extra wiring required. See README "5. (Optional)
+    Supabase helpers".
+13. **Protect every non-public page, layout, server action, and route
+    handler.** Use the **`henosia-auth-guards` skill**. The middleware is a
+    pre-check only — it does **not** satisfy the per-route authorization
+    requirement.
+14. Carefully remove the old auth flow components and routes that Henosia Auth replaces 
+
+## Subpath imports cheat sheet
+
+```ts
+// Server-side helpers (advanced; prefer the auth guards)
+import { auth, verifyHenosiaAuthToken, isUnauthorizedException, isPageRequest, HENOSIA_AUTH_SIGN_IN_PATH_NAME } from '@henosia/app-next'
+
+// Shared constants & types (no runtime deps; safe to import from server or client)
+import { HENOSIA_AUTH_SIGN_IN_PATH_NAME, HENOSIA_AUTH_GET_SESSION_PATH_NAME, HENOSIA_ORGANIZATION_CTX_COOKIE } from '@henosia/app-next/shared'
+import type { HenosiaOrganizationContext } from '@henosia/app-next/shared'
+
+// Middleware
+import { createHenosiaAuthMiddleware } from '@henosia/app-next/auth/middleware'
+
+// Server-side auth guards (see henosia-auth-guards skill)
+import { requireHenosiaAuth, getHenosiaAuth, routeWithHenosiaAuth } from '@henosia/app-next/auth/server-guards'
+
+// React auth client
+import { authClient } from '@henosia/app-next/auth/client'
+
+// Catch-all route re-exports
+export { GET, POST } from '@henosia/app-next/api/auth'
+export { GET }       from '@henosia/app-next/api/platform'
+
+// App-switcher hook
+import { useAppSwitcher } from '@henosia/app-next/platform/app-switcher'
+
+// Supabase helpers (peer deps required)
+import { createClient } from '@henosia/app-next/supabase/server'
+import { createClient } from '@henosia/app-next/supabase/client'
+```
+
+## Lower-level helpers — usually not needed
+
+`auth`, `verifyHenosiaAuthToken`, `isUnauthorizedException`, `isPageRequest` are
+exported from the package root for advanced/edge cases. For protecting pages
+and routes, **always prefer the guards** documented in the
+`henosia-auth-guards` skill. They encode the canonical redirect / 401 / 500
+contract, apply the correct security headers, and integrate with React's
+`cache()` for per-render deduplication.
+
+## See also
+
+- `henosia-auth-guards` skill — the per-page/per-route authorization workflow.
+  You will need this on virtually every Henosia-Auth-backed Next.js project.
+- `@henosia/app-next` README at `node_modules/@henosia/app-next/README.md`.
+- Reference template at `node_modules/@henosia/app-next/.agents/skills/henosia-app-next/assets/template/`.

package/.agents/skills/henosia-app-next/assets/template/app/(auth)/sign-in/loading.tsx

@@ -0,0 +1,10 @@
+export default function SignInLoading() {
+	return (
+		<div className="flex min-h-screen items-center justify-center">
+			<div className="text-center">
+				<div className="h-8 w-8 animate-spin rounded-full border-4 border-gray-300 border-t-gray-900 mx-auto"></div>
+				<p className="mt-4 text-gray-600">Loading...</p>
+			</div>
+		</div>
+	);
+}

package/.agents/skills/henosia-app-next/assets/template/app/(auth)/sign-in/page.tsx

@@ -0,0 +1,15 @@
+"use client";
+import {SignIn} from "@/components/sign-in";
+
+export default function Page() {
+
+	return (
+		<div className="w-full">
+			<div className="flex items-center flex-col justify-center w-full md:py-10">
+				<div className="md:w-[400px]">
+					<SignIn />
+				</div>
+			</div>
+		</div>
+	);
+}

package/.agents/skills/henosia-app-next/assets/template/app/api/auth/[...all]/route.ts

@@ -0,0 +1,9 @@
+//@ts-nocheck (remove when using the template)
+// Template use guidance: Preserve comments verbatim from the line `// To Henosia assistant regarding this file:` and below
+export { GET, POST } from '@henosia/app-next/api/auth'
+
+// 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.
+// All non-public pages and routes must be protected 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/app/api/henosia-platform/[...all]/route.ts

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

package/.agents/skills/henosia-app-next/assets/template/app/layout.tsx

@@ -0,0 +1,35 @@
+//@ts-nocheck (remove when using the template)
+// this partial layout file illustrates how to modify the layout based on whether the path is the sign in page
+// it should be merged with the existing layout's structure and dependencies
+"use client";
+import type * as React from "react";
+import { usePathname } from "next/navigation";
+import {HENOSIA_AUTH_SIGN_IN_PATH_NAME} from "@henosia/app-next/shared";
+import { QueryProvider } from "@/components/query-provider";
+
+// ... other required imports and setup, e.g. fonts
+
+export default function RootLayout({
+  children
+}: Readonly<{
+  children: React.ReactNode;
+  breadcrumb: React.ReactNode;
+}>) {
+  const path = usePathname();
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+          <QueryProvider>
+            {path !== HENOSIA_AUTH_SIGN_IN_PATH_NAME ? (
+                <>
+                  {/* Preserve the existing layout elements as it stands today when using this template */}
+                  <main>{children}</main>
+                </>
+            ) : (
+              children
+            )}
+          </QueryProvider>
+      </body>
+    </html>
+  );
+}

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

@@ -0,0 +1,148 @@
+//@ts-nocheck (remove when using the template)
+"use client"
+
+import * as React from "react"
+import {useState} from "react";
+import {ChevronsUpDown, GalleryVerticalEnd, Plus, PanelTop} from "lucide-react"
+
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover"
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+} from "@/components/ui/command"
+import {
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  useSidebar,
+} from "@/components/ui/sidebar"
+import {Skeleton} from "@/components/ui/skeleton";
+import {AppSwitcherApp, useAppSwitcher} from "@henosia/app-next/platform/app-switcher";
+
+export function AppSwitcher() {
+  const { isMobile } = useSidebar();
+  const [open, setOpen] = useState(false);
+
+  const {organization, groupedApps, error, isLoading} = useAppSwitcher({
+    enabled: open
+  });
+
+  const handleSelectApp = (app: AppSwitcherApp) => {
+    window.open(app.url);
+    setOpen(false);
+  };
+
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <Popover open={open} onOpenChange={setOpen}>
+          <PopoverTrigger asChild>
+            <SidebarMenuButton
+              size="lg"
+              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
+            >
+              <div className="flex aspect-square size-8 items-center justify-center rounded-lg text-sidebar-primary-foreground">
+                {organization ? (
+                  <>
+                    {organization.logoUrl ? (
+                      <>
+                        {/* eslint-disable-next-line @next/next/no-img-element */}
+                        <img alt={`Logo for ${organization.name}`} src={organization.logoUrl} className={"size-6"} />
+                      </>
+                    ) : (
+                      <GalleryVerticalEnd className={"size-4 text-primary"} />
+                    )}
+                  </>
+                ) : (
+                  <Skeleton className={"size-6 opacity-40 rounded-lg"} />
+                )}
+              </div>
+              <div className="grid flex-1 text-left text-sm leading-tight">
+                <span className="truncate font-semibold">
+                  {organization?.name ?? <Skeleton className={"w-16 h-[1em] opacity-40"} />}
+                </span>
+              </div>
+              <ChevronsUpDown className="ml-auto" />
+            </SidebarMenuButton>
+          </PopoverTrigger>
+          <PopoverContent
+            className="w-[22rem] rounded-lg p-0"
+            align="start"
+            side={isMobile ? "bottom" : "right"}
+            sideOffset={4}
+          >
+            <Command>
+              <CommandInput placeholder="Search apps…" />
+              <CommandList className="max-h-[80vh]">
+                {isLoading ? (
+                  <div className="flex flex-col gap-1 p-2" role="status" aria-label="Loading apps">
+                    {Array.from({ length: 3 }).map((_, i) => (
+                      <React.Fragment key={i}>
+                        {i === 0 && (<div className={"p-2"}><Skeleton className="h-2 w-24" /></div>)}
+                        <div key={i} className="flex items-center gap-2 p-2">
+                          <Skeleton className="size-6 rounded-sm" />
+                          <Skeleton className="h-3 flex-1" />
+                        </div>
+                      </React.Fragment>
+                    ))}
+                  </div>
+                ) : error ? (
+                  <div className="p-4 text-sm text-destructive">
+                    {error.message ?? 'Failed to load apps.'}
+                  </div>
+                ) : (
+                  <>
+                    <CommandEmpty>No apps found.</CommandEmpty>
+                    {groupedApps.map(({ group, apps }) => (
+                      <CommandGroup key={group} heading={group}>
+                        {apps.map((app) => (
+                          <CommandItem
+                            key={app.id}
+                            value={`${group} ${app.name}`}
+                            onSelect={() => handleSelectApp(app)}
+                            className="gap-2 p-2"
+                            title={`${app.name} – ${app.url}`}
+                          >
+                            <div className="flex size-6 items-center justify-center rounded-sm border bg-background">
+                              <PanelTop className="size-4 shrink-0" />
+                            </div>
+                            <span className="truncate">{app.name}</span>
+                          </CommandItem>
+                        ))}
+                      </CommandGroup>
+                    ))}
+                  </>
+                )}
+                <CommandSeparator />
+                <CommandGroup>
+                  <CommandItem
+                    disabled={isLoading}
+                    onSelect={() => {
+                      window.open('https://app.henosia.com/app');
+                      setOpen(false)
+                    }}
+                    className="gap-2 p-2"
+                  >
+                    <div className="flex size-6 items-center justify-center rounded-md border bg-background">
+                      <Plus className="size-4" />
+                    </div>
+                    <div className="font-medium text-muted-foreground">Build new app</div>
+                  </CommandItem>
+                </CommandGroup>
+              </CommandList>
+            </Command>
+          </PopoverContent>
+        </Popover>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  )
+}

package/.agents/skills/henosia-app-next/assets/template/components/nav-user.tsx

@@ -0,0 +1,143 @@
+//@ts-nocheck (remove when using the template)
+"use client"
+
+import {
+  BadgeCheck,
+  ChevronsUpDown,
+  LogOut,
+} from "lucide-react"
+
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+} from "@/components/ui/avatar"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+import {
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  useSidebar,
+} from "@/components/ui/sidebar"
+import { Skeleton } from "@/components/ui/skeleton"
+import Link from "next/link"
+import { useRouter } from "next/navigation"
+import { authClient } from "@/lib/auth-client";
+import { HENOSIA_AUTH_SIGN_IN_PATH_NAME } from "@henosia/app-next/shared"
+
+function getInitials(name?: string | null): string {
+  if (!name) return ""
+  const parts = name.trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return ""
+  if (parts.length === 1) return parts[0].slice(0, 2).toUpperCase()
+  return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase()
+}
+
+export function NavUser() {
+  const { isMobile } = useSidebar()
+  const router = useRouter()
+  const { data: session, isPending } = authClient.useSession()
+
+  if (isPending) {
+    return (
+      <SidebarMenu>
+        <SidebarMenuItem>
+          <SidebarMenuButton size="lg" disabled>
+            <Skeleton className="h-8 w-8 rounded-lg" />
+            <div className="grid flex-1 gap-1 text-left text-sm leading-tight">
+              <Skeleton className="h-3 w-24" />
+              <Skeleton className="h-3 w-32" />
+            </div>
+          </SidebarMenuButton>
+        </SidebarMenuItem>
+      </SidebarMenu>
+    )
+  }
+
+  const sessionUser = session?.user
+  if (!sessionUser) {
+    return null
+  }
+
+  const name = sessionUser.name ?? ""
+  const email = sessionUser.email ?? ""
+  const avatar = sessionUser.image ?? undefined
+  const initials = getInitials(name || email)
+
+  const handleSignOut = async () => {
+    await authClient.signOut({
+      fetchOptions: {
+        onSuccess: () => {
+          router.push(HENOSIA_AUTH_SIGN_IN_PATH_NAME)
+          router.refresh()
+        },
+      },
+    })
+  }
+
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <SidebarMenuButton
+              size="lg"
+              className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
+            >
+              <Avatar className="h-8 w-8 rounded-lg">
+                {avatar ? <AvatarImage src={avatar} alt={name} /> : null}
+                <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
+              </Avatar>
+              <div className="grid flex-1 text-left text-sm leading-tight">
+                <span className="truncate font-semibold">{name}</span>
+                <span className="truncate text-xs">{email}</span>
+              </div>
+              <ChevronsUpDown className="ml-auto size-4" />
+            </SidebarMenuButton>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            className="w-[--radix-dropdown-menu-trigger-width] min-w-56 rounded-lg"
+            side={isMobile ? "bottom" : "right"}
+            align="end"
+            sideOffset={4}
+          >
+            <DropdownMenuLabel className="p-0 font-normal">
+              <div className="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
+                <Avatar className="h-8 w-8 rounded-lg">
+                  {avatar ? <AvatarImage src={avatar} alt={name} /> : null}
+                  <AvatarFallback className="rounded-lg">{initials}</AvatarFallback>
+                </Avatar>
+                <div className="grid flex-1 text-left text-sm leading-tight">
+                  <span className="truncate font-semibold">{name}</span>
+                  <span className="truncate text-xs">{email}</span>
+                </div>
+              </div>
+            </DropdownMenuLabel>
+            <DropdownMenuSeparator />
+            <DropdownMenuGroup>
+              <DropdownMenuItem asChild={true}>
+                <Link target={'_blank'} href={"https://app.henosia.com/settings/profile"}>
+                  <BadgeCheck />
+                  Profile
+                </Link>
+              </DropdownMenuItem>
+            </DropdownMenuGroup>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onSelect={handleSignOut}>
+              <LogOut />
+              Log out
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  )
+}

package/.agents/skills/henosia-app-next/assets/template/components/query-provider.tsx

@@ -0,0 +1,23 @@
+//@ts-nocheck (remove when using the template)
+"use client";
+
+import * as React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = React.useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: 60 * 1000,
+            refetchOnWindowFocus: false,
+          },
+        },
+      })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}

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/dist/auth/server.mjs

@@ -59,7 +59,8 @@ const henosiaAuthConfig = {
 * 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");
+	const { headers } = request;
+	const dest = headers.get("X-Henosia-Fetch-Dest") ?? 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henosia/app-next",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Henosia integration for Next.js apps: Provides Henosia Auth and Henosia Platform features like app switcher",
   "author": "Henosia",
   "license": "SEE LICENSE IN LICENSE",
@@ -15,6 +15,7 @@
   "type": "module",
   "files": [
     "dist",
+    ".agents/skills",
     "LICENSE"
   ],
   "scripts": {