fedipod 1.36.6 → 1.40.0

package/lib/gateway/copy.mjs

@@ -0,0 +1,381 @@
+// copy.mjs — a kept account's working copy at the gateway.
+//
+// While the gateway keeps an account running, the account's state documents
+// (everything under ap-state/) live here, and every agent works from this copy:
+// the owner's browser (through the state API, state-api.mjs), the keeper and
+// the gateway's Mastodon API (in process). The pod is written from it every
+// fifteen minutes (flushCopy), and at once when the copy is given up
+// (dropCopy). What only the pod may hold never comes here: the signing key,
+// the pod's own lease document, and the passwords and tokens of accounts on
+// other servers.
+//
+// The lease that decides which agent acts lives in the copy too, and the copy
+// is what enforces it: a state document is written only by the lease's holder.
+// So two agents working from one copy never write over each other; whichever
+// acts takes the lease, as two browsers do today.
+//
+// `kv` is a small key-value store with conditional writes: Netlify Blobs with
+// strong consistency on Netlify (netlify/functions/front.mjs), a Map in a test
+// (memoryKv below).
+//   get(key) -> { text, etag } | null
+//   set(key, text, { ifMatch, ifNew }) -> { ok, etag }
+//   delete(key)
+//   list(prefix) -> [{ key, etag }]
+
+import crypto from 'node:crypto';
+import { Lease } from '../core/lease.mjs';
+import { podOnly } from '../core/pod-only.mjs';
+
+export { podOnly };
+// The holder id every writer at the gateway shares: the keeper, the Mastodon
+// API and the mail it reads for an app. They are kept apart by lockCopy().
+export const GATEWAY_HOLDER = 'gateway';
+// The pod lease while the copy exists, so an agent reading the pod directly
+// finds the account busy and only reads. Held a day at a time and renewed by
+// the round (renewPodLease): a copy that is lost frees the pod within a day.
+const POD_HOLDER = 'gateway-copy';
+const POD_LEASE_MS = 24 * 3600_000;
+const POD_RENEW_BEFORE_MS = 6 * 3600_000;
+
+// Keys are built from an account's directory key and a document's name, and
+// the store puts a key into a URL as it stands, where `..` would climb out of
+// the account. Only plain names are ever let through.
+const SAFE_HANDLE = /^[a-z0-9][a-z0-9._@-]{0,200}$/u;
+const SAFE_NAME = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,200}\.json$/u;
+export const safeName = (n) => typeof n === 'string' && SAFE_NAME.test(n) && !n.includes('..');
+export const safeHandle = (h) => typeof h === 'string' && SAFE_HANDLE.test(h) && !h.includes('..');
+function account(h) {
+  if (!safeHandle(h)) throw new Error(`not an account this gateway keeps: ${JSON.stringify(h)}`);
+  return h;
+}
+const docKey = (h, name) => {
+  if (!safeName(name)) throw new Error(`not a state document: ${JSON.stringify(name)}`);
+  return `${account(h)}/d/${name}`;
+};
+const hashOf = (s) => crypto.createHash('sha256').update(s).digest('base64url').slice(0, 22);
+
+export function memoryKv() {
+  const m = new Map();
+  let n = 0;
+  return {
+    map: m,
+    async get(key) { return m.has(key) ? { ...m.get(key) } : null; },
+    async set(key, text, { ifMatch = null, ifNew = false } = {}) {
+      const had = m.get(key);
+      if (ifNew && had) return { ok: false };
+      if (ifMatch && had?.etag !== ifMatch) return { ok: false };
+      const etag = `"${++n}"`;
+      m.set(key, { text: String(text), etag });
+      return { ok: true, etag };
+    },
+    async delete(key) { m.delete(key); },
+    async list(prefix) { return [...m].filter(([k]) => k.startsWith(prefix)).map(([key, v]) => ({ key, etag: v.etag })); },
+  };
+}
+
+const readJson = async (kv, key) => {
+  const got = await kv.get(key);
+  if (!got) return { doc: null, etag: null };
+  try { return { doc: JSON.parse(got.text), etag: got.etag }; } catch { return { doc: null, etag: got.etag }; }
+};
+
+/**
+ * Whether the gateway keeps this account under the identity it has now. A row
+ * kept under a former identity (the operator changed FEDIPOD_KEEPER_*) names
+ * one the owner's rules no longer need to name; until the owner's FediPod
+ * hands it over (web/app/copy-mode.mjs: handOverCopy), the gateway leaves it
+ * alone.
+ */
+export const keptNow = (ctx, rec) => !!(rec?.keeper && ctx.keeperWebId && (rec.keeper.webId || ctx.keeperWebId) === ctx.keeperWebId);
+export const keptBefore = (ctx, rec) => !!(rec?.keeper?.webId && ctx.keeperWebId && rec.keeper.webId !== ctx.keeperWebId);
+
+/**
+ * Forget a copy its owner has written to the pod themselves: no write-back, no
+ * pod lease to free (the owner took it). Asked only by the lease's holder.
+ */
+export async function forgetCopy(kv, h, { log = () => {} } = {}) {
+  await kv.delete(`_copies/${account(h)}`);
+  await kv.delete(`${h}/meta`);
+  await kv.delete(`${h}/flushed`);
+  for (const b of await kv.list(`${h}/`)) await kv.delete(b.key);
+  log(`copy @${h}: forgotten; its owner wrote it to the pod`);
+}
+
+/** Every account the gateway keeps a copy for. */
+export async function listCopies(kv) { return (await kv.list('_copies/')).map((b) => b.key.slice('_copies/'.length)); }
+
+/** What the gateway knows of an account's copy, or null when it keeps none. */
+export async function copyMeta(kv, h) { return (await readJson(kv, `${account(h)}/meta`)).doc; }
+
+/**
+ * A fetch for one document in the copy, answering GET and PUT as a pod would
+ * (an ETag, If-Match, 412). The lease is read and written through it, so the
+ * Lease class works on the copy unchanged.
+ */
+export function kvDocFetch(kv, key) {
+  return async (_url, init = {}) => {
+    const method = (init.method || 'GET').toUpperCase();
+    if (method === 'GET') {
+      const got = await kv.get(key);
+      if (!got) return new Response('', { status: 404 });
+      return new Response(got.text, { status: 200, headers: { 'content-type': 'application/json', etag: got.etag } });
+    }
+    if (method === 'PUT') {
+      const ifMatch = init.headers?.['if-match'] || init.headers?.get?.('if-match') || null;
+      const r = await kv.set(key, String(init.body ?? ''), ifMatch ? { ifMatch } : {});
+      if (!r.ok) return new Response('', { status: 412 });
+      return new Response(null, { status: 204, headers: { etag: r.etag } });
+    }
+    return new Response('', { status: 405 });
+  };
+}
+
+/** The lease on this account's copy, for a holder. */
+export function copyLease(kv, h, { id, log = () => {} }) {
+  return new Lease({ url: `copy:${account(h)}/lease`, fetchImpl: kvDocFetch(kv, `${h}/lease`), log, id });
+}
+
+/** Whether `holder` holds the copy's lease now. */
+export async function holds(kv, h, holder) {
+  const { doc } = await readJson(kv, `${account(h)}/lease`);
+  return !!doc && doc.holder === holder && Date.now() < doc.expiresAt;
+}
+
+/**
+ * Storage over the copy, for a PodStore. `holder` is who is writing, checked
+ * against the copy's lease on every write; `pod` is the account's state
+ * container on the pod (an HttpStorage), for what stays there.
+ */
+export class CopyStorage {
+  // `podNames`: which of the pod-only documents to list (all, by default). The
+  // gateway's own agents need only the key.
+  constructor(kv, handle, { holder, pod = null, onRefused = null, podNames = null }) {
+    this.kv = kv;
+    this.h = account(handle);
+    this.holder = holder;
+    this.pod = pod;
+    this.onRefused = onRefused;
+    this.podNames = podNames;
+  }
+
+  get kind() { return 'copy'; }
+  get base() { return `copy:${this.h}/`; }
+
+  async list(sub = '', { etag } = {}) {
+    if (sub) return { notModified: false, names: [], etag: null };
+    const docs = (await this.kv.list(`${this.h}/d/`)).map((b) => ({ name: b.key.slice(`${this.h}/d/`.length), etag: b.etag }));
+    // What stays on the pod is listed only where it can be read.
+    const kept = this.pod ? ((await copyMeta(this.kv, this.h))?.podOnly || []).filter((n) => !this.podNames || this.podNames.includes(n)) : [];
+    const names = [...docs.map((d) => d.name), ...kept.filter((n) => n !== 'lease.json')];
+    const tag = `"${hashOf(JSON.stringify([docs.map((d) => `${d.name}:${d.etag}`).sort(), [...kept].sort()]))}"`;
+    if (etag && etag === tag) return { notModified: true, names: null, etag };
+    return { notModified: false, names, etag: tag };
+  }
+
+  async read(name, opts = {}) {
+    if (!safeName(name)) return { ok: false, notModified: false, status: 404, body: null, etag: null };
+    if (podOnly(name)) {
+      if (!this.pod) return { ok: false, notModified: false, status: 404, body: null, etag: null };
+      return this.pod.read(name, opts);
+    }
+    const got = await this.kv.get(docKey(this.h, name));
+    if (!got) return { ok: false, notModified: false, status: 404, body: null, etag: null };
+    if (opts.etag && opts.etag === got.etag) return { ok: true, notModified: true, status: 304, body: null, etag: got.etag };
+    return { ok: true, notModified: false, status: 200, body: got.text, etag: got.etag };
+  }
+
+  // A refusal is an answer, not a hiccup: the lease is someone else's.
+  async _fenced() {
+    if (await holds(this.kv, this.h, this.holder)) return null;
+    this.onRefused?.();
+    return { ok: false, retry: false, why: 'another agent holds this account now', lost: true };
+  }
+
+  async write(name, body) {
+    if (!safeName(name)) return { ok: false, retry: false, why: 'not a state document name' };
+    if (podOnly(name)) {
+      if (!this.pod) return { ok: false, retry: false, why: 'no pod for this document' };
+      return this.pod.write(name, body, 'application/json');
+    }
+    const refused = await this._fenced();
+    if (refused) return refused;
+    const r = await this.kv.set(docKey(this.h, name), body);
+    return r.ok ? { ok: true, retry: false, why: '', etag: r.etag } : { ok: false, retry: true, why: 'copy write failed' };
+  }
+
+  async remove(name) {
+    if (!safeName(name)) return false;
+    if (podOnly(name)) return this.pod ? this.pod.remove(name) : false;
+    if (await this._fenced()) return false;
+    await this.kv.delete(docKey(this.h, name));
+    return true;
+  }
+}
+
+/**
+ * A short lock for the gateway's own writers on one account, so a keeper run,
+ * a post from an app and the mail read for an app take turns. Waits up to
+ * `waitMs`; returns the release function, or null when it could not get it.
+ * Held for `ms` at a time and extended while its holder runs, so a long run
+ * keeps it and a holder that died loses it within `ms`.
+ */
+export async function lockCopy(kv, h, { ms = 60_000, waitMs = 8_000, by = crypto.randomUUID() } = {}) {
+  const key = `${account(h)}/lock`;
+  const give = (etag) => {
+    let tag = etag;
+    const timer = setInterval(async () => {
+      const r = await kv.set(key, JSON.stringify({ by, until: Date.now() + ms }), { ifMatch: tag }).catch(() => ({ ok: false }));
+      if (r.ok) { tag = r.etag; return; }
+      // Not extended: still ours means the store hiccuped, and the next tick
+      // tries again with what it holds now; anybody else's, it has gone.
+      const cur = await readJson(kv, key).catch(() => ({}));
+      if (cur.doc?.by === by) tag = cur.etag; else clearInterval(timer);
+    }, Math.max(1000, Math.floor(ms / 3)));
+    timer.unref?.();
+    return async () => {
+      clearInterval(timer);
+      const cur = await readJson(kv, key);
+      if (cur.doc?.by === by) await kv.delete(key);
+    };
+  };
+  const until = Date.now() + waitMs;
+  for (;;) {
+    const got = await kv.set(key, JSON.stringify({ by, until: Date.now() + ms }), { ifNew: true });
+    if (got.ok) return give(got.etag);
+    const cur = await readJson(kv, key);
+    // A lock whose holder died is taken over once its time is up.
+    if (cur.doc && Date.now() > cur.doc.until) {
+      const took = await kv.set(key, JSON.stringify({ by, until: Date.now() + ms }), { ifMatch: cur.etag });
+      if (took.ok) return give(took.etag);
+    }
+    if (Date.now() > until) return null;
+    await new Promise((r) => setTimeout(r, 150 + Math.random() * 150));
+  }
+}
+
+/**
+ * Make the copy from the pod. `pod` is the account's state container, read
+ * with the keeper's identity; `podFetch` the same identity's fetch, for the
+ * pod's lease. Refused while an agent reading the pod directly is acting.
+ * Returns { ok } or { ok: false, why }; a copy half made is taken away again,
+ * and the pod's lease given back. The caller holds lockCopy for the account.
+ */
+export async function fillCopy(kv, h, { pod, podFetch, stateUrl, webId = null, log = () => {} }) {
+  if (await copyMeta(kv, h)) return { ok: true, already: true };
+  const podLease = new Lease({ url: stateUrl + 'lease.json', fetchImpl: podFetch, log, id: POD_HOLDER });
+  if (!await podLease.acquire()) return { ok: false, why: 'the account is active on another device' };
+  const undo = async (why) => {
+    for (const b of await kv.list(`${h}/d/`).catch(() => [])) await kv.delete(b.key).catch(() => {});
+    await podLease.release().catch(() => {});
+    return { ok: false, why };
+  };
+  try {
+    // Whatever an interrupted give-up left behind is not this copy.
+    for (const b of await kv.list(`${h}/d/`)) await kv.delete(b.key);
+    const listing = await pod.list('');
+    if (listing.missing) return await undo('no account state on the pod');
+    const names = listing.names.filter(safeName);
+    const flushed = {};
+    // Six at a time: the whole state is read once, and quickly.
+    const wanted = names.filter((n) => !podOnly(n));
+    for (let i = 0; i < wanted.length; i += 6) {
+      const got = await Promise.all(wanted.slice(i, i + 6).map(async (name) => [name, await pod.read(name, { accept: 'application/json' })]));
+      const bad = got.find(([, r]) => !r.ok);
+      if (bad) return await undo(`${bad[0]} could not be read (HTTP ${bad[1].status})`);
+      for (const [name, r] of got) {
+        const set = await kv.set(docKey(h, name), r.body);
+        flushed[name] = { etag: set.etag, hash: hashOf(r.body) };
+      }
+    }
+    await kv.set(`${h}/flushed`, JSON.stringify(flushed));
+    const podLeaseUntil = Date.now() + POD_LEASE_MS;
+    await podLease.write({ holder: POD_HOLDER, expiresAt: podLeaseUntil });
+    await kv.set(`${h}/meta`, JSON.stringify({ filledAt: Date.now(), webId, stateUrl, podOnly: names.filter(podOnly), podLeaseUntil }));
+    await kv.set(`_copies/${h}`, String(Date.now()));
+    log(`copy @${h}: made from the pod (${Object.keys(flushed).length} documents)`);
+    return { ok: true };
+  } catch (e) {
+    return undo(e.message);
+  }
+}
+
+/** The pod's lease, held another day when this one is running out; the round asks. */
+export async function renewPodLease(kv, h, { podFetch, log = () => {}, now = Date.now() } = {}) {
+  const { doc: meta, etag } = await readJson(kv, `${account(h)}/meta`);
+  if (!meta?.stateUrl || (meta.podLeaseUntil || 0) - now > POD_RENEW_BEFORE_MS) return false;
+  const podLeaseUntil = now + POD_LEASE_MS;
+  await new Lease({ url: meta.stateUrl + 'lease.json', fetchImpl: podFetch, log, id: POD_HOLDER })
+    .write({ holder: POD_HOLDER, expiresAt: podLeaseUntil });
+  await kv.set(`${h}/meta`, JSON.stringify({ ...meta, podLeaseUntil }), etag ? { ifMatch: etag } : {});
+  return true;
+}
+
+/**
+ * Write what changed in the copy to the pod. Returns how many documents were
+ * written or removed; a document the pod refused is tried again next time.
+ *
+ * What the pod holds is recorded per document as the copy's version of it and
+ * a hash of its content: a document whose version is unchanged is not read at
+ * all, and one whose content is unchanged is not sent.
+ */
+export async function flushCopy(kv, h, { pod, log = () => {} }) {
+  const docs = (await kv.list(`${account(h)}/d/`)).filter((b) => safeName(b.key.slice(`${h}/d/`.length)));
+  const { doc: had, etag: flushedEtag } = await readJson(kv, `${h}/flushed`);
+  const flushed = { ...(had || {}) };
+  let n = 0;
+  let changed = false;
+  for (const b of docs) {
+    const name = b.key.slice(`${h}/d/`.length);
+    if (flushed[name]?.etag === b.etag) continue;
+    const got = await kv.get(b.key);
+    if (!got) continue;
+    const hash = hashOf(got.text);
+    if (flushed[name]?.hash !== hash) {
+      const w = await pod.write(name, got.text, 'application/json');
+      if (!w.ok) { log(`copy @${h}: ${name} not written to the pod (${w.why})`); continue; }
+      n++;
+    }
+    flushed[name] = { etag: b.etag, hash };
+    changed = true;
+  }
+  const present = new Set(docs.map((b) => b.key.slice(`${h}/d/`.length)));
+  for (const name of Object.keys(flushed)) {
+    if (present.has(name)) continue;
+    if (await pod.remove(name)) { delete flushed[name]; n++; changed = true; }
+  }
+  if (changed) {
+    const saved = await kv.set(`${h}/flushed`, JSON.stringify(flushed), flushedEtag ? { ifMatch: flushedEtag } : {});
+    // Another flush got there first: its record stands, and anything this one
+    // wrote twice is written again next time, which is harmless.
+    if (!saved.ok) log(`copy @${h}: another flush recorded first`);
+  }
+  if (n) log(`copy @${h}: ${n} document(s) written to the pod`);
+  return n;
+}
+
+/**
+ * Give the copy up: everything written to the pod, the pod's lease freed, the
+ * copy deleted. Returns { ok } or { ok: false, why } when the pod would not
+ * take everything or its lease could not be freed, in which case nothing is
+ * deleted. The record of what the pod holds goes first, so a give-up cut off
+ * part way can never lead a later write-back to remove the pod's documents.
+ */
+export async function dropCopy(kv, h, { pod, podFetch, stateUrl, log = () => {} }) {
+  const meta = await copyMeta(kv, h);
+  if (!meta) return { ok: true, already: true };
+  await flushCopy(kv, h, { pod, log });
+  const docs = await kv.list(`${h}/d/`);
+  const { doc: flushed } = await readJson(kv, `${h}/flushed`);
+  const behind = docs.filter((b) => flushed?.[b.key.slice(`${h}/d/`.length)]?.etag !== b.etag);
+  if (behind.length) return { ok: false, why: `${behind.length} document(s) could not be written to the pod` };
+  const podLease = new Lease({ url: (stateUrl || meta.stateUrl) + 'lease.json', fetchImpl: podFetch, log, id: POD_HOLDER });
+  try { await podLease.write({ holder: POD_HOLDER, expiresAt: 0 }); } catch (e) {
+    return { ok: false, why: `the pod's lease could not be freed (${e.message})` };
+  }
+  await kv.delete(`_copies/${h}`);
+  await kv.delete(`${h}/meta`);
+  await kv.delete(`${h}/flushed`);
+  for (const b of await kv.list(`${h}/`)) await kv.delete(b.key);
+  log(`copy @${h}: given up; the pod holds everything`);
+  return { ok: true };
+}

package/lib/gateway/front-core.mjs

@@ -21,10 +21,13 @@ import { readCapped, safeFetch, isLoopbackHost } from '../shared/safefetch.mjs';
 import * as podRoot from '../pod/root.mjs';
 import * as podPolicy from '../pod/policy.mjs';
 import { podBaseOfWebId } from '../pod/urls.mjs';
-import { routeQuietApi, noteOpened, noteReceived, closedState, accountState, closedAnswer } from './quiet.mjs';
+import { routeQuietApi, noteOpened, noteReceived, closedState, accountState, closedAnswer, provedOwner } from './quiet.mjs';
+import { holdsMail, isPresent, holdingPut, afterHeld, routeHereApi, routeKeeperApi } from './held-mail.mjs';
 import { routeNoticesApi } from './notices.mjs';
 import { withSecurityHeaders } from './headers.mjs';
 import { podTokenVerifier } from './caches.mjs';
+import { claimedWebId } from './token-claims.mjs';
+import { announced, overLimit, relayOne } from './relay-extras.mjs';
 
 // The one WebFinger document, spelled out here rather than imported from
 // wire.mjs: wire drags the agent's whole HTML pipeline (sanitize-html and
@@ -55,7 +58,7 @@ const AP_CT = 'application/activity+json';
 // Verify a Solid-OIDC token (DPoP-bound) and return its WebID, or null. The
 // verifier is injected so tests stub it; in production it is the same library
 // the agent's own C2S auth uses.
-async function verifyPodToken(request, pathname, verifier) {
+export async function verifyPodToken(request, pathname, verifier) {
   const authz = request.headers.get('authorization');
   if (!authz) return null;
   try {
@@ -91,9 +94,13 @@ const podOwners = (podBase, fetchImpl = fetch) =>
   podRoot.readOwnerLinks(fetchImpl, podBase, { timeoutMs: OWNER_LOOKUP_MS });
 
 // Whether a token's WebID vouches for this pod, on the evidence of where it
-// lives. Weak on purpose, and never used alone any more — see provesPod.
+// lives: the same origin, and — for a suffixed pod — inside
+// the WebID's own pod, wherever in it the account was put. Weak on purpose,
+// and never used alone for an attach — see provesPod.
 function webidUnderPod(webid, podHome) {
-  try { return new URL(webid).origin === new URL(podHome).origin; } catch { return false; }
+  try {
+    return new URL(webid).origin === new URL(podHome).origin && String(podHome).startsWith(podBaseOfWebId(webid));
+  } catch { return false; }
 }
 
 /**
@@ -144,15 +151,8 @@ function podHomeProblem(podHome, frontOrigin) {
 }
 
 const RELAY_MAX_REQUESTS = 20;
-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;
 
 // The owner's APIs a browser at ANOTHER origin may call: an address moving
 // to a new gateway is driven from the new gateway's page, and it has to tell
@@ -167,46 +167,6 @@ const API_CORS = {
 const withApiCors = (out) => ({ ...out, headers: { ...(out.headers || {}), ...API_CORS } });
 const apiPreflight = () => ({ status: 204, headers: { ...API_CORS, allow: 'POST, OPTIONS' }, body: null });
 
-async function relayOne(item, rec, fetchImpl) {
-  const url = String(item?.url || '');
-  const method = String(item?.method || 'POST').toUpperCase();
-  if (method !== 'GET' && method !== 'POST') return { url, status: 0, error: 'method must be GET or POST' };
-  let u;
-  try { u = new URL(url); } catch { return { url, status: 0, error: 'not a URL' }; }
-  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && process.env.AP_ALLOW_PRIVATE_TARGETS === '1')) {
-    return { url, status: 0, error: 'https only' };
-  }
-  const headers = {};
-  for (const [k, v] of Object.entries(item?.headers || {})) {
-    const name = k.toLowerCase();
-    if (RELAY_HEADERS.has(name) && typeof v === 'string') headers[name] = v;
-  }
-  const body = method === 'POST' ? String(item?.body ?? '') : undefined;
-  if (body !== undefined && Buffer.byteLength(body) > RELAY_MAX_BODY) return { url, status: 0, error: 'body too large' };
-  const keyId = keyIdOf(headers.signature);
-  if (method === 'POST' && !keyId) return { url, status: 0, error: 'a delivery must be signed' };
-  if (keyId && !keyId.startsWith(rec.actorUrl + '#')) return { url, status: 0, error: "signed with a key that is not this account's" };
-  if (headers.digest) {
-    const want = 'SHA-256=' + crypto.createHash('sha256').update(body || '').digest('base64');
-    if (headers.digest !== want) return { url, status: 0, error: 'digest does not match the body' };
-  }
-  try {
-    const res = await safeFetch(url, { method, headers, body, signal: AbortSignal.timeout(RELAY_TIMEOUT_MS) }, fetchImpl);
-    const out = { url, method, status: res.status };
-    // The far server asking to be left alone has to reach the agent that will
-    // do the asking again. Without this the browser build could not honour a
-    // Retry-After at all — every delivery it makes goes through here — and fell
-    // back to its own ladder against a server that had already said how long.
-    const retryAfter = res.headers.get('retry-after');
-    if (retryAfter) out.retryAfter = retryAfter;
-    if (method === 'GET') {
-      out.contentType = res.headers.get('content-type') || null;
-      out.body = await readCapped(res, RELAY_MAX_BODY);
-    }
-    return out;
-  } catch (e) { return { url, method, status: 0, error: e.message }; }
-}
-
 const j = (status, obj, ct = 'application/json') =>
   ({ status, headers: { 'content-type': ct, 'cache-control': 'no-store' }, body: JSON.stringify(obj) });
 // Held at the edge like any other missing document: a bot's scan, a dead
@@ -257,6 +217,11 @@ const publicFor = (seconds, stale = seconds * 4) => ({
 // acts, and ten minutes of edge is what the plan's budget of function calls
 // can afford.
 const PUBLIC_EDGE_SECONDS = 600;
+// A browser account's documents change only when it acts, and it acts through
+// the relay, which clears the edge's copies (see /api/relay). So they are held
+// for an hour: the hour bounds only what changes without an announcement, a
+// like or a reply counted on one of its posts.
+const ANNOUNCED_EDGE_SECONDS = 3600;
 const WEBFINGER_EDGE_SECONDS = 3600;
 // A closed or moved address stays gone; a picture's address stays where it is.
 const GONE_EDGE_SECONDS = 3600;
@@ -615,6 +580,10 @@ async function route(request, ctx) {
   // The owner's say over an account that goes quiet (quiet.mjs).
   const quiet = await routeQuietApi(request, pathname, ctx, { j, verifyPodToken, webidUnderPod, apiPreflight });
   if (quiet) return withApiCors(quiet);
+  // The owner's app saying it is open, and taking what was held (held-mail.mjs).
+  const here = await routeHereApi(request, pathname, ctx, { j, verifyPodToken, webidUnderPod, apiPreflight, provedOwner })
+    || await routeKeeperApi(request, pathname, ctx, { j, verifyPodToken, webidUnderPod, apiPreflight, provedOwner });
+  if (here) return withApiCors(here);
 
   // The relay: the front sends requests a browser has already signed. A page
   // may not set the Date or Host header, and both are inside an HTTP
@@ -639,7 +608,11 @@ async function route(request, ctx) {
     // Acting through the relay is being here. Hourly at most; see noteOpened.
     await noteOpened(ctx, handle, rec).catch((e) => console.log(`relay @${handle}: stamp not written: ${e?.message || e}`));
     if (items.length > RELAY_MAX_REQUESTS) return withApiCors(j(400, { error: `at most ${RELAY_MAX_REQUESTS} requests per call` }));
+    const slow = overLimit(handle, items.length) && j(429, { error: 'too many relayed requests — slow down' });
+    if (slow) return withApiCors({ ...slow, headers: { ...slow.headers, 'retry-after': '60' } });
     const results = await Promise.all(items.map((it) => relayOne(it, rec, ctx.fetchImpl || fetch)));
+    // The account announced something of its own: the edge's copies go.
+    if (announced(items, rec.actorUrl)) await ctx.purge?.([`u-${handle}`]).catch((e) => console.log(`purge @${handle}: ${e?.message || e}`));
     // One line per relayed request, so a lookup that fails on the far side is
     // visible here and not only as an empty result in someone's browser.
     for (const r of results) console.log(`relay @${handle}: ${r.method || ''} ${r.url} → ${r.status}${r.error ? ` (${r.error})` : ''}`);
@@ -724,7 +697,8 @@ async function route(request, ctx) {
       return j(403, { error: 'the token proves a different pod than the one you listed' });
     }
     if (action === 'opt-in') {
-      const { httpStatus, ...reply } = await ctx.agentControl.optIn({ podBase, webId: webid });
+      const { httpStatus, ...reply } = await ctx.agentControl.optIn({ podBase, webId: webid,
+        container: String(body.container || ''), createIndex: body.createIndex === true });
       if (reply.doorSecret) {
       // The secret appears here and nowhere else; the command is the
       // paste-and-run way to open the owner door once.
@@ -833,11 +807,15 @@ async function route(request, ctx) {
     if (closed) { console.log(`door @${up.handle}: delivery → 410 (closed)`); return gone({}, CLOSED); }
     const policy = await policyFor(rec, ctx.fetchImpl || fetch);
     const standing = await accountState(ctx, up.handle, rec);
-    const { status, reason, content, bytes } = await handleDelivery(request, identFor(rec, policy),
-      { podPut: (u, b, ct) => ctx.podPut(up.handle, u, b, ct), fetchImpl: ctx.fetchImpl, paused: standing.paused });
+    // A browser account's mail waits here while its app is closed (held-mail.mjs).
+    const held = holdsMail(ctx, rec) && !(await isPresent(ctx, up.handle));
+    const { status, reason, content, bytes, type, notifies } = await handleDelivery(request, identFor(rec, policy),
+      { podPut: held ? holdingPut(ctx, up.handle, rec) : (u, b, ct) => ctx.podPut(up.handle, u, b, ct),
+        fetchImpl: ctx.fetchImpl, paused: standing.paused });
     // One line per delivery, so "did it arrive at the door" has an answer.
-    console.log(`door @${up.handle}: delivery → ${status} (${reason})`);
+    console.log(`door @${up.handle}: delivery → ${status} (${reason}${held && status === 202 ? ', held' : ''})`);
     if (status === 202 && content) await noteReceived(ctx, up.handle, rec, bytes);
+    if (held && status === 202) await afterHeld(ctx, up.handle, rec, { type, notifies });
     return { status, headers: {}, body: '' };
   }
 
@@ -876,13 +854,28 @@ async function route(request, ctx) {
       if (!webid) return json(401, { error: 'a Solid-OIDC token proving this account\'s owner is required' });
       const owner = rec.webId ? webid === rec.webId : webidUnderPod(webid, rec.podHome);
       if (!owner) return json(403, { error: 'this outbox belongs to its owner alone' });
-      const { status, reason, location } = await handleOwnerPost(request, identFor(rec),
-        { podPut: (u, b, ct) => ctx.podPut(up.handle, u, b, ct), ownerWebId: webid });
+      const onPod = (u) => u.replace(rec.actorUrl.replace(/ap\/actor$/u, ''), rec.podHome);
+      const { status, reason, location, object } = await handleOwnerPost(request, identFor(rec),
+        { podPut: (u, b, ct) => ctx.podPut(up.handle, u, b, ct), ownerWebId: webid,
+          exists: async (u) => ((await (ctx.podGet || fetch)(onPod(u), { podHome: rec.podHome })).status !== 404) });
       console.log(`door @${up.handle}: owner post → ${status} (${reason})`);
       if (status !== 201) return json(status, { error: reason });
-      return json(201, { accepted: true, ...(location ? { object: location } : {}),
+      return json(201, { accepted: true, ...(location ? { id: location } : {}), ...(object ? { object } : {}),
         note: 'it goes out when your FediPod agent next runs' }, location ? { location } : {});
     }
+    // Its owner, signed in, reads every message the account produced (§5.1:
+    // the outbox is filtered by who asks); that view is on the pod, under the
+    // owner's own rule. Anyone else reads the public one.
+    // The token is only read here, not verified: the redirect grants nothing,
+    // the pod checks the credential when the owner arrives there, and a
+    // verification per read would let anyone make the front fetch keys from a
+    // server they name.
+    if ((request.method === 'GET' || request.method === 'HEAD') && request.headers.get('authorization')) {
+      const webid = claimedWebId(request);
+      if (webid && (rec.webId ? webid === rec.webId : webidUnderPod(webid, rec.podHome))) {
+        return { status: 303, headers: { ...cors, location: rec.podHome + 'ap/private/outbox', 'cache-control': 'no-store' }, body: '' };
+      }
+    }
     if (rec.inboxOnly && (request.method === 'GET' || request.method === 'HEAD')) {
       return { status: 303, headers: { ...cors, location: rec.podHome + 'ap/outbox', 'cache-control': 'no-store' }, body: '' };
     }
@@ -907,6 +900,12 @@ async function route(request, ctx) {
   }
   if (closed) return gone({ ...open, ...publicFor(GONE_EDGE_SECONDS) }, CLOSED);
   const podTarget = rec.podHome + up.rest;
+  // The owner's own documents — the full outbox, the liked list, the pending
+  // lists — are read at the pod, which decides who may; never held here,
+  // where one reader's answer would be served to the next.
+  if (up.rest.startsWith('ap/private/')) {
+    return { status: 303, headers: { ...open, location: podTarget, 'cache-control': 'no-store' }, body: '' };
+  }
   // Media stays on the pod (lib/pod/urls.mjs keeps `media` off the front), but
   // the id rewrite below turns media links onto the front like every other
   // pod url in a document. Answer those by pointing at the pod: bytes are not
@@ -929,8 +928,9 @@ async function route(request, ctx) {
     ctx.podGet || ((u) => fetch(u, { headers: { accept } })),
     podTarget, { podHome: rec.podHome, accept });
   if (got.text === null) {
-    const hold = [401, 403, 404, 410].includes(got.status) ? publicFor(MISSING_EDGE_SECONDS) : {};
-    return { status: got.status, headers: { ...open, ...hold }, body: '' };
+    const hold = [401, 403, 404, 410].includes(got.status) ? { ...publicFor(MISSING_EDGE_SECONDS), 'netlify-cache-tag': `u-${up.handle}` } : {};
+    // A stranger is not told a document exists that they may not read (§3.2).
+    return { status: got.status === 401 || got.status === 403 ? 404 : got.status, headers: { ...open, ...hold }, body: '' };
   }
   let text = got.text;
   text = swap(text, rec.podHome, base);
@@ -946,6 +946,9 @@ async function route(request, ctx) {
       doc.preferredUsername = up.handle;               // so @handle@front cross-checks
       doc.inbox = base + 'ap/inbox/';                  // deliveries come to the front to be verified
       doc.endpoints = { ...(doc.endpoints || {}), sharedInbox: base + 'ap/inbox/' };
+      // The owner's own documents are read at the pod, where their credential
+      // works; they keep the pod's address.
+      for (const k of ['liked', 'ownerOutbox']) if (typeof doc[k] === 'string') doc[k] = doc[k].replace(base, rec.podHome);
       if (movedBase) {
         doc.movedTo = rec.movedTo;
         const aka = new Set([].concat(doc.alsoKnownAs || []).filter((a) => typeof a === 'string' && a !== doc.id));
@@ -961,9 +964,17 @@ async function route(request, ctx) {
     } catch { /* leave the rewritten text as-is if it will not parse */ }
   }
   // `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) },
+  // came back is one anybody can read — which is what makes it cacheable. A
+  // deleted post's Tombstone answers 410 Gone, and still says what it was.
+  let kind = null;
+  try { kind = JSON.parse(text)?.type; } catch { /* not JSON: a page or a container */ }
+  return { status: kind === 'Tombstone' ? 410 : 200,
+    headers: { ...open, 'content-type': got.type || (container ? 'text/turtle' : page ? 'text/html' : AP_CT),
+      ...publicFor(rec.openedAt ? ANNOUNCED_EDGE_SECONDS : PUBLIC_EDGE_SECONDS),
+      // The outbox answers its signed-in owner differently, so the edge keeps
+      // the public copy for those who show no credential.
+      ...(up.rest === 'ap/outbox' ? { 'netlify-vary': 'header=Authorization', vary: 'Authorization' } : {}),
+      'netlify-cache-tag': `u-${up.handle}` },
     body: text };
 }