@optique/keyring 1.3.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+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,187 @@
+@optique/keyring
+================
+
+Operating-system credential-store password fallback for [Optique].
+
+Use this package to read secrets from the keyring, with hidden password input
+for interactive commands or environment overrides for API keys. Avoid
+secret-valued CLI options, which can expose values in shell history and
+process listings.
+
+[Optique]: https://optique.dev/
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/keyring jsr:@optique/run jsr:@optique/inquirer
+npm add @optique/keyring @optique/run @optique/inquirer
+pnpm add @optique/keyring @optique/run @optique/inquirer
+yarn add @optique/keyring @optique/run @optique/inquirer
+bun add @optique/keyring @optique/run @optique/inquirer
+~~~~
+
+
+Quick start
+-----------
+
+Keyring lookups are asynchronous. Register the context with `runAsync()`
+through `contexts`, or the fallback cannot read the password. Use `fail()`
+to accept no CLI value and prompt only when the keyring has no password:
+
+~~~~ typescript
+import { object } from "@optique/core/constructs";
+import { fail } from "@optique/core/primitives";
+import { prompt } from "@optique/inquirer";
+import { bindKeyring, createKeyringContext } from "@optique/keyring";
+import { runAsync } from "@optique/run";
+
+const keyringContext = createKeyringContext();
+
+const parser = object({
+  password: prompt(
+    bindKeyring(fail<string>(), {
+      context: keyringContext,
+      service: "com.example.myapp",
+      username: "current-user",
+    }),
+    {
+      type: "password",
+      message: "Password:",
+      mask: false,
+    },
+  ),
+});
+
+const options = await runAsync(parser, {
+  contexts: [keyringContext],
+});
+~~~~
+
+The keyring is checked first. A missing password opens a prompt with hidden
+input; credential-store errors reject the parse without prompting. Entered
+passwords are used for this run only. Store a password for your service and
+username using your operating system's credential manager: this package does
+not write or delete credentials.
+
+
+Priority with environment variables
+-----------------------------------
+
+For API keys, put `bindEnv()` outside `bindKeyring()` so an environment
+variable wins over the credential store. Install *@optique/env* for this
+example. Using `fail<string>()` keeps the API key out of CLI arguments;
+this parser never prompts:
+
+~~~~ typescript
+import { fail } from "@optique/core/primitives";
+import { string } from "@optique/core/valueparser";
+import { bindEnv, createEnvContext } from "@optique/env";
+import { bindKeyring, createKeyringContext } from "@optique/keyring";
+import { runAsync } from "@optique/run";
+
+const envContext = createEnvContext({ prefix: "MYAPP_" });
+const keyringContext = createKeyringContext();
+
+const apiKey = bindEnv(
+  bindKeyring(fail<string>(), {
+    context: keyringContext,
+    service: "com.example.myapp.api-key",
+    username: "current-user",
+  }),
+  {
+    context: envContext,
+    key: "API_KEY",
+    parser: string(),
+  },
+);
+
+const secret = await runAsync(apiKey, {
+  contexts: [envContext, keyringContext],
+});
+~~~~
+
+This checks `MYAPP_API_KEY`, then the keyring, and fails if neither supplies
+an API key. Register both contexts. See the [API key example] for more detail.
+Environment variables can still be exposed or inherited; inject them through
+your automation's secret manager instead of typing literal keys into commands.
+
+[API key example]: https://optique.dev/integrations/keyring#priority-with-environment-variables
+
+
+Custom sources
+--------------
+
+Pass an asynchronous `source` to `createKeyringContext()` for tests, alternate
+credential backends, or runtimes that supply their own password reader. Return
+`undefined` only when that source has no password, and reject on lookup errors.
+
+~~~~ typescript
+import { createKeyringContext } from "@optique/keyring";
+
+const keyringContext = createKeyringContext({
+  source: () => Promise.resolve("test-password"),
+});
+~~~~
+
+
+Runtime setup
+-------------
+
+The password backend is loaded only when a lookup is needed. On Linux, the
+default source connects to Secret Service over the user's D-Bus session bus.
+Other platforms use the asynchronous `@napi-rs/keyring` API. Node.js and Bun
+use their normal package installations.
+
+Deno runs native Node addons from local `node_modules`. Run a Deno program with
+local modules enabled and grant the permissions used by the native loader
+on platforms using `@napi-rs/keyring`:
+
+~~~~ bash
+deno run --node-modules-dir=auto --allow-env --allow-sys \
+  --allow-read=node_modules --allow-ffi=node_modules main.ts
+~~~~
+
+On Linux, grant access to the session bus instead. For a standard session bus
+at `$XDG_RUNTIME_DIR/bus`:
+
+~~~~ bash
+deno run --node-modules-dir=auto --allow-env --allow-sys --allow-net \
+  --allow-read="node_modules,$XDG_RUNTIME_DIR/bus" \
+  --allow-write="$XDG_RUNTIME_DIR/bus" main.ts
+~~~~
+
+Use the socket path from `DBUS_SESSION_BUS_ADDRESS` if it differs.
+
+
+Missing credentials and errors
+------------------------------
+
+Missing credentials allow the inner parser to provide a fallback or its usual
+missing-value error. Locked, inaccessible, or ambiguous credentials reject the
+parse, including under `optional()` or `withDefault()`. Secret Service
+connection and lookup errors are propagated without switching stores.
+If the inner parser provides a validation hook, it is applied to stored
+passwords. `fail<string>()` has no value validation of its own.
+
+Stored-password validation failures use a generic message so the password
+cannot appear in error output. If a validation hook throws or rejects, it is
+replaced with a `TypeError` without the original message or cause.
+
+The macOS backend does not provide Touch ID authentication. A custom source can
+supply an alternative backend.
+
+
+Documentation
+-------------
+
+See the [keyring integration guide] for the complete usage guide.
+
+[keyring integration guide]: https://optique.dev/integrations/keyring
+
+
+License
+-------
+
+MIT License. See [LICENSE](../../LICENSE) for details.

package/dist/chunk-CUT6urMc.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/index.cjs

@@ -0,0 +1,327 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const __optique_core_annotations = require_chunk.__toESM(require("@optique/core/annotations"));
+const __optique_core_dependency_runtime = require_chunk.__toESM(require("@optique/core/dependency-runtime"));
+const __optique_core_extension = require_chunk.__toESM(require("@optique/core/extension"));
+const __optique_core_fluent = require_chunk.__toESM(require("@optique/core/fluent"));
+const __optique_core_message = require_chunk.__toESM(require("@optique/core/message"));
+
+//#region src/context.ts
+async function defaultKeyringSource(service, username) {
+	if (process.platform === "linux") {
+		const { readLinuxPassword } = await Promise.resolve().then(() => require("./linux-CtEKvJ1E.cjs"));
+		return await readLinuxPassword(service, username);
+	}
+	const { AsyncEntry } = await import("@napi-rs/keyring");
+	return await new AsyncEntry(service, username).getPassword() ?? void 0;
+}
+function getTypeName$1(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/**
+* Creates a single-pass context for keyring-backed parser fallbacks.
+*
+* The selected source is snapshotted into parse annotations. Creating the
+* context and collecting its annotations never reads the credential store.
+* On Linux, passwords are read from Secret Service without switching stores
+* on errors. Other platforms use `@napi-rs/keyring`.
+*
+* @param options Optional custom source configuration.
+* @returns A keyring context with a unique annotation identity.
+* @throws {TypeError} If `source` is present but is not a function.
+* @since 1.3.0
+*/
+function createKeyringContext(options = {}) {
+	const rawSource = options.source;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${getTypeName$1(rawSource)}.`);
+	const source = rawSource ?? defaultKeyringSource;
+	const contextId = Symbol(`@optique/keyring context:${Math.random()}`);
+	return {
+		id: contextId,
+		source,
+		phase: "single-pass",
+		getAnnotations() {
+			return { [contextId]: { source } };
+		},
+		[Symbol.dispose]() {}
+	};
+}
+
+//#endregion
+//#region src/internal.ts
+function createRunLookup() {
+	const cacheByRun = /* @__PURE__ */ new WeakMap();
+	return (results, path, lookup) => {
+		if (results == null) return lookup();
+		let cache = cacheByRun.get(results);
+		if (cache == null) {
+			cache = {
+				values: /* @__PURE__ */ new Map(),
+				symbolIds: /* @__PURE__ */ new Map()
+			};
+			cacheByRun.set(results, cache);
+		}
+		const { values, symbolIds } = cache;
+		const key = (path ?? []).map((segment) => {
+			if (typeof segment === "symbol") {
+				let id = symbolIds.get(segment);
+				if (id == null) {
+					id = symbolIds.size;
+					symbolIds.set(segment, id);
+				}
+				return `y${id}:`;
+			}
+			const tag = typeof segment === "number" ? "n" : "s";
+			const text = String(segment);
+			return `${tag}${text.length}:${text}`;
+		}).join("");
+		const cached = values.get(key);
+		if (cached != null) return cached;
+		const pending = Promise.resolve().then(lookup);
+		values.set(key, pending);
+		return pending;
+	};
+}
+function withAnnotatedInnerState(sourceState, innerState, run, inheritPrimitiveAnnotations = false) {
+	const annotations = (0, __optique_core_annotations.getAnnotations)(sourceState);
+	const innerStateIsObject = innerState != null && typeof innerState === "object";
+	if (annotations == null || (0, __optique_core_annotations.getAnnotations)(innerState) != null || !innerStateIsObject && !inheritPrimitiveAnnotations) return run(innerState);
+	const inheritedState = (0, __optique_core_extension.inheritAnnotations)(sourceState, innerState);
+	if (inheritedState !== innerState) return run(inheritedState);
+	return innerStateIsObject ? run((0, __optique_core_extension.withAnnotationView)(innerState, annotations)) : run(innerState);
+}
+
+//#endregion
+//#region src/parser.ts
+const stateKey = Symbol("@optique/keyring/bindState");
+function getTypeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function isSourceData(value) {
+	return value != null && typeof value === "object" && "source" in value && typeof value.source === "function";
+}
+/**
+* Adds an asynchronous keyring fallback to a string parser.
+*
+* Values resolve in CLI, keyring, then inner-parser fallback order. The
+* credential store is read only during demanded completion, and one lookup is
+* shared by the same wrapper occurrence across all passes of a run.
+* Stored-password validation failures use a generic message to keep the
+* credential out of error output.
+*
+* @param parser String parser whose CLI behavior and fallback are preserved.
+* @param options Keyring context and lookup identity.
+* @returns An always-async fluent parser with keyring fallback behavior.
+* @throws {TypeError} If `service` or `username` is not a string, or if stored
+* password validation throws. Validation exceptions are replaced with a
+* generic error without the original message or cause.
+* @throws Propagates password-source and inner completion errors unchanged.
+* @since 1.3.0
+*/
+function bindKeyring(parser, options) {
+	if (typeof options.service !== "string") throw new TypeError(`Expected service to be a string, but got: ${getTypeName(options.service)}.`);
+	if (typeof options.username !== "string") throw new TypeError(`Expected username to be a string, but got: ${getTypeName(options.username)}.`);
+	const stateId = Symbol("@optique/keyring/binding");
+	const isBindState = (value) => value != null && typeof value === "object" && stateKey in value && value[stateKey] === stateId;
+	const parserInheritsAnnotations = (0, __optique_core_extension.getTraits)(parser).inheritsAnnotations === true;
+	const lookupOnce = createRunLookup();
+	const innerState = (state) => isBindState(state) ? state.cliState : parser.initialState;
+	const withInnerState = (state, run) => withAnnotatedInnerState(state, innerState(state), run, parserInheritsAnnotations);
+	const innerNodes = (state, path = []) => withInnerState(state, (annotatedState) => parser.getSuggestRuntimeNodes?.(annotatedState, path) ?? []);
+	const isInnerDemanded = (state, exec) => innerNodes(state, exec?.path).some((node) => {
+		const id = node.parser.dependencyMetadata?.source?.sourceId;
+		return id != null && exec?.effectfulCompletionSession?.demanded.has(id) === true;
+	});
+	const preparedKey = (path = []) => (0, __optique_core_dependency_runtime.serializeSchedulingPath)([stateId, ...path]);
+	const isPreparedInner = (value) => value != null && typeof value === "object" && stateKey in value && value[stateKey] === stateId;
+	const completeInner = (state, exec) => {
+		const prepared = exec?.effectfulCompletionSession?.preparedByPath.get(preparedKey(exec.path));
+		if (isPreparedInner(prepared)) return Promise.resolve(prepared.result);
+		return Promise.resolve(withInnerState(state, (annotatedState) => parser.complete(annotatedState, exec)));
+	};
+	const boundParser = {
+		mode: "async",
+		$valueType: parser.$valueType,
+		$stateType: [],
+		priority: parser.priority,
+		usage: parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		initialState: {
+			[stateKey]: stateId,
+			hasCliValue: false,
+			cliState: parser.initialState
+		},
+		canSkip(state, exec) {
+			if (!(isBindState(state) && state.hasCliValue) && isSourceData((0, __optique_core_annotations.getAnnotations)(state)?.[options.context.id])) return true;
+			return withInnerState(state, (annotatedState) => parser.canSkip?.(annotatedState, exec) === true);
+		},
+		getSuggestRuntimeNodes(state, path) {
+			return (0, __optique_core_extension.delegateSuggestNodes)(parser, boundParser, state, path, innerState(state), "prepend");
+		},
+		async parse(context) {
+			const annotations = (0, __optique_core_annotations.getAnnotations)(context.state);
+			const state = innerState(context.state);
+			const result = await withInnerState(context.state, (annotatedState) => parser.parse({
+				...context,
+				state: annotatedState
+			}));
+			if (!result.success && result.consumed > 0) return result;
+			const consumedOnlyTerminator = result.success && !context.optionsTerminated && result.next.optionsTerminated && result.consumed.length === 1 && result.consumed[0] === "--";
+			const nextState = (0, __optique_core_extension.injectAnnotations)({
+				[stateKey]: stateId,
+				hasCliValue: isBindState(context.state) && context.state.hasCliValue || result.success && result.consumed.length > 0 && !consumedOnlyTerminator,
+				cliState: result.success ? result.next.state : state
+			}, annotations);
+			return {
+				success: true,
+				...result.success && result.provisional ? { provisional: true } : {},
+				next: {
+					...result.success ? result.next : context,
+					state: nextState
+				},
+				consumed: result.success ? result.consumed : []
+			};
+		},
+		async complete(state, exec) {
+			if (isBindState(state) && state.hasCliValue) return await completeInner(state, exec);
+			const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+			const sourceData = annotations?.[options.context.id];
+			if (exec != null && exec.phase !== "complete") {
+				if (isSourceData(sourceData)) return {
+					success: true,
+					value: "",
+					deferred: true
+				};
+				return await completeInner(state, exec);
+			}
+			if (!isSourceData(sourceData)) {
+				const innerResult = await completeInner(state, exec);
+				return annotations != null && !innerResult.success ? {
+					success: false,
+					error: __optique_core_message.message`Keyring password could not be read: the keyring context was not passed to run()'s contexts option.`
+				} : innerResult;
+			}
+			const session = exec?.effectfulCompletionSession;
+			const sourceId = boundParser.dependencyMetadata?.source?.sourceId;
+			if (session?.policy === "demand-only" && (sourceId == null ? !isInnerDemanded(state, exec) : !session.demanded.has(sourceId))) return {
+				success: true,
+				value: "",
+				deferred: true
+			};
+			const value = await lookupOnce(session?.results, exec?.path, () => sourceData.source(options.service, options.username));
+			if (value === void 0) return await completeInner(state, exec);
+			let result;
+			try {
+				result = typeof parser.validateValue === "function" ? await parser.validateValue(value) : {
+					success: true,
+					value
+				};
+			} catch {
+				throw new TypeError("The password from the keyring could not be validated.");
+			}
+			if (!result.success) return {
+				success: false,
+				error: __optique_core_message.message`The password from the keyring failed validation.`
+			};
+			if (sourceId != null) session?.effectfulSources.add(sourceId);
+			return result;
+		},
+		async *suggest(context, prefix) {
+			const suggestions = withInnerState(context.state, (annotatedState) => parser.suggest({
+				...context,
+				state: annotatedState
+			}, prefix));
+			yield* suggestions;
+		},
+		getDocFragments(state, upperDefaultValue) {
+			if (state.kind === "unavailable") return parser.getDocFragments(state, upperDefaultValue);
+			return withInnerState(state.state, (annotatedState) => parser.getDocFragments({
+				kind: "available",
+				state: annotatedState
+			}, upperDefaultValue));
+		},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: (state, exec) => withInnerState(state, (annotatedState) => parser.shouldDeferCompletion?.(annotatedState, exec) === true) } : {}
+	};
+	(0, __optique_core_extension.defineTraits)(boundParser, {
+		inheritsAnnotations: true,
+		completesFromSource: true
+	});
+	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
+		get: () => parser.placeholder,
+		configurable: true,
+		enumerable: false
+	});
+	for (const hook of ["normalizeValue", "validateValue"]) if (typeof parser[hook] === "function") Object.defineProperty(boundParser, hook, {
+		value: parser[hook].bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = (0, __optique_core_extension.mapSourceMetadata)(parser, (source) => ({
+		...source,
+		extractSourceValue: (state) => {
+			if (!(isBindState(state) && state.hasCliValue) && isSourceData((0, __optique_core_annotations.getAnnotations)(state)?.[options.context.id])) return void 0;
+			return source.extractSourceValue(isBindState(state) ? state.cliState : state);
+		},
+		completeSource: source.preservesSourceValue === false ? void 0 : async (state, exec) => await boundParser.complete(isBindState(state) ? state : (0, __optique_core_extension.injectAnnotations)(boundParser.initialState, (0, __optique_core_annotations.getAnnotations)(state)), exec)
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
+	(0, __optique_core_dependency_runtime.defineForwardedEffectfulSchedulingNodes)(boundParser, parser, (state) => withInnerState(state, (annotatedState) => annotatedState));
+	const schedulingNodes = boundParser[__optique_core_dependency_runtime.effectfulSchedulingNodesKey];
+	if (schedulingNodes != null) Object.defineProperty(boundParser, __optique_core_dependency_runtime.effectfulSchedulingNodesKey, {
+		value: ((state, path) => {
+			const sourceData = (0, __optique_core_annotations.getAnnotations)(state)?.[options.context.id];
+			if (isBindState(state) && state.hasCliValue || !isSourceData(sourceData)) return schedulingNodes(state, path);
+			const nodes = innerNodes(state, path);
+			const providesSourceIds = /* @__PURE__ */ new Set();
+			const dependencyIds = /* @__PURE__ */ new Set();
+			for (const node of nodes) {
+				const metadata = node.parser.dependencyMetadata;
+				if (metadata?.source != null) providesSourceIds.add(metadata.source.sourceId);
+				for (const id of metadata?.completion?.dependencyIds ?? []) dependencyIds.add(id);
+			}
+			if (providesSourceIds.size === 0) return [];
+			return [{
+				path: path ?? [],
+				parser: {},
+				state,
+				providesSourceIds,
+				barrierCompletionDependencies: {
+					orderingDependencyIds: [...dependencyIds].filter((id) => !providesSourceIds.has(id)),
+					demandEdges: []
+				},
+				prepare: async ({ exec, runtime }) => {
+					if (exec == null) return;
+					if (exec.effectfulCompletionSession?.policy === "demand-only" && !isInnerDemanded(state, exec)) return;
+					const value = await lookupOnce(exec.effectfulCompletionSession?.results, path, () => sourceData.source(options.service, options.username));
+					if (value !== void 0) return;
+					const result = await completeInner(isBindState(state) ? state : (0, __optique_core_extension.injectAnnotations)(boundParser.initialState, (0, __optique_core_annotations.getAnnotations)(state)), {
+						...exec,
+						path: path ?? [],
+						dependencyRuntime: runtime,
+						dependencyRegistry: runtime.registry
+					});
+					if (!result.success || !result.deferred) exec.effectfulCompletionSession?.preparedByPath.set(preparedKey(path), {
+						[stateKey]: stateId,
+						result
+					});
+					return result.success ? void 0 : result;
+				}
+			}];
+		}),
+		configurable: true,
+		enumerable: false
+	});
+	return (0, __optique_core_fluent.fluent)(boundParser);
+}
+
+//#endregion
+exports.bindKeyring = bindKeyring;
+exports.createKeyringContext = createKeyringContext;

package/dist/index.d.cts

@@ -0,0 +1,90 @@
+import { SourceContext } from "@optique/core/context";
+import { FluentParser } from "@optique/core/fluent";
+import { Mode, Parser } from "@optique/core/parser";
+
+//#region src/context.d.ts
+
+/**
+ * Asynchronous source for reading an OS credential-store password.
+ *
+ * @param service Service name associated with the password.
+ * @param username Username associated with the password.
+ * @returns The stored password, or `undefined` when no password is available.
+ * @throws Propagates credential-store loading and lookup failures.
+ * @since 1.3.0
+ */
+type KeyringSource = (service: string, username: string) => Promise<string | undefined>;
+/**
+ * Options for creating a keyring context.
+ *
+ * @since 1.3.0
+ */
+interface KeyringContextOptions {
+  /** Custom password source, primarily for alternate backends and tests. */
+  readonly source?: KeyringSource;
+}
+/**
+ * Context that provides an asynchronous keyring source to bound parsers.
+ *
+ * @since 1.3.0
+ */
+interface KeyringContext extends SourceContext {
+  /** Password source captured by this context. */
+  readonly source: KeyringSource;
+}
+/**
+ * Creates a single-pass context for keyring-backed parser fallbacks.
+ *
+ * The selected source is snapshotted into parse annotations. Creating the
+ * context and collecting its annotations never reads the credential store.
+ * On Linux, passwords are read from Secret Service without switching stores
+ * on errors. Other platforms use `@napi-rs/keyring`.
+ *
+ * @param options Optional custom source configuration.
+ * @returns A keyring context with a unique annotation identity.
+ * @throws {TypeError} If `source` is present but is not a function.
+ * @since 1.3.0
+ */
+declare function createKeyringContext(options?: KeyringContextOptions): KeyringContext;
+//#endregion
+//#region src/parser.d.ts
+declare const stateKey: unique symbol;
+interface BindState<TState> {
+  readonly [stateKey]: symbol;
+  readonly hasCliValue: boolean;
+  readonly cliState: TState;
+}
+/**
+ * Options for binding a string parser to an OS credential-store password.
+ *
+ * @since 1.3.0
+ */
+interface BindKeyringOptions {
+  /** Registered keyring context that supplies the password source. */
+  readonly context: KeyringContext;
+  /** Service name forwarded to the password source. */
+  readonly service: string;
+  /** Username forwarded to the password source. */
+  readonly username: string;
+}
+/**
+ * Adds an asynchronous keyring fallback to a string parser.
+ *
+ * Values resolve in CLI, keyring, then inner-parser fallback order. The
+ * credential store is read only during demanded completion, and one lookup is
+ * shared by the same wrapper occurrence across all passes of a run.
+ * Stored-password validation failures use a generic message to keep the
+ * credential out of error output.
+ *
+ * @param parser String parser whose CLI behavior and fallback are preserved.
+ * @param options Keyring context and lookup identity.
+ * @returns An always-async fluent parser with keyring fallback behavior.
+ * @throws {TypeError} If `service` or `username` is not a string, or if stored
+ * password validation throws. Validation exceptions are replaced with a
+ * generic error without the original message or cause.
+ * @throws Propagates password-source and inner completion errors unchanged.
+ * @since 1.3.0
+ */
+declare function bindKeyring<M extends Mode, TState>(parser: Parser<M, string, TState>, options: BindKeyringOptions): FluentParser<"async", string, BindState<TState>>;
+//#endregion
+export { type BindKeyringOptions, type KeyringContext, type KeyringContextOptions, type KeyringSource, bindKeyring, createKeyringContext };

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { FluentParser } from "@optique/core/fluent";
+import { SourceContext } from "@optique/core/context";
+import { Mode, Parser } from "@optique/core/parser";
+
+//#region src/context.d.ts
+
+/**
+ * Asynchronous source for reading an OS credential-store password.
+ *
+ * @param service Service name associated with the password.
+ * @param username Username associated with the password.
+ * @returns The stored password, or `undefined` when no password is available.
+ * @throws Propagates credential-store loading and lookup failures.
+ * @since 1.3.0
+ */
+type KeyringSource = (service: string, username: string) => Promise<string | undefined>;
+/**
+ * Options for creating a keyring context.
+ *
+ * @since 1.3.0
+ */
+interface KeyringContextOptions {
+  /** Custom password source, primarily for alternate backends and tests. */
+  readonly source?: KeyringSource;
+}
+/**
+ * Context that provides an asynchronous keyring source to bound parsers.
+ *
+ * @since 1.3.0
+ */
+interface KeyringContext extends SourceContext {
+  /** Password source captured by this context. */
+  readonly source: KeyringSource;
+}
+/**
+ * Creates a single-pass context for keyring-backed parser fallbacks.
+ *
+ * The selected source is snapshotted into parse annotations. Creating the
+ * context and collecting its annotations never reads the credential store.
+ * On Linux, passwords are read from Secret Service without switching stores
+ * on errors. Other platforms use `@napi-rs/keyring`.
+ *
+ * @param options Optional custom source configuration.
+ * @returns A keyring context with a unique annotation identity.
+ * @throws {TypeError} If `source` is present but is not a function.
+ * @since 1.3.0
+ */
+declare function createKeyringContext(options?: KeyringContextOptions): KeyringContext;
+//#endregion
+//#region src/parser.d.ts
+declare const stateKey: unique symbol;
+interface BindState<TState> {
+  readonly [stateKey]: symbol;
+  readonly hasCliValue: boolean;
+  readonly cliState: TState;
+}
+/**
+ * Options for binding a string parser to an OS credential-store password.
+ *
+ * @since 1.3.0
+ */
+interface BindKeyringOptions {
+  /** Registered keyring context that supplies the password source. */
+  readonly context: KeyringContext;
+  /** Service name forwarded to the password source. */
+  readonly service: string;
+  /** Username forwarded to the password source. */
+  readonly username: string;
+}
+/**
+ * Adds an asynchronous keyring fallback to a string parser.
+ *
+ * Values resolve in CLI, keyring, then inner-parser fallback order. The
+ * credential store is read only during demanded completion, and one lookup is
+ * shared by the same wrapper occurrence across all passes of a run.
+ * Stored-password validation failures use a generic message to keep the
+ * credential out of error output.
+ *
+ * @param parser String parser whose CLI behavior and fallback are preserved.
+ * @param options Keyring context and lookup identity.
+ * @returns An always-async fluent parser with keyring fallback behavior.
+ * @throws {TypeError} If `service` or `username` is not a string, or if stored
+ * password validation throws. Validation exceptions are replaced with a
+ * generic error without the original message or cause.
+ * @throws Propagates password-source and inner completion errors unchanged.
+ * @since 1.3.0
+ */
+declare function bindKeyring<M extends Mode, TState>(parser: Parser<M, string, TState>, options: BindKeyringOptions): FluentParser<"async", string, BindState<TState>>;
+//#endregion
+export { type BindKeyringOptions, type KeyringContext, type KeyringContextOptions, type KeyringSource, bindKeyring, createKeyringContext };

package/dist/index.js

@@ -0,0 +1,325 @@
+import { getAnnotations } from "@optique/core/annotations";
+import { defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, serializeSchedulingPath } from "@optique/core/dependency-runtime";
+import { defineTraits, delegateSuggestNodes, getTraits, inheritAnnotations, injectAnnotations, mapSourceMetadata, withAnnotationView } from "@optique/core/extension";
+import { fluent } from "@optique/core/fluent";
+import { message } from "@optique/core/message";
+
+//#region src/context.ts
+async function defaultKeyringSource(service, username) {
+	if (process.platform === "linux") {
+		const { readLinuxPassword } = await import("./linux-C36sbmnq.js");
+		return await readLinuxPassword(service, username);
+	}
+	const { AsyncEntry } = await import("@napi-rs/keyring");
+	return await new AsyncEntry(service, username).getPassword() ?? void 0;
+}
+function getTypeName$1(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/**
+* Creates a single-pass context for keyring-backed parser fallbacks.
+*
+* The selected source is snapshotted into parse annotations. Creating the
+* context and collecting its annotations never reads the credential store.
+* On Linux, passwords are read from Secret Service without switching stores
+* on errors. Other platforms use `@napi-rs/keyring`.
+*
+* @param options Optional custom source configuration.
+* @returns A keyring context with a unique annotation identity.
+* @throws {TypeError} If `source` is present but is not a function.
+* @since 1.3.0
+*/
+function createKeyringContext(options = {}) {
+	const rawSource = options.source;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${getTypeName$1(rawSource)}.`);
+	const source = rawSource ?? defaultKeyringSource;
+	const contextId = Symbol(`@optique/keyring context:${Math.random()}`);
+	return {
+		id: contextId,
+		source,
+		phase: "single-pass",
+		getAnnotations() {
+			return { [contextId]: { source } };
+		},
+		[Symbol.dispose]() {}
+	};
+}
+
+//#endregion
+//#region src/internal.ts
+function createRunLookup() {
+	const cacheByRun = /* @__PURE__ */ new WeakMap();
+	return (results, path, lookup) => {
+		if (results == null) return lookup();
+		let cache = cacheByRun.get(results);
+		if (cache == null) {
+			cache = {
+				values: /* @__PURE__ */ new Map(),
+				symbolIds: /* @__PURE__ */ new Map()
+			};
+			cacheByRun.set(results, cache);
+		}
+		const { values, symbolIds } = cache;
+		const key = (path ?? []).map((segment) => {
+			if (typeof segment === "symbol") {
+				let id = symbolIds.get(segment);
+				if (id == null) {
+					id = symbolIds.size;
+					symbolIds.set(segment, id);
+				}
+				return `y${id}:`;
+			}
+			const tag = typeof segment === "number" ? "n" : "s";
+			const text = String(segment);
+			return `${tag}${text.length}:${text}`;
+		}).join("");
+		const cached = values.get(key);
+		if (cached != null) return cached;
+		const pending = Promise.resolve().then(lookup);
+		values.set(key, pending);
+		return pending;
+	};
+}
+function withAnnotatedInnerState(sourceState, innerState, run, inheritPrimitiveAnnotations = false) {
+	const annotations = getAnnotations(sourceState);
+	const innerStateIsObject = innerState != null && typeof innerState === "object";
+	if (annotations == null || getAnnotations(innerState) != null || !innerStateIsObject && !inheritPrimitiveAnnotations) return run(innerState);
+	const inheritedState = inheritAnnotations(sourceState, innerState);
+	if (inheritedState !== innerState) return run(inheritedState);
+	return innerStateIsObject ? run(withAnnotationView(innerState, annotations)) : run(innerState);
+}
+
+//#endregion
+//#region src/parser.ts
+const stateKey = Symbol("@optique/keyring/bindState");
+function getTypeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function isSourceData(value) {
+	return value != null && typeof value === "object" && "source" in value && typeof value.source === "function";
+}
+/**
+* Adds an asynchronous keyring fallback to a string parser.
+*
+* Values resolve in CLI, keyring, then inner-parser fallback order. The
+* credential store is read only during demanded completion, and one lookup is
+* shared by the same wrapper occurrence across all passes of a run.
+* Stored-password validation failures use a generic message to keep the
+* credential out of error output.
+*
+* @param parser String parser whose CLI behavior and fallback are preserved.
+* @param options Keyring context and lookup identity.
+* @returns An always-async fluent parser with keyring fallback behavior.
+* @throws {TypeError} If `service` or `username` is not a string, or if stored
+* password validation throws. Validation exceptions are replaced with a
+* generic error without the original message or cause.
+* @throws Propagates password-source and inner completion errors unchanged.
+* @since 1.3.0
+*/
+function bindKeyring(parser, options) {
+	if (typeof options.service !== "string") throw new TypeError(`Expected service to be a string, but got: ${getTypeName(options.service)}.`);
+	if (typeof options.username !== "string") throw new TypeError(`Expected username to be a string, but got: ${getTypeName(options.username)}.`);
+	const stateId = Symbol("@optique/keyring/binding");
+	const isBindState = (value) => value != null && typeof value === "object" && stateKey in value && value[stateKey] === stateId;
+	const parserInheritsAnnotations = getTraits(parser).inheritsAnnotations === true;
+	const lookupOnce = createRunLookup();
+	const innerState = (state) => isBindState(state) ? state.cliState : parser.initialState;
+	const withInnerState = (state, run) => withAnnotatedInnerState(state, innerState(state), run, parserInheritsAnnotations);
+	const innerNodes = (state, path = []) => withInnerState(state, (annotatedState) => parser.getSuggestRuntimeNodes?.(annotatedState, path) ?? []);
+	const isInnerDemanded = (state, exec) => innerNodes(state, exec?.path).some((node) => {
+		const id = node.parser.dependencyMetadata?.source?.sourceId;
+		return id != null && exec?.effectfulCompletionSession?.demanded.has(id) === true;
+	});
+	const preparedKey = (path = []) => serializeSchedulingPath([stateId, ...path]);
+	const isPreparedInner = (value) => value != null && typeof value === "object" && stateKey in value && value[stateKey] === stateId;
+	const completeInner = (state, exec) => {
+		const prepared = exec?.effectfulCompletionSession?.preparedByPath.get(preparedKey(exec.path));
+		if (isPreparedInner(prepared)) return Promise.resolve(prepared.result);
+		return Promise.resolve(withInnerState(state, (annotatedState) => parser.complete(annotatedState, exec)));
+	};
+	const boundParser = {
+		mode: "async",
+		$valueType: parser.$valueType,
+		$stateType: [],
+		priority: parser.priority,
+		usage: parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		initialState: {
+			[stateKey]: stateId,
+			hasCliValue: false,
+			cliState: parser.initialState
+		},
+		canSkip(state, exec) {
+			if (!(isBindState(state) && state.hasCliValue) && isSourceData(getAnnotations(state)?.[options.context.id])) return true;
+			return withInnerState(state, (annotatedState) => parser.canSkip?.(annotatedState, exec) === true);
+		},
+		getSuggestRuntimeNodes(state, path) {
+			return delegateSuggestNodes(parser, boundParser, state, path, innerState(state), "prepend");
+		},
+		async parse(context) {
+			const annotations = getAnnotations(context.state);
+			const state = innerState(context.state);
+			const result = await withInnerState(context.state, (annotatedState) => parser.parse({
+				...context,
+				state: annotatedState
+			}));
+			if (!result.success && result.consumed > 0) return result;
+			const consumedOnlyTerminator = result.success && !context.optionsTerminated && result.next.optionsTerminated && result.consumed.length === 1 && result.consumed[0] === "--";
+			const nextState = injectAnnotations({
+				[stateKey]: stateId,
+				hasCliValue: isBindState(context.state) && context.state.hasCliValue || result.success && result.consumed.length > 0 && !consumedOnlyTerminator,
+				cliState: result.success ? result.next.state : state
+			}, annotations);
+			return {
+				success: true,
+				...result.success && result.provisional ? { provisional: true } : {},
+				next: {
+					...result.success ? result.next : context,
+					state: nextState
+				},
+				consumed: result.success ? result.consumed : []
+			};
+		},
+		async complete(state, exec) {
+			if (isBindState(state) && state.hasCliValue) return await completeInner(state, exec);
+			const annotations = getAnnotations(state);
+			const sourceData = annotations?.[options.context.id];
+			if (exec != null && exec.phase !== "complete") {
+				if (isSourceData(sourceData)) return {
+					success: true,
+					value: "",
+					deferred: true
+				};
+				return await completeInner(state, exec);
+			}
+			if (!isSourceData(sourceData)) {
+				const innerResult = await completeInner(state, exec);
+				return annotations != null && !innerResult.success ? {
+					success: false,
+					error: message`Keyring password could not be read: the keyring context was not passed to run()'s contexts option.`
+				} : innerResult;
+			}
+			const session = exec?.effectfulCompletionSession;
+			const sourceId = boundParser.dependencyMetadata?.source?.sourceId;
+			if (session?.policy === "demand-only" && (sourceId == null ? !isInnerDemanded(state, exec) : !session.demanded.has(sourceId))) return {
+				success: true,
+				value: "",
+				deferred: true
+			};
+			const value = await lookupOnce(session?.results, exec?.path, () => sourceData.source(options.service, options.username));
+			if (value === void 0) return await completeInner(state, exec);
+			let result;
+			try {
+				result = typeof parser.validateValue === "function" ? await parser.validateValue(value) : {
+					success: true,
+					value
+				};
+			} catch {
+				throw new TypeError("The password from the keyring could not be validated.");
+			}
+			if (!result.success) return {
+				success: false,
+				error: message`The password from the keyring failed validation.`
+			};
+			if (sourceId != null) session?.effectfulSources.add(sourceId);
+			return result;
+		},
+		async *suggest(context, prefix) {
+			const suggestions = withInnerState(context.state, (annotatedState) => parser.suggest({
+				...context,
+				state: annotatedState
+			}, prefix));
+			yield* suggestions;
+		},
+		getDocFragments(state, upperDefaultValue) {
+			if (state.kind === "unavailable") return parser.getDocFragments(state, upperDefaultValue);
+			return withInnerState(state.state, (annotatedState) => parser.getDocFragments({
+				kind: "available",
+				state: annotatedState
+			}, upperDefaultValue));
+		},
+		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: (state, exec) => withInnerState(state, (annotatedState) => parser.shouldDeferCompletion?.(annotatedState, exec) === true) } : {}
+	};
+	defineTraits(boundParser, {
+		inheritsAnnotations: true,
+		completesFromSource: true
+	});
+	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
+		get: () => parser.placeholder,
+		configurable: true,
+		enumerable: false
+	});
+	for (const hook of ["normalizeValue", "validateValue"]) if (typeof parser[hook] === "function") Object.defineProperty(boundParser, hook, {
+		value: parser[hook].bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = mapSourceMetadata(parser, (source) => ({
+		...source,
+		extractSourceValue: (state) => {
+			if (!(isBindState(state) && state.hasCliValue) && isSourceData(getAnnotations(state)?.[options.context.id])) return void 0;
+			return source.extractSourceValue(isBindState(state) ? state.cliState : state);
+		},
+		completeSource: source.preservesSourceValue === false ? void 0 : async (state, exec) => await boundParser.complete(isBindState(state) ? state : injectAnnotations(boundParser.initialState, getAnnotations(state)), exec)
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
+	defineForwardedEffectfulSchedulingNodes(boundParser, parser, (state) => withInnerState(state, (annotatedState) => annotatedState));
+	const schedulingNodes = boundParser[effectfulSchedulingNodesKey];
+	if (schedulingNodes != null) Object.defineProperty(boundParser, effectfulSchedulingNodesKey, {
+		value: ((state, path) => {
+			const sourceData = getAnnotations(state)?.[options.context.id];
+			if (isBindState(state) && state.hasCliValue || !isSourceData(sourceData)) return schedulingNodes(state, path);
+			const nodes = innerNodes(state, path);
+			const providesSourceIds = /* @__PURE__ */ new Set();
+			const dependencyIds = /* @__PURE__ */ new Set();
+			for (const node of nodes) {
+				const metadata = node.parser.dependencyMetadata;
+				if (metadata?.source != null) providesSourceIds.add(metadata.source.sourceId);
+				for (const id of metadata?.completion?.dependencyIds ?? []) dependencyIds.add(id);
+			}
+			if (providesSourceIds.size === 0) return [];
+			return [{
+				path: path ?? [],
+				parser: {},
+				state,
+				providesSourceIds,
+				barrierCompletionDependencies: {
+					orderingDependencyIds: [...dependencyIds].filter((id) => !providesSourceIds.has(id)),
+					demandEdges: []
+				},
+				prepare: async ({ exec, runtime }) => {
+					if (exec == null) return;
+					if (exec.effectfulCompletionSession?.policy === "demand-only" && !isInnerDemanded(state, exec)) return;
+					const value = await lookupOnce(exec.effectfulCompletionSession?.results, path, () => sourceData.source(options.service, options.username));
+					if (value !== void 0) return;
+					const result = await completeInner(isBindState(state) ? state : injectAnnotations(boundParser.initialState, getAnnotations(state)), {
+						...exec,
+						path: path ?? [],
+						dependencyRuntime: runtime,
+						dependencyRegistry: runtime.registry
+					});
+					if (!result.success || !result.deferred) exec.effectfulCompletionSession?.preparedByPath.set(preparedKey(path), {
+						[stateKey]: stateId,
+						result
+					});
+					return result.success ? void 0 : result;
+				}
+			}];
+		}),
+		configurable: true,
+		enumerable: false
+	});
+	return fluent(boundParser);
+}
+
+//#endregion
+export { bindKeyring, createKeyringContext };

package/dist/linux-C36sbmnq.js

@@ -0,0 +1,81 @@
+import { Buffer } from "node:buffer";
+import { createDecipheriv, createDiffieHellman, hkdfSync } from "node:crypto";
+import { clearTimeout, setTimeout } from "node:timers";
+import { DBusError, Message, Variant, sessionBus } from "@jellybrick/dbus-next";
+
+//#region src/linux.ts
+const destination = "org.freedesktop.secrets";
+const servicePath = "/org/freedesktop/secrets";
+const serviceInterface = "org.freedesktop.Secret.Service";
+const algorithm = "dh-ietf1024-sha256-aes128-cbc-pkcs7";
+const prime = Buffer.from("FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE649286651ECE65381FFFFFFFFFFFFFFFF", "hex");
+/**
+* Reads one matching Secret Service item without selecting another store.
+* @param service Service attribute of the credential.
+* @param username Username attribute of the credential.
+* @param bus Connection owned and closed by this lookup.
+* @returns The password, or undefined after a successful search with no match.
+* @throws If the service is inaccessible, the item is locked or ambiguous,
+* or the session or password cannot be read.
+* @internal
+*/
+async function readLinuxPassword(service, username, bus = sessionBus()) {
+	let timer;
+	const unavailable = new Promise((_, reject) => {
+		const events = bus;
+		events.on("error", (error) => reject(error));
+		timer = setTimeout(() => {
+			reject(new DOMException("The Secret Service password lookup timed out.", "TimeoutError"));
+		}, 3e4);
+	});
+	try {
+		return await Promise.race([readPassword(bus, service, username), unavailable]);
+	} finally {
+		clearTimeout(timer);
+		bus.disconnect();
+	}
+}
+async function call(bus, path, iface, member, signature, body, replySignature) {
+	const reply = await bus.call(new Message({
+		destination,
+		path,
+		interface: iface,
+		member,
+		signature,
+		body: [...body]
+	}));
+	if (reply == null || reply.signature !== replySignature) throw new TypeError("The Secret Service returned an invalid response.");
+	return reply.body;
+}
+async function readPassword(bus, service, username) {
+	const [unlocked, locked] = await call(bus, servicePath, serviceInterface, "SearchItems", "a{ss}", [{
+		service,
+		username
+	}], "aoao");
+	if (!isPaths(unlocked) || !isPaths(locked)) throw new TypeError("The Secret Service returned invalid search results.");
+	const paths = [...new Set([...unlocked, ...locked])];
+	if (paths.length === 0) return void 0;
+	if (paths.length > 1) throw new Error("More than one credential matches the service and username.");
+	if (locked.length > 0) throw new DBusError("org.freedesktop.Secret.Error.IsLocked", "The matching Secret Service credential is locked.");
+	const dh = createDiffieHellman(prime, 2);
+	const [output, session] = await call(bus, servicePath, serviceInterface, "OpenSession", "sv", [algorithm, new Variant("ay", dh.generateKeys())], "vo");
+	if (!(output instanceof Variant) || output.signature !== "ay" || !isBytes(output.value) || typeof session !== "string" || session === "/") throw new TypeError("The Secret Service returned an invalid session.");
+	const key = Buffer.from(hkdfSync("sha256", dh.computeSecret(output.value), "", "", 16));
+	const [secret] = await call(bus, paths[0], "org.freedesktop.Secret.Item", "GetSecret", "o", [session], "(oayays)");
+	if (!Array.isArray(secret) || secret.length !== 4 || secret[0] !== session || !isBytes(secret[1]) || secret[1].length !== 16 || !isBytes(secret[2]) || typeof secret[3] !== "string") throw new TypeError("The Secret Service returned an invalid secret.");
+	const decipher = createDecipheriv("aes-128-cbc", key, secret[1]);
+	const password = Buffer.concat([decipher.update(secret[2]), decipher.final()]);
+	return new TextDecoder("utf-8", {
+		fatal: true,
+		ignoreBOM: true
+	}).decode(password);
+}
+function isPaths(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isBytes(value) {
+	return value instanceof Uint8Array;
+}
+
+//#endregion
+export { readLinuxPassword };

package/dist/linux-CtEKvJ1E.cjs

@@ -0,0 +1,82 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const node_buffer = require_chunk.__toESM(require("node:buffer"));
+const node_crypto = require_chunk.__toESM(require("node:crypto"));
+const node_timers = require_chunk.__toESM(require("node:timers"));
+const __jellybrick_dbus_next = require_chunk.__toESM(require("@jellybrick/dbus-next"));
+
+//#region src/linux.ts
+const destination = "org.freedesktop.secrets";
+const servicePath = "/org/freedesktop/secrets";
+const serviceInterface = "org.freedesktop.Secret.Service";
+const algorithm = "dh-ietf1024-sha256-aes128-cbc-pkcs7";
+const prime = node_buffer.Buffer.from("FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE649286651ECE65381FFFFFFFFFFFFFFFF", "hex");
+/**
+* Reads one matching Secret Service item without selecting another store.
+* @param service Service attribute of the credential.
+* @param username Username attribute of the credential.
+* @param bus Connection owned and closed by this lookup.
+* @returns The password, or undefined after a successful search with no match.
+* @throws If the service is inaccessible, the item is locked or ambiguous,
+* or the session or password cannot be read.
+* @internal
+*/
+async function readLinuxPassword(service, username, bus = (0, __jellybrick_dbus_next.sessionBus)()) {
+	let timer;
+	const unavailable = new Promise((_, reject) => {
+		const events = bus;
+		events.on("error", (error) => reject(error));
+		timer = (0, node_timers.setTimeout)(() => {
+			reject(new DOMException("The Secret Service password lookup timed out.", "TimeoutError"));
+		}, 3e4);
+	});
+	try {
+		return await Promise.race([readPassword(bus, service, username), unavailable]);
+	} finally {
+		(0, node_timers.clearTimeout)(timer);
+		bus.disconnect();
+	}
+}
+async function call(bus, path, iface, member, signature, body, replySignature) {
+	const reply = await bus.call(new __jellybrick_dbus_next.Message({
+		destination,
+		path,
+		interface: iface,
+		member,
+		signature,
+		body: [...body]
+	}));
+	if (reply == null || reply.signature !== replySignature) throw new TypeError("The Secret Service returned an invalid response.");
+	return reply.body;
+}
+async function readPassword(bus, service, username) {
+	const [unlocked, locked] = await call(bus, servicePath, serviceInterface, "SearchItems", "a{ss}", [{
+		service,
+		username
+	}], "aoao");
+	if (!isPaths(unlocked) || !isPaths(locked)) throw new TypeError("The Secret Service returned invalid search results.");
+	const paths = [...new Set([...unlocked, ...locked])];
+	if (paths.length === 0) return void 0;
+	if (paths.length > 1) throw new Error("More than one credential matches the service and username.");
+	if (locked.length > 0) throw new __jellybrick_dbus_next.DBusError("org.freedesktop.Secret.Error.IsLocked", "The matching Secret Service credential is locked.");
+	const dh = (0, node_crypto.createDiffieHellman)(prime, 2);
+	const [output, session] = await call(bus, servicePath, serviceInterface, "OpenSession", "sv", [algorithm, new __jellybrick_dbus_next.Variant("ay", dh.generateKeys())], "vo");
+	if (!(output instanceof __jellybrick_dbus_next.Variant) || output.signature !== "ay" || !isBytes(output.value) || typeof session !== "string" || session === "/") throw new TypeError("The Secret Service returned an invalid session.");
+	const key = node_buffer.Buffer.from((0, node_crypto.hkdfSync)("sha256", dh.computeSecret(output.value), "", "", 16));
+	const [secret] = await call(bus, paths[0], "org.freedesktop.Secret.Item", "GetSecret", "o", [session], "(oayays)");
+	if (!Array.isArray(secret) || secret.length !== 4 || secret[0] !== session || !isBytes(secret[1]) || secret[1].length !== 16 || !isBytes(secret[2]) || typeof secret[3] !== "string") throw new TypeError("The Secret Service returned an invalid secret.");
+	const decipher = (0, node_crypto.createDecipheriv)("aes-128-cbc", key, secret[1]);
+	const password = node_buffer.Buffer.concat([decipher.update(secret[2]), decipher.final()]);
+	return new TextDecoder("utf-8", {
+		fatal: true,
+		ignoreBOM: true
+	}).decode(password);
+}
+function isPaths(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isBytes(value) {
+	return value instanceof Uint8Array;
+}
+
+//#endregion
+exports.readLinuxPassword = readLinuxPassword;

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@optique/keyring",
+  "version": "1.3.0-dev.0",
+  "description": "OS credential-store support for Optique",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "keyring",
+    "credential",
+    "password"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/keyring/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "imports": {
+    "#src/*.ts": {
+      "node": "./dist/*.js",
+      "default": "./src/*.ts"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@jellybrick/dbus-next": "0.11.3",
+    "@napi-rs/keyring": "2.0.0",
+    "@optique/core": "1.3.0"
+  },
+  "devDependencies": {
+    "@optique/env": "1.3.0",
+    "@types/node": "^24.0.0",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "node --test",
+    "test:bun": "bun test",
+    "test:deno": "deno test --allow-read --allow-write --allow-env --allow-run --allow-net --allow-sys",
+    "test-all": "tsdown && node --test && bun test && deno test --allow-read --allow-write --allow-env --allow-run --allow-net --allow-sys"
+  }
+}