Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,13 +90,19 @@ scope change. Source excerpts are off for new bindings unless you choose
Other hosts use `crosshead quickstart --adapter pi|omp|hermes|opencode`.

The installer downloads one release tarball, checks its SHA-256 against the
installer script, installs three npm dependencies (`@noble/curves`,
`nostr-tools`, `tar`) with install scripts disabled, and writes the wrappers
into `~/.crosshead/bin`. Installed runtimes check the fixed
`https://crosshead.sh` release origin and notify when an update is available.
They do not install remote code unattended. After obtaining the digest from an
independent release channel, install with `crosshead update --sha256 <digest>`.
`crosshead update --pin` disables automatic update checks.
installer script, installs the runtime npm dependencies with install scripts
disabled, and writes the wrappers into `~/.crosshead/bin`.

`crosshead update --auto` enables automatic updates on idle host launches
(the default), checking for a new release about once an hour and retrying failed checks after 30 minutes. Before installing, Crosshead verifies GitHub's signed
build attestation for the exact archive digest and this repository's release
workflow. If verification or download fails, the host still launches and the
update is retried later. `crosshead update --manual` disables automatic
updates. `crosshead update --policy` shows the current setting. The older
`--pin` option remains an alias for `--manual`.

For a manual install, obtain the digest from an independent release channel
and run `crosshead update --sha256 <digest>`.

To check that a release matches this source, compare the installer's
`RELEASE_SHA256` with `SHA256SUMS` on the matching GitHub release. Public
Expand Down
8 changes: 5 additions & 3 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,9 +88,11 @@ npm run typecheck && npm test
Compatibility constraints from already-installed clients:

- The installer and `crosshead update` read `RELEASE_ID`, `RELEASE_URL` and
`RELEASE_SHA256` from `/install`; the release URL must be on the same origin.
The updater additionally requires the operator to supply that SHA-256 from
an independent channel and never performs unattended installation.
`RELEASE_SHA256` from `/install`. The updater accepts only the official hosted
origin or the matching GitHub release asset. In `auto` mode, the updater
verifies GitHub's signed build attestation, release workflow identity, tag
and archive digest before installing on an idle host launch. In `manual`
mode, the operator supplies the trusted digest independently.
- The tarball must contain `package.json`, `package-lock.json` and
`dist/runtime/{cli,daemon,local-runtime,codex-adapter,claude-code-adapter,pi-adapter,codex-bridge,codex-hook,claude-code-bridge,claude-code-hook}.js`.
Older clients `require()` some of these modules directly during updates.
Expand Down
17 changes: 10 additions & 7 deletions docs/SECURITY-REVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,13 +63,16 @@ from it is in scope.

## Trust boundaries and entry points

1. **Install and self-update.** The production installer still reads release
metadata and the tarball from one TLS origin. The client updater is pinned
to `https://crosshead.sh`, requires a SHA-256 supplied through an independent
channel, validates archive entries and runs
`npm ci --omit=dev --ignore-scripts`. Background checks are notification-
only. See `parseInstallerReleaseMetadata`, `validateRuntimeReleaseArchive`
and `src/runtime/runtime-auto-update.ts`.
1. **Install and self-update.** The production installer reads release metadata
and checks the tarball digest. The updater reads metadata only from
`https://crosshead.sh`. In `auto` mode, an idle host launch verifies a
Sigstore build attestation for the exact digest, GitHub Actions release
workflow and tag before installing. In `manual` mode, the operator supplies
a trusted SHA-256 from an independent channel. Both paths validate archive
entries and run `npm ci --omit=dev --ignore-scripts` with install scripts
disabled. A failed update check does not prevent the host from launching.
See `src/runtime/release-attestation.ts`, `runtime-auto-update.ts`, and
`validateRuntimeReleaseArchive`.
2. **Local daemon HTTP API.** It binds `127.0.0.1` on a configurable port
(`src/runtime/local-runtime.ts:2042`). Requests require the
`x-onlybots-local-token` header, including `/health`. The federation-status
Expand Down
Loading
Loading