Handle early agent-info messages

[backkem]

Note: Marking this as a draft for now but with the purpose to solicit early feedback.

Summary

• Add NetworkStateMachine wrapper around Spake2StateMachine that peeks type keys and routes: auth (1001-1005) →
  SPAKE2, agent-info (10-13, 120) → skip, unknown → skip
• Prevents DecodeFailed crash when peer sends agent-info-request during authentication (spec-allowed per
  application.bs §4.1)

Agent-Info handling

I suggest to handle Agent-info messages at the network level because the spec
allows them before authentication completes. The network layer recognises
the type keys and stores raw metadata (display name, opaque capability
codes) as unverified PeerAgentInfo. Interpreting capabilities (mapping
u64 codes to AgentCapability variants like ReceiveVideo or
ControlPresentation) remains in the application crate, which is the
only layer that assigns semantic meaning to those values.

Application vs Network abstraction

I think there may also be room to make the split between both protocol layers more stricts. For reference, here's what i did on the Go side for the network protocol:

// PRE-AUTH (you have identity + can negotiate/authenticate, but no app streams yet)
type UnauthenticatedConnection struct {}

// PSK auth flow helpers (pre-auth only)
func (c *UnauthenticatedConnection) GetAuthenticationRole() AuthenticationRole
func (c *UnauthenticatedConnection) RequestAuthenticatePSK() error
func (c *UnauthenticatedConnection) GeneratePSK() ([]byte, error)
func (c *UnauthenticatedConnection) AcceptAuthenticate(ctx context.Context) (AuthenticationRole, error)

// Transitions to authenticated state (detaches UnauthenticatedConnection on success)
func (c *UnauthenticatedConnection) AuthenticatePSK(ctx context.Context, psk []byte) (*Connection, error)

func (c *UnauthenticatedConnection) LocalAgent() *Agent
func (c *UnauthenticatedConnection) RemoteAgent() *Agent
func (c *UnauthenticatedConnection) Close() error

// POST-AUTH (no auth negotiation APIs; you now have application streams)
type Connection struct {}

// Application data plane (QUIC bidirectional streams)
func (c *Connection) OpenStream(ctx context.Context) (ApplicationStream, error)
func (c *Connection) AcceptStream(ctx context.Context) (ApplicationStream, error)

func (c *Connection) LocalAgent() *Agent
func (c *Connection) RemoteAgent() *Agent
func (c *Connection) Close() error

// Minimal mental model:
//
//   u := <-listener.Accept(...)
//   role := u.GetAuthenticationRole()
//   ... u.RequestAuthenticatePSK() / u.AcceptAuthenticate(...)
//   psk := ... u.GeneratePSK() or obtain from user/peer ...
//   c, err := u.AuthenticatePSK(ctx, psk)   // => POST-AUTH Connection
//   s, _ := c.OpenStream(ctx)               // app streams only exist post-auth

[gemini-code-assist]

Summary of Changes

Hello @backkem, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the network communication layer by introducing a NetworkStateMachine to intelligently route messages based on their type keys. This crucial change enables the system to correctly process agent-info messages that may arrive before authentication is finalized, thereby preventing potential crashes and improving protocol compliance. Additionally, it standardizes message type key encoding using RFC 9000 variable-length integers and refines base64 encoding for serial numbers to ensure URL-safe compatibility.

Highlights

• Network State Machine Introduction: Introduced a new NetworkStateMachine that acts as a top-level wrapper around Spake2StateMachine, responsible for managing connection phases and routing incoming messages.
• Early Agent-Info Message Handling: Implemented logic within NetworkStateMachine to peek at message type keys and gracefully handle agent-info messages (type keys 10-13, 120) even before authentication is complete. This prevents DecodeFailed crashes, aligning with the OpenScreen Protocol specification.
• Standardized Message Encoding/Decoding: Refactored message encoding and decoding across application and network layers to use RFC 9000 variable-length integers for type keys, separating the type key from the CBOR body for improved protocol robustness and flexibility.
• URL-Safe Base64 for Serial Numbers: Updated the base64 encoding of serial numbers in openscreen-application/src/cert.rs to use a URL-safe, no-padding format (URL_SAFE_NO_PAD). This change addresses compatibility issues with DNS labels, as standard base64 characters like +, /, and = are invalid in DNS.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a NetworkStateMachine to wrap the existing Spake2StateMachine, enabling more flexible message routing during the authentication phase. This is a crucial change that allows the system to gracefully handle non-authentication messages, such as agent-info messages, which can arrive before authentication is complete, preventing DecodeFailed crashes. The message encoding and decoding logic has been refactored to use RFC 9000 variable-length integers for type keys, improving adherence to the OpenScreen Protocol specification. The introduction of decode_body methods for various message types also enhances modularity and clarity in the serialization logic. Overall, this is a well-structured change that improves robustness and protocol compliance.

[gemini-code-assist]

The handle_agent_info method contains a TODO to parse AgentInfoResponse and populate self.peer_agent_info. This indicates that the handling of agent-info responses is currently incomplete. While the PR prevents crashes, fully processing these messages is essential for the intended functionality.

[backkem]

Rebase and fixed the lint. Technically this is mergeable as-is, it does move things forward slightly.
But I wanted to be a bit careful with establishing new concepts. IDK if you prefer to do it a bit peace meal like this or first try to design a more evergreen abstraction.