{"id":10992,"library":"haraka-plugin-spf","title":"Haraka SPF Plugin","description":"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.","status":"active","version":"1.2.11","language":"javascript","source_language":"en","source_url":"https://github.com/haraka/haraka-plugin-spf","tags":["javascript","haraka","haraka-plugin","plugin","spf"],"install":[{"cmd":"npm install haraka-plugin-spf","lang":"bash","label":"npm"},{"cmd":"yarn add haraka-plugin-spf","lang":"bash","label":"yarn"},{"cmd":"pnpm add haraka-plugin-spf","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for network utility functions, likely for DNS lookups and IP parsing.","package":"net-utils","optional":false}],"imports":[{"note":"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.","wrong":"import { spf } from 'haraka-plugin-spf'; // Direct programmatic imports are not for end-users.","symbol":"spf","correct":"Add 'spf' to Haraka's config/plugins file."},{"note":"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.","wrong":"Configure SPF settings via JavaScript code or environment variables directly.","symbol":"spf.ini","correct":"Create a file named `spf.ini` within Haraka's `config` directory."},{"note":"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.","wrong":"import { Plugin } from 'haraka-plugin-spf'; // Not typically used by end-users.","symbol":"Plugin","correct":"const Plugin = require('haraka-plugin-spf'); // Used internally by Haraka or by developers extending the plugin."}],"quickstart":{"code":"/* Haraka config/plugins file */\n# This is a comment\n# Your other plugins...\ndata.headers\nrules\nqueue/smtp_proxy\n\nspf  # Add this line to enable the SPF plugin\n\n\n/* Haraka config/spf.ini file */\n; Place this file in your Haraka config directory (e.g., /etc/haraka/config/spf.ini)\n\nlookup_timeout = 29\n\n[relay]\ncontext=sender\n\n[skip]\nrelaying=false\nauth=false\n\n[deny]\nmfrom_fail=true  ; Only deny explicit MAIL FROM SPF failures\nopenspf_text=true ; Add OpenSPF explanation text on deny\n\n[deny_relay]\n; Typically do not deny SPF for relayed mail, unless specific policies are needed.\nmfrom_fail=false\nopenspf_text=false\n\n\n// After configuring, restart Haraka:\n// sudo haraka -c /etc/haraka\n// (or whichever command you use to start Haraka)","lang":"javascript","description":"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."},"warnings":[{"fix":"Review your `spf.ini` against the latest documentation and default settings. Remove any outdated or non-standard directives.","message":"Legacy configuration support was removed in version 1.2.10. Users upgrading from very old versions might need to update their `spf.ini` files.","severity":"breaking","affected_versions":">=1.2.10"},{"fix":"No action is required, but be aware that automated parsers or logs relying on the exact previous header format might need adjustments.","message":"The 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.","severity":"breaking","affected_versions":">=1.2.11"},{"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.","message":"SPF 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Enabling SPF error deferrals (`defer.helo_temperror`, `defer.mfrom_temperror`) can cause excessive delays or bounced mail for senders with broken DNS configurations.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Broken 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"An issue where the plugin attempted to process DNS MX records that were either missing or malformed, leading to an undefined variable.","error":"TypeError: Cannot read properties of undefined (reading 'length') OR similar crash related to MX records."},{"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.","cause":"The `spf.ini` configuration file is either missing from Haraka's `config` directory or is incorrectly named.","error":"Haraka failed to load plugin: spf (Error: ENOENT: no such file or directory, open '.../haraka/config/spf.ini')"},{"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+.","cause":"Your `spf.ini` file contains deprecated or unsupported configuration directives, likely due to an upgrade from an older plugin version.","error":"Haraka plugin 'spf' returned an error during [hook name]: ReferenceError: someLegacyConfigVariable is not defined OR plugin behaves unexpectedly due to config."}],"ecosystem":"npm"}