fedipod 1.36.6 → 1.40.0

package/lib/gateway/state-api.mjs

@@ -0,0 +1,207 @@
+// state-api.mjs — the owner's browser reaching its account's copy at the
+// gateway (copy.mjs).
+//
+//   POST /api/state/open             the owner, proved with the pod sign-in:
+//                                    makes the copy if there is none yet, and
+//                                    answers where it is and a token for it
+//   GET  /api/state/<handle>/        what the copy holds
+//   GET  /api/state/<handle>/<name>  one document (ETag, If-None-Match)
+//   PUT  /api/state/<handle>/<name>  one document, from the lease's holder
+//   DELETE …                         the same
+//   GET/PUT /api/state/<handle>/lease.json   the copy's lease (If-Match)
+//   POST /api/state/<handle>/leave   the copy written to the pod and given up,
+//                                    before the owner stops the gateway keeping
+//                                    the account running
+//
+// The token is the gateway's own, signed with a secret only it knows, and
+// names the account and the WebID that asked; it lasts a day. The signing key
+// and the passwords of accounts elsewhere are refused here: the copy does not
+// hold them, and the browser reads them from the pod.
+import crypto from 'node:crypto';
+import { HttpStorage } from '../core/storage.mjs';
+import { CopyStorage, copyMeta, fillCopy, dropCopy, forgetCopy, holds, lockCopy, kvDocFetch, podOnly, safeName, safeHandle, keptBefore } from './copy.mjs';
+
+const TOKEN_MS = 24 * 3600_000;
+const b64 = (s) => Buffer.from(s).toString('base64url');
+const sign = (secret, body) => crypto.createHmac('sha256', secret).update(body).digest('base64url');
+
+export function stateToken(secret, { handle, webId }, now = Date.now()) {
+  const body = b64(JSON.stringify({ h: handle, w: webId, e: now + TOKEN_MS }));
+  return { token: `${body}.${sign(secret, body)}`, expiresAt: now + TOKEN_MS };
+}
+
+export function readStateToken(secret, token, now = Date.now()) {
+  const [body, mac] = String(token || '').split('.');
+  if (!body || !mac) return null;
+  const want = Buffer.from(sign(secret, body));
+  const got = Buffer.from(mac);
+  if (want.length !== got.length || !crypto.timingSafeEqual(want, got)) return null;
+  try {
+    const t = JSON.parse(Buffer.from(body, 'base64url').toString());
+    return t.e > now ? { handle: t.h, webId: t.w } : null;
+  } catch { return null; }
+}
+
+// Where an account's state is on its pod.
+export const stateUrlOf = (rec) => `${rec.podHome.replace(/\/?$/u, '/')}ap-state/`;
+
+// Whether this gateway can keep a copy for this account at all.
+export const keepsCopies = (ctx) => !!(ctx.copyKv && ctx.keeperWebId && ctx.keeperFetch && ctx.stateSecret);
+
+const FILL_RETRY_MS = 5 * 60_000;
+
+/**
+ * The copy for an account, made from the pod when there is none: one maker at
+ * a time, and after a failed attempt not again for five minutes, so an app
+ * checking in every minute does not read the pod every minute. `owner`: the
+ * owner's own browser asking, which is not made to wait. Returns { ok } or
+ * { ok: false, status, why }.
+ */
+export async function ensureCopy(ctx, handle, rec, log = console.log, { owner = false } = {}) {
+  if (await copyMeta(ctx.copyKv, handle)) return { ok: true };
+  const failedAt = Number((await ctx.copyKv.get(`${handle}/fill-failed-at`))?.text || 0);
+  if (!owner && Date.now() - failedAt < FILL_RETRY_MS) {
+    return { ok: false, status: 503, why: 'this account could not be opened a moment ago; try again in a few minutes' };
+  }
+  const podFetch = await ctx.keeperFetch();
+  if (!podFetch) return { ok: false, status: 501, why: 'this gateway cannot reach pods for accounts' };
+  const unlock = await lockCopy(ctx.copyKv, handle);
+  if (!unlock) return { ok: false, status: 503, why: 'the gateway is busy with this account; try again' };
+  try {
+    if (await copyMeta(ctx.copyKv, handle)) return { ok: true };
+    // Marked failed before it starts and cleared when it is done, so an attempt
+    // cut off part way (a request's time running out) counts as failed too.
+    await ctx.copyKv.set(`${handle}/fill-failed-at`, String(Date.now())).catch(() => {});
+    const stateUrl = stateUrlOf(rec);
+    const made = await fillCopy(ctx.copyKv, handle, { pod: new HttpStorage(stateUrl, podFetch), podFetch, stateUrl, webId: rec.webId, log })
+      .catch((e) => ({ ok: false, why: e.message }));
+    if (made.ok) { await ctx.copyKv.delete(`${handle}/fill-failed-at`).catch(() => {}); return { ok: true }; }
+    return { ok: false, status: /active on another device/.test(made.why) ? 409 : 502, why: made.why };
+  } finally { await unlock(); }
+}
+
+/** Write the copy to the pod and give it up. Returns { ok } or { ok: false, why }. */
+export async function leaveCopy(ctx, handle, rec, log = console.log) {
+  if (!await copyMeta(ctx.copyKv, handle)) return { ok: true };
+  const podFetch = await ctx.keeperFetch();
+  if (!podFetch) return { ok: false, why: 'this gateway cannot reach the pod now' };
+  const release = await lockCopy(ctx.copyKv, handle);
+  if (!release) return { ok: false, why: 'the gateway is busy with this account; try again' };
+  try {
+    const stateUrl = stateUrlOf(rec);
+    return await dropCopy(ctx.copyKv, handle, { pod: new HttpStorage(stateUrl, podFetch), podFetch, stateUrl, log });
+  } finally { await release(); }
+}
+
+const j = (status, obj) => ({ status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }, body: JSON.stringify(obj) });
+
+export async function routeStateApi(request, pathname, ctx, deps) {
+  if (!pathname.startsWith('/api/state/')) return null;
+  if (!keepsCopies(ctx)) return j(501, { error: 'this gateway keeps no copies of accounts' });
+
+  if (pathname === '/api/state/open') {
+    if (request.method !== 'POST') return j(405, { error: 'POST' });
+    const webid = await deps.verifyPodToken(request, pathname, ctx.verifier);
+    if (!webid) return j(401, { error: 'a Solid-OIDC token proving the pod is required' });
+    let body = {};
+    try { body = JSON.parse((await request.clone().text()) || '{}'); } catch { return j(400, { error: 'bad JSON' }); }
+    // The account: named, or the one browser account kept here for this WebID.
+    let handle = String(body.handle || '').toLowerCase();
+    let rec = handle ? await ctx.lookup(handle) : null;
+    if (!handle) {
+      const rows = Object.entries(await ctx.listDirectory?.() || {})
+        .filter(([, r]) => r?.webId === webid && r.openedAt && r.keeper && !r.movedTo && !r.closedAt);
+      if (rows.length > 1) return j(409, { error: 'more than one account here for this sign-in; name one', handles: rows.map(([h]) => h) });
+      if (rows.length === 1) [[handle, rec]] = rows;
+    }
+    if (!rec) return j(404, { error: 'no account kept here for this sign-in' });
+    if (rec.webId !== webid) return j(403, { error: "the token proves a different pod than this account's" });
+    if (rec.movedTo || rec.closedAt) return j(410, { error: 'this address is not here any more' });
+    if (!rec.keeper) return j(409, { error: 'the gateway does not keep this account running' });
+    // Kept under a former identity: a copy that is still here is opened so its
+    // owner can hand it over; none is made under the new identity until the
+    // owner's rules name it.
+    const before = keptBefore(ctx, rec);
+    if (before && !await copyMeta(ctx.copyKv, handle)) return j(409, { error: 'kept under the gateway\'s former identity', moving: true });
+    const made = before ? { ok: true } : await ensureCopy(ctx, handle, rec, console.log, { owner: true });
+    if (!made.ok) return j(made.status, { error: made.why, busy: made.status === 409 });
+    const origin = new URL(request.url).origin;
+    const { token, expiresAt } = stateToken(ctx.stateSecret, { handle, webId: webid });
+    return j(200, { ok: true, handle, base: `${origin}/api/state/${encodeURIComponent(handle)}/`, token, expiresAt,
+      podHome: rec.podHome, moving: before });
+  }
+
+  const m = /^\/api\/state\/([^/]+)\/(.*)$/u.exec(pathname);
+  if (!m) return j(404, { error: 'no such route' });
+  let handle; let name;
+  try { handle = decodeURIComponent(m[1]).toLowerCase(); name = decodeURIComponent(m[2] || ''); } catch { return j(400, { error: 'bad path' }); }
+  // Plain names only: a name is part of a storage key, and a path in it would
+  // reach outside the account (copy.mjs).
+  if (!safeHandle(handle) || (name && !['leave', 'forget', 'lease.json'].includes(name) && !safeName(name))) return j(400, { error: 'not a state document' });
+  const bearer = /^Bearer (.+)$/u.exec(request.headers.get('authorization') || '')?.[1];
+  const who = readStateToken(ctx.stateSecret, bearer);
+  if (!who || who.handle !== handle) return j(401, { error: 'a token for this account is required' });
+  // The token is the owner's who asked for it; an address given up and taken
+  // by somebody else is not theirs any more.
+  const owned = await ctx.lookup(handle);
+  if (!owned || owned.webId !== who.webId) return j(401, { error: 'this token is not for this account' });
+  if (!await copyMeta(ctx.copyKv, handle)) return j(404, { error: 'the gateway keeps no copy of this account now', gone: true });
+  const kv = ctx.copyKv;
+  const noStore = { 'cache-control': 'no-store' };
+
+  if (name === 'leave') {
+    if (request.method !== 'POST') return j(405, { error: 'POST' });
+    const left = await leaveCopy(ctx, handle, owned).catch((e) => ({ ok: false, why: e.message }));
+    return left.ok ? j(200, { ok: true }) : j(502, { error: `the copy could not be written to the pod: ${left.why}` });
+  }
+  // The owner's browser has written the copy to the pod itself (a copy kept
+  // under the gateway's former identity, which cannot write it back now).
+  // Only the lease's holder may say so, and only for such a copy.
+  if (name === 'forget') {
+    if (request.method !== 'POST') return j(405, { error: 'POST' });
+    if (!keptBefore(ctx, owned)) return j(409, { error: 'this copy is written back by the gateway; ask to leave instead' });
+    const holder = request.headers.get('x-fedipod-holder') || '';
+    if (!holder || !await holds(kv, handle, holder)) return j(409, { error: 'only the agent holding this account may say so' });
+    await forgetCopy(kv, handle, { log: console.log });
+    return j(200, { ok: true });
+  }
+  if (name === 'lease.json') {
+    if (request.method !== 'GET' && request.method !== 'PUT') return j(405, { error: 'GET or PUT' });
+    const res = await kvDocFetch(kv, `${handle}/lease`)(null, {
+      method: request.method,
+      headers: { 'if-match': request.headers.get('if-match') || undefined },
+      body: request.method === 'PUT' ? await request.text() : undefined,
+    });
+    return { status: res.status, headers: { ...noStore, ...(res.headers.get('etag') ? { etag: res.headers.get('etag') } : {}),
+      ...(res.status === 200 ? { 'content-type': 'application/json' } : {}) }, body: res.status === 200 ? await res.text() : null };
+  }
+  if (name && podOnly(name)) return j(403, { error: 'this document is kept on the pod only' });
+
+  const holder = request.headers.get('x-fedipod-holder') || null;
+  const copy = new CopyStorage(kv, handle, { holder });
+  const ifNone = request.headers.get('if-none-match') || null;
+  if (!name) {
+    if (request.method !== 'GET') return j(405, { error: 'GET' });
+    const l = await copy.list('', { etag: ifNone });
+    if (l.notModified) return { status: 304, headers: { ...noStore, etag: l.etag }, body: null };
+    return { status: 200, headers: { ...noStore, 'content-type': 'application/json', etag: l.etag }, body: JSON.stringify({ names: l.names }) };
+  }
+  if (request.method === 'GET') {
+    const r = await copy.read(name, { etag: ifNone });
+    if (r.notModified) return { status: 304, headers: { ...noStore, etag: r.etag }, body: null };
+    if (!r.ok) return j(404, { error: 'no such document' });
+    return { status: 200, headers: { ...noStore, 'content-type': 'application/json', etag: r.etag }, body: r.body };
+  }
+  if (request.method === 'PUT') {
+    if (!holder) return j(400, { error: 'x-fedipod-holder is required' });
+    const w = await copy.write(name, await request.text());
+    if (w.lost) return j(409, { error: w.why });
+    if (!w.ok) return j(503, { error: w.why });
+    return { status: 204, headers: { ...noStore, etag: w.etag }, body: null };
+  }
+  if (request.method === 'DELETE') {
+    if (!holder) return j(400, { error: 'x-fedipod-holder is required' });
+    return (await copy.remove(name)) ? { status: 204, headers: noStore, body: null } : j(409, { error: 'another agent holds this account now' });
+  }
+  return j(405, { error: 'GET, PUT or DELETE' });
+}

package/lib/gateway/token-claims.mjs

@@ -0,0 +1,16 @@
+// token-claims.mjs — who a Solid access token says it is for, unchecked.
+//
+// Only for choosing where to send a read that the pod checks anyway: the
+// owner's full outbox lives on the pod under the owner's own rule, so reading
+// the claim decides nothing but the address. Verifying it here would let
+// anyone make the front fetch signing keys from a server they name, on every
+// read.
+
+export function claimedWebId(request) {
+  const token = /^(?:DPoP|Bearer)\s+([\w-]+)\.([\w-]+)\./u.exec(request.headers.get('authorization') || '');
+  if (!token) return null;
+  try {
+    const claims = JSON.parse(Buffer.from(token[2], 'base64url').toString('utf8'));
+    return typeof claims?.webid === 'string' ? claims.webid : null;
+  } catch { return null; }
+}

package/lib/pod/containers.mjs

@@ -63,6 +63,23 @@ export async function provisionPrivate(pod, urls) {
   return true;
 }
 
+/**
+ * The account's standing rules, written again only where the pod's differ:
+ * its folder, its state and its private posts (the owner's alone), and the
+ * notes and media anyone may read. Whoever else a rule names beside the owner
+ * is the transport's to say (a keeper: lib/gateway/keeper.mjs), so this is how
+ * granting or withdrawing one reaches the rules already on the pod.
+ */
+export async function restateRules(pod, urls) {
+  for (const url of [urls.home, urls.state, urls.home + 'ap/private/']) await pod.setAcl(url, [], { ifChanged: true });
+  for (const url of [urls.notes, urls.media]) await pod.setAcl(url, ['Read'], { ifChanged: true });
+  // The public documents that state their own rule — the actor, the
+  // collections and their pages — keep what they grant, with the names updated.
+  for (const child of await pod.listContainer(urls.home + 'ap/')) {
+    if (!child.url.endsWith('/')) await pod.restateAcl(child.url);
+  }
+}
+
 /**
  * Check the private trees are actually private, and put back any that are not.
  *

package/lib/pod/location.mjs

@@ -0,0 +1,52 @@
+// location.mjs — where in a pod an application's container goes.
+//
+// The container's own name is the caller's. The person says which container of
+// their pod holds it, as a path on the pod's own origin: `/` for a subdomained
+// pod, `/jeff/` for a suffixed one, or any container below either. Everything then lives under `<that><name>`, and the root kept is that
+// place relative to the pod.
+
+// The pod's own furniture: its profile, its settings, its well-known documents.
+const RESERVED = new Set(['profile', 'settings', '.well-known']);
+const SEGMENT = /^[A-Za-z0-9._-]+$/u;
+
+/** The prefilled answer: the pod's own root, as a path. */
+export function podRootPath(podBase) {
+  return new URL(podBase).pathname;
+}
+
+/**
+ * The container path someone typed, checked against their pod. Returns
+ * `{ root }` — the root relative to the pod, ending in `name` — or
+ * `{ problem }` saying what is wrong, in words for them.
+ */
+export function rootFromContainer(podBase, typed, name) {
+  const base = new URL(podBase);
+  let path = String(typed ?? '').trim() || base.pathname;
+  if (!path.startsWith('/')) path = '/' + path;
+  if (!path.endsWith('/')) path += '/';
+  if (!path.startsWith(base.pathname)) {
+    return { problem: `that is not in your pod — your pod starts at ${base.pathname}` };
+  }
+  const inside = path.slice(base.pathname.length);
+  const segments = inside.split('/').filter(Boolean);
+  if (segments.some(s => s === '.' || s === '..')) return { problem: 'a container path cannot go up with ..' };
+  if (segments.some(s => !SEGMENT.test(s))) {
+    return { problem: 'container names are letters, digits, dots, dashes and underscores' };
+  }
+  if (segments.length && RESERVED.has(segments[0])) {
+    return { problem: `${base.pathname}${segments[0]}/ belongs to your pod itself — choose another container` };
+  }
+  if (segments.length > 8) return { problem: 'that is nested too deep — eight containers at most' };
+  return { root: (segments.length ? segments.join('/') + '/' : '') + name };
+}
+
+/** Where the account lives, in full: the pod plus its root. */
+export const homeOf = (podBase, root) => podBase + root;
+
+/** The root back from a pod actor's address: `<pod><root>ap/actor`. */
+export function rootOfActor(podBase, actorUrl) {
+  const a = String(actorUrl || '');
+  if (!a.startsWith(podBase) || !a.endsWith('ap/actor')) return null;
+  const root = a.slice(podBase.length, -'ap/actor'.length);
+  return root.endsWith('/') ? root : null;
+}

package/lib/pod/notes.mjs

@@ -57,9 +57,6 @@ export async function writeTombstone(pod, noteId, doc) {
   await pod.setAcl(noteId, PUBLIC_READ);
 }
 
-/** Withdraw the Create. Returns whether the pod actually removed it. */
-export const dropCreate = (pod, createId) => pod.delete(createId).catch(() => false);
-
 /** The replies collection, once the note it belonged to is gone. */
 export const dropReplies = (pod, repliesId) => pod.delete(repliesId).catch(() => {});
 
@@ -73,7 +70,8 @@ export const dropReplies = (pod, repliesId) => pod.delete(repliesId).catch(() =>
 export async function list(pod, urls) {
   const children = await pod.listContainer(urls.notes);
   return children
-    .filter((c) => !/(-create|-replies)$/.test(c.url) && !c.url.endsWith('.keep'))
+    .filter((c) => !/(-create|-replies|-delete|-update-[^/]+)$/.test(c.url) && !/\/(announce|undo)-\d+$/.test(c.url)
+      && !c.url.endsWith('.keep'))
     // A defensive copy: the transport hands back the same array on a 304, so a
     // caller that sorts in place would corrupt it for every later reader.
     .map((c) => ({ ...c }));

package/lib/pod/transport.mjs

@@ -15,6 +15,7 @@
 import * as $rdf from 'rdflib';
 import { readCapped, retryAfterMs } from './http.mjs';
 import { linkTargets, REL } from './links.mjs';
+import { podBaseOfWebId } from './urls.mjs';
 
 const LDP = $rdf.Namespace('http://www.w3.org/ns/ldp#');
 const DC = $rdf.Namespace('http://purl.org/dc/terms/');
@@ -23,6 +24,17 @@ const RDF = $rdf.Namespace('http://www.w3.org/1999/02/22-rdf-syntax-ns#');
 const ACL = $rdf.Namespace('http://www.w3.org/ns/auth/acl#');
 const FOAF = $rdf.Namespace('http://xmlns.com/foaf/0.1/');
 const AS = $rdf.Namespace('https://www.w3.org/ns/activitystreams#');
+const RDFS = $rdf.Namespace('http://www.w3.org/2000/01/rdf-schema#');
+
+// An inserted term must be something a reader can take for what it says it
+// is: an absolute http(s) IRI, or a literal.
+function termProblem(t) {
+  if (t?.termType === 'Literal') return null;
+  if (t?.termType !== 'NamedNode') return `${t?.value ?? t} is not an IRI or a literal`;
+  try {
+    return /^https?:$/.test(new URL(t.value).protocol) ? null : `${t.value} is not an http(s) IRI`;
+  } catch { return `${t.value} is not an absolute IRI`; }
+}
 
 // A pod whose access rules are ACP policies, not WAC authorizations. This
 // library writes WAC; over an ACP resource that would be noise where the pod's
@@ -109,6 +121,14 @@ export class PodTransport {
     // request built from an advertised id lands on the pod — one choke point.
     // Unset → identity, byte-for-byte the unfronted behaviour.
     this.toPod = null;
+    // Whose rules these are. Every rule written names `aclOwner` as its owner
+    // (the transport's own WebID unless told otherwise), and gives each keeper
+    // the same access: a gateway the owner lets act for them while their app
+    // is closed (lib/gateway/keeper.mjs). A keeper writes a rule only when the
+    // pod's differs (`aclIfChanged`), so it restates nothing the owner wrote.
+    this.aclOwner = null;
+    this.keepers = [];
+    this.aclIfChanged = false;
   }
 
   /** Who is talking, and from where — the prefix on every log line and error. */
@@ -332,8 +352,10 @@ export class PodTransport {
     // 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),
+    authorize($rdf.sym(url + '#owner'), ACL('agent'), $rdf.sym(this.aclOwner || this.webId),
       ['Read', 'Write', 'Control']);
+    (this.keepers || []).forEach((webId, i) =>
+      authorize($rdf.sym(url + `#keeper${i}`), ACL('agent'), $rdf.sym(webId), ['Read', 'Write', 'Control']));
     return $rdf.serialize(doc, g, url, 'text/turtle');
   }
 
@@ -349,10 +371,41 @@ export class PodTransport {
     // `ifChanged`: read the rule the pod holds and write only when it differs.
     // For a rule restated at every start — the inbox door — a read is the
     // whole cost, where a write took the pod's lock to say the same thing.
-    if (opts.ifChanged && await this.aclSame(url, doc)) return { status: 304, unchanged: true };
+    if ((opts.ifChanged || this.aclIfChanged) && await this.aclSame(url, doc)) return { status: 304, unchanged: true };
     return this.put(url, doc, 'text/turtle');
   }
 
+  /**
+   * A rule already on the pod, stated again with this transport's owner and
+   * keepers, keeping what it grants the public (#public), agents who may only
+   * append (#gw…) and agents who may only read (#r…). A resource with no rule
+   * of its own inherits one and is left alone; so is a rule with anything this
+   * file did not write, which it cannot restate faithfully.
+   */
+  async restateAcl(targetUrl) {
+    const podTarget = this.toPod ? this.toPod(targetUrl) : targetUrl;
+    const url = await this.aclUrlFor(podTarget);
+    if (!await this.aclWritable(url)) return null;
+    const res = await this.fetch(url, { headers: { accept: 'text/turtle' } });
+    if (res.status !== 200) return null;
+    const g = $rdf.graph();
+    try { $rdf.parse(await res.text(), g, url, 'text/turtle'); } catch { return null; }
+    const modes = (auth) => g.each(auth, ACL('mode'), null).map((m) => m.value.slice(ACL('').value.length));
+    let publicModes = [];
+    const appendAgents = [];
+    const readAgents = [];
+    for (const auth of g.each(null, RDF('type'), ACL('Authorization'))) {
+      const frag = auth.value.includes('#') ? auth.value.slice(auth.value.lastIndexOf('#') + 1) : '';
+      if (frag === 'owner' || /^keeper\d+$/u.test(frag)) continue;
+      if (frag === 'public') { publicModes = modes(auth); continue; }
+      const agent = g.any(auth, ACL('agent'), null)?.value;
+      if (/^gw\d+$/u.test(frag) && agent) { appendAgents.push(agent); continue; }
+      if (/^r\d+$/u.test(frag) && agent) { readAgents.push(agent); continue; }
+      return null;
+    }
+    return this.setAcl(targetUrl, publicModes, { appendAgents, readAgents, ifChanged: true });
+  }
+
   // Whether the pod's rule at `aclUrl` states exactly what `doc` states.
   // Compared as graphs, not bytes: the pod serialises what it holds its own
   // way. Every rule this file writes names its subjects, so triple sets are
@@ -445,16 +498,11 @@ export class PodTransport {
    * written back — an empty or foreign body must never become the new profile.
    */
   async linkAccountInProfile({ actorUrl, accountName, kind = 'person', outbox = null }) {
-    const docUrl = this.webId.split('#')[0];
-    const res = await this.fetch(docUrl, { headers: { accept: 'text/turtle' } });
-    if (res.status >= 400) throw new Error(`[${this.label}] GET ${docUrl} → ${res.status}`);
-    const g = $rdf.graph();
-    $rdf.parse(await res.text(), g, docUrl, 'text/turtle');
-    const doc = $rdf.sym(docUrl);
     const me = $rdf.sym(this.webId);
-    if (!g.statementsMatching(me, null, null, doc).length) {
-      throw new Error(`profile at ${docUrl} does not mention ${this.webId} — not rewriting it`);
-    }
+    const podBase = podBaseOfWebId(this.webId);
+    // The profile and what its seeAlso names: what either says is said.
+    const docs = await this.profileDocs(podBase);
+    const says = (s, p, o) => docs.some(({ g }) => g?.holds(s, p, o));
     const actor = $rdf.sym(actorUrl);
     const wanted = [
       [me, FOAF('account'), actor],
@@ -465,22 +513,24 @@ export class PodTransport {
       // WebID is what dokieli reads); only where a door exists to take it.
       ...(outbox ? [[me, AS('outbox'), $rdf.sym(outbox)]] : []),
     ];
-    const missing = wanted.filter(([s, p, o]) => !g.holds(s, p, o, doc));
+    const missing = wanted.filter(([s, p, o]) => !says(s, p, o));
     // A handle change leaves the old accountName behind; ours is replaced.
     // Likewise an outbox that moved.
-    const stale = [
-      ...g.statementsMatching(actor, FOAF('accountName'), null, doc).filter(st => st.object.value !== accountName),
-      ...(outbox ? g.statementsMatching(me, AS('outbox'), null, doc).filter(st => st.object.value !== outbox) : []),
-    ];
+    const stale = [];
+    for (const { g } of docs) {
+      for (const st of g?.statementsMatching(actor, FOAF('accountName'), null) || []) {
+        if (st.object.value !== accountName) stale.push([st.subject, st.predicate, st.object]);
+      }
+      if (outbox) {
+        for (const st of g?.statementsMatching(me, AS('outbox'), null) || []) {
+          if (st.object.value !== outbox) stale.push([st.subject, st.predicate, st.object]);
+        }
+      }
+    }
     if (!missing.length && !stale.length) return false;
-    // A patch touches these statements and nothing else. Rewriting the whole
-    // profile re-serialises statements that are not ours — the OIDC issuer
-    // among them — and a server is entitled to refuse a write that would.
-    const deletes = stale.map(st => [st.subject, st.predicate, st.object]);
-    if (await this.patchDocument(docUrl, missing, deletes)) return true;
-    for (const st of stale) g.remove(st);
-    for (const [s, p, o] of missing) g.add(s, p, o, doc);
-    await this.put(docUrl, $rdf.serialize(doc, g, docUrl, 'text/turtle'), 'text/turtle');
+    // Checked before it is written, to the profile or else to a document its
+    // seeAlso names (writeAboutWebId); a patch carries only these statements.
+    await this.writeAboutWebId(podBase, { inserts: missing, deletes: stale });
     return true;
   }
 
@@ -522,4 +572,144 @@ export class PodTransport {
     if (res.status === 405 || res.status === 415 || res.status === 501) return false;
     throw new Error(`[${this.label}] PATCH ${docUrl} → ${res.status}`);
   }
+
+  // ---- writing a profile or a type index: valid RDF, or nothing ----
+  //
+  // Two rules. A change is written only if the document it leaves behind is
+  // valid RDF: the graph as it would be afterwards is serialised and parsed
+  // back, and the subject that must stay described still is. And a profile
+  // that will not take a write is not the end: the statements go to the first
+  // document its rdfs:seeAlso names, inside the same pod, that takes them —
+  // under the same check. A profile is what every Solid app signs in through;
+  // one left broken breaks them all. Reading follows the same links.
+
+  /** An IRI or a literal as a term, for the operations that pass plain values. */
+  sym(iri) {
+    try { return $rdf.sym(iri); } catch { throw new Error(`not written: ${iri} is not an absolute IRI`); }
+  }
+  literal(value) { return $rdf.literal(value); }
+
+  /** A document as a graph, or null when it is not there. */
+  async readRdf(docUrl) {
+    const res = await this.fetch(docUrl, { headers: { accept: 'text/turtle' } });
+    if (res.status === 404 || res.status === 410) return null;
+    if (res.status >= 400) throw new Error(`[${this.label}] GET ${docUrl} → ${res.status}`);
+    const g = $rdf.graph();
+    $rdf.parse(await res.text(), g, docUrl, 'text/turtle');
+    return g;
+  }
+
+  /**
+   * The document as it would be after the change, checked. Returns the Turtle
+   * to write, or throws saying why nothing may be written.
+   */
+  checkedRdf(g, docUrl, { inserts = [], deletes = [], mustDescribe = null }) {
+    const doc = $rdf.sym(docUrl);
+    for (const [s, p, o] of inserts) {
+      const bad = termProblem(s) || termProblem(p) || termProblem(o)
+        || (s?.termType === 'Literal' || p?.termType !== 'NamedNode' ? 'a literal subject or predicate' : null);
+      if (bad) throw new Error(`not written: ${bad}`);
+    }
+    const after = $rdf.graph();
+    for (const st of g.statementsMatching(null, null, null, doc)) after.add(st.subject, st.predicate, st.object, doc);
+    for (const [s, p, o] of deletes) for (const st of after.statementsMatching(s, p, o, doc)) after.remove(st);
+    for (const [s, p, o] of inserts) if (!after.holds(s, p, o, doc)) after.add(s, p, o, doc);
+    let text;
+    try { text = $rdf.serialize(doc, after, docUrl, 'text/turtle'); } catch (e) {
+      throw new Error(`not written: ${docUrl} would not serialise (${e.message})`);
+    }
+    const back = $rdf.graph();
+    try { $rdf.parse(text, back, docUrl, 'text/turtle'); } catch (e) {
+      throw new Error(`not written: ${docUrl} would not parse back (${e.message})`);
+    }
+    if (back.statementsMatching(null, null, null, doc).length !== after.statementsMatching(null, null, null, doc).length) {
+      throw new Error(`not written: ${docUrl} would not read back as written`);
+    }
+    if (mustDescribe && !back.statementsMatching($rdf.sym(mustDescribe), null, null, doc).length) {
+      throw new Error(`not written: ${docUrl} would no longer describe ${mustDescribe}`);
+    }
+    return text;
+  }
+
+  /**
+   * Change one document, or refuse. `g` is the document as read (null for a
+   * new one). A PATCH carries only these statements; where the pod cannot
+   * patch, the whole checked document is written. Returns the write's status.
+   */
+  async writeRdfChecked(docUrl, g, { inserts = [], deletes = [], mustDescribe = null }) {
+    const current = g || $rdf.graph();
+    const doc = $rdf.sym(docUrl);
+    const todo = inserts.filter(([s, p, o]) => !current.holds(s, p, o, doc));
+    const gone = deletes.filter(([s, p, o]) => current.holds(s, p, o, doc));
+    if (!todo.length && !gone.length) return 200;
+    const text = this.checkedRdf(current, docUrl, { inserts: todo, deletes: gone, mustDescribe });
+    if (g) {
+      let res = null;
+      try {
+        res = await this.fetch(docUrl, { method: 'PATCH', headers: { 'content-type': 'text/n3' },
+          body: this.n3Patch(docUrl, todo, gone) });
+      } catch { res = null; }
+      if (res && res.status < 300) return res.status;
+      // A pod that cannot patch gets the whole checked document; any other
+      // answer — a refusal, a conflict — is the answer.
+      if (res && ![405, 415, 501].includes(res.status)) return res.status;
+    }
+    const put = await this.fetch(docUrl, { method: 'PUT', headers: { 'content-type': 'text/turtle' }, body: text });
+    return put.status;
+  }
+
+  /**
+   * The profile and the documents its rdfs:seeAlso names inside this pod,
+   * each with its graph, the profile first. What any of them says about the
+   * WebID is what the profile says.
+   */
+  async profileDocs(podBase) {
+    const profileUrl = this.webId.split('#')[0];
+    const g = await this.readRdf(profileUrl);
+    if (!g) throw new Error(`no profile at ${profileUrl}`);
+    const out = [{ url: profileUrl, g, profile: true }];
+    const seen = new Set([profileUrl]);
+    for (const st of g.statementsMatching(null, RDFS('seeAlso'), null)) {
+      const url = st.object.value.split('#')[0];
+      if (seen.has(url) || !url.startsWith(podBase)) continue;       // inside this pod only
+      seen.add(url);
+      out.push({ url, g: await this.readRdf(url).catch(() => null), profile: false });
+    }
+    return out;
+  }
+
+  /** Every value the WebID has for `predicate`, across the profile and its seeAlso documents. */
+  webIdValues(docs, predicate) {
+    const me = $rdf.sym(this.webId);
+    const p = $rdf.sym(predicate);
+    const out = [];
+    for (const { g } of docs) for (const st of g?.statementsMatching(me, p, null) || []) out.push(st.object.value);
+    return [...new Set(out)];
+  }
+
+  /**
+   * Write statements about the WebID: to the profile, or — if the profile will
+   * not take them — to the first of its seeAlso documents that will. Every
+   * write checked. Returns the document written to, or null when nothing
+   * needed writing; throws when none would take it.
+   */
+  async writeAboutWebId(podBase, { inserts = [], deletes = [] }) {
+    const docs = await this.profileDocs(podBase);
+    const holds = ([s, p, o]) => docs.some(({ g }) => g?.holds(s, p, o));
+    const todo = inserts.filter(t => !holds(t));
+    const gone = deletes.filter(holds);
+    if (!todo.length && !gone.length) return null;
+    const refusals = [];
+    for (const d of docs) {
+      const here = gone.filter(([s, p, o]) => d.g?.holds(s, p, o));
+      const status = await this.writeRdfChecked(d.url, d.g, {
+        inserts: todo, deletes: here, mustDescribe: d.profile ? this.webId : null,
+      });
+      if (status < 300) return d.url;
+      refusals.push(`${d.url} → ${status}`);
+      if (status !== 401 && status !== 403) break;                    // a real answer, not "not yours to write"
+    }
+    throw new Error(`not written: neither the profile nor a document it names would take it (${refusals.join('; ')})`);
+  }
+
 }