Skip to content

Self-hosted project management for devs and their clients: tickets, time tracking, docs and meetings, with an AI assistant that cites its sources. AGPL-3.0.

Read the people directory over /api/v1 for the terminal client

Guido Boykea7409f2b4156
diff --git a/.github/workflows/guards.yml b/.github/workflows/guards.yml
index 48a7501..782054e 100644
--- a/.github/workflows/guards.yml
+++ b/.github/workflows/guards.yml
@@ -292,6 +292,8 @@ jobs:
spec/requests/api/v1/error_codes_spec.rb
spec/requests/api/v1/idempotency_spec.rb
spec/requests/api/v1/capabilities_spec.rb
+ spec/requests/api/v1/people_spec.rb
+ spec/requests/api/people_parity_spec.rb
spec/models/codebase_import_mapping_spec.rb
spec/services/codebase_import/time_session_importer_spec.rb
spec/services/codebase_import/duplicate_prevention_spec.rb
diff --git a/CLAUDE.md b/CLAUDE.md
index 39f3085..b962798 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -815,6 +815,18 @@ reach, organisations AND projects, and only the rows the web time list shows the
its minutes, with `ticket: null`. Owner: `TimeSessions::OpenHours`; guard:
`spec/requests/api/v1/time_sessions_open_access_spec.rb`.
+`GET /api/v1/organisations/:organisation_id/people` and `.../people/:id` (People S3b) read
+the people directory through `People::Lookup`, the object the assistant's `find_people` /
+`get_person` and their MCP twins read as well: one rights question (the people right, 403
+without it), one search, one field selection (a list row never carries contact details or
+notes; the card carries the notes, MCP and the assistant never do). Only a token that
+reaches every project of the organisation reads its directory: a token limited to some
+projects, an organisation outside the token (a deactivated membership included) and a
+missing one answer the same 404, as do a missing and an invisible person. The list pages
+by 50, at most 100; a value outside is a 400, never cut. Guards:
+`spec/requests/api/v1/people_spec.rb`, `spec/requests/api/mcp_people_spec.rb`,
+`spec/requests/api/people_parity_spec.rb` (REST and MCP answer the same rows).
+
## Admin: Betreiber-Teile kommen nur über Schlitze
**Verbindlich** (Guard-Spec: `spec/architecture/admin_operator_boundary_guard_spec.rb`; läuft über
diff --git a/app/controllers/api/v1/people_controller.rb b/app/controllers/api/v1/people_controller.rb
new file mode 100644
index 0000000..c314202
--- /dev/null
+++ b/app/controllers/api/v1/people_controller.rb
@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Api
+ module V1
+ # The people directory of one organisation for a program such as the terminal client
+ # (People S3b): the list and the card of one person, read through People::Lookup like the
+ # assistant's tools and their MCP twins (cli_rest_plan D5), never through Person itself.
+ #
+ # * Reach (E1): only a token that reaches every project of the organisation reads its
+ # directory. A token limited to some projects, an organisation outside the token, a
+ # missing one and a malformed id answer the same 404.
+ # * Rights: the people right of the people page (PersonPolicy), 403 without it.
+ # * Fields: the list rows never carry contact details or notes, the card carries the notes
+ # (E2 B). A missing and an invisible person are the same 404.
+ # * Paging (E4): 50 rows by default, at most 100, with the total. A value outside is
+ # refused, not cut: a program would get fewer rows than it asked for without being told.
+ class PeopleController < BaseController
+ DEFAULT_PER_PAGE = 50
+ MAX_PER_PAGE = 100
+ # Far beyond any directory, so an absurd page number is refused rather than skipped to.
+ MAX_PAGE = 100_000
+
+ # A list parameter the endpoint cannot take (q, page, per_page).
+ class InvalidParameter < StandardError; end
+
+ rescue_from People::Lookup::Refused, with: :forbidden
+ rescue_from People::Lookup::InvalidArgument, InvalidParameter, with: :bad_request
+
+ # GET /api/v1/organisations/:organisation_id/people?q=&kind=&page=&per_page=
+ def index
+ with_directory do |people|
+ # The rows are policy-scoped inside People::Lookup (People::Directory reads
+ # PersonPolicy::Scope and MembershipPolicy::Scope itself); a policy_scope here would be
+ # a second copy nothing reads.
+ skip_policy_scope
+ page = whole_number(:page, default: 1, max: MAX_PAGE)
+ per_page = whole_number(:per_page, default: DEFAULT_PER_PAGE, max: MAX_PER_PAGE)
+ found = people.find(query: query, kind: params[:kind], limit: per_page, offset: (page - 1) * per_page)
+
+ render json: { data: found.entries.map { |entry| People::Lookup.row(entry) },
+ meta: { page: page, per_page: per_page, total: found.total } }
+ end
+ end
+
+ # GET /api/v1/organisations/:organisation_id/people/:id, the id as the list hands it out
+ # ("person:<uuid>" or "member:<uuid>").
+ def show
+ with_directory do |people|
+ entry = people.entry(params[:id]) || raise(ActiveRecord::RecordNotFound)
+
+ render json: { data: People::Lookup.card(entry, notes: true) }
+ end
+ end
+
+ private
+
+ # The reach (E1), then the organisation's tenant, then the people right, the order the
+ # MCP twins keep (PeopleTool.with_token_lookup). PersonPolicy#index? reads the tenant.
+ def with_directory
+ people = People::Lookup.for_token(reach: current_token.reach, viewer: current_user,
+ organisation_id: params[:organisation_id])
+ raise ActiveRecord::RecordNotFound if people.nil?
+
+ ActsAsTenant.with_tenant(people.organisation) do
+ authorize Person, :index?
+ yield people
+ end
+ end
+
+ def query
+ value = params[:q]
+ return nil if value.nil?
+ raise InvalidParameter, "invalid q #{value.inspect} (expected text)" unless value.is_a?(String)
+
+ value.strip
+ end
+
+ # A whole number from 1 to max; absent or blank is the default.
+ def whole_number(name, default:, max:)
+ raw = params[name]
+ return default if raw.nil? || raw == ''
+
+ number = Integer(raw, 10) if raw.is_a?(String) && raw.match?(/\A\d+\z/)
+ return number if number&.between?(1, max)
+
+ raise InvalidParameter, "invalid #{name} #{raw.inspect} (expected a whole number from 1 to #{max})"
+ end
+ end
+ end
+end
diff --git a/app/services/CLAUDE.md b/app/services/CLAUDE.md
index ca0b8df..ac6a67c 100644
--- a/app/services/CLAUDE.md
+++ b/app/services/CLAUDE.md
@@ -1,4 +1,4 @@
-# Karte: app/services (Stand: 2026-10-28)
+# Karte: app/services (Stand: 2026-10-29)
**Entry-Point-Konvention für NEUE Services: `Klass.call(**kwargs)`** (Klassenmethode; eine
Instanz-`#call`-Implementierung dahinter ist erlaubt). Pflicht: mindestens 1 Kommentarzeile
@@ -178,6 +178,17 @@ Verzeichnis-Übersicht (Auswahl):
directory (`#entries`, `#person_entry`, `#member_entry`); `#last_contacts_for` gives the
card of one entry the last contact the list attaches to every row. Map:
`lalabase/CLAUDE.md`.
+ S3b (29.10.2026): `lookup.rb` (`People::Lookup`) is the ONE read of the directory outside
+ the page, for three adapters: the assistant's two tools, their MCP twins and
+ `Api::V1::PeopleController`. It owns the rights question (`#allowed?`, asked again by
+ `#find` and `#entry` before anything is read: `Refused`), the search (the Directory's, with
+ `kind` checked instead of read as `all`: `InvalidArgument`), the id format and the ONE field
+ selection (`.row`, `.card(entry, notes:)`; `notes: true` only on the REST card, S3b E2), and
+ `.for_token` (E1: only an organisation whose every project the token reaches,
+ `Reach#project_ids_for(id).nil?`; else nil, so a project-limited token, an organisation
+ outside the token and a missing one look alike). The caller sets the tenant (the MCP twins
+ and the controller do, before `authorize Person, :index?`); paging is the REST
+ controller's (50, at most 100, a value outside refused).
* `notifications/` — Empfänger-Fanout, Broadcast, Scoring (eigene Karte im Ordner); dazu
`inbox_query.rb` + `serializer.rb`, der EINE Besitzer der Token-Inbox (Reichweite,
Argument-Vertrag, Zeilen-JSON), geteilt von `GET /api/v1/notifications` und dem
diff --git a/app/services/api/v1/capabilities.rb b/app/services/api/v1/capabilities.rb
index 3663649..3d0da2d 100644
--- a/app/services/api/v1/capabilities.rb
+++ b/app/services/api/v1/capabilities.rb
@@ -14,13 +14,16 @@ module Api
module V1
module Capabilities
# Minor for an additive change (a new endpoint, field or capability), major
- # never: an existing name, field or meaning does not change.
- API_VERSION = '1.1.0'
+ # never: an existing name, field or meaning does not change. 1.2.0: people.list and
+ # people.show (People S3b).
+ API_VERSION = '1.2.0'
# name => [verb, path as the router spells it]
ENDPOINTS = {
'me.show' => ['GET', '/api/v1/me'],
'organisations.list' => ['GET', '/api/v1/organisations'],
+ 'people.list' => ['GET', '/api/v1/organisations/:organisation_id/people'],
+ 'people.show' => ['GET', '/api/v1/organisations/:organisation_id/people/:id'],
'projects.list' => ['GET', '/api/v1/projects'],
'projects.ticket_attribute_definitions' => ['GET', '/api/v1/projects/:id/ticket_attribute_definitions'],
'tickets.list' => ['GET', '/api/v1/projects/:project_id/tickets'],
diff --git a/config/routes.rb b/config/routes.rb
index 7558c50..8559747 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -925,7 +925,10 @@ Rails.application.routes.draw do
post :mark_all_as_read
end
end
- resources :organisations, only: %i[index]
+ resources :organisations, only: %i[index] do
+ # People S3b: the people directory of one organisation, read only.
+ resources :people, only: %i[index show]
+ end
get 'time_sessions/open', to: 'time_sessions#open'
resources :projects, only: %i[index] do
resources :tickets, only: %i[index create]
diff --git a/spec/contracts/mcp_contract_recorder.rb b/spec/contracts/mcp_contract_recorder.rb
index 125ec9a..cbef45f 100644
--- a/spec/contracts/mcp_contract_recorder.rb
+++ b/spec/contracts/mcp_contract_recorder.rb
@@ -536,7 +536,46 @@ module McpContract
# answer per error code, then a write with an Idempotency-Key, its replay
# and the key reused with another body.
'errors' => rest_error_calls,
- 'idempotency' => rest_idempotency_calls
+ 'idempotency' => rest_idempotency_calls,
+ # People S3b, appended last: the directory of people_world, made before the MCP calls.
+ 'GET /api/v1/organisations/:organisation_id/people' => rest_people_list_calls,
+ 'GET /api/v1/organisations/:organisation_id/people/:id' => rest_people_show_calls
+ }
+ end
+
+ def rest_people_list_calls
+ people_world
+ path = "/api/v1/organisations/#{id(:organisation)}/people"
+ {
+ 'ok' => rest_get(:read, path),
+ 'ok_query' => rest_get(:read, "#{path}?q=techn"),
+ 'ok_paged' => rest_get(:read, "#{path}?kind=members&per_page=1&page=2"),
+ 'empty' => rest_get(:read, "#{path}?q=niemand"),
+ 'invalid_input' => rest_get(:read, "#{path}?per_page=101"),
+ 'invalid_input_kind' => rest_get(:read, "#{path}?kind=member"),
+ # Dora is a member without the people right.
+ 'forbidden' => rest_get(:dora, path),
+ # Anna is no member there: outside the token, like a missing organisation.
+ 'not_found' => rest_get(:read, "/api/v1/organisations/#{id(:other_organisation)}/people"),
+ 'not_found_project_token' => rest_get(:limited, path),
+ 'unauthorized' => rest_get(nil, path)
+ }
+ end
+
+ def rest_people_show_calls
+ people_world
+ path = "/api/v1/organisations/#{id(:organisation)}/people"
+ doris = "person:#{id(:doris_person)}"
+ {
+ 'ok' => rest_get(:read, "#{path}/#{doris}"),
+ 'ok_member' => rest_get(:read, "#{path}/member:#{id(:ben)}"),
+ 'not_found' => rest_get(:read, "#{path}/person:#{id(:missing)}"),
+ # Dora is a member Anna does not see: answered like a missing person.
+ 'hidden' => rest_get(:read, "#{path}/member:#{id(:dora)}"),
+ 'invalid_input' => rest_get(:read, "#{path}/abc"),
+ 'forbidden' => rest_get(:dora, "#{path}/#{doris}"),
+ 'not_found_organisation' => rest_get(:read, "/api/v1/organisations/#{id(:other_organisation)}/people/#{doris}"),
+ 'not_found_project_token' => rest_get(:limited, "#{path}/#{doris}")
}
end
diff --git a/spec/fixtures/mcp_contract.json b/spec/fixtures/mcp_contract.json
index da861af..3b5906d 100644
--- a/spec/fixtures/mcp_contract.json
+++ b/spec/fixtures/mcp_contract.json
@@ -1,9 +1,9 @@
{
"header": {
"regenerate": "RAILS_ENV=test bin/rails mcp:contract",
- "core_commit": "aaddafbae770235d4978fe1e74050971bce2b6f0",
+ "core_commit": "c56a11b8820f9cb5f8d664fc9f0c433aedd30018",
"core_dirty": true,
- "contract_sha256": "f02188653864371cac510aa771011dd50f166e391741e7d945ea305b7033a256"
+ "contract_sha256": "463a72a9a78b957137b04184d6d5a5cc2c2a549412257495d5a72ae7ada865ac"
},
"contract": {
"mcp": {
@@ -3654,7 +3654,7 @@
"all_projects": true
}
],
- "api_version": "1.1.0",
+ "api_version": "1.2.0",
"capabilities": [
"error_codes",
"idempotency",
@@ -3664,6 +3664,8 @@
"notifications.mark_all_as_read",
"notifications.mark_as_read",
"organisations.list",
+ "people.list",
+ "people.show",
"posts.create",
"projects.list",
"projects.ticket_attribute_definitions",
@@ -3711,7 +3713,7 @@
"all_projects": true
}
],
- "api_version": "1.1.0",
+ "api_version": "1.2.0",
"capabilities": [
"error_codes",
"idempotency",
@@ -3721,6 +3723,8 @@
"notifications.mark_all_as_read",
"notifications.mark_as_read",
"organisations.list",
+ "people.list",
+ "people.show",
"posts.create",
"projects.list",
"projects.ticket_attribute_definitions",
@@ -4253,6 +4257,343 @@
}
}
}
+ },
+ "GET /api/v1/organisations/:organisation_id/people": {
+ "ok": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people"
+ },
+ "response": {
+ "status": 200,
+ "body": {
+ "data": [
+ {
+ "id": "member:00000000-0000-4000-8000-000000000011",
+ "name": "Anna Albers",
+ "kind": "member",
+ "function": null,
+ "department": null,
+ "company": null,
+ "last_contact": {
+ "on": "2026-01-05",
+ "kind": "ticket"
+ }
+ },
+ {
+ "id": "member:00000000-0000-4000-8000-000000000012",
+ "name": "Ben Berger",
+ "kind": "member",
+ "function": "Entwicklung",
+ "department": null,
+ "company": null,
+ "last_contact": null
+ },
+ {
+ "id": "person:00000000-0000-4000-8000-000000000091",
+ "name": "Doris Dienstleister",
+ "kind": "contact",
+ "function": "Technische Ansprechpartnerin",
+ "department": "Technik",
+ "company": "Hosting AG",
+ "last_contact": null
+ }
+ ],
+ "meta": {
+ "page": 1,
+ "per_page": 50,
+ "total": 3
+ }
+ }
+ }
+ },
+ "ok_query": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people?q=techn"
+ },
+ "response": {
+ "status": 200,
+ "body": {
+ "data": [
+ {
+ "id": "person:00000000-0000-4000-8000-000000000091",
+ "name": "Doris Dienstleister",
+ "kind": "contact",
+ "function": "Technische Ansprechpartnerin",
+ "department": "Technik",
+ "company": "Hosting AG",
+ "last_contact": null
+ }
+ ],
+ "meta": {
+ "page": 1,
+ "per_page": 50,
+ "total": 1
+ }
+ }
+ }
+ },
+ "ok_paged": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people?kind=members&per_page=1&page=2"
+ },
+ "response": {
+ "status": 200,
+ "body": {
+ "data": [
+ {
+ "id": "member:00000000-0000-4000-8000-000000000012",
+ "name": "Ben Berger",
+ "kind": "member",
+ "function": "Entwicklung",
+ "department": null,
+ "company": null,
+ "last_contact": null
+ }
+ ],
+ "meta": {
+ "page": 2,
+ "per_page": 1,
+ "total": 2
+ }
+ }
+ }
+ },
+ "empty": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people?q=niemand"
+ },
+ "response": {
+ "status": 200,
+ "body": {
+ "data": [],
+ "meta": {
+ "page": 1,
+ "per_page": 50,
+ "total": 0
+ }
+ }
+ }
+ },
+ "invalid_input": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people?per_page=101"
+ },
+ "response": {
+ "status": 400,
+ "body": {
+ "error": "bad_request",
+ "code": "invalid_input",
+ "message": "invalid per_page \"101\" (expected a whole number from 1 to 100)"
+ }
+ }
+ },
+ "invalid_input_kind": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people?kind=member"
+ },
+ "response": {
+ "status": 400,
+ "body": {
+ "error": "bad_request",
+ "code": "invalid_input",
+ "message": "kind must be one of: all, members, contacts"
+ }
+ }
+ },
+ "forbidden": {
+ "token": "dora",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people"
+ },
+ "response": {
+ "status": 403,
+ "body": {
+ "error": "forbidden",
+ "code": "forbidden"
+ }
+ }
+ },
+ "not_found": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000002/people"
+ },
+ "response": {
+ "status": 404,
+ "body": {
+ "error": "not_found",
+ "code": "not_found"
+ }
+ }
+ },
+ "not_found_project_token": {
+ "token": "limited",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people"
+ },
+ "response": {
+ "status": 404,
+ "body": {
+ "error": "not_found",
+ "code": "not_found"
+ }
+ }
+ },
+ "unauthorized": {
+ "token": "invalid",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people"
+ },
+ "response": {
+ "status": 401,
+ "body": {
+ "error": "unauthorized",
+ "code": "unauthorized"
+ }
+ }
+ }
+ },
+ "GET /api/v1/organisations/:organisation_id/people/:id": {
+ "ok": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people/person:00000000-0000-4000-8000-000000000091"
+ },
+ "response": {
+ "status": 200,
+ "body": {
+ "data": {
+ "id": "person:00000000-0000-4000-8000-000000000091",
+ "name": "Doris Dienstleister",
+ "kind": "contact",
+ "function": "Technische Ansprechpartnerin",
+ "department": "Technik",
+ "company": "Hosting AG",
+ "last_contact": null,
+ "salutation": "Frau",
+ "email": "[email protected]",
+ "phone": "+49 30 1234567",
+ "additional_details": [
+ {
+ "label": "Mobil",
+ "value": "+49 170 1234567"
+ }
+ ],
+ "notes": "Nur vormittags anrufen."
+ }
+ }
+ }
+ },
+ "ok_member": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people/member:00000000-0000-4000-8000-000000000012"
+ },
+ "response": {
+ "status": 200,
+ "body": {
+ "data": {
+ "id": "member:00000000-0000-4000-8000-000000000012",
+ "name": "Ben Berger",
+ "kind": "member",
+ "function": "Entwicklung",
+ "department": null,
+ "company": null,
+ "last_contact": null,
+ "salutation": null,
+ "email": "[email protected]",
+ "phone": "+49 30 7654321",
+ "additional_details": [],
+ "notes": null
+ }
+ }
+ }
+ },
+ "not_found": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people/person:00000000-0000-4000-8000-000000000999"
+ },
+ "response": {
+ "status": 404,
+ "body": {
+ "error": "not_found",
+ "code": "not_found"
+ }
+ }
+ },
+ "hidden": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people/member:00000000-0000-4000-8000-000000000014"
+ },
+ "response": {
+ "status": 404,
+ "body": {
+ "error": "not_found",
+ "code": "not_found"
+ }
+ }
+ },
+ "invalid_input": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people/abc"
+ },
+ "response": {
+ "status": 400,
+ "body": {
+ "error": "bad_request",
+ "code": "invalid_input",
+ "message": "invalid id (expected \"person:<uuid>\" or \"member:<uuid>\")"
+ }
+ }
+ },
+ "forbidden": {
+ "token": "dora",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people/person:00000000-0000-4000-8000-000000000091"
+ },
+ "response": {
+ "status": 403,
+ "body": {
+ "error": "forbidden",
+ "code": "forbidden"
+ }
+ }
+ },
+ "not_found_organisation": {
+ "token": "read",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000002/people/person:00000000-0000-4000-8000-000000000091"
+ },
+ "response": {
+ "status": 404,
+ "body": {
+ "error": "not_found",
+ "code": "not_found"
+ }
+ }
+ },
+ "not_found_project_token": {
+ "token": "limited",
+ "request": {
+ "path": "/api/v1/organisations/00000000-0000-4000-8000-000000000001/people/person:00000000-0000-4000-8000-000000000091"
+ },
+ "response": {
+ "status": 404,
+ "body": {
+ "error": "not_found",
+ "code": "not_found"
+ }
+ }
+ }
}
}
}
diff --git a/spec/requests/api/people_parity_spec.rb b/spec/requests/api/people_parity_spec.rb
new file mode 100644
index 0000000..68f764e
--- /dev/null
+++ b/spec/requests/api/people_parity_spec.rb
@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+# What: the REST people list and MCP find_people answer the same rows for the same data, and
+# the REST card is the MCP card plus the notes (People S3b).
+# Why: two surfaces for one question become two answers as soon as one of them builds its
+# own rows (cli_rest_plan, risk "two answers"). Both go through People::Lookup.row and
+# .card; this compares what reaches the wire, last contacts included.
+RSpec.describe 'People on REST and MCP', :ci_guard, type: :request do
+ let(:organisation) { create(:organisation) }
+ let(:user) { create(:user, first_name: 'Anna', last_name: 'Albers') }
+ let(:colleague) { create(:user, first_name: 'Carl', last_name: 'Kollege') }
+ let(:project) { ActsAsTenant.with_tenant(organisation) { create(:project, organisation: organisation) } }
+ let(:contact) do
+ ActsAsTenant.with_tenant(organisation) do
+ create(:person, organisation: organisation, name: 'Doris Dienstleister', salutation: 'Frau',
+ function: 'Leitung IT', department: 'Technik', company: 'Hosting AG',
+ email: '[email protected]', phone: '+49 30 1234567', notes: 'Nur vormittags anrufen.',
+ additional_details: [{ 'kind' => 'url', 'label' => '', 'value' => 'https://example.com' }])
+ end
+ end
+
+ before do
+ Prosopite.pause do
+ ActsAsTenant.with_tenant(organisation) do
+ role = create(:role, organisation: organisation)
+ create(:permission, role: role, category: 'people', action: 'view_people', allowed: true)
+ create(:membership, user: user, organisation: organisation, role: role, active: true)
+ create(:membership, user: colleague, organisation: organisation, role: create(:role, organisation: organisation),
+ active: true)
+ create(:project_permission, user: user, project: project, tickets_access: :read_only, meetings_access: :read_only)
+ create(:project_permission, user: colleague, project: project, tickets_access: :read_only)
+ create(:person, organisation: organisation, user: colleague, name: 'C. K.', function: 'Einkauf', phone: '+49 30 7654321')
+ create(:person, organisation: organisation, name: 'Jürgen Müller', company: 'Nordlicht AG')
+ # A last contact of each kind: a meeting for the contact, own ticket work for the member.
+ meeting = create(:meeting, organisation: organisation, project: project, occurred_at: 4.days.ago)
+ create(:meeting_participant, meeting: meeting, person: contact, display_name: 'Gast')
+ ticket = create(:ticket, organisation: organisation, project: project)
+ Activity.create!(actor: colleague, trackable: ticket, organisation: organisation, action: 'created',
+ parameters: { 'skip_notifications' => true }, created_at: 2.days.ago)
+ end
+ end
+ end
+
+ let(:pat) do
+ build(:personal_access_token, user: user, organisations: [organisation]).tap do |token|
+ token.token_hash = nil
+ token.token_prefix = nil
+ token.generate_token!
+ end
+ end
+
+ def rest(path, **query)
+ get "/api/v1/organisations/#{organisation.id}/people#{path}", params: query,
+ headers: { 'Authorization' => "Bearer #{pat.token}" }
+ expect(response).to have_http_status(:ok)
+ response.parsed_body['data']
+ end
+
+ def mcp(tool, **arguments)
+ post '/api/mcp', params: { jsonrpc: '2.0', id: 1, method: 'tools/call',
+ params: { name: tool, arguments: arguments.merge(organisation_id: organisation.id) } }.to_json,
+ headers: { 'Authorization' => "Bearer #{pat.token}", 'CONTENT_TYPE' => 'application/json' }
+ result = response.parsed_body['result']
+ expect(result['isError']).to be_falsey, result.inspect
+ JSON.parse(result.dig('content', 0, 'text'))
+ end
+
+ it 'lists the same rows on both, last contacts included' do
+ rows = rest('')
+
+ expect(rows.pluck('name')).to eq(['Anna Albers', 'Carl Kollege', 'Doris Dienstleister', 'Jürgen Müller'])
+ expect(rows.filter_map { |row| row['last_contact']&.fetch('kind') }).to contain_exactly('meeting', 'ticket')
+ expect(mcp('find_people')['data']).to eq(rows)
+ end
+
+ it 'searches and filters alike' do
+ expect(mcp('find_people', query: 'mueller')['data']).to eq(rest('', q: 'mueller'))
+ expect(mcp('find_people', kind: 'contacts')['data']).to eq(rest('', kind: 'contacts'))
+ end
+
+ it 'gives the REST card the MCP card plus the notes' do
+ card = rest("/person:#{contact.id}")
+
+ expect(card.except('notes')).to eq(mcp('get_person', id: "person:#{contact.id}"))
+ expect(card['notes']).to eq('Nur vormittags anrufen.')
+ expect(rest("/member:#{colleague.id}").except('notes')).to eq(mcp('get_person', id: "member:#{colleague.id}"))
+ end
+end
diff --git a/spec/requests/api/v1/capabilities_spec.rb b/spec/requests/api/v1/capabilities_spec.rb
index 6526449..8348aa0 100644
--- a/spec/requests/api/v1/capabilities_spec.rb
+++ b/spec/requests/api/v1/capabilities_spec.rb
@@ -33,7 +33,7 @@ RSpec.describe 'API V1 capabilities', :ci_guard, type: :request do
it 'names the API version and the capabilities beside the existing fields' do
data = me(token(read_only: false))
- expect(data['api_version']).to eq('1.1.0')
+ expect(data['api_version']).to eq('1.2.0')
expect(data['capabilities']).to eq(Api::V1::Capabilities.names)
expect(data.keys).to include('user', 'token', 'scoped_organisations')
end
@@ -46,7 +46,7 @@ RSpec.describe 'API V1 capabilities', :ci_guard, type: :request do
expect(Api::V1::Capabilities.names).to include(
'me.show', 'organisations.list', 'projects.list', 'tickets.list', 'tickets.create', 'tickets.show',
'tickets.update', 'tickets.attachments', 'posts.create', 'time_sessions.create',
- 'notifications.list', 'notifications.mark_as_read', 'idempotency', 'error_codes'
+ 'notifications.list', 'notifications.mark_as_read', 'people.list', 'people.show', 'idempotency', 'error_codes'
)
end
diff --git a/spec/requests/api/v1/people_spec.rb b/spec/requests/api/v1/people_spec.rb
new file mode 100644
index 0000000..433c271
--- /dev/null
+++ b/spec/requests/api/v1/people_spec.rb
@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+# What: GET /api/v1/organisations/:organisation_id/people and .../people/:id (People S3b), the
+# people directory for the terminal client, read through People::Lookup like the assistant.
+# Why: a token must read no person beyond the people page of its owner and no organisation
+# beyond its reach: not an organisation outside the token, not with a token limited to some
+# projects (E1), not without the people right, not a member of a project the owner cannot
+# see, not across the two organisations of one token. Notes only on the card, never in the
+# list (E2). A missing and an invisible person answer the same 404, body included; the list
+# pages by 50 and at most 100 (E4), and a value outside is refused, not cut.
+RSpec.describe 'API V1 people', :ci_guard, type: :request do
+ let(:organisation) { create(:organisation, name: 'Nordlicht GmbH') }
+ let(:other_organisation) { create(:organisation, name: 'Fremdfirma AG') }
+
+ def role_in(org, *actions)
+ ActsAsTenant.with_tenant(org) do
+ role = create(:role, organisation: org)
+ actions.each { |action| create(:permission, role: role, category: 'people', action: action, allowed: true) }
+ role
+ end
+ end
+
+ def member_of(org, user, role:)
+ ActsAsTenant.with_tenant(org) { create(:membership, user: user, organisation: org, role: role, active: true) }
+ end
+
+ let(:user) { create(:user, first_name: 'Anna', last_name: 'Albers', email: '[email protected]') }
+ let(:colleague) { create(:user, first_name: 'Carl', last_name: 'Kollege', email: '[email protected]') }
+ let(:stranger) { create(:user, first_name: 'Sven', last_name: 'Fremd', email: '[email protected]') }
+ let(:project) { ActsAsTenant.with_tenant(organisation) { create(:project, organisation: organisation) } }
+ let(:hidden_project) { ActsAsTenant.with_tenant(organisation) { create(:project, organisation: organisation) } }
+ let(:contact) do
+ ActsAsTenant.with_tenant(organisation) do
+ create(:person, organisation: organisation, name: 'Doris Dienstleister', salutation: 'Frau',
+ function: 'Leitung IT', department: 'Technik', company: 'Hosting AG',
+ email: '[email protected]', phone: '+49 30 1234567', notes: 'Nur vormittags anrufen.',
+ additional_details: [{ 'kind' => 'phone', 'label' => 'Mobil', 'value' => '+49 170 1234567' }])
+ end
+ end
+ let(:hidden_row) { ActsAsTenant.with_tenant(organisation) { Person.find_by!(user: stranger) } }
+ let(:foreign_contact) do
+ ActsAsTenant.with_tenant(other_organisation) do
+ create(:person, organisation: other_organisation, name: 'Olga Andere', notes: 'Fremde Notiz')
+ end
+ end
+
+ before do
+ Prosopite.pause do
+ member_of(organisation, user, role: role_in(organisation, 'view_people'))
+ plain = role_in(organisation)
+ member_of(organisation, colleague, role: plain)
+ member_of(organisation, stranger, role: plain)
+ member_of(other_organisation, user, role: role_in(other_organisation, 'view_people'))
+ ActsAsTenant.with_tenant(organisation) do
+ create(:project_permission, user: user, project: project, tickets_access: :read_only)
+ create(:project_permission, user: colleague, project: project, tickets_access: :read_only)
+ create(:project_permission, user: stranger, project: hidden_project, tickets_access: :read_only)
+ create(:person, organisation: organisation, user: colleague, name: 'C. Kollege (alt)', function: 'Einkauf',
+ email: '[email protected]', notes: 'Bevorzugt Mail.')
+ create(:person, organisation: organisation, user: stranger, name: 'Sven Fremd', function: 'Fremdes Projekt')
+ end
+ contact
+ foreign_contact
+ end
+ end
+
+ def token(organisations: [organisation], project_scopes: {}, read_only: true, owner: user)
+ build(:personal_access_token, user: owner, organisations: organisations, project_scopes: project_scopes,
+ read_only: read_only).tap do |pat|
+ pat.token_hash = nil
+ pat.token_prefix = nil
+ pat.generate_token!
+ end
+ end
+
+ let(:pat) { token }
+
+ def list(with: pat, organisation_id: organisation.id, **query)
+ get "/api/v1/organisations/#{organisation_id}/people", params: query,
+ headers: { 'Authorization' => "Bearer #{with.token}" }
+ response
+ end
+
+ def show(id, with: pat, organisation_id: organisation.id)
+ get "/api/v1/organisations/#{organisation_id}/people/#{id}", headers: { 'Authorization' => "Bearer #{with.token}" }
+ response
+ end
+
+ def body = response.parsed_body
+
+ def names = body['data'].pluck('name')
+
+ def not_found_body = { 'error' => 'not_found', 'code' => 'not_found' }
+
+ describe 'the list' do
+ # A read: the default token is read-only and reads.
+ it 'lists the people the owner sees, sorted by name, over a read-only token' do
+ expect(pat.read_only?).to be true
+
+ expect(list).to have_http_status(:ok)
+ expect(names).to eq(['Anna Albers', 'Carl Kollege', 'Doris Dienstleister'])
+ expect(body['data'].pluck('id')).to eq(["member:#{user.id}", "member:#{colleague.id}", "person:#{contact.id}"])
+ expect(body['meta']).to eq('page' => 1, 'per_page' => 50, 'total' => 3)
+ end
+
+ it 'carries the list fields only, never contact details or the notes' do
+ list(q: 'doris')
+
+ expect(body['data'].first.keys)
+ .to contain_exactly('id', 'name', 'kind', 'function', 'department', 'company', 'last_contact')
+ expect(response.body).not_to include('Nur vormittags anrufen.', '[email protected]', '+49 30 1234567')
+ end
+
+ it 'searches and filters as the people page does' do
+ list(q: 'techn')
+ expect(names).to eq(['Doris Dienstleister'])
+ list(kind: 'members')
+ expect(names).to eq(['Anna Albers', 'Carl Kollege'])
+ list(kind: 'contacts', q: 'hosting')
+ expect(names).to eq(['Doris Dienstleister'])
+ end
+
+ it 'answers no match with an empty list and its total' do
+ expect(list(q: 'zzz')).to have_http_status(:ok)
+ expect(body).to eq('data' => [], 'meta' => { 'page' => 1, 'per_page' => 50, 'total' => 0 })
+ end
+
+ it 'leaves out a member of a project the owner cannot see, and that member\'s row' do
+ list
+
+ expect(names).not_to include('Sven Fremd')
+ expect(response.body).not_to include('Fremdes Projekt', stranger.id)
+ end
+
+ it 'refuses a kind it does not know, a query that is no text, with invalid_input' do
+ list(kind: 'member')
+ expect(response).to have_http_status(:bad_request)
+ expect(body).to eq('error' => 'bad_request', 'code' => 'invalid_input',
+ 'message' => 'kind must be one of: all, members, contacts')
+
+ get "/api/v1/organisations/#{organisation.id}/people?q[]=doris", headers: { 'Authorization' => "Bearer #{pat.token}" }
+ expect(response).to have_http_status(:bad_request)
+ expect(body).to include('code' => 'invalid_input')
+ end
+ end
+
+ # E4: pages of 50 by default, at most 100. A value outside is refused: a cut would hand a
+ # program fewer rows than it asked for without saying so.
+ describe 'paging' do
+ def contacts(count)
+ Prosopite.pause do
+ ActsAsTenant.with_tenant(organisation) do
+ count.times { |index| create(:person, organisation: organisation, name: format('Zora Zusatz %03d', index)) }
+ end
+ end
+ end
+
+ it 'pages the list and counts every match' do
+ list(per_page: 1, page: 2)
+
+ expect(names).to eq(['Carl Kollege'])
+ expect(body['meta']).to eq('page' => 2, 'per_page' => 1, 'total' => 3)
+ end
+
+ it 'answers a page past the end with no rows and the total' do
+ list(page: 2)
+
+ expect(body).to eq('data' => [], 'meta' => { 'page' => 2, 'per_page' => 50, 'total' => 3 })
+ end
+
+ it 'shows 50 rows by default and 100 at most' do
+ contacts(101)
+
+ list(q: 'zusatz')
+ expect(body['data'].size).to eq(50)
+ expect(body['meta']).to eq('page' => 1, 'per_page' => 50, 'total' => 101)
+
+ list(q: 'zusatz', per_page: 100)
+ expect(body['data'].size).to eq(100)
+ list(q: 'zusatz', per_page: 100, page: 2)
+ expect(names).to eq(['Zora Zusatz 100'])
+ end
+
+ { per_page: ['101', '0', '-1', 'x', '1.5'], page: ['0', '-1', 'x', '100001'] }.each do |name, values|
+ values.each do |value|
+ it "refuses #{name}=#{value} with invalid_input" do
+ list(name => value)
+
+ expect(response).to have_http_status(:bad_request)
+ expect(body).to include('error' => 'bad_request', 'code' => 'invalid_input')
+ expect(body['message']).to include(name.to_s)
+ end
+ end
+ end
+ end
+
+ describe 'the card' do
+ it 'carries the card fields and the notes as stored' do
+ expect(show("person:#{contact.id}")).to have_http_status(:ok)
+
+ expect(body['data'].keys).to contain_exactly('id', 'name', 'kind', 'salutation', 'function', 'department',
+ 'company', 'email', 'phone', 'additional_details',
+ 'last_contact', 'notes')
+ expect(body['data']).to include('name' => 'Doris Dienstleister', 'email' => '[email protected]',
+ 'phone' => '+49 30 1234567', 'notes' => 'Nur vormittags anrufen.',
+ 'additional_details' => [{ 'label' => 'Mobil', 'value' => '+49 170 1234567' }])
+ end
+
+ it 'answers blank notes with null' do
+ ActsAsTenant.with_tenant(organisation) { contact.update!(notes: '') }
+
+ show("person:#{contact.id}")
+ expect(body['data']).to include('notes' => nil)
+ end
+
+ it 'takes a member\'s name and email from the account, the notes from the row' do
+ show("member:#{colleague.id}")
+
+ expect(body['data']).to include('id' => "member:#{colleague.id}", 'name' => 'Carl Kollege', 'kind' => 'member',
+ 'email' => '[email protected]', 'notes' => 'Bevorzugt Mail.')
+ end
+
+ it 'answers a missing, a foreign and an invisible person with the same 404' do
+ ids = ["person:#{SecureRandom.uuid}", "member:#{SecureRandom.uuid}", "person:#{foreign_contact.id}",
+ "person:#{hidden_row.id}", "member:#{stranger.id}"]
+
+ answers = Prosopite.pause do
+ ids.map do |id|
+ show(id)
+ [response.status, response.body]
+ end
+ end
+
+ expect(answers.uniq).to eq([[404, not_found_body.to_json]])
+ end
+
+ %w[abc person:abc new member:12345].each do |id|
+ it "refuses the id #{id} with invalid_input" do
+ show(id)
+
+ expect(response).to have_http_status(:bad_request)
+ expect(body).to eq('error' => 'bad_request', 'code' => 'invalid_input',
+ 'message' => 'invalid id (expected "person:<uuid>" or "member:<uuid>")')
+ end
+ end
+ end
+
+ # E1: only a token that reaches every project of the organisation reads its directory.
+ # Outside it, limited to some projects, missing or malformed: one 404, body included.
+ describe 'the organisation' do
+ def expect_not_found
+ expect(response).to have_http_status(:not_found)
+ expect(body).to eq(not_found_body)
+ end
+
+ it 'answers an organisation outside the token like a missing one, on both endpoints' do
+ outside = create(:organisation)
+ member_of(outside, user, role: role_in(outside, 'view_people'))
+
+ # Eight requests from one line read like an N+1 to Prosopite; each is one request.
+ Prosopite.pause do
+ [other_organisation.id, outside.id, SecureRandom.uuid, 'oops'].each do |id|
+ list(organisation_id: id)
+ expect_not_found
+ show("person:#{contact.id}", organisation_id: id)
+ expect_not_found
+ end
+ end
+ end
+
+ it 'answers a token limited to some projects of the organisation like an organisation outside it' do
+ limited = token(project_scopes: { organisation => [project] })
+
+ list(with: limited)
+ expect_not_found
+ show("person:#{contact.id}", with: limited)
+ expect_not_found
+ end
+
+ # The token stops reaching an organisation in which its owner is deactivated
+ # (PersonalAccessToken#organisation_scopes): a 404 like an organisation outside it.
+ it 'answers a deactivated member like an organisation outside the token' do
+ ActsAsTenant.with_tenant(organisation) { Membership.find_by!(user: user, organisation: organisation).update!(active: false) }
+
+ list
+ expect_not_found
+ show("person:#{contact.id}")
+ expect_not_found
+ end
+
+ it 'takes the organisation id in capitals as well' do
+ expect(list(organisation_id: organisation.id.upcase)).to have_http_status(:ok)
+ end
+ end
+
+ describe 'rights' do
+ it 'answers an owner without the people right with 403 forbidden, on both endpoints' do
+ plain = token(owner: colleague)
+
+ list(with: plain)
+ expect(response).to have_http_status(:forbidden)
+ expect(body).to eq('error' => 'forbidden', 'code' => 'forbidden')
+ show("person:#{contact.id}", with: plain)
+ expect(response).to have_http_status(:forbidden)
+ expect(body).to eq('error' => 'forbidden', 'code' => 'forbidden')
+ end
+
+ it 'asks the right before it looks at the parameters' do
+ plain = token(owner: colleague)
+
+ expect(list(with: plain, per_page: '500')).to have_http_status(:forbidden)
+ expect(show('abc', with: plain)).to have_http_status(:forbidden)
+ end
+ end
+
+ describe 'two organisations, one token' do
+ let(:both) { token(organisations: [organisation, other_organisation]) }
+
+ it 'lists the people of the organisation asked for and nobody of the other' do
+ list(with: both)
+ expect(names).to eq(['Anna Albers', 'Carl Kollege', 'Doris Dienstleister'])
+ expect(response.body).not_to include('Olga Andere', foreign_contact.id)
+
+ list(with: both, organisation_id: other_organisation.id)
+ expect(names).to eq(['Anna Albers', 'Olga Andere'])
+ expect(response.body).not_to include('Doris Dienstleister', contact.id)
+ end
+
+ it 'reads a person only in the organisation it belongs to' do
+ show("person:#{foreign_contact.id}", with: both, organisation_id: other_organisation.id)
+ expect(body['data']).to include('name' => 'Olga Andere', 'notes' => 'Fremde Notiz')
+
+ show("person:#{foreign_contact.id}", with: both)
+ expect(response).to have_http_status(:not_found)
+ show("person:#{contact.id}", with: both, organisation_id: other_organisation.id)
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+end
diff --git a/spec/requests/api/v1/pundit_tripwire_spec.rb b/spec/requests/api/v1/pundit_tripwire_spec.rb
index 97d01d2..db88cba 100644
--- a/spec/requests/api/v1/pundit_tripwire_spec.rb
+++ b/spec/requests/api/v1/pundit_tripwire_spec.rb
@@ -26,7 +26,8 @@ RSpec.describe 'Api::V1 Pundit-Tripwire' do
Api::V1::TicketsController,
Api::V1::ProjectsController,
Api::V1::PostsController,
- Api::V1::TimeSessionsController
+ Api::V1::TimeSessionsController,
+ Api::V1::PeopleController
].each do |controller|
expect(after_action_filters(controller))
.to include(:verify_authorized, :verify_policy_scoped),