==========================================================================
              MYSTIC EMAIL VERIFICATION RELAY v1.0
==========================================================================

PURPOSE
-------
This utility is a temporary compatibility workaround for Mystic BBS builds
that generate password-reset E-mail with an RFC-invalid Date header.

A message may be generated like this:

    Date: Sun, 30 Aug 2026 00:44:28

Some SMTP providers reject that message because the timezone is missing.
This relay changes only what is needed, for example:

    Date: Sun, 30 Aug 2026 00:44:28 -0400

Mystic connects to this program on localhost. This program then connects
DIRECTLY to your normal external SMTP provider, using the provider settings
in mys_email_veri.ini.

No sSMTP, Postfix, Sendmail, local MTA, or third-party Python package is
required.


PYTHON SUPPORT
--------------
The same relay script supports:

    Python 2.7
    Python 3.x

Python 2.7 is deliberately supported because many Mystic systems still use
it. Python 3 is also supported for newer installations.

For Internet SMTP with TLS, Python 2.7.9 or newer is strongly recommended so
modern SSL/TLS certificate handling is available. Python 2.7.15/2.7.18 are
good choices for systems that remain on Python 2.

The relay is a standalone Python program. It does NOT have to use the same
Python interpreter Mystic uses for MPY scripts.

The included Windows/Linux launchers prefer Python 2.7 when available and
fall back to a compatible Python 3 installation.


REQUIREMENTS
------------
* Mystic BBS with SMTP password-reset E-mail configured/enabled.
* Python 2.7 or Python 3 installed on the same Windows or Linux machine.
* SMTP account/relay information from your E-mail provider.
* The upstream SMTP provider must be reachable from the Mystic machine.

The relay uses only Python's standard library. No pip install is required.


RECOMMENDED INSTALL LOCATION
----------------------------
Keep the entire mys_email_veri directory together.

Windows example:

    C:\mystic\themes\default\scripts\mys_email_veri\

Linux example:

    /mystic/themes/default/scripts/mys_email_veri/

If Mystic is installed somewhere else, use the equivalent path under that
installation's themes/default/scripts directory.

Files included:

    mys_email_veri.py        Main SMTP relay (Python 2.7 / Python 3)
    mys_email_veri.ini       Provider/local configuration
    run_windows.bat          Windows foreground launcher
    run_linux.sh             Linux foreground launcher
    install_systemd.sh       Optional Linux systemd installer
    uninstall_systemd.sh     Removes the optional systemd unit
    SETUP.TXT                This file
    file_id.diz              BBS archive description

The relay also creates mys_email_veri.log after it starts unless file
logging is disabled in the INI.


STEP 1 - CONFIGURE YOUR SMTP PROVIDER
-------------------------------------
Open mys_email_veri.ini in a text editor and edit the [upstream] section.

Example for a provider using STARTTLS on port 587:

    [upstream]
    host = smtp.yourprovider.com
    port = 587
    security = starttls
    authenticate = yes
    username = you@example.com
    password = your_smtp_password
    timeout = 30
    envelope_from =

Valid security values are:

    starttls   Usually port 587. Connect normally, then upgrade with TLS.
    ssl        Usually port 465. TLS is used from the initial connection.
    none       No encryption. Normally only for a trusted local/internal
               SMTP relay. Do not use this across the Internet unless you
               specifically know your provider requires it.

If your provider does not require SMTP authentication:

    authenticate = no
    username =
    password =

Normally leave envelope_from blank. Mystic's SMTP envelope sender will then
be preserved. If your provider specifically requires every message to use a
particular authenticated envelope sender, set that address there.

IMPORTANT: mys_email_veri.ini contains your SMTP password in plain text.
Do not distribute your configured INI file. Protect access to the mod folder.


STEP 2 - TEST THE RELAY BEFORE CHANGING MYSTIC
----------------------------------------------
WINDOWS:

From a Command Prompt, change to the mod directory and run:

    run_windows.bat

The launcher tries Python in this general order:

    Python 2.7 through the Windows py launcher
    C:\Python27\python.exe
    python2.7 / python2 in PATH
    python in PATH
    Python 3 through the Windows py launcher

You may also start it directly, for example:

    C:\Python27\python.exe mys_email_veri.py

or:

    py -2 mys_email_veri.py

or:

    py -3 mys_email_veri.py


LINUX:

From the mod directory:

    ./run_linux.sh

The launcher prefers python2.7/python2 and then tries python3/python.

You may also start it directly, for example:

    python2.7 mys_email_veri.py

or:

    python3 mys_email_veri.py


A successful startup looks similar to:

    Mystic Email Verification Relay v1.0 starting under Python 2.7.18
    Listening on 127.0.0.1:2525
    Upstream SMTP: smtp.yourprovider.com:587 ...

Leave this window/terminal running during the first Mystic test.

If the program exits immediately, check mys_email_veri.log and verify the
INI settings.


STEP 3 - POINT MYSTIC AT THE LOCAL RELAY
----------------------------------------
Open Mystic's configuration utility and find the SMTP Send/password-reset
E-mail settings.

Keep SMTP sending enabled, but change Mystic's SMTP connection to the local
relay:

    SMTP Host        : 127.0.0.1:2525
    SMTP Login       : [blank]
    SMTP Password    : [blank]
    SMTP Auth Type   : None
    SMTP Use SSL/TLS : No

Wording may vary slightly by Mystic build.

The important part is:

    Host/port = 127.0.0.1:2525
    No authentication between Mystic and this relay
    No TLS between Mystic and this relay

The localhost connection never leaves the computer. The relay itself uses
your configured encryption/authentication when it contacts the real SMTP
provider.


STEP 4 - TEST A MYSTIC PASSWORD RESET
-------------------------------------
Use Mystic's Internet E-mail password reset normally.

The relay log should show something similar to:

    Local SMTP connection from 127.0.0.1
    Fixed Date header: ... -> ... -0400
    Relaying <...> to <...> through smtp.provider.com:587 (starttls)
    Upstream SMTP server accepted message

The message body, reset code, and SMTP password are NOT written to the log.

Mystic is only told that the message was accepted if the upstream SMTP
transaction succeeds. If the provider rejects the message, Mystic receives
an SMTP failure response instead.


RUNNING AUTOMATICALLY - WINDOWS
-------------------------------
OPTION A - START IT FROM YOUR BBS STARTUP/BATCH FILE

If you already use a batch file to start Mystic or related services, you can
start the relay from that file.

Python 2.7 example:

    start "Mystic Email Relay" /min C:\Python27\python.exe "C:\mystic\themes\default\scripts\mys_email_veri\mys_email_veri.py"

Python 3 example:

    start "Mystic Email Relay" /min python "C:\mystic\themes\default\scripts\mys_email_veri\mys_email_veri.py"

Use paths appropriate for your system.

Do not start a second copy if one is already running.


OPTION B - RUN run_windows.bat MANUALLY

Double-click run_windows.bat whenever Mystic starts. Leave the window open.
This is useful for initial testing but is not ideal for an unattended BBS.


OPTION C - WINDOWS TASK SCHEDULER

1. Open Task Scheduler.
2. Select "Create Task".
3. Give it a name such as:

       Mystic Email Verification Relay

4. Select "Run whether user is logged on or not" if appropriate.
5. Create a trigger for "At startup".
6. Create an action to start the Python executable directly.

   Python 2.7 Program/script example:

       C:\Python27\python.exe

   Arguments:

       "C:\mystic\themes\default\scripts\mys_email_veri\mys_email_veri.py"

   Start in:

       C:\mystic\themes\default\scripts\mys_email_veri

Use the actual locations of Python and Mystic on your system.

To locate Python from a Command Prompt, try:

    where python
    where python2
    py -0p

Do NOT also run run_windows.bat if Task Scheduler is already running the
relay, or the second copy will fail because port 2525 is already in use.


RUNNING AUTOMATICALLY - LINUX
-----------------------------
OPTION A - SYSTEMD (RECOMMENDED)

From the mys_email_veri directory:

    ./install_systemd.sh

The installer searches for Python 2.7 first, then a compatible Python 3,
and creates/enables:

    mys-email-veri.service

Check status:

    sudo systemctl status mys-email-veri.service

Follow the systemd log:

    sudo journalctl -u mys-email-veri.service -f

The mod's own rotating log remains available as mys_email_veri.log.

To uninstall ONLY the systemd service:

    ./uninstall_systemd.sh

The uninstall script does not delete the mod files or INI.


OPTION B - CRON @REBOOT

If you prefer cron rather than systemd, add ONE @reboot entry using the
absolute path to whichever Python interpreter you want to use.

Python 2.7 example:

    @reboot /usr/bin/python2.7 /mystic/themes/default/scripts/mys_email_veri/mys_email_veri.py >/dev/null 2>&1

Python 3 example:

    @reboot /usr/bin/python3 /mystic/themes/default/scripts/mys_email_veri/mys_email_veri.py >/dev/null 2>&1

Use your actual Mystic and Python paths. Do not use cron at the same time as
the systemd service.


OPTION C - YOUR OWN STARTUP/BASH SCRIPT

You may start mys_email_veri.py from an existing BBS boot/startup shell
script. For example:

    /usr/bin/python2.7 /mystic/themes/default/scripts/mys_email_veri/mys_email_veri.py &

The Python process must remain running while Mystic is available.

For unattended use, systemd is generally preferable because it can restart
the relay automatically after a failure.


LOCAL LISTENER / SECURITY
-------------------------
The relay is deliberately restricted to IPv4 localhost.

Default:

    listen_host = 127.0.0.1
    listen_port = 2525

The program will REFUSE to start if listen_host is changed to an external
address such as 0.0.0.0 or a LAN IP. This is intentional so the utility
cannot accidentally become an Internet-accessible/open SMTP relay.

Mystic-to-relay traffic is not encrypted because it stays entirely on the
same computer through the loopback interface.

Relay-to-provider traffic should normally use STARTTLS or SSL as required by
your provider.

Protect mys_email_veri.ini because it contains SMTP credentials.

Linux users may additionally restrict its permissions, for example:

    chmod 600 mys_email_veri.ini

provided the account running the relay can still read it.


PYTHON 2.7 TLS NOTE
-------------------
Python 2.7.9 and later added substantially improved SSL/TLS support. If you
are using an older Python 2.7 release, upgrade to at least 2.7.9 before using
this relay with an Internet SMTP provider.

The script uses certificate-validating SSL context support when the installed
Python provides it. There is intentionally no "ignore certificate errors"
option.


LOGGING
-------
By default logs are written to:

    mys_email_veri.log

The log rotates automatically. Defaults are:

    level   = INFO
    max_kb  = 512
    backups = 3

The relay does NOT log:

* SMTP passwords
* Authentication data
* Mystic password-reset codes
* E-mail message bodies

It logs envelope sender/recipient addresses and provider/server status so
SMTP problems can be diagnosed.


HOW THE DATE FIX WORKS
----------------------
Mystic may send:

    Date: Sun, 30 Aug 2026 00:44:28

The relay parses that as a local date/time and obtains the appropriate UTC
offset from the operating system. It then sends, for example:

    Date: Sun, 30 Aug 2026 00:44:28 -0400

The offset is NOT hard-coded. The code uses the operating system's local
standard/daylight time information, including on older Python 2.7 Windows
systems where strftime("%z") may not be dependable.

If Mystic already generates a Date header with a timezone, the relay leaves
that Date header alone.

If a message contains no Date header at all, the relay adds a valid current
Date header as a defensive fallback.

If duplicate Date headers are encountered, later duplicates are removed.


TROUBLESHOOTING
---------------
"Address already in use" / port 2525 unavailable:

    Another copy of the relay is probably already running, or another
    program is using port 2525. Do not run the manual launcher at the same
    time as systemd/Task Scheduler.

Mystic reports it cannot send E-mail and the relay logs nothing:

    Verify Mystic is pointing to 127.0.0.1:2525 with local authentication
    and SSL/TLS disabled. Verify the relay is running.

Mystic tries STARTTLS against the local relay:

    Disable SSL/TLS in Mystic's local SMTP settings. Encryption is applied
    by the relay when it connects to the external provider.

Upstream error 535 / authentication failure:

    Check username/password and your provider's requirements. Some providers
    require an application-specific password rather than the normal account
    password.

TLS/certificate failure:

    Confirm security= and port= match your provider. On Python 2, use 2.7.9
    or newer. The relay intentionally has no option to bypass bad certificates.

Upstream 4xx/5xx rejection after the Date fix:

    The provider is rejecting the message for another reason. Check the
    provider's SMTP policy and the relay log/error code.

Mystic says the message was sent but nothing arrives:

    First verify the relay logged "Upstream SMTP server accepted message".
    If so, check spam/junk filtering and the upstream provider's delivery
    logs if available.


WHEN MYSTIC IS FIXED
--------------------
This utility is intended as a compatibility workaround. If a later Mystic
build generates an RFC-valid Date header and your SMTP provider accepts
Mystic mail directly, the relay can be removed.

To revert:

1. Stop/disable this relay.
2. Restore your real SMTP host, login, authentication, and TLS settings in
   Mystic itself.
3. Test a password-reset E-mail directly from Mystic.

If you leave the relay in place after Mystic begins generating a correct
Date header, it will detect the existing timezone and leave that header alone.


NOTES FOR SYSOPS / REDISTRIBUTION
---------------------------------
Do not include your edited mys_email_veri.ini when redistributing the mod.
It contains your SMTP credentials.

A clean distribution archive should contain the original placeholder INI.

==========================================================================
