README is a full major version stale - document v6.2 and v7 (federation) #104

New issue

Closed

opened 2026-07-15 19:51:34 +00:00 by claude-bot · 1 comment

claude-bot commented

2026-07-15 19:51:34 +00:00

Contributor

Severity: Medium · Confidence: High · Effort: M · Category: tracker/docs

Evidence

README.md:681 - "v1.0.0 through v6.0.0 are all complete" vs package.json version 7.0.0 and CHANGELOG ## [7.0.0].
README describes ActivityPub publishing but not v7 inbound federation: remote-editor invites, signed write path, conflict-resolution queue, defederation kill-switch, remote project read/edit.
Also omits v6.2 Categories/Insights and several v6.0 features (password projects, templates, quotas, SMTP).

Problem
The README's version claim and feature list trail the codebase by a full major version. The biggest and highest-risk subsystem (cross-instance collaborative editing) is undocumented for any new operator/contributor.

Impact
A fresh operator/contributor gets a materially wrong picture of what the app does and its trust boundaries - which matters most for the federation surface that carries the security findings.

Fix
Update README: bump the version narrative; add v6.2 (Categories, Insights) and v7 (federation) sections; document the federation trust model and its admin prerequisites (an admin must federate an instance before it can be invited/written to).

Acceptance criteria

README states v7.0.0 and documents v7 federation features and their prerequisites.

Filed from the 2026-07-15 codebase audit. Full report: docs/.internal/report-2026-07-15.md (gitignored).

**Severity:** Medium · **Confidence:** High · **Effort:** M · Category: tracker/docs **Evidence** - `README.md:681` - "v1.0.0 through v6.0.0 are all complete" vs `package.json` version `7.0.0` and CHANGELOG `## [7.0.0]`. - README describes ActivityPub publishing but not v7 inbound federation: remote-editor invites, signed write path, conflict-resolution queue, defederation kill-switch, remote project read/edit. - Also omits v6.2 Categories/Insights and several v6.0 features (password projects, templates, quotas, SMTP). **Problem** The README's version claim and feature list trail the codebase by a full major version. The biggest and highest-risk subsystem (cross-instance collaborative editing) is undocumented for any new operator/contributor. **Impact** A fresh operator/contributor gets a materially wrong picture of what the app does and its trust boundaries - which matters most for the federation surface that carries the security findings. **Fix** Update README: bump the version narrative; add v6.2 (Categories, Insights) and v7 (federation) sections; document the federation trust model and its admin prerequisites (an admin must federate an instance before it can be invited/written to). **Acceptance criteria** - [ ] README states v7.0.0 and documents v7 federation features and their prerequisites. --- _Filed from the 2026-07-15 codebase audit. Full report: `docs/.internal/report-2026-07-15.md` (gitignored)._

claude-bot added this to the v7.2.0 - Reliability, data integrity & docs milestone

2026-07-15 19:51:34 +00:00

claude-bot added the

enhancement

label

2026-07-15 19:51:34 +00:00

rbrooks referenced this issue from a commit

2026-07-17 03:05:42 +00:00

docs(v7.2): document v6.2 and v7 federation in the README (#104)

claude-bot commented

2026-07-17 03:09:23 +00:00

Author

Contributor

Fixed in c09cc84 (v7.2.0). README 681 → 764 lines.

New "Federation (v7)" section — the point of the issue. Written for an operator who has never seen the codebase, and deliberately leads with the trust boundary:

Admin prerequisite, stated prominently: an admin must add and enable the remote instance on the Federation page first. An actor whose instance isn't federated+enabled can't be invited and can't write — there is no open inbox.
The five-layer trust chain on an inbound write, in order: not defederated (checked before any signature work) → signature covers (request-target)/date/digest with the digest verified against the raw body and a 5-minute freshness window → verifies against the actor's cached key → signer bound to activity.actor (401 on mismatch, every activity type) → must be an accepted remote editor on the target project (403).
Inviting a remote editor (owner-only, auto-accepted, signed Invite → their "Shared with me"), conflict resolution + the owner review queue, GET /ap/projects/:id, the SSRF guard (private-range denylist, per-hop redirect re-validation, admin-federated bypass so homelab peers still work), and the defederation kill-switch.

Also added: "Categories" (v6.2) under a renamed Tags & Categories section — drawing the distinction that actually confuses people (categories are project-scoped and curated; tags are user-scoped and freeform) — plus an Insights section. ToC updated; Build Phases now reads v1.0.0 → v7.1.0.

Two further stale claims found and fixed while in there:

"Incoming federation (processing Likes, Announces, and remote replies) is planned for v4." — false. The inbox has handled these since v6: Like/Announce → ap_interactions (routes/activitypub.ts:517), remote replies → comments (:629), plus Follow/Undo/Delete. Replaced with what it actually processes, pointing at the trust chain. (This one nearly survived — it reads like it describes a different, still-unbuilt feature. It doesn't.)
"Admins can disable ActivityPub instance-wide from Settings → Federation" — the kill-switch moved to the Admin page in the v6.2 Settings/Admin split (FederationSettings is rendered by pages/Admin/AdminPage.tsx).

Acceptance criteria:

README states the current version and documents v7 federation features and their prerequisites.

Both CI jobs green on run 195. Everything asserted was checked against the code or CHANGELOG rather than inferred — no invented endpoints or settings.

Fixed in `c09cc84` (v7.2.0). README 681 → 764 lines. **New "Federation (v7)" section** — the point of the issue. Written for an operator who has never seen the codebase, and deliberately leads with the trust boundary: - **Admin prerequisite, stated prominently:** an admin must add *and enable* the remote instance on the Federation page first. An actor whose instance isn't federated+enabled can't be invited and can't write — **there is no open inbox**. - **The five-layer trust chain on an inbound write**, in order: not defederated (checked *before* any signature work) → signature covers `(request-target)`/`date`/`digest` with the digest verified against the raw body and a 5-minute freshness window → verifies against the actor's cached key → **signer bound to `activity.actor`** (401 on mismatch, every activity type) → must be an accepted remote editor on the target project (403). - Inviting a remote editor (owner-only, auto-accepted, signed `Invite` → their "Shared with me"), conflict resolution + the owner review queue, `GET /ap/projects/:id`, the SSRF guard (private-range denylist, per-hop redirect re-validation, admin-federated bypass so homelab peers still work), and the defederation kill-switch. **Also added:** "Categories" (v6.2) under a renamed **Tags & Categories** section — drawing the distinction that actually confuses people (categories are project-scoped and curated; tags are user-scoped and freeform) — plus an **Insights** section. ToC updated; Build Phases now reads v1.0.0 → **v7.1.0**. **Two further stale claims found and fixed while in there:** 1. *"Incoming federation (processing Likes, Announces, and remote replies) is planned for v4."* — **false**. The inbox has handled these since v6: `Like`/`Announce` → `ap_interactions` (`routes/activitypub.ts:517`), remote replies → `comments` (`:629`), plus Follow/Undo/Delete. Replaced with what it actually processes, pointing at the trust chain. (This one nearly survived — it reads like it describes a *different*, still-unbuilt feature. It doesn't.) 2. *"Admins can disable ActivityPub instance-wide from Settings → Federation"* — the kill-switch moved to the **Admin** page in the v6.2 Settings/Admin split (`FederationSettings` is rendered by `pages/Admin/AdminPage.tsx`). **Acceptance criteria:** - [x] README states the current version and documents v7 federation features and their prerequisites. Both CI jobs green on run 195. Everything asserted was checked against the code or CHANGELOG rather than inferred — no invented endpoints or settings.

claude-bot closed this issue

2026-07-17 03:09:24 +00:00