remailers 0.1.0a2__tar.gz

remailers-0.1.0a2/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 JarbasAi
+
+   Full text: https://www.apache.org/licenses/LICENSE-2.0.txt

remailers-0.1.0a2/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: remailers
+Version: 0.1.0a2
+Summary: PGP anonymous-message (nym/remailer) toolkit over Usenet and Tor email.
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/JarbasAl/remailers
+Keywords: remailer,nym,anonymity,pgp,usenet,mixmaster,hsub,esub
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pycryptodomex
+Requires-Dist: PGPy
+Requires-Dist: dateparser
+Requires-Dist: PySocks
+Requires-Dist: requests
+Requires-Dist: usenet
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# remailers
+
+A toolkit for **anonymous messaging** with PGP over Usenet and Tor email:
+hashed/encrypted subjects (hSub/eSub), nym-server (ZAX) registration, and
+SOCKS/Tor SMTP. Built on top of [`usenet`](https://github.com/JarbasAl/usenet).
+
+> For research and privacy education. The public nym/remailer network is largely
+> historical. Treat the bundled server definitions as starting points.
+
+## Install
+
+```bash
+pip install remailers
+```
+
+## Quickstart
+
+Generate (or load) a PGP identity:
+
+```python
+from remailers import Credentials
+
+creds = Credentials("my_key.asc", name="PythonicAnon")
+print(creds.pubkey)
+```
+
+Hashed and encrypted subjects: let a recipient spot a message meant for them
+without revealing the subject:
+
+```python
+from remailers import create_hsub, match_hsub, create_esub, match_esub
+
+hsub = create_hsub("evil dolphin captain")
+assert match_hsub(hsub, "evil dolphin captain")
+
+esub = create_esub("evil dolphin captain", key="shared-secret")
+assert match_esub("evil dolphin captain", "shared-secret", esub)
+```
+
+Post and retrieve anonymous messages via `alt.anonymous.messages`:
+
+```python
+from usenet import UsenetServer
+from remailers import Credentials, AnonBox, create_hsub
+
+creds = Credentials("my_key.asc")
+hsub = create_hsub("evil dolphin captain")
+ciphertext = creds.encrypt("meet at noon")
+
+with UsenetServer("news.neodome.net") as server:
+    server.post(ciphertext, hsub, "alt.anonymous.messages")
+
+inbox = AnonBox(creds, UsenetServer("news.neodome.net"))
+for article in inbox.retrieve_by_subject("evil dolphin captain"):
+    print(article.text)
+```
+
+ZAX nym servers and Tor email are in `remailers.zax` and `remailers.mail`. See
+`examples/`.
+
+## Security notes
+
+- Initialization vectors come from `os.urandom` (`remailers.utils.generate_iv`).
+- hSub uses SHA-256. eSub uses Blowfish for Type-I compatibility: it exists for
+  interop with the legacy remailer ecosystem, not as modern AEAD.
+- Message bodies are protected by PGP (RSA-4096, AES-256), not by the subject
+  scheme.
+
+## Testing
+
+```bash
+pip install -e .[test]
+pytest test/
+```
+
+Tests are offline: subject round-trips, IV entropy, and a PGP encrypt/decrypt
+cycle with a freshly generated key.
+
+## License
+
+Apache-2.0

remailers-0.1.0a2/README.md

@@ -0,0 +1,81 @@
+# remailers
+
+A toolkit for **anonymous messaging** with PGP over Usenet and Tor email:
+hashed/encrypted subjects (hSub/eSub), nym-server (ZAX) registration, and
+SOCKS/Tor SMTP. Built on top of [`usenet`](https://github.com/JarbasAl/usenet).
+
+> For research and privacy education. The public nym/remailer network is largely
+> historical. Treat the bundled server definitions as starting points.
+
+## Install
+
+```bash
+pip install remailers
+```
+
+## Quickstart
+
+Generate (or load) a PGP identity:
+
+```python
+from remailers import Credentials
+
+creds = Credentials("my_key.asc", name="PythonicAnon")
+print(creds.pubkey)
+```
+
+Hashed and encrypted subjects: let a recipient spot a message meant for them
+without revealing the subject:
+
+```python
+from remailers import create_hsub, match_hsub, create_esub, match_esub
+
+hsub = create_hsub("evil dolphin captain")
+assert match_hsub(hsub, "evil dolphin captain")
+
+esub = create_esub("evil dolphin captain", key="shared-secret")
+assert match_esub("evil dolphin captain", "shared-secret", esub)
+```
+
+Post and retrieve anonymous messages via `alt.anonymous.messages`:
+
+```python
+from usenet import UsenetServer
+from remailers import Credentials, AnonBox, create_hsub
+
+creds = Credentials("my_key.asc")
+hsub = create_hsub("evil dolphin captain")
+ciphertext = creds.encrypt("meet at noon")
+
+with UsenetServer("news.neodome.net") as server:
+    server.post(ciphertext, hsub, "alt.anonymous.messages")
+
+inbox = AnonBox(creds, UsenetServer("news.neodome.net"))
+for article in inbox.retrieve_by_subject("evil dolphin captain"):
+    print(article.text)
+```
+
+ZAX nym servers and Tor email are in `remailers.zax` and `remailers.mail`. See
+`examples/`.
+
+## Security notes
+
+- Initialization vectors come from `os.urandom` (`remailers.utils.generate_iv`).
+- hSub uses SHA-256. eSub uses Blowfish for Type-I compatibility: it exists for
+  interop with the legacy remailer ecosystem, not as modern AEAD.
+- Message bodies are protected by PGP (RSA-4096, AES-256), not by the subject
+  scheme.
+
+## Testing
+
+```bash
+pip install -e .[test]
+pytest test/
+```
+
+Tests are offline: subject round-trips, IV entropy, and a PGP encrypt/decrypt
+cycle with a freshly generated key.
+
+## License
+
+Apache-2.0

remailers-0.1.0a2/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "remailers"
+dynamic = ["version"]
+description = "PGP anonymous-message (nym/remailer) toolkit over Usenet and Tor email."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "Apache-2.0"}
+authors = [{name = "JarbasAi", email = "jarbasai@mailfence.com"}]
+keywords = ["remailer", "nym", "anonymity", "pgp", "usenet", "mixmaster", "hsub", "esub"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Communications :: Email",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "pycryptodomex",
+    "PGPy",
+    "dateparser",
+    "PySocks",
+    "requests",
+    "usenet",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/JarbasAl/remailers"
+
+[tool.setuptools.dynamic]
+version = {attr = "remailers.version.__version__"}
+
+[tool.setuptools.packages.find]
+include = ["remailers*"]
+exclude = ["test*", "examples*", "docs*"]
+
+[tool.pytest.ini_options]
+testpaths = ["test"]
+addopts = "-q"

remailers-0.1.0a2/remailers/__init__.py

@@ -0,0 +1,26 @@
+from remailers.esub import match_esub, create_esub
+from remailers.hsub import match_hsub, create_hsub
+from remailers.keys import Credentials
+from remailers.aam import AnonBox
+from remailers.network import Remailer, fetch_live_remailers, parse_stats
+from remailers.cypherpunk import build_chain, final_request, wrap_encrypted
+from remailers.gpg import GPGKeyring, gpg_available
+from remailers.version import __version__
+
+__all__ = [
+    "match_esub",
+    "create_esub",
+    "match_hsub",
+    "create_hsub",
+    "Credentials",
+    "AnonBox",
+    "Remailer",
+    "fetch_live_remailers",
+    "parse_stats",
+    "build_chain",
+    "final_request",
+    "wrap_encrypted",
+    "GPGKeyring",
+    "gpg_available",
+    "__version__",
+]

remailers-0.1.0a2/remailers/aam.py

@@ -0,0 +1,56 @@
+from remailers.keys import PGPError
+from remailers import match_esub, match_hsub
+
+
+class AnonBox:
+    GROUP = 'alt.anonymous.messages'
+
+    def __init__(self, creds, usenet_server, esub_key=None):
+        self.creds = creds
+        self.usenet_server = usenet_server
+        self.esub_key = esub_key
+
+    def _decrypt_into(self, article):
+        """Decrypt the article body in place; return True on success."""
+        decrypted = self.creds.decrypt(article.text)
+        article._body = [line.encode("utf-8")
+                         for line in decrypted.split("\n")]
+        return True
+
+    def retrieve(self, limit=50):
+        """Pull the latest `limit` messages and keep the ones we can decrypt.
+
+        Browses by GROUP rather than NEWNEWS, which public servers disable.
+        """
+        articles = []
+        with self.usenet_server as server:
+            for article in server.get_articles(self.GROUP, limit=limit):
+                if "BEGIN PGP MESSAGE" not in article.text:
+                    continue
+                try:
+                    self._decrypt_into(article)
+                    articles.append(article)
+                except (PGPError, ValueError):
+                    continue
+        return articles
+
+    def retrieve_by_subject(self, subject, limit=200, esubs=True, hsubs=True):
+        """Keep messages whose subject matches `subject` directly or via an
+        hSub/eSub, and that decrypt with our key."""
+        articles = []
+        with self.usenet_server as server:
+            for article in server.get_articles(self.GROUP, limit=limit):
+                matched = (
+                    subject == article.subject
+                    or (hsubs and match_hsub(article.subject, subject))
+                    or (esubs and self.esub_key
+                        and match_esub(subject, self.esub_key, article.subject))
+                )
+                if not matched:
+                    continue
+                try:
+                    self._decrypt_into(article)
+                    articles.append(article)
+                except (PGPError, ValueError):
+                    continue  # subject matched, but not encrypted to our key
+        return articles

remailers-0.1.0a2/remailers/cypherpunk.py

@@ -0,0 +1,102 @@
+"""Build Type-I (Cypherpunk) remailer messages.
+
+A Cypherpunk remailer reads a message whose body is a "pasting-token" block:
+
+    ::
+    Encrypted: PGP
+
+    -----BEGIN PGP MESSAGE-----
+    ...
+    -----END PGP MESSAGE-----
+
+Decrypting that yields another ``::`` block of instructions — ``Anon-To:`` to
+relay to the next hop or final recipient, ``Anon-Post-To:`` to post to a
+newsgroup, ``Latent-Time:`` to delay. Nesting these, each layer encrypted to the
+next remailer's key, forms the onion that hides the path. This module assembles
+that onion; sending the entry message is left to :mod:`remailers.mail`.
+"""
+from typing import List, Optional, Sequence, Tuple
+
+from remailers.keys import encrypt_text
+
+
+def _block(headers: dict, body: str = "") -> str:
+    lines = ["::"]
+    for key, value in headers.items():
+        lines.append(f"{key}: {value}")
+    lines.append("")  # blank line terminates the header block
+    if body:
+        lines.append(body)
+    return "\n".join(lines)
+
+
+def final_request(dest: Optional[str] = None, anon_post_to: Optional[str] = None,
+                  body: str = "", latent: Optional[str] = None,
+                  extra_headers: Optional[dict] = None) -> str:
+    """Build the innermost instruction block delivered by the exit remailer.
+
+    Provide ``dest`` (email) or ``anon_post_to`` (newsgroup).
+    """
+    if not dest and not anon_post_to:
+        raise ValueError("final_request needs dest or anon_post_to")
+    headers = {}
+    if dest:
+        headers["Anon-To"] = dest
+    if anon_post_to:
+        headers["Anon-Post-To"] = anon_post_to
+    if latent:
+        headers["Latent-Time"] = latent
+    if extra_headers:
+        headers.update(extra_headers)
+    return _block(headers, body)
+
+
+def wrap_encrypted(remailer_key, inner: str) -> str:
+    """Encrypt ``inner`` to a remailer's PGP key and wrap it for that remailer."""
+    ciphertext = encrypt_text(remailer_key, inner)
+    return _block({"Encrypted": "PGP"}, ciphertext)
+
+
+def build_chain(hops: Sequence[Tuple[str, object]], dest: Optional[str] = None,
+                anon_post_to: Optional[str] = None, body: str = "",
+                latent: Optional[str] = None, encrypt=None) -> Tuple[str, str]:
+    """Assemble a nested Cypherpunk message through a chain of remailers.
+
+    ``hops`` is an ordered sequence of ``(address, recipient)`` from entry to
+    exit. ``encrypt(recipient, plaintext) -> armored`` does each layer; it
+    defaults to PGPy (``recipient`` is a ``PGPKey``). To reach the real network
+    (DSA/ElGamal keys), pass a GnuPG encryptor — e.g. ``GPGKeyring.encrypt`` with
+    ``recipient`` set to each remailer's address. Returns ``(message,
+    entry_address)`` — send ``message`` to ``entry_address``.
+    """
+    if not hops:
+        raise ValueError("need at least one remailer hop")
+    if encrypt is None:
+        encrypt = encrypt_text
+    inner = final_request(dest=dest, anon_post_to=anon_post_to,
+                          body=body, latent=latent)
+    message = None
+    next_addr = None
+    # build from the exit hop inward
+    for address, recipient in reversed(list(hops)):
+        if message is None:
+            payload = inner                       # exit hop delivers to dest
+        else:
+            payload = _block({"Anon-To": next_addr}, message)  # relay to next hop
+        message = _block({"Encrypted": "PGP"}, encrypt(recipient, payload))
+        next_addr = address
+    return message, hops[0][0]
+
+
+def send_chain(message: str, entry_address: str, user: str, password: str,
+               host: str = "mail.smtp2go.com", port: int = 465,
+               tor: bool = False) -> None:
+    """Deliver an assembled message to the entry remailer over SMTP.
+
+    Needs an email sender (any account, or a Tor-routed SMTP with ``tor=True``).
+    """
+    from remailers.mail import send_email, send_tor_email
+
+    sender = send_tor_email if tor else send_email
+    sender(user, password, entry_address, subject="", contents=message,
+           host=host, port=port)

remailers-0.1.0a2/remailers/esub.py

@@ -0,0 +1,48 @@
+try:
+    # pycryptodomex
+    from Cryptodome.Cipher import Blowfish
+except ImportError:
+    # pycrypto + pycryptodome
+    from Crypto.Cipher import Blowfish
+
+from hashlib import md5
+from remailers.utils import generate_iv
+
+
+def create_esub(text, key, iv=None):
+    """Produce a 192bit Encrypted Subject. The first 64 bits are the
+    Initialization vector used in the Blowfish CFB Mode.  The Subject text
+    is MD5 hashed and then encrypted using an MD5 hash of the Key."""
+    texthash = md5(text.encode("utf-8")).digest()
+    keyhash = md5(key.encode("utf-8")).digest()
+    if iv is None:
+        iv = generate_iv(8)
+    crypt1 = Blowfish.new(keyhash,
+                          Blowfish.MODE_OFB, iv).encrypt(texthash)[:8]
+    crypt2 = Blowfish.new(keyhash,
+                          Blowfish.MODE_OFB, crypt1).encrypt(texthash[8:])
+    return (iv + crypt1 + crypt2).hex()
+
+
+def match_esub(text, key, esub):
+    """Extract the IV from a passed eSub and generate another based on it,
+    using a passed Subject and Key.  If the resulting eSub collides with
+    the supplied one, return True."""
+    # All eSubs should be 48 bytes long
+    if len(esub) != 48:
+        return False
+    # The 64bit IV is hex encoded (16 digits) at the start of the esub.
+    try:
+        iv = bytes.fromhex(esub[:16])
+    except TypeError:
+        return False
+    return create_esub(text, key, iv) == esub
+
+
+if __name__ == "__main__":
+    key = "key"
+    subject = "text"
+    # new IV for each esub
+    esubs = [create_esub(subject, key) for i in range(10)]
+    for sub in esubs:
+        print(sub, match_esub(subject, key, sub))

remailers-0.1.0a2/remailers/gpg.py

@@ -0,0 +1,80 @@
+"""GnuPG backend for encrypting to real remailer keys.
+
+The live remailer network uses DSA primary keys with ElGamal encryption
+subkeys. PGPy cannot encrypt to ElGamal, so messages destined for actual
+remailers are encrypted by shelling out to GnuPG, which handles those keys
+natively. Our own RSA identity (remailers.keys.Credentials) still uses PGPy.
+"""
+import os
+import shutil
+import subprocess
+import tempfile
+from typing import List, Optional
+
+
+def gpg_available() -> bool:
+    """True if a usable `gpg` binary is on PATH."""
+    exe = shutil.which("gpg")
+    if not exe:
+        return False
+    try:
+        subprocess.run([exe, "--version"], capture_output=True, check=True)
+        return True
+    except (OSError, subprocess.CalledProcessError):
+        return False
+
+
+class GPGKeyring:
+    """A throwaway GnuPG home seeded with a keyring blob.
+
+    Use as a context manager; the temporary home is removed on exit.
+    """
+
+    def __init__(self, keyring_blob: str, gpg_bin: Optional[str] = None):
+        self.gpg = gpg_bin or shutil.which("gpg")
+        if not self.gpg:
+            raise RuntimeError("gpg not found on PATH")
+        self.home = tempfile.mkdtemp(prefix="remailers-gpg-")
+        self._import(keyring_blob)
+
+    def _run(self, args: List[str], data: Optional[bytes] = None) -> subprocess.CompletedProcess:
+        env = dict(os.environ, GNUPGHOME=self.home)
+        return subprocess.run(
+            [self.gpg, "--batch", "--no-tty", "--yes"] + args,
+            input=data, capture_output=True, env=env)
+
+    def _import(self, blob: str) -> None:
+        result = self._run(["--import"], blob.encode("utf-8", "replace"))
+        if result.returncode != 0:
+            raise RuntimeError(f"gpg import failed: {result.stderr.decode()[-200:]}")
+
+    def recipients(self) -> List[str]:
+        """Email addresses of imported keys."""
+        result = self._run(["--list-keys", "--with-colons"])
+        emails = []
+        for line in result.stdout.decode("utf-8", "replace").splitlines():
+            if line.startswith("uid"):
+                uid = line.split(":")[9]
+                if "<" in uid and ">" in uid:
+                    emails.append(uid.split("<", 1)[1].split(">", 1)[0])
+        return emails
+
+    def encrypt(self, recipient: str, plaintext: str) -> str:
+        """Return an ASCII-armored message encrypted to `recipient`."""
+        data = plaintext.encode("utf-8") if isinstance(plaintext, str) else plaintext
+        result = self._run(
+            ["--trust-model", "always", "--armor",
+             "--encrypt", "--recipient", recipient], data)
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"gpg encrypt to {recipient} failed: {result.stderr.decode()[-200:]}")
+        return result.stdout.decode("utf-8")
+
+    def close(self) -> None:
+        shutil.rmtree(self.home, ignore_errors=True)
+
+    def __enter__(self) -> "GPGKeyring":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

remailers-0.1.0a2/remailers/hsub.py

@@ -0,0 +1,60 @@
+from hashlib import sha256
+from remailers.utils import generate_iv
+
+
+def create_hsub(text, iv=None, hsublen=48):
+    """Create an hSub (Hashed Subject). This is constructed as:
+    --------------------------------------
+    | 64bit iv | 256bit SHA2 'iv + text' |
+    --------------------------------------"""
+    # Generate a 64bit random IV if none is provided.
+    if iv is None:
+        iv = generate_iv()
+    if isinstance(iv, str):
+        iv = iv
+    hashed = sha256(iv + text.encode("utf-8")).digest()
+    # Concatenate our IV with a SHA256 hash of text + IV.
+    hsub = iv + hashed
+    return hsub.hex()[:hsublen]
+
+
+def match_hsub(hsub, subject):
+    """Create an hSub using a known iv, (stripped from a passed hSub).  If
+    the supplied and generated hSub's collide, the message is probably for
+    us."""
+    # We are prepared to check variable length hsubs within boundaries.
+    # The low bound is the current Type-I esub length.  The high bound
+    # is the 256 bits within SHA2-256.
+    hsublen = len(hsub)
+    # 48 digits = 192 bit hsub, the smallest we allow.
+    # 80 digits = 320 bit hsub, the full length of SHA256 + 64 bit IV
+    if hsublen < 48 or hsublen > 80:
+        return False
+    iv = iv_from_hsub(hsub)
+    if not iv:
+        return False
+    # Return True if our generated hSub collides with the supplied
+    # sample.
+    return create_hsub(subject, iv, hsublen) == hsub
+
+
+def iv_from_hsub(hsub, digits=16):
+    """Return the decoded IV from an hsub.  By default the IV is the first
+    64bits of the hsub.  As it's hex encoded, this equates to 16 digits."""
+    # We don't want to process IVs of inadequate length.
+    if len(hsub) < digits:
+        return False
+    try:
+        return bytes.fromhex(hsub[:digits])
+    except:
+        # Not all Subjects are hSub'd
+        return False
+
+
+if __name__ == "__main__":
+    subject = "captain dolphin"
+    print("Subject: " + subject)
+    print("Should return True:  %s" % match_hsub(create_hsub(subject),
+                                                 subject))
+    print("Should return False: %s" % match_hsub(create_hsub("subject"),
+                                                 subject))