Initial import: n2usenet HTTPS/Nym Usenet gateway

1 files changed, 109 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2e7f835
--- /dev/null
+++ b/README.md
@@ -0,0 +1,109 @@
+# N2Usenet HTTPS/Nym
+
+N2Usenet HTTPS/Nym is the standalone clearnet-facing web gateway for posting to
+Usenet through the existing TCPReset Mail2News and NNTP infrastructure.
+
+It is intentionally separate from the onion `/compose/` deployment. M2Usenet
+remains the onion-only compose UI integrated into Onion Newsreader; N2Usenet is
+the standalone HTTPS/Nym service for `n2usenet.virebent.art`.
+
+## Flow
+
+```text
+Browser
+  -> HTTPS n2usenet.virebent.art
+  -> N2Usenet Go backend
+  -> local nym-socks5-client
+  -> Nym network requester
+  -> SMTP mail2news.tcpreset.net:25 STARTTLS
+  -> mail2news@mail2news.tcpreset.net
+  -> Mail2News gateway
+  -> news.tcpreset.net NNTP
+```
+
+## Build
+
+```bash
+go test ./...
+go build -o n2usenet ./cmd/n2usenet
+go build -o n2u-check ./cmd/n2u-check
+```
+
+## Required Configuration
+
+Set these in an environment file or systemd unit:
+
+```text
+N2U_LISTEN=127.0.0.1:8095
+N2U_PUBLIC_BASE_URL=https://n2usenet.virebent.art
+
+N2U_SMTP_HOST=mail2news.tcpreset.net
+N2U_SMTP_PORT=25
+N2U_SMTP_TLS_SERVER_NAME=mail.tcpreset.net
+N2U_SMTP_IMPLICIT_TLS=false
+N2U_SMTP_RECIPIENT=mail2news@mail2news.tcpreset.net
+N2U_SMTP_ENVELOPE_FROM=n2usenet@virebent.art
+N2U_SMTP_HELO=n2usenet.virebent.art
+N2U_MESSAGE_ID_DOMAIN=n2usenet.virebent.art
+
+N2U_IDENTICONS_CLI=/usr/local/bin/identicons-cli
+N2U_REQUIRE_FACE=true
+
+N2U_NYM_ENABLED=true
+N2U_NYM_MANAGED=false
+N2U_NYM_BINARY=/opt/n2usenet/bin/nym-socks5-client
+N2U_NYM_HOME=/var/lib/n2usenet/nym
+N2U_NYM_SOCKS=127.0.0.1:11080
+```
+
+Do not commit provider credentials, SMTP credentials, private keys, or operator
+secrets. The provider address is deployment configuration.
+
+## Notes
+
+- Hashcash replay protection is memory-only and is not written to disk.
+- IP rate limiting uses an in-memory keyed hash and is not persisted.
+- Ed25519 signatures are verified server-side when posts are submitted.
+- `Face:` is mandatory by default: every accepted identity must produce a VFACE
+  header from `username|email|ed25519-public-key`.
+- The browser still generates/loads the Ed25519 identity and signs messages
+  locally. The server never receives the Ed25519 secret key.
+- Browser identity, message fields, and submission state are kept only in tab
+  memory. After a successful send, the UI clears the key material and form
+  inputs immediately.
+- SMTP uses a fixed envelope sender by default, `n2usenet@virebent.art`, so the
+  Mail2News relay does not depend on the user's pseudonymous email passing
+  remote sender policy checks.
+- `/submit` returns `Cache-Control: no-store` and the browser path uses fetch
+  so successful submissions do not leave the full form state in the rendered
+  response page.
+- The app does not add a clearnet fallback to the M2Usenet onion PHP sender.
+- The service now prefers the `N2U_*` environment variable prefix and still
+  accepts legacy `M2U_*` variables during the rollout.
+
+## Current Production Status
+
+As of 2026-07-13 the standalone service is live on `pietro` and the Nym SMTP
+transport is working through a dedicated requester on `victor` and a local
+`nym-socks5-client` on `pietro`.
+
+Working deployment shape:
+
+- `victor` and `rasmus` are SSH aliases for the same host, `51.178.55.22`.
+- `victor` runs `n2usenet-network-requester.service`.
+- `pietro` runs `n2usenet-socks.service` on `127.0.0.1:11080`.
+- `pietro` runs `n2usenet.service` with SMTP target `mail2news.tcpreset.net:25`.
+- `pietro` uses `n2usenet@virebent.art` as the SMTP envelope sender.
+- `cmd/n2u-check` completed SMTP greeting, EHLO, STARTTLS, and TLS 1.3 through
+  the live Nym path on 2026-07-13.
+
+`identicons-cli` is already available on `victor` at `/usr/local/bin/identicons-cli`.
+Its output was checked against the `Ch1ffr3punk/identicons` engine using
+multiple deterministic `username|email|pubkey` inputs; the decoded 48x48 PNG
+outputs matched byte-for-byte.
+
+Direct SMTP checks from `victor` confirm that `mail2news.tcpreset.net` accepts:
+
+- `25` with STARTTLS.
+- `587` with STARTTLS.
+- `465` with implicit TLS.