Skip to content

✨ mailin: hive-mx receive-only mail receiver (Betty C2 part 1) - #18423

Merged
kubestellar-prow[bot] merged 4 commits into
v5from
feat/18395-mailin
Nov 16, 2026
Merged

kubestellar-prow[bot] merged 4 commits into
v5from
feat/18395-mailin

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Part 1 of #18395 (Betty C2, email in; plan in #18391, "Email invites").

What

New src/pkg/mailin and src/cmd/hive-mx: hive's receive-only SMTP receiver. Hub routing, the image, the spoke endpoints and the cluster deploy follow in separate PRs.

  • SMTP (emersion/go-smtp, MIT): RCPT TO accepted only for hive@<known hive host>; the host list comes from the hub (GET /api/mail/hosts) every 60 s, and until the first list loads RCPT gets a 451. At most 5 recipients, 2 MB SIZE, per-remote-IP and per-sender-organizational-domain rate limits, a connection cap, no AUTH, no relay, never sends mail. STARTTLS only when a certificate is mounted (re-read on renewal).
  • Sender authentication after DATA: SPF (blitiri.com.ar/go/spf, MIT), DKIM and DMARC identifier alignment with adkim/aspf and the organizational-domain record fallback (emersion/go-msgauth, MIT). The delivery carries the results; dmarc_aligned is the one field a spoke may trust.
  • Calendar invites (emersion/go-ical, MIT; teambition/rrule-go for RRULE validation): only text/calendar / application/ics parts. UID, SEQUENCE, METHOD (REQUEST/CANCEL, STATUS:CANCELLED too), RECURRENCE-ID, SUMMARY (200 runes), ORGANIZER, ATTENDEEs, DTSTART/DTEND/DURATION in UTC with TZID: IANA, Outlook Windows names (CLDR table), "(UTC-05:00) ..." display names and custom VTIMEZONE offsets; RRULE and EXDATE. Join link from X-GOOGLE-CONFERENCE, X-MICROSOFT-SKYPETEAMSMEETINGURL, LOCATION, or a host-limited scan of DESCRIPTION (meet.google.com, teams.microsoft.com, teams.live.com, *.zoom.us); platform; native meeting id and passcode (Zoom path + pwd, Teams /meet/<id>?p= or the "Meeting ID"/"Passcode" lines). Nothing else from DESCRIPTION is kept. Duplicate parts (Outlook inline + .ics) are merged by UID/RECURRENCE-ID keeping the highest SEQUENCE.
  • Mail-in files (emersion/go-message, MIT): .md, .m4a .mp3 .wav .ogg .webm, .png .jpg .gif .webp attachments, type decided by content sniffing that must agree with the extension; per-file, per-message and file-count caps, part-count and nesting caps; subject kept as title. Nothing executed.
  • Proof mails: a subject with a hive-proof-xxxxxxxxxxxx code is reported as a proof.
  • Output: pkg/mailin/wire (stdlib only, so hub and spoke can import it) is the JSON contract; one delivery per recipient is posted to POST /api/mail/inbound with the bearer token read from a mounted Secret on every call. A hub 4xx is a 550, anything else a 451 so the sender retries.

Licenses checked: all new modules are MIT (blitiri spf, go-smtp, go-sasl, go-msgauth, go-message, go-ical). NOTICE is regenerated from CI's notice-drift artifact in a follow-up commit on this PR.

Tests

Real-world ICS fixtures (Google Meet, Outlook/Teams with Windows TZIDs, Zoom, CANCEL, SEQUENCE bump, weekly RRULE with EXDATE), SMTP client tests over loopback (RCPT rejects, recipient cap, SIZE and body caps, IP and domain rate limits, hub down/refusing, partial refusal), DKIM sign/verify with an ed25519 test key against a fake resolver (aligned, other domain, relaxed vs strict, tampered, forged From), SPF pass/fail/null sender, DMARC fallback and temperror, an end-to-end Run with STARTTLS and health endpoints.

Docs: meetings.md "Inviting Betty by email", env-vars.md HIVE_MX_*.

🤖 Generated with Claude Code

New pkg/mailin and cmd/hive-mx: an SMTP receiver (emersion/go-smtp) that
accepts RCPT only for hive@<known hive host> (host list refreshed from the
hub every 60 s), caps recipients (5) and SIZE (2 MB), rate-limits per remote
IP and per sender organizational domain, offers no AUTH, relays nothing and
never sends mail; STARTTLS when a certificate is mounted.

After DATA it records SPF (blitiri.com.ar/go/spf), DKIM and DMARC
identifier alignment (emersion/go-msgauth) and keeps only:
- calendar invites (text/calendar, application/ics via emersion/go-ical):
  UID, SEQUENCE, METHOD, RECURRENCE-ID, summary, organizer, attendees,
  UTC times with Windows zone names mapped to IANA, RRULE and EXDATE, and
  the join link, platform, native meeting id and passcode;
- mail-in Markdown, audio and image attachments, content-sniffed, capped;
- proof codes in the subject.
Each delivery is posted to the hub (pkg/mailin/wire is the shared JSON
contract).

ICS fixtures for Google, Outlook/Teams, Zoom, CANCEL, a SEQUENCE bump and
a weekly RRULE with EXDATE; SMTP client tests for RCPT rejects, size caps
and rate limits; DKIM tests with an ed25519 test key and a fake resolver.

Part of #18391, #18395.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy 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 16, 2026
@github-actions

github-actions Bot commented Nov 16, 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
#18426 ✨ Inbox: read PDFs in a sandboxed hive-pdftext process same files src/docs/env-vars.md
#18424 ✨ meetings: Betty drafts issues, RFCs, Spek sessions and knowledge notes for approval (Betty F) same files src/docs/env-vars.md
src/docs/meetings.md
#18417 ✨ meetings: Settings tab "Meeting attendee" with Kokoro persona presets (Betty E) same files src/docs/meetings.md

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Mutation testing

gremlins found 46 surviving mutant(s) in changed files: the code ran under tests, but changing it did not fail any test.

File Line Mutation
src/pkg/mailin/auth.go 197 ARITHMETIC_BASE
src/pkg/mailin/auth.go 197 CONDITIONALS_BOUNDARY
src/pkg/mailin/auth.go 197 INVERT_NEGATIVES
src/pkg/mailin/config.go 71 CONDITIONALS_BOUNDARY
src/pkg/mailin/config.go 174 ARITHMETIC_BASE
src/pkg/mailin/config.go 175 ARITHMETIC_BASE
src/pkg/mailin/config.go 202 CONDITIONALS_NEGATION
src/pkg/mailin/config.go 212 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 51 CONDITIONALS_BOUNDARY
src/pkg/mailin/files.go 121 CONDITIONALS_BOUNDARY
src/pkg/mailin/files.go 129 CONDITIONALS_BOUNDARY
src/pkg/mailin/files.go 133 CONDITIONALS_BOUNDARY
src/pkg/mailin/hub.go 99 CONDITIONALS_BOUNDARY
src/pkg/mailin/ical.go 52 CONDITIONALS_BOUNDARY
src/pkg/mailin/ical.go 134 CONDITIONALS_NEGATION
src/pkg/mailin/ical.go 165 CONDITIONALS_BOUNDARY
src/pkg/mailin/ical.go 212 CONDITIONALS_BOUNDARY
src/pkg/mailin/ical.go 227 CONDITIONALS_BOUNDARY
src/pkg/mailin/ical.go 241 CONDITIONALS_BOUNDARY
src/pkg/mailin/ical.go 295 CONDITIONALS_BOUNDARY
src/pkg/mailin/joinurl.go 38 CONDITIONALS_BOUNDARY
src/pkg/mailin/joinurl.go 136 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 102 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 102 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 129 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 173 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 193 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 214 CONDITIONALS_NEGATION
src/pkg/mailin/ratelimit.go 40 CONDITIONALS_BOUNDARY
src/pkg/mailin/ratelimit.go 40 CONDITIONALS_BOUNDARY
src/pkg/mailin/ratelimit.go 43 CONDITIONALS_BOUNDARY
src/pkg/mailin/ratelimit.go 71 CONDITIONALS_BOUNDARY
src/pkg/mailin/ratelimit.go 71 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 86 CONDITIONALS_BOUNDARY
src/pkg/mailin/server.go 86 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 89 CONDITIONALS_BOUNDARY
src/pkg/mailin/server.go 89 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 194 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 269 CONDITIONALS_NEGATION
src/pkg/mailin/tz.go 192 CONDITIONALS_NEGATION
src/pkg/mailin/tz.go 208 CONDITIONALS_BOUNDARY
src/pkg/mailin/tz.go 208 CONDITIONALS_BOUNDARY
src/pkg/mailin/tz.go 211 ARITHMETIC_BASE
src/pkg/mailin/wire/wire.go 220 ARITHMETIC_BASE
src/pkg/mailin/wire/wire.go 220 CONDITIONALS_BOUNDARY
src/pkg/mailin/wire/wire.go 220 INVERT_NEGATIVES

48 mutant(s) in changed files are not reached by any test (NOT COVERED). A maintainer may apply the mutation/acknowledged label to accept this.

File Line Mutation
src/pkg/mailin/auth.go 42 ARITHMETIC_BASE
src/pkg/mailin/auth.go 86 CONDITIONALS_NEGATION
src/pkg/mailin/auth.go 123 CONDITIONALS_NEGATION
src/pkg/mailin/auth.go 125 CONDITIONALS_NEGATION
src/pkg/mailin/config.go 48 ARITHMETIC_BASE
src/pkg/mailin/config.go 49 ARITHMETIC_BASE
src/pkg/mailin/files.go 55 CONDITIONALS_BOUNDARY
src/pkg/mailin/files.go 55 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 55 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 64 CONDITIONALS_BOUNDARY
src/pkg/mailin/files.go 64 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 64 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 64 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 64 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 67 CONDITIONALS_BOUNDARY
src/pkg/mailin/files.go 67 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 67 CONDITIONALS_NEGATION
src/pkg/mailin/files.go 67 CONDITIONALS_NEGATION
src/pkg/mailin/hub.go 22 ARITHMETIC_BASE
src/pkg/mailin/hub.go 27 ARITHMETIC_BASE
src/pkg/mailin/hub.go 121 CONDITIONALS_BOUNDARY
src/pkg/mailin/hub.go 121 CONDITIONALS_BOUNDARY
src/pkg/mailin/hub.go 121 CONDITIONALS_NEGATION
src/pkg/mailin/hub.go 121 CONDITIONALS_NEGATION
src/pkg/mailin/hub.go 123 CONDITIONALS_NEGATION
src/pkg/mailin/hub.go 123 CONDITIONALS_NEGATION
src/pkg/mailin/hub.go 125 CONDITIONALS_BOUNDARY
src/pkg/mailin/hub.go 125 CONDITIONALS_BOUNDARY
src/pkg/mailin/hub.go 125 CONDITIONALS_NEGATION
src/pkg/mailin/hub.go 125 CONDITIONALS_NEGATION
src/pkg/mailin/joinurl.go 50 CONDITIONALS_NEGATION
src/pkg/mailin/joinurl.go 52 CONDITIONALS_NEGATION
src/pkg/mailin/joinurl.go 52 CONDITIONALS_NEGATION
src/pkg/mailin/joinurl.go 54 CONDITIONALS_NEGATION
src/pkg/mailin/message.go 145 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 145 CONDITIONALS_NEGATION
src/pkg/mailin/message.go 147 CONDITIONALS_BOUNDARY
src/pkg/mailin/message.go 147 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 66 ARITHMETIC_BASE
src/pkg/mailin/server.go 67 ARITHMETIC_BASE
src/pkg/mailin/server.go 68 ARITHMETIC_BASE
src/pkg/mailin/server.go 223 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 249 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 260 CONDITIONALS_BOUNDARY
src/pkg/mailin/server.go 260 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 262 CONDITIONALS_BOUNDARY
src/pkg/mailin/server.go 262 CONDITIONALS_NEGATION
src/pkg/mailin/server.go 262 CONDITIONALS_NEGATION

Verdict: lived (#17349).

@hivecommons-hive

hivecommons-hive Bot commented Nov 16, 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.

Why:

  • the review swarm returned requires_human: it has a question for you, not a fix for the hive
  • the reviewer asked you: clubanderson should decide whether a new internet-facing SMTP receiver (hive-mx) that posts to the hub with a bearer token, plus the new SPF/DKIM/DMARC dependencies, may land in this PR.

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.

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

Security review (head 65f51e5). Two in-scope findings, both about the rate-limit/DoS claims in the PR body.

1. Per-domain limit is keyed on the unauthenticated MAIL FROM (medium) — src/pkg/mailin/server.go:172
Mail() charges DomainLimiter against orgDomain(domainOf(from)) before SPF/DKIM/DMARC have run. Anyone can send MAIL FROM:<x@google.com> / outlook.com and drain that domain's bucket (burst 30, 120/h by default, config.go DefaultDomainPerHour). Real invites from that domain then get a 450 until it refills. A few IPs are enough to do this for the common calendar senders.

2. Limiter table wipe resets every bucket (low-medium) — src/pkg/mailin/ratelimit.go:76
At 10,000 keys with none idle for an hour, pruneLocked replaces the whole map. An attacker with many source addresses (an IPv6 /64) or many forged sender domains can fill the table and clear the per-IP and per-domain buckets for all senders, including their own. That lets them bypass both limits.

Suggested direction for both: charge the domain limiter after authentication (in Data, using auth.Aligned/auth.FromDomain), or only count aligned senders. At capacity, evict the oldest key or reject new keys rather than resetting the map. Key IPv6 clients by /64.

Advisory (out-of-scope, low): config.go:109 accepts a plain http:// HIVE_MX_HUB_URL, so the bearer token and message contents can go over cleartext. Consider requiring https outside tests.

Limits of this review: I read the SMTP server, auth, hub client, config, ratelimit and joinurl code. I did not run the tests or read the ical, tz, files and message parsers line by line.

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

Correctness review at head 65f51e5. I read server.go, auth.go, hub.go, ratelimit.go, message.go and wire.go. I did not read ical.go, tz.go or joinurl.go.

1. Medium: a partial hub failure makes the sender retry, so recipients already delivered get the message again (src/pkg/mailin/server.go:237-262)

  • Data posts one delivery per recipient, up to 5, in sequence.
  • If any post fails temporarily, temp > 0 returns errTemporary (451) for the whole message at line 260.
  • The sender then retries the whole message, and every recipient that was already delivered is posted again.
  • newDeliveryID() (line 239) is random on each attempt, so the hub has no stable key to dedupe on. MessageID is optional.
  • Result: duplicate invites or mail-in files in a hive, whenever one hub call out of several fails.
  • No test covers a multi-recipient case where one post fails and the others succeed. The PR body lists "partial refusal" for RCPT only.

Proposed fix: make the ID deterministic per message and recipient, and document that the hub must treat a repeated id as idempotent. That is a hub contract for the follow-up PR.

-func newDeliveryID() string {
-	b := make([]byte, deliveryIDBytes)
-	_, _ = rand.Read(b)
-	return hex.EncodeToString(b)
-}
+// deliveryID is stable across SMTP retries of the same message to the same
+// recipient, so the hub can drop a repeat.
+func deliveryID(raw []byte, rcpt string) string {
+	h := sha256.New()
+	h.Write(raw)
+	h.Write([]byte{0})
+	h.Write([]byte(rcpt))
+	return hex.EncodeToString(h.Sum(nil)[:deliveryIDBytes])
+}

Then use ID: deliveryID(raw, rcpt) at line 239. Add a test where the hub fails for one of two recipients, the sender retries, and the recipient that succeeded receives the same ID both times.

Checked, no defect found:

  • SPF handling of the null sender.
  • DMARC organizational-domain fallback and temperror handling.
  • Alignment logic.
  • Nil rate limiters.
  • HostSet atomics.
  • Part and depth caps.

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

Routing, not a defect report. This PR adds a public-facing network service (src/cmd/hive-mx, src/pkg/mailin/server.go), a hub credential path (HIVE_MX_HUB_TOKEN_FILE, config.go) and new modules in go.mod (blitiri.com.ar/go/spf, emersion/go-msgauth). Those are trust-surface additions that need a person's sign-off.

What I read: cmd/hive-mx/main.go (receive-only, config from env, exits 2 on bad config) and pkg/mailin/auth.go (SPF, DKIM capped at 5 signatures, DMARC with org-domain fallback, 20s DNS budget). Nothing wrong found there. I did not read server.go, hub.go, files.go or ical.go in full, so this is not an approval of them.

@hivecommons-hive

Copy link
Copy Markdown
Contributor
1596dea

ℹ️ Sentinel notice — informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @clubanderson, head 1596deac692e) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation — a maintainer should confirm the change is intended before it merges.

  • sensitive_path — changes 1 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • src/go.mod

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

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.

Style review (head 65f51e5). Nothing blocking; two small readability items.

  1. Typo in constant name — src/pkg/mailin/config.go:48 declares healthReadHeaderTimout (missing "e"), used at config.go:192. Suggested fix:
	healthReadHeaderTimeout = 5 * time.Second

(and update the use at line 192).

  1. PR body vs diff on NOTICE — the body says NOTICE "is regenerated ... in a follow-up commit", but the diff already adds 218 lines to NOTICE. Reword the body or confirm that the follow-up is not still pending, so reviewers know whether the file is final.

Advisory only: src/cmd/hive-mx/main.go:28 prints a hard-coded hive-mx 1 for --version. I did not check how other src/cmd/* binaries report versions.

— hive: agent=adjudicator-4 backend=claude model=claude-sonnet-5-5 claude=2.1.325

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Review follow-ups (below review.backlog.min_severity: P2)

Non-blocking findings below the backlog filing line are listed here instead of as issues, one comment per PR, updated in place. Tick them off as they are fixed; set review.backlog.min_severity: P3 to file every finding.

  • P3 low security — Hub URL may be plain http (src/pkg/mailin/config.go:109): ConfigFromEnv accepts http:// for HIVE_MX_HUB_URL, sending the bearer token and mail content in cleartext.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 16, 2026
@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 16, 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

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.

✨ Betty C2: email in (hive-mx receiver, hub routing, invites with join details, mail-in files to Inbox, allowlist with proof mails)

1 participant