SAFE Browser Application
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Improved vscode search (#856) Mar 27, 2017
__e2e__ fix(tests): OSX and Linux e2e tweaks Nov 29, 2018
__tests__ Enhance back/forwards (#446) Dec 3, 2018
app tests(E2E): Register and log checks for protocol handling via electron. Dec 17, 2018
flow-typed/npm WebId updates and enhancements. (#297) Aug 21, 2018
flow Add SASS support to project (#880) Mar 31, 2017
img Update Readme Stack (#882) Mar 31, 2017
mocks WebId updates and enhancements. (#297) Aug 21, 2018
resources feat(UI): loads favicons in tab bar Nov 23, 2018
.babelrc Feat(antd): Adding in ant design for experminetal toggles Nov 28, 2018
.editorconfig added in peruse base browser code Apr 17, 2017
.eslintignore feat/background: Move peruse safe-app to a background process. Feb 22, 2018
.eslintrc added in peruse base browser code Apr 17, 2017
.flowconfig feat/background: Move peruse safe-app to a background process. Feb 22, 2018
.gitattributes chore(dev): preloaded MockVault for development (#393) Oct 5, 2018
.gitignore feat/background: Move peruse safe-app to a background process. Feb 22, 2018
.npmrc WebId updates and enhancements. (#297) Aug 21, 2018
.nvmrc chore/electron: update electron to 1.8.4 Mar 27, 2018
.tern-project Added proper tern support (#711) Feb 3, 2017
.travis.yml tests(E2E): Register and log checks for protocol handling via electron. Dec 17, 2018
CHANGELOG.md Feat(Changelog): Add standard-version package (#363) Sep 18, 2018
LICENSE-BSD docs(Readme): Add documentation about the exposed DOM API available t… Sep 14, 2018
LICENSE-MIT docs(Readme): Add documentation about the exposed DOM API available t… Sep 14, 2018
README.md chore(naming): Peruse is now SAFE Browser (#391) Oct 9, 2018
appveyor.yml chore(naming): Peruse is now SAFE Browser (#391) Oct 9, 2018
jest.config.js chore(safe-node-app): Upgrade @maidsafe/safe-node-app dependency to v… Dec 11, 2018
package.json chore(safe-node-app): Upgrade @maidsafe/safe-node-app dependency to v… Dec 11, 2018
post-pack.js fix(package): crust.config matches executable on Windows Dec 3, 2018
postcss.config.js chore/linting Nov 3, 2017
releaseName.js chore/CI: only test packaged app Sep 10, 2018
runE2ETests.js feat(Tests): Add tests to check login/logout behaviour. Oct 12, 2018
tests_setup.js WebId updates and enhancements. (#297) Aug 21, 2018
updateAppVersionWithChangelog.js Feat(Changelog): Add standard-version package (#363) Sep 18, 2018
webpack.config.background.prod.js fix/safe-node-js: fixes for function renaming May 25, 2018
webpack.config.base.js Feat(antd): Adding in ant design for experminetal toggles Nov 28, 2018
webpack.config.browser.preload.js feat/tests: All wrapper DOM API funcs tested Apr 16, 2018
webpack.config.eslint.js added in peruse base browser code Apr 17, 2017
webpack.config.main.prod.js feat/webpack: update to webpack 4 + related deps. Mar 30, 2018
webpack.config.renderer.dev.dll.js feat/webpack: update to webpack 4 + related deps. Mar 30, 2018
webpack.config.renderer.dev.js Feat(UI): Add extensible settings menu Nov 28, 2018
webpack.config.renderer.live.dev.dll.js feat/webpack: update to webpack 4 + related deps. Mar 30, 2018
webpack.config.renderer.live.dev.js chore/merge: Merge in master Mar 30, 2018
webpack.config.renderer.preload.js feat/tests: All wrapper DOM API funcs tested Apr 16, 2018
webpack.config.renderer.prod.js feat/webpack: update to webpack 4 + related deps. Mar 30, 2018
webpack.config.test.js feat/webpack: update to webpack 4 + related deps. Mar 30, 2018
yarn.lock chore(safe-node-app): Upgrade @maidsafe/safe-node-app dependency to v… Dec 11, 2018

README.md

SAFE Browser

About

Built upon peruse, but using its baked in extensibility to add SAFE Network functionality.

Installation

For normal SAFE Network browsing, you should download the latest version of the browser from The SAFE Browser releases page.

Application developers should use the same link, but choose the -dev postfixed version for their platform. This version uses a mock network to allow local development (without the need to pay PUT costs on a live SAFE Network).

WebApp Development

There are -dev postfixed releases of SAFE Browser available. These come with both live network and mock network libs, bundled.

By default, opening the app will open SAFE Browser for the mock network.

Otherwise, there is the option to pass a --live flag to the browser. This will start the browser in a live network mode.

eg, on OSX:

open SAFE Browser.app --args --live

SAFE Network API

SAFE Browser exposes a set of APIs in the DOM which webapps can make use to connect to the SAFE Network, as well as fetch and store data on it.

A webapp has direct access to this set of APIs through the DOM at window.safe.

The SAFE Network client API exposed by SAFE Browser is a simple wrapper on top of the API provided by the @maidsafe/safe-node-app package (with a few minor exceptions explained below), therefore the documentation available for the safe-node-app API is valid and is the main reference for any developer wanting to create a webapp for The SAFE Network.

This API documentation can be found at the following URL: https://docs.maidsafe.net/safe_app_nodejs

As an example, if a webapp is trying to make use of the initialiseApp function, it simply needs to prefix the function name with window.safe, i.e. it shall simply call window.safe.initialiseApp and provide the parameters as described in that documentation. Note that it's not needed to import/require the safe-app-node package with require('@maidsafe/safe-node-app') from a webapp.

You will find some example code snippets in the API documentation as well, that you can use to learn, and also look at the Debugging section below for the interactive tool to try out the API.

As mentioned above, there are only a few functions related to the initialisation and app authorisation request process that are exposed by SAFE Browser and which slightly differ from the safe-app-node API:

  • There are no initialisation options supported by the initialiseApp function exposed in the DOM API
  • There are no initialisation options supported by the fromAuthUri function exposed in the DOM API
  • openUri is not available in the DOM API. A webapp shall instead call the window.safe.authorise function to send an authorisation request to the Authenticator. E.g.:
    const appInfo = {
        name: 'Hello SAFE Network',
        id: 'net.maidsafe.tutorials.web-app',
        version: '1.0.0',
        vendor: 'MaidSafe.net Ltd.'
    };
    
    async function authoriseAndConnect() {
      console.log('Initialising a SAFE app client instance...');
      const safeApp = await window.safe.initialiseApp(appInfo);
    
      console.log('Authorising the application...');
      const authReqUri = await safeApp.auth.genAuthUri();
      const authUri = await window.safe.authorise(authReqUri);
      console.log('SAFE application authorised by user');
    
      await safeApp.auth.loginFromUri(authUri);
      console.log("Application connected to the network");
    };
    

Experimental APIs

You are free to use any of the experimental APIs exposed, to explore the features and APIs that are being actively developed.

Although you should be aware of the fact that all/any of the experimental APIs may be moved behind a feature flag, changed, deprecated, or even removed in the future, and without much anticipated notification by the core developers.

The reason they are exposed is to just allow developers to experiment and start learning about the APIs at an early stage.

SAFE WebId

SAFE uses the RDF compliant WebId system for easily enabling user account management.

You can retrieve the current WebId via window.currentWebId.

Additionally, you can listen for changes via the event emitter, window.webIdEventEmitter, eg:

webIdEventEmitter.on('update', ( webId ) => {
  console.log('an update to current WebID occurred!', webId);
});

There is a set of very experimental APIs available on a SAFEApp instance (the object you obtain from calling window.safe.initialiseApp) which are utilities to manipulate WebIDs and public names. Since they are in their very early stage there is no documentation available just yet, but in case you want to explore them, this is an example how you can access them:

const safeApp = await window.safe.initialiseApp( appInfo );
await safeApp.web.createPublicName( ... );

RDF utilities

Another set of utilities in their early stage of development can be found in the RDF and WebID emulations. As you probably know our MutableData API supports emulations to be implemented on top of them, e.g. our NFS emulation allows apps to access the MutableData data as if it was a files directory.

In an analogous way to the NFS emulation, the RDF and WebID emulations can be applied on top of any MutableData object, e.g.:

const safeApp = await window.safe.initialiseApp( appInfo );
// authorise and connect to the network...
...
const md = await safeapp.mutableData.newRandomPublic( 15001 );
await md.quickSetup();
const rdfEmulation = await md.emulateAs( 'rdf' );

Debugging

A --debug flag is also available to get extra logs and devtool windows when working with a packaged application.

Additionally, the --preload flag can be passed in order to get the following features preloaded in mock network mode:

  • An interactive tool to learn about the browser's SAFE network API, located at safe://api.playground
  • Account login credentials, both secret and password being mocksafenetworkdeveloper

open SAFE Browser.app --args --mock --preload

Browser Development

Compiling

Make sure you have both git and yarn installed.

You need to use node.js version 8.x to build the browser currently.

  • git clone https://github.com/maidsafe/safe_browser.git
  • cd safe_browser
  • NODE_ENV=dev yarn (NODE_ENV is needed to install mock libs and to run yarn mock-dev).
  • yarn rebuild

And to run dev mode:

  • yarn mock-dev

Want to run 'production' variables, but with hot reloading?

  • yarn put-live-net-files-for-<windows|osx|linux>
  • yarn prod-dev

Note, you'll need a crust.config set for the application. Helper commands for osx/linux/windows

And to package:

  • yarn package

The resulting packages are contained within the releases folder.

A packaged application, built in a NODE_ENV=dev, can access either prod or dev networks. prod is the default, or alternatively you can open the application and pass a --mock flag to open and use a mock network.

Build commands

There are a few build commands for various situations:

  • yarn mock-dev will run a developer version of the application using MockVault
  • yarn prod-dev will run a developer version of the application using the live network.
  • yarn build compiles all code, but you shouldn't need to use this
  • yarn build-preload will need to be run whenever you change the preload.js file for changes to show up in the browser.

Release

yarn bump is available for automatically updating versions and generating a changelog update based upon conventional-commits.

Redux

The core is built around redux for simple state management allowing for easy extensibility.

React

The interface is built in react for simple data flow and clear componentisation.

Webpack

webpack.config.base contains loaders and alias' used across all webpack configs.

There is a prod, config. Alongside renderer configs.

When developing against hot reloading, the vendor setup is used to speed up build times etc.

There are 'dev' mode configs for running against the NODE_ENV=develeopment setup. There are 'live-dev' configs for running against NODE_ENV=production but without needing to package.

Testing

  • yarn test runs jest (you have the optional yarn test-watch, too).
  • yarn test-e2e runs spectron integration tests (not yet stable).
  • yarn lint ...lints...

Logging

Via electron-log: import logger from 'logger', and you can logger.info('things').

Logs are printed to both render console and stdout. Logs are also written to a log file per system.

yarn log-osx will tail the file. Similar commands (as yet untested) exist for linux/windows.

SAFE Network

The safe code is contained within the app/extensions folder. This includes a simple http server with is used to provide the http like functionalities of the safe network.

Currently you need to authenticate against the SAFE Browser to get network access.

Authenticator

Currently, we're using a temp_dist version of the authenticator webapp, prebuilt from the 'beaker-plugin-safe-authenticator'.

  • APIs are located in app/extensions/safe/api;
  • APIs are located in app/extensions/safe/auth-api;

Further Help

You can discuss development-related questions on the SAFE Dev Forum. If you are just starting to develop an application for the SAFE Network, it's very advisable to visit the SAFE Network Dev Hub where you will find a lot of relevant information, including tutorials.

License

SAFE Browser is a lightly modified fork of the Peruse Browser.

This SAFE Network application is dual-licensed under the Modified BSD (LICENSE-BSD https://opensource.org/licenses/BSD-3-Clause) or the MIT license (LICENSE-MIT https://opensource.org/licenses/MIT) at your option.