@alxia/janus 0.1.0

package/docs/guide/sessions.md

@@ -0,0 +1,350 @@
+# Sessions
+
+This page covers `session()`: the plugin 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.
+
+```ts
+import { alxia } from '@alxia/core';
+import { janusErrors, session } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	store: createMemoryStores(), // your database's adapter in production
+	hasher: scryptHasher(),
+});
+
+const app = alxia()
+	.use(janusErrors())
+	.get('/health', ({ reply }) => reply(200, 'ok'))       // before it: open
+	.use(session(accounts, { required: true }))
+	.get('/me', ({ user, reply }) => reply(200, { name: user.name })); // user: never null
+```
+
+`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`.
+
+## Where the session is read from
+
+`accounts.authenticate` reads, in this order, `Authorization: Bearer <token>`,
+`X-Session-Token: <token>`, and the session cookie (`janus-session` unless
+`janus({ cookie: { name } })` says otherwise). **The first credential
+present wins, not the first valid one**: a request sending a lapsed bearer
+beside a live cookie is anonymous.
+
+```ts
+await app.request('/me', { headers: { cookie: `janus-session=${token}` } });     // 200
+await app.request('/me', { headers: { authorization: `Bearer ${token}` } });     // 200
+await app.request('/me', { headers: { 'x-session-token': token } });             // 200
+await app.request('/me');                                                        // 401
+```
+
+A lapsed or revoked session, a user deleted or made inactive, or a user of
+another type than `type` is anonymous.
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `required` | `boolean` | `false` | `true`: an anonymous request is answered `401 { error: 'unauthenticated' }` and the route never runs; a literal `true` also types `user` as never `null` |
+| `type` | one of the user types of `janus()` | every type | only a user of this type is authenticated; any other is anonymous, and `user` is narrowed to it |
+| `device` | `DeviceCookieOptions` | the `janus-device` cookie | the device cookie `ctx.auth.device` reads and `ctx.auth.send` sets ([Devices](sign-in-and-out.md#devices)) |
+
+### `required`
+
+Without it, `user` and `session` are `null` for an anonymous request, and
+the route decides:
+
+```ts
+const app = alxia()
+	.use(session(accounts))
+	.get('/greeting', ({ user, reply }) =>
+		reply(200, user === null ? 'Hello, stranger' : `Hello, ${user.name}`),
+	);
+```
+
+With `required: true`, the 401 is in the type of every route after it, so a
+client generated from the app reads it:
+
+```text
+401 {"error":"unauthenticated"}
+```
+
+A `boolean` known only at run time is accepted too — and so is a whole
+`SessionOptions` value, for a wrapper that forwards it. The compiler cannot
+tell which it will be, so the routes get both answers: the 401 is in their
+type, and `user` may be `null`. At run time, `true` answers an anonymous
+request 401 and `false` lets it through with `user: null`:
+
+```ts
+const strict = Bun.env['STRICT'] === '1';
+
+const app = alxia()
+	.use(session(accounts, { required: strict }))
+	.get('/me', ({ user, reply }) => reply(200, user === null ? 'anonymous' : user.name));
+
+// STRICT=1: 401 {"error":"unauthenticated"}; otherwise: 200 "anonymous"
+```
+
+Write the literal `true` when the session is always required: only then
+does the compiler know `user` is never `null`.
+
+### `type`
+
+With several user types, `type` narrows `user` to one of them; a user of
+another type is anonymous there. Scope it with `group`:
+
+```ts
+import { alxia } from '@alxia/core';
+import { janusErrors, session } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	users: {
+		patient: {
+			schema: z.object({ email: z.email(), name: z.string() }),
+			password: { login: 'email' },
+		},
+		staff: {
+			schema: z.object({ username: z.string() }),
+			password: { login: 'username' },
+		},
+	},
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+const app = alxia()
+	.use(janusErrors())
+	.group('/staff', (staff) =>
+		staff
+			.use(session(accounts, { type: 'staff', required: true }))
+			.get('/me', ({ user, reply }) => reply(200, { username: user.username })), // a staff user
+	)
+	.use(session(accounts))
+	.get('/whoami', ({ user, reply }) =>
+		reply(200, user === null ? 'anonymous' : user.type), // 'patient' | 'staff'
+	);
+```
+
+A patient's session on `/staff/me` is a 401, as if they had sent none. A
+`type` that is not one of `janus()`'s user types does not compile.
+
+## What the routes read
+
+| Field | Without `required`, or `false` | With a `boolean` | With `required: true` |
+| --- | --- | --- | --- |
+| `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 |
+
+`Session` is `@nxgt/janus`'s: `id`, `userId`, `authenticatedAt`,
+`expiresAt`, `revokedAt`, `createdAt`. The token is never in it.
+
+`user` is the whole user as `janus()` answers it — your schema's fields,
+plus `id`, `type`, `emailVerified`, `active`, `hasPassword`,
+`hasSecondFactor`, `version`, `createdAt`, `updatedAt` — and never a
+password hash. Reply with the fields a client needs rather than the whole
+object when the user schema holds anything private.
+
+`auth` is the request's half of signing in and out, bound to it:
+`auth.send(signedIn)` sets the session cookie and returns the user,
+`auth.signOut()` revokes the session and clears it, `auth.device` is the
+device token the request carries. It is there whether or not the request
+is signed in — [Signing in and out](sign-in-and-out.md) is its page.
+
+## Where the sign-in routes go
+
+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
+twice — once open, for the sign-in routes; once required, for the rest:
+
+```ts
+import { alxia } from '@alxia/core';
+import { janusErrors, session } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+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 }) => {
+		const signedIn = await accounts.signIn(body);
+		return reply.ok({ id: auth.send(signedIn).id });
+	})
+	.post('/signout', async ({ auth, reply }) => reply.ok(await auth.signOut()))
+	.group('/account', (account) =>
+		account
+			.use(session(accounts, { required: true })) // required: user never null
+			.get('/me', ({ user, reply }) => reply.ok({ name: user.name })),
+	)
+	.get('/greeting', ({ user, reply }) => reply.ok(user === null ? 'Hello, stranger' : `Hello, ${user.name}`));
+```
+
+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.
+
+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
+`type` is its own lookup.
+
+## A renewed session is sent again
+
+A session type with a `renewAfter` slides: `authenticate` renews it in
+passing once that much has passed, and its expiry moves. `session()` then
+sends the cookie again, after the route, with the new `Expires` — under two
+conditions:
+
+- **the request presented the session as a cookie.** A client sending
+  `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
+  session it replaced does not undo it.
+
+```ts
+import { alxia } from '@alxia/core';
+import { session } from '@alxia/janus';
+import { createMemoryStores, fixedClock, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const clock = fixedClock(Date.UTC(2026, 8, 24));
+const accounts = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	session: { lifespan: '7d', renewAfter: '1d' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+	clock,
+});
+const app = alxia()
+	.use(session(accounts, { required: true }))
+	.get('/me', ({ user, reply }) => reply(200, user.email));
+
+const { token } = await accounts.signUp({ email: 'ada@example.com', password: 'correct horse' });
+clock.advance(2 * 86_400_000);
+
+const viaCookie = await app.request('/me', { headers: { cookie: `janus-session=${token}` } });
+viaCookie.headers.getSetCookie(); // ['janus-session=…; Expires=Sat, 03 Oct 2026 00:00:00 GMT; Path=/; HttpOnly; SameSite=Lax; Secure']
+
+const viaBearer = await app.request('/me', { headers: { authorization: `Bearer ${token}` } });
+viaBearer.headers.getSetCookie(); // []
+```
+
+The cookie's attributes are `janus()`'s `cookie` option — `name`, `domain`,
+`path` (`'/'`), `sameSite` (`'lax'`) and `secure` (`true`). This package
+writes it with `accounts.cookie.serialize`, so they are set in one place.
+
+## An outage is not anonymous
+
+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).
+
+Routes declared before `session()` do not call the store, and keep
+answering.
+
+## Testing it
+
+`app.request` calls the app in process; `fixedClock` moves time.
+
+```ts
+import { expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { session } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher({ cost: 10 }), // fast in tests
+});
+const app = alxia()
+	.use(session(accounts, { required: true }))
+	.get('/me', ({ user, reply }) => reply(200, { email: user.email }));
+
+test('the session reads the user, and anonymous is a 401', async () => {
+	const { token } = await accounts.signUp({ email: 'ada@example.com', password: 'correct horse' });
+	const me = await app.request('/me', { headers: { authorization: `Bearer ${token}` } });
+	expect(await me.json()).toEqual({ email: 'ada@example.com' });
+	expect((await app.request('/me')).status).toBe(401);
+});
+```
+
+## Signature
+
+```ts
+function session<A extends Auth<{ readonly type: string }>, const T extends 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>
+>;
+
+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
+>;
+
+function session<A extends Auth<{ readonly type: string }>, const T extends 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>
+>;
+
+interface SessionOptions<T extends string> {
+	readonly type?: T;
+	readonly required?: boolean;
+	/** The device cookie `ctx.auth.device` reads and `ctx.auth.send` sets. */
+	readonly device?: DeviceCookieOptions;
+}
+
+interface UnauthenticatedBody {
+	readonly error: 'unauthenticated';
+}
+
+/** The part of janus() this package calls: what any janus() instance answers. */
+type Auth<U extends { readonly type: string }> = Pick<SharedApi<U>, 'authenticate' | 'signOut' | 'cookie'>;
+
+/** The users a janus() instance knows, as a union narrowed by user.type. */
+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
+`SharedApi` are `@nxgt/janus`'s.
+
+Next: [Signing in and out](sign-in-and-out.md) sets the cookie this plugin
+reads.

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

@@ -0,0 +1,340 @@
+# Signing in and out
+
+This page covers `ctx.auth`, the request's half of signing in and out —
+`send` after a sign-up or a sign-in, `signOut`, and `device`, the device
+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 { janusErrors, session } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+const SignUp = z.object({ email: z.string(), name: z.string(), password: z.string() });
+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 }) => {
+		const signedUp = await accounts.signUp(body);
+		return reply.created({ id: auth.send(signedUp).id });
+	})
+	.post('/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+		const signedIn = await accounts.signIn(body);
+		return reply.ok({ id: auth.send(signedIn).id });
+	})
+	.post('/signout', async ({ auth, reply }) => reply.ok(await auth.signOut()));
+```
+
+**The sign-in itself stays on your `janus()` instance**: `accounts.signIn`,
+`accounts.signUp`, `accounts.patient.signIn` for a user type, a sign-in by code or
+by link — each flow has its own arguments, so the context does not wrap
+them. `ctx.auth` does what comes after: the cookies.
+
+**Behind a `session()` that is not required.** `ctx.auth` exists only on
+routes declared after `session()`, and behind `required: true` an
+anonymous request — anyone signing in — is answered 401 before the route
+runs. [Sessions](sessions.md#where-the-sign-in-routes-go) shows the layout
+with a required group after the sign-in routes.
+
+## `ctx.auth.send(signedIn)`
+
+Appends the session cookie to the response — `accounts.cookie.serialize(token,
+session)` — and returns `signedIn.user`. **The token goes in the cookie,
+never in the body**: answer the fields of the user a client needs.
+
+```text
+Set-Cookie: janus-session=yA_6A8zn…; Expires=Fri, 09 Oct 2026 03:50:45 GMT; Path=/; HttpOnly; SameSite=Lax; Secure
+```
+
+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)).
+
+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
+overwrites it with the session the request came in with.
+
+### A user type
+
+With several user types, the flow is the type's; `ctx.auth.send` is the
+same:
+
+```ts
+import { alxia } from '@alxia/core';
+import { janusErrors, session } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	users: {
+		patient: { schema: z.object({ email: z.email(), name: z.string() }), password: { login: 'email' } },
+		staff: { schema: z.object({ username: z.string() }), password: { login: 'username' } },
+	},
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+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 }) => {
+		const signedIn = await accounts.patient.signIn(body);
+		return reply.ok({ id: auth.send(signedIn).id });
+	});
+```
+
+### A second factor
+
+With `janus({ secondFactor })`, `signIn` answers either a session or a
+challenge, and `send` refuses the union at compile time
+([troubleshooting](../troubleshooting.md#type-secondfactorrequired-is-missing-the-following-properties-from-type-sessionopeneduser-token-session-user)).
+Switch on `status` first:
+
+```ts
+.post('/signin', { 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 });
+	}
+	return reply.ok({ status: result.status, id: auth.send(result).id });
+})
+```
+
+The challenge is a secret like a session token; `@nxgt/janus`'s
+second-factor guide says where to keep it and how to confirm it.
+
+## `ctx.auth.signOut()`
+
+Revokes the session the request presents — cookie, bearer or
+`X-Session-Token` — and clears the session cookie, **whatever the answer**,
+so a browser holding a stale cookie drops it too. It resolves to `true`
+when a session was revoked, `false` when the request presented none or an
+unknown one.
+
+```ts
+const out = await app.request('/signout', { method: 'POST', headers: { cookie: `janus-session=${token}` } });
+await out.json();             // true
+out.headers.getSetCookie();   // ['janus-session=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0; Path=/; HttpOnly; SameSite=Lax; Secure']
+
+const again = await app.request('/signout', { method: 'POST' });
+await again.json();           // false, and the cookie is cleared all the same
+```
+
+Behind `session(accounts)`, an anonymous request gets that `false`; behind
+`session(accounts, { required: true })`, it gets a 401 instead. Signing out of
+every device is `accounts.signOutEverywhere(user)`, `@nxgt/janus`'s.
+
+A store that cannot answer makes it throw `STORE_FAILED`, a 503 through
+[`janusErrors()`](errors.md); the cookie is not cleared then.
+
+## Devices
+
+`janus({ devices })` tells a user when their account signs in from a
+device it had not signed in from. The device is a **device token** the
+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 { janusErrors, session } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+	devices: { keys: [{ id: '2026-09', key: Bun.env['DEVICES_KEY'] ?? '' }] }, // openssl rand -base64 32
+});
+
+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 }) => {
+		const signedIn = await accounts.signIn(body, { device: auth.device });
+		return reply.ok({
+			id: auth.send(signedIn).id,
+			newDevice: signedIn.newDevice, // true for a browser with no device cookie
+		});
+	});
+```
+
+A first sign-in sends two cookies; the next one, presenting the device
+cookie, answers `newDevice: false` and sets the device cookie again so it
+lasts another `maxAge`:
+
+```text
+Set-Cookie: janus-session=5f1I36hr…; Expires=…; Path=/; HttpOnly; SameSite=Lax; Secure
+Set-Cookie: janus-device=d1.2026-09.By5A2egs…; Path=/; Max-Age=34560000; Secure; HttpOnly; SameSite=Lax
+```
+
+**Only with `devices`.** `ctx.auth.device` is `null` for a browser with no
+device cookie, and `janus()` treats `{ device: null }` as a device given:
+without `devices`, every such sign-in throws a `TypeError`, a 500
+([troubleshooting](../troubleshooting.md#typeerror-signin-a-device-was-given-but-janus-has-no-devices--pass-devices--keys-)).
+Leave `device` out when `janus()` has no `devices`.
+
+### Another device cookie
+
+`session(accounts, { device })` names the cookie both `ctx.auth.device` reads
+and `ctx.auth.send` sets, so they always agree:
+
+```ts
+const device = { name: 'shop-device', domain: 'example.com' };
+
+alxia()
+	.use(session(accounts, { device }))
+	.post('/signin', { body: SignIn }, async ({ body, auth, reply }) => {
+		const signedIn = await accounts.signIn(body, { device: auth.device });
+		return reply.ok({ id: auth.send(signedIn).id });
+	});
+```
+
+### `DeviceCookieOptions`
+
+Given to `session(accounts, { device })`, to `sendSession` as
+`{ device: { … } }`, or to `sendDevice`:
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `name` | `string` | `'janus-device'` (`DEVICE_COOKIE`) | the cookie's name, read and set |
+| `domain` | `string` | none: the host that set it | the cookie's `Domain` |
+| `path` | `string` | `'/'` | the cookie's `Path` |
+| `sameSite` | `'lax' \| 'strict' \| 'none'` | `'lax'` | the cookie's `SameSite` |
+| `secure` | `boolean` | `true` | the cookie's `Secure` |
+| `maxAge` | `number`, seconds | `34_560_000` (400 days, the most a browser keeps) | the cookie's `Max-Age` |
+
+The cookie is always `HttpOnly`. `DEVICE_COOKIE` is `'janus-device'`, the
+name `@nxgt/janus-hono` uses, so a device one of them remembers, the other
+does too:
+
+```ts
+import { DEVICE_COOKIE } from '@alxia/janus';
+
+DEVICE_COOKIE; // 'janus-device'
+```
+
+## Outside a route: `sendSession`, `signOut`, `deviceOf`
+
+`ctx.auth` is these functions bound to the request. Unbound, they take the
+context and the `janus()` instance, for code that has no `ctx.auth`: a
+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 { deviceOf, janusErrors, sendSession, session, signOut } from '@alxia/janus';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const accounts = janus({
+	user: z.object({ email: z.email(), name: z.string() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+	devices: { keys: [{ id: '2026-09', key: Bun.env['DEVICES_KEY'] ?? '' }] },
+});
+
+const SignIn = z.object({ email: z.string(), password: z.string() });
+
+const app = alxia()
+	.use(janusErrors())
+	.post('/signin', { body: SignIn }, async (ctx) => {
+		const signedIn = await accounts.signIn(ctx.body, { device: deviceOf(ctx) });
+		return ctx.reply.ok({ id: sendSession(ctx, accounts, signedIn).id });
+	})
+	.post('/signout', async (ctx) => ctx.reply.ok(await signOut(ctx, accounts)))
+	.use(session(accounts, { required: true }))
+	.get('/me', ({ user, reply }) => reply.ok({ name: user.name }));
+```
+
+They behave as `ctx.auth.send`, `ctx.auth.signOut` and `ctx.auth.device`
+above. With a device cookie of another name, pass the same options to both
+ends: `deviceOf(ctx, device)` and `sendSession(ctx, accounts, signedIn, { device })`.
+
+### `deviceOf(ctx, options?)`
+
+```ts
+function deviceOf(ctx: { readonly request: Request }, options?: { readonly name?: string }): string | null;
+```
+
+The device cookie's value, or `null` when the request has none or an empty
+one. `options.name` reads a cookie of another name.
+
+### `sendDevice(ctx, token, options?)`
+
+```ts
+function sendDevice(ctx: { readonly set: ResponseSettings }, token: string, options?: DeviceCookieOptions): void;
+```
+
+Sets the device cookie through `ctx.set.cookies`. `send` and `sendSession`
+call it when `signedIn.deviceToken` is a string; call it yourself only for
+a flow that answers a device token without a session.
+
+## Signatures
+
+```ts
+/** auth, on every route after session(). */
+interface RequestAuth {
+	/** The device token the request carries, for signIn(…, { device }): null when none. */
+	readonly device: string | null;
+	/** Sends the session cookie — and the device cookie, with a deviceToken — and answers the user. */
+	send<U>(signedIn: SessionOpened<U>): U;
+	/** Revokes the request's session and clears its cookie. */
+	signOut(): Promise<boolean>;
+}
+
+/** The part of @nxgt/janus's SignedIn — or of signUp's answer — that opens a session. */
+interface SessionOpened<U> extends Pick<SignedIn<U>, 'token' | 'session' | 'user'> {
+	readonly deviceToken?: string | null;
+}
+
+function sendSession<U>(
+	ctx: { readonly set: ResponseSettings },
+	auth: Pick<Auth<{ readonly type: string }>, 'cookie'>,
+	signedIn: SessionOpened<U>,
+	options?: SendSessionOptions,
+): U;
+
+interface SendSessionOptions {
+	readonly device?: DeviceCookieOptions;
+}
+
+function signOut(
+	ctx: { readonly request: Request; readonly set: ResponseSettings },
+	auth: Pick<Auth<{ readonly type: string }>, 'signOut' | 'cookie'>,
+): Promise<boolean>;
+
+interface DeviceCookieOptions {
+	readonly name?: string;
+	readonly domain?: string;
+	readonly path?: string;
+	readonly sameSite?: 'lax' | 'strict' | 'none';
+	readonly secure?: boolean;
+	readonly maxAge?: number;
+}
+
+const DEVICE_COOKIE = 'janus-device';
+```
+
+`ResponseSettings` is `@alxia/core`'s, `Session` is `@nxgt/janus`'s;
+`Auth` is described in [Sessions](sessions.md#signature).