vygrant

OAuth2 Authentication Daemon for Legacy Applications

vygrant provides a local CLI and background daemon for managing OAuth2 tokens on legacy applications that lack modern authentication support.

Features

• Daemon + CLI: Manage and refresh tokens through a local Unix socket.
• Secure token handling: Tokens are stored securely in memory and optionally persisted.
• Auto-refresh & notifications: Optional background token refresh with notification support on Linux/macOS/Windows.

Installation

Arch Linux

You can install vygrant from the AUR using an AUR helper like yay or paru:

yay -S vygrant
# or
paru -S vygrant

Else you can install it manually using git and makepkg:

git clone https://aur.archlinux.org/vygrant.git
cd vygrant
makepkg -si

Manual

git clone https://github.com/vybraan/vygrant.git
cd vygrant
go build  -ldflags "-s -w"

Getting Started

1. Initialize Configuration

Create a default configuration file:

vygrant init

This generates a config at ~/.config/vybr/vygrant.toml. Open and edit the file to register your OAuth2 accounts:

https_listen = "8443"
http_listen = ""
persist_tokens = true

[account.myapp]
auth_uri = "https://provider.com/auth"
token_uri = "https://provider.com/token"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
redirect_uri = "https://localhost:8443"
scopes = ["openid", "profile", "email"]

Optional Settings

• https_listen: Port for HTTPS callbacks (default 8080).
• http_listen: Port for HTTP callbacks (default disabled). Use this with redirect_uri = "http://localhost:<port>" if your browser blocks the self-signed HTTPS callback.
• persist_tokens: Whether to persist refresh tokens (default true). When enabled, vygrant prefers the OS keyring; access tokens stay in memory.
• token_event_cmd: Optional shell command to run whenever tokens change (set/delete/restore). VYGRANT_ACCOUNT and VYGRANT_EVENT are exported.

Token persistence and migration

• If a legacy ~/.vybr/vygrant/tokens.json exists and the keyring is available, vygrant migrates refresh tokens to the keyring on first run and renames the old file to tokens.json.bak.
• If the keyring is unavailable but a legacy tokens.json exists, vygrant uses that file store with a warning (legacy compatibility).
• If the keyring is unavailable and no legacy file exists, tokens are memory‑only and will be lost on daemon restart.
• If the keyring is unavailable and pass is installed, vygrant uses pass as the refresh-token store (access tokens remain in memory).

Exporting and restoring tokens (advanced)

You can export the current token state and re-import it later:

vygrant token dump > tokens.json
cat tokens.json | vygrant token restore

The dump contains secrets; store it encrypted (e.g., age, gpg). When token_event_cmd is set, you can automate this export on changes.

You may use Thunderbird's OAuth2 client ID/secret for Microsoft accounts, but it's recommended to create your own credentials.

2. Start the Daemon

Ensure the config exists, then run:

vygrant server

The daemon will listen for OAuth2 callbacks and manage the tokens.

Trusting the local certificate (one-time)

Vygrant generates a local CA and a localhost certificate on first run. To avoid browser warnings for HTTPS callbacks, import and trust the CA certificate once:

• Use the built-in command: vygrant trust (add --system for system trust where supported).
• CA certificate path: ~/.vybr/vygrant/certs/vygrant_ca.pem
• To remove trust later, run: vygrant untrust (add --system for system trust).

If you reinstall on another machine, a new CA is generated and should be trusted again.

3. Authenticate via CLI

Use the CLI to initiate authentication in your browser:

vygrant token refresh myapp

After approval in the browser, you'll see a friendly success page. You can then close the tab and vygrant handles everything in the background.

CLI Commands Overview

• vygrant accounts - list all configured accounts.
• vygrant status - display authentication status (valid, expired, missing).
• vygrant info - show daemon config details (socket path, ports, etc.).
• vygrant token get <account> - retrieve access token.
• vygrant token delete <account> - remove a stored token.
• vygrant token refresh <account> - perform OAuth authentication flow (opens browser).

Example usage with msmtp

account example@hotmail.com
host smtp-mail.outlook.com
port 587
from example@hotmail.com
user example@hotmail.com
passwordeval "vygrant token get myapp"
auth on
tls on
tls_trust_file	/etc/ssl/certs/ca-certificates.crt
tls_starttls

Quickshell Desktop UI (experimental)

There is an experimental Quickshell UI under quickshell/shell.qml.

• It shows daemon info, accounts, and status.
• It supports token actions for the selected account: refresh, delete, and get.
• It refreshes data periodically.

Run it with:

quickshell --path ./quickshell/shell.qml

If vygrant is not in your PATH, launch quickshell from a shell where it is available.

Alternatives

vygrant is very simple. You may also consider these programs as alternatives:

• Pizauth
• Email OAuth 2.0 Proxy
• mailctl
• mutt_oauth2.py
• oauth-helper-office-365

Contributing & License

Contributions are welcome! Please fork, submit pull requests, or file issues for enhancements or bug fixes.

vygrant is released under the MIT License.