@deepseek-ai/dsh-credentials-local 0.1.0-rc.8 → 0.1.1-rc.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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
+README.md: 7acd89ea24be4da3d2cecc6efe619e73e05bb823
+README.zh.md: d0443c31661eb0750b02f4f2b4c396730867904f

package/README.md

@@ -28,14 +28,36 @@ Under the product CLI, resolution reads the launcher's frozen [environment snaps
 
 ## The document
 
-A YAML mapping of credential reference to value, and nothing else:
+A versioned YAML document with one section per key space, and nothing else:
 
 ```yaml
-DEEPSEEK_API_KEY: sk-…
-OPENAI_API_KEY: sk-…
+version: 1
+
+refs:
+  DEEPSEEK_API_KEY: sk-…
+  OPENAI_API_KEY: sk-…
+
+records:
+  llm-pi-ai/openai-codex:
+    kind: grant
+    payload:                    # written verbatim; this provider does not interpret it
+      type: oauth
+      access: eyJhbGciOi…
+      refresh: rft_9f8e7d…
+      expires: 1786000000000
+  llm-pi-ai/amazon-bedrock:
+    kind: api-key               # environment values, no key: this route uses an AWS profile
+    env:
+      AWS_PROFILE: prod
+  llm-pi-ai/amazon-bedrock-dev:
+    kind: api-key               # neither: the owner confirmed the ambient credential chain
 ```
 
-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.
+The document holds credentials only, so every deviation is a rejection rather than a skipped entry — a silently ignored key would read as "the credential I stored has no effect". A non-mapping root, an unknown top-level key, a key that is not addressable in its space, a wrong-typed value, an empty string, an unknown record tag or field, a duplicate key, and malformed YAML all fail: loud at boot, and warn-and-keep-the-last-good-snapshot on a live reload.
+
+A `grant` payload must survive a JSON round trip, enforced in both directions. YAML spells values JSON has none for — `.inf`, alias cycles — and an owner may hand over a `Date` or a `bigint`; either way the store refuses rather than saving something it could not read back exactly as written.
+
+The pre-release layout was a flat mapping with no `version`. A boot that recognizes it exactly — addressable names over non-empty string scalars, no directives — upgrades the document in place under the writer lock: the original lines nest verbatim under `refs:`, so values, comments, and spellings survive byte for byte. Any other flat shape is refused by name, with the entry count and the one edit needed (`version: 1`, nest under `refs:`) — never read as an empty store, which would surface as an authentication failure on the first request instead of at load. A live reload never migrates: a flat document restored mid-run keeps the last good snapshot until the next boot.
 
 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.
 
@@ -47,7 +69,7 @@ The provider creates the directory `0700` and creates or atomically replaces the
 
 ## 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.
+External edits publish `credentials/reference-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
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-文件型[凭据](../credentials/README.md)提供方：四层来源，一套明确的优先级。
+文件型[凭据](../credentials/README.zh.md)提供方：四层来源，一套明确的优先级。
 
 | 层 | 来源 id | 可写 | 优先 |
 |---|---|---|---|
@@ -15,7 +15,7 @@
 
 它之下的所有来源优先级都低于受管存储，因此 Models 页写入的密钥会立即生效，即使某个 `.env` 里还留着更旧的密钥。没有存储任何东西时这两层仍会参与解析，`describe()` 会把来源报告为 `project-env` 或 `user-env` 且 `writable: true`——存入一个密钥就会取代它们成为生效来源。
 
-在产品 CLI（命令行界面）下，解析读取的是启动器冻结的[环境快照](../../util/launch-environment/README.md)而不是 `process.env`：只有快照才说得清某个值来自启动 shell 还是来自某个文件。并非由产品 CLI 启动的组合只有继承环境这一层，这让嵌入方保持它们原有的语义。
+在产品 CLI（命令行界面）下，解析读取的是启动器冻结的[环境快照](../../util/launch-environment/README.zh.md)而不是 `process.env`：只有快照才说得清某个值来自启动 shell 还是来自某个文件。并非由产品 CLI 启动的组合只有继承环境这一层，这让嵌入方保持它们原有的语义。
 
 ## 配置
 
@@ -28,16 +28,38 @@
 
 ## 文档本身
 
-一个从凭据引用到值的 YAML mapping，除此之外别无他物：
+一个带版本的 YAML 文档，每个键空间一个分节，除此之外别无他物：
 
 ```yaml
-DEEPSEEK_API_KEY: sk-…
-OPENAI_API_KEY: sk-…
+version: 1
+
+refs:
+  DEEPSEEK_API_KEY: sk-…
+  OPENAI_API_KEY: sk-…
+
+records:
+  llm-pi-ai/openai-codex:
+    kind: grant
+    payload:                    # written verbatim; this provider does not interpret it
+      type: oauth
+      access: eyJhbGciOi…
+      refresh: rft_9f8e7d…
+      expires: 1786000000000
+  llm-pi-ai/amazon-bedrock:
+    kind: api-key               # environment values, no key: this route uses an AWS profile
+    env:
+      AWS_PROFILE: prod
+  llm-pi-ai/amazon-bedrock-dev:
+    kind: api-key               # neither: the owner confirmed the ambient credential chain
 ```
 
-该文档只存放凭据，因此任何偏离都是拒绝，而不是跳过某个条目——被静默忽略的键读起来就是「我存进去的密钥没有生效」。非 mapping 的根、非 POSIX 标识符的键、非字符串值、空字符串、重复键以及格式错误的 YAML 全部失败：启动时明确报错，运行期热重载则告警并保留最后可用快照。没有 `version` 字段，也没有包装层；格式就是这个 mapping。
+该文档只存放凭据，因此任何偏离都是拒绝，而不是跳过某个条目——被静默忽略的键读起来就是「我存进去的凭据没有生效」。非 mapping 的根、未知的顶层键、在其空间中不可寻址的键、类型不符的值、空字符串、未知的记录标签或字段、重复键以及格式错误的 YAML 全部失败：启动时明确报错，运行期热重载则告警并保留最后可用快照。
 
-写入是对已解析文档打补丁而不是重建，因此注释与所有未触及条目的排版都会保留。直接位于某条目上方的注释属于该条目的注解，会随它一起删除。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。磁盘上已经无法解析的文档会让写入失败，而不是覆盖提供方读不懂的内容。
+`grant` 的 payload 必须能经受 JSON 往返，读写两个方向都强制。YAML 能拼写出 JSON 没有的值——`.inf`、别名环——拥有者也可能递来 `Date` 或 `bigint`；无论哪种，存储都选择拒绝，而不是存下一个自己无法逐字读回的东西。
+
+发布前的旧布局是没有 `version` 的扁平 mapping。启动时若能精确识别它——可寻址名称对非空字符串标量、且没有文档指令——就在写锁下原地升级：原有各行逐字下沉到 `refs:` 之下，值、注释与拼写逐字节保留。其余任何扁平形态都会被指名拒绝，并给出条目数与唯一需要做的编辑（`version: 1`，条目下沉到 `refs:`）——绝不当作空存储读过去，否则它会以第一次请求认证失败的形式出现，而不是在加载时。热重载从不迁移：运行中被恢复出来的扁平文档只会保住上一份完好快照，直到下次启动。
+
+写入是对已解析文档打补丁而不是重建，因此注释与所有未触及条目的排版都会保留。直接位于某条目上方的注释属于该条目的注解，会随它一起删除。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.zh.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。磁盘上已经无法解析的文档会让写入失败，而不是覆盖提供方读不懂的内容。
 
 任何字符串值都能往返，包括多行值，因此不会再有条目因为缺少可用引号样式而不可写。空的存储值等于不存在（seam 规则）——这也正是文档中的空字符串被直接拒绝的原因：`unset` 删除键，而不是把它置空。
 
@@ -47,13 +69,13 @@ OPENAI_API_KEY: sk-…
 
 ## 热重载
 
-外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。在 Chokidar 打开目标之前，提供方会对层级最深的现有祖先路径执行 realpath 解析，再拼回缺失的后缀；文件访问和诊断仍使用配置路径，从而避免 Windows 混用 8.3 别名与 libuv 的长格式事件路径。提供方自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读或无效时保留最后可用快照并告警；文件不存在即空存储；启动时不可读或无效则明确报错。
+外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/reference-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（智能体）的路径。
+文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，而已交付的 `workspace-write` 文件策略限制的是修改而非读取，因此它们读这个文件与读该用户拥有的任何其他文件毫无二致；也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境——这与用户的普通环境层 `$DSH_HOME/.env` 不同（见 [app-boot 的 Harness home 各层](../../boot/app-boot/README.zh.md#profiles)）——因此要拿到这个值，需要刻意去读一条并未交给 agent（智能体）的路径。
 
 这是审慎，不是边界。必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到；OS 钥匙串提供方——一种模型运行所在进程根本无法读取的存储——才是延后的答案，它应当作为平级包与本提供方并列。
 

package/lib/index.js

@@ -3,11 +3,11 @@ 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 { Document, isMap, isScalar, parseDocument } from "yaml";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
 import { canonicalizeWatchPath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
-import { CredentialProvider, credentialRef } from "@deepseek-ai/dsh-credentials";
+import { CredentialProvider, credentialRef, parseCredentialKey } from "@deepseek-ai/dsh-credentials";
 //#region lib/types/index.js
 /**
 * File-backed credentials provider over `$DSH_HOME/.credentials.yaml`, layered
@@ -63,6 +63,20 @@ function resolveSpec(config) {
 /** Permission bits outside the owner; a credentials document must have none of them. */
 const GROUP_OTHER_BITS = 63;
 /**
+* How long a record write waits for the cross-process writer lock. A record
+* mutation runs its caller's decision while holding the lock, and for the
+* operation this half exists to serve — an owner refreshing an expired token —
+* that decision includes a network round trip. The file-work default would
+* fail every other writer of this document for its duration. A contender's
+* wait is sized by the longest holder it can meet, and refs and records share
+* one file and one lock, so every writer of this document — reference writes
+* and record deletes included — waits this long, not only the mutation that
+* holds it. Like the retry cadence in `dsh-atomic-write`, this is a
+* robustness bound of the write protocol rather than a deployment choice: it
+* is sized by what a provider request costs, which no deployment varies.
+*/
+const DOCUMENT_LOCK_WAIT_MS = 3e4;
+/**
 * 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,
@@ -106,17 +120,18 @@ function describeYamlError(error) {
 	const where = at === void 0 ? "" : ` at line ${String(at.line)}, column ${String(at.col)}`;
 	return `${error.code}${where}`;
 }
+/** The document layout this build reads and writes. */
+const DOCUMENT_VERSION = 1;
 /**
-* 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.
+* Parse one credentials document. Everything is rejected rather than skipped —
+* an unversioned root, an unknown top-level key, a key that is not addressable,
+* a wrong-typed value, an unknown record tag or field — because this file holds
+* nothing but credentials and a silently ignored entry reads as "the credential
+* I stored has no effect". Duplicate keys surface as parser errors. An empty
+* document is an empty store and needs no version.
 * @param text - the document's text.
 * @param filename - absolute path, quoted in errors.
-* @returns the parsed entries, keyed by reference.
+* @returns the parsed references and records.
 */
 function parseCredentialsDocument(text, filename) {
 	const document = parseDocument(text, {
@@ -125,9 +140,58 @@ function parseCredentialsDocument(text, filename) {
 	});
 	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`);
+	if (typeof root !== "object" || root === null || Array.isArray(root)) throw new TypeError(`credentials-local: ${filename} must be a mapping`);
+	const fields = root;
+	const keys = Object.keys(fields);
+	if (keys.length === 0) return {
+		refs: /* @__PURE__ */ new Map(),
+		records: /* @__PURE__ */ new Map()
+	};
+	if (!("version" in fields)) throw new Error(`credentials-local: ${filename} uses the pre-release flat layout. Add \`version: 1\` and nest the existing ${keys.length} ${keys.length === 1 ? "entry" : "entries"} under \`refs:\`. No values need to change.`);
+	if (fields["version"] !== 1) throw new Error(`credentials-local: ${filename} declares version ${JSON.stringify(fields["version"])}; this build reads version 1`);
+	for (const key of keys) if (key !== "version" && key !== "refs" && key !== "records") throw new Error(`credentials-local: unknown top-level key "${key}" in ${filename}`);
+	return {
+		refs: parseRefs(fields["refs"], filename),
+		records: parseRecords(fields["records"], filename)
+	};
+}
+/**
+* Render the version-1 layout for a pre-release flat document, or `undefined`
+* for anything else. The flat layout is recognized exactly — a non-empty
+* top-level mapping of addressable reference names to non-empty string
+* scalars, with no `version` key and no document directives — and the rewrite
+* nests the original lines verbatim under `refs:` at two spaces' indent, so
+* comments, blank lines, and each value's spelling survive byte for byte.
+* Anything the recognizer declines keeps {@link parseCredentialsDocument}'s
+* loud rejection: a document this build cannot prove it understands is never
+* rewritten. Remove with the pre-release stance at the first tagged release.
+* @param text - the document's text.
+* @returns the migrated text, or `undefined` when the text is not the recognized flat layout.
+*/
+function renderFlatLayoutMigration(text) {
+	const document = parseDocument(text, {
+		prettyErrors: true,
+		uniqueKeys: true
+	});
+	if (document.errors.length > 0) return void 0;
+	const flat = document.contents;
+	if (!isMap(flat) || flat.items.length === 0) return void 0;
+	for (const line of text.split("\n")) if (/^(%|---|\.\.\.)/.test(line)) return void 0;
+	for (const pair of flat.items) {
+		if (!isScalar(pair.key) || typeof pair.key.value !== "string" || pair.key.value === "version") return void 0;
+		try {
+			credentialRef(pair.key.value);
+		} catch {
+			return;
+		}
+		if (!isScalar(pair.value) || typeof pair.value.value !== "string" || pair.value.value.length === 0) return void 0;
+	}
+	return `version: 1\nrefs:\n${text.split("\n").map((line) => line.length === 0 ? line : `  ${line}`).join("\n")}${text.endsWith("\n") ? "" : "\n"}`;
+}
+/** Admit a `refs` section: POSIX-identifier keys over non-empty string values. */
+function parseRefs(section, filename) {
 	const entries = /* @__PURE__ */ new Map();
-	for (const [key, value] of Object.entries(root)) {
+	for (const [key, value] of Object.entries(asSection(section, "refs", filename))) {
 		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`);
@@ -135,21 +199,194 @@ function parseCredentialsDocument(text, filename) {
 	}
 	return entries;
 }
+/** Admit a `records` section: `<scope>/<id>` keys over tagged record mappings. */
+function parseRecords(section, filename) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(asSection(section, "records", filename))) {
+		parseCredentialKey(key);
+		entries.set(key, parseRecord(key, value, filename));
+	}
+	return entries;
+}
+/**
+* Refuse an api-key record the read path could not admit, before it is
+* rendered: an empty key, an env name outside the reference grammar, or an
+* empty env value would persist a document `parseRecord` rejects at the next
+* boot — a durable-boundary write is validated where it is written.
+* @param key - the record's credential key, for the failure message.
+* @param record - the api-key record a mutation returned.
+*/
+function assertStorableApiKey(key, record) {
+	if (record.key !== void 0 && record.key.length === 0) throw new TypeError(`credentials-local: record "${key}" has an empty key; omit the field instead`);
+	for (const [name, value] of Object.entries(record.env ?? {})) {
+		credentialRef(name);
+		if (value.length === 0) throw new TypeError(`credentials-local: record "${key}" env "${name}" must be a non-empty string`);
+	}
+}
+/** One section of the document as a plain mapping; absent and null both mean empty. */
+function asSection(section, name, filename) {
+	if (section === void 0 || section === null) return {};
+	if (typeof section !== "object" || Array.isArray(section)) throw new TypeError(`credentials-local: "${name}" in ${filename} must be a mapping`);
+	return section;
+}
+/** Admit one record entry, rejecting an unknown tag or field rather than dropping it. */
+function parseRecord(key, value, filename) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`credentials-local: record "${key}" in ${filename} must be a mapping`);
+	const fields = value;
+	const kind = fields["kind"];
+	if (kind === "api-key") {
+		assertFields(key, fields, [
+			"kind",
+			"key",
+			"env"
+		], filename);
+		const apiKey = fields["key"];
+		if (apiKey !== void 0 && (typeof apiKey !== "string" || apiKey.length === 0)) throw new TypeError(`credentials-local: record "${key}" in ${filename} has a non-string or empty key`);
+		const env = parseRecordEnv(key, fields["env"], filename);
+		return {
+			kind: "api-key",
+			...apiKey === void 0 ? {} : { key: apiKey },
+			...env === void 0 ? {} : { env }
+		};
+	}
+	if (kind === "grant") {
+		assertFields(key, fields, ["kind", "payload"], filename);
+		if (!("payload" in fields)) throw new Error(`credentials-local: record "${key}" in ${filename} has no payload`);
+		assertJsonValue(`record "${key}" payload in ${filename}`, fields["payload"], /* @__PURE__ */ new Set());
+		return {
+			kind: "grant",
+			payload: fields["payload"]
+		};
+	}
+	if (kind === void 0) throw new Error(`credentials-local: record "${key}" in ${filename} has no kind`);
+	throw new Error(`credentials-local: record "${key}" in ${filename} has unknown kind ${JSON.stringify(kind)}`);
+}
+/** Reject a field the tag does not define, so a typo is not silently dropped. */
+function assertFields(key, fields, allowed, filename) {
+	for (const field of Object.keys(fields)) if (!allowed.includes(field)) throw new Error(`credentials-local: record "${key}" in ${filename} has unknown field "${field}"`);
+}
+/** Admit an api-key record's provider environment: POSIX names over non-empty strings. */
+function parseRecordEnv(key, env, filename) {
+	if (env === void 0) return void 0;
+	if (typeof env !== "object" || env === null || Array.isArray(env)) throw new TypeError(`credentials-local: record "${key}" in ${filename} has a non-mapping env`);
+	const parsed = {};
+	for (const [name, value] of Object.entries(env)) {
+		credentialRef(name);
+		if (typeof value !== "string" || value.length === 0) throw new TypeError(`credentials-local: record "${key}" env "${name}" in ${filename} must be a non-empty string`);
+		parsed[name] = value;
+	}
+	return parsed;
+}
 /**
-* 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.
+* Reject a payload that cannot survive a JSON round trip, on the way in and on
+* the way out. The seam promises owners their payload comes back exactly as
+* written, and both directions can break that: a document may spell `.inf` or
+* an alias cycle, and an owner may hand over a `Date`, a class instance, or a
+* `bigint` that this document has no faithful spelling for. Neither the value
+* nor any nested value is quoted in a diagnostic.
+* @param where - the subject named in a diagnostic, already free of any value.
+* @param value - the payload or nested value to admit.
+* @param seen - objects on the current path, for cycle detection.
+* @throws TypeError naming `where` when the value cannot round-trip.
+*/
+function assertJsonValue(where, value, seen) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return;
+	if (typeof value === "number") {
+		if (Number.isFinite(value)) return;
+		throw new TypeError(`credentials-local: ${where} holds a non-finite number`);
+	}
+	if (typeof value === "object") {
+		if (seen.has(value)) throw new TypeError(`credentials-local: ${where} is cyclic`);
+		if (Object.getPrototypeOf(value) === Object.prototype || Array.isArray(value)) {
+			seen.add(value);
+			for (const nested of Object.values(value)) assertJsonValue(where, nested, seen);
+			seen.delete(value);
+			return;
+		}
+	}
+	throw new TypeError(`credentials-local: ${where} holds a value JSON cannot represent`);
+}
+/**
+* The comment-preserving mutable tree one edit renders from. 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.
+* @returns the tree to edit, carrying this build's version stamp.
+*/
+function mutableDocument(text) {
+	const document = text === void 0 ? new Document({}) : parseDocument(text);
+	document.setIn(["version"], 1);
+	return document;
+}
+/**
+* Render the next document text with one reference set or deleted.
 * @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);
+function renderRef(text, ref, value) {
+	const document = mutableDocument(text);
+	if (value === void 0) deleteSectionEntry(document, "refs", ref);
+	else document.setIn(["refs", ref], value);
+	return document.toString();
+}
+/**
+* Render the next document text with one record written or deleted. The record
+* node is replaced wholesale rather than edited field by field: records are
+* machine-written, so there is no hand formatting inside one to preserve.
+* @param text - the current document text, `undefined` while the file is absent.
+* @param key - the record to write.
+* @param record - the new record, or `undefined` to delete it.
+* @returns the text to persist.
+*/
+function renderRecord(text, key, record) {
+	const document = mutableDocument(text);
+	if (record === void 0) deleteSectionEntry(document, "records", key);
+	else document.setIn(["records", key], record);
 	return document.toString();
 }
+/**
+* Remove one entry from a section, taking its annotation with it. A comment
+* block written above a section's first entry annotates that entry, but the
+* parser attaches it to the section's map rather than to the pair — leaving it
+* behind would move it onto whichever entry became first, which reads as an
+* annotation of a credential nobody wrote it for.
+* @param document - the mutable tree being edited.
+* @param section - the section holding the entry.
+* @param key - the entry to remove.
+*/
+function deleteSectionEntry(document, section, key) {
+	const map = document.get(section, true);
+	/* v8 ignore next -- both callers render a delete only for an entry they just
+	found in the parsed snapshot, so the section it lives in is always a map;
+	the guard is what narrows `get`'s `unknown`. */
+	if (isMap(map)) {
+		const first = map.items[0];
+		/* v8 ignore next -- a map that holds the entry has a first item, and the
+		parser admits only scalar keys, so only the identity test can be false. */
+		if (first !== void 0 && isScalar(first.key) && first.key.value === key) map.commentBefore = null;
+	}
+	document.deleteIn([section, key]);
+}
+/**
+* Structural equality over two admitted JSON values. Records reach this after
+* {@link assertJsonValue}, so the walk meets only JSON shapes; key order is
+* ignored because an external editor may reorder a record's fields without
+* changing what it stores.
+* @param left - one value.
+* @param right - the other value.
+* @returns whether the two carry the same JSON content.
+*/
+function sameJsonValue(left, right) {
+	if (left === right) return true;
+	if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+	if (Array.isArray(left) !== Array.isArray(right)) return false;
+	const leftKeys = Object.keys(left);
+	const rightKeys = Object.keys(right);
+	if (leftKeys.length !== rightKeys.length) return false;
+	return leftKeys.every((key) => key in right && sameJsonValue(left[key], right[key]));
+}
 /** File-backed credentials provider (`$DSH_HOME/.credentials.yaml`). */
 var LocalCredentialProvider = class extends CredentialProvider {
 	config;
@@ -166,8 +403,10 @@ var LocalCredentialProvider = class extends CredentialProvider {
 	* which is also the self-write suppression.
 	*/
 	text;
-	/** Parsed document snapshot; replaced wholesale on every reload. */
+	/** Parsed reference snapshot; replaced wholesale on every reload. */
 	values = /* @__PURE__ */ new Map();
+	/** Parsed record snapshot; replaced wholesale on every reload. */
+	records = /* @__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
@@ -278,6 +517,76 @@ var LocalCredentialProvider = class extends CredentialProvider {
 	async unset(ref) {
 		await this.write(ref, void 0);
 	}
+	readRecord(key) {
+		return Promise.resolve(this.records.get(key));
+	}
+	describeRecord(key) {
+		const stored = this.records.get(key);
+		if (stored === void 0) return Promise.resolve({
+			configured: false,
+			writable: true
+		});
+		return Promise.resolve({
+			configured: true,
+			kind: stored.kind,
+			writable: true
+		});
+	}
+	listRecords() {
+		return Promise.resolve([...this.records].map(([key, record]) => ({
+			key: parseCredentialKey(key),
+			kind: record.kind
+		})));
+	}
+	async modifyRecord(key, mutate) {
+		if (this.isClosed()) throw new Error(`credentials-local is disposed: cannot modify "${key}"`);
+		return this.enqueue(async () => {
+			if (this.isClosed()) throw new Error(`credentials-local was disposed before the queued "${key}" modify ran`);
+			await mkdir(dirname(this.spec.filename), {
+				recursive: true,
+				mode: 448
+			});
+			return withFileLock(this.spec.filename, async () => {
+				await this.reconcileFromDisk();
+				const current = this.records.get(key);
+				const next = await mutate(current);
+				if (next === void 0) return current;
+				if (next.kind === "grant") assertJsonValue(`record "${key}" payload`, next.payload, /* @__PURE__ */ new Set());
+				else assertStorableApiKey(key, next);
+				const nextText = renderRecord(this.text, key, next);
+				await writeFileAtomic(this.spec.filename, nextText, {
+					mode: 384,
+					dirMode: 448
+				});
+				this.text = nextText;
+				this.records.set(key, next);
+				this.notifyRecordUpdated(key);
+				return next;
+			}, { waitMs: DOCUMENT_LOCK_WAIT_MS });
+		});
+	}
+	async deleteRecord(key) {
+		if (this.isClosed()) throw new Error(`credentials-local is disposed: cannot delete "${key}"`);
+		await this.enqueue(async () => {
+			if (this.isClosed()) throw new Error(`credentials-local was disposed before the queued "${key}" delete ran`);
+			await mkdir(dirname(this.spec.filename), {
+				recursive: true,
+				mode: 448
+			});
+			await withFileLock(this.spec.filename, async () => {
+				await this.reconcileFromDisk();
+				if (!this.records.has(key)) return;
+				const nextText = renderRecord(this.text, key, void 0);
+				await writeFileAtomic(this.spec.filename, nextText, {
+					mode: 384,
+					dirMode: 448
+				});
+				this.text = nextText;
+				this.records.delete(key);
+				this.notifyRecordUpdated(key);
+			}, { waitMs: DOCUMENT_LOCK_WAIT_MS });
+		});
+	}
 	/** Queue one exclusive document operation behind every earlier one. */
 	enqueue(operation) {
 		const task = this.operations.then(operation);
@@ -307,7 +616,7 @@ var LocalCredentialProvider = class extends CredentialProvider {
 				await this.reconcileFromDisk();
 				const existing = this.values.get(ref);
 				if (value === void 0 && existing === void 0) return;
-				const nextText = renderDocument(this.text, ref, value);
+				const nextText = renderRef(this.text, ref, value);
 				await writeFileAtomic(this.spec.filename, nextText, {
 					mode: 384,
 					dirMode: 448
@@ -316,7 +625,7 @@ var LocalCredentialProvider = class extends CredentialProvider {
 				if (value === void 0) this.values.delete(ref);
 				else this.values.set(ref, value);
 				this.notifyUpdated(ref);
-			});
+			}, { waitMs: DOCUMENT_LOCK_WAIT_MS });
 		});
 	}
 	/**
@@ -330,7 +639,10 @@ var LocalCredentialProvider = class extends CredentialProvider {
 	/**
 	* 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".
+	* cannot be trusted must never be treated as "no credentials stored". The
+	* one exception is the recognized pre-release flat layout, which is
+	* upgraded in place first — a key stored by an earlier build must survive
+	* the layout change without a hand edit.
 	*/
 	async loadInitial() {
 		await assertOwnerOnly(this.spec.filename);
@@ -341,10 +653,41 @@ var LocalCredentialProvider = class extends CredentialProvider {
 			if (!isENOENT(error)) throw error;
 			return;
 		}
-		this.values = parseCredentialsDocument(text, this.spec.filename);
+		if (renderFlatLayoutMigration(text) !== void 0) text = await this.migrateFlatDocument();
+		const document = parseCredentialsDocument(text, this.spec.filename);
+		this.values = document.refs;
+		this.records = document.records;
 		this.text = text;
 	}
 	/**
+	* One-shot upgrade of the recognized pre-release flat layout, before the
+	* watcher exists. The rewrite runs under the document's writer lock and
+	* re-reads first — a concurrent boot may have migrated already — and
+	* whatever the re-read finds that is not the flat layout is returned
+	* untouched for the ordinary parse. Values are carried verbatim; only the
+	* enclosing layout changes. Remove with the pre-release stance at the
+	* first tagged release.
+	* @returns the document text this boot should parse.
+	*/
+	async migrateFlatDocument() {
+		return withFileLock(this.spec.filename, async () => {
+			const current = await readFile(this.spec.filename, "utf8");
+			const migrated = renderFlatLayoutMigration(current);
+			/* v8 ignore next 2 -- the losing side of the cross-process migration race:
+			another boot rewrote the document between the unlocked recognize and
+			this lock. That interleaving cannot be scheduled deterministically
+			through a whole boot (migration.spec drives it best-effort); the
+			decision itself is the recognizer's covered versioned-document decline. */
+			if (migrated === void 0) return current;
+			await writeFileAtomic(this.spec.filename, migrated, {
+				mode: 384,
+				dirMode: 448
+			});
+			this.ctx.logger.info("credentials-local: migrated %s to the version %d layout; values are unchanged", this.spec.filename, 1);
+			return migrated;
+		}, { waitMs: DOCUMENT_LOCK_WAIT_MS });
+	}
+	/**
 	* 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
@@ -378,11 +721,17 @@ var LocalCredentialProvider = class extends CredentialProvider {
 			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);
+		const next = text === void 0 ? {
+			refs: /* @__PURE__ */ new Map(),
+			records: /* @__PURE__ */ new Map()
+		} : parseCredentialsDocument(text, this.spec.filename);
+		const changedRefs = this.changedRefs(this.values, next.refs);
+		const changedRecords = this.changedRecords(this.records, next.records);
 		this.text = text;
-		this.values = next;
-		for (const ref of changed) this.notifyUpdated(ref);
+		this.values = next.refs;
+		this.records = next.records;
+		for (const ref of changedRefs) this.notifyUpdated(ref);
+		for (const key of changedRecords) this.notifyRecordUpdated(key);
 	}
 	/** Entries whose stored value changed; the parser has already proven every key addressable. */
 	changedRefs(prev, next) {
@@ -393,6 +742,15 @@ var LocalCredentialProvider = class extends CredentialProvider {
 		}
 		return changed;
 	}
+	/** Records whose stored value changed; the parser has already proven every key addressable. */
+	changedRecords(prev, next) {
+		const changed = [];
+		for (const key of new Set([...prev.keys(), ...next.keys()])) {
+			if (sameJsonValue(prev.get(key), next.get(key))) continue;
+			changed.push(parseCredentialKey(key));
+		}
+		return changed;
+	}
 };
 //#endregion
-export { CREDENTIALS_FILENAME, LocalCredentialProvider, LocalCredentialProvider as default, parseCredentialsDocument, resolveSpec };
+export { CREDENTIALS_FILENAME, DOCUMENT_VERSION, LocalCredentialProvider, LocalCredentialProvider as default, parseCredentialsDocument, renderFlatLayoutMigration, resolveSpec };

package/lib/invariant.js

@@ -10,7 +10,7 @@ const name = "credentials-local-invariant";
 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
+* `credentials/reference-updated` lifecycle contract; this provider's file/environment layering is
 * asynchronous I/O pinned by its unit suite.
 */
 const install = () => {};

package/lib/types/index.d.ts

@@ -37,7 +37,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { CredentialProvider } from '@deepseek-ai/dsh-credentials';
-import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials';
+import type { CredentialInfo, CredentialKey, CredentialRecord, CredentialRecordEntry, CredentialRecordInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/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. */
@@ -64,19 +64,41 @@ interface ResolvedSpec {
  * @returns the resolved file location and watch behavior.
  */
 export declare function resolveSpec(config: Config): ResolvedSpec;
+/** The document layout this build reads and writes. */
+export declare const DOCUMENT_VERSION = 1;
+/** One parsed credentials document: the two key spaces it stores, keyed as written. */
+export interface CredentialsDocument {
+    /** Reference entries, keyed by {@link CredentialRef}. */
+    refs: Map<string, string>;
+    /** Stored records, keyed by {@link CredentialKey}. */
+    records: Map<string, CredentialRecord>;
+}
 /**
- * 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.
+ * Parse one credentials document. Everything is rejected rather than skipped —
+ * an unversioned root, an unknown top-level key, a key that is not addressable,
+ * a wrong-typed value, an unknown record tag or field — because this file holds
+ * nothing but credentials and a silently ignored entry reads as "the credential
+ * I stored has no effect". Duplicate keys surface as parser errors. An empty
+ * document is an empty store and needs no version.
  * @param text - the document's text.
  * @param filename - absolute path, quoted in errors.
- * @returns the parsed entries, keyed by reference.
+ * @returns the parsed references and records.
+ */
+export declare function parseCredentialsDocument(text: string, filename: string): CredentialsDocument;
+/**
+ * Render the version-1 layout for a pre-release flat document, or `undefined`
+ * for anything else. The flat layout is recognized exactly — a non-empty
+ * top-level mapping of addressable reference names to non-empty string
+ * scalars, with no `version` key and no document directives — and the rewrite
+ * nests the original lines verbatim under `refs:` at two spaces' indent, so
+ * comments, blank lines, and each value's spelling survive byte for byte.
+ * Anything the recognizer declines keeps {@link parseCredentialsDocument}'s
+ * loud rejection: a document this build cannot prove it understands is never
+ * rewritten. Remove with the pre-release stance at the first tagged release.
+ * @param text - the document's text.
+ * @returns the migrated text, or `undefined` when the text is not the recognized flat layout.
  */
-export declare function parseCredentialsDocument(text: string, filename: string): Map<string, string>;
+export declare function renderFlatLayoutMigration(text: string): string | undefined;
 /** File-backed credentials provider (`$DSH_HOME/.credentials.yaml`). */
 export declare class LocalCredentialProvider extends CredentialProvider {
     config: Config;
@@ -88,8 +110,10 @@ export declare class LocalCredentialProvider extends CredentialProvider {
      * which is also the self-write suppression.
      */
     private text;
-    /** Parsed document snapshot; replaced wholesale on every reload. */
+    /** Parsed reference snapshot; replaced wholesale on every reload. */
     private values;
+    /** Parsed record snapshot; replaced wholesale on every reload. */
+    private records;
     /**
      * 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
@@ -114,6 +138,11 @@ export declare class LocalCredentialProvider extends CredentialProvider {
     describe(ref: CredentialRef): Promise<CredentialInfo>;
     set(ref: CredentialRef, value: string): Promise<void>;
     unset(ref: CredentialRef): Promise<void>;
+    readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>;
+    describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>;
+    listRecords(): Promise<readonly CredentialRecordEntry[]>;
+    modifyRecord(key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>): Promise<CredentialRecord | undefined>;
+    deleteRecord(key: CredentialKey): 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. */
@@ -129,9 +158,23 @@ export declare class LocalCredentialProvider extends CredentialProvider {
     /**
      * 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".
+     * cannot be trusted must never be treated as "no credentials stored". The
+     * one exception is the recognized pre-release flat layout, which is
+     * upgraded in place first — a key stored by an earlier build must survive
+     * the layout change without a hand edit.
      */
     private loadInitial;
+    /**
+     * One-shot upgrade of the recognized pre-release flat layout, before the
+     * watcher exists. The rewrite runs under the document's writer lock and
+     * re-reads first — a concurrent boot may have migrated already — and
+     * whatever the re-read finds that is not the flat layout is returned
+     * untouched for the ordinary parse. Values are carried verbatim; only the
+     * enclosing layout changes. Remove with the pre-release stance at the
+     * first tagged release.
+     * @returns the document text this boot should parse.
+     */
+    private migrateFlatDocument;
     /**
      * 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
@@ -150,6 +193,8 @@ export declare class LocalCredentialProvider extends CredentialProvider {
     private reconcileFromDisk;
     /** Entries whose stored value changed; the parser has already proven every key addressable. */
     private changedRefs;
+    /** Records whose stored value changed; the parser has already proven every key addressable. */
+    private changedRecords;
 }
 export default LocalCredentialProvider;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-credentials-local",
   "description": "File-backed credentials provider ($DSH_HOME/.env under the live process environment) for the DeepSeek Harness",
-  "version": "0.1.0-rc.8",
+  "version": "0.1.1-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,12 +32,12 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-atomic-write": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-atomic-write": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2"
   },
   "dependencies": {
     "chokidar": "^4.0.3",
@@ -45,11 +45,11 @@
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-atomic-write": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-credentials": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-atomic-write": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-home-paths": "^0.1.1-rc.2"
   }
 }