@graphorin/secret-1password 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @graphorin/secret-1password
 
+## 0.7.0
+
+### Minor Changes
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-072: every export map's `import` condition becomes `default`, and the Node floor rises to `>=22.12.0`.
+
+  CJS consumers previously hit a bewildering `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a clear ESM-only signal. With the `default` condition, plain `require('@graphorin/core')` works via Node's stable `require(esm)` - which shipped in 22.12, hence the engines bump across every workspace manifest (packages, examples, benchmarks, docs; enforced by the widened mvp-readiness sweep). No dual-instance hazard: there is no CJS build, `require()` returns the same ESM module instance. ESM consumers are unaffected (`default` serves both paths; `types` stays first). The pack gate now runs attw under the full `node16` profile (was `esm-only`) and adds a runtime `require(esm)` smoke against the packed tarballs. Installs on Node 22.0-22.11 with `engine-strict` will refuse - upgrade Node (see the migration guide).
+
+### Patch Changes
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Tarballs now ship `src/` so the published `dist/**/*.d.ts.map` files actually work (W-136): the maps referenced `../src/*.ts` that the `files` whitelist excluded, so go-to-definition fell back into `.d.ts` and the shipped maps were dead weight. The pack gate gains a `map-integrity` leg: every source referenced by a shipped map must resolve inside the tarball (or be embedded via `sourcesContent`), with an anti-vacuous guard - a package whose tsdown config emits declaration maps must contain a non-zero number of `.d.ts.map` files, so a cache-restored dist that silently dropped maps fails the gate instead of passing vacuously. `mvp-readiness` now requires `src` in every publishable `files` array.
+
+- Updated dependencies [[`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`832f22e`](https://github.com/o-stepper/graphorin/commit/832f22e570b8c3175c1adeb4c150070cbd131534), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`4ee256e`](https://github.com/o-stepper/graphorin/commit/4ee256e30fe9190cef6c48dc6785464757707156), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04), [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04)]:
+  - @graphorin/core@0.7.0
+  - @graphorin/security@0.7.0
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -6,14 +6,14 @@
 > pluggable `SecretResolver` registry by shelling out to the official
 > 1Password CLI (`op read 'op://<vault>/<item>/<field>'`).
 >
-> Project Graphorin · v0.6.1 · MIT License · © 2026 Oleksiy Stepurenko ·
+> Project Graphorin · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko ·
 > <https://github.com/o-stepper/graphorin>
 
 ---
 
 ## Status
 
-- **Published:** v0.6.1 (optional sub-pack)
+- **Published:** v0.7.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`.
@@ -167,4 +167,4 @@ MIT © 2026 Oleksiy Stepurenko
 
 ---
 
-**Project Graphorin** · v0.6.1 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>
+**Project Graphorin** · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.6.1";
+var version = "0.7.0";
 
 //#endregion
 export { version };

package/dist/package.js.map

@@ -1 +1 @@
-{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/secret-1password\",\n  \"version\": \"0.6.1\",\n  \"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.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/secret-1password\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/secret-1password\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"secrets\",\n    \"1password\",\n    \"op-cli\",\n    \"secret-resolver\",\n    \"secret-ref\"\n  ],\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=22.0.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"sideEffects\": false,\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\",\n    \"@graphorin/security\": \"workspace:*\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  }\n}\n"],"mappings":";cAEa"}
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/secret-1password\",\n  \"version\": \"0.7.0\",\n  \"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.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/secret-1password\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/secret-1password\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"secrets\",\n    \"1password\",\n    \"op-cli\",\n    \"secret-resolver\",\n    \"secret-ref\"\n  ],\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=22.12.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"sideEffects\": false,\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"src\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\",\n    \"@graphorin/security\": \"workspace:*\"\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  }\n}\n"],"mappings":";cAEa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/secret-1password",
-  "version": "0.6.1",
+  "version": "0.7.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",
@@ -26,7 +26,7 @@
   ],
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -35,19 +35,20 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@graphorin/core": "0.6.1",
-    "@graphorin/security": "0.6.1"
+    "@graphorin/core": "0.7.0",
+    "@graphorin/security": "0.7.0"
   },
   "publishConfig": {
     "access": "public",

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @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, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export {
+  createDefaultOpCli,
+  createOpCli,
+  type OpCli,
+  OpCliError,
+  type OpCliErrorKind,
+  type OpCliReadOptions,
+  type OpCliReadResult,
+} from './op-cli.js';
+export {
+  createOnePasswordResolver,
+  normalizeOpUri,
+  type OnePasswordResolverOptions,
+  onePasswordResolver,
+} from './resolver.js';

package/src/op-cli.ts

@@ -0,0 +1,293 @@
+/**
+ * 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
+ */
+
+import { spawn } from 'node:child_process';
+
+/** @stable */
+export interface OpCliReadResult {
+  readonly value: string;
+  readonly exitCode: number;
+  readonly durationMs: number;
+}
+
+/** @stable */
+export 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 */
+export 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
+ */
+export class OpCliError extends Error {
+  override 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;
+    },
+  ) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+    this.kind = kind;
+    if (options?.exitCode !== undefined) this.exitCode = options.exitCode;
+    if (options?.stderr !== undefined) this.stderr = options.stderr;
+    if (options?.hint !== undefined) this.hint = options.hint;
+  }
+}
+
+/** @stable */
+export 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
+ */
+export function createDefaultOpCli(): OpCli {
+  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 = 1_000;
+
+/**
+ * {@link OpCli} factory with an injectable `spawn` (for tests). Production
+ * code uses {@link createDefaultOpCli}.
+ *
+ * @stable
+ */
+export function createOpCli(deps: { readonly spawn?: typeof spawn } = {}): OpCli {
+  const spawnFn = deps.spawn ?? spawn;
+  return {
+    async read(uri: string, options: OpCliReadOptions = {}): Promise<OpCliReadResult> {
+      const binary = options.binary ?? 'op';
+      const timeoutMs = options.timeoutMs ?? 15_000;
+      const args = ['read', '--reveal'];
+      if (options.preserveColor !== true) args.push('--no-color');
+      if (options.account !== undefined && options.account.length > 0) {
+        args.push('--account', options.account);
+      }
+      args.push(uri);
+      const env: Record<string, string> = {};
+      const baseEnv = options.env ?? process.env;
+      for (const [k, v] of Object.entries(baseEnv)) {
+        if (typeof v === 'string') env[k] = v;
+      }
+      if (options.serviceAccountToken !== undefined) {
+        env.OP_SERVICE_ACCOUNT_TOKEN = options.serviceAccountToken;
+      }
+      if (options.connect !== undefined) {
+        env.OP_CONNECT_HOST = options.connect.host;
+        env.OP_CONNECT_TOKEN = options.connect.token;
+      }
+      const started = performance.now();
+      return new Promise<OpCliReadResult>((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        let killedByTimeout = false;
+        let proc: ReturnType<typeof spawn>;
+        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: ReturnType<typeof setTimeout> | undefined;
+        const timer = setTimeout(() => {
+          killedByTimeout = true;
+          try {
+            proc.kill('SIGTERM');
+          } catch {
+            // best-effort
+          }
+          // SPL-22: SIGTERM alone can hang forever if `op` ignores it. Escalate
+          // to SIGKILL after a short grace AND reject from the timer, so the
+          // promise settles even when `close` never fires.
+          graceTimer = setTimeout(() => {
+            try {
+              proc.kill('SIGKILL');
+            } catch {
+              // best-effort
+            }
+            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: Buffer) => {
+          stdout += chunk.toString('utf8');
+        });
+        proc.stderr?.on('data', (chunk: Buffer) => {
+          stderr += chunk.toString('utf8');
+        });
+        proc.on('error', (err) => {
+          clearTimeout(timer);
+          if (graceTimer !== undefined) clearTimeout(graceTimer);
+          if ((err as NodeJS.ErrnoException).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 !== undefined) 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: number, stderr: string): OpCliErrorKind {
+  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: OpCliErrorKind): string {
+  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.';
+  }
+}

package/src/resolver.ts

@@ -0,0 +1,175 @@
+/**
+ * `op://`-scheme `SecretResolver` for the Graphorin framework. Wraps
+ * the official 1Password CLI (`op`) per the canonical `op read` flow
+ * documented at https://developer.1password.com/docs/cli/secrets-references/.
+ *
+ * URI shape (per 1Password): `op://<vault>/<item>/[section/]<field>`.
+ * The resolver accepts any `op://` URI the CLI accepts (the CLI is
+ * the source of truth - we forward verbatim) and rejects only the
+ * obvious malformed cases at parse time.
+ *
+ * 1Password explicitly treats vault / item / field names as
+ * case-insensitive; the resolver normalises the URI by lowercasing the
+ * authority + path before forwarding to the CLI so two configs that
+ * differ only in case resolve to the same value.
+ *
+ * @packageDocumentation
+ */
+
+import type { SecretResolver, SecretResolverContext } from '@graphorin/core/contracts';
+import { type ParsedSecretRef, SecretResolutionError, SecretValue } from '@graphorin/security';
+
+import { createDefaultOpCli, type OpCli, OpCliError } from './op-cli.js';
+
+/** @stable */
+export 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
+ */
+export function createOnePasswordResolver(
+  options: OnePasswordResolverOptions = {},
+): SecretResolver {
+  const cli = options.cli ?? createDefaultOpCli();
+  return {
+    scheme: 'op',
+    async resolve(ref, ctx?: SecretResolverContext): Promise<SecretValue> {
+      void ctx;
+      const parsed = ref as ParsedSecretRef;
+      assertOpRef(parsed);
+      const normalized = options.preserveCase === true ? parsed.raw : normalizeOpUri(parsed.raw);
+      try {
+        const result = await cli.read(normalized, {
+          ...(options.binary !== undefined ? { binary: options.binary } : {}),
+          ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+          ...(options.serviceAccountToken !== undefined
+            ? { serviceAccountToken: options.serviceAccountToken }
+            : {}),
+          ...(options.connect !== undefined ? { connect: options.connect } : {}),
+          ...(options.account !== undefined ? { 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 !== undefined ? ` - 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
+ */
+export const onePasswordResolver: SecretResolver = createOnePasswordResolver();
+
+function assertOpRef(parsed: ParsedSecretRef): void {
+  if (parsed.scheme !== 'op') {
+    throw new SecretResolutionError(
+      'op',
+      parsed.raw,
+      `expected scheme 'op', received '${parsed.scheme}'.`,
+    );
+  }
+  if (parsed.authority === undefined || 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 === undefined || 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
+ */
+export function normalizeOpUri(raw: string): string {
+  // Lowercase only the part up to the first `?` or `#` so query /
+  // fragment components keep their original case (the CLI does not
+  // currently use them, but forward-compat matters).
+  const queryIdx = raw.indexOf('?');
+  const fragIdx = raw.indexOf('#');
+  const cuts = [queryIdx, fragIdx].filter((i) => i >= 0);
+  const split = cuts.length > 0 ? Math.min(...cuts) : raw.length;
+  const head = raw.slice(0, split).toLowerCase();
+  const tail = raw.slice(split);
+  return head + tail;
+}