Add Message Type

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

export enum MessageType {
  // ... existing types
  PING = "PING",  // your new type
}

2. Define the message interface

file: core/src/protocol/types.ts

export interface PingMessage extends BaseMessage {
  type: MessageType.PING;
  timestamp: number;
}

3. Add to the union

file: core/src/protocol/types.ts

export type ProtocolMessage =
  | HelloMessage
  | ChallengeMessage
  // ... existing
  | 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:

case MessageType.PING:
  if (typeof parsed.timestamp !== "number") {
    throw new Error("PING: missing timestamp");
  }
  break;

5. Handle in session

file: core/src/session/session.ts

add a case in handleIncoming():

case MessageType.PING:
  this.handlePing(msg as PingMessage);
  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

it("should roundtrip PING message", () => {
  const msg: PingMessage = {
    ...createBaseFields(MessageType.PING, "ABC123", 1),
    timestamp: Date.now(),
  };
  const bytes = serializeMessage(msg);
  const parsed = deserializeMessage(bytes);
  expect(parsed.type).toBe(MessageType.PING);
});

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.