theseus/docs/ADDON-UPDATES.md

# Signed add-on updates

An add-on can be updated at runtime, without waiting for the next Theseus
release, if its `addon.json` declares an `updateURL`. The client polls
that URL, verifies an Ed25519 signature against a hardcoded set of
operator pubkeys, stages the new copy under
`<userData>/addons-updates-staged/<id>-<version>/`, and promotes it on the
next launch — reusing the same backup-then-swap logic as
`seedBundledAddons`, so any local edits the user made survive as
`<userData>/addons-backups/<id>-<oldver>-<timestamp>/`.

## Client boot flow

```
initAddons()
├── promoteStagedUpdates()      # staged copy wins if newer than installed
├── seedBundledAddons()         # bundle wins if newer than what's on disk
└── AddonHost.discoverAndActivate()
```

Then, 30 s after boot, `checkAndStageUpdates()` fetches every installed
add-on's `updateURL`, verifies its signed manifest, and lands any newer
signed version in the staged dir for the NEXT launch to promote.

## Publishing an update

### One-time: generate the operator keypair

```
node scripts/generate-update-keypair.mjs "$USERPROFILE/.silentmode/ops"
```

The private key stays there. Copy the printed pubkey hex into
`addon-update-pubkeys.js` and ship a Theseus release that bakes it in;
until you do, `checkAndStageUpdates` skips silently and the client makes
no outbound requests.

### Every update

```
node scripts/sign-addon-update.mjs \
    bundled-addons/screenshot \
    https://addons.silentmode.st/screenshot \
    "$USERPROFILE/.silentmode/ops/addon-update-key.pem"
```

Produces:
- `out/screenshot-<version>.tar.gz` — upload to `<base-url>/<id>-<version>.tar.gz`
- `out/screenshot-<version>.entry.json` — prepend to your live `updates.json`

Then:

```
scp out/screenshot-*.tar.gz silentmode:/opt/silent-mode/site/addons/screenshot/
scp updates.json           silentmode:/opt/silent-mode/site/addons/screenshot/
```

The Sia autosync timer picks up `/opt/silent-mode/site/` on its usual
5-minute cadence, so both mirrors update together (see
`shipping-mirrors` for background).

## `updates.json` schema

```json
{
  "addons": [
    {
      "version": "0.3.0",
      "url": "https://addons.silentmode.st/screenshot/screenshot-0.3.0.tar.gz",
      "sha256": "hex",
      "sig": "base64"
    },
    { "version": "0.2.1", "url": "…", "sha256": "hex", "sig": "base64" }
  ]
}
```

Order does not matter — the client picks the highest `version` greater
than what's installed. Keep old entries around only if you want to
support rollback via a manual downgrade tool; the client never picks
anything older than the installed copy.

## Signature domain

```
message  = "silentmode.addon-update-v1|<id>|<version>|<sha256>"
signature = Ed25519_sign(operator_privkey, message)
```

Domain-separated so the operator key can't be tricked into signing
something else (a website login token, a wallet message) that happens
to have the right shape.

## Rotating the operator key

1. `generate-update-keypair.mjs` a new one.
2. Publish next `updates.json` entries signed by BOTH old and new key
   (the client accepts a signature from any pubkey in `PUBKEYS_HEX`).
3. Ship a Theseus release that adds the new pubkey.
4. After enough time has passed for existing installs to upgrade, ship
   a follow-up release removing the old pubkey. Stop signing with it.

## Threat model

- **Compromised operator key** = update-tunnel compromise. Attackers can
  push a malicious add-on to every install that has the endpoint
  reachable. Mitigations under consideration:
  - multi-sig: require signatures from N of M operator keys (not
    implemented — would extend the `sig` field to an array)
  - on-BCNR pubkey publication: pin the current pubkey set to a BNS
    record so rotation is auditable (roadmap)
- **Manifest downgrade** — a malicious mirror serves an older signed
  entry. The client refuses versions ≤ what's installed, so a rollback
  attack cannot land an older signed payload as if it were an update.
  A user who wipes `<userData>/addons/` and boots against a hostile
  mirror could receive a stale-but-signed copy; the bundled fallback
  from the Theseus release will beat it via `seedBundledAddons` unless
  the bundle is older still.
- **Path traversal in tarball** — `tar` refuses `..` entries by default;
  we do not pass `-P`. Extracted manifest's `id` + `version` are
  re-checked against the signed values before staging.
- **Empty pubkey list** = feature off. No outbound requests, no updates,
  no attack surface. Safe default for fresh builds.

## Files

- `addon-updater.js` — client-side fetch, verify, stage, promote.
- `addon-update-pubkeys.js` — hardcoded pubkey array (edit and rebuild
  to rotate).
- `scripts/generate-update-keypair.mjs` — one-time keygen.
- `scripts/sign-addon-update.mjs` — package + sign an update.