Metadata-Version: 2.5
Name: storage-kernel-provider-sftp
Version: 0.1.0a1
Summary: SFTP provider package for Storage Kernel.
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: paramiko
Requires-Dist: storage-kernel-contracts<0.2.0,>=0.1.0a1
Requires-Dist: storage-kernel-core<0.2.0,>=0.1.0a1
Description-Content-Type: text/markdown

# 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

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

## Usage

```python
from storage_kernel.contracts import StorageClientOptions, StorageLocation, StoragePath
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(StoragePath("docs/readme.txt"), "Hello")
```

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

## Provider Options

| Option | Purpose |
| --- | --- |
| `host` | SFTP server host |
| `port` | SFTP server port, defaulting to `22` |
| `username` | Username for authentication |
| `password` | Password authentication or private-key passphrase companion |
| `private_key` | Private key content as `str` or `bytes` |
| `private_key_path` | Path to a private key file |
| `passphrase` | Private key passphrase |
| `known_hosts_path` | OpenSSH `known_hosts` verification file |
| `host_key_sha256` | OpenSSH `SHA256:<base64>` host fingerprint |
| `host_verifier` | Custom host-key verification callable |
| `dangerously_disable_host_key_verification` | Explicit unsafe bypass |
| `root_directory` | Fallback root when `StorageLocation.directory` is absent |
| `public_base_url` | Enables `get_public_url` for externally served files |
| `client` | Optional caller-owned SFTP transport |

## 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 transport
- 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 transport. An injected transport 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.
