storage-kernel-provider-sftp

SFTP provider for Storage Kernel.

This provider maps StorageLocation.directory to a remote root directory and StorageLocation.prefix to a namespace below that root.

Install

uv add storage-kernel-contracts storage-kernel-provider-sftp

Usage

from storage_kernel.contracts import StorageClientOptions, StorageLocation
from storage_kernel.provider_sftp import SftpStorageProviderOptions, create_sftp_storage_client

storage = create_sftp_storage_client(
    StorageClientOptions(location=StorageLocation(directory="/upload", prefix="prod")),
    SftpStorageProviderOptions(
        host="sftp.example.com",
        username="storage",
        password="secret",
        known_hosts_path="/etc/ssh/storage_known_hosts",
    ),
)

await storage.send_content("docs/readme.txt", "Hello")

Signed URLs are not supported by SFTP and raise a normalized capability error.

Provider Options

Capabilities

• full binary and text reads/writes
• remote read streams and writable upload streams
• recursive directory reads and deletes
• same-provider native copy through the SFTP client
• password, private-key and passphrase-protected private-key authentication
• explicit known-host, fingerprint or custom host-key verification
• public URLs when public_base_url is configured

Exactly one host identity policy is required when the provider creates the paramiko client. An injected client owns its connection policy. Set dangerously_disable_host_key_verification=True only for controlled environments where host identity verification is intentionally bypassed, such as disposable local integration servers.

When private_key is provided, invalid key content or a wrong passphrase fails as a configuration error; the provider does not silently discard the key and fall back to another credential source.