fedipod 1.10.0 → 1.26.1

package/web/app/site/bb/read.mjs

@@ -0,0 +1,296 @@
+// read.mjs — reading a forum from its pod, as a browser does: the forum's
+// actor, its categories, a category's topics, a topic's posts, and the
+// readable copy of each post. Plain fetches of public documents; nothing here
+// needs an account. Runs in a browser and in Node alike.
+
+// No quoted profile parameter: a quote in a request header turns a browser's
+// read into a preflighted one, and a plain Accept is enough for every server.
+const ACCEPT = 'application/activity+json, application/ld+json, application/json;q=0.9';
+const MAX_PAGES = 50;
+
+export const categoryBase = (actorId) => String(actorId).replace(/ap\/actor$/u, '');
+
+// Where a forum is read from: through a Gateway at `<origin>/u/<handle>/`, or
+// a pod home given outright.
+export const forumBase = ({ origin = null, handle = null, pod = null } = {}) => {
+  if (pod) return pod.endsWith('/') ? pod : pod + '/';
+  if (!origin || !handle) throw new Error('a forum is named by a handle at this site, or by its pod');
+  return `${origin}/u/${encodeURIComponent(handle)}/`;
+};
+
+// Where the page runs decides how a forum is named and where it is read from.
+// At `bb.<gateway>` the forum is the first path segment and its record is read
+// through the Gateway at `<gateway>`; anywhere else it is `?forum=<handle>`
+// read through the page's own origin, or `?pod=<home>` read from the pod.
+export function placeOf({ origin, pathname = '/', search = '' }) {
+  const params = new URLSearchParams(search);
+  const u = new URL(origin);
+  const own = /^bb\./u.test(u.host);
+  const front = own ? `${u.protocol}//${u.host.replace(/^bb\./u, '')}` : origin;
+  const fromPath = own ? decodeURIComponent(pathname.split('/').filter(Boolean)[0] || '') : '';
+  const handle = params.get('forum') || fromPath || null;
+  const pod = params.get('pod');
+  return { front, handle, pod, base: pod || handle ? forumBase({ origin: front, handle, pod }) : null };
+}
+
+// The name a cached copy is filed under (the same digest the host uses).
+export async function cacheKey(postId) {
+  const bytes = new TextEncoder().encode(String(postId));
+  const d = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(d)].map(b => b.toString(16).padStart(2, '0')).join('').slice(0, 16);
+}
+
+// `@name@host` for an actor id, for display: what the id says about itself.
+export function authorLabel(actorId) {
+  try {
+    const u = new URL(actorId);
+    const name = u.pathname.replace(/\/$/u, '').split('/').filter(Boolean).filter(s => s !== 'ap' && s !== 'actor').pop() || u.host;
+    return `@${name}@${u.host}`;
+  } catch { return String(actorId); }
+}
+
+export function reader({ fetch: f = globalThis.fetch.bind(globalThis), session = null } = {}) {
+  // A topic's name and how many posts are in it, read once however many of
+  // its posts a feed carries.
+  const topicInfo = async (topicId, seen) => {
+    if (!topicId) return { name: null, total: 0 };
+    if (seen.has(topicId)) return seen.get(topicId);
+    const head = await get(topicId);
+    const info = { name: head?.name || null, total: Number(head?.totalItems) || 0 };
+    seen.set(topicId, info);
+    return info;
+  };
+  const get = async (url) => {
+    // A request that fails at the network level — a dropped connection, a
+    // document that is simply not there — reads the same as one that is not
+    // readable: nothing. Letting it throw meant one missing side document
+    // took the whole page down with it.
+    let r = null;
+    try { r = await f(url, { headers: { accept: ACCEPT } }); } catch { return null; }
+    // A members-only category answers 401 or 403 to the world. A reader who
+    // is signed in asks again as themselves, and the pod decides.
+    if (r && (r.status === 401 || r.status === 403) && session?.fetch) {
+      const mine = await session.fetch(url, { headers: { accept: ACCEPT } }).catch(() => null);
+      if (mine?.ok) { try { return await mine.json(); } catch { return null; } }
+      return null;
+    }
+    if (!r || !r.ok) return null;
+    try { return await r.json(); } catch { return null; }
+  };
+  const idOf = (v) => (typeof v === 'string' ? v : v?.id);
+  const pages = async (head, { forward = true } = {}) => {
+    const out = [];
+    let next = forward ? head?.first : head?.first;   // both collections start at `first`
+    const seen = new Set();
+    while (next && !seen.has(next) && out.length < MAX_PAGES) {
+      seen.add(next);
+      const page = await get(next);
+      if (!page) break;
+      out.push(page);
+      next = page.next;
+    }
+    return out;
+  };
+
+  return {
+    // The forum: its actor and its categories, each with its name, its
+    // summary and how many members it has.
+    async forum(base) {
+      const actor = await get(base + 'ap/actor');
+      if (!actor) return null;
+      const list = await get(base + 'ap/categories');
+      const categories = [];
+      for (const id of (list?.orderedItems || [])) {
+        const a = await get(id);
+        if (!a) continue;
+        const cbase = categoryBase(a.id || id);
+        const followers = await get(cbase + 'ap/followers');
+        categories.push({
+          id: a.id || id, base: cbase, slug: a.preferredUsername || null,
+          name: a.name || a.preferredUsername || id, summary: a.summary || null,
+          // Open or private, as the forum itself says on the category's
+          // actor. A private category approves each join, which is what AS2
+          // spells `manuallyApprovesFollowers`.
+          private: a.manuallyApprovesFollowers === true,
+          members: Number(followers?.totalItems) || 0,
+        });
+      }
+      // Who runs it (FEP-baf5), each with the page a person is sent to.
+      const admins = [];
+      for (const id of ((await get(base + 'ap/administrators'))?.orderedItems || []).map(idOf).filter(Boolean)) {
+        const a = await get(id);
+        admins.push({
+          id,
+          handle: a?.preferredUsername && a?.id ? `@${a.preferredUsername}@${new URL(a.id).host}` : authorLabel(id),
+          url: (typeof a?.url === 'string' && a.url) || id,
+        });
+      }
+      const heartbeat = await get(base + 'ap/heartbeat');
+      return { id: actor.id, name: actor.name || actor.preferredUsername, summary: actor.summary || null,
+        handle: actor.preferredUsername || null, categories, admins, lastHosted: heartbeat?.at || null };
+    },
+
+    // A category's topics, newest first, with each topic's head.
+    async topics(cbase) {
+      const head = await get(cbase + 'ap/topics');
+      if (!head) return { total: 0, topics: [] };
+      const ps = await pages(head);
+      const topics = [];
+      for (const page of ps) {
+        for (const id of (page.orderedItems || [])) {
+          const t = await get(idOf(id));
+          if (t) topics.push({ id: t.id, name: t.name || '', count: Number(t.totalItems) || 0, published: t.published || null, updated: t.updated || t.published || null });
+        }
+      }
+      return { total: Number(head.totalItems) || topics.length, topics };
+    },
+
+    // One topic: its head and every post id in order.
+    async topic(topicId) {
+      const head = await get(topicId);
+      if (!head) return null;
+      const ps = await pages(head);
+      const posts = ps.flatMap(p => (p.orderedItems || []).map(idOf)).filter(Boolean);
+      return { id: head.id, name: head.name || '', category: idOf(head.attributedTo) || null,
+        closed: head.closed || null,
+        total: Number(head.totalItems) || posts.length, published: head.published || null, updated: head.updated || null, posts };
+    },
+
+    // The author's card, when the forum kept one: handle, name, picture.
+    async author(cbase, actorId) {
+      const card = await get(cbase + 'ap/cache/' + await cacheKey(actorId));
+      if (!card) return null;
+      let host = '';
+      try { host = new URL(card.id || actorId).host; } catch { /* unlabelled */ }
+      return {
+        id: card.id || actorId, name: card.name || card.preferredUsername || null,
+        handle: card.preferredUsername && host ? `@${card.preferredUsername}@${host}` : authorLabel(actorId),
+        // The page a person is sent to is the one the actor names. Its id is a
+        // document for machines, so it is not offered in its place.
+        icon: card.icon?.url || null, url: (typeof card.url === 'string' && card.url) || null,
+      };
+    },
+
+    // Somebody the forum has kept nothing about — a moderator who has not
+    // posted, say. Their own actor is what the page has to go on.
+    async actorCard(actorId) {
+      const doc = await get(actorId);
+      if (!doc?.id) return null;
+      let host = '';
+      try { host = new URL(doc.id).host; } catch { /* unlabelled */ }
+      const icon = typeof doc.icon === 'string' ? doc.icon : doc.icon?.url;
+      return {
+        id: doc.id, name: doc.name || doc.preferredUsername || null,
+        handle: doc.preferredUsername && host ? `@${doc.preferredUsername}@${host}` : authorLabel(actorId),
+        icon: icon || null, url: (typeof doc.url === 'string' && doc.url) || null,
+        // Where a message for them is handed in.
+        inbox: (typeof doc.inbox === 'string' && doc.inbox) || doc.endpoints?.sharedInbox || null,
+      };
+    },
+
+    // The handle an actor says is its own. A name read off an address is a
+    // guess, right only where the address happens to spell the name; a server
+    // that will not hand out its actors unasked leaves the guess standing.
+    async actorHandle(actorId) {
+      const doc = await get(actorId);
+      if (!doc?.preferredUsername) return null;
+      try { return `@${doc.preferredUsername}@${new URL(doc.id || actorId).host}`; } catch { return null; }
+    },
+
+    // The forum's newest posts, across every category: the index names the
+    // forum's own copies, so one fetch of each tells who wrote it, when, and
+    // which topic and category it belongs to.
+    async latest(base, { limit = 30, from = 0 } = {}) {
+      const head = await get(base + 'ap/latest');
+      const all = (head?.orderedItems || []).map(idOf).filter(Boolean);
+      const ids = all.slice(from, from + limit);
+      const out = [];
+      const named = new Map();
+      for (const url of ids) {
+        // The post and how many voted it down, asked for together: the down
+        // count is a collection of its own beside the copy, because AS2 has
+        // no property to publish one in.
+        const [copy, disliked] = await Promise.all([get(url), get(url + '-dislikes')]);
+        if (!copy || copy.type === 'Tombstone') continue;
+        out.push({
+          id: copy.id || url,
+
+          author: idOf([].concat(copy.attributedTo || [])[0]) || null,
+          name: copy.name || null,
+          content: typeof copy.content === 'string' ? copy.content : '',
+          published: copy.published || null,
+          topic: idOf(copy.context) || null,
+          inReplyTo: idOf(copy.inReplyTo) || null,
+          // Answers to THIS post, as the forum counted them.
+          replies: Number(copy.replies?.totalItems) || 0,
+          likes: Number(copy.likes?.totalItems) || 0,
+          dislikes: Number(disliked?.totalItems) || 0,
+          category: idOf([].concat(copy.audience || [])[0]) || null,
+          page: [].concat(copy.url || []).map(u => (typeof u === 'string' ? u : null)).find(Boolean) || null,
+        });
+        const info = await topicInfo(out[out.length - 1].topic, named);
+        out[out.length - 1].topicName = info.name;
+        // Replies: everything in the topic but the post that opened it.
+        out[out.length - 1].topicTotal = info.total;
+        // What the index shows: how many replies the TOPIC has had. The
+        // post's own answers are on `replies`, for whatever wants them.
+        out[out.length - 1].topicReplies = Math.max(0, info.total - 1);
+      }
+      // What is left behind this page, so a reader can ask for it.
+      out.more = Math.max(0, all.length - (from + ids.length));
+      return out;
+    },
+
+    // The topics a category has pinned (its featured collection): what a
+    // reader should see first, whatever else has been said since.
+    async featured(cbase) {
+      const c = await get(cbase + 'ap/featured');
+      return (c?.orderedItems || []).map(idOf).filter(Boolean);
+    },
+
+    // Whether this reader may read a category's posts at all: a members-only
+    // one refuses the world, and its topics then look like none.
+    async canRead(cbase) {
+      const r = await f(cbase + 'ap/topics', { headers: { accept: ACCEPT } }).catch(() => null);
+      if (r && (r.status === 401 || r.status === 403)) {
+        if (!session?.fetch) return false;
+        const mine = await session.fetch(cbase + 'ap/topics', { headers: { accept: ACCEPT } }).catch(() => null);
+        return !!mine?.ok;
+      }
+      return !!r?.ok;
+    },
+
+    // Who moderates a category. The category says so itself (FEP-1b12), which
+    // is what lets a page show a moderator their own buttons.
+    async moderators(cbase) {
+      const c = await get(cbase + 'ap/moderators');
+      return (c?.orderedItems || []).map(idOf).filter(Boolean);
+    },
+
+    // The readable copy of a post, or null when the forum holds none.
+    async post(cbase, postId) {
+      const at = cbase + 'ap/cache/' + await cacheKey(postId);
+      const [copy, disliked] = await Promise.all([get(at), get(at + '-dislikes')]);
+      if (!copy) return null;
+      // `url` is where a PERSON reads this post; `id` is where a server
+      // fetches it. They are the same on some servers and never on a pod.
+      const page = [].concat(copy.url || [])
+        .map(u => (typeof u === 'string' ? u : (u?.mediaType === 'text/html' ? u.href : null)))
+        .find(u => typeof u === 'string' && /^https?:/u.test(u)) || null;
+      return {
+        id: copy.id || postId, type: copy.type || 'Note', gone: copy.type === 'Tombstone', page,
+        author: idOf([].concat(copy.attributedTo || [])[0]) || null,
+        name: copy.name || null, content: typeof copy.content === 'string' ? copy.content : '',
+        // What its author typed, when they said so: an edit reopens this
+        // rather than guessing it back out of the HTML.
+        source: copy.source?.mediaType === 'text/markdown' && typeof copy.source?.content === 'string' ? copy.source.content : null,
+        published: copy.published || null, updated: copy.updated || null, inReplyTo: idOf(copy.inReplyTo) || null,
+        // Which topic the forum placed it in: what a Delete has to name as
+        // the place the post is being taken out of.
+        topic: idOf(copy.context) || null,
+        likes: Number(copy.likes?.totalItems) || 0,
+        dislikes: Number(disliked?.totalItems) || 0,
+      };
+    },
+  };
+}

package/web/app/site/bb/seen.mjs

@@ -0,0 +1,64 @@
+// seen.mjs — what this reader has already read, kept in their own browser.
+//
+// A forum's record is public and its readers are mostly anonymous, so there is
+// nowhere on the pod to write "Mei has read this" and no right to. The mark is
+// the reader's own: one entry per topic, the time of the newest post that was
+// on the page when they last opened it, in this browser's storage and nowhere
+// else. Nothing here is sent anywhere.
+
+const KEY = (forum) => 'bb:seen:' + forum;
+// How many topics a reader's mark is kept for. Beyond this the oldest marks
+// go, and the forum's first-sight time below covers what falls off.
+const MAX = 300;
+
+const at = (iso) => { const t = Date.parse(iso); return Number.isFinite(t) ? t : null; };
+
+export function readState({ storage, forum, now = () => new Date().toISOString() }) {
+  const key = KEY(forum);
+  let rec;
+  try { rec = JSON.parse(storage.getItem(key) || 'null'); } catch { rec = null; }
+  if (!rec || typeof rec !== 'object') rec = null;
+  const save = () => { try { storage.setItem(key, JSON.stringify(rec)); } catch { /* full or blocked */ } };
+  // A forum a person has never opened is not a hundred unread topics; it is a
+  // forum they are arriving at. The first visit reads everything before it.
+  if (!rec) { rec = { since: now(), topics: {} }; save(); }
+  if (!rec.topics || typeof rec.topics !== 'object') rec.topics = {};
+
+  return {
+    since: rec.since,
+
+    // A post is new when it arrived after this reader last had its topic open
+    // — or, for a topic they have never opened, after they first saw the forum.
+    isNew(topicId, published) {
+      const when = at(published);
+      if (when === null) return false;
+      const mark = at((topicId && rec.topics[topicId]) || rec.since);
+      return mark === null ? false : when > mark;
+    },
+
+    // Opening a topic reads it, up to the newest post that was in it.
+    markRead(topicId, newest) {
+      const when = at(newest);
+      if (!topicId || when === null) return;
+      const had = at(rec.topics[topicId]);
+      if (had !== null && had >= when) return;
+      rec.topics[topicId] = new Date(when).toISOString();
+      const ids = Object.keys(rec.topics);
+      if (ids.length > MAX) {
+        ids.sort((a, b) => (at(rec.topics[a]) || 0) - (at(rec.topics[b]) || 0));
+        for (const id of ids.slice(0, ids.length - MAX)) delete rec.topics[id];
+      }
+      save();
+    },
+
+    // The newest post in a list, which is what opening it reads up to.
+    newest(posts) {
+      let best = null;
+      for (const p of posts || []) {
+        const t = at(p?.published);
+        if (t !== null && (best === null || t > best)) best = t;
+      }
+      return best === null ? null : new Date(best).toISOString();
+    },
+  };
+}

package/web/app/site/bb/solid-oidc-session.mjs

@@ -0,0 +1,233 @@
+// oidc-session.mjs — Solid-OIDC login for a browser page, with a secure,
+// durable, worker-visible session.
+//
+// The redirect handshake (authorization-code + PKCE) runs in the page. The
+// session it yields — a DPoP keypair whose private half is NON-EXTRACTABLE, plus
+// the refresh token, the token endpoint and the WebID — is kept in IndexedDB.
+// IndexedDB survives a browser restart and is readable by a service worker,
+// and a non-extractable key can sign but never be read out, even by injected
+// script.
+//
+//   import { solidOidcSession } from 'solid-oidc-session/oidc-session.mjs';
+//   const oidc = solidOidcSession({ dbName: 'my-app-oidc', clientName: 'My app' });
+//
+// Page:   const { authorizationUrl } = await oidc.beginLogin({ issuer, redirectUri });
+//         location.href = authorizationUrl;                      // ... redirect ...
+//         await oidc.completeLogin({ currentUrl: location.href });  // on return
+// Anywhere (page or worker, SAME dbName):
+//         const session = await oidc.getSession();  // { webId, issuer, fetch, refresh, signOut } | null
+//
+// No imports, no Node built-ins, nothing named after the application that
+// uses it: IndexedDB, WebCrypto and fetch are all it needs.
+
+const STORE = 'session';
+const b64u = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+const enc = (o) => b64u(new TextEncoder().encode(JSON.stringify(o)));
+const sha256 = (s) => crypto.subtle.digest('SHA-256', new TextEncoder().encode(s));
+const rand = (n = 32) => b64u(crypto.getRandomValues(new Uint8Array(n)));
+
+async function dpopKey() { return crypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, false, ['sign']); }
+async function publicJwk(pair) { const j = await crypto.subtle.exportKey('jwk', pair.publicKey); return { kty: j.kty, crv: j.crv, x: j.x, y: j.y }; }
+async function dpopProof(pair, jwk, htm, htu, ath) {
+  const header = { typ: 'dpop+jwt', alg: 'ES256', jwk };
+  const payload = { htm, htu: htu.split('#')[0], jti: crypto.randomUUID(), iat: Math.floor(Date.now() / 1000), ...(ath ? { ath } : {}) };
+  const data = `${enc(header)}.${enc(payload)}`;
+  const sig = await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, pair.privateKey, new TextEncoder().encode(data));
+  return `${data}.${b64u(sig)}`;
+}
+const jwtPayload = (jwt) => { try { return JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(jwt.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0)))); } catch { return {}; } };
+
+async function discover(issuer) {
+  const res = await fetch(`${issuer.replace(/\/+$/, '')}/.well-known/openid-configuration`, { headers: { accept: 'application/json' } });
+  if (!res.ok) throw new Error(`OIDC discovery failed at ${issuer} (HTTP ${res.status})`);
+  return res.json();
+}
+async function registerClient(cfg, redirectUri, clientName) {
+  const res = await fetch(cfg.registration_endpoint, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ client_name: clientName, redirect_uris: [redirectUri], token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], application_type: 'web', scope: 'openid webid offline_access' }),
+  });
+  if (!res.ok) throw new Error(`client registration failed (HTTP ${res.status})`);
+  return (await res.json()).client_id;
+}
+
+/**
+ * One session store. `dbName` is the IndexedDB database the session lives in:
+ * a page and its service worker must pass the same name to see the same
+ * sign-in, and two apps on one origin pass different names to keep theirs
+ * apart. `clientName` is what the pod's login screen shows the person.
+ */
+export function solidOidcSession({ dbName = 'solid-oidc-session', clientName = 'Solid app' } = {}) {
+  function idb() {
+    return new Promise((res, rej) => {
+      const r = indexedDB.open(dbName, 1);
+      r.onupgradeneeded = () => r.result.createObjectStore(STORE);
+      r.onsuccess = () => res(r.result);
+      r.onerror = () => rej(r.error);
+    });
+  }
+  async function idbGet(key) {
+    const db = await idb();
+    return new Promise((res, rej) => { const t = db.transaction(STORE).objectStore(STORE).get(key); t.onsuccess = () => res(t.result); t.onerror = () => rej(t.error); });
+  }
+  async function idbPut(key, val) {
+    const db = await idb();
+    return new Promise((res, rej) => { const t = db.transaction(STORE, 'readwrite').objectStore(STORE).put(val, key); t.onsuccess = () => res(); t.onerror = () => rej(t.error); });
+  }
+  async function idbDel(key) {
+    const db = await idb();
+    return new Promise((res, rej) => { const t = db.transaction(STORE, 'readwrite').objectStore(STORE).delete(key); t.onsuccess = () => res(); t.onerror = () => rej(t.error); });
+  }
+
+  /** Begin login: prepare PKCE + a non-extractable DPoP key, stash the pending
+   *  state, and return the authorization URL for the caller to navigate to. */
+  async function beginLogin({ issuer, redirectUri, clientName: name = clientName, returnTo = null }) {
+    const cfg = await discover(issuer);
+    const client_id = await registerClient(cfg, redirectUri, name);
+    const pair = await dpopKey();
+    const verifier = rand(48);
+    const challenge = b64u(await sha256(verifier));
+    const state = rand(16);
+    await idbPut('pending', { issuer, client_id, redirectUri, verifier, state, pair, returnTo,
+      tokenEndpoint: cfg.token_endpoint, authorizationEndpoint: cfg.authorization_endpoint,
+      revocationEndpoint: cfg.revocation_endpoint || null });
+    const url = new URL(cfg.authorization_endpoint);
+    for (const [k, v] of Object.entries({ client_id, redirect_uri: redirectUri, response_type: 'code',
+      scope: 'openid webid offline_access', code_challenge: challenge, code_challenge_method: 'S256', state, prompt: 'consent' })) url.searchParams.set(k, v);
+    return { authorizationUrl: url.href };
+  }
+
+  /** Complete login from the redirect back. Exchanges the code (DPoP + PKCE),
+   *  stores the durable session, and returns it. Returns null if there is no code. */
+  async function completeLogin({ currentUrl }) {
+    const u = new URL(currentUrl);
+    const code = u.searchParams.get('code');
+    const state = u.searchParams.get('state');
+    if (!code) return null;
+    const p = await idbGet('pending');
+    if (!p || p.state !== state) throw new Error('login state mismatch');
+    const jwk = await publicJwk(p.pair);
+    const res = await fetch(p.tokenEndpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', dpop: await dpopProof(p.pair, jwk, 'POST', p.tokenEndpoint) },
+      body: new URLSearchParams({ grant_type: 'authorization_code', code, redirect_uri: p.redirectUri, client_id: p.client_id, code_verifier: p.verifier }),
+    });
+    const tok = await res.json().catch(() => ({}));
+    if (!res.ok || !tok.access_token) throw new Error(`token exchange failed (HTTP ${res.status}): ${tok.error || ''}`);
+    const webId = jwtPayload(tok.access_token).webid || jwtPayload(tok.id_token || '').webid || null;
+    const session = { issuer: p.issuer, client_id: p.client_id, tokenEndpoint: p.tokenEndpoint, pair: p.pair,
+      // Where to hand the refresh token back at sign-out. Kept on the session
+      // because discovery is a network round trip and sign-out should not need
+      // one — see signOut().
+      revocationEndpoint: p.revocationEndpoint || null,
+      refreshToken: tok.refresh_token || null, accessToken: tok.access_token,
+      expiresAt: Date.now() + Math.max(30, (tok.expires_in || 300)) * 1000, webId };
+    await idbPut('session', session);
+    await idbDel('pending');
+    // `returnTo` rides only on the handle this call returns: where the person
+    // was when they left for the login page, for the caller to send them back.
+    return Object.assign(sessionHandle(session), p.returnTo ? { returnTo: p.returnTo } : {});
+  }
+
+  /** Restore the session from IndexedDB — works in the page and the worker. */
+  async function getSession() {
+    const s = await idbGet('session');
+    return s ? sessionHandle(s) : null;
+  }
+
+  /**
+   * Sign out, and tell the issuer.
+   *
+   * Dropping the row locally leaves the REFRESH TOKEN alive at the pod for its
+   * full life — signing out of a shared or borrowed browser would clear the
+   * screen and nothing else, and anyone who had copied the token could go on
+   * minting access tokens with it. RFC 7009: hand it back.
+   *
+   * Best effort, and the local teardown happens either way: an issuer that is
+   * unreachable, or that publishes no revocation endpoint, must not be able to
+   * keep somebody signed in.
+   */
+  async function signOut() {
+    const s = await idbGet('session').catch(() => null);
+    if (s?.revocationEndpoint && s.refreshToken) {
+      try {
+        await fetch(s.revocationEndpoint, {
+          method: 'POST',
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({
+            token: s.refreshToken, token_type_hint: 'refresh_token', client_id: s.client_id,
+          }),
+        });
+      } catch { /* told if we could; leaving is not conditional on being heard */ }
+    }
+    await idbDel('session');
+    await idbDel('pending');
+  }
+
+  function sessionHandle(s) {
+    let { accessToken, expiresAt, refreshToken } = s;
+    const jwkP = publicJwk(s.pair);
+    const refresh = async () => {
+      if (!refreshToken) throw new Error('session expired and there is no refresh token — sign in again');
+      const jwk = await jwkP;
+      let res;
+      try {
+        res = await fetch(s.tokenEndpoint, {
+          method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', dpop: await dpopProof(s.pair, jwk, 'POST', s.tokenEndpoint) },
+          body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: s.client_id, scope: 'openid webid offline_access' }),
+        });
+      } catch (e) {
+        // A renewal that never reached the server is not a refused one: the
+        // session is still good, and saying "your pod refused the write" about
+        // it sends whoever reads it looking in the wrong place. Under load a
+        // server refuses the token endpoint first, and a refusal with no CORS
+        // headers arrives here as the browser's bare "Failed to fetch".
+        throw new Error(`${e.message} — renewing your sign-in at ${new URL(s.tokenEndpoint).host}`);
+      }
+      const tok = await res.json().catch(() => ({}));
+      if (res.status === 429) {
+        throw new Error(`${new URL(s.tokenEndpoint).host} is asking us to slow down — your sign-in could not be renewed just now`);
+      }
+      if (!res.ok || !tok.access_token) { await idbDel('session'); throw new Error('refresh failed — sign in again'); }
+      accessToken = tok.access_token;
+      expiresAt = Date.now() + Math.max(30, (tok.expires_in || 300)) * 1000;
+      if (tok.refresh_token) refreshToken = tok.refresh_token;
+      // Re-read before writing back. There is ONE 'session' row, and this handle
+      // closed over the session it was made from — so a refresh that was already
+      // in flight when the user signed in as somebody else would put the OLD
+      // identity back, silently, over the new one. Only write if the row is still
+      // the session this handle belongs to.
+      const now = await idbGet('session');
+      if (now && now.webId !== s.webId) {
+        throw new Error('signed in as somebody else while this session was refreshing');
+      }
+      await idbPut('session', { ...s, accessToken, expiresAt, refreshToken });
+    };
+    const send = async (url, init) => {
+      const jwk = await jwkP;
+      const ath = b64u(await sha256(accessToken));
+      const headers = { ...(init.headers || {}), authorization: `DPoP ${accessToken}`, dpop: await dpopProof(s.pair, jwk, (init.method || 'GET'), url, ath) };
+      return fetch(url, { ...init, headers });
+    };
+    const authFetch = async (url, init = {}) => {
+      if (Date.now() > expiresAt - 30_000) await refresh();
+      const res = await send(url, init);
+      // A token the pod REFUSES is not only ever an expired one: a pod that
+      // restarted, a clock that drifted, a token the server stopped recognising
+      // all answer 401 while the clock here still says the token is good — so the
+      // renewal above never fires and every call fails from then on. Renew once
+      // and ask again.
+      if (res.status === 401 && refreshToken) {
+        try { await refresh(); } catch { return res; }
+        return send(url, init);
+      }
+      return res;
+    };
+    // `issuer` so a page that cannot renew can send the person back to the right
+    // login without asking them for their address again.
+    return { webId: s.webId, issuer: s.issuer, fetch: authFetch, refresh, signOut };
+  }
+
+  return { beginLogin, completeLogin, getSession, signOut };
+}

package/web/app/site/bb/tokens.css

@@ -0,0 +1,68 @@
+/* tokens.css — the FediPod design tokens: the front page's palette
+   (web/app/index.html), so the front, the record page, the bar and the client
+   shell are one visual system. The front is the reference; these values mirror
+   its :root. Declared under every name the pages already use — plus aliases
+   (--ink=--fg, --muted=--sub, --link=--accent, --field-edge=--field-border,
+   --danger=--err, --ring=--focus) — so a page only has to drop its own :root
+   colours and inherit these. The base size and the font family live here too:
+   20px base, Arial, and nothing on any page below 16px. */
+:root {
+  color-scheme: light dark;
+  font-size: 125%;                      /* 20px base (125% of 16) */
+  --font: Arial, Helvetica, sans-serif;  /* one family across the site */
+
+  /* ground + text */
+  --bg: #ffffff; --fg: #1a1a1a; --ink: #1a1a1a;
+  --surface: #f0f2f5;          /* the page ground behind cards */
+  --raised: #ffffff;           /* cards, the rail, the bar band, dialogs */
+
+  /* structure + action */
+  --heading: #2c4a35; --accent: #12467e; --link: #12467e;
+  --sub: #565656; --muted: #565656; --line: #b0b0b0;
+
+  /* fields */
+  --field-bg: #ececec; --field-bg-hover: #e2e4e8; --field-hover: #e2e4e8;
+  --field-text: #141414; --field-edge: #6f6f6f; --field-border: #6f6f6f;
+
+  /* buttons — filled, muted forest green (like the front) */
+  --btn: #3a5f43; --btn-hover: #30503a; --btn-text: #ffffff;
+  --btn-bg: #ececec; --btn-bg-hover: #e2e4e8; --btn-bg-active: #d8dade; --btn-edge: #6f6f6f;
+
+  /* status + focus */
+  --err: #b00020; --danger: #b00020; --warn: #8a4b00; --ok: #1f7a3d;
+  --focus: #12467e; --ring: #12467e;
+
+  /* the edge of a dialog: bright against the page behind it */
+  --dialog-edge: #b8b8b8;
+
+  /* every other row of a table. A stripe nobody can see is not a stripe:
+     this is a real step from the page, not a hint of one. */
+  --stripe: #d3dce8;
+
+  --chevron: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6'><path d='M1 1l4 4 4-4' fill='none' stroke='%23124f8a' stroke-width='1.6' stroke-linecap='round'/></svg>");
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #191919; --fg: #f3f3f3; --ink: #f3f3f3;
+    --surface: #18191a; --raised: #242526;
+
+    --heading: #a7d4b5; --accent: #8fc2f2; --link: #8fc2f2;
+    --sub: #d2d2d2; --muted: #d2d2d2; --line: #6d6d6d;
+
+    --field-bg: #474747; --field-bg-hover: #515151; --field-hover: #515151;
+    --field-text: #f5f5f5; --field-edge: #9aa0a6; --field-border: #9aa0a6;
+
+    /* a touch brighter on the dark page so white text and the fill-vs-page edge
+       both clear their contrast floors — still muted (kept in sync with the front) */
+    --btn: #4a7a54; --btn-hover: #3f6a49; --btn-text: #ffffff;
+    --btn-bg: #474747; --btn-bg-hover: #515151; --btn-bg-active: #5b5b5b; --btn-edge: #9aa0a6;
+
+    --err: #ff9b9b; --danger: #ff9b9b; --warn: #ffb366; --ok: #7fd39a;
+    --focus: #8fc2f2; --ring: #8fc2f2;
+    --dialog-edge: #f3f3f3;
+    --stripe: #363c45;
+
+    --chevron: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6'><path d='M1 1l4 4 4-4' fill='none' stroke='%23bcd8f0' stroke-width='1.6' stroke-linecap='round'/></svg>");
+  }
+}