@nxgt/janus 0.4.0 → 0.6.0

package/docs/roadmap.md

@@ -5,16 +5,20 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-- **One-time codes** — a one-time token short enough to type, sent by e-mail
-  to sign in without a password, or to confirm a sensitive action, issued
-  and redeemed by `janus` like the verification and reset tokens today; and
-  TOTP, the one-time codes of an authenticator app, as a second factor, its
-  secret sealed with a key your application holds. `signIn` will answer
-  `{ status: 'signedIn' }` or `{ status: 'secondFactor', challenge }`. The
-  store port that holds them shipped in v0.4.0, 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.
+- **Recovery codes** — single-use codes for the TOTP second factor, so a
+  user who loses their authenticator app can still sign in, without an
+  operator resetting the account.
 - **Sending the e-mails** — in a package of its own, `@nxgt/janus-mail`, built
   on a general mail toolkit shared with applications that are not about
   sign-in: a `Mailer` port you plug your transport into (SMTP, Resend, SES…) —
@@ -44,8 +48,10 @@ dates here, and the version something shipped in is the only number.
 - **More official adapters** — the ports are cut where atomicity is not
   required, so users, sessions and permission tuples can each live in the
   database that suits them. MongoDB is the first adapter
-  ([`@nxgt/janus-mongo`](https://www.npmjs.com/package/@nxgt/janus-mongo));
-  PostgreSQL is under Now.
+  ([`@nxgt/janus-mongo`](https://www.npmjs.com/package/@nxgt/janus-mongo)),
+  PostgreSQL and Redis followed
+  ([`@nxgt/janus-drizzle`](https://www.npmjs.com/package/@nxgt/janus-drizzle),
+  [`@nxgt/janus-redis`](https://www.npmjs.com/package/@nxgt/janus-redis)).
 
 ## Not planned
 
@@ -84,14 +90,31 @@ dates here, and the version something shipped in is the only number.
 
 ## Shipped
 
-Each entry names the version it came in.
+The last ten, newest first, each with the version it came in. Everything
+before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Sign in with a code sent by e-mail, v0.6.0** —
+  `auth.<type>.signInCode.request(email)` answers a six-digit code to send
+  and a challenge to keep with the visitor, or `null` for nobody — never
+  saying which; `signInCode.confirm(challenge, code)` marks the e-mail
+  verified and opens the session. On every user type with an e-mail, one
+  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. No flow uses them yet; the published adapters implement
-  them in `@nxgt/janus-drizzle` 0.2, `@nxgt/janus-mongo` 0.3 and
+  conformance cases. The published adapters implement them in
+  `@nxgt/janus-drizzle` 0.2, `@nxgt/janus-mongo` 0.3 and
   `@nxgt/janus-redis` 0.2.
 - **Permissions on a user, v0.3.0** — a user type may also be an object type:
   a staff member is the object `can()` asks about and is granted relations
@@ -109,7 +132,10 @@ Each entry names the version it came in.
   audit trail, never a login, a password, a session token or a one-time token;
   and [`@nxgt/janus-kit`](https://www.npmjs.com/package/@nxgt/janus-kit), all
   of it wired in one call.
-
+- **A NUL character or a lone surrogate never reaches a store** — refused in
+  fields with `USER_INVALID` on every adapter, rather than `STORE_FAILED` on
+  PostgreSQL alone; a login holding one is nobody's. The conformance suite
+  holds every adapter to round-tripping every other character. — v0.2.1
 - **The model's keys read `related` and `permits`** — Keto's OPL words: an
   object type declares `related: { members: ['staff', 'team#members'] }` and
   `permits: { view: ['members'] }`, and relation names are plural by convention. Breaking:
@@ -123,48 +149,7 @@ Each entry names the version it came in.
 - **The conformance suite accepts a store with its own expiry** — a store
   that drops a lapsed session at once, as a Redis TTL does, passes
   `sessions.deleteUser`; one that still holds it must count it. — v0.2.0
-- **A NUL character or a lone surrogate never reaches a store** — refused in
-  fields with `USER_INVALID` on every adapter, rather than `STORE_FAILED` on
-  PostgreSQL alone; a login holding one is nobody's. The conformance suite
-  holds every adapter to round-tripping every other character. — v0.2.1
-
 - **A Hono integration** — [`@nxgt/janus-hono`](https://www.npmjs.com/package/@nxgt/janus-hono):
   the session middleware, the cookie, a route guarded by a permission,
   `bindJanus()` to bind the instances once, and every error as its status.
   Its own 0.1.0, beside `@nxgt/janus` 0.1.3.
-- **`defineModel` completed by your editor** — subject types and subject sets
-  in a relation, subject types in `fromField`, relations, permissions and
-  arrows in a rule and in `when`; a wrong name's error lists the names it
-  could have been. — v0.1.2
-
-- **The model decides what a stored tuple grants** — `can()` and `list()` follow
-  only the holders a relation admits, as `grant()` writes only those: a tuple
-  stored past `grant()`, by an older model or by hand, grants nothing. — v0.1
-- **Guides and troubleshooting pages** — a `docs/` folder shipped in the
-  package: detailed guides with examples, and the errors you can meet, each
-  with its cause and fix. — v0.1
-- **Permissions at `@nxgt/janus/permissions`** — and `janus({ relations })`,
-  so deleting a user also deletes every tuple naming them. — v0.1
-- **`list()`** — the ids of every object a subject holds a permission on, as a
-  cursor page, `fromField` relations included through their `lookup`. — v0.1
-- **`can()`, `grant()` and `revoke()`** — a permission check that answers
-  `true` or `false` and throws on an outage, and tuple writes refused at
-  compile time when the model does not admit them. — v0.1
-- **Typed subjects and the `RelationStore` port** — `{ type, id }` subjects,
-  the tuple notation, `createMemoryRelations()`, and
-  `describeRelationStores` for adapter authors. — v0.1
-- **A permission model typed from itself** — `defineModel` with subject sets,
-  arrows, `fromField` relations read from your data, and `when` conditions
-  written in TypeScript. — v0.1
-- **Delete a user, and everything of theirs** — `delete(user)` removes the
-  user with every session and one-time token they had, idempotently. — v0.1
-- **Rehash a stale password on sign-in** — moving hashers, or raising a cost,
-  reaches every active user with no migration to run. — v0.1
-- **`janus()`** — sign-up, sign-in, sessions, e-mail verification and password
-  reset, with several user types in one instance, typed from your schemas.
-  — v0.1
-- **The conformance suite** — `@nxgt/janus/conformance`, the suite an adapter
-  runs, outages included. — v0.1
-- **The identity stores' port and its in-memory reference** — `JanusStores` and
-  `createMemoryStores()`, for your tests and as the model for an adapter.
-  — v0.1

package/docs/troubleshooting.md

@@ -23,7 +23,7 @@ How the messages are shaped:
 - [`error instanceof StoreFailure` is `false` for an outage](#error-instanceof-storefailure-is-false-for-an-outage)
 
 **Configuring `janus()`**
-- [`janus: pass either user … or users …, and exactly one of them`](#janus-pass-either-user-one-kind-of-user-or-users-several-kinds-and-exactly-one-of-them)
+- [`janus: pass either user … or users …, and exactly one of them`](#janus-pass-either-user-one-user-type-or-users-several-user-types-and-exactly-one-of-them)
 - [`janus: user must be a Standard Schema …`](#janus-user-must-be-a-standard-schema--a-zod-4-valibot-or-arktype-schema)
 - [`janus: a user type signs in with a password and no hasher is wired …`](#janus-a-user-type-signs-in-with-a-password-and-no-hasher-is-wired--pass-hasher-scrypthasher-or-bunhasher-on-bun-there-is-no-silent-fallback)
 - [`bunHasher: Bun.password is not available …`](#bunhasher-bunpassword-is-not-available--this-runtime-is-not-bun-wire-scrypthasher-instead)
@@ -36,6 +36,9 @@ How the messages are shaped:
 - [`janus: the user type "<name>" must be a camelCase name …`](#janus-the-user-type-name-must-be-a-camelcase-name--letters-and-digits-starting-with-a-letter)
 - [`janus: session.lifespan: "<value>" is not a duration …`](#janus-sessionlifespan-value-is-not-a-duration-write-a-number-followed-by-ms-s-m-h-or-d--for-example-15m-or-720h)
 - [`janus: cookie.sameSite "none" requires cookie.secure …`](#janus-cookiesamesite-none-requires-cookiesecure--browsers-refuse-the-cookie-otherwise)
+- [`janus: secondFactor.issuer must name your application …`](#janus-secondfactorissuer-must-name-your-application--the-authenticator-app-shows-it-beside-the-account)
+- [`janus: secondFactor.keys: the key "<id>" is not 32 bytes in base64 …`](#janus-secondfactorkeys-the-key-id-is-not-32-bytes-in-base64--make-one-with-openssl-rand--base64-32)
+- [`"hasSecondFactor" is a field janus sets itself; rename it`](#hassecondfactor-is-a-field-janus-sets-itself-rename-it)
 - [Other `janus:` wiring messages](#other-janus-wiring-messages)
 
 **Users, sessions and tokens**
@@ -58,6 +61,26 @@ How the messages are shaped:
 - [`<call>: the <type> type does not sign in with a password …`](#call-the-type-type-does-not-sign-in-with-a-password--add-password--login--to-it)
 - [`authenticate()` answers `null` although a valid cookie was sent](#authenticate-answers-null-although-a-valid-cookie-was-sent)
 
+**Second factor**
+- [`TS2339: Property 'token' does not exist on type 'SignInResult<…>'.`](#ts2339-property-token-does-not-exist-on-type-signinresult)
+- [`CODE_INVALID` — `<call>: the code does not match, or was already used`](#code_invalid--call-the-code-does-not-match-or-was-already-used)
+- [The code the authenticator app shows is refused with `CODE_INVALID`](#the-code-the-authenticator-app-shows-is-refused-with-code_invalid)
+- [`SECOND_FACTOR_NOT_ENROLLED` — `secondFactor.activate: the user has no second factor waiting …`](#second_factor_not_enrolled--secondfactoractivate-the-user-has-no-second-factor-waiting--call-enroll-first)
+- [`SECOND_FACTOR_ACTIVE` — `secondFactor.enroll: the user's second factor is active …`](#second_factor_active--secondfactorenroll-the-users-second-factor-is-active--disable-it-first)
+- [`<call>: …, and janus() was given no secondFactor …`](#call--and-janus-was-given-no-secondfactor--pass-secondfactor--issuer-keys-)
+- [`<call>: the secret is sealed with the key "<id>", which secondFactor.keys no longer holds …`](#call-the-secret-is-sealed-with-the-key-id-which-secondfactorkeys-no-longer-holds--keep-a-key-until-no-secret-is-sealed-with-it)
+- [`<call>: the secret does not open with the key "<id>" — was that key changed under the same id, or the secret copied from another user?`](#call-the-secret-does-not-open-with-the-key-id--was-that-key-changed-under-the-same-id-or-the-secret-copied-from-another-user)
+- [`<call>: the stored secret is not a sealed one`](#call-the-stored-secret-is-not-a-sealed-one)
+- [`<call>: the <type> type does not sign in with a password, so it has no second factor`](#call-the-type-type-does-not-sign-in-with-a-password-so-it-has-no-second-factor)
+- `TOKEN_*`, `USER_INACTIVE` and `VERSION_CONFLICT` from `secondFactor.confirm`: in their entries above.
+
+**Sign-in codes**
+- [`TOKEN_STALE` — `<call>: the code was sent to an e-mail the user no longer has`](#token_stale--call-the-code-was-sent-to-an-e-mail-the-user-no-longer-has)
+- [The code from an earlier e-mail is refused with `CODE_INVALID`](#the-code-from-an-earlier-e-mail-is-refused-with-code_invalid)
+- [`signInCode.request` answers `null` for a user who exists](#signincoderequest-answers-null-for-a-user-who-exists)
+- [`TS2339: Property 'signInCode' does not exist on type 'TypeApi<…>'.`](#ts2339-property-signincode-does-not-exist-on-type-typeapi)
+- `CODE_INVALID`, `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `USER_INACTIVE` and `VERSION_CONFLICT` from `signInCode.confirm`, and `TS2339` on its `token`: in their entries above.
+
 **Permissions**
 - [`PERMISSION_DEPTH` — `can: checking <type>#<permission> crossed more than <n> relations without an answer`](#permission_depth--can-checking-typepermission-crossed-more-than-n-relations-without-an-answer)
 - [`permissions: this model was not made by defineModel() …`](#permissions-this-model-was-not-made-by-definemodel--pass-what-definemodel-answered)
@@ -73,6 +96,7 @@ How the messages are shaped:
 
 **Subjects**
 - [`parseTuple: "<text>" is not a relation tuple; expected type:id#relation@subject`](#parsetuple-text-is-not-a-relation-tuple-expected-typeidrelationsubject)
+- [`setOf: pass a user or { type, id }, then a relation`](#setof-pass-a-user-or--type-id--then-a-relation)
 
 **Conformance (adapter authors)**
 - [`describeJanusStores: no test runner on globalThis …`](#describejanusstores-no-test-runner-on-globalthis--pass-runner--describe-it--under-bun-test-import-them-from-buntest)
@@ -274,7 +298,7 @@ Also `janus: "<name>" cannot name a user type — janus() answers a method of th
 
 ### `janus: session.lifespan: "<value>" is not a duration; write a number followed by ms, s, m, h or d — for example "15m" or "720h"`
 
-The same for `session.renewAfter`, `tokens.verifyEmail` and `tokens.resetPassword`. Also `<option>: a duration must be above zero` and `<option>: a duration in milliseconds must be a finite number above zero`.
+The same for `session.renewAfter`, `tokens.verifyEmail`, `tokens.resetPassword`, `tokens.signInCode` and `secondFactor.challenge`. Also `<option>: a duration must be above zero` and `<option>: a duration in milliseconds must be a finite number above zero`.
 
 **When:** `janus({...})`.
 **Why:** a duration is a number of milliseconds, or a number followed by one unit. `'30 m'` compiles — TypeScript's `${number}` accepts the space — and is refused here.
@@ -292,6 +316,48 @@ Also `janus: cookie.name must be a cookie-name token — letters, digits and !#$
 **Why:** browsers drop a `SameSite=None` cookie that is not `Secure`, so every sign-in would silently fail to stick.
 **Fix:** keep `secure: true` with `sameSite: 'none'`, or use the default `sameSite: 'lax'` when the site and the API share a site.
 
+### `janus: secondFactor.issuer must name your application — the authenticator app shows it beside the account`
+
+**When:** `janus({ ..., secondFactor })`, when `issuer` is missing, is not a string, or is blank.
+**Why:** the issuer is the label the authenticator app shows beside the account. Without it, a user with several accounts in the app cannot tell which code is yours.
+**Fix:**
+
+```ts
+janus({ ..., secondFactor: { issuer: 'Acme', keys } });
+```
+
+### `janus: secondFactor.keys: the key "<id>" is not 32 bytes in base64 — make one with openssl rand -base64 32`
+
+Also:
+
+- `janus: secondFactor.keys: expected at least one key — [{ id, key }], the first seals`
+- `janus: secondFactor.keys: every key needs an id of letters, digits, _ and -, at most 64 of them`
+- `janus: secondFactor.keys: two keys have the id "<id>"`
+
+**When:** `janus({ ..., secondFactor })`.
+**Why:** every TOTP secret is sealed with AES-256-GCM before a store sees it, and that takes a 32-byte key: 43 characters of base64 or base64url, with or without the trailing `=`. A hex key (64 characters), a passphrase, or an environment variable that is not set is refused. The id is written into every secret the key seals, so it is short, plain, and names one key only.
+**Fix:** make each key once and keep it with your other secrets:
+
+```sh
+openssl rand -base64 32
+```
+
+```ts
+janus({
+  ...,
+  secondFactor: {
+    issuer: 'Acme',
+    keys: [{ id: 'k2026a', key: process.env.TOTP_KEY_K2026A ?? '' }], // the first key seals
+  },
+});
+```
+
+### `"hasSecondFactor" is a field janus sets itself; rename it`
+
+**When:** `tsc`, on the `janus({...})` call, when your schema declares a `hasSecondFactor` field. This version added it to the fields janus sets on every user.
+**Why:** `user.hasSecondFactor` is janus's own answer: whether the user's second factor is active. A field of yours with that name would be shadowed. From JavaScript, a validated input holding it is refused with `USER_INVALID` and the issue `set by janus, not by a request`.
+**Fix:** rename the field in your schema, and read `user.hasSecondFactor` for janus's answer.
+
 ### Other `janus:` wiring messages
 
 | Message | Fix |
@@ -365,6 +431,23 @@ const user = await auth.get(id);
 await auth.update(user, { name }, { ifVersion: user.version });
 ```
 
+**From `secondFactor.confirm`**, the message is the store's:
+`updateUser: expected version <n>, found <m>`.
+
+**When:** two `confirm` calls for one user run at once with the same code — a
+double-submitted form, two tabs, a client that retries before the first answer.
+**Why:** of two codes accepted at once, the first write wins and opens a
+session. The second finds the user's version moved and writes nothing: no
+session. Its challenge is not spent, and has lost one attempt.
+**Fix:** submit the code form once. The session already exists, from the call
+that won; if the visitor still needs one, the next code works on the same
+challenge — the same code will not, it was used.
+
+```ts
+// in the browser: one submit per code
+form.addEventListener('submit', () => form.querySelector('button')?.setAttribute('disabled', ''));
+```
+
 ### `USER_INVALID` — `<call>: the fields do not match the <type> schema (<n> issues, at <paths>)`
 
 `UserInvalidError`, carrying `issues` — each a `path` and a `message`.
@@ -416,9 +499,9 @@ janus({ ..., hasher: scryptHasher(), verifiers: [bcryptVerifier] }); // a Passwo
 
 ### `USER_INACTIVE` — `<call>: the user is inactive`
 
-**When:** `signIn`, with the **right** password, for a user set inactive.
-**Why:** an inactive user keeps their record and password, and every sign-in is refused. It is checked after the password, so only somebody who knows the password learns the user is inactive.
-**Fix:** answer 403, or reactivate: `await auth.setActive(user, true)`.
+**When:** `signIn`, with the **right** password, for a user set inactive. Also `secondFactor.confirm`, for a user set inactive after `signIn` asked for a code, and `signInCode.confirm`, for a user set inactive after the code was sent.
+**Why:** an inactive user keeps their record and password, and every sign-in is refused. It is checked after the password, so only somebody who knows the password learns the user is inactive — and after the code, so only somebody who read the e-mail does: `signInCode.request` answers `null` for an inactive user, as for nobody. On either `confirm`, the challenge is spent: reactivating the user does not revive it.
+**Fix:** answer 403, or reactivate, then sign in again: `await auth.setActive(user, true)`.
 
 ### `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`
 
@@ -432,6 +515,46 @@ janus({ ..., hasher: scryptHasher(), verifiers: [bcryptVerifier] }); // a Passwo
 janus({ ..., tokens: { verifyEmail: '72h', resetPassword: '2h' } });
 ```
 
+**On `secondFactor.confirm`**, the messages name the challenge `signIn`
+answered: `secondFactor.confirm: no such challenge`,
+`secondFactor.confirm: the challenge was already used`,
+`secondFactor.confirm: the challenge has expired`.
+
+**When:** `secondFactor.confirm(challenge, code)`.
+**Why:** a challenge lives five minutes and takes five codes. It is spent by
+the code that opens the session, by the fifth wrong code, and by a refusal
+that ends it (`USER_INACTIVE`, `SECOND_FACTOR_NOT_ENROLLED`). `TOKEN_UNKNOWN`
+also covers a challenge whose user was deleted, and a challenge passed where a
+code was expected — the two arguments swapped.
+**Fix:** answer 400 and send the visitor back to sign in, which asks for a new
+code. To give slower visitors more time:
+
+```ts
+janus({ ..., secondFactor: { issuer: 'Acme', keys, challenge: '10m' } });
+```
+
+**On `signInCode.confirm`**, the messages name the challenge
+`signInCode.request` answered: `signInCode.confirm: no such challenge`,
+`signInCode.confirm: the challenge was already used`,
+`signInCode.confirm: the challenge has expired`.
+
+**When:** `signInCode.confirm(challenge, code)`.
+**Why:** a challenge lives ten minutes and takes five codes. It is spent by
+the code that signs the user in, by the fifth wrong code, and by a refusal
+that ends it (`TOKEN_STALE`, `USER_INACTIVE`). `TOKEN_UNKNOWN` also covers a
+challenge whose user was deleted, one confirmed through another user type's
+`signInCode`, the decoy challenge of a `request` that answered `null`, and
+the two arguments swapped. Another type's `confirm` compares no code and
+spends nothing, but it has already cost one of the challenge's five
+attempts: the attempt is counted before the type is known. The challenge is
+left for its own type, with one attempt fewer.
+**Fix:** answer 400 and offer to send a new code. To give slower inboxes
+more time:
+
+```ts
+janus({ ..., tokens: { signInCode: '15m' } });
+```
+
 ### `TOKEN_STALE` — `<call>: the token was sent to an e-mail the user no longer has`
 
 **When:** `verifyEmail.confirm` or `resetPassword.confirm`, after the user changed their e-mail.
@@ -486,6 +609,292 @@ const page = await access.list(user, 'view', 'record', {
 
 ---
 
+## Second factor
+
+Every entry here needs `janus({ ..., secondFactor })`, but for the
+`signInCode.confirm` paragraph of `CODE_INVALID`. The messages start with
+`secondFactor.enroll`, `secondFactor.activate`, `secondFactor.confirm` or
+`signIn` — prefixed by the type with several user types:
+`staff.secondFactor.confirm: …`. `secondFactor.confirm` also rejects with
+[`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
+[`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and
+[`VERSION_CONFLICT`](#version_conflict--call-expected-version-n-found-m);
+each of those entries has a paragraph for it.
+
+### `TS2339: Property 'token' does not exist on type 'SignInResult<…>'.`
+
+The same for `session` and `user`.
+
+**When:** `tsc`, wherever `signIn`'s answer is read, once `janus()` is given a `secondFactor` — and `signInCode.confirm`'s, on a user type with a password.
+**Why:** `signIn` then answers one of two shapes: `{ status: 'signedIn', user, session, token }`, or `{ status: 'secondFactor', challenge, expiresAt }` for a user whose second factor is active — the password alone opens no session for them. Without `secondFactor`, `signIn` still answers a session.
+**Fix:** switch on `status`:
+
+```ts
+const result = await auth.signIn({ email, password });
+if (result.status === 'secondFactor') {
+  // Keep the challenge for the next request — never in a URL — and ask for a code.
+  return Response.json({ challenge: result.challenge, expiresAt: result.expiresAt });
+}
+return Response.json({ token: result.token });
+
+// the next request, with the code the app shows
+const signedIn = await auth.secondFactor.confirm(challenge, code); // { status: 'signedIn', token, … }
+```
+
+### `CODE_INVALID` — `<call>: the code does not match, or was already used`
+
+`TokenError`. The same message answers three calls; there is a paragraph
+for each below.
+
+**When:** `secondFactor.activate`, `secondFactor.confirm` or
+`signInCode.confirm`, with a code that does not match.
+
+**`secondFactor.activate(user, code)`**
+**Why:** the code is wrong, or it was accepted before: a code is accepted
+once. There is no challenge here: no `attemptsLeft`, and nothing is spent.
+**Fix:** let the user try the next code the app shows. If it is the one on
+screen, see [the next entry](#the-code-the-authenticator-app-shows-is-refused-with-code_invalid).
+
+**`secondFactor.confirm(challenge, code)`**
+**Why:** the code is wrong, or it was accepted before. Every call costs one of
+the challenge's five attempts, counted before anything is checked. The error
+carries `attemptsLeft`, what remains; at `0`, the challenge is spent and the
+next `confirm` is `TOKEN_SPENT`.
+**Fix:** answer 401 with `attemptsLeft`, and send the visitor back to sign in
+once it is `0`:
+
+```ts
+import { TokenError } from '@nxgt/janus';
+
+try {
+  return await auth.secondFactor.confirm(challenge, code);
+} catch (error) {
+  if (error instanceof TokenError && error.code === 'CODE_INVALID') {
+    return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
+  }
+  throw error;
+}
+```
+
+**`signInCode.confirm(challenge, code)`** — the e-mailed code.
+**Why:** the code is not the one sent with this challenge, or is not six
+digits — a space, a dash, a code pasted with its label. The error carries
+`attemptsLeft` and the `userId` of the user the code was sent to. Every call
+costs one of the challenge's five attempts, counted before the code is
+compared — a call through another user type's `signInCode` too, although it
+answers `TOKEN_UNKNOWN`. At `0` the challenge is spent, and the next
+`confirm` is `TOKEN_SPENT`, even with the right code. Codes sent at once past
+the fifth attempt are all refused, the right one included.
+**Fix:** answer 401 with `attemptsLeft`, and request a new code once it is
+`0`. Strip what the visitor may have typed around the digits before calling
+`confirm`:
+
+```ts
+import { TokenError } from '@nxgt/janus';
+
+try {
+  return await auth.signInCode.confirm(challenge, code.replace(/\D/g, ''));
+} catch (error) {
+  if (error instanceof TokenError && error.code === 'CODE_INVALID') {
+    return Response.json({ code: error.code, attemptsLeft: error.attemptsLeft }, { status: 401 });
+  }
+  throw error;
+}
+```
+
+If the visitor typed the code from the e-mail correctly, see
+[the code from an earlier e-mail](#the-code-from-an-earlier-e-mail-is-refused-with-code_invalid).
+
+### The code the authenticator app shows is refused with `CODE_INVALID`
+
+**When:** `activate` or `confirm`, with the code on screen, typed correctly.
+**Why**, in the order to check:
+
+1. **A clock is off.** A code is accepted in its own 30-second step and one step either side. A phone or a server whose clock is more than about 30 seconds away from the real time produces codes outside those three steps. How many steps are accepted is not configurable.
+2. **The code was already used** — and so were the codes before it. Once a code is accepted, that code and every earlier one are refused: the user who activates and then signs in within the same 30 seconds, or who signs in twice in a row, must wait for the next code.
+3. **The app holds an older secret.** `enroll` called again before `activate` replaces the secret: an entry scanned from the first `enroll` shows codes for a secret nobody holds any more.
+
+**Fix:** for 1, keep the server's clock synchronised and ask the user to set their phone's time automatically. For 2, wait for the next code. For 3, delete the entry from the app and scan the `uri` of the last `enroll`.
+
+```sh
+timedatectl show -p NTPSynchronized   # NTPSynchronized=yes on the server
+```
+
+### `SECOND_FACTOR_NOT_ENROLLED` — `secondFactor.activate: the user has no second factor waiting — call enroll first`
+
+`SecondFactorError`. Also `secondFactor.confirm: the user no longer has a second factor — sign in again`.
+
+**When:** `activate` before `enroll`, or after `disable`. On `confirm`: the factor was disabled after `signIn` asked for a code.
+**Why:** `activate` checks a code against the secret `enroll` wrote, and there is none. On `confirm`, the factor the challenge asked for is gone, so the challenge is spent.
+**Fix:** `enroll`, show the `uri` as a QR code, then `activate` with a code from the app. After `confirm`'s refusal, sign in again: `signIn` answers a session directly for a user without a factor.
+
+```ts
+const { secret, uri } = await auth.secondFactor.enroll(user);
+// …the user scans uri, or types secret…
+await auth.secondFactor.activate(user, code);
+```
+
+### `SECOND_FACTOR_ACTIVE` — `secondFactor.enroll: the user's second factor is active — disable it first`
+
+`SecondFactorError`. Also `secondFactor.activate: the user's second factor is already active`.
+
+**When:** `enroll` or `activate` for a user whose factor is already active — often a form submitted twice, or a "set up again" button.
+**Why:** enrolling again would replace the secret and quietly switch the factor off until the new one is activated. It is refused so that only `disable` switches it off.
+**Fix:** check `user.hasSecondFactor` first. To move to a new phone, disable, then enroll:
+
+```ts
+const cleared = await auth.secondFactor.disable(user);
+const { uri } = await auth.secondFactor.enroll(cleared);
+```
+
+### `<call>: …, and janus() was given no secondFactor — pass secondFactor: { issuer, keys }`
+
+Most often: `signIn: the user's second factor is active, and janus() was given no secondFactor — pass secondFactor: { issuer, keys }`. A `TypeError`.
+
+**When:** `signIn` for a user whose factor is active, on a `janus()` built without `secondFactor` — a second process over the same users: a worker, a script, an admin service, an older deployment. From JavaScript, `enroll`, `activate` and `confirm` on such an instance too.
+**Why:** the password alone never opens a session for a user with an active factor, and an instance without keys cannot check a code. It refuses rather than sign the user in on the password alone.
+**Fix:** give every `janus()` over the same users the same `secondFactor`, from one module:
+
+```ts
+// auth-config.ts, imported by every process
+export const secondFactor = { issuer: 'Acme', keys } as const;
+
+janus({ ..., secondFactor });
+```
+
+### `<call>: the secret is sealed with the key "<id>", which secondFactor.keys no longer holds — keep a key until no secret is sealed with it`
+
+A `TypeError`.
+
+**When:** `activate` or `confirm`, for a user whose secret was sealed with a key since removed from `keys` — or with a key another deployment has and this one does not.
+**Why:** each sealed secret names its key. The first key seals, every key opens, and a secret is sealed again under the first key only the next time a code of that user is accepted. A user who has not signed in since the rotation still holds the old seal.
+**Fix:** put the old key back, after the new one:
+
+```ts
+secondFactor: {
+  issuer: 'Acme',
+  keys: [
+    { id: 'k2026b', key: process.env.TOTP_KEY_K2026B ?? '' }, // seals
+    { id: 'k2026a', key: process.env.TOTP_KEY_K2026A ?? '' }, // still opens
+  ],
+},
+```
+
+A key can go once no stored second-factor secret starts with `v1.<its id>.`.
+
+### `<call>: the secret does not open with the key "<id>" — was that key changed under the same id, or the secret copied from another user?`
+
+A `TypeError`.
+
+**When:** `activate` or `confirm`.
+**Why:** the key held under that id is not the one that sealed the secret: its value was changed and its id kept, or two environments sharing one database hold different keys under one id. It is also the message for a sealed secret copied onto another user — a seal is bound to the user's id — for example a user record duplicated by hand.
+**Fix:** restore the original key under that id. A new key always takes a new id. For a copied record, disable the factor and have the user enroll again: `await auth.secondFactor.disable(user)`.
+
+### `<call>: the stored secret is not a sealed one`
+
+A `TypeError`.
+
+**When:** `activate` or `confirm`.
+**Why:** the stored secret is not `v1.<key id>.<iv>.<sealed>`: it was written into the store directly — a plain base32 secret imported from another system — or cut short.
+**Fix:** never write the second factor into the store yourself. Disable it and have the user enroll again:
+
+```ts
+await auth.secondFactor.disable(user);
+```
+
+### `<call>: the <type> type does not sign in with a password, so it has no second factor`
+
+A `TypeError`.
+
+**When:** `secondFactor.enroll`, from JavaScript, on a user type without `password`. In TypeScript, `secondFactor` is absent from such a type.
+**Why:** a second factor is asked for after a password. A type that signs in otherwise has nothing to ask it after, and no login to show in the app.
+**Fix:** enroll only users of a type with `password: { login }`.
+
+---
+
+## Sign-in codes
+
+The messages start with `signInCode.confirm` — prefixed by the type with
+several user types: `patient.signInCode.confirm: …`. `signInCode.request`
+throws nothing but `STORE_FAILED`: an e-mail it cannot sign in is `null`.
+`signInCode.confirm` also rejects with
+[`CODE_INVALID`](#code_invalid--call-the-code-does-not-match-or-was-already-used),
+[`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
+[`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and
+[`VERSION_CONFLICT`](#version_conflict--call-expected-version-n-found-m);
+each of those entries has a paragraph for it.
+[The sign-in code guide](guide/sign-in-code.md) has the whole flow.
+
+### `TOKEN_STALE` — `<call>: the code was sent to an e-mail the user no longer has`
+
+`TokenError`, carrying the `userId`.
+
+**When:** `signInCode.confirm`, after the user's e-mail was changed — by
+`update`, or a patch naming the e-mail field — since the code was sent.
+**Why:** the code proves an address, and signing in with it would mark as
+verified an address the user no longer holds. The challenge is spent.
+**Fix:** answer 400, and request a new code: it goes to the current address.
+
+```ts
+const issued = await auth.signInCode.request(currentEmail);
+```
+
+### The code from an earlier e-mail is refused with `CODE_INVALID`
+
+**When:** the visitor asked for a code twice — pressed "send again", or
+opened the form in two tabs — and typed the code of the first e-mail.
+**Why:** every `request` issues a new code **with its own challenge**, and a
+code is checked against the challenge it was sent with. The cookie or the
+form field now holds the second challenge, so the first code does not
+match it — and costs an attempt.
+**Fix:** tell the visitor that only the last code sent works, and put the
+time it was sent in the e-mail's subject or text so they can tell the
+e-mails apart. The earlier challenge is not revoked: it still expires on its
+own.
+
+### `signInCode.request` answers `null` for a user who exists
+
+**When:** `signInCode.request(email)`, for an address you can see in the
+database.
+**Why**, in the order to check:
+
+1. **The user is inactive.** An inactive user gets no code, and the answer
+   is the same as for nobody.
+2. **It is another user type.** `clinic.patient.signInCode.request` looks
+   among patients only; the same address may hold a user of another type.
+3. **The address is not the type's e-mail field.** A type whose `email`
+   option names `contact` is looked up by `contact`. A login that looks like
+   an e-mail — a `username` of `ada@example.com` — is not an e-mail, and is
+   `null` too.
+
+The e-mail is trimmed and lowercased before the lookup, so case and
+surrounding spaces are never the cause.
+**Fix:** `setActive(user, true)`; call the right type's `signInCode`; name
+the field with `email: 'contact'`. Do not tell the visitor which case it
+was — the route answers the same page either way.
+
+### `TS2339: Property 'signInCode' does not exist on type 'TypeApi<…>'.`
+
+Also `Property 'signInCode' does not exist on type 'Janus<…>'.`, with the
+single-type form, `janus({ user })`.
+
+**When:** `tsc`, on `auth.signInCode` or `clinic.<type>.signInCode`.
+**Why:** the user type has no e-mail: no field called `email`, and no
+`email` option naming one. A code has nowhere to be sent, so the flow is
+absent from the type.
+**Fix:** name the field that holds the e-mail:
+
+```ts
+janus({
+  users: {
+    staff: { schema: Staff, password: { login: 'username' }, email: 'workEmail' },
+  },
+  ...
+});
+```
+
+---
+
 ## Permissions
 
 ### `PERMISSION_DEPTH` — `can: checking <type>#<permission> crossed more than <n> relations without an answer`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",