hex/docs/downloads.md
Dax 8201a4ce1c
ci: read release secrets from aws secrets manager (#1606)
* ci: read release secrets from aws secrets manager

* ci: read the linux signing key from hex/release/RELEASE_SIGNING_KEY

* ci: hex's own aur and homebrew keys; the signing cert has no password

* ci: the signing certificate has no password

* ci: use the shared aur and homebrew keys

* docs: the shared homebrew deploy key is anomaly-release

* docs: the shared homebrew deploy key is anomaly-release

* site: own /hex/files, drop the r2 write credential (#1611)

* site: own /hex/files for installers, appcast, and dev notes

The site build now copies install-linux.sh, install-windows.ps1, and
packaging/macos/legacy-appcast.xml into its Worker assets, so the same
Worker serves them at /hex/files with the Content-Type and Cache-Control
the bucket objects had. The Installers and Legacy appcast workflows,
r2-put.sh, and their R2 write credential are gone.

The dev notes move to the one-commit dev-notes branch, published by
Release's dev-notes job with GITHUB_TOKEN only; the Worker proxies that
file at /hex/files/dev-notes.json (falling back to the bucket copy until
the first dev release creates the branch) and renders /hex/dev from it.

Both site Workers now bind hex-production-files, read-only in code, for
the frozen 2.3.1 feeds and artifacts, which lets hex-dev-files go. The
Site build runs the installer test and appcast check the removed
workflows ran, and the verify job compares the served bytes.

* docs: the site owns /hex/files and needs no R2 write credential

Hosting, secrets, old clients, and Linux packages describe the built
installers and appcast, the dev-notes branch, and the read-only bucket.
2026-11-09 15:18:26 -05:00

160 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Download Hosting
## Public Paths
```ts
anoma.ly/release/hex/ the Anomaly release service (docs/releasing.md)
├── index.json, desktop/stable.json what the site, installers, and apps read
└── files/<sha256>/<name> hex-<v>-macos-arm64.{zip,dmg}, hex-<v>-windows-<arch>.exe,
hex-setup-<v>-windows-<arch>.exe,
hex-<v>-linux-<x64|arm64>{,.deb,.rpm}
anoma.ly/hex the one site: platform-aware download (Worker hex-production-site)
├── download/<target> 302 to anoma.ly/release/hex/desktop/stable/<target> once stable.json
│ exists, else to .../dev/<target> (the newest dev build)
├── install-linux.sh, install-windows.ps1 installers (copied from .github/release/ at the site build)
└── files/… the one owner of every release file (same Worker)
├── install-linux.sh, install-windows.ps1, appcast.xml built and served with the site
├── dev-notes.json the Release workflow's dev-notes branch
└── linux-update.json, windows-update.json, windows-aarch64-update.json, releases/HEX-2.3.1-…
frozen 2.3.1 history in hex-production-files,
read-only from the Worker binding
dev.anoma.ly/hex the dev site (reads anoma.ly/release; the service's dev stage
is only for testing the service)
hex.kitlangton.com, .dev Kit's old site (Kit's Cloudflare account); should 301 to
anoma.ly/hex (Kit's change; nothing links to it)
downloads.hex.kitlangton.dev, .com Kit's old bucket, frozen at 2.3.1; releases up to 2.3.1
compiled it, so it stays up forever; the Worker in
packaging/legacy-downloads redirects it to
anoma.ly/hex/files (same bytes) once deployed
github.com/anomalyco/hex/releases/tag/v<version> identical-byte mirror of every file (app-v through 2.3.1)
```
`docs/releasing.md` describes the Worker config, the workflow that publishes
these, the credentials, and the transition from Kit's bucket.
`hex-production-files` was seeded with byte copies of everything the old bucket
served. A Configuration Rule in the anoma.ly zone disables **Browser Integrity
Check** for `/hex/files/` on anoma.ly and dev.anoma.ly: the zone check returned
HTTP 403 to Python's default user agent. Keep browser challenges off download
and updater routes.
The release workflow uploads every file to the release service (stored by
hash, never replaced), then the release, then mirrors the files to the GitHub
release (verified byte for byte). App tags remain separate from TypeScript SDK
tags. The stable app release is GitHub's Latest release (the repository badge);
SDK releases are created with `--latest=false` and never take it. Still, do not
use GitHub's generic `releases/latest` redirect for an app download: links
name the release service or an explicit `v<version>` tag.
The site reads the stable manifest when it builds, so the production deploy
that follows a stable release updates every link. Bump the README's explicit
app mirror link by hand; the Release workflow pushes
`anomalyco/homebrew-tap/Casks/hex.rb`.
`bun run --cwd site check:downloads` must pass; then verify the live links.
## Network Recovery
App and model downloads have different hosts. Managed networks may need to allow:
- `anoma.ly` (paths `/release/` and, for 2.3.1, `/hex/files/`) for app
downloads and updates (`downloads.hex.kitlangton.dev` too for releases up to
2.3.1, which reach it through a redirect).
- GitHub release downloads and their asset delivery host for the alternative DMG.
- `huggingface.co` and its model download CDN for dictation-model setup.
On September 11, 2026, a HEAD request for the pinned default Parakeet Unified
English artifact followed `huggingface.co` to `us.aws.cdn.hf.co` and returned
HTTP 200. This is an observed delivery host, not a permanent exhaustive CDN list.
No model body was downloaded for that check.
Model downloads, update checks, and transformation scripts' `fetch` go through
Hex's own HTTPS client (`src/net.rs`, #894), which behaves like a browser on a
managed network:
- Proxy: `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, and `NO_PROXY` on every OS
(upper or lower case), else the system's settings. Windows: the signed-in
user's proxy (Settings › Network › Proxy, Internet Options), its PAC file or
WPAD, then the machine's WinHTTP proxy (`netsh winhttp set proxy`). macOS:
the network's HTTP and HTTPS proxies and their exceptions; a PAC file isn't
evaluated, so Hex passes over it to the next HTTP or HTTPS proxy in the list
(#1235), and a PAC-only network needs `HTTPS_PROXY`. Linux: the environment only. A proxy that
needs a sign-in (NTLM, Kerberos) fails with "the proxy needs a sign-in".
- TLS: the platform's own (SChannel, Security.framework, OpenSSL) with the
system's trusted roots, so a TLS-inspecting firewall whose root certificate
IT installed is trusted. A missing root shows as "the certificate isn't
trusted".
- Failures: one line naming the host, the proxy, and the cause ("Couldn't
reach huggingface.co through the proxy proxy.corp:8080: …"), then what to
try. Downloads go in 8 MB ranged pieces with a 5 minute bound each, so a
stalled connection fails instead of hanging, and resume where they stopped.
Observed on apollo (Linux), November 2026: the speech detector, the update
manifest, and a `fetch` worked directly, through mitmproxy with its root in
the trust bundle, and with `NO_PROXY` past a dead proxy; with the root
missing each failed naming the certificate, and with a dead proxy each named
the refused proxy. Not observed: Windows' and macOS' system proxy settings on
a real managed network (the Windows code is cross-compiled only).
If the old update endpoint is blocked, install the new signed DMG manually.
After restoring model-host access, retry preparation in Settings. Transfer failures preserve partial downloads. App download
success does not establish model-host reachability, and our external checks do
not establish access from a particular enterprise network.
## Observed Migration Checks — September 11, 2026
- The initial 2.1.16 mirror and custom-domain DMG matched the published Homebrew
SHA-256: `102dc1a8d80dc359ee15a30141957b6a311e581214b44a3c615026fa91288b8a`.
Its notarization staple validated.
- All five retained Sparkle ZIPs (2.1.12–2.1.16) were fetched directly through
the custom domain, compared to the prepared artifacts, checked against the
feed's lengths, and verified with the app's Ed25519 public key.
- The migration changed only feed hostnames and terminal whitespace; versions,
signatures, lengths, and release notes were preserved. The published feed was
read back identically from both the custom host and old R2 endpoint.
- The live website was rendered and inspected at 1280×900 and 390×844. Both
showed the version, requirements, and alternate link.
- Homebrew's cask and livecheck use the custom hostname; the 2.1.16 checksum
stayed unchanged during the host migration.
- `cargo test --locked`: 455 passed, 10 opt-in tests ignored, and all 12 keyboard
layout child processes passed. A stale Homebrew `libgit2` build-cache path was
cleared before the successful run. Strict all-target/all-feature Clippy and
the site's TypeScript/production build passed.
- No signed Linux feed has been published yet. Linux installer/updater source
defaults were migrated; no Linux native install or enterprise-network test
was performed as part of these hosting checks.
## Observed 2.1.17 Publication — September 11, 2026
Published macOS build 20117 from `5825a84`, including the new built-in Sparkle
feed URL and model-download recovery copy. Both the app and DMG were accepted by
Apple's notarization service and stapled. Bundle identity, signing team, Sparkle
key, archive layout, and both packaged app copies passed the release validator.
The packaged executable reported 2.1.17 without launching the GUI; its dynamic
library list contained no Homebrew or `/usr/local` dependency.
- DMG SHA-256: `b8b9d0abecd86a73169ded8941b7c1979bd22d7fc838cc7b9e8696f15570bcc8`.
- Sparkle ZIP SHA-256: `b773685fba2fb105c91eb30a4a8434003bcba300bece837149b3f42a5fcf17ce`.
- The ZIP's Ed25519 signature was independently verified against the public key
inside its app. The custom-domain DMG, ZIP, and latest-DMG pointer matched the
prepared files byte-for-byte after publication. Both feed endpoints returned
the identical 2.1.17 appcast using a Sparkle user agent.
- The GitHub `app-v2.1.17` release is public and its DMG has the same SHA-256.
Homebrew's cask is pinned to that version and checksum; its style check passed.
- A clean headless Chromium session blocked all `*.r2.dev` requests, clicked the
live site's primary download, and verified the complete DMG's checksum. With
the custom download host also blocked, clicking the GitHub alternative still
downloaded the identical DMG. This proves independent browser download paths,
not a particular enterprise's gateway behavior.
- Live desktop and mobile renders showed 2.1.17, requirements, and the alternate
link without horizontal overflow. Curl, Homebrew, Sparkle, Python, and browser
user-agent probes received direct 206 responses for ranged downloads during
the hostname migration.
- The mirror helper was also run against an intentionally different local DMG
for an existing release. It rejected the mismatch before publishing or
replacing the GitHub asset.
- Final debug and release suites each passed 457 tests with 10 opt-in tests
ignored, plus all 12 keyboard-layout child processes per profile. Strict
all-target/all-feature Clippy passed in both profiles. Formatting, app identity
guards, shell syntax, diff checks, and the site's production build passed.
No native in-place Sparkle installation, new model download, microphone capture,
or Linux binary publication was performed in this release verification.