@palbase/backend 39.1.0 → 39.1.2

package/docs/README.md

@@ -265,6 +265,35 @@ group these into namespaced calls — `pb.todos.list()`, `pb.todos.create(...)`,
 `pb.todos.get(id:)`. Rename the class or the method and the operationId (and the
 generated client surface) changes; the verb/path do not affect it.
 
+### What the CLI writes into your repository
+
+ONE directory, and everything in it is committed:
+
+```text
+palbase/
+  project.json              which project this checkout is bound to
+  palbase-env.d.ts          generated from your db/*.ts — types Database.public.*
+  .gitattributes            marks the generated files so they stay out of review diffs
+  environments/
+    local/                  the stack `palbase start` runs on this machine
+      openapi.json          the contract
+      roles.json            the role definitions
+    main/                   the deployed environment, same shape
+```
+
+There is nothing to ignore. Anything that belongs to YOUR MACHINE rather than to
+the project — the stack `palbase start` put in front of you, and the measurement
+`palbase plan` made — lives outside the checkout, beside your credentials in
+`~/.palbase/checkouts/<hash>/`. A repository that had to carry ignore rules for
+generated files is a repository where nobody can see those files drift.
+
+A checkout still holding the retired layout (`.palbase/`, or a `palbase/` with
+`Generated/`, `Config/` or a root `openapi.json` in it) is REFUSED by
+`palbase link`, which names what it found. There is no migration: a tree holding
+both layouts carries two contracts and two clients, and nothing can say which one
+a build read. Delete the old files, commit that deletion, and link again —
+everything there is regenerated from the project.
+
 ### CLI workflow
 
 - `palbase build` — validate the tree locally exactly the way a deploy would

package/docs/auth.md

@@ -5,6 +5,26 @@ unless it opts out with `auth: false`. Client SDKs attach the user's token
 automatically, so on the backend you declare what a route needs and inject the
 user.
 
+## Temporary verification failures
+
+An absent or invalid access token produces `401 unauthorized` on a protected
+route. If the runtime cannot retrieve a usable signing keyset, it instead
+returns `503 auth_unavailable`. A network failure, an unsuccessful JWKS response,
+or a keyset with no usable signing keys is an availability failure, not evidence
+that the caller's token is invalid. Keep the session and retry after the service
+recovers; signing in again is not required while the token remains valid.
+
+The same rule applies to upload authorization. Requests that cannot be verified
+do not reach the handler or the database, and uploads receive no grant. Public
+requests without credentials continue to work.
+
+Known signing keys remain usable within their trust TTL (five minutes by
+default). Expired keysets are not trusted during an outage. Concurrent refreshes
+share one request, and failed refreshes and unknown key IDs share a one-second
+retry interval so recovery and key rotation do not wait for the entire TTL.
+
+## Declaring authentication
+
 ```ts
 import { Controller, Get, Post, Body, User, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";

package/docs/llms-full.txt

@@ -273,6 +273,35 @@ group these into namespaced calls — `pb.todos.list()`, `pb.todos.create(...)`,
 `pb.todos.get(id:)`. Rename the class or the method and the operationId (and the
 generated client surface) changes; the verb/path do not affect it.
 
+### What the CLI writes into your repository
+
+ONE directory, and everything in it is committed:
+
+```text
+palbase/
+  project.json              which project this checkout is bound to
+  palbase-env.d.ts          generated from your db/*.ts — types Database.public.*
+  .gitattributes            marks the generated files so they stay out of review diffs
+  environments/
+    local/                  the stack `palbase start` runs on this machine
+      openapi.json          the contract
+      roles.json            the role definitions
+    main/                   the deployed environment, same shape
+```
+
+There is nothing to ignore. Anything that belongs to YOUR MACHINE rather than to
+the project — the stack `palbase start` put in front of you, and the measurement
+`palbase plan` made — lives outside the checkout, beside your credentials in
+`~/.palbase/checkouts/<hash>/`. A repository that had to carry ignore rules for
+generated files is a repository where nobody can see those files drift.
+
+A checkout still holding the retired layout (`.palbase/`, or a `palbase/` with
+`Generated/`, `Config/` or a root `openapi.json` in it) is REFUSED by
+`palbase link`, which names what it found. There is no migration: a tree holding
+both layouts carries two contracts and two clients, and nothing can say which one
+a build read. Delete the old files, commit that deletion, and link again —
+everything there is regenerated from the project.
+
 ### CLI workflow
 
 - `palbase build` — validate the tree locally exactly the way a deploy would
@@ -795,6 +824,26 @@ unless it opts out with `auth: false`. Client SDKs attach the user's token
 automatically, so on the backend you declare what a route needs and inject the
 user.
 
+## Temporary verification failures
+
+An absent or invalid access token produces `401 unauthorized` on a protected
+route. If the runtime cannot retrieve a usable signing keyset, it instead
+returns `503 auth_unavailable`. A network failure, an unsuccessful JWKS response,
+or a keyset with no usable signing keys is an availability failure, not evidence
+that the caller's token is invalid. Keep the session and retry after the service
+recovers; signing in again is not required while the token remains valid.
+
+The same rule applies to upload authorization. Requests that cannot be verified
+do not reach the handler or the database, and uploads receive no grant. Public
+requests without credentials continue to work.
+
+Known signing keys remain usable within their trust TTL (five minutes by
+default). Expired keysets are not trusted during an outage. Concurrent refreshes
+share one request, and failed refreshes and unknown key IDs share a one-second
+retry interval so recovery and key rotation do not wait for the entire TTL.
+
+## Declaring authentication
+
 ```ts
 import { Controller, Get, Post, Body, User, OptionalUser } from "@palbase/backend";
 import type { UserT } from "@palbase/backend";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "39.1.0",
+  "version": "39.1.2",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
@@ -110,7 +110,7 @@
     "typescript": "^5.7.0",
     "unplugin-swc": "^1.5.11",
     "vitest": "^3.0.0",
-    "@palbase/core": "^2.4.1"
+    "@palbase/core": "^2.4.2"
   },
   "publishConfig": {
     "access": "public",