feat: add file module for bidirectional file transfers

Implements a new file module that supports both upload (client → dutagent)
and download (dutagent → client) operations with flexible path resolution.

Signed-off-by: Fabian Wienand <fabian.wienand@9elements.com>

Author: RiSKeD

cmds/dutagent/modules.go

@@ -14,6 +14,7 @@ package main
 import (
 	_ "github.com/BlindspotSoftware/dutctl/pkg/module/agent"
 	_ "github.com/BlindspotSoftware/dutctl/pkg/module/dummy"
+	_ "github.com/BlindspotSoftware/dutctl/pkg/module/file"
 	_ "github.com/BlindspotSoftware/dutctl/pkg/module/flash"
 	_ "github.com/BlindspotSoftware/dutctl/pkg/module/gpio"
 	_ "github.com/BlindspotSoftware/dutctl/pkg/module/ipmi"

go.mod

@@ -6,6 +6,7 @@ require (
 	connectrpc.com/connect v1.19.1
 	github.com/bougou/go-ipmi v0.7.8
 	github.com/go-playground/validator/v10 v10.29.0
+	github.com/google/go-cmp v0.7.0
 	github.com/stianeikeland/go-rpio/v4 v4.6.0
 	github.com/tarm/serial v0.0.0-20180830185346-98f6abe2eb07
 	golang.org/x/crypto v0.46.0

pkg/module/file/README.md

@@ -0,0 +1,39 @@
+The _file_ package provides a single module:
+
+# File
+
+This module transfers files between client and dutagent, supporting both upload and download operations.
+
+```
+ARGUMENTS:
+	<path>              Single path argument. Interpretation depends on configuration.
+	<source>:<dest>     Explicitly specify both paths (incompatible with source/destination config)
+
+The operation type (upload or download) must be configured in the device YAML.
+
+Path Restrictions:
+  - Destination paths (sanitized): must be relative, no absolute paths, no leading '..'
+  - Source paths (not sanitized): any path allowed, including absolute paths
+
+Configuration Behavior:
+  - source configured: arg becomes destination (sanitized - must be relative)
+  - destination configured: arg becomes source (not sanitized - absolute allowed)
+  - neither configured: arg becomes both source and destination (dest is sanitized)
+  - both configured: no arg allowed
+  - Colon syntax: both parts are destinations and sanitized (must be relative)
+
+Path Processing:
+  - Relative paths preserve directory structure: ./dir/file.bin → dir/file.bin
+  - Internal '..' references are resolved: dir/../other/file.bin → other/file.bin
+```
+
+See [file-example-cfg.yml](./file-example-cfg.yml) for examples.
+
+## Configuration Options
+
+| Option      | Value  | Required | Description                                                                                        |
+|-------------|--------|----------|----------------------------------------------------------------------------------------------------|
+| operation   | string | yes      | Operation type: "upload" or "download"                                                             |
+| source      | string | no       | Source path. If set, argument path becomes the destination. Cannot be used with colon syntax       |
+| destination | string | no       | Destination path. If set, argument path becomes the source. Cannot be used with colon syntax       |
+| permission  | string | no       | File permissions in octal format (e.g., "0644", "0755"). Upload only. Default: "0644"              |

pkg/module/file/file-example-cfg.yml

@@ -0,0 +1,63 @@
+# Example configuration for the file module
+# This file demonstrates various use cases for file transfers between client and dutagent
+# $WD is a placeholder of the working directory on both the client and dutagent
+
+devices:
+  example-device:
+    cmds:
+      # Upload any file - preserves directory structure
+      upload:
+        desc: "Upload file to device"
+        modules:
+          - module: file
+            main: true
+            options:
+              operation: "upload"
+        # Usage:
+        #   dutctl example-device upload ./build/firmware.bin
+        #   → uploads to $WD/firmware.bin (preserves structure)
+        #
+        #   dutctl example-device upload ./firmware.bin:custom/firmware.bin
+        #   → uploads to $WD/custom/firmware.bin (custom destination via colon syntax)
+
+      # Upload with destination configured - arg becomes source
+      upload-script:
+        desc: "Upload and install a script"
+        modules:
+          - module: file
+            main: true
+            options:
+              operation: "upload"
+              destination: "/opt/scripts/install.sh"
+              permission: "0755" # Make it executable
+        # Usage:
+        #   dutctl example-device upload-script ./scripts/init.sh
+        #   → uploads to: /opt/scripts/install.sh on device
+
+      # Download with source configured - arg becomes destination
+      fetch-logs:
+        desc: "Download logs from device"
+        modules:
+          - module: file
+            main: true
+            options:
+              operation: "download"
+              source: "/var/log.txt"
+        # Usage:
+        #   dutctl example-device fetch-logs ./local-log.txt
+        #   → downloads /var/log.txt to ./local-log.txt on client
+
+      # Upload with both paths configured - no arg allowed
+      upload-config:
+        desc: "Upload configuration file with fixed paths"
+        modules:
+          - module: file
+            main: true
+            options:
+              operation: "upload"
+              source: "./configs/device.conf"
+              destination: "/etc/device/device.conf"
+              permission: "0644"
+        # Usage:
+        #   dutctl example-device upload-config
+        #   → uploads ./configs/device.conf to /etc/device/device.conf