fedipod 0.19.0 → 1.2.0

package/README.md

@@ -2,141 +2,111 @@
 
 - access the Fediverse from a Solid pod
 
-`FediPod` is a merger of three federating protocols - feeds from Mastodon and other Fediverse servers and from Bluesky and other ATProto servers, with all user data stored on a Solid pod. There are four different kinds of FediPod accounts :
+FediPod gives you a Fediverse account whose data lives on a Solid pod. You
+follow people on Mastodon, Bluesky, and other Fediverse or ATProto servers in
+one timeline. Your posts, followers and settings stay on your pod.
+
+The easiest way to run FediPod is to use it in any browser at https://fedipod.net. Nothing to install. A wizard will walk you through getting a pod (you can also bring your own) and creating a Fediverse identity attached to the pod.  
+
+There are also a number of [other ways to run FediPod](#other-ways-to-run-fedipod) which offer a variety of scenarios.  If interested in the code, see also : [architecture overview](architecture.md) and [files overview](files-overview.md).
+
+## Requirements
+
+- A current browser, on a desktop or a phone.
+- 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/`,
+  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. Public
+  and unlisted posts work on any pod.
+
+## Getting an account
+
+1. Open https://fedipod.net and choose **create an account**.
+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.
+4. Enter your pod password once. It creates the account and locks your
+   signing key. The password is not stored.
+
+Your account then opens in the client. To use it from another browser, go to
+https://fedipod.net, enter your address, sign in at your pod, and unlock your
+key with your password once on that browser.
+
+## What you can do
+
+The client is [Phanpy](https://github.com/cheeaun/phanpy) (MIT, by Chee Aun),
+served by fedipod.net. Through it you follow and unfollow, post, reply,
+favourite, boost, attach media, edit and delete. Content warnings, polls with
+up to four options and one or several answers, all four visibility levels, a
+conversations view for direct messages, bookmarks, lists, keyword filters,
+pinned posts that other servers can see, blocking and muting, and the custom
+emojis other servers send.
+
+**Bluesky.** Connect a Bluesky account, or any other ATProto account, from the
+manage page. Your public posts are mirrored to it, Bluesky replies and
+activity flow into your timeline, and you can like, repost and reply to
+Bluesky posts. Direct messages to Bluesky are not supported. None of this
+needs Bridgy Fed.
+
+**Your other Fediverse accounts.** If you also hold an account on Mastodon,
+or on any other server speaking the Mastodon API such as GoToSocial, Pleroma,
+Akkoma, Pixelfed or Friendica, connect it from the manage page and read it
+here. Its home timeline and notifications join the feed you already read,
+interleaved by time, and a post both accounts see appears once. Favouriting,
+boosting and replying act as the account the post came through. The token it
+hands back stays in your browser unless you choose to keep it on your pod.
+
+**Moving in.** Mastodon-format exports of follows, blocks, mutes, lists and
+domain blocks import from the manage page. Your old account can be listed as
+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).
+
+**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
+there it takes over; the first drops back to reading.
+
+## What the browser version does not do
+
+- **Scheduled posts.** Nothing runs between now and the time you picked, so
+  the composer refuses one rather than dropping it later.
+- **Notifications while the client is closed.** There is no push service.
+  Open the tab and they are there.
+- **Live updates.** The client refreshes by polling.
+- **Hosting a group.** Joining one works.
+- **Other clients.** A phone app or desktop client has nothing on the network
+  to connect to.
+
+For these, see [Other ways to run FediPod](#other-ways-to-run-fedipod).
+
+## Your data and your keys
+
+Everything you publish and everything you read is stored on your pod. Your
+signing key is stored there too, encrypted under your password, so nobody who
+can read your pod, its host included, can post as you. fedipod.net holds no
+key: it verifies incoming mail, drops the junk, forwards the rest to your pod,
+and hands your browser the app. You can detach from it at any time and attach
+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
+  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
+  users from a pod.
+- [The gateway](gateway.md): running an always-on door of your own, on
+  Netlify or any small host.
+- [FediPod Server](packages/fedipod-server/README.md): a full ActivityPub
+  server as a Community Solid Server component, giving every pod on the server
+  the option of a Fediverse account.
 
-| Kind of Account | Description | User requirements | Host requirements |
-|---|---|---|---|
-| FediPod Solo | Browse & interact with the Fediverse and ATProto from a Solid pod | an always-on pod, a usually on local agent | — |
-| FediPod Group | Host a discussion group of Fediverse/ATProto users from a Solid pod | an always-on pod, a usually on local agent | — |
-| FediPod Gateway | Solo or Group with spam filtering & optional community identity | same + gateway pass-through account | any always-on host, Netlify will do |
-| FediPod Server | Full ActivityPub server as a CSS component | a pod on a CSS server implementing the FediPod component | a CSS server implementing the FediPod component |
-
-## Installation & Setup
-
-You may sign up for free for a solo, group, or gateway account at https://fedipod.net/ .  Wizards will walk you through install and setup. If you want to host a community, instructions are available for [Fediverse User Group](https://github.com/jeff-zucker/FediPod/blob/main/groups.md), the lightweight [FediPod Gateway](https://github.com/jeff-zucker/FediPod/blob/main/gateway.md) and for the full CSS component [FediPod Server](https://github.com/jeff-zucker/FediPod/blob/main/packages/fedipod-server/README.md). 
-
-### Installing
-
-```
-npm install -g fedipod
-```
-
-Needs Node 20 or newer.
-
-### Running the agent - 
-
-Run `fedipod start`. You may optionally add a port number (`fedipod start --port 8081`) to change your local agent's port (default is 8030).
-
-Now point your browser (any) at `https://localhost:8030` — or your own port if you set one — and there you go!
-
-### Running the agent as a service (recommended)
-
-If you don't want to run the agent each time, you can install it as a system service. This is recommended as leaving the agent off causes your mail to pile up on the pod host.  To create a system 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 your FediPod install
-
-You can manage your posts, see logs, park, move, transfer your account and perform other actions. See the [GUI admin](https://github.com/jeff-zucker/FediPod/blob/main/gui.md) and [CLI admin](https://github.com/jeff-zucker/FediPod/blob/main/cli.md) pages.
-
-You can also use the admin tools to create other actors, either groups or persons.  You may have as many as you want on the local machine, but each one needs a separate pod.
-
-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 FediPod.net Gateway account (reccommended)
-
-Most of what a Fediverse inbox receives is broadcast noise. A gateway 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 own
-pod. There is a free gateway at [fedipod.net](https://fedipod.net/). Attaching to it or detaching from it is a few wizard-guided clicks.
-
-Users are recommended to associate with a gateway as it reduces the mail load on your pod host.
-
-## Fediverse Clients
-
-The UI is the bundled [Phanpy](https://github.com/cheeaun/phanpy)
-client (MIT, by Chee Aun). It is served same-origin over the agent's Mastodon client-API facade, and logging in is one click — the instance is filled in for you. If you ever enter it by hand, use the address on the record's **local host** row.
-
-The agent federates for real: follow/unfollow, post, reply, favourite,
-boost, media, delete; incoming boosts from people you follow and a
-configurable public-hashtag feed (`POST /tagfeed`) fill the timeline.
-Also: editing posts, content warnings, voting in polls, all four visibility
-levels (followers-only and direct posts work only on a pod that enforces
-WAC access control — on one that doesn't, the composer refuses and says why),
-a conversations view for direct messages, bookmarks, favourites, lists,
-keyword filters, scheduled posts, pinned posts (visible from other servers),
-blocking and muting from the client, custom emojis, and web-push
-notifications that reach you while the client is closed.
-
-<!-- CLAUDE 2026-09-09 — the browser build does not have three of the things
-     this paragraph promises, and it says so honestly now rather than
-     advertising them. Written as a first draft in your voice; rework or move
-     it wherever you think it belongs. Delete these markers when done. -->
-Two of those are the installed agent only. **Scheduled posts** need something
-running between now and the time you picked, and in the browser build nothing
-is — so it refuses a scheduled post rather than accepting one it would silently
-drop. **Web-push notifications** likewise: the browser build has no push
-service behind it, so it does not advertise one and your client hides the
-toggle instead of showing one that does nothing. Both work on the installed
-agent. **Custom emojis** you receive are rendered everywhere; the picker for
-sending your own is not built yet, on either.
-<!-- /CLAUDE -->
-
-Polls: up to four options, one answer or several, running from five minutes to
-a month.
-
-### Other clients
-
-- **Web clients**: drop any static Mastodon client dist into `ui/<name>/`
-  and it is served at `/<name>/`, same-origin — see `ui/README.md`.
-- **Desktop clients** (Tuba, Whalebird, …): add `https://localhost:8030` (or other port for other agent) as a
-  custom instance.
-- **Streaming**: the agent serves the Mastodon streaming API
-  (`/api/v1/streaming`, WebSocket) so clients update live instead of polling.
-  <!-- CLAUDE 2026-09-09 — true of the installed agent; the browser build is a
-       service worker and cannot hold a socket. It advertises no streaming URL,
-       so clients fall back to polling on their own. Delete markers when done. -->
-  The browser build cannot: a service worker answers fetches, not sockets, so it
-  advertises no streaming URL and clients poll instead.
-  <!-- /CLAUDE -->
-
-## Bluesky and ATProto
-
-`FediPod` includes experimental support for ATProto. A Bluesky connection lets your `FediPod` agent drive an existing Bluesky (or other ATProto) account alongside your Fediverse identity. When you post a public post from `FediPod`, it will be cross-posted to Bluesky as a mirror (a toggle you can turn off). Private DMs from `FediPod` to Bluesky are not currently supported.  Bluesky replies and activity flow into your timeline so you see, for example, a combined Bluesky and Mastodon feed.  You can like, boost, and reply to Bluesky posts from within `FediPod`.  None of these features require `Bridgy Fed`, however, fully joining a `FediPod` group from a Bluesky client other than `FediPod` does require a bridge.
-
-## Your other Fediverse accounts
-
-If you also hold an account on Mastodon — or on any other server speaking the Mastodon API, such as GoToSocial, Pleroma, Akkoma, Pixelfed or Friendica — you can connect it and read it here. Its home timeline and notifications join the feed you already read, interleaved by time, and a post both accounts see appears once rather than twice. Favouriting, boosting and replying act as the account the post came through, on its own server. Connect one from the **Other identities** row of the admin page: you sign in at that server, and the token it hands back stays on this machine.
-
-
-## Architecture
-
-`Activitypods` requires a server which provides both an ActivityPub server and a Solid server and thus requires a specific server setup.  `FediPod Solo & FediPod Group`, can be installed on any subdomained https-served pod without any modification to the server.  It does this by splitting the ActivityPub server into two parts.  The pod part provides discovery (webfinger) and stores mostly public data while the local agent provides the ActivityPub actions and storage for most private data. The exception is private direct messages which are stored on the pod protected by ACL resources. The same protected area also holds followers-only posts, and the pending-follow
-and blocked collections. [`FediPod Gateway`](https://github.com/jeff-zucker/FediPod/blob/main/gateway.md) can be supported from any lightweight Internet-facing box including Netlify, it does not require a full server and can work with any FediPod-capable pod.  [`FediPod Server`](https://github.com/jeff-zucker/FediPod/blob/main/packages/fedipod-server/README.md) works as a CSS server component.  If the pod host installs it, anyone with a pod on that server can opt-in to using their pod as a FediPod account fed by the server itself.
-
-![Fedipod Gateway flow](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
-agent 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.
-
-Group actors follow FEP-1b12: a carried post names the group as its
-`audience`, the moderator roster is published as the actor's `attributedTo`,
-a followed group's announced `Delete` of a post it carried is honoured, and
-the group's own moderation is announced to the membership. The FEP-4ccd
-pending-follow collections and the FEP-c648 blocked collection are published
-as owner-only documents. See [Groups](https://github.com/jeff-zucker/FediPod/blob/main/groups.md).
 
 ## Acknowledgements
 

package/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+FediPod splits an ActivityPub server into two parts. The pod provides
+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)
+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.
+
+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
+lightweight host will do, Netlify included.
+
+[FediPod Server](packages/fedipod-server/README.md) puts the agent inside a
+Community Solid Server, so anyone with a pod on that server can opt in to a
+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)
+
+## 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,
+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.
+
+Group actors follow FEP-1b12: a carried post names the group as its
+`audience`, the moderator roster is published as the actor's `attributedTo`,
+a followed group's announced `Delete` of a post it carried is honoured, and
+the group's own moderation is announced to the membership. The FEP-4ccd
+pending-follow collections and the FEP-c648 blocked collection are published
+as owner-only documents. See [Groups](groups.md).