@cfast/permissions 0.2.0 → 0.3.0

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

@@ -92,9 +92,61 @@ declare const CRUD_ACTIONS: readonly CrudAction[];
  *
  * @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) => DrizzleSQL | undefined;
+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.
  *
@@ -112,6 +164,37 @@ type Grant = {
      * 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;
 };
@@ -127,8 +210,20 @@ type Grant = {
  * @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> = (action: PermissionAction, subject: SubjectInput<TTables>, options?: {
-    where?: (columns: Record<string, unknown>, user: TUser) => DrizzleSQL | undefined;
+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.
@@ -251,4 +346,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 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 };
+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 { f as CrudAction, F as ForbiddenError, b as PermissionAction, e as PermissionCheckResult, d as PermissionDescriptor } from './client-C7xdwHTk.js';
+export { g as CrudAction, F as ForbiddenError, b as PermissionAction, f as PermissionCheckResult, e as PermissionDescriptor } from './client-DKSiBBkt.js';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+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
@@ -95,11 +95,33 @@ declare function definePermissions<TUser, TTables extends SchemaMap = SchemaMap>
  *   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<TTables extends SchemaMap = SchemaMap>(action: PermissionAction, subject: SubjectInput<TTables>, options?: {
+    with?: WithLookups;
     where?: WhereClause;
 }): Grant;
 
@@ -215,4 +237,4 @@ type UserWithRoles = {
 declare function resolveGrants(permissions: Permissions, user: UserWithRoles): Grant[];
 declare function resolveGrants(permissions: Permissions, roles: readonly string[]): Grant[];
 
-export { Grant, PermissionAction, PermissionCheckResult, PermissionDescriptor, Permissions, PermissionsConfig, SchemaMap, SubjectInput, type UserWithRoles, 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

@@ -9,6 +9,7 @@ function grant(action, subject, options) {
   return {
     action,
     subject,
+    with: options?.with,
     where: options?.where
   };
 }
@@ -143,36 +144,48 @@ function resolveGrants(permissions, userOrRoles) {
     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

@@ -71,12 +71,62 @@ type Permissions<TRoles> = {
 
 ### `grant(action, subject, options?): Grant`
 ```typescript
-grant(action: PermissionAction, subject: DrizzleTable | string, 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/permissions",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Isomorphic, composable permission system with Drizzle-native row-level access control",
   "keywords": [
     "cfast",