BitwardenBar

BitwardenBar is a macOS menu bar client for Bitwarden built in Swift. The active implementation lives in the BitwardenBar/ Swift package, which exposes a reusable BitwardenBar library and a thin BitwardenBarStandalone executable that launches the shared AppKit delegate.

This workspace also contains a small Xcode host app, OpenSpec change artifacts, and large upstream Bitwarden reference repos used to confirm protocol details. In normal development, you should expect to edit BitwardenBar/ and treat references/ as documentation.

Workspace Overview

• BitwardenBar/: main app code, Swift package manifest, tests, and the standalone executable target.
• BitwardenBarApp/: thin Xcode host app that embeds the shared BitwardenBar library via @NSApplicationDelegateAdaptor.
• openspec/: capability specs and change artifacts for planned or in-progress work.
• references/clients/: official Bitwarden TypeScript clients for request, response, and protocol verification.
• references/ios/: official Bitwarden iOS codebase for Swift-side modeling and behavior checks.

What The App Does

The current codebase is organized around a menu bar workflow:

• authenticate against Bitwarden using the identity and API services
• support two-step login and session unlock flows
• decrypt and cache vault data locally
• present vault items in a popover UI
• expose app settings, including global shortcut configuration

The app uses:

• AppKit NSStatusItem and NSPopover for the menu bar shell
• SwiftUI for login, unlock, vault, and settings screens
• pure Swift crypto for Bitwarden key derivation and decryption
• GRDB for the local SQLite-backed vault cache
• Keychain and UserDefaults for persisted account and credential state

Quick Start

Requirements

• macOS 13 or newer
• Xcode 26+ with Swift 5.9 toolchain support

Build And Test (Command Line)

From BitwardenBar/:

swift build
swift test

To launch the standalone package executable (no .app bundle):

cd BitwardenBar
swift run BitwardenBarStandalone

Build via Xcode

Open BitwardenBarApp/BitwardenBarApp.xcodeproj in Xcode and run the BitwardenBarApp target. The host app reuses the same BitwardenBarAppDelegate implementation as the standalone executable.

The Xcode project includes an Embed Native Messaging Host build phase that automatically builds BitwardenBrowserHost and BitwardenBrowserHostWrapper via swift build and copies them into .app/Contents/MacOS/. No manual steps are needed.

Packaging for Distribution

The app is distributed unsigned. Users download the .app bundle and run xattr -cr to bypass Gatekeeper.

Command Line (Recommended)

cd BitwardenBarApp
./build-release.sh

This script will:

1. Build the app in Release configuration via xcodebuild
2. Verify that BitwardenBrowserHost and BitwardenBrowserHostWrapper are embedded in the bundle
3. Create a ZIP archive (BitwardenBarApp-YYYYMMDD.zip)

Xcode Archive

1. Xcode → Product → Archive
2. Right-click the archive in Organizer → Show in Finder
3. Copy BitwardenBarApp.app from the archive's Products/Applications/ directory
4. Zip it for distribution: ditto -c -k --keepParent BitwardenBarApp.app BitwardenBarApp.zip

End-User Installation

After downloading the ZIP and extracting:

xattr -cr BitwardenBarApp.app
open BitwardenBarApp.app

The first launch will install native messaging manifests for all detected browsers automatically. No additional configuration is needed.

Browser Integration

BitwardenBar integrates with browser extensions via the native messaging protocol. The app bundles two helper executables:

• BitwardenBrowserHost: the native messaging host that communicates with browser extensions via stdio
• BitwardenBrowserHostWrapper: a thin wrapper around the host for debugging and environment setup

How Path Resolution Works

When the app launches, BrowserManifestInstaller writes manifest JSON files to each browser's NativeMessagingHosts directory. The manifest contains an absolute path pointing to BitwardenBrowserHost inside the running app bundle:

/path/to/BitwardenBarApp.app/Contents/MacOS/BitwardenBrowserHost

The path is resolved automatically at runtime — no manual configuration is needed. If you move the app to a different location, simply relaunch it and the manifests will be updated.

Supported Browsers

• Google Chrome (stable, Beta, Dev, Canary)
• Mozilla Firefox
• Microsoft Edge (stable, Beta, Dev, Canary)
• Chromium
• Vivaldi
• Zen Browser
• Helium

Debug Override

During development, you can override the host binary path with the BWB_BROWSER_HOST_PATH environment variable:

BWB_BROWSER_HOST_PATH=/path/to/BitwardenBrowserHost open BitwardenBarApp.app

The wrapper executable also supports BWB_REAL_BROWSER_HOST_PATH to point to a specific BitwardenBrowserHost binary.

Project Structure

Main Runtime Code

• BitwardenBar/Sources/BitwardenBar/App/: app delegate, menu bar controller, service wiring, app state, and hotkey registration
• BitwardenBar/Sources/BitwardenBar/Core/Auth/: Bitwarden login and token flow
• BitwardenBar/Sources/BitwardenBar/Core/Network/: request building and API communication
• BitwardenBar/Sources/BitwardenBar/Core/Crypto/: key derivation and decryption primitives
• BitwardenBar/Sources/BitwardenBar/Core/Vault/: sync and vault processing
• BitwardenBar/Sources/BitwardenBar/Core/Storage/: account state, keychain, hotkey settings, and cached vault storage
• BitwardenBar/Sources/BitwardenBar/UI/: login, unlock, vault, root, and settings views

Entry Points

• BitwardenBar/Sources/BitwardenBarStandalone/main.swift: standalone executable entry point
• BitwardenBar/Sources/BitwardenBar/App/AppDelegate.swift: shared AppKit lifecycle entry used by both the standalone target and the Xcode host app
• BitwardenBarApp/BitwardenBarApp/BitwardenBarAppApp.swift: thin SwiftUI app wrapper around the shared delegate

Tests

Unit tests live in BitwardenBar/Tests/BitwardenBarTests/ and currently cover core areas such as auth, crypto, cipher handling, TOTP, and hotkey settings.

Development Notes

• The active package product is BitwardenBar; the Xcode host app should stay thin.
• setup.sh exists to clone and patch a vendored sdk-swift copy for reference use. The current app does not depend on that SDK at runtime.
• references/ is intentionally large and should usually be treated as read-only support material.
• openspec/ documents capability specs and change history for features such as desktop auth sessions, global shortcuts, and vault detail presentation.

High-Value Files

• BitwardenBar/Sources/BitwardenBar/App/StatusBarController.swift: popover lifecycle and menu bar behavior
• BitwardenBar/Sources/BitwardenBar/App/ServiceContainer.swift: application wiring and service construction
• BitwardenBar/Sources/BitwardenBar/Core/Auth/AuthService.swift: login, token, and profile flow
• BitwardenBar/Sources/BitwardenBar/Core/Crypto/BWCrypto.swift: Bitwarden cryptography primitives
• BitwardenBar/Sources/BitwardenBar/Core/Vault/SyncService.swift: vault sync and decryption pipeline
• BitwardenBar/Sources/BitwardenBar/UI/Auth/LoginView.swift: login and two-factor UI flow
• BitwardenBar/Sources/BitwardenBar/UI/Vault/VaultRootView.swift: top-level vault presentation

Suggested Workflow

1. Make changes in BitwardenBar/ first.
2. Use swift build or swift test from BitwardenBar/ for quick validation.
3. Cross-check protocol-sensitive changes against references/clients/ and references/ios/ before changing auth or crypto behavior.
4. Update or consult openspec/ when a change affects documented capabilities or active work items.

Acknowledgements

BitwardenBar references and draws inspiration from the following official Bitwarden open source projects:

• bitwarden/ios — official Bitwarden iOS client, used as reference for Swift-side modeling and behavior.
• bitwarden/clients — official Bitwarden TypeScript clients, used for request, response, and protocol verification.

License

This project is licensed under the GNU General Public License v3.0.