Add SSH SFTP backend support

internal/adapters/ssh/auth.go

@@ -0,0 +1,61 @@
+package ssh
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"os"
+
+	cryptossh "golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/agent"
+)
+
+type agentDialer func(network, address string) (net.Conn, error)
+
+func authMethods(keyFile string) ([]cryptossh.AuthMethod, func(), error) {
+	return authMethodsWithAgent(os.Getenv("SSH_AUTH_SOCK"), net.Dial, keyFile)
+}
+
+func authMethodsWithAgent(agentSocket string, dial agentDialer, keyFile string) ([]cryptossh.AuthMethod, func(), error) {
+	var methods []cryptossh.AuthMethod
+	var closers []io.Closer
+	if agentSocket != "" {
+		methods = append(methods, cryptossh.PublicKeysCallback(func() ([]cryptossh.Signer, error) {
+			conn, err := dial("unix", agentSocket)
+			if err != nil {
+				return nil, err
+			}
+			closers = append(closers, conn)
+			return agent.NewClient(conn).Signers()
+		}))
+	}
+	if keyFile != "" {
+		signer, err := signerFromKeyFile(keyFile)
+		if err != nil {
+			return nil, nil, err
+		}
+		methods = append(methods, cryptossh.PublicKeys(signer))
+	}
+	if len(methods) == 0 {
+		return nil, nil, fmt.Errorf("no SSH auth methods configured; set SSH_AUTH_SOCK or ssh_key_file")
+	}
+	return methods, func() { closeAll(closers) }, nil
+}
+
+func signerFromKeyFile(path string) (cryptossh.Signer, error) {
+	key, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read ssh_key_file %q: %w", path, err)
+	}
+	signer, err := cryptossh.ParsePrivateKey(key)
+	if err != nil {
+		return nil, fmt.Errorf("parse ssh_key_file %q: %w", path, err)
+	}
+	return signer, nil
+}
+
+func closeAll(closers []io.Closer) {
+	for _, closer := range closers {
+		_ = closer.Close()
+	}
+}

internal/adapters/ssh/auth_test.go

@@ -0,0 +1,59 @@
+package ssh
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/x509"
+	"encoding/pem"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestAuthMethodsPreferAgentBeforeKeyFile(t *testing.T) {
+	keyFile := writePrivateKey(t)
+	methods, cleanup, err := authMethodsWithAgent("/tmp/ssh-agent.sock", nil, keyFile)
+	if err != nil {
+		t.Fatalf("authMethodsWithAgent() error = %v", err)
+	}
+	defer cleanup()
+	if got, want := len(methods), 2; got != want {
+		t.Fatalf("auth method count = %d, want %d", got, want)
+	}
+}
+
+func TestAuthMethodsLoadsKeyFile(t *testing.T) {
+	keyFile := writePrivateKey(t)
+	methods, cleanup, err := authMethodsWithAgent("", nil, keyFile)
+	if err != nil {
+		t.Fatalf("authMethodsWithAgent() error = %v", err)
+	}
+	defer cleanup()
+	if got, want := len(methods), 1; got != want {
+		t.Fatalf("auth method count = %d, want %d", got, want)
+	}
+}
+
+func TestAuthMethodsRejectsMissingAuth(t *testing.T) {
+	_, _, err := authMethodsWithAgent("", nil, "")
+	if err == nil {
+		t.Fatal("authMethodsWithAgent() error = nil, want error")
+	}
+}
+
+func writePrivateKey(t *testing.T) string {
+	t.Helper()
+	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	data := pem.EncodeToMemory(&pem.Block{
+		Type:  "RSA PRIVATE KEY",
+		Bytes: x509.MarshalPKCS1PrivateKey(privateKey),
+	})
+	path := filepath.Join(t.TempDir(), "id_rsa")
+	if err := os.WriteFile(path, data, 0o600); err != nil {
+		t.Fatalf("write private key: %v", err)
+	}
+	return path
+}

internal/adapters/ssh/backend.go

@@ -0,0 +1,445 @@
+package ssh
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"sort"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"github.com/pkg/sftp"
+	cryptossh "golang.org/x/crypto/ssh"
+)
+
+type Backend struct {
+	client    *sftp.Client
+	sshClient *cryptossh.Client
+	root      string
+}
+
+func New(ctx context.Context, options Options) (*Backend, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	options, err := options.normalized()
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.Root, storage.ErrInvalidPath, err)
+	}
+	hostKeyCallback, err := hostKeyCallback(options)
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.KnownHosts, storage.ErrInvalidPath, err)
+	}
+	auth, cleanupAuth, err := authMethods(options.KeyFile)
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.KeyFile, storage.ErrPermission, err)
+	}
+	defer cleanupAuth()
+
+	sshClient, err := cryptossh.Dial("tcp", options.address(), &cryptossh.ClientConfig{
+		User:            options.User,
+		Auth:            auth,
+		HostKeyCallback: hostKeyCallback,
+		Timeout:         30 * time.Second,
+	})
+	if err != nil {
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.address(), storage.ErrUnknown, err)
+	}
+	client, err := sftp.NewClient(sshClient)
+	if err != nil {
+		_ = sshClient.Close()
+		return nil, storage.NewError(storage.OpOpenBackend, BackendName, options.address(), storage.ErrUnknown, err)
+	}
+	return &Backend{client: client, sshClient: sshClient, root: options.Root}, nil
+}
+
+func (b *Backend) Close() error {
+	var err error
+	if b.client != nil {
+		err = b.client.Close()
+	}
+	if b.sshClient != nil {
+		if closeErr := b.sshClient.Close(); err == nil {
+			err = closeErr
+		}
+	}
+	return err
+}
+
+func (b *Backend) ReadFile(ctx context.Context, logicalPath string) ([]byte, error) {
+	reader, err := b.OpenReader(ctx, logicalPath)
+	if err != nil {
+		return nil, err
+	}
+	defer reader.Close()
+	data, err := io.ReadAll(reader)
+	if err != nil {
+		return nil, storage.NewError(storage.OpReadFile, BackendName, logicalPath, storage.ErrUnknown, err)
+	}
+	return data, nil
+}
+
+func (b *Backend) OpenReader(ctx context.Context, logicalPath string) (io.ReadCloser, error) {
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	nativePath, err := b.nativePath(logicalPath, false)
+	if err != nil {
+		return nil, err
+	}
+	if err := b.rejectSymlinkAncestors(ctx, logicalPath, true); err != nil {
+		return nil, err
+	}
+	info, err := b.client.Lstat(nativePath)
+	if err != nil {
+		return nil, b.translateError(storage.OpOpenReader, logicalPath, err)
+	}
+	if !info.Mode().IsRegular() {
+		return nil, storage.NewError(storage.OpOpenReader, BackendName, logicalPath, storage.ErrUnsupported, nil)
+	}
+	file, err := b.client.Open(nativePath)
+	if err != nil {
+		return nil, b.translateError(storage.OpOpenReader, logicalPath, err)
+	}
+	return file, nil
+}
+
+func (b *Backend) WriteFile(ctx context.Context, logicalPath string, data []byte, opts storage.WriteOptions) (storage.Entry, error) {
+	opts.Size = int64(len(data))
+	opts.SizeKnown = true
+	return b.WriteFrom(ctx, logicalPath, bytes.NewReader(data), opts)
+}
+
+func (b *Backend) WriteFrom(ctx context.Context, logicalPath string, r io.Reader, opts storage.WriteOptions) (storage.Entry, error) {
+	if err := ctx.Err(); err != nil {
+		return storage.Entry{}, err
+	}
+	nativePath, err := b.nativePath(logicalPath, false)
+	if err != nil {
+		return storage.Entry{}, err
+	}
+	if err := b.rejectSymlinkAncestors(ctx, parentOf(logicalPath), true); err != nil {
+		return storage.Entry{}, err
+	}
+	if info, err := b.client.Lstat(nativePath); err == nil {
+		if !opts.Overwrite {
+			return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrAlreadyExist, nil)
+		}
+		if !info.Mode().IsRegular() {
+			return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrConflict, nil)
+		}
+	} else if !isNotExist(err) {
+		return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+	}
+
+	parentNative := path.Dir(nativePath)
+	if err := b.client.MkdirAll(parentNative); err != nil {
+		return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+	}
+
+	writePath := nativePath
+	if opts.PreferAtomic {
+		writePath = path.Join(parentNative, fmt.Sprintf(".distributor-write-%d", time.Now().UnixNano()))
+	}
+	file, err := b.client.Create(writePath)
+	if err != nil {
+		return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+	}
+	cleanup := opts.PreferAtomic
+	defer func() {
+		if cleanup {
+			_ = b.client.Remove(writePath)
+		}
+	}()
+
+	written, copyErr := io.Copy(file, r)
+	closeErr := file.Close()
+	if copyErr != nil {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrUnknown, copyErr)
+	}
+	if closeErr != nil {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrUnknown, closeErr)
+	}
+	if opts.SizeKnown && written != opts.Size {
+		return storage.Entry{}, storage.NewError(storage.OpWriteFrom, BackendName, logicalPath, storage.ErrConflict, fmt.Errorf("stream size %d does not match expected size %d", written, opts.Size))
+	}
+	if opts.PreferAtomic {
+		if err := b.client.Rename(writePath, nativePath); err != nil {
+			return storage.Entry{}, b.translateError(storage.OpWriteFrom, logicalPath, err)
+		}
+		cleanup = false
+	}
+	return b.Stat(ctx, logicalPath)
+}
+
+func (b *Backend) Stat(ctx context.Context, logicalPath string) (storage.Entry, error) {
+	if err := ctx.Err(); err != nil {
+		return storage.Entry{}, err
+	}
+	nativePath, err := b.nativePath(logicalPath, true)
+	if err != nil {
+		return storage.Entry{}, err
+	}
+	info, err := b.client.Lstat(nativePath)
+	if err != nil {
+		return storage.Entry{}, b.translateError(storage.OpStat, logicalPath, err)
+	}
+	return entryFromInfo(logicalPath, info), nil
+}
+
+func (b *Backend) Walk(ctx context.Context, prefix string, opts storage.WalkOptions, fn storage.WalkFunc) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	nativePrefix, err := b.nativePath(prefix, true)
+	if err != nil {
+		return err
+	}
+	info, err := b.client.Lstat(nativePrefix)
+	if err != nil {
+		if isNotExist(err) {
+			return nil
+		}
+		return b.translateError(storage.OpWalk, prefix, err)
+	}
+
+	visited := 0
+	emit := func(entry storage.Entry) error {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		if opts.Limit > 0 && visited >= opts.Limit {
+			return storage.ErrStopWalk
+		}
+		visited++
+		if err := fn(entry); err != nil {
+			if errors.Is(err, storage.ErrStopWalk) {
+				return storage.ErrStopWalk
+			}
+			return storage.NewError(storage.OpWalk, BackendName, entry.Path, storage.ErrUnknown, err)
+		}
+		return nil
+	}
+
+	if !info.IsDir() {
+		if err := emit(entryFromInfo(prefix, info)); errors.Is(err, storage.ErrStopWalk) {
+			return nil
+		} else if err != nil {
+			return err
+		}
+		return nil
+	}
+
+	if err := b.walkDirectory(ctx, prefix, nativePrefix, opts, emit); errors.Is(err, storage.ErrStopWalk) {
+		return nil
+	} else if err != nil {
+		return err
+	}
+	return nil
+}
+
+func (b *Backend) HasAny(ctx context.Context, prefix string) (bool, error) {
+	found := false
+	err := b.Walk(ctx, prefix, storage.WalkOptions{Recursive: false, Limit: 1}, func(storage.Entry) error {
+		found = true
+		return storage.ErrStopWalk
+	})
+	if err != nil {
+		return false, err
+	}
+	return found, nil
+}
+
+func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	targets, err := storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	if err != nil {
+		return err
+	}
+	for _, target := range targets {
+		nativePath, err := b.nativePath(target, false)
+		if err != nil {
+			return err
+		}
+		if nativePath == b.root {
+			return storage.NewError(storage.OpDeleteManagedBundle, BackendName, target, storage.ErrInvalidPath, nil)
+		}
+		info, err := b.client.Lstat(nativePath)
+		if err != nil {
+			if opts.IgnoreMissing && isNotExist(err) {
+				continue
+			}
+			return b.translateError(storage.OpDeleteManagedBundle, target, err)
+		}
+		if info.IsDir() {
+			return storage.NewError(storage.OpDeleteManagedBundle, BackendName, target, storage.ErrUnsupported, nil)
+		}
+		if err := b.client.Remove(nativePath); err != nil {
+			return b.translateError(storage.OpDeleteManagedBundle, target, err)
+		}
+		if opts.PruneEmptyDirs {
+			b.pruneEmptyParents(parentOf(target))
+		}
+	}
+	return nil
+}
+
+func (b *Backend) walkDirectory(ctx context.Context, logicalPrefix, nativePrefix string, opts storage.WalkOptions, emit func(storage.Entry) error) error {
+	entries, err := b.client.ReadDir(nativePrefix)
+	if err != nil {
+		return b.translateError(storage.OpWalk, logicalPrefix, err)
+	}
+	sort.Slice(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
+	for _, info := range entries {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		logicalPath := info.Name()
+		if logicalPrefix != "" {
+			logicalPath = logicalPrefix + "/" + info.Name()
+		}
+		if err := emit(entryFromInfo(logicalPath, info)); err != nil {
+			return err
+		}
+		if opts.Recursive && info.IsDir() {
+			if err := b.walkDirectory(ctx, logicalPath, path.Join(nativePrefix, info.Name()), opts, emit); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func (b *Backend) nativePath(logicalPath string, allowEmpty bool) (string, error) {
+	if logicalPath == "" {
+		if !allowEmpty {
+			return "", storage.NewError(storage.OpValidatePath, BackendName, logicalPath, storage.ErrInvalidPath, nil)
+		}
+		return b.root, nil
+	}
+	if err := storage.ValidatePath(logicalPath); err != nil {
+		return "", err
+	}
+	nativePath := path.Clean(path.Join(b.root, logicalPath))
+	if !withinRoot(b.root, nativePath) {
+		return "", storage.NewError(storage.OpValidatePath, BackendName, logicalPath, storage.ErrInvalidPath, nil)
+	}
+	return nativePath, nil
+}
+
+func (b *Backend) rejectSymlinkAncestors(ctx context.Context, logicalPath string, includeFinal bool) error {
+	if logicalPath == "" {
+		return nil
+	}
+	if err := storage.ValidatePath(logicalPath); err != nil {
+		return err
+	}
+	segments := strings.Split(logicalPath, "/")
+	limit := len(segments)
+	if !includeFinal {
+		limit--
+	}
+	current := ""
+	for index := 0; index < limit; index++ {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		if current == "" {
+			current = segments[index]
+		} else {
+			current += "/" + segments[index]
+		}
+		nativePath, err := b.nativePath(current, false)
+		if err != nil {
+			return err
+		}
+		info, err := b.client.Lstat(nativePath)
+		if err != nil {
+			if isNotExist(err) {
+				return nil
+			}
+			return b.translateError(storage.OpStat, current, err)
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return storage.NewError(storage.OpStat, BackendName, current, storage.ErrUnsupported, nil)
+		}
+	}
+	return nil
+}
+
+func (b *Backend) pruneEmptyParents(logicalPath string) {
+	for logicalPath != "" {
+		nativePath, err := b.nativePath(logicalPath, false)
+		if err != nil || nativePath == b.root {
+			return
+		}
+		if err := b.client.RemoveDirectory(nativePath); err != nil {
+			return
+		}
+		logicalPath = parentOf(logicalPath)
+	}
+}
+
+func withinRoot(root, candidate string) bool {
+	if candidate == root {
+		return true
+	}
+	if root == "/" {
+		return strings.HasPrefix(candidate, "/")
+	}
+	return strings.HasPrefix(candidate, strings.TrimSuffix(root, "/")+"/")
+}
+
+func parentOf(logicalPath string) string {
+	index := strings.LastIndex(logicalPath, "/")
+	if index == -1 {
+		return ""
+	}
+	return logicalPath[:index]
+}
+
+func isNotExist(err error) bool {
+	return errors.Is(err, fs.ErrNotExist) || errors.Is(err, os.ErrNotExist) || errors.Is(err, sftp.ErrSSHFxNoSuchFile)
+}
+
+func (b *Backend) translateError(op, logicalPath string, err error) error {
+	kind := storage.ErrUnknown
+	switch {
+	case isNotExist(err):
+		kind = storage.ErrNotFound
+	case errors.Is(err, fs.ErrExist), errors.Is(err, os.ErrExist):
+		kind = storage.ErrAlreadyExist
+	case errors.Is(err, fs.ErrPermission), errors.Is(err, os.ErrPermission), errors.Is(err, sftp.ErrSSHFxPermissionDenied):
+		kind = storage.ErrPermission
+	case errors.Is(err, sftp.ErrSSHFxOpUnsupported):
+		kind = storage.ErrUnsupported
+	case errors.Is(err, sftp.ErrSSHFxNoConnection), errors.Is(err, sftp.ErrSSHFxConnectionLost):
+		kind = storage.ErrTemporary
+	}
+	return storage.NewError(op, BackendName, logicalPath, kind, err)
+}
+
+func entryFromInfo(logicalPath string, info fs.FileInfo) storage.Entry {
+	entryType := storage.EntryTypeOther
+	switch {
+	case info.Mode()&os.ModeSymlink != 0:
+		entryType = storage.EntryTypeSymlink
+	case info.Mode().IsRegular():
+		entryType = storage.EntryTypeFile
+	case info.IsDir():
+		entryType = storage.EntryTypeDirectory
+	}
+	return storage.Entry{
+		Path: logicalPath,
+		Type: entryType,
+		Size: info.Size(),
+	}
+}

internal/adapters/ssh/hostkeys.go

@@ -0,0 +1,81 @@
+package ssh
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"os"
+
+	cryptossh "golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/knownhosts"
+)
+
+func hostKeyCallback(options Options) (cryptossh.HostKeyCallback, error) {
+	switch options.HostKeyPolicy {
+	case HostKeyPolicyOff:
+		return cryptossh.InsecureIgnoreHostKey(), nil
+	case HostKeyPolicyStrict:
+		if options.KnownHosts == "" {
+			return nil, fmt.Errorf("known_hosts is required for strict host key checking")
+		}
+		callback, err := knownhosts.New(options.KnownHosts)
+		if err != nil {
+			return nil, fmt.Errorf("load known_hosts %q: %w", options.KnownHosts, err)
+		}
+		return callback, nil
+	case HostKeyPolicyAcceptNew:
+		return acceptNewHostKeyCallback(options)
+	default:
+		return nil, fmt.Errorf("host_key_policy must be strict, accept-new, or off")
+	}
+}
+
+func acceptNewHostKeyCallback(options Options) (cryptossh.HostKeyCallback, error) {
+	var checker cryptossh.HostKeyCallback
+	if options.KnownHosts != "" {
+		loaded, err := knownhosts.New(options.KnownHosts)
+		if err == nil {
+			checker = loaded
+		} else if !errors.Is(err, os.ErrNotExist) {
+			return nil, fmt.Errorf("load known_hosts %q: %w", options.KnownHosts, err)
+		}
+	}
+	return func(hostname string, remote net.Addr, key cryptossh.PublicKey) error {
+		if checker != nil {
+			err := checker(hostname, remote, key)
+			if err == nil {
+				return nil
+			}
+			var keyErr *knownhosts.KeyError
+			if !errors.As(err, &keyErr) {
+				return err
+			}
+			if len(keyErr.Want) > 0 {
+				return fmt.Errorf("host key for %s has changed: %w", hostname, err)
+			}
+		}
+		if options.KnownHosts == "" {
+			return fmt.Errorf("host key for %s is unknown and no writable known_hosts path is available", hostname)
+		}
+		if err := appendKnownHost(options.KnownHosts, hostname, key); err != nil {
+			return err
+		}
+		loaded, err := knownhosts.New(options.KnownHosts)
+		if err == nil {
+			checker = loaded
+		}
+		return nil
+	}, nil
+}
+
+func appendKnownHost(path, host string, key cryptossh.PublicKey) error {
+	file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
+	if err != nil {
+		return fmt.Errorf("persist accepted host key to known_hosts %q: %w", path, err)
+	}
+	defer file.Close()
+	if _, err := fmt.Fprintln(file, knownhosts.Line([]string{knownhosts.Normalize(host)}, key)); err != nil {
+		return fmt.Errorf("persist accepted host key to known_hosts %q: %w", path, err)
+	}
+	return nil
+}

internal/adapters/ssh/hostkeys_test.go

@@ -0,0 +1,87 @@
+package ssh
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	cryptossh "golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/knownhosts"
+)
+
+func TestAcceptNewHostKeyCallbackPersistsUnknownHost(t *testing.T) {
+	key := testPublicKey(t)
+	knownHosts := filepath.Join(t.TempDir(), "known_hosts")
+	callback, err := acceptNewHostKeyCallback(Options{KnownHosts: knownHosts})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	if err := callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, key); err != nil {
+		t.Fatalf("callback() error = %v", err)
+	}
+	data, err := os.ReadFile(knownHosts)
+	if err != nil {
+		t.Fatalf("read known_hosts: %v", err)
+	}
+	if !strings.Contains(string(data), "example.com") {
+		t.Fatalf("known_hosts = %q, want example.com entry", data)
+	}
+	if err := callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, key); err != nil {
+		t.Fatalf("second callback() error = %v", err)
+	}
+}
+
+func TestAcceptNewHostKeyCallbackRejectsChangedHostKey(t *testing.T) {
+	first := testPublicKey(t)
+	second := testPublicKey(t)
+	knownHosts := filepath.Join(t.TempDir(), "known_hosts")
+	if err := os.WriteFile(knownHosts, []byte(knownhosts.Line([]string{knownhosts.Normalize("example.com:22")}, first)+"\n"), 0o600); err != nil {
+		t.Fatalf("write known_hosts: %v", err)
+	}
+	callback, err := acceptNewHostKeyCallback(Options{KnownHosts: knownHosts})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	err = callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, second)
+	if err == nil || !strings.Contains(err.Error(), "has changed") {
+		t.Fatalf("callback() error = %v, want changed host key", err)
+	}
+}
+
+func TestAcceptNewHostKeyCallbackRequiresWritableKnownHostsForUnknownHost(t *testing.T) {
+	callback, err := acceptNewHostKeyCallback(Options{})
+	if err != nil {
+		t.Fatalf("acceptNewHostKeyCallback() error = %v", err)
+	}
+
+	err = callback("example.com:22", &net.TCPAddr{IP: net.ParseIP("192.0.2.10"), Port: 22}, testPublicKey(t))
+	if err == nil || !strings.Contains(err.Error(), "no writable known_hosts path") {
+		t.Fatalf("callback() error = %v, want no writable known_hosts path", err)
+	}
+}
+
+func TestStrictHostKeyCallbackRequiresKnownHosts(t *testing.T) {
+	_, err := hostKeyCallback(Options{HostKeyPolicy: HostKeyPolicyStrict})
+	if err == nil || !strings.Contains(err.Error(), "known_hosts is required") {
+		t.Fatalf("hostKeyCallback() error = %v, want known_hosts required", err)
+	}
+}
+
+func testPublicKey(t *testing.T) cryptossh.PublicKey {
+	t.Helper()
+	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	publicKey, err := cryptossh.NewPublicKey(&privateKey.PublicKey)
+	if err != nil {
+		t.Fatalf("new public key: %v", err)
+	}
+	return publicKey
+}

internal/adapters/ssh/integration_test.go

@@ -0,0 +1,39 @@
+package ssh
+
+import (
+	"context"
+	"os"
+	"strconv"
+	"testing"
+)
+
+func TestIntegrationSSHBackendStatRoot(t *testing.T) {
+	host := os.Getenv("DISTRIBUTOR_TEST_SSH_HOST")
+	if host == "" {
+		t.Skip("DISTRIBUTOR_TEST_SSH_HOST is not set")
+	}
+	port := 22
+	if raw := os.Getenv("DISTRIBUTOR_TEST_SSH_PORT"); raw != "" {
+		parsed, err := strconv.Atoi(raw)
+		if err != nil {
+			t.Fatalf("parse DISTRIBUTOR_TEST_SSH_PORT: %v", err)
+		}
+		port = parsed
+	}
+	backend, err := New(context.Background(), Options{
+		Host:          host,
+		User:          os.Getenv("DISTRIBUTOR_TEST_SSH_USER"),
+		Port:          port,
+		Root:          os.Getenv("DISTRIBUTOR_TEST_SSH_PATH"),
+		KeyFile:       os.Getenv("DISTRIBUTOR_TEST_SSH_KEY_FILE"),
+		KnownHosts:    os.Getenv("DISTRIBUTOR_TEST_SSH_KNOWN_HOSTS"),
+		HostKeyPolicy: HostKeyPolicyStrict,
+	})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	defer backend.Close()
+	if _, err := backend.Stat(context.Background(), ""); err != nil {
+		t.Fatalf("Stat(root) error = %v", err)
+	}
+}

internal/adapters/ssh/options.go

@@ -0,0 +1,77 @@
+package ssh
+
+import (
+	"fmt"
+	"os"
+	"os/user"
+	"path"
+	"path/filepath"
+	"strconv"
+)
+
+const (
+	BackendName = "ssh"
+
+	HostKeyPolicyStrict    HostKeyPolicy = "strict"
+	HostKeyPolicyAcceptNew HostKeyPolicy = "accept-new"
+	HostKeyPolicyOff       HostKeyPolicy = "off"
+)
+
+type HostKeyPolicy string
+
+type Options struct {
+	Host          string
+	User          string
+	Port          int
+	Root          string
+	KeyFile       string
+	KnownHosts    string
+	HostKeyPolicy HostKeyPolicy
+}
+
+func (o Options) normalized() (Options, error) {
+	if o.Host == "" {
+		return Options{}, fmt.Errorf("host is required")
+	}
+	if o.User == "" {
+		current, err := user.Current()
+		if err != nil || current.Username == "" {
+			return Options{}, fmt.Errorf("user is required when current OS user cannot be determined")
+		}
+		o.User = current.Username
+	}
+	if o.Port == 0 {
+		o.Port = 22
+	}
+	if o.Port < 1 || o.Port > 65535 {
+		return Options{}, fmt.Errorf("port must be between 1 and 65535")
+	}
+	if o.Root == "" {
+		return Options{}, fmt.Errorf("path is required")
+	}
+	o.Root = path.Clean(o.Root)
+	if o.HostKeyPolicy == "" {
+		o.HostKeyPolicy = HostKeyPolicyAcceptNew
+	}
+	switch o.HostKeyPolicy {
+	case HostKeyPolicyStrict, HostKeyPolicyAcceptNew, HostKeyPolicyOff:
+	default:
+		return Options{}, fmt.Errorf("host_key_policy must be strict, accept-new, or off")
+	}
+	if o.KnownHosts == "" && o.HostKeyPolicy != HostKeyPolicyOff {
+		o.KnownHosts = defaultKnownHostsPath()
+	}
+	return o, nil
+}
+
+func (o Options) address() string {
+	return o.Host + ":" + strconv.Itoa(o.Port)
+}
+
+func defaultKnownHostsPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return ""
+	}
+	return filepath.Join(home, ".ssh", "known_hosts")
+}

internal/adapters/ssh/options_test.go

@@ -0,0 +1,118 @@
+package ssh
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"github.com/pkg/sftp"
+)
+
+func TestOptionsNormalizeDefaultsUserPortAndHostKeyPolicy(t *testing.T) {
+	options, err := (Options{
+		Host: "example.com",
+		Root: "/reports",
+	}).normalized()
+	if err != nil {
+		t.Fatalf("normalized() error = %v", err)
+	}
+	if options.User == "" {
+		t.Fatal("normalized user is empty")
+	}
+	if options.Port != 22 {
+		t.Fatalf("port = %d, want 22", options.Port)
+	}
+	if options.HostKeyPolicy != HostKeyPolicyAcceptNew {
+		t.Fatalf("host key policy = %q, want accept-new", options.HostKeyPolicy)
+	}
+}
+
+func TestOptionsNormalizeRejectsInvalidFields(t *testing.T) {
+	tests := map[string]Options{
+		"host": {Root: "/reports"},
+		"port": {
+			Host: "example.com",
+			Port: 70000,
+			Root: "/reports",
+		},
+		"path": {
+			Host: "example.com",
+		},
+		"host key policy": {
+			Host:          "example.com",
+			Root:          "/reports",
+			HostKeyPolicy: "prompt",
+		},
+	}
+	for name, options := range tests {
+		t.Run(name, func(t *testing.T) {
+			if _, err := options.normalized(); err == nil {
+				t.Fatal("normalized() error = nil, want error")
+			}
+		})
+	}
+}
+
+func TestNativePathEnforcesLogicalPathRules(t *testing.T) {
+	backend := &Backend{root: "/srv/reports"}
+	tests := map[string]string{
+		"bundle/report.md": "/srv/reports/bundle/report.md",
+		"":                 "/srv/reports",
+	}
+	for logicalPath, want := range tests {
+		t.Run(logicalPath, func(t *testing.T) {
+			got, err := backend.nativePath(logicalPath, true)
+			if err != nil {
+				t.Fatalf("nativePath() error = %v", err)
+			}
+			if got != want {
+				t.Fatalf("nativePath() = %q, want %q", got, want)
+			}
+		})
+	}
+
+	for _, logicalPath := range []string{"/absolute", "../escape", "a/../b", `a\b`} {
+		t.Run("reject "+logicalPath, func(t *testing.T) {
+			_, err := backend.nativePath(logicalPath, true)
+			if err == nil || !storage.IsInvalidPath(err) {
+				t.Fatalf("nativePath() error = %v, want invalid path", err)
+			}
+		})
+	}
+}
+
+func TestNewRejectsMissingAuthBeforeDial(t *testing.T) {
+	t.Setenv("SSH_AUTH_SOCK", "")
+	_, err := New(context.Background(), Options{
+		Host:          "example.com",
+		User:          "reports",
+		Root:          "/reports",
+		HostKeyPolicy: HostKeyPolicyOff,
+	})
+	if err == nil || !strings.Contains(err.Error(), "no SSH auth methods configured") {
+		t.Fatalf("New() error = %v, want missing auth", err)
+	}
+}
+
+func TestTranslateErrorMapsSFTPStatusCodes(t *testing.T) {
+	backend := &Backend{}
+	tests := []struct {
+		name string
+		err  error
+		want storage.ErrorKind
+	}{
+		{name: "not found", err: sftp.ErrSSHFxNoSuchFile, want: storage.ErrNotFound},
+		{name: "permission", err: sftp.ErrSSHFxPermissionDenied, want: storage.ErrPermission},
+		{name: "unsupported", err: sftp.ErrSSHFxOpUnsupported, want: storage.ErrUnsupported},
+		{name: "temporary", err: sftp.ErrSSHFxConnectionLost, want: storage.ErrTemporary},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := backend.translateError(storage.OpStat, "report.md", tt.err)
+			if !storage.IsKind(err, tt.want) {
+				t.Fatalf("translateError() = %v, want kind %s", err, tt.want)
+			}
+		})
+	}
+}