@nxgt/janus 0.5.0 → 0.7.0

package/docs/troubleshooting.md

@@ -74,6 +74,13 @@ How the messages are shaped:
 - [`<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)
@@ -225,9 +232,11 @@ Also: `janus: store.<slot> is missing`, `janus: store must be an object with use
 
 **When:** `janus({...})`, from JavaScript or with a store typed loosely. TypeScript refuses a partial store at compile time and names the method.
 **Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. `deleteExpiredSessions` is the one optional method: absent, or a function.
-An adapter written against `@nxgt/janus` 0.3 reports
-`store.tokens has no method countAttempt` until it implements the method 0.4
-added.
+An adapter written for an earlier `@nxgt/janus` reports the method a later
+release added to the port: `store.tokens has no method countAttempt` for one
+written against 0.3 (the method came in 0.4), and
+`store.tokens has no method spendUserTokens` for one written against 0.6 (the
+method came in 0.7).
 
 **Fix:** pass the three stores, whole:
 
@@ -237,17 +246,17 @@ import { createMemoryStores, janus } from '@nxgt/janus';
 janus({ ..., store: createMemoryStores() });
 ```
 
-For `countAttempt`, upgrade the published adapter to the release that
-implements it — `@nxgt/janus-drizzle` 0.2, `@nxgt/janus-mongo` 0.3,
-`@nxgt/janus-redis` 0.2:
+Upgrade the published adapter to the release that implements both —
+`@nxgt/janus-drizzle` 0.3, `@nxgt/janus-mongo` 0.4, `@nxgt/janus-redis` 0.3:
 
 ```bash
-bun add @nxgt/janus@^0.4 @nxgt/janus-drizzle@^0.2 # or @nxgt/janus-mongo@^0.3, @nxgt/janus-redis@^0.2
+bun add @nxgt/janus@^0.7 @nxgt/janus-drizzle@^0.3 # or @nxgt/janus-mongo@^0.4, @nxgt/janus-redis@^0.3
 ```
 
-Your own adapter implements it as
-[`TokenStore.countAttempt`](guide/adapters.md#tokenstorecountattempt) sets
-out, then runs the conformance suite.
+Your own adapter implements them as
+[`TokenStore.countAttempt`](guide/adapters.md#tokenstorecountattempt) and
+[`TokenStore.spendUserTokens`](guide/adapters.md#tokenstorespendusertokens)
+set out, then runs the conformance suite.
 
 ### `janus: relations must be a relation store — relations.deleteEntity is missing`
 
@@ -291,7 +300,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`, `tokens.resetPassword` and `secondFactor.challenge`. 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.
@@ -466,7 +475,7 @@ if (error instanceof UserInvalidError) {
 Also `changePassword: the current password does not match`.
 
 **When:** `signIn`, `changePassword`.
-**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
+**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. Also a sign-in that verified a password written over while it ran (`reason: 'wrongPassword'`): its session is revoked, or its challenge spent, before the refusal. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
 **Fix:** answer 401 with the same body whatever the reason:
 
 ```ts
@@ -492,8 +501,8 @@ 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. Also `secondFactor.confirm`, for a user set inactive after `signIn` asked for a code.
-**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. On `secondFactor.confirm`, the challenge is spent: reactivating the user does not revive it.
+**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`
@@ -515,10 +524,14 @@ answered: `secondFactor.confirm: no such challenge`,
 
 **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.
+the code that opens the session, by the fifth wrong code, by a refusal
+that ends it (`USER_INACTIVE`, `SECOND_FACTOR_NOT_ENROLLED`), and by a
+password written — `resetPassword.confirm`, `setPassword`, `changePassword` —
+which ends every sign-in left waiting on its code.
+`TOKEN_UNKNOWN` also covers a challenge whose user was deleted, one
+confirmed through another user type's `secondFactor`, and a challenge passed
+where a code was expected — the two arguments swapped. Another type's
+`confirm` still costs an attempt, and the fifth spends the challenge.
 **Fix:** answer 400 and send the visitor back to sign in, which asks for a new
 code. To give slower visitors more time:
 
@@ -526,10 +539,37 @@ code. To give slower visitors more time:
 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, by a refusal
+that ends it (`TOKEN_STALE`, `USER_INACTIVE`), and by the next `request` for
+the same user: only the last code sent works, so a visitor who asked twice
+and typed the first code gets `TOKEN_SPENT` — and when two requests race,
+even the last code can be spent: at most one survives, sometimes none. `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, 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 — and the fifth such call
+spends it, as a fifth wrong code would.
+**Fix:** answer 400 and offer to send a new code — and tell the visitor to
+use the latest e-mail. 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.
-**Why:** confirming it would verify an address nobody holds any more. The token is spent.
+**When:** `verifyEmail.confirm` or `resetPassword.confirm`, after the user changed their e-mail — even while the link was being redeemed: the address is checked again on the very record the write replaces.
+**Why:** confirming it would verify an address nobody holds any more, or reset a password through one. The token is spent, and nothing is written.
 **Fix:** send a new token to the current address: `await auth.verifyEmail.send(user)`.
 
 ### `INVALID_CURSOR` — `<call>: this cursor was not minted by this store, or was minted for another ordering (<n> characters)`
@@ -582,7 +622,8 @@ const page = await access.list(user, 'view', 'record', {
 
 ## Second factor
 
-Every entry here needs `janus({ ..., secondFactor })`. The messages start with
+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
@@ -595,8 +636,8 @@ each of those entries has a paragraph for it.
 
 The same for `session` and `user`.
 
-**When:** `tsc`, wherever `signIn`'s answer is read, once `janus()` is given a `secondFactor`.
-**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.
+**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, userId }` 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
@@ -613,11 +654,25 @@ const signedIn = await auth.secondFactor.confirm(challenge, code); // { status:
 
 ### `CODE_INVALID` — `<call>: the code does not match, or was already used`
 
-`TokenError`, carrying `attemptsLeft` on `secondFactor.confirm`.
+`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).
 
-**When:** `secondFactor.activate(user, code)` or `secondFactor.confirm(challenge, code)`.
-**Why:** the code is wrong, or it was accepted before: a code is accepted once. On `confirm`, every call costs one of the challenge's five attempts, counted before anything is checked. `attemptsLeft` is what remains; at `0`, the challenge is spent and the next `confirm` is `TOKEN_SPENT`. On `activate` there is no challenge, no `attemptsLeft`, and nothing is spent: the user tries the next code.
-**Fix:** answer 401 with `attemptsLeft`, and send the visitor back to sign in once it is `0`:
+**`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';
@@ -632,7 +687,34 @@ try {
 }
 ```
 
-If the code the user typed is the one their app shows, see the next entry.
+**`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`
 
@@ -741,6 +823,89 @@ A `TypeError`.
 
 ---
 
+## 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 spent by the new `request`: the
+first code, even with its own challenge, answers `TOKEN_SPENT`.
+
+### `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.5.0",
+	"version": "0.7.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",