@sema-agent/settings-schema 14.5.0 → 14.7.0

package/dist/hooks-config.js

@@ -46,6 +46,7 @@
  * contract; cycles are tolerated, a throwing accessor propagates.
  */
 import { z } from "zod";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { buildQuotedIssue, fixed } from "./quoted-issue.js";
 // ── event vocabulary ───────────────────────────────────────────────────────────────────────────────────────
 // The two halves below are where each word came from (CC 2.1.198's own table, then the later additions) — provenance for the
@@ -141,8 +142,8 @@ export const HOOKS_CLASSIFICATION_OUTCOMES = ["loaded", "loaded-partial", "rejec
 export const HOOKS_DROPPED_PIECE_CODES = ["hooks-not-object", "unknown-event", "event-not-array", "matcher-invalid", "entry-invalid"];
 /**
  * Why the document was REJECTED (closed; each is "a guard may be in this piece"):
- *  · `guard-outside-hooks`       — a guard sign outside `hooks` (top level, under another key, or the document itself matcher-shaped);
- *  · `hooks-is-matcher`          — `hooks` is an array holding objects / arrays, a single matcher, or a single entry;
+ *  · `guard-outside-hooks`       — a guard sign outside `hooks` (top level, under another key, or the document itself matcher-shaped), or the document could not be read at all (path `[]`);
+ *  · `hooks-is-matcher`          — `hooks` is an array holding objects / arrays, a single matcher, or a single entry, or an object that is not a readable block (a class instance, a value that cannot be inspected) holding — or possibly holding — a guard sign;
  *  · `guard-under-unknown-event` — an unknown event name holding a guard sign;
  *  · `guard-event-not-array`     — a guard event whose value is not an array (and not null), or a known event whose non-array value holds a sign;
  *  · `guard-matcher-invalid`     — a bad matcher in a guard event, or a matcher holding a sign (in any event);
@@ -156,20 +157,74 @@ export const HOOKS_REJECTION_CODES = [
     "guard-matcher-invalid",
     "guard-entry-invalid",
 ];
-/** A JSON object: not null, not an array, prototype `Object.prototype` or null. */
-function hookIsRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const proto = Object.getPrototypeOf(value);
-    return proto === Object.prototype || proto === null;
+/** The value's shape — six words: `plain` is a JSON object (not null, not an array, prototype null or a prototype whose own prototype is null: any realm's `Object.prototype`),
+ *  `uninspectable` is a value whose shape cannot be read at all (a proxy that has been revoked, a throwing `getPrototypeOf` trap). This function IS `./plain-json-object`'s `jsonShapeOf`, character for
+ *  character: the classifier is copied as source by consumers' generators, so its closure cannot import — the package has this one second copy, and the test is what keeps it from drifting. */
+function hookShapeOf(v) {
+    try {
+        if (v === null)
+            return "null";
+        if (Array.isArray(v))
+            return "array";
+        if (typeof v === "function")
+            return "non_plain_object";
+        if (typeof v !== "object")
+            return "primitive";
+        const proto = Object.getPrototypeOf(v);
+        return proto === null || Object.getPrototypeOf(proto) === null ? "plain" : "non_plain_object";
+    }
+    catch {
+        return "uninspectable"; // 读形状就抛(已撤销的 Proxy 连 `Array.isArray` 都抛、`getPrototypeOf` 陷阱抛):不是「不朴素」,是读不出 —— 读者按最严处置
+    }
+}
+/** `./plain-json-object` 的 `isPlainJsonObject`,调各自的形状分类核后逐字同文(闭包里不能 import)。 */
+function hookIsRecord(v) {
+    const shape = hookShapeOf(v);
+    return shape === "plain";
+}
+/** Is the value object-like — anything but null / a primitive (arrays, functions and values whose shape cannot be read count). The shape is asked first, never a `typeof` split. */
+function hookIsObjectLike(v) {
+    const shape = hookShapeOf(v);
+    switch (shape) {
+        case "null":
+        case "primitive":
+            return false;
+        case "plain":
+        case "non_plain_object":
+        case "array":
+        case "uninspectable":
+            return true;
+        default: {
+            const unhandled = shape;
+            throw new Error(`hookIsObjectLike: unhandled shape ${String(unhandled)}`);
+        }
+    }
 }
+/** `./plain-json-object` 的 `isJsonArray`,逐字同文(闭包里不能 import):`Array.isArray` 的总版 —— 已撤销的 Proxy 读不出 ⇒ 不是数组,不抛。 */
+function hookIsArray(v) {
+    try {
+        return Array.isArray(v);
+    }
+    catch {
+        return false; // 已撤销的 Proxy:读不出 ⇒ 不是数组
+    }
+}
+/** `Symbol.iterator` WITHOUT the `Symbol` free name: the classifier closure is copied by consumers' generators whose registered built-ins do not include `Symbol` (a new built-in word
+ *  in the closure is a change they must follow), so the well-known symbol is taken from the one place every realm keeps it — `Array.prototype` is iterable by it. Read once at load;
+ *  a process in which `Array.prototype` has lost its iterator cannot say which objects hold content off their own keys, so the module refuses to load rather than answer "none do". */
+const HOOK_ITERATOR_SYMBOL = (() => {
+    const found = Object.getOwnPropertySymbols(Array.prototype).find((s) => s.description === "Symbol.iterator");
+    if (found === undefined)
+        throw new Error("hooks classifier: Array.prototype has no Symbol.iterator");
+    return found;
+})();
 /** The first own key of `node` (in key order) that names a guard event with a value other than null / undefined / `[]` (CC `ei`). */
 function hookGuardKeyOf(node) {
     for (const key of Object.keys(node)) {
         if (!HOOK_GUARD_EVENTS.includes(key))
             continue;
         const value = node[key];
-        if (value !== null && value !== undefined && !(Array.isArray(value) && value.length === 0))
+        if (value !== null && value !== undefined && !(hookIsArray(value) && value.length === 0))
             return key;
     }
     return undefined;
@@ -179,9 +234,9 @@ function hookLooksLikeMatcher(value) {
     if (!hookIsRecord(value))
         return false;
     const inner = Object.hasOwn(value, "hooks") ? value.hooks : undefined;
-    if (Array.isArray(inner))
+    if (hookIsArray(inner))
         return inner.length > 0;
-    return hookIsRecord(inner) && (Object.hasOwn(value, "matcher") || typeof inner.type === "string");
+    return hookIsRecord(inner) && (Object.hasOwn(value, "matcher") || (Object.hasOwn(inner, "type") && typeof inner.type === "string"));
 }
 /**
  * The coordinate of the first guard sign in `root`'s subtree, or undefined: each object answers for itself before its members are searched (its own
@@ -203,25 +258,54 @@ function hookGuardSignIn(root, rootPath, place) {
     };
     while (pending.length > 0) {
         const [node, frame, at] = pending.pop();
-        if (node === null || typeof node !== "object" || seen[at].has(node))
+        // the shape is asked BEFORE any `typeof` split: a node whose shape cannot be read — a proxy that has been revoked, of a function target included — cannot be shown free of guard signs
+        // ⇒ reported as a sign at its own coordinate (fail-closed: the document is rejected); no `typeof` gate of the classifier's own stands in front of the seat
+        const shape = hookShapeOf(node);
+        let isList = false;
+        switch (shape) {
+            case "null":
+            case "primitive":
+                continue; // not an object: nothing to search
+            case "uninspectable":
+                return pathTo(frame, []);
+            case "array":
+                isList = true;
+                break;
+            case "plain":
+                break; // searched as an object below
+            case "non_plain_object":
+                // an object whose content is supplied by the iteration protocol (a Map, a Set, a generator …) holds that content OFF its own keys: the own-key search below
+                // would find nothing and a guard held inside would vanish with the dropped piece. It cannot be shown free of guard signs ⇒ a sign at its own coordinate (same arm as
+                // "uninspectable"). Every other non-plain object (a class instance, a Date, a function) keeps what it holds on its own keys, searched below.
+                if (HOOK_ITERATOR_SYMBOL in node)
+                    return pathTo(frame, []);
+                break;
+            default: {
+                const unhandled = shape;
+                throw new Error(`hookGuardSignIn: unhandled shape ${String(unhandled)}`);
+            }
+        }
+        const visited = node;
+        if (seen[at].has(visited))
             continue;
-        seen[at].add(node);
-        if (Array.isArray(node)) {
-            for (let i = node.length - 1; i >= 0; i--) {
+        seen[at].add(visited);
+        if (isList) {
+            const list = node;
+            for (let i = list.length - 1; i >= 0; i--) {
                 frames.push({ key: i, parent: frame });
-                pending.push([node[i], frames.length - 1, at === "matcherList" ? "matcher" : "other"]);
+                pending.push([list[i], frames.length - 1, at === "matcherList" ? "matcher" : "other"]);
             }
             continue;
         }
-        const guardKey = hookGuardKeyOf(node);
+        const guardKey = hookGuardKeyOf(visited);
         if (guardKey !== undefined)
             return pathTo(frame, [guardKey]);
-        if (at !== "matcher" && hookLooksLikeMatcher(node))
+        if (at !== "matcher" && hookLooksLikeMatcher(visited))
             return pathTo(frame, []);
-        const keys = Object.keys(node);
+        const keys = Object.keys(visited);
         for (let i = keys.length - 1; i >= 0; i--) {
             frames.push({ key: keys[i], parent: frame });
-            pending.push([node[keys[i]], frames.length - 1, "other"]);
+            pending.push([visited[keys[i]], frames.length - 1, "other"]);
         }
     }
     return undefined;
@@ -248,7 +332,7 @@ function hookFieldFits(base, value) {
         case "stringRecord":
             return hookIsRecord(value) && Object.values(value).every((v) => typeof v === "string");
         case "stringList":
-            if (!Array.isArray(value))
+            if (!hookIsArray(value))
                 return false;
             for (let i = 0; i < value.length; i++)
                 if (typeof value[i] !== "string")
@@ -283,7 +367,7 @@ function hookEntryRead(entry) {
         const base = (optional ? kind.slice(0, -1) : kind);
         if (!hookFieldFits(base, value))
             return { field };
-        out[field] = Array.isArray(value) ? value.slice() : hookIsRecord(value) ? Object.fromEntries(Object.entries(value)) : value;
+        out[field] = hookIsArray(value) ? value.slice() : hookIsRecord(value) ? Object.fromEntries(Object.entries(value)) : value;
     }
     return { entry: out };
 }
@@ -301,18 +385,18 @@ function hookMatcherRead(matcher, at, guardEvent, reject, drop) {
     // the rejection's `field` is the matcher's own guard-event key if it has one, else the first member (document order) whose subtree holds a sign —
     // the order hookGuardSignIn reports
     const signField = hookGuardKeyOf(matcher) ??
-        Object.keys(matcher).find((key) => !(key === "hooks" && Array.isArray(entries)) && hookGuardSignIn(matcher[key], [...at, key], "other") !== undefined);
+        Object.keys(matcher).find((key) => !(key === "hooks" && hookIsArray(entries)) && hookGuardSignIn(matcher[key], [...at, key], "other") !== undefined);
     if (signField !== undefined) {
         reject("guard-matcher-invalid", at, signField);
         return undefined;
     }
     const entrySigns = [];
-    if (Array.isArray(entries))
+    if (hookIsArray(entries))
         for (let j = 0; j < entries.length; j++)
             entrySigns.push(hookGuardSignIn(entries[j], [...at, "hooks", j], "other"));
     const name = Object.hasOwn(matcher, "matcher") ? matcher.matcher : undefined;
-    const badField = name !== undefined && typeof name !== "string" ? "matcher" : !Array.isArray(entries) ? "hooks" : undefined;
-    if (badField !== undefined || !Array.isArray(entries)) {
+    const badField = name !== undefined && typeof name !== "string" ? "matcher" : !hookIsArray(entries) ? "hooks" : undefined;
+    if (badField !== undefined || !hookIsArray(entries)) {
         if (guardEvent || entrySigns.some((sign) => sign !== undefined))
             reject("guard-matcher-invalid", at, badField);
         else
@@ -340,13 +424,16 @@ function hookMatcherRead(matcher, at, guardEvent, reject, drop) {
 /** The `hooks` value → what loads of it (undefined when nothing does), reporting its bad pieces / signs into the two sinks. */
 function hookBlockRead(hooks, reject, drop) {
     if (!hookIsRecord(hooks)) {
-        if (Array.isArray(hooks) && hooks.some((x) => x !== null && typeof x === "object"))
+        if (hookIsArray(hooks) && hooks.some(hookIsObjectLike))
+            reject("hooks-is-matcher", ["hooks"]);
+        // an object that is not a readable block (a class instance, a proxy that cannot be inspected) holding — or possibly holding — a guard sign: reject, never drop it (a dropped guard silently disappears)
+        else if (hookGuardSignIn(hooks, ["hooks"], "other") !== undefined)
             reject("hooks-is-matcher", ["hooks"]);
         else
             drop("hooks-not-object", ["hooks"]);
         return undefined;
     }
-    if (hookLooksLikeMatcher(hooks) || typeof hooks.type === "string") {
+    if (hookLooksLikeMatcher(hooks) || (Object.hasOwn(hooks, "type") && typeof hooks.type === "string")) {
         reject("hooks-is-matcher", ["hooks"]);
         return undefined;
     }
@@ -355,14 +442,14 @@ function hookBlockRead(hooks, reject, drop) {
         const value = hooks[event];
         const at = ["hooks", event];
         if (!HOOK_EVENTS.includes(event)) {
-            if (hookGuardSignIn(value, at, Array.isArray(value) ? "matcherList" : "other") !== undefined)
+            if (hookGuardSignIn(value, at, hookIsArray(value) ? "matcherList" : "other") !== undefined)
                 reject("guard-under-unknown-event", at);
             else
                 drop("unknown-event", at);
             continue;
         }
         const guardEvent = HOOK_GUARD_EVENTS.includes(event);
-        if (!Array.isArray(value)) {
+        if (!hookIsArray(value)) {
             if ((guardEvent && value !== null) || hookGuardSignIn(value, at, "other") !== undefined)
                 reject("guard-event-not-array", at);
             else
@@ -392,6 +479,15 @@ function hookBlockRead(hooks, reject, drop) {
  * the hooks-classify test file (group ⑤) pins that the free names are exactly these.
  */
 export function classifyHooksConfig(settingsDoc) {
+    try {
+        return hookClassify(settingsDoc);
+    }
+    catch {
+        // reading the document threw (a trap, an accessor that throws): nothing in it can be shown free of guard signs ⇒ rejected at the root — ONE `try` for the whole classifier, none per node
+        return { outcome: "rejected", hooks: undefined, dropped: [], rejections: [{ code: "guard-outside-hooks", path: [] }] };
+    }
+}
+function hookClassify(settingsDoc) {
     const rejections = [];
     const dropped = [];
     const reject = (code, path, field) => {
@@ -401,7 +497,7 @@ export function classifyHooksConfig(settingsDoc) {
         dropped.push(field === undefined ? { code, path } : { code, path, field });
     };
     let hooks;
-    if (settingsDoc !== null && typeof settingsDoc === "object" && !Array.isArray(settingsDoc)) {
+    if (hookIsRecord(settingsDoc)) {
         const doc = settingsDoc;
         for (const key of Object.keys(doc)) {
             const value = doc[key];
@@ -412,7 +508,7 @@ export function classifyHooksConfig(settingsDoc) {
             // the document itself written as a matcher: its top-level `matcher` key is the evidence, reported at that key's place
             const sign = key === "matcher" && hookLooksLikeMatcher(doc)
                 ? [key]
-                : HOOK_GUARD_EVENTS.includes(key) && value !== null && value !== undefined && !(Array.isArray(value) && value.length === 0)
+                : HOOK_GUARD_EVENTS.includes(key) && value !== null && value !== undefined && !(hookIsArray(value) && value.length === 0)
                     ? [key]
                     : hookGuardSignIn(value, [key], "other");
             if (sign !== undefined)
@@ -450,7 +546,7 @@ function hooksFace(carry, strip, take) {
 }
 /** The carrier for one entry of type `type`: the value itself when it says that type, else an untyped object (⇒ the issue names `type`). */
 function entryOfType(value, type) {
-    return value !== null && typeof value === "object" && value.type === type ? value : {};
+    return isPlainJsonObject(value) && value.type === type ? value : {}; // 读不出 / 不是纯数据的值不当「自己说了这个 type」的载体:⇒ `{}`(issue 点名 `type`)
 }
 const entryFace = (type) => hooksFace((v) => ({ hooks: { Stop: [{ hooks: [entryOfType(v, type)] }] } }), 5, (h) => h.Stop[0].hooks[0]);
 export const CommandHookEntry = entryFace("command");

package/dist/http-hook-allowlists.d.ts

@@ -29,35 +29,52 @@ export declare const HttpHookAllowlistSettings: z.ZodObject<{
 }, z.core.$loose>;
 export type HttpHookAllowlistSettings = z.infer<typeof HttpHookAllowlistSettings>;
 /**
- * 一个设置层对两键的读数。键缺席 = 这一层不设限;`[]` = 这一层一个都不许。`source` = 这一层是哪个设置源(闭集 `SETTINGS_SOURCES`,原样回显进
- * `sources`);准入由判官按源经 `layerAdmission` 判,调用方不预先筛层、不给档。
+ * 一个设置层对两键的读数(读器交出的读数里的 `layer`)。键缺席 = 这一层不设限;`[]` = 这一层一个都不许。`source` = 这一层是哪个设置源(闭集 `SETTINGS_SOURCES`,原样回显进
+ * `sources`);准入由判官按源经 `layerAdmission` 判,调用方不预先筛层、不给档。读器交出的是寻常对象(不冻结)。
+ * **判官经读器读每一层**(与读器同一只读法,见 `httpHookUrlVerdict`):读器交出的层、调用方手造的寻常层、本 realm 的 `JSON.parse` 出来的层都按内容判,同一份内容同一个答案(另一个 realm 的数组按坏形,见 CHANGELOG 例外 ⑤)。读器交出的层里坏形名单已读成 `[]`(点名在读器的 `malformed`),所以同一份坏形设置直接交判官答 `malformed`、先过读器再交判官答 `empty` —— 坏形的告警看读器那一份读数。
  */
 export interface HttpHookAllowlistLayer {
     readonly source: SettingsSource;
     readonly allowedHttpHookUrls?: readonly string[];
     readonly httpHookAllowedEnvVars?: readonly string[];
 }
-/** 一层的读法结果:层读数 + 读成空名单的坏形键(调用方据此告警;读法本身不出句)。 */
+/**
+ * 一层的读法结果:层读数 + 读成空名单的坏形键(调用方据此告警;读法本身不出句)。由 {@link readHttpHookAllowlistLayer} 交出:普通对象、不冻结(与 v14.6.0 同形)。
+ * 读器对自己交出的 `layer` 再读,名单逐位同,`malformed` 只在第一次读出现(坏键第一次已读成 `[]`,再读是空名单);交判官与交它的副本同答。
+ */
 export interface HttpHookAllowlistLayerRead {
     readonly layer: HttpHookAllowlistLayer;
     readonly malformed: readonly HttpHookAllowlistKey[];
 }
 /**
- * 从一层的原始设置对象读出两键(唯一读法)。键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样;其余一切(非数组、含非串条目、`null`)
- * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象 ⇒ 两键都缺。
+ * 从一层的原始设置对象读出两键,过 `allowlistsOf`〔包内私有〕—— 与判官同一只读法:键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样的捕获副本;其余一切(非数组、含非串条目或洞、取值或读元素时抛、`null`)
+ * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象(`null` / 原始值 / 数组)⇒ 两键都缺。
+ * **是对象但不朴素**(类实例 / `Map` / 建在别的对象原型上的记录 / 函数 —— JSON 解析不出来,只能是嵌入方程序拼的)⇒ 同样 fail-closed:两键都读成 `[]` 并点名 `malformed`。
+ * 把它当「没有设置」读,等于把一层带名单的托管设置静默丢掉、方向放行(与本模块「坏形 = 一个都不许」的失败方向相反)。
+ * 名单键**只靠继承可见**(不是自有键)⇒ 同样 fail-closed:该键读成 `[]` 并点名 `malformed`(自有键盖过继承键;自有键值为 `undefined` 仍是「不设」)。
+ * 原型是带成员的 null 原型对象的对象(`Object.create(<null 原型的名单袋>)`)是一例:它按座位的判据读成朴素、按**自有**键读,名单键只在原型上 ⇒ 坏形。它只能由程序造出,JSON 解析不出来(座位头注 `./plain-json-object` 同写)。
  */
 export declare function readHttpHookAllowlistLayer(source: SettingsSource, settings: unknown): HttpHookAllowlistLayerRead;
-/** 拦下一只 http hook 的原因。`rule`:`empty` = 有一张准入名单是空的(那一层改对之前一只都不许);`url` = 没命中那几张名单里的任何模式。
- *  `sources` = 不放行它的那几张名单所在的层(入参序)。零 URL 回显 —— URL 调用方自己有,按受众给显示形。 */
+/** 拦下一只 http hook 的原因。`rule`(闭集,先到先得:`malformed` 先于 `empty` 先于 `url`):
+ *  `malformed` = 有一层判官读不出 —— ① 源读不出:`layers` 本身不是朴素数组 / 读不出 / 两份观测对不上,或某层的 `source` 缺席 / 只靠继承可见 / 读不出 / 两份不一致 / 不是串、层不是对象
+ *  ⇒ 那一层没有可信的源,不点名;② 源读得出、名单读不出(读器对同一份设置报 `malformed` 的那些形:不是朴素串数组 —— 另一个 realm 的数组、带框架挂件的数组、含非串条目或洞 ——、
+ *  读它或读它的元素时 getter 抛、两份观测不一致、名单键只靠继承可见、层对象不朴素)⇒ 点名那一层;
+ *  `empty` = 有一张准入名单真是空的 `[]`(那一层改对之前一只都不许;读器交出的层里坏形名单已是 `[]`,交判官也答 `empty` —— 坏形点名看读器的 `malformed`);
+ *  `url` = 没命中那几张名单里的任何模式。
+ *  `sources` = 不放行它的、读得出源的那几层(入参序)—— 所以 `rule: "malformed"` 时 `sources` 可以是空的(只有源读不出的层在拦)。零 URL 回显 —— URL 调用方自己有,按受众给显示形。 */
 export interface HttpHookUrlBlock {
     readonly list: "allowedHttpHookUrls";
-    readonly rule: "empty" | "url";
+    readonly rule: "malformed" | "empty" | "url";
     readonly sources: readonly SettingsSource[];
 }
 /**
  * 一只 http hook 的 URL 过不过名单:每一张准入的 `allowedHttpHookUrls` 都要有一条模式按放行出口({@link urlAllowPatternMatches})命中它。
- * 没有准入层写这张名单 ⇒ 不限(`undefined`)。`workspace` = 宿主对工作区信任的读数(读口抛或闭集外按 `declined` 交),与 `layerAdmission` 同一个入参。
+ * 没有准入层写这张名单 ⇒ 不限(`undefined`)。`layers` 的每一层经读器读({@link readHttpHookAllowlistLayer} 同一只读法;读不出源 ⇒ 坏形层,全拦、`rule: "malformed"`)。
+ * `workspace` = 宿主对工作区信任的读数(读口抛或闭集外按 `declined` 交),与 `layerAdmission` 同一个入参。
  */
 export declare function httpHookUrlVerdict(url: string, layers: readonly HttpHookAllowlistLayer[], workspace: WorkspaceTrustState): HttpHookUrlBlock | undefined;
-/** 一只 http hook 实际可插值进请求头的环境变量:它自己的 `allowedEnvVars` 与每一张准入的 `httpHookAllowedEnvVars` 取交(保持 hook 自己的序)。 */
+/**
+ * 一只 http hook 实际可插值进请求头的环境变量:它自己的 `allowedEnvVars` 与每一张准入的 `httpHookAllowedEnvVars` 取交(保持 hook 自己的序)。
+ * `layers` 同 {@link httpHookUrlVerdict}(坏形层 ⇒ 一个都不放);`hookVars` 只许普通的串数组({@link plainArrayOf};不是 ⇒ 当空,一个都不放)。
+ */
 export declare function httpHookEnvVarsAllowed(hookVars: readonly string[], layers: readonly HttpHookAllowlistLayer[], workspace: WorkspaceTrustState): string[];

package/dist/http-hook-allowlists.js

@@ -15,6 +15,8 @@
  * 判官出结构不出句:放行 ⇒ `undefined`;拦下 ⇒ {@link HttpHookUrlBlock}(哪张名单 / 为什么 / 出自哪几层),用户面那一句由各宿主按它铸。
  */
 import { z } from "zod";
+import { captureDenseArray, inspect, isStringEntry, readKey } from "./own-key-read.js";
+import { isJsonArray, isPlainJsonArray, jsonShapeOf } from "./plain-json-object.js";
 import { layerAdmission } from "./settings-sources.js";
 import { urlAllowPatternMatches } from "./url-pattern.js";
 /** 两键(闭集,声明序)。 */
@@ -29,45 +31,207 @@ export const HttpHookAllowlistSettings = z
     httpHookAllowedEnvVars: z.array(z.string()).optional(),
 })
     .passthrough();
+/** 坏形的那一份读数(名单按 `[]` 读、点名 malformed)。每次一份新数组。 */
+const malformedList = () => ({ list: [], malformed: true });
+const UNSET = { kind: "unset" };
+const BAD = { kind: "bad" };
 /**
- * 从一层的原始设置对象读出两键(唯一读法)。键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样;其余一切(非数组、含非串条目、`null`)
- * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象 ⇒ 两键都缺。
+ * 安全轴的数组(`layers` / `hookVars` / 两张名单)的描述符观测 D —— **只许朴素数组**,一条规则:座位的朴素数组判据({@link isPlainJsonArray}:是数组、原型恒等于本 realm 的 `Array.prototype`、
+ * `constructor` / `filter` / `flatMap` / `Symbol.iterator` 与本 realm 的内建恒等 —— 子类、假原型、`null` / 换过的原型、谎报原型或对这几只成员说谎的 Proxy、另一个 realm 的数组都不是);整容器读({@link denseArrayView},`wide` 归类)一次列自有键 ——
+ * 稠密(`length` 是安全非负整数、自有下标正好 `0 … length-1`),且**自有键只有下标与 `length`**:任何别的自有键(方法覆盖、`constructor`、任意串键、符号键 —— 含 `Symbol.species`)
+ * ⇒ 不是朴素数组,整个输入按坏形、不读元素(v14.6.0 的判官调过调用方数组自己的 `filter`,子类 / 自有方法 / species 构造器让它拦下或少放;本版一律拦,拦集不缩)。
+ * 元素值取自那一份描述符(访问器下标调它的 getter 一次),逐个过 `isEntry`(不过即停、后面的不读);交出一份定义语义造的副本。不是 / 读不出 ⇒ `undefined`。
+ */
+function plainArrayOf(v, isEntry) {
+    return isPlainJsonArray(v) ? captureDenseArray(v, "wide", isEntry, "refuse") : undefined; // 拷贝循环是内核那一份(与串数组读法同一只)
+}
+const isAny = (_entry) => true;
+/** 判官直接拿到的数组(`layers` / `hookVars`):描述符观测({@link plainArrayOf})与普通读({@link agreesByOrdinaryReading})两份一致才算读到;否则 `undefined`。设置里的名单不走这一只 —— 两键的描述符观测要先于任何普通读(见 {@link allowlistsOf})。 */
+function bothObservations(v, isEntry) {
+    const seen = plainArrayOf(v, isEntry);
+    return seen !== undefined && agreesByOrdinaryReading(v, seen) ? seen : undefined;
+}
+/**
+ * 观测 D(描述符通道,本包的读内核):名单键经 `readKey` 读一次 —— 缺席 / 自有 `undefined` ⇒ 不设;自有 ⇒ {@link plainArrayOf}(只许普通的串数组;不是 ⇒ 坏形);
+ * 只靠继承可见 / 读不出 ⇒ 坏形。
+ */
+function describedList(holder, key) {
+    const read = readKey(holder, key);
+    switch (read.presence) {
+        case "absent":
+            return UNSET;
+        case "inherited":
+        case "unreadable":
+            return BAD;
+        case "own": {
+            if (read.value === undefined)
+                return UNSET;
+            const list = plainArrayOf(read.value, isStringEntry);
+            return list === undefined ? BAD : { kind: "list", list };
+        }
+        default: {
+            const unhandled = read;
+            throw new Error(`describedList: unhandled presence ${String(unhandled.presence)}`);
+        }
+    }
+}
+/**
+ * 观测 G(普通读通道)与描述符那份 `seen` 是否一致:座位判数组、`length` 经 `[[Get]]` 等于 `seen.length`、逐下标「是不是自有」(`Object.hasOwn` —— 14.6.0 读器读名单的读法)、
+ * 「在不在」(`i in v`,HasProperty —— v14.6.0 判官对 `layers` / `hookVars` 的 `filter` 按它跳过下标)且 `[[Get]]` 的值与 `seen` 同一(`Object.is`)。
+ * 读量以 `seen` 的长度为界(长度不同即不一致,不逐位扫);读不出 ⇒ 不一致。名单、判官的 `layers` / `hookVars` 都用这一只。
+ */
+function agreesByOrdinaryReading(v, seen) {
+    const same = inspect(() => {
+        if (!isJsonArray(v) || v.length !== seen.length)
+            return false;
+        for (let i = 0; i < seen.length; i++)
+            if (!Object.hasOwn(v, i) || !(i in v) || !Object.is(v[i], seen[i]))
+                return false;
+        return true;
+    });
+    return same.ok && same.value;
+}
+/**
+ * 名单在一个对象上的**唯一读法**(读器读设置对象、判官读层对象,都调这一只 —— 两边对同一个对象永远同答):先问座位它是什么形(`jsonShapeOf`,一次)——
+ *  · 朴素对象 ⇒ **两份观测一致才算读到**:先对每个要的键做描述符观测 D({@link describedList}),再逐键做普通读 G({@link agreesByOrdinaryReading},v14.6.0 读器与判官普通读的合取)对拍 ——
+ *    两份都「不设」⇒ 不设;都是同一张串名单 ⇒ D 的捕获副本;其余一切(只一份读到、内容不同、任一份读不出 / 坏形、名单键只靠继承可见)⇒ `[]` + malformed(fail-closed:对无状态构造,拦集包含
+ *    「只看 G」的 14.6.0 与「只看 D」的读法各自的拦集,两份不一致也拦;普通对象上两份观测恒同,JSON 面零变化)。挡不住的(如实):有状态陷阱 —— 两次都答同一份假名单,
+ *    或第一次观测改了第二次观测的答案;G 是本模块读名单时唯一的 `[[Get]]`,只作对拍 —— 交出去的值取自 D;
+ *  · 是对象但不朴素(类实例 / `Map` / 建在别的对象原型上的记录 / 函数 —— JSON 解析不出来,只能是嵌入方程序拼的)或读形状就抛(已撤销的 Proxy)⇒ 要的键都读成 `[]` + malformed
+ *    (fail-closed:把它当「没有名单」读,等于把一层带名单的设置静默丢掉、方向放行);
+ *  · 不是对象(`null` / 原始值 / 数组)⇒ 都缺。
+ * 交出零原型的袋(只含读到的键)。
+ */
+function allowlistsOf(holder, keys) {
+    const out = Object.create(null); // 零原型:原型上被污染成只读的同名键不让赋值抛
+    const shape = jsonShapeOf(holder);
+    switch (shape) {
+        case "plain": {
+            // 安全轴的名单要**两份观测一致才算读到**:先对所有要的键做描述符观测 D(在任何普通读之前 —— 一个键的普通读改不动另一个键已经拿到的观测),再逐键做普通读 G 对拍
+            const described = keys.map((key) => describedList(holder, key));
+            keys.forEach((key, i) => {
+                const d = described[i];
+                if (d.kind === "bad") {
+                    out[key] = malformedList();
+                    return;
+                }
+                const got = inspect(() => holder[key]);
+                const agrees = got.ok && (d.kind === "unset" ? got.value === undefined : agreesByOrdinaryReading(got.value, d.list));
+                if (!agrees)
+                    out[key] = malformedList();
+                else if (d.kind === "list")
+                    out[key] = { list: d.list, malformed: false };
+            });
+            break;
+        }
+        case "non_plain_object":
+        case "uninspectable":
+            for (const key of keys)
+                out[key] = malformedList();
+            break;
+        case "array":
+        case "null":
+        case "primitive":
+            break;
+        default: {
+            const unhandled = shape;
+            throw new Error(`allowlistsOf: unhandled shape ${String(unhandled)}`);
+        }
+    }
+    return out;
+}
+/**
+ * 从一层的原始设置对象读出两键,过 `allowlistsOf`〔包内私有〕—— 与判官同一只读法:键缺席(或值为 `undefined`)⇒ 不设;字符串数组 ⇒ 原样的捕获副本;其余一切(非数组、含非串条目或洞、取值或读元素时抛、`null`)
+ * ⇒ **读成 `[]`**(CC 同向:坏形名单 = 一个都不许)并在 `malformed` 点名。整份设置不是对象(`null` / 原始值 / 数组)⇒ 两键都缺。
+ * **是对象但不朴素**(类实例 / `Map` / 建在别的对象原型上的记录 / 函数 —— JSON 解析不出来,只能是嵌入方程序拼的)⇒ 同样 fail-closed:两键都读成 `[]` 并点名 `malformed`。
+ * 把它当「没有设置」读,等于把一层带名单的托管设置静默丢掉、方向放行(与本模块「坏形 = 一个都不许」的失败方向相反)。
+ * 名单键**只靠继承可见**(不是自有键)⇒ 同样 fail-closed:该键读成 `[]` 并点名 `malformed`(自有键盖过继承键;自有键值为 `undefined` 仍是「不设」)。
+ * 原型是带成员的 null 原型对象的对象(`Object.create(<null 原型的名单袋>)`)是一例:它按座位的判据读成朴素、按**自有**键读,名单键只在原型上 ⇒ 坏形。它只能由程序造出,JSON 解析不出来(座位头注 `./plain-json-object` 同写)。
  */
 export function readHttpHookAllowlistLayer(source, settings) {
-    const bag = typeof settings === "object" && settings !== null && !Array.isArray(settings) ? settings : {};
-    const malformed = [];
-    const lists = {};
+    const read = allowlistsOf(settings, HTTP_HOOK_ALLOWLIST_KEYS);
+    // 累加器零原型:`{}` 继承 `Object.prototype`,原型上被污染成只读(只有 getter)的同名键会让赋值抛(读器该 fail-closed,不是抛)
+    const lists = Object.create(null);
     for (const key of HTTP_HOOK_ALLOWLIST_KEYS) {
-        if (!Object.hasOwn(bag, key) || bag[key] === undefined)
-            continue;
-        const v = bag[key];
-        if (Array.isArray(v) && v.every((x) => typeof x === "string"))
-            lists[key] = [...v];
-        else {
-            lists[key] = [];
-            malformed.push(key);
-        }
+        const captured = read[key];
+        if (captured !== undefined)
+            lists[key] = captured.list;
     }
+    // `malformed` 用 filter 造(定义语义)—— `push` 会命中 `Object.prototype` 上继承的数字键 setter、吞掉点名;返回形与 v14.6.0 同(普通对象、不冻结),字面量与 `...lists` 都是定义语义,污染下不抛
+    const malformed = HTTP_HOOK_ALLOWLIST_KEYS.filter((key) => read[key]?.malformed === true);
     return { layer: { source, ...lists }, malformed };
 }
-/** 进判决的那几层(入参序):`layerAdmission` 答 `admitted` 的层。每一层都问 —— 闭集外的源 / 工作区读数在这里响亮抛,哪怕那一层没写名单。 */
-function admittedLayers(layers, workspace) {
-    return layers.filter((l) => layerAdmission(l.source, workspace, "httpHookAllowlists") === "admitted");
+const MALFORMED_LAYER = { source: undefined, list: [], malformed: true };
+/**
+ * 一层的 `source`,与名单同一条双读一致律:层是对象(朴素与否都读)⇒ 自有描述符那份(`readKey`)与普通读那份(`[[Get]]`)是同一个值、且是串 ⇒ 那个词
+ * (闭集不在这里判:读得出的词交 `layerAdmission`,闭集外的词在那里响亮抛 —— 那是宿主代码写错了词,不是数据坏形);
+ * 其余一切(不是对象 / 读形状就抛、`source` 缺席 / 只靠继承可见 / 读不出、两份不一致、不是串)⇒ `undefined`(判官把这一层当坏形层,判决词 `malformed`)。
+ */
+function sourceOf(element) {
+    const shape = jsonShapeOf(element);
+    switch (shape) {
+        case "plain":
+        case "non_plain_object": {
+            const described = readKey(element, "source");
+            if (described.presence !== "own")
+                return undefined;
+            const got = inspect(() => element.source);
+            return got.ok && Object.is(got.value, described.value) && typeof described.value === "string" ? described.value : undefined;
+        }
+        case "array":
+        case "null":
+        case "primitive":
+        case "uninspectable":
+            return undefined;
+        default: {
+            const unhandled = shape;
+            throw new Error(`sourceOf: unhandled shape ${String(unhandled)}`);
+        }
+    }
+}
+/**
+ * 进判决的那几层(入参序)与它们对 `key` 那张名单的读数(`list` 缺 = 这一层不设)。**判官经读器读每一层**,与读器同一只读法,没有「是不是读器交出的」判:
+ * `layers` 数组见 {@link bothObservations}(不是朴素数组 / 读不出 / 两份观测对不上 ⇒ 整个当一张坏形层);每个元素先读源({@link sourceOf})——
+ * 读不出 ⇒ **坏形层**:名单按 `[]`,不问准入(它没有可信的源),进判决、全拦(判决词 `malformed`);
+ * 读得出 ⇒ 问 `layerAdmission`(闭集外的源 / 工作区读数在这里响亮抛 RangeError,哪怕那一层没写名单),准入的才进判决,名单与「读不出」= 读器读这个元素的读数({@link allowlistsOf},两键、双读一致律原样;读不出 ⇒ 判决词 `malformed`、点名这一层)。
+ * 于是读器交出的层、它的副本、手造的寻常层、本 realm 的 `JSON.parse` 出来的层同一份内容同一个答案(另一个 realm 的数组按坏形);读器对自己交出的 `layer` 再读,名单逐位同(`malformed` 只在第一次读出现)。
+ */
+function admittedLists(layers, workspace, key) {
+    const elements = bothObservations(layers, isAny);
+    if (elements === undefined)
+        return [MALFORMED_LAYER];
+    return elements.flatMap((element) => {
+        const source = sourceOf(element);
+        if (source === undefined)
+            return [MALFORMED_LAYER];
+        // 闭集外的词:`layerAdmission` 经源表那一只判官抛 RangeError(与 14.6.0 同句同类)—— 判官不另写闭集表
+        if (layerAdmission(source, workspace, "httpHookAllowlists") !== "admitted")
+            return [];
+        const captured = allowlistsOf(element, HTTP_HOOK_ALLOWLIST_KEYS)[key];
+        return [{ source: source, list: captured?.list, malformed: captured?.malformed === true }];
+    });
 }
 /**
  * 一只 http hook 的 URL 过不过名单:每一张准入的 `allowedHttpHookUrls` 都要有一条模式按放行出口({@link urlAllowPatternMatches})命中它。
- * 没有准入层写这张名单 ⇒ 不限(`undefined`)。`workspace` = 宿主对工作区信任的读数(读口抛或闭集外按 `declined` 交),与 `layerAdmission` 同一个入参。
+ * 没有准入层写这张名单 ⇒ 不限(`undefined`)。`layers` 的每一层经读器读({@link readHttpHookAllowlistLayer} 同一只读法;读不出源 ⇒ 坏形层,全拦、`rule: "malformed"`)。
+ * `workspace` = 宿主对工作区信任的读数(读口抛或闭集外按 `declined` 交),与 `layerAdmission` 同一个入参。
  */
 export function httpHookUrlVerdict(url, layers, workspace) {
-    const refusing = admittedLayers(layers, workspace).filter((l) => l.allowedHttpHookUrls !== undefined && !l.allowedHttpHookUrls.some((p) => urlAllowPatternMatches(url, p)));
+    const refusing = admittedLists(layers, workspace, "allowedHttpHookUrls").flatMap(({ source, list, malformed }) => list !== undefined && !list.some((p) => urlAllowPatternMatches(url, p)) ? [{ source, malformed, empty: list.length === 0 }] : []);
     if (refusing.length === 0)
         return undefined;
-    return { list: "allowedHttpHookUrls", rule: refusing.some((l) => l.allowedHttpHookUrls.length === 0) ? "empty" : "url", sources: refusing.map((l) => l.source) };
+    const sources = refusing.flatMap(({ source }) => (source === undefined ? [] : [source]));
+    const rule = refusing.some((r) => r.malformed) ? "malformed" : refusing.some((r) => r.empty) ? "empty" : "url";
+    return { list: "allowedHttpHookUrls", rule, sources };
 }
-/** 一只 http hook 实际可插值进请求头的环境变量:它自己的 `allowedEnvVars` 与每一张准入的 `httpHookAllowedEnvVars` 取交(保持 hook 自己的序)。 */
+/**
+ * 一只 http hook 实际可插值进请求头的环境变量:它自己的 `allowedEnvVars` 与每一张准入的 `httpHookAllowedEnvVars` 取交(保持 hook 自己的序)。
+ * `layers` 同 {@link httpHookUrlVerdict}(坏形层 ⇒ 一个都不放);`hookVars` 只许普通的串数组({@link plainArrayOf};不是 ⇒ 当空,一个都不放)。
+ */
 export function httpHookEnvVarsAllowed(hookVars, layers, workspace) {
-    const lists = admittedLayers(layers, workspace)
-        .filter((l) => l.httpHookAllowedEnvVars !== undefined)
-        .map((l) => l.httpHookAllowedEnvVars);
-    return hookVars.filter((v) => lists.every((list) => list.includes(v)));
+    const lists = admittedLists(layers, workspace, "httpHookAllowedEnvVars")
+        .map(({ list }) => list)
+        .filter((list) => list !== undefined);
+    const vars = bothObservations(hookVars, isStringEntry) ?? []; // 只许朴素的串数组,且两份观测一致才算读到;否则一个都不放
+    return vars.filter((v) => lists.every((list) => list.includes(v)));
 }

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from "./reader.js";
 export * from "./cross-domain.js";
 export * from "./remote-exec.js";
 export * from "./safety-merge-spec.js";
+export * from "./settings-units.js";
 export * from "./scheduler-store.js";
 export * from "./cross-session.js";
 export * from "./hooks.js";
@@ -28,6 +29,8 @@ export * from "./api/auth-bridge.js";
 export * from "./api/scopes.js";
 export * from "./api/pull-token.js";
 export * from "./api/feedback.js";
+export * from "./api/credentials.js";
+export * from "./sandbox-git.js";
 export * from "./web-admin-env.js";
 export * from "./web-admin-credential.js";
 export * from "./web-admin-session-url.js";