@sema-agent/settings-schema 6.2.0 → 6.4.0

package/dist/secret-scan.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 秘密扫描读的**归一化**,外加「URL 的 userinfo 就是凭据」那一只判定({@link carriesUserinfo})—— 包内私有模块(6.3.0):不进主 barrel、
+ * 不进 `package.json` 的 `exports`,消费方拿不到。
+ * 校验侧探测器 `containsSecretToken`(`./types`)只读 {@link percentLayers};展示侧脱敏器 `redactSecrets`(`./config-fns`)
+ * 读 {@link secretScanForms}。展示侧的读法(边界读法、`+` 读法、「没走完」那一位)刻意不做公开契约:它们以后要随新发现的
+ * 编码形调整,调整不该是契约变更(opus 独立腿 L7)。
+ *
+ * **单遍、零异常**(opus 独立腿 M1,对 6.2.0 的读路径 CPU 回归):6.2.0 起的宽容解码对每个 `%HH` 各 `try decodeURIComponent`,
+ * 非 ASCII 的转义每个都抛一次异常(≈ 20–30 µs / 字节,同步阻塞);6.3.0 首稿又让探测器顺带算它不用的展示形。这里两处解码都
+ * 不靠异常:单个转义的判据写成字符集(只有 ASCII 的 `%00`–`%7F` 单独解得开),转义串的判据写成 UTF-8 良构判定 ——
+ * 结果与原来的 try/catch 逐字相同(`test/disclosable-identity-6.3.0.test.ts` 的两只冻结 oracle 钉着)。
+ *
+ * 本模块零 import(`./types` 引它,它不回引,不成环)。
+ */
+/** How many percent-decoded layers a secret scan reads beyond the raw string (a multi-encoded `%2573%256B…` →
+ *  `%73%6B…` → `sk-…`). Bounded → deterministic. */
+export declare const SECRET_SCAN_DECODE_LAYERS = 3;
+/** The raw string first, then up to {@link SECRET_SCAN_DECODE_LAYERS} tolerant percent-decoded layers, stopping at the first
+ *  layer that decodes nothing — the forms the validation detector `containsSecretToken` reads, and nothing else. */
+export declare function percentLayers(text: string): readonly string[];
+/** What {@link secretScanForms} returns — plain data, no behavior. */
+export interface SecretScanForms {
+    /** {@link percentLayers} of the text. */
+    readonly percentLayers: readonly string[];
+    /** The forms the display-side redactor judges a whole string on: `percentLayers`, each layer's {@link boundaryReading}, and
+     *  each of those read the application/x-www-form-urlencoded way (`+` as a space); duplicates dropped, first seen first. */
+    readonly forms: readonly string[];
+    /** Normalization did not finish: the layer budget ran out while one more layer would still decode something. A caller that
+     *  shows text withholds it whole — what could not be normalized does not go out. (A lone undecodable escape is a fixed
+     *  point, not an unfinished one: `%E4%B8%AD` stays as it is and is not flagged.) */
+    readonly unresolved: boolean;
+}
+/** The display-side normalization — only `redactSecrets` (config-fns) calls it. */
+export declare function secretScanForms(text: string): SecretScanForms;
+/** 「URL 的 userinfo 就是凭据」的**唯一**判定(6.3.0,opus 腿 L1):username / password 任一在场即是。校验侧 `NON_SECRET_URL` 与 https
+ *  插件源据此拒写(`./types`),身份面据此否决(`./config-fns` 的 `isDisclosableIdentity` —— `https://admin:hunter2@db…` /
+ *  `postgres://svc:pw@h` 的字符全在身份白名单里)。串解析不成 URL ⇒ false:这只判定只说「一个 URL 带没带 userinfo」,
+ *  不是 URL 的串不在它的射程里(无 scheme 的 `svc:pw@host` 解析成不透明路径,同样答 false —— 如实登记的边界)。 */
+export declare function carriesUserinfo(u: URL | string): boolean;

package/dist/secret-scan.js

@@ -0,0 +1,110 @@
+/**
+ * 秘密扫描读的**归一化**,外加「URL 的 userinfo 就是凭据」那一只判定({@link carriesUserinfo})—— 包内私有模块(6.3.0):不进主 barrel、
+ * 不进 `package.json` 的 `exports`,消费方拿不到。
+ * 校验侧探测器 `containsSecretToken`(`./types`)只读 {@link percentLayers};展示侧脱敏器 `redactSecrets`(`./config-fns`)
+ * 读 {@link secretScanForms}。展示侧的读法(边界读法、`+` 读法、「没走完」那一位)刻意不做公开契约:它们以后要随新发现的
+ * 编码形调整,调整不该是契约变更(opus 独立腿 L7)。
+ *
+ * **单遍、零异常**(opus 独立腿 M1,对 6.2.0 的读路径 CPU 回归):6.2.0 起的宽容解码对每个 `%HH` 各 `try decodeURIComponent`,
+ * 非 ASCII 的转义每个都抛一次异常(≈ 20–30 µs / 字节,同步阻塞);6.3.0 首稿又让探测器顺带算它不用的展示形。这里两处解码都
+ * 不靠异常:单个转义的判据写成字符集(只有 ASCII 的 `%00`–`%7F` 单独解得开),转义串的判据写成 UTF-8 良构判定 ——
+ * 结果与原来的 try/catch 逐字相同(`test/disclosable-identity-6.3.0.test.ts` 的两只冻结 oracle 钉着)。
+ *
+ * 本模块零 import(`./types` 引它,它不回引,不成环)。
+ */
+/** How many percent-decoded layers a secret scan reads beyond the raw string (a multi-encoded `%2573%256B…` →
+ *  `%73%6B…` → `sk-…`). Bounded → deterministic. */
+export const SECRET_SCAN_DECODE_LAYERS = 3;
+/** One TOLERANT percent-decode layer: an escape decodes on its own iff `decodeURIComponent` would accept it alone — exactly
+ *  the ASCII ones, `%00`–`%7F` — and every other escape (`%C2`, a lone `%E4`, `%ZZ` is not an escape at all) stays as it
+ *  is, so one bad escape elsewhere can't abort the whole decode (R13's all-or-nothing decodeURIComponent did). Same result
+ *  as the per-escape try/catch loop it replaces, with no exception per non-ASCII escape. */
+function percentDecodeLayer(s) {
+    return s.indexOf("%") === -1 ? s : s.replace(/%([0-7][0-9A-Fa-f])/g, (_m, hex) => String.fromCharCode(parseInt(hex, 16)));
+}
+/** The raw string first, then up to {@link SECRET_SCAN_DECODE_LAYERS} tolerant percent-decoded layers, stopping at the first
+ *  layer that decodes nothing — the forms the validation detector `containsSecretToken` reads, and nothing else. */
+export function percentLayers(text) {
+    const layers = [text];
+    let cur = text;
+    for (let i = 0; i < SECRET_SCAN_DECODE_LAYERS; i++) {
+        const next = percentDecodeLayer(cur);
+        if (next === cur)
+            break;
+        layers.push(next);
+        cur = next;
+    }
+    return layers;
+}
+/** Is this byte sequence well-formed UTF-8 (Unicode Table 3-7: no overlongs, no surrogates, nothing above U+10FFFF)? That is
+ *  exactly when `decodeURIComponent` accepts a run of escapes spelling these bytes — decided without throwing. */
+function isWellFormedUtf8(bytes) {
+    for (let i = 0; i < bytes.length;) {
+        const lead = bytes[i];
+        if (lead < 0x80) {
+            i += 1;
+            continue;
+        }
+        // [续字节个数, 第一个续字节的下界, 上界];其余续字节恒为 80..BF。
+        const shape = lead >= 0xc2 && lead <= 0xdf ? [1, 0x80, 0xbf]
+            : lead === 0xe0 ? [2, 0xa0, 0xbf]
+                : (lead >= 0xe1 && lead <= 0xec) || lead === 0xee || lead === 0xef ? [2, 0x80, 0xbf]
+                    : lead === 0xed ? [2, 0x80, 0x9f]
+                        : lead === 0xf0 ? [3, 0x90, 0xbf]
+                            : lead >= 0xf1 && lead <= 0xf3 ? [3, 0x80, 0xbf]
+                                : lead === 0xf4 ? [3, 0x80, 0x8f]
+                                    : undefined;
+        if (shape === undefined)
+            return false;
+        const [need, lo, hi] = shape;
+        for (let k = 1; k <= need; k++) {
+            const c = bytes[i + k];
+            if (c === undefined || c < (k === 1 ? lo : 0x80) || c > (k === 1 ? hi : 0xbf))
+                return false;
+        }
+        i += need + 1;
+    }
+    return true;
+}
+/** The display-side BOUNDARY reading of one layer (codex r2): every run of %HH escapes is decoded as UTF-8 in one go when it
+ *  is well-formed (an encoded NBSP / zero-width space becomes the delimiter it really is); otherwise its ASCII escapes decode
+ *  on their own and every other escape reads as a space — an escape never glues its hex digits onto the token after it
+ *  (`%C2%A0sk-live-…` read escape by escape is `%C2%A0sk-…`, whose tokens are `C2` / `A0sk-…`: the `sk-` boundary is gone,
+ *  though any standard decoder restores it). Display-only: the validation detector never reads it. */
+function boundaryReading(s) {
+    if (s.indexOf("%") === -1)
+        return s;
+    return s.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+        const bytes = [];
+        for (let i = 0; i < run.length; i += 3)
+            bytes.push(parseInt(run.slice(i + 1, i + 3), 16));
+        return isWellFormedUtf8(bytes) ? decodeURIComponent(run) : bytes.map((b) => (b < 0x80 ? String.fromCharCode(b) : " ")).join("");
+    });
+}
+/** The display-side normalization — only `redactSecrets` (config-fns) calls it. */
+export function secretScanForms(text) {
+    const layers = percentLayers(text);
+    const last = layers[layers.length - 1];
+    const unresolved = layers.length === SECRET_SCAN_DECODE_LAYERS + 1 && percentDecodeLayer(last) !== last;
+    const readings = [...layers, ...layers.map((layer) => boundaryReading(layer))];
+    const forms = [...new Set([...readings, ...readings.map((reading) => (reading.indexOf("+") === -1 ? reading : reading.replace(/\+/g, " ")))])];
+    return { percentLayers: layers, forms, unresolved };
+}
+/** 「URL 的 userinfo 就是凭据」的**唯一**判定(6.3.0,opus 腿 L1):username / password 任一在场即是。校验侧 `NON_SECRET_URL` 与 https
+ *  插件源据此拒写(`./types`),身份面据此否决(`./config-fns` 的 `isDisclosableIdentity` —— `https://admin:hunter2@db…` /
+ *  `postgres://svc:pw@h` 的字符全在身份白名单里)。串解析不成 URL ⇒ false:这只判定只说「一个 URL 带没带 userinfo」,
+ *  不是 URL 的串不在它的射程里(无 scheme 的 `svc:pw@host` 解析成不透明路径,同样答 false —— 如实登记的边界)。 */
+export function carriesUserinfo(u) {
+    let url;
+    if (typeof u === "string") {
+        try {
+            url = new URL(u);
+        }
+        catch {
+            return false; // 不是 URL:不在这只判定的射程里(见头注),不是回退
+        }
+    }
+    else
+        url = u;
+    return url.username !== "" || url.password !== "";
+}

package/dist/types.d.ts

@@ -18,9 +18,10 @@
 import { z } from "zod";
 /** A private-key PEM header (`-----BEGIN [RSA |EC |OPENSSH |ENCRYPTED ]PRIVATE KEY`), unanchored — the ONE definition
  *  of that shape: {@link SECRET_LITERAL_RE} is composed from it (anchored, as one of its branches), and
- *  `redactSecrets` (config-fns) tests it ANYWHERE in a string. It carries spaces, so the token-splitting detector
- *  {@link containsSecretToken} only sees it at the very start of a string; a PEM behind a newline or a `key: ` prefix
- *  slipped past (S-712 codex review [high]). Public keys / certificates never match (see above). */
+ *  `redactSecrets` (config-fns) tests it ANYWHERE in a string, on every display-side normalized form. It carries spaces,
+ *  so the token-splitting detector {@link containsSecretToken} only sees it at the very start of a string; a PEM behind
+ *  a newline or a `key: ` prefix slipped past (S-712 codex review [high]), and a `key=`-prefixed percent-encoded one
+ *  hid it behind `%20` on the raw form, a form-urlencoded one behind `+` (6.3.0). Public keys / certificates never match. */
 export declare const PRIVATE_KEY_PEM_HEADER: RegExp;
 export declare const SECRET_LITERAL_RE: RegExp;
 export declare const ENV_NAME: z.ZodEffects<z.ZodString, string, string>;
@@ -29,9 +30,15 @@ export declare const ENV_NAME: z.ZodEffects<z.ZodString, string, string>;
  *  fs path — so the worker dies at exec/boot, not at config edit. A NUL is never legitimate in a command / path
  *  / host / image, so reject it on every exec-bound string field (mcp stdio + the whole remoteExec contract). R20. */
 export declare const hasNul: (s: string) => boolean;
-/** Does `s` contain a secret-shaped token? Scans the raw string AND a percent-decoded form (a secret can hide
- *  as `%73%6B-…`) — so mcp args / dockerHost / URL components all get uniform percent-decode coverage. Tokenized
- *  + JWT-aware (see scanForSecret). Shared by NON_SECRET_URL + dockerHost + mcp stdio. Round-4/5/11. */
+/** Does `s` contain a secret-shaped token? Scans every percent layer of it — the raw string AND up to three tolerant
+ *  percent-decoded layers (a secret can hide as `%73%6B-…`; the ONE definition of those layers is `percentLayers` in the
+ *  package-private `./secret-scan`) — so mcp args / dockerHost / URL components all get uniform percent-decode coverage.
+ *  Tokenized + JWT-aware (see scanForSecret). Shared by NON_SECRET_URL + dockerHost + mcp stdio. Round-4/5/11. (6.3.0 moved
+ *  the decode loop out, unchanged in result — same layers, same bound, same verdict — and made it exception-free; the
+ *  display-side readings the redactor also judges are not this detector's.) We do NOT fail-closed on a bare `%` — that
+ *  would false-reject legit values like `100%` / `%s`. A secret glued to a malformed escape (`%ZZsk-`) is an accepted
+ *  coarse-heuristic gap (no consumer reconstructs it; the real guarantee is the env-NAME boundary on structured fields).
+ *  R11/R13/R14. */
 export declare function containsSecretToken(s: string): boolean;
 /** Scan a URL's PATH + query + fragment (KEYS and values, decoded, tokenized) for a secret-shaped literal.
  *  Userinfo is handled separately (NON_SECRET_URL bans it; dockerHost scans the ssh user). Round-4/5. */
@@ -110,7 +117,8 @@ export declare const SealedApiKey: z.ZodObject<{
 export type SealedApiKey = z.infer<typeof SealedApiKey>;
 /** 谁来校验一个**解析透明键**的形。闭集:新增一员要在这里加词,穷举消费方即编译红。
  *  · `engine-ingest` —— 引擎摄入侧单点校验(不合形的那一条不挂并通告一次);
- *  · `consumer`      —— 消费方的投影/执法点(丢掉坏的那一个键、保留其宿主条目、记账)。 */
+ *  · `consumer`      —— 消费方的投影/执法点。坏值怎么处置(只丢那一个键 / 整条宿主条目不可用)是那个执法点自己的
+ *                      契约,写在登记行的 `why` 里 —— 本包不替它定。 */
 export type ParseTransparentValidator = "engine-ingest" | "consumer";
 /** {@link PARSE_TRANSPARENT_KEYS} 的一行。 */
 export interface ParseTransparentKey {
@@ -240,6 +248,16 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
      *  deep to hash later. That is not shape validation — it is the boundary every free-form value must clear to
      *  enter the persisted config and `stableHash` (R18). */
     compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
+    /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+     *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+     *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+     *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+     *  ABSENT = key not minted = today's behaviour, zero migration.
+     *
+     *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+     *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+     *  `extraBody` ({@link vetFreeFormJson}). */
+    headers: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
     /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
      *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
     quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -276,6 +294,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: Record<string, unknown> | undefined;
     compat?: unknown;
+    headers?: unknown;
     notes?: string | undefined;
 }, {
     id: string;
@@ -306,6 +325,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: unknown;
     compat?: unknown;
+    headers?: unknown;
     quotaWeight?: number | undefined;
     enabled?: boolean | undefined;
     notes?: string | undefined;
@@ -340,6 +360,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: Record<string, unknown> | undefined;
     compat?: unknown;
+    headers?: unknown;
     notes?: string | undefined;
 }, {
     id: string;
@@ -370,6 +391,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
     } | undefined;
     extraBody?: unknown;
     compat?: unknown;
+    headers?: unknown;
     quotaWeight?: number | undefined;
     enabled?: boolean | undefined;
     notes?: string | undefined;
@@ -578,6 +600,16 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
          *  deep to hash later. That is not shape validation — it is the boundary every free-form value must clear to
          *  enter the persisted config and `stableHash` (R18). */
         compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
+        /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+         *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+         *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+         *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+         *  ABSENT = key not minted = today's behaviour, zero migration.
+         *
+         *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+         *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+         *  `extraBody` ({@link vetFreeFormJson}). */
+        headers: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
         /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
          *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
         quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -614,6 +646,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }, {
         id: string;
@@ -644,6 +677,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -678,6 +712,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }, {
         id: string;
@@ -708,6 +743,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -832,6 +868,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }[];
     roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -887,6 +924,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -946,6 +984,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
         compat?: unknown;
+        headers?: unknown;
         notes?: string | undefined;
     }[];
     roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -1001,6 +1040,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
         } | undefined;
         extraBody?: unknown;
         compat?: unknown;
+        headers?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -9494,6 +9534,16 @@ export declare const DOMAIN_SCHEMAS: {
              *  deep to hash later. That is not shape validation — it is the boundary every free-form value must clear to
              *  enter the persisted config and `stableHash` (R18). */
             compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
+            /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+             *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+             *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+             *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+             *  ABSENT = key not minted = today's behaviour, zero migration.
+             *
+             *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+             *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+             *  `extraBody` ({@link vetFreeFormJson}). */
+            headers: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
             /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
              *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
             quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -9530,6 +9580,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }, {
             id: string;
@@ -9560,6 +9611,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9594,6 +9646,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }, {
             id: string;
@@ -9624,6 +9677,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9748,6 +9802,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }[];
         roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -9803,6 +9858,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9862,6 +9918,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
             compat?: unknown;
+            headers?: unknown;
             notes?: string | undefined;
         }[];
         roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -9917,6 +9974,7 @@ export declare const DOMAIN_SCHEMAS: {
             } | undefined;
             extraBody?: unknown;
             compat?: unknown;
+            headers?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;

package/dist/types.js

@@ -18,6 +18,7 @@
 import { z } from "zod";
 import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody depth cap with the hash cap (R18)
 import { DispatchPolicy } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
+import { carriesUserinfo, percentLayers } from "./secret-scan.js"; // package-private normalization + the userinfo judgement (not in the barrel)
 // COARSE, best-effort literal-secret SHAPE detector (NOT exhaustive — the real boundary is the env-NAME schema
 // on structured fields). Rejected in free-form value fields (worker `env`, model `extraBody`), URL components,
 // AND as an env-NAME value (an AWS key id is a valid env-NAME charset yet is a secret VALUE, not a NAME). Case-
@@ -28,9 +29,10 @@ import { DispatchPolicy } from "./fleet.js"; // WorkerSpec.fleet.dispatch (sched
 // which review flagged as a bypass (a private key misnamed `*_PUBKEY` skipped scanning entirely).
 /** A private-key PEM header (`-----BEGIN [RSA |EC |OPENSSH |ENCRYPTED ]PRIVATE KEY`), unanchored — the ONE definition
  *  of that shape: {@link SECRET_LITERAL_RE} is composed from it (anchored, as one of its branches), and
- *  `redactSecrets` (config-fns) tests it ANYWHERE in a string. It carries spaces, so the token-splitting detector
- *  {@link containsSecretToken} only sees it at the very start of a string; a PEM behind a newline or a `key: ` prefix
- *  slipped past (S-712 codex review [high]). Public keys / certificates never match (see above). */
+ *  `redactSecrets` (config-fns) tests it ANYWHERE in a string, on every display-side normalized form. It carries spaces,
+ *  so the token-splitting detector {@link containsSecretToken} only sees it at the very start of a string; a PEM behind
+ *  a newline or a `key: ` prefix slipped past (S-712 codex review [high]), and a `key=`-prefixed percent-encoded one
+ *  hid it behind `%20` on the raw form, a form-urlencoded one behind `+` (6.3.0). Public keys / certificates never match. */
 export const PRIVATE_KEY_PEM_HEADER = /-----BEGIN[A-Z0-9 ]*PRIVATE KEY/i;
 export const SECRET_LITERAL_RE = new RegExp(`^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\\s|basic\\s|eyJ[A-Za-z0-9_-]{10,}\\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|${PRIVATE_KEY_PEM_HEADER.source})`, "i");
 // 所有 *Env / *tokenEnv 字段的值是宿主机 env 变量的 NAME（不是值）。合法 env 变量名 + 拒绝 secret 形状的值（AKIA…
@@ -71,33 +73,17 @@ function scanForSecret(s) {
  *  fs path — so the worker dies at exec/boot, not at config edit. A NUL is never legitimate in a command / path
  *  / host / image, so reject it on every exec-bound string field (mcp stdio + the whole remoteExec contract). R20. */
 export const hasNul = (s) => s.includes("\0");
-/** Does `s` contain a secret-shaped token? Scans the raw string AND a percent-decoded form (a secret can hide
- *  as `%73%6B-…`) — so mcp args / dockerHost / URL components all get uniform percent-decode coverage. Tokenized
- *  + JWT-aware (see scanForSecret). Shared by NON_SECRET_URL + dockerHost + mcp stdio. Round-4/5/11. */
+/** Does `s` contain a secret-shaped token? Scans every percent layer of it — the raw string AND up to three tolerant
+ *  percent-decoded layers (a secret can hide as `%73%6B-…`; the ONE definition of those layers is `percentLayers` in the
+ *  package-private `./secret-scan`) — so mcp args / dockerHost / URL components all get uniform percent-decode coverage.
+ *  Tokenized + JWT-aware (see scanForSecret). Shared by NON_SECRET_URL + dockerHost + mcp stdio. Round-4/5/11. (6.3.0 moved
+ *  the decode loop out, unchanged in result — same layers, same bound, same verdict — and made it exception-free; the
+ *  display-side readings the redactor also judges are not this detector's.) We do NOT fail-closed on a bare `%` — that
+ *  would false-reject legit values like `100%` / `%s`. A secret glued to a malformed escape (`%ZZsk-`) is an accepted
+ *  coarse-heuristic gap (no consumer reconstructs it; the real guarantee is the env-NAME boundary on structured fields).
+ *  R11/R13/R14. */
 export function containsSecretToken(s) {
-    // scan the raw string AND up to 3 percent-decoded layers (handles a multi-encoded `%2573%256B…` → `%73%6B…`
-    // → `sk-…`). TOLERANT decode: each valid %HH is decoded, a malformed escape (`%ZZ`, `%` at end) is left as-is
-    // so one bad escape elsewhere can't abort the whole decode (R13's all-or-nothing decodeURIComponent did). We
-    // do NOT fail-closed on a bare `%` — that would false-reject legit values like `100%` / `%s`. A secret glued
-    // to a malformed escape (`%ZZsk-`) is an accepted coarse-heuristic gap (no consumer reconstructs it; the real
-    // guarantee is the env-NAME boundary on structured fields). Bounded → deterministic. R11/R13/R14. */
-    let cur = s;
-    for (let i = 0; i < 4; i++) {
-        if (scanForSecret(cur))
-            return true;
-        const next = cur.replace(/%[0-9A-Fa-f]{2}/g, (m) => {
-            try {
-                return decodeURIComponent(m);
-            }
-            catch {
-                return m;
-            }
-        });
-        if (next === cur)
-            break;
-        cur = next;
-    }
-    return false;
+    return percentLayers(s).some((form) => scanForSecret(form));
 }
 /** Scan a URL's PATH + query + fragment (KEYS and values, decoded, tokenized) for a secret-shaped literal.
  *  Userinfo is handled separately (NON_SECRET_URL bans it; dockerHost scans the ssh user). Round-4/5. */
@@ -141,7 +127,7 @@ export const NON_SECRET_URL = z
     .refine((s) => {
     try {
         const u = new URL(s);
-        if (!(u.protocol === "http:" || u.protocol === "https:") || !u.host || u.username || u.password)
+        if (!(u.protocol === "http:" || u.protocol === "https:") || !u.host || carriesUserinfo(u))
             return false;
         return !urlQueryFragmentHasSecret(u);
     }
@@ -215,9 +201,9 @@ export function extraBodyUnsafe(v) {
     }
     return false;
 }
-/** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`
- *  and `ModelEntry.compat` share this ONE function (1.10.0; before that it was inline in `extraBody` and a second
- *  free-form field would have copied it). The judgment is identical for every such field, so it lives in one place:
+/** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`,
+ *  `ModelEntry.compat` and `ModelEntry.headers` share this ONE function (1.10.0; before that it was inline in `extraBody`
+ *  and a second free-form field would have copied it). The judgment is identical for every such field, so it lives in one place:
  *
  *   1. getter-free descriptor walk ({@link extraBodyUnsafe}) over the RAW value — never invokes a getter, and any
  *      reflective throw (a hostile Proxy trap could throw a secret-bearing message) collapses into a FIXED message;
@@ -248,6 +234,22 @@ function vetFreeFormJson(v, field) {
         return { ok: false, message: `${field}: its serialized form carries a secret` };
     return { ok: true, value: clone };
 }
+/** The transform of every **parse-transparent free-form** key (`z.unknown().optional().transform(createFreeFormTransform(field))`:
+ *  `ModelEntry.compat` / `ModelEntry.headers`) — ONE closure, so those keys cannot drift apart: absent stays absent (key not
+ *  minted); anything else is the {@link vetFreeFormJson} safety judgment and nothing more (no SHAPE rule — whose job that is,
+ *  per key, is {@link PARSE_TRANSPARENT_KEYS}). `extraBody` is not one of these: it has its own shape gate first. */
+function createFreeFormTransform(field) {
+    return (v, ctx) => {
+        if (v === undefined)
+            return undefined;
+        const vetted = vetFreeFormJson(v, field);
+        if (!vetted.ok) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
+            return z.NEVER;
+        }
+        return vetted.value;
+    };
+}
 /** A k8s resource quantity ("250m", "1", "0.5", "512Mi", "1Gi", "128M") — catches garbage at config-submit
  *  rather than surfacing as a reconcile ApplyError at the apiserver (consistent with ENV_NAME/DURATION guards). */
 export const K8S_QUANTITY = z.string().regex(/^\d+(\.\d+)?(m|[kKMGTPE]i?)?$/, 'must be a k8s quantity like "250m", "512Mi", "1Gi"');
@@ -327,6 +329,13 @@ export const PARSE_TRANSPARENT_KEYS = [
         validatedBy: "engine-ingest",
         why: "镜像引擎的 per-model wire-compat 声明(thinkingFormat 等五键);那张词表随引擎走,本包复述一份必漂。",
     },
+    {
+        domain: "models",
+        path: "models[].headers",
+        since: "6.4.0",
+        validatedBy: "consumer",
+        why: "部署 ↔ 供应商的 per-model 附加请求头;判据(头名闭集白名单 × 读它的线路 × 值形)的唯一属主是 server 的目录条目判据(坏声明 ⇒ 该条目整条不可用,不是丢头照常),本包复述一份那张表必漂、两处各一份就是两个写者。",
+    },
     {
         domain: "mcp",
         path: "servers[].source",
@@ -438,16 +447,20 @@ export const ModelEntry = z.object({
     compat: z
         .unknown()
         .optional()
-        .transform((v, ctx) => {
-        if (v === undefined)
-            return undefined;
-        const vetted = vetFreeFormJson(v, "compat");
-        if (!vetted.ok) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
-            return z.NEVER;
-        }
-        return vetted.value;
-    }),
+        .transform(createFreeFormTransform("compat")),
+    /** Per-model extra request headers, deployment ↔ provider (e.g. `{"anthropic-beta": "context-1m-2025-08-07"}` on an
+     *  `anthropic-messages` entry). Real need: a beta that a shell passes as `--betas` / `ANTHROPIC_BETAS` never reaches the
+     *  request the engine sends; the catalog entry is the deployment-level seat for it — and without this key the entry's
+     *  declaration is stripped at parse on every read leg, so it never reaches the consumer at all.
+     *  ABSENT = key not minted = today's behaviour, zero migration.
+     *
+     *  **Parse-transparent** — who validates the shape, and why not here: {@link PARSE_TRANSPARENT_KEYS}
+     *  (`models.models[].headers`). The ONE rejection that remains is the free-form SAFETY judgment shared with `compat` /
+     *  `extraBody` ({@link vetFreeFormJson}). */
+    headers: z
+        .unknown()
+        .optional()
+        .transform(createFreeFormTransform("headers")),
     /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
      *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
     quotaWeight: z.number().finite().nonnegative().default(1),
@@ -2053,7 +2066,7 @@ export const PLUGIN_ORIGIN = z
         return true; // 已被上一条拒;避免对非 URL 再报一条噪声
     try {
         const u = new URL(s);
-        return !u.username && !u.password && !urlQueryFragmentHasSecret(u);
+        return !carriesUserinfo(u) && !urlQueryFragmentHasSecret(u);
     }
     catch {
         return false; // claims to be https but does not parse → reject

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",