> ## Documentation Index
> Fetch the complete documentation index at: https://developers.techwolf.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How SFTP works

A short, non-technical explanation of how SFTP secures file transfer and where
each part of the trust model lives in the TechWolf flow. For full
specifications, see [RFC 4251](https://datatracker.ietf.org/doc/html/rfc4251)
(SSH Protocol Architecture) and
[RFC 4252](https://datatracker.ietf.org/doc/html/rfc4252) (SSH Authentication
Protocol). The
[SSH.com SFTP overview](https://www.ssh.com/academy/ssh/sftp-ssh-file-transfer-protocol)
is a good visual primer.

# What SFTP is

SFTP (SSH File Transfer Protocol) carries file operations over a single
encrypted SSH channel on TCP port 22. The same channel handles authentication,
listing, reading, and writing.

# Keys: who holds what

An SSH keypair has two halves:

* The **private key** proves identity. It must never leave the system that
  owns it.
* The **public key** is not a secret. It can be shared freely. It lets a
  server recognise an inbound private key without revealing anything sensitive.

In the TechWolf self-service flow:

* TechWolf **generates the keypair** in the Console, on the **Keys** tab of a
  server.
* TechWolf **keeps the private key** in its database. The private key is never
  exported and never displayed.
* The customer receives the **public key** and installs it in the
  `authorized_keys` file of the configured user on the SFTP server.
* On every connection, TechWolf signs a server challenge with the private key.
  The customer's SFTP server verifies that signature with the public key it has
  on file. The private key crosses the network only as a signature, never as
  the key material itself.

# Host key: server identity

The customer's SFTP server has its own keypair, separate from the client's.
The server presents its **public host key** every time a client connects.

On the first successful connection, TechWolf captures the SHA256 fingerprint
of that host key and pins it on the connection. Every later connection must
present the same fingerprint, or TechWolf aborts the connection before any
credentials are sent.

This protects against man-in-the-middle attacks: even with valid client
credentials, an attacker cannot impersonate the customer's SFTP server without
also holding the matching host private key.

# The connection flow

```text theme={null}
  TechWolf SFTP worker                              Customer SFTP server
       (client)                                            (server)
           |                                                  |
           |  1. TCP connect on port 22                       |
           | -----------------------------------------------> |
           |                                                  |
           |  2. Server presents its public host key          |
           | <----------------------------------------------- |
           |     Client compares SHA256 fingerprint against   |
           |     the pinned value. Mismatch -> abort.         |
           |                                                  |
           |  3. Client authenticates                         |
           | -----------------------------------------------> |
           |     Signs a challenge with its private key,      |
           |     or sends a password.                         |
           |                                                  |
           |  4. LIST remote folder                           |
           | <----------------------------------------------> |
           |                                                  |
           |  5. GET file, upload to TechWolf storage         |
           | <----------------------------------------------- |
           |                                                  |
```

# Further reading

* [RFC 4251: SSH Protocol Architecture](https://datatracker.ietf.org/doc/html/rfc4251)
* [RFC 4252: SSH Authentication Protocol](https://datatracker.ietf.org/doc/html/rfc4252)
* [OpenSSH `authorized_keys` format](https://man.openbsd.org/sshd.8#AUTHORIZED_KEYS_FILE_FORMAT)