How to authenticate with jmap websocket?

[tttp]

Hi,

I'm writing a cli that talks jmap directly, I can list messages, send an email and everything seems to be working fine...

but I can't get it to listen to the websocket. Any idea why?

stalwart is behind an nginx that I think is properly configured for websockets:

location /jmap/ws {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

But I can't get it to upgrade the connection. I'm trying directly from the server to remove nginx potentially messing up:

`curl -i -N -H "Connection: Upgrade"              -H "Upgrade: websocket"              -H "Authorization: Basic $(echo -n 'user:password}' | base64)"              http://127.0.0.1:8080/jmap/ws
HTTP/1.1 400 Bad Request
content-type: application/problem+json
content-length: 100
access-control-allow-origin: *
access-control-allow-headers: Authorization, Content-Type, Accept, X-Requested-With
access-control-allow-methods: POST, GET, PATCH, PUT, DELETE, HEAD, OPTIONS
strict-transport-security: max-age=31536000; includeSubDomains; preload
date: Thu, 31 Jul 2025 12:16:13 GMT

{"type":"about:blank","status":400,"title":"Invalid parameters","detail":"WebSocket upgrade failed"}``

Am i doing something wrong? what parameters are invalid?

If I put an invalid login:password, I have an authentication error as expected
"type":"about:blank","status":401,"title":"Unauthorized","detail":"You have to authenticate first."}

stalwart logs contains:

2025-07-31T10:09:43Z ERROR Bad resource parameters (resource.bad-parameters) listenerId = "http", localPort = 8080, remoteIp = 127.0.0.1, remotePort = 54234, details = "WebSocket upgrade failed", reason = "Missing or Invalid Connection or Upgrade headers."

Any idea?

[mdecimus]

Never tried Web sockets with curl but apparently they support it using the wss: scheme:

https://curl.se/docs/websocket.html

[tttp]

Hi,

Sorry, I realised that I nudged you in the wrong direction: the problem isn't to use curl with websocket, the problem is that is seems that jmap hasn't standardised how to authenticate with websocket.

I'm trying to access it from a dump jmap cli in node, meaning my authentication (for the "normal" rest API isn't using oauth but the Basic authentication base64 (login:password)

this.authHeader = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;

it works fine to send an email or read a mailbox, but can't make it work the same with websockets (to listen to new messages)

https://github.com/fixthestatusquo/jmap-cli/blob/main/lib/jmap.js#L457

So my question: is this authentication supposed to work? the "normal" websocket from a browser doesn't seem to allow authHeaders, so may be it's not implemented in Stalwart? or is this my nginx messing things up?

If a basic authentication on websocket doesn't work how to authenticate?

[mdecimus]

You can use both Basic and Bearer authentication methods to start a JMAP WebSockets connection.
First try authenticating using a regular endpoint and once you get that to work try with WebSockets.
Also note that you need to send valid JMAP requests over the WebSockets connection.

[tttp]

the issue seems to be that (at least by default) websocket as used in the browsers don't allow to set custom headers, eg no authentication possible but jmap doesn't offer an alternative.

see the discussion on tmail and how their workaround
linagora/tmail-flutter#3860 (comment)

I tried using the native websocket on node and indeed, it doesn't seem to allow to add the required Authentication header

however, when using the same basic authentication that works fine on the regular jmap rest but trying to use it with websocket, but when trying wss://mail.example.org/jmap/ws' (as taken from .well-known)

  _header: 'GET /jmap/ws HTTP/1.1\r\n' +
    'Authorization: Basic <mybase64 encoded user password>\r\n' +
    'Sec-WebSocket-Protocol: jmap\r\n' +
    'Sec-WebSocket-Version: 13\r\n' +
    'Sec-WebSocket-Key: <autogenerated>\r\n' +
    'Connection: Upgrade\r\n' +
    'Upgrade: websocket\r\n' +
    'Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits\r\n' +
    'Host: mail.example.org\r\n' +
    '\r\n',

I still get an Unexpected server response: 400

is there something I'm missing? is there another way to authenticate on websocket (cookie being of the the suggestions)

[mdecimus]

Check the Stalwart WebSockets test suite to see how it can be done.