passtunnel

<div align="center">

# PassTunnel

**Connect your VPN without ever typing a one-time code again.**

PassTunnel is an open-source macOS app for OpenVPN and FortiGate SSL VPN. It keeps your TOTP
secret in the Keychain and fills in the current code (and your password) every time you connect.

[![macOS 13+](https://img.shields.io/badge/macOS-13%2B-blue)](#install)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Swift 5.10](https://img.shields.io/badge/Swift-5.10-orange)](Package.swift)
[![CI](https://github.com/passtunnel/passtunnel/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/passtunnel/passtunnel/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/PassTunnel/passtunnel/badge)](https://scorecard.dev/viewer/?uri=github.com/PassTunnel/passtunnel)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15779/badge)](https://www.bestpractices.dev/projects/15779)
[![OpenSSF Baseline](https://www.bestpractices.dev/projects/15779/baseline)](https://www.bestpractices.dev/projects/15779)

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/main-dark.png">
  <img src="docs/images/main-light.png" width="680" alt="PassTunnel main window: one row per VPN profile with its live one-time code, a countdown ring and a Connect button">
</picture>

[Features](#features) ·
[Install](#install) ·
[Quick start](#quick-start) ·
[Code format](#configuring-the-code-format) ·
[CLI](#command-line) ·
[AI assistants](#use-with-ai-assistants-mcp) ·
[FAQ](#faq) ·
[Security](SECURITY.md) ·
[Türkçe](#türkçe)

</div>

---

## Features

**One-time codes, handled**

- **No more typing codes.** The TOTP secret lives in the macOS Keychain; PassTunnel generates the
  code and sends it with your password when you click Connect. If fewer than 8 seconds are left in
  the current window, it waits for a fresh code instead of racing the clock.
- **Any format your server expects.** Append, prepend, `password:code`, `password,code`, or a custom
  template with any literal text, or send the code separately (OpenVPN static challenge, FortiGate
  OTP field). See [Configuring the code format](#configuring-the-code-format).
- **Authenticator-style main window.** Every profile shows its live code in large digits with a
  countdown ring. Click to copy; the clipboard is cleared again after 30 seconds. Codes can be
  hidden until copied.
- **QR import.** Drop a screenshot of your provider's QR code, choose an image or paste from the
  clipboard. Digits, period and algorithm (SHA-1/256/512) are read from the `otpauth://` link.
  Pasting a Base32 secret or an `otpauth://` link works too.
- **Auto-type (optional, off by default).** With global shortcuts on, ⌃⌥C types the current code into
  the focused field (also in the menu bar menu), for web portals and other places that still ask for it. Needs Accessibility
  permission, which is only requested when you turn the feature on.
- **Confirm with Touch ID (optional, per profile).** Touch ID or your Mac password before connecting,
  or also before showing codes; the saved secrets are then encrypted with a key in the Mac's Secure
  Enclave, so a one-click connect needs you, not just your unlocked Mac.

**VPN client**

- **OpenVPN and FortiGate SSL VPN**, using bundled, signed copies of `openvpn` and `openfortivpn`.
  Nothing else to install.
- **Menu bar badges.** One colored badge per pinned or active profile (letter, icon or both), five
  color palettes, and an alert when a connection drops unexpectedly.
- **Stays connected.** Optional auto-reconnect with backoff, a health check host inside the VPN,
  reconnect after wake, and a reminder before a server-side session limit runs out.
- **Several VPNs at once**, each with its own status, log and settings.
- **Shareable profiles.** Export a `.passtunnel` file for your team. It never contains passwords,
  TOTP secrets or user names.
- **Command-line tool.** `passtunnel connect`, `passtunnel code -c`, `--json` output, stable exit
  codes and shell completions: the same features as the app.
- **Works with AI assistants.** `passtunnel mcp` is an MCP server, so Claude Code, Claude Desktop
  and other MCP clients can check your VPNs, read logs and diagnose problems. Read-only unless
  you allow connecting, and it never hands out passwords, secrets or codes.
- **No sudoers rule, no admin password at every connect.** A small privileged helper, registered
  through macOS's own `SMAppService` and approved once, runs only the VPN tools signed and shipped
  inside the app, with sanitized configurations. See [SECURITY.md](SECURITY.md).
- **English and Turkish** user interface (follows your macOS language).

## How it works

```
PassTunnel.app ──XPC──▶ PassTunnelHelper (root) ──▶ bundled openvpn / openfortivpn
  │  (code-signature checked)                             │
  ├─ Keychain: password + TOTP secret                     └─ management socket (OpenVPN),
  └─ ~/Library/Application Support/PassTunnel                log file, status ──▶ back to the app
```

1. You click **Connect**. The app reads your password and TOTP secret from the Keychain, computes
   the current code and builds what the server expects (for example `secret123456`).
2. The app hands the request to the privileged helper over XPC. The helper accepts only the signed
   PassTunnel app, checks that the profile folder belongs to you, sanitizes the OpenVPN config (or
   writes the openfortivpn config itself from typed fields) and starts the bundled tool, which it
   lets run only after checking the signature of the code that was actually loaded.
3. The app follows the connection state (OpenVPN through a management socket that only your user
   can open, FortiGate through the log) and shows it in the window and the menu bar.

The full security model, including what is *not* protected, is in [SECURITY.md](SECURITY.md). The
code layout is described in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## Install

Requires **macOS 13 Ventura or later** on a Mac with **Apple silicon**.

### Download

Download `PassTunnel-<version>.dmg` from
[GitHub Releases](https://github.com/passtunnel/passtunnel/releases/latest), open it and drag
PassTunnel to **Applications**. Launch it from there: the helper can only be installed from the
Applications folder. The app is signed with a Developer ID and notarized by Apple.

PassTunnel keeps itself up to date (Settings → Updates); updates are signed and checked before
they are installed. After an update, the helper is updated automatically as soon as no VPN
connection is active (only when PassTunnel runs from the Applications folder).

### Homebrew

```sh
brew trust passtunnel/tap
brew install --cask passtunnel/tap/passtunnel
```

Since Homebrew 6, casks from third-party taps load only once you trust the tap, hence the first
line. The cask also links the `passtunnel` command. Updates arrive through the app itself, so
`brew upgrade` leaves it alone unless you run `brew upgrade --greedy`.

### Build from source

You need Xcode 15.3 or later (Swift 5.10, plus `xcstringstool` for the Turkish strings) and
[Homebrew](https://brew.sh), which provides the VPN tools that get bundled into the app:

```sh
brew install openvpn openfortivpn
git clone https://github.com/passtunnel/passtunnel.git
cd passtunnel
scripts/build-app.sh                  # → build/PassTunnel.app (ad-hoc signed)
```

`build-app.sh` builds a release binary, assembles the bundle, copies `openvpn`, `openfortivpn` and
their libraries in (`scripts/bundle-tools.sh`, with their license files), compiles the helper with
the code-signature hashes of exactly these tools and libraries, and signs everything inside-out with
the hardened runtime.

> [!IMPORTANT]
> The helper only talks to an app, and only runs tools, signed with the project's Developer ID Team ID.
> An **ad-hoc build is fine for the window, codes, QR import, profiles and the CLI, but cannot
> connect**. To connect with your own build, set `teamID` in
> [`Sources/PassTunnelShared/Identifiers.swift`](Sources/PassTunnelShared/Identifiers.swift) to your
> Team ID and sign with your certificate:
>
> ```sh
> scripts/build-app.sh --sign "Developer ID Application: Your Name (TEAMID)"
> ```
>
> Then move `build/PassTunnel.app` to `/Applications` before installing the helper.

## Quick start

On first launch PassTunnel walks you through three steps:

1. **Welcome.**
2. **Install the helper.** Click *Install Helper*, then turn PassTunnel on in **System Settings →
   General → Login Items** (macOS asks once). You can also do this later from **Settings → Helper**.
3. **Add your first VPN.**

<p align="center">
  <img src="docs/images/onboarding-helper.png" width="460" alt="Onboarding step: Install the helper">
</p>

### Add a profile

Use the **+** button in the toolbar, or drop a file onto the window:

| You have… | Do this |
|---|---|
| An OpenVPN file (`.ovpn` / `.conf`) | **+ → Import .ovpn…** Files it references (`ca ca.crt`, `tls-auth ta.key 1`, …) are embedded automatically. |
| A FortiGate gateway | **+ → New FortiGate…** Enter host and port, then **Fetch fingerprint** to pin the gateway certificate (SHA-256). |
| A `.passtunnel` file from a colleague | **+ → Import shared profile…** Then add your own user name, password and TOTP secret. |
| A QR code for your authenticator | **+ → Add code from QR…**, or drop the screenshot onto the window or the editor. |

Then open the profile editor (**⋯ → Edit…**):

- **Sign-in:** user name (leave empty to be asked each time) and password: saved in the Keychain,
  asked each time, or none (certificate-only OpenVPN).
- **One-time code:** *Generate* (TOTP), *Ask each time*, or *None*. With *Generate*, scan the QR code
  or paste the secret, and compare the live code with your phone before saving.

<p align="center">
  <img src="docs/images/editor-one-time-code.png" width="580" alt="Profile editor, One-time code section: QR drop z