@vigilkids/device-fingerprint 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present VigilKids
+
+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,99 @@
+# @vigilkids/device-fingerprint
+
+Browser device fingerprint and platform standard client headers for VigilKids / Visiva frontend applications. Built on [FingerprintJS v4](https://github.com/nicknisi/fingerprintjs) (MIT, open-source).
+
+## Features
+
+- **Deterministic fingerprint** — same hash in normal and incognito mode (canvas/webgl/audio signals)
+- **Memory-only cache** — no cookie/localStorage dependency, recomputes on page load (~50ms)
+- **Platform headers** — generates `X-Device-ID`, `X-Client-Type`, `X-Client-Platform`, `X-Product-Code` headers
+- **Multi-product** — works with any VigilKids product (`vigilkids`, `visiva`, etc.)
+
+## Install
+
+```bash
+pnpm add @vigilkids/device-fingerprint
+```
+
+## Usage
+
+### Client Headers (recommended)
+
+Most use cases only need `getClientHeaders` — it computes the fingerprint internally and returns all standard headers:
+
+```typescript
+import { getClientHeaders } from '@vigilkids/device-fingerprint'
+
+const headers = await getClientHeaders({
+  productCode: 'visiva',
+  appVersion: '1.0.0',  // optional
+})
+// {
+//   'X-Device-ID': 'a1b2c3d4e5f6...',
+//   'X-Client-Type': 'web',
+//   'X-Client-Platform': 'web',
+//   'X-Product-Code': 'visiva',
+//   'X-Client-Version': '1.0.0',
+// }
+```
+
+### Raw Fingerprint
+
+For direct access to the fingerprint result:
+
+```typescript
+import { getDeviceFingerprint } from '@vigilkids/device-fingerprint'
+
+const { visitorId, confidence } = await getDeviceFingerprint()
+// visitorId: hex string (FingerprintJS hash)
+// confidence: 0-1 (higher = more reliable)
+```
+
+### Reset Cache
+
+Force recomputation on next call (typically not needed):
+
+```typescript
+import { resetFingerprint } from '@vigilkids/device-fingerprint'
+
+resetFingerprint()
+```
+
+## Exports
+
+| Entry Point | Import | Content |
+|-------------|--------|---------|
+| Main | `@vigilkids/device-fingerprint` | `getDeviceFingerprint`, `getClientHeaders`, `resetFingerprint` |
+| Types | `@vigilkids/device-fingerprint/types` | `DeviceFingerprintResult`, `ClientHeaderOptions` |
+
+## How It Works
+
+```
+getClientHeaders()
+  └─ getDeviceFingerprint()
+       └─ FingerprintJS.load()  → agent (singleton, cached)
+            └─ agent.get()      → { visitorId, confidence }
+                                    ↓ (memory cache)
+       └─ return cached result
+  └─ build headers map with X-Device-ID = visitorId
+```
+
+The fingerprint is computed from browser hardware signals (canvas rendering, WebGL renderer, audio context, etc.). These signals are consistent across normal and incognito sessions on the same device/browser combination.
+
+## Backend Integration
+
+The generated headers are consumed by the OneX backend middleware chain:
+
+1. `ClientContextMiddleware` extracts `X-Device-ID` → `ClientContext.DeviceID`
+2. `SessionService.Create()` stores `DeviceID` in `p_identity_sessions.device_id`
+3. Audit and promotion modules use the device ID for logging and fraud analysis
+
+## Compatibility
+
+- Browser only (requires `window`, `document`, `canvas`)
+- ESM only
+- TypeScript >= 5.0
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+import { DeviceFingerprintResult, ClientHeaderOptions } from './types.mjs';
+
+/**
+ * 获取当前设备的指纹
+ *
+ * 首次调用会计算指纹（~50ms），后续调用返回内存缓存。
+ * 无痕模式下产生相同 hash（基于 canvas/webgl/audio 等硬件信号，不依赖 cookie/storage）。
+ *
+ * @throws 当浏览器环境不支持指纹计算时抛出错误（不使用随机 fallback）
+ */
+declare function getDeviceFingerprint(): Promise<DeviceFingerprintResult>;
+/**
+ * 清除内存缓存，强制下次调用重新计算
+ *
+ * 一般不需要调用。仅用于测试或特殊场景（如检测到硬件变更）。
+ */
+declare function resetFingerprint(): void;
+
+/**
+ * 生成平台标准客户端请求头
+ *
+ * 所有前端站点的 API 请求应携带这些 header，供后端：
+ * - Identity 模块：记录设备信息到 session
+ * - Audit 模块：记录访问日志
+ * - Promotion 模块：防欺诈分析
+ *
+ * @example
+ * ```ts
+ * const headers = await getClientHeaders({ productCode: 'visiva' })
+ * // 结果:
+ * // {
+ * //   'X-Device-ID': 'a1b2c3d4e5f6...',
+ * //   'X-Client-Type': 'web',
+ * //   'X-Client-Platform': 'web',
+ * //   'X-Product-Code': 'visiva',
+ * // }
+ * ```
+ */
+declare function getClientHeaders(options: ClientHeaderOptions): Promise<Record<string, string>>;
+
+export { ClientHeaderOptions, DeviceFingerprintResult, getClientHeaders, getDeviceFingerprint, resetFingerprint };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { DeviceFingerprintResult, ClientHeaderOptions } from './types.js';
+
+/**
+ * 获取当前设备的指纹
+ *
+ * 首次调用会计算指纹（~50ms），后续调用返回内存缓存。
+ * 无痕模式下产生相同 hash（基于 canvas/webgl/audio 等硬件信号，不依赖 cookie/storage）。
+ *
+ * @throws 当浏览器环境不支持指纹计算时抛出错误（不使用随机 fallback）
+ */
+declare function getDeviceFingerprint(): Promise<DeviceFingerprintResult>;
+/**
+ * 清除内存缓存，强制下次调用重新计算
+ *
+ * 一般不需要调用。仅用于测试或特殊场景（如检测到硬件变更）。
+ */
+declare function resetFingerprint(): void;
+
+/**
+ * 生成平台标准客户端请求头
+ *
+ * 所有前端站点的 API 请求应携带这些 header，供后端：
+ * - Identity 模块：记录设备信息到 session
+ * - Audit 模块：记录访问日志
+ * - Promotion 模块：防欺诈分析
+ *
+ * @example
+ * ```ts
+ * const headers = await getClientHeaders({ productCode: 'visiva' })
+ * // 结果:
+ * // {
+ * //   'X-Device-ID': 'a1b2c3d4e5f6...',
+ * //   'X-Client-Type': 'web',
+ * //   'X-Client-Platform': 'web',
+ * //   'X-Product-Code': 'visiva',
+ * // }
+ * ```
+ */
+declare function getClientHeaders(options: ClientHeaderOptions): Promise<Record<string, string>>;
+
+export { ClientHeaderOptions, DeviceFingerprintResult, getClientHeaders, getDeviceFingerprint, resetFingerprint };

package/dist/index.mjs

@@ -0,0 +1,41 @@
+import FingerprintJS from '@fingerprintjs/fingerprintjs';
+
+let agentPromise = null;
+let cachedResult = null;
+function getAgent() {
+  if (!agentPromise) {
+    agentPromise = FingerprintJS.load();
+  }
+  return agentPromise;
+}
+async function getDeviceFingerprint() {
+  if (cachedResult) {
+    return cachedResult;
+  }
+  const agent = await getAgent();
+  const result = await agent.get();
+  cachedResult = {
+    visitorId: result.visitorId,
+    confidence: result.confidence.score
+  };
+  return cachedResult;
+}
+function resetFingerprint() {
+  cachedResult = null;
+}
+
+async function getClientHeaders(options) {
+  const fp = await getDeviceFingerprint();
+  const headers = {
+    "X-Device-ID": fp.visitorId,
+    "X-Client-Type": "web",
+    "X-Client-Platform": "web",
+    "X-Product-Code": options.productCode
+  };
+  if (options.appVersion) {
+    headers["X-Client-Version"] = options.appVersion;
+  }
+  return headers;
+}
+
+export { getClientHeaders, getDeviceFingerprint, resetFingerprint };

package/dist/types.d.mts

@@ -0,0 +1,21 @@
+/**
+ * 设备指纹计算结果
+ *
+ * visitorId 基于浏览器硬件信号（canvas/webgl/audio）计算，
+ * 同一浏览器+硬件在正常和无痕模式下产生相同 hash。
+ */
+interface DeviceFingerprintResult {
+    /** 设备指纹 hash（十六进制字符串，由 FingerprintJS 生成） */
+    visitorId: string;
+    /** 指纹置信度 0-1（越高越可靠） */
+    confidence: number;
+}
+/** 平台标准请求头（所有 API 请求携带） */
+interface ClientHeaderOptions {
+    /** 产品标识（如 'visiva', 'vigilkids'） */
+    productCode: string;
+    /** 客户端版本号 */
+    appVersion?: string;
+}
+
+export type { ClientHeaderOptions, DeviceFingerprintResult };

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 设备指纹计算结果
+ *
+ * visitorId 基于浏览器硬件信号（canvas/webgl/audio）计算，
+ * 同一浏览器+硬件在正常和无痕模式下产生相同 hash。
+ */
+interface DeviceFingerprintResult {
+    /** 设备指纹 hash（十六进制字符串，由 FingerprintJS 生成） */
+    visitorId: string;
+    /** 指纹置信度 0-1（越高越可靠） */
+    confidence: number;
+}
+/** 平台标准请求头（所有 API 请求携带） */
+interface ClientHeaderOptions {
+    /** 产品标识（如 'visiva', 'vigilkids'） */
+    productCode: string;
+    /** 客户端版本号 */
+    appVersion?: string;
+}
+
+export type { ClientHeaderOptions, DeviceFingerprintResult };

package/dist/types.mjs

@@ -0,0 +1 @@
+

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@vigilkids/device-fingerprint",
+  "version": "0.1.0",
+  "description": "Browser device fingerprint and platform standard client headers for VigilKids frontend applications",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "unbuild"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1yhy/onex.git",
+    "directory": "packages/device-fingerprint"
+  },
+  "keywords": [
+    "device-fingerprint",
+    "fingerprintjs",
+    "browser-fingerprint",
+    "client-headers",
+    "vigilkids"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@fingerprintjs/fingerprintjs": "^4.6.1"
+  },
+  "devDependencies": {
+    "unbuild": "^3.5.0"
+  }
+}