sftp

github.com/pkg/sftp implements the SSH File Transfer Protocol (SFTP) in pure Go, layered directly on top of golang.org/x/crypto/ssh. It exposes a Client type whose API mirrors the standard library’s os package (Open, Create, Stat, Walk, and friends), so Go programs already familiar with local file I/O can start transferring files over an existing SSH connection with minimal new API surface to learn.

Beyond the client, the package also ships a full SFTP server implementation, including a lower-level Server for classic filesystem proxying and a request-based Handler abstraction (FileReader, FileWriter, FileCmder, FileLister) that lets applications expose an arbitrary virtual filesystem — backed by cloud storage, a database, or anything else — over the SFTP protocol without touching wire-format code directly.

What You Get

• os-like Client API - Open, Create, Stat, Lstat, Walk, Rename, and other familiar filesystem calls work directly over an SSH connection.
• Concurrent reads and writes - configurable concurrent request pipelining for faster large-file transfers, with options to tune packet size and in-flight request count.
• Full SFTP server - a low-level Server for serving a real filesystem plus a Handler-based request-server for exposing any custom backend as SFTP.
• Client and server on one wire-protocol implementation - both sides share the same packet encoding/decoding code, so protocol changes stay consistent.
• OpenSSH extension support - hardlink@openssh.com, posix-rename@openssh.com, and statvfs@openssh.com extensions are implemented and can be toggled via SetSFTPExtensions.

Common Use Cases

• Automated file transfer in CI/CD or ops tooling - a Go service pulls or pushes build artifacts to a remote host over SFTP without shelling out to sftp/scp binaries.
• Backup and sync agents - a Go daemon walks a remote directory tree and mirrors files locally (or vice versa) using the Walk and ReadDir APIs.
• Building a custom SFTP-facing service - a team implements the FileReader/FileWriter/FileLister interfaces to serve objects from S3 or a database as if they were a normal SFTP filesystem, without writing any SSH or wire-protocol code.
• Embedding an SFTP subsystem in an SSH daemon - a Go-based SSH server uses sftp.Server to handle the ‘sftp’ subsystem request from connecting clients.

Under The Hood

Architecture The package splits cleanly into a client layer (client.go, exposing an os-package-shaped Client type), a server layer with two flavors — a low-level Server (server.go) that proxies a real filesystem and a higher-level request-server (request.go, request-interfaces.go) built around small Handler interfaces (FileReader, FileWriter, FileCmder, FileLister) — and a shared wire-protocol layer (packet.go, packet-manager.go, internal/encoding/ssh/filexfer) that both sides use to encode and decode SSH_FXP_* packets. Concurrency on the server is handled by a worker-pool-backed packetManager (SftpServerWorkerCount workers) that dispatches requests in parallel but still returns responses in the order clients expect. Because client and server share the same packet-encoding package, a change to the wire format ripples through both sides rather than risking drift between two independent implementations.

Tech Stack Built as a standard Go module (go.mod targets Go 1.25) with golang.org/x/crypto/ssh as the only hard external dependency for the underlying SSH transport — this package implements just the SFTP subsystem on top of it. golang.org/x/sys backs POSIX-specific attribute handling (attrs_unix.go), github.com/kr/fs supplies the Walker interface for directory traversal, and github.com/stretchr/testify is used in tests. CI (GitHub Actions) runs the suite across Ubuntu and macOS on two Go versions plus a 32-bit GOARCH job, and a separate CIFuzz workflow continuously fuzzes the packet decoder via OSS-Fuzz. As a library, it has no deployment target of its own — it’s linked into whatever Go binary or daemon needs SFTP support.

Code Quality The repo carries 18 _test.go files, including integration tests that exercise a real SFTP server/client round trip (client_integration_test.go, server_integration_test.go) and a Makefile target that runs the full suite under the race detector. Errors are explicit and typed rather than opaque strings: StatusError wraps the protocol’s numeric SFTP status code and exposes it via FxCode(), while unexpectedPacketErr, unexpectedIDErr, and unexpectedVersionErr give callers structured detail on protocol mismatches. Public API naming deliberately tracks the standard library’s os package to minimize the learning curve for Go developers. There’s no dedicated linter config beyond go vet/gofmt conventions, but the combination of integration tests, race testing, and continuous fuzzing is well above typical library standards.

What Makes It Unique The most distinctive piece is the request-server abstraction: rather than only proxying a literal filesystem, applications can implement a handful of small interfaces (FileReader, FileWriter, FileCmder, FileLister) to expose an entirely virtual filesystem — backed by cloud storage, a database, or generated content — as a standards-compliant SFTP endpoint, with no wire-protocol code required on the consumer’s side. Supporting infrastructure like the allocator (reducing buffer churn on hot read/write paths) and the ordered packet manager (allowing concurrent request handling while preserving in-order responses) reflect mature engineering around a long-established protocol rather than a novel one — the SFTP specification itself predates this implementation by years, but the client/server package pairing and pluggable backend model are what set it apart from simpler SFTP wrappers.