@sema-agent/settings-schema 6.0.0 → 6.2.0

package/conformance/cases/c40-s712-identity-only-what-reads-out/input.json

@@ -0,0 +1,64 @@
+{
+  "meta": {
+    "version": 11,
+    "updatedAt": "2026-09-25T00:00:00.000Z"
+  },
+  "domains": {
+    "models": {
+      "models": [
+        {
+          "name": "keep",
+          "provider": "openai",
+          "id": "keep-id",
+          "apiKeyEnv": "OPENAI_API_KEY"
+        },
+        {
+          "name": "Authorization: Bearer FAKE-S712-CORPUS-00000000",
+          "provider": "openai",
+          "id": "withheld-id",
+          "enabled": "yes",
+          "apiKeyEnv": "not an env name"
+        },
+        {
+          "name": "off-model",
+          "provider": "openai",
+          "id": "off-id",
+          "enabled": false,
+          "apiKeyEnv": "not an env name"
+        },
+        {
+          "name": "tok=Bearer abc1234",
+          "provider": "openai",
+          "id": "short-bearer-id",
+          "apiKeyEnv": "not an env name"
+        },
+        {
+          "name": "-----BEGIN RSA PRIVATE KEY-----\nMIIEFAKES712CORPUSPEMBODY0000\n-----END RSA PRIVATE KEY-----",
+          "provider": "openai",
+          "id": "pem-id",
+          "apiKeyEnv": "not an env name"
+        },
+        {
+          "name": "prefixed-pem",
+          "provider": "openai",
+          "id": "key: -----BEGIN OPENSSH PRIVATE KEY-----\nMIIEFAKES712CODEXPREFIXED0000\n-----END OPENSSH PRIVATE KEY-----",
+          "apiKeyEnv": "not an env name"
+        },
+        {
+          "name": "glued-pem",
+          "provider": "openai",
+          "id": "sk-note:-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwFAKES712GLUEDCORPUS0000000000\n-----END PRIVATE KEY-----",
+          "apiKeyEnv": "not an env name"
+        }
+      ],
+      "roles": {
+        "summarize": {
+          "model": "keep"
+        },
+        "sk-note:-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwFAKES712GLUEDCORPUS0000000000\n-----END PRIVATE KEY-----": {
+          "model": "keep"
+        }
+      }
+    }
+  }
+}

package/conformance/cases/c40-s712-identity-only-what-reads-out/meta.json

@@ -0,0 +1,13 @@
+{
+  "contributor": "contract",
+  "claim": "S-712 身份律的两道闸压在语料上:被丢条目的 name 是一段脱敏器会改动的串(Bearer 形)⇒ identity 不带 name(同一条告警里坐标会打码,身份不许把原文带出去);enabled 是字符串 \"yes\" ⇒ 不带 enabled;id 是干净字符串 ⇒ 照带。另两条被丢条目压脱敏判据的两道边:`tok=Bearer abc1234`(短令牌,探测器 containsSecretToken 不判阳、脱敏器会改)与一整段 PEM 私钥(头里带空格,脱敏器的定点两遍够不着、靠整串兜底)⇒ 两条的 name 都不带。正控:另一条被丢条目 name / id / enabled:false 三键齐全逐字带出。读腿若放宽任一闸,告警面多出字段即红;秘密清单同时由告警面零命中门看着。",
+  "firstRedOn": [],
+  "secrets": [
+    "FAKE-S712-CORPUS-00000000",
+    "abc1234",
+    "MIIEFAKES712CORPUSPEMBODY0000",
+    "MIIEFAKES712CODEXPREFIXED0000",
+    "MC4CAQAwBQYDK2VwFAKES712GLUEDCORPUS0000000000"
+  ],
+  "note": "对抗轮 #5(车OD 2026-09-25):变异门 `test/conformance-mutation.test.ts` 为 readEntryIdentity 登记两靶(`redactSecrets(v) === v` → `true`、`typeof enabled === \"boolean\"` → `enabled !== void 0`),加本条之前两靶变异体全绿(语料缺口),加本条之后两靶各红。第三条律(只认数据属性、不触发访问器)JSON 表达不出 getter,不在本条射程内,由单测看着。firstRedOn 为空:旧版铸不出 identity,historical 归一器两侧剥掉 identity,本条在旧版上不计行为红 —— 它是护栏,不是真门。 验修轮 N4 / N1(车OD 2026-09-25):加入短令牌与 PEM 两条 —— 身份判据退回旧的 containsSecretToken 时短令牌那条带出 name ⇒ 本条红;redactSecrets 去掉整串兜底时 PEM 那条带出 name ⇒ 本条红。 codex 一审 [high](2026-09-25):再加一条 `id` = 带 `key: ` 前缀的 PEM 私钥(header 不在串首,探测器看不见)⇒ 身份只剩 name;redactSecrets 去掉「串内任意位置 PEM header」一道时本条红。 codex 验修轮 [high](2026-09-25):再加 `sk-note:` 紧贴私钥 PEM header 的串,既作被丢条目的 `id`(身份面)又作 `roles` 的坏键(坐标面 + zod error 面);redactSecrets 把 PEM 检查挪回替换之后时本条红(令牌那一遍先把 `sk-note:-----BEGIN` 换掉)。"
+}

package/conformance/cases/cli01-model-name-nfc-vs-nfd/expected.json

@@ -72,6 +72,10 @@
     "warnings": [
       {
         "domain": "models",
+        "identity": {
+          "id": "café-id",
+          "name": "café"
+        },
         "kind": "entry-dropped",
         "path": [
           "models",
@@ -80,6 +84,10 @@
       },
       {
         "domain": "models",
+        "identity": {
+          "id": "café-id",
+          "name": "café"
+        },
         "kind": "entry-dropped",
         "path": [
           "models",

package/conformance/cases/cli02-control-and-zero-width-chars/expected.json

@@ -85,6 +85,10 @@
     "warnings": [
       {
         "domain": "models",
+        "identity": {
+          "id": "a\u0007b-id",
+          "name": "a\u0007b"
+        },
         "kind": "entry-dropped",
         "path": [
           "models",
@@ -93,6 +97,10 @@
       },
       {
         "domain": "models",
+        "identity": {
+          "id": "zero​width-id",
+          "name": "zero​width"
+        },
         "kind": "entry-dropped",
         "path": [
           "models",

package/conformance/cases/t04-secret-literal-never-in-warning-value/expected.json

@@ -72,6 +72,10 @@
     "warnings": [
       {
         "domain": "models",
+        "identity": {
+          "id": "bad-id",
+          "name": "bad"
+        },
         "kind": "entry-dropped",
         "path": [
           "models",

package/dist/api/auth-bridge.d.ts

@@ -266,13 +266,13 @@ export declare const VerifiedIdentity: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     principal: string;
     role?: string | undefined;
-    scope?: string | undefined;
     grantId?: string | undefined;
+    scope?: string | undefined;
 }, {
     principal: string;
     role?: string | undefined;
-    scope?: string | undefined;
     grantId?: string | undefined;
+    scope?: string | undefined;
 }>;
 export type VerifiedIdentity = z.infer<typeof VerifiedIdentity>;
 /** The verifier's total result — exactly one of ok/error. */

package/dist/center-credential.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 中心(config-center 产品)凭证的**文件形契约** —— S-698(design/325 §1)。
+ *
+ * 引擎向中心出站时用的凭证由部署声明(见 server `src/center-credential.ts`,单属主);声明成文件时
+ * (`SEMA_REGISTRY_TOKEN_FILE`),文件内容有两种**种类**,不是一种语义的两种拼法:
+ *
+ *  · **裸行**(一个静态令牌,种类与今天相同):首行 = 静态 bearer,只收可打印 ASCII({@link TokenString} 的律)。它是用户 JWT 还是 worker
+ *    拉取令牌,由读方用 `looksLikeJwt`(`./api/auth-bridge`)自判 —— 本文件不重判种类。
+ *  · **信封**(新):一个 JSON 对象,形 = {@link CenterCredentialEnvelope}。今只有一员 `kind:"user-session"`
+ *    (人的登录会话:可轮换的访问令牌 + 单次有效的刷新令牌 + 到期时刻 + 签发它的中心根 URL)。worker 拉取
+ *    令牌**不进信封**:它不轮换、不属于人,保持裸行。
+ *
+ * 判别律(一条,{@link parseCenterCredentialFile} 是它的**唯一**实现):内容 `trim()` 后以 `{` 开头 ⇒ 只按
+ * 信封读,读不成 = `unreadable`(**不回落**成裸行 —— 一个 `{` 开头的裸 token 不存在,回落只会把一段坏 JSON
+ * 当 bearer 发出去);否则裸行;空 = `unreadable`。同一份内容只有一种读法(零双读)。
+ *
+ * 声明面(S-742,本文件尾段):两个声明键名 {@link CENTER_CREDENTIAL_ENV} 与二选一判官
+ * {@link judgeCenterCredentialDeclaration} —— 规则此前只活在 server,管理面 / 壳各自手抄键名。
+ *
+ * 纯契约:零 IO(读文件、写文件、续签都是消费方的事),browser-safe,与本包其余部分同一条纯度律。
+ */
+import { z } from "zod";
+/** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
+export declare const CENTER_CREDENTIAL_ENVELOPE_KIND: "user-session";
+/**
+ * 中心凭证**信封**(`SEMA_REGISTRY_TOKEN_FILE` 指向的文件是一个 JSON 对象时的唯一形)。`.strict()`:
+ * 多一个键就不是这份契约(拼错的 `refresh_token` 被静默剥掉,续签就会拿着缺席的刷新令牌去撞中心)。
+ *
+ *  · `accessToken` —— 出站 bearer(中心签的用户 JWT,形判 `looksLikeJwt`);读方拿它做身份分箱的方式与裸行
+ *    `user-jwt` 逐字同。令牌形与裸行同一条律({@link TokenString})。
+ *  · `refreshToken` —— 单次有效、严格轮换(`POST /api/v1/auth/token/refresh`,见 `./api/auth`);续签前**重读
+ *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
+ *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
+ *  · `issuer` —— 签发它的中心的**基础 URL**(与读方 `configCenter.url` 同形,可带路径前缀):续签只向同源的中心发,
+ *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ */
+export declare const CenterCredentialEnvelope: z.ZodObject<{
+    kind: z.ZodLiteral<"user-session">;
+    accessToken: z.ZodEffects<z.ZodString, string, string>;
+    refreshToken: z.ZodString;
+    expiresAt: z.ZodString;
+    issuer: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    kind: "user-session";
+    issuer: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+}, {
+    kind: "user-session";
+    issuer: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+}>;
+export type CenterCredentialEnvelope = z.infer<typeof CenterCredentialEnvelope>;
+/** {@link parseCenterCredentialFile} 的三态结果(判别键 `kind`)。`unreadable.reason` 只说**哪里**不对
+ *  (信封字段名 / zod 问题码 / 未知键**个数**),从不回显文件内容 —— 文件里装的就是凭据。 */
+export type CenterCredentialFile = {
+    kind: "bare";
+    bearer: string;
+} | {
+    kind: "envelope";
+    envelope: CenterCredentialEnvelope;
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+/**
+ * 凭证文件内容 → 三态({@link CenterCredentialFile})。判别律见模块头注,本函数是它的唯一实现:
+ *
+ *  1. `trim()`(含 BOM);空 ⇒ `unreadable("empty")`。
+ *  2. 以 `{` 开头 ⇒ 只按 {@link CenterCredentialEnvelope} 读:JSON 不成立或 schema 不过 ⇒ `unreadable`
+ *     (**不回落**裸行)。
+ *  3. 否则 ⇒ 首行(第一个 CR 或 LF 之前,再剥一次空白)。它是令牌({@link TokenString} 的律)⇒ `bare`;
+ *     不是 ⇒ `unreadable`(放不进 Authorization 头的行不是 bearer)。多行文件只认首行。
+ *
+ * 纯函数、零 IO;读方负责读文件(以及文件不可读时自己的那条 `unreadable` 臂)。
+ */
+export declare function parseCenterCredentialFile(text: string): CenterCredentialFile;
+/**
+ * 中心凭证的两个**声明键名**(部署 env)。一处定义、三方 import(server 读、管理面给 worker 渲染、壳给本机
+ * 引擎写)—— 键名是 wire 面,手抄的键名会静默漂。
+ *
+ *  · `token`(`SEMA_REGISTRY_TOKEN`)—— 值即凭证(部署注入;读方在进程生命期内读一次)。
+ *  · `tokenFile`(`SEMA_REGISTRY_TOKEN_FILE`)—— 凭证文件的路径,读方**每次取值都读文件**(轮换 / 换账号只需
+ *    改写文件,不重启);文件内容的读法见 {@link parseCenterCredentialFile}。
+ */
+export declare const CENTER_CREDENTIAL_ENV: {
+    readonly token: "SEMA_REGISTRY_TOKEN";
+    readonly tokenFile: "SEMA_REGISTRY_TOKEN_FILE";
+};
+/** {@link judgeCenterCredentialDeclaration} 的结果:凭证在哪里声明。`env` 形带**值** —— 它就是凭据,只在读方
+ *  自己的凭证模块里流转,不进日志。 */
+export type CenterCredentialDeclaration = {
+    from: "env";
+    token: string;
+} | {
+    from: "file";
+    path: string;
+} | {
+    from: "absent";
+};
+/**
+ * 读两个声明键,判凭证在哪里声明 —— 二选一规则的**唯一**实现:
+ *
+ *  · 空串 = 未设(`undefined` 同);其余一律算「设了」(不 trim —— 与规则上提前 server 的读法逐字同)。
+ *  · 两个都设 ⇒ **throw**(读方拒启):两个写者写同一个语义面,哪个赢都是猜。拒句点名两个键、不回显值。
+ *  · 只设 `tokenFile` ⇒ `{from:"file", path}`,`path` **原样**:相对路径按 cwd 解析是读方的事(纯契约不碰
+ *    `node:path`,也不知道读方的 cwd)。
+ *  · 只设 `token` ⇒ `{from:"env", token}`;都不设 ⇒ `{from:"absent"}`。
+ *
+ * 只读这两个键,别的 env 一概不看。
+ */
+export declare function judgeCenterCredentialDeclaration(env: Readonly<Record<string, string | undefined>>): CenterCredentialDeclaration;

package/dist/center-credential.js

@@ -0,0 +1,149 @@
+/**
+ * 中心(config-center 产品)凭证的**文件形契约** —— S-698(design/325 §1)。
+ *
+ * 引擎向中心出站时用的凭证由部署声明(见 server `src/center-credential.ts`,单属主);声明成文件时
+ * (`SEMA_REGISTRY_TOKEN_FILE`),文件内容有两种**种类**,不是一种语义的两种拼法:
+ *
+ *  · **裸行**(一个静态令牌,种类与今天相同):首行 = 静态 bearer,只收可打印 ASCII({@link TokenString} 的律)。它是用户 JWT 还是 worker
+ *    拉取令牌,由读方用 `looksLikeJwt`(`./api/auth-bridge`)自判 —— 本文件不重判种类。
+ *  · **信封**(新):一个 JSON 对象,形 = {@link CenterCredentialEnvelope}。今只有一员 `kind:"user-session"`
+ *    (人的登录会话:可轮换的访问令牌 + 单次有效的刷新令牌 + 到期时刻 + 签发它的中心根 URL)。worker 拉取
+ *    令牌**不进信封**:它不轮换、不属于人,保持裸行。
+ *
+ * 判别律(一条,{@link parseCenterCredentialFile} 是它的**唯一**实现):内容 `trim()` 后以 `{` 开头 ⇒ 只按
+ * 信封读,读不成 = `unreadable`(**不回落**成裸行 —— 一个 `{` 开头的裸 token 不存在,回落只会把一段坏 JSON
+ * 当 bearer 发出去);否则裸行;空 = `unreadable`。同一份内容只有一种读法(零双读)。
+ *
+ * 声明面(S-742,本文件尾段):两个声明键名 {@link CENTER_CREDENTIAL_ENV} 与二选一判官
+ * {@link judgeCenterCredentialDeclaration} —— 规则此前只活在 server,管理面 / 壳各自手抄键名。
+ *
+ * 纯契约:零 IO(读文件、写文件、续签都是消费方的事),browser-safe,与本包其余部分同一条纯度律。
+ */
+import { z } from "zod";
+import { looksLikeJwt } from "./api/auth-bridge.js";
+import { NON_SECRET_URL } from "./types.js";
+/** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
+export const CENTER_CREDENTIAL_ENVELOPE_KIND = "user-session";
+/** RFC 3339 `date-time` 的**剖面**:zod 的 `datetime({offset:true})` 管日历有效性(月日范围、闰年、时分秒范围),
+ *  这里再补它放过的三处 —— 秒必备、数字偏移必须是 `±hh:mm`、偏移的时 00–23 / 分 00–59(zod 也收 `10:00Z`、
+ *  `+0800` 与 `+99:99`,都不是 RFC 3339,后者 `Date.parse` 读成 NaN)。大写 `T` / `Z`、不收闰秒 `:60`:读方普遍用
+ *  `Date.parse` 取时刻,这是那组形里它处处读得准的子集。 */
+const RFC3339_DATE_TIME = z
+    .string()
+    .datetime({ offset: true })
+    .regex(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/, "must be an RFC 3339 date-time: seconds and a Z / ±hh:mm offset (hh 00-23, mm 00-59) are required");
+/** 一枚**令牌串**的形 —— 裸行 bearer、信封里的 `accessToken` / `refreshToken` 共用这**一条**律:可打印 ASCII
+ *  (0x20–0x7E),首尾是可见字符(0x21–0x7E)、中间可有空格(共享令牌可以是一句口令 —— 验修轮 N2:今天走得通的
+ *  这种令牌不许被本律拒掉)。控制字符、制表、非 ASCII、不可见字符一律不是令牌:判别器把它判 `unreadable`,而不是
+ *  发出去 —— 更不会把一段前面粘了不可见字符的信封 JSON 当 bearer 送出门(对抗轮 #7)。刻意比 RFC 6750 `b64token`
+ *  宽:部署手写的静态令牌可以带 `!` / `%` / 空格之类。**如实登记**:Latin-1 令牌(HTTP 头的 ByteString 收、中心也
+ *  逐字比得上)在这里判 `unreadable` —— 非 ASCII 与不可见字符(`\u0085` / `\u00AD`)分不开,取 fail-closed。 */
+const TOKEN_CHARS = /^[\x21-\x7E](?:[\x20-\x7E]*[\x21-\x7E])?$/;
+const TokenString = z.string().regex(TOKEN_CHARS, "must be a token: printable ASCII, no leading / trailing space, no control or non-ASCII characters");
+/**
+ * 中心凭证**信封**(`SEMA_REGISTRY_TOKEN_FILE` 指向的文件是一个 JSON 对象时的唯一形)。`.strict()`:
+ * 多一个键就不是这份契约(拼错的 `refresh_token` 被静默剥掉,续签就会拿着缺席的刷新令牌去撞中心)。
+ *
+ *  · `accessToken` —— 出站 bearer(中心签的用户 JWT,形判 `looksLikeJwt`);读方拿它做身份分箱的方式与裸行
+ *    `user-jwt` 逐字同。令牌形与裸行同一条律({@link TokenString})。
+ *  · `refreshToken` —— 单次有效、严格轮换(`POST /api/v1/auth/token/refresh`,见 `./api/auth`);续签前**重读
+ *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
+ *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
+ *  · `issuer` —— 签发它的中心的**基础 URL**(与读方 `configCenter.url` 同形,可带路径前缀):续签只向同源的中心发,
+ *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ */
+export const CenterCredentialEnvelope = z
+    .object({
+    kind: z.literal(CENTER_CREDENTIAL_ENVELOPE_KIND),
+    accessToken: TokenString.refine(looksLikeJwt, "must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope"),
+    refreshToken: TokenString,
+    expiresAt: RFC3339_DATE_TIME,
+    issuer: NON_SECRET_URL,
+})
+    .strict();
+/** 信封自己的字段名(schema 的键 —— reason 里只许出现这几个名字,不许出现用户写的键)。 */
+const ENVELOPE_FIELDS = new Set(Object.keys(CenterCredentialEnvelope.shape));
+/** 一次 schema 失败 → 不含文件内容的一句话。 */
+function envelopeRejection(error) {
+    const fields = new Set(); // 一个字段挂两道判据(datetime + 剖面正则)时只说一次
+    let unknownKeys = 0;
+    for (const issue of error.issues) {
+        if (issue.code === z.ZodIssueCode.unrecognized_keys) {
+            unknownKeys += issue.keys.length;
+            continue;
+        }
+        const head = issue.path[0];
+        const field = typeof head === "string" && ENVELOPE_FIELDS.has(head) ? head : "(envelope)";
+        fields.add(`${field} (${issue.code})`);
+    }
+    const parts = [...(fields.size > 0 ? [`fields rejected: ${[...fields].join(", ")}`] : []), ...(unknownKeys > 0 ? [`unknown keys: ${unknownKeys}`] : [])];
+    return `envelope does not match CenterCredentialEnvelope — ${parts.join("; ")}`;
+}
+/**
+ * 凭证文件内容 → 三态({@link CenterCredentialFile})。判别律见模块头注,本函数是它的唯一实现:
+ *
+ *  1. `trim()`(含 BOM);空 ⇒ `unreadable("empty")`。
+ *  2. 以 `{` 开头 ⇒ 只按 {@link CenterCredentialEnvelope} 读:JSON 不成立或 schema 不过 ⇒ `unreadable`
+ *     (**不回落**裸行)。
+ *  3. 否则 ⇒ 首行(第一个 CR 或 LF 之前,再剥一次空白)。它是令牌({@link TokenString} 的律)⇒ `bare`;
+ *     不是 ⇒ `unreadable`(放不进 Authorization 头的行不是 bearer)。多行文件只认首行。
+ *
+ * 纯函数、零 IO;读方负责读文件(以及文件不可读时自己的那条 `unreadable` 臂)。
+ */
+export function parseCenterCredentialFile(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return { kind: "unreadable", reason: "empty" };
+    if (trimmed.startsWith("{")) {
+        let json;
+        try {
+            json = JSON.parse(trimmed);
+        }
+        catch {
+            // JSON.parse 的报错会引用出错位置附近的原文 —— 不转述它。
+            return { kind: "unreadable", reason: "envelope is not valid JSON" };
+        }
+        const parsed = CenterCredentialEnvelope.safeParse(json);
+        return parsed.success ? { kind: "envelope", envelope: parsed.data } : { kind: "unreadable", reason: envelopeRejection(parsed.error) };
+    }
+    const firstLine = trimmed.split(/[\r\n]/, 1)[0].trim(); // 行尾 = 第一个 CR 或 LF(CRLF / LF / 孤 CR 同判)
+    if (!TOKEN_CHARS.test(firstLine))
+        return { kind: "unreadable", reason: "bare line is not a token — printable ASCII only (no control or non-ASCII characters)" };
+    return { kind: "bare", bearer: firstLine };
+}
+// ── S-742:凭证的两个声明键 + 二选一判官 ─────────────────────────────────────────────────────────────
+/**
+ * 中心凭证的两个**声明键名**(部署 env)。一处定义、三方 import(server 读、管理面给 worker 渲染、壳给本机
+ * 引擎写)—— 键名是 wire 面,手抄的键名会静默漂。
+ *
+ *  · `token`(`SEMA_REGISTRY_TOKEN`)—— 值即凭证(部署注入;读方在进程生命期内读一次)。
+ *  · `tokenFile`(`SEMA_REGISTRY_TOKEN_FILE`)—— 凭证文件的路径,读方**每次取值都读文件**(轮换 / 换账号只需
+ *    改写文件,不重启);文件内容的读法见 {@link parseCenterCredentialFile}。
+ */
+export const CENTER_CREDENTIAL_ENV = { token: "SEMA_REGISTRY_TOKEN", tokenFile: "SEMA_REGISTRY_TOKEN_FILE" };
+/**
+ * 读两个声明键,判凭证在哪里声明 —— 二选一规则的**唯一**实现:
+ *
+ *  · 空串 = 未设(`undefined` 同);其余一律算「设了」(不 trim —— 与规则上提前 server 的读法逐字同)。
+ *  · 两个都设 ⇒ **throw**(读方拒启):两个写者写同一个语义面,哪个赢都是猜。拒句点名两个键、不回显值。
+ *  · 只设 `tokenFile` ⇒ `{from:"file", path}`,`path` **原样**:相对路径按 cwd 解析是读方的事(纯契约不碰
+ *    `node:path`,也不知道读方的 cwd)。
+ *  · 只设 `token` ⇒ `{from:"env", token}`;都不设 ⇒ `{from:"absent"}`。
+ *
+ * 只读这两个键,别的 env 一概不看。
+ */
+export function judgeCenterCredentialDeclaration(env) {
+    const { token: tokenKey, tokenFile: fileKey } = CENTER_CREDENTIAL_ENV;
+    const token = env[tokenKey] ?? "";
+    const file = env[fileKey] ?? "";
+    if (token !== "" && file !== "") {
+        throw new Error(`${tokenKey} and ${fileKey} are both set — pick exactly one: ${tokenKey} carries the credential value, ` +
+            `${fileKey} names a file re-read on every request (rotation without restart). Two writers on one credential is a guess, not a config.`);
+    }
+    if (file !== "")
+        return { from: "file", path: file };
+    if (token !== "")
+        return { from: "env", token };
+    return { from: "absent" };
+}

package/dist/config-fns.d.ts

@@ -19,7 +19,17 @@ import { type DomainConfig, type DomainName, type EffectiveConfig, type Effectiv
  *  `received 'sk-live-…'`), so a secret pasted into the WRONG field would leak via the error string. Redacts
  *  space-spanning auth credentials (`Bearer <token>`) FIRST (the token pass can't see across the space), then
  *  any secret-shaped run (`%` kept in the run so a percent-encoded secret stays whole for the percent-aware
- *  containsSecretToken). invariant ①: a secret VALUE never rides an error. R13/R14. */
+ *  containsSecretToken). invariant ①: a secret VALUE never rides an error. R13/R14.
+ *
+ *  **Output invariant** (S-712 verification pass N1 + codex review [high] ×2): a string holding a private-key PEM
+ *  header ANYWHERE ({@link PRIVATE_KEY_PEM_HEADER}) is withheld WHOLE, and no result trips `containsSecretToken`.
+ *  The PEM header is judged on the ORIGINAL text, before any replacement: the token pass can rewrite the header
+ *  itself away (`sk-note:-----BEGIN` is one token-charset run that starts with `sk-`, so it becomes
+ *  `[redacted-secret]` and the key body after it would ride out untouched — codex verification round). A PEM header
+ *  carries spaces, so the targeted passes can never isolate it, and the detector only sees it at the very start of
+ *  a string. Every warning face that goes through here (coordinates, error text, entry identity) inherits the same
+ *  guarantee. The validation-side detector `containsSecretToken` is deliberately NOT widened here: making it reject
+ *  a mid-string PEM would tighten every field it validates (a major). */
 export declare function redactSecrets(text: string): string;
 /** Sanitize a ZodError IN PLACE so no surfaced error (message / `received` / nested `unionErrors`) echoes a
  *  pasted secret. RECURSES into `unionErrors` (a `z.union` failure nests a ZodError per member — e.g. RoleTarget
@@ -151,12 +161,48 @@ export type ConfigPath = readonly (string | number)[];
  *  **刻意不提供 parse 反函数**:2.1.0 起没有任何一处把坐标读回来(回写走 `keptIndex` 那本账),给它
  *  一个反函数就是给下一个人一条「在串上做事」的路。 */
 export declare function formatConfigPath(p: ConfigPath): string;
+/** 一条被丢掉的条目的**身份**(S-712):只从被丢条目**原文**里取,三键各自可缺。
+ *
+ *  律(一条,不分域):`name` / `id` 取**字符串**形、`enabled` 取**布尔**形,类型不对 ⇒ 不带该键(不猜、
+ *  不 `String()` 转换);只认**数据属性**(不触发访问器);{@link redactSecrets} 会改动的串 ⇒ 不带该键 ——
+ *  与坐标段同一只脱敏判据:坐标段必须在场,所以打码出门;身份是可缺的,打过码的串不再是任何条目的身份,
+ *  所以是**不带**而不是打码。三键都读不出 ⇒ 整个身份缺席(不铸空对象)。
+ *
+ *  **缺席 = 读不出**(不是字符串,或是字符串但不能原样出门),两种原因刻意不分:对消费方的正确处置相同
+ *  (身份未知 ⇒ 按未知处置,例如 fail-closed),而一个「被扣下」的标记本身就在说「这里有一段像凭据的东西」。
+ *
+ *  为什么要带:条目被丢之后它的名字从目录里消失,只给坐标的话,消费方要知道「丢的是谁」只能拿坐标回读
+ *  原文档 —— 而它手里那份原文档未必是这一次读到的那份。铸告警的这一层判的就是那条原文,在这里取一次、
+ *  随告警走,是唯一不会读错版本的地方。停用条目(`enabled:false`)照样带身份:判不判墓碑是消费方的事。 */
+export interface DroppedEntryIdentity {
+    name?: string;
+    id?: string;
+    enabled?: boolean;
+}
 /** 一条被丢掉的条目:`path` = 段坐标({@link ConfigPath};`["models", 3]` / `["roles", "summarize"]`),
- *  `error` 已脱敏。 */
+ *  `error` 已脱敏,`identity`(S-712)见 {@link DroppedEntryIdentity}(读不出 ⇒ 键缺席)。 */
 export interface DroppedEntry {
     path: ConfigPath;
     error: unknown;
+    identity?: DroppedEntryIdentity;
 }
+/** 身份串 —— 「一个用户写的身份串(条目的 `name` / `id`)能不能**原样**出门」的**唯一**判据:
+ *  {@link redactSecrets} 原样放行。入参是 `string`、返回 `boolean`,**刻意不是**类型谓词(`v is string`):它对一些
+ *  字符串答 false,谓词形会让调用方的否定分支把一个 `string` 收窄成 `never`;「是不是字符串」由调用点自己判
+ *  (运行期收到非字符串照答 false、不抛)。秘密形的串按**无名**处置(不带,而不是打码:打过码的串不再是身份)。
+ *  与坐标段脱敏、`error` 文案脱敏({@link sanitizeZodError})**同一只**判据:告警面上任何一处用户写的串,要么过这一只
+ *  脱敏器出门,要么(可缺的身份)不出门。两只判据会在同一条告警里给出两种答案(对抗轮 #2 真复现:`Bearer` 后接 NBSP
+ *  或短令牌时,旧判据放行、坐标却打码)。
+ *  执法面(同一条律):被丢条目的身份({@link DroppedEntryIdentity},本文件铸);`ModelRefusalsWire` 的 `entries` 键
+ *  (经 {@link isReportableRefusalName},S-768);引擎自己的日志 / 拒因句里要不要写出一个名字,同样问这一只。 */
+export declare function isDisclosableIdentity(v: string): boolean;
+/** S-768 —— 「一个目录条目名能不能当 {@link ModelRefusalsWire} `entries` 的键」的**唯一**判据;引擎铸键前只调这一只,
+ *  不过 ⇒ 按无名处置(不进键、不计数)。两条律的合取,不手抄任何一条:
+ *   ① 这只 schema **自己载得住**这个键 —— 就地拿 schema 判(空串不过键规则;`__proto__` 这类名被 zod 的 record 静默丢掉,
+ *      载不住),不写名单;
+ *   ② {@link isDisclosableIdentity}(秘密形 ⇒ 不出门)。
+ *  非字符串 ⇒ false。住在本文件而不是 `./fleet`:`fleet.ts` 被 `types.ts` 引,它再引本文件会成环。 */
+export declare function isReportableRefusalName(name: string): boolean;
 /** 抢救造成的**下标位移表**:数组字段名 → 该字段压缩后每个位置的**原**下标(`kept[j]` = 压缩后第 j 条
  *  在原文档里的下标)。纯数据,无行为。
  *
@@ -282,12 +328,15 @@ export type EffectiveReadWarning = {
 /** 一条**条目**没通过它自己的 entry schema,被单独丢掉了(域内其余条目照常生效)。`path` = 段坐标
  *  (`["models",3]` / `["roles","summarize"]`),与 `unknown-keys-dropped` 的坐标形同一套。逐条一发 —— 载荷是
  *  O(域里的条目数),与被读文档同阶,不放大,故不设条数上限(有上限的是**单条**告警里的键列表)。
- *  2.0.0 起;只可能来自 {@link DOMAIN_READ_FALLBACK} 判 `"default"` 的域,gate 域坏形仍然 throw。 */
+ *  2.0.0 起;只可能来自 {@link DOMAIN_READ_FALLBACK} 判 `"default"` 的域,gate 域坏形仍然 throw。
+ *  **S-712**(additive):`identity` = 被丢条目原文里读得出的身份({@link DroppedEntryIdentity};
+ *  读不出 ⇒ 键缺席),消费方据此知道「丢的是谁」而不必拿坐标回读原文档。 */
  | {
     domain: DomainName;
     kind: "entry-dropped";
     path: ConfigPath;
     error: unknown;
+    identity?: DroppedEntryIdentity;
 }
 /** `config.d/` 里存在、但本地读取集**永远不会读**的文件(名字不是域,或是域但不便携)。 */
  | {