Skip to content

Add origin.peek() so a listener can route a datagram to the right secret - #21

Merged
mullinmax merged 1 commit into
mainfrom
claude/vector-network-discovery-windows-2xeoja
Sep 2, 2026
Merged

mullinmax merged 1 commit into
mainfrom
claude/vector-network-discovery-windows-2xeoja

Conversation

@mullinmax

Copy link
Copy Markdown
Contributor

What

A listener following one board can verify every datagram with the one secret it holds. A listener following twenty cannot — it has to know which board is claiming to have sent a datagram before it can pick the secret to check it against.

origin.peek(packet) decodes the body without verifying it, for routing only:

claimed = origin.peek(datagram).get("machine_id")
event = origin.unpack(secrets[claimed], datagram)   # this is the trust step

Why not just use the source address

That's the obvious shortcut and it's the wrong one. NAT between a board and the listener rewrites the source address — which is exactly what Origin hits running Ray on the Docker bridge, and what any port-forwarding setup hits. More fundamentally, the signature is what establishes who sent a datagram; the address was never doing that job, it was just standing near it.

On handing out an unverified decode

peek() returns attacker-controlled data on an open network, so the docstring says so plainly and points at unpack() as the step that establishes trust. Parsing before verifying is safe as long as nothing is believed before verifying — the JSON decode itself is not a trust decision, and the alternative (duplicating the frame layout in every consumer) is worse for exactly the reason this module exists.

_split() and _decode() are factored out so peek() and unpack() cannot drift apart on framing or malformed-input handling.

Testing

  • python -m pytest — 299 passed
  • ruff check . — clean
  • New tests cover the round trip, that peek() explicitly does not authenticate (a forged datagram peeks fine and then fails unpack()), and malformed/non-object frames.

Notes

Version 0.3.1 → 0.4.0. Consumed by the Origin change that switches Ray from source-IP identification to machine_id from the signed body.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VmtVSp58rDkDBRPzL9hJkt


Generated by Claude Code

A listener that follows one board can verify every datagram with the one
secret it holds. A listener that follows twenty cannot: it has to know which
board is claiming to have sent a datagram before it can pick the secret to
check it against.

Identifying the sender by its source address is the obvious shortcut and the
wrong one -- NAT between a board and the listener rewrites it, and the
signature, not the address, is what establishes who sent the datagram.

peek() decodes the body without verifying it, for routing only. Its docstring
is blunt about what that means: nothing it returns is trustworthy until
unpack() has been called with the secret it led you to.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VmtVSp58rDkDBRPzL9hJkt
@github-actions

github-actions Bot commented Sep 2, 2026

Copy link
Copy Markdown

Coverage report

✅

Total coverage: 100.00% (0.00% vs base 100.00%)

@mullinmax
mullinmax marked this pull request as ready for review September 2, 2026 02:53
@mullinmax
mullinmax merged commit 273a13d into main Sep 2, 2026
12 checks passed
@mullinmax
mullinmax deleted the claude/vector-network-discovery-windows-2xeoja branch September 2, 2026 02:54
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.

2 participants