Skip to content

mta-sts.md

Latest commit

 

History

History
232 lines (184 loc) · 6.97 KB

mta-sts.md

File metadata and controls

232 lines (184 loc) · 6.97 KB

MTA-STS Result Reference

This document describes the result objects returned by MTA-STS (Mail Transfer Agent Strict Transport Security) functions.

Overview

MTA-STS allows domain owners to declare that their mail servers support TLS and specify policies for message delivery. mailauth provides functions to fetch, parse, and validate MTA-STS policies.

const { getPolicy, validateMx } = require('mailauth/lib/mta-sts');

getPolicy Result

The getPolicy function fetches and returns the MTA-STS policy for a domain.

const { policy, status } = await getPolicy('example.com', knownPolicy);

Result Object Fields

Field Type Description
policy object The MTA-STS policy object (see below)
status string Policy retrieval status (see below)

Status Values

Status Description
found New or updated policy was fetched successfully
not_found No MTA-STS policy exists for the domain
renewed Existing policy is still valid (ID unchanged, not expired)
errored Policy discovery failed due to an error

Policy Object Fields

Field Type Presence Description
id string|false Always Policy ID from DNS TXT record, or false if not found
version string Policy found Always "STSv1" for valid policies
mode string Always Policy mode (see below)
mx string[] Mode not "none" Array of allowed MX hostnames (may include wildcards)
maxAge number Policy found Policy validity period in seconds
expires string Policy found ISO 8601 expiration timestamp
error Error On error Error object if discovery failed

Mode Values

Mode Description
testing Policy is in test mode; report violations but don't enforce
enforce Strictly enforce TLS and MX restrictions
none No policy in effect

validateMx Result

The validateMx function checks if an MX hostname is valid according to the MTA-STS policy.

const result = validateMx('alt1.mx.example.com', policy);

Result Object Fields

Field Type Presence Description
valid boolean Always Whether the MX hostname is allowed
mode string Always Policy mode ("testing", "enforce", or "none")
match string Valid match The pattern that matched (exact hostname or wildcard)
testing boolean Always Whether policy is in testing mode

Example Output

Policy Found

{
    "policy": {
        "id": "20240115T120000",
        "version": "STSv1",
        "mode": "enforce",
        "mx": ["mx1.example.com", "mx2.example.com", "*.mail.example.com"],
        "maxAge": 86400,
        "expires": "2024-01-16T12:00:00.000Z"
    },
    "status": "found"
}

Policy Not Found

{
    "policy": {
        "id": false,
        "mode": "none"
    },
    "status": "not_found"
}

Policy Renewed (Cached)

{
    "policy": {
        "id": "20240115T120000",
        "version": "STSv1",
        "mode": "enforce",
        "mx": ["mx1.example.com", "mx2.example.com"],
        "maxAge": 86400,
        "expires": "2024-01-16T12:00:00.000Z"
    },
    "status": "renewed"
}

Policy Error

{
    "policy": {
        "id": "20240115T120000",
        "mode": "none",
        "expires": "2024-01-15T13:00:00.000Z",
        "error": {
            "message": "Request timeout for https://mta-sts.example.com/.well-known/mta-sts.txt",
            "code": "HTTP_SOCKET_TIMEOUT"
        }
    },
    "status": "errored"
}

MX Validation - Valid Match

{
    "valid": true,
    "mode": "enforce",
    "match": "mx1.example.com",
    "testing": false
}

MX Validation - Wildcard Match

{
    "valid": true,
    "mode": "enforce",
    "match": ".mail.example.com",
    "testing": false
}

MX Validation - Invalid

{
    "valid": false,
    "mode": "enforce",
    "testing": false
}

MX Validation - Testing Mode

{
    "valid": true,
    "mode": "testing",
    "match": "mx1.example.com",
    "testing": true
}

MX Validation - No Policy

{
    "valid": true,
    "mode": "none",
    "testing": false
}

Error Codes

Errors that may appear in policy.error:

Code Description
multi_sts_records Multiple TXT records found for _mta-sts.{domain}
invalid_sts_version Policy file has invalid or missing version field
invalid_sts_mode Policy file has invalid mode value
invalid_sts_max_age Policy file has invalid max_age value
invalid_sts_mx Policy file missing mx field in enforce/testing mode
HTTP_SOCKET_TIMEOUT HTTP request timed out
http_status_{code} HTTP request returned non-2xx status
ENOTFOUND DNS lookup failed (domain not found)
ENODATA DNS lookup returned no data

Usage Example

const { getPolicy, validateMx } = require('mailauth/lib/mta-sts');

// Fetch policy
const { policy, status } = await getPolicy('gmail.com');

console.log(`Policy status: ${status}`);
console.log(`Policy mode: ${policy.mode}`);

if (policy.mode !== 'none') {
    // Validate MX hostname
    const mx = 'alt1.gmail-smtp-in.l.google.com';
    const validation = validateMx(mx, policy);

    if (!validation.valid && !validation.testing) {
        console.error(`MX ${mx} is not allowed by MTA-STS policy`);
        // Reject delivery attempt
    } else if (!validation.valid && validation.testing) {
        console.warn(`MX ${mx} violates MTA-STS policy (testing mode)`);
        // Report violation but continue
    } else {
        console.log(`MX ${mx} is allowed`);
    }
}