@canopy-io/node 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @canopy-io/node
 
+## 0.7.0
+
+### Minor Changes
+
+- b336767: **Breaking:** the authorizer's cache window is capped at five minutes. `LocalAuthorizer`'s `ttlMs` (and `CanopyModule`'s `authorizationTtlMs`) above `300_000`, below `0`, or not a number now throws a `RangeError` when the authorizer is created. The window is how long a revoked user keeps access, so a longer one is refused rather than honoured. The default (60 seconds) and `0` (read fresh on every check) are unchanged. `MAX_TTL_MS` is exported.
+- b336767: **Breaking:** `TokenVerifier` no longer defaults its issuer. Every Canopy Environment is its own issuer with its own signing keys (`https://auth.canopy-io.com/environments/<id>`), so the old default, the bare hosted origin, rejected every identity token. Pass `environmentId`, or `issuer` on a custom auth domain or self-hosted instance; the constructor throws with neither or both. The key set is read from the issuer's own `/.well-known/jwks.json`.
+
+  `CanopyModule` now requires `verify` with `environmentId` (or `issuer`), since it builds the verifier at startup.
+
+  The generated types follow the published API, which now includes OAuth client management (`/api/v1/oauth-clients`); those routes are typed but not wrapped as a resource, like API key management.
+
+## 0.6.0
+
+### Minor Changes
+
+- 30b76ce: **Breaking:** `identities.deactivate()` and `identities.activate()` are removed, because the API no longer offers them to Environment-scoped keys. An identity's active flag is Account-wide, so a key for one Environment could lock a person out of every other one. To cut an identity off from this key's Environment, use `identities.delete()`, which removes it from this Environment only. Deactivating an identity everywhere is done in the Admin Workspace or through directory sync.
+
+  `identities.update()` no longer accepts `is_active`, for the same reason.
+
+  `identities.create()` now documents that `role_id` and `node_id` go together; the API answers 400 when only one is sent, where it used to create the identity with no assignment.
+
+  Identity invite responses no longer declare `environment_id` and `environment_name`, which the API never returned on an Environment-scoped key. Listing invites accepts `sort_by` (`name`, `email` or `created`) with `order`, which the API now honours.
+
+  An organization's SSO binding (`organizations.ssoConnections`) now carries `owner_organization_node_id` on its `sso_connection`, naming the organization when its administrator set the connection up from the organization portal. Unbinding such a connection from its organization answers 409 `organization.sso_connection_owned_cannot_unbind`; disable or delete it instead. The connection status enum no longer lists `failed`, which nothing ever set.
+
+- 30b76ce: SSO connection responses no longer carry `last_login_failure_at`, `consecutive_failures` or `auto_disabled_at`. Nothing ever set them, so they only ever returned their defaults; a connection is disabled only by a person. `last_login_at` stays and now records each successful sign-in through the connection.
+
+### Patch Changes
+
+- 30b76ce: Types regenerated from the spec, with no shape change: the descriptions now say that a deactivated role grants nothing to its holders (`is_active`, the explain trace's `active`), and that an empty `allowed_children` list makes a node type a leaf.
+
+  `Authorizer.invalidate()` documents deactivating or reactivating a role as a change to clear the whole cache for, since it changes access for everyone holding the role at once.
+
+  The identity invite create and resend descriptions say a `password_reset` invite expires after 24 hours; every other invite still expires after 7 days.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -110,8 +110,16 @@ rather than ignored when you have not said which client you are:
 new TokenVerifier({ audience: process.env.CANOPY_OAUTH_CLIENT_ID });
 ```
 
-Self-hosted instances set `issuer`. Getting it wrong fails closed: tokens are
-rejected, never mistakenly accepted.
+Every Environment is its own issuer, so name yours:
+
+```ts
+new TokenVerifier({ environmentId: process.env.CANOPY_ENVIRONMENT_ID });
+```
+
+On a custom auth domain or a self-hosted instance, set `issuer` instead
+(`https://auth.acme.com`, or `<origin>/environments/<id>`). The constructor
+throws with neither. Getting it wrong fails closed: tokens are rejected, never
+mistakenly accepted.
 
 With an Environment's **organizations** container on, an identity token also
 names the organization the session is acting in and the one role held there. Read the pair through `orgContext` rather than off the raw claims —
@@ -227,8 +235,9 @@ everything beneath it_, so the roots are never expanded into their descendants.
 
 Both are held for at most 60 seconds, which is the delay between an access
 change and it taking effect, including a moved node. Set `ttlMs` to change it,
-knowing that shortening it below the gap between a user's requests saves
-nothing — every request then finds the cache expired and refetches.
+up to five minutes (`300_000`); a longer value throws when the authorizer is
+created. Shortening it below the gap between a user's requests saves nothing:
+every request then finds the cache expired and refetches.
 
 `canopy.permissions.evaluate` remains for a decision with no staleness at all.
 

package/dist/index.cjs

@@ -84,6 +84,15 @@ function isCanopyTokenError(error) {
   return error instanceof Error && error.name === "CanopyTokenError";
 }
 
+// src/strings.ts
+function withoutTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+  return value.slice(0, end);
+}
+
 // src/client.ts
 function isCursorPagination(pagination) {
   return "next_cursor" in pagination;
@@ -108,7 +117,7 @@ var CanopyClient = class {
         "CanopyClient requires either `apiKey` (server-to-server) or `accessToken` (a user or identity JWT)."
       );
     }
-    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.baseUrl = withoutTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL);
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
@@ -552,29 +561,19 @@ var Identities = class {
       { body: input }
     );
   }
+  /**
+   * Takes the identity out of this key's Environment: its membership here is
+   * deactivated and its role assignments here are dropped. The identity and
+   * its access to other Environments are untouched. Deactivating an identity
+   * everywhere is an Account-level action, not available to an
+   * Environment-scoped key.
+   */
   delete(id) {
     return this.client.request(
       "DELETE",
       `/api/v1/identities/${encodeURIComponent(id)}`
     );
   }
-  /**
-   * Deactivation is the reversible counterpart to `delete` — sessions are
-   * revoked and sign-in refused, but the identity and its assignments survive.
-   * Prefer it for offboarding you may need to undo.
-   */
-  deactivate(id) {
-    return this.client.request(
-      "POST",
-      `/api/v1/identities/${encodeURIComponent(id)}/deactivate`
-    );
-  }
-  activate(id) {
-    return this.client.request(
-      "POST",
-      `/api/v1/identities/${encodeURIComponent(id)}/activate`
-    );
-  }
   /**
    * Every role this identity holds, and where — across all pages.
    *
@@ -636,7 +635,7 @@ var Identities = class {
    * Ends every session the identity holds, so the next refresh on any device
    * fails and the person signs in again. Access tokens already issued keep
    * working until their short lifetime runs out. For a suspected compromise;
-   * `deactivate` also refuses the next sign-in.
+   * `delete` also takes the identity out of this Environment.
    */
   revokeSessions(id) {
     return this.client.request(
@@ -1119,6 +1118,7 @@ var Canopy = class {
 
 // src/authorizer.ts
 var DEFAULT_TTL_MS = 6e4;
+var MAX_TTL_MS = 3e5;
 var MAX_WALK_DEPTH = 256;
 var LocalAuthorizer = class {
   client;
@@ -1145,6 +1145,11 @@ var LocalAuthorizer = class {
   constructor(client, options = {}) {
     this.client = client;
     this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    if (!Number.isFinite(this.ttlMs) || this.ttlMs < 0 || this.ttlMs > MAX_TTL_MS) {
+      throw new RangeError(
+        `ttlMs must be between 0 and ${MAX_TTL_MS} (five minutes); got ${String(this.ttlMs)}. It is how long a revoked user keeps access, so it is capped.`
+      );
+    }
     this.now = options.now ?? (() => Date.now());
     this.readOptions = {
       ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
@@ -1212,7 +1217,9 @@ var LocalAuthorizer = class {
    * With no argument, everything goes: grants and the hierarchy tree. Not
    * needed in normal operation, where entries expire on their own; useful in
    * tests and after a change whose reach you cannot name (a role's
-   * permissions edited, a node moved).
+   * permissions edited, a role deactivated or reactivated, a node moved). A
+   * deactivated role grants nothing to anyone holding it, so until the cache
+   * is cleared or expires, its holders keep being allowed locally.
    *
    * Multi-instance honesty: an invalidation reaches THIS process only. A
    * webhook lands on one instance behind a load balancer; the others serve
@@ -1332,12 +1339,29 @@ var LocalAuthorizer = class {
 };
 
 // src/verify.ts
-var DEFAULT_ISSUER = "https://auth.canopy-io.com";
+var HOSTED_ORIGIN = "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 resolveIssuer(options) {
+  const { environmentId, issuer } = options;
+  if (environmentId && issuer) {
+    throw new TypeError(
+      "TokenVerifier takes environmentId or issuer, not both."
+    );
+  }
+  if (issuer) {
+    return withoutTrailingSlashes(issuer);
+  }
+  if (environmentId) {
+    return `${HOSTED_ORIGIN}/environments/${environmentId}`;
+  }
+  throw new TypeError(
+    "TokenVerifier needs environmentId (the Environment your tokens come from) or, on a custom auth domain or self-hosted instance, issuer."
+  );
+}
 function orgContext(claims) {
   const { org_id, org_role } = claims;
   if (typeof org_id !== "string" || org_id === "" || typeof org_role !== "string" || org_role === "") {
@@ -1382,7 +1406,7 @@ var TokenVerifier = class {
   /** 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.issuer = resolveIssuer(options);
     this.audience = options.audience;
     this.jwksUri = options.jwksUri ?? `${this.issuer}/.well-known/jwks.json`;
     this.jwksCacheMaxAgeMs = options.jwksCacheMaxAgeMs ?? DEFAULT_JWKS_CACHE_MAX_AGE_MS;
@@ -1669,6 +1693,7 @@ exports.CanopyError = CanopyError;
 exports.CanopyTokenError = CanopyTokenError;
 exports.Identities = Identities;
 exports.LocalAuthorizer = LocalAuthorizer;
+exports.MAX_TTL_MS = MAX_TTL_MS;
 exports.Organizations = Organizations;
 exports.Paginator = Paginator;
 exports.Permissions = Permissions;