Bitwarden Alias Provider

This service mimics the Addy.io API to allow Bitwarden to generate email aliases directly on your email providers. It uses coolname for human-readable aliases. These services are supported at this moment:

• Purelymail
• MXRoute

⚠️ Disclaimer

Although there's authentication to the app, diligence is needed when exposing this utility to the public.

I'm not responsible for any compromised data.

Usage

Environment Variables

1. Configure the environment variables in a .env file or use them directly inside your docker-compose.yml:

   SERVER_API_TOKEN=your_secure_token_here
   ALIAS_PROVIDER=<your_provider> # available options: mxroute, purelymail
   
   # "mxroute" ALIAS_PROVIDER
   MXROUTE_SERVER=<your_server>.mxrouting.net
   MXROUTE_USERNAME=<control_pane_username>
   MXROUTE_API_KEY=<control_pane_api_key>
   
   # "purelymail" ALIAS_PROVIDER
   PURELYMAIL_API_KEY=<api_key>
   
   SERVER_ADDRESS=http://bitwarden-alias-provider-server:6123 # Optional for web app

2. Grab the example docker-compose file from here.
3. Start the service:

   docker-compose up -d

The application will be running on http://localhost:6123 by default.

How to use

Configure Bitwarden's "Generator" Tab:

1. Type: Forwarded email alias
2. Service: Addy.io
3. Email domain:
   1. Since we are "hacking" the Addy.io API spec for this plugin to work, all the customization is done through this field. The Web UI has an options configurator for ease of use, although optional
   2. Refer to the Available Options section below
4. API Key: Use the value of SERVER_API_TOKEN
5. Self-host server URL: http://<server_address>:6123/add
6. Click the "Generate email" icon

Available Options

Configure these in the "Email domain" field using key=value format, separated by commas.

Option	Type	Required	Default	Description
domain	String	yes	None	The domain to create the alias on.
destination	String	yes	None	The destination email address.
template	String	no	<slug>	Format template. Allowed: <slug>, <hex>.
prefix	String	no	None	Prefix added to the alias.
suffix	String	no	None	Suffix added to the alias.
hex_length	Number	no	6	Length of the random hex string.
slug_length	Number	no	2	Number of words in the slug.
slug_separator	String	no	_	Separator between slug words.
alias_separator	String	no	_	Separator between alias components.

Example Input: domain=test.com,destination=hello@test.com,prefix=foo,template=<slug><hex>,alias_separator=-

Result: foo-good_morning-8ed379@test.com

Note: If you encounter issues, try clearing the extension cache.

Web App & API

This project includes a web interface for managing aliases and an API for direct access.

• Web App: http://localhost:6124 (default)
• API Status: GET /
• List Aliases: GET /list/<domain>
• Add Alias: POST /add
• Delete Alias: DELETE /delete/<alias_email>

Browser Extensions

This project provides a helper browser extension (Chrome & Firefox) that allows you to easily generate option strings and manage your aliases without opening the full web app.

1. Download: Download the bitwarden-alias-provider-extension.zip from the latest GitHub Actions run
2. Unzip: Extract the zip file to a folder

Chromium Browsers

1. Go to chrome://extensions/
2. Enable Developer mode (top right toggle)
3. Click Load unpacked
4. Select the folder where you extracted the extension

Firefox

1. Go to about:debugging#/runtime/this-firefox
2. Click Load Temporary Add-on...
3. Select the manifest.json file inside the extracted folder

Development

The only method that I support right now is using a Nix shell.

1. Enter the development shell: nix develop
2. Run services: docker compose up