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-15966-public-safe-activity-view.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The hub serves an anonymous **public-safe Fleet activity view** at `/activity/public`, backed by `GET /api/hub/activity/public` ([#15966](https://github.com/hivecommons/hive/issues/15966), part of [#15861](https://github.com/hivecommons/hive/issues/15861)). It is the source of the `twitch.tv/hivecommonsfleet` broadcast, and `src/deploy/stream/fleet` now points `DASHBOARD_PATH` at it. The view shows only public-repository items and events from hives the registry lists as public on github.com. It leaves out private or unknown-visibility rows, totals and drop counts that can include private items, hive owners and every per-user grant. It never reads a session or token, so a signed-in viewer's own Fleet access cannot leak onto a public stream. The signed-in `/activity` page is unchanged, and no broadcast is activated.
10 changes: 6 additions & 4 deletions src/deploy/stream/fleet/configmap.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,19 @@ metadata:
data:
# Fail-closed switches (see ../public-safe-gate.sh). Only the owner flips
# STREAM_ENABLED to "true" and sets PUBLIC_SAFE_POLICY_ACK to the policy
# version, after provisioning the stream key and the public-safe hub view.
# version, after provisioning the stream key and checking the public-safe
# hub view in a private browser window.
STREAM_PROFILE: "public-safe"
STREAM_ENABLED: "false"
PUBLIC_SAFE_POLICY_ACK: ""
# The hub's public origin. The kiosk reaches it anonymously: no dashboard
# credential exists in this namespace and the auth proxy refuses one, so the
# stream shows only what the hub serves to the public.
DASHBOARD_URL: "https://hive.hivecommons.dev"
# The separately authorized public-safe hub view (#15966). The placeholder
# makes the gate refuse to start until the owner sets the real path.
DASHBOARD_PATH: "CHANGE-ME-public-safe-hub-view"
# The hub's anonymous public-safe Fleet activity view (#15966): public
# repositories of registry-public hives only, never per-user visibility.
# ?kiosk=1 hides the page chrome for the unattended stream.
DASHBOARD_PATH: "/activity/public?kiosk=1"
TWITCH_INGEST: "rtmp://live.twitch.tv/app"
VIDEO_SIZE: "1920x1080"
FPS: "30"
Expand Down
2 changes: 2 additions & 0 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1773` |
| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1774` |
| `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` |
| `POST` | `/api/shared-agent-pool/leases` | Hub handler-specific | Acquire or renew a shared CLI session lease | `pkg/hub/server.go:1708` |
| `PUT` | `/api/shared-agent-pool/leases` | Hub handler-specific | Renew an active shared CLI session lease | `pkg/hub/server.go:1709` |
Expand All @@ -49,6 +50,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/hub/evidence` | Hub admin | Read-only cross-hive evidence drill-down from each spoke's stored heartbeat `evidence` summary ([#12116](https://github.com/hivecommons/hive/issues/12116)); non-admins get `403`. Returns `spokes`, `reporting`, pooled `calibration` (bucket 0–5 → `{n, bad, rate, lo, hi}`; the hub view folds the six buckets into four reviewer-confidence ranges), `findings[]` (the plain-language *What this says* sentences, generated from the same fields; [#12456](https://github.com/hivecommons/hive/issues/12456)), `by_acmm_level` (`level`, `hives`, `merged_90d`, `revert_rate`, and `time_to_merge` — `median_of_hive_medians_s`, `hives`, `n` — the median of the level's per-hive median time-to-merge, omitted when no hive at the level reports one; [#12464](https://github.com/hivecommons/hive/issues/12464)), `family_false_approve_rate` (`same`/`cross`/`mixed`, hives classed by their reviewer vs author family sets), fleet `record_coverage` (merged PRs with an evidence record over `prs_merged_90d`), fleet panels ([#12370](https://github.com/hivecommons/hive/issues/12370)) `outcomes_by_author_kind[]` (`kind`, `hives`, `n`, `merged`, `reverted`, `merge_rate`, `revert_rate`), `write_counters[]` (`tier`, `hives`, `attempted`, `blocked`, `block_rate`) and `shadow_gate` (`review_gate` / `intent` → `held` / `passed` outcomes with `revert_rate`), each omitted while no spoke reports it and repeated per `by_acmm_level[]` row, and per hive `hives[]` with `acmm_level`, `prs_merged_90d`, `record_coverage`, `family_mix`, false-approve / false-block / revert rates, families, a calibration series the raw `counts` behind them (including `by_author_kind`) so the drill-down can re-pool a hive / ACMM-level selection client-side, and `criteria[]`: the per-axis criteria table derived hub-side from the quadrant criteria (`axis`, `label`, `scored`, `criteria[]` with `name`, `label`, `status` `met`/`unmet`/`not_reported`, `display`/`score` when measured, `reason` otherwise; offline, evidence-less or unscored hives are `not_reported`, never `unmet`; [#12463](https://github.com/hivecommons/hive/issues/12463)). Every rate is `{n, rate, lo, hi}` with a 95% Wilson interval; `rate`/`lo`/`hi` are null when `n` < 10. Window selection ([RFC #12062](https://github.com/hivecommons/hive/issues/12062)): `?hours=24|168|720` pools each hive's matching heartbeat `windows` block instead of its 90-day block (any other or absent `hours` → 90 days); `?from=YYYY-MM-DD|RFC3339[&to=…]` (date-only `to` is inclusive, `to` defaults to now, `to` ≥ `from`, span ≤ 366 days, else `400`) is served from the smallest reported window that reaches back to `from` and flagged `window.approximate`. The response carries `window` (`hours`, `key`, `label`, `from`, `to`, `approximate`, `coverage_available` — `record_coverage` is only computed for the 90-day window because `prs_merged_90d` is a 90-day count), `window_unreported` and per-hive `window_unreported` for hives whose spoke predates per-window reporting. `?hive=<id>[,<id>…]` (repeatable) and `?level=<n>` restrict the registry server-side to those hives / that ACMM level before pooling. Hub admins open it from the Fleet quadrant card or its **🔬 Evidence** button ([#12117](https://github.com/hivecommons/hive/issues/12117)), pick a window (24h / 7d / 30d / 90d / custom), filter it by hive and ACMM level and read each section's ⓘ explainer; the per-hive author-kind revert counts behind the *Revert rate by author kind* panel are `hives[].counts.by_author_kind` ([#12326](https://github.com/hivecommons/hive/issues/12326)). Never consulted by merge decisions | `pkg/hub/evidence.go` |
| `GET` | `/api/hub/evidence/report` | Hub admin | Plain-language report of the hub evidence view ([#12456](https://github.com/hivecommons/hive/issues/12456)), rendered server-side from the same `EvidenceView` as `/api/hub/evidence` so every figure reconciles with the modal; non-admins get `403`. Same `hours=` / `from=` / `to=` window and `hive=` / `level=` filter parameters. `format=md` (default, `text/markdown`) or `format=html` (standalone page, inline CSS, no scripts or external assets, hive names escaped); any other value → `400`. `download=1` sets `Content-Disposition: attachment; filename="hive-evidence-<hive|fleet>-<from>-<to>.md|html"`, otherwise inline. Sections: Summary (the generated findings), What we measured and why, The numbers, How to read these, What is not reported yet and why, Grade per section, footer link to `review-evidence.md`. `Cache-Control: no-store`. Read-only; never consulted by merge decisions | `pkg/hub/evidence_report.go` |
| `GET` | `/api/hub/activity` | Signed-in user | Read-only hub-wide activity view ([#15951](https://github.com/hivecommons/hive/issues/15951), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)) merged from each spoke's heartbeat `activity` digest, held in hub memory only. Authorization is per user and per hive before aggregation: hub admins see every registered hive; everyone else only hives they own or hold an unexpired grant for; anonymous → `401`. Returns `hives[]` (`hive_id`, `name`, `status` `ok`/`stale`/`not_reporting`/`missing`, `reporting`, `stale` once the block is older than two heartbeats, `last_heartbeat`, `received_at`, `generated_at`, `totals` — `items`, `by_stage`, `by_modifier`, counting private and truncated items too — `truncated` and `events_dropped`), `items[]` (`hive_id`, `repo`, `n`, `kind`, `title`, `author_kind`, `stage`, `stage_n`, `since`, `mods`, `private`) ordered needs-human/needs-decision, stalled, furthest stage, oldest, a response-level `truncated` (cap 2000), and `events[]` ([#15964](https://github.com/hivecommons/hive/issues/15964): `hive_id`, `received_at`, `seq`, `type` `opened`/`stage`/`merged`, `repo`, `n`, `kind`, `title`, `from`, `stage`, `at`, `private`), oldest first, from a fleet-wide in-memory ring of at most 1,000 events, none held longer than 24 hours (ageing out is not counted in `events_dropped`; when full, the oldest event of the hive holding the most events is dropped, counted in that hive's `events_dropped`, so one hive cannot evict the others' events). Events are filtered per user and per hive exactly like items, before aggregation, so an event for a hive the viewer cannot see is never delivered; `mod`/`author_kind` filters keep only events whose item is still on the hive's board. A spoke block carries at most 200 events; drops are disclosed per hive as `events_dropped`. New events change the `ETag`. Each digest carries at most 100 items by default and never more than the 250-item hub ceiling; private-repository items appear only when the spoke opts in. Filters: `hive`, `repo`, `stage`, `mod`, `author_kind`, `q` (title substring or `#<n>`), each ≤ 200 characters (else `400`). `ETag` + `If-None-Match` → `304`; `Cache-Control: private, no-cache`, `Vary: Cookie, Authorization`. No actions | `pkg/hub/activity.go` |
| `GET` | `/api/hub/activity/public` | Public | Public-safe activity view ([#15966](https://github.com/hivecommons/hive/issues/15966)): the `/api/hub/activity` shape for anyone, never reading a cookie, token or `Authorization` header (credentials do not change the response). Only hives the registry lists as public on github.com, and only items and events not marked `private`; `totals`, per-hive `truncated` and `events_dropped`, hive owners and per-user grants are omitted. Same filters (`400` on an invalid one); `ETag` + `If-None-Match` → `304`; `Cache-Control: no-cache` | `pkg/hub/activity_public.go` |
| `GET` | `/api/hub/version` | Hub handler-specific | Hub Version | `pkg/hub/server.go:1731` |
| `DELETE` | `/api/hub/registry/{id}` | Hub handler-specific | Registry Delete | `pkg/hub/server.go:1741` |
| `POST` | `/api/contribute/register` | Hub handler-specific | Contribute Proxy | `pkg/hub/server.go:1742` |
Expand Down
30 changes: 27 additions & 3 deletions src/docs/hub-fleet-activity.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,12 +128,35 @@ The playlist follows the spoke's rules:

The spoke-only wall options `density=tv` and `shift=1` are ignored here.

## Public-safe view

`https://<hub>/activity/public` is the same board served to anyone, without a
session ([#15966](https://github.com/hivecommons/hive/issues/15966)). It is the
source of the `twitch.tv/hivecommonsfleet` broadcast
([Streaming the Activity Monitor](streaming-the-activity-monitor.md#the-hivecommonsfleet-broadcast)).
On that path the page polls `GET /api/hub/activity/public` with
`credentials: 'omit'`, and the endpoint never reads a cookie, token or
`Authorization` header, so a signed-in browser or an admin gets the same rows
as an anonymous visitor.

The view is filtered on the hub before it is built:

- Only hives the registry lists as **public** (the flag the public registry
and leaderboard use) on public github.com. A hive with no public flag, or
on a GitHub Enterprise host, is left out.
- Only items and events the spoke marked public. A spoke marks a repository
private unless it knows it is public, so unknown visibility is left out.
- No `totals`, digest `truncated` or `events_dropped`, since those can count
private items, and no hive owner.
- No per-user grants: your own access never widens it.

## What the page does not do

- It has no action menus. The hub is visibility-only: act on an item on
GitHub, or from the hive's own tracker.
- It is not a broadcast source. Display mode only changes how the signed-in
page looks; the page still needs a hub session and shows only your hives.
- `/activity` is not a broadcast source. Display mode only changes how the
signed-in page looks; the page still needs a hub session and shows only
your hives. Broadcast only the [public-safe view](#public-safe-view).

## Security

Expand All @@ -146,7 +169,8 @@ The spoke-only wall options `density=tv` and `shift=1` are ignored here.
- The page, its script and the shared row-presentation and view assets are revalidated
on every load (`Cache-Control: no-cache` with a content ETag), so a hub
upgrade is picked up on the next visit.
- `/activity` is marked `noindex` and is disallowed in `robots.txt`.
- `/activity` (including `/activity/public`) is marked `noindex` and is
disallowed in `robots.txt`.

## For operators

Expand Down
45 changes: 34 additions & 11 deletions src/docs/streaming-the-activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -292,13 +292,37 @@ It reuses the same `hive-stream` image. Its ConfigMap sets
holds the `CHANGE-ME` placeholder; and `TWITCH_STREAM_KEY` is installed (a
local dry run with `STREAM_OUTPUT=null` or an absolute local `*.flv` path
needs no key; a URL such as `rtmp://…/x.flv` or any other raw
`STREAM_OUTPUT` is refused). Shipped defaults fail every one of
these, and the Deployment is at `replicas: 0` on top.
`STREAM_OUTPUT` is refused). Shipped defaults fail the enable,
acknowledgement and stream-key checks, and the Deployment is at
`replicas: 0` on top.
- **The auth proxy runs anonymous.** It refuses to start with a token, strips
any `Authorization` or `Cookie` header the browser sends and drops
`Set-Cookie` from responses, so no session can form. The kiosk sees exactly
what an anonymous visitor of the hub sees, and nothing else.

### The public-safe hub view

The source is the hub's anonymous public-safe Fleet activity view,
`/activity/public?kiosk=1` (`DASHBOARD_PATH` in `fleet/configmap.yaml`). It is
a separate route from the signed-in `/activity` page and polls its own
endpoint, `GET /api/hub/activity/public`, which needs no login and ignores any
cookie or token it is sent. The hub filters the data before it builds the
view, so private rows never reach the page:

- **Shown:** open issues and pull requests in public repositories of hives the
registry lists as public on github.com — number, title, stage, modifiers,
author kind — plus their public stage hops, opens and merges, each hive's
name and report freshness.
- **Omitted:** private-repository items and events (and items whose
visibility the spoke does not know), hives not listed as public or on a
GitHub Enterprise host, per-hive totals, truncation and dropped-event counts
(they can count private items), hive owners, and any per-user access grant.

A hub test (`TestActivityPublic_OmitsPrivateRowsByConstruction`) checks that a
private row is absent from this view whether the request is anonymous or
carries an admin's session. See also
[Hub Fleet activity page](hub-fleet-activity.md#public-safe-view).

### Dashboard authentication does not protect Twitch output

A Twitch stream is public. Anything painted in the kiosk is visible to anyone,
Expand Down Expand Up @@ -333,15 +357,14 @@ acknowledgement cannot cover new content.
### Enabling it (owner only)

Nothing below is done by this repository or by the hive; it is the owner's
decision on #15861. Status as of this change: the channel is provisioned; the
stream key is **not** installed and the public-safe hub view does **not** yet
exist (it follows the Fleet activity page,
[#15965](https://github.com/hivecommons/hive/issues/15965)).

1. **Source.** Confirm a hub route renders the public-safe view anonymously
and meets the policy above, then set `DASHBOARD_PATH` in
`fleet/configmap.yaml` (e.g. with `?kiosk=1`). Open it in a private
browser window first: what you see there is what Twitch will show.
decision on #15861. Status as of this change: the channel is provisioned and
the [public-safe hub view](#the-public-safe-hub-view) exists; the stream key
is **not** installed and the broadcast is **not** enabled.

1. **Source.** `DASHBOARD_PATH` already points at
`/activity/public?kiosk=1`. Open `https://hive.hivecommons.dev/activity/public`
in a private browser window and confirm it meets the policy above: what
you see there is what Twitch will show.
2. **Stream key.** In the `hivecommonsfleet` Creator Dashboard, copy the
Primary Stream key and install it without echoing it or writing it to a
file, a commit or an issue comment:
Expand Down
32 changes: 22 additions & 10 deletions src/pkg/hub/activity.go
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,9 @@ type activityHive struct {
Owner string
LastHeartbeat string
Missing bool
// Public is set only for a registry-public hive on public GitHub; only
// the public-safe view (activity_public.go) reads it.
Public bool
}

// visibleActivityHives returns the hives username may see, applying the
Expand Down Expand Up @@ -359,16 +362,7 @@ func (s *HubServer) handleHubActivity(w http.ResponseWriter, r *http.Request) {
return
}
now := time.Now().UTC()
s.mu.RLock()
registry := make([]activityHive, 0, len(s.registry.Hives))
for _, h := range s.registry.Hives {
name := h.ProjectName
if name == "" {
name = h.Name
}
registry = append(registry, activityHive{ID: h.ID, Name: name, Owner: h.Owner, LastHeartbeat: h.LastHeartbeat})
}
s.mu.RUnlock()
registry := s.activityRegistry()

hives := visibleActivityHives(username, loadSaaSUser(username), registry, now)
ids := make([]string, len(hives))
Expand Down Expand Up @@ -398,6 +392,24 @@ func (s *HubServer) handleHubActivity(w http.ResponseWriter, r *http.Request) {
_, _ = w.Write(body)
}

// activityRegistry copies the registry slice the activity views need.
func (s *HubServer) activityRegistry() []activityHive {
s.mu.RLock()
defer s.mu.RUnlock()
registry := make([]activityHive, 0, len(s.registry.Hives))
for _, h := range s.registry.Hives {
name := h.ProjectName
if name == "" {
name = h.Name
}
registry = append(registry, activityHive{
ID: h.ID, Name: name, Owner: h.Owner, LastHeartbeat: h.LastHeartbeat,
Public: h.IsPublic && sameGitHubHost(h.GitHubHost, publicGitHubHost),
})
}
return registry
}

// activityETagMatches is the RFC 9110 weak comparison of If-None-Match.
func activityETagMatches(header, etag string) bool {
want := strings.TrimPrefix(etag, "W/")
Expand Down
Loading
Loading