tld_emails.cpp

Go to the documentation of this file.

/* TLD library -- TLD, emails extractions
 * Copyright (c) 2013-2025  Made to Order Software Corp.  All Rights Reserved
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
#include "libtld/tld.h"
 
// C
//
#include <stdio.h>
#include <string.h>
 
// C++
//
#include <memory>
#include <iostream>
#include <algorithm>
 
 
namespace
{
void trim(std::string& value)
{
    if(!value.empty())
    {
        size_t i(value.length());
        for(; i > 0; --i)
        {
            const char c(value[i - 1]);
            if(c != ' ' && c != '\r' && c != '\n' && c != '\t')
            {
                break;
            }
        }
        value.resize(i);
    }
}
 
bool is_quoted_char(char c)
{
    // 0x7F is the Delete key which is viewed as a control
    // here we accept all characters over 127 in case the user
    // has UTF-8 as input data
    return c == '\t' || c >= ' ' && c != 0x7F;
}
 
bool is_atom_char(char c)
{
    return (c >= 'A' && c <= 'Z')
        || (c >= 'a' && c <= 'z')
        || (c >= '0' && c <= '9')
        || c == '!' || c == '#'
        || c == '$' || c == '%'
        || c == '&' || c == '\''
        || c == '*' || c == '+'
        || c == '-' || c == '/'
        || c == '=' || c == '?'
        || c == '^' || c == '_'
        || c == '`' || c == '{'
        || c == '|' || c == '}'
        || c == '~';
}
} // no name namespace
 
 
tld_email_list::tld_email_list()
    : f_flags(0)
    , f_result(TLD_RESULT_SUCCESS)
    , f_pos(0)
{
}
 
tld_result tld_email_list::parse(std::string const & emails, int flags)
{
    f_input = emails;
    f_flags = flags;
    f_result = TLD_RESULT_SUCCESS;
    f_last_group.clear();
    f_pos = 0; // always rewind too
    f_email_list.clear();
 
    parse_all_emails();
    if(f_result != TLD_RESULT_SUCCESS)
    {
        f_email_list.clear();
    }
 
    return f_result;
}
 
void tld_email_list::parse_all_emails()
{
    // old emails supposedly accepted \0 in headers!
    // we actually do not even support control characters as
    // defined in the newest version of the Internet Message
    // (RFC 5322); the following loop, though, does not check
    // all the characters, only those necessary to cut all the
    // email elements properly
 
    char const * start(f_input.c_str());
    bool group(true);
    char const * s(start);
    for(; *s != '\0'; ++s)
    {
        switch(*s)
        {
        case ' ':
        case '\n':
        case '\r':
        case '\t':
            // skip leading spaces immediately
            if(start == s)
            {
                start = s + 1;
            }
            break;
 
        case ';':
            // end of this group
            {
                // trim ending spaces
                char const * end(s);
                for(; end > start; --end)
                {
                    char const c(end[-1]);
                    if(c != ' ' && c != '\n' && c != '\r' && c != '\t')
                    {
                        break;
                    }
                }
                if(end - start > 0)
                {
                    std::string const e(start, end - start);
                    tld_email_t email;
                    email.f_group = f_last_group;
                    f_result = email.parse(e);
                    if(f_result != TLD_RESULT_SUCCESS)
                    {
                        return;
                    }
                    f_email_list.push_back(email);
                }
            }
            f_last_group = "";
            group = true;
            start = s + 1;
            break;
 
        case ':':
            // group label
            if(!group)
            {
                // wrong place for this ':' character
                f_result = TLD_RESULT_INVALID;
                return;
            }
            {
                // trim ending spaces
                char const * end(s);
                for(; end > start; --end)
                {
                    char const c(end[-1]);
                    if(c != ' ' && c != '\n' && c != '\r' && c != '\t')
                    {
                        break;
                    }
                }
                if(end - start <= 0)
                {
                    // An explicitly empty group name is not legal
                    f_result = TLD_RESULT_INVALID;
                    return;
                }
                std::string const last_group(start, end - start);
                // always add the group with an empty email (in case there
                // is no email; and it clearly delimit each group.)
                tld_email_t email;
                f_result = email.parse_group(last_group);
                if(f_result != TLD_RESULT_SUCCESS)
                {
                    // this happens if the group name is invalid
                    // (i.e. include controls or is empty)
                    return;
                }
                f_last_group = email.f_group;
                f_email_list.push_back(email);
            }
            start = s + 1;
            group = false; // cannot get another legal ':' until we find the ';'
            break;
 
        case ',':
            // email separation
            {
                // trim ending spaces
                char const * end(s);
                for(; end > start; --end)
                {
                    char const c(end[-1]);
                    if(c != ' ' && c != '\n' && c != '\r' && c != '\t')
                    {
                        break;
                    }
                }
                if(end - start > 0)
                {
                    std::string const e(start, end - start);
                    tld_email_t email;
                    email.f_group = f_last_group;
                    f_result = email.parse(e);
                    if(f_result != TLD_RESULT_SUCCESS)
                    {
                        return;
                    }
                    f_email_list.push_back(email);
                }
            }
            start = s + 1;
            break;
 
        case '"':
            // quoted strings may include escaped characters so it is a
            // special case, also it could include a comma
            for(++s; *s != '\0' && *s != '"'; ++s)
            {
                if(*s == '\\')
                {
                    if(!is_quoted_char(s[1]))
                    {
                        // "\NUL" is never considered valid
                        f_result = TLD_RESULT_INVALID;
                        return;
                    }
                    ++s;
                }
            }
            if(*s == '\0')
            {
                // unterminated quoted string
                f_result = TLD_RESULT_INVALID;
                return;
            }
            break;
 
        case '(':
            {
                // comments may include other comments
                int comment_count(1);
                for(++s; *s != '\0'; ++s)
                {
                    if(*s == '\\')
                    {
                        if(!is_quoted_char(s[1]))
                        {
                            // "\NUL" is never considered valid
                            f_result = TLD_RESULT_INVALID;
                            return;
                        }
                        ++s;
                    }
                    else if(*s == '(')
                    {
                        ++comment_count;
                    }
                    else if(*s == ')')
                    {
                        --comment_count;
                        if(comment_count <= 0)
                        {
                            break;
                        }
                    }
                }
                if(*s == '\0')
                {
                    // unterminated comment
                    f_result = TLD_RESULT_INVALID;
                    return;
                }
            }
            break;
 
        case '[':
            for(++s; *s != ']'; ++s)
            {
                if(*s == '\0' || *s == '[' || *s == '\\')
                {
                    // domain literal cannot include '[', ']', or '\'
                    // and it must end with ']'
                    //
                    f_result = TLD_RESULT_INVALID;
                    return;
                }
            }
            break;
 
        }
    }
 
    if(!group)
    {
        // the ';' to end a group is missing
        f_result = TLD_RESULT_INVALID;
        return;
    }
 
    {
        // trim ending spaces
        char const * end(s);
        for(; end > start; --end)
        {
            char const c(end[-1]);
            if(c != ' ' && c != '\n' && c != '\r' && c != '\t')
            {
                break;
            }
        }
        if(end - start > 0)
        {
            std::string const e(start, end - start);
            tld_email_t email;
            email.f_group = f_last_group;
            f_result = email.parse(e);
            if(f_result != TLD_RESULT_SUCCESS)
            {
                return;
            }
            f_email_list.push_back(email);
        }
    }
}
 
std::string tld_email_list::quote_string(const std::string& str, char quote)
{
    bool apply_quotes(false);
    char open(quote);
    char close('"');
    char const * extra("");
    char const * escape("");
    switch(quote)
    {
    case '(':
        close = ')';
        apply_quotes = true;
        escape = "()";
        break;
 
    case '"':
        extra = " \t";
        escape = "\"";
        break;
 
    case '\'':
        open = '"';
        close = '"';
        extra = ".";
        escape = "\"";
        break;
 
    case '[':
        close = ']';
        extra = ".";
        break;
 
    }
    if(!apply_quotes)
    {
        // check whether quotes are required
        char const * s(str.c_str());
        for(; *s != '\0'; ++s)
        {
            if(!is_atom_char(*s) && strchr(extra, *s) == nullptr)
            {
                break;
            }
        }
        apply_quotes = *s != '\0';
    }
    if(apply_quotes)
    {
        std::string result;
        result += open;
        for(const char *s(str.c_str()); *s != '\0'; ++s)
        {
            if(strchr(escape, *s) != nullptr)
            {
                result += '\\';
            }
            result += *s;
        }
        result += close;
        return result;
    }
    return str;
}
 
int tld_email_list::count() const
{
    return static_cast<int>(f_email_list.size());
}
 
void tld_email_list::rewind() const
{
    f_pos = 0;
}
 
bool tld_email_list::next(tld_email_t& e) const
{
    if(f_pos >= static_cast<int>(f_email_list.size()))
    {
        return false;
    }
 
    e = f_email_list[f_pos];
    ++f_pos;
 
    return true;
}
 
bool tld_email_list::next(tld_email *e) const
{
    if(f_pos >= static_cast<int>(f_email_list.size()))
    {
        return false;
    }
 
    e->f_group               = f_email_list[f_pos].f_group.c_str();
    e->f_original_email      = f_email_list[f_pos].f_original_email.c_str();
    e->f_fullname            = f_email_list[f_pos].f_fullname.c_str();
    e->f_username            = f_email_list[f_pos].f_username.c_str();
    e->f_domain              = f_email_list[f_pos].f_domain.c_str();
    e->f_email_only          = f_email_list[f_pos].f_email_only.c_str();
    e->f_canonicalized_email = f_email_list[f_pos].f_canonicalized_email.c_str();
    ++f_pos;
 
    return true;
}
 
tld_email_field_type tld_email_list::email_field_type(const std::string& name)
{
    std::string uname;
    for(const char *u(name.c_str()); *u != '\0' && *u != ':'; ++u)
    {
        if(*u >= 'a' && *u <= 'z')
        {
            uname += *u & 0x5F;
        }
        else if((*u >= 'A' && *u <= 'Z')
             || (*u >= '0' && *u <= '9')
             || *u == '-')
        {
            uname += *u;
        }
        else
        {
            return TLD_EMAIL_FIELD_TYPE_INVALID;
        }
    }
    // the field must start with a letter and it cannot be empty
    if(uname.empty() || uname[0] < 'A' || uname[0] > 'Z')
    {
        return TLD_EMAIL_FIELD_TYPE_INVALID;
    }
 
    if(uname == "FROM"
    || uname == "RESENT-FROM")
    {
        return TLD_EMAIL_FIELD_TYPE_MAILBOX_LIST;
    }
    if(uname == "SENDER"
    || uname == "RESENT-SENDER")
    {
        return TLD_EMAIL_FIELD_TYPE_MAILBOX;
    }
    if(uname == "TO"
    || uname == "CC"
    || uname == "REPLY-TO"
    || uname == "RESENT-TO"
    || uname == "RESENT-CC")
    {
        return TLD_EMAIL_FIELD_TYPE_ADDRESS_LIST;
    }
    if(uname == "BCC"
    || uname == "RESENT-BCC")
    {
        return TLD_EMAIL_FIELD_TYPE_ADDRESS_LIST_OPT;
    }
 
    return TLD_EMAIL_FIELD_TYPE_UNKNOWN;
}
 
tld_result tld_email_list::tld_email_t::parse(std::string const & email)
{
    // The following is parsing ONE email since we already removed the
    // groups, commas, semi-colons, leading and ending spaces.
    //
    std::string value;
    value.reserve(email.length());
    std::string fullname;
    std::string username;
    std::string domain;
    uint32_t count = 0;
    bool has_angle(false);
    bool found_at(false);
    bool found_dot(false);
    bool done(false);
    char const * start(email.c_str());
    char const * s(start);
    for(; *s != '\0'; ++s)
    {
        switch(*s)
        {
        case '"':
            if(done)
            {
                return TLD_RESULT_INVALID;
            }
            for(++s; *s != '"'; ++s)
            {
                if(*s == '\0')
                {
                    throw std::logic_error("somehow we found a \\0 in a quoted string in tld_email_t which should not happen since it was already checked validity in tld_email_t::parse()");
                }
                if(*s == '\\')
                {
                    // the backslash is not part of the result
                    ++s;
                    if(*s == '\0')
                    {
                        // this cannot actually happen because we are
                        // expected to capture those at the previous
                        // level
                        throw std::logic_error("somehow we found a \\0 in a quoted string after a backslash in tld_email_t which should not happen since it was already checked validity in tld_email_t::parse()"); // LCOV_EXCL_LINE
                    }
                }
                if((static_cast<unsigned char>(*s) < ' ' && *s != '\t') || *s == 0x7F)
                {
                    // do not accept any control characters
                    // (note that this is sufficient to check all characters
                    // after the \ character)
                    //
                    return TLD_RESULT_INVALID;
                }
                value += *s;
            }
            // on entry of this loop, *s == '"'
            do
            {
                ++s;
            }
            while(*s == ' ');
            if( *s != '<' && *s != '@' )
            {
                // A space afterwards is allowed, but '<' is expected
                //
                return TLD_RESULT_INVALID;
            }
            --s;
            break;
 
        case '(':
            // comments are completely ignored
            count = 1;
            for(++s; count > 0; ++s)
            {
                char c(*s);
                switch(c)
                {
                case '\0':
                    throw std::logic_error("somehow we found a \\0 in a comment in tld_email_t which should not happen since it was already checked in tld_email_t::parse()");
 
                case '(':
                    ++count;
                    break;
 
                case ')':
                    --count;
                    break;
 
                case '\n':
                case '\r':
                case '\t':
                    c = ' ';
                    break;
 
                case '\\':
                    ++s;
                    if(!is_quoted_char(*s))
                    {
                        throw std::logic_error("somehow we found a non-quotable character after a backslash (\\) in tld_email_t which should not happen since it was already checked in tld_email_t::parse()");
                    }
                    c = *s;
                    break;
 
                }
                if(static_cast<unsigned char>(c) < ' ')
                {
                    // do not accept any control characters in comments
                    // (except \r, \n, and \t)
                    return TLD_RESULT_INVALID;
                }
            }
            --s;
            break;
 
        case '[':
            if(!found_at || done || !value.empty() || !domain.empty())
            {
                // domain before the '@'
                //
                return TLD_RESULT_INVALID;
            }
            // trim spaces after the '['
            //
            for(++s; *s != ']'; ++s)
            {
                char const c(*s);
                if(c != ' ' && c != '\n' && c != '\r' && c != '\t')
                {
                    break;
                }
            }
            for(; *s != '[' && *s != '\\' && *s != ']' && *s != ' ' && *s != '\n' && *s != '\r' && *s != '\t'; ++s)
            {
                if(*s == '\0')
                {
                    throw std::logic_error("somehow we found a \\0 in a literal domain in tld_email_t which should not happen since it was already checked in tld_email_t::parse()");
                }
                // spaces are forbidden in domain names (see test above)
                //
                if(static_cast<unsigned char>(*s) < ' ' || *s == 0x7F)
                {
                    // do not accept any control characters
                    //
                    return TLD_RESULT_INVALID;
                }
                value += *s;
            }
            // we can have spaces at the end, but those must be followed by ']'
            //
            for(; *s != '[' && *s != '\\' && *s != ']'; ++s)
            {
                char const c(*s);
                if(c != ' ' && c != '\n' && c != '\r' && c != '\t')
                {
                    break;
                }
            }
            if(*s != ']' || value.empty())
            {
                // domain literal cannot include a space
                // nor can it be empty
                //
                return TLD_RESULT_NULL;
            }
            if(value[0] == '.'
            || *value.rbegin() == '.'
            || value.find("..") != std::string::npos)
            {
                // a domain cannot start or end with "."
                // a domain cannot include ".."
                //
                return TLD_RESULT_INVALID;
            }
            domain = value;
            value.clear();
            break;
 
        case '<':
            if(has_angle || found_at || found_dot || done)
            {
                // found two '<' or the '<' after the '@'
                // or we had a dot before meaning that we already have a dotted username
                // or we are done (a.k.a. found the '>')
                //
                return TLD_RESULT_INVALID;
            }
 
            // if we have an angle email address, whatever we found so far
            // is the user name; although it can be empty
            //
            trim(value);
            if(!value.empty())
            {
                fullname = value;
                value.clear();
            }
            has_angle = true;
            break;
 
        case '>':
            if(!has_angle || !found_at || done)
            {
                // missing '<' and/or '@'
                //
                return TLD_RESULT_INVALID;
            }
            if(domain.empty())
            {
                trim(value);
                if(value.empty())
                {
                    // an empty domain name is not valid, apparently
                    //
                    return TLD_RESULT_NULL;
                }
                // we are done, we can only find spaces and comments
                //
                domain = value;
            }
            else
            {
                if(!value.empty())
                {
                    return TLD_RESULT_INVALID;
                }
            }
            done = true;
            has_angle = false;
            value.clear();
            break;
 
        case '@':
            // Note: if done is true, found_at is also true here
            if(found_at || done)
            {
                // found two '@' characters
                return TLD_RESULT_INVALID;
            }
            found_at = true;
            found_dot = false; // reset this flag
            trim(value);
            if(value.empty())
            {
                // no username is not a valid entry
                //
                return TLD_RESULT_NULL;
            }
            username = value;
            value.clear();
            break;
 
        case ' ':
        case '\n':
        case '\r':
        case '\t':
            //
            // keep just one space
            //
            if( !value.empty() )
            {
                value += ' ';
            }
            // and skip all the others
            // (as far as I know this is not allowed in the RFC, only one space
            // between items; however, after a new-line / carriage return, you
            // could get many spaces and tabs and that's legal)
            //
            for(++s; *s != '\0'; ++s)
            {
                char const c(*s);
                if(c != ' ' && c != '\n' && c != '\r' && c != '\t')
                {
                    break;
                }
            }
            --s; // the main loop will skip that last character (again)
            break;
 
        case '.':
            if(value.empty()                                // cannot start with a dot
            || (!value.empty() && *value.rbegin() == '.')   // cannot include two dots one after the other
            || s[1] == '@' || s[1] == '>')                  // cannot end with a dot
            {
                return TLD_RESULT_INVALID;
            }
            found_dot = true;
            value += '.';
            break;
 
        default:
            // here we must have a valid atom character ([-A-Za-z0-9!#$%&'*+/=?^_`{|}~])
            //
            if(!is_atom_char(*s))
            {
                // not a valid atom character
                //
                return TLD_RESULT_INVALID;
            }
            value += *s;
            break;
 
        }
    }
 
    if(username.empty() || has_angle)
    {
        // no username means the '@' is missing
        // angle bracket was not closed ('>' missing)
        //
        return TLD_RESULT_NULL;
    }
 
    if(done)
    {
        if(!value.empty())
        {
            // nothing of substance can appear after the domain
            //
            return TLD_RESULT_INVALID;
        }
    }
    else
    {
        trim(value);
        if(value.empty())
        {
            if(domain.empty())
            {
                // domain is missing
                //
                return TLD_RESULT_NULL;
            }
        }
        else
        {
            if(!domain.empty())
            {
                // domain "defined twice"
                //
                return TLD_RESULT_INVALID;
            }
            domain = value;
        }
    }
 
    // finally, verify that the domain is indeed valid
    // (i.e. proper characters, structure, and TLD)
    // for that step we use the lowercase version
    //
    struct tld_info info;
    std::unique_ptr<char, void(*)(char *)> lowercase_domain(tld_domain_to_lowercase(domain.c_str()), reinterpret_cast<void(*)(char *)>(&::free));
    tld_result result(tld(lowercase_domain.get(), &info));
    if(result != TLD_RESULT_SUCCESS)
    {
        return result;
    }
 
    // EX-193 and EX-185: email must not have whitespace in it!
    //
    auto has_whitespace = [&]( char c )
        {
            return (c == ' ' || c == '\n' || c == '\r' || c == '\t');
        };
    if( std::find_if( std::begin(username), std::end(username), has_whitespace ) != std::end(username) )
    {
        return TLD_RESULT_INVALID;
    }
    //
    if( std::find_if( std::begin(domain), std::end(domain), has_whitespace ) != std::end(domain) )
    {
        return TLD_RESULT_INVALID;
    }
 
    f_original_email = email;
    f_fullname       = fullname;
    f_username       = username;
    f_domain         = domain;
    f_email_only     = quote_string(username, '\'') + "@" + quote_string(domain, '[');  // TODO protect characters...
 
    // the canonicalized version uses the domain name in lowercase
    //
    std::string canonicalized_email(quote_string(username, '\'') + "@" + quote_string(lowercase_domain.get(), '['));  // TODO protect characters...
    if(fullname.empty())
    {
        f_canonicalized_email = canonicalized_email;
    }
    else
    {
        f_canonicalized_email = quote_string(fullname, '"') + " <" + canonicalized_email + ">";  // TODO protect characters...
    }
 
    return TLD_RESULT_SUCCESS;
}
 
tld_result tld_email_list::tld_email_t::parse_group(std::string const & group)
{
    char const * s(group.c_str());
    std::string g;
    uint32_t count = 0;
 
    for(; *s != '\0'; ++s)
    {
        switch(*s)
        {
        case ' ':
        case '\n':
        case '\r':
        case '\t':
            if(!g.empty())
            {
                g += ' ';
            }
            for(++s; *s == ' ' || *s == '\n' || *s == '\r' || *s == '\t'; ++s);
            --s;
            break;
 
        case '(':
            count = 1;
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wstrict-overflow"
            for(++s; count > 0; ++s)
#pragma GCC diagnostic pop
            {
                if(*s == '\0')
                {
                    throw std::logic_error("somehow we found a \\0 in a quoted string in tld_email_t which should not happen since it was already checked in tld_email_t::parse()");
                }
                switch(*s)
                {
                case '(':
                    ++count;
                    break;
 
                case ')':
                    --count;
                    break;
 
                case '\\':
                    if(!is_quoted_char(s[1]))
                    {
                        throw std::logic_error("somehow we found a non-quotable character in tld_email_t which should not happen since it was already checked in tld_email_t::parse()");
                    }
                    ++s;
                    break;
 
                // controls, etc. were already checked
                }
            }
            // come back on the ')' since the main for will do a ++s
            --s;
            break;
 
        default:
            if(static_cast<unsigned char>(*s) < ' ' || *s == 0x7F)
            {
                return TLD_RESULT_INVALID;
            }
            g += *s;
            break;
 
        }
    }
    if(g.empty())
    {
        return TLD_RESULT_INVALID;
    }
 
    f_group = g;
 
    return TLD_RESULT_SUCCESS;
}
 
struct tld_email_list * tld_email_alloc()
{
    return new tld_email_list;
}
 
void tld_email_free(struct tld_email_list * list)
{
    delete list;
}
 
tld_result tld_email_parse(struct tld_email_list * list, char const * emails, int flags)
{
    return list->parse(emails, flags);
}
 
int tld_email_count(struct tld_email_list * list)
{
    return list->count();
}
 
void tld_email_rewind(struct tld_email_list * list)
{
    list->rewind();
}
 
int tld_email_next(struct tld_email_list * list, struct tld_email * e)
{
    return list->next(e) ? 1 : 0;
}
 
/* vim: ts=4 sw=4 et
 */