@web-ts-toolkit/express-oidc-vault 0.28.0

package/index.mjs

@@ -0,0 +1,954 @@
+// src/index.ts
+import { createHash, randomBytes } from "crypto";
+import express from "express";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+// src/config.ts
+var DEFAULT_OIDC_SCOPES = "openid email profile";
+var MANUAL_CONFIG_REQUIREMENTS = ["authorizationEndpoint", "tokenEndpoint", "jwksUri"];
+var normalizeOptionalString = (value) => {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+};
+var withOptionalValue = (target, key, value) => {
+  if (value !== void 0) {
+    target[key] = value;
+  }
+};
+function resolveOidcVaultConfig(config = {}) {
+  const issuer = normalizeOptionalString(config.issuer);
+  const clientId = normalizeOptionalString(config.clientId);
+  const clientSecret = normalizeOptionalString(config.clientSecret);
+  const scopes = normalizeOptionalString(config.scopes) ?? DEFAULT_OIDC_SCOPES;
+  if (!clientId) {
+    throw new Error("OIDC clientId is required.");
+  }
+  if (issuer) {
+    const resolved2 = {
+      mode: "issuer",
+      issuer,
+      scopes
+    };
+    withOptionalValue(resolved2, "clientId", clientId);
+    withOptionalValue(resolved2, "clientSecret", clientSecret);
+    return resolved2;
+  }
+  const resolved = {
+    mode: "manual",
+    scopes
+  };
+  withOptionalValue(resolved, "authorizationEndpoint", normalizeOptionalString(config.authorizationEndpoint));
+  withOptionalValue(resolved, "tokenEndpoint", normalizeOptionalString(config.tokenEndpoint));
+  withOptionalValue(resolved, "userInfoEndpoint", normalizeOptionalString(config.userInfoEndpoint));
+  withOptionalValue(resolved, "jwksUri", normalizeOptionalString(config.jwksUri));
+  withOptionalValue(resolved, "endSessionEndpoint", normalizeOptionalString(config.endSessionEndpoint));
+  withOptionalValue(resolved, "clientId", clientId);
+  withOptionalValue(resolved, "clientSecret", clientSecret);
+  const missing = MANUAL_CONFIG_REQUIREMENTS.filter((key) => !resolved[key]);
+  if (missing.length > 0) {
+    throw new Error(`Missing required OIDC configuration for manual mode: ${missing.join(", ")}`);
+  }
+  return resolved;
+}
+function resolveOidcVaultConfigFromEnv(env = process.env) {
+  return resolveOidcVaultConfig({
+    issuer: env.OIDC_ISSUER,
+    authorizationEndpoint: env.OIDC_AUTHORIZATION_ENDPOINT,
+    tokenEndpoint: env.OIDC_TOKEN_ENDPOINT,
+    userInfoEndpoint: env.OIDC_USERINFO_ENDPOINT,
+    jwksUri: env.OIDC_JWKS_URI,
+    endSessionEndpoint: env.OIDC_END_SESSION_ENDPOINT,
+    clientId: env.OIDC_CLIENT_ID,
+    clientSecret: env.OIDC_CLIENT_SECRET,
+    scopes: env.OIDC_SCOPES
+  });
+}
+
+// src/types.ts
+var OidcVaultStoreConflictError = class extends Error {
+  constructor(message = "OIDC vault store operation conflicted with concurrent state changes.") {
+    super(message);
+    this.name = "OidcVaultStoreConflictError";
+  }
+};
+
+// src/index.ts
+var DEFAULT_OIDC_VAULT_BASE_PATH = "/auth/oidc";
+var DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS = 10 * 60 * 1e3;
+var DEFAULT_EXCHANGE_CODE_TTL_MS = 30 * 1e3;
+var DEFAULT_SESSION_COOKIE_NAME = "oidc_vault_session";
+var OIDC_VAULT_ROUTE_PATHS = {
+  login: "/login",
+  callback: "/callback",
+  exchange: "/exchange",
+  refresh: "/refresh",
+  logout: "/logout",
+  "backchannel-logout": "/backchannel-logout"
+};
+var discoveryCache = /* @__PURE__ */ new Map();
+var jwksCache = /* @__PURE__ */ new Map();
+var OidcVaultHttpError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+};
+function normalizeOidcVaultBasePath(value) {
+  if (!value || value === "/") {
+    return DEFAULT_OIDC_VAULT_BASE_PATH;
+  }
+  return `/${value.replace(/^\/+|\/+$/g, "")}`;
+}
+var isRecord = (value) => typeof value === "object" && value !== null;
+var isString = (value) => typeof value === "string" && value.length > 0;
+var getNow = (options) => (options.now ?? Date.now)();
+var getSessionTransport = (options) => options.sessionTransport ?? "body";
+var usesCookieTransport = (options) => getSessionTransport(options) === "cookie";
+var createOpaqueId = (prefix) => `${prefix}_${randomBytes(16).toString("base64url")}`;
+var createPkceVerifier = () => randomBytes(32).toString("base64url");
+var createPkceChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
+var toErrorPayload = (error) => {
+  if (error instanceof OidcVaultHttpError) {
+    return {
+      status: error.status,
+      code: error.code,
+      message: error.message
+    };
+  }
+  return {
+    status: 500,
+    code: "OIDC_VAULT_INTERNAL_ERROR",
+    message: error instanceof Error ? error.message : "Unexpected OIDC vault error."
+  };
+};
+var getRequestOrigin = (req) => `${req.protocol}://${req.get("host") ?? "localhost"}`;
+var getCallbackUri = (req, basePath) => `${getRequestOrigin(req)}${basePath}${OIDC_VAULT_ROUTE_PATHS.callback}`;
+var getRequiredString = (value, message, code, status = 400) => {
+  if (!isString(value)) {
+    throw new OidcVaultHttpError(status, code, message);
+  }
+  return value;
+};
+var parseCookieHeader = (headerValue) => {
+  if (!headerValue) {
+    return {};
+  }
+  return headerValue.split(";").reduce((cookies, part) => {
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex === -1) {
+      return cookies;
+    }
+    const name = part.slice(0, separatorIndex).trim();
+    const value = part.slice(separatorIndex + 1).trim();
+    if (!name) {
+      return cookies;
+    }
+    cookies[name] = decodeURIComponent(value);
+    return cookies;
+  }, {});
+};
+var resolveCookieOptions = (options) => {
+  const cookieOptions = options.cookie ?? {};
+  const deploymentMode = cookieOptions.deploymentMode ?? "same-origin";
+  const sameSite = cookieOptions.sameSite ?? (deploymentMode === "cross-site" ? "none" : "lax");
+  const secure = cookieOptions.secure ?? (sameSite === "none" || deploymentMode === "cross-site");
+  return {
+    name: cookieOptions.name ?? DEFAULT_SESSION_COOKIE_NAME,
+    sameSite,
+    secure,
+    domain: cookieOptions.domain,
+    path: cookieOptions.path ?? "/",
+    httpOnly: cookieOptions.httpOnly ?? true
+  };
+};
+var usesCrossSiteCookieTransport = (options) => usesCookieTransport(options) && resolveCookieOptions(options).sameSite === "none";
+var resolveTrustedOrigins = (options) => new Set((options.trustedOrigins ?? []).map((value) => new URL(value).origin));
+var getRequestSourceOrigin = (req) => {
+  const origin = req.get("origin");
+  if (isString(origin)) {
+    return origin;
+  }
+  const referer = req.get("referer");
+  if (!isString(referer)) {
+    return void 0;
+  }
+  try {
+    return new URL(referer).origin;
+  } catch {
+    return void 0;
+  }
+};
+var assertTrustedOrigin = (req, options, trustedOrigins, action) => {
+  if (!usesCrossSiteCookieTransport(options)) {
+    return;
+  }
+  const origin = getRequestSourceOrigin(req);
+  if (!origin || !trustedOrigins.has(origin)) {
+    throw new OidcVaultHttpError(
+      403,
+      "OIDC_VAULT_UNTRUSTED_ORIGIN",
+      `${action === "refresh" ? "Refresh" : "Logout"} request origin is not trusted.`
+    );
+  }
+};
+var validateOidcVaultOptions = (options) => {
+  const config = resolveOidcVaultConfig(options.config);
+  const trustedOrigins = resolveTrustedOrigins(options);
+  if (usesCrossSiteCookieTransport(options) && trustedOrigins.size === 0) {
+    throw new Error("trustedOrigins is required when using cross-site cookie transport.");
+  }
+  return { config, trustedOrigins };
+};
+var serializeCookie = (name, value, options, overrides) => {
+  const sameSite = options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1);
+  const parts = [`${name}=${encodeURIComponent(value)}`, `Path=${options.path}`, `SameSite=${sameSite}`];
+  if (options.httpOnly) {
+    parts.push("HttpOnly");
+  }
+  if (options.secure || options.sameSite === "none") {
+    parts.push("Secure");
+  }
+  if (options.domain) {
+    parts.push(`Domain=${options.domain}`);
+  }
+  if (typeof overrides?.maxAge === "number") {
+    parts.push(`Max-Age=${overrides.maxAge}`);
+  }
+  if (overrides?.expires) {
+    parts.push(`Expires=${overrides.expires.toUTCString()}`);
+  }
+  return parts.join("; ");
+};
+var setSessionCookie = (res, options, sessionId) => {
+  const cookieOptions = resolveCookieOptions(options);
+  res.append("Set-Cookie", serializeCookie(cookieOptions.name, sessionId, cookieOptions));
+};
+var clearSessionCookie = (res, options) => {
+  const cookieOptions = resolveCookieOptions(options);
+  res.append(
+    "Set-Cookie",
+    serializeCookie(cookieOptions.name, "", cookieOptions, {
+      maxAge: 0,
+      expires: /* @__PURE__ */ new Date(0)
+    })
+  );
+};
+var getSessionIdFromCookie = (req, options) => {
+  const cookies = parseCookieHeader(req.headers.cookie);
+  return cookies[resolveCookieOptions(options).name];
+};
+var getSessionIdFromRequest = (req, options, action) => {
+  const body = getBody(req);
+  if (usesCookieTransport(options)) {
+    const cookieSessionId = getSessionIdFromCookie(req, options);
+    if (isString(cookieSessionId)) {
+      return cookieSessionId;
+    }
+    if (isString(body.sessionId)) {
+      return body.sessionId;
+    }
+    throw new OidcVaultHttpError(
+      400,
+      "OIDC_VAULT_MISSING_SESSION_ID",
+      `${action === "refresh" ? "Refresh" : "Logout"} request is missing the session cookie.`
+    );
+  }
+  return getRequiredString(
+    body.sessionId,
+    `${action === "refresh" ? "Refresh" : "Logout"} request is missing sessionId.`,
+    "OIDC_VAULT_MISSING_SESSION_ID"
+  );
+};
+var createExchangeResponse = (options, session, issuedToken) => ({
+  sessionId: usesCookieTransport(options) ? void 0 : session.sessionId,
+  user: session.user,
+  ...issuedToken
+});
+var extractBearerToken = (authorizationHeader) => {
+  if (!authorizationHeader) {
+    throw new OidcVaultHttpError(401, "OIDC_VAULT_MISSING_BEARER_TOKEN", "Missing bearer token.");
+  }
+  const [scheme, token, extra] = authorizationHeader.trim().split(/\s+/);
+  if (scheme?.toLowerCase() !== "bearer" || !token || extra) {
+    throw new OidcVaultHttpError(
+      401,
+      "OIDC_VAULT_INVALID_AUTHORIZATION_HEADER",
+      "Authorization header must use the Bearer scheme."
+    );
+  }
+  return token;
+};
+var setBearerChallengeHeader = (res) => {
+  res.setHeader("WWW-Authenticate", "Bearer");
+};
+var BACKCHANNEL_LOGOUT_EVENT_CLAIM = "http://schemas.openid.net/event/backchannel-logout";
+var defaultJwtClaimsMapper = (claims) => {
+  const subject = getRequiredString(
+    claims.sub,
+    "JWT access token is missing sub.",
+    "OIDC_VAULT_INVALID_ACCESS_TOKEN",
+    401
+  );
+  return {
+    subject,
+    sessionId: typeof claims.sid === "string" ? claims.sid : void 0,
+    scope: typeof claims.scope === "string" ? claims.scope : void 0,
+    claims
+  };
+};
+var buildWellKnownUrl = (issuer) => {
+  const normalizedIssuer = issuer.endsWith("/") ? issuer : `${issuer}/`;
+  return new URL(".well-known/openid-configuration", normalizedIssuer);
+};
+var resolveJwks = (jwksUri) => {
+  let jwks = jwksCache.get(jwksUri);
+  if (!jwks) {
+    jwks = createRemoteJWKSet(new URL(jwksUri));
+    jwksCache.set(jwksUri, jwks);
+  }
+  return jwks;
+};
+var appendQueryParam = (url, name, value) => {
+  if (value) {
+    url.searchParams.set(name, value);
+  }
+};
+var buildAuthorizationUrl = (metadata, transaction, redirectUri) => {
+  const url = new URL(metadata.authorizationEndpoint);
+  appendQueryParam(url, "response_type", "code");
+  appendQueryParam(url, "client_id", metadata.clientId);
+  appendQueryParam(url, "redirect_uri", redirectUri);
+  appendQueryParam(url, "scope", metadata.scopes);
+  appendQueryParam(url, "state", transaction.state);
+  appendQueryParam(url, "nonce", transaction.nonce);
+  appendQueryParam(url, "code_challenge", transaction.codeChallenge);
+  appendQueryParam(url, "code_challenge_method", "S256");
+  return url.toString();
+};
+var buildLogoutUrl = (endSessionEndpoint, idTokenHint, postLogoutRedirectUri) => {
+  const url = new URL(endSessionEndpoint);
+  appendQueryParam(url, "id_token_hint", idTokenHint);
+  appendQueryParam(url, "post_logout_redirect_uri", postLogoutRedirectUri);
+  return url.toString();
+};
+var toBasicAuthorization = (clientId, clientSecret) => `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`;
+var readJsonResponse = async (response, errorCode) => {
+  const text = await response.text();
+  if (!text) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new OidcVaultHttpError(response.status, errorCode, text);
+  }
+};
+var getLogoutTokenFromRequest = (req) => {
+  const body = getBody(req);
+  return getRequiredString(
+    body.logout_token,
+    "Backchannel logout request is missing logout_token.",
+    "OIDC_VAULT_MISSING_LOGOUT_TOKEN"
+  );
+};
+var createHookContext = (route, req, res, session, metadata) => ({ route, req, res, session, metadata });
+var mergeUserProfile = (sub, idTokenClaims, userInfo) => ({
+  ...idTokenClaims,
+  ...userInfo ?? {},
+  sub
+});
+var resolveReturnTo = (req, options) => {
+  const rawReturnTo = req.query.returnTo;
+  if (!isString(rawReturnTo)) {
+    return void 0;
+  }
+  const configuredFrontendUri = options.frontendRedirectUri;
+  if (!configuredFrontendUri) {
+    throw new OidcVaultHttpError(
+      400,
+      "OIDC_VAULT_INVALID_RETURN_TO",
+      "Custom returnTo requires a configured frontendRedirectUri."
+    );
+  }
+  const configuredUrl = new URL(configuredFrontendUri);
+  const resolvedUrl = rawReturnTo.startsWith("/") ? new URL(rawReturnTo, configuredUrl) : new URL(rawReturnTo);
+  if (resolvedUrl.origin !== configuredUrl.origin) {
+    throw new OidcVaultHttpError(
+      400,
+      "OIDC_VAULT_INVALID_RETURN_TO",
+      "returnTo must stay on the configured frontend origin."
+    );
+  }
+  return resolvedUrl.toString();
+};
+var appendCodeToRedirectUri = (redirectUri, code) => {
+  const url = new URL(redirectUri);
+  url.searchParams.set("code", code);
+  return url.toString();
+};
+var getBody = (req) => isRecord(req.body) ? req.body : {};
+var withIssuedToken = async (req, res, options, session) => {
+  if (!options.tokenIssuer) {
+    return {};
+  }
+  return options.tokenIssuer.issue({ req, res, session });
+};
+var resolveFrontendRedirectUri = (transaction, options) => {
+  const redirectUri = transaction.returnTo ?? options.frontendRedirectUri;
+  if (!redirectUri) {
+    throw new OidcVaultHttpError(
+      500,
+      "OIDC_VAULT_MISSING_FRONTEND_REDIRECT_URI",
+      "A frontendRedirectUri or login returnTo is required to complete the callback flow."
+    );
+  }
+  return redirectUri;
+};
+var shouldFetchUserInfo = (options, metadata) => options.fetchUserInfo !== false && Boolean(metadata.userInfoEndpoint);
+async function callHook(route, hook, req, res, session, metadata) {
+  if (!hook) {
+    return;
+  }
+  await hook(createHookContext(route, req, res, session, metadata));
+}
+async function handleRouteError(route, req, res, next, options, error) {
+  try {
+    await options.hooks?.onError?.({
+      ...createHookContext(route, req, res),
+      error
+    });
+  } catch {
+  }
+  if (res.headersSent) {
+    next(error);
+    return;
+  }
+  const payload = toErrorPayload(error);
+  res.status(payload.status).json({
+    code: payload.code,
+    message: payload.message
+  });
+}
+function createAsyncHandler(route, options, handler) {
+  return async (req, res, next) => {
+    try {
+      await handler(req, res, next);
+    } catch (error) {
+      await handleRouteError(route, req, res, next, options, error);
+    }
+  };
+}
+async function discoverIssuerMetadata(issuer) {
+  let discoveryPromise = discoveryCache.get(issuer);
+  if (!discoveryPromise) {
+    discoveryPromise = (async () => {
+      const discoveryUrl = buildWellKnownUrl(issuer);
+      const response = await fetch(discoveryUrl);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new OidcVaultHttpError(
+          502,
+          "OIDC_VAULT_DISCOVERY_FAILED",
+          errorText || `OIDC discovery failed with status ${response.status}.`
+        );
+      }
+      const discovered = await response.json();
+      const authorizationEndpoint = getRequiredString(
+        discovered.authorization_endpoint,
+        "OIDC discovery response is missing authorization_endpoint.",
+        "OIDC_VAULT_DISCOVERY_INVALID",
+        502
+      );
+      const tokenEndpoint = getRequiredString(
+        discovered.token_endpoint,
+        "OIDC discovery response is missing token_endpoint.",
+        "OIDC_VAULT_DISCOVERY_INVALID",
+        502
+      );
+      const jwksUri = getRequiredString(
+        discovered.jwks_uri,
+        "OIDC discovery response is missing jwks_uri.",
+        "OIDC_VAULT_DISCOVERY_INVALID",
+        502
+      );
+      return {
+        issuer: getRequiredString(
+          discovered.issuer,
+          "OIDC discovery response is missing issuer.",
+          "OIDC_VAULT_DISCOVERY_INVALID",
+          502
+        ),
+        authorizationEndpoint,
+        tokenEndpoint,
+        jwksUri,
+        userInfoEndpoint: typeof discovered.userinfo_endpoint === "string" ? discovered.userinfo_endpoint : void 0,
+        endSessionEndpoint: typeof discovered.end_session_endpoint === "string" ? discovered.end_session_endpoint : void 0
+      };
+    })();
+    discoveryCache.set(issuer, discoveryPromise);
+    discoveryPromise.catch(() => {
+      if (discoveryCache.get(issuer) === discoveryPromise) {
+        discoveryCache.delete(issuer);
+      }
+    });
+  }
+  return discoveryPromise;
+}
+async function resolveProviderMetadata(config) {
+  if (config.mode === "manual") {
+    return {
+      issuer: config.issuer,
+      authorizationEndpoint: config.authorizationEndpoint,
+      tokenEndpoint: config.tokenEndpoint,
+      jwksUri: config.jwksUri,
+      userInfoEndpoint: config.userInfoEndpoint,
+      endSessionEndpoint: config.endSessionEndpoint,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes
+    };
+  }
+  if (!config.issuer) {
+    throw new OidcVaultHttpError(500, "OIDC_VAULT_INVALID_CONFIG", "Issuer discovery requires an issuer URL.");
+  }
+  return {
+    ...await discoverIssuerMetadata(config.issuer),
+    clientId: config.clientId,
+    clientSecret: config.clientSecret,
+    scopes: config.scopes
+  };
+}
+async function requestToken(metadata, params) {
+  const clientId = metadata.clientId;
+  if (!clientId) {
+    throw new OidcVaultHttpError(500, "OIDC_VAULT_MISSING_CLIENT_ID", "OIDC clientId is required.");
+  }
+  const body = new URLSearchParams();
+  body.set("client_id", clientId);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0) {
+      body.set(key, value);
+    }
+  }
+  const headers = {
+    "content-type": "application/x-www-form-urlencoded"
+  };
+  if (metadata.clientSecret) {
+    headers.authorization = toBasicAuthorization(clientId, metadata.clientSecret);
+  }
+  const response = await fetch(metadata.tokenEndpoint, {
+    method: "POST",
+    headers,
+    body
+  });
+  const json = await readJsonResponse(response, "OIDC_VAULT_TOKEN_REQUEST_FAILED");
+  if (!response.ok) {
+    throw new OidcVaultHttpError(
+      502,
+      "OIDC_VAULT_TOKEN_REQUEST_FAILED",
+      typeof json.error_description === "string" ? json.error_description : `OIDC token request failed with status ${response.status}.`
+    );
+  }
+  return json;
+}
+async function fetchUserInfo(metadata, accessToken) {
+  if (!metadata.userInfoEndpoint) {
+    return {};
+  }
+  const response = await fetch(metadata.userInfoEndpoint, {
+    headers: {
+      authorization: `Bearer ${accessToken}`
+    }
+  });
+  const json = await readJsonResponse(response, "OIDC_VAULT_USERINFO_FAILED");
+  if (!response.ok) {
+    throw new OidcVaultHttpError(
+      502,
+      "OIDC_VAULT_USERINFO_FAILED",
+      `OIDC userinfo request failed with status ${response.status}.`
+    );
+  }
+  return json;
+}
+async function verifyIdToken(metadata, idToken, nonce) {
+  if (!metadata.jwksUri) {
+    throw new OidcVaultHttpError(500, "OIDC_VAULT_MISSING_JWKS_URI", "OIDC jwksUri is required to validate id_token.");
+  }
+  if (!metadata.clientId) {
+    throw new OidcVaultHttpError(
+      500,
+      "OIDC_VAULT_MISSING_CLIENT_ID",
+      "OIDC clientId is required to validate id_token."
+    );
+  }
+  const jwks = resolveJwks(metadata.jwksUri);
+  const result = await jwtVerify(idToken, jwks, {
+    audience: metadata.clientId,
+    issuer: metadata.issuer
+  });
+  if (nonce && result.payload.nonce !== nonce) {
+    throw new OidcVaultHttpError(502, "OIDC_VAULT_INVALID_ID_TOKEN", "OIDC id_token nonce validation failed.");
+  }
+  return result.payload;
+}
+async function verifyBackchannelLogoutToken(metadata, logoutToken) {
+  if (!metadata.jwksUri) {
+    throw new OidcVaultHttpError(
+      500,
+      "OIDC_VAULT_MISSING_JWKS_URI",
+      "OIDC jwksUri is required to validate logout_token."
+    );
+  }
+  if (!metadata.clientId) {
+    throw new OidcVaultHttpError(
+      500,
+      "OIDC_VAULT_MISSING_CLIENT_ID",
+      "OIDC clientId is required to validate logout_token."
+    );
+  }
+  const jwks = resolveJwks(metadata.jwksUri);
+  const result = await jwtVerify(logoutToken, jwks, {
+    audience: metadata.clientId,
+    issuer: metadata.issuer
+  });
+  const claims = result.payload;
+  if (claims.nonce !== void 0) {
+    throw new OidcVaultHttpError(
+      400,
+      "OIDC_VAULT_INVALID_LOGOUT_TOKEN",
+      "Backchannel logout token must not contain nonce."
+    );
+  }
+  if (!isRecord(claims.events) || !(BACKCHANNEL_LOGOUT_EVENT_CLAIM in claims.events)) {
+    throw new OidcVaultHttpError(
+      400,
+      "OIDC_VAULT_INVALID_LOGOUT_TOKEN",
+      "Backchannel logout token is missing the required event claim."
+    );
+  }
+  if (!isString(claims.sid) && !isString(claims.sub)) {
+    throw new OidcVaultHttpError(
+      400,
+      "OIDC_VAULT_INVALID_LOGOUT_TOKEN",
+      "Backchannel logout token must include sid or sub."
+    );
+  }
+  if (!isString(claims.jti)) {
+    throw new OidcVaultHttpError(400, "OIDC_VAULT_INVALID_LOGOUT_TOKEN", "Backchannel logout token must include jti.");
+  }
+  return claims;
+}
+var createLoginHandler = (options, config, basePath) => createAsyncHandler("login", options, async (req, res) => {
+  const metadata = await resolveProviderMetadata(config);
+  await callHook("login", options.hooks?.onLoginStart, req, res, void 0, { provider: metadata });
+  const now = getNow(options);
+  const pkceVerifier = createPkceVerifier();
+  const transaction = {
+    state: createOpaqueId("state"),
+    nonce: createOpaqueId("nonce"),
+    pkceVerifier,
+    codeChallenge: createPkceChallenge(pkceVerifier),
+    returnTo: resolveReturnTo(req, options),
+    createdAt: now,
+    expiresAt: now + (options.authorizationTransactionTtlMs ?? DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS)
+  };
+  await options.storeProvider.createAuthorizationTransaction(transaction);
+  const authorizationUrl = buildAuthorizationUrl(metadata, transaction, getCallbackUri(req, basePath));
+  await callHook("login", options.hooks?.onAuthorizationUrl, req, res, void 0, {
+    authorizationUrl,
+    state: transaction.state
+  });
+  res.redirect(302, authorizationUrl);
+});
+var createCallbackHandler = (options, config, basePath) => createAsyncHandler("callback", options, async (req, res) => {
+  if (isString(req.query.error)) {
+    throw new OidcVaultHttpError(400, "OIDC_VAULT_CALLBACK_ERROR", req.query.error);
+  }
+  const code = getRequiredString(
+    req.query.code,
+    "OIDC callback is missing the authorization code.",
+    "OIDC_VAULT_MISSING_CODE"
+  );
+  const state = getRequiredString(req.query.state, "OIDC callback is missing state.", "OIDC_VAULT_MISSING_STATE");
+  const transaction = await options.storeProvider.consumeAuthorizationTransaction(state);
+  if (!transaction) {
+    throw new OidcVaultHttpError(400, "OIDC_VAULT_INVALID_STATE", "OIDC state is invalid or expired.");
+  }
+  const metadata = await resolveProviderMetadata(config);
+  const tokenResponse = await requestToken(metadata, {
+    grant_type: "authorization_code",
+    code,
+    code_verifier: transaction.pkceVerifier,
+    redirect_uri: getCallbackUri(req, basePath)
+  });
+  if (!isString(tokenResponse.id_token)) {
+    throw new OidcVaultHttpError(502, "OIDC_VAULT_MISSING_ID_TOKEN", "OIDC token response is missing id_token.");
+  }
+  if (!isString(tokenResponse.refresh_token)) {
+    throw new OidcVaultHttpError(
+      502,
+      "OIDC_VAULT_MISSING_REFRESH_TOKEN",
+      "OIDC token response is missing refresh_token."
+    );
+  }
+  await callHook("callback", options.hooks?.onCallbackTokens, req, res, void 0, {
+    hasAccessToken: Boolean(tokenResponse.access_token),
+    hasRefreshToken: true,
+    hasIdToken: true
+  });
+  const claims = await verifyIdToken(metadata, tokenResponse.id_token, transaction.nonce);
+  const subject = getRequiredString(claims.sub, "OIDC id_token is missing sub.", "OIDC_VAULT_INVALID_ID_TOKEN", 502);
+  const userInfo = shouldFetchUserInfo(options, metadata) && isString(tokenResponse.access_token) ? await fetchUserInfo(metadata, tokenResponse.access_token) : void 0;
+  if (userInfo) {
+    await callHook("callback", options.hooks?.onUserInfo, req, res, void 0, { subject });
+  }
+  const now = getNow(options);
+  const sessionId = createOpaqueId("sess");
+  const session = {
+    sessionId,
+    subject,
+    providerSessionId: typeof claims.sid === "string" ? claims.sid : void 0,
+    provider: {
+      issuer: metadata.issuer ?? (typeof claims.iss === "string" ? claims.iss : void 0),
+      clientId: metadata.clientId
+    },
+    refreshToken: tokenResponse.refresh_token,
+    idToken: tokenResponse.id_token,
+    accessToken: isString(tokenResponse.access_token) ? tokenResponse.access_token : void 0,
+    scope: typeof tokenResponse.scope === "string" ? tokenResponse.scope : metadata.scopes,
+    expiresAt: typeof tokenResponse.expires_in === "number" ? now + tokenResponse.expires_in * 1e3 : void 0,
+    createdAt: now,
+    updatedAt: now,
+    user: mergeUserProfile(subject, claims, userInfo),
+    metadata: {
+      tokenType: tokenResponse.token_type
+    }
+  };
+  await callHook("callback", options.hooks?.onBeforeSessionCreate, req, res, session, { subject });
+  const createdSession = await options.storeProvider.createSession(session);
+  await callHook("callback", options.hooks?.onSessionCreated, req, res, createdSession, { subject });
+  const exchangeCode = createOpaqueId("code");
+  await options.storeProvider.createExchangeCode({
+    code: exchangeCode,
+    sessionId: createdSession.sessionId,
+    returnTo: transaction.returnTo,
+    createdAt: now,
+    expiresAt: now + (options.exchangeCodeTtlMs ?? DEFAULT_EXCHANGE_CODE_TTL_MS)
+  });
+  res.redirect(302, appendCodeToRedirectUri(resolveFrontendRedirectUri(transaction, options), exchangeCode));
+});
+var createExchangeHandler = (options) => createAsyncHandler("exchange", options, async (req, res) => {
+  const body = getBody(req);
+  const code = getRequiredString(body.code, "Exchange request is missing code.", "OIDC_VAULT_MISSING_EXCHANGE_CODE");
+  const exchangeRecord = await options.storeProvider.consumeExchangeCode(code);
+  if (!exchangeRecord) {
+    throw new OidcVaultHttpError(400, "OIDC_VAULT_INVALID_EXCHANGE_CODE", "Exchange code is invalid or expired.");
+  }
+  const session = await options.storeProvider.getSession(exchangeRecord.sessionId);
+  if (!session) {
+    throw new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
+  }
+  const issuedToken = await withIssuedToken(req, res, options, session);
+  if (usesCookieTransport(options)) {
+    setSessionCookie(res, options, session.sessionId);
+  }
+  const response = createExchangeResponse(options, session, issuedToken);
+  res.status(200).json(response);
+});
+var createRefreshHandler = (options, config, trustedOrigins) => createAsyncHandler("refresh", options, async (req, res) => {
+  assertTrustedOrigin(req, options, trustedOrigins, "refresh");
+  const sessionId = getSessionIdFromRequest(req, options, "refresh");
+  const currentSession = await options.storeProvider.getSession(sessionId);
+  if (!currentSession) {
+    if (usesCookieTransport(options)) {
+      clearSessionCookie(res, options);
+    }
+    throw new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
+  }
+  const metadata = await resolveProviderMetadata(config);
+  const tokenResponse = await requestToken(metadata, {
+    grant_type: "refresh_token",
+    refresh_token: currentSession.refreshToken
+  });
+  const idToken = isString(tokenResponse.id_token) ? tokenResponse.id_token : currentSession.idToken;
+  const claims = await verifyIdToken(metadata, idToken);
+  const subject = getRequiredString(claims.sub, "OIDC id_token is missing sub.", "OIDC_VAULT_INVALID_ID_TOKEN", 502);
+  const userInfo = shouldFetchUserInfo(options, metadata) && isString(tokenResponse.access_token) ? await fetchUserInfo(metadata, tokenResponse.access_token) : void 0;
+  const now = getNow(options);
+  const nextSession = {
+    ...currentSession,
+    sessionId: createOpaqueId("sess"),
+    subject,
+    providerSessionId: typeof claims.sid === "string" ? claims.sid : currentSession.providerSessionId,
+    refreshToken: isString(tokenResponse.refresh_token) ? tokenResponse.refresh_token : currentSession.refreshToken,
+    idToken,
+    accessToken: isString(tokenResponse.access_token) ? tokenResponse.access_token : currentSession.accessToken,
+    scope: typeof tokenResponse.scope === "string" ? tokenResponse.scope : currentSession.scope,
+    expiresAt: typeof tokenResponse.expires_in === "number" ? now + tokenResponse.expires_in * 1e3 : currentSession.expiresAt,
+    updatedAt: now,
+    user: mergeUserProfile(subject, claims, userInfo ?? currentSession.user)
+  };
+  const issuedToken = await withIssuedToken(req, res, options, nextSession);
+  let rotatedSession;
+  try {
+    rotatedSession = await options.storeProvider.rotateSession({
+      sessionId: currentSession.sessionId,
+      nextSession
+    });
+  } catch (error) {
+    if (error instanceof OidcVaultStoreConflictError) {
+      if (usesCookieTransport(options)) {
+        clearSessionCookie(res, options);
+      }
+      throw new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
+    }
+    throw error;
+  }
+  await callHook("refresh", options.hooks?.onSessionRefreshed, req, res, rotatedSession, {
+    previousSessionId: currentSession.sessionId
+  });
+  if (usesCookieTransport(options)) {
+    setSessionCookie(res, options, rotatedSession.sessionId);
+  }
+  const response = createExchangeResponse(options, rotatedSession, issuedToken);
+  res.status(200).json(response);
+});
+var createLogoutHandler = (options, config, trustedOrigins) => createAsyncHandler("logout", options, async (req, res) => {
+  assertTrustedOrigin(req, options, trustedOrigins, "logout");
+  const body = getBody(req);
+  const sessionId = getSessionIdFromRequest(req, options, "logout");
+  const redirect = body.redirect === true;
+  const session = await options.storeProvider.getSession(sessionId);
+  if (!session) {
+    if (usesCookieTransport(options)) {
+      clearSessionCookie(res, options);
+    }
+    res.status(200).json({ loggedOut: true });
+    return;
+  }
+  await callHook("logout", options.hooks?.onBeforeLogout, req, res, session, void 0);
+  await options.storeProvider.deleteSession(sessionId);
+  if (usesCookieTransport(options)) {
+    clearSessionCookie(res, options);
+  }
+  const metadata = await resolveProviderMetadata(config);
+  const upstreamLogoutUrl = metadata.endSessionEndpoint ? buildLogoutUrl(metadata.endSessionEndpoint, session.idToken, options.postLogoutRedirectUri) : void 0;
+  await callHook("logout", options.hooks?.onLogout, req, res, session, { upstreamLogoutUrl });
+  if (redirect && upstreamLogoutUrl) {
+    res.redirect(302, upstreamLogoutUrl);
+    return;
+  }
+  res.status(200).json({
+    loggedOut: true,
+    upstreamLogoutUrl
+  });
+});
+var createBackchannelLogoutHandler = (options, config) => createAsyncHandler("backchannel-logout", options, async (req, res) => {
+  const metadata = await resolveProviderMetadata(config);
+  const logoutToken = getLogoutTokenFromRequest(req);
+  const claims = await verifyBackchannelLogoutToken(metadata, logoutToken);
+  const revokedSessions = isString(claims.sid) ? await options.storeProvider.deleteSessionsByProviderSessionId({
+    providerSessionId: claims.sid,
+    issuer: metadata.issuer,
+    clientId: metadata.clientId
+  }) : await options.storeProvider.deleteSessionsBySubject({
+    subject: String(claims.sub),
+    issuer: metadata.issuer,
+    clientId: metadata.clientId
+  });
+  await callHook("backchannel-logout", options.hooks?.onLogout, req, res, void 0, {
+    providerSessionId: claims.sid,
+    subject: claims.sub,
+    revokedSessions
+  });
+  res.status(200).json({
+    loggedOut: true,
+    revokedSessions
+  });
+});
+function registerRoutes(router, options, config, trustedOrigins, basePath) {
+  router.get(OIDC_VAULT_ROUTE_PATHS.login, createLoginHandler(options, config, basePath));
+  router.get(OIDC_VAULT_ROUTE_PATHS.callback, createCallbackHandler(options, config, basePath));
+  router.post(OIDC_VAULT_ROUTE_PATHS.exchange, createExchangeHandler(options));
+  router.post(OIDC_VAULT_ROUTE_PATHS.refresh, createRefreshHandler(options, config, trustedOrigins));
+  router.post(OIDC_VAULT_ROUTE_PATHS.logout, createLogoutHandler(options, config, trustedOrigins));
+  router.post(OIDC_VAULT_ROUTE_PATHS["backchannel-logout"], createBackchannelLogoutHandler(options, config));
+}
+function createOidcVaultJwtAccessTokenValidator(options) {
+  return {
+    async validate(token) {
+      const result = await jwtVerify(token, options.key, {
+        issuer: options.issuer,
+        audience: options.audience,
+        algorithms: options.algorithms
+      });
+      const claims = result.payload;
+      return options.mapClaims ? options.mapClaims(claims) : defaultJwtClaimsMapper(claims);
+    }
+  };
+}
+function createOidcVaultAccessTokenMiddleware(options) {
+  return async (req, res, next) => {
+    try {
+      const token = extractBearerToken(req.get("authorization"));
+      const validationResult = await options.validator.validate(token);
+      const auth = {
+        token,
+        ...validationResult
+      };
+      const authenticatedRequest = req;
+      authenticatedRequest.auth = auth;
+      await options.onAuthContext?.({ req: authenticatedRequest, res, auth });
+      next();
+    } catch (error) {
+      if (error instanceof OidcVaultHttpError) {
+        setBearerChallengeHeader(res);
+        res.status(error.status).json({
+          code: error.code,
+          message: error.message
+        });
+        return;
+      }
+      if (error instanceof Error) {
+        setBearerChallengeHeader(res);
+        res.status(401).json({
+          code: "OIDC_VAULT_INVALID_ACCESS_TOKEN",
+          message: error.message || "Access token validation failed."
+        });
+        return;
+      }
+      setBearerChallengeHeader(res);
+      res.status(401).json({
+        code: "OIDC_VAULT_INVALID_ACCESS_TOKEN",
+        message: "Access token validation failed."
+      });
+    }
+  };
+}
+function createOidcVaultMiddleware(options) {
+  const { config, trustedOrigins } = validateOidcVaultOptions(options);
+  const rootRouter = express.Router();
+  const baseRouter = express.Router();
+  const basePath = normalizeOidcVaultBasePath(options.basePath);
+  baseRouter.use(express.json());
+  baseRouter.use(express.urlencoded({ extended: false }));
+  registerRoutes(baseRouter, options, config, trustedOrigins, basePath);
+  rootRouter.use(basePath, baseRouter);
+  return rootRouter;
+}
+export {
+  DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS,
+  DEFAULT_EXCHANGE_CODE_TTL_MS,
+  DEFAULT_OIDC_SCOPES,
+  DEFAULT_OIDC_VAULT_BASE_PATH,
+  DEFAULT_SESSION_COOKIE_NAME,
+  OIDC_VAULT_ROUTE_PATHS,
+  OidcVaultStoreConflictError,
+  createOidcVaultAccessTokenMiddleware,
+  createOidcVaultJwtAccessTokenValidator,
+  createOidcVaultMiddleware,
+  normalizeOidcVaultBasePath,
+  resolveOidcVaultConfig,
+  resolveOidcVaultConfigFromEnv
+};