@btravstack/prisma 0.12.0 → 0.13.0

package/README.md

@@ -15,7 +15,9 @@ pnpm add @btravstack/prisma @btravstack/core @btravstack/config @btravstack/di u
 Five peer dependencies — install every one, so the application holds a single
 copy of each. Your own `@prisma/client`, `prisma` and (if you want the `try*`
 twins) `@unthrown/prisma` are yours, not this package's: the client is
-generated from your schema. Node `>=22`.
+generated from your schema. `@prisma/client` is also an **optional** peer here,
+used only by the `@btravstack/prisma/rls` subpath below — a consumer that never
+imports it installs nothing extra. Node `>=22`.
 
 ## A worked example
 
@@ -85,14 +87,71 @@ port is typed by exactly what it returns.
   the failures as lines and `otel()` mints the instruments — with no flag here
   and no port list to satisfy when you compose neither.
 
+## Row-level security, on the `@btravstack/prisma/rls` subpath
+
+`tenantScoped(tenant)` is a Prisma client extension that pins **every** statement
+— raw SQL included — to `tenant` through a transaction-local
+`set_config('app.tenant_id', tenant, true)`, so a PostgreSQL row-level-security
+policy reading `current_setting('app.tenant_id', true)` sees it. Apply it
+**last**:
+
+<!-- doctest: isolate
+// `PrismaClient` and `unthrownPrisma` are the reader's own, exactly as in the
+// worked example above — so what this fence holds is `tenantScoped`'s call
+// shape and its place in the chain, not the generated client's `$extends`.
+// That half is compiled on the reference page, over the real client.
+import { PrismaPg } from "@prisma/adapter-pg";
+
+declare class PrismaClient {
+  constructor(options: { readonly adapter: PrismaPg });
+  $extends(extension: unknown): this;
+}
+declare const adapter: PrismaPg;
+declare const unthrownPrisma: unknown;
+declare const tenant: string;
+-->
+
+```ts
+import { tenantScoped } from "@btravstack/prisma/rls";
+
+const db = new PrismaClient({ adapter }).$extends(unthrownPrisma).$extends(tenantScoped(tenant));
+```
+
+That fence compiles `tenantScoped`'s call shape and its place in the chain over
+a client declared for the sample; the fence on the
+[reference page](https://btravstack.github.io/btravstack/reference/prisma) is
+the one compiled over a real generated client, which is what proves the
+extension is assignable to its `$extends`.
+
+It goes last because a transaction callback's `tx` comes from the client as it
+stood when this extension was applied, so anything added after it is invisible
+inside a transaction. `$transaction([...])` is refused rather than silently pinned: the
+batch form stops being atomic under this design, and a rejected promise beats a
+transaction that quietly no longer rolls back. Use the callback form.
+
+The database half stays the deployment's, and every part of it fails quietly
+when forgotten: a **superuser** role bypasses row security whatever the table
+says, and a policy without `FORCE ROW LEVEL SECURITY` is not applied to the
+table's **owner** — the role that ran the migrations. Either way the
+application works and no tenant is isolated. The policy must also read the
+**same** setting `tenantScoped` was given — `app.tenant_id` is only the default
+— because a `tenantScoped(tenant, { setting })` and a policy naming a different
+one deny every row and every write, which looks exactly like row security
+working. The
+[reference page](https://btravstack.github.io/btravstack/reference/prisma)
+carries the DDL and the two smaller lines that fail the same way.
+
 ## What it does not
 
-**Migrations.** A deployment runs `prisma migrate deploy` against this same URL
-_before the process starts_. An application that migrates itself at boot races
-every other replica.
+**Migrations.** A deployment runs `prisma migrate deploy` against the same
+database _before the process starts_ — and, where row security is on, as its
+**owner** rather than the role `DATABASE_URL` carries. An application that
+migrates itself at boot races every other replica.
 
 **Transactions.** Commit boundaries belong to the adapter, spelled at the call —
-`@unthrown/prisma`'s `$tryTransaction` is the primitive. There is no unit-scoped
+`@unthrown/prisma`'s `$tryTransaction` is the primitive. The `rls` subpath
+overrides `$transaction` to pin the tenant on the connection and nothing more;
+it opens no boundary of its own. There is no unit-scoped
 transaction and there will not be one; see
 [the kernel maps nothing](https://btravstack.github.io/btravstack/explanation/the-kernel-maps-nothing).
 
@@ -106,6 +165,7 @@ package's.
 | `name`         | `prismaDatabase(name)`                      | the port's id and the health check's name — required                                     |
 | `client`       | `prismaDatabase(name)({ client })`          | builds your client from the driver adapter this package built from the URL — required    |
 | `DATABASE_URL` | environment, read by `prismaDatabase(name)` | the connection string — required, validated at graph build; blank is an error, exit `78` |
+| `setting`      | `tenantScoped(tenant, { setting })`         | the PostgreSQL run-time setting the policy reads — default `app.tenant_id`               |
 
 There is **no `instrumented` flag**: observation is a set port every call is
 handed to, so a graph composing no observability pays one inert call and no

package/dist/rls.cjs

@@ -0,0 +1,40 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _prisma_client_extension = require("@prisma/client/extension");
+//#region src/rls.ts
+/**
+* A Prisma client extension pinning every statement to `tenant` through a
+* transaction-local `set_config`, so a row-level-security policy reading
+* `current_setting('app.tenant_id', true)` sees it.
+*
+* @remarks
+* Apply it **last**: the transaction callback's `tx` comes from the client as
+* it stood when this extension was applied, so an extension added after this
+* one is invisible inside a transaction.
+*
+* `$transaction([...])` is refused — the reasoning is in
+* `packages/prisma/CLAUDE.md`. Use the callback form.
+*
+* @example
+* ```ts
+* const db = new PrismaClient({ adapter }).$extends(unthrownPrisma).$extends(tenantScoped(tenant));
+* ```
+*/
+const tenantScoped = (tenant, options) => _prisma_client_extension.Prisma.defineExtension((client) => {
+	const setting = options?.setting ?? "app.tenant_id";
+	const bare = client;
+	const pinOn = (on) => on.$executeRaw`SELECT set_config(${setting}, ${tenant}, true)`;
+	return client.$extends({
+		name: "tenantScoped",
+		client: { $transaction: ((arg, txOptions) => {
+			if (Array.isArray(arg)) return Promise.reject(/* @__PURE__ */ new Error("tenantScoped: $transaction([...]) is unsupported — use the callback form."));
+			const fn = arg;
+			return bare.$transaction(async (tx) => {
+				await pinOn(tx);
+				return fn(tx);
+			}, txOptions);
+		}) },
+		query: { $allOperations: ({ args, query }) => bare.$transaction([pinOn(bare), query(args)]).then((results) => results[1]) }
+	});
+});
+//#endregion
+exports.tenantScoped = tenantScoped;

package/dist/rls.d.cts

@@ -0,0 +1,55 @@
+//#region src/rls.d.ts
+/** Options of {@link tenantScoped}. */
+type TenantScopedOptions = {
+  /**
+   * The PostgreSQL run-time setting the policy reads. Defaults to
+   * `app.tenant_id`, matching `current_setting('app.tenant_id', true)`.
+   */
+  readonly setting?: string;
+};
+/**
+ * The client a pinned `$transaction` callback receives — the extended client
+ * minus what a transaction cannot do, exactly as Prisma's own deny list has it.
+ *
+ * @remarks
+ * Not `@unthrown/prisma`'s `TransactionClient`, which denies a longer list; an
+ * application applying both extensions imports both names.
+ */
+type ScopedTransactionClient<C> = Omit<C, "$connect" | "$disconnect" | "$extends" | "$on" | "$use">;
+/**
+ * The `$transaction` a {@link tenantScoped} client exposes: the callback form
+ * only, with `this` carrying the extended client through to `tx`.
+ *
+ * @remarks
+ * The generic `this` is what keeps `tx` typed. The starter cannot name a
+ * generated client, so the receiver is the only place that type can come from.
+ * The array form is absent because it cannot be pinned atomically.
+ */
+type ScopedTransaction = <C, R>(this: C, fn: (tx: ScopedTransactionClient<C>) => Promise<R>, options?: {
+  maxWait?: number;
+  timeout?: number;
+  isolationLevel?: string;
+}) => Promise<R>;
+/**
+ * A Prisma client extension pinning every statement to `tenant` through a
+ * transaction-local `set_config`, so a row-level-security policy reading
+ * `current_setting('app.tenant_id', true)` sees it.
+ *
+ * @remarks
+ * Apply it **last**: the transaction callback's `tx` comes from the client as
+ * it stood when this extension was applied, so an extension added after this
+ * one is invisible inside a transaction.
+ *
+ * `$transaction([...])` is refused — the reasoning is in
+ * `packages/prisma/CLAUDE.md`. Use the callback form.
+ *
+ * @example
+ * ```ts
+ * const db = new PrismaClient({ adapter }).$extends(unthrownPrisma).$extends(tenantScoped(tenant));
+ * ```
+ */
+declare const tenantScoped: (tenant: string, options?: TenantScopedOptions) => (client: any) => import("@prisma/client/extension").PrismaClientExtends<import("@prisma/client/runtime/client").InternalArgs<{}, {}, {}, {
+  $transaction: ScopedTransaction;
+}> & import("@prisma/client/runtime/client").DefaultArgs>;
+//#endregion
+export { ScopedTransaction, ScopedTransactionClient, TenantScopedOptions, tenantScoped };

package/dist/rls.d.mts

@@ -0,0 +1,55 @@
+//#region src/rls.d.ts
+/** Options of {@link tenantScoped}. */
+type TenantScopedOptions = {
+  /**
+   * The PostgreSQL run-time setting the policy reads. Defaults to
+   * `app.tenant_id`, matching `current_setting('app.tenant_id', true)`.
+   */
+  readonly setting?: string;
+};
+/**
+ * The client a pinned `$transaction` callback receives — the extended client
+ * minus what a transaction cannot do, exactly as Prisma's own deny list has it.
+ *
+ * @remarks
+ * Not `@unthrown/prisma`'s `TransactionClient`, which denies a longer list; an
+ * application applying both extensions imports both names.
+ */
+type ScopedTransactionClient<C> = Omit<C, "$connect" | "$disconnect" | "$extends" | "$on" | "$use">;
+/**
+ * The `$transaction` a {@link tenantScoped} client exposes: the callback form
+ * only, with `this` carrying the extended client through to `tx`.
+ *
+ * @remarks
+ * The generic `this` is what keeps `tx` typed. The starter cannot name a
+ * generated client, so the receiver is the only place that type can come from.
+ * The array form is absent because it cannot be pinned atomically.
+ */
+type ScopedTransaction = <C, R>(this: C, fn: (tx: ScopedTransactionClient<C>) => Promise<R>, options?: {
+  maxWait?: number;
+  timeout?: number;
+  isolationLevel?: string;
+}) => Promise<R>;
+/**
+ * A Prisma client extension pinning every statement to `tenant` through a
+ * transaction-local `set_config`, so a row-level-security policy reading
+ * `current_setting('app.tenant_id', true)` sees it.
+ *
+ * @remarks
+ * Apply it **last**: the transaction callback's `tx` comes from the client as
+ * it stood when this extension was applied, so an extension added after this
+ * one is invisible inside a transaction.
+ *
+ * `$transaction([...])` is refused — the reasoning is in
+ * `packages/prisma/CLAUDE.md`. Use the callback form.
+ *
+ * @example
+ * ```ts
+ * const db = new PrismaClient({ adapter }).$extends(unthrownPrisma).$extends(tenantScoped(tenant));
+ * ```
+ */
+declare const tenantScoped: (tenant: string, options?: TenantScopedOptions) => (client: any) => import("@prisma/client/extension").PrismaClientExtends<import("@prisma/client/runtime/client").InternalArgs<{}, {}, {}, {
+  $transaction: ScopedTransaction;
+}> & import("@prisma/client/runtime/client").DefaultArgs>;
+//#endregion
+export { ScopedTransaction, ScopedTransactionClient, TenantScopedOptions, tenantScoped };

package/dist/rls.mjs

@@ -0,0 +1,39 @@
+import { Prisma } from "@prisma/client/extension";
+//#region src/rls.ts
+/**
+* A Prisma client extension pinning every statement to `tenant` through a
+* transaction-local `set_config`, so a row-level-security policy reading
+* `current_setting('app.tenant_id', true)` sees it.
+*
+* @remarks
+* Apply it **last**: the transaction callback's `tx` comes from the client as
+* it stood when this extension was applied, so an extension added after this
+* one is invisible inside a transaction.
+*
+* `$transaction([...])` is refused — the reasoning is in
+* `packages/prisma/CLAUDE.md`. Use the callback form.
+*
+* @example
+* ```ts
+* const db = new PrismaClient({ adapter }).$extends(unthrownPrisma).$extends(tenantScoped(tenant));
+* ```
+*/
+const tenantScoped = (tenant, options) => Prisma.defineExtension((client) => {
+	const setting = options?.setting ?? "app.tenant_id";
+	const bare = client;
+	const pinOn = (on) => on.$executeRaw`SELECT set_config(${setting}, ${tenant}, true)`;
+	return client.$extends({
+		name: "tenantScoped",
+		client: { $transaction: ((arg, txOptions) => {
+			if (Array.isArray(arg)) return Promise.reject(/* @__PURE__ */ new Error("tenantScoped: $transaction([...]) is unsupported — use the callback form."));
+			const fn = arg;
+			return bare.$transaction(async (tx) => {
+				await pinOn(tx);
+				return fn(tx);
+			}, txOptions);
+		}) },
+		query: { $allOperations: ({ args, query }) => bare.$transaction([pinOn(bare), query(args)]).then((results) => results[1]) }
+	});
+});
+//#endregion
+export { tenantScoped };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/prisma",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The Prisma starter for @btravstack/core: DATABASE_URL through Config, the Postgres driver adapter, and a client whose pool is the application scope's",
   "keywords": [
     "database",
@@ -40,11 +40,22 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./rls": {
+      "import": {
+        "types": "./dist/rls.d.mts",
+        "default": "./dist/rls.mjs"
+      },
+      "require": {
+        "types": "./dist/rls.d.cts",
+        "default": "./dist/rls.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/tsconfig": "0.2.0",
+    "@btravstack/tsconfig": "0.4.0",
     "@prisma/adapter-pg": "7.10.0",
+    "@prisma/client": "7.10.0",
     "@prisma/instrumentation": "7.10.0",
     "@types/node": "26.4.0",
     "@unthrown/vitest": "5.7.0",
@@ -53,19 +64,23 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.12.0",
-    "@btravstack/core": "0.12.0",
-    "@btravstack/di": "0.12.0"
+    "@btravstack/config": "0.13.0",
+    "@btravstack/core": "0.13.0",
+    "@btravstack/di": "0.13.0"
   },
   "peerDependencies": {
     "@prisma/adapter-pg": "^7.0.0",
+    "@prisma/client": "^7.10.0",
     "@prisma/instrumentation": "^7.0.0",
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.12.0",
-    "@btravstack/core": "^0.12.0",
-    "@btravstack/di": "^0.12.0"
+    "@btravstack/config": "^0.13.0",
+    "@btravstack/core": "^0.13.0",
+    "@btravstack/di": "^0.13.0"
   },
   "peerDependenciesMeta": {
+    "@prisma/client": {
+      "optional": true
+    },
     "@prisma/instrumentation": {
       "optional": true
     }
@@ -74,8 +89,8 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsdown src/index.ts src/rls.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts src/rls.ts --format cjs,esm --dts --watch",
     "test": "vitest run --coverage",
     "test:types": "tsc -p tsconfig.test-d.json --noEmit",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"