@palbase/backend 34.0.0 → 34.1.1

package/docs/auth.md

@@ -155,6 +155,64 @@ Two helpers are available in every policy body:
 Both take the caller from `auth.uid()` and accept no user id, so a policy cannot
 ask about somebody else.
 
+### `can` — what a row says you may do
+
+Every row a table hands back carries `can: string[]`: the names of the table's
+named **update** policies whose `using` expression is true for THIS row and THIS
+caller. It is computed in the same `SELECT` that fetched the row — the policy is
+the only copy of the rule, and `can` is its echo.
+
+```ts
+const transfer = await Database.public.transfers.findById(id);
+transfer?.can; // e.g. ["transfers_approve"] — typed from db/public.ts
+```
+
+To put it on the wire, name it in the response schema — the enum comes from the
+policy declaration, never from a hand-typed list:
+
+```ts
+import { z, can } from "@palbase/backend";
+import publicSchema from "../../db/public";
+
+export const TransferSchema = z.object({
+  id: z.string(),
+  status: z.string(),
+  can: can(publicSchema.tables.transfers),
+});
+```
+
+The contract, word for word: **`can` is for the interface; it cannot be used for
+an authorization decision; it may be incomplete; the server decides again on
+every request.** A policy whose `using` the engine cannot select as a column is
+dropped from `can` with a `warn` line — it never becomes a silent `true`. In a
+raw-string `using`, write column names unqualified (`status`, not
+`transfers.status` or `public.transfers.status`) and wrap every
+`auth.has_permission(...)` in `(select …)`; a comment, an unbalanced parenthesis
+or an unterminated quote drops the policy the same way.
+
+Rows read under `Database.$asService()` carry `can: []`: no policy applies to
+the service role and every `TO` gate is false for it, so a row fetched there and
+handed to a user says nothing about what that user may do — read it as the user.
+
+Only `.for("update")` policies are echoed. A `.for("all")` policy such as
+`notes_owner` above governs UPDATE too, but it is not a named update policy and
+never appears in `can` — a table whose only policy is `for("all")` gets
+`can: []` on every row, and `can(table)` refuses it by name. To get an
+affordance, declare a separate `.for("update")` policy beside it (the template's
+`notes_edit_own` next to `notes_owner`).
+
+The name `can` is reserved for this echo. A table that declares a column named
+`can` keeps its column and gets no echo (with a `warn`); a **relation** named
+`can` — a table named `can`, a `can_id` foreign key, `as: "can"` or
+`reverseAs: "can"` — is refused by `defineTable` itself, because `row.can` and
+`relations.can` cannot both be true of one row.
+
+When the server refuses, the 403 body names the cure: `required: "transfers.approve"`.
+`pb.auth.onPermissionDenied { required in … }` (iOS) / `pb.auth.onPermissionDenied(required => …)`
+(web) fires on it, so a screen drawn from a stale `can` refetches and repairs itself.
+`pb.auth.permissions.holds("transfers.approve")` is the live, observable set of the
+caller's permissions — pushed over realtime the moment a role changes.
+
 ## Email verification
 
 The platform handles verification end to end. **You do not configure a sender**,

package/docs/llms-full.txt

@@ -931,6 +931,64 @@ Two helpers are available in every policy body:
 Both take the caller from `auth.uid()` and accept no user id, so a policy cannot
 ask about somebody else.
 
+### `can` — what a row says you may do
+
+Every row a table hands back carries `can: string[]`: the names of the table's
+named **update** policies whose `using` expression is true for THIS row and THIS
+caller. It is computed in the same `SELECT` that fetched the row — the policy is
+the only copy of the rule, and `can` is its echo.
+
+```ts
+const transfer = await Database.public.transfers.findById(id);
+transfer?.can; // e.g. ["transfers_approve"] — typed from db/public.ts
+```
+
+To put it on the wire, name it in the response schema — the enum comes from the
+policy declaration, never from a hand-typed list:
+
+```ts
+import { z, can } from "@palbase/backend";
+import publicSchema from "../../db/public";
+
+export const TransferSchema = z.object({
+  id: z.string(),
+  status: z.string(),
+  can: can(publicSchema.tables.transfers),
+});
+```
+
+The contract, word for word: **`can` is for the interface; it cannot be used for
+an authorization decision; it may be incomplete; the server decides again on
+every request.** A policy whose `using` the engine cannot select as a column is
+dropped from `can` with a `warn` line — it never becomes a silent `true`. In a
+raw-string `using`, write column names unqualified (`status`, not
+`transfers.status` or `public.transfers.status`) and wrap every
+`auth.has_permission(...)` in `(select …)`; a comment, an unbalanced parenthesis
+or an unterminated quote drops the policy the same way.
+
+Rows read under `Database.$asService()` carry `can: []`: no policy applies to
+the service role and every `TO` gate is false for it, so a row fetched there and
+handed to a user says nothing about what that user may do — read it as the user.
+
+Only `.for("update")` policies are echoed. A `.for("all")` policy such as
+`notes_owner` above governs UPDATE too, but it is not a named update policy and
+never appears in `can` — a table whose only policy is `for("all")` gets
+`can: []` on every row, and `can(table)` refuses it by name. To get an
+affordance, declare a separate `.for("update")` policy beside it (the template's
+`notes_edit_own` next to `notes_owner`).
+
+The name `can` is reserved for this echo. A table that declares a column named
+`can` keeps its column and gets no echo (with a `warn`); a **relation** named
+`can` — a table named `can`, a `can_id` foreign key, `as: "can"` or
+`reverseAs: "can"` — is refused by `defineTable` itself, because `row.can` and
+`relations.can` cannot both be true of one row.
+
+When the server refuses, the 403 body names the cure: `required: "transfers.approve"`.
+`pb.auth.onPermissionDenied { required in … }` (iOS) / `pb.auth.onPermissionDenied(required => …)`
+(web) fires on it, so a screen drawn from a stale `can` refetches and repairs itself.
+`pb.auth.permissions.holds("transfers.approve")` is the live, observable set of the
+caller's permissions — pushed over realtime the moment a role changes.
+
 ## Email verification
 
 The platform handles verification end to end. **You do not configure a sender**,
@@ -2743,6 +2801,21 @@ calling user's rows — no `WHERE owner = …` needed in the handler. To read or
 write across all users (e.g. an admin job), use the explicit bypass:
 `Database.$asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
 
+Name your **update** policies deliberately: each name becomes a value in the row's
+`can` array (`row.can: ("transfers_approve" | "transfers_cancel")[]` in
+`palbase-env.d.ts`), and `can(table)` puts the same names into a response schema
+as an enum. Only `.for("update")` counts: a `.for("all")` policy like the
+owner policies above governs UPDATE but is never echoed, so a table with only
+`for("all")` policies carries `can: []`. In a raw-string `using`, write column
+names UNQUALIFIED (`status = 'pending_approval'`, not `transfers.status` or
+`public.transfers.status`) and wrap `auth.has_permission(...)` in `(select …)`:
+the engine selects the expression under a row alias, and a `using` it cannot
+carry there — a table qualifier, a comment, an unwrapped `has_permission`, a
+policy name longer than 59 bytes — is dropped from `can` with a `warn`, never
+spliced. A column or relation named `can` is reserved (see [auth.md](./auth.md)).
+`can` is for the interface; it cannot be used for an authorization decision; it
+may be incomplete; the server decides again on every request.
+
 ### How policies are applied
 
 On deploy, Palbase diffs your declared schema against the live database and

package/docs/schema.md

@@ -676,6 +676,21 @@ calling user's rows — no `WHERE owner = …` needed in the handler. To read or
 write across all users (e.g. an admin job), use the explicit bypass:
 `Database.$asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
 
+Name your **update** policies deliberately: each name becomes a value in the row's
+`can` array (`row.can: ("transfers_approve" | "transfers_cancel")[]` in
+`palbase-env.d.ts`), and `can(table)` puts the same names into a response schema
+as an enum. Only `.for("update")` counts: a `.for("all")` policy like the
+owner policies above governs UPDATE but is never echoed, so a table with only
+`for("all")` policies carries `can: []`. In a raw-string `using`, write column
+names UNQUALIFIED (`status = 'pending_approval'`, not `transfers.status` or
+`public.transfers.status`) and wrap `auth.has_permission(...)` in `(select …)`:
+the engine selects the expression under a row alias, and a `using` it cannot
+carry there — a table qualifier, a comment, an unwrapped `has_permission`, a
+policy name longer than 59 bytes — is dropped from `can` with a `warn`, never
+spliced. A column or relation named `can` is reserved (see [auth.md](./auth.md)).
+`can` is for the interface; it cannot be used for an authorization decision; it
+may be incomplete; the server decides again on every request.
+
 ### How policies are applied
 
 On deploy, Palbase diffs your declared schema against the live database and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "34.0.0",
+  "version": "34.1.1",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
@@ -94,24 +94,12 @@
     "stager",
     "template"
   ],
-  "scripts": {
-    "build": "tsup && npm run build:stager",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "docs:build": "node scripts/build-llms.mjs",
-    "emit:openapi-fixture": "tsx scripts/emit-openapi-fixture.mjs",
-    "check:api": "node scripts/api-surface.mjs",
-    "api:update": "node scripts/api-surface.mjs --update",
-    "build:stager": "mkdir -p stager && for f in src/stager/*.js; do case \"$f\" in *.test.js) ;; *) cp \"$f\" stager/ ;; esac; done && cp src/stager/package.json stager/"
-  },
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^7.3.4",
     "reflect-metadata": "^0.2.2",
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@palbase/core": "workspace:^",
     "@swc/core": "^1.16.1",
     "@types/node": "^25.5.2",
     "bun-types": "^1.4.0",
@@ -121,12 +109,24 @@
     "tsx": "^4.22.4",
     "typescript": "^5.7.0",
     "unplugin-swc": "^1.5.11",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@palbase/core": "^2.4.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "bin": {
     "palbase-backend": "./dist/bin/palbase-backend.js"
+  },
+  "scripts": {
+    "build": "tsup && npm run build:stager",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "docs:build": "node scripts/build-llms.mjs",
+    "emit:openapi-fixture": "tsx scripts/emit-openapi-fixture.mjs",
+    "check:api": "node scripts/api-surface.mjs",
+    "api:update": "node scripts/api-surface.mjs --update",
+    "build:stager": "mkdir -p stager && for f in src/stager/*.js; do case \"$f\" in *.test.js) ;; *) cp \"$f\" stager/ ;; esac; done && cp src/stager/package.json stager/"
   }
-}
+}

package/template/db/public.ts

@@ -31,6 +31,18 @@ const notes = defineTable("notes", {
       .using("user_id = (select auth.uid())")
       .withCheck("user_id = (select auth.uid())"),
 
+    // A NAMED update policy is also what the row's `can` array echoes back:
+    // `note.can` contains "notes_edit_own" when THIS caller may edit THIS row
+    // (typed from this file). Put it on the wire with
+    // `can(publicSchema.tables.notes)` in the response schema — the schema's
+    // table definition, not this handle. `can` is for the interface; it cannot be used for an
+    // authorization decision; it may be incomplete; the server decides again
+    // on every request.
+    policy("notes_edit_own")
+      .for("update")
+      .to("authenticated")
+      .using("user_id = (select auth.uid())"),
+
     // MODERATION, when you want it — delete these two if you do not.
     //
     // Roles are yours and there is no built-in "admin": you declare them from