Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-18395-hub-mail-routing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The hub routes mail from hive-mx: `GET /api/mail/hosts` lists the hosts it accepts `hive@<host>` 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.
30 changes: 16 additions & 14 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<hash>/<YYYY-MM>.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` |
Expand Down Expand Up @@ -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@<host>` 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` |
Expand Down
1 change: 1 addition & 0 deletions src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<login>--<name>` 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. |
Expand Down
31 changes: 29 additions & 2 deletions src/pkg/dashboard/webhook_relay.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
}
Expand All @@ -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)
}
72 changes: 72 additions & 0 deletions src/pkg/dashboard/webhook_relay_mail_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
Loading
Loading