Nogin NPM | npm.io

(Note that the more restrictive @fortawesome/fontawesome-free share-alike terms are for the fonts themselves, not its CSS (which is under MIT); see also licenses for dev. deps..)

Nogin

A maintained and expanded fork of https://github.com/braitsch/node-login.

nogin

The project name is a portmanteau of "Node" and "login" and is pronounced "noggin" (a colloquial word for "head").

So if you want Node login, use your "nogin"!

nogin

A basic account management system built in Node.js with the following features:

New user account creation
Email verification/activation
Secure password reset via email
Ability to update / delete account
Session tracking for logged-in users
Local cookie storage for returning Users
PBKDF2-based password encryption
XSRF/CSRF protection
helmet integration for HTTP headers control
sameSite session cookies
Timing safe login check comparisons
Throrough internationalization (i18n) and fundamental accessibility (a11y)
CLI option for managing accounts
100% Cypress UI and CLI Testing Coverage
Tested on Chrome and Firefox but with a Babel/core-js Rollup routine that should allow the code to work in other browsers as well.

Improvements over `node-login`

While you can see CHANGES (or the 1.0.0 migration guide) to see all of the fixes and enhancements (including security fixes), over the excellent node-login package, the essential change has been to avoid the necessity of directly modifying source. This component has been retooled to allow it to be added as an npm dependency and provided command-line arguments which customize the appearance and behavior to a high degree—and using a config file or CLI flags rather than environmental variables.

You provide the app (through the --router argument) your Express app entry file and optionally other arguments. See the next section.

Besides these changes, there have been subsequent additions as well:

Groups, privilege, and user management
Additional security

Installation & Setup

Install Node.js (minimum version of 10.4.0) and MongoDB if you haven't already. (Note that while we have provided a generic database adapter that could in theory be used to support other databases, MongoDB is the only currently supported database.)
Install the package.

npm install nogin

Install the peerDependencies. I recommend installing install-peerdeps (npm i -g install-peerdeps); then install-peerdeps nogin will auto-install the rest.
Add a nogin.js file (see the nogin-sample.js file)
Add a db directory at your project root (and probably add it to .gitignore and .npmignore)
Use run-p (which is made available by the nogin dependency, npm-run-all) along with two of your own package.json scripts, one of which to start the mongo database, and the other to start the nogin server (note that nodemon is also provided as a dependency, so you could add that to the nogin call to watch for changes to nogin files):

{
    "scripts": {
        "mongo": "mongod --port=27017 --dbpath=db --bind_ip=127.0.0.1",
        "server": "nogin --localScripts --config nogin.js",
        "start": "run-p -r mongo server"
    }
}

(The -r flag indicates that an error in one script will lead both to exit.)

Alternatively, you can start MongoDB in its own separate shell:

mongod

...and from within the nogin directory in another terminal, start the server:

nogin --localScripts --config nogin.js

You will most likely also want to use the --router and possibly --fallback, as well as --postLoginRedirectPath / arguments. See these options for more details.

Once the script mentions it is listening (on port 3000 by default), open a browser window and navigate to: http://127.0.0.1:3000/login
(For your live site, ensure your nogin.js NL_SITE_URL is pointing to this port.)
Set yourself as rootUser in nogin.js and add groups and privileges and assign groups to users as relevant. Use dots as namespaces in privilege and group names. Note that the built-in groups nogin.loggedInUsers and nogin.guests will apply to all who are logged in or not, respectfully. The privilegs should be additive from the level of guest to logged in user to regular user to root user.
Check the privileges in your app. You can check the privileges from req.hasPrivilege(...) regardless of whether the user is logged in or a guest. You can also get the privileges from /_privs JavaScript. If you want live results, you can make a GET request to /_privs?format=json (or just import the helper nogin/hasPrivilege.js).

Steps for getting port that may block Mongo DB

MongoDB may end up with a process that interferes with starting a new instance.

On the Mac, you can follow these steps to resolve:

Get the port sudo lsof -i :27017
Then kill by kill PID with PID as the result of step 1 (or if necessary kill -2 PID).

Command line usage

To view as non-embedded HTML or SVG files (for copy-pasteable commands):

Command line summary

Server flags (without verbs)

When no verbs are added (only flags are supplied), you can see the above for a detailed description of the available flags. We group and summarize these here (all strings unless indicated). See also "Flags available regardless of "verb"" as those also apply as server flags.

Use in place of command line flags (CLI flags will take precedence)**

-c/--config - (Defaults to <cwd>/nogin.json; may also be a JS file.)
--cwd (Defaults to process.cwd().)

Required fields (no defaults)

You can also look at nogin-sample.js for how to set these values within your own nogin.js config file.

--secret
--NL_EMAIL_USER
--NL_EMAIL_PASS
--NL_EMAIL_HOST
--NL_EMAIL_FROM
--NL_SITE_URL
--fromText
--fromURL

Security

--disableXSRF (Boolean; defaults to false.)
--noHelmet (Boolean; defaults to false.)
--noHostValidation (Boolean; defaults to false.)
--RATE_LIMIT (A number defaulting to 700 for a rate limit.)
--transferLimit (A string like "50mb" to be passed to express.json() and express.urlencoded())
--csurfOptions (A string, or, in config, an object; defaults to {cookie: {signed: true, sameSite: "lax"}; note that if you are on HTTPS, it is recommended to set this to {cookie: {secure: true, signed: true, sameSite: "lax"}).
--helmetOptions (A string, or, in config, an object; defaults to {frameguard: {action: "SAMEORIGIN"}}). Note that SAMEORIGIN is required as the action to allow nogin to be used within your site's iframes.
--sessionOptions (A string, or, in config, an object; defaults to {resave: true, saveUninitialized: true} along with cookie: sessionCookieOptions, secret, and store: MongoStore.create({mongoUrl: DB_URL})
--sessionCookieOptions (A string, or, in config, an object; defaults to {sameSite: 'lax'})

Tweaks for general administration

--NS_EMAIL_TIMEOUT (number of milliseconds, defaulting to 5000)
--PORT (number, defaulting to 3000)
-a/--adapter (Defaults to "mongodb", the only current option.)
--rootUser - Users who are granted all available privileges to view and edit groups, privileges, and users

Tweaks for user-facing behavior

--requireName (Default is false.)
--countryCodes (Two-letter country codes as JSON array; defaults to codes in /app/server/modules/country-codes.json.)

Customizing locales

--localesBasePath (Defaults to app/server; use if need to redefine locale values.)

Customizing HTML

These should normally not changing, but can be changed to tweak the HTML that is rendered in emails or on the server.

--composeResetPasswordEmailView (Defaults to /app/server/views/composeResetPasswordEmail.js)
--composeActivationEmailView (Defaults to /app/server/views/composeActivationEmail.js)
--injectHTML (No extra HTML is injected by default)
--favicon (String path; defaults to blank.)

Customizing stylesheets

--stylesheet (String path; defaults to no extra stylesheets being used.)
--noBuiltinStylesheets (Boolean, defaults to false)

Customizing JavaScript

--localScripts (Boolean, defaults to false)
--userJS (None by default)
--userJSModule (None by default)

These should primarily only be used with testing:

--useESM (Boolean, defaults to false.)
--noPolyfill (Boolean, defaults to false.)

Customizing routes

This is for changing the names or behavior of existing routes. See "Adding routes" for supporting additional routes.

--postLoginRedirectPath (Path/URL to which to redirect after login; defaults to home (/home) (or locale equivalent), but you should probably set it so that it redirects instead to your root (/).
--customRoute (Multiple strings in format <locale>=<route>=<path>)
--crossDomainJSRedirects (Boolean, defaults to false.)

Adding routes

-s/--SERVE_COVERAGE (Boolean; defaults to false.)
--staticDir (One or more string paths)
--middleware (One or more middleware to be required)
--fallback - If you need a default static file server and not just specific paths, you can add your own file such as follows, adding any desired headers, etc.:

import express from 'express';

/**
 * @param {import('express').Request} req
 * @param {import('express').Response} res
 * @param {import('express').NextFunction} next
 * @returns {void}
 */
export default function fallback (req, res, next) {
  express.static('.', {
    setHeaders (resp /* , path, stat */) {
      resp.set({
        'Content-Security-Policy': `object-src 'none';`
      });
    }
  })(req, res, next);
}

--router - This is where your own (Express) app should be. Note: The following paths should not be set as they are reserved by nogin:
- POST: /login, /logout, /home, /signup, /accessAPI, /reset-password, /lost-password, /delete, /reset
- GET: /login, /logout, /home, /signup, /accessAPI, /reset-password, /activation, /users, /coverage, /groups, /privileges, _lang, _privs

/**
 * @param {import('express').Application} app
 * @param {{userJS: string}} opts
 * @returns {void}
 */
export default function router (app, opts) {
  // Grab your `nogin.js` options here as needed
  console.log('Started with options:', {
    ...opts,
    secret: '<HIDDEN>',
    NL_EMAIL_PASS: '<HIDDEN>'
  });

  app.get('/', (req, _res, next) => {
    // To see your user session info (and determine privileges), you can get
    //   them from `req.sesssion?.user`:
    console.log('req.session', {
      ...req.session?.user,
      _id: '<some unique ID>',
      name: 'Brett Zamir',
      email: '<the user email address>',
      user: 'brettz9',
      pass: '<the password hash>',
      country: 'US',
      activationCode: '<activation code hash>',
      activated: true,
      passVer: 1,
      date: 1725865509592,
      cookie: '<cookie hash>',
      ip: '::ffff:127.0.0.1'
    });

    // We just use express' approach to point `/` to the path `/index.html`.
    req.url = '/index.html';

    // Or instead add optional config to conditionally point to any
    //    Cypress-instrumented entry file:
    // req.url = instrumented
    //   ? '/instrumented/index.html'
    //   : '/index.html';

    // Or point the user to the login page if they are not yet logged in
    // req.url = req.session?.user
    //   ? '/index.html'
    //   : '/login';
    next();
  });
}

Used mainly for internal testing of `nogin`

-d/--JS_DIR - (Defaults to /app/public; used for pointing to instrumented path.)

Verbs

One can also add a verb to nogin (e.g., nogin read) which performs a different behavior from creating a server.

help - Use with one of the verbs below to get help for that command
read/view - View user account(s)
update - Update user account(s)
add/create - Create new user account(s)
remove/delete - Remove user account(s)
listIndexes - List indexes of the nogin database

Flags available regardless of "verb" (besides `help`)

Defaults in parentheses:

--loggerLocale ("en-US")
--noLogging (false)
-n/--DB_NAME ("nogin")
-t/--DB_HOST ("127.0.0.1")
-p/--DB_PORT (27017)
-u/--DB_USER
-x/--DB_PASS

Flags reused among verbs "read"/"view", "update", "add"/"create", "remove"/"delete".

These are are all multiple (one to be added for each user being viewed/added/etc.).

Unless notes, all types are strings.

--user (as the default option, the flag --user can be omitted)
--name
--email
--country (Two digit recognized country code)
--pass
--passVer (A number indicating the current schema version; should always be set to "1" currently.)
--date (A number timestamp for record creation date)
--activated (A boolean)

These are shared but will primarily only be of interest in internal nogin testing:

--activationCode
--unactivatedEmail
--activationRequestDate (A number timestamp)

Flags for specific verbs

`add`/`create`

Note that the CLI API for the add and update verbs does not currently perform all validation that the UI does, so you will need to have some familiarity with nogin internals to be sure to include all required fields.

--userFile - Path to JSON file containing data to populate
--cwd - Used with userFile

`remove`/`delete`

--all - Boolean to indicate desire to remove all user records!

Programmatic docs

pnpm i (local install to get devDeps)
pnpm build-docs
Open docs/jsdoc/index.html

Contributing

Questions and suggestions for improvement are welcome.

For developing docs, see DEVELOPING.

To-dos

Review csurf and usage
Recheck coverage tests
See about removing @fortawesome/fontawesome-free dependency (and if so, rebuild license badges and remove note above about its license)
Login page
1. Provide option for integration within an existing page to avoid need for separate login page (Ajax)
  1. Adapt server-side redirect functionality to give Ajax feedback to client so it could instead handle forwarding with a hash.
  2. Consider possibility of an option to merge with signup page
2. Multiple simultaneously-shown login choices (e.g., to use version control or Cloud Storage and a database managing users and privileges)?
3. WebSockets with express-ws and jquery-form?
4. Optional captcha (see signup below)
Signup/Home pages
1. Allow Multiple choices
2. Allow adding to "Set up new account" fields (based on a schema?) (to be injected into app/server/views/account.js) to be passed to the server (app/server/routeList.js) and saved in the database along with other fields (check the user-supplied don't overwrite built-ins) and shown on home (also built by account.js) (unless hidden?); not trusting the client-side values of course (could parse server-side-supplied schema for expected types); use json-editor?
  1. Plugin system to allow asking for and saving additional data per user. May optionally be able to reject submission, but should instead use an authentication strategy plugin, if it is more fundamental to authentication (since this should generally be safely additive).
  2. Concept of SharedStorage for grabbing local user data (or on a URL) for populating site profiles/preferences (under control of user, so they can manage their data in one place, and let sites update their own copy (or directly utilize the local copy) when online and checking)
3. Captchas (svg-captcha (doesn't use easily breakable SVG text, and could convert to image))
  1. Plugin system for captchas, while potentially allowing saving to and retrieving from database (e.g., for admin-added list of Q&A's), need not be aware of any other co-submitted data like username, password, etc. Unlike "set up new account" plugins, wouldn't need access to user database, but can of course have potential to reject submission.
Authentication strategies
1. Passkeys
2. See about passport-next integration
  1. WebSockets with passport?
  2. Supporting user choice of authentication method
    1. Different strategies could optionally offer different schemas for:
      1. User (Registration and edit user)
      2. Preferences (Tied to user but unlike general content, may possibly of interest across site/application such as desire for dark mode, and unlike most content, would be private and not likely of interest in content queries)
      3. Login (e.g., to auto-add field for captcha, or CryptoKey and CryptoKeyPair) generation/selection.
      4. Privileges, Privilege Groups, User Groups
3. BrowserID to use with a server-side validation
  1. See https://github.com/jaredhanson/passport-browserid.
  2. Would presumably need to revive as a browser add-on
  3. Browser add-on could also expose global locally stored preferences
4. Strategy idea: Check host of email domain and insist on .name at a reliable host which promises not to give out domains under a minimum fee (as a deterrent for spamming and encouragement for mail address portability); would need to find hosts willing to commit to such a policy.
5. Add passwordless option
  1. See http://www.passportjs.org/packages/passport-passwordless/.
Users page
1. Ajax pagination
2. Privileges
  1. Role-based privileges (esp. for reset/delete!) with admin screens
  2. Hierarchical groups and roles?
  3. Multiple group membership allowing multiple roles per group, including user-customizable roles in addition to built-in ones such as the "login" privilege; roles per user (without group)
    1. Make a simple version of groups where groups are auto-created that map to privileges (e.g., a login group), so can easily add a user to a login group rather than needing to first create the group and add the privilege to that group (these could be the built-in groups, along with a few combined ones like visitor/user/admin/superadmin)
  4. Anticipate privileges that come automatically based on events (e.g., as with StackExchange)
  5. Atomic privileges (e.g., view-users as well as more encompassing view privilege)
  6. IP addressed-based privileges (or exclusions)
  7. Expiring privileges (or tied into payment subscription or some other event, auto-renewing or not)
  8. See to-dos in code for methods needing these!
    1. Restore reset from GET page to POST on the user (admin) page.
  9. Use within authentication
  10. Tie into PaymentRequest so privilege groups can be tied to payments or subscriptions
    1. npm package for processing/submitting credit info?
    2. might restrict access to whole site (though more likely just parts) until payment made
  11. Need to remember to handle case of users added before privilege changes
  12. Update docs for any privilege additions/config
Other pages
1. Method to auto-create accessibility-friendly navigation bar, including login (root), logout, home, signup, and users (the special pages, 'activation', 'lostPassword', 'resetPassword', 'delete', 'reset', 'coverage', should not need to be added). Also add breadcrumbs and <link rel=next/prev>.

Lower priority to-dos

Change POST APIs to GET where expected.
Add to /accessAPI (GET) to explain API and also possibly consolidate to one page?
"blockedIPs" pseudo-group to which one can add IPs (as distinct from "nogin.guests")
Add types like number, string, and array (of strings) privileges?
Add "local" boolean flag to privileges (if delivered by default in JavaScript)?
Add /user/<username> (GET) script for admins and others
Add /group/<groupname> (GET) script for admins and others
Could make groups hierarchical (multiple? inheritance privileges)
Allow variant of localScripts which uses CDN but generates fallback
Option to email forgotten username (as a workaround, the reset password email will send this currently, but not if adding an option to disable the current uniqueEmails mode). Alternatively, could allow login by email. Don't want to show username for email in UI though for privacy reasons (more serious than just detecting that the user has an account, this would detect what their account was).
We should already be checking the important items like avoiding existing names, but we should be rejecting bad values of lesser importance on the server-side as we do on the client-side (e.g., non-emails, too short of passwords, etc.)
Review client-side validation for any other opportunities (e.g., for any missing required fields, etc.)
Switch from jsdom to dominum (once latter may be capable), as latter is lighter-weight and we don't need all that jsdom offers; add tests within jamilih for the integration
See about minor to-dos in code along the way
Make email activation (and email) optional (would mitigate some problems with email detection when current enforcement of unique emails (proposed uniqueEmails: true) is enabled as users concerned with privacy could at least avoid an email that could be sniffed)?
Make server config to make error messages of potential concern to privacy optional (avoid allowing testing presence of an email in the system by feedback from lost password (detecting existent vs. non-existent email)
1. Only complete solution is if also allowing signup/update to an existing email (otherwise those pages could be used for detection instead).
  1. We could also make emails optional (beyond activation?)
  2. While we could make the errors less specific, this can still effectively be sniffed by signing up for different accounts and seeing if they result in some error (they likely shouldn't otherwise)
  3. In allowing disabling of uniqueEmails, require username be provided so will only send reset password for that account
2. Info: Optional since many sites might wish to enforce unique emails or identity-by-email, or may simply wish to give users full feedback about whether a lost password email was successfully sent or not.
3. Info: Note that login would always allow detecting existent vs. non-existent user names (this is just for email detection)
4. More validation from CLI, e.g., adding an option or default to report if an email is already in use