@sema-agent/settings-schema 12.3.0 → 13.0.1

package/dist/url-pattern.js

@@ -0,0 +1,239 @@
+/**
+ * URL 名单里一条模式对一个 URL 的**唯一判法**(13.0.0,U3 [10538] / S-1597)。管理员写的 URL 名单 —— http hook `allowedHttpHookUrls`
+ * ({@link ./http-hook-allowlists})、MCP `allowedMcpServers` / `deniedMcpServers` 的 `serverUrl` 条目({@link ./mcp-server-policy})——
+ * 都读这一只。纯函数,全局只用 `URL`,浏览器安全。
+ *
+ * 一条律,两只出口:**名单读不准的地方一律判向「拦」**。放行出口在含糊处不命中(命中面 ⊆ 上游),拒绝出口在含糊处命中(命中面 ⊇ 上游)。
+ *
+ * 组件判法(上游同形:CC 2.1.296 `g9`,cli296.js:249195;上游两张名单都调它):
+ *  - 模式恰为 `*` ⇒ 一切命中;URL 自身解析不了 ⇒ 不命中。
+ *  - 模式里的 `*` 换成占位记号后按 URL 解析;解析不了且端口位是 `*` ⇒ 端口位换 0 再解析,并记「端口不判」。
+ *  - 协议:相等,或模式协议整段是 `*`。主机名:两边去尾点、小写后按 glob 比。
+ *  - 端口:模式没写端口且主机名带 `*` ⇒ 不判;否则逐字相等(协议缺省端口两边都读成空)。
+ *  - 路径:模式路径是 `/` 或空、没有查询串、且模式原文不以 `/` 结尾 ⇒ 任意路径命中;否则「路径 + 查询串」按 glob 比。片段、用户信息不比。
+ *  - 模式解析不出 URL(或特殊协议的主机名里出现带通配的 punycode 标签)⇒ 回落成按 `/` 分段的 glob(段数相等、逐段比,`*` 跨不过 `/`)。
+ *  glob 只认 `*`(任意长度任意字符,含空),其余逐字、区分大小写。
+ *
+ * 放行出口比上游严(上游四洞;登本包 docs/CC-DIVERGENCE.md,与 cli 偏离登记 D-025 / D-026 / D-028 / D-029 同形):
+ *  - D-025 模式写了端口(哪怕是协议缺省端口,解析后读成空)⇒ 主机名带 `*` 也照判端口(上游把写明的 `:443` 当没写、放行任意端口)。
+ *    「写没写」由解析器自己答:同一串换成缺省端口不同的同族协议再解析,端口不再读成空 ⇒ 写了。
+ *  - D-026 目标协议不在「主机即连接目标」的四种(http / https / ws / wss)⇒ 模式必须写出那个协议,`*` 协议不通配它;`ws+unix:` 的连接目标
+ *    是路径里第一个 `:` 之前的套接字路径 ⇒ 套接字段只认逐字相等(带 `*` 即不放行任何套接字 —— 套接字路径到连接层还会被点段 / 反斜杠 /
+ *    长度截断改写,glob 判不住真实目标);`:` 之后的请求路径照 glob;没写路径的模式、套接字段为空或含 `..` 段的目标一律不放行。
+ *  - D-028 模式解析不出 URL 形(走分段回落)⇒ 不放行:回落把主机与端口拼成一段比,`*` 能跨过两者的边界。
+ *  - D-029 解析后主机名里出现不是占位来的 `*`(`%2a` / 全角 `＊` 被解析器解码、归一成的字面 `*`)⇒ 不放行:那是字面字符,不是通配。
+ * 拒绝出口比上游宽一处(D-027):另按整串 glob 再判一次,既有的无协议 / 跨组件写法不因按组件判而失效。
+ *
+ * 占位记号(与上游 / cli 不同的一处实现):上游用每进程随机串;本包要纯、要确定 ⇒ 按输入选一个记号 —— 它在模式与目标的任何解析读法里
+ * (原文 / 百分号解码 / IDNA 近似映射)都不出现,放进模式后也只在放进去的那几处出现(不与相邻字面拼出第二份)。
+ */
+/** 解析规则特殊、可能带缺省端口的协议(上游 `ojo`)。 */
+const SPECIAL_SCHEMES = new Set(["http:", "https:", "ws:", "wss:", "ftp:", "file:"]);
+/** 放行出口里 `*` 协议能通配的目标协议:这四种的连接目标就是 URL 的主机与端口。 */
+const HOST_ROUTED_SCHEMES = new Set(["http:", "https:", "ws:", "wss:"]);
+/** 有缺省端口的特殊协议 → 解析规则相同、缺省端口不同的同族协议(判「缺省端口是不是写出来的」用)。 */
+const OTHER_DEFAULT_PORT_SCHEME = { "http:": "https", "https:": "http", "ws:": "wss", "wss:": "ws", "ftp:": "http" };
+/** 连接目标是路径里第一个 `:` 之前那一段(套接字路径)的协议。 */
+const SOCKET_PATH_SCHEME = "ws+unix:";
+function parseUrl(s) {
+    try {
+        return new URL(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+function occurrences(haystack, needle) {
+    return haystack.split(needle).length - 1;
+}
+/**
+ * 一段文本在 URL 解析器眼里可能成为的样子:先过解析器自己的输入预处理({@link asParserSees}:去首尾 C0 与空格、删掉所有 TAB / LF / CR ——
+ * 不先做这一步,`zzwild<TAB>card0qq` 会在解析后拼回记号,codex r1 [high]),再取原文与百分号解码两读,各按主机名的 IDNA 映射近似
+ * (去默认可忽略码位、NFKC、小写)。
+ */
+function parserReadings(s) {
+    const fold = (x) => x.replace(/\p{Default_Ignorable_Code_Point}/gu, "").normalize("NFKC").toLowerCase().normalize("NFKC");
+    const seen = asParserSees(s);
+    const decoded = seen.replace(/(?:%[0-9a-f]{2})+/gi, (run) => {
+        try {
+            return decodeURIComponent(run);
+        }
+        catch {
+            return run;
+        }
+    });
+    return [fold(seen), fold(decoded)];
+}
+/**
+ * 选一个占位记号 `zz<stem><i>qq`:`avoid`(模式原文与目标 URL)的任何读法里都不出现,`build(token)` 造出的串在每一种读法里恰好出现
+ * `inserted` 次(只有自己放进去的那几处)。`avoid` 的读法只算一次、一遍扫出所有已被占用的序号,再取最小的空号 —— 工作量与输入长度成
+ * 线性(逐个候选重扫整段 `avoid` 会让塞满记号原文的目标 URL 逼出平方级工作,codex r1 [medium])。记号首尾不同(`zz…qq`)⇒ 不与自己重叠,
+ * 按切分数出现次数是准的,两处出现也不可能互相交叠。纯、确定。
+ */
+function freeToken(stem, avoid, build) {
+    const taken = new Set();
+    const shape = new RegExp(`zz${stem}(\\d+)qq`, "g");
+    for (const reading of parserReadings(avoid))
+        for (const m of reading.matchAll(shape))
+            taken.add(m[1]);
+    for (let i = 0;; i++) {
+        if (taken.has(String(i)))
+            continue;
+        const token = `zz${stem}${i}qq`;
+        const { built, inserted } = build(token);
+        if (parserReadings(built).every((r) => occurrences(r, token) === inserted))
+            return { token, built };
+        taken.add(String(i));
+    }
+}
+/** URL 解析器的输入预处理:去首尾 C0 控制符与空格(码位 ≤ U+0020)、删掉串里所有 TAB / LF / CR。去首尾按码位从两端扫(线性);
+ *  不用 `[\0-\x20]+$` 这类锚尾正则 —— 它会从串中间每一段空白的每个位置重试,长段空白上是平方级(13.0.0 codex 轮 [medium])。 */
+function asParserSees(s) {
+    let start = 0;
+    let end = s.length;
+    while (start < end && s.charCodeAt(start) <= 0x20)
+        start++;
+    while (end > start && s.charCodeAt(end - 1) <= 0x20)
+        end--;
+    return s.slice(start, end).replace(/[\t\n\r]/g, "");
+}
+/** 解析后端口读成空的模式,端口是不是写出来的缺省端口:换成缺省端口不同的同族协议再解析一次,端口不再为空 ⇒ 写了。 */
+function defaultPortWritten(marked, pat) {
+    if (pat.port !== "")
+        return false;
+    const other = OTHER_DEFAULT_PORT_SCHEME[pat.protocol];
+    if (other === undefined)
+        return false;
+    const seen = asParserSees(marked);
+    const colon = seen.indexOf(":");
+    if (colon === -1)
+        return false;
+    const alt = parseUrl(other + seen.slice(colon));
+    return alt !== undefined && alt.port !== "";
+}
+/** 模式写出了目标协议(按解析器看到的串,大小写不计)。 */
+function namesScheme(pattern, protocol) {
+    return asParserSees(pattern).toLowerCase().startsWith(protocol);
+}
+/** 路径里第一个 `:` 之前那一段(套接字协议的连接目标)。 */
+function socketPart(path) {
+    const i = path.indexOf(":");
+    return i === -1 ? path : path.slice(0, i);
+}
+/** 整串 glob:`*` = 任意长度任意字符;没有 `*` ⇒ 逐字相等。 */
+function globMatches(pattern, value) {
+    const parts = pattern.split("*");
+    const head = parts[0] ?? "";
+    if (parts.length === 1)
+        return head === value;
+    const tail = parts[parts.length - 1] ?? "";
+    const end = value.length - tail.length;
+    if (end < head.length || !value.startsWith(head) || !value.endsWith(tail))
+        return false;
+    let at = head.length;
+    for (const mid of parts.slice(1, -1)) {
+        if (mid === "")
+            continue;
+        const found = value.indexOf(mid, at);
+        if (found === -1 || found + mid.length > end)
+            return false;
+        at = found + mid.length;
+    }
+    return true;
+}
+function nextSeparator(s, separators, from) {
+    let i = from;
+    while (i < s.length && !separators.includes(s.charAt(i)))
+        i++;
+    return i;
+}
+/** 按分隔符逐段 glob:分隔符逐位相同、段数相等、每段 glob 命中(`*` 跨不过分隔符)。 */
+function segmentedGlobMatches(pattern, value, separators) {
+    let p = 0;
+    let v = 0;
+    for (;;) {
+        const pe = nextSeparator(pattern, separators, p);
+        const ve = nextSeparator(value, separators, v);
+        if (pattern.charAt(pe) !== value.charAt(ve) || !globMatches(pattern.slice(p, pe), value.slice(v, ve)))
+            return false;
+        if (pe === pattern.length)
+            return true;
+        p = pe + 1;
+        v = ve + 1;
+    }
+}
+/** 组件判法(见文件头);`allow` 多四处收紧(D-025 / D-026 / D-028 / D-029),`upstream` 与上游逐支同形。 */
+function componentMatches(url, pattern, reading) {
+    if (pattern === "*")
+        return true;
+    const target = parseUrl(url);
+    if (target === undefined)
+        return false;
+    const strict = reading === "allow";
+    if (strict && !HOST_ROUTED_SCHEMES.has(target.protocol) && !namesScheme(pattern, target.protocol))
+        return false;
+    const socketTarget = strict && target.protocol === SOCKET_PATH_SCHEME;
+    if (socketTarget) {
+        const socket = socketPart(target.pathname + target.search);
+        if (socket === "" || socket.split("/").includes(".."))
+            return false;
+    }
+    const { token: WILDCARD, built: starred } = freeToken("wildcard", `${pattern}\n${url}`, (t) => ({ built: pattern.replaceAll("*", t), inserted: occurrences(pattern, "*") }));
+    // 以 `xn--` 开头且带通配的标签前缀一个护符,免得解析器把它当 punycode 解码失败;比之前剥掉(上游 `j9t` / `BKe`)。
+    const { token: SHIELD, built: marked } = freeToken("punycode", `${starred}\n${url}`, (t) => {
+        let inserted = 0;
+        const built = starred.replace(/[a-z0-9-]+/gi, (run) => {
+            if (!/^xn--/i.test(run) || !run.includes(WILDCARD))
+                return run;
+            inserted++;
+            return t + run;
+        });
+        return { built, inserted };
+    });
+    const unshield = (s) => s.replaceAll(SHIELD, "");
+    let portAny = false;
+    let pat = parseUrl(marked);
+    if (pat === undefined) {
+        const zeroPort = marked.replace(new RegExp(`:${WILDCARD}(?=[/?#]|$)`), ":0");
+        if (zeroPort !== marked) {
+            pat = parseUrl(zeroPort);
+            portAny = pat !== undefined;
+        }
+    }
+    // 兜底:解析结果里记号出现得比放进去的还多 ⇒ 有一处是解析器从字面拼出来的,不是通配 —— 按「解析不出」处理(放行出口不放,拒绝出口回落)。
+    if (pat !== undefined && (occurrences(pat.href, WILDCARD) > occurrences(pattern, "*") || occurrences(pat.href, SHIELD) > occurrences(marked, SHIELD)))
+        pat = undefined;
+    if (pat === undefined || (SPECIAL_SCHEMES.has(pat.protocol) && pat.hostname.split(".").some((l) => l.startsWith("xn--") && l.includes(WILDCARD)))) {
+        return !strict && segmentedGlobMatches(pattern, `${target.protocol}//${target.host}${target.pathname}${target.search}`, "/");
+    }
+    if (pat.protocol !== `${WILDCARD}:` && pat.protocol !== target.protocol)
+        return false;
+    if (strict && unshield(pat.hostname).includes("*"))
+        return false;
+    const host = target.hostname.replace(/\.$/, "").toLowerCase();
+    const hostPattern = unshield(pat.hostname).replace(/\.$/, "").toLowerCase().replaceAll(WILDCARD, "*");
+    if (!globMatches(hostPattern, host))
+        return false;
+    if (pat.port === "" && pat.hostname.includes(WILDCARD) && !(strict && defaultPortWritten(marked, pat)))
+        portAny = true;
+    if (!portAny && pat.port !== target.port)
+        return false;
+    if ((pat.pathname === "/" || pat.pathname === "") && pat.search === "" && !marked.endsWith("/"))
+        return !socketTarget;
+    const pathPattern = unshield(pat.pathname + pat.search).replaceAll(WILDCARD, "*");
+    const targetPath = target.pathname + target.search;
+    if (!globMatches(pathPattern, targetPath))
+        return false;
+    if (!socketTarget)
+        return true;
+    const socketPattern = socketPart(pathPattern);
+    return !socketPattern.includes("*") && socketPattern === socketPart(targetPath);
+}
+/** 放行名单:`url` 是否被模式 `pattern` 放行(判法见文件头;命中面 ⊆ 上游)。 */
+export function urlAllowPatternMatches(url, pattern) {
+    return componentMatches(url, pattern, "allow");
+}
+/** 拒绝名单:`url` 是否被模式 `pattern` 拦下(上游组件判法,或整串 glob;命中面 ⊇ 上游)。 */
+export function urlDenyPatternMatches(url, pattern) {
+    return componentMatches(url, pattern, "upstream") || globMatches(pattern, url);
+}