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 (ECDSA 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

### Starting the Server

The dsfxnode requires a listening host, port, and an identity key (ECDSA private key in PEM format). For example:

```sh
dsfxnode -host localhost -port 8000 -key /path/to/serverkey.pem
```

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

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.

-key (required)
File path to the PEM-encoded ECDSA private key that serves as the server’s master key.

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 ECDSA key in PEM format) and currently supports only the “test” command for checking connectivity to the server.

Client command usage:

```sh
dsfxctl -key /path/to/clientkey.pem test <remote_addr>
```

Where:

-key (required)
Specifies the file path to your client’s PEM-encoded private key.

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#<base64 pubkey>” or “dsfx://127.0.0.1:8000#eyJuIjoiLy8v...`

Example:

```sh
dsfxctl -key ./dsfx-client/masterkey test dsfx://127.0.0.1:8000#eyJuIjoiLy8v..
```

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

### 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.