Secure WebSocket Implementation in Real-time JSON Editors

Why WSS?

wss:// encrypts the WebSocket connection using TLS/SSL, the same technology that secures HTTPS connections. This prevents eavesdropping and tampering with data in transit between the client and server. Without WSS, sensitive JSON data could be intercepted or modified over the network.

Ensure your server is configured to accept WSS connections, typically running on port 443 (the standard HTTPS port) and has a valid SSL certificate.

How to Authenticate the WS Connection?

• Query Parameters: Pass a token (e.g., a JWT) as a query parameter during the initial WebSocket handshake:

  ws://example.com/ws?token=<your_jwt_token>

  (Note: Use wss in production!)

• Custom Headers: Some WebSocket libraries allow sending custom headers during the handshake. This is often preferred over query parameters as tokens are less likely to be logged by intermediaries.
• Message-Based Authentication: Immediately after connecting, the client sends an authentication message containing the token. The server keeps the connection in an unauthenticated state until this message is received and validated.

The server must validate this token/session identifier for every new WebSocket connection and associate the connection with a specific user identity.

Example Authorization Checks:

• Can this user connect to the WebSocket channel for document ID doc-123?
• Can this user send an edit operation for document ID doc-123?
• Can this user modify the specific path /settings/admin within the JSON?

Every message received from a client should be processed within the context of their permissions.

// Server-side pseudo-code for handling an edit message
function handleEditMessage(userId, docId, editOperation) {
  // 1. Is userId authenticated? (Checked during connection setup)
  // 2. Is userId authorized to edit docId?
  if (!isUserAuthorized(userId, docId, 'write')) {
    // Send error back to client or close connection
    console.warn(`User ${userId} unauthorized to edit ${docId}`);
    return;
  }

  // 3. Is the edit operation valid for the current state of docId?
  if (!validateEditOperation(docId, editOperation)) {
     console.warn(`Invalid edit operation for ${docId}`);
     return;
  }

  // 4. Apply the edit operation and broadcast to other authorized users
  applyEditToDocument(docId, editOperation);
  broadcastToDocumentUsers(docId, editOperation, userId);
}

// Placeholder authorization check
function isUserAuthorized(userId, docId, permissionLevel) {
  // ... lookup user's roles/permissions for this document ...
  return true; // Placeholder: Assume authorized for example
}

Example: Sanitizing a string value

import escapeHTML from 'escape-html'; // Example sanitization library

function processIncomingString(inputString) {
  // Validate: Is it actually a string? Is it too long?
  if (typeof inputString !== 'string' || inputString.length > 1000) {
    throw new Error('Invalid string input');
  }
  // Sanitize: Escape HTML characters if the string will be rendered
  return escapeHTML(inputString);
}

Apply validation and sanitization not just to the entire JSON document, but also to individual fields and values being modified by operations.

Robust Message Handling:

• Wrap message parsing and handling logic in try...catch blocks.
• If a message is malformed or validation fails, log the event (including the user ID and potentially the message content for debugging, being mindful of sensitive data).
• Send a clear error message back to the client indicating the problem (e.g., "Invalid message format", "Validation failed").
• Consider disconnecting clients that repeatedly send malformed messages, as this could indicate malicious intent.

// Server-side pseudo-code for receiving messages
websocket.on('message', (messageString) => {
  try {
    // 1. Try to parse the message as JSON
    const message = JSON.parse(messageString);

    // 2. Validate the message structure and content
    if (!isValidMessage(message)) { // isValidMessage implements your checks
      console.warn('Received invalid message structure', { userId, messageString });
      // Send error response
      sendErrorMessage(websocket, 'Invalid message format or content.');
      return;
    }

    // 3. Process the valid message (requires authorization check inside)
    processMessage(userId, message); // Ensure processMessage checks authorization

  } catch (error) {
    // Handle JSON parsing errors or other unexpected errors
    console.error('Error processing message:', error, { userId, messageString });
    // Send a generic error response to avoid leaking internal details
    sendErrorMessage(websocket, 'An internal error occurred while processing your message.');
  }
});

Implementation Ideas:

• Track the number of messages received per user or per connection within a given time window (e.g., 100 messages per second).
• If a user exceeds the rate limit, temporarily reject their messages or disconnect their connection.
• Consider different rate limits for different types of messages (e.g., edit operations might have a lower rate limit than cursor position updates).

Server-Side Origin Check:

While the browser enforces some origin checks, a robust server should also validate the Origin header during the handshake to ensure the connection is coming from an expected domain. This helps prevent connections from malicious websites that might try to use your WebSocket endpoint.

// Server-side pseudo-code for WebSocket handshake
websocketServer.on('connection', (websocket, request) => {
  const origin = request.headers.origin;
  const allowedOrigins = ['https://your-editor.com', 'https://staging.your-editor.com'];

  if (origin && !allowedOrigins.includes(origin)) {
    console.warn(`Connection from disallowed origin: ${origin}`);
    websocket.close(1008, 'Origin not allowed'); // 1008 is Policy Violation status code
    return;
  }

  // Continue with authentication, authorization, etc.
  authenticateAndAuthorizeConnection(websocket, request)
    .then(userId => {
      websocket.userId = userId; // Attach user info to socket
      console.log(`User ${userId} connected`);
      // Setup message handlers...
    })
    .catch(error => {
      console.error('Authentication failed:', error);
      websocket.close(1008, 'Authentication failed');
    });
});