@zitadel/sdk-next 0.1.0-alpha.9 → 0.1.0

package/README.md

@@ -5,9 +5,37 @@ Next.js middleware and helpers for Nextgen Auth.
 ## Installation
 
 ```bash
-pnpm add @zitadel/sdk-next
+pnpm add @zitadel/sdk-next@latest
 ```
 
+Requires Next.js 15.2.3 or later. Earlier 15.x releases skip middleware for a
+request that sends an `x-middleware-subrequest` header (CVE-2025-29927), which
+on self-hosted deployments would let any request past `protectedRoutes`.
+
+## Requirements
+
+Peer dependencies: `next >=15.2.3`, `react >=18` and `react-dom >=18`.
+
+TypeScript ≥ 5.0, the floor shared by every SDK; see the [compatibility notes](https://github.com/zitadel/nextgen/blob/main/packages/AGENTS.md).
+
+## Entry points
+
+| Import                         | Runs in                          | Provides                                         |
+| ------------------------------ | -------------------------------- | ------------------------------------------------ |
+| `@zitadel/sdk-next/middleware` | Edge middleware                  | `nextgenMiddleware`, `createProxy`               |
+| `@zitadel/sdk-next/server`     | Server Components, Route Handlers | `auth()`, `NextgenProvider`                      |
+| `@zitadel/sdk-next/react`      | Client Components                | `useAuth()`, `AuthContextProvider`               |
+| `@zitadel/sdk-next/session`    | Client Components                | `getSession()`                                   |
+| `@zitadel/sdk-next/client`     | Client boundary                  | Web-component registration, `configureZitadel()` |
+| `@zitadel/sdk-next/components` | Client Components                | `ZitadelLogin`, `ZitadelLogout`, `ZitadelSession` |
+
+The package root re-exports the server and client surfaces together for use
+in server modules. Do not import the root from a `"use client"` module: it
+pulls in the server-only `auth()`, which fails the build with an import trace
+(exactly how depends on the bundler's tree shaking — the supported client
+imports are `/react` and `/session`). `NextgenProvider` is itself server-only
+because it accepts the token-bearing `auth()` result — see section 3.
+
 ## Setup
 
 ### 1. Middleware
@@ -35,62 +63,180 @@ The middleware runs on every matched route and does three things in one pass:
 
 1. **Proxies** `/__nextgen/*` requests to the auth backend
 2. **Verifies** the session JWT via JWKS using the Web Crypto API
-3. **Redirects** unauthenticated requests to `loginPath` for protected routes
+3. **Redirects** unauthenticated requests to `loginPath` for protected routes, with the requested path and query string in `?next=`, where `<zitadel-login>` returns after sign-in
 
 ### 2. Reading auth in a Server Component
 
-```ts
-import { auth } from "@zitadel/sdk-next";
+```tsx
+import { auth } from "@zitadel/sdk-next/server";
+import { Suspense } from "react";
 
-export default async function Page() {
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading…</p>}>
+      <Greeting />
+    </Suspense>
+  );
+}
+
+async function Greeting() {
   const session = await auth();
   if (!session.isAuthenticated) return <p>Not signed in</p>;
-  return <p>Hello {session.session.email}</p>;
+  return <p>Hello {session.session.display ?? session.session.identifier}</p>;
 }
 ```
 
+`auth()` reads the request, so whatever awaits it renders inside
+`<Suspense>`: with Cache Components on (`cacheComponents`, which
+`create-next-app` enables), Next.js refuses request data outside it.
+
+`auth()` reads the token the middleware tunnelled into the request headers
+and **verifies it before trusting it** — JWTs cryptographically via JWKS,
+opaque tokens against the backend's `GET /sessions/me` (which also supplies
+the user's identity). A forged `x-nextgen-auth-token` header sent directly by
+a client to a route outside the middleware `matcher` is rejected. Two things
+follow:
+
+- `auth()` only reports a session on routes the `matcher` covers — on other
+  routes the token never reaches it (see section 4 for chrome on public
+  pages).
+- If the middleware runs with custom verification options (`audience`,
+  `allowedAlgorithms`, …), pass the same values to `auth()` so both layers
+  accept the same tokens.
+
+`session.token` is the raw session token, available server-side for calling
+upstream APIs. Never forward it into client components yourself —
+`NextgenProvider` strips it for you (next section).
+
 ### 3. Reading auth in a Client Component
 
-Wrap your app in `NextgenProvider` (e.g. in your root layout):
+Seed the client tree once in your root layout (a Server Component), then
+read the state with `useAuth()` anywhere below it:
 
 ```tsx
-import { NextgenProvider } from '@zitadel/sdk-next';
+import { auth, NextgenProvider } from '@zitadel/sdk-next/server';
+import { Suspense } from 'react';
 
-export default async function RootLayout({ children }) {
-  const session = await auth();
+export default function RootLayout({ children }) {
   return (
     <html>
       <body>
-        <NextgenProvider value={session}>{children}</NextgenProvider>
+        <Suspense>
+          <AuthProvider>{children}</AuthProvider>
+        </Suspense>
       </body>
     </html>
   );
 }
+
+async function AuthProvider({ children }) {
+  const session = await auth();
+  return <NextgenProvider session={session}>{children}</NextgenProvider>;
+}
 ```
 
+`NextgenProvider` converts the `auth()` result to the client-safe shape
+**before** it crosses the server→client boundary: client components receive
+`userId` / `email` / `name`, and the raw session token never enters the RSC
+flight payload, where any script on the page could read it.
+
+That strip only protects you while it runs on the server, which is why
+`NextgenProvider` is server-only and **must not be re-exported through a
+`"use client"` wrapper** (the common `providers.tsx` pattern): the wrapper
+would become the client boundary, and its still-unstripped `session` prop —
+token included — would serialise into the flight payload before the provider
+ever ran. The `server-only` guard turns that wrapper into a build error
+instead of a silent leak. To seed the context from client-side state (e.g. a
+`getSession()` read), render `AuthContextProvider` from
+`@zitadel/sdk-next/react` — it only accepts the token-less
+`ClientAuthResult`.
+
 Then in any client component:
 
 ```tsx
 'use client';
-import { useAuth } from '@zitadel/sdk-next';
+import { useAuth } from '@zitadel/sdk-next/react';
 
 export function UserBadge() {
   const auth = useAuth();
-  return <span>{auth.isAuthenticated ? auth.session.email : 'Guest'}</span>;
+  return <span>{auth.isAuthenticated ? (auth.session.display ?? auth.session.identifier) : 'Guest'}</span>;
 }
 ```
 
-### 4. Login page
+`useAuth()` returns the same client-safe `ClientAuthResult` shape as
+`getSession()` and sdk-nuxt's `useAuth()`. It reflects what the server knew
+when the page rendered — which, like `auth()`, is only a live session on
+routes the middleware `matcher` covers.
+
+### 4. Session state for your own UI (any page)
 
-The `<zitadel-login>` web component (from `@zitadel/components`) must be rendered client-side only. Split it into a server wrapper and a client widget:
+`auth()` only sees a session on routes the middleware `matcher` covers, and the
+scaffolded matcher covers just the proxy path and the protected routes — so a
+header on a public page would always look signed out. For your app's own chrome
+(header navigation, account menus), read the session client-side with
+`getSession()` from `@zitadel/sdk-next/session`. It fetches the same-origin
+`{proxyPath}/sessions/me?project_id=…` — the same read the `<zitadel-session>`
+card performs — so it works on every page and the answer is the server's. The
+project is the `projectId` option, else the project of `configureZitadel()`,
+else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`; with none, it reads as signed out:
+
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+import { getSession, type ClientAuthResult } from '@zitadel/sdk-next/session';
+
+export function HeaderNav() {
+  // undefined = not yet known — render neutral chrome, not "Sign in".
+  const [auth, setAuth] = useState<ClientAuthResult>();
+  const [error, setError] = useState<Error>();
+  useEffect(() => {
+    getSession({ projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID }).then(setAuth, setError);
+  }, []);
+  if (error) return <span role="alert">Session unavailable</span>;
+  if (!auth) return null;
+  return auth.isAuthenticated ? (
+    <a href="/profile">{auth.session.display ?? auth.session.identifier ?? 'Account'}</a>
+  ) : (
+    <a href="/login">Sign in</a>
+  );
+}
+```
+
+A rejected `getSession()` means the state is *unknown* (broken proxy, network,
+5xx) — render a neutral or error state, never the signed-out CTAs.
+
+A `200` with a non-empty `user_id` resolves to
+`{ isAuthenticated: true, session: { userId, email, name } }` (client-safe —
+no token); the canonical `401/auth.unauthorized`, `403/sess.project_mismatch`
+(a session of another project on the same host), `404/sess.not_found`, and
+anonymous sessions resolve to signed out. The request
+and response are both marked no-store. Any other response — including malformed
+JSON or a framework's HTML 404 page from a misrouted proxy — throws so a broken
+proxy doesn't silently render as signed out. Sign-in and sign-out navigate
+(`post-sign-in-url` / `post-sign-out-url`), so chrome re-reads on the next page
+load without extra wiring; to react in place, listen for the widgets'
+`zitadel-signout` / `zitadel-flow-complete` events.
+
+### 5. Login page
+
+The `ZitadelLogin` component (the `@zitadel/sdk-react` wrapper, re-exported from `@zitadel/sdk-next/components`) must be rendered client-side only. Split it into a server wrapper and a client widget:
 
 ```tsx
 // app/login/page.tsx (server)
-import { auth } from '@zitadel/sdk-next';
+import { auth } from '@zitadel/sdk-next/server';
 import { redirect } from 'next/navigation';
+import { Suspense } from 'react';
 import { LoginWidget } from './widget';
 
-export default async function LoginPage() {
+export default function LoginPage() {
+  return (
+    <Suspense>
+      <SignedOutOnly />
+    </Suspense>
+  );
+}
+
+async function SignedOutOnly() {
   const session = await auth();
   if (session.isAuthenticated) redirect('/admin');
   return <LoginWidget />;
@@ -104,15 +250,19 @@ import dynamic from 'next/dynamic';
 
 const ZitadelLogin = dynamic(
   async () => {
-    await import('@zitadel/components');
+    // The /components entry registers the custom elements AND re-exports
+    // configureZitadel, so an app that only declares @zitadel/sdk-next
+    // resolves everything it needs (strict package managers would not
+    // resolve @zitadel/api or @zitadel/components transitively).
+    const { ZitadelLogin: Login, configureZitadel } = await import(
+      '@zitadel/sdk-next/components'
+    );
+    const project = configureZitadel({
+      projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID!,
+      proxyPath: '/__nextgen',
+    });
     return function ZitadelLoginElement() {
-      return (
-        <zitadel-login
-          api-base="/__nextgen"
-          project-id="demo"
-          post-sign-in-url="/admin"
-        />
-      );
+      return <Login project={project} postSignInUrl="/admin" />;
     };
   },
   { ssr: false },
@@ -123,12 +273,33 @@ export function LoginWidget() {
 }
 ```
 
+There is no `api-base` prop — pass the handle returned by `configureZitadel()`
+as `project`.
+
+## Widget events
+
+Each widget event reaches the callback in the last column, which receives the event's `detail` payload.
+
+| Widget event | Fires when | Detail | Widgets | Callback |
+| --- | --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login | `onFlowStep` |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login | `onFlowInput` |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login | `onFlowComplete` |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login | `onFlowRedirect` |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login | `onFlowError` |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session | `onSignout` |
+
+```tsx
+<ZitadelLogin project={project} theme="light" onFlowComplete={(detail) => track(detail)} />
+```
+
 ## Middleware options
 
 | Option              | Type                 | Default                  | Description                                                                                                                |
 | ------------------- | -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| `url`                 | `string`             | `ZITADEL_URL` env        | Full URL of the Zitadel auth backend                                                                                       |
-| `proxyPath`         | `string`             | `"/__nextgen"`           | Path prefix proxied to the auth backend                                                                                    |
+| `url`                 | `string`             | `ZITADEL_URL` env        | Full URL of the Zitadel auth backend. A trailing slash is ignored.                                                         |
+| `projectId`         | `string`             | `ZITADEL_PROJECT_ID`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID` | The project this app signs its users in to. A session of any other project on the server reads as signed out and keeps its cookie; with no project, no session counts. Pass the same value to `auth()` |
+| `proxyPath`         | `string`             | `"/__nextgen"`           | Path prefix proxied to the auth backend. Sign-in with an external provider currently requires the default: the provider returns to `/__nextgen/idp/{slug}/callback` |
 | `protectedRoutes`   | `string[]`           | `[]`                     | Paths requiring a valid session. Trailing `*` matches sub-paths                                                            |
 | `ignoredRoutes`     | `string[]`           | `[]`                     | Paths skipped entirely — no JWT check, no tunnelling. Useful for webhooks or health checks. Trailing `*` matches sub-paths |
 | `loginPath`         | `string`             | `"/login"`               | Where to redirect unauthenticated users                                                                                    |
@@ -136,17 +307,16 @@ export function LoginWidget() {
 | `allowedTokenTypes` | `string[]`           | `["JWT", "at+JWT"]`      | Accepted `typ` header values (case-insensitive). Set to `[]` to disable this check                                         |
 | `clockSkewMs`       | `number`             | `5000`                   | Clock skew tolerance in ms for `exp`, `nbf`, `iat`                                                                         |
 | `jwksTimeoutMs`     | `number`             | `5000`                   | Timeout in ms for JWKS endpoint requests. Token is rejected if the fetch exceeds this window                               |
+| `opaqueTokenTimeoutMs` | `number`          | `5000`                   | Timeout in ms for opaque (non-JWT) session validation via `GET /sessions/me`. Also accepted by `auth()`                    |
+| `proxyTimeoutMs`    | `number`             | `5000`                   | Timeout in ms for upstream proxy requests; requests exceeding it abort with a network error                                |
+| `jwtKey`            | `string`             | unset                    | Reserved for future use — local PEM public key for offline JWT verification                                                |
 | `audience`          | `string \| string[]` | not validated            | Expected `aud` claim value(s). When omitted, audience is not checked                                                       |
 
 ## How JWT verification works
 
-1. Bearer token from `Authorization` header is checked first; `__nextgen_session` cookie is the fallback
-2. The JWT header is decoded to extract `kid` and `alg`
-3. Tokens with an `alg` not in `allowedAlgorithms` (`RS256`, `ES256` by default) are rejected immediately — no JWKS fetch
-4. Tokens with a `typ` not in `allowedTokenTypes` are rejected immediately
-5. The public key is fetched from `{url}/oauth/v2/keys` (JWKS) using the Web Crypto API, with a 5 s timeout, and cached for 5 minutes per `kid`
-6. The signature is verified **before** any claim checks
-7. `iss` must be present and must equal `url` — tokens without an issuer are rejected
-8. `exp` must be present and must be in the future (with `clockSkewMs` tolerance) — tokens without an expiry are rejected
-9. `nbf` and `iat` are validated with `clockSkewMs` tolerance when present
-10. The `x-nextgen-auth-token` header is stripped from all proxied requests to prevent internal state leakage
+The verification pipeline is shared across SDKs and documented once in
+[`@zitadel/sdk-core`](https://github.com/zitadel/nextgen/tree/main/packages/sdk-core#how-jwt-verification-works).
+On top of that pipeline, the Next.js middleware adds:
+
+1. A request that carries an `x-nextgen-auth-token` header is refused with a 400 on every route, including ignored routes and the proxy path: the header is an internal channel that only the middleware writes, so a client never sends it
+2. `auth()` re-applies the same verification to the tunnelled token in the server runtime — the header alone is never treated as proof of a session

package/dist/auth.d.ts

@@ -1,17 +1,68 @@
-import { AuthResult } from '@zitadel/sdk-core/types';
-
+import "server-only";
+import type { AuthResult, NextgenMiddlewareOptions } from "./types.js";
+/**
+ * Options for {@link auth}.
+ *
+ * These mirror the token-verification subset of the middleware options. When
+ * the middleware runs with custom verification settings (a non-default
+ * `audience`, `allowedAlgorithms`, …), pass the same values here — otherwise
+ * a token the middleware accepted can fail re-verification in `auth()` and
+ * render as signed out.
+ */
+export type AuthOptions = Pick<NextgenMiddlewareOptions, "url" | "projectId" | "allowedAlgorithms" | "clockSkewMs" | "audience" | "allowedTokenTypes" | "jwksTimeoutMs" | "opaqueTokenTimeoutMs">;
 /**
  * Reads the auth state in a React Server Component or Next.js Route Handler.
  *
- * - **JWT tokens** are decoded locally (no backend round-trip).
- * - **Opaque encrypted tokens** have already been validated by the
- *   middleware via `GET /sessions/me`. If the `x-nextgen-auth-token`
- *   header is set, the session is authentic. Session details (email,
- *   name) are not available server-side for opaque tokens — use the
- *   `/__nextgen/sessions/me` proxy from a client component to fetch them.
+ * The session token arrives on the `x-nextgen-auth-token` request header,
+ * tunnelled there by the middleware — and `auth()` **verifies it before
+ * trusting it**:
+ *
+ * - **JWT tokens** are verified cryptographically (signature via JWKS,
+ *   issuer, expiry, algorithm and type allow-lists) using the same rules and
+ *   defaults as the middleware. The JWKS is cached in-process, so this does
+ *   not add a backend round-trip after the first call.
+ * - **Opaque encrypted tokens** are validated against the backend's
+ *   `GET /sessions/me`, which also supplies the user's identity (`userId`,
+ *   `email`, `name`). The lookup is deduplicated per render pass via React
+ *   `cache()`.
+ *
+ * The header alone is never proof of anything: on routes the middleware
+ * `matcher` does not cover, the middleware cannot refuse a forged
+ * client-supplied header, so `auth()` re-verifies every value it reads.
+ * A header value that fails verification is treated as signed out.
+ *
+ * Either way a session counts only in the app's own project: `projectId`,
+ * else `ZITADEL_PROJECT_ID`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`, else the
+ * project of `configureZitadel()` when it has run in this server runtime. A
+ * JWT must name it in `aud`; an opaque token must be a session of that
+ * project. With no project, nobody is signed in. A middleware built with
+ * `createProxy(config)` holds sessions to `config.projectId`: pass the same
+ * project here unless it comes from one of those variables.
+ *
+ * A backend that answers with an unexpected status, or not at all, reads as
+ * signed out and is logged, so a broken proxy or an unreachable backend is
+ * distinguishable from a missing session.
+ *
+ * **Matcher precondition (read this):** the middleware only tunnels the
+ * session token on routes covered by its `matcher`. On uncovered routes the
+ * cookie never reaches `auth()`, so `auth()` reports signed out even when a
+ * live session exists. Either extend the `matcher` to every route that calls
+ * `auth()`, or — for app chrome like headers and account menus — read the
+ * session client-side with `getSession()` from `@zitadel/sdk-next/session`,
+ * which works on any page.
+ *
+ * The backend URL comes from `options.url`, falling back to the same
+ * `ZITADEL_URL` environment variable the middleware uses. If the middleware
+ * runs with custom verification options (`audience`, `allowedAlgorithms`, …),
+ * pass the same values here; see {@link AuthOptions}.
+ *
+ * This module is server-only: importing it (or the package root) from a
+ * client component fails at build time. Client components read auth state
+ * from `@zitadel/sdk-next/react` (`useAuth()`) or
+ * `@zitadel/sdk-next/session` (`getSession()`).
  *
  * ```ts
- * import { auth } from "@zitadel/sdk-next";
+ * import { auth } from "@zitadel/sdk-next/server";
  *
  * export default async function Page() {
  *   const session = await auth();
@@ -20,8 +71,10 @@ import { AuthResult } from '@zitadel/sdk-core/types';
  * }
  * ```
  *
- * @returns The current {@link AuthResult}.
+ * @param options - Optional verification settings; see {@link AuthOptions}.
+ * @returns The current {@link AuthResult}. `session.token` is the raw session
+ *   token for calling upstream APIs server-side — never forward it into
+ *   client components (the `NextgenProvider` strips it for you).
  */
-declare function auth(): Promise<AuthResult>;
-
-export { auth };
+export declare function auth(options?: AuthOptions): Promise<AuthResult>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAQrB,OAAO,KAAK,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAIvE;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAC5B,wBAAwB,EACtB,KAAK,GACL,WAAW,GACX,mBAAmB,GACnB,aAAa,GACb,UAAU,GACV,mBAAmB,GACnB,eAAe,GACf,sBAAsB,CACzB,CAAC;AAgBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAsB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAsFzE"}

package/dist/auth.js

@@ -1,7 +1,162 @@
-import {
-  auth
-} from "./chunk-B7S6XMT3.js";
-import "./chunk-OCZMYSFX.js";
-export {
-  auth
-};
+import "server-only";
+import { getZitadelConfig } from "@zitadel/api/config";
+import { checkOpaqueSessionToken, jwtNamesProject } from "@zitadel/sdk-core/middleware";
+import { joinURL } from "ufo";
+import { headers } from "next/headers";
+import { cache } from "react";
+import { isJwtShaped, verifyJwt } from "./lib/jwt.js";
+/**
+ * Checks an opaque (non-JWT) session token against the backend's
+ * `GET /sessions/me`, held to `projectId` (see `checkOpaqueSessionToken` in
+ * `@zitadel/sdk-core`, which the middleware uses too).
+ *
+ * Wrapped in React's `cache()` so that many components calling `auth()` in
+ * the same render pass share a single backend round-trip. Arguments are
+ * primitives on purpose — `cache()` memoises by argument identity.
+ */
+const checkOpaqueSession = cache((token, issuerUrl, timeoutMs, projectId) => checkOpaqueSessionToken(token, issuerUrl, timeoutMs, projectId));
+/**
+ * Reads the auth state in a React Server Component or Next.js Route Handler.
+ *
+ * The session token arrives on the `x-nextgen-auth-token` request header,
+ * tunnelled there by the middleware — and `auth()` **verifies it before
+ * trusting it**:
+ *
+ * - **JWT tokens** are verified cryptographically (signature via JWKS,
+ *   issuer, expiry, algorithm and type allow-lists) using the same rules and
+ *   defaults as the middleware. The JWKS is cached in-process, so this does
+ *   not add a backend round-trip after the first call.
+ * - **Opaque encrypted tokens** are validated against the backend's
+ *   `GET /sessions/me`, which also supplies the user's identity (`userId`,
+ *   `email`, `name`). The lookup is deduplicated per render pass via React
+ *   `cache()`.
+ *
+ * The header alone is never proof of anything: on routes the middleware
+ * `matcher` does not cover, the middleware cannot refuse a forged
+ * client-supplied header, so `auth()` re-verifies every value it reads.
+ * A header value that fails verification is treated as signed out.
+ *
+ * Either way a session counts only in the app's own project: `projectId`,
+ * else `ZITADEL_PROJECT_ID`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`, else the
+ * project of `configureZitadel()` when it has run in this server runtime. A
+ * JWT must name it in `aud`; an opaque token must be a session of that
+ * project. With no project, nobody is signed in. A middleware built with
+ * `createProxy(config)` holds sessions to `config.projectId`: pass the same
+ * project here unless it comes from one of those variables.
+ *
+ * A backend that answers with an unexpected status, or not at all, reads as
+ * signed out and is logged, so a broken proxy or an unreachable backend is
+ * distinguishable from a missing session.
+ *
+ * **Matcher precondition (read this):** the middleware only tunnels the
+ * session token on routes covered by its `matcher`. On uncovered routes the
+ * cookie never reaches `auth()`, so `auth()` reports signed out even when a
+ * live session exists. Either extend the `matcher` to every route that calls
+ * `auth()`, or — for app chrome like headers and account menus — read the
+ * session client-side with `getSession()` from `@zitadel/sdk-next/session`,
+ * which works on any page.
+ *
+ * The backend URL comes from `options.url`, falling back to the same
+ * `ZITADEL_URL` environment variable the middleware uses. If the middleware
+ * runs with custom verification options (`audience`, `allowedAlgorithms`, …),
+ * pass the same values here; see {@link AuthOptions}.
+ *
+ * This module is server-only: importing it (or the package root) from a
+ * client component fails at build time. Client components read auth state
+ * from `@zitadel/sdk-next/react` (`useAuth()`) or
+ * `@zitadel/sdk-next/session` (`getSession()`).
+ *
+ * ```ts
+ * import { auth } from "@zitadel/sdk-next/server";
+ *
+ * export default async function Page() {
+ *   const session = await auth();
+ *   if (!session.isAuthenticated) return <p>Not signed in</p>;
+ *   return <p>Hello {session.session.userId}</p>;
+ * }
+ * ```
+ *
+ * @param options - Optional verification settings; see {@link AuthOptions}.
+ * @returns The current {@link AuthResult}. `session.token` is the raw session
+ *   token for calling upstream APIs server-side — never forward it into
+ *   client components (the `NextgenProvider` strips it for you).
+ */
+export async function auth(options = {}) {
+    const headerStore = await headers();
+    const token = headerStore.get("x-nextgen-auth-token");
+    if (!token) {
+        return { isAuthenticated: false, session: null };
+    }
+    const { url = process.env.ZITADEL_URL ?? "http://localhost:8080", projectId = process.env.ZITADEL_PROJECT_ID ||
+        process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID ||
+        getZitadelConfig()?.projectId, allowedAlgorithms = ["RS256", "ES256"], clockSkewMs = 5000, audience, allowedTokenTypes = ["JWT", "at+JWT"], jwksTimeoutMs, opaqueTokenTimeoutMs = 5000, } = options;
+    if (!projectId) {
+        warnMissingProject();
+        return { isAuthenticated: false, session: null };
+    }
+    if (isJwtShaped(token)) {
+        const payload = await verifyJwt(token, {
+            issuerUrl: url,
+            allowedAlgorithms,
+            clockSkewMs,
+            audience,
+            allowedTokenTypes,
+            jwksTimeoutMs,
+        });
+        if (payload?.sub && jwtNamesProject(payload, projectId)) {
+            return {
+                isAuthenticated: true,
+                session: {
+                    userId: payload.sub,
+                    identifier: payload.email ?? null,
+                    identifierProperty: null,
+                    display: payload.name ?? null,
+                    token,
+                },
+            };
+        }
+        if (payload?.sub) {
+            // Verified, but issued for another project: not a user of this one.
+            return { isAuthenticated: false, session: null };
+        }
+        // A middleware-tunnelled JWT always verifies (the middleware applied the
+        // same checks moments earlier). Reaching this branch means the header was
+        // NOT vetted by the middleware — a route outside the `matcher` received a
+        // client-forged header — or the JWKS endpoint is unreachable from this
+        // runtime, or auth() runs with verification options that diverge from the
+        // middleware's.
+        console.warn("[nextgen] auth(): rejected an x-nextgen-auth-token header that failed JWT " +
+            "verification. If this route is not covered by the middleware matcher, this was " +
+            "a forged client header; otherwise check that auth() and the middleware use the " +
+            `same verification options and that the JWKS endpoint at ${joinURL(url, "/auth/keys")} is reachable.`);
+        return { isAuthenticated: false, session: null };
+    }
+    // A refused session, an anonymous one and one of another project read as
+    // signed out here. So does a check without a verdict, which
+    // `checkOpaqueSessionToken` logs with its cause.
+    const check = await checkOpaqueSession(token, url, opaqueTokenTimeoutMs, projectId);
+    if (check.verdict === "live" && check.session.userId) {
+        return {
+            isAuthenticated: true,
+            session: {
+                userId: check.session.userId,
+                identifier: check.session.identifier,
+                identifierProperty: check.session.identifierProperty,
+                display: check.session.display,
+                token,
+            },
+        };
+    }
+    return { isAuthenticated: false, session: null };
+}
+let warnedMissingProject = false;
+/** Says once per process why `auth()` signs no one in: no project is configured. */
+function warnMissingProject() {
+    if (warnedMissingProject) {
+        return;
+    }
+    warnedMissingProject = true;
+    console.warn("[nextgen] auth(): no project id is configured, so no session counts as signed in. " +
+        "Set ZITADEL_PROJECT_ID, or pass the middleware's `projectId` to auth() (with " +
+        "createProxy(config), that is config.projectId).");
+}

package/dist/client.d.ts

@@ -1,2 +1,27 @@
-export { ZitadelLogin, ZitadelLogout } from '@zitadel/components';
-export { ZitadelConfig, ZitadelProject, configureZitadel, getApi } from '@zitadel/api/config';
+/**
+ * Registers the `<zitadel-login>`, `<zitadel-logout>` and `<zitadel-session>`
+ * Lit web components for use in Next.js apps.
+ *
+ * Import this inside a `"use client"` boundary (e.g. a dynamic import
+ * with `{ ssr: false }`) to register the custom elements with the
+ * browser's global registry:
+ *
+ * ```ts
+ * await import("@zitadel/sdk-next/client");
+ * ```
+ *
+ * On an edge runtime the components package resolves to an entry without the
+ * elements, so this entry still loads there.
+ *
+ * SDK configuration is done via `configureZitadel()`, re-exported here so
+ * a consuming app that only declares `@zitadel/sdk-next` as a direct
+ * dependency can configure the SDK without reaching into
+ * `@zitadel/api/config` (which strict package managers would not
+ * resolve). Call it inside the same `"use client"` boundary before the
+ * components mount.
+ */
+import "@zitadel/components";
+export { businessLocales } from "@zitadel/components";
+export { configureZitadel, getApi } from "@zitadel/api/config";
+export type { ZitadelConfig, ZitadelProject } from "@zitadel/api/config";
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,qBAAqB,CAAC;AAI7B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}