From d61b3e5978fb3e976a77706c2e7ee648c74f05af Mon Sep 17 00:00:00 2001 From: Joshua Oosthuizen Date: Tue, 17 Nov 2026 13:19:41 +0200 Subject: [PATCH] Docs: agent 1.0 built (changes while building), handover, changelogs Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 22 ++++++++++++++++++++++ apps/events/CHANGELOG.md | 8 ++++++++ docs/AGENT-1.0-PLAN.md | 28 ++++++++++++++++++++++++++++ docs/HANDOVER.md | 2 +- 4 files changed, 59 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4df480f..5a4ae3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,28 @@ Each package and app has its own section and its own tags (`contracts@1.0.0`, `a ## Unreleased +Phase 1d (docs/AGENT-1.0-PLAN.md), built on `feat/agent-1.0`, not released yet: + +### Contracts (1.3.0) + +- `crosscode.agent-job/1` (fixed job types, strict arguments), `crosscode.agent-report/1`, + `crosscode.script-report/1`, `crosscode.agent-stats/1`, the agent join / poll requests, + `crosscode.env-template/1` and `crosscode.church-export/1`. +- `@crosscode/contracts/signing`: Ed25519 jobs (over canonical JSON) and agent requests, config + sealed to a server (X25519 + HKDF + AES-256-GCM), export encryption. + +### Agent (1.0.0) + +- `apps/agent`: polls the Hub, checks every job (pinned key, server, time window, replays, type, + arguments) and runs the crosscode script for it; stats every minute; listens on nothing. + Install script, systemd unit, self-update with automatic revert. + +### crosscode script + +- `--json` reports and `--config` on every command; `.env` files from each release's env template + (appended to, never rewritten, on deploy); `install --frp` with Hub-given ports, a database on + another server, and clean-up on failure; frpc.ini blocks; `restart`, `export`, `uninstall`, `purge`. + ## events@2.2.0, contracts@1.2.0 - 2026-11-17 ### Events diff --git a/apps/events/CHANGELOG.md b/apps/events/CHANGELOG.md index 0d3dd4c..55c32f5 100644 --- a/apps/events/CHANGELOG.md +++ b/apps/events/CHANGELOG.md @@ -7,6 +7,14 @@ and this project follows [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Added + +- `env.template.json`: every `.env` variable with its layer, for installs and updates from the Hub. +- `scripts/export-church.ts`: the church's data as `crosscode.church-export/1` (for `crosscode export`). +- A site installed from the Hub registers by itself on first start when `HUB_LICENCE_KEY` is set + (with `HUB_ADMIN_NAME` / `HUB_ADMIN_EMAIL` as its admin contact), retrying while the Hub is + unreachable. + ## [2.2.0] - 2026-11-17 Cross Events moves into the `crosscode-platform` monorepo (ROADMAP-v3 phase 1b, diff --git a/docs/AGENT-1.0-PLAN.md b/docs/AGENT-1.0-PLAN.md index 7742b92..1d8a638 100644 --- a/docs/AGENT-1.0-PLAN.md +++ b/docs/AGENT-1.0-PLAN.md @@ -8,6 +8,10 @@ This replaces the old rule "the Hub never deploys" (decisions 10 and 23). The pa stays: **no site depends on the Hub to keep running**, and everything still goes through the `crosscode` script (EVENTS-2.2-PLAN §4), which keeps working by hand over SSH. +**Built 2026-11-18** (crosscode-platform branch `feat/agent-1.0`, events-hub branch +`feat/servers-agent`; not merged or released). Waiting for the VM tests (§13). Where the build +differs from this plan, see [Changes while building](#changes-while-building). + ## Contents 1. [The shape](#1-the-shape) @@ -453,6 +457,30 @@ Central check: both ports are open in frps and only on 127.0.0.1. 5. Docs: CHANGELOGs, HANDOVER.md (1d done), `events-hub/deployment.md` (the job-signing key), a server how-to in `apps/agent/README.md`. +## Changes while building + +Made on 2026-11-18, while building; none changes what Joshua or a church sees. + +1. **Config encryption** is X25519 + HKDF-SHA256 + AES-256-GCM (`x25519-hkdf-sha256-aes-256-gcm`) + instead of `x25519-xsalsa20-poly1305`: Node's built-in crypto has no XSalsa20, and this needs no + extra library on the servers. Same guarantee: only the server's private key opens it. +2. **Deployments, not new Install fields.** An `Install` row only exists once a site registers + with its licence, so the Hub keeps a `Deployment` per product per server (short name, domain, + ports, status), linked to its Install when the site registers. Installs made from the Hub + register by themselves: `HUB_LICENCE_KEY` in their `.env` (Events, on first start). +3. **The export key** goes to the Hub in the export job's report, so the Hub can email the link; + it's used once and never stored (job rows keep the report without it). The Hub still can't read + the stored file. +4. **Jobs are signed when the agent picks them up**, not when they're planned, so a scheduled job + carries the server configuration as it is at that moment. +5. **Uninstall runs as a batch of two** (export, then uninstall), so the uninstall never runs if + the export failed. +6. **Install behind frp** doesn't use nginx on the church server: frpc tunnels the app's two ports + straight to the central server (`crosscode install --frp`). The ports from the Hub are used for + `local_port` and `remote_port`. +7. **`crosscode install`** refuses a database or role that already exists, so it can never take + over (or, on a failed install, drop) another site's database. + ## Decisions Agreed with Joshua on 2026-11-12 (ROADMAP-v3 decisions 27–37): diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index 63939d6..cd1a660 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -27,7 +27,7 @@ for each phase. They moved here from `hope-events/docs/` on 2026-11-05. | 1 | Hub 2.0.0 | **Released** 2026-11-05 (`events-hub` `v2.0.0`; `docs/HUB-2.0-PLAN.md` there). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). crosscode-site's address prices are merged, **not deployed yet** | | 1b | Cross Events 2.2.0: moves here as `apps/events`, `crosscode` script | **In progress.** Planned in [EVENTS-2.2-PLAN.md](./EVENTS-2.2-PLAN.md). **Steps 1–3 done 2026-11-12** (merged into `main`): history merged in under `apps/events` (from `hope-events` `e6c9670`), workspaces and one root lockfile with versions pinned to 2.1.1, same test results as 2.1.1 (711 backend tests, typecheck, both builds). **The `crosscode` script and `adopt` (§4–5) are written** (branch `feat/crosscode-script`, 2026-11-12; shellcheck and 47 bats tests pass, not yet run on a server). **Tagged `events@2.2.0` on 2026-11-17, before the VM testing (Joshua's call), with two additions: AI use in tokens and the backend under `/api` (Hub `v2.0.1` and crosscode-site `v1.2.0` released with them).** **Still to do:** VM testing (§6) of the tagged release, adopting each install, archiving `hope-events` (§7). Until then servers keep deploying from `hope-events` `v2.1.1`, and **Events work happens here** (`hope-events` is frozen; a hotfix there as 2.1.2 is cherry-picked into `apps/events`) | | 1c | Cross Events 2.3.0: authenticator app 2FA (TOTP + recovery codes) | TOTP not started (`TwoFactorMethod` enum in Events' `prisma/schema.prisma`). | -| 1d | Agent 1.0.0 + Hub 2.1.0 (+ contracts 1.3.0): server agent, installs / scheduled updates / uninstalls from the Hub, server stats | **Planned** 2026-11-12 in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md) (ROADMAP decisions 27–37). Starts after 1b; can run alongside 1c | +| 1d | Agent 1.0.0 + Hub 2.1.0 (+ contracts 1.3.0): server agent, installs / scheduled updates / uninstalls from the Hub, server stats | **Built 2026-11-18, not released.** crosscode-platform branch `feat/agent-1.0` (contracts 1.3.0, the crosscode script with `--json`, env templates, frpc, restart / export / uninstall / purge, Events env template + export + `HUB_LICENCE_KEY`, `apps/agent`), events-hub branch `feat/servers-agent` (Hub 2.1.0). All unit and script tests pass. **Still to do:** the VM tests (AGENT-1.0-PLAN §13, together with EVENTS-2.2-PLAN §6), then release and roll out (§14). | | 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | Not started. Events keeps speaking protocol 1 until then | | 3–7 | Accounts 1.0.0 → Website 1.0.0 → Events 3.0.0 → App 1.0.0 → App 1.x | Not started |