@uniweb/api 1.1.1 → 1.2.0

package/README.md

@@ -52,13 +52,16 @@ function Account() {
 ```
 
 `viewer` is flat — `viewer.uuid`, `viewer.username`, `viewer.handle`, and `viewer.roles`,
-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.
+a list of `{ role, scope_unit_id }`. ⭐ **Roles describe the session, and on a site a
+session holds the account's roles as a reader's until it is elevated.** A site runs
+your foundation's code with the signed-in member's session, so an administrator signed
+in on it reads what their role reaches — the operator reads every member's content —
+and changes nothing through the role until they confirm it is them (*Acting as an
+administrator*, below). Their own content they edit, delete and share as always. An
+ordinary member holds no role (`[]`). `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
@@ -146,6 +149,42 @@ function Invitations() {
 - ⭐ Draw it wherever a signed-in member lands, not only after an `?offer=` link: an
   invitation sent to an account comes with no link to follow.
 
+**Acting as an administrator** — an administrator on the site reads what their role
+reaches; to change something through it — remove a member's post, grade a submission —
+they confirm it is them, and for a while the session acts through the role.
+`useElevation()` offers it:
+
+```jsx
+import { useElevation } from '@uniweb/api'
+
+function AdminMode() {
+  const { available, elevated, until, elevate, lower, error } = useElevation()
+  if (!available) return null
+  if (elevated) {
+    return <p>Acting as administrator until {new Date(until).toLocaleTimeString()}. <button onClick={lower}>Stop</button></p>
+  }
+  return <ConfirmItsYou onSubmit={(password, code) => elevate({ password, code })} refused={error?.kind === 'auth'} />
+}
+```
+
+- `available` — the account holds a role that does more than read. Offer it only then.
+- `elevate({ password, code })` — the account's password again, and `code` when it has a
+  second factor. Nothing tells you whether it has one, so offer the field to whoever
+  might. A wrong password or code is `error.kind === 'auth'`, one answer for both.
+- It lasts as long as the backend decides; `until` says when it ends. `elevated` turns
+  false by itself then, and the session is asked again. Elevating again starts the time
+  again; nothing extends it on its own. `lower()` ends it early.
+- While it lasts, `viewer.roles` names the role, and every record read before is read
+  again — `entity.can_edit` is the record's answer for the session as it is now.
+- `rolesInFull` — draw controls that act through a role from this: true while elevated,
+  and always on a backend that asks for no elevation.
+- An account with no password elevates through its provider:
+  `elevateWithProvider('google')` goes to the provider's sign-in and back to this page.
+  If the identity that comes back is not this account's, `error.extensions.reason` is
+  `'oauth_step_up_not_linked'`.
+
+Elevating does not open the backend's administration — the Admin link does.
+
 **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
@@ -160,8 +199,8 @@ const { adminHref } = useSession()
 ⛔ **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.
+administrator's session acts through their role only while elevated, and administering
+the backend happens at the other end of the link.
 
 ## Reading
 
@@ -178,10 +217,10 @@ 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.** 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.
+**Whose records.** Everyone signed in on the site reads their own entities, what was
+shared with them, and what a role of theirs reaches — the operator's reaches every
+member's; 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
 carries no items — read the entity for those. `hasMore` is true when a page came back
@@ -306,11 +345,12 @@ production, and nothing in your site's configuration changes between the two.
 refusals, for every route this package uses. It enforces what your schemas declare —
 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). The mail the backend would send — a sign-up's
+Everyone signed in reads and writes their own entities, and a member 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). The
+operator, as on a real site, reads every member's entities and changes them only once
+elevated, with its password, for fifteen minutes. 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:
@@ -332,7 +372,8 @@ npx uniweb-api-mock --port 8787 --site http://localhost:3000
 
 `@uniweb/api/client` carries the same operations as plain functions and imports no
 React: `probeSession`, `signIn`, `listEntities`, `readEntity`, `writeItems`,
-`createEntity`, `deleteEntity`, `adminHref`, for the links the backend mails,
+`createEntity`, `deleteEntity`, `adminHref`, for elevation, `elevate`, `lower`,
+`elevateWithProvider`, `isElevated` and `rolesInFull`, for the links the backend mails,
 `mailedLink`, `verifyEmail`, `claimOffer` and `forgetMailedLink`, and for invitations,
 `listInvitations`, `acceptInvitation` and `declineInvitation`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "1.1.1",
+  "version": "1.2.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": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.1.0"
+    "@uniweb/core": "~1.2.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -19,6 +19,7 @@ import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA
 import { Ledger } from './ledger.js'
 import { verifyEmailWith, claimOfferWith } from './mailed-links.js'
 import { listInvitationsWith, acceptInvitationWith, declineInvitationWith } from './invitations.js'
+import { viewerElevation, watchLapse, elevateWith, lowerWith, elevateWithProviderOf } from './elevation.js'
 
 /**
  * The site service this package reads its base from — the only name it owns.
@@ -219,6 +220,8 @@ export class ApiClient {
     const error = next.error ?? null
     if (cur.status === next.status && cur.viewer === viewer && cur.error === error) return cur
     this._session = Object.freeze({ status: next.status, viewer, error })
+    // An elevated session is asked again when its elevation runs out (`./elevation.js`).
+    watchLapse(this)
     for (const fn of this._listeners) fn()
     return this._session
   }
@@ -356,6 +359,7 @@ export class ApiClient {
       roles: Array.isArray(me?.roles) ? me.roles : [],
       workspace: viewerWorkspace(me?.workspace),
       adminApp: me?.[VIEWER.capabilities]?.[VIEWER.adminApp] === true,
+      elevation: viewerElevation(me?.[VIEWER.elevation]),
     })
     if (this._session.viewer && this._session.viewer.uuid !== viewer.uuid) this.forgetViewer()
     return this.setSession({ status: 'authenticated', viewer, error: null })
@@ -427,6 +431,35 @@ export class ApiClient {
     }
   }
 
+  /**
+   * Elevate the session — `{ password, code? }` — so it acts through the account's roles
+   * for a while. Answers `{ until }`. A refused credential throws `kind: 'auth'`, one
+   * answer for a wrong password or code (`./elevation.js`).
+   *
+   * @param {{ password: string, code?: string }} credentials
+   * @returns {Promise<{ until: string|null }>}
+   */
+  elevate(credentials) {
+    return elevateWith(this, credentials)
+  }
+
+  /** Lower the session before its time runs out. */
+  lower() {
+    return lowerWith(this)
+  }
+
+  /**
+   * Elevate through the account's provider — a navigation to its sign-in, which comes
+   * back to the page elevated. For an account with no password.
+   *
+   * @param {string} provider
+   * @param {{ returnTo?: string }} [options]
+   * @returns {string|null} the address navigated to
+   */
+  elevateWithProvider(provider, options) {
+    return elevateWithProviderOf(this, provider, options)
+  }
+
   /**
    * Sign up — `{ username, email, password }`, passed through unchanged.
    *
@@ -688,9 +721,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 — 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.
+   * read — signed in on a site, their own entities, what was shared with them, and what
+   * a role of theirs reaches, elevated or not: the operator's, every member's (`SCOPE`
+   * in `./wire.js`). `mine` is only what the viewer owns.
    *
    * ## Paging, as far as it can honestly be absorbed
    *
@@ -1023,6 +1056,12 @@ export const signIn = (credentials) => required().signIn(credentials)
 export const completeChallenge = (code) => required().completeChallenge(code)
 /** @see ApiClient#signOut */
 export const signOut = () => required().signOut()
+/** @see ApiClient#elevate — on any instance, an older copy's too */
+export const elevate = (credentials) => elevateWith(required(), credentials)
+/** @see ApiClient#lower — on any instance, an older copy's too */
+export const lower = () => lowerWith(required())
+/** @see ApiClient#elevateWithProvider — on any instance, an older copy's too */
+export const elevateWithProvider = (provider, options) => elevateWithProviderOf(required(), provider, options)
 /** @see ApiClient#signUp */
 export const signUp = (fields) => required().signUp(fields)
 /** @see ApiClient#requestPasswordReset */
@@ -1053,5 +1092,6 @@ export const deleteEntity = (args) => required().deleteEntity(args)
 export const adminHref = () => adminHrefOf(getClient())
 
 export { mailedLink, forgetMailedLink } from './mailed-links.js'
+export { isElevated, rolesInFull, elevationReturn } from './elevation.js'
 export { ApiError, kindOf } from './errors.js'
 export { Ledger } from './ledger.js'

package/src/elevation.js

@@ -0,0 +1,268 @@
+/**
+ * Elevation — a site's session reads through its roles until it is elevated.
+ *
+ * On a site's backend, a session signed in on the site holds each of the account's roles
+ * as a reader until it is elevated: an administrator reads what their role reaches, and
+ * changes nothing through it. Their own content they edit, delete and share as always.
+ * To act through the role — remove a member's post, grade a submission — the session
+ * elevates, with the password again (and the second factor, when the account has one),
+ * for a while the backend decides (`ELEVATION` in `./wire.js`). No React in this module;
+ * `useElevation` is the hook over it.
+ *
+ * ⭐ **Functions of a client, not methods** — the page's client may have been created by
+ * an older copy of this package (`./mailed-links.js` says why). Everything here reaches
+ * the wire through `request` and keeps its state on the instance.
+ */
+
+import { ApiError } from './errors.js'
+import { composeUrl } from './http.js'
+import { AUTH, ELEVATION } from './wire.js'
+
+/**
+ * `/auth/me`'s `elevation` as the viewer carries it — `{ available, until }`, `until` an
+ * ISO time or `null` — or `null` when the backend sends none: a backend no site reaches,
+ * whose roles answer in full.
+ *
+ * @param {*} raw
+ * @returns {{ available: boolean, until: string|null } | null}
+ */
+export function viewerElevation(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  const until = raw[ELEVATION.until]
+  return Object.freeze({
+    available: raw[ELEVATION.available] === true,
+    until: typeof until === 'string' && until ? until : null,
+  })
+}
+
+/**
+ * Whether a viewer's session is elevated — `until` still ahead, by this clock.
+ *
+ * @param {object|null} viewer - `useSession().viewer`
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function isElevated(viewer, now = Date.now()) {
+  const until = viewer?.elevation?.until
+  return typeof until === 'string' && Date.parse(until) > now
+}
+
+/**
+ * Whether a viewer's session acts through its roles now: elevated — or on a backend that
+ * asks for no elevation, whose `/auth/me` carries none and whose roles always answer in
+ * full. False for nobody signed in, and for a viewer read by a copy of this package
+ * older than elevation, which cannot say.
+ *
+ * @param {object|null} viewer
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function rolesInFull(viewer, now = Date.now()) {
+  if (!viewer || !('elevation' in viewer)) return false
+  return viewer.elevation === null || isElevated(viewer, now)
+}
+
+/** Whether a cached read is one entity's — whose `can_edit` is the session's answer. */
+const isEntityRead = (spec) => spec?.uuid != null
+
+/**
+ * Ask the backend again who the viewer is, after anything already asking: a probe that
+ * left before the change would answer for the session as it was.
+ */
+async function reprobe(client) {
+  const earlier = client._pending
+  if (earlier) await earlier.catch(() => {})
+  return client.refresh?.()
+}
+
+/**
+ * Elevate the session — the password again, and `code` when the account has a second
+ * factor. Answers `{ until }`, an ISO time. The session is asked again, so `roles` name
+ * what it holds now, and every entity read is read again, since what the viewer may do
+ * to an entity is its own answer (`can_edit`).
+ *
+ * ⚠️ **A wrong password, a wrong code, a missing code and a session that has ended are
+ * one answer, `401`** (`kind: 'auth'`). The session is asked again before the refusal is
+ * thrown, so a session that ended shows as signed out, and one still signed in means
+ * the credential was refused. Nothing on the wire says whether the account has a second
+ * factor: offer the code field to whoever might have one.
+ *
+ * @param {object} client
+ * @param {{ password: string, code?: string }} credentials
+ * @returns {Promise<{ until: string|null }>}
+ * @throws {ApiError} `auth` — refused, as above · `invalid` — no password given
+ */
+export async function elevateWith(client, { password, code } = {}) {
+  if (!password) {
+    throw ApiError.invalid(
+      'No Password',
+      'elevate needs the account’s password — an account with none elevates through its provider (elevateWithProvider)',
+    )
+  }
+  const body = { [ELEVATION.password]: password }
+  if (code != null && code !== '') body[ELEVATION.code] = code
+  let answer
+  try {
+    answer = await client.request('POST', AUTH.elevate, { body, onUnauthorized: 'ignore' })
+  } catch (error) {
+    if (error?.status === 401) await reprobe(client)
+    throw error
+  }
+  client.invalidate?.(isEntityRead)
+  await reprobe(client)
+  return { until: answer?.[ELEVATION.answer] ?? null }
+}
+
+/**
+ * Lower the session before its time runs out. The session is asked again, and every
+ * entity read is read again.
+ *
+ * @param {object} client
+ * @returns {Promise<{ until: null }>}
+ * @throws {ApiError} `auth` — nobody signed in
+ */
+export async function lowerWith(client) {
+  await client.request('DELETE', AUTH.elevate)
+  client.invalidate?.(isEntityRead)
+  await reprobe(client)
+  return { until: null }
+}
+
+/** Marks a `state` as ours, so its echo can be taken off the address bar on the way back. */
+const STATE_PREFIX = 'uw-elevate-'
+
+/** The page's own address, without its query or fragment — where the provider returns to. */
+function pageAddress() {
+  const location = globalThis.location
+  if (!location?.origin || location.origin === 'null') return null
+  return `${location.origin}${location.pathname}`
+}
+
+/**
+ * The provider's elevation for this attempt — for an account with no password — or
+ * `null`: no backend, nobody signed in, no provider named, or no page to return to.
+ *
+ * ⛔ **A navigation, never a fetch**, and one address per attempt: each carries a fresh
+ * `state`, so make it when the viewer asks, never at render.
+ *
+ * @param {object} client
+ * @param {string} provider - the provider's id, as the backend names it (`google`)
+ * @param {{ returnTo?: string }} [options] - the absolute address to come back to; the
+ *   page the viewer is on, without its query or fragment, by default
+ * @returns {string|null}
+ */
+export function elevationAddressOf(client, provider, { returnTo } = {}) {
+  const base = client?.base ?? null
+  if (base === null || !provider || client.session?.status !== 'authenticated') return null
+  const redirect = returnTo || pageAddress()
+  if (!redirect) return null
+  const state = `${STATE_PREFIX}${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`
+  return composeUrl(base, ELEVATION.byProvider(provider), { [ELEVATION.redirect]: redirect, [ELEVATION.state]: state })
+}
+
+/**
+ * Elevate through the account's provider — go to its sign-in, and come back elevated.
+ * Nothing happens outside a browser, or when there is no address to go to
+ * (`elevationAddressOf`).
+ *
+ * @param {object} client
+ * @param {string} provider
+ * @param {{ returnTo?: string }} [options]
+ * @returns {string|null} the address navigated to
+ */
+export function elevateWithProviderOf(client, provider, options) {
+  const address = elevationAddressOf(client, provider, options)
+  if (address && typeof globalThis.location?.assign === 'function') globalThis.location.assign(address)
+  return address
+}
+
+/**
+ * What a provider's elevation came back with, on the page it returned to:
+ * `{ ok: true }`, `{ ok: false, error: 'oauth_step_up_not_linked' }` — the identity that
+ * came back is not this account's — or `null` when the URL carries neither.
+ *
+ * @param {string} [search] - a query string; the page's own by default
+ * @returns {{ ok: boolean, error?: string } | null}
+ */
+export function elevationReturn(search = globalThis.location?.search ?? '') {
+  let params
+  try {
+    params = new URLSearchParams(search)
+  } catch {
+    return null
+  }
+  if (params.get(ELEVATION.returned) === ELEVATION.ok) return Object.freeze({ ok: true })
+  if (params.get(ELEVATION.error) === ELEVATION.notLinked) return Object.freeze({ ok: false, error: ELEVATION.notLinked })
+  return null
+}
+
+/**
+ * Take a provider's answer, and our own `state`, off the address bar — `replaceState`,
+ * no navigation. The rest of the URL stays, another `state` or `error` included.
+ */
+export function forgetElevationReturn() {
+  const location = globalThis.location
+  const history = globalThis.history
+  if (!location || typeof history?.replaceState !== 'function') return
+  const params = new URLSearchParams(location.search)
+  let changed = false
+  if (params.get(ELEVATION.returned) === ELEVATION.ok) {
+    params.delete(ELEVATION.returned)
+    changed = true
+  }
+  if (params.get(ELEVATION.error) === ELEVATION.notLinked) {
+    params.delete(ELEVATION.error)
+    changed = true
+  }
+  if (params.get(ELEVATION.state)?.startsWith(STATE_PREFIX)) {
+    params.delete(ELEVATION.state)
+    changed = true
+  }
+  if (!changed) return
+  const query = params.toString()
+  history.replaceState(history.state, '', `${location.pathname}${query ? `?${query}` : ''}${location.hash}`)
+}
+
+/**
+ * A provider's answer, read ONCE per page and taken off the address bar — the same
+ * answer to every component that asks.
+ *
+ * @param {object} client
+ * @returns {{ ok: boolean, error?: string } | null}
+ */
+export function takeElevationReturn(client) {
+  if (!client) return null
+  if (client._elevationReturn === undefined) {
+    client._elevationReturn = elevationReturn()
+    if (client._elevationReturn) forgetElevationReturn()
+  }
+  return client._elevationReturn
+}
+
+/**
+ * Ask the backend again when the session's elevation runs out, so `roles` stop naming
+ * what it no longer holds — one timer per client, armed for the `until` the session
+ * carries, and let go when that changes or the session ends.
+ *
+ * ⚠️ `until` is the backend's clock and the timer is this one's. Behind, the probe comes
+ * late. Ahead, the probe finds the session still elevated at an `until` this clock has
+ * passed, and arms nothing: the page's next probe tells.
+ *
+ * @param {object} client
+ */
+export function watchLapse(client) {
+  const until = client?.session?.viewer?.elevation?.until ?? null
+  if (client._lapse && client._lapse.until === until) return
+  if (client._lapse) clearTimeout(client._lapse.timer)
+  client._lapse = null
+  if (!until || typeof setTimeout !== 'function') return
+  const wait = Date.parse(until) - Date.now()
+  if (!(wait > 0)) return
+  // A second past `until`, and never longer than a timer can wait.
+  const timer = setTimeout(() => {
+    client._lapse = null
+    client.refresh?.()
+  }, Math.min(wait + 1000, 2 ** 31 - 1))
+  timer?.unref?.()
+  client._lapse = { until, timer }
+}

package/src/hooks/useElevation.js

@@ -0,0 +1,147 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+import { ApiError } from '../errors.js'
+import { elevateWith, lowerWith, elevateWithProviderOf, takeElevationReturn, rolesInFull } from '../elevation.js'
+import { useAction } from './useAction.js'
+
+const NONE = Object.freeze({ status: 'anonymous', viewer: null, error: null })
+const noSubscribe = () => () => {}
+const noSnapshot = () => NONE
+
+/**
+ * Elevation — whether the viewer's session acts through their roles, and the calls that
+ * change it.
+ *
+ * On a site's backend a session holds each of the account's roles as a reader until it
+ * is elevated: an administrator reads what their role reaches and changes nothing
+ * through it — their own content they edit, delete and share as always. To act through
+ * the role, they confirm it is them, and the session is elevated for a while.
+ *
+ * ```jsx
+ * const { available, elevated, until, elevate, lower, status, error } = useElevation()
+ * if (available && !elevated) return <ConfirmPassword onSubmit={(password, code) => elevate({ password, code })} />
+ * if (elevated) return <p>Acting as administrator until {new Date(until).toLocaleTimeString()}. <button onClick={lower}>Stop</button></p>
+ * ```
+ *
+ * - **`available`** — the account holds a role that answers more than reading: offer
+ *   elevation only then.
+ * - **`elevated`** — true while it lasts; `until` is when it ends, an ISO time. It turns
+ *   false by itself when the time passes, and the session is asked again then. Elevating
+ *   again starts the time again; nothing extends it on its own.
+ * - **`rolesInFull`** — whether the session acts through its roles now: elevated, or on a
+ *   backend that never asks for it. Draw controls that act through a role from this, and
+ *   ask each entity what the viewer may do to it — `useEntity`'s `entity.can_edit`, read
+ *   again after every change here.
+ * - **`elevate({ password, code })`** — `code` when the account has a second factor.
+ *   Nothing says whether it has one, so offer the field to whoever might. A refusal is
+ *   `kind: 'auth'`, one answer for a wrong password or code; a session that has ended
+ *   shows as signed out first.
+ * - **`elevateWithProvider(provider)`** — for an account with no password: a navigation
+ *   to the provider's sign-in, which comes back to this page. If the identity that comes
+ *   back is not this account's, `error` says so — `kind: 'auth'`,
+ *   `error.extensions.reason === 'oauth_step_up_not_linked'`.
+ * - **`lower()`** — ends it early.
+ *
+ * Elevating does not open the backend's administration — the Admin link does
+ * (`useSession().adminHref`). On a site with no backend, or with nobody signed in,
+ * nothing is available.
+ *
+ * @returns {{
+ *   available: boolean,
+ *   elevated: boolean,
+ *   until: string | null,
+ *   rolesInFull: boolean,
+ *   elevate: (credentials: { password: string, code?: string }) => Promise<{ until: string|null }>,
+ *   elevateWithProvider: (provider: string, options?: { returnTo?: string }) => string | null,
+ *   lower: () => Promise<{ until: null }>,
+ *   status: 'idle' | 'submitting' | 'success' | 'error',
+ *   error: Error | null,
+ *   reset: () => void,
+ * }}
+ */
+export function useElevation() {
+  const client = getClient()
+  const session = useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+  const viewer = session.status === 'authenticated' ? session.viewer : null
+  const elevation = viewer?.elevation ?? null
+  const until = elevation?.until ?? null
+
+  // Ask who the viewer is, as `useSession` does — this hook may be the only one asking.
+  useEffect(() => {
+    if (client && client.enabled) client.ensureSession()
+  }, [client])
+
+  // Render again when the elevation runs out, so `elevated` turns false on time.
+  const [, setTick] = useState(0)
+  useEffect(() => {
+    if (!until) return undefined
+    const wait = Date.parse(until) - Date.now()
+    if (!(wait > 0)) return undefined
+    const timer = setTimeout(() => setTick((n) => n + 1), Math.min(wait + 50, 2 ** 31 - 1))
+    return () => clearTimeout(timer)
+  }, [until])
+
+  const { run, status, error, reset } = useAction(
+    useCallback(
+      async (step, arg) => {
+        if (!client) throw ApiError.disabled()
+        return step === 'lower' ? lowerWith(client) : elevateWith(client, arg)
+      },
+      [client],
+    ),
+  )
+
+  // A provider's elevation returns to the page: read once, in an effect — the URL is the
+  // browser's, never the server render's. Coming back elevated needs nothing here: the
+  // session says so.
+  const [returned, setReturned] = useState(null)
+  useEffect(() => {
+    const answer = takeElevationReturn(client)
+    if (answer && !answer.ok) {
+      setReturned(
+        new ApiError({
+          status: 0,
+          title: 'Not Linked',
+          detail: 'the identity the provider returned is not this account’s',
+          kind: 'auth',
+          extensions: { reason: answer.error },
+        }),
+      )
+    }
+  }, [client])
+
+  const elevate = useCallback((credentials) => run('elevate', credentials), [run])
+  const lower = useCallback(() => run('lower'), [run])
+  const elevateWithProvider = useCallback(
+    (provider, options) => {
+      setReturned(null)
+      return client ? elevateWithProviderOf(client, provider, options) : null
+    },
+    [client],
+  )
+  const clear = useCallback(() => {
+    setReturned(null)
+    reset()
+  }, [reset])
+
+  const elevated = typeof until === 'string' && Date.parse(until) > Date.now()
+
+  return {
+    available: elevation?.available === true,
+    elevated,
+    until: elevated ? until : null,
+    rolesInFull: rolesInFull(viewer),
+    elevate,
+    elevateWithProvider,
+    lower,
+    status,
+    error: error ?? (status === 'idle' ? returned : null),
+    reset: clear,
+  }
+}
+
+export default useElevation

package/src/hooks/useRecords.js

@@ -35,8 +35,8 @@ const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, ha
  * `hasMore` is true when the page came back full.
  *
  * 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.
+ * own entities, what was shared with them, and what a role of theirs reaches: the
+ * operator's, every member's. `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
  * is now looking, and a write through `useEntityWriter` drops it.

package/src/hooks/useSession.js

@@ -15,6 +15,11 @@ const noop = async () => NONE
  * affordance on false. `error` is set when the backend could not be asked;
  * `refresh()` asks again.
  *
+ * `viewer.roles` describe the session, not the account: on a site's backend an
+ * administrator's session holds its roles as a reader until it is elevated, and
+ * `viewer.elevation` — `{ available, until }`, or `null` on a backend that never asks —
+ * says whether it can be, and until when it is. `useElevation` reads it and elevates.
+ *
  * `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`).

package/src/index.js

@@ -18,6 +18,11 @@ export {
   signIn,
   completeChallenge,
   signOut,
+  elevate,
+  lower,
+  elevateWithProvider,
+  isElevated,
+  rolesInFull,
   signUp,
   requestPasswordReset,
   confirmPasswordReset,
@@ -39,6 +44,7 @@ export {
 } from './client.js'
 
 export { useSession } from './hooks/useSession.js'
+export { useElevation } from './hooks/useElevation.js'
 export { useSignIn } from './hooks/useSignIn.js'
 export { useSignUp } from './hooks/useSignUp.js'
 export { usePasswordReset } from './hooks/usePasswordReset.js'

package/src/mock/index.js

@@ -1,4 +1,4 @@
-import { AUTH, ENTITIES, MODELS, OFFERS, INVITATIONS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL } from '../wire.js'
+import { AUTH, ENTITIES, MODELS, OFFERS, INVITATIONS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS, HANDOFF_REFUSAL, ELEVATION } from '../wire.js'
 import { MockStore, isUuid, refuse } from './store.js'
 import { DEFAULT_SEED } from './seed.js'
 
@@ -255,8 +255,21 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/_api', signe
         const token = q.get('token') || ''
         return token ? answer(store.verify(token)) : badRequest('verify requires `token`')
       }
+      if (path.startsWith(`${AUTH.elevate}/`) && method === 'GET') {
+        // The provider's elevation — a navigation. The mock has no sign-in providers.
+        return problem({ status: 404, title: 'Not Found', detail: 'the mock has no sign-in providers — elevate with the password' })
+      }
       const bad = unexpected(q, [])
       if (bad) return bad
+      if (path === AUTH.elevate && method === 'POST') {
+        if (!store.account) return unauthorized()
+        const b = await body(request)
+        return fields(b, [ELEVATION.password], '{"password": ..., "code": ...}') ?? answer(store.elevate(b))
+      }
+      if (path === AUTH.elevate && method === 'DELETE') {
+        if (!store.account) return unauthorized()
+        return answer(store.lower())
+      }
       if (path === AUTH.me && method === 'GET') {
         const viewer = store.viewer()
         return viewer ? json(200, viewer) : unauthorized()

package/src/mock/store.js

@@ -20,11 +20,14 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  *   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 — 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`.
+ *   seed gives it, and holds `system_admin` over the whole service. ⛔ **Signed in on
+ *   the site, it holds that role as a reader until it is elevated**: it reads every
+ *   member's entities (`via: rbac`) and changes none of them — a site runs third-party
+ *   code with its member's session. Elevated, with its password again, its role answers
+ *   in full until the window closes (`ELEVATION_WINDOW`) or it lowers it. *(Stated by
+ *   the backend, 2026-10-14. From 2026-10-10 the operator's session held a member's
+ *   rights only, and before that `system_admin` in full.)* A seeded account is the
+ *   operator with `operator: true`.
  * - **An offer binds when it is claimed, or when its address is confirmed** — and
  *   then its token answers `404`, as an unknown one does (backend, 2026-10-11). What
  *   it binds: its invitations, each waiting for the account's answer, to an
@@ -36,8 +39,10 @@ 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), a Model whose creation is closed, nested sections, second factors,
- * reference fields, password rules,
+ * same read), a Model whose creation is closed, nested sections, second factors —
+ * at a sign-in or an elevation, where a `code` is accepted and not checked —
+ * sign-in providers, and so no elevation through one, roles other than the operator's,
+ * step-up, reference fields, password rules,
  * an offer's grants (a count, sharing nothing), what joining an organization
  * gives — accepting an invitation answers, and opens nothing to read — and an
  * organization withdrawing an invitation.
@@ -60,6 +65,15 @@ export const HOME_ORG = Object.freeze({
   handle: 'home',
 })
 
+/**
+ * How long an elevation lasts — the backend's window, 15 minutes on 2026-10-14, as the
+ * backend states it. The client never assumes it; it reads `until`.
+ */
+export const ELEVATION_WINDOW = 15 * 60 * 1000
+
+/** The operator's role, as `/auth/me` names it — MEASURED 2026-09-18. */
+const OPERATOR_ROLE = Object.freeze({ role: 'system_admin', scope_unit_id: null })
+
 /** The gap between neighbouring items' order numbers, as the backend spaces them. */
 const GAP = 1_000_000
 
@@ -209,7 +223,7 @@ export class MockStore {
         const known = this.accounts.map((a) => a.username).join(', ') || '(none)'
         throw new Error(`[uniweb/api mock] signedInAs: '${signedInAs}' is not a seeded account. Seeded: ${known}`)
       }
-      this.session = { account }
+      this.session = { account, elevatedUntil: null }
     }
   }
 
@@ -234,24 +248,52 @@ export class MockStore {
     return this.session?.account ?? null
   }
 
+  /** Whether the session is elevated now — its window still open. */
+  get elevated() {
+    const until = this.session?.elevatedUntil
+    return until != null && Date.parse(until) > Date.now()
+  }
+
   /**
-   * 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.
+   * The viewer, in the shape `/auth/me` answers. `roles` are the session's: the
+   * operator's `system_admin`, held as `content_reader` at the same scope until the
+   * session is elevated; a member's, none. `elevation` says whether it can be — the
+   * operator's yes — and until when it is. 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
+    const elevated = this.elevated
+    const roles = account.operator ? [elevated ? { ...OPERATOR_ROLE } : { ...OPERATOR_ROLE, role: 'content_reader' }] : []
     return {
       account: this.identity(account),
-      roles: [],
+      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 },
+      elevation: { available: account.operator === true, ...(elevated ? { until: this.session.elevatedUntil } : {}) },
     }
   }
 
+  /**
+   * `POST /auth/elevate` — the password again, and the window opens: `elevated_until`.
+   * A wrong password is `401`, as the backend's one answer for a wrong password or code.
+   * An account with nothing to elevate is answered the same way — what the backend does
+   * then is not measured, and it changes nothing the account may do.
+   */
+  elevate({ password }) {
+    if (!this.account || this.account.password !== password) return refuse(401, 'Unauthorized')
+    this.session.elevatedUntil = new Date(Date.now() + ELEVATION_WINDOW).toISOString()
+    return { body: { elevated_until: this.session.elevatedUntil } }
+  }
+
+  /** `DELETE /auth/elevate` — the window closes now. */
+  lower() {
+    this.session.elevatedUntil = null
+    return { body: { elevated_until: null } }
+  }
+
   identity(account) {
     return { uuid: account.uuid, username: account.username, handle: account.handle }
   }
@@ -260,7 +302,7 @@ export class MockStore {
     const account = this.accounts.find((a) => a.username === username)
     if (!account || account.password !== password) return refuse(401, 'Unauthorized')
     if (!account.verified) return refuse(403, PROBLEM.notVerified, 'verify your email address before signing in')
-    this.session = { account }
+    this.session = { account, elevatedUntil: null }
     const expires = new Date(Date.now() + 30 * 24 * 3600 * 1000).toISOString()
     // No `token`: a site's backend answers a sign-in with the session cookie alone.
     return { body: { expires_at: expires, account: this.identity(account) } }
@@ -599,30 +641,35 @@ export class MockStore {
   }
 
   /**
-   * 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.
+   * The owner — or the operator, whose role reads everything, elevated or not — or any
+   * member, when the service lets members read each other's.
    */
   mayRead(entity) {
     const me = this.account
-    return !!me && (entity.owner_id === me.id || this.floorFor(entity) != null)
+    return !!me && (entity.owner_id === me.id || me.operator === true || this.floorFor(entity) != null)
   }
 
+  /**
+   * The owner — or the operator while its session is elevated — or any member, when the
+   * service lets members edit each other's.
+   */
   mayEdit(entity) {
     const me = this.account
-    return !!me && (entity.owner_id === me.id || this.floorFor(entity) === 'edit')
+    return !!me && (entity.owner_id === me.id || (me.operator === true && this.elevated) || 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`. 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`.)*
+   * are `owner`, the operator's too; the rest the operator reads through its role,
+   * `rbac`; a member reads the rest by the service's floor. *(From 2026-10-10 to
+   * 2026-10-14 the operator's session read nothing of a member's, and before that the
+   * rest as `rbac`, through `system_admin`.)*
    */
   via(entity) {
     const me = this.account
     if (entity.owner_id === me?.id) return 'owner'
+    if (me?.operator === true) return 'rbac'
     return 'unit_member'
   }
 

package/src/wire.js

@@ -121,6 +121,10 @@ export const AUTH = {
    * `detail`. **MEASURED** by backend, 2026-10-10.
    */
   memberHandoff: '/auth/member-handoff',
+  /**
+   * `POST /auth/elevate` elevates a site's session; `DELETE` lowers it (`ELEVATION`).
+   */
+  elevate: '/auth/elevate',
 }
 
 /**
@@ -148,7 +152,8 @@ export const HANDOFF_REFUSAL = Object.freeze({
  * | reset request | `{ email }` | `202 { status: 'reset_requested' }` whether or not the address is known |
  * | 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` |
+ * | me | none | `200 { account: { uuid, username, handle }, roles, workspace: { unit_uuid, handle }, capabilities: { admin_app }, elevation? }` · `401` |
+ * | elevate | `{ password, code? }` | `200 { elevated_until }` · `401`, one answer for a wrong password or code (`ELEVATION`) |
  *
  * ⭐ **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
@@ -161,6 +166,54 @@ export const AUTH_BODY = {
   register: ['username', 'email', 'password'],
   resetRequest: ['email'],
   resetConfirm: ['token', 'new_password', 'code?'],
+  elevate: ['password', 'code?'],
+}
+
+/**
+ * Elevation. **Stated by the backend, 2026-10-14, and measured by its own end-to-end
+ * test; not yet measured here.**
+ *
+ * On a site's backend, a session signed in on the site holds each of the account's
+ * roles as `content_reader`, at the same scope, until it is ELEVATED: it reads wherever
+ * a role reached and changes nothing through one. Ownership and grants work as always —
+ * a member edits, deletes and shares their own. To act through a role — an
+ * administrator removing a member's post — the session elevates, for a while.
+ *
+ * | route | body | answer |
+ * |---|---|---|
+ * | `GET /auth/me` | none | carries `elevation: { available, until? }` on such a session — `available` when the account holds a role that answers more than `read`; `until`, an ISO time, while elevated. A backend no site reaches sends no `elevation`: its roles answer in full |
+ * | `POST /auth/elevate` | `{ password, code? }` — `code` when a second factor is live | `200 { elevated_until }`. A wrong password or code is `401`, one answer — and so is no session at all |
+ * | `DELETE /auth/elevate` | none | `200 { elevated_until: null }` |
+ * | `GET /auth/elevate/{provider}/authorize?redirect_uri=&state=` | — | ⛔ **a navigation**, for an account with no password: the provider's sign-in, then back to `redirect_uri` with `?elevate=ok`, or `?error=oauth_step_up_not_linked` when the identity that came back is not the account's |
+ *
+ * - **The window is the backend's** — 15 minutes on 2026-10-14 — and this package never
+ *   assumes it: it reads `until`. Elevating again starts it again; nothing extends it.
+ * - **`roles` on `/auth/me` is what the session holds now** — `content_reader` rows until
+ *   it is elevated, the account's roles while it is (`VIEWER`).
+ * - **Elevating is step-up's proof too** (`PROBLEM.stepUp`).
+ * - **It does not reach the backend's administration**, which takes a site's session as
+ *   a reader, elevated or not. The Admin link does (`AUTH.memberHandoff`).
+ * - **What an elevated session may do to an entity is still the entity's answer** —
+ *   `can_edit` on a read (`READ`), so a read made before elevating is read again.
+ */
+export const ELEVATION = {
+  /** `/auth/me`'s field, and its two keys. */
+  me: 'elevation',
+  available: 'available',
+  until: 'until',
+  /** The answer of `POST` and `DELETE /auth/elevate`: an ISO time, or `null`. */
+  answer: 'elevated_until',
+  password: 'password',
+  code: 'code',
+  /** The provider's elevation — a navigation, never a fetch. */
+  byProvider: (provider) => `/auth/elevate/${segment(provider)}/authorize`,
+  redirect: 'redirect_uri',
+  state: 'state',
+  /** What the provider's elevation returns with: `?elevate=ok`, or `?error=oauth_step_up_not_linked`. */
+  returned: 'elevate',
+  ok: 'ok',
+  error: 'error',
+  notLinked: 'oauth_step_up_not_linked',
 }
 
 /**
@@ -274,13 +327,20 @@ 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`. ⭐ **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`.)*
+ * `unit_admin`, `content_editor`, `content_reader`, `user`; the operator's is
+ * `{ role: 'system_admin', scope_unit_id: null }` (MEASURED 2026-09-18). ⭐ **They
+ * describe the session, not the account.** On a site's `backend` service a session
+ * signed in on the site holds each of the account's roles as `content_reader`, at the
+ * same scope, until it is elevated — so `roles` name an administrator there only while
+ * the session is (`ELEVATION`): a site runs third-party code with its member's session,
+ * and a bug in that code acts with whatever the session holds. An ordinary member holds
+ * none: `[]`. *(Since 2026-10-14, stated by backend. From 2026-10-10 such a session held
+ * no `system_admin` and no `unit_admin` of the home org and every other role whole, and
+ * before that the operator's session on a site held `system_admin`.)*
+ *
+ * `elevation` is `{ available, until? }` on a site's session (`ELEVATION`), absent on a
+ * backend no site reaches. The viewer carries it as `{ available, until }` — `until`
+ * `null` when not elevated — or `null` when absent.
  *
  * `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
@@ -293,16 +353,16 @@ export const TOTP = {
  *
  * ⛔ **Neither is an operator signal.** Every member of a site's service works in the
  * 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.
+ * signed up a minute ago, and on a site `roles` name an administrator only while the
+ * session is elevated. 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
+ * never what is allowed on the site, where the session acts through its roles only
+ * while elevated. `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`.
  */
@@ -312,6 +372,7 @@ export const VIEWER = {
   workspace: 'workspace',
   capabilities: 'capabilities',
   adminApp: 'admin_app',
+  elevation: ELEVATION.me,
 }
 
 /**
@@ -383,12 +444,15 @@ export const PARAM = {
  * The list's `scope`. Default `accessible` — everything the viewer may read; `mine`
  * — only what the viewer owns.
  *
- * 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.)*
+ * What a session signed in on a site may read: its own entities, what was shared with
+ * it, and — for an account that holds a role — whatever that role reaches, elevated or
+ * not (`ELEVATION`): the operator's session reads every member's. An ordinary member's
+ * holds no role, and 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 — measured, and
+ * changed on the backend. The operator's session read everything until 2026-10-10,
+ * nothing of a member's from then, and since 2026-10-14 reads everything again and
+ * changes it only while elevated — stated by the backend.)*
  */
 export const SCOPE = {
   mine: 'mine',
@@ -503,9 +567,14 @@ export const CREATE = {
  *
  * `via` names why the viewer can read the row — `owner`, `grant`, `rbac`,
  * `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 []`.
+ * own rows are `owner` — the operator's too — and the rest the operator's session reads
+ * are `rbac`, through its role, elevated or not. *(From 2026-10-10 to 2026-10-14 the
+ * operator's session on a site read nothing of a member's.)* `rbac` is any
+ * administrative path — a role, and since 2026-10-14 a reader held at a unit over its
+ * people's content, and a reference whose field declares `readable_with` and whose
+ * target the viewer holds at that level *[backend, 2026-10-14; not measured here]* —
+ * while `grant` stays "shared with you". ⚠️ An empty list means empty: a lapsed session
+ * is a `401`, never `200 []`.
  */
 export const LIST = {
   records: 'entities',
@@ -603,4 +672,14 @@ 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: 'elevation-by-provider',
+    we:
+      "send the page's address without its query or fragment as `redirect_uri`, and a fresh `state` of our own per attempt, which we never read back — the session's own `elevation.until` says whether it worked; we then take `?elevate=ok`, `?error=oauth_step_up_not_linked` and our `state` off the address bar",
+    from:
+      'the backend names the route, its two parameters and the two answers (2026-10-14), and says it works as step-up\'s provider flow does; what `state` must be, and how an answer joins a `redirect_uri` that has a query of its own, it does not say — a sign-in through a provider sends a fresh `state` per attempt and gets it back',
+    breaks:
+      "a backend that refuses a `state` it did not mint, or this site's origin as a `redirect_uri`, answers the navigation with a page of its own: the viewer is not elevated, and nothing else changes",
+  },
+]