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
fix: refuse an MCP idempotency_key the store cannot hold before the write
Guido Boyke8087ff2059c6
diff --git a/.github/workflows/guards.yml b/.github/workflows/guards.ymlindex 84658dc..aaed374 100644--- a/.github/workflows/guards.yml+++ b/.github/workflows/guards.yml@@ -266,6 +266,8 @@ jobs:spec/requests/api/mcp_plain_comment_spec.rbspec/requests/api/mcp_time_report_spec.rbspec/requests/api/mcp_people_spec.rb+ spec/requests/api/mcp_idempotency_key_bound_spec.rb+ spec/services/mcp/idempotency_store_spec.rbspec/services/posts/plain_text_body_spec.rbspec/services/lalabase/tools/post_comment_spec.rbspec/services/lalabase/tools/post_comment_failure_spec.rbdiff --git a/CLAUDE.md b/CLAUDE.mdindex 53b5325..39c9b18 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -809,7 +809,12 @@ feature by feature):body), another request answers 422 `idempotency_key_reused`. Same table and store as MCP(`Mcp::IdempotencyStore`); the REST fingerprint includes method and path, so a key nevercrosses surfaces. Runs inside authentication and the read-only gate. A key is at most 255- bytes of valid UTF-8 without NUL (else: 422 `invalid_idempotency_key`, nothing written). A replay checks no rights+ bytes of valid UTF-8 without NUL (else: 422 `invalid_idempotency_key`, nothing written).+ One rule for both surfaces, `Mcp::IdempotencyStore.client_key` (strip, blank is no key) and+ `.storable_key?`: since MCP 0.13.1 a write tool refuses such an `idempotency_key` as+ `invalid_input` before it runs, after the project and read-only gates (guard+ `spec/requests/api/mcp_idempotency_key_bound_spec.rb`; it used to write, fail to remember+ the key with -32603 and write again on every retry). A replay checks no rights(it repeats what the same token already got; keys do not expire), and a retry must sendthe same bytes. Every write route must be `idempotent`(`spec/architecture/api_v1_writes_idempotent_guard_spec.rb`).diff --git a/app/controllers/concerns/api/v1/idempotent.rb b/app/controllers/concerns/api/v1/idempotent.rbindex 6accc2d..38dca16 100644--- a/app/controllers/concerns/api/v1/idempotent.rb+++ b/app/controllers/concerns/api/v1/idempotent.rb@@ -33,10 +33,6 @@ module ApiHEADER = 'Idempotency-Key'MISMATCH = 'idempotency_key_reused'INVALID_KEY = 'invalid_idempotency_key'- # Bytes. The unique index on (token, key) holds about 2.7 KB, and the key is- # stored only AFTER the write: a longer key wrote, failed to be stored with- # a 500, and wrote again on every retry. Refused before anything runs.- MAX_KEY_LENGTH = 255included do# The actions this controller declared, read by@@ -54,10 +50,14 @@ module Apiprivate+ # A key the store cannot hold (Mcp::IdempotencyStore.storable_key?, the rule+ # the MCP writes ask too) is refused before anything runs: the key is stored+ # only AFTER the write, so a key too long for the index wrote, failed to be+ # stored with a 500, and wrote again on every retry.def with_idempotency_key- key = request.headers[HEADER].to_s.strip.presence+ key = Mcp::IdempotencyStore.client_key(request.headers[HEADER])return yield unless key- return render_invalid_idempotency_key unless storable_key?(key)+ return render_invalid_idempotency_key unless Mcp::IdempotencyStore.storable_key?(key)store = Mcp::IdempotencyStore.new(token: current_token, tool_name: "rest:#{controller_path}##{action_name}",key: key, args: idempotency_fingerprint_args)@@ -69,13 +69,6 @@ module Apistore.remember({ status: response.status, body: response.body }.to_json) if response.successful?end- # Within the index (bytes) and storable in a PostgreSQL text column: valid- # UTF-8 without NUL, which the database refuses with an error otherwise.- def storable_key?(key)- utf8 = key.dup.force_encoding(Encoding::UTF_8)- key.bytesize <= MAX_KEY_LENGTH && utf8.valid_encoding? && !utf8.include?("\0")- end-def idempotency_fingerprint_args{ 'method' => request.request_method, 'path' => request.path,'params' => request.query_parameters.merge(request.request_parameters) }@@ -93,7 +86,7 @@ module Apidef render_invalid_idempotency_keyskip_authorizationrender_error(error: INVALID_KEY, code: 'invalid_input',- message: "#{HEADER} must be valid UTF-8 without NUL, at most #{MAX_KEY_LENGTH} bytes",+ message: Mcp::IdempotencyStore.unstorable_key_message(HEADER),status: :unprocessable_entity)enddiff --git a/app/services/lalabase/CLAUDE.md b/app/services/lalabase/CLAUDE.mdindex 21ddfb1..0c63657 100644--- a/app/services/lalabase/CLAUDE.md+++ b/app/services/lalabase/CLAUDE.md@@ -110,6 +110,13 @@ Codebase-Verständnis.und `data: []`. Wer das `:mcp`-Set ändert, erneuert den Vertrag`spec/fixtures/mcp_contract.json` mit `RAILS_ENV=test bin/rails mcp:contract` und hebt`Mcp::Dispatcher::SERVER_VERSION` (Minor); die Vertrags-Spec vergleicht nur.+ The seam answers some errors itself, before any tool runs, in this order: `project_id`+ missing (`invalid_input`), a project out of reach (`not_found`), a write over a read-only+ token (`read_only`), then (MCP 0.13.1) an `idempotency_key` the store cannot hold: more+ than 255 bytes, no valid UTF-8 or a NUL (`invalid_input`). The key is remembered only+ after the write, so such a key used to write, fail with -32603 and write again on the+ retry. The rule is `Mcp::IdempotencyStore`'s, shared with the REST header; a read tool is+ not offered the key and ignores it. Guard: `spec/requests/api/mcp_idempotency_key_bound_spec.rb`.* `indexer/` — Codebase-Indizierung (befüllt `project_index`, `code_symbol`, `fragment`)* `project_rag/` — Retrieval für projektbezogene Chats; org-Threads (S3a T3) nurContent-Schicht über `Fragment.for_context_map` (je Area verengte Projektmenge)diff --git a/app/services/mcp/dispatcher.rb b/app/services/mcp/dispatcher.rbindex 12ce714..ade73b8 100644--- a/app/services/mcp/dispatcher.rb+++ b/app/services/mcp/dispatcher.rb@@ -46,7 +46,9 @@ module Mcp# 0.12 = summarize_time_sessions (terminal client S6: the booked time of a# ticket). 0.13 = find_people and get_person (People S3b: the people directory,# for a token that reaches every project of the organisation named).- SERVER_VERSION = '0.13.0'+ # 0.13.1 = a key the store cannot hold (more than 255 bytes, no valid UTF-8,+ # a NUL) is refused as invalid_input before the write, as REST does since R0.+ SERVER_VERSION = '0.13.1'# MCP surface — sourced from the single tool registry (D6): the :mcp set is the# ONE definition of this surface, so a registry refactor can't drift it (R3);@@ -114,7 +116,7 @@ module Mcp# :token) the reach comes from the token and `project_id` is an optional# filter, advertised only to a tool that reads it (project_filter?). Mutating# tools also get an optional `idempotency_key` so a client retry can't- # double-write (D9).+ # double-write (D9); its description names the bound ToolCall holds it to.def mcp_input_schema(tool_class)schema = tool_class.input_schema.deep_dupschema[:properties] ||= {}@@ -136,7 +138,8 @@ module Mcpschema[:properties][:idempotency_key] = {type: 'string',description: 'Optional. Repeating a write with the same key returns the ' \- 'original result instead of creating a duplicate.'+ 'original result instead of creating a duplicate. At most ' \+ "#{IdempotencyStore::MAX_KEY_LENGTH} bytes of valid UTF-8 without NUL."}endschemadiff --git a/app/services/mcp/idempotency_store.rb b/app/services/mcp/idempotency_store.rbindex 2b3df8c..1ba13a7 100644--- a/app/services/mcp/idempotency_store.rb+++ b/app/services/mcp/idempotency_store.rb@@ -29,12 +29,49 @@ module Mcp## Keys are scoped per PAT (token + key is the unique constraint), so they cannot# collide or leak across tokens.+ #+ # WHICH KEY the store can hold is decided here, once, for both surfaces+ # (.client_key, .storable_key?): the REST header and the MCP argument are read+ # and bounded by the same rule, and each surface refuses a key outside it+ # BEFORE the write, in its own envelope (422 invalid_idempotency_key,+ # invalid_input).class IdempotencyStoreMISMATCH_ERROR = 'idempotency_key already used with different parameters'+ # Bytes, not characters. The unique index on (token, key) holds about 2.7 KB,+ # and the key is stored only AFTER the write: a longer key wrote, failed to+ # be stored with an error, and wrote again on every retry.+ MAX_KEY_LENGTH = 255++ # The key a client sent, read the same way on both surfaces: surrounding+ # whitespace dropped (String#strip, which drops a NUL at either end too), and+ # a blank key is no key (nil). Bytes that are no valid UTF-8 come back as+ # sent, for .storable_key? to refuse: String#strip raises on them. A REST+ # header arrives as binary, which is always a valid encoding.+ def self.client_key(raw)+ key = raw.to_s+ return key unless key.valid_encoding?++ key.strip.presence+ end++ # Within the index (bytes) and storable in a PostgreSQL text column: valid+ # UTF-8 without NUL, which the database refuses with an error otherwise.+ # Takes a key from .client_key; a binary one is read as the UTF-8 it claims.+ def self.storable_key?(key)+ utf8 = key.dup.force_encoding(Encoding::UTF_8)+ key.bytesize <= MAX_KEY_LENGTH && utf8.valid_encoding? && !utf8.include?("\0")+ end++ # The refusal of a key outside .storable_key?, naming the field the surface+ # reads it from (the REST header, the MCP argument).+ def self.unstorable_key_message(field)+ "#{field} must be valid UTF-8 without NUL, at most #{MAX_KEY_LENGTH} bytes"+ end# @param token [PersonalAccessToken]# @param tool_name [String] for the audit column only- # @param key [String] the client-supplied idempotency key+ # @param key [String] the client-supplied idempotency key, read by+ # .client_key and accepted by .storable_key?# @param args [Hash] the request args the key dedupes (already minus the key);# its fingerprint detects a key reused with a DIFFERENT payload.def initialize(token:, tool_name:, key:, args:)diff --git a/app/services/mcp/tool_call.rb b/app/services/mcp/tool_call.rbindex ff7d38b..9991f4d 100644--- a/app/services/mcp/tool_call.rb+++ b/app/services/mcp/tool_call.rb@@ -19,7 +19,8 @@ module Mcp# `project_id` as an optional filter argument, runs WITHOUT an ambient tenant# (its query names the organisations explicitly) and, being record-mode by# registry rule, marks its own authorization decision or the tripwire fires.- # The read-only gate (D3) and the idempotency replay apply to both modes.+ # The read-only gate (D3), the bound on the idempotency key and the replay+ # apply to both modes.## A project the token cannot access is reported exactly like a missing one — no# existence leak (mirrors Api::TokenAuthenticatable's RecordNotFound-on-scope-miss).@@ -65,7 +66,14 @@ module Mcp# central to the seam, so no individual write tool can forget it.return error_response('This token is read-only; writes are not permitted.', code: :read_only) if write_blocked?- run_tool(project)+ # A key the store cannot hold is refused before the write, after the two+ # gates above, so it says nothing about a project the token cannot see.+ # The key is remembered only after the write: one too long for the index+ # wrote, failed to be remembered (-32603) and wrote again on every retry.+ key = idempotency_key+ return unstorable_key_response if key && !IdempotencyStore.storable_key?(key)++ run_tool(project, key)rescue Pundit::NotAuthorizedError# Expected per-record denial (D2): the actor may not touch this record.# Reported as a clean tool error — never a leak, never a 500.@@ -88,19 +96,14 @@ module Mcp# Project mode runs under the project's tenant. Token mode (project nil) runs# without one: the tool's query filters organisations explicitly, an ambient# tenant would only hide one organisation's rows from a multi-org token.- def run_tool(project)- return run_in_place(project) if project.nil?+ def run_tool(project, key)+ return run_in_place(project, key) if project.nil?- ActsAsTenant.with_tenant(project.organisation) { run_in_place(project) }+ ActsAsTenant.with_tenant(project.organisation) { run_in_place(project, key) }end- def run_in_place(project)- key = idempotency_key- result = if key && @tool_class.mutating?- execute_idempotently(project, key)- else- execute_tool(project)- end+ def run_in_place(project, key)+ result = key ? execute_idempotently(project, key) : execute_tool(project)result_to_response(result)end@@ -146,8 +149,15 @@ module Mcpresultend+ # The client's key, read as REST reads its header (IdempotencyStore.client_key),+ # or nil. Only a write has one: a read tool is not offered the argument and+ # ignores it, whatever it holds.def idempotency_key- @args[IDEMPOTENCY_KEY].to_s.strip.presence+ IdempotencyStore.client_key(@args[IDEMPOTENCY_KEY]) if @tool_class.mutating?+ end++ def unstorable_key_response+ error_response(IdempotencyStore.unstorable_key_message(IDEMPOTENCY_KEY), code: :invalid_input)end# Audit/provenance (D9): every write attempt logs PAT id + origin, so andiff --git a/spec/contracts/mcp_contract_recorder.rb b/spec/contracts/mcp_contract_recorder.rbindex 0b807e8..4b2308c 100644--- a/spec/contracts/mcp_contract_recorder.rb+++ b/spec/contracts/mcp_contract_recorder.rb@@ -347,7 +347,24 @@ module McpContract'summarize_time_sessions' => time_report_calls(website, foreign),# People S3b, appended last for the same reason (people_world).'find_people' => find_people_calls,- 'get_person' => get_person_calls+ 'get_person' => get_person_calls,+ # MCP 0.13.1, appended last: refusals that write nothing, so every+ # answer after them stays as it was.+ 'idempotency_key' => idempotency_key_calls(website)+ }+ end++ # A key the store cannot hold is refused before the write (MCP 0.13.1).+ # Each from its own line (Prosopite), without `record`: nothing is written+ # and no clock moves. 256 bytes; 128 umlauts, which are 256 bytes in 128+ # characters (the bound counts bytes); a NUL inside the key. A key that is+ # no valid UTF-8 cannot be written into this file.+ def idempotency_key_calls(website)+ args = { project_id: website, ticket_id: id(:login_ticket), body: 'Hallo' }+ {+ 'too_long' => tool_call(:write, 'post_comment', **args, idempotency_key: 'k' * 256),+ 'too_long_multibyte' => tool_call(:write, 'post_comment', **args, idempotency_key: 'ä' * 128),+ 'nul' => tool_call(:write, 'post_comment', **args, idempotency_key: "k#{0.chr}x")}enddiff --git a/spec/fixtures/mcp_contract.json b/spec/fixtures/mcp_contract.jsonindex 1fd50c9..9c1f929 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": "1a16f823f40cab62f11c3e5c929a6912bda0c95b",+ "core_commit": "2f87d5b662836551f6a43591d9aa7d93655563de","core_dirty": true,- "contract_sha256": "80e07918e69c341f6079cc26d11f2144c73593178faa6cde0d6d616058c1f282"+ "contract_sha256": "b8d6c57cd4d33f09c2486752caee010263dece063d025bed80273520e61602de"},"contract": {"mcp": {@@ -42,7 +42,7 @@},"serverInfo": {"name": "lalabase",- "version": "0.13.0"+ "version": "0.13.1"}}}@@ -357,7 +357,7 @@},"idempotency_key": {"type": "string",- "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate."+ "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate. At most 255 bytes of valid UTF-8 without NUL."}},"required": [@@ -399,7 +399,7 @@},"idempotency_key": {"type": "string",- "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate."+ "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate. At most 255 bytes of valid UTF-8 without NUL."}},"required": [@@ -486,7 +486,7 @@},"idempotency_key": {"type": "string",- "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate."+ "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate. At most 255 bytes of valid UTF-8 without NUL."}},"required": [@@ -508,7 +508,7 @@},"idempotency_key": {"type": "string",- "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate."+ "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate. At most 255 bytes of valid UTF-8 without NUL."}},"required": [@@ -555,7 +555,7 @@},"idempotency_key": {"type": "string",- "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate."+ "description": "Optional. Repeating a write with the same key returns the original result instead of creating a duplicate. At most 255 bytes of valid UTF-8 without NUL."}},"required": [@@ -3619,6 +3619,116 @@}}}+ },+ "idempotency_key": {+ "too_long": {+ "token": "write",+ "request": {+ "jsonrpc": "2.0",+ "id": 1,+ "method": "tools/call",+ "params": {+ "name": "post_comment",+ "arguments": {+ "project_id": "00000000-0000-4000-8000-000000000031",+ "ticket_id": "00000000-0000-4000-8000-000000000041",+ "body": "Hallo",+ "idempotency_key": "kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"+ }+ }+ },+ "response": {+ "status": 200,+ "body": {+ "jsonrpc": "2.0",+ "id": 1,+ "result": {+ "content": [+ {+ "type": "text",+ "text": "idempotency_key must be valid UTF-8 without NUL, at most 255 bytes"+ }+ ],+ "isError": true,+ "_meta": {+ "lalabase/code": "invalid_input"+ }+ }+ }+ }+ },+ "too_long_multibyte": {+ "token": "write",+ "request": {+ "jsonrpc": "2.0",+ "id": 1,+ "method": "tools/call",+ "params": {+ "name": "post_comment",+ "arguments": {+ "project_id": "00000000-0000-4000-8000-000000000031",+ "ticket_id": "00000000-0000-4000-8000-000000000041",+ "body": "Hallo",+ "idempotency_key": "ääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääääää"+ }+ }+ },+ "response": {+ "status": 200,+ "body": {+ "jsonrpc": "2.0",+ "id": 1,+ "result": {+ "content": [+ {+ "type": "text",+ "text": "idempotency_key must be valid UTF-8 without NUL, at most 255 bytes"+ }+ ],+ "isError": true,+ "_meta": {+ "lalabase/code": "invalid_input"+ }+ }+ }+ }+ },+ "nul": {+ "token": "write",+ "request": {+ "jsonrpc": "2.0",+ "id": 1,+ "method": "tools/call",+ "params": {+ "name": "post_comment",+ "arguments": {+ "project_id": "00000000-0000-4000-8000-000000000031",+ "ticket_id": "00000000-0000-4000-8000-000000000041",+ "body": "Hallo",+ "idempotency_key": "k\u0000x"+ }+ }+ },+ "response": {+ "status": 200,+ "body": {+ "jsonrpc": "2.0",+ "id": 1,+ "result": {+ "content": [+ {+ "type": "text",+ "text": "idempotency_key must be valid UTF-8 without NUL, at most 255 bytes"+ }+ ],+ "isError": true,+ "_meta": {+ "lalabase/code": "invalid_input"+ }+ }+ }+ }+ }}}},diff --git a/spec/requests/api/mcp_idempotency_key_bound_spec.rb b/spec/requests/api/mcp_idempotency_key_bound_spec.rbnew file mode 100644index 0000000..a859d21--- /dev/null+++ b/spec/requests/api/mcp_idempotency_key_bound_spec.rb@@ -0,0 +1,325 @@+# frozen_string_literal: true++require 'rails_helper'++# What: an MCP write whose idempotency_key the store cannot hold (more than+# 255 bytes, bytes that are no valid UTF-8, a NUL) is refused as+# invalid_input before the tool runs: nothing written, nothing remembered. A+# key the store can hold works as before: the write lands once and a retry+# replays it.+# Type: request spec through /api/mcp, the gates of Mcp::ToolCall included.+# Why: the key is remembered only AFTER the write. A key too long for the unique+# index wrote, failed to be remembered (-32603) and wrote again on every+# retry; a key with a NUL or with bytes that are no UTF-8 ended in -32603.+# REST refuses such a key since R0, and both surfaces ask one rule+# (Mcp::IdempotencyStore). The project gate and the read-only gate still+# answer first, so the refusal tells nothing about a project the token cannot+# see.+#+# The write tools come from the registry, not from a list kept here: a write+# tool added to the surface fails this spec until it has a call in+# #write_calls.+#+# Security spec: tagged :ci_guard and listed in .github/workflows/guards.yml.+RSpec.describe 'MCP writes and an idempotency_key the store cannot hold', :ci_guard, type: :request do+ let(:organisation) { create(:organisation) }+ let(:other_organisation) { create(:organisation) }+ let(:user) { create(:user) }+ let(:role) { create(:role, organisation: organisation) }++ let!(:membership) do+ ActsAsTenant.with_tenant(organisation) do+ create(:membership, user: user, organisation: organisation, role: role, active: true)+ end+ end++ let(:project) { ActsAsTenant.with_tenant(organisation) { create(:project, organisation: organisation) } }++ let!(:project_permission) do+ ActsAsTenant.with_tenant(organisation) do+ create(:project_permission, user: user, project: project, tickets_access: :read_write)+ end+ end++ let!(:time_session_permission) do+ ActsAsTenant.with_tenant(organisation) do+ TimeSessionPermission.create!(user: user, project: project, can_create_own: true)+ end+ end++ let(:ticket) do+ ActsAsTenant.with_tenant(organisation) do+ create(:ticket, project: project, organisation: organisation, creator: user, title: 'Login bricht ab')+ end+ end++ let(:notification) do+ ActsAsTenant.with_tenant(organisation) do+ create(:notification, recipient: user, organisation: organisation, notifiable: ticket, state: 'queued')+ end+ end++ def build_pat(read_only:)+ token = build(:personal_access_token, user: user, organisations: [organisation], read_only: read_only)+ token.token_hash = nil+ token.token_prefix = nil+ token.generate_token!+ token+ end++ let(:write_pat) { build_pat(read_only: false) }+ let(:read_pat) { build_pat(read_only: true) }++ let(:refusal) { 'idempotency_key must be valid UTF-8 without NUL, at most 255 bytes' }+ let(:invalid_input) { { 'lalabase/code' => 'invalid_input' } }++ write_tools = Lalabase::Tools::Registry::MCP.select(&:mutating?)++ # One call per write tool that writes, and a reading of what it writes: the+ # reading changes when the write lands. Built in full for every example, so+ # the records the calls name exist before anything is measured.+ def write_calls+ {+ 'create_ticket' => [{ project_id: project.id, title: 'Neu angelegt' }, -> { Ticket.count }],+ 'post_comment' => [{ project_id: project.id, ticket_id: ticket.id, body: 'Hallo' }, -> { Post.count }],+ 'create_time_session' => [{ project_id: project.id, ticket_id: ticket.id, duration: '0:30' },+ -> { TimeSession.count }],+ 'mark_notification_read' => [{ notification_id: notification.id }, -> { notification.reload.state }],+ 'update_ticket' => [{ project_id: project.id, ticket_id: ticket.id, title: 'Neuer Titel' },+ -> { ticket.reload.title }]+ }+ end++ def reading_of(tool_name)+ reading = write_calls.fetch(tool_name).last+ ActsAsTenant.without_tenant { reading.call }+ end++ def remembered_keys+ McpIdempotencyKey.order(:created_at).pluck(:idempotency_key)+ end++ def rpc(tool_name, arguments)+ { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: tool_name, arguments: arguments } }.to_json+ end++ # The JSON-RPC `result`, or the whole body when there is none (a protocol+ # error such as -32603), so a failure shows what came back.+ def post_body(token, body, content_type: 'application/json')+ post '/api/mcp', params: body,+ headers: { 'Authorization' => "Bearer #{token.token}", 'CONTENT_TYPE' => content_type }+ parsed = JSON.parse(response.body)+ parsed.fetch('result', parsed)+ end++ def call_tool(token, tool_name, arguments)+ post_body(token, rpc(tool_name, arguments))+ end++ # JSON cannot be generated around bytes that are no UTF-8: the body is built+ # around a marker, and the marker is replaced by the raw bytes, or by the+ # JSON escape of a lone low surrogate, which the parser turns into such bytes.+ # Sent as text/plain: in a body sent as JSON, Rails refuses such bytes itself+ # (see 'a JSON body with bytes that are no UTF-8'), while the endpoint reads+ # the raw body whatever its type, so this is the way they reach the seam.+ def call_tool_with_raw_key(token, tool_name, arguments, raw, content_type: 'text/plain')+ post_body(token, raw_key_body(tool_name, arguments, raw), content_type: content_type)+ end++ def raw_key_body(tool_name, arguments, raw)+ marker = 'RAW-KEY-MARKER'+ rpc(tool_name, arguments.merge(idempotency_key: marker)).b.sub(marker, raw.b)+ end++ def text_of(result)+ result.dig('content', 0, 'text')+ end++ def expect_refused(result, tool_name, before)+ expect(result['isError']).to be(true)+ expect(result['_meta']).to eq(invalid_input)+ expect(text_of(result)).to eq(refusal)+ expect(reading_of(tool_name)).to eq(before)+ expect(remembered_keys).to be_empty+ end++ it 'has a write call for every write tool of the surface, and none for a tool that does not write' do+ expect(write_tools).not_to be_empty+ expect(write_calls.keys).to match_array(write_tools.map(&:tool_name))+ end++ write_tools.each do |tool|+ describe tool.tool_name do+ let(:arguments) { write_calls.fetch(tool.tool_name).first }++ it 'refuses a key of 256 bytes as invalid_input, writing and remembering nothing' do+ before = reading_of(tool.tool_name)+ expect_refused(call_tool(write_pat, tool.tool_name, arguments.merge(idempotency_key: 'k' * 256)),+ tool.tool_name, before)+ end++ # 128 characters, 256 bytes: the limit counts bytes.+ it 'refuses 128 umlauts, counting bytes and not characters' do+ before = reading_of(tool.tool_name)+ expect_refused(call_tool(write_pat, tool.tool_name, arguments.merge(idempotency_key: 'ä' * 128)),+ tool.tool_name, before)+ end++ it 'refuses a key with a NUL inside' do+ before = reading_of(tool.tool_name)+ expect_refused(call_tool(write_pat, tool.tool_name, arguments.merge(idempotency_key: "k#{0.chr}x")),+ tool.tool_name, before)+ end++ it 'refuses a key with bytes that are no UTF-8' do+ before = reading_of(tool.tool_name)+ expect_refused(call_tool_with_raw_key(write_pat, tool.tool_name, arguments, "k\xFFx".b),+ tool.tool_name, before)+ end++ it 'refuses a key the JSON parser turns into bytes that are no UTF-8 (a lone low surrogate)' do+ before = reading_of(tool.tool_name)+ expect_refused(call_tool_with_raw_key(write_pat, tool.tool_name, arguments, 'k\\udc00x'),+ tool.tool_name, before)+ end++ # 127 umlauts and one letter: 255 bytes, 128 characters.+ it 'writes and remembers a key of 255 bytes, umlauts included, and replays it without running again' do+ key = "#{'ä' * 127}k"+ before = reading_of(tool.tool_name)++ first = call_tool(write_pat, tool.tool_name, arguments.merge(idempotency_key: key))+ expect(first['isError']).to be_falsey+ expect(reading_of(tool.tool_name)).not_to eq(before)+ expect(remembered_keys).to eq([key])++ expect(tool).not_to receive(:execute)+ again = call_tool(write_pat, tool.tool_name, arguments.merge(idempotency_key: key))+ expect(text_of(again)).to eq(text_of(first))+ expect(remembered_keys).to eq([key])+ end+ end+ end++ describe 'reading the key' do+ let(:comment) { write_calls.fetch('post_comment').first }++ it 'drops surrounding whitespace before it counts, so 255 bytes between spaces are a key' do+ key = 'k' * 255+ before = reading_of('post_comment')++ first = call_tool(write_pat, 'post_comment', comment.merge(idempotency_key: " #{key}\t"))+ expect(first['isError']).to be_falsey+ expect(remembered_keys).to eq([key])++ again = call_tool(write_pat, 'post_comment', comment.merge(idempotency_key: key))+ expect(text_of(again)).to eq(text_of(first))+ expect(reading_of('post_comment')).to eq(before + 1)+ end++ it 'treats a blank key as none: writes on every call and remembers nothing' do+ before = reading_of('post_comment')+ first = call_tool(write_pat, 'post_comment', comment.merge(idempotency_key: ' '))+ second = call_tool(write_pat, 'post_comment', comment.merge(idempotency_key: ''))++ expect([first['isError'], second['isError']]).to all(be_falsey)+ expect(reading_of('post_comment')).to eq(before + 2)+ expect(remembered_keys).to be_empty+ end++ # The failure the bound exists for: a random key of 4 KB does not fit the+ # unique index. It used to write, fail to be remembered with -32603 and+ # write again on the retry.+ it 'refuses a key far beyond the index before the write, so its retry cannot write twice' do+ key = SecureRandom.hex(2048)+ before = reading_of('post_comment')++ first = call_tool(write_pat, 'post_comment', comment.merge(idempotency_key: key))+ retry_answer = call_tool(write_pat, 'post_comment', comment.merge(idempotency_key: key))++ expect([first, retry_answer].map { |result| result['_meta'] }).to all(eq(invalid_input))+ expect(reading_of('post_comment')).to eq(before)+ expect(remembered_keys).to be_empty+ end+ end++ # Rails reads a body sent as JSON before the endpoint runs and refuses such+ # bytes there: nothing reaches the seam. Pinned so the text/plain detour of+ # the examples above keeps its reason.+ describe 'a JSON body with bytes that are no UTF-8' do+ it 'is refused by Rails with 400 before the endpoint, writing and remembering nothing' do+ before = reading_of('post_comment')+ post '/api/mcp', params: raw_key_body('post_comment', write_calls.fetch('post_comment').first, "k\xFFx".b),+ headers: { 'Authorization' => "Bearer #{write_pat.token}", 'CONTENT_TYPE' => 'application/json' }++ expect(response).to have_http_status(:bad_request)+ expect(reading_of('post_comment')).to eq(before)+ expect(remembered_keys).to be_empty+ end+ end++ # The project gate and the read-only gate answer before the key: a key the+ # store cannot hold must not turn a foreign project or a read-only token into+ # an answer of its own.+ describe 'the gates before the key' do+ let(:comment) { write_calls.fetch('post_comment').first }+ let(:foreign_project) do+ ActsAsTenant.with_tenant(other_organisation) { create(:project, organisation: other_organisation) }+ end++ it 'answers a read-only token with read_only, writing nothing' do+ before = reading_of('post_comment')+ result = call_tool(read_pat, 'post_comment', comment.merge(idempotency_key: 'k' * 256))++ expect(result['isError']).to be(true)+ expect(result['_meta']).to eq('lalabase/code' => 'read_only')+ expect(reading_of('post_comment')).to eq(before)+ end++ it 'answers a read-only token on the token-scoped write with read_only, leaving the row unread' do+ result = call_tool(read_pat, 'mark_notification_read',+ { notification_id: notification.id, idempotency_key: 'k' * 256 })++ expect(result['_meta']).to eq('lalabase/code' => 'read_only')+ expect(notification.reload.state).to eq('queued')+ end++ it 'answers a read-only token with read_only for a key that is no UTF-8' do+ result = call_tool_with_raw_key(read_pat, 'post_comment', comment, "k\xFFx".b)++ expect(result['_meta']).to eq('lalabase/code' => 'read_only')+ end++ it 'answers a project of another organisation as with any key: not_found' do+ foreign = comment.merge(project_id: foreign_project.id)+ long = call_tool(write_pat, 'post_comment', foreign.merge(idempotency_key: 'k' * 256))+ short = call_tool(write_pat, 'post_comment', foreign.merge(idempotency_key: 'k'))++ expect(long['_meta']).to eq('lalabase/code' => 'not_found')+ expect(long).to eq(short)+ end++ it 'answers a project that does not exist as with any key: not_found' do+ missing = comment.merge(project_id: SecureRandom.uuid)+ result = call_tool_with_raw_key(write_pat, 'post_comment', missing, "k\xFFx".b)++ expect(result['_meta']).to eq('lalabase/code' => 'not_found')+ expect(text_of(result)).to eq('Project not found or not accessible.')+ end+ end++ # A read tool is not offered the argument and ignores whatever it holds.+ describe 'a read tool' do+ it 'ignores a key of 256 bytes' do+ result = call_tool(read_pat, 'list_tickets', { project_id: project.id, idempotency_key: 'k' * 256 })++ expect(result['_meta']).to eq('lalabase/kind' => 'ok')+ end++ it 'ignores a key with bytes that are no UTF-8' do+ result = call_tool_with_raw_key(read_pat, 'list_tickets', { project_id: project.id }, "k\xFFx".b)++ expect(result['_meta']).to eq('lalabase/kind' => 'ok')+ end+ end+enddiff --git a/spec/requests/api/v1/idempotency_spec.rb b/spec/requests/api/v1/idempotency_spec.rbindex fd50352..def3f6c 100644--- a/spec/requests/api/v1/idempotency_spec.rb+++ b/spec/requests/api/v1/idempotency_spec.rb@@ -161,7 +161,7 @@ RSpec.describe 'API V1 idempotency', :ci_guard, type: :request do# The unique index on (token, key) holds about 2.7 KB; a longer key used to# write, fail to be stored with a 500, and write again on every retry.it 'refuses a key longer than the limit before writing' do- long = 'k' * (Api::V1::Idempotent::MAX_KEY_LENGTH + 1)+ long = 'k' * (Mcp::IdempotencyStore::MAX_KEY_LENGTH + 1)expect { comment('Hallo', key: long) }.not_to(change { posts_count })expect(response).to have_http_status(:unprocessable_content)expect(response.parsed_body).to include('error' => 'invalid_idempotency_key', 'code' => 'invalid_input')@@ -191,7 +191,7 @@ RSpec.describe 'API V1 idempotency', :ci_guard, type: :request doendit 'accepts a key of exactly the limit' do- key = 'k' * Api::V1::Idempotent::MAX_KEY_LENGTH+ key = 'k' * Mcp::IdempotencyStore::MAX_KEY_LENGTHexpect { 2.times { comment('Hallo', key: key) } }.to change { posts_count }.by(1)endenddiff --git a/spec/services/mcp/idempotency_store_spec.rb b/spec/services/mcp/idempotency_store_spec.rbindex c6b3f40..f633314 100644--- a/spec/services/mcp/idempotency_store_spec.rb+++ b/spec/services/mcp/idempotency_store_spec.rb@@ -2,7 +2,16 @@require 'rails_helper'-RSpec.describe Mcp::IdempotencyStore do+# What: the idempotency store of the MCP and /api/v1 writes, and the one rule+# of which key it can hold (.client_key, .storable_key?), asked by both+# surfaces before a write runs.+# Why: the key is stored only after the write. A key the store cannot hold+# (too long for the unique index, no valid UTF-8, a NUL) used to write and+# then fail; a key read differently on the two surfaces would be refused on+# one and kept on the other.+#+# Security spec: tagged :ci_guard and listed in .github/workflows/guards.yml.+RSpec.describe Mcp::IdempotencyStore, :ci_guard dolet(:organisation) { create(:organisation) }let(:user) { create(:user) }let(:token) { create(:personal_access_token, user: user, organisations: [organisation]) }@@ -53,5 +62,74 @@ RSpec.describe Mcp::IdempotencyStore doother = create(:personal_access_token, user: user, organisations: [organisation])expect(store(key: 'shared', args: { a: 1 }, the_token: other).replay).to be_nilend++ # What .storable_key? accepts the table takes: the bound sits far inside the index.+ it 'remembers and replays a key of the limit, umlauts included' do+ key = "#{'ä' * 127}k"+ store(key: key, args: { a: 1 }).remember('{"id":"123"}')++ expect(store(key: key, args: { a: 1 }).replay.content).to eq('{"id":"123"}')+ end+ end++ describe '.client_key' do+ it 'drops surrounding whitespace' do+ expect(described_class.client_key(" k-1\t\n")).to eq('k-1')+ end++ it 'reads a blank key, or none, as no key' do+ expect(['', ' ', nil].map { |raw| described_class.client_key(raw) }).to all(be_nil)+ end++ # String#strip treats a NUL at either end like whitespace; only one inside+ # the key reaches .storable_key?.+ it 'drops a NUL at either end, as String#strip does' do+ expect(described_class.client_key("\0k\0")).to eq('k')+ end++ # String#strip raises on such bytes. They come back as sent, for+ # .storable_key? to refuse.+ it 'returns bytes that are no valid UTF-8 as sent, without raising' do+ raw = " k\xFF ".dup.force_encoding(Encoding::UTF_8)++ expect(described_class.client_key(raw)).to eq(raw)+ end++ # A REST header arrives as binary, a valid encoding: stripped as before.+ it 'strips a binary header like any other key' do+ expect(described_class.client_key(' k-1 '.b)).to eq('k-1'.b)+ end+ end++ describe '.storable_key?' do+ let(:limit) { described_class::MAX_KEY_LENGTH }++ it 'holds a key of exactly the limit in bytes, umlauts included' do+ expect(described_class.storable_key?('k' * limit)).to be(true)+ expect(described_class.storable_key?("#{'ä' * 127}k")).to be(true)+ end++ it 'refuses one byte more, counting bytes and not characters' do+ expect(described_class.storable_key?('k' * (limit + 1))).to be(false)+ expect(described_class.storable_key?('ä' * 128)).to be(false)+ end++ it 'refuses a NUL inside the key' do+ expect(described_class.storable_key?("k\0x")).to be(false)+ end++ it 'refuses bytes that are no valid UTF-8, sent as binary or as UTF-8' do+ expect(described_class.storable_key?("k\xFFx".b)).to be(false)+ expect(described_class.storable_key?("k\xFFx".dup.force_encoding(Encoding::UTF_8))).to be(false)+ end++ it 'holds a binary key whose bytes are valid UTF-8' do+ expect(described_class.storable_key?('schlüssel'.b)).to be(true)+ end+ end++ it 'names the field and the bound in its refusal' do+ expect(described_class.unstorable_key_message('idempotency_key'))+ .to eq('idempotency_key must be valid UTF-8 without NUL, at most 255 bytes')endend