@zitadel/sdk-core 0.1.0-alpha.9 → 1.0.0-alpha.20

package/README.md

@@ -1,3 +1,53 @@
 # @zitadel/sdk-core
 
-Core public runtime types and mock flow helpers used by the v1 Zitadel setup CLI.
+The shared runtime contract behind the framework SDKs: JWT verification,
+middleware primitives, runtime resolution, and the session types every
+`@zitadel/sdk-*` package re-exports. Application code usually consumes a
+framework SDK (`@zitadel/sdk-next`, `@zitadel/sdk-nuxt`, or one of the SPA
+SDKs) instead of this package directly — reach for `sdk-core` when you are
+building your own middleware or need the types without a framework wrapper.
+
+## Entry points
+
+| Import | What it carries |
+| --- | --- |
+| `@zitadel/sdk-core` | The middleware, JWT, and runtime-resolution exports in one namespace. The `/types` widget contract is **not** re-exported from the root — import it from `@zitadel/sdk-core/types` |
+| `@zitadel/sdk-core/types` | The SPA widget contract (`ZitadelFlowStepDetail` and the other widget event/config/handler/props types the SPA SDKs re-export) |
+| `@zitadel/sdk-core/jwt` | `verifyJwt`, `decodeJwt`, `isJwtShaped`, `JWKS_TTL_MS` |
+| `@zitadel/sdk-core/middleware` | The middleware layer: `NextgenSession`, `AuthResult`, `NextgenMiddlewareOptions`, route matching (`matchesRoutes`), response-header filtering (`filterResponseHeaders`, `HOP_BY_HOP`) |
+
+It also exports `resolveZitadelRuntime` / `resolveZitadelRuntimeEnv` and
+`ZitadelRuntimeError` for resolving the runtime environment
+(`development` / `preview` / `production`).
+
+## How JWT verification works
+
+This is the canonical description of the verification pipeline every SDK
+middleware runs (`verifyJwt`):
+
+1. The bearer token from the `Authorization` header is checked first; the
+   `__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 timeout (`jwksTimeoutMs`), and cached per `kid`
+   (`JWKS_TTL_MS`).
+6. The signature is verified **before** any claim checks.
+7. `iss` must be present and equal `url` — tokens without an issuer are
+   rejected.
+8. `exp` must be present and in the future (with `clockSkewMs` tolerance) —
+   tokens without an expiry are rejected.
+9. `nbf` and `iat` are validated with `clockSkewMs` tolerance when present.
+
+Opaque (non-JWT) session tokens are validated against the backend's
+`GET /sessions/me` instead, bounded by `opaqueTokenTimeoutMs`.
+
+Framework-specific steps (header tunnelling, `auth()` re-verification) are
+documented in each framework SDK's README on top of this pipeline.
+
+## Requirements
+
+TypeScript ≥ 5.0 — the published type definitions re-export with
+`export type *`.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export type { NextgenSession, AuthState, UnauthState, AuthResult, NextgenMiddlewareOptions } from "./types.js";
-export { HOP_BY_HOP, INTERNAL_HEADERS, matchesRoutes, filterResponseHeaders } from "./middleware.js";
-export { verifyJwt, decodeJwt, base64UrlDecode, JWKS_TTL_MS } from "./jwt.js";
+export type { NextgenSession, AuthState, UnauthState, AuthResult, NextgenMiddlewareOptions, } from "./middleware.js";
+export { HOP_BY_HOP, INTERNAL_HEADERS, matchesRoutes, filterResponseHeaders, } from "./middleware.js";
+export { verifyJwt, decodeJwt, isJwtShaped, base64UrlDecode, JWKS_TTL_MS } from "./jwt.js";
 export type { JwtPayload, JwtHeader, DecodedJwt, VerifyJwtOptions } from "./jwt.js";
 export type ZitadelEnvironment = "development" | "preview" | "production";
 export type ZitadelRuntime = {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAC/G,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACrG,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC9E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEpF,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;AAE1E,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,kBAAkB,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAgB,GACrD,cAAc,CAMhB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAmBhF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,SAAS,EACT,WAAW,EACX,UAAU,EACV,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC3F,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEpF,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;AAE1E,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,kBAAkB,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAgB,GACrD,cAAc,CAMhB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAgBhF"}

package/dist/index.js

@@ -1,5 +1,5 @@
-export { HOP_BY_HOP, INTERNAL_HEADERS, matchesRoutes, filterResponseHeaders } from "./middleware.js";
-export { verifyJwt, decodeJwt, base64UrlDecode, JWKS_TTL_MS } from "./jwt.js";
+export { HOP_BY_HOP, INTERNAL_HEADERS, matchesRoutes, filterResponseHeaders, } from "./middleware.js";
+export { verifyJwt, decodeJwt, isJwtShaped, base64UrlDecode, JWKS_TTL_MS } from "./jwt.js";
 export class ZitadelRuntimeError extends Error {
     code;
     constructor(code, message) {
@@ -36,15 +36,6 @@ function parseEnvironment(value) {
         return value;
     throw new ZitadelRuntimeError("E_ZITADEL_CONFIG", `Unsupported ZITADEL_ENVIRONMENT "${value}".`);
 }
-// @ts-expect-error will be used later
-// oxlint-disable-next-line no-unused-vars
-function requireEnv(env, key) {
-    const value = env[key];
-    if (!value) {
-        throw new ZitadelRuntimeError("E_ZITADEL_CONFIG", `${key} is required for Zitadel runtime.`);
-    }
-    return value;
-}
 function currentEnv() {
     const scope = globalThis;
     return scope.process?.env ?? {};

package/dist/jwt.d.ts

@@ -236,6 +236,24 @@ export declare function base64UrlDecode(input: string): Uint8Array<ArrayBuffer>;
  * @throws {TypeError} When `token` has fewer than three dot-separated segments.
  */
 export declare function decodeJwt(token: string): DecodedJwt;
+/**
+ * Returns `true` when `token` looks structurally like a signed JWT (JWS) —
+ * NOT an encrypted token (JWE).
+ *
+ * JWS compact: 3 dot-separated segments; header has `alg` but NOT `enc`.
+ * JWE compact: 5 dot-separated segments; header has BOTH `alg` and `enc`.
+ *
+ * The Zitadel backend issues JWE tokens (AES-256-GCM via go-jose
+ * `A256GCMKW/A256GCM`), whose compact form is
+ * `header.encrypted_key.iv.ciphertext.tag`. The header decodes to JSON with
+ * `"alg":"A256GCMKW","enc":"A256GCM"`. Checking for the absence of `enc`
+ * correctly identifies signed JWTs without false-positives on JWE tokens.
+ *
+ * This is a structural check only — not a security check. Use it to route a
+ * token to the correct validation path ({@link verifyJwt} for JWS, a backend
+ * session lookup for everything else), never to trust one.
+ */
+export declare function isJwtShaped(token: string): boolean;
 /**
  * Verifies a compact-serialised JWT and returns its validated payload.
  *

package/dist/jwt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AAIH,yEAAyE;AACzE,eAAO,MAAM,WAAW,QAAiB,CAAC;AAI1C;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC1C,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;CAC9B;AAYD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE/C;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAE/C;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAQtE;AA0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAYnD;AAsHD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA+G5B"}
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../src/jwt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AAIH,yEAAyE;AACzE,eAAO,MAAM,WAAW,QAAiB,CAAC;AAI1C;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC1C,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;CAC9B;AAYD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE/C;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAE/C;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAKtE;AA0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAYnD;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CASlD;AA8GD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAqGjG"}

package/dist/jwt.js

@@ -143,8 +143,8 @@ const ENCODER = new TextEncoder();
  * @returns The decoded bytes.
  */
 export function base64UrlDecode(input) {
-    const base64 = input.replace(/-/g, '+').replace(/_/g, '/');
-    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+    const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
     const binary = atob(padded);
     return Uint8Array.from(binary, (c) => c.charCodeAt(0));
 }
@@ -162,7 +162,7 @@ export function base64UrlDecode(input) {
  *   has fewer than three dot-separated segments.
  */
 function splitToken(token) {
-    const [h, p, s] = token.split('.');
+    const [h, p, s] = token.split(".");
     if (!h || !p || !s) {
         return null;
     }
@@ -184,7 +184,7 @@ function splitToken(token) {
 export function decodeJwt(token) {
     const segments = splitToken(token);
     if (!segments) {
-        throw new TypeError(`Invalid JWT: expected at least three dot-separated segments, received ${token.split('.').length}.`);
+        throw new TypeError(`Invalid JWT: expected at least three dot-separated segments, received ${token.split(".").length}.`);
     }
     const [h, p] = segments;
     return {
@@ -192,6 +192,36 @@ export function decodeJwt(token) {
         payload: JSON.parse(DECODER.decode(base64UrlDecode(p))),
     };
 }
+// ─── JWT shape detection ──────────────────────────────────────────────────────
+/**
+ * Returns `true` when `token` looks structurally like a signed JWT (JWS) —
+ * NOT an encrypted token (JWE).
+ *
+ * JWS compact: 3 dot-separated segments; header has `alg` but NOT `enc`.
+ * JWE compact: 5 dot-separated segments; header has BOTH `alg` and `enc`.
+ *
+ * The Zitadel backend issues JWE tokens (AES-256-GCM via go-jose
+ * `A256GCMKW/A256GCM`), whose compact form is
+ * `header.encrypted_key.iv.ciphertext.tag`. The header decodes to JSON with
+ * `"alg":"A256GCMKW","enc":"A256GCM"`. Checking for the absence of `enc`
+ * correctly identifies signed JWTs without false-positives on JWE tokens.
+ *
+ * This is a structural check only — not a security check. Use it to route a
+ * token to the correct validation path ({@link verifyJwt} for JWS, a backend
+ * session lookup for everything else), never to trust one.
+ */
+export function isJwtShaped(token) {
+    const parts = token.split(".");
+    if (parts.length < 3 || !parts[0])
+        return false;
+    try {
+        const header = JSON.parse(DECODER.decode(base64UrlDecode(parts[0])));
+        return typeof header?.alg === "string" && !("enc" in header);
+    }
+    catch {
+        return false;
+    }
+}
 // ─── Algorithm helpers ────────────────────────────────────────────────────────
 /**
  * Web Crypto parameters for importing a public key from JWKS, keyed by JWT
@@ -199,28 +229,28 @@ export function decodeJwt(token) {
  * anything not present throws {@link TypeError}.
  */
 const IMPORT_PARAMS = {
-    RS256: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
-    RS384: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-384' },
-    RS512: { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-512' },
-    ES256: { name: 'ECDSA', namedCurve: 'P-256' },
-    ES384: { name: 'ECDSA', namedCurve: 'P-384' },
-    ES512: { name: 'ECDSA', namedCurve: 'P-521' },
+    RS256: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    RS384: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-384" },
+    RS512: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-512" },
+    ES256: { name: "ECDSA", namedCurve: "P-256" },
+    ES384: { name: "ECDSA", namedCurve: "P-384" },
+    ES512: { name: "ECDSA", namedCurve: "P-521" },
 };
 /**
  * Web Crypto parameters for verifying a JWT signature, keyed by JWT `alg`
  * header value.
  */
 const VERIFY_PARAMS = {
-    RS256: { name: 'RSASSA-PKCS1-v1_5' },
-    RS384: { name: 'RSASSA-PKCS1-v1_5' },
-    RS512: { name: 'RSASSA-PKCS1-v1_5' },
-    ES256: { name: 'ECDSA', hash: 'SHA-256' },
-    ES384: { name: 'ECDSA', hash: 'SHA-384' },
-    ES512: { name: 'ECDSA', hash: 'SHA-512' },
+    RS256: { name: "RSASSA-PKCS1-v1_5" },
+    RS384: { name: "RSASSA-PKCS1-v1_5" },
+    RS512: { name: "RSASSA-PKCS1-v1_5" },
+    ES256: { name: "ECDSA", hash: "SHA-256" },
+    ES384: { name: "ECDSA", hash: "SHA-384" },
+    ES512: { name: "ECDSA", hash: "SHA-512" },
 };
 function assertSupportedAlgorithm(alg) {
     if (!Object.hasOwn(IMPORT_PARAMS, alg)) {
-        throw new TypeError(`Unsupported JWT algorithm: "${alg}". Supported algorithms are ${Object.keys(IMPORT_PARAMS).join(', ')}.`);
+        throw new TypeError(`Unsupported JWT algorithm: "${alg}". Supported algorithms are ${Object.keys(IMPORT_PARAMS).join(", ")}.`);
     }
 }
 function resolveImportAlgorithm(alg) {
@@ -252,7 +282,7 @@ function resolveVerifyAlgorithm(alg) {
  * @param kid     - The `kid` header value from the JWT, or `undefined`.
  */
 async function fetchAndCacheJwks(jwksUri, kid, timeoutMs) {
-    const cacheKey = `${jwksUri}:${kid ?? '__default__'}`;
+    const cacheKey = `${jwksUri}:${kid ?? "__default__"}`;
     const cached = jwksCache.get(cacheKey);
     if (cached && Date.now() - cached.fetchedAt < JWKS_TTL_MS) {
         return cached.key;
@@ -270,8 +300,10 @@ async function fetchAndCacheJwks(jwksUri, kid, timeoutMs) {
     // for RSA; kty/crv/x/y for EC) determines the key type. Fall back to RS256
     // when absent. The actual algorithm enforcement happens in verifyJwt via the
     // JWT header's 'alg' claim, not here.
-    const alg = jwk.alg ?? 'RS256';
-    const cryptoKey = await crypto.subtle.importKey('jwk', jwk, resolveImportAlgorithm(alg), false, ['verify']);
+    const alg = jwk.alg ?? "RS256";
+    const cryptoKey = await crypto.subtle.importKey("jwk", jwk, resolveImportAlgorithm(alg), false, [
+        "verify",
+    ]);
     jwksCache.set(cacheKey, { key: cryptoKey, fetchedAt: Date.now() });
     return cryptoKey;
 }
@@ -320,14 +352,14 @@ export async function verifyJwt(token, opts) {
         // 'none' means the token is unsigned; accepting it would allow anyone to
         // forge arbitrary claims without a key. The comparison is case-insensitive
         // so that "None", "NONE", or any other casing variant is also rejected.
-        if (alg.toLowerCase() === 'none') {
+        if (alg.toLowerCase() === "none") {
             return null;
         }
         if (allowedAlgorithms?.length && !allowedAlgorithms.includes(alg)) {
             return null;
         }
         if (allowedTokenTypes.length > 0) {
-            const typ = header.typ ?? '';
+            const typ = header.typ ?? "";
             if (!allowedTokenTypes.some((t) => t.toLowerCase() === typ.toLowerCase())) {
                 return null;
             }
@@ -377,7 +409,7 @@ export async function verifyJwt(token, opts) {
         // Any other unexpected error (network failure, malformed JWKS, Web Crypto
         // exception) is worth logging so operators can distinguish infrastructure
         // failures from genuine bad tokens.
-        console.error('[nextgen] verifyJwt unexpected error:', err);
+        console.error("[nextgen] verifyJwt unexpected error:", err);
         return null;
     }
 }

package/dist/middleware.d.ts

@@ -36,4 +36,143 @@ export declare function matchesRoutes(pathname: string, routes: readonly string[
  * @returns A new `Headers` object with filtered headers.
  */
 export declare function filterResponseHeaders(upstream: Headers): Headers;
+/**
+ * The authenticated session for a signed-in user.
+ */
+export type NextgenSession = {
+    /** 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;
+    /** The raw verified JWT. */
+    token: string;
+};
+/** Auth state when the user is signed in. */
+export type AuthState = {
+    isAuthenticated: true;
+    session: NextgenSession;
+};
+/** Auth state when the user is not signed in. */
+export type UnauthState = {
+    isAuthenticated: false;
+    session: null;
+};
+/** Union of all possible auth states. */
+export type AuthResult = AuthState | UnauthState;
+/**
+ * The client-safe session exposed to app UI (headers, account menus).
+ * Identical to {@link NextgenSession} but omits `token` — the raw session
+ * token must never reach client-side JavaScript, whether through an SSR
+ * payload or a client-side fetch result.
+ */
+export type ClientSession = {
+    /** The user's unique identifier (`sub` claim). */
+    userId: string;
+    /** The user's email address, or `null` if not present. */
+    email: string | null;
+    /** The user's display name, or `null` if not present. */
+    name: string | null;
+};
+/** Client-safe auth state when the user is signed in. */
+export type ClientAuthState = {
+    isAuthenticated: true;
+    session: ClientSession;
+};
+/**
+ * Union of all possible client-safe auth states. Returned by the client
+ * session reads (`useAuth()` in sdk-nuxt, `getSession()` in sdk-next).
+ * Token is intentionally absent — use the server-side helpers when the raw
+ * token is needed.
+ */
+export type ClientAuthResult = ClientAuthState | UnauthState;
+/**
+ * Options passed to the SDK middleware factory (`nextgenMiddleware` in
+ * sdk-next, `createNextgenMiddleware` in sdk-nuxt).
+ */
+export type NextgenMiddlewareOptions = {
+    /**
+     * Full URL of the Zitadel auth backend.
+     * @default process.env.ZITADEL_URL ?? "http://localhost:8080"
+     */
+    url?: string;
+    /**
+     * URL path prefix that is reverse-proxied to the auth backend.
+     * @default "/__nextgen"
+     */
+    proxyPath?: string;
+    /**
+     * Pathnames that require a valid session. Requests to these routes without
+     * a valid token are redirected to {@link loginPath}.
+     * Entries ending with `*` match any sub-path (e.g. `"/admin*"`).
+     * @default []
+     */
+    protectedRoutes?: string[];
+    /**
+     * Pathnames that are completely skipped by the middleware — no JWT
+     * verification, no protection check, no header tunnelling.
+     * Useful for webhooks, health-check endpoints, or any route where
+     * running auth logic is undesirable.
+     * Entries ending with `*` match any sub-path (e.g. `"/public*"`).
+     * @default []
+     */
+    ignoredRoutes?: string[];
+    /**
+     * Pathname to redirect unauthenticated users to.
+     * A `next` query parameter is appended with the originally requested path.
+     * @default "/login"
+     */
+    loginPath?: string;
+    /**
+     * Reserved for future use. Local PEM public key for offline JWT verification.
+     */
+    jwtKey?: string;
+    /**
+     * Restrict accepted JWT `alg` header values. Tokens whose algorithm is not
+     * in this list are rejected before JWKS is fetched.
+     * @default ["RS256", "ES256"]
+     */
+    allowedAlgorithms?: string[];
+    /**
+     * Clock skew tolerance in milliseconds applied to `exp`, `nbf`, and `iat`
+     * claim validation.
+     * @default 5000
+     */
+    clockSkewMs?: number;
+    /**
+     * Expected value(s) of the `aud` claim. When omitted, audience is not
+     * validated. Pass a single string or an array when a token may carry
+     * multiple audiences.
+     */
+    audience?: string | string[];
+    /**
+     * Accepted values for the JWT header `typ` claim (case-insensitive).
+     * Tokens whose `typ` is not in this list are rejected.
+     * Set to `[]` to disable token-type checking entirely.
+     * @default ["JWT", "at+JWT"]
+     */
+    allowedTokenTypes?: string[];
+    /**
+     * Timeout in milliseconds for JWKS endpoint requests.
+     * Requests that do not complete within this window are aborted and the
+     * token is rejected, treating the request as unauthenticated.
+     * @default 5000
+     */
+    jwksTimeoutMs?: number;
+    /**
+     * Timeout in milliseconds for upstream proxy requests.
+     * Requests that do not complete within this window are aborted with a
+     * network error. Defaults to 5 000 ms.
+     * @default 5000
+     */
+    proxyTimeoutMs?: number;
+    /**
+     * Timeout in milliseconds for opaque (non-JWT) session token validation
+     * via the backend's `GET /sessions/me` endpoint. Tokens that cannot be
+     * validated within this window are treated as invalid.
+     * @default 5000
+     */
+    opaqueTokenTimeoutMs?: number;
+};
 //# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAazC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAE/C,CAAC;AAKH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,OAAO,CAUT;AAID;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAYhE"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAazC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAqC,CAAC;AAIvF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAUlF;AAID;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAYhE;AAID;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,sEAAsE;IACtE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG;IAAE,eAAe,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAE3E,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG;IAAE,eAAe,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC;AAEpE,yCAAyC;AACzC,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yDAAyD;IACzD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG;IAAE,eAAe,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,WAAW,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE7B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC"}

package/dist/middleware.js

@@ -11,27 +11,25 @@
  * two directly connected peers and become invalid when proxied.
  */
 export const HOP_BY_HOP = new Set([
-    'connection',
+    "connection",
     // host is not a hop-by-hop header per RFC 7230, but it must be stripped so
     // the fetch implementation derives the correct Host from the upstream URL
     // rather than forwarding the client's Host and causing SNI/vhost mismatches.
-    'host',
-    'keep-alive',
-    'proxy-authenticate',
-    'proxy-authorization',
-    'te',
-    'trailer',
-    'transfer-encoding',
-    'upgrade',
+    "host",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
 ]);
 /**
  * SDK-internal headers that must never be forwarded to the upstream backend.
  * These headers carry session data between the middleware and server components;
  * forwarding them upstream would expose internal state and allow header injection.
  */
-export const INTERNAL_HEADERS = new Set([
-    'x-nextgen-auth-token',
-]);
+export const INTERNAL_HEADERS = new Set(["x-nextgen-auth-token"]);
 // ─── Route matching ──────────────────────────────────────────────────────────
 /**
  * Returns `true` when `pathname` matches at least one entry in `routes`.
@@ -48,7 +46,7 @@ export function matchesRoutes(pathname, routes) {
         return false;
     }
     return routes.some((pattern) => {
-        if (pattern.endsWith('*')) {
+        if (pattern.endsWith("*")) {
             return pathname.startsWith(pattern.slice(0, -1));
         }
         return pathname === pattern;
@@ -65,12 +63,12 @@ export function matchesRoutes(pathname, routes) {
  */
 export function filterResponseHeaders(upstream) {
     const filtered = new Headers();
-    for (const [key, value] of upstream.entries()) {
+    upstream.forEach((value, key) => {
         if (!HOP_BY_HOP.has(key.toLowerCase()) &&
-            key.toLowerCase() !== 'set-cookie' &&
-            key.toLowerCase() !== 'location') {
+            key.toLowerCase() !== "set-cookie" &&
+            key.toLowerCase() !== "location") {
             filtered.set(key, value);
         }
-    }
+    });
     return filtered;
 }