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-19164-hub-consent-disclosure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Hub: final profile sharing disclosure, a "what was sent" view and admin consent counts** ([#19164](https://github.com/hivecommons/hive/issues/19164)). The Profile sharing page now states what is sent and to whom, that the hive owner and anyone with Customers access on that hive can see and export it, what is never sent, that withdrawal is immediate on the hub and reaches the hive at its next sync, and that the hub cannot recall an exported copy. The disclosure version moves to 2, so a consent given under the earlier "nothing is sent yet" text shares nothing until the person confirms again. Each hive card shows what was last sent and when, from the delivery stamps. Hub admins see consent counts per hive only, in Scale Controls and at `GET /api/saas/admin/profile-share/counts`, with no person, field choice or value. The Customers, telemetry and hub deployment docs now describe the opt-in hub import instead of saying nothing is read from the hub.
2 changes: 2 additions & 0 deletions src/docs/api-reference/hub-saas.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/saas/hives/{id}/access-log` | Hub auth | Permission-Change Audit Log | `pkg/hub/saas.go:449` |
| `GET` | `/api/saas/admin/scale-settings` | Hub admin | Placeholder Pool Scale Settings Get | `pkg/hub/saas.go:466` |
| `POST` | `/api/saas/admin/scale-settings` | Hub admin | Placeholder Pool Scale Settings Set | `pkg/hub/saas.go:467` |
| `GET` | `/api/saas/admin/profile-share/counts` | Hub admin | Customers profile sharing: consent counts per hive (`hive_id`, `name`, `consents`, `awaiting_reconfirmation`). No person, field choice or value. `404` while `HIVE_HUB_CUSTOMERS_SHARE_ENABLED` is off | `pkg/hub/customer_consent.go` |
| `GET` | `/api/saas/admin/user-countries` | Hub admin | User Country Rollup | `pkg/hub/saas.go:476` |
| `GET` | `/api/saas/admin/auth-rollout` | Hub admin | Auth Rollout Readiness Summary | `pkg/hub/saas.go:481` |
| `GET` | `/api/saas/admin/notifications` | Hub admin | Hub Notifications Get | `pkg/hub/saas.go:482` |
Expand All @@ -104,6 +105,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `GET` | `/api/saas/hives/{id}/access-log` | Hub auth | Permission-Change Audit Log | `pkg/hub/saas.go:449` |
| `GET` | `/api/saas/admin/scale-settings` | Hub admin | Placeholder Pool Scale Settings Get | `pkg/hub/saas.go:466` |
| `POST` | `/api/saas/admin/scale-settings` | Hub admin | Placeholder Pool Scale Settings Set | `pkg/hub/saas.go:467` |
| `GET` | `/api/saas/admin/profile-share/counts` | Hub admin | Customers profile sharing: consent counts per hive (`hive_id`, `name`, `consents`, `awaiting_reconfirmation`). No person, field choice or value. `404` while `HIVE_HUB_CUSTOMERS_SHARE_ENABLED` is off | `pkg/hub/customer_consent.go` |
| `GET` | `/api/saas/admin/user-countries` | Hub admin | User Country Rollup | `pkg/hub/saas.go:476` |
| `GET` | `/api/saas/admin/auth-rollout` | Hub admin | Auth Rollout Readiness Summary | `pkg/hub/saas.go:481` |
| `GET` | `/api/saas/admin/notifications` | Hub admin | Hub Notifications Get | `pkg/hub/saas.go:482` |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@ Opening a profile shows:
- **Merge** (owner and read-write): fold another customer into this profile when they are the same person. Identities, tags, goals and activity come across, and **Undo merge** gives them back exactly. Two dashboard users cannot be merged. **Split off** on an identity moves it, and the activity it produced, to a new customer.
- **Export** and **Forget** (owner only): **Export this person** shows everything held about them in a viewer you can copy from. **Forget**: deletes the person, their identities and their activity links, and stops hive rebuilding the profile.

Nothing in this section leaves the hive. Turn it off with **Settings › Features › Customers** (`customers.enabled`), which takes effect when the hive restarts. API: [customers](api-reference/customers.md). Design: [customers](design/customers.md).
Nothing in this section leaves the hive, and nothing is read from the hub, unless the owner turns on **Settings › Features › Import details people shared on the hub** (`customers.hub_import.enabled`, default off). Then the hive sends the hub salted hashes of its confirmed customers' GitHub logins, and a person who opted in on the hub's **Profile sharing** page for this hive can have the real name, organization or country they entered there fill their profile, shown as "from the hub". A value set by hand here is never overwritten, and a withdrawal on the hub clears the imported value at the next sync. See [Customers hub import](telemetry.md#customers-hub-import). Turn the section off with **Settings › Features › Customers** (`customers.enabled`), which takes effect when the hive restarts. API: [customers](api-reference/customers.md). Design: [customers](design/customers.md).

## Contributors

Expand Down
5 changes: 4 additions & 1 deletion src/docs/design/customers-hub-consent.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# Customers: opt-in, consent-first import of hub-held person fields (#19088)

Status: **Decided; design only.** Spec for issue
Status: **Decided; phases 1 to 4 built, off by default.** Operator-facing
docs: [Customer profile sharing](../hub-deployment.md#customer-profile-sharing)
on the hub and [Customers hub import](../telemetry.md#customers-hub-import) on
the hive. Spec for issue
[#19088](https://github.com/hivecommons/hive/issues/19088). The operator decided
the model in that issue (option 1, below), so this page records it and cuts it
into phases; it does not reopen it. No code or behaviour changes with this
Expand Down
12 changes: 8 additions & 4 deletions src/docs/design/customers.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,9 @@ Goals:
Non-goals (this series):

- Any outbound path. Nothing is published, written to GitHub, sent to a hub or
added to a heartbeat.
added to a heartbeat. The one later exception is the opt-in, consent-first
hub import in [customers-hub-consent.md](customers-hub-consent.md), off by
default.
- An agent-callable query tool. Agents cannot query Hive's stores
([security-model.md](../security-model.md) section 4,
[ADR-0011](../adr/0011-knowledge-system.md)); a query tool is a later RFC.
Expand Down Expand Up @@ -92,7 +94,7 @@ contributor is one of several sources of identity for a person.
| `goals` | See section 8. |
| `satisfaction` | See section 8. |
| `notes` | Free text, written by people only. |
| `profile` | Optional `real_name`, `organization`, `location` and `country`, each `{value, source, rule, at, by}`. `source` is `auto` (the person's own public GitHub profile name, company and location, fetched once on accept; the country derived offline from the location, rule `location`) or `manual` (a person typed it or cleared it; neither the fetch nor the location changes it; `auto` hands it back). `country` is an ISO 3166 alpha-2 code. Also `dismissed_affiliations`, the suggested organizations a person refused (at most 20). Nothing here comes from the hub. |
| `profile` | Optional `real_name`, `organization`, `location` and `country`, each `{value, source, rule, at, by}`. `source` is `auto` (the person's own public GitHub profile name, company and location, fetched once on accept; the country derived offline from the location, rule `location`) or `manual` (a person typed it or cleared it; neither the fetch nor the location changes it; `auto` hands it back). `country` is an ISO 3166 alpha-2 code. Also `dismissed_affiliations`, the suggested organizations a person refused (at most 20). Nothing here comes from the hub, except a `real_name`, `organization` or `country` the person entered on the hub and consented to share with this hive, when `customers.hub_import.enabled` is on ([customers-hub-consent.md](customers-hub-consent.md)). |
| `merged_from` | Merge history, so a merge can be undone. |

**Identity** `{kind, value, source, confidence, manual, at, by}`. Kinds:
Expand Down Expand Up @@ -325,8 +327,10 @@ search, and keeps only the name, company and location the person published
stand-down, spends one request of that budget, and is never run by the sweep. A
suggested person has no profile fields until accepted. Forget deletes the fields
with the person and export includes them. The hub's own records of the same people
(name, company, country, notes, inferred affiliation) are not read or copied: that
is the open question in section 15 and needs a consent decision first.
(name, company, country, notes, inferred affiliation) are not read or copied,
except, when the hub import is on, the name, organization and country a person
entered on the hub and consented to share with this hive. Notes and affiliation
never cross. See [customers-hub-consent.md](customers-hub-consent.md).

Country and likely affiliation add no request of their own. The country is derived
from the location text by a bundled table (country names and aliases, ISO codes, US
Expand Down
2 changes: 1 addition & 1 deletion src/docs/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +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_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`. With it on, a hive that turned on `customers.hub_import.enabled` receives only the fields a person consented to share with it and entered themselves. 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. |
Expand Down
33 changes: 31 additions & 2 deletions src/docs/hub-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,8 +99,37 @@ 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.
material disclosure change requires reconfirmation: disclosure version 2, which
replaced the version that said nothing was sent yet, suspends every earlier
consent until the person confirms again.

A hive asks for these values only when its owner turns on
`customers.hub_import.enabled` (see
[Customers hub import](telemetry.md#customers-hub-import)). The hive posts
salted hashes of its confirmed customers' GitHub logins to
`POST /api/customers/match` with its per-hive bearer. The hub answers only for
people with an effective consent for that hive, with only the fields they
selected and only values they entered themselves; an unknown and an
unconsented person get the same empty answer. A withdrawal, a lost grant, a
blocked account or a deleted hub user makes the next answer tell the hive to
clear what it was sent.

What each role sees:

- **The person**, on the Profile sharing page: per hive, what was last sent and
when, which fields were sent at any time, and when the first delivery was.
- **A hub admin**, in the dashboard's Scale Controls, under **Customers profile
sharing**: the number of consents per hive, and how many await
reconfirmation. No person, field choice or value is shown, and no admin route
can grant, change or read a consent. The same counts are at
`GET /api/saas/admin/profile-share/counts`.
- **The hive owner and anyone with Customers access on that hive**: the values
the hive received, shown as "from the hub". They can export them, and the hub
cannot recall an exported copy.

Audit lines carry names of fields, never values: `audit: customer consent
grant`, `change` and `withdrawal` per consent change, and `audit: customer match`
per request with the hive id and counts.

### Ask AI help

Expand Down
6 changes: 5 additions & 1 deletion src/docs/security-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,11 @@ authoritative list is the switch and the `specialPurposePrefixes` table in

The Customers section keeps one profile per person. It lives in two files on the
hive's own volume and nothing in it leaves the hive. It is not sent to the hub,
written to GitHub or put in a heartbeat. The design is in
written to GitHub or put in a heartbeat. The one exception is the opt-in
Customers hub import (`customers.hub_import.enabled`, default off): it sends the
hub only salted hashes of confirmed customers' GitHub logins, and receives only
fields a person consented to share with this hive
([telemetry](telemetry.md#customers-hub-import)). The design is in
[customers](design/customers.md).

Some of these people never signed up. They are issue authors, meeting guests and
Expand Down
Loading
Loading