Authentication

Ravex does not handle authentication.

The library only has one hard requirement:

Every connecting client must send an auth.user object containing at least an id.

If this requirement is not met, the connection is rejected with the error:

Authentication failed: Missing or invalid user in auth payload

Beyond this minimal shape check, Ravex performs no authentication or authorization. It blindly trusts whatever user object the client sends.

How to Authenticate Users

You are fully responsible for authenticating users. The recommended way is to use Socket.IO's native auth mechanism.

Client Side

Pass your authentication token (JWT, session token, API key, etc.) through the auth option:

const client = new ChatClient({
  url: "http://localhost:3000",
  auth: {
    token: "your-jwt-or-session-token-here",
    // You can still send a user object if you want
    user: {
      id: "user-123",
      username: "alice",
    },
  },
});

Server Side

You can add your own Socket.IO middleware to verify the token before or alongside Ravex.

Example of adding custom authentication:

const engine = new ChatEngine(httpServer);

// Access the underlying Socket.IO namespace
const ns = engine.io.of("/");

// Add your auth middleware (runs before Ravex's internal check)
ns.use((socket, next) => {
  const token = socket.handshake.auth.token;

  if (!token) {
    return next(new Error("No auth token provided"));
  }

  // Verify your token here (JWT, session, etc.)
  try {
    const decoded = verifyToken(token); // your verification logic
    // You can attach extra data to the socket if needed
    (socket as any).authData = decoded;
    next();
  } catch (err) {
    next(new Error("Invalid token"));
  }
});

Ravex's internal middleware will then run and only check for the presence of auth.user.

Important Notes

• Ravex does not validate tokens, sessions, or permissions.
• The user object sent by the client is not verified by Ravex.
• You can completely ignore the user object and implement authentication however you want using Socket.IO's auth field.
• If you need more control, you can add your own middlewares on the namespace.

Best Practices

• Always verify identity on the server using your own auth system (JWT, sessions, OAuth, etc.).
• Only put trusted data into auth.user after you've verified the client.
• Use the auth field to pass tokens rather than sending sensitive data in the user object.