1 files changed, 65 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cc517ae
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# NymDrop
+
+A modern, Nym-native anonymous submission system — a SecureDrop alternative that
+uses the [Nym mixnet](https://nymtech.net/) as its transport instead of Tor.
+
+The source uses an ordinary browser. There is nothing to install, no onion
+service to reach, and no client-side configuration. Anonymity protection lives in
+the design, not in an obligation on the source to install anything.
+
+## Design
+
+- **Transport:** Nym mixnet only — no Tor. Cover traffic, padding and mixnet
+  unlinkability protect the server side.
+- **Client-side encryption:** submissions are encrypted in the browser with
+  X25519 + HKDF-SHA-256 + AES-GCM-256 (WebCrypto). The server never sees
+  plaintext.
+- **No-log server:** no IP, no timestamps, no metadata persisted. A blind relay
+  forwards ciphertext through the mixnet and keeps nothing on disk.
+- **No third parties:** no CDN, no Cloudflare, no NIST curves, no tracking
+  JavaScript.
+
+See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the full threat model and component
+breakdown.
+
+## Components
+
+| Binary | Role |
+|---|---|
+| `nymdrop` | Public-facing HTTP server + blind relay. Embeds a `nym-client`, accepts encrypted submissions on `POST /submit`, forwards them through the mixnet to the reader's Nym address. |
+| `nymdrop-reader` | Operator-side inbox. Runs a `nym-client`, receives messages from the mixnet, decrypts them with the operator's X25519 private key, and writes submissions to disk. |
+| `nymdrop-source` | Optional SOCKS5-based source helper. |
+
+## Build
+
+The `nym-client` binary is required at build time (embedded via `go:embed`) but
+is **not** committed to keep the repository small. Fetch it first:
+
+```sh
+./scripts/fetch-nym-binaries.sh   # downloads nym-client v1.1.76 (linux/amd64)
+
+go build ./cmd/nymdrop/
+go build ./cmd/nymdrop-reader/
+```
+
+## Run
+
+```sh
+# 1. Start the reader (prints its Nym inbox address and the public key to deploy)
+./nymdrop-reader --id nymdrop-inbox --ws-port 1977
+
+# 2. Start the server, pointing it at the reader's Nym address
+./nymdrop --journalist "<NYM_ADDRESS_FROM_READER>" --static ./static --listen 127.0.0.1:8080
+```
+
+Deploy the reader's public key into `static/crypto.js` so the browser encrypts to
+the right key. Put the server behind TLS in production.
+
+## Status
+
+End-to-end verified: browser/client → HTTP server → Nym mixnet → reader →
+decrypted submission on disk.
+
+## License
+
+[AGPL-3.0](LICENSE).