@cedarjs/permissions 0.0.0-stage → 8.0.0-canary.3571

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @cedarjs/permissions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Permissions for a Cedar app: who may do what, defined in one place. A role is a
+named bundle of permissions.
+
+Fields, services and components check a permission, never a role. 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.
+
+`yarn cedar setup permissions` sets this up. In an app with tenancy
+(`yarn cedar setup tenancy`), `@cedarjs/tenancy` checks the same definitions
+against the user's role in the current organization.
+
+## Defining permissions
+
+The definitions live in the app's `packages/permissions`, shared by the api and
+web sides:
+
+```ts
+// packages/permissions/src/index.ts
+import { definePermissions } from '@cedarjs/permissions'
+import type { PermissionName } from '@cedarjs/permissions'
+
+const reader = ['posts.read'] as const
+
+export const permissions = definePermissions({
+  permissions: ['posts.read', 'posts.edit', 'users.manage'],
+  roles: {
+    admin: [...reader, 'posts.edit', 'users.manage'],
+    editor: [...reader, 'posts.edit'],
+    reader,
+  },
+})
+
+export type Permission = PermissionName<typeof permissions>
+```
+
+The explicit `permissions` list makes a typo in a role's list a type error (and
+an error at runtime) instead of a new permission. A role the definitions don't
+list has no permissions.
+
+`@cedarjs/permissions` is plain data and functions with no api code in it, so
+the web can import it too. It also exports:
+
+- `permissionsOf(definitions, roles)`: the permissions of a role, or of a list
+  of roles (their union). The one place a role becomes permissions.
+- `coversRole(definitions, held, role)`: whether the permissions in `held`
+  include every permission of `role`.
+- `isPermission(definitions, name)` and `assertPermission(definitions, name)`:
+  whether `name` is defined, as a type guard or an assertion.
+
+## Checking permissions on the api
+
+`createPermissions` from `@cedarjs/permissions/api` checks the signed-in user's
+permissions: those of their roles, in `currentUser.roles` (one role or a list of
+them).
+
+```ts
+// api/src/lib/permissions.ts
+import { createPermissions } from '@cedarjs/permissions/api'
+
+import { permissions } from '@my-app/permissions'
+
+export const {
+  hasPermission,
+  requirePermission,
+  canGrantRole,
+  permissionsOf,
+  withPermissions,
+} = createPermissions(permissions)
+```
+
+- `hasPermission('posts.edit')`: whether one of the user's roles has it. False
+  when no one is signed in.
+- `requirePermission('posts.edit')`: throws `AuthenticationError` when no one is
+  signed in, and `ForbiddenError` when they may not.
+- `canGrantRole(role)`: whether the user may give someone `role`, or take it
+  away: they hold every permission it has, so no one can hand out more than they
+  may do themselves. False for a role the definitions don't list.
+- `permissionsOf(user)`: the permissions of `user.roles`.
+- `withPermissions(user)`: `user` with a `permissions` list added, for
+  `getCurrentUser` to return.
+
+Permission names are typed from the definitions, so a typo in a service is a
+type error. A name that isn't defined (a typo in an SDL directive) throws.
+
+Fields use the `@requirePermission` directive that setup adds:
+
+```graphql
+type Mutation {
+  updatePost(id: Int!, input: UpdatePostInput!): Post!
+    @requirePermission(permission: "posts.edit")
+}
+```
+
+## On the web
+
+`getCurrentUser` returns the user through `withPermissions`, so
+`currentUser.permissions` has the user's permissions, and
+`useAuth().hasPermission('posts.edit')` and
+`<PrivateSet permission="posts.edit">` check them. The web only decides what to
+show; the api's checks are the guard.
+
+## In tests
+
+`mockCurrentUser({ roles: ['editor'] })` gives the user the permissions the
+app's definitions give `editor`, on the api and on the web.

package/dist/api.d.ts

@@ -0,0 +1,64 @@
+import type { PermissionDefinitions } from './definePermissions.js';
+/** A user as `getCurrentUser` returns it, with its permissions */
+export type WithPermissions<User, Permission extends string> = User & {
+    permissions: Permission[];
+};
+export interface Permissions<Permission extends string> {
+    /**
+     * Whether the signed-in user may do `permission`: one of their roles,
+     * in `currentUser.roles`, has it. False when no one is signed in.
+     */
+    hasPermission(permission: Permission): boolean;
+    /**
+     * Guards a service or directive on `hasPermission(permission)`. Throws
+     * `AuthenticationError` when no one is signed in, and `ForbiddenError`
+     * when they may not.
+     */
+    requirePermission(permission: Permission): void;
+    /**
+     * Whether the signed-in user may give `role` to someone, or take it
+     * away: they hold every permission `role` has, so no one can hand out
+     * more than they may do themselves. False for a role the definitions
+     * don't list.
+     *
+     * This is only the role half: who may manage users at all is a
+     * permission of its own (`users.manage`, say) on the field.
+     */
+    canGrantRole(role: string): boolean;
+    /**
+     * What `user` may do: the permissions of each of its roles, from
+     * `user.roles` (one role, or a list of them). The one place a user's
+     * permissions are worked out, which `hasPermission`, `requirePermission`
+     * and `withPermissions` all use.
+     */
+    permissionsOf(user: unknown): Permission[];
+    /**
+     * `user` with its permissions added, for `getCurrentUser` to return, so
+     * the web gets them (`useAuth().hasPermission`)
+     */
+    withPermissions<User extends object>(user: User): WithPermissions<User, Permission>;
+    withPermissions<User extends object>(user: User | null): WithPermissions<User, Permission> | null;
+}
+/**
+ * Permissions on top of the user's roles: roles map to permissions in one
+ * place, and fields and services ask for a permission instead of listing
+ * roles, so adding a role is one entry in the definitions instead of an
+ * edit to every field it should reach.
+ *
+ * ```ts
+ * // api/src/lib/permissions.ts
+ * import { permissions } from '@my-app/permissions'
+ *
+ * export const { hasPermission, requirePermission, canGrantRole, withPermissions } =
+ *   createPermissions(permissions)
+ * ```
+ *
+ * `permissions` comes from `definePermissions`. A user's permissions are
+ * those of their roles, in `currentUser.roles`. Fails closed: a user whose
+ * roles don't have the permission is refused, as is a role the definitions
+ * don't list. Permission names are typed, so a typo in a service is a type
+ * error; a name that isn't defined (a typo in an SDL directive) throws
+ * instead of quietly refusing everyone.
+ */
+export declare function createPermissions<const Permission extends string>(definitions: PermissionDefinitions<Permission>): Permissions<Permission>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAEnE,kEAAkE;AAClE,MAAM,MAAM,eAAe,CAAC,IAAI,EAAE,UAAU,SAAS,MAAM,IAAI,IAAI,GAAG;IACpE,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B,CAAA;AAED,MAAM,WAAW,WAAW,CAAC,UAAU,SAAS,MAAM;IACpD;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAA;IAC9C;;;;OAIG;IACH,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;IAC/C;;;;;;;;OAQG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACnC;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,EAAE,CAAA;IAC1C;;;OAGG;IACH,eAAe,CAAC,IAAI,SAAS,MAAM,EACjC,IAAI,EAAE,IAAI,GACT,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACpC,eAAe,CAAC,IAAI,SAAS,MAAM,EACjC,IAAI,EAAE,IAAI,GAAG,IAAI,GAChB,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,IAAI,CAAA;CAC5C;AAmBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,UAAU,SAAS,MAAM,EAC/D,WAAW,EAAE,qBAAqB,CAAC,UAAU,CAAC,GAC7C,WAAW,CAAC,UAAU,CAAC,CA6CzB"}

package/dist/api.js

@@ -0,0 +1,55 @@
+import { context } from "@cedarjs/context";
+import { AuthenticationError, ForbiddenError } from "@cedarjs/graphql-server";
+import {
+  assertPermission,
+  assertPermissionDefinitions,
+  coversRole,
+  permissionsOf
+} from "./definePermissions.js";
+function rolesOf(user) {
+  if (typeof user !== "object" || user === null || !("roles" in user)) {
+    return [];
+  }
+  const { roles } = user;
+  if (typeof roles === "string") {
+    return [roles];
+  }
+  return Array.isArray(roles) ? roles.filter((role) => typeof role === "string") : [];
+}
+function createPermissions(definitions) {
+  assertPermissionDefinitions(definitions);
+  const userPermissions = (user) => permissionsOf(definitions, rolesOf(user));
+  const hasPermission = (permission) => {
+    assertPermission(definitions, permission);
+    return userPermissions(context.currentUser).includes(permission);
+  };
+  function withPermissions(user) {
+    if (!user) {
+      return null;
+    }
+    return { ...user, permissions: userPermissions(user) };
+  }
+  return {
+    hasPermission,
+    permissionsOf: userPermissions,
+    withPermissions,
+    canGrantRole(role) {
+      if (!context.currentUser) {
+        return false;
+      }
+      return coversRole(definitions, userPermissions(context.currentUser), role);
+    },
+    requirePermission(permission) {
+      assertPermission(definitions, permission);
+      if (!context.currentUser) {
+        throw new AuthenticationError("You don't have permission to do that.");
+      }
+      if (!hasPermission(permission)) {
+        throw new ForbiddenError("You don't have access to do that.");
+      }
+    }
+  };
+}
+export {
+  createPermissions
+};

package/dist/definePermissions.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Every permission an app checks, and what each role may do.
+ *
+ * Plain data with no api code in it, so both sides can import it: the api to
+ * check permissions (`createPermissions`), and the web for the names.
+ */
+export interface PermissionDefinitions<Name extends string = string> {
+    /**
+     * Every permission the app checks, by name. Fields, services and the web
+     * ask for these names, so they're defined in code. A name is a stable id,
+     * so it can also key what an app shows for it, such as translations.
+     */
+    permissions: readonly Name[];
+    /**
+     * What each role may do: a role is a named bundle of permissions. A role
+     * that isn't listed has no permissions.
+     */
+    roles: Readonly<Record<string, readonly Name[]>>;
+}
+/** The permission names in `definitions` */
+export type PermissionName<Definitions> = Definitions extends PermissionDefinitions<infer Name> ? Name : never;
+/**
+ * Throws when a role lists a permission that `permissions` doesn't define.
+ * The types catch this in TypeScript; this is for JavaScript, and for
+ * definitions built at runtime.
+ */
+export declare function assertPermissionDefinitions(definitions: PermissionDefinitions): void;
+/**
+ * Defines an app's permissions, and what each role may do. Permission names
+ * are typed from `permissions`, so a role listing a name that isn't defined
+ * is a type error.
+ *
+ * ```ts
+ * export const permissions = definePermissions({
+ *   permissions: ['projects.read', 'members.manage'],
+ *   roles: {
+ *     owner: ['projects.read', 'members.manage'],
+ *     member: ['projects.read'],
+ *   },
+ * })
+ * ```
+ *
+ * Pass the result to `createPermissions` on the api.
+ */
+export declare function definePermissions<const Name extends string>(definitions: {
+    permissions: readonly Name[];
+    roles: Readonly<Record<string, readonly NoInfer<Name>[]>>;
+}): PermissionDefinitions<Name>;
+/** Whether `name` is one of the permissions `definitions` defines */
+export declare function isPermission<Name extends string>(definitions: PermissionDefinitions<Name>, name: unknown): name is Name;
+/**
+ * Throws when `definitions` doesn't define `name`, so a typo (in an SDL
+ * directive, say) is an error instead of a check that refuses everyone
+ */
+export declare function assertPermission<Name extends string>(definitions: PermissionDefinitions<Name>, name: string): asserts name is Name;
+/**
+ * What `roles` may do: every permission any of them has. The one place a
+ * role becomes permissions. A role the definitions don't list has none.
+ */
+export declare function permissionsOf<Name extends string>(definitions: PermissionDefinitions<Name>, roles: string | readonly string[] | null | undefined): Name[];
+/**
+ * Whether `held` covers `role`: it has every permission `role` has. This is
+ * who may give someone a role, so no one can hand out more than they may do
+ * themselves. False for a role the definitions don't list.
+ */
+export declare function coversRole<Name extends string>(definitions: PermissionDefinitions<Name>, held: readonly string[], role: string): boolean;
+//# sourceMappingURL=definePermissions.d.ts.map

package/dist/definePermissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definePermissions.d.ts","sourceRoot":"","sources":["../src/definePermissions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACjE;;;;OAIG;IACH,WAAW,EAAE,SAAS,IAAI,EAAE,CAAA;IAC5B;;;OAGG;IACH,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC,CAAA;CACjD;AAED,4CAA4C;AAC5C,MAAM,MAAM,cAAc,CAAC,WAAW,IACpC,WAAW,SAAS,qBAAqB,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,CAAA;AAEtE;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,qBAAqB,QAanC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,WAAW,EAAE;IACxE,WAAW,EAAE,SAAS,IAAI,EAAE,CAAA;IAC5B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;CAC1D,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAI9B;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,IAAI,SAAS,MAAM,EAC9C,WAAW,EAAE,qBAAqB,CAAC,IAAI,CAAC,EACxC,IAAI,EAAE,OAAO,GACZ,IAAI,IAAI,IAAI,CAEd;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,MAAM,EAClD,WAAW,EAAE,qBAAqB,CAAC,IAAI,CAAC,EACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,IAAI,IAAI,CAOtB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAS,MAAM,EAC/C,WAAW,EAAE,qBAAqB,CAAC,IAAI,CAAC,EACxC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GACnD,IAAI,EAAE,CAcR;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,SAAS,MAAM,EAC5C,WAAW,EAAE,qBAAqB,CAAC,IAAI,CAAC,EACxC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,MAAM,GACX,OAAO,CAQT"}

package/dist/definePermissions.js

@@ -0,0 +1,54 @@
+function assertPermissionDefinitions(definitions) {
+  const defined = new Set(definitions.permissions);
+  for (const [role, names] of Object.entries(definitions.roles)) {
+    for (const name of names) {
+      if (!defined.has(name)) {
+        throw new Error(
+          `Unknown permission "${name}" in role "${role}". Add it to \`permissions\` in your permission definitions first.`
+        );
+      }
+    }
+  }
+}
+function definePermissions(definitions) {
+  assertPermissionDefinitions(definitions);
+  return definitions;
+}
+function isPermission(definitions, name) {
+  return definitions.permissions.some((permission) => permission === name);
+}
+function assertPermission(definitions, name) {
+  if (!isPermission(definitions, name)) {
+    throw new Error(
+      `Unknown permission "${name}". Add it to \`permissions\` in your permission definitions before using it.`
+    );
+  }
+}
+function permissionsOf(definitions, roles) {
+  const list = typeof roles === "string" ? [roles] : roles ?? [];
+  const permissions = /* @__PURE__ */ new Set();
+  for (const role of list) {
+    if (Object.hasOwn(definitions.roles, role)) {
+      for (const permission of definitions.roles[role]) {
+        permissions.add(permission);
+      }
+    }
+  }
+  return [...permissions];
+}
+function coversRole(definitions, held, role) {
+  if (!Object.hasOwn(definitions.roles, role)) {
+    return false;
+  }
+  return definitions.roles[role].every(
+    (permission) => held.includes(permission)
+  );
+}
+export {
+  assertPermission,
+  assertPermissionDefinitions,
+  coversRole,
+  definePermissions,
+  isPermission,
+  permissionsOf
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { assertPermission, assertPermissionDefinitions, coversRole, definePermissions, isPermission, permissionsOf, } from './definePermissions.js';
+export type { PermissionDefinitions, PermissionName, } from './definePermissions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,UAAU,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,qBAAqB,EACrB,cAAc,GACf,MAAM,wBAAwB,CAAA"}

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  assertPermission,
+  assertPermissionDefinitions,
+  coversRole,
+  definePermissions,
+  isPermission,
+  permissionsOf
+} from "./definePermissions.js";
+export {
+  assertPermission,
+  assertPermissionDefinitions,
+  coversRole,
+  definePermissions,
+  isPermission,
+  permissionsOf
+};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@cedarjs/permissions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "8.0.0-canary.3571",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cedarjs/cedar.git",
+    "directory": "packages/permissions"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./api": {
+      "default": {
+        "types": "./dist/api.d.ts",
+        "default": "./dist/api.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.d.*"
+  ],
+  "scripts": {
+    "build": "node ./build.mts",
+    "build:pack": "yarn pack -o cedarjs-permissions.tgz",
+    "build:types": "tsc --build --verbose ./tsconfig.build.json",
+    "check:attw": "yarn cedar-fwtools-attw",
+    "check:package": "concurrently npm:check:attw yarn:publint",
+    "test": "vitest run",
+    "test:types": "tstyche",
+    "test:watch": "vitest watch"
+  },
+  "dependencies": {
+    "@cedarjs/context": "8.0.0-canary.3571",
+    "@cedarjs/graphql-server": "8.0.0-canary.3571"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@cedarjs/framework-tools": "8.0.0-canary.3571",
+    "concurrently": "9.2.5",
+    "publint": "0.3.25",
+    "tstyche": "5.0.2",
+    "typescript": "5.9.3",
+    "vitest": "4.1.12"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}