@cfast/permissions 0.3.0 → 0.4.0

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

@@ -49,9 +49,26 @@ var ForbiddenError = class extends Error {
     };
   }
 };
+var PermissionRegistrationError = class extends Error {
+  /** The unresolved subject string that was passed to `grant()`. */
+  subject;
+  /** The available table names (both JS keys and SQL names) from the schema. */
+  availableTables;
+  constructor(subject, availableTables) {
+    const sorted = [...availableTables].sort();
+    const list = sorted.length === 0 ? "<empty schema>" : sorted.map((n) => `"${n}"`).join(", ");
+    super(
+      `grant() subject "${subject}" does not match any table in the schema. Available tables (by JS key and SQL name): ${list}. Did you forget to pass the schema as the second generic to definePermissions<User, typeof schema>()?`
+    );
+    this.name = "PermissionRegistrationError";
+    this.subject = subject;
+    this.availableTables = sorted;
+  }
+};
 
 export {
   getTableName,
   CRUD_ACTIONS,
-  ForbiddenError
+  ForbiddenError,
+  PermissionRegistrationError
 };

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

@@ -17,27 +17,61 @@ type DrizzleSQL = {
     getSQL(): unknown;
 };
 /**
- * A schema map: an object mapping table names to Drizzle table references.
+ * A schema map: an object mapping JS schema keys 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.
+ * `"projects"` or `"project_versions"`) 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}.
+ * Structural shape of a Drizzle table's static metadata used purely for
+ * type-level SQL-name extraction.
  *
- * Given `typeof schema` (where `schema` exports tables as named bindings),
- * `TableName<typeof schema>` is the union of all exported table-key strings.
+ * Drizzle tables expose their SQL name on a readonly `_.name` field (see
+ * `drizzle-orm/table` `Table._.name`). By narrowing against this shape we can
+ * extract `"project_versions"` from `typeof projectVersions` even though the
+ * runtime value lives on a `Symbol.for("drizzle:Name")` key.
  */
-type TableName<TTables extends SchemaMap> = Extract<keyof TTables, string>;
+type TableWithSqlName = {
+    _: {
+        name: string;
+    };
+};
+/**
+ * Extracts the SQL table name literal from a Drizzle table reference, or
+ * `never` when the argument is not a Drizzle table with a `_.name` field.
+ *
+ * @example
+ * ```ts
+ * const postVersions = sqliteTable("post_versions", { ... });
+ * type N = SqlNameOf<typeof postVersions>; // "post_versions"
+ * ```
+ */
+type SqlNameOf<T> = T extends TableWithSqlName ? T["_"]["name"] extends string ? T["_"]["name"] : never : never;
+/**
+ * Extracts the string-literal union of valid subject keys from a
+ * {@link SchemaMap}, including **both** the JS schema keys (e.g.
+ * `"postVersions"`) and the SQL table names (e.g. `"post_versions"`).
+ *
+ * The runtime side of `definePermissions<User, Schema>()` builds a
+ * matching lookup table keyed by both forms, so the two string forms are
+ * fully interchangeable — whichever matches your mental model.
+ *
+ * Without this, string subjects were accidentally constrained to JS keys
+ * only (#177), causing confusion when a schema's JS key differs from its
+ * SQL table name (e.g. `documentVersions` vs `document_versions`).
+ */
+type TableName<TTables extends SchemaMap> = Extract<keyof TTables, string> | SqlNameOf<TTables[keyof TTables]>;
 /**
  * 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.
+ * - A string-literal table name from {@link TableName} — either the JS schema
+ *   key (`"postVersions"`) or the SQL table name (`"post_versions"`) — both
+ *   resolve to the same underlying table at runtime.
  * - The literal `"all"` for grants that apply to every table.
  */
 type SubjectInput<TTables extends SchemaMap = SchemaMap> = DrizzleTable | TableName<TTables> | "all";
@@ -345,5 +379,28 @@ declare class ForbiddenError extends Error {
         role: string | undefined;
     };
 }
+/**
+ * Error thrown at **permission-definition time** when a string-form subject
+ * passed to the `grant` callback inside
+ * `definePermissions<User, typeof schema>()` cannot be resolved to a real
+ * Drizzle table reference from the schema map.
+ *
+ * This is the runtime sibling of the compile-time constraint on
+ * {@link TableName} — it catches cases where the schema generic was skipped,
+ * the string was typed wrong (typo, wrong case), or the table was removed
+ * from the schema without updating the grant.
+ *
+ * Unlike {@link ForbiddenError} (thrown per-request on a permission check),
+ * `PermissionRegistrationError` is thrown **once at startup** from
+ * `definePermissions()` — so a misconfigured grant fails fast and loud
+ * instead of silently matching nothing at query time.
+ */
+declare class PermissionRegistrationError extends Error {
+    /** The unresolved subject string that was passed to `grant()`. */
+    readonly subject: string;
+    /** The available table names (both JS keys and SQL names) from the schema. */
+    readonly availableTables: readonly string[];
+    constructor(subject: string, availableTables: readonly string[]);
+}
 
-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 };
+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, PermissionRegistrationError as j, type SqlNameOf as k, getTableName as l };

package/dist/client.d.ts

@@ -1 +1 @@
-export { g as CrudAction, F as ForbiddenError, b as PermissionAction, f as PermissionCheckResult, e as PermissionDescriptor } from './client-DKSiBBkt.js';
+export { g as CrudAction, F as ForbiddenError, b as PermissionAction, f as PermissionCheckResult, e as PermissionDescriptor } from './client-D6goQV8b.js';

package/dist/client.js

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

package/dist/index.d.ts

@@ -1,20 +1,44 @@
-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';
+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-D6goQV8b.js';
+export { C as CRUD_ACTIONS, g as CrudAction, D as DrizzleTable, F as ForbiddenError, h as GrantFn, L as LookupDb, i as LookupFn, j as PermissionRegistrationError, k as SqlNameOf, T as TableName, l as getTableName } from './client-D6goQV8b.js';
 
 /**
  * Creates a permission configuration that can be shared between server-side
  * enforcement (`@cfast/db`) and client-side introspection (`@cfast/actions`).
  *
- * Supports three calling styles:
- * - **Direct:** `definePermissions(config)` when no custom user type is needed.
- * - **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`.
+ * Supports four calling styles:
+ *
+ * 1. **Direct:** `definePermissions(config)` — when no custom user type and
+ *    no schema map is needed.
+ *
+ * 2. **Curried (user only):** `definePermissions<MyUser>()(config)` — types
+ *    the `user` parameter inside `where` clauses. String subjects are still
+ *    accepted but are **not** compile-time or runtime validated against a
+ *    schema; they are stored as opaque strings and matched by `getTableName`.
+ *
+ * 3. **Curried (user + schema types only, no runtime schema):**
+ *    `definePermissions<MyUser, typeof schema>()(config)` — constrains
+ *    string subjects to `"jsKey" | "sql_name"` at compile time, but at
+ *    runtime still stores strings opaquely. Prefer style (4) when you can.
+ *
+ * 4. **Curried with runtime schema (RECOMMENDED):**
+ *    `definePermissions<MyUser, typeof schema>({ schema })(config)` — walks
+ *    the schema at startup and resolves every string-form subject to the
+ *    exact Drizzle table reference the schema uses. This is the only form
+ *    that lets string-form grants work with Drizzle relational `with`
+ *    queries, because Drizzle identifies tables by reference, not name
+ *    (see issues #146, #175, #177).
+ *
+ *    - Unknown strings throw {@link PermissionRegistrationError} **at
+ *      startup** (fast, loud failure instead of silently matching nothing).
+ *    - Both the JS key (`"documentVersions"`) and the SQL table name
+ *      (`"document_versions"`) resolve to the same table reference.
+ *    - Object-form subjects still work unchanged.
+ *
+ * @param configOrOptions - Either the permissions config (style 1) or the
+ *   resolver options `{ schema }` (style 4). When omitted entirely, returns
+ *   the curried form (styles 2 and 3).
+ * @returns A {@link Permissions} object, or a function that takes a config
+ *   and returns one.
  *
  * @example
  * ```typescript
@@ -23,31 +47,30 @@ export { C as CRUD_ACTIONS, g as CrudAction, D as DrizzleTable, F as ForbiddenEr
  * import * as schema from "./schema";
  * const { posts, comments } = schema;
  *
- * // Direct form — accepts table objects
+ * // Style 1 — direct, accepts table objects
  * const permissions = definePermissions({
  *   roles: ["anonymous", "user", "admin"] as const,
  *   grants: {
  *     anonymous: [
  *       grant("read", posts, { where: (p) => eq(p.published, true) }),
  *     ],
- *     user: [
- *       grant("read", posts),
- *       grant("create", posts),
- *     ],
+ *     user: [grant("read", posts), grant("create", posts)],
  *     admin: [grant("manage", "all")],
  *   },
  * });
  *
- * // Curried form — string subjects constrained to known tables
+ * // Style 4 — recommended: runtime-resolved string subjects
  * type AuthUser = { id: string };
- * const perms = definePermissions<AuthUser, typeof schema>()({
+ * const perms = definePermissions<AuthUser, typeof schema>({ schema })({
  *   roles: ["user", "admin"] as const,
  *   grants: (grant) => ({
  *     user: [
- *       grant("read", "posts"),               // string form
- *       grant("update", posts, {              // object form still works
+ *       grant("read", "posts"),                // JS key — resolves
+ *       grant("create", "post_versions"),      // SQL name — also resolves
+ *       grant("update", posts, {               // object form still works
  *         where: (p, u) => eq(p.authorId, u.id),
  *       }),
+ *       // grant("read", "unknownTable"),      // throws at startup
  *     ],
  *     admin: [grant("manage", "all")],
  *   }),
@@ -55,6 +78,9 @@ export { C as CRUD_ACTIONS, g as CrudAction, D as DrizzleTable, F as ForbiddenEr
  * ```
  */
 declare function definePermissions<TRoles extends readonly string[]>(config: PermissionsConfig<TRoles>): Permissions<TRoles>;
+declare function definePermissions<TUser, TTables extends SchemaMap>(options: {
+    schema: TTables;
+}): <TRoles extends readonly string[]>(config: PermissionsConfig<TRoles, TUser, TTables>) => Permissions<TRoles>;
 declare function definePermissions<TUser, TTables extends SchemaMap = SchemaMap>(): <TRoles extends readonly string[]>(config: PermissionsConfig<TRoles, TUser, TTables>) => Permissions<TRoles>;
 
 /**

package/dist/index.js

@@ -1,8 +1,9 @@
 import {
   CRUD_ACTIONS,
   ForbiddenError,
+  PermissionRegistrationError,
   getTableName
-} from "./chunk-NCLN5YBQ.js";
+} from "./chunk-ISTOPBSB.js";
 
 // src/grant.ts
 function grant(action, subject, options) {
@@ -15,9 +16,43 @@ function grant(action, subject, options) {
 }
 
 // src/define-permissions.ts
-function buildPermissions(config) {
+function buildSchemaLookup(schema) {
+  const lookup = /* @__PURE__ */ new Map();
+  const available = /* @__PURE__ */ new Set();
+  if (!schema) return { lookup, available: [] };
+  for (const [jsKey, table] of Object.entries(schema)) {
+    if (!table || typeof table !== "object" && typeof table !== "function") {
+      continue;
+    }
+    lookup.set(jsKey, table);
+    available.add(jsKey);
+    const sqlName = getTableName(table);
+    if (sqlName && sqlName !== "unknown") {
+      lookup.set(sqlName, table);
+      available.add(sqlName);
+    }
+  }
+  return { lookup, available: [...available] };
+}
+function makeSchemaAwareGrant(lookup, available) {
+  const schemaGrant = ((action, subject, options) => {
+    if (typeof subject !== "string" || subject === "all") {
+      return grant(action, subject, options);
+    }
+    const resolved = lookup.get(subject);
+    if (!resolved) {
+      throw new PermissionRegistrationError(subject, available);
+    }
+    return grant(action, resolved, options);
+  });
+  return schemaGrant;
+}
+function buildPermissions(config, schema) {
   const { roles, hierarchy } = config;
-  const grantFn = grant;
+  const grantFn = schema ? (() => {
+    const { lookup, available } = buildSchemaLookup(schema);
+    return makeSchemaAwareGrant(lookup, available);
+  })() : grant;
   const grants = typeof config.grants === "function" ? config.grants(grantFn) : config.grants;
   const resolvedGrants = resolveHierarchy(roles, grants, hierarchy);
   return {
@@ -26,11 +61,20 @@ function buildPermissions(config) {
     resolvedGrants
   };
 }
-function definePermissions(config) {
-  if (config === void 0) {
+function definePermissions(configOrOptions) {
+  if (configOrOptions === void 0) {
     return (c) => buildPermissions(c);
   }
-  return buildPermissions(config);
+  if (isSchemaOptions(configOrOptions)) {
+    const { schema } = configOrOptions;
+    return (c) => buildPermissions(c, schema);
+  }
+  return buildPermissions(configOrOptions);
+}
+function isSchemaOptions(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.schema !== void 0 && typeof v.schema === "object" && v.schema !== null && v.roles === void 0;
 }
 function resolveHierarchy(roles, grants, hierarchy) {
   if (!hierarchy) {
@@ -193,6 +237,7 @@ function resolveGrants(permissions, userOrRoles) {
 export {
   CRUD_ACTIONS,
   ForbiddenError,
+  PermissionRegistrationError,
   can,
   checkPermissions,
   definePermissions,

package/llms.txt

@@ -32,34 +32,39 @@ const permissions = definePermissions({
 });
 ```
 
-**Curried form** for typed user in WHERE clauses:
-```typescript
-const permissions = definePermissions<MyUser>()({
-  roles: [...] as const,
-  grants: (grant) => ({
-    user: [ grant("update", posts, { where: (post, user) => eq(post.authorId, user.id) }) ],
-    // ...
-  }),
-});
-```
+**Curried form with schema (RECOMMENDED)** — pass the schema as a runtime argument to resolve string subjects to the exact same Drizzle table reference your schema uses. This is the only form that lets string-form grants work with Drizzle relational `with` queries, because `@cfast/db` identifies tables by reference (not name):
 
-**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>()({
+const permissions = definePermissions<MyUser, typeof schema>({ schema })({
   roles: ["member", "admin"] as const,
   grants: (grant) => ({
     member: [
-      grant("read", "projects"),                  // ✓ string form, type-checked
+      grant("read", "projects"),                  // ✓ JS key
+      grant("read", "project_versions"),          // ✓ SQL name (snake_case)
       grant("read", schema.projects),             // ✓ object form still works
-      // grant("read", "unknownTable"),           // ✗ TypeScript error
+      // grant("read", "unknownTable"),           // ✗ TypeScript error + runtime throw
     ],
     admin: [grant("manage", "all")],
   }),
 });
 ```
 
+Both JS schema keys (e.g. `"projectVersions"`) and SQL table names (e.g. `"project_versions"`) resolve to the same table reference. Unknown strings throw `PermissionRegistrationError` at **startup** — fast, loud failure instead of silently matching nothing at query time.
+
+**Curried form without runtime schema** — legacy shape that types the `user` parameter but does not resolve strings. String subjects are stored opaquely and matched by name only; cross-table `with` relational queries will silently return empty arrays. Prefer the recommended form above:
+
+```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> = {
@@ -79,7 +84,7 @@ grant(action: PermissionAction, subject: DrizzleTable | string, options?: {
 - `PermissionAction`: `"read" | "create" | "update" | "delete" | "manage"`
 - `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.
+- `subject` may be a Drizzle table object, a string table name (JS key **or** SQL name), or `"all"`. When called via the `grant` callback inside `definePermissions<User, typeof schema>({ schema })`, string subjects are resolved at startup to the exact same Drizzle table reference the schema uses, and unknown strings throw `PermissionRegistrationError`. When called standalone (not via the schema-aware callback), string subjects are stored opaquely and matched by name — prefer the resolved form so cross-table relational `with` queries work correctly.
 
 #### Cross-table grants via `with`
 
@@ -93,7 +98,7 @@ const { recipes, friendGrants } = schema;
 
 type AppUser = { id: string; roles: string[] };
 
-export const permissions = definePermissions<AppUser, typeof schema>()({
+export const permissions = definePermissions<AppUser, typeof schema>({ schema })({
   roles: ["user"] as const,
   grants: (g) => ({
     user: [
@@ -168,6 +173,20 @@ class ForbiddenError extends Error {
 }
 ```
 
+Thrown at request time when a permission check fails (row-level denial).
+
+### `PermissionRegistrationError`
+```typescript
+import { PermissionRegistrationError } from "@cfast/permissions";
+
+class PermissionRegistrationError extends Error {
+  readonly subject: string;                 // the unresolved string
+  readonly availableTables: readonly string[]; // sorted JS keys + SQL names
+}
+```
+
+Thrown **at startup** from `definePermissions<User, typeof schema>({ schema })(...)` when a string-form grant subject does not match any table in the schema. Fast, loud failure so a typo or a removed table surfaces immediately instead of silently matching nothing at query time.
+
 ### `can(grants, action, table): boolean`
 ```typescript
 import { can } from "@cfast/permissions";

package/package.json

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