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