@mycf711/dsh-gate 0.0.0-stage → 0.1.0

package/lib/index.js

@@ -0,0 +1,503 @@
+/**
+ * @mycf711/dsh-gate —— 内容层门禁（确定性规则 + 可选语义复审）。
+ *
+ * 门禁只管「回复正文里有什么」：凭证、本机路径、越界引用、未发布承诺、破坏性建议。
+ * 它**不是**工具权限层，不替代官方授权审查。
+ *
+ * 四层配置，后者覆盖前者：
+ *   1. 默认          packages/dsh-gate/gates/default.json（随包发布）
+ *   2. 用户全局      ~/.dsh/state/session-superagent/gates.json
+ *   3. 项目          <repo>/.superagent/gates.json
+ *   4. 本地覆盖      <repo>/.superagent/gates.local.json
+ *
+ * 规则按 id 合并：同 id 覆盖，不同 id 追加。项目 / 本地只能**关闭**语义复审，
+ * 不能替用户开复审或换模型。
+ *
+ * 除 loadGateConfig / readGateScope / writeGateConfig 这类显式 IO 函数外，其余都是纯函数，方便主插件和测试注入。
+ */
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  SEMANTIC_TRIGGERS,
+  normalizeSemanticConfig,
+  semanticReview,
+} from './semantic.js'
+
+export {
+  SEMANTIC_TRIGGERS,
+  listModels,
+  normalizeSemanticConfig,
+  optimizePrompt,
+  resolveSemanticConfig,
+  parseSemanticReply,
+  semanticReview,
+} from './semantic.js'
+
+export const PACKAGE_NAME = '@mycf711/dsh-gate'
+/** 与 package.json 的 version 同步（测试守着）。 */
+export const PACKAGE_VERSION = '0.1.0'
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+
+/** 门禁支持的全部触发器。 */
+export const TRIGGERS = Object.freeze(['issue.reply', 'pr.reply', 'pr.handle', 'merge', 'release'])
+const TRIGGER_SET = new Set(TRIGGERS)
+const SEMANTIC_TRIGGER_SET = new Set(SEMANTIC_TRIGGERS)
+
+/** 确定性规则类型。 */
+export const RULE_TYPES = Object.freeze(['regex', 'contains', 'maxLength', 'nonEmpty', 'foreign-ref'])
+const RULE_TYPE_SET = new Set(RULE_TYPES)
+
+const RULE_ID_RE = /^[a-z][a-z0-9-]{1,63}$/
+const MAX_PATTERN_LENGTH = 400
+const MAX_EXTENDS_DEPTH = 8
+
+export const DEFAULT_GATE_PATH = join(PACKAGE_ROOT, 'gates', 'default.json')
+
+function stateDir({ home = homedir(), env = process.env } = {}) {
+  return env.DSH_SUPERAGENT_STATE || join(home, '.dsh', 'state', 'session-superagent')
+}
+
+/** 用户全局配置路径；`DSH_GATE_USER_CONFIG` 可整体覆盖，方便测试与自定义安装。 */
+export function userGatePath({ home = homedir(), env = process.env } = {}) {
+  return env.DSH_GATE_USER_CONFIG || join(stateDir({ home, env }), 'gates.json')
+}
+
+/** 项目配置路径。 */
+export function projectGatePath(repo = process.cwd()) {
+  return join(repo || process.cwd(), '.superagent', 'gates.json')
+}
+
+/** 本地覆盖路径（不进版本库）。 */
+export function localGatePath(repo = process.cwd()) {
+  return join(repo || process.cwd(), '.superagent', 'gates.local.json')
+}
+
+// 旧版主插件 lib/gates.js 的导出名，保留给 re-export，避免 G2 迁移时破坏调用点。
+export const USER_GATE_PATH = userGatePath
+export const PROJECT_GATE_PATH = projectGatePath
+export const LOCAL_GATE_PATH = localGatePath
+
+function configPathFor(scope, { repo = process.cwd(), home = homedir(), env = process.env, defaultPath = DEFAULT_GATE_PATH } = {}) {
+  if (scope === 'default') return defaultPath
+  if (scope === 'user') return userGatePath({ home, env })
+  if (scope === 'project') return projectGatePath(repo)
+  if (scope === 'local') return localGatePath(repo)
+  throw new Error('scope 只能是 default / user / project / local，收到：' + String(scope))
+}
+
+function normalizeRule(rule) {
+  if (!rule || typeof rule !== 'object' || Array.isArray(rule)) return null
+  const id = String(rule.id || '')
+  if (!RULE_ID_RE.test(id)) return null
+  if (!RULE_TYPE_SET.has(rule.type)) return null
+  if (rule.severity !== undefined && rule.severity !== 'error' && rule.severity !== 'warn') return null
+  const triggers = Array.isArray(rule.triggers) && rule.triggers.length > 0
+    ? [...new Set(rule.triggers.map(String).filter((trigger) => TRIGGER_SET.has(trigger)))]
+    : ['issue.reply', 'pr.reply']
+  if (triggers.length === 0) return null
+  const flags = typeof rule.flags === 'string' ? rule.flags : ''
+  if (rule.type === 'regex') {
+    const pattern = String(rule.pattern || '')
+    if (!pattern || [...pattern].length > MAX_PATTERN_LENGTH) return null
+    try {
+      new RegExp(pattern, flags)
+    } catch {
+      return null
+    }
+  }
+  if (rule.type === 'foreign-ref' && rule.pattern !== undefined) {
+    try {
+      new RegExp(String(rule.pattern), 'g')
+    } catch {
+      return null
+    }
+  }
+  // 坏规则不能变成「全拦」：contains 空串 / maxLength 非正数会让每条回复都命中，
+  // 直接丢弃（validateConfig 会给出具体原因），而不是静默阻断所有回复。
+  if (rule.type === 'contains' && (typeof rule.value !== 'string' || rule.value.length === 0)) return null
+  if (rule.type === 'maxLength' && !(Number.isFinite(Number(rule.value)) && Number(rule.value) > 0)) return null
+  return {
+    id,
+    label: String(rule.label || id),
+    description: String(rule.description || ''),
+    severity: rule.severity === 'warn' ? 'warn' : 'error',
+    triggers,
+    type: rule.type,
+    pattern: rule.pattern === undefined ? undefined : String(rule.pattern),
+    flags,
+    value: rule.value,
+    message: String(rule.message || rule.label || '未通过门禁'),
+  }
+}
+
+/** 整理成稳定形状；非法规则被丢弃（`validateConfig` 会给出具体原因）。 */
+export function normalizeConfig(input, semanticBase = undefined) {
+  const config = input && typeof input === 'object' && !Array.isArray(input) ? input : {}
+  const rules = Array.isArray(config.rules) ? config.rules.map(normalizeRule).filter(Boolean) : []
+  return {
+    version: 1,
+    name: typeof config.name === 'string' && config.name.trim() ? config.name.trim() : 'config',
+    rules,
+    semantic: normalizeSemanticConfig(config.semantic, semanticBase),
+  }
+}
+
+/**
+ * 合并两层配置：同 id 覆盖、不同 id 追加；语义复审按字段覆盖。
+ * 规则顺序保持「先出现的位置」，同 id 只更新内容。
+ */
+export function mergeConfig(base, override) {
+  const a = normalizeConfig(base)
+  // 语义配置按字段合并：只写 mode 的层不能把上层 baseURL / model 清空。
+  const b = normalizeConfig(override, a.semantic)
+  const byId = new Map(a.rules.map((rule) => [rule.id, rule]))
+  for (const rule of b.rules) byId.set(rule.id, rule)
+  return {
+    version: 1,
+    name: b.name !== 'config' ? b.name : a.name,
+    rules: [...byId.values()],
+    semantic: b.semantic,
+  }
+}
+
+/**
+ * 读一个配置层，并解析 `extends`。
+ *
+ * - 没有 `extends`：只返回本层规则（由调用方叠到已累积配置上）。
+ * - `extends: false | 'none'`：返回 `mode: 'replace'`，丢掉之前所有层。
+ * - `extends: true | 'default'`：以包内默认配置为基。
+ * - `extends: './base.json'`：以相对本文件的配置为基。
+ * - `extends: { rules: [...] }`：以对象为基。
+ *
+ * 读不到 / 循环 / 层级过深时**不抛错**：记录 error，按本层规则继续（fail-open，
+ * 避免一个坏配置文件让整个门禁不可用）。
+ */
+function readLayerConfig(path, { seen = new Set(), depth = 0 } = {}) {
+  const absolute = resolve(path)
+  const empty = { config: normalizeConfig(null), mode: 'merge', raw: null, error: null }
+  if (depth > MAX_EXTENDS_DEPTH) {
+    return { ...empty, error: 'extends 嵌套超过 ' + MAX_EXTENDS_DEPTH + ' 层：' + basename(absolute) }
+  }
+  if (seen.has(absolute)) {
+    return { ...empty, error: 'extends 出现循环：' + basename(absolute) }
+  }
+  seen.add(absolute)
+  if (!existsSync(absolute)) {
+    return { ...empty, error: 'extends 目标不存在：' + basename(absolute) }
+  }
+  let raw
+  try {
+    raw = JSON.parse(readFileSync(absolute, 'utf8'))
+  } catch (error) {
+    return { ...empty, error: '配置不是合法 JSON：' + basename(absolute) + '（' + String((error && error.message) || error) + '）' }
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...empty, error: '配置必须是对象：' + basename(absolute) }
+  }
+  if (!Object.prototype.hasOwnProperty.call(raw, 'extends')) {
+    // 返回**原始对象**，让调用方的 mergeConfig 按字段合并 semantic。
+    return { config: raw, mode: 'merge', raw, error: null }
+  }
+  const extended = raw.extends
+  if (extended === false || extended === 'none') {
+    return { config: raw, mode: 'replace', raw, error: null }
+  }
+  if (extended === true || extended === 'default') {
+    const base = readLayerConfig(DEFAULT_GATE_PATH, { seen: new Set(seen), depth: depth + 1 })
+    return { config: mergeConfig(base.config, raw), mode: 'merge', raw, error: base.error }
+  }
+  if (typeof extended === 'string') {
+    const target = resolve(dirname(absolute), extended)
+    const base = readLayerConfig(target, { seen, depth: depth + 1 })
+    return { config: mergeConfig(base.config, raw), mode: 'merge', raw, error: base.error }
+  }
+  if (extended && typeof extended === 'object' && !Array.isArray(extended)) {
+    return { config: mergeConfig(extended, raw), mode: 'merge', raw, error: null }
+  }
+  return { config: raw, mode: 'merge', raw, error: 'extends 必须是字符串、false 或对象：' + basename(absolute) }
+}
+
+/**
+ * 项目 / 本地层只能关掉语义复审，不能开启或换模型。
+ * 返回修正后的配置；尝试开启时往 errors 里记一条。
+ */
+function restrictSemantic(config, raw, beforeSemantic, layer, path, errors) {
+  const requested = raw && Object.prototype.hasOwnProperty.call(raw, 'semantic') ? raw.semantic : undefined
+  const disable = requested === false
+    || (requested && typeof requested === 'object' && !Array.isArray(requested) && requested.enabled === false)
+  const attempted = requested !== undefined && !disable
+  const semantic = beforeSemantic
+    ? { ...beforeSemantic, enabled: disable ? false : beforeSemantic.enabled === true }
+    : { enabled: false }
+  if (attempted) {
+    errors.push({ layer, path, error: '项目/本地配置只能关闭语义复审，不能开启或更换模型' })
+  }
+  return { ...config, semantic }
+}
+
+/**
+ * 读取四层配置。
+ *
+ * @returns {{ config: object, sources: Array<{name: string, path: string}>, errors: Array<{layer: string, path: string, error: string}> }}
+ * `sources` 只列真实存在的层（按 default → user → project → local 顺序）。
+ */
+export function loadGateConfig({
+  repo = process.cwd(),
+  home = homedir(),
+  env = process.env,
+  defaultPath = DEFAULT_GATE_PATH,
+} = {}) {
+  const sources = []
+  const errors = []
+  let config = normalizeConfig(null)
+  const layers = [
+    ['default', defaultPath],
+    ['user', userGatePath({ home, env })],
+    ['project', projectGatePath(repo)],
+    ['local', localGatePath(repo)],
+  ]
+  for (const [name, path] of layers) {
+    if (!existsSync(path)) {
+      if (name === 'default') errors.push({ layer: name, path, error: '默认规则文件不存在' })
+      continue
+    }
+    const layer = readLayerConfig(path)
+    if (!layer.raw) {
+      errors.push({ layer: name, path, error: layer.error || '配置读取失败' })
+      continue
+    }
+    if (layer.error) errors.push({ layer: name, path, error: layer.error })
+    sources.push({ name, path })
+    const beforeSemantic = config.semantic
+    config = layer.mode === 'replace' ? normalizeConfig(layer.config) : mergeConfig(config, layer.config)
+    if (name === 'project' || name === 'local') {
+      config = restrictSemantic(config, layer.raw, beforeSemantic, name, path, errors)
+    }
+  }
+  return { config, sources, errors }
+}
+
+function normalizeCurrent(value) {
+  if (value === undefined || value === null) return null
+  const text = String(value).trim().replace(/^#/, '')
+  if (!/^\d+$/.test(text)) return null
+  return String(Number(text))
+}
+
+function ruleMatches(rule, text, current) {
+  if (rule.type === 'nonEmpty') return text.trim().length === 0
+  if (rule.type === 'maxLength') return text.length > Number(rule.value || 0)
+  if (rule.type === 'contains') return text.includes(String(rule.value || ''))
+  if (rule.type === 'foreign-ref') {
+    // 没给当前编号时无法判断「其它」——跳过，不制造假红。
+    const currentRef = normalizeCurrent(current)
+    if (currentRef === null) return false
+    const re = new RegExp(rule.pattern || '#(\\d+)', 'g')
+    const refs = [...text.matchAll(re)].map((match) => (match[1] === undefined ? match[0] : match[1]))
+    return refs.some((ref) => normalizeCurrent(ref) !== currentRef)
+  }
+  return new RegExp(rule.pattern, rule.flags || '').test(text)
+}
+
+function assertTrigger(trigger) {
+  if (!TRIGGER_SET.has(trigger)) {
+    throw new Error('trigger 必须是 ' + TRIGGERS.join(' / ') + ' 之一，收到：' + String(trigger))
+  }
+}
+
+/**
+ * 跑确定性门禁。
+ *
+ * @param {string} text 回复正文
+ * @param {object} config 配置（四层合并结果或任意自定义配置）
+ * @param {{trigger?: string, current?: number|string}} options
+ * @returns {{ ok: boolean, hits: Array<{id: string, label: string, severity: 'error'|'warn', message: string}> }}
+ * `ok` 只由 `severity: 'error'` 的命中决定；warn 命中会出现在 hits 里但不阻断。
+ */
+export function lintText(text, config, { trigger = 'issue.reply', current } = {}) {
+  assertTrigger(trigger)
+  const body = String(text ?? '')
+  const hits = []
+  for (const rule of normalizeConfig(config).rules) {
+    if (!rule.triggers.includes(trigger)) continue
+    if (!ruleMatches(rule, body, current)) continue
+    hits.push({ id: rule.id, label: rule.label, severity: rule.severity, message: rule.message })
+  }
+  return { ok: hits.every((hit) => hit.severity !== 'error'), hits }
+}
+
+/**
+ * 严格校验一份配置（写盘 / 面板保存前用）。
+ * 与 `normalizeConfig` 不同：这里不静默丢弃，返回第一条具体错误。
+ */
+export function validateConfig(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { ok: false, error: '配置必须是对象' }
+  }
+  if (!Array.isArray(input.rules)) return { ok: false, error: 'rules 必须是数组' }
+  if (input.name !== undefined && typeof input.name !== 'string') return { ok: false, error: 'name 必须是字符串' }
+  const seen = new Set()
+  for (const raw of input.rules) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      return { ok: false, error: '规则必须是对象' }
+    }
+    const id = String(raw.id || '')
+    if (!RULE_ID_RE.test(id)) return { ok: false, error: '规则 id 非法：' + (id || '?') }
+    if (seen.has(id)) return { ok: false, error: '规则 id 重复：' + id }
+    seen.add(id)
+    if (!RULE_TYPE_SET.has(raw.type)) return { ok: false, error: '规则类型非法：' + id }
+    if (raw.severity !== undefined && raw.severity !== 'error' && raw.severity !== 'warn') {
+      return { ok: false, error: 'severity 只能是 error / warn：' + id }
+    }
+    if (raw.triggers !== undefined) {
+      if (!Array.isArray(raw.triggers) || raw.triggers.length === 0) {
+        return { ok: false, error: 'triggers 必须是非空数组：' + id }
+      }
+      for (const trigger of raw.triggers) {
+        if (!TRIGGER_SET.has(String(trigger))) {
+          return { ok: false, error: '未知 trigger：' + String(trigger) + '（' + id + '）' }
+        }
+      }
+    }
+    if (raw.type === 'regex') {
+      const pattern = String(raw.pattern || '')
+      if (!pattern) return { ok: false, error: 'regex 规则缺少 pattern：' + id }
+      if ([...pattern].length > MAX_PATTERN_LENGTH) return { ok: false, error: '正则过长（上限 ' + MAX_PATTERN_LENGTH + ' 字符）：' + id }
+      if (raw.flags !== undefined && typeof raw.flags !== 'string') return { ok: false, error: 'flags 必须是字符串：' + id }
+      try {
+        new RegExp(pattern, raw.flags || '')
+      } catch (error) {
+        return { ok: false, error: '正则非法：' + id + '（' + String((error && error.message) || error) + '）' }
+      }
+    }
+    if (raw.type === 'contains' && (typeof raw.value !== 'string' || raw.value.length === 0)) {
+      return { ok: false, error: 'contains 规则缺少 value：' + id }
+    }
+    if (raw.type === 'maxLength' && !(Number.isFinite(Number(raw.value)) && Number(raw.value) > 0)) {
+      return { ok: false, error: 'maxLength 规则的 value 必须是正数：' + id }
+    }
+    if (raw.type === 'foreign-ref' && raw.pattern !== undefined) {
+      try {
+        new RegExp(String(raw.pattern), 'g')
+      } catch (error) {
+        return { ok: false, error: 'foreign-ref 的 pattern 非法：' + id + '（' + String((error && error.message) || error) + '）' }
+      }
+    }
+  }
+  if (input.semantic !== undefined && input.semantic !== false) {
+    if (typeof input.semantic !== 'object' || Array.isArray(input.semantic)) {
+      return { ok: false, error: 'semantic 必须是对象或 false' }
+    }
+    if (input.semantic.enabled !== undefined && typeof input.semantic.enabled !== 'boolean') {
+      return { ok: false, error: 'semantic.enabled 必须是布尔值' }
+    }
+    if (input.semantic.mode !== undefined && input.semantic.mode !== 'warn' && input.semantic.mode !== 'block') {
+      return { ok: false, error: 'semantic.mode 只能是 warn / block' }
+    }
+    if (input.semantic.timeoutMs !== undefined && !(Number.isFinite(Number(input.semantic.timeoutMs)) && Number(input.semantic.timeoutMs) > 0)) {
+      return { ok: false, error: 'semantic.timeoutMs 必须是正数' }
+    }
+    if (input.semantic.maxInputChars !== undefined && !(Number.isFinite(Number(input.semantic.maxInputChars)) && Number(input.semantic.maxInputChars) > 0)) {
+      return { ok: false, error: 'semantic.maxInputChars 必须是正数' }
+    }
+  }
+  return { ok: true, config: normalizeConfig(input) }
+}
+
+/** 读某一层的原始配置（给面板展示「这一层现在写的是什么」）。 */
+export function readGateScope(scope, { repo = process.cwd(), home = homedir(), env = process.env, defaultPath = DEFAULT_GATE_PATH } = {}) {
+  const path = configPathFor(scope, { repo, home, env, defaultPath })
+  try {
+    if (!existsSync(path)) return { path, config: null }
+    return { path, config: JSON.parse(readFileSync(path, 'utf8')) }
+  } catch (error) {
+    return { path, config: null, error: '配置不是合法 JSON：' + String((error && error.message) || error) }
+  }
+}
+
+/**
+ * 写某一层配置：先备份 `.bak`，再原子替换（临时文件 + rename）。
+ * 只允许 user / project / local —— 默认规则随包发布，不能从面板改。
+ */
+export function writeGateConfig(scope, config, { repo = process.cwd(), home = homedir(), env = process.env } = {}) {
+  if (scope !== 'user' && scope !== 'project' && scope !== 'local') {
+    throw new Error('scope 只能是 user / project / local')
+  }
+  const checked = validateConfig(config)
+  if (!checked.ok) throw new Error(checked.error)
+  const path = configPathFor(scope, { repo, home, env })
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = path + '.tmp-' + process.pid + '-' + Date.now()
+  try {
+    if (existsSync(path)) copyFileSync(path, path + '.bak')
+    writeFileSync(tmp, JSON.stringify(checked.config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+    renameSync(tmp, path)
+  } catch (error) {
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp)
+    } catch {
+      // 清理失败不覆盖原始错误
+    }
+    throw error
+  }
+  return { path, config: checked.config }
+}
+
+/**
+ * 稳定 GateProvider 接口（主插件优先 `ctx.get('gate')`，缺失时回退到这里）。
+ *
+ * ```js
+ * const gate = createGate()
+ * const result = await gate.check({ trigger: 'issue.reply', text, current, repo })
+ * if (!result.ok) return
+ * ```
+ *
+ * 语义复审默认跟随配置（`semantic.enabled`），且只对 merge / release 生效。
+ */
+export function createGate({
+  id = 'dsh-gate',
+  version = PACKAGE_VERSION,
+  repo,
+  config,
+  semantic = true,
+  semanticOptions = {},
+  ...loadOptions
+} = {}) {
+  return {
+    id,
+    version,
+    async check(input = {}) {
+      const trigger = input.trigger === undefined ? 'issue.reply' : input.trigger
+      assertTrigger(trigger)
+      const text = String(input.text ?? '')
+      const current = input.current
+      const loaded = config !== undefined
+        ? { config: normalizeConfig(config), sources: [], errors: [] }
+        : loadGateConfig({ ...loadOptions, repo: input.repo || repo || process.cwd() })
+      const deterministic = lintText(text, loaded.config, { trigger, current })
+      const hits = [...deterministic.hits]
+      let semanticResult = { skipped: true }
+      const semanticEnabled = Boolean(loaded.config.semantic && loaded.config.semantic.enabled === true)
+      if (semantic !== false && semanticEnabled && SEMANTIC_TRIGGER_SET.has(trigger)) {
+        semanticResult = await semanticReview(text, loaded.config, { trigger, current, ...semanticOptions })
+        hits.push(...(semanticResult.hits || []))
+      }
+      return {
+        ok: hits.every((hit) => hit.severity !== 'error'),
+        hits,
+        semantic: semanticResult,
+      }
+    },
+  }
+}

package/lib/redact.js

@@ -0,0 +1,52 @@
+/**
+ * 凭证脱敏：任何要进模型上下文的文本都先过这里。
+ *
+ * 为什么独立包也要带一份：语义复审会把回复正文发给模型，如果正文里本来就有
+ * token / 私钥 / 数据库口令，那等于亲手把它们送出去。门禁先脱敏，再发请求。
+ *
+ * 两层形状：
+ * 1. 供应商前缀是精确的（ghp_ / github_pat_ / glpat- / xox / sk_live_ / npm_ / AKIA ...），
+ *    误伤极低；
+ * 2. 通用形状（URL 里的密码、裸 Bearer、查询参数）必须配上下文词，不做裸扫。
+ */
+
+/** Patterns that must never reach the transcript. */
+export const SECRET_PATTERNS = [
+  /gh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub PAT（ghp_ / gho_ / ghu_ / ghs_ / ghr_）
+  /github_pat_[A-Za-z0-9_]{20,}/g, // GitHub 细粒度 PAT
+  /glpat-[A-Za-z0-9_-]{20,}/g, // GitLab PAT
+  /xox[baprs]-[A-Za-z0-9-]{10,}/g, // Slack
+  /sk_live_[A-Za-z0-9]{20,}/g, // Stripe
+  /npm_[A-Za-z0-9]{30,}/g, // npm automation token
+  /AIza[0-9A-Za-z_-]{35}/g, // Google API key
+  /AKIA[0-9A-Z]{16}/g, // AWS access key id
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, // JWT
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, // 完整 PEM 块
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*/g, // 被截断的 PEM：吃到结尾
+  /-----BEGIN PGP PRIVATE KEY BLOCK-----[\s\S]*?-----END PGP PRIVATE KEY BLOCK-----/g,
+  /Authorization:\s*(?:token|Bearer|Basic)\s+\S+/gi, // 回显的请求头
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}/g, // 裸 Bearer（无头名）
+  /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp):\/\/[^:\s/]+:[^@\s]+@/gi, // 数据库 URL 里的密码
+  /[?&](?:access_token|api_key|apikey|private_token)=[^&\s"']+/gi, // 查询参数里的凭证
+  // Gitee 私人令牌：无前缀的 32 位十六进制。裸扫会误伤 md5 / commit sha，
+  // 所以要求前面 20 字内出现 gitee / 令牌 / access_token 这类上下文词。
+  /\b(?:gitee|私人令牌|access[_ ]?token)[^\n]{0,20}?\b[0-9a-f]{32}\b/gi,
+]
+
+/** Replace every credential-shaped substring with `***`. */
+export function redact(text) {
+  let out = String(text ?? '')
+  for (const re of SECRET_PATTERNS) out = out.replace(re, '***')
+  return out
+}
+
+/** True when `text` still contains a credential-shaped substring. */
+export function hasSecret(text) {
+  const value = String(text ?? '')
+  return SECRET_PATTERNS.some((re) => {
+    re.lastIndex = 0
+    const hit = re.test(value)
+    re.lastIndex = 0
+    return hit
+  })
+}