Skip to content

Make stream correlation a first-class seam (CorrelationID)#3

Draft
sigma wants to merge 1 commit into
mainfrom
grill/stream-correlation-seam
Draft

Make stream correlation a first-class seam (CorrelationID)#3
sigma wants to merge 1 commit into
mainfrom
grill/stream-correlation-seam

Conversation

@sigma

@sigma sigma commented Jul 18, 2026

Copy link
Copy Markdown
Member

Implements candidate #4 from the architecture review: name the stream-correlation requirement that auth.Wrap (and, it turns out, vterm) was smuggling through RemoteID.

Problem

auth.Wrap keyed its identity map on transport.Stream.RemoteID() — a field documented "used for log tagging; not for authentication." To satisfy this unnamed requirement, every backend overloaded RemoteID with a correlation value (websocket's per-process token, unix's SO_PEERCRED string). The interface contradicted its own contract, and each new backend had to reverse-engineer what auth needed.

Change

  • Add Stream.CorrelationID(): an unauthenticated, per-dialer-instance handle that links streams to an Identity the handshake already established — it never itself grants identity. RemoteID() reverts to a pure, possibly-empty log tag.
  • auth.Wrap keys on CorrelationID and fails closed on an empty handle (no aliasing under the "" key), both when storing post-handshake and when admitting app streams.
  • Backends: websocket splits the token (CorrelationID) from the remote address (RemoteID); unix/libp2p/http2 expose one honest value for both roles.
  • Backend correlation tests migrate from asserting RemoteID to CorrelationID; adds auth/wrap_test.go for the empty-handle guard.

Second consumer found during implementation

vterm correlated a peer's /mosey/control resize with its later /mosey/pty attach also via RemoteID. Demoting RemoteID to a per-connection tag would have silently broken that over websocket. vterm now reads CorrelationID too (internal remotecorrelation rename). The review only flagged auth.Wrap; this was under-scoped.

Safety

No wire/protocol change — the websocket mosey-peer-<token> subprotocol and unix peercreds derivation are byte-identical; only where the value surfaces in Go moves. Full go build/go test ./... green.

Design record

  • docs/adr/0004-stream-correlation-seam.md — granularity decision (per-dialer, not per-connection or per-identity), the link-not-grant contract, the fail-closed rule, per-backend unforgeability bar, and deferred known-limits (identity-map eviction, unix pid-reuse).
  • CONTEXT.md — new Transport glossary section (Stream, CorrelationID, RemoteID).

Produced via a /grill-with-docs session.

Notes for the reviewer

  • This branch is off origin/main (83876a5). CONTEXT.md and docs/adr/ do not yet exist upstream — they are being introduced by the parallel /grill-with-docs sessions. This PR's CONTEXT.md therefore also carries candidate refactor(walletsolana): keyless Source construction; export RPC caller seam #1's Capabilities/Auth sections (uncommitted elsewhere); only the Transport section and ADR 0004 are this PR's subject. ADR numbering was bumped 0002→0004 to avoid collision with the concurrent signing-session (0002) and moseynet (0003) sessions.

…seam

auth.Wrap keyed its identity map on transport.Stream.RemoteID() — a field
documented "not for authentication" — so every backend quietly overloaded
RemoteID with a correlation value (websocket's per-process token, unix's
SO_PEERCRED string). vterm did the same to tie a peer's /mosey/control resize
to its later /mosey/pty attach. The interface contradicted its use.

Add Stream.CorrelationID(): an unauthenticated, per-dialer-instance handle that
*links* streams to an Identity the handshake already established — it never
grants identity. RemoteID reverts to a pure log tag. auth.Wrap and vterm both
key on CorrelationID, and auth.Wrap fails closed on an empty handle. No wire
change: the websocket subprotocol token and unix peercreds derivation are
byte-identical; only where the value surfaces in Go moves.

See docs/adr/0004-stream-correlation-seam.md and the CONTEXT.md Transport
glossary. Backend correlation tests migrate from RemoteID to CorrelationID.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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