Skip to content

✨ Hub: send the confirmation reply for mail sent to a hive with DKIM, behind the signing key (off by default) - #19101

Merged
kubestellar-prow[bot] merged 9 commits into
v5from
feat/mail-reply-real-sender-18746
Nov 19, 2026
Merged

kubestellar-prow[bot] merged 9 commits into
v5from
feat/mail-reply-real-sender-18746

Conversation

@clubanderson

@clubanderson clubanderson commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Refs #18746

This is the sender behind the reply decision, ledger and templates that merged earlier. The issue stays open: the foundation DNS records, the outbound TCP 25 and reverse DNS check on the hosted hub, the key pair and the two-provider dmarc=pass test are owner actions, and nothing here turns replies on.

What it does

The real mailReplySender (src/pkg/hub/mail_reply_smtp.go), installed as the default mailReplySenderFactory:

  • Plain-text, 7-bit message with the existing headers, null envelope sender (MAIL FROM:<>).
  • DKIM-signed with the mounted key as the From domain. Library: github.com/emersion/go-msgauth (MIT), already a direct dependency. SMTP is the standard library client (net/smtp, which can set the HELO name before STARTTLS; the go-smtp client cannot). One module moves from indirect to direct for the optional relay (see Relay): github.com/emersion/go-sasl, already in the module graph, no new module. Keys: PKCS#8 or PKCS#1 PEM, RSA of at least 2048 bits or Ed25519.
  • MX lookup, then only the best-preference host: one connection, one message, STARTTLS required with a verified certificate, public IPv4 preferred, private, loopback, link-local and shared ranges refused (the sender's domain is attacker-chosen). No second MX, no retry, no redirects. This is the default path; the optional relay below replaces the MX lookup only when configured.
  • Timeouts: 10 s per DNS lookup, 15 s connect, 45 s for the SMTP conversation, within the existing 90 s per reply.
  • Any failure is final (the ledger keeps the claim). The ledger limits are applied before the sender is called, as before. A key that cannot be loaded sends nothing and claims nothing.
  • Header and address injection (CR, LF, NUL or other control characters, display names, non-ASCII addresses, a Message-ID that is not a plain token, a non-7-bit body, a From other than the configured one) is refused before any DNS lookup or connection. A subject with non-ASCII letters is sent as an RFC 2047 encoded word.
  • Logs: delivery id, hive id, a reason class and, when the server refused, its numeric code. Never the key, an address, a domain, a subject, a body or a server's text.

Gate

Default off. Replies need the key file (existing), HIVE_HUB_MAIL_REPLY_FROM and HIVE_HUB_MAIL_REPLY_DKIM_SELECTOR (existing), and the new HIVE_HUB_MAIL_REPLY_HELO (the fully qualified name carrying the SPF record and the reverse DNS; no default). With any of them missing the hub builds no sender and opens no connection; removing the key file stops replies at once.

Tests (mail_reply_smtp_test.go)

Fake DNS and a fake SMTP server (go-smtp server, STARTTLS with a throwaway certificate) on the loopback interface, no network. Test keys are made in memory.

  • Valid DKIM signature verifies against the published test key (RSA and Ed25519); a modified body does not; null envelope sender, STARTTLS, port 25, headers, plain text only.
  • MX lookup failure, lookup timeout, no MX, null MX, bad MX name, MX host with no address, MX host in private ranges.
  • Only the best MX is used; a failed connection is final.
  • Session timeout and context cancellation.
  • Rejected recipient and rejected sender (final, code only, no data sent), no STARTTLS, untrusted certificate.
  • Limit exceeded: the server sees no connection; duplicate Message-ID.
  • Key missing, empty, directory, garbage, public key, weak RSA, wrong type, too large: no send, no connection; an unusable key claims nothing.
  • CRLF and header injection in subject, address, reply-to, Message-ID and body; a hostile title neutralized by the template.
  • Gate off: nothing built, nothing dialed.

Relay (optional smarthost)

Added so replies can leave from one fixed sending IP with reverse DNS, which receiving servers use for reputation. It is off unless HIVE_HUB_MAIL_REPLY_RELAY is set; with it unset, behavior is exactly the MX path above.

  • HIVE_HUB_MAIL_REPLY_RELAY: host or host:port (default port 587, named constant mailReplyRelayDefaultPort). Environment only; the reply sender has no yaml surface, and the docs say so.
  • HIVE_HUB_MAIL_REPLY_RELAY_AUTH_FILE: path to a file with the user name on line 1 and the password on line 2 (at most 1 KiB). AUTH PLAIN is sent only after STARTTLS. Credentials are read from the file, never inline, and never logged.
  • Fails closed: STARTTLS is required with a verified certificate and there is no fallback to direct delivery. An invalid relay value, or an auth file set without a relay, builds no sender. Unreadable credentials send nothing and do not use up the ledger claim, the same as an unusable DKIM key.
  • Unchanged: the hub still DKIM-signs before the hand-off, the envelope sender stays MAIL FROM:<>, and the header and address injection checks, ledger limits and timeouts above all apply. A relay may have a private address because the operator chooses it, unlike the attacker-chosen MX hosts.
  • New log reason classes: relay_address_lookup, relay_auth_unavailable, relay_auth, relay_credentials_unusable. Still no address, credential or server text.
  • Tests: mail_reply_relay_test.go covers relay unset (unchanged), relay set routes to the relay, STARTTLS refused fails closed, an untrusted certificate, AUTH from the file, a bad credentials file, and no secret in logs or errors.
  • src/go.mod: github.com/emersion/go-sasl moves from indirect to direct because the test imports it.

Docs

src/docs/meetings.md (new "How a reply is sent", including the relay), src/docs/env-vars.md (both relay variables), src/docs/inbox-voice-sources.md, changelog fragment.

Not run locally by design (CI is the gate).

… behind the signing key (off by default)

Adds the real sender behind the existing mailReplySender interface: one
plain-text message, DKIM-signed with the mounted key (RSA >= 2048 bits or
Ed25519, via the go-msgauth module the repo already uses), null envelope
sender, one connection to the best-preference MX host with required
STARTTLS, bounded timeouts, no retry. Any failure is final. A key that
cannot be loaded sends nothing and claims nothing. Header and address
injection is refused before any connection, an MX host in a private range
is refused, and logs hold ids, a reason class and a numeric code only.

Off unless the key file, From, selector and the new
HIVE_HUB_MAIL_REPLY_HELO are all set.

Tests use a fake DNS and a fake SMTP server on the loopback interface.

Refs #18746

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19202 ✨ ask: hub panel for optional Ask AI help same files src/docs/env-vars.md
#19200 ✨ ask: hub backend for optional Ask AI help same files src/docs/env-vars.md
#19199 ✨ ask: hub backend for optional Ask AI help (phase 1) same files src/docs/env-vars.md

@hivecommons-hive

hivecommons-hive Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

  • build-and-test

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

ℹ️ Sentinel: informational, author is trusted (owner), merge is not blocked. Head 38646c774b24 matched:

  • sensitive_path: changes 1 sensitive path(s) (src/go.mod)

No sentinel-alert label was added. The finding is recorded in the dashboard Security tab and /api/sentinel; set sentinel.trusted_authors_block: true to block trusted authors too.

Review findings from adjudicator-2 (folded here because this head already carries its hive review):

Security review at head 38646c7: no exploitable issue found, approving with one advisory.

Advisory: the PR body does not mention the smarthost relay and SMTP AUTH credentials file (HIVE_HUB_MAIL_REPLY_RELAY, HIVE_HUB_MAIL_REPLY_RELAY_AUTH_FILE, src/pkg/hub/mail_reply_smtp.go). In relay mode the public-IP filter is skipped by design, because the relay is operator-chosen. STARTTLS and certificate verification are still required, AUTH is sent only after STARTTLS, and there is no direct-delivery fallback. Please add this to the PR description. Optionally, have loadMailReplyRelayAuth reject a group- or world-readable credentials file.

Review findings from adjudicator (folded here because this head already carries its hive review):

Correctness review at 38646c7: no in-scope blocker found. The gate, the order of compose, DNS and dial, the STARTTLS requirement, the null envelope sender, the session deadline and the Ready()-before-claim check (mail_reply.go handle) all behave as the PR describes.

One advisory: the PR body says "No new dependency, go.mod is unchanged", but src/go.mod promotes go-sasl to a direct dependency. The body also omits the relay/SMTP AUTH path (deliverViaRelay, mail_reply_relay_test.go), which only the changelog fragment describes. Please update the body.

I did not read the test files in full.

Findings not on a changed line

  • src/go.mod:15: Body says go.mod is unchanged, but go-sasl is promoted to a direct dependency here (used for the relay AUTH path). Please correct the PR body and mention the relay feature.

stage 080-awaiting-merge-admission → 071-needs-author: required-check-failing:build-and-test

…ests

go-smtp makes a second session once STARTTLS has run, so the fake MX
counted two per connection. Count only the plain-text one.

Refs #18746

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
HIVE_HUB_MAIL_REPLY_RELAY sends the DKIM-signed reply through a fixed-IP relay instead of direct MX delivery; unset keeps today's behavior. STARTTLS stays required with no fallback, the envelope sender stays null, and optional SMTP AUTH reads its credentials from a file named by HIVE_HUB_MAIL_REPLY_RELAY_AUTH_FILE and never logs them.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
)

Signed-off-by: Andy Anderson <andy@clubanderson.com>

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intent alignment (contract: PR title + diff; body refs #18746, which I read: "Design: confirmation reply email for mail sent to a hive"). The core sender, gate (key + From + selector + new HELO) and off-by-default behavior match the title. Two gaps between body and diff:

  1. Undeclared smarthost relay feature. The diff adds HIVE_HUB_MAIL_REPLY_RELAY and HIVE_HUB_MAIL_REPLY_RELAY_AUTH_FILE (mail_reply.go mailReplyConfig Relay/RelayAuthFile; mail_reply_smtp.go const envMailReplyRelay; the whole 495-line mail_reply_relay_test.go; docs in env-vars.md/meetings.md/changelog). This is a second delivery path (route to a fixed host on port 587, SMTP AUTH PLAIN credentials read from a file). The PR body never mentions it, and it contradicts the body's "MX lookup, then only the best-preference host ... No second MX" and its test list. Credential handling and a new outbound path are not part of "send the confirmation reply with DKIM behind the signing key".
  2. go.mod is not unchanged. Body says "No new dependency, go.mod is unchanged", but the diff moves github.com/emersion/go-sasl from indirect to direct (needed for the relay's AUTH).

Requested change (pick the cheaper): either (a) remove the relay (Relay/RelayAuthFile fields, env consts, relay test file, relay doc paragraphs, changelog sentence, go.mod hunk) and land it in a follow-up PR, or (b) keep it and update the PR body to describe the relay, its AUTH file handling, the go-sasl promotion and its tests, so the reviewed intent matches the diff. Not blocking on behavior: relay is off unless the env var is set.

Limit of this review: intent-alignment only; I did not audit the SMTP/DKIM code paths for correctness.

-- hive: agent=reviewer backend=claude model=claude-sonnet-5-5 claude=2.1.327

@clubanderson

Copy link
Copy Markdown
Member Author

PR body updated to describe the optional smarthost relay (env vars, AUTH file handling, fail-closed behavior, the go-sasl indirect to direct move and its tests), which resolves the intent-alignment gap from the review. Kept the relay in this PR by choice; it is off unless the env var is set.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Baseline triage: build-and-test / build-go fail on this PR only, and the branch is 8 commits behind v5. Suggested fix: merge v5 into the branch (signed off) and re-check; if still red, the job log is the next step. Not pushed, as this is not a hive-authored branch.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Scanner triage: failing checks here are not caused by this diff. Baseline check says MERGE_BASE: the branch is 14 commits behind v5 (sibling PRs are equally stale). Suggested fix: merge v5 into the branch with sign-off (git merge -s ort --signoff origin/v5) and push, then re-check. Not pushed from here because the branch is not hive-authored.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Scanner triage: build-go and build-and-test fail and the branch is 18 commits behind v5, where build-and-test is green. The failure looks stale-branch, not diff-caused. Suggested fix: merge v5 into the branch (signed off, git merge -s ... --signoff or the update-branch button) and re-check. Not pushed from here because this is a human-authored branch.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Scanner triage: the failing checks here (native-queue-policy, Sign-off survives the squash) are not on the default branch; the branch is behind v5 and the checks are stale. Suggested fix: merge the base branch into this branch (signed off) and let CI re-run. This is a human-authored branch, so I am not pushing.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Scanner triage: baseline check says this branch is behind its base by 22 commits and the failing checks (build-go, build-and-test) are not shared with the base branch. Suggested fix: merge the base branch into this branch (signed off, git merge -s ort origin/<base> && git commit -s if needed) and re-run CI before diagnosing further. I am not pushing to this branch because it is not hive-authored.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

Signed-off-by: Andy Anderson <andy@clubanderson.com>

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision needed: @clubanderson should decide whether the optional smarthost relay (HIVE_HUB_MAIL_REPLY_RELAY, with AUTH credentials read from a file) lands with the direct-MX sender, given #18746 frames a third-party relay as a separate option C and this PR adds outbound mail plus a credentials path?

I read mail_reply_smtp.go and the gate in mail_reply.go at the PR head and found no defect. This is routed to a person only because it adds outbound mail and a credentials path, which is a trust and external-side-effect surface.

What I checked and found sound:

  • Gate: newMailReplierFromEnv only builds a sender when the key file, From, selector and HELO are all set, and handle calls Ready() before ledger.reserve, so an unusable key or credentials file claims nothing.
  • Direct path: the MX address goes through mailReplyPublicIP and pickMailAddr before any dial, so an attacker-chosen domain cannot point the hub at its own network. STARTTLS is required with a verified certificate, and the envelope sender is null.
  • Relay path: AUTH is attempted only after StartTLS in converse, and there is no plain-text or direct fallback when the relay lacks STARTTLS.
  • Headers and addresses are validated before any connection, and failures log a reason class and numeric code only.

The relay deliberately skips the public-address check (deliverViaRelay), which is reasonable for an operator-chosen host. The open question is scope: per #18746 the relay is the "option C" fallback if port 25 is blocked, not part of option A, and the PR body does not say the owner has chosen it.

Not a defect: the PR is default-off and the body says DNS, TCP 25, reverse DNS and the dmarc=pass test remain owner actions, which matches the issue's step list.

-- hive: agent=reviewer backend=claude model=claude-sonnet-5-5 claude=2.1.327

@clubanderson clubanderson added lgtm Indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Nov 19, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow
kubestellar-prow Bot merged commit 1883dff into v5 Nov 19, 2026
105 of 107 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/mail-reply-real-sender-18746 branch November 19, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant