<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library\mail;
use seekquarry\atto\FileMailStorage;
use seekquarry\atto\MailSite;
use seekquarry\yioop\configs as C;
use seekquarry\yioop\models\MailAliasModel;
use seekquarry\yioop\models\MailSenderAllowModel;
use seekquarry\yioop\models\UserModel;
/**
* Central wiring helper for MailSite. Returns a configured
* instance with authenticator, storage backend, and local
* domain list installed, ready for either of two consumers:
*
* 1. The long-running daemon under Manage Machines, which
* calls listen() on the returned instance to start its
* SMTP and IMAP listeners.
* 2. The Yioop web layer, which calls the direct-API methods
* (listFolders, fetchMessage, appendMessage, and so on)
* against the same storage the daemon serves. Web requests
* never call listen(); they instantiate, operate, return.
*
* Both consumers point at the same WORK_DIRECTORY/mail tree so
* a webmail UI and a Thunderbird IMAP session see consistent
* mailbox state. The factory is intentionally a static helper
* rather than an injected service because there is one set of
* wiring decisions per Yioop install (storage path is a config
* derivative, authenticator is fixed by the project's identity
* model) and no test-time variation worth a DI layer.
*/
class MailSiteFactory
{
/**
* Folder name into which the Spam Insecure posture files mail
* that arrived without TLS from an untrusted sender. Matches
* the Junk folder MailSite creates and maps to the \Junk
* special-use attribute.
*/
const JUNK_FOLDER = 'Junk';
/**
* Local-part of the reserved mailbox that receives unsubscribe mail
* (bot@<first-domain>). The username is reserved at registration so
* no member can take it.
*/
const UNSUBSCRIBE_MAILBOX = 'bot';
/**
* Test-only override. When set to a non-null MailSite, build()
* returns it instead of constructing the production wiring.
* Unit tests use this to substitute a RamMailStorage-backed
* MailSite so they exercise MailSiteMailBackend's logic
* without touching disk or needing a WORK_DIRECTORY.
*
* @var \seekquarry\atto\MailSite|null
*/
protected static $test_override = null;
/**
* Installs (or clears, when $site is null) a test-only
* MailSite that build() should return in place of the real
* production wiring. Tests are expected to clear the
* override in tearDown so subsequent tests see normal
* factory behaviour.
*
* @param \seekquarry\atto\MailSite|null $site the test
* instance to return from build(), or null to clear
*/
public static function setTestOverride($site)
{
self::$test_override = $site;
}
/**
* Returns a handle to the local mail store on disk (the same tree
* the MailSite server reads and writes), so callers such as the
* unsubscribe reader can list and remove messages from a mailbox.
*
* @return object a FileMailStorage rooted at the mail directory
*/
public static function storage()
{
/* FileMailStorage shares its source file with the MailSite
server class, so the autoloader (which looks for a file
named after the class) cannot reach it on its own; loading
MailSite pulls in the whole file and defines it. */
class_exists(MailSite::class);
return new FileMailStorage(C\MAIL_DIR);
}
/**
* Builds the MailSite server: the local mail store, the Yioop user
* authenticator, the local domains it answers for, alias handling
* and (when logging is on) connection hooks.
*
* @return object the configured MailSite, or a test override when
* one has been set
*/
public static function build()
{
if (self::$test_override !== null) {
return self::$test_override;
}
$mail_site = new MailSite();
$mail_site->auth(new YioopUserAuthenticator());
$mail_site->storage(self::storage());
$mail_site->domains(self::localDomains());
$mail_site->aliasResolver(self::resolveAliasOwner(...));
if (C\p('MAIL_LOG_ENABLED')) {
$mail_site->onConnect(self::logConnect(...));
$mail_site->onSecure(self::logSecure(...));
}
if (C\p('MAIL_DELIVERY_SECURITY') === 'spam') {
$mail_site->onMessage(self::junkInsecureMail(...));
}
if (C\p('MAIL_DMARC_ENFORCE')) {
$mail_site->onMessage(self::dmarcEnforce(...));
}
if (!C\p('MAIL_TEST_MODE')) {
$mail_site->onMailFrom(self::rejectIfNotFqdn(...));
$mail_site->onRcptTo(self::rejectIfNotFqdn(...));
}
$mail_site->onOutbound(self::enqueueOutbound(...));
return $mail_site;
}
/**
* Resolves an alias local-part to the username of the Yioop
* user who owns it, or the empty string when the local-part is
* not a registered alias. Wired into MailSite as the alias
* resolver so the atto-namespace server can route alias
* recipients to the owner's mailbox without referencing a
* Yioop model directly. The models are built per call; alias
* resolution happens once per inbound recipient, not in a hot
* loop, so the construction cost is not a concern.
*
* @param string $alias lowercased alias local-part to resolve
* @param string $domain recipient domain the alias must belong
* to
* @return string owning user's username, or '' when not an
* alias
*/
public static function resolveAliasOwner($alias, $domain)
{
$alias_model = new MailAliasModel();
$user_id = $alias_model->userIdForAlias($alias, $domain);
if ($user_id <= 0) {
return '';
}
$user_model = new UserModel();
$username = $user_model->getUsername($user_id);
return is_string($username) ? $username : '';
}
/**
* onMessage hook for the "Spam Insecure" delivery posture.
* When a message arrived without TLS and the receiving user
* has not trusted its envelope sender, the message is filed in
* Junk instead of the INBOX; otherwise delivery proceeds
* normally. Messages that arrived over TLS are never diverted.
* The trust list is consulted per receiving user, so the same
* sender may be quarantined for one user and trusted by
* another. Registered only when the posture is 'spam'.
*
* @param array $info delivery info with 'from', 'to', 'bytes'
* @param array $context per-session context, read for
* 'TLS_ACTIVE'
* @return array|null a folder-redirect verdict routing to Junk,
* or null to deliver normally
*/
public static function junkInsecureMail($info, $context)
{
if (!empty($context['TLS_ACTIVE'])) {
return null;
}
$sender = (string) ($info['from'] ?? '');
$recipient = (string) ($info['to'] ?? '');
$user_id = self::userIdForRecipient($recipient);
if ($user_id <= 0) {
return null;
}
$allow_model = new MailSenderAllowModel();
if ($allow_model->isAllowed($user_id, $sender)) {
return null;
}
return ['folder' => self::JUNK_FOLDER,
'flags' => ['\Recent']];
}
/**
* onMessage hook that evaluates DMARC for an inbound message and
* acts on a failure. It runs SPF against the connecting client
* and the envelope-sender domain, verifies the message's DKIM
* signature, then asks DmarcCheck whether either authenticates a
* domain that aligns with the From-header domain. When the From
* domain publishes a DMARC policy and neither aligns, a
* quarantine policy files the message in Junk and a reject policy
* refuses it; a none policy, and a From domain that publishes no
* policy, deliver normally. Registered only when
* C\p('MAIL_DMARC_ENFORCE') is true.
*
* @param array $info delivery info with 'from' (envelope
* sender), 'to', and 'bytes' (the full message)
* @param array $context per-session context, read for
* 'REMOTE_ADDR' (the connecting client) and 'HELO'
* @return array|string|null 'reject' to refuse the message, a
* folder-redirect verdict routing to Junk, or null to
* deliver normally
*/
public static function dmarcEnforce($info, $context)
{
$bytes = (string) ($info['bytes'] ?? '');
if ($bytes === '') {
return null;
}
list($header_block, ) = DkimKey::splitMessage($bytes);
$headers = DkimKey::parseHeaders($header_block);
$from_domain = DkimKey::fromDomain($headers);
if ($from_domain === '') {
return null;
}
$client_ip = (string) ($context['REMOTE_ADDR'] ?? '');
$helo = (string) ($context['HELO'] ?? '');
$sender = (string) ($info['from'] ?? '');
$sender_domain = self::senderDomain($sender, $helo);
$spf_status = SpfCheck::check($client_ip, $sender_domain,
$helo);
$dkim = DkimKey::verify($bytes);
$dkim_status = $dkim['status'] ?? DkimKey::VERIFY_NONE;
$dkim_domain = $dkim['domain'] ?? '';
$outcome = DmarcCheck::evaluate($from_domain, $dkim_status,
$dkim_domain, $spf_status, $sender_domain);
if ($outcome['result'] !== DmarcCheck::FAIL) {
return null;
}
if ($outcome['policy'] === DmarcCheck::POLICY_REJECT) {
return 'reject';
}
if ($outcome['policy'] === DmarcCheck::POLICY_QUARANTINE) {
return ['folder' => self::JUNK_FOLDER,
'flags' => ['\Recent']];
}
return null;
}
/**
* Picks the domain SPF should authenticate: the domain part of
* the envelope sender, or the HELO name when the reverse path is
* empty (a bounce or DSN), as RFC 7208 directs.
*
* @param string $sender envelope MAIL FROM address
* @param string $helo the HELO/EHLO name the client gave
* @return string the domain to evaluate SPF for
*/
private static function senderDomain($sender, $helo)
{
$sender = trim($sender);
$at = strrpos($sender, '@');
if ($at === false) {
return strtolower(trim($helo));
}
return strtolower(trim(substr($sender, $at + 1)));
}
/**
* Resolves a recipient address to the id of the Yioop user
* whose mailbox receives it, following the same direct-user-
* then-alias order as MailSite::resolveLocalUser. Returns 0
* when the local part is neither a user nor an alias. Used by
* the Spam Insecure hook to pick whose trust list applies.
*
* @param string $recipient full recipient address
* @return int owning user's id, or 0 when unresolved
*/
protected static function userIdForRecipient($recipient)
{
$at = strrpos($recipient, '@');
$local = ($at === false) ? $recipient :
substr($recipient, 0, $at);
$local = strtolower(trim($local));
$domain = ($at === false) ? '' :
strtolower(trim(substr($recipient, $at + 1)));
if ($local === '') {
return 0;
}
$user_model = new UserModel();
$user = $user_model->getUser($local);
if (is_array($user) && isset($user['USER_ID'])) {
return (int) $user['USER_ID'];
}
$alias_model = new MailAliasModel();
return $alias_model->userIdForAlias($local, $domain);
}
/**
* Hook callback for MailSite's onMailFrom and onRcptTo. Reads
* the relevant address out of the hook info array and returns
* 'reject' when its domain part is not a fully-qualified
* domain name. Registered only when C\p('MAIL_TEST_MODE') is
* false (production); test rigs skip this hook so loopback
* addresses work. The null reverse-path ('<>' for DSN/bounce,
* which parseSmtpAddress reports as the empty string) is
* accepted regardless -- RFC 5321 sec 4.5.5 requires servers
* to accept it so non-delivery reports can flow.
*
* @param array $info hook payload; 'from' for MAIL FROM,
* 'to' for RCPT TO
* @return string|null 'reject' to refuse the address; null
* to pass through to the next hook / accept
*/
public static function rejectIfNotFqdn($info)
{
$addr = $info['from'] ?? $info['to'] ?? '';
if ($addr === '') {
return null;
}
return self::isFqdnAddress($addr) ? null : 'reject';
}
/**
* Returns true when the supplied SMTP address has a domain
* part that looks like a fully-qualified domain name --
* contains at least one dot, the last label starts with a
* non-digit character, and the address is not an RFC-5321
* address-literal (square-bracketed IP). Bare IP-literal
* domains such as 127.0.0.1 fail the last-label check.
* Addresses with no '@' fail outright.
*
* @param string $addr SMTP address text (already unwrapped
* from any angle brackets by parseSmtpAddress)
* @return bool whether the domain part is a FQDN by the
* criteria above
*/
public static function isFqdnAddress($addr)
{
$at_pos = strrpos($addr, '@');
if ($at_pos === false) {
return false;
}
$domain = substr($addr, $at_pos + 1);
if ($domain === '' || $domain[0] === '[') {
return false;
}
$dot_pos = strrpos($domain, '.');
if ($dot_pos === false) {
return false;
}
$tld = substr($domain, $dot_pos + 1);
if ($tld === '' || ctype_digit($tld[0])) {
return false;
}
return true;
}
/**
* Parses C\p('MAIL_DOMAINS') into the array shape MailSite expects.
* MAIL_DOMAINS is stored as a comma-separated string by the
* server-settings form, so this splits, trims, and drops
* empties. The empty-list case falls back to ['localhost']
* to match MailSite's own internal default; this matters for
* a fresh install where the admin has not yet visited the
* Mail Services panel.
*
* @return array list of bare domain strings considered local
* to this MailSite instance for SMTP local delivery
*/
public static function localDomains()
{
$raw = trim((string) C\p('MAIL_DOMAINS'));
if ($raw === '') {
return ['localhost'];
}
$domains = array_filter(array_map('trim',
explode(',', $raw)));
if (empty($domains)) {
return ['localhost'];
}
return array_values($domains);
}
/**
* The host name the mail server announces: in the inbound SMTP
* and IMAP greeting banner, and as the EHLO/HELO name on
* outbound delivery. Configurable through MAIL_HOST_NAME; when
* that is empty it falls back to the first configured mail
* domain, then the system host name, then localhost, so the
* name is never empty. For best deliverability this should be
* the sending IP's reverse-DNS (PTR) name and forward-confirm
* back to that IP.
*
* @return string the host name to announce
*/
public static function mailHostName()
{
$configured = trim((string) C\p('MAIL_HOST_NAME'));
if ($configured !== '') {
return $configured;
}
$raw = trim((string) C\p('MAIL_DOMAINS'));
if ($raw !== '') {
$first = trim(strtok($raw, ','));
if ($first !== '') {
return $first;
}
}
$uname = trim((string) php_uname('n'));
return $uname === '' ? 'localhost' : $uname;
}
/**
* Works out the e-mail address that unsubscribe requests should be
* sent to, named in the List-Unsubscribe header on bulk mail. When
* this Yioop runs its own mail for one or more domains, replies go to
* the reserved bot mailbox on the first such domain
* (bot@<first-domain>). When it does not run its own mail there is no
* local mailbox to receive them, so they are addressed to the site's
* root account instead.
*
* @param string $root_email the root account e-mail address, used
* only when this site does not run its own mail
* @return string the address unsubscribe mail should be sent to
*/
public static function unsubscribeMailtoAddress($root_email)
{
$raw = trim((string) C\p('MAIL_DOMAINS'));
if ($raw !== '') {
return self::botAddress();
}
return (string) $root_email;
}
/**
* Absolute path to the shared secret file the site's own mail
* sender and the local mail server use to authenticate the
* reserved bot account. The sender writes a fresh random secret
* here just before it logs in, and the mail server reads it to
* check the bot's password, so the site can relay its own mail
* without an operator-stored bot password. It sits beside the
* TLS key in the security directory, which is not web reachable.
*
* @return string absolute path to the bot secret file
*/
public static function botSecretPath()
{
return C\SECURITY_DIR . "/bot_security.txt";
}
/**
* The local part (mailbox name) of the site's bot identity. The
* bot identity is the configured MAIL_SENDER: when MAIL_SENDER is
* a bare name its local part is itself, and when it is a full
* address the part before the "@" is used. An empty MAIL_SENDER
* falls back to the reserved default name.
*
* @param string|null $sender the sender address to read; defaults
* to the MAIL_SENDER setting
* @return string the bot mailbox name
*/
public static function botLocalPart($sender = null)
{
if ($sender === null) {
$sender = C\p('MAIL_SENDER');
}
$sender = trim((string)$sender);
if ($sender === "") {
return self::UNSUBSCRIBE_MAILBOX;
}
return strtok($sender, "@");
}
/**
* The full e-mail address of the site's bot identity. When the
* configured MAIL_SENDER is already a full address it is used as
* is; when it is a bare name the first local mail domain is
* appended so the bot has a deliverable address.
*
* @param string|null $sender the sender address to read; defaults
* to the MAIL_SENDER setting
* @return string the bot e-mail address
*/
public static function botAddress($sender = null)
{
if ($sender === null) {
$sender = C\p('MAIL_SENDER');
}
$sender = trim((string)$sender);
if (strpos($sender, "@") !== false) {
return $sender;
}
$domains = self::localDomains();
return self::botLocalPart($sender) . "@" . ($domains[0] ?? "");
}
/**
* Reports whether a login name is the site's bot identity. The
* test is on the local part, so both the bare bot name and the
* full bot address count as the bot.
*
* @param string $username the login name to test
* @return bool true when the name is the bot identity
*/
public static function isBotUsername($username)
{
return strtok((string)$username, "@") === self::botLocalPart();
}
/**
* Reports whether a member account may not use a given email address
* because it would collide with the site's own mail. The site's bot
* address is always refused; every other address on a managed mail
* domain is refused only when MAIL_REFUSE_LOCAL_DOMAIN_ACCOUNTS is
* turned on, which it is not by default, so an ordinary person on
* the same domain (for example someone@example.com at an in-house
* example.com install) can still register. This reads the live
* settings and hands them to accountEmailRefused, which holds the
* actual rule.
*
* @param string $email the address a member wants to use
* @return bool true when the address must be refused
*/
public static function isForbiddenAccountEmail($email)
{
return self::accountEmailRefused($email, self::botLocalPart(),
self::localDomains(),
(bool)C\MAIL_REFUSE_LOCAL_DOMAIN_ACCOUNTS);
}
/**
* The rule behind isForbiddenAccountEmail, written as a plain
* decision over its inputs so it can be reasoned about and tested
* without the live configuration. An address is refused when it sits
* on one of the managed mail domains and either its mailbox name is
* the bot's or the caller asked to refuse all addresses on those
* domains. The localhost placeholder used by a site with no mail
* domains configured never counts as managed, so on such a site no
* address is refused. All comparisons ignore letter case.
*
* @param string $email the address a member wants to use
* @param string $bot_local the bot's mailbox name
* @param array $managed_domains bare domains the site handles mail
* for
* @param bool $refuse_local_domain whether to refuse every address
* on a managed domain, not only the bot's
* @return bool true when the address must be refused
*/
public static function accountEmailRefused($email, $bot_local,
$managed_domains, $refuse_local_domain)
{
$at = strrpos((string)$email, "@");
if ($at === false) {
return false;
}
$local = strtolower(trim(substr((string)$email, 0, $at)));
$domain = strtolower(trim(substr((string)$email, $at + 1)));
if ($domain === "" || $domain === "localhost") {
return false;
}
$is_managed = false;
foreach ($managed_domains as $managed) {
if (strtolower(trim((string)$managed)) === $domain) {
$is_managed = true;
break;
}
}
if (!$is_managed) {
return false;
}
if ($local === strtolower(trim((string)$bot_local))) {
return true;
}
return (bool)$refuse_local_domain;
}
/**
* Builds the mail client used to send the site's own outgoing mail
* (registration and bulk mail). When the site sends as the bot
* through its own MailSite, the connection details are derived
* rather than read from the manually entered mail-server fields:
* the client connects to the local MailSite on the submission port
* as the bot identity over STARTTLS, sending from the bot address
* (the configured MAIL_SENDER). No password is supplied here
* because the client mints a one-time secret for the bot at login
* time. The local certificate is accepted without name checking
* because the connection is to the same machine on localhost.
* Otherwise the client is built from the configured external relay
* fields.
*
* @param bool|null $bot_handled whether the bot/MailSite route is
* in use; defaults to the MAIL_BOT_HANDLED setting
* @return SmtpClient a client ready to send outgoing mail
*/
public static function outboundSmtpClient($bot_handled = null)
{
if ($bot_handled === null) {
$bot_handled = C\p('MAIL_BOT_HANDLED');
}
if ($bot_handled) {
return new SmtpClient(self::botAddress(), "localhost",
C\p('MAIL_SUBMISSION_PORT'), self::botLocalPart(), "",
"starttls", true);
}
return new SmtpClient(C\p('MAIL_SENDER'), C\p('MAIL_SERVER'),
C\p('MAIL_SERVERPORT'), C\p('MAIL_USERNAME'), C\p('MAIL_PASSWORD'),
C\p('MAIL_SECURITY'));
}
/**
* Maps a delivery-security posture to the MTA-STS policy mode
* to publish. 'spam' publishes a 'testing' policy (senders
* report TLS failures but still deliver) and 'require'
* publishes 'enforce' (senders refuse cleartext delivery). The
* 'insecure' posture publishes no policy, signalled here by the
* empty string, so the route returns a 404 rather than an
* empty or misleading file.
*
* @param string $delivery_security posture, one of 'insecure',
* 'spam', 'require'
* @return string 'testing', 'enforce', or '' for no policy
*/
public static function mtaStsMode($delivery_security)
{
if ($delivery_security === 'require') {
return 'enforce';
}
if ($delivery_security === 'spam') {
return 'testing';
}
return '';
}
/**
* Builds the body of the MTA-STS policy file (RFC 8461) for one
* policy domain. The mx lines cover both a bare apex MX
* (mx: domain) and any subdomain MX (mx: *.domain) so the
* policy matches whichever host the domain's MX record names
* without hard-coding a specific mail hostname; this pairs with
* a wildcard-or-SAN certificate covering the domain and its
* subdomains. The version and max_age follow the RFC; max_age
* is one week, a conservative rollout value above the one-day
* floor some senders impose. Returns the empty string when the
* mode is empty (no policy), so callers can treat that as
* "nothing to serve".
*
* @param string $mode policy mode, 'testing' or 'enforce'
* (an empty mode yields no policy)
* @param string $domain policy domain whose MX hosts the
* policy authorizes
* @return string the policy file body, or '' when no policy
*/
public static function mtaStsPolicy($mode, $domain)
{
$domain = trim((string) $domain);
if ($mode === '' || $domain === '') {
return '';
}
$lines = [
'version: STSv1',
'mode: ' . $mode,
'mx: *.' . $domain,
'mx: ' . $domain,
'max_age: ' . C\ONE_WEEK,
];
return implode("\r\n", $lines) . "\r\n";
}
/**
* Resolves the policy domain for an MTA-STS request from the
* Host header. In production the policy is served from the
* dedicated host mta-sts.<domain>, so the leading "mta-sts."
* label is stripped and the remainder must be a configured
* local mail domain. As a loopback testing convenience, a
* request whose host is localhost or 127.0.0.1 (optionally
* with a port) resolves to the first configured local domain
* so the operator can fetch the file without standing up the
* mta-sts subdomain. Any other host yields the empty string,
* meaning no policy should be served.
*
* @param string $host the request Host header value
* @param array $domains configured local mail domains
* @return string the policy domain, or '' when the host does
* not correspond to a served policy
*/
public static function mtaStsDomainForHost($host, $domains)
{
$host = strtolower(trim((string) $host));
$colon = strpos($host, ':');
if ($colon !== false) {
$host = substr($host, 0, $colon);
}
if ($host === '') {
return '';
}
if (($host === 'localhost' || $host === '127.0.0.1') &&
!empty($domains)) {
return $domains[0];
}
if (strncmp($host, 'mta-sts.', 8) === 0) {
$candidate = substr($host, 8);
foreach ($domains as $domain) {
if (strcasecmp($candidate, trim($domain)) === 0) {
return $domain;
}
}
}
return '';
}
/**
* Builds the suggested _mta-sts policy-discovery TXT record
* (RFC 8461) for a domain. Sending servers look up this record
* to learn that the domain publishes an MTA-STS policy and to
* detect when it changes; the id is bumped whenever the policy
* changes so senders re-fetch it. A timestamp-derived id is a
* common convention. Returns an empty string when no policy is
* being published (mode empty), since the record should not be
* advertised without a policy to back it.
*
* @param string $mode policy mode, 'testing' or 'enforce'
* (empty mode yields no record)
* @param int $policy_id integer used to derive the record id,
* typically a timestamp
* @return string the suggested TXT record value, or '' when no
* policy is published
*/
public static function mtaStsTxtRecord($mode, $policy_id)
{
if ($mode === '') {
return '';
}
return 'v=STSv1; id=' . (int) $policy_id;
}
/**
* Builds a suggested SPF TXT record for a domain. The record
* authorizes the hosts named by the domain's own MX records to
* send for it (mx mechanism) and asks receivers to soft-fail
* mail from anywhere else (~all), a conservative starting
* point that an operator tightens to -all once confident.
*
* @return string the suggested SPF TXT record value
*/
public static function spfTxtRecord()
{
return 'v=spf1 mx ~all';
}
/**
* Builds a suggested DMARC TXT record (published at
* _dmarc.<domain>). It starts in the report-only "none" policy
* so an operator can watch aggregate reports before tightening
* to quarantine or reject; rua names the address that receives
* those aggregate reports.
*
* @param string $report_address mailbox to receive aggregate
* DMARC reports (the rua target)
* @return string the suggested DMARC TXT record value
*/
public static function dmarcTxtRecord($report_address)
{
$record = 'v=DMARC1; p=none';
$report_address = trim((string) $report_address);
if ($report_address !== '') {
$record .= '; rua=mailto:' . $report_address;
}
return $record;
}
/**
* Assembles the suggested DNS records an operator should
* publish for each configured mail domain, for display in the
* Server Settings DNS helper. Each entry names the record host
* (relative to the domain), its type, and the suggested value.
* The MTA-STS records are included only when the delivery
* posture publishes a policy. The mx host patterns mirror the
* MTA-STS policy: a wildcard and an apex entry so the operator
* can point the domain's MX at the apex or any subdomain
* covered by a wildcard-or-SAN certificate, without this code
* inventing a specific mail hostname.
*
* A listed domain that is the www. or mta-sts. host of another
* listed domain is skipped, since it is not an independent mail
* domain: the apex's own set already carries the mta-sts. host
* and policy records, and a www. host needs no mail records.
*
* @param array $domains configured local mail domains
* @param string $delivery_security posture, used to decide
* whether MTA-STS records are suggested
* @param int $policy_id id for the _mta-sts record
* @param string $report_address rua target for DMARC, may be
* empty
* @param string $dkim_selector DKIM selector label; with a
* record, drives the <selector>._domainkey.<domain> host
* @param string $dkim_record DKIM public-key TXT value; when
* empty no DKIM record is suggested
* @return array map of domain to a list of records, each a map
* with 'host', 'type', and 'value'
*/
public static function suggestedDnsRecords($domains,
$delivery_security, $policy_id, $report_address,
$dkim_selector = '', $dkim_record = '')
{
$mode = self::mtaStsMode($delivery_security);
$listed = [];
foreach ($domains as $listed_domain) {
$listed_domain = trim($listed_domain);
if ($listed_domain !== '') {
$listed[$listed_domain] = true;
}
}
$suggestions = [];
foreach ($domains as $domain) {
$domain = trim($domain);
if ($domain === '') {
continue;
}
/* A www. or mta-sts. host of a domain already in the
list is not an independent mail domain: www is a web
alias and mta-sts is that domain's MTA-STS policy host,
whose records the apex's own set already carries.
Emitting a full mail record set for it would produce
nonsense such as _mta-sts.mta-sts.<apex> or
mta-sts.www.<apex>, so skip it. A bare www./mta-sts.
host whose apex is not listed is left alone, since
nothing else covers it. */
if ((strncmp($domain, 'www.', 4) === 0 &&
!empty($listed[substr($domain, 4)])) ||
(strncmp($domain, 'mta-sts.', 8) === 0 &&
!empty($listed[substr($domain, 8)]))) {
continue;
}
$records = [];
$records[] = ['host' => $domain, 'type' => 'TXT',
'value' => self::spfTxtRecord()];
$records[] = ['host' => '_dmarc.' . $domain,
'type' => 'TXT',
'value' => self::dmarcTxtRecord($report_address)];
$sts_txt = self::mtaStsTxtRecord($mode, $policy_id);
if ($sts_txt !== '') {
$records[] = ['host' => '_mta-sts.' . $domain,
'type' => 'TXT', 'value' => $sts_txt];
$records[] = ['host' => 'mta-sts.' . $domain,
'type' => 'A/CNAME',
'value' => 'this Yioop web server'];
}
if ($dkim_record !== '' && $dkim_selector !== '') {
$records[] = [
'host' => $dkim_selector . '._domainkey.' .
$domain,
'type' => 'TXT', 'value' => $dkim_record];
}
$suggestions[$domain] = $records;
}
return $suggestions;
}
/**
* Connection-logging hook. Writes one mail.log line recording
* the protocol, remote address and port, and whether the
* connection arrived already wrapped in TLS. Wired only when
* MAIL_LOG_ENABLED is on; the write itself also goes through
* SmtpClient::appendLog, which is a no-op when logging is off,
* so this never writes unexpectedly. Returns null so the
* connection is never refused by the act of logging.
*
* @param array $info connect details from MailSite: protocol,
* remote_addr, remote_port, tls_active
* @param array $context per-session context (unused)
* @return null always, so the session proceeds
*/
public static function logConnect($info, $context)
{
$line = date('r') . " MailSite connect " .
($info['protocol'] ?? '?') . " from " .
($info['remote_addr'] ?? '?') . ":" .
($info['remote_port'] ?? '?') .
(empty($info['tls_active']) ? "" : " (implicit TLS)") .
"\n";
SmtpClient::appendLog($line);
return null;
}
/**
* TLS-handshake-logging hook. Writes one mail.log line for each
* handshake attempt, implicit or STARTTLS, recording the mode,
* the remote address and port, and whether the handshake
* succeeded; on failure the handshake error is included. This
* is what makes a client that opens a secure port but never
* completes the handshake visible in the log. Returns null;
* the return value is ignored for this hook regardless.
*
* @param array $info handshake details from MailSite: protocol,
* remote_addr, remote_port, mode, ok, error
* @param array $context per-session context (unused)
* @return null always
*/
public static function logSecure($info, $context)
{
$outcome = empty($info['ok']) ?
("failed: " . ($info['error'] ?? 'unknown')) : "ok";
$line = date('r') . " MailSite TLS " .
($info['mode'] ?? '?') . " " .
($info['protocol'] ?? '?') . " from " .
($info['remote_addr'] ?? '?') . ":" .
($info['remote_port'] ?? '?') . " " . $outcome . "\n";
SmtpClient::appendLog($line);
return null;
}
/**
* Absolute path of the outbound spool directory, where
* messages awaiting background direct-MX delivery are queued.
* Lives beside the mailbox tree under MAIL_DIR.
* @return string absolute outbound spool directory path
*/
public static function outboundSpoolDir()
{
return C\MAIL_DIR . "/outbound";
}
/**
* onOutbound hook: queues one message for background outbound
* delivery. Writes two files into the outbound spool named by a
* unique base: a ".eml" holding the raw RFC 5322 bytes, and an
* ".envelope" holding a JSON record with the envelope sender,
* the remote recipient list, an attempt counter, and the time
* of the next delivery attempt. Writes are done to a temporary
* name and renamed into place so the drainer never reads a
* half-written file. Returns null; the hook's return value is
* ignored.
* @param array $info outbound details from MailSite: 'from',
* 'recipients' (remote addresses), 'bytes' (message)
* @param array $context per-session context (unused)
* @return null always
*/
public static function enqueueOutbound($info, $context)
{
$recipients = $info['recipients'] ?? [];
if (empty($recipients)) {
return null;
}
$spool = static::outboundSpoolDir();
if (!is_dir($spool)) {
@mkdir($spool, 0700, true);
}
$base = $spool . "/" . uniqid("out_", true);
$envelope = [
'from' => (string) ($info['from'] ?? ''),
'recipients' => array_values($recipients),
'attempts' => 0,
'next_attempt' => time(),
];
$message = (string) ($info['bytes'] ?? '');
$eml_tmp = $base . ".eml.tmp";
if (@file_put_contents($eml_tmp, $message) === false) {
SmtpClient::appendLog(date('r') .
" MailSite outbound queue write failed\n");
return null;
}
@rename($eml_tmp, $base . ".eml");
$envelope_tmp = $base . ".envelope.tmp";
@file_put_contents($envelope_tmp,
json_encode($envelope));
@rename($envelope_tmp, $base . ".envelope");
SmtpClient::appendLog(date('r') .
" MailSite outbound queued " . count($recipients) .
" recipient(s) from " . $envelope['from'] . "\n");
return null;
}
/**
* Sweeps the outbound spool and attempts delivery of every
* message whose next-attempt time has arrived. Called on a
* timer by MailServer so delivery happens off the event loop.
* Each message is delivered by direct MX (see
* deliverOutboundFile); on success its spool files are
* removed, on a transient failure its attempt counter is
* incremented and a later retry is scheduled, and once the
* attempt cap (MAIL_SCHEDULED_MAX_ATTEMPTS) is reached the
* message is bounced back to its local sender and removed.
* Returns counts for logging/testing.
* @param int|null $now current time (defaults to time()), for
* tests
* @return array{sent:int, retried:int, bounced:int} outcome
* counts
*/
public static function drainOutbound($now = null)
{
if ($now === null) {
$now = time();
}
$stats = ['sent' => 0, 'retried' => 0, 'bounced' => 0];
$spool = static::outboundSpoolDir();
if (!is_dir($spool)) {
return $stats;
}
$envelopes = glob($spool . "/*.envelope");
if (empty($envelopes)) {
return $stats;
}
$max_attempts = (int) C\MAIL_SCHEDULED_MAX_ATTEMPTS;
foreach ($envelopes as $envelope_path) {
$base = substr($envelope_path,
0, strlen($envelope_path) - strlen(".envelope"));
$eml_path = $base . ".eml";
$envelope = json_decode(
(string) @file_get_contents($envelope_path), true);
if (!is_array($envelope) || !is_file($eml_path)) {
continue;
}
if ((int) ($envelope['next_attempt'] ?? 0) > $now) {
continue;
}
$result = static::deliverOutboundFile($envelope,
$eml_path);
if ($result['ok']) {
@unlink($eml_path);
@unlink($envelope_path);
$stats['sent']++;
continue;
}
$envelope['attempts'] =
(int) ($envelope['attempts'] ?? 0) + 1;
if ($envelope['attempts'] >= $max_attempts) {
static::bounceOutbound($envelope, $eml_path,
$result['error']);
@unlink($eml_path);
@unlink($envelope_path);
$stats['bounced']++;
continue;
}
$envelope['next_attempt'] = $now +
$envelope['attempts'] * (int) C\MAIL_AGGREGATION_TIME;
$envelope_tmp = $envelope_path . ".tmp";
@file_put_contents($envelope_tmp,
json_encode($envelope));
@rename($envelope_tmp, $envelope_path);
SmtpClient::appendLog(date('r') .
" MailSite outbound retry " . $envelope['attempts'] .
" for " . implode(', ', $envelope['recipients']) .
": " . $result['error'] . "\n");
$stats['retried']++;
}
return $stats;
}
/**
* Delivers one queued message to its remote recipients by
* direct MX, grouping recipients by domain and trying each
* domain's MX hosts in priority order. Speaks SMTP as a peer
* MTA (no AUTH), opportunistic STARTTLS, with a port-25 then
* submission-port attempt so a network that blocks outbound 25
* still has a path. A per-domain failure leaves the whole
* message unsent so a single retry covers all recipients.
* @param array $envelope decoded envelope record (from,
* recipients)
* @param string $eml_path path to the raw message bytes
* @return array{ok:bool, error:string} delivery outcome
*/
protected static function deliverOutboundFile($envelope,
$eml_path)
{
$from = (string) ($envelope['from'] ?? '');
$recipients = $envelope['recipients'] ?? [];
$bytes = (string) @file_get_contents($eml_path);
if ($bytes === '' || empty($recipients)) {
return ['ok' => false, 'error' => 'empty message'];
}
$by_domain = [];
foreach ($recipients as $rcpt) {
$at = strrpos($rcpt, '@');
if ($at === false) {
return ['ok' => false,
'error' => "no domain in $rcpt"];
}
$domain = strtolower(substr($rcpt, $at + 1));
$by_domain[$domain][] = $rcpt;
}
$ports = [25];
$submission = (int) C\p('MAIL_SUBMISSION_PORT');
if ($submission > 0 && $submission !== 25) {
$ports[] = $submission;
}
foreach ($by_domain as $domain => $domain_recipients) {
$mx_hosts = SmtpClient::resolveMxHosts($domain);
if (empty($mx_hosts)) {
return ['ok' => false,
'error' => "no MX record for $domain"];
}
$accepted = false;
$last_error = '';
foreach ($mx_hosts as $mx_host) {
foreach ($ports as $port) {
$smtp = new SmtpClient($from, $mx_host, $port,
'', '', 'opportunistic', false);
if ($smtp->deliverBytes($from,
$domain_recipients, $bytes)) {
$accepted = true;
break 2;
}
$last_error = trim($smtp->getLastError());
/* try the submission port only on a TCP-layer
failure; an SMTP-level rejection is
definitive for that MX. */
if (stripos($last_error,
'could not connect') === false) {
break;
}
}
}
if (!$accepted) {
return ['ok' => false, 'error' =>
"$domain: " . ($last_error !== '' ?
$last_error : 'no MX accepted')];
}
}
return ['ok' => true, 'error' => ''];
}
/**
* Generates a delivery-failure notice for a message that could
* not be delivered after the attempt cap and posts it to the
* sender's local mailbox. Outbound relay is permitted only from
* a local sender, so the sender always has a local mailbox to
* receive the bounce; the failure is also written to the log.
* @param array $envelope decoded envelope record (from,
* recipients)
* @param string $eml_path path to the original message bytes
* @param string $error the final delivery error
* @return void
*/
protected static function bounceOutbound($envelope, $eml_path,
$error)
{
$from = (string) ($envelope['from'] ?? '');
$recipients = implode(', ',
(array) ($envelope['recipients'] ?? []));
SmtpClient::appendLog(date('r') .
" MailSite outbound bounced to $from for $recipients: " .
$error . "\n");
$original = (string) @file_get_contents($eml_path);
$boundary = "bounce_" . bin2hex(random_bytes(8));
$eol = "\r\n";
$notice = "From: Mail Delivery System <postmaster" .
"@" . self::primaryLocalDomain() . ">" . $eol .
"To: <$from>" . $eol .
"Subject: Undelivered Mail Returned to Sender" . $eol .
"Content-Type: multipart/mixed; boundary=\"" .
$boundary . "\"" . $eol . $eol .
"--" . $boundary . $eol .
"Content-Type: text/plain; charset=utf-8" . $eol . $eol .
"Delivery to the following recipient(s) failed " .
"permanently:" . $eol . $eol .
" " . $recipients . $eol . $eol .
"Reason: " . $error . $eol . $eol .
"--" . $boundary . $eol .
"Content-Type: message/rfc822" . $eol . $eol .
$original . $eol .
"--" . $boundary . "--" . $eol;
$site = self::build();
$site->deliverMail("<>", $from, $notice,
['source' => 'outbound-bounce']);
}
/**
* The server's primary local mail domain, used as the host
* part of the postmaster address on a bounce notice. Falls
* back to 'localhost' when no domain is configured.
* @return string a local domain name
*/
protected static function primaryLocalDomain()
{
$domains = self::localDomains();
return !empty($domains[0]) ? $domains[0] : 'localhost';
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software