Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
Add passphrase dictionaries contributing docs (#776)
Leendert de Borst352d3d3c733c
diff --git a/docs/docs/contributing/index.mdx b/docs/docs/contributing/index.mdxindex dbd765b5c..44e8deedd 100644--- a/docs/docs/contributing/index.mdx+++ b/docs/docs/contributing/index.mdx@@ -21,12 +21,21 @@ Here are some common ways you can help the AliasVault project:<a className="av-action-card" href="./identity-generator/"><div className="av-action-card__emoji">๐ค</div>- <div className="av-action-card__title">Translate Identity Generator</div>+ <div className="av-action-card__title">Improve Identity Generator</div><p className="av-action-card__desc">Provide name dictionaries to make the identity generator support your language.</p><span className="av-action-card__cta">Get Started</span></a>++ <a className="av-action-card" href="./passphrase-dictionaries/">+ <div className="av-action-card__emoji">๐ฒ</div>+ <div className="av-action-card__title">Improve Passphrase Generator</div>+ <p className="av-action-card__desc">+ Add or improve the Diceware word lists used to generate memorable passphrases.+ </p>+ <span className="av-action-card__cta">Get Started</span>+ </a></div>---@@ -62,8 +71,6 @@ Help improve our documentation:### ๐ป Code ContributionsSee the [Development](development/index.md) guide for setting up a local-environment and working on the apps, and the+environment to contribute to the AliasVault apps. See the[CONTRIBUTING.md](https://github.com/aliasvault/aliasvault/blob/main/CONTRIBUTING.md)for contribution guidelines.--**Thank you for making AliasVault better!** ๐diff --git a/docs/docs/contributing/passphrase-dictionaries.md b/docs/docs/contributing/passphrase-dictionaries.mdnew file mode 100644index 000000000..9d69bc6c6--- /dev/null+++ b/docs/docs/contributing/passphrase-dictionaries.md@@ -0,0 +1,101 @@+---+sidebar_position: 4+sidebar_label: "Passphrase Generator"+---+# Passphrase Generator++AliasVault can generate memorable and secure passphrases (instead of random character passwords) using the [Diceware](https://en.wikipedia.org/wiki/Diceware) method. Each passphrase is built by picking random words from a language-specific word list, for example `correct-horse-battery-staple`.++The word lists (dictionaries) are available in the following languages:++- ๐ฌ๐ง **English** (en)+- ๐ณ๐ฑ **Dutch** (nl)+- ๐ฉ๐ช **German** (de)+- ๐ซ๐ท **French** (fr)+- ๐ช๐ธ **Spanish** (es)+- ๐ฎ๐น **Italian** (it)++**Your language not listed?** Help us add it! And if your language *is* listed, you can still help by improving the existing word list.++---++## How Diceware works++Diceware maps every word in a list to a unique sequence of five dice rolls. Because each die has 6 sides, a complete list contains exactly **7776 words** (6โต = 7776), one word per line, in dice order. Rolling five dice (or generating an equivalent random number) selects one word, and chaining several words together produces a passphrase.++The 7776-word size is what gives each word a known, uniform amount of entropy (about 12.9 bits per word), which is the whole point of Diceware. For this reason every dictionary **must contain exactly 7776 words**. Not more, not less.++---++## Adding a New Language++If youโd like to help add a new language to the passphrase generator, you can do so by providing a new Diceware word list:++A good word list:+- โ Contains exactly **7776 unique words**, one per line+- โ Uses **common, easy-to-spell, easy-to-type** words from everyday language+- โ Avoids profanity, slurs, and otherwise offensive or upsetting words+- โ Avoids very long words and confusing near-duplicates where possible++### How to submit++- **GitHub**: Open a pull request adding a `<code>.diceware` file (see [existing dictionaries](#existing-dictionaries) below for the exact format)+- **Discord**: Join our [community server](https://discord.gg/DsaXMTEtpF) and share in #translations (a maintainer will collaborate with you)+- **Email**: [[email protected]](mailto:[email protected]) and attach the wordlist to the email.++After we receive the list, we'll take care of the technical formatting, attribution, and wiring it into the AliasVault apps.++---++## Improving an Existing Dictionary++The current dictionaries were collected from a variety of upstream sources (see the [attribution file](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/ATTRIBUTION.md)). They are a great starting point, but they are not perfect and improvements are very welcome.++Common reasons to improve a list include:++- **Uncommon or obscure words**: words most native speakers wouldn't recognize or use+- **Hard-to-spell or hard-to-type words**: these make passphrases harder to type and remember+- **Replacing profanity or offensive words**: eliminating words that could be upsetting or inappropriate+- **Inconsistencies**: duplicates, accents, or formatting that doesn't fit the rest of the list++### How to edit a dictionary++You can edit an existing word list directly on GitHub.++1. Open the dictionary for your language:+ - [๐ฌ๐ง English (`en.diceware`)](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/en.diceware)+ - [๐ณ๐ฑ Dutch (`nl.diceware`)](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/nl.diceware)+ - [๐ฉ๐ช German (`de.diceware`)](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/de.diceware)+ - [๐ซ๐ท French (`fr.diceware`)](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/fr.diceware)+ - [๐ช๐ธ Spanish (`es.diceware`)](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/es.diceware)+ - [๐ฎ๐น Italian (`it.diceware`)](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/it.diceware)+2. Click the โ๏ธ "Edit this file" button in the top-right of the file view. GitHub will ask you to create your own copy (fork) of the project. Click to confirm.+3. Make your changes.+4. Click **Commit changes** and choose **Create a new branch and start a pull request**.+5. Submit the pull request. A maintainer will review it and merge it in.++If you'd rather not use GitHub, you can also reach us on [Discord](https://discord.gg/DsaXMTEtpF) or by [email](mailto:[email protected]), and send us your improved list there.++:::warning Keep exactly 7776 words+A Diceware list must always contain **exactly 7776 words**, since removing a word breaks the entropy math (and the validation tests). So **replace or edit words in place, don't add or remove lines**. To fix a bad word, swap it for a better one on the same line.+:::++---++## Example dictionaries++Here are some example wordlists you can view for reference:++- [All wordlists (GitHub directory)](https://github.com/aliasvault/aliasvault/tree/main/core/rust/src/password_generator/wordlists)+- [English example (`en.diceware`)](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/en.diceware)+- [Attribution & sources](https://github.com/aliasvault/aliasvault/blob/main/core/rust/src/password_generator/wordlists/ATTRIBUTION.md)++These files are plain text, with one word per line, in dice (random) order. Each contains exactly 7776 lines.++---++## Questions?+If you have any questions, feel free to get in touch:++- Join our [Discord](https://discord.gg/DsaXMTEtpF) - Ask questions in #translations+- Email us: [[email protected]](mailto:[email protected])diff --git a/docs/sidebars.ts b/docs/sidebars.tsindex a115647bb..16a476f41 100644--- a/docs/sidebars.ts+++ b/docs/sidebars.ts@@ -63,7 +63,7 @@ const sidebars: SidebarsConfig = {label: 'Contributing to AliasVault',link: {type: 'doc', id: 'contributing/index'},collapsed: false,- items: ['contributing/ui-translations', 'contributing/identity-generator'],+ items: ['contributing/ui-translations', 'contributing/identity-generator', 'contributing/passphrase-dictionaries'],},{type: 'category',