@cfast/permissions 0.0.1 → 0.2.0

package/llms.txt

@@ -0,0 +1,233 @@
+# @cfast/permissions
+
+> Isomorphic, Drizzle-native permission system. Define permissions once, enforce as SQL WHERE clauses.
+
+## When to use
+Use this package to define role-based permissions that compile down to Drizzle `where` clauses for Cloudflare D1. Permissions defined here are consumed by `@cfast/db` for server enforcement and `@cfast/actions` for client-side UI introspection.
+
+## Key concepts
+- **Permissions are WHERE clauses**: A read permission becomes a SQL filter. You don't write a check then repeat the logic in your query.
+- **Two layers**: (1) Structural -- "does this role have any grant for update on posts?" (2) Row-level -- "does the grant's WHERE clause include this specific row?" Structural checks are cheap and work client-side. Row-level checks happen at execution time.
+- **`"manage"` = all CRUD**: A shorthand for granting `read`, `create`, `update`, `delete`.
+- **`"all"` = every table**: `grant("manage", "all")` grants full access to everything.
+- **Role hierarchy**: Roles can inherit from parent roles. Multiple WHERE clauses on the same action+table are OR'd (more permissive grant wins).
+
+## API Reference
+
+### `definePermissions(config): Permissions`
+```typescript
+import { definePermissions, grant } from "@cfast/permissions";
+
+const permissions = definePermissions({
+  roles: ["anonymous", "user", "admin"] as const,
+  grants: {
+    anonymous: [ grant("read", posts, { where: (post) => eq(post.published, true) }) ],
+    user: [ grant("read", posts), grant("create", posts) ],
+    admin: [ grant("manage", "all") ],
+  },
+  hierarchy: {           // optional
+    user: ["anonymous"], // user inherits anonymous grants
+    admin: ["user"],     // admin inherits user grants
+  },
+});
+```
+
+**Curried form** for typed user in WHERE clauses:
+```typescript
+const permissions = definePermissions<MyUser>()({
+  roles: [...] as const,
+  grants: (grant) => ({
+    user: [ grant("update", posts, { where: (post, user) => eq(post.authorId, user.id) }) ],
+    // ...
+  }),
+});
+```
+
+**Curried form with schema** to constrain string subjects to known table names at compile time:
+```typescript
+import * as schema from "./schema";
+
+const permissions = definePermissions<MyUser, typeof schema>()({
+  roles: ["member", "admin"] as const,
+  grants: (grant) => ({
+    member: [
+      grant("read", "projects"),                  // ✓ string form, type-checked
+      grant("read", schema.projects),             // ✓ object form still works
+      // grant("read", "unknownTable"),           // ✗ TypeScript error
+    ],
+    admin: [grant("manage", "all")],
+  }),
+});
+```
+
+**Returns** `Permissions<TRoles>`:
+```typescript
+type Permissions<TRoles> = {
+  roles: TRoles;
+  grants: Record<TRoles[number], Grant[]>;
+  resolvedGrants: Record<TRoles[number], Grant[]>; // hierarchy-expanded
+};
+```
+
+### `grant(action, subject, options?): Grant`
+```typescript
+grant(action: PermissionAction, subject: DrizzleTable | string, options?: { where?: WhereClause }): Grant
+```
+- `PermissionAction`: `"read" | "create" | "update" | "delete" | "manage"`
+- `WhereClause`: `(columns, user) => DrizzleSQL | undefined`
+- `subject` may be a Drizzle table object, a string table name (e.g. `"projects"`), or `"all"`. String and object forms are interchangeable at runtime — both are normalized to the same key by `getTableName()`. To get compile-time validation that a string subject is a known table, use the `definePermissions<User, typeof schema>()` curried form.
+
+### `checkPermissions(role, permissions, descriptors): PermissionCheckResult`
+```typescript
+import { checkPermissions } from "@cfast/permissions";
+
+const result = checkPermissions("user", permissions, [
+  { action: "update", table: posts },         // object form
+  { action: "create", table: "comments" },    // string form also accepted
+]);
+result.permitted;  // boolean
+result.denied;     // PermissionDescriptor[]
+result.reasons;    // string[]
+```
+
+### `resolveGrants(permissions, userOrRoles): Grant[]`
+Merges grants from multiple roles into a flat array. Deduplicates by action+subject and OR-merges WHERE clauses.
+
+Two calling styles are supported (both equivalent):
+
+```typescript
+// Preferred: pass the user directly — the function extracts user.roles
+const grants = resolveGrants(permissions, user);
+
+// Legacy: pass the roles array yourself (still supported)
+const grants = resolveGrants(permissions, user.roles);
+```
+
+The user-object form accepts any value with a `roles: readonly string[]` field, so it works directly with the user shape from `@cfast/auth` without manual extraction.
+
+### `ForbiddenError`
+```typescript
+import { ForbiddenError } from "@cfast/permissions";
+
+class ForbiddenError extends Error {
+  readonly action: PermissionAction;
+  readonly table: DrizzleTable;
+  readonly role: string | undefined;
+  readonly descriptors: PermissionDescriptor[];
+  toJSON(): { name, message, action, table, role };
+}
+```
+
+### `can(grants, action, table): boolean`
+```typescript
+import { can } from "@cfast/permissions";
+function can<TTables extends Record<string, DrizzleTable> = Record<string, DrizzleTable>>(
+  grants: Grant[],
+  action: PermissionAction,
+  table: DrizzleTable | string,
+): boolean
+```
+Quick grant-level permission check that works directly with resolved grants. Unlike `checkPermissions` (which takes a role string + full permissions object), `can` works with the user's resolved grants -- the same grants available in loaders, actions, and client-side. Returns `true` if any grant permits the action on the table (including `manage`/`all` wildcards).
+
+Accepts either a Drizzle table object or a string table name. To get compile-time validation that a string is an actual table, supply the schema map as a generic argument.
+
+```typescript
+import * as schema from "../db/schema";
+
+can(grants, "create", schema.posts)        // ✓ object form
+can(grants, "create", "posts")             // ✓ string form (untyped)
+can<typeof schema>(grants, "create", "posts")        // ✓ string form, type-checked
+// can<typeof schema>(grants, "create", "unknownTable")  // ✗ TypeScript error
+```
+
+### `CRUD_ACTIONS`
+```typescript
+const CRUD_ACTIONS: readonly CrudAction[] = ["read", "create", "update", "delete"];
+```
+
+### Client entrypoint
+```typescript
+import { ForbiddenError, can } from "@cfast/permissions/client";
+import type { PermissionAction, CrudAction, PermissionDescriptor, PermissionCheckResult } from "@cfast/permissions/client";
+```
+Use this in client bundles to avoid importing server-only code. `can` is available from both the main and client entrypoints.
+
+## Usage Examples
+
+### Ownership-based permissions with hierarchy
+```typescript
+import { definePermissions, grant } from "@cfast/permissions";
+import { eq } from "drizzle-orm";
+import { posts, comments } from "./schema";
+
+export const permissions = definePermissions({
+  roles: ["anonymous", "user", "editor", "admin"] as const,
+  hierarchy: {
+    user: ["anonymous"],
+    editor: ["user"],
+    admin: ["editor"],
+  },
+  grants: {
+    anonymous: [
+      grant("read", posts, { where: (p) => eq(p.published, true) }),
+    ],
+    user: [
+      grant("create", posts),
+      grant("update", posts, { where: (p, u) => eq(p.authorId, u.id) }),
+      grant("delete", posts, { where: (p, u) => eq(p.authorId, u.id) }),
+    ],
+    editor: [
+      grant("read", posts),   // unrestricted overrides inherited "published only"
+      grant("update", posts),
+      grant("delete", posts),
+    ],
+    admin: [
+      grant("manage", "all"),
+    ],
+  },
+});
+```
+
+### Quick permission check with `can()`
+```typescript
+import { can } from "@cfast/permissions";
+
+// In a loader/action -- grants come from auth.requireUser()
+const { grants } = await auth.requireUser(request);
+if (can(grants, "update", posts)) {
+  // user has structural permission to update posts
+}
+
+// In a React component -- grants come from loader data
+function PostCard({ post, grants }) {
+  return (
+    <div>
+      <h2>{post.title}</h2>
+      {can(grants, "update", posts) && <Button>Edit</Button>}
+      {can(grants, "delete", posts) && <Button color="danger">Delete</Button>}
+    </div>
+  );
+}
+```
+
+### Checking permissions manually
+```typescript
+const result = checkPermissions("user", permissions, [
+  { action: "delete", table: posts },
+]);
+if (!result.permitted) {
+  console.log(result.reasons); // ["Role 'user' cannot delete on 'posts'"] -- if no grant exists
+}
+```
+
+## Integration
+- **`@cfast/db`**: Pass `permissions` to `createDb()`. Operations auto-enforce permissions.
+- **`@cfast/actions`**: Actions extract `PermissionDescriptor[]` from operations for client-side `permitted` booleans.
+- **`@cfast/admin`**: Admin CRUD goes through the same permission system.
+
+## Common Mistakes
+- **Forgetting `as const` on roles array** -- without it, TypeScript infers `string[]` and you lose type checking on grant keys.
+- **Expecting WHERE on `"create"` grants** -- create is boolean (can/can't). There's no existing row to filter.
+- **Circular hierarchy** -- detected at runtime and throws `Error`. E.g., A inherits B inherits A.
+- **Using `checkPermissions` for row-level security** -- it only does structural checks (action + table). Row-level WHERE enforcement happens at execution time in `@cfast/db`.
+- **Importing `definePermissions` in client bundles** -- use `@cfast/permissions/client` instead to keep the bundle small.

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@cfast/permissions",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Isomorphic, composable permission system with Drizzle-native row-level access control",
+  "keywords": [
+    "cfast",
+    "cloudflare-workers",
+    "permissions",
+    "rbac",
+    "access-control"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,7 +29,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "sideEffects": false,
   "publishConfig": {

package/dist/chunk-FVAAEIAE.js

@@ -1,32 +0,0 @@
-// src/errors.ts
-function getTableName(table) {
-  return table._?.name ?? "unknown";
-}
-var ForbiddenError = class extends Error {
-  action;
-  table;
-  role;
-  descriptors;
-  constructor(options) {
-    const tableName = getTableName(options.table);
-    super(`Role '${options.role}' cannot ${options.action} on '${tableName}'`);
-    this.name = "ForbiddenError";
-    this.action = options.action;
-    this.table = options.table;
-    this.role = options.role;
-    this.descriptors = options.descriptors ?? [];
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      action: this.action,
-      table: getTableName(this.table),
-      role: this.role
-    };
-  }
-};
-
-export {
-  ForbiddenError
-};

package/dist/chunk-IPYPD2CZ.js

@@ -1,53 +0,0 @@
-// src/types.ts
-var DRIZZLE_NAME_SYMBOL = /* @__PURE__ */ Symbol.for("drizzle:Name");
-function getTableName(table) {
-  return table[DRIZZLE_NAME_SYMBOL] ?? "unknown";
-}
-var CRUD_ACTIONS = ["read", "create", "update", "delete"];
-
-// src/errors.ts
-var ForbiddenError = class extends Error {
-  /** The action that was denied (e.g., `"delete"`). */
-  action;
-  /** The Drizzle table the action targeted. */
-  table;
-  /** The role that lacked the permission, or `undefined` if not specified. */
-  role;
-  /** The full list of permission descriptors that were checked. */
-  descriptors;
-  /**
-   * Creates a new `ForbiddenError`.
-   *
-   * @param options - The action, table, and optional role/descriptors for the error.
-   */
-  constructor(options) {
-    const tableName = getTableName(options.table);
-    const msg = options.role ? `Role '${options.role}' cannot ${options.action} on '${tableName}'` : `Cannot ${options.action} on '${tableName}'`;
-    super(msg);
-    this.name = "ForbiddenError";
-    this.action = options.action;
-    this.table = options.table;
-    this.role = options.role;
-    this.descriptors = options.descriptors ?? [];
-  }
-  /**
-   * Serializes the error to a JSON-safe object for server-to-client transfer.
-   *
-   * @returns A plain object with `name`, `message`, `action`, `table`, and `role` fields.
-   */
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      action: this.action,
-      table: getTableName(this.table),
-      role: this.role
-    };
-  }
-};
-
-export {
-  getTableName,
-  CRUD_ACTIONS,
-  ForbiddenError
-};

package/dist/chunk-PNHVTXCZ.js

@@ -1,39 +0,0 @@
-// src/types.ts
-var DRIZZLE_NAME_SYMBOL = /* @__PURE__ */ Symbol.for("drizzle:Name");
-function getTableName(table) {
-  return table[DRIZZLE_NAME_SYMBOL] ?? "unknown";
-}
-var CRUD_ACTIONS = ["read", "create", "update", "delete"];
-
-// src/errors.ts
-var ForbiddenError = class extends Error {
-  action;
-  table;
-  role;
-  descriptors;
-  constructor(options) {
-    const tableName = getTableName(options.table);
-    const msg = options.role ? `Role '${options.role}' cannot ${options.action} on '${tableName}'` : `Cannot ${options.action} on '${tableName}'`;
-    super(msg);
-    this.name = "ForbiddenError";
-    this.action = options.action;
-    this.table = options.table;
-    this.role = options.role;
-    this.descriptors = options.descriptors ?? [];
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      action: this.action,
-      table: getTableName(this.table),
-      role: this.role
-    };
-  }
-};
-
-export {
-  getTableName,
-  CRUD_ACTIONS,
-  ForbiddenError
-};

package/dist/chunk-YYYHMPTS.js

@@ -1,33 +0,0 @@
-// src/errors.ts
-function getTableName(table) {
-  return table._?.name ?? "unknown";
-}
-var ForbiddenError = class extends Error {
-  action;
-  table;
-  role;
-  descriptors;
-  constructor(options) {
-    const tableName = getTableName(options.table);
-    const msg = options.role ? `Role '${options.role}' cannot ${options.action} on '${tableName}'` : `Cannot ${options.action} on '${tableName}'`;
-    super(msg);
-    this.name = "ForbiddenError";
-    this.action = options.action;
-    this.table = options.table;
-    this.role = options.role;
-    this.descriptors = options.descriptors ?? [];
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      action: this.action,
-      table: getTableName(this.table),
-      role: this.role
-    };
-  }
-};
-
-export {
-  ForbiddenError
-};

package/dist/chunk-ZTQJZJFW.js

@@ -1,38 +0,0 @@
-// src/types.ts
-function getTableName(table) {
-  return table._?.name ?? "unknown";
-}
-var CRUD_ACTIONS = ["read", "create", "update", "delete"];
-
-// src/errors.ts
-var ForbiddenError = class extends Error {
-  action;
-  table;
-  role;
-  descriptors;
-  constructor(options) {
-    const tableName = getTableName(options.table);
-    const msg = options.role ? `Role '${options.role}' cannot ${options.action} on '${tableName}'` : `Cannot ${options.action} on '${tableName}'`;
-    super(msg);
-    this.name = "ForbiddenError";
-    this.action = options.action;
-    this.table = options.table;
-    this.role = options.role;
-    this.descriptors = options.descriptors ?? [];
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      message: this.message,
-      action: this.action,
-      table: getTableName(this.table),
-      role: this.role
-    };
-  }
-};
-
-export {
-  getTableName,
-  CRUD_ACTIONS,
-  ForbiddenError
-};

package/dist/client-8HHp1rPO.d.ts

@@ -1,62 +0,0 @@
-type DrizzleTable = {
-    _: {
-        name: string;
-    };
-};
-type DrizzleSQL = {
-    getSQL(): unknown;
-};
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-type CrudAction = Exclude<PermissionAction, "manage">;
-declare const CRUD_ACTIONS: readonly CrudAction[];
-type WhereClause = (columns: Record<string, unknown>, user: any) => DrizzleSQL | undefined;
-type Grant = {
-    action: PermissionAction;
-    subject: DrizzleTable | "all";
-    where?: WhereClause;
-};
-type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all", options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
-}) => Grant;
-type PermissionDescriptor = {
-    action: PermissionAction;
-    table: DrizzleTable;
-};
-type PermissionCheckResult = {
-    permitted: boolean;
-    denied: PermissionDescriptor[];
-    reasons: string[];
-};
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser>) => Record<TRoles[number], Grant[]>);
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-type Permissions<TRoles extends readonly string[] = readonly string[]> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]>;
-    resolvedGrants: Record<TRoles[number], Grant[]>;
-};
-
-type ForbiddenErrorOptions = {
-    action: PermissionAction;
-    table: DrizzleTable;
-    role?: string;
-    descriptors?: PermissionDescriptor[];
-};
-declare class ForbiddenError extends Error {
-    readonly action: PermissionAction;
-    readonly table: DrizzleTable;
-    readonly role: string | undefined;
-    readonly descriptors: PermissionDescriptor[];
-    constructor(options: ForbiddenErrorOptions);
-    toJSON(): {
-        name: string;
-        message: string;
-        action: PermissionAction;
-        table: string;
-        role: string | undefined;
-    };
-}
-
-export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type WhereClause as W, type Permissions as a, type PermissionAction as b, type PermissionDescriptor as c, type PermissionCheckResult as d, type CrudAction as e, type GrantFn as f };

package/dist/client-BBcryLDZ.d.ts

@@ -1,61 +0,0 @@
-import { SQL } from 'drizzle-orm';
-
-type DrizzleTable = {
-    _: {
-        name: string;
-    };
-};
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-type CrudAction = Exclude<PermissionAction, "manage">;
-declare const CRUD_ACTIONS: readonly CrudAction[];
-type WhereClause = (columns: Record<string, unknown>, user: any) => SQL | undefined;
-type Grant = {
-    action: PermissionAction;
-    subject: DrizzleTable | "all";
-    where?: WhereClause;
-};
-type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all", options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => SQL | undefined;
-}) => Grant;
-type PermissionDescriptor = {
-    action: PermissionAction;
-    table: DrizzleTable;
-};
-type PermissionCheckResult = {
-    permitted: boolean;
-    denied: PermissionDescriptor[];
-    reasons: string[];
-};
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser>) => Record<TRoles[number], Grant[]>);
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-type Permissions<TRoles extends readonly string[] = readonly string[]> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]>;
-    resolvedGrants: Record<TRoles[number], Grant[]>;
-};
-
-type ForbiddenErrorOptions = {
-    action: PermissionAction;
-    table: DrizzleTable;
-    role: string;
-    descriptors?: PermissionDescriptor[];
-};
-declare class ForbiddenError extends Error {
-    readonly action: PermissionAction;
-    readonly table: DrizzleTable;
-    readonly role: string;
-    readonly descriptors: PermissionDescriptor[];
-    constructor(options: ForbiddenErrorOptions);
-    toJSON(): {
-        name: string;
-        message: string;
-        action: PermissionAction;
-        table: string;
-        role: string;
-    };
-}
-
-export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type WhereClause as W, type Permissions as a, type PermissionAction as b, type PermissionDescriptor as c, type PermissionCheckResult as d, type CrudAction as e, type GrantFn as f };

package/dist/client-BKD8jH5P.d.ts

@@ -1,56 +0,0 @@
-import { Table, SQL } from 'drizzle-orm';
-
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-type CrudAction = Exclude<PermissionAction, "manage">;
-declare const CRUD_ACTIONS: readonly CrudAction[];
-type WhereClause = (columns: Record<string, unknown>, user: any) => SQL | undefined;
-type Grant = {
-    action: PermissionAction;
-    subject: Table | "all";
-    where?: WhereClause;
-};
-type GrantFn<TUser> = (action: PermissionAction, subject: Table | "all", options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => SQL | undefined;
-}) => Grant;
-type PermissionDescriptor = {
-    action: PermissionAction;
-    table: Table;
-};
-type PermissionCheckResult = {
-    permitted: boolean;
-    denied: PermissionDescriptor[];
-    reasons: string[];
-};
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser>) => Record<TRoles[number], Grant[]>);
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-type Permissions<TRoles extends readonly string[] = readonly string[]> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant[]>;
-    resolvedGrants: Record<TRoles[number], Grant[]>;
-};
-
-type ForbiddenErrorOptions = {
-    action: PermissionAction;
-    table: Table;
-    role: string;
-    descriptors?: PermissionDescriptor[];
-};
-declare class ForbiddenError extends Error {
-    readonly action: PermissionAction;
-    readonly table: Table;
-    readonly role: string;
-    readonly descriptors: PermissionDescriptor[];
-    constructor(options: ForbiddenErrorOptions);
-    toJSON(): {
-        name: string;
-        message: string;
-        action: PermissionAction;
-        table: string;
-        role: string;
-    };
-}
-
-export { CRUD_ACTIONS as C, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type WhereClause as W, type Permissions as a, type PermissionAction as b, type PermissionDescriptor as c, type PermissionCheckResult as d, type CrudAction as e, type GrantFn as f };