@uniweb/api 0.6.10 → 0.8.0

package/README.md

@@ -1,10 +1,10 @@
 # @uniweb/api
 
-The client a foundation uses to talk to **its site's `api` service** — sign-in, the
+The client a foundation uses to talk to **its site's `backend` service** — sign-in, the
 site's members, and the content they create.
 
 You import it the way you import `@uniweb/kit`. It is bundled into your foundation,
-tree-shaken, and **inert on a site that has no `api` service**: nothing throws, no request
+tree-shaken, and **inert on a site that has no `backend` service**: nothing throws, no request
 leaves, and your components render the version of themselves that does not need one.
 
 ```bash
@@ -17,9 +17,9 @@ Ask before you draw. This is a synchronous read of the site's own configuration,
 a probe — there is nothing to await.
 
 ```jsx
-import { isApiEnabled } from '@uniweb/kit'
+import { isBackendEnabled } from '@uniweb/kit'
 
-if (!isApiEnabled()) return <StaticVersion />
+if (!isBackendEnabled()) return <StaticVersion />
 ```
 
 ⛔ **And when the answer is no, draw nothing** — not a disabled button, and not an
@@ -52,11 +52,13 @@ 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
@@ -69,6 +71,23 @@ already taken fails with status `409`.
 second factor is enrolled). **Second factor** — when `signIn` answers
 `{ ok: false, challenge: { kind: 'totp' } }`, finish with `completeChallenge(code)`.
 
+**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
 
 ```jsx
@@ -79,14 +98,14 @@ const { status, records, hasMore } = useRecords({ schema: '@acme/session', scope
 ```
 
 ⭐ **`absent` and an empty `ready` are different answers.** `absent` means there is no
-live source — no `api` service, or nobody signed in — so render your site's own content.
+live source — no `backend` service, or nobody signed in — so render your site's own content.
 `ready` with `records: []` means the service answered and there is nothing there.
 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
@@ -170,8 +189,9 @@ Building against a live service is slow and puts a shared database behind your
 experiments. Name a local one in `site.yml`:
 
 ```yaml
-api: /_api                 # where the service answers — the same in production
-$devApi: ./mock/api.js     # what answers it locally; never published
+services:
+  backend: true                # ask your host for it, on a site you publish
+$devBackend: ./mock/api.js    # what answers it in `uniweb dev`; never published
 ```
 
 ```js
@@ -181,7 +201,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: {
@@ -203,20 +223,22 @@ export default createMockBackend({
 }).fetch
 ```
 
-`uniweb dev` mounts it at your `api:` address — same origin, so cookies behave as they
-will in production, and your site's configuration is identical either way.
+`uniweb dev` mounts it at an address of its own on the dev server, and hands your site that
+address the way a host hands over its own — same origin, so cookies behave as they will in
+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.
+verified: the link is in `mock.outbox` (the standalone server prints it). The
+operator's Admin link answers too, landing on a page of the mock's own — the backend's
+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:
 
@@ -228,7 +250,7 @@ npx uniweb-api-mock --port 8787
 
 `@uniweb/api/client` carries the same operations as plain functions and imports no
 React: `probeSession`, `signIn`, `listEntities`, `readEntity`, `writeItems`,
-`createEntity`, `deleteEntity`.
+`createEntity`, `deleteEntity`, `adminHref`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.6.10",
+  "version": "0.8.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.37.0"
+    "@uniweb/core": "^0.38.1"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -2,7 +2,7 @@
  * @uniweb/api — the client half. No React in this module.
  *
  * A foundation's client for the site's own backend — the one a host declares
- * as the site service `api`. Absent that declaration the site has no such
+ * as the site service `backend`. Absent that declaration the site has no such
  * backend and everything here is inert: no request leaves, and a component
  * renders for that state rather than retrying it.
  *
@@ -15,11 +15,19 @@ 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'
 
-/** The site service this package reads its base from — the only name it owns. */
-export const SERVICE_NAME = 'api'
+/**
+ * The site service this package reads its base from — the only name it owns.
+ *
+ * ⛔ **It was `api` until 2026-10-07.** A service is named for what it gives the
+ * site — `search`, `records` — and this one is the site's own backend; `/api` is
+ * only the interface it answers on, which is what this package is named for. A
+ * foundation built before then asks for `api`, which no host offers now, and draws
+ * no sign-in until it is rebuilt.
+ */
+export const SERVICE_NAME = 'backend'
 
 /**
  * The shape of the shared instance, as a contract between copies of this
@@ -31,10 +39,10 @@ export const CONTRACT = 1
 /**
  * Where the site's backend is, if it has one.
  *
- * `resolveService` answers with the host's offer first (`config.services.api`),
- * then the site's own declaration (`api:` in `site.yml`), and `null` when neither
- * names an address. Absence is the ordinary state of a site with no backend,
- * not an error.
+ * `resolveService` answers with the host's offer first (`config.services.backend`),
+ * then the site's own address (`backend:` under `services:` in `site.yml`), and
+ * `null` when neither names one. Absence is the ordinary state of a site with no
+ * backend, not an error.
  *
  * @param {object} website - the active Website, or anything shaped `{ config, basePath }`
  * @returns {string|null} the base every request is made against, or null
@@ -44,34 +52,35 @@ export function resolveBase(website) {
 }
 
 /**
- * Does this site have an app backend — the `api` service?
+ * Does this site have an app backend — the `backend` service?
  *
  * The question to ask before drawing a sign-in affordance or any control only a
  * backend can answer. False means: draw nothing, or the static alternative the
  * site already carries.
  *
  * ⭐ **The website argument is OPTIONAL and defaults to the active one**, so this
- * is the same call as `@uniweb/kit`'s `isApiEnabled()` — one predicate per
+ * is the same call as `@uniweb/kit`'s `isBackendEnabled()` — one predicate per
  * service, no arguments, the website resolved for you. Pass one explicitly only
  * when you already hold it, or are working outside a render.
  *
  * ⛔ **THE DEFAULT IS NOT A CONVENIENCE, IT CLOSES A TRAP.** For one commit this
  * took a REQUIRED website while every doc and template showed the no-argument
- * spelling — so `import { isApiEnabled } from '@uniweb/api'` followed by
- * `isApiEnabled()` resolved `undefined`, returned `false` forever, and drew no
- * sign-in UI on a site that had a backend. Silent, and indistinguishable from a
- * site with no backend: exactly the invisible absence this predicate exists to
- * prevent. Caught in review the same day; pinned by `tests/enabled.test.js`.
+ * spelling — so the documented call resolved `undefined`, returned `false`
+ * forever, and drew no sign-in UI on a site that had a backend. Silent, and
+ * indistinguishable from a site with no backend: exactly the invisible absence
+ * this predicate exists to prevent. Caught in review the same day; pinned by
+ * `tests/enabled.test.js`.
  *
- * ⛔ **Renamed from `isEnabled` (2026-09-10).** The old name said nothing about
- * its subject and collided with three unrelated `isEnabled`s in the framework —
- * including the field `useSearch()` returns, which made `uniweb doctor` read a
- * search control as gated when it was gated on this instead.
+ * ⛔ **Renamed twice.** From `isEnabled` (2026-09-10): the old name said nothing
+ * about its subject and collided with three unrelated `isEnabled`s in the
+ * framework — including the field `useSearch()` returns, which made `uniweb
+ * doctor` read a search control as gated when it was gated on this instead. Then
+ * from `isApiEnabled` (2026-10-07), with the service it asks about (`SERVICE_NAME`).
  *
  * @param {object} [website] - defaults to the active website
  * @returns {boolean}
  */
-export function isApiEnabled(website = getUniweb()?.activeWebsite ?? null) {
+export function isBackendEnabled(website = getUniweb()?.activeWebsite ?? null) {
   return resolveBase(website) !== null
 }
 
@@ -344,6 +353,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 })
@@ -618,8 +628,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
    *
@@ -912,6 +923,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() {
@@ -944,6 +977,8 @@ 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 { ApiError, kindOf } from './errors.js'
 export { Ledger } from './ledger.js'

package/src/hooks/useRecords.js

@@ -18,7 +18,7 @@ const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, ha
  * ## ⭐ `absent` and an empty `ready` are DIFFERENT, and conflating them is the bug
  *
  * `absent` means **there is no live source for this viewer** — a site with no
- * `api` service, which is the ordinary standalone case, or nobody signed in, since
+ * `backend` service, which is the ordinary standalone case, or nobody signed in, since
  * the backend lists nothing to an anonymous caller (it answers `401`, so no request
  * is sent once the session is known to be anonymous). `ready` with `records: []`
  * means **the source answered, and there is nothing there.**
@@ -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

@@ -13,7 +13,7 @@
 export {
   SERVICE_NAME,
   resolveBase,
-  isApiEnabled,
+  isBackendEnabled,
   probeSession,
   signIn,
   completeChallenge,
@@ -26,6 +26,7 @@ export {
   writeItems,
   createEntity,
   deleteEntity,
+  adminHref,
   ApiError,
   Ledger,
 } from './client.js'

package/src/mock/index.js

@@ -1,9 +1,26 @@
-import { AUTH, ENTITIES, MODELS, PARAM, OP, FIELD, CREATE, PAGE, SCOPE, PROBLEM, GUARDED_OPS } from '../wire.js'
+import { AUTH, ENTITIES, MODELS, 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'
 
 /**
- * A mock of a site's `api` service, for local development.
+ * 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.
  *
  * ```js
  * import { createMockBackend } from '@uniweb/api/mock'
@@ -29,19 +46,22 @@ import { DEFAULT_SEED } from './seed.js'
  * ## Where it answers
  *
  * Its routes are the API's own — `/auth/me`, `/entities` — under whatever the
- * site's `api` address is. It accepts a request with the site's `/_api` prefix
+ * site's `backend` address is. It accepts a request with the site's `/_api` prefix
  * still on, and one with an extra `/api` after it (how clients before 0.4
  * composed URLs), so it answers the same whether or not the server mounting it
  * strips its path.
  *
  * ## 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 the link in `mock.outbox` is followed. The
+ * operator is the account the backend's administration admits, so its Admin link
+ * answers — with a redirect to a page of the mock's own, since the administration
+ * itself is not modelled. It does not model entitlements behind `via`, nested
+ * sections, or second factors.
  *
  * @param {object} [options]
  * @param {object} [options.seed] - accounts, schemas and entities to start from (see `MockStore`)
@@ -199,6 +219,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))
@@ -391,6 +419,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}` })
   }
 

package/src/mock/node.js

@@ -40,7 +40,7 @@ async function send(response, res) {
 
 /**
  * Connect-style middleware — what Vite's `configureServer` takes. Mount it at the
- * site's `api` address (`/_api`), which is the base the client composes routes
+ * site's `backend` address (`/_api`), which is the base the client composes routes
  * onto: `/_api/auth/me`, `/_api/entities`.
  *
  * ```js
@@ -76,7 +76,7 @@ export function middleware(mock, { prefix = '/_api' } = {}) {
 
 /**
  * A standalone server. Resolves once listening; call `close()` to stop. Its routes
- * answer at the root — a site's `api` address for it is the server's URL
+ * answer at the root — a site's `backend` address for it is the server's URL
  * (`http://localhost:8787`), plus `prefix` when one is given.
  *
  * @param {{ fetch: Function }} mock

package/src/mock/store.js

@@ -6,7 +6,7 @@ import { checkItemWrite, OUTCOME } from './schema-shape.js'
  * entities whose content is items.
  *
  * ⭐ **It stores what the backend stores, the way the backend stores it** —
- * measured 2026-09-18 against a real one set up as a site's `api` service:
+ * measured 2026-09-18 against a real one set up as a site's `backend` service:
  *
  * - **An entity's content is items, each in a section of its Model.** There is no
  *   entity-level data. A `single` section holds one item; its `brief` section's item
@@ -19,10 +19,12 @@ 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
@@ -207,15 +209,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 +237,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() {
@@ -468,28 +477,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

@@ -22,7 +22,7 @@
  * ## ⭐ MEASURED 2026-09-18 — every shape below, in literal responses
  *
  * The whole surface this package touches was exercised against a real backend set
- * up the way a site's `api` service is: one operator account, members who sign up
+ * up the way a site's `backend` service is: one operator account, members who sign up
  * themselves, and the site's own Models. Where this module quotes a shape it was
  * copied from a response, not described. That pass corrected the package in these
  * places, each now fixed and pinned by a test:
@@ -47,7 +47,7 @@
  * The lane. ⭐ **RULED** *(2026-09-01)*: this package reads and writes
  * **entities**, reads the definitions of their Models, and touches nothing under
  * `/sites/*`. Those routes create sites, which is the app's job, not a
- * foundation's, and a site's own `api` service has no site to address.
+ * foundation's, and a site's own `backend` service has no site to address.
  *
  * ⛔ Do not add a route that is not under `/entities`, `/models` or `/auth`.
  */
@@ -59,7 +59,7 @@ export const MODELS = '/models'
 /**
  * The base, and how a route joins it. **MEASURED.**
  *
- * The base the site is handed for its `api` service is the address of the
+ * The base the site is handed for its `backend` service is the address of the
  * backend's API route space, and every route here is relative to it:
  * `${base}/auth/me`, `${base}/entities`. On a hosted site that is `/_api` on the
  * site's own origin, which reaches the backend's `/api/…`; wherever a page reaches
@@ -99,8 +99,32 @@ export const AUTH = {
   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 +132,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 |
  * | 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'],
@@ -135,10 +164,16 @@ 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 `api` service such a request lands in
+ * package's requests name none, and on a site's `backend` service such a request lands in
  * the service's **home org**, `handle: 'home'`, in which every account is enrolled.
  * Both `null` there means an account that is not a member — a service account, a
  * revoked membership. (On a backend with no home org, naming none is personal: both
@@ -147,14 +182,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',
 }
 
 /**
@@ -224,11 +271,12 @@ export const PARAM = {
  * 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 +390,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 = {