philipmw / phrase.shop

A web app to generate secure yet memorable passphrases

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.

phrase.shop's Issues

Add parts of speech

<adjective> <noun> <verb>s is more memorable than <word> <word> <word>.

Find a way to incorporate capital letters into phrase

Capital letters are required for many passphrases, but phrase.shop's attitude toward that is, "just capitalize it yourself." But maybe customers want a capitalized phrase delivered?

Some options are to randomly capitalize the start of each word, to randomly capitalize the first word, or even randomly capitalize any letter.

Persisting/clearing policy for generated phrases

Right now, the app displays the last generated phrase indefinitely, but it does not persist it in any local storage.

This means we don't control if/when the phrase disappears from the customer. It depends on the browser. For mobile devices, it depends on memory pressure.

The customer may want us to clear the phrase more aggressively. They can already close the tab/window, but maybe they forgot and hand the device to someone else who can unintentionally see the phrase.

Or the customer may want us to be conservative and persist the phrase until they explicitly clear it. I've had it happen that I generate a phrase, set it as the password on an important system, then forget it-- and it was already gone by then.

I see three possible approaches:

1. Clear phrase after X time (optimize for security).
2. Keep current behavior. Let the browser manage it. (optimize for simplicity).
3. Persist phrase in local storage until explicit customer action. (optimize for data integrity).

I don't have a clear answer.

Set up a canary

Set up a canary to alert me if the site ever goes down or breaks.

Improve verb conjugation

Today, making a verb plural uses a home-brewed algorithm that's often wrong. Wrong pluralization is confusing, distracting, and makes phrases less readable and memorable.

I do not want to rely on a 3rd party library (or worse, a service) to pluralize, since phrase.shop has minimal dependencies today and that's a virtue.

Let's also consider other conjugations for verbs, to make phrases more expressive and increase entropy.

Saved parts

I would like to be able to create my own custom preset

It would appear that an update has removed the ability to choose your own parts
I would like the ability to choose my own and then save that set of parts as a custom preset

So where there are currently 3 buttons, a fourth choice could be added for the user's custom preset that could be used when returning to the site

Support setting entropy requirement through URL param

Needs UX design. What are the use cases? An organization setting a minimum bar?

Disable zooming on mobile double tap

I keep zooming in unintentionally.

Install to browser offline

I note that I can disconnect my network and the page still works

However, if (for whatever reason) the page is reloaded/refreshed; then the app can not be reloaded.

I request that it can be installed as a chrome web app to allow for true offline use.

This link might explain the relevant info https://developer.chrome.com/blog/getting-started-pwa/#service-worker-for-offline-caching

Add meta description tag to improve SEO

https://web.dev/meta-description/

Support regenerating the passphrase without starting over

Although we'd need to warn the user:

By rerolling, you are decreasing the effective entropy of your passphrase because you are expressing a preference that an attacker may take advantage of.

This warning needs UX design.

Add support for light mode and dark mode

Right now the app is very dark, which is good for dark mode, but maybe not so good for light mode. Let's have two styles, one for light and one for dark modes.

Add code coverage metric visible in GitHub

Write first round of unit tests

Incorporate favicon into UI

For brand recognition, let's put the favicon into the UI somehow. My latest thinking is to put it into the buttons.

Remember phrase configuration

Once I configure my perfect <verb> <noun> <digit> <digit> <adjective> <noun>, I want the app to remember this, or I want to be able to bookmark this configuration.

Separate verbs into transitive and not

Ensure that transitive verbs are used only with a direct object.

Conjugate words

Now: <noun> <verb> => fish defeat

Wanted: <noun> <verb> => fish defeats or fish defeated

This will improve memorability.

Do not shift buttons during phrase building

This is annoying to the user.

Narrow range of word lengths in English wordbank

Instead of 1--6 letters, aim for 4--6 to help customer meet minimum passphrase length requirements.

Improve the dark UI

The UI right now looks very high contrast and alarming. I have some ideas for how to improve it.

Collect entropy bits from more dice sides

Right now we collect entropy bits only from the first 2^n sides of dice. We discard rolls on sides above that.

For example, for six-sided dice, we collect entropy from sides 1--4 but discard rolls landing on 5 and 6.

This is wasteful and may be confusing to the user.

To collect entropy from the largest range of dice sides, we need to implement algorithm Q2 from this paper: http://markus-jakobsson.com/papers/jakobsson-ieeeit00.pdf

Improve SEO

1. Add an H1 tag
2. Add sitemap.xml (how)
3. Lengthen TITLE tag
4. Lengthen meta description to 70--320 characters
5. Add robots.txt

Upgrade to Webpack 5

https://webpack.js.org/blog/2020-10-10-webpack-5-release/

Animate phrase parts, cycling through keyspace, before landing on cleartext

Just for fun.

Switch to Preact

Don't jerk UI during animation

Right now, while the phrase is animating, everything below it (disabled buttons, text) is jumping around. This is especially pronounced on mobile.

Redesign the UI so there is no jerking. One idea is to fade out everything below the animation, then bring it back once the animation is done.

Improve color-coding of phrase parts

Right now almost all parts of phrase are black, except for color type which is intense blue.

Let's give subtle coloring to nouns vs verbs to cue the reader to understand phrases easier that have ambiguous words.

Edit phrase parts without refreshing / starting over

Needs UX design. Allow drag and drop, or only (x) to delete?

Set GitHub repo icon for this project

Add support for supplying entropy with fair dice

Separate noun wordbank into countable and not

https://en.wikipedia.org/wiki/Count_noun

Many nouns we have in the wordbank are not count nouns, so pluralizing them does not make sense. For example, "3 weathers" shouldn't be allowed.

Split the current wordbank of nouns into count nouns and not.

Dice sides numeric input is inconvenient/broken on iPhone

It does not show spinner buttons, so I have to backspace, and as soon as I erase the last digit, the app crashes.

Ability to type dice values

It can become tedious to manually enter each dice value with a click on a button.
Especially when those first 6 dice have icons that are very hard to see without squinting.

Please add a text entry box that allows multiple dice values to be entered at once using a space or comma etc, to separate the values.

This way a user can throw multiple dice and type the values instead of matching them to values on a screen that need to be clicked (it's more optimized to enter them on a keyboard where the user may already know the positions of the keys such as the Numpad)

Additionally, they could potentially copy and paste the values from a premade CSV string of their dice results - making it much faster to enter dice rolls as opposed to generated ones (making it less likely a user will choose the generated option for convenience reasons - which is less secure)

Widen the dice slider so it's easier to select wanted value

During animation, mask all final plaintext

Right now, during phrase animation, sometimes real plaintext shines through. The real plaintext is visually distinct from animation temp plaintext, so it is distracting. Plus we don't want to reveal the plaintext til animation is finished.

This seems to happen in the beginning of animation and is especially visible with long phrases.

I suspect it is because we generate temp plaintext for each slot incrementally, and before we generate the temp plaintext for a slot, it defaults to displaying its real plaintext. If so, we can solve it by generating temp plaintext for all slots at animation start, before the incremental algorithm starts.

Eliminate render-blocking resources

https://web.dev/render-blocking-resources/

Add airport codes as a phrase part type

Good list here: https://www.faa.gov/airports/planning_capacity/passenger_allcargo_stats/passenger/media/preliminary-cy19-commercial-service-enplanements.pdf

Fix interaction between sentence templates and dice entropy

In phrase.shop v1, you'd first build a phrase from parts (which requires no entropy), then generate it (which does). With dice entropy, the app would let you build the phrase but keep the Generate button disabled until you roll the dice enough times. This ensured we don't try to generate the phrase until we have enough entropy.

In v2, building and generating are combined into one step, but the entropy check now happens at the wrong time and for the wrong amount.

Add Fry words

Fry words are an alternative to Voice of America.

Add support for supplying entropy with loaded dice

http://markus-jakobsson.com/papers/jakobsson-ieeeit00.pdf