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

package/dist/commands/setup/tenancy/permissionsPackage.js

@@ -0,0 +1,240 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Listr } from "listr2";
+import * as toml from "smol-toml";
+import { runScript } from "@cedarjs/cli-helpers/packageManager/exec";
+import { installPackages } from "@cedarjs/cli-helpers/packageManager/packages";
+import { addWorkspaceDir } from "@cedarjs/cli-helpers/packageManager/workspaces";
+import { getConfigPath } from "@cedarjs/project-config";
+import { getPackageManager } from "@cedarjs/project-config/packageManager";
+import { getPaths, writeFile } from "../../../lib/index.js";
+import {
+  addDependencyToPackageJson,
+  nameVariants,
+  updateGitignore,
+  updateTsconfig,
+  updateWorkspaceTsconfigReferences
+} from "../../generate/package/packageHandler.js";
+const PERMISSIONS_PACKAGE_FOLDER = "permissions";
+const TABLE_HEADER = "[experimental.packagesWorkspace]";
+function enablePackagesWorkspace(tomlContent) {
+  const config = toml.parse(tomlContent);
+  const packagesWorkspace = config.experimental?.packagesWorkspace;
+  if (packagesWorkspace?.enabled === true) {
+    return null;
+  }
+  const lines = tomlContent.split("\n");
+  const headerIndex = lines.findIndex((line) => line.trim() === TABLE_HEADER);
+  if (headerIndex === -1) {
+    if (packagesWorkspace) {
+      throw new Error(
+        "CEDAR_TENANCY_ERR_PACKAGES_WORKSPACE: set `experimental.packagesWorkspace.enabled = true` in cedar.toml and run this command again."
+      );
+    }
+    return tomlContent.replace(/\n*$/, "") + `
+
+${TABLE_HEADER}
+  enabled = true
+`;
+  }
+  const tableEnd = lines.findIndex(
+    (line, index) => index > headerIndex && /^\s*\[/.test(line)
+  );
+  const end = tableEnd === -1 ? lines.length : tableEnd;
+  const enabledIndex = lines.findIndex(
+    (line, index) => index > headerIndex && index < end && /^\s*enabled\s*=/.test(line)
+  );
+  if (enabledIndex === -1) {
+    lines.splice(headerIndex + 1, 0, "  enabled = true");
+  } else {
+    lines[enabledIndex] = lines[enabledIndex].replace(
+      /enabled\s*=.*/,
+      "enabled = true"
+    );
+  }
+  return lines.join("\n");
+}
+const packageNameIn = (packageDir) => {
+  try {
+    const { name } = JSON.parse(
+      fs.readFileSync(path.join(packageDir, "package.json"), "utf-8")
+    );
+    return typeof name === "string" ? name : void 0;
+  } catch {
+    return void 0;
+  }
+};
+function permissionsPackageName(packagesDir = path.join(getPaths().base, "packages")) {
+  const existing = packageNameIn(
+    path.join(packagesDir, PERMISSIONS_PACKAGE_FOLDER)
+  );
+  if (existing) {
+    return existing;
+  }
+  const otherPackages = fs.existsSync(packagesDir) ? fs.readdirSync(packagesDir, { withFileTypes: true }) : [];
+  const scope = otherPackages.filter((entry) => entry.isDirectory()).map((entry) => packageNameIn(path.join(packagesDir, entry.name))).find((name) => name?.startsWith("@") && name.includes("/"))?.split("/")[0];
+  return scope ? `${scope}/${PERMISSIONS_PACKAGE_FOLDER}` : nameVariants(PERMISSIONS_PACKAGE_FOLDER).packageName;
+}
+function permissionsPackageFiles({
+  packageName,
+  cedarVersion,
+  indexSource
+}) {
+  const packageJson = {
+    name: packageName,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    main: "dist/index.js",
+    types: "./dist/index.d.ts",
+    exports: {
+      ".": {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      }
+    },
+    scripts: {
+      build: "tsc",
+      watch: "tsc --watch"
+    },
+    dependencies: {
+      "@cedarjs/tenancy": cedarVersion
+    },
+    devDependencies: {
+      typescript: "5.9.3"
+    }
+  };
+  const tsconfig = {
+    compilerOptions: {
+      composite: true,
+      target: "es2023",
+      module: "node20",
+      esModuleInterop: true,
+      strict: true,
+      skipLibCheck: true,
+      rootDir: "src",
+      outDir: "dist",
+      sourceMap: true,
+      declaration: true,
+      declarationMap: true
+    },
+    include: ["src"]
+  };
+  return {
+    "package.json": JSON.stringify(packageJson, null, 2) + "\n",
+    "tsconfig.json": JSON.stringify(tsconfig, null, 2) + "\n",
+    "src/index.ts": indexSource
+  };
+}
+function writePermissionsPackageFiles(packageDir, files, { force }) {
+  const kept = [];
+  for (const [file, content] of Object.entries(files)) {
+    const filePath = path.join(packageDir, file);
+    if (fs.existsSync(filePath) && !force) {
+      kept.push(filePath);
+      continue;
+    }
+    writeFile(filePath, content, { overwriteExisting: force });
+  }
+  return kept;
+}
+function addPermissionsPackageTasks({
+  cedarVersion,
+  indexSource,
+  force
+}) {
+  const paths = getPaths();
+  const packageDir = path.join(
+    paths.base,
+    "packages",
+    PERMISSIONS_PACKAGE_FOLDER
+  );
+  const packageName = permissionsPackageName();
+  return new Listr([
+    {
+      title: "Turning on the packages workspace in cedar.toml...",
+      task: (ctx, task) => {
+        const configPath = getConfigPath();
+        const updated = enablePackagesWorkspace(
+          fs.readFileSync(configPath, "utf-8")
+        );
+        if (updated === null) {
+          task.skip("Already on");
+          return;
+        }
+        fs.writeFileSync(configPath, updated);
+        ctx.packagesWorkspaceTurnedOn = true;
+      }
+    },
+    {
+      title: "Updating workspace config...",
+      task: (_ctx, task) => {
+        const result = addWorkspaceDir(
+          paths.base,
+          `packages/${PERMISSIONS_PACKAGE_FOLDER}`,
+          getPackageManager()
+        );
+        if (result === "exists") {
+          task.skip("Workspaces already configured");
+        }
+      }
+    },
+    {
+      title: "Updating tsconfig files...",
+      task: (_ctx, task) => updateTsconfig(task)
+    },
+    {
+      title: "Updating .gitignore...",
+      task: (_ctx, task) => updateGitignore(task)
+    },
+    {
+      title: `Writing ${packageName}...`,
+      task: (_ctx, task) => {
+        const files = permissionsPackageFiles({
+          packageName,
+          cedarVersion,
+          indexSource
+        });
+        const kept = writePermissionsPackageFiles(packageDir, files, { force });
+        if (kept.length === Object.keys(files).length) {
+          task.skip("Already there (run with --force to overwrite)");
+        }
+      }
+    },
+    {
+      title: "Adding it to the api and web sides...",
+      task: async (_ctx, task) => {
+        for (const side of [paths.api.base, paths.web.base]) {
+          await addDependencyToPackageJson(
+            task,
+            path.join(side, "package.json"),
+            packageName
+          );
+        }
+      }
+    },
+    {
+      title: "Updating tsconfig references...",
+      task: (_ctx, task) => updateWorkspaceTsconfigReferences(
+        task,
+        PERMISSIONS_PACKAGE_FOLDER,
+        "both"
+      )
+    },
+    {
+      title: "Installing and building it...",
+      task: async () => {
+        await installPackages({ cwd: paths.base });
+        await runScript("build", [], { cwd: packageDir });
+      }
+    }
+  ]);
+}
+export {
+  PERMISSIONS_PACKAGE_FOLDER,
+  addPermissionsPackageTasks,
+  enablePackagesWorkspace,
+  permissionsPackageFiles,
+  permissionsPackageName,
+  writePermissionsPackageFiles
+};

package/dist/commands/setup/tenancy/templates/OrgScope.tsx.template

@@ -1,12 +1,26 @@
 import type { ReactNode } from 'react'
 
 import { OrgScope as TenancyOrgScope } from '@cedarjs/tenancy/web'
+import type { OrgScopeProps as TenancyOrgScopeProps } from '@cedarjs/tenancy/web'
 
 import { useAuth } from 'src/auth'
 
 export interface OrgScopeProps {
   /** Overrides the `orgSlug` route param. */
   orgSlug?: string
+  /** Only members with one of these roles in the organization get in. */
+  roles?: string | string[]
+  /**
+   * Only members whose role has this permission (api/src/lib/permissions)
+   * get in.
+   */
+  permission?: TenancyOrgScopeProps['permission']
+  /**
+   * The name of the route a member without one of `roles`, or without
+   * `permission`, is sent to. It gets the `orgSlug` param when its path has
+   * one.
+   */
+  unauthorized?: string
   children: ReactNode
 }
 
@@ -19,15 +33,40 @@ export interface OrgScopeProps {
  *     <Route path="/org/{orgSlug}/projects" page={ProjectsPage} name="projects" />
  *   </Set>
  *
+ * Under it, `useAuth().hasPermission` and `useCurrentOrg().hasOrgRole`
+ * check the user's membership in the organization, and
+ * `useAuth().hasUserRole` checks `currentUser.roles`. For pages only some
+ * members may open, wrap them in a component that passes `permission` (or
+ * `roles`; there's no `<PrivateSet roles>` with tenancy):
+ *
+ *   const MemberManagers = ({ children }: { children: ReactNode }) => (
+ *     <OrgScope permission="members.manage" unauthorized="projects">
+ *       {children}
+ *     </OrgScope>
+ *   )
+ *
+ *   <Set wrap={MemberManagers}>
+ *     <Route path="/org/{orgSlug}/members" page={MembersPage} name="members" />
+ *   </Set>
+ *
  * Routes under `OrgScope` must not carry `prerender`: `OrgScope`'s nested
  * Apollo client shadows the per-route client the prerenderer injects above
  * `App`, so a prerendered query under here would not go through it.
  */
-export const OrgScope = ({ orgSlug, children }: OrgScopeProps) => {
+export const OrgScope = ({
+  orgSlug,
+  roles,
+  permission,
+  unauthorized,
+  children,
+}: OrgScopeProps) => {
   return (
     <TenancyOrgScope
       useAuth={useAuth}
       orgSlug={orgSlug}
+      roles={roles}
+      permission={permission}
+      unauthorized={unauthorized}
       notAMember={
         <div>
           <p>You don&apos;t have access to this organization.</p>

package/dist/commands/setup/tenancy/templates/organizations.sdl.ts.template

@@ -43,16 +43,17 @@ export const schema = gql`
 
   type Query {
     "Every membership belonging to the signed-in user, across all organizations they belong to."
-    myMemberships: [Membership!]! @requireAuth
+    myMemberships: [Membership!]! @requireUserAuth
 
     "The current organization, resolved by resolveCurrentOrg for this request."
-    organization(id: String!): Organization @requireMembership
+    organization(id: String!): Organization
+      @requirePermission(permission: "organization.read")
   }
 
   type Mutation {
     "Creates a new organization with the caller as its owner."
     createOrganization(input: CreateOrganizationInput!): Organization!
-      @requireAuth
+      @requireUserAuth
 
     """
     Creates a pending membership (an invitation) in the current organization,
@@ -64,7 +65,7 @@ export const schema = gql`
     the invite shows up if the inviter is also the invitee.
     """
     inviteMember(input: InviteMemberInput!): Invitation!
-      @requireMembership(roles: ["owner", "admin"])
+      @requirePermission(permission: "members.manage")
 
     """
     Attaches the pending membership matching token to the signed-in user, or
@@ -73,7 +74,8 @@ export const schema = gql`
     Web callers must call reauthenticate() from useAuth() in onCompleted so
     the new membership is reflected in currentUser.memberships.
     """
-    acceptInvitation(token: String!): Organization! @requireAuth
+    acceptInvitation(token: String!): Organization!
+      @requireUserAuth
 
     """
     Removes a membership from the current organization, for a role the
@@ -84,6 +86,6 @@ export const schema = gql`
     removing their own membership.
     """
     removeMember(membershipId: String!): Membership!
-      @requireMembership(roles: ["owner", "admin"])
+      @requirePermission(permission: "members.manage")
   }
 `

package/dist/commands/setup/tenancy/templates/organizations.test.ts.template

@@ -1,5 +1,3 @@
-import { setContext } from '@cedarjs/context'
-
 import { db } from 'src/lib/db'
 
 import {
@@ -18,39 +16,37 @@ import type { StandardScenario } from './organizations.scenarios.js'
 // CedarJS Testing Docs:
 //       https://cedarjs.com/docs/testing#testing-services
 
-/**
- * `context.currentUser` is typed from this app's `getCurrentUser`, which
- * selects more fields than these tests need.
- */
-const asCurrentUser = (user: { id: string; memberships?: unknown[] }) =>
-  user as unknown as typeof context.currentUser
+/** The id of the user a scenario membership belongs to */
+const userIdOf = (membership: { userId: string | null }) => {
+  if (!membership.userId) {
+    throw new Error('Expected the scenario membership to have a user')
+  }
+
+  return membership.userId
+}
 
 /**
- * Sets `context.currentUser` and `context.currentOrg` the way the GraphQL
- * `context` function does for an authenticated, in-organization request.
+ * Signs in as `membership`'s user, in its organization, the way the GraphQL
+ * `context` function does for an in-organization request
  */
 const asMember = (
   scenario: StandardScenario,
   membership: { id: string; userId: string | null; role: string },
 ) => {
-  setContext({
-    currentUser: asCurrentUser({ id: membership.userId! }),
-    currentOrg: {
-      id: scenario.organization.acme.id,
-      slug: scenario.organization.acme.slug,
-      role: membership.role,
-      membershipId: membership.id,
-    },
-  })
+  mockCurrentUser({ id: userIdOf(membership) })
+  context.currentOrg = {
+    id: scenario.organization.acme.id,
+    slug: scenario.organization.acme.slug,
+    role: membership.role,
+    membershipId: membership.id,
+  }
 }
 
 describe('organizations service', () => {
   scenario(
     "myMemberships returns the signed-in user's memberships",
     async (scenario: StandardScenario) => {
-      setContext({
-        currentUser: asCurrentUser({ id: scenario.membership.owner.userId! }),
-      })
+      mockCurrentUser({ id: userIdOf(scenario.membership.owner) })
 
       const result = await myMemberships()
 
@@ -235,7 +231,7 @@ describe('organizations service', () => {
           },
         })
 
-        setContext({ currentUser: asCurrentUser({ id: invitee.id }) })
+        mockCurrentUser({ id: invitee.id })
 
         const result = await acceptInvitation({
           token: scenario.membership.pending.invitationToken!,
@@ -256,7 +252,7 @@ describe('organizations service', () => {
           },
         })
 
-        setContext({ currentUser: asCurrentUser({ id: invitee.id }) })
+        mockCurrentUser({ id: invitee.id })
 
         const token = scenario.membership.pending.invitationToken!
 
@@ -287,10 +283,10 @@ describe('organizations service', () => {
 
         const token = scenario.membership.pending.invitationToken!
 
-        setContext({ currentUser: asCurrentUser({ id: firstUser.id }) })
+        mockCurrentUser({ id: firstUser.id })
         await acceptInvitation({ token })
 
-        setContext({ currentUser: asCurrentUser({ id: secondUser.id }) })
+        mockCurrentUser({ id: secondUser.id })
         await expect(acceptInvitation({ token })).rejects.toThrow()
       },
     )
@@ -308,7 +304,7 @@ describe('organizations service', () => {
 
         const token = scenario.membership.pending.invitationToken!
 
-        setContext({ currentUser: asCurrentUser({ id: invitee.id }) })
+        mockCurrentUser({ id: invitee.id })
         await acceptInvitation({ token })
 
         const claimed = await db.membership.findUnique({
@@ -321,7 +317,7 @@ describe('organizations service', () => {
     )
 
     it('rejects a token that never matched a pending invitation', async () => {
-      setContext({ currentUser: asCurrentUser({ id: 'some-user-id' }) })
+      mockCurrentUser({ id: 'some-user-id' })
 
       await expect(
         acceptInvitation({ token: 'not-a-real-token' }),

package/dist/commands/setup/tenancy/templates/organizations.ts.template

@@ -62,7 +62,7 @@ const canGrantRole = (granterRole: string, targetRole: string): boolean =>
  * organizations. `Membership` is a global model, so this reads plain `db`.
  */
 export const myMemberships: QueryResolvers['myMemberships'] = () => {
-  // @requireAuth guarantees a signed-in user before this resolver runs.
+  // @requireUserAuth guarantees a signed-in user before this resolver runs.
   return db.membership.findMany({
     where: { userId: context.currentUser!.id },
     orderBy: { createdAt: 'asc' },
@@ -72,8 +72,8 @@ export const myMemberships: QueryResolvers['myMemberships'] = () => {
 /**
  * The current organization (the one `resolveCurrentOrg` resolved for this
  * request). `id` is required so callers state which organization they mean,
- * but it must match the current organization: `@requireMembership` only
- * checks that the caller belongs to *some* organization, not to `id`.
+ * but it must match the current organization: `@requirePermission` checks
+ * the caller's membership in the current organization, not in `id`.
  */
 export const organization: QueryResolvers['organization'] = async ({ id }) => {
   const currentOrg = requireCurrentOrg()
@@ -89,7 +89,7 @@ export const organization: QueryResolvers['organization'] = async ({ id }) => {
 export const createOrganization: MutationResolvers['createOrganization'] =
   async ({ input }) => {
     const baseSlug = slugify(input.name)
-    // @requireAuth guarantees a signed-in user before this resolver runs.
+    // @requireUserAuth guarantees a signed-in user before this resolver runs.
     const userId = context.currentUser!.id
 
     let slug = baseSlug
@@ -135,7 +135,7 @@ export const createOrganization: MutationResolvers['createOrganization'] =
  * Creates a pending membership (an invitation) in the current organization,
  * for a role the caller's own role may grant per `ROLE_GRANTS` -- an
  * `admin` can invite an `admin` or a `member`, but not an `owner`, even
- * though `@requireMembership(roles: ["owner", "admin"])` lets an admin call
+ * though `@requirePermission(permission: "members.manage")` lets an admin call
  * this mutation at all. A role that isn't in `ROLE_GRANTS` is rejected
  * outright, so a typo in `input.role` can never create a membership nobody
  * can check against.
@@ -232,7 +232,7 @@ const claimInvitation = async (
 export const acceptInvitation: MutationResolvers['acceptInvitation'] = async ({
   token,
 }) => {
-  // @requireAuth guarantees a signed-in user before this resolver runs.
+  // @requireUserAuth guarantees a signed-in user before this resolver runs.
   const userId = context.currentUser!.id
 
   const claim = await claimInvitation(token, userId)

package/dist/commands/setup/tenancy/templates/permissions.ts.template

@@ -0,0 +1,20 @@
+import { permissions } from '__PERMISSIONS_PACKAGE__'
+
+import { createPermissions } from '@cedarjs/tenancy'
+
+/**
+ * Checks the permissions defined in __PERMISSIONS_PACKAGE__
+ * (packages/permissions). `getCurrentUser` adds each membership's
+ * permissions with `withPermissions`, so the web can check them with
+ * `useAuth().hasPermission()`. The web only decides what to show; these
+ * checks are the guard.
+ *
+ * Who may grant which role is `ROLE_GRANTS` in
+ * api/src/services/organizations/organizations.
+ */
+export const {
+  hasPermission,
+  requirePermission,
+  permissionsOf,
+  withPermissions,
+} = createPermissions(permissions)

package/dist/commands/setup/tenancy/templates/permissionsPackage.index.ts.template

@@ -0,0 +1,28 @@
+import { definePermissions } from '@cedarjs/tenancy/permissions'
+import type { PermissionName } from '@cedarjs/tenancy/permissions'
+
+/**
+ * Every permission the app checks, and what each role may do. Fields ask
+ * for a permission (`@requirePermission(permission: "members.manage")`, or
+ * `requirePermission()` in a service) instead of listing roles, so a new
+ * role is one entry here: it can do exactly what its list says, and a
+ * field added later is closed to it unless its permission is on the list.
+ *
+ * `roles` are per organization: a membership's role decides what the user
+ * may do in that organization. Fields about the user rather than an
+ * organization (their own account, say) use `@requireUserAuth` instead.
+ *
+ * This package is shared: the api checks these permissions
+ * (api/src/lib/permissions), and the web can import the names. The web gets each
+ * membership's permissions from the api, through `getCurrentUser`.
+ */
+export const permissions = definePermissions({
+  permissions: ['organization.read', 'members.manage'],
+  roles: {
+    owner: ['organization.read', 'members.manage'],
+    admin: ['organization.read', 'members.manage'],
+    member: ['organization.read'],
+  },
+})
+
+export type Permission = PermissionName<typeof permissions>

package/dist/commands/setup/tenancy/templates/requireOrgAuth.test.ts.template

@@ -0,0 +1,56 @@
+import { mockRedwoodDirective, getDirectiveName } from '@cedarjs/testing/api'
+
+import requireOrgAuth from './requireOrgAuth.js'
+
+const currentOrg = (role: string) => ({
+  id: 'org-1',
+  slug: 'org-1',
+  role,
+  membershipId: 'membership-1',
+})
+
+describe('requireOrgAuth directive', () => {
+  it('declares the directive sdl as schema, with the correct name', () => {
+    expect(requireOrgAuth.schema).toBeTruthy()
+    expect(getDirectiveName(requireOrgAuth.schema)).toBe('requireOrgAuth')
+  })
+
+  it('throws when there is no current user', () => {
+    const mockExecution = mockRedwoodDirective(requireOrgAuth, { context: {} })
+
+    expect(mockExecution).toThrowError("You don't have permission to do that.")
+  })
+
+  it('throws when there is no current organization', () => {
+    const mockExecution = mockRedwoodDirective(requireOrgAuth, {
+      context: { currentUser: { id: 'user-1' } },
+    })
+
+    expect(mockExecution).toThrowError(
+      'You must be a member of an organization to do that.',
+    )
+  })
+
+  it('does not throw for a member of the current organization', () => {
+    const mockExecution = mockRedwoodDirective(requireOrgAuth, {
+      context: {
+        currentUser: { id: 'user-1' },
+        currentOrg: currentOrg('member'),
+      },
+    })
+
+    expect(mockExecution).not.toThrowError()
+  })
+
+  it("throws when the role in the current organization isn't listed", () => {
+    const mockExecution = mockRedwoodDirective(requireOrgAuth, {
+      context: {
+        currentUser: { id: 'user-1' },
+        currentOrg: currentOrg('member'),
+      },
+      directiveArgs: { roles: ['owner'] },
+    })
+
+    expect(mockExecution).toThrowError("You don't have access to do that.")
+  })
+})

package/dist/commands/setup/tenancy/templates/requireOrgAuth.ts.template

@@ -0,0 +1,25 @@
+import { gql } from 'graphql-tag'
+
+import type { ValidatorDirectiveFunc } from '@cedarjs/graphql-server'
+import { createValidatorDirective } from '@cedarjs/graphql-server'
+
+import { requireOrgAuth as applicationRequireOrgAuth } from 'src/lib/auth'
+
+export const schema = gql`
+  """
+  Use to check that the signed-in user is a member of the current
+  organization, with one of an optional set of roles there.
+  """
+  directive @requireOrgAuth(roles: [String]) on FIELD_DEFINITION
+`
+
+type RequireOrgAuthValidate = ValidatorDirectiveFunc<{ roles?: string[] }>
+
+const validate: RequireOrgAuthValidate = ({ directiveArgs }) => {
+  const { roles } = directiveArgs
+  applicationRequireOrgAuth({ roles })
+}
+
+const requireOrgAuth = createValidatorDirective(schema, validate)
+
+export default requireOrgAuth