fedipod 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Zucker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# FediPod
+
+- 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 :
+
+| 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. Log in with one click, using `https://localhost:8030` (or your own port) as the instance.
+
+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.
+
+### 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.
+
+## 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.
+
+## 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
+
+This project is inspired by the fantastic [ActivityPods project](https://github.com/activitypods) and is meant to be a lightweight alternative rather than a replacement.  Thanks to [Sébastien](https://github.com/srosset81) and collaborators for all your work.  Thanks to [Damon](https://github.com/outlaw-dame), [Mikhal](https://github.com/mrkvon), [Alain](https://github.com/bourgeoa), [Sharon](https://github.com/SharonStrats), and [Vincent](https://github.com/Vinnl) for testing and encouragement.  Special thanks are due to [Joseph](https://github.com/jg10-mastodon-social) whose client-to-server authentication approach and the netlify/fronted-identity ideas I borrowed from [solid-activitypub-netlify](https://github.com/jg10-mastodon-social/solid-activitypub-netlify).
+
+## Transparency
+
+This package was created using a heavily hectored claude.
+
+## License
+
+(c) Jeff Zucker, 2026; may be freely used with an MIT license.

package/architecture.svg

@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1290 800" width="1290" height="800" font-family="system-ui, sans-serif">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#555"/>
+    </marker>
+  </defs>
+  <style>
+    .t   { font-size: 18px; font-weight: 600; fill: #1a1a19; }
+    .d   { font-size: 16px; fill: #333; }
+    .sub { font-size: 15px; fill: #666; }
+    .lbl { font-size: 15px; fill: #555; }
+    .cc  { font-size: 11px; font-weight: 400; font-style: italic; fill: #555; }
+    .arrow  { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); }
+    .arrow2 { stroke: #555; stroke-width: 2; fill: none; marker-end: url(#arr); marker-start: url(#arr); }
+  </style>
+
+  <rect width="1290" height="800" fill="#ffffff"/>
+
+  <!-- The open social web -->
+  <rect x="210" y="30" width="870" height="92" rx="12" fill="#eef1f8" stroke="#7a88b8"/>
+  <text class="t" x="645" y="64" text-anchor="middle">The open social web</text>
+  <text class="d" x="645" y="94" text-anchor="middle">other servers: deliver mail to us, read what we publish</text>
+
+  <!-- FediPod gateway -->
+  <rect x="210" y="180" width="870" height="134" rx="12" fill="#f2ece0" stroke="#b09a5e" stroke-dasharray="7 5"/>
+  <text class="t" x="645" y="214" text-anchor="middle">FediPod gateway</text>
+  <text class="d" x="645" y="240" text-anchor="middle">(optional — Netlify or any always on box)</text>
+  <text class="d" x="645" y="266" text-anchor="middle">checks each delivery's signature at the door;</text>
+  <text class="d" x="645" y="288" text-anchor="middle">drops spam and forgeries before the pod</text>
+
+  <!-- Pod -->
+  <rect x="210" y="375" width="360" height="197" rx="12" fill="#e7f2e7" stroke="#6a9a6a"/>
+  <text class="t" x="390" y="407" text-anchor="middle">Tamara's pod</text>
+  <text class="sub" x="390" y="431" text-anchor="middle">any https, sub-domained, always on pod</text>
+  <text class="d" x="390" y="459" text-anchor="middle">stores &amp; serves her public</text>
+  <text class="d" x="390" y="481" text-anchor="middle">record in S2S AS2 format —</text>
+  <text class="d" x="390" y="503" text-anchor="middle">actor, posts, collections;</text>
+  <text class="d" x="390" y="525" text-anchor="middle">her inbox buffers mail</text>
+  <text class="d" x="390" y="547" text-anchor="middle">even when her agent is off</text>
+
+  <!-- Agent -->
+  <rect x="720" y="375" width="360" height="197" rx="12" fill="#fdeeee" stroke="#b87a7a"/>
+  <text class="t" x="900" y="407" text-anchor="middle">Tamara's FediPod Agent</text>
+  <text class="sub" x="900" y="431" text-anchor="middle">on local device</text>
+  <text class="d" x="900" y="459" text-anchor="middle">does the thinking:</text>
+  <text class="d" x="900" y="481" text-anchor="middle">reads the buffered mail,</text>
+  <text class="d" x="900" y="503" text-anchor="middle">accepts follows, builds her</text>
+  <text class="d" x="900" y="525" text-anchor="middle">timeline, signs &amp; delivers</text>
+  <text class="d" x="900" y="547" text-anchor="middle">everything she says</text>
+
+  <!-- Client -->
+  <rect x="720" y="628" width="360" height="136" rx="12" fill="#f0e9f5" stroke="#9a7ab0"/>
+  <text class="t" x="900" y="662" text-anchor="middle">Browser or Native App</text>
+  <text class="sub" x="900" y="686" text-anchor="middle">(Phanpy, Whalebird, …)</text>
+  <text class="d" x="900" y="714" text-anchor="middle">where she reads and posts;</text>
+  <text class="d" x="900" y="736" text-anchor="middle">talks only to her agent</text>
+
+  <!-- open social web -> gateway -->
+  <path class="arrow" d="M 645 124 L 645 176"/>
+  <text class="lbl" x="657" y="155">deliveries in</text>
+
+  <!-- gateway -> pod -->
+  <path class="arrow" d="M 390 316 L 390 371"/>
+  <text class="lbl" x="402" y="336">verified mail</text>
+  <text class="lbl" x="402" y="357">+ receipt</text>
+
+  <!-- pod <-> agent -->
+  <path class="arrow2" d="M 572 473 L 718 473"/>
+  <text class="lbl" x="645" y="455" text-anchor="middle">drains mail,</text>
+  <text class="lbl" x="645" y="497" text-anchor="middle">writes the record</text>
+
+  <!-- agent <-> client -->
+  <path class="arrow2" d="M 900 574 L 900 626"/>
+  <text class="lbl" x="912" y="605">read / post</text>
+
+  <!-- pod -> open social web: read directly, never through the gateway -->
+  <path class="arrow" d="M 208 440 L 70 440 C 45 440, 38 400, 38 330 C 38 210, 88 100, 206 100"/>
+  <text class="lbl" x="188" y="412" text-anchor="end">reads her record</text>
+
+  <!-- agent -> open social web: delivers her own posts, never through the gateway -->
+  <path class="arrow" d="M 1082 440 L 1220 440 C 1245 440, 1252 400, 1252 330 C 1252 210, 1202 78, 1084 78"/>
+  <text class="lbl" x="1102" y="412">signed deliveries out</text>
+
+  <text class="d" x="45" y="716">The gateway stops unwanted mail from reaching the pod.</text>
+  <text class="d" x="45" y="740">The agent prevents mail buildup and does the mail processing.</text>
+  <text class="d" x="45" y="764">This leaves the pod with the minimal possible load.</text>
+
+  <text class="cc" x="1245" y="764" text-anchor="end">(cc) 4.0 By, Jeff Zucker, 2026</text>
+</svg>