fedipod-server 0.9.0 → 0.11.0

package/web/app/shims/fedify-sig.mjs

@@ -0,0 +1,77 @@
+// fedify-sig.mjs — a browser stand-in for @fedify/fedify/sig.
+//
+// Fedify itself will not run in a browser: it reaches for node:dns, node:net
+// and node:process to resolve and fetch actors. Only two of its functions are
+// on the agent's path:
+//
+//   signRequest       — outbound HTTP Signatures (draft-cavage), what a remote
+//                       server verifies. Implemented here with WebCrypto and
+//                       proven byte-identical to Fedify's own output for the
+//                       same request and key (claude/validation/signing-shim/).
+//   verifyRequestDetailed — inbound verification. The browser agent never runs
+//                       it: it trusts the gateway's receipt, exactly as the
+//                       agent does in the gateway's `trust` mode. Stubbed so a
+//                       bundled import resolves.
+//
+// A browser cannot set Date or Host on a request (both are forbidden header
+// names) and does not add them itself, so a signature that covers them can only
+// travel through the relay, which sends the signed headers verbatim. That is why
+// the real work is `sign()`, which returns the signed headers as data. The
+// browser deliverer hands that to the relay; `signRequest` wraps it into a
+// Request for the Fedify-shaped callers and the byte-equality proof.
+
+const b64 = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)));
+
+/**
+ * Sign a request and return the parts to send: the covered header names, the
+ * header values (Date/Host/Digest filled in), the body, and the target. Host is
+ * always signed from the URL; the relay's own fetch sends the matching Host.
+ */
+export async function sign({ url, method = 'POST', headers = {}, body }, privateKey, keyId) {
+  const u = new URL(url);
+  const m = method.toUpperCase();
+  const signed = {};
+  for (const [k, v] of Object.entries(headers)) {
+    const name = k.toLowerCase();
+    if (name !== 'signature' && name !== 'host') signed[name] = v;
+  }
+
+  let bodyBytes;
+  if (m !== 'GET' && m !== 'HEAD' && body != null) {
+    bodyBytes = typeof body === 'string' ? new TextEncoder().encode(body) : new Uint8Array(body);
+    if (!('digest' in signed)) signed.digest = `SHA-256=${b64(await crypto.subtle.digest('SHA-256', bodyBytes))}`;
+  }
+  if (!('date' in signed)) signed.date = new Date().toUTCString();
+  signed.host = u.host;
+
+  const names = ['(request-target)', ...Object.keys(signed).sort()];
+  const signingString = names.map((n) => (n === '(request-target)'
+    ? `(request-target): ${m.toLowerCase()} ${u.pathname}${u.search}`
+    : `${n}: ${signed[n]}`)).join('\n');
+  const sig = await crypto.subtle.sign('RSASSA-PKCS1-v1_5', privateKey, new TextEncoder().encode(signingString));
+  signed.signature = `keyId="${keyId.href || keyId}",algorithm="rsa-sha256",headers="${names.join(' ')}",signature="${b64(sig)}"`;
+
+  return { url: u.href, method: m, headers: signed, body: bodyBytes ?? null, covered: names };
+}
+
+/** Fedify's signRequest shape: sign, then return a Request. Forbidden headers
+ *  (Host, Date) survive here only where the runtime allows them (Node); the
+ *  browser delivery path uses sign() and the relay instead. */
+export async function signRequest(request, privateKey, keyId) {
+  const headers = {};
+  for (const [k, v] of request.headers) headers[k] = v;
+  const body = (request.method === 'GET' || request.method === 'HEAD')
+    ? undefined : new Uint8Array(await request.clone().arrayBuffer());
+  const s = await sign({ url: request.url, method: request.method, headers, body }, privateKey, keyId);
+  const out = new Headers();
+  for (const [k, v] of Object.entries(s.headers)) out.set(k, v);
+  const init = { method: s.method, headers: out, signal: request.signal };
+  if (s.body) init.body = s.body;
+  return new Request(request.url, init);
+}
+
+// The browser agent verifies nothing itself — the gateway already did, and its
+// receipt is what the drain trusts. Present so the import resolves.
+export async function verifyRequestDetailed() {
+  return { success: false, reason: 'the browser agent does not verify; it trusts the gateway receipt' };
+}

package/web/app/shims/node-crypto.mjs

@@ -0,0 +1,113 @@
+// node-crypto.mjs — a browser stand-in for node:crypto, for the agent bundle.
+//
+// The agent uses only a small synchronous slice: SHA-256 (and HMAC-SHA-256)
+// hashing, random bytes, constant-time compare — plus WebCrypto (crypto.subtle),
+// which the browser has natively. Rather than pull in crypto-browserify (which
+// drags Node streams into the bundle), SHA-256 is implemented here in pure JS.
+// Key generation and KeyObject calls are never reached: keys are made by
+// keystore.mjs and loaded straight into WebCrypto.
+
+const K = new Uint32Array([
+  0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,
+  0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,
+  0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,
+  0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,
+  0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,
+  0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,
+  0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,
+  0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2]);
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+function sha256(bytes) {
+  const l = bytes.length;
+  const withOne = l + 1;
+  const k = (56 - (withOne % 64) + 64) % 64;
+  const total = withOne + k + 8;
+  const m = new Uint8Array(total);
+  m.set(bytes); m[l] = 0x80;
+  const bits = l * 8;
+  const dv = new DataView(m.buffer);
+  dv.setUint32(total - 4, bits >>> 0);
+  dv.setUint32(total - 8, Math.floor(bits / 0x100000000));
+  const H = new Uint32Array([0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19]);
+  const w = new Uint32Array(64);
+  for (let i = 0; i < total; i += 64) {
+    for (let t = 0; t < 16; t++) w[t] = dv.getUint32(i + t * 4);
+    for (let t = 16; t < 64; t++) {
+      const s0 = rotr(w[t-15],7) ^ rotr(w[t-15],18) ^ (w[t-15] >>> 3);
+      const s1 = rotr(w[t-2],17) ^ rotr(w[t-2],19) ^ (w[t-2] >>> 10);
+      w[t] = (w[t-16] + s0 + w[t-7] + s1) >>> 0;
+    }
+    let [a,b,c,d,e,f,g,h] = H;
+    for (let t = 0; t < 64; t++) {
+      const S1 = rotr(e,6) ^ rotr(e,11) ^ rotr(e,25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (h + S1 + ch + K[t] + w[t]) >>> 0;
+      const S0 = rotr(a,2) ^ rotr(a,13) ^ rotr(a,22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      h=g; g=f; f=e; e=(d+t1)>>>0; d=c; c=b; b=a; a=(t1+t2)>>>0;
+    }
+    H[0]=(H[0]+a)>>>0; H[1]=(H[1]+b)>>>0; H[2]=(H[2]+c)>>>0; H[3]=(H[3]+d)>>>0;
+    H[4]=(H[4]+e)>>>0; H[5]=(H[5]+f)>>>0; H[6]=(H[6]+g)>>>0; H[7]=(H[7]+h)>>>0;
+  }
+  const out = new Uint8Array(32);
+  new DataView(out.buffer).setUint32(0, H[0]); new DataView(out.buffer).setUint32(4, H[1]);
+  new DataView(out.buffer).setUint32(8, H[2]); new DataView(out.buffer).setUint32(12, H[3]);
+  new DataView(out.buffer).setUint32(16, H[4]); new DataView(out.buffer).setUint32(20, H[5]);
+  new DataView(out.buffer).setUint32(24, H[6]); new DataView(out.buffer).setUint32(28, H[7]);
+  return out;
+}
+function hmacSha256(key, msg) {
+  if (key.length > 64) key = sha256(key);
+  const pad = new Uint8Array(64); pad.set(key);
+  const ipad = new Uint8Array(64); const opad = new Uint8Array(64);
+  for (let i = 0; i < 64; i++) { ipad[i] = pad[i] ^ 0x36; opad[i] = pad[i] ^ 0x5c; }
+  const inner = sha256(concat(ipad, msg));
+  return sha256(concat(opad, inner));
+}
+const concat = (a, b) => { const o = new Uint8Array(a.length + b.length); o.set(a); o.set(b, a.length); return o; };
+const toBytes = (data, enc) => {
+  if (data == null) return new Uint8Array(0);
+  if (typeof data === 'string') {
+    if (enc === 'hex') return Uint8Array.from(data.match(/.{1,2}/g) || [], (h) => parseInt(h, 16));
+    if (enc === 'base64') return Uint8Array.from(atob(data), (c) => c.charCodeAt(0));
+    return new TextEncoder().encode(data);
+  }
+  return data instanceof Uint8Array ? data : new Uint8Array(data);
+};
+const encode = (bytes, enc) => {
+  if (!enc || enc === 'buffer') return bytes;
+  if (enc === 'hex') return [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+  const b64 = btoa(String.fromCharCode(...bytes));
+  if (enc === 'base64url') return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  return b64;   // base64
+};
+
+export function createHash(alg) {
+  if (alg !== 'sha256') throw new Error(`node-crypto shim: only sha256 is implemented (got ${alg})`);
+  let acc = new Uint8Array(0);
+  return { update(d, e) { acc = concat(acc, toBytes(d, e)); return this; }, digest(enc) { return encode(sha256(acc), enc); } };
+}
+export function createHmac(alg, key) {
+  if (alg !== 'sha256') throw new Error(`node-crypto shim: only hmac-sha256 is implemented (got ${alg})`);
+  const k = toBytes(key); let acc = new Uint8Array(0);
+  return { update(d, e) { acc = concat(acc, toBytes(d, e)); return this; }, digest(enc) { return encode(hmacSha256(k, acc), enc); } };
+}
+// A Buffer, not a bare Uint8Array, so callers' `.toString('hex')` works (the
+// prelude defines Buffer before any bundle code runs).
+export function randomBytes(n) { const b = new Uint8Array(n); crypto.getRandomValues(b); return globalThis.Buffer ? globalThis.Buffer.from(b) : b; }
+export const webcrypto = globalThis.crypto;
+export const randomUUID = () => globalThis.crypto.randomUUID();
+export function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let out = 0; for (let i = 0; i < a.length; i++) out |= a[i] ^ b[i];
+  return out === 0;
+}
+const unavailable = (name) => () => { throw new Error(`node:crypto ${name} is not available in the browser agent`); };
+export const generateKeyPairSync = unavailable('generateKeyPairSync');
+export const createPrivateKey = unavailable('createPrivateKey');
+export const createPublicKey = unavailable('createPublicKey');
+export const scryptSync = unavailable('scryptSync');
+export default { createHash, createHmac, randomBytes, webcrypto, randomUUID, timingSafeEqual,
+  generateKeyPairSync, createPrivateKey, createPublicKey, scryptSync };

package/web/app/shims/node-fs.mjs

@@ -0,0 +1,17 @@
+// node-fs.mjs — the tiny synchronous slice of node:fs touched at import time.
+// ua.mjs and publisher.mjs read package.json for the version; everything else
+// (FileStorage, home, certs) is never constructed in the browser.
+const PKG = JSON.stringify({ version: '0.18.0', name: 'fedipod' });
+export const readFileSync = (p) => {
+  if (String(p).endsWith('package.json')) return PKG;
+  throw new Error(`node:fs readFileSync(${p}) is not available in the browser agent`);
+};
+export const existsSync = () => false;
+const nope = (name) => () => { throw new Error(`node:fs ${name} is not available in the browser agent`); };
+export const writeFileSync = nope('writeFileSync');
+export const mkdirSync = nope('mkdirSync');
+export const readdirSync = () => [];
+export const statSync = nope('statSync');
+export const unlinkSync = nope('unlinkSync');
+export const rmSync = nope('rmSync');
+export default { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync, rmSync };

package/web/app/shims/node-path.mjs

@@ -0,0 +1,19 @@
+// node-path.mjs — the POSIX slice of node:path the agent uses in the browser.
+const normalize = (p) => {
+  const up = p.startsWith('/');
+  const parts = [];
+  for (const seg of p.split('/')) {
+    if (!seg || seg === '.') continue;
+    if (seg === '..') { if (parts.length && parts[parts.length - 1] !== '..') parts.pop(); else if (!up) parts.push('..'); }
+    else parts.push(seg);
+  }
+  return (up ? '/' : '') + parts.join('/') || (up ? '/' : '.');
+};
+const join = (...segs) => normalize(segs.filter((s) => s != null && s !== '').join('/'));
+const dirname = (p) => { const i = p.replace(/\/$/, '').lastIndexOf('/'); return i <= 0 ? (i === 0 ? '/' : '.') : p.slice(0, i); };
+const basename = (p, ext) => { let b = p.slice(p.lastIndexOf('/') + 1); if (ext && b.endsWith(ext)) b = b.slice(0, -ext.length); return b; };
+const extname = (p) => { const b = basename(p); const i = b.lastIndexOf('.'); return i > 0 ? b.slice(i) : ''; };
+const resolve = (...segs) => join(...segs);
+const posix = { join, dirname, basename, extname, resolve, normalize, sep: '/' };
+export { join, dirname, basename, extname, resolve, normalize, posix };
+export default { join, dirname, basename, extname, resolve, normalize, posix, sep: '/' };

package/web/app/shims/node-url.mjs

@@ -0,0 +1,7 @@
+// node-url.mjs — the node:url slice the agent uses. URL is native; the two
+// file-path converters are only ever called with data: or http URLs in the
+// browser build, so plain string surgery suffices.
+export const fileURLToPath = (u) => { const s = typeof u === 'string' ? u : u.href; return s.replace(/^file:\/\//, ''); };
+export const pathToFileURL = (p) => new URL('file://' + (p.startsWith('/') ? p : '/' + p));
+export { URL, URLSearchParams } from './_globals.mjs';
+export default { URL: globalThis.URL, URLSearchParams: globalThis.URLSearchParams, fileURLToPath, pathToFileURL };

package/web/app/shims/prelude.js

@@ -0,0 +1,58 @@
+// prelude.js — globals the bundled Node code expects, set once before it runs.
+// Injected as the bundle's banner. Kept minimal and local: Buffer is a subclass
+// of Uint8Array (not a prototype patch), so nothing else in the page is touched.
+globalThis.process ??= { env: {}, argv: [], platform: 'browser', cwd: () => '/', nextTick: (f, ...a) => queueMicrotask(() => f(...a)) };
+globalThis.Buffer ??= (() => {
+  const b64 = (u) => btoa(String.fromCharCode(...u));
+  const hex = (u) => { let s = ''; for (const b of u) s += b.toString(16).padStart(2, '0'); return s; };
+  class Buf extends Uint8Array {
+    // Uint8Array.indexOf finds a single BYTE; Node's Buffer finds a whole
+    // subsequence, and lib/mastoapi.mjs's readMultipart walks a multipart body
+    // by searching for the boundary and for the CRLFCRLF that ends each part's
+    // headers. Without this every search returned -1, so an upload came back
+    // "file required" however good the bytes were.
+    indexOf(needle, from = 0) {
+      const pat = typeof needle === 'string' ? new TextEncoder().encode(needle)
+        : needle instanceof Uint8Array ? needle : null;
+      if (pat === null) return super.indexOf(needle, from);      // a single byte
+      if (pat.length === 0) return Math.min(from, this.length);
+      const last = this.length - pat.length;
+      outer: for (let i = Math.max(0, from); i <= last; i++) {
+        for (let j = 0; j < pat.length; j++) if (this[i + j] !== pat[j]) continue outer;
+        return i;
+      }
+      return -1;
+    }
+    toString(enc) {
+      if (enc === 'hex') return hex(this);
+      if (enc === 'base64') return b64(this);
+      if (enc === 'base64url') return b64(this).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+      return new TextDecoder().decode(this);
+    }
+  }
+  const fromString = (s, enc) => {
+    if (enc === 'hex') return Buf.from(s.match(/.{1,2}/g) || [], (h) => parseInt(h, 16));
+    if (enc === 'base64' || enc === 'base64url') {
+      const n = s.replace(/-/g, '+').replace(/_/g, '/');
+      return Buf.from(atob(n + '==='.slice((n.length + 3) % 4)), (c) => c.charCodeAt(0));
+    }
+    return Buf.from(new TextEncoder().encode(s));
+  };
+  const from = (d, enc) => {
+    if (typeof d === 'string') return fromString(d, enc);
+    if (typeof d === 'function') { const args = arguments; return Uint8Array.from.call(Buf, args[0], args[1]); }
+    const b = new Buf(d.length); b.set(d); return b;
+  };
+  const fromAny = (d, e) => {
+    if (typeof d === 'string') return fromString(d, e);
+    if (typeof e === 'function') { const arr = Array.from(d, e); const b = new Buf(arr.length); b.set(arr); return b; }
+    if (d instanceof Uint8Array || Array.isArray(d)) { const b = new Buf(d.length); b.set(d); return b; }
+    return new Buf(d);
+  };
+  return {
+    from: fromAny,
+    concat: (list) => { const n = list.reduce((s, x) => s + x.length, 0); const o = new Buf(n); let i = 0; for (const x of list) { o.set(x, i); i += x.length; } return o; },
+    alloc: (n) => new Buf(n),
+    isBuffer: (x) => x instanceof Uint8Array,
+  };
+})();

package/web/app/shims/safefetch.mjs

@@ -0,0 +1,58 @@
+// safefetch.mjs — browser stand-in for lib/safefetch.mjs.
+//
+// The Node version pins connections to a validated IP to stop DNS-rebinding and
+// refuses private targets, using undici and node:dns. A browser cannot open raw
+// sockets and is bound by the same-origin policy and CORS, so the rebinding
+// attack this defends against is not reachable from here; the browser agent's
+// only cross-origin writes go through the relay, which runs the Node checks.
+// This keeps the same surface with plain fetch and no top-level await.
+export const HTTP_TIMEOUT_MS = 20_000;
+const MAX_BYTES = 5 * 1024 * 1024;
+
+export function retryAfterMs(res, max = 30 * 60_000) {
+  const h = res?.headers?.get?.('retry-after');
+  if (!h) return null;
+  const secs = /^\d+$/.test(h.trim()) ? Number(h) * 1000 : (Date.parse(h) - Date.now());
+  return Number.isFinite(secs) ? Math.max(0, Math.min(secs, max)) : null;
+}
+export function isPrivateAddress() { return false; }
+export function isLoopbackHost(host) { return /^(localhost|127\.|\[?::1)/.test(String(host)); }
+export function insecureUrlReason(url, what = 'address') {
+  try { const u = new URL(url); if (u.protocol === 'https:' || isLoopbackHost(u.hostname)) return null;
+    if (u.protocol !== 'http:') return `the ${what} must be http(s)`; return null; } catch { return `"${url}" is not a ${what}`; }
+}
+export async function assertPublicUrl() { return null; }     // no socket pinning in a browser
+export async function pinnedFor() { return undefined; }
+// The one thing in this file that is NOT made unnecessary by being in a
+// browser. Pinning and the private-address checks answer DNS rebinding, which
+// a browser closes on its own; a byte budget answers a server that simply
+// keeps sending, which it does not. This used to check `content-length` and
+// then hand back `res.text()` — and a chunked response carries no
+// `content-length` at all, so every caller below dereferences a URL a stranger
+// chose (the note, the actor, the receipt, the Tombstone check, WebFinger)
+// with no bound on what comes back. Stream it and stop at the budget, the way
+// the Node version does. TextDecoder rather than Buffer, and `stream: true` so
+// a UTF-8 sequence split across two chunks still decodes.
+export async function readCapped(res, max = MAX_BYTES) {
+  const len = Number(res.headers?.get?.('content-length') || 0);
+  if (len > max) throw new Error(`response too large (${len} bytes)`);
+  if (!res.body) return res.text();
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let out = '';
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > max) {
+      await reader.cancel();
+      throw new Error(`response exceeded ${max} bytes`);
+    }
+    out += decoder.decode(value, { stream: true });
+  }
+  return out + decoder.decode();
+}
+export async function safeFetch(url, init = {}, fetchImpl = fetch) {
+  return fetchImpl(url, { ...init, signal: init.signal || AbortSignal.timeout(HTTP_TIMEOUT_MS) });
+}

package/web/app/shims/web-push.mjs

@@ -0,0 +1,14 @@
+// web-push.mjs — browser stand-in. The facade needs a VAPID public key to put
+// in its instance document; server-sent push while the tab is closed is not
+// part of the browser build, so sendNotification is a no-op. The keypair is a
+// well-formed placeholder (a real one needs a matching private key, which the
+// browser push model does not use this way).
+const b64u = (u) => btoa(String.fromCharCode(...u)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+export function generateVAPIDKeys() {
+  const pub = new Uint8Array(65); pub[0] = 0x04; crypto.getRandomValues(pub.subarray(1));
+  const priv = new Uint8Array(32); crypto.getRandomValues(priv);
+  return { publicKey: b64u(pub), privateKey: b64u(priv) };
+}
+export function setVapidDetails() { /* no-op */ }
+export async function sendNotification() { return { statusCode: 201, body: '', headers: {} }; }
+export default { generateVAPIDKeys, setVapidDetails, sendNotification };

package/web/app/signup.mjs

@@ -0,0 +1,248 @@
+// signup.mjs — the setup flow of `fedipod setup`, run in the browser. It does
+// what lib/setup.mjs's runSetup does up to the publish step: create the account
+// and pod (or accept one you bring), mint a credential, make the signing keys
+// and lock them on the pod under the password. Publishing the actor is the
+// agent's first-run job, exactly as `connect()` publishes after `setup` mints —
+// so this module needs nothing from lib.
+//
+// It returns the two things a browser must keep for itself: the credential and
+// the config. Neither is secret to the pod owner, but the credential is a pod
+// write key, so the caller stores it in this browser only, never on the pod.
+// The only thing this writes to the pod is the password-wrapped signing key.
+
+import { createAccountWithPod, mintCredential, makeDpopSession, revokeCredential } from './pod-auth.mjs';
+import { generateKeys, wrapKeys } from './keystore.mjs';
+import { BrowserRemotePod } from './pod-remote.mjs';
+import * as podState from '../../lib/pod/state.mjs';
+import { kvPut } from './idb-kv.mjs';
+import { keyCacheKey } from './keys-browser.mjs';
+
+// The container everything the agent publishes hangs under. New pods made here
+// use `fedipod/`; the agent's own default stays `activitypods-js/` for installs
+// that predate this, so those pods are untouched. The name is stored on the
+// credential and the config, so the agent reads it rather than guessing.
+export const AP_ROOT = 'fedipod/';
+const actorUrlFor = (pod) => `${pod}${AP_ROOT}ap/actor`;
+const keysDocFor = (pod) => `${pod}${AP_ROOT}ap-state/keys.json`;
+
+const HANDLE_RE = /^[a-z0-9-]{2,30}$/;
+
+export function handleProblem(handle) {
+  if (!handle) return 'a handle is required';
+  if (!HANDLE_RE.test(handle)) return 'letters, digits and hyphens only, 2–30 characters';
+  if (handle.startsWith('-') || handle.endsWith('-')) return 'cannot start or end with a hyphen';
+  return null;
+}
+
+// Resume across a failed attempt. A run that throws part-way keeps what it
+// already achieved in this page session — the pod it made, the credential it
+// minted, the key it wrote — so a second attempt (the failure screen's Try
+// again) continues from the first unfinished step instead of restarting. The
+// record lives only in memory here: no secret is written to disk, and it is
+// dropped the moment the run completes. Keyed by the identity being built, so
+// changing the handle or pod on the form starts a clean attempt.
+const PROGRESS = new Map();
+const progressKey = (a) => [a.issuer, a.mode, a.handle, a.mode === 'new' ? (a.podName || a.handle) : a.pod].join('|');
+
+/**
+ * Run sign-up. Steps are reported through onStep(key, state, note) so a page can
+ * draw the same tick list the CLI setup shows. Resumable: see PROGRESS above.
+ *
+ * answers: { mode:'new'|'existing', issuer, email, password, handle,
+ *            podName?, pod?, gateway? }
+ * returns: { credential, config, actorUrl, address, keysPublic }
+ */
+export async function signUp(answers, { onStep = () => {}, frontOrigin = null } = {}) {
+  const { mode, issuer, email, password, handle } = answers;
+  const bad = handleProblem(handle);
+  if (bad) throw new Error(bad);
+  if (!email) throw new Error('an email is required');           // recovery + account login
+  if (!password) throw new Error('a password is required');
+  if (mode === 'existing' && !answers.pod) throw new Error('a pod address is required');
+
+  const key = progressKey(answers);
+  const prog = PROGRESS.get(key) || {};
+  PROGRESS.set(key, prog);                                       // resume record for this identity
+
+  const step = (key) => ({
+    running: (note) => onStep(key, 'running', note),
+    ok: (note) => onStep(key, 'ok', note),
+    skip: (note) => onStep(key, 'skipped', note),
+  });
+
+  // --- account + pod --- (skipped outright once a prior attempt has made it)
+  let accountToken = null;                                       // valid only within this call
+  const acct = step('account');
+  if (!prog.pod) {
+    if (mode === 'new') {
+      acct.running('creating the account and pod');
+      const made = await createAccountWithPod({ issuer, email, password, podName: answers.podName || handle });
+      prog.pod = made.pod; prog.webId = made.webId; accountToken = made.accountToken;
+      acct.ok(made.pod);
+    } else {
+      const brought = answers.pod.endsWith('/') ? answers.pod : answers.pod + '/';
+      acct.running('checking your pod');
+      const head = await fetch(brought, { method: 'HEAD' }).catch(() => null);
+      if (!head || head.status >= 400) throw new Error(`the pod at ${brought} did not answer (HTTP ${head?.status || 'no response'})`);
+      prog.pod = brought;
+      acct.skip('using the pod you brought');
+    }
+  } else {
+    acct.ok(prog.pod);                                          // resumed: the pod is already there
+  }
+  const pod = prog.pod; const webId = prog.webId || null;
+
+  // WebFinger is answered at a host root, so the address only works if the pod
+  // is the root of its own host. Refuse a path pod rather than making an
+  // account nobody can find.
+  const podUrl = new URL(pod);
+  if (podUrl.pathname !== '/') {
+    throw new Error(`${pod} is a path on ${podUrl.host}, not its own host. `
+      + 'A Fediverse address lives at a host root, so this pod cannot carry one. '
+      + 'Use a pod that is the root of its own subdomain.');
+  }
+
+  const actorUrl = actorUrlFor(pod);
+
+  // --- credential --- (a fresh attempt re-mints; a resumed one reuses it)
+  const cred = step('credential');
+  let credential;
+  if (!prog.credential) {
+    cred.running('minting a credential for this browser');
+    // accountToken is null when the account step was skipped (a resume), so
+    // mintCredential logs in fresh with email+password rather than reusing a
+    // token that a prior attempt may have let go stale.
+    credential = await mintCredential({ issuer, email, password, webId, podUrl: pod, accountToken });
+    credential.remotePod = pod;
+    credential.root = AP_ROOT;                                   // the agent reads the container name from here
+    prog.credential = credential;
+    cred.ok();
+  } else {
+    credential = prog.credential;
+    cred.ok();
+  }
+
+  // A pod-writing session for the remaining pod writes and the gateway proof.
+  const session = await makeDpopSession(credential);
+
+  // --- keys, encrypted, in an owner-only container on the pod ---
+  //
+  // The durable copy is on the pod, because a browser has no disk you can carry
+  // to the next machine. That copy used to be the bare record, on the argument
+  // that the pod's owner-only ACL is protection enough and the pod host already
+  // holds your data. It is not the same thing: your data is your data, and the
+  // signing key IS you — whoever holds it is you to every server in the
+  // fediverse, for as long as the key lives, and no ACL reaches the host itself.
+  // So it is wrapped under the account password first, and the host stores
+  // ciphertext. (Three documents already said this was happening. Now it is.)
+  //
+  // Two things in that order, deliberately: the ACL BEFORE the key. Writing the
+  // key first leaves a window where a pod whose root is world-readable serves it
+  // to anyone who asks, and a brought pod is exactly the case where that root
+  // may be public.
+  //
+  // The opened copy is kept in this browser (IndexedDB) so the worker can boot
+  // itself after an idle kill with nobody there to type a password. A browser
+  // that has no copy asks for the password once — see boot.mjs.
+  const keysStep = step('keys');
+  let keys;
+  if (!prog.keysStored) {
+    keysStep.running('making your signing key and locking it under your password');
+    keys = await generateKeys();
+    keys.mintedFor = actorUrl;                                   // one key, one actor (lib/keys.mjs)
+    const remote = new BrowserRemotePod(session, { webId: credential.webId, role: 'signup', log: () => {} });
+    // Owner-only, and THEN the key — one operation, so the order cannot be got
+    // wrong here or anywhere else. A pod that refuses the ACL write is not a
+    // pod this key may sit on, wrapped or not.
+    try {
+      await podState.provisionKey(remote, {
+        stateUrl: `${pod}${AP_ROOT}ap-state/`,
+        keysUrl: keysDocFor(pod),
+        envelope: await wrapKeys(keys, password),
+      });
+    } catch (e) {
+      throw new Error(`could not store the signing key on the pod (${e.message}). `
+        + `The credential is for ${credential.webId} — that WebID must own ${pod} and its ${AP_ROOT} must be writable by it.`);
+    }
+    // This browser's own opened copy, so the boot after the login redirect
+    // needs no password. Best effort: a browser that refuses IndexedDB (private
+    // mode) simply asks for the password on the way back in.
+    await kvPut(keyCacheKey(actorUrl), keys).catch(() => {});
+    prog.keys = keys; prog.keysStored = true;
+    keysStep.ok();
+  } else {
+    keys = prog.keys;
+    keysStep.ok();
+  }
+
+  // Connect the mail door: attach to the gateway (fedipod.net), inbox-only, so
+  // the actor advertises the door as its inbox. The door verifies each delivery
+  // and forwards the clean mail to the pod; the agent trusts the door's receipt.
+  // The same DPoP session proves the pod to the gateway — no password reaches it.
+  let gateway = answers.gateway || prog.gateway || null;
+  if (frontOrigin && !gateway) {
+    const gw = step('gateway');
+    gw.running(`connecting your mail door on ${new URL(frontOrigin).host}`);
+    const res = await session.fetch(`${frontOrigin.replace(/\/$/, '')}/api/attach`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      // podHome is the AP CONTAINER, not the pod root: the front builds the
+      // delivery target as `podHome + 'ap/inbox/'` (lib/front-core.mjs), so a
+      // bare pod root sends this identity's mail to <pod>/ap/inbox/ — outside
+      // the container the agent drains, where nothing would ever read it. The
+      // manage surface has always sent `urls.home`; this is the same value.
+      body: JSON.stringify({ handle, podHome: `${pod}${AP_ROOT}`, actorUrl, kind: 'person' }),
+    });
+    const d = await res.json().catch(() => ({}));
+    if (res.status !== 201 || !d.hmacSecret) {
+      throw new Error(`could not connect the mail door (HTTP ${res.status}): ${d.error || ''}`);
+    }
+    gateway = { url: d.doorInbox, hmacSecret: d.hmacSecret, mode: 'trust' };
+    prog.gateway = gateway;
+    gw.ok();
+  } else if (frontOrigin && gateway) {
+    step('gateway').ok();                                        // resumed
+  }
+
+  const config = {
+    remotePod: pod, root: AP_ROOT, handle, name: handle, issuer: credential.issuerOrigin,
+    ...(gateway ? { gateway } : {}),
+  };
+  // Write the config to the pod (owner-only, beside the key) so a returning
+  // sign-in — which arrives with only an OIDC session — can read the account's
+  // config and key from the pod and boot with no password.
+  const cfgRemote = new BrowserRemotePod(session, { webId: credential.webId, role: 'signup', log: () => {} });
+  try {
+    await podState.writeConfig(cfgRemote, { state: `${pod}${AP_ROOT}ap-state/` }, config);
+  } catch (e) {
+    throw new Error(`could not store the config on the pod (${e.message})`);
+  }
+
+  // The credential was for sign-up, and sign-up is over. The agent runs on the
+  // Solid-OIDC session from here on and never needs it again, so leaving it
+  // alive would leave permanent full access to the pod in a key nothing holds.
+  // Best effort: a server that will not delete it is a credential the owner can
+  // still revoke from their pod's account page, and not a reason to fail a
+  // sign-up that otherwise worked.
+  const revoked = await revokeCredential({
+    resource: credential.resource, accountToken: credential.accountToken,
+  });
+  delete credential.accountToken;              // never leaves this function
+  if (!revoked && credential.resource) {
+    onStep('credential', 'ok', 'this browser is ready (the setup credential could not be '
+      + 'revoked automatically — you can remove it from your pod\'s account page)');
+  }
+
+  PROGRESS.delete(key);                                          // finished — nothing left to resume
+
+  const host = new URL(pod).host;
+  return {
+    credential, config, actorUrl,
+    address: `@${handle}@${host}`,
+    // The opened keys, for booting the agent in THIS browser session right away.
+    // The durable copy on the pod is wrapped under the account password; this
+    // browser also holds an opened one in IndexedDB (above), which is what the
+    // worker reads. A fresh browser asks for the password once and makes its own.
+    keys,
+    keysPublic: { rsa: keys.rsa.publicPem, ed25519: keys.ed25519?.publicPem || null },
+  };
+}

package/web/app/site/_headers

@@ -0,0 +1,9 @@
+/app/*
+  Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data: blob:; media-src 'self' https: blob:; connect-src 'self' https:; font-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'self'; form-action 'self'
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: same-origin
+
+/admin/*
+  Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' https: data: blob:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'; form-action 'self'
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: same-origin

package/web/app/site/_redirects

@@ -0,0 +1,21 @@
+# gateway + front API → the function
+/api/handle             /.netlify/functions/front  200
+/api/attach             /.netlify/functions/front  200
+/api/relay              /.netlify/functions/front  200
+/api/roster             /.netlify/functions/front  200
+/api/revoke             /.netlify/functions/front  200
+/api/agent              /.netlify/functions/front  200
+/u/*                    /.netlify/functions/front  200
+/.well-known/*          /.netlify/functions/front  200
+/install                /.netlify/functions/front  200
+/run                    /.netlify/functions/front  200
+/roster                 /.netlify/functions/front  200
+/solid-oidc-client.js   /.netlify/functions/front  200
+# the in-browser app, served static (these win over the project catch-all)
+/            /index.html    200
+/sw.js       /sw.js         200
+/boot.js     /boot.js       200
+/app         /app/          301
+/app/*       /app/:splat    200
+/admin       /admin/        301
+/admin/*     /admin/:splat  200