Skip to content

📖 Design: confirmation reply email for mail sent to a hive (authenticated senders only) #18746

Closed

Description

@clubanderson

Part of #18744. That issue ships what needs no new infrastructure: SMTP refusals that say how to try again with a help link, and "How to try again" / "Report a problem" / Approve / Decline next to each mail in the Inbox's Recent mail list. This issue is the part that is not built: a reply email from the hive to the sender.

Why it is not built

Hive has no way to send mail today. Checked on v5:

  • No code sends mail: nothing under src/ imports net/smtp for sending, calls smtp.SendMail, or talks to a mail provider (SES, Postmark, Mailgun, SendGrid, Resend). The only SMTP client code is in the receiver's tests.
  • The receiver (src/pkg/mailin, hive-mx) is receive-only by design: no AUTH, no relay, "it never sends mail" in its package doc, in src/cmd/hive-mx/main.go, in src/Dockerfile.mx and in src/docs/meetings.md.
  • The calendar-invite flow sends nothing back: src/pkg/mailin/ical.go reads REQUEST and CANCEL and ignores REPLY; no iTIP REPLY is ever generated. Address proof works by the user sending a code to the hive for the same reason ("Hive never sends mail, so this is how it learns which addresses are yours").
  • No sending domain is set up. The project's organizational domain publishes a DMARC policy of p=reject; sp=reject with strict alignment (adkim=s; aspf=s), and hive hosts have a wildcard MX only: no SPF record and no DKIM key. Mail sent today as hive@<hive host> would fail DMARC and be rejected or junked by every large provider.

So there is nothing that works with no DNS change. Standing up a sender and requesting DNS records is a decision for the maintainers and the foundation's IT, not something to slip into a feature PR.

Safety rules (not negotiable, whichever option is chosen)

  1. Reply only to an authenticated sender. A reply goes only to a From address whose message passed DMARC alignment (wire.Auth.Aligned). Everything else gets what it gets today: the SMTP refusal at receive time, which the sender's own provider turns into a bounce. A reply to a forged From is backscatter and gets the domain blocklisted.
  2. Never reply to automatic or bulk mail. No reply when the message has Auto-Submitted other than no, Precedence: bulk|list|junk, List-Id / List-Unsubscribe, X-Auto-Response-Suppress, a null return path (MAIL FROM:<>), a sender local part of mailer-daemon, postmaster, no-reply / noreply, or when the sender is any hive address (hive@<known host>), including our own.
  3. Mark what we send. Auto-Submitted: auto-replied, X-Auto-Response-Suppress: All, Precedence: auto_reply, In-Reply-To and References set to the original Message-ID, a null envelope sender (MAIL FROM:<>) so a failed reply never bounces back into a hive.
  4. Rate limits. Per sender address (for example 10 replies an hour, 30 a day), per sender domain, and per hive (for example 200 a day). Past a limit the reply is dropped silently and counted in a metric; the mail itself is unaffected.
  5. At most one reply per Message-ID per hive, remembered for at least 7 days. A message without a Message-ID gets no reply.
  6. No content. The reply quotes the original subject line (truncated, as the reply's own subject) and nothing else: no body, no attachments, no file names.
  7. Privacy. The reply states the outcome and no more. Because only authenticated senders are replied to, nobody learns from a reply (or from its absence) whether some other address is a user of a hive. The "held" wording does not say why the sender is not trusted.
  8. Reply-to-try-again must work. Reply-To is the hive's own address (hive@<hive host>), so a reply with the corrected attachment is a new delivery through the normal receive path, with the normal checks. Rule 2 keeps that from looping.
  9. On by default, no new setting, unless an operator-level switch turns out to be required for self-hosted hubs (a hub without a signing key simply does not send).

Which mails get a reply

Outcome Today With this design
Received nothing reply to aligned senders: "received", link to the item in the hive Inbox (sign-in required)
Held for approval (aligned, not on the allowlist) nothing reply: "received, waiting for the hive owner's approval"
Held for approval (not aligned) nothing no reply (rule 1); visible in the Inbox only
Refused SMTP 5xx, bounced by the sender's provider, with the fix and help link (#18744) unchanged in the first step. The bounce is already the failure notice; a second mail would duplicate it. A later step may, for aligned senders only, send a friendlier refusal reply

Options for the sender

A. Hub-side sender with DKIM (recommended)

The hub already sees each delivery (src/pkg/hub/mail_relay.go), the receiver's authentication result, and the spoke's answer (items, awaiting_approval), so it knows the outcome. It composes the reply, signs it with a DKIM key from a mounted Secret, and hands it to a small outbound queue that delivers by direct MX lookup with STARTTLS.

  • Needs: the receiver to pass the loop-relevant facts in wire.Delivery (auto-submitted, precedence, list headers, null return path, sender local part), since the hub never sees headers. A signing key held by the hub. Outbound TCP 25 from the hub's network (many clouds block it by default: verify before anything else) and reverse DNS for the sending IP.
  • Good: one place holds the key, the rate limits and the reply ledger; spokes hold nothing and need no new egress.
  • Cost: we own IP reputation and a retry queue.

B. Receiver-side sender

hive-mx sends the reply itself after the hub answers.

  • Good: it has the headers and already has port 25 exposure and a mail identity (its HELO name).
  • Bad: it stops being receive-only, which is its main security property today; it would hold a signing key on the most exposed component; it does not see the spoke's outcome unless the hub's answer is extended.

C. Transactional mail provider

The hub calls a provider's HTTPS API (Amazon SES, Postmark, Resend or similar).

  • Good: no outbound port 25, the provider's IP reputation, bounce and complaint handling for free.
  • Bad: a third party sees recipient addresses and subject lines; an account, an API key in a Secret, and a cost (small at this volume); more DNS records than option A; a provider choice the foundation may want a say in.

DNS records to request

Hosted hive addresses are hive@<name>.hive.<project domain>. The existing DMARC policy is strict, so the DKIM signing domain must equal the From domain exactly. That makes a per-hive From expensive (one key record per hive, or a delegated zone). Two workable shapes:

Shape 1 (recommended): one fixed From, per-hive Reply-To. From: Hive <hive@hive.<project domain>>, Reply-To: hive@<hive host>. Works for vanity hosts too.

Record Type Value Required
<selector>._domainkey.hive.<project domain> TXT v=DKIM1; k=rsa; p=<public key> (2048-bit; the private key stays in a hub Secret) yes
hive.<project domain> TXT v=spf1 ip4:<sending IP> -all recommended (DKIM alone satisfies DMARC, since the envelope sender is null)
<sending host name> TXT v=spf1 a -all (covers the HELO identity used with a null envelope sender) recommended
reverse DNS for the sending IP PTR <sending host name> yes, set at the cloud provider, not in the zone

No existing record changes. The organizational DMARC record already covers this name.

Shape 2: From: hive@<hive host> itself. Needs one of: a DKIM TXT record per hive host (a ticket per hive, or delegating the hive.<project domain> zone so records can be automated), or relaxing the organizational DMARC record from adkim=s to adkim=r so one key at hive.<project domain> signs for every hive host. The second is a one-word change but weakens the policy for the whole domain; it should be the foundation's call. Vanity hosts are not covered either way.

With a provider (option C): the provider's DKIM records (for SES, three CNAMEs under _domainkey.hive.<project domain>), plus a custom return-path subdomain (one MX and one SPF TXT, for example at bounce.hive.<project domain>).

With no DNS change: nothing can be sent that passes DMARC. The SMTP refusal text and the Inbox are the whole feedback channel, which is what #18744 improves.

Templates

Short, plain text first, HTML alternative with the same words and two links. No images, no tracking.

Headers on all three:

From: Hive <hive@hive.<project domain>>
Reply-To: hive@<hive host>
To: <authenticated sender>
Subject: Re: <original subject, at most 120 characters>
In-Reply-To: <original Message-ID>
References: <original Message-ID>
Auto-Submitted: auto-replied
X-Auto-Response-Suppress: All
Precedence: auto_reply

Received

Your mail reached the hive.

Open it in the Inbox (sign-in required):
https://<hive host>/#inbox

Something wrong? Report a problem:
https://github.com/hivecommons/hive/issues/new/choose

This is an automatic reply. Replying to it sends a new mail to the hive.

Held for approval

Your mail reached the hive and is waiting for the hive owner's approval.
Nothing more is needed from you.

What this means:
https://github.com/hivecommons/hive/blob/v5/src/docs/inbox-voice-sources.md#mailing-your-hive-what-the-replies-mean

Report a problem:
https://github.com/hivecommons/hive/issues/new/choose

This is an automatic reply. Replying to it sends a new mail to the hive.

Refused (later step, aligned senders only)

The hive could not take your mail: <reason sentence, the same as the SMTP reply>.

To try again: <fix>. Reply to this message with the corrected file attached,
or send a new mail to the same address.

What this means:
<docs anchor for the reason>

Report a problem:
https://github.com/hivecommons/hive/issues/new/choose

This is an automatic reply.

Minimal HTML alternative (same for all three, text swapped in):

<p>Your mail reached the hive.</p>
<p><a href="https://<hive host>/#inbox">Open it in the Inbox</a> (sign-in required)</p>
<p><a href="https://github.com/hivecommons/hive/issues/new/choose">Report a problem</a></p>
<p style="color:#666">This is an automatic reply. Replying to it sends a new mail to the hive.</p>

Recommended first step

  1. Decide option A with DNS shape 1, and confirm with whoever runs the hosted hub that outbound TCP 25 and reverse DNS are available there. If port 25 is blocked and cannot be opened, go to option C.
  2. File the foundation IT ticket for the one required DKIM TXT record (and the two recommended SPF records).
  3. Build, behind the presence of the signing key: the header facts in wire.Delivery, the hub's reply decision (rules 1 to 7) with its ledger and limits, the "received" and "held" templates, and tests that assert each rule as an invariant (no reply to an unaligned sender, to bulk mail, twice for one Message-ID, or past a limit).
  4. Send to a test mailbox at two large providers and check the Authentication-Results header shows dmarc=pass before turning it on for everyone.

Activity

  1. self-assigned this
    on Nov 17, 2026
  2. clubanderson commented on Nov 17, 2026

    @clubanderson
    MemberAuthor

    On hold: this needs a maintainer decision and a DNS request to the foundation's IT before any code. Hive agents, please do not implement it.

  3. added
    stage/020-claimedClaimed by the scanner or a relay contributor
    stage/stalledIn its current stage longer than expected
    stage/010-actionableTriaged; eligible for the hive to pick up
    and removed
    stage/020-claimedClaimed by the scanner or a relay contributor
    stage/stalledIn its current stage longer than expected
    on Nov 18, 2026
  4. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    Parking for a maintainer ruling rather than implementing. Nothing in this design works without a sending domain, SPF/DKIM DNS records and outbound port 25 from the hub's network, and those belong to the maintainers and the foundation's IT, not to a feature PR.

    Risk: infrastructure/spend (owner-only DNS, credentials for a DKIM key) and public-facing behaviour (mail sent from the project's domain).

    Options:

    • A. Hub-side sender with DKIM (the recommendation in the issue body).
    • B. Receiver-side sender in hive-mx.
    • C. A third-party mail provider.

    Reply with /hive decision naming A, B or C, once DNS and egress are confirmed. The safety rules in the issue apply to all three.


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

    — hive: agent=scanner backend=claude model=claude-sonnet-5-5 claude=2.1.327

  5. added
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 18, 2026
  6. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    What to reply

    • /hive approve: go with the recommendation
    • /hive decision <your instructions>: go ahead, following your instructions
    • /hive help: show these again

    If what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply /fixed to close it as completed; Hive clears its park labels.

    Only a maintainer with write access can un-park; everything else is ignored. Full command reference: https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md.

  7. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    /hive decision A with DNS shape 1: hub-side sender with DKIM, as recommended in the issue. Confirm outbound TCP 25 and reverse DNS on the hosted hub first and fall back to option C (transactional provider) if they are not available. The foundation IT ticket for the DKIM TXT record and the two SPF records is the owner's action. Meanwhile build step 3 behind the presence of the signing key (default off, nothing is ever sent without the key): the header facts in wire.Delivery, the hub reply decision and ledger, the two templates and the invariant tests. Replies go only to authenticated senders (DMARC-aligned, allowlisted); never reply to a message that is itself an automated reply, a bounce or list mail; rate limits per sender and per hive.

  8. 14 remaining items

  9. github-actions commented on Nov 18, 2026

    @github-actions
    Contributor

    PR #18955 has merged (#18955) and referenced this issue with a non-closing Refs #18746 rather than a closing keyword.

    This issue remains open because the merged PR did not use Closes / Fixes / Resolves. If the fix should close it on merge, use a closing keyword in the PR body; use the opt-in hive: needs-confirmation marker only when the reporter genuinely must verify before closure.

  10. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    Claimed by the maintainer: a dispatched agent is working this, one PR to follow where code is needed. Please do not open a parallel PR.

  11. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    Fixed by #18955 (merged 52e3985). Closing. Reply /reopen if the problem persists.

  12. added
    human-onlyOnly a person or the owner can do this; never offered to contributor relays
    on Nov 18, 2026
  13. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    Adding smarthost (relay) support to the reply sender on the #19101 branch; relay runbook to follow.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

approved-directionhive/partially-addressedA merged PR addressed only part of this issue; remainder still actionablehuman-onlyOnly a person or the owner can do this; never offered to contributor relays

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions