fedipod-server 0.21.0 → 0.26.0

package/lib/gateway/front-core.mjs

@@ -26,14 +26,22 @@ import { podBaseOfWebId } from '../pod/urls.mjs';
 // wire.mjs: wire drags the agent's whole HTML pipeline (sanitize-html and
 // friends), which a serverless front must never carry — it crashed the
 // deployed function before it answered its first request.
-const jrd = ({ handle, host, actor, aliases = [], page = null }) => ({
+const jrd = ({ handle, host, actor, aliases = [], page = null, subscribe = null }) => ({
   subject: `acct:${handle}@${host}`,
   ...(aliases.length ? { aliases } : {}),
   links: [
     { rel: 'self', type: 'application/activity+json', href: actor },
     ...(page ? [{ rel: 'http://webfinger.net/rel/profile-page', type: 'text/html', href: page }] : []),
+    // Remote follow. Somebody reading this account on another server presses
+    // Follow, says they are here, and that server looks for this link to find
+    // out where to send them. `{uri}` is a literal the other server fills in
+    // with whatever they are following — it must not be escaped.
+    ...(subscribe ? [{ rel: 'http://ostatus.org/schema/1.0/subscribe', template: subscribe }] : []),
   ],
 });
+// The door that link names, which the site staged beside this function serves.
+const subscribeTemplate = (origin) => (origin
+  ? `${String(origin).replace(/\/$/u, '')}/authorize_interaction?uri={uri}` : null);
 // The public profile page of any account the front answers for lives on
 // its pod, whether the address is the front's or the pod's own.
 const profilePageOf = (rec) => (rec?.podHome ? rec.podHome + 'ap/profile.html' : null);
@@ -136,6 +144,8 @@ const RELAY_MAX_BODY = 1024 * 1024;
 const RELAY_TIMEOUT_MS = 8_000;
 // The only headers a relayed request may carry to the remote server. Host
 // comes from the URL; the user agent from safeFetch.
+const SERVER_PROBE_MS = 6000;
+const SERVER_PROBE_BYTES = 64 * 1024;
 const RELAY_HEADERS = new Set(['date', 'digest', 'signature', 'content-type', 'accept']);
 
 const keyIdOf = (signature) => (/keyId="([^"]+)"/.exec(signature || '') || [])[1] || null;
@@ -203,6 +213,54 @@ function parseUserPath(pathname) {
   return m ? { handle: decodeURIComponent(m[1]), rest: m[2] } : null;
 }
 
+// A public document is the same for everybody who asks, so the edge may hold
+// it and answer the next reader itself. Without this every read of an actor,
+// a topic, a post or a card was a function call: one visit to a forum is
+// twenty of them, and every visitor and every refresh paid again.
+//
+// `netlify-cdn-cache-control` is the edge's own instruction; `cache-control`
+// is what the reader's browser is told. The edge may serve a stale copy while
+// it fetches a fresh one, so nobody waits on the pod for a document that is
+// merely minutes old. The edge holds a document far longer than a browser
+// is asked to: the edge is what turns a thousand readers into one function
+// call, while a browser that held an actor for ten minutes would show one
+// person a stale profile they had just edited.
+const BROWSER_MAX_AGE = 60;
+const publicFor = (seconds, stale = seconds * 4) => ({
+  'cache-control': `public, max-age=${Math.min(seconds, BROWSER_MAX_AGE)}`,
+  'netlify-cdn-cache-control': `public, s-maxage=${seconds}, stale-while-revalidate=${stale}`,
+});
+// How long the edge holds a public document, and a handle's WebFinger
+// answer. Every server that has heard of an account asks for its actor and
+// its handle again and again; a post or a collection changes when its owner
+// acts, and ten minutes of edge is what the plan's budget of function calls
+// can afford.
+const PUBLIC_EDGE_SECONDS = 600;
+const WEBFINGER_EDGE_SECONDS = 3600;
+
+// Where a pod owner opts their identity in. An operator may name it, because
+// the path it takes is one their pod server can no longer serve; the dot says
+// it belongs to the server rather than to anybody's data, the way
+// `.well-known` and `.account` do.
+export const DEFAULT_RUN_PATH = '/.fediverse-account';
+export const runPath = (ctx) => {
+  const said = String(ctx?.runPath || '').trim().replace(/\/+$/u, '');
+  if (!said) return DEFAULT_RUN_PATH;
+  return said.startsWith('/') ? said : `/${said}`;
+};
+
+// A request the browser itself says came from this very origin. `Sec-Fetch-Site`
+// is the browser's word and a page cannot forge it; an `Origin` that matches is
+// the older way of saying the same. This is what makes it safe to read a
+// session cookie as proof: a page on another site gets neither.
+const sameOriginRequest = (request, origin) => {
+  const site = request.headers.get('sec-fetch-site');
+  if (site) return site === 'same-origin';
+  const said = request.headers.get('origin');
+  if (!said || !origin) return false;
+  try { return new URL(said).origin === new URL(origin).origin; } catch { return false; }
+};
+
 // Top-level paths a handle may not take, so a name never shadows a route.
 const RESERVED = new Set(['u', 'api', 'signup', 'new-account', 'run', 'admin', 'roster', 'gateway',
   'gw', 'well-known', 'inbox', 'outbox', 'actor', 'install']);
@@ -240,7 +298,9 @@ const policyFor = (rec, fetchImpl = fetch) =>
 // `policy` is the person's published filtering policy when there is one.
 function identFor(rec, policy = null) {
   return {
-    inboxUrl: rec.podHome + 'ap/inbox/',
+    // A row may name the inbox its deliveries are written to: a forum's
+    // categories share one, on the forum's pod, above their own trees.
+    inboxUrl: rec.inboxUrl || rec.podHome + 'ap/inbox/',
     actorUrl: rec.actorUrl,                 // the FRONT actor id (what mail is addressed to)
     followersUrl: rec.actorUrl.replace(/actor$/, 'followers'),
     notesPrefix: rec.actorUrl.replace(/ap\/actor$/, 'ap/notes/'),
@@ -330,10 +390,10 @@ async function route(request, ctx) {
   // The run page: a pod owner opting their identity in or out of being run by
   // this server. Meaningful only on a host that embeds the agent; a host that
   // does not simply supplies no page.
-  if (pathname === '/run') {
+  if (pathname === runPath(ctx)) {
     if (request.method !== 'GET' && request.method !== 'HEAD') return { status: 405, headers: {}, body: '' };
     if (!ctx.runPage) return notFound();
-    return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: ctx.runPage };
+    return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' }, body: ctx.runPage };
   }
 
   // The roster page: the host reading who has accounts here. The page signs in
@@ -398,6 +458,48 @@ async function route(request, ctx) {
       offersPods: !!ctx.offersPods, version: ctx.version || null });
   }
 
+  // What a reader's own server speaks, asked here rather than in their
+  // browser: a page cannot probe a stranger's server (no CORS), and the
+  // answer decides how that reader takes part in a forum.
+  if (pathname === '/api/server') {
+    const host = (url.searchParams.get('host') || '').trim().toLowerCase();
+    const open = { 'access-control-allow-origin': '*' };
+    const said = (kind, extra = {}) => ({ ...j(200, { host, kind, ...extra }), headers: { ...j(200, {}).headers, ...open } });
+    // An address at this front is a FediPod account: its client is the
+    // browser here, and no other server holds it. Asked before the shape of
+    // the host, since a front may answer at a name with no dot in it.
+    if (host && host === String(ctx.host || '').toLowerCase()) {
+      const handle = (url.searchParams.get('handle') || '').toLowerCase();
+      const rec = handle ? await ctx.lookup(handle) : null;
+      if (!rec) return said('fedipod');
+      // Where the owner of this pod signs in: the pod says so itself, at the
+      // well-known document every Solid server answers (or redirects to).
+      let issuer = null;
+      try {
+        const res = await safeFetch(new URL('/.well-known/openid-configuration', rec.podHome).href,
+          { headers: { accept: 'application/json' }, redirect: 'follow', signal: AbortSignal.timeout(SERVER_PROBE_MS) },
+          ctx.fetchImpl || fetch);
+        if (res.ok) issuer = JSON.parse(await readCapped(res, SERVER_PROBE_BYTES)).issuer || null;
+      } catch { /* a pod that will not say leaves the reader to type it */ }
+      return said('fedipod', { podHome: rec.podHome, actor: rec.actorUrl, issuer, inbox: identFor(rec).inboxUrl });
+    }
+    if (!/^[a-z0-9.-]+\.[a-z0-9-]+(:\d+)?$/u.test(host)) return said('invalid');
+    const f = ctx.fetchImpl || fetch;
+    const ask = async (path) => {
+      try {
+        const res = await safeFetch(`https://${host}${path}`,
+          { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(SERVER_PROBE_MS) }, f);
+        if (!res.ok) return null;
+        return JSON.parse(await readCapped(res, SERVER_PROBE_BYTES));
+      } catch { return null; }
+    };
+    const masto = await ask('/api/v1/instance');
+    if (masto) return said('mastodon-api', { name: masto.title || masto.domain || host });
+    const lemmy = await ask('/api/v3/site');
+    if (lemmy) return said('lemmy', { name: lemmy.site_view?.site?.name || host });
+    return said('unknown');
+  }
+
   // Attach: create the account. The user proves control of the pod they claim
   // by presenting a Solid-OIDC token whose WebID lives on that pod — no
   // password reaches the front. On success the directory gets a row and the
@@ -463,10 +565,20 @@ async function route(request, ctx) {
     const claimedActor = typeof body.actorUrl === 'string' && body.actorUrl.startsWith(podHome) ? body.actorUrl : null;
     const actorUrl = fronted ? `${userBase(ctx.frontOrigin, key)}ap/actor` : (claimedActor || podHome + 'ap/actor');
     const hmacSecret = prior?.hmacSecret || crypto.randomBytes(32).toString('base64');
+    // Where the door writes: the row's own tree unless the caller names an
+    // inbox on the same pod — a forum's categories name the forum's.
+    let inboxUrl = null;
+    if (typeof body.inboxUrl === 'string' && body.inboxUrl) {
+      let ok = false;
+      try { ok = new URL(body.inboxUrl).origin === new URL(podHome).origin && body.inboxUrl.endsWith('/'); } catch { ok = false; }
+      if (!ok) return j(400, { error: 'inboxUrl must be a container on the same pod' });
+      inboxUrl = body.inboxUrl;
+    }
     const record = {
       handle, address, podHome, webId: webid, actorUrl,
-      kind: body.kind === 'group' ? 'group' : 'person',
+      kind: body.kind === 'group' ? 'group' : body.kind === 'application' ? 'application' : 'person',
       gatewayWebId: ctx.gatewayWebId || null, hmacSecret,
+      ...(inboxUrl ? { inboxUrl } : {}),
       ...(fronted ? {} : { inboxOnly: true }),
     };
     await ctx.putDirectory(key, record);
@@ -508,6 +620,28 @@ async function route(request, ctx) {
     return j(200, { results });
   }
 
+  // Who is here, and which pod of theirs could opt in. The opt-in page asks
+  // this first: on a pod server that issued the reader's session, the answer
+  // names their pod and its address, and the page shows one button instead of
+  // a form. A Gateway holds no such session and says so; the page then asks
+  // for the pod by hand and proves it with a sign-in, as before.
+  if (pathname === '/api/agent' && request.method === 'GET') {
+    if (!ctx.agentControl) return j(501, { error: 'this server does not run identities' });
+    if (!ctx.webIdsFromSession) return j(200, { offered: true, session: 'unknown' });
+    if (!sameOriginRequest(request, ctx.frontOrigin)) return j(200, { offered: true, session: 'none' });
+    const webIds = await ctx.webIdsFromSession(request).catch(() => []);
+    if (!webIds.length) return j(200, { offered: true, session: 'none', loginUrl: '/.account/login/password/' });
+    const pods = [];
+    for (const webId of webIds) {
+      let podBase;
+      try { podBase = podBaseOfWebId(webId); } catch { continue; }
+      let about = null;
+      try { about = ctx.agentControl.describe ? await ctx.agentControl.describe({ podBase }) : null; } catch { about = null; }
+      pods.push({ webId, podBase, ...(about || {}) });
+    }
+    return j(200, { offered: true, session: 'ok', pods });
+  }
+
   // Runtime opt-in: a pod owner asks the server this front sits on to RUN
   // their identity. Same proof as attach — a Solid-OIDC token — but the
   // ownership check is stricter: the WebID must live UNDER the pod base, not
@@ -540,15 +674,27 @@ async function route(request, ctx) {
     if (/(^|\/)\.internal(\/|$)/u.test(podUrl.pathname) || /(^|\/)\.\.(\/|$)/u.test(podUrl.pathname)) {
       return j(403, { error: 'that is not a pod address' });
     }
-    const webid = await verifyPodToken(request, pathname, ctx.verifier);
-    if (!webid) return j(401, { error: 'a Solid-OIDC token proving the pod is required' });
     // The pod's own server names its owner when it can, and where it does that
     // is the proof. Where it does not, the WebID must live in EXACTLY this pod
     // — its own pod base equal to podBase, not merely starting with it, which on
     // a path server an ancestor of another's pod would.
     const owners = await podOwners(podBase, ctx.fetchImpl || fetch);
-    const proven = owners.length ? owners.includes(webid) : podBaseOfWebId(webid) === podBase;
-    if (!proven) {
+    const ownsIt = (who) => (owners.length ? owners.includes(who) : podBaseOfWebId(who) === podBase);
+    const token = await verifyPodToken(request, pathname, ctx.verifier);
+    // A server that issued the reader's own session can simply read it. On a
+    // pod server the page, the session and the pod are one origin, and a token
+    // proves nothing the session does not — so opting in cost a round trip to
+    // an identity provider that had just said who they were. A Gateway fronting
+    // somebody else's pod holds no such session and this does nothing there.
+    //
+    // One account can hold several WebIDs, so it is the one that owns this pod
+    // that is taken, not whichever came back first.
+    const session = !token && ctx.webIdsFromSession && sameOriginRequest(request, ctx.frontOrigin)
+      ? (await ctx.webIdsFromSession(request).catch(() => [])).find(ownsIt) || null
+      : null;
+    const webid = token || session;
+    if (!webid) return j(401, { error: 'a Solid-OIDC token proving the pod is required' });
+    if (!ownsIt(webid)) {
       return j(403, { error: 'the token proves a different pod than the one you listed' });
     }
     if (action === 'opt-in') {
@@ -578,10 +724,12 @@ async function route(request, ctx) {
   if (mPageScript) {
     const body = ctx.pageScripts?.[`${mPageScript[1]}.js`];
     if (!body) return notFound();
-    return { status: 200, headers: { 'content-type': 'text/javascript; charset=utf-8' }, body };
+    // Revalidated on every load: a page served fresh with a script the
+    // browser kept from last time is the mismatch nobody can see.
+    return { status: 200, headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' }, body };
   }
 
-  // The vendored Solid-OIDC browser library the /run and /admin pages load —
+  // The vendored Solid-OIDC browser library the opt-in and admin pages load —
   // served here because this function owns every path on the domain.
   if (pathname === '/solid-oidc-client.js') {
     if (!ctx.authBundle) return notFound();
@@ -606,10 +754,15 @@ async function route(request, ctx) {
     // is the alias, so a client signing in by the fronted address can find
     // the pod (and its login) without a lookup only the host could answer.
     const podActor = rec.inboxOnly ? [] : [rec.podHome + 'ap/actor'];
-    const out = j(200, jrd({ handle: m[1], host: ctx.host, actor: rec.actorUrl, aliases: podActor, page: profilePageOf(rec) }),
-      'application/jrd+json');
+    const out = j(200, jrd({ handle: m[1], host: ctx.host, actor: rec.actorUrl, aliases: podActor,
+      page: profilePageOf(rec), subscribe: subscribeTemplate(ctx.frontOrigin) }),
+    'application/jrd+json');
     // RFC 7033: a JRD is read from any origin.
     out.headers['access-control-allow-origin'] = '*';
+    // A handle answers the same for everybody, and changes only when a row
+    // does. Every server that has heard of this account asks for it; the edge
+    // can answer most of them.
+    Object.assign(out.headers, publicFor(WEBFINGER_EDGE_SECONDS));
     return out;
   }
 
@@ -692,6 +845,14 @@ async function route(request, ctx) {
   // Everything else is a public GET, served by reading the user's pod and
   // rewriting pod ids to the front. The actor also gets its handle and inbox
   // fixed to the front so a consumer cross-checks it consistently.
+  // Public documents are read from any origin — a page on another site, the
+  // forum's own host among them — the way a pod serves them, so the read
+  // carries the open origin and a preflight is answered.
+  const open = { 'access-control-allow-origin': '*' };
+  if (request.method === 'OPTIONS') {
+    return { status: 204, headers: { ...open, 'access-control-allow-methods': 'GET, HEAD, OPTIONS',
+      'access-control-allow-headers': 'Accept', 'access-control-max-age': '86400', allow: 'GET, HEAD, OPTIONS' }, body: null };
+  }
   if (request.method !== 'GET' && request.method !== 'HEAD') return { status: 405, headers: {}, body: '' };
   const podTarget = rec.podHome + up.rest;
   // Media stays on the pod (lib/pod/urls.mjs keeps `media` off the front), but
@@ -705,10 +866,17 @@ async function route(request, ctx) {
   // directly (the CSS server component) has no access control of its own and
   // needs to be told what it may reach. See podHomeProblem above for the other
   // half — a row that names something which is not a pod.
+  // A container is Turtle, a profile page is HTML, everything else here is
+  // ActivityPub. Ask for what the thing can be, not for what most of them are.
+  const container = podTarget.endsWith('/');
+  const page = /\.html?$/u.test(podTarget);
+  const accept = container ? 'text/turtle, */*;q=0.8'
+    : page ? 'text/html, */*;q=0.8'
+      : AP_CT;
   const got = await podRoot.readPublicDocument(
-    ctx.podGet || ((u) => fetch(u, { headers: { accept: AP_CT } })),
-    podTarget, { podHome: rec.podHome });
-  if (got.text === null) return { status: got.status, headers: {}, body: '' };
+    ctx.podGet || ((u) => fetch(u, { headers: { accept } })),
+    podTarget, { podHome: rec.podHome, accept });
+  if (got.text === null) return { status: got.status, headers: open, body: '' };
   let text = got.text;
   text = swap(text, rec.podHome, base);
   if (up.rest === 'ap/actor') {
@@ -720,7 +888,11 @@ async function route(request, ctx) {
       text = JSON.stringify(doc);
     } catch { /* leave the rewritten text as-is if it will not parse */ }
   }
-  return { status: 200, headers: { 'content-type': AP_CT, 'cache-control': 'no-store' }, body: text };
+  // `readPublicDocument` asked for it with no credential, so a document that
+  // came back is one anybody can read — which is what makes it cacheable.
+  return { status: 200,
+    headers: { ...open, 'content-type': got.type || (container ? 'text/turtle' : page ? 'text/html' : AP_CT), ...publicFor(PUBLIC_EDGE_SECONDS) },
+    body: text };
 }
 
 export const _internal = { parseUserPath, identFor, swap, handleProblem, policyFor, policyCache };

package/lib/pod/root.mjs

@@ -94,8 +94,11 @@ export async function probeAnswers(podUrl, fetchImpl = fetch) {
  *
  * ---- asked by: a front publishing a pod's public face under its own name ----
  */
-export async function readPublicDocument(getter, podTarget, { podHome, maxBytes = PUBLIC_DOC_MAX_BYTES } = {}) {
-  const res = await getter(podTarget, { podHome });
+export async function readPublicDocument(getter, podTarget, { podHome, accept = null, maxBytes = PUBLIC_DOC_MAX_BYTES } = {}) {
+  const res = await getter(podTarget, { podHome, accept });
   if (!res || res.status >= 400) return { status: res?.status || 502, text: null };
-  return { status: 200, text: await readCapped(res, maxBytes) };
+  // What the pod called it: a front that relabels an HTML page as JSON hands
+  // a browser something it will not render.
+  const type = res.headers?.get?.('content-type') || null;
+  return { status: 200, text: await readCapped(res, maxBytes), type };
 }

package/lib/pod/transport.mjs

@@ -309,7 +309,7 @@ export class PodTransport {
   // leaves the private trees world-readable. $rdf.sym() also throws on an
   // illegal IRI, so a pod URL with something odd in it fails here rather than
   // silently producing a document that means something else.
-  aclDoc(targetUrl, publicModes, { appendAgents = [], aclUrl = null } = {}) {
+  aclDoc(targetUrl, publicModes, { appendAgents = [], readAgents = [], aclUrl = null } = {}) {
     const url = aclUrl || targetUrl + '.acl';
     const doc = $rdf.sym(url);
     const target = $rdf.sym(targetUrl);
@@ -328,6 +328,10 @@ export class PodTransport {
     // locked to a gateway — public loses Append, the gateway's WebID keeps it.
     appendAgents.forEach((webId, i) =>
       authorize($rdf.sym(url + `#gw${i}`), ACL('agent'), $rdf.sym(webId), ['Append']));
+    // Named agents granted Read but not public: this is how a forum's
+    // moderators read a queue that names people, without it being public.
+    readAgents.forEach((webId, i) =>
+      authorize($rdf.sym(url + `#r${i}`), ACL('agent'), $rdf.sym(webId), ['Read']));
     authorize($rdf.sym(url + '#owner'), ACL('agent'), $rdf.sym(this.webId),
       ['Read', 'Write', 'Control']);
     return $rdf.serialize(doc, g, url, 'text/turtle');

package/lib/session/README.md

@@ -0,0 +1,123 @@
+# fediverse-account
+
+The library lets an app take a Fediverse handle or a WebID and act as that
+account.
+
+- **`login`** — sends the person to wherever their account signs in, their
+  Mastodon server or their pod, and brings them back to where they were.
+- **`resume`** — on every page load, finishes a sign-in they are coming back
+  from. Otherwise does nothing.
+- **`current`** — the signed-in account, or nothing.
+- **`signOut`** — signs them out, at their server or pod as well as in the
+  browser.
+- **`describe`** — says what an address is without signing in: a Mastodon
+  account or a pod account, and its handle.
+
+Once signed in, the account gives you:
+
+- **`post`** — publishes a post as them, public, unlisted or followers-only.
+- **`reply`** — answers a post.
+- **`timeline`** — their home timeline, newest first.
+- **`follow`** — follows someone by handle.
+- **`favourite`**, **`boost`** — as they say.
+- **`profile`** — who they are as their server or pod shows them: name,
+  handle, picture, bio, counts, profile page, and the WebID for a pod
+  account.
+- **`notice`** — a sentence to show them, or nothing. A browser-based
+  FediPod account gets: "Because you have a browser-based account, your
+  posts and interactions will only go out to the Fediverse when your browser
+  is opened to your account."
+- **`handle`, `name`, `kind`** — who they are, and whether the account is on
+  Mastodon or a pod, for an app that wants to know.
+- **`signOut`** — the same as above.
+
+The app never asks which kind it has. A Mastodon account acts at once. A
+pod account's actions are carried out by its own agent, at once for a
+DeviceAgent or Server account, and when fedipod.net is next open for a
+browser-based one.
+
+Three files, no dependencies. It runs in a page and in a service worker.
+
+[The demo](https://jeff-zucker.github.io/FediPod/) shows the sign-in and
+the profile that comes back.
+
+## Get it
+
+From a CDN, with nothing to install:
+
+```js
+import { fediAccount } from 'https://cdn.jsdelivr.net/npm/fediverse-account@0.1.0/fedi-account.mjs';
+```
+
+Or from npm:
+
+```bash
+npm install fediverse-account
+```
+
+```js
+import { fediAccount } from 'fediverse-account';
+```
+
+## Use
+
+```js
+import { fediAccount } from 'fediverse-account';
+const accounts = fediAccount({ dbName: 'my-app', clientName: 'My app' });
+
+await accounts.resume();                                   // on every page load
+
+signInButton.onclick = () => accounts.login(addressField.value);
+
+const me = await accounts.current();                       // null when nobody is signed in
+if (me?.notice) show(me.notice);
+await me.post({ text: 'Hello from my app' });
+for (const p of await me.timeline({ limit: 20 })) render(p);
+await me.follow('@aisha@her.server');
+await me.reply(p.url, 'Well said');
+await me.signOut();
+```
+
+## The details
+
+- **`fediAccount({ dbName, clientName })`** — sets the library up for your
+  app, once. `dbName` keeps this app's sign-ins apart from another app's on
+  the same origin. `clientName` is what the person sees on the consent
+  screen.
+- **`login(address, { returnTo, redirectUri })`** — `@kwame@mastodon.social`
+  goes to Mastodon; `@mei@fedipod.net`, or a WebID, goes to the pod. They
+  come back to this page unless `redirectUri` says otherwise, and are
+  returned to where they were unless `returnTo` says otherwise.
+- **`post({ text, inReplyTo, visibility })`** — `visibility` is `public`,
+  `unlisted` or `followers`.
+- **`reply(post, text)`** — the post is named by its address or its id.
+- **`timeline({ limit })`** — each post as `{ id, url, author: { id, handle,
+  name }, html, published, inReplyTo }`.
+- **`fetch`** — the raw authenticated fetch, for anything the above does not
+  cover.
+- **`actor`** — the account's ActivityPub id.
+
+Every action answers `{ sent: true }` when the server did it, or `{ queued:
+true }` when the account's own agent will carry it out.
+
+## What it cannot do
+
+- **An address whose server is neither a Mastodon-family server nor a Solid
+  pod** is refused with a sentence naming the host.
+- **A browser-based FediPod account acts when its browser is open.** Posts,
+  follows and replies wait at the account's outbox until fedipod.net is next
+  open in some browser, and its timeline is the one that browser last built.
+  The account's `notice` says so; show it.
+- **A Mastodon account has no pod.** An app that keeps things on a pod has
+  nowhere to keep them for such a person.
+
+## Where the sign-in goes, and what stays in the browser
+
+A Mastodon account signs in at its own server, which asks the person to
+approve your app once. The token it grants stays in their browser and is
+handed back to the server at sign-out.
+
+A pod account signs in at the pod's login provider. The key that proves the
+sign-in is made in the browser and cannot be read out of it, even by a
+script on the page. The person stays signed in across browser restarts
+until they sign out, and sign-out is reported to the provider.

package/lib/session/demo.html

@@ -0,0 +1,94 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Act as a Fediverse account</title>
+<link rel="stylesheet" href="../../web/admin/tokens.css">
+<style>
+  body { font-family: var(--font, Arial, Helvetica, sans-serif); background: var(--bg); color: var(--fg); margin: 0; padding: .75rem 1rem 2rem; }
+  main { max-width: 44rem; margin: 0 auto; }
+  h1 { margin-top: .5rem; }
+  form { display: flex; gap: .75rem; flex-wrap: wrap; align-items: end; margin: 1.25rem 0; }
+  label { display: flex; flex-direction: column; gap: .35rem; flex: 1 1 18rem; }
+  input { font: inherit; padding: .6rem .8rem; background: var(--field-bg); color: var(--field-text); border: 1px solid var(--field-border); border-radius: .4rem; }
+  button { font: inherit; padding: .6rem 1.2rem; background: var(--btn); color: var(--btn-text); border: 1px solid var(--btn-edge); border-radius: .4rem; cursor: pointer; }
+  button:hover { background: var(--btn-hover); }
+  a { color: var(--link); }
+  .kinds { padding-left: 1.4rem; margin: .75rem 0 1.25rem; } .kinds li { margin: .4rem 0; }
+  :focus-visible { outline: 3px solid var(--focus); outline-offset: 2px; }
+  .skip { position: absolute; left: -999px; } .skip:focus { left: 1rem; top: 1rem; }
+  #status, #profile { padding: 1rem 1.2rem; border: 1px solid var(--line); border-radius: .4rem; background: var(--surface); margin: 1rem 0; }
+  #status { min-height: 1.5em; }
+  #status[data-kind="error"] { border-color: var(--err); }
+  #status[hidden] { display: none; }
+  #profile { display: grid; grid-template-columns: auto 1fr; gap: .5rem 1.2rem; align-items: start; }
+  #profile img { width: 5rem; height: 5rem; border-radius: .6rem; object-fit: cover; background: var(--raised); }
+  #profile dl { margin: 0; display: grid; grid-template-columns: max-content 1fr; gap: .3rem 1rem; }
+  #profile dt { font-weight: bold; } #profile dd { margin: 0; overflow-wrap: anywhere; }
+  section[hidden] { display: none; }
+</style>
+</head>
+<body>
+<a href="#main" class="skip">Skip to content</a>
+<main id="main">
+  <h1>Act as a Fediverse account</h1>
+  <p>Type an address and you are sent to wherever that account signs in, then come back here signed in as it. Any of these works:</p>
+  <ul class="kinds">
+    <li><strong>A FediPod handle</strong> — <code>@jeff@fedipod.net</code> — signs in at your Solid pod</li>
+    <li><strong>Other Fediverse handle</strong> — <code>@you@mastodon.social</code> — signs in at your server</li>
+    <li><strong>A WebID</strong> — <code>https://you.solidcommunity.net/profile/card#me</code> — signs in at your Solid pod</li>
+  </ul>
+  <p>This demo is created with the <a href="https://github.com/jeff-zucker/FediPod/tree/main/lib/session">fediverse-account</a> library. Once signed in, the demo shows you your profile. The library itself returns an account session with methods to post, reply, like, etc.</p>
+  <form id="form">
+    <label>Your address
+      <input id="address" name="address" type="text" autocomplete="username" placeholder="@you@your.server" required>
+    </label>
+    <button type="submit" id="go">Sign in</button>
+    <button type="button" id="out" hidden>Sign out</button>
+  </form>
+  <p id="status" role="status" aria-live="polite">Not signed in.</p>
+  <section id="acting" hidden aria-labelledby="profile-h">
+    <h2 id="profile-h">Profile</h2>
+    <div id="profile"></div>
+  </section>
+</main>
+<script type="module">
+  import { fediAccount } from './fedi-account.mjs';
+  const accounts = fediAccount({ dbName: 'fedi-account-demo', clientName: 'Fediverse account demo' });
+  const $ = (id) => document.getElementById(id);
+  const say = (text, kind = '') => { $('status').hidden = false; $('status').textContent = text; $('status').dataset.kind = kind; $('status').setAttribute('role', kind === 'error' ? 'alert' : 'status'); };
+  const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  const link = (u) => (u ? `<a href="${esc(u)}">${esc(u)}</a>` : '—');
+  const showProfile = async (me) => {
+    try {
+      const p = await me.profile();
+      $('profile').innerHTML = `${p.avatar ? `<img src="${esc(p.avatar)}" alt="">` : '<span></span>'}
+        <dl>
+          <dt>Name</dt><dd>${esc(p.name || '—')}</dd>
+          <dt>Handle</dt><dd>${esc(p.handle || '—')}</dd>
+          <dt>Kind</dt><dd>${me.kind === 'pod' ? 'a FediPod account on a Solid pod' : 'a Mastodon account'}</dd>
+          <dt>Bio</dt><dd>${p.bio || '—'}</dd>
+          <dt>Counts</dt><dd>${p.posts ?? '?'} posts, ${p.followers ?? '?'} followers, ${p.following ?? '?'} following</dd>
+          <dt>Profile page</dt><dd>${link(p.url)}</dd>
+          <dt>Actor</dt><dd>${link(p.actor)}</dd>
+          ${p.webId ? `<dt>WebID</dt><dd>${link(p.webId)}</dd>` : ''}
+        </dl>`;
+    } catch (e) { $('profile').textContent = `The profile could not be read: ${e.message}`; }
+  };
+  const show = async () => {
+    const me = await accounts.current();
+    $('out').hidden = !me; $('acting').hidden = !me; $('status').hidden = !!me;
+    if (!me) { say('Not signed in.'); $('profile').innerHTML = ''; return; }
+    await showProfile(me);
+  };
+  try { await accounts.resume(); } catch (e) { say(e.message, 'error'); }
+  await show();
+  $('form').addEventListener('submit', async (e) => {
+    e.preventDefault(); say('Finding that account…');
+    try { await accounts.login($('address').value); } catch (err) { say(err.message, 'error'); }
+  });
+  $('out').addEventListener('click', async () => { await accounts.signOut(); await show(); });
+</script>
+</body>
+</html>