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-19180-ask-hub-backend.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Hub operators can enable an optional Ask AI help backend that answers docs questions server side through the Kapa.ai Chat API: per-person consent, credential-shaped questions refused, only allowlisted cited sources, per-person and hub-wide limits, a circuit breaker and content-free audit lines. Off by default and inert until a key file, project id and integration id are configured; no panel yet ([#19180](https://github.com/hivecommons/hive/issues/19180)).
5 changes: 5 additions & 0 deletions src/docs/api-reference/hub-saas.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,3 +111,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/saas/admin/key-generations` | Hub admin | Token-Crypto Key Generations | `pkg/hub/saas.go:489` |
| `POST` | `/api/saas/admin/rotate-master-key` | Hub admin | Rotate Token Master Key (double-call refused) | `pkg/hub/saas.go:490` |
| `GET` | `/api/saas/admin/advisory-diagnostics` | Hub admin | Fleet Advisory/App-State Diagnostics | `pkg/hub/saas.go:516` |
| `GET` | `/api/ask/status` | Hub auth | Browser session only (no bearer, no impersonation). Ask AI help status for the signed-in person: `enabled`, `text_version`, `disclosure`, `consented`, `docs_url`, `ai_label`. Registered only when `HIVE_ASK_ENABLED` is on and fully configured; otherwise `404`. Never returns the vendor key, project id or integration id. See [Ask AI help](../hub-deployment.md#ask-ai-help) | `pkg/hub/ask.go:123` |
| `PUT` | `/api/ask/consent` | Hub auth | Browser session only. Record the person's consent to the Ask disclosure: body `{text_version}`; `409` when the page showed an older text; `204` on success. One audit line, no text | `pkg/hub/ask.go:124` |
| `DELETE` | `/api/ask/consent` | Hub auth | Browser session only. Withdraw Ask consent; takes effect on the next request; `204` | `pkg/hub/ask.go:125` |
| `POST` | `/api/ask` | Hub auth | Browser session only. Ask a docs-help question: body `{question, section?, conversation?}` (`section` is an id from the closed list in `pkg/askai/sections.go`; `conversation` is the opaque handle from the previous answer). Always `200` with `{outcome, answer?, sources[]?, uncertain?, conversation?, retry_after_seconds?, message?, ai_generated, docs_url}`; `outcome` is one of `ok`, `no_cited_answer`, `refused_secret_shape`, `rate_limited`, `breaker_open`, `upstream_error`, `not_consented`, `invalid_question`. Only the question and the section label are sent to Kapa.ai | `pkg/hub/ask.go:126` |
| `GET` | `/api/ask/stats` | Hub admin | Ask cost view: counts by outcome, today's total against the daily budget, breaker state, effective limits. No per-person data | `pkg/hub/ask.go:127` |
68 changes: 34 additions & 34 deletions src/docs/api-reference/hub-server.md

Large diffs are not rendered by default.

14 changes: 14 additions & 0 deletions src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,20 @@ behavior. [Maintenance limitations](#keeping-this-reference-current) still apply
| `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_ASK_ENABLED` | No | off | Switches on Ask AI help ([#19177](https://github.com/hivecommons/hive/issues/19177)). Accepts `1/true/yes/on`. Inert until the Kapa values below are also set; a missing or unreadable value keeps it off with one warning that names no value. See [Ask AI help](hub-deployment.md#ask-ai-help). |
| `HIVE_ASK_MODE` | No | `off` | `off`, `direct` (this process calls Kapa.ai with its own key) or `hub` (a hosted hive uses the hub relay). The hub is always `direct` and ignores it. |
| `HIVE_ASK_KAPA_PROJECT_ID` | With Ask on in direct mode | none | Kapa.ai project id. Configuration only; never in the repo, never logged or returned by an API. |
| `HIVE_ASK_KAPA_INTEGRATION_ID` | With Ask on in direct mode | none | Kapa.ai HTTP API integration id. Configuration only; never logged or returned by an API. |
| `HIVE_ASK_KAPA_API_KEY_FILE` | With Ask on in direct mode | none | Path to the Kapa.ai API key file, under `/secrets` or `/data/secrets`, mounted from a Secret. A path elsewhere is never read. Secret. |
| `HIVE_ASK_SEND_SECTION_LABEL` | No | on | Whether the label of the dashboard section the person is in (from a closed list of our own ids) accompanies the question. |
| `HIVE_ASK_LIMIT_PERSON_PER_MINUTE` | No | `3` | Ask requests one person may make per minute. |
| `HIVE_ASK_LIMIT_PERSON_PER_HOUR` | No | `20` | Ask requests one person may make per hour. |
| `HIVE_ASK_LIMIT_HIVE_PER_HOUR` | No | `60` | Relayed Ask requests one hive may make per hour on the hub. |
| `HIVE_ASK_LIMIT_GLOBAL_PER_MINUTE` | No | `4` | Ask requests per minute across the whole process; capped at `10`, half the vendor's per-team limit of 20 a minute. |
| `HIVE_ASK_LIMIT_IN_FLIGHT` | No | `2` | Ask requests in flight at once across the process. |
| `HIVE_ASK_LIMIT_DAILY` | No | `500` | Ask requests per day across the process; when spent, the panel shows the docs link until the window resets. |
| `HIVE_ASK_RELAY_HIVES` | No | `hosted` | Hub only: which hives may use the Ask relay, `none` or `hosted` (`registered` is accepted and treated as `hosted` in this round). |
| `HIVE_ASK_RELAY_DISABLED_HIVES` | No | none | Hub only: comma-separated hive ids the Ask relay refuses. |
| `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
65 changes: 65 additions & 0 deletions src/docs/hub-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,71 @@ 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.

### Ask AI help

Ask AI help is an optional docs-help backend for the hub dashboard (design:
[Dashboard Ask AI help](design/dashboard-ask-ai-help.md)). It is off by
default. With it off, or switched on but missing a value, the hub registers no
Ask route, reads no key and sends nothing. The hub calls the Kapa.ai Chat API
itself, server side; the browser only ever talks to the hub, and no
third-party script or Content-Security-Policy change is involved.

To wire it once a Kapa API key exists:

1. In the Kapa project, create an HTTP API integration and an API key. Keep
both out of the repository.
2. Store the key in a Kubernetes Secret and mount it under one of the allowed
secret dirs (`/secrets` or `/data/secrets`), for example:

```sh
kubectl -n <hub-namespace> create secret generic hive-ask-kapa \
--from-file=api-key=<path-to-key-file>
```

and add a volume plus `volumeMounts: [{name: hive-ask-kapa, mountPath: /secrets/kapa, readOnly: true}]`
to the hub Deployment.
3. Set the hub environment:

```yaml
env:
- name: HIVE_ASK_ENABLED
value: "true"
- name: HIVE_ASK_KAPA_PROJECT_ID
value: <project id>
- name: HIVE_ASK_KAPA_INTEGRATION_ID
value: <integration id>
- name: HIVE_ASK_KAPA_API_KEY_FILE
value: /secrets/kapa/api-key
```

The project id and integration id may also come from the same Secret
through `valueFrom.secretKeyRef`. There is no env var that holds the key
itself.
4. Restart the hub. It logs `ask: enabled` with the effective limits, or one
`ask: requested but staying off` line with the reason. Neither line, nor any
API response, carries the key, the project id or the integration id.

What leaves the hub per question: the question text (refused, not sent, when
it looks like a password, token or key), the label of the dashboard section
from a closed list of ids in `pkg/askai/sections.go` (set
`HIVE_ASK_SEND_SECTION_LABEL=false` to drop it), the integration id and, for a
follow-up, the vendor's thread id. No login, email, page content, URL, hive or
repo name is sent. Each person confirms a disclosure before their first
question and can withdraw; the record lives under `/data/saas/ask-consents/`
and is deleted with the user. Answers without an allowlisted source
(`docs.hivecommons.dev` or the GitHub docs path under `hivecommons/hive`) are
shown as "no cited answer" with a docs link.

Limits (env overrides in [Environment variables](env-vars.md)): per person 3 a
minute, 20 an hour and one in flight; hub-wide 4 a minute (a fifth of the
vendor's 20 a minute per-team limit, and never more than half of it), 2 in
flight and 500 a day. A vendor `429` backs every caller off for its
`Retry-After`; three upstream failures in a row open a circuit breaker for five
minutes. Audit lines (`audit: ask request`, `audit: ask consent grant`,
`audit: ask consent withdraw`, `audit: ask breaker opened`, `audit: ask daily
budget spent`) carry outcomes and counts, never text. Hub admins can read the
counters at `GET /api/ask/stats`.

### 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
1 change: 1 addition & 0 deletions src/docs/telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Hive sends a small number of operational signals outside the running hive only t
| Build-containment lookup | A commit SHA (the hive's running commit and the commit being asked about) or a PR number, sent as part of a GitHub REST `compare` or `pulls` request. Only when an operator runs a lookup (`GET /api/saas/build-contains` on the hub, `GET /api/version/contains` on a hive). No hive identifier, org, repo name or user is in the request. | `api.github.com`, the public `hivecommons/hive` repository, using the hub's read-only GitHub identity or the hive's own configured GitHub client. The answer is shown to the caller only. | On demand only; no background polling. A hive with no GitHub client answers `unknown` and sends nothing. | None stored; compare answers are cached in memory, for the life of the process. | Do not run the lookup; there is no setting because nothing is sent otherwise. | `src/pkg/buildcontains/buildcontains.go`; `src/pkg/hub/build_contains.go`; `src/pkg/dashboard/api_version_contains.go`. |
| NPS prompt | Score 1-4, optional free text, hive ID, and dashboard version. The signed-in username is used only locally for rate limiting and is not sent. | Hub `POST /api/nps/ingest`, or an explicitly configured NPS relay for standalone hives; only hub admins can read stored responses. | Hosted spokes default on; self-hosted/federated/standalone default off. Standalone relay requires explicit `hub.nps_enabled`/`HIVE_NPS_ENABLED` and `hub.nps_relay_url`/`HIVE_NPS_RELAY_URL`. | Hub store keeps at most 1,000 responses per hive and 10,000 total, oldest dropped first. | `hub.nps_enabled: false` or `HIVE_NPS_ENABLED=false`; leave relay URL unset. | `src/docs/nps.md`; `src/docs/env-vars.md`; `src/pkg/dashboard/nps.go`; `src/pkg/hub/nps.go`. |
| Hosted hub web analytics | GA4 page/event data from hub-hosted pages, including custom hub events such as hive creation/deletion. Existing event code includes hive IDs and creation inputs such as org, primary repo, ACMM level, and cluster ID. | Google Analytics via `www.googletagmanager.com`, property `G-4707R797K3`. | Loaded by hosted hub static HTML pages. This is website analytics, not spoke software telemetry, but it still needs privacy review because custom events may include project identifiers. | Google Analytics retention is controlled in the GA property, not in this repository. | Browser tracking protections or removing the hosted hub GA script; there is no repository config flag. | `src/pkg/hub/assets/dashboard.html`; `src/pkg/hub/saas_pages.go`; `src/pkg/hub/static/*.html` pages such as `reading.html` and `cncf-reference-architecture.html`. |
| Ask AI help (optional) | The question a signed-in person typed, after a credential-shape check that refuses rather than sends; the label of the dashboard section they are in, from a closed list of our own ids; the Kapa.ai integration id; and, for a follow-up, the vendor thread id. No login, email, page content, URL, hive, repo or agent name. | Kapa.ai Chat API (`api.kapa.ai`), called server side by the hub; the project's Kapa administrators can read questions in Kapa analytics. | Off by default (`HIVE_ASK_ENABLED`); inert until a key file, project id and integration id are configured; each person confirms a disclosure before their first question and can withdraw. | Kapa keeps conversations for the duration of the service; Hive stores no question or answer text, only the per-person consent record. | Leave `HIVE_ASK_ENABLED` unset, or withdraw consent per person. | `src/pkg/askai/service.go`; `src/pkg/askai/kapa.go`; `src/pkg/hub/ask.go`; [design](design/dashboard-ask-ai-help.md). |
| Crash/error reporting | No Sentry/PostHog/Segment/Plausible crash reporter was found in `src` during the onboarding audit. Errors are logged locally; selected log-safe health/error strings can appear in hub heartbeats as described above. | Local logs and, for selected operational state, the configured hub. | No third-party crash reporting by default. | Local log/PVC retention is deployment-specific. | N/A for third-party crash reporting; disable hub link for heartbeat-carried operational errors. | Audit search: `telemetry|analytics|metrics push|phone.?home|posthog|segment|plausible|gtag|googletagmanager|sentry` over Go/HTML/JS/Markdown. |

## Linux Foundation telemetry-policy status
Expand Down
103 changes: 103 additions & 0 deletions src/pkg/askai/breaker.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
package askai

import (
"sync"
"time"
)

const (
// DefaultBreakerFailures consecutive upstream failures open the breaker.
DefaultBreakerFailures = 3
// DefaultBreakerCooldown is how long an open breaker short-circuits to
// the docs link before one trial call is let through.
DefaultBreakerCooldown = 5 * time.Minute
)

// breakerEvent reports a state change for the audit line.
type breakerEvent int

const (
breakerNoChange breakerEvent = iota
breakerOpened
breakerClosed
)

// breaker is a consecutive-failure circuit breaker with a half-open trial.
type breaker struct {
mu sync.Mutex
threshold int
cooldown time.Duration
failures int
openUntil time.Time
open bool
trial bool
}

func newBreaker(threshold int, cooldown time.Duration) *breaker {
if threshold <= 0 {
threshold = DefaultBreakerFailures
}
if cooldown <= 0 {
cooldown = DefaultBreakerCooldown
}
return &breaker{threshold: threshold, cooldown: cooldown}
}

// allow reports whether a call may go out, and how long to wait if not.
// After the cool-down exactly one trial call is admitted at a time.
func (b *breaker) allow(now time.Time) (bool, time.Duration) {
b.mu.Lock()
defer b.mu.Unlock()
if !b.open {
return true, 0
}
if now.Before(b.openUntil) {
return false, b.openUntil.Sub(now)
}
if b.trial {
return false, time.Second
}
b.trial = true
return true, 0
}

// cancelTrial returns an admitted trial slot that never reached the vendor
// (for example, the request was rate limited after allow).
func (b *breaker) cancelTrial() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cancelTrial clears trial unconditionally, so a request that never took the trial slot can free another request's half-open trial. Return a 'took trial' bool from allow and cancel only then.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cancelTrial clears trial without checking that this caller holds the slot. When the breaker is closed, or a different caller holds the trial, a rate-limited request calling it lets a second trial through. Suggested fix: have allow return whether it took the trial slot, and call cancelTrial only in that case. cancelTrial can also check b.open as a minimum.

b.mu.Lock()
defer b.mu.Unlock()
b.trial = false
}

func (b *breaker) success() breakerEvent {
b.mu.Lock()
defer b.mu.Unlock()
wasOpen := b.open
b.failures, b.open, b.trial = 0, false, false
if wasOpen {
return breakerClosed
}
return breakerNoChange
}

func (b *breaker) failure(now time.Time) breakerEvent {
b.mu.Lock()
defer b.mu.Unlock()
b.failures++
if b.open {
// A failed trial re-opens for another cool-down.
b.openUntil, b.trial = now.Add(b.cooldown), false
return breakerNoChange
}
if b.failures >= b.threshold {
b.open, b.openUntil, b.trial = true, now.Add(b.cooldown), false
return breakerOpened
}
return breakerNoChange
}

func (b *breaker) isOpen() bool {
b.mu.Lock()
defer b.mu.Unlock()
return b.open
}
Loading
Loading