Basic Authentication for Vantage.js

Common errors

• Access denied: too many login attempts.

  cause The user failed to authenticate within the configured 'retry' limit, leading to a session kick-out.
  fix Check the username and password for correctness. If locked out, wait for the 'unlockTime' duration to expire, or restart the Vantage session if the lockout is session-bound. Review the 'retry' and 'unlockTime' options in your configuration for appropriate values.

Warnings

• breaking This package and its parent framework, Vantage.js, are no longer actively maintained. Using them in modern Node.js environments (v12+) may lead to compatibility issues, unpatched security vulnerabilities, or unexpected behavior. It is strongly advised not to use this package for new projects or in production environments.
  Fix: Migrate to a currently maintained CLI framework and authentication solution, such as Commander.js or Oclif with appropriate authentication middleware.
• gotcha This package is part of the older Vantage.js ecosystem, primarily designed for CommonJS environments and Node.js versions up to 0.x / 1.x. Modern Node.js projects (ESM-first, recent Node versions) will encounter compatibility issues with `require()` and may prefer more modern authentication solutions.
  Fix: If absolutely necessary to use, ensure your project uses CommonJS modules. For new development, consider alternative, actively maintained CLI frameworks.
• gotcha Direct `require("vantage-auth-basic")` is often unnecessary. Vantage.js itself integrates this authentication method, allowing users to simply pass the string "basic" to `vantage.auth()`. Relying on the string is generally preferred for consistency with the framework.
  Fix: Use `vantage.auth("basic", options);` instead of explicitly requiring the module if integrating directly into a Vantage instance.
• gotcha User passwords are configured directly in memory via the `users` option. For production environments, consider implementing a more secure password storage and verification mechanism (e.g., hashing passwords and verifying against a database) rather than hardcoded credentials. This package does not provide robust password management or hashing itself.
  Fix: For production, pre-hash passwords before storing them in the `users` array and implement custom verification logic within Vantage, or use a separate authentication system.

Install

• npm install vantage-auth-basic npm
• yarn add vantage-auth-basic yarn
• pnpm add vantage-auth-basic pnpm

Imports

• basicAuth
  wrong:

  import basicAuth from 'vantage-auth-basic';

  correct:

  var basicAuth = require("vantage-auth-basic");

  This package is primarily for CommonJS environments due to its age and the `vantage.js` ecosystem. ESM imports are not supported.
• "basic" string identifier

  vantage.auth("basic", options);

  This is the recommended and most common way to integrate this authentication, as it's often built into Vantage.js itself and doesn't require an explicit `require()` call.

Quickstart

This quickstart demonstrates how to configure basic authentication with `vantage-auth-basic` for a Vantage.js instance, defining users, retry policies, and an example command that accesses the authenticated user's information.

var users = [
	{ user: "admin", pass: "4k#842jx!%s" },
	{ user: "user", pass: "Unicorn11" }
];

var vantage = require("vantage")();

vantage.auth("basic", {
	"users": users,
  "retry": 3,
  "retryTime": 500,
  "deny": 1,
  "unlockTime": 3000
});

vantage
  .command("whoami", "Outputs logged in user.")
  .action(function(args, cb){
  	console.log("You are " + this.user);
  	cb();
  });

// To make the Vantage instance active, you would typically call .listen() or similar.
// For example, vantage.listen(4000) or run it from the command line if installed globally.
// This snippet primarily demonstrates the authentication setup.