Web2Native Bridge - Uniting the "Web" and "App" worlds

Note: this is a system in development, the specification may change anytime without notice

This repository contains all code for building and testing an emulation of the Web2Native Bridge concept (https://cyberphone.github.io/doc/web/web2native-bridge.pdf) using the Google Chrome and Mozilla Firefox desktop browsers. It also runs on the Open Source Chromium browser.

The emulator code exploits Chrome's native messaging (https://developer.chrome.com/extensions/nativeMessaging) featured in a single universal Chrome/Firefox extension.

Applications callable by the Web2Native Bridge emulator must be written in Java and stored in a for the purpose dedicated directory.

API

The Web2Native Bridge emulator extends the navigator object by a single method
nativeConnect('Name of target application' [, optionalArgument]) which returns a JavaScript Promise to a port object.

The port object supports the following methods and events:

postMessage(message)
disconnect()
addMessageListener(function(message))
addDisconnectListener(function())

optionalArgument and message must be valid JSON-serializable JavaScript objects.

An example which could be hosted in an ordinary (non-privileged) web page:

navigator.nativeConnect('com.example.myapp').then(function(port) {

    port.addMessageListener(function(message) {
        // We got a message from the native application...
    });

    port.addDisconnectListener(function() {
        // Native application disconnected...
    });

    port.postMessage({greeting:'Native app, how are you doing?'});
    // Note: JavaScript serialization makes the above a genuine JSON object

    port.disonnect();  // Not much of a conversation going on here...

}, function(err) {
    console.debug(err);
});

The argument to nativeConnect holds the name of the specifically adapted local application to invoke. The current scheme uses a Java-inspired dotted path pointing to a subdirectory and JAR-application having this name.

Manifest

For specifying access to native applications there must be a JSON-formatted manifest file associated with each application. The following manifest provides universal access to an application:

{
  "callableFrom": ["*://*/*", "file:///*"]
}

A more restrictive manifest could limit access to a single domain and https operation:

{
  "callableFrom": ["https://example.com/*", "https://*.example.com/*"]
}

Architecture

The Web2Native Bridge emulator always invokes a central proxy located at proxy/install/w2nb-proxy.

The proxy in turn dispatches a call to the specific target application located at
proxy/install/apps/dottedpath/dottedpath.jar.

The mandatory manifest file is stored at
proxy/install/apps/dottedpath/manifest.json.

Common Java libraries may be stored in proxy/install/libs.

For debugging purposes there is also a logging system writing data in proxy/install/logs.

All local I/O between the browser, proxy and the callable applications is performed through stdin and stdout.

Native Application Interface

Native applications (in the prototype Java applications hosted in JAR-files) are called as follows:

args[0]	Absolute path to the proxy/install directory
args[1]	Application name (dotted path)
args[2]	URL of calling web page
args[3]	Coordinates of calling web page
args[4]	Custom invocation data (OptionalArgument)
args[5...]	Chrome's Native Messaging arguments

For detailed information about the format of these fields, turn to the code :-)

Installation

Prerequisites

You need to have Java SE version 8 installed to run the Web2Native Bridge emulator
OS/X and Linux installations presume that clang respectively g++ is available
Clone the web2native-bridge master repository or just download the ZIP via GitHub to any free directory

Note: If you are using Oracle Java you must install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files as well.

Chrome/Chromium specific steps

Start a terminal window and move to proxy/install. Then run the install-proxy script that suits your platform
Install the Web2Native Bridge browser extension from the Chrome Web Store: https://chrome.google.com/webstore/detail/web2native-bridge-emulato/jphfmfbdedghfhhjijaogeloiehomfni
In Chrome, go to Settings->Extensions and check "Allow access to file URLs" for the Web2Native Bridge extension

Firefox specific steps

Start a terminal window and move to firefox/install. Then run the install-proxy script that suits your platform
Install the Web2Native Bridge browser extension from the file firefox/install/xpi/web2native_bridge_emulator-1.0.xpi using the Firefox menu option: Add-ons->Extensions->Install Add-on from file.

Testing the installation

Now you can try the two sample applications (see next sections) since they are installed by default.

Please don't hesitate contacting me if you run into problems during installation or execution of the emulator!

Basic Sample Application

The HTML file sample1/demo/sample1.html does approximately the same thing as the application depicted in http://www.cnet.com/news/google-paves-over-hole-left-by-chrome-plug-in-ban/ albeit with a few significant enhancements:

The sample application is invoked by an ordinary web page
The Web2Native Bridge browser extension is fully generic and can support any number of very different applications
The Web2Native Bridge adds positioning support enabling alignment UI-wise with the web

The native part of the sample application resides in proxy/install/apps/org.webpki.w2nb.sample1/org.webpki.w2nb.sample1.jar.

Single Page Application

Although not a design goal, the Web2Native Bridge API is also compliant with the SPA concept:
https://en.wikipedia.org/wiki/Single-page_application

Security Considerations

Since an emulator by definition isn't the "real thing" some limitations apply. That is, the Web2Native Bridge emulator is not intended for production since it doesn't support the following security measures:

Native application vetting infrastructure. An improperly designed native message extension could enable web access to the entire computer!
HTTPS information
Site-blocking support and associated administration

Although not entirely comforting, Chrome's native messaging framework also lacks these qualities...

In addition, the scheme injects code in every web page visited which is a core "feature" of Chrome extensions slowing down execution. It is probably wise disabling the extension (using Chrome settings) when not using it.

cyberphone/web2native-bridge