dsfx/README.md

# dsfx: Distributed Secure File Exchange

dsfx is a robust, secure, and distributed file exchange system written in Go. Designed from the ground up for safety, performance, and ease of maintenance, dsfx enables encrypted file transfers between nodes in a distributed network. Its streamlined architecture ensures that file exchanges are both secure and efficient.

---

## Features

- **End-to-End Security:** Uses modern cryptographic primitives (ED25519 keys, for example) to ensure that all file exchanges are encrypted and authenticated.
- **Distributed Architecture:** Designed for secure file exchange across multiple nodes with built-in support for key-based authentication.
- **High Performance:** Optimized for low latency and high throughput, with a focus on reliable and predictable behavior.
- **Administrative and Test Tools:** The dsfx client can be used to test connectivity and perform preliminary administrative actions against the dsfx server.
- **Easy Integration:** Built in Go with minimal external dependencies, dsfx is simple to deploy and integrate into existing systems.

---

## Installation

### Prerequisites

- Go 1.24 or later is required.
- Git

### Build from Source

Clone the repository:

```sh
git clone https://koti.casa/numenor-labs/dsfx.git
cd dsfx
```

Build the project:

```sh
go build -o dist/ ./cmd/...
```

You can also install the executables to your $GOPATH/bin:

```sh
go install ./cmd/...
```

---

## Usage

**WARNING:** The dsfx project is still in development and should not be used in a
production environment. The following instructions are for testing and development
purposes only. The system implements it's own cryptography and has not been audited
by a third party.

Currently, the target audience consists of developers, testers, and security
researchers who are interested in secure file exchange systems. We also welcome
homelab enthusiasts, but do **not recommened** using this software as your sole
method of secure backup.

### Starting the Server

The dsfxnode requires a listening host and port. On it's first run, it will
attempt to initialize a new folder at the directory specified by the `-dir` flag.
The default value of this is `$HOME/.dsfxnode`. The server will then generate a
ED25519 key pair, and begin listening for incoming connections. Your
private key is stored unencrypted at `<-dir>/key`. Please ensure that
this file is kept secure. Currently the worst case scenario if this file is lost
is that you will need to generate a new key pair, and existing connections will
not recognize your server anymore. You will still have access to all of your data
once the new key is generated and the server is restarted.

```sh
dsfxnode -host localhost -port 8000
```

> Note, if you need to generate a new ED25519 key, you can use the following command: `go run ./tool/genkey > path/to/key`

Command-line flags for dsfx-server:

-host (default "localhost")
The host interface on which the server will listen.

-port (default 8000)
The TCP port on which the server will accept connections.

-dir (default "~/.dsfxnode")
The directory where the server will store files. The default is `$HOME/.dsfxnode`.

-log (default "<-dir>/log")
The file path where the server will write logs. As a special case, you may run
`-log stdout` to write logs to standard output.

Once started, the server will bind to the specified host and port and wait for incoming secure file exchange (or other test) connections. When a client connects, the initial payload (up to 1024 bytes) from the client is read and logged.

### Running the Admin Client

The dsfxctl uses a private key for the client (also an ED25519 key in Base64 format) and currently supports only the “test” command for checking connectivity to the server.

Client command usage:

```sh
dsfxctl test <remote_addr>
```

Where:

Command-line flags for dsfx-server:

-dir (default "~/.dsfxctl")
The directory where the client will store files. The default is `$HOME/.dsfxctl`.

The command-line arguments for the dsfx-client are as follows:

Command: test
Tests the connection against the remote dsfx-server instance.

<remote_addr>:
The address of the server in the format “dsfx://IP:PORT#PUBLIC_KEY_BASE_64”.
For example, `dsfx://127.0.0.1:8000#m8I9H6qf2RLMhwnSHjJAkxq2Zeuv6a+/JDdJB9C6O24=`.

Example:

```sh
dsfxctl test dsfx://127.0.0.1:8000#m8I9H6qf2RLMhwnSHjJAkxq2Zeuv6a+/JDdJB9C6O24=
```

If no command or an unrecognized command is provided, the client will print a brief usage message and exit.

The first time you run the client, it will generate a new ED25519 key pair and
store it in the file `<-dir>/key`. This key pair is used for all subsequent
connections to the server.

### Help and Usage Information

For quick help, simply pass the -h flag:

```sh
dsfxctl -h
dsfxnode -h
```

This will display the usage information along with available flags.

---

## Contributing

Contributions to dsfx are welcome and encouraged!

### How to Contribute

1. **Fork the Repository:** Create your own branch from the latest code in `main`.
2. **Make Your Changes:** Follow the [TigerStyle for Go](./tigerstyle.md) guidelines to ensure code consistency and quality.
3. **Write Tests:** Ensure that new features and bug fixes include proper tests.
4. **Submit a Pull Request:** Document your changes clearly in your pull request.

### Reporting Issues

Please use the Git repository's issue tracker to report bugs or to suggest new features. Provide as much detail as possible to help reproduce and address any issues.

---

## License

dsfx is distributed under the MIT License. See [LICENSE](./LICENSE) for details.