Otiluke

Otiluke is a toolbox for JavaScript source-to-source compilers (also called transpiler) which are written as CommonJS modules. Otiluke is itself an npm module and can be installed with npm install otiluke -g. With Otiluke you can:

1. Debug and benchmark your JavaScript transpiler: --test
2. Demonstrate how awesome your JavaScript transpilers are: --demo
3. Deploy your JavaScript transpiler on node modules: --node
4. Deploy your JavaScript transpiler on online HTML pages: --mitm

Otiluke expects the JavaScript transpiler to be a CommonJS module exporting a transformation function. This transformation module will always be executed side-to-side with the program targetted for transformation. Such online transformation process enables easy support for dynamic code evaluation. Below is the Otiluke's demo tool; see usage for more examples.

Test Tool

The --test tool deploys a local HTTP server at the given port, it is usefull to debug and benchmark a transformation module. On receiving an HTTP request, the server browserify the given transformation module and bundle the target(s) pointed by the request's URL. The request's URL can point to a single target JavaScript file or a directory exclusively containing target JavaScript files.

otiluke --test --transform /path/to/transform.js --port 8080

require("otiluke").test({transform:"/path/to/transform.js", port:8080});

Demo Tool

The --demo tool browserifies the given transformation module(s) inside a standlone html page and writes it into the given output file. The transform option can point to a single transformation module or a directory exclusively containing transformation modules. Use this tool to demonstrate how awesome are your transformation modules. Note that only the dependencies initially present in the given transformation modules will be bundled into the page, therefore arbitrary requires are not supported in the demo page.

otiluke --demo --transform /path/to/transform.js --out ./bundle.html

require("otiluke").demo({transform:"/path/to/transform.js", port:8080});

Node Tool

The --node tool first executes the given transformation module. The main file and its dependencies are then transformed before being executed.

otiluke --node --transform /path/to/transform.js --main /path/to/main.js

require("otiluke").node({transform:"/path/to/transform.js", main:"/path/to/main.js"});

MITM Tool

The --mitm tool deploys a HTTP proxy at the given port which effectively implements the man-in-the-middle attack. The given transformation module is browserified into every requested HTML page while the JavaScript traffic is stringified and passed to the transformation function. Note that inline event handlers are NOT intercepted (yet).

otiluke --mitm --transform /path/to/transform.js --port 8080

require("otiluke").mitm({transform:"/path/to/transform.js", port:"/path/to/main.js"});

The --mitm tools requires openssl to be accessible via the PATH. Also, two modifications should be done on your browser (here Firefox but should works on other browsers as well) before deploying the MITM proxy:

1. You have to indicate Firefox that you trust Otiluke's root certificate. Go to about:preferences#advanced then click on Certificates then View Certificates. You can now import Otiluke's root certificate which can be found at /path/otiluke/mitm/ca/cacert.pem. Note that you can reset all Otiluke's certificates with

   otiluke --mitm --reset

   require("otiluke").mitm({reset:true});

   

   After changes in certificates' trust, restart Firefox to avoid sec_error_reused_issuer_and_serial error.

2. You have to redirect all Firefox requests to the local port where the MITM proxy is deployed. Go again to about:preferences#advanced then click on Network then Settings.... You can now tick the checkbox Manual proxy configuration and Use this proxy server for all protocols. The HTTP proxy fields should be the localhost 127.0.0.1 and the port given in the options.