fedipod 0.14.1 → 0.17.0

package/lib/mastoapi.mjs

@@ -16,6 +16,7 @@ import { sanitizeHtml, followsNeedApproval, publicHandle } from './wire.mjs';
 import { authorOf } from './intake.mjs';
 import { profileUrl, postUrl } from './bskyfeed.mjs';
 import { Push } from './webpush.mjs';
+import { safeFetch, readCapped } from './safefetch.mjs';
 
 // What an attachment is allowed to BE. Anything else is stored as bytes, which
 // a browser downloads rather than runs.
@@ -62,6 +63,8 @@ const AUTHZ_WINDOW_MS = 60_000;
 const AUTHZ_MAX_ATTEMPTS = 5;
 const CODE_TTL_MS = 5 * 60_000;                  // an authorization code is short-lived
 const MAX_APPS = 200;                            // registered third-party clients, capped
+const CLIENT_DOC_TTL_MS = 10 * 60_000;           // how long a fetched client document is trusted
+const CLIENT_DOC_MAX = 64 * 1024;                // it names a client; it is not a payload
 
 export class MastoApi {
   constructor({ agent, log = console.log, allowed = null, scheme = null, embedded = false }) {
@@ -127,7 +130,91 @@ export class MastoApi {
   // said, and only that client, presenting its secret, can exchange it for a
   // bearer. A redirect back to this agent's own origin keeps the local flow.
   apps() { return this.store.read('oauth-apps.json', []); }
+  /**
+   * What a client needs to know before it can sign in, at the address RFC 8414
+   * puts it. The actor carries the same two endpoints; a client that looks
+   * here first finds everything rather than the minimum.
+   *
+   * `none` among the authentication methods is what says a client keeping no
+   * secret is welcome, which is the whole of what a browser app needs to hear.
+   */
+  authorizationServerMetadata(origin) {
+    const at = (p) => `${origin.replace(/\/$/u, '')}${p}`;
+    return {
+      issuer: origin.replace(/\/$/u, ''),
+      authorization_endpoint: at('/oauth/authorize'),
+      token_endpoint: at('/oauth/token'),
+      revocation_endpoint: at('/oauth/revoke'),
+      registration_endpoint: at('/api/v1/apps'),
+      response_types_supported: [ 'code' ],
+      grant_types_supported: [ 'authorization_code' ],
+      code_challenge_methods_supported: [ 'S256', 'plain' ],
+      token_endpoint_auth_methods_supported: [ 'client_secret_post', 'none' ],
+      scopes_supported: [ 'read', 'write', 'follow', 'push' ],
+    };
+  }
+
   findApp(clientId) { return clientId ? this.apps().find(a => a.clientId === clientId) || null : null; }
+
+  /**
+   * A client that publishes its own metadata document is named by that
+   * document's URL and registers nothing here: the document says who it is
+   * and where it may be sent back to. Such a client keeps no secret, so it
+   * always proves itself with a challenge instead.
+   *
+   * The fetch is the guarded one — a client id is a URL a stranger chose, and
+   * an unguarded fetch of it would ask this machine to reach wherever they
+   * pointed.
+   */
+  async resolveClientDocument(clientId) {
+    if (!/^https:\/\//iu.test(String(clientId || ''))) return null;   // cleartext is refused
+    this.clientDocs = this.clientDocs || new Map();
+    const seen = this.clientDocs.get(clientId);
+    if (seen && Date.now() - seen.at < CLIENT_DOC_TTL_MS) return seen.client;
+    let doc;
+    try {
+      const res = await safeFetch(clientId, { headers: { accept: 'application/json' } });
+      if (res.status >= 400) { this.log(`client document ${clientId} → ${res.status}`); return null; }
+      doc = JSON.parse(await readCapped(res, CLIENT_DOC_MAX));
+    } catch (e) {
+      this.log(`client document ${clientId} could not be read: ${e.message}`);
+      return null;
+    }
+    // It must claim to be itself: a document naming some other id would let
+    // one client borrow another's name.
+    if (doc?.client_id !== clientId) {
+      this.log(`client document ${clientId} names ${doc?.client_id ?? 'nothing'} — refused`);
+      return null;
+    }
+    const redirectUris = [].concat(doc.redirect_uris || []).filter((u) => typeof u === 'string');
+    if (!redirectUris.length) { this.log(`client document ${clientId} names no redirect — refused`); return null; }
+    const client = {
+      clientId, redirectUris,
+      name: String(doc.client_name || clientId).slice(0, 200),
+      scopes: 'read write follow',
+    };
+    this.clientDocs.set(clientId, { at: Date.now(), client });
+    return client;
+  }
+
+  /**
+   * Whether a redirect the client asked for is one it published.
+   *
+   * A native client listens on whatever port the machine gave it, so it can
+   * only publish the loopback address without one (RFC 8252). The port is
+   * therefore not part of the match there, and nowhere else.
+   */
+  static redirectMatches(published, asked) {
+    if (published === asked) return true;
+    try {
+      const a = new URL(published);
+      const b = new URL(asked);
+      const loopback = (h) => h === '127.0.0.1' || h === '[::1]' || h === 'localhost';
+      if (!loopback(a.hostname) || a.hostname !== b.hostname) return false;
+      return a.protocol === b.protocol
+        && a.pathname.replace(/\/$/u, '') === b.pathname.replace(/\/$/u, '');
+    } catch { return false; }
+  }
   registerApp({ name, website, redirectUris, scopes }) {
     const app = {
       clientId: crypto.randomBytes(16).toString('hex'),
@@ -143,13 +230,39 @@ export class MastoApi {
   // A short-lived, single-use authorization code for a registered client, kept
   // apart from masto-tokens.json so the code is NOT a bearer until it is
   // exchanged with the client secret.
-  mintCode({ clientId, redirectUri, scope }) {
+  mintCode({ clientId, redirectUri, scope, challenge = null, challengeMethod = null }) {
     const code = crypto.randomBytes(24).toString('hex');
     const now = Date.now();
     const kept = this.store.read('oauth-codes.json', []).filter(c => now - c.createdAt < CODE_TTL_MS);
-    this.store.write('oauth-codes.json', [...kept, { code, clientId, redirectUri, scope, createdAt: now }].slice(-50));
+    this.store.write('oauth-codes.json', [ ...kept, {
+      code, clientId, redirectUri, scope, createdAt: now,
+      // What the client promised to prove when it comes back for the token.
+      // A client that cannot keep a secret — anything running in a browser —
+      // has this instead, and it is the only thing standing between a stolen
+      // code and a token.
+      ...(challenge ? { challenge, challengeMethod: challengeMethod || 'plain' } : {}),
+    } ].slice(-50));
     return code;
   }
+  /**
+   * Whether this verifier is the one the challenge was made from (RFC 7636).
+   * Length is checked because a short verifier is guessable, which is the
+   * whole thing this is here to prevent.
+   */
+  static provesCode(rec, verifier) {
+    const v = String(verifier || '');
+    if (v.length < 43 || v.length > 128) return false;
+    if ((rec.challengeMethod || 'plain') === 'S256') {
+      const made = crypto.createHash('sha256').update(v).digest('base64url');
+      const given = Buffer.from(made);
+      const known = Buffer.from(String(rec.challenge));
+      return given.length === known.length && crypto.timingSafeEqual(given, known);
+    }
+    const given = Buffer.from(v);
+    const known = Buffer.from(String(rec.challenge));
+    return given.length === known.length && crypto.timingSafeEqual(given, known);
+  }
+
   consumeCode(code) {
     const now = Date.now();
     const all = this.store.read('oauth-codes.json', []);
@@ -620,19 +733,35 @@ export class MastoApi {
       if (req.method === 'POST') { body = await readBody(req); params = new URLSearchParams(body); }
       const redirect = params.get('redirect_uri') || '';
       const app = this.findApp(params.get('client_id') || '');
+      // A client that published its own metadata document needs no
+      // registration here: the document is its name and says where it may be
+      // sent back to.
+      const doc = app ? null : await this.resolveClientDocument(params.get('client_id') || '');
       // A REGISTERED client is always the third-party flow — its code is
       // bound to it and exchanged with its secret — even when its redirect
       // points back at this very agent (a web client served from our own
       // origin registers itself exactly like a phone app does). The local
       // code-is-the-token flow is only for the built-in client, which never
       // registers.
-      const external = !!app;
-      const client = { name: app?.name || null, redirect, scope: params.get('scope') || 'read' };
-      if (external) {
+      const external = !!app || !!doc;
+      const client = { name: app?.name || doc?.name || null, redirect, scope: params.get('scope') || 'read' };
+      if (app) {
         if (!app.redirectUris.includes(redirect)) {
           this.log(`authorize refused: redirect_uri "${redirect}" not registered for ${app.clientId}`);
           return send(400, { error: 'redirect_uri was not registered by this client' });
         }
+      } else if (doc) {
+        if (!doc.redirectUris.some((u) => MastoApi.redirectMatches(u, redirect))) {
+          this.log(`authorize refused: redirect_uri "${redirect}" is not one ${doc.clientId} published`);
+          return send(400, { error: 'redirect_uri is not one this client published' });
+        }
+        // It keeps no secret, so the challenge is the only thing that will
+        // stand between its code and a token. Refuse now rather than mint a
+        // code nothing can prove.
+        if (!params.get('code_challenge')) {
+          this.log(`authorize refused: ${doc.clientId} keeps no secret and offered no challenge`);
+          return send(400, { error: 'a client identified by its own document must send a code_challenge' });
+        }
       } else if (!this.redirectAllowed(redirect)) {
         this.log(`authorize refused: redirect_uri "${redirect}" is not this agent`);
         return send(400, { error: 'redirect_uri must be an address of this agent' });
@@ -640,7 +769,11 @@ export class MastoApi {
       if (req.method === 'POST') {
         if (this.rateLimited()) {
           this.log('authorize rate limited');
-          return sendLoginForm(res, params, 'too many attempts — wait a minute', client);
+          // 429, not 401: a client that reads this as a wrong password will
+          // ask the person to type it again, which is the one thing that
+          // cannot help. Retry-After says how long the wait actually is.
+          return sendLoginForm(res, params, 'too many attempts — wait a minute', client,
+            429, { 'retry-after': String(Math.ceil(AUTHZ_WINDOW_MS / 1000)) });
         }
         if (!pw || !checkPassword(pw, body.password || '')) {
           return sendLoginForm(res, params, 'wrong password — try again', client);
@@ -670,7 +803,9 @@ export class MastoApi {
       }
       // External clients get a bound code; the local flow keeps code==token.
       const code = external
-        ? this.mintCode({ clientId: app.clientId, redirectUri: redirect, scope: client.scope })
+        ? this.mintCode({ clientId: (app || doc).clientId, redirectUri: redirect, scope: client.scope,
+          challenge: params.get('code_challenge') || null,
+          challengeMethod: params.get('code_challenge_method') || null })
         : this.mintToken();
       if (!redirect || redirect === 'urn:ietf:wg:oauth:2.0:oob') return send(200, { code });
       const target = new URL(redirect);
@@ -685,6 +820,44 @@ export class MastoApi {
       // A registered third-party client exchanges its bound code, proving its
       // secret, for a real bearer — the code alone is not a token.
       const app = this.findApp(body.client_id || '');
+      // A client named by its own document keeps no secret at all, so the
+      // challenge is the whole of its proof. The code carries the document's
+      // URL as the client it was bound to.
+      if (!app && body.code_verifier && /^https:\/\//iu.test(String(body.client_id || ''))) {
+        const rec = this.consumeCode(body.code || '');
+        if (!rec || rec.clientId !== body.client_id
+          || (body.redirect_uri && rec.redirectUri !== body.redirect_uri)) {
+          this.log('token refused: code is not a live authorization for that client document');
+          return send(400, { error: 'invalid_grant' });
+        }
+        if (!rec.challenge || !MastoApi.provesCode(rec, body.code_verifier)) {
+          this.log('token refused: the verifier does not answer the challenge this code was made with');
+          return send(400, { error: 'invalid_grant' });
+        }
+        return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
+          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
+          ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
+      }
+      // A client that runs in a browser cannot keep a secret, so it proves it
+      // is the same caller that asked instead: it sends the verifier for the
+      // challenge it presented at authorize (RFC 7636). Sending a verifier is
+      // what says which of the two flows this is.
+      if (app && body.code_verifier) {
+        const rec = this.consumeCode(body.code || '');
+        if (!rec || rec.clientId !== app.clientId || (body.redirect_uri && rec.redirectUri !== body.redirect_uri)) {
+          this.log('token refused: code is not a live authorization for this client');
+          return send(400, { error: 'invalid_grant' });
+        }
+        // A code minted without a challenge cannot be redeemed with one: that
+        // would let anyone holding a stolen code invent the proof for it.
+        if (!rec.challenge || !MastoApi.provesCode(rec, body.code_verifier)) {
+          this.log('token refused: the verifier does not answer the challenge this code was made with');
+          return send(400, { error: 'invalid_grant' });
+        }
+        return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
+          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
+          ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
+      }
       if (app && body.client_secret) {
         const given = Buffer.from(String(body.client_secret));
         const known = Buffer.from(app.clientSecret);
@@ -695,8 +868,18 @@ export class MastoApi {
           this.log('token refused: code is not a live authorization for this client');
           return send(400, { error: 'invalid_grant' });
         }
+        // A challenge, once made, is not optional: without this a client could
+        // present one and then skip past it with the secret alone.
+        if (rec.challenge && !MastoApi.provesCode(rec, body.code_verifier)) {
+          this.log('token refused: this code was made with a challenge and the verifier does not answer it');
+          return send(400, { error: 'invalid_grant' });
+        }
         return send(200, { access_token: this.mintToken(), token_type: 'Bearer',
-          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000) });
+          scope: rec.scope || 'read', created_at: Math.floor(Date.now() / 1000),
+          // Which actor the token acts for. A Mastodon client ignores it; an
+          // ActivityPub API client needs it, and asking for it separately
+          // would mean a second round trip before it knows who it is.
+          ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
       }
       // Local flow: the code IS the token, minted by /oauth/authorize after the
       // password gate. Minting one here for an unrecognised code handed a
@@ -707,7 +890,9 @@ export class MastoApi {
         this.log('token refused: code is not a live authorization');
         return send(400, { error: 'invalid_grant' });
       }
-      return send(200, { access_token: body.code, token_type: 'Bearer', scope: body.scope || 'read write follow push', created_at: Math.floor(Date.now() / 1000) });
+      return send(200, { access_token: body.code, token_type: 'Bearer',
+        scope: body.scope || 'read write follow push', created_at: Math.floor(Date.now() / 1000),
+        ...(this.urls?.actor ? { activitypub_actor_id: this.urls.actor } : {}) });
     }
     if (pathname === '/oauth/revoke' && req.method === 'POST') {
       // It used to answer 200 and keep the token, so logging out of a client
@@ -1554,7 +1739,7 @@ const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c =>
 const parseRedirects = (v) => (Array.isArray(v) ? v : String(v || '').split(/\s+/))
   .map(s => s.trim()).filter(Boolean);
 
-function sendLoginForm(res, params, error = '', client = null) {
+function sendLoginForm(res, params, error = '', client = null, status = null, headers = {}) {
   const hidden = [...params.entries()].filter(([k]) => k !== 'password')
     .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`).join('\n');
   // Name what is asking, so the owner approves a client they can see rather
@@ -1569,7 +1754,8 @@ function sendLoginForm(res, params, error = '', client = null) {
       + `${where ? `, sending the authorization to <code>${escapeHtml(where)}</code>` : ''}.</p>`
       + `<p>Scope: <code>${escapeHtml(client.scope || 'read')}</code>. Enter the agent password to allow it.</p>`;
   }
-  res.writeHead(error ? 401 : 200, { 'content-type': 'text/html; charset=utf-8' });
+  res.writeHead(status || (error ? 401 : 200),
+    { 'content-type': 'text/html; charset=utf-8', ...headers });
   res.end(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
 <title>FediPod — authorize</title>
 <style>:root{color-scheme:light dark;font-size:125%;--heading:#1a4f8a}

package/lib/publisher.mjs

@@ -23,7 +23,7 @@ const AGENT_VERSION = JSON.parse(fs.readFileSync(
 
 export class Publisher {
   constructor({ config, remote, local, store, deliverer, publicKeyPem, assertionKey = null, log = console.log,
-    probeFetch = null, resolveMention = null, privateOnPod = true,
+    probeFetch = null, resolveMention = null, privateOnPod = true, clientOrigin = null,
   }) {
     this.config = config;
     this.remote = remote;
@@ -32,6 +32,10 @@ export class Publisher {
     this.deliverer = deliverer;
     this.publicKeyPem = publicKeyPem;
     this.assertionKey = assertionKey;      // Ed25519 public half, multibase; null = no proofs
+    // Where this identity's client surface answers, when that is an address a
+    // stranger can reach. Null on a laptop, where the surface is on loopback
+    // and advertising it to the world would name somewhere nobody can go.
+    this.clientOrigin = clientOrigin;
     // A fronted identity (config.gateway.frontActor) advertises its ids on a
     // shared domain; the map tells RemotePod where each writes on the pod.
     const publicBase = config.gateway?.frontActor
@@ -88,6 +92,13 @@ export class Publisher {
       pendingFollowing: priv ? urls.pendingFollowing : null,
       blocked: priv ? urls.blocked : null,
       inbox: gwActive ? gw.url : null,
+      // The agent's own outbox endpoint, where it is reachable: a client
+      // following the actor must arrive somewhere that will take a write.
+      outbox: this.clientOrigin ? `${this.clientOrigin}ap/outbox` : null,
+      // How a client-to-server client finds the way in with nothing configured
+      // by hand. Advertised only where the surface is publicly reachable.
+      oauthAuthorize: this.clientOrigin ? `${this.clientOrigin}oauth/authorize` : null,
+      oauthToken: this.clientOrigin ? `${this.clientOrigin}oauth/token` : null,
     });
     const surface = crypto.createHash('sha256').update(JSON.stringify({
       actor: actorDoc, handle: this.config.handle, host,

package/lib/remote.mjs

@@ -29,6 +29,12 @@ export { mintCredential, discoverTokenEndpoint, revokeCredentialViaAccount };
 // opened — and the callers' existing retry paths take it from there.
 // The parser is shared with the outbound path; see lib/safefetch.mjs.
 import { retryAfterMs, readCapped } from './safefetch.mjs';
+import { linkTargets, REL } from './links.mjs';
+
+// A pod whose access rules are ACP policies, not WAC authorizations. This
+// agent writes WAC; over an ACP resource that would be noise where the pod's
+// real rules used to be, so it stops instead.
+const ACP_NS = 'http://www.w3.org/ns/solid/acp#';
 
 // The inbox is public-Append, so the listing's size is in other people's
 // hands; reading it whole must still have a ceiling.
@@ -82,6 +88,11 @@ export class RemotePod {
     this.pausedUntil = 0;
     this.probeCount = 0;
     this.log = log;
+    // Where each resource's access control lives, as the pod itself said. WAC
+    // forbids working it out from the resource's own URL, so it is asked for
+    // and remembered rather than assembled.
+    this.aclUrls = new Map();
+    this.aclFlavour = null;      // null until the first write asks what this pod speaks
     // A fronted identity advertises ids on a shared domain but writes to the
     // pod. run-agent installs the fronted→pod mapping here, so every request
     // built from an advertised id lands on the pod — one choke point, and
@@ -153,9 +164,63 @@ export class RemotePod {
       method: 'PUT', headers: { 'content-type': contentType }, body,
     });
     if (res.status >= 400) throw new Error(`PUT ${url} → ${res.status}`);
+    // Writing a document is usually the step before setting its access, and
+    // the answer to the write already says where that lives. Taking it here
+    // spares the extra request the ACL write would otherwise make.
+    this.noteAclLink(url, res);
     return res;
   }
 
+  /** Remember an access-control location the pod volunteered on a response. */
+  noteAclLink(url, res) {
+    if (this.aclUrls.has(url)) return;
+    const [acl] = linkTargets(res?.headers?.get?.('link'), REL.acl, url);
+    if (acl) this.aclUrls.set(url, acl);
+  }
+
+  /**
+   * Where this resource's access control lives. The pod says so on any
+   * response about the resource; a pod that says nothing is taken to keep it
+   * at the usual suffix, which is what every server this runs against does.
+   */
+  async aclUrlFor(targetUrl) {
+    const known = this.aclUrls.get(targetUrl);
+    if (known) return known;
+    try {
+      const res = await this.fetch(targetUrl, { method: 'HEAD' });
+      this.noteAclLink(targetUrl, res);
+    } catch { /* unreachable or no such resource yet: the suffix below */ }
+    const resolved = this.aclUrls.get(targetUrl) || targetUrl + '.acl';
+    this.aclUrls.set(targetUrl, resolved);
+    return resolved;
+  }
+
+  /**
+   * Whether writing a WAC document here is meaningful. Asked once per pod, on
+   * the first access-control write. A pod that answers with ACP policies is
+   * left alone: replacing them with authorizations it does not read would take
+   * away the rules actually protecting it.
+   */
+  async aclWritable(aclUrl) {
+    if (this.aclFlavour !== null) return this.aclFlavour;
+    this.aclFlavour = true;
+    try {
+      const res = await this.fetch(aclUrl, { headers: { accept: 'text/turtle' } });
+      if (res.status < 300) {
+        const g = $rdf.graph();
+        $rdf.parse(await res.text(), g, aclUrl, 'text/turtle');
+        const acp = g.statements.some(st => st.predicate.value.startsWith(ACP_NS)
+          || st.object.value.startsWith(ACP_NS));
+        if (acp) {
+          this.aclFlavour = false;
+          this.log('this pod states access as ACP policies, which this agent does not write — '
+            + 'its access rules are left exactly as they are, and nothing here is published private');
+        }
+      }
+    } catch { /* absent, unreadable or unparsable: WAC is what we write */ }
+    return this.aclFlavour;
+  }
+
   async putJson(url, obj, contentType = 'application/activity+json') {
     return this.put(url, JSON.stringify(obj), contentType);
   }
@@ -173,6 +238,11 @@ export class RemotePod {
 
   async delete(url) {
     protectedFromDeletion(url);
+    // The pattern list above knows the usual name for an access-control
+    // document. One the pod named itself is just as fatal to remove.
+    for (const acl of this.aclUrls.values()) {
+      if (acl === url) throw new Error(`refusing to DELETE an access-control document: ${url}`);
+    }
     const res = await this.fetch(url, { method: 'DELETE' });
     return res.status < 400 || res.status === 404;
   }
@@ -238,8 +308,8 @@ export class RemotePod {
   // $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 = [] } = {}) {
-    const url = targetUrl + '.acl';
+  aclDoc(targetUrl, publicModes, { appendAgents = [], aclUrl = null } = {}) {
+    const url = aclUrl || targetUrl + '.acl';
     const doc = $rdf.sym(url);
     const target = $rdf.sym(targetUrl);
     const g = $rdf.graph();
@@ -263,7 +333,9 @@ export class RemotePod {
   }
 
   async setAcl(targetUrl, publicModes, opts = {}) {
-    return this.put(targetUrl + '.acl', this.aclDoc(targetUrl, publicModes, opts), 'text/turtle');
+    const url = await this.aclUrlFor(targetUrl);
+    if (!await this.aclWritable(url)) return null;
+    return this.put(url, this.aclDoc(targetUrl, publicModes, { ...opts, aclUrl: url }), 'text/turtle');
   }
 
   // The WebID profile advertises the actor as an account:
@@ -295,9 +367,53 @@ export class RemotePod {
     const stale = g.statementsMatching(actor, FOAF('accountName'), null, doc)
       .filter(st => st.object.value !== accountName);
     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');
     return true;
   }
+
+  /**
+   * An N3 Patch of exactly these statements, or false when the pod will not
+   * take one and the caller should write the document instead.
+   *
+   * The statements are serialised by rdflib; only the wrapper naming what is
+   * being patched is assembled here, because N3's braces have no rdflib form.
+   */
+  n3Patch(docUrl, inserts, deletes) {
+    const block = (triples) => {
+      const g = $rdf.graph();
+      for (const [s, p, o] of triples) g.add(s, p, o);
+      return $rdf.serialize(null, g, docUrl, 'application/n-triples').trim();
+    };
+    const clauses = [];
+    if (deletes.length) clauses.push(`  solid:deletes { ${block(deletes)} }`);
+    if (inserts.length) clauses.push(`  solid:inserts { ${block(inserts)} }`);
+    return `@prefix solid: <http://www.w3.org/ns/solid/terms#>.\n`
+      + `<> a solid:InsertDeletePatch;\n${clauses.join(';\n')}.\n`;
+  }
+
+  async patchDocument(docUrl, inserts, deletes) {
+    let res;
+    try {
+      res = await this.fetch(docUrl, {
+        method: 'PATCH',
+        headers: { 'content-type': 'text/n3' },
+        body: this.n3Patch(docUrl, inserts, deletes),
+      });
+    } catch {
+      return false;   // no PATCH on this transport at all
+    }
+    if (res.status < 300) return true;
+    // The pod cannot patch. Anything else — a 409 saying what we meant to
+    // remove is not there any more — is a real answer, and rewriting the whole
+    // document over the top of it would destroy whatever changed it.
+    if (res.status === 405 || res.status === 415 || res.status === 501) return false;
+    throw new Error(`PATCH ${docUrl} → ${res.status}`);
+  }
 }

package/lib/setup.mjs

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import * as $rdf from 'rdflib';
 
 import { createAccountWithPod as realCreateAccount } from './account.mjs';
 import { mintCredential as realMint } from './remote.mjs';
@@ -20,8 +21,48 @@ import { rootOf, recordLastUsed, writeJsonAtomic } from './home.mjs';
 import { insecureUrlReason } from './safefetch.mjs';
 import { CURRENT_LAYOUT, isCurrent } from './migrate.mjs';
 
+const SOLID = $rdf.Namespace('http://www.w3.org/ns/solid/terms#');
+
 export const STEPS = ['account', 'credential', 'bootstrap', 'connect', 'publish', 'verify'];
 
+// Read-only pre-check on the pod behind an existing-pod setup, before a
+// credential is minted or the first write is attempted. Two failures it turns
+// from a bare "PUT … → 401" into a plain sentence:
+//   1. the pod host is unreachable — no account should be built on a pod that
+//      is not there;
+//   2. the pod's WebID document declares no OIDC issuer. A pod verifies a token
+//      by dereferencing its WebID and looking for solid:oidcIssuer; an empty or
+//      issuer-less profile makes it reject every write with 401, so setup would
+//      stall on the first one. Only judged when the document is publicly
+//      readable — a protected one cannot be read here and is left to bootstrap.
+export async function checkPodUsable(pod, { webId, fetch: doFetch = globalThis.fetch } = {}) {
+  const base = pod.endsWith('/') ? pod : pod + '/';
+  const wid = webId || new URL('profile/card#me', base).href;
+  const cardUrl = wid.split('#')[0];
+
+  let root;
+  try { root = await doFetch(base, { headers: { accept: 'text/turtle' } }); }
+  catch (e) { return { ok: false, error: `${base} could not be reached (${e.message}). Check the address and that the server is running.` }; }
+  if (root.status === 404) return { ok: false, error: `there is no pod at ${base} — the server answered 404.` };
+  if (root.status >= 500) return { ok: false, error: `the pod host at ${base} is not responding (HTTP ${root.status}).` };
+
+  let card;
+  try { card = await doFetch(cardUrl, { headers: { accept: 'text/turtle' } }); }
+  catch (e) { return { ok: false, error: `the pod's WebID document ${cardUrl} could not be read (${e.message}).` }; }
+  if (card.status === 404) return { ok: false, error: `the pod has no WebID document at ${cardUrl} — the identity it needs is missing.` };
+  if (card.status >= 500) return { ok: false, error: `the pod host is not serving ${cardUrl} (HTTP ${card.status}).` };
+  if (card.status === 401 || card.status === 403) return { ok: true };   // cannot read unauthenticated; leave it to bootstrap
+
+  const body = await card.text().catch(() => '');
+  const g = $rdf.graph();
+  try { $rdf.parse(body, g, cardUrl, (card.headers.get('content-type') || 'text/turtle').split(';')[0].trim()); }
+  catch { return { ok: false, error: `the pod's WebID document ${cardUrl} could not be parsed as RDF.` }; }
+  if (!g.each($rdf.sym(wid), SOLID('oidcIssuer'), null).length) {
+    return { ok: false, error: `the pod's WebID document ${cardUrl} declares no OIDC issuer, so the pod will reject every write. It looks empty or incomplete — restore it, or set up with a fresh pod.` };
+  }
+  return { ok: true };
+}
+
 export const credentialPath = (home) => path.join(home, 'credential.json');
 export const hasCredential = (home) => fs.existsSync(credentialPath(home));
 
@@ -118,6 +159,7 @@ export function preflight({ mode, pod, issuer, podName, handle, kind }) {
 export async function runSetup({ home, agent, answers, run, deps = {}, log = () => {} }) {
   const createAccount = deps.createAccountWithPod || realCreateAccount;
   const mint = deps.mintCredential || realMint;
+  const checkPod = deps.checkPodUsable || checkPodUsable;
 
   const at = (key) => run.steps.find(s => s.key === key);
   const begin = (key) => { at(key).state = 'running'; };
@@ -166,14 +208,21 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
       }
       done('account', pod);
     } else {
+      // A pod you bring must be there and carry a usable WebID before a
+      // credential is minted against it — no account on a pod that is not
+      // reachable, and no silent 401 later on a pod whose profile is empty.
+      const usable = await checkPod(pod);
+      if (!usable.ok) throw new Error(usable.error);
       skip('account', 'using the pod you already have');
     }
 
     // --- credential: the point of no return, and the durability boundary ---
+    let resumeWebId = null;
     if (resuming) {
       const rec = JSON.parse(fs.readFileSync(credPath, 'utf8'));
       pod = rec.remotePod;
       root = rec.root;
+      resumeWebId = rec.webId || null;
       skip('credential', `already minted — ${credPath}`);
     } else {
       begin('credential');
@@ -212,6 +261,13 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
 
     // --- provision the pod and bring federation up ---
     begin('bootstrap');
+    // Resuming skipped the checks the fresh paths ran, and the credential it
+    // carries may be the one bound to a pod whose profile is empty — the write
+    // below would 401. Catch it here, as this step, with a sentence.
+    if (resuming) {
+      const ready = await checkPod(pod, { webId: resumeWebId || undefined });
+      if (!ready.ok) throw new Error(ready.error);
+    }
     await agent.bootstrap({ handle, name: name || handle, root, kind, approveJoins, summary, icon, gateway });
     done('bootstrap');
 

package/lib/storage.mjs

@@ -61,9 +61,15 @@ export class HttpStorage {
     return { notModified: false, names, etag: res.headers.get('etag') };
   }
 
-  async read(p, { etag } = {}) {
+  // `accept` is for callers reading something that is RDF but is wanted as it
+  // was written: asking turtle-first for a JSON-LD document gets turtle back,
+  // because the server is entitled to convert between two RDF syntaxes.
+  async read(p, { etag, accept } = {}) {
     const res = await this.fetchImpl(this._url(p), {
-      headers: { accept: 'text/turtle, application/json;q=0.9, */*;q=0.8', ...(etag ? { 'if-none-match': etag } : {}) },
+      headers: {
+        accept: accept || 'text/turtle, application/json;q=0.9, */*;q=0.8',
+        ...(etag ? { 'if-none-match': etag } : {}),
+      },
     });
     if (res.status === 304) return { ok: true, notModified: true, status: 304, body: null, etag };
     if (res.status >= 400) return { ok: false, notModified: false, status: res.status, body: null, etag: null };