2.2.1 • Published 4 months ago

express-simple-pass v2.2.1

Weekly downloads
-
License
MIT
Repository
-
Last release
4 months ago

express-simple-pass

An express middleware for protecting admin UIs and dashboards with a simple password gate. Perfect for securing monitoring tools, admin panels, and internal dashboards without implementing a full authentication system

Why?

Many packages like bull board, agendash, or swagger UI provide useful admin interfaces that need to be protected from public access. However, protecting these routes usually means you need to:

  • Build custom login pages
  • Handle form submissions
  • Manage sessions/cookies
  • Set up authentication routes
  • Create template/views

express-simple-pass eliminates all of this busywork. No need to build custom login pages, handle sessions, or manage authentication flows. Just wrap your routes with the middleware, and you get a clean, functional password gate

Features

  • 🔒 Simple password protection for any express route
  • 🎨 Customizable login page with custom css support
  • 🍪 Cookie-based authentication (no session setup needed)
  • ↩️ Automatic redirect after authentication
  • 🔄 Flexible password verification
  • 📝 No need to create views or handle form submissions

Installation

npm install express-simple-pass
# or
yarn add express-simple-pass
# or
pnpm add express-simple-pass

Usage

Basic Example

import express from "express";
import { SimplePass } from "express-simple-pass";
import Agendash from "agendash";
import agenda from "./agenda-instance"; // example agenda instance
import argon2 from "argon2";

const app = express();

const simplepass = new SimplePass({
  type: "passkey",
  verify: (passkey) => argon2.verify(process.env.PASS_KEY_HASH, passkey),
  cookie: {
    secret: "superduperlongsecuresecret"
  }
});

app.use(simplepass.router());

app.use(
  "/agendash",
  (req, res, next) => simplepass.usepass(req, res, next),
  Agendash(agenda)
);

app.listen(3000);

Protecting Routes

You can use the usepass middleware to guard any route or set of routes. Ff a request hasn’t authenticated, they’ll be redirected to the authentication page

app.use(
  "/admin",
  (req, res, next) => simplepass.usepass(req, res, next),
  adminroutes
);

Configuration Options

SimplePassOptions

PropertyTypeDescriptionDefault Value
type"passkey" \| "email-password"Specifies the authentication type. Determines the input fields and verification method.required
verify(passkey: string) => boolean \| Promise<boolean>A function that takes a passkey as input and returns a boolean or a Promise that resolves to a boolean indicating whether the passkey is valid.required
rootpathstringAn optional string that specifies the root path for the middleware. It should start with a /.N/A
cookie{ secret: string \| string[] } & express.CookieOptionsAn object that contains cookie options. The secret property is required and can be a string or an array of strings. The other properties are standard Express cookie options.{ maxAge: 12 * 60 * 60 * 1000 }
cssstringAn optional string that specifies the path to a custom CSS file to style the login page.N/A
titlestringAn optional string that specifies the title of the login page.N/A
labels{ title?: string; instruction?: string; passkey_placeholder?: string; unpass?: string; unpassed?: string }Customize static text displayed on the authentication page. Defaults are provided if not specified{ title: "Authentication", instruction: "Enter the pass key to continue", passkey_placeholder: "Enter the pass key", unpass: "Unpass", unpassed: "Unpassed" }

Authentication Types

You can choose between two authentication types:

Passkey Authentication

const simplepass = new SimplePass({
  type: "passkey",
  verify: (passkey) => argon2.verify(process.env.PASS_KEY_HASH, passkey),
  cookie: {
    secret: "superduperlongsecret"
  }
});

Email + Password Authentication

const simplepass = new SimplePass({
  type: "email-password",
  verify: async (email, password) => {
    const admin = await User.findOne({
      email,
      role: "admin"
    }).orFail();

    return argon2.verify(admin.password_hash, password);
  },
  cookie: {
    secret: "superduperlongsecret"
  }
});

API

simplepass.router()

Returns an express router that serves the authentication page and handles passkey verification

simplepass.usepass(req, res, next)

Middleware to protect a route. redirects unauthenticated requests to the authentication page

SimplePass.passed(req)

Returns true if the request is authenticated

Customization

You can provide custom css for the authentication page via the css option. pass a string of css or an absolute path to a .css file:

const simplepass = new SimplePass({
  css: "C:/users/john/path/to/styles.css",
  title: "Admin Access"
});

Key css classes and ids you can target:

.container {
  /* Main form container */
}

.title {
  /* "Authentication" title */
}

.instruction {
}

form {
  /* Form element - controls layout of inputs and buttons */
}

form button {
  /* Submit button */
}

.input {
  /* Email/password/passkey input field */
}

#email,
#password,
#passkey {
  /* Additional specific styling to email, password, and passkey inputs */
}

.message.error {
  /* Error message styling */
}

.message.success {
  /* Success message styling */
}

.unpass {
  /* Unpass/logout link */
}
2.2.1

4 months ago

2.2.0

6 months ago

2.1.0

8 months ago

2.0.2

9 months ago

2.0.1

1 year ago

2.0.0

1 year ago

1.0.3

2 years ago

1.0.2

2 years ago

1.0.1

2 years ago

1.0.0

2 years ago