@cfast/permissions 0.0.1 → 0.2.0

package/dist/{chunk-I35WLWUH.js → chunk-NCLN5YBQ.js}

@@ -1,6 +1,9 @@
 // src/types.ts
 var DRIZZLE_NAME_SYMBOL = /* @__PURE__ */ Symbol.for("drizzle:Name");
 function getTableName(table) {
+  if (typeof table === "string") {
+    return table;
+  }
   const name = Reflect.get(table, DRIZZLE_NAME_SYMBOL);
   return typeof name === "string" ? name : "unknown";
 }
@@ -10,7 +13,7 @@ var CRUD_ACTIONS = ["read", "create", "update", "delete"];
 var ForbiddenError = class extends Error {
   /** The action that was denied (e.g., `"delete"`). */
   action;
-  /** The Drizzle table the action targeted. */
+  /** The Drizzle table or string table name the action targeted. */
   table;
   /** The role that lacked the permission, or `undefined` if not specified. */
   role;

package/dist/{client-CJBFS0IS.d.ts → client-C7xdwHTk.d.ts}

@@ -17,12 +17,46 @@ type DrizzleSQL = {
     getSQL(): unknown;
 };
 /**
- * Extracts the table name string from a Drizzle table reference.
+ * A schema map: an object mapping table names to Drizzle table references.
  *
- * @param table - A Drizzle table object containing the `drizzle:Name` symbol.
- * @returns The table name, or `"unknown"` if the symbol is not present.
+ * Typically the result of `import * as schema from "./schema"`. Used as the
+ * `TTables` generic parameter for {@link definePermissions}, {@link can}, and
+ * the curried {@link grant} callback so that string subjects (e.g.
+ * `"projects"`) are constrained to known table names at compile time.
  */
-declare function getTableName(table: DrizzleTable): string;
+type SchemaMap = Record<string, DrizzleTable>;
+/**
+ * Extracts the string-literal union of valid table names from a {@link SchemaMap}.
+ *
+ * Given `typeof schema` (where `schema` exports tables as named bindings),
+ * `TableName<typeof schema>` is the union of all exported table-key strings.
+ */
+type TableName<TTables extends SchemaMap> = Extract<keyof TTables, string>;
+/**
+ * The set of acceptable subject inputs for a grant or `can()` check.
+ *
+ * - A {@link DrizzleTable} object reference (the original form, always allowed).
+ * - A string-literal table name from {@link TableName}, constrained to the
+ *   provided `TTables` schema map at compile time when one is supplied.
+ * - The literal `"all"` for grants that apply to every table.
+ */
+type SubjectInput<TTables extends SchemaMap = SchemaMap> = DrizzleTable | TableName<TTables> | "all";
+/**
+ * Extracts the table name string from a Drizzle table reference, or returns
+ * a string subject as-is.
+ *
+ * Accepts both:
+ * - A Drizzle table object containing the `drizzle:Name` symbol — the symbol
+ *   is read via `Reflect.get`.
+ * - A bare string (e.g., a table-name literal like `"projects"`) — returned
+ *   unchanged so callers can use the same key for grant matching whether the
+ *   subject was declared as an object or a string.
+ *
+ * @param table - A Drizzle table object or a string subject key.
+ * @returns The table name, the input string, or `"unknown"` if a symbol-less
+ *   object was provided.
+ */
+declare function getTableName(table: DrizzleTable | string): string;
 /**
  * A permission action: one of the four CRUD operations, or `"manage"` for all.
  *
@@ -63,24 +97,37 @@ declare const CRUD_ACTIONS: readonly CrudAction[];
 type WhereClause = (columns: Record<string, unknown>, user: unknown) => DrizzleSQL | undefined;
 /**
  * A single permission grant: an action on a subject, optionally restricted by a `where` clause.
+ *
+ * `subject` may be a Drizzle table object, a string table name (e.g.
+ * `"projects"`), or the literal `"all"` for grants that apply to every table.
+ * String and object subjects are normalized to the same key by
+ * {@link getTableName} during matching, so the two forms are interchangeable
+ * at runtime.
  */
 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";
+    /**
+     * The subject of the grant: a Drizzle table object, a string table name,
+     * or `"all"` for every table.
+     */
+    subject: DrizzleTable | string;
     /** Optional row-level filter that restricts which rows this grant covers. */
     where?: WhereClause;
 };
 /**
- * Type-safe grant builder function, parameterized by the user type.
+ * Type-safe grant builder function, parameterized by the user type and an
+ * optional schema map.
  *
  * Used when `grants` is provided as a callback in {@link PermissionsConfig}
- * so that `where` clauses receive a correctly typed `user` parameter.
+ * so that `where` clauses receive a correctly typed `user` parameter and
+ * string subjects are constrained to known table names from `TTables`.
  *
  * @typeParam TUser - The user type passed to `where` clause callbacks.
+ * @typeParam TTables - Optional schema map (e.g. `typeof schema`) used to
+ *   constrain string subjects to known table-name literals.
  */
-type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all", options?: {
+type GrantFn<TUser, TTables extends SchemaMap = SchemaMap> = (action: PermissionAction, subject: SubjectInput<TTables>, options?: {
     where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
 }) => Grant;
 /**
@@ -90,19 +137,27 @@ type GrantFn<TUser> = (action: PermissionAction, subject: DrizzleTable | "all",
  * 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.
  *
+ * The `table` field accepts either a Drizzle table object or a string table
+ * name; both forms are normalized to the same key by {@link getTableName}.
+ *
  * @example
  * ```typescript
  * const descriptor: PermissionDescriptor = {
  *   action: "update",
- *   table: posts,
+ *   table: posts,         // object form
+ * };
+ *
+ * const descriptor2: PermissionDescriptor = {
+ *   action: "create",
+ *   table: "posts",       // string form
  * };
  * ```
  */
 type PermissionDescriptor = {
     /** The operation being checked. */
     action: PermissionAction;
-    /** The Drizzle table the operation targets. */
-    table: DrizzleTable;
+    /** The Drizzle table or string table name the operation targets. */
+    table: DrizzleTable | string;
 };
 /**
  * Result of a permission check via {@link checkPermissions}.
@@ -120,12 +175,14 @@ type PermissionCheckResult = {
  *
  * @typeParam TRoles - Tuple of role name string literals (use `as const`).
  * @typeParam TUser - The user type for typed `where` clauses (defaults to `unknown`).
+ * @typeParam TTables - Optional schema map used to constrain string subjects
+ *   inside the `grants` callback to known table names.
  */
-type PermissionsConfig<TRoles extends readonly string[], TUser = unknown> = {
+type PermissionsConfig<TRoles extends readonly string[], TUser = unknown, TTables extends SchemaMap = SchemaMap> = {
     /** 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[]>);
+    grants: Record<TRoles[number], Grant[]> | ((grant: GrantFn<TUser, TTables>) => Record<TRoles[number], Grant[]>);
     /** Optional role hierarchy declaring which roles inherit from which. */
     hierarchy?: Partial<Record<TRoles[number], TRoles[number][]>>;
 };
@@ -151,8 +208,8 @@ type Permissions<TRoles extends readonly string[] = readonly string[]> = {
 type ForbiddenErrorOptions = {
     /** The action that was denied. */
     action: PermissionAction;
-    /** The Drizzle table the action targeted. */
-    table: DrizzleTable;
+    /** The Drizzle table or string table name the action targeted. */
+    table: DrizzleTable | string;
     /** The role that lacked the permission, if known. */
     role?: string;
     /** The full list of permission descriptors that were checked. */
@@ -168,8 +225,8 @@ type ForbiddenErrorOptions = {
 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 Drizzle table or string table name the action targeted. */
+    readonly table: DrizzleTable | string;
     /** The role that lacked the permission, or `undefined` if not specified. */
     readonly role: string | undefined;
     /** The full list of permission descriptors that were checked. */
@@ -194,4 +251,4 @@ declare class ForbiddenError extends Error {
     };
 }
 
-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 };
+export { CRUD_ACTIONS as C, type DrizzleTable as D, ForbiddenError as F, type Grant as G, type PermissionsConfig as P, type SchemaMap as S, type TableName as T, type WhereClause as W, type Permissions as a, type PermissionAction as b, type SubjectInput as c, type PermissionDescriptor as d, type PermissionCheckResult as e, type CrudAction as f, type GrantFn as g, getTableName as h };

package/dist/client.d.ts

@@ -1 +1 @@
-export { e as CrudAction, F as ForbiddenError, b as PermissionAction, d as PermissionCheckResult, c as PermissionDescriptor } from './client-CJBFS0IS.js';
+export { f as CrudAction, F as ForbiddenError, b as PermissionAction, e as PermissionCheckResult, d as PermissionDescriptor } from './client-C7xdwHTk.js';

package/dist/client.js

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

package/dist/index.d.ts

@@ -1,13 +1,17 @@
-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';
+import { P as PermissionsConfig, a as Permissions, S as SchemaMap, b as PermissionAction, c as SubjectInput, W as WhereClause, G as Grant, d as PermissionDescriptor, e as PermissionCheckResult } from './client-C7xdwHTk.js';
+export { C as CRUD_ACTIONS, f as CrudAction, D as DrizzleTable, F as ForbiddenError, g as GrantFn, T as TableName, h as getTableName } from './client-C7xdwHTk.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:
+ * Supports three calling styles:
  * - **Direct:** `definePermissions(config)` when no custom user type is needed.
- * - **Curried:** `definePermissions<MyUser>()(config)` to get typed `where` clause user parameters.
+ * - **Curried (user only):** `definePermissions<MyUser>()(config)` for typed
+ *   `where` clause user parameters.
+ * - **Curried (user + tables):** `definePermissions<MyUser, typeof schema>()(config)`
+ *   to additionally constrain string subjects passed to the `grant` callback
+ *   to known table names from the schema map.
  *
  * @param config - The permissions configuration with roles, grants, and optional hierarchy.
  * @returns A {@link Permissions} object containing roles, raw grants, and hierarchy-expanded `resolvedGrants`.
@@ -16,8 +20,10 @@ export { C as CRUD_ACTIONS, e as CrudAction, F as ForbiddenError, f as GrantFn,
  * ```typescript
  * import { definePermissions, grant } from "@cfast/permissions";
  * import { eq } from "drizzle-orm";
- * import { posts, comments } from "./schema";
+ * import * as schema from "./schema";
+ * const { posts, comments } = schema;
  *
+ * // Direct form — accepts table objects
  * const permissions = definePermissions({
  *   roles: ["anonymous", "user", "admin"] as const,
  *   grants: {
@@ -27,15 +33,29 @@ export { C as CRUD_ACTIONS, e as CrudAction, F as ForbiddenError, f as GrantFn,
  *     user: [
  *       grant("read", posts),
  *       grant("create", posts),
- *       grant("update", posts, { where: (p, u) => eq(p.authorId, u.id) }),
  *     ],
  *     admin: [grant("manage", "all")],
  *   },
  * });
+ *
+ * // Curried form — string subjects constrained to known tables
+ * type AuthUser = { id: string };
+ * const perms = definePermissions<AuthUser, typeof schema>()({
+ *   roles: ["user", "admin"] as const,
+ *   grants: (grant) => ({
+ *     user: [
+ *       grant("read", "posts"),               // string form
+ *       grant("update", posts, {              // object form still works
+ *         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>;
+declare function definePermissions<TUser, TTables extends SchemaMap = SchemaMap>(): <TRoles extends readonly string[]>(config: PermissionsConfig<TRoles, TUser, TTables>) => Permissions<TRoles>;
 
 /**
  * Declares that a role can perform an action on a subject, optionally restricted
@@ -44,8 +64,15 @@ declare function definePermissions<TUser>(): <TRoles extends readonly string[]>(
  * Used inside the `grants` map of {@link definePermissions} to build permission rules.
  * A grant without a `where` clause applies to all rows.
  *
+ * Subjects accept three forms (all interchangeable at runtime):
+ * - A {@link DrizzleTable} object reference (the original form).
+ * - A string table name (e.g. `"projects"`) — when called via the `grant`
+ *   callback inside `definePermissions<User, typeof schema>()`, strings are
+ *   constrained to known table names by TypeScript.
+ * - The literal `"all"` for grants that apply to every table.
+ *
  * @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 subject - A Drizzle table reference, a string table name, 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.
@@ -56,9 +83,13 @@ declare function definePermissions<TUser>(): <TRoles extends readonly string[]>(
  * import { eq } from "drizzle-orm";
  * import { posts } from "./schema";
  *
- * // Unrestricted read on all posts
+ * // Object form (always works)
  * grant("read", posts);
  *
+ * // String form (works standalone; type-checked when called via the
+ * // `grant` callback inside `definePermissions<User, typeof schema>()`)
+ * grant("read", "posts");
+ *
  * // Only allow updating own posts
  * grant("update", posts, {
  *   where: (post, user) => eq(post.authorId, user.id),
@@ -68,10 +99,46 @@ declare function definePermissions<TUser>(): <TRoles extends readonly string[]>(
  * grant("manage", "all");
  * ```
  */
-declare function grant(action: PermissionAction, subject: DrizzleTable | "all", options?: {
+declare function grant<TTables extends SchemaMap = SchemaMap>(action: PermissionAction, subject: SubjectInput<TTables>, options?: {
     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`.
+ *
+ * Accepts either a Drizzle table object or a string table name. The two forms
+ * are interchangeable and resolve to the same underlying key. To get
+ * compile-time validation that a string table name actually exists in your
+ * schema, supply the schema map as a generic argument: `can<typeof schema>(...)`.
+ *
+ * @typeParam TTables - Optional schema map (e.g. `typeof schema`) used to
+ *   constrain string subjects to known table-name literals.
+ * @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 or string table name to check against.
+ * @returns `true` if any grant permits the action on the table.
+ *
+ * @example
+ * ```ts
+ * import { can } from "@cfast/permissions";
+ * import * as schema from "../db/schema";
+ *
+ * // Object form (always works)
+ * if (!can(ctx.auth.grants, "create", schema.posts)) throw redirect("/");
+ *
+ * // String form (always allowed; type-checked when a schema generic is supplied)
+ * if (!can<typeof schema>(ctx.auth.grants, "create", "posts")) throw redirect("/");
+ *
+ * // In a component
+ * {can(grants, "update", schema.posts) && <Button>Edit</Button>}
+ * ```
+ */
+declare function can<TTables extends SchemaMap = SchemaMap>(grants: Grant[], action: PermissionAction, table: SubjectInput<TTables>): boolean;
+
 /**
  * Checks whether a role satisfies a set of permission descriptors.
  *
@@ -106,6 +173,14 @@ declare function grant(action: PermissionAction, subject: DrizzleTable | "all",
  */
 declare function checkPermissions(role: string, permissions: Permissions, descriptors: PermissionDescriptor[]): PermissionCheckResult;
 
+/**
+ * Minimal user shape accepted by {@link resolveGrants}: any object with a
+ * `roles` array. The function reads `.roles` and forwards them to the
+ * underlying merge logic.
+ */
+type UserWithRoles = {
+    roles: readonly string[];
+};
 /**
  * Resolves and merges grants for multiple roles into a single flat array.
  *
@@ -117,10 +192,27 @@ declare function checkPermissions(role: string, permissions: Permissions, descri
  *
  * This is used when a user has multiple roles and their grants need to be combined.
  *
+ * Two calling styles are supported (both equivalent):
+ * - **User object (preferred):** `resolveGrants(permissions, user)` where
+ *   `user` has a `roles` field. The function extracts roles internally.
+ * - **Roles array (legacy):** `resolveGrants(permissions, roles)` where
+ *   `roles` is a string array. Still supported for backwards compatibility.
+ *
  * @param permissions - The permissions object from {@link definePermissions}.
- * @param roles - Array of role names whose grants should be merged.
+ * @param userOrRoles - Either a user object with a `roles` field, or an
+ *   array of role names whose grants should be merged.
  * @returns A deduplicated array of {@link Grant} objects with merged `where` clauses.
+ *
+ * @example
+ * ```ts
+ * // Preferred: pass the user directly
+ * const grants = resolveGrants(permissions, user);
+ *
+ * // Legacy: pass roles array (still works)
+ * const grants = resolveGrants(permissions, user.roles);
+ * ```
  */
-declare function resolveGrants(permissions: Permissions, roles: string[]): Grant[];
+declare function resolveGrants(permissions: Permissions, user: UserWithRoles): Grant[];
+declare function resolveGrants(permissions: Permissions, roles: readonly string[]): Grant[];
 
-export { DrizzleTable, Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, WhereClause, checkPermissions, definePermissions, grant, resolveGrants };
+export { Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, SchemaMap, SubjectInput, type UserWithRoles, WhereClause, can, checkPermissions, definePermissions, grant, resolveGrants };

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   CRUD_ACTIONS,
   ForbiddenError,
   getTableName
-} from "./chunk-I35WLWUH.js";
+} from "./chunk-NCLN5YBQ.js";
 
 // src/grant.ts
 function grant(action, subject, options) {
@@ -58,11 +58,23 @@ function resolveHierarchy(roles, grants, hierarchy) {
   return resolved;
 }
 
+// src/can.ts
+function can(grants, action, table) {
+  const targetKey = getTableName(table);
+  return grants.some((g) => {
+    const actionOk = g.action === action || g.action === "manage";
+    if (!actionOk) return false;
+    if (g.subject === "all") return true;
+    return getTableName(g.subject) === targetKey;
+  });
+}
+
 // 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;
+  if (!actionOk) return false;
+  if (g.subject === "all") return true;
+  return getTableName(g.subject) === getTableName(table);
 }
 function hasGrantFor(grants, action, table) {
   return grants.some((g) => grantMatches(g, action, table));
@@ -101,7 +113,11 @@ import { or } from "drizzle-orm";
 function toSQLWrapper(value) {
   return value;
 }
-function resolveGrants(permissions, roles) {
+function isUserWithRoles(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Array.isArray(value.roles);
+}
+function resolveGrants(permissions, userOrRoles) {
+  const roles = isUserWithRoles(userOrRoles) ? userOrRoles.roles : userOrRoles;
   const allGrants = [];
   for (const role of roles) {
     const roleGrants = permissions.resolvedGrants[role];
@@ -113,16 +129,18 @@ function resolveGrants(permissions, roles) {
   const groups = /* @__PURE__ */ new Map();
   const subjectIds = /* @__PURE__ */ new Map();
   let nextId = 0;
-  function getSubjectId(subject) {
+  function getSubjectKey(subject) {
+    if (subject === "all") return "all";
+    if (typeof subject === "string") return `s:${subject}`;
     let id = subjectIds.get(subject);
     if (id === void 0) {
       id = nextId++;
       subjectIds.set(subject, id);
     }
-    return id;
+    return `o:${id}`;
   }
   for (const g of allGrants) {
-    const key = `${g.action}:${getSubjectId(g.subject)}`;
+    const key = `${g.action}:${getSubjectKey(g.subject)}`;
     let group = groups.get(key);
     if (!group) {
       group = { action: g.action, subject: g.subject, wheres: [] };
@@ -162,6 +180,7 @@ function resolveGrants(permissions, roles) {
 export {
   CRUD_ACTIONS,
   ForbiddenError,
+  can,
   checkPermissions,
   definePermissions,
   getTableName,