# TMail.pl
Minimal, Auditable CGI Mail Relay

Copyright (c) 2023-2025
David Peter
Tangent Networks
https://tangentnet.top
---

## Overview

`TMail.pl` is a deliberately minimal CGI mail relay designed for shared web
hosting environments where operators have access only to `cgi-bin` and cannot
install daemons, background services, or third-party libraries.

It accepts form submissions via HTTP POST and relays them as formatted HTML
email using Gmail SMTP with App Password authentication.

This project exists to solve a narrow problem well, without abstraction,
frameworks, or vendor dependency.

---

## Intended Environment

This script is suitable for:

- Shared web hosting
- CGI-based deployments
- Static or server-rendered websites
- Environments without SSH or package managers
- Operators who require deterministic behavior

It is not intended for application frameworks, high-volume mail systems,
or dynamic routing logic.

---

## Core Features

- POST-only request handling
- Referrer validation
- Perl taint mode enabled (`-T`)
- Explicit input untainting
- SMTP header injection prevention
- HTML email formatting
- No JavaScript dependencies
- No database usage
- No third-party APIs beyond SMTP

---

## Configuration

The following values must be configured before deployment:

```perl
my $smtp_user = 'your-relay@gmail.com';
my $smtp_pass = 'your-gmail-app-password';
my $smtp_to   = 'destination@example.com';
my $allowed_origin = qr{^https://example\.com}i;
my $redirect_url   = 'https://example.com/thank-you.html';

File Permissions

Recommended permissions:

chmod 700 TMail.pl

This ensures the script is executable but not readable by other users.

---

Gmail App Password Setup

Gmail requires App Passwords for SMTP relay.

Steps:

1. Log in to your Google Account

2. Navigate to Security

3. Enable 2-Step Verification

4. Open App passwords

5. Create a password for:

   • App: Mail
   • Device: Other (name it after your site or server)

6. Copy the generated 16-character password

7. Use it as $smtp_pass in the script

App Passwords can be revoked independently and grant SMTP-only access.

---

Security Model

Execution Assumptions

• The script executes via CGI and is not served as a static file
• cgi-bin is configured correctly by the hosting provider
• Directory listing is disabled
• Script ownership and permissions prevent cross-user access

Input Handling

• Taint mode enforces trust boundaries
• Inputs are explicitly untainted before use
• CR/LF characters are blocked in SMTP headers
• HTML output is controlled and deterministic

Network Surface

• One outbound SMTP connection
• No inbound sockets
• No background processes
• No webhooks
• No client-side JavaScript

---

Threat Model (Enterprise Summary)

In Scope

• Cross-site form abuse
• SMTP header injection
• Open relay misuse
• Accidental GET invocation
• Information leakage via verbose errors

Out of Scope

• Hosting provider compromise
• Kernel or interpreter vulnerabilities
• Gmail account takeover
• Physical server access
• Compromised DNS or TLS trust anchors

Mitigations

Threat	Mitigation
Open relay abuse	Fixed recipient address
Cross-site posting	Referrer validation
Header injection	CR/LF rejection
XSS in mail body	Controlled HTML output
Credential exposure	Non-readable CGI execution

---

Why This Is Safer Than PHPMailer

PHPMailer is a capable library, but it introduces complexity that is unnecessary and undesirable in CGI-based shared hosting:

• Large codebase increases audit surface
• Dependency management required
• Designed for application frameworks
• Implicit behavior hidden behind abstractions

TMail.pl favors explicit control over flexibility. Every mail operation is visible and linear.

---

Why This Is Safer Than Commercial Form Vendors

Hosted form services typically involve:

• Third-party data custody
• JavaScript execution
• Tracking and analytics
• Vendor lock-in
• External failure domains

With TMail.pl:

• Data flows directly from your server to your mailbox
• No third party sees submissions
• No external services must remain available
• No quotas, dashboards, or billing layers exist

---

Why This Is Safer Than Legacy formmail.pl

Classic formmail.pl scripts are known for:

• Open relay vulnerabilities
• Overly permissive configuration
• Feature sprawl
• Poor maintenance history

TMail.pl intentionally excludes:

• Dynamic recipients
• CC/BCC handling
• Attachments
• Arbitrary template expansion
• Legacy compatibility layers

Reduced surface area is a security feature.

---

Diff Summary: Legacy CGI Mailers vs TMail.pl

Aspect	Legacy CGI Mailers	TMail.pl
Recipient handling	User-controlled	Fixed
Input validation	Minimal or implicit	Explicit
Taint mode	Often disabled	Enforced
Error handling	Verbose	Minimal
Code size	Large	Small
Auditability	Low	High

---

Design Philosophy

This script follows one rule:

If mail flow cannot be reasoned about line-by-line, it is too complex.

There are no background tasks, no queues, and no hidden logic.

---

Warranty and Liability

This software is provided as-is, without warranty of any kind. The author assumes no responsibility for misuse, misconfiguration, or credential exposure.

Users are responsible for securing their hosting environment and credentials.

---

Authorship

Written and maintained by:

David Peter Tangent Networks https://tangentnet.top