Add CcuBackupVerifier for HomeMatic CCU backup validation and integrate with FirmwareBackupClient. Add tests for backup verification logic.

Author: darthsharp

.serena/project.yml

@@ -3,22 +3,27 @@ project_name: "HomeMatic"
 
 
 # list of languages for which language servers are started; choose from:
-#   al                  bash                clojure             cpp                 csharp
-#   csharp_omnisharp    dart                elixir              elm                 erlang
-#   fortran             fsharp              go                  groovy              haskell
-#   haxe                java                julia               kotlin              lua
-#   markdown
-#   matlab              nix                 pascal              perl                php
-#   php_phpactor        powershell          python              python_jedi         r
-#   rego                ruby                ruby_solargraph     rust                scala
-#   swift               terraform           toml                typescript          typescript_vts
-#   vue                 yaml                zig
+#   al                  angular             ansible             bash                clojure
+#   cpp                 cpp_ccls            crystal             csharp              csharp_omnisharp
+#   dart                elixir              elm                 erlang              fortran
+#   fsharp              go                  groovy              haskell             haxe
+#   hlsl                html                java                json                julia
+#   kotlin              lean4               lua                 luau                markdown
+#   matlab              msl                 nix                 ocaml               pascal
+#   perl                php                 php_phpactor        powershell          python
+#   python_jedi         python_ty           r                   rego                ruby
+#   ruby_solargraph     rust                scala               scss                solidity
+#   svelte              swift               systemverilog       terraform           toml
+#   typescript          typescript_vts      vue                 yaml                zig
 #   (This list may be outdated. For the current list, see values of Language enum here:
 #   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
 #   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
 # Note:
 #   - For C, use cpp
 #   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
 #   - For Free Pascal/Lazarus, use pascal
 # Special requirements:
 #   Some languages require additional setup/installations.
@@ -66,54 +71,17 @@ read_only: false
 
 # list of tool names to exclude.
 # This extends the existing exclusions (e.g. from the global configuration)
-#
-# Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
-# execute `uv run scripts/print_tool_overview.py`.
-#
-#  * `activate_project`: Activates a project based on the project name or path.
-#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
-#  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_memory`: Delete a memory file. Should only happen if a user asks for it explicitly,
-#       for example by saying that the information retrieved from a memory file is no longer correct
-#       or no longer relevant for the project.
-#  * `edit_memory`: Replaces content matching a regular expression in a memory.
-#  * `execute_shell_command`: Executes a shell command.
-#  * `find_file`: Finds files in the given relative paths
-#  * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend
-#  * `find_symbol`: Performs a global (or local) search using the language server backend.
-#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Provides instructions Serena usage (i.e. the 'Serena Instructions Manual')
-#       for clients that do not read the initial instructions when the MCP server is connected.
-#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: List available memories. Any memory can be read using the `read_memory` tool.
-#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Read the content of a memory file. This tool should only be used if the information
-#       is relevant to the current task. You can infer whether the information
-#       is relevant from the memory file name.
-#       You should not read the same memory file multiple times in the same conversation.
-#  * `rename_memory`: Renames or moves a memory. Moving between project and global scope is supported
-#       (e.g., renaming "global/foo" to "bar" moves it from global to project scope).
-#  * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
-#       For JB, we use a separate tool.
-#  * `replace_content`: Replaces content in a file (optionally using regular expressions).
-#  * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend.
-#  * `safe_delete_symbol`:
-#  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `write_memory`: Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format.
-#       The memory name should be meaningful.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 excluded_tools: []
 
 # list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
 # This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 included_optional_tools: []
 
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
 # This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 fixed_tools: []
 
 # list of mode names to that are always to be included in the set of active modes
@@ -124,11 +92,14 @@ fixed_tools: []
 # Set this to a list of mode names to always include the respective modes for this project.
 base_modes:
 
-# list of mode names that are to be activated by default.
-# The full set of modes to be activated is base_modes + default_modes.
-# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
 # Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
 # This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
 default_modes:
 
 # initial prompt for the project. It will always be given to the LLM upon activating the project
@@ -152,3 +123,19 @@ read_only_memory_patterns: []
 # Extends the list from the global configuration, merging the two lists.
 # Example: ["_archive/.*", "_episodes/.*"]
 ignored_memory_patterns: []
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+additional_workspace_folders: []

source/CreativeCoders.HomeMatic/CreativeCoders.HomeMatic.csproj

@@ -9,6 +9,11 @@
         <PackageReference Include="Microsoft.Extensions.Http"/>
     </ItemGroup>
 
+    <ItemGroup>
+        <InternalsVisibleTo Include="CreativeCoders.HomeMatic.Tests"/>
+        <InternalsVisibleTo Include="DynamicProxyGenAssembly2"/>
+    </ItemGroup>
+
     <ItemGroup>
         <ProjectReference Include="..\CreativeCoders.HomeMatic.Core\CreativeCoders.HomeMatic.Core.csproj"/>
         <ProjectReference Include="..\CreativeCoders.HomeMatic.JsonRpc\CreativeCoders.HomeMatic.JsonRpc.csproj"/>

source/CreativeCoders.HomeMatic/FirmwareBackup/FirmwareBackupClient.cs

@@ -12,17 +12,20 @@ public sealed class FirmwareBackupClient : IFirmwareBackupClient
 {
     private readonly ICcuSessionClient _sessionClient;
     private readonly IFirmwareBackupDownloader _downloader;
+    private readonly ICcuBackupVerifier _verifier;
     private readonly FirmwareBackupOptions _options;
     private readonly IFileSystem _fileSystem;
 
     internal FirmwareBackupClient(
         ICcuSessionClient sessionClient,
         IFirmwareBackupDownloader downloader,
+        ICcuBackupVerifier verifier,
         FirmwareBackupOptions options,
         IFileSystem fileSystem)
     {
         _sessionClient = Ensure.NotNull(sessionClient);
         _downloader = Ensure.NotNull(downloader);
+        _verifier = Ensure.NotNull(verifier);
         _options = Ensure.NotNull(options);
         _fileSystem = Ensure.NotNull(fileSystem);
     }
@@ -38,11 +41,32 @@ public async Task<FirmwareBackupResult> CreateBackupAsync(CancellationToken canc
         {
             var download = await _downloader.DownloadAsync(sessionId, cancellationToken).ConfigureAwait(false);
 
+            var capacity = download.ContentLength is > 0 and <= int.MaxValue
+                ? (int)download.ContentLength.Value
+                : 0;
+            var content = new MemoryStream(capacity);
+
+            try
+            {
+                await using (var httpResources = download.HttpResources.ConfigureAwait(false))
+                {
+                    await download.Content.CopyToAsync(content, cancellationToken).ConfigureAwait(false);
+                }
+
+                content.Position = 0;
+                await _verifier.VerifyAsync(content, cancellationToken).ConfigureAwait(false);
+                content.Position = 0;
+            }
+            catch
+            {
+                await content.DisposeAsync().ConfigureAwait(false);
+                throw;
+            }
+
             return new FirmwareBackupResult(
-                download.Content,
+                content,
                 download.FileName,
                 download.ContentLength,
-                download.HttpResources,
                 new LogoutDisposable(_sessionClient, sessionId));
         }
         catch

source/CreativeCoders.HomeMatic/FirmwareBackup/FirmwareBackupClientFactory.cs

@@ -57,6 +57,8 @@ public IFirmwareBackupClient Create(FirmwareBackupOptions options)
             options.BackupCgiPath,
             options.BackupAction);
 
-        return new FirmwareBackupClient(sessionClient, downloader, options, _fileSystem);
+        var verifier = new CcuBackupVerifier();
+
+        return new FirmwareBackupClient(sessionClient, downloader, verifier, options, _fileSystem);
     }
 }

source/CreativeCoders.HomeMatic/FirmwareBackup/Internal/CcuBackupVerifier.cs

@@ -0,0 +1,135 @@
+using System.Formats.Tar;
+using System.IO.Compression;
+using CreativeCoders.Core;
+
+namespace CreativeCoders.HomeMatic.FirmwareBackup.Internal;
+
+/// <summary>
+/// Default <see cref="ICcuBackupVerifier"/>. Validates that a backup is a HomeMatic CCU backup archive
+/// (an uncompressed tar containing non-empty <c>signature</c> and <c>user_data.tar.gz</c> entries, the
+/// latter being a valid gzip archive).
+/// </summary>
+/// <remarks>
+/// The <c>signature</c> entry is only checked for presence and non-zero length; its bytes are not
+/// cryptographically verified, so a successful verification does not prove the backup's authenticity.
+/// </remarks>
+internal sealed class CcuBackupVerifier : ICcuBackupVerifier
+{
+    private const string SignatureEntryName = "signature";
+
+    private const string UserDataEntryName = "user_data.tar.gz";
+
+    private const byte GzipId1 = 0x1F;
+
+    private const byte GzipId2 = 0x8B;
+
+    private const byte GzipDeflateMethod = 0x08;
+
+    /// <inheritdoc />
+    public async Task VerifyAsync(Stream content, CancellationToken cancellationToken = default)
+    {
+        Ensure.NotNull(content);
+
+        if (content.CanSeek)
+        {
+            content.Seek(0, SeekOrigin.Begin);
+        }
+
+        var signatureFound = false;
+        var userDataValid = false;
+
+        try
+        {
+            await using var tarReader = new TarReader(content, leaveOpen: true);
+
+            while (await tarReader.GetNextEntryAsync(copyData: true, cancellationToken).ConfigureAwait(false)
+                   is { } entry)
+            {
+                var entryName = NormalizeEntryName(entry.Name);
+
+                switch (entryName)
+                {
+                    case SignatureEntryName when entry.Length > 0:
+                        signatureFound = true;
+                        break;
+                    case UserDataEntryName when entry.Length > 0:
+                        userDataValid = await IsValidGzipArchiveAsync(entry, cancellationToken).ConfigureAwait(false);
+                        break;
+                }
+            }
+        }
+        catch (Exception ex) when (ex is not OperationCanceledException)
+        {
+            throw new InvalidFirmwareBackupException(
+                "The downloaded backup is not a valid HomeMatic CCU backup: it could not be read as a tar archive.",
+                ex);
+        }
+
+        if (!signatureFound)
+        {
+            throw new InvalidFirmwareBackupException(
+                $"The downloaded backup is not a valid HomeMatic CCU backup: the '{SignatureEntryName}' entry is missing or empty.");
+        }
+
+        if (!userDataValid)
+        {
+            throw new InvalidFirmwareBackupException(
+                $"The downloaded backup is not a valid HomeMatic CCU backup: the '{UserDataEntryName}' entry is missing, empty or is not a valid gzip archive.");
+        }
+    }
+
+    private static string NormalizeEntryName(string name)
+    {
+        var normalized = name.Replace('\\', '/');
+
+        var lastSeparator = normalized.LastIndexOf('/');
+
+        return lastSeparator < 0
+            ? normalized
+            : normalized[(lastSeparator + 1)..];
+    }
+
+    private static async Task<bool> IsValidGzipArchiveAsync(TarEntry entry, CancellationToken cancellationToken)
+    {
+        var dataStream = entry.DataStream;
+
+        if (dataStream is null)
+        {
+            return false;
+        }
+
+        // The entry was read with copyData: true, so its data stream is a seekable in-memory copy.
+        dataStream.Seek(0, SeekOrigin.Begin);
+
+        var header = new byte[3];
+
+        try
+        {
+            await dataStream.ReadExactlyAsync(header, cancellationToken).ConfigureAwait(false);
+        }
+        catch (EndOfStreamException)
+        {
+            return false;
+        }
+
+        if (header[0] != GzipId1 || header[1] != GzipId2 || header[2] != GzipDeflateMethod)
+        {
+            return false;
+        }
+
+        dataStream.Seek(0, SeekOrigin.Begin);
+
+        try
+        {
+            await using var gzip = new GZipStream(dataStream, CompressionMode.Decompress, leaveOpen: true);
+
+            await gzip.CopyToAsync(Stream.Null, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex) when (ex is InvalidDataException or EndOfStreamException)
+        {
+            return false;
+        }
+
+        return true;
+    }
+}

source/CreativeCoders.HomeMatic/FirmwareBackup/Internal/ICcuBackupVerifier.cs

@@ -0,0 +1,27 @@
+namespace CreativeCoders.HomeMatic.FirmwareBackup.Internal;
+
+/// <summary>
+/// Verifies that a downloaded backup is a valid HomeMatic CCU backup archive.
+/// </summary>
+/// <remarks>
+/// This is a structural integrity check only: it confirms the archive contains the expected,
+/// non-empty entries. The <c>signature</c> entry is verified to be present and non-empty; its
+/// contents are not cryptographically validated, so a passing result is not proof of authenticity.
+/// </remarks>
+internal interface ICcuBackupVerifier
+{
+    /// <summary>
+    /// Verifies that the given stream contains a valid HomeMatic CCU backup.
+    /// </summary>
+    /// <param name="content">
+    /// The stream containing the backup payload. If it is seekable, it is rewound to the beginning
+    /// before reading; otherwise it is read from its current position. The stream is left open and
+    /// its position is undefined after the call.
+    /// </param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that completes when verification succeeds.</returns>
+    /// <exception cref="InvalidFirmwareBackupException">
+    /// Thrown when the content is not a valid HomeMatic CCU backup.
+    /// </exception>
+    Task VerifyAsync(Stream content, CancellationToken cancellationToken = default);
+}