@nxgt/janus-hono 0.5.0 → 0.5.1

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,110 @@ 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', 'no-referrer'); // the URL holds the token: send it nowhere
+	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.
+- **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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-hono",
-	"version": "0.5.0",
+	"version": "0.5.1",
 	"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.15.0",
 		"@types/bun": "^1.4.2",
 		"hono": "^4.13.9",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@nxgt/janus": "^0.14.0",
+		"@nxgt/janus": "^0.15.0",
 		"hono": "^4.13.4",
 		"typescript": "^6.0.3"
 	}