@alxia/janus 0.1.0

package/dist/permission.d.ts

@@ -0,0 +1,52 @@
+import { type BaseContext, type RequiresOf } from '@alxia/core';
+import type { CheckableOf, ModelConfig, ObjectTypeOf, Permissions } from '@nxgt/janus/permissions';
+import type { Awaitable, ObjectData, OptionsArgs } from './permission-options';
+/** The body of each refusal. */
+export interface PermissionRefusedBody {
+    readonly error: 'unauthenticated' | 'not_found' | 'forbidden';
+}
+/**
+ * A guard, as a plugin: the routes declared after it run only if the
+ * subject holds `permission` on an object of `type`. It loads the object
+ * once, checks it with `access.can`, and hands it to them as `object`.
+ *
+ * | the request | answered |
+ * | --- | --- |
+ * | anonymous | 401 — before the object is loaded |
+ * | `load` answers `null` | 404 |
+ * | a denial | 403 |
+ * | allowed | the route runs, `object` set |
+ *
+ * Each refusal is typed on those routes. **A failure throws**: a store that
+ * cannot answer is `STORE_FAILED`, never a 403 — `janusErrors()` answers
+ * it 503. Scope it with `group`, so it guards only its routes:
+ *
+ * ```ts
+ * app.use(session(accounts)).group('/records/:id', (records) =>
+ *   records.use(permission(access, 'view', 'record', byParam('id', findRecord)))
+ *     .get('/', ({ object, reply }) => reply(200, object)));
+ * ```
+ */
+export declare function permission<C extends ModelConfig, const T extends ObjectTypeOf<C>, const P extends CheckableOf<C, T>, O extends ObjectData<C, T>, LoadCtx extends object = BaseContext, SubjectCtx extends object = BaseContext, CheckCtx extends object = BaseContext>(access: Pick<Permissions<C>, 'can'>, permission: P, type: T, load: (ctx: BaseContext & LoadCtx) => Awaitable<O | null>, ...options: OptionsArgs<C, T, P, O, SubjectCtx, CheckCtx>): import("@alxia/core").Alxia<RequiresOf<LoadCtx & SubjectCtx & CheckCtx, AnnotatedAny<LoadCtx, SubjectCtx>> & {
+    object: O;
+}, import("@alxia/core").Empty, "", import("@alxia/core").Reply<401, PermissionRefusedBody> | import("@alxia/core").Reply<404, PermissionRefusedBody> | import("@alxia/core").Reply<403, PermissionRefusedBody>> & import("@alxia/core").Requiring<RequiresOf<LoadCtx & SubjectCtx & CheckCtx, AnnotatedAny<LoadCtx, SubjectCtx>>>;
+/**
+ * The callback to name when `RequiresOf` refuses one annotated `any`: `load`
+ * or `subject` when it is that one, `ctx` otherwise. An `any` in any of the
+ * three makes their intersection `any`, so `RequiresOf` cannot tell which;
+ * a `Record<string, any>` passes the same test.
+ */
+type AnnotatedAny<LoadCtx, SubjectCtx> = [LoadCtx] extends [
+    {
+        readonly '~any': 1;
+    }
+] ? 'load' : [SubjectCtx] extends [{
+    readonly '~any': 1;
+}] ? 'subject' : 'ctx';
+/**
+ * A `load` reading one path parameter, as it arrived: `find(id)`, or `null`
+ * — a 404 — when the route has no such parameter.
+ */
+export declare function byParam<O>(name: string, find: (id: string) => Awaitable<O | null>): (ctx: BaseContext) => Awaitable<O | null>;
+export {};
+//# sourceMappingURL=permission.d.ts.map

package/dist/permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,KAAK,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,WAAW,EAEX,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE/E,gCAAgC;AAChC,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC;CAC9D;AASD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CACzB,CAAC,SAAS,WAAW,EACrB,KAAK,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAC/B,KAAK,CAAC,CAAC,SAAS,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EACjC,CAAC,SAAS,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,OAAO,SAAS,MAAM,GAAG,WAAW,EACpC,UAAU,SAAS,MAAM,GAAG,WAAW,EACvC,QAAQ,SAAS,MAAM,GAAG,WAAW,EAErC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EACnC,UAAU,EAAE,CAAC,EACb,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EACzD,GAAG,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC;;mUAoCzD;AAED;;;;;GAKG;AACH,KAAK,YAAY,CAAC,OAAO,EAAE,UAAU,IAAI,CAAC,OAAO,CAAC,SAAS;IAC1D;QAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;KAAE;CACtB,GACE,MAAM,GACN,CAAC,UAAU,CAAC,SAAS,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,GAC5C,SAAS,GACT,KAAK,CAAC;AAEV;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,GACvC,CAAC,GAAG,EAAE,WAAW,KAAK,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAK3C"}

package/dist/send.d.ts

@@ -0,0 +1,34 @@
+import type { ResponseSettings } from '@alxia/core';
+import { type DeviceCookieOptions } from './device';
+import type { Auth, SessionOpened } from './types';
+/** What `sendSession` takes besides: the device cookie's options. */
+export interface SendSessionOptions {
+    readonly device?: DeviceCookieOptions;
+}
+/**
+ * Sends the session cookie — after `signUp`, `signIn`, anything that
+ * answered a token and its session — and answers the user. The token is in
+ * the cookie, never in the body. With a `deviceToken`, the device cookie
+ * too.
+ *
+ * ```ts
+ * const signedIn = await auth.signIn(body, { device: deviceOf(ctx) });
+ * return reply(200, { id: sendSession(ctx, auth, signedIn).id });
+ * ```
+ */
+export declare function sendSession<U>(ctx: {
+    readonly set: ResponseSettings;
+}, auth: Pick<Auth<{
+    readonly type: string;
+}>, 'cookie'>, signedIn: SessionOpened<U>, options?: SendSessionOptions): U;
+/**
+ * Revokes the session the request presents and clears the cookie — cleared
+ * whatever the answer, so a browser holding a stale cookie drops it too.
+ */
+export declare function signOut(ctx: {
+    readonly request: Request;
+    readonly set: ResponseSettings;
+}, auth: Pick<Auth<{
+    readonly type: string;
+}>, 'signOut' | 'cookie'>): Promise<boolean>;
+//# sourceMappingURL=send.d.ts.map

package/dist/send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../src/send.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,KAAK,mBAAmB,EAAc,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEnD,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,GAAG,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAA;CAAE,EACvC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,QAAQ,CAAC,EACrD,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,EAC1B,OAAO,GAAE,kBAAuB,GAC9B,CAAC,CASH;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC5B,GAAG,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAA;CAAE,EAClE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,GAC/D,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/session.d.ts

@@ -0,0 +1,67 @@
+import { type Alxia, type Empty, type Reply } from '@alxia/core';
+import type { Session } from '@nxgt/janus';
+import { type DeviceCookieOptions } from './device';
+import type { Auth, RequestAuth, UserOfAuth } from './types';
+export interface SessionOptions<T extends string> {
+    /** Only a user of this type is authenticated here; any other is anonymous. */
+    readonly type?: T;
+    /**
+     * `true`: an anonymous request is answered 401 and the route never runs,
+     * so `user` is never `null` in it — and the 401 is in its type. A
+     * `boolean` known only at runtime keeps the 401 in the type, and `user`
+     * may be `null`.
+     */
+    readonly required?: boolean;
+    /** The device cookie `auth.device` reads and `auth.send` sets. */
+    readonly device?: DeviceCookieOptions;
+}
+/** The body of the 401 a required session answers. */
+export interface UnauthenticatedBody {
+    readonly error: 'unauthenticated';
+}
+type UserOf<A, T> = Extract<UserOfAuth<A>, {
+    readonly type: T;
+}>;
+/**
+ * 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`.
+ *
+ * **An outage is not anonymous**: a store that cannot answer throws
+ * `STORE_FAILED`, which `janusErrors()` 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));
+ * ```
+ */
+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>>;
+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>;
+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>>;
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+import type { SharedApi, SignedIn } from '@nxgt/janus';
+/** Anything `janus()` answered: the part of it this package calls. */
+export type Auth<U extends {
+    readonly type: string;
+}> = Pick<SharedApi<U>, 'authenticate' | 'signOut' | 'cookie'>;
+/** The users an `auth` instance knows, as a union narrowed by `user.type`. */
+export type UserOfAuth<A> = A extends Auth<infer U> ? U : never;
+/**
+ * What `sendSession` takes: the part of `@nxgt/janus`'s `SignedIn` — or of
+ * `signUp`'s answer — that opens a session.
+ */
+export interface SessionOpened<U> extends Pick<SignedIn<U>, 'token' | 'session' | 'user'> {
+    readonly deviceToken?: string | null;
+}
+/**
+ * What the routes behind `session()` call, bound to their request: no
+ * `ctx`, no `Auth` to pass.
+ *
+ * ```ts
+ * const signedIn = await accounts.patient.signIn(body, { device: auth.device });
+ * return reply.ok({ id: auth.send(signedIn).id });
+ * ```
+ */
+export 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: `sendSession`, bound.
+     */
+    send<U>(signedIn: SessionOpened<U>): U;
+    /** Revokes the request's session and clears its cookie: `signOut`, bound. */
+    signOut(): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvD,sEAAsE;AACtE,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,IAAI,IAAI,CAC3D,SAAS,CAAC,CAAC,CAAC,EACZ,cAAc,GAAG,SAAS,GAAG,QAAQ,CACrC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAC/B,SAAQ,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACvC,6EAA6E;IAC7E,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B"}

package/docs/README.md

@@ -0,0 +1,16 @@
+# @alxia/janus documentation
+
+The [package README](../README.md) is the short version. This folder is
+the long one: a guide page per area, with the options, defaults, errors and
+a realistic example for each.
+
+## Guide
+
+| Page | Read it when |
+| --- | --- |
+| [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 |
+| [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 |

package/docs/guide/errors.md

@@ -0,0 +1,176 @@
+# Errors
+
+This page covers `janusErrors()`: the plugin 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 { 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', minLength: 12 },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+const SignUp = z.object({ email: z.string(), name: z.string(), password: z.string() });
+
+const app = alxia()
+	.use(janusErrors())
+	.use(session(accounts))
+	.post('/signup', { 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.
+
+```text
+400 {"code":"PASSWORD_TOO_SHORT","minLength":12}
+400 {"code":"USER_INVALID","issues":[{"path":["email"],"message":"Invalid email address"}]}
+409 {"code":"LOGIN_TAKEN"}
+401 {"code":"CREDENTIALS_INVALID"}
+401 {"code":"CREDENTIALS_INVALID","retryAfter":900}      + Retry-After: 900
+503 {"code":"STORE_FAILED"}
+```
+
+## 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"}`.
+
+It answers only a `JanusError`. Anything else goes on to the app's next
+`onError`, or its 500.
+
+## Statuses
+
+`statusOf(code)` is `@nxgt/janus`'s, re-exported:
+
+| Status | Codes |
+| --- | --- |
+| 400 | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `HASH_UNSUPPORTED`, `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE`, `INVALID_CURSOR` |
+| 401 | `CREDENTIALS_INVALID`, `CODE_INVALID` |
+| 403 | `USER_INACTIVE`, `STEP_UP_REQUIRED` |
+| 404 | `NOT_FOUND` |
+| 409 | `LOGIN_TAKEN`, `VERSION_CONFLICT`, `SECOND_FACTOR_NOT_ENROLLED`, `SECOND_FACTOR_ACTIVE` |
+| 500 | `PERMISSION_DEPTH` — a permission check walked past `maxDepth`: not a denial |
+| 501 | `UNSUPPORTED` — a wiring mistake: a store lacks a method a flow needs |
+| 503 | `STORE_FAILED` — **an outage, never a 401 or a 404** |
+
+```ts
+import { statusOf } from '@alxia/janus';
+
+statusOf('STORE_FAILED'); // 503
+statusOf('TOKEN_SPENT');  // 400
+```
+
+## Bodies
+
+`bodyOf(error)` is the body: the `code`, and only what a client can act on.
+**Never** the login, the `reason`, a hash prefix or a cause — those are for
+your logs, and stay on the `JanusError`.
+
+| Code | Body |
+| --- | --- |
+| `USER_INVALID` | `{ code, issues }` — `issues` is `[]` when the error carries none |
+| `PASSWORD_TOO_SHORT` | `{ code, minLength? }` |
+| `CODE_INVALID` | `{ code, attemptsLeft? }` |
+| `CREDENTIALS_INVALID` | `{ code, retryAfter? }` — seconds; also sent as `Retry-After` |
+| every other code | `{ code }` |
+
+```ts
+import { bodyOf } from '@alxia/janus';
+import { NotFoundError } from '@nxgt/janus';
+
+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
+`Retry-After` header.
+
+## Reporting the 5xx
+
+```ts
+const app = alxia().use(
+	janusErrors({
+		report: (error, ctx) => console.error(`${ctx.route}: ${error.code}`, error.cause),
+	}),
+);
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `report` | `(error: JanusError, ctx: BaseContext) => unknown` | none | called with every `JanusError` answered 500, 501 or 503 — `STORE_FAILED`, `UNSUPPORTED`, `PERMISSION_DEPTH` — the server's to fix |
+
+`report` is started as the error is answered, not awaited: a slow report
+never holds the response, and it cannot change the answer. One that throws
+or rejects is a process warning, and the 503 is sent all the same:
+
+```text
+(node:13837) Warning: janusErrors(): report failed: Error: boom
+```
+
+The 4xx are not reported: they are the client's.
+
+## On the client
+
+The refusals are in the type of every route after the plugin, so
+`@alxia/client` reads them. 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:
+
+```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 }))
+	.get('/me', ({ user, reply }) => reply(200, { name: user.name }));
+
+const me = await client(app).get('/me');
+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 (me.status === 503) console.log(me.data.code);          // 'STORE_FAILED' and the like: try again later
+```
+
+## Signatures
+
+```ts
+function janusErrors(options?: JanusErrorsOptions): Alxia<Empty, Empty, '', Reply<JanusErrorStatus, JanusErrorBody>>;
+
+interface JanusErrorsOptions {
+	readonly report?: (error: JanusError, ctx: BaseContext) => unknown;
+}
+
+function bodyOf(error: JanusError): JanusErrorBody;
+
+interface JanusErrorBody {
+	readonly code: JanusErrorCode;
+	readonly issues?: JanusError['issues'];
+	readonly minLength?: number;
+	readonly attemptsLeft?: number;
+	readonly retryAfter?: number;
+}
+
+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.
+
+The permission guard's own refusals — `{ error: 'forbidden' }` and the
+like — are not `JanusError`s; see [Permissions](permissions.md#refusals).