@zitadel/sdk-nuxt 0.1.0-alpha.17 → 0.1.0-alpha.19

package/README.md

@@ -1,6 +1,6 @@
 # @zitadel/sdk-nuxt
 
-Nuxt middleware and helpers for Nextgen Auth.
+Nuxt module, Nitro middleware, and helpers for Nextgen Auth.
 
 ## Installation
 
@@ -8,67 +8,66 @@ Nuxt middleware and helpers for Nextgen Auth.
 pnpm add @zitadel/sdk-nuxt
 ```
 
-## Setup
+There are two ways to wire the SDK. **The module is what `zitadel setup`
+scaffolds** and the recommended path; the direct-middleware surface remains
+for hand-rolled setups.
 
-### 1. Server middleware
+## Surface 1 — the Nuxt module (recommended, CLI-scaffolded)
 
-Create `server/middleware/auth.ts`:
-
-```ts
-import { createNextgenMiddleware } from '@zitadel/sdk-nuxt/server';
-
-const { nextgen } = useRuntimeConfig();
-
-export default createNextgenMiddleware({
-  url: nextgen.url,
-  protectedRoutes: ['/admin', '/dashboard*'],
-  loginPath: '/login',
-});
-```
-
-The middleware runs on every request 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
-
-Add the issuer URL to `nuxt.config.ts`:
+Register the module under the `nextgen` config key, and give the client
+plugin your project id via `runtimeConfig.public.zitadelProjectId` — without
+it the plugin skips `configureZitadel()`, `useZitadelProject()` returns
+`null`, and the login widget cannot initialize:
 
 ```ts
 export default defineNuxtConfig({
+  modules: ['@zitadel/sdk-nuxt/module'],
+  nextgen: {
+    url: process.env.ZITADEL_URL ?? 'http://localhost:8080',
+    protectedRoutes: ['/admin', '/dashboard*'],
+    loginPath: '/login',
+  },
   runtimeConfig: {
-    nextgen: {
-      url: process.env.ZITADEL_URL ?? 'http://localhost:4000',
+    public: {
+      zitadelProjectId: process.env.NUXT_PUBLIC_ZITADEL_PROJECT_ID ?? '',
     },
   },
 });
 ```
 
-### 2. Plugin
+(This mirrors what `zitadel setup` writes into `nuxt.config.ts`.)
 
-Create `plugins/auth.server.ts` to make auth state available in pages:
+The module registers the Nitro server middleware, the auth plugin (which
+seeds server-side auth state, hydrates it on the client, and calls
+`configureZitadel()` from the runtime config above), and auto-imports the
+composables — no `server/middleware/auth.ts`, no manual plugin.
 
-```ts
-import { defineNuxtPlugin, useRequestEvent, useState } from '#imports';
-
-export default defineNuxtPlugin(() => {
-  const event = useRequestEvent();
-  const auth = event?.context.nextgenAuth ?? {
-    isAuthenticated: false as const,
-    session: null,
-  };
-  useState('nextgen-auth', () => auth);
-});
-```
+### Module options (what the module actually forwards)
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | `string` | `ZITADEL_URL` env, else `http://localhost:8080` | Full URL of the Zitadel auth backend |
+| `proxyPath` | `string` | `"/__nextgen"` | The path the **client** widgets call (exposed via public runtime config). The registered server handler currently always serves `/__nextgen` regardless of this option — to actually move the server prefix, use the direct-middleware surface |
+| `protectedRoutes` | `string[]` | `[]` | Paths requiring a valid session. Trailing `*` matches sub-paths |
+| `loginPath` | `string` | `"/login"` | Where to redirect unauthenticated users |
 
-### 3. Reading auth in a page
+The module's registered handler reads only `url`, `protectedRoutes`, and
+`loginPath` from runtime config; `proxyPath` configures the client side only
+(see its row above). The fine-tuning options of the direct-middleware surface
+(`ignoredRoutes`, `allowedAlgorithms`, `allowedTokenTypes`, `clockSkewMs`,
+`jwksTimeoutMs`, `opaqueTokenTimeoutMs`, `proxyTimeoutMs`, `audience`) are
+**not currently forwarded by the module** — if you need them, use Surface 2.
+The module also loads the server-only project secret into runtime config at
+startup, from the `ZITADEL_PROJECT_SECRET` environment variable or the
+scaffolded `.env.local`.
+
+### Reading auth state
+
+`useAuth()` is auto-imported:
 
 ```vue
 <script setup lang="ts">
-const auth = useState('nextgen-auth');
-if (auth.value?.isAuthenticated) {
-  await navigateTo('/admin');
-}
+const auth = useAuth();
 </script>
 
 <template>
@@ -76,10 +75,30 @@ if (auth.value?.isAuthenticated) {
 </template>
 ```
 
-### 4. Register components (client only)
+The returned state intentionally omits the raw JWT — use `getAuth(event)` in
+a server route when you need the token to call upstream APIs:
+
+```ts
+import { getAuth } from '@zitadel/sdk-nuxt/server';
+
+export default defineEventHandler((event) => {
+  const auth = getAuth(event);
+  if (!auth.isAuthenticated) throw createError({ statusCode: 401 });
+  return { userId: auth.session.userId };
+});
+```
+
+### Login page
+
+Register the shared components in a client-only plugin
+(`plugins/zitadel-components.client.ts` — do **not** import
+`@zitadel/components` from page `<script setup>`, that runs during SSR).
+Under strict package managers (pnpm, Yarn PnP) `@zitadel/components` is not
+resolvable as a transitive dependency, so declare it in your app first:
 
-Create `plugins/zitadel-components.client.ts` — do **not** import
-`@zitadel/components` from page `<script setup>` (that runs during SSR):
+```bash
+pnpm add @zitadel/components
+```
 
 ```ts
 import "@zitadel/components";
@@ -87,37 +106,48 @@ import "@zitadel/components";
 export default defineNuxtPlugin(() => {});
 ```
 
-Set `body { margin: 0; font-family: sans-serif; }` in `app.vue` (see
-[`apps/demo-nuxt`](../../apps/demo-nuxt/README.md)). Arimo loads from
-`branding.font_url` inside `<zitadel-login>` when the mock/API supplies it.
-
-### 5. Login page
-
-Render `<zitadel-login>` inside `<ClientOnly>`:
+Then render `<zitadel-login>` inside `<ClientOnly>`, binding the project
+handle from the auto-imported `useZitadelProject()` composable — there is no
+`api-base` attribute:
 
 ```vue
+<script setup lang="ts">
+const project = useZitadelProject();
+</script>
+
 <template>
   <main>
     <ClientOnly>
-      <zitadel-login api-base="/__nextgen" project-id="demo" post-sign-in-url="/admin" />
+      <zitadel-login :project="project" post-sign-in-url="/admin" />
     </ClientOnly>
   </main>
 </template>
 ```
 
-### 6. Reading auth in a server route
+## Surface 2 — direct middleware (hand-rolled)
+
+Create `server/middleware/auth.ts` yourself when you need the full option
+set:
 
 ```ts
-import { getAuth } from '@zitadel/sdk-nuxt/server';
+import { createNextgenMiddleware } from '@zitadel/sdk-nuxt/server';
 
-export default defineEventHandler((event) => {
-  const auth = getAuth(event);
-  if (!auth.isAuthenticated) throw createError({ statusCode: 401 });
-  return { userId: auth.session.userId };
+const { nextgen } = useRuntimeConfig();
+
+export default createNextgenMiddleware({
+  url: nextgen.url,
+  protectedRoutes: ['/admin', '/dashboard*'],
+  loginPath: '/login',
 });
 ```
 
-## Middleware options
+The middleware runs on every request 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
+
+### Direct-middleware options
 
 | Option              | Type                 | Default                  | Description                                                                                                                |
 | ------------------- | -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
@@ -130,17 +160,13 @@ export default defineEventHandler((event) => {
 | `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`                                               |
+| `proxyTimeoutMs`    | `number`             | `5000`                   | Timeout in ms for upstream proxy requests; requests exceeding it abort with a network error                                |
 | `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}/auth/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 it, the Nitro middleware strips the `x-nextgen-auth-token` header
+from all proxied requests to prevent internal state leakage.

package/dist/{chunk-AQZKZRKQ.js → chunk-MJ3RLEU6.js}

@@ -96,7 +96,7 @@ async function proxyRequest(event, authUrl, proxyPath, url, proxyTimeoutMs) {
   const rawBody = hasBody ? await readRawBody(event, false) : void 0;
   const body = rawBody != null ? new Uint8Array(rawBody) : void 0;
   const upstreamHeaders = buildUpstreamHeaders(event);
-  if (!upstreamHeaders.has("authorization")) {
+  if (requiresProjectSecret(method, suffix) && !upstreamHeaders.has("authorization")) {
     const config = useRuntimeConfig();
     const projectSecret = config.nextgen?.projectSecret;
     if (projectSecret) {
@@ -130,6 +130,9 @@ async function proxyRequest(event, authUrl, proxyPath, url, proxyTimeoutMs) {
   }
   return response.body;
 }
+function requiresProjectSecret(method, pathname) {
+  return method.toUpperCase() === "POST" && pathname === "/sessions/exchange";
+}
 var DECODER = new TextDecoder();
 function isJwtShaped(token) {
   const parts = token.split(".");
@@ -193,13 +196,14 @@ async function handleAuth(event, opts) {
     };
     return;
   }
+  let liveAnonymousSession = false;
   if (!payload && cookieToken && !isJwtShaped(cookieToken)) {
     const opaqueResult = await validateOpaqueSessionToken(cookieToken, url, opaqueTokenTimeoutMs);
-    if (opaqueResult) {
+    if (opaqueResult?.userId) {
       event.context.nextgenAuth = {
         isAuthenticated: true,
         session: {
-          userId: opaqueResult.userId ?? "unknown",
+          userId: opaqueResult.userId,
           email: null,
           name: null,
           token: cookieToken
@@ -207,11 +211,14 @@ async function handleAuth(event, opts) {
       };
       return;
     }
+    liveAnonymousSession = opaqueResult !== null;
   }
   event.context.nextgenAuth = { isAuthenticated: false, session: null };
-  for (const name of Object.keys(parseCookies(event))) {
-    if (name.startsWith("__nextgen")) {
-      deleteCookie(event, name);
+  if (!liveAnonymousSession) {
+    for (const name of Object.keys(parseCookies(event))) {
+      if (name.startsWith("__nextgen")) {
+        deleteCookie(event, name);
+      }
     }
   }
   if (matchesRoutes(pathname, protectedRoutes)) {

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-export { ZitadelLogin, ZitadelLogout } from '@zitadel/components';
+export { ZitadelLogin, ZitadelLogout, businessLocales } from '@zitadel/components';
 export { createNextgenMiddleware, getAuth } from './runtime/server/middleware.js';
 import { ZitadelProject } from '@zitadel/api/config';
-export { ClientAuthResult } from './runtime/types.js';
-export { AuthResult, NextgenMiddlewareOptions } from '@zitadel/sdk-core/middleware';
+export { AuthResult, ClientAuthResult, NextgenMiddlewareOptions } from '@zitadel/sdk-core/middleware';
 import 'h3';
 
 /**

package/dist/index.js

@@ -2,10 +2,11 @@ import "./chunk-ZNXAFGLP.js";
 import {
   createNextgenMiddleware,
   getAuth
-} from "./chunk-AQZKZRKQ.js";
+} from "./chunk-MJ3RLEU6.js";
 
 // src/index.ts
 import { ZitadelLogin, ZitadelLogout } from "@zitadel/components";
+import { businessLocales } from "@zitadel/components";
 
 // src/runtime/composables/useZitadelProject.ts
 import { getZitadelConfig } from "@zitadel/api/config";
@@ -15,6 +16,7 @@ function useZitadelProject() {
 export {
   ZitadelLogin,
   ZitadelLogout,
+  businessLocales,
   createNextgenMiddleware,
   getAuth,
   useZitadelProject

package/dist/module.js

@@ -48,7 +48,7 @@ var module_default = defineNuxtModule({
       // Server-only — never exposed to the client. Override at deploy time via
       // `NUXT_NEXTGEN_PROJECT_SECRET`. Left undefined when the env var (and
       // `.env.local`) provide no value, so the middleware surfaces a missing
-      // bearer instead of silently sending an empty one.
+      // exchange bearer instead of silently sending an empty one.
       projectSecret: loadProjectSecret(nuxt.options.rootDir)
     };
     nuxt.options.runtimeConfig.public.zitadelProxyPath = options.proxyPath ?? "/__nextgen";

package/dist/runtime/server/handler.js

@@ -1,6 +1,6 @@
 import {
   createNextgenMiddleware
-} from "../../chunk-AQZKZRKQ.js";
+} from "../../chunk-MJ3RLEU6.js";
 
 // src/runtime/server/handler.ts
 import { useRuntimeConfig } from "#imports";

package/dist/runtime/server/middleware.js

@@ -1,7 +1,7 @@
 import {
   createNextgenMiddleware,
   getAuth
-} from "../../chunk-AQZKZRKQ.js";
+} from "../../chunk-MJ3RLEU6.js";
 export {
   createNextgenMiddleware,
   getAuth

package/dist/runtime/types.d.ts

@@ -1,37 +1 @@
-import { UnauthState } from '@zitadel/sdk-core/middleware';
-export { AuthResult, AuthState, NextgenMiddlewareOptions, NextgenSession, UnauthState } from '@zitadel/sdk-core/middleware';
-
-/**
- * Re-exports shared SDK types from `@zitadel/sdk-core`.
- *
- * These types are defined once in sdk-core and shared by both sdk-next
- * and sdk-nuxt.
- */
-
-/**
- * The client-safe session exposed to Vue components via {@link useAuth}.
- * Identical to {@link NextgenSession} but omits `token` — the raw JWT must
- * not be serialised into the Nuxt SSR payload where third-party scripts can
- * read it.
- */
-type ClientSession = {
-    /** The user's unique identifier (`sub` claim). */
-    userId: string;
-    /** The user's email address, or `null` if not present in the token. */
-    email: string | null;
-    /** The user's display name, or `null` if not present in the token. */
-    name: string | null;
-};
-/** Client-safe auth state when the user is signed in. */
-type ClientAuthState = {
-    isAuthenticated: true;
-    session: ClientSession;
-};
-/**
- * Union of all possible auth states returned by {@link useAuth}.
- * Token is intentionally absent — use {@link getAuth} server-side when the
- * raw JWT is needed.
- */
-type ClientAuthResult = ClientAuthState | UnauthState;
-
-export type { ClientAuthResult, ClientAuthState, ClientSession };
+export { AuthResult, AuthState, ClientAuthResult, ClientAuthState, ClientSession, NextgenMiddlewareOptions, NextgenSession, UnauthState } from '@zitadel/sdk-core/middleware';

package/dist/server.js

@@ -2,7 +2,7 @@ import "./chunk-ZNXAFGLP.js";
 import {
   createNextgenMiddleware,
   getAuth
-} from "./chunk-AQZKZRKQ.js";
+} from "./chunk-MJ3RLEU6.js";
 export {
   createNextgenMiddleware,
   getAuth

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zitadel/sdk-nuxt",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.19",
   "description": "Nuxt proxy middleware and helpers for the pre-release Zitadel preview.",
   "homepage": "https://github.com/zitadel/nextgen/tree/main/packages/sdk-nuxt#readme",
   "bugs": {
@@ -33,9 +33,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@zitadel/api": "0.1.0-alpha.17",
-    "@zitadel/sdk-core": "0.1.0-alpha.17",
-    "@zitadel/components": "0.1.0-alpha.17"
+    "@zitadel/api": "0.1.0-alpha.19",
+    "@zitadel/sdk-core": "0.1.0-alpha.19",
+    "@zitadel/components": "0.1.0-alpha.19"
   },
   "peerDependencies": {
     "h3": ">=1",
@@ -53,7 +53,7 @@
     "eslint-plugin-perfectionist": "^4.0.0",
     "eslint-plugin-prettier": "^5.0.0",
     "h3": "^1.15.3",
-    "nuxt": "^4.4.8",
+    "nuxt": "^4.5.1",
     "prettier": "^3.0.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",