From 9ea6b656c3a5fdf2fd1e6ded7258f3da82a99b27 Mon Sep 17 00:00:00 2001 From: Christopher McMahon Date: Tue, 13 Sep 2016 14:34:41 -0700 Subject: [PATCH 1/3] Rework README Clarify clone/fork vs. from scratch instructions Add CSRF-JWT demo instructions --- README.md | 117 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 98 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 982b1e738..fccdeeab9 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,63 @@ -# Electrode app with Electrode Modules -- This repo is a sample Electrode app generated from `yo electrode` with Electrode modules +# Electrode App with Electrode Modules +A sample Electrode app generated using `yo electrode` that demonstrates the usage of several Electrode modules. -## Electrode Confippet -- [Confippet](https://github.com/electrode-io/electrode-confippet) is a versatile utility for managing your NodeJS application configuration. Its goal is customization and extensibility, but offers a preset config out of the box. -- Scaffold an electrode app using the following commands: +## Install and Run + +If cloning or forking this repo, simply install via `npm` and run with `gulp`: + +```bash +$ npm install +$ NODE_ENV=development gulp hot +``` + +The app should be accessible at http://127.0.0.1:3000/ + +## Starting from Scratch + +This app was generated using [yeoman](yeoman.io) and instructions for recreating it from scratch are provided below. + +First, install `yeoman` and `electrode-generator`: + +```bash +$ npm install -g yo +$ npm install -g generator-electrode +``` +Scaffold a new app using `yeoman`: + +```bash +$ mkdir electrode-app-csrf-jwt +$ cd electrode-app-csrf-jwt +$ yo electrode ``` -npm install -g yo -npm install -g generator-electrode -yo electrode + +At this point, you should be able to run the server locally: + +```bash +$ npm install +$ NODE_ENV=development gulp hot +``` + +## Electrode Module Demos + +This application already contains demonstration code for the following modules. If you're starting from scratch using scaffolding, you can find instructions for adding and configuring individual modules below. + +- [Electrode Confippet](#electrode-confippet) +- [Electrode CSRF-JWT](#electrode-csrf-jwt) + +## Electrode Confippet + +[Confippet](https://github.com/electrode-io/electrode-confippet) is a versatile utility for managing your NodeJS application configuration. Its goal is customization and extensibility, but offers a preset config out of the box. + +### Installation + +```bash +$ npm install electrode-confippet --save ``` ### Config Files -- Once the scaffolding is complete, open the following config files: + +Open the following config files: ``` config @@ -22,9 +67,9 @@ config ``` ### Development Environment -- Update the `config/development.json` to have the following settings: +- Update the `config/development.json` to have the following settings: -``` +```json { "server": { "connections": { @@ -46,9 +91,9 @@ config - The above settings should show server log errors that may be beneficial for debugging, disable content encoding, and run the server in port 3000 ### Production Environment -- Update the `config/production.json` to have the following settings: +- Update the `config/production.json` to have the following settings: -``` +```json { "server": { "connections": { @@ -73,7 +118,7 @@ config - Keys that exist in the `config/default.json` that are also in the other environment configs will be replaced by the environment specific versions ### Confippet Require -- In Electrode, the configurations are loaded from `server/index.js` at this line: +- In Electrode, the configurations are loaded from `server/index.js` at this line: ``` const config = require("electrode-confippet").config; @@ -83,16 +128,50 @@ require("electrode-server")(config, [staticPathsDecor()]); ``` ### Running Electrode app -- Start the electrode app in `development` environment: +- Start the electrode app in `development` environment: +```bash +$ NODE_ENV=development gulp hot ``` -NODE_ENV=development gulp hot + +- Start the electrode app in `production` environment: + +```bash +$ NODE_ENV=production gulp hot ``` -- Start the electrode app in `production` environment: +- Running in the selected environment should load the appropriate configuration settings + +## Electrode CSRF-JWT + +[CSRF-JWT](https://github.com/electrode-io/electrode-csrf-jwt) is an Electrode plugin that allows you to authenticate HTTP requests using JWT in your Electrode applications. +### Installation + +Add the `electrode-csrf-jwt` component: + +```bash +$ npm install electrode-csrf-jwt --save ``` -NODE_ENV=production gulp hot + +Next, register the plugin with the Electrode server. Add the following configuration to the `plugins` section of `config/default.json`: + +```json + "electrode-csrf-jwt": { + "options": { + "secret": "test", + "expiresIn": 60 + } + } ``` -- Running in the selected environment should load the appropriate configuration settings +That's it! CSRF protection will be automatically enabled for endpoints added to the app. CSRF JWT tokens will be returned in the headers of every `GET` response and must be provided as a header in every `POST` request. + +> You can read more about options and usage details on [the component's README page](https://github.com/electrode-io/electrode-csrf-jwt#usage) + +### CSRF-JWT Demonstration code + +In addition to the above steps, the following modifications were made in order to demonstrate functionality: + +* A plugin with two endpoints was added as `server/plugins/csrf.js` and registered via `config/default.json` +* AJAX testing logic was added to `client/components/csrf.jsx` From 2d8d4f88b6409bb0148b300cc9a4c2549d104aab Mon Sep 17 00:00:00 2001 From: Christopher McMahon Date: Wed, 14 Sep 2016 12:35:11 -0700 Subject: [PATCH 2/3] Update to clarify CSRF tokens in both headers and cookies --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 401ed406f..8a1dd5714 100644 --- a/README.md +++ b/README.md @@ -169,7 +169,7 @@ Next, register the plugin with the Electrode server. Add the following configura } ``` -That's it! CSRF protection will be automatically enabled for endpoints added to the app. CSRF JWT tokens will be returned in the headers of every `GET` response and must be provided as a header in every `POST` request. +That's it! CSRF protection will be automatically enabled for endpoints added to the app. CSRF JWT tokens will be returned in the headers and set as cookies for every `GET` response and must be provided as both a header and a cookie in every `POST` request. > You can read more about options and usage details on [the component's README page](https://github.com/electrode-io/electrode-csrf-jwt#usage) From 79992a3cab00d2585d56ce4426c436b0c45e404f Mon Sep 17 00:00:00 2001 From: Christopher McMahon Date: Wed, 14 Sep 2016 12:55:46 -0700 Subject: [PATCH 3/3] Clarify CSRF-JWT response behavior --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8a1dd5714..fe1f84ae5 100644 --- a/README.md +++ b/README.md @@ -169,7 +169,7 @@ Next, register the plugin with the Electrode server. Add the following configura } ``` -That's it! CSRF protection will be automatically enabled for endpoints added to the app. CSRF JWT tokens will be returned in the headers and set as cookies for every `GET` response and must be provided as both a header and a cookie in every `POST` request. +That's it! CSRF protection will be automatically enabled for endpoints added to the app. CSRF JWT tokens will be returned in the headers and set as cookies for every response and must be provided as both a header and a cookie in every `POST` request. > You can read more about options and usage details on [the component's README page](https://github.com/electrode-io/electrode-csrf-jwt#usage)