Delegated Account Recovery Example Application for Node.js

The "examples/nodejs" directory of https://github.com/facebook/DelegatedRecoveryReferenceImplementation provides an example web application and library for using the Delegated Account Recovery protocol documented at https://github.com/facebook/DelegatedRecoveryReferenceImplementation

Usage

This is a Node.js application built with the Express framework. It is packaged for deployment on Heroku, but should be easily adaptable to any Node.js environment.

index.js contains the example application. This application is, apart from some cryptographic keys, stateless, and only demonstrates the protocol flows without creating actual user accounts.

This code is for example purposes only, to demonstrate the concepts of Delegated Account Recovery. Because the application does not persist any state, you will not be able to recover "accounts" across resets of the runtime, including when Herkou puts the application to sleep and restores it.

Dependencies

The example application is written in ES2015 for Node JS >= 6.10.0

It uses the delegated-account-recovery module to implement core features of Delegated Account Recovery.

The example application is built with the Express framework. The application is built to run on the Heroku cloud application platform, but has only a few lines of Herkou-specific code, to manage configuration of application secrets and handle Heroku's idiosyncracies in how https is routed. The application should be easily adapted to any Node.js hosting environment. Refer to the documentation for your specific environment to configure https and secure storage for application secrets.

The example application requires the following additional NPM modules:

Following the step-by-step tutorial included in the example application will require

  • a bash command line environment with git, openssl, and curl available
  • a Heroku account
  • the Heroku toolbelt installed for working with Node.js applications

Installation

Begin by forking the repository. In the top right corner of the repository home page on GitHub, click Fork

Now, in your bash command line, get a copy of the forked repository.

$ git clone https://github.com/{your-github-username}/DelegatedRecoveryReferenceImplementation

Change to the root directory of your cloned repository

$ cd DelegatedRecoveryReferenceImplementation

Edit the examples/nodejs/app.json and examples/nodejs/package.json files and make sure the "repository" properties point to your fork of the application.

These steps must be run from the root directory of your repository clone.

  1. First, commit your updates to app.json and package.json
  2. Next, create a heroku app. The results of this command will tell you your app name.
  3. Push the subtree containing the example app to the heroku git remote created by step 2.
$ git commit -am "update app.json and package.json"
$ heroku create
$ git subtree push --prefix examples/nodejs heroku master

Ensure that at least one instance of the app is running:

$ heroku ps:scale web=1

Next, you need to set some config variables for the application. You must have a recent build of openssl to complete this step.

First, you need to create the assymetric key pair for signing recovery tokens.

$ openssl ecparam -name prime256v1 -genkey -noout -out prime256v1-key.pem
$ openssl ec -in prime256v1-key.pem -pubout -out prime256v1-pub.pem

Make sure you don't check the secret keys into your source control. (it's fine to check in the public key if you want)

$ echo "*.pem" >> .gitignore

And now we'll strip the PEM files down to unadorned, single-line base64 and set them as config variables.

$ heroku config:set RECOVERY_PRIVATE_KEY=`perl -p -e 's/\R//g; s/-----[\w\s]+-----//' prime256v1-key.pem`
$ heroku config:set RECOVERY_PUBLIC_KEY=`perl -p -e 's/\R//g; s/-----[\w\s]+-----//' prime256v1-pub.pem`

Now, set the value your application needs to report as its issuer in the Delegated Account Recovery configuration: (note that not trailing slash is allowed)

$ heroku config:set ISSUER_ORIGIN="https://{your-app-name}.herokuapp.com"

You can see your current configuration using:

$ heroku config

Check that your application deployed successfully with these configuration variables from the command line:

$ curl https://{your-app-name}.herokuapp.com/.well-known/delegated-account-recovery/configuration

You should get a JSON file that lists your public key as the first entry in the array that is the value of the key tokensign-pubkeys-secp256r1

You can try the application itself by running:

$ heroku open

During the closed beta, you will only be able to use the sample applications when logging in to Facebook with a whitehat test account. Create and manage test accounts here.