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

package/README.md

@@ -1,3 +1,108 @@
 # @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`), session judgement (`resolveSession`, the opaque session check `checkOpaqueSessionToken`), and the session cookie per project (`sessionCookieName`, `proxySessionCookies`, `serializeSessionCookie`) |
+
+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
+   session cookie is the fallback (see
+   [The session cookie](#the-session-cookie)).
+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.
+10. `aud` must name the app's project (`projectId`).
+
+Opaque (non-JWT) session tokens are validated against the backend's
+`GET /sessions/me?project_id=…` instead, bounded by `opaqueTokenTimeoutMs`
+(`checkOpaqueSessionToken`).
+
+A session belongs to one project, while a browser sends the session cookie
+to every app on the same host, including the Console of a local server. So a
+session counts as signed in only in the app's own project: `projectId`, which
+each SDK otherwise reads from `ZITADEL_PROJECT_ID` (then its framework's public
+project id variable, as `zitadel setup` writes both). The backend refuses an
+opaque session of another project (`403 sess.project_mismatch`), and the SDK
+checks the project the answer names as well. A session of another project
+reads as signed out and keeps its cookie, since it is live in its own app.
+With no project configured, no session counts as signed in.
+
+Only the backend's refusal makes the session cookie dead, and only then does
+the middleware clear it: a `401`, or a `404` with the `sess.not_found` code for
+a session that is gone. A JWT session cookie is dead when it fails verification
+or names no user of this project. Any other outcome (a `5xx`, no answer in
+time, a network error) is not a refusal: the request counts as signed out, the
+cookie stays, and a protected route answers `503 Service Unavailable` rather
+than send a user who may well be signed in to the login page. A Bearer token
+that signs no one in here leaves the cookie to be judged on its own.
+
+`resolveSession` is the one implementation of these rules; every server SDK's
+middleware calls it.
+
+## The session cookie
+
+The server sets and reads one session cookie, `__nextgen_session`. A browser
+shares a host's cookies across every port, so under that name alone the Console
+of a local server and every app on `localhost` would keep their sessions in one
+slot and sign each other out. An app with a server SDK therefore keeps its
+session in a cookie of its own, `sessionCookieName(projectId)`:
+`__nextgen_session_<projectId>` (ADR 073).
+
+- **The proxy** (`proxySessionCookies`) renames the server's `Set-Cookie` to the
+  app's name on the way to the browser, and on the way to the server sends the
+  app's cookie under the server's name. No other session cookie, the
+  Console's or another app's, goes up.
+- **The middleware** (`resolveSession`) reads the app's cookie, and clears only
+  that cookie when the backend refuses its session.
+- **A session kept under the server's name** before the change, by this app or,
+  on `localhost`, by the Console, is read only where the server holds it to the
+  app's project: by the middleware, and by the proxy for the session probe
+  `GET /sessions/me?project_id=…`. A session that signs a user of this project
+  in is copied to the app's cookie, and the old cookie stays: the Console may
+  share the project. When the app next signs a user in (`POST /sessions/exchange`)
+  or out (`DELETE /sessions/me`), the proxy retires it: cleared when it holds a
+  session of this project (and on sign-out that session is ended), or a dead
+  one; left when it holds another project's.
+- **Every response that sets a session cookie** sends
+  `Cache-Control: private, no-store` (`SESSION_COOKIE_CACHE_CONTROL`), and
+  `Secure` follows the server's rule on the scheme and host a proxy in front of
+  the app forwarded (`X-Forwarded-Proto`, `X-Forwarded-Host`).
+- **Without a project**, the proxy passes the cookies through unchanged.
+
+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.mts

@@ -0,0 +1,23 @@
+import { DecodedJwt, JWKS_MIN_REFRESH_MS, JWKS_TTL_MS, JwtHeader, JwtPayload, VerifyJwtOptions, base64UrlDecode, clearJwksCache, decodeJwt, isJwtShaped, verifyJwt } from "./jwt.mjs";
+import { AuthResult, AuthState, BrowserRequest, HOP_BY_HOP, INTERNAL_HEADERS, NextgenMiddlewareOptions, NextgenSession, OpaqueSession, OpaqueSessionCheck, ProxiedAnswer, ProxiedRequest, ProxiedSessionCookies, ProxyUpstream, ResolveSessionOptions, ResolvedSession, SERVER_SESSION_COOKIE, SESSION_COOKIE_CACHE_CONTROL, SESSION_PROJECT_MISMATCH, SessionCookie, SessionRequest, UnauthState, checkOpaqueSessionToken, clearSessionCheckCache, filterResponseHeaders, jwtNamesProject, matchesRoutes, proxySessionCookies, requiresProjectSecret, resolveSession, serializeSessionCookie, sessionCookieName, validateOpaqueSessionToken } from "./middleware.mjs";
+//#region src/index.d.ts
+export type ZitadelEnvironment = "development" | "preview" | "production";
+export type ZitadelRuntime = {
+  projectId: string;
+  environment: ZitadelEnvironment;
+  issuer?: string;
+};
+export type ZitadelRuntimeInput = {
+  projectId?: string;
+  environment?: ZitadelEnvironment;
+  issuer?: string;
+};
+export declare class ZitadelRuntimeError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+export declare function resolveZitadelRuntimeEnv(env?: Record<string, string | undefined>): ZitadelRuntime;
+export declare function resolveZitadelRuntime(input: ZitadelRuntimeInput): ZitadelRuntime;
+//#endregion
+export { type AuthResult, type AuthState, type BrowserRequest, type DecodedJwt, HOP_BY_HOP, INTERNAL_HEADERS, JWKS_MIN_REFRESH_MS, JWKS_TTL_MS, type JwtHeader, type JwtPayload, type NextgenMiddlewareOptions, type NextgenSession, type OpaqueSession, type OpaqueSessionCheck, type ProxiedAnswer, type ProxiedRequest, type ProxiedSessionCookies, type ProxyUpstream, type ResolveSessionOptions, type ResolvedSession, SERVER_SESSION_COOKIE, SESSION_COOKIE_CACHE_CONTROL, SESSION_PROJECT_MISMATCH, type SessionCookie, type SessionRequest, type UnauthState, type VerifyJwtOptions, base64UrlDecode, checkOpaqueSessionToken, clearJwksCache, clearSessionCheckCache, decodeJwt, filterResponseHeaders, isJwtShaped, jwtNamesProject, matchesRoutes, proxySessionCookies, requiresProjectSecret, resolveSession, serializeSessionCookie, sessionCookieName, validateOpaqueSessionToken, verifyJwt };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;YAiDY;YAEA;EACV;EACA,aAAa;EACb;;YAGU;EACV;EACA,cAAc;EACd;;qBAGW,4BAA4B;WAC9B;EAEG,YAAA,cAAc;;wBAOZ,yBACd,MAAK,qCACJ;wBAQa,sBAAsB,OAAO,sBAAsB"}

package/dist/index.mjs

@@ -0,0 +1,40 @@
+import { JWKS_MIN_REFRESH_MS, JWKS_TTL_MS, base64UrlDecode, clearJwksCache, decodeJwt, isJwtShaped, verifyJwt } from "./jwt.mjs";
+import { HOP_BY_HOP, INTERNAL_HEADERS, SERVER_SESSION_COOKIE, SESSION_COOKIE_CACHE_CONTROL, SESSION_PROJECT_MISMATCH, checkOpaqueSessionToken, clearSessionCheckCache, filterResponseHeaders, jwtNamesProject, matchesRoutes, proxySessionCookies, requiresProjectSecret, resolveSession, serializeSessionCookie, sessionCookieName, validateOpaqueSessionToken } from "./middleware.mjs";
+//#region src/index.ts
+var ZitadelRuntimeError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "ZitadelRuntimeError";
+		this.code = code;
+	}
+};
+function resolveZitadelRuntimeEnv(env = currentEnv()) {
+	return resolveZitadelRuntime({
+		projectId: env.NEXT_PUBLIC_ZITADEL_PROJECT_ID ?? env.ZITADEL_PROJECT_ID,
+		environment: parseEnvironment(env.NEXT_PUBLIC_ZITADEL_ENVIRONMENT ?? env.ZITADEL_ENVIRONMENT),
+		issuer: env.NEXT_PUBLIC_ZITADEL_ISSUER ?? env.ZITADEL_ISSUER
+	});
+}
+function resolveZitadelRuntime(input) {
+	const environment = input.environment ?? "development";
+	if (!input.projectId) throw new ZitadelRuntimeError("E_ZITADEL_CONFIG", "ZITADEL_PROJECT_ID is required for Zitadel runtime.");
+	if (environment === "production" && !input.issuer) throw new ZitadelRuntimeError("E_ZITADEL_CONFIG", "ZITADEL_ISSUER is required in production.");
+	return {
+		projectId: input.projectId,
+		environment,
+		issuer: input.issuer
+	};
+}
+function parseEnvironment(value) {
+	if (!value || value === "development") return "development";
+	if (value === "preview" || value === "production") return value;
+	throw new ZitadelRuntimeError("E_ZITADEL_CONFIG", `Unsupported ZITADEL_ENVIRONMENT "${value}".`);
+}
+function currentEnv() {
+	return globalThis.process?.env ?? {};
+}
+//#endregion
+export { HOP_BY_HOP, INTERNAL_HEADERS, JWKS_MIN_REFRESH_MS, JWKS_TTL_MS, SERVER_SESSION_COOKIE, SESSION_COOKIE_CACHE_CONTROL, SESSION_PROJECT_MISMATCH, ZitadelRuntimeError, base64UrlDecode, checkOpaqueSessionToken, clearJwksCache, clearSessionCheckCache, decodeJwt, filterResponseHeaders, isJwtShaped, jwtNamesProject, matchesRoutes, proxySessionCookies, requiresProjectSecret, resolveSession, resolveZitadelRuntime, resolveZitadelRuntimeEnv, serializeSessionCookie, sessionCookieName, validateOpaqueSessionToken, verifyJwt };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["scope"],"sources":["../src/index.ts"],"sourcesContent":["export type {\n  NextgenSession,\n  AuthState,\n  UnauthState,\n  AuthResult,\n  NextgenMiddlewareOptions,\n} from \"./middleware.js\";\nexport {\n  HOP_BY_HOP,\n  INTERNAL_HEADERS,\n  matchesRoutes,\n  filterResponseHeaders,\n  requiresProjectSecret,\n  checkOpaqueSessionToken,\n  validateOpaqueSessionToken,\n  jwtNamesProject,\n  resolveSession,\n  SESSION_PROJECT_MISMATCH,\n  SERVER_SESSION_COOKIE,\n  sessionCookieName,\n  serializeSessionCookie,\n  proxySessionCookies,\n  clearSessionCheckCache,\n  SESSION_COOKIE_CACHE_CONTROL,\n} from \"./middleware.js\";\nexport type {\n  OpaqueSession,\n  OpaqueSessionCheck,\n  SessionRequest,\n  SessionCookie,\n  ResolveSessionOptions,\n  ResolvedSession,\n  ProxiedRequest,\n  ProxiedAnswer,\n  ProxiedSessionCookies,\n  ProxyUpstream,\n  BrowserRequest,\n} from \"./middleware.js\";\nexport {\n  verifyJwt,\n  decodeJwt,\n  isJwtShaped,\n  base64UrlDecode,\n  JWKS_TTL_MS,\n  JWKS_MIN_REFRESH_MS,\n  clearJwksCache,\n} from \"./jwt.js\";\nexport type { JwtPayload, JwtHeader, DecodedJwt, VerifyJwtOptions } from \"./jwt.js\";\n\nexport type ZitadelEnvironment = \"development\" | \"preview\" | \"production\";\n\nexport type ZitadelRuntime = {\n  projectId: string;\n  environment: ZitadelEnvironment;\n  issuer?: string;\n};\n\nexport type ZitadelRuntimeInput = {\n  projectId?: string;\n  environment?: ZitadelEnvironment;\n  issuer?: string;\n};\n\nexport class ZitadelRuntimeError extends Error {\n  readonly code: string;\n\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = \"ZitadelRuntimeError\";\n    this.code = code;\n  }\n}\n\nexport function resolveZitadelRuntimeEnv(\n  env: Record<string, string | undefined> = currentEnv(),\n): ZitadelRuntime {\n  return resolveZitadelRuntime({\n    projectId: env.NEXT_PUBLIC_ZITADEL_PROJECT_ID ?? env.ZITADEL_PROJECT_ID,\n    environment: parseEnvironment(env.NEXT_PUBLIC_ZITADEL_ENVIRONMENT ?? env.ZITADEL_ENVIRONMENT),\n    issuer: env.NEXT_PUBLIC_ZITADEL_ISSUER ?? env.ZITADEL_ISSUER,\n  });\n}\n\nexport function resolveZitadelRuntime(input: ZitadelRuntimeInput): ZitadelRuntime {\n  const environment = input.environment ?? \"development\";\n  if (!input.projectId) {\n    throw new ZitadelRuntimeError(\n      \"E_ZITADEL_CONFIG\",\n      \"ZITADEL_PROJECT_ID is required for Zitadel runtime.\",\n    );\n  }\n  if (environment === \"production\" && !input.issuer) {\n    throw new ZitadelRuntimeError(\"E_ZITADEL_CONFIG\", \"ZITADEL_ISSUER is required in production.\");\n  }\n  return {\n    projectId: input.projectId,\n    environment,\n    issuer: input.issuer,\n  };\n}\n\nfunction parseEnvironment(value: string | undefined): ZitadelEnvironment {\n  if (!value || value === \"development\") return \"development\";\n  if (value === \"preview\" || value === \"production\") return value;\n  throw new ZitadelRuntimeError(\"E_ZITADEL_CONFIG\", `Unsupported ZITADEL_ENVIRONMENT \"${value}\".`);\n}\n\nfunction currentEnv(): Record<string, string | undefined> {\n  const scope = globalThis as { process?: { env?: Record<string, string | undefined> } };\n  return scope.process?.env ?? {};\n}\n"],"mappings":";;;AA+DA,IAAa,sBAAb,cAAyC,MAAM;CAC7C;CAEA,YAAY,MAAc,SAAiB;EACzC,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,OAAO;CACd;AACF;AAEA,SAAgB,yBACd,MAA0C,WAAW,GACrC;CAChB,OAAO,sBAAsB;EAC3B,WAAW,IAAI,kCAAkC,IAAI;EACrD,aAAa,iBAAiB,IAAI,mCAAmC,IAAI,mBAAmB;EAC5F,QAAQ,IAAI,8BAA8B,IAAI;CAChD,CAAC;AACH;AAEA,SAAgB,sBAAsB,OAA4C;CAChF,MAAM,cAAc,MAAM,eAAe;CACzC,IAAI,CAAC,MAAM,WACT,MAAM,IAAI,oBACR,oBACA,qDACF;CAEF,IAAI,gBAAgB,gBAAgB,CAAC,MAAM,QACzC,MAAM,IAAI,oBAAoB,oBAAoB,2CAA2C;CAE/F,OAAO;EACL,WAAW,MAAM;EACjB;EACA,QAAQ,MAAM;CAChB;AACF;AAEA,SAAS,iBAAiB,OAA+C;CACvE,IAAI,CAAC,SAAS,UAAU,eAAe,OAAO;CAC9C,IAAI,UAAU,aAAa,UAAU,cAAc,OAAO;CAC1D,MAAM,IAAI,oBAAoB,oBAAoB,oCAAoC,MAAM,GAAG;AACjG;AAEA,SAAS,aAAiD;CAExD,OAAOA,WAAM,SAAS,OAAO,CAAC;AAChC"}

package/dist/{jwt.d.ts → jwt.d.mts}

@@ -1,3 +1,4 @@
+//#region src/jwt.d.ts
 /**
  * @file lib/jwt.ts
  *
@@ -81,17 +82,16 @@
  *
  * ## JWKS caching
  *
- * Public keys are expensive to fetch and import. They are cached in-process,
- * keyed by `"${jwksUri}:${kid}"` (or `"${jwksUri}:__default__"` when `kid` is
- * absent), for {@link JWKS_TTL_MS} milliseconds (default 5 minutes).
+ * Each issuer's whole JWKS document is cached in-process, keyed by its JWKS URI,
+ * for {@link JWKS_TTL_MS} milliseconds (default 5 minutes); keys are imported
+ * once and reused. Keying by the URI keeps two issuers that publish the same
+ * `kid` apart.
  *
- * Including the full JWKS URI in the cache key prevents a key imported for one
- * issuer from being mistakenly served when a different issuer happens to use the
- * same `kid` string — a scenario that can arise in multi-tenant deployments or
- * during key-rotation incidents where two servers briefly share a key identifier.
- *
- * A cache miss — on first use or after TTL expiry — triggers a fresh fetch
- * from `{issuerUrl}/auth/keys`.
+ * The document is fetched from `{issuerUrl}/auth/keys` on first use and after
+ * the TTL. A token naming a `kid` the cached document lacks refreshes it — how
+ * a rotated key is picked up — but no sooner than {@link JWKS_MIN_REFRESH_MS}
+ * after the last fetch. The `kid` header is attacker-controlled, so a per-`kid`
+ * cache would let any request with a made-up `kid` cost a JWKS fetch.
  *
  * > **Note (serverless):** the cache is module-level. In serverless environments
  * > each cold start gets a fresh cache; warm instances share it across requests.
@@ -106,8 +106,15 @@
  * The previous per-SDK copies (one using `atob`, one using `Buffer`) have
  * been consolidated here.
  */
-/** How long a cached JWKS key is considered fresh before re-fetching. */
+/** How long a cached JWKS document is considered fresh before re-fetching. */
 export declare const JWKS_TTL_MS: number;
+/**
+ * The least time between two JWKS fetches for one issuer. A token naming a
+ * `kid` the cached document lacks triggers a refresh — that is how a rotated
+ * key is picked up — but at most this often, so a stream of tokens with random
+ * `kid` values cannot turn every request into a JWKS fetch.
+ */
+export declare const JWKS_MIN_REFRESH_MS: number;
 /**
  * The subset of standard JWT payload claims this module reads or validates.
  *
@@ -117,26 +124,26 @@ export declare const JWKS_TTL_MS: number;
  * Refer to the module-level documentation for the full verification matrix.
  */
 export interface JwtPayload {
-    /** Issuer (`iss`) — identifies the auth server that created the token. */
-    readonly iss?: string;
-    /** Subject (`sub`) — the user's unique identifier. */
-    readonly sub?: string;
-    /**
-     * Audience (`aud`) — the intended recipient(s).
-     * A single string or an array of strings per RFC 7519 §4.1.3.
-     */
-    readonly aud?: string | readonly string[];
-    /** Expiration time (`exp`) — seconds since Unix epoch. */
-    readonly exp?: number;
-    /** Not before (`nbf`) — seconds since Unix epoch. */
-    readonly nbf?: number;
-    /** Issued at (`iat`) — seconds since Unix epoch. */
-    readonly iat?: number;
-    /** User's email address (custom claim). */
-    readonly email?: string;
-    /** User's display name (custom claim). */
-    readonly name?: string;
-    readonly [key: string]: unknown;
+  /** Issuer (`iss`) — identifies the auth server that created the token. */
+  readonly iss?: string;
+  /** Subject (`sub`) — the user's unique identifier. */
+  readonly sub?: string;
+  /**
+   * Audience (`aud`) — the intended recipient(s).
+   * A single string or an array of strings per RFC 7519 §4.1.3.
+   */
+  readonly aud?: string | readonly string[];
+  /** Expiration time (`exp`) — seconds since Unix epoch. */
+  readonly exp?: number;
+  /** Not before (`nbf`) — seconds since Unix epoch. */
+  readonly nbf?: number;
+  /** Issued at (`iat`) — seconds since Unix epoch. */
+  readonly iat?: number;
+  /** User's email address (custom claim). */
+  readonly email?: string;
+  /** User's display name (custom claim). */
+  readonly name?: string;
+  readonly [key: string]: unknown;
 }
 /**
  * The typed representation of a JWT header.
@@ -145,13 +152,13 @@ export interface JwtPayload {
  * header parameters are preserved under the index signature.
  */
 export interface JwtHeader {
-    /** Signing algorithm (`alg`) — e.g. `"RS256"`, `"ES256"`. */
-    readonly alg?: string;
-    /** Token type (`typ`) — e.g. `"JWT"`, `"at+JWT"`. */
-    readonly typ?: string;
-    /** Key ID (`kid`) — selects the matching public key from the JWKS. */
-    readonly kid?: string;
-    readonly [key: string]: unknown;
+  /** Signing algorithm (`alg`) — e.g. `"RS256"`, `"ES256"`. */
+  readonly alg?: string;
+  /** Token type (`typ`) — e.g. `"JWT"`, `"at+JWT"`. */
+  readonly typ?: string;
+  /** Key ID (`kid`) — selects the matching public key from the JWKS. */
+  readonly kid?: string;
+  readonly [key: string]: unknown;
 }
 /**
  * The decoded, unverified parts of a compact-serialised JWT.
@@ -161,8 +168,8 @@ export interface JwtHeader {
  * raw data into the next step.
  */
 export interface DecodedJwt {
-    readonly header: JwtHeader;
-    readonly payload: JwtPayload;
+  readonly header: JwtHeader;
+  readonly payload: JwtPayload;
 }
 /**
  * Options for {@link verifyJwt}.
@@ -170,49 +177,55 @@ export interface DecodedJwt {
  * All fields are `readonly` — this object is never mutated after construction.
  */
 export interface VerifyJwtOptions {
-    /**
-     * Base URL of the auth backend.
-     *
-     * Serves two purposes:
-     * 1. Determines the JWKS endpoint: `{issuerUrl}/auth/keys`
-     * 2. Is compared against the `iss` claim when present in the token.
-     */
-    readonly issuerUrl: string;
-    /**
-     * Restrict accepted `alg` header values. Tokens whose algorithm is not in
-     * this list are rejected before the JWKS is fetched.
-     * When `undefined`, all algorithms are accepted (the middleware layer
-     * defaults to `["RS256", "ES256"]` before passing options here).
-     */
-    readonly allowedAlgorithms?: readonly string[];
-    /**
-     * Clock-skew tolerance in milliseconds, applied symmetrically to `exp`,
-     * `nbf`, and `iat` checks to accommodate minor differences between clocks.
-     */
-    readonly clockSkewMs: number;
-    /**
-     * Expected `aud` claim value(s). When `undefined`, audience is not
-     * validated. Provide a string or array when the auth server sets `aud`
-     * and you want to ensure the token was issued specifically for your app.
-     */
-    readonly audience?: string | readonly string[];
-    /**
-     * Accepted `typ` header values (case-insensitive).
-     *
-     * Guards against using a refresh token or ID token where an access token
-     * is expected. Set to an empty array (`[]`) to disable this check.
-     *
-     * @default ["JWT", "at+JWT"]
-     */
-    readonly allowedTokenTypes: readonly string[];
-    /**
-     * Timeout in milliseconds for JWKS endpoint requests.
-     * Requests that do not complete within this window are aborted and the
-     * token is rejected (function returns `null`).
-     * @default 5000
-     */
-    readonly jwksTimeoutMs?: number;
+  /**
+   * Base URL of the auth backend.
+   *
+   * Serves two purposes:
+   * 1. Determines the JWKS endpoint: `{issuerUrl}/auth/keys`
+   * 2. Is compared against the `iss` claim when present in the token.
+   */
+  readonly issuerUrl: string;
+  /**
+   * Restrict accepted `alg` header values. Tokens whose algorithm is not in
+   * this list are rejected before the JWKS is fetched.
+   * When `undefined`, all algorithms are accepted (the middleware layer
+   * defaults to `["RS256", "ES256"]` before passing options here).
+   */
+  readonly allowedAlgorithms?: readonly string[];
+  /**
+   * Clock-skew tolerance in milliseconds, applied symmetrically to `exp`,
+   * `nbf`, and `iat` checks to accommodate minor differences between clocks.
+   */
+  readonly clockSkewMs: number;
+  /**
+   * Expected `aud` claim value(s). When `undefined`, audience is not
+   * validated. Provide a string or array when the auth server sets `aud`
+   * and you want to ensure the token was issued specifically for your app.
+   */
+  readonly audience?: string | readonly string[];
+  /**
+   * Accepted `typ` header values (case-insensitive).
+   *
+   * Guards against using a refresh token or ID token where an access token
+   * is expected. Set to an empty array (`[]`) to disable this check.
+   *
+   * @default ["JWT", "at+JWT"]
+   */
+  readonly allowedTokenTypes: readonly string[];
+  /**
+   * Timeout in milliseconds for JWKS endpoint requests.
+   * Requests that do not complete within this window are aborted and the
+   * token is rejected (function returns `null`).
+   * @default 5000
+   */
+  readonly jwksTimeoutMs?: number;
 }
+/**
+ * Forgets every cached JWKS document, so the next verification fetches the key
+ * set anew. Use it to drop a compromised key at once instead of waiting out
+ * {@link JWKS_TTL_MS}, and in tests that publish different keys per case.
+ */
+export declare function clearJwksCache(): void;
 /**
  * Decodes a Base64URL-encoded string into a `Uint8Array`.
  *
@@ -236,6 +249,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.
  *
@@ -261,4 +292,5 @@ export declare function decodeJwt(token: string): DecodedJwt;
  * @returns The verified {@link JwtPayload}, or `null` if verification fails.
  */
 export declare function verifyJwt(token: string, opts: VerifyJwtOptions): Promise<JwtPayload | null>;
-//# sourceMappingURL=jwt.d.ts.map
+//#endregion
+//# sourceMappingURL=jwt.d.mts.map

package/dist/jwt.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.mts","names":[],"sources":["../src/jwt.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiHa;;;;;;;qBAQA;;;;;;;;;iBAYI;;WAEN;;WAEA;;;;;WAKA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;YACC;;;;;;;;iBASK;;WAEN;;WAEA;;WAEA;YACC;;;;;;;;;iBAUK;WACN,QAAQ;WACR,SAAS;;;;;;;iBAuBH;;;;;;;;WAQN;;;;;;;WAQA;;;;;WAMA;;;;;;WAOA;;;;;;;;;WAUA;;;;;;;WAQA;;;;;;;wBAkCK;;;;;;;;;;wBAqBA,gBAAgB,gBAAgB,WAAW;;;;;;;;;;;;;wBA2C3C,UAAU,gBAAgB;;;;;;;;;;;;;;;;;;wBAiC1B,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;wBA8ON,UAAU,eAAe,MAAM,mBAAmB,QAAQ"}