# N2Usenet Architecture

## Components

- `cmd/n2usenet`: process entrypoint, lifecycle, HTTP server.
- `cmd/n2u-check`: SMTP diagnostic helper for direct or SOCKS5-routed checks.
- `internal/config`: environment-driven configuration.
- `internal/nymclient`: optional managed `nym-socks5-client` lifecycle.
- `internal/socks5`: minimal SOCKS5 dialer used for Nym transport.
- `internal/smtpclient`: SMTP + STARTTLS sender over an injected dialer.
- `internal/transporthealth`: cached background readiness state for the complete
  SOCKS, SMTP, TLS, and AUTH path.
- `internal/submit`: HTTP handlers, validation, message construction.
- `internal/storage`: replay cache for Hashcash tokens.
- `internal/assets/web`: embedded template and browser assets.

## Privacy Boundary

The HTTPS server necessarily receives browser connections. It should not persist
source IPs, user agents, raw posts, or submitted identities. Operational logs
must stay generic. Rate limiting uses an in-memory keyed hash of the source
address and resets on process restart. Hashcash replay protection is also
memory-only. The browser-side identity, signature inputs, and compose fields are
kept only in tab memory and cleared after successful send.

## Transport Boundary

The app never dials an SMTP target directly when `N2U_NYM_ENABLED=true`. All
SMTP traffic goes through `N2U_NYM_SOCKS`, normally provided by
`nym-socks5-client`. The MTA boundary uses STARTTLS plus SMTP AUTH. Credentials
are loaded from a root-managed file, not embedded in source or command-line
arguments. SMTP AUTH, the SMTP envelope sender, and the RFC 5322 `Sender:`
header use the fixed N2Usenet service account. The public RFC 5322 `From:`
header instead contains the complete profile identity, `username <email>`, so
Mail2News and newsreaders do not replace it with the transport account. This
profile address is a pseudonymous claim bound to the VFACE tuple and public
key, not verification that the author controls the address domain.

The intended posting chain is:

```text
Browser -> HTTPS n2usenet.virebent.art
N2Usenet -> Nym SOCKS5/requester
Nym requester -> 51.178.55.22:587 SMTP with STARTTLS + AUTH
                (TLS name mail.virebent.art)
mail.virebent.art Postfix -> SPF/DKIM/DMARC signing and relay
mail2news@mail2news.tcpreset.net -> Mail2News gateway
Mail2News -> Tor SOCKS
Mail2News -> peannyjkqwqfynd24p6dszvtchkq7hfkwymi5by5y332wmosy5dwfaqd.onion:119 NNTP
TCPReset INN -> news.tcpreset.net
```

Nym and Tor protect different transport segments. Nym carries the
N2Usenet-to-MTA SMTP connection, with STARTTLS providing authenticated TLS
inside that path. After Postfix relays the message to Mail2News, Mail2News uses
Tor for the final connection to the onion NNTP endpoint. The final Usenet
article is public.

## Deployment Boundary

The current onion PHP app remains deployed under Onion Newsreader `/compose/`.
This app is a separate HTTP service intended to be reverse-proxied by the
public HTTPS frontend for `https://n2usenet.virebent.art`, Apache on `pietro`
in the current production deployment.

Current production split:

- `victor` runs the dedicated Nym network requester and the authenticated
  Postfix submission endpoint.
- `pietro` runs the public HTTPS app and the local `nym-socks5-client`.

The SOCKS destination is the MTA's global IPv4 address because local hostname
resolution on `victor` also returns interface-local addresses that the Nym
requester correctly rejects. TLS identity verification still uses
`mail.virebent.art`.

## Operational Readiness

`/healthz` is a liveness endpoint and does not imply that Nym can deliver.
`/readyz` exposes only the cached result of a periodic transport probe. The
probe performs SOCKS connection, SMTP greeting, STARTTLS, TLS verification,
post-TLS EHLO, and SMTP AUTH, then quits before `MAIL FROM`; it never sends a
message. Keeping the probe out of the request path prevents public health
requests from consuming Nym bandwidth.

Nym gateway registrations are time-limited. The deployment timer runs once a
day and renews the active gateway only when it is within 24 hours of expiry.
The rotation is performed with the application and SOCKS services stopped,
backed up first, and accepted only after the same no-mail transport probe
succeeds.