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

package/README.md

@@ -1,22 +1,73 @@
+<!-- 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
+
+```bash
+pnpm add -D @theholocron/holocron-plugin-1password@alpha
+```
+
+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
 
@@ -30,40 +81,75 @@ 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
 {
-  "providers": {
-    "vault": ["1password", {
-      "vault": "rando",                                    // 1P vault name
-      "account": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"              // optional: 1P account UUID
-    }]
-  }
+	"providers": {
+		"vault": [
+			"1password",
+			{
+				"vault": "rando", // 1P vault name
+				"account": "ABCDEFGHIJKLMNOPQRSTUVWXYZ", // optional: 1P account UUID
+			},
+		],
+	},
 }
 ```
 
 - `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
 
-**v0.0.0 — first port.** Ports `rando-id/rando.id`
-`adapters/op-cli.ts`. The stdio shape (`['inherit', 'pipe', 'pipe']`)
-is critical: it gives `op` a TTY signal so it can fire the desktop
+**`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
 biometric unlock dialog when running locally. CI runs see no TTY and
 fall back to whatever auth mode the env var configures.

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.0",
+  "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.0"
+    "@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.0"
+    "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"
 }