@nxgt/janus 0.4.0 → 0.6.0

package/docs/README.md

@@ -14,6 +14,8 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [Users](guide/users.md) | You are wiring `janus()`, declaring one or several user types, or calling `create`, `update`, `list`, `delete` |
 | [Sessions](guide/sessions.md) | You need to know who a request belongs to, set or clear the cookie, renew, sign out, or test expiry |
 | [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, disabling |
 | [Password hashing](guide/passwords.md) | You are choosing a hasher, raising its cost, moving to argon2id, or importing hashes from another system |
 
 ### Permissions — `@nxgt/janus/permissions`

package/docs/guide/adapters.md

@@ -97,10 +97,12 @@ interface UserRecord {
 }
 ```
 
-`secret` is **opaque to a store**: once the second factor ships, the core
-will seal it with a key the application holds before a store sees it, so a
-dump of the users cannot produce a code. Keep it like a password hash — byte
-for byte, no parsing, no trimming. Store
+`secret` is **opaque to a store**: the core seals it with a key the
+application holds — AES-256-GCM, written `v1.<key id>.<iv>.<ciphertext>` —
+before a store sees it, so a dump of the users cannot produce a code. Keep it
+like a password hash — byte for byte, no parsing, no trimming. The core
+rewrites it, sealed under another key, when the application
+[rotates its keys](second-factor.md#rotating-the-keys). Store
 the second factor whole: a method without a secret, or a `lastStep` without a
 method, is a record the core never writes.
 
@@ -150,7 +152,7 @@ interface TokenRecord {
 	readonly tokenHash: string;
 	readonly kind: TokenKind;
 	readonly userId: Id;
-	readonly address: string;
+	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 attempts: number; // 0 at insertion
 	readonly expiresAt: Date;
@@ -160,7 +162,9 @@ interface TokenRecord {
 ```
 
 A token redeemed for another kind is unknown: every method that takes a
-`kind` matches on it. `codeHash` and `attempts` round-trip like every other
+`kind` matches on it. A `secondFactor` token is the challenge `signIn`
+answers, and its `address` is `''`: a column or a validator that refuses an
+empty string refuses every sign-in with a code. `codeHash` and `attempts` round-trip like every other
 field. An adapter whose stored tokens predate them reads them as `null` and
 `0`, as the three published adapters do, so no data migration is needed for
 them.
@@ -294,7 +298,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 44: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — twelve of them | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 45: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — twelve of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 15: the relation store, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty
@@ -320,6 +324,7 @@ while you work on it, never to ship:
 | `tokens.countAttempt` | two calls answer `attempts` 1 then 2, `codeHash` as written; `consumeToken` answers the count |
 | `tokens.countAttemptConcurrency` | twenty concurrent calls answer 1 to 20, each once |
 | `tokens.countAttemptRace` | attempts racing one redemption: the counts answered unspent are 1 to the final count, and every answer after the spend carries that final count |
+| `tokens.challenge` | a second-factor challenge, whose `address` is `''`, kept, counted and spent like any token |
 | `tokens.countAttemptSpent` | a spent token answered unchanged; another kind and an unknown hash answer `null` and count nothing |
 | `outage.countAttempt` | a store that cannot answer rejects, never `null` |
 

package/docs/guide/email-flows.md

@@ -51,6 +51,9 @@ clinic.patient.verifyEmail.send; // exists: `email` names the field
 clinic.staff.verifyEmail;
 ```
 
+A type with an e-mail can also sign in with a code sent to it, with or
+without a password — see [sign-in codes](sign-in-code.md).
+
 ## Options
 
 | Option | Type | Default | Effect |
@@ -142,5 +145,6 @@ never the token, and no refusal's message contains it.
 ## See also
 
 - [Users](users.md) — `email`, `update`, and the other per-type methods
+- [Sign-in codes](sign-in-code.md) — the third flow that sends an e-mail: a code, not a link
 - [Sessions](sessions.md) — `signOutEverywhere`, which `resetPassword.confirm` calls for you
 - [Errors](errors.md) — every code, and the status it deserves

package/docs/guide/errors.md

@@ -27,7 +27,11 @@ export function statusOf(code: JanusErrorCode): number {
 		case 'TOKEN_STALE':
 			return 400;
 		case 'CREDENTIALS_INVALID':
+		case 'CODE_INVALID':
 			return 401;
+		case 'SECOND_FACTOR_NOT_ENROLLED':
+		case 'SECOND_FACTOR_ACTIVE':
+			return 409;
 		case 'USER_INACTIVE':
 			return 403;
 		case 'UNSUPPORTED':
@@ -39,11 +43,12 @@ export function statusOf(code: JanusErrorCode): number {
 
 export function toResponse(error: unknown): Response {
 	if (!(error instanceof JanusError)) throw error;
-	return Response.json({ code: error.code }, { status: statusOf(error.code) });
+	const body = error.code === 'CODE_INVALID' ? { code: error.code, attemptsLeft: error.attemptsLeft } : { code: error.code };
+	return Response.json(body, { status: statusOf(error.code) });
 }
 ```
 
-`JanusErrorCode` is a union of sixteen string literals, so that `switch` is
+`JanusErrorCode` is a union of nineteen string literals, so that `switch` is
 exhaustive: when a code is added, a function like `statusOf` stops compiling
 instead of answering `undefined`.
 
@@ -61,7 +66,7 @@ told they do not exist.
 | Thrown | When | Class |
 | --- | --- | --- |
 | At **call** time, on a value that could have come from a request | a taken login, a wrong password, a spent token, an outage | a `JanusError` subclass, with a `code` |
-| At **wiring** time, from how you called the library | a lifespan that is not a duration, a store missing a method, a model with a loop, a malformed tuple string | a bare `TypeError` |
+| At **wiring** time, from how you called the library | a lifespan that is not a duration, a store missing a method, a model with a loop, a malformed tuple string, a sealing key removed while secrets sealed with it are stored, a user with an active second factor signing in through a `janus()` given no `secondFactor` | a bare `TypeError` |
 
 No request handler should ever answer a `TypeError` — it is a bug in the code
 that wired the library, so no handler needs to tell it apart.
@@ -78,8 +83,11 @@ that wired the library, so no handler needs to tell it apart.
 | `PASSWORD_TOO_SHORT` | `CredentialError` | 400 | Below `password.minLength` | `minLength` — never the password |
 | `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 | `userId` |
-| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means) | |
+| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, or the right code | `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) — or a sign-in code sent by e-mail — see [sign-in codes](sign-in-code.md#attempts) | `attemptsLeft` from either `confirm`: what the challenge has left, `0` once it is spent. None from `activate`. `userId` |
+| `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`, or `confirm` after the factor was disabled | `userId` |
+| `SECOND_FACTOR_ACTIVE` | `SecondFactorError` | 409 | `enroll` or `activate` on a factor already active: `disable` it first | `userId` |
 | `INVALID_CURSOR` | `InvalidCursorError` | 400 | A cursor this store did not mint. Never a silent first page | |
 | `UNSUPPORTED` | `UnsupportedError` | 501 | The wired store lacks an optional capability — `collectExpired` without `deleteExpiredSessions` | `slot`, `operation` |
 | `PERMISSION_DEPTH` | `PermissionDepthError` | 500 | A check or list walked past `maxDepth`. **Not a denial** | `permission`, `maxDepth` |
@@ -114,13 +122,17 @@ async function signIn(email: string, password: string): Promise<Response> {
   would read as "no".
 - **`VERSION_CONFLICT` is a retry**: read the user again, reapply, write with
   the new `version`.
+- **`CODE_INVALID`'s `attemptsLeft`** belongs in the body — the form can say
+  how many attempts are left. `0` means the challenge is spent: send the visitor
+  back to the password.
 - **`USER_INVALID`'s `issues`** have the schema's own paths
   (`['address', 'city']`), so a form can show each next to its field.
 
 ## No message holds a secret
 
-Not a password, not a hash, not a session token, not a token's hash, and not a
-connection URI — a connection string holds a password. Nor a login: a message
+Not a password, not a hash, not a session token, not a token's hash, not a
+challenge, a second factor's code or its secret, and not a connection URI — a
+connection string holds a password. Nor a login: a message
 reports a shape, never a value, so `LOGIN_TAKEN` carries the login in
 `error.login` and not in its message. A message names the
 call you wrote (`signIn`, `users.findUser`) so you know where to look.