fedipod 0.19.0 → 1.2.0

package/browser.svg

@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 860 486" font-family="Helvetica, Arial, sans-serif">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#333"/>
+    </marker>
+  </defs>
+  <rect x="0" y="0" width="860" height="486" fill="#ffffff"/>
+
+  <!-- boxes (draw.io palette) -->
+  <g stroke-width="1.5">
+    <rect x="315" y="24"  width="230" height="72" rx="6" fill="#dae8fc" stroke="#6c8ebf"/>
+    <rect x="315" y="190" width="230" height="68" rx="6" fill="#e1d5e7" stroke="#9673a6"/>
+    <rect x="40"  y="372" width="210" height="70" rx="6" fill="#f8cecc" stroke="#b85450"/>
+    <rect x="580" y="360" width="250" height="88" rx="6" fill="#d5e8d4" stroke="#82b366"/>
+  </g>
+
+  <!-- box labels -->
+  <g fill="#111" text-anchor="middle">
+    <text x="430" y="56"  font-size="17" font-weight="bold">Open Social Web</text>
+    <text x="430" y="80"  font-size="13">Mastodon · Pixelfed · Bluesky …</text>
+
+    <text x="430" y="220" font-size="17" font-weight="bold">FediPod Gateway</text>
+    <text x="430" y="242" font-size="13">the mail door &amp; the relay</text>
+
+    <text x="145" y="391" font-size="17" font-weight="bold">Your Pod</text>
+    <text x="145" y="409" font-size="13">AP S2S formatted data</text>
+    <text x="145" y="426" font-size="13">in addition to other pod data</text>
+
+    <text x="705" y="392" font-size="17" font-weight="bold">Any Browser</text>
+    <text x="705" y="414" font-size="13">runs your FediPod Agent,</text>
+    <text x="705" y="431" font-size="13">a Mastodon API client</text>
+  </g>
+
+  <!-- arrows -->
+  <g stroke="#333" stroke-width="1.6" fill="none">
+    <!-- 1: Open Social Web <-> Gateway (AP S2S mail) -->
+    <line x1="430" y1="96" x2="430" y2="190" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+    <!-- 2: Your Pod -> Open Social Web (UNCHANGED, pod answers lookups) -->
+    <path d="M110,372 C46,300 46,150 322,92" marker-end="url(#arrow)"/>
+    <!-- 3: Gateway -> Your Pod (one way now) -->
+    <path d="M338,258 C300,300 250,330 205,372" marker-end="url(#arrow)"/>
+    <!-- 4: Gateway <-> Any Browser (agent loaded; signed posts sent) -->
+    <path d="M632,360 C560,320 522,300 472,258" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+    <!-- 5: Your Pod <-> Any Browser (Solid) -->
+    <line x1="250" y1="408" x2="580" y2="408" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+    <!-- 6: Any Browser <-> Open Social Web (ATProto client — Bluesky) -->
+    <path d="M760,360 C824,300 824,150 538,92" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+  </g>
+
+  <!-- arrow labels -->
+  <g fill="#333" font-size="13">
+    <text x="418" y="134" text-anchor="end">raw mail in</text>
+    <text x="418" y="150" text-anchor="end">relayed posts out</text>
+    <text x="442" y="142" text-anchor="start">AP S2S Protocol</text>
+
+    <text x="96"  y="250" text-anchor="start">Pod responds to requests for</text>
+    <text x="96"  y="266" text-anchor="start">webfinger, actor, public posts</text>
+
+    <text x="300" y="322" text-anchor="start">verified mail in</text>
+
+    <text x="588" y="302" text-anchor="middle">FediPod Agent loaded in browser;</text>
+    <text x="588" y="318" text-anchor="middle">signed posts sent to gateway</text>
+
+    <text x="430" y="400" text-anchor="middle" font-weight="bold" fill="#111">Solid Protocol</text>
+    <text x="430" y="428" text-anchor="middle">reads &amp; writes your pod</text>
+
+    <text x="780" y="238" text-anchor="end">ATProto</text>
+    <text x="780" y="254" text-anchor="end">client protocol</text>
+  </g>
+
+  <text x="830" y="474" text-anchor="end" font-size="11" fill="#888">© 2026 Jeff Zucker · CC BY-SA 4.0</text>
+</svg>

package/cli.md

@@ -70,9 +70,6 @@ fedipod revoke-credential --email EMAIL  # cut this machine off from the pod acc
 ```
 A new password takes effect when a running agent restarts.
 
-<!-- CLAUDE 2026-09-09 — `passwd` stopped being optional for one case, and a
-     user who hits it will want to know why here. First draft in your voice;
-     delete these markers when done. -->
 **A client hosted somewhere else now needs one.** A client running on its own
 site (Elk, Phanpy on someone's own domain) asks the agent to send the sign-in
 result back to that site. Without a password there is nothing to approve that
@@ -81,7 +78,6 @@ to have open could ask for the same thing and be given a key to your account.
 So: no password, no sending credentials off this machine. Clients that live on
 the agent itself (the bundled one, a dist in `ui/`, anything on
 `https://localhost:<port>`) are unaffected and need no password.
-<!-- /CLAUDE -->
 
 ## Bluesky
 

package/gateway.md

@@ -0,0 +1,160 @@
+# The gateway
+
+Most of what a Fediverse inbox receives is broadcast noise. A gateway is an
+always-on, internet-facing door that stands in front of your pod: it checks
+each delivery's signature where the headers still exist, drops forgeries and
+junk before they ever touch your pod, and passes the rest on with a receipt
+saying it checked.
+
+Your name, your signing key and your data stay on your own pod. The gateway is
+**keyless** — it never holds the key you sign with, so it cannot post as you,
+read your private things, or be you anywhere. The worst a broken one can do is
+push items into your inbox, and those still face your agent's own checks.
+
+A FediPod install works without any gateway at all. Deliveries go straight to
+your pod inbox, which holds them whether your agent is running or not.
+
+## Attaching your pod to one
+
+There is a gateway at [fedipod.net](https://fedipod.net/). Attaching happens
+from your own agent, which proves the pod with its own credential — no
+password is typed anywhere:
+
+1. Open your agent's admin page and, in the **Gateway** panel, give the
+   gateway's address and the name you want there. The panel checks the name
+   is free as you type.
+2. Choose a pod-based name (`@you@your.pod`) or a gateway-based name
+   (`@you@the-gateway`). The gateway account is created automatically either
+   way. A pod-based attach applies immediately; taking a gateway-based name
+   restarts the agent itself to publish under it.
+
+The same attach from the command line, against the running agent:
+
+```
+fedipod gateway --attach https://fedipod.net --name yourname
+```
+
+`--name` defaults to your handle; add `--fronted` for a gateway-based name.
+
+To undo it:
+
+```
+fedipod gateway --detach
+```
+
+That republishes your actor with your pod's own inbox. Nothing else moves.
+Detach talks to the running agent, so start it first. For a fronted identity,
+detaching also moves every published id back to the pod — a rename other
+servers see, not just a mail change.
+
+## Easing into it
+
+Attaching does not have to change how deliveries are treated on day one. The
+mode says how far you trust the door, and every step is reversible:
+
+- **off** — configured but not advertised; nothing changes on the wire. This
+  is where a by-hand configure starts, and the step back short of forgetting
+  the gateway entirely.
+- **shadow** — your actor advertises the gateway and the agent measures how
+  much real traffic verifies.
+- **trust** — verified follows are accepted without review.
+- **locked** — your inbox accepts writes only from the gateway.
+
+In every mode past **off**, the door itself is already filtering: blocked
+actors, content that does not concern you, and forged signatures are dropped
+at the door and never reach the pod. The mode says only how far the agent
+believes the door's receipts.
+
+The shadow numbers come from the agent:
+
+```
+curl -k https://localhost:8030/gateway
+```
+
+which reports the mode and the verified and unverified counts.
+
+Set it from the agent's own API:
+
+```
+curl -k -X POST https://localhost:8030/gateway -H 'content-type: application/json' \
+  -d '{"action":"mode","mode":"shadow"}'
+```
+
+8030 is the default identity's port; `fedipod status`
+prints the right one for each identity.
+
+## The receipt secret
+
+The gateway stamps each verification receipt with a secret shared between it
+and your agent, and your agent believes a receipt only when the stamp checks
+out. That is what stops somebody dropping a forged "verified" receipt beside a
+forged delivery.
+
+You never fetch this secret from anywhere. When you run your own gateway,
+your agent mints it and shows it to you once; you carry it to the gateway
+yourself. When you attach to a multi-user gateway, the direction is reversed:
+the gateway mints the secret and answers the attach with it, and your agent
+records it.
+
+## What the gateway can see
+
+It reads only public data to decide what concerns you: your published
+followers and following, and a small public policy document your agent writes
+with a mirror of your blocklist. Nothing private leaves your pod. Publishing
+that mirror does make your blocklist public, which is part of the bargain of
+running behind a door.
+
+## Running a gateway
+
+Any always-on box will do — a VPS, a home server behind a tunnel, a serverless
+host. The logic is plain Node in `lib/gateway/gateway-core.mjs`, and a host needs only
+a thin adapter that calls `handleDelivery`.
+
+Two ways are ready to use:
+
+- **On Netlify**, with the adapter in `netlify/functions/inbox.mjs`. See
+  [netlify/README.md](netlify/README.md) for the deployment specifics.
+- **On any box of your own**, with your own adapter around the same core.
+- **Inside a Community Solid Server**, as the same door run in-process by the
+  CSS component — see [packages/fedipod-server](packages/fedipod-server/README.md).
+
+### Offering accounts to other people
+
+A gateway can also be a front for many people, so a host can offer
+`@name@their-host` addresses. Each user keeps their own pod, their own agent
+and their own signing key; the front answers WebFinger for all of them, serves
+each public face by rewriting that user's pod ids onto the shared domain, and
+routes every verified delivery into the right pod.
+
+A fronted identity is the gateway-based name choice in the admin page's
+Gateway panel, or:
+
+```
+fedipod gateway --attach <front-origin> --name <name> --fronted
+```
+
+Choose at attach time: changing an existing identity's front later renames
+every published id, and the attach refuses it.
+
+**A front is only a doorway.** It never hosts pods and never dictates where
+they live. A host who also wants to offer pods to people who have none runs a
+pod server separately, with the duties that carries — and users may always
+bring a pod of their own instead.
+
+## Setting one up by hand
+
+If you are not using a signup page:
+
+1. Deploy the door to your box.
+2. Give it Append on your inbox, using a dedicated low-privilege pod account —
+   never your owner credential. FediPod's default inbox is public-Append, so
+   this is optional: with no credential the door writes with a plain PUT.
+3. Point your agent at it, which mints the shared secret and returns it once:
+
+   ```
+   curl -k -X POST https://localhost:8030/gateway -H 'content-type: application/json' \
+     -d '{"action":"configure","url":"<door-inbox-url>","webId":"<door-webid>"}'
+   ```
+
+   Copy that secret into the door's environment.
+4. Walk the modes above, starting at shadow.

package/groups.md

@@ -14,16 +14,12 @@ 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.
 
-<!-- CLAUDE 2026-09-09 — nothing anywhere said this, and a browser user who
-     went looking for the group option would just not have found it. First
-     draft in your voice; move or reword as you like. Delete markers when done. -->
 **Running a group needs the installed agent.** 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
 anywhere else: joining is following, and that works everywhere. It is hosting
 one that needs an install.
-<!-- /CLAUDE -->
 
 Being in a group also connects you to the people in it: posts from fellow
 members reach your timeline even when you do not follow them individually,
@@ -73,8 +69,6 @@ boosting the author.
 
 A group can be handed on rather than abandoned using the `Transfer this account away` button. This tells every follower to migrate, so the membership survives a change of host.
 
-
-
 ## Bluesky members
 
 A group with a connected Bluesky account is joinable from Bluesky: following

package/gui.md

@@ -1,5 +1,10 @@
 # The Admin interface
 
+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
+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.
 Picking an actor marked "(stopped)" starts its agent, then opens its page.
 
@@ -92,14 +97,9 @@ is marked **sign in again** rather than quietly dropped.
 
 New followers appear under **Follow requests** with **Accept** and **Refuse**
 beside them; nothing is accepted without you.
-<!-- CLAUDE 2026-09-09 — these were visible on this page and NOWHERE else
-     until today: the client API stubbed the list empty and offered no way to
-     answer one, so no Mastodon client could show them. Delete markers when
-     read. -->
 They show in any Mastodon client as well, now that the client API serves the
-queue and takes both answers — before this they were visible on this page
-alone.
-<!-- /CLAUDE --> Groups are different — joining
+queue and takes both answers.
+Groups are different — joining
 follows the group's own moderation settings; see [Groups](groups.md).
 
 **Accept all** answers the whole queue at once, and the identity pane's
@@ -131,12 +131,8 @@ account*); your followers arrive by themselves. Removing an alias asks
 twice — servers still processing the move check it while they retry. The CSV
 files from the old server's export are imported with the CLI; see
 [CLI admin](cli.md).
-<!-- CLAUDE 2026-09-09 — the browser build runs the same importer now, so
-     "with the CLI" is no longer the whole story. Reword as you like; delete
-     these markers when done. -->
 The in-browser build runs the same importer, so a CSV can be handed to it
 there too.
-<!-- /CLAUDE -->
 
 ## Protecting & recovering your data
 

package/installed-agent.md

@@ -0,0 +1,97 @@
+# The installed agent
+
+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 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.
+- 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/lib/{c2s.mjs → client/c2s.mjs}

@@ -15,8 +15,9 @@
 // read their own inbox" is served from there, by this agent, to the owner
 // alone.
 
-import * as social from './social.mjs';
-import * as wire from './wire.mjs';
+import * as social from '../core/social.mjs';
+import * as wire from '../core/wire.mjs';
+import { readLenient } from '../core/as2.mjs';
 
 const MAX_BODY = 512 * 1024;          // same ceiling the inbox drain enforces
 
@@ -190,9 +191,13 @@ export class C2S {
       if (!took) return this.send(res, 503, { error: 'another agent is active for this pod — takeover failed, try again' });
     }
 
+    // Read as JSON-LD, so a client may send its activity with whatever context
+    // it likes and still be understood. One we cannot read that way is read as
+    // plain JSON rather than refused, which is what a client sending ordinary
+    // ActivityStreams has always got.
     let activity;
     try {
-      activity = JSON.parse(await readBody(req));
+      activity = (await readLenient(await readBody(req))).doc;
     } catch (e) {
       return this.send(res, 400, { error: `unreadable body: ${e.message}` });
     }

package/lib/{localapi.mjs → client/localapi.mjs}

@@ -12,8 +12,8 @@
 import https from 'node:https';
 import fs from 'node:fs';
 import path from 'node:path';
-import { rootOf, apRoot } from './home.mjs';
-import { certPaths } from './certs.mjs';
+import { rootOf, apRoot } from '../device/home.mjs';
+import { certPaths } from '../device/certs.mjs';
 
 /**
  * The authorities worth offering for a loopback call: this install's, and the