diff --git a/changelog.d/added-18395-hub-mail-routing.md b/changelog.d/added-18395-hub-mail-routing.md new file mode 100644 index 0000000000..ac9459a32a --- /dev/null +++ b/changelog.d/added-18395-hub-mail-routing.md @@ -0,0 +1 @@ +- The hub routes mail from hive-mx: `GET /api/mail/hosts` lists the hosts it accepts `hive@` for, and `POST /api/mail/inbound` signs each delivery with the target hive's relay key and forwards it to that hive; spokes accept such relays through an `X-Hive-Relay-Delivery` header with the webhook relay's replay protection. Off until `HIVE_HUB_MAIL_TOKEN` is set. diff --git a/src/docs/api-reference/hub-server.md b/src/docs/api-reference/hub-server.md index cca609f0a4..35b5e2603f 100644 --- a/src/docs/api-reference/hub-server.md +++ b/src/docs/api-reference/hub-server.md @@ -35,8 +35,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/benchmarks/ingest` | Per-hive heartbeat bearer | Spoke push target for anonymized [benchmark records](../benchmarks.md): body `{hive_id, records[]}`; the hub recomputes the hive hash from the authenticated id, rejects records whose `source.hive_id` differs (`401` bad bearer, `403` unregistered hive, `400` malformed), merges accepted records by id into `/data/benchmarks//.json` and returns `202 {accepted, rejected, files}` | `pkg/hub/benchmarks.go` | | `GET` | `/api/hub/benchmarks` | Public | Benchmark publisher status: `last_ingest_at`, `last_publish_at`, `last_publish_files`, `last_error`, `pending_files`, `hive_count`, `record_count` and per-hive-hash `hives{}` counts; the hub commits pending month files hourly to `hivecommons/benchmarks` (`HIVE_BENCHMARKS_REPO`) via its App identity | `pkg/hub/benchmarks.go` | | `GET` | `/api/reach` | Hub admin | PR Reach Report (?pr=NNN or ?recent=K) | `pkg/hub/saas.go:522` | -| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1822` | -| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1823` | +| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1824` | +| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1825` | | `GET` | `/activity` | Signed-in user | Fleet activity page ([#16063](https://github.com/hivecommons/hive/issues/16063)): read-only, data-free shell that polls `/api/hub/activity` every 15 s with `If-None-Match`. No session → `307` to `/login`; blocked user → `403`. Own Content-Security-Policy (scripts and styles from `'self'` only, `script-src-attr`/`style-src-attr` `'none'`), `Cache-Control: no-cache` + content `ETag`. See [Hub Fleet activity page](../hub-fleet-activity.md) | `pkg/hub/activity_page.go` | | `GET` | `/activity/public` | Public | Public-safe Fleet activity page ([#15966](https://github.com/hivecommons/hive/issues/15966)): the same data-free shell as `/activity`, served without a session; on this path the page polls `/api/hub/activity/public` with `credentials: 'omit'`. Source of the `twitch.tv/hivecommonsfleet` broadcast. Same CSP and cache headers as `/activity`. See [Hub Fleet activity page](../hub-fleet-activity.md#public-safe-view) | `pkg/hub/activity_public.go` | | `GET` | `/activity/assets/{name}` | Public | The shared tracker assets the Fleet activity page loads, byte-identical: the row asset (`pkg/webassets/trackerrow`, [#16062](https://github.com/hivecommons/hive/issues/16062)) and the `am.*` URL-view and display-playlist helpers (`pkg/webassets/trackerview`, [#16064](https://github.com/hivecommons/hive/issues/16064)); only names in `trackerrow.Files` or `trackerview.Files`, else `404`. `Cache-Control: no-cache` + content `ETag` | `pkg/hub/activity_page.go` | @@ -64,18 +64,20 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/contribute/status` | Hub handler-specific | Contribute Status | `pkg/hub/server.go:1792` | | `GET` | `/api/contribute/ws` | Hub handler-specific | Contribute WSProxy | `pkg/hub/server.go:1793` | | `POST` | `/api/github/webhook` | Hub handler-specific | GitHub Webhook | `pkg/hub/server.go:1794` | -| `GET` | `/gh-setup` | Hub handler-specific | GitHub App Setup Router | `pkg/hub/server.go:1795` | -| `GET` | `/learn` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1796` | -| `GET` | `/get-started` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1797` | -| `GET` | `/api/docs` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1800` | -| `GET` | `/api/reading-list` | Hub handler-specific | Reading List | `pkg/hub/server.go:1803` | -| `GET` | `/reading` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1804` | -| `GET` | `/cncf-reference-architecture` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1811` | -| `GET` | `/cncf-reference-architecture/console` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1812` | -| `GET` | `/cncf-reference-architecture/bluefin` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1813` | -| `GET` | `/{$}` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1830` | -| `GET` | `/og-card.png` | Hub handler-specific | OGCard | `pkg/hub/server.go:1835` | -| `GET` | `/` | Public | Static asset fallback (`http.FileServerFS` over the embedded `static/` tree) for any path no other route claims | `pkg/hub/server.go:1837` | +| `GET` | `/api/mail/hosts` | hive-mx bearer (`HIVE_HUB_MAIL_TOKEN`) | Hosts the mail receiver accepts `hive@` for ([#18395](https://github.com/hivecommons/hive/issues/18395)): `{hosts[]}`, sorted, lower-case: every hosted hive's subdomain host, vanity URL host and reported dashboard URL host. A host claimed by two hives is left out. `401` bad token, `404` while `HIVE_HUB_MAIL_TOKEN` is unset. `Cache-Control: no-store` | `pkg/hub/mail_relay.go` | +| `POST` | `/api/mail/inbound` | hive-mx bearer (`HIVE_HUB_MAIL_TOKEN`) | One parsed mail delivery from hive-mx (`pkg/mailin/wire.Delivery`, at most 8 MiB). The hub matches the recipient host to a hosted hive, signs the body byte for byte with that hive's relay key (`X-Hive-Relay-Timestamp`, `X-Hive-Relay-Signature-256` bound to `X-Hive-Relay-Delivery`) and forwards it to the spoke's `/api/meetings/invites`, `/api/inbox/email` or `/api/meetings/calendar-emails/proof` by `kind`, behind the webhook relay's private-address guard and without following redirects. Stores nothing; logs the delivery id only. `202` delivered; `400` invalid delivery; `404` no such hive; `413` too large; `422` the spoke refused it (permanent); `502`/`503` hive not reachable yet or unavailable (hive-mx asks the sender to retry) | `pkg/hub/mail_relay.go` | +| `GET` | `/gh-setup` | Hub handler-specific | GitHub App Setup Router | `pkg/hub/server.go:1797` | +| `GET` | `/learn` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1798` | +| `GET` | `/get-started` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1799` | +| `GET` | `/api/docs` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1802` | +| `GET` | `/api/reading-list` | Hub handler-specific | Reading List | `pkg/hub/server.go:1805` | +| `GET` | `/reading` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1806` | +| `GET` | `/cncf-reference-architecture` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1813` | +| `GET` | `/cncf-reference-architecture/console` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1814` | +| `GET` | `/cncf-reference-architecture/bluefin` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1815` | +| `GET` | `/{$}` | Hub handler-specific | Static HTML page | `pkg/hub/server.go:1832` | +| `GET` | `/og-card.png` | Hub handler-specific | OGCard | `pkg/hub/server.go:1837` | +| `GET` | `/` | Public | Static asset fallback (`http.FileServerFS` over the embedded `static/` tree) for any path no other route claims | `pkg/hub/server.go:1839` | | `GET` | `/api/marketplace/workflows` | Public | Workflow-model marketplace index ([#17620](https://github.com/hivecommons/hive/issues/17620) phase 7): `{generatedAt, entries:[{name, version, hash, tier, description, source, states, columns, publishedAt, publishedBy, sourceSHA?, newerIngestAvailable, adoption:{}, ratings:{}, benchmarks:{}}]}`. Strong `ETag` (sha256 of the body) + `Cache-Control: no-cache`; `If-None-Match` → `304`. Tiers: `built-in`, `curated`, `ingested-unreviewed`, `local-published`. `404` when `HIVE_HUB_MARKETPLACE_DISABLED` is set | `pkg/hub/marketplace.go:36` | | `GET` | `/api/marketplace/workflows/{name}/{version}/bundle` | Public | One immutable signed bundle (`{apiVersion, model, profile, hash, createdAt, createdBy, tier}`), `Cache-Control: immutable`; `404` unknown, `400` malformed key | `pkg/hub/marketplace.go:37` | | `POST` | `/api/marketplace/workflows` | Spoke heartbeat bearer + `X-Hive-ID`, or Hub admin session | Publish a bundle. Body = bundle (≤ 4 MiB); the hub re-verifies the hash and recompiles the model before storing. Publisher may assert tier `local`/`local-published` (normalised to `local-published`) or `ingested-unreviewed`; `curated`/`built-in` require a hub admin session (`403` otherwise). `201 {published, created:true, entry}`; identical republish `200 created:false`; different content under an existing `name@version` `409`; verification failure `422`; unknown hive `403`; no hub secret `503` | `pkg/hub/marketplace.go:38` | diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index 88e3d971ea..aeb29e65df 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -89,6 +89,7 @@ behavior. [Maintenance limitations](#keeping-this-reference-current) still apply | `HIVE_HUB_LEGACY_COOKIE_DOMAIN` | No | none | Optional transition-only hub SSO cookie domain to expire alongside the active cookie domain while accepting any carried `hive_hub_user` cookie value during a host migration. Writes still target the domain derived from `HIVE_HUB_PUBLIC_URL`; unset disables the extra legacy-domain cleanup. | | `HIVE_HUB_SECRET` | Required for spokes registered to a protected hub; optional for a standalone hub with `/data/saas/hub-secret.key` | `/data/saas/hub-secret.key` on the hub when present; no fallback for spoke heartbeat auth | Bearer secret for spoke heartbeats and hub/spoke SaaS APIs. Self-hosted (`byo-`) hives registered through self-service never receive it: they hold only their own `HIVE_HEARTBEAT_KEY`, and the hub never tries `HIVE_HUB_SECRET` or anything derived from it for a `byo-` ID. | | `HIVE_HUB_SELFSERVICE_REGISTRATION` | No | off | Enables the self-service registration API (`/api/hub/selfservice/*`) that lets a signed-in user register a hive they run themselves under the reserved `byo---` ID namespace, after proving `permissions.admin` on every listed repo with their own GitHub token ([#18060](https://github.com/hivecommons/hive/issues/18060)). Accepts `1/true/yes/on`. When off, every route but `GET /api/hub/selfservice/status` answers `404` and the status reports `enabled: false`. Read per request; no restart needed. | +| `HIVE_HUB_MAIL_TOKEN` | Only on a hub that routes mail from `hive-mx` | none | Bearer token `hive-mx` presents on `GET /api/mail/hosts` and `POST /api/mail/inbound` ([#18395](https://github.com/hivecommons/hive/issues/18395)); the same value as the `hive-mx` Secret. Unset: both endpoints answer `404`. Read per request. Secret. | | `HIVE_HUB_SELFSERVICE_MAX_PER_USER` | No | `5` | Maximum self-service hives one user may have registered at once; the next registration answers `429` until one is removed. | | `HIVE_HUB_SELFSERVICE_EXPIRY` | No | `24h` | How long a self-service hive may go without an accepted heartbeat before the expiry sweep revokes its key and removes its registry entry (counted from the last accepted heartbeat, or from registration while there has been none). Reported by `GET /api/hub/selfservice/status` as `expiry`. Go duration syntax. | | `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL` | No | `10m` | How often the self-service expiry sweep (`src/pkg/hub/selfservice_expiry.go`) runs. Each removal writes `audit: selfservice_hive_expired` (see [audit-log.md](audit-log.md)). Read at startup; restart after changing. Go duration syntax. | diff --git a/src/pkg/dashboard/webhook_relay.go b/src/pkg/dashboard/webhook_relay.go index 24f01987c0..fe17df4a3c 100644 --- a/src/pkg/dashboard/webhook_relay.go +++ b/src/pkg/dashboard/webhook_relay.go @@ -24,9 +24,16 @@ import ( // After the MAC verifies, a timestamp more than webhookRelayMaxSkew from now // is rejected as stale, and a delivery ID already accepted inside the replay // window is rejected as replayed. +// +// Non-GitHub relays (hive-mx mail, hivecommons/hive#18395) carry their +// delivery ID in X-Hive-Relay-Delivery instead of X-GitHub-Delivery; when +// that header is present it is the ID the signature is bound to and the one +// remembered for replay, in its own namespace so the two kinds of ID never +// collide. const ( webhookRelaySignatureHeader = "X-Hive-Relay-Signature-256" webhookRelayTimestampHeader = "X-Hive-Relay-Timestamp" + webhookRelayDeliveryHeader = "X-Hive-Relay-Delivery" webhookRelayMaxSkew = 5 * time.Minute // webhookRelayReplayTTL covers every timestamp still inside the skew @@ -107,7 +114,13 @@ func (c *webhookRelayReplayCache) firstSeen(id string, now time.Time) bool { // fill the replay cache. func (s *Server) verifyWebhookRelay(h http.Header, body []byte, key string, now time.Time) string { ts := h.Get(webhookRelayTimestampHeader) - delivery := h.Get("X-GitHub-Delivery") + delivery, replayKey := h.Get("X-GitHub-Delivery"), "" + if relayed := h.Get(webhookRelayDeliveryHeader); relayed != "" { + delivery, replayKey = relayed, "relay:"+relayed + } + if replayKey == "" { + replayKey = "github:" + delivery + } if !verifyWebhookRelaySignature(body, ts, delivery, h.Get(webhookRelaySignatureHeader), key) { return webhookRelayReasonBadSignature } @@ -121,8 +134,22 @@ func (s *Server) verifyWebhookRelay(h http.Header, body []byte, key string, now if skew := now.Sub(time.Unix(sec, 0)); skew > webhookRelayMaxSkew || skew < -webhookRelayMaxSkew { return webhookRelayReasonStale } - if !s.webhookRelaySeen.firstSeen(delivery, now) { + if !s.webhookRelaySeen.firstSeen(replayKey, now) { return webhookRelayReasonReplayed } return "" } + +// verifyRelayedRequest authenticates a non-GitHub hub relay (hive-mx mail) +// with this hive's relay key: the X-Hive-Relay-Delivery header is required +// and the same signature, skew and replay rules apply. It returns "" when +// accepted, otherwise the rejection reason. +func (s *Server) verifyRelayedRequest(h http.Header, body []byte, key string, now time.Time) string { + if key == "" || h.Get(webhookRelaySignatureHeader) == "" { + return webhookRelayReasonBadSignature + } + if h.Get(webhookRelayDeliveryHeader) == "" { + return webhookRelayReasonNoDelivery + } + return s.verifyWebhookRelay(h, body, key, now) +} diff --git a/src/pkg/dashboard/webhook_relay_mail_test.go b/src/pkg/dashboard/webhook_relay_mail_test.go new file mode 100644 index 0000000000..b2ccb88429 --- /dev/null +++ b/src/pkg/dashboard/webhook_relay_mail_test.go @@ -0,0 +1,72 @@ +package dashboard + +import ( + "net/http" + "strconv" + "testing" + "time" +) + +func relayHeader(key, delivery string, ts time.Time, body []byte, withDelivery bool) http.Header { + h := http.Header{} + sec := strconv.FormatInt(ts.Unix(), 10) + h.Set(webhookRelayTimestampHeader, sec) + h.Set(webhookRelaySignatureHeader, signWebhookRelayForTest(key, sec, delivery, body)) + if withDelivery { + h.Set(webhookRelayDeliveryHeader, delivery) + } + return h +} + +// TestVerifyRelayedRequest: a non-GitHub relay (hive-mx mail, #18395) is +// bound to X-Hive-Relay-Delivery with the webhook relay's skew and replay +// rules. +func TestVerifyRelayedRequest(t *testing.T) { + const key = "relay-key-mail" + s := &Server{} + now := time.Now() + body := []byte(`{"id":"d1","kind":"invite"}`) + + if r := s.verifyRelayedRequest(relayHeader(key, "d1", now, body, true), body, key, now); r != "" { + t.Fatalf("valid relay rejected: %s", r) + } + if r := s.verifyRelayedRequest(relayHeader(key, "d1", now, body, true), body, key, now); r != webhookRelayReasonReplayed { + t.Fatalf("replay: %q", r) + } + cases := map[string]struct { + h http.Header + body []byte + key string + want string + }{ + "no key": {relayHeader(key, "d2", now, body, true), body, "", webhookRelayReasonBadSignature}, + "unsigned": {http.Header{webhookRelayDeliveryHeader: {"d3"}}, body, key, webhookRelayReasonBadSignature}, + "no delivery": {relayHeader(key, "d4", now, body, false), body, key, webhookRelayReasonNoDelivery}, + "tampered": {relayHeader(key, "d5", now, body, true), []byte(`{"id":"d5","kind":"files"}`), key, webhookRelayReasonBadSignature}, + "other delivery": {func() http.Header { h := relayHeader(key, "d6", now, body, true); h.Set(webhookRelayDeliveryHeader, "d7"); return h }(), body, key, webhookRelayReasonBadSignature}, + "stale": {relayHeader(key, "d8", now.Add(-time.Hour), body, true), body, key, webhookRelayReasonStale}, + "from the future": {relayHeader(key, "d9", now.Add(time.Hour), body, true), body, key, webhookRelayReasonStale}, + } + for name, c := range cases { + if got := s.verifyRelayedRequest(c.h, c.body, c.key, now); got != c.want { + t.Errorf("%s: %q, want %q", name, got, c.want) + } + } +} + +// TestRelayReplayNamespaces: a mail delivery id never collides with a GitHub +// delivery id of the same value. +func TestRelayReplayNamespaces(t *testing.T) { + const key = "relay-key-ns" + s := &Server{} + now := time.Now() + body := []byte(`{}`) + gh := relayHeader(key, "same-id", now, body, false) + gh.Set("X-GitHub-Delivery", "same-id") + if r := s.verifyWebhookRelay(gh, body, key, now); r != "" { + t.Fatalf("github relay: %q", r) + } + if r := s.verifyRelayedRequest(relayHeader(key, "same-id", now, body, true), body, key, now); r != "" { + t.Fatalf("mail relay with the same id: %q", r) + } +} diff --git a/src/pkg/hub/mail_relay.go b/src/pkg/hub/mail_relay.go new file mode 100644 index 0000000000..7c1097fee6 --- /dev/null +++ b/src/pkg/hub/mail_relay.go @@ -0,0 +1,272 @@ +package hub + +import ( + "bytes" + "context" + "crypto/subtle" + "encoding/json" + "errors" + "io" + "net/http" + "net/url" + "os" + "regexp" + "sort" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/mailin/wire" +) + +// Mail routing for hive-mx, the cluster's receive-only mail receiver +// (hivecommons/hive#18395, plan #18391 "Email invites"). +// +// hive-mx holds no per-hive secret. It asks the hub which hosts it may accept +// hive@ for (GET /api/mail/hosts) and posts each parsed delivery to +// POST /api/mail/inbound. The hub maps the recipient host to a hosted hive, +// signs the body with that hive's relay key exactly as it signs relayed +// GitHub webhooks (signWebhookRelayHeaders), with the delivery id in +// X-Hive-Relay-Delivery, and forwards it to the spoke behind the same +// private-address guard and no-redirect client as the webhook relay. The hub +// stores nothing and logs only the delivery id. +// +// Both endpoints need the shared bearer token HIVE_HUB_MAIL_TOKEN (the same +// value hive-mx mounts from its Secret); without it they answer 404, so a hub +// that does not run hive-mx exposes nothing. +const ( + // envHubMailToken is the bearer token hive-mx authenticates with. + envHubMailToken = "HIVE_HUB_MAIL_TOKEN" + // mailRelayDeliveryHeader carries a non-GitHub relay's delivery id; the + // spoke binds the relay signature to it (pkg/dashboard/webhook_relay.go). + mailRelayDeliveryHeader = "X-Hive-Relay-Delivery" + // mailInboundMaxBody bounds one delivery: a 2 MB message is at most + // about 2.7 MB of base64 attachments plus the JSON around them. + mailInboundMaxBody = 8 << 20 + // mailRelayTimeout bounds the forward to the spoke; hive-mx waits for + // the answer so the sender's server can be told to retry. + mailRelayTimeout = 30 * time.Second + // mailSpokeErrBody bounds what is read of a spoke's answer. + mailSpokeErrBody = 4096 +) + +// mailDeliveryIDRE is the shape of a hive-mx delivery id (16 random bytes). +var mailDeliveryIDRE = regexp.MustCompile(`^[0-9a-f]{32}$`) + +// mailRelayClient never follows redirects, for the reason documented on +// spokeWebhookRelayClient. +var mailRelayClient = &http.Client{ + Timeout: mailRelayTimeout, + CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }, +} + +func (s *HubServer) registerMailRoutes() { + s.mux.HandleFunc("GET "+wire.HostsPath, s.handleMailHosts) + s.mux.HandleFunc("POST "+wire.InboundPath, s.handleMailInbound) +} + +// mailAuthorized checks the hive-mx bearer token in constant time. An unset +// token disables the endpoints. +func mailAuthorized(r *http.Request) (enabled, ok bool) { + want := strings.TrimSpace(os.Getenv(envHubMailToken)) + if want == "" { + return false, false + } + got, found := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ") + if !found { + return true, false + } + return true, subtle.ConstantTimeCompare([]byte(strings.TrimSpace(got)), []byte(want)) == 1 +} + +// gateMail answers 404 while mail is off and 401 for a bad token; it +// returns true when the request may proceed. +func gateMail(w http.ResponseWriter, r *http.Request) bool { + enabled, ok := mailAuthorized(r) + switch { + case !enabled: + http.NotFound(w, r) + return false + case !ok: + w.Header().Set("WWW-Authenticate", `Bearer realm="hive-mx"`) + http.Error(w, "unauthorized", http.StatusUnauthorized) + return false + } + return true +} + +// hostOf is the lower-cased host of a URL or bare host name, "" if none. +func hostOf(v string) string { + v = strings.TrimSpace(v) + if v == "" { + return "" + } + if !strings.Contains(v, "://") { + v = "https://" + v + } + u, err := url.Parse(v) + if err != nil { + return "" + } + return strings.TrimSuffix(strings.ToLower(u.Hostname()), ".") +} + +// mailHostMap maps every host a hosted hive answers on (its subdomain, its +// vanity URL and the dashboard URL its spoke reports) to the hive id. A host +// claimed by two hives is dropped: mail for it cannot be routed safely. +func (s *HubServer) mailHostMap() map[string]string { + dashboards := map[string]string{} + s.mu.RLock() + for _, e := range s.registry.Hives { + if e.ID != "" && e.DashboardURL != "" { + dashboards[e.ID] = e.DashboardURL + } + } + s.mu.RUnlock() + + out := map[string]string{} + conflict := map[string]bool{} + add := func(host, id string) { + if host == "" || conflict[host] { + return + } + if prev, ok := out[host]; ok && prev != id { + delete(out, host) + conflict[host] = true + return + } + out[host] = id + } + for _, h := range listSaaSHives() { + if h.ID == "" { + continue + } + add(hostOf(h.Subdomain), h.ID) + add(hostOf(h.VanityURL), h.ID) + add(hostOf(dashboards[h.ID]), h.ID) + } + return out +} + +// handleMailHosts lists the hosts hive-mx accepts hive@ for. +func (s *HubServer) handleMailHosts(w http.ResponseWriter, r *http.Request) { + if !gateMail(w, r) { + return + } + m := s.mailHostMap() + hosts := make([]string, 0, len(m)) + for h := range m { + hosts = append(hosts, h) + } + sort.Strings(hosts) + w.Header().Set("Content-Type", "application/json") + w.Header().Set("Cache-Control", "no-store") + _ = json.NewEncoder(w).Encode(wire.HostsResponse{Hosts: hosts}) +} + +// mailEnvelope is the part of a delivery the hub reads to route it; the +// rest is forwarded untouched. +type mailEnvelope struct { + ID string `json:"id"` + Kind wire.Kind `json:"kind"` + Recipient string `json:"recipient"` +} + +func mailError(w http.ResponseWriter, code int, msg string) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(code) + _ = json.NewEncoder(w).Encode(map[string]string{"error": msg}) +} + +// handleMailInbound routes one hive-mx delivery to its hive. Status codes +// tell hive-mx whether the sender should retry: 4xx (other than 408/429) +// is permanent, everything else temporary. +func (s *HubServer) handleMailInbound(w http.ResponseWriter, r *http.Request) { + if !gateMail(w, r) { + return + } + body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, mailInboundMaxBody)) + if err != nil { + var tooBig *http.MaxBytesError + if errors.As(err, &tooBig) { + mailError(w, http.StatusRequestEntityTooLarge, "delivery too large") + return + } + mailError(w, http.StatusBadRequest, "unreadable body") + return + } + var env mailEnvelope + if err := json.Unmarshal(body, &env); err != nil { + mailError(w, http.StatusBadRequest, "invalid delivery") + return + } + path := wire.SpokePath(env.Kind) + host := wire.RecipientHost(env.Recipient) + if !mailDeliveryIDRE.MatchString(env.ID) || path == "" || host == "" { + mailError(w, http.StatusBadRequest, "invalid delivery") + return + } + hiveID, ok := s.mailHostMap()[host] + if !ok { + s.logger.Info("mail relay: no hive for recipient", "delivery", env.ID) + mailError(w, http.StatusNotFound, "no such hive") + return + } + h := loadSaaSHive(hiveID) + if h == nil { + mailError(w, http.StatusNotFound, "no such hive") + return + } + dashboardURL := "" + s.mu.RLock() + for _, e := range s.registry.Hives { + if e.ID == hiveID { + dashboardURL = e.DashboardURL + break + } + } + s.mu.RUnlock() + if h.WebhookRelayKey == "" || dashboardURL == "" { + // The spoke has not heartbeated since the relay key was minted, or + // has never reported its dashboard: worth retrying later. + s.logger.Info("mail relay: hive not reachable yet", "delivery", env.ID, "hive_id", hiveID) + mailError(w, http.StatusServiceUnavailable, "hive not reachable yet") + return + } + ctx, cancel := context.WithTimeout(r.Context(), mailRelayTimeout) + defer cancel() + if spokeWebhookRelayGuard(ctx, dashboardURL) { + s.logger.Warn("mail relay: refusing private or unresolvable dashboard URL", "delivery", env.ID, "hive_id", hiveID) + mailError(w, http.StatusBadGateway, "hive not reachable") + return + } + spokeURL := strings.TrimRight(dashboardURL, "/") + path + req, err := http.NewRequestWithContext(ctx, http.MethodPost, spokeURL, bytes.NewReader(body)) + if err != nil { + mailError(w, http.StatusBadGateway, "hive not reachable") + return + } + req.Header.Set("Content-Type", "application/json") + req.Header.Set(mailRelayDeliveryHeader, env.ID) + signWebhookRelayHeaders(req.Header, h.WebhookRelayKey, time.Now(), env.ID, body) + resp, err := mailRelayClient.Do(req) + if err != nil { + s.logger.Warn("mail relay: spoke unreachable", "delivery", env.ID, "hive_id", hiveID, "error", err) + mailError(w, http.StatusBadGateway, "hive not reachable") + return + } + _, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, mailSpokeErrBody)) + _ = resp.Body.Close() + s.logger.Info("mail relay: delivered", "delivery", env.ID, "hive_id", hiveID, "kind", string(env.Kind), "status", resp.StatusCode) + switch code := resp.StatusCode; { + case code >= 200 && code < 300: + w.WriteHeader(http.StatusAccepted) + case code == http.StatusUnauthorized, code == http.StatusNotFound, code == http.StatusMethodNotAllowed: + // A relay key the spoke does not hold yet, or a spoke that predates + // the endpoint: temporary from the sender's point of view. + mailError(w, http.StatusBadGateway, "hive did not accept the delivery yet") + case code == http.StatusRequestTimeout, code == http.StatusTooManyRequests, code >= 500: + mailError(w, http.StatusBadGateway, "hive unavailable") + default: + mailError(w, http.StatusUnprocessableEntity, "hive refused the delivery") + } +} diff --git a/src/pkg/hub/mail_relay_test.go b/src/pkg/hub/mail_relay_test.go new file mode 100644 index 0000000000..017ff60778 --- /dev/null +++ b/src/pkg/hub/mail_relay_test.go @@ -0,0 +1,275 @@ +package hub + +import ( + "bytes" + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "strconv" + "strings" + "sync/atomic" + "testing" + + "github.com/hivecommons/hive/pkg/mailin/wire" +) + +const testMailToken = "mx-token-123" + +// mailTestHub is a hub with one hosted hive (subdomain, vanity URL and a +// reported dashboard URL) and an optional second hive. +func mailTestHub(t *testing.T, dashboardURL string) *HubServer { + t.Helper() + old := saasHivesDir + saasHivesDir = t.TempDir() + t.Cleanup(func() { saasHivesDir = old }) + t.Setenv(envHubMailToken, testMailToken) + for _, h := range []*SaaSHive{ + {ID: "hosted-acme-widgets-ab12", Subdomain: "hosted-acme-widgets-ab12.hive.hivecommons.dev", VanityURL: "https://acme.hive.hivecommons.dev", WebhookRelayKey: "relay-key-acme"}, + {ID: "hosted-beta-x-cd34", Subdomain: "hosted-beta-x-cd34.hive.hivecommons.dev"}, + // Two hives claiming one vanity host: neither gets its mail. + {ID: "hosted-dup-1", Subdomain: "dup-1.hive.hivecommons.dev", VanityURL: "https://dup.hive.hivecommons.dev"}, + {ID: "hosted-dup-2", Subdomain: "dup-2.hive.hivecommons.dev", VanityURL: "https://dup.hive.hivecommons.dev/"}, + {ID: "hosted-dup-3", Subdomain: "dup-3.hive.hivecommons.dev", VanityURL: "dup.hive.hivecommons.dev"}, + } { + if err := saveSaaSHive(h); err != nil { + t.Fatal(err) + } + } + s := newWebhookHub() + s.registry.Hives = []RegistryEntry{ + {ID: "hosted-acme-widgets-ab12", DashboardURL: dashboardURL}, + {ID: "hosted-beta-x-cd34"}, + {ID: "byo-someone--selfhosted", DashboardURL: "https://self.example.org"}, + } + return s +} + +func mailRequest(method, path, token string, body []byte) *http.Request { + r := httptest.NewRequest(method, path, bytes.NewReader(body)) + if token != "" { + r.Header.Set("Authorization", "Bearer "+token) + } + return r +} + +func TestMailHosts(t *testing.T) { + s := mailTestHub(t, "https://dash.acme.example/") + rec := httptest.NewRecorder() + s.handleMailHosts(rec, mailRequest(http.MethodGet, wire.HostsPath, testMailToken, nil)) + if rec.Code != http.StatusOK { + t.Fatalf("status %d", rec.Code) + } + var hr wire.HostsResponse + if err := json.Unmarshal(rec.Body.Bytes(), &hr); err != nil { + t.Fatal(err) + } + want := "acme.hive.hivecommons.dev,dash.acme.example,dup-1.hive.hivecommons.dev,dup-2.hive.hivecommons.dev,dup-3.hive.hivecommons.dev,hosted-acme-widgets-ab12.hive.hivecommons.dev,hosted-beta-x-cd34.hive.hivecommons.dev" + if got := strings.Join(hr.Hosts, ","); got != want { + t.Fatalf("hosts\n got %s\nwant %s", got, want) + } +} + +func TestMailGate(t *testing.T) { + s := mailTestHub(t, "https://dash.acme.example") + for _, tc := range []struct { + token string + want int + }{{"", http.StatusUnauthorized}, {"wrong", http.StatusUnauthorized}} { + rec := httptest.NewRecorder() + s.handleMailHosts(rec, mailRequest(http.MethodGet, wire.HostsPath, tc.token, nil)) + if rec.Code != tc.want { + t.Errorf("token %q: %d, want %d", tc.token, rec.Code, tc.want) + } + rec = httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, tc.token, []byte(`{}`))) + if rec.Code != tc.want { + t.Errorf("inbound token %q: %d, want %d", tc.token, rec.Code, tc.want) + } + } + // No token configured: the endpoints do not exist. + t.Setenv(envHubMailToken, "") + rec := httptest.NewRecorder() + s.handleMailHosts(rec, mailRequest(http.MethodGet, wire.HostsPath, testMailToken, nil)) + if rec.Code != http.StatusNotFound { + t.Fatalf("mail off: %d", rec.Code) + } +} + +func TestMailRoutesRegistered(t *testing.T) { + s := mailTestHub(t, "https://dash.acme.example") + s.mux = http.NewServeMux() + s.registerMailRoutes() + rec := httptest.NewRecorder() + s.mux.ServeHTTP(rec, mailRequest(http.MethodGet, wire.HostsPath, testMailToken, nil)) + if rec.Code != http.StatusOK { + t.Fatalf("GET hosts through the mux: %d", rec.Code) + } +} + +type spokeHit struct { + path string + header http.Header + body []byte +} + +func delivery(id string, kind wire.Kind, rcpt string) []byte { + b, _ := json.Marshal(wire.Delivery{ID: id, Kind: kind, Recipient: rcpt, Invites: []wire.Invite{{UID: "u1", Passcode: "p"}}}) + return b +} + +const testDeliveryID = "0123456789abcdef0123456789abcdef" + +func TestMailInboundForwardsSigned(t *testing.T) { + allowLoopbackRelay(t) + hits := make(chan spokeHit, 4) + var status atomic.Int32 + status.Store(http.StatusOK) + spoke := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + hits <- spokeHit{r.URL.Path, r.Header.Clone(), body} + w.WriteHeader(int(status.Load())) + })) + defer spoke.Close() + s := mailTestHub(t, spoke.URL+"/") + + for kind, path := range map[wire.Kind]string{wire.KindInvite: wire.SpokeInvitesPath, wire.KindFiles: wire.SpokeFilesPath, wire.KindProof: wire.SpokeProofPath} { + body := delivery(testDeliveryID, kind, "hive@ACME.hive.hivecommons.dev") + rec := httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, testMailToken, body)) + if rec.Code != http.StatusAccepted { + t.Fatalf("%s: status %d %s", kind, rec.Code, rec.Body) + } + h := <-hits + if h.path != path || !bytes.Equal(h.body, body) { + t.Fatalf("%s: forwarded to %s, body equal %v", kind, h.path, bytes.Equal(h.body, body)) + } + if h.header.Get(mailRelayDeliveryHeader) != testDeliveryID || h.header.Get("Content-Type") != "application/json" { + t.Fatalf("%s: headers %v", kind, h.header) + } + ts := h.header.Get(webhookRelayTimestampHeader) + if _, err := strconv.ParseInt(ts, 10, 64); err != nil { + t.Fatalf("timestamp %q", ts) + } + if want := webhookRelaySignature("relay-key-acme", ts, testDeliveryID, body); h.header.Get(webhookRelaySignatureHeader) != want { + t.Fatalf("%s: relay signature does not verify with the hive's key", kind) + } + } + + // The spoke's answer maps to a retry decision for hive-mx. + for spokeCode, want := range map[int]int{ + http.StatusUnauthorized: http.StatusBadGateway, + http.StatusNotFound: http.StatusBadGateway, + http.StatusTooManyRequests: http.StatusBadGateway, + http.StatusInternalServerError: http.StatusBadGateway, + http.StatusBadRequest: http.StatusUnprocessableEntity, + http.StatusForbidden: http.StatusUnprocessableEntity, + } { + status.Store(int32(spokeCode)) + rec := httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, testMailToken, delivery(testDeliveryID, wire.KindInvite, "hive@acme.hive.hivecommons.dev"))) + <-hits + if rec.Code != want { + t.Errorf("spoke %d: hub answered %d, want %d", spokeCode, rec.Code, want) + } + } +} + +func TestMailInboundRejects(t *testing.T) { + allowLoopbackRelay(t) + spoke := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + t.Errorf("unexpected forward to %s", r.URL.Path) + })) + defer spoke.Close() + s := mailTestHub(t, spoke.URL) + cases := map[string]struct { + body []byte + want int + }{ + "not json": {[]byte("{"), http.StatusBadRequest}, + "bad id": {delivery("not-hex", wire.KindInvite, "hive@acme.hive.hivecommons.dev"), http.StatusBadRequest}, + "bad kind": {delivery(testDeliveryID, "spam", "hive@acme.hive.hivecommons.dev"), http.StatusBadRequest}, + "not the mailbox": {delivery(testDeliveryID, wire.KindInvite, "bob@acme.hive.hivecommons.dev"), http.StatusBadRequest}, + "unknown host": {delivery(testDeliveryID, wire.KindInvite, "hive@nowhere.example"), http.StatusNotFound}, + "ambiguous host": {delivery(testDeliveryID, wire.KindInvite, "hive@dup.hive.hivecommons.dev"), http.StatusNotFound}, + "self-hosted": {delivery(testDeliveryID, wire.KindInvite, "hive@self.example.org"), http.StatusNotFound}, + "no relay key yet": {delivery(testDeliveryID, wire.KindInvite, "hive@hosted-beta-x-cd34.hive.hivecommons.dev"), http.StatusServiceUnavailable}, + "too large": {append([]byte(`{"id":"`), bytes.Repeat([]byte("a"), mailInboundMaxBody)...), http.StatusRequestEntityTooLarge}, + } + for name, c := range cases { + rec := httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, testMailToken, c.body)) + if rec.Code != c.want { + t.Errorf("%s: %d, want %d (%s)", name, rec.Code, c.want, strings.TrimSpace(rec.Body.String())) + } + } +} + +func TestMailInboundGuardAndUnreachable(t *testing.T) { + // The production guard refuses a loopback dashboard URL. + s := mailTestHub(t, "http://127.0.0.1:9") + rec := httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, testMailToken, delivery(testDeliveryID, wire.KindInvite, "hive@acme.hive.hivecommons.dev"))) + if rec.Code != http.StatusBadGateway { + t.Fatalf("private dashboard URL: %d", rec.Code) + } + + // Allowed but nothing listening: temporary. + allowLoopbackRelay(t) + rec = httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, testMailToken, delivery(testDeliveryID, wire.KindInvite, "hive@acme.hive.hivecommons.dev"))) + if rec.Code != http.StatusBadGateway { + t.Fatalf("unreachable spoke: %d", rec.Code) + } + + // A dashboard URL that cannot form a request. + s.registry.Hives[0].DashboardURL = "http://bad host" + rec = httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, testMailToken, delivery(testDeliveryID, wire.KindInvite, "hive@acme.hive.hivecommons.dev"))) + if rec.Code != http.StatusBadGateway { + t.Fatalf("bad dashboard URL: %d", rec.Code) + } +} + +func TestMailRelayNeverFollowsRedirects(t *testing.T) { + allowLoopbackRelay(t) + internal := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + t.Error("the relay followed a redirect") + })) + defer internal.Close() + spoke := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + http.Redirect(w, r, internal.URL, http.StatusTemporaryRedirect) + })) + defer spoke.Close() + s := mailTestHub(t, spoke.URL) + rec := httptest.NewRecorder() + s.handleMailInbound(rec, mailRequest(http.MethodPost, wire.InboundPath, testMailToken, delivery(testDeliveryID, wire.KindInvite, "hive@acme.hive.hivecommons.dev"))) + if rec.Code != http.StatusUnprocessableEntity { + t.Fatalf("redirect answer: %d", rec.Code) + } +} + +func TestMailSpokePathsArePublic(t *testing.T) { + for _, p := range []string{wire.SpokeInvitesPath, wire.SpokeFilesPath, wire.SpokeProofPath} { + if !isSaaSPublicPath(p) { + t.Errorf("%s must pass the hosted auth-check: the spoke verifies the relay signature itself", p) + } + } + if isSaaSPublicPath("/api/meetings/calendar-emails") { + t.Error("the user-facing calendar-emails API must stay behind the login gate") + } +} + +func TestHostOf(t *testing.T) { + for in, want := range map[string]string{ + "": "", + "Acme.Example.": "acme.example", + "https://acme.example:8443/": "acme.example", + "http://[::1]:80": "::1", + "https://bad host": "", + } { + if got := hostOf(in); got != want { + t.Errorf("%q: %q, want %q", in, got, want) + } + } +} diff --git a/src/pkg/hub/saas_auth.go b/src/pkg/hub/saas_auth.go index 2daf88d43a..367b39d747 100644 --- a/src/pkg/hub/saas_auth.go +++ b/src/pkg/hub/saas_auth.go @@ -16,6 +16,7 @@ import ( "golang.org/x/net/publicsuffix" hgithub "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/mailin/wire" ) func (s *HubServer) requireAuth(next http.HandlerFunc) http.HandlerFunc { @@ -879,6 +880,12 @@ var publicExactPaths = map[string]struct{}{ "/tokens.css": {}, spokeWidgetSummaryPath: {}, spokeWebhookRelayPath: {}, + // The hive-mx mail relay targets (#18395, mail_relay.go). Like the + // webhook receiver, each spoke handler fails closed without a valid + // hub relay signature. + wire.SpokeInvitesPath: {}, + wire.SpokeFilesPath: {}, + wire.SpokeProofPath: {}, } var publicTreePaths = []string{"/api/contribute", "/api/leaderboard", "/contribute", "/leaderboard", "/snapshot"} diff --git a/src/pkg/hub/server.go b/src/pkg/hub/server.go index 94ec9a0f1b..854268a817 100644 --- a/src/pkg/hub/server.go +++ b/src/pkg/hub/server.go @@ -1792,6 +1792,8 @@ func NewHubServer(port int, logger *slog.Logger, gitHash, gitBranch string) *Hub s.mux.HandleFunc("GET /api/contribute/status", s.handleContributeStatus) s.mux.HandleFunc("GET /api/contribute/ws", s.handleContributeWSProxy) s.mux.HandleFunc("POST /api/github/webhook", s.handleGitHubWebhook) + // hive-mx mail routing (#18395, mail_relay.go); 404 without HIVE_HUB_MAIL_TOKEN. + s.registerMailRoutes() s.mux.HandleFunc("GET /gh-setup", s.handleGitHubAppSetupRouter) s.mux.HandleFunc("GET /learn", s.serveStatic("static/learn.html")) s.mux.HandleFunc("GET /get-started", s.serveStatic("static/get-started.html"))