feat(bitwarden): add Bitwarden Password Manager / Vaultwarden support via bw CLI

.changeset/bitwarden-password-manager-vaultwarden.md

@@ -0,0 +1,12 @@
+---
+"@varlock/bitwarden-plugin": minor
+---
+
+Add Bitwarden Password Manager and Vaultwarden support via the `bw` CLI.
+
+New additions:
+- `@initBwp()` root decorator — initializes a Password Manager instance using a `bw unlock` session token
+- `bwp()` resolver function — fetches any field (password, username, notes, totp, uri, or custom field) from a vault item by name or UUID
+- `bwSessionToken` data type — sensitive type for the `bw` CLI session token
+
+This enables local-development use of Bitwarden Password Manager and self-hosted Vaultwarden vaults, which do not support machine accounts.

packages/plugins/bitwarden/README.md

@@ -2,16 +2,30 @@
 
 [![npm version](https://img.shields.io/npm/v/@varlock/bitwarden-plugin.svg)](https://www.npmjs.com/package/@varlock/bitwarden-plugin) [![GitHub stars](https://img.shields.io/github/stars/dmno-dev/varlock.svg?style=social&label=Star)](https://github.com/dmno-dev/varlock) [![license](https://img.shields.io/npm/l/@varlock/bitwarden-plugin.svg)](https://github.com/dmno-dev/varlock/blob/main/LICENSE)
 
-This package is a [Varlock](https://varlock.dev) [plugin](https://varlock.dev/guides/plugins/) that enables loading data from [Bitwarden Secrets Manager](https://bitwarden.com/products/secrets-manager/) into your configuration.
+This package is a [Varlock](https://varlock.dev) [plugin](https://varlock.dev/guides/plugins/) that enables loading data from **Bitwarden** into your configuration.
+
+It supports two distinct Bitwarden products:
+
+| Feature | Bitwarden Secrets Manager | Bitwarden Password Manager / Vaultwarden |
+|---------|--------------------------|------------------------------------------|
+| Auth    | Machine account access token (`BWS_ACCESS_TOKEN`) | CLI session token (`bw unlock`) |
+| Access  | REST API (no CLI needed) | `bw` CLI required |
+| Ideal for | Production / CI environments | Local development |
+| Vaultwarden support | ✗ (Vaultwarden does not offer Secrets Manager) | ✓ |
 
 ## Features
 
+**Secrets Manager (existing)**
 - **Zero-config authentication** - Just provide your machine account access token
 - **UUID-based secret access** - Fetch secrets by their unique identifiers
-- **Organization support** - Optional organization ID for filtering and management
 - **Self-hosted Bitwarden support** - Configure custom API and identity URLs
 - **Multiple instances** - Connect to different organizations or self-hosted instances
-- **Comprehensive error handling** with helpful tips
+
+**Password Manager / Vaultwarden (new)**
+- **CLI-based access** via the official `bw` CLI tool
+- **Fetch any field** - password, username, notes, TOTP, URI, or custom fields
+- **Vaultwarden support** - Works with any Bitwarden-compatible server
+- **Multiple instances** - Connect to different vaults
 
 ## Installation
 
@@ -31,11 +45,17 @@ Otherwise just set the explicit version number when you register it
 
 See our [Plugin Guide](https://varlock.dev/guides/plugins/#installation) for more details.
 
-## Setup + Auth
+---
+
+## Bitwarden Secrets Manager
+
+The Secrets Manager integration uses a machine account access token and communicates directly with the Bitwarden API — no CLI required.
+
+### Setup + Auth
 
 After registering the plugin, you must initialize it with the `@initBitwarden` root decorator.
 
-### Basic Setup
+#### Basic Setup
 
 For most use cases, you only need to provide the access token:
 
@@ -55,7 +75,7 @@ BITWARDEN_ACCESS_TOKEN=
 3. Copy the **Access token** (displayed only once!)
 4. Grant the machine account access to the secrets or projects you need
 
-### Self-hosted
+#### Self-hosted
 
 For self-hosted Bitwarden instances, you'll need to provide both URLs:
 
@@ -70,7 +90,7 @@ For self-hosted Bitwarden instances, you'll need to provide both URLs:
 - `apiUrl` - API URL for your self-hosted instance (e.g., "https://bitwarden.yourcompany.com/api")
 - `identityUrl` - Identity service URL for your self-hosted instance (e.g., "https://bitwarden.yourcompany.com/identity")
 
-### Multiple instances
+#### Multiple instances
 
 If you need to connect to multiple organizations or instances, register multiple named instances:
 
@@ -79,7 +99,7 @@ If you need to connect to multiple organizations or instances, register multiple
 # @initBitwarden(id=dev, accessToken=$DEV_ACCESS_TOKEN)
 ```
 
-## Reading secrets
+### Reading secrets
 
 This plugin introduces the `bitwarden()` function to fetch secret values.
 
@@ -110,13 +130,118 @@ To find a secret's UUID:
 
 ---
 
+## Bitwarden Password Manager / Vaultwarden
+
+The Password Manager integration uses the official `bw` CLI tool.  This makes it easy to use with **Vaultwarden** (the open-source self-hosted alternative) and regular Bitwarden password vault accounts, which do not have machine accounts.
+
+> **Note:** Because this relies on the `bw` CLI and an interactive session token it is primarily intended for **local development**. For production/CI use, prefer Bitwarden Secrets Manager (above) or another provider that supports non-interactive machine authentication.
+
+### Prerequisites
+
+Install the [Bitwarden CLI](https://bitwarden.com/help/cli/):
+
+```bash
+# macOS
+brew install bitwarden-cli
+
+# Linux (snap)
+snap install bw
+
+# Windows
+choco install bitwarden-cli
+```
+
+#### Vaultwarden / self-hosted server
+
+Point the CLI at your self-hosted server before logging in:
+
+```bash
+bw config server https://vaultwarden.yourcompany.com
+```
+
+### Setup + Auth
+
+1. **Log in** (one-time setup):
+
+   ```bash
+   bw login
+   ```
+
+2. **Unlock** your vault and capture the session token:
+
+   ```bash
+   export BWP_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)
+   ```
+
+   Or unlock interactively and copy the token:
+
+   ```bash
+   bw unlock
+   # copy the export line it prints, e.g.:
+   # export BW_SESSION="<token>"
+   ```
+
+3. **Configure** the plugin:
+
+```env-spec title=".env.schema"
+# @plugin(@varlock/bitwarden-plugin)
+# @initBwp(sessionToken=$BWP_SESSION)
+# ---
+
+# @type=bwSessionToken @sensitive
+BWP_SESSION=
+```
+
+### Reading items
+
+Use the `bwp()` function to fetch values from your vault:
+
+```env-spec title=".env.schema"
+# @plugin(@varlock/bitwarden-plugin)
+# @initBwp(sessionToken=$BWP_SESSION)
+# ---
+
+# @type=bwSessionToken @sensitive
+BWP_SESSION=
+
+# Fetch the password field (default)
+DATABASE_URL=bwp("My Database Item")
+
+# Fetch specific fields
+DB_USER=bwp("My Database Item", field="username")
+DB_NOTES=bwp("My Database Item", field="notes")
+DB_TOTP=bwp("My Database Item", field="totp")
+DB_URI=bwp("My Database Item", field="uri")
+
+# Fetch a custom field
+API_KEY=bwp("API Keys", field="production_api_key")
+```
+
+You can also use the item's UUID instead of its name:
+
+```env-spec
+DATABASE_URL=bwp("12345678-1234-1234-1234-123456789abc")
+```
+
+### Multiple instances
+
+```env-spec
+# @initBwp(id=work, sessionToken=$BWP_WORK_SESSION)
+# @initBwp(id=personal, sessionToken=$BWP_PERSONAL_SESSION)
+
+WORK_SECRET=bwp(work, "Work Item")
+PERSONAL_SECRET=bwp(personal, "Personal Item")
+```
+
+---
+
 ## Reference
 
 ### Root decorators
 
 #### `@initBitwarden()`
 
-Initialize a Bitwarden Secrets Manager plugin instance.
+Initialize a Bitwarden **Secrets Manager** plugin instance.
 
 **Parameters:**
 
@@ -125,11 +250,20 @@ Initialize a Bitwarden Secrets Manager plugin instance.
 - `identityUrl?: string` - Identity service URL for self-hosted Bitwarden (defaults to `https://identity.bitwarden.com`)
 - `id?: string` - Instance identifier for multiple instances (defaults to `_default`)
 
+#### `@initBwp()`
+
+Initialize a Bitwarden **Password Manager / Vaultwarden** plugin instance (uses the `bw` CLI).
+
+**Parameters:**
+
+- `sessionToken: string` (required) - CLI session token from `bw unlock`
+- `id?: string` - Instance identifier for multiple instances (defaults to `_default`)
+
 ### Functions
 
 #### `bitwarden()`
 
-Fetch a secret from Bitwarden Secrets Manager.
+Fetch a secret from Bitwarden **Secrets Manager**.
 
 **Signatures:**
 
@@ -140,85 +274,75 @@ Fetch a secret from Bitwarden Secrets Manager.
 
 - Must be a valid UUID: `"12345678-1234-1234-1234-123456789abc"`
 
-### Data Types
+#### `bwp()`
 
-- `bitwardenAccessToken` - Machine account access token (sensitive)
-- `bitwardenSecretId` - Secret UUID (validated format)
-- `bitwardenOrganizationId` - Organization UUID (validated format)
-
----
-
-## Bitwarden Setup
-
-### Create a Machine Account
-
-Machine accounts provide programmatic access to Bitwarden Secrets Manager.
-
-**Using the Web Vault:**
-
-1. Log in to your Bitwarden organization
-2. Navigate to **Secrets Manager** → **Machine accounts**
-3. Click **New machine account**
-4. Provide a name (e.g., "Production App")
-5. Copy the **Access token** (shown only once!)
-6. Grant access to specific projects or secrets
-
-**Permission Levels:**
-
-- **Can read** - Retrieve secrets only
-- **Can read, write** - Retrieve, create, and edit secrets
-
-**Important:** Store the access token securely - it will only be displayed once!
+Fetch a field value from a Bitwarden **Password Manager / Vaultwarden** vault item via the `bw` CLI.
 
-### Grant Access to Secrets
-
-**Via Projects:**
+**Signatures:**
 
-1. Create or select a project in Secrets Manager
-2. Add secrets to the project
-3. Grant your machine account access to the project
+- `bwp("item")` - Fetch the `password` field of the named item (default instance)
+- `bwp("item", field="username")` - Fetch a specific field (default instance)
+- `bwp(instanceId, "item")` - Use a named instance
+- `bwp(instanceId, "item", field="notes")` - Named instance + specific field
 
-**Direct Secret Access:**
+**Supported fields:**
 
-1. Navigate to a specific secret
-2. Click **Access**
-3. Add your machine account with appropriate permissions
+- `password` (default) - Login password
+- `username` - Login username
+- `notes` - Secure notes
+- `totp` - TOTP secret / code
+- `uri` - First URI in the login entry
+- Any custom field name - Matches case-insensitively against the item's custom fields
 
-### Find Your Organization ID
+### Data Types
 
-```bash
-# Via Bitwarden CLI
-bw org list
+- `bitwardenAccessToken` - Secrets Manager machine account access token (sensitive)
+- `bitwardenSecretId` - Secret UUID (validated format)
+- `bitwardenOrganizationId` - Organization UUID (validated format)
+- `bwSessionToken` - Bitwarden CLI session token from `bw unlock` (sensitive)
 
-# Or check your organization's URL
-https://vault.bitwarden.com/#/organizations/{organization-id}
-```
+---
 
 ## Troubleshooting
 
-### Secret not found
+### Secret not found (Secrets Manager)
 - Verify the secret UUID is correct (must be valid UUID format)
 - Check that the secret exists in your Bitwarden Secrets Manager
 - Ensure your machine account has access to the secret or its project
 
-### Permission denied
+### Permission denied (Secrets Manager)
 - Verify your machine account has "Can read" or "Can read, write" permissions
 - Check that the machine account has access to the specific secret
 - Review the access settings in Bitwarden Secrets Manager console
 
-### Authentication failed
+### Authentication failed (Secrets Manager)
 - Verify the access token is correct
 - Check if the access token has been revoked or expired
 - Ensure the machine account is not disabled
 - For self-hosted: verify apiUrl and identityUrl are correct
 
-### Invalid UUID format
+### Invalid UUID format (Secrets Manager)
 - Secret IDs must be valid UUIDs: `12345678-1234-1234-1234-123456789abc`
 - Check for typos or incorrect format
 - UUIDs should contain 32 hexadecimal characters and 4 hyphens
 
+### `bw` CLI not found (Password Manager)
+- Install the Bitwarden CLI: https://bitwarden.com/help/cli/
+- Ensure `bw` is available in your `$PATH`
+
+### Session invalid or expired (Password Manager)
+- Run `bw unlock` again to get a fresh session token
+- Update your `BWP_SESSION` (or whichever env var you use) with the new token
+
+### Item not found (Password Manager)
+- Verify the item name matches exactly (or use its UUID)
+- Run `bw list items` to see all items in your vault
+- Make sure your vault is synced: `bw sync`
+
 ## Resources
 
 - [Bitwarden Secrets Manager](https://bitwarden.com/products/secrets-manager/)
 - [Machine Accounts Documentation](https://bitwarden.com/help/machine-accounts/)
+- [Bitwarden CLI](https://bitwarden.com/help/cli/)
+- [Vaultwarden (self-hosted)](https://github.com/dani-garcia/vaultwarden)
 - [Self-Hosting Bitwarden](https://bitwarden.com/help/manage-your-secrets-org/#self-hosting)