sftpfs

SftpFs - SFTP FileSystem

The sftpfs package provides bidirectional SFTP support for the absfs ecosystem:

• Client Mode: Access remote SFTP servers as an absfs.FileSystem
• Server Mode: Serve any absfs.FileSystem over SFTP protocol

Features

• Bidirectional: Both client and server implementations
• Secure file operations: All operations encrypted over SSH
• Multiple authentication methods: Password and SSH key authentication
• Standard interface: Client implements absfs.Filer for seamless integration
• Full file operations: Read, write, seek, truncate, and more
• Directory operations: Create, remove, and list directories
• Server mode: Expose any absfs filesystem via SFTP

Install

go get github.com/absfs/sftpfs

Client Usage

Password Authentication

package main

import (
    "log"
    "os"

    "github.com/absfs/sftpfs"
)

func main() {
    // Connect using password
    fs, err := sftpfs.Dial("example.com:22", "username", "password")
    if err != nil {
        log.Fatal(err)
    }
    defer fs.Close()

    // Use like any other filesystem
    f, _ := fs.OpenFile("/remote/path/file.txt", os.O_RDONLY, 0)
    defer f.Close()

    // Read, write, etc.
}

Key-Based Authentication

package main

import (
    "log"
    "os"

    "github.com/absfs/sftpfs"
)

func main() {
    // Read private key
    key, err := os.ReadFile("/home/user/.ssh/id_rsa")
    if err != nil {
        log.Fatal(err)
    }

    // Connect using SSH key
    fs, err := sftpfs.DialWithKey("example.com:22", "username", key)
    if err != nil {
        log.Fatal(err)
    }
    defer fs.Close()

    // Use filesystem operations
    fs.Mkdir("/remote/newdir", 0755)
}

Advanced Configuration

package main

import (
    "log"
    "time"

    "github.com/absfs/sftpfs"
)

func main() {
    config := &sftpfs.Config{
        Host:     "example.com:22",
        User:     "username",
        Password: "password",
        Timeout:  60 * time.Second,
    }

    fs, err := sftpfs.New(config)
    if err != nil {
        log.Fatal(err)
    }
    defer fs.Close()

    // Use filesystem
}

Server Usage

The server mode allows you to expose any absfs.FileSystem over SFTP protocol. This is useful for creating custom file servers, testing, or bridging different storage backends.

Basic Server

package main

import (
    "crypto/rand"
    "crypto/rsa"
    "log"
    "net"

    "github.com/absfs/memfs"
    "github.com/absfs/sftpfs"
    "golang.org/x/crypto/ssh"
)

func main() {
    // Create a filesystem to serve (could be any absfs.FileSystem)
    fs, err := memfs.NewFS()
    if err != nil {
        log.Fatal(err)
    }

    // Generate a host key (in production, load from file)
    privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
    if err != nil {
        log.Fatal(err)
    }
    signer, err := ssh.NewSignerFromKey(privateKey)
    if err != nil {
        log.Fatal(err)
    }

    // Create SFTP server with password authentication
    server := sftpfs.NewServer(fs, &sftpfs.ServerConfig{
        HostKeys: []ssh.Signer{signer},
        PasswordCallback: sftpfs.SimplePasswordAuth("admin", "secret"),
    })

    // Listen and serve
    listener, err := net.Listen("tcp", ":2222")
    if err != nil {
        log.Fatal(err)
    }
    log.Println("SFTP server listening on :2222")
    log.Fatal(server.Serve(listener))
}

Multi-User Authentication

users := map[string]string{
    "alice": "password1",
    "bob":   "password2",
    "carol": "password3",
}

server := sftpfs.NewServer(fs, &sftpfs.ServerConfig{
    HostKeys:         []ssh.Signer{signer},
    PasswordCallback: sftpfs.MultiUserPasswordAuth(users),
})

Public Key Authentication

server := sftpfs.NewServer(fs, &sftpfs.ServerConfig{
    HostKeys: []ssh.Signer{hostKey},
    PublicKeyCallback: func(conn ssh.ConnMetadata, key ssh.PublicKey) (*ssh.Permissions, error) {
        // Verify the public key against your authorized keys
        authorizedKey, _, _, _, err := ssh.ParseAuthorizedKey(authorizedKeysData)
        if err != nil {
            return nil, err
        }

        if ssh.KeysEqual(key, authorizedKey) {
            return nil, nil // Authentication successful
        }
        return nil, fmt.Errorf("unknown public key")
    },
})

Serving Different Filesystems

// Serve local files
osfs, _ := osfs.NewFS()
server := sftpfs.NewServer(osfs, config)

// Serve in-memory files
memfs, _ := memfs.NewFS()
server := sftpfs.NewServer(memfs, config)

// Serve composed filesystems
union := unionfs.New(baseFS, overlayFS)
server := sftpfs.NewServer(union, config)

Testing

Unit Tests

Unit tests use mock interfaces and do not require an SFTP server:

go test -v ./...

Integration Tests

Integration tests require a running SFTP server. The project includes Docker Compose configuration for easy setup:

# Start the SFTP server
docker-compose up -d

# Run integration tests
go test -v -tags=integration ./...

# Stop the server
docker-compose down

The Docker setup uses atmoz/sftp with the following credentials:

• Host: localhost:2222
• Username: testuser
• Password: testpass

Benchmarks

Run benchmarks to measure performance:

go test -bench=. -benchmem ./...

Coverage

Check test coverage:

go test -cover ./...

Security Note

The current implementation uses ssh.InsecureIgnoreHostKey() which skips host key verification. For production use, you should implement proper host key verification to prevent man-in-the-middle attacks.

Example of implementing host key verification:

// For production, implement proper host key callback
hostKeyCallback, err := knownhosts.New("/home/user/.ssh/known_hosts")
if err != nil {
    log.Fatal(err)
}
// Use hostKeyCallback in your SSH configuration

API Reference

Client Types and Methods

FileSystem Methods

File Methods

Server Types and Methods

Server

ServerConfig

Helper Functions

absfs

Check out the absfs repo for more information about the abstract filesystem interface and features like filesystem composition.

LICENSE

This project is governed by the MIT License. See LICENSE