@nxgt/janus 0.4.0 → 0.5.0

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/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.
@@ -79,7 +84,10 @@ 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 | `userId` |
-| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means) | |
+| `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 | |
+| `CODE_INVALID` | `TokenError` | 401 | A second factor's code that does not match, or was already accepted — see [the second factor](second-factor.md#confirming-the-code-at-sign-in) | `attemptsLeft` from `confirm`: what the challenge has left, `0` once it is spent. None from `activate` |
+| `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.