<?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\yioop\configs as C;

/**
 * Light-weight RFC 5322 header parser used by Yioop's webmail to
 * extract Subject / From / Date / Delivered-To / Message-ID and
 * similar from a raw header byte block (typically returned by
 * MailSite::messageHeaderBytes). Designed to handle the common-
 * case real-world mail correctly without pulling in a full MIME
 * parser dependency.
 *
 * What's supported:
 *   - Header unfolding (continuation lines starting with WSP)
 *   - Case-insensitive header names (normalized to lower-case
 *     keys on output)
 *   - Both CRLF and bare-LF line terminators
 *   - RFC 2047 encoded-word decoding for Q and B encodings,
 *     UTF-8, ISO-8859-1, and us-ascii
 *   - Adjacent encoded-words concatenation (RFC 2047 Section 6.2)
 *   - Address-list split into [name, email] pairs
 *
 * What's NOT supported:
 *   - Group-list address syntax (group-name: a@b, c@d;)
 *   - Comments inside the header value (RFC 5322 allows them but
 *     they almost never appear in From/To/Cc)
 *   - Encoded-word charsets beyond UTF-8 / ISO-8859-1 / us-ascii
 *     (anything else returns the raw bytes for graceful
 *     degradation)
 *
 * Intentionally not exposed: the parse-all variant that
 * preserves every Received line. The handful of headers Yioop
 * cares about today are not the kind that repeat with semantic
 * significance, so the simpler name=>value shape is enough.
 *
 * @author Chris Pollett
 */
class MailHeaderParser
{
    /**
     * Parses the raw RFC 5322 header bytes of a message into a
     * lower-case-keyed associative array. Folded continuation
     * lines are unfolded into a single value joined by a space.
     * Duplicate headers: later occurrence wins (good enough for
     * Subject / From / Date / Delivered-To since these typically
     * appear at most once).
     *
     * @param string $bytes the raw header block bytes; everything
     *      before the first blank line. Both CRLF and bare-LF
     *      line terminators are accepted
     * @return array map of lower-case header name to value
     */
    public static function parse($bytes)
    {
        $bytes = str_replace("\r\n", "\n", (string) $bytes);
        $lines = explode("\n", $bytes);
        $headers = [];
        $current_name = null;
        $current_value = '';
        foreach ($lines as $line) {
            if ($line === '') {
                continue;
            }
            $first = $line[0];
            if ($first === ' ' || $first === "\t") {
                if ($current_name !== null) {
                    $current_value .= ' ' . trim($line);
                }
                continue;
            }
            if ($current_name !== null) {
                $headers[$current_name] = $current_value;
            }
            $colon = strpos($line, ':');
            if ($colon === false) {
                $current_name = null;
                $current_value = '';
                continue;
            }
            $current_name = strtolower(substr($line, 0, $colon));
            $current_value = ltrim(substr($line, $colon + 1));
        }
        if ($current_name !== null) {
            $headers[$current_name] = $current_value;
        }
        return $headers;
    }
    /**
     * Decodes an RFC 2047 encoded-word string in place: replaces
     * each =?charset?encoding?data?= run with its decoded form.
     * Encoded-word runs are case-insensitively matched. Adjacent
     * encoded-words are concatenated without the separating
     * whitespace as required by RFC 2047 Section 6.2.
     *
     * @param string $text header value possibly containing
     *      encoded-words
     * @return string decoded UTF-8 string
     */
    public static function decodeMimeWord($text)
    {
        $text = (string) $text;
        if (strpos($text, '=?') === false) {
            return $text;
        }
        $pattern = '/=\?([^?]+)\?([QqBb])\?([^?]*)\?=' .
            '(\s+(?==\?))?/';
        return preg_replace_callback($pattern,
            function ($match) {
                $charset = strtolower($match[1]);
                $encoding = strtolower($match[2]);
                $payload = $match[3];
                if ($encoding === 'q') {
                    $payload = str_replace('_', ' ', $payload);
                    $decoded = quoted_printable_decode($payload);
                } else {
                    $decoded = base64_decode($payload, true);
                    if ($decoded === false) {
                        return $match[0];
                    }
                }
                if ($charset === 'utf-8' || $charset === 'us-ascii') {
                    return $decoded;
                }
                if ($charset === 'iso-8859-1') {
                    return mb_convert_encoding($decoded, 'UTF-8',
                        'ISO-8859-1');
                }
                return $decoded;
            },
            $text);
    }
    /**
     * Splits a From/To/Cc address-list header value into its
     * component addresses. Each entry comes back as a two-element
     * array [name, email]. Display names are unquoted and
     * decoded from RFC 2047 encoded-words if present. The email
     * portion is whatever is between the angle brackets, or the
     * whole token when no brackets are present.
     *
     * @param string $value the header value bytes
     * @return array list of [name, email] pairs
     */
    public static function splitAddresses($value)
    {
        $value = (string) $value;
        if ($value === '') {
            return [];
        }
        $items = [];
        $buffer = '';
        $depth = 0;
        $in_quote = false;
        $length = strlen($value);
        for ($pos = 0; $pos < $length; $pos++) {
            $character = $value[$pos];
            if ($character === '"' &&
                    ($pos === 0 || $value[$pos - 1] !== '\\')) {
                $in_quote = !$in_quote;
                $buffer .= $character;
                continue;
            }
            if (!$in_quote) {
                if ($character === '<') {
                    $depth++;
                } else if ($character === '>' && $depth > 0) {
                    $depth--;
                } else if ($character === ',' && $depth === 0) {
                    $entry = self::splitOneAddress(trim($buffer));
                    if ($entry !== null) {
                        $items[] = $entry;
                    }
                    $buffer = '';
                    continue;
                }
            }
            $buffer .= $character;
        }
        $entry = self::splitOneAddress(trim($buffer));
        if ($entry !== null) {
            $items[] = $entry;
        }
        return $items;
    }
    /**
     * Helper for splitAddresses: decomposes one address token
     * into [name, email]. Recognizes the common forms
     * "Name <a@b>", "<a@b>", and bare "a@b". Quotation marks
     * around the name are stripped; RFC 2047 encoded-words in
     * the name are decoded.
     *
     * @param string $token one trimmed address-list entry
     * @return array|null [name, email] pair, or null if the
     *      token is empty
     */
    protected static function splitOneAddress($token)
    {
        if ($token === '') {
            return null;
        }
        $name = '';
        $email = '';
        $left = strpos($token, '<');
        $right = strrpos($token, '>');
        if ($left !== false && $right !== false && $right > $left) {
            $email = trim(substr($token, $left + 1,
                $right - $left - 1));
            $name = trim(substr($token, 0, $left));
        } else {
            $email = trim($token);
        }
        if ($name !== '' && $name[0] === '"' &&
                substr($name, -1) === '"') {
            $name = substr($name, 1, -1);
        }
        $name = self::decodeMimeWord($name);
        return [$name, $email];
    }
    /**
     * Splits a comma-separated address header into its individual
     * address specs, keeping each one whole. A comma inside a quoted
     * display name or inside the angle brackets around an address is
     * not a separator, so "Doe, Jane <j@x>" stays one entry. Returns
     * the trimmed specs as written, with empty pieces dropped.
     *
     * @param string $list the raw address header value
     * @return array the individual address specs
     */
    public static function parseAddressList($list)
    {
        $out = [];
        if ($list === '') {
            return $out;
        }
        $parts = [];
        $buffer = '';
        $in_quote = false;
        $in_angle = false;
        $length = strlen($list);
        for ($index = 0; $index < $length; $index++) {
            $character = $list[$index];
            if ($character === '"' && !$in_angle) {
                $in_quote = !$in_quote;
                $buffer .= $character;
                continue;
            }
            if ($character === '<' && !$in_quote) {
                $in_angle = true;
                $buffer .= $character;
                continue;
            }
            if ($character === '>' && !$in_quote) {
                $in_angle = false;
                $buffer .= $character;
                continue;
            }
            if ($character === ',' && !$in_quote && !$in_angle) {
                $parts[] = $buffer;
                $buffer = '';
                continue;
            }
            $buffer .= $character;
        }
        if ($buffer !== '') {
            $parts[] = $buffer;
        }
        foreach ($parts as $part) {
            $trimmed = trim($part);
            if ($trimmed !== '') {
                $out[] = $trimmed;
            }
        }
        return $out;
    }
    /**
     * Pulls the plain email address out of one address spec, dropping
     * any display name. "Jane <j@x>" becomes "j@x"; a spec that is
     * already bare comes back unchanged. The result is trimmed and
     * lower-cased so two writings of the same address compare equal.
     *
     * @param string $spec one address spec
     * @return string the bare lower-cased email address
     */
    public static function extractBareAddress($spec)
    {
        $open = strrpos($spec, '<');
        $close = strrpos($spec, '>');
        if ($open !== false && $close !== false &&
                $close > $open) {
            $bare = substr($spec, $open + 1,
                $close - $open - 1);
        } else {
            $bare = $spec;
        }
        return strtolower(trim($bare));
    }
    /**
     * completeLocalAddress fills in the domain on an address written as
     * a bare name. Somebody writing to a person on the same site types
     * the name alone, as jannew rather than jannew@example.com, and the
     * address that reaches the send would otherwise be turned away for
     * naming no domain. The given domain is put on such a name; an
     * address that already names a domain, and anything holding a space
     * or an at sign, is handed back unchanged. Any display name around
     * the address is kept, so "Jane <jannew>" completes the part inside
     * the angle brackets and keeps Jane.
     *
     * @param string $spec one address spec, possibly with a display name
     * @param string $domain the mail domain to fill in, without an at
     *     sign; where it is empty the spec comes back unchanged
     * @return string the spec with a domain on its address
     */
    public static function completeLocalAddress($spec, $domain)
    {
        $domain = trim((string) $domain);
        if ($domain === '') {
            return $spec;
        }
        $open = strrpos($spec, '<');
        $close = strrpos($spec, '>');
        $has_brackets = ($open !== false && $close !== false &&
            $close > $open);
        $bare = $has_brackets ?
            substr($spec, $open + 1, $close - $open - 1) : $spec;
        $bare = trim($bare);
        if ($bare === '' || strpos($bare, '@') !== false ||
            preg_match('/\s/', $bare)) {
            return $spec;
        }
        $completed = $bare . '@' . $domain;
        if (!$has_brackets) {
            return $completed;
        }
        return substr($spec, 0, $open + 1) . $completed .
            substr($spec, $close);
    }
    /**
     * Says whether a bare email address looks deliverable. Normally
     * this is PHP's email validator; in test mode it relaxes to a
     * simple "something@something" check so test addresses with
     * made-up domains still pass.
     *
     * @param string $bare a bare email address
     * @return bool true when the address looks valid
     */
    public static function isValidAddress($bare)
    {
        if (C\p('MAIL_TEST_MODE')) {
            $at_pos = strrpos($bare, '@');
            if ($at_pos === false || $at_pos === 0 ||
                    $at_pos === strlen($bare) - 1) {
                return false;
            }
            return true;
        }
        return (bool) filter_var($bare, FILTER_VALIDATE_EMAIL);
    }
    /**
     * Makes a user-supplied value safe to place in a single mail
     * header: control characters (which could otherwise smuggle in
     * extra header lines) are stripped, surrounding spaces removed,
     * and the value capped at a maximum length.
     *
     * @param string $value the raw value
     * @param int $max_len the most characters to keep
     * @return string the cleaned, length-capped value
     */
    public static function cleanHeader($value, $max_len)
    {
        $value = preg_replace('/[\x00-\x1F\x7F]/', '',
            (string) $value);
        $value = trim($value);
        if (strlen($value) > $max_len) {
            $value = substr($value, 0, $max_len);
        }
        return $value;
    }
    /**
     * Removes specific recipients from an address header: the one
     * address in $exclude_email, and everyone already present in
     * $exclude_listed. Used when building a reply so the sender and
     * the existing recipients are not added again. Returns a
     * comma-joined header of what remains.
     *
     * @param string $list the address header to filter
     * @param string $exclude_email a bare address to drop
     * @param string $exclude_listed an address header whose members
     *      are also dropped
     * @return string the filtered, comma-joined address header
     */
    public static function filterAddressList($list, $exclude_email,
        $exclude_listed)
    {
        $listed_bare = [];
        foreach (self::parseAddressList($exclude_listed) as $addr) {
            $bare = self::extractBareAddress($addr);
            if ($bare !== '') {
                $listed_bare[$bare] = true;
            }
        }
        $out = [];
        foreach (self::parseAddressList($list) as $addr) {
            $bare = self::extractBareAddress($addr);
            if ($bare === $exclude_email) {
                continue;
            }
            if (isset($listed_bare[$bare])) {
                continue;
            }
            $out[] = $addr;
        }
        return implode(', ', $out);
    }
    /**
     * Merges two address headers into one, dropping duplicates and a
     * given address. Used when forwarding or replying to combine
     * recipient lists without repeating anyone or re-including the
     * sender. Returns a comma-joined header.
     *
     * @param string $list_a the first address header
     * @param string $list_b the second address header
     * @param string $exclude_email a bare address to drop
     * @return string the merged, comma-joined address header
     */
    public static function joinAddressLists($list_a, $list_b,
        $exclude_email)
    {
        $seen = [];
        $out = [];
        foreach ([$list_a, $list_b] as $list) {
            foreach (self::parseAddressList($list) as $addr) {
                $bare = self::extractBareAddress($addr);
                if ($bare === $exclude_email) {
                    continue;
                }
                if (isset($seen[$bare])) {
                    continue;
                }
                $seen[$bare] = true;
                $out[] = $addr;
            }
        }
        return implode(', ', $out);
    }
    /**
     * Reads the envelope sender (the Return-Path address) out of a
     * raw message's headers, or returns an empty string when there
     * is none. Only the header block is scanned, and the address is
     * unwrapped from its angle brackets and trimmed.
     *
     * @param string $bytes the raw message bytes
     * @return string the bare Return-Path address, or empty string
     */
    public static function envelopeSender($bytes)
    {
        $bytes = (string) $bytes;
        $break = strpos($bytes, "\r\n\r\n");
        if ($break === false) {
            $break = strpos($bytes, "\n\n");
        }
        $header_block = ($break === false) ? $bytes :
            substr($bytes, 0, $break);
        if (!preg_match('/^Return-Path:\s*(.*)$/mi', $header_block,
            $match)) {
            return '';
        }
        $value = trim($match[1]);
        $value = trim($value, "<>");
        $value = trim($value);
        return $value;
    }
}
