@palbase/backend 38.0.4 → 38.0.5

package/docs/auth.md

@@ -40,17 +40,21 @@ interface UserT {          // exported as `UserT`; the value name `User` is the
 }
 ```
 
-Every field is **server-resolved** from the verified profile — nothing here is
-client-settable. `metadata` is your own `auth.users.metadata` (set through the
-admin users API); `role` is the **database** role RLS reads and is always
-`"authenticated"` for a signed-in user, so `user.role === "admin"` is always
-false and reads like a working check.
+Every field is **server-resolved** — nothing here is client-settable. `role` is
+the **database** role RLS reads and is always `"authenticated"` for a signed-in
+user, so `user.role === "admin"` is always false and reads like a working check.
+
+**`metadata` is always `{}`.** Its only source is a `metadata` claim, and the
+access token has none — so an `auth.users.metadata` row you filled through the
+admin users API never reaches `user.metadata`, and `user.metadata.plan` is
+`undefined` for every caller with nothing raised anywhere to say so. Keep your
+own per-user attributes in a table of your own and read them with `Database`.
 
 Application roles are **`user.roles`** — a `string[]` resolved per request from
 `auth.user_roles`, the table `palbase roles` writes. They were once kept in
 `metadata`; they are not any more, and a role written there gates nothing.
 
-`emailVerified`, `email`, `role` and `metadata` come from the **verified token**,
+`emailVerified`, `email` and `role` come from the **verified token**,
 so they say what was true when it was minted: a user who confirms their address
 mid-session keeps reporting `false` until their next token. `roles` is the
 exception, and deliberately so — it is read from the table on every request, so

package/docs/database.md

@@ -714,10 +714,12 @@ policies, every `Database.*` call runs as the request's verified user, so the
 database filters out rows the user's policies don't allow. That is the secure
 default.
 
-The Postgres role it connects as is **`backend_authenticated`** (or
-`backend_anon` when there is no signed-in user) — not `authenticated`. You
+The Postgres role it connects as is **`backend_authenticated`** — always, for
+every request, whether or not somebody is signed in — not `authenticated`. You
 rarely need to know that, because a policy declared in `db/*.ts` is
-deployed targeting both. It matters in exactly one place: **hand-written
+deployed targeting both. What it does mean is that the role never tells a
+policy whether the caller is signed in: put that in the `using` expression,
+never in the role. It matters in exactly one place: **hand-written
 `CREATE POLICY` SQL in a migration must name both roles**, or it applies to
 nothing your code does. See
 [Row-Level Security](./schema.md#row-level-security-rls).

package/docs/endpoints.md

@@ -103,9 +103,13 @@ query (RFC semantics), so a QUERY route carries its whole input there.
 
 `@Body`/`@QueryParams`/`@Headers` take a zod schema (validation + codegen source); the
 developer writes the matching type annotation (same name). `UserT` is the
-authenticated-user type (`{ id: string; email?: string; role: string; metadata:
-Record<string, unknown> }`) — exported under the alias `UserT` because the value
-name `User` is the `@User()` decorator.
+authenticated-user type (`{ id: string; email?: string; emailVerified: boolean;
+role: string; roles: string[]; metadata: Record<string, unknown>; device:
+VerifiedDevice | null }`) — exported under the alias `UserT` because the value
+name `User` is the `@User()` decorator. **`roles` is the one to reach for**:
+`role` is the DATABASE role and is always `"authenticated"` for a signed-in
+caller, so `user.role === "admin"` is a check that never fires. See
+[Authentication](./auth.md#what-user-gives-you).
 
 ## Output = return type
 
@@ -118,12 +122,22 @@ error. A method that returns nothing annotates `: void` (or `: Promise<void>`).
 ## Auth — controller default + route override cascade
 
 **Secure by default:** a route requires authentication UNLESS it explicitly opts
-out. Resolution order (most specific wins):
+out. Resolution order (most specific wins) — **four links, not three**:
 
 1. Route-level `@Post("", { auth })` — wins if present.
 2. Controller-level `@Controller("/x", { auth })` — applies to routes without
    their own `auth`.
-3. Default `true` (secure-by-default).
+3. **Application-level `defineDefaultAuth(...)`** — one declaration, every
+   controller that did not speak for itself. This is the link to know about,
+   because it can TIGHTEN what a route you are reading looks like it does:
+   `defineDefaultAuth({ verifiedEmail: true })` makes every undeclared route
+   demand a confirmed address, and nothing at the route says so.
+4. Default `true` (secure-by-default).
+
+The whole chain is one function — `resolveEffectiveAuth(routeAuth,
+controllerAuth)` — and both the router and the spec emitter ask it rather than
+spelling the cascade out, so the build-time answer and the runtime answer cannot
+drift apart about who may call an endpoint.
 
 ```ts
 @Controller("/public", { auth: false })          // all routes default public

package/docs/errors.md

@@ -26,14 +26,15 @@ import { BadRequest, Unauthorized, Forbidden, NotFound, Conflict, TooManyRequest
 
 throw new Conflict("title taken");      // → 409  ("conflict" code by default)
 throw new NotFound();                   // → 404  ("not_found", "Not found")
-throw new BadRequest("missing field");  // → 400
+throw new BadRequest({ fields: [] });   // → 400  (data-first, see below)
 throw new Unauthorized();               // → 401
 throw new Forbidden();                  // → 403
-throw new TooManyRequests();            // → 429
+throw new TooManyRequests({ retryAfter: 30 });  // → 429  (data-first)
 ```
 
-Each class fixes its HTTP status. The constructor is
-`new <Class>(message?, code?, data?)`:
+Each class fixes its HTTP status. Four of them take
+`new <Class>(message?, code?, data?)` — `Unauthorized`, `Forbidden`, `NotFound`,
+`Conflict`:
 
 - `message` overrides the human-readable `error_description` (defaults to a label
   derived from the class name).
@@ -41,6 +42,13 @@ Each class fixes its HTTP status. The constructor is
   code, e.g. `not_found`).
 - `data` rides along under the envelope's `data` field for structured context.
 
+**`BadRequest` and `TooManyRequests` are DATA-FIRST, and their data is
+required** — `new BadRequest(data, message?)`, `new TooManyRequests(data,
+message?)`. Both carry a fixed typed payload so codegen can surface it on the
+client: `BadRequestData` is `{ fields: FieldError[] }` and
+`TooManyRequestsData` is `{ retryAfter: number }`. Passing a string, or nothing,
+does not compile.
+
 ```ts
 throw new NotFound("Room does not exist", "room_not_found");
 throw new Conflict("locked", "title_locked", { retryAfter: 30 });

package/docs/llms-full.txt

@@ -702,9 +702,13 @@ query (RFC semantics), so a QUERY route carries its whole input there.
 
 `@Body`/`@QueryParams`/`@Headers` take a zod schema (validation + codegen source); the
 developer writes the matching type annotation (same name). `UserT` is the
-authenticated-user type (`{ id: string; email?: string; role: string; metadata:
-Record<string, unknown> }`) — exported under the alias `UserT` because the value
-name `User` is the `@User()` decorator.
+authenticated-user type (`{ id: string; email?: string; emailVerified: boolean;
+role: string; roles: string[]; metadata: Record<string, unknown>; device:
+VerifiedDevice | null }`) — exported under the alias `UserT` because the value
+name `User` is the `@User()` decorator. **`roles` is the one to reach for**:
+`role` is the DATABASE role and is always `"authenticated"` for a signed-in
+caller, so `user.role === "admin"` is a check that never fires. See
+[Authentication](./auth.md#what-user-gives-you).
 
 ## Output = return type
 
@@ -717,12 +721,22 @@ error. A method that returns nothing annotates `: void` (or `: Promise<void>`).
 ## Auth — controller default + route override cascade
 
 **Secure by default:** a route requires authentication UNLESS it explicitly opts
-out. Resolution order (most specific wins):
+out. Resolution order (most specific wins) — **four links, not three**:
 
 1. Route-level `@Post("", { auth })` — wins if present.
 2. Controller-level `@Controller("/x", { auth })` — applies to routes without
    their own `auth`.
-3. Default `true` (secure-by-default).
+3. **Application-level `defineDefaultAuth(...)`** — one declaration, every
+   controller that did not speak for itself. This is the link to know about,
+   because it can TIGHTEN what a route you are reading looks like it does:
+   `defineDefaultAuth({ verifiedEmail: true })` makes every undeclared route
+   demand a confirmed address, and nothing at the route says so.
+4. Default `true` (secure-by-default).
+
+The whole chain is one function — `resolveEffectiveAuth(routeAuth,
+controllerAuth)` — and both the router and the spec emitter ask it rather than
+spelling the cascade out, so the build-time answer and the runtime answer cannot
+drift apart about who may call an endpoint.
 
 ```ts
 @Controller("/public", { auth: false })          // all routes default public
@@ -816,17 +830,21 @@ interface UserT {          // exported as `UserT`; the value name `User` is the
 }
 ```
 
-Every field is **server-resolved** from the verified profile — nothing here is
-client-settable. `metadata` is your own `auth.users.metadata` (set through the
-admin users API); `role` is the **database** role RLS reads and is always
-`"authenticated"` for a signed-in user, so `user.role === "admin"` is always
-false and reads like a working check.
+Every field is **server-resolved** — nothing here is client-settable. `role` is
+the **database** role RLS reads and is always `"authenticated"` for a signed-in
+user, so `user.role === "admin"` is always false and reads like a working check.
+
+**`metadata` is always `{}`.** Its only source is a `metadata` claim, and the
+access token has none — so an `auth.users.metadata` row you filled through the
+admin users API never reaches `user.metadata`, and `user.metadata.plan` is
+`undefined` for every caller with nothing raised anywhere to say so. Keep your
+own per-user attributes in a table of your own and read them with `Database`.
 
 Application roles are **`user.roles`** — a `string[]` resolved per request from
 `auth.user_roles`, the table `palbase roles` writes. They were once kept in
 `metadata`; they are not any more, and a role written there gates nothing.
 
-`emailVerified`, `email`, `role` and `metadata` come from the **verified token**,
+`emailVerified`, `email` and `role` come from the **verified token**,
 so they say what was true when it was minted: a user who confirms their address
 mid-session keeps reporting `false` until their next token. `roles` is the
 exception, and deliberately so — it is read from the table on every request, so
@@ -1830,10 +1848,12 @@ policies, every `Database.*` call runs as the request's verified user, so the
 database filters out rows the user's policies don't allow. That is the secure
 default.
 
-The Postgres role it connects as is **`backend_authenticated`** (or
-`backend_anon` when there is no signed-in user) — not `authenticated`. You
+The Postgres role it connects as is **`backend_authenticated`** — always, for
+every request, whether or not somebody is signed in — not `authenticated`. You
 rarely need to know that, because a policy declared in `db/*.ts` is
-deployed targeting both. It matters in exactly one place: **hand-written
+deployed targeting both. What it does mean is that the role never tells a
+policy whether the caller is signed in: put that in the `using` expression,
+never in the role. It matters in exactly one place: **hand-written
 `CREATE POLICY` SQL in a migration must name both roles**, or it applies to
 nothing your code does. See
 [Row-Level Security](./schema.md#row-level-security-rls).
@@ -2724,19 +2744,31 @@ policy("pb_owner_all")
 
 #### Which role your policy must target
 
-The runtime connects to Postgres as **`backend_authenticated`** (or
-`backend_anon` when anonymous), which is a **separate role from
-`authenticated`** — not a member of it. A policy addressed only to
+The runtime connects to Postgres as **`backend_authenticated`** — always, for
+every request, signed in or not — which is a **separate role from
+`authenticated`** and not a member of it. A policy addressed only to
 `authenticated` therefore applies to nothing your backend does, and with RLS on
 and no applicable policy, Postgres denies everything: reads come back empty and
 writes are refused, while your code compiles, your tests pass and the deploy
 reports success.
 
+`backend_anon` is provisioned too, but your backend never connects as it — so a
+policy written only for `anon` changes nothing about what your controllers can
+read.
+
 You do not have to think about this when you declare policies here. `.to("authenticated")`
 is deployed as `TO authenticated, backend_authenticated` (and `anon` gains
 `backend_anon`); `service_role` is left alone because `backend_service_role` has
 `BYPASSRLS` and policies never apply to it.
 
+**And that is why `.to("authenticated")` does not mean "signed in".** Since
+every request arrives under the same role, an anonymous caller reaches an
+`authenticated` policy too. The role decides nothing about identity — the
+`using` expression does. If a policy is meant for signed-in users, say so in the
+expression (`auth.uid() is not null`, or a predicate that dereferences it); a
+policy whose `using` never mentions the caller applies to anonymous traffic as
+well.
+
 **Hand-written SQL is the case to watch.** A `CREATE POLICY` in a
 `db/migrations/*.sql` file is applied verbatim, so write both roles yourself:
 
@@ -3038,11 +3070,13 @@ column builders, the policy DSL, and typed `Database.public.*` access.
 
 Two things the generated path handles for you and raw SQL does not.
 
-**Name both roles.** The runtime connects as `backend_authenticated` /
-`backend_anon`, which are *not* members of `authenticated` / `anon`. A policy
+**Name both roles.** The runtime connects as `backend_authenticated` — every
+request, signed in or not — and it is *not* a member of `authenticated`. A policy
 addressed only to `authenticated` applies to nothing your backend does — and with
 RLS on and no applicable policy, Postgres denies everything: empty reads, refused
-writes, no error anywhere that says why.
+writes, no error anywhere that says why. (`backend_anon` is provisioned and gets
+the same twin treatment, but your backend never connects as it, so naming it
+does not fence anonymous callers — the `using` expression is what does that.)
 
 **Guard the CREATE.** Postgres has no `CREATE POLICY IF NOT EXISTS`, so a
 migration that replays — a fresh Environment, or `palbase start --reset`, which
@@ -3534,14 +3568,15 @@ import { BadRequest, Unauthorized, Forbidden, NotFound, Conflict, TooManyRequest
 
 throw new Conflict("title taken");      // → 409  ("conflict" code by default)
 throw new NotFound();                   // → 404  ("not_found", "Not found")
-throw new BadRequest("missing field");  // → 400
+throw new BadRequest({ fields: [] });   // → 400  (data-first, see below)
 throw new Unauthorized();               // → 401
 throw new Forbidden();                  // → 403
-throw new TooManyRequests();            // → 429
+throw new TooManyRequests({ retryAfter: 30 });  // → 429  (data-first)
 ```
 
-Each class fixes its HTTP status. The constructor is
-`new <Class>(message?, code?, data?)`:
+Each class fixes its HTTP status. Four of them take
+`new <Class>(message?, code?, data?)` — `Unauthorized`, `Forbidden`, `NotFound`,
+`Conflict`:
 
 - `message` overrides the human-readable `error_description` (defaults to a label
   derived from the class name).
@@ -3549,6 +3584,13 @@ Each class fixes its HTTP status. The constructor is
   code, e.g. `not_found`).
 - `data` rides along under the envelope's `data` field for structured context.
 
+**`BadRequest` and `TooManyRequests` are DATA-FIRST, and their data is
+required** — `new BadRequest(data, message?)`, `new TooManyRequests(data,
+message?)`. Both carry a fixed typed payload so codegen can surface it on the
+client: `BadRequestData` is `{ fields: FieldError[] }` and
+`TooManyRequestsData` is `{ retryAfter: number }`. Passing a string, or nothing,
+does not compile.
+
 ```ts
 throw new NotFound("Room does not exist", "room_not_found");
 throw new Conflict("locked", "title_locked", { retryAfter: 30 });

package/docs/migrations.md

@@ -175,11 +175,13 @@ column builders, the policy DSL, and typed `Database.public.*` access.
 
 Two things the generated path handles for you and raw SQL does not.
 
-**Name both roles.** The runtime connects as `backend_authenticated` /
-`backend_anon`, which are *not* members of `authenticated` / `anon`. A policy
+**Name both roles.** The runtime connects as `backend_authenticated` — every
+request, signed in or not — and it is *not* a member of `authenticated`. A policy
 addressed only to `authenticated` applies to nothing your backend does — and with
 RLS on and no applicable policy, Postgres denies everything: empty reads, refused
-writes, no error anywhere that says why.
+writes, no error anywhere that says why. (`backend_anon` is provisioned and gets
+the same twin treatment, but your backend never connects as it, so naming it
+does not fence anonymous callers — the `using` expression is what does that.)
 
 **Guard the CREATE.** Postgres has no `CREATE POLICY IF NOT EXISTS`, so a
 migration that replays — a fresh Environment, or `palbase start --reset`, which

package/docs/schema.md

@@ -570,19 +570,31 @@ policy("pb_owner_all")
 
 #### Which role your policy must target
 
-The runtime connects to Postgres as **`backend_authenticated`** (or
-`backend_anon` when anonymous), which is a **separate role from
-`authenticated`** — not a member of it. A policy addressed only to
+The runtime connects to Postgres as **`backend_authenticated`** — always, for
+every request, signed in or not — which is a **separate role from
+`authenticated`** and not a member of it. A policy addressed only to
 `authenticated` therefore applies to nothing your backend does, and with RLS on
 and no applicable policy, Postgres denies everything: reads come back empty and
 writes are refused, while your code compiles, your tests pass and the deploy
 reports success.
 
+`backend_anon` is provisioned too, but your backend never connects as it — so a
+policy written only for `anon` changes nothing about what your controllers can
+read.
+
 You do not have to think about this when you declare policies here. `.to("authenticated")`
 is deployed as `TO authenticated, backend_authenticated` (and `anon` gains
 `backend_anon`); `service_role` is left alone because `backend_service_role` has
 `BYPASSRLS` and policies never apply to it.
 
+**And that is why `.to("authenticated")` does not mean "signed in".** Since
+every request arrives under the same role, an anonymous caller reaches an
+`authenticated` policy too. The role decides nothing about identity — the
+`using` expression does. If a policy is meant for signed-in users, say so in the
+expression (`auth.uid() is not null`, or a predicate that dereferences it); a
+policy whose `using` never mentions the caller applies to anonymous traffic as
+well.
+
 **Hand-written SQL is the case to watch.** A `CREATE POLICY` in a
 `db/migrations/*.sql` file is applied verbatim, so write both roles yourself:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "38.0.4",
+  "version": "38.0.5",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {