Skip to content

Add HTTP envelope wire codec boundary - #96

Merged
BenCodez merged 3 commits into
mainfrom
security/http-envelope-wire-codec-20260927
Sep 27, 2026
Merged

BenCodez merged 3 commits into
mainfrom
security/http-envelope-wire-codec-20260927

Conversation

@BenCodez

@BenCodez BenCodez commented Sep 27, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • add an optional HTTP envelope wire codec while preserving all existing identity-codec constructors
  • keep proxy durable queues in semantic/plain envelope form and apply encoding independently on every transmission attempt
  • decode authenticated wire envelopes before application callbacks and replay-state mutation
  • reject envelopes whose encoded form exceeds the transport bound before queue admission

Why

VotingPlugin's optional communication encryption must not persist key-specific ciphertext inside SimpleAPI's durable HTTP queue. A queued delivery must survive enabling encryption or rotating the shared key and be encoded with the current transport policy when it is retried.

Durability and compatibility

  • Existing callers use the identity codec and retain their current behavior.
  • Stable delivery IDs, acknowledgements, durable replay fences, ordering, and TLS enrollment remain unchanged.
  • Proxy queue files retain the semantic envelope.
  • A replacement codec is checked against recovered queue entries before the listener starts, so an undeliverable retained entry fails explicitly without being lost or blocking later traffic silently.
  • Codec work runs on the existing HTTP transport workers and is bounded to one protocol batch.

Validation

  • Focused HTTP tests: 71 passed before the review fix; final codec regression suite: 3 passed
  • mvn -B -f SimpleAPI/pom.xml clean package: 419 tests passed, 0 failed, 0 skipped
  • Full artifact checks: 2 passed
  • Shared artifact checks: 1 passed
  • Full JAR: 3,664,927 bytes
  • git diff --check: clean
  • Fresh isolated read-only Codex review: no actionable findings

This is a prerequisite for the durable HTTP encryption fix in VotingPlugin PR #1638.

Summary by CodeRabbit

  • New Features
    • HTTP transport now supports configurable encoding and decoding of messages, with existing configurations continuing to use the unchanged format.
  • Bug Fixes
    • Invalid or oversized messages are rejected instead of being delivered.
    • Pending deliveries remain queued when a response cannot be prepared, helping prevent messages from being lost.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 27, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-27T04:20:24.996829Z c22cca9 New commits
🔒 Security Review ✅ Completed 2026-09-27T03:08:58.737122Z f0d09b0 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Sep 27, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 6aa1410b-364d-42fa-bb07-2ba938685f5e

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: b7f5fac5-d076-4459-89d0-d82f87955766

📥 Commits

Reviewing files that changed from the base of the PR and between 675b800 and f0d09b0.

📒 Files selected for processing (4)
  • SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpBackendTransportConnector.java
  • SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpEnvelopeWireCodec.java
  • SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpProxyTransportServer.java
  • SimpleAPI/src/test/java/com/bencodez/simpleapi/servercomm/http/HttpEnvelopeWireCodecTest.java

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📜 Recent review details
⏰ Context from checks skipped due to timeout. (3)
  • GitHub Check: build
  • GitHub Check: Analyze (java-kotlin)
  • GitHub Check: Analyze (actions)
🔇 Additional comments (4)
SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpEnvelopeWireCodec.java (1)

1-32: LGTM!

SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpBackendTransportConnector.java (1)

110-125: LGTM!

Also applies to: 178-192, 280-286, 312-321, 333-333, 354-363

SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpProxyTransportServer.java (1)

87-96: LGTM!

Also applies to: 108-136, 161-161, 321-321, 335-339, 430-440, 461-470, 760-792

SimpleAPI/src/test/java/com/bencodez/simpleapi/servercomm/http/HttpEnvelopeWireCodecTest.java (1)

1-162: LGTM!


📝 Walkthrough

Walkthrough

The HTTP backend connector and proxy server now support a configurable envelope wire codec. They encode and validate outbound envelopes and decode and validate inbound envelopes. Existing constructor paths use the identity codec.

Changes

HTTP wire codec

Layer / File(s) Summary
Codec contract and transport configuration
SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpEnvelopeWireCodec.java, SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpBackendTransportConnector.java, SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpProxyTransportServer.java
Adds the HttpEnvelopeWireCodec interface and identity implementation. Both transports accept a codec, while existing constructor paths use the identity codec.
Backend connector HTTP boundary
SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpBackendTransportConnector.java, SimpleAPI/src/test/java/com/bencodez/simpleapi/servercomm/http/HttpEnvelopeWireCodecTest.java
The connector encodes and validates outbound envelopes before sending, then decodes and validates response envelopes. Tests cover authenticated envelope exchange through the codec.
Proxy server HTTP boundary and delivery handling
SimpleAPI/src/main/java/com/bencodez/simpleapi/servercomm/http/HttpProxyTransportServer.java, SimpleAPI/src/test/java/com/bencodez/simpleapi/servercomm/http/HttpEnvelopeWireCodecTest.java
The server validates encoded envelopes for enqueueing and restored deliveries, and decodes authenticated request envelopes. It removes acknowledgements only after response fitting succeeds. Tests cover codec replacement, oversized encoded envelopes, and pending deliveries.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant HttpBackendTransportConnector
  participant HttpEnvelopeWireCodec
  participant HttpProxyTransportServer
  HttpBackendTransportConnector->>HttpEnvelopeWireCodec: encode outbound envelopes
  HttpBackendTransportConnector->>HttpProxyTransportServer: send encoded poll request
  HttpProxyTransportServer->>HttpEnvelopeWireCodec: decode authenticated request envelopes
  HttpProxyTransportServer->>HttpEnvelopeWireCodec: encode response envelopes
  HttpProxyTransportServer->>HttpBackendTransportConnector: return encoded response
  HttpBackendTransportConnector->>HttpEnvelopeWireCodec: decode response envelopes
Loading

Merge Risk: ⚪ Minimal · up to f0d09

No concrete issue remains that calls for a fix before merge; the configured codec can be used after credential enrollment.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to f0d09

The new boundary preserves the existing identity-codec behavior and keeps queued deliveries independent of the active codec. A mixed-codec rollout remains a meaningful risk: a peer using the identity codec can accept a transformed envelope without knowing it needed decoding. No verified security finding was supplied, but that compatibility question warrants design review.

Retained concerns

  • Medium · security · inferred: Mixed-codec peers have no established wire-policy agreement. An identity-codec receiver can pass a structurally valid transformed envelope to its application callback and acknowledge it rather than reject an incompatible delivery.
Security review details

Security Blast Radius

  • inferred — A codec mismatch affects deliveries between an enrolled backend and its proxy. The inspected evidence does not establish exposure beyond that HTTP transport relationship.

Security Findings and Attack Paths

  • inferred — If a configured codec emits a structurally valid transformed envelope to an identity-codec peer, identity decode leaves it unchanged; successful application processing can then complete the delivery without applying the sender’s intended decoding policy. This is a conditional rollout path, not a verified exploit or a claim about a shipped encryption codec.

Trust Boundaries and Controls

  • observed — The proxy checks the peer certificate against the claimed server before decoding, validates each decoded envelope, and retains the authenticated server identity at callback dispatch. These controls limit identity substitution but do not establish codec-policy agreement.

Resilience and Maintainability Implications

  • observed — Both sides validate encoded envelopes against the envelope bound; the proxy checks retained deliveries on startup and fits encoded candidates into responses before advancing delivery timing.

Hardening Proposals

  • proposed — Define and test a fail-closed codec-policy or wire-version check before delivery acknowledgement, including identity-versus-configured and key-rotation rollout states.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 16.28% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 43 functions across 4 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely identifies the main change: adding an HTTP envelope wire codec boundary. It matches the pull request objectives and changed components.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f0d09b0c6a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8acffc3bf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@BenCodez
BenCodez merged commit 9072347 into main Sep 27, 2026
5 checks passed
@BenCodez
BenCodez deleted the security/http-envelope-wire-codec-20260927 branch September 27, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant