diff --git a/changelog.d/added-18742-customers-merge-graph.md b/changelog.d/added-18742-customers-merge-graph.md new file mode 100644 index 0000000000..44eddc3da3 --- /dev/null +++ b/changelog.d/added-18742-customers-merge-graph.md @@ -0,0 +1 @@ +- **Customers: graph view, merge and split, export (#18742).** A profile now has a **Graph**: a drawing of the person, the things they touched and the other people on those things, read from the customer graph; clicking another person opens their profile, and a read-only user's graph holds only themselves. The owner and read-write users can **merge** a customer into another when they are the same person (identities, tags, goals and activity move across, and two dashboard users are never merged), **undo** a merge exactly (only what the merge brought goes back), and **split off** an identity, which moves it and the activity it produced to a new customer. The owner can **export** everything held about a person in an in-app viewer (the profile, merge history, hints and up to 10,000 activity references). Four new routes under `/api/customers/{id}`, audited as `customer_merge`, `customer_unmerge`, `customer_split` and `customer_export`; a read-only user can use none of them, including on their own profile. diff --git a/dashboard/openapi.json b/dashboard/openapi.json index fd0d0ace68..cb048f0152 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -2129,6 +2129,271 @@ } } }, + "/api/customers/{id}/merge": { + "post": { + "tags": [ + "Customers" + ], + "summary": "Merge a customer into this one", + "description": "Folds the customer in from into this one: identities, tags, goals and the activity edges move across, and the merge is recorded so it can be undone. Two dashboard users cannot be merged (409). Owner or read-write. Audited as customer_merge.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Customer id, or me for the viewer's own profile" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "from" + ], + "properties": { + "from": { + "type": "string", + "description": "Customer id" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The customer after the change", + "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 nothing to do" + }, + "403": { + "description": "Owner or read-write access required" + }, + "404": { + "description": "No such customer" + }, + "503": { + "description": "Customers are turned off on this hive" + }, + "409": { + "description": "Two dashboard users, or a conflicting identity" + } + } + } + }, + "/api/customers/{id}/unmerge": { + "post": { + "tags": [ + "Customers" + ], + "summary": "Undo a merge", + "description": "Restores the customer from as it stood before it was merged into this one, and gives back exactly the identities, tags, goals and activity the merge brought. The pair is remembered as different people. Owner or read-write. Audited as customer_unmerge.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Customer id, or me for the viewer's own profile" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "from" + ], + "properties": { + "from": { + "type": "string", + "description": "Customer id" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The customer after the change", + "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 nothing to do" + }, + "403": { + "description": "Owner or read-write access required" + }, + "404": { + "description": "No such customer" + }, + "503": { + "description": "Customers are turned off on this hive" + } + } + } + }, + "/api/customers/{id}/split": { + "post": { + "tags": [ + "Customers" + ], + "summary": "Split identities off into a new customer", + "description": "Moves the named identities (kind:value) off this customer onto a new one, and the activity those identities produced moves with them. A hive user identity cannot be split off and a split must leave an identity behind. Returns the new customer. Owner or read-write. Audited as customer_split.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Customer id, or me for the viewer's own profile" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "identities" + ], + "properties": { + "identities": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Identity keys, kind:value" + }, + "name": { + "type": "string", + "description": "Name for the new customer; defaults to the first identity" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The customer after the change", + "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 nothing to do" + }, + "403": { + "description": "Owner or read-write access required" + }, + "404": { + "description": "No such customer" + }, + "503": { + "description": "Customers are turned off on this hive" + } + } + } + }, + "/api/customers/{id}/export": { + "get": { + "tags": [ + "Customers" + ], + "summary": "Export everything held about a customer", + "description": "Owner only. Returns the profile (including notes, the satisfaction assessment and the merge history), open hints and the references behind the person's activity (at most 10,000), as a JSON download. It holds references, never the content of what they point at. Audited as customer_export.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Customer id, or me for the viewer's own profile" + } + ], + "responses": { + "200": { + "description": "The export", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "person": { + "type": "object", + "description": "The full profile" + }, + "edges": { + "type": "array", + "items": { + "type": "object", + "description": "person, predicate, artefact, via, source, at" + } + }, + "truncated": { + "type": "boolean" + }, + "hints": { + "type": "array", + "items": { + "type": "object" + } + } + } + } + } + } + }, + "403": { + "description": "Owner access required" + }, + "404": { + "description": "No such customer" + }, + "503": { + "description": "Customers are turned off on this hive" + } + } + } + }, "/api/customers/suggestions/{sid}/accept": { "post": { "tags": [ diff --git a/src/cmd/hive/customerswire.go b/src/cmd/hive/customerswire.go index c0ca95979d..ff58f772ed 100644 --- a/src/cmd/hive/customerswire.go +++ b/src/cmd/hive/customerswire.go @@ -210,3 +210,23 @@ func installCustomersAgentContext(c *customersDashboard, setKickLookup func(sche setKickLookup(c.svc.KickContext) } } + +func (c *customersDashboard) Merge(v dashboard.CustomersViewer, id, from string) (dashboard.CustomerResult, error) { + return customerResult(c.svc.Merge(customersViewer(v), id, from)) +} + +func (c *customersDashboard) Unmerge(v dashboard.CustomersViewer, id, from string) (dashboard.CustomerResult, error) { + return customerResult(c.svc.Unmerge(customersViewer(v), id, from)) +} + +func (c *customersDashboard) Split(v dashboard.CustomersViewer, id string, keys []string, name string) (dashboard.CustomerResult, error) { + return customerResult(c.svc.Split(customersViewer(v), id, keys, name)) +} + +func (c *customersDashboard) Export(v dashboard.CustomersViewer, id string) (any, error) { + out, err := c.svc.Export(customersViewer(v), id) + if err != nil { + return nil, customersError(err) + } + return out, nil +} diff --git a/src/docs/api-reference.md b/src/docs/api-reference.md index 6c0a2356b0..645b69fb09 100644 --- a/src/docs/api-reference.md +++ b/src/docs/api-reference.md @@ -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) | 9 | +| Customers | [`api-reference/customers.md`](api-reference/customers.md) | 13 | | 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 | @@ -82,7 +82,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh ## Customers -9 routes — see [api-reference/customers.md](api-reference/customers.md). +13 routes — see [api-reference/customers.md](api-reference/customers.md). ## Dashboard miscellaneous diff --git a/src/docs/api-reference/customers.md b/src/docs/api-reference/customers.md index 0442b88abc..6884013a65 100644 --- a/src/docs/api-reference/customers.md +++ b/src/docs/api-reference/customers.md @@ -12,14 +12,18 @@ 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: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` | +| `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:164` | +| `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:165` | +| `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:166` | +| `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:167` | +| `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:168` | +| `POST` | `/api/customers/suggestions/{sid}/accept` | Full view | Turn a suggested person into a customer. Audited as `customer_accept` | `pkg/dashboard/api_customers.go:169` | +| `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:170` | +| `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:171` | +| `POST` | `/api/customers/{id}/merge` | Full view | Fold the customer `{from}` into this one: identities, tags, goals and activity move across and the merge is recorded. 409 for two dashboard users. Audited as `customer_merge` | `pkg/dashboard/api_customers.go:172` | +| `POST` | `/api/customers/{id}/unmerge` | Full view | Undo a merge: `{from}` comes back as it stood, with exactly what the merge brought it. Audited as `customer_unmerge` | `pkg/dashboard/api_customers.go:173` | +| `POST` | `/api/customers/{id}/split` | Full view | Move identities `{identities: ["kind:value"], name?}` off this customer onto a new one, with the activity they produced; returns the new customer. Audited as `customer_split` | `pkg/dashboard/api_customers.go:174` | +| `GET` | `/api/customers/{id}/export` | Owner only | Everything held about one customer as a JSON download: the profile, merge history, hints and up to 10,000 activity references. Audited as `customer_export` | `pkg/dashboard/api_customers.go:175` | | `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 diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index a7bfa380f5..b86a4695b0 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -220,7 +220,9 @@ Opening a profile shows: - **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). 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. +- **Graph**: **Show graph** draws the person, the things they touched and the other people on those things. Click a green dot to open that person. A read-only user's graph holds only themselves. +- **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). diff --git a/src/docs/design/customers.md b/src/docs/design/customers.md index c6b40e91d9..f77e2d13a3 100644 --- a/src/docs/design/customers.md +++ b/src/docs/design/customers.md @@ -384,6 +384,24 @@ artefact they materialise to a per-query budget. Access is not decided in the GraphQL layer at all: every resolver calls the customers service with the viewer of the request, the same service the REST routes use. +**Merge, split and the graph view.** Merge folds one customer into another and +moves every edge across; the merge is recorded on the target with the source as +it stood and the identities, tags and goals it brought, so unmerge can give back +exactly those. Unmerge moves back only the edges whose `via` identity belonged +to the restored person, so activity the target produced on its own stays put. +Split works the same way in the other direction: the edges that the named +identities produced move with them. Two dashboard users are never merged, and a +`hive_user` identity is never split off. Both are full-view actions and audited +(`customer_merge`, `customer_unmerge`, `customer_split`). Export is owner only +and audited (`customer_export`); it holds the profile, merge history, hints and +at most 10,000 edge references. + +The graph view is a static SVG drawn from the same GraphQL endpoint (one query: +a person's edges and, under each, the people on that artefact). It does not +reuse the knowledge graph canvas, which is animated and styled inline; the +customers view is a small radial drawing that stays readable on a phone and +follows the page's design tokens. + ## 12. Agents and privacy guard rails **Agents.** Hive selects from the graph for the agent; the agent does not diff --git a/src/pkg/customers/service.go b/src/pkg/customers/service.go index 6660d668a6..485d129134 100644 --- a/src/pkg/customers/service.go +++ b/src/pkg/customers/service.go @@ -449,3 +449,122 @@ func (s *Service) AnswerHint(v Viewer, hintID string, same bool) (PersonView, er } return s.view(v, p, false, true), nil } + +// Merge folds the customer src into dst: identities, tags and goals come +// across, and so do the activity edges. The merge is recorded on dst, so +// Unmerge can undo it exactly. Full view only. +func (s *Service) Merge(v Viewer, dstID, srcID string) (PersonView, error) { + if !v.Full { + return PersonView{}, ErrForbidden + } + dst, dstMe, err := s.resolve(v, dstID) + if err != nil { + return PersonView{}, err + } + src, _, err := s.resolve(v, srcID) + if err != nil { + return PersonView{}, err + } + merged, err := s.store.Merge(dst.ID, src.ID, v.User) + if err != nil { + return PersonView{}, err + } + if s.index != nil { + if _, err := s.index.Move(src.ID, dst.ID, func(Edge) bool { return true }); err != nil { + return PersonView{}, err + } + } + return s.view(v, merged, dstMe, true), nil +} + +// Unmerge undoes a merge: the customer comes back as it stood, and the edges +// the merged identities produced go back with it. Full view only. +func (s *Service) Unmerge(v Viewer, dstID, srcID string) (PersonView, error) { + if !v.Full { + return PersonView{}, ErrForbidden + } + dst, dstMe, err := s.resolve(v, dstID) + if err != nil { + return PersonView{}, err + } + back, restored, err := s.store.Unmerge(dst.ID, srcID) + if err != nil { + return PersonView{}, err + } + if s.index != nil { + keys := make([]string, 0, len(restored.Identities)) + for _, i := range restored.Identities { + keys = append(keys, i.Key()) + } + if _, err := s.index.Move(dst.ID, restored.ID, ViaAny(keys)); err != nil { + return PersonView{}, err + } + } + return s.view(v, back, dstMe, true), nil +} + +// Split moves the identities named by keys off a customer onto a new one, +// and the edges those identities produced move with them. It returns the +// new customer. Full view only. +func (s *Service) Split(v Viewer, id string, keys []string, name string) (PersonView, error) { + if !v.Full { + return PersonView{}, ErrForbidden + } + p, _, err := s.resolve(v, id) + if err != nil { + return PersonView{}, err + } + _, fresh, err := s.store.Split(p.ID, keys, name, v.User) + if err != nil { + return PersonView{}, err + } + if s.index != nil { + if _, err := s.index.Move(p.ID, fresh.ID, ViaAny(keys)); err != nil { + return PersonView{}, err + } + } + return s.view(v, fresh, false, true), nil +} + +// ExportMaxEdges bounds how many edges one export carries. +const ExportMaxEdges = 10000 + +// Export is everything the hive holds about one customer, for the owner. +type Export struct { + Person Person `json:"person"` + // Edges are references to artefacts, never their content. + Edges []Edge `json:"edges"` + // Truncated is true when the person has more edges than ExportMaxEdges. + Truncated bool `json:"truncated,omitempty"` + Hints []Hint `json:"hints,omitempty"` +} + +// Export returns a customer and their edges. Owner only: it holds notes, the +// satisfaction assessment and the merge history. +func (s *Service) Export(v Viewer, id string) (Export, error) { + if !v.Full || !v.Owner { + return Export{}, ErrForbidden + } + p, _, err := s.resolve(v, id) + if err != nil { + return Export{}, err + } + out := Export{Person: p, Edges: []Edge{}, Hints: s.store.Hints(p.ID)} + if s.index == nil { + return out, nil + } + after := "" + for len(out.Edges) < ExportMaxEdges { + page, next, err := s.index.ByPerson(p.ID, "", after, MaxEdgePage) + if err != nil { + return Export{}, err + } + out.Edges = append(out.Edges, page...) + if next == "" { + return out, nil + } + after = next + } + out.Truncated = true + return out, nil +} diff --git a/src/pkg/customers/service_test.go b/src/pkg/customers/service_test.go index c663014c5d..00fe449095 100644 --- a/src/pkg/customers/service_test.go +++ b/src/pkg/customers/service_test.go @@ -541,3 +541,140 @@ func TestEdgesAndArtefactPeopleFollowTheViewer(t *testing.T) { t.Fatalf("ArtefactPeople without an index = %v, %v", p, err) } } + +func edgeCounts(t *testing.T, s *Service, id string) map[string]int { + t.Helper() + c, err := s.Index().Counts(id) + if err != nil { + t.Fatal(err) + } + return c +} + +// TestMergeUnmergeSplitMoveEdgesExactly: an edge follows the identity that +// produced it, through a merge, an undo and a split. +func TestMergeUnmergeSplitMoveEdgesExactly(t *testing.T) { + s := newService(t) + a, _ := s.Add(ownerV, "Ada", []Identity{{Kind: KindGitHub, Value: "ada"}}) + b, _ := s.Add(ownerV, "A. Lovelace", []Identity{{Kind: KindEmail, Value: "ada@example.com"}, {Kind: KindGitHub, Value: "ada-alt"}}) + if _, err := s.Index().Put([]Edge{ + edge(a.ID, PredAuthored, PRRef("o/r", 1), "github:ada", 1), + edge(b.ID, PredSent, InboxRef("email", "m1"), "email:ada@example.com", 2), + edge(b.ID, PredReported, IssueRef("o/r", 2), "github:ada-alt", 3), + }); err != nil { + t.Fatal(err) + } + + merged, err := s.Merge(rwV, a.ID, b.ID) + if err != nil || len(merged.Identities) != 3 || len(merged.MergedFrom) != 1 { + t.Fatalf("Merge = %+v, %v", merged, err) + } + if c := edgeCounts(t, s, a.ID); c[PredAuthored] != 1 || c[PredSent] != 1 || c[PredReported] != 1 { + t.Fatalf("after merge the target's edges = %v", c) + } + if c := edgeCounts(t, s, b.ID); len(c) != 0 { + t.Fatalf("the merged-in person still has edges: %v", c) + } + + // Undo: the merged identities' edges go back, the target keeps its own. + back, err := s.Unmerge(rwV, a.ID, b.ID) + if err != nil || len(back.Identities) != 1 || len(back.MergedFrom) != 0 { + t.Fatalf("Unmerge = %+v, %v", back, err) + } + if c := edgeCounts(t, s, a.ID); len(c) != 1 || c[PredAuthored] != 1 { + t.Fatalf("after unmerge the target's edges = %v", c) + } + if c := edgeCounts(t, s, b.ID); c[PredSent] != 1 || c[PredReported] != 1 { + t.Fatalf("after unmerge the restored person's edges = %v", c) + } + + // Split one identity off: exactly its edges move. + fresh, err := s.Split(ownerV, b.ID, []string{"email:ada@example.com"}, "Mail only") + if err != nil || fresh.Name != "Mail only" || !fresh.HasIdentity("email:ada@example.com") { + t.Fatalf("Split = %+v, %v", fresh, err) + } + if c := edgeCounts(t, s, fresh.ID); len(c) != 1 || c[PredSent] != 1 { + t.Fatalf("the new person's edges = %v", c) + } + if c := edgeCounts(t, s, b.ID); len(c) != 1 || c[PredReported] != 1 { + t.Fatalf("the original's edges = %v", c) + } + + // Refusals. + if _, err := s.Merge(rwV, a.ID, a.ID); !errors.Is(err, ErrInvalid) { + t.Fatalf("self merge = %v", err) + } + if _, err := s.Merge(rwV, a.ID, "p_missing"); !errors.Is(err, ErrNotFound) { + t.Fatalf("merge a missing person = %v", err) + } + if _, err := s.Unmerge(rwV, a.ID, b.ID); !errors.Is(err, ErrNotFound) { + t.Fatalf("unmerge twice = %v", err) + } + if _, err := s.Split(ownerV, b.ID, []string{"github:ada-alt"}, "x"); !errors.Is(err, ErrInvalid) { + t.Fatalf("splitting off the last identity = %v", err) + } +} + +func TestMergeSplitExportRoles(t *testing.T) { + s := newService(t) + a, _ := s.Add(ownerV, "Ada", []Identity{{Kind: KindGitHub, Value: "ada"}}) + b, _ := s.Add(ownerV, "Bo", []Identity{{Kind: KindGitHub, Value: "bo"}, {Kind: KindEmail, Value: "bo@example.com"}}) + me, _ := s.Get(readV, MeID) + // A read-only viewer can do none of it, on anyone, themselves included. + for _, id := range []string{a.ID, b.ID, MeID, me.ID} { + if _, err := s.Merge(readV, id, a.ID); !errors.Is(err, ErrForbidden) { + t.Errorf("read-only Merge(%s) = %v", id, err) + } + if _, err := s.Unmerge(readV, id, a.ID); !errors.Is(err, ErrForbidden) { + t.Errorf("read-only Unmerge(%s) = %v", id, err) + } + if _, err := s.Split(readV, id, []string{"github:bo"}, "x"); !errors.Is(err, ErrForbidden) { + t.Errorf("read-only Split(%s) = %v", id, err) + } + if _, err := s.Export(readV, id); !errors.Is(err, ErrForbidden) { + t.Errorf("read-only Export(%s) = %v", id, err) + } + } + if _, err := s.Export(rwV, a.ID); !errors.Is(err, ErrForbidden) { + t.Fatalf("read-write Export = %v, want ErrForbidden (the owner exports)", err) + } + // Two dashboard users are never merged. + alice, _ := s.Get(ownerV, MeID) + if _, err := s.Merge(ownerV, alice.ID, me.ID); !errors.Is(err, ErrConflict) { + t.Fatalf("merging two dashboard users = %v", err) + } + if _, err := s.Split(rwV, b.ID, []string{"email:bo@example.com"}, "Bo mail"); err != nil { + t.Fatalf("read-write Split = %v", err) + } +} + +func TestExport(t *testing.T) { + s := newService(t) + a, _ := s.Add(ownerV, "Ada", []Identity{{Kind: KindGitHub, Value: "ada"}}) + for _, e := range []Edit{{Op: OpNotes, Notes: "met at the summit"}, {Op: OpSatisfactionSet, Level: "at_risk"}} { + if _, err := s.Edit(ownerV, a.ID, e); err != nil { + t.Fatal(err) + } + } + var edges []Edge + for i := 0; i < MaxEdgePage+10; i++ { + edges = append(edges, edge(a.ID, PredAuthored, PRRef("o/r", i+1), "github:ada", i)) + } + if _, err := s.Index().Put(edges); err != nil { + t.Fatal(err) + } + out, err := s.Export(ownerV, a.ID) + if err != nil || out.Person.ID != a.ID || out.Person.Notes != "met at the summit" || out.Person.Satisfaction.Level != LevelAtRisk { + t.Fatalf("Export = %+v, %v", out.Person, err) + } + if len(out.Edges) != MaxEdgePage+10 || out.Truncated || out.Edges[0].Artefact == "" { + t.Fatalf("export edges = %d truncated=%v", len(out.Edges), out.Truncated) + } + if _, err := s.Export(ownerV, "p_missing"); !errors.Is(err, ErrNotFound) { + t.Fatalf("export of a missing person = %v", err) + } + bare := NewService(s.Store(), nil, nil) + if out, err := bare.Export(ownerV, a.ID); err != nil || out.Edges == nil || len(out.Edges) != 0 { + t.Fatalf("export without an index = %+v, %v", out, err) + } +} diff --git a/src/pkg/dashboard/api_customers.go b/src/pkg/dashboard/api_customers.go index e3719aa3d3..3b8830b3dd 100644 --- a/src/pkg/dashboard/api_customers.go +++ b/src/pkg/dashboard/api_customers.go @@ -47,6 +47,8 @@ const ( customersSelfEditPath = "/api/customers/me/edit" // customersMeID is the id alias for the viewer's own profile. customersMeID = "me" + // customersAuditIDMax bounds an id copied into an audit line. + customersAuditIDMax = 40 ) // CustomersViewer is who is asking. Full is the owner and read-write view; @@ -114,6 +116,27 @@ type CustomersService interface { // suggested identity the customer's own, false closes the question for // good. AnswerHint(v CustomersViewer, hintID string, same bool) (CustomerResult, error) + // Merge folds the customer "from" into id; Unmerge undoes it. + Merge(v CustomersViewer, id, from string) (CustomerResult, error) + Unmerge(v CustomersViewer, id, from string) (CustomerResult, error) + // Split moves the named identity keys (kind:value) off id onto a new + // customer, which it returns. + Split(v CustomersViewer, id string, keys []string, name string) (CustomerResult, error) + // Export returns everything held about one customer (owner only), + // JSON-encoded as returned. + Export(v CustomersViewer, id string) (any, error) +} + +// CustomerMergeRequest is the body of POST /api/customers/{id}/merge and +// /unmerge: From is the customer folded in (or restored). +type CustomerMergeRequest struct { + From string `json:"from"` +} + +// CustomerSplitRequest is the body of POST /api/customers/{id}/split. +type CustomerSplitRequest struct { + Identities []string `json:"identities"` + Name string `json:"name,omitempty"` } // CustomerHintAnswer is the body of POST /api/customers/hints/{hid}/answer. @@ -146,6 +169,10 @@ func (s *Server) registerCustomersRoutes() { s.mux.HandleFunc("POST /api/customers/suggestions/{sid}/accept", s.handleCustomersAccept) s.mux.HandleFunc("POST /api/customers/suggestions/{sid}/dismiss", s.handleCustomersDismiss) s.mux.HandleFunc("POST /api/customers/hints/{hid}/answer", s.handleCustomersHintAnswer) + s.mux.HandleFunc("POST /api/customers/{id}/merge", s.handleCustomersMerge) + s.mux.HandleFunc("POST /api/customers/{id}/unmerge", s.handleCustomersUnmerge) + s.mux.HandleFunc("POST /api/customers/{id}/split", s.handleCustomersSplit) + s.mux.HandleFunc("GET /api/customers/{id}/export", s.handleCustomersExport) s.registerCustomersGraphRoutes() } @@ -414,3 +441,106 @@ func (s *Server) handleCustomersHintAnswer(w http.ResponseWriter, r *http.Reques s.auditFromRequest(r, "customer_hint_answer", auditDetail("person", res.ID, "same", boolString(body.Same)), "") jsonResponse(w, res.View) } + +func (s *Server) handleCustomersMerge(w http.ResponseWriter, r *http.Request) { + s.customersMergeOrUnmerge(w, r, "customer_merge", func(svc CustomersService, v CustomersViewer, id, from string) (CustomerResult, error) { + return svc.Merge(v, id, from) + }) +} + +func (s *Server) handleCustomersUnmerge(w http.ResponseWriter, r *http.Request) { + s.customersMergeOrUnmerge(w, r, "customer_unmerge", func(svc CustomersService, v CustomersViewer, id, from string) (CustomerResult, error) { + return svc.Unmerge(v, id, from) + }) +} + +func (s *Server) customersMergeOrUnmerge(w http.ResponseWriter, r *http.Request, action string, do func(CustomersService, CustomersViewer, string, string) (CustomerResult, error)) { + v, ok := customersFullViewer(w, r) + if !ok { + return + } + svc, ok := s.customersService(w) + if !ok { + return + } + var body CustomerMergeRequest + if !decodeCustomersBody(w, r, &body) { + return + } + if strings.TrimSpace(body.From) == "" { + jsonError(w, "from is required", http.StatusBadRequest) + return + } + res, err := do(svc, v, r.PathValue("id"), body.From) + if err != nil { + s.customersError(w, r, err) + return + } + s.auditFromRequest(r, action, auditDetail("person", res.ID, "from", auditPersonID(body.From)), "") + jsonResponse(w, res.View) +} + +// auditPersonID keeps only what an id may hold, so a hand-made request +// cannot put free text in the audit log. +func auditPersonID(id string) string { + out := make([]byte, 0, len(id)) + for i := 0; i < len(id) && len(out) < customersAuditIDMax; i++ { + c := id[i] + if c >= 'a' && c <= 'z' || c >= '0' && c <= '9' || c == '_' { + out = append(out, c) + } + } + return string(out) +} + +func (s *Server) handleCustomersSplit(w http.ResponseWriter, r *http.Request) { + v, ok := customersFullViewer(w, r) + if !ok { + return + } + svc, ok := s.customersService(w) + if !ok { + return + } + var body CustomerSplitRequest + if !decodeCustomersBody(w, r, &body) { + return + } + if len(body.Identities) == 0 { + jsonError(w, "name at least one identity to split off", http.StatusBadRequest) + return + } + res, err := svc.Split(v, r.PathValue("id"), body.Identities, body.Name) + if err != nil { + s.customersError(w, r, err) + return + } + s.auditFromRequest(r, "customer_split", auditDetail("from", auditPersonID(r.PathValue("id")), "person", res.ID, "identities", strconv.Itoa(len(body.Identities))), "") + jsonResponse(w, res.View) +} + +// handleCustomersExport gives the owner everything held about one person as +// a JSON download. It is audited, since it moves personal data off the page. +func (s *Server) handleCustomersExport(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + v, ok := customersViewer(w, r) + if !ok { + return + } + svc, ok := s.customersService(w) + if !ok { + return + } + id := r.PathValue("id") + out, err := svc.Export(v, id) + if err != nil { + s.customersError(w, r, err) + return + } + s.auditFromRequest(r, "customer_export", auditDetail("person", auditPersonID(id)), "") + w.Header().Set("Content-Disposition", `attachment; filename="customer-export.json"`) + w.Header().Set("Cache-Control", "no-store") + jsonResponse(w, out) +} diff --git a/src/pkg/dashboard/api_customers_test.go b/src/pkg/dashboard/api_customers_test.go index 9e8578d826..075e4b8c75 100644 --- a/src/pkg/dashboard/api_customers_test.go +++ b/src/pkg/dashboard/api_customers_test.go @@ -69,6 +69,29 @@ func (f *fakeCustomersService) AnswerHint(v CustomersViewer, hid string, same bo return f.result("p_hinted", v) } +func (f *fakeCustomersService) Merge(v CustomersViewer, id, from string) (CustomerResult, error) { + f.note("Merge", v, id+"<-"+from) + return f.result(id, v) +} + +func (f *fakeCustomersService) Unmerge(v CustomersViewer, id, from string) (CustomerResult, error) { + f.note("Unmerge", v, id+"<-"+from) + return f.result(id, v) +} + +func (f *fakeCustomersService) Split(v CustomersViewer, id string, keys []string, name string) (CustomerResult, error) { + f.note("Split", v, id+":"+strings.Join(keys, ",")+":"+name) + return f.result("p_split", v) +} + +func (f *fakeCustomersService) Export(v CustomersViewer, id string) (any, error) { + f.note("Export", v, id) + if f.err != nil { + return nil, f.err + } + return map[string]any{"person": map[string]any{"id": id}, "edges": []any{}}, nil +} + func (f *fakeCustomersService) Dismiss(v CustomersViewer, sid string) error { f.note("Dismiss", v, sid) return f.err @@ -126,6 +149,10 @@ var ( custForget = customersRoute{http.MethodDelete, "/api/customers/p_other", ""} custAccept = customersRoute{http.MethodPost, "/api/customers/suggestions/s_1/accept", ""} custDismiss = customersRoute{http.MethodPost, "/api/customers/suggestions/s_1/dismiss", ""} + custMerge = customersRoute{http.MethodPost, "/api/customers/p_other/merge", `{"from":"p_src"}`} + custUnmerge = customersRoute{http.MethodPost, "/api/customers/p_other/unmerge", `{"from":"p_src"}`} + custSplit = customersRoute{http.MethodPost, "/api/customers/p_other/split", `{"identities":["email:a@b.c"],"name":"Split"}`} + custExport = customersRoute{http.MethodGet, "/api/customers/p_other/export", ""} custHint = customersRoute{http.MethodPost, "/api/customers/hints/h_1/answer", `{"same":true}`} ) @@ -150,6 +177,10 @@ func TestCustomersRoleMatrix(t *testing.T) { {custAccept, map[string]int{"owner": ok, "read-write": ok, "merger": ok, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, {custDismiss, map[string]int{"owner": ok, "read-write": ok, "merger": ok, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, {custHint, map[string]int{"owner": ok, "read-write": ok, "merger": ok, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, + {custMerge, map[string]int{"owner": ok, "read-write": ok, "merger": ok, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, + {custUnmerge, map[string]int{"owner": ok, "read-write": ok, "merger": ok, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, + {custSplit, map[string]int{"owner": ok, "read-write": ok, "merger": ok, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, + {custExport, map[string]int{"owner": ok, "read-write": forbidden, "merger": forbidden, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, {custForget, map[string]int{"owner": ok, "read-write": forbidden, "merger": forbidden, "read": forbidden, "unverified owner": forbidden, "read with no name": forbidden}}, } s, _ := apiServer(t) @@ -237,7 +268,7 @@ func TestCustomersOffAndErrors(t *testing.T) { if rec.Code != http.StatusOK || json.Unmarshal(rec.Body.Bytes(), &off) != nil || off["enabled"] != false { t.Fatalf("list while off = %d %s", rec.Code, rec.Body.String()) } - for _, r := range []customersRoute{custGetMe, custEditMe, custAdd, custForget, custAccept, custDismiss, custHint} { + for _, r := range []customersRoute{custGetMe, custEditMe, custAdd, custForget, custAccept, custDismiss, custHint, custMerge, custUnmerge, custSplit, custExport} { if rec := customersDo(s, custOwner, r.method, r.path, r.body); rec.Code != http.StatusServiceUnavailable { t.Errorf("%s %s while off = %d, want 503", r.method, r.path, rec.Code) } @@ -295,6 +326,10 @@ func TestCustomersAudit(t *testing.T) { {custReadWrite, custAccept}, {custReadWrite, custDismiss}, {custReadWrite, custHint}, + {custReadWrite, custMerge}, + {custReadWrite, custUnmerge}, + {custReadWrite, custSplit}, + {custOwner, custExport}, {custOwner, custForget}, } for _, st := range steps { @@ -310,8 +345,8 @@ func TestCustomersAudit(t *testing.T) { count++ } } - if count != 8 { - t.Fatalf("audited %d customer actions, want 8: %v", count, got) + if count != 12 { + t.Fatalf("audited %d customer actions, want 12: %v", count, got) } want := map[string]string{ "customer_profile_open": "olivia|person=p_other;", @@ -320,6 +355,10 @@ func TestCustomersAudit(t *testing.T) { "customer_accept": "rita|person=p_accepted;", "customer_dismiss": "rita|suggestion=s_1;", "customer_hint_answer": "rita|person=p_hinted, same=true;", + "customer_merge": "rita|person=p_other, from=p_src;", + "customer_unmerge": "rita|person=p_other, from=p_src;", + "customer_split": "rita|from=p_other, person=p_split, identities=1;", + "customer_export": "olivia|person=p_other;", } for action, detail := range want { if got[action] != detail { @@ -336,3 +375,41 @@ func TestCustomersAudit(t *testing.T) { t.Errorf("audit carries a written value: %v", got) } } + +func TestCustomersMergeSplitExportBodiesAndAudit(t *testing.T) { + s, _ := apiServer(t) + fake := &fakeCustomersService{} + s.SetCustomersService(fake) + for _, r := range []customersRoute{ + {http.MethodPost, "/api/customers/p_a/merge", `{}`}, + {http.MethodPost, "/api/customers/p_a/merge", `{not json`}, + {http.MethodPost, "/api/customers/p_a/unmerge", `{"from":" "}`}, + {http.MethodPost, "/api/customers/p_a/split", `{"identities":[]}`}, + {http.MethodPost, "/api/customers/p_a/split", `{}`}, + } { + if rec := customersDo(s, custOwner, r.method, r.path, r.body); rec.Code != http.StatusBadRequest { + t.Errorf("%s %s %s = %d, want 400", r.method, r.path, r.body, rec.Code) + } + } + if len(fake.calls) != 0 { + t.Fatalf("a malformed request reached the service: %v", fake.calls) + } + // An id copied into the audit line is cleaned and bounded. + rec := customersDo(s, custOwner, http.MethodPost, "/api/customers/p_a/merge", `{"from":"p_x\n