@cfast/permissions 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -72,6 +72,33 @@ declare function grant(action: PermissionAction, subject: DrizzleTable | "all",
     where?: WhereClause;
 }): Grant;
 
+/**
+ * Checks whether a set of resolved grants permits a specific action on a table.
+ *
+ * Unlike {@link checkPermissions} (which takes a role string and the full permissions
+ * object), `can` works directly with the user's resolved grants — the same grants
+ * available in loaders, actions, and client-side via `useActions`.
+ *
+ * @param grants - The user's resolved permission grants.
+ * @param action - The permission action to check (e.g., `"create"`, `"read"`).
+ * @param table - The Drizzle table object to check against.
+ * @returns `true` if any grant permits the action on the table.
+ *
+ * @example
+ * ```ts
+ * import { can } from "@cfast/permissions";
+ *
+ * // In a loader
+ * if (!can(ctx.auth.grants, "create", posts)) {
+ *   throw redirect("/");
+ * }
+ *
+ * // In a component
+ * {can(grants, "update", posts) && <Button>Edit</Button>}
+ * ```
+ */
+declare function can(grants: Grant[], action: PermissionAction, table: DrizzleTable): boolean;
+
 /**
  * Checks whether a role satisfies a set of permission descriptors.
  *
@@ -123,4 +150,4 @@ declare function checkPermissions(role: string, permissions: Permissions, descri
  */
 declare function resolveGrants(permissions: Permissions, roles: string[]): Grant[];
 
-export { DrizzleTable, Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, WhereClause, checkPermissions, definePermissions, grant, resolveGrants };
+export { DrizzleTable, Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, WhereClause, can, checkPermissions, definePermissions, grant, resolveGrants };

package/dist/index.js

@@ -58,6 +58,15 @@ function resolveHierarchy(roles, grants, hierarchy) {
   return resolved;
 }
 
+// src/can.ts
+function can(grants, action, table) {
+  return grants.some((g) => {
+    const actionOk = g.action === action || g.action === "manage";
+    const subjectOk = g.subject === "all" || typeof g.subject === "object" && getTableName(g.subject) === getTableName(table);
+    return actionOk && subjectOk;
+  });
+}
+
 // src/check.ts
 function grantMatches(g, action, table) {
   const actionOk = g.action === action || g.action === "manage";
@@ -162,6 +171,7 @@ function resolveGrants(permissions, roles) {
 export {
   CRUD_ACTIONS,
   ForbiddenError,
+  can,
   checkPermissions,
   definePermissions,
   getTableName,

package/llms.txt

@@ -0,0 +1,192 @@
+# @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) }) ],
+    // ...
+  }),
+});
+```
+
+**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 | "all", options?: { where?: WhereClause }): Grant
+```
+- `PermissionAction`: `"read" | "create" | "update" | "delete" | "manage"`
+- `WhereClause`: `(columns, user) => DrizzleSQL | undefined`
+
+### `checkPermissions(role, permissions, descriptors): PermissionCheckResult`
+```typescript
+import { checkPermissions } from "@cfast/permissions";
+
+const result = checkPermissions("user", permissions, [
+  { action: "update", table: posts },
+]);
+result.permitted;  // boolean
+result.denied;     // PermissionDescriptor[]
+result.reasons;    // string[]
+```
+
+### `resolveGrants(permissions, roles): Grant[]`
+Merges grants from multiple roles into a flat array. Deduplicates by action+subject and OR-merges WHERE clauses.
+
+### `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(grants: Grant[], action: PermissionAction, table: DrizzleTable): 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).
+
+```typescript
+can(grants, "create", posts)  // → boolean
+can(grants, "delete", comments) // → boolean
+```
+
+### `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.1.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,12 +29,20 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "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"
+  },
   "peerDependencies": {
     "drizzle-orm": ">=0.35"
   },
@@ -35,12 +50,5 @@
     "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"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Daniel Schmidt
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

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 };

package/dist/client-ChpyEV1r.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;
-    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-CuB6igvw.d.ts

@@ -1,195 +0,0 @@
-/**
- * Minimal structural type for a Drizzle ORM table reference.
- *
- * Drizzle stores table metadata via Symbols (e.g., `Symbol('drizzle:Name')`).
- * This loose type avoids importing `drizzle-orm` directly into the permissions package.
- */
-type DrizzleTable = Record<string | symbol, any>;
-/**
- * Minimal structural type for a Drizzle SQL expression.
- *
- * Matches any object with a `getSQL()` method, which includes Drizzle's
- * `SQL`, `SQLWrapper`, and condition builder results.
- */
-type DrizzleSQL = {
-    getSQL(): unknown;
-};
-/**
- * Extracts the table name string from a Drizzle table reference.
- *
- * @param table - A Drizzle table object containing the `drizzle:Name` symbol.
- * @returns The table name, or `"unknown"` if the symbol is not present.
- */
-declare function getTableName(table: DrizzleTable): string;
-/**
- * A permission action: one of the four CRUD operations, or `"manage"` for all.
- *
- * - `"read"` maps to `SELECT` queries.
- * - `"create"` maps to `INSERT` statements.
- * - `"update"` maps to `UPDATE` statements.
- * - `"delete"` maps to `DELETE` statements.
- * - `"manage"` is shorthand for granting all four CRUD actions.
- */
-type PermissionAction = "read" | "create" | "update" | "delete" | "manage";
-/**
- * A CRUD-only permission action (excludes `"manage"`).
- *
- * Useful when you need to iterate over concrete operations without the
- * `"manage"` shorthand. See also {@link CRUD_ACTIONS}.
- */
-type CrudAction = Exclude<PermissionAction, "manage">;
-/**
- * Readonly array of the four CRUD action strings, useful for iteration.
- *
- * @example
- * ```typescript
- * import { CRUD_ACTIONS } from "@cfast/permissions";
- *
- * for (const action of CRUD_ACTIONS) {
- *   console.log(action); // "read", "create", "update", "delete"
- * }
- * ```
- */
-declare const CRUD_ACTIONS: readonly CrudAction[];
-/**
- * A function that produces a Drizzle `WHERE` clause for row-level permission filtering.
- *
- * @param columns - The table's column references for building filter expressions.
- * @param user - The current user object (from `@cfast/auth`).
- * @returns A Drizzle SQL expression to restrict matching rows, or `undefined` for no restriction.
- */
-type WhereClause = (columns: Record<string, unknown>, user: any) => DrizzleSQL | undefined;
-/**
- * A single permission grant: an action on a subject, optionally restricted by a `where` clause.
- */
-type Grant = {
-    /** The permitted operation. `"manage"` is shorthand for all four CRUD actions. */
-    action: PermissionAction;
-    /** The Drizzle table this grant applies to, or `"all"` for every table. */
-    subject: DrizzleTable | "all";
-    /** Optional row-level filter that restricts which rows this grant covers. */
-    where?: WhereClause;
-};
-/**
- * Type-safe grant builder function, parameterized by the user type.
- *
- * Used when `grants` is provided as a callback in {@link PermissionsConfig}
- * so that `where` clauses receive a correctly typed `user` parameter.
- *
- * @typeParam TUser - The user type passed to `where` clause callbacks.
- */
-type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all", options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
-}) => Grant;
-/**
- * Structural description of a permission requirement.
- *
- * Describes *what kind* of operation on *which table* without specifying concrete row values.
- * This is what makes client-side permission introspection possible: you can check whether a
- * role has the right grants without knowing the specific row being accessed.
- *
- * @example
- * ```typescript
- * const descriptor: PermissionDescriptor = {
- *   action: "update",
- *   table: posts,
- * };
- * ```
- */
-type PermissionDescriptor = {
-    /** The operation being checked. */
-    action: PermissionAction;
-    /** The Drizzle table the operation targets. */
-    table: DrizzleTable;
-};
-/**
- * Result of a permission check via {@link checkPermissions}.
- */
-type PermissionCheckResult = {
-    /** `true` only if every descriptor in the check was satisfied. */
-    permitted: boolean;
-    /** The descriptors that were not satisfied. */
-    denied: PermissionDescriptor[];
-    /** Human-readable reasons for each denial. */
-    reasons: string[];
-};
-/**
- * Configuration object for {@link definePermissions}.
- *
- * @typeParam TRoles - Tuple of role name string literals (use `as const`).
- * @typeParam TUser - The user type for typed `where` clauses (defaults to `unknown`).
- */
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
-    /** All roles in the application, declared with `as const` for type inference. */
-    roles: TRoles;
-    /** A map from role to grant arrays, or a callback that receives a typed `grant` function. */
-    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser>) => Record<TRoles[number], Grant[]>);
-    /** Optional role hierarchy declaring which roles inherit from which. */
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-/**
- * The resolved permissions object returned by {@link definePermissions}.
- *
- * Contains the original roles and grants, plus the hierarchy-expanded `resolvedGrants`.
- * Pass this to `createDb()` for server-side enforcement or import it on the client
- * for UI-level permission introspection.
- *
- * @typeParam TRoles - Tuple of role name string literals.
- */
-type Permissions<TRoles extends readonly string[] = readonly string[]> = {
-    /** The role names from the configuration. */
-    roles: TRoles;
-    /** The raw grants as declared (before hierarchy expansion). */
-    grants: Record<TRoles[number], Grant[]>;
-    /** Grants expanded with inherited grants from the role hierarchy. */
-    resolvedGrants: Record<TRoles[number], Grant[]>;
-};
-
-/** Options for constructing a {@link ForbiddenError}. */
-type ForbiddenErrorOptions = {
-    /** The action that was denied. */
-    action: PermissionAction;
-    /** The Drizzle table the action targeted. */
-    table: DrizzleTable;
-    /** The role that lacked the permission, if known. */
-    role?: string;
-    /** The full list of permission descriptors that were checked. */
-    descriptors?: PermissionDescriptor[];
-};
-/**
- * Error thrown when a permission check fails during an operation.
- *
- * Extends `Error` with structured fields for the denied action, target table,
- * and role. Includes a `toJSON()` method so it can be serialized across the
- * server/client boundary.
- */
-declare class ForbiddenError extends Error {
-    /** The action that was denied (e.g., `"delete"`). */
-    readonly action: PermissionAction;
-    /** The Drizzle table the action targeted. */
-    readonly table: DrizzleTable;
-    /** The role that lacked the permission, or `undefined` if not specified. */
-    readonly role: string | undefined;
-    /** The full list of permission descriptors that were checked. */
-    readonly descriptors: PermissionDescriptor[];
-    /**
-     * Creates a new `ForbiddenError`.
-     *
-     * @param options - The action, table, and optional role/descriptors for the error.
-     */
-    constructor(options: ForbiddenErrorOptions);
-    /**
-     * 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(): {
-        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, getTableName as g };

package/dist/client-DduKFZmk.d.ts

@@ -1,59 +0,0 @@
-type DrizzleTable = Record<string | symbol, any>;
-type DrizzleSQL = {
-    getSQL(): unknown;
-};
-declare function getTableName(table: DrizzleTable): 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) => 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, getTableName as g };

package/dist/client-FbortuK3.d.ts

@@ -1,53 +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<TUser = unknown> = (columns: Record<string, unknown>, user: TUser) => SQL | undefined;
-type Grant<TUser = unknown> = {
-    action: PermissionAction;
-    subject: Table | "all";
-    where?: WhereClause<TUser>;
-};
-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<TUser>[]>;
-    hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
-};
-type Permissions<TRoles extends readonly string[] = readonly string[], TUser = unknown> = {
-    roles: TRoles;
-    grants: Record<TRoles[number], Grant<TUser>[]>;
-    resolvedGrants: Record<TRoles[number], Grant<TUser>[]>;
-};
-
-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 };