fedipod 0.8.0

package/cli.md

@@ -0,0 +1,243 @@
+# CLI admin
+
+Everything here runs from the install folder. Most day-to-day management is
+in the [GUI admin](gui.md); the terminal is for starting and stopping, and
+for the few things a page cannot do. Replace NAME, DIR and EMAIL with your
+own values.
+
+## Starting and stopping
+
+```
+fedipod start              # start your default identity (the one you last used)
+fedipod start --port 8081  # same, on a port of your choice — it is remembered
+fedipod up --profile NAME  # start a specific identity
+fedipod stop               # stop it, saving state first
+fedipod status             # is it running, and as whom
+fedipod profiles           # every identity on this machine, running or not
+```
+
+Installing the boot services (see the README) makes starting by hand unnecessary.
+
+## Creating an identity
+
+```
+fedipod setup        # opens the browser setup
+fedipod setup --cli  # the same questions in the terminal
+```
+`--group` makes a group actor instead of a person, `--new-account` creates the
+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.
+
+## Which identity a command acts on
+
+`--profile NAME` works on every command, not just `up`; `AP_PROFILE` is the
+same thing as an environment variable, and `AP_HOME` points at an install
+folder directly. Without either, commands act on the default identity — with
+several identities, say which you mean. `profiles` does not list identities
+under a custom `AP_HOME`.
+
+Commands that manage a live identity — `alias`, `admit`, `import`, `archive`,
+`bsky`, `describe`, `status`, `rebuild`, `gateway --detach` and the group
+commands — talk to the running agent and say so when it is not there. `keys`,
+`state`, `home` and attaching a gateway want the agent stopped.
+
+## Recovery
+
+```
+fedipod rotate-key --force
+```
+When an identity's `keys.json` is lost or damaged the agent refuses to start;
+this mints a replacement and tells other servers.
+It asks before rotating; `--yes` answers for you.
+ Any other device still
+using the old key stops working as this identity.
+
+```
+fedipod rebuild --from-notes
+```
+A deeper version of the GUI's **Recover posts**: reads every note the pod
+still holds, and can bring back a post whose deletion half-failed. Adds only;
+nothing local is overwritten.  Agent must be running.
+
+## Security
+
+```
+fedipod passwd                           # require a password when a client logs in
+fedipod tokens                           # list client logins; --revoke <prefix> or --revoke-all
+fedipod revoke-credential --email EMAIL  # cut this machine off from the pod account
+```
+A new password takes effect when a running agent restarts.
+
+## Bluesky
+
+```
+fedipod bsky connect HANDLE APP-PASSWORD  # drive an existing Bluesky account
+fedipod bsky status                       # which account, and any last error
+fedipod bsky crosspost off                # your public posts stay off Bluesky (on: they mirror)
+fedipod bsky disconnect                   # forget the session and the stored credential
+```
+HANDLE and APP-PASSWORD come from the Bluesky account: make the app password
+under its Settings → Privacy and security → App Passwords. Add
+`--service URL` when the account lives on a PDS other than bsky.social.
+Disconnecting does not remove anything already posted to Bluesky.
+
+## Inbox history
+
+```
+fedipod archive off  # stop keeping drained mail (on: keep it, the default)
+```
+The archive keeps each incoming activity's original bytes in the private
+half's `inbox-archive/` after it is verified and applied (JSON-LD, so the
+receipts read as RDF too) — receipts you can re-verify, and the inbound half
+of an account move. It lives only in the private half; the pod cannot
+rebuild it.
+
+## Moving the install
+
+```
+fedipod home           # where your identities live
+fedipod home --to DIR  # move them all somewhere else
+```
+Stop the agents first. If you use the boot services, run
+`fedipod install-service` again afterwards.
+
+## Going quiet, and leaving
+
+```
+fedipod park                            # stop the mail and unfollow, keeping the handle
+fedipod revive                          # come back: re-follow everyone from the parking snapshot
+fedipod retire                          # permanent: followers' servers are told to drop the account
+fedipod retire --move-to @you@new.host  # tell followers to migrate, then stand down
+fedipod retire --keep-handle            # stand down, but the handle keeps resolving
+```
+Each asks before acting; `--yes` answers for you. These are the terminal form
+of the record page's status control and lifecycle buttons.
+
+## Where the private half lives
+
+```
+fedipod state           # show where the private half and public face live
+fedipod state --to pod  # move the private half into pod state (multi-device)
+fedipod state --to DIR  # or into another directory
+fedipod upgrade         # which identities are on an older layout
+```
+`upgrade` reports and names the `state` commands to run; it moves nothing
+itself. Stop the agent before moving state.
+
+## Taking your data out
+
+```
+fedipod export --format as-collections --to DIR
+```
+Writes the outbox, followers and the archived inbox as paged AS2 collections;
+`--to` also takes a pod container URL.
+
+## Running a group
+
+```
+fedipod members             # who is in
+fedipod requests            # who is waiting to join
+fedipod admit ACTOR-URL     # let one in (or: admit --all)
+fedipod refuse ACTOR-URL
+fedipod joins open|approve  # whether joining waits for review
+fedipod mute ACTOR-URL      # stop carrying them; unmute undoes it
+fedipod eject ACTOR-URL
+fedipod review on|off       # whether posts wait for approval
+fedipod pending             # posts waiting for approval
+fedipod approve NOTE-URL
+fedipod decline NOTE-URL
+fedipod announced           # what the group has carried
+fedipod retract NOTE-URL    # un-carry one
+```
+The agent must be running. What these mean: [Groups](groups.md).
+
+Also: `describe --summary "…" --icon URL` sets the bio and avatar and
+republishes the actor; `install-service` / `uninstall-service` are the
+service installers the README names, as fedipod subcommands; and
+`home --restructure` is the one-time move of an old top-level identity into
+`profiles/` — commands that need it say so.
+
+## Moving here from another server
+
+```
+fedipod alias --add @you@old.server  # list the old account on your actor
+fedipod alias                        # show the aliases
+fedipod alias --remove URL --yes     # take one off
+```
+The alias is what the old account's server checks before it will send the
+move. Add it, then trigger the move on the old server. Leave the alias in
+place until the migration has settled — servers keep checking it while they
+retry.
+
+```
+fedipod admit --all  # accept every waiting follow request
+```
+Turning on automatic acceptance first (the admin page's **new followers**
+control) means the incoming wave never queues at all.
+
+```
+fedipod import following_accounts.csv blocked_accounts.csv
+```
+Takes the CSV files from the old server's export — follows, blocks, mutes,
+lists and domain blocks; the file names say which is which, or pass
+`--kind follow|block|mute|list|domain` with a single file. Rows are applied
+slowly on purpose and the command shows progress; `import` with no files
+shows where a run stands, and `--clear` drops the finished record. Bookmarks
+are not imported.
+
+## The gateway
+
+```
+fedipod gateway <door-inbox-url> --secret <hmac> --inbox-only
+fedipod gateway --detach
+```
+Attaching points your actor's advertised inbox at a gateway's door, so
+deliveries are verified and de-junked before they reach your pod; your name,
+key and data stay on your pod. The URL and secret come from the gateway's
+signup page. Attaching takes effect when the agent next starts; detaching
+needs it running, and republishes your actor with the pod's own inbox.
+(`front` still works as an alias, and the `<…/ap/actor>` form without
+`--inbox-only` takes a fronted identity instead.)
+
+What a gateway is, easing into one, and running your own: [gateway.md](gateway.md).
+
+## Keys
+
+```
+fedipod keys
+fedipod keys --to pod
+fedipod keys --to local
+```
+Where the signing key lives. On the pod, every device that reaches your
+state store can sign as the actor — that is what multi-device needs; the
+pod's operator can also read a pod-held key. The pod copy is shared between
+devices only when the state store is on the pod too — `state --to pod`
+first. Local keeps it on this machine
+alone; the next start adopts the pod copy and removes it from the pod. Stop
+the agent before moving keys.
+
+## update
+
+```
+fedipod update
+```
+Pulls the latest published FediPod into this install and restarts the
+agents — those installed as services restart themselves; any started by hand
+need their own restart. The record page offers the same thing when a newer version exists —
+every agent checks once a day. A checkout with local changes is refused
+rather than overwritten. `AP_UPDATE_CHECK=0` turns the daily check off.
+
+## https
+
+```
+fedipod https
+fedipod https --trust
+```
+Every agent's address is https, on the port you gave it.
+The first agent start makes the certificate and signs it with a local
+certificate authority that can only ever vouch for localhost names. On Linux
+the authority lands in Chrome and Chromium's store by itself; Firefox, macOS
+and Windows run `https --trust` once, which prints any remaining step.
+`https` shows what is minted and when it expires.
+

package/groups.md

@@ -0,0 +1,85 @@
+# Groups
+
+A group is an actor other people follow, rather than one that follows people.
+When members post to the group, it re-announces to everyone following it, so members see each
+other without having to follow each other. If they do already follow each other , the posts are not duplicated. Joining is following, leaving is
+unfollowing, and remote Mastodon users can join exactly as pod owners do — they
+need no pod of their own.
+
+A group needs a pod of its own, and runs like any other identity on its own
+port — the same status, parking and lifecycle controls on its record page.
+
+A group is made the same way as any other account: choose "add a new account"
+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.
+
+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,
+so a reply in the room is something you see rather than something filed
+among strangers' mail. Who counts is the group's own membership, so its
+moderation settings decide who reaches you.
+
+As with persons, a group display name and bio should be handled on the client.
+
+## Managing a group
+
+The group passes along posts from its own members only. This stops spam from outside the group.
+A carried post must also be public: the group never widens an audience, so a
+followers-only post or a DM to the group is not carried.
+Internal moderation is also possible :
+
+* owner may choose to moderate join requests - no one becomes a member without review
+* owner may choose to moderate posts - nothing gets posted without review
+* owner may mute users (refuse to rebroadcast their posts)
+
+The controls live on the group's admin page: members, join requests, held
+posts and carried posts. Ejecting also mutes: a re-follow is accepted again,
+but nothing of theirs is carried until unmuted. Refusing a join request is not
+sticky — they may ask again.
+
+A carried post names the group as its
+`audience`, and when you ban or eject someone (or change the moderator roster),
+the group announces that moderation to its members so their servers can mirror
+it. A moderator list can be set on the group's config; those actors' moderation
+requests arriving over federation are held in a review queue rather than acted
+on automatically, since a delivery alone does not prove who sent it. That
+queue is its own list, separate from post review, and appears on the group's
+admin page as **Moderation requests** when something is waiting: carry it out,
+or turn it down.
+A followed group's own announced deletion of a post it carried to you is honoured.
+
+## 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
+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
+boosting the author.
+
+## Transferring group ownership
+
+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
+the group's Bluesky account is a join, and mentioning its handle submits a
+post. Both pass through the same moderation settings as fediverse members —
+join review, post review, and muting all apply, and an approved post is
+carried to the group's Bluesky followers as a repost.
+A follow from an already-bridged Bluesky account is ignored on the Bluesky
+side — its join arrives over ActivityPub from the bridge instead. Carrying
+fediverse posts to the group's Bluesky followers happens only while
+crossposting is on.
+
+A Bluesky member's posts reach the fediverse side only if their account is
+bridged (it follows @ap.brid.gy on Bluesky). Unbridged members are welcomed
+with a single post mentioning them explaining that, and everything else about their
+membership still works, and bridging later upgrades them in place: the
+bridge's follow supersedes their Bluesky-only membership rather than adding a
+second one. Ejecting a Bluesky member blocks their account, since their server cannot be told any
+other way.

package/gui.md

@@ -0,0 +1,99 @@
+# The Admin interface
+
+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.
+
+`Update`, shown on the software row when a newer FediPod exists, pulls the latest version and restarts every agent on the machine — agents installed as services; any started by hand need their own restart. The same row flags an older data layout after an update; the `fedipod upgrade` terminal command lists those moves and the commands that make them.
+
+* **Parking** (the status control) stops the mail and unfollows people you follow, but keeps your handle
+  alive. Setting it back to active re-follows everyone — as requests, so a
+  few may not come back.  If your local machine is going to be off for more than a couple of days, you should park the account because, if you don't, mail will accumulate on the pod possibly causing load issues.
+* **Transfer this account away** hands your followers to the account you name; your
+  old handle keeps working as a redirect, and the identity is parked
+  afterwards.
+* **Retire identity** is permanent — every follower's server is told to drop
+  the account, and the identity does not come back.
+* In the **Upkeep** group: **Drain the inbox** fetches and handles everything
+  waiting now, and **Show dead letters** lists deliveries that failed for
+  good and will not be retried.
+* **Rotate signing key** — any other device still using the old key can no
+  longer act as this identity.
+* **Recover posts** re-reads your own posts from the pod after a restore. It
+  only ever adds; nothing local is overwritten.
+* Discarding a backlog drops old content only — its follows, unfollows and
+  deletions are still applied, whatever their size.
+
+The handle, the pod and person-vs-group are permanent. The display name, bio
+and pictures are edited in the client, not here.
+
+Most of these open a small window that floats over the page. You can drag it by
+its title bar, resize it from its corner, and close it with its ✕ or by pressing
+Escape. Parking is a control on the status row, and discarding a backlog is its
+own section further down the page.
+
+**+ add a new account…** at the bottom of the actors dropdown creates another
+person or group on this machine: it needs a pod of its own (create one there,
+or point it at one you have), and the new identity runs as its own agent on
+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
+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
+any fediverse app.
+
+## Bluesky
+
+Connecting a Bluesky account makes this identity also post as that account:
+your **public** posts mirror to Bluesky (never unlisted, followers-only or direct
+ones), deleting a post deletes its Bluesky copy, and the account's timeline
+and notifications appear in your home feed. Replying to, favouriting and
+boosting a Bluesky post act as the connected account. A reply lives on
+Bluesky only — it is always public and fits Bluesky's 300-character limit —
+because your fediverse followers cannot see the post it answers. The
+**crosspost** control stops the
+mirroring without disconnecting. Disconnecting forgets the login but removes
+nothing already posted. For a group, the connected account is the group's
+presence on Bluesky — joining and posting through it follow the group's own
+moderation settings; see [Groups](groups.md).
+
+## Handling follow requests
+
+New followers appear under **Follow requests** with **Accept** and **Refuse**
+beside them; nothing is accepted without you. 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
+**new followers** control switches between waiting for your approval and
+accepting automatically.
+
+## Moving here from another server
+
+Open **Transfer an account here** on the action rail and add your old account
+as an alias, set
+**new followers** to *accepted automatically*, then trigger the move on the
+old server; 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).
+
+## Protecting & recovering your data
+
+Your posts, timeline, contacts, blocklist and notifications are kept locally,
+in `~/.fedipod`. This is the only copy, which means you should back
+it up regularly. It contains credentials, so back it up securely.
+Each identity's copy is under `~/.fedipod/profiles/<name>/`, and
+`fedipod state --to` can move it elsewhere — if you have moved it, back up
+where it lives now.
+
+With a backup, restoring is copying the folder back and starting the agent —
+everything returns, timeline included. Without one, nothing is fatal but some
+things are gone: run setup again with your pod account (at `/admin/setup/` on the agent), rotate the signing
+key, and your followers return by themselves the next time you post, while
+**Recover posts** reads your own posts back from the pod. What nothing can
+bring back is the timeline you received, your notifications, your blocklist,
+and your client logins.
+

package/lib/account.mjs

@@ -0,0 +1,87 @@
+// account.mjs — create a brand-new account + pod on a CSS server (v7 account
+// API), the `setup --new-account` path. Public-server sibling of
+// data-kitchen's seed-account.cjs, but simpler: the pod.create control makes
+// the pod AND its WebID in one step — no ownership challenge, because the
+// server authors the WebID itself.
+//
+// Flow: POST .account/account/ (or login when the email already exists) →
+// password.create → account.pod {name} → { pod, webId }.
+
+async function jfetch(url, { method = 'GET', body, cookie } = {}) {
+  const headers = { accept: 'application/json' };
+  if (body !== undefined) headers['content-type'] = 'application/json';
+  if (cookie) headers.cookie = cookie;
+  const res = await fetch(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+  let json = null;
+  try { json = await res.json(); } catch { /* non-JSON */ }
+  return { status: res.status, json };
+}
+
+export async function createAccountWithPod({ issuer, email, password, podName }) {
+  const origin = issuer.replace(/\/+$/, '');
+  const accountRoot = `${origin}/.account/`;
+
+  // Authenticate: log in when the email is already registered (idempotent
+  // re-runs), otherwise create the account and set its password.
+  let cookie;
+  const login = await jfetch(`${accountRoot}login/password/`, { method: 'POST', body: { email, password } });
+  if (login.status < 400 && login.json?.authorization) {
+    cookie = `css-account=${login.json.authorization}`;
+  } else {
+    const create = await jfetch(`${accountRoot}account/`, { method: 'POST' });
+    if (!create.json?.authorization) {
+      throw new Error(`account create failed (HTTP ${create.status}): ${create.json?.message || 'is this a CSS server with signup enabled?'}`);
+    }
+    cookie = `css-account=${create.json.authorization}`;
+    const pwCreate = (await jfetch(accountRoot, { cookie })).json?.controls?.password?.create;
+    if (!pwCreate) throw new Error('password.create control missing — not a CSS v7 account API');
+    const pw = await jfetch(pwCreate, { method: 'POST', cookie, body: { email, password } });
+    if (pw.status >= 400) throw new Error(`password create failed (HTTP ${pw.status}): ${pw.json?.message || ''}`);
+  }
+
+  // Create the pod (server picks root-path or subdomain layout). When the
+  // name is already taken BY THIS ACCOUNT — a setup re-run, or a pod made
+  // earlier by hand — reuse it; taken by someone else stays a hard error.
+  const controls = (await jfetch(accountRoot, { cookie })).json?.controls;
+  const podCreate = controls?.account?.pod;
+  if (!podCreate) throw new Error('pod create control missing — not a CSS v7 account API');
+  // Scheme-agnostic on purpose: matching `https://name.` missed every pod on an
+  // http server, so a re-run after a crashed setup always tried to create again
+  // and died on "already registered to this account".
+  const findOwn = async () => {
+    const pods = (await jfetch(podCreate, { cookie })).json?.pods || {};
+    return Object.entries(pods).find(([url]) => {
+      try {
+        const u = new URL(url);
+        return u.hostname === podName || u.hostname.startsWith(`${podName}.`)
+          || u.pathname.split('/').filter(Boolean).includes(podName);
+      } catch { return false; }
+    }) || null;
+  };
+  // One pod per account, refused BEFORE anything is created. A second pod gives
+  // the account a second WebID, and a credential can only be bound to one of
+  // them — so the second actor authenticates and then 403s every write to its
+  // own pod. Reusing a pod of the same name is still fine: that is a re-run of
+  // a setup, not a second identity.
+  const owned = Object.keys((await jfetch(podCreate, { cookie })).json?.pods || {});
+  if (owned.length && !await findOwn()) {
+    throw new Error(`${email} already has a pod on ${new URL(origin).host}: ${owned[0]} — `
+      + 'one account, one pod. A second actor needs its own account and email. '
+      + 'Nothing was created.');
+  }
+  const made = await jfetch(podCreate, { method: 'POST', cookie, body: { name: podName } });
+  let pod = made.json?.pod || made.json?.podBaseUrl || null;
+  let webId = made.json?.webId || null;
+  if (made.status >= 400 || !pod) {
+    const own = await findOwn();
+    if (own) {
+      pod = own[0];
+      webId = webId || own[1]?.webId || null;
+    } else if (made.status >= 400) {
+      throw new Error(`pod create failed (HTTP ${made.status}): ${made.json?.message || `is the name "${podName}" taken by another account?`}`);
+    }
+  }
+  if (!pod) throw new Error('pod created but its URL was not reported — check the account dashboard');
+  pod = pod.endsWith('/') ? pod : pod + '/';
+  return { pod, webId: webId || new URL('profile/card#me', pod).href };
+}