@cfast/permissions 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+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-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-DKSiBBkt.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Minimal structural type for a Drizzle ORM table reference.
+ *
+ * Drizzle stores table metadata via Symbols (e.g., `Symbol('drizzle:Name')`).
+ * Uses `object` so real Drizzle table classes (which lack an explicit index
+ * signature) are assignable without an `as` cast, while still excluding
+ * primitives.
+ */
+type DrizzleTable = object;
+/**
+ * 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;
+};
+/**
+ * A schema map: an object mapping table names to Drizzle table references.
+ *
+ * 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.
+ */
+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.
+ *
+ * - `"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`).
+ * @param lookups - Resolved values from the grant's `with` map (see {@link Grant.with}).
+ *   Empty object when the grant declares no `with` map. Each key holds the awaited
+ *   result of the lookup function with the same name.
+ * @returns A Drizzle SQL expression to restrict matching rows, or `undefined` for no restriction.
+ */
+type WhereClause = (columns: Record<string, unknown>, user: unknown, lookups: Record<string, unknown>) => DrizzleSQL | undefined;
+/**
+ * Minimal structural type for the read-only database handle passed to grant
+ * `with` lookup functions.
+ *
+ * Defined here so the permissions package stays independent of `@cfast/db`.
+ * The runtime instance is provided by `@cfast/db` (an unsafe-mode db) and
+ * is structurally compatible with this interface, so authors can call
+ * `db.query(table).findMany().run()` inside a lookup without casting.
+ *
+ * The `query` method is intentionally typed loosely (`unknown` arguments and
+ * results) to avoid pulling Drizzle generics into the permissions surface.
+ * Authors typically know exactly which table they are querying and cast the
+ * result inline.
+ */
+interface LookupDb {
+    query: (table: DrizzleTable | string) => {
+        findMany: (options?: unknown) => {
+            run: (params?: unknown) => Promise<unknown[]>;
+        };
+        findFirst: (options?: unknown) => {
+            run: (params?: unknown) => Promise<unknown>;
+        };
+    };
+}
+/**
+ * A single prerequisite lookup function for a grant's `with` map.
+ *
+ * Lookups run **before** the main query and their resolved values are passed
+ * as the third argument to the grant's {@link WhereClause}. Use them to gather
+ * data from other tables that a row-level filter depends on (for example,
+ * the set of friend ids that a user can see content for).
+ *
+ * Lookups receive an unsafe-mode db handle so they can read freely without
+ * recursively triggering permission checks. Their results are cached for the
+ * lifetime of the per-request `Db` instance, so a single lookup runs at most
+ * once even when the same grant is consulted multiple times.
+ *
+ * @typeParam TUser - The user type (typed via `definePermissions<TUser>`).
+ */
+type LookupFn<TUser = unknown> = (user: TUser, db: LookupDb) => Promise<unknown> | unknown;
+/**
+ * A map of named prerequisite lookups for a grant.
+ *
+ * Each value is a {@link LookupFn} whose resolved result is passed to the
+ * grant's `where` clause via the third `lookups` argument under the same key.
+ *
+ * @typeParam TUser - The user type (typed via `definePermissions<TUser>`).
+ */
+type WithLookups<TUser = unknown> = Record<string, LookupFn<TUser>>;
+/**
+ * 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 subject of the grant: a Drizzle table object, a string table name,
+     * or `"all"` for every table.
+     */
+    subject: DrizzleTable | string;
+    /**
+     * Optional prerequisite lookups that resolve **before** the main query and
+     * are passed to the {@link where} clause as its third argument.
+     *
+     * Each lookup receives the current user and an unsafe-mode db handle and
+     * may return any value (synchronously or as a promise). Results are cached
+     * per `Db` instance, so a single lookup runs at most once per request even
+     * when the same grant participates in multiple queries.
+     *
+     * @example
+     * ```ts
+     * grant("read", recipes, {
+     *   with: {
+     *     friendIds: async (user, db) => {
+     *       const rows = await db
+     *         .query(friendGrants)
+     *         .findMany({ where: eq(friendGrants.grantee, user.id) })
+     *         .run();
+     *       return (rows as { target: string }[]).map((r) => r.target);
+     *     },
+     *   },
+     *   where: (recipe, user, { friendIds }) =>
+     *     or(
+     *       eq(recipe.visibility, "public"),
+     *       eq(recipe.authorId, user.id),
+     *       inArray(recipe.authorId, friendIds as string[]),
+     *     ),
+     * });
+     * ```
+     */
+    with?: WithLookups;
+    /** Optional row-level filter that restricts which rows this grant covers. */
+    where?: WhereClause;
+};
+/**
+ * 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 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, TTables extends SchemaMap = SchemaMap> = <TWith extends WithLookups<TUser> = WithLookups<TUser>>(action: PermissionAction, subject: SubjectInput<TTables>, options?: {
+    /**
+     * Prerequisite lookups whose resolved values are passed to {@link where}
+     * via its third argument. See {@link Grant.with}.
+     */
+    with?: TWith;
+    /**
+     * Row-level filter. The third argument exposes the resolved values from
+     * {@link with}, keyed by the same names; pass an empty `with` map (or
+     * omit it) when the filter does not need cross-table data.
+     */
+    where?: (columns: Record<string, unknown>, user: TUser, lookups: {
+        [K in keyof TWith]: Awaited<ReturnType<TWith[K]>>;
+    }) => 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.
+ *
+ * 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,         // object form
+ * };
+ *
+ * const descriptor2: PermissionDescriptor = {
+ *   action: "create",
+ *   table: "posts",       // string form
+ * };
+ * ```
+ */
+type PermissionDescriptor = {
+    /** The operation being checked. */
+    action: PermissionAction;
+    /** The Drizzle table or string table name the operation targets. */
+    table: DrizzleTable | string;
+};
+/**
+ * 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`).
+ * @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, 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, TTables>) => 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 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. */
+    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 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. */
+    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 LookupDb as L, type PermissionsConfig as P, type SchemaMap as S, type TableName as T, type WithLookups as W, type Permissions as a, type PermissionAction as b, type SubjectInput as c, type WhereClause as d, type PermissionDescriptor as e, type PermissionCheckResult as f, type CrudAction as g, type GrantFn as h, type LookupFn as i, getTableName as j };

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 { g as CrudAction, F as ForbiddenError, b as PermissionAction, f as PermissionCheckResult, e as PermissionDescriptor } from './client-DKSiBBkt.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 WithLookups, d as WhereClause, G as Grant, e as PermissionDescriptor, f as PermissionCheckResult } from './client-DKSiBBkt.js';
+export { C as CRUD_ACTIONS, g as CrudAction, D as DrizzleTable, F as ForbiddenError, h as GrantFn, L as LookupDb, i as LookupFn, T as TableName, j as getTableName } from './client-DKSiBBkt.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,19 +83,45 @@ 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),
  * });
  *
+ * // Cross-table grant: read recipes that public, owned by the user, or
+ * // owned by a friend (resolved via a prerequisite lookup that runs once
+ * // per request and is cached for subsequent reads).
+ * grant("read", recipes, {
+ *   with: {
+ *     friendIds: async (user, db) => {
+ *       const rows = await db
+ *         .query(friendGrants)
+ *         .findMany({ where: eq(friendGrants.grantee, user.id) })
+ *         .run();
+ *       return (rows as { target: string }[]).map((r) => r.target);
+ *     },
+ *   },
+ *   where: (recipe, user, { friendIds }) =>
+ *     or(
+ *       eq(recipe.visibility, "public"),
+ *       eq(recipe.authorId, user.id),
+ *       inArray(recipe.authorId, friendIds as string[]),
+ *     ),
+ * });
+ *
  * // Full access to everything
  * 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?: {
+    with?: WithLookups;
     where?: WhereClause;
 }): Grant;
 
@@ -79,25 +132,34 @@ declare function grant(action: PermissionAction, subject: DrizzleTable | "all",
  * 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 to check against.
+ * @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("/");
  *
- * // In a loader
- * if (!can(ctx.auth.grants, "create", 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", posts) && <Button>Edit</Button>}
+ * {can(grants, "update", schema.posts) && <Button>Edit</Button>}
  * ```
  */
-declare function can(grants: Grant[], action: PermissionAction, table: DrizzleTable): boolean;
+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.
@@ -133,6 +195,14 @@ declare function can(grants: Grant[], action: PermissionAction, table: DrizzleTa
  */
 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.
  *
@@ -144,10 +214,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, can, checkPermissions, definePermissions, grant, resolveGrants };
+export { Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, SchemaMap, SubjectInput, type UserWithRoles, WhereClause, WithLookups, can, checkPermissions, definePermissions, grant, resolveGrants };

package/dist/index.js

@@ -2,13 +2,14 @@ import {
   CRUD_ACTIONS,
   ForbiddenError,
   getTableName
-} from "./chunk-I35WLWUH.js";
+} from "./chunk-NCLN5YBQ.js";
 
 // src/grant.ts
 function grant(action, subject, options) {
   return {
     action,
     subject,
+    with: options?.with,
     where: options?.where
   };
 }
@@ -60,18 +61,21 @@ function resolveHierarchy(roles, grants, hierarchy) {
 
 // src/can.ts
 function can(grants, action, table) {
+  const targetKey = getTableName(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;
+    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));
@@ -110,7 +114,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];
@@ -122,48 +130,62 @@ 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: [] };
+      group = { action: g.action, subject: g.subject, grants: [] };
       groups.set(key, group);
     }
-    group.wheres.push(g.where);
+    group.grants.push(g);
   }
   const result = [];
   for (const group of groups.values()) {
-    const hasUnrestricted = group.wheres.some((w) => w === void 0);
+    const hasUnrestricted = group.grants.some((g) => !g.where);
     if (hasUnrestricted) {
       result.push({ action: group.action, subject: group.subject });
-    } else {
-      const whereFns = group.wheres.filter(
-        (w) => w !== void 0
+      continue;
+    }
+    const withLookups = group.grants.filter((g) => g.with !== void 0);
+    const plain = group.grants.filter((g) => g.with === void 0 && g.where);
+    for (const g of withLookups) {
+      result.push({
+        action: group.action,
+        subject: group.subject,
+        with: g.with,
+        where: g.where
+      });
+    }
+    if (plain.length === 1) {
+      result.push({
+        action: group.action,
+        subject: group.subject,
+        where: plain[0].where
+      });
+    } else if (plain.length > 1) {
+      const whereFns = plain.map(
+        (g) => g.where
+      );
+      const merged = (columns, user, lookups) => or(
+        ...whereFns.map(
+          (fn) => toSQLWrapper(fn(columns, user, lookups))
+        )
       );
-      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
-        });
-      }
+      result.push({
+        action: group.action,
+        subject: group.subject,
+        where: merged
+      });
     }
   }
   return result;

package/llms.txt

@@ -43,6 +43,23 @@ const permissions = definePermissions<MyUser>()({
 });
 ```
 
+**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> = {
@@ -54,26 +71,90 @@ type Permissions<TRoles> = {
 
 ### `grant(action, subject, options?): Grant`
 ```typescript
-grant(action: PermissionAction, subject: DrizzleTable | "all", options?: { where?: WhereClause }): Grant
+grant(action: PermissionAction, subject: DrizzleTable | string, options?: {
+  with?: WithLookups;
+  where?: WhereClause;
+}): Grant
 ```
 - `PermissionAction`: `"read" | "create" | "update" | "delete" | "manage"`
-- `WhereClause`: `(columns, user) => DrizzleSQL | undefined`
+- `WhereClause`: `(columns, user, lookups) => DrizzleSQL | undefined`
+- `WithLookups`: `Record<string, (user, db) => Promise<unknown> | unknown>`
+- `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.
+
+#### Cross-table grants via `with`
+
+When a row-level filter needs data from another table (e.g. "recipes are visible if the user is in the recipe author's friend list"), declare the prerequisite read in the `with` map. Each entry runs **before** the main query, its result is passed to `where` under the same name, and results are cached per-request via the `Db` instance — a lookup runs at most once per request even when consulted by multiple queries.
+
+```typescript
+import { definePermissions } from "@cfast/permissions";
+import { eq, inArray, or } from "drizzle-orm";
+import * as schema from "./schema";
+const { recipes, friendGrants } = schema;
+
+type AppUser = { id: string; roles: string[] };
+
+export const permissions = definePermissions<AppUser, typeof schema>()({
+  roles: ["user"] as const,
+  grants: (g) => ({
+    user: [
+      g("read", recipes, {
+        with: {
+          // db is an unsafe-mode handle so the lookup itself isn't filtered.
+          friendIds: async (user, db) => {
+            const rows = await db
+              .query(friendGrants)
+              .findMany({ where: eq(friendGrants.grantee, user.id) })
+              .run();
+            return (rows as { target: string }[]).map((r) => r.target);
+          },
+        },
+        where: (recipe, user, { friendIds }) =>
+          or(
+            eq(recipe.visibility, "public"),
+            eq(recipe.authorId, user.id),
+            inArray(recipe.authorId, friendIds as string[]),
+          ),
+      }),
+    ],
+  }),
+});
+```
+
+Notes on `with` semantics:
+- Lookup functions receive the user and a `LookupDb` (the unsafe sibling of the per-request `Db`); they may return any value, sync or async.
+- Multiple lookups in a single grant resolve in **parallel** before the where clause is invoked.
+- Results live in a per-`Db` cache keyed by grant identity, so the same grant participating in many `findMany`/`findFirst`/`paginate`/`update`/`delete` calls during one request only triggers each lookup once.
+- A sibling **unrestricted** grant (e.g. an admin role) collapses the group, so the lookup is skipped entirely.
+- A `with`-grant is never folded into another grant's `where` closure during `resolveGrants` — it stays a standalone grant so its lookup map can resolve independently.
 
 ### `checkPermissions(role, permissions, descriptors): PermissionCheckResult`
 ```typescript
 import { checkPermissions } from "@cfast/permissions";
 
 const result = checkPermissions("user", permissions, [
-  { action: "update", table: posts },
+  { 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, roles): Grant[]`
+### `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";
@@ -90,13 +171,23 @@ class ForbiddenError extends Error {
 ### `can(grants, action, table): boolean`
 ```typescript
 import { can } from "@cfast/permissions";
-function can(grants: Grant[], action: PermissionAction, table: DrizzleTable): boolean
+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
-can(grants, "create", posts)  // → boolean
-can(grants, "delete", comments) // → boolean
+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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/permissions",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Isomorphic, composable permission system with Drizzle-native row-level access control",
   "keywords": [
     "cfast",
@@ -36,13 +36,6 @@
   "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"
   },
@@ -50,5 +43,12 @@
     "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/dist/client-CJBFS0IS.d.ts

@@ -1,197 +0,0 @@
-/**
- * Minimal structural type for a Drizzle ORM table reference.
- *
- * Drizzle stores table metadata via Symbols (e.g., `Symbol('drizzle:Name')`).
- * Uses `object` so real Drizzle table classes (which lack an explicit index
- * signature) are assignable without an `as` cast, while still excluding
- * primitives.
- */
-type DrizzleTable = object;
-/**
- * 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: unknown) => 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 };