@rowstile/client 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,81 @@
+# rowstile for TypeScript
+
+The SDK for TypeScript apps on a rowstile policy: every transaction signs in as whoever the request
+or the job acts for, refused writes become a 403 with the database's reason, rows the user can't see a 404,
+signed-in reads stay out of Next.js's caches, and the app refuses to start on a connection that skips
+row-level security. It holds no rowstile logic: it calls the `authz.*` functions the policy made, and
+translates their answers.
+
+Next.js with Prisma:
+
+```ts
+// src/db.ts
+import { PrismaPg } from "@prisma/adapter-pg";
+import { authz, signedIn } from "@rowstile/prisma";
+import "@rowstile/next";                         // signed-in reads never land in a cache
+import "./authz.gen";                            // the policy's names (rowstile client)
+
+const adapter = signedIn(new PrismaPg({ connectionString: process.env.DATABASE_URL }),
+                         { user: async () => (await auth())?.user.id });
+export const db = new PrismaClient({ adapter }).$extends(authz());
+```
+
+```ts
+// app/api/folders/[id]/route.ts: no checks; a hidden folder is 404, one the user may not rename 403
+export const PATCH = route(async (req: Request, { params }: { params: Promise<{ id: string }> }) => {
+  await db.folder.update({ where: { id: Number((await params).id) }, data: await req.json() });
+  return Response.json({ ok: true });
+});
+```
+
+| package | what |
+|---|---|
+| `@rowstile/client` | `actingAs(who, fn)`, `job(who, fn)`, `current()`, `Refused`, `NotFound`, `NotSignedIn`, `translate(e)` and `problemResponse(e)` for any driver's error, `errorCode(e)` (rowstile's code: `AZ709`), `calls(queryable)` (the runtime's functions), the `Register` the generated names fill in |
+| `@rowstile/prisma` | `signedIn(adapter, { user })`: every transaction Prisma begins signs in; `authz()`: P2025 as `NotFound` or `Refused` with the reason, refused creates naming the rule, `db.$authz` (`can`, `ids`, `permsOf`, `share`, `check`, ...) |
+| `@rowstile/pg` | `authz(pool, { user })`: `transaction(fn)`, `query()`, the runtime's functions; `changes(pool)` for live updates |
+| `@rowstile/postgres` | `authz(sql, { user })`: `begin(fn)`, the runtime's functions |
+| `@rowstile/drizzle` | `withAuthz(db, { user })`: `transaction(fn)`; `inIds(column, type, perm)` and `ids()` for `where`; `expect(tx, result, ...)` for updates and deletes that changed nothing |
+| `@rowstile/next` | `route(handler)` (403 and 404 problem bodies), `action(fn)` (`{ ok, value }` or `{ ok: false, problem }`), `authzRoutes()` (what the React kit calls), `checkAtStart()` for `instrumentation.ts`; importing it keeps signed-in reads out of caches |
+| `@rowstile/react` | `<AuthzProvider>`, `usePerms(type, ids)` (one call for a list), `<Can>`, `useShares` and a headless `<ShareDialog>`, `useAccessRequest`; kept current over server-sent events |
+| `@rowstile/vitest` | `expect.extend(matchers)`: `toBeRefused(command, reason)`, `toBeNotFound()`; `asUser(who, fn)`; `databasePerWorker(url)`. Vitest 4 or 5 |
+
+Who a transaction acts for: `42` or `"42"` (a user), `["service", 3]` (another principal type of the policy),
+or `null` (nobody: only what `anyone` may see). A plain id is always a user's, whatever it holds: `"service:3"`
+is the user with that id, so an id from outside (a username, an identity provider's subject) can't name a
+service. `parsePrincipal("service:3")` reads back what `describe()` wrote, for text your own code wrote. Whoever the code acts for (`actingAs`, a `job`)
+comes first, else the `user` function, else nobody; a `who` given to one call (`transaction(fn, who)`) comes
+before all, and `null` there is nobody. Every transaction signs in, even as nobody, and nothing uses a
+session-level `SET`, so pools and poolers in transaction mode are safe; the change feed needs its own connection
+to Postgres ([Behind a pooler](../../docs/operations.md#behind-a-pooler)).
+
+Traps it handles:
+
+- **Next.js caching.** Before a transaction signs in as someone, `@rowstile/next` calls Next's `connection()`:
+  the render is dynamic, and a signed-in read inside `"use cache"` or `unstable_cache` fails instead of being
+  cached for the next user. Reads as nobody may be cached.
+- **Prisma answers some calls together.** It dispatches the `findUnique` calls of one tick, and array
+  transactions, from the first caller's context. `authz()` runs each `findUnique` in a transaction of its own,
+  and refuses `$transaction([...])` (use `$transaction(async (tx) => ...)`), so no query runs as someone else.
+  Use the client `$extends(authz())` returns, and only that one: the client it was made from is refused
+  whenever it is used.
+- **Inserts that read the row back** (`RETURNING`, Prisma's `create`) also need the select rule: Postgres's own
+  message comes back as `Refused` naming the select rule.
+- **Prisma's promises are lazy**: `actingAs` and `job` await what they return inside their scope.
+- **A connection that drops.** node-postgres stops the process when a client that is checked out loses its
+  connection and nobody listens: `@rowstile/pg` listens while it holds one, so the transaction fails instead.
+  `changes(pool)` listens again after its connection drops, and tells its subscribers once.
+- **An update that changed nothing** is `NotFound` when the user can't see the row, `Refused` when the database
+  says no, and `NotFound` again when the rule allows it and the statement matched nothing for another reason
+  (a `where` with more than the key).
+- **The answers in the browser are one user's.** Give `<AuthzProvider user={id}>` if the user can change
+  without a page load: the hooks forget what they had and ask again.
+
+The types and permissions of the policy are generated names: with a `@rowstile/*` dependency in
+`package.json`, `rowstile client` writes only the names (`[clients] ts = "src/authz.gen.ts"`), registered with
+the SDK, so `db.$authz.can("note", 1, "edt")` doesn't type-check. Policy changes ship as migrations for your
+tool (`rowstile migrate`, with `tool = "prisma"` or `"drizzle"` in `rowstile.toml`).
+
+The packages are an npm workspace at the repository root (`npm ci`, then `npx tsc -b sdk/typescript`).
+`integrations/nextjs/` is the conformance suite: a small Next.js app on Prisma 7 and Prisma Migrate, and the
+checks every supported stack passes, with pg, postgres.js, Drizzle and the React kit
+(`integrations/nextjs/test.sh`).

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+/** Filled in by the generated file: `declare module "@rowstile/client" { interface Register { ... } }`. */
+export interface Register {
+}
+type Registered = Register extends {
+    permissions: infer P;
+} ? P : {
+    readonly [type: string]: readonly string[];
+};
+type RegisteredShared = Register extends {
+    sharedRelations: infer S;
+} ? S : {
+    readonly [type: string]: {
+        readonly [relation: string]: readonly string[];
+    };
+};
+/** A type the policy declares ("folder"). */
+export type ObjectType = Extract<keyof Registered, string>;
+/** A permission type T has ("edit"). */
+export type Permission<T extends ObjectType = ObjectType> = Registered[T] extends readonly (infer P)[] ? Extract<P, string> : string;
+/** A type with relations people may share. */
+export type SharedType = Extract<keyof RegisteredShared, string>;
+/** A relation of T people may share ("editor"). */
+export type SharedRelation<T extends SharedType = SharedType> = Extract<keyof RegisteredShared[T], string>;
+/** An object's id; for a composite key, its columns in order: [orgId, id]. */
+export type Id = string | number | bigint | readonly (string | number | bigint)[];
+/** An id as the database compares it: a composite key as Postgres writes a row (every field quoted); a key of
+ *  one column given as an array is that value. */
+export declare function idText(id: Id): string;
+/** A user (type "user"), another principal type the policy declares (a service, a bot), or nobody (id null:
+ *  only what `anyone` may see). */
+export interface Principal {
+    readonly type: string;
+    readonly id: string | null;
+}
+/** 42, "42", ["service", 3], a Principal, or null / undefined (nobody). A plain id is a user's, whatever it holds:
+ *  "service:3" is the user whose id that is (ids often come from outside: a username, an identity provider's
+ *  subject), never service 3. Another principal type is named: ["service", 3]. */
+export type Who = Principal | string | number | bigint | readonly [string, string | number | bigint | null] | null | undefined;
+export declare const NOBODY: Principal;
+export declare function principal(who: Who): Principal;
+/** What describe() wrote, read back: "service:3" is service 3, "42" user 42, "nobody" nobody. For text your own
+ *  code wrote (a job's argument, the audit trail's `by`), not for an id that came from outside. */
+export declare function parsePrincipal(text: string): Principal;
+/** "42", "service:3" or "nobody". */
+export declare function describe(p: Principal): string;
+/** Who the code running now acts for (set by actingAs, a job, or a web integration), or undefined if unset. */
+export declare function current(): Principal | undefined;
+/** Runs fn acting for `who`: every transaction it begins (the drivers' packages) signs in as them. */
+export declare function actingAs<R>(who: Who, fn: () => R): R;
+/** A background job (BullMQ, Next.js `after()`, a cron handler) that acts for `who`, whatever started it:
+ *  job(["service", 3], async (payload) => { ... }). */
+export declare function job<A extends unknown[], R>(who: Who, fn: (...args: A) => R): (...args: A) => R;
+/** Who the request is, when nothing set it with actingAs: e.g. async () => (await auth())?.user.id */
+export type UserResolver = () => Who | Promise<Who>;
+/** Something to run before a transaction signs in (the Next.js integration keeps signed-in reads out of caches). */
+export declare function beforeSignIn(hook: (p: Principal) => unknown): void;
+/** Whom the next transaction signs in as: `who` if the call was given one (null: nobody), else whoever the
+ *  code acts for, else user(), else nobody. The hooks run for each: a transaction told who it acts for is
+ *  kept out of caches like any other. */
+export declare function signingIn(user?: UserResolver, who?: Who): Promise<Principal>;
+/** The statement that signs a transaction in, with its parameters. */
+export declare function actAs(p: Principal): {
+    text: string;
+    values: (string | null)[];
+};
+/** A SQL string literal (standard_conforming_strings, as every supported Postgres has it). */
+export declare function literal(value: string | null): string;
+/** The same statement with its values written in, for APIs that take no parameters. */
+export declare function actAsSql(p: Principal): string;
+/** An RFC 9457 problem body. */
+export interface Problem {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    [field: string]: unknown;
+}
+/** The database refused a write, and said why: the rule (table and command), and the explanation. */
+export declare class Refused extends Error {
+    table?: string | undefined;
+    command?: string | undefined;
+    why: string[];
+    readonly status = 403;
+    readonly code = "AZ709";
+    constructor(message: string, table?: string | undefined, command?: string | undefined, why?: string[], options?: {
+        cause?: unknown;
+    });
+    problem(): Problem;
+}
+/** The row isn't there, or whoever the transaction acts for can't see it. */
+export declare class NotFound extends Error {
+    table?: string | undefined;
+    id?: string | undefined;
+    readonly status = 404;
+    constructor(table?: string | undefined, id?: string | undefined, options?: {
+        cause?: unknown;
+    });
+    problem(): Problem;
+}
+/** A query that needs to know who is asking ran in a transaction nobody signed in to (strict sign-in). */
+export declare class NotSignedIn extends Error {
+    readonly code = "AZ701";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** authz.connection_check() found that the app's connection skips row-level security (or worse). */
+export declare class ConnectionProblem extends Error {
+    problems: string[];
+    constructor(problems: string[]);
+}
+interface DbError {
+    code: string;
+    message: string;
+    detail?: string;
+    hint?: string;
+    schema?: string;
+    table?: string;
+    constraint?: string;
+}
+/** The Postgres error in e, if there is one: its SQLSTATE and fields, whichever driver raised it. */
+export declare function dbError(e: unknown): DbError | null;
+/** rowstile's code for a database error (AZ709; `rowstile help AZ709` says what it means): from its HINT, where
+ *  the runtime puts it, or its message. Undefined for an error rowstile didn't raise. */
+export declare function errorCode(e: unknown): string | undefined;
+export declare function sqlstate(e: unknown): string | undefined;
+/** A Refused for an error that is the database refusing a write (SQLSTATE 42501, raised by rowstile's
+ *  policies with the rule and why), else null. `schemaOf` qualifies a bare table name (Prisma knows it).
+ *  Another 42501 (a table the app role was never granted) is the app's mistake, not a refusal: null. */
+export declare function refusal(e: unknown, schemaOf?: (table: string) => string | undefined): Refused | null;
+/** Whether e is strict sign-in's error: a query that needs to know who is asking, and nobody signed in. */
+export declare function notSignedIn(e: unknown): boolean;
+/** e as rowstile's error: Refused, NotFound or NotSignedIn as they are, a database refusal as Refused, strict
+ *  sign-in's error as NotSignedIn; null for anything else. */
+export declare function translate(e: unknown, schemaOf?: (table: string) => string | undefined): Refused | NotFound | NotSignedIn | null;
+/** The problem body and status for e (Refused: 403, NotFound: 404), or null. */
+export declare function problemOf(e: unknown): Problem | null;
+/** A Response (application/problem+json) for e, or null: for route handlers. */
+export declare function problemResponse(e: unknown): Response | null;
+/** The errors among authz.connection_check()'s rows. */
+export declare function checkProblems(rows: {
+    severity: string;
+    problem: string;
+}[]): string[];
+/** Anything that runs one statement with $1, $2 parameters and returns its rows. */
+export interface Queryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+        rowCount?: number | null;
+    }>;
+}
+/** A share, as authz.list_shares returns it. */
+export interface Share {
+    relation: string;
+    subject_type: string;
+    subject_id: string;
+    subject_relation: string;
+    [column: string]: unknown;
+}
+/** What the React kit's routes need; each driver's package gives it (Prisma: db.$authz). */
+export interface AuthzCalls {
+    can<T extends ObjectType>(type: T, id: Id, perm: Permission<T>): Promise<boolean>;
+    perms<T extends ObjectType>(type: T, id: Id): Promise<Permission<T>[]>;
+    permsOf<T extends ObjectType>(type: T, ids: readonly Id[]): Promise<Record<string, Permission<T>[]>>;
+    list<T extends ObjectType>(type: T, perm: Permission<T>, page?: {
+        after?: Id;
+        limit?: number;
+    }): Promise<string[]>;
+    listShares<T extends ObjectType>(type: T, id: Id): Promise<Share[]>;
+    share<T extends SharedType>(type: T, id: Id, relation: SharedRelation<T>, subjectType: string, subjectId: Id, subjectRelation?: string): Promise<void>;
+    unshare<T extends SharedType>(type: T, id: Id, relation: SharedRelation<T>, subjectType: string, subjectId: Id, subjectRelation?: string): Promise<void>;
+    requestAccess<T extends SharedType>(type: T, id: Id, relation: SharedRelation<T>, reason: string): Promise<string>;
+    explainRule(table: string, command: "insert" | "update" | "delete", id?: Id, row?: object): Promise<string[] | null>;
+    connectionCheck(): Promise<{
+        severity: string;
+        problem: string;
+    }[]>;
+}
+/** The runtime's functions over q (a signed-in transaction, or something that signs each query in). */
+export declare function calls(q: Queryable): AuthzCalls & {
+    expect<R>(result: R, table: string, command: "update" | "delete", id: Id, row?: object): Promise<R>;
+    check(): Promise<void>;
+};
+/** Whether an UPDATE or DELETE's result changed anything: rows, a count, {count}, {rowCount}, postgres.js's .count. */
+export declare function changed(result: unknown): boolean;
+/** What an UPDATE or DELETE that changed nothing was: NotFound when the row isn't there for this user (why is
+ *  null), or when the rule allows the write (its first line says yes: the statement matched nothing for
+ *  another reason, such as a where with more than the key); Refused with the reason otherwise. */
+export declare function verdict(table: string, command: string, id: Id, why: string[] | null): NotFound | Refused;
+export {};

package/dist/index.js

@@ -0,0 +1,339 @@
+/**
+ * rowstile for TypeScript apps.
+ *
+ * Every transaction signs in as whoever the request (or the job) acts for, with `authz.act_as()`; the
+ * database's refusals become `Refused` (a 403 with the reason), rows the user can't see become `NotFound`
+ * (a 404). This package holds no rowstile logic: it calls the `authz.*` functions the policy made, and
+ * translates their answers. The drivers' packages (`@rowstile/pg`, `/postgres`, `/prisma`, `/drizzle`) use it.
+ *
+ *     import { actingAs } from "@rowstile/client";
+ *     await actingAs(42, async () => { ... });        // every transaction in here signs in as user 42
+ *
+ * The names the policy declares come from the generated file (`rowstile client`, e.g. `src/authz.gen.ts`),
+ * which registers them here, so a misspelled type or permission doesn't type-check.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/** An id as the database compares it: a composite key as Postgres writes a row (every field quoted); a key of
+ *  one column given as an array is that value. */
+export function idText(id) {
+    if (Array.isArray(id)) {
+        if (id.length === 1)
+            return String(id[0]);
+        return "(" + id.map((v) => '"' + String(v).replace(/["\\]/g, (c) => "\\" + c) + '"').join(",") + ")";
+    }
+    return String(id);
+}
+export const NOBODY = Object.freeze({ type: "user", id: null });
+export function principal(who) {
+    if (who === null || who === undefined)
+        return NOBODY;
+    if (Array.isArray(who)) {
+        const [type, id] = who;
+        return Object.freeze({ type: String(type), id: id === null || id === undefined ? null : String(id) });
+    }
+    if (typeof who === "object") {
+        const p = who;
+        return Object.freeze({ type: p.type ?? "user", id: p.id === null || p.id === undefined ? null : String(p.id) });
+    }
+    return Object.freeze({ type: "user", id: String(who) });
+}
+/** What describe() wrote, read back: "service:3" is service 3, "42" user 42, "nobody" nobody. For text your own
+ *  code wrote (a job's argument, the audit trail's `by`), not for an id that came from outside. */
+export function parsePrincipal(text) {
+    if (text === "nobody")
+        return NOBODY;
+    const colon = text.indexOf(":");
+    if (colon > 0 && !text.startsWith("("))
+        return Object.freeze({ type: text.slice(0, colon), id: text.slice(colon + 1) });
+    return Object.freeze({ type: "user", id: text });
+}
+/** "42", "service:3" or "nobody". */
+export function describe(p) {
+    return p.id === null ? "nobody" : p.type === "user" ? p.id : `${p.type}:${p.id}`;
+}
+const KEY = Symbol.for("rowstile.context");
+const shared = globalThis[KEY] ??
+    (globalThis[KEY] = { store: new AsyncLocalStorage(), hooks: [] });
+/** Who the code running now acts for (set by actingAs, a job, or a web integration), or undefined if unset. */
+export function current() {
+    return shared.store.getStore();
+}
+/** Runs fn in p's scope; a promise it returns is awaited in the scope too, as Prisma's queries only start when
+ *  they are awaited. */
+function inScope(p, fn) {
+    return shared.store.run(p, () => {
+        const r = fn();
+        if (r && typeof r.then === "function")
+            return (async () => await r)();
+        return r;
+    });
+}
+/** Runs fn acting for `who`: every transaction it begins (the drivers' packages) signs in as them. */
+export function actingAs(who, fn) {
+    return inScope(principal(who), fn);
+}
+/** A background job (BullMQ, Next.js `after()`, a cron handler) that acts for `who`, whatever started it:
+ *  job(["service", 3], async (payload) => { ... }). */
+export function job(who, fn) {
+    const p = principal(who);
+    return (...args) => inScope(p, () => fn(...args));
+}
+/** Something to run before a transaction signs in (the Next.js integration keeps signed-in reads out of caches). */
+export function beforeSignIn(hook) {
+    if (!shared.hooks.includes(hook))
+        shared.hooks.push(hook);
+}
+/** Whom the next transaction signs in as: `who` if the call was given one (null: nobody), else whoever the
+ *  code acts for, else user(), else nobody. The hooks run for each: a transaction told who it acts for is
+ *  kept out of caches like any other. */
+export async function signingIn(user, who) {
+    let p = who !== undefined ? principal(who) : current();
+    if (p === undefined)
+        p = user ? principal(await user()) : NOBODY;
+    for (const hook of shared.hooks)
+        await hook(p);
+    return p;
+}
+/** The statement that signs a transaction in, with its parameters. */
+export function actAs(p) {
+    return { text: "SELECT authz.act_as($1, $2)", values: p.id === null ? [null, null] : [p.type, p.id] };
+}
+/** A SQL string literal (standard_conforming_strings, as every supported Postgres has it). */
+export function literal(value) {
+    return value === null ? "NULL" : "'" + value.replace(/'/g, "''") + "'";
+}
+/** The same statement with its values written in, for APIs that take no parameters. */
+export function actAsSql(p) {
+    return p.id === null ? "SELECT authz.act_as(NULL, NULL)" : `SELECT authz.act_as(${literal(p.type)}, ${literal(p.id)})`;
+}
+/** The database refused a write, and said why: the rule (table and command), and the explanation. */
+export class Refused extends Error {
+    table;
+    command;
+    why;
+    status = 403;
+    code = "AZ709"; // rowstile help AZ709
+    constructor(message, table, command, why = [], options) {
+        super(message, options);
+        this.table = table;
+        this.command = command;
+        this.why = why;
+        this.name = "Refused";
+    }
+    problem() {
+        return { type: "https://rowstile.dev/problems/refused", title: "Forbidden", status: 403, detail: this.message,
+            table: this.table ?? null, command: this.command ?? null, why: this.why, code: this.code };
+    }
+}
+/** The row isn't there, or whoever the transaction acts for can't see it. */
+export class NotFound extends Error {
+    table;
+    id;
+    status = 404;
+    constructor(table, id, options) {
+        super(`${table ?? "the row"}${id === undefined ? "" : " " + id} not found`, options);
+        this.table = table;
+        this.id = id;
+        this.name = "NotFound";
+    }
+    problem() {
+        return { type: "https://rowstile.dev/problems/not-found", title: "Not Found", status: 404, detail: this.message };
+    }
+}
+/** A query that needs to know who is asking ran in a transaction nobody signed in to (strict sign-in). */
+export class NotSignedIn extends Error {
+    code = "AZ701"; // rowstile help AZ701
+    constructor(message, options) {
+        super(message, options);
+        this.name = "NotSignedIn";
+    }
+}
+/** authz.connection_check() found that the app's connection skips row-level security (or worse). */
+export class ConnectionProblem extends Error {
+    problems;
+    constructor(problems) {
+        super("the app's database connection can't be used with rowstile: " + problems.join("; "));
+        this.problems = problems;
+        this.name = "ConnectionProblem";
+    }
+}
+/** The error and the driver's errors inside it: pg's and postgres.js's are the error itself, Drizzle keeps
+ *  the driver's as the cause, Prisma's driver adapters in meta.driverAdapterError.cause. */
+function chain(e) {
+    const out = [];
+    const todo = [e];
+    while (todo.length) {
+        const x = todo.shift();
+        if (!x || typeof x !== "object" || out.includes(x))
+            continue;
+        const o = x;
+        out.push(o);
+        todo.push(o.cause, o.meta, o.driverAdapterError, o.originalError);
+    }
+    return out;
+}
+const str = (v) => (typeof v === "string" && v ? v : undefined);
+/** The Postgres error in e, if there is one: its SQLSTATE and fields, whichever driver raised it. */
+export function dbError(e) {
+    for (const o of chain(e)) {
+        if (o.clientVersion !== undefined)
+            continue; // Prisma's own error: its code is Prisma's
+        const code = str(o.originalCode) ?? str(o.sqlState) ?? str(o.code);
+        // five characters, and not Node's own (EPIPE, EPERM: no SQLSTATE class begins with E)
+        if (!code || !/^[0-9A-Z]{5}$/.test(code) || code.startsWith("E"))
+            continue;
+        return {
+            code,
+            message: str(o.originalMessage) ?? str(o.message) ?? "",
+            detail: str(o.detail), hint: str(o.hint),
+            schema: str(o.schema) ?? str(o.schema_name), table: str(o.table) ?? str(o.table_name),
+            constraint: str(o.constraint) ?? str(o.constraint_name),
+        };
+    }
+    return null;
+}
+/** rowstile's code for a database error (AZ709; `rowstile help AZ709` says what it means): from its HINT, where
+ *  the runtime puts it, or its message. Undefined for an error rowstile didn't raise. */
+export function errorCode(e) {
+    const err = dbError(e);
+    for (const text of [err?.hint, err?.message]) {
+        const m = /(?:rowstile|rowfence) help (AZ\d{3})|\[(AZ\d{3})\]/.exec(text ?? "");
+        if (m)
+            return m[1] ?? m[2];
+    }
+    return undefined;
+}
+export function sqlstate(e) {
+    return dbError(e)?.code;
+}
+const RLS_GENERIC = /^new row violates row-level security policy (\(USING expression\) )?for table "([^"]+)"/;
+const OURS = /may not (insert|update|delete) this row (?:into|of) (\S+?)(?: to these values)?$/;
+/** A Refused for an error that is the database refusing a write (SQLSTATE 42501, raised by rowstile's
+ *  policies with the rule and why), else null. `schemaOf` qualifies a bare table name (Prisma knows it).
+ *  Another 42501 (a table the app role was never granted) is the app's mistake, not a refusal: null. */
+export function refusal(e, schemaOf) {
+    const err = dbError(e);
+    if (!err || err.code !== "42501")
+        return null;
+    const generic = RLS_GENERIC.exec(err.message);
+    if (generic) {
+        const schema = err.schema ?? schemaOf?.(generic[2]);
+        const table = schema ? `${schema}.${generic[2]}` : generic[2];
+        if (generic[1]) {
+            // an upsert (INSERT ... ON CONFLICT DO UPDATE) whose existing row this user may not update, or not see
+            return new Refused(`${err.message}: the row is there already, and the update rule (or the select rule) doesn't ` +
+                "let this user change it (ON CONFLICT DO UPDATE)", table, "update", [], { cause: e });
+        }
+        // Postgres's own words, not rowstile's: the row was allowed in, but may not be read back (INSERT ...
+        // RETURNING, or an ORM that reads the new row, as Prisma's create does), which the select rule decides
+        return new Refused(`${err.message}: the write was allowed, but the select rule doesn't let this user read the row ` +
+            "back (RETURNING); read it back only if the select rule allows it", table, "select", [], { cause: e });
+    }
+    const ours = OURS.exec(err.message);
+    if (!ours && !err.constraint?.startsWith("authz_") && errorCode(e) === undefined)
+        return null;
+    const table = err.schema && err.table ? `${err.schema}.${err.table}` : err.table ?? ours?.[2];
+    const command = err.constraint?.startsWith("authz_") ? err.constraint.slice(6) : ours?.[1];
+    return new Refused(err.message, table, command, err.detail ? err.detail.split("\n") : [], { cause: e });
+}
+/** Whether e is strict sign-in's error: a query that needs to know who is asking, and nobody signed in. */
+export function notSignedIn(e) {
+    return sqlstate(e) === "28000";
+}
+/** e as rowstile's error: Refused, NotFound or NotSignedIn as they are, a database refusal as Refused, strict
+ *  sign-in's error as NotSignedIn; null for anything else. */
+export function translate(e, schemaOf) {
+    if (e instanceof Refused || e instanceof NotFound || e instanceof NotSignedIn)
+        return e;
+    const r = refusal(e, schemaOf);
+    if (r)
+        return r;
+    if (notSignedIn(e)) {
+        return new NotSignedIn("nobody signed in in this transaction: every transaction must begin with authz.act_as() " +
+            "(the drivers' packages do it; is this query outside them?)", { cause: e });
+    }
+    return null;
+}
+/** The problem body and status for e (Refused: 403, NotFound: 404), or null. */
+export function problemOf(e) {
+    const t = translate(e);
+    return t instanceof Refused || t instanceof NotFound ? t.problem() : null;
+}
+/** A Response (application/problem+json) for e, or null: for route handlers. */
+export function problemResponse(e) {
+    const p = problemOf(e);
+    return p ? new Response(JSON.stringify(p), { status: p.status, headers: { "content-type": "application/problem+json" } }) : null;
+}
+/** The errors among authz.connection_check()'s rows. */
+export function checkProblems(rows) {
+    return rows.filter((r) => r.severity === "error").map((r) => r.problem);
+}
+// The policy names tables with their schema; a table named without one (a model that names no schema) is
+// looked up on the search_path
+const EXPLAIN_RULE = "SELECT authz.explain_rule(coalesce((SELECT n.nspname || '.' || c.relname FROM pg_catalog.pg_class c " +
+    "JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE position('.' in $1::text) = 0 " +
+    "AND c.oid = pg_catalog.to_regclass(pg_catalog.quote_ident($1::text))), $1::text), $2, $3, $4::jsonb) AS e";
+/** The runtime's functions over q (a signed-in transaction, or something that signs each query in). */
+export function calls(q) {
+    const one = async (text, values) => (await q.query(text, values)).rows[0];
+    const c = {
+        can: async (type, id, perm) => Boolean((await one("SELECT authz.can($1, $2::text, $3) AS ok", [type, idText(id), perm])).ok),
+        perms: async (type, id) => ((await one("SELECT authz.perms($1, $2::text) AS p", [type, idText(id)])).p ?? []),
+        permsOf: async (type, ids) => {
+            const rows = (await q.query("SELECT id, perms FROM authz.perms_of($1, $2::text[])", [type, ids.map(idText)])).rows;
+            return Object.fromEntries(rows.map((r) => [r.id, r.perms ?? []]));
+        },
+        list: async (type, perm, page = {}) => (await q.query("SELECT x FROM authz.list($1, $2, $3, $4) x", [type, perm, page.after === undefined ? null : idText(page.after), page.limit ?? null])).rows.map((r) => r.x),
+        listShares: async (type, id) => (await q.query("SELECT * FROM authz.list_shares($1, $2::text)", [type, idText(id)])).rows,
+        share: async (type, id, relation, subjectType, subjectId, subjectRelation = "") => {
+            // void functions in FROM: some drivers (Prisma) can't read a void column
+            await q.query("SELECT 1 AS ok FROM authz.share($1, $2::text, $3, $4, $5::text, $6)", [type, idText(id), relation, subjectType, idText(subjectId), subjectRelation]);
+        },
+        unshare: async (type, id, relation, subjectType, subjectId, subjectRelation = "") => {
+            await q.query("SELECT 1 AS ok FROM authz.unshare($1, $2::text, $3, $4, $5::text, $6)", [type, idText(id), relation, subjectType, idText(subjectId), subjectRelation]);
+        },
+        requestAccess: async (type, id, relation, reason) => String((await one("SELECT authz.request_access($1, $2::text, $3, $4) AS id", [type, idText(id), relation, reason])).id),
+        explainRule: async (table, command, id, row) => ((await one(EXPLAIN_RULE, [table, command, id === undefined ? null : idText(id), row === undefined ? null : JSON.stringify(row)])).e ?? null),
+        connectionCheck: async () => (await q.query("SELECT severity, problem FROM authz.connection_check()", [])).rows,
+        /** The result of an UPDATE or DELETE (rows, a count, or a driver's result): returned if it changed a row,
+         *  otherwise NotFound (the user can't see the row) or Refused (they may not, and why). */
+        expect: async (result, table, command, id, row) => {
+            if (changed(result))
+                return result;
+            throw verdict(table, command, id, await c.explainRule(table, command, id, row));
+        },
+        /** Throws ConnectionProblem if this connection skips row-level security. As nobody: it runs at start-up,
+         *  where there is no request to ask who is signed in. */
+        check: () => actingAs(null, async () => {
+            const problems = checkProblems(await c.connectionCheck());
+            if (problems.length)
+                throw new ConnectionProblem(problems);
+        }),
+    };
+    return c;
+}
+/** Whether an UPDATE or DELETE's result changed anything: rows, a count, {count}, {rowCount}, postgres.js's .count. */
+export function changed(result) {
+    if (typeof result === "number" || typeof result === "bigint")
+        return Number(result) > 0;
+    if (result && typeof result === "object") {
+        const o = result;
+        for (const k of ["rowCount", "count", "rowsAffected", "affectedRows"]) {
+            if (typeof o[k] === "number")
+                return o[k] > 0;
+        }
+        if (Array.isArray(result))
+            return result.length > 0;
+        if (Array.isArray(o.rows))
+            return o.rows.length > 0;
+    }
+    return Boolean(result);
+}
+/** What an UPDATE or DELETE that changed nothing was: NotFound when the row isn't there for this user (why is
+ *  null), or when the rule allows the write (its first line says yes: the statement matched nothing for
+ *  another reason, such as a where with more than the key); Refused with the reason otherwise. */
+export function verdict(table, command, id, why) {
+    if (why === null || /^\s*yes\b/.test(why[0] ?? ""))
+        return new NotFound(table, idText(id));
+    return new Refused(`permission denied: may not ${command} ${table} ${idText(id)}`, table, command, why);
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@rowstile/client",
+  "version": "0.1.0-alpha.2",
+  "description": "rowstile for TypeScript apps: who each transaction acts for, refusals as errors, generated names",
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/rowstile/rowstile.git", "directory": "sdk/typescript/client" },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist"],
+  "sideEffects": false,
+  "dependencies": {},
+  "peerDependencies": {}
+}