@iambpn/auths NPM

Auths

Authentication System inspired by Auth0. It is a plug and play authentication and authorization system with in express application. Auths has support for 3 different type of database mysql2, sqlite and postgres to store user credentials.

Setup auths with 3 simple steps:

Install auths in to your existing express application
Setup required environment variable
Link your express app to auths

Documentation:

Getting Started: setting up your project with sqlite db

# File: .env
AUTHS_DB_DRIVER=sqlite
AUTHS_DB_URI=""; # sqlite uri is only supported
AUTHS_SECRET=""; # secret to use while issuing jwt token / other token
AUTHS_JWT_EXPIRATION_TIME=string; # JWT token expiration time
AUTHS_LOGIN_TOKEN_EXPIRATION_TIME=string; # Login token expiration time
AUTHS_HASH_SALT_ROUNDS=string; # number of rounds to use while hashing password

// File: main.ts

// Load Env
dotenv.config();

// initiate express server
const app = express();

// configure global middlewares
app.use(express.json());
...

// Initiate auth package
authsInit(app, path.join(__dirname, "permission.json"));

Since seeding permission can be tedious, you can create a permission.json file in your project root and seed it automatically

// File: permission.json
{
  "isSeeded": false, // boolean: "false" if you want to run the seed. This value will be automatically set to "true" after the first seed

  // default permissions
  "permission": [
    { "name": "create", "slug": "create" },
    ...
  ]
}

Accessing auths dashboard:
<url>/auths & default username and password: admin@admin.com and admin123
Example: http://localhost:8008/auths
Auths Seeds:
By Default, on first boot-up auths will seed the following
- New user with default superAdmin_admin role
- New superAdmin_admin role
  Default superAdmin_admin role has no permission and can do anything inside of auths dashboard but cannot access the client side resource. To access client side resource, Admin needs to manually add required permissions to default superAdmin_admin role. Only Users with default super admin role can access and use auths dashboard.
  Note: Default super admin is identified by its slug superAdmin__default so default super admin is not deletable.

Deep Dive

Workflow diagram of Sign-up
Workflow diagram of Login
Workflow diagram of forgot password and reset password

List of ENV Variables

/*
  Secret key to encrypt auths jwt token.
*/
AUTHS_SECRET: string;

/*
  Auths Jwt token expiry time in Seconds
*/
AUTHS_JWT_EXPIRATION_TIME?: number;

/*
  Auths login token expiration time in MilliSeconds
*/
AUTHS_LOGIN_TOKEN_EXPIRATION_TIME?: number;

/*
  Number of salt rounds to use when encrypting password
*/
AUTHS_HASH_SALT_ROUNDS?: number;

/*
  Specifying Which Database Driver to Use

  Possible values:
    - 'better-sqlite'
    - 'mysql2'
    - 'node-postgres'
*/
AUTHS_DB_DRIVER: string;

/*
  Required if AUTHS_DB_DRIVER is 'better-sqlite'
*/
AUTHS_DB_URI?: string;

/*
  Required if AUTHS_DB_DRIVER is 'mysql2' or 'node-postgres'
*/
AUTHS_DB_HOST?: string;

/*
  Required if AUTHS_DB_DRIVER is 'mysql2' or 'node-postgres'
*/
AUTHS_DB_PORT?: number;

/*
  Required if AUTHS_DB_DRIVER is 'mysql2' or 'node-postgres'
*/
AUTHS_DB_USERNAME?: string;

/*
  Required if AUTHS_DB_DRIVER is 'mysql2' or 'node-postgres'
*/
AUTHS_DB_PASSWORD?: string;

/*
  Required if AUTHS_DB_DRIVER is 'mysql2' or 'node-postgres'
*/
AUTHS_DB_NAME?: string;

API References

Consumable REST APIs

Here are the list of exposed apis users can consume.

### User Login
GET {URL}/auths/login HTTP/1.1
Content-Type: application/json

{
  email: string;
  password: string;
}

### User Reset Password
GET {URL}/auths/resetPassword HTTP/1.1
Content-Type: application/json

{
  email: string;
  token: string;
  newPassword: string;
}

### Get Current User
GET {URL}/auths/currentUser HTTP/1.1

Exported Functions

Here are the list of function that can be used to interact with auths system from backend directly.

function authsInit(app: Express, permissionFileUrl?: string): void;

function signup(
  email: string,
  password: string,
  roleSlug: string,
  others?: Record<string, any>
): Promise<{
  email: string;
  uuid: string;
  role: string;
}>;

function loginFn(
  token: string,
  email: string,
  additionalPayload?: Record<string, any> // additional payload to store in jwt
): Promise<{
  email: string;
  uuid: string;
  jwtToken: string;
}>;

function validateUser(email: string): Promise<{
  uuid: string;
  email: string;
  others: string | null;
  createdAt: Date;
  updatedAt: Date;
}>;

function initiateForgotPasswordFn(
  email: string,
  returnToken?: string | undefined
): Promise<{
  email: string;
  token: string;
  expires_at: Date;
}>;

Middlewares

Here are the list of middlewares that can be used inside of your express application.

/**
 * Check if user is authenticated via bearer token.
 */
function isAuthenticated(req: Request, res: Response, next: NextFunction): void;

/**
 * Check if user has required permission to access resources
 */
function requiredPermissions(permission_slugs: string[]): (req: Request, res: Response, next: NextFunction) => void;

Types

Here are the list of exposed Typescript Types

type AuthsRequestUser<T = Record<string, any>>

Limitation:

Currently only better-sqlite3, node-postgres and mysql2 db drivers are only supported.

Changelog

1.0.0
- Auths Released
- Added Sqlite database is supported
- Added Authentication and Authorization support
2.0.0:
- Adding support for mysql2 and postgres database
- Added User management system
- Added more env variables
- Breaking: Auths function is now async
- Breaking: AUTHS_DB_DRIVER env variable is now required.