Skip to content

✨ hub: route hive-mx mail to hives with the relay key (Betty C2 part 3) - #18429

Merged
hivecommons-hive[bot] merged 2 commits into
v5from
feat/18395-hub-mail
Nov 16, 2026
Merged

hivecommons-hive[bot] merged 2 commits into
v5from
feat/18395-hub-mail

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Part 3 of #18395 (Betty C2, email in; plan #18391 "Email invites"). Uses the pkg/mailin/wire contract from #18423.

Hub (src/pkg/hub/mail_relay.go)

  • GET /api/mail/hosts: every hosted hive's subdomain host, vanity URL host and the dashboard URL host its spoke reports, sorted; a host two hives claim is left out (mail for it cannot be routed safely).
  • POST /api/mail/inbound: reads only id, kind and recipient of a hive-mx delivery (8 MiB cap), maps the recipient host to its SaaSHive, signs the unchanged body with that hive's relay key (signWebhookRelayHeaders, delivery id in X-Hive-Relay-Delivery) and forwards it to /api/meetings/invites, /api/inbox/email or /api/meetings/calendar-emails/proof by kind, behind the webhook relay's private-address guard (spokeWebhookRelayGuard) and a client that never follows redirects. Stores nothing; logs the delivery id, hive id and status only.
  • Status codes tell hive-mx whether the sender's server should retry: 202 delivered, 400/404/413/422 permanent, 502/503 temporary (no relay key yet, spoke unreachable, spoke 401/404/405/408/429/5xx).
  • Both endpoints need the bearer token HIVE_HUB_MAIL_TOKEN (constant-time compare) and answer 404 while it is unset, so a hub without hive-mx exposes nothing.
  • The three spoke paths are added to isSaaSPublicPath: the spoke handlers fail closed without a valid relay signature.

Spoke (src/pkg/dashboard/webhook_relay.go)

The relay verification accepts X-Hive-Relay-Delivery for non-GitHub relays: when present it is the id the signature is bound to and the one remembered for replay, with the same 5-minute skew and replay window; replay ids are namespaced (github: / relay:) so the two kinds never collide. verifyRelayedRequest requires the header (used by the spoke endpoints in the next PR).

Docs: api-reference/hub-server.md (citations fixed with check-docs-citations.py --fix), env-vars.md.

🤖 Generated with Claude Code

GET /api/mail/hosts lists every hosted hive's subdomain, vanity and
reported dashboard host (a host two hives claim is left out). POST
/api/mail/inbound reads only id, kind and recipient of a hive-mx delivery,
maps the recipient host to its SaaSHive, signs the unchanged body with that
hive's relay key (signWebhookRelayHeaders, delivery id in
X-Hive-Relay-Delivery) and forwards it to /api/meetings/invites,
/api/inbox/email or /api/meetings/calendar-emails/proof behind the webhook
relay's private-address guard and a no-redirect client. It stores nothing
and logs the delivery id only; status codes tell hive-mx whether the sender
should retry. Both endpoints need HIVE_HUB_MAIL_TOKEN and 404 without it.

The three spoke paths pass the hosted auth-check (isSaaSPublicPath). The
spoke's relay verification accepts X-Hive-Relay-Delivery for non-GitHub
relays with the same skew and replay rules, replay ids namespaced per kind,
and verifyRelayedRequest for the mail endpoints.

Part of #18391, #18395.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 16, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found 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 added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label 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
#18424 ✨ meetings: Betty drafts issues, RFCs, Spek sessions and knowledge notes for approval (Betty F) same files src/docs/env-vars.md

@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 a spoke-reported dashboard URL host may be used to route inbound mail to that hive.

This adds a new public-facing hub ingest path (POST /api/mail/inbound, bearer HIVE_HUB_MAIL_TOKEN) that signs bodies with a hive's relay key, and widens isSaaSPublicPath. That is a credentials and external-input surface, so it goes to a person. I found no concrete bug.

What I read: the token check is constant-time and fails to 404 when unset (mail_relay.go, mailAuthorized); redirects are disabled; the spoke-side change only namespaces replay keys (github:/relay:) and requires X-Hive-Relay-Delivery in verifyRelayedRequest, with the same MAC, skew and replay checks.

Open question, not verified as a defect: mailHostMap also maps hostOf(dashboards[h.ID]), and that URL is reported by the spoke through the registry. A host claimed by two hives is dropped from the map. So a spoke that reports another hive's host would remove that hive's mail routing, or one reporting an unclaimed host would receive mail for it. Please confirm that registry DashboardURL is validated against the hive's own domain before it is trusted here (the same concern as #14813).

— hive: agent=reviewer-2 backend=claude model=claude-sonnet-5-5 claude=2.1.325

@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 spoke-reported dashboard URL host may be used to route inbound mail to that hive.

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.

Evidence bundle `#184291aed879` sha256:cbcc384378413245c31c3ab9a9a78862a6bfd3c43964b21fe2d688a3984565d1 — download from the dashboard or `hivectl review evidence #18429`.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Mutation testing

✅ Resolved: no surviving or uncovered mutants in changed files on the current head.

Verdict: pass (#17349).

@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 a spoke-reported dashboard URL host may count toward hive-mx host routing, given a self-service (byo-) hive can then claim a host and make the hub drop mail for any host it shares?

Routing to a human: this adds a token-gated endpoint, signs with per-hive relay keys, and widens publicExactPaths — all trust-surface changes. I read mail_relay.go, the webhook_relay.go change and the saas_auth.go hunk at head 1aed879.

What looks correct to me:

  • mailAuthorized compares in constant time and fails to 404 when HIVE_HUB_MAIL_TOKEN is unset (mail_relay.go, gateMail).
  • The forward goes through spokeWebhookRelayGuard and a no-redirect client; the signature binds the delivery id, and replay ids are namespaced (relay: / github:) in verifyWebhookRelay, with tests for both.

One question I could not settle from the diff (open question, not a confirmed defect): mailHostMap includes e.DashboardURL from s.registry.Hives, which the PR body says is "the dashboard URL its spoke reports". On a host claimed by two hives, add deletes it and blacklists it for everyone. If a spoke (including a self-service byo- hive, #18060) can report another hive's host as its dashboard URL, it can silently stop mail routing for that hive. I did not find where the heartbeat validates that URL. Worth a maintainer confirming it is constrained (or restricting the host map to hub-assigned subdomain/vanity hosts).

Minor, suggestion only: the three spoke paths added to publicExactPaths (saas_auth.go hunk) are only safe if the spoke handlers in the next PR call verifyRelayedRequest; nothing in this PR enforces that, so that PR deserves a close read.

— hive: agent=reviewer-2 backend=claude model=claude-sonnet-5-5 claude=2.1.325

@hivecommons-hive
hivecommons-hive Bot merged commit f03a809 into v5 Nov 16, 2026
80 of 81 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/18395-hub-mail branch November 16, 2026 15:17
@hivecommons-hive

Copy link
Copy Markdown
Contributor

merged by Hive trusted-author auto-merge: author @clubanderson holds role owner and GitHub permission admin on repo; CI green at 1aed879.

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/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant