@logictan/dsh-config-manager 0.1.60

package/lib/utils/hashing.d.ts

@@ -0,0 +1,17 @@
+export declare function sha256Hex(data: Uint8Array | string): string;
+export declare function hashFile(filePath: string): Promise<string>;
+/** 生成一组 ZIP 相对路径 → SHA-256 的校验表（路径必须为 ZIP 内正斜杠相对路径） */
+export declare function buildChecksums(entries: {
+    name: string;
+    data: Uint8Array;
+}[]): Record<string, string>;
+export interface ChecksumVerifyResult {
+    ok: boolean;
+    mismatches: string[];
+    missing: string[];
+}
+/**
+ * 校验：checksums 表内每个相对路径必须在 entries 中存在且 SHA-256 一致。
+ * entries 中多余的文件（如 manifest.json / checksums.json 自身）不参与校验。
+ */
+export declare function verifyChecksums(entries: ReadonlyMap<string, Uint8Array>, checksums: Record<string, string>): ChecksumVerifyResult;

package/lib/utils/hashing.js

@@ -0,0 +1,41 @@
+/**
+ * SHA-256 完整性工具（integrity/checksums.json 的生成与校验）。
+ * m4 的 security/integrity.ts 可在此之上强化（本模块已实现规范 §18 全部语义）。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+export function sha256Hex(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+export async function hashFile(filePath) {
+    const data = await fs.readFile(filePath);
+    return sha256Hex(data);
+}
+/** 生成一组 ZIP 相对路径 → SHA-256 的校验表（路径必须为 ZIP 内正斜杠相对路径） */
+export function buildChecksums(entries) {
+    const checksums = {};
+    for (const e of entries) {
+        checksums[e.name] = sha256Hex(e.data);
+    }
+    return checksums;
+}
+/**
+ * 校验：checksums 表内每个相对路径必须在 entries 中存在且 SHA-256 一致。
+ * entries 中多余的文件（如 manifest.json / checksums.json 自身）不参与校验。
+ */
+export function verifyChecksums(entries, checksums) {
+    const mismatches = [];
+    const missing = [];
+    for (const [relPath, expected] of Object.entries(checksums)) {
+        const data = entries.get(relPath);
+        if (data === undefined) {
+            missing.push(relPath);
+            continue;
+        }
+        if (sha256Hex(data) !== expected) {
+            mismatches.push(relPath);
+        }
+    }
+    return { ok: mismatches.length === 0 && missing.length === 0, mismatches, missing };
+}
+//# sourceMappingURL=hashing.js.map

package/lib/utils/json.d.ts

@@ -0,0 +1,24 @@
+/**
+ * JSON 深度保护：解析/序列化/克隆带嵌套深度上限（防 JSON 深度攻击，规范 §19.5）。
+ * 解析分两段：JSON.parse 可能因引擎栈限制抛 RangeError（捕获并归一），
+ * 再对结果做显式栈 walk 检查深度（避免 walk 自身递归爆栈）。
+ */
+export declare const DEFAULT_MAX_JSON_DEPTH = 64;
+export declare const DEFAULT_MAX_JSON_BYTES: number;
+export declare class JsonDepthError extends Error {
+    constructor(message?: string);
+}
+/** 测量对象/数组的嵌套深度（迭代式显式栈，不会递归爆栈；二进制视为叶子） */
+export declare function measureDepth(value: unknown): number;
+/** 深度保护解析：超限抛 JsonDepthError，非法 JSON 抛 SyntaxError */
+export declare function parseJsonSafe(text: string, opts?: {
+    maxDepth?: number;
+    maxBytes?: number;
+}): unknown;
+/** 深度保护序列化：先测深度再 stringify（默认不缩进） */
+export declare function stringifyJsonSafe(value: unknown, opts?: {
+    maxDepth?: number;
+    space?: number;
+}): string;
+/** 深度保护深拷贝（迭代式，安全） */
+export declare function deepClone<T>(value: T, maxDepth?: number): T;

package/lib/utils/json.js

@@ -0,0 +1,76 @@
+/**
+ * JSON 深度保护：解析/序列化/克隆带嵌套深度上限（防 JSON 深度攻击，规范 §19.5）。
+ * 解析分两段：JSON.parse 可能因引擎栈限制抛 RangeError（捕获并归一），
+ * 再对结果做显式栈 walk 检查深度（避免 walk 自身递归爆栈）。
+ */
+export const DEFAULT_MAX_JSON_DEPTH = 64;
+export const DEFAULT_MAX_JSON_BYTES = 64 * 1024 * 1024;
+export class JsonDepthError extends Error {
+    constructor(message = `JSON 嵌套深度超过上限 ${DEFAULT_MAX_JSON_DEPTH}`) {
+        super(message);
+        this.name = 'JsonDepthError';
+    }
+}
+/** 测量对象/数组的嵌套深度（迭代式显式栈，不会递归爆栈；二进制视为叶子） */
+export function measureDepth(value) {
+    let max = 0;
+    // 栈元素：[value, depth]
+    const stack = [[value, 1]];
+    while (stack.length > 0) {
+        const [current, depth] = stack.pop();
+        if (depth > max)
+            max = depth;
+        if (current !== null && typeof current === 'object' && !(current instanceof Uint8Array)) {
+            const next = depth + 1;
+            if (Array.isArray(current)) {
+                for (const item of current)
+                    stack.push([item, next]);
+            }
+            else {
+                for (const key of Object.keys(current)) {
+                    stack.push([current[key], next]);
+                }
+            }
+        }
+    }
+    return max;
+}
+/** 深度保护解析：超限抛 JsonDepthError，非法 JSON 抛 SyntaxError */
+export function parseJsonSafe(text, opts = {}) {
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_JSON_BYTES;
+    if (text.length > maxBytes) {
+        throw new JsonDepthError(`JSON 体积超过上限 ${maxBytes} 字节`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        // 引擎栈限制导致的深层嵌套也会以 RangeError 出现 → 归一为 JsonDepthError
+        if (err instanceof RangeError)
+            throw new JsonDepthError(`JSON 解析失败（可能是嵌套过深）: ${String(err.message)}`);
+        throw err;
+    }
+    const depth = measureDepth(parsed);
+    if (depth > maxDepth) {
+        throw new JsonDepthError(`JSON 嵌套深度 ${depth} 超过上限 ${maxDepth}`);
+    }
+    return parsed;
+}
+/** 深度保护序列化：先测深度再 stringify（默认不缩进） */
+export function stringifyJsonSafe(value, opts = {}) {
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+    const depth = measureDepth(value);
+    if (depth > maxDepth)
+        throw new JsonDepthError(`JSON 嵌套深度 ${depth} 超过上限 ${maxDepth}`);
+    return JSON.stringify(value, null, opts.space);
+}
+/** 深度保护深拷贝（迭代式，安全） */
+export function deepClone(value, maxDepth = DEFAULT_MAX_JSON_DEPTH) {
+    const depth = measureDepth(value);
+    if (depth > maxDepth)
+        throw new JsonDepthError();
+    return JSON.parse(JSON.stringify(value));
+}
+//# sourceMappingURL=json.js.map

package/lib/utils/logger.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 结构化日志（规范 §24）：LEVEL / 消息 / 可选元数据，带 redact 钩子。
+ * Secret 值永不入日志：sink 前对 msg 做文本级掩码、对 meta 做字段名级掩码。
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** 敏感字段名黑名单（大小写不敏感；命中即掩码值，规范 §6 清单） */
+export declare const SENSITIVE_FIELD_BLACKLIST: string[];
+/** 字段名是否命中敏感黑名单（大小写不敏感，子串匹配） */
+export declare function isSensitiveField(field: string): boolean;
+/** 对象级掩码：字段名命中黑名单 → 值替换（返回新对象，不改原对象） */
+export declare function redactValue(value: unknown, blacklist?: string[]): unknown;
+/** 文本级掩码：JSON 片段 `"field": "value"`、`field=value`、`field: value` 形态 */
+export declare function redact(text: string, blacklist?: string[]): string;
+export interface LogMeta {
+    [key: string]: unknown;
+}
+export interface LogSink {
+    (level: LogLevel, message: string, meta?: LogMeta): void;
+}
+export interface Logger {
+    level: LogLevel;
+    debug(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    error(message: string, meta?: LogMeta): void;
+}
+export interface LoggerOptions {
+    level?: LogLevel;
+    /** 输出目标；缺省写 console（单行 JSON）。测试可注入内存 sink。 */
+    sink?: LogSink;
+    /** 额外敏感字段黑名单 */
+    extraBlacklist?: string[];
+    /** 是否带时间戳前缀 */
+    timestamp?: boolean;
+}
+/** 创建结构化日志器（默认 console JSON 行，全部输出过 redact） */
+export declare function createLogger(opts?: LoggerOptions): Logger;
+/** 静默日志器（测试用） */
+export declare function nullLogger(): Logger;

package/lib/utils/logger.js

@@ -0,0 +1,82 @@
+/** 敏感字段名黑名单（大小写不敏感；命中即掩码值，规范 §6 清单） */
+export const SENSITIVE_FIELD_BLACKLIST = [
+    'password', 'passwd', 'token', 'accesstoken', 'refreshtoken', 'apikey',
+    'secret', 'credential', 'authorization', 'cookie', 'privatekey', 'clientsecret',
+    'sessionkey', 'authtoken', 'bearer',
+];
+const REDACTED = '***REDACTED***';
+/** 字段名是否命中敏感黑名单（大小写不敏感，子串匹配） */
+export function isSensitiveField(field) {
+    const lower = field.toLowerCase().replace(/[^a-z0-9]/g, '');
+    return SENSITIVE_FIELD_BLACKLIST.some((f) => lower.includes(f));
+}
+/** 对象级掩码：字段名命中黑名单 → 值替换（返回新对象，不改原对象） */
+export function redactValue(value, blacklist = SENSITIVE_FIELD_BLACKLIST) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, blacklist));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        const lower = k.toLowerCase();
+        const hit = blacklist.some((f) => lower.includes(f));
+        out[k] = hit ? REDACTED : redactValue(v, blacklist);
+    }
+    return out;
+}
+/** 文本级掩码：JSON 片段 `"field": "value"`、`field=value`、`field: value` 形态 */
+export function redact(text, blacklist = SENSITIVE_FIELD_BLACKLIST) {
+    let out = text;
+    for (const field of blacklist) {
+        // "field": "anything"
+        out = out.replace(new RegExp(`("${field}"\\s*:\\s*")[^"]*(")`, 'gi'), `$1${REDACTED}$2`);
+        // field=value / field: value（不含 JSON 引号形态）
+        out = out.replace(new RegExp(`(\\b${field}\\s*=\\s*)[^\\s,;]+`, 'gi'), `$1${REDACTED}`);
+        out = out.replace(new RegExp(`(\\b${field}\\s*:\\s*)[^\\s,;}]+`, 'gi'), `$1${REDACTED}`);
+    }
+    return out;
+}
+const LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+/** 创建结构化日志器（默认 console JSON 行，全部输出过 redact） */
+export function createLogger(opts = {}) {
+    const level = opts.level ?? 'info';
+    const blacklist = [...SENSITIVE_FIELD_BLACKLIST, ...(opts.extraBlacklist ?? [])];
+    const sink = opts.sink ?? ((lvl, message, meta) => {
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            level: lvl,
+            msg: redact(message, blacklist),
+            ...(meta ? { meta: redactValue(meta, blacklist) } : {}),
+        });
+        // eslint-disable-next-line no-console
+        (lvl === 'error' ? console.error : lvl === 'warn' ? console.warn : console.log)(line);
+    });
+    const emit = (lvl, message, meta) => {
+        if (LEVEL_ORDER[lvl] < LEVEL_ORDER[level])
+            return;
+        try {
+            sink(lvl, message, meta);
+        }
+        catch {
+            // 日志器自身永不抛错
+        }
+    };
+    return {
+        level,
+        debug: (m, meta) => emit('debug', m, meta),
+        info: (m, meta) => emit('info', m, meta),
+        warn: (m, meta) => emit('warn', m, meta),
+        error: (m, meta) => emit('error', m, meta),
+    };
+}
+/** 静默日志器（测试用） */
+export function nullLogger() {
+    return {
+        level: 'error',
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/lib/utils/paths.d.ts

@@ -0,0 +1,42 @@
+import type { PathMapping } from '../core/types.ts';
+/** 归一化内部表示：统一 `/` 分隔、去尾部斜杠（空串保持） */
+export declare function normalizePath(p: string): string;
+/** 转当前平台原生路径 */
+export declare function toNativePath(p: string): string;
+/** 跨平台绝对路径识别（POSIX `/x` 与 Windows `C:\x`、UNC `\\server\share`） */
+export declare function isAbsolutePath(p: string): boolean;
+/** 路径是否为 home 目录（~ 或用户主目录开头） */
+export declare function isHomePath(p: string, homeDir: string): boolean;
+/** 目标平台与当前平台是否一致 */
+export declare function isSamePlatform(a: string, b: string): boolean;
+/** ZIP 条目名安全检查（Zip Slip / 绝对路径 / 盘符 / NUL，规范 §19.1-2）。
+ * 规则与 node:path 解耦：纯分段校验，跨平台无歧义。 */
+export declare function isPathSafe(entryName: string): boolean;
+/** 候选目录是否位于父目录之内（含等于父目录） */
+export declare function isSameOrChild(p: string, parent: string): boolean;
+/**
+ * 归一化并折叠 `.` / `..` 路径段（Reviewer B P0 修复）。
+ * 宿主 fs 经 `resolve(join(homeDir, rel))` 会折叠 `..`，因此「看似不在保留命名空间、实际经 `..` 落到保留区」
+ * 的路径（如 `dsh-config-manager/../dsh-config-manager/snapshots/...`）必须在此折叠后再判，否则 F23 被绕过。
+ * 纯字符串、跨平台（只用 `/`）语义与 node:path normalize 一致；`..` 超根时按根截断（不越到 home 外）。
+ */
+export declare function normalizePathCollapsed(p: string): string;
+/** 判断相对 homeDir 的路径是否落在内部 control-plane namespace（F23 投毒防护）。
+ *  大小写不敏感（Windows 文件系统大小写不敏感，防 `DSh-Config-Manager/...` 绕过）；
+ *  先折叠 `..`/`.` 段（宿主 fs 会折叠，此处必须同样折叠以免被路径穿越绕过）。 */
+export declare function isReservedInternalRel(relPath: string): boolean;
+/**
+ * 前缀批量映射（规范 §12）：把对象内所有字符串值中匹配 oldPrefix 的路径
+ * 替换为 newPrefix（路径感知：必须落在段边界）。返回新对象（不改原对象）。
+ */
+export declare function applyPrefixMappings(value: unknown, mappings: PathMapping[]): unknown;
+/** 对对象内所有字符串叶节点做变换（迭代式，保留非字符串原样；二进制 Uint8Array 视为叶子） */
+export declare function mapStrings(value: unknown, fn: (s: string) => string): unknown;
+/**
+ * 收集对象中所有绝对路径叶值（供 analyzer 做跨设备路径检测）。
+ * 返回 (value, jsonPath) 对；jsonPath 形如 "workspaces[0].path"。
+ */
+export declare function collectAbsolutePaths(value: unknown, prefix?: string): {
+    value: string;
+    path: string;
+}[];

package/lib/utils/paths.js

@@ -0,0 +1,189 @@
+/**
+ * 路径处理唯一出口（node:path 不直接散落业务代码）：
+ * 规范化、平台判定、绝对路径识别、前缀批量映射、ZIP 条目名安全校验。
+ */
+import path from 'node:path';
+/** 归一化内部表示：统一 `/` 分隔、去尾部斜杠（空串保持） */
+export function normalizePath(p) {
+    if (p === '')
+        return '';
+    const norm = p.replaceAll('\\', '/');
+    return norm.length > 1 ? norm.replace(/\/+$/, '') : norm;
+}
+/** 转当前平台原生路径 */
+export function toNativePath(p) {
+    const norm = normalizePath(p);
+    if (process.platform === 'win32')
+        return norm.replaceAll('/', '\\');
+    return norm;
+}
+/** 跨平台绝对路径识别（POSIX `/x` 与 Windows `C:\x`、UNC `\\server\share`） */
+export function isAbsolutePath(p) {
+    if (p === '')
+        return false;
+    if (p.startsWith('/'))
+        return true;
+    if (/^[a-zA-Z]:[\\/]/.test(p))
+        return true; // 盘符
+    if (p.startsWith('\\\\') || p.startsWith('//'))
+        return true; // UNC
+    return false;
+}
+/** 路径是否为 home 目录（~ 或用户主目录开头） */
+export function isHomePath(p, homeDir) {
+    const norm = normalizePath(p);
+    const home = normalizePath(homeDir);
+    return norm === '~' || norm === home || norm.startsWith(home + '/') || norm.startsWith('~/');
+}
+/** 目标平台与当前平台是否一致 */
+export function isSamePlatform(a, b) {
+    return a === b;
+}
+/** ZIP 条目名安全检查（Zip Slip / 绝对路径 / 盘符 / NUL，规范 §19.1-2）。
+ * 规则与 node:path 解耦：纯分段校验，跨平台无歧义。 */
+export function isPathSafe(entryName) {
+    if (entryName === '')
+        return false;
+    if (entryName.includes('\0'))
+        return false;
+    if (entryName.startsWith('/') || entryName.startsWith('\\'))
+        return false; // 绝对路径
+    if (/^[a-zA-Z]:[\\/]/.test(entryName))
+        return false; // 盘符
+    if (/^\\\\/.test(entryName))
+        return false; // UNC
+    const segments = entryName.split(/[\\/]+/);
+    if (segments.some((s) => s === '..'))
+        return false; // 目录穿越
+    return true;
+}
+/** 候选目录是否位于父目录之内（含等于父目录） */
+export function isSameOrChild(p, parent) {
+    const rel = path.relative(parent, p);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/**
+ * 内部 control-plane namespace（F23 修复）：不可信 import（pluginFiles/self/file adapters）
+ * 不得把普通 config/file item 映射到这些 recovery storage 目录。
+ * 相对 homeDir 的路径（正斜杠归一）命中任一前缀 → 拒绝。
+ */
+const RESERVED_INTERNAL_PREFIXES = [
+    'dsh-config-manager/snapshots/',
+    'dsh-config-manager/transactions/',
+    'dsh-config-manager/locks/',
+    'dsh-config-manager/safe-mode',
+    'dsh-config-manager/recovery-history/',
+    'dsh-config-manager/environment-fingerprint.token',
+    // Phase 6：迁移历史审计目录（统一历史引擎；防 F23 投毒链——不可信导入不得映射到该目录）。
+    'dsh-config-manager/migration-history/',
+    // 注意：不得整段保留 dsh-config-manager/sync/ —— self 分区合法持有 sync/*.json 白名单配置
+    //（sync-config / sync-selection / ui-prefs / backup-schedule），会误伤。
+    'dsh-config-manager/sync/snapshots/',
+    'dsh-config-manager/sync/work/',
+];
+/**
+ * 归一化并折叠 `.` / `..` 路径段（Reviewer B P0 修复）。
+ * 宿主 fs 经 `resolve(join(homeDir, rel))` 会折叠 `..`，因此「看似不在保留命名空间、实际经 `..` 落到保留区」
+ * 的路径（如 `dsh-config-manager/../dsh-config-manager/snapshots/...`）必须在此折叠后再判，否则 F23 被绕过。
+ * 纯字符串、跨平台（只用 `/`）语义与 node:path normalize 一致；`..` 超根时按根截断（不越到 home 外）。
+ */
+export function normalizePathCollapsed(p) {
+    const norm = normalizePath(p);
+    if (norm === '')
+        return '';
+    if (norm === '.')
+        return '';
+    const out = [];
+    for (const seg of norm.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..') {
+            if (out.length > 0)
+                out.pop();
+            continue; // 超根 `..` 直接丢弃（home 相对路径不可能越出 homeDir）
+        }
+        out.push(seg);
+    }
+    return out.join('/');
+}
+/** 判断相对 homeDir 的路径是否落在内部 control-plane namespace（F23 投毒防护）。
+ *  大小写不敏感（Windows 文件系统大小写不敏感，防 `DSh-Config-Manager/...` 绕过）；
+ *  先折叠 `..`/`.` 段（宿主 fs 会折叠，此处必须同样折叠以免被路径穿越绕过）。 */
+export function isReservedInternalRel(relPath) {
+    const norm = normalizePathCollapsed(relPath).toLowerCase();
+    if (norm === '')
+        return false;
+    for (const prefix of RESERVED_INTERNAL_PREFIXES) {
+        if (norm === prefix || norm.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * 前缀批量映射（规范 §12）：把对象内所有字符串值中匹配 oldPrefix 的路径
+ * 替换为 newPrefix（路径感知：必须落在段边界）。返回新对象（不改原对象）。
+ */
+export function applyPrefixMappings(value, mappings) {
+    if (mappings.length === 0)
+        return value;
+    return mapStrings(value, (s) => {
+        let out = s;
+        for (const m of mappings) {
+            const oldNorm = normalizePath(m.oldPrefix);
+            if (oldNorm === '')
+                continue;
+            const candidate = normalizePath(out);
+            if (candidate === oldNorm) {
+                out = normalizePath(m.newPrefix);
+                continue;
+            }
+            if (candidate.startsWith(oldNorm + '/')) {
+                const rest = candidate.slice(oldNorm.length); // 含前导 /
+                out = normalizePath(normalizePath(m.newPrefix) + rest);
+            }
+        }
+        return out;
+    });
+}
+/** 对对象内所有字符串叶节点做变换（迭代式，保留非字符串原样；二进制 Uint8Array 视为叶子） */
+export function mapStrings(value, fn) {
+    if (typeof value === 'string')
+        return fn(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (value instanceof Uint8Array)
+        return value; // 二进制不按字段展开
+    if (Array.isArray(value))
+        return value.map((v) => mapStrings(v, fn));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = mapStrings(v, fn);
+    }
+    return out;
+}
+/**
+ * 收集对象中所有绝对路径叶值（供 analyzer 做跨设备路径检测）。
+ * 返回 (value, jsonPath) 对；jsonPath 形如 "workspaces[0].path"。
+ */
+export function collectAbsolutePaths(value, prefix = '') {
+    const hits = [];
+    const visit = (v, p) => {
+        if (typeof v === 'string') {
+            if (isAbsolutePath(v))
+                hits.push({ value: v, path: p });
+            return;
+        }
+        if (v === null || typeof v !== 'object')
+            return;
+        if (Array.isArray(v)) {
+            v.forEach((item, i) => visit(item, `${p}[${i}]`));
+            return;
+        }
+        for (const [k, val] of Object.entries(v)) {
+            visit(val, p === '' ? k : `${p}.${k}`);
+        }
+    };
+    visit(value, prefix);
+    return hits;
+}
+//# sourceMappingURL=paths.js.map

package/lib/utils/proxy.d.ts

@@ -0,0 +1,69 @@
+/** 代理相关环境变量（大小写兼容后的归一形态） */
+export interface ProxyEnv {
+    /** http 目标使用的代理（`HTTP_PROXY` / `http_proxy`） */
+    httpProxy: string | null;
+    /** https 目标使用的代理（`HTTPS_PROXY` / `https_proxy`） */
+    httpsProxy: string | null;
+    /** 直连白名单（`NO_PROXY` / `no_proxy`） */
+    noProxy: string | null;
+}
+/** 读代理环境变量（纯函数，便于测试注​入任意 env） */
+export declare function readProxyEnv(env?: Record<string, string | undefined>): ProxyEnv;
+/** 是否配置了任何代理（用于启动日志与「是否需要走代理链路」的判定） */
+export declare function isProxyConfigured(env?: ProxyEnv): boolean;
+/**
+ * 目标是否命中 `NO_PROXY`。
+ * 支持：`*`（全直连）、精确主机、`.example.com` 与 `example.com`（含子域）、可选 `:port` 限定。
+ */
+export declare function matchesNoProxy(host: string, port: string, noProxy: string | null): boolean;
+/**
+ * 该目标应使用的代理 URL；无需代理（未配置 / 命中 NO_PROXY / 非法）→ null。
+ *
+ * 选择规则（对齐 undici `EnvHttpProxyAgent` 的直觉语义）：
+ *  - `https:` 目标 → `HTTPS_PROXY`，缺省回退 `HTTP_PROXY`；
+ *  - `http:` 目标 → `HTTP_PROXY`，缺省回退 `HTTPS_PROXY`。
+ */
+export declare function proxyUrlFor(target: string | URL, env?: ProxyEnv): string | null;
+/** 代理的**脱敏**描述（供日志/报错提示；凭据一律剥离，绝不外泄） */
+export declare function describeProxy(proxyUrl: string): string;
+/** 单次请求的输入 */
+export interface RawRequestOptions {
+    method?: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: Buffer | string | undefined;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    env?: ProxyEnv;
+}
+/** 单次请求的响应（始终缓冲完整响应体；插件用到的响应体都是小 JSON/文本） */
+export interface RawResponse {
+    status: number;
+    statusText: string;
+    headers: Headers;
+    body: Buffer;
+}
+/**
+ * 发起一次 HTTP/1.1 请求（自动：直连 / 经代理 absolute-form / 经代理 CONNECT 隧道）。
+ * 不跟随重定向（跟随策略由调用方决定：WebDAV 保方法语义，fetch 按浏览器语义）。
+ */
+export declare function requestOnce(options: RawRequestOptions): Promise<RawResponse>;
+/**
+ * 代理感知的 fetch 兼容实现（仅插件自身使用；替代 `globalThis.fetch` 的默认值）。
+ *
+ * 与浏览器 fetch 的关键语义对齐：自动跟随 301/302/303/307/308（上限 5 跳）；303 且非 GET/HEAD
+ * 降级为 GET 并丢弃请求体；**跨源跳转剥离 `authorization`**（token 不转发给第三方域名）；
+ * 无响应体状态（204/304 等）不构造 body。
+ */
+export declare function createProxyAwareFetch(env?: ProxyEnv): typeof fetch;
+/**
+ * 默认出站 fetcher：**未配置代理时原样返回全局 `fetch`**（保持既有行为零变化）；
+ * 配置了代理才切到代理感知实现。
+ */
+export declare function defaultFetcher(env?: ProxyEnv): typeof fetch;
+/** 启动日志用：当前生效的代理描述（已脱敏），未启用 → null */
+export declare function activeProxySummary(env?: ProxyEnv): {
+    http: string | null;
+    https: string | null;
+    noProxyEntries: number;
+} | null;