@alxia/janus 0.1.2 → 0.3.0

package/docs/guide/sign-in-and-out.md

@@ -6,7 +6,7 @@ cookie that tells `janus()` a sign-in comes from a device it has seen
 before — and the unbound functions for code outside a route.
 
 ```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';
@@ -24,11 +24,11 @@ const SignIn = z.object({ email: z.string(), password: z.string() });
 const app = alxia()
 	.use(janusErrors()) // a refused sign-in answered 401, a login taken 409
 	.use(session(accounts)) // not required: the people signing in are anonymous
-	.post('/signup', { body: SignUp }, async ({ body, auth, reply }) => {
+	.post('/signup', validate({ body: SignUp }), async ({ body, auth, reply }) => {
 		const signedUp = await accounts.signUp(body);
 		return reply.created({ id: auth.send(signedUp).id });
 	})
-	.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 });
 	})
@@ -60,12 +60,12 @@ It takes a `SessionOpened` — anything holding a `token`, a `session` and
 a `user`, what `signUp`, `signIn` and the other flows of `janus()` that open
 a session answer — so it works after a sign-in by code, by link, or after
 a second factor is confirmed too. With a `deviceToken`, it sets the device
-cookie as well, with the plugin's `device` options ([below](#devices)).
+cookie as well, with the middleware's `device` options ([below](#devices)).
 
 The cookie's attributes — `name` (`janus-session`), `domain`, `path`
 (`'/'`), `sameSite` (`'lax'`), `secure` (`true`) — are set once, in
 `janus({ cookie })`, and `session()` reads and renews the same cookie. A
-route that sends a session keeps its own `Set-Cookie`: the plugin never
+route that sends a session keeps its own `Set-Cookie`: the middleware never
 overwrites it with the session the request came in with.
 
 ### A user type
@@ -74,7 +74,7 @@ With several user types, the flow is the type's; `ctx.auth.send` is the
 same:
 
 ```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';
@@ -93,7 +93,7 @@ const SignIn = z.object({ email: z.string(), password: z.string() });
 const app = alxia()
 	.use(janusErrors())
 	.use(session(accounts))
-	.post('/patients/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+	.post('/patients/signin', validate({ body: SignIn }), async ({ body, auth, reply }) => {
 		const signedIn = await accounts.patient.signIn(body);
 		return reply.ok({ id: auth.send(signedIn).id });
 	});
@@ -107,7 +107,7 @@ challenge, and `send` refuses the union at compile time
 Switch on `status` first:
 
 ```ts
-.post('/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+.post('/signin', validate({ body: SignIn }), async ({ body, auth, reply }) => {
 	const result = await accounts.signIn(body);
 	if (result.status === 'secondFactor') {
 		return reply.ok({ status: result.status, challenge: result.challenge });
@@ -151,7 +151,7 @@ client keeps in a long-lived cookie and presents at its next sign-in.
 `ctx.auth.device` reads it, `ctx.auth.send` writes it back:
 
 ```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';
@@ -169,7 +169,7 @@ const SignIn = z.object({ email: z.string(), password: z.string() });
 const app = alxia()
 	.use(janusErrors())
 	.use(session(accounts))
-	.post('/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+	.post('/signin', validate({ body: SignIn }), async ({ body, auth, reply }) => {
 		const signedIn = await accounts.signIn(body, { device: auth.device });
 		return reply.ok({
 			id: auth.send(signedIn).id,
@@ -203,7 +203,7 @@ const device = { name: 'shop-device', domain: 'example.com' };
 
 alxia()
 	.use(session(accounts, { device }))
-	.post('/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+	.post('/signin', validate({ body: SignIn }), async ({ body, auth, reply }) => {
 		const signedIn = await accounts.signIn(body, { device: auth.device });
 		return reply.ok({ id: auth.send(signedIn).id });
 	});
@@ -241,7 +241,7 @@ helper shared by several routes, a test, or a route declared **before**
 any `session()`, which then looks up no session at all:
 
 ```ts
-import { alxia } from '@alxia/core';
+import { alxia, validate } from '@alxia/core';
 import { deviceOf, janusErrors, sendSession, session, signOut } from '@alxia/janus';
 import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
 import { z } from 'zod';
@@ -258,7 +258,7 @@ const SignIn = z.object({ email: z.string(), password: z.string() });
 
 const app = alxia()
 	.use(janusErrors())
-	.post('/signin', { body: SignIn }, async (ctx) => {
+	.post('/signin', validate({ body: SignIn }), async (ctx) => {
 		const signedIn = await accounts.signIn(ctx.body, { device: deviceOf(ctx) });
 		return ctx.reply.ok({ id: sendSession(ctx, accounts, signedIn).id });
 	})

package/docs/roadmap.md

@@ -7,7 +7,17 @@ number on it. Every release, with each change it made, is in
 
 ## Now
 
-Nothing scheduled yet.
+- **Middlewares, not hooks.** `session()`, `permission()` and `janusErrors()`
+  are middlewares given to `use`. `janusErrors()` is a try/catch: it answers
+  the refusals thrown behind it, so it goes to `use` before `session()`. A
+  required `session()` on the app answers an anonymous request to a missing
+  path with its 401: scope it with a `group`. Lands in 0.4. Their deprecated
+  plugin form, `app.plugin(session(…))`, was removed with alxia 0.5.
+- **Refusals as problems.** On an app with `@alxia/core`'s
+  `alxia({ errors: 'problem' })`, `janusErrors()`, a required `session()`
+  and `permission()` answer RFC 9457 problems — `janusErrors()`'s with its
+  `code` as an extension — and keep their bodies otherwise
+  ([guide](guide/errors.md#as-problems)).
 
 ## Next
 
@@ -31,7 +41,7 @@ Nothing scheduled yet.
 
 ### 0.1.0
 
-- **The user in the context.** `use(session(accounts))` hands the routes
+- **The user in the context.** `plugin(session(accounts))` hands the routes
   after it `user`, `session` and `auth`, typed by the user schema and
   narrowed by `type`; with `required: true`, an anonymous request is a typed
   401 and `user` is never `null`. A required `session()` behind an open one

package/docs/troubleshooting.md

@@ -11,7 +11,6 @@ symptom, under [Traps](#traps).
 - [`'user' is possibly 'null'`](#user-is-possibly-null)
 - [`Type '"admin"' is not assignable to type '"user"'`](#type-admin-is-not-assignable-to-type-user)
 - [`Type 'SecondFactorRequired' is missing the following properties from type 'SessionOpened<User<…>>': token, session, user`](#type-secondfactorrequired-is-missing-the-following-properties-from-type-sessionopeneduser-token-session-user)
-- [`Property 'error' is missing in type '{ code: JanusErrorCode; … }'`](#property-error-is-missing-in-type--code-januserrorcode--)
 
 **Types: permissions**
 
@@ -21,8 +20,8 @@ symptom, under [Traps](#traps).
 - [`Type '() => { locked: boolean; }' is not assignable to type 'undefined'`](#type----locked-boolean--is-not-assignable-to-type-undefined)
 - [`Property 'doctorId' is missing in type '{ … }' but required in type '{ readonly doctorId: string | null; }'`](#property-doctorid-is-missing-in-type----but-required-in-type--readonly-doctorid-string--null-)
 - [`Property 'tenant' does not exist on type 'BaseContext'`](#property-tenant-does-not-exist-on-type-basecontext)
-- [`the plugin reads "tenant", which this app's context does not give: use the plugin that adds it first`](#the-plugin-reads-tenant-which-this-apps-context-does-not-give-use-the-plugin-that-adds-it-first)
-- [`the plugin reads "tenant", which this app's context gives with another type`](#the-plugin-reads-tenant-which-this-apps-context-gives-with-another-type)
+- [`Property 'tenant' is missing in type 'BaseContext & Empty' but required in type '{ tenant: Tenant; }'`](#property-tenant-is-missing-in-type-basecontext--empty-but-required-in-type--tenant-tenant-)
+- [`Types of property 'tenant' are incompatible`](#types-of-property-tenant-are-incompatible)
 - [`the plugin's load reads its context as any: annotate what it reads, or leave it unannotated`](#the-plugins-load-reads-its-context-as-any-annotate-what-it-reads-or-leave-it-unannotated)
 
 **Runtime**
@@ -31,8 +30,11 @@ symptom, under [Traps](#traps).
 - [`TypeError: signIn: a device was given, but janus() has no devices — pass devices: { keys }`](#typeerror-signin-a-device-was-given-but-janus-has-no-devices--pass-devices--keys-)
 - [`Warning: janusErrors(): report failed: …`](#warning-januserrors-report-failed-)
 - [`500 {"error":"internal"}`, with a `JanusError` in the log](#500-errorinternal-with-a-januserror-in-the-log)
+- [`500 {"error":"internal"}` when the identity store is down, and `janusErrors()` is there](#500-errorinternal-when-the-identity-store-is-down-and-januserrors-is-there)
 - [`503 {"code":"STORE_FAILED"}`](#503-codestore_failed)
 - [`401 {"error":"unauthenticated"}` from the sign-in route](#401-errorunauthenticated-from-the-sign-in-route)
+- [`401 {"error":"unauthenticated"}` on a path that does not exist](#401-errorunauthenticated-on-a-path-that-does-not-exist)
+- [`logger()` or `secureHeaders()` never shows the reply of `janusErrors()`](#logger-or-secureheaders-never-shows-the-reply-of-januserrors)
 - [`401 {"code":"CREDENTIALS_INVALID","retryAfter":900}` with the right password](#401-codecredentials_invalidretryafter900-with-the-right-password)
 
 **Traps**
@@ -57,7 +59,7 @@ error TS2339: Property 'user' does not exist on type 'Context<Empty, "/profile",
 **Why:** `session()` adds `user` and `session` to the routes declared
 **after** it. The route before it is not authenticated at all.
 
-**Fix:** declare the route after the plugin:
+**Fix:** declare the route after the middleware:
 
 ```ts
 alxia()
@@ -86,7 +88,7 @@ the route where it is and call the unbound `sendSession(ctx, accounts, …)`,
 ```ts
 alxia()
 	.use(session(accounts))
-	.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 });
 	});
@@ -106,7 +108,7 @@ only at run time, an anonymous request may reach the route with
 `user: null`.
 
 **Fix:** answer the anonymous case, or require the session with a literal
-`true`, so the plugin answers it with a 401 and `user` is never `null`:
+`true`, so the middleware answers it with a 401 and `user` is never `null`:
 
 ```ts
 alxia().use(session(accounts, { required: true })).get('/me', ({ user, reply }) => reply(200, user.email));
@@ -150,30 +152,6 @@ if (result.status === 'secondFactor') return reply.ok({ challenge: result.challe
 return reply.ok({ id: auth.send(result).id });
 ```
 
-### `Property 'error' is missing in type '{ code: JanusErrorCode; … }'`
-
-**When:** a client reads a 401 from a route behind
-`session(accounts, { required: true })` and `janusErrors()` as the session's
-body only.
-
-```text
-error TS2322: Type '{ error: "unauthenticated"; } | { code: JanusErrorCode; issues?: …; minLength?: number; attemptsLeft?: number; retryAfter?: number; }' is not assignable to type '{ error: "unauthenticated"; }'.
-  Property 'error' is missing in type '{ code: JanusErrorCode; … }' but required in type '{ error: "unauthenticated"; }'.
-```
-
-**Why:** two 401s are possible there: the session's own
-`{ error: 'unauthenticated' }`, and janus's `{ code }` — a refused code
-or password — through `janusErrors()`.
-
-**Fix:** narrow on the key ([Errors](guide/errors.md#on-the-client)):
-
-```ts
-if (me.status === 401) {
-	if ('error' in me.data) console.log('sign in first');
-	else console.log(me.data.code);
-}
-```
-
 ## Types: permissions
 
 ### `Property 'object' does not exist on type 'Context<…>'`
@@ -271,17 +249,17 @@ byParam('id', (id) => db.records.findOne({ id }, { projection: { title: 1, docto
 error TS2339: Property 'tenant' does not exist on type 'BaseContext'.
 ```
 
-**When:** `load`, `subject` or `ctx` reads something a `derive` or a plugin
+**When:** `load`, `subject` or `ctx` reads something a `derive` or a middleware
 before the guard added — a tenant, a member — and its parameter is not
 annotated: `load: (ctx) => ctx.tenant.records.get(…)`.
 
 **Why:** an unannotated callback is typed with the request's `BaseContext`
-— the request, the URL, the path parameters — not with what other hooks
+— the request, the URL, the path parameters — not with what other middlewares
 added. `permission()` is built before it is used, so it cannot see the app
 it will be used on.
 
 **Fix:** annotate the parameter with what it reads. The guard infers it,
-and the app that uses it must then give it, before the guard:
+and the app that mounts it must then give it, before the guard:
 
 ```ts
 import type { BaseContext } from '@alxia/core';
@@ -290,51 +268,55 @@ const byTenant = permission(access, 'view', 'record', ({ tenant, pathParams }: B
 	tenant.records.get(pathParams['id'] ?? '') ?? null,
 );
 
-app.use(tenancy).use(byTenant); // tenancy derives tenant
+app.plugin(tenancy).use(byTenant); // tenancy derives tenant
 ```
 
 See [Reading the app's context](guide/permissions.md#reading-the-apps-context).
 
-### `the plugin reads "tenant", which this app's context does not give: use the plugin that adds it first`
+### `Property 'tenant' is missing in type 'BaseContext & Empty' but required in type '{ tenant: Tenant; }'`
 
 ```text
 error TS2769: No overload matches this call.
   …
-        Types of property ''~requires'' are incompatible.
-          Type '{ tenant: Tenant; }' is not assignable to type '"the plugin reads \"tenant\", which this app's context does not give: use the plugin that adds it first"'.
+          Type 'BaseContext & Empty' is not assignable to type 'MiddlewareContext<{ tenant: Tenant; }>'.
+            Property 'tenant' is missing in type 'BaseContext & Empty' but required in type '{ tenant: Tenant; }'.
 ```
 
 **When:** a callback of the guard is annotated to read `tenant`, and the
 guard is used on an app — or in a group — whose context has no `tenant` at
 that point: `alxia().use(byTenant)`, or `use(byTenant)` before
-`use(tenancy)`.
+`plugin(tenancy)`.
 
 **Why:** an annotated `load`, `subject` or `ctx` makes the guard require
-what it reads, and `use` checks the app's context against it, so the
+what it reads, and `app.use` checks the app's context against it, so the
 callback never runs without it.
 
-**Fix:** use the plugin that adds `tenant` first:
+**Fix:** mount what adds `tenant` first:
 
 ```ts
-app.use(tenancy).use(byTenant);
+app.plugin(tenancy).use(byTenant);
 ```
 
 More on this message in
-[`@alxia/core`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#the-plugin-reads--which-this-apps-context-does-not-give-use-the-plugin-that-adds-it-first).
+[`@alxia/core`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#the-plugin-reads--which-this-apps-context-does-not-give-add-the-plugin-or-middleware-that-gives-it-first).
 
-### `the plugin reads "tenant", which this app's context gives with another type`
+### `Types of property 'tenant' are incompatible`
 
 ```text
 error TS2769: No overload matches this call.
   …
-          Type '{ tenant: Tenant; }' is not assignable to type '"the plugin reads \"tenant\", which this app's context gives with another type"'.
+          Type 'BaseContext & Empty & { tenant: Tenant | null; }' is not assignable to type 'MiddlewareContext<{ tenant: Tenant; }>'.
+            Type 'BaseContext & Empty & { tenant: Tenant | null; }' is not assignable to type '{ tenant: Tenant; }'.
+              Types of property 'tenant' are incompatible.
+                Type 'Tenant | null' is not assignable to type 'Tenant'.
+                  Type 'null' is not assignable to type 'Tenant'.
 ```
 
 **When:** the app gives a `tenant`, but of a type that does not fit the one
 the callback's parameter is annotated with: a `Tenant | null` where `load`
 reads `Tenant`, or a tenant of another shape.
 
-**Why:** `use` checks each key the guard reads against the app's context;
+**Why:** `app.use` checks each key the guard reads against the app's context;
 a narrower type passes, a wider or different one does not.
 
 **Fix:** annotate the callback with the type the app gives, and handle it
@@ -354,8 +336,8 @@ More on this message in
 ```text
 error TS2769: No overload matches this call.
   …
-        Types of property ''~requires'' are incompatible.
-          Type '{ readonly '~any': "the plugin's load reads its context as any: annotate what it reads, or leave it unannotated"; }' is not assignable to type '"the plugin's load reads its context as any: annotate what it reads, or leave it unannotated"'.
+          Type 'BaseContext & Empty' is not assignable to type 'MiddlewareContext<{ readonly '~any': "the plugin's load reads its context as any: annotate what it reads, or leave it unannotated"; }>'.
+            Property ''~any'' is missing in type 'BaseContext & Empty' but required in type '{ readonly '~any': "the plugin's load reads its context as any: annotate what it reads, or leave it unannotated"; }'.
 ```
 
 The same message names `subject` or `ctx` when that callback is the one at
@@ -370,7 +352,7 @@ reads, so the guard would require nothing, and an app without a `tenant`
 would be accepted, and throw on every guarded request. The guard is
 refused instead.
 
-**Fix:** annotate what the callback reads, and use the plugin that adds it
+**Fix:** annotate what the callback reads, and mount what adds it
 first:
 
 ```ts
@@ -378,7 +360,7 @@ const byTenant = permission(access, 'view', 'record', ({ tenant, pathParams }: B
 	tenant.records.get(pathParams['id'] ?? '') ?? null,
 );
 
-app.use(tenancy).use(byTenant);
+app.plugin(tenancy).use(byTenant);
 ```
 
 Or leave it unannotated when it reads only the request, as `byParam`'s
@@ -450,21 +432,35 @@ one failing.
 **When:** a `janus()` refusal — `NotFoundError`, a refused password —
 thrown by a route is answered 500 instead of its own status.
 
-**Why:** the route is declared before `use(janusErrors())`, which answers
-only the routes after it.
+**Why:** `janusErrors()` is a try/catch middleware: it answers what is thrown
+**behind** it. The error was thrown by something declared before it, or by
+`session()` or a route while `janusErrors()` was given to `use` after them.
 
-**Fix:** use `janusErrors()` first:
+**Fix:** give `janusErrors()` to `use` first, before `session()`:
 
 ```ts
 const app = alxia()
-	.use(janusErrors())
-	.use(session(accounts))
-	.post('/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+	.use(janusErrors(), session(accounts))
+	.post('/signin', validate({ body: SignIn }), async ({ body, auth, reply }) => {
 		const signedIn = await accounts.signIn(body); // a refusal is now its 401
 		return reply.ok({ id: auth.send(signedIn).id });
 	});
 ```
 
+### `500 {"error":"internal"}` when the identity store is down, and `janusErrors()` is there
+
+**When:** the store behind `session()` is unreachable, and the answer is a 500
+instead of the 503 below, though the app uses `janusErrors()`.
+
+**Why:** `janusErrors()` was given to `use` **after** `session()`. The session
+is read before it, so the `STORE_FAILED` it throws is not behind it.
+
+**Fix:** put it before:
+
+```ts
+alxia().use(janusErrors(), session(accounts)); // not use(session(accounts), janusErrors())
+```
+
 ### `503 {"code":"STORE_FAILED"}`
 
 **When:** every authenticated request, while the identity or relation store
@@ -473,7 +469,7 @@ is unreachable.
 **Why:** intended. A store that cannot answer makes `authenticate` and
 `can` throw `STORE_FAILED`, and `janusErrors()` answers it 503 — never a
 401, which would send every signed-in user to the sign-in page, nor a 403.
-Routes declared before `session()` still answer.
+Routes declared before `session()` still answer. This holds when `janusErrors()` is before `session()`.
 
 **Fix:** the store. Pass `report` to `janusErrors()` to hear about it:
 
@@ -498,7 +494,7 @@ the session for the routes after it, or in a `group`
 alxia()
 	.use(janusErrors())
 	.use(session(accounts))                     // the sign-in routes
-	.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 });
 	})
@@ -506,6 +502,45 @@ alxia()
 	.get('/me', ({ user, reply }) => reply.ok({ name: user.name }));
 ```
 
+### `401 {"error":"unauthenticated"}` on a path that does not exist
+
+**When:** an anonymous request to a missing path is answered 401, where it
+used to be a 404.
+
+**Why:** a required `session()` given to the app's `use` runs on every
+request, a request no route matches included, and answers before the 404.
+The same holds for `permission()` on the app.
+
+**Fix:** scope the guard with a `group`, or a path, so it guards only some routes:
+
+```ts
+alxia()
+	.use(janusErrors(), session(accounts))                      // open: runs on every request
+	.group('/account', (account) =>
+		account
+			.use(session(accounts, { required: true }))          // required: only /account/*
+			.get('/me', ({ user, reply }) => reply.ok({ name: user.name })),
+	);
+```
+
+### `logger()` or `secureHeaders()` never shows the reply of `janusErrors()`
+
+**When:** `janusErrors()` is declared before `logger()`, `secureHeaders()`
+or another observer: the janus error is answered as janus says, but the
+log line shows a 500, or the response lacks the security headers.
+
+**Why:** an observer settles `next()`: it reads the response the error
+would be answered with — a 500 — and the error goes on to `janusErrors()`
+outside it, which answers it. The observer inside saw the 500, not the
+reply.
+
+**Fix:** observers first, then the error-handling middleware, so that
+they see its reply:
+
+```ts
+alxia().use(logger()).use(janusErrors(), session(accounts));
+```
+
 ### `401 {"code":"CREDENTIALS_INVALID","retryAfter":900}` with the right password
 
 **When:** signing in after many failed attempts at the same login; the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/janus",
-	"version": "0.1.2",
+	"version": "0.3.0",
 	"description": "Identities and sessions for alxia on @nxgt/janus: the user typed in the context, the session cookie kept and renewed, a typed 401",
 	"license": "MIT",
 	"type": "module",
@@ -41,14 +41,16 @@
 		]
 	},
 	"devDependencies": {
-		"@alxia/client": "^0.2.1",
-		"@alxia/core": "^0.3.0",
+		"@alxia/core": "^0.5.0",
+		"@alxia/i18n": "^0.3.0",
+		"@alxia/language": "^0.3.0",
+		"@nxgt/i18n": "^2.0.0",
 		"@nxgt/janus": "^0.17.1",
 		"@types/bun": "^1.4.2",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@alxia/core": "^0.3.0",
+		"@alxia/core": "^0.5.0",
 		"@nxgt/janus": "^0.17.1",
 		"typescript": "^6.0.3 || ^7.0.0"
 	}