@zitadel/sdk-next 1.0.0-alpha.25 → 1.0.0-alpha.28

package/README.md

@@ -5,9 +5,19 @@ Next.js middleware and helpers for Nextgen Auth.
 ## Installation
 
 ```bash
-pnpm add @zitadel/sdk-next
+pnpm add @zitadel/sdk-next@alpha
 ```
 
+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                                         |
@@ -52,20 +62,33 @@ 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
+```tsx
 import { auth } from "@zitadel/sdk-next/server";
+import { Suspense } from "react";
+
+export default function Page() {
+  return (
+    <Suspense fallback={<p>Loading…</p>}>
+      <Greeting />
+    </Suspense>
+  );
+}
 
-export default async function Page() {
+async function Greeting() {
   const session = await auth();
   if (!session.isAuthenticated) return <p>Not signed in</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
@@ -91,17 +114,24 @@ read the state with `useAuth()` anywhere below it:
 
 ```tsx
 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 session={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
@@ -144,8 +174,10 @@ 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` — the same read the `<zitadel-session>` card performs —
-so it works on every page and the answer is the server's:
+`{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';
@@ -157,7 +189,7 @@ export function HeaderNav() {
   const [auth, setAuth] = useState<ClientAuthResult>();
   const [error, setError] = useState<Error>();
   useEffect(() => {
-    getSession().then(setAuth, setError);
+    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;
@@ -174,8 +206,9 @@ A rejected `getSession()` means the state is *unknown* (broken proxy, network,
 
 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`,
-`404/sess.not_found`, and anonymous sessions resolve to signed out. The request
+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
@@ -189,11 +222,20 @@ The `<zitadel-login>` web component (from `@zitadel/components`) must be rendere
 
 ```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 />;
@@ -232,12 +274,39 @@ There is no `api-base` attribute — the element reads the global handle from
 `configureZitadel()` (or you can assign the returned handle to the element's
 `project` property).
 
+## Widget events
+
+The widgets are plain custom elements, so each event is a DOM `CustomEvent` that carries its payload in `detail`. The events and payloads are the same ones every SPA SDK exposes as callbacks.
+
+| Widget event | Fires when | Detail | Widgets |
+| --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session |
+
+```tsx
+const ref = useRef<HTMLElementTagNameMap['zitadel-login']>(null);
+
+useEffect(() => {
+  const login = ref.current;
+  const onComplete = (event: Event) => track((event as CustomEvent).detail);
+  login?.addEventListener('zitadel-flow-complete', onComplete);
+  return () => login?.removeEventListener('zitadel-flow-complete', onComplete);
+}, []);
+
+return <zitadel-login ref={ref} post-sign-in-url="/admin" />;
+```
+
 ## 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. Sign-in with an external provider currently requires the default: the provider returns to `/__nextgen/idp/callback` |
+| `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                                                                                    |
@@ -256,5 +325,5 @@ 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. The `x-nextgen-auth-token` header is stripped from all proxied requests to prevent internal state leakage
+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

@@ -9,7 +9,7 @@ import type { AuthResult, NextgenMiddlewareOptions } from "./types.js";
  * a token the middleware accepted can fail re-verification in `auth()` and
  * render as signed out.
  */
-export type AuthOptions = Pick<NextgenMiddlewareOptions, "url" | "allowedAlgorithms" | "clockSkewMs" | "audience" | "allowedTokenTypes" | "jwksTimeoutMs" | "opaqueTokenTimeoutMs">;
+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.
  *
@@ -27,10 +27,22 @@ export type AuthOptions = Pick<NextgenMiddlewareOptions, "url" | "allowedAlgorit
  *   `cache()`.
  *
  * The header alone is never proof of anything: on routes the middleware
- * `matcher` does not cover, the middleware cannot neutralise a forged
+ * `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

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAOrB,OAAO,KAAK,EAAE,UAAU,EAAiB,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAItF;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAC5B,wBAAwB,EACtB,KAAK,GACL,mBAAmB,GACnB,aAAa,GACb,UAAU,GACV,mBAAmB,GACnB,eAAe,GACf,sBAAsB,CACzB,CAAC;AA+DF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAsB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8DzE"}
+{"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,57 +1,20 @@
 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";
 /**
- * Validates an opaque (non-JWT) session token against the backend's
- * `GET /sessions/me` and returns the client-safe identity, or `null` when the
- * backend does not confirm a signed-in user.
+ * 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.
- *
- * Fail-closed: network errors, timeouts, and unexpected statuses all resolve
- * to `null` (signed out). Unexpected failures are logged so a broken proxy or
- * unreachable backend is distinguishable from a genuinely missing session.
  */
-const validateOpaqueSession = cache(async (token, issuerUrl, timeoutMs) => {
-    try {
-        const res = await fetch(`${issuerUrl}/sessions/me`, {
-            method: "GET",
-            headers: { accept: "application/json", cookie: `__nextgen_session=${token}` },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        // 401 = no/invalid session token, 404 = session gone (revoked/expired):
-        // both are the server's definitive "not signed in".
-        if (res.status === 401 || res.status === 404) {
-            return null;
-        }
-        if (!res.ok) {
-            console.warn(`[nextgen] auth(): session validation failed with HTTP ${res.status} from ` +
-                `${issuerUrl}/sessions/me — treating as signed out. If this persists, the ` +
-                `backend URL is likely misconfigured (ZITADEL_URL or the \`url\` option).`);
-            return null;
-        }
-        const session = (await res.json());
-        // An anonymous session (no verified user factor yet) has no user_id —
-        // for server-rendered UI that is "not signed in".
-        if (!session.user_id) {
-            return null;
-        }
-        return {
-            userId: session.user_id,
-            identifier: session.user?.identifier ?? null,
-            identifierProperty: session.user?.identifier_property ?? null,
-            display: session.user?.display ?? null,
-        };
-    }
-    catch {
-        console.warn(`[nextgen] auth(): could not reach ${issuerUrl}/sessions/me to validate the ` +
-            `session token — treating as signed out.`);
-        return null;
-    }
-});
+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.
  *
@@ -69,10 +32,22 @@ const validateOpaqueSession = cache(async (token, issuerUrl, timeoutMs) => {
  *   `cache()`.
  *
  * The header alone is never proof of anything: on routes the middleware
- * `matcher` does not cover, the middleware cannot neutralise a forged
+ * `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
@@ -112,7 +87,13 @@ export async function auth(options = {}) {
     if (!token) {
         return { isAuthenticated: false, session: null };
     }
-    const { url = process.env.ZITADEL_URL ?? "http://localhost:8080", allowedAlgorithms = ["RS256", "ES256"], clockSkewMs = 5000, audience, allowedTokenTypes = ["JWT", "at+JWT"], jwksTimeoutMs, opaqueTokenTimeoutMs = 5000, } = options;
+    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,
@@ -122,7 +103,7 @@ export async function auth(options = {}) {
             allowedTokenTypes,
             jwksTimeoutMs,
         });
-        if (payload?.sub) {
+        if (payload?.sub && jwtNamesProject(payload, projectId)) {
             return {
                 isAuthenticated: true,
                 session: {
@@ -134,6 +115,10 @@ export async function auth(options = {}) {
                 },
             };
         }
+        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
@@ -143,12 +128,35 @@ export async function auth(options = {}) {
         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 ${url}/auth/keys is reachable.`);
+            `same verification options and that the JWKS endpoint at ${joinURL(url, "/auth/keys")} is reachable.`);
         return { isAuthenticated: false, session: null };
     }
-    const session = await validateOpaqueSession(token, url, opaqueTokenTimeoutMs);
-    if (session) {
-        return { isAuthenticated: true, session: { ...session, token } };
+    // 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,6 +1,6 @@
 /**
- * Re-exports the `<zitadel-login>` and `<zitadel-logout>` Lit web components
- * for use in Next.js apps.
+ * 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
@@ -10,6 +10,9 @@
  * 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
@@ -17,7 +20,8 @@
  * resolve). Call it inside the same `"use client"` boundary before the
  * components mount.
  */
-export { ZitadelLogin, ZitadelLogout, ZitadelSession, businessLocales } from "@zitadel/components";
+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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}
+{"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"}

package/dist/client.js

@@ -1,6 +1,6 @@
 /**
- * Re-exports the `<zitadel-login>` and `<zitadel-logout>` Lit web components
- * for use in Next.js apps.
+ * 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
@@ -10,6 +10,9 @@
  * 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
@@ -17,5 +20,10 @@
  * resolve). Call it inside the same `"use client"` boundary before the
  * components mount.
  */
-export { ZitadelLogin, ZitadelLogout, ZitadelSession, businessLocales } from "@zitadel/components";
+// Registers <zitadel-login>, <zitadel-logout> and <zitadel-session> in the browser.
+// The edge build of the components package has no elements, so this does nothing there.
+import "@zitadel/components";
+// Re-exported so scaffolded apps can wire the business copy overlay without a
+// direct @zitadel/components dependency (strict package managers reject those).
+export { businessLocales } from "@zitadel/components";
 export { configureZitadel, getApi } from "@zitadel/api/config";

package/dist/middleware.d.ts

@@ -20,6 +20,9 @@ import { NextResponse } from "next/server";
  *   });
  * }
  *
+ * A session counts only in the app's own project: `projectId`, else
+ * `ZITADEL_PROJECT_ID`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`.
+ *
  * export const config = {
  *   matcher: ["/__nextgen/:path*", "/profile/:path*"],
  * };
@@ -54,7 +57,7 @@ export type ProxyHandler = (req: NextRequest) => Promise<NextResponse | Response
  * import { createProxy } from "@zitadel/sdk-next/middleware";
  *
  * const zitadel = configureZitadel({
- *   projectId: "demo",
+ *   projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID ?? "",
  *   url: process.env.ZITADEL_URL,
  * });
  *
@@ -71,6 +74,12 @@ export type ProxyHandler = (req: NextRequest) => Promise<NextResponse | Response
  * export const middleware = proxy;
  * ```
  *
+ * Sessions are held to the handle's project unless `options.projectId` names
+ * another. `auth()` runs in the server runtime, where the middleware's handle
+ * may not be configured: it reads `ZITADEL_PROJECT_ID` /
+ * `NEXT_PUBLIC_ZITADEL_PROJECT_ID`, else a handle configured there. When the
+ * project lives only in this handle, pass it as `auth({ projectId })` too.
+ *
  * @param config  - The SDK handle from `configureZitadel()`.
  * @param options - Route protection and JWT options.
  * @returns A middleware handler function.

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmC3C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,CAqDlC;AAuPD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,wBAAwB,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,YAAiB,GAAG,YAAY,CAO5F"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAyB,MAAM,8BAA8B,CAAC;AAEpG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAa/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,CAyDlC;AAuMD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,wBAAwB,EAAE,WAAW,GAAG,KAAK,CAAC,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,YAAiB,GAAG,YAAY,CAQ5F"}

package/dist/middleware.js

@@ -1,6 +1,6 @@
-import { HOP_BY_HOP, INTERNAL_HEADERS, filterResponseHeaders, matchesRoutes, } from "@zitadel/sdk-core/middleware";
+import { joinURL } from "ufo";
+import { HOP_BY_HOP, INTERNAL_HEADERS, filterResponseHeaders, loginRedirectUrl, matchesRoutes, proxySessionCookies, SESSION_COOKIE_CACHE_CONTROL, requiresProjectSecret, resolveSession, } from "@zitadel/sdk-core/middleware";
 import { NextResponse } from "next/server";
-import { verifyJwt, isJwtShaped } from "./lib/jwt.js";
 /**
  * Clones the incoming request headers, injects `extra` key/value pairs,
  * and registers them with the Next.js header-tunnelling mechanism so that
@@ -19,6 +19,8 @@ function tunnelHeaders(req, extra) {
     // scratch using only the names we inject ourselves.
     headers.delete("x-middleware-override-headers");
     const injectedNames = [];
+    // This is the only writer of x-nextgen-auth-token: it injects the verified
+    // value for server components, and a client-sent one never reaches here.
     for (const [name, value] of Object.entries(extra)) {
         headers.set(name, value);
         headers.set(`x-middleware-request-${name}`, value);
@@ -45,6 +47,9 @@ function tunnelHeaders(req, extra) {
  *   });
  * }
  *
+ * A session counts only in the app's own project: `projectId`, else
+ * `ZITADEL_PROJECT_ID`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`.
+ *
  * export const config = {
  *   matcher: ["/__nextgen/:path*", "/profile/:path*"],
  * };
@@ -55,7 +60,7 @@ function tunnelHeaders(req, extra) {
  * @returns A `NextResponse` or `Response` to continue, redirect, or proxy.
  */
 export async function nextgenMiddleware(req, options = {}) {
-    const { url = process.env.ZITADEL_URL ?? "http://localhost:8080", proxyPath = "/__nextgen", protectedRoutes = [], ignoredRoutes = [], loginPath = "/login", allowedAlgorithms = ["RS256", "ES256"], clockSkewMs = 5000, audience, allowedTokenTypes = ["JWT", "at+JWT"], jwksTimeoutMs, proxyTimeoutMs = 5000, opaqueTokenTimeoutMs = 5000, } = options;
+    const { url = process.env.ZITADEL_URL ?? "http://localhost:8080", projectId = process.env.ZITADEL_PROJECT_ID || process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID, proxyPath = "/__nextgen", protectedRoutes = [], ignoredRoutes = [], loginPath = "/login", allowedAlgorithms = ["RS256", "ES256"], clockSkewMs = 5000, audience, allowedTokenTypes = ["JWT", "at+JWT"], jwksTimeoutMs, proxyTimeoutMs = 5000, opaqueTokenTimeoutMs = 5000, } = options;
     // Guard against open-redirect: loginPath must be a relative path. An absolute
     // URL (e.g. "https://evil.com/phish") or a protocol-relative URL
     // (e.g. "//evil.com") would redirect the browser to an external host.
@@ -64,19 +69,21 @@ export async function nextgenMiddleware(req, options = {}) {
             `Received: "${loginPath}". Using an absolute or protocol-relative URL ` +
             `would allow open-redirect attacks.`);
     }
+    // Clients never send x-nextgen-auth-token: it is an internal channel. Refuse any
+    // request that carries it, on every route, before anything else runs.
+    if (req.headers.has("x-nextgen-auth-token")) {
+        return new Response("Bad Request", { status: 400 });
+    }
     const { pathname } = new URL(req.url);
     if (matchesRoutes(pathname, ignoredRoutes)) {
-        // Neutralise any client-supplied x-nextgen-auth-token on ignored routes.
-        // handleAuth is skipped for ignored routes, so we must strip the header
-        // here to prevent a forged value from reaching server components.
-        const headers = tunnelHeaders(req, { "x-nextgen-auth-token": "" });
-        return NextResponse.next({ request: { headers } });
+        return NextResponse.next();
     }
     if (pathname === proxyPath || pathname.startsWith(`${proxyPath}/`)) {
-        return proxyRequest(req, url, proxyPath, proxyTimeoutMs);
+        return proxyRequest(req, url, proxyPath, projectId, proxyTimeoutMs);
     }
     return handleAuth(req, {
         url,
+        projectId,
         protectedRoutes,
         loginPath,
         allowedAlgorithms,
@@ -88,30 +95,11 @@ export async function nextgenMiddleware(req, options = {}) {
         pathname,
     });
 }
-/**
- * Validates an opaque (non-JWT) session token by calling the backend's
- * `/sessions/me` endpoint. Returns `true` when the backend confirms the
- * session is live (HTTP 200), `false` otherwise.
- *
- * This is the fallback path for backends that issue encrypted opaque tokens
- * rather than self-contained JWTs.
- */
-async function validateOpaqueSessionToken(token, issuerUrl, timeoutMs) {
-    try {
-        const res = await fetch(`${issuerUrl}/sessions/me`, {
-            method: "GET",
-            headers: { cookie: `__nextgen_session=${token}` },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        return res.ok;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Forwards a `/__nextgen/*` request to the upstream auth backend and streams
- * the response back verbatim, stripping hop-by-hop headers in both directions.
+ * the response back, stripping hop-by-hop headers in both directions. The
+ * session cookie travels under this project's name in the browser and the
+ * server's name upstream ({@link proxySessionCookies}).
  *
  * All non-hop-by-hop headers from the incoming request are forwarded, including
  * any `X-Forwarded-For` chain already set by an upstream CDN or load balancer.
@@ -123,12 +111,13 @@ async function validateOpaqueSessionToken(token, issuerUrl, timeoutMs) {
  * @param req        - The incoming edge request.
  * @param authUrl    - Base URL of the auth backend.
  * @param proxyPath  - The path prefix being proxied (e.g. `"/__nextgen"`).
+ * @param projectId  - The project this app signs its users in to.
  * @returns The proxied upstream `Response`.
  */
-async function proxyRequest(req, authUrl, proxyPath, proxyTimeoutMs) {
+async function proxyRequest(req, authUrl, proxyPath, projectId, proxyTimeoutMs) {
     const url = new URL(req.url);
     const suffix = url.pathname.slice(proxyPath.length);
-    const target = `${authUrl}${suffix}${url.search}`;
+    const target = `${joinURL(authUrl, suffix)}${url.search}`;
     const upstreamHeaders = new Headers();
     for (const [key, value] of req.headers.entries()) {
         const lower = key.toLowerCase();
@@ -140,7 +129,7 @@ async function proxyRequest(req, authUrl, proxyPath, proxyTimeoutMs) {
     // upstream auth server sees the full proxy path. We never skip this even when
     // a chain is already present — a CDN or load balancer may have set XFF before
     // the request reached this edge node, and our hop must still be recorded.
-    const directIp = req.ip ?? req.headers.get("x-real-ip");
+    const directIp = req.ip;
     if (directIp) {
         const existingXff = upstreamHeaders.get("x-forwarded-for");
         upstreamHeaders.set("x-forwarded-for", existingXff ? `${existingXff}, ${directIp}` : directIp);
@@ -151,6 +140,21 @@ async function proxyRequest(req, authUrl, proxyPath, proxyTimeoutMs) {
     if (!upstreamHeaders.has("x-forwarded-proto")) {
         upstreamHeaders.set("x-forwarded-proto", url.protocol.replace(":", ""));
     }
+    const sessionCookies = proxySessionCookies({
+        method: req.method,
+        path: suffix,
+        search: url.search,
+        cookie: req.headers.get("cookie"),
+        requestUrl: url,
+        forwardedProto: req.headers.get("x-forwarded-proto"),
+        forwardedHost: req.headers.get("x-forwarded-host"),
+    }, projectId, { url: authUrl, timeoutMs: proxyTimeoutMs });
+    if (sessionCookies.upstreamCookie === null) {
+        upstreamHeaders.delete("cookie");
+    }
+    else {
+        upstreamHeaders.set("cookie", sessionCookies.upstreamCookie);
+    }
     const hasBody = !["GET", "HEAD"].includes(req.method);
     // ADR 036: the current browser flow needs the confidential project secret
     // only for the handoff exchange. Stamping it onto every proxied operation
@@ -177,80 +181,77 @@ async function proxyRequest(req, authUrl, proxyPath, proxyTimeoutMs) {
     // The app's own request URL: the origin a proxied redirect may name, and
     // the base a relative one resolves against.
     const responseHeaders = filterResponseHeaders(upstream.headers, req.nextUrl.toString());
-    const setCookies = upstream.headers.getSetCookie?.() ?? [];
-    for (const cookie of setCookies) {
+    const answer = await sessionCookies.toBrowser(upstream);
+    for (const cookie of answer.setCookies) {
         responseHeaders.append("set-cookie", cookie);
     }
-    return new Response(upstream.body, {
+    if (answer.setCookies.length > 0) {
+        responseHeaders.set("cache-control", SESSION_COOKIE_CACHE_CONTROL);
+    }
+    return new Response(answer.body, {
         status: upstream.status,
         headers: responseHeaders,
     });
 }
-function requiresProjectSecret(method, pathname) {
-    return method.toUpperCase() === "POST" && pathname === "/sessions/exchange";
-}
 /**
- * Verifies the session token and tunnels the result to server components via
- * a request header. Redirects to the login page when the token is absent or
- * invalid on a protected route.
+ * Judges the session and tunnels the token of a signed-in user to server
+ * components via a request header, where `auth()` verifies it again.
+ * Redirects to the login page when nobody is signed in on a protected route.
+ * Either way the response carries the session cookies the judgement asks for.
+ * When the backend cannot say whether the session is live, a protected route
+ * answers `503` instead.
  *
  * @param req  - The incoming edge request.
  * @param opts - Auth handler options.
- * @returns A `NextResponse` to continue or redirect.
+ * @returns A `NextResponse` to continue, redirect, or answer `503`.
  */
 async function handleAuth(req, opts) {
-    const { url, protectedRoutes, loginPath, allowedAlgorithms, clockSkewMs, audience, allowedTokenTypes, jwksTimeoutMs, opaqueTokenTimeoutMs, pathname, } = opts;
+    const { protectedRoutes, loginPath, pathname, ...verification } = opts;
     const authHeader = req.headers.get("authorization");
     const bearerToken = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
-    const cookieToken = req.cookies.get("__nextgen_session")?.value ?? null;
-    // Bearer token takes explicit precedence over the session cookie. API clients
-    // (e.g. mobile apps, CLIs) use Authorization headers while browsers use
-    // cookies; when both are present the caller clearly intended the Bearer token.
-    const token = bearerToken ?? cookieToken;
-    const payload = token
-        ? await verifyJwt(token, {
-            issuerUrl: url,
-            allowedAlgorithms,
-            clockSkewMs,
-            audience,
-            allowedTokenTypes,
-            jwksTimeoutMs,
-        })
-        : null;
-    if (payload && token && payload.sub) {
-        const tunnelled = tunnelHeaders(req, { "x-nextgen-auth-token": token });
-        return NextResponse.next({ request: { headers: tunnelled } });
+    const { auth, undecided, cookies } = await resolveSession({
+        bearer: bearerToken,
+        cookie: (name) => req.cookies.get(name)?.value,
+        requestUrl: req.url,
+        forwardedProto: req.headers.get("x-forwarded-proto"),
+        forwardedHost: req.headers.get("x-forwarded-host"),
+    }, verification);
+    let response;
+    if (auth.isAuthenticated) {
+        const tunnelled = tunnelHeaders(req, { "x-nextgen-auth-token": auth.session.token });
+        response = NextResponse.next({ request: { headers: tunnelled } });
     }
-    // The backend issues opaque encrypted session tokens rather than JWTs.
-    // Only fall back to /sessions/me validation when the token is definitively
-    // not a JWT (non-JSON segments). A token with a valid JWT structure that
-    // failed verification (bad sig, wrong typ/alg) must be rejected — never
-    // accepted by a backend call that doesn't re-check the JWT claims.
-    if (!payload && cookieToken && !isJwtShaped(cookieToken)) {
-        const isValid = await validateOpaqueSessionToken(cookieToken, url, opaqueTokenTimeoutMs);
-        if (isValid) {
-            const tunnelled = tunnelHeaders(req, {
-                "x-nextgen-auth-token": cookieToken,
-            });
-            return NextResponse.next({ request: { headers: tunnelled } });
-        }
+    else if (undecided && matchesRoutes(pathname, protectedRoutes)) {
+        // The backend could not say whether the session is live. The user may well
+        // be signed in, so a protected route answers 503 rather than send them to
+        // the login page.
+        response = new NextResponse("Service Unavailable", { status: 503 });
     }
-    const tunnelled = tunnelHeaders(req, { "x-nextgen-auth-token": "" });
-    const staleNextgenCookies = req.cookies
-        .getAll()
-        .filter((c) => c.name.startsWith("__nextgen"));
-    if (matchesRoutes(pathname, protectedRoutes)) {
-        const loginUrl = new URL(loginPath, req.url);
-        loginUrl.searchParams.set("next", pathname);
-        const redirect = NextResponse.redirect(loginUrl, { status: 302 });
-        for (const cookie of staleNextgenCookies) {
-            redirect.cookies.delete(cookie.name);
-        }
-        return redirect;
+    else if (matchesRoutes(pathname, protectedRoutes)) {
+        response = NextResponse.redirect(loginRedirectUrl(loginPath, req.url), { status: 302 });
+    }
+    else {
+        const tunnelled = tunnelHeaders(req, { "x-nextgen-auth-token": "" });
+        response = NextResponse.next({ request: { headers: tunnelled } });
     }
-    const response = NextResponse.next({ request: { headers: tunnelled } });
-    for (const cookie of staleNextgenCookies) {
-        response.cookies.delete(cookie.name);
+    // A dead session's cookie is cleared so the browser stops replaying it, and a
+    // session of this project still under the shared name is copied to the
+    // project's own cookie. A live session that signs no one in here (an
+    // anonymous one, or one of another project) keeps its cookie, and so does one
+    // the backend gave no verdict on. The cookies go through the response's
+    // cookie jar, so a middleware composed around this one that sets a cookie of
+    // its own through it keeps them.
+    for (const cookie of cookies) {
+        response.cookies.set(cookie.name, cookie.value, {
+            path: "/",
+            httpOnly: true,
+            sameSite: "lax",
+            secure: cookie.secure,
+            ...(cookie.maxAge === undefined ? {} : { maxAge: cookie.maxAge }),
+        });
+    }
+    if (cookies.length > 0) {
+        response.headers.set("cache-control", SESSION_COOKIE_CACHE_CONTROL);
     }
     return response;
 }
@@ -265,7 +266,7 @@ async function handleAuth(req, opts) {
  * import { createProxy } from "@zitadel/sdk-next/middleware";
  *
  * const zitadel = configureZitadel({
- *   projectId: "demo",
+ *   projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID ?? "",
  *   url: process.env.ZITADEL_URL,
  * });
  *
@@ -282,6 +283,12 @@ async function handleAuth(req, opts) {
  * export const middleware = proxy;
  * ```
  *
+ * Sessions are held to the handle's project unless `options.projectId` names
+ * another. `auth()` runs in the server runtime, where the middleware's handle
+ * may not be configured: it reads `ZITADEL_PROJECT_ID` /
+ * `NEXT_PUBLIC_ZITADEL_PROJECT_ID`, else a handle configured there. When the
+ * project lives only in this handle, pass it as `auth({ projectId })` too.
+ *
  * @param config  - The SDK handle from `configureZitadel()`.
  * @param options - Route protection and JWT options.
  * @returns A middleware handler function.
@@ -289,6 +296,7 @@ async function handleAuth(req, opts) {
 export function createProxy(config, options = {}) {
     const mergedOptions = {
         ...options,
+        projectId: options.projectId ?? (config.projectId || undefined),
         proxyPath: config.proxyPath,
         url: config.url,
     };

package/dist/server.d.ts

@@ -9,4 +9,5 @@
 export { auth } from "./auth.js";
 export type { AuthOptions } from "./auth.js";
 export { NextgenProvider } from "./provider.js";
+export type { AuthResult, AuthState, UnauthState, NextgenSession, ClientAuthResult, NextgenMiddlewareOptions, } from "./types.js";
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,YAAY,CAAC"}

package/dist/session.d.ts

@@ -7,24 +7,37 @@ export type GetSessionOptions = {
      * on this page, else `"/__nextgen"` (the scaffold default).
      */
     proxyPath?: string;
+    /**
+     * The project this app signs its users in to. A session of another project
+     * reads as signed out. Defaults to the project from `configureZitadel()`
+     * when it has run on this page, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`. With
+     * none, nobody reads as signed in, as on the server.
+     */
+    projectId?: string;
 };
 /**
  * Reads the current session state from the browser — the supported way for
  * an app's own UI (header navigation, account menus) to know whether a user
  * is signed in and who they are.
  *
- * Fetches the same-origin `{proxyPath}/sessions/me` with credentials and
- * `cache: "no-store"` — the same read the `<zitadel-session>` card performs —
- * so the answer is the server's, not a client-side guess. Works on any page:
- * unlike server-side `auth()`, it does not require the route to be covered by
- * the middleware `matcher` (only the proxy path itself must be matched, which
- * the scaffolded request boundary always does), and it does not require
- * `configureZitadel()` to have run.
+ * Fetches the same-origin `{proxyPath}/sessions/me?project_id=…` with
+ * credentials and `cache: "no-store"` — the same read the `<zitadel-session>`
+ * card performs — so the answer is the server's, not a client-side guess.
+ * Works on any page: unlike server-side `auth()`, it does not require the
+ * route to be covered by the middleware `matcher` (only the proxy path itself
+ * must be matched, which the scaffolded request boundary always does).
+ *
+ * A session counts only in the app's own project: `options.projectId`, else
+ * the project of `configureZitadel()`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`.
+ * With none of them, it reads as signed out without asking the server.
  *
  * - `200` with an authenticated user → `{ isAuthenticated: true, session }`
  *   with the client-safe identity (`userId`, `email`, `name` — no token).
- * - `200` for an anonymous session, `401` with `auth.unauthorized`, or `404`
- *   with `sess.not_found` → signed out.
+ * - `200` for an anonymous session, `401` with `auth.unauthorized`, `403`
+ *   with `sess.project_mismatch`, or `404` with `sess.not_found` → signed out.
+ *   The `403` answers a session of another project on the same server, and a
+ *   `200` naming another project (from a server that predates the parameter)
+ *   reads as signed out too.
  * - Any other response throws — including a framework's HTML 404 page from
  *   a misrouted proxy: a failing proxy is a misconfiguration and must not
  *   silently render as "signed out". Treat a rejection as "unknown" —
@@ -39,7 +52,10 @@ export type GetSessionOptions = {
  *   const [auth, setAuth] = useState<ClientAuthResult>();
  *   const [failed, setFailed] = useState(false);
  *   useEffect(() => {
- *     getSession().then(setAuth, () => setFailed(true));
+ *     getSession({ projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID }).then(
+ *       setAuth,
+ *       () => setFailed(true),
+ *     );
  *   }, []);
  *   if (failed) return <span role="alert">Session unavailable</span>;
  *   if (!auth) return null;

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD,sCAAsC;AACtC,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2D3F;AAED,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKnD,sCAAsC;AACtC,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA8BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqE3F;AAED,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/session.js

@@ -1,23 +1,53 @@
 import { getZitadelConfig } from "@zitadel/api/config";
 /** Matches the `configureZitadel()` default so zero-config apps agree with the scaffold. */
 const DEFAULT_PROXY_PATH = "/__nextgen";
+/**
+ * `NEXT_PUBLIC_ZITADEL_PROJECT_ID`, which Next.js inlines into client bundles
+ * at build time. Read defensively: where it was not inlined, `process` may not
+ * exist in the browser.
+ */
+function publicProjectId() {
+    try {
+        return process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+let warnedMissingProject = false;
+/** Says once per page why `getSession()` signs no one in: no project is known. */
+function warnMissingProject() {
+    if (warnedMissingProject) {
+        return;
+    }
+    warnedMissingProject = true;
+    console.warn("[nextgen] getSession(): no project id is known, so no session counts as signed in. " +
+        "Pass `projectId` (e.g. process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID) or call " +
+        "configureZitadel() first.");
+}
 /**
  * Reads the current session state from the browser — the supported way for
  * an app's own UI (header navigation, account menus) to know whether a user
  * is signed in and who they are.
  *
- * Fetches the same-origin `{proxyPath}/sessions/me` with credentials and
- * `cache: "no-store"` — the same read the `<zitadel-session>` card performs —
- * so the answer is the server's, not a client-side guess. Works on any page:
- * unlike server-side `auth()`, it does not require the route to be covered by
- * the middleware `matcher` (only the proxy path itself must be matched, which
- * the scaffolded request boundary always does), and it does not require
- * `configureZitadel()` to have run.
+ * Fetches the same-origin `{proxyPath}/sessions/me?project_id=…` with
+ * credentials and `cache: "no-store"` — the same read the `<zitadel-session>`
+ * card performs — so the answer is the server's, not a client-side guess.
+ * Works on any page: unlike server-side `auth()`, it does not require the
+ * route to be covered by the middleware `matcher` (only the proxy path itself
+ * must be matched, which the scaffolded request boundary always does).
+ *
+ * A session counts only in the app's own project: `options.projectId`, else
+ * the project of `configureZitadel()`, else `NEXT_PUBLIC_ZITADEL_PROJECT_ID`.
+ * With none of them, it reads as signed out without asking the server.
  *
  * - `200` with an authenticated user → `{ isAuthenticated: true, session }`
  *   with the client-safe identity (`userId`, `email`, `name` — no token).
- * - `200` for an anonymous session, `401` with `auth.unauthorized`, or `404`
- *   with `sess.not_found` → signed out.
+ * - `200` for an anonymous session, `401` with `auth.unauthorized`, `403`
+ *   with `sess.project_mismatch`, or `404` with `sess.not_found` → signed out.
+ *   The `403` answers a session of another project on the same server, and a
+ *   `200` naming another project (from a server that predates the parameter)
+ *   reads as signed out too.
  * - Any other response throws — including a framework's HTML 404 page from
  *   a misrouted proxy: a failing proxy is a misconfiguration and must not
  *   silently render as "signed out". Treat a rejection as "unknown" —
@@ -32,7 +62,10 @@ const DEFAULT_PROXY_PATH = "/__nextgen";
  *   const [auth, setAuth] = useState<ClientAuthResult>();
  *   const [failed, setFailed] = useState(false);
  *   useEffect(() => {
- *     getSession().then(setAuth, () => setFailed(true));
+ *     getSession({ projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID }).then(
+ *       setAuth,
+ *       () => setFailed(true),
+ *     );
  *   }, []);
  *   if (failed) return <span role="alert">Session unavailable</span>;
  *   if (!auth) return null;
@@ -62,7 +95,12 @@ export async function getSession(options = {}) {
     while (proxyPath.endsWith("/")) {
         proxyPath = proxyPath.slice(0, -1);
     }
-    const response = await fetch(`${proxyPath}/sessions/me`, {
+    const projectId = options.projectId || getZitadelConfig()?.projectId || publicProjectId();
+    if (!projectId) {
+        warnMissingProject();
+        return { isAuthenticated: false, session: null };
+    }
+    const response = await fetch(`${proxyPath}/sessions/me?project_id=${encodeURIComponent(projectId)}`, {
         cache: "no-store",
         credentials: "include",
         headers: { accept: "application/json" },
@@ -70,9 +108,10 @@ export async function getSession(options = {}) {
     // Only the backend's canonical error envelope is definitive signed-out.
     // A framework route, gateway, or WAF can also return 401/404; accepting the
     // status or content type alone would turn a broken proxy into signed-out.
-    if (response.status === 401 || response.status === 404) {
+    if (response.status === 401 || response.status === 403 || response.status === 404) {
         const error = await readErrorEnvelope(response);
         const isSignedOut = (response.status === 401 && error?.code === "auth.unauthorized") ||
+            (response.status === 403 && error?.code === "sess.project_mismatch") ||
             (response.status === 404 && error?.code === "sess.not_found");
         if (isSignedOut) {
             return { isAuthenticated: false, session: null };
@@ -82,9 +121,10 @@ export async function getSession(options = {}) {
         throw new Error(`[nextgen] Session read failed: HTTP ${response.status} from ${proxyPath}/sessions/me`);
     }
     const session = (await response.json());
-    // An anonymous session (no verified user factor yet) has no user_id —
-    // for app chrome that is "not signed in".
-    if (!session.user_id) {
+    // An anonymous session (no verified user factor yet) has no user_id, and a
+    // backend that predates `project_id` answers for any project: for app
+    // chrome, either is "not signed in".
+    if (!session.user_id || session.project_id !== projectId) {
         return { isAuthenticated: false, session: null };
     }
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zitadel/sdk-next",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.28",
   "description": "Next.js helpers and mock auth UI for Zitadel",
   "homepage": "https://github.com/zitadel/nextgen/tree/main/packages/sdk-next#readme",
   "bugs": {
@@ -54,24 +54,26 @@
     "access": "public"
   },
   "dependencies": {
+    "@zitadel/api": "1.0.0-alpha.28",
+    "@zitadel/components": "1.0.0-alpha.28",
+    "@zitadel/sdk-core": "1.0.0-alpha.28",
     "server-only": "^0.0.1",
-    "@zitadel/api": "1.0.0-alpha.25",
-    "@zitadel/components": "1.0.0-alpha.25",
-    "@zitadel/sdk-core": "1.0.0-alpha.25"
+    "ufo": "^1.6.4"
   },
   "peerDependencies": {
-    "next": ">=15",
+    "next": ">=15.2.3",
     "react": ">=18",
     "react-dom": ">=18"
   },
   "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.6.0",
+    "@types/node": "^24.19.1",
     "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^4.1.11",
     "jsdom": "^29.0.2",
-    "next": "^16.2.11",
+    "next": "^16.3.8",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
@@ -81,6 +83,8 @@
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node -e \"require('node:fs').copyFileSync('src/jsx.d.ts', 'dist/jsx.d.ts')\"",
     "typecheck": "tsc --noEmit -p tsconfig.lib.json && tsc --noEmit -p tsconfig.spec.json",
     "test": "vitest run",
-    "test:all": "pnpm run test"
+    "test:all": "pnpm run test",
+    "lint": "biome check .",
+    "build-release": "node ../../scripts/release-clean.mjs local-dist && pnpm run build"
   }
 }