@sladkoff/kysely-access-control 0.0.6

package/README.md

@@ -0,0 +1,284 @@
+This package contains some utilities for implementing a permission system on top of the 
+[Kysely](https://github.com/koskimas/kysely) query builder.
+
+It exposes two interfaces, a low-level interface accessible via `createAccessControlPlugin` and
+and a higher level interface that is similar to Postgres's internal permissions 
+accessible via `createKyselyGrantGuard`.
+
+It uses `bun` for package installation, monorepo management, building, and running scripts and tests,
+but exports packages in a way that is compatible with Node or Deno normally.
+
+# Motivation
+
+Implementing permissions at the query builder layer makes more sense than in *each query*:
+1. **DRY-er**: Common use cases like filtering a table or omitting a column are just specified once, instead of in every query in your application.
+2. **Separation of concerns**: Maintain a part of your application responsible for generating different guards for different users and ensure that your core application logic is not polluted with permission checks, and doesn't need to change when permissions or new roles are created.
+3. **Harder to forget**: No more odd bugs where you forget to add a check for `.is_deleted` or `.tenant_id = ?`
+
+Even though PostgreSQL has a fully featured permission system, implementing permissions at the query builder layer
+can makes more sense than in *the database* itself:
+1. **Dynamically generate context specific permissions**: Postgres permissions are static, and so you can't, for example, generate permissions based on the current context / user role / action matrix. Although you can use a role per user approach, that role controls those users permissions in any context.
+3. **No security definer escape**: When using database level permissions, it's common to use security definer functions as an escape hatch. When you do, you're back to manually re-implementing parts of the permissions you want to keep.
+3. **More control**: Postgres, for example, has no deny rules, and so it can be easy to accidentally grant permissions that leak when additive roles combine.
+
+
+# High Level Grants Usage
+
+Construct a `Grant` with the following type, like:
+```typescript
+type Grant = {
+  on: Table;
+  for: 'select' | 'insert' | 'update' | 'delete' | 'all'
+  columns?: string[] // all columns are allowed if blank
+  where?: (
+    eb: ExpressionBuilder<KyselyDatabase, TableName>
+  ) => ExpressionWrapper<KyselyDatabase, TableName, SqlBool>;
+  whereType?: "permissive" | "restrictive";
+}
+```
+
+`Grant.where` and `Grant.whereType` function similar to Postgres [row level security](https://www.postgresql.org/docs/current/sql-createpolicy.html).
+
+You can check a list of grants into your codebase, like:
+```typescript
+// in some file db.ts
+import { createKyselyGrantGuard, createAccessControlPlugin } from 'kysely-access-control'
+
+const getSharedGrants = (currentUserId) => [
+  {
+    on: 'posts',
+    for: 'select'
+  },
+  {
+    on: 'comments',
+    for: 'select'
+  },
+  {
+    on: 'posts',
+    for: 'all',
+    where: (eb) => eb.eq('author_id', currentUserId)
+  },
+  {
+    on: 'comments',
+    for: 'all',
+    where: (eb) => eb.eq('author_id', currentUserId)
+  }
+]
+
+const adminGrants = [
+  {
+    on: 'accounts',
+    for: 'all',
+  }
+]
+
+const query = (userId, isAdmin) => {
+  return db.withPlugin(createAccessControlPlugin(
+    createKyselyGrantGuard(
+      getSharedGrants(userId).concat(isAdmin ? adminGrants : [])
+    )
+  )
+}
+
+// in some api.ts
+import { query } from './db.ts'
+
+// in some request handler
+// this query will have permissions enforced
+await query(req.user.id, req.user.isAdmin).selectFrom('posts').select(['id']).execute();
+```
+
+Or you can generate them from a database, storing them in some `grants` table, or 
+anything else you can think of.
+
+In my projects, I'm constructing the plugin in response to each request. In one, I'm doing it in a [tRPC middleware](https://trpc.io/docs/server/middlewares) and adding it to the RPC's context. 
+
+
+### Only Table/Column Grants
+
+Currently only table x column permissions are implemented, i.e. all grants look like:
+```sql
+grant select (id, first_name, last_name) on person to a;
+```
+
+There is no intent to implement schema level ownership or other higher level permissions.
+If you want a user to be able to access everything, just skip the `.withPlugin()` call.
+
+
+# Lower Level Access Control Usage
+
+```typescript
+import { createAccessControlPlugin, KyselyAccessControlGuard, Allow, Deny, Update, Delete, ColumnInUpdateSet } from 'kysely-access-control';
+import { Database } from './my-kysely-types.ts'
+
+// Define your guard
+const guard: KyselyAccessControlGuard<Database> = {
+  table: (table, statementType, usageContext) => {
+    // table.name is restricted to keyof Database
+    if (table.name === 'events' && statementType ===  Delete) {
+      return Deny;
+    }
+
+    return Allow;
+  },
+  column: (table, column, statementType, usageContext) => {
+    // Control if the column can be inserted, updated independently
+    if (table.name === 'events' && column.name === 'is_deleted' && statementType === Update && usageContext === ColumnInUpdateSet) {
+      return Deny;
+    }
+
+    return Allow;
+  }
+}
+
+// When executing a query...
+const events = await db
+  .withPlugin(createAccessControlPlugin(guard))
+  .updateTable('events)
+  .set({ is_deleted: false })
+  .execute();
+// throws 'UPDATE denied on events.is_deleted'
+```
+
+# Limitations
+
+## No Enforcement of Raw SQL
+
+`kysely-access-control` works by operating on the internal `OperationNode`s used in Kysely's query builder. As a result, anything [specified in raw SQL](https://kysely-org.github.io/kysely-apidoc/interfaces/Sql.html) can't be enforced.
+
+There are definitely legitimate uses that require raw SQL, but try to use it only when necessary in order to maintain most of
+the benefits of `kysely-access-control`. 
+
+For example,
+```typescript
+db.selectFrom('person')
+  .select(({ fn, val, ref }) => [ fn<string>('concat', [ref('first_name'), val(' '), ref('last_name')]) ])
+```
+
+Enforces column permissions, whereas:
+```typescript
+db.selectFrom('person')
+  .select(sql<string>`concat(first_name, ' ', last_name)`)
+```
+
+enforces only table permissions, and:
+```typescript
+sql`select concat(first_name, ' ', last_name) from person`
+```
+
+enforces nothing.
+
+## No RLS on Insert (or Check for Update out of RLS)
+
+`kysely-access-control`'s RLS works by adding user supplied expression's as where clauses in the right places. As a result, it is only capable of implementing
+the `USING` part of traditional RLS, and not the `WITH CHECK` part.
+
+As a result, we can't check that a new row version (whether inserted or updated) matches the conditions specified.
+
+## Types May Be Incorrect
+
+If you use `kysely-access-control` to restrict access to a column, the query return types may still portray 
+that column as being present (and potentially even not null), even though it will be undefined in the actual result.
+
+## Joins May Fail Where You Don't Expect
+
+Even if a foreign key is not null, if you join to a table with a `where` guard on it, the join may fail
+because the context does not permit the user to see the joined row.
+
+This is true for Postgres RLS as well.
+
+## Top Level `.selectAll()` is not allowed
+
+While `kysely-access-control` allows usage of `.selectAll()` in subqueries, it does not allow it at the top level
+because it would circumvent column permissions controls.
+
+Unfortunately, even those you provide the column list to Kysely as a type, that type is not inspectable by the plugin
+system (or at all by the runtime), and as a result we cannot do the sensible thing of replacing a `.selectAll()` with a
+select of all columns.
+
+# Features
+
+## Table/Column Statement Type + Context Controls
+
+`createAccessControlPlugin` allows you to control access to tables and columns based on the statement type and context.  
+For example, you can allow a user to select from a table, but not update it, or allow a user to update a table, but not set a particular column.
+
+For full controls, see the types of the guard:
+```typescript
+type FullKyselyAccessControlGuard<KyselyDatabase> = {
+  table: (
+    table: TableNodeTableWithKeyOf<KyselyDatabase>,
+    statementType: StatementType,
+    tableUsageContext: TableUsageContext
+  ) => TableGuardResult<KyselyDatabase>;
+
+  column: (
+    table: TableNodeTableWithKeyOf<KyselyDatabase>,
+    column: ColumnNode["column"],
+    statementType: StatementType,
+    columnUsageContext: ColumnUsageContext
+  ) => ColumnGuardResult;
+};
+
+export enum StatementType {
+  Select = "select",
+  Insert = "insert",
+  Update = "update",
+  Delete = "delete",
+}
+
+export enum ColumnUsageContext {
+  ColumnInSelectOrReturning = "column-in-select-or-returning",
+  ColumnInWhereOrJoin = "column-in-where-or-join",
+  ColumnInUpdateSet = "column-in-update-set",
+  ColumnInInsert = "column-in-insert",
+}
+
+export enum TableUsageContext {
+  TableTopLevel = "table-top-level",
+  TableInJoin = "table-in-join",
+}
+```
+
+## RLS in Select/Update/Delete 
+
+In addition to returning a simple `Allow` token to allow access, you can also return a tuple where the second
+argument is a Kysely where clause to be added to the query.
+
+For example, you can implement RLS like so:
+```typescript
+const guard: KyselyAccessControlGuard = {
+  table: (table) => {
+    if (table.name === 'people') {
+      return [
+        Allow,
+        expressionBuilder<Database, 'people'>().eb('is_deleted', 'is', false);
+      ];
+    }
+  }
+}
+```
+
+Now, any query that targets the `people` table will have `is_deleted` is false inlined as a where clause.
+
+## Column Omission vs Erroring
+
+At column level select statements, you can choose `Omit` as a third option to `Allow` vs. `Deny`.
+
+If you choose this option, the column you select will be omitted from the query, and the query will still succeed.
+
+This also works for `returning` clauses as well, whether they are on a top level insert, update, or delete statement.
+
+# Contributing
+
+The most helpful form of contribution right now would be additional tests on complex queries in your
+actual applications.
+
+Currently, `kysely-access-control` has not been tested to properly enforce permissions with every type of SQL query
+Kysely itself can generate.
+
+However, it has been programmed to throw errors if it encounters a query type that is not yet implemented,
+and it should generate these errors even if you don't enforce any particularly complex permission on them.
+
+For any of these failures, it is possible to make `kysely-access-control` work, it just requires a few more `if`s, so
+please open an issue.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./src/kyselyAccessControl";
+export * from "./src/kyselyGrants";

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./src/kyselyAccessControl"), exports);
+__exportStar(require("./src/kyselyGrants"), exports);

package/dist/src/kyselyAccessControl.d.ts

@@ -0,0 +1,40 @@
+import { ColumnNode, ExpressionWrapper, KyselyPlugin, TableNode, SqlBool } from "kysely";
+export declare const Allow: "allow";
+export declare const Deny: "deny";
+export declare const Omit: "omit";
+type TAllow = typeof Allow;
+type TDeny = typeof Deny;
+type TOmit = typeof Omit;
+export declare enum StatementType {
+    Select = "select",
+    Insert = "insert",
+    Update = "update",
+    Delete = "delete"
+}
+export declare enum ColumnUsageContext {
+    ColumnInSelectOrReturning = "column-in-select-or-returning",
+    ColumnInWhereOrJoin = "column-in-where-or-join",
+    ColumnInUpdateSet = "column-in-update-set",
+    ColumnInInsert = "column-in-insert"
+}
+export declare enum TableUsageContext {
+    TableTopLevel = "table-top-level",
+    TableInJoin = "table-in-join"
+}
+type TableGuardResult<KyselyDatabase> = TAllow | [TAllow, ExpressionWrapper<KyselyDatabase, any, SqlBool>] | TDeny | [TDeny, string];
+type ColumnGuardResult = TAllow | TOmit | TDeny | [TDeny, string];
+type TableNodeTable = TableNode["table"];
+type TableNodeTableIdentifierWithNamesAsKeyOf<KyselyDatabase> = Omit<TableNodeTable["identifier"], "name"> & {
+    name: keyof KyselyDatabase;
+};
+type TableNodeTableWithKeyOf<KyselyDatabase> = Omit<TableNodeTable, "identifier"> & {
+    identifier: TableNodeTableIdentifierWithNamesAsKeyOf<KyselyDatabase>;
+};
+export declare const throwIfDenyWithReason: (guardResult: ColumnGuardResult | TableGuardResult<unknown>, coreErrorString: string) => void;
+type FullKyselyAccessControlGuard<KyselyDatabase = unknown> = {
+    table: (table: TableNodeTableWithKeyOf<KyselyDatabase>, statementType: StatementType, tableUsageContext: TableUsageContext) => TableGuardResult<KyselyDatabase>;
+    column: (table: TableNodeTableWithKeyOf<KyselyDatabase>, column: ColumnNode["column"], statementType: StatementType, columnUsageContext: ColumnUsageContext) => ColumnGuardResult;
+};
+export type KyselyAccessControlGuard<KyselyDatabase = unknown> = Partial<FullKyselyAccessControlGuard<KyselyDatabase>>;
+export declare const createAccessControlPlugin: <KyselyDatabase = unknown>(guard: Partial<FullKyselyAccessControlGuard<KyselyDatabase>>) => KyselyPlugin;
+export {};

package/dist/src/kyselyAccessControl.js

@@ -0,0 +1,459 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAccessControlPlugin = exports.throwIfDenyWithReason = exports.TableUsageContext = exports.ColumnUsageContext = exports.StatementType = exports.Omit = exports.Deny = exports.Allow = void 0;
+const kysely_1 = require("kysely");
+const tiny_invariant_1 = __importDefault(require("tiny-invariant"));
+exports.Allow = "allow";
+exports.Deny = "deny";
+exports.Omit = "omit";
+var StatementType;
+(function (StatementType) {
+    StatementType["Select"] = "select";
+    StatementType["Insert"] = "insert";
+    StatementType["Update"] = "update";
+    StatementType["Delete"] = "delete";
+})(StatementType || (exports.StatementType = StatementType = {}));
+var ColumnUsageContext;
+(function (ColumnUsageContext) {
+    ColumnUsageContext["ColumnInSelectOrReturning"] = "column-in-select-or-returning";
+    ColumnUsageContext["ColumnInWhereOrJoin"] = "column-in-where-or-join";
+    ColumnUsageContext["ColumnInUpdateSet"] = "column-in-update-set";
+    ColumnUsageContext["ColumnInInsert"] = "column-in-insert";
+})(ColumnUsageContext || (exports.ColumnUsageContext = ColumnUsageContext = {}));
+var TableUsageContext;
+(function (TableUsageContext) {
+    TableUsageContext["TableTopLevel"] = "table-top-level";
+    TableUsageContext["TableInJoin"] = "table-in-join";
+})(TableUsageContext || (exports.TableUsageContext = TableUsageContext = {}));
+const throwIfDenyWithReason = (guardResult, coreErrorString) => {
+    if (guardResult === exports.Deny) {
+        throw new Error(coreErrorString);
+    }
+    if (guardResult[0] === exports.Deny) {
+        throw new Error(`${coreErrorString}: ${guardResult[1]}`);
+    }
+};
+exports.throwIfDenyWithReason = throwIfDenyWithReason;
+const createAccessControlPlugin = (guard) => {
+    // 2 things are accomplished in this translation into fullGuard
+    // 1. Default guards are provided if the user does not provide either .table or .column
+    // 2. We lose table and column keyof typings so that we can safely call these guards internally
+    //    without extra coercion
+    const fullGuard = Object.assign({ table: () => {
+            return exports.Allow;
+        }, column: () => {
+            return exports.Allow;
+        } }, guard);
+    class Transformer extends kysely_1.OperationNodeTransformer {
+        getParentNode() {
+            return this.nodeStack[this.nodeStack.length - 2]; // last element is the current one, one before is the parent
+        }
+        isAChildOf(nodeType) {
+            return this.nodeStack.find((node) => nodeType.is(node)) !== undefined;
+        }
+        /**
+         * Enforce update on a table
+         * - enforces whether the table is allowed to be updated
+         * - enforce the target columns to be updated
+         */
+        transformUpdateQuery(node) {
+            var _a, _b;
+            const tableNode = node.table;
+            (0, tiny_invariant_1.default)(kysely_1.TableNode.is(tableNode), "kysely-access-control: only table nodes are supported for update queries");
+            const guardResult = fullGuard.table(tableNode.table, StatementType.Update, TableUsageContext.TableTopLevel);
+            (0, exports.throwIfDenyWithReason)(guardResult, `UPDATE denied on table ${((_a = tableNode.table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${tableNode.table.schema.name}.` : ""}${tableNode.table.identifier.name}`);
+            // Enforce column permissions
+            if (node.updates) {
+                for (const columnUpdateNode of node.updates) {
+                    const column = columnUpdateNode.column;
+                    const guardResult = fullGuard.column(tableNode.table, column.column, StatementType.Update, ColumnUsageContext.ColumnInUpdateSet);
+                    (0, exports.throwIfDenyWithReason)(guardResult, `UPDATE denied on column ${((_b = tableNode.table.schema) === null || _b === void 0 ? void 0 : _b.name)
+                        ? `${tableNode.table.schema.name}.`
+                        : ""}${tableNode.table.identifier.name}.${column.column.name}`);
+                    if (guardResult === exports.Omit) {
+                        throw new Error(`Omit is not supported in update set: got Omit for ${column.column.name}`);
+                    }
+                }
+            }
+            // Must be allow
+            return super.transformUpdateQuery(node);
+        }
+        /**
+         * Enforce insert on a table
+         * - enforces whether the table is allowed to be inserted into
+         *
+         * Enforcement of returning limitations is handled in transformReturning
+         */
+        transformInsertQuery(node) {
+            var _a, _b;
+            const tableNode = node.into;
+            const columns = node.columns;
+            const guardResult = fullGuard.table(tableNode.table, StatementType.Insert, TableUsageContext.TableTopLevel);
+            (0, exports.throwIfDenyWithReason)(guardResult, `INSERT denied on table ${((_a = tableNode.table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${tableNode.table.schema.name}.` : ""}${tableNode.table.identifier.name}`);
+            // Skip column enforcement if there are none
+            if (columns === undefined) {
+                return super.transformInsertQuery(node);
+            }
+            const transformedColumns = [];
+            for (const column of columns) {
+                const guardResult = fullGuard.column(tableNode.table, column.column, StatementType.Insert, ColumnUsageContext.ColumnInInsert);
+                (0, exports.throwIfDenyWithReason)(guardResult, `INSERT denied on column ${((_b = tableNode.table.schema) === null || _b === void 0 ? void 0 : _b.name)
+                    ? `${tableNode.table.schema.name}.`
+                    : ""}${tableNode.table.identifier.name}.${column.column.name}`);
+                if (guardResult === exports.Omit) {
+                    continue;
+                }
+                transformedColumns.push(column);
+            }
+            return super.transformInsertQuery(Object.assign(Object.assign({}, node), { columns: transformedColumns }));
+        }
+        /**
+         * Handles enforcement of column permissions in returning
+         * for insert/update/delete
+         */
+        transformReturning(node) {
+            // Check whether it's insert, update, or delete via node stack
+            const parentNode = this.getParentNode();
+            const mode = kysely_1.InsertQueryNode.is(parentNode)
+                ? StatementType.Insert
+                : kysely_1.UpdateQueryNode.is(parentNode)
+                    ? StatementType.Update
+                    : kysely_1.DeleteQueryNode.is(parentNode)
+                        ? StatementType.Delete
+                        : undefined;
+            (0, tiny_invariant_1.default)(mode !== undefined, `kysely-access-control: returning must be used with insert, update, or delete. kind was ${parentNode.kind}`);
+            const { selections } = node;
+            const [statementType, tableNode] = kysely_1.InsertQueryNode.is(parentNode)
+                ? [StatementType.Insert, parentNode.into]
+                : kysely_1.UpdateQueryNode.is(parentNode)
+                    ? [StatementType.Update, parentNode.table]
+                    : kysely_1.DeleteQueryNode.is(parentNode)
+                        ? [StatementType.Delete, parentNode.from.froms[0]]
+                        : [undefined, undefined];
+            // Only inserting into a table is supported
+            (0, tiny_invariant_1.default)(statementType !== undefined, "kysely-access-control: currently only insert/update/delete returning is supported");
+            (0, tiny_invariant_1.default)(kysely_1.TableNode.is(tableNode), "kysely-access-control: currently only update/delete from a table");
+            const transformedSelections = this._transformSelections(selections.slice(), tableNode, false, statementType);
+            const transformedNode = Object.assign(Object.assign({}, node), { selections: transformedSelections });
+            return super.transformReturning(transformedNode);
+        }
+        /**
+         * Enforce delete on a table
+         * - enforces whether the table is allowed to be deleted from
+         */
+        transformDeleteQuery(node) {
+            var _a;
+            // Ensure only 1 from and that its a table
+            (0, tiny_invariant_1.default)(node.from.froms.length === 1, "kysely-access-control: can only delete from one table at a time");
+            const tableNode = node.from.froms[0];
+            (0, tiny_invariant_1.default)(kysely_1.TableNode.is(tableNode), "kysely-access-control: can only delete from tables");
+            const guardResult = fullGuard.table(tableNode.table, StatementType.Delete, TableUsageContext.TableTopLevel);
+            (0, exports.throwIfDenyWithReason)(guardResult, `DELETE denied on table ${((_a = tableNode.table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${tableNode.table.schema.name}.` : ""}${tableNode.table.identifier.name}`);
+            // Must be allow - TODO add RLS
+            return super.transformDeleteQuery(node);
+        }
+        /**
+         * In transformSelectQuery, we:
+         * - throw if any columns are selected that shouldn't be
+         * - omit any columns we should omit (throwing if selectAll is used)
+         */
+        transformSelectQuery(node) {
+            var _a;
+            const { from: fromNode, selections, joins, where } = node;
+            if (!fromNode) {
+                // This covers queries such as select 1, or select following only by subselects
+                // We do nothing here
+                return super.transformSelectQuery(node);
+            }
+            (0, tiny_invariant_1.default)(fromNode.froms.length === 1, "kysely-access-control: there must be exactly one from node when not joining");
+            const tableNode = fromNode.froms[0];
+            (0, tiny_invariant_1.default)(kysely_1.TableNode.is(tableNode), "kysely-access-control: currently only select from table/view is supported");
+            (0, tiny_invariant_1.default)(selections !== undefined, "kysely-access-control: selections should be defined");
+            const table = tableNode.table;
+            const guardResult = fullGuard.table(table, StatementType.Select, TableUsageContext.TableTopLevel);
+            (0, exports.throwIfDenyWithReason)(guardResult, `SELECT denied on table ${((_a = table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${table.schema.name}.` : ""}${table.identifier.name}`);
+            /* COLUMN ENFORCEMENT */
+            // Some selected columns include a table, some don't
+            // If there's no joins and therefore only one valid relation to reference
+            // we can assume that the column's table is the same as the fromNode's table
+            //
+            // If there is a join, we require that the user specifies the table
+            // Even though kysely's type system and SQL engines can resolve the reference,
+            // We cannot
+            const hasJoin = joins !== undefined && joins.length > 0;
+            const transformedSelections = this._transformSelections(selections.slice(), tableNode, hasJoin, StatementType.Select);
+            const newNode = Object.assign(Object.assign({}, node), { selections: transformedSelections, where: this._transformWhere(guardResult, node.where) });
+            return super.transformSelectQuery(newNode);
+        }
+        /**
+         * Next 3 methods enforce table level permissions
+         * included Allow/Deny and row level permissions
+         * for the 3 different types of joins:
+         *  - select * from x join y on x.key = y.key
+         *  - update x from y where x.key = y.key
+         *  - delete from x using y where x.key = y.key
+         */
+        transformJoin(node) {
+            var _a;
+            const tableNode = node.table;
+            if (!kysely_1.TableNode.is(tableNode)) {
+                // If it's not a table node (it's an alias node with a subselect, etc.)
+                // Any enforcement needed will happen on those components
+                return super.transformJoin(node);
+            }
+            const guardResult = fullGuard.table(tableNode.table, StatementType.Select, TableUsageContext.TableInJoin);
+            (0, exports.throwIfDenyWithReason)(guardResult, `JOIN denied on table ${((_a = tableNode.table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${tableNode.table.schema.name}.` : ""}${tableNode.table.identifier.name}`);
+            if (guardResult === exports.Allow) {
+                return super.transformJoin(node);
+            }
+            // If RLS is applied, replace the table node with a select node that has the RLS applied inline
+            // This means replacing the "table" with an AliasNode of a SelectQueryNode + identifier with the same name
+            // Fortunately, our top level transformSelectQueryBuilder will handle applying RLS
+            // We just need to transform it to a SelectQueryBuilder with an alias so that those
+            // transformations can happen
+            const newTable = kysely_1.AliasNode.create(kysely_1.SelectQueryNode.cloneWithSelections(kysely_1.SelectQueryNode.createFrom([tableNode]), [kysely_1.SelectionNode.createSelectAll()]), kysely_1.IdentifierNode.create(tableNode.table.identifier.name));
+            return super.transformJoin(Object.assign(Object.assign({}, node), { table: newTable }));
+        }
+        transformFrom(node) {
+            const parentNode = this.getParentNode();
+            if (!kysely_1.UpdateQueryNode.is(parentNode)) {
+                return super.transformFrom(node);
+            }
+            const newFroms = node.froms.map((from) => {
+                var _a;
+                if (!kysely_1.TableNode.is(from)) {
+                    // Only guard tables - non tables (subselects) will be handled further down in
+                    // the internal SelectQueryNode
+                    return from;
+                }
+                const guardResult = fullGuard.table(from.table, StatementType.Update, TableUsageContext.TableInJoin);
+                (0, exports.throwIfDenyWithReason)(guardResult, `JOIN denied on table ${((_a = from.table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${from.table.schema.name}.` : ""}${from.table.identifier.name}`);
+                if (guardResult === exports.Allow) {
+                    return from;
+                }
+                // Must be an RLS case
+                // Again, don't worry about the where clauses
+                // those will be handled by the internal SelectQueryNode
+                return kysely_1.AliasNode.create(kysely_1.SelectQueryNode.cloneWithSelections(kysely_1.SelectQueryNode.createFrom([from]), [kysely_1.SelectionNode.createSelectAll()]), kysely_1.IdentifierNode.create(from.table.identifier.name));
+            });
+            return super.transformFrom(Object.assign(Object.assign({}, node), { froms: newFroms }));
+        }
+        transformUsing(node) {
+            const parentNode = this.getParentNode();
+            if (!kysely_1.DeleteQueryNode.is(parentNode)) {
+                return super.transformUsing(node);
+            }
+            const newTables = node.tables.map((table) => {
+                var _a;
+                if (!kysely_1.TableNode.is(table)) {
+                    // Only guard tables - non tables (subselects) will be handled further down in
+                    // the internal SelectQueryNode
+                    return table;
+                }
+                const guardResult = fullGuard.table(table.table, StatementType.Delete, TableUsageContext.TableInJoin);
+                (0, exports.throwIfDenyWithReason)(guardResult, `JOIN denied on table ${((_a = table.table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${table.table.schema.name}.` : ""}${table.table.identifier.name}`);
+                if (guardResult === exports.Allow) {
+                    return table;
+                }
+                // Must be an RLS case
+                // Again, don't worry about the where clauses
+                // those will be handled by the internal SelectQueryNode
+                return kysely_1.AliasNode.create(kysely_1.SelectQueryNode.cloneWithSelections(kysely_1.SelectQueryNode.createFrom([table]), [kysely_1.SelectionNode.createSelectAll()]), kysely_1.IdentifierNode.create(table.table.identifier.name));
+            });
+            return super.transformUsing(Object.assign(Object.assign({}, node), { tables: newTables }));
+        }
+        /**
+         * Enforce column permissions in update set clause
+         */
+        // protected transform
+        /**
+         * Enforce column permissions in where clause
+         * These are always wrapped in a reference node
+         *
+         * Reference nodes are also used in select statements, so we return early
+         * if we're not in a recursion with a WhereNode parent
+         */
+        transformReference(node) {
+            var _a;
+            const isAChildOfWhere = this.isAChildOf(kysely_1.WhereNode);
+            const isAChildOfJoin = this.isAChildOf(kysely_1.JoinNode);
+            if (!isAChildOfWhere && !isAChildOfJoin) {
+                return super.transformReference(node);
+            }
+            // If it's a child of where, then it's a column reference
+            // being used in a filter statement, so we call the guard with those parameters
+            // However, the table may not be specified, and so we need to search up the stack
+            // to something that has the table specified
+            // The entity with the specified table should be the one that is the parent of the where node
+            // but it could be an insert/update/delete or select statement
+            // TODO - we're calling the table with the wrong column here because there could be a top level join
+            // Need to refactor this to up front decide if the table specified is required
+            let tableNode;
+            const tableNodeSpecifiedWithColumn = node.table;
+            if (!tableNodeSpecifiedWithColumn) {
+                // If it's a child of join, we need the table specified
+                // It can't be inferred
+                if (!isAChildOfWhere) {
+                    throw new Error("kysely-access-control: could not find table node for column reference in join");
+                }
+                const reversedStack = this.nodeStack.slice().reverse();
+                const idxOfWhere = reversedStack.findIndex((node) => kysely_1.WhereNode.is(node));
+                const idxOfParent = idxOfWhere + 1;
+                const parentOfWhere = reversedStack[idxOfParent];
+                (0, tiny_invariant_1.default)(parentOfWhere !== undefined, "kysely-access-control: could not find parent of where node");
+                const hasJoins = this._topLevelHasMoreThanOneTable(parentOfWhere);
+                if (hasJoins) {
+                    throw new Error("kysely-access-control: if joins are present, each column reference in where must specify the table");
+                }
+                const foundTableNode = this._getTableNodeFromTopLevelQueryNode(parentOfWhere);
+                (0, tiny_invariant_1.default)(foundTableNode !== undefined, "kysely-access-control: could not find table node for column reference in filter statement");
+                (0, tiny_invariant_1.default)(kysely_1.TableNode.is(foundTableNode), "kysely-access-control: node for column reference in filter statement must be a table node");
+                tableNode = foundTableNode;
+            }
+            else {
+                tableNode = tableNodeSpecifiedWithColumn;
+            }
+            const columnNode = node.column;
+            (0, tiny_invariant_1.default)(kysely_1.ColumnNode.is(columnNode), "kysely-access-control: select all in filter statement is not supported");
+            const guardResult = fullGuard.column(tableNode.table, columnNode.column, StatementType.Select, ColumnUsageContext.ColumnInWhereOrJoin);
+            (0, exports.throwIfDenyWithReason)(guardResult, `FILTER denied on column ${((_a = tableNode.table.schema) === null || _a === void 0 ? void 0 : _a.name) ? `${tableNode.table.schema.name}.` : ""}${tableNode.table.identifier.name}.${columnNode.column.name}`);
+            // Must be allow now
+            return super.transformReference(node);
+        }
+        /*
+         * From here on down there are utility methods that are not directly called by the Kysely plugin machinery
+         */
+        /**
+         * Get whether an SelectQueryNode, UpdateQueryNode, or DeleteQueryNode has more than one table in reference scope
+         * for select and where clauses
+         */
+        _topLevelHasMoreThanOneTable(node) {
+            if (kysely_1.UpdateQueryNode.is(node)) {
+                const fromJoin = node.from;
+                if (fromJoin && fromJoin.froms.length > 0) {
+                    return true;
+                }
+                return false;
+            }
+            if (kysely_1.SelectQueryNode.is(node)) {
+                const join = node.joins;
+                return !!join && join.length > 0;
+            }
+            if (kysely_1.DeleteQueryNode.is(node)) {
+                const using = node.using;
+                if (using && using.tables && using.tables.length > 0) {
+                    return true;
+                }
+                return false;
+            }
+            throw new Error("_topLevelHasMoreThanOneTable called with something that is not a select, update, or delete query");
+        }
+        /**
+         * Get the table node for a top level query type (select, update, delete, or insert)
+         */
+        _getTableNodeFromTopLevelQueryNode(node) {
+            if (kysely_1.UpdateQueryNode.is(node)) {
+                (0, tiny_invariant_1.default)(node.table !== undefined && kysely_1.TableNode.is(node.table), "kysely-access-control: update query must have a table");
+                return node.table;
+            }
+            if (kysely_1.SelectQueryNode.is(node)) {
+                (0, tiny_invariant_1.default)(node.from !== undefined && node.from.froms.length === 1, "kysely-access-control: select query must have exactly one from");
+                (0, tiny_invariant_1.default)(kysely_1.TableNode.is(node.from.froms[0]), "kysely-access-control: select query must have a table");
+                return node.from.froms[0];
+            }
+            if (kysely_1.DeleteQueryNode.is(node)) {
+                (0, tiny_invariant_1.default)(node.from !== undefined && node.from.froms.length === 1, "kysely-access-control: delete query must have exactly one from");
+                (0, tiny_invariant_1.default)(kysely_1.TableNode.is(node.from.froms[0]), "kysely-access-control: delete query must have a table");
+                return node.from.froms[0];
+            }
+            if (kysely_1.InsertQueryNode.is(node)) {
+                (0, tiny_invariant_1.default)(kysely_1.TableNode.is(node.into), "kysely-access-control: insert query must have a table");
+                return node.into;
+            }
+            throw new Error("_getTopLevelTableNode called with something that is not a select, update, delete, or insert query");
+        }
+        /**
+         * Common utility used in transformSelectQuery, transformReturning, etc.
+         * that enforces column select permissions
+         */
+        _transformSelections(selections, tableNode, scopedHasMoreThanOneTable, statementType) {
+            var _a;
+            const transformedSelections = [];
+            // We only allow a select all IF it's inside of a join
+            // otherwise, we require that the user specifies the columns
+            const selectAllIsAllowed = this.isAChildOf(kysely_1.JoinNode) ||
+                this.isAChildOf(kysely_1.FromNode) ||
+                this.isAChildOf(kysely_1.UsingNode);
+            if (selectAllIsAllowed) {
+                return selections.slice();
+            }
+            for (const selectionNode of selections) {
+                const { selection } = selectionNode;
+                // Handle SelectQueryNode selections (from jsonObjectFrom, jsonArrayFrom, etc.)
+                if (kysely_1.SelectQueryNode.is(selection)) {
+                    // For subquery selections, recursively transform the subquery to apply access control
+                    // The subquery transformation will be handled by the parent transformer
+                    // We just need to ensure the subquery gets processed, so we pass it through
+                    // The parent transformer will call transformSelectQuery on the subquery
+                    transformedSelections.push(selectionNode);
+                    continue;
+                }
+                // Handle SelectAllNode selections (from selectAll())
+                if (selection.kind === "SelectAllNode") {
+                    throw new Error("kysely-access-control: .selectAll() is not supported");
+                }
+                // Handle ReferenceNode selections (column references)
+                if (kysely_1.ReferenceNode.is(selection)) {
+                    const { table: columnIncludedTableNode, column: columnNode } = selection;
+                    (0, tiny_invariant_1.default)(columnNode.kind !== "SelectAllNode", "kysely-access-control: .selectAll() is not supported");
+                    let tableNodeToUseForColumn = tableNode;
+                    if (scopedHasMoreThanOneTable) {
+                        (0, tiny_invariant_1.default)(columnIncludedTableNode !== undefined, `kysely-access-control: table must be specified for each column when joining - could not infer table for ${columnNode.column.name}`);
+                        tableNodeToUseForColumn = columnIncludedTableNode;
+                    }
+                    const guardResult = fullGuard.column(tableNodeToUseForColumn.table, columnNode.column, statementType, ColumnUsageContext.ColumnInSelectOrReturning);
+                    (0, exports.throwIfDenyWithReason)(guardResult, `SELECT denied on column ${((_a = tableNodeToUseForColumn.table.schema) === null || _a === void 0 ? void 0 : _a.name)
+                        ? `${tableNodeToUseForColumn.table.schema.name}.`
+                        : ""}${tableNodeToUseForColumn.table.identifier.name}.${columnNode.column.name}`);
+                    if (guardResult === exports.Omit) {
+                        continue;
+                    }
+                    transformedSelections.push(selectionNode);
+                    continue;
+                }
+                // For other selection types (expressions, raw builders, etc.), allow them to pass through
+                // These will be transformed by the parent transformer and don't directly reference main table columns
+                transformedSelections.push(selectionNode);
+            }
+            return transformedSelections;
+        }
+        _transformWhere(guardResult, nodeWhere) {
+            if (guardResult === exports.Allow) {
+                return nodeWhere;
+            }
+            const guardWhereUnguarded = guardResult[0] === exports.Allow ? guardResult[1] : undefined;
+            (0, tiny_invariant_1.default)(guardWhereUnguarded !== undefined &&
+                typeof guardWhereUnguarded === "object" &&
+                "toOperationNode" in guardWhereUnguarded, "kysely-access-control: returned where must be an expression wrapper");
+            const guardWhere = kysely_1.WhereNode.create(guardWhereUnguarded.toOperationNode());
+            const newWhere = guardWhere && nodeWhere
+                ? kysely_1.WhereNode.create(kysely_1.AndNode.create(guardWhere.where, nodeWhere.where))
+                : guardWhere || nodeWhere;
+            return super.transformWhere(newWhere);
+        }
+    }
+    const plugin = {
+        transformQuery: (args) => {
+            const transformer = new Transformer();
+            return transformer.transformNode(args.node);
+        },
+        transformResult: (args) => {
+            return Promise.resolve(args.result);
+        },
+    };
+    return plugin;
+};
+exports.createAccessControlPlugin = createAccessControlPlugin;

package/dist/src/kyselyGrants.d.ts

@@ -0,0 +1,26 @@
+import { ExpressionBuilder, ExpressionWrapper, SqlBool } from "kysely";
+import { ColumnUsageContext, StatementType } from "./kyselyAccessControl";
+type GrantWithoutWhereClause<KyselyDatabase, TableName extends keyof KyselyDatabase> = {
+    table: TableName;
+    schema?: string;
+    for: "all" | "select" | "update" | "insert" | "delete";
+    columns?: (keyof KyselyDatabase[TableName])[];
+};
+type GrantWithWhereClause<KyselyDatabase, TableName extends keyof KyselyDatabase> = GrantWithoutWhereClause<KyselyDatabase, TableName> & {
+    where: (eb: ExpressionBuilder<KyselyDatabase, TableName>) => ExpressionWrapper<KyselyDatabase, TableName, SqlBool>;
+    whereType?: "permissive" | "restrictive";
+};
+export type Grant<KyselyDatabase, TableName extends keyof KyselyDatabase> = GrantWithWhereClause<KyselyDatabase, TableName> | GrantWithoutWhereClause<KyselyDatabase, TableName>;
+export declare const createKyselyGrantGuard: <KyselyDatabase>(grants: Grant<KyselyDatabase, any>[]) => Partial<{
+    table: (table: Omit<import("kysely/dist/cjs/operation-node/schemable-identifier-node").SchemableIdentifierNode, "identifier"> & {
+        identifier: Omit<import("kysely").IdentifierNode, "name"> & {
+            name: never;
+        };
+    }, statementType: StatementType, tableUsageContext: import("./kyselyAccessControl").TableUsageContext) => "allow" | "deny" | ["deny", string] | ["allow", ExpressionWrapper<unknown, any, SqlBool>];
+    column: (table: Omit<import("kysely/dist/cjs/operation-node/schemable-identifier-node").SchemableIdentifierNode, "identifier"> & {
+        identifier: Omit<import("kysely").IdentifierNode, "name"> & {
+            name: never;
+        };
+    }, column: import("kysely").IdentifierNode, statementType: StatementType, columnUsageContext: ColumnUsageContext) => "allow" | "deny" | "omit" | ["deny", string];
+}>;
+export {};

package/dist/src/kyselyGrants.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKyselyGrantGuard = void 0;
+const kysely_1 = require("kysely");
+const kyselyAccessControl_1 = require("./kyselyAccessControl");
+const isGrantWithWhereClause = (grant) => "where" in grant;
+const createKyselyGrantGuard = (grants) => {
+    const guard = {
+        table: (table, statementType) => {
+            const allowGrants = grants.filter((grant) => {
+                var _a;
+                return ((grant.schema === undefined || grant.schema === ((_a = table.schema) === null || _a === void 0 ? void 0 : _a.name)) &&
+                    grant.table === table.identifier.name &&
+                    (grant.for === "all" || grant.for === statementType));
+            });
+            if (allowGrants.length === 0) {
+                return kyselyAccessControl_1.Deny;
+            }
+            // Now that we know we're allowing, we create all RLS
+            const grantsWithWheres = allowGrants.filter(isGrantWithWhereClause);
+            const grantsWithRestrictiveWheres = grantsWithWheres.filter((grant) => grant.whereType === "restrictive");
+            // Permissive is the default
+            const grantsWithPermissiveWheres = grantsWithWheres.filter((grant) => grant.whereType !== "restrictive");
+            if (grantsWithRestrictiveWheres.length === 0 &&
+                grantsWithPermissiveWheres.length === 0) {
+                return kyselyAccessControl_1.Allow;
+            }
+            if (grantsWithPermissiveWheres.length === 0 &&
+                grantsWithRestrictiveWheres.length > 0) {
+                // No rows will be returned - see https://www.postgresql.org/docs/current/sql-createpolicy.html
+                return [kyselyAccessControl_1.Allow, (0, kysely_1.expressionBuilder)().lit(false)];
+            }
+            const permissiveEbs = (0, kysely_1.expressionBuilder)().or(grantsWithPermissiveWheres.map((grant) => grant.where((0, kysely_1.expressionBuilder)())));
+            if (grantsWithRestrictiveWheres.length > 0) {
+                // And the or of the permissives and the and of the restrictives
+                return [
+                    kyselyAccessControl_1.Allow,
+                    (0, kysely_1.expressionBuilder)().and([
+                        permissiveEbs,
+                        (0, kysely_1.expressionBuilder)().and(grantsWithRestrictiveWheres.map((grant) => grant.where((0, kysely_1.expressionBuilder)()))),
+                    ]),
+                ];
+            }
+            else {
+                return [kyselyAccessControl_1.Allow, permissiveEbs];
+            }
+        },
+        column: (table, column, statementType, columnUsageContext) => {
+            const allowGrant = grants.find((grant) => {
+                var _a;
+                const rightSchemaAndTableAndColumns = (grant.schema === undefined || grant.schema === ((_a = table.schema) === null || _a === void 0 ? void 0 : _a.name)) &&
+                    grant.table === table.identifier.name &&
+                    (grant.columns === undefined ||
+                        (Array.isArray(grant.columns) &&
+                            // TODO - retype this when column node is typed
+                            grant.columns.includes(column.name)));
+                if (!rightSchemaAndTableAndColumns) {
+                    return false;
+                }
+                if (grant.for === "all") {
+                    return true;
+                }
+                if (grant.for === kyselyAccessControl_1.StatementType.Select &&
+                    [
+                        kyselyAccessControl_1.ColumnUsageContext.ColumnInSelectOrReturning,
+                        kyselyAccessControl_1.ColumnUsageContext.ColumnInWhereOrJoin,
+                    ].includes(columnUsageContext)) {
+                    return true;
+                }
+                if (grant.for === kyselyAccessControl_1.StatementType.Update &&
+                    kyselyAccessControl_1.ColumnUsageContext.ColumnInUpdateSet === columnUsageContext) {
+                    return true;
+                }
+                if (grant.for === kyselyAccessControl_1.StatementType.Insert &&
+                    kyselyAccessControl_1.ColumnUsageContext.ColumnInInsert === columnUsageContext) {
+                    return true;
+                }
+                return false;
+            });
+            if (!allowGrant) {
+                return kyselyAccessControl_1.Deny;
+            }
+            return kyselyAccessControl_1.Allow;
+        },
+    };
+    return guard;
+};
+exports.createKyselyGrantGuard = createKyselyGrantGuard;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sladkoff/kysely-access-control",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "index.ts",
+  "version": "0.0.6",
+  "scripts": {
+    "compile": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.2.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0",
+    "kysely": "^0.26.3"
+  },
+  "dependencies": {
+    "tiny-invariant": "^1.3.1"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:ben-pr-p/kysely-access-control.git"
+  },
+  "author": "Ben Packer <ben.paul.ryan.packer@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ben-pr-p/kysely-access-control/issues"
+  },
+  "homepage": "https://github.com/ben-pr-p/kysely-access-control"
+}