@deepexi/datasense-connector 0.0.0-stage → 3.1.0

package/src/testing/mock-external-system.ts

@@ -0,0 +1,249 @@
+/**
+ * 模拟外部系统：连接器操作单元测试里替换 `ctx.http` 底层的 fetch（交给 `createLocalGateway({ fetch })`）。
+ * 它不是出站网关：主机求交、凭证句柄替换、超时都仍由网关做，这里只按路由应答并记下每次请求。
+ *
+ * - 路由键 `'<METHOD> <path>'`，path 段可写 `:名字` 占位（如 `GET /orders/:id`），处理函数拿到 `params`；
+ * - `script(route, steps)` 给该路由排一串结果，每次请求消费一步，排完后回到处理函数：
+ *   `'ok'` 交给处理函数；`'reject'` 回 422 `{ code: 'REJECTED', message }`；`'timeout'` 一直不应答，
+ *   直到请求的 `signal` 中止（网关按请求超时中止，连接器得到 `TRANSIENT_ERROR`；执行器超时时为 `CANCELED`）；
+ *   `{ slowMs }` 等这么久再交给处理函数；
+ * - 没有匹配的路由回 404 `{ code: 'NOT_FOUND' }`，请求同样记下；
+ * - `calls(route?)` 返回记下的请求（头名小写，JSON 正文已解析），`reset()` 清空记录与排好的结果。
+ */
+
+export interface MockRequest {
+  method: string;
+  path: string;
+  /** 路由里 `:名字` 占位对应的路径段（已解码）。 */
+  params: Record<string, string>;
+  query: Record<string, string>;
+  /** 头名小写。 */
+  headers: Record<string, string>;
+  /** JSON 正文解析后的值；不是 JSON 时为文本；没有正文时为 null。 */
+  body: unknown;
+}
+
+export interface MockResponse {
+  /** 缺省 200。 */
+  status?: number;
+  headers?: Record<string, string>;
+  /** 字符串原样作为正文，其余按 JSON 序列化；省略则没有正文。 */
+  body?: unknown;
+}
+
+export type MockRouteHandler = (request: MockRequest) => MockResponse | Response | Promise<MockResponse | Response>;
+
+export type MockStep = 'ok' | 'reject' | 'timeout' | { slowMs: number };
+
+export interface MockCall {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+export interface MockExternalSystem {
+  /** 交给 `createLocalGateway({ fetch })` 或其他测试用的执行器 / 网关替身。 */
+  fetch: typeof fetch;
+  /** 给路由排一串结果，追加在尚未消费的结果之后。 */
+  script(route: string, steps: MockStep[]): void;
+  /** 记下的请求；给了路由键时只返回匹配该路由的请求。 */
+  calls(route?: string): MockCall[];
+  /** 清空请求记录与排好的结果（路由不变）。 */
+  reset(): void;
+}
+
+interface CompiledRoute {
+  key: string;
+  method: string;
+  segments: string[];
+  handler: MockRouteHandler;
+}
+
+const ROUTE_KEY = /^([A-Za-z]+) (\/\S*)$/;
+
+/** 拆出路由键的方法（大写）与路径；不合法时返回 null。 */
+function parseKey(key: string): { method: string; path: string } | null {
+  const match = ROUTE_KEY.exec(key.trim());
+  const method = match?.[1];
+  const path = match?.[2];
+  return method !== undefined && path !== undefined ? { method: method.toUpperCase(), path } : null;
+}
+
+function splitPath(path: string): string[] {
+  return path.split('/').filter((segment) => segment !== '');
+}
+
+function compileRoute(key: string, handler: MockRouteHandler): CompiledRoute {
+  const parsed = parseKey(key);
+  if (!parsed) throw new TypeError(`mock route "${key}" must look like "<METHOD> /path"`);
+  if (typeof handler !== 'function') throw new TypeError(`mock route "${key}" needs a handler function`);
+  return { key: `${parsed.method} ${parsed.path}`, method: parsed.method, segments: splitPath(parsed.path), handler };
+}
+
+function normalizeKey(key: string): string {
+  const parsed = parseKey(key);
+  return parsed ? `${parsed.method} ${parsed.path}` : key.trim();
+}
+
+function matchRoute(route: CompiledRoute, method: string, segments: string[]): Record<string, string> | null {
+  if (route.method !== method || route.segments.length !== segments.length) return null;
+  const params: Record<string, string> = {};
+  for (const [index, expected] of route.segments.entries()) {
+    const actual = segments[index] ?? '';
+    if (expected.startsWith(':')) {
+      try {
+        params[expected.slice(1)] = decodeURIComponent(actual);
+      } catch {
+        params[expected.slice(1)] = actual;
+      }
+    } else if (expected !== actual) {
+      return null;
+    }
+  }
+  return params;
+}
+
+function validateSteps(route: string, steps: unknown): MockStep[] {
+  if (!Array.isArray(steps)) throw new TypeError(`script("${route}") needs an array of steps`);
+  return steps.map((step, index) => {
+    if (step === 'ok' || step === 'reject' || step === 'timeout') return step;
+    if (typeof step === 'object' && step !== null && typeof (step as { slowMs?: unknown }).slowMs === 'number'
+      && Number.isFinite((step as { slowMs: number }).slowMs) && (step as { slowMs: number }).slowMs >= 0) {
+      return { slowMs: (step as { slowMs: number }).slowMs };
+    }
+    throw new TypeError(`script("${route}") step ${index} must be 'ok', 'reject', 'timeout' or { slowMs: number }`);
+  });
+}
+
+function bodyText(body: unknown): string | null {
+  if (body === undefined || body === null) return null;
+  if (typeof body === 'string') return body;
+  if (body instanceof Uint8Array) return new TextDecoder().decode(body);
+  if (body instanceof ArrayBuffer) return new TextDecoder().decode(new Uint8Array(body));
+  if (body instanceof URLSearchParams) return body.toString();
+  return String(body);
+}
+
+function parseBody(text: string | null): unknown {
+  if (text === null || text === '') return null;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function toResponse(result: MockResponse | Response): Response {
+  if (result instanceof Response) return result;
+  const headers = new Headers(result.headers ?? {});
+  let body: string | null = null;
+  if (result.body !== undefined) {
+    if (typeof result.body === 'string') {
+      body = result.body;
+    } else {
+      body = JSON.stringify(result.body);
+      if (!headers.has('content-type')) headers.set('content-type', 'application/json');
+    }
+  }
+  return new Response(body, { status: result.status ?? 200, headers });
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+function abortError(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+}
+
+/** 等 `ms` 毫秒；`signal` 中止时立即拒绝。`ms` 为 Infinity 时只等中止。 */
+function wait(ms: number, signal: AbortSignal | null | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal));
+      return;
+    }
+    const timer = Number.isFinite(ms) ? setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms) : null;
+    const onAbort = (): void => {
+      if (timer !== null) clearTimeout(timer);
+      reject(signal ? abortError(signal) : new DOMException('The operation was aborted', 'AbortError'));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+export function createMockExternalSystem(routes: Record<string, MockRouteHandler>): MockExternalSystem {
+  const compiled = Object.entries(routes).map(([key, handler]) => compileRoute(key, handler));
+  const byKey = new Map(compiled.map((route) => [route.key, route]));
+  const scripts = new Map<string, MockStep[]>();
+  const recorded: Array<{ route: string | null; call: MockCall }> = [];
+
+  const routeOf = (key: string): CompiledRoute => {
+    const route = byKey.get(normalizeKey(key));
+    if (!route) throw new TypeError(`mock route "${key}" is not defined; defined routes: ${[...byKey.keys()].join(', ') || '(none)'}`);
+    return route;
+  };
+
+  const mockFetch = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const request = input instanceof Request ? input : null;
+    const url = new URL(request ? request.url : String(input));
+    const method = (init?.method ?? request?.method ?? 'GET').toUpperCase();
+    const headers: Record<string, string> = {};
+    new Headers(init?.headers ?? request?.headers ?? {}).forEach((value, name) => {
+      headers[name.toLowerCase()] = value;
+    });
+    const text = init?.body !== undefined ? bodyText(init.body) : request ? await request.text() : null;
+    const body = parseBody(text);
+    const signal = init?.signal ?? request?.signal ?? null;
+    const segments = splitPath(url.pathname);
+
+    let matched: { route: CompiledRoute; params: Record<string, string> } | null = null;
+    for (const route of compiled) {
+      const params = matchRoute(route, method, segments);
+      if (params) {
+        matched = { route, params };
+        break;
+      }
+    }
+    recorded.push({ route: matched?.route.key ?? null, call: { method, path: url.pathname, headers: { ...headers }, body } });
+    if (!matched) return jsonResponse(404, { code: 'NOT_FOUND', message: `no mock route for ${method} ${url.pathname}` });
+
+    const step = scripts.get(matched.route.key)?.shift() ?? 'ok';
+    if (step === 'reject') return jsonResponse(422, { code: 'REJECTED', message: 'rejected by the mock external system' });
+    if (step === 'timeout') {
+      await wait(Number.POSITIVE_INFINITY, signal);
+    } else if (typeof step === 'object') {
+      await wait(step.slowMs, signal);
+    }
+    const query: Record<string, string> = {};
+    url.searchParams.forEach((value, name) => {
+      query[name] = value;
+    });
+    const result = await matched.route.handler({ method, path: url.pathname, params: matched.params, query, headers: { ...headers }, body });
+    return toResponse(result);
+  };
+
+  return {
+    fetch: mockFetch as typeof fetch,
+    script(route, steps) {
+      const key = routeOf(route).key;
+      const queue = scripts.get(key) ?? [];
+      queue.push(...validateSteps(route, steps));
+      scripts.set(key, queue);
+    },
+    calls(route) {
+      const key = route === undefined ? null : routeOf(route).key;
+      return recorded
+        .filter((entry) => key === null || entry.route === key)
+        .map(({ call }) => ({ ...call, headers: { ...call.headers } }));
+    },
+    reset() {
+      recorded.length = 0;
+      scripts.clear();
+    },
+  };
+}

package/src/testing/pinned-http.ts

@@ -0,0 +1,144 @@
+/**
+ * 本地网关走真实网络时的单跳请求：用 `node:http` / `node:https` 发出，连接地址固定为网关检查过的解析结果（`lookup` 只回这些地址），
+ * 关掉「检查时解析一次、fetch 再解析一次」之间的 DNS 重绑定窗口。主机名照常用于 `Host` 头、TLS 的 SNI 与证书校验。
+ *
+ * 行为与 `fetch(..., { redirect: 'manual' })` 对齐：不跟随重定向；按 `content-encoding`（gzip / deflate / br）解压正文；
+ * 返回缓冲好的 `Response`。正文（解压前后）超过 `maxBytes` 时抛 `PinnedBodyTooLargeError`；`signal` 中止时销毁连接。
+ */
+import { request as httpRequest, type IncomingMessage } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import type { LookupAddress } from 'node:dns';
+import { brotliDecompressSync, gunzipSync, inflateRawSync, inflateSync } from 'node:zlib';
+
+export class PinnedBodyTooLargeError extends Error {
+  constructor() {
+    super('response body too large');
+    this.name = 'PinnedBodyTooLargeError';
+  }
+}
+
+/** 这些状态码的 `Response` 不能带正文。 */
+const NULL_BODY_STATUSES: ReadonlySet<number> = new Set([101, 103, 204, 205, 304]);
+
+type LookupCallback = (error: NodeJS.ErrnoException | null, address: string | LookupAddress[], family?: number) => void;
+
+function pinnedLookup(addresses: readonly LookupAddress[]) {
+  return (_hostname: string, options: unknown, callback: LookupCallback): void => {
+    const all = typeof options === 'object' && options !== null && (options as { all?: unknown }).all === true;
+    const first = addresses[0];
+    if (!first) {
+      callback(Object.assign(new Error('no address to connect to'), { code: 'ENOTFOUND' }), []);
+      return;
+    }
+    if (all) callback(null, [...addresses]);
+    else callback(null, first.address, first.family);
+  };
+}
+
+function decompress(bytes: Buffer, encoding: string, maxBytes: number): Buffer {
+  const options = { maxOutputLength: maxBytes + 1 };
+  try {
+    switch (encoding) {
+      case 'gzip':
+      case 'x-gzip':
+        return gunzipSync(bytes, options);
+      case 'deflate':
+        try {
+          return inflateSync(bytes, options);
+        } catch (error) {
+          if (error instanceof RangeError) throw error;
+          return inflateRawSync(bytes, options);
+        }
+      case 'br':
+        return brotliDecompressSync(bytes, options);
+      default:
+        return bytes;
+    }
+  } catch (error) {
+    if (error instanceof RangeError || (error as { code?: unknown }).code === 'ERR_BUFFER_TOO_LARGE') throw new PinnedBodyTooLargeError();
+    throw error;
+  }
+}
+
+function toHeaders(response: IncomingMessage): Headers {
+  const headers = new Headers();
+  const raw = response.rawHeaders;
+  for (let index = 0; index + 1 < raw.length; index += 2) {
+    try {
+      headers.append(raw[index] ?? '', raw[index + 1] ?? '');
+    } catch {
+      // 非法的头名或头值：丢弃这一个
+    }
+  }
+  return headers;
+}
+
+export interface PinnedRequestInput {
+  url: URL;
+  method: string;
+  headers: Record<string, string>;
+  body: Uint8Array | null;
+  addresses: readonly LookupAddress[];
+  signal: AbortSignal;
+  maxBytes: number;
+}
+
+export function pinnedRequest(input: PinnedRequestInput): Promise<Response> {
+  const { url, method, signal, maxBytes } = input;
+  const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+  const body = input.body !== null && method !== 'GET' && method !== 'HEAD' ? Buffer.from(input.body) : null;
+  const headers: Record<string, string> = { ...input.headers };
+  if (body !== null) headers['content-length'] = String(body.byteLength);
+
+  return new Promise<Response>((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new Error('aborted'));
+      return;
+    }
+    let settled = false;
+    const fail = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener('abort', onAbort);
+      reject(error);
+    };
+    const req = send(url, { method, headers, lookup: pinnedLookup(input.addresses) as never }, (response) => {
+      const chunks: Buffer[] = [];
+      let size = 0;
+      response.on('data', (chunk: Buffer) => {
+        size += chunk.byteLength;
+        if (size > maxBytes) {
+          req.destroy();
+          fail(new PinnedBodyTooLargeError());
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on('error', (error) => fail(error));
+      response.on('end', () => {
+        if (settled) return;
+        try {
+          const status = response.statusCode ?? 0;
+          const encoding = (response.headers['content-encoding'] ?? '').trim().toLowerCase();
+          const bytes = method === 'HEAD' ? Buffer.alloc(0) : decompress(Buffer.concat(chunks), encoding, maxBytes);
+          const responseHeaders = toHeaders(response);
+          // DOM lib 下 `Buffer<ArrayBufferLike>` 不算 BodyInit（CLI 带 DOM lib 编译本文件），运行时照收。
+          const body = NULL_BODY_STATUSES.has(status) || bytes.byteLength === 0 ? null : bytes as unknown as NonNullable<ConstructorParameters<typeof Response>[0]>;
+          const result = new Response(body, { status, headers: responseHeaders });
+          settled = true;
+          signal.removeEventListener('abort', onAbort);
+          resolve(result);
+        } catch (error) {
+          fail(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+    });
+    const onAbort = (): void => {
+      req.destroy(new Error('aborted'));
+      fail(new Error('aborted'));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    req.on('error', (error) => fail(error));
+    req.end(body ?? undefined);
+  });
+}

package/src/testing/recorder.ts

@@ -0,0 +1,140 @@
+/**
+ * 夹具录制：挂在本地模拟网关的 `onExchange` 上，把未遮蔽的原始往来（`LocalExchange`）按遮蔽规则写成 `FixtureExchange`。
+ *
+ * 遮蔽规则（与 shared `connector-redaction.ts` 同一套，实现见 `redaction.ts`）：
+ * - 长度 ≥ 4 的 Secret 明文 → `***`（URL、头、body、db 的 SQL / 参数 / 行、crypto 的 key / data、错误文案）；
+ * - `CREDENTIAL_HEADER_NAMES` 六个请求 / 响应头的值 → `***`；
+ * - 含句柄 `ontos:secret:` 的 query 值 → `***`；请求 body 与头里的句柄原样保留（网关替换前的形态）。
+ *
+ * db：一次查询的分页（`db.query` + 若干 `db.next`）合成一条往来，`rows` 为全部行；中途失败时记下已取到的行与错误。
+ * crypto 调用失败时不录（回放时 `hash` 本地计算，`hmac` / `sign` 报 `FIXTURE_EXCHANGE_MISMATCH`）。
+ */
+import type { CryptoRequest, DbNextResponse, DbQueryResponse, EgressHttpRequest, EgressHttpResponse } from '../runtime/protocol';
+import { canonicalRequestUrl, type FixtureExchange } from './fixtures';
+import type { LocalExchange } from './gateway';
+import { redactHeaders, redactSecretValues, redactUrl, secretRedactionTexts } from './redaction';
+
+type DbExchange = Extract<FixtureExchange, { kind: 'db' }>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 深拷贝成 JSON 值，字符串逐个遮蔽明文。 */
+function redactDeep(value: unknown, secrets: readonly string[]): unknown {
+  const plain: unknown = value === undefined ? null : JSON.parse(JSON.stringify(value));
+  const walk = (item: unknown): unknown => {
+    if (typeof item === 'string') return redactSecretValues(item, secrets);
+    if (Array.isArray(item)) return item.map(walk);
+    if (isRecord(item)) return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, walk(child)]));
+    return item;
+  };
+  return walk(plain);
+}
+
+export interface FixtureRecorder {
+  onExchange(exchange: LocalExchange): void;
+  /** 至今录下的往来（按 `seq` 升序，深拷贝）。 */
+  exchanges(): FixtureExchange[];
+}
+
+/**
+ * `secrets`：配置里的 Secret 字段 → 明文；`extraSecrets`：其余要遮蔽的明文（如本地 `db` 的密码）。
+ * 遮蔽时每个明文连同它的 URL 编码与表单编码写法一起替换。
+ */
+export function createRecorder(options: { secrets: Record<string, string>; extraSecrets?: readonly string[] }): FixtureRecorder {
+  const secrets = secretRedactionTexts([...Object.values(options.secrets), ...(options.extraSecrets ?? [])]
+    .filter((value): value is string => typeof value === 'string'));
+  const redact = (text: string): string => redactSecretValues(text, secrets);
+  const recorded: FixtureExchange[] = [];
+  const openCursors = new Map<string, DbExchange>();
+  let seq = 0;
+
+  const errorOf = (exchange: LocalExchange): { code: string; message: string } | null =>
+    exchange.error ? { code: exchange.error.code, message: redact(exchange.error.message) } : null;
+
+  const recordHttp = (exchange: LocalExchange): void => {
+    const request = exchange.request as Partial<EgressHttpRequest>;
+    if (!isRecord(request) || typeof request.url !== 'string' || typeof request.method !== 'string') return;
+    const bodyEncoding = request.bodyEncoding === 'base64' ? 'base64' : 'utf8';
+    const body = typeof request.body === 'string' ? (bodyEncoding === 'utf8' ? redact(request.body) : request.body) : null;
+    const response = exchange.response as EgressHttpResponse | null;
+    seq += 1;
+    recorded.push({
+      seq,
+      kind: 'http',
+      request: {
+        method: request.method,
+        url: redactUrl(canonicalRequestUrl(request.url, request.query), secrets),
+        headers: redactHeaders(isRecord(request.headers) ? request.headers as Record<string, string> : {}, secrets),
+        body,
+        bodyEncoding,
+      },
+      response: exchange.error || !isRecord(response)
+        ? null
+        : {
+          status: response.status,
+          headers: redactHeaders(response.headers ?? {}, secrets),
+          body: response.bodyEncoding === 'utf8' ? redact(response.body) : response.body,
+          bodyEncoding: response.bodyEncoding,
+        },
+      error: errorOf(exchange) ?? (isRecord(response) ? null : { code: 'HOST_CALL_FAILED', message: 'no response was recorded' }),
+    });
+  };
+
+  const recordDb = (exchange: LocalExchange): void => {
+    const request = exchange.request;
+    if (!isRecord(request)) return;
+    if (typeof request.sql === 'string') {
+      const response = exchange.response as DbQueryResponse | null;
+      seq += 1;
+      const entry: DbExchange = {
+        seq,
+        kind: 'db',
+        sql: redact(request.sql),
+        params: redactDeep(Array.isArray(request.params) ? request.params : [], secrets) as unknown[],
+        fields: isRecord(response) && Array.isArray(response.fields) ? response.fields.map((field) => ({ name: field.name, dataTypeId: field.dataTypeId })) : [],
+        rows: isRecord(response) && Array.isArray(response.rows) ? redactDeep(response.rows, secrets) as Array<Record<string, unknown>> : [],
+        error: errorOf(exchange),
+      };
+      recorded.push(entry);
+      if (isRecord(response) && typeof response.cursorId === 'string' && response.done === false) openCursors.set(response.cursorId, entry);
+      return;
+    }
+    if (typeof request.cursorId === 'string') {
+      const entry = openCursors.get(request.cursorId);
+      if (!entry) return;
+      const response = exchange.response as DbNextResponse | null;
+      if (isRecord(response) && Array.isArray(response.rows)) entry.rows.push(...(redactDeep(response.rows, secrets) as Array<Record<string, unknown>>));
+      const error = errorOf(exchange);
+      if (error) entry.error = error;
+      if (error || !isRecord(response) || response.done !== false) openCursors.delete(request.cursorId);
+    }
+  };
+
+  const recordCrypto = (exchange: LocalExchange): void => {
+    if (exchange.error || !isRecord(exchange.request) || !isRecord(exchange.response) || typeof exchange.response.value !== 'string') return;
+    const request = redactDeep(exchange.request, secrets) as CryptoRequest;
+    seq += 1;
+    recorded.push({ seq, kind: 'crypto', request, value: redact(exchange.response.value) });
+  };
+
+  return {
+    onExchange(exchange) {
+      switch (exchange.kind) {
+        case 'http':
+          recordHttp(exchange);
+          return;
+        case 'db':
+          recordDb(exchange);
+          return;
+        case 'crypto':
+          recordCrypto(exchange);
+          return;
+      }
+    },
+    exchanges() {
+      return JSON.parse(JSON.stringify(recorded)) as FixtureExchange[];
+    },
+  };
+}

package/src/testing/redaction.ts

@@ -0,0 +1,94 @@
+/**
+ * 遮蔽规则（录制夹具、本地 `read` 的请求行、本地运行日志共用），与 shared `utils/connector-redaction.ts` 同一套规则；
+ * SDK 不依赖 shared，这里另写一份，`test/testing/redaction.test.ts` 对照两份实现的结果。
+ *
+ * - 长度 ≥ 4 的 Secret 明文 → `***`（长的先替换，避免短值截断长值）；
+ * - `CREDENTIAL_HEADER_NAMES` 里的请求 / 响应头（小写比较）整值 → `***`；
+ * - 含句柄 `ontos:secret:` 的 query 值 → `***`；请求里的句柄本身原样保留（网关替换前的形态）。
+ */
+
+/** 凭证类请求 / 响应头（小写）；与 shared 的 `CREDENTIAL_HEADER_NAMES` 同值。 */
+export const CREDENTIAL_HEADER_NAMES: readonly string[] = Object.freeze([
+  'authorization',
+  'proxy-authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'x-auth-token',
+]);
+
+/** 遮蔽的最短明文长度：更短的值误伤面太大，不替换。 */
+export const REDACT_MIN_LENGTH = 4;
+
+export const REDACTED = '***';
+
+const CREDENTIAL_HEADER_SET: ReadonlySet<string> = new Set(CREDENTIAL_HEADER_NAMES);
+
+/** 句柄的两种写法：原文 `ontos:secret:` 与 URL 编码后的 `ontos%3Asecret%3A`。 */
+const HANDLE_PATTERN = /ontos(?::|%3[Aa])secret(?::|%3[Aa])/;
+
+/** 文本里是否含凭证句柄（原文或 URL 编码写法）。 */
+export function containsSecretHandle(text: string): boolean {
+  return HANDLE_PATTERN.test(text);
+}
+
+/** 把文本里长度 ≥ 4 的 Secret 明文替换为 `***`（先替换较长的）。 */
+export function redactSecretValues(text: string, secrets: readonly string[]): string {
+  const candidates = [...new Set(secrets.filter((secret) => typeof secret === 'string' && secret.length >= REDACT_MIN_LENGTH))]
+    .sort((a, b) => b.length - a.length);
+  let result = text;
+  for (const secret of candidates) {
+    if (result.includes(secret)) result = result.split(secret).join(REDACTED);
+  }
+  return result;
+}
+
+/**
+ * 遮蔽用的明文清单：每个 Secret 加上它进 URL 后的两种写法——`encodeURIComponent` 与表单编码（`URLSearchParams`，空格写成 `+`）。
+ * 句柄替换进 URL 时用的是编码写法，响应的 `url`、日志与录制里出现的也是它，只遮明文会漏掉。
+ */
+export function secretRedactionTexts(secrets: readonly string[]): string[] {
+  const result = new Set<string>();
+  for (const secret of secrets) {
+    if (typeof secret !== 'string') continue;
+    result.add(secret);
+    result.add(encodeURIComponent(secret));
+    result.add(new URLSearchParams([['', secret]]).toString().slice(1));
+  }
+  return [...result];
+}
+
+/** 凭证类头（名字按小写比较）的值换成 `***`，其余头的值做 `redactSecretValues`；头名保持原样。 */
+export function redactHeaders(headers: Record<string, string>, secrets: readonly string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    result[name] = CREDENTIAL_HEADER_SET.has(name.toLowerCase()) ? REDACTED : redactSecretValues(String(value), secrets);
+  }
+  return result;
+}
+
+/** query 参数：值含句柄的换成 `***`，其余值做 `redactSecretValues`。 */
+export function redactQuery(query: Record<string, string | string[]>, secrets: readonly string[]): Record<string, string | string[]> {
+  const one = (value: string): string => (containsSecretHandle(value) ? REDACTED : redactSecretValues(value, secrets));
+  const result: Record<string, string | string[]> = {};
+  for (const [name, value] of Object.entries(query)) result[name] = Array.isArray(value) ? value.map(one) : one(value);
+  return result;
+}
+
+/** URL：值含句柄的 query 参数换成 `***`，再遮蔽明文；解析不了时只做明文遮蔽。与 connector 的 `traceUrl` 相同。 */
+export function redactUrl(url: string, secrets: readonly string[]): string {
+  let text = url;
+  try {
+    const parsed = new URL(url);
+    const entries = [...parsed.searchParams.entries()];
+    if (entries.some(([, value]) => containsSecretHandle(value))) {
+      const masked = new URLSearchParams();
+      for (const [name, value] of entries) masked.append(name, containsSecretHandle(value) ? REDACTED : value);
+      parsed.search = masked.toString();
+      text = parsed.toString();
+    }
+  } catch {
+    // 原样遮蔽
+  }
+  return redactSecretValues(text, secrets);
+}