feat(grpc-events): v8 OpenConnection serializer + native error decode (Path A disproven)

Builds the native 2023 R2 version-8 OpenConnection format, which (unlike v6)
carries a ConnectionType byte (Event vs Process) — required because the 2023 R2
server returns event rows only on an Event connection.

- HistorianOpen2Protocol.SerializeNativeOpenConnectionVersion8: reproduces the
  302-byte v8 layout decoded from a live capture (version 8, markers, client-key
  GUID, username HString, length-prefixed credential token, ClientType /
  ConnectionType / flag / constant word / compact metadata / two empty strings;
  the tail reuses WriteClientCommonInfo). Golden-tested
  (Version8EventSerializerReproducesCapturedNativeStructure).
- HistorianNativeHandshake.BuildEventOpenConnectionVersion8Request: ConnectionType=
  Event, zeroed credential token (mirroring how v6 zeros its credential block and
  relies on the separate ValidateClientCredential handshake).
- HistorianGrpcHandshake.OpenSession: optional eventConnection switch; the
  OpenConnection failure path now decodes the native error (type/code/ASCII).

Path A (reuse ValidateClientCredential + zeroed token) was live-tested and
DISPROVEN: the server parses the v8 buffer but rejects it at the auth check with
native 132/34 "EstablishConnection Failed to get client key" — the v8 path looks
up the client key in the registry HistoryService.ExchangeKey (ECDH) populates,
not the one ValidateClientCredential does. The event orchestrator is therefore
reverted to the v6 session (gated test still pins the no-row throw). The v8
serializer/builder are retained for Path B (implement ExchangeKey). 323/323
offline tests pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B6mcaT2PjRFKcogzp9UkfC
This commit is contained in:
Joseph Doherty
2026-06-23 09:45:52 -04:00
parent ea85ea248d
commit 0b1e9d0a7f
5 changed files with 149 additions and 4 deletions
@@ -50,6 +50,49 @@ internal static class HistorianOpen2Protocol
return stream.ToArray();
}
/// <summary>
/// Builds the native 2023 R2 <b>version-8</b> OpenConnection request — the format the stock client
/// uses, which (unlike v6) carries a <paramref name="connectionType"/> byte (Event vs Process). The
/// tail is the same <see cref="HistorianClientCommonInfo"/> v6 emits; the head is the v8 layout
/// decoded from a live capture (docs/reverse-engineering/grpc-event-query-capture.md): version 8,
/// two marker bytes, the client-key GUID, a username <c>HistorianString</c>, a length-prefixed
/// credential token, then ClientType / ConnectionType / flag / a constant word / compact metadata
/// namespace / two empty strings. The credential token is normally an ECDH-derived blob in the
/// native cert path; this serializer sends it as supplied (zeroed for the Negotiate-auth path,
/// mirroring how the v6 request already sends a zeroed credential block and relies on the separate
/// ValidateClientCredential handshake for authentication).
/// </summary>
public static byte[] SerializeNativeOpenConnectionVersion8(
HistorianClientCommonInfo commonInfo,
Guid clientKey,
byte connectionType,
byte connectionFlag,
string userName,
byte[] credentialToken)
{
using MemoryStream stream = new();
using BinaryWriter writer = new(stream, Encoding.Unicode, leaveOpen: true);
writer.Write((byte)8); // [0] format version 8
writer.Write((byte)0xF0); // [1] constant marker
writer.Write(new byte[19]); // [2..20] zero padding
writer.Write((byte)1); // [21] constant marker
writer.Write(clientKey.ToByteArray()); // [22..37] per-session client key
WriteHistorianString(writer, userName); // username (UTF-16 HistorianString)
writer.Write((ushort)credentialToken.Length); // credential-token length (u16)
writer.Write(credentialToken); // credential token (zeroed for the Negotiate path)
writer.Write((byte)4); // ClientType = 4
writer.Write(connectionType); // ConnectionType (Event = 1 / Process = 2)
writer.Write(connectionFlag); // type flag (Event = 1 / Process = 0)
writer.Write((ushort)3); // constant word observed at [97..98]
WriteCompactMetadataNamespace(writer, HistorianMetadataNamespace.Empty);
WriteHistorianString(writer, string.Empty);
WriteHistorianString(writer, string.Empty);
WriteClientCommonInfo(writer, commonInfo); // tail: FormatVersion 3 => no ClientDllVersion
writer.Write(0u); // trailing terminator
return stream.ToArray();
}
private static void WriteNativeOpenConnectionContent(
BinaryWriter writer,
HistorianOpen2Request request,