Skip to content
This repository was archived by the owner on Feb 16, 2022. It is now read-only.

Commit 3ef856b

Browse files
author
Sean Gates
committed
Initial commit
0 parents  commit 3ef856b

File tree

13 files changed

+1617
-0
lines changed

13 files changed

+1617
-0
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.DS_Store
2+
node_modules
3+
.http-mitm-proxy

‎LICENSE.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# The MIT License
2+
SPDX short identifier: MIT
3+
4+
Copyright 2018 eBay Inc.
5+
6+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
7+
8+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
9+
10+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Userscript Proxy
2+
3+
Ever tried to run userscripts on your iOS device or your Android phone? For iOS, it's not possible, and for Android it's an exercise in frustration.
4+
5+
Userscript Proxy allows you to run userscripts on mobile devices. Userscripts are snippets of JavaScript and CSS code that are added to a particular web page, to change the way it looks or the way it behaves. [Tampermonkey](https://tampermonkey.net) and [Greasemonkey](http://www.greasespot.net) are browser extensions that allow you to install userscripts into web pages, but they only work properly in desktop browsers – they don't support iOS at all, and the version for Android is tied to an old browser that doesn't work very well anymore.
6+
7+
Instead of running userscripts directly in the browser, Userscript Proxy is an HTTP proxy server that transparently injects scripts and stylesheets (userscripts) into existing sites. We use this tool to quickly generate research stimuli for user testing: we write JavaScript scripts and CSS stylesheets that alter our existing sites according to new designs. This makes it much easier for our developers when we want to test out a simple change: we can run our changes on top of the existing site.
8+
9+
With Userscript Proxy, you can set up a collection of scripts, run multiple scripts at once, and specify which hosts and URLs to inject each script into. You can think of it as Tampermonkey or Greasemonkey running inside of a proxy server.
10+
11+
## How it works
12+
13+
Userscript Proxy generates a proxy PAC file that specifies which web hosts have URLs that need to be altered, and directs all requests to those hosts to Userscript Proxy's proxy server. The proxy server then adds userscripts to the HTML file that is served from each URL that matches. Scripts and stylesheets are added inline to the proxied page, so they run with the same permissions as a script running directly on the website.
14+
15+
Userscript Proxy uses the [http-mitm-proxy](https://github.com/joeferner/node-http-mitm-proxy/) npm module for the core proxy functionality.
16+
17+
## Installing
18+
19+
Userscript Proxy is a [Node.js](https://nodejs.org) application. The proxy can be used as a command-line application or as a Node module. Install as a command-line application unless you want to include the proxy in software you're writing.
20+
21+
### Installing as stand-alone command-line application
22+
23+
* Download and install [Node.js](https://nodejs.org)
24+
* Open a Terminal window and install Userscript Proxy:
25+
26+
```sh
27+
npm install -g userscript-proxy
28+
```
29+
30+
#### Running with example files
31+
32+
To run Userscript Proxy, you need a configuration file (config.json) and userscripts, which are JavaScript and CSS files. You can get a feel for how it works with the example files on this page. Clone this repository to your computer or [download the ZIP file](https://github.corp.ebay.com/EPIC/userscript-proxy/archive/master.zip) from the GitHub page, open a Terminal window and navigate to the `examples` directory, then run:
33+
34+
```sh
35+
userscript-proxy config.json
36+
```
37+
38+
See "Using the proxy server" below to set it up on your devices.
39+
40+
#### Running on the command line
41+
42+
In general, run Userscript Proxy as follows:
43+
44+
```sh
45+
userscript-proxy <config_file> [options]
46+
```
47+
48+
* `<config_file>` is the path to a JSON file that specifies the configuration of the proxy (see below for config file format)
49+
* `[options]` include:
50+
51+
```sh
52+
--loadScript set Start the proxy with the given set of userscripts active (defined in the config file)
53+
--staticDir dir Path to directory of static files to serve at /static
54+
--proxyPort port Port for HTTP proxy server (default 8888)
55+
--pacPort port Port to serve PAC and other static files (default 8080)
56+
--limitHosts Only proxy hosts in the currently-selected userscript set
57+
(see "Notes" section for more details)
58+
--addPac file Path to existing PAC file to add proxy rules to
59+
(see "Notes" section for more details)
60+
--proxyIndex file Path to proxy index HTML file
61+
--auth Enable proxy authentication (experimental; see "Notes" section)
62+
```
63+
64+
### Installing as an npm module
65+
66+
```sh
67+
npm install --save userscript-proxy
68+
```
69+
70+
Add the following code to your script:
71+
72+
```javascript
73+
var proxy = require('userscript-proxy');
74+
proxy(config, id, options);
75+
```
76+
77+
* `config` is a JavaScript object that specifies the configuration of the proxy (see below for config format)
78+
* `id` is the id of the set of userscripts you want to enable
79+
* `options` is an optional parameter with proxy options:
80+
81+
```javascript
82+
{
83+
'loadScript': 'userscriptSetId', // Start the proxy with the given set of userscripts active (defined in config)
84+
'staticDir': './path/to/static', // Path to directory of static files to serve at /static
85+
'proxyPort': 8888, // Port for HTTP proxy server (default 8888)
86+
'pacPort': 8080, // Port to serve PAC and other static files (default 8080)
87+
'limitHosts': false, // Only proxy hosts in the currently-selected userscript set
88+
// (see "Notes" section for more details)
89+
'addPac': pacFileString, // Add proxy rules to the beginning of an existing PAC file (as string)
90+
// (see "Notes" section for more details)
91+
'proxyIndex': indexFileString, // Proxy index HTML file (as string)
92+
'auth': false // Enable proxy authentication (experimental; see "Notes" section)
93+
}
94+
```
95+
96+
### Using the proxy server
97+
98+
* Connect the device that you wish to run userscripts on to the same network as your server.
99+
* Load `http://<proxy-server>:8080/` in the browser of the device that will run the userscripts, where `<proxy-server>` is the hostname or IP of the proxy server.
100+
* Install the CA certificate on the device that will run the userscripts. Download the CA Certificate from the page you just loaded. There are detailed instructions on the proxy's web page for multiple platforms.
101+
* Set the Automatic HTTP Proxy URL on the device that will run the userscripts. Copy the link from the page you just loaded to your device's proxy settings. There are detailed instructions on the proxy's web page for multiple platforms.
102+
* If you select a different set of userscripts from `http://<proxy-server>:8080/`, the proxy will globally and immediately update which sites will have userscripts added to them.
103+
104+
## Creating userscripts
105+
106+
Userscript Proxy doesn't have a graphical interface like Tampermonkey to install scripts, but don't get scared off &ndash; you just need to add the scripts to an easy configuration file.
107+
108+
See the `examples` directory for a sample `config.json` file and sample scripts. You can run the samples directly by opening a Terminal window in the `examples` directory and running `userscript-proxy config.json`
109+
110+
Userscripts are defined in a JavaScript object, defined below.
111+
112+
```json
113+
{
114+
"userscripts": [
115+
{
116+
"title": "Title of userscript",
117+
"id": "userscriptId",
118+
"match": [
119+
{"host": "example.com", "url": "/"},
120+
{"host": "example.com", "url": "/index.html"}
121+
],
122+
"scripts": [
123+
"./scripts/userscript.js"
124+
],
125+
"styles": [
126+
"./styles/userscript.css"
127+
]
128+
},
129+
...
130+
],
131+
"userscriptSets": [
132+
{
133+
"title": "Title of userscript set",
134+
"id": "userscriptSetId",
135+
"password": "pass",
136+
"userscripts": ["userscriptId", ...]
137+
},
138+
...
139+
]
140+
}
141+
```
142+
143+
* `userscripts` inject JavaScript or CSS file(s) into specified URL(s).
144+
* `userscriptSets` are collections of individual userscripts that will be enabled at the same time. These sets are what are shown to the user on the proxy web page, and the user can switch between them.
145+
* Individual userscripts have a `title` and `id`, can `match` one or more URLs, can have one or more JavaScript files (`scripts`) injected into that URL, and can have one or more CSS files (`styles`) injected into that URL.
146+
* Sets of userscripts have a `title` and `id`, a `password` that is used when proxy authentication is enabled, and an array of `userscripts` IDs that will all be enabled when this set is selected.
147+
* Every time you add a new userscript to the `userscripts` array, an entry also needs to be added to the `userscriptSets` array to allow the user to enable a userscript or set of userscripts by ID.
148+
* The configuration object is passed directly to the proxy when using it a module, or as a JSON file if the proxy is invoked from the command line.
149+
150+
### Adding proxy information to your userscripts
151+
152+
All instances of the following static keys will be replaced with their corresponding dynamic values in userscripts.
153+
154+
* `@@USERSCRIPT-PROXY-HOSTNAME-FQDN@@` fully qualified domain name of the proxy server
155+
* `@@USERSCRIPT-PROXY-HOSTNAME@@` hostname of the proxy server
156+
* `@@USERSCRIPT-PROXY-PAC-PORT@@` port number that static files and the PAC are served from
157+
* `@@USERSCRIPT-PROXY-PROXY-PORT@@` port number of the HTTP proxy
158+
* `@@USERSCRIPT-PROXY-STATIC-SERVER@@` base URL of the static directory served by the proxy
159+
* `@@USERSCRIPT-PROXY-LIST@@` HTML list of available userscript sets
160+
* `@@USERSCRIPT-PROXY-PAC-URL@@` URL to download PAC from
161+
* `@@USERSCRIPT-PROXY-CA-URL@@` URL to download CA certificate from
162+
163+
## Usage Notes
164+
165+
* Please note that there currently are no access controls on this proxy server. If you route the port that Userscript Proxy is using directly to the Internet, you will be running an [open proxy](https://en.wikipedia.org/wiki/Open_proxy).
166+
* You can load userscript set-specific PAC files that limit the client device to use the proxy only for the hosts in the specified set of userscripts. Use the following URL in the proxy settings of the client device: `http://<proxy-server>:8080/userscript-proxy-<id>.pac`, where `<proxy-server>` is the hostname of the proxy server, and `<id>` is the ID of the set of userscripts you want to enable.
167+
* If you want to limit the proxy to only proxy hosts in the currently-selected userscript set (best used in conjunction with userscript set-specific PAC files, as described in the previous bullet), start the proxy server with the option `--limitHosts`.
168+
* If you want to fall back to another set of proxy PAC rules, start the proxy server with the option `--addPac <path>`, where `<path>` is the path to a PAC file on your computer. Userscript Proxy will add its proxy rules to the beginning of the `FindProxyForURL` function in that PAC file. Use the following URL in the proxy settings of the client device: `http://<proxy-server>:8080/userscript-proxy-<id>-internal.pac`, where `<proxy-server>` is the hostname of the proxy server, and `<id>` is the ID of the set of userscripts you want to enable or `all` if you want to allow all hosts in your config to be proxied.
169+
* Userscripts installed with this proxy have the same permissions as scripts running on the page itself, as they are injected directly into the HTML code. Since they are just local scripts to the page, this means that they do not have any of the additional permissions offered by Tampermonkey or Greasemonkey such as cross-site XMLHttpRequests.
170+
* If you've stopped Userscript Proxy, attempted to use it, and then restarted the proxy, your computer may still think that the proxy is down and not try to use it; you may need to force the computer to start using the proxy again by removing it, applying your changes, then enabling it and applying your changes.
171+
172+
## Implementation Notes
173+
174+
* Safari/macOS doesn't pass the URL path from requests to the proxy PAC file, and the PAC file has no visibility into the path when proxying HTTPS sites on any platform. Therefore, we can't filter which sites to proxy based on anything other than the host.
175+
* iOS doesn't let you clear the username/password cache for proxy authentication without a factory reset of the device, so it's not feasible to use proxy authentication to choose which set of userscripts to enable. If you want to try it out anyway, start the proxy with the option `--auth`.
176+
* If you don't install the CA certificate, you will have no issues with unencrypted web pages, but you will get a security warning that you can bypass for regular HTTPS connections and won't be allowed to connect at all for HTTPS connections with HSTS (e.g. Google).
177+
* The CA certificate is automatically generated after running the proxy for the first time. It is located at `~/.userscript-proxy/certs/ca.pem`. If you want to use the generated CA certificate directly from `~/.userscript-proxy/certs/ca.pem`, you may need to convert it to `der` format or use the `crt` file extension, depending on the client device. The proxy serves a version in `der` format with the `crt` extension.
178+
179+
## Acknowledgements
180+
181+
* [Aaron Kleinsteiber](https://github.com/akleinsteiber) (special thanks to Aaron for the project)
182+
* [Anthony Topper](https://github.com/tonytopper)
183+
* [Sean Gates](https://github.com/seangates)
184+
185+
## License
186+
187+
Copyright (c) 2018 eBay Inc.
188+
189+
Use of this source code is governed by a MIT-style license that can be found in the LICENSE file or at [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT).

‎bin/userscript-proxy.js

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#! /usr/bin/env node
2+
'use strict';
3+
4+
var proxy = require('../lib/userscript-proxy');
5+
var fs = require('fs');
6+
var argv = require('minimist')(process.argv.slice(2));
7+
8+
//Output usage info if incorrect number of command-line arguments
9+
if (argv['_'].length != 1) {
10+
console.log(`Userscript Proxy: HTTP proxy to inject scripts & stylesheets into existing sites
11+
Usage: node userscript-proxy.js config_file [options]
12+
Options:
13+
--loadScript set Start the proxy with the given set of userscripts active
14+
--staticDir dir Path to directory of static files to serve at /static
15+
--proxyPort port Port for HTTP proxy server (default 8888)
16+
--pacPort port Port to serve PAC and other static files (default 8080)
17+
--limitHosts Only proxy hosts in the currently-selected userscript set
18+
(use in conjunction with set-specific PAC files)
19+
--addPac file Path to existing PAC file to add proxy rules to
20+
--proxyIndex file Path to proxy index HTML file
21+
--auth Enable proxy authentication (experimental)
22+
--overrideHost Override domain name that was automatically discovered`);
23+
return;
24+
}
25+
26+
//Read config file from file specified in command-line arguments
27+
var config = JSON.parse(fs.readFileSync(argv['_'][0], 'utf8'));
28+
//Read proxy index HTML file if argument is provided
29+
if (argv['proxyIndex'] && argv['proxyIndex'] !== true) {
30+
argv['proxyIndex'] = fs.readFileSync(argv['proxyIndex'], 'utf8');
31+
}
32+
//Read PAC file to add proxy rules to, if argument is provided
33+
if (argv['addPac'] && argv['addPac'] !== true) {
34+
argv['addPac'] = fs.readFileSync(argv['addPac'], 'utf8');
35+
}
36+
37+
//Start the proxy
38+
proxy(config, argv);

0 commit comments

Comments
 (0)