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

package/dist/client.js

@@ -1,9 +1,29 @@
-// src/client.ts
-import { ZitadelLogin, ZitadelLogout } from "@zitadel/components";
-import { configureZitadel, getApi } from "@zitadel/api/config";
-export {
-  ZitadelLogin,
-  ZitadelLogout,
-  configureZitadel,
-  getApi
-};
+/**
+ * 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.
+ */
+// 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/components.d.ts

@@ -0,0 +1,16 @@
+/**
+ * React components for the Zitadel widgets in Next.js apps.
+ *
+ * Use these instead of the raw `<zitadel-login>`, `<zitadel-logout>` and
+ * `<zitadel-session>` elements: the wrappers set `project` and `locales` as DOM
+ * properties on React 18 and 19, including after server-rendered hydration,
+ * where the raw elements lose them (React 19) or write `[object Object]`
+ * attributes (React 18).
+ *
+ * ```tsx
+ * import { ZitadelLogin } from "@zitadel/sdk-next/components";
+ * ```
+ */
+export { businessLocales, configureZitadel, ZitadelLogin, ZitadelLogout, ZitadelSession, } from "@zitadel/sdk-react";
+export type { ZitadelLoginReactProps, ZitadelLogoutReactProps, ZitadelSessionReactProps, } from "@zitadel/sdk-react";
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/components.js

@@ -0,0 +1,15 @@
+"use client";
+/**
+ * React components for the Zitadel widgets in Next.js apps.
+ *
+ * Use these instead of the raw `<zitadel-login>`, `<zitadel-logout>` and
+ * `<zitadel-session>` elements: the wrappers set `project` and `locales` as DOM
+ * properties on React 18 and 19, including after server-rendered hydration,
+ * where the raw elements lose them (React 19) or write `[object Object]`
+ * attributes (React 18).
+ *
+ * ```tsx
+ * import { ZitadelLogin } from "@zitadel/sdk-next/components";
+ * ```
+ */
+export { businessLocales, configureZitadel, ZitadelLogin, ZitadelLogout, ZitadelSession, } from "@zitadel/sdk-react";

package/dist/context.d.ts

@@ -1,11 +1,22 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-import { AuthResult, NextgenSession } from '@zitadel/sdk-core/types';
-
-declare function NextgenProvider({ session, children, }: {
-    session: AuthResult | NextgenSession | null;
+import { type ReactNode } from "react";
+import type { ClientAuthResult } from "./types.js";
+/**
+ * Client-side context carrier. In the standard server-seeded setup, render
+ * {@link NextgenProvider} from `@zitadel/sdk-next/server` instead — it
+ * normalises the server's `auth()` result to the client-safe shape (dropping
+ * the raw session token) *before* the value crosses the server→client
+ * component boundary, and its `server-only` guard keeps it out of client
+ * wrappers where that strip would come too late.
+ *
+ * Render this component directly only from client code that already holds a
+ * client-safe value — e.g. seeding from a `getSession()` read.
+ *
+ * The `value` prop is deliberately typed as {@link ClientAuthResult}: the
+ * raw session token must never enter client-side state.
+ */
+export declare function AuthContextProvider({ value, children, }: {
+    value: ClientAuthResult;
     children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function useAuthContext(): AuthResult;
-
-export { NextgenProvider, useAuthContext };
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useAuthContext(): ClientAuthResult;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,gBAAgB,CAAC;IACxB,QAAQ,EAAE,SAAS,CAAC;CACrB,2CAEA;AAED,wBAAgB,cAAc,IAAI,gBAAgB,CAEjD"}

package/dist/context.js

@@ -1,9 +1,25 @@
 "use client";
-import {
-  NextgenProvider,
-  useAuthContext
-} from "./chunk-2BFQLJQE.js";
-export {
-  NextgenProvider,
-  useAuthContext
-};
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const defaultValue = { isAuthenticated: false, session: null };
+const NextgenAuthContext = createContext(defaultValue);
+/**
+ * Client-side context carrier. In the standard server-seeded setup, render
+ * {@link NextgenProvider} from `@zitadel/sdk-next/server` instead — it
+ * normalises the server's `auth()` result to the client-safe shape (dropping
+ * the raw session token) *before* the value crosses the server→client
+ * component boundary, and its `server-only` guard keeps it out of client
+ * wrappers where that strip would come too late.
+ *
+ * Render this component directly only from client code that already holds a
+ * client-safe value — e.g. seeding from a `getSession()` read.
+ *
+ * The `value` prop is deliberately typed as {@link ClientAuthResult}: the
+ * raw session token must never enter client-side state.
+ */
+export function AuthContextProvider({ value, children, }) {
+    return _jsx(NextgenAuthContext.Provider, { value: value, children: children });
+}
+export function useAuthContext() {
+    return useContext(NextgenAuthContext);
+}

package/dist/index.d.ts

@@ -1,9 +1,16 @@
-export { AuthResult, AuthState, NextgenMiddlewareOptions, NextgenSession, UnauthState } from '@zitadel/sdk-core/types';
-export { ProxyHandler, ProxyOptions, createProxy, nextgenMiddleware } from './middleware.js';
-export { auth } from './auth.js';
-export { NextgenProvider, useAuthContext } from './context.js';
-export { useAuth } from './useAuth.js';
-import '@zitadel/api/config';
-import 'next/server';
-import 'react/jsx-runtime';
-import 'react';
+/**
+ * Package root — for **Server Components and server modules only**: it
+ * includes the server-only `auth()`, so importing it from a `"use client"`
+ * module fails at build time. Client components import from
+ * `@zitadel/sdk-next/react` (provider + hooks) or
+ * `@zitadel/sdk-next/session` (`getSession()`) instead.
+ */
+export * from "./types.js";
+export { nextgenMiddleware, createProxy } from "./middleware.js";
+export type { ProxyOptions, ProxyHandler } from "./middleware.js";
+export { auth } from "./auth.js";
+export type { AuthOptions } from "./auth.js";
+export { NextgenProvider } from "./provider.js";
+export { AuthContextProvider, useAuthContext } from "./context.js";
+export { useAuth } from "./useAuth.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,24 +1,13 @@
-import {
-  createProxy,
-  nextgenMiddleware
-} from "./chunk-4KENHIG4.js";
-import {
-  auth
-} from "./chunk-B7S6XMT3.js";
-import "./chunk-OCZMYSFX.js";
-import "./chunk-6F4PWJZI.js";
-import {
-  useAuth
-} from "./chunk-XTCHTAIQ.js";
-import {
-  NextgenProvider,
-  useAuthContext
-} from "./chunk-2BFQLJQE.js";
-export {
-  NextgenProvider,
-  auth,
-  createProxy,
-  nextgenMiddleware,
-  useAuth,
-  useAuthContext
-};
+/**
+ * Package root — for **Server Components and server modules only**: it
+ * includes the server-only `auth()`, so importing it from a `"use client"`
+ * module fails at build time. Client components import from
+ * `@zitadel/sdk-next/react` (provider + hooks) or
+ * `@zitadel/sdk-next/session` (`getSession()`) instead.
+ */
+export * from "./types.js";
+export { nextgenMiddleware, createProxy } from "./middleware.js";
+export { auth } from "./auth.js";
+export { NextgenProvider } from "./provider.js";
+export { AuthContextProvider, useAuthContext } from "./context.js";
+export { useAuth } from "./useAuth.js";

package/dist/jsx.d.ts

@@ -0,0 +1,5 @@
+// Types-only shim: scaffolded apps depend on @zitadel/sdk-next, not
+// @zitadel/components, so the React JSX declarations for the <zitadel-*>
+// elements are re-exposed here as `@zitadel/sdk-next/jsx`. Copied verbatim
+// into dist/ by the build script.
+/// <reference types="@zitadel/components/jsx" />

package/dist/lib/jwt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-exports shared JWT verification from `@zitadel/sdk-core`.
+ *
+ * The JWT module is runtime-agnostic (uses `atob` which is available in both
+ * Edge and Node.js 16+) and is defined once in sdk-core.
+ */
+export { JWKS_TTL_MS, base64UrlDecode, decodeJwt, isJwtShaped, verifyJwt, } from "@zitadel/sdk-core/jwt";
+export type { JwtPayload, JwtHeader, DecodedJwt, VerifyJwtOptions } from "@zitadel/sdk-core/jwt";
+//# sourceMappingURL=jwt.d.ts.map

package/dist/lib/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/lib/jwt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,WAAW,EACX,eAAe,EACf,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/lib/jwt.js

@@ -0,0 +1,7 @@
+/**
+ * Re-exports shared JWT verification from `@zitadel/sdk-core`.
+ *
+ * The JWT module is runtime-agnostic (uses `atob` which is available in both
+ * Edge and Node.js 16+) and is defined once in sdk-core.
+ */
+export { JWKS_TTL_MS, base64UrlDecode, decodeJwt, isJwtShaped, verifyJwt, } from "@zitadel/sdk-core/jwt";

package/dist/middleware.d.ts

@@ -1,7 +1,7 @@
-import { ZitadelProject } from '@zitadel/api/config';
-import { NextgenMiddlewareOptions } from '@zitadel/sdk-core/types';
-import { NextRequest, NextResponse } from 'next/server';
-
+import type { ZitadelProject } from "@zitadel/api/config";
+import type { NextgenMiddlewareOptions } from "@zitadel/sdk-core/middleware";
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
 /**
  * Next.js Edge middleware that handles proxying, JWT verification, and route
  * protection in a single pass.
@@ -20,6 +20,9 @@ import { NextRequest, 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*"],
  * };
@@ -29,7 +32,7 @@ import { NextRequest, NextResponse } from 'next/server';
  * @param options - Middleware configuration options.
  * @returns A `NextResponse` or `Response` to continue, redirect, or proxy.
  */
-declare function nextgenMiddleware(req: NextRequest, options?: NextgenMiddlewareOptions): Promise<NextResponse | Response>;
+export declare function nextgenMiddleware(req: NextRequest, options?: NextgenMiddlewareOptions): Promise<NextResponse | Response>;
 /**
  * Options for {@link createProxy} that are separate from the shared
  * {@link ZitadelConfig}. These configure route protection, login
@@ -38,11 +41,11 @@ declare function nextgenMiddleware(req: NextRequest, options?: NextgenMiddleware
  * `proxyPath` and `url` are omitted because they come from the
  * {@link ZitadelConfig} passed as the first argument.
  */
-type ProxyOptions = Omit<NextgenMiddlewareOptions, 'proxyPath' | 'url'>;
+export type ProxyOptions = Omit<NextgenMiddlewareOptions, "proxyPath" | "url">;
 /**
  * A pre-configured middleware handler returned by {@link createProxy}.
  */
-type ProxyHandler = (req: NextRequest) => Promise<NextResponse | Response>;
+export type ProxyHandler = (req: NextRequest) => Promise<NextResponse | Response>;
 /**
  * Creates a pre-configured middleware handler from the SDK config
  * returned by `configureZitadel()`. This is the derived-service
@@ -54,7 +57,7 @@ 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,10 +74,15 @@ 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.
  */
-declare function createProxy(config: ZitadelProject, options?: ProxyOptions): ProxyHandler;
-
-export { type ProxyHandler, type ProxyOptions, createProxy, nextgenMiddleware };
+export declare function createProxy(config: ZitadelProject, options?: ProxyOptions): ProxyHandler;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +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,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,9 +1,304 @@
-import {
-  createProxy,
-  nextgenMiddleware
-} from "./chunk-4KENHIG4.js";
-import "./chunk-OCZMYSFX.js";
-export {
-  createProxy,
-  nextgenMiddleware
-};
+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";
+/**
+ * Clones the incoming request headers, injects `extra` key/value pairs,
+ * and registers them with the Next.js header-tunnelling mechanism so that
+ * server components can read them via `headers()`.
+ *
+ * @param req   - The incoming edge request.
+ * @param extra - Additional headers to inject (e.g. `x-nextgen-auth-token`).
+ * @returns A new `Headers` instance with the injected values registered.
+ */
+function tunnelHeaders(req, extra) {
+    const headers = new Headers(req.headers);
+    // Security: strip any x-middleware-override-headers the client may have sent.
+    // Preserving the client value would allow an attacker to inject arbitrary
+    // header names into the Next.js override list, potentially bypassing the
+    // internal header-tunnelling safety checks. We always build this header from
+    // 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);
+        injectedNames.push(name);
+    }
+    headers.set("x-middleware-override-headers", injectedNames.join(","));
+    return headers;
+}
+/**
+ * Next.js Edge middleware that handles proxying, JWT verification, and route
+ * protection in a single pass.
+ *
+ * Place this in your `middleware.ts` file:
+ *
+ * ```ts
+ * import { nextgenMiddleware } from "@zitadel/sdk-next/middleware";
+ * import type { NextRequest } from "next/server";
+ *
+ * export function middleware(req: NextRequest) {
+ *   return nextgenMiddleware(req, {
+ *     url: process.env.ZITADEL_URL,
+ *     protectedRoutes: ["/profile"],
+ *     loginPath: "/login",
+ *   });
+ * }
+ *
+ * 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*"],
+ * };
+ * ```
+ *
+ * @param req     - The incoming Next.js edge request.
+ * @param options - Middleware configuration options.
+ * @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", 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.
+    if (!loginPath.startsWith("/") || loginPath.startsWith("//")) {
+        throw new Error(`[nextgen] loginPath must be a relative path starting with a single "/". ` +
+            `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)) {
+        return NextResponse.next();
+    }
+    if (pathname === proxyPath || pathname.startsWith(`${proxyPath}/`)) {
+        return proxyRequest(req, url, proxyPath, projectId, proxyTimeoutMs);
+    }
+    return handleAuth(req, {
+        url,
+        projectId,
+        protectedRoutes,
+        loginPath,
+        allowedAlgorithms,
+        clockSkewMs,
+        audience,
+        allowedTokenTypes,
+        jwksTimeoutMs,
+        opaqueTokenTimeoutMs,
+        pathname,
+    });
+}
+/**
+ * Forwards a `/__nextgen/*` request to the upstream auth backend and streams
+ * 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.
+ * When `X-Forwarded-For` is absent (direct connection with no upstream proxy),
+ * it is initialised from the runtime-provided client IP so the auth server
+ * always receives origin information. `X-Forwarded-Host` and `X-Forwarded-Proto`
+ * are set only when absent, preserving values injected by an upstream CDN.
+ *
+ * @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, projectId, proxyTimeoutMs) {
+    const url = new URL(req.url);
+    const suffix = url.pathname.slice(proxyPath.length);
+    const target = `${joinURL(authUrl, suffix)}${url.search}`;
+    const upstreamHeaders = new Headers();
+    for (const [key, value] of req.headers.entries()) {
+        const lower = key.toLowerCase();
+        if (!HOP_BY_HOP.has(lower) && !INTERNAL_HEADERS.has(lower)) {
+            upstreamHeaders.set(key, value);
+        }
+    }
+    // Always append the direct client IP to the X-Forwarded-For chain so the
+    // 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;
+    if (directIp) {
+        const existingXff = upstreamHeaders.get("x-forwarded-for");
+        upstreamHeaders.set("x-forwarded-for", existingXff ? `${existingXff}, ${directIp}` : directIp);
+    }
+    if (!upstreamHeaders.has("x-forwarded-host")) {
+        upstreamHeaders.set("x-forwarded-host", url.host);
+    }
+    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
+    // turns this public request boundary into an operator-capable open relay.
+    // Preserve an explicit caller credential so the exchange can use the future
+    // publishable-key plane without being overwritten.
+    if (requiresProjectSecret(req.method, suffix) && !upstreamHeaders.has("authorization")) {
+        const secret = process.env.ZITADEL_PROJECT_SECRET;
+        if (secret) {
+            upstreamHeaders.set("authorization", `Bearer ${secret}`);
+        }
+    }
+    // Read body eagerly so undici receives a concrete buffer rather than a
+    // WinterCG ReadableStream, which is incompatible with Node.js fetch body
+    // extraction.
+    const bodyBuffer = hasBody ? await req.arrayBuffer() : undefined;
+    const upstream = await fetch(target, {
+        method: req.method,
+        headers: upstreamHeaders,
+        body: bodyBuffer,
+        redirect: "manual",
+        signal: AbortSignal.timeout(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 answer = await sessionCookies.toBrowser(upstream);
+    for (const cookie of answer.setCookies) {
+        responseHeaders.append("set-cookie", cookie);
+    }
+    if (answer.setCookies.length > 0) {
+        responseHeaders.set("cache-control", SESSION_COOKIE_CACHE_CONTROL);
+    }
+    return new Response(answer.body, {
+        status: upstream.status,
+        headers: responseHeaders,
+    });
+}
+/**
+ * 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, redirect, or answer `503`.
+ */
+async function handleAuth(req, opts) {
+    const { protectedRoutes, loginPath, pathname, ...verification } = opts;
+    const authHeader = req.headers.get("authorization");
+    const bearerToken = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+    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 } });
+    }
+    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 });
+    }
+    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 } });
+    }
+    // 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;
+}
+/**
+ * Creates a pre-configured middleware handler from the SDK config
+ * returned by `configureZitadel()`. This is the derived-service
+ * derived service pattern:
+ *
+ * ```ts
+ * // src/zitadel.ts
+ * import { configureZitadel } from "@zitadel/api/config";
+ * import { createProxy } from "@zitadel/sdk-next/middleware";
+ *
+ * const zitadel = configureZitadel({
+ *   projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID ?? "",
+ *   url: process.env.ZITADEL_URL,
+ * });
+ *
+ * export const proxy = createProxy(zitadel, {
+ *   protectedRoutes: ["/admin*"],
+ *   loginPath: "/login",
+ * });
+ * ```
+ *
+ * Then in middleware.ts:
+ *
+ * ```ts
+ * import { proxy } from "./zitadel";
+ * 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.
+ */
+export function createProxy(config, options = {}) {
+    const mergedOptions = {
+        ...options,
+        projectId: options.projectId ?? (config.projectId || undefined),
+        proxyPath: config.proxyPath,
+        url: config.url,
+    };
+    return (req) => nextgenMiddleware(req, mergedOptions);
+}