fedipod 1.5.0 → 1.7.0

package/lib/device/setup.mjs

@@ -14,11 +14,12 @@ import { pathToFileURL } from 'node:url';
 import * as $rdf from 'rdflib';
 
 import { createAccountWithPod as realCreateAccount } from './account.mjs';
-import { mintCredential as realMint } from './remote.mjs';
+import { mintCredential as realMint, RemotePod } from './remote.mjs';
 import { hashPassword } from '../client/masto/index.mjs';
-import { webfingerHost } from '../core/wire.mjs';
+import { webfingerHost, apUrls, DEFAULT_ROOT } from '../core/wire.mjs';
 import { rootOf, recordLastUsed, writeJsonAtomic } from './home.mjs';
 import { insecureUrlReason } from '../shared/safefetch.mjs';
+import { resourceExists } from '../pod/root.mjs';
 import { CURRENT_LAYOUT, isCurrent } from './migrate.mjs';
 
 const SOLID = $rdf.Namespace('http://www.w3.org/ns/solid/terms#');
@@ -96,6 +97,11 @@ export function setupInputError(a, resuming = false) {
     const badGw = insecureUrlReason(a.gateway.url, 'gateway address');
     if (badGw) return badGw;
   }
+  if (a.shape && a.shape !== 'pod' && a.shape !== 'front') return 'shape must be "pod" or "front"';
+  if (a.gatewayOrigin) {
+    const badO = insecureUrlReason(a.gatewayOrigin, 'gateway address');
+    if (badO) return badO;
+  }
   if (resuming) return null;
   if (a.mode !== 'new' && a.mode !== 'existing') return 'mode must be "new" or "existing"';
   if (!a.issuer) return 'an identity provider is required';
@@ -111,23 +117,61 @@ export function setupInputError(a, resuming = false) {
   return null;
 }
 
+// Where an identity's address lives. A pod on a suffix-based host cannot
+// answer WebFinger for a handle, so its address must live at the Gateway
+// whatever was asked; a pod at its own host root takes the shape chosen.
+export function frontedAddress({ pod, shape }) {
+  const pathPod = pod ? !webfingerHost(pod) : false;
+  return pathPod || shape === 'front';
+}
+
+// Take an address at a Gateway: attach the pod to it, fronted, and return the
+// gateway config bootstrap writes and connect reads. The pod session proves
+// the pod — no password reaches the Gateway. Injected for tests.
+export async function takeGatewayAddress({ home, credential, gatewayOrigin, handle, podHome, actorUrl, kind, log = () => {} }) {
+  const remote = new RemotePod(credential, { home, log });
+  await remote.warmup?.();
+  const origin = String(gatewayOrigin).replace(/\/$/, '');
+  const res = await remote.session.fetch(`${origin}/api/attach`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ handle, podHome, actorUrl, kind: kind === 'group' ? 'group' : 'person', fronted: true }),
+  });
+  const d = await res.json().catch(() => ({}));
+  if (res.status !== 201 || !d.hmacSecret) {
+    throw new Error(`could not take a gateway address at ${new URL(origin).host} (HTTP ${res.status})${d.error ? ': ' + d.error : ''}`);
+  }
+  return {
+    url: `${origin}/u/${handle}/ap/inbox/`,
+    frontActor: String(d.frontActor || `${origin}/u/${handle}/ap/actor`),
+    hmacSecret: String(d.hmacSecret), mode: 'trust',
+  };
+}
+
 // What the CLI printed before asking "create pod and fediverse account?"
 // (bin/fedipod.mjs, the address preview) — as data, so the page can show
 // the same warnings. Pure: no network, so it can answer while you type.
-export function preflight({ mode, pod, issuer, podName, handle, kind }) {
+export function preflight({ mode, pod, issuer, podName, handle, kind, shape = 'pod', gatewayOrigin = 'https://fedipod.net' }) {
   const warnings = [];
   if (!handle) return { ok: false, error: 'a handle is required' };
   let issuerHost;
   try { issuerHost = new URL(issuer || 'https://solidcommunity.net').host; }
   catch { return { ok: false, error: `"${issuer}" is not a URL` }; }
 
+  let gwHost; try { gwHost = new URL(gatewayOrigin).host; } catch { gwHost = 'fedipod.net'; }
+
   if (mode === 'new') {
-    // No warning about whether the server gives the pod its own subdomain. The
-    // run checks what it actually got and fails the account step when a group
-    // lands on a shared host, which is the case that matters; saying it up
-    // front only made the form noisy.
+    // Whether the provider puts the pod on its own subdomain or on a path is
+    // the provider's call, learned only once the pod is made. If the address
+    // was asked to live at the Gateway, it does. Otherwise the pod's own host
+    // is the address, and the run moves it to the Gateway if the provider
+    // turned out to use paths.
+    if (shape === 'front') {
+      if (kind === 'group') return { ok: false, mode, handle, kind, error: 'group-needs-host-root', refusal: 'group-needs-host-root', warnings };
+      return { ok: true, mode, handle, kind, fronted: true, forced: false, gatewayHost: gwHost, shape: 'front',
+        address: `@${handle}@${gwHost}`, webfingerHost: null, resolvable: true, warnings, refusal: null };
+    }
     return {
-      ok: true, mode, handle, kind,
+      ok: true, mode, handle, kind, fronted: false, shape: 'pod',
       address: `@${handle}@${podName || handle}.${issuerHost}`,
       webfingerHost: null, resolvable: null, warnings, refusal: null,
     };
@@ -137,20 +181,26 @@ export function preflight({ mode, pod, issuer, podName, handle, kind }) {
   try { podUrl = new URL(pod); }
   catch { return { ok: false, error: `"${pod}" is not a pod address` }; }
   // A handle resolves through <host>/.well-known/webfinger, so it only works
-  // when the pod owns the root of its host.
+  // when the pod owns the root of its host. A pod that does not can still be
+  // an account, with its address at the Gateway.
   const wfHost = webfingerHost(podUrl.href);
-  let refusal = null;
-  if (!wfHost) {
-    warnings.push('pod-is-a-path');
-    // A person warned about an unresolvable handle is the one who suffers, so
-    // that is their call to accept. Nobody could ever find this group, and the
-    // people it would fail are not the operator reading the warning.
-    if (kind === 'group') refusal = 'group-needs-host-root';
+  const fronted = !wfHost || shape === 'front';
+  if (fronted) {
+    // A person's address moves to the Gateway; a group cannot, yet — a group
+    // needs a pod at its own host until fronted groups are proven.
+    if (kind === 'group') {
+      return { ok: false, mode: 'existing', handle, kind, refusal: 'group-needs-host-root', warnings,
+        address: `@${handle}@${podUrl.host}`, webfingerHost: null, resolvable: false };
+    }
+    return {
+      ok: true, mode: 'existing', handle, kind, fronted: true, forced: !wfHost, gatewayHost: gwHost, shape: 'front',
+      address: `@${handle}@${gwHost}`, webfingerHost: null, resolvable: true, warnings, refusal: null,
+    };
   }
   return {
-    ok: !refusal, mode: 'existing', handle, kind,
-    address: `@${handle}@${wfHost || podUrl.host}`,
-    webfingerHost: wfHost, resolvable: !!wfHost, warnings, refusal,
+    ok: true, mode: 'existing', handle, kind, fronted: false, shape: 'pod',
+    address: `@${handle}@${wfHost}`,
+    webfingerHost: wfHost, resolvable: true, warnings, refusal: null,
   };
 }
 
@@ -160,6 +210,7 @@ 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 attachGateway = deps.attachGateway || takeGatewayAddress;
 
   const at = (key) => run.steps.find(s => s.key === key);
   const begin = (key) => { at(key).state = 'running'; };
@@ -169,9 +220,11 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
   const {
     mode, issuer, email, password, handle, name, podName,
     kind = 'person', approveJoins = false, summary, icon, keys, uiPassword,
-    gateway = null,
+    gateway = null, shape = 'pod', gatewayOrigin = 'https://fedipod.net',
   } = answers;
   let { pod, root } = answers;
+  if (!root) root = 'fedipod/';   // new installs default to the fedipod/ container; a
+  // resuming run overwrites this with the credential's own root below.
   let accountWebId = null;   // what createAccountWithPod reported, when it ran
   // The private half always starts here, beside the credential and the keys —
   // not on the pod. Every activity you receive would otherwise cost the pod
@@ -202,7 +255,7 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
       // nobody could ever find this group. A person was warned before we got
       // here and chose to continue; a group cannot.
       if (kind === 'group' && !webfingerHost(pod)) {
-        throw new Error(`${issuer} created the pod at ${pod} — a path on a shared host, `
+        throw new Error(`${issuer} created the pod at ${pod} — a suffix-based host, `
           + 'not a host root. WebFinger is only answered at a host root, so nobody '
           + 'could find this group. The pod exists; no actor was published.');
       }
@@ -213,6 +266,9 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
       // 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);
+      if (await (deps.resourceExists || resourceExists)(deps.fetch || fetch, apUrls(pod, root || DEFAULT_ROOT).actor)) {
+        throw new Error('The pod already hosts a FediPod account. If you want a second account, put it on a different pod.');
+      }
       skip('account', 'using the pod you already have');
     }
 
@@ -259,6 +315,26 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
       done('credential', credPath);
     }
 
+    // --- take an address at the Gateway, if this pod needs one or asked for
+    // one --- before bootstrap, so the config it writes carries the Gateway
+    // ids and the key connect mints below is stamped to the Gateway actor from
+    // the start. A signup-arranged gateway (the installer carry-over) wins.
+    let gatewayCfg = gateway;
+    if (!gatewayCfg && frontedAddress({ pod, shape })) {
+      if (kind === 'group') {
+        throw new Error(`a group needs a pod at its own host — a Gateway address for a group is not supported yet`
+          + (webfingerHost(pod) ? '' : `; ${pod} is a suffix-based host`) + '.');
+      }
+      const urls = apUrls(pod, root || DEFAULT_ROOT);
+      const cred = JSON.parse(fs.readFileSync(credPath, 'utf8'));
+      log(`taking a gateway address at ${new URL(gatewayOrigin).host}`);
+      gatewayCfg = await attachGateway({
+        home, credential: cred, gatewayOrigin, handle,
+        podHome: urls.home, actorUrl: urls.actor, kind, log,
+      });
+      log(`gateway address @${handle}@${new URL(gatewayOrigin).host}`);
+    }
+
     // --- provision the pod and bring federation up ---
     begin('bootstrap');
     // Resuming skipped the checks the fresh paths ran, and the credential it
@@ -268,7 +344,7 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
       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 });
+    await agent.bootstrap({ handle, name: name || handle, root, kind, approveJoins, summary, icon, gateway: gatewayCfg });
     done('bootstrap');
 
     begin('connect');
@@ -293,14 +369,18 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
       ? `not readable without credentials: ${unreachable.join(', ')}`
       : 'the public surface is reachable');
 
+    // A fronted identity resolves at the Gateway, not the pod host.
+    const frontActor = gatewayCfg?.frontActor || agent.store.getConfig()?.gateway?.frontActor || null;
+    const gwHost = frontActor ? new URL(frontActor).host : null;
     run.result = {
       kind,
       pod,
       handle,
       actor: agent.urls?.actor || null,
-      webfingerHost: wfHost,
-      resolvable: !!wfHost,
-      address: wfHost ? `@${handle}@${wfHost}` : null,
+      fronted: !!frontActor,
+      webfingerHost: gwHost || wfHost,
+      resolvable: !!(gwHost || wfHost),
+      address: gwHost ? `@${handle}@${gwHost}` : (wfHost ? `@${handle}@${wfHost}` : null),
       unreachable,
     };
     run.phase = 'done';

package/lib/gateway/front-core.mjs

@@ -20,6 +20,7 @@ import { handleDelivery } from './gateway-core.mjs';
 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';
 
 // The one WebFinger document, spelled out here rather than imported from
 // wire.mjs: wire drags the agent's whole HTML pipeline (sanitize-html and
@@ -513,20 +514,31 @@ async function route(request, ctx) {
     if (!/^https?:\/\/\S+\/$/.test(podBase)) {
       return j(400, { error: 'podBase must be a URL ending in /' });
     }
-    // An identity needs an origin of its own, so only an origin root may opt
-    // in. Anything deeper would also let one path-pod user claim an ancestor
-    // of another's pod.
-    try {
-      if (new URL(podBase).pathname !== '/') {
-        return j(403, { error: 'podBase must be a pod origin root, like https://mei.example.org/' });
-      }
-    } catch { return j(400, { error: 'podBase is not a URL' }); }
+    let podUrl;
+    try { podUrl = new URL(podBase); } catch { return j(400, { error: 'podBase is not a URL' }); }
+    // A pod may be host-root (its own origin) or on a PATH of a shared host — a
+    // suffix pod, which the Server runs at `https://server/aisha/`. What is
+    // refused is the gateway's own origin root itself: that is where the
+    // gateway lives, not a pod, and admitting it would (with the ownership
+    // fallback below) let a co-tenant claim the whole origin.
+    if (ctx.frontOrigin) {
+      try {
+        if (podUrl.origin === new URL(ctx.frontOrigin).origin && podUrl.pathname === '/') {
+          return j(403, { error: 'that is this gateway, not a pod — name the pod that holds your data' });
+        }
+      } catch { /* no usable frontOrigin: the checks below still apply */ }
+    }
+    if (/(^|\/)\.internal(\/|$)/u.test(podUrl.pathname) || /(^|\/)\.\.(\/|$)/u.test(podUrl.pathname)) {
+      return j(403, { error: 'that is not a pod address' });
+    }
     const webid = await verifyPodToken(request, pathname, ctx.verifier);
     if (!webid) return j(401, { error: 'a Solid-OIDC token proving the pod is required' });
-    // The pod's own server names its owner when it can. Where it does, that is
-    // the proof; where it does not, the WebID must at least live under the pod.
+    // The pod's own server names its owner when it can, and where it does that
+    // is the proof. Where it does not, the WebID must live in EXACTLY this pod
+    // — its own pod base equal to podBase, not merely starting with it, which on
+    // a path server an ancestor of another's pod would.
     const owners = await podOwners(podBase, ctx.fetchImpl || fetch);
-    const proven = owners.length ? owners.includes(webid) : webid.startsWith(podBase);
+    const proven = owners.length ? owners.includes(webid) : podBaseOfWebId(webid) === podBase;
     if (!proven) {
       return j(403, { error: 'the token proves a different pod than the one you listed' });
     }

package/lib/pod/root.mjs

@@ -41,7 +41,7 @@ export async function readOwnerLinks(fetchImpl, podBase, { timeoutMs = OWNER_LOO
  */
 /**
  * Where a provider puts its pods: on hosts of their own, or on paths of one
- * shared host. No spec says. What does say is the storage description at the
+ * suffix-based host. No spec says. What does say is the storage description at the
  * provider's root: a CSS that keeps pods on subdomains answers 501 there,
  * because its root is not a storage; one that keeps them on paths answers 200
  * with the root described as a storage. Anything else is unknown.
@@ -66,6 +66,17 @@ export async function podLayout(fetchImpl, providerOrigin, { timeoutMs = OWNER_L
   return /ns\/pim\/space#Storage|pim:Storage/u.test(body) ? 'path' : null;
 }
 
+// Whether a document is there — one unauthenticated GET, 200 or not. The caller
+// names the URL; asked before a second setup, so a pod that already serves an
+// actor at the app's container refuses another rather than growing a duplicate.
+export async function resourceExists(fetchImpl, url, { timeoutMs = OWNER_LOOKUP_MS } = {}) {
+  try {
+    const res = await fetchImpl(url,
+      { headers: { accept: 'application/activity+json' }, signal: AbortSignal.timeout(timeoutMs) });
+    return !!res && res.status === 200;
+  } catch { return false; }
+}
+
 export async function probeAnswers(podUrl, fetchImpl = fetch) {
   try {
     const res = await fetchImpl(podUrl, { method: 'HEAD' });

package/lib/server/embed.mjs

@@ -47,7 +47,8 @@ const mintSecret = () => crypto.randomBytes(32).toString('base64');
  */
 export async function ensureDoorSecret(session, podBase, { rotate = false, dataDir = null, handle = null, log = () => {} } = {}) {
   const base = podBase.endsWith('/') ? podBase : podBase + '/';
-  const url = apUrls(base, DEFAULT_ROOT).state + 'door-secret.json';
+  // Under the identity's own tree (fedipod/), where the gate reads it back.
+  const url = apUrls(base, 'fedipod/').state + 'door-secret.json';
   const onHost = dataDir && handle ? path.join(dataDir, handle, 'door-secret.json') : null;
 
   if (!rotate) {
@@ -136,7 +137,7 @@ function ensureCredential(home, { podBase, webId }) {
   const rec = {
     webId,
     remotePod: podBase.endsWith('/') ? podBase : podBase + '/',
-    root: 'activitypods-js/',
+    root: 'fedipod/',
     keysMode: 'pod',
   };
   writeJsonAtomic(file, rec, { mode: 0o600 });
@@ -275,7 +276,7 @@ export async function startEmbeddedAgent({
   pollSeconds = null,
   autoAcceptFollows = true,
   gateToken = null,
-  uiPath = '/fedipod/',
+  uiPath = '/fp/',
 }) {
   const base = podBase.endsWith('/') ? podBase : podBase + '/';
   const handle = handleFor(base);
@@ -323,7 +324,7 @@ export async function startEmbeddedAgent({
       throw new Error(`no pod at ${base} yet — its owner profile is not there`);
     }
     log(`no identity on ${base} yet — provisioning @${handle}`);
-    await agent.bootstrap({ handle, name: handle, kind: 'person' });
+    await agent.bootstrap({ handle, name: handle, kind: 'person', root: cred.root });
     if (autoAcceptFollows) {
       agent.store.setConfig({ ...agent.store.getConfig(), autoAcceptFollows: true });
       await agent.store.flush();
@@ -342,15 +343,31 @@ export async function startEmbeddedAgent({
   // speaks, the write API, nodeinfo, and behind the door the admin routes and
   // the web client. Same code the standalone agent serves, minus the routes
   // that only mean something to a process of one's own.
+  //
+  // A pod that lives on a PATH of its host (a suffix pod, e.g.
+  // https://server.example/aisha/) shares its origin with the front and with
+  // every other suffix pod, so its whole surface answers UNDER that path: the
+  // mount is the pod's own pathname, and it is stripped before a route is
+  // matched and folded back into every self-URL. A host-root or subdomain pod
+  // has an empty mount and everything is exactly as it was.
   const authorities = new FixedAuthorities(base);
   agent.authorities = authorities;
+  const mount = new URL(base).pathname.replace(/\/+$/u, '');
   const surface = buildAdminSurface({
     agent,
     log,
-    gate: makeGate(gateToken, { secureCookie: authorities.secure }),
+    // The door cookie is named the same for every identity; on a shared origin
+    // (suffix pods) it has to be scoped to this identity's own door path so two
+    // co-tenants do not overwrite each other's. A host-root/subdomain pod keeps
+    // the whole-origin cookie it always had.
+    gate: makeGate(gateToken, {
+      secureCookie: authorities.secure,
+      cookiePath: mount ? mount + uiPath : '/',
+    }),
     allowed: authorities,
     embedded: true,
     basePath: uiPath,
+    mount,
     publicOrigin: base,
     scheme: new URL(base).protocol,
   });
@@ -399,7 +416,7 @@ export async function startEmbeddedAgent({
   // podHome and actorUrl are the identity's own locations on the pod. They are
   // returned rather than rebuilt by the caller so the root name lives here.
   return {
-    agent, handle, home, surface, host: authorities.host,
+    agent, handle, home, surface, host: authorities.host, mount,
     podHome: urls.home, actorUrl: urls.actor, inboxUrl: urls.inbox, stop,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fedipod",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Standalone single-actor ActivityPub agent whose wire face, RDF truth and state all live on a Solid pod (CSS). Bundles a Phanpy UI and a Mastodon client-API facade.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "cli.md",
     "groups.md",
     "architecture.svg",
-    "installed-agent.md",
+    "device-agent.md",
     "architecture.md",
     "gateway.md",
     "browser.svg"

package/run-agent.mjs

@@ -1,6 +1,6 @@
 // run-agent.mjs — fedipod: a standalone single-actor ActivityPub
 // agent. The remote pod is a RELAY: it serves the public wire face
-// (/activitypods-js/ap/) and buffers inbound mail in a public-append inbox
+// (/fedipod/ap/) and buffers inbound mail in a public-append inbox
 // while this process is off, and it keeps one private document, the lease,
 // because a lock only one machine can reach coordinates nothing.
 //

package/vendor/gate.cjs

@@ -85,7 +85,7 @@ function cookieValue(header, name) {
 // AP_ALLOWED_HOSTS has nothing but this token, so the gate has to be total.
 // `token` may be a function, resolved per request: an identity's secret can
 // rotate while the server runs, and the very next request sees the new one.
-function makeGate(token, { allowOrigins = [], publicEndpoints = false, secureCookie = false } = {}) {
+function makeGate(token, { allowOrigins = [], publicEndpoints = false, secureCookie = false, cookiePath = '/' } = {}) {
   const tokenNow = () => (typeof token === 'function' ? token() : token);
   // gate(req, res) → true when the gate handled the response (caller stops).
   function gate(req, res) {
@@ -102,7 +102,10 @@ function makeGate(token, { allowOrigins = [], publicEndpoints = false, secureCoo
       url.searchParams.delete(COOKIE);
       url.searchParams.delete('dk-bless');
       res.writeHead(302, {
-        'set-cookie': `${COOKIE}=${t}; Path=/; HttpOnly; SameSite=Strict; Max-Age=31536000`
+        // Path scopes the cookie to this identity's own door: on a shared
+        // origin (suffix pods) two co-tenants must not clobber each other's,
+        // and a whole-origin cookie would. Defaults to '/'.
+        'set-cookie': `${COOKIE}=${t}; Path=${cookiePath}; HttpOnly; SameSite=Strict; Max-Age=31536000`
           + (secureCookie ? '; Secure' : ''),
         'location': url.pathname + url.search,
       });

package/web/admin/setup/index.html

@@ -130,9 +130,20 @@ button:disabled { opacity: .5; cursor: default; }
         <label for="issuer-new">Solid pod provider</label>
         <select id="issuer-new" name="issuerNew" aria-describedby="issuer-new-hint">
           <option value="https://solidcommunity.net">solidcommunity.net</option>
+          <option value="https://privatedatapod.com">privatedatapod.com</option>
+          <option value="https://solid.redpencil.io">redpencil.io</option>
+          <option value="https://pods.solidcommunity.au">solidcommunity.au</option>
+          <option value="https://solidweb.me">solidweb.me</option>
+          <option value="https://teamid.live">teamid.live</option>
+          <option value="">Other…</option>
         </select>
-        <p class="hint" id="issuer-new-hint">Providers that give each pod its own subdomain, so the
-          Fediverse address works everywhere.</p>
+        <div id="row-issuer-other" hidden>
+          <label for="issuerOther">Provider address</label>
+          <input type="url" id="issuerOther" name="issuerOther" autocomplete="url" placeholder="https://pods.example.org">
+        </div>
+        <p class="hint" id="issuer-new-hint">The Community Solid Server providers from
+          solidproject.org. A provider that puts pods on paths gives your address at a
+          gateway instead.</p>
       </div>
 
       <div id="row-issuer-existing" hidden>
@@ -170,6 +181,18 @@ button:disabled { opacity: .5; cursor: default; }
       Wrong account or pod?
       <button type="button" id="form-reenter" title="   Discard the credential and enter the account and pod again">Re-enter credentials</button></p>
 
+    <fieldset id="fs-shape" hidden>
+      <legend>Where your address lives</legend>
+      <label class="choice"><input type="radio" name="shape" value="pod" checked> On your pod</label>
+      <label class="choice"><input type="radio" name="shape" value="front"> At a gateway</label>
+      <div id="row-gateway" hidden>
+        <label for="gatewayOrigin">Gateway</label>
+        <input type="url" id="gatewayOrigin" name="gatewayOrigin" value="https://fedipod.net" autocomplete="url">
+        <p class="hint">The gateway answers your address and forwards your mail to your pod.</p>
+      </div>
+      <p class="hint" id="shape-note" hidden></p>
+    </fieldset>
+
     <h2>You will be</h2>
     <p class="address" id="preview">…</p>
     <div id="preview-notes"></div>

package/web/admin/setup/setup.js

@@ -93,12 +93,18 @@ function answers() {
   const f = $('form').elements;
   const kind = f.kind.value;
   const mode = state.resumable ? 'existing' : f.mode.value;
+  const issuer = mode === 'new'
+    ? (f.issuerNew.value || (f.issuerOther ? f.issuerOther.value : '')).trim()
+    : f.issuer.value.trim();
   const a = {
     kind,
     mode,
     handle: f.handle.value.trim(),
-    issuer: (mode === 'new' ? f.issuerNew.value : f.issuer.value).trim(),
+    issuer,
     email: f.email.value.trim(),
+    // Where the address lives; a group cannot front (yet), so it stays 'pod'.
+    shape: (kind === 'group') ? 'pod' : (f.shape ? f.shape.value : 'pod'),
+    gatewayOrigin: (f.gatewayOrigin ? f.gatewayOrigin.value.trim() : '') || 'https://fedipod.net',
   };
   if (mode === 'new') a.podName = f.podName.value.trim() || a.handle;
   else a.pod = f.pod.value.trim();
@@ -128,6 +134,9 @@ function onEdit() {
   $('row-pod').hidden = mode === 'new';
   $('row-issuer-new').hidden = mode !== 'new';
   $('row-issuer-existing').hidden = mode === 'new';
+  const f = $('form').elements;
+  if ($('row-issuer-other')) $('row-issuer-other').hidden = !(mode === 'new' && f.issuerNew.value === '');
+  if ($('row-gateway')) $('row-gateway').hidden = !(f.shape && f.shape.value === 'front');
   clearTimeout(editTimer);
   editTimer = setTimeout(preview, 150);
 }
@@ -140,6 +149,26 @@ async function preview() {
   const { json } = await postJson('/setup/check', a);
   if (!json) return;
   $('preview').textContent = json.address || '…';
+  // The address-shape choice: hidden for a group (a group cannot front yet),
+  // locked to the gateway for a pod on a suffix-based host, an open choice
+  // for a pod at its own host.
+  const f = $('form').elements;
+  const shapeFs = $('fs-shape');
+  if (shapeFs) {
+    const isGroup = a.kind === 'group';
+    shapeFs.hidden = isGroup || (a.mode === 'existing' && !a.pod);
+    const forced = !!json.forced;
+    for (const r of f.shape) r.disabled = forced;
+    if (forced) { for (const r of f.shape) r.checked = r.value === 'front'; }
+    if ($('row-gateway')) $('row-gateway').hidden = !(f.shape.value === 'front');
+    const note = $('shape-note');
+    if (note) {
+      note.hidden = !forced;
+      note.textContent = forced
+        ? 'Your pod is on a suffix-based host, so its address lives at the gateway. Your posts, key and data stay on your pod.'
+        : '';
+    }
+  }
   const notes = $('preview-notes');
   for (const w of json.warnings || []) {
     const p = document.createElement('p');

package/web/app/README.md

@@ -72,6 +72,6 @@ See the `MastoApi` options in `agent.mjs`.
 | **Streaming** | a service worker answers fetches, not sockets. No streaming URL is advertised, so clients poll. |
 | **Web push** | `shims/web-push.mjs` is a no-op. `vapid` is omitted, and a client that subscribes anyway gets a 422 rather than a subscription nothing will push to. |
 | **Scheduled posts** | nothing runs between now and the scheduled time. A `scheduled_at` is refused with a 422 that says so — accepting one was silent loss. |
-| **Groups** | sign-up makes personal identities only (`signup.mjs`), and the moderation surface is not here. Joining a group works; hosting one needs the installed agent. See `groups.md`. |
-| **Changing where the address lives** | the shape is chosen at sign-up (`signup.mjs`): on the pod, `@you@yourpod` with the gateway as a mail door, or at the gateway, `@you@front` — and a pod on a path of a shared host is always fronted. `admin-facade.mjs` refuses changing it afterwards, because a rename needs a restart a browser does not have. |
+| **Groups** | sign-up makes personal identities only (`signup.mjs`), and the moderation surface is not here. Joining a group works; hosting one needs the DeviceAgent. See `groups.md`. |
+| **Changing where the address lives** | the shape is chosen at sign-up (`signup.mjs`): on the pod, `@you@yourpod` with the gateway as a mail door, or at the gateway, `@you@front` — and a pod on a suffix-based host is always fronted. `admin-facade.mjs` refuses changing it afterwards, because a rename needs a restart a browser does not have. |
 | **Moving the private half** | `/state-move` is about filesystem paths and `credential.json`. A browser has neither; its private half is always on the pod. |

package/web/app/admin-facade.mjs

@@ -317,7 +317,7 @@ export class AdminFacade {
         const aliases = [...(cfg.aliases || [])];
         if (body.add) {
           if (!webfingerHost(urls.base) && !cfg.gateway?.frontActor) {
-            return json(400, { error: 'this pod is a path on a shared host, so other servers could never resolve it as a Move target' });
+            return json(400, { error: 'this pod is a suffix-based host, so other servers could never resolve it as a Move target' });
           }
           const id = await this.resolveActor(body.add);
           if (!id) return json(400, { error: `could not fetch the old account (${body.add}) — enter its URL or @user@host, and it must answer` });

package/web/app/agent.mjs

@@ -160,7 +160,7 @@ export class BrowserAgent {
     if (oidc) {
       session = { fetch: (u, i) => oidc.fetch(u, i) };
       webId = oidc.webId;
-      remotePod = podBaseOfWebId(webId);              // the pod, which on a shared host is a path
+      remotePod = podBaseOfWebId(webId);              // the pod, which on a suffix-based host is a path
     } else {
       const dpop = await makeDpopSession(credential);
       session = { fetch: (u, i) => dpop.fetch(u, i) };
@@ -189,7 +189,7 @@ export class BrowserAgent {
     // builds its own urls from `config.root` (publisher.mjs), and a config
     // without one falls to the Node default — so an account set up elsewhere
     // and signed into here would keep its state under `fedipod/` while every
-    // document it published landed under `activitypods-js/`. One root, decided
+    // document it published landed under a different root. One root, decided
     // once, carried by the config everything downstream reads.
     this.store.setConfig({ ...(this.store.getConfig() || {}), ...cfg, root });
     config = this.store.getConfig();
@@ -224,7 +224,7 @@ export class BrowserAgent {
     this.publisher = new Publisher({
       config: this.store.getConfig(), remote: this.remote, store: this.store,
       deliverer: this.deliverer, publicKeyPem: keys.rsaPublicPem, assertionKey: null, log: this.log,
-      // Who a post names, resolved — the same lookup the installed agent
+      // Who a post names, resolved — the same lookup the DeviceAgent
       // gives its publisher. Without it no mention from the browser ever
       // resolved: a direct message went to nobody, a mention notified no one.
       resolveMention: (h) => resolveHandle(this, h),

package/web/app/boot.mjs

@@ -70,7 +70,7 @@ window.fedipodUnlock = async (password) => {
   if (!session) throw new Error('Sign in first.');
   // The config on the pod says where this account's state lives; the key sits
   // beside it. Both are read with the session, as the owner.
-  const podFromWebId = podBaseOfWebId(session.webId);   // a path on a shared host, or its own host
+  const podFromWebId = podBaseOfWebId(session.webId);   // a suffix-based host, or its own host
   const state = `${podFromWebId}${AP_ROOT}ap-state/`;
   // Through the transport rather than the bare session: this is a pod read
   // like any other, and going round it skipped the retry ladder that exists
@@ -288,7 +288,7 @@ if (typeof document !== 'undefined') (async () => {
   // brought by its address, which may be its own host or a path on a shared one.
   const podHostOf = () => { const sub = f().podName.value.trim().toLowerCase(); const ph = providerHost(); return (sub && ph) ? `${sub}.${ph}` : ''; };
   const podUrl = () => { let v = f().pod.value.trim(); if (!v) return ''; if (!/^https?:\/\//i.test(v)) v = 'https://' + v; if (!v.endsWith('/')) v += '/'; try { return new URL(v).href; } catch { return ''; } };
-  // A pod on a path of a shared host cannot answer WebFinger, so its address
+  // A pod on a suffix-based host cannot answer WebFinger, so its address
   // lives at this site; a pod at its own host root gets the choice.
   const isPathPod = (u) => { try { return new URL(u).pathname !== '/'; } catch { return false; } };
   // Where the chosen provider puts new pods, asked of the provider itself