From c05a00092eccafea7c968654b019345dbb262604 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:35:14 +0200 Subject: [PATCH 1/2] docs/security.md: the security model in plain words What an attacker could do before (instructions hidden in reports, a skipped check that counted as passed, releases straight to every player, downloads trusting GitHub alone, pipeline files changed like any other), what stops it now (untrusted text, verify always running, beta then stable, signed updates, code owners, the agents' own GitHub App), what still needs Ludovic, and what it doesn't solve. Written for the website's Contributing page; CONTRIBUTING.md links it. Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 1 + docs/security.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/security.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26bfb3759..16cb9d86f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,6 +66,7 @@ your change can affect. Without the vanilla data on your machine it lists those `release-now` is for crash fixes that shouldn't wait. pr_ready suggests one. Every merge to main is released automatically ([release flow](docs/release-flow.md)), so main always stays playable. +How agents, checks, releases and signed updates keep this safe: [security](docs/security.md). ## Parity checks on forks diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 000000000..5b1ed3aad --- /dev/null +++ b/docs/security.md @@ -0,0 +1,84 @@ +# Security + +How Horizon keeps its code and its downloads safe while most of the work is done by AI agents and releases go out +by themselves, including when Ludovic isn't at his computer. In plain words: what someone could have done before, +what stops them now, and what still needs Ludovic. + +## Who does what + +- **Agents** (Claude sessions run by Ludovic) write most pull requests, review them, merge them and answer + reports. Everything an agent posts on GitHub says so ("Opened by Ludovic's AI agent"). +- **Contributors** send pull requests from their forks like on any open-source project. +- **Players** report bugs on Discord and GitHub. Kira, the Discord bot, files their reports as issues. +- **Releases** are automatic: every merged change that players run ships within the hour. + +## What could go wrong before (October 2026) + +1. **Instructions hidden in a report.** Someone could write "ignore your previous instructions and…" in a + Discord message or an issue. Agents read those reports while working with Ludovic's full GitHub account. +2. **A check that counted as passed without running.** Adding a label to a pull request started a second run of + the checks in which `verify` was *skipped*, and GitHub counts a skipped required check as passed. Two pull + requests merged before their real check had finished. +3. **Every release went straight to every player.** A broken or malicious build reached every launcher within + minutes, with nobody looking at it first. +4. **Downloads trusted GitHub alone.** Anyone who got hold of a token that can write to the repository could + replace a release's files, and launchers and servers would install them. +5. **The release machinery was ordinary code.** A pull request could change the workflows that build and publish + releases as easily as it changes a texture. + +## What stops it now + +- **Reports are data, never instructions.** Agents receive people's text only inside quoted blocks marked as + untrusted, with attachments as plain links. Text that looks aimed at an AI (talking to "the AI", asking to run + commands, asking for passwords or keys, linking to scripts, hidden characters) is marked **suspicious**, and the + agent coordinating the others sees the mark. +- **`verify` always runs.** Labels no longer start the checks, and the required `verify` job has no condition, so + the only `verify` a change can have is one that ran. Main requires it, from GitHub Actions only, for everyone, + admins included. +- **Beta, then stable.** Every release is first a **beta**. It becomes **stable**, the version launchers and + servers install by themselves, only after it has been out 6 hours, passed its smoke test (the game started and + drew a world on the Mac mini), and nobody has labelled an issue naming it `release-blocker`. Players who want the + newest builds at once turn on "Beta builds" in the launcher's Settings. Discord announces stable releases only. +- **Signed updates.** Each release carries a list of its files' checksums, signed with Horizon's release key. The + launcher (for the game and for itself) and `horizon-server update` check that signature against the public key + built into them, then check the download against the list. Anything unsigned, signed with another key, signed + for another version, or changed in any way is refused with a message saying why. The private key exists only as + a secret of GitHub's `release` environment, which only real releases from main can use. The job that signs runs + nothing from the repository but a short script calling OpenSSL, so no pull request can read the key by changing + the code that gets built. Nobody, Ludovic included, ever needs to see it. +- **The release machinery needs Ludovic.** The workflows, the release and signing tools, the update-checking code + and the installers are listed in `.github/CODEOWNERS`. Once main's protection requires code owners' reviews, a + change to any of them waits for Ludovic's approval. Everything else still merges as soon as its checks pass. +- **Agents get their own, smaller identity** (prepared, switched on by Ludovic). The `horizon-agent` GitHub App + can read and write code, pull requests and issues, and read the checks. It cannot change settings, workflows, + secrets or members, and its tokens last an hour. Once agents use it, their pull requests are the app's, and + Ludovic approves the rare pipeline change with one tap. + +## What still needs Ludovic + +- **Approving pipeline changes** (rare): a pull request touching a file in `.github/CODEOWNERS`. +- **Holding a release back or speeding one up**, from his phone if he likes. Label an issue naming the version + `release-blocker` to hold that beta and the later ones. Run the `promote` workflow (GitHub app: Actions, + promote, Run workflow) to make a beta stable at once. +- **Creating the GitHub App**: one link, "Create GitHub App", then "Install". His login, his clicks. +- **Fork pull requests**: they run on the Mac mini only after a maintainer has read them and added `run-parity`. +- **A leaked key**: rotate it (docs/release-flow.md, "Signed checksums"). Launchers older than the new key then + refuse new versions until players download the launcher again. + +## What this doesn't solve + +- **Code that merges is code that ships.** Signing proves a build came from Horizon's pipeline, not that the code + is good. Against a bad change, the safety nets are the checks and harnesses, review, the 6-hour beta and the + release-blocker label. +- **Until agents switch to the App**, they still work with Ludovic's own account, so nothing technical tells his + actions from theirs. Code owners' reviews are switched on together with the App. +- **The Mac mini** builds the macOS release and also runs the parity checks of this repository's pull requests, + so a pull request runs code on it before review. Forks don't. +- **The first install** with `install.sh` / `install.ps1` checks the checksum GitHub publishes, not the + signature: verifying Ed25519 signatures needs OpenSSL 3, which macOS doesn't ship. Every update after that + checks the signature. + +## Reporting a security problem + +Use GitHub's private vulnerability reporting (the repository's **Security** tab, "Report a vulnerability"), not a +public issue or Discord. Say what you found and how to reproduce it; we answer there. From 1ea04a2b10da1cae1c4f1acd8cfd827cfa4bb2e5 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:45:24 +0200 Subject: [PATCH 2/2] docs/security.md: where things stand today, and the Mac mini runs forks' code too once labelled - A table of what is live, waiting to merge, or waiting for Ludovic, so the page doesn't read as if it all were. - Forks: their checks need a maintainer's approval, and run-parity runs them on the Mac mini; the Mac mini section no longer says forks don't run there, and says what a clean release checkout does and doesn't fix. - Blockers hold every beta while open; releases from before signing stay installable with pinned files. Co-Authored-By: Claude Opus 5.5 --- docs/security.md | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/security.md b/docs/security.md index 5b1ed3aad..7dead0e83 100644 --- a/docs/security.md +++ b/docs/security.md @@ -26,6 +26,24 @@ what stops them now, and what still needs Ludovic. 5. **The release machinery was ordinary code.** A pull request could change the workflows that build and publish releases as easily as it changes a texture. +## Where things stand (19 October 2026) + +The next section describes the design once every part is in place. Some parts are live, some are waiting to merge, +and some are waiting for Ludovic: + +| Part | Today | +| --- | --- | +| `verify` always runs | **Live** (#1010). | +| Fork pull requests need approval | **Live**: every outside contributor's workflows wait for a maintainer's approval. | +| Private vulnerability reporting | **Live** (see the end of this page). | +| Signed checksums on releases | **Live** for new releases (#1011): the `release` environment holds the key, and its public half is in `release-keys.txt` (#1023). Releases from before then are unsigned. | +| Launchers and servers checking signatures | **Not yet**: #1014 waits as a draft until a signed stable game release and a signed launcher release exist. Until then they trust GitHub's checksum, as before. | +| Beta, then stable | **Not yet** (#1012): every release still goes straight to every player. The launcher's "Beta builds" switch is already there (#1013), and has no betas to offer yet. | +| Reports marked suspicious | **Partly**: the scan of Discord for agents does it. Kira's issues do it once its pull request merges. | +| Code owners' review of the pipeline | **Not yet**: `.github/CODEOWNERS` and its protection (#1015) wait for the App, below. Until then pipeline changes merge like any other once `verify` passes. | +| Agents on their own GitHub App | **Not yet**: prepared, waiting for Ludovic to create it. Agents still use his account. | +| Mac mini releases from a clean checkout | **Waiting to merge** (#1024): see "What this doesn't solve". | + ## What stops it now - **Reports are data, never instructions.** Agents receive people's text only inside quoted blocks marked as @@ -36,13 +54,16 @@ what stops them now, and what still needs Ludovic. the only `verify` a change can have is one that ran. Main requires it, from GitHub Actions only, for everyone, admins included. - **Beta, then stable.** Every release is first a **beta**. It becomes **stable**, the version launchers and - servers install by themselves, only after it has been out 6 hours, passed its smoke test (the game started and - drew a world on the Mac mini), and nobody has labelled an issue naming it `release-blocker`. Players who want the + servers install by themselves, only after it has been out 6 hours and passed its smoke test (the game started and + drew a world on the Mac mini), and only while no issue labelled `release-blocker` is open. If no beta has + become stable for a day, an issue says so. Players who want the newest builds at once turn on "Beta builds" in the launcher's Settings. Discord announces stable releases only. - **Signed updates.** Each release carries a list of its files' checksums, signed with Horizon's release key. The launcher (for the game and for itself) and `horizon-server update` check that signature against the public key built into them, then check the download against the list. Anything unsigned, signed with another key, signed - for another version, or changed in any way is refused with a message saying why. The private key exists only as + for another version, or changed in any way is refused with a message saying why. Releases from before signing + stay installable, for going back to an older version, but only with the exact files they had when signing + began: their checksums are built into the launcher and the server too. The private key exists only as a secret of GitHub's `release` environment, which only real releases from main can use. The job that signs runs nothing from the repository but a short script calling OpenSSL, so no pull request can read the key by changing the code that gets built. Nobody, Ludovic included, ever needs to see it. @@ -57,11 +78,12 @@ what stops them now, and what still needs Ludovic. ## What still needs Ludovic - **Approving pipeline changes** (rare): a pull request touching a file in `.github/CODEOWNERS`. -- **Holding a release back or speeding one up**, from his phone if he likes. Label an issue naming the version - `release-blocker` to hold that beta and the later ones. Run the `promote` workflow (GitHub app: Actions, +- **Holding a release back or speeding one up**, from his phone if he likes. Label an issue `release-blocker` to + hold every beta until it is closed. Run the `promote` workflow (GitHub app: Actions, promote, Run workflow) to make a beta stable at once. - **Creating the GitHub App**: one link, "Create GitHub App", then "Install". His login, his clicks. -- **Fork pull requests**: they run on the Mac mini only after a maintainer has read them and added `run-parity`. +- **Fork pull requests**: their checks run only after a maintainer approves them, and they run on the Mac mini only + after a maintainer has read them and added `run-parity`. - **A leaked key**: rotate it (docs/release-flow.md, "Signed checksums"). Launchers older than the new key then refuse new versions until players download the launcher again. @@ -72,8 +94,12 @@ what stops them now, and what still needs Ludovic. release-blocker label. - **Until agents switch to the App**, they still work with Ludovic's own account, so nothing technical tells his actions from theirs. Code owners' reviews are switched on together with the App. -- **The Mac mini** builds the macOS release and also runs the parity checks of this repository's pull requests, - so a pull request runs code on it before review. Forks don't. +- **The Mac mini** builds the macOS release and also runs pull requests' parity checks: a pull request from this + repository runs its code there before review, and a fork's does once a maintainer adds `run-parity`. Code + running there as the runner's user could tamper with what the next release builds. Releases check out clean + (#1024), which removes anything a pull request left in the work folder by accident, but + not a deliberate attack. The protection is review: only agents and maintainers push to this repository, and a + maintainer reads a fork's change before labelling it. - **The first install** with `install.sh` / `install.ps1` checks the checksum GitHub publishes, not the signature: verifying Ed25519 signatures needs OpenSSL 3, which macOS doesn't ship. Every update after that checks the signature.