@palbase/backend 14.0.0 → 14.2.0

package/dist/test/index.d.cts

@@ -1,4 +1,4 @@
-import { D as DBClient, P as PBRequest, a as PalbaseModuleClients, L as Logger, C as CacheClient, U as User } from '../endpoint-CAWdScEH.cjs';
+import { D as DBClient, P as PBRequest, a as PalbaseModuleClients, L as Logger, C as CacheClient, U as User } from '../endpoint-D2yR2RD1.cjs';
 import 'zod';
 
 /** Mock DB client with tracking and seed data support. */

package/dist/test/index.d.ts

@@ -1,4 +1,4 @@
-import { D as DBClient, P as PBRequest, a as PalbaseModuleClients, L as Logger, C as CacheClient, U as User } from '../endpoint-CAWdScEH.js';
+import { D as DBClient, P as PBRequest, a as PalbaseModuleClients, L as Logger, C as CacheClient, U as User } from '../endpoint-D2yR2RD1.js';
 import 'zod';
 
 /** Mock DB client with tracking and seed data support. */

package/docs/auth.md

@@ -36,11 +36,38 @@ interface User {
 }
 ```
 
-Every field is **server-resolved** from the verified token — nothing here is
-client-settable. `emailVerified` in particular is read from the user's verified
-profile, not from a JWT claim: a claim is only true as of when the token was
-minted, so a user who verifies mid-session would keep reporting `false` until
-their token expired.
+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 application roles belong in
+`metadata`, not there.
+
+`emailVerified` is likewise read from the verified profile rather than a JWT
+claim: a claim is only true as of when the token was minted, so a user who
+verifies mid-session would keep reporting `false` until their token expired.
+Profile reads are cached for ~30 seconds, so a change shows up within that
+window, not on the very next request.
+
+## Roles
+
+`auth: { role: "admin" }` gates on the caller's `metadata.role`:
+
+```ts
+@Controller("/admin", { auth: { role: "admin" } })
+export default class AdminController {
+  @Get("/stats")
+  stats(): Promise<Stats> { … }   // only metadata.role === "admin" reaches here
+}
+```
+
+Not signed in → `401`. Signed in with a different (or missing) role → `403`. A
+role gate implies authentication, so the caller is resolved even on a route with
+no `@User()` parameter.
+
+The role is read from the verified profile, not from a claim baked into the
+token, so revoking it takes effect **within ~30 seconds** — the runtime caches a
+verified identity for that long — rather than whenever the token happens to
+expire.
 
 ## Email verification
 
@@ -92,10 +119,14 @@ publish(@User() user: UserT) {
 }
 ```
 
-> There is no per-route `requireVerifiedEmail` option. A route-level flag would
-> have to be enforced by the runtime, and the one-line check above is enforced by
-> your own code — visible where it applies, and impossible to declare on a route
-> and have quietly do nothing.
+Or declare it on the route and let the runtime enforce it:
+
+```ts
+@Controller("/posts", { auth: { verifiedEmail: true } })
+```
+
+Unverified callers get `403 email_not_verified`. Use the route flag to fence a
+whole controller, and the inline check when only part of a handler cares.
 
 ## Password reset and magic links
 

package/docs/llms-full.txt

@@ -680,11 +680,38 @@ interface User {
 }
 ```
 
-Every field is **server-resolved** from the verified token — nothing here is
-client-settable. `emailVerified` in particular is read from the user's verified
-profile, not from a JWT claim: a claim is only true as of when the token was
-minted, so a user who verifies mid-session would keep reporting `false` until
-their token expired.
+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 application roles belong in
+`metadata`, not there.
+
+`emailVerified` is likewise read from the verified profile rather than a JWT
+claim: a claim is only true as of when the token was minted, so a user who
+verifies mid-session would keep reporting `false` until their token expired.
+Profile reads are cached for ~30 seconds, so a change shows up within that
+window, not on the very next request.
+
+## Roles
+
+`auth: { role: "admin" }` gates on the caller's `metadata.role`:
+
+```ts
+@Controller("/admin", { auth: { role: "admin" } })
+export default class AdminController {
+  @Get("/stats")
+  stats(): Promise<Stats> { … }   // only metadata.role === "admin" reaches here
+}
+```
+
+Not signed in → `401`. Signed in with a different (or missing) role → `403`. A
+role gate implies authentication, so the caller is resolved even on a route with
+no `@User()` parameter.
+
+The role is read from the verified profile, not from a claim baked into the
+token, so revoking it takes effect **within ~30 seconds** — the runtime caches a
+verified identity for that long — rather than whenever the token happens to
+expire.
 
 ## Email verification
 
@@ -736,10 +763,14 @@ publish(@User() user: UserT) {
 }
 ```
 
-> There is no per-route `requireVerifiedEmail` option. A route-level flag would
-> have to be enforced by the runtime, and the one-line check above is enforced by
-> your own code — visible where it applies, and impossible to declare on a route
-> and have quietly do nothing.
+Or declare it on the route and let the runtime enforce it:
+
+```ts
+@Controller("/posts", { auth: { verifiedEmail: true } })
+```
+
+Unverified callers get `403 email_not_verified`. Use the route flag to fence a
+whole controller, and the inline check when only part of a handler cares.
 
 ## Password reset and magic links
 

package/package.json

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