diff --git a/CHANGELOG.md b/CHANGELOG.md index 98d47cec..840a979a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,8 +41,8 @@ and only when it changes something a contributor or fork holder must do ## Unreleased -User-visible: one change to how updates roll out. Not user-visible: the -protocol now carries a version number. +User-visible: one change to how updates roll out, and two new documents. +Not user-visible: the protocol now carries a version number. ### Login & connection @@ -64,6 +64,15 @@ protocol now carries a version number. show up in the audit log. Invite entries name the invite by id, never by code. +### Documentation + +- `docs/trust-model.md` answers "who can read my messages?": the server + operator can read text and files; voice, video and screen share are + end-to-end encrypted; what beta does not claim. Every claim cites the code + or test behind it. +- `docs/architecture/plugins.md`: plugins are experimental, off by default, + compiled out of release binaries, and carry no API promise. + ### Repository - `protocol/schema.json` declares `protocol_epoch`; `npm run generate` emits it diff --git a/docs/plans/b2-protocol-trust-compat-2026-08-28.md b/docs/plans/b2-protocol-trust-compat-2026-08-28.md index 45e9ce8f..1bbab71c 100644 --- a/docs/plans/b2-protocol-trust-compat-2026-08-28.md +++ b/docs/plans/b2-protocol-trust-compat-2026-08-28.md @@ -5,7 +5,7 @@ `v1.2.0-alpha.4` — claims verified at `64d2e108`; the branch was rebased onto `dd7ed091` (#1432) before merge **Status:** in progress — entry gate 1 of 3 met at draft time (see below); B2-0, -B2-1 and B2-8 landed 2026-08-28, B2-2 (with B2-3 and B2-4 folded in) and B2-5 on 2026-08-29 (evidence in their sections); B2-6 landed 2026-08-29 (PR #1441); B2-7 is next. +B2-1 and B2-8 landed 2026-08-28, B2-2 (with B2-3 and B2-4 folded in) and B2-5 on 2026-08-29 (evidence in their sections); B2-6 landed 2026-08-29 (PR #1441); B2-7 is in review 2026-08-29 (evidence in its section). Update this line, not only the step table, when a step lands. Primary inputs: @@ -570,6 +570,85 @@ Runs in parallel with B2-1 and B2-6. re-tagging the gate to B10 with the reason recorded in HP-2. Doing neither is not an option. +**Evidence, 2026-08-29** — branch `feat/b2-7-trust-model` from `dev` +`2b2d58ab`; PR to `dev` (number recorded in the review-outcome note below). +HP-2 questions 3 and 6 cite this block. + +- Pre-squash SHAs, one commit per item: `a4cd077b` (item 1, trust model + + links), `083d87d9` (item 2, absence test + outbound-host table), `cbfcf702` + (item 3, plugin boundary), and the commit carrying this block (item 4, the + L-08 decision + register row). +- Item 1 — `docs/trust-model.md`. Sections as planned: the short answer, + server-readable data and why, E2EE rules with their tests, transport per + `tls.mode` with desktop pinning and the browser rule, the C-09 contract + (eight MUST clauses and the regression list, stated as requirements — the + private report's mechanism is not reproduced), at rest, operator can/cannot, + multi-device sessions, what beta does not claim. Every claim carries a + `path:line` or a test name, verified by reading the line at `2b2d58ab`; + two claims are absences with no positive test and say so (server holds no + room key; text is not encrypted). Linked from `docs/security.md` (new + §Trust model), `docs/deployment.md` §TLS Setup, `docs/quick-start.md` + §Client Connection Notes, `docs/README.md` (both tables). + - **BPR-051 exit evidence** — a non-developer reads "The short answer" and + answers "who can read my messages?" correctly. Reader: **\_\_\_\_**. + Date: **\_\_\_\_**. Answer given: **\_\_\_\_**. (Owner fills in; + HP-2 question 3 quotes this line.) +- Item 2 — `Server/api/absence_contract_test.go` + `TestAbsenceContract_NoFederationDirectoryOrListingRoutes`. Builds the + production router with uploads, voice and the GIF proxy on (the bare + `setupRouter` config mounts only 92 routes; the full one clears the 100-route + floor), `chi.Walk`s the tree including the mounted `/admin` and + `/api/v1/admin/plugins` subrouters, and fails on `(?i)federat|directory|discover|listing`. + Green on `2b2d58ab` (`go test -race ./api/`). Proven able to fail by + temporarily mounting `r.Get("/directory", healthHandler)` under `/api/v1` + in `router.go`: + + ``` + absence_contract_test.go:92: routes matching "(?i)federat|directory|discover|listing" must not exist (see docs/trust-model.md, "What OwnCord does not have"): + GET /api/v1/directory + --- FAIL: TestAbsenceContract_NoFederationDirectoryOrListingRoutes (0.02s) + ``` + + `router.go` restored before the commit (`git checkout`, tree clean). A grep + of non-test `Server/` for `federat` is empty; every `directory|discover|listing` + hit is a filesystem directory, a config field or a query-result noun. The + outbound-host table in `trust-model.md` §"Outbound connections the server + makes" came from a read of every `http.Client`, `net.Dial` and URL literal + in non-test server code (ten rows, each with trigger, purpose, off switch + and anchor) and is B6's capture checklist; no analytics, crash reporting or + phone-home exists. + +- Item 3 — `docs/architecture/plugins.md`, linked from + `docs/architecture/README.md`, `docs/architecture/server.md`, + `docs/README.md`. Finding worth stating on its own: **release binaries and + the Docker image are built without `-tags wazero`** + (`.github/workflows/release.yml:261`, `:268`; `Server/Dockerfile:13`), so + no shipped artifact can execute a plugin regardless of `plugins.enabled`; + the HP-2 question 6 configuration audit (fresh, upgraded, Docker, + standalone, source-with-flag) is the table in that document. The beta + release-notes paragraph is in the same file and is to be quoted verbatim. +- Item 4 — **L-08 decision: re-tag the build gate to B10.** The two options + were a compile-and-compare job with a second Go SDK, or re-tagging with the + reason recorded for HP-2. Re-tagged, because: (a) "compare" cannot pass in + principle — TinyGo 0.40.1 embeds absolute host paths and has no `-trimpath` + (`Server/plugin/examples/hello/README.md:70-74`), so the only honest + check is compile-only; (b) that compile needs TinyGo 0.40.1, a Go 1.25.x + SDK beside the repo's Go 1.26, and Binaryen 129 on every PR + (`hello/README.md:37-44`); (c) the subsystem is compiled out of every + shipped artifact (item 3), so a per-PR job guards nothing a release + contains. B10 (qualify and publish the beta) runs the compile once against + the release candidate or closes on the provenance record already in the + README. The register row now says so + (`docs/plans/repo-health-issue-register-2026-08-23.md` L-08, phase + `B1/B10`); the "no API promise" half of its closure evidence is closed by + item 3. HP-2 cites this paragraph as the reason. +- Gates before each commit: `npm run check:docs`, `npm run check:hygiene` + (prettier over the tree; shellcheck/actionlint skipped locally, CI runs + them); for item 2 additionally `go vet ./api/`, `golangci-lint run ./api/...` + (0 issues), `go test -race -count=1 ./api/`; the full server gate (four + build variants, `go vet`, `go test -race ./...`, `-tags deadlock ./ws/`, + `golangci-lint run`) ran before push. + ## B2-8 — The B2-tagged findings Lands **before** B2-2; they touch the same replay/resume files. diff --git a/docs/plans/repo-health-issue-register-2026-08-23.md b/docs/plans/repo-health-issue-register-2026-08-23.md index b53ad78f..bef85e34 100644 --- a/docs/plans/repo-health-issue-register-2026-08-23.md +++ b/docs/plans/repo-health-issue-register-2026-08-23.md @@ -224,24 +224,24 @@ The layout audit recommends a targeted, isolated migration—not a wholesale monorepo/server rewrite. Pure moves, mechanical path rewrites, and behavior-changing work must remain in separate reviewable commits. -| ID | Pri | Source | Required work | Phase | Closure evidence | -| ---- | --: | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ----------------------------------------------------------------------------------------------------------------------- | -| L-01 | P1 | RL-01 | Flatten `Client/tauri-client/` to `Client/` as two adjacent non-functional commits: pure file moves, then mechanical active-path rewrites. | B1 | History/release asset names are preserved and the full baseline is unchanged after both commits. | -| L-02 | P1 | RL-02 | Record the browser/desktop platform-contract map in B1, then introduce typed adapters for native-dependent frontend services. | B7 | The same adapter contract suite passes for desktop and browser implementations. | -| L-03 | P1 | RL-03 | Establish independent `build:web` and `build:desktop` contracts from one shared UI after server-first phases close. | B7 | Both production builds are required and target-specific behavior is isolated. | -| L-04 | P2 | RL-04 | Add cross-platform root bootstrap, format, generation, scoped, and full verification commands. | B1 | Fresh Windows/Linux contributors can discover and run the intended checks; Go-only direct commands remain supported. | -| L-05 | P2 | RL-05 | Record the workspace decision and cover every lock root with deterministic install/dependency automation. | B1 | Measured rationale, immutable installs, and update coverage for all package roots. | -| L-06 | P2 | RL-06 | Make large Graphify payloads reproducible CI artifacts; retain only a compact deterministic report if needed. | B1 | Portable local/CI generation works, committed report drift is checked, and published history is not rewritten. | -| L-07 | P2 | RL-07 | Remove the tracked duplicate human rendering after deterministic on-demand/CI rendering and a drift check exist. | B1 | The JSON ledger remains canonical; a downloadable rendering is reproducible and CI rejects generation failure or drift. | -| L-08 | P2 | RL-08 | Keep the example WASM source, stop tracking its prebuilt output, and compile/verify it in CI or release checks. | B1/B2 | Deterministic source build passes and no stable plugin API promise is implied. | -| L-09 | P2 | RL-09 | Move protocol schema/generator ownership to a root protocol/tool boundary. | B1/B2 | One command generates Go and TypeScript consumers with zero drift. | -| L-10 | P1 | RL-10 | Move executable tooling under conventional command ownership and remove package-discovery filesystem side effects. | B1 | Broad Go discovery is read-only and tool execution is explicit/tested. | -| L-11 | P2 | RL-11 | Reclassify cross-stack invariants under an explicit owner or root system-contract tier. | B1 | Test names/location/commands expose ownership and CI runs the correct tier. | -| L-12 | P2 | RL-13 | Align the Go module namespace to `github.com/J3vb/OwnCord/Server` in an isolated mechanical change. | B1 | Imports, generators, build tags, source archives, and downstream instructions agree. | -| L-13 | P2 | RL-19 | Add an editor baseline and repository gates for Markdown, YAML, JSON, CSS, Rust, Go, shell, and workflows. | B1 | Cross-platform fast checks cover material tracked sources with explicit generated/vendor exclusions. | -| L-14 | P2 | RL-20 | Make hooks portable and remove undocumented `make`/POSIX assumptions on Windows. | B1 | Hooks are thin optional wrappers around cross-platform root commands; prerequisites are explicit. | -| L-15 | P2 | RL-21 | Route ideas/feedback to Discussions and modernize issue forms for browser, ARM64, deployment mode, and security reporting. | B1 | Intake matches BPR-100..102 and captures reproducible environment details. | -| L-16 | P1 | RL-22 | Harden authorization for externally triggered paid automation. | B1 | Trusted authorization, least privilege, and cost-abuse regression tests are required. | +| ID | Pri | Source | Required work | Phase | Closure evidence | +| ---- | --: | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| L-01 | P1 | RL-01 | Flatten `Client/tauri-client/` to `Client/` as two adjacent non-functional commits: pure file moves, then mechanical active-path rewrites. | B1 | History/release asset names are preserved and the full baseline is unchanged after both commits. | +| L-02 | P1 | RL-02 | Record the browser/desktop platform-contract map in B1, then introduce typed adapters for native-dependent frontend services. | B7 | The same adapter contract suite passes for desktop and browser implementations. | +| L-03 | P1 | RL-03 | Establish independent `build:web` and `build:desktop` contracts from one shared UI after server-first phases close. | B7 | Both production builds are required and target-specific behavior is isolated. | +| L-04 | P2 | RL-04 | Add cross-platform root bootstrap, format, generation, scoped, and full verification commands. | B1 | Fresh Windows/Linux contributors can discover and run the intended checks; Go-only direct commands remain supported. | +| L-05 | P2 | RL-05 | Record the workspace decision and cover every lock root with deterministic install/dependency automation. | B1 | Measured rationale, immutable installs, and update coverage for all package roots. | +| L-06 | P2 | RL-06 | Make large Graphify payloads reproducible CI artifacts; retain only a compact deterministic report if needed. | B1 | Portable local/CI generation works, committed report drift is checked, and published history is not rewritten. | +| L-07 | P2 | RL-07 | Remove the tracked duplicate human rendering after deterministic on-demand/CI rendering and a drift check exist. | B1 | The JSON ledger remains canonical; a downloadable rendering is reproducible and CI rejects generation failure or drift. | +| L-08 | P2 | RL-08 | Keep the example WASM source, stop tracking its prebuilt output, and compile/verify it in CI or release checks. | B1/B10 | Untracking and the toolchain record landed in B1-6 (#1418); "no stable plugin API promise" is closed by `docs/architecture/plugins.md` (B2-7). The build gate is re-tagged to B10 by the B2-7 decision: the output is not byte-reproducible (TinyGo embeds host paths, no `-trimpath`), so "deterministic build" cannot pass in principle, and a compile-only drift check needs a second Go SDK plus TinyGo and Binaryen on every PR for a subsystem that release builds compile out. B10 runs that compile once against the release candidate, or closes on the provenance record. | +| L-09 | P2 | RL-09 | Move protocol schema/generator ownership to a root protocol/tool boundary. | B1/B2 | One command generates Go and TypeScript consumers with zero drift. | +| L-10 | P1 | RL-10 | Move executable tooling under conventional command ownership and remove package-discovery filesystem side effects. | B1 | Broad Go discovery is read-only and tool execution is explicit/tested. | +| L-11 | P2 | RL-11 | Reclassify cross-stack invariants under an explicit owner or root system-contract tier. | B1 | Test names/location/commands expose ownership and CI runs the correct tier. | +| L-12 | P2 | RL-13 | Align the Go module namespace to `github.com/J3vb/OwnCord/Server` in an isolated mechanical change. | B1 | Imports, generators, build tags, source archives, and downstream instructions agree. | +| L-13 | P2 | RL-19 | Add an editor baseline and repository gates for Markdown, YAML, JSON, CSS, Rust, Go, shell, and workflows. | B1 | Cross-platform fast checks cover material tracked sources with explicit generated/vendor exclusions. | +| L-14 | P2 | RL-20 | Make hooks portable and remove undocumented `make`/POSIX assumptions on Windows. | B1 | Hooks are thin optional wrappers around cross-platform root commands; prerequisites are explicit. | +| L-15 | P2 | RL-21 | Route ideas/feedback to Discussions and modernize issue forms for browser, ARM64, deployment mode, and security reporting. | B1 | Intake matches BPR-100..102 and captures reproducible environment details. | +| L-16 | P1 | RL-22 | Harden authorization for externally triggered paid automation. | B1 | Trusted authorization, least privilege, and cost-abuse regression tests are required. | Layout findings reconciled elsewhere: RL-12 is owned by R-06; RL-14 by G-03; RL-15 by BG-20; RL-16 by R-09; RL-17 by C-01; and RL-18 by L-05,