Bug: onAwarenessUpdate is returning the same context every call

[GuiLeme]

Description

First, I would like to congratulate you on such a great product—you’re building something fantastic.

Now, regarding the issue:

Context:
I want to validate whether the userName present in a document cursor coming from the front-end (we’re using BlockNote) matches the authenticated user in the Hocuspocus server context.

While working on this, I noticed that the onAwarenessUpdate hook (from Hocuspocus) always provides the same context in the data parameter—specifically, the context of the first user who joined the document. Even when a second user joins, the added list (containing the clientId of the recently added user) still appears to be associated with the context of the first user.

To make things even stranger, the awareness state map (retrieved via awareness.getStates()) only contains the clientId (which, as far as I understand, is created whenever a user creates a cursor to join the document) and the user information defined by the client (Therefore we cannot fully trust the second portion of the information).

If that’s the case, the first time I see a clientId is inside the onAwarenessUpdate hook. Because of this, I have no way to associate that clientId with any other server-side information (such as the WebSocket connection, socketId, so on). This becomes a problem if I need to disconnect a newly added clientId due to a userName mismatch (client tells a diffetent name from that of the server - completely feasable).

---

Steps to reproduce the bug

1. Create a basic client that connects to the server and allows choosing a userName
   (in my case, I used BlockNote, which allows setting the user name).
2. Create a Hocuspocus server with at least the onAwarenessUpdate hook, and log the socketId from the connection data.
3. Open the first client connection.
4. Observe the logs showing the socketId and the corresponding clientId.
5. Open a second client connection.
6. Observe that the context received in the hook’s data parameter is still the same as before (compare the socketIds), even though there is a new clientId added to the awareness state.

---

Expected behavior

I would expect at least one of the following scenarios to be possible to validate the userName from the cursor (ideally all of them):

• Expose clientId earlier or elsewhere
  For example, passing the clientId to the onAuthenticate hook, so we can associate a clientId with a socketId (and, by extension, the WebSocket connection).
  This might already exist, but I couldn’t find it.

• Include server-side identifiers in awareness states
  For example, storing the socketId (or another server-defined identifier) alongside the client data in awareness.getStates().
  I understand this might be a bit more difficult than the first.

• Bind awareness changes to the originating client context
  Meaning that awareness updates (e.g., cursor changes) would be handled using the context of the client that triggered that change.
  That way, every clientId observed in onAwarenessUpdate would be directly associated with the correct user context, and therefore the websocket connection completely.
  This is probably the most complex option.

---

Environment

• Operating system: Ubuntu 22.04
• Browser: Chrome v140.0.7339.80
• Platform: Desktop
• Hocuspocus version: v3.4.4
• BlockNote version: v0.31.1

---

Additional context

It’s very likely that I’m missing something here—if so, please let me know. Thank you in advance for your help.

There is also an open PR in our repository for integrating BlockNote with BigBlueButton, which might help clarify the broader context of this issue:
bigbluebutton/bigbluebutton#24519

In there we use Hocuspocus in the server component named bbb-shared-notes-server;

I am open to discussion, let me know if you have any questions.

Thanks for your time, and keep up the great work!

[janthurau]

Hi Guileme,

thank you for your report! I understand that this is confusing. onAwarenessUpdate is triggered after an update of awareness, so it's a.) too late to validate the incoming state and b.) we don't know anymore where it came from. Actually I think there is a property transactionOrigin which is the websocket, so probably contains the socket id (https://docs.yjs.dev/api/about-awareness). However if you want to validate, you still need to do it like mentioned below.

If you want to validate awareness before applying them to the local awareness instance, I suggest you use the beforeHandleMessage hook. Unfortunately it comes with a slight performance hit, but that shouldnt really matter based on my experience.

It should work kinda like this:

Server.configure({
  beforeHandleMessage(data) {
    const parsedMessage = new IncomingMessage(data.update);

    let documentName = parsedMessage.readVarString();
    let messageType = -1;

    try {
      messageType = parsedMessage.readVarUint();
    } catch (e) {}

    if (MessageType.Awareness === messageType) {
      // we got awareness

      const awareness = new Awareness();

      applyAwarenessUpdate(awareness, message.readVarUint8Array());

      if (!validate(awareness)) {
        throw new Error("invalid update received, disconnecting client");
      }
    }
  },
});

Let me know if this helps, I'll update the docs if it does.

[GuiLeme]

@janthurau Thank you for the reply and the suggestion, I will try it, and return here with news!

[GuiLeme]

Hello @janthurau, thanks for the suggestion. Unfortunately, using beforeHandleMessage didn’t solve the problem either.

While this hook does provide access to the WebSocket context, awareness updates are still aggregated and rebroadcast by all clients, not only by their original sender. As a result, every connection ends up sending awareness updates for all users, including those it does not own.

To illustrate the issue more concretely:

• User A joins the session
• User A sends an awareness update for User A
• User B joins the session
• User B receives User A’s awareness state
• User B sends an awareness update containing User A’s state
• User B sends its own awareness update
• User A receives User B’s awareness update
  … and so on

Because of this behavior, even in beforeHandleMessage, it’s not possible to reliably determine whether a given clientID (or awareness state) originated from the WebSocket connection currently being handled, since all clients legitimately send awareness updates for all known users.

The core requirement on my side is to be able to guarantee server-side ownership of a clientID or awareness update, and at the moment I don’t see a way to do that with the current awareness flow.

Regarding the other suggestion: transactionOrigin appears to be available only in onChangePayload and onStoreDocumentPayload. I couldn’t find any equivalent or related information exposed in the Awareness APIs.