Phase 0: Backend Setup (With Detailed Comments)

Understanding the Problem

In this phase, we need to set up the backend of our authentication application. This includes creating the project structure, installing dependencies, setting up Sequelize, initializing Express, and configuring security middlewares.

The goal is to have a well-structured Express application ready for implementing authentication features in later phases.

Planning the Solution

1. Create the project folder structure
2. Set up the README.md file
3. Create a .gitignore file
4. Initialize Git repository
5. Create backend and frontend folders
6. Install necessary backend dependencies
7. Set up environment variables
8. Configure Sequelize
9. Set up Express application with security middleware
10. Create routes
11. Configure the server
12. Set up User model, migration, and seeder
13. Test the server

Implementing the Solution

1. Create Project Folder Structure

Start by creating a root folder for your project. The name should be meaningful and represent your project.

mkdir my_authentication_project
cd my_authentication_project

2. Set up README.md

Create a README.md file at the root of your project to document your API and database schema.

touch README.md

Add the following content to README.md:

# My Authentication Project

## Database Schema Design

![db-schema](./images/db-schema.png)

## API Documentation

### All endpoints that require authentication

All endpoints that require a current user to be logged in.

* Request: endpoints that require authentication
* Error Response: Require authentication
  * Status Code: 401
  * Headers:
    * Content-Type: application/json
  * Body:

    ```json
    {
      "message": "Authentication required"
    }
    ```

3. Create .gitignore File

Create a .gitignore file at the root to exclude certain files from version control:

touch .gitignore

Add the following content to .gitignore:

node_modules
.env
build
.DS_Store
*.db

4. Initialize Git Repository

Configure Git to use 'main' as the default branch, initialize the repository, and make your first commit:

git config --global init.defaultBranch main
git init
git add .
git commit -m 'Initial commit'

Create a remote GitHub repository and connect it to your local repository:

git remote add origin <github-remote-url>
git push origin main

5. Create Backend and Frontend Folders

Create folders to separate backend and frontend code:

mkdir backend frontend images

6. Install Backend Dependencies

Initialize the package.json file in the backend folder and install necessary dependencies:

cd backend
npm init -y
npm install cookie-parser cors csurf dotenv express express-async-errors helmet jsonwebtoken morgan per-env sequelize@6 sequelize-cli@6 pg
npm install -D sqlite3 dotenv-cli nodemon

7. Set Up Environment Variables

Create a .env file in the backend folder:

touch .env

Add the following content to the .env file:

PORT=8000
DB_FILE=db/dev.db
JWT_SECRET=your_secret_here
JWT_EXPIRES_IN=604800
SCHEMA=your_schema_name_here

To generate a strong JWT secret, you can use the openssl command:

openssl rand -base64 10

8. Create Configuration Files

Create a config folder in the backend folder and add an index.js file for environment variables:

mkdir -p backend/config
touch backend/config/index.js

Add the following content to config/index.js:

// backend/config/index.js
module.exports = {
  environment: process.env.NODE_ENV || 'development',  // Default to development if not specified
  port: process.env.PORT || 8000,                      // Server port, fallback to 8000
  dbFile: process.env.DB_FILE,                         // Database file location
  jwtConfig: {
    secret: process.env.JWT_SECRET,                    // Secret key for JWT signing
    expiresIn: process.env.JWT_EXPIRES_IN              // JWT expiration time
  }
};

9. Set Up Sequelize

Create a .sequelizerc file in the backend folder:

touch backend/.sequelizerc

Add the following content to .sequelizerc:

// backend/.sequelizerc
const path = require('path');

module.exports = {
  config: path.resolve('config', 'database.js'),          // Database configuration path
  'models-path': path.resolve('db', 'models'),            // Models directory path
  'seeders-path': path.resolve('db', 'seeders'),          // Seed data directory path
  'migrations-path': path.resolve('db', 'migrations')     // Migrations directory path
};

Initialize Sequelize:

npx sequelize init

Update the config/database.js file with the following content:

// backend/config/database.js
const config = require('./index');

module.exports = {
  development: {
    storage: config.dbFile,                 // SQLite file location
    dialect: "sqlite",                      // Use SQLite in development
    seederStorage: "sequelize",             // Store seeder execution history in the database
    logQueryParameters: true,               // Log query parameters for debugging
    typeValidation: true                    // Enable strict type validation
  },
  production: {
    use_env_variable: 'DATABASE_URL',       // Use DATABASE_URL from environment
    dialect: 'postgres',                    // Use PostgreSQL in production
    seederStorage: 'sequelize',             // Store seeder execution history
    dialectOptions: {
      ssl: {
        require: true,                      // Require SSL for security
        rejectUnauthorized: false           // Allow self-signed certificates
      }
    },
    define: {
      schema: process.env.SCHEMA           // Set schema for PostgreSQL
    }
  }
};

Create a psql-setup-script.js file in the backend folder:

touch backend/psql-setup-script.js

Add the following content to psql-setup-script.js:

// backend/psql-setup-script.js
const { sequelize } = require('./db/models');

sequelize.showAllSchemas({ logging: false }).then(async (data) => {
  if (!data.includes(process.env.SCHEMA)) {
    await sequelize.createSchema(process.env.SCHEMA);  // Create schema if it doesn't exist
  }
});

10. Set Up Express Application

Create an app.js file in the backend folder:

touch backend/app.js

Add the following content to app.js:

// backend/app.js
const express = require('express');
require('express-async-errors');                // Automatically catch async errors
const morgan = require('morgan');               // HTTP request logger
const cors = require('cors');                   // Cross-Origin Resource Sharing
const csurf = require('csurf');                 // CSRF protection
const helmet = require('helmet');               // Security headers
const cookieParser = require('cookie-parser');  // Parse cookies in requests

const { environment } = require('./config');
const isProduction = environment === 'production';

const app = express();

// Connect morgan middleware for logging HTTP requests
app.use(morgan('dev'));

// Parse cookies and JSON bodies
app.use(cookieParser());
app.use(express.json());

// Security middleware
if (!isProduction) {
  // Enable CORS only in development
  // In production, frontend and backend should be on same domain
  app.use(cors());
}

// Helmet helps set security headers
app.use(
  helmet.crossOriginResourcePolicy({
    policy: "cross-origin"                  // Allow resources to be shared cross-origin
  })
);

// Set the _csrf token and create req.csrfToken method
app.use(
  csurf({
    cookie: {
      secure: isProduction,                 // HTTPS only in production
      sameSite: isProduction && "Lax",      // Controls when cookies are sent with cross-site requests
      httpOnly: true                        // Prevents JavaScript access to cookies
    }
  })
);

// Connect routes
const routes = require('./routes');
app.use(routes);

module.exports = app;

11. Create Routes

Set up the routes folder and create an index.js file:

mkdir -p backend/routes
touch backend/routes/index.js

Add the following content to routes/index.js:

// backend/routes/index.js
const express = require('express');
const router = express.Router();

// Test route - serves as a health check and sets CSRF token
router.get('/hello/world', function(req, res) {
  res.cookie('XSRF-TOKEN', req.csrfToken());  // Set CSRF token in cookie for frontend
  res.send('Hello World!');                    // Simple response to confirm server works
});

// CSRF token restoration route
router.get("/api/csrf/restore", (req, res) => {
  const csrfToken = req.csrfToken();
  res.cookie("XSRF-TOKEN", csrfToken);         // Set token in cookie
  res.status(200).json({
    'XSRF-Token': csrfToken                    // Also return token in JSON response
  });
});

module.exports = router;

12. Set Up User Model and Migration

Create a User model and migration:

npx sequelize model:generate --name User --attributes username:string,email:string,hashedPassword:string

This command creates:

• A User model file in db/models/user.js
• A migration file in db/migrations/ with a timestamp

Update the User model in db/models/user.js:

// backend/db/models/user.js
'use strict';
const { Model, Validator } = require('sequelize');
const bcrypt = require('bcryptjs');

module.exports = (sequelize, DataTypes) => {
  class User extends Model {
    toSafeObject() {
      const { id, username, email } = this; // context will be the User instance
      return { id, username, email };
    }

    validatePassword(password) {
      return bcrypt.compareSync(password, this.hashedPassword.toString());
    }

    static getCurrentUserById(id) {
      return User.scope("currentUser").findByPk(id);
    }

    static async login({ credential, password }) {
      const { Op } = require('sequelize');
      const user = await User.scope('loginUser').findOne({
        where: {
          [Op.or]: {
            username: credential,
            email: credential
          }
        }
      });
      if (user && user.validatePassword(password)) {
        return await User.scope('currentUser').findByPk(user.id);
      }
    }

    static async signup({ username, email, password }) {
      const hashedPassword = bcrypt.hashSync(password);
      const user = await User.create({
        username,
        email,
        hashedPassword
      });
      return await User.scope('currentUser').findByPk(user.id);
    }

    static associate(models) {
      // define association here
    }
  }
  
  User.init({
    username: {
      type: DataTypes.STRING,
      allowNull: false,
      validate: {
        len: [4, 30],
        isNotEmail(value) {
          if (Validator.isEmail(value)) {
            throw new Error("Cannot be an email.");
          }
        }
      }
    },
    email: {
      type: DataTypes.STRING,
      allowNull: false,
      validate: {
        len: [3, 256],
        isEmail: true
      }
    },
    hashedPassword: {
      type: DataTypes.STRING.BINARY,
      allowNull: false,
      validate: {
        len: [60, 60]
      }
    }
  }, {
    sequelize,
    modelName: 'User',
    defaultScope: {
      attributes: {
        exclude: ['hashedPassword', 'email', 'createdAt', 'updatedAt']
      }
    },
    scopes: {
      currentUser: {
        attributes: { exclude: ['hashedPassword'] }
      },
      loginUser: {
        attributes: {}
      }
    }
  });
  return User;
};

Update the migration file in db/migrations/XXXXXXXXXXXXXX-create-user.js:

// backend/db/migrations/XXXXXXXXXXXXXX-create-user.js
'use strict';

let options = {};
if (process.env.NODE_ENV === 'production') {
  options.schema = process.env.SCHEMA;  // define your schema in options object
}

module.exports = {
  up: async (queryInterface, Sequelize) => {
    return queryInterface.createTable('Users', {
      id: {
        allowNull: false,
        autoIncrement: true,
        primaryKey: true,
        type: Sequelize.INTEGER
      },
      username: {
        type: Sequelize.STRING(30),
        allowNull: false,
        unique: true
      },
      email: {
        type: Sequelize.STRING(256),
        allowNull: false,
        unique: true
      },
      hashedPassword: {
        type: Sequelize.STRING.BINARY,
        allowNull: false
      },
      createdAt: {
        allowNull: false,
        type: Sequelize.DATE,
        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP')
      },
      updatedAt: {
        allowNull: false,
        type: Sequelize.DATE,
        defaultValue: Sequelize.literal('CURRENT_TIMESTAMP')
      }
    }, options);
  },
  down: async (queryInterface, Sequelize) => {
    options.tableName = "Users";
    return queryInterface.dropTable(options);
  }
};

Install bcryptjs for password hashing:

npm install bcryptjs

13. Create User Seeds

Create a seed file for adding demo users:

npx sequelize seed:generate --name demo-user

Update the seed file in db/seeders/XXXXXXXXXXXXXX-demo-user.js:

// backend/db/seeders/XXXXXXXXXXXXXX-demo-user.js
'use strict';
const bcrypt = require('bcryptjs');

let options = {};
if (process.env.NODE_ENV === 'production') {
  options.schema = process.env.SCHEMA;  // define your schema in options object
}

module.exports = {
  up: async (queryInterface, Sequelize) => {
    options.tableName = 'Users';
    return queryInterface.bulkInsert(options, [
      {
        email: 'demo@user.io',
        username: 'Demo-lition',
        hashedPassword: bcrypt.hashSync('password')
      },
      {
        email: 'user1@user.io',
        username: 'FakeUser1',
        hashedPassword: bcrypt.hashSync('password2')
      },
      {
        email: 'user2@user.io',
        username: 'FakeUser2',
        hashedPassword: bcrypt.hashSync('password3')
      }
    ], {});
  },

  down: async (queryInterface, Sequelize) => {
    options.tableName = 'Users';
    const Op = Sequelize.Op;
    return queryInterface.bulkDelete(options, {
      username: { [Op.in]: ['Demo-lition', 'FakeUser1', 'FakeUser2'] }
    }, {});
  }
};

14. Run Migrations and Seeds

Run the migration to create the Users table:

npx dotenv sequelize db:migrate

Run the seed to add demo users:

npx dotenv sequelize db:seed:all

15. Add Authentication Middleware

Create a utils folder in the backend directory for middleware functions:

mkdir -p backend/utils

Create the auth.js file in the utils folder:

touch backend/utils/auth.js

Add the following content to auth.js:

// backend/utils/auth.js
const jwt = require('jsonwebtoken');
const { jwtConfig } = require('../config');
const { User } = require('../db/models');

const { secret, expiresIn } = jwtConfig;

// Send a JWT Cookie
const setTokenCookie = (res, user) => {
  // Create the token
  const token = jwt.sign(
    { data: user.toSafeObject() },
    secret,
    { expiresIn: parseInt(expiresIn) } // 604,800 seconds = 1 week
  );

  const isProduction = process.env.NODE_ENV === "production";

  // Set the token cookie
  res.cookie('token', token, {
    maxAge: expiresIn * 1000, // maxAge in milliseconds
    httpOnly: true,
    secure: isProduction,
    sameSite: isProduction && "Lax"
  });

  return token;
};

// Restore the user from a JWT token
const restoreUser = (req, res, next) => {
  // token parsed from cookies
  const { token } = req.cookies;
  req.user = null;

  return jwt.verify(token, secret, null, async (err, jwtPayload) => {
    if (err) {
      return next();
    }

    try {
      const { id } = jwtPayload.data;
      req.user = await User.getCurrentUserById(id);
    } catch (e) {
      res.clearCookie('token');
      return next();
    }

    if (!req.user) res.clearCookie('token');

    return next();
  });
};

// Require user to be authenticated
const requireAuth = function (req, _res, next) {
  if (req.user) return next();

  const err = new Error('Authentication required');
  err.title = 'Authentication required';
  err.errors = { message: 'Authentication required' };
  err.status = 401;
  return next(err);
};

module.exports = { setTokenCookie, restoreUser, requireAuth };

16. Set Up Server

Create a bin folder and www file to start the server:

mkdir -p backend/bin
touch backend/bin/www

Add the following content to bin/www:

#!/usr/bin/env node
// backend/bin/www

// Import environment variables
require('dotenv').config();                     // Load variables from .env file

const { port } = require('../config');

const app = require('../app');
const db = require('../db/models');

// Check the database connection before starting the app
db.sequelize
  .authenticate()                               // Test database connection
  .then(() => {
    console.log('Database connection success! Sequelize is ready to use...');

    // Start listening for connections
    app.listen(port, () => console.log(`Listening on port ${port}...`));
  })
  .catch((err) => {
    console.log('Database connection failure.');
    console.error(err);
  });

17. Configure Package.json Scripts

Update your backend/package.json file to include the following scripts:

"scripts": {
  "sequelize": "sequelize",                    // Run Sequelize CLI directly
  "sequelize-cli": "sequelize-cli",            // Alternative way to run Sequelize CLI
  "start": "per-env",                          // Runs different scripts based on NODE_ENV
  "start:development": "nodemon ./bin/www",    // Development: auto-restart on changes
  "start:production": "node ./bin/www",        // Production: regular node process
  "build": "node psql-setup-script.js"         // Used during deployment for database setup
}

18. Test the Server

Start the server and test the hello world route:

cd backend
npm start

Open your browser and navigate to http://localhost:8000/hello/world. You should see "Hello World!" displayed, and two cookies (_csrf and XSRF-TOKEN) should be set in your browser.

Review the Solution

At this point, you have successfully set up the backend of your authentication application. Let's review what you've accomplished:

• Created a well-structured project with separate backend and frontend folders
• Set up a Git repository with proper .gitignore
• Installed and configured necessary dependencies
• Set up environment variables for different environments
• Configured Sequelize for both development and production
• Created an Express application with security middleware
• Set up basic routes and CSRF protection
• Created a User model with authentication methods
• Created and ran migrations and seeds
• Set up authentication middleware with JWT
• Created a server that checks the database connection before starting
• Added a route to restore CSRF tokens

Your application is now ready for implementing API routes, which we'll cover in Phase 1.

Common Issues and Solutions

• Database Connection Errors: Make sure your database file path is correct in the .env file and you have the right permissions.
• CSRF Errors: When making non-GET requests, make sure to include the XSRF-TOKEN in the headers.
• Port Already in Use: If port 8000 is already in use, change the PORT in your .env file.
• Migration Errors: If migrations fail, check sequelize logs and ensure your database configuration is correct.
• Model Validation Errors: If seed data doesn't match model validation constraints, seeding will fail.
• JWT Issues: Make sure your JWT_SECRET is properly set in the .env file and that cookie settings match your environment.

Next Steps

Now that you have set up the backend of your application, you are ready to move on to Phase 1: API Routes, where you will create API endpoints for your application.