A module for implementing role-based access control with Prisma when using Postgres
English: from Middle English yates ‘gates’ plural of yate Old English geat ‘gate’ hence a topographic or occupational name for someone who lived by the gates of a town or castle and who probably acted as the gatekeeper or porter.
Yates is a module for implementing role-based access control with Prisma. It is designed to be used with the Prisma Client and PostgreSQL. It uses PostgreSQL's Row Level Security feature to provide a simple and secure way to implement role-based access control. This feature allows you to define complex access control rules and have them apply to all of your Prisma queries automatically.
Yates requires the prisma package at version 4.9.0 or greater and the @prisma/client package at version 4.0.0 or greater. Additionally, it uses Prisma Client extensions to generate rules and add RLS checking (which require a preview feature flag until Prisma 4.16.0, so you might need to enable this feature in your Prisma schema):
generator client {
provider = "prisma-client-js"
// previewFeatures = ["clientExtensions"] // uncomment when using Prisma before 4.16.0
}npm i @cerebruminc/yatesOnce you've installed Yates, you can use it in your Prisma project by importing it and calling the setup function. This function takes a Prisma Client instance and a configuration object as arguments and returns a client that can intercept all queries and apply the appropriate row-level security policies to them.
Yates uses Prisma Client Extensions to generate the RLS rules and add the RLS checking to the Prisma Client queries. This means that you can use the Prisma Client as you normally would, and Yates will automatically apply the appropriate RLS policies to each query. It also means that you will need to apply your Prisma Client middleware before creating the Yates client, as middleware cannot be applied to an extended client.
Client extensions share the same API as the Prisma Client, you can use the Yates client as a drop-in replacement for the Prisma Client in your application. They also share the same connection pool as the base client, which means that you can freely create new Yates clients with minimal performance impact.
The setup function will generate CRUD abilities for each model in your Prisma schema, as well as any additional abilities that you have defined in your configuration. It will then create a new PG role for each ability and apply the appropriate row-level security policies to each role. Finally, it will create a new PG role for each user role you specify and grant them the appropriate abilities.
For Yates to be able to set the correct user role for each request, you must pass a function called getContext in the setup configuration that will return the user role for the current request. This function will be called for each request and the user role returned will be used to set the role in the current session. If you want to bypass RLS completely for a specific role, you can return null from the getContext function for that role.
For accessing the context of a Prisma query, we recommend using a package like cls-hooked to store the context in the current session.
import { setup } from "@cerebruminc/yates";
import { PrismaClient } from "@prisma/client";
const prisma = new PrismaClient();
const client = await setup({
prisma,
// Define any custom abilities that you want to add to the system.
customAbilities: () => ({
USER: {
Post: {
insertOwnPost: {
description: "Insert own post",
// You can express the rule as a Prisma `where` clause.
expression: (client, row, context) => {
return {
// This expression uses a context setting returned by the getContext function
authorId: context('user.id')
}
},
operation: "INSERT",
},
},
Comment: {
deleteOnOwnPost: {
description: "Delete comment on own post",
// You can also express the rule as a conventional Prisma query.
expression: (client, row, context) => {
return client.post.findFirst({
where: {
id: row('postId'),
authorId: context('user.id')
}
})
},
operation: "DELETE",
},
},
User: {
updateOwnUser: {
description: "Update own user",
// For low-level control you can also write expressions as a raw SQL string.
expression: `current_setting('user.id') = "id"`,
operation: "UPDATE",
},
}
}
}),
// Return a mapping of user roles and abilities.
// This function is paramaterised with a list of all CRUD abilities that have been
// automatically generated by Yates, as well as any customAbilities that have been defined.
getRoles: (abilities) => {
return {
SUPER_ADMIN: "*",
USER: [
abilities.User.read,
abilities.Comment.read
],
};
},
getContext: () => {
// Here we are using cls-hooked to access the context in the current session.
const ctx = clsSession.get("ctx");
if (!ctx) {
return null;
}
const { user } = ctx;
const role = user.role
return {
role,
context: {
// This context setting will be available in ability expressions using `current_setting('user.id')`
'user.id': user.id,
},
};
},
options: {
// The maximum amount of time Yates will wait to acquire a transaction from the database. The default value is 30 seconds.
txMaxWait: 5000,
// The maximum amount of time the Yates query transaction can run before being canceled and rolled back. The default value is 30 seconds.
txTimeout: 10000,
}
});When defining an ability you need to provide the following properties:
description: A description of the ability.expression: A boolean SQL expression that will be used to filter the results of the query. This expression can use any of the columns in the table that the ability is being applied to, as well as any context settings that have been defined in thegetContextfunction.- For
INSERT,UPDATEandDELETEoperations, the expression uses the values from the row being inserted. If the expression returnsfalsefor a row, that row will not be inserted, updated or deleted. - For
SELECToperations, the expression uses the values from the row being returned. If the expression returnsfalsefor a row, that row will not be returned.
- For
operation: The operation that the ability is being applied to. This can be one ofCREATE,READ,UPDATEorDELETE.
To run Yates in debug mode, use the environment variable DEBUG=yates.
Yates uses a transaction to apply the RLS policies to each query. This means that if you are using transactions in your application, rollbacks will not work as expected. This is because Prisma has poor support for nested transactions and will COMMIT the inner transaction even if the outer transaction is rolled back.
If you need this functionality and you are using Yates, you can return null from the getContext() setup method to bypass the internal transaction, and therefore the RLS policies for the current request. See the nested-transactions.spec.ts test case for an example of how to do this.
If you are using the Prisma Client to construct an ability expression, the following where keywords are not supported.
ANDORNOTisisNot
Additionally, using context or row values to query Prisma Enums is not supported.
If you need to use these expressions, you can use the expression property of the ability to write a raw SQL expression instead.
The project is licensed under the MIT license.
