diff --git a/README.md b/README.md index 6166a8f..6ed5e25 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,8 @@ To use a proxy for local testing - * proxyPass: Password for USERNAME, will be ignored if USERNAME is empty or not specified * useCaCertificate: Path to ca cert file, if required +The same settings, including proxyUser/proxyPass and useCaCertificate, are used when the library downloads the BrowserStack Local binary. The download goes through the proxy only when both proxyHost and proxyPort are set. + ```js bs_local_args = { 'key': '', 'proxyHost': '127.0.0.1', 'proxyPort': '8000', 'proxyUser': 'user', 'proxyPass': 'password', 'useCaCertificate': '/Users/test/cert.pem' } ``` diff --git a/lib/Local.js b/lib/Local.js index ffd8af9..80a3784 100644 --- a/lib/Local.js +++ b/lib/Local.js @@ -320,6 +320,12 @@ function Local(){ if(this.proxyHost && this.proxyPort){ conf.proxyHost = this.proxyHost; conf.proxyPort = this.proxyPort; + /* The running binary already gets these as --proxy-user/--proxy-pass + (getBinaryArgs); the download goes through the same proxy and needs them too. */ + if(this.proxyUser) { + conf.proxyUser = this.proxyUser; + conf.proxyPass = this.proxyPass; + } } if (this.useCaCertificate) { conf.useCaCertificate = this.useCaCertificate; diff --git a/lib/LocalBinary.js b/lib/LocalBinary.js index eb94cfc..9a51c5d 100644 --- a/lib/LocalBinary.js +++ b/lib/LocalBinary.js @@ -8,7 +8,7 @@ var https = require('https'), util = require('util'), childProcess = require('child_process'), zlib = require('zlib'), - HttpsProxyAgent = require('https-proxy-agent'), + { buildProxyAgent } = require('./util'), version = require('../package.json').version, LocalError = require('./LocalError'), fetchDownloadSourceUrlAsync = require('./fetchDownloadSourceUrlAsync'); @@ -37,6 +37,21 @@ function LocalBinary(){ */ this.downloadState = { fallbackEnabled: false, errorMessage: null, sourceURL: null }; + /* Proxy credentials reach the spawned download scripts through their environment, + never argv — same reason as the auth token. A copy already sitting in process.env + is dropped first so only this instance's settings are used. */ + this.addProxyCredentialsToEnv = function(env, conf) { + delete env.BROWSERSTACK_LOCAL_PROXY_USER; + delete env.BROWSERSTACK_LOCAL_PROXY_PASS; + if(conf.proxyHost && conf.proxyPort && conf.proxyUser) { + env.BROWSERSTACK_LOCAL_PROXY_USER = String(conf.proxyUser); + if(conf.proxyPass !== undefined && conf.proxyPass !== null) { + env.BROWSERSTACK_LOCAL_PROXY_PASS = String(conf.proxyPass); + } + } + return env; + }; + this.getSourceUrlSync = function(conf, retries) { /* Request for an endpoint to download the local binary from Rails no more than twice with 5 retries each */ if (![4, 9].includes(retries) && this.sourceURL != null) { @@ -74,6 +89,7 @@ function LocalBinary(){ if (this.key) { env.BROWSERSTACK_LOCAL_AUTH_TOKEN = this.key; } + this.addProxyCredentialsToEnv(env, conf); const obj = childProcess.spawnSync(cmd, opts, { env: env }); /* stdout is null on a spawn failure; reading .length masked the real cause. */ if(obj.error) { @@ -108,7 +124,7 @@ function LocalBinary(){ downloadErrorMessage = this.downloadErrorMessage || this.downloadState.errorMessage; } - fetchDownloadSourceUrlAsync(this.key, this.bsHost, downloadFallback, downloadErrorMessage, conf.proxyHost, conf.proxyPort, conf.useCaCertificate, (err, sourceURL) => { + fetchDownloadSourceUrlAsync(this.key, this.bsHost, downloadFallback, downloadErrorMessage, conf.proxyHost, conf.proxyPort, conf.proxyUser, conf.proxyPass, conf.useCaCertificate, (err, sourceURL) => { if (err) return callback(err); this.sourceURL = sourceURL; this.downloadState.sourceURL = sourceURL; @@ -242,6 +258,7 @@ function LocalBinary(){ try{ const userAgent = [packageName, version].join('/'); const env = Object.assign({ 'USER_AGENT': userAgent }, process.env); + this.addProxyCredentialsToEnv(env, conf); const obj = childProcess.spawnSync(cmd, opts, { env: env }); if(obj.status !== 0) { that.binaryDownloadError('Download failed with status', String(obj.status)); @@ -304,11 +321,9 @@ function LocalBinary(){ }); var options = url.parse(this.httpPath); - if(conf.proxyHost && conf.proxyPort) { - options.agent = new HttpsProxyAgent({ - host: conf.proxyHost, - port: conf.proxyPort - }); + var agent = buildProxyAgent(conf.proxyHost, conf.proxyPort, conf.proxyUser, conf.proxyPass); + if(agent) { + options.agent = agent; } if (conf.useCaCertificate) { try { diff --git a/lib/download.js b/lib/download.js index 2d54cc4..aaa96fa 100644 --- a/lib/download.js +++ b/lib/download.js @@ -1,11 +1,12 @@ const https = require('https'), fs = require('fs'), - HttpsProxyAgent = require('https-proxy-agent'), url = require('url'), zlib = require('zlib'), - { isUndefined } = require('./util'); + { isUndefined, buildProxyAgent } = require('./util'); const binaryPath = process.argv[2], httpPath = process.argv[3], proxyHost = process.argv[4], proxyPort = process.argv[5], useCaCertificate = process.argv[6]; +/* Proxy credentials come through the environment, never argv (see fetchDownloadSourceUrl.js). */ +const proxyUser = process.env.BROWSERSTACK_LOCAL_PROXY_USER, proxyPass = process.env.BROWSERSTACK_LOCAL_PROXY_PASS; var fileStream = fs.createWriteStream(binaryPath); @@ -22,15 +23,13 @@ fileStream.on('error', function (err) { }); var options = url.parse(httpPath); -/* isUndefined, not plain truthiness: the parent passes literal `undefined` - placeholders for the proxy slots when only a CA is configured, and those - arrive here as the *string* "undefined" — which is truthy, and previously - built a proxy agent pointing at the host "undefined". */ -if(!isUndefined(proxyHost) && !isUndefined(proxyPort)) { - options.agent = new HttpsProxyAgent({ - host: proxyHost, - port: proxyPort - }); +/* buildProxyAgent treats the *string* "undefined" as absent: the parent passes + literal `undefined` placeholders for the proxy slots when only a CA is + configured, and plain truthiness previously built a proxy agent pointing at + the host "undefined". */ +const agent = buildProxyAgent(proxyHost, proxyPort, proxyUser, proxyPass); +if(agent) { + options.agent = agent; } /* Applied regardless of whether a proxy is configured: this is the caller's TLS diff --git a/lib/fetchDownloadSourceUrl.js b/lib/fetchDownloadSourceUrl.js index 6b5d37c..a0edb14 100644 --- a/lib/fetchDownloadSourceUrl.js +++ b/lib/fetchDownloadSourceUrl.js @@ -1,12 +1,12 @@ const https = require('https'), fs = require('fs'), - HttpsProxyAgent = require('https-proxy-agent'), - { isUndefined } = require('./util'); + { isUndefined, buildProxyAgent } = require('./util'); -/* The auth token is read from the environment, never from argv: argv is world-readable - via `ps` / /proc//cmdline, whereas /proc//environ is restricted to the - owning user. Keep it out of this argument list. */ +/* The auth token and proxy credentials are read from the environment, never from argv: + argv is world-readable via `ps` / /proc//cmdline, whereas /proc//environ is + restricted to the owning user. Keep them out of this argument list. */ const authToken = process.env.BROWSERSTACK_LOCAL_AUTH_TOKEN, bsHost = process.argv[2], proxyHost = process.argv[5], proxyPort = process.argv[6], useCaCertificate = process.argv[7], downloadFallback = process.argv[3], downloadErrorMessage = process.argv[4]; +const proxyUser = process.env.BROWSERSTACK_LOCAL_PROXY_USER, proxyPass = process.env.BROWSERSTACK_LOCAL_PROXY_PASS; let body = '', data = {'auth_token': authToken}; const options = { @@ -24,11 +24,9 @@ if (downloadFallback == 'true') { data['error_message'] = downloadErrorMessage; } -if(!isUndefined(proxyHost) && !isUndefined(proxyPort)) { - options.agent = new HttpsProxyAgent({ - host: proxyHost, - port: proxyPort - }); +const agent = buildProxyAgent(proxyHost, proxyPort, proxyUser, proxyPass); +if(agent) { + options.agent = agent; } if (!isUndefined(useCaCertificate)) { try { diff --git a/lib/fetchDownloadSourceUrlAsync.js b/lib/fetchDownloadSourceUrlAsync.js index ad6e97a..3d355af 100644 --- a/lib/fetchDownloadSourceUrlAsync.js +++ b/lib/fetchDownloadSourceUrlAsync.js @@ -1,12 +1,11 @@ const https = require('https'), fs = require('fs'), - HttpsProxyAgent = require('https-proxy-agent'), - { isUndefined } = require('./util'), + { isUndefined, buildProxyAgent } = require('./util'), version = require('../package.json').version; const packageName = 'browserstack-local-nodejs'; -function fetchDownloadSourceUrlAsync(authToken, bsHost, downloadFallback, downloadErrorMessage, proxyHost, proxyPort, useCaCertificate, callback) { +function fetchDownloadSourceUrlAsync(authToken, bsHost, downloadFallback, downloadErrorMessage, proxyHost, proxyPort, proxyUser, proxyPass, useCaCertificate, callback) { let body = '', data = {'auth_token': authToken}; const userAgent = [packageName, version].join('/'); const options = { @@ -24,11 +23,9 @@ function fetchDownloadSourceUrlAsync(authToken, bsHost, downloadFallback, downlo data['error_message'] = downloadErrorMessage; } - if(!isUndefined(proxyHost) && !isUndefined(proxyPort)) { - options.agent = new HttpsProxyAgent({ - host: proxyHost, - port: proxyPort - }); + const agent = buildProxyAgent(proxyHost, proxyPort, proxyUser, proxyPass); + if(agent) { + options.agent = agent; } if (!isUndefined(useCaCertificate)) { try { diff --git a/lib/util.js b/lib/util.js index b7de5b5..4b4fe33 100644 --- a/lib/util.js +++ b/lib/util.js @@ -1 +1,21 @@ -module.exports.isUndefined = value => (value === undefined || value === null || value === 'undefined'); +const HttpsProxyAgent = require('https-proxy-agent'); + +const isUndefined = value => (value === undefined || value === null || value === 'undefined'); +module.exports.isUndefined = isUndefined; + +const isBlank = value => (isUndefined(value) || value === ''); + +/* Builds the proxy agent for every binary-download request: the in-process async + download and the scripts the sync path spawns. Without proxyUser/proxyPass in it, + an authenticating proxy answers the CONNECT with 407 and the binary is never + downloaded, even though the running binary gets them as --proxy-user/--proxy-pass. + Same rule as the README: proxyPass is ignored unless proxyUser is set. */ +module.exports.buildProxyAgent = (proxyHost, proxyPort, proxyUser, proxyPass) => { + if(isBlank(proxyHost) || isBlank(proxyPort)) return undefined; + const agentOptions = { host: proxyHost, port: proxyPort }; + if(!isBlank(proxyUser)) { + /* https-proxy-agent sends this as `Proxy-Authorization: Basic base64(auth)`. */ + agentOptions.auth = proxyUser + ':' + (isUndefined(proxyPass) ? '' : proxyPass); + } + return new HttpsProxyAgent(agentOptions); +}; diff --git a/test/fixtures/recording_proxy.js b/test/fixtures/recording_proxy.js new file mode 100644 index 0000000..60ec5ea --- /dev/null +++ b/test/fixtures/recording_proxy.js @@ -0,0 +1,29 @@ +/* Test double for a corporate proxy that requires Basic auth. It runs in its own + process so the sync download path, which blocks the test process in spawnSync, + can still reach it. Every CONNECT is recorded and refused with 407, so nothing + leaves the machine. Talks to the parent over the fork IPC channel: + sends { port } once listening, answers 'dump' with { requests }, exits on 'stop'. */ +const http = require('http'); + +const requests = []; +const server = http.createServer(function (req, res) { + res.writeHead(405); + res.end(); +}); + +server.on('connect', function (req, socket) { + requests.push({ target: req.url, auth: req.headers['proxy-authorization'] || null }); + socket.end('HTTP/1.1 407 Proxy Authentication Required\r\n' + + 'Proxy-Authenticate: Basic realm="corp"\r\n' + + 'Content-Length: 0\r\n' + + 'Connection: close\r\n\r\n'); +}); + +process.on('message', function (msg) { + if (msg === 'dump') process.send({ requests: requests.splice(0) }); + if (msg === 'stop') server.close(function () { process.exit(0); }); +}); + +server.listen(0, '127.0.0.1', function () { + process.send({ port: server.address().port }); +}); diff --git a/test/proxy_auth_download.js b/test/proxy_auth_download.js new file mode 100644 index 0000000..bc5e549 --- /dev/null +++ b/test/proxy_auth_download.js @@ -0,0 +1,209 @@ +/* Regression tests for #164: proxyUser/proxyPass reached the running binary + (--proxy-user/--proxy-pass) but not the binary download, so a proxy that requires + Basic auth refused the download with 407 and Local never started. + + Everything here runs offline: the proxy is test/fixtures/recording_proxy.js, which + records each CONNECT's Proxy-Authorization header and refuses it with 407. It runs + in its own process because the sync path blocks this one in spawnSync. */ +var expect = require('expect.js'), + sinon = require('sinon'), + rimraf = require('rimraf'), + fs = require('fs'), + os = require('os'), + path = require('path'), + childProcess = require('child_process'), + browserstack = require('../index'), + LocalBinary = require('../lib/LocalBinary'), + buildProxyAgent = require('../lib/util').buildProxyAgent; + +var PROXY_USER = 'corpuser', + // ':' and '@' would be mangled if the credentials were ever treated as a URL. + PROXY_PASS = 'corp:pass@1', + EXPECTED_AUTH = 'Basic ' + Buffer.from(PROXY_USER + ':' + PROXY_PASS).toString('base64'), + BINARY_HOST = 'local-downloads.browserstack.com', + BINARY_BASE_URL = 'https://' + BINARY_HOST + '/binaries/release/latest_unzip', + TEST_TIMEOUT = 20000; + +function check(done, assertions) { + try { + assertions(); + done(); + } catch (err) { + done(err); + } +} + +/* Points every directory LocalBinary searches for an existing binary (home, cwd, + tmpdir) at a fresh empty dir, so start()/startSync() really download. */ +function isolateBinaryDirs() { + var saved = { HOME: process.env.HOME, TMPDIR: process.env.TMPDIR, cwd: process.cwd() }; + var dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bs-local-proxy-auth-')); + process.env.HOME = dir; + process.env.TMPDIR = dir; + process.chdir(dir); + return function restore() { + process.chdir(saved.cwd); + ['HOME', 'TMPDIR'].forEach(function (name) { + if (saved[name] === undefined) delete process.env[name]; + else process.env[name] = saved[name]; + }); + rimraf.sync(dir); + }; +} + +describe('Binary download through an authenticating proxy', function () { + var proxyProcess, proxyPort, sandBox, restoreDirs, tempDir; + + function proxyConf(extra) { + return Object.assign({ proxyHost: '127.0.0.1', proxyPort: proxyPort, + proxyUser: PROXY_USER, proxyPass: PROXY_PASS }, extra || {}); + } + + function recordedRequests(callback) { + proxyProcess.once('message', function (msg) { callback(msg.requests); }); + proxyProcess.send('dump'); + } + + function expectAuthenticated(requests, target) { + expect(requests.length).to.be.greaterThan(0); + requests.forEach(function (request) { + expect(request.auth).to.equal(EXPECTED_AUTH); + if (target) expect(request.target).to.equal(target); + }); + } + + before(function (done) { + proxyProcess = childProcess.fork(path.join(__dirname, 'fixtures', 'recording_proxy.js')); + proxyProcess.once('message', function (msg) { + proxyPort = msg.port; + done(); + }); + }); + + after(function () { + proxyProcess.send('stop'); + }); + + beforeEach(function () { + sandBox = sinon.sandbox.create(); + tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bs-local-proxy-auth-dl-')); + }); + + afterEach(function () { + sandBox.restore(); + if (restoreDirs) restoreDirs(); + restoreDirs = null; + rimraf.sync(tempDir); + delete process.env.BROWSERSTACK_LOCAL_PROXY_USER; + delete process.env.BROWSERSTACK_LOCAL_PROXY_PASS; + }); + + it('Local.start sends the proxy credentials when it downloads the binary', function (done) { + this.timeout(TEST_TIMEOUT); + restoreDirs = isolateBinaryDirs(); + new browserstack.Local().start(proxyConf({ key: 'DUMMY' }), function () { + recordedRequests(function (requests) { + check(done, function () { expectAuthenticated(requests); }); + }); + }); + }); + + it('Local.startSync sends the proxy credentials, through the environment and not argv', function (done) { + this.timeout(TEST_TIMEOUT); + restoreDirs = isolateBinaryDirs(); + var spawnSpy = sandBox.spy(childProcess, 'spawnSync'); + + new browserstack.Local().startSync(proxyConf({ key: 'DUMMY' })); + + var downloadSpawns = spawnSpy.args.filter(function (args) { + return /(fetchDownloadSourceUrl|download)\.js$/.test(String(args[1] && args[1][0])); + }); + recordedRequests(function (requests) { + check(done, function () { + expect(downloadSpawns.length).to.be.greaterThan(0); + downloadSpawns.forEach(function (args) { + var argv = args[1].map(String).join(' '); + expect(argv).to.not.contain(PROXY_USER); + expect(argv).to.not.contain(PROXY_PASS); + expect(args[2].env.BROWSERSTACK_LOCAL_PROXY_USER).to.equal(PROXY_USER); + expect(args[2].env.BROWSERSTACK_LOCAL_PROXY_PASS).to.equal(PROXY_PASS); + }); + expectAuthenticated(requests); + }); + }); + }); + + it('sends the proxy credentials on the binary request itself (async)', function (done) { + this.timeout(TEST_TIMEOUT); + var binary = new LocalBinary(); + sandBox.stub(binary, 'getDownloadPath', function (conf, retries, callback) { + callback(null, BINARY_BASE_URL + '/' + binary.getBinaryFilename()); + }); + binary.download(proxyConf(), tempDir, function () { + recordedRequests(function (requests) { + check(done, function () { expectAuthenticated(requests, BINARY_HOST + ':443'); }); + }); + }, 0); + }); + + it('sends the proxy credentials on the binary request itself (sync)', function (done) { + this.timeout(TEST_TIMEOUT); + var binary = new LocalBinary(); + sandBox.stub(binary, 'getSourceUrlSync', function () { return BINARY_BASE_URL; }); + binary.downloadSync(proxyConf(), tempDir, 0); + recordedRequests(function (requests) { + check(done, function () { expectAuthenticated(requests, BINARY_HOST + ':443'); }); + }); + }); + + it('sends no Proxy-Authorization when no proxy user is configured', function (done) { + this.timeout(TEST_TIMEOUT); + restoreDirs = isolateBinaryDirs(); + // proxyPass alone is ignored, as the README documents. + new browserstack.Local().start(proxyConf({ key: 'DUMMY', proxyUser: undefined }), function () { + recordedRequests(function (requests) { + check(done, function () { + expect(requests.length).to.be.greaterThan(0); + requests.forEach(function (request) { expect(request.auth).to.equal(null); }); + }); + }); + }); + }); + + it('does not hand proxy credentials already in process.env to the download scripts', function () { + process.env.BROWSERSTACK_LOCAL_PROXY_USER = 'planted-user'; + process.env.BROWSERSTACK_LOCAL_PROXY_PASS = 'planted-pass'; + var spawnStub = sandBox.stub(childProcess, 'spawnSync', function () { + return { stdout: Buffer.from('https://legit.browserstack.com/bs\n'), stderr: Buffer.from('') }; + }); + var binary = new LocalBinary(); + binary.parentRetries = 9; + + binary.getSourceUrlSync(proxyConf({ proxyUser: undefined, proxyPass: undefined }), 9); + + var childEnv = spawnStub.args[0][2].env; + expect(childEnv).to.not.have.property('BROWSERSTACK_LOCAL_PROXY_USER'); + expect(childEnv).to.not.have.property('BROWSERSTACK_LOCAL_PROXY_PASS'); + }); +}); + +describe('buildProxyAgent', function () { + it('adds Basic auth from proxyUser and proxyPass', function () { + expect(buildProxyAgent('127.0.0.1', 3128, PROXY_USER, PROXY_PASS).proxy.auth).to.equal(PROXY_USER + ':' + PROXY_PASS); + }); + + it('allows a proxy user with an empty password', function () { + expect(buildProxyAgent('127.0.0.1', 3128, PROXY_USER, undefined).proxy.auth).to.equal(PROXY_USER + ':'); + }); + + it('ignores proxyPass without proxyUser', function () { + expect(buildProxyAgent('127.0.0.1', 3128, undefined, PROXY_PASS).proxy.auth).to.equal(undefined); + }); + + it('returns no agent without both host and port, including the "undefined" argv placeholder', function () { + expect(buildProxyAgent(undefined, 3128)).to.equal(undefined); + expect(buildProxyAgent('127.0.0.1', undefined)).to.equal(undefined); + expect(buildProxyAgent('undefined', 'undefined', PROXY_USER, PROXY_PASS)).to.equal(undefined); + expect(buildProxyAgent('', '')).to.equal(undefined); + }); +});