@blamejs/core 0.4.1

package/lib/auth/oauth.js

@@ -0,0 +1,691 @@
+"use strict";
+/**
+ * oauth — OAuth 2 / OIDC client.
+ *
+ * "Login with Google / GitHub / Microsoft / Apple / etc." — table
+ * stakes for B2C and SSO B2B. Without this, operators reach for
+ * `passport-*` packages and we lose control of the request flow.
+ *
+ * The framework's PQC-first stance applies to outbound crypto we
+ * emit. OIDC IdPs sign ID tokens with classical-algo JWS (RS256,
+ * ES256, etc.) — third-party crypto we MUST verify. This module
+ * carries an OIDC-specific verifier for that interop case;
+ * `lib/auth/jwt.js` remains PQC-only for tokens the FRAMEWORK signs.
+ *
+ * Public API:
+ *
+ *   var oauth = b.auth.oauth.create({
+ *     provider:    "google",                              // preset
+ *     clientId:    "...", clientSecret: "...",
+ *     redirectUri: "https://app/auth/callback",
+ *     scope:       ["openid", "email", "profile"],
+ *   });
+ *
+ *   // Or generic:
+ *   var oauth = b.auth.oauth.create({
+ *     issuer:      "https://auth.example.com",            // OIDC discovery
+ *     clientId, clientSecret, redirectUri, scope: [...],
+ *   });
+ *
+ *   // Step 1 — Build the authorize URL. Operator persists the
+ *   // returned `verifier` and `state` in their session.
+ *   var auth = await oauth.authorizationUrl();
+ *   //  → { url, state, nonce, verifier, challenge }
+ *   res.redirect(302, auth.url);
+ *
+ *   // Step 2 — In the callback handler, verify state + exchange code.
+ *   var stored = req.session.get("oauth-state");
+ *   if (req.query.state !== stored.state) throw new ForbiddenError();
+ *   var tokens = await oauth.exchangeCode({
+ *     code:     req.query.code,
+ *     state:    req.query.state,
+ *     verifier: stored.verifier,
+ *   });
+ *   //  → { accessToken, idToken, refreshToken, tokenType, expiresIn,
+ *   //      scope, claims, profile }
+ *
+ *   // Step 3 — operator decides: create user, link to existing, etc.
+ *
+ *   // Refresh:
+ *   var fresh = await oauth.refreshAccessToken(tokens.refreshToken);
+ *
+ *   // Revoke (RFC 7009; not all providers support it — checked at
+ *   // discovery, throws if unavailable):
+ *   await oauth.revokeToken(tokens.refreshToken, { type: "refresh_token" });
+ *
+ *   // Userinfo (OIDC standard endpoint):
+ *   var profile = await oauth.fetchUserInfo(tokens.accessToken);
+ *
+ * Vendor presets (b.auth.oauth.PRESETS):
+ *   google     OIDC discovery via accounts.google.com
+ *   microsoft  OIDC via login.microsoftonline.com (common tenant)
+ *   apple      "Sign in with Apple" — RSA-PSS signed ID tokens
+ *   auth0      OIDC via {tenant}.auth0.com (operator passes tenant)
+ *   keycloak   OIDC via {host}/realms/{realm}/.well-known/...
+ *   github     OAuth 2 only (NOT OIDC — no ID token; GitHub uses
+ *              a userinfo-equivalent endpoint /user)
+ *   generic    operator passes endpoints manually
+ *
+ * Discovery:
+ *   When `issuer` (or a preset's discovery URL) is set, the client
+ *   fetches `/.well-known/openid-configuration` on first use and
+ *   caches authorization_endpoint, token_endpoint, jwks_uri,
+ *   userinfo_endpoint, revocation_endpoint, supported algos. Cache
+ *   default 1 hour; operators tune via `discoveryCacheMs`.
+ *
+ * PKCE:
+ *   ON BY DEFAULT. RFC 7636. The framework refuses to build an
+ *   authorization URL without PKCE unless the operator explicitly
+ *   passes `pkce: false` (and even then it logs a warning). Operators
+ *   on legacy IdPs that don't support PKCE — vanishingly rare in 2026
+ *   — must opt out explicitly.
+ *
+ * State + nonce:
+ *   Generated fresh per-call. The framework returns them but doesn't
+ *   store them — that's the operator's session's job. The state
+ *   verifies the OAuth callback came from the same browser session
+ *   (CSRF defense); the nonce verifies the ID token wasn't replayed
+ *   from a different login flow.
+ *
+ * ID token verification (when an ID token is present):
+ *   - Header alg must be on `acceptedAlgorithms` (default RS256, RS384,
+ *     RS512, ES256, ES384, ES512, PS256, PS384, PS512). HS256 is
+ *     refused — symmetric-keyed ID tokens are an anti-pattern.
+ *   - kid lookup against the discovered JWKS.
+ *   - Signature verification via node:crypto for the matching algo.
+ *   - Claim validation: iss matches issuer, aud contains clientId,
+ *     exp not past, iat not future, nonce matches the call's nonce.
+ *
+ * HTTPS:
+ *   All endpoints must be https except localhost during dev. The
+ *   discovery / token / userinfo / revocation / jwks fetches go
+ *   through `b.httpClient` which enforces the framework's PQC-locked
+ *   posture by default (operators with mixed-protocol setups pass
+ *   `allowedProtocols`).
+ */
+
+var nodeCrypto = require("node:crypto");
+var cache = require("../cache");
+var safeUrl = require("../safe-url");
+var C = require("../constants");
+var { defineClass } = require("../framework-error");
+var { boot } = require("../log");
+
+var OAuthError = defineClass("OAuthError", { alwaysPermanent: true });
+var log = boot("auth.oauth");
+
+// Vendor presets. Each entry has either { issuer } (OIDC) or explicit
+// endpoints { authorizationEndpoint, tokenEndpoint, userinfoEndpoint }.
+var PRESETS = Object.freeze({
+  google: {
+    issuer:        "https://accounts.google.com",
+    defaultScope:  ["openid", "email", "profile"],
+    isOidc:        true,
+  },
+  microsoft: {
+    issuer:        "https://login.microsoftonline.com/common/v2.0",
+    defaultScope:  ["openid", "email", "profile"],
+    isOidc:        true,
+  },
+  apple: {
+    issuer:        "https://appleid.apple.com",
+    defaultScope:  ["openid", "email", "name"],
+    isOidc:        true,
+    // Apple wants form_post response_mode (browser POSTs back to redirect).
+    responseMode:  "form_post",
+  },
+  auth0: {
+    // Operator passes auth0Domain: "tenant.auth0.com" via opts; we
+    // expand it into the issuer URL.
+    issuerTemplate: function (opts) {
+      if (!opts.auth0Domain) {
+        throw new OAuthError("auth-oauth/auth0-domain",
+          "auth0 preset requires opts.auth0Domain ('your-tenant.auth0.com')");
+      }
+      return "https://" + opts.auth0Domain;
+    },
+    defaultScope:   ["openid", "email", "profile"],
+    isOidc:         true,
+  },
+  keycloak: {
+    // Keycloak realms: opts.keycloakUrl + opts.keycloakRealm
+    issuerTemplate: function (opts) {
+      if (!opts.keycloakUrl || !opts.keycloakRealm) {
+        throw new OAuthError("auth-oauth/keycloak-config",
+          "keycloak preset requires opts.keycloakUrl and opts.keycloakRealm");
+      }
+      return opts.keycloakUrl.replace(/\/$/, "") + "/realms/" + opts.keycloakRealm;
+    },
+    defaultScope:   ["openid", "email", "profile"],
+    isOidc:         true,
+  },
+  github: {
+    // GitHub is OAuth 2 only — no OIDC, no ID tokens, no JWKS.
+    authorizationEndpoint: "https://github.com/login/oauth/authorize",
+    tokenEndpoint:         "https://github.com/login/oauth/access_token",
+    userinfoEndpoint:      "https://api.github.com/user",
+    defaultScope:          ["read:user", "user:email"],
+    isOidc:                false,
+  },
+  generic: {
+    // Operator-defined endpoints (or issuer-driven discovery). The
+    // preset itself adds nothing — its presence makes provider:'generic'
+    // a valid explicit selector instead of falling through to "unknown
+    // provider preset". Operators pass authorizationEndpoint /
+    // tokenEndpoint / userinfoEndpoint (or issuer + isOidc:true to
+    // discover) on opts.
+  },
+});
+
+var DEFAULT_ACCEPTED_ALGS = Object.freeze([
+  "RS256", "RS384", "RS512",
+  "ES256", "ES384", "ES512",
+  "PS256", "PS384", "PS512",
+]);
+
+var DEFAULT_DISCOVERY_CACHE_MS = C.TIME.hours(1);
+var DEFAULT_CLOCK_SKEW_MS      = C.TIME.minutes(1);
+
+// ---- helpers ----
+
+function _b64urlEncode(buf) {
+  if (typeof buf === "string") buf = Buffer.from(buf, "utf8");
+  return buf.toString("base64").replace(/=+$/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+function _b64urlDecode(s) {
+  if (typeof s !== "string") throw new OAuthError("auth-oauth/bad-base64", "expected base64url string");
+  var padded = s.replace(/-/g, "+").replace(/_/g, "/");
+  while (padded.length % 4) padded += "=";
+  return Buffer.from(padded, "base64");
+}
+
+function _generateRandomToken(bytes) {
+  return _b64urlEncode(nodeCrypto.randomBytes(bytes));
+}
+
+function _generatePkce() {
+  // RFC 7636: code_verifier is 43–128 chars [A-Za-z0-9-._~].
+  // base64url of 32 random bytes = 43 chars, all valid.
+  var verifier = _b64urlEncode(nodeCrypto.randomBytes(32));
+  var challenge = _b64urlEncode(nodeCrypto.createHash("sha256").update(verifier).digest());
+  return { verifier: verifier, challenge: challenge };
+}
+
+function _validateUrl(url, allowHttp, label) {
+  if (typeof url !== "string" || url.length === 0) {
+    throw new OAuthError("auth-oauth/bad-url", label + ": URL is required");
+  }
+  var parsed;
+  try { parsed = new URL(url); }
+  catch (_e) {
+    throw new OAuthError("auth-oauth/bad-url", label + ": invalid URL '" + url + "'");
+  }
+  if (parsed.protocol === "https:") return url;
+  if (parsed.protocol === "http:" && allowHttp) return url;
+  throw new OAuthError("auth-oauth/insecure-url",
+    label + ": must be https (got '" + parsed.protocol + "//" + parsed.host + "')");
+}
+
+// ---- JOSE alg → node:crypto verify parameters ----
+
+function _verifyParamsForAlg(alg) {
+  // Returns { hash, padding, dsaEncoding } for node:crypto.verify.
+  if (alg === "RS256") return { hash: "sha256", padding: nodeCrypto.constants.RSA_PKCS1_PADDING };
+  if (alg === "RS384") return { hash: "sha384", padding: nodeCrypto.constants.RSA_PKCS1_PADDING };
+  if (alg === "RS512") return { hash: "sha512", padding: nodeCrypto.constants.RSA_PKCS1_PADDING };
+  if (alg === "PS256") return { hash: "sha256", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 };
+  if (alg === "PS384") return { hash: "sha384", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 48 };
+  if (alg === "PS512") return { hash: "sha512", padding: nodeCrypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: 64 };
+  if (alg === "ES256") return { hash: "sha256", dsaEncoding: "ieee-p1363" };
+  if (alg === "ES384") return { hash: "sha384", dsaEncoding: "ieee-p1363" };
+  if (alg === "ES512") return { hash: "sha512", dsaEncoding: "ieee-p1363" };
+  throw new OAuthError("auth-oauth/unsupported-alg",
+    "alg '" + alg + "' is not supported for ID-token verification");
+}
+
+// ---- JWKS → KeyObject ----
+
+function _jwkToKey(jwk) {
+  // node's createPublicKey accepts JWK directly since Node 16.
+  try { return nodeCrypto.createPublicKey({ key: jwk, format: "jwk" }); }
+  catch (e) {
+    throw new OAuthError("auth-oauth/bad-jwk",
+      "could not import JWK (kid=" + (jwk && jwk.kid) + "): " + ((e && e.message) || String(e)));
+  }
+}
+
+// ---- core ----
+
+function create(opts) {
+  opts = opts || {};
+  var clientId     = opts.clientId;
+  var clientSecret = opts.clientSecret || null;     // public clients can omit
+  var redirectUri  = opts.redirectUri;
+  var pkce         = opts.pkce !== false;
+  var clockSkewMs  = typeof opts.clockSkewMs === "number" ? opts.clockSkewMs : DEFAULT_CLOCK_SKEW_MS;
+  var discoveryCacheMs = typeof opts.discoveryCacheMs === "number"
+                           ? opts.discoveryCacheMs : DEFAULT_DISCOVERY_CACHE_MS;
+  var acceptedAlgorithms = Array.isArray(opts.acceptedAlgorithms) && opts.acceptedAlgorithms.length > 0
+                             ? opts.acceptedAlgorithms.slice() : DEFAULT_ACCEPTED_ALGS.slice();
+  var allowHttp        = !!opts.allowHttp;          // localhost dev opt-in
+  var httpClientOpts   = opts.httpClient || {};
+  var responseMode     = opts.responseMode || null;
+
+  if (!clientId) {
+    throw new OAuthError("auth-oauth/no-client-id", "create: opts.clientId is required");
+  }
+  if (!redirectUri) {
+    throw new OAuthError("auth-oauth/no-redirect-uri", "create: opts.redirectUri is required");
+  }
+  _validateUrl(redirectUri, allowHttp, "redirectUri");
+  if (!pkce) {
+    log("WARNING: PKCE disabled — modern IdPs require it; this should only be used for legacy providers");
+  }
+
+  // Resolve preset → effective config.
+  var preset = null;
+  if (opts.provider) {
+    if (!Object.prototype.hasOwnProperty.call(PRESETS, opts.provider)) {
+      throw new OAuthError("auth-oauth/unknown-provider",
+        "unknown provider preset '" + opts.provider + "' (known: " +
+        Object.keys(PRESETS).join(", ") + ")");
+    }
+    preset = PRESETS[opts.provider];
+  }
+  var isOidc = (preset && typeof preset.isOidc === "boolean") ? preset.isOidc
+             : (opts.isOidc !== undefined ? !!opts.isOidc : true);
+  var issuer = opts.issuer
+             || (preset && typeof preset.issuerTemplate === "function" && preset.issuerTemplate(opts))
+             || (preset && preset.issuer)
+             || null;
+  var scope = Array.isArray(opts.scope) && opts.scope.length > 0
+                ? opts.scope.slice()
+                : (preset && preset.defaultScope ? preset.defaultScope.slice() : ["openid"]);
+  if (!responseMode && preset && preset.responseMode) responseMode = preset.responseMode;
+
+  // Endpoints — either from preset (explicit), discovery, or operator opts.
+  var staticEndpoints = {
+    authorizationEndpoint: opts.authorizationEndpoint || (preset && preset.authorizationEndpoint) || null,
+    tokenEndpoint:         opts.tokenEndpoint         || (preset && preset.tokenEndpoint)         || null,
+    userinfoEndpoint:      opts.userinfoEndpoint      || (preset && preset.userinfoEndpoint)      || null,
+    revocationEndpoint:    opts.revocationEndpoint    || (preset && preset.revocationEndpoint)    || null,
+    jwksUri:               opts.jwksUri               || (preset && preset.jwksUri)               || null,
+  };
+
+  // Discovery + JWKS caches use b.cache.create + .wrap so concurrent
+  // boot races for the same IdP collapse to one fetch (single-flight)
+  // and operators can wire b.audit / observability without us
+  // re-implementing those hooks here. Per-cache namespaces are unique
+  // per oauth-client instance (clientId-scoped) so two clients pointed
+  // at different IdPs don't collide in a future cluster-cache backend.
+  var jwksCacheMs = typeof opts.jwksCacheMs === "number" ? opts.jwksCacheMs : DEFAULT_DISCOVERY_CACHE_MS;
+  var _discoveryCache = cache.create({
+    namespace: "oauth.discovery." + clientId,
+    ttlMs:     discoveryCacheMs,
+  });
+  var _jwksCache = cache.create({
+    namespace: "oauth.jwks." + clientId,
+    ttlMs:     jwksCacheMs,
+  });
+
+  function _httpClient() {
+    return require("../http-client");
+  }
+
+  async function _fetchJson(url, fetchOpts) {
+    fetchOpts = fetchOpts || {};
+    var hc = _httpClient();
+    var req = Object.assign({
+      url:    url,
+      method: "GET",
+    }, fetchOpts);
+    if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    Object.assign(req, httpClientOpts);
+    var res = await hc.request(req);
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      var bodyText = res.body ? res.body.toString("utf8") : "";
+      throw new OAuthError("auth-oauth/http-" + res.statusCode,
+        url + " returned " + res.statusCode + ": " + bodyText.slice(0, 500));
+    }
+    if (!res.body) return null;
+    try { return JSON.parse(res.body.toString("utf8")); }
+    catch (e) {
+      throw new OAuthError("auth-oauth/bad-json",
+        url + " response not JSON: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  async function _discover() {
+    if (!isOidc || !issuer) return null;
+    return _discoveryCache.wrap("config", async function () {
+      var url = issuer.replace(/\/$/, "") + "/.well-known/openid-configuration";
+      _validateUrl(url, allowHttp, "discovery url");
+      var config = await _fetchJson(url);
+      if (!config || typeof config !== "object") {
+        throw new OAuthError("auth-oauth/bad-discovery", "discovery document missing");
+      }
+      if (config.issuer && config.issuer !== issuer) {
+        throw new OAuthError("auth-oauth/issuer-mismatch",
+          "discovery issuer '" + config.issuer + "' does not match configured issuer '" + issuer + "'");
+      }
+      return config;
+    });
+  }
+
+  async function _resolveEndpoint(name) {
+    if (staticEndpoints[name]) return staticEndpoints[name];
+    var config = await _discover();
+    if (!config) {
+      throw new OAuthError("auth-oauth/no-endpoint",
+        name + " endpoint not configured and no OIDC discovery available");
+    }
+    // OIDC discovery uses snake_case key names.
+    var snake = ({
+      authorizationEndpoint: "authorization_endpoint",
+      tokenEndpoint:         "token_endpoint",
+      userinfoEndpoint:      "userinfo_endpoint",
+      revocationEndpoint:    "revocation_endpoint",
+      jwksUri:               "jwks_uri",
+    })[name];
+    var endpoint = config[snake];
+    if (!endpoint) {
+      throw new OAuthError("auth-oauth/no-endpoint",
+        name + " not present in discovery document");
+    }
+    return endpoint;
+  }
+
+  async function authorizationUrl(uopts) {
+    uopts = uopts || {};
+    var endpoint = await _resolveEndpoint("authorizationEndpoint");
+    var state = uopts.state || _generateRandomToken(16);
+    var nonce = uopts.nonce || (isOidc ? _generateRandomToken(16) : null);
+    var pkceVals = pkce ? _generatePkce() : null;
+    var params = new URLSearchParams();
+    params.set("response_type", "code");
+    params.set("client_id",     clientId);
+    params.set("redirect_uri",  redirectUri);
+    params.set("scope",         scope.join(" "));
+    params.set("state",         state);
+    if (nonce)         params.set("nonce", nonce);
+    if (pkceVals) {
+      params.set("code_challenge", pkceVals.challenge);
+      params.set("code_challenge_method", "S256");
+    }
+    if (responseMode)  params.set("response_mode", responseMode);
+    if (uopts.prompt)  params.set("prompt", uopts.prompt);
+    if (uopts.loginHint) params.set("login_hint", uopts.loginHint);
+    if (uopts.maxAge != null) params.set("max_age", String(uopts.maxAge));
+    // Operator-supplied additional params (audience, resource, etc.).
+    if (uopts.extraParams && typeof uopts.extraParams === "object") {
+      var ek = Object.keys(uopts.extraParams);
+      for (var i = 0; i < ek.length; i++) params.set(ek[i], String(uopts.extraParams[ek[i]]));
+    }
+    var sep = endpoint.indexOf("?") === -1 ? "?" : "&";
+    return {
+      url:       endpoint + sep + params.toString(),
+      state:     state,
+      nonce:     nonce,
+      verifier:  pkceVals ? pkceVals.verifier  : null,
+      challenge: pkceVals ? pkceVals.challenge : null,
+    };
+  }
+
+  async function exchangeCode(eopts) {
+    eopts = eopts || {};
+    if (!eopts.code) {
+      throw new OAuthError("auth-oauth/no-code", "exchangeCode: opts.code is required");
+    }
+    if (pkce && !eopts.verifier) {
+      throw new OAuthError("auth-oauth/no-verifier",
+        "exchangeCode: opts.verifier is required when PKCE is on (default)");
+    }
+    var endpoint = await _resolveEndpoint("tokenEndpoint");
+    var body = new URLSearchParams();
+    body.set("grant_type",   "authorization_code");
+    body.set("code",         eopts.code);
+    body.set("redirect_uri", redirectUri);
+    body.set("client_id",    clientId);
+    if (clientSecret) body.set("client_secret", clientSecret);
+    if (eopts.verifier) body.set("code_verifier", eopts.verifier);
+
+    var tokens = await _postForm(endpoint, body);
+    return await _normalizeTokens(tokens, { nonce: eopts.nonce });
+  }
+
+  async function refreshAccessToken(refreshToken) {
+    if (!refreshToken) {
+      throw new OAuthError("auth-oauth/no-refresh-token",
+        "refreshAccessToken: refresh token is required");
+    }
+    var endpoint = await _resolveEndpoint("tokenEndpoint");
+    var body = new URLSearchParams();
+    body.set("grant_type",    "refresh_token");
+    body.set("refresh_token", refreshToken);
+    body.set("client_id",     clientId);
+    if (clientSecret) body.set("client_secret", clientSecret);
+    var tokens = await _postForm(endpoint, body);
+    // Refreshed tokens may not include a new id_token; verification
+    // is conditional.
+    return await _normalizeTokens(tokens, { skipNonceCheck: true });
+  }
+
+  async function fetchUserInfo(accessToken) {
+    if (!accessToken) {
+      throw new OAuthError("auth-oauth/no-access-token",
+        "fetchUserInfo: access token is required");
+    }
+    var endpoint = await _resolveEndpoint("userinfoEndpoint");
+    return await _fetchJson(endpoint, {
+      headers: {
+        "Authorization": "Bearer " + accessToken,
+        "Accept":        "application/json",
+        "User-Agent":    "blamejs",
+      },
+    });
+  }
+
+  async function revokeToken(token, ropts) {
+    if (!token) {
+      throw new OAuthError("auth-oauth/no-token", "revokeToken: token is required");
+    }
+    ropts = ropts || {};
+    var endpoint = await _resolveEndpoint("revocationEndpoint");
+    var body = new URLSearchParams();
+    body.set("token", token);
+    if (ropts.type) body.set("token_type_hint", ropts.type);
+    body.set("client_id", clientId);
+    if (clientSecret) body.set("client_secret", clientSecret);
+    var hc = _httpClient();
+    var req = {
+      url:     endpoint,
+      method:  "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body:    Buffer.from(body.toString(), "utf8"),
+    };
+    if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    Object.assign(req, httpClientOpts);
+    var res = await hc.request(req);
+    // RFC 7009: 200 even if the token was already revoked / unknown.
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      throw new OAuthError("auth-oauth/revoke-failed",
+        "revocation returned " + res.statusCode);
+    }
+  }
+
+  async function _postForm(endpoint, body) {
+    var hc = _httpClient();
+    var req = {
+      url:     endpoint,
+      method:  "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept":       "application/json",
+      },
+      body:    Buffer.from(body.toString(), "utf8"),
+    };
+    if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    Object.assign(req, httpClientOpts);
+    var res = await hc.request(req);
+    var text = res.body ? res.body.toString("utf8") : "";
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      throw new OAuthError("auth-oauth/token-error-" + res.statusCode,
+        endpoint + " returned " + res.statusCode + ": " + text.slice(0, 500));
+    }
+    var parsed;
+    try { parsed = JSON.parse(text); }
+    catch (e) {
+      throw new OAuthError("auth-oauth/bad-token-json",
+        "token endpoint response not JSON: " + ((e && e.message) || String(e)));
+    }
+    return parsed;
+  }
+
+  async function _normalizeTokens(raw, vopts) {
+    vopts = vopts || {};
+    var tokens = {
+      accessToken:  raw.access_token,
+      tokenType:    raw.token_type || "Bearer",
+      expiresIn:    raw.expires_in || null,
+      refreshToken: raw.refresh_token || null,
+      idToken:      raw.id_token || null,
+      scope:        raw.scope ? raw.scope.split(/\s+/) : scope.slice(),
+      raw:          raw,
+    };
+    if (tokens.idToken && isOidc) {
+      var v = await verifyIdToken(tokens.idToken, {
+        nonce:          vopts.nonce,
+        skipNonceCheck: vopts.skipNonceCheck,
+      });
+      tokens.claims  = v.claims;
+      tokens.profile = {
+        sub:     v.claims.sub,
+        email:   v.claims.email,
+        name:    v.claims.name,
+        picture: v.claims.picture,
+      };
+    }
+    return tokens;
+  }
+
+  async function _getJwks() {
+    return _jwksCache.wrap("keys", async function () {
+      var jwksUri = await _resolveEndpoint("jwksUri");
+      var jwks = await _fetchJson(jwksUri);
+      if (!jwks || !Array.isArray(jwks.keys)) {
+        throw new OAuthError("auth-oauth/bad-jwks", "JWKS response missing 'keys' array");
+      }
+      return jwks.keys;
+    });
+  }
+
+  async function verifyIdToken(idToken, vopts) {
+    vopts = vopts || {};
+    if (typeof idToken !== "string") {
+      throw new OAuthError("auth-oauth/no-id-token", "verifyIdToken: idToken must be a string");
+    }
+    var parts = idToken.split(".");
+    if (parts.length !== 3) {
+      throw new OAuthError("auth-oauth/malformed-jwt", "ID token does not have 3 parts");
+    }
+    var header, payload;
+    try {
+      header  = JSON.parse(_b64urlDecode(parts[0]).toString("utf8"));
+      payload = JSON.parse(_b64urlDecode(parts[1]).toString("utf8"));
+    } catch (e) {
+      throw new OAuthError("auth-oauth/malformed-jwt",
+        "ID token header/payload base64 decode failed: " + ((e && e.message) || String(e)));
+    }
+    if (!header || typeof header.alg !== "string") {
+      throw new OAuthError("auth-oauth/malformed-jwt", "ID token header missing 'alg'");
+    }
+    if (acceptedAlgorithms.indexOf(header.alg) === -1) {
+      throw new OAuthError("auth-oauth/alg-not-accepted",
+        "ID token signed with '" + header.alg + "' which is not in the accepted-algorithm list");
+    }
+    var keys = await _getJwks();
+    var match = null;
+    if (header.kid) {
+      for (var i = 0; i < keys.length; i++) {
+        if (keys[i].kid === header.kid) { match = keys[i]; break; }
+      }
+    } else if (keys.length === 1) {
+      match = keys[0];
+    }
+    if (!match) {
+      throw new OAuthError("auth-oauth/no-matching-key",
+        "no JWKS key matches header.kid='" + header.kid + "'");
+    }
+    var keyObject = _jwkToKey(match);
+    var params = _verifyParamsForAlg(header.alg);
+    var signingInput = parts[0] + "." + parts[1];
+    var sig = _b64urlDecode(parts[2]);
+    var verifyOpts = { key: keyObject };
+    if (params.padding !== undefined) verifyOpts.padding = params.padding;
+    if (params.saltLength !== undefined) verifyOpts.saltLength = params.saltLength;
+    if (params.dsaEncoding !== undefined) verifyOpts.dsaEncoding = params.dsaEncoding;
+    var verified = nodeCrypto.verify(params.hash, Buffer.from(signingInput, "ascii"), verifyOpts, sig);
+    if (!verified) {
+      throw new OAuthError("auth-oauth/bad-signature", "ID token signature verification failed");
+    }
+
+    // Claim validation.
+    var now = Math.floor(Date.now() / 1000);
+    var skewSec = Math.floor(clockSkewMs / 1000);
+    if (typeof payload.exp !== "number" || payload.exp + skewSec < now) {
+      throw new OAuthError("auth-oauth/expired", "ID token expired (exp=" + payload.exp + ", now=" + now + ")");
+    }
+    if (typeof payload.iat === "number" && payload.iat - skewSec > now) {
+      throw new OAuthError("auth-oauth/iat-future", "ID token iat is in the future");
+    }
+    if (typeof payload.nbf === "number" && payload.nbf - skewSec > now) {
+      throw new OAuthError("auth-oauth/nbf-future", "ID token nbf is in the future");
+    }
+    if (issuer && payload.iss !== issuer) {
+      throw new OAuthError("auth-oauth/iss-mismatch",
+        "ID token iss '" + payload.iss + "' does not match expected '" + issuer + "'");
+    }
+    var aud = Array.isArray(payload.aud) ? payload.aud : (payload.aud ? [payload.aud] : []);
+    if (aud.indexOf(clientId) === -1) {
+      throw new OAuthError("auth-oauth/aud-mismatch",
+        "ID token aud does not contain clientId '" + clientId + "'");
+    }
+    if (vopts.nonce && !vopts.skipNonceCheck) {
+      if (payload.nonce !== vopts.nonce) {
+        throw new OAuthError("auth-oauth/nonce-mismatch",
+          "ID token nonce mismatch (replay protection)");
+      }
+    }
+    return { header: header, claims: payload };
+  }
+
+  return {
+    authorizationUrl:    authorizationUrl,
+    exchangeCode:        exchangeCode,
+    refreshAccessToken:  refreshAccessToken,
+    fetchUserInfo:       fetchUserInfo,
+    revokeToken:         revokeToken,
+    verifyIdToken:       verifyIdToken,
+    discover:            _discover,
+    // Diagnostic / power-user surface
+    issuer:              issuer,
+    clientId:            clientId,
+    redirectUri:         redirectUri,
+    scope:               scope,
+    isOidc:              isOidc,
+  };
+}
+
+module.exports = {
+  create:                create,
+  PRESETS:               PRESETS,
+  OAuthError:            OAuthError,
+  DEFAULT_ACCEPTED_ALGS: DEFAULT_ACCEPTED_ALGS,
+  // Internal helpers exposed for tests
+  _generatePkce:         _generatePkce,
+  _generateRandomToken:  _generateRandomToken,
+  _b64urlEncode:         _b64urlEncode,
+  _b64urlDecode:         _b64urlDecode,
+  _verifyParamsForAlg:   _verifyParamsForAlg,
+};