@fluixi/oauth2 1.0.0-alpha.1

package/dist/verify.mjs

@@ -0,0 +1,590 @@
+/*! @fluixi/oauth2 v1.0.0-alpha.1 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+import {
+  OAuthError
+} from "./chunk-4NSOGPLM.mjs";
+import "./chunk-25WE6UWI.mjs";
+
+// src/client-auth.ts
+var CANONICAL = {
+  basic: "client_secret_basic",
+  body: "client_secret_post",
+  client_secret_basic: "client_secret_basic",
+  client_secret_post: "client_secret_post",
+  private_key_jwt: "private_key_jwt",
+  none: "none"
+};
+function resolveMethod(auth) {
+  if (auth.method) return CANONICAL[auth.method] ?? "client_secret_basic";
+  if (auth.privateKey) return "private_key_jwt";
+  return auth.clientSecret ? "client_secret_basic" : "none";
+}
+function assertUsable(auth, who) {
+  if (!auth.clientId) throw new Error(`[fluixi/oauth2] ${who} needs a clientId.`);
+  const method = resolveMethod(auth);
+  if (method === "private_key_jwt" && !auth.privateKey) {
+    throw new Error(
+      `[fluixi/oauth2] ${who}: private_key_jwt needs \`privateKey\`, the JWK whose public half the provider holds.`
+    );
+  }
+  if ((method === "client_secret_basic" || method === "client_secret_post") && !auth.clientSecret) {
+    throw new Error(
+      `[fluixi/oauth2] ${who}: ${method} needs a \`clientSecret\`. A public client should use \`method: 'none'\`, which PKCE is what protects.`
+    );
+  }
+  return method;
+}
+async function loadJose() {
+  try {
+    return await import("./browser-ONMHX3Z3.mjs");
+  } catch {
+    throw new OAuthError(
+      "private_key_jwt needs `jose`. Install it: npm i jose. It is an optional peer, so a client using a secret does not carry it.",
+      "jose_missing"
+    );
+  }
+}
+async function signAssertion(auth, endpoint) {
+  const jose = await loadJose();
+  const alg = auth.assertionAlgorithm ?? "RS256";
+  const key = await jose.importJWK(auth.privateKey, alg);
+  const kid = auth.keyId ?? auth.privateKey.kid;
+  return new jose.SignJWT({}).setProtectedHeader(kid ? { alg, kid } : { alg }).setIssuer(auth.clientId).setSubject(auth.clientId).setAudience(endpoint).setJti(crypto.randomUUID()).setIssuedAt().setExpirationTime("1m").sign(key);
+}
+async function applyClientAuth(auth, endpoint, headers, form) {
+  switch (resolveMethod(auth)) {
+    case "client_secret_basic": {
+      const pair = `${encodeURIComponent(auth.clientId)}:${encodeURIComponent(auth.clientSecret)}`;
+      headers.authorization = `Basic ${btoa(pair)}`;
+      break;
+    }
+    case "client_secret_post":
+      form.set("client_id", auth.clientId);
+      form.set("client_secret", auth.clientSecret);
+      break;
+    case "private_key_jwt":
+      form.set("client_id", auth.clientId);
+      form.set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer");
+      form.set("client_assertion", await signAssertion(auth, endpoint));
+      break;
+    case "none":
+      form.set("client_id", auth.clientId);
+      break;
+  }
+}
+
+// src/discovery.ts
+var cache = /* @__PURE__ */ new Map();
+function documentUrl(issuer) {
+  return `${issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+}
+async function discover(issuer, fetcher = fetch) {
+  const cached = cache.get(issuer);
+  if (cached) return cached;
+  const pending = (async () => {
+    let response;
+    try {
+      response = await fetcher(documentUrl(issuer));
+    } catch (cause) {
+      throw new OAuthError(
+        `Could not read the discovery document at ${documentUrl(issuer)}. In a browser this is usually the provider refusing a cross-origin read: give \`endpoints\` directly, or resolve them on a server. (${cause instanceof Error ? cause.message : String(cause)})`,
+        "discovery_unreachable"
+      );
+    }
+    if (!response.ok) {
+      throw new OAuthError(
+        `Discovery failed for ${issuer}: ${response.status}`,
+        "discovery_failed"
+      );
+    }
+    const doc = await response.json();
+    if (!doc.authorization_endpoint || !doc.token_endpoint) {
+      throw new OAuthError(
+        `${issuer} published a discovery document with no authorization or token endpoint.`,
+        "discovery_incomplete"
+      );
+    }
+    return {
+      authorization: doc.authorization_endpoint,
+      token: doc.token_endpoint,
+      userinfo: doc.userinfo_endpoint,
+      endSession: doc.end_session_endpoint,
+      jwks: doc.jwks_uri,
+      introspection: doc.introspection_endpoint,
+      revocation: doc.revocation_endpoint,
+      issuer: doc.issuer ?? issuer
+    };
+  })();
+  cache.set(issuer, pending);
+  pending.catch(() => cache.delete(issuer));
+  return pending;
+}
+
+// src/env-credentials.ts
+async function jwkAt(path) {
+  const [{ readFileSync }, { homedir }] = await Promise.all([
+    import("node:fs"),
+    import("node:os")
+  ]);
+  const file = path.replace(/^~(?=$|\/)/, homedir());
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    throw new Error(
+      `[fluixi/oauth2] the key file ${file} cannot be read. A signing key is named by path so it can stay outside the repository.`
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`[fluixi/oauth2] ${file} is not JSON, and a private key is expected as a JWK.`);
+  }
+}
+async function credentialsFromEnv(options) {
+  const source = options.env ?? (typeof process === "undefined" ? {} : process.env);
+  const upper = options.prefix.toUpperCase();
+  const prefer = (options.preferPrefix ?? `${upper}_INTROSPECT`).toUpperCase();
+  const read = (suffix) => source[`${prefer}_${suffix}`] ?? source[`${upper}_${suffix}`];
+  const clientId = read("CLIENT_ID") ?? options.clientId;
+  if (!clientId) return null;
+  const keyPath = read("PRIVATE_KEY");
+  if (keyPath) {
+    return {
+      clientId,
+      privateKey: await jwkAt(keyPath),
+      keyId: read("KEY_ID"),
+      clientAuthMethod: "private_key_jwt",
+      assertionAlgorithm: read("ASSERTION_ALG")
+    };
+  }
+  const clientSecret = read("SECRET") ?? read("CLIENT_SECRET");
+  if (clientSecret) return { clientId, clientSecret };
+  return null;
+}
+function explainCredentials(options) {
+  const upper = options.prefix.toUpperCase();
+  const who = options.label ?? options.prefix;
+  return `This call authenticates its caller, so ${who} needs credentials. For a client with a shared secret, set ${upper}_CLIENT_SECRET. For one registered with a public key (Okta calls this "Public key / Private key"), set ${upper}_PRIVATE_KEY to the path of its private JWK and ${upper}_KEY_ID to the kid the provider lists. Prefix either with ${upper}_INTROSPECT_ to have a different client ask, which Okta requires: a public SPA cannot introspect at all.`;
+}
+
+// src/roles.ts
+var rolesFrom = {
+  /** Keycloak, realm roles. Where it puts them unless a client mapper is configured. */
+  keycloakRealm: (claims) => {
+    const realm = claims.realm_access;
+    return realm?.roles ?? [];
+  },
+  /** Keycloak, roles scoped to one client rather than the realm. */
+  keycloakClient: (clientId) => (claims) => {
+    const all = claims.resource_access;
+    return all?.[clientId]?.roles ?? [];
+  },
+  /** Okta, and anything else using a groups claim. Needs a groups claim on the token. */
+  groups: (claims) => Array.isArray(claims.groups) ? claims.groups : [],
+  /** Cognito, which namespaces the claim. */
+  cognito: (claims) => {
+    const groups = claims["cognito:groups"];
+    return Array.isArray(groups) ? groups : [];
+  },
+  /**
+   * Auth0, which requires a namespaced custom claim added by an action.
+   *
+   * `rolesFrom.namespaced('https://adafri.com/roles')`. Auth0 silently drops a custom claim
+   * that is not a URI, so an empty list here usually means the namespace, not the action.
+   */
+  namespaced: (claim) => (claims) => {
+    const value = claims[claim];
+    return Array.isArray(value) ? value : [];
+  },
+  /** The `scope` claim read as a role list, for a provider issuing no roles at all. */
+  scope: (claims) => typeof claims.scope === "string" ? claims.scope.split(" ") : []
+};
+
+// src/api-guard.ts
+var asList = (value) => value === void 0 ? [] : Array.isArray(value) ? value : [value];
+function refuse(refusal) {
+  const body = { error: refusal.code };
+  if (refusal.detail) body.detail = refusal.detail;
+  return new Response(JSON.stringify(body), {
+    status: refusal.status,
+    headers: { "content-type": "application/json" }
+  });
+}
+function createApiGuard(options) {
+  const answer = (refusal, request) => {
+    const response = options.onRefused ? options.onRefused(refusal, request) : refuse(refusal);
+    if (refusal.status === 401 && !response.headers.has("www-authenticate")) {
+      response.headers.set("www-authenticate", `Bearer error="${refusal.code}"`);
+    }
+    return response;
+  };
+  const rolesOf = (claims, what) => {
+    if (!options.roles) {
+      throw new Error(
+        `[fluixi/oauth2] this route requires ${what}, but createApiGuard was given no \`roles\`. Providers disagree on where roles live, so there is no default: pass one of \`rolesFrom\`, or a function reading the claim your provider uses.`
+      );
+    }
+    return options.roles(claims);
+  };
+  return (handler, requirements = {}) => async (request) => {
+    let claims;
+    try {
+      claims = await options.verify.fromRequest(request);
+    } catch (cause) {
+      const code = cause instanceof TokenError ? cause.code : "invalid_token";
+      return answer({ status: 401, code }, request);
+    }
+    const wanted = asList(requirements.role);
+    if (wanted.length) {
+      const held = rolesOf(claims, "a role");
+      if (!wanted.some((role) => held.includes(role))) {
+        return answer(
+          {
+            status: 403,
+            code: "insufficient_role",
+            detail: `needs ${wanted.length > 1 ? "one of " : ""}${wanted.join(", ")}`,
+            claims
+          },
+          request
+        );
+      }
+    }
+    if (requirements.allRoles?.length) {
+      const held = rolesOf(claims, "roles");
+      const missing = requirements.allRoles.filter((role) => !held.includes(role));
+      if (missing.length) {
+        return answer(
+          { status: 403, code: "insufficient_role", detail: `needs ${missing.join(", ")}`, claims },
+          request
+        );
+      }
+    }
+    const scopes = asList(requirements.scope);
+    if (scopes.length) {
+      const held = typeof claims.scope === "string" ? claims.scope.split(" ") : [];
+      if (!scopes.some((scope) => held.includes(scope))) {
+        return answer(
+          {
+            status: 403,
+            code: "insufficient_scope",
+            detail: `needs ${scopes.length > 1 ? "one of " : ""}${scopes.join(", ")}`,
+            claims
+          },
+          request
+        );
+      }
+    }
+    if (requirements.require) {
+      const verdict = requirements.require(claims, request);
+      if (verdict !== true) {
+        return answer(
+          {
+            status: 403,
+            code: "forbidden",
+            detail: typeof verdict === "string" ? verdict : void 0,
+            claims
+          },
+          request
+        );
+      }
+    }
+    return handler(request, claims);
+  };
+}
+
+// src/verify.ts
+var TokenError = class extends OAuthError {
+  constructor(message, code = "invalid_token") {
+    super(message, code);
+    this.name = "TokenError";
+  }
+};
+function bearerOf(request) {
+  const header = request.headers.get("authorization");
+  if (!header) return null;
+  const match = header.match(/^(?:Bearer|DPoP)\s+(.+)$/i);
+  return match ? match[1].trim() : null;
+}
+async function loadJose2() {
+  try {
+    return await import("./browser-ONMHX3Z3.mjs");
+  } catch {
+    throw new OAuthError(
+      "Token verification needs `jose`. Install it: npm i jose. It is an optional peer so an app that does not verify does not carry it.",
+      "jose_missing"
+    );
+  }
+}
+function createTokenVerifier(options) {
+  const issuers = (Array.isArray(options.issuer) ? options.issuer : [options.issuer]).filter(Boolean);
+  if (!issuers.length) {
+    throw new Error("[fluixi/oauth2] createTokenVerifier needs an issuer to accept tokens from.");
+  }
+  const discoveryIssuer = issuers[0];
+  if (options.audience === void 0) {
+    throw new Error(
+      "[fluixi/oauth2] createTokenVerifier needs an audience, or `audience: false` to say this service really does accept a token minted for any client of the issuer."
+    );
+  }
+  if (options.audience === false && options.authorizedParty === void 0) {
+    console.warn(
+      "[fluixi/oauth2] This verifier checks neither `aud` nor `azp`, so a token minted for any client of the issuer is accepted. Set `authorizedParty` if that is not what you meant."
+    );
+  }
+  const algorithms = options.algorithms ?? ["RS256"];
+  if (algorithms.some((alg) => !alg || alg.toLowerCase() === "none")) {
+    throw new Error("[fluixi/oauth2] `none` is not a signing algorithm and cannot be accepted.");
+  }
+  let keys = null;
+  async function keySet() {
+    if (keys) return keys;
+    const jose = await loadJose2();
+    if (options.jwks) {
+      keys = jose.createLocalJWKSet(options.jwks);
+      return keys;
+    }
+    let uri = options.jwksUri;
+    if (!uri) {
+      const endpoints = await discover(discoveryIssuer);
+      uri = endpoints.jwks;
+    }
+    if (!uri) {
+      throw new OAuthError(
+        `${discoveryIssuer} published no jwks_uri. Give the verifier one directly.`,
+        "no_jwks"
+      );
+    }
+    keys = jose.createRemoteJWKSet(new URL(uri));
+    return keys;
+  }
+  const checkProof = async (claims, token, request) => {
+    const jose = await loadJose2();
+    const { boundKeyOf, thumbprintOf } = await import("./dpop-LVPWWADA.mjs");
+    const bound = boundKeyOf(claims);
+    if (!bound) {
+      throw new TokenError(
+        "This token is not bound to a key, and this service requires binding.",
+        "token_not_bound"
+      );
+    }
+    const proof = request.headers.get("dpop");
+    if (!proof) throw new TokenError("The request carried no DPoP proof.", "missing_dpop_proof");
+    let payload;
+    let header;
+    try {
+      const result = await jose.jwtVerify(proof, jose.EmbeddedJWK, { typ: "dpop+jwt" });
+      payload = result.payload;
+      header = result.protectedHeader;
+    } catch (cause) {
+      throw new TokenError(
+        `The DPoP proof did not verify: ${cause instanceof Error ? cause.message : String(cause)}`,
+        "invalid_dpop_proof"
+      );
+    }
+    const presented = await thumbprintOf(header.jwk);
+    if (presented !== bound) {
+      throw new TokenError(
+        "The DPoP proof was signed with a different key from the one this token is bound to.",
+        "dpop_key_mismatch"
+      );
+    }
+    const url = new URL(request.url);
+    url.search = "";
+    url.hash = "";
+    if (payload.htm !== request.method.toUpperCase()) {
+      throw new TokenError("The DPoP proof was made for a different method.", "invalid_dpop_proof");
+    }
+    if (payload.htu !== url.toString()) {
+      throw new TokenError("The DPoP proof was made for a different URL.", "invalid_dpop_proof");
+    }
+    if (typeof payload.ath === "string") {
+      const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
+      let binary = "";
+      for (const byte of new Uint8Array(digest)) binary += String.fromCharCode(byte);
+      const expected = btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+      if (payload.ath !== expected) {
+        throw new TokenError("The DPoP proof was made for a different token.", "invalid_dpop_proof");
+      }
+    }
+    const age = Math.abs(Date.now() / 1e3 - payload.iat);
+    if (!Number.isFinite(age) || age > (options.dpopProofAgeSec ?? 10)) {
+      throw new TokenError("The DPoP proof is too old to accept.", "invalid_dpop_proof");
+    }
+  };
+  const verify = async (token, request) => {
+    if (!token) throw new TokenError("No token to verify.", "no_token");
+    const jose = await loadJose2();
+    let payload;
+    try {
+      ({ payload } = await jose.jwtVerify(token, await keySet(), {
+        // jose takes a list and accepts any of them, which is what a provider naming
+        // itself two ways needs.
+        issuer: issuers,
+        ...options.audience === false ? {} : { audience: options.audience },
+        algorithms,
+        clockTolerance: options.clockToleranceSec ?? 5
+      }));
+    } catch (cause) {
+      throw new TokenError(
+        `The token was not accepted: ${cause instanceof Error ? cause.message : String(cause)}`
+      );
+    }
+    if (options.authorizedParty !== void 0) {
+      const allowed = Array.isArray(options.authorizedParty) ? options.authorizedParty : [options.authorizedParty];
+      const issuedTo = payload.azp ?? payload.client_id;
+      if (typeof issuedTo !== "string" || !allowed.includes(issuedTo)) {
+        throw new TokenError("The token was issued to a different client.", "invalid_azp");
+      }
+    }
+    if (options.dpop) {
+      if (!request) {
+        throw new Error(
+          "[fluixi/oauth2] `dpop: true` needs the request to read its proof. Use `verify.fromRequest(request)` rather than verifying a bare token."
+        );
+      }
+      await checkProof(payload, token, request);
+    }
+    if (options.require) {
+      const verdict = options.require(payload);
+      if (verdict !== true) {
+        throw new TokenError(
+          typeof verdict === "string" ? verdict : "The token did not meet this service's requirements.",
+          "insufficient_claims"
+        );
+      }
+    }
+    return payload;
+  };
+  const verifier = verify;
+  verifier.bearerOf = bearerOf;
+  verifier.fromRequest = async (request) => {
+    const token = verifier.bearerOf(request);
+    if (!token) {
+      throw new TokenError("The request carried no bearer token.", "no_token");
+    }
+    return verify(token, request);
+  };
+  return verifier;
+}
+function createTokenIntrospector(options) {
+  const issuers = (Array.isArray(options.issuer) ? options.issuer : [options.issuer]).filter(Boolean);
+  if (!issuers.length) {
+    throw new Error("[fluixi/oauth2] createTokenIntrospector needs an issuer.");
+  }
+  const discoveryIssuer = issuers[0];
+  const auth = {
+    clientId: options.clientId,
+    method: options.clientAuthMethod,
+    clientSecret: options.clientSecret,
+    privateKey: options.privateKey,
+    keyId: options.keyId,
+    assertionAlgorithm: options.assertionAlgorithm
+  };
+  if (resolveMethod(auth) === "none") {
+    throw new Error(
+      "[fluixi/oauth2] createTokenIntrospector needs credentials: a secret, or private_key_jwt with a key."
+    );
+  }
+  assertUsable(auth, "createTokenIntrospector");
+  if (options.audience === void 0) {
+    throw new Error(
+      "[fluixi/oauth2] createTokenIntrospector needs an audience, or `audience: false` to say this service accepts a token minted for any client of the issuer."
+    );
+  }
+  const ttl = options.cacheMs ?? 0;
+  const cache2 = /* @__PURE__ */ new Map();
+  let endpoint = options.introspectionEndpoint ?? null;
+  async function resolveEndpoint() {
+    if (endpoint) return endpoint;
+    const endpoints = await discover(discoveryIssuer);
+    if (!endpoints.introspection) {
+      throw new OAuthError(
+        `${discoveryIssuer} published no introspection_endpoint. Give the introspector one directly, or verify JWTs with createTokenVerifier.`,
+        "no_introspection"
+      );
+    }
+    endpoint = endpoints.introspection;
+    return endpoint;
+  }
+  const introspect = async (token) => {
+    if (!token) throw new TokenError("No token to verify.", "no_token");
+    const cached = cache2.get(token);
+    if (cached && cached.until > Date.now()) return cached.claims;
+    const url = await resolveEndpoint();
+    const headers = {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json"
+    };
+    const form = new URLSearchParams({ token, token_type_hint: "access_token" });
+    await applyClientAuth(auth, url, headers, form);
+    const response = await fetch(url, { method: "POST", headers, body: form.toString() });
+    if (!response.ok) {
+      const method = resolveMethod(auth);
+      const check = method === "private_key_jwt" ? `Check clientId, and that the provider holds the public half of this key${auth.keyId ? ` under kid ${auth.keyId}` : ""}. A key registered to a different client than clientId is refused this way.` : "Check clientId and clientSecret.";
+      const said = await response.text().catch(() => "");
+      throw new OAuthError(
+        `The introspection endpoint refused this service: ${response.status}. ${check}${said ? ` It said: ${said}` : ""}`,
+        "introspection_failed"
+      );
+    }
+    const body = await response.json();
+    if (body.active !== true) {
+      throw new TokenError(
+        "The provider reports this token is not active. If it was just issued, check that this client is in the token audience: some providers refuse to introspect a token minted for someone else and say only this.",
+        "inactive_token"
+      );
+    }
+    if (typeof body.iss === "string" && !issuers.includes(body.iss)) {
+      throw new TokenError("The token was issued by a different issuer.", "invalid_issuer");
+    }
+    if (options.audience !== false && body.aud !== void 0) {
+      const wanted = Array.isArray(options.audience) ? options.audience : [options.audience];
+      const got = Array.isArray(body.aud) ? body.aud : [body.aud];
+      if (!got.some((a) => wanted.includes(a))) {
+        throw new TokenError("The token was minted for a different audience.", "invalid_audience");
+      }
+    }
+    if (options.authorizedParty !== void 0) {
+      const allowed = Array.isArray(options.authorizedParty) ? options.authorizedParty : [options.authorizedParty];
+      const issuedTo = body.client_id ?? body.azp;
+      if (!issuedTo || !allowed.includes(issuedTo)) {
+        throw new TokenError("The token was issued to a different client.", "invalid_azp");
+      }
+    }
+    if (options.require) {
+      const verdict = options.require(body);
+      if (verdict !== true) {
+        throw new TokenError(
+          typeof verdict === "string" ? verdict : "The token did not meet this service's requirements.",
+          "insufficient_claims"
+        );
+      }
+    }
+    if (ttl > 0) {
+      if (cache2.size > 500) {
+        const now = Date.now();
+        for (const [key, entry] of cache2) if (entry.until <= now) cache2.delete(key);
+        if (cache2.size > 500) cache2.delete(cache2.keys().next().value);
+      }
+      cache2.set(token, { claims: body, until: Date.now() + ttl });
+    }
+    return body;
+  };
+  const verifier = introspect;
+  verifier.bearerOf = bearerOf;
+  verifier.fromRequest = async (request) => {
+    const token = bearerOf(request);
+    if (!token) throw new TokenError("The request carried no bearer token.", "no_token");
+    return introspect(token);
+  };
+  return verifier;
+}
+export {
+  TokenError,
+  createApiGuard,
+  createTokenIntrospector,
+  createTokenVerifier,
+  credentialsFromEnv,
+  explainCredentials,
+  rolesFrom
+};