mutkoff/yopass-mfa repository overview

⁠Yopass MFA

A self-hosted Yopass fork with one-time in-browser image preview for secure sharing of passwords, secrets, files, and MFA/TOTP QR codes.

Based on the original Yopass⁠ project.

⁠What's different?

The main addition is direct preview of encrypted images in the browser.

Supported image formats:

• PNG
• JPEG
• WebP

Instead of automatically downloading an MFA QR code, the recipient can open the one-time link and scan the QR code directly from the browser.

The original Yopass security model is preserved:

• client-side encryption and decryption;
• server stores only encrypted data;
• one-time secrets are removed after retrieval;
• no external cloud services are required.

This makes yopass-mfa especially useful for distributing MFA/TOTP enrollment QR codes inside organizations.

⁠Quick Start

Create a docker-compose.yml:

services:
  memcached:
    image: memcached:1.6-alpine
    container_name: yopass-memcached
    restart: unless-stopped
    command:
      - memcached
      - -m
      - "128"
      - -I
      - 10m

  yopass:
    image: mutkoff/yopass-mfa:latest
    container_name: yopass
    restart: unless-stopped
    command:
      - --memcached=memcached:11211
      - --force-onetime-secrets
    ports:
      - "8080:1337"
    depends_on:
      - memcached

Start the service:

docker compose up -d

Check container status:

docker compose ps

Open Yopass in your browser:

http://SERVER_IP:8080

For example:

http://192.168.1.100:8080

⁠Usage

1. Open Yopass.
2. Upload a password, secret, file, or MFA QR-code image.
3. Create a one-time link.
4. Send the link to the recipient.
5. The recipient opens the link and decrypts the secret in the browser.
6. Image files are displayed directly in the browser instead of being automatically downloaded.
7. The recipient scans the QR code with an authenticator application.

Regular non-image files continue to work like standard Yopass downloads.

⁠Update

docker compose pull
docker compose up -d

⁠Stop

docker compose down

⁠Production Use

For production use, HTTPS is strongly recommended.

When using Nginx, Traefik, Caddy, or another reverse proxy on the same server, bind Yopass only to localhost:

ports:
  - "127.0.0.1:8080:1337"

Then proxy HTTPS traffic to:

http://127.0.0.1:8080

⁠Storage

The example configuration uses Memcached for temporary encrypted storage.

Secrets are stored in memory and are not persisted to disk by default. Restarting Memcached removes all currently stored secrets.

⁠Security Note

A one-time link prevents the secret from being retrieved from the server more than once.

Once an image is displayed in the browser, however, it is technically impossible to prevent the recipient from taking a screenshot or photographing the screen.

⁠License

This project is based on Yopass, which is licensed under the Apache License 2.0.

See the included LICENSE file for details.