Skip to content

feat(parity): BodyVerify Layer 1.5 — universal VerifyEchoMiddleware#87

Merged
mikemolinet merged 1 commit into
mainfrom
feat/bodyverify-universal-sweep
May 11, 2026
Merged

feat(parity): BodyVerify Layer 1.5 — universal VerifyEchoMiddleware#87
mikemolinet merged 1 commit into
mainfrom
feat/bodyverify-universal-sweep

Conversation

@mikemolinet
Copy link
Copy Markdown
Collaborator

@mikemolinet mikemolinet commented May 11, 2026

Summary

Parity port of cueapi/cueapi#797. Adds the universal middleware counterpart to Phase 1's per-handler echo-back (cueapi/cueapi#795 / cueapi-core#86). All POST/PATCH/PUT JSON endpoints (and all future endpoints) now carry the BodyVerify echo-back primitive automatically.

Design doc: https://trydock.ai/workspaces/cue-message-silent-corruption-substrate-design-2026-05-11

Direction of parity

Private-leads, OSS-lags. Private PR cueapi/cueapi#797 merges first; this port follows.

Implementation

  • `app/middleware/verify_echo.py` — verbatim port from private (raw ASGI middleware, idempotent with Phase 1 handler-supplied echo)
  • `app/main.py` — `VerifyEchoMiddleware` registered between `RequestId`/`BodySizeLimit` and `RateLimit` (preserves shared-middleware ordering; hosted's `SecurityHeaders` + `AccessAudit` are hosted-only)
  • `tests/test_verify_echo_middleware.py` — verbatim port; all 24 tests pass identically against OSS endpoints

Behavior

Identical to private:

  • No-op unless `X-CueAPI-Verify-Echo: true`
  • Captures request body + replays via `receive_replay` (no double-consumption)
  • Injects `body_received` + `body_received_sha256` on 2xx application/json dict responses
  • Idempotent: Phase 1 endpoints (messages + fire) preserve their handler-supplied echo view
  • Method-gated (POST/PATCH/PUT only)
  • Skips on 4xx/5xx, non-JSON content-type, non-dict JSON responses

Parity-manifest updates

  • New entry: `app/middleware/verify_echo.py`
  • Updated `app/main.py` with BodyVerify deviation note (middleware ordering preserved relative to shared middlewares; hosted's SecurityHeaders + AccessAudit are hosted-only)

Test plan

  • Local: 24/24 OSS tests pass
  • CI: green on cueapi-core
  • parity-check action: no warnings (manifest updated)

🤖 Generated with Claude Code

@mikemolinet @claude
feat(parity): BodyVerify Layer 1.5 — universal VerifyEchoMiddleware
2718c88 
Parity port of cueapi/cueapi#797. Adds the universal middleware
counterpart to Phase 1's per-handler echo-back. All POST/PATCH/PUT
JSON endpoints (and all future endpoints) now carry the BodyVerify
echo-back primitive automatically; Phase 1 idempotency preserved.

Design doc:
https://trydock.ai/workspaces/cue-message-silent-corruption-substrate-design-2026-05-11

Direction of parity: private-leads, OSS-lags. Private PR #797 merging
first; this port follows within ~30min.

Files added:
- app/middleware/verify_echo.py (verbatim port from private)
- tests/test_verify_echo_middleware.py (verbatim port; all 24 tests
  pass identically — OSS has the same agents+cues+messages+fire
  endpoint shapes used by the integration tests)

Files modified:
- app/main.py — VerifyEchoMiddleware registered between RequestId/
  BodySizeLimit and RateLimit (preserves shared-middleware ordering;
  hosted's SecurityHeaders + AccessAudit are hosted-only)

Parity-manifest updates:
- New entry: app/middleware/verify_echo.py
- Updated app/main.py with BodyVerify deviation note (middleware
  ordering identical to private modulo hosted-only middlewares)

24/24 OSS tests pass locally; middleware coverage 95% on private.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 11, 2026

Parity check

This PR modifies files tracked in parity-manifest.json:

  • app/main.py
  • app/middleware/verify_echo.py

Please confirm one of the following in a reply or PR description update:

  1. The equivalent change has been applied to the private cueapi monorepo. Link the PR.
  2. This change is OSS-only and does not need porting. Briefly explain why (e.g. "fixes a bug that only exists in the OSS build").
  3. A follow-up issue has been filed to port the reverse direction. Link the issue.

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.

@govindkavaturi-art govindkavaturi-art enabled auto-merge (squash) May 11, 2026 23:24
@mikemolinet mikemolinet merged commit 6a0dc60 into main May 11, 2026
6 checks passed
@mikemolinet mikemolinet deleted the feat/bodyverify-universal-sweep branch May 11, 2026 23:26
@mikemolinet mikemolinet mentioned this pull request May 12, 2026
Merged
mikemolinet added a commit that referenced this pull request May 12, 2026
@mikemolinet
docs: body-verify guide for self-hosters (cueapi/cueapi #801 parity)
607978b 
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
@mikemolinet
docs: body-verify guide for self-hosters (cueapi/cueapi #801 parity) (#…
85e7409 
…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.)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mikemolinet