@alxia/janus 0.1.2 → 0.3.0

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-import { type Alxia, type Empty, type Reply } from '@alxia/core';
+import { type Empty, type Middleware, type Next, type Problem, type Reply } from '@alxia/core';
 import type { Session } from '@nxgt/janus';
 import { type DeviceCookieOptions } from './device';
 import type { Auth, RequestAuth, UserOfAuth } from './types';
@@ -19,49 +19,51 @@ export interface SessionOptions<T extends string> {
 export interface UnauthenticatedBody {
     readonly error: 'unauthenticated';
 }
+/** The 401 a required session answers under `alxia({ errors: 'problem' })`. */
+export type UnauthenticatedProblem = Problem<401>;
 type UserOf<A, T> = Extract<UserOfAuth<A>, {
     readonly type: T;
 }>;
+/** What a session gives the routes after it. */
+type Given<User, S> = {
+    readonly user: User;
+    readonly session: S;
+    readonly auth: RequestAuth;
+};
+/** What `session()` makes: a middleware that gives `Added`, or answers `Refused`. */
+export type SessionMiddleware<Added extends object, Refused = never> = Middleware<Empty, Promise<Refused | Next<Added>>>;
 /**
- * Who a request belongs to, as a plugin: `auth.authenticate(request)`, and
- * the routes declared after it read `user` and `session` — typed by the
- * user schema, narrowed by `type`.
+ * Who a request belongs to, as a middleware: `auth.authenticate(request)`,
+ * and the routes declared after it read `user` and `session` — typed by
+ * the user schema, narrowed by `type`. Given to `app.use`, it runs on a
+ * request no route matches too: a required session answers it 401 before
+ * its 404.
  *
  * **An outage is not anonymous**: a store that cannot answer throws
- * `STORE_FAILED`, which `janusErrors()` answers 503, never 401.
+ * `STORE_FAILED`, which `janusErrors()` — given to `use` before it —
+ * answers 503, never 401.
  *
  * A session renewed in passing is sent again as a cookie, after the route —
  * only to a request that presented it as one (a `Bearer` client is never
  * handed a cookie), and never over a session cookie the route set itself.
  *
  * ```ts
- * app.use(session(accounts, { required: true })).get('/me', ({ user, reply }) => reply.ok(user));
+ * app.use(janusErrors(), session(accounts, { required: true }))
+ *    .get('/me', ({ user, reply }) => reply.ok(user));
  * ```
  */
 export declare function session<A extends Auth<{
     readonly type: string;
 }>, const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(auth: A, options: SessionOptions<T> & {
     readonly required: true;
-}): Alxia<{
-    readonly user: UserOf<A, T>;
-    readonly session: Session;
-    readonly auth: RequestAuth;
-}, Empty, '', Reply<401, UnauthenticatedBody>>;
+}): SessionMiddleware<Given<UserOf<A, T>, Session>, Reply<401, UnauthenticatedBody | UnauthenticatedProblem>>;
 export declare function session<A extends Auth<{
     readonly type: string;
 }>, const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(auth: A, options?: SessionOptions<T> & {
     readonly required?: false;
-}): Alxia<{
-    readonly user: UserOf<A, T> | null;
-    readonly session: Session | null;
-    readonly auth: RequestAuth;
-}, Empty, '', never>;
+}): SessionMiddleware<Given<UserOf<A, T> | null, Session | null>>;
 export declare function session<A extends Auth<{
     readonly type: string;
-}>, const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(auth: A, options?: SessionOptions<T>): Alxia<{
-    readonly user: UserOf<A, T> | null;
-    readonly session: Session | null;
-    readonly auth: RequestAuth;
-}, Empty, '', Reply<401, UnauthenticatedBody>>;
+}>, const T extends UserOfAuth<A>['type'] = UserOfAuth<A>['type']>(auth: A, options?: SessionOptions<T>): SessionMiddleware<Given<UserOf<A, T> | null, Session | null>, Reply<401, UnauthenticatedBody | UnauthenticatedProblem>>;
 export {};
 //# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,KAAK,EAEV,KAAK,KAAK,EACV,KAAK,KAAK,EAEV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,KAAK,mBAAmB,EAAY,MAAM,UAAU,CAAC;AAG9D,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE7D,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM;IAC/C,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CAClC;AAED,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAEjE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CACtB,CAAC,SAAS,IAAI,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACzC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAE7D,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GACtD,KAAK,CACP;IACC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC3B,EACD,KAAK,EACL,EAAE,EACF,KAAK,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAC/B,CAAC;AACF,wBAAgB,OAAO,CACtB,CAAC,SAAS,IAAI,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACzC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAE7D,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GACzD,KAAK,CACP;IACC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC3B,EACD,KAAK,EACL,EAAE,EACF,KAAK,CACL,CAAC;AACF,wBAAgB,OAAO,CACtB,CAAC,SAAS,IAAI,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACzC,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAE7D,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,KAAK,CACP;IACC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC3B,EACD,KAAK,EACL,EAAE,EACF,KAAK,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAC/B,CAAC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -10,7 +10,14 @@ a realistic example for each.
 | --- | --- |
 | [Sessions](guide/sessions.md) | reading who a request belongs to, requiring a session, narrowing to one user type, placing the sign-in routes before the required ones, knowing where the token is read from and when a renewed cookie is sent, or testing a signed-in route |
 | [Signing in and out](guide/sign-in-and-out.md) | setting the session cookie with `ctx.auth.send` after a sign-up or a sign-in, handling a second factor, signing out, remembering devices with the device cookie, or doing any of it outside a route |
-| [Errors](guide/errors.md) | answering janus's refusals with their status and a safe body, knowing which code is which status, reporting the 5xx, or reading a refusal on the client |
-| [Permissions](guide/permissions.md) | guarding routes with a permission on an object, loading it by a path parameter, passing a condition's context, checking for another subject than the session's user, or reading what an earlier plugin added |
+| [Errors](guide/errors.md) | answering janus's refusals with their status and a safe body, knowing which code is which status, reporting the 5xx, or reading a refusal on the wire |
+| [Permissions](guide/permissions.md) | guarding routes with a permission on an object, loading it by a path parameter, passing a condition's context, checking for another subject than the session's user, or reading what an earlier middleware added |
 | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message, or a request is anonymous, refused or a 404 when you did not expect it |
 | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |
+
+## Recipes
+
+A task that crosses packages, in [the repository's recipes](https://github.com/softistx/alxia/blob/develop/docs/recipes/README.md), each with a complete example:
+
+- [Authenticate requests](https://github.com/softistx/alxia/blob/develop/docs/recipes/authentication.md): a bearer token or a cookie session, a role check, the user typed in every handler
+- [Answer errors consistently](https://github.com/softistx/alxia/blob/develop/docs/recipes/errors.md): problem details, `HttpError`, a `try`/`catch` middleware

package/docs/guide/errors.md

@@ -1,12 +1,12 @@
 # Errors
 
-This page covers `janusErrors()`: the plugin that answers every refusal
+This page covers `janusErrors()`: the middleware that answers every refusal
 `@nxgt/janus` throws — a wrong password, a login taken, a store down —
 with its status and a body a client can act on, typed on the routes after
 it; and `bodyOf` and `statusOf`, the two functions it is made of.
 
 ```ts
-import { alxia } from '@alxia/core';
+import { alxia, validate } from '@alxia/core';
 import { janusErrors, session } from '@alxia/janus';
 import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
 import { z } from 'zod';
@@ -23,13 +23,13 @@ const SignUp = z.object({ email: z.string(), name: z.string(), password: z.strin
 const app = alxia()
 	.use(janusErrors())
 	.use(session(accounts))
-	.post('/signup', { body: SignUp }, async ({ body, auth, reply }) => {
+	.post('/signup', validate({ body: SignUp }), async ({ body, auth, reply }) => {
 		const signedUp = await accounts.signUp(body); // throws a JanusError when it refuses
 		return reply.created({ id: auth.send(signedUp).id });
 	});
 ```
 
-A route needs no `try`: `signUp` throws, and the plugin answers.
+A route needs no `try`: `signUp` throws, and the middleware answers.
 
 ```text
 400 {"code":"PASSWORD_TOO_SHORT","minLength":12}
@@ -42,12 +42,37 @@ A route needs no `try`: `signUp` throws, and the plugin answers.
 
 ## Where to put it
 
-`janusErrors()` is an `onError` hook: it answers the errors of the routes
-declared **after** it. Put it first. A `JanusError` thrown by a route
-declared before it is the app's 500 `{"error":"internal"}`.
+`janusErrors()` is a try/catch middleware: it answers a `JanusError` thrown
+**behind** it, by `session()`, by `permission()` or by a route. Give it to
+`use` before `session()`:
+
+```ts
+const app = alxia().use(janusErrors(), session(accounts));
+```
+
+Declared after `session()`, it never sees what `session()` throws: a store
+down while the session is read (`STORE_FAILED`) is the app's 500
+`{"error":"internal"}`, not the 503. The same goes for a route declared
+before it: a `JanusError` it throws is not behind `janusErrors()`.
 
-It answers only a `JanusError`. Anything else goes on to the app's next
-`onError`, or its 500.
+It answers only a `JanusError`. Anything else goes on, thrown, to the
+middlewares before it — a try/catch of your own around `await next()` — and,
+when none answers it, to the route boundary: an `HttpError`'s status, else a 500.
+
+An observer that settles `next()` (`logger()`, `secureHeaders()`,
+`telemetry()`, `createI18n()`) reads the response the error would be
+answered with, and lets the error go on: `janusErrors()` answers it
+wherever it stands, `use(janusErrors()).use(i18n).use(session())`
+included. Give the observers to `use` first, then `janusErrors()`, so
+that they see its reply rather than the 500.
+
+```ts
+import { logger } from '@alxia/logger';
+
+const app = alxia()
+	.use(logger())                          // sees the 503 janusErrors() answers
+	.use(janusErrors(), session(accounts));
+```
 
 ## Statuses
 
@@ -95,7 +120,7 @@ bodyOf(new NotFoundError('user')); // { code: 'NOT_FOUND' }
 `CREDENTIALS_INVALID` is one code for an unknown login, a wrong password and
 a login throttled for too many attempts: a client cannot tell a login exists
 from it. `retryAfter` is set only once `janus()`'s throttle trips — ten
-passwords in fifteen minutes by default — and the plugin then adds the
+passwords in fifteen minutes by default — and the middleware then adds the
 `Retry-After` header.
 
 ## Reporting the 5xx
@@ -105,6 +130,7 @@ const app = alxia().use(
 	janusErrors({
 		report: (error, ctx) => console.error(`${ctx.route}: ${error.code}`, error.cause),
 	}),
+	session(accounts),
 );
 ```
 
@@ -122,35 +148,63 @@ or rejects is a process warning, and the 503 is sent all the same:
 
 The 4xx are not reported: they are the client's.
 
-## On the client
+## On the wire
 
-The refusals are in the type of every route after the plugin, so
-`@alxia/client` reads them. A 401 from a route behind
+Every route after the middleware may answer these refusals: declare them in
+your OpenAPI document, and the client you generate from it (with
+`@nxgt/openapi-codegen`, say) reads them typed. A 401 from a route behind
 `session(accounts, { required: true })` is either the session's
-`{ error: 'unauthenticated' }` or janus's `{ code }`; narrow on the key:
+`{ error: 'unauthenticated' }` or janus's `{ code }`; a caller narrows on
+the key:
 
 ```ts
-import { client } from '@alxia/client';
 import { alxia } from '@alxia/core';
 import { janusErrors, session } from '@alxia/janus';
 
 const app = alxia()
-	.use(janusErrors())
-	.use(session(accounts, { required: true }))
+	.use(janusErrors(), session(accounts, { required: true }))
 	.get('/me', ({ user, reply }) => reply(200, { name: user.name }));
 
-const me = await client(app).get('/me');
+const me = await app.request('/me');
+const body = await me.json();
 if (me.status === 401) {
-	if ('error' in me.data) console.log('sign in first');   // the session's own 401
-	else console.log(me.data.code);                           // a JanusErrorCode
+	if ('error' in body) console.log('sign in first');   // the session's own 401
+	else console.log(body.code);                          // a JanusErrorCode
 }
-if (me.status === 503) console.log(me.data.code);          // 'STORE_FAILED' and the like: try again later
+if (me.status === 503) console.log(body.code);         // 'STORE_FAILED' and the like: try again later
+```
+
+### As problems
+
+On an app that answers its errors as RFC 9457 problems, every answer of
+this package is one, sent as `application/problem+json`, with the
+`Retry-After` header kept: `janusErrors()`'s carries `bodyOf(error)` as
+its extensions, `code` first among them (`JanusErrorProblem`); a
+required `session()`'s 401 (`UnauthenticatedProblem`) and
+`permission()`'s 401, 404 and 403 (`PermissionRefusedProblem`) carry
+their five members alone. A caller narrows on `code` rather than on
+`error`:
+
+```text
+503 {"type":"about:blank","title":"Service Unavailable","status":503,"detail":"Service Unavailable","instance":"/me","code":"STORE_FAILED"}
+401 {"type":"about:blank","title":"Unauthorized","status":401,"detail":"The request has no session","instance":"/me"}
+403 {"type":"about:blank","title":"Forbidden","status":403,"detail":"The view permission on this record is not granted","instance":"/records/r1"}
 ```
 
+Each reads the format of the app serving the request, with
+`@alxia/core`'s `errorFormat(ctx)`
+([core's errors guide](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/errors.md)).
+
 ## Signatures
 
 ```ts
-function janusErrors(options?: JanusErrorsOptions): Alxia<Empty, Empty, '', Reply<JanusErrorStatus, JanusErrorBody>>;
+function janusErrors(options?: JanusErrorsOptions): JanusErrors;
+
+// a middleware: answers the JanusErrors thrown behind it
+type JanusErrors = Middleware<object, Promise<Next | Reply<JanusErrorStatus, JanusErrorBody | JanusErrorProblem>>>;
+
+// under alxia({ errors: 'problem' })
+type JanusErrorProblem = Problem<JanusErrorStatus, JanusErrorBody>;
 
 interface JanusErrorsOptions {
 	readonly report?: (error: JanusError, ctx: BaseContext) => unknown;
@@ -170,7 +224,7 @@ function statusOf(code: JanusErrorCode): JanusErrorStatus; // @nxgt/janus's
 ```
 
 `JanusError`, `JanusErrorCode` and `JanusErrorStatus` are `@nxgt/janus`'s;
-`Alxia`, `Empty`, `Reply` and `BaseContext` are `@alxia/core`'s.
+`Middleware`, `Next`, `Reply`, `Problem` and `BaseContext` are `@alxia/core`'s.
 
 The permission guard's own refusals — `{ error: 'forbidden' }` and the
 like — are not `JanusError`s; see [Permissions](permissions.md#refusals).

package/docs/guide/permissions.md

@@ -45,6 +45,11 @@ const app = alxia()
 	);
 ```
 
+The guard lives in a `group`: given to the app's own `use`, it would also run
+on a request no route matches, and answer it 401 or 404 before the 404 it
+should get. `janusErrors()` is given to `use` before `session()`, so it
+answers what `session()` and the guard throw.
+
 `object` is what `findRecord` answered, typed as such. Granting access is
 `@nxgt/janus`'s:
 
@@ -64,7 +69,7 @@ await access.grant({ type: 'record', id: 'r1' }, 'owners', user); // user: what
 | `options.ctx` | `(ctx: BaseContext, object: O) => …` | the context a condition of the permission reads; **required exactly when the permission has one**, refused otherwise |
 
 Each callback reads the request's `BaseContext`, and, when its parameter is
-annotated, what an earlier plugin added: see
+annotated, what an earlier middleware added: see
 [Reading the app's context](#reading-the-apps-context).
 
 It runs once per request, before the route:
@@ -83,7 +88,7 @@ and answer it 401 or 404.
 
 ## Refusals
 
-Each refusal is in the type of the guarded routes, with the body
+Each guarded route may answer these refusals, with the body
 `PermissionRefusedBody`:
 
 | The request | Answered |
@@ -93,6 +98,11 @@ Each refusal is in the type of the guarded routes, with the body
 | `can` answers `false` | `403 {"error":"forbidden"}` |
 | allowed | the route runs, `object` set |
 
+On an app with `alxia({ errors: 'problem' })`, each refusal is an RFC 9457
+problem instead, sent as `application/problem+json` — `"title":"Forbidden",
+"detail":"The view permission on this record is not granted"` — typed
+`PermissionRefusedProblem` ([Errors](errors.md#as-problems)).
+
 **A failure throws.** A relation store that cannot answer throws
 `STORE_FAILED`, never a 403; a check that walks past `maxDepth` throws
 `PERMISSION_DEPTH`. Both are `JanusError`s: [`janusErrors()`](errors.md)
@@ -206,7 +216,7 @@ request throws a `TypeError` and answers 500
 `subject` names another — an API key's service account, a user read from a
 header set by a gateway. It reads the `BaseContext`, so the request, the
 URL and the path parameters, not the route's validated headers — and, when
-its parameter is annotated, what an earlier plugin added
+its parameter is annotated, what an earlier middleware added
 ([Reading the app's context](#reading-the-apps-context)). `null` is
 anonymous, a 401:
 
@@ -222,12 +232,12 @@ permission(access, 'view', 'record', byParam('id', findRecord), {
 ## Reading the app's context
 
 `load`, `subject` and `ctx` read `BaseContext` — the request, the URL, the
-path parameters. To read what an earlier plugin added — a tenant, a member,
+path parameters. To read what an earlier middleware added — a tenant, a member,
 a feature flag — annotate the callback's parameter. `permission()` infers
 what each one reads from its annotation, while `access`, `permission`,
 `type` and the object stay inferred as before, and the guard is a
-[`definePlugin`](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/writing-a-plugin.md#a-plugin-that-needs-an-earlier-one)
-plugin: an app that does not give it before the guard cannot use it.
+[middleware that requires an earlier one](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/writing-a-plugin.md#a-plugin-that-needs-an-earlier-one):
+an app that does not give it before the guard cannot `use` it.
 
 ```ts
 import { alxia, type BaseContext } from '@alxia/core';
@@ -250,20 +260,20 @@ const edit = permission(
 
 const app = alxia()
 	.use(janusErrors())
-	.use(tenancy) // derives tenant and member
+	.plugin(tenancy) // derives tenant and member
 	.group('/records/:id', (record) =>
 		record.use(edit).put('/', ({ object, reply }) => reply(200, { title: object.title })),
 	);
 
 alxia().use(edit);
-// error, one message per missing key: the plugin reads "tenant", which this app's context does not give: use the plugin that adds it first
-//   | the plugin reads "member", which this app's context does not give: use the plugin that adds it first
+// error, one message per missing key: Property 'tenant' is missing in type 'BaseContext & Empty' but required in type '{ tenant: Tenant; }'
+//   | Property 'member' is missing in type 'BaseContext & Empty' but required in type '{ member: { type: 'user'; id: string } | null; }'
 ```
 
 What the guard requires is the union of what the three annotations read.
 An annotation may be `BaseContext & { member: Member }` or `{ member: Member }`
 alone. An app whose `member` has a type that does not fit is refused too —
-`the plugin reads "member", which this app's context gives with another type`
+`Types of property 'member' are incompatible`
 — while a narrower one passes. A key `BaseContext` already has, annotated
 with a type it does not give — `({ pathParams }: { pathParams: string })` —
 is refused the same way.
@@ -316,13 +326,13 @@ function permission<
 	type: T,
 	load: (ctx: BaseContext & LoadCtx) => Awaitable<O | null>,
 	...options: OptionsArgs<C, T, P, O, SubjectCtx, CheckCtx>
-): Alxia<
-	RequiresOf<LoadCtx & SubjectCtx & CheckCtx> & { object: O },
-	Empty,
-	'',
-	Reply<401, PermissionRefusedBody> | Reply<404, PermissionRefusedBody> | Reply<403, PermissionRefusedBody>
-> &
-	Requiring<RequiresOf<LoadCtx & SubjectCtx & CheckCtx>>;
+): Middleware<
+	RequiresOf<LoadCtx & SubjectCtx & CheckCtx>,
+	Promise<
+		| Reply<401 | 404 | 403, PermissionRefusedBody | PermissionRefusedProblem>
+		| Next<{ object: O }>
+	>
+>;
 
 function byParam<O>(name: string, find: (id: string) => Awaitable<O | null>): (ctx: BaseContext) => Awaitable<O | null>;
 
@@ -340,10 +350,13 @@ interface PermissionRefusedBody {
 	readonly error: 'unauthenticated' | 'not_found' | 'forbidden';
 }
 
+// a refusal under @alxia/core's alxia({ errors: 'problem' })
+type PermissionRefusedProblem = Problem<401 | 403 | 404>;
+
 type Awaitable<V> = V | Promise<V>;
 ```
 
-`RequiresOf` and `Requiring` are `@alxia/core`'s. `LoadCtx`, `SubjectCtx`
+`RequiresOf`, `Middleware`, `Next`, `Reply` and `Problem` are `@alxia/core`'s. `LoadCtx`, `SubjectCtx`
 and `CheckCtx` are inferred from the types `load`, `subject` and `ctx`'s
 parameters are annotated with, `BaseContext` when they are not. `RequiresOf<X>` is what `X` adds to `BaseContext` — `{ tenant: Tenant }`
 for `BaseContext & { tenant: Tenant }` — and `Empty` when it adds nothing;

package/docs/guide/sessions.md

@@ -1,6 +1,6 @@
 # Sessions
 
-This page covers `session()`: the plugin that reads who a request belongs
+This page covers `session()`: the middleware that reads who a request belongs
 to, hands the routes after it a typed `user` and `session` and a bound
 `auth`, refuses an anonymous request when asked to, and sends a renewed
 session's cookie again.
@@ -27,7 +27,9 @@ const app = alxia()
 
 `session(accounts)` calls `accounts.authenticate(request)` once per request, for
 the routes declared **after** it. A route declared before it is not
-touched, and has no `user`, `session` or `auth`.
+touched, and has no `user`, `session` or `auth`. A request no route matches
+is not a route, so `session()` runs on it, wherever it is declared: with
+`required: true`, `GET /nothing` is a 401 before it is a 404.
 
 ## Where the session is read from
 
@@ -68,8 +70,9 @@ const app = alxia()
 	);
 ```
 
-With `required: true`, the 401 is in the type of every route after it, so a
-client generated from the app reads it:
+With `required: true`, every route after it answers this 401 to an
+anonymous request; declare it in the OpenAPI document a client is
+generated from:
 
 ```text
 401 {"error":"unauthenticated"}
@@ -143,7 +146,7 @@ A patient's session on `/staff/me` is a 401, as if they had sent none. A
 | `user` | the user, typed by its schema and narrowed by `type`, or `null` | the user, or `null` | the user |
 | `session` | `Session` or `null` | `Session` or `null` | `Session` |
 | `auth` | `RequestAuth`: `send`, `signOut`, `device` | the same | the same |
-| a 401 in the routes' type | no | yes | yes |
+| a 401 to an anonymous request | no | yes | yes |
 
 `Session` is `@nxgt/janus`'s: `id`, `userId`, `authenticatedAt`,
 `expiresAt`, `revokedAt`, `createdAt`. The token is never in it.
@@ -164,11 +167,11 @@ is signed in — [Signing in and out](sign-in-and-out.md) is its page.
 
 A sign-in route is called by someone who is not signed in yet, so it sits
 behind a `session()` that is **not** required: behind `required: true` it
-answers `401 {"error":"unauthenticated"}` before it runs. Use the plugin
+answers `401 {"error":"unauthenticated"}` before it runs. Use the middleware
 twice — once open, for the sign-in routes; once required, for the rest:
 
 ```ts
-import { alxia } from '@alxia/core';
+import { alxia, validate } from '@alxia/core';
 import { janusErrors, session } from '@alxia/janus';
 import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
 import { z } from 'zod';
@@ -185,7 +188,7 @@ const SignIn = z.object({ email: z.string(), password: z.string() });
 const app = alxia()
 	.use(janusErrors())
 	.use(session(accounts))                       // open: user may be null
-	.post('/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+	.post('/signin', validate({ body: SignIn }), async ({ body, auth, reply }) => {
 		const signedIn = await accounts.signIn(body);
 		return reply.ok({ id: auth.send(signedIn).id });
 	})
@@ -202,10 +205,13 @@ The second `session()` replaces the first's `user`, `session` and `auth`
 for the routes after it, with its own types: `user` is never `null` under
 `/account`, and still may be on `/greeting`, outside the group. Without the
 `group`, `.use(session(accounts, { required: true }))` on the app itself works
-the same for every route declared after it.
+the same for every route declared after it, and for a request no route
+matches: an anonymous request to a missing path is then a 401, not a 404.
+Scope a required session with a `group` to guard only some routes: a path-scoped
+`use('/api', session(…))` does not compile, since `session` adds `user`.
 
-A route behind both plugins still looks the session up once: the plugins
-of one instance share a request's lookup, for the same `type`. A different
+A route behind both middlewares still looks the session up once: the
+middlewares of one instance share a request's lookup, for the same `type`. A different
 `type` is its own lookup.
 
 ## A renewed session is sent again
@@ -219,7 +225,7 @@ conditions:
   `Authorization: Bearer` is never handed a cookie; it keeps its token,
   which is still the same one;
 - **the route did not set a session cookie itself.** A route behind the
-  plugin that signs in, or signs out, keeps its own `Set-Cookie`: the
+  route that signs in, or signs out, keeps its own `Set-Cookie`: the
   session it replaced does not undo it.
 
 ```ts
@@ -260,11 +266,17 @@ writes it with `accounts.cookie.serialize`, so they are set in one place.
 A store that cannot answer makes `authenticate` throw `STORE_FAILED`.
 `session()` does not catch it: the request fails, and `janusErrors()`
 answers it **503** `{ "code": "STORE_FAILED" }` — never a 401 that would
-send every user to the sign-in page. Without `janusErrors()`, it is the
-app's 500. See [Errors](errors.md).
+send every user to the sign-in page. `janusErrors()` must be given to `use`
+**before** `session()`, or it is not behind it to see the error: the app's
+500 answers instead. See [Errors](errors.md).
+
+```ts
+const app = alxia().use(janusErrors(), session(accounts, { required: true }));
+```
 
 Routes declared before `session()` do not call the store, and keep
-answering.
+answering. A request no route matches does run it: `session()` on the app is
+given to every request.
 
 ## Testing it
 
@@ -301,27 +313,32 @@ test('the session reads the user, and anonymous is a 401', async () => {
 function session<A extends Auth<{ readonly type: string }>, const T extends UserOfAuth<A>['type']>(
 	auth: A,
 	options: SessionOptions<T> & { readonly required: true },
-): Alxia<
+): SessionMiddleware<
 	{ readonly user: UserOf<A, T>; readonly session: Session; readonly auth: RequestAuth },
-	Empty, '', Reply<401, UnauthenticatedBody>
+	Reply<401, UnauthenticatedBody | UnauthenticatedProblem>
 >;
 
 function session<A extends Auth<{ readonly type: string }>, const T extends UserOfAuth<A>['type']>(
 	auth: A,
 	options?: SessionOptions<T> & { readonly required?: false },
-): Alxia<
-	{ readonly user: UserOf<A, T> | null; readonly session: Session | null; readonly auth: RequestAuth },
-	Empty, '', never
+): SessionMiddleware<
+	{ readonly user: UserOf<A, T> | null; readonly session: Session | null; readonly auth: RequestAuth }
 >;
 
 function session<A extends Auth<{ readonly type: string }>, const T extends UserOfAuth<A>['type']>(
 	auth: A,
 	options?: SessionOptions<T>,
-): Alxia<
+): SessionMiddleware<
 	{ readonly user: UserOf<A, T> | null; readonly session: Session | null; readonly auth: RequestAuth },
-	Empty, '', Reply<401, UnauthenticatedBody>
+	Reply<401, UnauthenticatedBody | UnauthenticatedProblem>
 >;
 
+// a middleware that gives Added, or answers Refused
+type SessionMiddleware<Added extends object, Refused = never> = Middleware<Empty, Promise<Refused | Next<Added>>>;
+
+// the 401 under @alxia/core's alxia({ errors: 'problem' })
+type UnauthenticatedProblem = Problem<401>;
+
 interface SessionOptions<T extends string> {
 	readonly type?: T;
 	readonly required?: boolean;
@@ -343,8 +360,8 @@ type UserOfAuth<A> = A extends Auth<infer U> ? U : never;
 `RequestAuth` and `DeviceCookieOptions` are shown in
 [Signing in and out](sign-in-and-out.md#signatures).
 `UserOf<A, T>` is `Extract<UserOfAuth<A>, { readonly type: T }>`; it is not
-exported. `Alxia`, `Empty` and `Reply` are `@alxia/core`'s; `Session` and
+exported. `Middleware`, `Next`, `Empty`, `Reply` and `Problem` are `@alxia/core`'s; `Session` and
 `SharedApi` are `@nxgt/janus`'s.
 
-Next: [Signing in and out](sign-in-and-out.md) sets the cookie this plugin
+Next: [Signing in and out](sign-in-and-out.md) sets the cookie this middleware
 reads.