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.

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.yml
index 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.rb
spec/requests/api/mcp_time_report_spec.rb
spec/requests/api/mcp_people_spec.rb
+ spec/requests/api/mcp_idempotency_key_bound_spec.rb
+ spec/services/mcp/idempotency_store_spec.rb
spec/services/posts/plain_text_body_spec.rb
spec/services/lalabase/tools/post_comment_spec.rb
spec/services/lalabase/tools/post_comment_failure_spec.rb
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 never
crosses 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 send
the 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.rb
index 6accc2d..38dca16 100644
--- a/app/controllers/concerns/api/v1/idempotent.rb
+++ b/app/controllers/concerns/api/v1/idempotent.rb
@@ -33,10 +33,6 @@ module Api
HEADER = '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 = 255
included do
# The actions this controller declared, read by
@@ -54,10 +50,14 @@ module Api
private
+ # 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 Api
store.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 Api
def render_invalid_idempotency_key
skip_authorization
render_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)
end
diff --git a/app/services/lalabase/CLAUDE.md b/app/services/lalabase/CLAUDE.md
index 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) nur
Content-Schicht über `Fragment.for_context_map` (je Area verengte Projektmenge)
diff --git a/app/services/mcp/dispatcher.rb b/app/services/mcp/dispatcher.rb
index 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_dup
schema[:properties] ||= {}
@@ -136,7 +138,8 @@ module Mcp
schema[: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."
}
end
schema
diff --git a/app/services/mcp/idempotency_store.rb b/app/services/mcp/idempotency_store.rb
index 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 IdempotencyStore
MISMATCH_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.rb
index 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 Mcp
result
end
+ # 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 an
diff --git a/spec/contracts/mcp_contract_recorder.rb b/spec/contracts/mcp_contract_recorder.rb
index 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")
}
end
diff --git a/spec/fixtures/mcp_contract.json b/spec/fixtures/mcp_contract.json
index 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.rb
new file mode 100644
index 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
+end
diff --git a/spec/requests/api/v1/idempotency_spec.rb b/spec/requests/api/v1/idempotency_spec.rb
index 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 do
end
it 'accepts a key of exactly the limit' do
- key = 'k' * Api::V1::Idempotent::MAX_KEY_LENGTH
+ key = 'k' * Mcp::IdempotencyStore::MAX_KEY_LENGTH
expect { 2.times { comment('Hallo', key: key) } }.to change { posts_count }.by(1)
end
end
diff --git a/spec/services/mcp/idempotency_store_spec.rb b/spec/services/mcp/idempotency_store_spec.rb
index 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 do
let(: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 do
other = create(:personal_access_token, user: user, organisations: [organisation])
expect(store(key: 'shared', args: { a: 1 }, the_token: other).replay).to be_nil
end
+
+ # 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')
end
end