This is the official JavaScript implementation of SuperGenPass. It provides the code used by the bookmarklet and mobile version of SuperGenPass to generate passwords. If you are building or have built your own JavaScript-based application for SuperGenPass, please consider using this library.
npm install supergenpass-libvar sgp = require('supergenpass-lib');
// A string containing the user's master password.
var masterPassword = 'master-password';
// A URI or hostname of the site being visited.
var URI = 'http://www.example.com/page.html';
// A callback function to accept the generated password.
var callback = function (password) {/* code */};
// Generate the password.
sgp.generate(masterPassword, URI, {/* options */}, callback);Note: Version 3.0.0 introduces the generate method instead of making
this function the root export. This change was made to align with
ES6 exports.
As shown above, supergenpass-lib optionally accepts a hash map of options.
- Default
10 - Expects
Number
Minimum number of rounds to hash the input. (Hashing may continue past the minimum until the password validation rules are satisfied.)
- Default
10 - Expects
Number
Length of the generated password. Valid lengths are integers between 4 and 24
inclusive. Note that 23- and 24-character MD5-based passwords provide no
additional entropy. (The value for those characters will always be A.)
- Default
'md5' - Expects
StringorFunction
A string specifying the requested hash function. The only supported string
values are 'md5' or 'sha512'.
Alternatively, you can supply your own hash function. This hash function must accept a string value and return a string value. Returned hashes should be at least 24 characters and will be subject to SGP’s password validation rules.
- Default
false - Expects
Boolean
A boolean value directing whether or not to use the url as is without validation or changes.
- Default
true - Expects
Boolean
A boolean value directing whether or not to remove subdomains from the hostname before generating the password.
- Default
'' - Expects
String
A secret password to be appended to the master password before generating the password. This option is provided for convenience, as the same output can be produced by manually concatenating the master and secret passwords.
By default, supergenpass-lib isolates the domain name (e.g., example.com)
from the hostname by removing all subdomains. This ensures that the same
password is generated at example.com, www.example.com, and
login.example.com. It additionally uses a hardcoded list of country-code and
special-purpose TLDs to produce different passwords across sites registered
there. While this list is no doubt incomplete and out-of-date, it remains
static to maintain backwards compatibility. You can disable subdomain removal
in the options.
To help provide user feedback about the exact hostname used to generate the
password, supergenpass-lib provides a hostname method that can be used
separately.
// Isolate a domain name from a URL using SuperGenPass's rules.
var hostname = supergenpass.hostname('http://login.example.com/doLogin.htm', {
removeSubdomains: true // default = true
});SuperGenPass is a very simple password hashing scheme. At its essence, it takes a master password and a hostname and concatenates them together:
masterpassword:example.com
It uses this as the input for the user's preferred hash function. It guarantees hashing at least ten times to protect against rainbow tables. The hash is then cut to the user's preferred password length.
For more detail, please see the (well-commented and concise) source code.
Tests require Node >=4.0. Run npm test.
Hash functions are provided by crypto-js. All original code is released under the GPLv2.
Development of this library was helped tremendously by Denis Sokolov, author of the SuperGenPass Chrome extension.