@nxgt/janus 0.10.0 → 0.12.0

package/dist/permissions/index.js

@@ -4,15 +4,15 @@ import {
   UNSTORABLE,
   MAX_PAGE_SIZE2,
   pageLimit2
-} from "../chunks/index-5tm04t5p.js";
+} from "../chunks/index-jp2kka6d.js";
 import {
   PermissionDepthError2,
   isSetOf2,
   formatEntity2
-} from "../chunks/index-5e2fw7he.js";
+} from "../chunks/index-j2gd8fry.js";
 import {
   createMemoryRelations2
-} from "../chunks/index-6f6wja93.js";
+} from "../chunks/index-km7ffctx.js";
 
 // src/permissions/resolve/resolved.ts
 function admits(holders, subject) {

package/docs/README.md

@@ -16,6 +16,7 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [E-mail verification and password reset](guide/email-flows.md) | You are sending a verification or reset link, and handling what comes back |
 | [Signing in with an e-mailed code](guide/sign-in-code.md) | You are signing users in with a six-digit code sent by e-mail — with no password, or beside one: requesting it without telling who exists, keeping the challenge, the attempts and the errors |
 | [The second factor](guide/second-factor.md) | You are turning on TOTP codes: making and rotating the sealing keys, the QR code, `signIn`'s `status`, confirming a challenge, recovery codes for a lost phone, disabling |
+| [Step-up](guide/step-up.md) | A sensitive action — changing the e-mail, disabling the second factor, deleting the account — should ask a signed-in user to prove again who they are: `assertFresh`, `stepUp.request` and `confirm`, by e-mailed code or by their app |
 | [User events](guide/events.md) | You want to hear when a user is created, verifies their e-mail, resets their password, turns the second factor on or off, uses a recovery code or is deleted — to queue it, sync it, or send it as a webhook |
 | [Password hashing](guide/passwords.md) | You are choosing a hasher, raising its cost, moving to argon2id, or importing hashes from another system |
 

package/docs/guide/adapters.md

@@ -135,6 +135,7 @@ interface SessionStore {
 	insertSession(record: SessionRecord): Promise<void>;
 	findSessionByTokenHash(tokenHash: string): Promise<SessionRecord | null>;
 	extendSession(id: SessionId, expiresAt: Date): Promise<SessionRecord | null>; // null once revoked
+	reauthenticateSession(id: SessionId, at: Date): Promise<SessionRecord | null>; // authenticatedAt only; null once revoked
 	revokeSession(id: SessionId, at: Date): Promise<boolean>;
 	revokeUserSessions(userId: Id, at: Date, except?: SessionId): Promise<number>;
 	deleteUserSessions(userId: Id): Promise<number>;
@@ -159,14 +160,14 @@ update. A read followed by a write lets two requests redeem one reset token.
 A token is its hash, never its secret, and what it is for:
 
 ```ts
-type TokenKind = 'verifyEmail' | 'resetPassword' | 'secondFactor' | 'signInCode';
+type TokenKind = 'verifyEmail' | 'resetPassword' | 'secondFactor' | 'signInCode' | 'stepUp';
 
 interface TokenRecord {
 	readonly tokenHash: string;
 	readonly kind: TokenKind;
 	readonly userId: Id;
 	readonly address: string; // '' for a secondFactor challenge: nothing was sent
-	readonly codeHash: string | null; // a signInCode's code, hashed; null for every other kind
+	readonly codeHash: string | null; // an e-mailed code, hashed — signInCode, or stepUp by e-mail; else null
 	readonly attempts: number; // 0 at insertion
 	readonly expiresAt: Date;
 	readonly spentAt: Date | null;
@@ -175,7 +176,11 @@ interface TokenRecord {
 ```
 
 A token redeemed for another kind is unknown: every method that takes a
-`kind` matches on it. A `secondFactor` token is the challenge `signIn`
+`kind` matches on it. A `stepUp` token is a signed-in user's confirmation of
+a sensitive action; kept apart from `signInCode`, a sign-in code never
+confirms an action, nor an action's code signs anyone in. A store that lists
+the kinds — a `CHECK`, an enum in a validator — lists `stepUp` too, which
+`tokens.everyKind` proves. A `secondFactor` token is the challenge `signIn`
 answers — or the count of a user's attempts at `regenerateRecoveryCodes`,
 a token of the same kind whose secret nobody is given, never redeemed and
 only counted — and its `address` is `''`: a column or a validator that refuses an
@@ -190,6 +195,35 @@ expiry — a TTL index, a Redis key TTL — may drop a lapsed session or token
 before anyone asks: reads then answer `null`, and `deleteUserSessions` does
 not count it. The conformance suite accepts both.
 
+### `SessionStore.reauthenticateSession`
+
+Moves `authenticatedAt` to `at` — **only while the session is not revoked**
+— and answers the record as written, every other field as it was. It is
+what a step-up calls once a signed-in user proved again who they are, so
+that "signed in less than ten minutes ago" is one field of the session
+`authenticate` already read. `null` for no session, or a revoked one: a
+confirmation racing a revocation must never bring the session back, so the
+condition is in the write — the same one `extendSession` has:
+
+```ts
+import type { SessionStore } from '@nxgt/janus';
+
+export const reauthenticateSession: SessionStore['reauthenticateSession'] = async (id, at) => {
+	const written = await sessions.findOneAndUpdate(
+		{ _id: id, revokedAt: null },
+		{ $set: { authenticatedAt: at } },
+		{ returnDocument: 'after' },
+	);
+	return written === null ? null : toSession(written);
+};
+```
+
+In SQL, `update … set authenticated_at = $2 where id = $1 and revoked_at is
+null returning *`; in Redis, one Lua script that checks `revokedAt` is empty
+before its `HSET`. The expiry does not move, so neither does a TTL. It has
+its own outage case, and `sessions.reauthenticateRace` races it against
+`revokeSession`.
+
 ### `TokenStore.countAttempt`
 
 Counts one attempt at a code against a token, and answers the token **as it
@@ -368,7 +402,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 49: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — thirteen of them | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 54: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — fourteen of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 16: the relation store, ids of edge characters, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty

package/docs/guide/errors.md

@@ -57,6 +57,7 @@ that wired the library, so no handler needs to tell it apart.
 | `CREDENTIALS_INVALID` | `CredentialError` | 401 | Unknown login, no password, or the wrong one — **one code for the three** | `reason`, for your logs only |
 | `HASH_UNSUPPORTED` | `CredentialError` | 400 | A stored hash no wired hasher reads | `hashPrefix` — never the hash |
 | `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, or the right code | `userId` |
+| `STEP_UP_REQUIRED` | `StepUpRequiredError` | 403 | `assertFresh`: the session proved who it is `maxAge` ago or more. Not a denial of the action — ask for a [step-up](step-up.md), then send the request again | `userId` |
 | `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means). For a second factor's challenge: sign in again; for a sign-in code's: request a new code — see [sign-in codes](sign-in-code.md#what-confirm-refuses) | `userId` on `TOKEN_STALE` |
 | `CODE_INVALID` | `TokenError` | 401 | A one-time code that does not match: a second factor's, or one already accepted — see [the second factor](second-factor.md#confirming-the-code-at-sign-in) — a recovery code not the user's, or already used — see [recovery codes](second-factor.md#signing-in-with-one) — or a sign-in code sent by e-mail — see [sign-in codes](sign-in-code.md#attempts) | `attemptsLeft` from either `confirm` and from `recover`: what the challenge has left, `0` once it is spent; from `regenerateRecoveryCodes`, what the user's 15-minute window has left, `0` past the fifth — see [regenerating them](second-factor.md#regenerating-them). None from `activate`. `userId` |
 | `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`; `regenerateRecoveryCodes` without an active factor; `confirm` or `recover` after the factor was disabled | `userId` |

package/docs/guide/events.md

@@ -48,7 +48,7 @@ The words — **user event**, **listener** — are defined in
 | `user.secondFactorEnabled` | `secondFactor.activate`, once the first code made the factor active | for `enroll`, which leaves the factor waiting and asked for nowhere; for a code refused |
 | `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
 | `user.recoveryCodesRegenerated` | `secondFactor.regenerateRecoveryCodes`: the codes the user held stopped working | for `activate`, whose first codes come with `user.secondFactorEnabled`; for a code refused |
-| `user.recoveryCodeUsed` | `secondFactor.recover`, once the recovery code is spent — even if opening the session then fails | for a recovery code refused. How many are left is not in the event: read the user |
+| `user.recoveryCodeUsed` | `secondFactor.recover`, once the recovery code is spent — even if opening the session then fails | for a recovery code refused. How many are left is not in the event: `secondFactor.recoveryCodesLeft(event.userId)` reads it |
 | `user.deleted` | `delete`, when it deleted the user | for a replay that finds nobody, or an id of another user type |
 
 A reset whose link verifies the e-mail sends both, `user.passwordReset`
@@ -81,26 +81,39 @@ function onUserEvent(event: UserEvent): void {
 ### Telling the user a recovery code was used
 
 A recovery code used by someone else is a sign-in without the user's phone,
-so tell the user each time. `@nxgt/janus-mail` has no template for it yet:
-send your own.
+so tell the user each time — and how many codes they have left, which the
+event does not carry: `secondFactor.recoveryCodesLeft` reads it, after the
+write, so the code just spent is already out of the count.
+[`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail)'s
+`recoveryCodeUsed` is the e-mail, in English and French:
 
 ```ts
-// `sendMail` is your mailer, and the user schema holds an e-mail.
+// `mail` is janusMail({ … }), and the user schema holds a name and a locale.
 const auth = janus({
 	...config,
 	async events(event) {
 		if (event.type === 'user.recoveryCodeUsed') {
 			const user = await auth.get(event.userId);
-			await sendMail(
-				user.email,
-				'A recovery code was used to sign in',
-				'Someone signed in to your account with one of your recovery codes. If it was not you, change your password and regenerate your codes.',
+			const recoveryCodesLeft = await auth.secondFactor.recoveryCodesLeft(user);
+			if (recoveryCodesLeft === null) return; // the factor was turned off since
+			const when = new Intl.DateTimeFormat(user.locale, {
+				dateStyle: 'long',
+				timeStyle: 'short',
+				timeZone: 'Europe/Paris', // the user's, when you keep it
+			}).format(event.occurredAt);
+			await mail.recoveryCodeUsed(
+				{ name: user.name, locale: user.locale, email: user.email },
+				{ when, recoveryCodesLeft }, // "You have 9 recovery codes left."
 			);
 		}
 	},
 });
 ```
 
+With several user types, the count is the type's:
+`auth.patient.secondFactor.recoveryCodesLeft(event.userId)`, on
+`event.userType`.
+
 ## What an event carries
 
 **The user named by id, and nothing else.** No login, no e-mail, no field of

package/docs/guide/second-factor.md

@@ -421,6 +421,28 @@ spent — even if opening the session then fails. It is the one to tell the
 user about: a recovery code used by someone else is a sign-in without their
 phone.
 
+### Counting what is left
+
+`recoveryCodesLeft(user)` reads the count `recover` answered, for whoever
+did not see that answer: a `user.recoveryCodeUsed` listener, which carries
+the user's id only, or a security settings page that says "3 recovery codes
+left".
+
+```ts
+await auth.secondFactor.recoveryCodesLeft(user); // 9 — or null, with no active factor
+```
+
+- **`null` without an active factor**: a user with none, or one still
+  waiting for its first code, holds no codes to count. `0` is an active
+  factor whose codes are all spent: send them to
+  [regenerate](#regenerating-them).
+- **An unknown id is `NOT_FOUND`**, as for `get`; a store that fails throws
+  `STORE_FAILED`. It writes nothing, and takes no key: it counts hashes.
+- **Read after the write**: in a `user.recoveryCodeUsed` listener it counts
+  the code just spent out.
+  [`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail)'s
+  `recoveryCodeUsed` says it in the e-mail — see [User events](events.md#telling-the-user-a-recovery-code-was-used).
+
 ### Regenerating them
 
 ```ts
@@ -466,21 +488,16 @@ its first ten.
 | `VERSION_CONFLICT` | `{ ifVersion }` no longer matches, or another call changed the user meanwhile — the same code tried twice at once regenerates once |
 
 Like `enroll` and `disable`, `regenerateRecoveryCodes` does not know who is
-calling: pass the user from `auth.authenticate(request)`, and apply your
-[recent sign-in rule](#asking-before-enroll-and-disable-is-your-policy)
-first. The app's code is the one check `janus` makes itself.
+calling: pass the user from `auth.authenticate(request)`, and ask for a
+[recent proof](#asking-before-enroll-and-disable-is-your-policy) first. The app's code is the one check `janus` makes itself.
 
 ```ts
-import { TokenError } from '@nxgt/janus';
-
-const RECENT = 5 * 60_000;
+import { TokenError, assertFresh } from '@nxgt/janus';
 
 export async function regenerateRecoveryCodes(request: Request): Promise<Response> {
 	const current = await auth.authenticate(request);
 	if (current === null) return new Response(null, { status: 401 });
-	if (Date.now() - current.session.authenticatedAt.getTime() > RECENT) {
-		return Response.json({ error: 'signInAgain' }, { status: 403 });
-	}
+	assertFresh(current.session, '5m'); // STEP_UP_REQUIRED: your error handler answers 403, and the client steps up
 	const { code } = (await request.json()) as { code: string };
 	try {
 		const { recoveryCodes } = await auth.secondFactor.regenerateRecoveryCodes(current.user, code);
@@ -548,25 +565,36 @@ again first is the application's decision** — a support tool may disable a
 factor for a user who lost their phone, while a user's own settings page
 should not let a stolen session switch it off.
 
-A common rule is a **recent sign-in**: the session was opened a few minutes
-ago, so its holder just gave the password — and the code, when the factor is
-active. `session.authenticatedAt` is when the session was opened, and renewal
-does not move it:
+A common rule is a **recent proof**: the session signed in, or was
+confirmed by a [step-up](step-up.md), a few minutes ago — so its holder just
+gave the password, the code, or both. `assertFresh` reads
+`session.authenticatedAt`, which renewal never moves, and throws
+`STEP_UP_REQUIRED` (403) for an older session:
 
 ```ts
-const RECENT = 5 * 60_000;
+import { JanusError, assertFresh, statusOf } from '@nxgt/janus';
 
 export async function disableSecondFactor(request: Request): Promise<Response> {
 	const current = await auth.authenticate(request);
 	if (current === null) return new Response(null, { status: 401 });
-	if (Date.now() - current.session.authenticatedAt.getTime() > RECENT) {
-		return Response.json({ error: 'signInAgain' }, { status: 403 });
+	try {
+		assertFresh(current.session, '5m');
+	} catch (error) {
+		// STEP_UP_REQUIRED: the client asks for auth.stepUp, then sends this again
+		if (error instanceof JanusError) {
+			return Response.json({ code: error.code }, { status: statusOf(error.code) });
+		}
+		throw error;
 	}
 	await auth.secondFactor.disable(current.user);
 	return new Response(null, { status: 204 });
 }
 ```
 
+For a user whose factor is active, `stepUp.request` asks for their app's
+code, never an e-mailed one: a stolen session and a read inbox together still
+cannot switch the factor off.
+
 Use the same check before `enroll`, before `regenerateRecoveryCodes` — which
 asks for the app's code besides — before `changePassword`, and before
 anything else a stolen session should not be able to do.
@@ -822,6 +850,7 @@ interface SecondFactorApi<U> {
 		disable(user: UserRef, options?: WriteOptions): Promise<U>;
 		confirm(challenge: string, code: string): Promise<SignedIn<U>>;
 		recover(challenge: string, code: string): Promise<RecoveredSignIn<U>>; // code: a recovery code
+		recoveryCodesLeft(user: UserRef): Promise<number | null>; // null: no active factor
 	};
 }
 

package/docs/guide/sessions.md

@@ -98,6 +98,12 @@ With several user types, each type has its own `session`.
 Expiry is decided by the core on every read, not by the store: a store may
 still hold a lapsed session, and `authenticate` answers it as anonymous.
 
+**Renewal is not freshness.** `session.authenticatedAt` is when the session
+last proved who it is — at the sign-in, or since by a
+[step-up](step-up.md) — and renewal never moves it. A sensitive route checks
+it with `assertFresh(session, '10m')`, which throws `STEP_UP_REQUIRED` for
+an older one.
+
 ## The cookie
 
 ```ts
@@ -227,5 +233,6 @@ cannot be replayed. `Session` is the stored record without that hash: `id`,
 
 - [Users](users.md) — `signUp`, `signIn`, the configuration
 - [The second factor](second-factor.md) — the challenge `signIn` answers instead of a session
+- [Step-up](step-up.md) — proving again who you are, and `assertFresh`
 - [E-mail flows](email-flows.md) — verification and password reset
 - [Errors](errors.md) — `STORE_FAILED`, `UNSUPPORTED` and the rest

package/docs/guide/step-up.md

@@ -0,0 +1,178 @@
+# Confirming a sensitive action — the step-up
+
+This page is for asking a signed-in user to prove again who they are before
+something a stolen session should not do alone: changing the e-mail,
+disabling the second factor, deleting the account. `janus` issues and checks
+a code, and **stamps the session as freshly confirmed**; sending the e-mail
+is yours, and so is deciding which routes ask.
+
+```ts
+import { assertFresh, createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+import { z } from 'zod';
+
+const auth = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+// The route that deletes the account asks for a recent proof:
+const current = await auth.authenticate(request);
+if (current === null) return new Response(null, { status: 401 });
+assertFresh(current.session, '10m'); // STEP_UP_REQUIRED (403) past ten minutes
+
+// The client, told STEP_UP_REQUIRED, asks for a step-up…
+const issued = await auth.stepUp.request(current.user);
+await sendMail(issued.email, 'Confirm it is you', `${issued.code} confirms the action. It expires in 10 minutes.`);
+// …keeps issued.challenge, and sends it back with the code the user typed:
+const session = await auth.stepUp.confirm(request, issued.challenge, code);
+session.authenticatedAt; // now: the action goes through for the next ten minutes
+```
+
+A step-up is two requests, as a sign-in by code is: one issues the code, the
+other takes it and stamps the session. It **opens no session** and hands out
+no new token: the session the request presents is the one confirmed, which
+is why `confirm` takes the request.
+
+## What "fresh" means
+
+`session.authenticatedAt` is when the session last proved who it is: at the
+sign-in, and since then at every `stepUp.confirm` on it. Renewing a sliding
+session does not move it. So a session signed in five minutes ago is fresh
+already — the user just gave their password — and one signed in days ago
+is fresh again once a step-up confirms it.
+
+`assertFresh(session, maxAge, clock?)` is that check, and reads nothing
+else: no store, no request. It throws `StepUpRequiredError`, code
+`STEP_UP_REQUIRED`, which `statusOf` answers 403, when the session proved
+who it is `maxAge` ago or more. Pass the `clock` you gave `janus()` when it
+is not the system's — `fixedClock` in a spec. A `maxAge` that is not a
+[duration](vocabulary.md) is a `TypeError`: it is written in the code.
+
+```ts
+import { StepUpRequiredError } from '@nxgt/janus';
+
+try {
+	assertFresh(current.session, '5m');
+} catch (error) {
+	if (error instanceof StepUpRequiredError) {
+		return Response.json({ code: error.code }, { status: 403 });
+	}
+	throw error;
+}
+```
+
+## Which types have it
+
+`stepUp` exists on every user type with an e-mail, as `signInCode` does. A
+type with no e-mail has no `stepUp`: it is absent from its type.
+
+```ts
+const clinic = janus({
+	users: {
+		patient: { schema: Patient, password: { login: 'email' } },   // has stepUp
+		staff: { schema: Staff, password: { login: 'username' } },    // no e-mail field
+	},
+	store,
+	hasher,
+});
+
+// @ts-expect-error — staff have no e-mail to send a code to
+clinic.staff.stepUp;
+```
+
+## Requesting a step-up
+
+```ts
+const issued = await auth.stepUp.request(user); // a user, or its id
+```
+
+What it answers depends on the user:
+
+| The user | `issued.via` | What to do |
+| --- | --- | --- |
+| no active second factor | `'email'` | send `issued.code` to `issued.email`, keep `issued.challenge` |
+| an active second factor | `'secondFactor'` | send nothing: ask for the code their app shows, keep `issued.challenge` |
+
+A user whose factor is active **confirms with their app, never by e-mail**:
+a step-up is never weaker than the sign-in their account asks for, so
+somebody who reads the user's inbox cannot disable the factor with a stolen
+session. Without `secondFactor` in `janus()`'s configuration, and on a type
+with no password, `via` is always `'email'`, and the type says so: `issued.code`
+is there without narrowing.
+
+```ts
+const issued = await auth.stepUp.request(current.user);
+if (issued.via === 'email') {
+	await sendMail(issued.email, 'Confirm it is you', issued.code);
+}
+return Response.json({ challenge: issued.challenge, via: issued.via });
+```
+
+**One step-up is live per user**: a request spends every step-up issued
+before it. The challenge lapses after ten minutes by default —
+`janus({ tokens: { stepUp: '5m' } })` changes it.
+
+`request` refuses a user of no such id, or one with no e-mail, with
+`NOT_FOUND`, and an inactive one with `USER_INACTIVE`. It is meant for the
+user of the session: call it with `current.user`, never with an id a client
+sent.
+
+## Confirming
+
+```ts
+const session = await auth.stepUp.confirm(request, challenge, code);
+```
+
+`confirm` checks the code, then moves `authenticatedAt` of **the session the
+request presents** to now — read from the request as `authenticate` reads
+it: `Authorization: Bearer`, `X-Session-Token`, then the cookie. It answers
+that session. The session must be a standing one of the user the challenge
+is for: a request with no session, a revoked or lapsed one, or another
+user's is refused as `TOKEN_UNKNOWN`, as a challenge nobody issued is.
+
+| Code | When |
+| --- | --- |
+| `CODE_INVALID`, with `attemptsLeft` | the code does not match; the fifth wrong one spends the challenge |
+| `TOKEN_UNKNOWN` | no such challenge, a sign-in code's challenge, or a request whose session is not a standing one of the challenge's user — or was revoked while the code was checked |
+| `TOKEN_SPENT`, `TOKEN_EXPIRED` | the challenge was used, replaced by a later request, or lapsed |
+| `TOKEN_STALE` | an e-mailed code, and the user changed their e-mail since |
+| `SECOND_FACTOR_ACTIVE` | an e-mailed code, and the user activated a second factor since: request again, the app confirms now |
+| `SECOND_FACTOR_NOT_ENROLLED` | an app's challenge, and the factor was disabled since |
+| `USER_INACTIVE` | the user was deactivated |
+| `VERSION_CONFLICT` | an app's code sent twice at once: the other confirmation stamped the session |
+
+Every attempt is counted before anything is compared — a guess that fails
+for any reason has cost one — as for a sign-in code. An app's codes are also
+counted **per user**, five per 15-minute window, in the same count as
+`regenerateRecoveryCodes`: a stolen session asking for challenge after
+challenge still gets five guesses per window, not five per challenge. The
+app's code accepted is spent, as at a sign-in: it confirms nothing else.
+
+**Rate-limit `request` per user.** An e-mailed code has no such window:
+five guesses per challenge, and a new challenge takes only a new `request`.
+A stolen session could ask again and again — each request also sends an
+e-mail and cancels the code before it. Limit `stepUp.request` per user —
+a few an hour is plenty for a person — as you limit `signInCode.request`
+per address; the `janus.stepUp.asked` event of `@nxgt/janus-telemetry` is
+the signal to alert on.
+
+A step-up and a sign-in code are **two kinds of token**: a sign-in code's
+challenge confirms no action, and a step-up's code signs nobody in.
+
+## Nothing else is written
+
+`stepUp.confirm` writes the session's `authenticatedAt` and, for an app's
+code, the step the factor accepted. It sends no user event — nothing about
+the user changed — and opens no session. With `@nxgt/janus-telemetry`, both
+calls are traced like every other flow.
+
+## See also
+
+- [Sessions](sessions.md) — `authenticate`, and what a session holds.
+- [The second factor](second-factor.md) — the app's codes, and asking
+  before `disable`.
+- [Signing in with an e-mailed code](sign-in-code.md) — the same six digits,
+  to sign in.
+- [Errors](errors.md) — every code and its status.

package/docs/guide/users.md

@@ -95,6 +95,7 @@ that cuts an emoji in half, say.
 | `tokens.verifyEmail` | `Duration` | `'24h'` | How long a verification token lives |
 | `tokens.resetPassword` | `Duration` | `'1h'` | How long a reset token lives |
 | `tokens.signInCode` | `Duration` | `'10m'` | How long an e-mailed sign-in code and its challenge live. See [sign-in codes](sign-in-code.md) |
+| `tokens.stepUp` | `Duration` | `'10m'` | How long a step-up's challenge — and its e-mailed code — lives. See [step-up](step-up.md) |
 | `secondFactor` | `{ issuer, keys, challenge? }` | none | A TOTP second factor for every type with a password. Changes what `signIn` answers — see [the second factor](second-factor.md#configuration) |
 | `events` | `UserEventListener` | none | Called with every user event — `user.created`, `user.deleted`, … — after the write, awaited. See [user events](events.md) |
 

package/docs/guide/vocabulary.md

@@ -51,8 +51,8 @@ either finds this row.
 | **second factor** | What a user proves at sign-in beyond their password: a TOTP secret their authenticator app holds, `UserRecord.secondFactor`. **Enrolled** once `enroll` stored it, waiting for a first code (`confirmedAt: null`); **active** once `activate` accepted one — `hasSecondFactor`, and only then does `signIn` ask for a code | "2FA", "MFA", "OTP device"; "confirmed" for the state — to *confirm* is to redeem a challenge |
 | **recovery code** | One of ten single-use codes `secondFactor.activate` and `secondFactor.regenerateRecoveryCodes` answer **once** — ten characters, shown `xxxxx-xxxxx` — that `secondFactor.recover` takes instead of a TOTP code, for a user whose authenticator app is gone. Stored only as keyed hashes. Always written in full: *code* alone is a one-time code, and a recovery code is never one | "backup code", "scratch code", "recovery key" |
 | **attempt** | One code tried against a challenge, counted by `countAttempt` in the token's `attempts` before the code is checked. A challenge takes five, a second factor's or a sign-in code's | "try"; "retry" is a repeated write, never a guess |
-| **challenge** | A secret the visitor keeps, redeemed once with a code — which is what *confirm* means for it. `signIn` answers one instead of a session when the user's second factor is active, for `secondFactor.confirm` — or `secondFactor.recover`, with a recovery code; `signInCode.request` answers one beside the sign-in code, for `signInCode.confirm`. Stored as its hash, as a one-time token of kind `secondFactor` or `signInCode`: five minutes or ten by default, and five attempts | "MFA token", "pending session", "ticket" |
-| **spent** | A one-time token or a challenge that can no longer be redeemed — `spentAt` set, `TOKEN_SPENT`, and never unset. Spent by its redemption, by its fifth attempt (a wrong code, or a call through another user type's API), by a redemption after it expired, by a refusal that ends it (`USER_INACTIVE`, `TOKEN_STALE`, `SECOND_FACTOR_NOT_ENROLLED`), or by what ends it early: the next `signInCode.request` for the same user (at most one sign-in code is live at a time), or a password written by `resetPassword.confirm`, `setPassword` or `changePassword` (every second-factor challenge left waiting) | "used up", "invalidated"; "consumed" only in `consumeToken`'s name; "revoked" is a session's |
+| **challenge** | A secret the visitor keeps, redeemed once with a code — which is what *confirm* means for it. `signIn` answers one instead of a session when the user's second factor is active, for `secondFactor.confirm` — or `secondFactor.recover`, with a recovery code; `signInCode.request` answers one beside the sign-in code, for `signInCode.confirm`; `stepUp.request` answers one for `stepUp.confirm`. Stored as its hash, as a one-time token of kind `secondFactor`, `signInCode` or `stepUp`: five minutes or ten by default, and five attempts | "MFA token", "pending session", "ticket" |
+| **spent** | A one-time token or a challenge that can no longer be redeemed — `spentAt` set, `TOKEN_SPENT`, and never unset. Spent by its redemption, by its fifth attempt (a wrong code, or a call through another user type's API), by a redemption after it expired, by a refusal that ends it (`USER_INACTIVE`, `TOKEN_STALE`, `SECOND_FACTOR_NOT_ENROLLED`), or by what ends it early: the next `signInCode.request` or `stepUp.request` for the same user (at most one of each is live at a time), or a password written by `resetPassword.confirm`, `setPassword` or `changePassword` (every second-factor challenge left waiting) | "used up", "invalidated"; "consumed" only in `consumeToken`'s name; "revoked" is a session's |
 | **step** | The thirty-second period a TOTP code belongs to. `lastStep` is the step of the last code accepted, and only a later step counts: that is why a code is accepted once | "window", "period", "counter", in prose |
 | **seal**, **sealing key** | To seal is to encrypt a TOTP secret — AES-256-GCM, bound to the user's id — before a store sees it. A sealing key is one `{ id, key }` of `secondFactor.keys`: the first seals, every one opens | "encrypt", "encryption key", "master key", "pepper" |
 | **token** | Never alone in prose: a *session token* or a *one-time token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |
@@ -60,6 +60,7 @@ either finds this row.
 | **issued** | What a flow answers for the application to send: an `IssuedToken` from `verifyEmail.send` or `resetPassword.request`, an `IssuedCode` from `signInCode.request` — the address with it. `@nxgt/janus-mail` takes it as it is | "result", "payload" |
 | **notice** | An e-mail that tells a user of a change and asks for nothing: *password changed*, *e-mail changed* — the latter sent to the former address — and *two-factor enabled*, *two-factor disabled*. `@nxgt/janus-mail` sends all four | "alert", "notification" |
 | **user event** | What happened to a user, once it is written: `user.created`, `user.emailVerified`, `user.passwordReset`, `user.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated`, `user.recoveryCodeUsed`, `user.deleted` — a `UserEvent`, naming the user by id alone, with an `id` of its own. See [user events](events.md) | "webhook" — a webhook is one way to deliver it; "event" alone where it could be read as `@nxgt/janus-telemetry`'s audit log record — on a page about user events, "the event" is fine |
+| **step-up**, **fresh** | A step-up is a signed-in user proving again who they are before a sensitive action — `stepUp.request`, then `stepUp.confirm`, with an e-mailed code or, when their second factor is active, their app's — which moves the session's `authenticatedAt` to now and opens no session. A session is **fresh** for `maxAge` after it proved who it is, at the sign-in or by a step-up; `assertFresh` refuses an older one with `STEP_UP_REQUIRED`. See [step-up](step-up.md) | "re-authentication", "sudo mode", "elevated session"; "recent sign-in" once a step-up counts too |
 | **listener** | The one function `janus({ events })` hands every user event to, after the write and awaited | "handler", "hook", "subscriber" |
 
 ### Permissions

package/docs/roadmap.md

@@ -5,17 +5,12 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-Nothing is in progress between releases; the next item is below.
+Nothing between releases.
 
 ## Next
 
-- **Confirm an action with an e-mailed code (step-up)** — a signed-in user
-  proves they still read their inbox before something a stolen session should
-  not do alone: changing the e-mail, disabling the second factor, deleting
-  the account. The same six digits, challenge and five attempts as a sign-in
-  code, bound to the session that asked rather than opening one — which
-  takes a token kind of its own, so a sign-in code can never confirm an
-  action nor an action's code sign anyone in.
+Nothing yet.
+
 ## Later
 
 - **More official adapters** — the ports are cut where atomicity is not
@@ -66,6 +61,21 @@ Nothing is in progress between releases; the next item is below.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Confirm an action with a code (step-up), v0.12.0** —
+  `auth.stepUp.request(user)` and `stepUp.confirm(request, challenge, code)`:
+  a signed-in user proves again who they are before a sensitive action, with
+  a six-digit code sent by e-mail — or, when their second factor is active,
+  the code from their app. The confirmation moves the session's
+  `authenticatedAt` and opens no session, and `assertFresh(session, maxAge)`
+  refuses an older one with `STEP_UP_REQUIRED` (403). A token kind of its
+  own, `stepUp`, and `SessionStore.reauthenticateSession`, in the three
+  adapters and the conformance suite.
+- **The recovery codes left, read again, v0.11.0** —
+  `secondFactor.recoveryCodesLeft(user)` answers the count `recover`
+  answered, for a `user.recoveryCodeUsed` listener — the event names the
+  user only — or a security settings page; `null` for a user with no active
+  factor. The listener can now tell the user how many codes remain, as
+  `@nxgt/janus-mail`'s `recoveryCodeUsed` e-mail does.
 - **Recovery codes, v0.10.0** — a user who loses their authenticator app
   still signs in, with no operator resetting the account.
   `secondFactor.activate` answers `{ user, recoveryCodes }`: ten single-use
@@ -136,18 +146,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   without a password included; an active second factor is still asked for.
   A challenge lives ten minutes (`tokens.signInCode`) and takes five
   attempts, and only the code's hash is stored, keyed by the challenge.
-- **A TOTP second factor, v0.5.0** — `janus({ secondFactor: { issuer, keys } })`
-  and `auth.<type>.secondFactor`'s `enroll`, `activate`, `disable` and
-  `confirm`, for every user type with a password; each secret sealed with
-  AES-256-GCM under keys your application holds, and rotated by adding a key.
-  Breaking once configured: `signIn` answers `{ status: 'signedIn', … }` or
-  `{ status: 'secondFactor', challenge, expiresAt }`. A challenge lives five
-  minutes and takes five attempts, a code is accepted once, and a refused one
-  throws `CODE_INVALID` with `attemptsLeft`.
-- **The store port holds a second factor and counts attempts on a token,
-  v0.4.0** — `UserRecord.secondFactor`, a token's `codeHash` and `attempts`,
-  the token kinds `'secondFactor'` and `'signInCode'`, and
-  `TokenStore.countAttempt`, one conditional write per attempt, with six new
-  conformance cases. The published adapters implement them in
-  `@nxgt/janus-drizzle` 0.2, `@nxgt/janus-mongo` 0.3 and
-  `@nxgt/janus-redis` 0.2.