@stjoseph/prumo 0.1.1 → 0.3.0

package/.prumo-templates/api/auth.md

@@ -2,62 +2,62 @@
 
 ## Rule
 
-Mount Better Auth at `/api/auth/*` with the catch-all route in `src/infra/http/controllers/auth.controller.ts`,
-which rebuilds the request for `auth.handler`, as Better Auth's Fastify guide does. Mark it
-`config: { public: true }`.
+Keep authentication in the `auth` module, as any other module: `User` and `Session` in `entities/`, the
+password hasher, the access tokens and the opaque tokens in `ports/`, one use case per action. Their adapters
+live in `src/infra/auth/`. No authentication library owns a table, a route or a migration.
 
-Every route is protected by the global `preHandler` hook in `src/infra/http/hooks/auth.hook.ts`. Mark a route
-that needs no session with `config: { public: true }`; that means only *do not answer 401*, and the session is
-still read.
+Serve `POST /api/auth/sign-up`, `sign-in`, `refresh` and `sign-out`, and `GET /api/auth/session`, from
+`auth.controller.ts`. Answer their errors as every route does, in problem+json.
 
-Read the user in the handler with `currentUser(request)` and pass its id to the use case as an argument. A use
-case never reads the request or any ambient session.
+Issue an access token as a JWT valid for **15 minutes**, signed with `HS256` from `JWT_SECRET`, and name the
+algorithm when verifying it. Issue the refresh token as an opaque `<sessionId>.<secret>`, store only its
+SHA-256, and **rotate it on every use**. A token from an earlier rotation revokes its session; the one replaced
+less than ten seconds ago answers 409 instead, and revokes nothing.
 
-Keep Better Auth's tables in their own Postgres schema, `auth`, on their own connection, migrated by its own
-CLI from the compiled `dist/infra/auth/auth.cli.js`, before our migrations. `pnpm db:migrate` does both, in
-that order.
+Hash passwords with Argon2id through `@node-rs/argon2`, at the library's defaults. When the email is unknown,
+still verify the password against a decoy hash, and answer exactly as for a wrong password.
 
-Set `advanced.database.generateId` to `'uuid'`. Reference `auth.user(id)` from an application table with a
-real foreign key and `ON DELETE RESTRICT`, declared in its schema as a to-one relation to `AuthUser` with
-`mapToPk: true`, so the domain still holds a plain `userId`. `AuthUser`, in `auth-user.schema.ts`, maps only
-the id and is the one Better Auth table the ORM knows. Keep `schemaGenerator.ignoreSchema: ['auth']` and
-`skipTables: ['auth.user']` in `mikro-orm.factory.ts`. Better Auth's tables follow Better Auth's conventions,
-not `database/entities.md`.
+Give the web its tokens in `httpOnly`, `SameSite=Lax` cookies: the access cookie on `/`, the refresh cookie only
+on `/api/auth/refresh`, both `Secure` when `API_URL` is https. Give a native client its tokens in the body, and
+only when it sends `X-Auth-Transport: bearer`; it then sends `Authorization: Bearer`. Refuse with 403 any
+request that changes state, carries a cookie and no bearer, and does not come from `WEB_ORIGIN`.
 
-Create what the application keeps about a user in `databaseHooks.user.create.after`, through a use case:
-`src/infra/di/index.ts` passes the hook into `createAuth`.
+Every route is protected by the global `preHandler` hook in `auth.hook.ts`. Mark a route that needs no session
+with `config: { public: true }`; that means only *do not answer 401*, and the token is still read. Read the
+user in the handler with `currentUser(request)` and pass its id to the use case as an argument. A use case
+never reads the request.
 
-## Rationale
+Create a user and the application's own row for it in one use case, inside one transaction: `SignUpUseCase`
+creates the `User` and calls `CreateProfileUseCase`.
+
+Limit the routes that take a password with `@fastify/rate-limit`, through the route's own
+`config.rateLimit`. The plugin is registered with `global: false`.
 
-The route sits inside Fastify, so the request id and the logs cover the authentication flow. **The error
-handler does not:** Better Auth writes its own responses, so an authentication error arrives as
-`{ message, code }`, not as problem+json. The client converts it; the server does not rewrite another
-library's responses.
+## Rationale
 
-Protected is the default because of the asymmetry between the two mistakes. A route someone forgot to
-protect is open, and nothing breaks. A route someone forgot to mark public answers 401 on the first call and
-is fixed in seconds.
+Authentication is part of the product's data, so it follows the product's rules: one database, one connection,
+one migration tool, and a domain that names what it needs through ports. Nothing has to be adapted to a
+library's tables, ids or responses, and the user is an entity the ORM knows like any other.
 
-The user arrives as an argument so a use case's signature says what it needs, and its test passes an id
-instead of building a request.
+An access token is checked by its signature alone, so no request touches the database to accept one, and
+nothing can revoke one before it expires. Fifteen minutes bounds that. The refresh token is what can be
+revoked, so it lives in the database, and rotation makes a stolen copy detectable: whoever presents an old one
+is not the client that rotated it, and the session ends for both. The ten seconds exist because two tabs
+refreshing at once both present the same token, and the second must not sign the user out.
 
-Better Auth's ids are `text` by default, which no `uuid` column can reference; `generateId: 'uuid'` fixes
-that. What stays different is not ours to fix: camelCase columns and `gen_random_uuid()`. Rewriting another
-library's schema fights its CLI on every upgrade. Better Auth's migrations run first because an application
-table references its tables.
+The decoy hash is there because the time a sign-in takes would otherwise say which emails have an account.
 
-The ORM compares its entities with everything in the database, so without `ignoreSchema` it reads Better
-Auth's tables as leftovers and every generated migration drops them, with every login in them. The foreign
-key is declared rather than written by hand in a migration because the ORM would otherwise drop that too,
-every time. `AuthUser` exists only as that anchor.
+A cookie no script can read is a token an injected script cannot take, which is why the web never receives
+one in a body. A cookie is also sent by the browser whoever wrote the page, which is what the Origin check
+answers: a request leaning on a cookie must come from the web app. A native app has no cookie jar and no
+Origin, so it carries a bearer and passes.
 
-**The sign-up hook is not atomic:** the user and the application's row are written over two connections, so
-a failure between them leaves a user without a profile. The result is a visible 404, not corrupted data. And
-the foreign key means deleting a user fails while rows reference it, so the application removes them first.
+**What this costs:** the security of sign-in is this code's. There is no upstream fix to wait for, and no
+reset of a password, verification of an email or social sign-in until one is written.
 
 ## Applies to
 
-Every route, every use case that acts for a user, and `src/infra/auth/`, where Better Auth is built.
+Every route, every use case that acts for a user, `src/domain/auth/`, and `src/infra/auth/`.
 
 ## Examples
 
@@ -68,19 +68,21 @@ Every route, every use case that acts for a user, and `src/infra/auth/`, where B
 ✅  execute(currentUser(request).id)
 ❌  execute(request)
 
-✅  userId: { kind: 'm:1', entity: () => 'AuthUser' as never, mapToPk: true, deleteRule: 'restrict' }
-❌  userId: { type: 'uuid' }                         nothing stops an orphan
+✅  jwtVerify(token, key, { algorithms: ['HS256'], issuer, audience })
+❌  jwtVerify(token, key)                         the token chooses its own algorithm
+
+✅  sessions store sha256(secret)
+❌  sessions store the refresh token
 ```
 
 ## Enforcement
 
 **Boot.** The hook is global, so a route is unprotected only by an explicit `public: true`.
 
-**Tests.** `users.controller.spec.ts` signs up through the real route and proves 401 without a session.
-`mikro-orm.factory.spec.ts` asserts that a migrated database leaves the schema generator nothing to change,
-so a configuration that would drop Better Auth's schema, or the foreign key, fails the suite.
-
-**The database.** A row referencing a user that does not exist is refused.
+**Tests.** `auth.controller.spec.ts` covers both transports, rotation, the Origin check, 401, 409, 400 and the
+rate limit. `refresh-session.use-case.spec.ts` proves that a replayed token revokes the session and that one
+just rotated does not. `jose-access-tokens.adapter.spec.ts` refuses an expired token, another secret, another
+issuer, an unsigned token and another algorithm.
 
 **Review only.** That each `public: true` is deliberate: the one mistake that is invisible at runtime, because
 the route works, for everyone.

package/.prumo-templates/api/config.md

@@ -33,7 +33,7 @@ bodies; a process environment legitimately carries `PATH`, `HOME` and whatever t
 exception is written down so nobody harmonises it later.
 
 **The file is loaded by `loadEnv()` rather than by the server** because the server is not the only entry
-point: the ORM's CLI and Better Auth's CLI both read the configuration without starting it. Node's
+point: the ORM's CLI reads the configuration without starting it. Node's
 `--env-file` would work without code, but it has to be typed on every command. One function every entry
 point calls keeps one policy, including *never in production*.
 
@@ -47,7 +47,7 @@ point calls keeps one policy, including *never in production*.
 ✅  constructor(@inject(ENV) private readonly env: Env) {}
 ❌  const url = process.env.DATABASE_URL
 
-✅  Invalid environment: DATABASE_URL, BETTER_AUTH_SECRET
+✅  Invalid environment: DATABASE_URL, JWT_SECRET
 ❌  DATABASE_URL is invalid: postgres://admin:hunter2@prod-db/app
 ```
 

package/.prumo-templates/api/routes.md

@@ -3,8 +3,9 @@
 ## Rule
 
 Serve every route at `/api/v<n>/<resource>`: register each controller with
-`prefix: '/api/v<n>/<resource>'`. Better Auth's `/api/auth/*`, `/api/health/*` and `/api/docs` are the only
-routes outside a version.
+`prefix: '/api/v<n>/<resource>'`. `/api/auth/*`, `/api/health/*` and `/api/docs`, and with MCP `/api/mcp`,
+`/api/oauth/*` and `/.well-known/*`, are the only routes outside a version. They answer with the statuses their
+own contracts set.
 
 Name resources in the plural, kebab-case for compound words. Use REST verbs. A `POST` answers `201`
 through `reply.code(201)`; every other method answers `200`.
@@ -28,8 +29,9 @@ Serve the documentation UI outside production only.
 
 ## Rationale
 
-The prefix makes Better Auth's `/api/auth/*` fall out of the ordinary convention instead of becoming the
-one route with an exception in its path.
+The prefix makes the authentication and protocol routes fall out of the ordinary convention instead of each
+becoming the one route with an exception in its path. They stay outside a version because what shapes them is
+what they implement, OAuth's discovery above all, whose addresses are fixed by its RFCs.
 
 Versioning costs five characters today and a coordinated migration of every consumer later, including a
 published mobile app that does not update when you want it to. It goes in the URI rather than a header

package/.prumo-templates/api/structure.md

@@ -17,7 +17,8 @@ folders, each created with its first file:
 | Folder | Holds | File |
 |---|---|---|
 | `entities/` | A plain class with the data and the behaviour of one entity | `<name>.entity.ts` |
-| `repositories/` | The port: an interface and its `Symbol` token, in one file | `<name>.repository.ts` |
+| `repositories/` | The port to persistence: an interface and its `Symbol` token, in one file | `<name>.repository.ts` |
+| `ports/` | Any other port, such as a password hasher or a token signer: an interface and its `Symbol` token | `<name>.port.ts` |
 | `use-cases/` | One class per use case, with one `execute()` method | `<verb>-<noun>.use-case.ts` |
 | `dto/` | Zod schemas and their inferred types, input and output | `<name>.dto.ts` |
 | `errors/` | Classes extending `DomainError` | `<name>.error.ts` |
@@ -94,6 +95,8 @@ A module:
     domain/users/repositories/profile.repository.ts        interface + PROFILE_REPOSITORY
     domain/users/use-cases/update-profile.use-case.ts
     domain/users/dto/update-profile.dto.ts
+✅  domain/auth/ports/password-hasher.port.ts              interface + PASSWORD_HASHER
+❌  domain/auth/repositories/password-hasher.repository.ts  stores nothing
 ❌  domain/users/users.service.ts                           every case in one class
 ❌  domain/users/profile.ts                                 no role suffix
 ```

package/.prumo-templates/client/data.md

@@ -3,15 +3,15 @@
 ## Rule
 
 Keep the wire contract with the project's API in `src/api-contract/`: `createClient`, which builds every URL
-including the `/api/v1` prefix, the `ApiError`, the hand-written request and response types, and the query
-factories. **Let the app inject the transport** (`createClient({ baseUrl, fetch })`) with
-`credentials: 'include'` on the web configured there, once. In a monorepo the same directory is
-`packages/api-contract`.
+including the `/api/v1` prefix, the `ApiError`, the hand-written request and response types, the query
+factories, and `createAuthClient` with `sessionQuery`. **Let the app inject the transport**
+(`createClient({ baseUrl, fetch })`) with `credentials: 'include'` on the web configured there, once. In a
+monorepo the same directory is `packages/api-contract`.
 
-Call Better Auth's routes through Better Auth's own client, `createAuthClient`, configured once. In `mobile`, give it
-the `expoClient` plugin, and let the transport for the project's API attach the session with `auth.getCookie()` and
-send `credentials: 'omit'`. Do not write
-its routes, bodies or responses by hand, and do not send them through the wrapper.
+Build the auth client once, and give the API client its `fetch`: `createClient({ baseUrl, fetch: auth.fetch })`.
+That fetch refreshes once on a 401 and repeats the request, with one refresh for every request refused at
+once. The web passes no token store and lives on its cookies. `mobile` passes a `TokenStore` over
+`expo-secure-store`, which makes the client ask for bearer tokens and send them.
 
 Declare request and response types by hand, in `api-contract/`. Do not generate a client
 from the OpenAPI document, and **do not `import type` an entity from the API package**; see below.
@@ -21,8 +21,8 @@ function travel together. Include in the key everything that changes the result:
 ordering.
 
 Let the client parse every `application/problem+json` body into one `ApiError` carrying `status`,
-`title`, `detail`, `requestId` and the `errors` map, and throw it. Convert the auth client's `error` into the
-same `ApiError` in one adapter. No component reads a raw error body.
+`title`, `detail`, `requestId` and the `errors` map, and throw it. The auth routes answer the same way. No
+component reads a raw error body.
 
 Use `useInfiniteQuery` for paginated lists, with `getNextPageParam` returning `nextCursor`, or `undefined`
 once it is null.
@@ -55,12 +55,10 @@ difference between their keys fills one cache entry while the other is read, pay
 nothing, with no warning. A key that omits a filter is the same class of fault: two screens share one
 entry and the second shows the first's data.
 
-**There are two doors because there are two contracts.** The project's API is ours, so its types are written
-here. Better Auth's routes are Better Auth's: hand-writing them would copy a contract we do not control, which
-drifts on every upgrade and grows with every plugin. Its client already carries those types and follows the
-library, and `multi-tenancy/client.md` depends on it. **Its errors are not problem+json**: `toNodeHandler`
-writes the response itself, past the exception filter, so the body is `{ message, code }` with no `requestId`.
-The adapter is what keeps that difference out of every form.
+**The auth client is the one door every request goes through.** An access token lasts fifteen minutes, so any
+request can meet a 401 that a refresh would answer. Doing that once, in the transport, means no screen knows
+tokens expire. Several requests refused together share one refresh, because a second would present a token the
+first has already rotated, and the API would read that as theft.
 
 One `ApiError` keeps the shape of problem+json in a single file instead of in every component that
 displays an error. It also puts `requestId` on every failure without anyone asking, which is what makes a
@@ -92,8 +90,8 @@ The query factory:
 Reaching the server:
 
 ```
-✅  api.get('/users/me')                         authClient.signIn.email({ email, password })
-❌  api.post('/auth/sign-in/email', { … })       // Better Auth's contract, copied by hand
+✅  createClient({ baseUrl, fetch: auth.fetch })     // refreshed and repeated on a 401
+❌  createClient({ baseUrl, fetch })                 // the first expired token signs the user out
 ```
 
 Reading an error:

package/.prumo-templates/client/forms.md

@@ -13,8 +13,8 @@ field. **Turn anything that matches no field into a form-level error**, shown at
 `requestId`. Do it through one function in `features/forms/`, which sets the form-level error on
 `root.server`.
 
-Show an error carrying no field the same way: form-level, with `title` and the `requestId`. **Every
-authentication error is this case**: Better Auth's errors carry no field map.
+Show an error carrying no field the same way: form-level, with `title` and the `requestId`. A wrong password
+is this case: the API names no field, so as not to say whether the email exists.
 
 Disable the submit button while `isSubmitting`. Never clear the form on error.
 

package/.prumo-templates/core/testing.md

@@ -55,11 +55,10 @@ been published since January 2024. Every other rule here (placement, no database
 behaviour) holds unchanged. **What it costs:** two runners in one workspace with near-identical APIs, so `vi.fn`
 written in a mobile test is a mistake an assistant will make.
 
-**Three things a mobile test meets, verified with Expo SDK 57:** `render` from `@testing-library/react-native` 14
-is **asynchronous** and its matchers need no setup. `jest-expo` leaves the app manifest empty, which Better Auth's
-Expo plugin needs to build an origin, so a component test uses a Better Auth client without that plugin, which is
-why a form asks only for the auth methods it calls. And Better Auth ships ESM, partly as `.mjs`, so Jest extends
-`jest-expo`'s own transform settings to include it rather than restating them.
+**Two things a mobile test meets, verified with Expo SDK 57:** `render` from `@testing-library/react-native` 14
+is **asynchronous** and its matchers need no setup. And `expo-secure-store` needs the native Keychain or Keystore,
+which Jest does not have, so a test builds the auth client with an in-memory token store, which is why a form
+asks only for the auth methods it calls.
 
 A coverage threshold turns a proxy into a target. Whoever is below writes tests to raise the number rather
 than to check anything; whoever is above stops thinking. With no database mocks a test costs more to write,

package/.prumo-templates/database/testing.md

@@ -6,10 +6,9 @@ Start one Postgres container per test run with Testcontainers. Give each Vitest
 inside it. Never point a test at a shared or long-lived database.
 
 Build the schema by running the migrations, once per worker database. Do not use the schema generator.
-Run Better Auth's migrations first, through its programmatic `getMigrations`, then ours.
 
-Truncate every table between tests, in a single `TRUNCATE` statement listing them all, Better Auth's
-included. Do not wrap a test in a transaction and roll it back.
+Truncate every table between tests, in a single `TRUNCATE` statement listing every entity's table, read from
+the ORM's metadata. Do not wrap a test in a transaction and roll it back.
 
 Create test data with a factory per entity: a function returning a valid row from defaults and
 accepting overrides. Do not keep a shared fixture file.
@@ -35,11 +34,10 @@ inside one turns the code's transaction into a savepoint, which behaves differen
 never exercised. Testing a lock inside a wrapper that will roll back tests something adjacent to the
 truth.
 
-Better Auth's migrations run first for the same reason they do in production: an application table
-references `auth.user`, so its foreign key cannot be created before the table exists. Its tables are in the
-truncation for the mirror reason: leave them out and the next test's factory collides with a user the
-previous test created. A factory for such a table creates the user first; Better Auth's tables have no entity
-here, so that insert is raw SQL, with its one-line reason.
+The list comes from the metadata so that a new entity is truncated without anyone remembering to add it. Read
+it as the `Map` it is: `Object.values()` on it is empty, and a suite once passed for months truncating nothing,
+saved only by a cascade from tables it no longer has. A factory for a table that references a user creates the
+user first, through the user's own factory.
 
 Factories rather than a fixture file, because a fixture grows until a test depends on user number twelve
 having a particular plan, and then neither can be changed alone. A factory call states what the scenario

package/.prumo-templates/mcp/server.md

@@ -2,10 +2,10 @@
 
 ## Rule
 
-Serve MCP at `POST /api/mcp`, in `src/infra/http/controllers/mcp.controller.ts`. Protect it with
-`requireMcpAuth` from `@better-auth/mcp`, with the same `resource` as `mcp()` in `auth.factory.ts`:
-`mcpResource(env)`. The route is `public: true` for the session hook, because it answers a bearer access
-token, never a cookie.
+Serve MCP at `POST /api/mcp`, in `src/infra/http/controllers/mcp.controller.ts`. Accept only a bearer access
+token whose audience is `mcpResource(env)` and which names a client; answer anything else with 401 and a
+`WWW-Authenticate` naming `resource_metadata`. The route is `public: true` for the session hook, because the
+audience decides, not the session.
 
 Build the server per request in `src/infra/mcp/mcp.server.ts` with `createMcpHandler` from
 `@modelcontextprotocol/server`, `legacy: 'reject'`. The user is the token's `sub`, passed through
@@ -15,8 +15,21 @@ Write a module's tools in `src/infra/mcp/tools/<module>.tool.ts`. A tool resolve
 `execute()`, exactly as a route handler does. Take its input schema from the module's `dto/`, and pass its
 result through the module's output schema with `.parse()` before returning it.
 
-Keep Better Auth the authorization server: `jwt()`, `mcp()` and `cimd()` in `auth.factory.ts`, discovery at
-`/.well-known/*`, sign-in and consent on the web app. Do not enable dynamic client registration.
+Keep the authorization server in the `oauth` module and `oauth.controller.ts`, following MCP's 2026-07-28
+authorization profile:
+
+- Publish protected resource metadata (RFC 9728) at `/.well-known/oauth-protected-resource/api/mcp` and at the
+  root, and server metadata (RFC 8414) at `/.well-known/oauth-authorization-server`.
+- Identify a client by its metadata document (CIMD) only. Do not enable dynamic client registration.
+- Check the client and its redirect URI, by exact match, before any error may be redirected.
+- Require PKCE with `S256`, and a `resource` equal to `mcpResource(env)`, which becomes the token's audience.
+- Send the browser to the web app's `/consent`. Show the client's name, the host of its `client_id` and the
+  host of its redirect URI, and warn when that redirect returns to this device.
+- Return the code with `iss` (RFC 9207), and spend it once: a code presented twice revokes the session its
+  first exchange started.
+- Rotate refresh tokens, and accept one only from the client it was issued to.
+- Fetch a metadata document over https only, at most 5 KB and 5 seconds, following no redirect, and never from
+  a private, loopback or link-local address, checked at the connection's own lookup.
 
 ## Rationale
 
@@ -28,13 +41,21 @@ obeys.
 list and MCP does not: a tool returns whatever it is handed, so an entity passed straight through publishes
 every column.
 
-`legacy: 'reject'` and CIMD follow the MCP 2026-07-28 profile, which Better Auth's plugin targets. The
-protocol is stateless, so a server per request costs nothing and knows only its caller. Dynamic client
-registration stays off because that profile deprecates it.
+The audience keeps the two kinds of token apart. A token a client obtained for MCP cannot call the API's own
+routes, and the web's own token cannot call MCP.
+
+The client chooses the URL the server fetches, which is what makes CIMD a server-side request forgery risk:
+without the address check, a client could make the API read its own network. The check runs at the
+connection's lookup, so a name that resolves differently a second time cannot slip past it, and a literal
+address is checked before connecting because no lookup happens for one.
+
+**What this costs:** no scopes. A tool acts with everything the user may do, and adding scopes is a change to
+this module and to the consent page.
 
 ## Applies to
 
-`src/infra/mcp/`, `mcp.controller.ts`, the MCP part of `auth.factory.ts`, and the web app's `/consent` route.
+`src/infra/mcp/`, `mcp.controller.ts`, `oauth.controller.ts`, `src/domain/oauth/`, `src/infra/oauth/`, and the
+web app's `/consent` route.
 
 ## Examples
 
@@ -44,11 +65,17 @@ registration stays off because that profile deprecates it.
 
 ✅  structuredContent: profileResponseSchema.parse(profile)
 ❌  structuredContent: profile                       every column leaves
+
+✅  redirectUris.includes(redirectUri)
+❌  redirectUri.startsWith(registeredOrigin)
 ```
 
 ## Enforcement
 
-**Tests.** `mcp.controller.spec.ts` walks the whole authorization, consent included, connects the SDK's
-own client, and asserts a tool returns only the public fields.
+**Tests.** `mcp.controller.spec.ts` walks discovery from the 401, the authorization, consent and the token, then
+connects the SDK's own client and asserts a tool returns only the public fields. It also refuses an unknown
+client without redirecting, a missing or plain PKCE, another resource, a wrong verifier, a code spent twice,
+another client's refresh token, and each token where the other belongs. `https-client-metadata.adapter.spec.ts`
+refuses non-canonical client ids and private addresses.
 
 **Review only.** That a new tool goes through a use case and parses its output.

package/.prumo-templates/mobile/routing.md

@@ -2,7 +2,7 @@
 
 ## Rule
 
-Hold the native splash screen until the session has been read from `expo-secure-store`. Only then let the
+Hold the native splash screen until the session has been read, with the tokens from `expo-secure-store`. Only then let the
 router render the authenticated group or redirect to login.
 
 Express protection with an authenticated layout group. Do not check for a session inside a screen.

package/.prumo-templates/mobile/storage.md

@@ -2,14 +2,15 @@
 
 ## Rule
 
-Put in `expo-secure-store` anything that **grants access if stolen**: the session cookie and any token.
+Put in `expo-secure-store` anything that **grants access if stolen**: the access and refresh tokens, and any
+other token.
 Put everything else in MMKV.
 
 Do not use MMKV's own encryption.
 
 Persist the TanStack Query cache to MMKV with a maximum age.
 
-On logout, clear the session, the persisted cache, and every MMKV key holding that user's data. Leave
+On logout, clear the tokens, the persisted cache, and every MMKV key holding that user's data. Leave
 device preferences (theme, language) untouched.
 
 Decide when writing each key whether it belongs to the user or to the device.
@@ -33,7 +34,7 @@ from one that opens blank with a spinner, which is what happens every time someb
 maximum age exists because a cache without one presents months-old data as current with no way for the
 user to tell.
 
-That persistence is also why logout must clear more than the session: switching users on one device would
+That persistence is also why logout must clear more than the tokens: switching users on one device would
 otherwise show the previous user's data. Wiping MMKV wholesale instead would take theme and language with
 it, so the same person returning finds the app as if it were new; security that punishes the common case
 gets switched off by somebody.
@@ -47,7 +48,7 @@ Every write to persistent storage, and the logout path.
 Choosing a store:
 
 ```
-✅  SecureStore: the session cookie
+✅  SecureStore: the access and refresh tokens
     MMKV:        theme, last opened tab, cached responses
 ❌  MMKV:        the session token        // works perfectly, protects nothing
 ```
@@ -62,8 +63,8 @@ Opening MMKV (version 4):
 Logout:
 
 ```
-✅  clear session + query cache + user-scoped MMKV keys, kept as one list the logout walks
-❌  clear session only
+✅  clear tokens + query cache + user-scoped MMKV keys, kept as one list the logout walks
+❌  clear tokens only
 ❌  MMKV.clearAll()          // takes theme and language too
 ```
 

package/.prumo-templates/monorepo/layout.md

@@ -30,9 +30,9 @@ Dockerfile.
 The integration package exists because the rest of the sharing was already refused: contract types are
 hand-written rather than generated, validation differs on each side, and shadcn copies components rather
 than sharing them. What genuinely repeats across clients is how a URL is built, how an error body becomes
-an `ApiError`, and what the contract's shapes are. Only transport differs (the web sends its cookie
-automatically, mobile attaches it from secure storage, a site's server calls anonymously), so transport
-comes from outside.
+an `ApiError`, what the contract's shapes are, and how an expired access token is refreshed. Only transport
+differs (the web sends its cookies automatically, mobile hands the auth client a store over secure storage, a
+site's server calls anonymously), so transport comes from outside.
 
 **This is also what recovers most of what hand-written types gave up.** That decision accepted, as its
 cost, that a renamed field leaves each client compiling against its own copy. One copy instead of three
@@ -65,7 +65,7 @@ The package's boundary:
 
 ```
 ✅  createClient({ fetch: myTransport })
-❌  the package calling fetch and reading a cookie itself
+❌  the package calling fetch and reading secure storage itself
 ```
 
 ## Enforcement

package/.prumo-templates/multi-tenancy/client.md

@@ -17,7 +17,7 @@ Never read the tenant from local storage or from a cached response to decide wha
 
 The query-key rule already says a key includes everything that changes the result, and the tenant changes
 the result. **But the tenant is invisible to whoever writes the query:** the server derives it from the
-session, so the client never sends it, never passes it as a filter, and never sees it in the calling code.
+access token, so the client never sends it, never passes it as a filter, and never sees it in the calling code.
 Nobody remembers to put it in a key, because nothing in the file suggests it exists. Adding it everywhere
 would be correct when remembered and silent when not; clearing once, in one place, does not depend on
 memory.
@@ -45,10 +45,10 @@ Every client of a multi-tenant project: `web`, `mobile` and `site` alike.
 Switching:
 
 ```
-✅  await organization.setActive({ organizationId })
+✅  await switchTenant(organizationId)                // the API re-issues the access token
     queryClient.clear()
     router.navigate({ to: '/' })
-❌  await organization.setActive({ organizationId })   // cache and route untouched
+❌  await switchTenant(organizationId)                // cache and route untouched
 ```
 
 Query keys:
@@ -78,6 +78,6 @@ client may choose.
 That the active tenant is on screen. Its absence breaks nothing and costs somebody a wrong action in the
 wrong account.
 
-**Known limit:** if the session's tenant changes without this app knowing (another tab switching), the
-cache is not cleared. That follows from the active organization living in the session, and is the cost that
-decision accepted.
+**Known limit:** if the session's tenant changes without this app knowing (another tab switching), this tab
+keeps its access token, and its tenant, until the next refresh, and then its cache is not cleared. That follows
+from the active organization living in the session, and is the cost that decision accepted.

package/.prumo-templates/multi-tenancy/isolation.md

@@ -5,14 +5,16 @@
 Derive the active tenant from the session. **Never from anything the client sends**: not a header, not a
 path parameter, not the `Host`.
 
-Use Better Auth's `organization` plugin with `activeOrganizationId` **persisted in the session**. Do not
-manage the active organization client-side.
+Keep organizations in the `auth` module: an `Organization` entity, and a `Membership` joining a user to one.
+Store the active tenant on the `Session` row, as `active_organization_id`, and copy it into the access token as
+a claim each time one is issued or refreshed. Switch tenants through one route that checks the membership,
+updates the session and issues a new access token. Do not manage the active organization client-side.
 
 Give every tenant-scoped table a `tenant_id` that is `NOT NULL` and carries a foreign key into
 `organization`, with `ON DELETE RESTRICT`.
 
 Register the MikroORM filter with `default: true` and set its parameter once per request, from the
-session.
+verified access token's claim.
 
 **Never accept `tenant_id` as a method argument.** Read it where the filter's parameter is read.
 
@@ -22,7 +24,8 @@ a comment saying it was checked.
 Declare a route that has no tenant. **Treat an absent filter parameter as an error**, never as "no
 filter".
 
-Run Better Auth's migrations before ours.
+When a membership ends, revoke that user's sessions with it, or the departed member keeps the tenant until the
+access token expires.
 
 ## Rationale
 
@@ -32,9 +35,13 @@ forgetting is invisible, because the route works perfectly for someone entitled
 someone who is not. A subdomain is input too: it arrives in a header a client controls and that proxies
 rewrite, so the defence would rest on infrastructure configuration.
 
-Better Auth's own documentation offers managing the active organization client-side, for multiple tabs. For
-a multi-tenant system that means the **tab** decides isolation, so it is refused here by name: somebody
-will find that sentence.
+Keeping the active organization in the client, per tab, is a common suggestion for working in two tenants at
+once. For a multi-tenant system that means the **tab** decides isolation, so it is refused here by name:
+somebody will find that suggestion.
+
+The claim is read from a token whose signature was just verified, so no request touches the database to learn
+its tenant. The cost is the token's lifetime: a membership removed now still reads for up to fifteen minutes,
+unless the sessions go with it, which is why the rule asks for both.
 
 The filter is an application-level guard, and its own documentation says a raw query or a forgotten
 `filters` option reads past it. It leaves three holes and they get different answers, because the problems
@@ -48,8 +55,8 @@ did not load, middleware in the wrong order) into a query that returns the whole
 
 The foreign key exists because without it a `tenant_id` pointing nowhere inserts cleanly and passes tests,
 leaving a row invisible to every filtered query. `RESTRICT` means deleting an organization with business
-data fails, which is wanted: the application should decide what happens to that data rather than a library
-CLI cascading it away.
+data fails, which is wanted: the application should decide what happens to that data rather than a cascade
+deciding for it.
 
 ## Applies to
 
@@ -64,7 +71,7 @@ decision rather than configuration.
 Where the tenant comes from:
 
 ```
-✅  const tenantId = session.activeOrganizationId
+✅  const tenantId = claims.organizationId          // from the verified access token
 ❌  const tenantId = req.headers['x-tenant-id']
 ❌  const tenantId = subdomainOf(req.headers.host)
 ```