### Install mailauth npm package

Source: https://github.com/postalsys/mailauth/blob/master/README.md

Install the mailauth library using npm. This is the first step before importing its methods into your project.

```bash
npm install mailauth
```

--------------------------------

### Install Dependencies Script

Source: https://github.com/postalsys/mailauth/blob/master/test/fixtures/arc/README.md

Execute this script to install necessary external packages for the ARC test suite.

```bash
./dependencies.py
```

--------------------------------

### MTA-STS Policy Found Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example JSON output when a new or updated MTA-STS policy is successfully fetched.

```json
{
    "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"
}
```

--------------------------------

### MTA-STS Policy Not Found Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example JSON output when no MTA-STS policy is found for the domain.

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

--------------------------------

### BIMI None (No Record) Example Output

Source: https://github.com/postalsys/mailauth/blob/master/docs/bimi.md

Example JSON output when no BIMI record is found for the domain. This indicates that BIMI is not configured or applicable.

```json
{
    "status": {
        "result": "none",
        "header": {
            "selector": "default",
            "d": "example.com"
        }
    },
    "info": "bimi=none header.selector=default header.d=example.com"
}
```

--------------------------------

### Install mailauth CLI via npm

Source: https://github.com/postalsys/mailauth/blob/master/cli.md

Install the mailauth CLI globally using npm. This command is used to add the mailauth utility to your system's PATH.

```bash
npm install -g mailauth
```

--------------------------------

### MTA-STS Policy Error Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example JSON output when an error occurs during MTA-STS policy discovery.

```json
{
    "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"
}
```

--------------------------------

### Example DMARC Status Comment

Source: https://github.com/postalsys/mailauth/blob/master/docs/dmarc.md

Provides an example of a DMARC status comment string.

```plaintext
p=REJECT sp=REJECT arc=pass
```

--------------------------------

### CLI spf command

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Example of using the `spf` subcommand of the mailauth CLI tool to verify SPF records.

```bash
mailauth spf --sender "test@example.com" --helo "example.com"
```

--------------------------------

### CLI sign command

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Example of using the `sign` subcommand of the mailauth CLI tool for DKIM signing.

```bash
mailauth sign --key ./test/fixtures/private.key --selector dkim --domain example.com --body "Hello World"
```

--------------------------------

### DNS helper function

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Example usage of a DNS helper function from `lib/tools.js`, likely for performing DNS lookups.

```javascript
import { lookup } from "./lib/tools.js";

const address = await lookup("example.com");
console.log(address);
```

--------------------------------

### Get mailauth CLI Help

Source: https://github.com/postalsys/mailauth/blob/master/cli.md

Display help information for the mailauth CLI or specific commands using the --help flag. This is useful for understanding available options and usage.

```bash
mailauth --help
mailauth report --help
mailauth sign --help
mailauth seal --help
mailauth spf --help
```

--------------------------------

### BIMI Skipped (DMARC Failed) Example Output

Source: https://github.com/postalsys/mailauth/blob/master/docs/bimi.md

Example JSON output when BIMI validation is skipped due to DMARC failure. The message did not meet DMARC requirements.

```json
{
    "status": {
        "result": "skipped",
        "comment": "message failed DMARC",
        "header": {}
    },
    "info": "bimi=skipped (message failed DMARC)"
}
```

--------------------------------

### AR Consolidation Example

Source: https://github.com/postalsys/mailauth/blob/master/test/fixtures/arc/README.md

Illustrates how Authentication-Results (AR) headers are consolidated into an ARC-Authentication-Results (AAR) header.

```text
Authentication-Results: lists.example.org; arc=none;
  spf=pass smtp.mfrom=jqd@d1.example
Authentication-Results: lists.example.org; dkim=pass (1024-bit key) header.i=@d1.example
Authentication-Results: lists.example.org; dmarc=pass
Authentication-Results: nobody.example.org; something=ignored
MIME-Version: 1.0
Return-Path: <jqd@d1.example.org>
....

Would yield the following AAR, assuming this to be the first arc hop:

ARC-Authentication-Results: i=1; lists.example.org; arc=none;
  spf=pass smtp.mfrom=jqd@d1.example;
  dkim=pass (1024-bit key) header.i=@d1.example;
  dmarc=pass
```

--------------------------------

### BIMI Pass Example Output

Source: https://github.com/postalsys/mailauth/blob/master/docs/bimi.md

Example JSON output when BIMI validation passes. This indicates successful validation of the VMC and associated logo.

```json
{
    "status": {
        "result": "pass",
        "header": {
            "selector": "default",
            "d": "example.com"
        },
        "policy": {
            "authority": "none",
            "authority-uri": "https://example.com/bimi/vmc.pem"
        }
    },
    "location": "https://example.com/bimi/logo.svg",
    "authority": "https://example.com/bimi/vmc.pem",
    "preference": "self",
    "rr": "v=BIMI1; l=https://example.com/bimi/logo.svg; a=https://example.com/bimi/vmc.pem; p=self",
    "info": "bimi=pass header.selector=default header.d=example.com policy.authority=none policy.authority-uri=https://example.com/bimi/vmc.pem"
}
```

--------------------------------

### CLI seal command

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Example of using the `seal` subcommand of the mailauth CLI tool for ARC sealing.

```bash
mailauth seal --key ./test/fixtures/arc.key --selector arc --domain example.com --chain "1"
```

--------------------------------

### SPF None (No Record) Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/spf.md

Represents a scenario where no SPF record is found for the domain. This can lead to emails being marked as suspicious or rejected, as there's no explicit authorization.

```json
{
    "domain": "no-spf.example.com",
    "client-ip": "192.0.2.1",
    "helo": "mail.no-spf.example.com",
    "envelope-from": "user@no-spf.example.com",
    "status": {
        "result": "none",
        "comment": "mx.receiver.com: no-spf.example.com does not designate permitted sender hosts",
        "smtp": {
            "mailfrom": "user@no-spf.example.com",
            "helo": "mail.no-spf.example.com"
        }
    },
    "header": "Received-SPF: none (mx.receiver.com: no-spf.example.com does not designate permitted sender hosts) client-ip=192.0.2.1;",
    "info": "spf=none (mx.receiver.com: no-spf.example.com does not designate permitted sender hosts) smtp.mailfrom=user@no-spf.example.com smtp.helo=mail.no-spf.example.com",
    "lookups": {
        "limit": 10,
        "count": 1,
        "void": 1,
        "subqueries": {}
    }
}
```

--------------------------------

### Example Validation Scenario YAML

Source: https://github.com/postalsys/mailauth/blob/master/test/fixtures/arc/README.md

A sample YAML configuration for an ARC validation test scenario. Includes message content and DNS TXT records.

```yaml
description: >-
  dummy scenario
tests:
  test1:
    spec:        12/16
    description: basic test
    message:     |
      MIME-Version: 1.0
      Return-Path: <jqd@d1.example.org>
      Received: by 10.157.14.6 with HTTP; Tue, 3 Jan 2017 12:22:54 -0800 (PST)
      Message-ID: <54B84785.1060301@d1.example.org>
      Date: Thu, 14 Jan 2015 15:00:01 -0800
      From: John Q Doe <jqd@d1.example.org>
      To: arc@dmarc.org
      Subject: Example 1

      Hey gang,
      This is a test message.
      --J.
    cv:          None
txt_records:
  dummy._domainkey.example.org: >-
    v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAg1i2lO83x/r58cbo/JSBwfZrrct6S/yi4L6GsG3wNgFE9lO3orzBwnAEJJM33WrvJfOWia1fAx64Vs1QEpYtLFCzyeIhDDMaHv/G8NgKPgnWK4gI8/x2Q2SYCmiqil66oHaSOC2phMDRI+c/Q35MlZbc2FqlgevpKzdCg+YE6mYA0XN7/tdQplbx4meLVsVPIL9QCP4yu8oBsNqcwyxkQafJucVyoZI+VEO+dySw3QXNdmJhr7y1hD1tCNqoAG0iphKQVXPXmGnGhaxaVU92Kq5UKL6/LiTZ1piqyJfJyZ/zCgH+mtY8MNk9f7LHpwFljI7TbYmr7MmV3d6xj3sghwIDAQAB
comment: >-
  This is a comment
```

--------------------------------

### MTA-STS Policy: No Policy Mode

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example of an MTA-STS policy JSON configuration where no policy is applied.

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

--------------------------------

### Example ARC Signing Scenario

Source: https://github.com/postalsys/mailauth/blob/master/test/fixtures/arc/README.md

This snippet defines a dummy signing scenario for ARC. It includes a sample message with Authentication-Results, SPF, DKIM, and DMARC information, along with signing parameters and a private key.

```yaml
description: >-
  dummy scenario
tests:
  test1:
    spec:        12/16
    description: basic test
    message:      |
      Authentication-Results: lists.example.org;
        spf=pass smtp.mfrom=jqd@d1.example;
        dkim=pass (1024-bit key) header.i=@d1.example;
        dmarc=pass
      MIME-Version: 1.0
      Return-Path: <jqd@d1.example.org>
      Received: by 10.157.14.6 with HTTP; Tue, 3 Jan 2017 12:22:54 -0800 (PST)
      Message-ID: <54B84785.1060301@d1.example.org>
      Date: Thu, 14 Jan 2015 15:00:01 -0800
      From: John Q Doe <jqd@d1.example.org>
      To: arc@dmarc.org
      Subject: Example 1

      Hey gang,
      This is a test message.
      --J.
    t:           12345
    sig-headers: from:to:subject
    srv-id: lists.example.org
    AS:          |
      a=rsa-sha256; b=oXNsU/I3fVAFVMIhssuTgCkdSqw6tLBI9w9c+izOlrVQElsVxarVCmhH
      7NGae7CyqDQMYxEFfrqjzSxsu6G9yhqxsge574oHCvZgx8VLkFAa16hrBe0M+YPauA0TCkMm
      zGPLTDJVtblJ5qZApAuIizX8smdreZJVS3BAv7FpnmQ=;
      cv=none; d=example.org; i=1; s=dummy; t=12345
    AMS:         |
      a=rsa-sha256;
      b=aHfjYd84tmqd6nApu4mmmxbR6ZRLwgqN5Acppn4jj3Dfij0WRHLpe22E30AiJ1fyyRyKS0
      zZmOfhcYA+5B2IJv91EjUzP3Vt1gW5UqjhYMkeJl4NCBdn0xBdn49fBX9w0PbC7AZjW3tok0
      ZEuORs3bB9rnoh1BSU+OM7+HnxxRo=;
      bh=KWSe46TZKCcDbH4klJPo+tjk5LWJnVRlP5pvjXFZYLQ=; c=relaxed/relaxed;
      d=example.org; h=from:to:subject:arc-authentication-results; i=1;
      s=dummy; t=12345
    AAR:         |
      i=1; lists.example.org;
      spf=pass smtp.mfrom=jqd@d1.example;
      dkim=pass (1024-bit key) header.i=@d1.example;
      dmarc=pass
domain:     example.org
sel:        dummy
privatekey: |
  -----BEGIN RSA PRIVATE KEY-----
  MIICXQIBAAKBgQDkHlOQoBTzWRiGs5V6NpP3idY6Wk08a5qhdR6wy5bdOKb2jLQi
  Y/J16JYi0Qvx/byYzCNb3W91y3FutACDfzwQ/BC/e/8uBsCR+yz1Lxj+PL6lHvqM
  KrM3rG4hstT5QjvHO9PzoxZyVYLzBfO2EeC3Ip3G+2kryOTIKT+l/K4w3QIDAQAB
  AoGAH0cxOhFZDgzXWhDhnAJDw5s4roOXN4OhjiXa8W7Y3rhX3FJqmJSPuC8N9vQm
  6SVbaLAE4SG5mLMueHlh4KXffEpuLEiNp9Ss3O4YfLiQpbRqE7Tm5SxKjvvQoZZe
  zHorimOaChRL2it47iuWxzxSiRMv4c+j70GiWdxXnxe4UoECQQDzJB/0U58W7RZy
  6enGVj2kWF732CoWFZWzi1FicudrBFoy63QwcowpoCazKtvZGMNlPWnC7x/6o8Gc
  uSe0ga2xAkEA8C7PipPm1/1fTRQvj1o/dDmZp243044ZNyxjg+/OPN0oWCbXIGxy
  WvmZbXriOWoSALJTjExEgraHEgnXssuk7QJBALl5ICsYMu6hMxO73gnfNayNgPxd
  WFV6Z7ULnKyV7HSVYF0hgYOHjeYe9gaMtiJYoo0zGN+L3AAtNP9huqkWlzECQE1a
  licIeVlo1e+qJ6Mgqr0Q7Aa7falZ448ccbSFYEPD6oFxiOl9Y9se9iYHZKKfIcst
  o7DUw1/hz2Ck4N5JrgUCQQCyKveNvjzkkd8HjYs0SwM0fPjK16//5qDZ2UiDGnOe
  uEzxBDAr518Z8VFbR41in3W4Y3yCDgQlLlcETrS+zYcL
  -----END RSA PRIVATE KEY-----
txt-records:
  dummy._domainkey.example.org: |
    v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDkHlOQ
    oBTzWRiGs5V6NpP3idY6Wk08a5qhdR6wy5bdOKb2jLQiY/J16JYi0Qvx/byYzC
    Nb3W91y3FutACDfzwQ/BC/e/8uBsCR+yz1Lxj+PL6lHvqMKrM3rG4hstT5QjvH
    O9PzoxZyVYLzBfO2EeC3Ip3G+2kryOTIKT+l/K4w3QIDAQAB
comment: >-
  This is a comment
```

--------------------------------

### SPF Pass Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/spf.md

Illustrates a successful SPF check where the sending IP is authorized by the domain's SPF record. This indicates proper mail server configuration.

```json
{
    "domain": "example.com",
    "client-ip": "192.0.2.1",
    "helo": "mail.example.com",
    "envelope-from": "user@example.com",
    "status": {
        "result": "pass",
        "comment": "mx.receiver.com: domain of user@example.com designates 192.0.2.1 as permitted sender",
        "smtp": {
            "mailfrom": "user@example.com",
            "helo": "mail.example.com"
        }
    },
    "header": "Received-SPF: pass (mx.receiver.com: domain of user@example.com designates 192.0.2.1 as permitted sender) client-ip=192.0.2.1;",
    "info": "spf=pass (mx.receiver.com: domain of user@example.com designates 192.0.2.1 as permitted sender) smtp.mailfrom=user@example.com smtp.helo=mail.example.com",
    "rr": "v=spf1 ip4:192.0.2.0/24 -all",
    "lookups": {
        "limit": 10,
        "count": 1,
        "void": 0,
        "subqueries": {}
    }
}
```

--------------------------------

### DMARC with Subdomain Policy Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/dmarc.md

Demonstrates a DMARC record with a specific subdomain policy ('sp'). The main domain policy ('p') and subdomain policy ('sp') can differ.

```json
{
    "status": {
        "result": "pass",
        "header": {
            "from": "example.com",
            "d": "sub.example.com"
        },
        "comment": "p=NONE sp=QUARANTINE"
    },
    "domain": "example.com",
    "policy": "quarantine",
    "p": "none",
    "sp": "quarantine",
    "pct": 100,
    "rr": "v=DMARC1; p=none; sp=quarantine; rua=mailto:dmarc@example.com",
    "alignment": {
        "spf": {
            "result": "example.com",
            "strict": false
        },
        "dkim": {
            "result": false,
            "strict": false
        }
    },
    "info": "dmarc=pass (p=NONE sp=QUARANTINE) header.from=example.com"
}
```

--------------------------------

### BIMI Skipped (Policy Too Lax) Example Output

Source: https://github.com/postalsys/mailauth/blob/master/docs/bimi.md

Example JSON output when BIMI validation is skipped because the DMARC policy is too lax. This means the DMARC policy does not enforce sufficient authentication.

```json
{
    "status": {
        "result": "skipped",
        "comment": "too lax DMARC policy",
        "header": {}
    },
    "info": "bimi=skipped (too lax DMARC policy)"
}
```

--------------------------------

### CLI bodyhash command

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Example of using the `bodyhash` subcommand of the mailauth CLI tool to calculate the DKIM body hash.

```bash
mailauth bodyhash --body "Hello World" --canonicalization "relaxed/simple"
```

--------------------------------

### DMARC None (No Record) Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/dmarc.md

Represents a scenario where no DMARC record was found for the domain. The 'result' field is 'none'.

```json
{
    "status": {
        "result": "none",
        "header": {
            "from": "no-dmarc.example.com"
        }
    },
    "domain": "no-dmarc.example.com",
    "info": "dmarc=none header.from=no-dmarc.example.com"
}
```

--------------------------------

### DMARC Fail Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/dmarc.md

Illustrates a DMARC record result where authentication failed. The 'result' field is 'fail'.

```json
{
    "status": {
        "result": "fail",
        "header": {
            "from": "example.com",
            "d": "example.com"
        },
        "comment": "p=REJECT"
    },
    "domain": "example.com",
    "policy": "reject",
    "p": "reject",
    "sp": "reject",
    "pct": 100,
    "rr": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
    "alignment": {
        "spf": {
            "result": false,
            "strict": false
        },
        "dkim": {
            "result": false,
            "strict": false
        }
    },
    "info": "dmarc=fail (p=REJECT) header.from=example.com"
}
```

--------------------------------

### Python Test Harness for ARC

Source: https://github.com/postalsys/mailauth/blob/master/test/fixtures/arc/README.md

This Python script serves as a harness for running ARC test suites. It accepts 'sign' or 'validate' as input and requires a command-line tool to perform the operation. A local DNS server is started during execution.

```python
import sys

def main():
    if len(sys.argv) < 3:
        print("Usage: testarc.py <sign|validate> <tool> [tool_args...]\n")
        sys.exit(1)

    command = sys.argv[1]
    tool = sys.argv[2]

    if command not in ('sign', 'validate'):
        print("Command must be 'sign' or 'validate'.\n")
        sys.exit(1)

    # Placeholder for actual test suite execution logic
    print(f"Running test suite with command: {command} and tool: {tool}")
    # In a real scenario, this would involve setting up a DNS server,
    # executing the specified tool, and processing results.

if __name__ == '__main__':
    main()
```

--------------------------------

### MTA-STS Policy: Testing Mode

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example of an MTA-STS policy JSON configuration for testing mode, allowing validation without enforcement.

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

--------------------------------

### CLI vmc command

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Example of using the `vmc` subcommand of the mailauth CLI tool, likely for validating BIMI-related information.

```bash
mailauth vmc --domain "example.com" --selector "default"
```

--------------------------------

### DMARC Pass Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/dmarc.md

Shows a DMARC record result indicating a successful authentication. The 'result' field is 'pass'.

```json
{
    "status": {
        "result": "pass",
        "header": {
            "from": "example.com",
            "d": "example.com"
        },
        "comment": "p=REJECT arc=none"
    },
    "domain": "example.com",
    "policy": "reject",
    "p": "reject",
    "sp": "reject",
    "pct": 100,
    "rr": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
    "alignment": {
        "spf": {
            "result": false,
            "strict": false
        },
        "dkim": {
            "result": "example.com",
            "strict": false
        }
    },
    "info": "dmarc=pass (p=REJECT arc=none) header.from=example.com"
}
```

--------------------------------

### DNS Cache File Format

Source: https://context7.com/postalsys/mailauth/llms.txt

Example structure for a DNS cache file used with the `--dns-cache` option in the mailauth CLI. It maps domains to their TXT and MX DNS records.

```json
{
  "example.com": {
    "TXT": [["v=spf1 include:_spf.example.com -all"]],
    "MX": [{ "exchange": "mail.example.com", "priority": 10 }]
  },
  "_dmarc.example.com": {
    "TXT": [["v=DMARC1; p=reject; rua=mailto:dmarc@example.com;"]]
  }
}
```

--------------------------------

### Authenticate Message with ARC

Source: https://github.com/postalsys/mailauth/blob/master/docs/arc.md

Initiates message authentication, enabling ARC validation. Ensure the 'mailauth' library is installed and imported.

```javascript
const { authenticate } = require('mailauth');

const { arc } = await authenticate(message, {
    trustReceived: true
});
```

--------------------------------

### Run all tests

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Execute all linting and mocha tests for the project.

```bash
npm test
```

--------------------------------

### MTA-STS Policy Renewed Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example JSON output when an existing MTA-STS policy is still valid and has not expired.

```json
{
    "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"
}
```

--------------------------------

### SPF verification with custom resolver

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Shows how to use the SPF verification function with a custom DNS resolver, enabling testing with mock data or custom caching.

```javascript
import { verify } from "./lib/spf/index.js";

const resolver = async (domain, recordType) => {
  // Mock DNS lookup logic
  if (domain === 'example.com' && recordType === 'TXT') {
    return ['"v=spf1 mx -all"'];
  }
  return [];
};

const result = await verify("sender@example.com", "example.com", resolver);
console.log(result);
```

--------------------------------

### Format code

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Format code using Prettier according to project style guidelines.

```bash
npm run format
```

--------------------------------

### Get DMARC Record

Source: https://github.com/postalsys/mailauth/blob/master/README.md

Retrieves the DMARC record for a given domain. Requires the 'mailauth/lib/dmarc/get-dmarc-record' module.

```javascript
const getDmarcRecord = require('mailauth/lib/dmarc/get-dmarc-record');

const dmarcRecord = await getDmarcRecord('ethereal.email');
console.log(dmarcRecord);
```

--------------------------------

### MTA-STS Policy: Invalid Configuration

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example of an MTA-STS policy JSON configuration indicating an invalid state.

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

--------------------------------

### Run a single test file

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Execute a specific test file using mocha.

```bash
npx mocha test/dkim/body/relaxed-test.js --reporter spec
```

--------------------------------

### Get DMARC Record

Source: https://github.com/postalsys/mailauth/blob/master/README.md

Retrieves the DMARC record for a given domain. Supports custom DNS resolvers.

```APIDOC
## Get DMARC Record

### Description
Retrieves the DMARC record for a given domain. Supports custom DNS resolvers.

### Method
`getDmarcRecord(domain, resolver)`

### Parameters
#### Path Parameters
- **domain** (string): The domain to check for a DMARC record.
- **resolver** (function, optional): Custom DNS resolver function. Defaults to `dns.resolve`.

### Request Example
```javascript
const getDmarcRecord = require('mailauth/lib/dmarc/get-dmarc-record');

const dmarcRecord = await getDmarcRecord('ethereal.email');
console.log(dmarcRecord);
```

### Response
#### Success Response (200)
- **v** (string): DMARC version.
- **p** (string): Policy.
- **pct** (integer): Percentage.
- **rua** (string): Reporting URI for aggregate reports.
- **sp** (string): Subdomain policy.
- **aspf** (string): Address alignment for SPF.
- **rr** (string): Raw DMARC record.
- **isOrgRecord** (boolean): Indicates if it's an organizational record.

#### Response Example
```json
{
    "v": "DMARC1",
    "p": "none",
    "pct": 100,
    "rua": "mailto:re+joqy8fpatm3@dmarc.postmarkapp.com",
    "sp": "none",
    "aspf": "r",
    "rr": "v=DMARC1; p=none; pct=100; rua=mailto:re+joqy8fpatm3@dmarc.postmarkapp.com; sp=none; aspf=r;",
    "isOrgRecord": false
}
```
```

--------------------------------

### JavaScript: Fetch and Validate MTA-STS Policy

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Demonstrates how to fetch an MTA-STS policy for a given domain and validate an MX hostname against it using the mailauth library.

```javascript
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`);
    }
}
```

--------------------------------

### Main authentication function export

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

The main entry point `lib/mailauth.js` exports the `authenticate()` function and individual protocol functions.

```javascript
import { authenticate } from "./lib/mailauth.js";
// or
const mailauth = require("./lib/mailauth");
mailauth.authenticate();
```

--------------------------------

### Get MTA-STS Policy

Source: https://github.com/postalsys/mailauth/blob/master/README.md

Fetches the MTA-STS policy for a given domain. Supports using a previously cached policy.

```APIDOC
## Get MTA-STS Policy

### Description
Fetches the MTA-STS policy for a given domain. Supports using a previously cached policy.

### Method
`getPolicy(domain, knownPolicy)`

### Parameters
#### Path Parameters
- **domain** (string): The domain to retrieve the policy for.
- **knownPolicy** (object, optional): Previously cached policy for the domain.

### Request Example
```javascript
const { getPolicy } = require('mailauth/lib/mta-sts');

const knownPolicy = /* Retrieve from your cache if available */;
const { policy, status } = await getPolicy('gmail.com', knownPolicy);

if (policy.id !== knownPolicy?.id) {
  // Update your cache with the new policy
}

if (policy.mode === 'enforce') {
  // TLS must be used when sending to this domain
}
```

### Response
#### Success Response (200)
- **policy** (object): The MTA-STS policy object.
- **status** (string): The status of the policy retrieval. Possible values: "not_found", "cached", "found", "renew", "errored".

**Possible Status Values:**
- "not_found": No policy was found.
- "cached": Existing policy is still valid.
- "found": New or updated policy found.
- "renew": Existing policy is valid; renew cache.
- "errored": Policy discovery failed due to a temporary error.
```

--------------------------------

### MTA-STS Policy: Wildcard Match

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example of an MTA-STS policy JSON configuration that uses a wildcard match for MX validation.

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

--------------------------------

### MX Validation Result - Valid Match

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Example JSON output when an MX hostname is valid according to the MTA-STS policy.

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

--------------------------------

### Display Mailauth License

Source: https://github.com/postalsys/mailauth/blob/master/cli.md

Displays the license information for the mailauth tool and its included modules.

```bash
mailauth license
```

--------------------------------

### CLI Usage

Source: https://context7.com/postalsys/mailauth/llms.txt

Command-line interface commands for mailauth, including reporting, signing, sealing, and SPF checks.

```APIDOC
## CLI Usage

mailauth ships a `mailauth` binary installable via npm or as a standalone binary for macOS, Linux, and Windows.

### Commands

#### `report`
Performs a full authentication check on an email file.

**Usage:**
```bash
mailauth report [options] <email_file>
```

**Options:**
- `--client-ip <ip>`: The client IP address.
- `--sender <email>`: The sender's email address.
- `--helo <hostname>`: The HELO/EHLO hostname.
- `--mta <hostname>`: The Mail Transfer Agent hostname.
- `--verbose`: Enable verbose output.
- `--dns-cache <file>`: Use a DNS cache file for offline/CI testing.

**Output:** JSON with DKIM, SPF, ARC, DMARC, BIMI, and received chain information.

#### `sign`
Adds a DKIM signature to an email file.

**Usage:**
```bash
mailauth sign [options] <email_file>
```

**Options:**
- `--domain <domain>`: The signing domain.
- `--selector <selector>`: The DKIM selector.
- `--private-key <path>`: Path to the private key file.
- `--canonicalization <type>`: Canonicalization method (e.g., `relaxed/relaxed`).
- `--verbose`: Enable verbose output.

#### `seal`
Adds an ARC seal to an email file.

**Usage:**
```bash
mailauth seal [options] <email_file>
```

**Options:**
- `--domain <domain>`: The signing domain.
- `--selector <selector>`: The ARC selector.
- `--private-key <path>`: Path to the private key file.
- `--client-ip <ip>`: The client IP address.
- `--mta <hostname>`: The Mail Transfer Agent hostname.
- `--verbose`: Enable verbose output.

#### `spf`
Checks the SPF record for a given sender and client IP.

**Usage:**
```bash
mailauth spf [options]
```

**Options:**
- `--sender <email>`: The sender's email address.
- `--client-ip <ip>`: The client IP address.
- `--verbose`: Enable verbose output.

#### `vmc`
Validates a BIMI VMC certificate.

**Usage:**
```bash
mailauth vmc [options]
```

**Options:**
- `--authority <url>`: The URL of the VMC certificate authority.
- `--domain <domain>`: The domain associated with the VMC.

#### `bodyhash`
Computes the DKIM body hash for an email file.

**Usage:**
```bash
mailauth bodyhash [options] <email_file>
```

**Options:**
- `--algo <algorithm>`: The hashing algorithm (e.g., `sha256`).
- `--canonicalization <type>`: Canonicalization method (e.g., `relaxed`).

### DNS Cache File Format

```json
{
  "example.com": {
    "TXT": [["v=spf1 include:_spf.example.com -all"]],
    "MX": [{ "exchange": "mail.example.com", "priority": 10 }]
  },
  "_dmarc.example.com": {
    "TXT": [["v=DMARC1; p=reject; rua=mailto:dmarc@example.com;"]]
  }
}
```
```

--------------------------------

### Import mailauth MTA-STS Functions

Source: https://github.com/postalsys/mailauth/blob/master/docs/mta-sts.md

Import the necessary functions for fetching and validating MTA-STS policies.

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

--------------------------------

### DMARC Temperror Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/dmarc.md

Shows a DMARC record result indicating a temporary error during DMARC lookup. The 'result' field is 'temperror'.

```json
{
    "status": {
        "result": "temperror",
        "header": {
            "from": "example.com"
        }
    },
    "domain": "example.com",
    "error": "DNS timeout",
    "info": "dmarc=temperror header.from=example.com"
}
```

--------------------------------

### spf(options)

Source: https://context7.com/postalsys/mailauth/llms.txt

Verifies the SPF record for a given sender IP and MAIL FROM address. Performs live DNS lookups or uses a custom resolver. Supports single checks and batch processing.

```APIDOC
## spf(options)

### Description
Verifies the SPF record for a given sender IP and MAIL FROM address. Performs live DNS lookups (or uses a custom resolver).

### Method
`spf(options)`

### Parameters
#### Options Object
- **sender** (string) - Required - MAIL FROM address.
- **ip** (string) - Required - SMTP client IP (IPv4 or IPv6).
- **helo** (string) - Required - EHLO/HELO hostname.
- **mta** (string) - Optional - MTA performing the check.
- **maxResolveCount** (number) - Optional - Maximum DNS lookups (default: 10).
- **maxVoidCount** (number) - Optional - Maximum void lookups (default: 2).

### Request Example
```javascript
const { spf } = require('mailauth/lib/spf');
const result = await spf({
    sender: 'user@example.com',
    ip: '203.0.113.42',
    helo: 'mail.example.com',
    mta: 'mx.myhost.com',
    maxResolveCount: 10,
    maxVoidCount: 2
});
console.log(result.status.result);
```

### Response
#### Success Response
Returns an object containing SPF verification details.
- **header** (string) - The full Received-SPF header.
- **status** (object) - Contains the result of the SPF check.
  - **result** (string) - 'pass' | 'fail' | 'softfail' | 'neutral' | 'none' | 'permerror' | 'temperror'.
- **domain** (string) - The domain verified.
- **rr** (string) - The raw SPF TXT record string.
- **info** (string) - An Authentication-Results formatted line.
- **lookups** (object) - Details about DNS lookups performed.
  - **limit** (number) - The lookup limit.
  - **count** (number) - The number of lookups performed.
  - **void** (number) - The number of void lookups.
  - **subqueries** (object) - Details about subqueries.

### Response Example
```json
{
  "header": "Received-SPF: pass (mx.myhost.com: domain of user@example.com designates 203.0.113.42 as permitted sender) client-ip=203.0.113.42;\r\n envelope-from=\"user@example.com\";\r\n",
  "status": {
    "result": "pass"
  },
  "domain": "example.com",
  "rr": "v=spf1 mx -all",
  "info": "Authentication-Results: mx.myhost.com; spf=pass (sender IP matches 203.0.113.42) smtp.mailfrom=user@example.com",
  "lookups": {
    "limit": 10,
    "count": 3,
    "void": 0,
    "subqueries": {}
  }
}
```
```

--------------------------------

### Lint code

Source: https://github.com/postalsys/mailauth/blob/master/CLAUDE.md

Run ESLint to check code style and potential issues in JavaScript files.

```bash
npx eslint "lib/**/*.js" "test/**/*.js"
```

--------------------------------

### CLI: Full Authentication Report

Source: https://context7.com/postalsys/mailauth/llms.txt

Generates a comprehensive authentication check for an email file, including DKIM, SPF, ARC, DMARC, BIMI, and received chain information. Supports verbose output and DNS caching for offline testing.

```bash
mailauth report \
    --client-ip 217.146.67.33 \
    --sender andris@ekiri.ee \
    --helo uvn-67-33.tll01.zonevs.eu \
    --mta mx.myhost.com \
    --verbose \
    email.eml
```

```bash
mailauth report --dns-cache examples/dns-cache.json email.eml
```

--------------------------------

### SPF Fail Example

Source: https://github.com/postalsys/mailauth/blob/master/docs/spf.md

Shows an SPF check failure, meaning the sending IP is not authorized by the domain's SPF record. This often indicates a spoofing attempt or misconfiguration.

```json
{
    "domain": "example.com",
    "client-ip": "203.0.113.1",
    "helo": "attacker.example.net",
    "envelope-from": "user@example.com",
    "status": {
        "result": "fail",
        "comment": "mx.receiver.com: domain of user@example.com does not designate 203.0.113.1 as permitted sender",
        "smtp": {
            "mailfrom": "user@example.com",
            "helo": "attacker.example.net"
        }
    },
    "header": "Received-SPF: fail (mx.receiver.com: domain of user@example.com does not designate 203.0.113.1 as permitted sender) client-ip=203.0.113.1;",
    "info": "spf=fail (mx.receiver.com: domain of user@example.com does not designate 203.0.113.1 as permitted sender) smtp.mailfrom=user@example.com smtp.helo=attacker.example.net",
    "rr": "v=spf1 ip4:192.0.2.0/24 -all",
    "lookups": {
        "limit": 10,
        "count": 1,
        "void": 0,
        "subqueries": {}
    }
}
```