Clarify isTokenValid logic

lib/auth/server.coffee

@@ -77,9 +77,9 @@ exports.awaitForToken = (options) ->
 			Promise.try ->
 				if not token
 					throw new Error('No token')
-				return utils.isTokenValid(token)
-			.tap (isValid) ->
-				if not isValid
+				return utils.loginIfTokenValid(token)
+			.tap (loggedIn) ->
+				if not loggedIn
 					throw new Error('Invalid token')
 			.then ->
 				renderAndDone({ request, response, viewName: 'success', token })

lib/auth/utils.coffee

@@ -42,7 +42,7 @@ exports.getDashboardLoginURL = (callbackUrl) ->
 		return url.resolve(dashboardUrl, "/login/cli/#{callbackUrl}")
 
 ###*
-# @summary Check if a token is valid
+# @summary Log in using a token, but only if the token is valid
 # @function
 # @protected
 #
@@ -50,23 +50,26 @@ exports.getDashboardLoginURL = (callbackUrl) ->
 # This function checks that the token is not only well-structured
 # but that it also authenticates with the server successfully.
 #
-# @param {String} sessionToken - token
-# @fulfil {Boolean} - whether is valid or not
+# If authenticated, the token is persisted, if not then the previous
+# login state is restored.
+#
+# @param {String} token - session token or api key
+# @fulfil {Boolean} - whether the login was successful or not
 # @returns {Promise}
 #
-# utils.isTokenValid('...').then (isValid) ->
-#   if isValid
+# utils.loginIfTokenValid('...').then (loggedIn) ->
+#   if loggedIn
 #     console.log('Token is valid!')
 ###
-exports.isTokenValid = (sessionToken) ->
-	if not sessionToken? or _.isEmpty(sessionToken.trim())
+exports.loginIfTokenValid = (token) ->
+	if not token? or _.isEmpty(token.trim())
 		return Promise.resolve(false)
 
 	return resin.auth.getToken()
 	.catchReturn(undefined)
 	.then (currentToken) ->
-		resin.auth.loginWithToken(sessionToken)
-			.return(sessionToken)
+		resin.auth.loginWithToken(token)
+			.return(token)
 			.then(resin.auth.isLoggedIn)
 			.tap (isLoggedIn) ->
 				return if isLoggedIn

tests/auth/server.spec.coffee

@@ -51,11 +51,11 @@ describe 'Server:', ->
 	describe 'given the token authenticates with the server', ->
 
 		beforeEach ->
-			@utilsIsTokenValidStub = m.sinon.stub(utils, 'isTokenValid')
-			@utilsIsTokenValidStub.returns(Promise.resolve(true))
+			@loginIfTokenValidStub = m.sinon.stub(utils, 'loginIfTokenValid')
+			@loginIfTokenValidStub.returns(Promise.resolve(true))
 
 		afterEach ->
-			@utilsIsTokenValidStub.restore()
+			@loginIfTokenValidStub.restore()
 
 		it 'should eventually be the token', (done) ->
 			promise = server.awaitForToken(options)
@@ -74,11 +74,11 @@ describe 'Server:', ->
 	describe 'given the token does not authenticate with the server', ->
 
 		beforeEach ->
-			@utilsIsTokenValidStub = m.sinon.stub(utils, 'isTokenValid')
-			@utilsIsTokenValidStub.returns(Promise.resolve(false))
+			@loginIfTokenValidStub = m.sinon.stub(utils, 'loginIfTokenValid')
+			@loginIfTokenValidStub.returns(Promise.resolve(false))
 
 		afterEach ->
-			@utilsIsTokenValidStub.restore()
+			@loginIfTokenValidStub.restore()
 
 		it 'should be rejected', (done) ->
 			promise = server.awaitForToken(options)

tests/auth/utils.spec.coffee

@@ -43,22 +43,22 @@ describe 'Utils:', ->
 				expectedUrl = "#{dashboardUrl}/login/cli/http%253A%252F%252F127.0.0.1%253A3000%252Fcallback"
 				m.chai.expect(loginUrl).to.equal(expectedUrl)
 
-	describe '.isTokenValid()', ->
+	describe '.loginIfTokenValid()', ->
 
 		it 'should eventually be false if token is undefined', ->
-			promise = utils.isTokenValid(undefined)
+			promise = utils.loginIfTokenValid(undefined)
 			m.chai.expect(promise).to.eventually.be.false
 
 		it 'should eventually be false if token is null', ->
-			promise = utils.isTokenValid(null)
+			promise = utils.loginIfTokenValid(null)
 			m.chai.expect(promise).to.eventually.be.false
 
 		it 'should eventually be false if token is an empty string', ->
-			promise = utils.isTokenValid('')
+			promise = utils.loginIfTokenValid('')
 			m.chai.expect(promise).to.eventually.be.false
 
 		it 'should eventually be false if token is a string containing only spaces', ->
-			promise = utils.isTokenValid('     ')
+			promise = utils.loginIfTokenValid('     ')
 			m.chai.expect(promise).to.eventually.be.false
 
 		describe 'given the token does not authenticate with the server', ->
@@ -71,7 +71,7 @@ describe 'Utils:', ->
 				@resinAuthIsLoggedInStub.restore()
 
 			it 'should eventually be false', ->
-				promise = utils.isTokenValid(tokens.johndoe.token)
+				promise = utils.loginIfTokenValid(tokens.johndoe.token)
 				m.chai.expect(promise).to.eventually.be.false
 
 			describe 'given there was a token already', ->
@@ -82,7 +82,7 @@ describe 'Utils:', ->
 				it 'should preserve the old token', ->
 					resin.auth.getToken().then (originalToken) ->
 						m.chai.expect(originalToken).to.equal(tokens.janedoe.token)
-						return utils.isTokenValid(tokens.johndoe.token)
+						return utils.loginIfTokenValid(tokens.johndoe.token)
 					.then(resin.auth.getToken).then (currentToken) ->
 						m.chai.expect(currentToken).to.equal(tokens.janedoe.token)
 
@@ -92,7 +92,7 @@ describe 'Utils:', ->
 					resin.auth.logout()
 
 				it 'should stay without a token', ->
-					utils.isTokenValid(tokens.johndoe.token).then ->
+					utils.loginIfTokenValid(tokens.johndoe.token).then ->
 						resin.auth.isLoggedIn()
 					.then (isLoggedIn) ->
 						m.chai.expect(isLoggedIn).to.equal(false)
@@ -107,5 +107,5 @@ describe 'Utils:', ->
 				@resinAuthIsLoggedInStub.restore()
 
 			it 'should eventually be true', ->
-				promise = utils.isTokenValid(tokens.johndoe.token)
+				promise = utils.loginIfTokenValid(tokens.johndoe.token)
 				m.chai.expect(promise).to.eventually.be.true