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-19160-hub-customer-consent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hub operators can enable a profile-sharing page where people enter their own profile details and grant or withdraw consent per hive and field. Scale Controls shows the effective setting. Off by default; no profile data is sent to hives in this phase ([#19160](https://github.com/hivecommons/hive/issues/19160)).
196 changes: 98 additions & 98 deletions src/docs/api-reference/hub-saas.md

Large diffs are not rendered by default.

10 changes: 5 additions & 5 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,13 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/openrouter/models` | Hub auth | Hub Open Router Models | `pkg/hub/openrouter.go:28` |
| `GET` | `/api/openrouter/credit` | Hub auth | Hub Open Router Credit | `pkg/hub/openrouter.go:29` |
| `GET` | `/openrouter/callback` | Hub handler-specific | Hub Open Router Callback | `pkg/hub/openrouter.go:30` |
| `GET` | `/dashboard` | Hub handler-specific | Dashboard | `pkg/hub/saas.go:369` |
| `GET` | `/access-denied` | Hub handler-specific | Access Denied | `pkg/hub/saas.go:370` |
| `GET` | `/api/hub/clusters` | Hub auth | List Clusters | `pkg/hub/saas.go:531` |
| `GET` | `/api/hub/image-pulls` | Hub auth | Per-Release Image Pull Series | `pkg/hub/saas.go:377` |
| `GET` | `/dashboard` | Hub handler-specific | Dashboard | `pkg/hub/saas.go:361` |
| `GET` | `/access-denied` | Hub handler-specific | Access Denied | `pkg/hub/saas.go:362` |
| `GET` | `/api/hub/clusters` | Hub auth | List Clusters | `pkg/hub/saas.go:520` |
| `GET` | `/api/hub/image-pulls` | Hub auth | Per-Release Image Pull Series | `pkg/hub/saas.go:369` |
| `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` | `/api/reach` | Hub admin | PR Reach Report (?pr=NNN or ?recent=K) | `pkg/hub/saas.go:511` |
| `GET` | `/fleet` | Hub handler-specific | My-Hives Fleet Page (static; data via `/api/saas/my-hives`) | `pkg/hub/server.go:1829` |
| `GET` | `/my-hives` | Hub handler-specific | 301 redirect to `/fleet` (query preserved) | `pkg/hub/server.go:1830` |
| `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` |
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 @@ -93,6 +93,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_CUSTOMERS_SHARE_ENABLED` | No | off | Enables the hub's signed-in profile-sharing page and API for per-person, per-hive consent. Accepts `1/true/yes/on`. This phase sends no profile data to hives. See [Customer profile sharing](hub-deployment.md#customer-profile-sharing). |
| `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_MAIL_MAX_BODY_BYTES` | No | `50331648` | Largest delivery `POST /api/mail/inbound` accepts from a `hive-mx` that sends routing headers (48 MiB, this route only; [#18564](https://github.com/hivecommons/hive/issues/18564)). Without routing headers the cap stays 8 MiB. |
| `HIVE_HUB_MAIL_CHUNK_BYTES` | No | `786432` | Piece size when the hub relays a large mail-in delivery to the spoke (768 KiB, under the 1 MiB ingress default); clamped to 64 KiB to 8 MiB. |
Expand Down
14 changes: 14 additions & 0 deletions src/docs/hub-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,20 @@ env:

Without `HIVE_HUB_SECRET`, a protected hub returns `401 unauthorized`, the spoke logs `hub heartbeat rejected status=401`, and the hub shows the hive offline. This matches the gotcha in `manual-provisioning.md`.

### Customer profile sharing

`HIVE_HUB_CUSTOMERS_SHARE_ENABLED` is off by default. Set it to `1`, `true`,
`yes`, or `on` in the hub environment to enable **Profile sharing** in Fleet
and on hive cards where the signed-in person holds a grant. The hub dashboard's
operator settings show the effective state. With the switch off, the page and
its API return `404`; stored choices are not deleted.

People can enter or clear their real name, organization, and country, then
confirm or withdraw their own selections separately for each hive. Legacy,
administrator-entered, and inferred values are not eligible for sharing. A
material disclosure change requires reconfirmation. This phase records consent
on the hub only and does not send any profile fields to hives.

### Reserved `byo-` hive IDs (credential fence)

Hive IDs that start with `byo-` are reserved for hives that their owners run and register themselves ([#18060](https://github.com/hivecommons/hive/issues/18060)). A hub lists such a hive as directory metadata only, so its heartbeat response never carries hub-held credentials or management actions, whatever key the spoke authenticated with. The hub withholds these fields: the GitHub App config (including cluster, secondary and webhook relay keys), the pending gateway, the claimed project config, the cluster ID, the authorized-user list, visibility, upgrade and branch-switch instructions, the upgrade announcement and policy, spoke restarts, agent-restart resets, fleet-breaker instructions, and self-experiment flags. Display-only data such as admin banners still flows. When the fence withholds a field, the hub logs `heartbeat: credential fence withheld fields from self-service hive` with the field names, never the values. Do not give an operator-provisioned hive a `byo-` ID.
Expand Down
24 changes: 23 additions & 1 deletion src/pkg/hub/assets/dashboard.html
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,10 @@
.cluster-health-message.info { color: var(--muted); background: var(--surface); border: 1px solid var(--border); }
.cluster-health-message.warn { color: var(--amber); background: var(--surface); border: 1px solid var(--amber); }

.customers-share-setting { padding: var(--sp-5); margin-bottom: var(--sp-6); border: 1px solid var(--border); border-radius: var(--r); background: var(--surface); font-size: var(--fs-base); }
.customers-share-setting h3 { font-size: var(--fs-base); margin-bottom: var(--sp-2); }
.customers-share-setting p:last-child { font-size: var(--fs-sm); color: var(--muted); margin-top: var(--sp-2); }

/* ── Hive search + facets ──
The facet panel is a CLICK-TOGGLED left tray, collapsed by default so the
dashboard is uncluttered until the operator asks for filters. Collapsed it
Expand Down Expand Up @@ -835,6 +839,7 @@
<p class="section-label">Dashboard</p>
<h1>My Hives</h1>
<p class="subtitle">Hive instances you own or have access to</p>
<p id="profile-share-link" hidden><a href="/profile-share">Profile sharing</a></p>
<p style="margin-top:var(--sp-4);padding:8px 14px;border:1px solid var(--line);border-radius:8px;background:color-mix(in srgb,var(--hub-dashboard-accent) 8%,transparent);font-size:0.85rem">👋 New to Hive? Read the <a href="https://docs.kubestellar.io/docs/hive/getting-started" target="_blank" rel="noopener" style="color:var(--amber);font-weight:700">Getting Started Guide</a> before diving in.</p>
<p id="benchmarks-pointer" class="benchmarks-pointer">📊 See how models perform across the fleet &mdash; merge rate, CI first-try and estimated cost per PR, from real hive output. <a href="https://hivecommons.dev/benchmarks/" target="_blank" rel="noopener">Open the benchmarks ↗</a></p>
<p id="latest-image-sha" style="font-size:0.7rem;color:var(--muted);margin-top:var(--sp-2)"></p>
Expand Down Expand Up @@ -1086,6 +1091,11 @@ <h2 style="font-size:1.3rem;color:var(--hub-dashboard-accent);margin:var(--sp-0)
(worker-count reductions apply on the next hub restart).
</div>
<div id="scale-globals" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:var(--sp-5);margin-bottom:var(--sp-6)"></div>
<div class="customers-share-setting">
<h3>Customers profile sharing</h3>
<p>In force: <strong id="customers-share-effective">Unknown</strong> · Default: Off</p>
<p>Set <code>HIVE_HUB_CUSTOMERS_SHARE_ENABLED</code> on the hub to enable the personal profile and consent page. The environment is authoritative; this setting cannot be changed here. No profile details are sent to hives in this release.</p>
</div>
<div style="font-size:0.85rem;color:var(--text);margin:var(--sp-5) var(--sp-0) var(--sp-4);font-weight:600">Per-cluster limits</div>
<div class="table-wrap"><table style="width:100%;font-size:0.85rem"><thead><tr>
<th style="text-align:left">Cluster</th><th style="text-align:right">Hives</th><th style="text-align:right">Pool avail</th>
Expand Down Expand Up @@ -4717,6 +4727,7 @@ <h2 style="font-size:1.3rem;color:var(--hub-dashboard-accent);margin:var(--sp-0)
var data = await resp.json();
applyImpersonationBanner(data);
if (data.authenticated) {
_personalProfileLinksAllowed = !data.impersonating;
_isAdmin = !!data.hub_admin;
_isRootAdmin = !!data.root_admin;
/* The signed-in login is the ONE piece of viewer identity the hive
Expand Down Expand Up @@ -4759,6 +4770,9 @@ <h2 style="font-size:1.3rem;color:var(--hub-dashboard-accent);margin:var(--sp-0)
}

var _userQuota = 0, _userUsed = 0, _isAdmin = false, _isRootAdmin = false;
var _personalProfileLinksAllowed = false;
var _profileShareHiveIDs = new Set();
var _profileShareHiveSignature = '';
/* Lowercased login of the signed-in viewer, set by loadUser(). Empty until
that resolves, and empty is safe: hiveAccessAvatars() then simply omits
nobody, which is a cosmetic over-render for one paint rather than a
Expand Down Expand Up @@ -7890,6 +7904,11 @@ <h2 style="font-size:1.3rem;color:var(--hub-dashboard-accent);margin:var(--sp-0)
_userUsed = data.saas_used || 0;
_allDashHives = data.hives || [];
_hiveRegistry = data.hives || [];
var showProfileShare = _personalProfileLinksAllowed && data.customersShareEnabled === true;
var profileShareIDs = showProfileShare ? (data.profileShareHiveIDs || []) : [];
document.getElementById('profile-share-link').hidden = !showProfileShare;
_profileShareHiveIDs = new Set(profileShareIDs);
_profileShareHiveSignature = JSON.stringify(profileShareIDs);
/* The fleet reference polygon behind every kite. Captured here rather
than derived in the browser: it is the average over the SAME
population the server scored, and recomputing it client-side from
Expand Down Expand Up @@ -8996,7 +9015,7 @@ <h2 style="font-size:1.3rem;color:var(--hub-dashboard-accent);margin:var(--sp-0)
'|' + JSON.stringify(_dashFacetCollapsed) + '|' + JSON.stringify(_dashSectionCollapsed) +
'|' + _dashGroupBy + '|' + JSON.stringify(_dashGroupCollapsed) +
'|' + _dashActiveView + '|' + _dashDefaultView + '|' + JSON.stringify(_dashSavedViews) +
'|' + _dashFacetTrayOpen;
'|' + _dashFacetTrayOpen + '|' + _profileShareHiveSignature;
if (!force && sig === _lastHivesJSON) return;
_lastHivesJSON = sig;
/* Status/facet filters describe ASSIGNED hives only. An unassigned
Expand Down Expand Up @@ -9166,6 +9185,7 @@ <h2 style="font-size:1.3rem;color:var(--hub-dashboard-accent);margin:var(--sp-0)
var snapUrl = snapshotLink(h);
var apiUrl = apiLink(h);
var menuItems = [];
if (_profileShareHiveIDs.has(h.id)) menuItems.push('<a href="/profile-share?hive=' + encodeURIComponent(h.id) + '" class="hive-menu-item">Profile sharing</a>');
if (_isAdmin && h.provStatus === 'available' && !h.assigning) menuItems.push('<div onclick="openAssignModal(\'' + esc(h.id) + '\')" class="hive-menu-item" style="color:#3fb950;font-weight:600">Assign / Claim</div><div style="border-top:1px solid #30363d;margin:var(--sp-2) var(--sp-0)"></div>');
/* Reset assignment: escape hatch for a placeholder wedged at
assigned && !claim_delivered (assignedUnclaimed) — its spoke never
Expand Down Expand Up @@ -11660,6 +11680,8 @@ <h2 style="font-size:1.3rem;color:var(--hub-dashboard-accent);margin:var(--sp-0)
if (body) body.style.display = _scaleControlsCollapsed ? 'none' : '';
if (toggle) toggle.style.transform = _scaleControlsCollapsed ? '' : 'rotate(90deg)';
var eff = data.effective || {};
document.getElementById('customers-share-effective').textContent =
typeof eff.customers_share_enabled !== 'boolean' ? 'Unknown' : (eff.customers_share_enabled ? 'On' : 'Off');
document.getElementById('scale-controls-summary').textContent =
'wave ' + eff.upgrade_wave_size + ' · workers ' + eff.provision_workers +
' · per-cluster ' + eff.provision_per_cluster + ' · kubectl ' + eff.kubectl_per_cluster;
Expand Down
83 changes: 83 additions & 0 deletions src/pkg/hub/assets/profile-share.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex, nofollow">
<title>Profile sharing — Hive Hub</title>
<link rel="stylesheet" href="/tokens.css">
<link rel="stylesheet" href="/components.css">
<link rel="stylesheet" href="/static/profile-share.css">
<script src="/static/profile-share.js" defer></script>
</head>
<body data-text-version="{{CONSENT_TEXT_VERSION}}">
<header class="site-header">
<a href="/" class="brand">🐝 Hive</a>
<nav aria-label="Hub navigation">
<a href="/dashboard">My Hives</a>
<a href="/fleet">Fleet</a>
</nav>
</header>
<main>
<h1>Profile sharing</h1>
<p class="muted">Manage your own Hub details and choose what may be shared with each hive’s Customers area.</p>
<noscript><p>Enable JavaScript to manage your details and consent.</p></noscript>

<section aria-labelledby="details-heading">
<h2 id="details-heading">Your details</h2>
<p class="muted">Each field is saved separately. A value you didn’t enter yourself isn’t eligible for sharing unless you type and save it here. Clearing a value leaves that field empty; it does not change your selections for any hive.</p>
<p id="profile-status" class="status" role="status">Loading your details…</p>
<div id="profile-fields" class="profile-fields"></div>
</section>

<section aria-labelledby="hives-heading">
<h2 id="hives-heading">Hives</h2>
<div class="panel disclosure" id="sharing-disclosure">
<h3>What you’re agreeing to</h3>
<p><strong>No profile details are sent to any hive in this release.</strong> You can record your choices now for future syncs.</p>
<p>For each hive you choose, only the fields you select may be shared: your real name, organization, or country. Only non-empty values you entered about yourself are eligible. That hive’s owner and anyone with Customers access there can view and export the shared values. When a future sync matches you to a confirmed customer in that hive, the Hub learns about that customer relationship.</p>
<p>This feature never sends notes, Slack IDs, email, affiliation, provider-supplied profile details, or anything an administrator entered or the Hub inferred. Information already visible to hive owners through existing access lists is unaffected by these choices.</p>
<p>Withdrawal stops sharing immediately on the Hub. Once syncing is available, the hive removes the imported values at its next sync. Withdrawal cannot undo what someone already saw, copied, or exported.</p>
<p>Boxes always start unchecked; any previous selection is shown separately. Confirming replaces the entire selection for that hive. Leave nothing selected and use <strong>Withdraw consent</strong> to remove the entire selection.</p>
</div>
<p id="consents-status" class="status" role="status">Loading your hives…</p>
<div id="consent-hives" class="consent-hives"></div>
</section>
</main>
<footer class="muted">
&copy; Copyright Hive Commons Series of LF Projects, LLC<br>
For website terms of use, trademark policy and other project policies please see <a href="https://lfprojects.org/policies/">https://lfprojects.org/policies/</a>.
</footer>

<template id="profile-field-template">
<form class="panel detail" method="post" autocomplete="off">
<h3></h3>
<p class="current"></p>
<p class="muted source"></p>
<fieldset>
<label><span></span><input type="text" required></label>
<div class="actions">
<button class="hv-btn btn-primary" type="submit">Save</button>
<button class="hv-btn btn-outline clear" type="button">Clear saved value</button>
</div>
</fieldset>
<p class="status" role="status"></p>
</form>
</template>
<template id="consent-hive-template">
<form class="panel consent" method="post" autocomplete="off" aria-describedby="sharing-disclosure">
<h3 tabindex="-1"></h3>
<p class="muted saved-selection"></p>
<fieldset>
<legend>Choose fields for this hive</legend>
<div class="choices"></div>
</fieldset>
<div class="actions">
<button class="hv-btn btn-primary" type="submit">Confirm selection</button>
<button class="hv-btn btn-outline withdraw" type="button">Withdraw consent</button>
</div>
<p class="status" role="status"></p>
</form>
</template>
</body>
</html>
1 change: 1 addition & 0 deletions src/pkg/hub/background_pollers.go
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ func (s *HubServer) StartBackgroundPollers(ctx context.Context) <-chan struct{}
// Self-service (byo-) registrations past HIVE_HUB_SELFSERVICE_EXPIRY with
// no accepted heartbeat are revoked and dropped from the registry (#18146).
start(s.startSelfServiceExpirySweep)
start(s.startCustomerConsentSweep)
s.githubActivityMu.Lock()
s.githubActivityCtx = ctx
feed := s.githubActivityFeed
Expand Down
Loading
Loading