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.
Ruby agplai-assistantdockerdsgvogdprhotwireissue-trackerjira-alternativeknowledge-basellmmcp-servermeeting-notesopen-sourceproject-managementredmine-alternativeruby-on-railsself-hostedticketingtime-tracking
Read the people directory over /api/v1 for the terminal client
Guido Boykea7409f2b4156
diff --git a/.github/workflows/guards.yml b/.github/workflows/guards.ymlindex 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.rbspec/requests/api/v1/idempotency_spec.rbspec/requests/api/v1/capabilities_spec.rb+ spec/requests/api/v1/people_spec.rb+ spec/requests/api/people_parity_spec.rbspec/models/codebase_import_mapping_spec.rbspec/services/codebase_import/time_session_importer_spec.rbspec/services/codebase_import/duplicate_prevention_spec.rbdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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 theits 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 überdiff --git a/app/controllers/api/v1/people_controller.rb b/app/controllers/api/v1/people_controller.rbnew file mode 100644index 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+enddiff --git a/app/services/CLAUDE.md b/app/services/CLAUDE.mdindex 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; eineInstanz-`#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 thecard 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 demdiff --git a/app/services/api/v1/capabilities.rb b/app/services/api/v1/capabilities.rbindex 3663649..3d0da2d 100644--- a/app/services/api/v1/capabilities.rb+++ b/app/services/api/v1/capabilities.rb@@ -14,13 +14,16 @@ module Apimodule V1module 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.rbindex 7558c50..8559747 100644--- a/config/routes.rb+++ b/config/routes.rb@@ -925,7 +925,10 @@ Rails.application.routes.draw dopost :mark_all_as_readendend- 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]+ endget 'time_sessions/open', to: 'time_sessions#open'resources :projects, only: %i[index] doresources :tickets, only: %i[index create]diff --git a/spec/contracts/mcp_contract_recorder.rb b/spec/contracts/mcp_contract_recorder.rbindex 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}")}enddiff --git a/spec/fixtures/mcp_contract.json b/spec/fixtures/mcp_contract.jsonindex 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.rbnew file mode 100644index 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+enddiff --git a/spec/requests/api/v1/capabilities_spec.rb b/spec/requests/api/v1/capabilities_spec.rbindex 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 doit 'names the API version and the capabilities beside the existing fields' dodata = 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 doexpect(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')enddiff --git a/spec/requests/api/v1/people_spec.rb b/spec/requests/api/v1/people_spec.rbnew file mode 100644index 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+enddiff --git a/spec/requests/api/v1/pundit_tripwire_spec.rb b/spec/requests/api/v1/pundit_tripwire_spec.rbindex 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' doApi::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),