@stackstackstack/dsh-credentials-local 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/credentials/credentials-local/README.md
+README.md: 63895d34fe8396d55c1d6ef29b3e3d9a9dc17264
+README.zh.md: 3c60fb7bbf06a0ae9ec905f36a5c543c2fb6af1b

package/README.md

@@ -0,0 +1,71 @@
+# dsh-credentials-local
+
+English | [中文](README.zh.md)
+
+File-backed [credentials](../credentials/README.md) provider: four layers, one honest precedence.
+
+| Layer | Source id | Writable | Wins |
+|---|---|---|---|
+| Inherited process environment | `env` | no | always |
+| `$DSH_HOME/.credentials.yaml` document | `file` | yes (`set`/`unset`) | over both `.env` layers |
+| `<invocation cwd>/.env` | `project-env` | not here | over the user `.env` |
+| `$DSH_HOME/.env` | `user-env` | not here | otherwise |
+
+The launching environment wins because a per-run override (`DEEPSEEK_API_KEY=… dsh`, a CI secret, a container `-e`) is operator intent for this run — and because it cannot be edited from inside, it must be *visibly* read-only: `describe()` reports `source: 'env', writable: false`, and `set`/`unset` reject instead of writing a change the reader would never see.
+
+Everything below it loses to the managed store, so a key written by the Models page takes effect immediately even when an older key sits in a `.env`. Those two layers still resolve when nothing is stored, and `describe()` names them `project-env` or `user-env` with `writable: true` — storing a key replaces them as the effective source.
+
+Under the product CLI, resolution reads the launcher's frozen [environment snapshot](../../util/launch-environment/README.md) rather than `process.env`: only the snapshot can say whether a value came from the launching shell or from a file. A composition the product CLI did not boot has the inherited environment as its only layer, which keeps embedders on the semantics they already had.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `path` | `<harness home>/.credentials.yaml` | Credentials document location. |
+| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home used when `path` is omitted. |
+| `watch` | `true` | Hot-publish external edits. |
+| `debounceMs` | `100` | Watcher write-settle window. |
+
+## The document
+
+A YAML mapping of credential reference to value, and nothing else:
+
+```yaml
+DEEPSEEK_API_KEY: sk-…
+OPENAI_API_KEY: sk-…
+```
+
+The document holds credentials only, so every deviation is a rejection rather than a skipped entry — a silently ignored key would read as "the secret I stored has no effect". A non-mapping root, a key that is not a POSIX identifier, a non-string value, an empty string, a duplicate key, and malformed YAML all fail: loud at boot, and warn-and-keep-the-last-good-snapshot on a live reload. There is no `version` field and no wrapper level; the format is the mapping.
+
+Writes patch the parsed document rather than rebuilding it, so comments and the formatting of every untouched entry survive. A comment directly above an entry is that entry's annotation and is removed with it. Every write first re-reads the document under the cross-process writer lock of [`dsh-atomic-write`](../../util/atomic-write/README.md) and publishes anything it had not observed, then commits atomically with mode `0600` under an owner-only (`0700`) directory — so a concurrent writer or an external edit inside the watcher's debounce window is folded in rather than overwritten. An on-disk document that no longer parses fails the write instead of overwriting content the provider could not understand.
+
+Any string value round-trips, multi-line values included, so no entry is unwritable for want of a quoting style. An empty stored value is absent, per the seam rule — which is why an empty string in the document is rejected outright: `unset` removes a key, it does not blank it.
+
+## Permissions
+
+The provider creates the directory `0700` and creates or atomically replaces the document `0600`. It holds what it *reads* to that same bound: on POSIX a document carrying any group or other permission bit fails before its contents are parsed — at boot and on every reload — and the error names the `chmod 600` repair. Windows has no mode to inspect, so the check is skipped there rather than faked.
+
+## Hot reload
+
+External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. Before Chokidar opens the target, the provider realpaths its deepest existing ancestor and restores any missing suffix; file access and diagnostics retain the configured path, while Windows cannot mix an 8.3 alias with long-form libuv events. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable or invalid document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable or invalid file at boot fails loud.
+
+## Security boundary
+
+The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, and the shipped `workspace-write` file policy confines mutations rather than reads, so they can read this file exactly like any other file the user owns; no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment — unlike `$DSH_HOME/.env`, which is the user's ordinary environment layer (see [app-boot's Harness-home layers](../../boot/app-boot/README.md#profiles)) — so reaching the value takes a deliberate read of a path the agent was not given.
+
+That is discretion, not a boundary. A deployment that must keep provider keys away from its own agent cannot get there with file permissions; an OS-keychain provider — a store the model's processes cannot read at all — is the deferred answer and belongs beside this provider as a sibling package.
+
+## Model Experience
+
+Indirectly, through the consuming LLM adapters: stored values authorize their provider requests, and the adapter owns every model-visible surface.
+
+#### KV Cache effect
+
+No direct invalidation; credentials never enter a request prefix.
+
+## Known Limitations and Deferred Work
+
+- **Same-reference concurrent writes are last-write-wins** — the writer lock and the read-modify-write keep concurrent writers from dropping each other's entries, but two writers editing one reference still resolve to the later write; there is no revision check.
+- **A same-UID process can read the document** — see [Security boundary](#security-boundary): the file-effect sandbox modes do not deny reads, and an OS-keychain provider is deferred.
+- **Environment changes are invisible** — the snapshot is frozen at launch, so a variable exported after startup reaches neither resolution nor `describe`; changing an environment-sourced credential takes a restart.
+- **Atomic, not crash-durable** — inherited from `dsh-atomic-write`; the store re-reads on boot.

package/README.zh.md

@@ -0,0 +1,73 @@
+# dsh-credentials-local
+
+[English](README.md) | 中文
+
+文件型[凭据](../credentials/README.md)提供方：四层来源，一套明确的优先级。
+
+| 层 | 来源 id | 可写 | 优先 |
+|---|---|---|---|
+| 继承的进程环境 | `env` | 否 | 始终优先 |
+| `$DSH_HOME/.credentials.yaml` 文档 | `file` | 是（`set`/`unset`） | 高于两个 `.env` 层 |
+| `<invocation cwd>/.env` | `project-env` | 不在此处 | 高于用户 `.env` |
+| `$DSH_HOME/.env` | `user-env` | 不在此处 | 其余情况 |
+
+启动环境优先，因为按次覆盖（`DEEPSEEK_API_KEY=… dsh`、CI 机密、容器 `-e`）代表本次运行的操作者意图——而它无法从进程内部修改，就必须*可见地*只读：`describe()` 报告 `source: 'env', writable: false`，`set`/`unset` 直接拒绝，而不是写下一个读取方永远看不到的变更。
+
+它之下的所有来源优先级都低于受管存储，因此 Models 页写入的密钥会立即生效，即使某个 `.env` 里还留着更旧的密钥。没有存储任何东西时这两层仍会参与解析，`describe()` 会把来源报告为 `project-env` 或 `user-env` 且 `writable: true`——存入一个密钥就会取代它们成为生效来源。
+
+在产品 CLI（命令行界面）下，解析读取的是启动器冻结的[环境快照](../../util/launch-environment/README.md)而不是 `process.env`：只有快照才说得清某个值来自启动 shell 还是来自某个文件。并非由产品 CLI 启动的组合只有继承环境这一层，这让嵌入方保持它们原有的语义。
+
+## 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `path` | `<harness home>/.credentials.yaml` | 凭据文档位置。 |
+| `dshHome` | `$DSH_HOME` 或 `~/.dsh` | `path` 缺省时使用的 harness home。 |
+| `watch` | `true` | 热发布外部编辑。 |
+| `debounceMs` | `100` | watcher 写入稳定窗口。 |
+
+## 文档本身
+
+一个从凭据引用到值的 YAML mapping，除此之外别无他物：
+
+```yaml
+DEEPSEEK_API_KEY: sk-…
+OPENAI_API_KEY: sk-…
+```
+
+该文档只存放凭据，因此任何偏离都是拒绝，而不是跳过某个条目——被静默忽略的键读起来就是「我存进去的密钥没有生效」。非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败：启动时明确报错，运行期热重载则告警并保留最后可用快照。没有 `version` 字段，也没有包装层；格式就是这个 mapping。
+
+写入是对已解析文档打补丁而不是重建，因此注释与所有未触及条目的排版都会保留。直接位于某条目上方的注释属于该条目的注解，会随它一起删除。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。磁盘上已经无法解析的文档会让写入失败，而不是覆盖提供方读不懂的内容。
+
+任何字符串值都能往返，包括多行值，因此不会再有条目因为缺少可用引号样式而不可写。空的存储值等于不存在（seam 规则）——这也正是文档中的空字符串被直接拒绝的原因：`unset` 删除键，而不是把它置空。
+
+## 权限
+
+提供方以 `0700` 创建目录，以 `0600` 创建或原子替换文档。它对*读取*同样守住这条界线：在 POSIX 上，只要文档带有任何 group 或 other 权限位，就会在解析其内容之前失败——启动时与每次 reload 都检查——并在错误里给出 `chmod 600` 的修复命令。Windows 没有可检查的 mode，因此在那里跳过该检查而不是伪造它。
+
+## 热重载
+
+外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀；文件访问和诊断仍使用配置路径，从而避免 Windows 混用 8.3 别名与 libuv 的长格式事件路径。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
+
+<a id="security-boundary"></a>
+
+## 安全边界
+
+文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../boot/app-boot/README.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
+
+这是审慎，不是边界。必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到；OS 钥匙串提供方——一种模型运行所在进程根本无法读取的存储——才是延后的答案，它应当作为平级包与本提供方并列。
+
+## 模型体验
+
+经由消费它的 LLM（大语言模型）适配器间接生效：存储的值为适配器向提供方发出的请求授权，所有模型可见内容均由适配器负责。
+
+#### KV Cache 影响
+
+无直接失效；凭据绝不进入请求前缀。
+
+## 已知限制与暂缓事项
+
+- **同一引用的并发写入是后写胜出**——写锁加读-改-写让并发写入者不会丢掉彼此的条目，但两个写入者编辑同一个引用时仍以较后的写入为准；没有修订检查。
+- **同 UID 进程可以读取该文档**——见[安全边界](#security-boundary)：文件效果沙箱模式不会拒绝读取，OS 钥匙串提供方仍是延后项。
+- **环境变化不可见**：快照在启动时冻结，因此启动之后 export 的变量既不会进入解析，也不会进入 `describe`；要更换来自环境的凭据需要重启。
+- **原子但不具备崩溃持久性**——继承自 `dsh-atomic-write`；存储在启动时重新读取。

package/lib/index.js

@@ -0,0 +1,398 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { watch } from "chokidar";
+import { mkdir, readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { Document, parseDocument } from "yaml";
+import { withFileLock, writeFileAtomic } from "@stackstackstack/dsh-atomic-write";
+import { canonicalizeWatchPath, resolveDshHome } from "@stackstackstack/dsh-home-paths";
+import { launchEnvironmentOf } from "@stackstackstack/dsh-launch-environment";
+import { CredentialProvider, credentialRef } from "@stackstackstack/dsh-credentials";
+//#region lib/types/index.js
+/**
+* File-backed credentials provider over `$DSH_HOME/.credentials.yaml`, layered
+* against the environment by how much each layer is trusted:
+*
+* ```text
+* inherited process environment      (read-only, wins)
+* > $DSH_HOME/.credentials.yaml      (provider-managed, writable)
+* > <invocation cwd>/.env            (read-only fallback)
+* > $DSH_HOME/.env                   (read-only fallback)
+* ```
+*
+* The inherited environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI
+* secret, or a container `-e` is this run's explicit intent; it cannot be
+* edited from inside, so it must be *visibly* read-only rather than silently
+* shadow writes. Everything below it loses to the managed store, so a key the
+* Models page writes takes effect immediately even when an older key sits in
+* the user's `.env`.
+*
+* The invoking project may supply a key, because the product trusts the
+* project it is launched in. It ranks below the managed store, so a key stored
+* through the Models page is never displaced by one a checkout happens to carry.
+*
+* The file is the provider-managed writable source: every write re-reads the
+* document under a cross-process writer lock before patching only its own key
+* — comments and the formatting of every untouched entry survive — external
+* edits hot-publish through the seam, and each reload replaces the snapshot
+* wholesale so a deleted entry never lingers in memory.
+*
+* The document holds nothing but credentials, which is why it is a strict
+* `CredentialRef`-to-string mapping rather than a dotenv file: a store the
+* Harness owns and never materializes into the environment cannot also serve
+* as the user's environment layer; a store that doubled as the environment
+* layer would shadow non-secret entries behind its precedence, making them
+* silently unreachable.
+* @module @stackstackstack/dsh-credentials-local
+*/
+/** Basename of the credentials document inside the harness home. */
+const CREDENTIALS_FILENAME = ".credentials.yaml";
+/**
+* Resolve the runtime spec from plugin config: an explicit `path` wins,
+* otherwise the document lives at `<harness home>/.credentials.yaml`.
+* @param config - raw plugin config.
+* @returns the resolved file location and watch behavior.
+*/
+function resolveSpec(config) {
+	return {
+		filename: resolve(config.path ?? join(resolveDshHome(config.dshHome), ".credentials.yaml")),
+		watch: config.watch ?? true,
+		debounceMs: config.debounceMs ?? 100
+	};
+}
+/** Permission bits outside the owner; a credentials document must have none of them. */
+const GROUP_OTHER_BITS = 63;
+/**
+* Reject a credentials document other OS users can read, before its contents
+* are read at all. The provider creates and replaces the file at `0600`, but a
+* hand-written or externally generated one carries whatever umask produced it,
+* and silently serving secrets out of a world-readable file would make the
+* mode the provider promises meaningless.
+*
+* POSIX only: Windows has no mode to inspect — its ACLs are not expressible
+* here — so the check is skipped rather than faked, and the file's protection
+* there is whatever the create and replace APIs express.
+* @param filename - absolute path of the document.
+* @throws when the path hierarchy is invalid or the file exists with group or other permission bits set.
+*/
+async function assertOwnerOnly(filename) {
+	let mode;
+	try {
+		mode = (await stat(filename)).mode;
+	} catch (error) {
+		if (!isENOENT(error)) throw error;
+		await canonicalizeWatchPath(filename);
+		return;
+	}
+	/* v8 ignore next -- POSIX coverage cannot take the Windows peer; native Windows coverage does. */
+	if (process.platform === "win32") return;
+	if ((mode & GROUP_OTHER_BITS) === 0) return;
+	throw new Error(`credentials-local: ${filename} is readable beyond its owner (mode ${(mode & 511).toString(8)}); run "chmod 600 ${filename}" before starting again`);
+	/* v8 ignore stop */
+}
+/** Whether a filesystem error means absence; every non-ENOENT failure must surface. */
+function isENOENT(error) {
+	return error?.code === "ENOENT";
+}
+/**
+* Describe one YAML parse failure without quoting the source. The parser's own
+* message embeds the offending line, which here holds a secret.
+* @param error - the parser's error.
+* @returns the error code with its line and column.
+*/
+function describeYamlError(error) {
+	const at = error.linePos?.[0];
+	/* v8 ignore next -- `prettyErrors` populates linePos on every error; the guard answers its optional type */
+	const where = at === void 0 ? "" : ` at line ${String(at.line)}, column ${String(at.col)}`;
+	return `${error.code}${where}`;
+}
+/**
+* Parse one credentials document into its entries. The document is a strict
+* mapping of {@link CredentialRef} to non-empty string: a non-mapping root, a
+* key that is not a POSIX identifier, a non-string value, and an empty string
+* are all rejected rather than skipped, because this file holds nothing but
+* credentials and a silently ignored entry reads as "the key I stored has no
+* effect". Duplicate keys surface as parser errors. An empty document is an
+* empty store.
+* @param text - the document's text.
+* @param filename - absolute path, quoted in errors.
+* @returns the parsed entries, keyed by reference.
+*/
+function parseCredentialsDocument(text, filename) {
+	const document = parseDocument(text, {
+		prettyErrors: true,
+		uniqueKeys: true
+	});
+	if (document.errors.length > 0) throw new Error(`credentials-local: invalid document at ${filename}: ${document.errors.map(describeYamlError).join("; ")}`);
+	const root = document.toJS() ?? {};
+	if (typeof root !== "object" || root === null || Array.isArray(root)) throw new TypeError(`credentials-local: ${filename} must be a mapping of credential reference to value`);
+	const entries = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(root)) {
+		credentialRef(key);
+		if (typeof value !== "string") throw new TypeError(`credentials-local: the value for "${key}" in ${filename} must be a string`);
+		if (value.length === 0) throw new Error(`credentials-local: the value for "${key}" in ${filename} is empty; remove the key instead`);
+		entries.set(key, value);
+	}
+	return entries;
+}
+/**
+* Render the next document text with one reference set or deleted. Editing
+* the parsed document rather than rebuilding it keeps comments and the
+* formatting of every untouched entry; an absent document starts a fresh one.
+* @param text - the current document text, `undefined` while the file is absent.
+* @param ref - the reference to write.
+* @param value - the new value, or `undefined` to delete the key.
+* @returns the text to persist.
+*/
+function renderDocument(text, ref, value) {
+	const document = text === void 0 ? new Document({}) : parseDocument(text);
+	if (value === void 0) document.deleteIn([ref]);
+	else document.setIn([ref], value);
+	return document.toString();
+}
+/** File-backed credentials provider (`$DSH_HOME/.credentials.yaml`). */
+var LocalCredentialProvider = class extends CredentialProvider {
+	config;
+	static Config = z.object({
+		path: z.string(),
+		dshHome: z.string(),
+		watch: z.boolean().default(true),
+		debounceMs: z.number().min(0).default(100)
+	});
+	spec;
+	/**
+	* Raw text of the last read or persisted document; `undefined` while the
+	* file is absent. Watcher events whose content equals this cache are no-ops,
+	* which is also the self-write suppression.
+	*/
+	text;
+	/** Parsed document snapshot; replaced wholesale on every reload. */
+	values = /* @__PURE__ */ new Map();
+	/**
+	* Single exclusive operation chain: watcher reloads and line edits run one
+	* at a time in queue order (settled tail), so an edit can never render from
+	* text a concurrent reload is busy replacing.
+	*/
+	operations = Promise.resolve();
+	/** Set at dispose: refuse new writes and let in-flight work no-op. */
+	closed = false;
+	/** Opaque read of {@link closed}: control flow cannot narrow it across awaits. */
+	isClosed() {
+		return this.closed;
+	}
+	constructor(ctx, config) {
+		super(ctx);
+		this.config = config;
+		this.spec = resolveSpec(config);
+	}
+	/** The inherited-environment value for a reference, or `undefined` when empty or unset. */
+	inherited(ref) {
+		const entry = launchEnvironmentOf(this.ctx).getFrom(ref, ["process"]);
+		return entry !== void 0 && entry.value.length > 0 ? entry.value : void 0;
+	}
+	/**
+	* The `.env` fallback for a reference — below the managed store, never above
+	* it. The invoking project ranks over the user's home file, matching the
+	* environment layering: the more specific location wins.
+	*/
+	dotenvFallback(ref) {
+		const entry = launchEnvironmentOf(this.ctx).getFrom(ref, ["project-env", "user-env"]);
+		return entry !== void 0 && entry.value.length > 0 ? entry : void 0;
+	}
+	async *[Service.init]() {
+		yield async () => {
+			this.closed = true;
+			await this.operations;
+		};
+		await this.loadInitial();
+		if (!this.spec.watch) return;
+		const watcher = watch(await canonicalizeWatchPath(this.spec.filename), {
+			ignoreInitial: true,
+			awaitWriteFinish: {
+				stabilityThreshold: this.spec.debounceMs,
+				pollInterval: Math.max(1, Math.min(this.spec.debounceMs, 10))
+			}
+		});
+		watcher.on("all", () => {
+			if (this.closed) return;
+			this.queueRefresh();
+		});
+		watcher.on("ready", () => {
+			if (this.closed) return;
+			this.queueRefresh();
+		});
+		watcher.on("error", (error) => {
+			this.ctx.logger.warn("credentials-local: watcher error on %s", this.spec.filename);
+			this.ctx.logger.warn(error);
+		});
+		yield async () => {
+			this.closed = true;
+			await watcher.close();
+			await this.operations;
+		};
+	}
+	resolve(ref) {
+		const inherited = this.inherited(ref);
+		if (inherited !== void 0) return Promise.resolve({
+			value: inherited,
+			source: "env"
+		});
+		const stored = this.values.get(ref);
+		if (stored !== void 0) return Promise.resolve({
+			value: stored,
+			source: "file"
+		});
+		const fallback = this.dotenvFallback(ref);
+		if (fallback !== void 0) return Promise.resolve({
+			value: fallback.value,
+			source: fallback.source
+		});
+		return Promise.resolve(void 0);
+	}
+	describe(ref) {
+		if (this.inherited(ref) !== void 0) return Promise.resolve({
+			configured: true,
+			source: "env",
+			writable: false
+		});
+		if (this.values.get(ref) !== void 0) return Promise.resolve({
+			configured: true,
+			source: "file",
+			writable: true
+		});
+		const fallback = this.dotenvFallback(ref);
+		if (fallback !== void 0) return Promise.resolve({
+			configured: true,
+			source: fallback.source,
+			writable: true
+		});
+		return Promise.resolve({
+			configured: false,
+			writable: true
+		});
+	}
+	async set(ref, value) {
+		if (value.length === 0) throw new Error(`credentials-local: an empty value cannot be stored for "${ref}"; use unset`);
+		await this.write(ref, value);
+	}
+	async unset(ref) {
+		await this.write(ref, void 0);
+	}
+	/** Queue one exclusive document operation behind every earlier one. */
+	enqueue(operation) {
+		const task = this.operations.then(operation);
+		this.operations = task.then(() => void 0, () => void 0);
+		return task;
+	}
+	/** Queue a reload; only an invariant violation escaping the fan-out can reject it. */
+	queueRefresh() {
+		this.enqueue(() => this.refresh()).catch((error) => {
+			this.ctx.logger.error("credentials-local: reload commit failed at %s", this.spec.filename);
+			this.ctx.logger.error(error);
+		});
+	}
+	/** Queue one line edit; entry checks reject early, the queue re-judges them at run time. */
+	async write(ref, value) {
+		const verb = value === void 0 ? "unset" : "set";
+		if (this.isClosed()) throw new Error(`credentials-local is disposed: cannot ${verb} "${ref}"`);
+		this.assertUnshadowed(ref, verb);
+		return this.enqueue(async () => {
+			if (this.isClosed()) throw new Error(`credentials-local was disposed before the queued "${ref}" ${verb} ran`);
+			this.assertUnshadowed(ref, verb);
+			await mkdir(dirname(this.spec.filename), {
+				recursive: true,
+				mode: 448
+			});
+			await withFileLock(this.spec.filename, async () => {
+				await this.reconcileFromDisk();
+				const existing = this.values.get(ref);
+				if (value === void 0 && existing === void 0) return;
+				const nextText = renderDocument(this.text, ref, value);
+				await writeFileAtomic(this.spec.filename, nextText, {
+					mode: 384,
+					dirMode: 448
+				});
+				this.text = nextText;
+				if (value === void 0) this.values.delete(ref);
+				else this.values.set(ref, value);
+				this.notifyUpdated(ref);
+			});
+		});
+	}
+	/**
+	* Reject a write the inherited environment would shadow into apparent
+	* no-effect. Only that layer can shadow a write: everything else this
+	* provider resolves ranks below the document being written.
+	*/
+	assertUnshadowed(ref, verb) {
+		if (this.inherited(ref) !== void 0) throw new Error(`credentials-local: "${ref}" is supplied read-only by the launching environment, so ${verb} would be shadowed; unset it in the shell you start dsh from instead`);
+	}
+	/**
+	* Boot read: an absent file is an empty store; an invalid one fails the
+	* plugin's activation, because a credentials document that exists but
+	* cannot be trusted must never be treated as "no credentials stored".
+	*/
+	async loadInitial() {
+		await assertOwnerOnly(this.spec.filename);
+		let text;
+		try {
+			text = await readFile(this.spec.filename, "utf8");
+		} catch (error) {
+			if (!isENOENT(error)) throw error;
+			return;
+		}
+		this.values = parseCredentialsDocument(text, this.spec.filename);
+		this.text = text;
+	}
+	/**
+	* Re-read the document after a watcher event. Unchanged content (including
+	* this provider's own writes) is a no-op; an unreadable document keeps the
+	* last good snapshot and warns — a live hot-reload must never take the
+	* process down. An invariant violation escaping the fan-out is not a reload
+	* failure and propagates to the queue's error surface.
+	*/
+	async refresh() {
+		if (this.closed) return;
+		try {
+			await this.reconcileFromDisk();
+		} catch (error) {
+			if (error?.code === "INVARIANT") throw error;
+			this.ctx.logger.warn("credentials-local: reload failed at %s; keeping the last good document", this.spec.filename);
+			this.ctx.logger.warn(error);
+		}
+	}
+	/**
+	* Compare the on-disk text against the cache and publish any difference
+	* into the seam. Absence publishes the empty store; an unreadable or
+	* invalid document throws, so each caller picks its policy — a reload warns
+	* and keeps the last good snapshot, a write fails loud rather than
+	* overwriting a document it could not understand.
+	*/
+	async reconcileFromDisk() {
+		await assertOwnerOnly(this.spec.filename);
+		let text;
+		try {
+			text = await readFile(this.spec.filename, "utf8");
+		} catch (error) {
+			if (!isENOENT(error)) throw error;
+			text = void 0;
+		}
+		if (text === this.text || this.isClosed()) return;
+		const next = text === void 0 ? /* @__PURE__ */ new Map() : parseCredentialsDocument(text, this.spec.filename);
+		const changed = this.changedRefs(this.values, next);
+		this.text = text;
+		this.values = next;
+		for (const ref of changed) this.notifyUpdated(ref);
+	}
+	/** Entries whose stored value changed; the parser has already proven every key addressable. */
+	changedRefs(prev, next) {
+		const changed = [];
+		for (const key of new Set([...prev.keys(), ...next.keys()])) {
+			if (prev.get(key) === next.get(key)) continue;
+			changed.push(credentialRef(key));
+		}
+		return changed;
+	}
+};
+//#endregion
+export { CREDENTIALS_FILENAME, LocalCredentialProvider, LocalCredentialProvider as default, parseCredentialsDocument, resolveSpec };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@stackstackstack/dsh-credentials-local`.
+* @module @stackstackstack/dsh-credentials-local/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-credentials-local";
+/** Cordis companion plugin name. */
+const name = "credentials-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the Service Definition companion (`dsh-credentials/invariant`) owns the
+* `credentials/updated` lifecycle contract; this provider's file/environment layering is
+* asynchronous I/O pinned by its unit suite.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * File-backed credentials provider over `$DSH_HOME/.credentials.yaml`, layered
+ * against the environment by how much each layer is trusted:
+ *
+ * ```text
+ * inherited process environment      (read-only, wins)
+ * > $DSH_HOME/.credentials.yaml      (provider-managed, writable)
+ * > <invocation cwd>/.env            (read-only fallback)
+ * > $DSH_HOME/.env                   (read-only fallback)
+ * ```
+ *
+ * The inherited environment wins because `DEEPSEEK_API_KEY=… dsh`, a CI
+ * secret, or a container `-e` is this run's explicit intent; it cannot be
+ * edited from inside, so it must be *visibly* read-only rather than silently
+ * shadow writes. Everything below it loses to the managed store, so a key the
+ * Models page writes takes effect immediately even when an older key sits in
+ * the user's `.env`.
+ *
+ * The invoking project may supply a key, because the product trusts the
+ * project it is launched in. It ranks below the managed store, so a key stored
+ * through the Models page is never displaced by one a checkout happens to carry.
+ *
+ * The file is the provider-managed writable source: every write re-reads the
+ * document under a cross-process writer lock before patching only its own key
+ * — comments and the formatting of every untouched entry survive — external
+ * edits hot-publish through the seam, and each reload replaces the snapshot
+ * wholesale so a deleted entry never lingers in memory.
+ *
+ * The document holds nothing but credentials, which is why it is a strict
+ * `CredentialRef`-to-string mapping rather than a dotenv file: a store the
+ * Harness owns and never materializes into the environment cannot also serve
+ * as the user's environment layer; a store that doubled as the environment
+ * layer would shadow non-secret entries behind its precedence, making them
+ * silently unreachable.
+ * @module @stackstackstack/dsh-credentials-local
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { CredentialProvider } from '@stackstackstack/dsh-credentials';
+import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@stackstackstack/dsh-credentials';
+/** Basename of the credentials document inside the harness home. */
+export declare const CREDENTIALS_FILENAME = ".credentials.yaml";
+/** Plugin config: file location and hot-reload behavior. */
+export interface Config {
+    /** Credentials document path; defaults to `.credentials.yaml` under the harness home. */
+    path?: string;
+    /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
+    dshHome?: string;
+    /** Watch the document and hot-publish external edits; defaults to true. */
+    watch?: boolean;
+    /** Watcher write-settle window in milliseconds; defaults to 100. */
+    debounceMs?: number;
+}
+/** Fully resolved provider parameters; defaulting happens here, never inline. */
+interface ResolvedSpec {
+    filename: string;
+    watch: boolean;
+    debounceMs: number;
+}
+/**
+ * Resolve the runtime spec from plugin config: an explicit `path` wins,
+ * otherwise the document lives at `<harness home>/.credentials.yaml`.
+ * @param config - raw plugin config.
+ * @returns the resolved file location and watch behavior.
+ */
+export declare function resolveSpec(config: Config): ResolvedSpec;
+/**
+ * Parse one credentials document into its entries. The document is a strict
+ * mapping of {@link CredentialRef} to non-empty string: a non-mapping root, a
+ * key that is not a POSIX identifier, a non-string value, and an empty string
+ * are all rejected rather than skipped, because this file holds nothing but
+ * credentials and a silently ignored entry reads as "the key I stored has no
+ * effect". Duplicate keys surface as parser errors. An empty document is an
+ * empty store.
+ * @param text - the document's text.
+ * @param filename - absolute path, quoted in errors.
+ * @returns the parsed entries, keyed by reference.
+ */
+export declare function parseCredentialsDocument(text: string, filename: string): Map<string, string>;
+/** File-backed credentials provider (`$DSH_HOME/.credentials.yaml`). */
+export declare class LocalCredentialProvider extends CredentialProvider {
+    config: Config;
+    static Config: z<Config>;
+    private readonly spec;
+    /**
+     * Raw text of the last read or persisted document; `undefined` while the
+     * file is absent. Watcher events whose content equals this cache are no-ops,
+     * which is also the self-write suppression.
+     */
+    private text;
+    /** Parsed document snapshot; replaced wholesale on every reload. */
+    private values;
+    /**
+     * Single exclusive operation chain: watcher reloads and line edits run one
+     * at a time in queue order (settled tail), so an edit can never render from
+     * text a concurrent reload is busy replacing.
+     */
+    private operations;
+    /** Set at dispose: refuse new writes and let in-flight work no-op. */
+    private closed;
+    /** Opaque read of {@link closed}: control flow cannot narrow it across awaits. */
+    private isClosed;
+    constructor(ctx: Context, config: Config);
+    /** The inherited-environment value for a reference, or `undefined` when empty or unset. */
+    private inherited;
+    /**
+     * The `.env` fallback for a reference — below the managed store, never above
+     * it. The invoking project ranks over the user's home file, matching the
+     * environment layering: the more specific location wins.
+     */
+    private dotenvFallback;
+    [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void>;
+    resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>;
+    describe(ref: CredentialRef): Promise<CredentialInfo>;
+    set(ref: CredentialRef, value: string): Promise<void>;
+    unset(ref: CredentialRef): Promise<void>;
+    /** Queue one exclusive document operation behind every earlier one. */
+    private enqueue;
+    /** Queue a reload; only an invariant violation escaping the fan-out can reject it. */
+    private queueRefresh;
+    /** Queue one line edit; entry checks reject early, the queue re-judges them at run time. */
+    private write;
+    /**
+     * Reject a write the inherited environment would shadow into apparent
+     * no-effect. Only that layer can shadow a write: everything else this
+     * provider resolves ranks below the document being written.
+     */
+    private assertUnshadowed;
+    /**
+     * Boot read: an absent file is an empty store; an invalid one fails the
+     * plugin's activation, because a credentials document that exists but
+     * cannot be trusted must never be treated as "no credentials stored".
+     */
+    private loadInitial;
+    /**
+     * Re-read the document after a watcher event. Unchanged content (including
+     * this provider's own writes) is a no-op; an unreadable document keeps the
+     * last good snapshot and warns — a live hot-reload must never take the
+     * process down. An invariant violation escaping the fan-out is not a reload
+     * failure and propagates to the queue's error surface.
+     */
+    private refresh;
+    /**
+     * Compare the on-disk text against the cache and publish any difference
+     * into the seam. Absence publishes the empty store; an unreadable or
+     * invalid document throws, so each caller picks its policy — a reload warns
+     * and keeps the last good snapshot, a write fails loud rather than
+     * overwriting a document it could not understand.
+     */
+    private reconcileFromDisk;
+    /** Entries whose stored value changed; the parser has already proven every key addressable. */
+    private changedRefs;
+}
+export default LocalCredentialProvider;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-credentials-local`.
+ * @module @stackstackstack/dsh-credentials-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "credentials-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@stackstackstack/dsh-credentials-local",
+  "description": "File-backed credentials provider ($DSH_HOME/.env under the live process environment) for the DeepSeek Harness",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/credentials/credentials-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-atomic-write": "^0.1.5",
+    "@stackstackstack/dsh-credentials": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-home-paths": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@stackstackstack/dsh-launch-environment": "^0.1.5"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "yaml": "^2.9.0",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-atomic-write": "^0.1.5",
+    "@stackstackstack/dsh-launch-environment": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-home-paths": "^0.1.5",
+    "@stackstackstack/dsh-credentials": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}