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-18742-customers-hints-audit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- **Customers: audit activity and "Same person?" hints (#18742).** The discovery sweep now reads the dashboard audit log: a customer gets one `acted` edge per day they did something and a `logged_in` edge on days they signed in. Only the user, the day and the kind of action are read, never an audit line's detail, and an edge goes when its day leaves the 90-day audit retention. Hive also raises "Same person?" questions when a suggested address starts like a customer's login (or a suggested login like one of their addresses); names are never compared, short and role addresses are skipped, and nothing is linked until the owner or a read-write user answers on the profile: yes makes the suggested identity theirs, no pins the pair so it is not asked again (`POST /api/customers/hints/{hid}/answer`, audited as `customer_hint_answer`). `src/docs/security-model.md` now describes the customers store, the position on people who never signed up, and the one trust assumption in identity linking: a `github:<login>` access-list entry is taken as proof of that GitHub login. The budgeted GitHub search on accept is not part of this change.
66 changes: 66 additions & 0 deletions dashboard/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -2063,6 +2063,72 @@
}
}
},
"/api/customers/hints/{hid}/answer": {
"post": {
"tags": [
"Customers"
],
"summary": "Answer a \"Same person?\" question",
"description": "Hive raises a question when a suggested person's address starts like a customer's login, or the reverse. Nothing is linked until it is answered. same true makes the suggested identity the customer's own and deletes the suggestion; same false closes the question and remembers it so it is not asked again. A question between two customers is answered by merging them, so same true on one is refused with 400. Owner or read-write. Audited as customer_hint_answer.",
"parameters": [
{
"name": "hid",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Hint id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"same"
],
"properties": {
"same": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The customer after the answer",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Customer profile as the viewer sees it, as returned by GET /api/customers/{id}"
}
}
}
},
"400": {
"description": "Malformed body, or a customer-to-customer question answered yes"
},
"403": {
"description": "Owner or read-write access required"
},
"404": {
"description": "No such question, customer or suggestion"
},
"409": {
"description": "The identity already belongs to another customer"
},
"503": {
"description": "Customers are turned off on this hive"
}
}
}
},
"/api/customers/suggestions/{sid}/accept": {
"post": {
"tags": [
Expand Down
69 changes: 69 additions & 0 deletions src/cmd/hive/customers_sweep.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"time"

"github.com/hivecommons/hive/pkg/claims"
"github.com/hivecommons/hive/pkg/compliance"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/customers"
"github.com/hivecommons/hive/pkg/dashboard"
Expand Down Expand Up @@ -44,6 +45,16 @@ const (
customersSourceMail = "inbox_mail"
customersSourceCalendar = "calendar"
customersSourceMeetings = "meetings"
customersSourceAudit = "audit_log"
)

const (
// customersAuditWindow is how many recent audit entries one pass reads.
customersAuditWindow = 5000
// customersLoginActionMarker marks an audit action that is a sign-in.
customersLoginActionMarker = "login"
// customersAuditDayLayout is the day an audit reference names.
customersAuditDayLayout = "2006-01-02"
)

// customersSources is one sweep's reading of the hive's local state.
Expand All @@ -60,12 +71,19 @@ type customersSources struct {
mail []inbox.Item
events []schedule.Event
meetings []meetings.Meeting
// audit is the recent dashboard audit log (step D).
audit []dashboard.AuditEntry
}

// customersSources reads the local stores. A store that is off or fails to
// list contributes nothing this pass.
func (b *boot) customersSources(ctx context.Context, cfg *config.Config) customersSources {
src := customersSources{cfg: cfg, last: b.lastActionable.Load()}
if b.dashSrv != nil {
if log := b.dashSrv.GetAudit(); log != nil {
src.audit = log.Recent(customersAuditWindow)
}
}
if b.ownerIdentity != nil {
src.ownerLogin = b.ownerIdentity.Status().Login
}
Expand Down Expand Up @@ -127,6 +145,7 @@ func customersSweepInput(src customersSources) customers.SweepInput {
in.Users, in.Links = customersUsers(src)
in.Sightings = append(in.Sightings, customersGitHubSightings(src)...)
in.Sightings = append(in.Sightings, customersLocalSightings(src)...)
in.Sightings = append(in.Sightings, customersAuditSightings(src)...)
return in
}

Expand Down Expand Up @@ -369,6 +388,7 @@ func (b *boot) customersResolvers() customers.Resolvers {
customers.RefMeeting: customersMeetingResolver{b: b},
customers.RefEvent: customersEventResolver{b: b},
customers.RefInbox: customersInboxResolver{b: b},
customers.RefAudit: customersAuditResolver{now: time.Now},
}
}

Expand Down Expand Up @@ -446,3 +466,52 @@ func (r customersInboxResolver) Exists(ref string) bool {
}

func (r customersInboxResolver) Visible(_ string, v customers.Viewer) bool { return v.Full }

// customersAuditSightings is step D: what a dashboard user did, as one edge
// per person per day. The audit log carries the user and the day; the
// action's detail is never read, so nothing a person typed is copied.
// Pseudo-users such as the system and an unproxied local session match no
// customer and are dropped by the store.
func customersAuditSightings(src customersSources) []customers.Sighting {
type key struct{ user, pred, day string }
seen := map[key]bool{}
var out []customers.Sighting
for _, e := range src.audit {
user := strings.TrimSpace(e.User)
if user == "" {
continue
}
at, err := time.Parse(time.RFC3339, e.Timestamp)
if err != nil {
continue
}
day := at.UTC().Format(customersAuditDayLayout)
pred := customers.PredActed
if strings.Contains(strings.ToLower(e.Action), customersLoginActionMarker) {
pred = customers.PredLoggedIn
}
k := key{strings.ToLower(user), pred, day}
if seen[k] {
continue
}
seen[k] = true
out = append(out, customersSighting(customers.KindHiveUser, user, pred, customers.AuditRef(day), at, customersSourceAudit))
}
return out
}

// customersAuditResolver: an audit day exists while it is inside the audit
// log's retention. An audit edge is for the full view only: it says when
// someone worked.
type customersAuditResolver struct{ now func() time.Time }

func (r customersAuditResolver) Exists(ref string) bool {
day, err := time.Parse(customersAuditDayLayout, customersRefID(ref, customers.RefAudit))
if err != nil {
return false
}
retention := time.Duration(compliance.BuiltinAuditRetentionDays) * 24 * time.Hour
return r.now().Sub(day) <= retention+24*time.Hour
}

func (r customersAuditResolver) Visible(_ string, v customers.Viewer) bool { return v.Full }
59 changes: 59 additions & 0 deletions src/cmd/hive/customers_sweep_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,15 @@ import (
"net/http"
"net/http/httptest"
"path/filepath"
"strings"
"sync/atomic"
"testing"
"time"

"github.com/hivecommons/hive/pkg/claims"
"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/customers"
"github.com/hivecommons/hive/pkg/dashboard"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/inbox"
"github.com/hivecommons/hive/pkg/mailallow"
Expand Down Expand Up @@ -311,3 +313,60 @@ func TestCustomersResolversWithStoresOff(t *testing.T) {
}
}
}

func TestCustomersAuditSightings(t *testing.T) {
src := customersTestSources()
src.audit = []dashboard.AuditEntry{
{Timestamp: "2026-11-03T09:00:00Z", User: "olivia", Action: "config_save", Detail: "secret=hunter2"},
{Timestamp: "2026-11-03T17:00:00Z", User: "Olivia", Action: "agent_restart"},
{Timestamp: "2026-11-03T08:00:00Z", User: "olivia", Action: "dashboard_login"},
{Timestamp: "2026-11-04T01:00:00Z", User: "olivia", Action: "pause"},
{Timestamp: "2026-11-03T09:00:00Z", User: "reed", Action: "customer_edit"},
{Timestamp: "not a time", User: "reed", Action: "pause"},
{Timestamp: "2026-11-03T09:00:00Z", User: " ", Action: "pause"},
}
got := map[sightKey]customers.Sighting{}
for _, s := range customersAuditSightings(src) {
got[sightKey{s.Kind, s.Value, s.Predicate, s.Artefact}] = s
}
want := []sightKey{
{customers.KindHiveUser, "olivia", customers.PredActed, "audit:2026-11-03"},
{customers.KindHiveUser, "olivia", customers.PredLoggedIn, "audit:2026-11-03"},
{customers.KindHiveUser, "olivia", customers.PredActed, "audit:2026-11-04"},
{customers.KindHiveUser, "reed", customers.PredActed, "audit:2026-11-03"},
}
if len(got) != len(want) {
t.Fatalf("%d audit sightings, want %d (one per person, kind and day): %v", len(got), len(want), got)
}
for _, k := range want {
if s, ok := got[k]; !ok || s.Source != customersSourceAudit {
t.Errorf("missing audit sighting %+v", k)
}
}
for k := range got {
if strings.Contains(k.ref+k.value, "hunter2") {
t.Fatal("audit detail text was copied")
}
}
if len(customersAuditSightings(customersSources{})) != 0 {
t.Fatal("no audit log, no sightings")
}
}

func TestCustomersAuditResolver(t *testing.T) {
now := time.Date(2026, 11, 17, 12, 0, 0, 0, time.UTC)
r := customersAuditResolver{now: func() time.Time { return now }}
for ref, want := range map[string]bool{
"audit:2026-11-17": true, "audit:2026-08-20": true, "audit:2026-08-10": false, "audit:garbage": false, "audit:": false,
} {
if got := r.Exists(ref); got != want {
t.Errorf("Exists(%q) = %v, want %v", ref, got, want)
}
}
if !r.Visible("audit:2026-11-17", customers.Viewer{User: "a", Full: true}) || r.Visible("audit:2026-11-17", customers.Viewer{User: "a"}) {
t.Fatal("audit edges are for the full view only")
}
if (&boot{}).customersResolvers()[customers.RefAudit] == nil {
t.Fatal("the audit resolver is not registered")
}
}
4 changes: 4 additions & 0 deletions src/cmd/hive/customerswire.go
Original file line number Diff line number Diff line change
Expand Up @@ -160,3 +160,7 @@ func (c *customersDashboard) Graph(ctx context.Context, v dashboard.CustomersVie
res := c.graph.Exec(ctx, customersViewer(v), req.Query, req.OperationName, req.Variables)
return dashboard.CustomerGraphResult{Body: res.Body, Nodes: res.Nodes, Errors: res.Errors}, nil
}

func (c *customersDashboard) AnswerHint(v dashboard.CustomersViewer, hintID string, same bool) (dashboard.CustomerResult, error) {
return customerResult(c.svc.AnswerHint(customersViewer(v), hintID, same))
}
4 changes: 2 additions & 2 deletions src/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh
| Inception | [`api-reference/inception.md`](api-reference/inception.md) | 14 |
| Beads | [`api-reference/beads.md`](api-reference/beads.md) | 5 |
| Sessions | [`api-reference/sessions.md`](api-reference/sessions.md) | 8 |
| Customers | [`api-reference/customers.md`](api-reference/customers.md) | 8 |
| Customers | [`api-reference/customers.md`](api-reference/customers.md) | 9 |
| Dashboard miscellaneous | [`api-reference/dashboard-misc.md`](api-reference/dashboard-misc.md) | 56 |
| Hub SaaS | [`api-reference/hub-saas.md`](api-reference/hub-saas.md) | 102 |
| Hub server | [`api-reference/hub-server.md`](api-reference/hub-server.md) | 46 |
Expand Down Expand Up @@ -82,7 +82,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh

## Customers

8 routes — see [api-reference/customers.md](api-reference/customers.md).
9 routes — see [api-reference/customers.md](api-reference/customers.md).

## Dashboard miscellaneous

Expand Down
15 changes: 8 additions & 7 deletions src/docs/api-reference/customers.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,14 @@ The rules are enforced twice: by the handlers and again by the store's service o

| Method | Path | Auth | Purpose | Source |
|---|---|---|---|---|
| `GET` | `/api/customers` | Signed-in user | The Customers section: `{enabled, full, owner, me, people, suggestions, default_tags, levels}`. `me` is the viewer's own profile, created on first read. `people` and `suggestions` are empty without the full view | `pkg/dashboard/api_customers.go:132` |
| `POST` | `/api/customers` | Full view | Add a customer by hand: `{name, identities?: [{kind, value}]}`. 409 when an identity belongs to another customer; a `hive_user` identity is refused. Audited as `customer_add` | `pkg/dashboard/api_customers.go:133` |
| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:134` |
| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:135` |
| `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:136` |
| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. Audited as `customer_accept` | `pkg/dashboard/api_customers.go:137` |
| `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:138` |
| `GET` | `/api/customers` | Signed-in user | The Customers section: `{enabled, full, owner, me, people, suggestions, default_tags, levels}`. `me` is the viewer's own profile, created on first read. `people` and `suggestions` are empty without the full view | `pkg/dashboard/api_customers.go:141` |
| `POST` | `/api/customers` | Full view | Add a customer by hand: `{name, identities?: [{kind, value}]}`. 409 when an identity belongs to another customer; a `hive_user` identity is refused. Audited as `customer_add` | `pkg/dashboard/api_customers.go:142` |
| `GET` | `/api/customers/{id}` | Signed-in user; self reaches only `me` | One profile, with edge counts and open "Same person?" hints for the full view. A viewer without the full view gets no notes, satisfaction, merge history, counts or hints. Opening someone else's profile is audited as `customer_profile_open` | `pkg/dashboard/api_customers.go:143` |
| `POST` | `/api/customers/{id}/edit` | Full view; self only as `/api/customers/me/edit` | One change: `{op, ...}` with `op` one of `name`, `notes`, `identity_add` (`kind`, `value`), `identity_remove` (`key`), `tag` (`tag`, `state` of `on`, `off` or `auto`), `goal_add` (`text`), `goal_edit` (`goal_id`, `text`), `goal_confirm`, `goal_reject` (`goal_id`), `satisfaction_set` (`level`), `satisfaction_confirm`, `satisfaction_reject`. Self may use the name, identity, tag and goal ops; an identity added by self is an unconfirmed claim that resolves nobody until the full view confirms it with `identity_add`. Audited as `customer_edit` with the person and the op, never the value | `pkg/dashboard/api_customers.go:144` |
| `DELETE` | `/api/customers/{id}` | Owner only | Forget: deletes the customer, their identities and every edge to them, and keeps one salted-hash tombstone per confirmed identity so discovery does not rebuild them. 200 `{forgotten, edges_removed}`. Audited as `customer_forget` | `pkg/dashboard/api_customers.go:145` |
| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. Audited as `customer_accept` | `pkg/dashboard/api_customers.go:146` |
| `POST` | `/api/customers/suggestions/{sid}/dismiss` | Full view | Delete a suggestion and tombstone its key, so it is not offered again. Audited as `customer_dismiss` | `pkg/dashboard/api_customers.go:147` |
| `POST` | `/api/customers/hints/{hid}/answer` | Full view | Answer a "Same person?" question: `{same}`. `true` makes the suggested identity the customer's own and deletes the suggestion; `false` closes the question for good. A question between two customers is answered by merging them, so `true` on one is 400. Audited as `customer_hint_answer` | `pkg/dashboard/api_customers.go:148` |
| `POST` | `/api/graph` | Signed-in user | The customer graph over GraphQL, read-only (no mutations, so a read-only user may call it): `{query, operationName?, variables?}`, answered with a GraphQL `{data, errors}` document. Access follows the viewer exactly as above; see [the customer graph](#the-customer-graph). Audited as `customer_graph_query` with the operation name, node count and error count, never the query text | `pkg/dashboard/api_graph.go:47` |

## The customer graph
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 @@ -219,7 +219,7 @@ Opening a profile shows:
- **Satisfaction** (owner and read-write only): a level (Unknown, At risk, Neutral, Satisfied) with what led to it. There is no score. Hive may suggest a level; it never changes one a person set.
- **Tags**: click a tag to turn it on or off. A tag marked manual stays as set; **Reset to automatic** hands it back to hive.
- **Identities**: the logins, addresses and ids the person is known by. An identity a read-only user adds to their own profile is shown as unconfirmed, and does nothing, until the owner or a read-write user presses **Confirm**. The hive user identity cannot be changed.
- **Activity** and **Notes** (owner and read-write only). The person does not see the notes.
- **Activity** and **Notes** (owner and read-write only). Activity also shows open "Same person?" questions: hive spots a suggested address or login that looks like one of this customer's. **Yes** makes it theirs; **No** closes the question for good. Nothing is linked until you answer. The person does not see the notes.
- **Forget** (owner only): 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).
Expand Down
Loading
Loading