@cedarjs/tenancy 8.0.0-canary.3538 → 8.0.0-canary.3540

package/README.md

@@ -76,23 +76,71 @@ import {
 ## Auth helpers
 
 ```ts
-import { hasOrgRole, requireMembership } from '@cedarjs/tenancy'
+// api/src/lib/auth.ts, in place of the single-tenant hasRole/requireAuth
+import { createTenancyAuth } from '@cedarjs/tenancy'
+
+export const { hasUserRole, hasOrgRole, requireUserAuth, requireOrgAuth } =
+  createTenancyAuth()
 
 // In a service:
-requireMembership({ roles: ['owner', 'admin'] })
+requireOrgAuth({ roles: ['owner', 'admin'] }) // in the current organization
+requireUserAuth() // signed in, no organization needed
 
 // Anywhere:
-if (hasOrgRole('owner')) { ... }
+if (hasOrgRole('owner')) { ... } // in the current organization
+if (hasUserRole('superuser')) { ... } // currentUser.roles
+```
+
+`requireOrgAuth` (and the `@requireOrgAuth` directive `setup tenancy` adds) is
+about the current organization: it throws `AuthenticationError` with no
+current user, and `ForbiddenError` with no current organization or when the
+user's role there isn't one of `roles` when they're given. With no `roles`,
+any member gets in. `requireUserAuth` (and `@requireUserAuth`) is for fields about the user
+rather than an organization: it needs a signed-in user, and checks `roles`
+against `currentUser.roles`. `hasOrgRole` and `hasUserRole` are the boolean
+checks to match. There's no `requireAuth` or `hasRole`.
+
+## Permissions
+
+```ts
+// packages/permissions/src/index.ts, shared by the api and web sides
+import { definePermissions } from '@cedarjs/tenancy/permissions'
+
+export const permissions = definePermissions({
+  permissions: ['projects.read', 'projects.edit', 'members.manage'],
+  roles: {
+    owner: ['projects.read', 'projects.edit', 'members.manage'],
+    member: ['projects.read'],
+  },
+})
+```
+
+```ts
+// api/src/lib/permissions.ts
+import { createPermissions } from '@cedarjs/tenancy'
+
+import { permissions } from '@my-app/permissions'
+
+export const { hasPermission, requirePermission, withPermissions } =
+  createPermissions(permissions)
 ```
 
-`requireMembership` throws `AuthenticationError` with no current user and
-`ForbiddenError` with no current organization or a role mismatch — the same
-error types `requireAuth` uses.
+Roles map to permissions in one place; fields ask for a permission with
+`@requirePermission(permission: "projects.edit")` or `requirePermission()`.
+A role only gets what its list says, so a new role is one entry. Permission
+names are typed from the definitions. `withPermissions` in `getCurrentUser` gives each
+membership its permissions, which `useAuth().hasPermission()` checks inside
+`OrgScope`. Every permission is about an organization: fields about the user
+rather than an organization use `@requireUserAuth`.
 
 ## Web
 
-`@cedarjs/tenancy/web` exports `OrgScope`, `useCurrentOrg`, `OrgContext` and
+`@cedarjs/tenancy/web` exports `OrgScope`, `useCurrentOrg` and
 `getMemberships`/`hasOrgRole` for the client side: a per-organization Apollo
 client provided under organization routes, keyed by the immutable organization
-id so switching organizations never mixes caches. See the how-to for the full
+id so switching organizations never mixes caches. `useCurrentOrg().hasOrgRole`
+checks the user's role in the organization, and `OrgScope`'s `roles` and
+`unauthorized` props guard routes by it. `useAuth().hasUserRole` checks
+`currentUser.roles`; there's no `useAuth().hasRole` or `<PrivateSet roles>` in
+an app with tenancy. See the how-to for the full
 `<Set wrap={OrgScope}>` setup `yarn cedar setup tenancy` generates.

package/dist/auth.d.ts

@@ -1,3 +1,4 @@
+type Roles = string | readonly string[];
 /**
  * Whether the current request holds one of `roles` in an organization.
  *
@@ -9,20 +10,56 @@
  *
  * Returns `false` when there's no authenticated user, no matching
  * organization, or no matching membership. An empty `roles` array returns
- * `true` as long as a matching membership exists, mirroring `hasRole()`'s
- * behavior for global roles.
+ * `true` as long as a matching membership exists.
  */
-export declare function hasOrgRole(roles: string | string[], organizationId?: string): boolean;
+export declare function hasOrgRole(roles: Roles, organizationId?: string): boolean;
+export interface TenancyAuth {
+    /**
+     * Whether the signed-in user holds one of `roles` in `currentUser.roles`,
+     * in any organization or none. What the single-tenant `hasRole()` checked;
+     * `hasOrgRole()` checks the role in an organization.
+     */
+    hasUserRole(roles: Roles): boolean;
+    /**
+     * Guards a service or directive on the current organization: signed in,
+     * a member of the current organization and, when `roles` are given, with
+     * one of them there. With no `roles`, any member gets in, as any
+     * signed-in user gets past the single-tenant `requireAuth()`: use `roles`
+     * or `requirePermission()` for anything narrower.
+     *
+     * Throws `AuthenticationError` when no one is signed in, and
+     * `ForbiddenError` otherwise.
+     */
+    requireOrgAuth(options?: {
+        roles?: Roles;
+    }): void;
+    /**
+     * Guards a service or directive on the signed-in user alone, in any
+     * organization or none: their account, their memberships, accepting an
+     * invitation. When `roles` are given, the user needs one of them in
+     * `currentUser.roles`.
+     *
+     * Throws `AuthenticationError` when no one is signed in, and
+     * `ForbiddenError` otherwise.
+     */
+    requireUserAuth(options?: {
+        roles?: Roles;
+    }): void;
+    /** The standalone `hasOrgRole`: with no roles, any membership */
+    hasOrgRole(roles?: Roles, organizationId?: string): boolean;
+}
 /**
- * Guards a service or directive on the current request having a membership
- * in the current organization, optionally with one of `roles`.
+ * The auth checks for an app with tenancy, which `api/src/lib/auth.ts`
+ * exports in place of its single-tenant `hasRole` and `requireAuth`:
  *
- * Throws `AuthenticationError` when there's no authenticated user, and
- * `ForbiddenError` when there's no current organization or the membership's
- * role doesn't match — the same error types `requireAuth` uses, so existing
- * error handling on the web side applies unchanged.
+ * ```ts
+ * export const { hasUserRole, hasOrgRole, requireUserAuth, requireOrgAuth } =
+ *   createTenancyAuth()
+ * ```
+ *
+ * There's no `hasRole` or `requireAuth`: every check says whether it's
+ * about the signed-in user alone or the current organization.
  */
-export declare function requireMembership(options?: {
-    roles?: string | string[];
-}): void;
+export declare function createTenancyAuth(): TenancyAuth;
+export {};
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EACxB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CA4BT;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAO,GAC1C,IAAI,CAwBN"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAKA,KAAK,KAAK,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;AAwBvC;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CA4BzE;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAA;IAClC;;;;;;;;;OASG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAA;IACjD;;;;;;;;OAQG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,IAAI,CAAA;IAClD,iEAAiE;IACjE,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAC5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CA8C/C"}

package/dist/auth.js

@@ -1,8 +1,19 @@
 import { context } from "@cedarjs/context";
 import { AuthenticationError, ForbiddenError } from "@cedarjs/graphql-server";
 import { getCurrentOrg, isUserWithMemberships } from "./context.js";
+const toList = (roles) => roles === void 0 ? [] : typeof roles === "string" ? [roles] : [...roles];
+function userRoles() {
+  const roles = context.currentUser?.roles;
+  if (typeof roles === "string") {
+    return [roles];
+  }
+  if (Array.isArray(roles)) {
+    return roles.filter((role) => typeof role === "string");
+  }
+  return [];
+}
 function hasOrgRole(roles, organizationId) {
-  const roleList = Array.isArray(roles) ? roles : [roles];
+  const roleList = toList(roles);
   if (organizationId) {
     const currentUser = context.currentUser;
     if (!isUserWithMemberships(currentUser)) {
@@ -22,26 +33,40 @@ function hasOrgRole(roles, organizationId) {
   }
   return roleList.length === 0 || roleList.includes(currentOrg.role);
 }
-function requireMembership(options = {}) {
-  if (!context.currentUser) {
-    throw new AuthenticationError("You must be logged in to do that.");
-  }
-  const currentOrg = getCurrentOrg();
-  if (!currentOrg) {
-    throw new ForbiddenError(
-      "You must be a member of an organization to do that."
-    );
-  }
-  const { roles } = options;
-  if (roles === void 0) {
-    return;
-  }
-  const roleList = Array.isArray(roles) ? roles : [roles];
-  if (roleList.length > 0 && !roleList.includes(currentOrg.role)) {
-    throw new ForbiddenError("You do not have permission to do that.");
-  }
+function createTenancyAuth() {
+  return {
+    hasUserRole(roles) {
+      const roleList = toList(roles);
+      return !!context.currentUser && userRoles().some((role) => roleList.includes(role));
+    },
+    requireUserAuth({ roles } = {}) {
+      if (!context.currentUser) {
+        throw new AuthenticationError("You don't have permission to do that.");
+      }
+      if (roles && !userRoles().some((role) => toList(roles).includes(role))) {
+        throw new ForbiddenError("You don't have access to do that.");
+      }
+    },
+    requireOrgAuth({ roles } = {}) {
+      if (!context.currentUser) {
+        throw new AuthenticationError("You don't have permission to do that.");
+      }
+      const currentOrg = getCurrentOrg();
+      if (!currentOrg) {
+        throw new ForbiddenError(
+          "You must be a member of an organization to do that."
+        );
+      }
+      if (roles && !toList(roles).includes(currentOrg.role)) {
+        throw new ForbiddenError("You don't have access to do that.");
+      }
+    },
+    hasOrgRole(roles = [], organizationId) {
+      return hasOrgRole(roles, organizationId);
+    }
+  };
 }
 export {
-  hasOrgRole,
-  requireMembership
+  createTenancyAuth,
+  hasOrgRole
 };

package/dist/definePermissions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Every permission an app checks, and what the built-in roles may do.
+ *
+ * Plain data with no api code in it, so both sides can import it: the api to
+ * check permissions (`createPermissions`), and the web for the names.
+ */
+export interface PermissionDefinitions<Name extends string = string> {
+    /**
+     * Every permission the app checks, by name. Fields, services and the web
+     * ask for these names, so they're defined in code. A name is a stable id,
+     * so it can also key what an app shows for it, such as translations.
+     */
+    permissions: readonly Name[];
+    /**
+     * What each built-in role may do in an organization. A role that isn't
+     * listed has no permissions.
+     */
+    roles: Readonly<Record<string, readonly Name[]>>;
+}
+/** The permission names in `definitions` */
+export type PermissionName<Definitions> = Definitions extends PermissionDefinitions<infer Name> ? Name : never;
+/**
+ * Throws when a role lists a permission that `permissions` doesn't define. The types catch this in TypeScript; this is for
+ * JavaScript, and for definitions built at runtime.
+ */
+export declare function assertPermissionDefinitions(definitions: PermissionDefinitions): void;
+/**
+ * Defines an app's permissions, and what each built-in role may do.
+ * Permission names are typed from `permissions`, so a role listing a name
+ * that isn't defined is a type error.
+ *
+ * ```ts
+ * export const permissions = definePermissions({
+ *   permissions: ['projects.read', 'members.manage'],
+ *   roles: {
+ *     owner: ['projects.read', 'members.manage'],
+ *     member: ['projects.read'],
+ *   },
+ * })
+ * ```
+ *
+ * Pass the result to `createPermissions` on the api.
+ */
+export declare function definePermissions<const Name extends string>(definitions: {
+    permissions: readonly Name[];
+    roles: Readonly<Record<string, readonly NoInfer<Name>[]>>;
+}): PermissionDefinitions<Name>;
+//# sourceMappingURL=definePermissions.d.ts.map

package/dist/definePermissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definePermissions.d.ts","sourceRoot":"","sources":["../src/definePermissions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACjE;;;;OAIG;IACH,WAAW,EAAE,SAAS,IAAI,EAAE,CAAA;IAC5B;;;OAGG;IACH,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,CAAA;CACjD;AAED,4CAA4C;AAC5C,MAAM,MAAM,cAAc,CAAC,WAAW,IACpC,WAAW,SAAS,qBAAqB,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,CAAA;AAEtE;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,qBAAqB,QAanC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,WAAW,EAAE;IACxE,WAAW,EAAE,SAAS,IAAI,EAAE,CAAA;IAC5B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;CAC1D,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAI9B"}

package/dist/definePermissions.js

@@ -0,0 +1,20 @@
+function assertPermissionDefinitions(definitions) {
+  const defined = new Set(definitions.permissions);
+  for (const [role, names] of Object.entries(definitions.roles)) {
+    for (const name of names) {
+      if (!defined.has(name)) {
+        throw new Error(
+          `Unknown permission "${name}" in role "${role}". Add it to \`permissions\` in your permission definitions first.`
+        );
+      }
+    }
+  }
+}
+function definePermissions(definitions) {
+  assertPermissionDefinitions(definitions);
+  return definitions;
+}
+export {
+  assertPermissionDefinitions,
+  definePermissions
+};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './errors.js';
 export * from './context.js';
 export * from './auth.js';
+export * from './permissions.js';
 export { createTenancyExtension } from './prismaExtension.js';
 export type { ModelNamesFor, TenancyConfig } from './prismaExtension.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,kBAAkB,CAAA;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./errors.js";
 export * from "./context.js";
 export * from "./auth.js";
+export * from "./permissions.js";
 import { createTenancyExtension } from "./prismaExtension.js";
 export {
   createTenancyExtension

package/dist/permissions.d.ts

@@ -0,0 +1,69 @@
+import type { PermissionDefinitions } from './definePermissions.js';
+export { definePermissions } from './definePermissions.js';
+export type { PermissionDefinitions, PermissionName, } from './definePermissions.js';
+/** What `permissionsOf` needs to know about a membership */
+export interface MembershipForPermissions {
+    role: string;
+}
+/** A membership as `getCurrentUser` returns it, with its permissions */
+export type WithPermissions<Membership, Permission extends string> = Membership & {
+    permissions: Permission[];
+};
+export interface Permissions<Permission extends string> {
+    /**
+     * Whether the signed-in user may do `permission` in this request: their
+     * membership in the current organization has it. False with no current
+     * organization.
+     */
+    hasPermission(permission: Permission): boolean;
+    /**
+     * Guards a service or directive on `hasPermission(permission)`. Throws
+     * `AuthenticationError` when no one is signed in, and `ForbiddenError`
+     * when they may not.
+     */
+    requirePermission(options: {
+        permission: Permission;
+    }): void;
+    /**
+     * What a membership may do: its role's permissions. The one place a membership's permissions are worked out, which
+     * `hasPermission`, `requirePermission` and `withPermissions` all use.
+     */
+    permissionsOf(membership: MembershipForPermissions): Permission[];
+    /**
+     * `user` with each of its memberships' permissions added, for
+     * `getCurrentUser` to return, so the web gets them with the memberships
+     * (`useAuth().hasPermission`).
+     */
+    withPermissions<User extends {
+        memberships: MembershipForPermissions[];
+    }>(user: User): Omit<User, 'memberships'> & {
+        memberships: WithPermissions<User['memberships'][number], Permission>[];
+    };
+    withPermissions<User extends {
+        memberships: MembershipForPermissions[];
+    }>(user: User | null): (Omit<User, 'memberships'> & {
+        memberships: WithPermissions<User['memberships'][number], Permission>[];
+    }) | null;
+}
+/**
+ * Permissions on top of roles: roles map to permissions in one place, and
+ * fields and services ask for a permission instead of listing roles, so
+ * adding a role is one entry in the definitions instead of an edit to every
+ * field it should reach.
+ *
+ * ```ts
+ * // api/src/lib/permissions.ts
+ * import { permissions } from '@my-app/permissions'
+ *
+ * export const { hasPermission, requirePermission, withPermissions } =
+ *   createPermissions(permissions)
+ * ```
+ *
+ * `permissions` comes from `definePermissions`. Fails closed: a role without
+ * the permission is refused, as is a role the definitions don't list.
+ * Permission names are typed, so a typo in a service is a type error; a
+ * name that isn't defined (a typo in an SDL directive) throws instead of
+ * quietly refusing everyone.
+ */
+export declare function createPermissions<const Permission extends string>(definitions: PermissionDefinitions<Permission>): Permissions<Permission>;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAEnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,YAAY,EACV,qBAAqB,EACrB,cAAc,GACf,MAAM,wBAAwB,CAAA;AAE/B,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAA;CACb;AAED,wEAAwE;AACxE,MAAM,MAAM,eAAe,CACzB,UAAU,EACV,UAAU,SAAS,MAAM,IACvB,UAAU,GAAG;IAAE,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAA;AAE9C,MAAM,WAAW,WAAW,CAAC,UAAU,SAAS,MAAM;IACpD;;;;OAIG;IACH,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAA;IAC9C;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE;QAAE,UAAU,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAAA;IAC5D;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,wBAAwB,GAAG,UAAU,EAAE,CAAA;IACjE;;;;OAIG;IACH,eAAe,CAAC,IAAI,SAAS;QAAE,WAAW,EAAE,wBAAwB,EAAE,CAAA;KAAE,EACtE,IAAI,EAAE,IAAI,GACT,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,GAAG;QAC7B,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,EAAE,CAAA;KACxE,CAAA;IACD,eAAe,CAAC,IAAI,SAAS;QAAE,WAAW,EAAE,wBAAwB,EAAE,CAAA;KAAE,EACtE,IAAI,EAAE,IAAI,GAAG,IAAI,GAEf,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,GAAG;QAC3B,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,EAAE,CAAA;KACxE,CAAC,GACF,IAAI,CAAA;CACT;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,UAAU,SAAS,MAAM,EAC/D,WAAW,EAAE,qBAAqB,CAAC,UAAU,CAAC,GAC7C,WAAW,CAAC,UAAU,CAAC,CAwFzB"}

package/dist/permissions.js

@@ -0,0 +1,68 @@
+import { context } from "@cedarjs/context";
+import { AuthenticationError, ForbiddenError } from "@cedarjs/graphql-server";
+import { getCurrentOrg, isUserWithMemberships } from "./context.js";
+import { assertPermissionDefinitions } from "./definePermissions.js";
+import { definePermissions } from "./definePermissions.js";
+function createPermissions(definitions) {
+  assertPermissionDefinitions(definitions);
+  const assertDefined = (permission) => {
+    if (!definitions.permissions.includes(permission)) {
+      throw new Error(
+        `Unknown permission "${permission}". Add it to \`permissions\` in your permission definitions before using it.`
+      );
+    }
+  };
+  const permissionsOf = (membership) => Object.hasOwn(definitions.roles, membership.role) ? [...definitions.roles[membership.role]] : [];
+  const currentMembership = () => {
+    const currentOrg = getCurrentOrg();
+    if (!currentOrg) {
+      return void 0;
+    }
+    const currentUser = context.currentUser;
+    const membership = isUserWithMemberships(currentUser) ? currentUser.memberships.find((m) => m.id === currentOrg.membershipId) : void 0;
+    return { ...membership, role: currentOrg.role };
+  };
+  const hasPermission = (permission) => {
+    assertDefined(permission);
+    if (!context.currentUser) {
+      return false;
+    }
+    const membership = currentMembership();
+    return !!membership && permissionsOf(membership).includes(permission);
+  };
+  function withPermissions(user) {
+    if (!user) {
+      return null;
+    }
+    return {
+      ...user,
+      memberships: user.memberships.map((membership) => ({
+        ...membership,
+        permissions: permissionsOf(membership)
+      }))
+    };
+  }
+  return {
+    hasPermission,
+    permissionsOf,
+    withPermissions,
+    requirePermission({ permission }) {
+      assertDefined(permission);
+      if (!context.currentUser) {
+        throw new AuthenticationError("You don't have permission to do that.");
+      }
+      if (!getCurrentOrg()) {
+        throw new ForbiddenError(
+          "You must be a member of an organization to do that."
+        );
+      }
+      if (!hasPermission(permission)) {
+        throw new ForbiddenError("You don't have access to do that.");
+      }
+    }
+  };
+}
+export {
+  createPermissions,
+  definePermissions
+};

package/dist/web/OrgScope.d.ts

@@ -1,10 +1,28 @@
 import React from 'react';
-import type { UseAuth } from '@cedarjs/auth';
+import type { PermissionName, UseAuth } from '@cedarjs/auth';
 export interface OrgScopeProps {
     /** Overrides the `orgSlug` route param. */
     orgSlug?: string;
     /** Rendered when the user has no membership matching the slug. */
     notAMember?: React.ReactNode;
+    /**
+     * Only members with one of these roles in the organization get in.
+     * Checked after the organization is resolved, which `<PrivateSet roles>`
+     * around `OrgScope` can't do.
+     */
+    roles?: string | string[];
+    /**
+     * Only members whose membership has this permission get in (see
+     * `createPermissions` in `@cedarjs/tenancy`). Checked like `roles`.
+     */
+    permission?: PermissionName;
+    /**
+     * The name of the route a member without one of `roles`, or without
+     * `permission`, is redirected to. It gets the `orgSlug` param when its
+     * path has one, so it can be a page of the same organization. Without
+     * it, they get `notAMember`.
+     */
+    unauthorized?: string;
     /**
      * The app's `useAuth`, so `OrgScope` can read `currentUser.memberships`
      * without importing app code. Defaults to `useNoAuth`.
@@ -21,9 +39,12 @@ export interface OrgScopeProps {
  * Provides the per-organization Apollo client and `OrgContext` for the
  * organization matching `orgSlug` (a prop, or else the `orgSlug` route
  * param). Renders `notAMember` when the current user has no membership in
- * that organization; otherwise wraps `children` in that organization's own
- * `ApolloProvider`, so every Cell, `useQuery` and `useMutation` under it
- * carries the `cedar-org` header and reads from that organization's cache.
+ * that organization (or not one with `roles`, see `unauthorized`);
+ * otherwise wraps `children` in that organization's own `ApolloProvider`,
+ * so every Cell, `useQuery` and `useMutation` under it carries the
+ * `cedar-org` header and reads from that organization's cache. Under it,
+ * `useAuth().hasPermission` checks the user's membership in that
+ * organization.
  */
-export declare function OrgScope({ orgSlug: orgSlugProp, notAMember, useAuth, onSetOrg, children, }: OrgScopeProps): React.JSX.Element;
+export declare function OrgScope({ orgSlug: orgSlugProp, notAMember, roles, permission, unauthorized, useAuth, onSetOrg, children, }: OrgScopeProps): React.JSX.Element;
 //# sourceMappingURL=OrgScope.d.ts.map

package/dist/web/OrgScope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrgScope.d.ts","sourceRoot":"","sources":["../../src/web/OrgScope.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAe5C,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kEAAkE;IAClE,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAYD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EAAE,WAAW,EACpB,UAAiB,EACjB,OAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAyInC"}
+{"version":3,"file":"OrgScope.d.ts","sourceRoot":"","sources":["../../src/web/OrgScope.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAqB5D,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kEAAkE;IAClE,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,cAAc,CAAA;IAC3B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAwCD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EAAE,WAAW,EACpB,UAAiB,EACjB,KAAK,EACL,UAAU,EACV,YAAY,EACZ,OAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA8KnC"}

package/dist/web/OrgScope.js

@@ -1,20 +1,44 @@
 import { Fragment, jsx } from "react/jsx-runtime";
 import React from "react";
 import { ApolloProvider } from "@apollo/client/react";
-import { useNoAuth } from "@cedarjs/auth";
-import { navigate, useLocation, useParams } from "@cedarjs/router";
+import { HasPermissionContext, useNoAuth } from "@cedarjs/auth";
+import {
+  navigate,
+  Redirect,
+  routes,
+  useLocation,
+  useParams
+} from "@cedarjs/router";
 import { useCreateApolloClient } from "@cedarjs/web/apollo";
 import { getMemberships } from "./getMemberships.js";
 import { hasOrgRole } from "./hasOrgRole.js";
 import { clearOrgClients, dropOrgClient, getOrgClient } from "./orgClients.js";
 import { OrgContext } from "./OrgContext.js";
 const CEDAR_ORG_HEADER = "cedar-org";
+const toList = (roles) => Array.isArray(roles) ? roles : [roles];
+const REPLACE = { replace: true };
+function isNamedRoute(value) {
+  return typeof value === "function";
+}
+function unauthorizedPath(route, orgSlug) {
+  try {
+    return route();
+  } catch (e) {
+    if (e instanceof Error && e.message.includes("Missing parameter")) {
+      return route({ orgSlug });
+    }
+    throw e;
+  }
+}
 function membershipRoleMap(memberships) {
   return new Map(memberships.map((m) => [m.organizationId, m.role]));
 }
 function OrgScope({
   orgSlug: orgSlugProp,
   notAMember = null,
+  roles,
+  permission,
+  unauthorized,
   useAuth = useNoAuth,
   onSetOrg,
   children
@@ -77,15 +101,32 @@ function OrgScope({
     [onSetOrg, params, location.pathname, location.search, location.hash]
   );
   const membership = orgSlug ? memberships.find((m) => m.organization.slug === orgSlug) : void 0;
-  if (!membership || !userId) {
+  const membershipPermissions = membership?.permissions;
+  const hasPermission = React.useCallback(
+    (permissionToCheck) => membershipPermissions?.includes(permissionToCheck) ?? false,
+    [membershipPermissions]
+  );
+  if (!membership || !userId || !orgSlug) {
     return /* @__PURE__ */ jsx(Fragment, { children: notAMember });
   }
+  const allowed = (roles === void 0 || toList(roles).includes(membership.role)) && (permission === void 0 || hasPermission(permission));
+  if (!allowed) {
+    if (!unauthorized) {
+      return /* @__PURE__ */ jsx(Fragment, { children: notAMember });
+    }
+    const route = Object.hasOwn(routes, unauthorized) ? Reflect.get(routes, unauthorized) : void 0;
+    if (!isNamedRoute(route)) {
+      throw new Error(`We could not find a route named ${unauthorized}`);
+    }
+    return /* @__PURE__ */ jsx(Redirect, { to: unauthorizedPath(route, orgSlug), options: REPLACE });
+  }
   const org = {
     id: membership.organizationId,
     slug: membership.organization.slug,
     name: membership.organization.name,
     role: membership.role,
-    membershipId: membership.id
+    membershipId: membership.id,
+    permissions: membership.permissions ?? []
   };
   const orgClient = getOrgClient({
     userId,
@@ -97,10 +138,10 @@ function OrgScope({
   const contextValue = {
     org,
     memberships,
-    hasOrgRole: (roles, organizationId) => hasOrgRole(memberships, roles, organizationId ?? org.id),
+    hasOrgRole: (roles2, organizationId) => hasOrgRole(memberships, roles2, organizationId ?? org.id),
     setOrg
   };
-  return /* @__PURE__ */ jsx(ApolloProvider, { client: orgClient, children: /* @__PURE__ */ jsx(OrgContext.Provider, { value: contextValue, children }) });
+  return /* @__PURE__ */ jsx(ApolloProvider, { client: orgClient, children: /* @__PURE__ */ jsx(OrgContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsx(HasPermissionContext.Provider, { value: hasPermission, children }) }) });
 }
 export {
   OrgScope

package/dist/web/getMemberships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getMemberships.d.ts","sourceRoot":"","sources":["../../src/web/getMemberships.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AA+B/C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,OAAO,GAAG,aAAa,EAAE,CAYpE"}
+{"version":3,"file":"getMemberships.d.ts","sourceRoot":"","sources":["../../src/web/getMemberships.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAmC/C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,OAAO,GAAG,aAAa,EAAE,CAYpE"}

package/dist/web/getMemberships.js

@@ -8,7 +8,8 @@ function isOrgMembership(value) {
     return false;
   }
   const org = organization;
-  return typeof membership["id"] === "string" && typeof membership["organizationId"] === "string" && typeof membership["role"] === "string" && typeof org["id"] === "string" && typeof org["slug"] === "string" && typeof org["name"] === "string";
+  const permissions = membership["permissions"];
+  return (permissions === void 0 || Array.isArray(permissions) && permissions.every((permission) => typeof permission === "string")) && typeof membership["id"] === "string" && typeof membership["organizationId"] === "string" && typeof membership["role"] === "string" && typeof org["id"] === "string" && typeof org["slug"] === "string" && typeof org["name"] === "string";
 }
 function getMemberships(currentUser) {
   if (!currentUser || typeof currentUser !== "object") {

package/dist/web/index.d.ts

@@ -1,6 +1,5 @@
 export { getMemberships } from './getMemberships.js';
 export { hasOrgRole } from './hasOrgRole.js';
-export { OrgContext } from './OrgContext.js';
 export type { OrgScopeProps } from './OrgScope.js';
 export { OrgScope } from './OrgScope.js';
 export { clearOrgClients } from './orgClients.js';

package/dist/web/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/web/index.js

@@ -1,11 +1,9 @@
 import { getMemberships } from "./getMemberships.js";
 import { hasOrgRole } from "./hasOrgRole.js";
-import { OrgContext } from "./OrgContext.js";
 import { OrgScope } from "./OrgScope.js";
 import { clearOrgClients } from "./orgClients.js";
 import { useCurrentOrg } from "./useCurrentOrg.js";
 export {
-  OrgContext,
   OrgScope,
   clearOrgClients,
   getMemberships,

package/dist/web/types.d.ts

@@ -7,6 +7,12 @@ export interface OrgMembership {
     id: string;
     organizationId: string;
     role: string;
+    /**
+     * What the membership may do: `withPermissions` from the app's
+     * permissions map adds these in `getCurrentUser`. Missing when the app
+     * doesn't use permissions.
+     */
+    permissions?: string[];
     organization: {
         id: string;
         slug: string;
@@ -23,9 +29,11 @@ export interface CurrentOrgSummary {
     name: string;
     role: string;
     membershipId: string;
+    /** The membership's permissions; empty when the app doesn't use them */
+    permissions: string[];
 }
 /**
- * The value `OrgContext` carries, read through `useCurrentOrg()`.
+ * What `OrgScope` provides below it, read through `useCurrentOrg()`.
  */
 export interface OrgContextValue {
     org: CurrentOrgSummary | undefined;

package/dist/web/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/web/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE;QACZ,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAA;IAClC,WAAW,EAAE,aAAa,EAAE,CAAA;IAC5B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACtE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/web/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,YAAY,EAAE;QACZ,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAA;IAClC,WAAW,EAAE,aAAa,EAAE,CAAA;IAC5B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACtE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedarjs/tenancy",
-  "version": "8.0.0-canary.3538",
+  "version": "8.0.0-canary.3540",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cedarjs/cedar.git",
@@ -15,6 +15,12 @@
         "default": "./dist/index.js"
       }
     },
+    "./permissions": {
+      "default": {
+        "types": "./dist/definePermissions.d.ts",
+        "default": "./dist/definePermissions.js"
+      }
+    },
     "./web": {
       "default": {
         "types": "./dist/web/index.d.ts",
@@ -38,17 +44,17 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@cedarjs/api": "8.0.0-canary.3538",
-    "@cedarjs/context": "8.0.0-canary.3538",
-    "@cedarjs/graphql-server": "8.0.0-canary.3538"
+    "@cedarjs/api": "8.0.0-canary.3540",
+    "@cedarjs/context": "8.0.0-canary.3540",
+    "@cedarjs/graphql-server": "8.0.0-canary.3540"
   },
   "devDependencies": {
     "@apollo/client": "4.3.5",
     "@arethetypeswrong/cli": "0.18.5",
-    "@cedarjs/auth": "8.0.0-canary.3538",
-    "@cedarjs/framework-tools": "8.0.0-canary.3538",
-    "@cedarjs/router": "8.0.0-canary.3538",
-    "@cedarjs/web": "8.0.0-canary.3538",
+    "@cedarjs/auth": "8.0.0-canary.3540",
+    "@cedarjs/framework-tools": "8.0.0-canary.3540",
+    "@cedarjs/router": "8.0.0-canary.3540",
+    "@cedarjs/web": "8.0.0-canary.3540",
     "@prisma/adapter-better-sqlite3": "7.10.1",
     "@prisma/client": "7.10.1",
     "@testing-library/dom": "10.4.2",
@@ -74,9 +80,9 @@
   },
   "peerDependencies": {
     "@apollo/client": "4.3.5",
-    "@cedarjs/auth": "8.0.0-canary.3538",
-    "@cedarjs/router": "8.0.0-canary.3538",
-    "@cedarjs/web": "8.0.0-canary.3538",
+    "@cedarjs/auth": "8.0.0-canary.3540",
+    "@cedarjs/router": "8.0.0-canary.3540",
+    "@cedarjs/web": "8.0.0-canary.3540",
     "@prisma/client": "7.10.1",
     "react": "19.3.1"
   },