fedipod 1.5.0 → 1.7.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/{installed-agent.md → device-agent.md}

@@ -1,4 +1,4 @@
-# The installed agent
+# The DeviceAgent
 
 FediPod can also run as a program on your own machine, in front of the same
 kind of pod. It does everything the browser version at fedipod.net does, plus
@@ -10,9 +10,11 @@ connect to it; and it can host a [group](groups.md).
 ## Requirements
 
 - Node 20 or newer.
-- A Solid pod with a host name of its own, such as
-  `https://alice.solidcommunity.net/`. A pod on a path of a shared host cannot
-  be a Fediverse address.
+- A Solid pod, either with a host name of its own, such as
+  `https://alice.solidcommunity.net/`, or on a suffix-based host, such as
+  `https://server.example/alice/`. A pod at its own host carries its address on
+  the pod; a pod on a suffix-based host takes its address at a gateway,
+  `@handle@fedipod.net`, with the posts, key and data staying on the pod.
 - Followers-only and direct posts need a pod that enforces WAC access control;
   on one that does not, the composer refuses those two and says why.
 - While the agent is off, your mail waits on your pod's host. Run it as a

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
@@ -59,7 +59,7 @@ A followed group's own announced deletion of a post it carried to you is honoure
 ## Inviting people
 
 A group has a page anyone can open, at `ap/profile.html` under its pod's
-app container — `<pod>/activitypods-js/ap/profile.html`. It
+app container — `<pod>/fedipod/ap/profile.html`. It
 carries the group's address and a Follow box that sends a visitor to their
 own server's follow screen, so it is the link to put where people will find
 it. Posts the group carries appear in members' timelines as the group

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.
@@ -46,7 +46,7 @@ its own port.
 ## Sharing an account
 
 Each identity has a page anyone can open, at `ap/profile.html` under its pod
-— for example `https://your-pod.example/activitypods-js/ap/profile.html`. It
+— for example `https://your-pod.example/fedipod/ap/profile.html`. It
 shows the name, bio and address, and offers a Follow box: a visitor types
 their own server and lands on that server's follow screen. Hand out that
 link, or the `@name@host` address itself, which works in the search box of

package/lib/client/masto/index.mjs

@@ -32,8 +32,14 @@ export { attachmentType, extensionFor } from './media.mjs';
 
 export class MastoApi {
   constructor({ agent, log = console.log, allowed = null, scheme = null, embedded = false,
-    streaming = true, webPush = true, scheduling = true }) {
+    mount = '', streaming = true, webPush = true, scheduling = true }) {
     this.agent = agent;
+    // The path this identity's surface answers under, when it shares its origin
+    // with others (a suffix pod, e.g. `/aisha`). Empty for a host-root or
+    // subdomain pod. Folded into the self-URLs the client is handed —
+    // pagination links, the OAuth issuer — so they name the address the client
+    // actually reached.
+    this.mount = mount;
     // A server-hosted identity has no CLI of its own, so the advice this gives
     // when it refuses has to name the route that identity really has.
     this.embedded = embedded;

package/lib/client/masto/timelines.mjs

@@ -254,7 +254,7 @@ export async function handle(api, ctx) {
 
     // A client pages by following these rather than by guessing ids.
     if (page.length) {
-      const base = `${api.scheme || (req.socket?.encrypted ? 'https' : 'http')}://${req.headers.host}${pathname}`;
+      const base = `${api.scheme || (req.socket?.encrypted ? 'https' : 'http')}://${req.headers.host}${api.mount || ''}${pathname}`;
       const link = (params) => {
         const u = new URL(base);
         for (const [k, v] of q) if (k !== 'max_id' && k !== 'since_id' && k !== 'min_id') u.searchParams.append(k, v);

package/lib/client/oidc-auth.mjs

@@ -8,7 +8,7 @@
 // The verifier is injected so offline tests stub it, and wrapped so the
 // library (CJS, older jose) can be replaced without touching any caller.
 
-export function makeC2sAuth({ agent, masto = null, verifier = null, log = () => {}, scheme = null }) {
+export function makeC2sAuth({ agent, masto = null, verifier = null, log = () => {}, scheme = null, mount = '' }) {
   let verify = verifier;
   const loadVerifier = async () => {
     if (!verify) {
@@ -31,9 +31,11 @@ export function makeC2sAuth({ agent, masto = null, verifier = null, log = () =>
       // The URL the client signed its proof over. The Host header already
       // passed the Authorities firewall, so whichever alias the client used
       // (localhost, 127.0.0.1, the named origin) is one this agent answers on;
-      // the scheme is whichever listener the request arrived on.
+      // the scheme is whichever listener the request arrived on. `pathname` is
+      // relative to this identity's mount, so a suffix pod folds the mount back
+      // in — the client signed over the full path it actually requested.
       const htu = `${scheme ? scheme.replace(/:$/u, '') : req.socket?.encrypted ? 'https' : 'http'
-      }://${req.headers.host}${pathname}`;
+      }://${req.headers.host}${mount}${pathname}`;
       ({ webid } = await v(
         req.headers.authorization,
         req.headers.dpop ? { header: req.headers.dpop, method: req.method, url: htu } : undefined,

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/core/wire.mjs

@@ -20,7 +20,10 @@ export { webfingerHost } from '../pod/urls.mjs';
 // contains; the browser build states `fedipod/` on its own configs. A config
 // that names a root is always believed — this is only the answer for one that
 // does not.
-export const DEFAULT_ROOT = 'activitypods-js/';
+// Every build writes its data into a `fedipod/` container in the pod. This is
+// the answer for a config that names no root; a config that names one is always
+// believed. (`activitypods-js/` was an earlier name, now abandoned.)
+export const DEFAULT_ROOT = 'fedipod/';
 
 // The handle the fediverse sees: a fronted identity's name is the front's.
 export function publicHandle(config) {

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

@@ -47,7 +47,7 @@ export async function post(p, body, ctx, req, res) {   // eslint-disable-line no
       };
       const podActorId = () => {
         const base = cfg.remotePod.endsWith('/') ? cfg.remotePod : `${cfg.remotePod}/`;
-        const root = cfg.root ? (cfg.root.endsWith('/') ? cfg.root : `${cfg.root}/`) : 'activitypods-js/';
+        const root = cfg.root ? (cfg.root.endsWith('/') ? cfg.root : `${cfg.root}/`) : 'fedipod/';
         return `${base}${root}ap/actor`;
       };
       // The reply first, the restart a beat later — same shape as /update.

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/admin/surface.mjs

@@ -76,14 +76,14 @@ const ROUTES = [owner, setup, lifecycle, gateway, social, connections];
 // a fediverse instance must let strangers reach /api and /oauth, so the gate
 // guards the operator's door (basePath) instead of the whole surface.
 export function buildAdminSurface({ agent, gate, allowed, log = console.log,
-  port = null, handle = null, embedded = false, basePath = '/',
+  port = null, handle = null, embedded = false, basePath = '/', mount = '',
   publicOrigin = null, scheme = null,
   versionOnDisk = () => localVersion(projectRoot) }) {
   const json = (res, status, obj) => sendJson(res, status, obj, allowed);
-  const masto = new MastoApi({ agent, log, allowed, scheme, embedded });
+  const masto = new MastoApi({ agent, log, allowed, scheme, embedded, mount });
   // The spec's own write API (§6), beside the facade. Its bearer fallback is
   // the facade's token, so the two surfaces share one notion of the operator.
-  const c2s = new C2S({ agent, log, auth: makeC2sAuth({ agent, masto, log, scheme }) });
+  const c2s = new C2S({ agent, log, auth: makeC2sAuth({ agent, masto, log, scheme, mount }) });
   const streaming = new Streaming({ masto, log, allowed, gate, gateOptional: embedded });
   // Asked per request, not once here: startAdmin runs before connect, so the
   // kind is not known yet at mount time.
@@ -104,21 +104,29 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
     } catch (e) { log(`streaming broadcast: ${e.message}`); }
   };
 
-  // A path as the browser must ask for it: behind the door, prefixed with it.
-  const atPath = (p_) => (basePath === '/' ? p_ : basePath.slice(0, -1) + p_);
+  // A path as the browser must ask for it: under this identity's mount (a
+  // suffix pod's own path, or nothing) and behind the door, prefixed with it.
+  const atPath = (p_) => mount + (basePath === '/' ? p_ : basePath.slice(0, -1) + p_);
 
   // What every route may reach: the agent and the deployment's facts.
   const ctx = { agent, log, allowed, embedded, port, handle, publicOrigin, versionOnDisk, isGroup, json, setup: setup_ };
 
   const handler = async (req, res) => {
     const url = new URL(req.url, 'http://localhost');
+    // A suffix pod's surface answers under its mount (its own path on a shared
+    // host). Strip it once, here, so every route below is matched relative to
+    // the mount and a host-root/subdomain pod (empty mount) is unchanged. The
+    // full path stays on `url`/`req.url` for self-URLs that fold the mount back
+    // in themselves (the pagination base, the DPoP htu).
+    let p = url.pathname;
+    if (mount && (p === mount || p.startsWith(mount + '/'))) p = p.slice(mount.length) || '/';
     // Mastodon-style: the bearer-gated client API and the OAuth + nodeinfo
     // routes answer any origin — a browser client is served the way any
     // instance serves it. CORS headers and the preflight make that work; the
     // bearer stays the only credential, and the Host check below (which is
     // what stops DNS rebinding) still runs.
-    const apiPath = url.pathname.startsWith('/api/') || url.pathname.startsWith('/oauth/')
-      || url.pathname === '/.well-known/nodeinfo' || url.pathname === '/nodeinfo/2.0';
+    const apiPath = p.startsWith('/api/') || p.startsWith('/oauth/')
+      || p === '/.well-known/nodeinfo' || p === '/nodeinfo/2.0';
     if (apiPath) {
       res.setHeader('access-control-allow-origin', '*');
       res.setHeader('access-control-expose-headers', 'Link');
@@ -142,11 +150,11 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
       res.end('forbidden\n');
       return;
     }
-    let p = url.pathname;
-    // Embedded, the operator's door is one path on the pod's origin. Behind it
-    // is everything that was the admin server; in front of it are the protocol
-    // routes, which have to answer strangers because that is what makes the pod
-    // an instance other software can talk to.
+    // Embedded, the operator's door is one path on the pod's origin (under the
+    // mount, when there is one). Behind it is everything that was the admin
+    // server; in front of it are the protocol routes, which have to answer
+    // strangers because that is what makes the pod an instance other software
+    // can talk to.
     let atDoor = !embedded;
     if (embedded && basePath !== '/'
       && (p === basePath.slice(0, -1) || p.startsWith(basePath))) {
@@ -171,7 +179,7 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
       // above still decides who gets this far.
       if (p === '/.well-known/oauth-authorization-server') {
         const scheme = req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https' ? 'https' : 'http';
-        return json(res, 200, masto.authorizationServerMetadata(`${scheme}://${req.headers.host}`));
+        return json(res, 200, masto.authorizationServerMetadata(`${scheme}://${req.headers.host}${mount}`));
       }
       if (atDoor && gate(req, res)) return;
       if (p === '/api/v1/streaming/health') {
@@ -180,7 +188,7 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
       // NodeInfo on the agent origin — clients probe it at login.
       if (p === '/.well-known/nodeinfo') {
         return json(res, 200, nodeinfoPointer(
-          `${req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https' ? 'https' : 'http'}://${req.headers.host}/nodeinfo/2.0`));
+          `${req.socket.encrypted || req.headers['x-forwarded-proto'] === 'https' ? 'https' : 'http'}://${req.headers.host}${mount}/nodeinfo/2.0`));
       }
       if (p === '/nodeinfo/2.0') {
         return json(res, 200, nodeinfoDoc({
@@ -206,8 +214,8 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
         // Our own pages come before the group check: a group is set up in the
         // browser like anything else, and it has a record to edit. It still
         // serves no fediverse client — see the 404 two lines down.
-        const mount = webMount(p);
-        if (mount) {
+        const wmount = webMount(p);
+        if (wmount) {
           // Without the slash a page's own relative <script src> resolves one
           // level up and 404s — and that is true at any depth, so ask the
           // filesystem rather than only special-casing the mount itself.
@@ -217,7 +225,7 @@ export function buildAdminSurface({ agent, gate, allowed, log = console.log,
             res.end();
             return;
           }
-          return serveWeb(res, p, mount, allowed);
+          return serveWeb(res, p, wmount, allowed);
         }
         // The bare URL means "show me what this agent wants from me now".
         // Keyed on the credential FILE, never on configured(): a healthy

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

@@ -18,7 +18,7 @@ export async function setup() {
   if (process.stdin.isTTY && !has('cli') && !IDENTITY_FLAGS.some(f => args.includes('--' + f))) {
     return runBrowserSetup();
   }
-const root = flag('root');
+const root = flag('root') || 'fedipod/';   // new installs default to the fedipod/ container
 const kind = has('group') ? 'group' : 'person';
 const approveJoins = has('group') && has('approve-joins');
 const summary = flag('summary');
@@ -48,6 +48,14 @@ if (!newAccount && !pod) {
   }
 }
 if (!newAccount && !pod) { console.error('no pod given'); process.exit(2); }
+if (!newAccount) {
+  const { resourceExists } = await import(new URL('../../../../lib/pod/root.mjs', import.meta.url));
+  const { apUrls, DEFAULT_ROOT: DR } = await import(new URL('../../../../lib/core/wire.mjs', import.meta.url));
+  if (await resourceExists(fetch, apUrls(pod, DR).actor)) {
+    console.error('The pod already hosts a FediPod account. If you want a second account, put it on a different pod.');
+    process.exit(2);
+  }
+}
 
 const issuer = flag('issuer') || await ask('Solid identity provider', 'https://solidcommunity.net');
 // Before the password is asked for, let alone sent. The issuer is where it
@@ -79,9 +87,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 +118,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 +144,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 +186,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}`