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

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

@@ -71,9 +71,90 @@ function findExportedConst(root, name) {
     }
   });
 }
+const USER_LOOKUP = {
+  callee: {
+    type: "MemberExpression",
+    object: {
+      type: "MemberExpression",
+      object: { name: "db" },
+      property: { name: "user" }
+    },
+    property: { name: "findUnique" }
+  }
+};
+function addContextImport(root) {
+  const usesContext = root.find(j.Identifier, { name: "context" }).filter(
+    (path) => !(j.MemberExpression.check(path.parent.node) && path.parent.node.property === path.node && !path.parent.node.computed) && !(j.ObjectProperty.check(path.parent.node) && path.parent.node.key === path.node)
+  ).length > 0;
+  const declaresContext = root.find(j.ImportDeclaration, {
+    source: { value: "@cedarjs/graphql-server" }
+  }).length > 0 || root.find(j.ImportSpecifier, { local: { name: "context" } }).length > 0 || root.find(j.VariableDeclarator, { id: { name: "context" } }).length > 0;
+  if (!usesContext || declaresContext) {
+    return false;
+  }
+  const contextImport = j.withParser("ts")(`import { context } from '@cedarjs/context'
+`).find(j.ImportDeclaration).nodes()[0];
+  const cedarImports = root.find(j.ImportDeclaration).filter((path) => String(path.node.source.value).startsWith("@cedarjs/"));
+  const before = cedarImports.filter(
+    (path) => String(path.node.source.value) > "@cedarjs/context"
+  );
+  if (before.length > 0) {
+    before.at(0).insertBefore(contextImport);
+  } else if (cedarImports.length > 0) {
+    cedarImports.at(cedarImports.length - 1).insertAfter(contextImport);
+  } else {
+    root.find(j.Program).forEach((path) => {
+      path.node.body.unshift(contextImport);
+    });
+  }
+  return true;
+}
+function addWithPermissions(root, lookups) {
+  const isWithPermissionsCall = (node) => j.CallExpression.check(node) && j.Identifier.check(node.callee) && node.callee.name === "withPermissions";
+  let wrapped = false;
+  root.find(j.CallExpression, USER_LOOKUP).forEach((path) => {
+    if (!lookups.has(path.node)) {
+      return;
+    }
+    const awaited = j.AwaitExpression.check(path.parent.node) ? path.parent : null;
+    const thenCall = path.parent.parent?.node;
+    const isThenWithPermissions = j.MemberExpression.check(path.parent.node) && j.Identifier.check(path.parent.node.property) && path.parent.node.property.name === "then" && j.CallExpression.check(thenCall) && j.Identifier.check(thenCall.arguments[0]) && thenCall.arguments[0].name === "withPermissions";
+    if (isWithPermissionsCall((awaited ?? path).parent.node) || isThenWithPermissions) {
+      return;
+    }
+    wrapped = true;
+    if (awaited) {
+      awaited.replace(
+        j.callExpression(j.identifier("withPermissions"), [awaited.node])
+      );
+    } else {
+      path.replace(
+        j.callExpression(j.memberExpression(path.node, j.identifier("then")), [
+          j.identifier("withPermissions")
+        ])
+      );
+    }
+  });
+  return wrapped;
+}
+function addPermissionsImport(source) {
+  if (/import \{[^}]*\bwithPermissions\b[^}]*\} from/.test(source)) {
+    return source;
+  }
+  const eol = source.includes("\r\n") ? "\r\n" : "\n";
+  const dbImport = /^import \{ db \} from (['"])(.*?)db(\.js)?\1;?\r?\n/m;
+  if (dbImport.test(source)) {
+    return source.replace(
+      dbImport,
+      (line, quote, dir, ext = "") => `${line}import { withPermissions } from ${quote}${dir}permissions${ext}${quote}${eol}`
+    );
+  }
+  return `import { withPermissions } from 'src/lib/permissions'${eol}${source}`;
+}
 function transform(fileInfo) {
   const root = j.withParser("tsx")(fileInfo.source);
   let selectFound = false;
+  const membershipLookups = /* @__PURE__ */ new Set();
   let changed = false;
   root.find(j.CallExpression, {
     callee: {
@@ -104,13 +185,20 @@ function transform(fileInfo) {
       changed = true;
     }
     selectFound = true;
+    membershipLookups.add(path.node);
   });
   if (!selectFound) {
     throw new Error("CEDAR_CODEMOD_ERR_AUTH_SHAPE_NOT_FOUND");
   }
+  if (addWithPermissions(root, membershipLookups)) {
+    changed = true;
+  }
   const alreadyWired = root.find(j.ImportSpecifier, { imported: { name: "createTenancyAuth" } }).length > 0;
   if (alreadyWired) {
-    return changed ? root.toSource() : fileInfo.source;
+    if (addContextImport(root)) {
+      changed = true;
+    }
+    return addPermissionsImport(changed ? root.toSource() : fileInfo.source);
   }
   const hasRole = findExportedConst(root, "hasRole");
   const requireAuth = findExportedConst(root, "requireAuth");
@@ -151,7 +239,8 @@ function transform(fileInfo) {
       path.node.body.unshift(tenancyImport);
     });
   }
-  return root.toSource();
+  addContextImport(root);
+  return addPermissionsImport(root.toSource());
 }
 export {
   TENANCY_AUTH_EXPORT,

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,6 +1,7 @@
 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'
 
@@ -10,8 +11,14 @@ export interface OrgScopeProps {
   /** Only members with one of these roles in the organization get in. */
   roles?: string | string[]
   /**
-   * The name of the route a member without one of `roles` is sent to. It
-   * gets the `orgSlug` param when its path has one.
+   * 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
@@ -26,19 +33,20 @@ export interface OrgScopeProps {
  *     <Route path="/org/{orgSlug}/projects" page={ProjectsPage} name="projects" />
  *   </Set>
  *
- * `useCurrentOrg().hasOrgRole` checks the user's role in the organization,
- * and `useAuth().hasUserRole` checks `currentUser.roles`. For pages only some
- * roles may open, wrap them in a component that passes `roles` (there's no
- * `<PrivateSet roles>` with tenancy):
+ * 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 OwnersOnly = ({ children }: { children: ReactNode }) => (
- *     <OrgScope roles="owner" unauthorized="projects">
+ *   const MemberManagers = ({ children }: { children: ReactNode }) => (
+ *     <OrgScope permission="members.manage" unauthorized="projects">
  *       {children}
  *     </OrgScope>
  *   )
  *
- *   <Set wrap={OwnersOnly}>
- *     <Route path="/org/{orgSlug}/settings" page={SettingsPage} name="settings" />
+ *   <Set wrap={MemberManagers}>
+ *     <Route path="/org/{orgSlug}/members" page={MembersPage} name="members" />
  *   </Set>
  *
  * Routes under `OrgScope` must not carry `prerender`: `OrgScope`'s nested
@@ -48,6 +56,7 @@ export interface OrgScopeProps {
 export const OrgScope = ({
   orgSlug,
   roles,
+  permission,
   unauthorized,
   children,
 }: OrgScopeProps) => {
@@ -56,6 +65,7 @@ export const OrgScope = ({
       useAuth={useAuth}
       orgSlug={orgSlug}
       roles={roles}
+      permission={permission}
       unauthorized={unauthorized}
       notAMember={
         <div>

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

@@ -46,7 +46,8 @@ export const schema = gql`
     myMemberships: [Membership!]! @requireUserAuth
 
     "The current organization, resolved by resolveCurrentOrg for this request."
-    organization(id: String!): Organization @requireOrgAuth
+    organization(id: String!): Organization
+      @requirePermission(permission: "organization.read")
   }
 
   type Mutation {
@@ -64,7 +65,7 @@ export const schema = gql`
     the invite shows up if the inviter is also the invitee.
     """
     inviteMember(input: InviteMemberInput!): Invitation!
-      @requireOrgAuth(roles: ["owner", "admin"])
+      @requirePermission(permission: "members.manage")
 
     """
     Attaches the pending membership matching token to the signed-in user, or
@@ -85,6 +86,6 @@ export const schema = gql`
     removing their own membership.
     """
     removeMember(membershipId: String!): Membership!
-      @requireOrgAuth(roles: ["owner", "admin"])
+      @requirePermission(permission: "members.manage")
   }
 `

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

@@ -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: `@requireOrgAuth` checks the
- * caller's membership in the current organization, not in `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()
@@ -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 `@requireOrgAuth(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.

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/requirePermission.test.ts.template

@@ -0,0 +1,50 @@
+import { mockRedwoodDirective, getDirectiveName } from '@cedarjs/testing/api'
+
+import requirePermission from './requirePermission.js'
+
+const currentOrg = (role: string) => ({
+  id: 'org-1',
+  slug: 'org-1',
+  role,
+  membershipId: 'membership-1',
+})
+
+describe('requirePermission directive', () => {
+  it('declares the directive sdl as schema, with the correct name', () => {
+    expect(requirePermission.schema).toBeTruthy()
+    expect(getDirectiveName(requirePermission.schema)).toBe('requirePermission')
+  })
+
+  it('throws when there is no current user', () => {
+    const mockExecution = mockRedwoodDirective(requirePermission, {
+      context: {},
+      directiveArgs: { permission: 'organization.read' },
+    })
+
+    expect(mockExecution).toThrowError()
+  })
+
+  it("throws when the role in the current organization doesn't have it", () => {
+    const mockExecution = mockRedwoodDirective(requirePermission, {
+      context: {
+        currentUser: { id: 'user-1' },
+        currentOrg: currentOrg('member'),
+      },
+      directiveArgs: { permission: 'members.manage' },
+    })
+
+    expect(mockExecution).toThrowError()
+  })
+
+  it('passes when the role in the current organization has it', () => {
+    const mockExecution = mockRedwoodDirective(requirePermission, {
+      context: {
+        currentUser: { id: 'user-1' },
+        currentOrg: currentOrg('owner'),
+      },
+      directiveArgs: { permission: 'members.manage' },
+    })
+
+    expect(mockExecution).not.toThrowError()
+  })
+})

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

@@ -0,0 +1,32 @@
+import type { Permission } from '__PERMISSIONS_PACKAGE__'
+import { gql } from 'graphql-tag'
+
+import type { ValidatorDirectiveFunc } from '@cedarjs/graphql-server'
+import { createValidatorDirective } from '@cedarjs/graphql-server'
+
+import { requirePermission as applicationRequirePermission } from 'src/lib/permissions'
+
+export const schema = gql`
+  """
+  Use to check that the signed-in user may do something: that their role in
+  the current organization has the permission (see packages/permissions).
+  """
+  directive @requirePermission(permission: String!) on FIELD_DEFINITION
+`
+
+// Optional to fit `ValidatorDirectiveFunc`; the SDL makes it required
+type RequirePermissionValidate = ValidatorDirectiveFunc<{
+  permission?: string
+}>
+
+const validate: RequirePermissionValidate = ({ directiveArgs }) => {
+  // A name the permissions map doesn't know throws, so a typo in the SDL is
+  // an error rather than a field nobody can use
+  applicationRequirePermission({
+    permission: directiveArgs.permission as Permission,
+  })
+}
+
+const requirePermission = createValidatorDirective(schema, validate)
+
+export default requirePermission

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

@@ -26,6 +26,10 @@ import {
   renameRequireAuthDirective,
   renameLibAuthImports
 } from "./authDirectives.js";
+import {
+  addPermissionsPackageTasks,
+  permissionsPackageName
+} from "./permissionsPackage.js";
 import {
   authNotSetUpMessage,
   hasWebAuthFile,
@@ -44,8 +48,10 @@ const DEFAULT_TENANT_FIELD = "organizationId";
 const AUTH_SNIPPET = `
   import { createTenancyAuth } from '@cedarjs/tenancy'
 
+  import { withPermissions } from 'src/lib/permissions'
+
   export const getCurrentUser = async (session) => {
-    return await db.user.findUnique({
+    return withPermissions(await db.user.findUnique({
       where: { id: session.id },
       select: {
         // ...your existing fields...
@@ -58,7 +64,7 @@ const AUTH_SNIPPET = `
           },
         },
       },
-    })
+    }))
   }
 
   // In place of your hasRole and requireAuth
@@ -315,6 +321,47 @@ ${SIGNUP_SNIPPET}`;
           }
         }
       },
+      {
+        title: "Adding the permissions package...",
+        task: () => addPermissionsPackageTasks({
+          cedarVersion,
+          indexSource: fs.readFileSync(
+            path.resolve(
+              import.meta.dirname,
+              "templates",
+              "permissionsPackage.index.ts.template"
+            ),
+            "utf-8"
+          ),
+          force
+        })
+      },
+      {
+        title: "Adding permission checks and the requirePermission directive...",
+        task: async () => {
+          const replacements = {
+            __PERMISSIONS_PACKAGE__: permissionsPackageName()
+          };
+          await writeTemplateFile(
+            "permissions.ts.template",
+            path.join(paths.api.lib, `permissions.${ext}`),
+            replacements
+          );
+          const directiveDir = path.join(
+            paths.api.directives,
+            "requirePermission"
+          );
+          await writeTemplateFile(
+            "requirePermission.ts.template",
+            path.join(directiveDir, `requirePermission.${ext}`),
+            replacements
+          );
+          await writeTemplateFile(
+            "requirePermission.test.ts.template",
+            path.join(directiveDir, `requirePermission.test.${ext}`)
+          );
+        }
+      },
       {
         title: "Adding the organizations service...",
         task: async () => {
@@ -488,7 +535,13 @@ ${SIGNUP_SNIPPET}`;
              tenant-owned models with ${c.highlight("withTenancy")} from ${c.highlight(
             "@cedarjs/tenancy"
           )}.
-          5. ${c.highlight("@requireAuth")} is gone. Your fields use ${c.highlight("@requireUserAuth")} now,
+          5. Your permissions, and what each role may do, are in
+             ${c.highlight("packages/permissions")}, shared by the api and web sides${ctx.packagesWorkspaceTurnedOn ? ` (this
+             turned on ${c.highlight("experimental.packagesWorkspace")} in cedar.toml)` : ""}. Guard
+             organization fields with ${c.highlight('@requirePermission(permission: "...")')}
+             (or ${c.highlight("@requireOrgAuth(roles: [...])")}), and check permissions on the
+             web with ${c.highlight("useAuth().hasPermission()")}.
+          6. ${c.highlight("@requireAuth")} is gone. Your fields use ${c.highlight("@requireUserAuth")} now,
              which checks what ${c.highlight("@requireAuth")} did: there were no organizations
              before. ${c.highlight("@requireOrgAuth")} needs a current organization, and checks
              the user's role in it.${ctx.keptRequireAuthDirective ? `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedarjs/cli",
-  "version": "8.0.0-canary.3539",
+  "version": "8.0.0-canary.3540",
   "description": "The CedarJS Command Line",
   "repository": {
     "type": "git",
@@ -36,17 +36,17 @@
     "@babel/preset-typescript": "7.29.7",
     "@babel/traverse": "7.29.10",
     "@babel/types": "7.29.11",
-    "@cedarjs/api-server": "8.0.0-canary.3539",
-    "@cedarjs/babel-config": "8.0.0-canary.3539",
-    "@cedarjs/cli-helpers": "8.0.0-canary.3539",
-    "@cedarjs/internal": "8.0.0-canary.3539",
-    "@cedarjs/prerender": "8.0.0-canary.3539",
-    "@cedarjs/project-config": "8.0.0-canary.3539",
-    "@cedarjs/structure": "8.0.0-canary.3539",
-    "@cedarjs/telemetry": "8.0.0-canary.3539",
-    "@cedarjs/utils": "8.0.0-canary.3539",
-    "@cedarjs/vite": "8.0.0-canary.3539",
-    "@cedarjs/web-server": "8.0.0-canary.3539",
+    "@cedarjs/api-server": "8.0.0-canary.3540",
+    "@cedarjs/babel-config": "8.0.0-canary.3540",
+    "@cedarjs/cli-helpers": "8.0.0-canary.3540",
+    "@cedarjs/internal": "8.0.0-canary.3540",
+    "@cedarjs/prerender": "8.0.0-canary.3540",
+    "@cedarjs/project-config": "8.0.0-canary.3540",
+    "@cedarjs/structure": "8.0.0-canary.3540",
+    "@cedarjs/telemetry": "8.0.0-canary.3540",
+    "@cedarjs/utils": "8.0.0-canary.3540",
+    "@cedarjs/vite": "8.0.0-canary.3540",
+    "@cedarjs/web-server": "8.0.0-canary.3540",
     "@listr2/prompt-adapter-enquirer": "4.4.3",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/core": "2.12.0",
@@ -93,7 +93,7 @@
     "yargs": "18.2.0"
   },
   "devDependencies": {
-    "@cedarjs/framework-tools": "8.0.0-canary.3539",
+    "@cedarjs/framework-tools": "8.0.0-canary.3540",
     "@prisma/dmmf": "7.10.1",
     "@types/archiver": "^7.0.0",
     "memfs": "4.80.0",