@nxgt/janus-hono 0.7.1 → 0.7.3

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 or link, the device cookie of a sign-in from a new device, 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, accepting an invitation, the device cookie of a sign-in from a new device, 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

@@ -379,22 +379,25 @@ 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;
 
+/** Runs `work` off the request, and reports what it throws: nobody else will see it. */
+const offRequest = (work: () => Promise<unknown>): void => void work().catch(reportError);
+
 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 });
+	// counted, nobody looked up, a challenge minted: MAIL_THROTTLED → 429 by janusErrors()
+	const pending = await auth.signInCode.prepare(email);
+	offRequest(async () => {
+		const issued = await pending.send(); // the lookup and the code, off the visitor's request
+		if (issued !== null) await mailer.send(issued.email, `Your sign-in code: ${issued.code}`); // the code only
+	});
+	// the same answer either way: a challenge for everybody, TOKEN_UNKNOWN when nobody holds the e-mail
+	setCookie(c, CODE_CHALLENGE, pending.challenge, { ...codeScope, maxAge: 600 });
 	return c.json({ next: 'code' }, 202);
 });
 
@@ -409,17 +412,20 @@ app.post('/sign-in/email/code', async (c) => {
 ```
 
 **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. `@nxgt/janus` throttles
-each address — five requests per 10 minutes, then `MAIL_THROTTLED`, which
-`janusErrors()` answers 429 with `Retry-After` (the last code sent still
-works); rate-limit the route per client yourself, since one client can ask for
-many addresses.
+same body, and a cookie either way, in the same time. `signInCode.prepare`
+(`@nxgt/janus` 0.20) counts the address and mints the challenge **without
+looking anybody up**, so it makes the same store calls for any address;
+`send()`, which looks the address up and issues the code under that
+challenge, runs after the answer. For an address nobody holds `send()`
+answers `null`, and the challenge confirms as `TOKEN_UNKNOWN`. `maxAge: 600`
+is the default ten minutes of `tokens.signInCode`. `@nxgt/janus` throttles
+each address — five requests per 10 minutes, then `MAIL_THROTTLED` from
+`prepare`, in the visitor's request, which `janusErrors()` answers 429 with
+`Retry-After` (the last code sent still works); rate-limit the route per
+client yourself, since one client can ask for many addresses. `send()` runs
+once: a second call is a `TypeError`, so a retry prepares again. With
+`signInCode.request(email)` instead, the route would wait for the lookup —
+its time would tell — and would set a random decoy challenge for `null`.
 
 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
@@ -488,6 +494,8 @@ 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.
 
+`offRequest` is the helper of [a code sent by e-mail](#a-code-sent-by-e-mail).
+
 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.
@@ -502,10 +510,12 @@ const TOKEN = /^[A-Za-z0-9_-]{43}$/; // 32 bytes, base64url: the only thing echo
 
 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
-	}
+	const pending = await auth.magicLink.prepare(email); // counted, nobody looked up: MAIL_THROTTLED → 429
+	offRequest(async () => { // offRequest: see A code sent by e-mail (#a-code-sent-by-e-mail)
+		// the lookup and the token, after the answer, so its time tells nothing; in production, a queue
+		const issued = await pending.send();
+		if (issued !== null) await mailer.send(issued.email, `${ORIGIN}/sign-in/link?token=${issued.token}`);
+	});
 	return c.body(null, 202); // the same answer either way: nothing of a link reaches the visitor
 });
 
@@ -593,6 +603,36 @@ this e-mail with `mail.magicLink(issued)`, building its button with
 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).
 
+## Accepting an invitation
+
+An invitation is the application's own proof: it issued the token, and the
+person followed it. `auth.signInProven(userId)` signs them in on that proof
+— no e-mail, no mail-throttle count, no link spent — and answers what
+`signIn` answers, so `sendSession` and the second factor work as above.
+There is no route of this package for it: the proof is yours to check, and
+the id must come from your invitation's record, **never from the request**.
+
+```ts
+app.post('/invitation/accept', csrf({ origin: ORIGIN }), async (c) => {
+	const token = String((await c.req.parseBody()).token ?? '');
+	const invitation = await invitations.spend(hash(token), new Date()); // yours: once, unexpired
+	if (invitation === null) return c.json({ code: 'INVITATION_INVALID' }, 404);
+
+	const result = await auth.signInProven(invitation.userId, { device: deviceOf(c) });
+	if (result.status === 'secondFactor') {
+		setCookie(c, CHALLENGE, result.challenge, { ...scope, expires: result.expiresAt });
+		return c.redirect('/sign-in/second-factor', 303);
+	}
+	sendSession(c, auth, result);
+	return c.redirect('/', 303);
+});
+```
+
+Not `magicLink.request` then `confirm` at once: `request` counts against
+the mail throttle per address, so five anonymous requests for the invitee's
+address would answer this route 429. See [`@nxgt/janus`'s
+sessions guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/sessions.md#signing-in-on-your-own-proof--signinproven).
+
 ## The device cookie
 
 With `janus({ devices })`, every sign-in can tell the user it came from a
@@ -771,7 +811,8 @@ cookie drops it too.
 
 ## E-mail verification and password reset
 
-Sending the e-mail is yours; the one-time token goes in a link.
+Sending the e-mail is yours; the one-time token goes in a link. `offRequest`
+is the helper of [a code sent by e-mail](#a-code-sent-by-e-mail).
 
 ```ts
 app.post('/verify-email', session(auth, { required: true }), async (c) => {
@@ -788,11 +829,12 @@ app.post('/verify-email/confirm', async (c) => {
 
 app.post('/reset-password', async (c) => {
 	const { email } = await c.req.json();
-	const issued = await auth.resetPassword.request(email);
-	if (issued !== null) {
-		await mailer.send(issued.email, `https://app.test/reset?token=${issued.token}`);
-	}
-	return c.body(null, 202); // the same answer either way: never say which e-mails exist
+	const pending = await auth.resetPassword.prepare(email); // counted, nobody looked up: MAIL_THROTTLED → 429
+	offRequest(async () => { // offRequest: see A code sent by e-mail (#a-code-sent-by-e-mail)
+		const issued = await pending.send(); // the lookup and the link, off the visitor's request
+		if (issued !== null) await mailer.send(issued.email, `https://app.test/reset?token=${issued.token}`);
+	});
+	return c.body(null, 202); // the same answer, in the same time, either way: never say which e-mails exist
 });
 
 app.post('/reset-password/confirm', async (c) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus-hono",
-	"version": "0.7.1",
+	"version": "0.7.3",
 	"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.19.0",
+		"@nxgt/janus": "^0.21.0",
 		"@types/bun": "^1.4.2",
 		"hono": "^4.13.9",
 		"zod": "^4.6.5"
 	},
 	"peerDependencies": {
-		"@nxgt/janus": "^0.19.0",
+		"@nxgt/janus": "^0.21.0",
 		"hono": "^4.13.4",
 		"typescript": "^6.0.3"
 	}