@canopy-io/node 0.1.1 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ Despite the name, it is not Node-only: the client is `fetch` and nothing else, s
 
 ## Features
 
-- **Typed resource wrappers** for `permissions`, `identities`, `roles` and `assignments` — the four every integration touches.
+- **Typed resource wrappers** for `permissions`, `identities`, `roles`, `assignments` and `organizations` — the ones every integration touches.
 - **The whole API, typed.** Any operation without a wrapper is reachable through `canopy.client.request` with the same envelope handling, error typing and retry policy.
 - **Both credential types.** An API key (`cnpy_…`, sent as `X-API-Key`) for server-to-server calls, or an identity or portal JWT sent as a bearer token.
 - **Envelope unwrapping.** All five response shapes are handled, so a call returns the payload rather than a wrapper.
@@ -113,6 +113,43 @@ 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.
 
+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 —
+Canopy mints the two together, and the helper refuses a half-present pair:
+
+```ts
+import { orgContext } from "@canopy-io/node";
+
+const org = orgContext(claims);
+
+if (org) {
+  org.orgId; // the organization — also a hierarchy node id
+  org.orgRole; // the single role held there, by name
+}
+```
+
+`null` is an ordinary answer: every token from an Environment without the
+container on, and every identity that belongs to no organization yet.
+
+Tokens also carry `amr`, how the session was proven (`pwd`, `otp` or `sso`,
+plus `mfa` once a second factor was verified), so a backend can insist on
+`claims.amr?.includes("mfa")` before a sensitive action.
+
+The organizations themselves are wrapped on the client: provision a tenant,
+manage its members and invitations, tighten its sign-in policy, and bind its
+identity provider.
+
+```ts
+const acme = await canopy.organizations.create({ name: "Acme Corp" });
+
+await canopy.organizations.addMember(acme.id, {
+  identity_id: identityId,
+  role_id: ownerRoleId,
+});
+
+await canopy.organizations.updatePolicy(acme.id, { mfa_required: true });
+```
+
 ### Authorizing without a call per request
 
 Asking "may this identity act _here_" on every request puts Canopy in your

package/dist/index.cjs

@@ -619,6 +619,162 @@ function withConcurrency(options = {}) {
   return { headers: { "If-Match": options.ifMatch } };
 }
 
+// src/resources/organizations.ts
+var Organizations = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(query = {}) {
+    return paginate(
+      (params) => this.client.request("GET", "/api/v1/organizations", {
+        query: params
+      }),
+      { ...query }
+    );
+  }
+  get(id) {
+    return this.client.request("GET", `/api/v1/organizations/${enc(id)}`);
+  }
+  create(input) {
+    return this.client.request("POST", "/api/v1/organizations", {
+      body: input
+    });
+  }
+  /**
+   * Pass `ifMatch` with the organization'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/organizations/${enc(id)}`, {
+      body: input,
+      ...withConcurrency(options)
+    });
+  }
+  /**
+   * Removes the organization with its memberships, pending invitations,
+   * policy, connection bindings, and the tree beneath it. Member identities
+   * survive.
+   */
+  delete(id, options = {}) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/organizations/${enc(id)}`,
+      withConcurrency(options)
+    );
+  }
+  /** Empties the container: every organization goes, the step before switching it off. */
+  deleteAll() {
+    return this.client.request("DELETE", "/api/v1/organizations");
+  }
+  // ── Members: one role per member, held inside the organization only ──
+  listMembers(id, query = {}) {
+    return paginate(
+      (params) => this.client.request("GET", `/api/v1/organizations/${enc(id)}/members`, {
+        query: params
+      }),
+      { ...query }
+    );
+  }
+  addMember(id, input) {
+    return this.client.request(
+      "POST",
+      `/api/v1/organizations/${enc(id)}/members`,
+      { body: input }
+    );
+  }
+  changeMemberRole(id, identityId, input) {
+    return this.client.request(
+      "PATCH",
+      `/api/v1/organizations/${enc(id)}/members/${enc(identityId)}`,
+      { body: input }
+    );
+  }
+  /** Revokes that organization's one role; the identity and its other memberships are untouched. */
+  removeMember(id, identityId) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/organizations/${enc(id)}/members/${enc(identityId)}`
+    );
+  }
+  // ── Invitations: pending membership, carrying the role the recipient will hold ──
+  listInvites(id, query = {}) {
+    return paginate(
+      (params) => this.client.request("GET", `/api/v1/organizations/${enc(id)}/invites`, {
+        query: params
+      }),
+      { ...query }
+    );
+  }
+  createInvite(id, input) {
+    return this.client.request(
+      "POST",
+      `/api/v1/organizations/${enc(id)}/invites`,
+      { body: input }
+    );
+  }
+  revokeInvite(id, inviteId) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/organizations/${enc(id)}/invites/${enc(inviteId)}`
+    );
+  }
+  // ── Policy: the organization's tightening of the Environment's sign-in rules ──
+  /**
+   * The organization's own values (null inherits), the Environment baseline
+   * they tighten from, and the effective policy its members sign in under.
+   */
+  getPolicy(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/organizations/${enc(id)}/policy`
+    );
+  }
+  /**
+   * Can only tighten the Environment: a value that would loosen it answers
+   * 400 `organization.policy_loosens`. Pass `ifMatch` with the policy's
+   * `version` (0 until the organization sets one) for a safe
+   * read-modify-write.
+   */
+  updatePolicy(id, input, options = {}) {
+    return this.client.request(
+      "PATCH",
+      `/api/v1/organizations/${enc(id)}/policy`,
+      { body: input, ...withConcurrency(options) }
+    );
+  }
+  // ── SSO: the organization's own identity provider ──
+  listSsoConnections(id) {
+    return this.client.request(
+      "GET",
+      `/api/v1/organizations/${enc(id)}/sso-connections`
+    );
+  }
+  /**
+   * Sign-ins through the connection then land in this organization, joining
+   * as a member with `default_role_id`. The connection must already be bound
+   * to the organization's Environment, and a connection binds to one
+   * organization per Environment.
+   */
+  bindSsoConnection(id, input) {
+    return this.client.request(
+      "POST",
+      `/api/v1/organizations/${enc(id)}/sso-connections`,
+      { body: input }
+    );
+  }
+  unbindSsoConnection(id, connectionId) {
+    return this.client.request(
+      "DELETE",
+      `/api/v1/organizations/${enc(id)}/sso-connections/${enc(connectionId)}`
+    );
+  }
+};
+function enc(segment) {
+  return encodeURIComponent(segment);
+}
+
 // src/resources/permissions.ts
 var Permissions = class {
   constructor(client) {
@@ -780,12 +936,14 @@ var Canopy = class {
   identities;
   roles;
   assignments;
+  organizations;
   constructor(options) {
     this.client = new CanopyClient(options);
     this.permissions = new Permissions(this.client);
     this.identities = new Identities(this.client);
     this.roles = new Roles(this.client);
     this.assignments = new Assignments(this.client);
+    this.organizations = new Organizations(this.client);
   }
 };
 
@@ -874,10 +1032,30 @@ var LocalAuthorizer = class {
     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.
+   * Drop what is held so the next evaluate refetches.
+   *
+   * With an `identityId`, only that identity's grants are dropped — the
+   * cached hierarchy and every other identity's entries stay warm. This is
+   * the shape an assignment webhook wants: the event names the identity
+   * whose authority moved, and nothing else needs to pay a refetch for it.
+   *
+   * 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).
+   *
+   * Multi-instance honesty: an invalidation reaches THIS process only. A
+   * webhook lands on one instance behind a load balancer; the others serve
+   * their cached grants until their own TTL expires. Unless the app fans the
+   * event out over its own pub/sub, the fleet-wide revocation guarantee is
+   * the TTL, and webhook-driven invalidation is a latency optimization on
+   * top of it — size the TTL to the revocation latency you can promise.
    */
-  invalidate() {
+  invalidate(identityId) {
+    if (identityId !== void 0) {
+      this.grants.delete(identityId);
+      return;
+    }
     this.grants.clear();
     this.tree = void 0;
   }
@@ -990,6 +1168,13 @@ 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 orgContext(claims) {
+  const { org_id, org_role } = claims;
+  if (typeof org_id !== "string" || org_id === "" || typeof org_role !== "string" || org_role === "") {
+    return null;
+  }
+  return { orgId: org_id, orgRole: org_role };
+}
 function decodeBase64Url(value) {
   const padded = value.replace(/-/g, "+").replace(/_/g, "/");
   const binary = atob(padded.padEnd(Math.ceil(padded.length / 4) * 4, "="));
@@ -1309,6 +1494,7 @@ exports.CanopyError = CanopyError;
 exports.CanopyTokenError = CanopyTokenError;
 exports.Identities = Identities;
 exports.LocalAuthorizer = LocalAuthorizer;
+exports.Organizations = Organizations;
 exports.Paginator = Paginator;
 exports.Permissions = Permissions;
 exports.Roles = Roles;
@@ -1318,6 +1504,7 @@ exports.isCanopyConnectionError = isCanopyConnectionError;
 exports.isCanopyError = isCanopyError;
 exports.isCanopyTokenError = isCanopyTokenError;
 exports.isCursorPagination = isCursorPagination;
+exports.orgContext = orgContext;
 exports.paginate = paginate;
 exports.withConcurrency = withConcurrency;
 //# sourceMappingURL=index.cjs.map