# Nexus Update System

**Status:** POC 1 — check only  
**Channel URL:** https://nexus.ninjakernen.info/downloads/

---

## Overview

Ninja Nexus clients receive updates through a **public HTTPS update channel** hosted on Coolify. POC 1 implements manifest fetch and version comparison only — no download or install.

```
Client (Nexus Shell)
    │
    ▼ GET /downloads/latest.json  (no-cache)
UpdateService
    │
    ├─ Parse manifest
    ├─ Compare build + version
    └─ Show status in UI (no install)
```

---

## Update channel layout

```
/downloads/
  latest.json              ← current release manifest (no-cache)
  sha256.txt               ← SHA256 of root nexus-shell-poc.zip
  nexus-shell-poc.zip      ← copy of latest release (immutable cache)
  releases/
    {version}/
      manifest.json
      sha256.txt
      nexus-shell-poc.zip
```

Deploy config: [deployment/coolify/nexus-downloads/](../deployment/coolify/nexus-downloads/)

---

## Manifest standard

| Field | Purpose |
|-------|---------|
| `product` | Product name |
| `channel` | `poc`, `beta`, `stable` |
| `version` | Semver + channel tag e.g. `0.1.0-poc1` |
| `build` | Monotonic integer for comparison |
| `publishedAt` | ISO 8601 UTC |
| `minimumSupportedVersion` | Clients below this may be forced to update (future) |
| `packageUrl` | HTTPS URL to versioned ZIP |
| `sha256Url` | HTTPS URL to checksum file |
| `sha256` | SHA256 of package |
| `sizeBytes` | Package size |
| `releaseNotes` | Array of strings |
| `requiresRuntime` | Prerequisites |
| `requiresSafePoc` | Must run with `--safe-poc` |
| `mandatory` | Force update flag (future) |
| `rollbackVersion` | Previous version if rollback needed |
| `signature` | `null` in POC; Authenticode/minisign later |

---

## POC phases

| Phase | Client capability |
|-------|-------------------|
| **POC 1** | Check manifest, show status, info panel |
| **POC 2** | Download ZIP + SHA256 verify |
| **POC 3** | Install via safe updater service |
| **Production** | Signature verify, staged rollout, rollback |

---

## Security model (future)

### SHA256 verification (POC 2+)

1. Download `packageUrl`
2. Compute SHA256
3. Compare with manifest `sha256` and `sha256Url` file

### Code signing (later)

- Sign packages with org certificate
- Manifest `signature` field contains signature over manifest + hash
- Client trusts pinned org public key before install

### Rollback

- `rollbackVersion` points to last known-good release folder
- Safe updater keeps previous package in `%ProgramData%\NinjaNexus\updates\backup\`
- Recovery doc: [security/NEXUS_LOCKDOWN_MODE.md](../security/NEXUS_LOCKDOWN_MODE.md)

### Staged rollout

- Channel tags: `poc` → `beta` → `stable`
- Future: manifest includes `rolloutPercent` or separate canary URL

### Mandatory updates

- `mandatory: true` blocks Shell usage until update (production only)
- POC 1 ignores mandatory flag

### Delta updates (later)

- Full ZIP only for POC
- Binary deltas or MSIX differential updates in production

### Safe updater service (later)

- Windows service or elevated helper
- Stops Shell → extracts ZIP → verifies → restarts Shell
- **Installer lock** prevents user tampering during update

### Recovery if update fails

1. Updater restores backup folder
2. Master Developer recovery via Developer Console
3. Manual reinstall from `releases/{version}/`

---

## Client implementation (POC 1)

| Component | Role |
|-----------|------|
| `UpdateService` | Fetch + parse + compare |
| `config/version.poc.json` | Installed version/build |
| `appsettings.json` → `Update:ManifestUrl` | Channel endpoint |
| Settings + top bar | Status display |
| `UpdateInfoWindow` | Details only — no install |

---

## Publish flow

```powershell
.\scripts\nexus-laptop-poc\build-package.ps1
.\scripts\nexus-laptop-poc\publish-coolify.ps1 -DryRun   # local only
# After Jacob approval:
$env:NEXUS_COOLIFY_APP_UUID = '<uuid>'
.\scripts\nexus-laptop-poc\publish-coolify.ps1
```

Evidence: `docs/evidence/nexus-update-channel/`

---

## Offline behavior

If network fails, UI shows **"Update channel unavailable"** — Shell continues normally. Lockdown does not depend on internet.

---

## Related docs

- [NEXUS_LOCKDOWN_MODE.md](../security/NEXUS_LOCKDOWN_MODE.md)
- [deployment/coolify/nexus-downloads/README.md](../deployment/coolify/nexus-downloads/README.md)
