npm - @sgysldz/anti-debug - Versions diffs - 1.0.0 - Mend

@sgysldz/anti-debug 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,173 @@
+# anti-debug
+浏览器端**防调试 / 降低窥探便利度**的轻量工具库（TypeScript）。通过启发式检测「调试器暂停」与「DevTools 可能已打开」，并在命中时回调业务逻辑；可选弱化 `console` 输出。
+> **重要**：前端代码**无法**做到不可被逆向或不可被阅读。本库仅**提高成本**，不能替代服务端鉴权、密钥不下发、构建混淆、关闭生产 Source Map 等工程措施。
+---
+## 功能概览
+| 能力 | 说明 |
+| --- | --- |
+| **定时守护** | `startAntiDebugGuard` 按间隔执行多项检测，命中时调用 `onThreat(reason)` |
+| **debugger 耗时** | `detectDebuggerTiming`：利用 `debugger` 断点处前后时间差异常 |
+| **窗口 / 视口** | `detectDevToolsByDimensions`：`outer-inner` + 根元素 / `visualViewport` 差值（**不依赖断点**） |
+| **console 耗时（可选）** | `detectDevToolsByConsoleTiming`：DevTools 打开时常更慢（默认关，防误报） |
+| **本机跳过** | `skipInDevelopment` + `isLikelyLocalDevHost`，避免本地开发时被频繁打断 |
+| **noop console** | `installNoopConsole`：可选替换常见 `console.*` 为空实现 |
+| **快捷键 / 右键** | `installDevToolsUiBlock` 或 `startAntiDebugGuard({ uiBlock: true })`：拦 F12、Ctrl+Shift+I/J/C 等；可选拦右键、Ctrl+U |
+---
+## 安装
+在 monorepo 中依赖工作区包（示例）：
+```json
+{
+  "dependencies": {
+    "anti-debug": "workspace:*"
+  }
+}
+```
+```bash
+pnpm add anti-debug@workspace:* -F your-app
+```
+---
+## 快速开始
+```ts
+import { startAntiDebugGuard, installNoopConsole } from "anti-debug"
+// 可选：弱化控制台（记得在需要调试时注释掉或条件编译）
+const restoreConsole = installNoopConsole()
+const guard = startAntiDebugGuard({
+  intervalMs: 2500,
+  // 本地 localhost 不跑守护，正式域名照常检测
+  skipInDevelopment: true,
+  // 拦 F12、Ctrl+Shift+I/J/C 等；默认不拦整页右键，需则传 { blockContextMenu: true }
+  uiBlock: true,
+  onThreat(reason) {
+    // reason: 'debugger-timing' | 'devtools-dimensions' | 'devtools-console-timing'
+    // 自行实现：跳转、清 DOM、上报等（本库不内置网络请求）
+    window.location.replace("/")
+  },
+})
+// 单页应用卸载或不再需要时
+// guard.stop();
+// restoreConsole();
+```
+---
+## API 说明
+### `startAntiDebugGuard(options?)`
+- **环境**：仅在存在 `window` 的浏览器中启动 `setInterval`；Node / 无 `window` 时返回 `{ stop: () => {} }`，不抛错。
+- **`intervalMs`**：轮询间隔，默认 `2000`。
+- **`immediate`**：是否在挂载后立即执行第一次检测，默认 `true`。
+- **`skipInDevelopment`**：为 `true` 且当前 hostname 为常见本机地址（见下）时，**不启动**守护。
+- **`checks`**：可关闭 `debuggerTiming` / `devToolsDimensions`；`devToolsConsoleTiming` 默认**关闭**，需显式 `true`。
+- **`devToolsThresholds`**：微调 `widthGap` / `heightGap` / `layoutGap` / `consoleTimingMs`（漏报时可略调低前两项）。
+- **`uiBlock`**：`true` 或 `DevToolsUiBlockOptions` 对象；与 `skipInDevelopment` 同时生效时，本机 hostname 下**不**安装（与轮询一致）。`stop()` 时会一并卸载快捷键监听。
+- **`onThreat(reason)`**：有检测为阳性时调用；未传则仅轮询，不执行任何默认破坏操作。
+### `AntiDebugReason`（`reason` 取值）
+| 值                        | 含义                                                     |
+| ------------------------- | -------------------------------------------------------- |
+| `debugger-timing`         | `detectDebuggerTiming` 认为执行在断点/调试器下被显著拖慢 |
+| `devtools-dimensions`     | 视口 / 尺寸启发式认为像已打开 DevTools（dock 场景为主）  |
+| `devtools-console-timing` | 可选；`console` 单次调用耗时偏高（与「停用断点」无关）   |
+### `detectDebuggerTiming(thresholdMs?)`
+- 默认 `thresholdMs = 120`。耗时超过该值返回 `true`。
+- 内含 **`debugger` 语句**：若被 ESLint 禁止，需在项目规则中对本库或本行做例外。
+### `detectDevToolsByDimensions(options?)` 或 `(widthGap, heightGap)`
+- **对象形式**：可传 `widthGapThreshold`、`heightGapThreshold`、`layoutGapThreshold`（默认 `160` / `300` / `100`），并包含对 `innerWidth - clientWidth`、`visualViewport` 与内视口的辅助判断。
+- **两数字形式**：与旧版兼容，等价于仅调整 outer-inner 阈值。
+- **「停用断点」**：不会执行 `debugger`，故 **`debugger-timing` 会漏报**；可依赖本项与可选的 `detectDevToolsByConsoleTiming`。
+- DevTools **独立窗口 undock** 时主页面尺寸往往不变 → 纯前端**无法可靠**检测，只能依赖服务端或其它手段。
+### `detectDevToolsByConsoleTiming(thresholdMs?)`
+- 默认 `5` ms；仅建议在 `checks: { devToolsConsoleTiming: true }` 时由守护调用；单独使用亦可。
+- 可能有误报，请结合业务与 `devToolsThresholds.consoleTimingMs` 调整。
+### `isLikelyLocalDevHost()`
+在 `location` 存在时，匹配：`localhost`、`127.0.0.1`、`[::1]`、`0.0.0.0`，以及以 `.local` 结尾的主机名。
+### `installNoopConsole(options?)`
+- 默认替换常见输出类方法；返回**卸载函数**，务必在测试或需要控制台时调用恢复。
+### `installDevToolsUiBlock(options?)`
+- 在 `window` 上注册**捕获阶段** `keydown`，默认拦截：**F12**；**Ctrl+Shift+I/J/C/K/E**（Windows/Linux）；**Cmd+Option+I/J/C**、**Cmd+Shift+C**（Mac 常见）。
+- 可选：`blockContextMenu: true` 拦截整页右键；`blockViewSource: true` 拦截 **Ctrl+U** 查看源代码。
+- **无法**拦截：浏览器菜单「更多工具 → 开发者工具」、扩展、远程调试、从书签/其它页已打开的 DevTools 等。
+- 返回卸载函数；也可通过 `startAntiDebugGuard({ uiBlock: true })` 自动安装并在 `stop()` 时卸载。
+---
+## 局限与误报
+1. **「Deactivate breakpoints / 停用断点」与「Resume」**：`debugger` 不暂停时，`debugger-timing` **必然漏报**——这是浏览器行为，不是库 bug。请依赖 **`devtools-dimensions`**，并视情况开启 **`devToolsConsoleTiming`** 或调低 `devToolsThresholds.widthGap` / `heightGap`。
+2. **DevTools 独立窗口**：主页面 `outer/inner` 可能不变 → 尺寸类检测**常漏报**；纯前端无完美对策。
+3. **尺寸 / console 检测**：分屏、缩放、扩展、省电模式等 → 误报或漏报均可能存在。
+4. **性能**：轮询与 `debugger` / `console` 检测占用主线程，间隔不宜过小。
+5. **合规与体验**：过度惩罚可能伤害正常用户；请谨慎设计 `onThreat`。
+6. **快捷键拦截**：仅挡常见快捷键；无障碍与高级用户仍可通过菜单或其它方式打开 DevTools，勿当作安全边界。
+---
+## 构建
+```bash
+pnpm --filter anti-debug build
+pnpm --filter anti-debug check-types
+```
+产物目录 `dist/` **仅两个文件**（单文件分发）：
+- `index.js`：单入口 `rolldown` 打成一个 chunk，再经 `javascript-obfuscator` 处理；
+- `index.d.ts`：`dts-bundle-generator` 自 `src/index.ts` 合并生成的单文件类型声明（与 `package.json` 的 `types` / `exports` 对齐）。
+构建开始时会清空 `dist/`，避免历史构建遗留的多份 `.d.ts`。
+若根目录 `.gitignore` 忽略了 `dist/`，则构建产物不入库；克隆后需先执行 `pnpm --filter anti-debug build`，依赖方才能解析类型与运行时代码。
+### 压缩与混淆说明
+1. **Rolldown（Oxc Minifier）**：`minify` 开启完整压缩与名称混淆；**必须**设置 `compress.dropDebugger: false`，否则默认会删除源码中的 `debugger`，`detectDebuggerTiming` 会失效。
+2. **javascript-obfuscator**：对打包结果做字符串阵列、Base64 编码等增强混淆；未开启控制流平坦化/自防御等，以降低体积与误伤风险。
+若只需 Rolldown 压缩、不要第二层混淆，可将 `package.json` 中 `build` 改为仅 `rolldown -c`。
+---
+## 与其他措施的关系
+| 措施 | 说明                                     |
+| ---- | ---------------------------------------- |
+| 本库 | 运行时启发式，可组合埋点与温和响应       |
+| 构建 | 压缩、混淆、关闭生产 Source Map          |
+| 架构 | 敏感逻辑与密钥放在服务端；前端仅展示结果 |
+| 合规 | 遵循当地法律与用户协议，勿用于恶意目的   |
+---
+## 许可证
+ISC（与 `package.json` 保持一致）。

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1 @@

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,257 @@
+/**
+ * 当 {@link startAntiDebugGuard} 中某项检测判定为「可疑」时，通过
+ * {@link AntiDebugOptions.onThreat} 传入的原因标识，便于区分策略或埋点。
+ */
+export type AntiDebugReason =
+/** {@link detectDebuggerTiming} 认为执行在断点/调试器下被显著拖慢 */
+"debugger-timing"
+/** {@link detectDevToolsByDimensions} 认为窗口/视口尺寸特征像已打开 DevTools */
+ | "devtools-dimensions"
+/** {@link detectDevToolsByConsoleTiming} 认为 `console` 调用异常偏慢（与断点无关；默认不启用） */
+ | "devtools-console-timing";
+/**
+ * 分项开关：可单独关闭某一类检测，减轻误报或降低性能开销。
+ *
+ * 默认两项均为开启（等价于未传 `checks` 或各字段为 `true`）。
+ * 显式设为 `false` 可关闭对应检测。
+ */
+export interface AntiDebugChecks {
+	/**
+	 * 是否启用「debugger 耗时」检测。
+	 * @default true（未传或 `undefined` 时视为开启）
+	 */
+	debuggerTiming?: boolean;
+	/**
+	 * 是否启用「窗口 / 视口 / 根元素尺寸差」检测（DevTools dock 场景；**不依赖断点**）。
+	 * @default true
+	 */
+	devToolsDimensions?: boolean;
+	/**
+	 * 是否启用「console 调用耗时」检测（DevTools 打开时常更慢；**与「停用断点」无关**）。
+	 * 误报相对多，默认关闭；需更强提示时再开。
+	 * @default false
+	 */
+	devToolsConsoleTiming?: boolean;
+}
+/**
+ * {@link installDevToolsUiBlock} / {@link AntiDebugOptions.uiBlock} 的配置。
+ *
+ * 未写字段在实现里按「尽量拦截快捷键、尽量不挡右键」处理。
+ */
+export interface DevToolsUiBlockOptions {
+	/**
+	 * 是否拦截 **F12**。
+	 * @default true
+	 */
+	blockF12?: boolean;
+	/**
+	 * 是否拦截常见组合键（如 Ctrl+Shift+I/J/C、Mac Cmd+Opt+I 等）。
+	 * @default true
+	 */
+	blockKeyboardShortcuts?: boolean;
+	/**
+	 * 是否拦截**整个页面**的右键菜单（含非 DevTools 场景）。
+	 * @default false
+	 */
+	blockContextMenu?: boolean;
+	/**
+	 * 是否拦截 **Ctrl+U**（查看网页源代码）。
+	 * @default false
+	 */
+	blockViewSource?: boolean;
+}
+/** {@link AntiDebugOptions.devToolsThresholds} 的字段说明 */
+export interface AntiDebugDevToolsThresholds {
+	/** 传给 {@link detectDevToolsByDimensions} 的 `widthGapThreshold` */
+	widthGap?: number;
+	/** 传给 {@link detectDevToolsByDimensions} 的 `heightGapThreshold` */
+	heightGap?: number;
+	/** 传给 {@link detectDevToolsByDimensions} 的 `layoutGapThreshold` */
+	layoutGap?: number;
+	/** 传给 {@link detectDevToolsByConsoleTiming} 的毫秒阈值 */
+	consoleTimingMs?: number;
+}
+/**
+ * {@link startAntiDebugGuard} 的完整配置。
+ *
+ * **注意**：所有检测均为启发式，不能替代服务端鉴权或代码混淆；
+ * 仅用于提高前端被随意调试、窥探的成本。
+ */
+export interface AntiDebugOptions {
+	/**
+	 * 两次完整检测轮询之间的间隔（毫秒）。
+	 * 过小会增加主线程占用与用户耗电感知；过大则反应变慢。
+	 * @default 2000
+	 */
+	intervalMs?: number;
+	/**
+	 * 是否在启动守护后立即执行第一次检测（不等待首个 `interval`）。
+	 * 若设为 `false`，仅按 `intervalMs` 周期执行。
+	 * @default true
+	 */
+	immediate?: boolean;
+	/**
+	 * 任一启用的检测返回阳性时调用。常见用途：
+	 * - 跳转空白页或登录页
+	 * - 移除敏感 DOM、清空内存中的临时密钥展示
+	 * - 向自有服务端上报（需自行实现请求，本库不内置网络）
+	 *
+	 * 未提供时，检测仍会周期性执行，但不会触发任何回调（可用于仅做埋点以外的场景时自行组合）。
+	 */
+	onThreat?: (reason: AntiDebugReason) => void;
+	/**
+	 * 为 `true` 时：若当前页面 hostname 被 {@link isLikelyLocalDevHost}
+	 * 判为常见本机开发地址（如 `localhost`），则**不启动**守护，避免本地调试时被频繁打断。
+	 *
+	 * 部署到正式域名后，该判断通常为 `false`，检测会正常生效。
+	 * 若你希望连本机也强制执行检测，保持默认（`false`）即可。
+	 * @default false
+	 */
+	skipInDevelopment?: boolean;
+	/** 见 {@link AntiDebugChecks} */
+	checks?: AntiDebugChecks;
+	/**
+	 * 微调 DevTools 相关启发式阈值（漏报多时可略调低 `widthGap` / `heightGap`；误报多则调大）。
+	 * 未指定的项使用库内默认值。
+	 */
+	devToolsThresholds?: AntiDebugDevToolsThresholds;
+	/**
+	 * 是否拦截 F12 / 常见打开 DevTools 的快捷键（及可选右键、Ctrl+U）。
+	 * - `true`：使用默认（拦 F12 + 快捷键；**不**默认拦右键，避免整站右键失效）。
+	 * - 对象：见 {@link DevToolsUiBlockOptions}。
+	 *
+	 * 与 {@link skipInDevelopment} 同时为真且处于本机 hostname 时，**不会**安装（与轮询检测一致）。
+	 */
+	uiBlock?: boolean | DevToolsUiBlockOptions;
+}
+/**
+ * {@link startAntiDebugGuard} 的返回值：用于在适当时机停止轮询（例如单页应用卸载、用户登出）。
+ */
+export interface AntiDebugHandle {
+	/**
+	 * 清除内部 `setInterval`，之后不再执行检测。
+	 * 可重复调用，无副作用。
+	 */
+	stop: () => void;
+}
+/**
+ * 启动防调试守护：在浏览器主线程上以 `setInterval` 周期性执行检测。
+ *
+ * **行为说明**：
+ * - `window` 不存在（如 Node、部分 SSR 仅服务端执行）时：不启动定时器，返回的 `stop` 为空操作。
+ * - `skipInDevelopment === true` 且 {@link isLikelyLocalDevHost} 为真：不启动定时器（便于本地开发）。
+ * - 每次 `tick`：若 `onThreat` 存在且某检测为阳性，则调用 `onThreat(reason)`；同一轮内只触发一次回调。
+ *
+ * @param options 见 {@link AntiDebugOptions}
+ * @returns {@link AntiDebugHandle}，用于 `stop()` 停止轮询
+ */
+export declare function startAntiDebugGuard(options?: AntiDebugOptions): AntiDebugHandle;
+/**
+ * @module detectDebuggerTiming
+ * 「调试器耗时」检测：利用在断点处暂停时，`debugger` 语句前后时间差会异常变大。
+ *
+ * **原理简述**：正常执行时，`debugger` 到下一行几乎瞬时；若开发者工具打开且执行停在该行，
+ * 则 `performance.now()` 差值会达到数十毫秒以上（具体与机器与浏览器有关）。
+ *
+ * **局限性**：
+ * - 用户关闭断点、使用「禁用断点」或极快环境时，可能漏报。
+ * - 系统卡顿、省电模式也可能拉长耗时，存在极低概率误判（可通过调大 `thresholdMs` 缓解）。
+ */
+/**
+ * 执行一次同步耗时测量：包含一条 `debugger` 语句。
+ *
+ * @param thresholdMs 超过该毫秒数则视为「可能被调试/停在断点」。默认 `120`。
+ * @returns `true` 表示耗时超过阈值，**怀疑**处于调试暂停；`false` 表示未超过或未提供 `performance`。
+ *
+ * @example
+ * ```ts
+ * if (detectDebuggerTiming(150)) {
+ *   // 自行处理，例如仅记录埋点
+ * }
+ * ```
+ */
+export declare function detectDebuggerTiming(thresholdMs?: number): boolean;
+/**
+ * @module detectDevToolsDimensions
+ * 「窗口尺寸」启发式：许多浏览器在 DevTools 以 dock 形式贴边时，
+ * `outerWidth/Height` 与 `innerWidth/Height` 的差值会明显变大。
+ *
+ * 另补充 `innerWidth - documentElement.clientWidth` 等差值，用于在 **outer-inner**
+ * 阈值边缘时提高对「已打开 DevTools 但停用断点」场景的灵敏度（仍无法覆盖**独立窗口** undock）。
+ *
+ * **非绝对可靠**：分屏、高分屏、缩放、移动端、无边框窗口等可能误报或漏报。
+ */
+/** {@link detectDevToolsByDimensions} 的可选参数（全部有默认值） */
+export interface DevToolsDimensionOptions {
+	/** `outerWidth - innerWidth` 超过该像素则视为阳性 */
+	widthGapThreshold?: number;
+	/** `outerHeight - innerHeight` 超过该像素则视为阳性 */
+	heightGapThreshold?: number;
+	/**
+	 * `innerWidth - document.documentElement.clientWidth`（或高度侧）超过该值则视为阳性。
+	 * 用于捕捉仅靠 outer-inner 未过阈值但视口与根元素不一致的情况（略增灵敏度）。
+	 */
+	layoutGapThreshold?: number;
+}
+/**
+ * 根据窗口 / 视口 / 根元素尺寸差，判断 DevTools **可能**已打开（dock 场景为主）。
+ *
+ * 兼容旧调用方式：`detectDevToolsByDimensions(160, 300)` 两个数字参数。
+ */
+export declare function detectDevToolsByDimensions(widthOrOptions?: number | DevToolsDimensionOptions, heightGapThreshold?: number): boolean;
+/**
+ * @module detectDevToolsConsoleTiming
+ * 在 DevTools 打开（尤其 Console 面板）时，部分浏览器对 `console.*` 的调用
+ * 会比关闭时更慢。与 `debugger` 无关，**不受「停用断点」影响**。
+ *
+ * **局限**：误报/漏报均存在（省电模式、扩展、无 DevTools 但 Console 被 hook 等）；
+ * 默认在守护中**关闭**，需显式 `checks.devToolsConsoleTiming: true` 再启用。
+ */
+/**
+ * @param thresholdMs 单次 `console.debug` 耗时超过该值则视为可疑（毫秒）。
+ * @returns `true` 表示耗时超过阈值；无 `performance`/`console` 时返回 `false`。
+ */
+export declare function detectDevToolsByConsoleTiming(thresholdMs?: number): boolean;
+/**
+ * 与「是否跳过本地开发机上的守护」相关的环境判断，供 {@link startAntiDebugGuard}
+ * 在 `skipInDevelopment === true` 时使用。
+ */
+/**
+ * 判断当前页面是否运行在常见的本地开发用 hostname 上。
+ *
+ * 命中时包括：`localhost`、`127.0.0.1`、`[::1]`、`0.0.0.0`、以及以 `.local` 结尾的主机名
+ *（部分 mDNS 环境）。
+ *
+ * @returns 在浏览器中且 hostname 匹配上述规则时为 `true`；无 `location`（如部分 Worker/SSR）为 `false`。
+ */
+export declare function isLikelyLocalDevHost(): boolean;
+/**
+ * 可选：将全局 `console` 上若干方法替换为空函数，使依赖脚本难以在控制台输出结构化信息。
+ * **不能**防止用户阅读源码或 Network 面板；仅增加「随手打 log 」的阻力。
+ */
+export type ConsoleMethod = keyof Console;
+export interface NoopConsoleOptions {
+	/**
+	 * 要替换的 `console` 方法名；未传时使用 {@link DEFAULT_NOOP_METHODS}。
+	 */
+	methods?: ConsoleMethod[];
+}
+/**
+ * 安装 noop console：保存原始实现，返回 `uninstall` 函数。
+ *
+ * - 在单元测试或需要恢复调试时，务必调用返回的函数。
+ * - 若某方法在运行环境中不存在，会跳过。
+ *
+ * @param options 可选，指定要替换的方法集合。
+ * @returns 调用后恢复所有被替换方法的函数。
+ */
+export declare function installNoopConsole(options?: NoopConsoleOptions): () => void;
+/**
+ * 注册 `keydown`（捕获阶段）与可选的 `contextmenu`。
+ *
+ * @param options 未传字段见 {@link DevToolsUiBlockOptions} 默认值说明。
+ * @returns 卸载函数：移除监听，可重复调用无副作用。
+ */
+export declare function installDevToolsUiBlock(options?: DevToolsUiBlockOptions): () => void;
+export {};

package/dist/index.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,44 @@
+{
+  "name": "@sgysldz/anti-debug",
+  "version": "1.0.0",
+  "description": "浏览器端防调试与基础运行时防护（检测调试器、DevTools 等）",
+  "keywords": [
+    "anti-debug",
+    "browser",
+    "devtools",
+    "protection"
+  ],
+  "license": "ISC",
+  "author": "ldz",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "typescript": "~6.0.3"
+  },
+  "devDependencies": {
+    "dts-bundle-generator": "^9.5.1",
+    "javascript-obfuscator": "^5.4.2",
+    "rolldown": "1.0.0-rc.18"
+  },
+  "scripts": {
+    "build": "node ./scripts/clean-dist.mjs && rolldown -c && node ./scripts/obfuscate-dist.mjs && dts-bundle-generator -o dist/index.d.ts src/index.ts --project tsconfig.json --no-banner",
+    "check-types": "tsc -p tsconfig.json --noEmit"
+  }
+}