@nxgt/janus-hono 0.3.0 → 0.3.2

package/README.md

@@ -51,7 +51,7 @@ declarations import without extensions, so `nodenext` is not supported.
 | `signOut(c, auth)` | Revokes the session the request presents and clears the cookie, whatever the answer. `false` when the request presented no session, or an unknown one |
 | `janusErrors({ report?, fallback? })` | An `app.onError` handler: every `JanusError` answered with `statusOf(code)` and `bodyOf(error)`; anything else to `fallback`, or to Hono's own handling. `report(error, c)` sees every one answered 5xx first — `STORE_FAILED` and the like, for your logs |
 | `statusOf(code)` | The status a code deserves: `STORE_FAILED` 503, `CREDENTIALS_INVALID` and `CODE_INVALID` 401, `USER_INACTIVE` 403, `LOGIN_TAKEN`, `SECOND_FACTOR_NOT_ENROLLED` and `SECOND_FACTOR_ACTIVE` 409, … Exhaustive over `JanusErrorCode` |
-| `bodyOf(error)` | `{ code }`, plus `issues` for `USER_INVALID`, `minLength` for `PASSWORD_TOO_SHORT` and `attemptsLeft` for a `CODE_INVALID` from `secondFactor.confirm` — what the client can act on, and nothing else |
+| `bodyOf(error)` | `{ code }`, plus `issues` for `USER_INVALID`, `minLength` for `PASSWORD_TOO_SHORT` and `attemptsLeft` for any `CODE_INVALID` that carries it — `secondFactor.confirm`'s and `signInCode.confirm`'s — what the client can act on, and nothing else |
 | `SessionOptions<Type>` | `{ type?, required? }`, the options of `session()` — for a wrapper of your own |
 | `SessionEnv<typeof auth, Type?, Required?>` | The `Env` `session()` sets, for `new Hono<SessionEnv<typeof auth>>()` |
 | `UserOfAuth<typeof auth>` | The users an instance knows, as a union narrowed by `user.type` |
@@ -223,7 +223,7 @@ passes `{ subject: (c) => … }` to `permission()`; one without permissions uses
 
 ## Documentation
 
-- [Guides](docs/README.md) — wiring the middleware, the routes of a sign-in and of a second factor, guarded routes
+- [Guides](docs/README.md) — wiring the middleware, the routes of a sign-in, of a second factor and of a code sent by e-mail, guarded routes
 - [Troubleshooting](docs/troubleshooting.md) — by the symptom or message you see
 - [Roadmap](docs/roadmap.md) — what is next, and what is not planned
 

package/docs/README.md

@@ -5,7 +5,7 @@ give the detail.
 
 | Page | Read it when |
 | --- | --- |
-| [The routes of an application](guide/routes.md) | You are writing sign-up, sign-in, a second factor's code, sign-out and the e-mail flows as Hono routes, with one user type or several |
+| [The routes of an application](guide/routes.md) | You are writing sign-up, sign-in, a second factor's code, a sign-in by e-mailed code, sign-out and the e-mail flows as Hono routes, with one user type or several |
 | [Guarded routes and writing tuples](guide/permissions.md) | You are guarding a route with a permission, passing a condition's context, or granting and revoking from a route |
 | [Troubleshooting](troubleshooting.md) | A route answers something you did not expect, or the compiler refuses one |
 | [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/routes.md

@@ -142,6 +142,9 @@ With `secondFactor` configured, `signIn` may answer a challenge instead of a
 session: narrow on `status` before `sendSession` — see
 [A second factor](#a-second-factor).
 
+To sign in with no password, by a code sent to the user's e-mail, see
+[A code sent by e-mail](#a-code-sent-by-e-mail).
+
 The refusals need no `try`: `janusErrors()` answers them.
 
 | Thrown | Answered |
@@ -168,7 +171,7 @@ return c.json({
 ## A second factor
 
 With `janus({ secondFactor })`, `signIn` answers either a session or a
-**challenge** — `{ status: 'secondFactor', challenge, expiresAt }` — and
+**challenge** — `{ status: 'secondFactor', challenge, expiresAt, userId }` — and
 `sendSession` only takes the first. **Narrow on `status` before
 `sendSession`**: passing `signIn`'s answer straight in no longer compiles,
 because a challenge has no `token` and no `session`.
@@ -264,6 +267,114 @@ app.delete('/account/second-factor', session(auth, { required: true }), async (c
 The key rotation, the attempts and the replay rules are
 [`@nxgt/janus`'s second factor guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/second-factor.md).
 
+## A code sent by e-mail
+
+A sign-in by e-mailed code is two routes, built like
+[the second factor's](#a-second-factor): the first asks for a code and keeps
+the **challenge** in a cookie scoped to the second, which takes the code and
+opens the session. Sending the e-mail is yours.
+
+```ts
+import { randomBytes } from 'node:crypto';
+import { sendSession } from '@nxgt/janus-hono';
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie';
+
+const CODE_CHALLENGE = 'sign-in-code';
+const codeScope = { path: '/sign-in/email', httpOnly: true, secure: true, sameSite: 'Strict' } as const;
+
+app.post('/sign-in/email', async (c) => {
+	const { email } = await c.req.json();
+	const issued = await auth.signInCode.request(email);
+	if (issued !== null) {
+		void mailer.send(issued.email, `Your sign-in code: ${issued.code}`); // the code only; not awaited
+	}
+	// the same answer either way: a decoy challenge when nobody holds the e-mail
+	const challenge = issued?.challenge ?? randomBytes(32).toString('base64url');
+	setCookie(c, CODE_CHALLENGE, challenge, { ...codeScope, maxAge: 600 });
+	return c.json({ next: 'code' }, 202);
+});
+
+app.post('/sign-in/email/code', async (c) => {
+	const { code } = await c.req.json();
+	const challenge = getCookie(c, CODE_CHALLENGE);
+	if (challenge === undefined) return c.json({ code: 'TOKEN_UNKNOWN' }, 400);
+	const user = sendSession(c, auth, await auth.signInCode.confirm(challenge, code));
+	deleteCookie(c, CODE_CHALLENGE, codeScope);
+	return c.json({ id: user.id });
+});
+```
+
+**The request route answers the same whoever asked** — the same status, the
+same body, and a cookie either way. `signInCode.request` answers `null` for
+an address nobody holds, and a route that answered differently, or set no
+cookie, would tell anyone which addresses have an account. The decoy is 32
+random bytes, the shape of a real challenge; confirming it is
+`TOKEN_UNKNOWN`. `maxAge: 600` is the default ten minutes of
+`tokens.signInCode`, written out so both cookies match. Not awaiting the
+mailer keeps the answer's time from telling either. Rate-limit this route
+per address and per client: every call sends an e-mail.
+
+The code route still tells a decoy apart: a wrong code against it is 400
+`TOKEN_UNKNOWN`, against a real challenge 401 `CODE_INVALID` with
+`attemptsLeft`. Where your users' addresses must stay secret, answer every
+refusal of that route alike, before `janusErrors()` sees it:
+
+```ts
+import { JanusError } from '@nxgt/janus';
+
+app.onError((error, c) =>
+	error instanceof JanusError && error.code !== 'STORE_FAILED' && c.req.path === '/sign-in/email/code'
+		? c.json({ code: 'CODE_INVALID' }, 401) // no attemptsLeft: it would tell a real challenge from a decoy
+		: answer(error, c),
+);
+```
+
+with `answer` the `janusErrors()` of [Wiring](#wiring).
+
+The code goes in the e-mail, **the challenge never does**: not in the
+e-mail, not in a link, not in a log.
+
+A wrong code leaves the cookie in place, so the visitor types it again.
+`janusErrors()` answers what `confirm` throws, with the statuses above:
+
+| Thrown | Answered |
+| --- | --- |
+| `CODE_INVALID` | 401 `{ code, attemptsLeft }` — the attempts the challenge has left, `0` once the fifth wrong code spent it |
+| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED` | 400 `{ code }` — offer to send a new code |
+| `TOKEN_STALE` | 400 `{ code }` — the e-mail changed since the code was sent: send a new one |
+| `USER_INACTIVE` | 403 `{ code }` |
+
+`confirm` marks the user's e-mail verified: the code reached the inbox.
+
+### With a second factor
+
+With `janus({ secondFactor })`, a user whose factor is active gets a
+**challenge** from `signInCode.confirm`, not a session — the code proves the
+e-mail, not the factor — and passing its answer straight to `sendSession`
+no longer compiles on a type with a password. Narrow on `status`, and hand
+the challenge to the second factor's cookie, so
+[`/sign-in/code`](#a-second-factor) takes it from there:
+
+```ts
+app.post('/sign-in/email/code', async (c) => {
+	const { code } = await c.req.json();
+	const challenge = getCookie(c, CODE_CHALLENGE);
+	if (challenge === undefined) return c.json({ code: 'TOKEN_UNKNOWN' }, 400);
+	const result = await auth.signInCode.confirm(challenge, code);
+	deleteCookie(c, CODE_CHALLENGE, codeScope);
+	if (result.status === 'secondFactor') {
+		setCookie(c, CHALLENGE, result.challenge, { ...scope, expires: result.expiresAt });
+		return c.json({ next: 'secondFactor' });
+	}
+	const user = sendSession(c, auth, result);
+	return c.json({ id: user.id });
+});
+```
+
+A user type with no password has no second factor, so its `confirm` always
+answers a session. The attempts, the lifetime and every refusal are
+[`@nxgt/janus`'s sign-in code guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/sign-in-code.md).
+
 ## Sign-out
 
 ```ts
@@ -343,5 +454,6 @@ as staff replaces the patient's cookie.
 - [`@nxgt/janus` — sessions](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/sessions.md) — lifespans, renewal, the cookie's attributes
 - [`@nxgt/janus` — errors](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/errors.md) — every code
 - [`@nxgt/janus` — the second factor](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/second-factor.md) — keys, states, attempts
+- [`@nxgt/janus` — sign-in codes](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/sign-in-code.md) — requesting, the challenge, attempts, passwordless types
 - [Guarded routes and writing tuples](permissions.md) — `permission()`, `provide()`
 - [Troubleshooting](../troubleshooting.md)

package/docs/troubleshooting.md

@@ -29,7 +29,7 @@ for what causes each.
 - [`401` with an empty body, for a signed-in user](#401-with-an-empty-body-for-a-signed-in-user)
 - [`503 {"code":"STORE_FAILED"}` on every route](#503-codestore_failed-on-every-route)
 - [`400 {"code":"HASH_UNSUPPORTED"}` on sign-in](#400-codehash_unsupported-on-sign-in)
-- [`401 {"code":"CODE_INVALID","attemptsLeft":<n>}` on the code form](#401-codecode_invalidattemptsleftn-on-the-code-form)
+- [`401 {"code":"CODE_INVALID","attemptsLeft":<n>}` on the code form](#401-codecode_invalidattemptsleftn-on-the-code-form) — a second factor's, or the code sent by e-mail
 - [`409 {"code":"SECOND_FACTOR_ACTIVE"}` or `409 {"code":"SECOND_FACTOR_NOT_ENROLLED"}`](#409-codesecond_factor_active-or-409-codesecond_factor_not_enrolled)
 - [The browser never sends the cookie back](#the-browser-never-sends-the-cookie-back)
 - [A bearer client holds an expiry earlier than the session's](#a-bearer-client-holds-an-expiry-earlier-than-the-sessions)
@@ -155,7 +155,7 @@ Also: `Type 'SecondFactorRequired' is missing the following properties …: toke
 given a `secondFactor`.
 
 **Why:** `signIn` then answers a session, or `{ status: 'secondFactor',
-challenge, expiresAt }` for a user whose second factor is active — and a
+challenge, expiresAt, userId }` for a user whose second factor is active — and a
 challenge is no session to send.
 
 **Fix:** switch on `status`, and send the session `secondFactor.confirm`
@@ -318,7 +318,8 @@ Also `401 {"code":"CODE_INVALID"}`, with no `attemptsLeft`, from
 
 **When:** a route calling `secondFactor.confirm(challenge, code)` or
 `secondFactor.activate(user, code)`, with a code that does not match or was
-already used.
+already used — or a route calling `signInCode.confirm(challenge, code)`, the
+code sent by e-mail, with a code that does not match or is not six digits.
 
 **Why:** `janusErrors()` answers a wrong code 401, like a wrong password. On
 `confirm`, `attemptsLeft` is what the challenge has left of its five attempts;
@@ -327,6 +328,9 @@ at `0` it is spent, and the next call with it answers
 is a clock off by more than about 30 seconds, or a code used already — see
 [`@nxgt/janus`'s troubleshooting](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/troubleshooting.md#the-code-the-authenticator-app-shows-is-refused-with-code_invalid).
 
+On `signInCode.confirm`, `attemptsLeft` counts the same five attempts, and
+at `0` the challenge is spent too: the right code no longer works with it.
+
 **Fix:** read `attemptsLeft` in the client: ask again while it is above `0`,
 and go back to the sign-in form once it is `0`.
 
@@ -339,6 +343,18 @@ if (response.status === 401) {
 }
 ```
 
+For the code sent by e-mail, request a new code once it is `0` — a new
+challenge, with five attempts of its own:
+
+```ts
+const response = await fetch('/sign-in/email/code', { method: 'POST', body: JSON.stringify({ code }) });
+if (response.status === 401) {
+	const { attemptsLeft } = await response.json();
+	if (attemptsLeft === 0) showEmailForm(); // POST /sign-in/email again: a new code
+	else showCodeForm(`Wrong code — ${attemptsLeft} attempts left`);
+}
+```
+
 ### `409 {"code":"SECOND_FACTOR_ACTIVE"}` or `409 {"code":"SECOND_FACTOR_NOT_ENROLLED"}`
 
 **When:** a route calling `secondFactor.enroll` or `secondFactor.activate`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-hono",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Hono middleware for @nxgt/janus: the signed-in user on every request, the session cookie, routes guarded by a permission, and every error as its status",
 	"license": "MIT",
 	"type": "module",
@@ -49,13 +49,13 @@
 		]
 	},
 	"devDependencies": {
-		"@nxgt/janus": "^0.5.0",
+		"@nxgt/janus": "^0.7.0",
 		"@types/bun": "^1.4.2",
 		"hono": "^4.13.9",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@nxgt/janus": "^0.5.0",
+		"@nxgt/janus": "^0.7.0",
 		"hono": "^4.13.4",
 		"typescript": "^6.0.3"
 	}