@uniweb/api 0.8.0 → 0.9.0

package/README.md

@@ -63,13 +63,49 @@ record, read that record: `entity.can_edit` is the backend's own answer.
 **Signing up** — `useSignUp().signUp({ username, email, password })` answers
 `{ status: 'verification_required', email }`, the same answer for an address already in
 use. The account cannot sign in until the address is confirmed from the email the
-backend sends; until then `signIn` fails with `error.kind === 'unverified'`. A username
-already taken fails with status `409`.
+backend sends — its link lands on your site (below); until then `signIn` fails with
+`error.kind === 'unverified'`. A username already taken fails with status `409`.
 
-**Password reset** — `usePasswordReset()`: `request({ email })`, then
-`confirm({ token, new_password })` with the token the viewer was sent (and `code` when a
-second factor is enrolled). **Second factor** — when `signIn` answers
-`{ ok: false, challenge: { kind: 'totp' } }`, finish with `completeChallenge(code)`.
+**Password reset** — `usePasswordReset().request({ email })` asks for one; the email's
+link lands on your site, where `useMailedLink` finishes it. **Second factor** — when
+`signIn` answers `{ ok: false, challenge: { kind: 'totp' } }`, finish with
+`completeChallenge(code)`.
+
+**The links the backend mails** — a sign-up's confirmation, a password reset, an
+invitation sent to an address with no account here: each is a link to your site's root,
+a token in the query (`?verify=`, `?reset=`, `?offer=`), and the page it lands on
+finishes the step. `useMailedLink()` says which step, and finishes it:
+
+```jsx
+import { useMailedLink } from '@uniweb/api'
+
+// Wherever the site's root renders it — a header or a layout is on every page.
+function FromYourEmail() {
+  const { step, status, result, error, confirm } = useMailedLink()
+  if (step === 'verify' && status === 'done') return <p>Your address is confirmed. Sign in.</p>
+  if (step === 'reset' && status !== 'done') {
+    return <NewPassword onSave={(password) => confirm({ new_password: password })} error={error} />
+  }
+  if (step === 'offer' && status === 'idle') return <p>Sign in, or create an account, to take up your invitation.</p>
+  if (step === 'offer' && status === 'done' && result.invitations + result.grants > 0) return <p>Your invitation is in.</p>
+  if (status === 'error' || status === 'done') return <p>This link can no longer be used.</p>
+  return null
+}
+```
+
+- `verify` finishes by itself. `reset` waits for `confirm({ new_password, code? })` —
+  `code` when the account has a second factor — and supplies the token; a password the
+  backend's rule refuses is `error.extensions.reason === 'password_too_short'` (with
+  `min_length`), and the same link works again. `offer` waits until someone is signed
+  in — whatever their account's own address — and then claims by itself.
+- An offer answers counts, `{ invitations, grants }` — invitations now waiting for this
+  account to accept, and entities now shared with it — never names. Both `0` means it
+  bound nothing. ⛔ A token unknown, revoked or already used is ONE answer,
+  `error.kind === 'absent'`: say one sentence, naming no cause.
+- Once the backend has judged the token, it leaves the address bar, so a reload asks
+  nothing again; a link the backend could not be reached about (`kind: 'unavailable'`)
+  stays, and works on a reload. However many components use the hook, the link is
+  finished once. `dismiss()` forgets it unfinished.
 
 **The Admin link** — some of the site's members administer its backend, the operator
 among them. For them, `adminHref` is the address that takes them to the backend's
@@ -235,22 +271,27 @@ Everyone signed in — the operator too, as on a real site — reads and writes
 entities and nothing of anyone else's (`memberFloor: 'read'` in the seed models a
 service set up to let members read each other's — or per Model,
 `memberFloor: { '@acme/course': 'read' }`, so the operator's content is shared while
-each member's own records stay private). A new sign-up must be
-verified: the link is in `mock.outbox` (the standalone server prints it). The
-operator's Admin link answers too, landing on a page of the mock's own — the backend's
+each member's own records stay private). The mail the backend would send — a sign-up's
+confirmation, a password reset — is printed where the mock runs, in the terminal of
+`uniweb dev`, its link on your site's root as the backend's is, so following it is
+trying your page; the messages are in `mock.outbox` too. To try an invitation, seed one:
+`offers: [{ email: 'guest@example.test', invitations: 1 }]` is mailed when the mock starts.
+The operator's Admin link answers too, landing on a page of the mock's own — the backend's
 administration is not part of it. State is in memory: restart to reset.
 
-There is also a standalone server, for a frontend that is not a Uniweb site:
+There is also a standalone server, for a frontend that is not a Uniweb site — `--site`
+names that frontend's origin, where the mail's links land:
 
 ```bash
-npx uniweb-api-mock --port 8787
+npx uniweb-api-mock --port 8787 --site http://localhost:3000
 ```
 
 ## Outside React
 
 `@uniweb/api/client` carries the same operations as plain functions and imports no
 React: `probeSession`, `signIn`, `listEntities`, `readEntity`, `writeItems`,
-`createEntity`, `deleteEntity`, `adminHref`.
+`createEntity`, `deleteEntity`, `adminHref`, and for the links the backend mails,
+`mailedLink`, `verifyEmail`, `claimOffer` and `forgetMailedLink`.
 
 ## License
 

package/bin/uniweb-api-mock.js

@@ -6,10 +6,12 @@
  * then same-origin with the site, which is what a real deployment looks like. Use
  * this when the frontend is not a Uniweb site, or when proxying to it.
  *
- *   uniweb-api-mock [--port 8787] [--prefix /_api] [--seed ./seed.js]
+ *   uniweb-api-mock [--port 8787] [--prefix /_api] [--seed ./seed.js] [--site http://localhost:3000]
  *
- * The site's `api` address for it is the URL it prints. Mail the backend would
- * send — a sign-up's verification, a password reset — is printed here instead.
+ * The site's `backend` address for it is the URL it prints. Mail the backend would
+ * send — a sign-up's confirmation, a password reset, an invitation — is printed here
+ * instead, its link on the site's root as the backend mails it: on `--site`, the
+ * frontend's origin, or this server's when none is given.
  */
 import { createMockBackend } from '../src/mock/index.js'
 import { serve } from '../src/mock/node.js'
@@ -23,23 +25,10 @@ const flag = (name, fallback) => {
 const seedPath = flag('seed', null)
 const seed = seedPath ? (await import(new URL(seedPath, `file://${process.cwd()}/`).href)).default : undefined
 
-const mock = createMockBackend({ ...(seed ? { seed } : {}) })
+// The mock prints each message as it is sent (`printMail`), its link on the site's origin.
+const mock = createMockBackend({ ...(seed ? { seed } : {}), siteOrigin: flag('site', null) })
 const prefix = flag('prefix', '')
-
-// Print each message the moment it is "sent", with what finishes it.
-let printed = 0
-const serving = {
-  fetch: async (request) => {
-    const response = await mock.fetch(request)
-    for (const message of mock.outbox.slice(printed)) {
-      console.log(`  ✉ ${message.subject} → ${message.to}`)
-      console.log(message.verify ? `    verify: GET ${prefix}${message.verify}` : `    token: ${message.token}`)
-    }
-    printed = mock.outbox.length
-    return response
-  },
-}
-const server = await serve(serving, { port: Number(flag('port', 8787)), prefix })
+const server = await serve(mock, { port: Number(flag('port', 8787)), prefix })
 
 console.log(`uniweb-api-mock listening on ${server.url}`)
 console.log(`  accounts: ${mock.store.accounts.map((a) => `${a.username}${a.operator ? ' (operator)' : ''}`).join(', ')}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The client for a Uniweb site's own backend — session, records, entities — imported by a foundation the way it imports @uniweb/kit.",
   "type": "module",
   "exports": {

package/src/client.js

@@ -17,6 +17,7 @@ import { ApiError } from './errors.js'
 import { composeUrl, isCrossOrigin, readBody, UNSAFE } from './http.js'
 import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, PAGE, TOTP, VIEWER } from './wire.js'
 import { Ledger } from './ledger.js'
+import { verifyEmailWith, claimOfferWith } from './mailed-links.js'
 
 /**
  * The site service this package reads its base from — the only name it owns.
@@ -450,6 +451,31 @@ export class ApiClient {
     return this.request('POST', AUTH.resetConfirm, { body: fields, onUnauthorized: 'ignore' })
   }
 
+  /**
+   * Confirm an address with the token of the link the backend mailed for it — `?verify=`
+   * on the site's root (`mailedLink`). Starts no session: once confirmed, the member
+   * signs in. A link used, expired or never valid throws `kind: 'invalid'`.
+   *
+   * @param {string} token
+   * @returns {Promise<{ verified: true }>}
+   */
+  verifyEmail(token) {
+    return verifyEmailWith(this, token)
+  }
+
+  /**
+   * Take up an invitation sent to an address with no account here — with the token of
+   * its mailed link, `?offer=` — for the account signed in, whatever its own address.
+   * Answers counts: `{ invitations, grants }`. A token unknown, revoked or already
+   * claimed throws `kind: 'absent'`, one answer by design; nobody signed in, `auth`.
+   *
+   * @param {string} token
+   * @returns {Promise<{ invitations: number, grants: number }>}
+   */
+  claimOffer(token) {
+    return claimOfferWith(this, token)
+  }
+
   // ── The cache ─────────────────────────────────────────────────────────────
 
   /**
@@ -967,6 +993,10 @@ export const signUp = (fields) => required().signUp(fields)
 export const requestPasswordReset = (fields) => required().requestPasswordReset(fields)
 /** @see ApiClient#confirmPasswordReset */
 export const confirmPasswordReset = (fields) => required().confirmPasswordReset(fields)
+/** @see ApiClient#verifyEmail — on any instance, an older copy's too */
+export const verifyEmail = (token) => verifyEmailWith(required(), token)
+/** @see ApiClient#claimOffer — on any instance, an older copy's too */
+export const claimOffer = (token) => claimOfferWith(required(), token)
 /** @see ApiClient#readEntity */
 export const readEntity = (args) => required().readEntity(args)
 /** @see ApiClient#listEntities */
@@ -980,5 +1010,6 @@ export const deleteEntity = (args) => required().deleteEntity(args)
 /** The Admin link for the current viewer, or `null` — never throws; see `adminHrefOf`. */
 export const adminHref = () => adminHrefOf(getClient())
 
+export { mailedLink, forgetMailedLink } from './mailed-links.js'
 export { ApiError, kindOf } from './errors.js'
 export { Ledger } from './ledger.js'

package/src/hooks/useMailedLink.js

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+import { ApiError } from '../errors.js'
+import { LINK } from '../wire.js'
+import { mailedLink, forgetMailedLink, finishMailedLink, spends } from '../mailed-links.js'
+
+const IDLE = Object.freeze({ status: 'idle', result: null, error: null })
+const noSubscribe = () => () => {}
+const noSnapshot = () => null
+
+/**
+ * The step a link the site's backend mailed came to finish — on the page it lands on.
+ *
+ * A site's backend mails its members links to the site's root, a token in the query:
+ * `?verify=` to confirm a new account's address, `?reset=` to choose a new password,
+ * `?offer=` to take up an invitation sent to an address with no account here. Draw the
+ * member area from `step` and `status`:
+ *
+ * ```jsx
+ * const link = useMailedLink()
+ * // link.step: null | 'verify' | 'reset' | 'offer'
+ * // link.status: 'idle' | 'working' | 'done' | 'error'
+ * if (link.step === 'verify' && link.status === 'done') return <p>Your address is confirmed. Sign in.</p>
+ * if (link.step === 'reset' && link.status !== 'done') return <NewPassword onSubmit={(p) => link.confirm({ new_password: p })} />
+ * if (link.step === 'offer' && link.status === 'done') return <p>{link.result.invitations} invitation(s) waiting for you.</p>
+ * ```
+ *
+ * - **`verify`** finishes by itself: `working`, then `done` (`result: { verified: true }`),
+ *   or `error` — `kind: 'invalid'` for a link used, expired or never valid.
+ * - **`reset`** waits for the new password: `confirm({ new_password, code? })` — `code`
+ *   when the account has a second factor — and the token is supplied. `done` ends every
+ *   other session of the account, so the session is asked again. A password the rule
+ *   refuses is `error`, `kind: 'invalid'` with `error.extensions.reason ===
+ *   'password_too_short'` and `min_length`, and the same link works again.
+ * - **`offer`** waits for a sign-in — `idle` until someone is signed in, so offer the
+ *   sign-in and sign-up — then claims by itself: `done` with `result: { invitations,
+ *   grants }`, COUNTS — invitations waiting for this account to accept, entities now
+ *   shared with it — or `error`, `kind: 'absent'` for a token unknown, revoked or
+ *   already claimed. ⛔ One sentence for that, naming no cause: the backend keeps the
+ *   three indistinguishable on purpose.
+ *
+ * Once the backend has judged the token, its parameter leaves the address bar, so a
+ * reload asks nothing again. `dismiss()` forgets the link without finishing it. On a
+ * site with no backend, `step` is always null.
+ *
+ * ⛔ **Keep the token on the URL, nowhere else.** A sign-up switches what the page shows
+ * without navigating, so an offer's token is still there when the new member signs in.
+ * A member who signs up under another address confirms it from a link of its own; the
+ * offer then waits in the email it came in — a token is a credential, and this package
+ * puts it in no storage.
+ *
+ * ⭐ **One request per link, however many components use this.** The first finishes it,
+ * and the others are given the same answer.
+ *
+ * @returns {{
+ *   step: 'verify' | 'reset' | 'offer' | null,
+ *   status: 'idle' | 'working' | 'done' | 'error',
+ *   result: object | null,
+ *   error: Error | null,
+ *   confirm: (fields: { new_password: string, code?: string }) => Promise<object>,
+ *   dismiss: () => void,
+ * }}
+ */
+export function useMailedLink() {
+  const client = getClient()
+  const session = useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+  const [link, setLink] = useState(null)
+  const [state, setState] = useState(IDLE)
+
+  const live = useRef(true)
+  useEffect(() => {
+    live.current = true
+    return () => {
+      live.current = false
+    }
+  }, [])
+
+  // Read once mounted: the URL is the browser's, and the first render stays the server's.
+  useEffect(() => {
+    if (client?.enabled) setLink(mailedLink())
+  }, [client])
+
+  // An offer is claimed for whoever is signed in — and again, for another account.
+  const signedIn = session?.status === 'authenticated' ? (session.viewer?.uuid ?? 'signed-in') : null
+  const claimant = link?.step === LINK.offer ? signedIn : null
+  const finishes = !!link && (link.step === LINK.verify || claimant !== null)
+
+  useEffect(() => {
+    if (!finishes) return
+    let current = true
+    setState({ status: 'working', result: null, error: null })
+    finishMailedLink(client, link).then(
+      (result) => {
+        forgetMailedLink(link)
+        if (current) setState({ status: 'done', result, error: null })
+      },
+      (error) => {
+        if (spends(error)) forgetMailedLink(link)
+        if (current) setState({ status: 'error', result: null, error })
+      },
+    )
+    return () => {
+      current = false
+    }
+  }, [client, link, finishes, claimant])
+
+  const confirm = useCallback(
+    async (fields = {}) => {
+      if (!client) throw ApiError.disabled()
+      if (link?.step !== LINK.reset) {
+        throw ApiError.invalid('No Reset Link', 'confirm finishes a mailed reset link, and this page has none')
+      }
+      setState({ status: 'working', result: null, error: null })
+      try {
+        const result = await client.confirmPasswordReset({ ...fields, token: link.token })
+        forgetMailedLink(link)
+        if (live.current) setState({ status: 'done', result, error: null })
+        // Every other session of the account has ended — this page's may be one of them.
+        client.refresh()
+        return result
+      } catch (error) {
+        if (live.current) setState({ status: 'error', result: null, error })
+        throw error
+      }
+    },
+    [client, link],
+  )
+
+  const dismiss = useCallback(() => {
+    forgetMailedLink(link)
+    setLink(null)
+    setState(IDLE)
+  }, [link])
+
+  return {
+    step: link?.step ?? null,
+    status: state.status,
+    result: state.result,
+    error: state.error,
+    confirm,
+    dismiss,
+  }
+}
+
+export default useMailedLink

package/src/index.js

@@ -21,6 +21,10 @@ export {
   signUp,
   requestPasswordReset,
   confirmPasswordReset,
+  verifyEmail,
+  claimOffer,
+  mailedLink,
+  forgetMailedLink,
   readEntity,
   listEntities,
   writeItems,
@@ -35,6 +39,7 @@ export { useSession } from './hooks/useSession.js'
 export { useSignIn } from './hooks/useSignIn.js'
 export { useSignUp } from './hooks/useSignUp.js'
 export { usePasswordReset } from './hooks/usePasswordReset.js'
+export { useMailedLink } from './hooks/useMailedLink.js'
 export { useEntity } from './hooks/useEntity.js'
 export { useRecords } from './hooks/useRecords.js'
 export { useEntityWriter } from './hooks/useEntityWriter.js'

package/src/mailed-links.js

@@ -0,0 +1,132 @@
+/**
+ * The links a site's backend mails — and the steps they come to finish.
+ *
+ * A site's backend mails its members: to confirm an address, to reset a password, to
+ * invite them. Every link lands on the site's root, with a token in one parameter
+ * (`LINK` in `./wire.js`), and the page finishes the step there. No React in this
+ * module; `useMailedLink` is the hook over it.
+ *
+ * ⭐ **Functions of a client, not methods.** The page holds one client, created by
+ * whichever copy of this package asked first (`getClient`), so an instance an older
+ * copy created may lack an operation added since. Everything here reaches the wire
+ * through `request`, which every instance has, and keeps its state on the instance.
+ */
+
+import { ApiError } from './errors.js'
+import { AUTH, CLAIM, LINK, OFFERS, PARAM } from './wire.js'
+
+const STEPS = Object.values(LINK)
+
+/**
+ * The step a link the site's backend mailed came to finish — `{ step, token }`, where
+ * `step` is `'verify'`, `'reset'` or `'offer'` — or `null` when the URL carries none.
+ *
+ * @param {string} [search] - a query string; the page's own by default
+ * @returns {{ step: string, token: string } | null}
+ */
+export function mailedLink(search = globalThis.location?.search ?? '') {
+  let params
+  try {
+    params = new URLSearchParams(search)
+  } catch {
+    return null
+  }
+  for (const step of STEPS) {
+    const token = params.get(step)
+    if (token) return Object.freeze({ step, token })
+  }
+  return null
+}
+
+/**
+ * Take a mailed link's parameter off the address bar, so a reload does not spend a used
+ * token again and the token leaves the page's URL. The rest of the URL stays. Nothing
+ * happens outside a browser, or when the URL no longer carries that token.
+ *
+ * ⛔ **`history.replaceState`, not a navigation** — no route change, no scroll, no new
+ * history entry, and the router's own state is kept.
+ *
+ * @param {{ step: string, token: string } | null} [link] - the page's own by default
+ */
+export function forgetMailedLink(link = mailedLink()) {
+  const location = globalThis.location
+  const history = globalThis.history
+  if (!link || !location || typeof history?.replaceState !== 'function') return
+  const params = new URLSearchParams(location.search)
+  if (params.get(link.step) !== link.token) return
+  params.delete(link.step)
+  const query = params.toString()
+  history.replaceState(history.state, '', `${location.pathname}${query ? `?${query}` : ''}${location.hash}`)
+}
+
+/**
+ * Confirm an address with the token of its mailed link (`?verify=`). No session needed,
+ * and it starts none: once confirmed, the member signs in.
+ *
+ * @param {object} client
+ * @param {string} token
+ * @returns {Promise<{ verified: true }>}
+ * @throws {ApiError} `invalid` — the link was used, has expired, or was never valid
+ */
+export async function verifyEmailWith(client, token) {
+  if (!token) throw ApiError.invalid('No Token', 'verifyEmail needs the token of the mailed link')
+  return client.request('GET', AUTH.verify, { query: { [PARAM.token]: token }, onUnauthorized: 'ignore' })
+}
+
+/**
+ * Claim an offer with the token of its mailed link (`?offer=`), for the account signed
+ * in. Answers counts (`CLAIM`): invitations now waiting for this account to accept, and
+ * entities now shared with it — so when there are any, the viewer's cached reads go,
+ * and what is mounted reads again.
+ *
+ * @param {object} client
+ * @param {string} token
+ * @returns {Promise<{ invitations: number, grants: number }>}
+ * @throws {ApiError} `absent` — unknown, revoked or already claimed, one answer by design ·
+ *   `auth` — nobody signed in
+ */
+export async function claimOfferWith(client, token) {
+  if (!token) throw ApiError.invalid('No Token', 'claimOffer needs the token of the mailed link')
+  const answer = await client.request('POST', OFFERS.claim, { body: { [CLAIM.token]: token } })
+  if (answer?.[CLAIM.grants] > 0) client.invalidate?.(() => true)
+  return answer
+}
+
+/**
+ * Finish a `verify` or an `offer` link ONCE per page, however many components ask: the
+ * token is spent by the first request, so a second would be refused. A step that
+ * succeeded answers the same again; one that failed may be asked again. An offer is
+ * claimed per viewer — another account signed in afterwards asks the backend itself.
+ * A `reset` needs the new password, so it is finished with `confirmPasswordReset`.
+ *
+ * @param {object} client
+ * @param {{ step: string, token: string }} link
+ * @returns {Promise<object>} the backend's answer
+ */
+export function finishMailedLink(client, link) {
+  if (link?.step !== LINK.verify && link?.step !== LINK.offer) {
+    return Promise.reject(ApiError.invalid('Not Finished Here', `a ${link?.step} link needs the member's input`))
+  }
+  const runs = (client._mailedLinks ??= new Map())
+  const key = link.step === LINK.offer ? `${link.step}:${link.token}:${client.viewerId}` : `${link.step}:${link.token}`
+  if (runs.has(key)) return runs.get(key)
+  const run = link.step === LINK.verify ? verifyEmailWith(client, link.token) : claimOfferWith(client, link.token)
+  const pending = run.catch((error) => {
+    runs.delete(key)
+    throw error
+  })
+  runs.set(key, pending)
+  return pending
+}
+
+/**
+ * Whether a refusal settles the link for good — the backend judged the token — so it
+ * leaves the address bar. A link the backend could not be asked about, or asked
+ * without a session, may still work.
+ *
+ * @param {ApiError} error
+ * @returns {boolean}
+ */
+export function spends(error) {
+  return error?.kind === 'invalid' || error?.kind === 'absent'
+}

package/src/mock/index.js

@@ -1,7 +1,15 @@
-import { AUTH, ENTITIES, MODELS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL } from '../wire.js'
+import { AUTH, ENTITIES, MODELS, OFFERS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL } from '../wire.js'
 import { MockStore, isUuid, refuse } from './store.js'
 import { DEFAULT_SEED } from './seed.js'
 
+/**
+ * The mock's postman: each message, as it is sent, where the mock runs — the dev
+ * server's terminal, under `uniweb dev` — with its link on the site's origin.
+ */
+export function printMail(message, url) {
+  console.log(`[uniweb/api mock] ✉ ${message.subject} → ${message.to}\n    ${url}`)
+}
+
 /**
  * Where the mock's Admin link lands. The backend's administration lives on its own
  * origin, outside the API, and the mock models none of it: the handoff's redirect
@@ -57,21 +65,53 @@ function adminPage(account) {
  * in — the operator too, as on a real site — reads and writes their own entities and
  * nothing of another's (unless the seed's `memberFloor` says the service lets them);
  * anyone signed in may create entries of any Model (Models are open); sign-up
- * leaves an account unverified until the link in `mock.outbox` is followed. The
- * operator is the account the backend's administration admits, so its Admin link
- * answers — with a redirect to a page of the mock's own, since the administration
- * itself is not modelled. It does not model entitlements behind `via`, nested
- * sections, or second factors.
+ * leaves an account unverified until its address is confirmed. The operator is the
+ * account the backend's administration admits, so its Admin link answers — with a
+ * redirect to a page of the mock's own, since the administration itself is not
+ * modelled. It does not model entitlements behind `via`, nested sections, second
+ * factors, password rules, or what an offer binds.
+ *
+ * ## The mail it sends
+ *
+ * A sign-up's confirmation, a password reset, and an invitation to an address with no
+ * account (`seed.offers`) are mailed as the backend mails them: a link to the site's
+ * root carrying a token — `/?verify=…`, `/?reset=…`, `/?offer=…` — which the site's
+ * own pages finish (`useMailedLink`). Each message is kept in `outbox` and, as it is
+ * sent, handed to `onMail` — printed, by default, where the mock runs.
  *
  * @param {object} [options]
- * @param {object} [options.seed] - accounts, schemas and entities to start from (see `MockStore`)
+ * @param {object} [options.seed] - accounts, schemas, entities and offers to start from (see `MockStore`)
  * @param {string} [options.signedInAs] - a seeded `username` to start signed in as. Throws if not seeded.
  * @param {string} [options.prefix] - the path the API is mounted under (default `/_api`), stripped when present
+ * @param {string} [options.siteOrigin] - the site's origin, on which the mail's links land. By
+ *   default, the origin of the request that sent the mail — the site's own when the mock is
+ *   mounted in the site's dev server, as `uniweb dev` mounts it
+ * @param {((message: object, url: string) => void) | null} [options.onMail] - called with each
+ *   message as it is sent, and its link on the site's origin. `printMail` by default; `null`
+ *   sends quietly
  * @returns {{ fetch: (request: Request) => Promise<Response>, store: MockStore, diagnostics: object[], outbox: object[] }}
  */
-export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signedInAs = null } = {}) {
+export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signedInAs = null, siteOrigin = null, onMail = printMail } = {}) {
   const store = new MockStore(seed, { signedInAs })
 
+  // Mail is delivered after the request that sent it, so its link can name that
+  // request's origin. Mail the seed sent waits for the first request.
+  let delivered = 0
+  function deliver(request) {
+    const fresh = store.outbox.slice(delivered)
+    delivered = store.outbox.length
+    if (typeof onMail !== 'function' || !fresh.length) return
+    let origin = siteOrigin
+    if (!origin) {
+      try {
+        origin = new URL(request.url).origin
+      } catch {
+        origin = null
+      }
+    }
+    for (const message of fresh) onMail(message, origin ? new URL(message.link, origin).href : message.link)
+  }
+
   const json = (status, body) =>
     new Response(body === undefined ? null : JSON.stringify(body), {
       status,
@@ -258,6 +298,15 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
       }
     }
 
+    // ── Offers ──────────────────────────────────────────────────────────────
+    if (path === OFFERS.claim && method === 'POST') {
+      const bad = unexpected(q, [])
+      if (bad) return bad
+      if (!store.account) return unauthorized()
+      const b = await body(request)
+      return fields(b, ['token'], '{"token": ...}') ?? answer(store.claimOffer(b.token))
+    }
+
     // ── A Model's definition ─────────────────────────────────────────────────
     if (path.startsWith(`${MODELS}/`) && method === 'GET') {
       const bad = unexpected(q, [])
@@ -436,18 +485,24 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
     get diagnostics() {
       return store.diagnostics
     },
-    /** The mail the backend would have sent — sign-up verification and password-reset tokens. */
+    /**
+     * The mail the backend would have sent — `{ to, subject, token, link }`, `link` a
+     * site-root link carrying the token (`/?verify=…`, `/?reset=…`, `/?offer=…`).
+     */
     get outbox() {
       return store.outbox
     },
     async fetch(request) {
+      let response
       try {
-        return await route(request)
+        response = await route(request)
       } catch (err) {
         // A mock that throws leaves the caller staring at a network error and
         // blaming their own code. Answer, and say it was us.
-        return problem({ status: 500, title: 'MockFailure', detail: err?.message || 'the mock threw' })
+        response = problem({ status: 500, title: 'MockFailure', detail: err?.message || 'the mock threw' })
       }
+      deliver(request)
+      return response
     },
   }
 }

package/src/mock/seed.js

@@ -13,6 +13,9 @@
  * - **`entities`** — `uuid` must be a UUID, as it is on the wire; content is items,
  *   each naming its section. The entity's `brief` is derived from its brief
  *   section's item, as the backend derives it.
+ * - **`offers`** — optional, and none here: `{ email, invitations?, grants? }`, an
+ *   invitation sent to an address with no account, mailed when the mock starts. Its
+ *   link (`/?offer=…`) is how a site's pages are tried with one.
  */
 export const DEFAULT_SEED = {
   accounts: [

package/src/mock/store.js

@@ -1,4 +1,4 @@
-import { FIELD, OP, PROBLEM } from '../wire.js'
+import { CLAIM, FIELD, LINK, OP, PROBLEM } from '../wire.js'
 import { checkItemWrite, OUTCOME } from './schema-shape.js'
 
 /**
@@ -31,9 +31,15 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  * drifts and is believed anyway.
  *
  * ⛔ **What it does not model**: entitlements behind `via` (a `via` read is the
- * same read), nested sections, second factors, reference fields.
+ * same read), nested sections, second factors, reference fields, password rules,
+ * and what an offer binds — a seeded offer answers the counts its seed gives, and
+ * confirming the address it was sent to takes up nothing (the backend binds every
+ * pending offer then).
  */
 
+/** A mailed link — the site's root, the step's parameter, the token. */
+const linkTo = (step, token) => `/?${step}=${encodeURIComponent(token)}`
+
 /** The unit every account of a site acts in — an entity's `unit_id`. */
 export const SITE_UNIT = 1
 
@@ -123,6 +129,9 @@ export class MockStore {
    *   member's are private. A string applies to every Model; a map `{ '@scope/name': 'read' }`
    *   applies per Model, so a service can open the operator's content (courses, lessons) to
    *   its members while their own records (progress, submissions) stay theirs alone.
+   * @param {object[]} [seed.offers] - `{ email, invitations?, grants? }`: an invitation sent
+   *   to an address with no account, mailed when the mock starts. Claiming it answers the
+   *   counts given (default `0`), once.
    * @param {object} [options]
    * @param {string} [options.signedInAs] - start with this account already signed in.
    */
@@ -167,9 +176,16 @@ export class MockStore {
      * seed lists as `migration_debt`. Empty is the good state.
      */
     this.diagnostics = []
-    /** Mail the backend would send: `{ to, subject, token, verify? }`, newest last. */
+    /**
+     * Mail the backend would send: `{ to, subject, token, link }`, newest last. `link` is
+     * the mail's link without its origin — the site's root, its step's parameter and the
+     * token (`/?verify=…`); the backend's carries the site's origin.
+     */
     this.outbox = []
     this.pending = { verify: new Map(), reset: new Map() }
+    /** Offers by token: `{ email, invitations, grants, claimed }`. */
+    this.offers = new Map()
+    for (const offer of seed.offers || []) this.addOffer(offer)
     this.entities = new Map()
     for (const e of seed.entities || []) this.seedEntity(e)
 
@@ -255,7 +271,7 @@ export class MockStore {
       const account = this.addAccount({ username, email, password }, { verified: false })
       const token = newUuid()
       this.pending.verify.set(token, account)
-      this.outbox.push({ to: email, subject: 'Confirm your email address', token, verify: `/auth/verify?token=${token}` })
+      this.outbox.push({ to: email, subject: 'Confirm your email address', token, link: linkTo(LINK.verify, token) })
     }
     return { status: 202, body: { status: 'verification_required', email } }
   }
@@ -273,7 +289,7 @@ export class MockStore {
     if (account) {
       const token = newUuid()
       this.pending.reset.set(token, account)
-      this.outbox.push({ to: email, subject: 'Reset your password', token })
+      this.outbox.push({ to: email, subject: 'Reset your password', token, link: linkTo(LINK.reset, token) })
     }
     return { status: 202, body: { status: 'reset_requested' } }
   }
@@ -288,6 +304,33 @@ export class MockStore {
     return { body: { reset: true } }
   }
 
+  // ── Offers ──────────────────────────────────────────────────────────────────
+
+  /** An invitation to an address with no account here — its token mailed at once. */
+  addOffer({ email, invitations = 0, grants = 0 } = {}) {
+    const count = (n) => Number.isInteger(n) && n >= 0
+    if (typeof email !== 'string' || !email || !count(invitations) || !count(grants)) {
+      throw new Error(
+        `[uniweb/api mock] an offer is { email, invitations?, grants? }, the counts whole numbers — got ${JSON.stringify({ email, invitations, grants })}`
+      )
+    }
+    const token = newUuid()
+    this.offers.set(token, { email, invitations, grants, claimed: false })
+    this.outbox.push({ to: email, subject: "You've been invited", token, link: linkTo(LINK.offer, token) })
+    return token
+  }
+
+  /**
+   * Claim an offer for the account signed in. Unknown, revoked and already claimed are
+   * one answer, `404`, as on the backend.
+   */
+  claimOffer(token) {
+    const offer = this.offers.get(token)
+    if (!offer || offer.claimed) return refuse(404, 'Not Found', 'offer not found')
+    offer.claimed = true
+    return { body: { [CLAIM.invitations]: offer.invitations, [CLAIM.grants]: offer.grants } }
+  }
+
   // ── Models ──────────────────────────────────────────────────────────────────
 
   defineModel(name, decl = {}, itemSections = new Set()) {

package/src/wire.js

@@ -91,10 +91,12 @@ export const AUTH = {
   logout: '/auth/logout',
   register: '/auth/register',
   /**
-   * `GET /auth/verify?token=` → `{ verified: true }`; a bad token is `400 Validation`.
-   * ⚠️ This package does not call it: the link in the verification email is the
-   * backend's own, not a page of the site. The mock serves it so a sign-up can be
-   * finished locally.
+   * `GET /auth/verify?token=` → `{ verified: true }`: the address is confirmed and the
+   * member may sign in — it starts no session. A token that was used, has expired or
+   * was never valid is `400 Validation`. The token comes from the link the backend
+   * mails, which lands on the site's root (`LINK.verify`), and `verifyEmail` finishes
+   * it. *(Until 2026-10-11 that link named the backend's own sign-in page, and this
+   * package did not call the route.)*
    */
   verify: '/auth/verify',
   resetRequest: '/auth/reset/request',
@@ -136,7 +138,7 @@ export const HANDOFF_REFUSAL = Object.freeze({
  * | challenge | `{ challenge_token, code }` | as login's `200`; a bad token or code is `401` |
  * | register | `{ username, email, password }` | `202 { status: 'verification_required', email }` — the same answer for an address already taken; a taken **username** is `409` |
  * | reset request | `{ email }` | `202 { status: 'reset_requested' }` whether or not the address is known |
- * | reset confirm | `{ token, new_password, code? }` | `200 { reset: true }`; a bad token is `400 Validation`; `code` is required when a second factor is enrolled |
+ * | reset confirm | `{ token, new_password, code? }` | `200 { reset: true }`, and every other session of the account ends; a bad token is `400 Validation`; `code` is required when a second factor is enrolled. A password the rule refuses is `400` with `reason: 'password_too_short'` and `min_length` — refused BEFORE the token is spent, so the same link works again (RULED by backend, 2026-10-11) |
  * | logout | none | `204`; with no session to end, `401` |
  * | me | none | `200 { account: { uuid, username, handle }, roles, workspace: { unit_uuid, handle }, capabilities: { admin_app } }` · `401` |
  *
@@ -153,6 +155,56 @@ export const AUTH_BODY = {
   resetConfirm: ['token', 'new_password', 'code?'],
 }
 
+/**
+ * The links a site's backend mails. **RULED** by backend, 2026-10-11.
+ *
+ * Every link in the mail a site's backend sends lands on the site's root — `/` on the
+ * site's primary origin — with at most one of these parameters, carrying a token:
+ *
+ * | parameter | the step it starts | finished with |
+ * |---|---|---|
+ * | `verify` | confirm a new account's address | `GET /auth/verify?token=` |
+ * | `reset` | choose a new password — and give a code, with a second factor | `POST /auth/reset/confirm` |
+ * | `offer` | take up an invitation sent to this address | `POST /offers/claim`, signed in |
+ *
+ * The root with none — a notice, such as a password changed or an invitation waiting —
+ * has no step to finish: the member signs in. The names are the ones all of the
+ * backend's mail uses, so a token means the same thing wherever its link lands.
+ *
+ * ⚠️ A root that redirects drops the query unless the redirect carries it.
+ * `@uniweb/runtime` carries it on its own redirects since 0.29.6.
+ */
+export const LINK = {
+  verify: 'verify',
+  reset: 'reset',
+  offer: 'offer',
+}
+
+/**
+ * Offers. **MEASURED** by backend, 2026-09-15.
+ *
+ * Inviting an address nobody here holds — to an organization, or to share an entity —
+ * mints an offer, and the backend mails its token to that address (`LINK.offer`).
+ * Whoever holds the token claims it, signed in, for that account — whatever the
+ * account's own address — and what the offer held binds to it.
+ *
+ * `POST /offers/claim` `{ token }` → `200 { invitations, grants }` (`CLAIM`) —
+ * COUNTS, not names: invitations now waiting for this account to accept, and entities
+ * now shared with it. ⛔ **An unknown, revoked or already-claimed token is ONE answer,
+ * `404`**, so the route never says whether a token was ever real. A missing `token`
+ * is `400`.
+ */
+export const OFFERS = {
+  claim: '/offers/claim',
+}
+
+/** The claim's body and answer. MEASURED. */
+export const CLAIM = {
+  token: 'token',
+  invitations: 'invitations',
+  grants: 'grants',
+}
+
 /** A sign-in that needs a second factor. MEASURED. */
 export const TOTP = {
   status: 'totp_required',
@@ -241,6 +293,7 @@ export const ROUTES = {
  * | items | `model` (required) · `readback` |
  * | create | `model` (required) |
  * | remove | `rev_ref_policy` |
+ * | verify (`AUTH.verify`) | `token` (required) |
  *
  * ✅ **`via` and `depth` compose** (an assumption retired 2026-09-18): both are
  * parameters of the same read and answer different questions — `via` *who may
@@ -265,6 +318,7 @@ export const PARAM = {
   maxDepth: 'max_depth',
   readback: 'readback',
   revRefPolicy: 'rev_ref_policy',
+  token: 'token',
 }
 
 /**
@@ -472,7 +526,7 @@ export const PROBLEM = {
  * ⛔ THE LIST TO HAND BACKEND — everything this package asserts that nobody has
  * confirmed. Each entry says what we do, and what breaks if we are wrong.
  *
- * ⭐ **Empty since 2026-09-18.** The last two were answered by measurement:
+ * Empty from 2026-09-18 to 2026-10-11, when the last two were answered by measurement:
  *
  * | retired | answered as |
  * |---|---|
@@ -483,4 +537,11 @@ export const PROBLEM = {
  * `op-field-names` — see `FIELD` and `OP`.)* A new entry needs `we`, `from` and
  * `breaks`; `tests/wire.test.js` pins the set, so adding one is deliberate.
  */
-export const ASSUMPTIONS = []
+export const ASSUMPTIONS = [
+  {
+    id: 'offer-claim-needs-a-session',
+    we: 'claim an offer only once signed in (`useMailedLink`), and answer a claim with no session `401` in the mock',
+    from: 'the backend: the member signs up or signs in, then claims (2026-10-11). Nobody has recorded what a claim with no session answers',
+    breaks: 'nothing the hook does, since it never claims signed out — but the mock would answer a signed-out claim unlike the backend',
+  },
+]