@cfast/permissions 0.0.1

package/dist/client.js

@@ -0,0 +1,6 @@
+import {
+  ForbiddenError
+} from "./chunk-I35WLWUH.js";
+export {
+  ForbiddenError
+};

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { P as PermissionsConfig, a as Permissions, b as PermissionAction, D as DrizzleTable, W as WhereClause, G as Grant, c as PermissionDescriptor, d as PermissionCheckResult } from './client-CJBFS0IS.js';
+export { C as CRUD_ACTIONS, e as CrudAction, F as ForbiddenError, f as GrantFn, g as getTableName } from './client-CJBFS0IS.js';
+
+/**
+ * Creates a permission configuration that can be shared between server-side
+ * enforcement (`@cfast/db`) and client-side introspection (`@cfast/actions`).
+ *
+ * Supports two calling styles:
+ * - **Direct:** `definePermissions(config)` when no custom user type is needed.
+ * - **Curried:** `definePermissions<MyUser>()(config)` to get typed `where` clause user parameters.
+ *
+ * @param config - The permissions configuration with roles, grants, and optional hierarchy.
+ * @returns A {@link Permissions} object containing roles, raw grants, and hierarchy-expanded `resolvedGrants`.
+ *
+ * @example
+ * ```typescript
+ * import { definePermissions, grant } from "@cfast/permissions";
+ * import { eq } from "drizzle-orm";
+ * import { posts, comments } from "./schema";
+ *
+ * const permissions = definePermissions({
+ *   roles: ["anonymous", "user", "admin"] as const,
+ *   grants: {
+ *     anonymous: [
+ *       grant("read", posts, { where: (p) => eq(p.published, true) }),
+ *     ],
+ *     user: [
+ *       grant("read", posts),
+ *       grant("create", posts),
+ *       grant("update", posts, { where: (p, u) => eq(p.authorId, u.id) }),
+ *     ],
+ *     admin: [grant("manage", "all")],
+ *   },
+ * });
+ * ```
+ */
+declare function definePermissions<TRoles extends readonly string[]>(config: PermissionsConfig<TRoles>): Permissions<TRoles>;
+declare function definePermissions<TUser>(): <TRoles extends readonly string[]>(config: PermissionsConfig<TRoles, TUser>) => Permissions<TRoles>;
+
+/**
+ * Declares that a role can perform an action on a subject, optionally restricted
+ * by a row-level `where` clause.
+ *
+ * Used inside the `grants` map of {@link definePermissions} to build permission rules.
+ * A grant without a `where` clause applies to all rows.
+ *
+ * @param action - The operation being permitted (`"read"`, `"create"`, `"update"`, `"delete"`, or `"manage"` for all four).
+ * @param subject - A Drizzle table reference, or `"all"` to apply to every table.
+ * @param options - Optional configuration.
+ * @param options.where - A Drizzle filter function `(columns, user) => SQL` that restricts which rows this grant covers.
+ * @returns A {@link Grant} object for use in a permissions configuration.
+ *
+ * @example
+ * ```typescript
+ * import { grant } from "@cfast/permissions";
+ * import { eq } from "drizzle-orm";
+ * import { posts } from "./schema";
+ *
+ * // Unrestricted read on all posts
+ * grant("read", posts);
+ *
+ * // Only allow updating own posts
+ * grant("update", posts, {
+ *   where: (post, user) => eq(post.authorId, user.id),
+ * });
+ *
+ * // Full access to everything
+ * grant("manage", "all");
+ * ```
+ */
+declare function grant(action: PermissionAction, subject: DrizzleTable | "all", options?: {
+    where?: WhereClause;
+}): Grant;
+
+/**
+ * Checks whether a role satisfies a set of permission descriptors.
+ *
+ * This is the low-level structural checking function. It determines whether a
+ * role has *any* matching grant for each descriptor (action + table), without
+ * evaluating row-level `where` clauses. Row-level enforcement happens at
+ * execution time in `@cfast/db`.
+ *
+ * @param role - The role to check (e.g., `"user"`, `"admin"`).
+ * @param permissions - The permissions object from {@link definePermissions}.
+ * @param descriptors - Array of permission descriptors to check against.
+ * @returns A {@link PermissionCheckResult} with `permitted`, `denied`, and `reasons`.
+ *
+ * @example
+ * ```typescript
+ * import { checkPermissions, definePermissions, grant } from "@cfast/permissions";
+ *
+ * const permissions = definePermissions({
+ *   roles: ["user", "admin"] as const,
+ *   grants: {
+ *     user: [grant("read", posts), grant("create", posts)],
+ *     admin: [grant("manage", "all")],
+ *   },
+ * });
+ *
+ * const result = checkPermissions("user", permissions, [
+ *   { action: "update", table: posts },
+ * ]);
+ * result.permitted; // false
+ * result.denied;    // [{ action: "update", table: posts }]
+ * ```
+ */
+declare function checkPermissions(role: string, permissions: Permissions, descriptors: PermissionDescriptor[]): PermissionCheckResult;
+
+/**
+ * Resolves and merges grants for multiple roles into a single flat array.
+ *
+ * Looks up each role's pre-expanded grants (from hierarchy resolution) and
+ * deduplicates them by action + subject. When multiple grants share the same
+ * action + subject:
+ * - If **any** grant has no `where` clause, the merged grant is unrestricted.
+ * - If **all** grants have `where` clauses, they are OR-merged via Drizzle's `or()`.
+ *
+ * This is used when a user has multiple roles and their grants need to be combined.
+ *
+ * @param permissions - The permissions object from {@link definePermissions}.
+ * @param roles - Array of role names whose grants should be merged.
+ * @returns A deduplicated array of {@link Grant} objects with merged `where` clauses.
+ */
+declare function resolveGrants(permissions: Permissions, roles: string[]): Grant[];
+
+export { DrizzleTable, Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, WhereClause, checkPermissions, definePermissions, grant, resolveGrants };

package/dist/index.js

@@ -0,0 +1,170 @@
+import {
+  CRUD_ACTIONS,
+  ForbiddenError,
+  getTableName
+} from "./chunk-I35WLWUH.js";
+
+// src/grant.ts
+function grant(action, subject, options) {
+  return {
+    action,
+    subject,
+    where: options?.where
+  };
+}
+
+// src/define-permissions.ts
+function buildPermissions(config) {
+  const { roles, hierarchy } = config;
+  const grantFn = grant;
+  const grants = typeof config.grants === "function" ? config.grants(grantFn) : config.grants;
+  const resolvedGrants = resolveHierarchy(roles, grants, hierarchy);
+  return {
+    roles,
+    grants,
+    resolvedGrants
+  };
+}
+function definePermissions(config) {
+  if (config === void 0) {
+    return (c) => buildPermissions(c);
+  }
+  return buildPermissions(config);
+}
+function resolveHierarchy(roles, grants, hierarchy) {
+  if (!hierarchy) {
+    return { ...grants };
+  }
+  const resolved = {};
+  const resolving = /* @__PURE__ */ new Set();
+  function resolve(role) {
+    if (resolved[role]) return resolved[role];
+    if (resolving.has(role)) {
+      throw new Error(
+        `Circular role hierarchy detected: '${role}' inherits from itself`
+      );
+    }
+    resolving.add(role);
+    const own = grants[role] ?? [];
+    const parents = hierarchy?.[role] ?? [];
+    const inherited = parents.flatMap((parent) => resolve(parent));
+    resolved[role] = [...inherited, ...own];
+    resolving.delete(role);
+    return resolved[role];
+  }
+  for (const role of roles) {
+    resolve(role);
+  }
+  return resolved;
+}
+
+// src/check.ts
+function grantMatches(g, action, table) {
+  const actionOk = g.action === action || g.action === "manage";
+  const subjectOk = g.subject === "all" || g.subject === table || getTableName(g.subject) === getTableName(table);
+  return actionOk && subjectOk;
+}
+function hasGrantFor(grants, action, table) {
+  return grants.some((g) => grantMatches(g, action, table));
+}
+function hasManagePermission(grants, table) {
+  if (hasGrantFor(grants, "manage", table)) return true;
+  return CRUD_ACTIONS.every((action) => hasGrantFor(grants, action, table));
+}
+function checkPermissions(role, permissions, descriptors) {
+  const grants = permissions.resolvedGrants[role] ?? [];
+  const denied = [];
+  const reasons = [];
+  for (const descriptor of descriptors) {
+    let permitted;
+    if (descriptor.action === "manage") {
+      permitted = hasManagePermission(grants, descriptor.table);
+    } else {
+      permitted = hasGrantFor(grants, descriptor.action, descriptor.table);
+    }
+    if (!permitted) {
+      denied.push(descriptor);
+      reasons.push(
+        `Role '${role}' cannot ${descriptor.action} on '${getTableName(descriptor.table)}'`
+      );
+    }
+  }
+  return {
+    permitted: denied.length === 0,
+    denied,
+    reasons
+  };
+}
+
+// src/resolve-grants.ts
+import { or } from "drizzle-orm";
+function toSQLWrapper(value) {
+  return value;
+}
+function resolveGrants(permissions, roles) {
+  const allGrants = [];
+  for (const role of roles) {
+    const roleGrants = permissions.resolvedGrants[role];
+    if (roleGrants) {
+      allGrants.push(...roleGrants);
+    }
+  }
+  if (allGrants.length === 0) return [];
+  const groups = /* @__PURE__ */ new Map();
+  const subjectIds = /* @__PURE__ */ new Map();
+  let nextId = 0;
+  function getSubjectId(subject) {
+    let id = subjectIds.get(subject);
+    if (id === void 0) {
+      id = nextId++;
+      subjectIds.set(subject, id);
+    }
+    return id;
+  }
+  for (const g of allGrants) {
+    const key = `${g.action}:${getSubjectId(g.subject)}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = { action: g.action, subject: g.subject, wheres: [] };
+      groups.set(key, group);
+    }
+    group.wheres.push(g.where);
+  }
+  const result = [];
+  for (const group of groups.values()) {
+    const hasUnrestricted = group.wheres.some((w) => w === void 0);
+    if (hasUnrestricted) {
+      result.push({ action: group.action, subject: group.subject });
+    } else {
+      const whereFns = group.wheres.filter(
+        (w) => w !== void 0
+      );
+      if (whereFns.length === 1) {
+        result.push({
+          action: group.action,
+          subject: group.subject,
+          where: whereFns[0]
+        });
+      } else {
+        const merged = (columns, user) => or(
+          ...whereFns.map((fn) => toSQLWrapper(fn(columns, user)))
+        );
+        result.push({
+          action: group.action,
+          subject: group.subject,
+          where: merged
+        });
+      }
+    }
+  }
+  return result;
+}
+export {
+  CRUD_ACTIONS,
+  ForbiddenError,
+  checkPermissions,
+  definePermissions,
+  getTableName,
+  grant,
+  resolveGrants
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@cfast/permissions",
+  "version": "0.0.1",
+  "description": "Isomorphic, composable permission system with Drizzle-native row-level access control",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DanielMSchmidt/cfast.git",
+    "directory": "packages/permissions"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.35"
+  },
+  "devDependencies": {
+    "tsup": "^8",
+    "typescript": "^5.7",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/client.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/client.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run"
+  }
+}