@graphorin/secret-1password 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @graphorin/secret-1password
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release of the reference 1Password secret-resolver adapter for the
+  Graphorin framework. Registers the `op://` scheme on top of the
+  `@graphorin/security` resolver registry, shells out to the official
+  1Password CLI, and serves as the canonical template community packages
+  should follow when wiring HashiCorp Vault, AWS Secrets Manager, GCP
+  Secret Manager, Azure Key Vault, Bitwarden, or Unix `pass`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @graphorin/secret-1password
+
+> Reference 1Password secret-resolver adapter for the
+> [Graphorin](https://github.com/o-stepper/graphorin) framework.
+> Registers the `op://` scheme on top of `@graphorin/security`'s
+> pluggable `SecretResolver` registry by shelling out to the official
+> 1Password CLI (`op read 'op://<vault>/<item>/<field>'`).
+>
+> Project Graphorin · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko ·
+> <https://github.com/o-stepper/graphorin>
+
+---
+
+## Status
+
+- **Published:** v0.5.0 (optional sub-pack)
+- Reference adapter — community packages should follow this template
+  when wiring HashiCorp Vault, AWS Secrets Manager, GCP Secret
+  Manager, Azure Key Vault, Bitwarden, or Unix `pass`.
+
+---
+
+## Install
+
+```bash
+pnpm add @graphorin/secret-1password
+```
+
+The package shells out to the **system** `op` binary; install it from
+[1Password's official CLI distribution](https://developer.1password.com/docs/cli/get-started/).
+The package does NOT bundle the CLI — the operator chooses how it is
+provisioned (homebrew, scoop, apt, official tarball, k8s init
+container, etc.).
+
+---
+
+## Usage
+
+### Local interactive mode
+
+Sign in to 1Password once via `eval $(op signin)`; the resolver picks
+up the cached session token from your shell.
+
+```ts
+import { registerResolver, resolveSecret } from '@graphorin/security';
+import { onePasswordResolver } from '@graphorin/secret-1password';
+
+registerResolver(onePasswordResolver);
+
+const apiKey = await resolveSecret('op://Personal/OpenAI/api-key');
+await apiKey.use((raw) => callOpenAI(raw));
+```
+
+### Headless / CI mode
+
+Use a [1Password Service Account](https://developer.1password.com/docs/service-accounts/)
+token. The resolver forwards it via `OP_SERVICE_ACCOUNT_TOKEN`:
+
+```ts
+import { createOnePasswordResolver } from '@graphorin/secret-1password';
+
+registerResolver(
+  createOnePasswordResolver({
+    serviceAccountToken: process.env.OP_SERVICE_ACCOUNT_TOKEN!,
+    timeoutMs: 10_000,
+  }),
+);
+```
+
+### 1Password Connect
+
+For self-hosted Connect deployments:
+
+```ts
+registerResolver(
+  createOnePasswordResolver({
+    connect: {
+      host: process.env.OP_CONNECT_HOST!,
+      token: process.env.OP_CONNECT_TOKEN!,
+    },
+  }),
+);
+```
+
+### Multiple accounts
+
+Pass `--account` through:
+
+```ts
+registerResolver(
+  createOnePasswordResolver({
+    account: 'team-graphorin.1password.com',
+  }),
+);
+```
+
+---
+
+## URI format
+
+`op://<vault>/<item>/[section/]<field>`
+
+Per 1Password, vault / item / field names are case-insensitive. The
+resolver lowercases the URI before forwarding to the CLI; pass
+`preserveCase: true` to opt out.
+
+Examples:
+
+```text
+op://Personal/OpenAI/api-key
+op://Production/Stripe/credentials/live-secret-key
+op://Engineering/Postgres/section/connection-string
+```
+
+---
+
+## Error handling
+
+Every error surfaces as a typed `OpCliError` with a `kind` field and
+an actionable hint:
+
+| `kind`                  | When it fires                                              | Hint                                                                                            |
+|-------------------------|------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| `binary-missing`        | `op` not on PATH.                                          | Install the 1Password CLI.                                                                      |
+| `signed-out`            | `op` reports "not signed in" or session expired.           | Run `eval $(op signin)` (interactive) or set `OP_SERVICE_ACCOUNT_TOKEN` (headless).             |
+| `reference-not-found`   | The vault / item / field does not exist.                   | Verify with `op item get <item> --vault <vault>`.                                               |
+| `timeout`               | The CLI did not return within the timeout.                 | Increase `timeoutMs` or check 1Password connectivity.                                           |
+| `unknown`               | Any other non-zero exit code.                              | Inspect the captured stderr.                                                                    |
+
+The resolver wraps `OpCliError` in `SecretResolutionError` (the
+canonical `@graphorin/security` error) so existing `catch` paths in
+agent code keep working.
+
+---
+
+## Template for community resolvers
+
+The package is intentionally tiny (~170 LOC). The structure is the
+canonical template community packages should follow when wiring
+HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key
+Vault, Bitwarden, or Unix `pass`:
+
+1. Build a `<Tool>Cli` interface that captures the upstream tool's
+   surface (read / list / health-check); ship a default
+   implementation that spawns the binary or calls the SDK.
+2. Build a `create<Tool>Resolver(options)` factory that returns a
+   `SecretResolver` honouring the upstream URI scheme.
+3. Validate the URI shape locally; the upstream tool is the source of
+   truth for the actual lookup.
+4. Wrap upstream errors in `SecretResolutionError` so existing `catch`
+   paths keep working.
+5. Test with a stub `<Tool>Cli` — never reach the network or the
+   real binary in CI.
+
+---
+
+## Related decisions
+
+- ADR-026 — `SecretValue` and `SecretsStore` end-to-end contract.
+- ADR-028 — `SecretRef` URI scheme (`env:` / `keyring:` / `file:` / `encrypted-file:` / `op://` / `vault://` / `ref:`).
+
+---
+
+## License
+
+MIT © 2026 Oleksiy Stepurenko
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { OpCli, OpCliError, OpCliErrorKind, OpCliReadOptions, OpCliReadResult, createDefaultOpCli, createOpCli } from "./op-cli.js";
+import { OnePasswordResolverOptions, createOnePasswordResolver, normalizeOpUri, onePasswordResolver } from "./resolver.js";
+
+//#region src/index.d.ts
+
+/**
+ * @graphorin/secret-1password — reference 1Password secret-resolver
+ * adapter for the Graphorin framework.
+ *
+ * Registers the `op://` scheme on top of `@graphorin/security`'s
+ * pluggable `SecretResolver` registry by shelling out to the official
+ * 1Password CLI:
+ *
+ * ```ts
+ * import { registerResolver } from '@graphorin/security';
+ * import { onePasswordResolver } from '@graphorin/secret-1password';
+ *
+ * registerResolver(onePasswordResolver);
+ *
+ * // Anywhere downstream:
+ * const apiKey = await resolveSecret('op://Personal/OpenAI/api-key');
+ * ```
+ *
+ * The adapter is also the canonical template community packages
+ * should follow when wiring HashiCorp Vault, AWS Secrets Manager, GCP
+ * Secret Manager, Azure Key Vault, Bitwarden, or Unix `pass` as
+ * additional `SecretResolver` implementations.
+ *
+ * @packageDocumentation
+ */
+/** Canonical version constant. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+//#endregion
+export { type OnePasswordResolverOptions, type OpCli, OpCliError, type OpCliErrorKind, type OpCliReadOptions, type OpCliReadResult, VERSION, createDefaultOpCli, createOnePasswordResolver, createOpCli, normalizeOpUri, onePasswordResolver };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AA2BA;;;;;;;;;;;;;;;;;;;;;;cAAa,OAAA"}

package/dist/index.js

@@ -0,0 +1,35 @@
+import { OpCliError, createDefaultOpCli, createOpCli } from "./op-cli.js";
+import { createOnePasswordResolver, normalizeOpUri, onePasswordResolver } from "./resolver.js";
+
+//#region src/index.ts
+/**
+* @graphorin/secret-1password — reference 1Password secret-resolver
+* adapter for the Graphorin framework.
+*
+* Registers the `op://` scheme on top of `@graphorin/security`'s
+* pluggable `SecretResolver` registry by shelling out to the official
+* 1Password CLI:
+*
+* ```ts
+* import { registerResolver } from '@graphorin/security';
+* import { onePasswordResolver } from '@graphorin/secret-1password';
+*
+* registerResolver(onePasswordResolver);
+*
+* // Anywhere downstream:
+* const apiKey = await resolveSecret('op://Personal/OpenAI/api-key');
+* ```
+*
+* The adapter is also the canonical template community packages
+* should follow when wiring HashiCorp Vault, AWS Secrets Manager, GCP
+* Secret Manager, Azure Key Vault, Bitwarden, or Unix `pass` as
+* additional `SecretResolver` implementations.
+*
+* @packageDocumentation
+*/
+/** Canonical version constant. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { OpCliError, VERSION, createDefaultOpCli, createOnePasswordResolver, createOpCli, normalizeOpUri, onePasswordResolver };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @graphorin/secret-1password — reference 1Password secret-resolver\n * adapter for the Graphorin framework.\n *\n * Registers the `op://` scheme on top of `@graphorin/security`'s\n * pluggable `SecretResolver` registry by shelling out to the official\n * 1Password CLI:\n *\n * ```ts\n * import { registerResolver } from '@graphorin/security';\n * import { onePasswordResolver } from '@graphorin/secret-1password';\n *\n * registerResolver(onePasswordResolver);\n *\n * // Anywhere downstream:\n * const apiKey = await resolveSecret('op://Personal/OpenAI/api-key');\n * ```\n *\n * The adapter is also the canonical template community packages\n * should follow when wiring HashiCorp Vault, AWS Secrets Manager, GCP\n * Secret Manager, Azure Key Vault, Bitwarden, or Unix `pass` as\n * additional `SecretResolver` implementations.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.5.0';\n\nexport {\n  createDefaultOpCli,\n  createOpCli,\n  type OpCli,\n  OpCliError,\n  type OpCliErrorKind,\n  type OpCliReadOptions,\n  type OpCliReadResult,\n} from './op-cli.js';\nexport {\n  createOnePasswordResolver,\n  normalizeOpUri,\n  type OnePasswordResolverOptions,\n  onePasswordResolver,\n} from './resolver.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,MAAa,UAAU"}

package/dist/op-cli.d.ts

@@ -0,0 +1,93 @@
+import { spawn } from "node:child_process";
+
+//#region src/op-cli.d.ts
+
+/** @stable */
+interface OpCliReadResult {
+  readonly value: string;
+  readonly exitCode: number;
+  readonly durationMs: number;
+}
+/** @stable */
+interface OpCli {
+  /**
+   * Resolve a single `op://...` reference. Returns the **trimmed**
+   * stdout. Throws {@link OpCliError} when the binary is missing, the
+   * user is signed out, the reference does not resolve, or the call
+   * exceeds the timeout.
+   */
+  read(uri: string, options?: OpCliReadOptions): Promise<OpCliReadResult>;
+}
+/** @stable */
+interface OpCliReadOptions {
+  /** Override the binary path. Default `'op'` (looked up on `$PATH`). */
+  readonly binary?: string;
+  /** Hard timeout in milliseconds. Default `15000`. */
+  readonly timeoutMs?: number;
+  /** Override `process.env`. Default forwards the parent process. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Optional 1Password Connect / Service-Account token forwarding. */
+  readonly serviceAccountToken?: string;
+  /**
+   * Optional 1Password Connect host + token tuple. When set the
+   * resolver wires them through the `OP_CONNECT_HOST` /
+   * `OP_CONNECT_TOKEN` env vars (the canonical Connect-mode contract
+   * documented by 1Password).
+   */
+  readonly connect?: {
+    readonly host: string;
+    readonly token: string;
+  };
+  /**
+   * Optional `--account` override forwarded to the CLI. Useful when
+   * the operator is signed in to multiple 1Password accounts.
+   */
+  readonly account?: string;
+  /**
+   * Optional `--no-color` flag suppression. The resolver always sets
+   * `--no-color` so terminal colour codes do not leak into the
+   * resolved value; pass `true` to opt out.
+   */
+  readonly preserveColor?: boolean;
+}
+/**
+ * Typed error raised by the CLI wrapper. Carries a `kind` so callers
+ * can distinguish operator-fixable failure modes.
+ *
+ * @stable
+ */
+declare class OpCliError extends Error {
+  readonly name = "OpCliError";
+  readonly kind: OpCliErrorKind;
+  readonly exitCode?: number;
+  readonly stderr?: string;
+  readonly hint?: string;
+  constructor(kind: OpCliErrorKind, message: string, options?: {
+    cause?: unknown;
+    exitCode?: number;
+    stderr?: string;
+    hint?: string;
+  });
+}
+/** @stable */
+type OpCliErrorKind = 'binary-missing' | 'signed-out' | 'reference-not-found' | 'timeout' | 'unknown';
+/**
+ * Default {@link OpCli} implementation. Spawns `op read --no-color
+ * --reveal '<uri>'` with the configured timeout and inherits the
+ * parent environment.
+ *
+ * @stable
+ */
+declare function createDefaultOpCli(): OpCli;
+/**
+ * {@link OpCli} factory with an injectable `spawn` (for tests). Production
+ * code uses {@link createDefaultOpCli}.
+ *
+ * @stable
+ */
+declare function createOpCli(deps?: {
+  readonly spawn?: typeof spawn;
+}): OpCli;
+//#endregion
+export { OpCli, OpCliError, OpCliErrorKind, OpCliReadOptions, OpCliReadResult, createDefaultOpCli, createOpCli };
+//# sourceMappingURL=op-cli.d.ts.map

package/dist/op-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-cli.d.ts","names":[],"sources":["../src/op-cli.ts"],"sourcesContent":[],"mappings":";;;;;AAoEgC,UArDf,eAAA,CAqDe;EAAK,SAAA,KAAA,EAAA,MAAA;EA0BzB,SAAA,QAAc,EAAA,MAAA;EAcV,SAAA,UAAA,EAAkB,MAAA;AAkBlC;;UAxGiB,KAAA;;;;;;;8BAOa,mBAAmB,QAAQ;;;UAIxC,gBAAA;;;;;;iBAMA,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6Bb,UAAA,SAAmB,KAAA;;iBAEf;;;;oBAMP;;;;;;;;KAkBE,cAAA;;;;;;;;iBAcI,kBAAA,CAAA,GAAsB;;;;;;;iBAkBtB,WAAA;0BAA4C;IAAe"}

package/dist/op-cli.js

@@ -0,0 +1,180 @@
+import { spawn } from "node:child_process";
+
+//#region src/op-cli.ts
+/**
+* Thin wrapper around the 1Password CLI (`op`). Spawns `op` with the
+* canonical `read` subcommand, captures stdout, and surfaces typed
+* errors for the most common operator-fixable failure modes.
+*
+* The wrapper is split out so the resolver can be unit-tested without
+* touching the real `op` binary — tests inject a stub `OpCli`
+* implementation through {@link createOnePasswordResolver}.
+*
+* @packageDocumentation
+*/
+/**
+* Typed error raised by the CLI wrapper. Carries a `kind` so callers
+* can distinguish operator-fixable failure modes.
+*
+* @stable
+*/
+var OpCliError = class extends Error {
+	name = "OpCliError";
+	kind;
+	exitCode;
+	stderr;
+	hint;
+	constructor(kind, message, options) {
+		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.kind = kind;
+		if (options?.exitCode !== void 0) this.exitCode = options.exitCode;
+		if (options?.stderr !== void 0) this.stderr = options.stderr;
+		if (options?.hint !== void 0) this.hint = options.hint;
+	}
+};
+/**
+* Default {@link OpCli} implementation. Spawns `op read --no-color
+* --reveal '<uri>'` with the configured timeout and inherits the
+* parent environment.
+*
+* @stable
+*/
+function createDefaultOpCli() {
+	return createOpCli();
+}
+/**
+* Grace period after SIGTERM before escalating to SIGKILL (SPL-22). A
+* well-behaved `op` exits on SIGTERM well within this window; a wedged one
+* (ignoring SIGTERM in an uninterruptible read) is force-killed so the hard
+* timeout actually settles the promise.
+*/
+const SIGKILL_GRACE_MS = 1e3;
+/**
+* {@link OpCli} factory with an injectable `spawn` (for tests). Production
+* code uses {@link createDefaultOpCli}.
+*
+* @stable
+*/
+function createOpCli(deps = {}) {
+	const spawnFn = deps.spawn ?? spawn;
+	return { async read(uri, options = {}) {
+		const binary = options.binary ?? "op";
+		const timeoutMs = options.timeoutMs ?? 15e3;
+		const args = ["read", "--reveal"];
+		if (options.preserveColor !== true) args.push("--no-color");
+		if (options.account !== void 0 && options.account.length > 0) args.push("--account", options.account);
+		args.push(uri);
+		const env = {};
+		const baseEnv = options.env ?? process.env;
+		for (const [k, v] of Object.entries(baseEnv)) if (typeof v === "string") env[k] = v;
+		if (options.serviceAccountToken !== void 0) env.OP_SERVICE_ACCOUNT_TOKEN = options.serviceAccountToken;
+		if (options.connect !== void 0) {
+			env.OP_CONNECT_HOST = options.connect.host;
+			env.OP_CONNECT_TOKEN = options.connect.token;
+		}
+		const started = performance.now();
+		return new Promise((resolve, reject) => {
+			let stdout = "";
+			let stderr = "";
+			let killedByTimeout = false;
+			let proc;
+			try {
+				proc = spawnFn(binary, args, {
+					env,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					]
+				});
+			} catch (err) {
+				reject(new OpCliError("binary-missing", `'${binary}' is not installed or not on PATH. Install the 1Password CLI: https://developer.1password.com/docs/cli/get-started`, {
+					cause: err,
+					hint: "install the 1Password CLI"
+				}));
+				return;
+			}
+			let graceTimer;
+			const timer = setTimeout(() => {
+				killedByTimeout = true;
+				try {
+					proc.kill("SIGTERM");
+				} catch {}
+				graceTimer = setTimeout(() => {
+					try {
+						proc.kill("SIGKILL");
+					} catch {}
+					reject(new OpCliError("timeout", `op CLI timed out after ${timeoutMs} ms while resolving '${uri}' and did not exit on SIGTERM.`, {
+						stderr,
+						hint: "increase --op-timeout-ms or check 1Password connectivity"
+					}));
+				}, SIGKILL_GRACE_MS);
+				graceTimer.unref?.();
+			}, timeoutMs);
+			timer.unref?.();
+			proc.stdout?.on("data", (chunk) => {
+				stdout += chunk.toString("utf8");
+			});
+			proc.stderr?.on("data", (chunk) => {
+				stderr += chunk.toString("utf8");
+			});
+			proc.on("error", (err) => {
+				clearTimeout(timer);
+				if (graceTimer !== void 0) clearTimeout(graceTimer);
+				if (err.code === "ENOENT") {
+					reject(new OpCliError("binary-missing", `'${binary}' is not installed or not on PATH. Install the 1Password CLI: https://developer.1password.com/docs/cli/get-started`, {
+						cause: err,
+						hint: "install the 1Password CLI"
+					}));
+					return;
+				}
+				reject(new OpCliError("unknown", `op CLI invocation failed: ${err.message}`, { cause: err }));
+			});
+			proc.on("close", (code) => {
+				clearTimeout(timer);
+				if (graceTimer !== void 0) clearTimeout(graceTimer);
+				const durationMs = performance.now() - started;
+				if (killedByTimeout) {
+					reject(new OpCliError("timeout", `op CLI timed out after ${timeoutMs} ms while resolving '${uri}'.`, {
+						stderr,
+						hint: "increase --op-timeout-ms or check 1Password connectivity"
+					}));
+					return;
+				}
+				if (code !== 0) {
+					const kind = classifyExitError(code ?? -1, stderr);
+					reject(new OpCliError(kind, `op CLI exited with code ${code} for '${uri}'${stderr.length > 0 ? `: ${stderr.trim()}` : ""}`, {
+						...code !== null ? { exitCode: code } : {},
+						stderr,
+						hint: hintForExitKind(kind)
+					}));
+					return;
+				}
+				resolve(Object.freeze({
+					value: stdout.replace(/\r?\n$/, ""),
+					exitCode: 0,
+					durationMs
+				}));
+			});
+		});
+	} };
+}
+function classifyExitError(_code, stderr) {
+	const lower = stderr.toLowerCase();
+	if (lower.includes("not signed in") || lower.includes("please sign in") || lower.includes("not authenticated") || lower.includes("session expired")) return "signed-out";
+	if (lower.includes("couldn't find") || lower.includes("does not exist") || lower.includes("item not found") || lower.includes("field not found") || lower.includes("reference not found")) return "reference-not-found";
+	return "unknown";
+}
+function hintForExitKind(kind) {
+	switch (kind) {
+		case "signed-out": return "run 'eval $(op signin)' (interactive) or set OP_SERVICE_ACCOUNT_TOKEN (headless).";
+		case "reference-not-found": return "verify the reference with 'op item get <item> --vault <vault>' before retrying.";
+		case "timeout": return "check 1Password connectivity / increase --op-timeout-ms.";
+		case "binary-missing": return "install the 1Password CLI: https://developer.1password.com/docs/cli/get-started";
+		default: return "check the op CLI stderr output for details.";
+	}
+}
+
+//#endregion
+export { OpCliError, createDefaultOpCli, createOpCli };
+//# sourceMappingURL=op-cli.js.map

package/dist/op-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-cli.js","names":["env: Record<string, string>","proc: ReturnType<typeof spawn>","graceTimer: ReturnType<typeof setTimeout> | undefined"],"sources":["../src/op-cli.ts"],"sourcesContent":["/**\n * Thin wrapper around the 1Password CLI (`op`). Spawns `op` with the\n * canonical `read` subcommand, captures stdout, and surfaces typed\n * errors for the most common operator-fixable failure modes.\n *\n * The wrapper is split out so the resolver can be unit-tested without\n * touching the real `op` binary — tests inject a stub `OpCli`\n * implementation through {@link createOnePasswordResolver}.\n *\n * @packageDocumentation\n */\n\nimport { spawn } from 'node:child_process';\n\n/** @stable */\nexport interface OpCliReadResult {\n  readonly value: string;\n  readonly exitCode: number;\n  readonly durationMs: number;\n}\n\n/** @stable */\nexport interface OpCli {\n  /**\n   * Resolve a single `op://...` reference. Returns the **trimmed**\n   * stdout. Throws {@link OpCliError} when the binary is missing, the\n   * user is signed out, the reference does not resolve, or the call\n   * exceeds the timeout.\n   */\n  read(uri: string, options?: OpCliReadOptions): Promise<OpCliReadResult>;\n}\n\n/** @stable */\nexport interface OpCliReadOptions {\n  /** Override the binary path. Default `'op'` (looked up on `$PATH`). */\n  readonly binary?: string;\n  /** Hard timeout in milliseconds. Default `15000`. */\n  readonly timeoutMs?: number;\n  /** Override `process.env`. Default forwards the parent process. */\n  readonly env?: Readonly<Record<string, string | undefined>>;\n  /** Optional 1Password Connect / Service-Account token forwarding. */\n  readonly serviceAccountToken?: string;\n  /**\n   * Optional 1Password Connect host + token tuple. When set the\n   * resolver wires them through the `OP_CONNECT_HOST` /\n   * `OP_CONNECT_TOKEN` env vars (the canonical Connect-mode contract\n   * documented by 1Password).\n   */\n  readonly connect?: { readonly host: string; readonly token: string };\n  /**\n   * Optional `--account` override forwarded to the CLI. Useful when\n   * the operator is signed in to multiple 1Password accounts.\n   */\n  readonly account?: string;\n  /**\n   * Optional `--no-color` flag suppression. The resolver always sets\n   * `--no-color` so terminal colour codes do not leak into the\n   * resolved value; pass `true` to opt out.\n   */\n  readonly preserveColor?: boolean;\n}\n\n/**\n * Typed error raised by the CLI wrapper. Carries a `kind` so callers\n * can distinguish operator-fixable failure modes.\n *\n * @stable\n */\nexport class OpCliError extends Error {\n  override readonly name = 'OpCliError';\n  readonly kind: OpCliErrorKind;\n  readonly exitCode?: number;\n  readonly stderr?: string;\n  readonly hint?: string;\n\n  constructor(\n    kind: OpCliErrorKind,\n    message: string,\n    options?: {\n      cause?: unknown;\n      exitCode?: number;\n      stderr?: string;\n      hint?: string;\n    },\n  ) {\n    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n    this.kind = kind;\n    if (options?.exitCode !== undefined) this.exitCode = options.exitCode;\n    if (options?.stderr !== undefined) this.stderr = options.stderr;\n    if (options?.hint !== undefined) this.hint = options.hint;\n  }\n}\n\n/** @stable */\nexport type OpCliErrorKind =\n  | 'binary-missing'\n  | 'signed-out'\n  | 'reference-not-found'\n  | 'timeout'\n  | 'unknown';\n\n/**\n * Default {@link OpCli} implementation. Spawns `op read --no-color\n * --reveal '<uri>'` with the configured timeout and inherits the\n * parent environment.\n *\n * @stable\n */\nexport function createDefaultOpCli(): OpCli {\n  return createOpCli();\n}\n\n/**\n * Grace period after SIGTERM before escalating to SIGKILL (SPL-22). A\n * well-behaved `op` exits on SIGTERM well within this window; a wedged one\n * (ignoring SIGTERM in an uninterruptible read) is force-killed so the hard\n * timeout actually settles the promise.\n */\nconst SIGKILL_GRACE_MS = 1_000;\n\n/**\n * {@link OpCli} factory with an injectable `spawn` (for tests). Production\n * code uses {@link createDefaultOpCli}.\n *\n * @stable\n */\nexport function createOpCli(deps: { readonly spawn?: typeof spawn } = {}): OpCli {\n  const spawnFn = deps.spawn ?? spawn;\n  return {\n    async read(uri: string, options: OpCliReadOptions = {}): Promise<OpCliReadResult> {\n      const binary = options.binary ?? 'op';\n      const timeoutMs = options.timeoutMs ?? 15_000;\n      const args = ['read', '--reveal'];\n      if (options.preserveColor !== true) args.push('--no-color');\n      if (options.account !== undefined && options.account.length > 0) {\n        args.push('--account', options.account);\n      }\n      args.push(uri);\n      const env: Record<string, string> = {};\n      const baseEnv = options.env ?? process.env;\n      for (const [k, v] of Object.entries(baseEnv)) {\n        if (typeof v === 'string') env[k] = v;\n      }\n      if (options.serviceAccountToken !== undefined) {\n        env.OP_SERVICE_ACCOUNT_TOKEN = options.serviceAccountToken;\n      }\n      if (options.connect !== undefined) {\n        env.OP_CONNECT_HOST = options.connect.host;\n        env.OP_CONNECT_TOKEN = options.connect.token;\n      }\n      const started = performance.now();\n      return new Promise<OpCliReadResult>((resolve, reject) => {\n        let stdout = '';\n        let stderr = '';\n        let killedByTimeout = false;\n        let proc: ReturnType<typeof spawn>;\n        try {\n          proc = spawnFn(binary, args, { env, stdio: ['ignore', 'pipe', 'pipe'] });\n        } catch (err) {\n          reject(\n            new OpCliError(\n              'binary-missing',\n              `'${binary}' is not installed or not on PATH. Install the 1Password CLI: https://developer.1password.com/docs/cli/get-started`,\n              { cause: err, hint: 'install the 1Password CLI' },\n            ),\n          );\n          return;\n        }\n        let graceTimer: ReturnType<typeof setTimeout> | undefined;\n        const timer = setTimeout(() => {\n          killedByTimeout = true;\n          try {\n            proc.kill('SIGTERM');\n          } catch {\n            // best-effort\n          }\n          // SPL-22: SIGTERM alone can hang forever if `op` ignores it. Escalate\n          // to SIGKILL after a short grace AND reject from the timer, so the\n          // promise settles even when `close` never fires.\n          graceTimer = setTimeout(() => {\n            try {\n              proc.kill('SIGKILL');\n            } catch {\n              // best-effort\n            }\n            reject(\n              new OpCliError(\n                'timeout',\n                `op CLI timed out after ${timeoutMs} ms while resolving '${uri}' and did not exit on SIGTERM.`,\n                { stderr, hint: 'increase --op-timeout-ms or check 1Password connectivity' },\n              ),\n            );\n          }, SIGKILL_GRACE_MS);\n          graceTimer.unref?.();\n        }, timeoutMs);\n        timer.unref?.();\n        proc.stdout?.on('data', (chunk: Buffer) => {\n          stdout += chunk.toString('utf8');\n        });\n        proc.stderr?.on('data', (chunk: Buffer) => {\n          stderr += chunk.toString('utf8');\n        });\n        proc.on('error', (err) => {\n          clearTimeout(timer);\n          if (graceTimer !== undefined) clearTimeout(graceTimer);\n          if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n            reject(\n              new OpCliError(\n                'binary-missing',\n                `'${binary}' is not installed or not on PATH. Install the 1Password CLI: https://developer.1password.com/docs/cli/get-started`,\n                { cause: err, hint: 'install the 1Password CLI' },\n              ),\n            );\n            return;\n          }\n          reject(\n            new OpCliError('unknown', `op CLI invocation failed: ${err.message}`, {\n              cause: err,\n            }),\n          );\n        });\n        proc.on('close', (code) => {\n          clearTimeout(timer);\n          if (graceTimer !== undefined) clearTimeout(graceTimer);\n          const durationMs = performance.now() - started;\n          if (killedByTimeout) {\n            reject(\n              new OpCliError(\n                'timeout',\n                `op CLI timed out after ${timeoutMs} ms while resolving '${uri}'.`,\n                { stderr, hint: 'increase --op-timeout-ms or check 1Password connectivity' },\n              ),\n            );\n            return;\n          }\n          if (code !== 0) {\n            const kind = classifyExitError(code ?? -1, stderr);\n            reject(\n              new OpCliError(\n                kind,\n                `op CLI exited with code ${code} for '${uri}'${stderr.length > 0 ? `: ${stderr.trim()}` : ''}`,\n                {\n                  ...(code !== null ? { exitCode: code } : {}),\n                  stderr,\n                  hint: hintForExitKind(kind),\n                },\n              ),\n            );\n            return;\n          }\n          resolve(Object.freeze({ value: stdout.replace(/\\r?\\n$/, ''), exitCode: 0, durationMs }));\n        });\n      });\n    },\n  };\n}\n\nfunction classifyExitError(_code: number, stderr: string): OpCliErrorKind {\n  const lower = stderr.toLowerCase();\n  if (\n    lower.includes('not signed in') ||\n    lower.includes('please sign in') ||\n    lower.includes('not authenticated') ||\n    lower.includes('session expired')\n  ) {\n    return 'signed-out';\n  }\n  if (\n    lower.includes(\"couldn't find\") ||\n    lower.includes('does not exist') ||\n    lower.includes('item not found') ||\n    lower.includes('field not found') ||\n    lower.includes('reference not found')\n  ) {\n    return 'reference-not-found';\n  }\n  return 'unknown';\n}\n\nfunction hintForExitKind(kind: OpCliErrorKind): string {\n  switch (kind) {\n    case 'signed-out':\n      return \"run 'eval $(op signin)' (interactive) or set OP_SERVICE_ACCOUNT_TOKEN (headless).\";\n    case 'reference-not-found':\n      return \"verify the reference with 'op item get <item> --vault <vault>' before retrying.\";\n    case 'timeout':\n      return 'check 1Password connectivity / increase --op-timeout-ms.';\n    case 'binary-missing':\n      return 'install the 1Password CLI: https://developer.1password.com/docs/cli/get-started';\n    default:\n      return 'check the op CLI stderr output for details.';\n  }\n}\n"],"mappings":"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"}

package/dist/resolver.d.ts

@@ -0,0 +1,72 @@
+import { OpCli } from "./op-cli.js";
+import { SecretResolver } from "@graphorin/core/contracts";
+
+//#region src/resolver.d.ts
+
+/** @stable */
+interface OnePasswordResolverOptions {
+  /**
+   * Inject a {@link OpCli} implementation. Defaults to a wrapper that
+   * spawns the system `op` binary. Tests pass a stub.
+   */
+  readonly cli?: OpCli;
+  /** Override the CLI binary path. Default `'op'`. */
+  readonly binary?: string;
+  /** Hard timeout per resolve. Default `15000` ms. */
+  readonly timeoutMs?: number;
+  /**
+   * Optional service-account token. When set the resolver forwards it
+   * via `OP_SERVICE_ACCOUNT_TOKEN` so the CLI runs in headless mode.
+   * The token is itself a secret — pass a previously-resolved
+   * `SecretValue` and use `.use(...)` to scope its lifetime.
+   */
+  readonly serviceAccountToken?: string;
+  /**
+   * Optional 1Password Connect host + token. Mutually exclusive with
+   * a service-account token at the CLI level (the CLI honours the
+   * Connect env vars if both are present).
+   */
+  readonly connect?: {
+    readonly host: string;
+    readonly token: string;
+  };
+  /**
+   * Optional `--account` override. Useful when the operator is signed
+   * in to multiple 1Password accounts.
+   */
+  readonly account?: string;
+  /**
+   * If `true`, do **not** lowercase the URI before forwarding to the
+   * CLI. Default `false`. Toggle only when interoperating with a
+   * deployment that intentionally relies on case-sensitive keys.
+   */
+  readonly preserveCase?: boolean;
+}
+/**
+ * Build a `SecretResolver` that honours the `op://` scheme. Register
+ * with `registerResolver(...)` from `@graphorin/security` at app
+ * bootstrap.
+ *
+ * @stable
+ */
+declare function createOnePasswordResolver(options?: OnePasswordResolverOptions): SecretResolver;
+/**
+ * Cache the default-options resolver so callers that just want the
+ * happy-path behaviour can use a constant export.
+ *
+ * @stable
+ */
+declare const onePasswordResolver: SecretResolver;
+/**
+ * Lowercase the authority + path segments of an `op://` URI so two
+ * configs that differ only in case resolve to the same value (matching
+ * 1Password's case-insensitive behaviour).
+ *
+ * Exposed for tests.
+ *
+ * @stable
+ */
+declare function normalizeOpUri(raw: string): string;
+//#endregion
+export { OnePasswordResolverOptions, createOnePasswordResolver, normalizeOpUri, onePasswordResolver };
+//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","names":[],"sources":["../src/resolver.ts"],"sourcesContent":[],"mappings":";;;;;;UAwBiB,0BAAA;;;;;iBAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCD,yBAAA,WACL,6BACR;;;;;;;cAkDU,qBAAqB;;;;;;;;;;iBA4ClB,cAAA"}

package/dist/resolver.js

@@ -0,0 +1,71 @@
+import { OpCliError, createDefaultOpCli } from "./op-cli.js";
+import { SecretResolutionError, SecretValue } from "@graphorin/security";
+
+//#region src/resolver.ts
+/**
+* Build a `SecretResolver` that honours the `op://` scheme. Register
+* with `registerResolver(...)` from `@graphorin/security` at app
+* bootstrap.
+*
+* @stable
+*/
+function createOnePasswordResolver(options = {}) {
+	const cli = options.cli ?? createDefaultOpCli();
+	return {
+		scheme: "op",
+		async resolve(ref, ctx) {
+			const parsed = ref;
+			assertOpRef(parsed);
+			const normalized = options.preserveCase === true ? parsed.raw : normalizeOpUri(parsed.raw);
+			try {
+				const result = await cli.read(normalized, {
+					...options.binary !== void 0 ? { binary: options.binary } : {},
+					...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {},
+					...options.serviceAccountToken !== void 0 ? { serviceAccountToken: options.serviceAccountToken } : {},
+					...options.connect !== void 0 ? { connect: options.connect } : {},
+					...options.account !== void 0 ? { account: options.account } : {}
+				});
+				if (result.value.length === 0) throw new SecretResolutionError("op", parsed.raw, "1Password CLI returned an empty value; verify the field exists and is non-empty.");
+				return SecretValue.fromString(result.value, { source: {
+					resolver: "op",
+					ref: parsed.raw
+				} });
+			} catch (err) {
+				if (err instanceof OpCliError) throw new SecretResolutionError("op", parsed.raw, `${err.message}${err.hint !== void 0 ? ` — hint: ${err.hint}` : ""}`, { cause: err });
+				throw err;
+			}
+		}
+	};
+}
+/**
+* Cache the default-options resolver so callers that just want the
+* happy-path behaviour can use a constant export.
+*
+* @stable
+*/
+const onePasswordResolver = createOnePasswordResolver();
+function assertOpRef(parsed) {
+	if (parsed.scheme !== "op") throw new SecretResolutionError("op", parsed.raw, `expected scheme 'op', received '${parsed.scheme}'.`);
+	if (parsed.authority === void 0 || parsed.authority.length === 0) throw new SecretResolutionError("op", parsed.raw, "op:// SecretRef must include a vault authority (e.g. 'op://Personal/Item/field').");
+	if (parsed.path === void 0 || parsed.path.length <= 1) throw new SecretResolutionError("op", parsed.raw, "op:// SecretRef must include an item + field path segment (e.g. 'op://Vault/Item/field').");
+	const segments = parsed.path.split("/").filter((s) => s.length > 0);
+	if (segments.length < 2) throw new SecretResolutionError("op", parsed.raw, `op:// SecretRef must reference at least an item + field (got ${segments.length} path segment(s) after the vault).`);
+}
+/**
+* Lowercase the authority + path segments of an `op://` URI so two
+* configs that differ only in case resolve to the same value (matching
+* 1Password's case-insensitive behaviour).
+*
+* Exposed for tests.
+*
+* @stable
+*/
+function normalizeOpUri(raw) {
+	const cuts = [raw.indexOf("?"), raw.indexOf("#")].filter((i) => i >= 0);
+	const split = cuts.length > 0 ? Math.min(...cuts) : raw.length;
+	return raw.slice(0, split).toLowerCase() + raw.slice(split);
+}
+
+//#endregion
+export { createOnePasswordResolver, normalizeOpUri, onePasswordResolver };
+//# sourceMappingURL=resolver.js.map

package/dist/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","names":["onePasswordResolver: SecretResolver"],"sources":["../src/resolver.ts"],"sourcesContent":["/**\n * `op://`-scheme `SecretResolver` for the Graphorin framework. Wraps\n * the official 1Password CLI (`op`) per the canonical `op read` flow\n * documented at https://developer.1password.com/docs/cli/secrets-references/.\n *\n * URI shape (per 1Password): `op://<vault>/<item>/[section/]<field>`.\n * The resolver accepts any `op://` URI the CLI accepts (the CLI is\n * the source of truth — we forward verbatim) and rejects only the\n * obvious malformed cases at parse time.\n *\n * 1Password explicitly treats vault / item / field names as\n * case-insensitive; the resolver normalises the URI by lowercasing the\n * authority + path before forwarding to the CLI so two configs that\n * differ only in case resolve to the same value.\n *\n * @packageDocumentation\n */\n\nimport type { SecretResolver, SecretResolverContext } from '@graphorin/core/contracts';\nimport { type ParsedSecretRef, SecretResolutionError, SecretValue } from '@graphorin/security';\n\nimport { createDefaultOpCli, type OpCli, OpCliError } from './op-cli.js';\n\n/** @stable */\nexport interface OnePasswordResolverOptions {\n  /**\n   * Inject a {@link OpCli} implementation. Defaults to a wrapper that\n   * spawns the system `op` binary. Tests pass a stub.\n   */\n  readonly cli?: OpCli;\n  /** Override the CLI binary path. Default `'op'`. */\n  readonly binary?: string;\n  /** Hard timeout per resolve. Default `15000` ms. */\n  readonly timeoutMs?: number;\n  /**\n   * Optional service-account token. When set the resolver forwards it\n   * via `OP_SERVICE_ACCOUNT_TOKEN` so the CLI runs in headless mode.\n   * The token is itself a secret — pass a previously-resolved\n   * `SecretValue` and use `.use(...)` to scope its lifetime.\n   */\n  readonly serviceAccountToken?: string;\n  /**\n   * Optional 1Password Connect host + token. Mutually exclusive with\n   * a service-account token at the CLI level (the CLI honours the\n   * Connect env vars if both are present).\n   */\n  readonly connect?: { readonly host: string; readonly token: string };\n  /**\n   * Optional `--account` override. Useful when the operator is signed\n   * in to multiple 1Password accounts.\n   */\n  readonly account?: string;\n  /**\n   * If `true`, do **not** lowercase the URI before forwarding to the\n   * CLI. Default `false`. Toggle only when interoperating with a\n   * deployment that intentionally relies on case-sensitive keys.\n   */\n  readonly preserveCase?: boolean;\n}\n\n/**\n * Build a `SecretResolver` that honours the `op://` scheme. Register\n * with `registerResolver(...)` from `@graphorin/security` at app\n * bootstrap.\n *\n * @stable\n */\nexport function createOnePasswordResolver(\n  options: OnePasswordResolverOptions = {},\n): SecretResolver {\n  const cli = options.cli ?? createDefaultOpCli();\n  return {\n    scheme: 'op',\n    async resolve(ref, ctx?: SecretResolverContext): Promise<SecretValue> {\n      void ctx;\n      const parsed = ref as ParsedSecretRef;\n      assertOpRef(parsed);\n      const normalized = options.preserveCase === true ? parsed.raw : normalizeOpUri(parsed.raw);\n      try {\n        const result = await cli.read(normalized, {\n          ...(options.binary !== undefined ? { binary: options.binary } : {}),\n          ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),\n          ...(options.serviceAccountToken !== undefined\n            ? { serviceAccountToken: options.serviceAccountToken }\n            : {}),\n          ...(options.connect !== undefined ? { connect: options.connect } : {}),\n          ...(options.account !== undefined ? { account: options.account } : {}),\n        });\n        if (result.value.length === 0) {\n          throw new SecretResolutionError(\n            'op',\n            parsed.raw,\n            '1Password CLI returned an empty value; verify the field exists and is non-empty.',\n          );\n        }\n        return SecretValue.fromString(result.value, {\n          source: { resolver: 'op', ref: parsed.raw },\n        });\n      } catch (err) {\n        if (err instanceof OpCliError) {\n          throw new SecretResolutionError(\n            'op',\n            parsed.raw,\n            `${err.message}${err.hint !== undefined ? ` — hint: ${err.hint}` : ''}`,\n            { cause: err },\n          );\n        }\n        throw err;\n      }\n    },\n  };\n}\n\n/**\n * Cache the default-options resolver so callers that just want the\n * happy-path behaviour can use a constant export.\n *\n * @stable\n */\nexport const onePasswordResolver: SecretResolver = createOnePasswordResolver();\n\nfunction assertOpRef(parsed: ParsedSecretRef): void {\n  if (parsed.scheme !== 'op') {\n    throw new SecretResolutionError(\n      'op',\n      parsed.raw,\n      `expected scheme 'op', received '${parsed.scheme}'.`,\n    );\n  }\n  if (parsed.authority === undefined || parsed.authority.length === 0) {\n    throw new SecretResolutionError(\n      'op',\n      parsed.raw,\n      \"op:// SecretRef must include a vault authority (e.g. 'op://Personal/Item/field').\",\n    );\n  }\n  if (parsed.path === undefined || parsed.path.length <= 1) {\n    throw new SecretResolutionError(\n      'op',\n      parsed.raw,\n      \"op:// SecretRef must include an item + field path segment (e.g. 'op://Vault/Item/field').\",\n    );\n  }\n  const segments = parsed.path.split('/').filter((s) => s.length > 0);\n  if (segments.length < 2) {\n    throw new SecretResolutionError(\n      'op',\n      parsed.raw,\n      'op:// SecretRef must reference at least an item + field (got ' +\n        `${segments.length} path segment(s) after the vault).`,\n    );\n  }\n}\n\n/**\n * Lowercase the authority + path segments of an `op://` URI so two\n * configs that differ only in case resolve to the same value (matching\n * 1Password's case-insensitive behaviour).\n *\n * Exposed for tests.\n *\n * @stable\n */\nexport function normalizeOpUri(raw: string): string {\n  // Lowercase only the part up to the first `?` or `#` so query /\n  // fragment components keep their original case (the CLI does not\n  // currently use them, but forward-compat matters).\n  const queryIdx = raw.indexOf('?');\n  const fragIdx = raw.indexOf('#');\n  const cuts = [queryIdx, fragIdx].filter((i) => i >= 0);\n  const split = cuts.length > 0 ? Math.min(...cuts) : raw.length;\n  const head = raw.slice(0, split).toLowerCase();\n  const tail = raw.slice(split);\n  return head + tail;\n}\n"],"mappings":";;;;;;;;;;;AAmEA,SAAgB,0BACd,UAAsC,EAAE,EACxB;CAChB,MAAM,MAAM,QAAQ,OAAO,oBAAoB;AAC/C,QAAO;EACL,QAAQ;EACR,MAAM,QAAQ,KAAK,KAAmD;GAEpE,MAAM,SAAS;AACf,eAAY,OAAO;GACnB,MAAM,aAAa,QAAQ,iBAAiB,OAAO,OAAO,MAAM,eAAe,OAAO,IAAI;AAC1F,OAAI;IACF,MAAM,SAAS,MAAM,IAAI,KAAK,YAAY;KACxC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE;KAClE,GAAI,QAAQ,cAAc,SAAY,EAAE,WAAW,QAAQ,WAAW,GAAG,EAAE;KAC3E,GAAI,QAAQ,wBAAwB,SAChC,EAAE,qBAAqB,QAAQ,qBAAqB,GACpD,EAAE;KACN,GAAI,QAAQ,YAAY,SAAY,EAAE,SAAS,QAAQ,SAAS,GAAG,EAAE;KACrE,GAAI,QAAQ,YAAY,SAAY,EAAE,SAAS,QAAQ,SAAS,GAAG,EAAE;KACtE,CAAC;AACF,QAAI,OAAO,MAAM,WAAW,EAC1B,OAAM,IAAI,sBACR,MACA,OAAO,KACP,mFACD;AAEH,WAAO,YAAY,WAAW,OAAO,OAAO,EAC1C,QAAQ;KAAE,UAAU;KAAM,KAAK,OAAO;KAAK,EAC5C,CAAC;YACK,KAAK;AACZ,QAAI,eAAe,WACjB,OAAM,IAAI,sBACR,MACA,OAAO,KACP,GAAG,IAAI,UAAU,IAAI,SAAS,SAAY,YAAY,IAAI,SAAS,MACnE,EAAE,OAAO,KAAK,CACf;AAEH,UAAM;;;EAGX;;;;;;;;AASH,MAAaA,sBAAsC,2BAA2B;AAE9E,SAAS,YAAY,QAA+B;AAClD,KAAI,OAAO,WAAW,KACpB,OAAM,IAAI,sBACR,MACA,OAAO,KACP,mCAAmC,OAAO,OAAO,IAClD;AAEH,KAAI,OAAO,cAAc,UAAa,OAAO,UAAU,WAAW,EAChE,OAAM,IAAI,sBACR,MACA,OAAO,KACP,oFACD;AAEH,KAAI,OAAO,SAAS,UAAa,OAAO,KAAK,UAAU,EACrD,OAAM,IAAI,sBACR,MACA,OAAO,KACP,4FACD;CAEH,MAAM,WAAW,OAAO,KAAK,MAAM,IAAI,CAAC,QAAQ,MAAM,EAAE,SAAS,EAAE;AACnE,KAAI,SAAS,SAAS,EACpB,OAAM,IAAI,sBACR,MACA,OAAO,KACP,gEACK,SAAS,OAAO,oCACtB;;;;;;;;;;;AAaL,SAAgB,eAAe,KAAqB;CAMlD,MAAM,OAAO,CAFI,IAAI,QAAQ,IAAI,EACjB,IAAI,QAAQ,IAAI,CACA,CAAC,QAAQ,MAAM,KAAK,EAAE;CACtD,MAAM,QAAQ,KAAK,SAAS,IAAI,KAAK,IAAI,GAAG,KAAK,GAAG,IAAI;AAGxD,QAFa,IAAI,MAAM,GAAG,MAAM,CAAC,aAAa,GACjC,IAAI,MAAM,MAAM"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@graphorin/secret-1password",
+  "version": "0.5.0",
+  "description": "Reference 1Password secret-resolver adapter for the Graphorin framework. Registers the `op://` scheme on top of `@graphorin/security`'s pluggable `SecretResolver` registry by shelling out to the official 1Password CLI (`op read 'op://<vault>/<item>/<field>'`). The resolver enforces a strict timeout, validates the URI before invoking the CLI, redacts the resolved value behind a `SecretValue`, and surfaces actionable errors when the CLI is missing, the user is not signed in, or the requested field is not present. Serves as the canonical template community packages should follow when wiring HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, Bitwarden, or Unix `pass` as additional `SecretResolver` implementations. Created and maintained by Oleksiy Stepurenko.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/secret-1password",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/secret-1password"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "secrets",
+    "1password",
+    "op-cli",
+    "secret-resolver",
+    "secret-ref"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0",
+    "@graphorin/security": "0.5.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}