@agent-vm/secret-management 0.0.71

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Shravan Sunder
+
+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/dist/contracts.d.ts

@@ -0,0 +1,18 @@
+//#region src/contracts.d.ts
+interface MediatedSecretSpec {
+  readonly hosts: readonly string[];
+  readonly value: string;
+}
+type SecretRef = {
+  readonly source: '1password';
+  readonly ref: string;
+} | {
+  readonly source: 'environment';
+  readonly ref: string;
+};
+interface SecretResolver {
+  resolve(ref: SecretRef): Promise<string>;
+  resolveAll(refs: Record<string, SecretRef>): Promise<Record<string, string>>;
+}
+//#endregion
+export { MediatedSecretSpec, SecretRef, SecretResolver };

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { MediatedSecretSpec, SecretRef, SecretResolver } from "./contracts.js";
+import { createStaticSecretResolver } from "./testing.js";
+import { ResolveAllResponse } from "@1password/sdk";
+
+//#region src/composite-secret-resolver.d.ts
+type SecretEnvironment = Readonly<Record<string, string | undefined>>;
+declare function createCompositeSecretResolver(onePasswordResolver: SecretResolver | null, env?: SecretEnvironment): SecretResolver;
+//#endregion
+//#region src/onepassword-secret-resolver.d.ts
+interface SecretResolverClient {
+  readonly secrets: {
+    resolve(secretReference: string): Promise<string>;
+    resolveAll(secretReferences: readonly string[]): Promise<ResolveAllResponse>;
+  };
+}
+type TokenSource = {
+  readonly type: 'op-cli';
+  readonly ref: string;
+} | {
+  readonly type: 'env';
+  readonly envVar?: string | undefined;
+} | {
+  readonly type: 'keychain';
+  readonly service: string;
+  readonly account: string;
+};
+interface ExecFileOptions {
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly input?: string | undefined;
+  readonly redactErrorOutput?: boolean | undefined;
+}
+interface ExecFileResult {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+declare function resolveServiceAccountToken(source: TokenSource, dependencies?: {
+  readonly execFileAsync?: (command: string, args: readonly string[], options?: ExecFileOptions) => Promise<ExecFileResult>;
+}): Promise<string>;
+interface CreateSecretResolverDependencies {
+  readonly createClient?: (config: {
+    auth: string;
+    integrationName: string;
+    integrationVersion: string;
+  }) => Promise<SecretResolverClient>;
+  readonly execFileAsync?: (command: string, args: readonly string[], options?: ExecFileOptions) => Promise<ExecFileResult>;
+  readonly integrationName?: string;
+  readonly integrationVersion?: string;
+}
+declare function createSecretResolver(options: {
+  readonly serviceAccountToken: string;
+}, dependencies?: CreateSecretResolverDependencies): Promise<SecretResolver>;
+declare function createOpCliSecretResolver(options: {
+  readonly serviceAccountToken: string;
+}, dependencies?: Pick<CreateSecretResolverDependencies, 'execFileAsync'>): Promise<SecretResolver>;
+//#endregion
+export { CreateSecretResolverDependencies, ExecFileOptions, ExecFileResult, MediatedSecretSpec, SecretRef, SecretResolver, SecretResolverClient, type TokenSource, createCompositeSecretResolver, createOpCliSecretResolver, createSecretResolver, createStaticSecretResolver, resolveServiceAccountToken };

package/dist/index.js

@@ -0,0 +1,500 @@
+import "./contracts.js";
+import { createStaticSecretResolver } from "./testing.js";
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createClient } from "@1password/sdk";
+//#region src/composite-secret-resolver.ts
+function resolveEnvironmentSecret(ref, env) {
+	const value = env[ref.ref];
+	if (value === void 0) throw new Error(`Environment variable '${ref.ref}' is not set.`);
+	if (value.trim().length === 0) throw new Error(`Environment variable '${ref.ref}' is set but empty.`);
+	return value;
+}
+function formatUnknownError$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function createSecretResolutionError(options) {
+	return new Error(`Failed to resolve secret '${options.secretName}' from '${options.ref.ref}': ${formatUnknownError$1(options.cause)}`, { cause: options.cause });
+}
+function throwAggregateSecretResolutionError(failures) {
+	if (failures.length > 0) throw new AggregateError(failures, `Failed to resolve ${String(failures.length)} secret(s).`);
+}
+function extractAggregateErrors(error) {
+	return (Array.isArray(error.errors) ? error.errors : [error]).map((failure) => failure instanceof Error ? failure : new Error(formatUnknownError$1(failure), { cause: failure }));
+}
+function createCompositeSecretResolver(onePasswordResolver, env = process.env) {
+	return {
+		async resolve(ref) {
+			switch (ref.source) {
+				case "environment": return resolveEnvironmentSecret(ref, env);
+				case "1password":
+					if (!onePasswordResolver) throw new Error("Secret with source '1password' requires host.secretsProvider to be configured.");
+					return await onePasswordResolver.resolve(ref);
+				default: throw new Error(`Unsupported secret source: ${JSON.stringify(ref)}`);
+			}
+		},
+		async resolveAll(refs) {
+			const resolved = {};
+			const onePasswordRefs = {};
+			const failures = [];
+			for (const [name, ref] of Object.entries(refs)) switch (ref.source) {
+				case "environment":
+					try {
+						resolved[name] = resolveEnvironmentSecret(ref, env);
+					} catch (error) {
+						failures.push(createSecretResolutionError({
+							cause: error,
+							ref,
+							secretName: name
+						}));
+					}
+					break;
+				case "1password":
+					onePasswordRefs[name] = ref;
+					break;
+				default: throw new Error(`Unsupported secret source: ${JSON.stringify(ref)}`);
+			}
+			if (Object.keys(onePasswordRefs).length > 0) if (!onePasswordResolver) failures.push(...Object.entries(onePasswordRefs).map(([name, ref]) => createSecretResolutionError({
+				cause: /* @__PURE__ */ new Error("Secret with source '1password' requires host.secretsProvider to be configured."),
+				ref,
+				secretName: name
+			})));
+			else {
+				const resolver = onePasswordResolver;
+				try {
+					Object.assign(resolved, await resolver.resolveAll(onePasswordRefs));
+				} catch (error) {
+					if (error instanceof AggregateError) failures.push(...extractAggregateErrors(error));
+					else failures.push(...Object.entries(onePasswordRefs).map(([name, ref]) => createSecretResolutionError({
+						cause: error,
+						ref,
+						secretName: name
+					})));
+				}
+			}
+			throwAggregateSecretResolutionError(failures);
+			return resolved;
+		}
+	};
+}
+//#endregion
+//#region src/onepassword-secret-resolver.ts
+function formatUnknownError(error) {
+	if (error instanceof AggregateError) {
+		const childMessages = readAggregateErrorChildren(error).map(formatUnknownError);
+		if (childMessages.length === 0) return error.message;
+		const separator = error.message.endsWith(".") ? "" : ".";
+		return `${error.message}${separator} Details: ${childMessages.join("; ")}`;
+	}
+	return error instanceof Error ? error.message : String(error);
+}
+var RedactedExecFileError = class extends Error {
+	safeDetail;
+	constructor(message, safeDetail, options) {
+		super(message, options);
+		this.safeDetail = safeDetail;
+		this.name = "RedactedExecFileError";
+	}
+};
+var OpInjectOutputError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OpInjectOutputError";
+	}
+};
+function formatErrorMetadataValue(value) {
+	if (typeof value === "number" || typeof value === "string") return String(value);
+}
+function readErrorCode(error) {
+	if (!("code" in error)) return;
+	return formatErrorMetadataValue(error.code);
+}
+function readErrorSignal(error) {
+	if (!("signal" in error)) return;
+	return formatErrorMetadataValue(error.signal);
+}
+function formatRedactedExecErrorDetail(error) {
+	const exitCode = readErrorCode(error) ?? "unknown";
+	const signal = readErrorSignal(error);
+	return signal === void 0 ? `exit code ${exitCode}` : `exit code ${exitCode}, signal ${signal}`;
+}
+function createExecFileError(options) {
+	if (options.redactErrorOutput) {
+		const safeDetail = formatRedactedExecErrorDetail(options.error);
+		return new RedactedExecFileError(`${options.command} failed: ${safeDetail}`, safeDetail);
+	}
+	const errorDetail = options.stderr.trim() || options.error.message;
+	return /* @__PURE__ */ new Error(`${options.command} failed: ${errorDetail}`);
+}
+function formatStdinWriteErrorDetail(error) {
+	const errorCode = readErrorCode(error);
+	return errorCode === void 0 ? "stdin write failed" : `stdin write failed: ${errorCode}`;
+}
+function createStdinWriteError(command, error, redactErrorOutput) {
+	if (redactErrorOutput) {
+		const safeDetail = formatStdinWriteErrorDetail(error);
+		return new RedactedExecFileError(`${command} failed writing stdin: ${safeDetail}`, safeDetail, { cause: error });
+	}
+	return new Error(`${command} failed writing stdin: ${formatUnknownError(error)}`, { cause: error });
+}
+function ensureMacOsForKeychain() {
+	if (process.platform !== "darwin") throw new Error("Keychain token source is only supported on macOS. Use an env or op-cli token source on this platform so cmd-ts can surface a clear startup error.");
+}
+function execFileAsync(command, args, options) {
+	return new Promise((resolve, reject) => {
+		let hasSettled = false;
+		const rejectOnce = (error) => {
+			if (hasSettled) return;
+			hasSettled = true;
+			reject(error);
+		};
+		const resolveOnce = (result) => {
+			if (hasSettled) return;
+			hasSettled = true;
+			resolve(result);
+		};
+		const child = execFile(command, [...args], {
+			env: options?.env,
+			timeout: 3e4
+		}, (error, stdout, stderr) => {
+			if (error) {
+				rejectOnce(createExecFileError({
+					command,
+					error,
+					redactErrorOutput: options?.redactErrorOutput,
+					stderr
+				}));
+				return;
+			}
+			resolveOnce({
+				stdout,
+				stderr
+			});
+		});
+		if (options?.input !== void 0) {
+			if (!child.stdin) {
+				child.kill();
+				rejectOnce(/* @__PURE__ */ new Error(`${command} did not expose stdin for input`));
+				return;
+			}
+			child.stdin.once("error", (error) => {
+				child.kill();
+				rejectOnce(createStdinWriteError(command, error, options.redactErrorOutput));
+			});
+			child.stdin.end(options.input);
+		}
+	});
+}
+const SAFE_IDENTIFIER_PATTERN = /^[\w.@-]+$/u;
+async function resolveServiceAccountToken(source, dependencies) {
+	const exec = dependencies?.execFileAsync ?? execFileAsync;
+	switch (source.type) {
+		case "op-cli": {
+			const token = (await exec("op", ["read", source.ref], { redactErrorOutput: true })).stdout.trim();
+			if (token.length === 0) throw new Error("op-cli token resolution returned empty value");
+			return token;
+		}
+		case "env": {
+			const envVar = source.envVar ?? "OP_SERVICE_ACCOUNT_TOKEN";
+			const token = process.env[envVar]?.trim();
+			if (!token) throw new Error(`Environment variable ${envVar} is not set`);
+			return token;
+		}
+		case "keychain": {
+			ensureMacOsForKeychain();
+			if (!SAFE_IDENTIFIER_PATTERN.test(source.service)) throw new Error("Keychain service name contains invalid characters");
+			if (!SAFE_IDENTIFIER_PATTERN.test(source.account)) throw new Error("Keychain account name contains invalid characters");
+			const token = (await exec("security", [
+				"find-generic-password",
+				"-s",
+				source.service,
+				"-a",
+				source.account,
+				"-w"
+			])).stdout.trim();
+			if (token.length === 0) throw new Error("Keychain token resolution returned empty value");
+			return token;
+		}
+		default: throw new Error(`Unsupported token source: ${JSON.stringify(source)}`);
+	}
+}
+async function resolveSecretWithOpCli(serviceAccountToken, secretReference, exec) {
+	return stripOpReadStdoutTerminator((await exec("op", ["read", secretReference], {
+		env: createOpCliServiceAccountEnv(serviceAccountToken),
+		redactErrorOutput: true
+	})).stdout);
+}
+function stripOpReadStdoutTerminator(stdout) {
+	if (stdout.endsWith("\r\n")) return stdout.slice(0, -2);
+	if (stdout.endsWith("\n")) return stdout.slice(0, -1);
+	return stdout;
+}
+const opCliProcessPlumbingEnvNames = [
+	"APPDATA",
+	"ALL_PROXY",
+	"all_proxy",
+	"COMSPEC",
+	"HOME",
+	"HTTP_PROXY",
+	"http_proxy",
+	"HTTPS_PROXY",
+	"https_proxy",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"LOCALAPPDATA",
+	"NO_PROXY",
+	"no_proxy",
+	"PATH",
+	"SSL_CERT_DIR",
+	"SSL_CERT_FILE",
+	"TEMP",
+	"TMP",
+	"TMPDIR",
+	"TZ",
+	"USERPROFILE",
+	"WINDIR",
+	"XDG_CACHE_HOME",
+	"XDG_CONFIG_HOME",
+	"XDG_DATA_HOME",
+	"XDG_RUNTIME_DIR"
+];
+function createOpCliServiceAccountEnv(serviceAccountToken) {
+	const env = {};
+	for (const envName of opCliProcessPlumbingEnvNames) {
+		const envValue = process.env[envName];
+		if (envValue !== void 0) env[envName] = envValue;
+	}
+	env.OP_SERVICE_ACCOUNT_TOKEN = serviceAccountToken;
+	return env;
+}
+const opInjectTemplateDelimiterPattern = /(?:\{\{|\}\})/u;
+function assertOpInjectTemplateSafeReference(entry) {
+	if (!opInjectTemplateDelimiterPattern.test(entry.secretRef.ref) && !entry.secretRef.ref.includes("\0") && !entry.secretRef.ref.includes("\r") && !entry.secretRef.ref.includes("\n")) return;
+	throw new OpInjectOutputError(`op inject template rejected unsafe 1Password reference for secret '${entry.secretName}'.`);
+}
+async function resolveAllSecretsWithOpCli(serviceAccountToken, refs, exec) {
+	try {
+		return await resolveAllSecretsWithOpInject(serviceAccountToken, refs, exec);
+	} catch (error) {
+		const sanitizedInjectError = sanitizeOpInjectError(error);
+		try {
+			return await resolveAllSecretsWithSerialOpReads(serviceAccountToken, refs, exec);
+		} catch (readError) {
+			if (readError instanceof AggregateError) throw createAggregateErrorWithCause({
+				cause: readError,
+				errors: [sanitizedInjectError, ...readAggregateErrorChildren(readError)],
+				message: readError.message
+			});
+			throw createAggregateErrorWithCause({
+				cause: readError,
+				errors: [sanitizedInjectError, readError],
+				message: "op inject and serial op read both failed."
+			});
+		}
+	}
+}
+function sanitizeOpInjectError(error) {
+	if (error instanceof RedactedExecFileError) return /* @__PURE__ */ new Error(`op inject failed before serial op read: ${error.safeDetail}`);
+	if (error instanceof OpInjectOutputError) return /* @__PURE__ */ new Error(`op inject failed before serial op read: ${error.message}`);
+	const errorType = error instanceof Error ? error.name : typeof error;
+	return /* @__PURE__ */ new Error(`op inject failed before serial op read: ${errorType}`);
+}
+function readAggregateErrorChildren(error) {
+	const errorChildren = error.errors;
+	return Array.isArray(errorChildren) ? errorChildren : [];
+}
+function createAggregateErrorWithCause(options) {
+	const aggregateError = new AggregateError(options.errors, options.message);
+	aggregateError.cause = options.cause;
+	return aggregateError;
+}
+function createFallbackStageError(stage, error) {
+	return new Error(`${stage} failed before op CLI fallback: ${formatUnknownError(error)}`, { cause: error });
+}
+function createFallbackFailureError(options) {
+	if (options.fallbackError instanceof AggregateError) return createAggregateErrorWithCause({
+		cause: options.fallbackError,
+		errors: [options.stageError, ...readAggregateErrorChildren(options.fallbackError)],
+		message: options.fallbackError.message
+	});
+	return createAggregateErrorWithCause({
+		cause: options.fallbackError,
+		errors: [options.stageError, options.fallbackError],
+		message: options.message
+	});
+}
+function opInjectStartMarker(markerId) {
+	return `agent-vm-op-inject-start:${markerId}`;
+}
+function opInjectEndMarker(markerId) {
+	return `agent-vm-op-inject-end:${markerId}`;
+}
+function createOpInjectEntries(refs) {
+	return Object.entries(refs).map(([secretName, secretRef]) => ({
+		markerId: randomUUID(),
+		secretName,
+		secretRef
+	}));
+}
+function buildOpInjectTemplate(entries) {
+	return entries.map((entry) => {
+		assertOpInjectTemplateSafeReference(entry);
+		return [
+			opInjectStartMarker(entry.markerId),
+			`{{ ${entry.secretRef.ref} }}`,
+			opInjectEndMarker(entry.markerId)
+		].join("\n");
+	}).join("\n");
+}
+function findUniqueOpInjectMarker(options) {
+	const markerIndex = options.output.indexOf(options.marker);
+	if (markerIndex === -1) throw new OpInjectOutputError(`op inject output omitted ${options.markerDescription} marker for secret '${options.secretName}' (${options.secretReference}).`);
+	if (options.output.indexOf(options.marker, markerIndex + options.marker.length) !== -1) throw new OpInjectOutputError(`op inject output for secret '${options.secretName}' (${options.secretReference}) contained repeated ${options.markerDescription} marker.`);
+	return markerIndex;
+}
+function extractInjectedSecret(options) {
+	const startToken = `${opInjectStartMarker(options.entry.markerId)}\n`;
+	const endToken = `\n${opInjectEndMarker(options.entry.markerId)}`;
+	const secretStartIndex = findUniqueOpInjectMarker({
+		marker: startToken,
+		markerDescription: "start",
+		output: options.output,
+		secretName: options.entry.secretName,
+		secretReference: options.entry.secretRef.ref
+	}) + startToken.length;
+	const secretEndIndex = findUniqueOpInjectMarker({
+		marker: endToken,
+		markerDescription: "end",
+		output: options.output,
+		secretName: options.entry.secretName,
+		secretReference: options.entry.secretRef.ref
+	});
+	return options.output.slice(secretStartIndex, secretEndIndex);
+}
+function mapOpInjectOutput(entries, output) {
+	return Object.fromEntries(entries.map((entry) => [entry.secretName, extractInjectedSecret({
+		entry,
+		output
+	})]));
+}
+async function resolveAllSecretsWithOpInject(serviceAccountToken, refs, exec) {
+	const entries = createOpInjectEntries(refs);
+	if (entries.length === 0) return {};
+	return mapOpInjectOutput(entries, (await exec("op", [
+		"inject",
+		"--in-file",
+		"/dev/stdin"
+	], {
+		env: createOpCliServiceAccountEnv(serviceAccountToken),
+		input: buildOpInjectTemplate(entries),
+		redactErrorOutput: true
+	})).stdout);
+}
+async function resolveAllSecretsWithSerialOpReads(serviceAccountToken, refs, exec) {
+	const resolvedSecrets = {};
+	const failures = [];
+	for (const [secretName, secretRef] of Object.entries(refs)) try {
+		resolvedSecrets[secretName] = await resolveSecretWithOpCli(serviceAccountToken, secretRef.ref, exec);
+	} catch (error) {
+		failures.push(new Error(`Failed to resolve secret '${secretName}' from '${secretRef.ref}' via op read: ${formatUnknownError(error)}`, { cause: error }));
+	}
+	if (failures.length > 0) throw new AggregateError(failures, `Failed to resolve ${String(failures.length)} secret(s) via op read.`);
+	return resolvedSecrets;
+}
+function formatResolveReferenceError(error) {
+	return "message" in error && typeof error.message === "string" ? `${error.type}: ${error.message}` : error.type;
+}
+function readSdkBatchSecret(options) {
+	const individualResponse = options.response.individualResponses[options.secretReference];
+	if (!individualResponse) throw new Error(`1Password SDK resolveAll response omitted '${options.secretName}' (${options.secretReference}).`);
+	if (individualResponse.content !== void 0) return individualResponse.content.secret;
+	if (individualResponse.error !== void 0) throw new Error(`1Password SDK resolveAll failed for '${options.secretName}' (${options.secretReference}): ${formatResolveReferenceError(individualResponse.error)}`);
+	throw new Error(`1Password SDK resolveAll returned neither content nor error for '${options.secretName}' (${options.secretReference}).`);
+}
+function mapSdkResolveAllResponse(refs, response) {
+	return Object.fromEntries(Object.entries(refs).map(([secretName, secretRef]) => [secretName, readSdkBatchSecret({
+		response,
+		secretName,
+		secretReference: secretRef.ref
+	})]));
+}
+async function createSecretResolver(options, dependencies = {}) {
+	const exec = dependencies.execFileAsync ?? execFileAsync;
+	try {
+		const client = await (dependencies.createClient ?? createClient)({
+			auth: options.serviceAccountToken,
+			integrationName: dependencies.integrationName ?? "agent-vm",
+			integrationVersion: dependencies.integrationVersion ?? "0.0.1"
+		});
+		return {
+			resolve: async (ref) => {
+				try {
+					return await client.secrets.resolve(ref.ref);
+				} catch (error) {
+					const sdkResolveError = createFallbackStageError("1Password SDK resolve", error);
+					try {
+						return await resolveSecretWithOpCli(options.serviceAccountToken, ref.ref, exec);
+					} catch (fallbackError) {
+						throw createFallbackFailureError({
+							fallbackError,
+							message: "1Password SDK resolve and op CLI fallback both failed.",
+							stageError: sdkResolveError
+						});
+					}
+				}
+			},
+			resolveAll: async (refs) => {
+				try {
+					return mapSdkResolveAllResponse(refs, await client.secrets.resolveAll(Object.values(refs).map((secretRef) => secretRef.ref)));
+				} catch (error) {
+					const sdkResolveAllError = createFallbackStageError("1Password SDK resolveAll", error);
+					try {
+						return await resolveAllSecretsWithOpCli(options.serviceAccountToken, refs, exec);
+					} catch (fallbackError) {
+						throw createFallbackFailureError({
+							fallbackError,
+							message: "1Password SDK resolveAll and op CLI fallback both failed.",
+							stageError: sdkResolveAllError
+						});
+					}
+				}
+			}
+		};
+	} catch (error) {
+		const sdkClientCreationError = createFallbackStageError("1Password SDK client creation", error);
+		return {
+			resolve: async (ref) => {
+				try {
+					return await resolveSecretWithOpCli(options.serviceAccountToken, ref.ref, exec);
+				} catch (fallbackError) {
+					throw createFallbackFailureError({
+						fallbackError,
+						message: "1Password SDK client creation and op CLI fallback both failed.",
+						stageError: sdkClientCreationError
+					});
+				}
+			},
+			resolveAll: async (refs) => {
+				try {
+					return await resolveAllSecretsWithOpCli(options.serviceAccountToken, refs, exec);
+				} catch (fallbackError) {
+					throw createFallbackFailureError({
+						fallbackError,
+						message: "1Password SDK client creation and op CLI fallback both failed.",
+						stageError: sdkClientCreationError
+					});
+				}
+			}
+		};
+	}
+}
+async function createOpCliSecretResolver(options, dependencies = {}) {
+	const exec = dependencies.execFileAsync ?? execFileAsync;
+	return {
+		resolve: async (ref) => await resolveSecretWithOpCli(options.serviceAccountToken, ref.ref, exec),
+		resolveAll: async (refs) => await resolveAllSecretsWithOpCli(options.serviceAccountToken, refs, exec)
+	};
+}
+//#endregion
+export { createCompositeSecretResolver, createOpCliSecretResolver, createSecretResolver, createStaticSecretResolver, resolveServiceAccountToken };

package/dist/testing.d.ts

@@ -0,0 +1,6 @@
+import { SecretResolver } from "./contracts.js";
+
+//#region src/testing.d.ts
+declare function createStaticSecretResolver(values: Readonly<Record<string, string>>): SecretResolver;
+//#endregion
+export { createStaticSecretResolver };

package/dist/testing.js

@@ -0,0 +1,16 @@
+//#region src/testing.ts
+function createStaticSecretResolver(values) {
+	const resolve = async (ref) => {
+		const value = values[ref.ref];
+		if (value === void 0) throw new Error(`No test secret value configured for '${ref.ref}'.`);
+		return value;
+	};
+	return {
+		resolve,
+		resolveAll: async (refs) => {
+			return Object.fromEntries(await Promise.all(Object.entries(refs).map(async ([name, ref]) => [name, await resolve(ref)])));
+		}
+	};
+}
+//#endregion
+export { createStaticSecretResolver };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agent-vm/secret-management",
+  "version": "0.0.71",
+  "description": "Shared secret reference contracts and resolvers for agent-vm packages.",
+  "homepage": "https://github.com/ShravanSunder/agent-vm#readme",
+  "bugs": {
+    "url": "https://github.com/ShravanSunder/agent-vm/issues"
+  },
+  "license": "MIT",
+  "author": "Shravan Sunder <ShravanSunder@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShravanSunder/agent-vm.git",
+    "directory": "packages/secret-management"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@1password/sdk": "^0.4.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}