@nano-app/backend 0.18.0 → 0.20.0

package/README.md

@@ -48,7 +48,7 @@ export default createRoute({
 
 ## Routes
 
-Each `*.route.ts` under `mainPlugin.routesDir` default-exports an object with the HTTP methods it implements (`GET`, `POST`, `PUT`, `DELETE`, `QUERY`). **The file path is the URL** (`index.route.ts` → `/`, `api/users.route.ts` → `/api/users`). A route file holds only those methods and its options (`expression`, `public`, `permissions`, `callbacks`): any other key, or an invalid value, stops the startup with the file and what is wrong. `expression` is appended to that path as is, in Express syntax (`/:id`, `{/:id}` for optional):
+Each `*.route.ts` under `routesDir` default-exports an object with the HTTP methods it implements (`GET`, `POST`, `PUT`, `DELETE`, `QUERY`). **The file path is the URL** (`index.route.ts` → `/`, `api/users.route.ts` → `/api/users`). A route file holds only those methods and its options (`expression`, `public`, `permissions`, `callbacks`): any other key, or an invalid value, stops the startup with the file and what is wrong. `expression` is appended to that path as is, in Express syntax (`/:id`, `{/:id}` for optional):
 
 ```ts
 export default createRoute({
@@ -84,10 +84,14 @@ Every option is optional.
 | `listener` | `() => {}` | Callback once the server is listening. |
 | `settings` | `{ "trust proxy": <private networks> }` | Values for `app.set()`: see [Client IP](#client-ip). |
 | `packages` | see below | Framework base middlewares. |
-| `mainPlugin` | `{ routesDir: "src/routes" }` | Your routes (`routesDir`, relative to `cwd`), `basePath` (e.g. `/api`, no trailing slash) and database: see [Database](#database). |
-| `plugins` | `[]` | Plugins mounted around your routes, in order: see [Plugins](#plugins). |
+| `routesDir` | `"src/routes"` | Folder of your routes, relative to `cwd`. |
+| `database` | none | Your Drizzle relations and how its tables are applied: see [Database](#database). |
+| `auth` | none | Better Auth options: see [Better Auth](#better-auth). |
+| `plugins` | `{}` | Plugins mounted `before` and `after` your routes, in order: see [Plugins](#plugins). |
 
-`packages` accepts `morgan`, `cors`, `helmet`, `compression`, `express` (`express.json` options) and `urlencoded`. The merge is **per section**: passing one key keeps the others; pass `false` to disable one.
+`packages` accepts `morgan`, `cors`, `helmet`, `rateLimit`, `compression`, `express` (`express.json` options) and `urlencoded`. Each one you set replaces its default whole and the others keep theirs; pass `false` to disable one. `settings` works the same way, key by key.
+
+`rateLimit` is off by default. With `{ capacity, refillPerSecond, message }` (defaults `100`, `1` and a generic message) it limits every request per client IP, Better Auth's endpoints too: each request spends a token of the client's bucket, which refills over time; without one it answers `429` with `message` and `Retry-After`. The addresses of an IPv6 `/56` are one client, and the buckets live in the memory of each process.
 
 `compression` is off by default: the proxy in front of the app (an ingress, nginx) usually compresses the answers. Turn it on with `packages: { compression: true }` when nothing does.
 
@@ -104,7 +108,7 @@ createNanoApp({
 
 ### Client IP
 
-The [`rate-limit` plugin](../plugins/README.md) and Better Auth count each client by its IP. Behind a proxy (the frontend of `@nano-app/frontend`, nginx, a load balancer, a CDN, Tailscale Funnel), the IP of the request is the proxy's: the client's is the last one the proxies appended to `X-Forwarded-For`.
+The [rate limit](#configuration) and Better Auth count each client by its IP. Behind a proxy (the frontend of `@nano-app/frontend`, nginx, a load balancer, a CDN, Tailscale Funnel), the IP of the request is the proxy's: the client's is the last one the proxies appended to `X-Forwarded-For`.
 
 By default the backend reads that header only when the request comes from loopback or a private network (`127.0.0.0/8`, `::1`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`), and takes the last address that is not one of them. A request from a public IP is counted by that IP, whatever header it sends. Better Auth gets the same networks as `advanced.ipAddress.trustedProxies`.
 
@@ -114,7 +118,7 @@ By default the backend reads that header only when the request comes from loopba
 
 ## Database
 
-Off until the app passes its schema: nano-app creates a [Drizzle](https://orm.drizzle.team) client of it on `DATABASE_URL` and passes it to your handlers as `db`. **It never modifies your schemas**: applying them (`drizzle-kit push`, `drizzle-kit generate` and `migrate`) is up to you.
+Off until the app passes its relations: nano-app creates a [Drizzle](https://orm.drizzle.team) client of them on `DATABASE_URL` and passes it to your handlers as `db`. It changes your tables only when you ask: `push` or `migrate`. Without them, applying the schema (`drizzle-kit push`, `drizzle-kit generate` and `migrate`) is up to you.
 
 ```bash
 pnpm add drizzle-orm pg
@@ -133,10 +137,11 @@ export const users = pgTable('users', {
 
 ```ts
 // src/app.ts — DATABASE_URL comes from the environment (or a .env file)
+import { defineRelations } from 'drizzle-orm';
 import { createNanoApp } from '@nano-app/backend';
 import * as schema from './db/schema';
 
-createNanoApp({ mainPlugin: { database: { schema } } });
+createNanoApp({ database: { relations: defineRelations(schema) } });
 ```
 
 ```ts
@@ -148,64 +153,48 @@ export default createRoute({
 });
 ```
 
-- `database.schema` is the module of your tables: every export that is a table, and `relations` (from `defineRelations`) when you relate them. A `pgSchema` the tables use is exported too, so drizzle-kit creates it.
-- One pool serves the app and every plugin with a database. It connects on its first query: a missing table fails that query, not the startup.
+- `database.relations` is what `defineRelations` gives of your tables, with their relations when you relate them. A `pgSchema` the tables use is exported from the module too, so drizzle-kit creates it. The rest of `database` goes to Drizzle as its options.
+- `database.push: true` applies the tables at startup with drizzle-kit's push (`pnpm add drizzle-kit`), only to the Postgres schemas they use. A change that would lose data stops the startup.
+- `database.migrate` is the folder `drizzle-kit generate` writes: its pending migrations are applied at startup. With both, the migrations run first, then the push.
+- One startup at a time changes the database: a Postgres lock covers the migrations and the push of every database, across replicas.
+- One pool serves the app, Better Auth and every plugin with a database. It connects on its first query: a missing table fails that query, not the startup.
 - Startup fails if `DATABASE_URL` is missing.
-- The `nano_` prefix is reserved for plugins: a table of yours in a `nano_*` Postgres schema fails the startup.
+- Each `nano_*` Postgres schema is reserved for the plugin of its name (`nano_auth` for Better Auth): a table of yours in one fails the startup.
 - Without a database, `db` is `undefined`.
 - Drizzle and pg are loaded only when your database or a mounted plugin's is on.
 
 ## Better Auth
 
-Users, sign-in and sessions with [Better Auth](https://www.better-auth.com), on your database. On when your app has `src/auth.ts` (or the built `src/auth.js`), relative to `cwd`: its default export holds the options in `options` (everything but `database`: nano-app passes your Drizzle client and schema). Without the file it stays off.
+Users, sign-in and sessions with [Better Auth](https://www.better-auth.com). On when `createNanoApp` has `auth`: its options, everything but `database`. Without it, it stays off.
 
 ```bash
-pnpm add better-auth
-```
-
-```ts
-// src/auth.ts: nano-app and the Better Auth CLI read `options`
-import type { BetterAuthOptions } from 'better-auth';
-
-export default {
-  options: { emailAndPassword: { enabled: true } } satisfies BetterAuthOptions,
-};
+pnpm add better-auth kysely pg
 ```
 
 ```ts
 // src/app.ts
 import { createNanoApp } from '@nano-app/backend';
-import * as schema from './db/schema';
-
-createNanoApp({ mainPlugin: { database: { schema } } });
-```
 
-Its tables are yours, like the rest of your schema. Add them with its CLI, then apply them with drizzle-kit; run both again when you change the options:
-
-```bash
-npx auth generate --adapter drizzle --dialect pg --output src/db/auth-schema.ts   # then export its tables from src/db/schema.ts
-pnpm drizzle-kit push
+createNanoApp({ auth: { emailAndPassword: { enabled: true } } });
 ```
 
-- It needs the database: `src/auth.ts` without `mainPlugin.database.schema` fails at startup, and so does a file without `options`.
-- Startup also fails if your schema lacks a table the options need (`user`, `session`, ...), naming them.
-- Its endpoints are mounted with your routes, at its `basePath` (default `/api/auth`), and stay public.
+- It uses the pool of `DATABASE_URL`, with or without a database of the app: startup fails if it is missing.
+- Its tables live in the Postgres schema `nano_auth`, and Better Auth decides them from its options (plugins, `user.additionalFields`).
+- `auth.database` says how they are applied at startup, `{ push: true }` by default: `push` creates them with Better Auth's migrations and adds what new options need, never dropping anything; `migrate` is a folder of Drizzle migrations of them (`npx auth generate --adapter drizzle`, then `drizzle-kit generate`), applied in `nano_auth`.
+- Its endpoints are mounted before your routes, at its `basePath` (default `/api/auth`), and stay public.
 - In production, Better Auth limits sign-in, sign-up and password reset to a few attempts per client IP (its `rateLimit`): see [Client IP](#client-ip).
-- Every route of yours and of the `after` plugins needs a session: without one, 401. The `before` plugins stay public (a landing, an about page).
-- Handlers and `onBefore` receive the session in `params.session` (`{ user, session }`).
+- With it on, every route of the app and of every plugin needs a session: without one it answers 401 `Not authenticated`.
+- `createRoute({ public: true, ... })` answers without a session. An unknown path answers 404.
+- Handlers and `onBefore` receive the session in `params.session` (`{ user, session }`), also on a public route when the request has one.
 - Sign-up works as Better Auth sets it: with `emailAndPassword` anyone can sign up and reach your routes. Close it with `disableSignUp: true`, or check roles in your handlers.
-- Relate your tables to `user` in your `relations`. Extra user fields go in its `user.additionalFields`.
+- Extra user fields go in its `user.additionalFields`.
 - Set `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` in the environment, as Better Auth asks.
-- With it on, every route of the app and of the plugins mounted after it (`stage: 'after'`) needs a session: without one it answers 401 `Not authenticated`. The handlers receive it in `session`.
-- `createRoute({ public: true, ... })` answers without a session; its handlers still receive `session` when the request has one. An unknown path answers 404.
-- Its own endpoints, the plugins mounted before the app and the middlewares a plugin adds with `app.use` in `onMount` are not checked: a plugin that exposes something public says it in its README.
-- Better Auth is loaded only when it is on.
-- Before 0.14.0 the options went in `packages.betterAuth`: move them to the default export of `src/auth.ts`.
-- nano-app creates the one instance the app uses: do not call `betterAuth()` in `src/auth.ts`. The CLI's `generate` only reads `options` of its default export.
+- Better Auth is loaded only when it is on, and nano-app creates the one instance the app uses.
+- Before 0.19.0 the options went in the default export of `src/auth.ts` and its tables in your schema: move the options to `auth`.
 
 ### Permissions
 
-A route asks for permissions of Better Auth's [admin plugin](https://www.better-auth.com/docs/plugins/admin): add `admin()` to the `plugins` of your options, with your roles (`ac` and `roles`), and generate its fields with `npx auth generate`. A user without them gets 403:
+A route asks for permissions of Better Auth's [admin plugin](https://www.better-auth.com/docs/plugins/admin): add `admin()` to the `plugins` of your options, with your roles (`ac` and `roles`). A user without them gets 403:
 
 ```ts
 export default createRoute({
@@ -214,13 +203,13 @@ export default createRoute({
 });
 ```
 
-A method may ask for its own permissions instead of the route's: `POST: { handler, permissions: { notes: ['create'] } }`. A plain function takes those of the route. Without any, a session is enough. In a handler of your own, `isGranted(params, permissions)` asks Better Auth the same.
+A method may ask for its own permissions instead of the route's: `POST: { handler, permissions: { notes: ['create'] } }`. A plain function takes those of the route. Without any, a session is enough. In a handler of your own, `isGranted(params.session, permissions)` asks Better Auth the same.
 
-A public route does not check them. Without Better Auth the route answers anyway, with a warning at startup. Handlers and callbacks receive Better Auth's instance as `auth`, next to `db`; these params are read-only.
+A public route does not check them. Without Better Auth nothing checks them: the route answers anyway, so turn on `auth` before you rely on them. The params of handlers and callbacks are read-only.
 
 ## Plugins
 
-A plugin is a group of endpoints mounted under a base path. Your routes are mounted as one (named `app`). The official plugins are in [`@nano-app/plugins`](https://github.com/Nano-Nathan/nano-app/blob/main/plugins/README.md). You write one with `createPlugin` and list it in `plugins`. Nothing is mounted unless you list it. Official plugins that have tables ship their own migrations: nano-app applies them at startup, each in its `nano_*` schema. That is the only change it makes to your database.
+A plugin is a group of endpoints mounted under a base path. Your routes are mounted as one (named `app`). The official plugins are in [`@nano-app/plugins`](https://github.com/Nano-Nathan/nano-app/blob/main/plugins/README.md). You write one with `createPlugin` and list it in `plugins.before` or `plugins.after`. Nothing is mounted unless you list it.
 
 ```ts
 // src/plugins/hello/index.ts
@@ -228,9 +217,9 @@ import { createPlugin } from '@nano-app/backend';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export default createPlugin((options?: { basePath?: string }) => ({
+export default createPlugin(() => ({
   name: 'hello',
-  basePath: options?.basePath ?? '/hello',
+  basePath: '/hello',
   routesDir: resolve(dirname(fileURLToPath(import.meta.url)), 'routes'),
 }));
 ```
@@ -249,39 +238,34 @@ export default createRoute({
 import { createNanoApp } from '@nano-app/backend';
 import hello from './plugins/hello';
 
-createNanoApp({ plugins: [hello()] });
+createNanoApp({ plugins: { before: [hello()] } });
 ```
 
-`createPlugin` types the options of that plugin. Each plugin chooses its base path and whether it mounts `before` (default) or `after` your routes. What the plugin puts in `options` reaches every callback and handler of its routes in `params`.
+A plugin may also make routes in code with `routes`, by path, beside or instead of `routesDir`: they are checked as the files, and a path in both takes the one in `routes`. Useful when its routes come from its options, as one per table with its own permissions:
+
+```ts
+routes: Object.fromEntries(
+  models.map(sModel => [`/${sModel}`, createRoute({ GET: { handler, permissions: { [sModel]: ['read'] } } })]),
+),
+```
+
+`createPlugin` types the options of that plugin, and adds `basePath` to them: each plugin chooses its default, and the app moves it with `hello({ basePath: '/hi' })`. The app also chooses whether it mounts `before` or `after` its routes: a route of a `before` plugin takes its path from the app's routes, and an `after` plugin only gets what they leave. What the plugin puts in `options` reaches every callback and handler of its routes in `params`.
 
 ### Callbacks
 
-Two levels. Only the plugin's receives the Express app, so nothing app-wide depends on the order of the route files.
+Two levels: the plugin's runs once for the whole plugin, the endpoint's for its route.
 
 | Level | Callback | Runs | Receives | Use |
 |---|---|---|---|---|
-| Plugin (`callbacks` in its config) | `onMount` | Once, after its database and before its endpoints | `(app, params)` | App-level middlewares (a guard), shared setup |
+| Plugin (`callbacks` in its config) | `onMount` | Once, after its database and before its endpoints | `(params)` | Shared setup (a client, a job) |
 | Endpoint (`callbacks` in `createRoute`) | `onInit` | Once, when the endpoint is mounted | `(params)` | Setup of that route |
 | Endpoint | `onBefore` | Before every request the endpoint handles | `(req, method, params)` | Validate or load; its return value reaches the handler as `params.onBeforeResult` (`{}` without `onBefore`) |
 
-```ts
-export default createPlugin((options?: { publicPaths?: string[] }) => ({
-  name: 'guard',
-  routesDir: resolve(dirname(fileURLToPath(import.meta.url)), 'routes'),
-  options: { publicPaths: options?.publicPaths ?? [] },
-  callbacks: {
-    onMount: async (app, { publicPaths }) => {
-      app.use((req, _res, next) => next(publicPaths.includes(req.path) ? undefined : { status: 401, message: 'Unauthorized' }));
-    },
-  },
-}));
-```
-
-The endpoints of one plugin have no guaranteed order: one route's `onInit` must not depend on another's. `mainPlugin` takes `callbacks` too.
+The endpoints of one plugin have no guaranteed order: one route's `onInit` must not depend on another's.
 
-Everything is mounted on one Express application, in this order: base middlewares → `before` plugins → your routes → `after` plugins → 404 → error handler.
+Everything is mounted on one Express application, in this order: base middlewares → Better Auth → `before` plugins → your routes → `after` plugins → 404 → error handler.
 
-A plugin with a database passes its own `database: { schema }`, and keeps its tables in the Postgres schema `nano_<its name>`: a table elsewhere fails the startup. Two plugins with the same name and a database fail too. Without a database of its own, a plugin receives the app's `db`. See [`@nano-app/plugins`](https://github.com/Nano-Nathan/nano-app/blob/main/plugins/README.md#database).
+A plugin with a database passes its own `database` (`relations`, `push`, `migrate`, as the app's). Only it may keep tables in the Postgres schema `nano_<its name>`: a table in the `nano_*` schema of another fails the startup. Without a database of its own, a plugin receives the app's `db`. See [`@nano-app/plugins`](https://github.com/Nano-Nathan/nano-app/blob/main/plugins/README.md#database).
 
 ## Errors
 
@@ -289,10 +273,9 @@ The framework mounts the 404 and the error handler: an unmatched request becomes
 
 ```ts
 throw { status: 409, message: 'Already exists' };   // → 409 { success: false, warning: false, message: "Already exists" }
-throw 'Field name is required';                     // → 400 { success: false, message: "Field name is required" }
+throw 'Field name is required';                     // → 400 { success: false, warning: false, message: "Field name is required" }
 throw new Error('boom');                            // → 500 "Internal server error", logged to stderr
-// A Postgres error the request caused answers without its message, which names tables and columns:
-// 23505 and 23503 → 409 "Conflict", 23502 and 22P02 → 400 "Invalid request"
+// A Postgres error is one more Error: 500. Catch it in your handler to answer a 409
 GET /unknown                                        // → 404 { success: false, warning: false, message: "/unknown not found" }
 ```
 

package/build/index.d.ts

@@ -1,9 +1,12 @@
-import express, { Express, Request, Request as Request$1 } from "express";
-import { CorsOptions } from "cors";
-import "dotenv/config";
-import "jiti";
 import { z } from "zod";
-import "better-auth";
+import express, { Express, Request, Request as Request$1, RequestHandler } from "express";
+import "dotenv/config";
+import { CorsOptions } from "cors";
+import { BetterAuthOptions } from "better-auth";
+import { AnyRelations } from "drizzle-orm";
+import { DrizzlePgConfig } from "drizzle-orm/pg-core";
+/** Generic object */
+type NanoObject<T = any> = Record<string, T>;
 /** API response */
 type ApiResponse<T = any> = {
   status?: number;
@@ -26,10 +29,34 @@ type QueryParams = {
   limit?: number;
   offset?: number;
 };
+/** Error of the framework, with the status a handler answers */
+declare class NanoError extends Error {
+  status?: number;
+  /** Error with its message, and the status a handler answers (500 without one) */
+  constructor(sMessage: string, iStatus?: number);
+  /** Prefix of the framework's messages, shown before the message */
+  get name(): string;
+}
+/** What every database has, whatever its client */
+type DatabaseOptions = {
+  /** Folder of its migrations, applied at startup */
+  migrate?: string;
+  /** Applies its tables at startup as they are declared, failing on data loss; not with `migrate` */
+  push?: boolean;
+};
+/** Drizzle's options for its client: its tables and how they relate, from `defineRelations` */
+type DrizzleConfig = DrizzlePgConfig<AnyRelations> & {
+  relations: AnyRelations;
+};
+/** Database of a plugin or of the app: the options of its client and what every database has */
+type DatabaseConfig = DatabaseOptions & DrizzleConfig;
+/** Better Auth options; `database` says how its tables are applied, `push` by default */
+type AuthOptions = Omit<BetterAuthOptions, 'database'> & {
+  /** How its tables are applied at startup: `migrate` or `push`. Defaults to `{ push: true }` */
+  database?: DatabaseOptions;
+};
 /** Extra params of handlers and callbacks: what the app injects (options, `db`) and the framework adds */
 type Params<Deps = NanoObject<any>> = Deps & {
-  /** Better Auth's instance, when it is on */
-  auth?: NanoObject;
   /** `{ user, session }` of Better Auth, when the request has one */
   session?: NanoObject;
 };
@@ -57,8 +84,8 @@ type Handlers<Deps = NanoObject<any>> = {
 type Callback<Deps> = (params: Params<Deps>) => Promise<void>;
 /** Callback run before a method, with its request */
 type CallbackMethod<Deps> = (req: Request$1, method: string, params: Params<Deps>) => Promise<NanoObject>;
-/** Callback run with the Express app */
-type CallbackMount<Deps> = (app: Express, params: Params<Deps>) => Promise<void>;
+/** Callback run once with the params */
+type CallbackMount<Deps> = (params: Params<Deps>) => Promise<void>;
 /** Callbacks of an endpoint; what affects the whole app goes in the plugin's onMount */
 type Callbacks<Deps = NanoObject<any>> = {
   /** Run once, when the endpoint is mounted */
@@ -68,46 +95,34 @@ type Callbacks<Deps = NanoObject<any>> = {
 };
 /** Callbacks of a plugin */
 type PluginCallbacks<Deps = NanoObject<any>> = {
-  /** Run once with the Express app, after its database and before its endpoints (e.g. app-level middlewares) */
+  /** Run once, after its database and before its endpoints: the plugin's setup */
   onMount?: CallbackMount<Deps>;
 };
-/** Entry of a route file (`*.route.ts`) */
-type RouteEntry<Deps = NanoObject<any>> = {
-  /** Express route expression appended to the path (e.g. `/:id`) */
-  expression?: string;
+/** Endpoint params */
+type EndpointParams<Deps = NanoObject<any>> = {
   /** With Better Auth on, answers without a session; the handlers still receive it when there is one */
   public?: boolean;
   /** With Better Auth on, the permissions of its admin plugin the user needs (`{ notes: ['read'] }`) */
   permissions?: NanoObject<string[]>;
   callbacks?: Callbacks<Deps>;
 } & Handlers<Deps>;
-/** Generic object */
-type NanoObject<T = any> = Record<string, T>;
-/** Error of the framework, with the status a handler answers */
-declare class NanoError extends Error {
-  status?: number;
-  /** Error with its message, and the status a handler answers (500 without one) */
-  constructor(sMessage: string, iStatus?: number);
-  /** Prefix of the framework's messages, shown before the message */
-  get name(): string;
-}
-/** Database of a plugin or of the app */
-type DatabaseConfig = {
-  /** Its Drizzle schema: the module of its tables and `relations` */
-  schema: NanoObject;
+/** Route params */
+type RouteParams = {
+  /** Express route expression appended to the path (e.g. `/:id`) */
+  expression?: string;
 };
-/** When a plugin is mounted, relative to the consumer routes */
-type PluginStage = 'before' | 'after';
+/** Entry of a route file (`*.route.ts`) */
+type RouteEntry<Deps = NanoObject<any>> = RouteParams & EndpointParams<Deps>;
 /** Plugin configuration: a group of endpoints */
 type PluginConfig<Options = NanoObject> = {
   /** Name of the plugin, also the name of its database when it has one */
   name: string;
   /** Directory used to discover the `*.route.ts` files */
-  routesDir: string;
+  routesDir?: string;
+  /** Routes made in code, by path (`{ '/notes': createRoute({...}) }`), validated as the files */
+  routes?: NanoObject<RouteEntry<any>>;
   /** Base path prepended to every endpoint, e.g. "/auth" (no trailing slash). Defaults to none */
   basePath?: string;
-  /** Mount point relative to the consumer routes. Defaults to "before" */
-  stage?: PluginStage;
   /** Drizzle schema of the plugin's database, mounted before its endpoints */
   database?: DatabaseConfig;
   /** Plugin options */
@@ -115,8 +130,34 @@ type PluginConfig<Options = NanoObject> = {
   /** Plugin callbacks */
   callbacks?: PluginCallbacks;
 };
-/** The project's plugin, named "app": `routesDir` defaults to "src/routes" */
-type MainPluginConfig<Options = NanoObject> = Partial<Omit<PluginConfig<Options>, 'name' | 'stage'>>;
+/** Options every plugin takes, besides its own */
+type PluginOptions = {
+  /** Base path of its endpoints, over the plugin's default */
+  basePath?: string;
+};
+/** What PluginManager reads: the app's plugin and the ones around it */
+type PluginManagerConfig = {
+  /** Folder of the app's routes. Defaults to "src/routes" */
+  routesDir?: string;
+  /** Drizzle schema of the app's database */
+  database?: DatabaseConfig;
+  /** Plugins mounted before and after the app's routes */
+  plugins?: {
+    /** Before the app's routes */
+    before?: PluginConfig[];
+    /** After the app's routes */
+    after?: PluginConfig[];
+  };
+};
+/** Rate limit per client IP: a bucket of tokens per client, refilled over time */
+type RateLimitConfig = {
+  /** Tokens of a full bucket. Defaults to 100 */
+  capacity?: number;
+  /** Tokens refilled per second. Defaults to 1 */
+  refillPerSecond?: number;
+  /** Message of the 429 */
+  message?: string;
+};
 /** Configuration of the framework's built-in packages */
 type PackagesConfig = {
   /** Morgan configuration */
@@ -128,6 +169,8 @@ type PackagesConfig = {
   };
   /** CORS configuration */
   cors?: CorsOptions | false;
+  /** Rate limit per client IP, off by default; it covers every request, Better Auth's too */
+  rateLimit?: RateLimitConfig | false;
   /** Helmet configuration */
   helmet?: boolean;
   /** Compression configuration */
@@ -137,36 +180,50 @@ type PackagesConfig = {
   /** urlencoded configuration */
   urlencoded?: Partial<Parameters<typeof express.urlencoded>[0]> | false;
 };
-/** Application configuration */
-type NanoAppConfig = {
+/** What NanoApp reads: the server */
+type ServerConfig = {
   /** Listener run once the server is listening */
   listener?: () => void;
   /** Application port. Defaults to 3000 */
   port?: number;
-  /** Values applied with Express `app.set()` (e.g. `{ "trust proxy": 1 }`) */
+  /** Values for Express `app.set()` (e.g. `{ "trust proxy": 1 }`), over the defaults */
   settings?: NanoObject<unknown>;
-  /** Default middlewares configuration */
+  /** Base middlewares: each one set replaces its default */
   packages?: PackagesConfig;
-  /** Plugins to mount. Defaults to [] */
-  plugins?: PluginConfig[];
-  /** Main plugin to mount. */
-  mainPlugin?: MainPluginConfig;
+  /** Better Auth options: with them, every route needs a session unless it is `public` */
+  auth?: AuthOptions;
 };
-/** Merges the consumer configuration over the initial one; the main plugin is always named "app" */
-declare function mergeConfig(oConfig?: NanoAppConfig): NanoAppConfig & Required<Pick<NanoAppConfig, 'port' | 'settings' | 'plugins' | 'packages'>> & {
-  mainPlugin: PluginConfig;
+/** A route NanoApp registers */
+type Mount = {
+  /** Express path of the route */
+  path: string;
+  /** Its handler */
+  handler: RequestHandler;
 };
+/** Application configuration: the server and its plugins */
+type NanoAppConfig = ServerConfig & PluginManagerConfig;
+/** Better Auth of the app: its tables in `nano_auth`, its endpoints and the access of each request */
+declare abstract class Auth {
+  private static oAuth?;
+  private static fnHeaders?;
+  /** Mounts its database and creates the instance; its endpoints, none without options */
+  static init(oOptions?: AuthOptions): Promise<Mount[]>;
+  /** The session of a request; 401 without one unless public, 403 without the permissions */
+  static guard(oReq: Request$1, isPublic: boolean, oPermissions?: NanoObject<string[]>): Promise<NanoObject | undefined>;
+  /** The session of a request, when it has one */
+  private static session;
+  /** Whether the user of a session has the permissions; always without Better Auth or permissions */
+  static isGranted(oSession?: NanoObject, oPermissions?: NanoObject<string[]>): Promise<boolean>;
+}
 /** Main NanoApp class */
 declare class NanoApp {
   protected oApp: Express;
-  protected oConfig: ReturnType<typeof mergeConfig>;
+  protected oConfig: NanoAppConfig;
   constructor(oConfig?: NanoAppConfig);
   /** Starts the application */
   private start;
   /** Initializes the application in the right order */
   private initialize;
-  /** Adds the packages according to the configuration */
-  private setPackages;
 }
 /** Creates a new NanoApp instance */
 export declare function createNanoApp(oConfig?: NanoAppConfig): NanoApp;
@@ -174,9 +231,9 @@ export declare function createNanoApp(oConfig?: NanoAppConfig): NanoApp;
 export declare function createRoute<Deps = NanoObject<any>>(oRoute: RouteEntry<Deps>): RouteEntry<Deps>;
 /** Creates a plugin: a function of the plugin's own options that returns its configuration. */
 type Creator<Options> = (options?: Options) => PluginConfig<Options>;
-export declare function createPlugin<Options>(fnCreator: Creator<Options>): Creator<Options>;
+export declare function createPlugin<Options extends NanoObject = NanoObject>(fnCreator: Creator<Options>): (options?: Options & PluginOptions) => PluginConfig<Options>;
 /** Creates the callbacks of a plugin, typed with what it injects in its params. */
 export declare function createPluginCallbacks<Deps = NanoObject<any>>(oCallbacks: PluginCallbacks<Deps>): PluginCallbacks<Deps>;
-/** Whether the session's user has the permissions; always without Better Auth or permissions */
-declare function isGranted({ auth, session }: Params, oPermissions?: NanoObject<string[]>): Promise<boolean>;
-export { type ApiPromise, type ApiResponse, type Callbacks, type DatabaseConfig, type Handler, type HandlerParams, type Handlers, type MainPluginConfig, type MethodEntry, NanoApp, type NanoAppConfig, NanoError, type NanoObject, type PackagesConfig, type Params, type PluginCallbacks, type PluginConfig, type PluginStage, type QueryParams, type Request, type RouteEntry, isGranted };
+/** Whether the user of a session has the permissions, asked to Better Auth */
+export declare const isGranted: typeof Auth.isGranted;
+export { type ApiPromise, type ApiResponse, type Callbacks, type DatabaseConfig, type Handler, type HandlerParams, type Handlers, type MethodEntry, NanoApp, type NanoAppConfig, NanoError, type NanoObject, type PackagesConfig, type Params, type PluginCallbacks, type PluginConfig, type PluginManagerConfig, type PluginOptions, type QueryParams, type Request, type RouteEntry, type ServerConfig };