v0.1.12: one-click self-update with SHA-256 verify + on-exit swap

User clicks "Install update" in the version banner → plugin downloads
the new DLL, verifies SHA-256, stages a .new file next to the loaded
one, and spawns a hidden PowerShell helper that swaps the file once
ACT exits. User effort: one click + restart ACT.

──────────────────────────────────────────────────────────────────
Why this design — the constraint that shapes everything else:

Windows holds an exclusive lock on a loaded .NET DLL for the process
lifetime. The plugin can't overwrite its own DLL from inside ACT.
Workaround is "write to <dll>.new, then atomic-rename once the
process exits". The rename has to be done by something OTHER than
the plugin (because the plugin dies with ACT), so we spawn a
detached PowerShell job that Wait-Process'es on ACT's PID and does
the Move-Item once it returns.
──────────────────────────────────────────────────────────────────

New pieces:

  * src/Core/UpdateChecker.cs — ParseLatestDllAsset extracts the
    browser_download_url + digest from the GH release feed. Strips
    the "sha256:" prefix, returns ("","") on any missing piece.
  * src/Core/UpdateStatus.cs — UpdateCheckResult gains LatestDllUrl
    + LatestDllSha256. Empty digest = installer refuses to stage,
    user falls back to browser.
  * src/Core/PluginUpdater.cs — pure download + verify. Refuses
    without a digest, on size overflow (10 MB cap vs ~76 KB DLL),
    on any hash mismatch. Constant-time hex compare.
  * src/UpdateInstaller.cs — UI-side staging. Writes <dll>.new,
    drops EQ2Lexicon.ACTPlugin.UPDATE_READ_ME.txt with manual
    recovery steps, spawns the hidden PowerShell helper. If the
    helper spawn fails (no PowerShell, restricted exec policy, AV
    blocking child procs) the staged file + readme are still there
    so the user can complete the swap by hand.

UI changes (SettingsPanel):

  * Version banner now has TWO buttons: "Install update" (primary)
    + "Download in browser" (secondary). Install only shown when
    we have both URL and digest; Download always available as the
    fallback for any failure case.
  * New italic status line below the buttons shows
    "Downloading…" → "Verified. Staging…" → "Update staged. Close
    and reopen ACT to apply" — or a clear error.
  * Successful stage disables both buttons so the user can't
    re-stage in the same session.

Plugin.BeginAutoUpdateAsync orchestrates the pipeline. All
exceptions caught and surfaced via SetUpdateInstallStatus —
clicking Install must never crash ACT or leave the UI in a
half-disabled state.

Tests: 10 new PluginUpdaterTests pinning the verify branch
(happy path, hash mismatch, no-digest refusal, oversized
rejection, fetcher exceptions, case-insensitive hash compare).
5 new UpdateChecker tests for ParseLatestDllAsset (real GH
shape, draft skip, non-DLL asset skip, missing digest, case-
insensitive prefix). Total 174/174.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: VortexUK

CLAUDE.md

@@ -35,7 +35,9 @@ The split also unlocks GitHub Actions CI: the workflow at `.github/workflows/ci.
 | `src/Core/Snapshots.cs` | Plain DTOs (`EncounterSnapshot`, `CombatantSnapshot`, `DamageTypeAggregate`, `AttackTypeSnapshot`) that mirror the slice of ACT's data model the payload builder reads. |
 | `src/Core/PluginConfig.cs` | User settings persisted as XML. `Load(path)` and `Save(path)` take the path from the caller (resolved in `Plugin.cs` via `ActHelpers.GetConfigPath()`). API token is DPAPI-encrypted on disk (current-user scope) with a `DPAPI:` prefix; legacy plaintext from v0.1.0–v0.1.4 still loads. |
 | `src/Core/UploadClient.cs` | `HttpClient` wrapper. `TestConnectionAsync` (GET `/api/auth/whoami`), `UploadEncounterAsync` (POST `/api/parses/ingest`). `ValidateServerUrl` rejects non-https except `localhost`/`127.0.0.1`/`[::1]`. Adds `X-Lexicon-Signature` HMAC header to every upload (see PayloadSigner) and blocks uploads when `UpdateStatus.UploadBlocked == true`. |
-| `src/Core/UpdateChecker.cs` | GitHub-releases-feed fetcher + pure version-comparison logic. `Compute(currentVersion, releasedVersions)` returns an `UpdateCheckResult` with `Current`/`SlightlyStale`/`TooOld`/`DevBuild`/`Unknown`. Threshold = `StaleThresholdVersions` (2) — older than that blocks uploads. Failure modes (network down, GH 5xx, rate-limit) all collapse to `Unknown` so the gate fails OPEN. |
+| `src/Core/UpdateChecker.cs` | GitHub-releases-feed fetcher + pure version-comparison logic. `Compute(currentVersion, releasedVersions)` returns an `UpdateCheckResult` with `Current`/`SlightlyStale`/`TooOld`/`DevBuild`/`Unknown`. Threshold = `StaleThresholdVersions` (2) — older than that blocks uploads. Failure modes (network down, GH 5xx, rate-limit) all collapse to `Unknown` so the gate fails OPEN. `ParseLatestDllAsset` extracts the latest-release DLL URL + SHA-256 digest for the self-update flow. |
+| `src/Core/PluginUpdater.cs` | Download + SHA-256 verify for the self-update flow (v0.1.12+). Pure (`IDllAssetFetcher` injects HTTP). Constant-time hash compare. Refuses to install without a digest, on size overflow (10 MB cap vs ~76 KB DLL), and on any hash mismatch. |
+| `src/UpdateInstaller.cs` | UI-side staging for the self-update flow. Writes `<dll>.new` next to the running DLL, drops a manual-recovery readme, spawns a hidden PowerShell `Wait-Process -Id <act_pid>; Move-Item -Force *.new *.dll` that swaps the file once ACT exits. Recovery readme covers the case where the helper script gets killed by AV. |
 | `src/Core/PayloadSigner.cs` | HMAC-SHA256 of the upload body keyed by the user's API token. See "Payload integrity" below for the threat model and what this does/doesn't defend. |
 | `tests/EQ2Lexicon.ACTPlugin.Tests/` | xUnit project, `net48`. 72 tests. References Core only (UI types aren't testable without ACT). Covers PayloadBuilder, PluginConfig (incl. DPAPI roundtrip), UploadClient (incl. URL validator). Coverage collected via `coverlet.collector`. |
 
@@ -144,6 +146,21 @@ Failure modes (offline, GitHub 5xx, rate-limit, malformed JSON) all collapse to
 
 No caching of the GitHub response — request volume is at most a handful per user per day, well under the unauthenticated 60/h/IP limit, and re-fetching on every ACT start means a user who just installed an update sees the banner clear instantly after restarting ACT.
 
+## Self-update (v0.1.12+)
+
+The version banner gets a primary "Install update" button (alongside the existing "Download in browser" secondary fallback) when both an asset URL and a SHA-256 digest were resolved from the GitHub release feed. Click flow:
+
+1. **Download** the DLL bytes from `LatestDllUrl` via HttpClient. Capped at 10 MB; refused on any non-2xx response. Bytes held in memory only.
+2. **Verify** SHA-256 against `LatestDllSha256` (pulled from the release feed's `digest` field) via constant-time compare. Mismatch → refuse, surface error, don't touch disk. **No digest** → also refuse — shipping unverified code into a running .NET process is unacceptable, the user gets nudged to the browser fallback.
+3. **Stage** by writing the bytes to `EQ2Lexicon.ACTPlugin.dll.new` next to the loaded DLL. (Windows allows creating this file; it does NOT allow overwriting the loaded `.dll` itself — that's why we don't just overwrite.)
+4. **Drop a recovery readme** (`EQ2Lexicon.ACTPlugin.UPDATE_READ_ME.txt`) in the same folder with manual swap instructions, in case the helper script fails.
+5. **Spawn a hidden PowerShell helper**: `Wait-Process -Id <act_pid>; Move-Item -Force *.new *.dll`. Sleeps in the background until ACT exits, then atomic-renames. User sees nothing.
+6. **UI message**: "Update staged. Close and reopen ACT to apply — the swap happens automatically." Buttons disable.
+
+User effort: one click + restart ACT whenever convenient. The Railway URL fallback covers users who don't restart for days — the v0.1.12 staging sits there, the v0.1.11 keeps uploading via parses.eq2lexicon.com (same Railway service), no breakage.
+
+**What it doesn't try to do**: relaunch ACT itself. Spawning a "wait then re-launch host" helper from a plugin is the kind of behaviour that gets flagged by AV. The user restart is small friction; the auto-relaunch isn't worth the suspicion budget.
+
 ## Language assumptions (English-only EQ2)
 
 The plugin assumes English ACT EQ2-parser output throughout. ACT does have German + French EQ2 parser plugins on record, but as of 2026 there are **no active non-English EQ2 servers** — the EU/JP servers (Storms = French, Valor = German, Sebilis = Japanese) were consolidated into the English-only Thurgadin server in 2016, and the current TLE servers (Varsoon, Kaladim) are English-only. So this assumption is safe today; documenting it so future-you doesn't have to re-research it.

src/Core/EQ2Lexicon.ACTPlugin.Core.csproj

@@ -18,7 +18,7 @@
       Build metadata is mirrored from the UI csproj so this assembly's
       version tracks the user-facing plugin version.
     -->
-    <Version>0.1.11</Version>
+    <Version>0.1.12</Version>
     <Company>EQ2 Lexicon</Company>
     <Product>EQ2 Lexicon Uploader (Core)</Product>
     <Description>Pure payload / config / HTTP layer shared by EQ2Lexicon.ACTPlugin.</Description>

src/Core/PluginUpdater.cs

@@ -0,0 +1,182 @@
+using System;
+using System.Net.Http;
+using System.Security.Cryptography;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace EQ2Lexicon.ACTPlugin
+{
+    /// <summary>
+    /// Outcome of a download + verify attempt. Plain DTO so Plugin and
+    /// the UI can pattern-match without a sea of out-parameters.
+    /// </summary>
+    public class DownloadResult
+    {
+        /// <summary>True iff bytes were fetched AND hash matched.</summary>
+        public bool Success { get; set; }
+
+        /// <summary>The verified DLL bytes when <see cref="Success"/> is true; null otherwise.</summary>
+        public byte[]? DllBytes { get; set; }
+
+        /// <summary>Short user-facing message — what to show in the SettingsPanel.</summary>
+        public string Message { get; set; } = "";
+    }
+
+    /// <summary>
+    /// Abstracts the binary fetch so unit tests can supply canned bytes
+    /// without going to the network. Symmetrical with
+    /// <see cref="IReleaseFeedFetcher"/>.
+    /// </summary>
+    public interface IDllAssetFetcher
+    {
+        Task<byte[]> FetchAsync(string url);
+    }
+
+    /// <summary>
+    /// Production fetcher — wraps HttpClient and applies the same
+    /// User-Agent contract the rest of the plugin uses.
+    /// </summary>
+    public class HttpDllAssetFetcher : IDllAssetFetcher
+    {
+        private readonly HttpClient _http;
+        private readonly string _userAgent;
+
+        public HttpDllAssetFetcher(HttpClient http, string userAgent)
+        {
+            _http = http;
+            _userAgent = string.IsNullOrWhiteSpace(userAgent) ? "EQ2LexiconACTPlugin" : userAgent;
+        }
+
+        public async Task<byte[]> FetchAsync(string url)
+        {
+            using (var req = new HttpRequestMessage(HttpMethod.Get, url))
+            {
+                req.Headers.UserAgent.ParseAdd(_userAgent);
+                using (var resp = await _http.SendAsync(req).ConfigureAwait(false))
+                {
+                    if (!resp.IsSuccessStatusCode)
+                    {
+                        throw new HttpRequestException(
+                            $"HTTP {(int)resp.StatusCode} {resp.StatusCode} when fetching {url}");
+                    }
+                    return await resp.Content.ReadAsByteArrayAsync().ConfigureAwait(false);
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    /// Pure download + verify orchestration for the self-update flow.
+    /// Lives in Core because the verification logic (SHA-256, constant-
+    /// time compare, size cap) is exactly the kind of thing that
+    /// silently regresses without tests.
+    ///
+    /// The actual on-disk staging happens in <c>UpdateInstaller</c>
+    /// (UI assembly — needs Process.Start, etc.) because Core can't
+    /// know where the running DLL is or how to spawn the swap helper.
+    /// </summary>
+    public static class PluginUpdater
+    {
+        /// <summary>
+        /// Hard cap on the downloaded DLL size. Real DLL is ~76 KB; a
+        /// 10 MB ceiling absorbs years of growth and still rejects a
+        /// hostile substitution that would balloon the file (e.g. a
+        /// CDN-cached different binary).
+        /// </summary>
+        public const int MaxDllBytes = 10 * 1024 * 1024;
+
+        /// <summary>
+        /// Download bytes from <paramref name="url"/>, compute SHA-256,
+        /// constant-time-compare against <paramref name="expectedSha256Hex"/>.
+        /// Returns a <see cref="DownloadResult"/> — caller decides
+        /// what to do with success/failure (almost certainly: stage on
+        /// disk or display the error message).
+        ///
+        /// Hard rule: <paramref name="expectedSha256Hex"/> must be
+        /// non-empty (64 lowercase hex chars). We refuse to download
+        /// without a digest to compare against — shipping unverified
+        /// code into the user's ACT process would be an own-goal.
+        /// </summary>
+        public static async Task<DownloadResult> DownloadAndVerifyAsync(
+            string url,
+            string expectedSha256Hex,
+            IDllAssetFetcher fetcher)
+        {
+            if (string.IsNullOrWhiteSpace(url))
+                return new DownloadResult { Message = "No download URL available." };
+            if (string.IsNullOrWhiteSpace(expectedSha256Hex))
+                return new DownloadResult { Message = "No SHA-256 digest published for this release — refusing to auto-install." };
+            if (fetcher == null)
+                return new DownloadResult { Message = "Internal: fetcher missing." };
+
+            byte[] bytes;
+            try
+            {
+                bytes = await fetcher.FetchAsync(url).ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                return new DownloadResult { Message = "Download failed: " + ex.Message };
+            }
+
+            if (bytes == null || bytes.Length == 0)
+                return new DownloadResult { Message = "Download returned no bytes." };
+            if (bytes.Length > MaxDllBytes)
+                return new DownloadResult
+                {
+                    Message = $"Downloaded file too large ({bytes.Length} bytes; cap is {MaxDllBytes}).",
+                };
+
+            string actualHex;
+            using (var sha = SHA256.Create())
+            {
+                actualHex = ToLowerHex(sha.ComputeHash(bytes));
+            }
+            var expected = expectedSha256Hex.Trim().ToLowerInvariant();
+            if (!ConstantTimeEquals(actualHex, expected))
+            {
+                return new DownloadResult
+                {
+                    Message = $"SHA-256 mismatch (expected {expected.Substring(0, 12)}…, got {actualHex.Substring(0, 12)}…). " +
+                              "Refusing to install a tampered or corrupt download.",
+                };
+            }
+
+            return new DownloadResult
+            {
+                Success = true,
+                DllBytes = bytes,
+                Message = $"Downloaded {bytes.Length} bytes, SHA-256 verified.",
+            };
+        }
+
+        private static string ToLowerHex(byte[] bytes)
+        {
+            var sb = new StringBuilder(bytes.Length * 2);
+            for (int i = 0; i < bytes.Length; i++)
+            {
+                sb.Append(bytes[i].ToString("x2"));
+            }
+            return sb.ToString();
+        }
+
+        /// <summary>
+        /// Length-then-bitwise compare. Length difference short-circuits
+        /// (and is itself not secret — hashes are fixed-width) but the
+        /// per-char compare never short-circuits, so timing doesn't leak
+        /// which prefix matched. Probably overkill for "did the download
+        /// get tampered with" but free and correct.
+        /// </summary>
+        private static bool ConstantTimeEquals(string a, string b)
+        {
+            if (a == null || b == null) return false;
+            if (a.Length != b.Length) return false;
+            int diff = 0;
+            for (int i = 0; i < a.Length; i++)
+            {
+                diff |= a[i] ^ b[i];
+            }
+            return diff == 0;
+        }
+    }
+}

src/Core/UpdateChecker.cs

@@ -139,6 +139,111 @@ public static List<Version> ParseReleaseVersions(string json)
             return result;
         }
 
+        /// <summary>
+        /// Walk the GitHub release feed for the FIRST non-draft release
+        /// (newest published) and pull out the URL + SHA-256 digest of
+        /// the EQ2Lexicon.ACTPlugin.dll asset attached to it.
+        ///
+        /// Used by the self-update flow (v0.1.12+) — the URL feeds
+        /// HttpClient.GetByteArrayAsync, the digest feeds
+        /// PluginUpdater's hash verification.
+        ///
+        /// Returns empty strings when:
+        ///   * JSON is empty / malformed
+        ///   * no non-draft release exists
+        ///   * the release has no asset matching "*.ACTPlugin.dll"
+        ///   * the asset has no `digest` field (very recent GitHub
+        ///     releases occasionally surface before the digest backfill
+        ///     completes) — the installer must refuse to auto-stage
+        ///     in that case rather than ship an unverified binary
+        ///
+        /// Parser is a small hand-rolled walk over the JSON shape rather
+        /// than full deserialisation, matching the convention used by
+        /// ParseReleaseVersions. The shape we depend on:
+        ///   [ { "tag_name": "v0.1.12", "draft": false,
+        ///       "assets": [ { "name": "...dll",
+        ///                     "browser_download_url": "https://...",
+        ///                     "digest": "sha256:abc..." } ] } ]
+        /// </summary>
+        public static (string Url, string Sha256Hex) ParseLatestDllAsset(string json)
+        {
+            if (string.IsNullOrEmpty(json)) return ("", "");
+
+            // Find the first release block — defined as the first
+            // `"tag_name"` whose corresponding `"draft"` is false (or
+            // absent). The block runs until the matching closing brace
+            // at the top object level. We approximate that as "the
+            // next `"tag_name"`" — assets always appear before the
+            // next release object since GH returns assets inline.
+            int idx = 0;
+            while (idx < json.Length)
+            {
+                int tagAt = json.IndexOf("\"tag_name\"", idx, StringComparison.Ordinal);
+                if (tagAt < 0) return ("", "");
+                // Block end = the next "tag_name" (next release) or end of JSON.
+                int nextTagAt = json.IndexOf("\"tag_name\"", tagAt + 1, StringComparison.Ordinal);
+                int blockEnd = nextTagAt < 0 ? json.Length : nextTagAt;
+                var block = json.Substring(tagAt, blockEnd - tagAt);
+                idx = blockEnd;
+
+                // Skip drafts.
+                if (LooksLikeDraft(block)) continue;
+
+                // Find the assets array and within it the first asset
+                // whose `"name"` ends with ".dll" (we ship exactly one
+                // DLL today; matching by suffix accommodates future
+                // multi-asset releases).
+                var (url, sha) = FindDllAsset(block);
+                return (url, sha);
+            }
+            return ("", "");
+        }
+
+        private static bool LooksLikeDraft(string block)
+        {
+            int draftAt = block.IndexOf("\"draft\"", StringComparison.Ordinal);
+            if (draftAt < 0) return false;
+            int colon = block.IndexOf(':', draftAt);
+            if (colon < 0) return false;
+            var after = block.Substring(colon + 1).TrimStart();
+            return after.StartsWith("true", StringComparison.OrdinalIgnoreCase);
+        }
+
+        private static (string Url, string Sha256Hex) FindDllAsset(string releaseBlock)
+        {
+            // Walk every `"name"` field in the block; for each one ending
+            // ".dll", pluck the adjacent `browser_download_url` and
+            // `digest`. GitHub orders the JSON keys consistently inside
+            // each asset object so the adjacent search is stable, but we
+            // search both directions defensively.
+            int idx = 0;
+            while (idx < releaseBlock.Length)
+            {
+                int nameAt = releaseBlock.IndexOf("\"name\"", idx, StringComparison.Ordinal);
+                if (nameAt < 0) return ("", "");
+                var nameVal = UploadClient.ExtractJsonString(releaseBlock.Substring(nameAt), "name") ?? "";
+                idx = nameAt + "\"name\"".Length;
+
+                if (!nameVal.EndsWith(".dll", StringComparison.OrdinalIgnoreCase)) continue;
+
+                // Found a DLL asset. The browser_download_url + digest
+                // for THIS asset are within the next ~1KB of JSON.
+                int probeEnd = Math.Min(releaseBlock.Length, idx + 1500);
+                var probe = releaseBlock.Substring(idx, probeEnd - idx);
+                var url = UploadClient.ExtractJsonString(probe, "browser_download_url") ?? "";
+                var digest = UploadClient.ExtractJsonString(probe, "digest") ?? "";
+
+                // Digest is shaped "sha256:HEX..." — strip the algo prefix.
+                var sha = "";
+                if (digest.StartsWith("sha256:", StringComparison.OrdinalIgnoreCase))
+                {
+                    sha = digest.Substring("sha256:".Length).Trim().ToLowerInvariant();
+                }
+                return (url, sha);
+            }
+            return ("", "");
+        }
+
         /// <summary>
         /// Convert "v0.1.8" or "0.1.8" (with optional "-rc1" suffix) into
         /// a <see cref="Version"/>. Returns null on anything we can't make
@@ -256,7 +361,17 @@ public static async Task<UpdateCheckResult> CheckAsync(Version currentVersion, I
                 var json = await fetcher.FetchAsync().ConfigureAwait(false);
                 if (string.IsNullOrEmpty(json)) return result;
                 var versions = ParseReleaseVersions(json);
-                return Compute(currentVersion ?? new Version(0, 0, 0), versions);
+                var status = Compute(currentVersion ?? new Version(0, 0, 0), versions);
+
+                // Latest-release asset info for the self-update flow.
+                // Best-effort: missing/malformed asset metadata leaves
+                // both strings empty and the installer falls back to
+                // opening the browser instead of staging.
+                var (url, sha) = ParseLatestDllAsset(json);
+                status.LatestDllUrl = url;
+                status.LatestDllSha256 = sha;
+
+                return status;
             }
             catch
             {