hoplitejs

Easy to Implement Authorization and Authentication Library

Usage no npm install needed!

<script type="module">
  import hoplitejs from 'https://cdn.skypack.dev/hoplitejs';
</script>

README

Welcome to hopLiteJS! hopLiteJS is a developer friendly, lightweight middleware library for Node.js. hopLiteJS can be imported and used in any Express-based web application. It has multiple developer interfaces for customizing authentication and authorization. With hopLiteJS, developers no longer have to dread authentication, authorization and hashing.

COOKIES The developer is able to add custom cookies by first utilizing the createRulesetCookie method. This method can be used alongside any other ruleset-creating methods in hopLiteJS (eg. createRulesetCookieJWT). The parameters of the method are cookies (object) and optional cookieOptions (object). The developer is required to first create the data for these parameters. Each key-value pair in the cookies object are individual cookies where the keys are cookie names and values are cookie data. Each key-value pair in the optional cookie options object consists optional security measures such as domain, encode, etc. (shown below). If the option parameter is not inputted, default options will be applied.

Default Options for Cookies are as follows:

const hopLiteJSDefaultOptions = {
  httpOnly: true,
  secure: true,
  maxAge: 1209600000,
  sameSite: "lax"
};

REMEMBER: These defaults are applied to every cookie unless the user provides options for their cookies.

Cookie:

Options: domain (string), encode (function), expires (date), maxAge (number), httponly (boolean), path (string), secure (boolean), signed (boolean), sameSite (boolean or string)

Example Code:

The developer may create an object to store unique cookie options:

const cookieOptions = {
  secure: true,
  httponly: true,
  signed: true,
  expires: new Date(Date.now() + 900000),
  domain: 'hopliteJS.com',
  path: '/hopliteJS'
}

Create an object to store cookie name and value:

const cookies = {
  cookieName1: 'cookie value 1',
  cookieName2: 'cookie value 2',
  foo: 'bar'
}

Invoke createRulesetCookie with cookie object and optional cookie option object const cookieRuleset = hoplite.createRulesetCookie(cookies [, cookieOptions])

COOKIE-JWTs The developer is able to add custom JWTs to cookies by first utilizing the createRulesetCookieJWT method. This method can be used alongside any other ruleset-creating methods in hopLiteJS (eg. createRulesetCookie). This method takes in a CookieJWTList parameter, where a developer defines the names of the cookies, their secrets, and options. Each key-value pair in the CookieJWTList object are individual cookies where the keys are cookie names and their values are objects with a secret key, and the optional cookie options object consisting of optional security measures such as domain, encode, etc. (shown below). If the option parameter is not inputted, hopLiteJS default options will be applied.

const cookieJWTList = {
  cookieName1: {
    secret: "kljashdflkjshadf",
    options: {
      httpOnly: true,
    }
  },
  cookieName2: {
    secret: "hello",
  }
}

const myPayload = {
  cookieName1: h3bv3h3hg3g,
  cookieName2: 'L2'
}

OPTIONS: domain (string), encode (function), expires (date), maxAge (number), httponly (boolean), path (string), secure (boolean), signed (boolean), sameSite (boolean or string)

Example Code:

Create a secret string:

const mySecret = 'password123';

Create a payload object

const myPayload = {
  cookieName1: h3bv3h3hg3g,
  cookieName2: 'L2'
}

Create an optional options object:

const cookieOptions = {
  secure: true,
  httponly: true,
  signed: true,
  expires: new Date(Date.now() + 400000),
  domain: 'hopliteIsAwesome.com',
  path: '/hopliteAwesome'
}

Create a cookie-JWT object:

const cookieJWTObj = {
  token1 = JWT
}

Invoke createRuleset method with cookieJWTObj as an argument: const cookieJWTRuleset = hoplite.createRulesetCookieJWT(cookieJWTObject)

USING THE GLOBAL RULESET CREATOR:

After the developer decides which security methods (eg. cookie, cookieJWT, etc.) to use, they must invoke the createRuleset method with each of these creation methods as arguments. The first argument must be a message which will be used as the res.send at the end of the middleware.

Example Code:

Create a message which will be used as the res.send:

const message = 'Cookie and Cookie-JWTs have been set successfully'

createRuleset with parameters:

hoplite.createRuleset(message, ...args)

Invoke createRuleset with appropriate arguments:

const ruleset = hoplite.createRuleset(message, cookieRuleset, cookieJWTRuleset)

AUTHENTICATION: After creating the global ruleset, the developer is able to authenticate their clients by invoking the authenticate method. The parameters are the global ruleset, payload(represents list of cookies, OR JWT payload) and the response object, provided by express.

Example Code:

app.post('/authn', async (req, res) => {
  const result = await authenticate(ruleset, payload, res); 
})

AUTHORIZATION: After creating the global ruleset, defining unique payloads, and authenticating, the developer is able to authorize their clients by invoking the authorization middleware method. The parameters are the global ruleset, and the unique key-value pairs required to access the next resource.

Example:

const requiredClaims = {
  role: "admin",
  bonusKey: "Only I may access this resource"
}

Example Code:
app.post('/authz', authorize(myRuleset, requiredClaims), (req, res) => {
  res.status(200).send("Authorization Successful");
})

HASHING:

A. Hashing using bcrypt The developer is required to provide inputPassword (string) and cost (number) as parameters. The inputPassword refers to the password input by the client and cost refers to the number of salt rounds in bcrypt. By default the cost is set to 10 rounds. The output of this function is a hashed string.

Example Code:

const inputPassword = 'password123';
const cost = 10;

const hashedPassword = hoplite.bcryptHash(inputPassword, cost);
console.log(hashedPassword) //prints hashed string

B. Comparing input password with hashed string using bcrypt The developer is required to provide inputPassword (string) and hashedPassword (string) as parameters. The inputPassword refers to the password input by the client and hashedPassword refers to the hashed password that is stored. A developer can store the hashed password in a database and query for it using the id that is associated with it. The output of this function is a boolean.

Example Code:

const inputPassword = 'password123';
const hashedPassword = 'Hashed Database Password';

const samePassword = hoplite.bcryptCompare(inputPassword, hashedPassword);
console.log(samePassword) //prints true or false

C. Hashing using argon2 The developer is required to provide inputPassword (string) as a parameter. The inputPassword refers to the password input by the client. The output of this function is a hashed string.

Example Code:

const inputPassword = 'password123';
const hashedPassword = hoplite.argonHash(inputPassword);
console.log(hashedPassword) //prints hashed string

D. Comparing input password with hashed string using argon2 The developer is required to provide inputPassword (string) and hashedPassword (string) as parameters. The inputPassword refers to the password input by the client and hashedPassword refers to the hashed password that is stored. A developer can store the hashed password in a database and query for it using the id that is associated with it. The output of this function is a boolean.

Example Code:

const inputPassword = 'qwerty123';
const hashedPassword = 'Hashed Database Password';

const samePassword  = hoplite.argonCompare(inputPassword, hashedPassword);
console.log(samePassword) //prints true or false

CURRENTLY DEVELOPING: -oAuth -user privilege