From c1decadb590c4d79d92bcc4df7772119a5c91244 Mon Sep 17 00:00:00 2001 From: Gab Virebent Date: Sat, 22 Aug 2026 20:36:56 +0200 Subject: Initial Aegis Usenet client release --- README.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..ac1d12b --- /dev/null +++ b/README.md @@ -0,0 +1,103 @@ +# Aegis + +Aegis is a desktop Usenet reader written in Go with Fyne. It connects to an +NNTP server directly or through SOCKS5, supports implicit TLS, optional +`AUTHINFO USER/PASS` authentication, group discovery, local subscriptions, +overview search, article retrieval, and text article posting. + +## Group population + +Before subscribing, Aegis displays an estimated post count for every group +returned by `LIST ACTIVE`. The estimate is `high - low + 1`. NNTP article +numbers can contain gaps, so this is an upper-bound style estimate rather than +a guaranteed count. After selecting a group, the server's `GROUP` response is +used for the current article count. + +## Build and test + +```sh +gofmt -w . +go test ./... +go test -race ./... +go vet -buildvcs=false ./... +go build -buildvcs=false -o aegis . +``` + +The `-buildvcs=false` option is useful when the source directory is not a Git +working tree. + +## Configuration and credentials + +Settings are stored in the user configuration directory as +`aegis/config.json` with mode `0600`. The NNTP password is never written to +that file and remains only in memory for the current application run. + +TLS certificate validation is enabled by default. The Settings screen has an +explicit `Do not verify the TLS certificate` opt-in for local testing or a +pinned/trusted connection that cannot present a verifiable certificate. It can +expose account credentials and article traffic to a man-in-the-middle and +should not be enabled on an untrusted network. + +## Identity and message cryptography + +The posting profile is VFace-compatible but optional for publishing. Its +username, email address, and canonical Ed25519 public key are joined as +`username|email|public-key`. That exact string produces the 48x48 transparent +PNG identicon through the existing Ch1ffr3punk `identicon-cli` executable. +Aegis accepts no uploaded or alternate profile image and no image format other +than the validated PNG. It publishes the SHA-256 identity hash, the SHA-256 +hash of the PNG, and the verification link +`https://identicons.virebent.art` together with `Face:` and the interoperable +`X-Ed25519-Pub` header. Aegis looks first at +`/home/gabriel1/Projects/identicons/identicons-cli`, then at the configured +`AEGIS_IDENTICON_CLI` path and other standard locations. The executable must +return a 48x48 PNG as base64. Aegis does not embed the identicon GUI. + +Age is the software encryption format. OpenPGP is not exposed as a standalone +software format: it is reserved for the YubiKey OpenPGP integration. The +optional VFace profile generates an Ed25519 identity and stores it in an +age-encrypted local vault protected by a user password of at least 12 +characters. + +The composer keeps the classic Usenet path as the default. It sends RFC 5322 +and MIME-compatible text articles directly to NNTP, with UTF-8 `8bit` text, +canonical CRLF line endings, and a generated `Message-ID`. Optional composer +modes can sign the canonical body with an Ed25519 key, encrypt the body with +age (native X25519 or SSH Ed25519/RSA recipients), or do both. These modes add +`X-Aegis-*` metadata, +including the inline verification key, its SHA-256 fingerprint, and an +optional HTTPS key URL. The URL is metadata only and is never fetched +automatically. + +Ed25519 is used for signatures, not encryption. The age recipient must be an +encryption key, and private keys are supplied for the current operation only. +The optional SURB integration remains a separate future task and is not part +of classic Usenet posting. + +TLS connections require TLS 1.2 or 1.3. For TLS 1.2, Aegis offers only +ECDHE-AES-GCM suites. Go does not expose TLS 1.3 cipher-suite selection, so a +TLS 1.3 connection can still negotiate the platform's ChaCha20-Poly1305 +suite. Deployments that require GCM exclusively must cap the NNTP server at +TLS 1.2. + +## Current limits + +- implicit TLS and STARTTLS are supported; COMPRESS DEFLATE is deliberately + rejected whenever TLS is enabled and is available only for cleartext NNTP; +- SOCKS5 username/password authentication is not exposed in the interface; +- at most the latest 500 overview records are loaded per group; +- posting creates MIME 1.0 text articles with UTF-8 and `8bit` by default; + attachment file selection remains pending; article lines are validated at a maximum of 998 + octets and sent with canonical CRLF line endings; +- composer supports age and optional VFace Ed25519 signing; OpenPGP remains + reserved for the YubiKey integration; +- SMTP mail2news delivery supports cleartext, implicit TLS or STARTTLS. It + reuses the single NNTP proxy configuration, and SOCKS5 routing is required + for `.onion` hosts; the SMTP password is session-only; +- subscriptions are local Aegis preferences, because NNTP itself has no + standard server-side subscription command. + +The complete-client audit and prioritized roadmap are in +[`docs/client-feature-audit.md`](docs/client-feature-audit.md). Optional +features remain part of the main Aegis binary for now, without a runtime +plugin directory. -- cgit v1.2.3