@stjoseph/prumo 0.2.0 → 0.4.0

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

@@ -2,71 +2,63 @@
 
 ## 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.
 
-Pin every Better Auth package to one version, and declare `@better-auth/core` as a direct dependency at that
-version: `better-auth`, `auth` and every `@better-auth/*` plugin, in the api and in every client. Upgrade them in
-one change, never one package at a time.
+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`.
 
-## Rationale
-
-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.
+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`.
 
-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.
+## Rationale
 
-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.
+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.
 
-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.
+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.
 
-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.
+The decoy hash is there because the time a sign-in takes would otherwise say which emails have an account.
 
-`better-auth` pins its core exactly, but each plugin only asks for a compatible core as a peer. Without a
-direct `@better-auth/core`, pnpm satisfies that peer with the newest core on the registry, so a core release
-installs a second core beside the pinned one, and the plugins stop typechecking against it. One version and
-a declared core leave pnpm a single core to install.
+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. Email
+verification, password reset and social sign-in are questions `prumo new` asks; a project that answered no to
+them has none of them until they are 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
 
@@ -77,22 +69,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.
-
-**Typecheck.** Two cores in one project usually fail `pnpm typecheck` in `src/infra/auth/`.
+**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 an upgrade moves the whole Better Auth family, `@better-auth/core` included. And that
-each `public: true` is deliberate: the one mistake that is invisible at runtime, because
+**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

@@ -56,10 +56,10 @@ behaviour) holds unchanged. **What it costs:** two runners in one workspace with
 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.
+is **asynchronous** and its matchers need no setup. `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. And `jest-expo` leaves the app manifest empty, so `expo-linking` cannot
+know the app's scheme: a test that reaches `Linking.createURL` mocks it with the scheme it expects.
 
 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/email/codes.md

@@ -0,0 +1,62 @@
+# Email codes
+
+## Rule
+
+Confirm an email address and reset a password with a **6-digit code** sent by mail, never a link. One flow
+serves the web and the mobile app alike.
+
+Keep one live code per user and purpose (`verify-email`, `reset-password`) in `email_code`. A code lives
+**15 minutes** and allows **5 attempts**; the fifth wrong one kills it. Sending another replaces it, and the old
+one stops working. Store only its HMAC-SHA256, keyed with `JWT_SECRET`.
+
+Open no session at sign-up: answer `201 { verificationRequired: true }` and send the code. Refuse sign-in to an
+unconfirmed account with **403** and `code: 'email_not_verified'`, and only after the password matched. Sign
+the user in when the code is confirmed.
+
+On a password reset, set the new password, mark the email confirmed, and revoke every session of the user before
+starting a new one.
+
+Answer `/email/verification` and `/password/forgot` with 204 whether or not the email has an account, and a
+wrong code, a dead one and an unknown email with the same `422 invalid_code`.
+
+Read the outcome of a sign-up and of a refused sign-in in the client: `verificationRequired` and
+`email_not_verified` both lead to the code screen, which offers to send a new code.
+
+## Rationale
+
+A link needs a page to open: easy on the web, and a deep link with universal links on mobile. A code is typed
+the same way everywhere, so there is one flow, one set of screens and one set of tests.
+
+Six digits are a million possibilities, which is why the attempts are counted and the lifetime short: five
+guesses against a million cannot succeed by luck. The hash is keyed because a million codes hash in a moment,
+so an unkeyed digest in a database copy would give every live code away.
+
+Every answer that could say whether an email has an account says the same thing instead, so these routes cannot
+be used to find out who signed up. Asking for confirmation only after the password matched keeps that true at
+sign-in too.
+
+A reset revokes every session because whoever knew the old password may have opened one, and the reset is often
+the reaction to exactly that.
+
+## Applies to
+
+`src/domain/auth/` for the codes, `auth-email.controller.ts`, and the code, forgot-password and reset-password
+screens on the web and mobile.
+
+## Examples
+
+```
+✅  POST /api/auth/password/forgot  → 204 for any email
+❌  POST /api/auth/password/forgot  → 404 "no account with this email"
+
+✅  sign-in with the right password, unconfirmed → 403 email_not_verified
+❌  sign-in, unconfirmed, before checking the password → 403        // tells anyone the account exists
+```
+
+## Enforcement
+
+**Tests.** `email.use-case.spec.ts` covers the dead code after five guesses, the replaced code, the unknown email
+and the reset revoking sessions. `auth-email.controller.spec.ts` covers the HTTP answers, and the clients'
+`email-flows.spec.tsx` the screens.
+
+**Review only.** That a new mail with a code goes through `IssueEmailCodeUseCase`, so it keeps the same limits.

package/.prumo-templates/email/mailer.md

@@ -0,0 +1,47 @@
+# Mailer
+
+## Rule
+
+Send every email through the `Mailer` port in `src/domain/auth/ports/mailer.port.ts`. A use case composes the
+`Mail` (`to`, `subject`, `text`) and hands it over; nothing else in the domain knows how mail travels.
+
+Keep `LogMailer`, which writes each mail to the API's log, as the adapter until the project sends real mail.
+Read a code during development from that log.
+
+To send real mail, write a second adapter under `src/infra/email/` and register it in `email.di.ts` in place of
+`LogMailer`, for production only. Either speak SMTP, with `nodemailer` and an `SMTP_URL` any provider accepts, or
+call a provider's HTTP API. Validate the new variable in `env.ts`.
+
+In a test, register a `FakeMailer` and read the code from it, as `test/support/test-app.ts` does.
+
+## Rationale
+
+Sending mail needs an account with somebody, and choosing one is a commercial decision the project's owner
+makes, not the template. So the template ships the port and an adapter that needs nothing, and the flows that
+depend on mail work end to end from the first `pnpm dev`: the code is in the terminal.
+
+The port is the whole contract on purpose. SES, Postmark, Resend, Mailgun and a company relay all accept the
+same three fields, so changing provider is one new adapter and one line in the container.
+
+**What this costs:** until an adapter is written, a deployed API sends nothing, and a user waiting for a code
+never receives it. Nothing warns about that but this document.
+
+## Applies to
+
+Every email the API sends, now and later: codes, invitations, receipts.
+
+## Examples
+
+```
+✅  await this.mailer.send({ to, subject, text })
+❌  await fetch('https://api.provider.example/send', …)     // inside a use case
+
+✅  container.register(MAILER, { useValue: new SmtpMailer(env) })   // production adapter
+❌  if (env.NODE_ENV === 'production') { … }               // inside LogMailer
+```
+
+## Enforcement
+
+**Tests.** The suite reads every code through `FakeMailer`, so a flow that stops sending mail fails.
+
+**Review only.** That production registers a real adapter. `LogMailer` in production loses mail silently.

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

@@ -2,21 +2,41 @@
 
 ## 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
 `authInfo.extra.userId`.
 
-Write a module's tools in `src/infra/mcp/tools/<module>.tool.ts`. A tool resolves a use case and calls
-`execute()`, exactly as a route handler does. Take its input schema from the module's `dto/`, and pass its
+Write a module's tools in `src/infra/mcp/tools/<module>.tool.ts`, with the scope each one needs beside it:
+`<module>:read` to read the module's data, `<module>:write` to change it. Add the module's two scopes to
+`SCOPES` in `mcp.scopes.ts`, worded for a person, and its tools to `TOOL_SCOPES`. A tool resolves a use case and
+calls `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.
+- Grant the scopes the client asked for, all of `SCOPES` when it asked for none, and refuse an unknown one with
+  `invalid_scope`. Carry them in the session, its access token and every refresh. Advertise them in both metadata
+  documents and in the 401.
+- Refuse a `tools/call` the token's scopes do not cover before the server runs it: 403 with
+  `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`, every scope the call needs in one challenge.
+- 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 +48,26 @@ 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.
+
+Scopes are per module and per kind of access because a client that only reads should not be able to change
+anything, and because a list worded per tool would grow past what a consent page can make readable. The call is
+refused at the HTTP edge, with the scopes it needs, because that is the answer MCP's step-up flow reads: the
+client asks the user for more and comes back.
+
+**What this costs:** a new module's tools need their scopes written in two places, the tool file and
+`mcp.scopes.ts`.
 
 ## 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 +77,19 @@ 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` fails when a tool the server lists has no scope in `TOOL_SCOPES`, lets a
+read-only token read and refuses its write with `insufficient_scope`,
+keeps the scope through a refresh, and refuses an unknown scope. It also 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.