@cedarjs/cli 8.0.0-canary.3569 → 8.0.0-canary.3571

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

@@ -0,0 +1,125 @@
+import j from "jscodeshift";
+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 findGetCurrentUser(root) {
+  const expression = root.find(j.VariableDeclarator, { id: { name: "getCurrentUser" } }).map((path) => path.get("init")).filter(
+    (path) => j.ArrowFunctionExpression.check(path.node) || j.FunctionExpression.check(path.node)
+  );
+  return expression.size() > 0 ? expression : root.find(j.FunctionDeclaration, { id: { name: "getCurrentUser" } });
+}
+const isWithPermissions = (node) => j.Identifier.check(node) && node.name === "withPermissions";
+function isWrapped(node) {
+  if (!j.CallExpression.check(node)) {
+    return false;
+  }
+  if (isWithPermissions(node.callee)) {
+    return true;
+  }
+  return j.MemberExpression.check(node.callee) && j.Identifier.check(node.callee.property) && node.callee.property.name === "then" && isWithPermissions(node.arguments[0]);
+}
+function isNothing(node) {
+  return j.NullLiteral.check(node) || j.Identifier.check(node) && node.name === "undefined";
+}
+function isDbCall(node) {
+  return j.CallExpression.check(node) && j.MemberExpression.check(node.callee) && j.MemberExpression.check(node.callee.object) && j.Identifier.check(node.callee.object.object) && node.callee.object.object.name === "db";
+}
+function wrap(node, isAsync) {
+  const withPermissions = j.identifier("withPermissions");
+  if (j.ObjectExpression.check(node) || j.AwaitExpression.check(node)) {
+    return j.callExpression(withPermissions, [node]);
+  }
+  if (isAsync) {
+    return j.callExpression(withPermissions, [j.awaitExpression(node)]);
+  }
+  const promise = isDbCall(node) ? node : j.callExpression(
+    j.memberExpression(j.identifier("Promise"), j.identifier("resolve")),
+    [node]
+  );
+  return j.callExpression(j.memberExpression(promise, j.identifier("then")), [
+    withPermissions
+  ]);
+}
+function selectRoles(getCurrentUser) {
+  let added = false;
+  getCurrentUser.find(j.CallExpression, {
+    callee: {
+      type: "MemberExpression",
+      object: {
+        type: "MemberExpression",
+        object: { name: "db" },
+        property: { name: "user" }
+      },
+      property: { name: "findUnique" }
+    }
+  }).forEach((path) => {
+    const [args] = path.node.arguments;
+    const select = j.ObjectExpression.check(args) ? args.properties.find(
+      (prop) => j.ObjectProperty.check(prop) && j.Identifier.check(prop.key) && prop.key.name === "select"
+    ) : void 0;
+    if (!j.ObjectProperty.check(select) || !j.ObjectExpression.check(select.value)) {
+      return;
+    }
+    const hasRoles = select.value.properties.some(
+      (prop) => j.ObjectProperty.check(prop) && j.Identifier.check(prop.key) && prop.key.name === "roles"
+    );
+    if (!hasRoles) {
+      select.value.properties.push(
+        j.objectProperty(j.identifier("roles"), j.booleanLiteral(true))
+      );
+      added = true;
+    }
+  });
+  return added;
+}
+function transform(fileInfo, _api, options = {}) {
+  const root = j.withParser("tsx")(fileInfo.source);
+  const getCurrentUser = findGetCurrentUser(root).at(0);
+  const fn = getCurrentUser.nodes()[0];
+  if (!j.ArrowFunctionExpression.check(fn) && !j.FunctionExpression.check(fn) && !j.FunctionDeclaration.check(fn)) {
+    throw new Error("CEDAR_CODEMOD_ERR_GET_CURRENT_USER_NOT_FOUND");
+  }
+  const isAsync = !!fn.async;
+  let wrapsAUser = false;
+  let changed = false;
+  if (j.BlockStatement.check(fn.body)) {
+    getCurrentUser.find(j.ReturnStatement).filter((path) => j(path).closest(j.Function).nodes()[0] === fn).forEach((path) => {
+      const argument = path.node.argument;
+      if (!argument || isNothing(argument)) {
+        return;
+      }
+      wrapsAUser = true;
+      if (!isWrapped(argument)) {
+        path.node.argument = wrap(argument, isAsync);
+        changed = true;
+      }
+    });
+  } else if (j.ArrowFunctionExpression.check(fn) && !isNothing(fn.body)) {
+    wrapsAUser = true;
+    if (!isWrapped(fn.body)) {
+      fn.body = wrap(fn.body, isAsync);
+      changed = true;
+    }
+  }
+  if (!wrapsAUser) {
+    throw new Error("CEDAR_CODEMOD_ERR_GET_CURRENT_USER_NOT_FOUND");
+  }
+  if (options.userHasRoles === true && selectRoles(getCurrentUser)) {
+    changed = true;
+  }
+  return addPermissionsImport(changed ? root.toSource() : fileInfo.source);
+}
+export {
+  transform as default
+};

package/dist/commands/setup/permissions/permissions.js

@@ -0,0 +1,25 @@
+import { recordTelemetryAttributes } from "@cedarjs/cli-helpers/telemetry";
+const command = "permissions";
+const description = "Set up permissions: a map of what each role may do, checked with @requirePermission and hasPermission";
+const builder = (yargs) => {
+  yargs.option("force", {
+    alias: "f",
+    default: false,
+    description: "Overwrite existing configuration",
+    type: "boolean"
+  });
+};
+const handler = async (options) => {
+  recordTelemetryAttributes({
+    command: "setup permissions",
+    force: options.force
+  });
+  const { handler: handler2 } = await import("./permissionsHandler.js");
+  return handler2(options);
+};
+export {
+  builder,
+  command,
+  description,
+  handler
+};

package/dist/commands/setup/permissions/permissionsHandler.js

@@ -0,0 +1,229 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Listr } from "listr2";
+import { format } from "prettier";
+import { terminalLink } from "termi-link";
+import { colors as c } from "@cedarjs/cli-helpers/colors";
+import { getPrettierOptions } from "@cedarjs/cli-helpers/fileHelpers";
+import { addApiPackages } from "@cedarjs/cli-helpers/installHelpers";
+import { formatCedarCommand } from "@cedarjs/cli-helpers/packageManager/display";
+import { runBinSync } from "@cedarjs/cli-helpers/packageManager/exec";
+import { getPrismaSchemas } from "@cedarjs/project-config";
+import { errorTelemetry } from "@cedarjs/telemetry";
+import { getPaths, transformTSToJS, writeFile } from "../../../lib/index.js";
+import { isTypeScriptProject } from "../../../lib/project.js";
+import { runTransform } from "../../../lib/runTransform.js";
+import { hasWebAuthFile } from "../tenancy/preflight.js";
+import {
+  addPermissionsPackageTasks,
+  permissionsPackageName
+} from "./permissionsPackage.js";
+import { authNotSetUpMessage, hasTenancyMessage } from "./preflight.js";
+import {
+  findRoles,
+  permissionsIndexSource,
+  userModelHasRoles
+} from "./roles.js";
+const AUTH_SNIPPET = `
+  import { withPermissions } from 'src/lib/permissions'
+
+  export const getCurrentUser = async (session) => {
+    return withPermissions(await db.user.findUnique({
+      where: { id: session.id },
+      select: { id: true, roles: true },
+    }))
+  }`;
+const templatePath = (templateFile) => path.resolve(import.meta.dirname, "templates", templateFile);
+function dependsOnTenancy(packageJsonPath) {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    return !!packageJson.dependencies?.["@cedarjs/tenancy"] || !!packageJson.devDependencies?.["@cedarjs/tenancy"];
+  } catch {
+    return false;
+  }
+}
+const handler = async ({ force }) => {
+  const paths = getPaths();
+  if (!hasWebAuthFile(paths.web.src)) {
+    console.error(c.error(authNotSetUpMessage()));
+    process.exit(1);
+  }
+  if (dependsOnTenancy(path.join(paths.api.base, "package.json"))) {
+    console.error(c.error(hasTenancyMessage()));
+    process.exit(1);
+  }
+  const projectIsTypescript = isTypeScriptProject();
+  const ext = projectIsTypescript ? "ts" : "js";
+  const packageJson = await import(pathToFileURL(path.join(paths.base, "package.json")).href, { with: { type: "json" } });
+  const cedarVersion = packageJson.default.devDependencies["@cedarjs/core"] ?? "latest";
+  const authPath = path.join(paths.api.lib, `auth.${ext}`);
+  const roles = findRoles([paths.api.src, paths.web.src]);
+  const writtenFiles = [];
+  const keptFiles = [];
+  const writeTemplateFile = async (templateFile, outputPath) => {
+    const templateContent = fs.readFileSync(templatePath(templateFile), "utf-8").replaceAll("__PERMISSIONS_PACKAGE__", permissionsPackageName());
+    if (fs.existsSync(outputPath) && !force) {
+      keptFiles.push(outputPath);
+      return;
+    }
+    const content = projectIsTypescript ? templateContent : await transformTSToJS(outputPath, templateContent);
+    writtenFiles.push(outputPath);
+    return writeFile(outputPath, content, { overwriteExisting: force });
+  };
+  const tasks = new Listr(
+    [
+      {
+        ...addApiPackages([`@cedarjs/permissions@${cedarVersion}`]),
+        title: "Adding @cedarjs/permissions to your api side..."
+      },
+      {
+        title: "Adding the permissions package...",
+        task: () => addPermissionsPackageTasks({
+          cedarVersion,
+          indexSource: permissionsIndexSource(
+            fs.readFileSync(
+              templatePath("permissionsPackage.index.ts.template"),
+              "utf-8"
+            ),
+            roles
+          ),
+          force
+        })
+      },
+      {
+        title: "Adding permission checks and the requirePermission directive...",
+        task: async () => {
+          await writeTemplateFile(
+            "permissions.ts.template",
+            path.join(paths.api.lib, `permissions.${ext}`)
+          );
+          const directiveDir = path.join(
+            paths.api.directives,
+            "requirePermission"
+          );
+          await writeTemplateFile(
+            "requirePermission.ts.template",
+            path.join(directiveDir, `requirePermission.${ext}`)
+          );
+          await writeTemplateFile(
+            "requirePermission.test.ts.template",
+            path.join(directiveDir, `requirePermission.test.${ext}`)
+          );
+        }
+      },
+      {
+        title: "Adding the user\u2019s permissions to getCurrentUser...",
+        task: async (_ctx, task) => {
+          if (!fs.existsSync(authPath)) {
+            task.skip("No api/src/lib/auth file found; skipping.");
+            return;
+          }
+          let userHasRoles = false;
+          try {
+            const { schemas } = await getPrismaSchemas();
+            userHasRoles = userModelHasRoles(
+              schemas.map(([, schema]) => schema).join("\n")
+            );
+          } catch {
+          }
+          const transformResult = await runTransform({
+            transformPath: path.join(import.meta.dirname, "authCodemod.js"),
+            targetPaths: [authPath],
+            options: { userHasRoles }
+          });
+          if (transformResult.error) {
+            task.output = `Could not update api/src/lib/auth automatically. Please add this by hand:
+${AUTH_SNIPPET}`;
+          }
+        }
+      },
+      {
+        title: "Formatting and linting changed files...",
+        task: async (_ctx, task) => {
+          const changedFiles = [...writtenFiles, authPath].filter(
+            (file) => fs.existsSync(file)
+          );
+          const prettierOptions = await getPrettierOptions();
+          for (const file of changedFiles) {
+            try {
+              const source = fs.readFileSync(file, "utf-8");
+              const formatted = await format(source, {
+                ...prettierOptions,
+                parser: "babel-ts"
+              });
+              fs.writeFileSync(file, formatted, "utf-8");
+            } catch {
+              task.output = "Couldn't prettify the changes. Please reformat the files manually if needed.";
+            }
+          }
+          try {
+            runBinSync("eslint", ["--fix", ...changedFiles], {
+              cwd: paths.base
+            });
+          } catch {
+            task.output = `Some of the changed files still have lint errors. Run ${c.highlight(
+              formatCedarCommand(["lint"])
+            )} to see them.`;
+          }
+        }
+      },
+      {
+        title: "Next steps...",
+        task: (ctx, task) => {
+          const rolesText = roles.length > 0 ? `It has an entry, with no permissions yet, for each role
+             your role lists name: ${roles.map((role) => c.highlight(role)).join(", ")}.` : `It has an example map, as no role lists name a role.`;
+          task.title = `Next steps...
+
+          ${c.success("\nPermissions configured!\n")}
+          1. 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)` : ""}.
+             ${rolesText}
+             A role is a bundle of permissions: list what each one may do.
+          2. A user may do what any of their roles, in ${c.highlight("currentUser.roles")},
+             may do, so ${c.highlight("getCurrentUser")} returns ${c.highlight("roles")}: this selects
+             them when your ${c.highlight("User")} model has a ${c.highlight("roles")} field. Without one,
+             return the user's roles from where they're kept. It returns the
+             user through ${c.highlight("withPermissions")}, which adds
+             ${c.highlight("currentUser.permissions")} for the web.
+          3. Guard fields with ${c.highlight('@requirePermission(permission: "...")')}, and
+             services with ${c.highlight("requirePermission('...')")} from src/lib/permissions.
+             A field with a ${c.highlight("roles")} list checks those roles; move each to a
+             permission that names what it allows, so a new role can do
+             only what its entry in the map says.
+          4. On the web, check permissions with ${c.highlight("useAuth().hasPermission()")}, and
+             guard routes with ${c.highlight('<PrivateSet permission="...">')}. A user without
+             it is sent to ${c.highlight("unauthorized")}. ${c.highlight(formatCedarCommand(["generate", "types"]))}
+             types the names.
+          5. In tests, ${c.highlight("mockCurrentUser({ roles: ['admin'] })")} gives the user
+             the permissions the map gives ${c.highlight("admin")}.
+${keptFiles.length > 0 ? `
+          Kept these existing files rather than overwriting them (run with
+          ${c.highlight("--force")} to overwrite):
+${keptFiles.map((file) => `            ${path.relative(paths.base, file)}`).join("\n")}
+` : ""}
+          Check out the docs for more info:
+          ${terminalLink("", "https://cedarjs.com/docs/permissions")}
+
+        `;
+        }
+      }
+    ],
+    {
+      rendererOptions: { collapseSubtasks: false }
+    }
+  );
+  try {
+    await tasks.run();
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const exitCode = e instanceof Error && "exitCode" in e && typeof e.exitCode === "number" ? e.exitCode : 1;
+    errorTelemetry(process.argv, message);
+    console.error(c.error(message));
+    process.exit(exitCode);
+  }
+};
+export {
+  handler
+};

package/dist/commands/setup/{tenancy → permissions}/permissionsPackage.js

@@ -28,7 +28,7 @@ function enablePackagesWorkspace(tomlContent) {
   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."
+        "CEDAR_PERMISSIONS_ERR_PACKAGES_WORKSPACE: set `experimental.packagesWorkspace.enabled = true` in cedar.toml and run this command again."
       );
     }
     return tomlContent.replace(/\n*$/, "") + `
@@ -98,7 +98,7 @@ function permissionsPackageFiles({
       watch: "tsc --watch"
     },
     dependencies: {
-      "@cedarjs/tenancy": cedarVersion
+      "@cedarjs/permissions": cedarVersion
     },
     devDependencies: {
       typescript: "5.9.3"

package/dist/commands/setup/permissions/preflight.js

@@ -0,0 +1,25 @@
+import { formatCedarCommand } from "@cedarjs/cli-helpers/packageManager/display";
+function authNotSetUpMessage() {
+  return [
+    "Auth is not set up in this project.",
+    "",
+    "Permissions build on your app's auth: a user may do what their roles,",
+    "in `currentUser.roles`, may do. Set up auth first, then run this",
+    "command again:",
+    "",
+    `  ${formatCedarCommand(["setup", "auth", "dbAuth"])}`,
+    "",
+    "Any provider works. See https://cedarjs.com/docs/authentication"
+  ].join("\n");
+}
+function hasTenancyMessage() {
+  return [
+    "This app has tenancy, which includes permissions: they are in",
+    "packages/permissions, and api/src/lib/permissions checks them against",
+    "the user's role in the current organization."
+  ].join("\n");
+}
+export {
+  authNotSetUpMessage,
+  hasTenancyMessage
+};

package/dist/commands/setup/permissions/roles.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+const SOURCE_FILE = /\.(?:[jt]sx?)$/;
+const NOT_APP_CODE = /\.(?:test|spec|scenarios|mock|mocks|stories)\.[jt]sx?$/;
+const LIST = String.raw`(\[[^\]]*\]|'[^'\n]*'|"[^"\n]*")`;
+const ROLE_LISTS = [
+  // `@requireAuth(roles: ["admin"])` in an SDL, `requireAuth({ roles: 'admin' })`
+  new RegExp(String.raw`\broles\s*:\s*` + LIST, "g"),
+  // `<PrivateSet roles="admin">`, `<PrivateSet roles={['admin', 'editor']}>`
+  new RegExp(String.raw`\broles\s*=\s*\{?\s*` + LIST, "g"),
+  // `hasRole('admin')`, `hasRole(['admin', 'editor'])`
+  new RegExp(String.raw`\bhasRole\(\s*` + LIST, "g")
+];
+const STRING = /'([^'\n]*)'|"([^"\n]*)"/g;
+function rolesInSource(source) {
+  const roles = /* @__PURE__ */ new Set();
+  for (const pattern of ROLE_LISTS) {
+    for (const [, list] of source.matchAll(pattern)) {
+      for (const [, single, double] of list.matchAll(STRING)) {
+        const role = (single ?? double).trim();
+        if (role) {
+          roles.add(role);
+        }
+      }
+    }
+  }
+  return [...roles];
+}
+function sourceFiles(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  return fs.readdirSync(dir, { recursive: true, encoding: "utf-8" }).filter(
+    (file) => SOURCE_FILE.test(file) && !NOT_APP_CODE.test(file) && !file.split(path.sep).includes("node_modules")
+  ).map((file) => path.join(dir, file));
+}
+function findRoles(dirs) {
+  const roles = /* @__PURE__ */ new Set();
+  for (const file of dirs.flatMap(sourceFiles)) {
+    for (const role of rolesInSource(fs.readFileSync(file, "utf-8"))) {
+      roles.add(role);
+    }
+  }
+  return [...roles].sort();
+}
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const key = (role) => IDENTIFIER.test(role) ? role : JSON.stringify(role);
+function permissionsIndexSource(template, roles) {
+  const rolesComment = roles.length > 0 ? [
+    " * These are the roles the app's role lists name, with no",
+    " * permissions yet. Add the permissions each one needs, then guard",
+    " * fields with them instead of `roles`."
+  ].join("\n") : [
+    " * An example map: replace these permissions and roles with the",
+    " * app's own."
+  ].join("\n");
+  const definitions = roles.length > 0 ? [
+    "  permissions: [],",
+    "  roles: {",
+    ...roles.map((role) => `    ${key(role)}: [],`),
+    "  },"
+  ] : [
+    "  permissions: ['posts.read', 'posts.edit'],",
+    "  roles: {",
+    "    editor: ['posts.read', 'posts.edit'],",
+    "    reader: ['posts.read'],",
+    "  },"
+  ];
+  return template.replace("__ROLES_COMMENT__", rolesComment).replace("__DEFINITIONS__", definitions.join("\n"));
+}
+function userModelHasRoles(schema) {
+  const userModel = schema.match(/^model\s+User\s*\{([\s\S]*?)^\}/m)?.[1];
+  return !!userModel && /^\s*roles\s+\S/m.test(userModel);
+}
+export {
+  findRoles,
+  permissionsIndexSource,
+  rolesInSource,
+  userModelHasRoles
+};

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

@@ -0,0 +1,23 @@
+import { permissions } from '__PERMISSIONS_PACKAGE__'
+
+import { createPermissions } from '@cedarjs/permissions/api'
+
+/**
+ * Checks the permissions defined in __PERMISSIONS_PACKAGE__
+ * (packages/permissions): a user may do what any of their roles, in
+ * `currentUser.roles`, may do. `getCurrentUser` adds the user's permissions
+ * with `withPermissions`, so the web can check them with
+ * `useAuth().hasPermission()` and `<PrivateSet permission>`. The web only
+ * uses them to decide what to show. These checks are the guard.
+ *
+ * `canGrantRole(role)` is whether the signed-in user may give someone
+ * `role`, or take it away. They may if they hold every permission the role
+ * has, so nobody can hand out more than they may do themselves.
+ */
+export const {
+  hasPermission,
+  requirePermission,
+  canGrantRole,
+  permissionsOf,
+  withPermissions,
+} = createPermissions(permissions)

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

@@ -0,0 +1,28 @@
+import { definePermissions } from '@cedarjs/permissions'
+import type { PermissionName } from '@cedarjs/permissions'
+
+/**
+ * Every permission the app checks, and what each role may do. A role is a
+ * named bundle of permissions.
+ *
+ * Fields and services ask for a permission, never a role:
+ * `@requirePermission(permission: "posts.edit")` on a field, and
+ * `requirePermission('posts.edit')` in a service. So a role can do exactly
+ * what its list says. A field added later is closed to a role until its
+ * permission is on that role's list.
+ *
+ * A user's roles are in `currentUser.roles` (one role, or a list of them),
+ * and they may do what any of their roles may do. A role that isn't listed
+ * here may do nothing.
+ *
+__ROLES_COMMENT__
+ *
+ * This package is shared: the api checks these permissions
+ * (api/src/lib/permissions), and the web can import the names. The web gets
+ * the user's permissions from the api, through `getCurrentUser`.
+ */
+export const permissions = definePermissions({
+__DEFINITIONS__
+})
+
+export type Permission = PermissionName<typeof permissions>

package/dist/commands/setup/permissions/templates/requirePermission.test.ts.template

@@ -0,0 +1,60 @@
+import { permissions } from '__PERMISSIONS_PACKAGE__'
+
+import { mockRedwoodDirective, getDirectiveName } from '@cedarjs/testing/api'
+
+import requirePermission from './requirePermission.js'
+
+/** A role in packages/permissions with a permission, and that permission */
+const granted = Object.entries(permissions.roles)
+  .flatMap(([role, names]) => names.map((permission) => ({ role, permission })))
+  .at(0)
+
+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: granted?.permission },
+    })
+
+    expect(mockExecution).toThrowError()
+  })
+
+  it('throws for a permission that packages/permissions does not define', () => {
+    const mockExecution = mockRedwoodDirective(requirePermission, {
+      context: { currentUser: {} },
+      directiveArgs: { permission: 'not.defined' },
+    })
+
+    expect(mockExecution).toThrowError('Unknown permission "not.defined"')
+  })
+
+  if (granted) {
+    it('throws for a user without roles', () => {
+      const mockExecution = mockRedwoodDirective(requirePermission, {
+        context: { currentUser: {} },
+        directiveArgs: { permission: granted.permission },
+      })
+
+      expect(mockExecution).toThrowError()
+    })
+
+    it("passes when one of the user's roles has it", () => {
+      const mockExecution = mockRedwoodDirective(requirePermission, {
+        // One role, as a string. A list of roles works too.
+        context: { currentUser: { roles: granted.role } },
+        directiveArgs: { permission: granted.permission },
+      })
+
+      expect(mockExecution).not.toThrowError()
+    })
+  } else {
+    it.todo(
+      "passes when one of the user's roles has it, once a role in packages/permissions has a permission",
+    )
+  }
+})

package/dist/commands/setup/{tenancy → permissions}/templates/requirePermission.ts.template

@@ -8,21 +8,26 @@ import { requirePermission as applicationRequirePermission } from 'src/lib/permi
 
 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).
+  Use to check that the signed-in user may do something: that they have the
+  permission (see packages/permissions and api/src/lib/permissions).
   """
   directive @requirePermission(permission: String!) on FIELD_DEFINITION
 `
 
-// Optional to fit `ValidatorDirectiveFunc`; the SDL makes it required
+// Optional to fit `ValidatorDirectiveFunc`; the SDL makes it required. Any
+// name can reach it from an SDL, which `requirePermission` checks.
 type RequirePermissionValidate = ValidatorDirectiveFunc<{
-  permission?: string
+  permission?: Permission
 }>
 
 const validate: RequirePermissionValidate = ({ directiveArgs }) => {
+  if (directiveArgs.permission === undefined) {
+    throw new Error('@requirePermission needs a `permission`')
+  }
+
   // 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(directiveArgs.permission as Permission)
+  applicationRequirePermission(directiveArgs.permission)
 }
 
 const requirePermission = createValidatorDirective(schema, validate)

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

@@ -6,12 +6,14 @@ 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.
+ * `useAuth().hasPermission()` and `<PrivateSet permission>`. The web only
+ * uses them to decide what to show. These checks are the guard.
  *
- * `canGrantRole` is who may give someone a role, or take it away: whoever
- * holds every permission it has (`inviteMember` and `removeMember` in
- * api/src/services/organizations).
+ * `canGrantRole(role)` is whether the signed-in user may give someone
+ * `role`, or take it away. They may if they hold every permission the role
+ * has, so nobody can hand out more than they may do themselves.
+ * `inviteMember` and `removeMember` in api/src/services/organizations use
+ * it.
  */
 export const {
   hasPermission,

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

@@ -1,13 +1,16 @@
-import { definePermissions } from '@cedarjs/tenancy/permissions'
-import type { PermissionName } from '@cedarjs/tenancy/permissions'
+import { definePermissions } from '@cedarjs/permissions'
+import type { PermissionName } from '@cedarjs/permissions'
 
 /**
- * Every permission the app checks, and what each role may do: a role is a
- * named bundle of permissions. Fields ask for a permission
- * (`@requirePermission(permission: "members.manage")`, or
- * `requirePermission('members.manage')` in a service), never a role, 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.
+ * Every permission the app checks, and what each role may do. A role is a
+ * named bundle of permissions.
+ *
+ * Fields and services ask for a permission, never a role:
+ * `@requirePermission(permission: "members.manage")` on a field, and
+ * `requirePermission('members.manage')` in a service. So a role can do
+ * exactly what its list says, and adding a role is one entry here. A field
+ * added later is closed to a role until its permission is on that role's
+ * list.
  *
  * `organization.read` is "any member": every role lists it, and fields any
  * member may use ask for it. `organization.manage` is the owner's alone,

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

@@ -16,10 +16,10 @@ import { createTenancy } from '@cedarjs/tenancy/web'
  *
  * A user who isn't signed in is sent to log in, and one who isn't a member
  * of the organization sees `notAMember`. Pages only some members may open
- * take `orgPermission` (see packages/permissions), and the one a member
+ * take a `permission` (see packages/permissions), and the one a member
  * without it is sent to is `unauthorized`:
  *
- *   <PrivateSet unauthenticated="login" unauthorized="projects" orgPermission="members.manage">
+ *   <PrivateSet unauthenticated="login" unauthorized="projects" permission="members.manage">
  *     <Route path="/org/{orgSlug}/members" page={MembersPage} name="members" />
  *   </PrivateSet>
  *

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

@@ -23,7 +23,7 @@ import { runTransform } from "../../../lib/runTransform.js";
 import {
   addPermissionsPackageTasks,
   permissionsPackageName
-} from "./permissionsPackage.js";
+} from "../permissions/permissionsPackage.js";
 import {
   authNotSetUpMessage,
   hasWebAuthFile,
@@ -97,21 +97,21 @@ const handler = async ({ tenantField, force }) => {
   const isDbAuthProject = fs.existsSync(functionsAuthPath) && fs.readFileSync(functionsAuthPath, "utf-8").includes("DbAuthHandler");
   const writtenFiles = [];
   const keptFiles = [];
-  const writeTemplateFile = async (templateFile, outputPath, replacements = {}, transform = (content) => content) => {
+  const writeTemplateFile = async (templateFile, outputPath, replacements = {}, transform = (content) => content, replaces = () => false) => {
     const dirname = import.meta.dirname;
-    const templatePath = path.resolve(dirname, "templates", templateFile);
+    const templatePath = templateFile.startsWith("requirePermission.ts") ? path.resolve(dirname, "../permissions/templates", templateFile) : path.resolve(dirname, "templates", templateFile);
     let templateContent = fs.readFileSync(templatePath, "utf-8");
     for (const [token, value] of Object.entries(replacements)) {
       templateContent = templateContent.replaceAll(token, value);
     }
     templateContent = transform(templateContent);
     const content = projectIsTypescript ? templateContent : await transformTSToJS(outputPath, templateContent);
-    if (fs.existsSync(outputPath) && !force) {
+    if (fs.existsSync(outputPath) && !force && !replaces(fs.readFileSync(outputPath, "utf-8"))) {
       keptFiles.push(outputPath);
       return;
     }
     writtenFiles.push(outputPath);
-    return writeFile(outputPath, content, { overwriteExisting: force });
+    return writeFile(outputPath, content, { overwriteExisting: true });
   };
   const tasks = new Listr(
     [
@@ -257,30 +257,65 @@ ${SIGNUP_SNIPPET}`;
       },
       {
         title: "Adding the permissions package...",
-        task: () => addPermissionsPackageTasks({
-          cedarVersion,
-          indexSource: fs.readFileSync(
-            path.resolve(
-              import.meta.dirname,
-              "templates",
-              "permissionsPackage.index.ts.template"
+        task: (ctx) => {
+          const indexPath = path.join(
+            paths.packages,
+            "permissions",
+            "src",
+            "index.ts"
+          );
+          ctx.mapNeedsOrgPermissions = !force && fs.existsSync(indexPath) && !fs.readFileSync(indexPath, "utf-8").includes("organization.read");
+          return addPermissionsPackageTasks({
+            cedarVersion,
+            indexSource: fs.readFileSync(
+              path.resolve(
+                import.meta.dirname,
+                "templates",
+                "permissionsPackage.index.ts.template"
+              ),
+              "utf-8"
             ),
-            "utf-8"
-          ),
-          force
-        })
+            force
+          });
+        }
       },
       {
         title: "Adding permission checks and the requirePermission directive...",
-        task: async () => {
+        task: async (ctx) => {
           const replacements = {
             __PERMISSIONS_PACKAGE__: permissionsPackageName()
           };
+          const libPermissionsPath = path.join(
+            paths.api.lib,
+            `permissions.${ext}`
+          );
+          const asCode = (source) => source.replace(/\s+|;/g, "").replaceAll('"', "'");
+          const isSetupPermissionsFile = async (templateFile, outputPath) => {
+            let source = fs.readFileSync(
+              path.resolve(
+                import.meta.dirname,
+                "../permissions/templates",
+                templateFile
+              ),
+              "utf-8"
+            );
+            for (const [token, value] of Object.entries(replacements)) {
+              source = source.replaceAll(token, value);
+            }
+            const generated = projectIsTypescript ? source : await transformTSToJS(outputPath, source);
+            return (existing) => asCode(existing) === asCode(generated);
+          };
           await writeTemplateFile(
             "permissions.ts.template",
-            path.join(paths.api.lib, `permissions.${ext}`),
-            replacements
+            libPermissionsPath,
+            replacements,
+            void 0,
+            await isSetupPermissionsFile(
+              "permissions.ts.template",
+              libPermissionsPath
+            )
           );
+          ctx.libPermissionsNeedsMembership = !force && fs.readFileSync(libPermissionsPath, "utf-8").includes("@cedarjs/permissions/api");
           const directiveDir = path.join(
             paths.api.directives,
             "requirePermission"
@@ -290,10 +325,21 @@ ${SIGNUP_SNIPPET}`;
             path.join(directiveDir, `requirePermission.${ext}`),
             replacements
           );
+          const directiveTestPath = path.join(
+            directiveDir,
+            `requirePermission.test.${ext}`
+          );
           await writeTemplateFile(
             "requirePermission.test.ts.template",
-            path.join(directiveDir, `requirePermission.test.${ext}`)
+            directiveTestPath,
+            {},
+            void 0,
+            await isSetupPermissionsFile(
+              "requirePermission.test.ts.template",
+              directiveTestPath
+            )
           );
+          ctx.directiveTestMocksRoles = !force && fs.readFileSync(directiveTestPath, "utf-8").includes("one of the user's roles has it");
         }
       },
       {
@@ -514,15 +560,41 @@ ${ctx.routerNeedsTenancy ? `
              what the user's role there may do.
           7. Roles are the user's own: ${c.highlight("hasRole")} and ${c.highlight("<PrivateSet roles>")}
              check ${c.highlight("currentUser.roles")}. In an organization, check a
-             permission instead: guard routes with ${c.highlight("<PrivateSet orgPermission>")}
-             for a permission of their membership in the route's organization.
+             permission instead: guard routes with ${c.highlight("<PrivateSet permission>")},
+             which checks their membership in the route's organization.
              A member who lacks it is sent to ${c.highlight("unauthorized")}:
 
-               <PrivateSet unauthenticated="login" unauthorized="projects" orgPermission="organization.manage">
+               <PrivateSet unauthenticated="login" unauthorized="projects" permission="organization.manage">
                  <Route path="/org/{orgSlug}/settings" page={SettingsPage} name="settings" />
                </PrivateSet>
 
-${keptFiles.length > 0 ? `
+${ctx.libPermissionsNeedsMembership ? `
+          ${c.warning("Kept your api/src/lib/permissions.")}
+          Its checks use ${c.highlight("createPermissions")} from ${c.highlight("@cedarjs/permissions/api")},
+          which checks ${c.highlight("currentUser.roles")}. In an organization, a role belongs to
+          the membership: import ${c.highlight("createPermissions")} from ${c.highlight("@cedarjs/tenancy")} instead.
+
+` : ""}${ctx.directiveTestMocksRoles ? `
+          ${c.warning("Kept your api/src/directives/requirePermission test.")}
+          It mocks users with ${c.highlight("roles")}. With tenancy, permissions come from
+          the user's membership in the current organization: mock
+          ${c.highlight("memberships")} and ${c.highlight("context.currentOrg")} instead.
+
+` : ""}${ctx.mapNeedsOrgPermissions ? `
+          ${c.warning("Kept your permission map in packages/permissions.")}
+          Its roles are now roles in an organization. Add the permissions the
+          generated organizations service checks, and give its member roles
+          these permissions, next to any they already have:
+
+            permissions: [...yours, 'organization.read', 'organization.manage', 'members.manage'],
+            roles: {
+              ...yours,
+              owner: [...(yours.owner ?? []), 'organization.read', 'organization.manage', 'members.manage'],
+              admin: [...(yours.admin ?? []), 'organization.read', 'members.manage'],
+              member: [...(yours.member ?? []), 'organization.read'],
+            },
+
+` : ""}${keptFiles.length > 0 ? `
           Kept these existing files rather than overwriting them (run with
           ${c.highlight("--force")} to overwrite):
 ${keptFiles.map((file) => `            ${path.relative(paths.base, file)}`).join("\n")}

package/dist/commands/setup.js

@@ -14,6 +14,7 @@ import * as setupMiddleware from "./setup/middleware/middleware.js";
 import * as setupMonitoring from "./setup/monitoring/monitoring.js";
 import * as setupNeon from "./setup/neon/neon.js";
 import * as setupPackage from "./setup/package/package.js";
+import * as setupPermissions from "./setup/permissions/permissions.js";
 import * as setupRealtime from "./setup/realtime/realtime.js";
 import * as setupServerFile from "./setup/server-file/serverFile.js";
 import * as setupTenancy from "./setup/tenancy/tenancy.js";
@@ -21,7 +22,7 @@ import * as setupUi from "./setup/ui/ui.js";
 import * as setupUploads from "./setup/uploads/uploads.js";
 const command = "setup <command>";
 const description = "Initialize project config and install packages";
-const builder = (yargs) => yargs.command(setupAuth).command(setupCache).command(setupDatabase).command(setupDeploy).command(setupDocker).command(setupGenerator).command(setupGraphql).command(setupI18n).command(setupJobs).command(setupMailer).command(setupMiddleware).command(setupMonitoring).command(setupNeon).command(setupPackage).command(setupRealtime).command(setupServerFile).command(setupTenancy).command(setupUi).command(setupUploads).demandCommand().middleware(detectCedarVersion).epilogue(
+const builder = (yargs) => yargs.command(setupAuth).command(setupCache).command(setupDatabase).command(setupDeploy).command(setupDocker).command(setupGenerator).command(setupGraphql).command(setupI18n).command(setupJobs).command(setupMailer).command(setupMiddleware).command(setupMonitoring).command(setupNeon).command(setupPackage).command(setupPermissions).command(setupRealtime).command(setupServerFile).command(setupTenancy).command(setupUi).command(setupUploads).demandCommand().middleware(detectCedarVersion).epilogue(
   `Also see the ${terminalLink(
     "CedarJS CLI Reference",
     "https://cedarjs.com/docs/cli-commands#setup"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedarjs/cli",
-  "version": "8.0.0-canary.3569",
+  "version": "8.0.0-canary.3571",
   "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.3569",
-    "@cedarjs/babel-config": "8.0.0-canary.3569",
-    "@cedarjs/cli-helpers": "8.0.0-canary.3569",
-    "@cedarjs/internal": "8.0.0-canary.3569",
-    "@cedarjs/prerender": "8.0.0-canary.3569",
-    "@cedarjs/project-config": "8.0.0-canary.3569",
-    "@cedarjs/structure": "8.0.0-canary.3569",
-    "@cedarjs/telemetry": "8.0.0-canary.3569",
-    "@cedarjs/utils": "8.0.0-canary.3569",
-    "@cedarjs/vite": "8.0.0-canary.3569",
-    "@cedarjs/web-server": "8.0.0-canary.3569",
+    "@cedarjs/api-server": "8.0.0-canary.3571",
+    "@cedarjs/babel-config": "8.0.0-canary.3571",
+    "@cedarjs/cli-helpers": "8.0.0-canary.3571",
+    "@cedarjs/internal": "8.0.0-canary.3571",
+    "@cedarjs/prerender": "8.0.0-canary.3571",
+    "@cedarjs/project-config": "8.0.0-canary.3571",
+    "@cedarjs/structure": "8.0.0-canary.3571",
+    "@cedarjs/telemetry": "8.0.0-canary.3571",
+    "@cedarjs/utils": "8.0.0-canary.3571",
+    "@cedarjs/vite": "8.0.0-canary.3571",
+    "@cedarjs/web-server": "8.0.0-canary.3571",
     "@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.3569",
+    "@cedarjs/framework-tools": "8.0.0-canary.3571",
     "@prisma/dmmf": "7.10.1",
     "@types/archiver": "^7.0.0",
     "memfs": "4.80.0",