@prisma/security-rules 0.3.6 → 0.4.0

package/README.md

@@ -4,10 +4,10 @@
 
 Prisma Security Rules is a **permission rules system for Prisma ORM and Prisma Postgres**. With Security Rules, you can:
 
-- define access permission rules in TypeScript
-- deploy the permission rules to your Prisma Postgres instance
-- query Prisma Postgres with the permission rules applied
-- access Prisma Postgres from the frontend
+- Define access permission rules in TypeScript
+- Deploy the permission rules to your Prisma Postgres instance
+- Query Prisma Postgres with the permission rules applied
+- Access Prisma Postgres from the frontend
 
 At the core of it, you define rules that allow/deny requests to your database based on model name, operation (e.g. `findMany`) and the parameters you pass to said operation.
 
@@ -15,11 +15,11 @@ At the core of it, you define rules that allow/deny requests to your database ba
 
 ### Prerequisites
 
-- A project with Prisma ORM (>=6.2.0) installed and a Prisma Postgres database. If you don’t have one, you can get started [here](https://www.prisma.io/docs/getting-started/prisma-postgres/from-the-cli?utm_source=readme&utm_medium=rules_extension).
+- A project with Prisma ORM (>=6.2.0) installed and a Prisma Postgres database. If you don’t have one, you can get started [here](https://www.prisma.io/docs/getting-started/prisma-postgres/from-the-cli?utm_source=readme&utm_medium=security_rules).
 
-- The Prisma CLI being authenticated with Prisma Data Platform (via [`prisma platform auth login --early-access`](https://www.prisma.io/docs/platform/platform-cli/commands?utm_source=readme&utm_medium=rules_extension#auth-login)).
+- The Prisma CLI being authenticated with Prisma Data Platform (via [`prisma platform auth login --early-access`](https://www.prisma.io/docs/platform/platform-cli/commands?utm_source=readme&utm_medium=security_rules#auth-login)).
 
-### 1. Install the Prisma Client extension for Policy
+### 1. Install the Security Rules package
 
 ```shell
 npm install @prisma/security-rules
@@ -50,74 +50,67 @@ bun install @prisma/security-rules
 
 </details>
 
-### 2. Extend your `PrismaClient` with the Policy extension
+### 2. Define your Security Rules
 
-First, import the extension and add it to your existing Prisma Client:
+First, import the package and define your rules. Create a `rules.ts`in your `prisma` folder:
 
 ```ts
 import { PrismaClient } from "@prisma/client";
-import { withPolicy } from "@prisma/security-rules";
+import { defineRules } from "@prisma/security-rules";
 import { z } from "zod";
 
 import { decode } from "path/to/decode"; // imaginary import of your jwt token decode helper
 
-export const prisma = new PrismaClient().$extends(
-  withPolicy({
-    contextSchema: z.object({
-      token: z.string(),
-    }),
-    rules: {
-      user: {
-        async read(req) {
-          // On each request, the context object can be used to perform custom auth/access business logic. We know it's shape thanks to the `contextSchema` property.
-          const { userId } = await decode(req.context.token);
-
-          return {
-            $where: { id: userId },
-          };
-        },
-        $allOperations: false,
+export default defineRules({
+  prisma: new PrismaClient(),
+  contextSchema: z.object({
+    token: z.string(),
+  }),
+  rules: {
+    user: {
+      async read(req) {
+        // On each request, the context object can be used to perform custom auth/access business logic. We know it's shape thanks to the `contextSchema` property.
+        const { userId } = await decode(req.context.token);
+
+        return {
+          $where: { id: userId },
+        };
       },
-      $allModels: false,
-      $transaction: false,
+      $allOperations: false,
     },
-  }),
-);
+    $allModels: false,
+    $transaction: false,
+  },
+});
 ```
 
 > Note: While the rules are applied to your `PrismaClient` instance, this instance will retain _full_ database access.
 
 This example uses `zod`, but you can use any schema library that implements the [standard schema](https://github.com/standard-schema/standard-schema#what-schema-libraries-implement-the-spec) specification.
 
-This example includes Policy rules that will deny all requests except for reads (e.g. `findMany`) on `user` model. It also ensures a user only sees their own data by applying a `where` override (effectively `AND(incoming_query_where, rule_$where)`) that filters by the user's id (decoded from the session token).
-
-### 3. Create a file exporting the `PolicyClient` for your application
+This example includes rules that will deny all requests except for reads (e.g. `findMany`) on `user` model. It also ensures a user only sees their own data by applying a `where` override (effectively `AND(incoming_query_where, rule_$where)`) that filters by the user's id (decoded from the session token).
 
-```ts
-import { PolicyClient } from "@prisma/security-rules";
-
-// it is very important to not forget the `type` annotation here, to tell TypeScript to only import the types!!!
-import type { prisma as rpcClient } from "path/to/file/where/rules/are/used";
-
-export const prisma = new PolicyClient<typeof rpcClient>({
-  publicKey: "<TBD>",
-});
-```
-
-### 4. Deploy Policy rules
+### 3. Deploy your Security Rules
 
 ```shell
-prisma rules deploy <rules_name> -f path/to/file/where/rules/are/used
+prisma rules deploy <rules_name> -f ./prisma/rules.ts
 ```
 
-Be sure to copy the public key from the deploy command's output in your terminal, and replace the `<TBD>` from the previous step.
+Be sure to copy the public key from the deploy command's output in your terminal, and replace the `<public_key>` below.
 
-### 5. Use `PolicyClient` to access Prisma Postgres
+### 4. Use `AuthorizedClient` to access Prisma Postgres
 
-`PolicyClient` is a lightweight version of `PrismaClient` that you can use in your browser. Once your rules are deployed, you can use it as follows in your application:
+`AuthorizedClient` is a lightweight version of `PrismaClient` that you can use in your browser. Once your rules are deployed, you can use it as follows in your application:
 
 ```ts
-import { prisma } from "path/to/rules-client";
+import { AuthorizedClient } from "@prisma/security-rules";
+
+// It is important not to forget the `type` annotation here.
+import type rules from "path/to/prisma/rules";
+
+const authorizedClient = new AuthorizedClient<typeof rules>({
+  publicKey: "<public_key>",
+});
 
 prisma.setGlobalContext({ token: "<some_session_token>" });
 
@@ -128,23 +121,20 @@ const users = await prisma.users.findMany();
 
 This package exposes:
 
-- A [Prisma Client extension](https://www.prisma.io/docs/orm/prisma-client/client-extensions) called `withPolicy` that helps attach Prisma Policy-related configuration to an existing Prisma ORM client, making it suitable to act as a Remote Procedure Call (RPC) called object once bundled and deployed to Prisma Policy's workers.
-
-- A lightweight Remote Procedure Call (RPC) stub called `PolicyClient` that allows your application to execute Prisma ORM queries and transactions remotely on Prisma Policy's workers in a secure way (based on your Policy configuration).
+- A `defineRules` helper to attach Prisma Security Rules to an existing Prisma ORM client, which gets deployed at the edge when you run `prisma rules deploy`.
 
-The deployment logic is not part of this package, and is accessible via the Prisma CLI through `prisma rules`. A deployment's output will include a public key you'll need to pass to `PolicyClient`.
+- An `AuthorizedClient` class that is a drop-in replacement for `PrismaClient`, a lightweight client that will enforce the rules you've defined and deployed.
 
-Here's a simplified high-level view of Policy's architecture:
+Here's a simplified high-level view of Prisma Security Rule's architecture:
 
-![Prisma Policy's RPC in excalidraw](https://www.unpkg.com/@prisma/security-rules@latest/assets/rpc.png)
+![Prisma Security Rules RPC](https://www.unpkg.com/@prisma/security-rules@latest/assets/rpc.png)
 
 ### Rule Engine
 
-Each request, that is received by Policy's workers, will be evaluated by a rule engine:
-
-- if a request does not adhere to your rules, it will be denied with a reason, and the `PolicyClient` will throw an error.
+Each request, that is received by Prisma Security Rules' workers, will be evaluated by a rule engine:
 
-- if a request adheres to your rules, it will be executed with the `PrismaClient` and the results will be sent to the `PolicyClient`.
+- If a request does not adhere to your rules, it will be denied with a reason, and the `AuthorizedClient` will throw an error.
+- If a request adheres to your rules, it will be executed with the `PrismaClient` and the results will be sent to the `AuthorizedClient`.
 
 #### Rules
 
@@ -193,7 +183,7 @@ type ModelRules =
 
 Operation rules are best described by the following diagram:
 
-![Prisma Policy's operation rules "onion"](https://www.unpkg.com/@prisma/security-rules@latest/assets/operation-rules.png)
+![Prisma Security Rules operation "onion"](https://www.unpkg.com/@prisma/security-rules@latest/assets/operation-rules.png)
 
 It's like an 🧅.
 
@@ -213,10 +203,10 @@ The callback's `req` argument is an object that includes the model name, operati
 
 Here's a diagram depicting the rule engine's evaluation process in a simplified manner:
 
-![Prisma Policy's rule engine algorithm](https://www.unpkg.com/@prisma/security-rules@latest/assets/rule-engine.png)
+![Prisma Security Rules engine algorithm](https://www.unpkg.com/@prisma/security-rules@latest/assets/rule-engine.png)
 
 The rule engine is designed to introduce as little overhead as possible. As soon as a rule is not adhered by some check, the request is denied. Meaning, it doesn't try and run additional checks to collect more deny reasons.
 
 ## Need help?
 
-If you need assistance, reach out in the #help-and-questions channel on our [Discord](https://pris.ly/discord), or connect with our community to see how others are using Policy.
+If you need assistance, reach out in the #help-and-questions channel on our [Discord](https://pris.ly/discord), or connect with our community to see how others are using Prisma Security Rules.