Adding a new message type

the ShareGo protocol uses typed JSON messages over WebSocket. adding a new message type requires changes in the core library and documentation.

Steps

1. Add the type to the enum

file: core/src/protocol/types.ts

typescript
1export enum MessageType {
2  // ... existing types
3  PING = "PING",  // your new type
4}

2. Define the message interface

file: core/src/protocol/types.ts

typescript
1export interface PingMessage extends BaseMessage {
2  type: MessageType.PING;
3  timestamp: number;
4}

3. Add to the union

file: core/src/protocol/types.ts

typescript
1export type ProtocolMessage =
2  | HelloMessage
3  | ChallengeMessage
4  // ... existing
5  | PingMessage;  // add here

4. Update serialization validation

file: core/src/protocol/serialization.ts

add a case for the new type in deserializeMessage() to validate required fields:

typescript
1case MessageType.PING:
2  if (typeof parsed.timestamp !== "number") {
3    throw new Error("PING: missing timestamp");
4  }
5  break;

5. Handle in session

file: core/src/session/session.ts

add a case in handleIncoming():

typescript
1case MessageType.PING:
2  this.handlePing(msg as PingMessage);
3  break;

6. Export if needed

if the new message type needs to be used by app shells, export it from:

• core/src/protocol/index.ts
• core/src/index.ts

7. Add tests

file: core/src/protocol/serialization.test.ts

typescript
1it("should roundtrip PING message", () => {
2  const msg: PingMessage = {
3    ...createBaseFields(MessageType.PING, "ABC123", 1),
4    timestamp: Date.now(),
5  };
6  const bytes = serializeMessage(msg);
7  const parsed = deserializeMessage(bytes);
8  expect(parsed.type).toBe(MessageType.PING);
9});

8. Update documentation

• docs/PROTOCOL.md — add the message spec, fields table, and example JSON
• docs/THREAT_MODEL.md — add security implications if the message carries sensitive data
• .cursor/rules/sharego-protocol.mdc — update if wire format changes

Security checklist

• new message does NOT carry plaintext sensitive data (passwords, OTPs)
• if it carries binary data, it uses AEAD encryption like DATA messages
• sequence number is required and validated
• protocol version is checked
• session ID is validated
• unknown/unexpected messages of this type are rejected, not ignored
• no new fields leak key material or internal state

Checklist

• enum value added to MessageType
• interface defined extending BaseMessage
• added to ProtocolMessage union
• serialization validation added in deserializeMessage()
• handler added in session.ts handleIncoming()
• exported from barrel files (if needed by app shells)
• roundtrip test added
• docs/PROTOCOL.md updated with spec
• docs/THREAT_MODEL.md updated if security-relevant