@theholocron/holocron-plugin-1password 2.0.0-alpha.1 → 2.0.0-alpha.5

package/README.md

@@ -1,8 +1,49 @@
+<!-- editorconfig-checker-disable-file -->
+
 # `@theholocron/holocron-plugin-1password`
 
-1Password plugin for [Holocron](../cli). Implements the **required**
-`vault` capability via shell-out to the `op` CLI
-(<https://developer.1password.com/docs/cli>).
+1Password plugin for [Holocron](../cli). Implements the `vault`
+capability via shell-out to the `op` CLI
+(<https://developer.1password.com/docs/cli>). Also exports
+`verifyToken` + `AUTH_HINT` for use by `holocron auth`.
+
+## One of several vault providers
+
+`vault` is a REQUIRED capability, but 1Password is one of several
+providers you can pick — the capability/provider model is designed
+so you can swap by editing one config line. Peer plugins:
+
+- **[`@theholocron/holocron-plugin-doppler`](../holocron-plugin-doppler)**
+  — REST-transport, Doppler-CLI-managed auth via the OS keychain
+  (`doppler login` → `holocron auth set doppler …`). This repo's
+  own default since `2.0.0-alpha.4`.
+- **`@theholocron/holocron-plugin-infisical`** — planned (see [#97](https://github.com/theholocron/holocron/issues/97)),
+  will use the same REST + keyring shape.
+
+### When to choose 1Password
+
+Reach for this plugin if:
+
+- Your existing personal / team secrets already live in 1Password
+  and adding another vault provider is real friction.
+- You value 1Password's biometric-first UX for laptop workflows
+  over the "REST + keyring" ergonomic set that the other plugins
+  offer.
+- You're comfortable running the `op` CLI on every machine that
+  needs to reach your secrets — including CI, where you'd set
+  `OP_SERVICE_ACCOUNT_TOKEN` instead of the biometric flow.
+
+Reach for one of the REST plugins (Doppler / Infisical) instead
+when you want:
+
+- Zero desktop-app dependency (Doppler-CLI on the laptop still
+  needed; nothing on CI beyond a bearer token).
+- 100% REST transport across every capability call (this plugin
+  shells out per operation).
+- A vault whose API you can reach without unlocking anything.
+
+Both patterns are fully supported — switch by editing
+`holocron.config.json`.
 
 ## Install
 
@@ -10,21 +51,23 @@
 pnpm add -D @theholocron/holocron-plugin-1password@alpha
 ```
 
-Requires the `op` binary on PATH (see [Prerequisite](#prerequisite) below).
+Requires the `op` binary on PATH (see [Prerequisite](#prerequisite)).
 
 ## Why shell-out, not REST
 
 1Password's "REST API" is the **Connect server** — a Docker container
-you have to run yourself (or pay for the cloud-hosted version). For a
-solo / small-team workflow, that's overkill. The `op` CLI is what every
-developer already has installed and uses for hand-debugging anyway, so:
+you have to run yourself (or pay for the cloud-hosted version). For
+a solo / small-team workflow, that's overkill. The `op` CLI is what
+every developer already has installed and uses for hand-debugging
+anyway, so:
 
-- **Local dev:** developer's signed-in `op` CLI (biometric unlock via
-	the desktop app)
-- **CI:** `OP_SERVICE_ACCOUNT_TOKEN` env var; `op` auto-detects it
-- **Either way:** same binary, same commands, same code path
+- **Local dev**: developer's signed-in `op` CLI (biometric unlock
+  via the desktop app).
+- **CI**: `OP_SERVICE_ACCOUNT_TOKEN` env var; `op` auto-detects it.
+- **Either way**: same binary, same commands, same code path.
 
-The plugin's job is just to drive the CLI; auth handling is the CLI's.
+The plugin's job is just to drive the CLI; auth handling is the
+CLI's.
 
 ## Prerequisite
 
@@ -38,6 +81,19 @@ brew install 1password-cli   # macOS
 The plugin throws a clear error at construction time if `op` isn't
 found.
 
+## Auth
+
+This plugin does NOT store a bearer token — the `op` CLI manages
+its own auth via the 1Password desktop app (biometric unlock on
+laptops) or `OP_SERVICE_ACCOUNT_TOKEN` on CI. `holocron auth set
+1password` will accept a token, but since the plugin doesn't read
+the keyring, storing one has no runtime effect. The `AUTH_HINT`
+export makes this explicit in `holocron auth` output.
+
+`holocron auth check 1password` runs `op whoami --format=json` to
+confirm you're signed in — a useful sanity check independent of
+holocron.
+
 ## Config
 
 ```jsonc
@@ -55,27 +111,43 @@ found.
 ```
 
 - `vault` (required) — the 1Password vault name items live in.
-- `account` (optional) — 1P account UUID. Passes `--account <UUID>` on
-	every `op` call so the integration targets a specific account even
-	when the developer has multiple signed in (e.g., work + personal).
-	Find via `op account list`.
+- `account` (optional) — 1P account UUID. Passes `--account <UUID>`
+  on every `op` call so the integration targets a specific account
+  even when the developer has multiple signed in (e.g., work +
+  personal). Find via `op account list`.
 
 ## What's implemented
 
-| Method                  | What it does                                                                                   |
-| ----------------------- | ---------------------------------------------------------------------------------------------- |
-| `read(reference)`       | `op read <reference>` — resolves `op://Vault/Item/field`. `--no-newline`.                      |
-| `write(reference, v)`   | Probe + `op item edit` if exists, else `op item create --category=API Credential`.             |
-| `list()`                | `op item list --vault=<vault> --format=json` — names of items in the vault.                    |
-| `environments()`        | `op environment list --format=json` — names of 1P Environments.                                |
-| `readEnvironment(id)`   | `op environment read <id>` — parses KEY=VALUE lines into a record.                             |
-| `whoami()` (via doctor) | `op whoami --format=json` — tolerates the JSON-shape drift across CLI versions and auth modes. |
+| Method                | What it does                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `read(reference)`     | `op read <reference>` — resolves `op://Vault/Item/field`. `--no-newline`.          |
+| `write(reference, v)` | Probe + `op item edit` if exists, else `op item create --category=API Credential`. |
+| `list()`              | `op item list --vault=<vault> --format=json` — names of items in the vault.        |
+| `environments()`      | `op environment list --format=json` — names of 1P Environments.                    |
+| `readEnvironment(id)` | `op environment read <id>` — parses `KEY=VALUE` lines into a record.               |
+
+Plugin-level exports (not capability methods, per the auth-bootstrap
+convention):
+
+| Export        | Purpose                                                                                                     |
+| ------------- | ----------------------------------------------------------------------------------------------------------- |
+| `verifyToken` | `op whoami --format=json` — token arg ignored (see [Auth](#auth)). Returns `ok: true` when signed in.       |
+| `AUTH_HINT`   | Explains the `op signin` / `OP_SERVICE_ACCOUNT_TOKEN` model to operators — 1P has no bearer token to store. |
+
+### Not implemented (deliberately)
+
+`ensureProject` / `ensureEnvironment` — 1Password's data model
+doesn't have projects with sub-configs the way Doppler / Infisical
+do. The vault + item hierarchy is created via the 1P UI or `op item
+create`, not via `holocron setup`. The methods are simply omitted;
+`runSetup` skips them cleanly (see the [`Vault`
+interface](../cli/src/capabilities/index.ts)).
 
 ## Status
 
-**`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.
-[Release notes](https://github.com/theholocron/holocron/releases/tag/v2.0.0-alpha.0).
-APIs may still shift before stable v2.0.0.
+**`v2.0.0-alpha.1`** (or later — check [releases](https://github.com/theholocron/holocron/releases)).
+Published on npm under the `alpha` dist-tag. APIs may still shift
+before stable v2.0.0.
 
 Implementation note: the stdio shape (`['inherit', 'pipe', 'pipe']`)
 is critical — it gives `op` a TTY signal so it can fire the desktop

package/dist/index.d.mts

@@ -60,6 +60,22 @@ declare class OpVault implements Vault {
   readEnvironment(environmentId: string): Promise<Record<string, string>>;
 }
 //#endregion
+//#region src/verify-token.d.ts
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  spawn?: typeof spawnSync;
+  binary?: string;
+}
+declare function verifyToken(_token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
 //#region src/index.d.ts
 interface OpPluginOptions extends VerifyInput {
   /** 1P vault name items live in. Required. */
@@ -79,5 +95,11 @@ declare function createPlugin(options: OpPluginOptions): {
     vault: () => Vault;
   };
 };
+/**
+ * One-line hint printed by `holocron auth set 1password` — 1P doesn't
+ * store a token in the holocron keyring; the `op` CLI manages its own
+ * auth. Directs the operator to the two paths that actually work.
+ */
+declare const AUTH_HINT: string;
 //#endregion
-export { AuthError, OpPluginOptions, OpShell, OpVault, PluginContext, VerifyInput, createContext, createPlugin, vault, verifyOpInstalled };
+export { AUTH_HINT, AuthError, OpPluginOptions, OpShell, OpVault, PluginContext, VerifyInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, vault, verifyOpInstalled, verifyToken };

package/dist/index.mjs

@@ -211,6 +211,53 @@ var OpShell = class {
 	}
 };
 //#endregion
+//#region src/verify-token.ts
+/**
+* `verifyToken` — plugin-level export used by `holocron auth check`.
+*
+* 1Password doesn't use a bearer token like the REST-transport plugins
+* do — the `op` CLI manages its own auth via desktop-app biometric on
+* laptops and `OP_SERVICE_ACCOUNT_TOKEN` env var in CI. So the token
+* argument is intentionally IGNORED here. What we actually check is:
+* is `op` installed AND signed in (i.e., can it answer `whoami`).
+*
+* If someone tries `holocron auth set 1password <token>`, the token
+* will be stored in the keyring but never read by this plugin — the
+* `AUTH_HINT` below explains that up front.
+*/
+async function verifyToken(_token, opts = {}) {
+	const spawnImpl = opts.spawn ?? spawnSync;
+	const binary = opts.binary ?? "op";
+	const result = spawnImpl(binary, ["whoami", "--format=json"], {
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	if (result.error) return {
+		ok: false,
+		message: `1Password CLI (\`${binary}\`) not found on PATH. Install via \`brew install 1password-cli\`.`
+	};
+	if (result.status !== 0) return {
+		ok: false,
+		message: `\`${binary} whoami\` failed: ${(result.stderr ?? "").trim() || `exit ${result.status ?? "?"}`}`
+	};
+	try {
+		const parsed = JSON.parse(result.stdout ?? "{}");
+		return {
+			ok: true,
+			subject: `op: ${parsed.email ?? parsed.url ?? parsed.user_uuid ?? "signed in"}`
+		};
+	} catch {
+		return {
+			ok: true,
+			subject: "op: signed in"
+		};
+	}
+}
+//#endregion
 //#region src/index.ts
 function createContext(options) {
 	if (!options.vault) throw new Error("@theholocron/holocron-plugin-1password requires `vault` in options");
@@ -237,5 +284,11 @@ function createPlugin(options) {
 		capabilities: { vault: () => vault(ctx) }
 	};
 }
+/**
+* One-line hint printed by `holocron auth set 1password` — 1P doesn't
+* store a token in the holocron keyring; the `op` CLI manages its own
+* auth. Directs the operator to the two paths that actually work.
+*/
+const AUTH_HINT = "1Password uses the `op` CLI for auth — no bearer token to store. On laptop: `op signin` (or the desktop app's biometric flow). In CI: set `OP_SERVICE_ACCOUNT_TOKEN` in the workflow env.";
 //#endregion
-export { AuthError, OpShell, OpVault, createContext, createPlugin, vault, verifyOpInstalled };
+export { AUTH_HINT, AuthError, OpShell, OpVault, createContext, createPlugin, vault, verifyOpInstalled, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-1password",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.5",
   "description": "Holocron plugin for 1Password. Implements the vault capability via shell-out to the `op` CLI (https://developer.1password.com/docs/cli).",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-1password#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -21,7 +21,7 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.1"
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "devDependencies": {
     "@theholocron/tsconfig": "^4.1.0",
@@ -32,7 +32,8 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
     "tsdown": "^0.22.3",
-    "@theholocron/cli": "2.0.0-alpha.1"
+    "tsx": "^4.22.4",
+    "@theholocron/cli": "2.0.0-alpha.5"
   },
   "publishConfig": {
     "access": "public"
@@ -47,7 +48,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
   },
   "types": "./dist/index.d.mts"
 }