@uniweb/api 0.7.0 → 0.9.0

package/README.md

@@ -52,22 +52,77 @@ function Account() {
 ```
 
 `viewer` is flat — `viewer.uuid`, `viewer.username`, `viewer.handle`, and `viewer.roles`,
-a list of `{ role, scope_unit_id }`. A member holds no roles (`[]`); the site's operator
-holds `system_admin`. ⚠️ `viewer.workspace` — the site service's home org,
-`{ handle: 'home', … }` — is the same for every member, so it cannot tell an operator
-from a member. To decide whether to show an edit control for
-a particular record, read that record: `entity.can_edit` is the backend's own answer.
+a list of `{ role, scope_unit_id }`. ⭐ **Roles describe the session, and a session
+signed in on a site holds a member's rights — the operator's too.** A site runs your
+foundation's code with the signed-in member's session, so no administrator's role
+rides with it: `viewer.roles` never names one there, and an ordinary member holds none
+(`[]`). `viewer.workspace` — the site service's home org, `{ handle: 'home', … }` — is
+the same for everyone. To decide whether to show an edit control for a particular
+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
+administration, already signed in; for everyone else it is `null`, so draw the link
+only when it is set:
+
+```jsx
+const { adminHref } = useSession()
+
+{adminHref && <a href={adminHref}>Admin</a>}
+```
+
+⛔ **Navigate to it — a link, or `location.assign(adminHref)` — never `fetch` it.** It
+answers with a redirect carrying a one-time credential that no script on the site is
+to hold. The link decides what to offer, not what is allowed: on the site, an
+administrator's session acts as a member's, and administering happens at the other
+end of the link.
 
 ## Reading
 
@@ -84,9 +139,9 @@ live source — no `backend` service, or nobody signed in — so render your sit
 Showing "nothing yet" for the first case tells a visitor their content is missing
 when it is simply not being asked for.
 
-**Whose records.** A member reads their own entities and what was shared with them;
-other members' are private unless the site's service was set up to let members read
-each other's. The site's operator reads everything. `scope: 'mine'` lists only the
+**Whose records.** Everyone signed in on the site — its operator too — reads their own
+entities and what was shared with them; other members' are private unless the site's
+service was set up to let members read each other's. `scope: 'mine'` lists only the
 viewer's own.
 
 A record is a summary: `record.brief` holds the fields of the Model's brief section. It
@@ -182,7 +237,7 @@ import { createMockBackend } from '@uniweb/api/mock'
 export default createMockBackend({
   seed: {
     accounts: [
-      { username: 'me', password: 'me', operator: true },   // the site's operator
+      { username: 'me', password: 'me', operator: true },   // runs the site, and gets the Admin link
       { username: 'member', password: 'member' },
     ],
     schemas: {
@@ -210,27 +265,33 @@ production, and nothing in your site's configuration changes between the two.
 
 ⭐ **The mock answers what the backend answers** — the same statuses, bodies and
 refusals, for every route this package uses. It enforces what your schemas declare —
-who may create entries, which sections are insert-only, the fields a section takes —
-and it is as strict as the backend about requests, so a mistake fails here rather
-than in front of a user. Members read and write their own entities and nothing of each
-other's; the operator reads and writes everything (`memberFloor: 'read'` in the seed
-models a service set up to let members read each other's — or per Model,
+which sections are insert-only, the fields a section takes — and it is as strict as
+the backend about requests, so a mistake fails here rather than in front of a user.
+Everyone signed in — the operator too, as on a real site — reads and writes their own
+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). State is in
-memory: restart to reset.
+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`.
+`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.7.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": {
@@ -34,7 +34,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.38.0"
+    "@uniweb/core": "^0.38.1"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -15,8 +15,9 @@ import { getUniweb, deriveCacheKey } from '@uniweb/core'
 import { resolveService } from '@uniweb/core'
 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 } from './wire.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.
@@ -353,6 +354,7 @@ export class ApiClient {
       ...account,
       roles: Array.isArray(me?.roles) ? me.roles : [],
       workspace: viewerWorkspace(me?.workspace),
+      adminApp: me?.[VIEWER.capabilities]?.[VIEWER.adminApp] === true,
     })
     if (this._session.viewer && this._session.viewer.uuid !== viewer.uuid) this.forgetViewer()
     return this.setSession({ status: 'authenticated', viewer, error: null })
@@ -449,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 ─────────────────────────────────────────────────────────────
 
   /**
@@ -627,8 +654,9 @@ export class ApiClient {
    * a `401` too, never an empty list (so `records: []` means empty).
    *
    * `scope` decides whose: the default, `accessible`, is everything the viewer may
-   * read — for a member of a site, their own entities and what was shared with them;
-   * for the operator, everything. `mine` is only what the viewer owns.
+   * read — signed in on a site, their own entities and what was shared with them, the
+   * operator's session included (`VIEWER` in `./wire.js`). `mine` is only what the
+   * viewer owns.
    *
    * ## Paging, as far as it can honestly be absorbed
    *
@@ -921,6 +949,28 @@ export function getClient() {
   return client
 }
 
+/**
+ * The Admin link — the address that takes the viewer to the backend's administration,
+ * signed in — or `null` when there is none to offer: no backend, nobody signed in, or
+ * an account the administration does not admit (`viewer.adminApp`).
+ *
+ * ⛔ **For a navigation — an `<a href>`, `location.assign` — never a `fetch`.** It
+ * answers with a redirect carrying a one-time credential that no script on a site is to
+ * hold, and a fetch that follows it spends the code (`AUTH.memberHandoff`).
+ *
+ * A function of the client's base and a session snapshot, not a method: an instance an
+ * older copy of this package created has neither, and works here all the same.
+ *
+ * @param {ApiClient|null} client
+ * @param {object} [session] - a snapshot; the client's current one by default
+ * @returns {string|null}
+ */
+export function adminHrefOf(client, session = client?.session) {
+  const base = client?.base ?? null
+  if (base === null || session?.status !== 'authenticated' || session.viewer?.adminApp !== true) return null
+  return composeUrl(base, AUTH.memberHandoff)
+}
+
 // ── The functions — the same client, outside React ───────────────────────────
 
 function required() {
@@ -943,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 */
@@ -953,6 +1007,9 @@ export const writeItems = (args) => required().writeItems(args)
 export const createEntity = (args) => required().createEntity(args)
 /** @see ApiClient#deleteEntity */
 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/hooks/useRecords.js

@@ -34,8 +34,8 @@ const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, ha
  * entity for those. ⚠️ `matched` counts the records in this answer, not a total:
  * `hasMore` is true when the page came back full.
  *
- * The default scope is everything the viewer may read — for a member, their own
- * entities and what was shared with them; for the operator, everything.
+ * The default scope is everything the viewer may read — signed in on a site, their
+ * own entities and what was shared with them, the operator included.
  * `scope: 'mine'` is only the viewer's own.
  *
  * Cached under a key scoped to the viewer, so a sign-in re-reads the list for who

package/src/hooks/useSession.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useSyncExternalStore } from 'react'
-import { getClient } from '../client.js'
+import { getClient, adminHrefOf } from '../client.js'
 
 const NONE = Object.freeze({ status: 'anonymous', viewer: null, error: null })
 const noSubscribe = () => () => {}
@@ -15,6 +15,10 @@ const noop = async () => NONE
  * affordance on false. `error` is set when the backend could not be asked;
  * `refresh()` asks again.
  *
+ * `adminHref` is the Admin link — set only for a signed-in account the backend's
+ * administration admits, `null` for everyone else, so draw the link only when it is
+ * set. ⛔ Navigate to it, never `fetch` it (`adminHrefOf` in `../client.js`).
+ *
  * Reads the shared snapshot through `useSyncExternalStore`, so every copy of
  * this package on the page sees one session, and the first render on the
  * server matches the first render in the browser.
@@ -24,6 +28,7 @@ const noop = async () => NONE
  *   viewer: object | null,
  *   error: Error | null,
  *   canSignIn: boolean,
+ *   adminHref: string | null,
  *   signOut: () => Promise<void>,
  *   refresh: () => Promise<object>,
  * }}
@@ -48,6 +53,7 @@ export function useSession() {
     viewer: session.viewer,
     error: session.error,
     canSignIn: !!(client && client.enabled),
+    adminHref: adminHrefOf(client, session),
     signOut,
     refresh,
   }

package/src/index.js

@@ -21,11 +21,16 @@ export {
   signUp,
   requestPasswordReset,
   confirmPasswordReset,
+  verifyEmail,
+  claimOffer,
+  mailedLink,
+  forgetMailedLink,
   readEntity,
   listEntities,
   writeItems,
   createEntity,
   deleteEntity,
+  adminHref,
   ApiError,
   Ledger,
 } from './client.js'
@@ -34,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,32 @@
-import { AUTH, ENTITIES, MODELS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS } 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
+ * comes here instead, to a page that says so. A path of the mock's, not the backend's.
+ */
+const ADMIN_PAGE = '/admin'
+
+const escapeHtml = (value) =>
+  String(value).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+
+function adminPage(account) {
+  const who = account ? `Signed in as <b>${escapeHtml(account.handle)}</b>. ` : ''
+  return `<!doctype html><meta charset="utf-8"><title>Administration</title>
+<p>${who}On a live site, the Admin link opens the backend's administration here, signed in. The local mock has none to open.</p>
+`
+}
+
 /**
  * A mock of a site's `backend` service, for local development.
  *
@@ -36,22 +61,57 @@ import { DEFAULT_SEED } from './seed.js'
  *
  * ## What it models, and what it does not
  *
- * One operator (`operator: true` on a seeded account) and members; a member reads
- * and writes their own entities and nothing of another's (unless the seed's
- * `memberFloor` says the service lets them), the operator reads and writes all;
+ * One operator (`operator: true` on a seeded account) and members; everyone signed
+ * 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. 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,
@@ -199,6 +259,14 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
         const viewer = store.viewer()
         return viewer ? json(200, viewer) : unauthorized()
       }
+      if (path === AUTH.memberHandoff && method === 'GET') {
+        if (!store.account) return unauthorized()
+        if (!store.account.operator) return problem(HANDOFF_REFUSAL)
+        // The backend redirects to its administration on its own origin. The mock has
+        // none, so the redirect lands on a page of its own that says so (`ADMIN_PAGE`).
+        // Relative, so it lands under whatever path the mock is mounted at.
+        return new Response(null, { status: 302, headers: { location: `..${ADMIN_PAGE}` } })
+      }
       if (path === AUTH.login && method === 'POST') {
         const b = await body(request)
         return fields(b, ['username', 'password'], '{"username": ..., "password": ...}') ?? answer(store.signIn(b))
@@ -230,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, [])
@@ -391,6 +468,11 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
       }
     }
 
+    // ── Where the Admin link lands ──────────────────────────────────────────
+    if (path === ADMIN_PAGE && method === 'GET') {
+      return new Response(adminPage(store.account), { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' } })
+    }
+
     return problem({ status: 404, title: 'Not Found', detail: `no route for ${method} ${path}` })
   }
 
@@ -403,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'
 
 /**
@@ -19,19 +19,27 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  *   unless shared. A service can be set up to let members read (or edit) each
  *   other's — the seed's `memberFloor` models that choice. *(Until 2026-09-18 the
  *   backend gave every member read access to every other member's entities.)*
- * - **The operator** — the account that runs the site's service — holds
- *   `system_admin`, creates the Models only the operator may, and may write
- *   anything. It is a member of the site's unit like everyone else, so what it
- *   makes is its own. A seeded account is the operator with `operator: true`.
+ * - **The operator** — the account that runs the site's service — owns what the
+ *   seed gives it. ⛔ **Signed in on the site it holds a member's rights**, like
+ *   everyone: no `system_admin` in `roles`, and nothing of another member's unless
+ *   shared — a site runs third-party code with its member's session. *(Until
+ *   2026-10-10 the operator's session held `system_admin` and read and wrote
+ *   everything.)* A seeded account is the operator with `operator: true`.
  *
  * ⛔ **Seeded fixtures plus in-memory mutation, and deliberately not a database.**
  * A mock that grows a schema and migrations becomes a second implementation that
  * 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
 
@@ -121,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.
    */
@@ -165,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)
 
@@ -207,15 +225,21 @@ export class MockStore {
     return this.session?.account ?? null
   }
 
-  /** The viewer, in the shape `/auth/me` answers. */
+  /**
+   * The viewer, in the shape `/auth/me` answers. `roles` are the session's, and a
+   * session on a site holds no administrator's — the operator's neither. Whether the
+   * backend's administration admits the ACCOUNT is `capabilities.admin_app`: the
+   * operator's yes, a member's no.
+   */
   viewer(account = this.account) {
     if (!account) return null
     return {
       account: this.identity(account),
-      roles: account.operator ? [{ role: 'system_admin', scope_unit_id: null }] : [],
+      roles: [],
       // A request that names no workspace — as this package's never do — lands in the
       // home org, which every account belongs to. Both null would mean a non-member.
       workspace: { ...HOME_ORG },
+      capabilities: { admin_app: account.operator === true },
     }
   }
 
@@ -229,7 +253,8 @@ export class MockStore {
     if (!account.verified) return refuse(403, PROBLEM.notVerified, 'verify your email address before signing in')
     this.session = { account }
     const expires = new Date(Date.now() + 30 * 24 * 3600 * 1000).toISOString()
-    return { body: { token: `mock-${account.uuid}`, expires_at: expires, account: this.identity(account) } }
+    // No `token`: a site's backend answers a sign-in with the session cookie alone.
+    return { body: { expires_at: expires, account: this.identity(account) } }
   }
 
   signOut() {
@@ -246,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 } }
   }
@@ -264,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' } }
   }
@@ -279,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()) {
@@ -468,28 +520,31 @@ export class MockStore {
     return floor[entity.model] ?? null
   }
 
-  /** The operator, the owner — or any member, when the service lets members read each other's. */
+  /**
+   * The owner — or any member, when the service lets members read each other's. The
+   * operator is a member here like everyone: a session on a site holds no
+   * administrator's rights.
+   */
   mayRead(entity) {
     const me = this.account
-    return !!me && (me.operator || entity.owner_id === me.id || this.floorFor(entity) != null)
+    return !!me && (entity.owner_id === me.id || this.floorFor(entity) != null)
   }
 
   mayEdit(entity) {
     const me = this.account
-    return !!me && (me.operator || entity.owner_id === me.id || this.floorFor(entity) === 'edit')
+    return !!me && (entity.owner_id === me.id || this.floorFor(entity) === 'edit')
   }
 
   /**
    * Which branch lets the viewer read a row, as the backend names it — the first to
-   * answer in its order: `owner`, `grant`, `rbac`, `unit_member`. The operator's own rows
-   * are `owner` like anyone's, and the rest it reads as `system_admin`. *(Until
-   * 2026-09-18 the operator was not a member of the site's unit, and ownership speaks
-   * only for a member — so its own rows answered `rbac` too.)*
+   * answer in its order: `owner`, `grant`, `rbac`, `unit_member`. A session's own rows
+   * are `owner`, the operator's too, and the rest it reads by the service's floor.
+   * *(Until 2026-10-10 the operator's session read the rest as `rbac`, through
+   * `system_admin`.)*
    */
   via(entity) {
     const me = this.account
     if (entity.owner_id === me?.id) return 'owner'
-    if (me?.operator) return 'rbac'
     return 'unit_member'
   }
 

package/src/wire.js

@@ -91,16 +91,42 @@ 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',
   resetConfirm: '/auth/reset/confirm',
+  /**
+   * `GET /auth/member-handoff` — the Admin link (`adminHref` in `./client.js`).
+   * ⛔ **A navigation, never a fetch.** For an account the backend's administration
+   * admits (`VIEWER`'s `admin_app`), it answers `302` toward that administration, on
+   * the backend's own origin, carrying a one-time credential no script on a site is to
+   * hold — a fetch learns nothing from the redirect, and one that follows it spends
+   * the code. `401` no session · `403` an account it does not admit
+   * (`HANDOFF_REFUSAL`) · `404` a backend no site reaches · `503` a backend never told
+   * its own origin — each problem JSON, branched on by `title` or `reason`, never
+   * `detail`. **MEASURED** by backend, 2026-10-10.
+   */
+  memberHandoff: '/auth/member-handoff',
 }
 
+/**
+ * The handoff's `403`, as sent — an account the administration does not admit.
+ * **MEASURED** by backend, 2026-10-10. This package never reads it: the handoff is a
+ * navigation, so the browser shows it. The mock answers it.
+ */
+export const HANDOFF_REFUSAL = Object.freeze({
+  status: 403,
+  title: 'Admin Role Required',
+  detail: "the admin app admits a system_admin or an administrator of this deployment's home org",
+  reason: 'admin_role_required',
+})
+
 /**
  * The bodies of the auth routes. **MEASURED.** This package hands a caller's
  * fields to the backend unchanged, so these are the names a caller must use — a
@@ -108,13 +134,18 @@ export const AUTH = {
  *
  * | route | body | answer |
  * |---|---|---|
- * | login | `{ username, password }` | `200 { token, expires_at, account }` + the session cookie · `200 { status: 'totp_required', challenge_token }` · `401` wrong credential · `403 Email Not Verified` |
+ * | login | `{ username, password }` | `200 { expires_at, account }` + the session cookie · `200 { status: 'totp_required', challenge_token }` · `401` wrong credential · `403 Email Not Verified` |
  * | 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 } }` · `401` |
+ * | me | none | `200 { account: { uuid, username, handle }, roles, workspace: { unit_uuid, handle }, capabilities: { admin_app } }` · `401` |
+ *
+ * ⭐ **The session is the cookie, and only the cookie.** A site's backend answers a
+ * sign-in with no `token` (since 2026-10-10, MEASURED by backend; `token` was in the
+ * reply until then), and this package never read one: it signs in, then asks
+ * `/auth/me` who the viewer is.
  */
 export const AUTH_BODY = {
   login: ['username', 'password'],
@@ -124,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',
@@ -135,7 +216,13 @@ export const TOTP = {
  * The viewer, as `/auth/me` answers. **MEASURED.**
  *
  * `roles` is a list of `{ role, scope_unit_id }` — `role` one of `system_admin`,
- * `unit_admin`, `content_editor`, `user`. An ordinary member holds none: `[]`.
+ * `unit_admin`, `content_editor`, `user`. ⭐ **They describe the session, not the
+ * account.** On a site's `backend` service a session signed in on the site holds no
+ * `system_admin` and no `unit_admin` of the home org — the operator's neither — so
+ * `roles` never name an administrator there: a site runs third-party code with its
+ * member's session, and a bug in that code must not act as one. An ordinary member
+ * holds none: `[]`. *(Since 2026-10-10, MEASURED by backend; until then the operator's
+ * session on a site held `system_admin`.)*
  *
  * `workspace` is `{ unit_uuid, handle }` — **the workspace the request works in**. This
  * package's requests name none, and on a site's `backend` service such a request lands in
@@ -147,14 +234,26 @@ export const TOTP = {
  * function the route serializes, 2026-09-23.)*
  *
  * ⛔ **Neither is an operator signal.** Every member of a site's service works in the
- * same home org, so it reads the same for the operator and for someone who signed up a
- * minute ago. The operator holds `system_admin`. Better than either: ask about the
- * thing — a single-entity read carries `can_edit`, the write gate's own answer.
+ * same home org, so `workspace` reads the same for the operator and for someone who
+ * signed up a minute ago, and on a site `roles` name no administrator. Ask about the
+ * thing instead — a single-entity read carries `can_edit`, the write gate's own answer
+ * for this session.
+ *
+ * `capabilities.admin_app` is the one fact here about the ACCOUNT rather than the
+ * session: `true` when the backend's administration admits it — the operator, and
+ * whoever else administers the service. The viewer carries it as `adminApp`, and the
+ * package then offers the Admin link (`AUTH.memberHandoff`). It decides what to OFFER,
+ * never what is allowed on the site, where the session acts as a member whatever the
+ * account holds. `true` or `false` for every signed-in caller, at the same path as on
+ * `/session/bootstrap` (MEASURED by backend, 2026-10-10); anything else reads as
+ * `false`.
  */
 export const VIEWER = {
   account: 'account',
   roles: 'roles',
   workspace: 'workspace',
+  capabilities: 'capabilities',
+  adminApp: 'admin_app',
 }
 
 /**
@@ -194,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
@@ -218,17 +318,19 @@ export const PARAM = {
   maxDepth: 'max_depth',
   readback: 'readback',
   revRefPolicy: 'rev_ref_policy',
+  token: 'token',
 }
 
 /**
  * The list's `scope`. Default `accessible` — everything the viewer may read; `mine`
  * — only what the viewer owns.
  *
- * What a member of a site may read: their own entities, and what was shared with
- * them. Other members' entities are private to their owners unless the site's
- * service was set up to let members read each other's. The operator reads
- * everything. *(A site's service let every member read every other member's
- * entities until 2026-09-18 — measured, and changed on the backend.)*
+ * What a session signed in on a site may read — any member's, the operator's
+ * included (`VIEWER`): its own entities, and what was shared with it. Other members'
+ * entities are private to their owners unless the site's service was set up to let
+ * members read each other's. *(A site's service let every member read every other
+ * member's entities until 2026-09-18, and the operator's session read everything until
+ * 2026-10-10 — both measured, and changed on the backend.)*
  */
 export const SCOPE = {
   mine: 'mine',
@@ -342,9 +444,9 @@ export const CREATE = {
  * paging; a page that came back full is the only sign there may be more.
  *
  * `via` names why the viewer can read the row — `owner`, `grant`, `rbac`,
- * `unit_member`, `entitlement`; treat an unknown value as "no opinion". The
- * operator's own rows are `owner` and the rest `rbac` — since 2026-09-18; an older
- * backend answers `rbac` on the operator's own rows too. ⚠️ An empty list means
+ * `unit_member`, `entitlement`; treat an unknown value as "no opinion". A session's
+ * own rows are `owner` — the operator's too. *(Until 2026-10-10 the operator's session
+ * on a site read the rest as `rbac`, through `system_admin`.)* ⚠️ An empty list means
  * empty: a lapsed session is a `401`, never `200 []`.
  */
 export const LIST = {
@@ -424,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 |
  * |---|---|
@@ -435,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',
+  },
+]