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

package/README.md

@@ -76,23 +76,38 @@ 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
 ```
 
-`requireMembership` throws `AuthenticationError` with no current user and
-`ForbiddenError` with no current organization or a role mismatch — the same
-error types `requireAuth` uses.
+`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`.
 
 ## 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/web/OrgScope.d.ts

@@ -5,6 +5,18 @@ export interface OrgScopeProps {
     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[];
+    /**
+     * The name of the route a member without one of `roles` 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 +33,10 @@ 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.
  */
-export declare function OrgScope({ orgSlug: orgSlugProp, notAMember, useAuth, onSetOrg, children, }: OrgScopeProps): React.JSX.Element;
+export declare function OrgScope({ orgSlug: orgSlugProp, notAMember, roles, 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,OAAO,EAAE,MAAM,eAAe,CAAA;AAqB5C,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;;;;OAIG;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;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAO,EAAE,WAAW,EACpB,UAAiB,EACjB,KAAK,EACL,YAAY,EACZ,OAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA4JnC"}

package/dist/web/OrgScope.js

@@ -2,19 +2,42 @@ 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 {
+  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,
+  unauthorized,
   useAuth = useNoAuth,
   onSetOrg,
   children
@@ -77,9 +100,19 @@ 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) {
+  if (!membership || !userId || !orgSlug) {
     return /* @__PURE__ */ jsx(Fragment, { children: notAMember });
   }
+  if (roles !== void 0 && !toList(roles).includes(membership.role)) {
+    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,
@@ -97,7 +130,7 @@ 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 }) });

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

@@ -25,7 +25,7 @@ export interface CurrentOrgSummary {
     membershipId: string;
 }
 /**
- * The value `OrgContext` carries, read through `useCurrentOrg()`.
+ * What `OrgScope` provides below it, read through `useCurrentOrg()`.
  */
 export interface OrgContextValue {
     org: CurrentOrgSummary | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedarjs/tenancy",
-  "version": "8.0.0-canary.3538",
+  "version": "8.0.0-canary.3539",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cedarjs/cedar.git",
@@ -38,17 +38,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.3539",
+    "@cedarjs/context": "8.0.0-canary.3539",
+    "@cedarjs/graphql-server": "8.0.0-canary.3539"
   },
   "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.3539",
+    "@cedarjs/framework-tools": "8.0.0-canary.3539",
+    "@cedarjs/router": "8.0.0-canary.3539",
+    "@cedarjs/web": "8.0.0-canary.3539",
     "@prisma/adapter-better-sqlite3": "7.10.1",
     "@prisma/client": "7.10.1",
     "@testing-library/dom": "10.4.2",
@@ -74,9 +74,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.3539",
+    "@cedarjs/router": "8.0.0-canary.3539",
+    "@cedarjs/web": "8.0.0-canary.3539",
     "@prisma/client": "7.10.1",
     "react": "19.3.1"
   },