@nxgt/janus 0.15.0 → 0.16.1

package/docs/guide/events.md

@@ -45,10 +45,10 @@ The words — **user event**, **listener** — are defined in
 | `user.created` | `create`, `signUp` — once the user is inserted, even if `signUp`'s session then fails to open | for a sign-up refused (`LOGIN_TAKEN`, `USER_INVALID`, `PASSWORD_TOO_SHORT`) |
 | `user.emailVerified` | `verifyEmail.confirm`; `resetPassword.confirm` and `magicLink.confirm`, whose link proves the e-mail; `signInCode.confirm`, whose code does | for an e-mail already verified, or a refused confirm |
 | `user.passwordReset` | `resetPassword.confirm` | for `setPassword` or `changePassword` — they are not resets |
-| `user.passwordChanged` | `changePassword` and `setPassword` — a first password set on a user created without one included — once the password is written — even if spending the reset links and second-factor challenges it ends then fails | for a reset, which is `user.passwordReset` alone; for a `changePassword` refused (`CREDENTIALS_INVALID`) |
+| `user.passwordChanged` | `changePassword` and `setPassword` — a first password set on a user created without one included — once the password is written — even if spending the reset links and second-factor challenges it ends then fails; `signInCode.confirm` and `magicLink.confirm` when their first proof of the e-mail dropped a password, after `user.emailVerified` | for a reset, which is `user.passwordReset` alone; for a `changePassword` refused (`CREDENTIALS_INVALID`) |
 | `user.emailChanged` | `update`, when it changed the e-mail — added, replaced or removed. It carries `formerEmail`, the address before | for an update that leaves the e-mail alone, or changes only its case (`Ada@…` for `ada@…`): compared normalised, the same test that makes the new address unverified; for a type with no e-mail; for an update refused |
 | `user.secondFactorEnabled` | `secondFactor.activate`, once the first code made the factor active | for `enroll`, which leaves the factor waiting and asked for nowhere; for a code refused |
-| `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
+| `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor; `signInCode.confirm` and `magicLink.confirm` when their first proof of the e-mail removed one, after `user.emailVerified` and any `user.passwordChanged` — even if an outage interrupts the sign-outs | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
 | `user.recoveryCodesRegenerated` | `secondFactor.regenerateRecoveryCodes`: the codes the user held stopped working | for `activate`, whose first codes come with `user.secondFactorEnabled`; for a code refused |
 | `user.recoveryCodeUsed` | `secondFactor.recover`, once the recovery code is spent — even if opening the session then fails | for a recovery code refused. How many are left is not in the event: `secondFactor.recoveryCodesLeft(event.userId)` reads it |
 | `user.deleted` | `delete`, when it deleted the user | for a replay that finds nobody, or an id of another user type |
@@ -204,7 +204,7 @@ Where the listener runs within a flow, and what an outage does to it:
 | `verifyEmail.confirm` | after the write — the flow's last step | — |
 | `update` | after the write — the flow's last step | — |
 | `changePassword`, `setPassword` | **after** the reset links and the second-factor challenges left open are spent | fails the call; the event is sent all the same, from a `finally` |
-| `signInCode.confirm`, `magicLink.confirm` | after the write, **before** the session or the second-factor challenge is opened | fails the call; the event is already sent |
+| `signInCode.confirm`, `magicLink.confirm` | on an e-mail never verified: **after** every session is revoked and the reset links and second-factor challenges left open are spent — before the write and again after it — and **before** the new session or second-factor challenge is opened. `user.passwordChanged` follows `user.emailVerified` when a password was dropped, then `user.secondFactorDisabled` when an active second factor was removed. An e-mail already verified sends nothing | fails the call; the events are sent all the same, from a `finally`. An outage in the sign-outs before the write fails the call with nothing written and nothing sent: the next code or link proves the e-mail again |
 | `secondFactor.activate`, `secondFactor.regenerateRecoveryCodes`, `secondFactor.disable` | after the write — the flow's last step | — |
 | `secondFactor.recover` | after the recovery code is spent and the session opened — or failed to open | fails the call; the recovery code is spent and the event sent all the same, from a `finally` |
 | `resetPassword.confirm` | **after** the sessions opened with the old password are revoked, and the other reset links and the second-factor challenges left open are spent | fails the call; the events are sent all the same, from a `finally` |
@@ -316,7 +316,7 @@ see [troubleshooting](../troubleshooting.md#janus-events-must-be-a-function-that
 ## See also
 
 - [E-mail verification and password reset](email-flows.md) — the flows that send `user.emailVerified` and `user.passwordReset`
-- [The second factor](second-factor.md) — `activate` and `disable`, which send `user.secondFactorEnabled` and `user.secondFactorDisabled`; [recovery codes](second-factor.md#recovery-codes), which send `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
+- [The second factor](second-factor.md) — `activate` and `disable`, which send `user.secondFactorEnabled` and `user.secondFactorDisabled` — sent too by the first proof of an e-mail by a [code](sign-in-code.md) or a [link](magic-link.md#an-account-someone-else-registered); [recovery codes](second-factor.md#recovery-codes), which send `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
 - [Users](users.md) — `create`, `signUp`, `update`, `delete`
 - [Passwords](passwords.md) — `changePassword` and `setPassword`, which send `user.passwordChanged`
 - [Troubleshooting](../troubleshooting.md) — `JANUS_EVENT_FAILED`

package/docs/guide/magic-link.md

@@ -153,7 +153,7 @@ export function linkPage(request: Request): Response {
 		{
 			headers: {
 				'Content-Type': 'text/html; charset=utf-8',
-				'Referrer-Policy': 'no-referrer', // the URL holds the token: send it nowhere
+				'Referrer-Policy': 'strict-origin', // the origin only: the token's URL reaches nobody
 				'Cache-Control': 'no-store',
 			},
 		},
@@ -167,8 +167,14 @@ export function linkPage(request: Request): Response {
   scripts submits the form too; one that does not click buttons does not.
   Auto-submitting saves the user a click, at the price of every link a
   script-running scanner opens.
-- **`Referrer-Policy: no-referrer`** keeps the URL, and the token in it, out
-  of the `Referer` of anything the page loads.
+- **`Referrer-Policy: strict-origin`** keeps the URL, and the token in it,
+  out of the `Referer` of anything the page loads: a `Referer` holds the
+  origin only — `https://app.example/` — never the path and its query, and
+  none at all from HTTPS to HTTP. Not `no-referrer`: with it the browser
+  posts the form with `Origin: null`, which a check on `Origin` alone — as
+  `confirmLink` [below](#as-routes) — refuses every time, and one that tries
+  `Sec-Fetch-Site` first refuses whenever the browser sends none: on plain
+  HTTP off `localhost`, or in an older browser.
 - **Refuse a `POST` from another site.** The token says nothing of the
   browser that asked for it: a page anywhere that posts a token of the
   attacker's own account to your route signs its visitor in as the attacker,
@@ -218,27 +224,52 @@ spent.
 ### An account someone else registered
 
 The proof can land on an account its owner did not create. `signUp` does
-not wait for the e-mail to be proved, and `signIn` does not ask whether it
-was, so anyone can register `ada@example.com` with a password of theirs. When
-Ada later signs in by link, `confirm` marks the e-mail verified and opens her
-session — **and the other password, and the session `signUp` opened, still
-work**. A [password reset](email-flows.md) would have replaced both; a link
-or a [code](sign-in-code.md) touches neither.
-
-Where a password signs in before the e-mail is verified, **require
-`verifyEmail` before `signIn`**, and the question does not arise. Otherwise
-treat the first proof as a takeover of the address: `confirm` sends
-[`user.emailVerified`](events.md) exactly when the e-mail was not verified
-before, and awaits your listener before the session opens. Sign every
-session out there — `signOutEverywhere(user)`; the one `confirm` opens comes
-after — and have the user set a password of their own.
+not wait for the e-mail to be proved, so anyone can register
+`ada@example.com` with a password of theirs — and enrol a second factor on
+their own phone. When Ada later signs in by link, `confirm` proves an e-mail
+never verified, and **drops the password and the second factor, and signs
+out every session** before it opens hers — as a
+[password reset](email-flows.md) does. The same holds for a
+[code](sign-in-code.md).
+
+- In the write that proves the e-mail, the password is removed
+  (`hasPassword` turns `false`), and so is the second factor, active or
+  still waiting for its first code, with its recovery codes
+  (`hasSecondFactor` turns `false`): Ada's sign-in asks for no factor she
+  never set. Every session of the user is revoked, and
+  the reset links and second-factor challenges still waiting are spent,
+  before that write and again after it: an outage before it leaves the
+  e-mail unproved, so the next link or code runs all of it again.
+- [`user.emailVerified`](events.md) is sent, then `user.passwordChanged`
+  when a password was dropped, then `user.secondFactorDisabled` when an
+  active factor was — even if an outage interrupts the sign-outs.
+- **An e-mail already verified changes nothing**: the password, the second
+  factor and the sessions stay, and nothing is written or sent.
+- An e-mail changed by `update` is unverified again: its first proof drops
+  the password and the second factor too.
+- **A user who enrolled a factor before proving their own e-mail loses it
+  the same way**: the library cannot tell them from a squatter. Send
+  `verifyEmail` before offering `secondFactor.enroll`, and no owner's
+  factor is ever dropped by a sign-in.
+
+A user who signed up with a password and signs in by link before verifying
+has **no password afterwards**: `signIn` answers `CREDENTIALS_INVALID` with
+`reason: 'noPassword'`. Offer to set one:
+
+```ts
+const signedIn = await auth.magicLink.confirm(token);
+if (signedIn.status === 'signedIn' && !signedIn.user.hasPassword) {
+	// a page of yours that calls auth.setPassword(signedIn.user, password)
+}
+```
 
 ### A second factor is still asked for
 
 The link proves the e-mail, not the second factor. With
-`janus({ secondFactor })`, a user whose factor is active gets **no session
-from the link**: `confirm` answers a challenge, exactly as `signIn` does,
-and [`secondFactor.confirm`](second-factor.md#confirming-the-code-at-sign-in)
+`janus({ secondFactor })`, a user whose e-mail was already verified and
+whose factor is active gets **no session from the link**: `confirm` answers
+a challenge, exactly as `signIn` does, and
+[`secondFactor.confirm`](second-factor.md#confirming-the-code-at-sign-in)
 redeems it with their app's code.
 
 ```ts

package/docs/guide/second-factor.md

@@ -127,7 +127,7 @@ Without `secondFactor`, `signIn` answers a session as before, typed
 
 | State | `hasSecondFactor` | `signIn` answers | Recovery codes | Reached by |
 | --- | --- | --- | --- | --- |
-| none | `false` | a session | none | a new user; `disable`, which removes the codes with the factor |
+| none | `false` | a session | none | a new user; `disable`, which removes the codes with the factor; the [first proof of the e-mail](#a-first-sign-in-by-e-mail-removes-it-too) by a sign-in code or link |
 | **enrolled** — waiting for a first code | `false` | a session | none | `enroll` |
 | **active** | `true` | a challenge | ten from `activate`; one fewer per `recover`; ten new from `regenerateRecoveryCodes` | `activate`, with a code that matches |
 
@@ -559,6 +559,31 @@ const auth = janus({
 });
 ```
 
+### A first sign-in by e-mail removes it too
+
+When [`signInCode.confirm`](sign-in-code.md) or
+[`magicLink.confirm`](magic-link.md#an-account-someone-else-registered)
+proves an e-mail **never verified**, the write that proves it also removes
+the factor, active or enrolled, with its recovery codes — and drops the
+password, and signs out every session. Whoever registered the address never
+proved they held its inbox, so a factor they enrolled is not theirs to keep:
+the inbox's owner signs in with no challenge.
+
+```ts
+const signedIn = await auth.magicLink.confirm(token); // an e-mail never verified
+if (signedIn.status === 'signedIn' && !signedIn.user.hasSecondFactor) {
+	// offer setPassword, then enroll again
+}
+```
+
+`user.secondFactorDisabled` is sent when the factor removed was active, after
+`user.emailVerified` and any `user.passwordChanged`, so the listener above
+tells the inbox's owner. An e-mail already verified keeps the factor, and
+`confirm` answers a challenge as `signIn` does. **Send `verifyEmail` before
+offering `enroll`**: a user who enrolls before proving their own e-mail loses
+the factor on their first sign-in by code or link, since the library cannot
+tell them from someone who registered their address.
+
 ### Asking before `enroll` and `disable` is your policy
 
 `janus` checks nothing before `enroll` or `disable`: it does not know who is

package/docs/guide/sessions.md

@@ -182,7 +182,10 @@ if (current !== null) {
 ```
 
 `changePassword` leaves other sessions open; call this after it when that is
-your policy. `resetPassword.confirm` signs out everywhere on its own.
+your policy. `resetPassword.confirm` signs out everywhere on its own, and so
+do `signInCode.confirm` and `magicLink.confirm` when they prove an e-mail
+never verified, before opening their own session
+([why](magic-link.md#an-account-someone-else-registered)).
 
 ## `collectExpired`
 

package/docs/guide/sign-in-code.md

@@ -274,16 +274,21 @@ succeeds, and their `version` moves: the code proves the address as a
 verification link would, and a [`user.emailVerified` event](events.md) is
 sent. A user already verified is not written, and nothing is sent.
 
-**The proof can land on an account someone else registered** — with a
-password of theirs, which keeps working, as does the session `signUp`
-opened. Where a password signs in before the e-mail is verified, see
+**An e-mail proved for the first time drops the password and the second
+factor, and signs out every session** before the new one opens: the proof
+can land on an account someone else registered, with a password — and maybe
+a second factor — of theirs. `user.passwordChanged` follows
+`user.emailVerified` when a password was dropped, then
+`user.secondFactorDisabled` when an active factor was; an e-mail already
+verified changes nothing. The details are in
 [the sign-in link guide](magic-link.md#an-account-someone-else-registered):
 the same holds for a code.
 
 ### A second factor is still asked for
 
 The code proves the e-mail, not the second factor. With `janus({ secondFactor })`,
-a user whose factor is active gets **no session from the code**: `confirm`
+a user whose e-mail was already verified and whose factor is active gets
+**no session from the code**: `confirm`
 answers a challenge, exactly as `signIn` does with a password, and
 [`secondFactor.confirm`](second-factor.md#confirming-the-code-at-sign-in)
 redeems it with the code of their authenticator app — or

package/docs/guide/step-up.md

@@ -30,6 +30,12 @@ const session = await auth.stepUp.confirm(request, issued.challenge, code);
 session.authenticatedAt; // now: the action goes through for the next ten minutes
 ```
 
+`sendMail` stands for your own sending. With
+[`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail) 0.8,
+`mail.stepUp(issued, { name, locale })` sends it — "Your confirmation code",
+in English or French — see [Sending the code with
+`@nxgt/janus-mail`](#sending-the-code-with-nxgtjanus-mail).
+
 A step-up is two requests, as a sign-in by code is: one issues the code, the
 other takes it and stamps the session. It **opens no session** and hands out
 no new token: the session the request presents is the one confirmed, which
@@ -110,6 +116,31 @@ if (issued.via === 'email') {
 return Response.json({ challenge: issued.challenge, via: issued.via });
 ```
 
+### Sending the code with `@nxgt/janus-mail`
+
+`@nxgt/janus-mail`'s `mail.stepUp` takes what `request` answered, once
+narrowed to `via: 'email'`, and sends it to `issued.email`: a greeting by
+name, the code, how long it lasts — "This code expires in 10 minutes." —
+and a **Secure my account** button to its `links.secureAccount()`, for a
+user who asked for nothing. It reads the code, the address and `expiresAt`,
+never the challenge:
+
+```ts
+import { janusMail } from '@nxgt/janus-mail';
+
+const mail = janusMail({ mailer, from: 'noreply@acme.example', brand: 'Acme', links });
+
+const issued = await auth.stepUp.request(current.user);
+if (issued.via === 'email') {
+	await mail.stepUp(issued, { name: current.user.name, locale: current.user.locale });
+}
+return Response.json({ challenge: issued.challenge, via: issued.via });
+```
+
+An un-narrowed answer is a compile error there, and a `via: 'secondFactor'`
+passed from JavaScript a `TypeError`: an app's step-up has nothing to send.
+See its [sending guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-mail/docs/guide/sending.md#stepupissued-to-options).
+
 **One step-up is live per user**: a request spends every step-up issued
 before it. The challenge lapses after ten minutes by default —
 `janus({ tokens: { stepUp: '5m' } })` changes it.
@@ -176,3 +207,5 @@ calls are traced like every other flow.
 - [Signing in with an e-mailed code](sign-in-code.md) — the same six digits,
   to sign in.
 - [Errors](errors.md) — every code and its status.
+- [`@nxgt/janus-mail`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-mail/docs/guide/sending.md#stepupissued-to-options)
+  — `mail.stepUp`, the step-up's e-mail.

package/docs/guide/users.md

@@ -222,11 +222,14 @@ await auth.delete(renamed);                        // true
 The patch is spread over the stored fields and the result is checked against
 the schema, so a patch can never leave a user the schema would refuse.
 Changing the e-mail sets `emailVerified` back to `false`, and moves the login
-with it when the e-mail is the login. It also sends a
-[`user.emailChanged` event](events.md#telling-the-user-their-password-or-e-mail-changed)
-carrying `formerEmail`, the address before — so the notice goes to the inbox
-the account just left. A change of case only (`Ada@…` for `ada@…`) is no
-change, and sends nothing.
+with it when the e-mail is the login — so the next sign-in by code or link
+proves it anew, and [drops the password and the second factor, and signs out
+every session](magic-link.md#an-account-someone-else-registered). It also
+sends a [`user.emailChanged`
+event](events.md#telling-the-user-their-password-or-e-mail-changed) carrying
+`formerEmail`, the address before — so the notice goes to the inbox the
+account just left. A change of case only (`Ada@…` for `ada@…`) is no change,
+and sends nothing.
 
 ### `ifVersion`
 

package/docs/guide/vocabulary.md

@@ -43,7 +43,7 @@ either finds this row.
 | **credential** | What a caller presents to prove who they are: a login and a password at sign-in (`CredentialError`, `CREDENTIALS_INVALID`), or a token on a request — always written *session credential* | |
 | **password policy** | The rules a new password must meet: `minLength`, `normalize` | the model |
 | **session** | A signed-in period, carried by a **session token** | |
-| **lapsed**, **revoked**, **renewed** | A session past its `expiresAt`; one ended by a sign-out or a password reset; one whose `expiresAt` moved in passing (`renewAfter`) | "expired" — kept for `TOKEN_EXPIRED`, a one-time token |
+| **lapsed**, **revoked**, **renewed** | A session past its `expiresAt`; one ended by a sign-out, a password reset, or the first proof of an e-mail by a code or a link; one whose `expiresAt` moved in passing (`renewAfter`) | "expired" — kept for `TOKEN_EXPIRED`, a one-time token |
 | **anonymous** | A request that presents no session credential, or one that authenticates nobody: `authenticate` answers `null` | "unauthenticated", "guest", "logged out" |
 | **bearer client** | A client that sends its session token as `Authorization: Bearer` rather than in a cookie | |
 | **one-time token** | A single-use token sent by e-mail in a link, for verification, a password reset or a sign-in | "code": a code is typed, a token is followed in a link |

package/docs/roadmap.md

@@ -70,6 +70,14 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **The first sign-in by link or code ends a squatter's password and second
+  factor, v0.16.0** — when `signInCode.confirm` or `magicLink.confirm`
+  proves an e-mail never verified, the password and the second factor with
+  its recovery codes are dropped and every session signed out before the
+  new one opens: whoever registered the address without its inbox keeps
+  nothing, and the owner is asked for no factor they never set.
+  `user.passwordChanged` and `user.secondFactorDisabled` report what was
+  dropped. An e-mail already verified changes nothing.
 - **Sign in with an e-mailed link (magic link), v0.15.0** —
   `auth.magicLink.request(email)` and `magicLink.confirm(token)` on every
   user type with an e-mail, with or without a password: the sign-in code
@@ -134,13 +142,6 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   `SecondFactorRecord.recoveryCodes`,
   stored by the users stores of `@nxgt/janus-drizzle` and
   `@nxgt/janus-mongo`, with conformance cases.
-- **The second factor in the user events, v0.9.0** —
-  `user.secondFactorEnabled`, once `secondFactor.activate` made a factor
-  active, and `user.secondFactorDisabled`, once `secondFactor.disable`
-  removed an active one: a listener can tell the user, as
-  `@nxgt/janus-mail`'s `twoFactorEnabled` and `twoFactorDisabled` notices
-  do, whoever made the change. `enroll`, a factor still waiting, and a
-  `disable` that found none send nothing.
 - **Sending the e-mails, `@nxgt/janus-mail` v0.1.0** — a package of its
   own, built on the `@nxgt/mail` toolkit: `janusMail({ mailer, from, brand,
   links })` takes what each flow answers —

package/docs/troubleshooting.md

@@ -93,6 +93,7 @@ How the messages are shaped:
 
 **Sign-in links**
 - [A sign-in link answers `TOKEN_SPENT` on the user's first click](#a-sign-in-link-answers-token_spent-on-the-users-first-click)
+- [The link's own button answers `403`](#the-links-own-button-answers-403)
 - [The link signed in another device than the one that asked](#the-link-signed-in-another-device-than-the-one-that-asked)
 - [`magicLink.request` answers `null` for a user who exists](#magiclinkrequest-answers-null-for-a-user-who-exists)
 - [`TS2339: Property 'magicLink' does not exist on type 'TypeApi<…>'.`](#ts2339-property-magiclink-does-not-exist-on-type-typeapi)
@@ -564,8 +565,8 @@ if (error instanceof UserInvalidError) {
 Also `changePassword: the current password does not match`.
 
 **When:** `signIn`, `changePassword`.
-**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. Also a sign-in that verified a password written over while it ran (`reason: 'wrongPassword'`): its session is revoked, or its challenge spent, before the refusal. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter; a login past its attempts has its own message, below. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
-**Fix:** answer 401 with the same body whatever the reason:
+**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. Also a sign-in that verified a password written over while it ran (`reason: 'wrongPassword'`): its session is revoked, or its challenge spent, before the refusal. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter; a login past its attempts has its own message, below. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one. A user who signed up with a password and then signed in by `signInCode` or `magicLink` before verifying the e-mail has no password any more (`noPassword`): that first proof drops it, and the second factor, and signs out every session, so an address registered by someone else keeps nothing of theirs — [the sign-in link guide](guide/magic-link.md#an-account-someone-else-registered) has why.
+**Fix:** answer 401 with the same body whatever the reason — and, for a user who signed in by code or link before verifying, offer `setPassword` after that sign-in, or send `verifyEmail` at sign-up:
 
 ```ts
 // Never: { reason: error.reason } — `unknownLogin` tells an attacker which users exist.
@@ -986,7 +987,7 @@ const { recoveryCodes } = await auth.secondFactor.regenerateRecoveryCodes(curren
 
 `SecondFactorError`. Also `secondFactor.confirm: the user no longer has a second factor — sign in again`, and the same from `secondFactor.recover`.
 
-**When:** `activate` before `enroll`, or after `disable`. On `confirm` or `recover`: the factor was disabled after `signIn` asked for a code.
+**When:** `activate` before `enroll`, or after `disable` — or after a sign-in by `signInCode` or `magicLink` that proved the e-mail for the first time, which removes a factor enrolled before it. On `confirm` or `recover`: the factor was disabled after `signIn` asked for a code, or removed by such a first proof when an outage kept its challenges from being spent — the proof spends them otherwise, and `confirm` answers `TOKEN_SPENT`.
 **Why:** `activate` checks a code against the secret `enroll` wrote, and there is none. On `confirm`, the factor the challenge asked for is gone, so the challenge is spent.
 **Fix:** `enroll`, show the `uri` as a QR code, then `activate` with a code from the app. After `confirm`'s refusal, sign in again: `signIn` answers a session directly for a user without a factor.
 
@@ -1231,6 +1232,30 @@ const signedIn = await auth.magicLink.confirm(token);
 The [guide](guide/magic-link.md#confirming-from-a-post-never-from-the-links-get)
 has the page, with the headers it needs.
 
+### The link's own button answers `403`
+
+**When:** the page the e-mailed link opens posts its token, and the route
+that checks the `Origin` before `magicLink.confirm` refuses it — for every
+user, or only on plain HTTP off `localhost` and in older browsers.
+**Why:** the page is sent with `Referrer-Policy: no-referrer`, and under it
+the browser posts the form with `Origin: null`. A check on `Origin` alone
+refuses every such `POST`; one that tries `Sec-Fetch-Site: same-origin`
+first refuses it wherever the browser sends no `Sec-Fetch-Site`. A
+mismatched `ORIGIN` — `http` for `https`, a port, a trailing `/` — does the
+same.
+**Fix:** send the page with `Referrer-Policy: strict-origin`, and set
+`ORIGIN` to the scheme, host and port the address bar shows. A `Referer`
+then holds the origin only, never the path and its token, and the form
+carries its real `Origin`:
+
+```ts
+new Response(html, { headers: { 'Referrer-Policy': 'strict-origin', 'Cache-Control': 'no-store' } }); // the GET page
+if (request.headers.get('Origin') !== ORIGIN) return new Response(null, { status: 403 }); // on the POST
+```
+
+The [guide](guide/magic-link.md#confirming-from-a-post-never-from-the-links-get)
+has the page and the route.
+
 ### The link signed in another device than the one that asked
 
 **When:** a user asks for a link on a laptop and opens the e-mail on their
@@ -1435,7 +1460,7 @@ process.on('warning', (warning) => {
 
 **Fix:** for the last two, reconcile against the users themselves and treat events as the fast path, not the record: page through `auth.list()` and compare with the receiver's copy — a user it lacks is a missed `user.created`, a user the receiver has that `auth.find` answers `null` for is a missed `user.deleted`, a user whose `emailVerified` differs is a missed `user.emailVerified`, and a user whose `hasSecondFactor` differs is a missed `user.secondFactorEnabled` or `user.secondFactorDisabled`.
 
-A store outage **after** the write does not lose the event. `create`, `signUp` and `signInCode.confirm` send it before the steps that follow; `delete` and `resetPassword.confirm` run theirs — removing the sessions, tokens and tuples; revoking the sessions — in a `try`, and send it from its `finally`, whether they succeeded or not.
+A store outage **after** the write does not lose the event. `create` and `signUp` send it before the steps that follow; `delete`, `resetPassword.confirm`, and `signInCode.confirm` and `magicLink.confirm` on an e-mail never verified run theirs — removing the sessions, tokens and tuples; revoking the sessions — in a `try`, and send it from its `finally`, whether they succeeded or not. `signInCode.confirm` and `magicLink.confirm` also revoke the sessions **before** the write: an outage there leaves nothing written and nothing sent, and the next code or link proves the e-mail again.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus",
-	"version": "0.15.0",
+	"version": "0.16.1",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",