Skip to content

📖 Customers: opt-in, consent-first import of hub-held person fields (design) #19088

Open

Description

@clubanderson

Design for the second half of the operator's ask: Customers on a spoke showing context the hub already holds about the same people. Companion to #19085 (spoke-local country, likely affiliation, notes). Design decision from the consistency deck: hub data in Customers is opt-in, consent first, and off by default. No code is proposed yet because two consent questions below are the operator's to decide.

What exists today (verified in the repo)

  • The hub keeps a per-user record (SaaSUser, pkg/hub/saas.go): full_name, slack_id, notes and company (operator-entered CRM text; notes are admin-only, withheld even from hive owners), country with a source of inferred (from the browser language at login), admin or user (the person chose it), affiliation with affiliation_source (cached from public GitHub footprint), provider display_name, email, linked_github_login.
  • Per-hive access rows already carry full_name and slack_id to a hive owner, and notes only to a hub admin (saas_access.go).
  • The hub has no per-person consent state. Nothing records that a person agreed to their fields being shared with a hive.
  • A spoke talks to the hub by heartbeat (POST /api/heartbeat, per-hive bearer); the hub can piggyback data on the reply. There is no endpoint where a spoke asks the hub about a person, and none returning these fields to a spoke.
  • On the spoke, Customers profile fields carry provenance auto or manual; "Nothing is read from the hub" is stated in the design doc and ✨ Customers: real name, organization and location on a profile #18973.

Proposed model

Per-field provenance value hub (a third value beside auto and manual), shown as "from the hub", never overwriting a manual field, overwritten by nothing but a person or the next sanctioned import.

Fields by sensitivity

  1. Country, organization, real name: low risk when the person set them. Importable only where hub provenance is user (the person entered it). inferred and admin values are not imported by default: an inferred country is a guess about a browser, and an admin attribution is a claim by someone else.
  2. Hub notes: admin-private CRM text that can name other people. Never imported. Not an option.
  3. Email, Slack id: identifiers, not profile context. Not imported in v1.

Who consents (operator decision 1). Options: (a) the person, per hive, through a hub page "share my name, organization and country with hive X"; (b) the hub operator, by policy, for hives the hub itself hosts; (c) the spoke owner, by turning the switch on (which only says the spoke wants it; the hub still decides what to send). Recommendation: (a) is the only option that is consent in the ordinary sense. (b) is defensible only for hives the same operator runs, and must be disclosed in the privacy text. The spoke owner's switch is always required and never sufficient.

What crosses the wire. A signed, per-hive pull: the spoke posts the hash of each confirmed Customers identity it holds (GitHub login or confirmed email, salted per hive) and the hub answers only for persons who consented to that hive, with {match_hash, real_name, organization, country}, each field present only if hub provenance is user. No plaintext identifiers from the spoke, no notes, no unconsented person (the hub cannot tell a spoke whether someone exists on the hub: unconsented and unknown look the same).

Transport and auth. Reuse the existing per-hive bearer and the heartbeat channel (or a sibling endpoint under the same auth). Rate-limited and cached on the hub; off in the spoke unless customers.hub_import.enabled (default off, env override) AND the hive is registered with a hub.

Revocation. Person: withdraw on the hub; the hub stops answering for them, and the next sanctioned import clears spoke fields with provenance hub for that person (a tombstone reply, not silence). Forget on the spoke already deletes the person; a hash tombstone prevents re-import. Forget on the hub (account deletion) is a withdrawal for every hive.

Default. Off, everywhere, until the operator decides 1 and 2 below.

Decisions the operator must make

  1. Who consents: the person, per hive (recommended), the hub operator for hosted hives only, or the spoke owner alone (not recommended).
  2. Is it acceptable to ship consent as a new hub page and stored per-person per-hive record before any spoke code? Without it there is nothing to consent to.
  3. Do admin-sourced values (an operator typed the organization for someone) ever cross, with the person's consent, or only user-sourced ones?
  4. Should email-derived affiliation on the spoke (✨ Customers: country flag, likely affiliation suggestion and notes rules on a profile (spoke-local) #19085) stay spoke-local forever, or be reconciled with the hub's cached affiliation once a consent record exists?

Out of scope here

Any implementation. A PR is not opened because decisions 1 and 2 change the hub's data model and privacy text.

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 18, 2026
  2. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    🔓 Claim by @Danathar released (lease revoked).

    Claim history
    • 2026-11-18 18:50 UTC — claimed by Danathar (contributor on hive hosted-available-oke-11-placeholder-r05x)
    • 2026-11-18 18:54 UTC — released by Danathar (contributor; lease revoked)
  3. hivecommons-hive commented on Nov 18, 2026

    @hivecommons-hive
    Contributor

    What to reply

    • /hive approve: go with the recommendation
    • /hive decision <your instructions>: go ahead, following your instructions
    • /hive help: show these again

    If what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply /fixed to close it as completed; Hive clears its park labels.

    Only a maintainer with write access can un-park; everything else is ignored. Full command reference: https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md.

  4. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    Decision needed: one real choice. The other three follow from it or can wait.

    Verified against v5: the hub stores country_source and affiliation_source per user but has no per-person consent record, and no endpoint returns person fields to a spoke. #19085 / #19087 (spoke-local country, affiliation, notes) are merged, so nothing here blocks current Customers work. Default stays off.

    The one question: who consents to hub-held name, organization and country reaching a hive?

    1. The person, per hive, on a hub page (recommended). Tradeoff: the only option that is consent in the ordinary sense and works for self-hosted spokes; costs a new hub page and a stored per-person, per-hive record before any spoke code, and few people will opt in at first.
    2. The hub operator, by policy, for hub-hosted hives only. Tradeoff: ships faster and needs no person action, but is a disclosure-in-privacy-text model rather than consent, and must never extend to self-hosted spokes.
    3. The spoke owner's switch alone. Not recommended: the spoke owner cannot consent for someone else.

    Follow-ons, with defaults that apply unless you say otherwise

    • Hub consent storage and page first: implied by option 1 (there is nothing to consent to without it). Not needed for option 2.
    • admin-entered hub values: never cross in v1; only values the person entered themselves (user provenance). An operator's attribution of someone else is not the person's statement.
    • Spoke email affiliation vs the hub's cached affiliation: stays spoke-local in v1; revisit only after a consent record exists.

    Reply /hive decision 1 (or 2) to accept that option with the defaults above, or name any default you want changed.

  5. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    Decision (owner): option 1. The person consents, per hive, on a hub page; the hub consent page and consent record come first; only values the person entered themselves cross to a hive, never admin-entered ones; email affiliation stays spoke-local in v1. Default off until the person opts in.

  6. clubanderson commented on Nov 18, 2026

    @clubanderson
    MemberAuthor

    /hive decision 1. The person consents, per hive, on a hub page. Build the hub consent page and the per-person, per-hive consent record first, before any spoke code. Only values the person entered themselves (user provenance) cross to a hive, never admin-entered ones. Email affiliation stays spoke-local in v1. Default off until the person opts in. Any setting this needs gets a home in the dashboard Settings UI.

    (Same decision as the owner comment above, restated in the form the un-park sweep parses.)

  7. added and removed
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    on Nov 18, 2026
  8. 14 remaining items

  9. added
    hive/verified-openHive verified that a likely/already-done claim did not finish this issue; keep open for more work
    on Nov 19, 2026
  10. clubanderson commented on Nov 19, 2026

    @clubanderson
    MemberAuthor

    Decision change (2026-11-19, operator): part of the consent-first rule is relaxed for hub-held person fields.

    • Country and organization (affiliation) that the hub holds or derives may pass to a hive's customer records for that hive's grant holders without per-person consent. Every value is labeled with where it came from (entered by the person, set by a hub admin, derived from an email domain, inferred from browser language), and the label shows in the tooltip and pill.
    • Affiliation derived from an email domain passes only when the domain is a known public organization domain. Personal or vanity domains, free-mail providers and any domain not confidently an organization's never pass. Email addresses and domains themselves never pass.
    • Public forge profile data (GitHub, GHE, GitLab, Gitea, Linear) is fine; that work is separate (customers.profile_fill).
    • Precedence on the hive: set by hand on the hive > entered by the person on the hub > public forge profile > hub derived or admin-set. A manual edit on the hive is never overwritten.
    • Everything else keeps the consent-first rule. Real name still needs consent. Location, notes, email and Slack ids never pass.

    Import switches stay off. Implementation is tracked in a new issue, linked below.

  11. clubanderson commented on Nov 19, 2026

    @clubanderson
    MemberAuthor

    Implementation of the decision change above: #19306.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

approved-directionhelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.hive/partially-addressedA merged PR addressed only part of this issue; remainder still actionablehive/verified-openHive verified that a likely/already-done claim did not finish this issue; keep open for more workstage/010-actionableTriaged; eligible for the hive to pick up

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions