@gangdai/fingerprint 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gang.dai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# @gangdai/fingerprint
+
+A lightweight, zero-dependency browser fingerprint collection library with full TypeScript support.
+
+## Features
+
+- 🔒 **High-precision fingerprinting**: Combines multiple dimensions to generate unique device identifiers
+- 💾 **Smart caching**: Dual-layer caching with IndexedDB + LocalStorage, 30-day validity
+- 🚀 **Lightweight & efficient**: Zero dependencies, small bundle size, excellent performance
+- 📦 **Ready to use**: Simple API with full TypeScript support
+- 🔄 **Fallback mechanism**: Automatically generates UUID when collection fails
+
+## Installation
+
+```bash
+# Using pnpm (recommended)
+pnpm add @gangdai/fingerprint
+
+# Using npm
+npm install @gangdai/fingerprint
+
+# Using yarn
+yarn add @gangdai/fingerprint
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { getDeviceFingerprint } from '@gangdai/fingerprint';
+
+// Get device fingerprint
+const result = await getDeviceFingerprint();
+console.log(result.fingerprint); // "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
+console.log(result.isFallback);  // false
+console.log(result.timestamp);   // 1705824000000
+```
+
+### Get Fingerprint String Only
+
+```typescript
+import { getFingerprint } from '@gangdai/fingerprint';
+
+const fingerprint = await getFingerprint();
+console.log(fingerprint); // "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
+```
+
+### Custom Configuration
+
+```typescript
+import { initFingerprint, getDeviceFingerprint } from '@gangdai/fingerprint';
+
+// Initialize with custom config
+initFingerprint({
+  cacheExpiry: 7 * 24 * 60 * 60 * 1000,  // Cache for 7 days
+  enableIndexedDB: true,                  // Enable IndexedDB
+  storageKeyPrefix: 'myapp',              // Custom storage key prefix
+  version: 1,                             // Version number
+});
+
+// Use configured instance
+const result = await getDeviceFingerprint();
+```
+
+### Use in HTTP Requests
+
+```typescript
+import { getFingerprint, HTTP_HEADER_NAME } from '@gangdai/fingerprint';
+import axios from 'axios';
+
+// Get fingerprint
+const fingerprint = await getFingerprint();
+
+// Include fingerprint in request headers
+axios.post('/api/login', data, {
+  headers: {
+    [HTTP_HEADER_NAME]: fingerprint,  // 'X-Device-Fingerprint'
+  },
+});
+```
+
+### Refresh and Clear
+
+```typescript
+import { refreshFingerprint, clearFingerprint } from '@gangdai/fingerprint';
+
+// Force refresh fingerprint (re-collect)
+const newResult = await refreshFingerprint();
+
+// Clear cached fingerprint
+await clearFingerprint();
+```
+
+## API 文档
+
+### `getDeviceFingerprint(): Promise<FingerprintResult>`
+
+获取完整的设备指纹信息。
+
+**返回值：**
+```typescript
+interface FingerprintResult {
+  fingerprint: string;  // 32位 MD5 哈希值
+  isFallback: boolean;  // 是否为兜底 UUID
+  timestamp: number;    // 采集时间戳
+  expiresAt: number;    // 过期时间戳
+}
+```
+
+### `getFingerprint(): Promise<string>`
+
+获取设备指纹字符串（简化版）。
+
+**返回值：** 32位 MD5 哈希字符串
+
+### `initFingerprint(config?: FingerprintConfig): void`
+
+初始化指纹模块配置（可选）。
+
+**参数：**
+```typescript
+interface FingerprintConfig {
+  cacheExpiry?: number;        // 缓存过期时间（毫秒），默认 30 天
+  enableIndexedDB?: boolean;   // 是否启用 IndexedDB，默认 true
+  storageKeyPrefix?: string;   // 存储键名前缀，默认 'df'
+  version?: number;            // 版本号，默认 1
+}
+```
+
+### `refreshFingerprint(): Promise<FingerprintResult>`
+
+强制刷新指纹（重新采集，忽略缓存）。
+
+### `clearFingerprint(): Promise<void>`
+
+清除缓存的指纹数据。
+
+### `getHeaderName(): string`
+
+获取 HTTP Header 名称。
+
+**返回值：** `'X-Device-Fingerprint'`
+
+### 常量
+
+```typescript
+import { HTTP_HEADER_NAME } from '@gangdai/fingerprint';
+
+console.log(HTTP_HEADER_NAME); // 'X-Device-Fingerprint'
+```
+
+## Collection Dimensions
+
+The fingerprint collection includes the following dimensions:
+
+- **Basic Information**: User Agent, language, timezone, screen resolution, color depth
+- **Canvas Fingerprint**: Canvas rendering characteristics
+- **WebGL Fingerprint**: WebGL renderer information
+- **Audio Fingerprint**: Audio context characteristics
+- **Font Detection**: System installed fonts list
+- **Plugin Information**: Browser plugins list
+- **Hardware Information**: CPU cores, memory size, touch support
+
+## Caching Strategy
+
+1. **Prioritize IndexedDB**: Persistent storage, unaffected by private mode
+2. **Fallback to LocalStorage**: Alternative when IndexedDB is unavailable
+3. **30-day validity**: Default cache for 30 days, customizable
+4. **Version management**: Supports version numbers for future upgrades
+
+## Fallback Mechanism
+
+When fingerprint collection fails (e.g., private mode, permission restrictions), a UUID is automatically generated as a fallback identifier:
+
+```typescript
+const result = await getDeviceFingerprint();
+if (result.isFallback) {
+  console.log('Using fallback UUID:', result.fingerprint);
+}
+```
+
+## TypeScript Support
+
+Complete TypeScript type definitions:
+
+```typescript
+import type {
+  FingerprintResult,
+  FingerprintConfig,
+  CollectorResult,
+  CachedFingerprint
+} from '@gangdai/fingerprint';
+```
+
+## Browser Compatibility
+
+- Chrome 60+
+- Firefox 55+
+- Safari 11+
+- Edge 79+
+
+## Important Notes
+
+1. **Privacy Compliance**: Ensure compliance with local privacy regulations (e.g., GDPR, CCPA) before use
+2. **User Notification**: Recommend explaining the use of device fingerprinting in your privacy policy
+3. **Not a Sole Identifier**: Recommend using in combination with other authentication methods
+4. **Cache Clearing**: Users clearing browser data will cause fingerprint regeneration
+
+## Use Cases
+
+- 🔐 **Login Security**: Detect abnormal login behavior
+- 🛡️ **Risk Control**: Identify malicious devices and fraudulent activities
+- 📊 **User Analytics**: Count unique devices
+- 🔄 **Session Management**: Cross-tab session correlation
+
+## License
+
+MIT License
+
+## Support
+
+For issues or suggestions, please visit [GitHub Issues](https://github.com/gangdai/fingerprint/issues).

package/dist/index.d.mts

@@ -0,0 +1,86 @@
+/**
+ * 设备指纹模块 - 类型定义
+ * @description 独立模块，便于其他系统复用
+ */
+/** 指纹采集结果 */
+interface FingerprintResult {
+    /** 指纹哈希值 (32位MD5) */
+    fingerprint: string;
+    /** 是否为兜底UUID */
+    isFallback: boolean;
+    /** 采集时间戳 */
+    timestamp: number;
+    /** 过期时间戳 */
+    expiresAt: number;
+}
+/** 指纹管理器配置 */
+interface FingerprintConfig {
+    /** 缓存过期时间（毫秒），默认30天 */
+    cacheExpiry?: number;
+    /** 是否启用IndexedDB，默认true */
+    enableIndexedDB?: boolean;
+    /** 存储键名前缀 */
+    storageKeyPrefix?: string;
+    /** 当前版本号 */
+    version?: number;
+}
+
+/** HTTP Header 名称 */
+declare const HTTP_HEADER_NAME = "X-Device-Fingerprint";
+
+/**
+ * 设备指纹模块 - 主入口
+ *
+ * @description
+ * 独立、高内聚的设备指纹模块，便于复用到其他系统。
+ *
+ * @example
+ * ```typescript
+ * import { getDeviceFingerprint, initFingerprint } from 'src/utils/fingerprint';
+ *
+ * // 方式1: 使用默认配置
+ * const fp = await getDeviceFingerprint();
+ * console.log(fp.fingerprint); // 32位MD5哈希
+ *
+ * // 方式2: 自定义配置
+ * initFingerprint({
+ *   cacheExpiry: 7 * 24 * 60 * 60 * 1000, // 7天
+ *   storageKeyPrefix: 'myapp',
+ * });
+ * const fp2 = await getDeviceFingerprint();
+ * ```
+ *
+ * @author IDaaS Team
+ * @version 1.0.0
+ */
+
+/**
+ * 初始化指纹模块（可选）
+ * @param config 配置选项
+ */
+declare function initFingerprint(config?: FingerprintConfig): void;
+/**
+ * 获取设备指纹
+ * @returns 指纹结果
+ */
+declare function getDeviceFingerprint(): Promise<FingerprintResult>;
+/**
+ * 获取指纹值（简化版，仅返回哈希字符串）
+ * @returns 32位MD5哈希字符串
+ */
+declare function getFingerprint(): Promise<string>;
+/**
+ * 强制刷新指纹
+ * @returns 新的指纹结果
+ */
+declare function refreshFingerprint(): Promise<FingerprintResult>;
+/**
+ * 清除指纹缓存
+ */
+declare function clearFingerprint(): Promise<void>;
+/**
+ * 获取HTTP Header名称
+ */
+declare function getHeaderName(): string;
+
+export { type FingerprintConfig, type FingerprintResult, HTTP_HEADER_NAME, clearFingerprint, getDeviceFingerprint, getFingerprint, getHeaderName, initFingerprint, refreshFingerprint };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 设备指纹模块 - 类型定义
+ * @description 独立模块，便于其他系统复用
+ */
+/** 指纹采集结果 */
+interface FingerprintResult {
+    /** 指纹哈希值 (32位MD5) */
+    fingerprint: string;
+    /** 是否为兜底UUID */
+    isFallback: boolean;
+    /** 采集时间戳 */
+    timestamp: number;
+    /** 过期时间戳 */
+    expiresAt: number;
+}
+/** 指纹管理器配置 */
+interface FingerprintConfig {
+    /** 缓存过期时间（毫秒），默认30天 */
+    cacheExpiry?: number;
+    /** 是否启用IndexedDB，默认true */
+    enableIndexedDB?: boolean;
+    /** 存储键名前缀 */
+    storageKeyPrefix?: string;
+    /** 当前版本号 */
+    version?: number;
+}
+
+/** HTTP Header 名称 */
+declare const HTTP_HEADER_NAME = "X-Device-Fingerprint";
+
+/**
+ * 设备指纹模块 - 主入口
+ *
+ * @description
+ * 独立、高内聚的设备指纹模块，便于复用到其他系统。
+ *
+ * @example
+ * ```typescript
+ * import { getDeviceFingerprint, initFingerprint } from 'src/utils/fingerprint';
+ *
+ * // 方式1: 使用默认配置
+ * const fp = await getDeviceFingerprint();
+ * console.log(fp.fingerprint); // 32位MD5哈希
+ *
+ * // 方式2: 自定义配置
+ * initFingerprint({
+ *   cacheExpiry: 7 * 24 * 60 * 60 * 1000, // 7天
+ *   storageKeyPrefix: 'myapp',
+ * });
+ * const fp2 = await getDeviceFingerprint();
+ * ```
+ *
+ * @author IDaaS Team
+ * @version 1.0.0
+ */
+
+/**
+ * 初始化指纹模块（可选）
+ * @param config 配置选项
+ */
+declare function initFingerprint(config?: FingerprintConfig): void;
+/**
+ * 获取设备指纹
+ * @returns 指纹结果
+ */
+declare function getDeviceFingerprint(): Promise<FingerprintResult>;
+/**
+ * 获取指纹值（简化版，仅返回哈希字符串）
+ * @returns 32位MD5哈希字符串
+ */
+declare function getFingerprint(): Promise<string>;
+/**
+ * 强制刷新指纹
+ * @returns 新的指纹结果
+ */
+declare function refreshFingerprint(): Promise<FingerprintResult>;
+/**
+ * 清除指纹缓存
+ */
+declare function clearFingerprint(): Promise<void>;
+/**
+ * 获取HTTP Header名称
+ */
+declare function getHeaderName(): string;
+
+export { type FingerprintConfig, type FingerprintResult, HTTP_HEADER_NAME, clearFingerprint, getDeviceFingerprint, getFingerprint, getHeaderName, initFingerprint, refreshFingerprint };