Commite54d8d24Recorded24 Sep 2026Repositorysigil

Document registry-backed upgrades for 0.22.7

Changed
 RELEASES.md             | 17 +++++++++++++++++
 docs/getting-started.md |  4 +++-
 docs/reference/cli.md   | 24 ++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 1 deletion(-)
Diff
RELEASES.mdmodified
@@ -63,6 +63,23 @@ steps back up on its own, and a remembered rate is ignored when the buffering it
63
measured under has changed. `rate-ladder-report` gives the readout line, such as `48000/24000 BY
64
LADDER@20.2S`.
65
+66
### Upgrades come from the registry, verified end to end
+67
+68
Until now an upgrade trusted whatever Codeberg's release file said, protected only by HTTPS.
+69
Now `sigil` reads the registry's signed release list and downloads the binary by its content
+70
hash. It checks the chain itself, with no `minisign` program needed: the registry's key list
+71
must be signed by the root key built into `sigil`, the release list by a toolchain key from
+72
that list, and the binary must have the hash and size the list gives. A release list older
+73
than one `sigil` has already seen is refused, so a stale or replayed copy cannot roll you back.
+74
+75
If the registry can't be reached, `sigil` says `Registry unavailable, using Codeberg.` and
+76
upgrades from Codeberg as before; if only the binary is missing, the Codeberg copy must still
+77
match the hash in the registry's signed list. If the registry answers but what it serves fails a check,
+78
`sigil` says `Verification failed; nothing was installed.`, gives the reason, and stops rather
+79
than falling back. `sigil cli use` for a release older than the registry still downloads it
+80
from Codeberg, with a note. Set `SIGIL_REGISTRY` to use a mirror; the keys that verify it stay
+81
the same.
+82
83
## 0.22.6 (2026-09-24)
84
85
A reliability release for scripts, plus the groundwork for `sigil env`. Two defects let a
docs/getting-started.mdmodified
@@ -99,7 +99,9 @@ Check for and download new versions:
99
sigil cli upgrade
100
```
101
−102
This downloads the latest release but doesn't activate it automatically. To switch:
+102
This downloads the latest release from the Sigil package registry, after checking its
+103
signatures and the binary's hash, but doesn't activate it automatically. If the registry is
+104
unreachable it says so and downloads from Codeberg instead. To switch:
105
106
```bash
107
sigil cli use 0.2.0
docs/reference/cli.mdmodified
@@ -158,6 +158,29 @@ sigil cli prune # Remove old versions
158
sigil cli env # Print shell configuration
159
```
160
+161
`upgrade` and `use` read the release list from the Sigil package registry
+162
(`https://pkg.usesigil.org`, or the URL in `SIGIL_REGISTRY`) and download the binary by its
+163
content hash. Before anything is installed, `sigil` checks the whole chain itself: the
+164
registry's key list must be signed by the root key built into this `sigil`, the release list
+165
must be signed by a toolchain key from that list, and the downloaded binary must have the
+166
sha256 and size the release list gives. No `minisign` program is needed.
+167
+168
- If the registry cannot be reached, or does not have the release list, `sigil` prints
+169
`Registry unavailable, using Codeberg.` and uses Codeberg's release metadata instead, which
+170
is checked by HTTPS and its sha256 list. If the registry's signed release list did arrive but
+171
the binary itself was not served, the Codeberg download must have exactly the sha256 and size
+172
the signed list gives.
+173
- If the registry answers but what it serves fails a check (a bad signature, a key without the
+174
right role, a release list older than one already seen, or a binary with the wrong hash),
+175
`sigil` prints `Verification failed; nothing was installed.` with the reason, and stops. It
+176
does not fall back to Codeberg in that case.
+177
- `sigil cli use <ver>` for a release the registry does not carry (releases from before the
+178
registry) prints a note and downloads it from Codeberg.
+179
+180
`sigil` remembers the newest sequence numbers it has verified, per root key, in
+181
`$SIGIL_HOME/registry-seen-seq`, so a mirror cannot serve an older release list either.
+182
Deleting the file resets that memory.
+183
184
### `sigil changes`
185
186
Release management:
@@ -184,6 +207,7 @@ sigil changes changelog # Generate changelog
207
|----------|-------------|---------|
208
| `SIGIL_PATH` | Library search path (colon-separated) | Current directory |
209
| `SIGIL_HOME` | Sigil installation and global dependency-state directory | `~/.sigil` |
+210
| `SIGIL_REGISTRY` | Package registry base URL, for packages and for `sigil cli upgrade`/`use`. A mirror changes where bytes come from, never which keys verify them | `https://pkg.usesigil.org` |
211
| `NO_COLOR` | Disable colored output | Not set |
212
| `SIGIL_DEPS_TRACE_DROPPED` | Set to `1` to trace dependency constraints the resolver discarded | Not set |
213