Skip to content

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.mdx
index 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 Contributions
See 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.md
new file mode 100644
index 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.ts
index 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',