feat: Support 1Password Connect server in 1Password plugin (#533)

* Initial plan

* feat: add 1Password Connect server support

Add a new auth mode for self-hosted 1Password Connect servers using
connectHost + connectToken parameters in @initOp(). Uses direct REST
API calls via native fetch - no op CLI or 1Password SDK required.

Includes:
- Connect REST API integration with vault/item/field resolution
- op:// reference parsing for Connect API lookups
- Vault and item ID caching within a session
- New opConnectToken data type
- Clear error for opLoadEnvironment (not supported with Connect)
- Updated README with Connect server documentation
- Changeset for minor version bump

Agent-Logs-Url: https://github.com/dmno-dev/varlock/sessions/6fa88b02-ac93-4548-adfb-94a31cd5ac69

Co-authored-by: theoephraim <1158956+theoephraim@users.noreply.github.com>

* fix: escape double quotes in Connect API filter queries

Prevent potential filter syntax issues if vault/item names contain
double quotes by escaping them before constructing filter expressions.

Agent-Logs-Url: https://github.com/dmno-dev/varlock/sessions/6fa88b02-ac93-4548-adfb-94a31cd5ac69

Co-authored-by: theoephraim <1158956+theoephraim@users.noreply.github.com>

* fix: escape backslashes in Connect API filter queries

Address CodeQL incomplete-sanitization alert by escaping backslashes
before quotes in filter expressions to prevent filter injection.

Agent-Logs-Url: https://github.com/dmno-dev/varlock/sessions/6fa88b02-ac93-4548-adfb-94a31cd5ac69

Co-authored-by: theoephraim <1158956+theoephraim@users.noreply.github.com>

* refactor: prefix Connect-only helper methods/fields with "connect"

Rename private members of OpPluginInstance to make it immediately clear
they are only relevant to the Connect server auth mode:

- vaultIdCache → connectVaultIdCache
- resolveVaultId → connectResolveVaultId
- itemIdCache → connectItemIdCache
- resolveItemId → connectResolveItemId
- extractField → connectExtractField

Agent-Logs-Url: https://github.com/dmno-dev/varlock/sessions/85435a8e-c00e-4d7e-9660-8b6966e6f017

Co-authored-by: theoephraim <1158956+theoephraim@users.noreply.github.com>

* downgrade to patch bump

this is purely additive functionality

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: theoephraim <1158956+theoephraim@users.noreply.github.com>
Co-authored-by: Theo Ephraim <theo@dmno.dev>

Author: Copilot

.changeset/brave-doors-connect.md

@@ -0,0 +1,13 @@
+---
+"@varlock/1password-plugin": patch
+---
+
+Add support for 1Password Connect server (self-hosted)
+
+- New auth mode: `connectHost` + `connectToken` parameters in `@initOp()` for connecting to self-hosted 1Password Connect servers
+- Direct REST API integration — no `op` CLI or 1Password SDK required for Connect server usage
+- New `opConnectToken` data type for Connect server API tokens
+- Parses standard `op://vault/item/[section/]field` references and resolves them via the Connect API
+- Caches vault and item ID lookups within a session for efficiency
+- Clear error when `opLoadEnvironment()` is used with Connect (not supported by the Connect API)
+- Updated error messages and tips to include Connect server as an auth option

packages/plugins/1password/README.md

@@ -8,6 +8,7 @@ This package is a [Varlock](https://varlock.dev) [plugin](https://varlock.dev/gu
 
 - **Service account authentication** for CI/CD and production environments
 - **Desktop app authentication** for local development (with biometric unlock support)
+- **Connect server authentication** for self-hosted 1Password infrastructure
 - **Secret references** using 1Password's standard `op://` format
 - **Bulk-load environments** with `opLoadEnvironment()` via `@setValuesBulk`
 - **Multiple vault support** for different environments and access levels
@@ -89,6 +90,31 @@ When enabled, if the service account token is empty, the plugin will use the des
 Keep in mind that this method connects as _YOU_ who likely has more access than a tightly scoped service account. Consider only enabling this for non-production secrets.
 :::
 
+### Connect server setup (self-hosted)
+
+If you are running a self-hosted [1Password Connect server](https://developer.1password.com/docs/connect/), you can authenticate using a Connect server URL and token:
+
+```env-spec
+# @plugin(@varlock/1password-plugin)
+# @initOp(connectHost="http://connect-server:8080", connectToken=$OP_CONNECT_TOKEN)
+# ---
+
+# @type=opConnectToken @sensitive
+OP_CONNECT_TOKEN=
+```
+
+**Setup requirements:**
+
+1. Deploy a [1Password Connect server](https://developer.1password.com/docs/connect/get-started/)
+2. Create a Connect token with access to the required vault(s)
+3. Set the `OP_CONNECT_TOKEN` environment variable
+
+This method uses the Connect server REST API directly — no `op` CLI or 1Password SDK is required.
+
+:::note
+The `opLoadEnvironment()` function is not supported with Connect server auth. Use `op()` to read individual items instead.
+:::
+
 ### Multiple instances
 
 If you need to connect to multiple accounts or vault configurations, register multiple named instances:
@@ -173,6 +199,8 @@ Initialize a 1Password plugin instance - setting up options and authentication.
 - `token?: string` - Service account token. Should be a reference to a config item of type `opServiceAccountToken`.
 - `allowAppAuth?: boolean` - Enable authenticating using the local desktop app (defaults to `false`)
 - `account?: string` - Limits the `op` CLI to connect to specific 1Password account (shorthand, sign-in address, account ID, or user ID)
+- `connectHost?: string` - URL of a self-hosted 1Password Connect server (e.g., `http://connect-server:8080`)
+- `connectToken?: string` - API token for the Connect server. Should be a reference to a config item of type `opConnectToken`. Required when `connectHost` is set.
 - `id?: string` - Instance identifier for multiple instances (defaults to `_default`)
 
 ### Functions
@@ -203,6 +231,7 @@ Load all variables from a 1Password environment. Intended for use with `@setValu
 ### Data Types
 
 - `opServiceAccountToken` - 1Password service account token (sensitive, validated format)
+- `opConnectToken` - API token for a self-hosted 1Password Connect server (sensitive)
 
 ---
 
@@ -262,6 +291,12 @@ Note that [rate limits](https://developer.1password.com/docs/service-accounts/ra
 - Check that you specified the correct account (run `op account list`)
 - Try running `op whoami` to debug CLI connection
 
+### Connect server errors
+- Verify the Connect server URL is correct and the server is running
+- Check that the Connect token has access to the required vault(s)
+- Ensure the Connect server version supports the vaults and items you're accessing
+- Try accessing `<connectHost>/v1/vaults` directly to verify connectivity
+
 ### Rate limiting
 - Check your account type's rate limits
 - Consider implementing caching or reducing request frequency
@@ -271,6 +306,7 @@ Note that [rate limits](https://developer.1password.com/docs/service-accounts/ra
 
 - [1Password](https://1password.com/)
 - [Service Accounts](https://developer.1password.com/docs/service-accounts/)
+- [1Password Connect](https://developer.1password.com/docs/connect/)
 - [1Password CLI](https://developer.1password.com/docs/cli/)
 - [Secret References](https://developer.1password.com/docs/cli/secret-references/)
 - [Full documentation](https://varlock.dev/plugins/1password/)