CASL Prisma

This package allows to define CASL permissions on Prisma models using Prisma WhereInput. And that brings a lot of power in terms of permission management in SQL world:

1. We can use Prisma Query to define permissions, no need to learn MongoDB query language anymore.
2. Additionally, we can ask our SQL database questions like: "Which records can be read?" or "Which records can be updated?".

Installation

npm install @casl/prisma @casl/ability
# or
yarn add @casl/prisma @casl/ability
# or
pnpm add @casl/prisma @casl/ability

@casl/prisma requires Prisma Client 4.16.0 or later. Prisma Client extensions are used by the createCaslExtension helper which is important to add to Prisma Client!

Usage

This package is a bit different from all others because it provides a custom createPrismaAbility factory function that is configured to check permissions using Prisma WhereInput:

import { User, Post, Prisma } from '@prisma/client';
import { Ability, AbilityBuilder, subject, type ForcedSubject, type TaggedSubject } from '@casl/ability';
import { createPrismaAbility, PrismaQuery } from '@casl/prisma';

type AppSubjects =
  | User & ForcedSubject<'User'>
  | Post & ForcedSubject<'Post'>
type AppAbility = Ability<[string, AppSubjects], PrismaQuery, TaggedSubject>;
const { can, cannot, build } = new AbilityBuilder<AppAbility>(createPrismaAbility);

can('read', 'Post', { authorId: 1 });
cannot('read', 'Post', { title: { startsWith: '[WIP]:' } });

const ability = build();
ability.can('read', 'Post');
ability.can('read', subject('Post', { title: '...', authorId: 1 })));

See CASL guide to learn how to define abilities. Everything is the same except of conditions language.

If you generate Prisma Client with the Prisma 7 prisma-client generator, import model types from your generated client path (for example ./prisma/generated/client) and create a small wrapper around @casl/prisma/runtime as shown below.

Note on subject helper

ForcedSubject<'Post'> declares the tag on an object. When your subject union contains only tagged object types, you must specify TaggedSubject as the third generic parameter of Ability or PrismaAbility to also accept subject names such as 'Post' in permission checks:

type AppAbility = Ability<[string, AppSubjects], PrismaQuery, TaggedSubject>;

TaggedSubject uses __caslSubjectType__ by default, matching the subject helper. If you omit the third generic parameter, DefaultSubject preserves the existing behavior: include both the names and the tagged object types explicitly, for example Ability<[string, 'User' | 'Post' | AppSubjects], PrismaQuery>.

Because Prisma returns DTO objects without exposing any type information on it, we need to use subject helper to provide that type manually, so CASL can understand what rules to apply to passed in object.

Unfortunately, there is no easy way to automate this, except of adding additional column to all models. For more details, check this issue.

To get more details about object type detection, please read CASL Subject type detection

Note on Prisma Query runtime interpreter

@casl/prisma uses ucast to interpret Prisma WhereInput in JavaScript runtime. However, there are few caveats:

• equality of JSON columns is not implemented
• equality of array/list columns is not implemented (however operators like has, hasSome and hasEvery should be more than enough)
• when defining conditions on relation, always specify one of operators (every, none, some, is or isNot)

Interpreter throws a ParsingQueryError in cases it receives invalid parameters for query operators or if some operation is not supported.

Prisma 7 configuration

Prisma 7 moves connection details into prisma.config.ts and no longer loads .env files automatically. Add a config next to your schema so prisma generate keeps working:

// prisma.config.ts
import 'dotenv/config';
import { defineConfig } from 'prisma/config';

export default defineConfig({
  schema: './schema.prisma',
  datasource: {
    // fall back to a local URL so generate does not fail in CI
    url: process.env.DATABASE_URL ?? 'postgresql://postgres:postgres@localhost:5432/postgres',
  },
});

If you stay on the legacy prisma-client-js generator, the default @prisma/client import keeps working.

Finding Accessible Records

One nice feature of Prisma and CASL integration is that we can get all records from the database our user has access to. To do this, just use accessibleBy helper function:

// ability is a PrismaAbility instance created in the example above

const accessiblePosts = await prisma.post.findMany({
  where: accessibleBy(ability).ofType('Post')
});

That function accepts Ability instance and action (defaults to read), returns an instance of AccessibleRecords with an ofType method which accepts Prisma model name and returns an object aggregated from permission rules WhereInput.

Important: in case user doesn't have ability to access any posts, .ofType returns a special empty condition. If you pass it directly to Prisma Client without createCaslExtension, Prisma rejects the query because the condition contains an internal marker field. This makes denied access fail closed.

To combine this with business logic conditions, just use AND:

const accessiblePosts = await prisma.post.findMany({
  where: {
    AND: [
      accessibleBy(ability).ofType('Post'),
      { /* business related conditions */ }
    ]
  }
})

For the current Prisma extension implementation, putting accessibleBy(...) first in compound conditions such as AND: [...] allows empty-condition detection to short-circuit sooner.

Prisma Client extension

createCaslExtension addresses this issue by letting Prisma Client handle CASL's empty conditions as empty query results instead of throwing forbidden error.

Important: make sure to add this extension to the Prisma Client instance you use for CASL-protected queries. Otherwise, some CASL restrictions may not be applied correctly.

Add it as any other regular extension:

import { PrismaClient } from '@prisma/client';
import { createCaslExtension } from '@casl/prisma';

const prisma = new PrismaClient().$extends(createCaslExtension());

With this extension, operations with an empty CASL condition return the same kind of "no records" result Prisma users usually expect:

const posts = await prisma.post.findMany({
  where: accessibleBy(ability).ofType('Post')
});
// posts === []

Single-record operations that require a matching record, such as findFirstOrThrow, findUniqueOrThrow, update, and delete, will reject with a "No record was found for an ..." error.

TypeScript support

The package is written in TypeScript what provides comprehensive IDE hints and compile time validation.

Makes sure to call prisma generate. @casl/prisma uses Prisma generated types, so if client is not generated nothing will work.

Additionally, there are several helpers that makes it easy to work with Prisma and CASL:

PrismaQuery

It's a generic type that provides Prisma.ModelWhereInput in generic way. We need to pass inside a named model:

import type { User } from '@prisma/client';
import type { ForcedSubject } from '@casl/ability';
import type { PrismaQuery } from '@casl/prisma';

// almost the same as Prisma.UserWhereInput except that it's a higher order type
type UserWhereInput = PrismaQuery<User & ForcedSubject<'User'>>;

Custom PrismaClient output path (Prisma 7 default)

Prisma 7's prisma-client generator writes the client into a custom directory, so @prisma/client no longer re-exports your project types. Point CASL at the generated client with a small wrapper built on @casl/prisma/runtime:

// schema.prisma
generator client {
  provider = "prisma-client"
  output   = "../src/generated/client"
}

// prisma.config.ts
import { defineConfig } from 'prisma/config';

export default defineConfig({
  schema: './schema.prisma',
  datasource: { url: process.env.DATABASE_URL! },
});

// src/casl-prisma.ts
import {
  accessibleBy,
  createPrismaAbility,
  ParsingQueryError,
  prismaQuery,
  type PrismaQueryOf,
  type WhereInputOf,
} from '@casl/prisma/runtime';
import type { Ability, ForcedSubject, TaggedSubject } from "@casl/ability";
import type { Prisma, Post, User } from './generated/client';

export { accessibleBy, createPrismaAbility, ParsingQueryError, prismaQuery };

export type PrismaQuery<T extends ForcedSubject<any> = ForcedSubject<any>> =
  PrismaQueryOf<Prisma.TypeMap, T>;
export type WhereInput<TModelName extends Prisma.ModelName> =
  WhereInputOf<Prisma.TypeMap, TModelName>;
export type AppSubjects =
  | User & ForcedSubject<'User'>
  | Post & ForcedSubject<'Post'>
;

export type AppAbility = Ability<['create' | "read" | "update" | "delete", 'all' | AppSubjects], PrismaQuery, TaggedSubject>

Use this wrapper in your app instead of importing from @casl/prisma directly. If you stay on the legacy prisma-client-js generator for Prisma 6.x compatibility, the default @casl/prisma entrypoint keeps working.

Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on guidelines for contributing.

If you'd like to help us sustain our community and project, consider to become a financial contributor on Open Collective

See Support CASL for details

License

MIT License