@kleora-io/node 0.0.0 → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1057 @@
+'use strict';
+
+var jose = require('jose');
+
+// src/errors.ts
+var KleoraError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "KleoraError";
+    this.code = code;
+  }
+};
+var TokenError = class extends KleoraError {
+  constructor(code, message, options) {
+    super(code, message, options);
+    this.name = "TokenError";
+  }
+};
+var LoginRequired = class extends KleoraError {
+  constructor(message) {
+    super("login_required", message);
+    this.name = "LoginRequired";
+  }
+};
+var EnvironmentMismatch = class extends KleoraError {
+  constructor(message) {
+    super("environment_mismatch", message);
+    this.name = "EnvironmentMismatch";
+  }
+};
+var ApiError = class extends KleoraError {
+  type;
+  status;
+  detail;
+  errors;
+  problem;
+  /**
+   * The correlation id of the response that failed.
+   *
+   * The one field a support conversation needs: it is what ties the error a
+   * customer pasted to the request in our logs. Read from the document's
+   * `request_id` first and from the `X-Request-Id` response header otherwise,
+   * because the header is all there is when the body is not a problem document
+   * — an intermediary's HTML 502 — or when the deployment answering predates
+   * the member. `undefined` only when neither carried one.
+   */
+  requestId;
+  constructor(type, status, detail, errors, problem2, requestId) {
+    super("api_error", detail ?? type);
+    this.name = "ApiError";
+    this.type = type;
+    this.status = status;
+    this.detail = detail;
+    this.errors = errors;
+    this.problem = problem2;
+    this.requestId = requestId;
+  }
+};
+
+// src/environment.ts
+var SANDBOX_SUFFIX = "-sandbox";
+var PORT_SUFFIX = /:\d+$/;
+function classify(host) {
+  const first = host.toLowerCase().replace(PORT_SUFFIX, "").split(".")[0] ?? "";
+  return first.length > SANDBOX_SUFFIX.length && first.endsWith(SANDBOX_SUFFIX) ? "sandbox" : "production";
+}
+function parseAbsolute(name, value) {
+  const complaint = `${name} must be an absolute http(s) URL, got '${value}'`;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new KleoraError("invalid_configuration", complaint);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new KleoraError("invalid_configuration", complaint);
+  }
+  return url;
+}
+var KEY_PREFIXES = {
+  production: "kl_live_",
+  sandbox: "kl_test_"
+};
+function classifyKey(apiKey) {
+  if (apiKey.startsWith(KEY_PREFIXES.production)) return "production";
+  if (apiKey.startsWith(KEY_PREFIXES.sandbox)) return "sandbox";
+  return null;
+}
+function redactKey(apiKey) {
+  const kind = classifyKey(apiKey);
+  if (kind === null) return "[redacted]";
+  return apiKey.slice(0, KEY_PREFIXES[kind].length + 8);
+}
+function assertKeyMatches(apiKey, kind, what) {
+  const keyKind = classifyKey(apiKey);
+  if (keyKind === null) {
+    throw new KleoraError(
+      "invalid_configuration",
+      `the API key does not start with '${KEY_PREFIXES.production}' or '${KEY_PREFIXES.sandbox}', so the environment it belongs to cannot be checked`
+    );
+  }
+  if (keyKind !== kind) {
+    throw new EnvironmentMismatch(
+      `the API key ${redactKey(apiKey)} is a ${keyKind} key but ${what} is ${kind}; sandbox and production must not be mixed`
+    );
+  }
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+var USER_AGENT = `kleora-node/${VERSION}`;
+
+// src/jwks.ts
+var DEFAULT_TTL_SECONDS = 300;
+var MIN_REFETCH_SECONDS = 60;
+var STALE_MULTIPLIER = 2;
+var DEFAULT_TIMEOUT_MS = 5e3;
+var monotonic = () => performance.now();
+var JwksCache = class {
+  url;
+  doFetch;
+  now;
+  ttlOverride;
+  floor;
+  timeout;
+  set = null;
+  /** When a fetch was last *attempted*, successful or not. */
+  lastAttempt = null;
+  /** When a fetch last failed, or `null` if the last one succeeded. */
+  lastFailure = null;
+  /** Why it last failed, so `get` can report the outage rather than guess. */
+  lastError = null;
+  /** In-flight fetch, so concurrent verifications share one request. */
+  inFlight = null;
+  imported = /* @__PURE__ */ new Map();
+  /** Fetches performed, for the tests that count them. */
+  fetches = 0;
+  constructor(issuer, options = {}) {
+    this.url = new URL("/.well-known/jwks.json", issuer).href;
+    this.doFetch = options.fetch ?? globalThis.fetch;
+    this.now = options.now ?? monotonic;
+    this.ttlOverride = options.ttl === void 0 ? void 0 : options.ttl * 1e3;
+    this.floor = (options.minRefetchInterval ?? MIN_REFETCH_SECONDS) * 1e3;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+  }
+  /**
+   * The key `kid` names, refetching within the rules above.
+   *
+   * Throws `TokenError('unknown_kid')` when the issuer does not publish it —
+   * which is also the answer when the endpoint is unreachable and the cached
+   * set is past 2 × TTL, because at that point the SDK cannot tell an
+   * unpublished key from an unfetchable one and must fail closed.
+   */
+  async get(kid) {
+    if (this.set === null) {
+      await this.refresh();
+    } else if (this.age() >= this.set.ttl && this.mayRetry()) {
+      await this.refreshQuietly();
+    }
+    if (this.lookup(kid) === void 0 && this.mayRefetch()) {
+      await this.refreshQuietly();
+    }
+    const jwk = this.lookup(kid);
+    if (jwk === void 0) {
+      if (!this.usable()) {
+        throw this.lastError ?? new TokenError("issuer_unavailable", `${this.url} could not be read`);
+      }
+      throw new TokenError(
+        "unknown_kid",
+        `the issuer at ${this.url} publishes no key with kid '${kid}'`
+      );
+    }
+    const cached = this.imported.get(kid);
+    if (cached !== void 0) return cached;
+    const key = await jose.importJWK(jwk, "ES256");
+    this.imported.set(kid, key);
+    return key;
+  }
+  /** Whether the cached set may still answer at all. */
+  usable() {
+    return this.set !== null && this.age() < this.set.ttl * STALE_MULTIPLIER;
+  }
+  lookup(kid) {
+    return this.usable() ? this.set?.keys.get(kid) : void 0;
+  }
+  age() {
+    return this.set === null ? Number.POSITIVE_INFINITY : this.now() - this.set.at;
+  }
+  /**
+   * Whether an unknown `kid` may force a fetch.
+   *
+   * The floor counts from the last *attempt*, not the last success: an issuer
+   * that is answering 500 would otherwise be refetched on every token, and
+   * the whole point of the floor is that whoever sends the token does not get
+   * to decide how often this process calls its issuer.
+   */
+  mayRefetch() {
+    return this.lastAttempt === null || this.now() - this.lastAttempt >= this.floor;
+  }
+  /**
+   * Whether an expired TTL may be refreshed.
+   *
+   * The document's `max-age` is the issuer's own instruction and is obeyed as
+   * given, floor or no floor — a deployment that publishes `max-age=30` means
+   * thirty seconds. What is throttled is *retrying a failure*: an endpoint
+   * that is down would otherwise be asked once per verification for as long
+   * as the stale window lasts.
+   */
+  mayRetry() {
+    return this.lastFailure === null || this.now() - this.lastFailure >= this.floor;
+  }
+  /** Refresh, tolerating a failure. The callers decide whether to try. */
+  async refreshQuietly() {
+    try {
+      await this.refresh();
+    } catch {
+    }
+  }
+  async refresh() {
+    this.inFlight ??= this.fetchKeys().finally(() => {
+      this.inFlight = null;
+    });
+    await this.inFlight;
+  }
+  async fetchKeys() {
+    this.lastAttempt = this.now();
+    this.lastFailure = this.lastAttempt;
+    this.fetches += 1;
+    try {
+      const response = await this.doFetch(this.url, {
+        headers: { Accept: "application/json", "User-Agent": USER_AGENT },
+        // Bounded here rather than left to the runtime: undici's default is
+        // 300 s, and a coalesced refresh makes that every concurrent
+        // verification's wait, not just the first one's.
+        signal: AbortSignal.timeout(this.timeout)
+      });
+      if (!response.ok) {
+        throw new TokenError(
+          "issuer_unavailable",
+          `${this.url} answered ${String(response.status)}`
+        );
+      }
+      const document = await response.json();
+      const keys = /* @__PURE__ */ new Map();
+      if (typeof document === "object" && document !== null) {
+        const listed = document.keys;
+        if (Array.isArray(listed)) {
+          for (const entry of listed) {
+            if (typeof entry.kid === "string") keys.set(entry.kid, entry);
+          }
+        }
+      }
+      if (keys.size === 0) {
+        throw new TokenError("issuer_unavailable", `${this.url} published no usable key`);
+      }
+      this.set = { keys, at: this.now(), ttl: this.ttlOverride ?? maxAge(response) };
+      this.lastFailure = null;
+      this.lastError = null;
+      for (const kid of [...this.imported.keys()]) {
+        if (!keys.has(kid)) this.imported.delete(kid);
+      }
+    } catch (cause) {
+      const error = cause instanceof TokenError ? cause : new TokenError("issuer_unavailable", `${this.url} could not be read: ${reason(cause)}`, {
+        cause
+      });
+      this.lastError = error;
+      throw error;
+    }
+  }
+};
+function maxAge(response) {
+  const header = response.headers.get("cache-control");
+  const match = header === null ? null : /(?:^|[\s,])max-age\s*=\s*(\d+)/i.exec(header);
+  const seconds = match?.[1] === void 0 ? Number.NaN : Number(match[1]);
+  return (Number.isFinite(seconds) && seconds > 0 ? seconds : DEFAULT_TTL_SECONDS) * 1e3;
+}
+function reason(cause) {
+  if (cause instanceof Error) {
+    return cause.name === "TimeoutError" ? "the request timed out" : cause.message;
+  }
+  return "unknown error";
+}
+var caches = /* @__PURE__ */ new Map();
+function jwksFor(issuer, options = {}) {
+  const url = new URL("/.well-known/jwks.json", issuer).href;
+  let cache = caches.get(url);
+  if (cache === void 0) {
+    cache = new JwksCache(issuer, options);
+    caches.set(url, cache);
+  }
+  return cache;
+}
+function clearJwksCaches() {
+  caches.clear();
+}
+var CLOCK_TOLERANCE_SECONDS = 60;
+var ALGORITHM = "ES256";
+var ACCESS_TOKEN_TYPES = /* @__PURE__ */ new Set(["at+jwt", "application/at+jwt"]);
+var BEARER = /^Bearer +(?<token>[^\s]+)$/i;
+async function verifyAccessToken(token, options) {
+  const issuer = parseAbsolute("issuer", options.issuer);
+  const expectedIssuer = trimTrailingSlash(options.issuer);
+  const tolerance = clockTolerance(options);
+  const keys = options.jwks ?? resolverFor(options);
+  const header = readHeader(token);
+  if (header.alg !== ALGORITHM) {
+    throw new TokenError(
+      "malformed",
+      `the token is signed with '${String(header.alg)}'; this issuer signs ${ALGORITHM} only`
+    );
+  }
+  const typ = typeof header.typ === "string" ? header.typ.toLowerCase() : null;
+  if (typ === null || !ACCESS_TOKEN_TYPES.has(typ)) {
+    throw new TokenError(
+      "invalid_type",
+      `the token header's typ is ${typ === null ? "absent or not a string" : `'${typ}'`}; an access token is 'at+jwt' (RFC 9068 \xA72.1)`
+    );
+  }
+  if (typeof header.kid !== "string" || header.kid === "") {
+    throw new TokenError("malformed", "the token header names no kid");
+  }
+  const key = await keys.get(header.kid);
+  let payload;
+  try {
+    const verified = await jose.compactVerify(token, key, { algorithms: [ALGORITHM] });
+    payload = new TextDecoder().decode(verified.payload);
+  } catch (cause) {
+    throw new TokenError("invalid_signature", `the token's signature does not verify`, {
+      cause
+    });
+  }
+  const claims = parseClaims(payload);
+  if (claims.iss !== expectedIssuer) {
+    throw new TokenError(
+      "issuer_mismatch",
+      `the token's iss is '${claims.iss}', expected '${expectedIssuer}'`
+    );
+  }
+  if (!claims.aud.includes(options.audience)) {
+    throw new TokenError(
+      "audience_mismatch",
+      `the token's aud ${JSON.stringify(claims.aud)} does not contain '${options.audience}'`
+    );
+  }
+  const now = Math.floor((options.now?.() ?? Date.now()) / 1e3);
+  if (now > claims.exp + tolerance) {
+    throw new TokenError(
+      "expired",
+      `the token expired at ${String(claims.exp)}, now ${String(now)} (clock tolerance ${String(tolerance)}s)`
+    );
+  }
+  if (claims.iat > now + tolerance) {
+    throw new TokenError(
+      "expired",
+      `the token was issued at ${String(claims.iat)}, in the future of ${String(now)} (clock tolerance ${String(tolerance)}s)`
+    );
+  }
+  const kind = classify(issuer.host);
+  if (claims.env !== kind) {
+    throw new EnvironmentMismatch(
+      `the token's env claim is '${claims.env}' but the issuer '${options.issuer}' is ${kind}`
+    );
+  }
+  return claims;
+}
+async function authenticate(request, options) {
+  return verifyAccessToken(bearerOf(request), options);
+}
+function bearerOf(request) {
+  const header = request.headers.authorization;
+  if (typeof header !== "string" || header.trim() === "") {
+    throw new LoginRequired("the request carries no Authorization header");
+  }
+  const token = BEARER.exec(header.trim())?.groups?.["token"];
+  if (token === void 0) {
+    throw new LoginRequired("the Authorization header is not a Bearer credential");
+  }
+  return token;
+}
+function resolverFor(options) {
+  const cacheOptions = {};
+  if (options.fetch !== void 0) cacheOptions.fetch = options.fetch;
+  return jwksFor(options.issuer, cacheOptions);
+}
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+function clockTolerance(options) {
+  const value = options.clockTolerance ?? CLOCK_TOLERANCE_SECONDS;
+  if (!Number.isFinite(value) || value < 0) {
+    throw new KleoraError(
+      "invalid_configuration",
+      `clockTolerance must be a finite number of seconds >= 0, got ${String(value)}`
+    );
+  }
+  return value;
+}
+function assertVerifyOptions(options) {
+  parseAbsolute("issuer", options.issuer);
+  if (typeof options.audience !== "string" || options.audience === "") {
+    throw new KleoraError(
+      "invalid_configuration",
+      "audience must be a non-empty string: the environment's api_audience, or the client id when it declares none"
+    );
+  }
+  clockTolerance(options);
+}
+function readHeader(token) {
+  try {
+    return jose.decodeProtectedHeader(token);
+  } catch (cause) {
+    throw new TokenError("malformed", "the token is not a compact JWS", { cause });
+  }
+}
+function parseClaims(payload) {
+  let document;
+  try {
+    document = JSON.parse(payload);
+  } catch (cause) {
+    throw new TokenError("malformed", "the token payload is not JSON", { cause });
+  }
+  if (typeof document !== "object" || document === null || Array.isArray(document)) {
+    throw new TokenError("malformed", "the token payload is not a JSON object");
+  }
+  const claims = document;
+  const audience = claims["aud"];
+  const aud = typeof audience === "string" ? [audience] : Array.isArray(audience) && audience.every((entry) => typeof entry === "string") ? audience : null;
+  const required = {
+    iss: string(claims["iss"]),
+    sub: string(claims["sub"]),
+    jti: string(claims["jti"]),
+    client_id: string(claims["client_id"]),
+    scope: string(claims["scope"]),
+    exp: integer(claims["exp"]),
+    iat: integer(claims["iat"])
+  };
+  const env = claims["env"];
+  const missing = Object.entries(required).filter(([, value]) => value === null).map(([name]) => name);
+  if (aud === null) missing.push("aud");
+  if (env !== "sandbox" && env !== "production") missing.push("env");
+  if (missing.length > 0) {
+    throw new TokenError(
+      "malformed",
+      `the token is missing or misdeclares: ${missing.sort().join(", ")}`
+    );
+  }
+  return {
+    ...claims,
+    iss: required.iss,
+    sub: required.sub,
+    aud,
+    exp: required.exp,
+    iat: required.iat,
+    jti: required.jti,
+    client_id: required.client_id,
+    scope: required.scope,
+    env,
+    roles: stringList(claims["roles"]),
+    permissions: stringList(claims["permissions"]),
+    amr: stringList(claims["amr"])
+  };
+}
+var string = (value) => typeof value === "string" ? value : null;
+var integer = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+var stringList = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+
+// src/problem.ts
+var PROBLEM_BASE = "https://kleora.io/problems/";
+var TITLES = {
+  unauthenticated: "Authentication required",
+  "insufficient-permission": "Permission denied",
+  "issuer-unavailable": "Identity provider unavailable"
+};
+function problem(slug, status, detail) {
+  return {
+    type: `${PROBLEM_BASE}${slug}`,
+    title: TITLES[slug] ?? slug,
+    status,
+    detail
+  };
+}
+var isFastify = (response) => typeof response.code === "function";
+function sendProblem(response, document, headers = {}) {
+  const all = {
+    "Content-Type": "application/problem+json",
+    ...document.status === 401 ? { "WWW-Authenticate": "Bearer" } : {},
+    ...headers
+  };
+  if (isFastify(response)) {
+    response.code(document.status);
+    for (const [name, value] of Object.entries(all)) {
+      if (name === "Content-Type") response.type(value);
+      else response.header(name, value);
+    }
+    response.send(document);
+    return;
+  }
+  response.status(document.status);
+  for (const [name, value] of Object.entries(all)) response.setHeader(name, value);
+  response.json(document);
+}
+
+// src/middleware.ts
+var UNAUTHENTICATED = "the request could not be authenticated";
+function refusal(error) {
+  if (error instanceof TokenError && error.code === "issuer_unavailable") {
+    return problem(
+      "issuer-unavailable",
+      503,
+      "the identity provider could not be reached to verify this token"
+    );
+  }
+  if (error instanceof TokenError || error instanceof LoginRequired) {
+    return problem("unauthenticated", 401, UNAUTHENTICATED);
+  }
+  return null;
+}
+function report(options, error, mustLog) {
+  if (options.logger !== void 0) {
+    try {
+      options.logger(error);
+    } catch {
+    }
+    return;
+  }
+  if (mustLog) console.error("[@kleora-io/node]", error);
+}
+var asError = (error) => error instanceof Error ? error : new Error(String(error));
+function express(options) {
+  assertVerifyOptions(options);
+  return (request, response, next) => {
+    void admit(request, response, options).then(
+      (verdict) => {
+        if (verdict.kind === "ok") next();
+        else if (verdict.kind === "internal") next(asError(verdict.error));
+      },
+      (error) => {
+        report(options, error, true);
+        next(asError(error));
+      }
+    ).catch((error) => {
+      report(options, error, true);
+    });
+  };
+}
+function fastify(options) {
+  assertVerifyOptions(options);
+  const plugin = (instance) => {
+    instance.decorateRequest("kleora", null);
+    instance.addHook("onRequest", async (request, reply) => {
+      const verdict = await admit(request, reply, options);
+      if (verdict.kind === "internal") {
+        report(options, verdict.error, true);
+        throw asError(verdict.error);
+      }
+      return verdict.kind === "ok" ? void 0 : reply;
+    });
+    return Promise.resolve();
+  };
+  return Object.assign(plugin, { [/* @__PURE__ */ Symbol.for("skip-override")]: true });
+}
+async function admit(request, response, options) {
+  let claims;
+  try {
+    claims = await authenticate(request, options);
+  } catch (error) {
+    const document = refusal(error);
+    if (document === null) return { kind: "internal", error };
+    report(options, error, false);
+    try {
+      sendProblem(response, document);
+    } catch (failure) {
+      report(options, failure, true);
+    }
+    return { kind: "answered" };
+  }
+  request.kleora = claims;
+  return { kind: "ok" };
+}
+function requirePermission(name) {
+  return (request, response, next) => {
+    const claims = request.kleora;
+    if (claims === void 0 || claims === null) {
+      sendProblem(response, problem("unauthenticated", 401, UNAUTHENTICATED));
+      return;
+    }
+    if (!claims.permissions.includes(name)) {
+      sendProblem(
+        response,
+        problem(
+          "insufficient-permission",
+          403,
+          claims.permissions_truncated === true ? `the token does not carry the permission '${name}'. Its permissions claim was truncated at 200 entries, so this may be a permission the user does hold but the token could not carry; coarser roles are the fix.` : `the token does not carry the permission '${name}'`
+        )
+      );
+      return;
+    }
+    next?.();
+  };
+}
+
+// src/management.ts
+var DEFAULT_BASE_URL = "https://api.kleora.io";
+var PREFIX = "/api/v1";
+var DEFAULT_TIMEOUT_MS2 = 1e4;
+var ManagementClient = class {
+  baseUrl;
+  issuer;
+  #apiKey;
+  #fetch;
+  #timeout;
+  /** The guard, run at most once; a rejection is remembered and re-thrown. */
+  #guard = null;
+  #environment = null;
+  constructor(options) {
+    if (classifyKey(options.apiKey) === null) {
+      throw new KleoraError(
+        "invalid_configuration",
+        `apiKey must start with 'kl_live_' or 'kl_test_'`
+      );
+    }
+    this.#apiKey = options.apiKey;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS2;
+    this.baseUrl = normaliseBase(parseAbsolute("baseUrl", options.baseUrl ?? DEFAULT_BASE_URL).href);
+    this.issuer = options.issuer === void 0 ? null : trimSlash(options.issuer);
+    if (options.issuer !== void 0) {
+      const parsed = parseAbsolute("issuer", options.issuer);
+      assertKeyMatches(
+        options.apiKey,
+        classify(parsed.host),
+        `the configured issuer '${this.issuer}'`
+      );
+    }
+  }
+  /** The key's environment, once the guard has read it. `null` before that. */
+  get environment() {
+    return this.#environment;
+  }
+  get(path, ...args) {
+    return this.#call("GET", path, args[0]);
+  }
+  post(path, ...args) {
+    return this.#call("POST", path, args[0]);
+  }
+  put(path, ...args) {
+    return this.#call("PUT", path, args[0]);
+  }
+  patch(path, ...args) {
+    return this.#call("PATCH", path, args[0]);
+  }
+  delete(path, ...args) {
+    return this.#call("DELETE", path, args[0]);
+  }
+  /** The prefix, and nothing else. The key itself never leaves this object. */
+  toString() {
+    return `ManagementClient(${redactKey(this.#apiKey)} @ ${this.baseUrl})`;
+  }
+  toJSON() {
+    return { apiKey: redactKey(this.#apiKey), baseUrl: this.baseUrl, issuer: this.issuer };
+  }
+  /** `console.log(client)` and `util.inspect` see the same redaction. */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+  async #call(method, path, args) {
+    await this.#ensureGuarded(args);
+    return this.#send(method, path, args);
+  }
+  /**
+   * The environment guard.
+   *
+   * The remote half. The local half — key prefix against the configured issuer
+   * — already ran in the constructor, which is what "no request with the key is
+   * sent" means for a sandbox key aimed at production. This is
+   * one `GET /me`, and it is the authority: the prefix says which *kind* of
+   * environment the key belongs to, and only the server says which environment
+   * that is.
+   */
+  #ensureGuarded(args) {
+    this.#guard ??= this.#runGuard(args).catch((error) => {
+      if (!(error instanceof EnvironmentMismatch)) this.#guard = null;
+      throw error;
+    });
+    return this.#guard;
+  }
+  async #runGuard(args) {
+    const me = await this.#send(
+      "GET",
+      `${PREFIX}/me`,
+      args?.requestId === void 0 ? {} : { requestId: args.requestId }
+    );
+    const environment = me.environment ?? null;
+    if (environment === null) {
+      throw new EnvironmentMismatch(
+        `GET ${PREFIX}/me reported no environment for ${redactKey(this.#apiKey)}`
+      );
+    }
+    assertKeyMatches(this.#apiKey, environment.kind, `its environment '${environment.issuer}'`);
+    if (this.issuer !== null && trimSlash(environment.issuer) !== this.issuer) {
+      throw new EnvironmentMismatch(
+        `the key belongs to '${environment.issuer}' but the client was configured with issuer '${this.issuer}'`
+      );
+    }
+    this.#environment = environment;
+  }
+  async #send(method, path, args) {
+    const url = new URL(this.baseUrl + expand(path, args?.path));
+    for (const [name, value] of queryEntries(args?.query)) url.searchParams.append(name, value);
+    const headers = {
+      Accept: "application/json, application/problem+json",
+      Authorization: `Bearer ${this.#apiKey}`,
+      "User-Agent": USER_AGENT
+    };
+    if (args?.requestId !== void 0) headers["X-Request-Id"] = args.requestId;
+    if (args?.idempotencyKey !== void 0) headers["Idempotency-Key"] = args.idempotencyKey;
+    if (args?.body !== void 0) headers["Content-Type"] = "application/json";
+    const response = await this.#fetch(url, {
+      method,
+      headers,
+      ...args?.body === void 0 ? {} : { body: JSON.stringify(args.body) },
+      signal: deadline(this.#timeout, args?.signal)
+    });
+    if (!response.ok) throw await toApiError(response);
+    if (response.status === 204) return void 0;
+    const text = await response.text();
+    return text === "" ? void 0 : JSON.parse(text);
+  }
+};
+function normaliseBase(value) {
+  const trimmed = trimSlash(value);
+  return trimmed.endsWith(PREFIX) ? trimmed.slice(0, -PREFIX.length) : trimmed;
+}
+var trimSlash = (value) => value.replace(/\/+$/, "");
+function deadline(timeout, signal) {
+  const own = AbortSignal.timeout(timeout);
+  return signal === void 0 ? own : AbortSignal.any([signal, own]);
+}
+function expand(path, params) {
+  return path.replace(/\{([^}]+)\}/g, (_, name) => {
+    const value = params?.[name];
+    if (value === void 0 || value === null) {
+      throw new KleoraError(
+        "invalid_request",
+        `${path} needs the path parameter '${name}'`
+      );
+    }
+    return encodeURIComponent(String(value));
+  });
+}
+function queryEntries(query) {
+  const entries = [];
+  for (const [name, value] of Object.entries(query ?? {})) {
+    if (value === void 0 || value === null) continue;
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (typeof item === "string") entries.push([name, item]);
+      else if (typeof item === "number" || typeof item === "boolean") {
+        entries.push([name, String(item)]);
+      }
+    }
+  }
+  return entries;
+}
+async function toApiError(response) {
+  let document = {};
+  try {
+    const body = await response.json();
+    if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+      document = body;
+    }
+  } catch {
+  }
+  const errors = document["errors"];
+  const problem2 = {
+    document,
+    retryAfter: retryAfterOf(response, document),
+    idempotencyReplayed: response.headers.get("idempotency-replayed")
+  };
+  return new ApiError(
+    typeof document["type"] === "string" ? document["type"] : "about:blank",
+    response.status,
+    typeof document["detail"] === "string" ? document["detail"] : response.statusText === "" ? void 0 : response.statusText,
+    Array.isArray(errors) ? errors : void 0,
+    problem2,
+    requestIdOf(response, document)
+  );
+}
+function requestIdOf(response, document) {
+  const fromDocument = document["request_id"];
+  if (typeof fromDocument === "string" && fromDocument !== "") return fromDocument;
+  return response.headers.get("x-request-id") ?? void 0;
+}
+function retryAfterOf(response, document) {
+  const raw = response.headers.get("retry-after");
+  const trimmed = raw?.trim() ?? "";
+  if (trimmed !== "") {
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds);
+    const at = Date.parse(trimmed);
+    if (Number.isFinite(at)) return Math.max(0, Math.round((at - Date.now()) / 1e3));
+  }
+  const fromDocument = document["retry_after"];
+  return typeof fromDocument === "number" && Number.isFinite(fromDocument) ? fromDocument : null;
+}
+
+// src/account.ts
+var DEFAULT_ACCOUNT_TIMEOUT_MS = 1e4;
+var id = (value) => encodeURIComponent(value);
+var AccountClient = class {
+  /** `{issuer}/account/v1`. */
+  baseUrl;
+  #accessToken;
+  #fetch;
+  #timeout;
+  constructor(options) {
+    const issuer = parseAbsolute("issuer", options.issuer);
+    if (options.accessToken === "") {
+      throw new KleoraError("invalid_configuration", "accessToken must not be empty");
+    }
+    this.baseUrl = `${issuer.href.replace(/\/+$/, "")}/account/v1`;
+    this.#accessToken = options.accessToken;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#timeout = options.timeout ?? DEFAULT_ACCOUNT_TIMEOUT_MS;
+  }
+  /** `GET /profile`. */
+  getProfile() {
+    return this.#send("GET", "/profile");
+  }
+  /** `PATCH /profile` — name, locale, picture; `null` clears one. */
+  updateProfile(changes) {
+    return this.#send("PATCH", "/profile", { body: changes });
+  }
+  /** `GET /email`. */
+  getEmail() {
+    return this.#send("GET", "/email");
+  }
+  /** `POST /email` — mails a confirmation link to the new address. **Sensitive.** */
+  requestEmailChange(email) {
+    return this.#send("POST", "/email", { body: { email } });
+  }
+  /** `POST /email/confirm` — the token from that link. */
+  confirmEmailChange(token) {
+    return this.#send("POST", "/email/confirm", { body: { token } });
+  }
+  /** `POST /email/resend`. */
+  resendVerificationEmail() {
+    return this.#send("POST", "/email/resend");
+  }
+  /** `GET /password` — whether there is one, and the Environment's policy. */
+  getPasswordPolicy() {
+    return this.#send("GET", "/password");
+  }
+  /** `POST /password` — change it, or set one for a person who has none. **Sensitive.** */
+  changePassword(options) {
+    return this.#send("POST", "/password", {
+      body: {
+        new_password: options.newPassword,
+        ...options.currentPassword === void 0 ? {} : { current_password: options.currentPassword }
+      }
+    });
+  }
+  /** `GET /reauth` — what this person can re-authenticate with. */
+  getReauthentication() {
+    return this.#send("GET", "/reauth");
+  }
+  /** `POST /reauth` — a password; opens the five-minute window. */
+  reauthenticate(password) {
+    return this.#send("POST", "/reauth", { body: { password } });
+  }
+  /** `GET /sessions` — live sessions, newest first, one cursor page. */
+  listSessions(options = {}) {
+    return this.#send("GET", "/sessions", { query: { limit: options.limit, cursor: options.cursor } });
+  }
+  /** `DELETE /sessions/{id}`. */
+  revokeSession(sessionId) {
+    return this.#send("DELETE", `/sessions/${id(sessionId)}`);
+  }
+  /** `POST /sessions/revoke-others` — every live session but this token's. */
+  revokeOtherSessions() {
+    return this.#send("POST", "/sessions/revoke-others");
+  }
+  /** `GET /mfa`. */
+  listMfaFactors() {
+    return this.#send("GET", "/mfa");
+  }
+  /** `POST /mfa/enroll/start`. **Sensitive.** */
+  startTotpEnrollment() {
+    return this.#send("POST", "/mfa/enroll/start");
+  }
+  /** `POST /mfa/enroll/confirm` — answers the recovery codes, once. **Sensitive.** */
+  confirmTotpEnrollment(code) {
+    return this.#send("POST", "/mfa/enroll/confirm", { body: { code } });
+  }
+  /** `DELETE /mfa/{id}`. **Sensitive.** */
+  removeMfaFactor(factorId) {
+    return this.#send("DELETE", `/mfa/${id(factorId)}`);
+  }
+  /** `POST /mfa/recovery/regenerate`. **Sensitive.** */
+  regenerateRecoveryCodes() {
+    return this.#send("POST", "/mfa/recovery/regenerate");
+  }
+  /** `GET /passkeys`. */
+  listPasskeys() {
+    return this.#send("GET", "/passkeys");
+  }
+  /** `DELETE /passkeys/{id}`. **Sensitive.** */
+  removePasskey(passkeyId) {
+    return this.#send("DELETE", `/passkeys/${id(passkeyId)}`);
+  }
+  /** `GET /identities`. */
+  listIdentities() {
+    return this.#send("GET", "/identities");
+  }
+  /** `DELETE /identities/{id}`. **Sensitive.** */
+  unlinkIdentity(identityId) {
+    return this.#send("DELETE", `/identities/${id(identityId)}`);
+  }
+  /** `GET /settings`. */
+  listSettings() {
+    return this.#send("GET", "/settings");
+  }
+  /** `PUT /settings/{key}`. */
+  setSetting(key, value) {
+    return this.#send("PUT", `/settings/${id(key)}`, { body: { value } });
+  }
+  /** `DELETE /settings/{key}` — back to the definition's default. */
+  resetSetting(key) {
+    return this.#send("DELETE", `/settings/${id(key)}`);
+  }
+  /** `GET /portal` — the hosted portal's entry URL and the sections offered. */
+  getPortal() {
+    return this.#send("GET", "/portal");
+  }
+  /** `POST /deletion` — deleted permanently after 7 days, cancellable until then. **Sensitive.** */
+  requestDeletion() {
+    return this.#send("POST", "/deletion");
+  }
+  /** `DELETE /deletion` — the emailed cancellation token; the one anonymous operation. */
+  cancelDeletion(token) {
+    return this.#send("DELETE", "/deletion", { body: { token }, anonymous: true });
+  }
+  toString() {
+    return `AccountClient(${this.baseUrl})`;
+  }
+  toJSON() {
+    return { baseUrl: this.baseUrl };
+  }
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+  async #token() {
+    const token = typeof this.#accessToken === "function" ? await this.#accessToken() : this.#accessToken;
+    if (token === "") throw new KleoraError("invalid_configuration", "accessToken returned an empty token");
+    return token;
+  }
+  async #send(method, path, call = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [name, value] of Object.entries(call.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(name, String(value));
+    }
+    const headers = {
+      Accept: "application/json, application/problem+json",
+      "User-Agent": USER_AGENT
+    };
+    if (call.anonymous !== true) headers["Authorization"] = `Bearer ${await this.#token()}`;
+    if (call.body !== void 0) headers["Content-Type"] = "application/json";
+    const response = await this.#fetch(url, {
+      method,
+      headers,
+      ...call.body === void 0 ? {} : { body: JSON.stringify(call.body) },
+      signal: AbortSignal.timeout(this.#timeout)
+    });
+    if (!response.ok) throw await toApiError(response);
+    if (response.status === 204) return void 0;
+    const text = await response.text();
+    return text === "" ? void 0 : JSON.parse(text);
+  }
+};
+
+// src/portal.ts
+var ACCOUNT_PORTAL_SECTIONS = [
+  "profile",
+  "password",
+  "security",
+  "sessions",
+  "danger"
+];
+var invalid = (message) => new KleoraError("invalid_configuration", message);
+function assertReturnTo(value) {
+  const url = parseAbsolute("returnTo", value);
+  if (url.hash !== "" || value.includes("#")) {
+    throw invalid(`returnTo must not carry a fragment, got '${value}'`);
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw invalid(`returnTo must not carry userinfo, got '${value}'`);
+  }
+}
+function assertSection(section) {
+  if (!ACCOUNT_PORTAL_SECTIONS.includes(section)) {
+    throw invalid(
+      `section must be one of ${ACCOUNT_PORTAL_SECTIONS.join(", ")}; got '${section}'`
+    );
+  }
+}
+function accountPortalUrl(options) {
+  const issuer = parseAbsolute("issuer", options.issuer);
+  if (options.clientId.length === 0) {
+    throw invalid("clientId must not be empty");
+  }
+  if (options.section !== void 0) assertSection(options.section);
+  if (options.returnTo !== void 0) assertReturnTo(options.returnTo);
+  const base = issuer.href.replace(/\/+$/, "");
+  const path = options.section === void 0 ? "/account" : `/account/${options.section}`;
+  const url = new URL(base + path);
+  url.searchParams.set("client_id", options.clientId);
+  if (options.returnTo !== void 0) url.searchParams.set("return_to", options.returnTo);
+  return url.href;
+}
+
+exports.ACCOUNT_PORTAL_SECTIONS = ACCOUNT_PORTAL_SECTIONS;
+exports.AccountClient = AccountClient;
+exports.ApiError = ApiError;
+exports.CLOCK_TOLERANCE_SECONDS = CLOCK_TOLERANCE_SECONDS;
+exports.DEFAULT_ACCOUNT_TIMEOUT_MS = DEFAULT_ACCOUNT_TIMEOUT_MS;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DEFAULT_JWKS_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+exports.DEFAULT_MANAGEMENT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS2;
+exports.DEFAULT_TTL_SECONDS = DEFAULT_TTL_SECONDS;
+exports.EnvironmentMismatch = EnvironmentMismatch;
+exports.JwksCache = JwksCache;
+exports.KEY_PREFIXES = KEY_PREFIXES;
+exports.KleoraError = KleoraError;
+exports.LoginRequired = LoginRequired;
+exports.MIN_REFETCH_SECONDS = MIN_REFETCH_SECONDS;
+exports.ManagementClient = ManagementClient;
+exports.PROBLEM_BASE = PROBLEM_BASE;
+exports.STALE_MULTIPLIER = STALE_MULTIPLIER;
+exports.TokenError = TokenError;
+exports.USER_AGENT = USER_AGENT;
+exports.VERSION = VERSION;
+exports.accountPortalUrl = accountPortalUrl;
+exports.assertVerifyOptions = assertVerifyOptions;
+exports.authenticate = authenticate;
+exports.classify = classify;
+exports.classifyKey = classifyKey;
+exports.clearJwksCaches = clearJwksCaches;
+exports.express = express;
+exports.fastify = fastify;
+exports.jwksFor = jwksFor;
+exports.problem = problem;
+exports.redactKey = redactKey;
+exports.requirePermission = requirePermission;
+exports.sendProblem = sendProblem;
+exports.verifyAccessToken = verifyAccessToken;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map