fedipod 1.6.0 → 1.7.0

package/device-agent.md

@@ -0,0 +1,99 @@
+# 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
+what a browser tab cannot: it keeps running while no tab is open, so scheduled
+posts go out and push notifications reach you; it serves the Mastodon streaming
+API, so clients update live; any Mastodon client, phone app or desktop, can
+connect to it; and it can host a [group](groups.md).
+
+## Requirements
+
+- Node 20 or newer.
+- 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
+  service, or attach to a gateway, so it does not pile up there.
+
+## Installing
+
+```
+npm install -g fedipod
+```
+
+## Running
+
+Run `fedipod start`. Add a port to change the local agent's port, for example
+`fedipod start --port 8081`; the default is 8030. Then point any browser at
+`https://localhost:8030`, or the port you chose, and the setup pages take it
+from there.
+
+## Running as a service
+
+```
+fedipod install-service
+```
+
+It registers every identity on this machine, one service each, so all of your
+actors start at boot. An identity running in a terminal is stopped and taken
+over by its service. `fedipod uninstall-service` reverses it.
+
+## Managing
+
+Posts, logs, parking, moving, transferring and the rest are on the
+[admin interface](gui.md); starting, stopping and what a page cannot do are in
+[CLI admin](cli.md). The admin tools also create other actors, groups or
+persons. You may have as many as you want on one machine, each with a pod of
+its own.
+
+Every agent checks once a day whether a newer FediPod is published. When one
+exists, the record page offers **Update**, and `fedipod update` does the same
+from the terminal. `AP_UPDATE_CHECK=0` turns the check off.
+
+## A gateway account
+
+Most of what a Fediverse inbox receives is broadcast noise. A
+[gateway](gateway.md) is a shared, always-on door that verifies each delivery,
+drops the junk, and passes the rest to your pod, while your key and data stay
+on your pod. There is a free one at [fedipod.net](https://fedipod.net/).
+Attaching or detaching is a few wizard-guided clicks from your agent, and it
+takes the mail load off your pod's host.
+
+## Clients
+
+The bundled client is [Phanpy](https://github.com/cheeaun/phanpy) (MIT, by
+Chee Aun), served by the agent itself, and logging in is one click. If you
+ever enter the instance by hand, use the address on the record's **local
+host** row.
+
+- **Other web clients**: drop any static Mastodon client dist into
+  `ui/<name>/` and it is served at `/<name>/`; see `ui/README.md`.
+- **Desktop and phone clients** (Tuba, Whalebird, and the like): add
+  `https://localhost:8030`, or your agent's port, as a custom instance.
+- **Streaming**: the agent serves the Mastodon streaming API at
+  `/api/v1/streaming`, so clients update live instead of polling.
+- **Web push**: notifications reach you while the client is closed.
+- **Scheduled posts** go out at the time you picked.
+
+Polls, content warnings, editing, all four visibility levels, direct
+messages, bookmarks, favourites, lists, keyword filters, pinned posts,
+blocking and muting, and custom emojis work as in the browser version.
+
+## Bluesky, and your other Fediverse accounts
+
+A Bluesky connection lets the agent drive an existing Bluesky, or other
+ATProto, account alongside your Fediverse identity: public posts are
+cross-posted as a mirror, with a toggle to turn it off; Bluesky replies and
+activity flow into your timeline; you can like, boost and reply to Bluesky
+posts. Direct messages to Bluesky are not supported.
+
+An account on Mastodon or any server speaking the Mastodon API can be
+connected from the **Other identities** row of the admin page. Its home
+timeline and notifications join your feed, a post both accounts see appears
+once, and favouriting, boosting and replying act as the account the post came
+through. The token it hands back stays on this machine.

package/groups.md

@@ -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

@@ -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/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/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

package/lib/device/setup.mjs

@@ -19,6 +19,7 @@ import { hashPassword } from '../client/masto/index.mjs';
 import { webfingerHost, apUrls, DEFAULT_ROOT } from '../core/wire.mjs';
 import { rootOf, recordLastUsed, writeJsonAtomic } from './home.mjs';
 import { insecureUrlReason } from '../shared/safefetch.mjs';
+import { resourceExists } from '../pod/root.mjs';
 import { CURRENT_LAYOUT, isCurrent } from './migrate.mjs';
 
 const SOLID = $rdf.Namespace('http://www.w3.org/ns/solid/terms#');
@@ -222,6 +223,8 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
     gateway = null, shape = 'pod', gatewayOrigin = 'https://fedipod.net',
   } = answers;
   let { pod, root } = answers;
+  if (!root) root = 'fedipod/';   // new installs default to the fedipod/ container; a
+  // resuming run overwrites this with the credential's own root below.
   let accountWebId = null;   // what createAccountWithPod reported, when it ran
   // The private half always starts here, beside the credential and the keys —
   // not on the pod. Every activity you receive would otherwise cost the pod
@@ -263,6 +266,9 @@ export async function runSetup({ home, agent, answers, run, deps = {}, log = ()
       // reachable, and no silent 401 later on a pod whose profile is empty.
       const usable = await checkPod(pod);
       if (!usable.ok) throw new Error(usable.error);
+      if (await (deps.resourceExists || resourceExists)(deps.fetch || fetch, apUrls(pod, root || DEFAULT_ROOT).actor)) {
+        throw new Error('The pod already hosts a FediPod account. If you want a second account, put it on a different pod.');
+      }
       skip('account', 'using the pod you already have');
     }
 

package/lib/gateway/front-core.mjs

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

package/lib/pod/root.mjs

@@ -66,6 +66,17 @@ export async function podLayout(fetchImpl, providerOrigin, { timeoutMs = OWNER_L
   return /ns\/pim\/space#Storage|pim:Storage/u.test(body) ? 'path' : null;
 }
 
+// Whether a document is there — one unauthenticated GET, 200 or not. The caller
+// names the URL; asked before a second setup, so a pod that already serves an
+// actor at the app's container refuses another rather than growing a duplicate.
+export async function resourceExists(fetchImpl, url, { timeoutMs = OWNER_LOOKUP_MS } = {}) {
+  try {
+    const res = await fetchImpl(url,
+      { headers: { accept: 'application/activity+json' }, signal: AbortSignal.timeout(timeoutMs) });
+    return !!res && res.status === 200;
+  } catch { return false; }
+}
+
 export async function probeAnswers(podUrl, fetchImpl = fetch) {
   try {
     const res = await fetchImpl(podUrl, { method: 'HEAD' });

package/lib/server/embed.mjs

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

package/package.json

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

package/run-agent.mjs

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

package/vendor/gate.cjs

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

package/web/app/agent.mjs

@@ -189,7 +189,7 @@ export class BrowserAgent {
     // builds its own urls from `config.root` (publisher.mjs), and a config
     // without one falls to the Node default — so an account set up elsewhere
     // and signed into here would keep its state under `fedipod/` while every
-    // document it published landed under `activitypods-js/`. One root, decided
+    // document it published landed under a different root. One root, decided
     // once, carried by the config everything downstream reads.
     this.store.setConfig({ ...(this.store.getConfig() || {}), ...cfg, root });
     config = this.store.getConfig();