From 0e90baeb6646c45594b423f7ad3beee8def3a59b Mon Sep 17 00:00:00 2001 From: Torsten Rehn Date: Sat, 24 Oct 2015 13:23:54 +0200 Subject: [PATCH] add rudimentary password generator and strength meter closes #32 --- bower-strip.sh | 11 + .../templates/secrets/secret_addedit.html | 52 ++++ .../secrets/secret_addedit_password.html | 8 +- .../bundled/password-generator/.bower.json | 33 +++ .../bundled/password-generator/.travis.yml | 10 + .../static/bundled/password-generator/LICENSE | 7 + .../bundled/password-generator/README.md | 176 +++++++++++++ .../bundled/password-generator/bower.json | 23 ++ .../dist/password-generator.min.js | 6 + .../bundled/password-generator/package.json | 57 +++++ .../static/bundled/zxcvbn/.bower.json | 45 ++++ .../static/bundled/zxcvbn/LICENSE.txt | 20 ++ src/teamvault/static/bundled/zxcvbn/README.md | 234 ++++++++++++++++++ .../static/bundled/zxcvbn/bower.json | 33 +++ .../static/bundled/zxcvbn/dist/zxcvbn.js | 22 ++ .../static/bundled/zxcvbn/dist/zxcvbn.js.map | 23 ++ 16 files changed, 759 insertions(+), 1 deletion(-) create mode 100644 src/teamvault/static/bundled/password-generator/.bower.json create mode 100644 src/teamvault/static/bundled/password-generator/.travis.yml create mode 100644 src/teamvault/static/bundled/password-generator/LICENSE create mode 100644 src/teamvault/static/bundled/password-generator/README.md create mode 100644 src/teamvault/static/bundled/password-generator/bower.json create mode 100644 src/teamvault/static/bundled/password-generator/dist/password-generator.min.js create mode 100644 src/teamvault/static/bundled/password-generator/package.json create mode 100644 src/teamvault/static/bundled/zxcvbn/.bower.json create mode 100644 src/teamvault/static/bundled/zxcvbn/LICENSE.txt create mode 100644 src/teamvault/static/bundled/zxcvbn/README.md create mode 100644 src/teamvault/static/bundled/zxcvbn/bower.json create mode 100644 src/teamvault/static/bundled/zxcvbn/dist/zxcvbn.js create mode 100644 src/teamvault/static/bundled/zxcvbn/dist/zxcvbn.js.map diff --git a/bower-strip.sh b/bower-strip.sh index ff36f6f5..e3fd5167 100755 --- a/bower-strip.sh +++ b/bower-strip.sh @@ -37,6 +37,17 @@ rm -rvf ${BUNDLED_DIR}/font-awesome/.npmignore # jquery rm -rvf ${BUNDLED_DIR}/jquery/src +# password-generator +rm -rvf ${BUNDLED_DIR}/password-generator/*.html +rm -rvf ${BUNDLED_DIR}/password-generator/*.js +rm -rvf ${BUNDLED_DIR}/password-generator/*.yml +rm -rvf ${BUNDLED_DIR}/password-generator/.gitignore +rm -rvf ${BUNDLED_DIR}/password-generator/bin +rm -rvf ${BUNDLED_DIR}/password-generator/dist/password-generator.js +rm -rvf ${BUNDLED_DIR}/password-generator/lib +rm -rvf ${BUNDLED_DIR}/password-generator/Makefile +rm -rvf ${BUNDLED_DIR}/password-generator/test + # select2 rm -rvf ${BUNDLED_DIR}/select2/.gitignore rm -rvf ${BUNDLED_DIR}/select2/component.json diff --git a/src/teamvault/apps/secrets/templates/secrets/secret_addedit.html b/src/teamvault/apps/secrets/templates/secrets/secret_addedit.html index a52028ce..9c369cdc 100644 --- a/src/teamvault/apps/secrets/templates/secrets/secret_addedit.html +++ b/src/teamvault/apps/secrets/templates/secrets/secret_addedit.html @@ -16,7 +16,9 @@ {% endblock %} {% block "js" %} + + {% endblock %} {% block "content" %} @@ -188,7 +190,57 @@

$(".access-details").is(':visible')? $("#access_toggle_icon").html('') : $("#access_toggle_icon").html(''); $(".access-details").slideToggle(); }); +String.prototype.repeat = function(times) { + return (new Array(times + 1)).join(this); +}; +function ratePassword () { + var score = zxcvbn($("#id_password").val(), user_inputs=[]).score + 1; + var color = "text-warning"; + if (!$("#id_password").val()) { + color = "text-muted"; + score = 0; + } + else if (score <= 2) { + color = "text-danger"; + } + else if (score == 5) { + color = "text-success"; + } + var filled_star = ""; + var hollow_star = ""; + $("#id_password_strength").html(filled_star.repeat(score) + hollow_star.repeat(5 - score)); +} +$("#id_password").keyup(function() { + ratePassword(); + $("#id_password").generated = false; + setTimeout( + function() { + if (!$("#id_password").generated) { + $("#id_password").prop("type", "password"); + } + }, + 2000 + ); +}); +$("#id_pwgen").focusout(function() { + setTimeout( + function() { + if (!$('#id_password').is(':focus')) { + $("#id_password").prop("type", "password"); + } + }, + 1000 + ); +}); +$("#id_pwgen").click(function() { + $("#id_password").val(generatePassword(32, false)); + ratePassword(); + $("#id_password").prop("type", "text"); + $("#id_password").generated = true; +}); $(document).ready(function() { + $('[data-toggle="popover"]').popover(); + $("#id_password").generated = false; $("#id_allowed_groups").select2({ tags: true, tokenSeparators: [",", " "], diff --git a/src/teamvault/apps/secrets/templates/secrets/secret_addedit_password.html b/src/teamvault/apps/secrets/templates/secrets/secret_addedit_password.html index a1e6377a..f26cb887 100644 --- a/src/teamvault/apps/secrets/templates/secrets/secret_addedit_password.html +++ b/src/teamvault/apps/secrets/templates/secrets/secret_addedit_password.html @@ -6,7 +6,13 @@
- +
+ + + + + +

  {% trans "This field will be stored securely." %}

diff --git a/src/teamvault/static/bundled/password-generator/.bower.json b/src/teamvault/static/bundled/password-generator/.bower.json new file mode 100644 index 00000000..193edd11 --- /dev/null +++ b/src/teamvault/static/bundled/password-generator/.bower.json @@ -0,0 +1,33 @@ +{ + "name": "password-generator", + "description": "Memorable password generator. For the command line, Node.js and browsers.", + "version": "2.0.2", + "main": "lib/password-generator.js", + "license": "MIT", + "keywords": [ + "password", + "generator", + "pass", + "random", + "browser", + "crypto", + "security" + ], + "authors": [ + "Bermi Ferrer " + ], + "repository": { + "type": "git", + "url": "git@github.com:bermi/password-generator.git" + }, + "homepage": "https://github.com/bermi/password-generator", + "_release": "2.0.2", + "_resolution": { + "type": "version", + "tag": "2.0.2", + "commit": "bda69de1a18cc4848c8c50278568559139129a60" + }, + "_source": "git://github.com/bermi/password-generator.git", + "_target": "~2.0.1", + "_originalSource": "password-generator" +} \ No newline at end of file diff --git a/src/teamvault/static/bundled/password-generator/.travis.yml b/src/teamvault/static/bundled/password-generator/.travis.yml new file mode 100644 index 00000000..c96bd3b7 --- /dev/null +++ b/src/teamvault/static/bundled/password-generator/.travis.yml @@ -0,0 +1,10 @@ +language: node_js +sudo: false +node_js: + - 0.10 +branches: + only: + - master +notifications: + email: + - bermi@bermilabs.com \ No newline at end of file diff --git a/src/teamvault/static/bundled/password-generator/LICENSE b/src/teamvault/static/bundled/password-generator/LICENSE new file mode 100644 index 00000000..e71379fa --- /dev/null +++ b/src/teamvault/static/bundled/password-generator/LICENSE @@ -0,0 +1,7 @@ +Copyright (c) 2011 Bermi Ferrer + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/src/teamvault/static/bundled/password-generator/README.md b/src/teamvault/static/bundled/password-generator/README.md new file mode 100644 index 00000000..a6ab798b --- /dev/null +++ b/src/teamvault/static/bundled/password-generator/README.md @@ -0,0 +1,176 @@ +# password-generator + +Memorable password generator. For the command line, Node.js and browsers. + +[![Build Status](https://secure.travis-ci.org/bermi/password-generator.png?branch=master)](http://travis-ci.org/bermi/password-generator) + +[![browser support](http://ci.testling.com/bermi/password-generator.png)](http://ci.testling.com/bermi/password-generator) + +## Installation + + $ npm install password-generator + +## Usage + +### From the CLI + + password-generator -h + +Displays this help + + Generates a memorable password + + Options: + -l Password length + -c Generates a non memorable password [default: false] + -p Pattern to match for the generated password + -h Displays this help + +Simple memorable pass + + password-generator + => maqetaxaku + +Custom length + + password-generator -l 30 + => nugiferagiraqadamedewubaqirali + +Non memorable + + password-generator -c + => QPnb3gl7_0 + +Customize the pattern to match for each password character + + password-generator -p "[\d\W\w\p]" + => Je;VgG?{Yd + +Any number or letter + + password-generator -p "[\w]" + => 3NHPqzjIAq + +Combine multiple strategies 6 memorable and 3 numbers + + echo "`password-generator -l 6``password-generator -p "[0-9]" -l 3`" + => wazawe351 + + +### From Node.js + + var generatePassword = require('password-generator'); + +### From the browser + + + +#### Usage + +##### Default settings (memorable 10 letters) + + generatePassword() // -> xexeyimahi + +##### Custom length not memorable + + generatePassword(12, false) // -> 76PAGEaq6i5c + +##### Characters should match a pattern + + generatePassword(12, false, /\d/) // -> 252667390298 + +##### Customize the password prefix + + generatePassword(12, false, /\d/, 'foo-') // -> foo-67390298 + +##### Example with custom validation rules + +Given the pattern regexp can only match a single character +you can build a function that generates multiple passwords until you +hit one that complies with your rules. + +The following example will generate a password with the following requirements + +* Must contain at least two numbers +* Must contain at least three uppercase letters +* Must contain at least three lowercase letters +* Must contain at least two special characters +* Must NOT contain sequences of two or more repeated characters + + +```javascript +var generatePassword = require("password-generator"); + +var maxLength = 18; +var minLength = 12; +var uppercaseMinCount = 3; +var lowercaseMinCount = 3; +var numberMinCount = 2; +var specialMinCount = 2; +var UPPERCASE_RE = /([A-Z])/g; +var LOWERCASE_RE = /([a-z])/g; +var NUMBER_RE = /([\d])/g; +var SPECIAL_CHAR_RE = /([\?\-])/g; +var NON_REPEATING_CHAR_RE = /([\w\d\?\-])\1{2,}/g; + +function isStrongEnough(password) { + var uc = password.match(UPPERCASE_RE); + var lc = password.match(LOWERCASE_RE); + var n = password.match(NUMBER_RE); + var sc = password.match(SPECIAL_CHAR_RE); + var nr = password.match(NON_REPEATING_CHAR_RE); + return password.length >= minLength && + !nr && + uc && uc.length >= uppercaseMinCount && + lc && lc.length >= lowercaseMinCount && + n && n.length >= numberMinCount && + sc && sc.length >= specialMinCount; +} + +function customPassword() { + var password = ""; + var randomLength = Math.floor(Math.random() * (maxLength - minLength)) + minLength; + while (!isStrongEnough(password)) { + password = generatePassword(randomLength, false, /[\w\d\?\-]/); + } + return password; +} + +console.log(customPassword()); // => 2hP5v?1KKNx7_a-W +``` + + +## Running tests + + npm install + make test + +## Building + + npm install + make all + +## License + +(The MIT License) + +Copyright (c) 2011-2012 Bermi Ferrer <bermi@bermilabs.com> + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +'Software'), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/src/teamvault/static/bundled/password-generator/bower.json b/src/teamvault/static/bundled/password-generator/bower.json new file mode 100644 index 00000000..00adf12b --- /dev/null +++ b/src/teamvault/static/bundled/password-generator/bower.json @@ -0,0 +1,23 @@ +{ + "name": "password-generator", + "description": "Memorable password generator. For the command line, Node.js and browsers.", + "version": "2.0.1", + "main": "lib/password-generator.js", + "license": "MIT", + "keywords": [ + "password", + "generator", + "pass", + "random", + "browser", + "crypto", + "security" + ], + "authors": [ + "Bermi Ferrer " + ], + "repository": { + "type": "git", + "url": "git@github.com:bermi/password-generator.git" + } +} diff --git a/src/teamvault/static/bundled/password-generator/dist/password-generator.min.js b/src/teamvault/static/bundled/password-generator/dist/password-generator.min.js new file mode 100644 index 00000000..c1d123e3 --- /dev/null +++ b/src/teamvault/static/bundled/password-generator/dist/password-generator.min.js @@ -0,0 +1,6 @@ +/*! password-generator - v1.0.1 (2015-09-24) +* ----------------- +* Copyright(c) 2011-2015 Bermi Ferrer +* MIT Licensed +*/ +(function(e){function o(e,t){var n,r,i=new Uint8Array(t);u(i);for(n in i)if(i.hasOwnProperty(n)){r=i[n];if(r>e&&rf;f+=1)u=String.fromCharCode(f),u.match(r)&&l.push(u);if(!l.length)throw new Error("Could not find characters that match the password pattern "+r+". Patterns must match individual "+"characters, not the password as a whole.")}while(i.length", + "keywords": [ + "password", + "generator", + "pass", + "random", + "browser", + "crypto", + "security" + ], + "bugs": { + "web": "http://github.com/bermi/password-generator/issues" + }, + "licenses": [ + { + "type": "MIT", + "url": "http://opensource.org/licenses/mit-license.php" + } + ], + "repository": { + "type": "git", + "url": "git://github.com/bermi/password-generator.git" + }, + "dependencies": { + "optimist": "0.6.1" + }, + "devDependencies": { + "expect.js": "0.2.0", + "grunt": "0.3.17", + "mocha": "2.2.5" + }, + "scripts": { + "test": "make test" + }, + "testling": { + "browsers": [ + "iexplore/9..latest", + "firefox/38..latest", + "chrome/40..latest", + "opera/30..latest", + "safari/7..latest", + "iphone/7..latest", + "ipad/7..latest" + ], + "harness": "mocha", + "files": "test/*.js" + }, + "main": "index", + "bin": "./bin/password-generator", + "directories": { + "lib": "./lib" + } +} diff --git a/src/teamvault/static/bundled/zxcvbn/.bower.json b/src/teamvault/static/bundled/zxcvbn/.bower.json new file mode 100644 index 00000000..df5a03df --- /dev/null +++ b/src/teamvault/static/bundled/zxcvbn/.bower.json @@ -0,0 +1,45 @@ +{ + "name": "zxcvbn", + "description": "realistic password strength estimation", + "main": "dist/zxcvbn.js", + "keywords": [ + "password", + "passphrase", + "strength", + "quality", + "estimation", + "estimate", + "meter", + "pattern", + "matcher", + "security", + "authentication", + "cracking", + "scoring", + "entropy", + "bruteforce" + ], + "ignore": [ + "/.*", + "*.json", + "node_modules", + "data", + "data-scripts", + "demo", + "lib", + "src", + "test" + ], + "homepage": "https://github.com/dropbox/zxcvbn", + "version": "3.5.0", + "_release": "3.5.0", + "_resolution": { + "type": "version", + "tag": "3.5.0", + "commit": "6ccccbd140af6b401c6558b549c8239dd4158ce7" + }, + "_source": "git://github.com/dropbox/zxcvbn.git", + "_target": "~3.5.0", + "_originalSource": "zxcvbn", + "_direct": true +} \ No newline at end of file diff --git a/src/teamvault/static/bundled/zxcvbn/LICENSE.txt b/src/teamvault/static/bundled/zxcvbn/LICENSE.txt new file mode 100644 index 00000000..4f083a08 --- /dev/null +++ b/src/teamvault/static/bundled/zxcvbn/LICENSE.txt @@ -0,0 +1,20 @@ +Copyright (c) 2012-2015 Dan Wheeler and Dropbox, Inc. + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/src/teamvault/static/bundled/zxcvbn/README.md b/src/teamvault/static/bundled/zxcvbn/README.md new file mode 100644 index 00000000..e5c29ef3 --- /dev/null +++ b/src/teamvault/static/bundled/zxcvbn/README.md @@ -0,0 +1,234 @@ +``` +_________________________________________________/\/\___________________ +_/\/\/\/\/\__/\/\__/\/\____/\/\/\/\__/\/\__/\/\__/\/\________/\/\/\/\___ +_____/\/\______/\/\/\____/\/\________/\/\__/\/\__/\/\/\/\____/\/\__/\/\_ +___/\/\________/\/\/\____/\/\__________/\/\/\____/\/\__/\/\__/\/\__/\/\_ +_/\/\/\/\/\__/\/\__/\/\____/\/\/\/\______/\______/\/\/\/\____/\/\__/\/\_ +________________________________________________________________________ +``` + +[![Build Status](https://travis-ci.org/dropbox/zxcvbn.svg?branch=master)](https://travis-ci.org/dropbox/zxcvbn) +[![Sauce Test Status](https://saucelabs.com/browser-matrix/dropbox-zxcvbn.svg)](https://saucelabs.com/u/dropbox-zxcvbn) + +`zxcvbn` is a password strength estimator inspired by password crackers. Through pattern matching and conservative entropy calculations, it recognizes and weighs 10k common passwords, common names and surnames according to US census data, popular English words, and other common patterns like dates, repeats (`aaa`), sequences (`abcd`), keyboard patterns (`qwertyuiop`), and l33t speak. + +Consider using zxcvbn as an algorithmic alternative to password policy — it is more secure, flexible, and usable when sites require a minimal complexity score in place of annoying rules like "passwords must contain three of {lower, upper, numbers, symbols}". + +* __More secure__: policies often fail both ways, allowing weak passwords (`P@ssword1`) and disallowing strong passwords. +* __More flexible__: zxcvbn allows many password styles to flourish so long as it detects sufficient complexity — passphrases are rated highly given enough uncommon words, keyboard patterns are either terrible or great depending on length and number of turns, and capitalization adds more complexity when it's unpredictaBle. Neither crackers nor zxcvbn are fooled by `'@'` for `'a'` or `'0'` for `'o'`. +* __More usable__: Dumping a list of password rules onto users hurts usability. Understanding and satisfying said rules can be time-consuming and frustrating, leading to passwords that are [harder to remember](https://xkcd.com/936/). Use zxcvbn instead to build simple, rule-free interfaces that give instant feedback. + +At Dropbox we use zxcvbn on our [signup page](https://www.dropbox.com/register) and change/reset password flows. zxcvbn is designed for node and the browser, but we use our [python port](https://github.com/dropbox/python-zxcvbn) inside the Dropbox desktop client, [Objective C port](https://github.com/dropbox/zxcvbn-ios) in our iOS app, and Java port (not yet open sourced) on Android. + +[Release notes](https://github.com/dropbox/zxcvbn/releases) + +For more motivation, see: + +http://tech.dropbox.com/?p=165 + +# Installation + +zxcvbn detects and supports CommonJS (node, browserify) and AMD (RequireJS). In the absence of those, it adds a single function `zxcvbn()` to the global namespace. + +## Bower + +Install [`node`](https://nodejs.org/download/) and [`bower`](http://bower.io/) if you haven't already. This won't make your codebase dependent on node or bower. + +Get `zxcvbn`: + +``` shell +cd /path/to/project/root +bower install zxcvbn +``` + +Add this script to your `index.html`: + +``` html + +``` + +To make sure it loaded properly, open your html in a browser and type `zxcvbn('Tr0ub4dour&3')` into the console. + +To pull in updates and bug fixes: + +``` shell +bower update zxcvbn +``` + +## Node / npm + +zxcvbn works identically on the server. + +``` shell +$ npm install zxcvbn +$ node +> var zxcvbn = require('zxcvbn'); +> zxcvbn('Tr0ub4dour&3'); +``` + +## RequireJS + +Add [`zxcvbn.js`](https://raw.githubusercontent.com/dropbox/zxcvbn/master/dist/zxcvbn.js) to your project (using bower, npm or direct download) and import as usual: + +``` javascript +requirejs(["relpath/to/zxcvbn"], function (zxcvbn) { + console.log(zxcvbn('Tr0ub4dour&3')); +}); +``` + +## Browserify / Webpack + +If you're using `npm` and have `require('zxcvbn')` somewhere in your code, browserify and webpack should just work. + +``` shell +$ npm install zxcvbn +$ echo "console.log(require('zxcvbn'))" > mymodule.js +$ browserify mymodule.js > browserify_bundle.js +$ webpack mymodule.js webpack_bundle.js +``` + +But we recommend against bundling zxcvbn via tools like browserify and webpack, for three reasons: + +* Minified and gzipped, zxcvbn is still several hundred kilobytes. (Significantly grows bundle size.) +* Most sites will only need zxcvbn on a few pages (registration, password reset). +* Most sites won't need `zxcvbn()` immediately upon page load; since `zxcvbn()` is typically called in response to user events like filling in a password, there's ample time to fetch `zxcvbn.js` after initial html/css/js loads and renders. + +See the [performance](#perf) section below for tips on loading zxcvbn stand-alone. + +Tangentially, if you want to build your own standalone, consider tweaking the browserify pipeline used to generate `dist/zxcvbn.js`: + +``` shell +$ browserify --debug --standalone zxcvbn \ + -t coffeeify --extension='.coffee' \ + -t uglifyify \ + src/main.coffee | exorcist dist/zxcvbn.js.map >| dist/zxcvbn.js +``` + +* `--debug` adds an inline source map to the bundle. `exorcist` pulls it out into `dist/zxcvbn.js.map`. +* `--standalone zxcvbn` exports a global `zxcvbn` when CommonJS/AMD isn't detected. +* `-t coffeeify --extension='.coffee'` compiles `.coffee` to `.js` before bundling. This is convenient as it allows `.js` modules to import from `.coffee` modules and vice-versa. Instead of this transform, one could also compile everything to `.js` first (`npm run prepublish`) and point `browserify` to `lib` instead of `src`. +* `-t uglifyify` minifies the bundle through UglifyJS, maintaining proper source mapping. + +## Manual installation + +Download [zxcvbn.js](https://raw.githubusercontent.com/dropbox/zxcvbn/master/dist/zxcvbn.js). + +Add to your .html: + +``` html + +``` + +# Usage + +``` javascript +zxcvbn(password, user_inputs=[]) +``` + +`zxcvbn()` takes one required argument, a password, and returns a result object. The result includes a few properties: + +``` coffee +result.entropy # bits + +result.crack_time # estimation of actual crack time, in seconds. + +result.crack_time_display # same crack time, as a friendlier string: + # "instant", "6 minutes", "centuries", etc. + +result.score # [0,1,2,3,4] if crack time is less than + # [10**2, 10**4, 10**6, 10**8, Infinity]. + # (useful for implementing a strength bar.) + +result.match_sequence # the list of patterns that zxcvbn based the + # entropy calculation on. + +result.calc_time # how long it took zxcvbn to calculate an answer, + # in milliseconds. +```` + +The optional `user_inputs` argument is an array of strings that zxcvbn will treat as an extra dictionary. This can be whatever list of strings you like, but is meant for user inputs from other fields of the form, like name and email. That way a password that includes a user's personal information can be heavily penalized. This list is also good for site-specific vocabulary — Acme Brick Co. might want to include ['acme', 'brick', 'acmebrick', etc]. + +# Performance + +## runtime latency + +zxcvbn operates below human perception of delay for most input: ~5-20ms for ~25 char passwords on modern browsers/CPUs, ~100ms for passwords around 100 characters. To bound runtime latency for really long passwords, consider sending `zxcvbn()` only the first 100 characters or so of user input. + +## script load latency + +`zxcvbn.js` bundled and minified is about 320kb gzipped or 680kb uncompressed, most of which is dictionaries. Consider these tips if you're noticing page load latency on your site. + +* Make sure your server is configured to compress static assets for browsers that support it. ([nginx tutorial](https://rtcamp.com/tutorials/nginx/enable-gzip/), [apache/IIS tutorial](http://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/).) + +Then try one of these alternatives: + +1. Put your `