@canopy-io/node 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -9,13 +9,20 @@ var CanopyError = class extends Error {
   data;
   /** The path and method that failed, for logging. */
   request;
-  constructor(body, request) {
+  /**
+   * How long to wait before retrying, in milliseconds, when the server said so
+   * via `Retry-After` — populated on a 429, and on any other response that
+   * carries the header. Undefined when the server gave no guidance.
+   */
+  retryAfterMs;
+  constructor(body, request, retryAfterMs) {
     super(body.message);
     this.statusCode = body.statusCode;
     this.code = body.code;
     this.details = body.details;
     this.data = body.data;
     this.request = request;
+    this.retryAfterMs = retryAfterMs;
   }
   /** A 429. `retryAfterMs` is populated when the server said how long to wait. */
   get isRateLimited() {
@@ -34,12 +41,48 @@ var CanopyConnectionError = class extends Error {
     this.request = request;
   }
 };
+var CanopyTokenError = class extends Error {
+  name = "CanopyTokenError";
+  /**
+   * One of:
+   *
+   * - `token.malformed` — not a JWS, or a segment would not decode
+   * - `token.unsupported_algorithm` — not RS256; Canopy issues only RS256
+   * - `token.key_not_found` — no published key matches the token's `kid`
+   * - `token.jwks_unavailable` — the key set could not be fetched or parsed
+   * - `token.signature_invalid` — signature does not match the signing key
+   * - `token.expired` / `token.not_yet_valid` — outside its validity window
+   * - `token.issuer_mismatch` — `iss` is not the configured issuer
+   * - `token.audience_mismatch` — `aud` does not include the configured audience
+   * - `token.audience_unverified` — token has an `aud` but none was configured
+   * - `token.preauth_not_allowed` — a pre-auth token, which grants no access
+   */
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+  }
+};
+var CanopyAuthorizerError = class extends Error {
+  name = "CanopyAuthorizerError";
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+  }
+};
+function isCanopyAuthorizerError(error) {
+  return error instanceof Error && error.name === "CanopyAuthorizerError";
+}
 function isCanopyError(error) {
   return error instanceof Error && error.name === "CanopyError";
 }
 function isCanopyConnectionError(error) {
   return error instanceof Error && error.name === "CanopyConnectionError";
 }
+function isCanopyTokenError(error) {
+  return error instanceof Error && error.name === "CanopyTokenError";
+}
 
 // src/client.ts
 function isCursorPagination(pagination) {
@@ -48,11 +91,14 @@ function isCursorPagination(pagination) {
 var DEFAULT_BASE_URL = "https://auth.canopy-io.com";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_MAX_BACKOFF_MS = 3e4;
 var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "PUT", "DELETE"]);
+var NOT_MODIFIED = 304;
 var CanopyClient = class {
   baseUrl;
   timeoutMs;
   maxRetries;
+  maxBackoffMs;
   authHeaders;
   extraHeaders;
   fetchImpl;
@@ -65,6 +111,7 @@ var CanopyClient = class {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
     this.extraHeaders = options.headers ?? {};
     this.fetchImpl = options.fetch ?? globalThis.fetch;
     if (typeof this.fetchImpl !== "function") {
@@ -86,30 +133,80 @@ var CanopyClient = class {
    * `CanopyConnectionError`.
    */
   async request(method, path, options = {}) {
+    const response = await this.perform(method, path, options);
+    return this.unwrap(response, method.toUpperCase(), path);
+  }
+  /**
+   * A conditional read: send the validator you already hold, and find out
+   * whether anything changed.
+   *
+   * The sibling of `If-Match`, which this client already sends for optimistic
+   * concurrency. `304 Not Modified` is a *success* — it means the copy you
+   * have is current — but it is not a 2xx, so `request` would raise it as an
+   * error. Hence a separate entry point with a return type that says which
+   * happened rather than one that has to be inspected.
+   *
+   * Use it to hold something expensive and revalidate cheaply — the hierarchy
+   * behind local authorization is the case this exists for.
+   */
+  async requestConditional(method, path, etag, options = {}) {
+    const conditional = etag ? { ...options, headers: { ...options.headers, "If-None-Match": etag } } : options;
+    const response = await this.perform(
+      method,
+      path,
+      conditional,
+      (status) => status === NOT_MODIFIED || status >= 200 && status < 300
+    );
+    if (response.status === NOT_MODIFIED) {
+      return { modified: false };
+    }
+    return {
+      modified: true,
+      data: await this.unwrap(response, method.toUpperCase(), path),
+      etag: response.headers.get("etag")
+    };
+  }
+  /**
+   * Everything up to the response: retries, backoff, cancellation and the
+   * status check, without deciding what the body means.
+   *
+   * Split out so a conditional read can accept `304` where an ordinary one
+   * must not, rather than either duplicating the retry policy or teaching
+   * `unwrap` about statuses that carry no body.
+   */
+  async perform(method, path, options = {}, accept = (status) => status >= 200 && status < 300) {
     const url = this.buildUrl(path, options.query);
     const upper = method.toUpperCase();
     const retryable = options.idempotent ?? IDEMPOTENT_METHODS.has(upper);
+    const maxRetries = options.maxRetries ?? this.maxRetries;
+    const maxBackoffMs = options.maxBackoffMs ?? this.maxBackoffMs;
+    throwIfAborted(options.signal);
     let lastError;
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
       if (attempt > 0) {
-        await delay(backoffMs(attempt, lastError));
+        await delay(
+          backoffMs(attempt, lastError, maxBackoffMs),
+          options.signal
+        );
+        throwIfAborted(options.signal);
       }
       try {
         const response = await this.send(upper, url, options);
-        if (this.shouldRetry(response.status, retryable, attempt)) {
+        if (this.shouldRetry(response.status, retryable, attempt, maxRetries)) {
           lastError = await this.toError(response, upper, path);
           continue;
         }
-        if (!response.ok) {
+        if (!accept(response.status)) {
           throw await this.toError(response, upper, path);
         }
-        return await this.unwrap(response);
+        return response;
       } catch (error) {
         if (error instanceof CanopyError) {
           throw error;
         }
         lastError = error;
-        if (!retryable || attempt === this.maxRetries) {
+        throwIfAborted(options.signal);
+        if (!retryable || attempt === maxRetries) {
           throw new CanopyConnectionError(
             `${upper} ${path} failed: ${describe(error)}`,
             { method: upper, path },
@@ -119,13 +216,13 @@ var CanopyClient = class {
       }
     }
     throw new CanopyConnectionError(
-      `${upper} ${path} exhausted ${this.maxRetries + 1} attempts`,
+      `${upper} ${path} exhausted ${maxRetries + 1} attempts`,
       { method: upper, path },
       { cause: lastError }
     );
   }
-  shouldRetry(status, retryable, attempt) {
-    if (attempt >= this.maxRetries) {
+  shouldRetry(status, retryable, attempt, maxRetries) {
+    if (attempt >= maxRetries) {
       return false;
     }
     if (status === 429) {
@@ -135,17 +232,21 @@ var CanopyClient = class {
   }
   async send(method, url, options) {
     const controller = new AbortController();
-    const timer = this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : void 0;
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+    const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
     const onAbort = () => controller.abort();
+    if (options.signal?.aborted) {
+      controller.abort();
+    }
     options.signal?.addEventListener("abort", onAbort, { once: true });
     const headers = {
       Accept: "application/json",
-      ...this.extraHeaders,
-      ...this.authHeaders
+      ...this.extraHeaders
     };
     if (options.body !== void 0) {
       headers["Content-Type"] = "application/json";
     }
+    Object.assign(headers, options.headers, this.authHeaders);
     const init = { method, headers, signal: controller.signal };
     if (options.body !== void 0) {
       init.body = JSON.stringify(options.body);
@@ -172,7 +273,7 @@ var CanopyClient = class {
     }
     return url.toString();
   }
-  async unwrap(response) {
+  async unwrap(response, method, path) {
     if (response.status === 204) {
       return void 0;
     }
@@ -180,7 +281,19 @@ var CanopyClient = class {
     if (text === "") {
       return void 0;
     }
-    const parsed = JSON.parse(text);
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw new CanopyError(
+        {
+          statusCode: response.status,
+          code: null,
+          message: `${method} ${path} returned ${response.status} with a body that is not JSON.`
+        },
+        { method, path }
+      );
+    }
     if (parsed && typeof parsed === "object" && "data" in parsed) {
       return parsed["data"];
     }
@@ -203,14 +316,7 @@ var CanopyClient = class {
       }
     } catch {
     }
-    const error = new CanopyError(body, { method, path });
-    if (retryAfter !== null) {
-      Object.defineProperty(error, "retryAfterMs", {
-        value: retryAfter,
-        enumerable: true
-      });
-    }
-    return error;
+    return new CanopyError(body, { method, path }, retryAfter ?? void 0);
   }
 };
 function parseRetryAfter(header) {
@@ -227,20 +333,46 @@ function parseRetryAfter(header) {
   }
   return Math.max(0, date - Date.now());
 }
-function backoffMs(attempt, lastError) {
+function backoffMs(attempt, lastError, maxBackoffMs) {
   const advised = lastError && typeof lastError === "object" && "retryAfterMs" in lastError ? Number(lastError.retryAfterMs) : NaN;
   if (Number.isFinite(advised)) {
-    return advised;
+    return Math.min(advised, maxBackoffMs);
   }
   const base = 250 * 2 ** (attempt - 1);
-  return base + Math.random() * base;
+  return Math.min(base + Math.random() * base, maxBackoffMs);
+}
+function throwIfAborted(signal) {
+  if (!signal?.aborted) {
+    return;
+  }
+  throw signal.reason ?? new DOMException("This operation was aborted", "AbortError");
 }
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function delay(ms, signal) {
+  if (signal?.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const state = { settled: false };
+    const finish = () => {
+      if (state.settled) {
+        return;
+      }
+      state.settled = true;
+      if (state.timer !== void 0) {
+        clearTimeout(state.timer);
+      }
+      signal?.removeEventListener("abort", finish);
+      resolve();
+    };
+    state.timer = setTimeout(finish, ms);
+    if (!state.settled) {
+      signal?.addEventListener("abort", finish, { once: true });
+    }
+  });
 }
 function describe(error) {
   if (error instanceof Error) {
-    return error.name === "AbortError" ? "timed out or aborted" : error.message;
+    return error.name === "AbortError" ? "timed out" : error.message;
   }
   return String(error);
 }
@@ -443,11 +575,25 @@ var Identities = class {
       `/api/v1/identities/${encodeURIComponent(id)}/activate`
     );
   }
-  /** Every role this identity holds, and where. */
-  assignments(id) {
-    return this.client.request(
-      "GET",
-      `/api/v1/identities/${encodeURIComponent(id)}/assignments`
+  /**
+   * Every role this identity holds, and where — across all pages.
+   *
+   * Paginated (20 per page by default), so this returns a `Paginator` rather
+   * than one response. Reading a single page here would under-report what an
+   * identity can do, which is the dangerous direction to be wrong in.
+   *
+   * ```ts
+   * for await (const assignment of canopy.identities.assignments(id)) { … }
+   * ```
+   */
+  assignments(id, query = {}) {
+    return paginate(
+      (params) => this.client.request(
+        "GET",
+        `/api/v1/identities/${encodeURIComponent(id)}/assignments`,
+        { query: params }
+      ),
+      { ...query }
     );
   }
   /**
@@ -465,6 +611,14 @@ var Identities = class {
   }
 };
 
+// src/schema.ts
+function withConcurrency(options = {}) {
+  if (options.ifMatch === void 0) {
+    return {};
+  }
+  return { headers: { "If-Match": options.ifMatch } };
+}
+
 // src/resources/permissions.ts
 var Permissions = class {
   constructor(client) {
@@ -480,10 +634,19 @@ var Permissions = class {
    * `effective_node_id: null` — that answer must never be used to guard a
    * resource that belongs to a specific node, which is why the scope is a
    * required field rather than a default.
+   *
+   * This runs on the request path, so it is the call most worth passing
+   * `signal` and a tight `timeoutMs` to: without them a slow answer here holds
+   * an inbound request open for the client-wide deadline on every attempt.
    */
-  evaluate(input) {
+  evaluate(input, options = {}) {
     return this.client.request("POST", "/api/v1/permissions/evaluate", {
-      body: input
+      body: input,
+      // A POST only because the question travels in a body; it computes a
+      // decision and writes nothing, so repeating it is safe — and this is the
+      // call least able to afford giving up on a transient 5xx.
+      idempotent: true,
+      ...options
     });
   }
   /**
@@ -492,9 +655,12 @@ var Permissions = class {
    * Prefer this to a loop over `evaluate` when rendering a screen: the checks
    * are answered together instead of paying request latency for each.
    */
-  evaluateBulk(input) {
+  evaluateBulk(input, options = {}) {
     return this.client.request("POST", "/api/v1/permissions/evaluate/bulk", {
-      body: input
+      body: input,
+      /** Read-only, like `evaluate`. */
+      idempotent: true,
+      ...options
     });
   }
   /**
@@ -502,9 +668,12 @@ var Permissions = class {
    * it was inherited from. For debugging an unexpected allow or deny, not for
    * the enforcement path.
    */
-  explain(input) {
+  explain(input, options = {}) {
     return this.client.request("POST", "/api/v1/permissions/evaluate/explain", {
-      body: input
+      body: input,
+      /** Read-only, like `evaluate`. */
+      idempotent: true,
+      ...options
     });
   }
   /** Every permission in the Environment, page by page. */
@@ -524,17 +693,23 @@ var Permissions = class {
   create(input) {
     return this.client.request("POST", "/api/v1/permissions", { body: input });
   }
-  update(id, input) {
+  /**
+   * Pass `ifMatch` with the permission's current `version` to make a
+   * read-modify-write safe — a concurrent edit answers 409 instead of being
+   * silently overwritten.
+   */
+  update(id, input, options = {}) {
     return this.client.request(
       "PATCH",
       `/api/v1/permissions/${encodeURIComponent(id)}`,
-      { body: input }
+      { body: input, ...withConcurrency(options) }
     );
   }
-  delete(id) {
+  delete(id, options = {}) {
     return this.client.request(
       "DELETE",
-      `/api/v1/permissions/${encodeURIComponent(id)}`
+      `/api/v1/permissions/${encodeURIComponent(id)}`,
+      withConcurrency(options)
     );
   }
 };
@@ -560,17 +735,23 @@ var Roles = class {
   create(input) {
     return this.client.request("POST", "/api/v1/roles", { body: input });
   }
-  update(id, input) {
+  /**
+   * Pass `ifMatch` with the role's current `version` to make a
+   * read-modify-write safe — a concurrent edit answers 409 instead of being
+   * silently overwritten.
+   */
+  update(id, input, options = {}) {
     return this.client.request(
       "PATCH",
       `/api/v1/roles/${encodeURIComponent(id)}`,
-      { body: input }
+      { body: input, ...withConcurrency(options) }
     );
   }
-  delete(id) {
+  delete(id, options = {}) {
     return this.client.request(
       "DELETE",
-      `/api/v1/roles/${encodeURIComponent(id)}`
+      `/api/v1/roles/${encodeURIComponent(id)}`,
+      withConcurrency(options)
     );
   }
   permissions(id) {
@@ -608,18 +789,536 @@ var Canopy = class {
   }
 };
 
+// src/authorizer.ts
+var DEFAULT_TTL_MS = 6e4;
+var MAX_WALK_DEPTH = 256;
+var LocalAuthorizer = class {
+  client;
+  ttlMs;
+  now;
+  readOptions;
+  grants = /* @__PURE__ */ new Map();
+  tree;
+  /**
+   * In-flight reads, so concurrent requests for the same thing share one call.
+   *
+   * Without this a cold start under load fans out: a hundred simultaneous
+   * requests for one identity would each miss the cache and each fetch, which
+   * is the per-request traffic this class exists to remove, concentrated into
+   * the worst possible moment.
+   */
+  pendingGrants = /* @__PURE__ */ new Map();
+  pendingTree;
+  stats = {
+    grantFetches: 0,
+    treeRequests: 0,
+    treeNotModified: 0
+  };
+  constructor(client, options = {}) {
+    this.client = client;
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.now = options.now ?? (() => Date.now());
+    this.readOptions = {
+      ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+      ...options.maxRetries === void 0 ? {} : { maxRetries: options.maxRetries, maxBackoffMs: options.timeoutMs }
+    };
+  }
+  /**
+   * Whether the identity holds the permission.
+   *
+   * Shaped like the API's own evaluate so a caller can swap one for the other.
+   * A `node` check with no node is a denial rather than an error: a request
+   * whose subject cannot be established is exactly the one that must not pass.
+   */
+  async evaluate(query, options = {}) {
+    if (!options.signal) {
+      return this.decide(query);
+    }
+    const signal = options.signal;
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+      const fail = () => {
+        reject(
+          signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason ?? "aborted"))
+        );
+      };
+      if (signal.aborted) {
+        fail();
+        return;
+      }
+      onAbort = fail;
+      signal.addEventListener("abort", fail, { once: true });
+    });
+    return Promise.race([this.decide(query), aborted]).finally(() => {
+      if (onAbort) {
+        signal.removeEventListener("abort", onAbort);
+      }
+    });
+  }
+  async decide(query) {
+    const roots = await this.grantRootsFor(query.identity_id);
+    const granted = roots.get(query.permission);
+    if (!granted || granted.size === 0) {
+      return { allowed: false };
+    }
+    if ((query.scope ?? "node") === "app_wide") {
+      return { allowed: true };
+    }
+    if (!query.node_id) {
+      return { allowed: false };
+    }
+    return { allowed: await this.holdsAtNode(granted, query.node_id) };
+  }
+  /** Counters for observability — how much traffic the cache is actually saving. */
+  snapshot() {
+    return { ...this.stats };
+  }
+  /**
+   * Drop everything held. Not needed in normal operation, where entries expire
+   * on their own; useful in tests and after a known change.
+   */
+  invalidate() {
+    this.grants.clear();
+    this.tree = void 0;
+  }
+  /** Climb from `nodeId` and look for a grant root among its ancestors. */
+  async holdsAtNode(granted, nodeId) {
+    if (granted.has(nodeId)) {
+      return true;
+    }
+    const parents = await this.parents();
+    if (!parents.has(nodeId)) {
+      throw new CanopyAuthorizerError(
+        "authorizer.hierarchy_incomplete",
+        `The hierarchy this client can read does not contain node "${nodeId}", so authorization at that node cannot be decided. A scoped API key needs the \`hierarchy.view\` scope to read the tree.`
+      );
+    }
+    let current = parents.get(nodeId);
+    let depth = 0;
+    while (current && depth < MAX_WALK_DEPTH) {
+      if (granted.has(current)) {
+        return true;
+      }
+      current = parents.get(current);
+      depth += 1;
+    }
+    return false;
+  }
+  async grantRootsFor(identityId) {
+    const cached = this.grants.get(identityId);
+    if (cached && cached.expiresAt > this.now()) {
+      return cached.roots;
+    }
+    const pending = this.pendingGrants.get(identityId);
+    if (pending) {
+      return pending;
+    }
+    const read = this.fetchGrantRoots(identityId).finally(() => {
+      this.pendingGrants.delete(identityId);
+    });
+    this.pendingGrants.set(identityId, read);
+    return read;
+  }
+  async fetchGrantRoots(identityId) {
+    this.stats.grantFetches += 1;
+    const response = await this.client.request(
+      "GET",
+      `/api/v1/identities/${encodeURIComponent(identityId)}/grants`,
+      this.readOptions
+    );
+    const roots = /* @__PURE__ */ new Map();
+    for (const row of response.items ?? []) {
+      roots.set(row.permission, new Set(row.nodes));
+    }
+    this.grants.set(identityId, {
+      roots,
+      expiresAt: this.now() + this.ttlMs
+    });
+    return roots;
+  }
+  async parents() {
+    if (this.tree && this.tree.expiresAt > this.now()) {
+      return this.tree.parents;
+    }
+    if (this.pendingTree) {
+      return this.pendingTree;
+    }
+    const read = this.fetchTree().finally(() => {
+      this.pendingTree = void 0;
+    });
+    this.pendingTree = read;
+    return read;
+  }
+  /**
+   * Revalidate rather than re-read. The hierarchy is the expensive half and
+   * the one that changes least, so the common case is a `304` and no transfer
+   * at all — the tree stays in memory and only its expiry moves.
+   */
+  async fetchTree() {
+    this.stats.treeRequests += 1;
+    const held = this.tree;
+    const result = await this.client.requestConditional(
+      "GET",
+      "/api/v1/nodes/parents",
+      held?.etag ?? void 0,
+      this.readOptions
+    );
+    if (!result.modified && held) {
+      this.stats.treeNotModified += 1;
+      this.tree = { ...held, expiresAt: this.now() + this.ttlMs };
+      return held.parents;
+    }
+    const parents = /* @__PURE__ */ new Map();
+    if (result.modified) {
+      for (const edge of result.data.items) {
+        parents.set(edge.id, edge.parent_node_id ?? null);
+      }
+    }
+    this.tree = {
+      parents,
+      etag: result.modified ? result.etag : held?.etag ?? null,
+      expiresAt: this.now() + this.ttlMs
+    };
+    return parents;
+  }
+};
+
+// src/verify.ts
+var DEFAULT_ISSUER = "https://auth.canopy-io.com";
+var DEFAULT_JWKS_CACHE_MAX_AGE_MS = 10 * 60 * 1e3;
+var DEFAULT_JWKS_MIN_REFETCH_INTERVAL_MS = 30 * 1e3;
+var DEFAULT_JWKS_TIMEOUT_MS = 5e3;
+var PRINCIPAL_TYPES = /* @__PURE__ */ new Set(["user", "identity", "api_key", "platform"]);
+var DEFAULT_CLOCK_TOLERANCE_SEC = 60;
+function decodeBase64Url(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded.padEnd(Math.ceil(padded.length / 4) * 4, "="));
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function decodeJsonSegment(segment, what) {
+  try {
+    return JSON.parse(new TextDecoder().decode(decodeBase64Url(segment)));
+  } catch (cause) {
+    throw new CanopyTokenError(
+      "token.malformed",
+      `Token ${what} is not valid base64url-encoded JSON.`,
+      { cause }
+    );
+  }
+}
+var TokenVerifier = class {
+  issuer;
+  audience;
+  jwksUri;
+  jwksCacheMaxAgeMs;
+  jwksMinRefetchIntervalMs;
+  jwksTimeoutMs;
+  clockToleranceSec;
+  allowPreAuthTokens;
+  fetchImpl;
+  /** Imported keys by `kid`, so a repeat verification skips the import cost. */
+  keys = /* @__PURE__ */ new Map();
+  keysFetchedAt = 0;
+  lastFetchAttemptAt = 0;
+  /** In-flight fetch, so a burst of requests triggers one call, not N. */
+  inFlight = null;
+  constructor(options = {}) {
+    this.issuer = (options.issuer ?? DEFAULT_ISSUER).replace(/\/+$/, "");
+    this.audience = options.audience;
+    this.jwksUri = options.jwksUri ?? `${this.issuer}/.well-known/jwks.json`;
+    this.jwksCacheMaxAgeMs = options.jwksCacheMaxAgeMs ?? DEFAULT_JWKS_CACHE_MAX_AGE_MS;
+    this.jwksMinRefetchIntervalMs = options.jwksMinRefetchIntervalMs ?? DEFAULT_JWKS_MIN_REFETCH_INTERVAL_MS;
+    this.jwksTimeoutMs = options.jwksTimeoutMs ?? DEFAULT_JWKS_TIMEOUT_MS;
+    this.clockToleranceSec = options.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC;
+    this.allowPreAuthTokens = options.allowPreAuthTokens ?? false;
+    const boundFetch = options.fetch ?? globalThis.fetch;
+    if (typeof boundFetch !== "function") {
+      throw new TypeError(
+        "TokenVerifier requires a fetch implementation. Pass `fetch` on Node runtimes without a global one."
+      );
+    }
+    this.fetchImpl = boundFetch.bind(globalThis);
+  }
+  /**
+   * Verify a token and return its claims. Throws {@link CanopyTokenError} on
+   * anything short of a full pass — branch on `error.code`.
+   *
+   * Order matters: the signature is checked before any claim is believed, so
+   * nothing downstream ever reads an unverified payload.
+   */
+  async verify(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new CanopyTokenError(
+        "token.malformed",
+        "Token is not a three-part JWS."
+      );
+    }
+    const [encodedHeader, encodedPayload, encodedSignature] = parts;
+    const header = decodeJsonSegment(encodedHeader, "header");
+    if (header.alg !== "RS256") {
+      throw new CanopyTokenError(
+        "token.unsupported_algorithm",
+        `Token is signed with "${header.alg ?? "none"}"; Canopy issues RS256.`
+      );
+    }
+    const key = await this.resolveKey(header.kid);
+    const signed = new TextEncoder().encode(
+      `${encodedHeader}.${encodedPayload}`
+    );
+    let signatureValid;
+    try {
+      signatureValid = await crypto.subtle.verify(
+        "RSASSA-PKCS1-v1_5",
+        key,
+        decodeBase64Url(encodedSignature),
+        signed
+      );
+    } catch (cause) {
+      throw new CanopyTokenError(
+        "token.malformed",
+        "Token signature is not decodable.",
+        { cause }
+      );
+    }
+    if (!signatureValid) {
+      throw new CanopyTokenError(
+        "token.signature_invalid",
+        "Token signature does not match Canopy's signing key."
+      );
+    }
+    const claims = decodeJsonSegment(
+      encodedPayload,
+      "payload"
+    );
+    this.assertClaims(claims);
+    return claims;
+  }
+  /** Everything checked after the signature is known good. */
+  assertClaims(claims) {
+    if (typeof claims.sub !== "string" || claims.sub === "") {
+      throw new CanopyTokenError(
+        "token.malformed",
+        "Token has no `sub` claim, so it identifies no one."
+      );
+    }
+    if (!PRINCIPAL_TYPES.has(claims.type)) {
+      throw new CanopyTokenError(
+        "token.malformed",
+        `Token has an unrecognised \`type\` claim: ${JSON.stringify(claims.type)}.`
+      );
+    }
+    if (claims.iss !== this.issuer) {
+      throw new CanopyTokenError(
+        "token.issuer_mismatch",
+        `Token was issued by "${String(claims.iss)}", not "${this.issuer}".`
+      );
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (typeof claims.exp !== "number") {
+      throw new CanopyTokenError(
+        "token.malformed",
+        "Token has no `exp` claim."
+      );
+    }
+    if (now > claims.exp + this.clockToleranceSec) {
+      throw new CanopyTokenError("token.expired", "Token has expired.");
+    }
+    if (typeof claims.nbf === "number" && now < claims.nbf - this.clockToleranceSec) {
+      throw new CanopyTokenError(
+        "token.not_yet_valid",
+        "Token is not valid yet."
+      );
+    }
+    this.assertAudience(claims);
+    if (claims.token_type === "preauth" && !this.allowPreAuthTokens) {
+      throw new CanopyTokenError(
+        "token.preauth_not_allowed",
+        "This is a pre-auth token: the user authenticated but has not selected an Account, so it grants no access. Set `allowPreAuthTokens: true` only if you are building the account picker."
+      );
+    }
+  }
+  /**
+   * `aud` is checked when either side mentions it.
+   *
+   * The case worth stating: a token carries `aud` but the verifier was not
+   * configured with one. That is not "no audience to check" — it is an OAuth
+   * token being verified by something that never said which client it is, and
+   * ignoring it would accept a token minted for a different client. So it
+   * throws and names the option.
+   */
+  assertAudience(claims) {
+    const audiences = claims.aud === void 0 ? [] : Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    if (this.audience === void 0) {
+      if (audiences.length > 0) {
+        throw new CanopyTokenError(
+          "token.audience_unverified",
+          "Token carries an `aud` claim but the verifier has no `audience` configured. Set `audience` to your OAuth client id; Direct API tokens carry no audience and need no option."
+        );
+      }
+      return;
+    }
+    if (!audiences.includes(this.audience)) {
+      throw new CanopyTokenError(
+        "token.audience_mismatch",
+        `Token audience does not include "${this.audience}".`
+      );
+    }
+  }
+  /**
+   * The signing key for a `kid`, fetching the key set when it is stale or when
+   * the `kid` is unknown — the latter is how key rotation is picked up
+   * mid-process, bounded by `jwksMinRefetchIntervalMs`.
+   */
+  async resolveKey(kid) {
+    if (kid === void 0) {
+      throw new CanopyTokenError(
+        "token.malformed",
+        "Token header has no `kid`, so its signing key cannot be identified."
+      );
+    }
+    const stale = Date.now() - this.keysFetchedAt > this.jwksCacheMaxAgeMs;
+    if (this.keys.size === 0 || stale) {
+      if (this.shouldRefresh()) {
+        await this.refreshKeys();
+      } else if (this.keys.size === 0) {
+        throw new CanopyTokenError(
+          "token.jwks_unavailable",
+          `Signing keys at ${this.jwksUri} are unavailable; backing off before retrying.`
+        );
+      }
+    }
+    const cached = this.keys.get(kid);
+    if (cached) {
+      return cached;
+    }
+    if (this.shouldRefresh()) {
+      await this.refreshKeys();
+    }
+    const rotated = this.keys.get(kid);
+    if (rotated) {
+      return rotated;
+    }
+    throw new CanopyTokenError(
+      "token.key_not_found",
+      `No signing key matches kid "${kid}".`
+    );
+  }
+  /**
+   * Whether to await a key-set refresh.
+   *
+   * Two ways to qualify, and the first matters as much as the second. A read
+   * already in flight is joined regardless of the floor: it costs no extra
+   * outbound request, and it is what lets a concurrent burst share one fetch
+   * instead of one caller winning and the rest being turned away.
+   *
+   * Otherwise the floor applies — the same one for every refetch path, so they
+   * cannot drift into having different amplification properties.
+   */
+  shouldRefresh() {
+    if (this.inFlight) {
+      return true;
+    }
+    return Date.now() - this.lastFetchAttemptAt >= this.jwksMinRefetchIntervalMs;
+  }
+  async refreshKeys() {
+    this.inFlight ??= this.fetchKeys().finally(() => {
+      this.inFlight = null;
+    });
+    await this.inFlight;
+  }
+  async fetchKeys() {
+    this.lastFetchAttemptAt = Date.now();
+    let response;
+    const controller = new AbortController();
+    const timer = this.jwksTimeoutMs > 0 ? setTimeout(() => controller.abort(), this.jwksTimeoutMs) : void 0;
+    try {
+      response = await this.fetchImpl(this.jwksUri, {
+        headers: { accept: "application/json" },
+        signal: controller.signal
+      });
+    } catch (cause) {
+      throw new CanopyTokenError(
+        "token.jwks_unavailable",
+        `Could not reach the signing keys at ${this.jwksUri}.`,
+        { cause }
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      throw new CanopyTokenError(
+        "token.jwks_unavailable",
+        `Signing keys at ${this.jwksUri} returned HTTP ${response.status}.`
+      );
+    }
+    let document;
+    try {
+      document = await response.json();
+    } catch (cause) {
+      throw new CanopyTokenError(
+        "token.jwks_unavailable",
+        `Signing keys at ${this.jwksUri} were not valid JSON.`,
+        { cause }
+      );
+    }
+    const imported = /* @__PURE__ */ new Map();
+    for (const jwk of document.keys ?? []) {
+      if (jwk.kty !== "RSA" || jwk.kid === void 0 || jwk.n === void 0 || jwk.e === void 0) {
+        continue;
+      }
+      if (jwk.alg !== void 0 && jwk.alg !== "RS256") {
+        continue;
+      }
+      try {
+        imported.set(
+          jwk.kid,
+          await crypto.subtle.importKey(
+            "jwk",
+            { kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", ext: true },
+            { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+            false,
+            ["verify"]
+          )
+        );
+      } catch {
+        continue;
+      }
+    }
+    if (imported.size === 0) {
+      throw new CanopyTokenError(
+        "token.jwks_unavailable",
+        `Signing keys at ${this.jwksUri} contained no usable RS256 key.`
+      );
+    }
+    this.keys = imported;
+    this.keysFetchedAt = Date.now();
+  }
+};
+
 exports.Assignments = Assignments;
 exports.Canopy = Canopy;
+exports.CanopyAuthorizerError = CanopyAuthorizerError;
 exports.CanopyClient = CanopyClient;
 exports.CanopyConnectionError = CanopyConnectionError;
 exports.CanopyError = CanopyError;
+exports.CanopyTokenError = CanopyTokenError;
 exports.Identities = Identities;
+exports.LocalAuthorizer = LocalAuthorizer;
 exports.Paginator = Paginator;
 exports.Permissions = Permissions;
 exports.Roles = Roles;
+exports.TokenVerifier = TokenVerifier;
+exports.isCanopyAuthorizerError = isCanopyAuthorizerError;
 exports.isCanopyConnectionError = isCanopyConnectionError;
 exports.isCanopyError = isCanopyError;
+exports.isCanopyTokenError = isCanopyTokenError;
 exports.isCursorPagination = isCursorPagination;
 exports.paginate = paginate;
+exports.withConcurrency = withConcurrency;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map