vygrant

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #typescript #go #android #rust #linux #macos #java #windows #cli #ios #mcp

(★ 11)

vygrant - oauth2 token manager daemon for legacy and cli applications

vygrant Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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`:

```bash
yay -S vygrant
# or
paru -S vygrant
```

Else you can install it manually using `git` and `makepkg`:

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

### Manual

```bash
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:

```bash
vygrant init
```

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

```toml
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:

```bash
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:

```bash
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:

```bash
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
```

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

* [Pizauth](https://github.com/ltratt/pizauth)
* [Email OAuth 2.0 Proxy](https://github.com/simonrob/email-oauth2-proxy)
* [mailctl](https://github.com/pdobsan/mailctl)
* [mutt_oauth2.py](https://gitlab.com/muttmua/mutt/-/blob/master/contrib/mutt_oauth2.py)
* [oauth-helper-office-365](https://github.com/ahrex/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.

vygrant

vygrant Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

vygrant

vygrant Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README