Haraka 3.1.4 → 3.1.6

package/README.md

@@ -1,144 +1,119 @@
-## Haraka - a Node.js Mail Server
+# Haraka — a Node.js Mail Server
 
 ![Tests](https://github.com/haraka/Haraka/actions/workflows/ci.yml/badge.svg)
 [![Coverage Status][cov-img]][cov-url]
 
-Haraka is a highly scalable [node.js][1] email server with a modular
-plugin architecture. Haraka can serve thousands of concurrent connections
-and deliver thousands of messages per second. Haraka and plugins are written
-in asynchronous JS and are very fast.
+Haraka is a highly scalable [Node.js][1] SMTP server with a modular plugin architecture. It handles thousands of concurrent connections and delivers thousands of messages per second. Haraka and its plugins are written in asynchronous JavaScript, optimised for throughput and low latency.
 
-Haraka has very good spam protection (see [plugins][4]) and works
-well as a filtering [MTA][3]. It also works well as a [MSA][5] running on
-port 587 with auth and [dkim][6] plugins enabled.
+Haraka offers strong spam protection (see [Plugins.md][plugins]) and is widely deployed as a filtering [MTA][3] or as a [MSA][5] on port 465 (and legacy 587) with the auth and [DKIM][6] plugins enabled.
 
-Haraka makes no attempt to be a mail store (like Exchange or Postfix/Exim/Qmail),
-a [LDA][7], nor an IMAP server (like Dovecot or Courier). Haraka is
-typically used **with** such systems.
+Haraka is not a mail store, an [LDA][7], or an IMAP server. It is designed to work **alongside** those systems. A scalable outbound delivery engine is built in: mail flagged as `relaying` (for example, by an auth plugin) is queued for
+outbound delivery automatically.
 
-Haraka has a scalable outbound mail delivery engine built in. Mail
-marked as `relaying` (such as via an `auth` plugin) is automatically
-queued for outbound delivery.
+## Plugin Architecture
 
-### Getting Help
+Haraka's defining feature is its plugin system. Every SMTP transaction is a sequence of well-defined hooks — `connect`, `helo`, `mail`, `rcpt`, `data`, `data_post`, `queue`, and more — and each hook can be extended with a few lines of JavaScript. Plugins are asynchronous by default, so a slow lookup against DNS, Redis, or an HTTP API never blocks the server.
 
-- [Join the mailing list][8] (implemented as a Haraka plugin)
-- [GitHub Issues][15]
+The result is that behaviours which would require a custom MTA elsewhere are typically a small file in Haraka. For example, accepting qmail-style tagged addresses (`user-anything@domain.com`) and rewriting them to `user@domain.com` before forwarding to an Exchange or IMAP backend looks roughly like this:
 
-### Screencast
+```js
+exports.hook_rcpt = (next, connection, params) => {
+  const rcpt = params[0]
+  const [user] = rcpt.user.split('-')
+  rcpt.user = user
+  next()
+}
+```
 
-[Getting started with Haraka][2]
+A comprehensive registry of community and core plugins — auth, DNSBLs, DKIM, SpamAssassin, rspamd, Redis, ClamAV, queue backends, and many others — lives in [Plugins.md][plugins]. To write your own, see the [plugin tutorial][tutorial].
 
-### Why Use Haraka?
+## Documentation
 
-Haraka's plugin architecture provides an easily extensible MTA that
-complements traditional MTAs that excel at managing mail stores but do
-not have sufficient filtering.
+- [Plugins.md][plugins] — plugin registry and configuration reference
+- [docs/][docs] — core documentation (Connection, Transaction, Outbound, …)
+- [Tutorial][tutorial] — step-by-step getting started guide
+- [CHANGELOG.md][changelog] — release notes
+- [SECURITY.md][security] — security policy and reporting
 
-The plugin system makes it easy to code new features. A typical example
-is providing qmail-like extended addresses to an Exchange system,
-whereby you could receive mail as `user-anyword@domain.com`, and yet
-still have it correctly routed to `user@domain.com`. This is a few lines of
-code in Haraka.
+## Getting Help
 
-Plugins are provided for running mail through [SpamAssassin][9], validating
-[HELO][10] names, checking [DNS Blocklists][11], and [many others][12].
+- [GitHub Issues][issues]
+- [Mailing list][mailing-list] (implemented as a Haraka plugin)
+- [Screencast: Getting started with Haraka][screencast]
 
-### Installing Haraka
+## Installation
 
-Haraka requires [node.js][1] to run. Install Haraka with [npm][2]:
+Haraka requires [Node.js][1]. Install via [npm][npm]:
 
 ```sh
-# If the second command gives "nobody" errors, uncomment & run the next command
-# npm -g config set user root
 npm install -g Haraka
 ```
 
-After installation, use the `haraka` binary to set up the service.
-
-### Running Haraka
-
-First, create the service:
+Create a service directory:
 
 ```sh
 haraka -i /path/to/haraka_test
 ```
 
-That creates the directory `haraka_test` with `config` and `plugin`
-directories within. It also sets the host name used by Haraka
-to the output of `hostname`.
+This creates `haraka_test` with `config/` and `plugins/` subdirectories and sets the host name from `hostname(1)`. Edit `config/host_list` to add the domains for which Haraka should accept mail.
 
-If `hostname` is not correct, edit `config/host_list`. For example,
-to receive mail addressed to `user@domain.com`, add `domain.com` to the
-`config/host_list` file.
-
-Finally, start Haraka using root permissions:
+Start Haraka:
 
 ```sh
 haraka -c /path/to/haraka_test
 ```
 
-And it will run.
-
-### Configure Haraka
+## Configuration
 
-To choose which plugins run, edit `config/plugins`. Plugins control the
-overall behaviour of Haraka. By default, only messages to domains listed
-in `config/host_list` will be accepted and then delivered via the
-`smtp-forward` plugin. Configure the destination in `config/smtp_forward.ini`.
+Edit `config/plugins` to select active plugins. By default, mail addressed to domains in `config/host_list` is accepted and forwarded via the `smtp-forward` plugin (configured in `config/smtp_forward.ini`).
 
-### Read the Fine Manual
+Per-plugin documentation is available via:
 
 ```sh
-haraka -h plugins/$name
+haraka -h plugins/<name>
 ```
 
-The docs detail how each plugin is configured. After editing
-`config/plugins`, restart Haraka and enjoy!
-
-### Running from git
+See [Plugins.md][plugins] for the full registry.
 
-If you are unable to use npm to install Haraka, you can run from git by
-following these steps:
+## Running from Source
 
-First clone the repository:
-
-    $ git clone https://github.com/haraka/Haraka.git
-    $ cd Haraka
-
-Install Haraka's node.js dependencies locally:
-
-    $ npm install
-
-Edit `config/plugins` and `config/smtp.ini` to specify the plugins and
-config you want.
+```sh
+git clone https://github.com/haraka/Haraka.git
+cd Haraka
+npm install
+node haraka.js
+```
 
-Finally run Haraka:
+## Authorship and Maintenance
 
-    $ node haraka.js
+Haraka was created by [Matt Sergeant][matt-sergeant] (`baudehlo`), formerly project leader of [SpamAssassin][spamassassin] and a contributor to [Qpsmtpd][qpsmtpd]. The project is currently maintained by
+[Matt Simerson][msimerson] (`msimerson`).
 
-### License and Author
+Haraka is the work of many hands. See [CONTRIBUTORS.md][contributors] for the full list of people who have contributed code, documentation, and plugins.
 
-Haraka is MIT licensed - see the [LICENSE][16] file for details.
+## License
 
-Haraka is a project started by [Matt Sergeant][17], a 10 year veteran of the email and anti-spam world. Previous projects have been the project leader for
-SpamAssassin and a hacker on [Qpsmtpd][13].
+Haraka is released under the MIT License. See [LICENSE][license] for details.
 
-[1]: http://nodejs.org/
-[2]: http://youtu.be/6twKXMAsPsw
-[3]: http://en.wikipedia.org/wiki/Message_transfer_agent
-[4]: https://github.com/haraka/Haraka/blob/master/Plugins.md
-[5]: http://en.wikipedia.org/wiki/Mail_submission_agent
+[1]: https://nodejs.org/
+[3]: https://en.wikipedia.org/wiki/Message_transfer_agent
+[5]: https://en.wikipedia.org/wiki/Message_submission_agent
 [6]: https://github.com/haraka/haraka-plugin-dkim
 [7]: https://en.wikipedia.org/wiki/Mail_delivery_agent
-[8]: mailto:haraka-sub@harakamail.com
-[9]: https://haraka.github.io/plugins/spamassassin
-[10]: https://haraka.github.io/plugins/helo.checks
-[11]: https://haraka.github.io/plugins/dnsbl
-[12]: https://github.com/haraka/Haraka/blob/master/Plugins.md
-[13]: https://github.com/smtpd/qpsmtpd/
-[15]: https://github.com/haraka/Haraka/issues
-[16]: https://github.com/haraka/Haraka/blob/master/LICENSE
-[17]: https://github.com/baudehlo
+[npm]: https://www.npmjs.com/package/Haraka
+[plugins]: https://github.com/haraka/Haraka/blob/master/Plugins.md
+[docs]: https://github.com/haraka/Haraka/tree/master/docs
+[tutorial]: https://github.com/haraka/Haraka/blob/master/docs/Tutorial.md
+[changelog]: https://github.com/haraka/Haraka/blob/master/CHANGELOG.md
+[security]: https://github.com/haraka/Haraka/blob/master/SECURITY.md
+[contributors]: https://github.com/haraka/Haraka/blob/master/CONTRIBUTORS.md
+[license]: https://github.com/haraka/Haraka/blob/master/LICENSE
+[issues]: https://github.com/haraka/Haraka/issues
+[mailing-list]: mailto:haraka-sub@harakamail.com
+[screencast]: https://youtu.be/6twKXMAsPsw
+[matt-sergeant]: https://github.com/baudehlo
+[msimerson]: https://github.com/msimerson
+[spamassassin]: https://spamassassin.apache.org/
+[qpsmtpd]: https://github.com/smtpd/qpsmtpd/
 [cov-img]: https://codecov.io/github/haraka/Haraka/coverage.svg
 [cov-url]: https://codecov.io/github/haraka/Haraka?branch=master

package/SECURITY.md

@@ -0,0 +1,178 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are applied to the **current release** only. We encourage all users to run the latest version.
+
+| Version        | Supported |
+| -------------- | --------- |
+| 3.1.x (latest) | ✅        |
+| < 3.1          | ❌        |
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Use [GitHub Private Vulnerability Reporting](https://github.com/haraka/Haraka/security/advisories/new) to disclose security issues confidentially. This allows the maintainers to assess and patch the issue before public disclosure.
+
+Include as much of the following as possible:
+
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof-of-concept
+- Affected version(s)
+- Any suggested mitigations or patches
+
+## Response Process
+
+1. **Acknowledgement** — We aim to acknowledge reports within **72 hours**.
+2. **Assessment** — We will confirm the issue, determine severity, and identify affected versions.
+3. **Fix & Release** — A patch release will be prepared and coordinated with the reporter.
+4. **Disclosure** — A GitHub Security Advisory (and CVE if applicable) will be published after the fix is available.
+
+We follow [coordinated vulnerability disclosure](https://vuls.cert.org/confluence/display/CVD). Reporters are credited in the advisory unless they prefer otherwise.
+
+## Security Advisories
+
+Published advisories are listed at:
+**https://github.com/haraka/Haraka/security/advisories**
+
+## Threat Model
+
+Haraka is an SMTP server and plugin host. It accepts inbound network
+connections, parses SMTP commands and message content, and can deliver mail
+outbound when an operator enables relaying or outbound.
+
+This threat model assumes the operator controls the host, configuration,
+enabled plugins, credentials, TLS material, and any external services Haraka
+is configured to use.
+
+### Data flow
+
+```mermaid
+flowchart LR
+    client["SMTP client<br/>(untrusted)"]
+    dns["DNS resolver<br/>(untrusted)"]
+    peer["Outbound peer<br/>(untrusted)"]
+    operator(["Operator<br/>(trusted)"])
+    subgraph haraka["Haraka process — trust boundary"]
+        listener["Listener / TLS / Parser"] --> plugins["Plugin pipeline"]
+        plugins --> queue[("Queue · FS")]
+        queue --> delivery["Delivery"]
+        stores[("Config · TLS keys · Logs")]
+    end
+    client <--> listener
+    plugins <--> dns
+    delivery --> peer
+    operator -.-> stores
+    operator -.-> plugins
+```
+
+The trust boundary is the Haraka process. External peers (SMTP clients, DNS
+resolvers, outbound peers) are untrusted; data crossing the boundary inbound
+must be validated before it affects delivery, state, or process behavior.
+Inside the boundary, plugins, the queue, configuration, TLS material, and
+logs share the Haraka process privilege and are the operator's
+responsibility — they are not a security boundary against each other.
+
+### Assets
+
+The assets Haraka aims to protect:
+
+- **Message content** in transit and queued on disk
+- **AUTH credentials** received via SMTP AUTH, and any upstream credentials
+  Haraka holds for outbound or backend services
+- **TLS private keys** and certificates used by the listener and for
+  outbound delivery
+- **Queue integrity** — no injection, alteration, or deletion of queued
+  messages from outside the trust boundary
+- **Availability** of the SMTP service to legitimate clients
+- **Sender reputation** of the operator's deployment — Haraka must not be
+  abusable as an open relay or spam amplifier under documented
+  configuration
+
+### Entry points and actors
+
+Untrusted data enters Haraka through:
+
+- **SMTP listeners** on the operator-configured ports (typically 25, 465,
+  587, and any additional listeners enabled by plugins or configuration)
+- **PROXY protocol or XCLIENT metadata** when the operator has enabled
+  trusted-relay forwarding
+- **DNS responses** to lookups performed by Haraka core or plugins
+  (rDNS, SPF, DKIM, MX, DNSBL, etc.)
+- **Outbound SMTP responses** received from peers during delivery
+
+Haraka distinguishes these actors:
+
+- **Anonymous SMTP client** — connecting from the network without
+  authentication; trusted only to issue SMTP commands subject to policy
+- **Authenticated submission user** — passed SMTP AUTH; trusted with the
+  envelope and policy the operator's auth backend permits, nothing more
+- **Trusted relay peer** — a network source the operator has configured to
+  bypass certain checks (e.g. permitted to relay, or whose PROXY/XCLIENT
+  metadata is honored)
+- **Operator** — controls the host, configuration, and installed plugins;
+  fully trusted
+- **Plugin code** — runs inside the trust boundary with full process
+  privilege; treated as trusted-as-installed, and not a security boundary
+
+### Haraka does not trust
+
+- SMTP clients and other remote peers, including commands, envelopes, headers,
+  bodies, attachments, authentication attempts, HELO/EHLO names, and proxied
+  client metadata before validation
+- Data returned by remote services Haraka communicates with, such as DNS
+  lookups and outbound SMTP peers
+- Untrusted remote input must not be able to trigger behavior beyond
+  documented SMTP and plugin semantics, such as unauthorized relaying,
+  unintended command execution, protected-data disclosure, or service
+  unavailability
+
+### Haraka trusts
+
+- The operating system, filesystem, Node.js runtime, local network, process
+  privileges, and local administrators operating the service
+- Haraka configuration and deployment choices, including listener exposure,
+  relay and authentication policy, TLS certificates, proxy settings, and
+  enabled plugins
+- Code loaded as plugins or dependencies. Plugins run with Haraka's process
+  privileges and are not a security boundary
+- Upstream services and dependencies as separate projects; flaws in those
+  components are usually reported upstream unless Haraka's integration creates
+  a distinct vulnerability
+
+### STRIDE summary
+
+In-scope threats are classified using [STRIDE][stride] applied at the
+Haraka trust boundary shown above. A finding that lets a remote peer
+cause any of the following under documented or default-safe configuration
+is generally a vulnerability.
+
+| Category                   | Example threats at the Haraka boundary                                                                                 |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **S**poofing               | Forged HELO/EHLO or AUTH, identity bypass, unvalidated XCLIENT or proxy metadata accepted as authoritative             |
+| **T**ampering              | SMTP smuggling, CRLF or header injection, parser inconsistencies that change how a message is delivered or interpreted |
+| **R**epudiation            | Remote input that erases or forges the Received: trail, or otherwise defeats logging under default configuration       |
+| **I**nformation disclosure | Leakage of message content, credentials, or internal state through SMTP responses, DSNs, error messages, or logs       |
+| **D**enial of service      | Deterministic resource exhaustion or crashes triggered by remote input without operator misconfiguration               |
+| **E**levation of privilege | Remote code execution, or escape of documented SMTP/plugin semantics into arbitrary behavior inside the Haraka process |
+
+Plugins execute inside the trust boundary by design, so a malicious or
+vulnerable plugin can produce any STRIDE category above. Findings that
+require installing such a plugin are not vulnerabilities in Haraka itself.
+
+[stride]: https://en.wikipedia.org/wiki/STRIDE_model
+
+## Scope
+
+Issues that require control of a trusted element are out of scope, including:
+
+- Vulnerabilities requiring control of the host OS, filesystem, Node.js
+  runtime, local administrator account, or other trusted infrastructure
+- Malicious or compromised plugins or dependencies intentionally installed or
+  enabled by the operator
+- Pure misconfiguration of listeners, relay policy, TLS, proxying, or
+  outbound destinations unless Haraka's documented defaults create the
+  insecure state
+
+Issues in third-party plugins maintained outside this repository should be reported to their respective maintainers.

package/bin/haraka

@@ -11,7 +11,6 @@ const os = require('node:os')
 
 const nopt = require('nopt')
 const utils = require('haraka-utils')
-const sprintf = require('sprintf-js').sprintf
 const base = path.join(__dirname, '..')
 const ver = utils.getVersion(base)
 const knownOpts = {
@@ -313,15 +312,7 @@ if (parsed.version) {
   ;(async () => {
     const qlist = await outbound.list_queue()
     for (const todo of qlist) {
-      console.log(
-        sprintf(
-          'Q: %s rcpt:%d from:%s domain:%s',
-          todo.file,
-          todo.rcpt_to.length,
-          todo.mail_from.toString(),
-          todo.domain,
-        ),
-      )
+      console.log(`Q: ${todo.file} rcpt:${todo.rcpt_to.length} from:${todo.mail_from} domain:${todo.domain}`)
     }
     process.exit()
   })()
@@ -379,12 +370,14 @@ if (parsed.version) {
   console.log('')
   for (const hook of getHooks()) {
     if (!plugins.registered_hooks[hook]) continue
-    console.log(sprintf("%'--80s", `Hook: ${hook} `))
-    console.log(sprintf('%-35s %-35s %-4s %-3s', 'Plugin', 'Method', 'Prio', 'T/O'))
-    console.log(sprintf("%'-80s", ''))
+    console.log(`Hook: ${hook} `.padEnd(80, '-'))
+    console.log(`${'Plugin'.padEnd(35)} ${'Method'.padEnd(35)} ${'Prio'.padEnd(4)} T/O`)
+    console.log('-'.repeat(80))
     for (let p = 0; p < plugins.registered_hooks[hook].length; p++) {
       const item = plugins.registered_hooks[hook][p]
-      console.log(sprintf('%-35s %-35s %4d %3d', item.plugin, item.method, item.priority, item.timeout))
+      console.log(
+        `${item.plugin.padEnd(35)} ${item.method.padEnd(35)} ${String(item.priority).padStart(4)} ${String(item.timeout).padStart(3)}`,
+      )
     }
     console.log('')
   }

package/config/plugins

@@ -12,7 +12,6 @@
 # status
 # process_title
 # syslog
-# watch
 
 # CONNECT
 # ----------
@@ -20,7 +19,6 @@
 # karma
 # relay
 # access
-# p0f
 # geoip
 # asn
 # fcrdns
@@ -49,7 +47,6 @@ mail_from.is_resolvable
 # At least one rcpt_to plugin is REQUIRED for inbound email.
 rcpt_to.in_host_list
 # qmail-deliverable
-# rcpt_to.routes
 
 # DATA
 # ----------

package/docs/Connection.md

@@ -1,66 +1,153 @@
 # Connection Object
 
-For each connection to Haraka there is one connection object.
+For each connection to Haraka there is one connection object. It is the first argument passed to almost every plugin hook and is the primary context object plugins use to inspect and act on the SMTP session.
 
-## API
+## Properties
 
-- connection.uuid
+### connection.uuid
 
-A unique UUID for this connection.
+A unique UUID for this connection. Used as the connection identifier in logs and inherited by `transaction.uuid`.
 
-- connection.remote - info about the host that is connecting to Haraka.
+### connection.remote
 
-  - ip - remote IP address
-  - host - reverse DNS of the remote hosts IP
-  - is_private - true if the remote IP is from a private (loopback, RFC 1918, link local, etc.) IP address.
-  - is_local - true if the remote IP is localhost (loopback, link local)
+Information about the host connecting to Haraka.
 
-- connection.local - info about the host that is running Haraka
+- `ip` — remote IP address
+- `port` — remote TCP port
+- `host` — reverse DNS of the remote IP (populated by the `connect.rdns_access` / `connect` hooks)
+- `info` — free-form descriptor (e.g. populated by FCrDNS)
+- `closed` — `true` once the remote end has dropped the connection
+- `is_private` — `true` if the remote IP is in a private range (RFC 1918, loopback, link-local, etc.)
+- `is_local` — `true` if the remote IP is localhost / loopback
 
-  - ip - the IP of the Haraka server, as reported by the OS
-  - port - the port number handling the connection.
-  - host - the rDNS host name of the local IP
+### connection.local
 
-- connection.proxy - proxy properties set when a proxy is used (like haproxy)
+Information about the Haraka server endpoint handling this connection.
 
-  - allowed - if the remote IP has proxy permission
-  - ip - when proxied, the proxy servers IP address
-  - type - currently null or 'haproxy'
+- `ip` — the IP of the Haraka server, as reported by the OS
+- `port` — the port number handling the connection
+- `host` — the primary host name of the Haraka server
+- `info` — `Haraka` (with `/<version>` appended when `headers.show_version` is enabled in `connection.ini`)
 
-- connection.hello
+### connection.hello
 
-  - verb - Either 'EHLO' or 'HELO' whichever the remote end used
-  - host - The hostname given with HELO or EHLO
+The greeting given by the client.
 
-- connection.notes
+- `verb` — `EHLO` or `HELO`, whichever the client used
+- `host` — the hostname argument
 
-An object which persists during the lifetime of the connection. It is used to store connection-specific properties. See also, connection.results and [haraka-notes](https://github.com/haraka/haraka-notes).
+### connection.tls
 
-- connection.transaction
+State of the TLS layer on this connection.
 
-The current transaction object, valid after MAIL FROM, and destroyed at queue
-time, RSET time, or if MAIL FROM was rejected. See the Transaction Object
-documentation file.
+- `enabled` — `true` once STARTTLS has been negotiated (or the listener is `smtps`)
+- `advertised` — `true` if Haraka advertised STARTTLS in the EHLO response
+- `verified` — `true` if the peer certificate validated against the configured CAs
+- `cipher` — the negotiated cipher object (`name`, `version`, …)
+- `verifyError` — the verification error, if any
+- `peerCertificate` — the parsed peer certificate (when client certs are used)
 
-- connection.relaying
+### connection.proxy
 
-A boolean flag to say whether this connection is allowed to relay mails (i.e.
-deliver mails outbound). This is normally set by SMTP AUTH, or sometimes via
-an IP address check.
+Proxy-protocol state, set when the connection arrived via HAProxy (see [HAProxy.md](HAProxy.md)).
 
-- connection.current_line
+- `allowed` — `true` if the remote IP is in the `haproxy.hosts` allow-list
+- `ip` — the proxy server's IP (the real client IP appears in `connection.remote.ip` once PROXY is parsed)
+- `type` — currently `null` or `'haproxy'`
 
-For low level use. Contains the current line sent from the remote end,
-verbatim as it was sent. Can be useful in certain botnet detection techniques.
+### connection.notes
 
-- connection.last_response
+A plain object that persists for the lifetime of the connection. Use it to share state between plugin hooks. For structured per-test results prefer `connection.results`. See also [haraka-notes](https://github.com/haraka/haraka-notes).
 
-Contains the last SMTP response sent to the client.
+### connection.results
 
-- connection.remote_closed
+Structured store for plugin results. See [haraka-results](https://github.com/haraka/haraka-results).
 
-For low level use. This value is set when the remote host drops the connection.
+### connection.transaction
 
-- connection.results
+The current `Transaction` object. Valid between `MAIL FROM` and the end of `queue` / `RSET` (or until `MAIL FROM` is rejected). See [Transaction.md](Transaction.md).
 
-Store results of processing in a structured format. See [haraka-results](https://github.com/haraka/haraka-results)
+### connection.relaying
+
+Boolean. `true` if this connection is allowed to relay (i.e. deliver mail outbound). Normally set by an auth plugin or an IP allow-list. Reading or writing this property transparently routes through the current transaction when one exists, so the flag survives across multiple messages in a single connection only when set on the connection.
+
+### connection.capabilities
+
+Array of ESMTP capabilities advertised in the EHLO response (e.g. `['PIPELINING', '8BITMIME', 'SIZE 0', 'STARTTLS', 'AUTH PLAIN LOGIN']`). Plugins may push additional capability strings during the `capabilities` hook.
+
+### connection.esmtp
+
+`true` if the client used `EHLO` (as opposed to `HELO`).
+
+### connection.pipelining
+
+`true` once Haraka has advertised, and the client has used, SMTP pipelining.
+
+### connection.early_talker
+
+`true` if the client sent data before Haraka issued its banner — a
+common spam-bot signal.
+
+### connection.tran_count
+
+Number of transactions completed on this connection.
+
+### connection.rcpt_count / connection.msg_count
+
+Per-disposition counters (`accept`, `tempfail`, `reject`) tracking
+recipients and full messages on this connection.
+
+### connection.start_time
+
+Connection start time, in epoch milliseconds (`Date.now()`).
+
+### connection.last_response
+
+The last SMTP response line Haraka sent to the client.
+
+### connection.last_reject
+
+The text of the last rejection issued to this client (used by
+`max_unrecognized_commands` and similar throttling plugins).
+
+### connection.errors
+
+Count of protocol errors on this connection.
+
+### connection.current_line
+
+Low-level. The current line as sent by the remote end, verbatim. Useful
+for botnet fingerprinting.
+
+### connection.state
+
+The connection's protocol state — one of the values in `haraka-constants`'s `connection.state` table (`PAUSE`, `CMD`, `LOOP`, `DATA`, `DISCONNECTING`, `DISCONNECTED`).
+
+## Methods
+
+### connection.respond(code, msg, cb)
+
+Send an SMTP response to the client. `code` is the numeric SMTP code, `msg` is the human-readable text (a string or an array of strings for a multi-line response). The callback fires when the response has been written.
+
+### connection.disconnect()
+
+Close the connection after running the `disconnect` hook.
+
+### connection.reset_transaction(cb)
+
+Tear down the current transaction (equivalent to `RSET`) and invoke `cb` when complete.
+
+### connection.set(path, value)
+
+Assign a nested property safely, e.g. `connection.set('remote.host', 'mx.example.com')`. Setting `remote.ip`
+automatically recomputes `remote.is_private` / `remote.is_local`.
+
+### connection.get(path)
+
+Read a nested property, returning `undefined` if any segment is missing.
+
+### connection.loginfo / lognotice / logwarn / logerror / logdebug / logcrit / logalert / logemerg / logprotocol / logdata
+
+Log at the named level. Each takes either `(msg)` or `(plugin, msg, data)`.
+
+See [Logging.md](Logging.md).