diff --git a/README.md b/README.md index 6ec8a0b..a49adf9 100644 --- a/README.md +++ b/README.md @@ -241,7 +241,7 @@ pusher This library supports end-to-end encryption of your private channels. This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them. You can enable this feature by following these steps: -1. You should first set up Private channels. This involves [creating an authentication endpoint on your server](https://pusher.com/docs/authenticating_users). +1. You should first set up Private channels. This involves [creating an authorization endpoint on your server](https://pusher.com/docs/authenticating_users). 2. Next, generate your 32 byte master encryption key, encode it as base64 and pass it to the Pusher constructor. @@ -278,17 +278,44 @@ pusher.trigger(["channel-1", "private-encrypted-channel-2"], "test_event", { Rationale: the methods in this library map directly to individual Channels HTTP API requests. If we allowed triggering a single event on multiple channels (some encrypted, some unencrypted), then it would require two API requests: one where the event is encrypted to the encrypted channels, and one where the event is unencrypted for unencrypted channels. -### Authenticating private channels +### Authenticating users -To authorise your users to access private channels on Pusher Channels, you can use the `authenticate` function: +To authenticate users during sign in, you can use the `authenticateUser` function: ```javascript -const auth = pusher.authenticate(socketId, channel) +const userData = { + id: "unique_user_id", + name: "John Doe", + image: "https://...", +} +const auth = pusher.authenticateUser(socketId, userData) +``` + +The `userData` parameter must contain an `id` property with a non empty string. For more information see: + +### Terminating user connections + +In order to terminate a user's connections, the user must have been authenticated. Check the [Server user authentication docs](http://pusher.com/docs/authenticating_users) for the information on how to create a user authentication endpoint. + +To terminate all connections established by a given user, you can use the `terminateUserConnections` function: + +```javascript +pusher.terminateUserConnections(userId) +``` + +Please note, that it only terminates the user's active connections. This means, if nothing else is done, the user will be able to reconnect. For more information see: [Terminating user connections docs](https://pusher.com/docs/channels/server_api/terminating-user-connections/). + +### Private channel authorisation + +To authorise your users to access private channels on Pusher Channels, you can use the `authorizeChannel` function: + +```javascript +const auth = pusher.authorizeChannel(socketId, channel) ``` For more information see: -### Authenticating presence channels +### Presence channel authorisation Using presence channels is similar to private channels, but you can specify extra data to identify that particular user: @@ -300,7 +327,7 @@ const channelData = { twitter_id: '@leggetter' } }; -const auth = pusher.authenticate(socketId, channel, channelData); +const auth = pusher.authorizeChannel(socketId, channel, channelData); ``` The `auth` is then returned to the caller as JSON. diff --git a/lib/auth.js b/lib/auth.js index 7df3038..e3e5b79 100644 --- a/lib/auth.js +++ b/lib/auth.js @@ -1,5 +1,14 @@ const util = require("./util") +function getSocketSignatureForUser(token, socketId, userData) { + const serializedUserData = JSON.stringify(userData) + const signature = token.sign(`${socketId}::user::${serializedUserData}`) + return { + auth: `${token.key}:${signature}`, + user_data: serializedUserData, + } +} + function getSocketSignature(pusher, token, channel, socketID, data) { const result = {} @@ -26,4 +35,5 @@ function getSocketSignature(pusher, token, channel, socketID, data) { return result } +exports.getSocketSignatureForUser = getSocketSignatureForUser exports.getSocketSignature = getSocketSignature diff --git a/lib/pusher.js b/lib/pusher.js index 2e938a8..3b25cf9 100644 --- a/lib/pusher.js +++ b/lib/pusher.js @@ -34,6 +34,19 @@ const validateSocketId = function (socketId) { } } +const validateUserId = function (userId) { + if (typeof userId !== "string" || userId === "") { + throw new Error("Invalid user id: '" + userId + "'") + } +} + +const validateUserData = function (userData) { + if (userData == null || typeof userData !== "object") { + throw new Error("Invalid user data: '" + userData + "'") + } + validateUserId(userData.id) +} + /** Provides access to Pusher's REST API, WebHooks and authentication. * * @constructor @@ -103,9 +116,9 @@ Pusher.forCluster = function (cluster, options) { * @param {String} socketId socket id * @param {String} channel channel name * @param {Object} [data] additional socket data - * @returns {String} authentication signature + * @returns {String} authorization signature */ -Pusher.prototype.authenticate = function (socketId, channel, data) { +Pusher.prototype.authorizeChannel = function (socketId, channel, data) { validateSocketId(socketId) validateChannel(channel) @@ -118,6 +131,60 @@ Pusher.prototype.authenticate = function (socketId, channel, data) { ) } +/** Returns a signature for given socket id, channel and socket data. + * + * DEPRECATED. Use authorizeChannel. + * + * @param {String} socketId socket id + * @param {String} channel channel name + * @param {Object} [data] additional socket data + * @returns {String} authorization signature + */ +Pusher.prototype.authenticate = Pusher.prototype.authorizeChannel + +/** Returns a signature for given socket id and user data. + * + * @param {String} socketId socket id + * @param {Object} userData user data + * @returns {String} authentication signature + */ +Pusher.prototype.authenticateUser = function (socketId, userData) { + validateSocketId(socketId) + validateUserData(userData) + + return auth.getSocketSignatureForUser(this.config.token, socketId, userData) +} + +/** Sends an event to a user. + * + * Event name can be at most 200 characters long. + * + * @param {String} userId user id + * @param {String} event event name + * @param data event data, objects are JSON-encoded + * @returns {Promise} a promise resolving to a response, or rejecting to a RequestError. + * @see RequestError + */ +Pusher.prototype.sendToUser = function (userId, event, data) { + if (event.length > 200) { + throw new Error("Too long event name: '" + event + "'") + } + validateUserId(userId) + return events.trigger(this, [`#server-to-user-${userId}`], event, data) +} + +/** Terminate users's connections. + * + * + * @param {String} userId user id + * @returns {Promise} a promise resolving to a response, or rejecting to a RequestError. + * @see RequestError + */ +Pusher.prototype.terminateUserConnections = function (userId) { + validateUserId(userId) + return this.post({ path: `/users/${userId}/terminate_connections`, body: {} }) +} + /** Triggers an event. * * Channel names can contain only characters which are alphanumeric, '_' or '-' diff --git a/tests/integration/pusher/authenticate.js b/tests/integration/pusher/authenticate.js index a755b21..792db0d 100644 --- a/tests/integration/pusher/authenticate.js +++ b/tests/integration/pusher/authenticate.js @@ -9,38 +9,163 @@ describe("Pusher", function () { pusher = new Pusher({ appId: 10000, key: "aaaa", secret: "tofu" }) }) - describe("#auth", function () { + describe("#authenticateUser", function () { it("should prefix the signature with the app key", function () { let pusher = new Pusher({ appId: 10000, key: "1234", secret: "tofu" }) - expect(pusher.authenticate("123.456", "test")).to.eql({ + expect(pusher.authenticateUser("123.456", { id: "45678" })).to.eql({ + auth: + "1234:f4b1fdeea7c93e32648c7230e32b172057c5623cace6cfce791c6e7035e0babd", + user_data: '{"id":"45678"}', + }) + + pusher = new Pusher({ appId: 10000, key: "abcdef", secret: "tofu" }) + expect(pusher.authenticateUser("123.456", { id: "45678" })).to.eql({ + auth: + "abcdef:f4b1fdeea7c93e32648c7230e32b172057c5623cace6cfce791c6e7035e0babd", + user_data: '{"id":"45678"}', + }) + }) + + it("should return correct authentication signatures for different user data", function () { + expect(pusher.authenticateUser("123.456", { id: "45678" })).to.eql({ + auth: + "aaaa:f4b1fdeea7c93e32648c7230e32b172057c5623cace6cfce791c6e7035e0babd", + user_data: '{"id":"45678"}', + }) + expect( + pusher.authenticateUser("123.456", { id: "55555", user_name: "test" }) + ).to.eql({ + auth: + "aaaa:b8a9f173455903792ae2b788add0c4c78ad7372b3ae7fb5769479276a1993743", + user_data: JSON.stringify({ id: "55555", user_name: "test" }), + }) + }) + + it("should return correct authentication signatures for different secrets", function () { + let pusher = new Pusher({ appId: 10000, key: "11111", secret: "1" }) + expect(pusher.authenticateUser("123.456", { id: "45678" })).to.eql({ + auth: + "11111:79bddf29fe8e2153dd5d8d569b3f45e5aeb26ae2eb4758879d844791b466cfa2", + user_data: '{"id":"45678"}', + }) + pusher = new Pusher({ appId: 10000, key: "11111", secret: "2" }) + expect(pusher.authenticateUser("123.456", { id: "45678" })).to.eql({ + auth: + "11111:a542498ffa6faf6de7c17a8106b923c042319bd73acfd1d274df32e269b55d1f", + user_data: '{"id":"45678"}', + }) + }) + + it("should return correct authentication signature with utf-8 in user data", function () { + expect(pusher.authenticateUser("1.1", { id: "ą§¶™€łü€ß£" })).to.eql({ + auth: + "aaaa:620494cee53d6c568b49598313194088afda37218f0d059af03c0c898ed61ff4", + user_data: '{"id":"ą§¶™€łü€ß£"}', + }) + }) + + it("should raise an exception if socket id is not a string", function () { + expect(function () { + pusher.authenticateUser(undefined, { id: "123" }) + }).to.throwException(/^Invalid socket id: 'undefined'$/) + expect(function () { + pusher.authenticateUser(null, { id: "123" }) + }).to.throwException(/^Invalid socket id: 'null'$/) + expect(function () { + pusher.authenticateUser(111, { id: "123" }) + }).to.throwException(/^Invalid socket id: '111'$/) + }) + + it("should raise an exception if socket id is an empty string", function () { + expect(function () { + pusher.authenticateUser("", { id: "123" }) + }).to.throwException(/^Invalid socket id: ''$/) + }) + + it("should raise an exception if socket id is invalid", function () { + expect(function () { + pusher.authenticateUser("1.1:", { id: "123" }) + }).to.throwException(/^Invalid socket id/) + expect(function () { + pusher.authenticateUser(":1.1", { id: "123" }) + }).to.throwException(/^Invalid socket id/) + expect(function () { + pusher.authenticateUser(":\n1.1", { id: "123" }) + }).to.throwException(/^Invalid socket id/) + expect(function () { + pusher.authenticateUser("1.1\n:", { id: "123" }) + }).to.throwException(/^Invalid socket id/) + }) + + it("should raise an exception if user data is not a non-null object", function () { + expect(function () { + pusher.authenticateUser("111.222", undefined) + }).to.throwException(/^Invalid user data: 'undefined'$/) + expect(function () { + pusher.authenticateUser("111.222", null) + }).to.throwException(/^Invalid user data: 'null'$/) + expect(function () { + pusher.authenticateUser("111.222", 111) + }).to.throwException(/^Invalid user data: '111'$/) + expect(function () { + pusher.authenticateUser("111.222", "") + }).to.throwException(/^Invalid user data: ''$/) + expect(function () { + pusher.authenticateUser("111.222", "abc") + }).to.throwException(/^Invalid user data: 'abc'$/) + }) + + it("should raise an exception if user data doesn't have a valid id field", function () { + expect(function () { + pusher.authenticateUser("111.222", {}) + }).to.throwException(/^Invalid user id: 'undefined'$/) + expect(function () { + pusher.authenticateUser("111.222", { id: "" }) + }).to.throwException(/^Invalid user id: ''$/) + expect(function () { + pusher.authenticateUser("111.222", { id: 123 }) + }).to.throwException(/^Invalid user id: '123'$/) + }) + }) + + describe("#authenticate", function () { + it("should be the exactly the same as authorizeChannel", function () { + expect(pusher.authenticate).to.eql(pusher.authorizeChannel) + }) + }) + + describe("#authorizeChannel", function () { + it("should prefix the signature with the app key", function () { + let pusher = new Pusher({ appId: 10000, key: "1234", secret: "tofu" }) + expect(pusher.authorizeChannel("123.456", "test")).to.eql({ auth: "1234:efa6cf7644a0b35cba36aa0f776f3cbf7bb60e95ea2696bde1dbe8403b61bd7c", }) pusher = new Pusher({ appId: 10000, key: "abcdef", secret: "tofu" }) - expect(pusher.authenticate("123.456", "test")).to.eql({ + expect(pusher.authorizeChannel("123.456", "test")).to.eql({ auth: "abcdef:efa6cf7644a0b35cba36aa0f776f3cbf7bb60e95ea2696bde1dbe8403b61bd7c", }) }) it("should return correct authentication signatures for different socket ids", function () { - expect(pusher.authenticate("123.456", "test")).to.eql({ + expect(pusher.authorizeChannel("123.456", "test")).to.eql({ auth: "aaaa:efa6cf7644a0b35cba36aa0f776f3cbf7bb60e95ea2696bde1dbe8403b61bd7c", }) - expect(pusher.authenticate("321.654", "test")).to.eql({ + expect(pusher.authorizeChannel("321.654", "test")).to.eql({ auth: "aaaa:f6ecb0a17d3e4f68aca28f1673197a7608587c09deb0208faa4b5519aee0a777", }) }) it("should return correct authentication signatures for different channels", function () { - expect(pusher.authenticate("123.456", "test1")).to.eql({ + expect(pusher.authorizeChannel("123.456", "test1")).to.eql({ auth: "aaaa:d5ab857f805433cb50562da96afa41688d7742a3c3a021ed15a4d991a4d8cf94", }) - expect(pusher.authenticate("123.456", "test2")).to.eql({ + expect(pusher.authorizeChannel("123.456", "test2")).to.eql({ auth: "aaaa:43affa6a09af1fb9ce1cadf176171346beaf7366673ec1e5920f68b3e97a466d", }) @@ -48,12 +173,12 @@ describe("Pusher", function () { it("should return correct authentication signatures for different secrets", function () { let pusher = new Pusher({ appId: 10000, key: "11111", secret: "1" }) - expect(pusher.authenticate("123.456", "test")).to.eql({ + expect(pusher.authorizeChannel("123.456", "test")).to.eql({ auth: "11111:584828bd6e80b2d177d2b28fde07b8e170abf87ccb5a791a50c933711fb8eb28", }) pusher = new Pusher({ appId: 10000, key: "11111", secret: "2" }) - expect(pusher.authenticate("123.456", "test")).to.eql({ + expect(pusher.authorizeChannel("123.456", "test")).to.eql({ auth: "11111:269bbf3f7625db4e0d0525b617efa5915c3ae667fd222dc8e4cb94bc531f26f2", }) @@ -61,24 +186,26 @@ describe("Pusher", function () { it("should return the channel data", function () { expect( - pusher.authenticate("123.456", "test", { foo: "bar" }).channel_data + pusher.authorizeChannel("123.456", "test", { foo: "bar" }).channel_data ).to.eql('{"foo":"bar"}') }) it("should return correct authentication signatures with and without the channel data", function () { - expect(pusher.authenticate("123.456", "test")).to.eql({ + expect(pusher.authorizeChannel("123.456", "test")).to.eql({ auth: "aaaa:efa6cf7644a0b35cba36aa0f776f3cbf7bb60e95ea2696bde1dbe8403b61bd7c", }) - expect(pusher.authenticate("123.456", "test", { foo: "bar" })).to.eql({ - auth: - "aaaa:f41faf9ead2ea76772cc6b1168363057459f02499ae4d92e88229dc7f4efa2d4", - channel_data: '{"foo":"bar"}', - }) + expect(pusher.authorizeChannel("123.456", "test", { foo: "bar" })).to.eql( + { + auth: + "aaaa:f41faf9ead2ea76772cc6b1168363057459f02499ae4d92e88229dc7f4efa2d4", + channel_data: '{"foo":"bar"}', + } + ) }) it("should return correct authentication signature with utf-8 in channel data", function () { - expect(pusher.authenticate("1.1", "test", "ą§¶™€łü€ß£")).to.eql({ + expect(pusher.authorizeChannel("1.1", "test", "ą§¶™€łü€ß£")).to.eql({ auth: "aaaa:2a229263e89d9c50524fd80c2e88be2843379f6931e28995e2cc214282c9db0c", channel_data: '"ą§¶™€łü€ß£"', @@ -87,58 +214,58 @@ describe("Pusher", function () { it("should raise an exception if socket id is not a string", function () { expect(function () { - pusher.authenticate(undefined, "test") + pusher.authorizeChannel(undefined, "test") }).to.throwException(/^Invalid socket id: 'undefined'$/) expect(function () { - pusher.authenticate(null, "test") + pusher.authorizeChannel(null, "test") }).to.throwException(/^Invalid socket id: 'null'$/) expect(function () { - pusher.authenticate(111, "test") + pusher.authorizeChannel(111, "test") }).to.throwException(/^Invalid socket id: '111'$/) }) it("should raise an exception if socket id is an empty string", function () { expect(function () { - pusher.authenticate("", "test") + pusher.authorizeChannel("", "test") }).to.throwException(/^Invalid socket id: ''$/) }) it("should raise an exception if socket id is invalid", function () { expect(function () { - pusher.authenticate("1.1:", "test") + pusher.authorizeChannel("1.1:", "test") }).to.throwException(/^Invalid socket id/) expect(function () { - pusher.authenticate(":1.1", "test") + pusher.authorizeChannel(":1.1", "test") }).to.throwException(/^Invalid socket id/) expect(function () { - pusher.authenticate(":\n1.1", "test") + pusher.authorizeChannel(":\n1.1", "test") }).to.throwException(/^Invalid socket id/) expect(function () { - pusher.authenticate("1.1\n:", "test") + pusher.authorizeChannel("1.1\n:", "test") }).to.throwException(/^Invalid socket id/) }) it("should raise an exception if channel name is not a string", function () { expect(function () { - pusher.authenticate("111.222", undefined) + pusher.authorizeChannel("111.222", undefined) }).to.throwException(/^Invalid channel name: 'undefined'$/) expect(function () { - pusher.authenticate("111.222", null) + pusher.authorizeChannel("111.222", null) }).to.throwException(/^Invalid channel name: 'null'$/) expect(function () { - pusher.authenticate("111.222", 111) + pusher.authorizeChannel("111.222", 111) }).to.throwException(/^Invalid channel name: '111'$/) }) it("should raise an exception if channel name is an empty string", function () { expect(function () { - pusher.authenticate("111.222", "") + pusher.authorizeChannel("111.222", "") }).to.throwException(/^Invalid channel name: ''$/) }) it("should throw an error for private-encrypted- channels", function () { expect(function () { - pusher.authenticate("123.456", "private-encrypted-bla", "foo") + pusher.authorizeChannel("123.456", "private-encrypted-bla", "foo") }).to.throwException( "Cannot generate shared_secret because encryptionMasterKey is not set" ) @@ -160,10 +287,10 @@ describe("Pusher with encryptionMasterKey", function () { }) }) - describe("#auth", function () { + describe("#authorizeChannel", function () { it("should return a shared_secret for private-encrypted- channels", function () { expect( - pusher.authenticate("123.456", "private-encrypted-bla", "foo") + pusher.authorizeChannel("123.456", "private-encrypted-bla", "foo") ).to.eql({ auth: "f00d:962c48b78bf93d98ff4c92ee7dff04865821455b7b401e9d60a9e0a90af2c105", @@ -172,7 +299,7 @@ describe("Pusher with encryptionMasterKey", function () { }) }) it("should not return a shared_secret for non-encrypted channels", function () { - expect(pusher.authenticate("123.456", "bla", "foo")).to.eql({ + expect(pusher.authorizeChannel("123.456", "bla", "foo")).to.eql({ auth: "f00d:013ad3da0d88e0df6ae0a8184bef50b9c3933f2344499e6e3d1ad67fad799e20", channel_data: '"foo"', diff --git a/tests/integration/pusher/terminate.js b/tests/integration/pusher/terminate.js new file mode 100644 index 0000000..8749368 --- /dev/null +++ b/tests/integration/pusher/terminate.js @@ -0,0 +1,55 @@ +const expect = require("expect.js") +const nock = require("nock") + +const Pusher = require("../../../lib/pusher") +const sinon = require("sinon") + +describe("Pusher", function () { + let pusher + + beforeEach(function () { + pusher = new Pusher({ appId: 1234, key: "f00d", secret: "tofu" }) + nock.disableNetConnect() + }) + + afterEach(function () { + nock.cleanAll() + nock.enableNetConnect() + }) + + describe("#terminateUserConnections", function () { + it("should throw an error if user id is empty", function () { + expect(function () { + pusher.terminateUserConnections("") + }).to.throwError(function (e) { + expect(e).to.be.an(Error) + expect(e.message).to.equal("Invalid user id: ''") + }) + }) + + it("should throw an error if user id is not a string", function () { + expect(function () { + pusher.terminateUserConnections(123) + }).to.throwError(function (e) { + expect(e).to.be.an(Error) + expect(e.message).to.equal("Invalid user id: '123'") + }) + }) + }) + + it("should call /terminate_connections endpoint", function (done) { + sinon.stub(pusher, "post") + pusher.appId = 1234 + const userId = "testUserId" + + pusher.terminateUserConnections(userId) + + expect(pusher.post.called).to.be(true) + expect(pusher.post.getCall(0).args[0]).eql({ + path: `/users/${userId}/terminate_connections`, + body: {}, + }) + pusher.post.restore() + done() + }) +}) diff --git a/tests/integration/pusher/trigger.js b/tests/integration/pusher/trigger.js index 40a964b..3797733 100644 --- a/tests/integration/pusher/trigger.js +++ b/tests/integration/pusher/trigger.js @@ -2,8 +2,10 @@ const expect = require("expect.js") const nock = require("nock") const nacl = require("tweetnacl") const naclUtil = require("tweetnacl-util") +const sinon = require("sinon") const Pusher = require("../../../lib/pusher") +const events = require("../../../lib/events") describe("Pusher", function () { let pusher @@ -441,6 +443,46 @@ describe("Pusher", function () { .catch(done) }) }) + + describe("#sendToUser", function () { + it("should trigger an event on #server-to-user-{userId}", function () { + sinon.stub(events, "trigger") + pusher.sendToUser("abc123", "halo", { foo: "bar" }) + expect(events.trigger.called).to.be(true) + expect(events.trigger.getCall(0).args[1]).eql(["#server-to-user-abc123"]) + expect(events.trigger.getCall(0).args[2]).equal("halo") + expect(events.trigger.getCall(0).args[3]).eql({ foo: "bar" }) + events.trigger.restore() + }) + + it("should throw an error if user id is empty", function () { + expect(function () { + pusher.sendToUser("", "halo", { foo: "bar" }) + }).to.throwError(function (e) { + expect(e).to.be.an(Error) + expect(e.message).to.equal("Invalid user id: ''") + }) + }) + + it("should throw an error if user id is not a string", function () { + expect(function () { + pusher.sendToUser(123, "halo", { foo: "bar" }) + }).to.throwError(function (e) { + expect(e).to.be.an(Error) + expect(e.message).to.equal("Invalid user id: '123'") + }) + }) + + it("should throw an error if event name is longer than 200 characters", function () { + const event = new Array(202).join("x") // 201 characters + expect(function () { + pusher.sendToUser("abc123", event, { foo: "bar" }) + }).to.throwError(function (e) { + expect(e).to.be.an(Error) + expect(e.message).to.equal("Too long event name: '" + event + "'") + }) + }) + }) }) describe("Pusher with encryptionMasterKey", function () {