fedipod 1.4.1 → 1.6.0

package/README.md

@@ -16,8 +16,11 @@ 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 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.
   On one that does not, the composer refuses those two and says why. Public
   and unlisted posts work on any pod.
@@ -28,6 +31,10 @@ There are also a number of [other ways to run FediPod](#other-ways-to-run-fedipo
 2. Choose a pod: a new one at the provider you name, or a pod you already have.
 3. Choose your handle. Your address is `@handle@yourpod`. Both parts are
    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 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.
 
@@ -66,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
@@ -96,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

@@ -28,6 +28,12 @@ password is typed anywhere:
    way. A pod-based attach applies immediately; taking a gateway-based name
    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 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.
+
 The same attach from the command line, against the running agent:
 
 ```

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/client/masto/index.mjs

@@ -78,7 +78,12 @@ export class MastoApi {
     });
     return this._push;
   }
-  get host() { return this.urls ? new URL(this.urls.base).host : 'unconfigured.invalid'; }
+  // The host in the owner's own address: the gateway's when the identity is
+  // fronted (its documents still live on the pod, but its name does not).
+  get host() {
+    if (!this.urls) return 'unconfigured.invalid';
+    return new URL(this.urls.publicHome || this.urls.base).host;
+  }
 
   // Where the live feed is, as the CLIENT must address it: this agent's own
   // origin, taken from the request, not the pod's host. An instance document

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

@@ -49,9 +49,10 @@ export function hostMeta(base) {
   return `<?xml version="1.0" encoding="UTF-8"?>\n<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">\n  <Link rel="lrdd" template="${base}.well-known/webfinger?resource={uri}"/>\n</XRD>\n`;
 }
 
-export function jrd({ handle, host, actor }) {
+export function jrd({ handle, host, actor, aliases = [] }) {
   return {
     subject: `acct:${handle}@${host}`,
+    ...(aliases.length ? { aliases } : {}),
     links: [{ rel: 'self', type: 'application/activity+json', href: actor }],
   };
 }

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

@@ -25,8 +25,9 @@ import * as podPolicy from '../pod/policy.mjs';
 // wire.mjs: wire drags the agent's whole HTML pipeline (sanitize-html and
 // friends), which a serverless front must never carry — it crashed the
 // deployed function before it answered its first request.
-const jrd = ({ handle, host, actor }) => ({
+const jrd = ({ handle, host, actor, aliases = [] }) => ({
   subject: `acct:${handle}@${host}`,
+  ...(aliases.length ? { aliases } : {}),
   links: [{ rel: 'self', type: 'application/activity+json', href: actor }],
 });
 
@@ -580,7 +581,11 @@ async function route(request, ctx) {
     if (!m || m[2] !== ctx.host) return notFound();
     const rec = await ctx.lookup(m[1]);
     if (!rec) return notFound();
-    return j(200, jrd({ handle: m[1], host: ctx.host, actor: rec.actorUrl }),
+    // A fronted identity's documents live on its pod; the pod's own actor id
+    // is the alias, so a client signing in by the fronted address can find
+    // the pod (and its login) without a lookup only the host could answer.
+    const podActor = rec.inboxOnly ? [] : [rec.podHome + 'ap/actor'];
+    return j(200, jrd({ handle: m[1], host: ctx.host, actor: rec.actorUrl, aliases: podActor }),
       'application/jrd+json');
   }
 
@@ -607,6 +612,13 @@ async function route(request, ctx) {
   // fixed to the front so a consumer cross-checks it consistently.
   if (request.method !== 'GET' && request.method !== 'HEAD') return { status: 405, headers: {}, body: '' };
   const podTarget = rec.podHome + up.rest;
+  // Media stays on the pod (lib/pod/urls.mjs keeps `media` off the front), but
+  // the id rewrite below turns media links onto the front like every other
+  // pod url in a document. Answer those by pointing at the pod: bytes are not
+  // a document to cap and relabel, and remotes follow a redirect for a picture.
+  if (up.rest.startsWith('ap/media/')) {
+    return { status: 302, headers: { location: podTarget, 'cache-control': 'no-store' }, body: '' };
+  }
   // The pod this read belongs to travels with it: an adapter reading a store
   // directly (the CSS server component) has no access control of its own and
   // needs to be told what it may reach. See podHomeProblem above for the other

package/lib/pod/root.mjs

@@ -39,6 +39,33 @@ export async function readOwnerLinks(fetchImpl, podBase, { timeoutMs = OWNER_LOO
  *
  * ---- asked by: a provisioning client, about a pod the person brought ----
  */
+/**
+ * Where a provider puts its pods: on hosts of their own, or on paths of one
+ * 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.
+ *
+ * Decides, at sign-up, whether the address can live on the pod at all: a pod
+ * on a path shares its host, so nothing there answers WebFinger for it.
+ *
+ * @returns 'host' | 'path' | null
+ */
+export async function podLayout(fetchImpl, providerOrigin, { timeoutMs = OWNER_LOOKUP_MS } = {}) {
+  let origin;
+  try { origin = new URL(providerOrigin).origin; } catch { return null; }
+  let res;
+  try {
+    res = await fetchImpl(`${origin}/.well-known/solid`,
+      { headers: { accept: 'text/turtle' }, signal: AbortSignal.timeout(timeoutMs) });
+  } catch { return null; }
+  if (res.status === 501) return 'host';
+  if (res.status !== 200) return null;
+  let body = '';
+  try { body = await readCapped(res, 64 * 1024); } catch { return null; }
+  return /ns\/pim\/space#Storage|pim:Storage/u.test(body) ? 'path' : null;
+}
+
 export async function probeAnswers(podUrl, fetchImpl = fetch) {
   try {
     const res = await fetchImpl(podUrl, { method: 'HEAD' });

package/lib/pod/transport.mjs

@@ -334,9 +334,14 @@ export class PodTransport {
   }
 
   async setAcl(targetUrl, publicModes, opts = {}) {
-    const url = await this.aclUrlFor(targetUrl);
+    // The rule names the resource on the POD. A fronted identity hands in
+    // advertised urls; `fetch` maps the request, but a rule whose accessTo
+    // named the advertised url would guard a resource the pod does not have,
+    // and lock the real one to nobody — the owner included.
+    const podTarget = this.toPod ? this.toPod(targetUrl) : targetUrl;
+    const url = await this.aclUrlFor(podTarget);
     if (!await this.aclWritable(url)) return null;
-    return this.put(url, this.aclDoc(targetUrl, publicModes, { ...opts, aclUrl: url }), 'text/turtle');
+    return this.put(url, this.aclDoc(podTarget, publicModes, { ...opts, aclUrl: url }), 'text/turtle');
   }
 
   // Child documents of an LDP container (URLs under it, excluding aux docs).