fedipod 1.5.0 → 1.6.0

package/README.md

@@ -16,9 +16,9 @@ There are also a number of [other ways to run FediPod](#other-ways-to-run-fedipo
 - A Solid pod with a host name of its own, such as
   `https://alice.solidcommunity.net/`. Sign-up can create one for you at
   solidcommunity.net or another provider, or use a pod you already have. A
-  pod that lives on a path of a shared host, like `https://server.example/alice/`,
+  pod that lives on a suffix-based host, like `https://server.example/alice/`,
   cannot be a Fediverse address.
-  A pod on a path of a shared host, like `https://server.example/alice/`,
+  A pod on a suffix-based host, like `https://server.example/alice/`,
   works too. Its address is then `@handle@fedipod.net`, because the shared
   host cannot answer for the handle; your posts, key and data stay on your pod.
 - Followers-only and direct posts need a pod that enforces WAC access control.
@@ -33,7 +33,7 @@ There are also a number of [other ways to run FediPod](#other-ways-to-run-fedipo
    permanent; display name, bio and pictures are set later in the client.
    With a pod at its own host you also choose where the address lives: on
    your pod, `@handle@yourpod`, or at this site, `@handle@fedipod.net`. A pod
-   on a path of a shared host gets the fedipod.net address. The choice is
+   on a suffix-based host gets the fedipod.net address. The choice is
    permanent.
 4. Enter your pod password once. It creates the account and locks your
    signing key. The password is not stored.
@@ -73,7 +73,7 @@ an alias, so a Move from it lands here.
 **The manage page.** `manage account` in the bar opens it: your profile,
 aliases, the gateway, key rotation, recovering posts, parking, moving to
 another server, retiring, and clearing a backlog. It is the same interface
-the installed agent has, described in [the admin interface](gui.md).
+the DeviceAgent has, described in [the admin interface](gui.md).
 
 **More than one browser.** One browser runs your account at a time. Opening
 it in a second browser shows your timeline read-only, and the moment you act
@@ -103,7 +103,7 @@ to a gateway of your own. Your address and your data do not change.
 
 ## Other ways to run FediPod
 
-- [The installed agent](installed-agent.md) runs on your own machine and
+- [The DeviceAgent](device-agent.md) runs on your own machine and
   adds scheduled posts, push notifications, live updates, group hosting and
   the use of any Mastodon client.
 - [Groups](groups.md): hosting a discussion group of Fediverse and Bluesky

package/architecture.md

@@ -5,7 +5,7 @@ discovery and stores the public record: the actor, its outbox, followers and
 posts, and the inbox that receives deliveries. The agent provides the
 ActivityPub actions: it drains the inbox, builds the timeline, signs and
 delivers, and answers the Mastodon client. The agent runs either in your
-browser, served by fedipod.net, or as [the installed agent](installed-agent.md)
+browser, served by fedipod.net, or as [the DeviceAgent](device-agent.md)
 on your own machine. Private direct messages, followers-only posts and the
 pending-follow and blocked collections live on the pod in an area protected by
 access control.
@@ -13,7 +13,7 @@ access control.
 A [gateway](gateway.md) can stand in front of the pod: an always-on door that
 verifies each delivery where the signature can still be checked, drops spam,
 and forwards the rest to the pod inbox with a receipt. It holds no key. The
-browser version always has one; the installed agent may use one. Any
+browser version always has one; the DeviceAgent may use one. Any
 lightweight host will do, Netlify included.
 
 [FediPod Server](packages/fedipod-server/README.md) puts the agent inside a
@@ -22,13 +22,13 @@ Fediverse account fed by the server itself.
 
 ![The browser version](https://raw.githubusercontent.com/jeff-zucker/FediPod/main/browser.svg)
 
-![The installed agent, with a gateway](https://raw.githubusercontent.com/jeff-zucker/FediPod/main/architecture.svg)
+![The DeviceAgent, with a gateway](https://raw.githubusercontent.com/jeff-zucker/FediPod/main/architecture.svg)
 
 ## Protocol conformance
 
 FediPod is a full ActivityPub server, on both of the spec's profiles:
 server-to-server (§7) and client-to-server (§6). `POST /ap/outbox` on the
-installed agent takes an activity, or a bare Note, and does the id-minting,
+DeviceAgent takes an activity, or a bare Note, and does the id-minting,
 side-effects and delivery, authenticated by a Solid-OIDC token whose WebID is
 the owner's. The Mastodon REST API is the everyday client interface; C2S is
 the spec's own.

package/cli.md

@@ -29,6 +29,13 @@ pod account as part of it, `--keys pod` puts the signing key in pod state for
 multi-device use, and `AP_PASSWORD` supplies the pod password without a
 prompt. `--profile NAME` names the new identity when you have more than one.
 
+`--address pod` (the default) puts your address on your pod, `@you@yourpod`;
+`--address front` puts it at a gateway, `@you@the-gateway`, with your posts,
+key and data still on your pod. `--gateway <url>` names the gateway
+(`https://fedipod.net` by default). A pod on a suffix-based host cannot
+answer WebFinger for a handle, so it always takes a gateway address, whichever
+`--address` you gave.
+
 ## Which identity a command acts on
 
 `--profile NAME` works on every command, not just `up`; `AP_PROFILE` is the

package/gateway.md

@@ -29,7 +29,7 @@ password is typed anywhere:
    restarts the agent itself to publish under it.
 
 In the BrowserAgent the same choice is made once, at sign-up, and cannot be
-changed afterwards. A pod on a path of a shared host, like
+changed afterwards. A pod on a suffix-based host, like
 `https://server.example/alice/`, always takes the gateway-based name: nothing
 at that host answers for the handle, so the gateway does. Its posts, key and
 data stay on the pod.

package/groups.md

@@ -14,7 +14,7 @@ and pick group rather than person, or take the group path on a signup page.
 You can turn on join review as you create it. The group's pod must be the root
 of its own host, so its handle resolves.
 
-**Running a group needs the installed agent.** The in-browser build makes
+**Running a group needs the DeviceAgent.** The in-browser build makes
 personal identities only — the sign-up wizard has no group option, and the
 moderation surface (join review, members, muting, the moderation queue) is not
 part of that build. You can *join* a group from the browser exactly as from

package/gui.md

@@ -2,7 +2,7 @@
 
 In the browser version at fedipod.net, `manage account` in the bar opens this
 same page for your account. The rest of this page describes it as the
-installed agent serves it; the controls are the same, minus the manual inbox
+DeviceAgent serves it; the controls are the same, minus the manual inbox
 drain and the local log, which a browser does not have.
 
 Open `https://localhost:8030/` while any agent is running — it forwards you to the agent — then choose `manage account` and select the actor you want from the local actors dropdown.

package/lib/core/publisher/index.mjs

@@ -201,7 +201,7 @@ export class Publisher {
     this.log(this.config.gateway?.frontActor || wire.webfingerHost(urls.base)
       ? `profile published: @${pubName}@${pubHost} → ${urls.actor}`
       : `profile published → ${urls.actor} — NOT discoverable as @${pubName}@${pubHost}: `
-        + 'this pod is a path on a shared host, and WebFinger is only answered at a host root');
+        + 'this pod is a suffix-based host, and WebFinger is only answered at a host root');
     return { unreachable, updated };
   }
 

package/lib/device/admin/routes/lifecycle.mjs

@@ -102,7 +102,7 @@ export async function post(p, body, ctx, req, res) {   // eslint-disable-line no
         // A Move target nobody can resolve is a landing pad nobody lands on.
         if (!webfingerHost(urls.base) && !cfg.gateway?.frontActor) {
           return json(res, 400, {
-            error: 'this pod is a path on a shared host, so WebFinger cannot answer for it '
+            error: 'this pod is a suffix-based host, so WebFinger cannot answer for it '
               + '— other servers could never resolve this account as a Move target',
           });
         }

package/lib/device/admin/routes/setup.mjs

@@ -12,6 +12,7 @@ import { identityHomes, rootOf, tildify, writeJsonAtomic } from '../../home.mjs'
 import { copyPrivateHalf, isCurrent, CURRENT_LAYOUT } from '../../migrate.mjs';
 import { insecureUrlReason } from '../../../shared/safefetch.mjs';
 import { newRun, preflight, runSetup, setupInputError, hasCredential, credentialPath } from '../../setup.mjs';
+import { podLayout } from '../../../pod/root.mjs';
 import { portFree, freePortFrom } from '../../ports.mjs';
 import { yieldDirectory } from '../../../gateway/directory.mjs';
 import { localFetch } from '../../../client/localapi.mjs';
@@ -113,7 +114,25 @@ export async function post(p, body, ctx, req, res) {   // eslint-disable-line no
       return true;
     }
     // ---- setup, driven by the page at /admin/setup/ ----
-    case '/setup/check': return json(res, 200, preflight(body));
+    case '/setup/check': {
+      const pre = preflight(body);
+      // For a new pod, ask the provider where it puts pods, so the page can
+      // show the Gateway address before the pod exists. A provider on paths
+      // means the address must live at the Gateway; the run decides for real.
+      if (pre.ok && body.mode === 'new' && body.shape !== 'front') {
+        const layout = await podLayout(fetch, body.issuer || '').catch(() => null);
+        if (layout === 'path') {
+          if ((body.kind || 'person') === 'group') {
+            return json(res, 200, { ...pre, ok: false, layout, refusal: 'group-needs-host-root' });
+          }
+          let gwHost; try { gwHost = new URL(body.gatewayOrigin || 'https://fedipod.net').host; } catch { gwHost = 'fedipod.net'; }
+          return json(res, 200, { ...pre, layout, fronted: true, forced: true, shape: 'front', gatewayHost: gwHost,
+            address: `@${body.handle}@${gwHost}`, resolvable: true });
+        }
+        return json(res, 200, { ...pre, layout });
+      }
+      return json(res, 200, pre);
+    }
     // Discard a credential that never finished setup, so the account and
     // pod can be entered again. The credential a CSS server mints is shown
     // once, so a setup that stops after the mint (a wrong pod answers 401

package/lib/device/cli/commands/setup.mjs

@@ -79,9 +79,26 @@ const name = flag('name') || await ask('display name (shown above your address)'
 // A handle resolves through <host>/.well-known/webfinger, so it only works
 // when the pod owns the root of its host. Whether a NEW pod gets its own
 // subdomain is the server's call, so promise nothing here we cannot keep.
-const { webfingerHost } = await import(new URL('../../../../lib/core/wire.mjs', import.meta.url));
+const { webfingerHost, apUrls, DEFAULT_ROOT } = await import(new URL('../../../../lib/core/wire.mjs', import.meta.url));
 const issuerHost = new URL(issuer).host;
 const wfHost = newAccount ? null : webfingerHost(pod);
+
+// Where the address lives: on the pod (default), or at a gateway. A pod on a
+// suffix-based host cannot answer WebFinger for a handle, so its address
+// is at the gateway whatever was asked. `--address front` takes a gateway
+// address for a host-root pod too; `--gateway <origin>` names the gateway.
+const addressShape = String(flag('address') || 'pod').toLowerCase();
+if (addressShape !== 'pod' && addressShape !== 'front') { console.error('--address must be pod or front'); process.exit(2); }
+const gatewayOrigin = flag('gateway') || 'https://fedipod.net';
+{ const badGw = insecureUrlReason(gatewayOrigin, 'gateway address'); if (badGw) { console.error(badGw); process.exit(2); } }
+const gatewayHost = new URL(gatewayOrigin).host;
+// For an EXISTING pod the shape is known now; for a NEW pod the path case is
+// decided after the pod is made, below.
+let fronted = (!newAccount && !wfHost) || addressShape === 'front';
+if (fronted && kind === 'group') {
+  console.error('a group needs a pod at its own host — a gateway address for a group is not supported yet.');
+  process.exit(2);
+}
 // A person warned about an unresolvable handle is the one who suffers, so a
 // warning is their call to accept. Nobody could ever find this group, and the
 // people it would fail are not the operator reading the warning.
@@ -93,20 +110,16 @@ if (kind === 'group' && !newAccount && !wfHost) {
 }
 console.log(kind === 'group' ? '\nThe group will be:\n' : '\nYou will be:\n');
 console.log(`  ${name}`);
-if (wfHost) {
+if (fronted) {
+  console.log(`  @${handle}@${gatewayHost}\n`);
+  console.log(`— your address lives at ${gatewayHost}; your posts, key and data stay on your pod.\n`);
+} else if (wfHost) {
   console.log(`  @${handle}@${wfHost}\n`);
 } else if (newAccount) {
   console.log(`  @${handle}@${podName}.${issuerHost}\n`);
-  console.log(`— provided ${issuerHost} gives each pod its own subdomain. Some servers put`);
-  console.log(`pods at ${issuerHost}/${podName}/ instead, and a pod sharing a host cannot`);
-  console.log('answer WebFinger for an address. Setup checks which you got and says so');
-  console.log('before publishing anything.\n');
-} else {
-  console.log(`  @${handle}@${new URL(pod).host}   —   WILL NOT RESOLVE\n`);
-  console.log(`This pod is ${pod} — a path on ${new URL(pod).host}, not the root of its own`);
-  console.log('host. WebFinger is answered only at a host root, which this pod cannot');
-  console.log('write to, so other servers will not find you. Posting and reading still');
-  console.log('work; being discovered does not.\n');
+  console.log(`— provided ${issuerHost} gives each pod its own subdomain. A server that puts`);
+  console.log(`pods at ${issuerHost}/${podName}/ instead cannot answer WebFinger for an address,`);
+  console.log(`so setup takes an address at ${gatewayHost} for you and says so.\n`);
 }
 console.log('The display name can be changed later; the handle and pod cannot.');
 const go = await ask(newAccount
@@ -123,14 +136,15 @@ if (newAccount) {
   pod = made.pod;
   console.log(`account + pod created: ${pod}`);
   if (!webfingerHost(pod)) {
-    console.log(`\n${issuerHost} created the pod at a path rather than on its own subdomain,`);
-    console.log(`so @${handle}@\u2026 cannot be discovered by other Fediverse servers.`);
-    const cont = kind === 'group' ? 'n' : (interactive ? await ask('continue anyway? (y/n)', 'n') : 'y');
-    endAsking();
-    if (!/^y/i.test(cont)) {
-      console.log('stopping \u2014 the pod exists, but no actor was published');
+    if (kind === 'group') {
+      console.log(`\n${issuerHost} created the pod at ${pod} — a suffix-based host.`);
+      console.log('WebFinger is answered only at a host root, so nobody could find this group.');
+      console.log('The pod exists; no actor was published.');
       process.exit(0);
     }
+    // A path pod's address lives at the gateway; nothing to warn about.
+    fronted = true;
+    console.log(`${issuerHost} puts pods on paths, so your address will be @${handle}@${gatewayHost}.`);
   }
 }
 
@@ -164,13 +178,23 @@ if (rootOf(HOME) === AP_ROOT) recordLastUsed(AP_ROOT, path.basename(HOME));
 recordAgent({ port: PORT, handle });   // later commands need no --port
 console.log(`credential minted and saved to ${path.join(HOME, 'credential.json')}`);
 
+let gatewayCfg = null;
+if (fronted) {
+  const { takeGatewayAddress } = await import(new URL('../../../../lib/device/setup.mjs', import.meta.url));
+  const urls = apUrls(pod, root || DEFAULT_ROOT);
+  console.log(`taking a gateway address at ${gatewayHost}`);
+  gatewayCfg = await takeGatewayAddress({
+    home: HOME, credential: rec, gatewayOrigin, handle,
+    podHome: urls.home, actorUrl: urls.actor, kind, log: (...a) => console.log('[setup]', ...a),
+  });
+}
 const { Agent } = await import(new URL('../../../../run-agent.mjs', import.meta.url));
 const agent = new Agent({ home: HOME, log: (...a) => console.log('[setup]', ...a) });
-await agent.bootstrap({ handle, name, root, kind, approveJoins, summary, icon });
+await agent.bootstrap({ handle, name, root, kind, approveJoins, summary, icon, gateway: gatewayCfg });
 await agent.connect({ repair: false });   // publishProfile below is the publish
 await agent.publisher.publishProfile();
 await agent.store.flush();
-const finalHost = webfingerHost(rec.remotePod);
+const finalHost = gatewayCfg ? gatewayHost : webfingerHost(rec.remotePod);
 const what = kind === 'group' ? 'group' : 'actor';
 console.log(finalHost
   ? `${what} published: @${handle}@${finalHost}`

package/lib/device/setup.mjs

@@ -14,9 +14,9 @@ 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 { CURRENT_LAYOUT, isCurrent } from './migrate.mjs';
@@ -96,6 +96,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 +116,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 +180,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 +209,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,7 +219,7 @@ 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;
   let accountWebId = null;   // what createAccountWithPod reported, when it ran
@@ -202,7 +252,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.');
       }
@@ -259,6 +309,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 +338,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 +363,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/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fedipod",
-  "version": "1.5.0",
+  "version": "1.6.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",

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` });