Registry / auth-security / haraka-plugin-spf

haraka-plugin-spf

library1.2.11jsnpmunverified

This package, `haraka-plugin-spf`, implements the Sender Policy Framework (SPF) within the Haraka SMTP server. The current stable version is 1.2.11. It primarily adds `Received-SPF` headers to emails, with robust configurable options to defer or deny mail based on SPF test results, such as `mfrom_fail` for sender validation. While it has seen consistent updates recently, including ES6 refactoring, dependency bumps, and header formatting improvements, it does not adhere to a strict time-based release cadence, focusing instead on bug fixes and enhancements. Its key differentiator is its deep and flexible integration into the Haraka ecosystem, allowing granular control via `spf.ini` for handling various SPF outcomes (none, softfail, fail, permerror) for both HELO and MAIL FROM contexts, and specifically for relayed connections. It also provides a valuable command-line tool for debugging SPF records and validating domain configurations. The plugin allows Haraka operators to enforce SPF policies ranging from mere informational headers to hard rejections, providing essential protection against email spoofing.

auth-security communication

npm install haraka-plugin-spf

github ↗package ↗

INSTALL

IMPORT

SIG · HARAKA-PLUGIN-SPF

haraka-plugin-spf

auth-securityjavascriptv1.2.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

spf

✓ Add 'spf' to Haraka's config/plugins file.

✗ import { spf } from 'haraka-plugin-spf'; // Direct programmatic imports are not for end-users.

This package is a Haraka plugin. End-users enable it by listing 'spf' in their Haraka `config/plugins` file, rather than importing it directly into application code. Haraka handles the loading and execution.

spf.ini

✓ Create a file named `spf.ini` within Haraka's `config` directory.

✗ Configure SPF settings via JavaScript code or environment variables directly.

The primary configuration for `haraka-plugin-spf` is done through the `spf.ini` file. This INI file allows for fine-grained control over lookup timeouts, denial policies for various SPF outcomes (e.g., `helo_fail`, `mfrom_softfail`), and behavior for relayed connections.

Plugin

✓ const Plugin = require('haraka-plugin-spf'); // Used internally by Haraka or by developers extending the plugin.

✗ import { Plugin } from 'haraka-plugin-spf'; // Not typically used by end-users.

While the plugin's `index.js` may have undergone ES6 refactoring (v1.2.10), Haraka's plugin loading mechanism fundamentally uses CommonJS `require()`. This pattern is for Haraka itself or for developers creating other plugins that interact with `haraka-plugin-spf` programmatically, not for typical end-user setup.

This quickstart demonstrates how to enable the `haraka-plugin-spf` by adding it to Haraka's `config/plugins` file and setting up a basic `spf.ini` configuration to deny messages that explicitly fail SPF for the MAIL FROM address.

/* Haraka config/plugins file */ # This is a comment # Your other plugins... data.headers rules queue/smtp_proxy spf # Add this line to enable the SPF plugin /* Haraka config/spf.ini file */ ; Place this file in your Haraka config directory (e.g., /etc/haraka/config/spf.ini) lookup_timeout = 29 [relay] context=sender [skip] relaying=false auth=false [deny] mfrom_fail=true ; Only deny explicit MAIL FROM SPF failures openspf_text=true ; Add OpenSPF explanation text on deny [deny_relay] ; Typically do not deny SPF for relayed mail, unless specific policies are needed. mfrom_fail=false openspf_text=false // After configuring, restart Haraka: // sudo haraka -c /etc/haraka // (or whichever command you use to start Haraka)

haraka-plugin-spf --version

Debug

Known issues

breakingLegacy configuration support was removed in version 1.2.10. Users upgrading from very old versions might need to update their `spf.ini` files.

fix

Review your `spf.ini` against the latest documentation and default settings. Remove any outdated or non-standard directives.

affects: >=1.2.10

breakingThe formatting of the `Received-SPF` header was refactored in version 1.2.11 to fold the header and remove redundant server names for better readability and compliance.

fix

No action is required, but be aware that automated parsers or logs relying on the exact previous header format might need adjustments.

affects: >=1.2.11

gotchaSPF HELO tests rarely pass for legitimate senders, as most do not publish SPF records for their mail server hostnames. Relying heavily on HELO validation for denial often leads to false positives.

fix

It is generally recommended to disable `deny.helo_fail` and similar HELO-based denial options. Focus instead on `mfrom_fail` for more reliable SPF enforcement.

affects: All

gotchaEnabling SPF error deferrals (`defer.helo_temperror`, `defer.mfrom_temperror`) can cause excessive delays or bounced mail for senders with broken DNS configurations.

fix

Only enable deferrals for temporary errors if you are willing to accept potential delays or loss of valid mail. It's often safer to log these errors than to defer on them.

affects: All

gotchaBroken SPF records by valid senders are common. Denying mail based on SPF errors (e.g., `helo_permerror`, `mfrom_permerror`) can lead to legitimate emails being rejected.

fix

Exercise caution when enabling denial for SPF error results. `mfrom_fail` is typically the only deny option most sites should consider, and even then, be aware of legitimate mail from forwarders/mailing lists.

affects: All

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'length') OR similar crash related to MX records.

An issue where the plugin attempted to process DNS MX records that were either missing or malformed, leading to an undefined variable.

fix

Upgrade `haraka-plugin-spf` to version 1.2.9 or newer, which contains a fix for crashes in `mech_mx` code when no valid MX records are found.

Haraka failed to load plugin: spf (Error: ENOENT: no such file or directory, open '.../haraka/config/spf.ini')

The `spf.ini` configuration file is either missing from Haraka's `config` directory or is incorrectly named.

fix

Create `spf.ini` in your Haraka `config` directory. You can start with the commented-out default settings provided in the `haraka-plugin-spf` repository's README or package.

Haraka plugin 'spf' returned an error during [hook name]: ReferenceError: someLegacyConfigVariable is not defined OR plugin behaves unexpectedly due to config.

Your `spf.ini` file contains deprecated or unsupported configuration directives, likely due to an upgrade from an older plugin version.

fix

Review the `spf.ini` file and remove any options that are no longer documented or have been deprecated. Specifically, ensure no 'legacy config support' options are present if upgrading to v1.2.10+.

Upgrade

Version history

1.2.11latest on npm

Audit

Dependencies

net-utilsrequiredUsed for network utility functions, likely for DNS lookups and IP parsing.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/haraka/haraka-plugin-spf ↗

packagehttps://www.npmjs.com/package/haraka-plugin-spf ↗