@nxgt/janus-hono 0.5.0 → 0.5.2

package/README.md

@@ -300,7 +300,7 @@ passes `{ subject: (c) => … }` to `permission()`; one without permissions uses
 
 ## Documentation
 
-- [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
+- [Guides](docs/README.md) — wiring the middleware, the routes of a sign-in, of a second factor and of a code or a link 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, a sign-in by e-mailed 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 or link, 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

@@ -465,6 +465,117 @@ 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).
 
+## A link sent by e-mail
+
+A sign-in by e-mailed link takes three routes. The first asks for a link.
+The link then opens **a page that spends nothing**, and that page's button
+posts the token back to the third route, which signs the user in.
+
+Never sign in on the link's `GET`. Mail scanners open every link in an
+e-mail and would spend the token before the user clicks. Sending the e-mail
+is your job.
+
+```ts
+import { JanusError, TokenError } from '@nxgt/janus';
+import { sendSession } from '@nxgt/janus-hono';
+import { csrf } from 'hono/csrf';
+
+const ORIGIN = 'https://app.example';
+const TOKEN = /^[A-Za-z0-9_-]{43}$/; // 32 bytes, base64url: the only thing echoed into the page
+
+app.post('/sign-in/email/link', async (c) => {
+	const { email } = await c.req.json();
+	const issued = await auth.magicLink.request(email);
+	if (issued !== null) {
+		void mailer.send(issued.email, `${ORIGIN}/sign-in/link?token=${issued.token}`); // not awaited, so the answer's time tells nothing; in production, a queue that awaits and retries
+	}
+	return c.body(null, 202); // the same answer either way: nothing of a link reaches the visitor
+});
+
+// GET: what the e-mail links to. It renders a page and does nothing else.
+app.get('/sign-in/link', (c) => {
+	const token = c.req.query('token') ?? '';
+	c.header('Referrer-Policy', 'strict-origin'); // the origin only: never the token
+	c.header('Cache-Control', 'no-store');
+	if (!TOKEN.test(token)) return c.text('This link is not valid.', 400);
+	return c.html(`<!doctype html><meta charset="utf-8"><title>Sign in</title>
+<form method="post" action="/sign-in/link">
+	<input type="hidden" name="token" value="${token}">
+	<button>Sign in</button>
+</form>`);
+});
+
+// POST: the page's button. csrf() answers 403 to a form posted from another site.
+app.post('/sign-in/link', csrf({ origin: ORIGIN }), async (c) => {
+	const token = String((await c.req.parseBody()).token ?? '');
+	try {
+		sendSession(c, auth, await auth.magicLink.confirm(token));
+		return c.redirect('/', 303);
+	} catch (error) {
+		if (error instanceof TokenError || (error instanceof JanusError && error.code === 'VERSION_CONFLICT')) {
+			return c.redirect('/sign-in?link=expired', 303); // ask for another link
+		}
+		throw error; // USER_INACTIVE 403, STORE_FAILED 503: janusErrors()
+	}
+});
+```
+
+- **The request route answers `202` whoever asked.** `magicLink.request`
+  answers `null` for an address nobody holds and for an inactive user. With
+  a code, the route needs a decoy challenge. Nothing of a link reaches the
+  visitor, so here there is no decoy to forge. Rate-limit the route per
+  address and per client: every call sends an e-mail and cancels the link
+  sent before it.
+- **The page echoes only a token of the token's shape.** Anything else
+  written into the HTML is a cross-site scripting hole. Use a button, not a
+  script that submits the form by itself: a scanner that runs scripts would
+  submit it too.
+- **Put `csrf({ origin })` on the `POST`.** The token does not identify the
+  browser that asked for it. Without the check, any site could post a token
+  for an account it controls and sign its visitor into that account.
+- **Send the page with `Referrer-Policy: strict-origin`.** A `Referer` then
+  holds the origin only — never the path and the token in its query — so
+  nothing the page loads learns the token. Not `no-referrer`: with it the
+  browser posts the form with `Origin: null`, and wherever `csrf()` falls
+  back to the `Origin` — no `Sec-Fetch-Site` on plain HTTP off `localhost`,
+  or from an older browser — the button's own `POST` answers
+  [403](../troubleshooting.md#403-forbidden-on-post-sign-inlink).
+- **Answer the `POST` with a `303`**, so that reloading the page does not
+  post the spent token again. The cookie that `sendSession` set is sent with
+  the redirect.
+
+`confirm` spends the link on its first call, whether that call signs the
+user in or is refused, and it marks the user's e-mail verified. To the user,
+every `TOKEN_*` error means the same thing: ask for another link. The rare
+`VERSION_CONFLICT` means the same too; it happens when the user record was
+written while the e-mail was being proved.
+
+### With a second factor
+
+With `janus({ secondFactor })`, a user whose factor is active gets a
+**challenge** from `magicLink.confirm`, not a session. On a type with a
+password, passing that answer straight to `sendSession` no longer compiles.
+Narrow on `status`, and hand the challenge to the second factor's cookie:
+
+```ts
+app.post('/sign-in/link', csrf({ origin: ORIGIN }), async (c) => {
+	const token = String((await c.req.parseBody()).token ?? '');
+	const result = await auth.magicLink.confirm(token);
+	if (result.status === 'secondFactor') {
+		setCookie(c, CHALLENGE, result.challenge, { ...scope, expires: result.expiresAt });
+		return c.redirect('/sign-in/second-factor', 303); // a page of yours whose form posts the app's code to /sign-in/code
+	}
+	sendSession(c, auth, result);
+	return c.redirect('/', 303);
+});
+```
+
+[`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail) sends
+this e-mail with `mail.magicLink(issued)`, building its button with
+`links.magicLink(token)`. Point `links.magicLink` at the `GET` route above.
+For the lifetime and every refusal, see [`@nxgt/janus`'s sign-in link
+guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/magic-link.md).
+
 ## A step-up
 
 A route a stolen session should not run alone — deleting the account,

package/docs/roadmap.md

@@ -36,6 +36,10 @@ Nothing yet.
 
 Newest first; the [CHANGELOG](../CHANGELOG.md) holds every release.
 
+- **The routes of a sign-in link, v0.5.1** — the routes guide's
+  [A link sent by e-mail](guide/routes.md#a-link-sent-by-e-mail): a page
+  that spends nothing, a `POST` behind `csrf()` that confirms, and the
+  second factor's challenge handed on. Needs `@nxgt/janus` 0.15.0.
 - **A throttled sign-in's `retryAfter`, v0.5.0** — `janusErrors()` and
   `bodyOf()` answer `@nxgt/janus`'s throttled `CREDENTIALS_INVALID` with
   `retryAfter` in the body and a `Retry-After` header. Needs `@nxgt/janus`

package/docs/troubleshooting.md

@@ -35,6 +35,7 @@ for what causes each.
 - [`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) — a second factor's, or the code sent by e-mail
 - [`401 {"code":"CREDENTIALS_INVALID","retryAfter":<n>}` with the right password](#401-codecredentials_invalidretryaftern-with-the-right-password)
+- [`403 Forbidden` on `POST /sign-in/link`](#403-forbidden-on-post-sign-inlink) — Hono's `csrf()`, not `janusErrors()`
 - [`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)
@@ -156,15 +157,19 @@ const app = new Hono().use(session(auth), provide({ auth, access }));
 
 Also: `Type 'SecondFactorRequired' is missing the following properties …: token, session, user`.
 
-**When:** `sendSession(c, auth, await auth.signIn(...))`, once `janus()` is
-given a `secondFactor`.
+**When:** `sendSession(c, auth, await auth.signIn(...))`,
+`sendSession(c, auth, await auth.magicLink.confirm(token))` or
+`sendSession(c, auth, await auth.signInCode.confirm(challenge, code))`, once
+`janus()` is given a `secondFactor`, for a user type with a password.
 
-**Why:** `signIn` then answers a session, or `{ status: 'secondFactor',
+**Why:** each of the three then answers a session, or `{ status: 'secondFactor',
 challenge, expiresAt, userId }` for a user whose second factor is active — and a
-challenge is no session to send.
+challenge is no session to send. A link or a code sent by e-mail proves the
+e-mail, not the factor. A user type with no password has no second factor, so
+its `confirm` answers a session and compiles as it is.
 
 **Fix:** switch on `status`, and send the session `secondFactor.confirm`
-answers on the next request.
+answers on the next request. For the password form:
 
 ```ts
 app.post('/sign-in', async (c) => {
@@ -182,6 +187,23 @@ app.post('/sign-in/code', async (c) => {
 });
 ```
 
+`magicLink.confirm` and `signInCode.confirm` narrow the same way. They hand
+the challenge on in a cookie, which the guide's `/sign-in/code` reads instead of
+the body. `CHALLENGE`, `scope` and that route are under
+[A second factor](guide/routes.md#a-second-factor). The link route redirects, as below. The code route answers
+`c.json({ next: 'secondFactor' })` instead. See "With a second factor" under
+[a code sent by e-mail](guide/routes.md#with-a-second-factor) and under
+[a link sent by e-mail](guide/routes.md#with-a-second-factor-1).
+
+```ts
+const result = await auth.magicLink.confirm(token);
+if (result.status === 'secondFactor') {
+	setCookie(c, CHALLENGE, result.challenge, { ...scope, expires: result.expiresAt });
+	return c.redirect('/sign-in/second-factor', 303); // a page whose form posts the code to /sign-in/code
+}
+sendSession(c, auth, result);
+```
+
 ## Runtime
 
 ### `TypeError: permission(): c.var.object is already set`
@@ -452,6 +474,52 @@ To change the limit, `janus({ signIn: { throttle: { attempts, window } } })`;
 in a test, advance the clock past `retryAfter`, or wire
 `signIn: { throttle: false }`.
 
+### `403 Forbidden` on `POST /sign-in/link`
+
+The body is the text `Forbidden`, not a `{ code }`. It is not a `JanusError`:
+`csrf()` threw it, and `janusErrors()` hands it to Hono's default response, or
+to your `fallback`.
+
+**When:** the button of the page the e-mailed link opens, on the route
+guarded by `csrf({ origin: ORIGIN })` — see
+[a link sent by e-mail](guide/routes.md#a-link-sent-by-e-mail).
+
+**Why:** Hono's `csrf()` lets a form post through when the browser sends
+`Sec-Fetch-Site: same-origin`, or else an `Origin` header equal to `origin`,
+character for character. Neither held:
+
+- **The page and the route are on two origins.** The page may be served by a
+  development server on another port, or on `www.` while the route is on the
+  bare host. The browser then sends `same-site` or `cross-site`, and the
+  `Origin` decides.
+- **The browser sends no `Sec-Fetch-Site`.** It sends none to plain `http://`
+  on a host other than `localhost` or a loopback address, and an older browser
+  sends none at all. The `Origin` decides here too.
+- **The `Origin` is `null`.** A page sent with `Referrer-Policy: no-referrer`
+  makes the browser send `Origin: null` for every form it posts. So whenever
+  the `Origin` decides, the answer is 403, whatever `ORIGIN` holds.
+- **`ORIGIN` is not what the browser shows.** Check for `http` against
+  `https`, a missing or extra port, or a trailing `/`. Leaving `origin` out does
+  not help behind a proxy: `csrf()` then compares with the URL the app sees,
+  which is the proxy's `http://` upstream, not the public one.
+
+**Fix:** serve the page and the route on one origin, over HTTPS or on
+`localhost` in development. Redirect `www.` to the bare host, and post the form
+to a relative `action`. Set `ORIGIN` to the scheme, host and port the address
+bar shows. Send the page with `strict-origin`, as
+[the guide](guide/routes.md#a-link-sent-by-e-mail) does, never
+`no-referrer`. A `Referer` then holds the origin only, never the path and its
+token, and the form carries its real `Origin`.
+
+```ts
+const ORIGIN = process.env.ORIGIN ?? 'https://app.example'; // what the address bar shows, no trailing slash
+
+// on the GET page: the token's URL still reaches nobody, and Origin is no longer null
+c.header('Referrer-Policy', 'strict-origin');
+
+app.post('/sign-in/link', csrf({ origin: ORIGIN }), handler);
+```
+
 ### `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.5.0",
+	"version": "0.5.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.14.0",
+		"@nxgt/janus": "^0.16.0",
 		"@types/bun": "^1.4.2",
 		"hono": "^4.13.9",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@nxgt/janus": "^0.14.0",
+		"@nxgt/janus": "^0.16.0",
 		"hono": "^4.13.4",
 		"typescript": "^6.0.3"
 	}