@zitadel/sdk-core 0.1.0-alpha.0 → 0.1.0-alpha.11

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { NextgenSession, AuthState, UnauthState, AuthResult, NextgenMiddlewareOptions } from "./types.js";
-export { HOP_BY_HOP, INTERNAL_HEADERS, matchesRoutes, filterResponseHeaders } from "./middleware.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, base64UrlDecode, JWKS_TTL_MS } from "./jwt.js";
 export type { JwtPayload, JwtHeader, DecodedJwt, VerifyJwtOptions } from "./jwt.js";
 export type ZitadelEnvironment = "development" | "preview" | "production";

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;IAEtB,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIxC;CACF;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,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,CAgBhF"}

package/dist/index.js

@@ -1,36 +1,42 @@
-import { HOP_BY_HOP as e, INTERNAL_HEADERS as t, filterResponseHeaders as n, matchesRoutes as r } from "./middleware.js";
-import { JWKS_TTL_MS as i, base64UrlDecode as a, decodeJwt as o, verifyJwt as s } from "./jwt.js";
-//#region src/index.ts
-var c = class extends Error {
-	code;
-	constructor(e, t) {
-		super(t), this.name = "ZitadelRuntimeError", this.code = e;
-	}
-};
-function l(e = f()) {
-	return u({
-		projectId: e.NEXT_PUBLIC_ZITADEL_PROJECT_ID ?? e.ZITADEL_PROJECT_ID,
-		environment: d(e.NEXT_PUBLIC_ZITADEL_ENVIRONMENT ?? e.ZITADEL_ENVIRONMENT),
-		issuer: e.NEXT_PUBLIC_ZITADEL_ISSUER ?? e.ZITADEL_ISSUER
-	});
+export { HOP_BY_HOP, INTERNAL_HEADERS, matchesRoutes, filterResponseHeaders, } from "./middleware.js";
+export { verifyJwt, decodeJwt, base64UrlDecode, JWKS_TTL_MS } from "./jwt.js";
+export class ZitadelRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ZitadelRuntimeError";
+        this.code = code;
+    }
 }
-function u(e) {
-	let t = e.environment ?? "development";
-	if (!e.projectId) throw new c("E_ZITADEL_CONFIG", "ZITADEL_PROJECT_ID is required for Zitadel runtime.");
-	if (t === "production" && !e.issuer) throw new c("E_ZITADEL_CONFIG", "ZITADEL_ISSUER is required in production.");
-	return {
-		projectId: e.projectId,
-		environment: t,
-		issuer: e.issuer
-	};
+export 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 d(e) {
-	if (!e || e === "development") return "development";
-	if (e === "preview" || e === "production") return e;
-	throw new c("E_ZITADEL_CONFIG", `Unsupported ZITADEL_ENVIRONMENT "${e}".`);
+export 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 f() {
-	return globalThis.process?.env ?? {};
+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() {
+    const scope = globalThis;
+    return scope.process?.env ?? {};
 }
-//#endregion
-export { e as HOP_BY_HOP, t as INTERNAL_HEADERS, i as JWKS_TTL_MS, c as ZitadelRuntimeError, a as base64UrlDecode, o as decodeJwt, n as filterResponseHeaders, r as matchesRoutes, u as resolveZitadelRuntime, l as resolveZitadelRuntimeEnv, s as verifyJwt };

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;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

@@ -1,111 +1,385 @@
-//#region src/jwt.ts
-var e = 300 * 1e3, t = /* @__PURE__ */ new Map(), n = new TextDecoder(), r = new TextEncoder();
-function i(e) {
-	let t = e.replace(/-/g, "+").replace(/_/g, "/"), n = t.padEnd(t.length + (4 - t.length % 4) % 4, "="), r = atob(n);
-	return Uint8Array.from(r, (e) => e.charCodeAt(0));
+/**
+ * @file lib/jwt.ts
+ *
+ * # JWT Verification
+ *
+ * Stateless JWT verification via JWKS, with in-process key caching.
+ *
+ * ## Anatomy of a JWT
+ *
+ * A compact JWT (JWS compact serialisation) is three Base64URL-encoded parts
+ * joined by dots:
+ *
+ * ```
+ * <header>.<payload>.<signature>
+ * ```
+ *
+ * - **Header** — metadata about the token: signing algorithm, key ID, token type.
+ * - **Payload** — the claims: user identity, expiry, issuer, audience, etc.
+ * - **Signature** — `SIGN(privateKey, "<header>.<payload>")`. Any party with the
+ *   matching public key can verify it without contacting the auth server.
+ *
+ * A valid signature proves two things:
+ *
+ * 1. **Authenticity** — the token was produced by the holder of the private key.
+ * 2. **Integrity** — neither the header nor the payload has been altered since signing.
+ *
+ * Signature verification alone is not sufficient. The claims inside the payload
+ * must also be checked (expiry, issuer, audience, …). Both steps are performed
+ * by {@link verifyJwt}.
+ *
+ * ---
+ *
+ * ## JWT Header fields
+ *
+ * The header is a JSON object Base64URL-encoded into the first segment.
+ *
+ * | Field | Purpose | Verified |
+ * |-------|---------|---------|
+ * | `alg` | Signing algorithm (`RS256`, `ES256`, …) | Checked against {@link VerifyJwtOptions.allowedAlgorithms} before JWKS is fetched |
+ * | `kid` | Key ID — selects the matching public key from the JWKS | Used for key lookup; falls back to the first JWKS key when absent |
+ * | `typ` | Token type (`JWT`, `at+JWT`, …) | Checked against {@link VerifyJwtOptions.allowedTokenTypes} (case-insensitive) |
+ * | ~~`enc`~~ | ~~Encryption algorithm — present in JWE (encrypted) tokens only~~ | ~~Not applicable — we verify JWS (signed) tokens, not JWE (encrypted)~~ |
+ * | ~~`cty`~~ | ~~Content type — describes the secured content media type~~ | ~~Not applicable — not set by standard OIDC/OAuth auth servers~~ |
+ *
+ * ---
+ *
+ * ## JWT Payload claims
+ *
+ * The payload is a JSON object Base64URL-encoded into the second segment.
+ *
+ * ### Validated claims
+ *
+ * | Claim | Purpose | How |
+ * |-------|---------|-----|
+ * | `iss` | Issuer — the URL of the auth server that issued the token | Must be present and must equal {@link VerifyJwtOptions.issuerUrl} |
+ * | `exp` | Expiration time — Unix timestamp after which the token is invalid | Must be present and in the future, allowing {@link VerifyJwtOptions.clockSkewMs} tolerance |
+ * | `nbf` | Not before — Unix timestamp before which the token must not be accepted | Must be in the past, allowing {@link VerifyJwtOptions.clockSkewMs} tolerance |
+ * | `iat` | Issued at — Unix timestamp when the token was created | Must not be in the future beyond {@link VerifyJwtOptions.clockSkewMs} |
+ * | `aud` | Audience — the intended recipient(s) of the token | Checked against {@link VerifyJwtOptions.audience} when that option is provided |
+ *
+ * ### Read-only claims (extracted into the session, not further validated)
+ *
+ * | Claim | Purpose |
+ * |-------|---------|
+ * | `sub` | Subject — the user's unique identifier |
+ * | `email` | User's email address |
+ * | `name` | User's display name |
+ *
+ * ### Not validated
+ *
+ * | Claim | Purpose | Why skipped |
+ * |-------|---------|-------------|
+ * | ~~`jti`~~ | ~~JWT ID — a unique identifier for this specific token instance~~ | ~~Revocation requires a server-side blocklist; not feasible in stateless edge middleware~~ |
+ * | ~~`azp`~~ | ~~Authorized party — the OAuth 2.0 client that requested the token~~ | ~~The proxy architecture means the browser never contacts the auth server directly, making cross-origin token replay a non-threat~~ |
+ * | ~~`nonce`~~ | ~~OIDC nonce — binds a token to a specific authorisation request~~ | ~~Not applicable in our password/cookie flow (no OIDC redirect round-trip)~~ |
+ * | ~~`acr`~~ | ~~Authentication class reference — describes the strength of the authentication~~ | ~~Not validated (future: require MFA for sensitive routes)~~ |
+ * | ~~`amr`~~ | ~~Authentication methods reference — list of methods used to authenticate~~ | ~~Not validated~~ |
+ * | ~~`scope`~~ | ~~OAuth 2.0 scopes granted to the token~~ | ~~Not validated (future: per-route scope enforcement)~~ |
+ *
+ * ---
+ *
+ * ## 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).
+ *
+ * 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`.
+ *
+ * > **Note (serverless):** the cache is module-level. In serverless environments
+ * > each cold start gets a fresh cache; warm instances share it across requests.
+ *
+ * ---
+ *
+ * ## Runtime note
+ *
+ * This file is the **shared implementation** used by both `sdk-next` (Edge
+ * runtime) and `sdk-nuxt` (Node.js/Nitro). `base64UrlDecode` uses `atob`,
+ * which is available in both environments (Edge natively; Node.js since v16).
+ * The previous per-SDK copies (one using `atob`, one using `Buffer`) have
+ * been consolidated here.
+ */
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** How long a cached JWKS key is considered fresh before re-fetching. */
+export const JWKS_TTL_MS = 5 * 60 * 1_000;
+// ─── JWKS cache ───────────────────────────────────────────────────────────────
+/**
+ * In-memory JWKS key cache.
+ *
+ * Keys are of the form `"${jwksUri}:${kid}"`, or `"${jwksUri}:__default__"`
+ * when the JWT carries no `kid`. Including the full JWKS URI prevents a cached
+ * key from one issuer being returned for a request targeting a different issuer
+ * that happens to share the same `kid` string — a scenario that can arise in
+ * multi-tenant deployments or during key-rotation incidents.
+ *
+ * Cache entries are immutable once written; the cache itself grows up to one
+ * entry per distinct `(jwksUri, kid)` pair seen in the lifetime of the process.
+ *
+ * The cache is intentionally unbounded. In practice the number of distinct
+ * (jwksUri, kid) pairs is bounded by the number of key rotations during the
+ * process lifetime — typically a handful. A bounded LRU eviction policy could
+ * be added if memory growth becomes a concern for very long-lived processes
+ * with frequent key rotations, but is omitted here to keep the implementation
+ * dependency-free.
+ */
+const jwksCache = new Map();
+const DECODER = new TextDecoder();
+const ENCODER = new TextEncoder();
+// ─── Base64URL ────────────────────────────────────────────────────────────────
+/**
+ * Decodes a Base64URL-encoded string into a `Uint8Array`.
+ *
+ * The Edge runtime has no `Buffer`, so this uses `atob` after translating the
+ * Base64URL alphabet (`-` → `+`, `_` → `/`) and padding to a multiple of four.
+ *
+ * @param input - A Base64URL-encoded string (padding is optional).
+ * @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 binary = atob(padded);
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
 }
-function a(e) {
-	let [t, n, r] = e.split(".");
-	return !t || !n || !r ? null : [
-		t,
-		n,
-		r
-	];
+// ─── JWT splitting ────────────────────────────────────────────────────────────
+/**
+ * Splits a compact JWT string into its three raw Base64URL segments without
+ * decoding or verifying any of them.
+ *
+ * Tokens with more than three segments (e.g. nested JWTs) are accepted; only
+ * the first three parts are returned. Tokens with fewer than three segments are
+ * structurally invalid compact JWTs and cannot be verified.
+ *
+ * @param token - The compact JWT string.
+ * @returns A `[header, payload, signature]` tuple, or `null` when the token
+ *   has fewer than three dot-separated segments.
+ */
+function splitToken(token) {
+    const [h, p, s] = token.split(".");
+    if (!h || !p || !s) {
+        return null;
+    }
+    return [h, p, s];
 }
-function o(e) {
-	let t = a(e);
-	if (!t) throw TypeError(`Invalid JWT: expected at least three dot-separated segments, received ${e.split(".").length}.`);
-	let [r, o] = t;
-	return {
-		header: JSON.parse(n.decode(i(r))),
-		payload: JSON.parse(n.decode(i(o)))
-	};
+// ─── JWT decode ───────────────────────────────────────────────────────────────
+/**
+ * Decodes a compact-serialised JWT into its header and payload **without**
+ * verifying the signature.
+ *
+ * **Do not trust the result of this function alone.** Use it only as the first
+ * step of a full verification pipeline — the signature check in {@link verifyJwt}
+ * must follow before any claim can be trusted.
+ *
+ * @param token - A compact JWT string (`header.payload.signature`).
+ * @returns The decoded {@link DecodedJwt}.
+ * @throws {TypeError} When `token` has fewer than three dot-separated segments.
+ */
+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}.`);
+    }
+    const [h, p] = segments;
+    return {
+        header: JSON.parse(DECODER.decode(base64UrlDecode(h))),
+        payload: JSON.parse(DECODER.decode(base64UrlDecode(p))),
+    };
 }
-var s = {
-	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"
-	}
-}, c = {
-	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"
-	}
+// ─── Algorithm helpers ────────────────────────────────────────────────────────
+/**
+ * Web Crypto parameters for importing a public key from JWKS, keyed by JWT
+ * `alg` header value. The keys of this object are the only supported algorithms;
+ * 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" },
 };
-function l(e) {
-	if (!Object.hasOwn(s, e)) throw TypeError(`Unsupported JWT algorithm: "${e}". Supported algorithms are ${Object.keys(s).join(", ")}.`);
+/**
+ * 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" },
+};
+function assertSupportedAlgorithm(alg) {
+    if (!Object.hasOwn(IMPORT_PARAMS, alg)) {
+        throw new TypeError(`Unsupported JWT algorithm: "${alg}". Supported algorithms are ${Object.keys(IMPORT_PARAMS).join(", ")}.`);
+    }
 }
-function u(e) {
-	return l(e), s[e];
+function resolveImportAlgorithm(alg) {
+    assertSupportedAlgorithm(alg);
+    return IMPORT_PARAMS[alg];
 }
-function d(e) {
-	return l(e), c[e];
+function resolveVerifyAlgorithm(alg) {
+    assertSupportedAlgorithm(alg);
+    return VERIFY_PARAMS[alg];
 }
-async function f(e, n, r) {
-	let i = `${e}:${n ?? "__default__"}`, a = t.get(i);
-	if (a && Date.now() - a.fetchedAt < 3e5) return a.key;
-	let o = await fetch(e, { signal: AbortSignal.timeout(r) });
-	if (!o.ok) return null;
-	let s = await o.json(), c = n ? s.keys.find((e) => e.kid === n) : s.keys[0];
-	if (!c) return null;
-	let l = c.alg ?? "RS256", d = await crypto.subtle.importKey("jwk", c, u(l), !1, ["verify"]);
-	return t.set(i, {
-		key: d,
-		fetchedAt: Date.now()
-	}), d;
+// ─── JWKS fetch ───────────────────────────────────────────────────────────────
+/**
+ * Fetches the JWKS from `jwksUri`, imports the key matching `kid`, and caches
+ * it for {@link JWKS_TTL_MS} milliseconds.
+ *
+ * The cache key is `"${jwksUri}:${kid ?? '__default__'}"`. Scoping the key to
+ * the full endpoint URL ensures that two issuers that happen to publish keys
+ * under the same `kid` string are never confused with one another.
+ *
+ * Behaviour:
+ * - When the cached entry for the `(jwksUri, kid)` pair is still within TTL,
+ *   it is returned immediately with no network request.
+ * - When `kid` is absent, the first key in the JWKS is used and cached under
+ *   the `"__default__"` sentinel combined with the endpoint URI.
+ * - Returns `null` when the JWKS endpoint returns a non-OK status, no matching
+ *   key is found, or key import fails.
+ *
+ * @param jwksUri - Full URL of the JWKS endpoint.
+ * @param kid     - The `kid` header value from the JWT, or `undefined`.
+ */
+async function fetchAndCacheJwks(jwksUri, kid, timeoutMs) {
+    const cacheKey = `${jwksUri}:${kid ?? "__default__"}`;
+    const cached = jwksCache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < JWKS_TTL_MS) {
+        return cached.key;
+    }
+    const res = await fetch(jwksUri, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) {
+        return null;
+    }
+    const json = (await res.json());
+    const jwk = kid ? json.keys.find((k) => k.kid === kid) : json.keys[0];
+    if (!jwk) {
+        return null;
+    }
+    // RFC 7517 §4.4 makes 'alg' optional in a JWK — the key material (kty, n/e
+    // 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",
+    ]);
+    jwksCache.set(cacheKey, { key: cryptoKey, fetchedAt: Date.now() });
+    return cryptoKey;
 }
-async function p(e, t) {
-	try {
-		let { issuerUrl: o, allowedAlgorithms: s, clockSkewMs: c, audience: l, allowedTokenTypes: u, jwksTimeoutMs: p = 5e3 } = t, m = a(e);
-		if (!m) return null;
-		let [h, g, _] = m, v = JSON.parse(n.decode(i(h))), y = JSON.parse(n.decode(i(g))), b = v.alg;
-		if (!b || b.toLowerCase() === "none" || s?.length && !s.includes(b)) return null;
-		if (u.length > 0) {
-			let e = v.typ ?? "";
-			if (!u.some((t) => t.toLowerCase() === e.toLowerCase())) return null;
-		}
-		let x = v.kid, S = await f(`${o}/auth/keys`, x, p);
-		if (!S || !await crypto.subtle.verify(d(b), S, i(_), r.encode(`${h}.${g}`)) || y.iss !== o) return null;
-		if (l !== void 0) {
-			let e = y.aud === void 0 ? [] : [y.aud].flat();
-			if (![l].flat().some((t) => e.includes(t))) return null;
-		}
-		let C = Date.now();
-		return y.exp === void 0 || y.exp * 1e3 < C - c || y.nbf !== void 0 && y.nbf * 1e3 > C + c || y.iat !== void 0 && y.iat * 1e3 > C + c ? null : y;
-	} catch (e) {
-		return e instanceof SyntaxError || console.error("[nextgen] verifyJwt unexpected error:", e), null;
-	}
+// ─── Verification ─────────────────────────────────────────────────────────────
+/**
+ * Verifies a compact-serialised JWT and returns its validated payload.
+ *
+ * ## Verification steps (in order)
+ *
+ * 1. Split the token — returns `null` immediately when fewer than three
+ *    dot-separated segments are present.
+ * 2. Reject if `alg` is not in {@link VerifyJwtOptions.allowedAlgorithms} (when set).
+ * 3. Reject if `typ` is not in {@link VerifyJwtOptions.allowedTokenTypes} (when non-empty).
+ * 4. Fetch (or retrieve from cache) the matching public key from the JWKS endpoint.
+ * 5. Verify the cryptographic signature over `header.payload`.
+ * 6. Reject if `iss` is absent or does not equal {@link VerifyJwtOptions.issuerUrl}.
+ * 7. Reject if {@link VerifyJwtOptions.audience} is set and `aud` does not contain it.
+ * 8. Reject if `exp` is absent or is in the past (minus clock-skew tolerance).
+ * 9. Reject if `nbf` is in the future (plus clock-skew tolerance).
+ * 10. Reject if `iat` is in the future (plus clock-skew tolerance).
+ *
+ * Returns `null` on any failure rather than throwing, so callers can treat a
+ * bad token identically to a missing one without try/catch at the call site.
+ *
+ * @param token - The raw compact-serialised JWT string.
+ * @param opts  - Verification options; see {@link VerifyJwtOptions}.
+ * @returns The verified {@link JwtPayload}, or `null` if verification fails.
+ */
+export async function verifyJwt(token, opts) {
+    try {
+        const { issuerUrl, allowedAlgorithms, clockSkewMs, audience, allowedTokenTypes, jwksTimeoutMs = 5000, } = opts;
+        const segments = splitToken(token);
+        if (!segments) {
+            return null;
+        }
+        const [rawHeader, rawPayload, rawSig] = segments;
+        const header = JSON.parse(DECODER.decode(base64UrlDecode(rawHeader)));
+        const payload = JSON.parse(DECODER.decode(base64UrlDecode(rawPayload)));
+        // RFC 7515 §4.1.1 requires 'alg' in the JWT header. A token that omits it
+        // is structurally invalid — we reject it rather than guessing an algorithm.
+        const alg = header.alg;
+        if (!alg) {
+            return null;
+        }
+        // Unconditionally reject the 'none' algorithm regardless of the allowlist.
+        // '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") {
+            return null;
+        }
+        if (allowedAlgorithms?.length && !allowedAlgorithms.includes(alg)) {
+            return null;
+        }
+        if (allowedTokenTypes.length > 0) {
+            const typ = header.typ ?? "";
+            if (!allowedTokenTypes.some((t) => t.toLowerCase() === typ.toLowerCase())) {
+                return null;
+            }
+        }
+        const kid = header.kid;
+        const cryptoKey = await fetchAndCacheJwks(`${issuerUrl}/auth/keys`, kid, jwksTimeoutMs);
+        if (!cryptoKey) {
+            return null;
+        }
+        const valid = await crypto.subtle.verify(resolveVerifyAlgorithm(alg), cryptoKey, base64UrlDecode(rawSig), ENCODER.encode(`${rawHeader}.${rawPayload}`));
+        if (!valid) {
+            return null;
+        }
+        // Strict equality is intentional: the issuer URL must match exactly as
+        // configured. We deliberately do not normalise trailing slashes, case, or
+        // surrounding whitespace — any difference is either a misconfiguration or
+        // a token issued by a different server and must be rejected.
+        if (payload.iss !== issuerUrl) {
+            return null;
+        }
+        if (audience !== undefined) {
+            const audList = payload.aud !== undefined ? [payload.aud].flat() : [];
+            const expectedList = [audience].flat();
+            if (!expectedList.some((a) => audList.includes(a))) {
+                return null;
+            }
+        }
+        const now = Date.now();
+        if (payload.exp === undefined || payload.exp * 1000 < now - clockSkewMs) {
+            return null;
+        }
+        if (payload.nbf !== undefined && payload.nbf * 1000 > now + clockSkewMs) {
+            return null;
+        }
+        if (payload.iat !== undefined && payload.iat * 1000 > now + clockSkewMs) {
+            return null;
+        }
+        return payload;
+    }
+    catch (err) {
+        // SyntaxError from JSON.parse means the token segments are not JSON —
+        // this is an opaque (non-JWT) token. Return null silently; the middleware
+        // will fall back to opaque token validation via the backend.
+        if (err instanceof SyntaxError) {
+            return null;
+        }
+        // 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);
+        return null;
+    }
 }
-//#endregion
-export { e as JWKS_TTL_MS, i as base64UrlDecode, o as decodeJwt, p as verifyJwt };