Merge pull request #13 from silverbucket/sasl-oauthbearer

feat: add SASL OAUTHBEARER mechanism support (RFC 7628)

Author: silverbucket

README.md

@@ -102,9 +102,11 @@ The configuration options are as follows.
 
  - `password`: Password used to connect to the network. Most networks don't have one. 
 
- - `saslPassword`: Will be used for SASL authentication if the sasl property is also true.
+ - `saslMechanism`: SASL mechanism to use. Either `"PLAIN"` (default) or `"OAUTHBEARER"`.
 
- - `saslUsername`: Will be used for SASL authentication. (Defaults to username if not set).
+ - `saslPassword`: The credential sent during SASL. For `PLAIN`, this is the account password. For `OAUTHBEARER`, this is the OAuth 2.0 access token.
+
+ - `saslUsername`: Account name sent during SASL authentication. Defaults to `username` if not set. Required for `PLAIN`; sent but not used on the wire for `OAUTHBEARER`.
 
  - `proxy`: WEBIRC details if your connection is acting as a (probably web-based) proxy.
 
@@ -165,18 +167,57 @@ client.connect().then(function (res) {
 ```
 
 ## SASL ##
-Supporting SASL authentication.
+
+SASL authentication negotiates a `sasl` capability during the IRCv3 handshake, then runs one of two mechanisms:
+
+- **`PLAIN`** (default) — sends username + password, base64-encoded per [RFC 4616](https://datatracker.ietf.org/doc/html/rfc4616).
+- **`OAUTHBEARER`** — sends an OAuth 2.0 access token, base64-encoded per [RFC 7628](https://datatracker.ietf.org/doc/html/rfc7628).
+
+Providing `saslPassword` triggers SASL. Always request the `sasl` capability so the server negotiates it:
+
+```javascript
+capabilities: { requires: ["sasl"] }
+```
+
+### PLAIN
 
 ```javascript
 const client = IrcSocket({
-  capabilities: {
-    requires: ["sasl"]
-  },
-  saslUsername: 'exampleuser',  // will default to `username` if not specified
-  saslPassword: 'foo bar'
+  capabilities: { requires: ["sasl"] },
+  saslUsername: 'exampleuser',  // defaults to `username` if omitted
+  saslPassword: 'correct horse battery staple'
 });
 ```
 
+### OAUTHBEARER
+
+Supported by networks such as SourceHut's `chat.sr.ht`. Use this when you have an OAuth 2.0 access token rather than a password:
+
+```javascript
+const client = IrcSocket({
+  capabilities: { requires: ["sasl"] },
+  saslMechanism: 'OAUTHBEARER',
+  saslUsername: 'exampleuser',
+  saslPassword: ACCESS_TOKEN  // your OAuth 2.0 access token
+});
+```
+
+### Security
+
+The bearer token (or password) is sent over the wire. Connect over TLS — typically port `6697` with a `tls.Socket` as the underlying socket — so credentials are not exposed in transit.
+
+### Failure handling
+
+If the server rejects authentication (numerics `902`, `904`, `905`, `906`, or `907`), the connect promise resolves with `Fail(IrcSocket.connectFailures.saslAuthenticationFailed)` and the socket is closed with `QUIT`. The handshake finalizes on `903` (RPL_SASLSUCCESS); `900` (RPL_LOGGEDIN) is informational. For OAUTHBEARER, when the server responds with an RFC 7628 error challenge instead of the `+` prompt, the client acknowledges with `AUTHENTICATE AQ==` so the server can emit the failure numeric.
+
+### Large payloads
+
+`AUTHENTICATE` payloads are automatically split into 400-byte chunks per IRCv3 SASL 3.1. You don't need to size credentials manually — long OAuth access tokens are handled transparently.
+
+### Unsupported mechanism
+
+Passing any `saslMechanism` other than `"PLAIN"` or `"OAUTHBEARER"` throws synchronously at construction.
+
 ## Writing to the Server ##
 To send messages to the server, use socket.raw(). It accepts either a
 string or an array of Strings. The message '''must''' follow the

irc-socket.js

@@ -29,13 +29,23 @@ const endsWith = function (string, postfix) {
     return string.lastIndexOf(postfix) === string.length - postfix.length;
 };
 
+const encodeSaslCredential = function (mechanism, username, secret) {
+    if (mechanism === 'OAUTHBEARER') {
+        // RFC 7628: gs2-header "n,," then \x01 auth=Bearer <token> \x01 \x01
+        return Buffer.from('n,,\x01auth=Bearer ' + secret + '\x01\x01').toString('base64');
+    }
+    // PLAIN (RFC 4616): [authzid]\0[authcid]\0[passwd]
+    return Buffer.from(username + '\0' + username + '\0' + secret).toString('base64');
+};
+
 const failures = {
     killed: 'killed',
     nicknamesUnavailable: 'nicknames unavailable',
     badProxyConfiguration: 'bad proxy configuration',
     missingRequiredCapabilities: 'missing required capabilities',
     badPassword: 'bad password',
-    socketEnded: 'socket ended'
+    socketEnded: 'socket ended',
+    saslAuthenticationFailed: 'sasl authentication failed'
 };
 
 class IrcSocket extends EventEmitter {
@@ -64,6 +74,10 @@ class IrcSocket extends EventEmitter {
         if (config.saslPassword) {
             this.saslUsername = config.saslUsername || config.username;
             this.saslPassword = config.saslPassword;
+            this.saslMechanism = (config.saslMechanism || 'PLAIN').toUpperCase();
+            if (this.saslMechanism !== 'PLAIN' && this.saslMechanism !== 'OAUTHBEARER') {
+                throw new Error('Unsupported SASL mechanism: ' + config.saslMechanism);
+            }
         }
         this.username = config.username;
         this.realname = config.realname;
@@ -154,6 +168,12 @@ class IrcSocket extends EventEmitter {
             this.emit("connect");
             timeout = setTimeout(onSilence, timeoutPeriod);
             let serverCapabilities, acknowledgedCapabilities, sentRequests, respondedRequests, allRequestsSent, nickname;
+            // SASL challenge state: saslResponseSent flips once we've replied to
+            // the initial AUTHENTICATE + prompt; saslChallenge accumulates
+            // server-sent challenge chunks per IRCv3 SASL 3.1 (400-byte chunks,
+            // terminated by a short chunk or a trailing AUTHENTICATE +).
+            let saslResponseSent = false;
+            let saslChallenge = '';
 
             if (this.capabilities) {
                 this.capabilities.requires = this.capabilities.requires || [];
@@ -251,7 +271,7 @@ class IrcSocket extends EventEmitter {
                             acknowledgedCapabilities.push(capability);
                         }
                         if (acknowledgedCapabilities.includes('sasl')) {
-                            this.raw(['AUTHENTICATE', 'PLAIN']);
+                            this.raw(['AUTHENTICATE', this.saslMechanism || 'PLAIN']);
                         }
                     }
 
@@ -274,12 +294,58 @@ class IrcSocket extends EventEmitter {
                     }
 
                 } else if (parts[0] === "AUTHENTICATE") {
-                    if (parts[1] === '+') {
-                        const encPW = Buffer.from(this.saslUsername + '\0' + this.saslUsername + '\0' + this.saslPassword).toString('base64');
-                        this.raw(['AUTHENTICATE', encPW]);
+                    const chunkSize = 400;
+                    if (!saslResponseSent) {
+                        // Initial server prompt. Send our credential in 400-byte
+                        // AUTHENTICATE chunks; if the final chunk is exactly 400
+                        // bytes (or the payload is empty), append a trailing
+                        // AUTHENTICATE + per IRCv3 SASL 3.1.
+                        if (parts[1] !== '+') {
+                            return;
+                        }
+                        const payload = encodeSaslCredential(this.saslMechanism, this.saslUsername, this.saslPassword);
+                        if (payload.length === 0) {
+                            this.raw(['AUTHENTICATE', '+']);
+                        } else {
+                            for (let i = 0; i < payload.length; i += chunkSize) {
+                                this.raw(['AUTHENTICATE', payload.slice(i, i + chunkSize)]);
+                            }
+                            if (payload.length % chunkSize === 0) {
+                                this.raw(['AUTHENTICATE', '+']);
+                            }
+                        }
+                        saslResponseSent = true;
+                    } else {
+                        // Post-response server challenge. Accumulate chunks until
+                        // we see either a short chunk or a trailing "+" (after
+                        // 400-byte chunks). For OAUTHBEARER, RFC 7628 §3.2.3
+                        // requires AUTHENTICATE AQ== to ack the error challenge
+                        // before the server emits 904/905.
+                        let challengeComplete = false;
+                        if (parts[1] === '+') {
+                            challengeComplete = true;
+                        } else {
+                            saslChallenge += parts[1];
+                            if (parts[1].length < chunkSize) {
+                                challengeComplete = true;
+                            }
+                        }
+                        if (challengeComplete) {
+                            saslChallenge = '';
+                            if (this.saslMechanism === 'OAUTHBEARER') {
+                                this.raw(['AUTHENTICATE', 'AQ==']);
+                            }
+                        }
                     }
                 } else if (numeric === '903') {
+                    // RPL_SASLSUCCESS — advance past CAP. 900 RPL_LOGGEDIN is
+                    // informational and may arrive before 903; ignore it.
                     this.raw("CAP END");
+                } else if (numeric === '902' || numeric === '904' || numeric === '905' || numeric === '906' || numeric === '907') {
+                    // SASL aborted/failed/too-long/already/mech-unavailable
+                    this.raw("QUIT");
+                    this.resolvePromise(Fail(failures.saslAuthenticationFailed));
+                    return;
                 } else if (numeric === "001") {
                     this.status = "running";
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "irc-socket-sasl",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Simple IRC Socket with SSL and SASL support, for usage with IRC libraries. Forked from irc-socket.",
   "main": "irc-socket.js",
   "private": false,