feat(file): add file management API, deploy provider, and templates

README.md

@@ -29,6 +29,7 @@ them to be used as appliances.
 | 🖥️ **[Node Management][]** | Hostname, uptime, OS info, disk, memory, load |
 | 🌐 **[Network Management][]** | DNS read/update, ping |
 | ⚙️ **[Command Execution][]** | Remote exec and shell across managed hosts |
+| 📁 **[File Management][]** | Upload, deploy, and template files with SHA-based idempotency |
 | 📊 **[System Facts][]** | Agent-collected system facts — architecture, kernel, FQDN, CPUs, network interfaces, service/package manager |
 | 🔄 **[Agent Lifecycle][]** | Node conditions (memory, disk, load pressure), graceful drain/cordon for maintenance |
 | ⚡ **[Async Job System][]** | NATS JetStream with KV-first architecture — broadcast, load-balanced, and label-based routing across hosts |
@@ -42,6 +43,7 @@ them to be used as appliances.
 [Node Management]: https://osapi-io.github.io/osapi/sidebar/features/node-management
 [Network Management]: https://osapi-io.github.io/osapi/sidebar/features/network-management
 [Command Execution]: https://osapi-io.github.io/osapi/sidebar/features/command-execution
+[File Management]: https://osapi-io.github.io/osapi/sidebar/features/file-management
 [Async Job System]: https://osapi-io.github.io/osapi/sidebar/features/job-system
 [Health]: https://osapi-io.github.io/osapi/sidebar/features/health-checks
 [Metrics]: https://osapi-io.github.io/osapi/sidebar/features/metrics

cmd/agent_helpers.go

@@ -28,6 +28,7 @@ import (
 	"github.com/retr0h/osapi/internal/cli"
 	"github.com/retr0h/osapi/internal/config"
 	"github.com/retr0h/osapi/internal/job"
+	fileProv "github.com/retr0h/osapi/internal/provider/file"
 )
 
 // setupAgent connects to NATS, creates providers, and builds the agent
@@ -47,6 +48,10 @@ func setupAgent(
 	providerFactory := agent.NewProviderFactory(log)
 	hostProvider, diskProvider, memProvider, loadProvider, dnsProvider, pingProvider, netinfoProvider, commandProvider := providerFactory.CreateProviders()
 
+	// Create file provider if Object Store and file-state KV are configured
+	hostname, _ := job.GetAgentHostname(appConfig.Agent.Hostname)
+	fileProvider := createFileProvider(ctx, log, b, namespace, hostname)
+
 	a := agent.New(
 		appFs,
 		appConfig,
@@ -61,9 +66,46 @@ func setupAgent(
 		pingProvider,
 		netinfoProvider,
 		commandProvider,
+		fileProvider,
 		b.registryKV,
 		b.factsKV,
 	)
 
 	return a, b
 }
+
+// createFileProvider creates a file provider if Object Store and file-state KV
+// are configured. Returns nil if either is unavailable.
+func createFileProvider(
+	ctx context.Context,
+	log *slog.Logger,
+	b *natsBundle,
+	namespace string,
+	hostname string,
+) fileProv.Provider {
+	if appConfig.NATS.Objects.Bucket == "" || appConfig.NATS.FileState.Bucket == "" {
+		return nil
+	}
+
+	objStoreName := job.ApplyNamespaceToInfraName(namespace, appConfig.NATS.Objects.Bucket)
+	objStore, err := b.nc.ObjectStore(ctx, objStoreName)
+	if err != nil {
+		log.Warn("Object Store not available, file operations disabled",
+			slog.String("bucket", objStoreName),
+			slog.String("error", err.Error()),
+		)
+		return nil
+	}
+
+	fileStateKVConfig := cli.BuildFileStateKVConfig(namespace, appConfig.NATS.FileState)
+	fileStateKV, err := b.nc.CreateOrUpdateKVBucketWithConfig(ctx, fileStateKVConfig)
+	if err != nil {
+		log.Warn("file state KV not available, file operations disabled",
+			slog.String("bucket", fileStateKVConfig.Bucket),
+			slog.String("error", err.Error()),
+		)
+		return nil
+	}
+
+	return fileProv.New(log, appFs, objStore, fileStateKV, hostname)
+}

cmd/api_helpers.go

@@ -32,6 +32,7 @@ import (
 	natsclient "github.com/osapi-io/nats-client/pkg/client"
 
 	"github.com/retr0h/osapi/internal/api"
+	"github.com/retr0h/osapi/internal/api/file"
 	"github.com/retr0h/osapi/internal/api/health"
 	"github.com/retr0h/osapi/internal/audit"
 	"github.com/retr0h/osapi/internal/cli"
@@ -62,6 +63,8 @@ type ServerManager interface {
 	GetMetricsHandler(metricsHandler http.Handler, path string) []func(e *echo.Echo)
 	// GetAuditHandler returns audit handler for registration.
 	GetAuditHandler(store audit.Store) []func(e *echo.Echo)
+	// GetFileHandler returns file handler for registration.
+	GetFileHandler(objStore file.ObjectStoreManager) []func(e *echo.Echo)
 	// RegisterHandlers registers a list of handlers with the Echo instance.
 	RegisterHandlers(handlers []func(e *echo.Echo))
 }
@@ -75,6 +78,7 @@ type natsBundle struct {
 	registryKV jetstream.KeyValue
 	factsKV    jetstream.KeyValue
 	stateKV    jetstream.KeyValue
+	objStore   file.ObjectStoreManager
 }
 
 // setupAPIServer connects to NATS, creates the API server with all handlers,
@@ -119,7 +123,7 @@ func setupAPIServer(
 	sm := api.New(appConfig, log, serverOpts...)
 	registerAPIHandlers(
 		sm, b.jobClient, checker, metricsProvider,
-		metricsHandler, metricsPath, auditStore,
+		metricsHandler, metricsPath, auditStore, b.objStore,
 	)
 
 	return sm, b
@@ -173,6 +177,19 @@ func connectNATSBundle(
 		}
 	}
 
+	// Create or update Object Store bucket for file management API
+	var objStore file.ObjectStoreManager
+	if appConfig.NATS.Objects.Bucket != "" {
+		objStoreConfig := cli.BuildObjectStoreConfig(namespace, appConfig.NATS.Objects)
+		var objErr error
+		objStore, objErr = nc.CreateOrUpdateObjectStore(ctx, objStoreConfig)
+		if objErr != nil {
+			log.Warn("Object Store not available, file endpoints disabled",
+				slog.String("bucket", objStoreConfig.Bucket),
+				slog.String("error", objErr.Error()))
+		}
+	}
+
 	jc, err := jobclient.New(log, nc, &jobclient.Options{
 		Timeout:    30 * time.Second,
 		KVBucket:   jobsKV,
@@ -192,6 +209,7 @@ func connectNATSBundle(
 		registryKV: registryKV,
 		factsKV:    factsKV,
 		stateKV:    stateKV,
+		objStore:   objStore,
 	}
 }
 
@@ -395,6 +413,7 @@ func registerAPIHandlers(
 	metricsHandler http.Handler,
 	metricsPath string,
 	auditStore audit.Store,
+	objStore file.ObjectStoreManager,
 ) {
 	startTime := time.Now()
 
@@ -409,6 +428,9 @@ func registerAPIHandlers(
 	if auditStore != nil {
 		handlers = append(handlers, sm.GetAuditHandler(auditStore)...)
 	}
+	if objStore != nil {
+		handlers = append(handlers, sm.GetFileHandler(objStore)...)
+	}
 
 	sm.RegisterHandlers(handlers)
 }

cmd/client_file.go

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 John Dewey
+
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// clientFileCmd represents the clientFile command.
+var clientFileCmd = &cobra.Command{
+	Use:   "file",
+	Short: "The file subcommand",
+}
+
+func init() {
+	clientCmd.AddCommand(clientFileCmd)
+}

cmd/client_file_delete.go

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 John Dewey
+
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/retr0h/osapi/internal/cli"
+)
+
+// clientFileDeleteCmd represents the clientFileDelete command.
+var clientFileDeleteCmd = &cobra.Command{
+	Use:   "delete",
+	Short: "Delete a file from the Object Store",
+	Long:  `Delete a specific file from the OSAPI Object Store.`,
+	Run: func(cmd *cobra.Command, _ []string) {
+		ctx := cmd.Context()
+		name, _ := cmd.Flags().GetString("name")
+
+		resp, err := sdkClient.File.Delete(ctx, name)
+		if err != nil {
+			cli.HandleError(err, logger)
+			return
+		}
+
+		if jsonOutput {
+			fmt.Println(string(resp.RawJSON()))
+			return
+		}
+
+		fmt.Println()
+		cli.PrintKV("Name", resp.Data.Name)
+		cli.PrintKV("Deleted", fmt.Sprintf("%v", resp.Data.Deleted))
+	},
+}
+
+func init() {
+	clientFileCmd.AddCommand(clientFileDeleteCmd)
+
+	clientFileDeleteCmd.PersistentFlags().
+		String("name", "", "Name of the file in the Object Store (required)")
+
+	_ = clientFileDeleteCmd.MarkPersistentFlagRequired("name")
+}

cmd/client_file_get.go

@@ -0,0 +1,65 @@
+// Copyright (c) 2026 John Dewey
+
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/retr0h/osapi/internal/cli"
+)
+
+// clientFileGetCmd represents the clientFileGet command.
+var clientFileGetCmd = &cobra.Command{
+	Use:   "get",
+	Short: "Get file metadata",
+	Long:  `Get metadata for a specific file stored in the OSAPI Object Store.`,
+	Run: func(cmd *cobra.Command, _ []string) {
+		ctx := cmd.Context()
+		name, _ := cmd.Flags().GetString("name")
+
+		resp, err := sdkClient.File.Get(ctx, name)
+		if err != nil {
+			cli.HandleError(err, logger)
+			return
+		}
+
+		if jsonOutput {
+			fmt.Println(string(resp.RawJSON()))
+			return
+		}
+
+		fmt.Println()
+		cli.PrintKV("Name", resp.Data.Name)
+		cli.PrintKV("SHA256", resp.Data.SHA256)
+		cli.PrintKV("Size", fmt.Sprintf("%d", resp.Data.Size))
+	},
+}
+
+func init() {
+	clientFileCmd.AddCommand(clientFileGetCmd)
+
+	clientFileGetCmd.PersistentFlags().
+		String("name", "", "Name of the file in the Object Store (required)")
+
+	_ = clientFileGetCmd.MarkPersistentFlagRequired("name")
+}