Biometric Unlock for CLI

[jeanregisser]

Select Topic Area

✅ Code Contribution Proposal

Code Contribution Proposal

TL;DR: I want to add Touch ID support to CLI. Two approaches proposed: (A) keychain storage or (B) desktop app IPC. Seeking feedback on best approach before coding. Ready to contribute!

Background

There's significant community interest in adding biometric unlock support to the Bitwarden CLI:

• Community request: Biometric unlock for CLI (2021)
• Feature request: Get password from keychain with Touch ID (2023)
• Discussion: Biometric unlock in CLI not working (2024)

Users currently work around this with unofficial scripts that store credentials in platform keychains, but these lack official support and have unclear security models.

I'm interested in contributing this feature and would like community/team feedback on the implementation approach before writing code.

Current State

Today, biometric unlock works great for:

• ✅ Desktop app (Touch ID on macOS, Windows Hello, etc.)
• ✅ Browser extensions (via native messaging IPC to desktop app)
• ❌ CLI (requires master password or manual $BW_SESSION management)

The CLI's session model is well-designed (locked by default, explicit unlock, session tokens), but lacks the convenience of biometric auth that other clients enjoy.

Use Cases

Primary use case: CLI power users who:

• Run bw commands frequently in their terminal workflow
• Already use Touch ID for desktop/browser
• Want secure but frictionless CLI access

Example workflow:

# Today: type master password
bw unlock
# Enter master password: ********

# Proposed: Interactive with auto-detection
bw unlock
# Biometric unlock available. How would you like to unlock?
# > Use Touch ID
#   Use master password
# 👆 Touch ID sensor...
# Vault unlocked!

# Or explicit flag
bw unlock --biometric

Proposed Implementation

I've researched the desktop app's biometric implementation and see two viable approaches:

Option A: Self-Contained Keychain Storage

How it works:

1. CLI stores BW_SESSION token in platform secure storage (macOS Keychain, Windows Credential Manager, etc.)
2. Storage is protected by kSecAccessControlUserPresence (macOS) or equivalent
3. Every access triggers OS biometric prompt
4. CLI retrieves token and uses it normally

Implementation details (macOS):

// Approach 1: Shell out to 'security' command (simpler, but limited)
import { exec } from "child_process";
import { promisify } from "util";
const execAsync = promisify(exec);

async function storeBiometricSession(sessionToken: string, userId: string) {
  // Note: security CLI doesn't support kSecAccessControlUserPresence
  // This only requires system authentication (password or Touch ID if system-wide enabled)
  await execAsync(
    `security add-generic-password -a "${userId}" -s "com.bitwarden.cli" ` +
      `-w "${sessionToken}" -T "" -U`
  );
}

async function getBiometricSession(userId: string): Promise<string> {
  // Triggers system authentication prompt (not guaranteed to be Touch ID)
  const { stdout } = await execAsync(
    `security find-generic-password -a "${userId}" -s "com.bitwarden.cli" -w`
  );
  return stdout.trim();
}

// Approach 2: NAPI module (required for true Touch ID enforcement)
// Using Rust with security-framework crate to set kSecAccessControlUserPresence
// (Would require native build setup similar to desktop app)

Pros:

• Self-contained, no desktop app dependency
• Works offline
• Simple security model: OS handles biometric verification
• Natural fit with existing CLI session management

Cons:

• Platform-specific code needed (macOS, Windows, Linux)
• Separate biometric setup from desktop app
• Stores session token (not UserKey like desktop app)

Option B: Desktop App IPC Integration

How it works:

1. CLI connects to desktop app's existing native messaging socket
2. Sends UnlockWithBiometricsForUser command (same as browser extension)
3. Desktop app shows Touch ID prompt, returns UserKey
4. CLI derives session from UserKey

Implementation details:

• Connect to Unix domain socket at ~/Library/Caches/com.bitwarden.desktop/s.bw (or App Group path if sandboxed)
• Implement RSA key exchange + AES encryption (existing protocol)
• Reuse desktop app's biometric infrastructure

Pros:

• Consistent with browser extension approach
• Reuses desktop app's biometric setup and UserKey storage
• Single source of truth for biometric config

Cons:

• Requires desktop app running
• More complex implementation (IPC protocol, encryption)
• Tighter coupling between CLI and desktop app
• UserKey → session conversion needed

User Experience Mockup

Setup Flow

$ bw config biometric-unlock true
✓ Biometric unlock enabled for this device

To complete setup, unlock once with your master password:
$ bw unlock
? Master password: ********
✓ Vault unlocked
✓ Biometric unlock configured

# Future unlocks will use Touch ID

Usage Flow

Interactive (auto-detects biometric availability):

$ bw unlock
? How would you like to unlock?
  > Use Touch ID (recommended)
    Use master password
👆 Touch ID sensor...
✓ Vault unlocked
Your session key: abc123...

# Note: Option B (desktop IPC) would show:
# "Use Touch ID via Desktop App (requires desktop app running)"

Explicit flag:

$ bw unlock --biometric
👆 Touch ID sensor to unlock vault...
✓ Vault unlocked

# Falls back gracefully if unavailable
$ bw unlock --biometric
⚠ Biometric unlock not available
? Master password: ********

Management

# Enable/disable
$ bw config biometric-unlock true|false

# Check status
$ bw config biometric-status
✓ Biometric unlock: Enabled, Touch ID: Available

Security Considerations

What's stored:

• Option A: BW_SESSION token (time-limited, revocable)
• Option B: Nothing (uses desktop app's stored UserKey)

Threat model:

• ✅ Protected from: Malware reading token, physical access without biometric
• ❌ Not protected from: Authorized user with valid biometric, root/admin access
• Similar to: Desktop app's current biometric model

Session lifecycle:

• Session tokens expire per vault timeout settings
• bw lock clears session (keeps biometric config)
• bw logout removes everything including biometric setup
• Re-setup required after master password change

Platform security:

• macOS: Keychain with kSecAccessControlUserPresence
• Windows: Credential Manager with CRED_TYPE_GENERIC + Windows Hello
• Linux: Secret Service with prompt requirement (polkit)

Implementation Plan

Initial focus: macOS (can expand to other platforms later, or accept community contributions)

Example plan for Option A (would adjust based on chosen approach):

1. Implement keychain access (shell out to security command or create NAPI module)
2. Implement bw config biometric-unlock setup
3. Add interactive unlock prompt with biometric option
4. Add --biometric flag
5. Store/retrieve session token from Keychain with access controls
6. Handle Touch ID prompts and error cases
7. Add tests and documentation

Future expansion (community contributions welcome):

• Windows: Credential Manager + Windows Hello
• Linux: Secret Service + polkit/prompt

Important note on implementation: The security command-line tool does not support setting kSecAccessControlUserPresence directly. Shelling out to security only provides system authentication (which may or may not use Touch ID depending on system settings). For true Touch ID enforcement, would need to create a small NAPI module using the Rust security-framework crate (like the desktop app does).

References & Prior Art

Similar features in other tools:

• 1Password CLI: Integrates with desktop app for biometric unlock (Touch ID, Windows Hello)
• GitHub CLI: OAuth token storage in system keychain

Bitwarden codebase references:

• Desktop app macOS biometric: os-biometrics-mac.service.ts
• Native messaging protocol: biometric-message-handler.service.ts
• CLI session management: unlock.command.ts

Community workarounds:

• Keychain wrapper gist

Feedback Requested

I'm ready to start implementing this, but want to ensure the approach aligns with Bitwarden's security philosophy, CLI architecture, and community needs.

Key questions:

1. Architecture preference: Option A (self-contained keychain) vs Option B (desktop IPC)?
2. For Option A: Shell out to security command or create NAPI module? Acceptable to add native dependencies?
3. Security: Any concerns with storing session tokens in platform keychains?
4. Scope: CLI-native code or separate wrapper tool?
5. UX: Preferences on interactive prompts vs explicit flags?
6. PR review: What would make this easiest to review and merge?

Looking forward to your feedback! Happy to iterate on this design before diving into implementation.

[github-actions[bot]]

✨ Thank you for your code contribution proposal! While the Bitwarden team reviews your submission, we encourage you to check out our contribution guidelines.

Please ensure that your code contribution includes a detailed description of what you would like to contribute, along with any relevant screenshots and links to existing feature requests. This information helps us gather feedback from the community and Bitwarden team members before you start writing code.

To keep discussions focused, posts that do not include a proposal for a code contribution will be removed.

• 💡 For feature requests and general discussion, please visit the Bitwarden Community Forums.
• ℹ️ For questions and support, visit the Bitwarden Help Center.
• 🐛 To report a potential bug, please visit the corresponding repo. Server | Clients | iOS | Android

Thank you for contributing to Bitwarden!