feat(parity): BodyVerify Layer 1 — X-CueAPI-Verify-Echo echo-back substrate primitive#86
Merged
Merged
Conversation
Parity port of cueapi/cueapi PR #795. Adds the X-CueAPI-Verify-Echo
opt-in echo-back primitive on POST /v1/messages and
POST /v1/cues/{cue_id}/fire so callers can diff sent vs received body
bytes and catch caller-side shell expansion that silently mutates body
content at variable-assignment time.
Design doc:
https://trydock.ai/workspaces/cue-message-silent-corruption-substrate-design-2026-05-11
Files added:
- app/utils/verify_echo.py (verbatim port from private)
- tests/test_verify_echo.py (adapted: fire metachar parametrization is
private-only since OSS FireRequest carries only send_at; hosted's
payload_override is the corruption vector and lives in private)
Files modified:
- app/routers/messages.py — send_message integrates apply_verify_echo
- app/routers/cues.py — fire_cue takes Request param + integrates helper
Parity-manifest updates:
- New entry: app/utils/verify_echo.py
- Updated: app/routers/messages.py + app/routers/cues.py deviation notes
- Documents the OSS / private fire-test divergence in a single place
27/27 OSS tests pass locally (private had 33; 6 fire-metachar tests
deferred per FireRequest shape divergence).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Parity checkThis PR modifies files tracked in
Please confirm one of the following in a reply or PR description update:
This is a soft check — it does not block merge. The goal is visibility, not friction. See HOSTED_ONLY.md for the open-core policy. |
This was referenced May 11, 2026
Merged
mikemolinet
added a commit
that referenced
this pull request
May 12, 2026
Private cueapi #801 added docs/guides/body-verify.mdx (Mintlify, 247 lines) documenting the X-CueAPI-Verify-Echo primitive for hosted users. cueapi-core ships the SAME substrate (Layer 1 from #86 + Layer 1.5 universal middleware from #87 + STRING-shape spec-lock from #88) but had no user-facing guide. Self-hosters running cueapi-core need this. ## Scope cueapi-core-flavored adaptation — plain MD (not MDX), substrate-focused (narrower than the hosted MDX guide which covers SDK install + hosted- specific patterns). Sections: 1. The bug class — caller-side shell expansion ($(...), `...`, ${VAR}) 2. How it works — X-CueAPI-Verify-Echo header + response shape 3. Substrate architecture — Layer 1 (endpoint-specific STRING shape on /v1/messages + /v1/cues/{id}/fire) vs Layer 1.5 (universal middleware on all other POST/PATCH/PUT endpoints, OBJECT shape) 4. SDK auto-verify summary table (python / cli / mcp / action), with the messages-default-on vs fire-opt-in distinction explicit 5. Defense-in-depth layers — substrate + SDK + force-file + docs 6. When to disable + opt-out semantics 7. Implementation file references (app/utils/verify_echo.py, app/middleware/verify_echo.py, app/routers/{messages,cues}.py) 8. Background — Mike directive 2026-05-11; cross-stack ship history ## Out of scope - Per-language SDK install / API-key bootstrap content — already in each SDK's own README. This guide links rather than duplicates. - The hosted-specific Mintlify mint.json registration — cueapi-core uses plain MD; doc discovery via the docs/ dir, not Mintlify. ## Build / lint - Plain Markdown; no build step required. (Other docs in this dir follow the same convention — see quickstart.md, configuration.md.)
mikemolinet
added a commit
that referenced
this pull request
May 12, 2026
…90) Private cueapi #801 added docs/guides/body-verify.mdx (Mintlify, 247 lines) documenting the X-CueAPI-Verify-Echo primitive for hosted users. cueapi-core ships the SAME substrate (Layer 1 from #86 + Layer 1.5 universal middleware from #87 + STRING-shape spec-lock from #88) but had no user-facing guide. Self-hosters running cueapi-core need this. ## Scope cueapi-core-flavored adaptation — plain MD (not MDX), substrate-focused (narrower than the hosted MDX guide which covers SDK install + hosted- specific patterns). Sections: 1. The bug class — caller-side shell expansion ($(...), `...`, ${VAR}) 2. How it works — X-CueAPI-Verify-Echo header + response shape 3. Substrate architecture — Layer 1 (endpoint-specific STRING shape on /v1/messages + /v1/cues/{id}/fire) vs Layer 1.5 (universal middleware on all other POST/PATCH/PUT endpoints, OBJECT shape) 4. SDK auto-verify summary table (python / cli / mcp / action), with the messages-default-on vs fire-opt-in distinction explicit 5. Defense-in-depth layers — substrate + SDK + force-file + docs 6. When to disable + opt-out semantics 7. Implementation file references (app/utils/verify_echo.py, app/middleware/verify_echo.py, app/routers/{messages,cues}.py) 8. Background — Mike directive 2026-05-11; cross-stack ship history ## Out of scope - Per-language SDK install / API-key bootstrap content — already in each SDK's own README. This guide links rather than duplicates. - The hosted-specific Mintlify mint.json registration — cueapi-core uses plain MD; doc discovery via the docs/ dir, not Mintlify. ## Build / lint - Plain Markdown; no build step required. (Other docs in this dir follow the same convention — see quickstart.md, configuration.md.)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Parity port of cueapi/cueapi#795 — substrate echo-back primitive (BodyVerify Layer 1). Opt-in via$-paren, $ {VAR}) that silently mutates body content at variable-assignment time.
X-CueAPI-Verify-Echo: truerequest header onPOST /v1/messagesandPOST /v1/cues/{cue_id}/fire. Server returns `body_received` + `body_received_sha256` so callers can diff sent vs received bytes and detect caller-side shell expansion (backticks,Design doc: https://trydock.ai/workspaces/cue-message-silent-corruption-substrate-design-2026-05-11
Direction of parity
Private-leads → OSS-lags. cueapi/cueapi#795 merged first; this port follows within ~30min.
OSS-specific adaptations
Net test count: 27 in OSS (vs 33 in private).
Parity-manifest updates
Test plan
🤖 Generated with Claude Code