From cc27b5b180f45af622c67501ffbade7cc9039658 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Fri, 16 Oct 2026 16:24:40 +0300 Subject: [PATCH] docs: install from the 0.1.0 release, and fetch the unit from its tag The README, the setup guide and SECURITY.md still said that there is no release. The install steps now offer the release first: download the tarball and SHA256SUMS on a trusted machine, check them as docs/releasing.md says, copy the file straight to each machine, and check its SHA-256 on the broker host. Building from the source stays as the second way. The release tarball does not hold the systemd unit. Section 8 and the upgrade steps in section 13 now fetch it from the tag of the version, named as refs/tags/... so that a branch with the same name cannot serve a changed unit, and never through an agent machine. Closes #81 --- README.md | 54 +++++++++++++++++++++++++++++++++++++------------- SECURITY.md | 5 ++++- docs/setup.md | 55 ++++++++++++++++++++++++++++++++++++--------------- 3 files changed, 83 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index aa72e27..30c6a68 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,12 @@ nodkey lets an AI coding agent use a secret or an SSH key only after a person approves that one request on a phone. -**Status:** on 2026-10-15, the code of version 1 is on `main`, and the -test with a real Telegram bot -([#17](https://github.com/code6x/nodkey/issues/17)) is done. There is no -release yet. Try it on a test setup first. See the +**Status:** on 2026-10-15, the code of version 1 is on `main`, the test +with a real Telegram bot +([#17](https://github.com/code6x/nodkey/issues/17)) is done, and the +first release, +[0.1.0](https://github.com/code6x/nodkey/releases/tag/v0.1.0), is out. +Try it on a test setup first. See the [v1 milestone](https://github.com/code6x/nodkey/milestone/1). ## How it works @@ -48,17 +50,31 @@ clipboard, terminals and browser. Keep no SSH key or other way to get root on the broker host on the agent machine ([docs/setup.md section 1](docs/setup.md#where-you-do-the-setup)). -1. **Install** `nodkey` on both machines. There is no release yet, so - build it from this repository with Go 1.26 or newer, on a trusted - machine, never on the agent machine: +1. **Install** `nodkey` on both machines. Get it on a trusted machine, + never on the agent machine. The easy way is the + [latest release](https://github.com/code6x/nodkey/releases/latest): + download the tarball for the CPU of each machine, such as + `nodkey_0.1.0_linux_amd64.tar.gz` or `nodkey_0.1.0_linux_arm64.tar.gz`, + and `SHA256SUMS`. Check them as + [docs/releasing.md](docs/releasing.md#verify-a-download) says, and + take the file `nodkey` out of the tarball: + + ```sh + tar -xzf nodkey_0.1.0_linux_amd64.tar.gz nodkey + ``` + + If the two machines have different CPUs, take each file out in a + folder of its own, and copy each to its machine. + + Or build it from this repository with Go 1.26 or newer: ```sh CGO_ENABLED=0 go build -trimpath -o nodkey ./cmd/nodkey ``` - Copy the file straight to both machines, not through the agent - machine. On the broker host, `sha256sum nodkey` must print the same - SHA-256 as on the build machine. Install it as root: + Copy the file `nodkey` straight to both machines, not through the + agent machine. On the broker host, `sha256sum nodkey` must print the + same SHA-256 as on the trusted machine. Install it as root: ```sh install -o root -g root -m 0755 nodkey /usr/local/bin/nodkey @@ -136,10 +152,20 @@ root on the broker host on the agent machine ask = "always" ``` - Copy [contrib/systemd/nodkey.service](contrib/systemd/nodkey.service) - to `/etc/systemd/system/`. Keep only the `LoadCredentialEncrypted=` - lines of `broker-tls-key`, `telegram-token` and `bws-token`. Then - start the broker, and read its log: + Take the example unit from the tag of your version, such as + [v0.1.0](https://github.com/code6x/nodkey/blob/refs/tags/v0.1.0/contrib/systemd/nodkey.service), + never through the agent machine + ([docs/setup.md section 8](docs/setup.md#8-the-systemd-unit)). After + a build from the source, use the unit in your copy of the repository + instead. For the release 0.1.0: + + ```sh + curl -fL -o /etc/systemd/system/nodkey.service https://raw.githubusercontent.com/code6x/nodkey/refs/tags/v0.1.0/contrib/systemd/nodkey.service + ``` + + Keep only the `LoadCredentialEncrypted=` lines of `broker-tls-key`, + `telegram-token` and `bws-token`. Then start the broker, and read its + log: ```sh systemctl daemon-reload diff --git a/SECURITY.md b/SECURITY.md index 10f0a36..b772b7a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -33,4 +33,7 @@ normal issues. ## Supported versions -There is no release yet. Until 1.0, only the latest release gets fixes. +Until 1.0, only the +[latest release](https://github.com/code6x/nodkey/releases/latest) gets +fixes. To get a fix, upgrade to the newest release +([docs/setup.md section 13](docs/setup.md#a-new-version-of-nodkey)). diff --git a/docs/setup.md b/docs/setup.md index 5ed8828..3cf344e 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -100,21 +100,23 @@ section 5, item 8). So: ## 2. Get nodkey Install the same version of nodkey on the broker host and on each agent -machine, as `/usr/local/bin/nodkey`, owned by root. +machine, as `/usr/local/bin/nodkey`, owned by root. There are two ways +to get it: from a release, or from the source. Use a trusted machine for +both, never an agent machine ([section 1](#where-you-do-the-setup)). -**From a release.** Download the tarball for your machine and -`SHA256SUMS` from the -[release page](https://github.com/code6x/nodkey/releases). Check both, -as [docs/releasing.md](releasing.md#verify-a-download) says. Then: +**From a release.** This is the easier way. Download the tarball for +your machine, such as `nodkey_0.1.0_linux_amd64.tar.gz` +(`nodkey_0.1.0_linux_arm64.tar.gz` on 64-bit ARM), and `SHA256SUMS` from +the [release page](https://github.com/code6x/nodkey/releases). Check +both, as [docs/releasing.md](releasing.md#verify-a-download) says. Then +take the file `nodkey` out of the tarball: ```sh tar -xzf nodkey_0.1.0_linux_amd64.tar.gz nodkey -install -o root -g root -m 0755 nodkey /usr/local/bin/nodkey ``` -**From the source.** There is no release yet on 2026-10-15. Build nodkey -with Go 1.26 or newer, on a trusted machine. Never build it on an agent -machine: the agent could change the build. +**From the source.** Build nodkey with Go 1.26 or newer. Never build it +on an agent machine: the agent could change the build. ```sh git clone https://github.com/code6x/nodkey.git @@ -125,13 +127,14 @@ CGO_ENABLED=0 go build -trimpath -ldflags "-X main.version=$(git rev-parse --sho The `-ldflags` part is optional. It puts the commit into `nodkey version` and into the `broker_started` entry of the audit log. -Copy the file straight from the build machine to each machine, never -through an agent machine ([section 1](#where-you-do-the-setup)). On the -broker host, check that it is the same file: `sha256sum nodkey` must -print the same SHA-256 as on the build machine. Then install it with the -`install` command above, and check it: +**Then, for both ways:** copy the file `nodkey` straight from the +trusted machine to each machine, never through an agent machine +([section 1](#where-you-do-the-setup)). On the broker host, check that it +is the same file: `sha256sum nodkey` must print the same SHA-256 as on +the trusted machine. Then install it, and check it: ```sh +install -o root -g root -m 0755 nodkey /usr/local/bin/nodkey nodkey version ``` @@ -777,6 +780,18 @@ instead. Copy the example unit [contrib/systemd/nodkey.service](../contrib/systemd/nodkey.service), of the same version as your nodkey, to `/etc/systemd/system/nodkey.service`. +Never copy it through an agent machine: whoever can change the unit can +run a program as root on the broker host. After a build from the source, +the unit is in your copy of the repository. The release tarball does not +hold it. Take it from the tag of your version in the repository, such as +[v0.1.0](https://github.com/code6x/nodkey/blob/refs/tags/v0.1.0/contrib/systemd/nodkey.service), +on the broker host or on the trusted machine. For 0.1.0, on the broker +host: + +```sh +curl -fL -o /etc/systemd/system/nodkey.service https://raw.githubusercontent.com/code6x/nodkey/refs/tags/v0.1.0/contrib/systemd/nodkey.service +``` + Then change it to fit your setup: - Keep one `LoadCredentialEncrypted=` line for each credential that you @@ -1181,9 +1196,17 @@ cut shows as an anchor whose entry is missing. 1. Read the release notes. 2. Get the new version, and check it ([section 2](#2-get-nodkey)). -3. Compare the example unit of the new version with your unit, and take +3. Get the example unit of the new version from its tag, as in + [section 8](#8-the-systemd-unit), but save it as `nodkey.service`, not + over your unit. After a build from the source, use the unit in your + copy of the repository instead. Compare it with your unit, and take over the changes: - `diff -u /etc/systemd/system/nodkey.service contrib/systemd/nodkey.service`. + + ```sh + VERSION=0.1.0 # the new version + curl -fL -o nodkey.service "https://raw.githubusercontent.com/code6x/nodkey/refs/tags/v$VERSION/contrib/systemd/nodkey.service" + diff -u /etc/systemd/system/nodkey.service nodkey.service + ``` 4. Install it, and restart the broker: ```sh