phrase.shop

phrase.shop is a web app to generate secure yet memorable passphrases.

Purpose and inspiration

• You Should Probably Change Your Password
• Diceware
• How long should my passphrase be?
• DiceKeys
• Man vs. Machine, or, why Man is not a Particularly Good Source of Entropy.

Features

While there are several passphrase generators online, this one has the following strengths:

• It aims to make phrases grammatically correct, not just words strung together.
• You can make the phrase more or less complex. You are not limited to five rolls of six-sided dice.
• It uses Voice Of America's Learning English vocabulary of core English words.
• If you don’t want to use your computer’s random number generator, you can roll physical dice and submit the rolls to the app to collect entropy. There’s a progress bar showing how much entropy you’ve collected, and you can generate the passphrase only once you’ve rolled enough times. What this feature lacks in practicality it makes up for in educational and entertainment value!
• The app is open-source, and contributions are welcome.
• The app's only motivations is making you good passphrases. Its only customer is you. There are no ads and no data collection.

Design principles

• Strong passphrases are for everyone, including those who don't care about or understand entropy, and including those with limited English.
• App is engaging and educational for those who understand, or want to learn, about entropy.
• Shop theme: you are buying passphrase components, paying for them with entropy.

Dice

While any modern computer's randomness is just fine, using physical dice is more fun.

I like hexadecimal (16-sided) dice from Gamescience. I have three of these, bought specifically for this project. I roll all three at a time, for 12 bits of entropy per roll. This makes generating even the longest passphrase a breeze.

Gamescience also sells a 100-sided monster of a dice, which would yield a massive 6 bits of entropy per roll.

Developing

I welcome your contributions. In particular, I'm very supportive of newbie developers.

This app is written in TypeScript and uses Preact as the web framework. For unit tests, it uses Jest and Enzyme.

If you are new to developing web applications, I recommend the book Test-Driven React, which will introduce you to React, Jest, Enzyme, and Wallaby.js.

The workflow I propose:

1. Decide what to work on. There are a number of open issues that you're welcome to resolve, or you can scratch your own itch. Before starting development, please open an issue for your desired change so we can discuss it and align on whether it needs to be addressed and how to address it. If you don't lead with an issue, you risk wasting your time developing something I'll disagree with and won't accept.

2. Work on your changes. See next sections for how to run this project locally.

3. Run npm run build before submitting a pull request and resolve any linter and unit test errors.

4. Submit a pull request on GitHub. Check that your change passes the Continuous Integration workflow. I'll review your contribution, and we'll either have a discussion, or I'll accept your change as-is.

5. You'll see your contribution on https://phrase.shop!

UX flow

flowchart TB
    init([App start])
    generating[/Generating.../]
    viewResult(View generated passphrase)

    init-->generating
    generating-- consume entropy -->viewResult
    viewResult-- change/seed entropy -->viewResult
    viewResult-- change complexity -->generating

UI component architecture

classDiagram

class App {
  entropyBitsAvailable
  entropySource
  phraseParts
}

class PhrasePartUi {
  type
}

class PhraseStruct {
  phraseParts
  order
  dependencyTree
}

App o-- PhrasePartUi

Running phrase.shop locally

Install npm using whatever means is most convenient for you, such as Homebrew on macOS.

Initialize:

$ npm install

This creates a node_modules directory.

Run unit tests:

$ npm test

Run the app locally:

$ npm start

This supports hot-reloading, so feel free to edit Javascript and see your changes in the browser immediately.

Run linter and generate final artifacts:

$ npm run build

This produces the app bundle Javascript, in ./docs, that's served to real customers. If any part of this process fails, please fix any issues before submitting a pull request.

why some things are the way they are

• https://stackoverflow.com/a/64223627/1214939

React/TS template

The React/TS template for this web app came from https://github.com/philipmw/spa-template.

favicon

I made the favicon with Inkscape 1.0, with all the creativity that I could muster.