@alxia/react-router 0.12.1 → 0.14.0

package/dist/session/model/step-up-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-up-props.d.ts","sourceRoot":"","sources":["../../../src/session/model/step-up-props.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAY3D"}

package/dist/session/model/step-up.d.ts

@@ -0,0 +1,48 @@
+import type { StepUpVia } from './second-factor';
+import type { StepUpConfirmAnswer, StepUpError, StepUpRequestAnswer } from './step-up-answers';
+/** Where a step-up is. */
+export type StepUpPhase = 'idle' | 'requesting' | 'code' | 'confirming' | 'done';
+export interface StepUpState {
+    readonly phase: StepUpPhase;
+    /** How the challenge held (or the last one) is confirmed. */
+    readonly via?: StepUpVia | undefined;
+    /** The challenge held. A secret: never in a URL, a log or loader data. */
+    readonly challenge?: string | undefined;
+    /** The tries the last refused code left. */
+    readonly attemptsLeft?: number | undefined;
+    /** No try left on an app or recovery code: wait, asking again would fail too. */
+    readonly locked: boolean;
+    readonly error?: StepUpError | undefined;
+    /** The last refusal worded for the page, until the next step or the release. */
+    readonly message?: string | undefined;
+    /** The seconds a throttled request asks to wait before asking again. */
+    readonly retryAfter?: number | undefined;
+    /** A request or a code is in flight. */
+    readonly pending: boolean;
+    /** The last request replaced a challenge that was held. */
+    readonly resent: boolean;
+}
+export type StepUpAction = {
+    readonly type: 'start';
+} | {
+    readonly type: 'requested';
+    readonly answer: StepUpRequestAnswer;
+} | {
+    readonly type: 'submit';
+} | {
+    readonly type: 'confirmed';
+    readonly answer: StepUpConfirmAnswer;
+} | {
+    readonly type: 'release';
+};
+export declare const INITIAL_STEP_UP: StepUpState;
+/**
+ * The step-up's transitions, pure. `start` (a request in flight) forgets the
+ * last error but keeps a challenge held, so a refused "Resend code" leaves
+ * the code form up; a refusal keeps its `message` (and a throttle its
+ * `retryAfter`) until the next step; a granted request replaces the challenge; a code accepted
+ * spends it; an expired or spent one leaves "ask again"; at 0 tries left a
+ * mailed code is `expired` and an app or recovery code is `locked`.
+ */
+export declare function stepUpReducer(state: StepUpState, action: StepUpAction): StepUpState;
+//# sourceMappingURL=step-up.d.ts.map

package/dist/session/model/step-up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-up.d.ts","sourceRoot":"","sources":["../../../src/session/model/step-up.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EACX,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,MAAM,mBAAmB,CAAC;AAE3B,0BAA0B;AAC1B,MAAM,MAAM,WAAW,GACpB,MAAM,GACN,YAAY,GACZ,MAAM,GACN,YAAY,GACZ,MAAM,CAAC;AAEV,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEhC,eAAO,MAAM,eAAe,EAAE,WAK7B,CAAC;AA2DF;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,YAAY,GAClB,WAAW,CAoCb"}

package/dist/session/second-factor.d.ts

@@ -0,0 +1,22 @@
+import type { FlowContext, SignInAnswer, SignInFlow } from './flow-types';
+import type { SecondFactorKind } from './model';
+/**
+ * The code a second-factor page posted, with how it is given
+ * (`{ kind: 'code' | 'recovery', code }`, the code at most 40 characters). A
+ * native form post goes back to its page, which then posts JSON; a
+ * cross-site post is a 403; a body of another shape is a 400.
+ */
+export declare function readCodeInput<L extends string>({ options }: FlowContext<L>, request: Request): Promise<{
+    kind: SecondFactorKind;
+    code: string;
+}>;
+/**
+ * The code against the sign-in's challenge: an issued code (an app's, or
+ * the one mailed) is confirmed, a recovery code is recovered. Either
+ * answers like a sign-in.
+ */
+export declare function codeStep(input: {
+    readonly kind: SecondFactorKind;
+    readonly code: string;
+}, challenge: string, steps: Parameters<SignInFlow<string>['codeStep']>[2]): Promise<SignInAnswer>;
+//# sourceMappingURL=second-factor.d.ts.map

package/dist/session/second-factor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"second-factor.d.ts","sourceRoot":"","sources":["../../src/session/second-factor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAQhD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,EACnD,EAAE,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,GACd,OAAO,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACvB,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjE,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAClD,OAAO,CAAC,YAAY,CAAC,CAIvB"}

package/dist/session/serialize.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The bytes of a cookie, and the reading of one: `Name=v; Max-Age=n; Path=/;
+ * HttpOnly[; Secure]; SameSite=Lax`, in this order, so a session set by an
+ * app before it adopted this package is still read after, and the other way
+ * round.
+ */
+export interface SerializeOptions {
+    /** Seconds; floored, and never below 0 (0 removes the cookie, and so does a value that is not finite). */
+    readonly maxAge: number;
+    /** `/` by default. */
+    readonly path?: string | undefined;
+    /** Adds `Secure`. Required: it is never read from the environment. */
+    readonly secure: boolean;
+}
+/** Whether `name` can name a cookie (an RFC 6265 token). */
+export declare const isCookieName: (name: string) => boolean;
+/** Whether `path` can be a cookie's `Path`: absolute, no `;`, no control character. */
+export declare const isCookiePath: (path: string) => boolean;
+/**
+ * A `Set-Cookie` value: always `HttpOnly` and `SameSite=Lax`, `Secure` when
+ * asked. A name or a path that could open another attribute throws a
+ * `TypeError`; a `maxAge` that is not finite is 0.
+ */
+export declare function serializeCookie(name: string, value: string, { maxAge, path, secure }: SerializeOptions): string;
+/**
+ * A cookie of the request: the first one of that name that is not empty,
+ * decoded; `null` when there is none, or when it is not valid percent-encoding.
+ */
+export declare function readCookie(request: Request, name: string): string | null;
+/** An instant as milliseconds; 0 when it is not a date. */
+export declare function millisOf(at: string | Date): number;
+/** Seconds from `now` until `expiresAt`: 0 when past or unreadable. */
+export declare function secondsUntil(expiresAt: string | Date, now?: number): number;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/session/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/session/serialize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,gBAAgB;IAChC,0GAA0G;IAC1G,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sBAAsB;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAQD,4DAA4D;AAC5D,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,OAA2B,CAAC;AACxE,uFAAuF;AACvF,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,OAA0B,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,EAAE,MAAM,EAAE,IAAU,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAC9C,MAAM,CAmBR;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAaxE;AAED,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGlD;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,GAAG,GAAE,MAAmB,GACtB,MAAM,CAGR"}

package/dist/session/sign-in.d.ts

@@ -0,0 +1,17 @@
+import type { SignInFlow, SignInFlowOptions } from './flow-types';
+/**
+ * The server side of a BFF's sign-in, over the cookies, the app's
+ * `createApiErrors` and its `jsonActions`: where an answer lands, the form
+ * steps with their refusals, the second factor, the viewer and sign-out.
+ * Built once, beside the app's cookies; it speaks `@nxgt/janus`'s words
+ * (`signedIn`, `secondFactor`, `CODE_INVALID`) and the app maps its API's.
+ *
+ * @example
+ * export const signIn = signInFlow({
+ * 	cookies, errors, json,
+ * 	revoke: (token, request) => execute(SignOutMutation, {}, { token }),
+ * 	attemptsLeft: (count, language) => t('auth.attempts-left', { count }, language),
+ * });
+ */
+export declare function signInFlow<L extends string>(options: SignInFlowOptions<L>): SignInFlow<L>;
+//# sourceMappingURL=sign-in.d.ts.map

package/dist/session/sign-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign-in.d.ts","sourceRoot":"","sources":["../../src/session/sign-in.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAqC/E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAC1C,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,UAAU,CAAC,CAAC,CAAC,CA0Bf"}

package/dist/session/step-up-codes.d.ts

@@ -0,0 +1,9 @@
+/** `@nxgt/janus`'s code for a mutation that needs a recent step-up. */
+export declare const STEP_UP_REQUIRED = "STEP_UP_REQUIRED";
+/**
+ * The codes that end a step-up's challenge: unknown, spent, expired or stale,
+ * and a second factor that changed since the request (`SECOND_FACTOR_ACTIVE`,
+ * `SECOND_FACTOR_NOT_ENROLLED`). The user asks again.
+ */
+export declare const STEP_UP_OVER: readonly ["TOKEN_UNKNOWN", "TOKEN_SPENT", "TOKEN_EXPIRED", "TOKEN_STALE", "SECOND_FACTOR_ACTIVE", "SECOND_FACTOR_NOT_ENROLLED"];
+//# sourceMappingURL=step-up-codes.d.ts.map

package/dist/session/step-up-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-up-codes.d.ts","sourceRoot":"","sources":["../../src/session/step-up-codes.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,YAAY,iIAKf,CAAC"}

package/dist/session/step-up-types.d.ts

@@ -0,0 +1,69 @@
+import type { data } from 'react-router';
+import type { ApiErrorLike } from '../errors/api-error';
+import type { SignInCodes, SignInFlow } from './flow-types';
+import type { StepUpConfirmAnswer, StepUpRequestAnswer, StepUpVia } from './model';
+/** The codes the step-up tells apart; `@nxgt/janus`'s by default. */
+export interface StepUpCodes extends SignInCodes {
+    /** The code of a mutation that needs a step-up first (`'STEP_UP_REQUIRED'`). */
+    readonly stepUpRequired?: string | undefined;
+    /** The code of a mail the API holds back (`'MAIL_THROTTLED'`): `request` answers `error: 'throttled'`. */
+    readonly mailThrottled?: string | undefined;
+}
+export interface StepUpStepsOptions<L extends string> {
+    /**
+     * The app's sign-in flow: the step-up reads its `errors`, its `json` (a
+     * step runs only for a same-site JSON post) and its `attemptsLeft`.
+     */
+    readonly signIn: SignInFlow<L>;
+    /** A challenge that is over, worded ("ask for a new code"). */
+    spent(language: L): string;
+    /**
+     * What an app or recovery code with no try left adds to its message: the
+     * account is locked, wait (asking again would fail too).
+     */
+    readonly locked?: ((language: L) => string) | undefined;
+    /**
+     * The app's own words for a refusal that is not a code's (a mail
+     * throttle's wait, say), before `errors`' default. `undefined` keeps the
+     * default.
+     */
+    readonly wording?: ((error: ApiErrorLike, language: L) => string | undefined) | undefined;
+    readonly codes?: StepUpCodes | undefined;
+}
+/** An answer that stays on the page: the answer, with the API's status. */
+export type StepUpStayed<T> = ReturnType<typeof data<T>>;
+/**
+ * What each step takes beside `run`: the request, whose headers must be a
+ * same-site JSON post's (a native form post goes back to its page, another
+ * site is a 403), and the language of the wording.
+ */
+export interface StepUpCall<L extends string> {
+    readonly request: Request;
+    readonly language: L;
+}
+export interface StepUpSteps<L extends string> {
+    /**
+     * Starts a step-up (`requestStepUp`): the challenge and how it is
+     * confirmed. The challenge goes to the page's fetcher and nowhere else.
+     * A refusal is `error: 'failed'` with the
+     * message and the API's status, and a throttled mail `error: 'throttled'`,
+     * with `retryAfter` when the API says how long; an API it cannot reach is a 503. Anything
+     * that is not an API failure is thrown. Only a same-site JSON post goes on.
+     */
+    request(run: () => Promise<{
+        readonly challenge: string;
+        readonly via: StepUpVia;
+    }>, options: StepUpCall<L>): Promise<StepUpRequestAnswer | StepUpStayed<StepUpRequestAnswer>>;
+    /**
+     * Confirms the step-up with the code (`confirmStepUp`). A refusal says
+     * why: `invalid` with the tries left, `expired` (ask again), or `failed`;
+     * with no try left, a mailed code (`via: 'email'`, or not given) is
+     * `expired` and an app or recovery code is `locked`.
+     */
+    confirm(run: () => Promise<unknown>, options: StepUpCall<L> & {
+        readonly via?: StepUpVia | undefined;
+    }): Promise<StepUpConfirmAnswer | StepUpStayed<StepUpConfirmAnswer>>;
+    /** Whether `error` is the API asking for a step-up first. */
+    isStepUpRequired(error: unknown): boolean;
+}
+//# sourceMappingURL=step-up-types.d.ts.map

package/dist/session/step-up-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-up-types.d.ts","sourceRoot":"","sources":["../../src/session/step-up-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EACX,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,MAAM,SAAS,CAAC;AAEjB,qEAAqE;AACrE,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,gFAAgF;IAChF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,0GAA0G;IAC1G,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM;IACnD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EACd,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC,GAC1D,SAAS,CAAC;IACb,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACzC;AAED,2EAA2E;AAC3E,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,MAAM;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;CACrB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM;IAC5C;;;;;;;OAOG;IACH,OAAO,CACN,GAAG,EAAE,MAAM,OAAO,CAAC;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;KAAE,CAAC,EAC3E,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,mBAAmB,GAAG,YAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACpE;;;;;OAKG;IACH,OAAO,CACN,GAAG,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC3B,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG;QAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;KAAE,GAC/D,OAAO,CAAC,mBAAmB,GAAG,YAAY,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACpE,6DAA6D;IAC7D,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CAC1C"}

package/dist/session/step-up.d.ts

@@ -0,0 +1,17 @@
+import type { StepUpSteps, StepUpStepsOptions } from './step-up-types';
+/**
+ * The server side of a BFF's step-up: `request` and `confirm` answer the
+ * page's fetcher with `StepUpRequestAnswer` and `StepUpConfirmAnswer`, which
+ * `stepUpReducer` takes as they are. It speaks `@nxgt/janus`'s words
+ * (`CODE_INVALID`, `TOKEN_*`, `STEP_UP_REQUIRED`); the app maps the rest.
+ *
+ * @example
+ * const stepUp = stepUpSteps({
+ * 	errors,
+ * 	attemptsLeft: (count, language) => t('code.attempts-left', { count }, language),
+ * 	spent: (language) => t('step-up.spent', {}, language),
+ * 	locked: (language) => t('step-up.locked', {}, language),
+ * });
+ */
+export declare function stepUpSteps<L extends string>(options: StepUpStepsOptions<L>): StepUpSteps<L>;
+//# sourceMappingURL=step-up.d.ts.map

package/dist/session/step-up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-up.d.ts","sourceRoot":"","sources":["../../src/session/step-up.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAEX,WAAW,EACX,kBAAkB,EAClB,MAAM,iBAAiB,CAAC;AA8IzB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC3C,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC5B,WAAW,CAAC,CAAC,CAAC,CAQhB"}

package/dist/session/step.d.ts

@@ -0,0 +1,20 @@
+import { type ApiErrorLike } from '../errors/api-error';
+import type { CodeWording, FlowContext, SignInAnswer, SignInFlow, SignInFlowOptions, SignInStayed } from './flow-types';
+/**
+ * A refused code's message, with the tries left when the API counts them;
+ * `undefined` when the challenge is over (gone, or no try left and no
+ * `whenNone` to say instead) and the user must sign in again.
+ */
+export declare function codeRefusal<L extends string>({ options, invalidCode, challengeOver }: CodeWording<L>, error: ApiErrorLike, language: L, whenNone?: string): string | undefined;
+/** What a sign-in says when the API cannot be reached. */
+export declare const unavailableMessage: <L extends string>({ unavailable, errors }: Pick<SignInFlowOptions<L>, "unavailable" | "errors">, language: L) => string;
+/**
+ * Runs a sign-in step and redirects where its answer leads, a new session
+ * replacing the browser's (`landReplacing`). A refusal is the form's
+ * message (a wrong password, a lock with its delay); an unreachable API
+ * says `unavailable`, with a 503.
+ */
+export declare function signInStep<L extends string, T extends object>(context: FlowContext<L>, run: () => Promise<SignInAnswer>, { request, language, next, extra, refused, }: Parameters<SignInFlow<L>['signInStep']>[1] & {
+    extra: T;
+}): Promise<Response | SignInStayed<T>>;
+//# sourceMappingURL=step.d.ts.map

package/dist/session/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/session/step.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,YAAY,EAGjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACX,WAAW,EACX,WAAW,EACX,YAAY,EACZ,UAAU,EACV,iBAAiB,EAEjB,YAAY,EACZ,MAAM,cAAc,CAAC;AAItB;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC3C,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,EACvD,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,CAAC,EACX,QAAQ,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAapB;AAED,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,EAClD,yBAAyB,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,aAAa,GAAG,QAAQ,CAAC,EAC7E,UAAU,CAAC,KACT,MAAwE,CAAC;AAE5E;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAClE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,GAAG,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EAChC,EACC,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,OAAO,GACP,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAA;CAAE,GAC1D,OAAO,CAAC,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAuBrC"}

package/dist/session/viewer.d.ts

@@ -0,0 +1,33 @@
+import type { FlowContext } from './flow-types';
+/** The `next` a sign-in page was opened with, safe to redirect to. */
+export declare const nextParam: (request: Request) => string;
+/**
+ * The sign-in page, coming back to this request's page afterwards, with the
+ * session cookie cleared: what a page answers without a (live) session. A
+ * request that carried a session cookie says it ended when `endedParam` is
+ * set.
+ */
+export declare function signInRedirect<L extends string>({ options, paths }: FlowContext<L>, request: Request): Response;
+/**
+ * For the sign-in pages: the viewer when the cookie holds a live session,
+ * `null` when the API refuses it (a 401), `undefined` without a cookie or
+ * when the API cannot tell.
+ */
+export declare function viewer<L extends string, V>({ options }: FlowContext<L>, request: Request, read: (token: string) => Promise<V | null>, token?: string | null | undefined): Promise<V | null | undefined>;
+/**
+ * The signed-in viewer, else the sign-in redirect. Its `headers` move the
+ * cookie's expiry to the session's when the API moved it.
+ */
+export declare function requireViewer<L extends string, V>(context: FlowContext<L>, request: Request, read: (token: string) => Promise<V | null>, expiresAt: (viewer: V) => string | null): Promise<{
+    viewer: V;
+    headers: HeadersInit;
+}>;
+/**
+ * Ends the session and goes to the sign-in page (`?signed-out=1`), or to
+ * `to`. The body is read as JSON first: JSON and same-origin only, so
+ * another site cannot sign the user out.
+ */
+export declare function signOut<L extends string>(context: FlowContext<L>, request: Request, { to }?: {
+    readonly to?: string | undefined;
+}): Promise<Response>;
+//# sourceMappingURL=viewer.d.ts.map

package/dist/session/viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.d.ts","sourceRoot":"","sources":["../../src/session/viewer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAIhD,sEAAsE;AACtE,eAAO,MAAM,SAAS,GAAI,SAAS,OAAO,KAAG,MACW,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC9C,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,EAClC,OAAO,EAAE,OAAO,GACd,QAAQ,CAWV;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAC/C,EAAE,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC1C,KAAK,GAAE,MAAM,GAAG,IAAI,GAAG,SAA0C,GAC/D,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAO/B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EACtD,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC1C,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GACrC,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,CAiB9C;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,CAAC,SAAS,MAAM,EAC7C,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,EAAE,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAO,GAC/C,OAAO,CAAC,QAAQ,CAAC,CAcnB"}

package/docs/README.md

@@ -19,6 +19,7 @@ installable and usable offline, wording an API's refusals, and what to do with e
 | [Deploying](guide/deploying.md) | running the build with `bun build/server/index.js`, and the Docker image |
 | [Installable and offline](guide/pwa.md) | making the app installable and usable offline: the subpaths of `@alxia/react-router/pwa`, the service worker (`startWorker`, `/pwa/worker`), its build by `alxia()` or `buildWorker` (`/pwa/build`), its contract and cache names, which requests the worker caches and which responses it stores, the precache list read from a build, or clearing the caches at sign-out |
 | [An API's refusals](guide/errors.md) | wording a GraphQL API's refusals for the pages: recognising an `ApiError`, the request id, the page a request is for, the catalogue store, the form checks in the API's words, the provider, and the loaders, the error page and the actions that answer with it, the JSON actions with their CSRF check and fetcher hook, calling the API from a loader (`apiCallFailure`), and keeping the catalogue fresh (`@alxia/react-router/errors`) |
+| [A BFF session](guide/session.md) | redirecting after sign-in to a page of the site and nowhere else, the sign-in pages' paths, the session's cookies, the sign-in flow (where an answer lands, a refused code, the viewer, sign-out; `@alxia/react-router/session`), the pages a mail's link opens (a magic link, a password reset: `authLinks`), and the step-up's state and the props it gives the UI (`@alxia/react-router/session/model`) |
 | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message, or a page streams, hydrates or reads its context unlike you expected |
 | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |
 

package/docs/guide/errors.md

@@ -29,6 +29,7 @@ import is `react-router`, never `@alxia/core`, so a page can import it
 | `ApiErrorLike`, `isApiErrorLike(error)` | the shape of `@nxgt/graphql-client`'s `ApiError`, and the test for it |
 | `ApiErrorEntryLike`, `ApiErrorExtensionsLike`, `ApiErrorParamsLike`, `ApiFieldErrorLike` | one error of the response, its `extensions`, their `params`, and one refused field |
 | `waitMinutes(extensions)` | the minutes of a throttle's wait: `minutes` (at least one), else `retryAfter` rounded up to minutes |
+| `attemptsLeftOf(error)` | the tries a refused code leaves, as `@nxgt/janus` counts them: `extensions.attemptsLeft` of the first error, else `params.attemptsLeft`; `undefined` when it is not a whole number from 0 up |
 | `REQUEST_ID_HEADER`, `requestIdOf(response)` | the header an API echoes on every response, and its value |
 | `nextOf(url)` | the page a request is for, as `next` carries it back after sign-in |
 | `FormErrors` | what a form action answers when the API refused the input |
@@ -73,6 +74,24 @@ waitMinutes({ retryAfter: 90 }); // 2
 waitMinutes({ params: { minutes: 4 } }); // 4
 ```
 
+### The tries a code leaves
+
+A wrong second-factor or step-up code is refused with `@nxgt/janus`'s
+`CODE_INVALID` and the tries left in `extensions.attemptsLeft`.
+`attemptsLeftOf(error)` reads that count from the first error, else from its
+`params`, and answers `undefined` for anything that is not a whole number from
+0 up (a string, a negative number, a missing key). `0` is a count: no try is
+left.
+
+```ts
+import { attemptsLeftOf } from '@alxia/react-router/errors';
+
+attemptsLeftOf(error); // 3 after a wrong code, 0 on the last, undefined if uncounted
+```
+
+[`signInFlow`'s `codeRefusal`](session.md#the-second-factor) words it for a
+sign-in's code page.
+
 ## The request id
 
 An API that echoes `x-request-id` lets a page tell the user which request
@@ -323,6 +342,32 @@ catalogue, then the API's own message. `fieldErrors` uses the same order for
 a single `extensions.field`, while the entries of `extensions.fields` go
 straight to the catalogue.
 
+`reword` words a whole family of codes once, after the text is worded, so
+there is no list of codes to keep in step with the catalogue. It receives the
+final text, the error, and `{ code, values, language }`: `values` are the
+merged values the catalogue formats with (`extensions` and
+`extensions.params`, the params winning). Return the text to show, or
+`undefined` to keep it:
+
+```ts
+export const apiErrors = createApiErrors<'en' | 'fr'>({
+	messages: apiMessages,
+	unavailable: (language) => translate('app.error.unavailable', language),
+	reword: (text, error, { code }) =>
+		code.endsWith('.errors.referenced')
+			? `${text} ${stillLinkedTo(error)}`
+			: undefined,
+});
+```
+
+`reword` sees the text `apiErrorMessage` returns for an error with a code,
+whichever produced it: the catalogue, the API's own message, or `byCode`; so
+`apiRefusal`, `fetcherResult`, `fetcherRefusal`, `submitForm` and a single
+`extensions.field` are reworded too. It does not see `refused`'s text (an
+error with no API code), `unavailable`'s (a network failure, which is no API
+code), `translateCode`'s, nor the entries of `extensions.fields`, which go
+straight to the catalogue.
+
 `isApiCode` changes what counts as an API code (`<module>.errors.<slug>` by
 default). Here only the codes of the `todos` module are the catalogue's; any
 other code, even one shaped like a catalogue code, says `refused`: