stable-deviceid 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qirly
+
+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,192 @@
+# stable-deviceid
+
+跨端一致的现代浏览器设备身份库。为 Web 应用提供**稳定、可自愈、隐私友好**的设备标识：
+结构化稳定设备 ID（生成 / 校验 / 自愈）、canvas + WebGL 设备指纹（默认关闭）、
+HTTP 响应头身份同步、SSO 跨 origin 身份归一、axios 一站式接入。
+
+> 设计目标：设备 ID 一经生成终身复用——用户清除缓存可自动恢复（httpOnly cookie 兜底）、
+> 时钟偏差不引起身份漂移（±5 分钟容差）、多标签页实时同步、同设备跨应用（SSO iframe）归一为同一身份。
+
+## 特性
+
+- 🆔 **结构化设备 ID**：`{PLATFORM}-{ENCODED_TS}-{RANDOM}`（如 `WEB-DaBOSbNdSuc-8s4T`），
+  时间戳位混淆 + Base62 编码 + 高熵随机后缀（`crypto.getRandomValues` 拒绝采样）
+- 🔁 **自愈能力**：损坏 / 老格式 / 过期 / 未来时间的存量 ID 自动重生；服务端校验失败自动收敛（一轮往返）
+- 🔄 **响应头同步**：服务端可下发权威 ID（`X-Device-Id`），客户端写回后下一请求立即生效
+- 🧩 **SSO 跨 origin 归一**：oauth21 式 iframe 登录场景，子应用采纳权威域 ID，同物理设备全端同身份
+- 🛡 **安全内建**：与后端校验规则逐条对齐、脏值拒绝、超长头忽略、日志截断、SSO 消息双重校验
+- 🤫 **隐私友好**：设备指纹默认关闭，需显式启用；存储层静默降级，不抛异常
+- 📦 **零依赖**：ESM-only、tree-shaking 友好（`sideEffects: false`）、TypeScript 类型完备
+
+## 安装
+
+```bash
+npm install stable-deviceid
+```
+
+要求 Node.js >= 18（仅构建环境；运行时为现代浏览器）。
+
+## 快速开始
+
+### axios 一站式接入（推荐）
+
+```ts
+import axios from 'axios';
+import { setupDeviceSync } from 'stable-deviceid';
+
+const http = axios.create({ baseURL: '/api', withCredentials: true });
+setupDeviceSync(http);
+```
+
+`setupDeviceSync` 自动完成：
+
+1. 请求拦截器注入 `x-device-id` 头（内存缓存直读，近乎零开销）
+2. 按需注入设备指纹头 `x-device-fp`（默认按环境判定，见下方指纹开关）
+3. 响应拦截器同步服务端下发的设备 ID（写回存储 + 失效内存缓存）
+4. 注册跨标签页 storage 监听（幂等）
+
+```ts
+// 可选配置
+setupDeviceSync(http, {
+  fingerprint: true,                    // 强制开启指纹（默认按 meta/env 判定）
+  onDeviceIdChange: (oldId, newId) => { /* 设备 ID 变更回调 */ }
+});
+
+// dispose：卸载拦截器（HMR / 单测场景）
+const dispose = setupDeviceSync(http);
+dispose();
+```
+
+### 原生 fetch / 显式带头
+
+```ts
+import { getDeviceHeaders } from 'stable-deviceid';
+
+fetch('/api/profile', { headers: { ...getDeviceHeaders() } });
+```
+
+### 手动拦截器（细粒度控制）
+
+```ts
+import {
+  getStableDeviceId,          // 稳定设备 ID（持久化 + 内存缓存）
+  getDeviceFingerprint,       // 设备指纹（异步，32 位 hex）
+  isDeviceFingerprintEnabled, // 指纹开关判定
+  handleDeviceSyncInResponse, // 响应头同步（传 axios response）
+  initDeviceSync              // 全局初始化（跨标签页监听，幂等）
+} from 'stable-deviceid';
+
+http.interceptors.request.use(async config => {
+  config.headers['x-device-id'] = getStableDeviceId();
+  if (isDeviceFingerprintEnabled()) {
+    try {
+      config.headers['x-device-fp'] = await getDeviceFingerprint();
+    } catch { /* 采集失败不影响主流程 */ }
+  }
+  return config;
+});
+
+http.interceptors.response.use(response => {
+  handleDeviceSyncInResponse(response);
+  return response;
+});
+```
+
+## API 一览
+
+| 导出 | 说明 |
+| --- | --- |
+| `setupDeviceSync(instance, options?)` | 一站式接入（axios），返回 dispose 函数 |
+| `getDeviceHeaders()` | 同步返回 `{ 'x-device-id': id }`，供 fetch / 显式带头 |
+| `getStableDeviceId()` | 稳定设备 ID（首次生成，之后持久复用） |
+| `getCurrentDeviceId()` / `setDeviceId(id)` / `clearDeviceId()` | 读取 / 校验写入 / 清除（均含格式校验） |
+| `adoptDeviceId(id)` | 采纳 SSO 权威域下发的 ID（格式 + 平台段双校验，跨 origin 归一） |
+| `validateDeviceIdFormat(id)` | 本地格式校验（返回 `{ valid, reason? }`） |
+| `parseDeviceId(id)` | 解析 ID 信息（platform / timestamp / age），非法返回 null |
+| `syncDeviceFromHeaders(headers, options?)` | 从响应头同步（兼容 Headers / AxiosHeaders / 普通对象） |
+| `handleDeviceSyncInResponse(response, options?)` | 响应拦截器集成（axios / fetch Response 均可） |
+| `initDeviceSync(options?)` | 全局初始化：跨标签页监听 + 变更回调（幂等） |
+| `getDeviceFingerprint()` / `isDeviceFingerprintEnabled()` | 指纹采集（Promise 缓存、并发去重）与开关判定 |
+| `sha256(message)` | SHA-256（Web Crypto 优先，非安全上下文自动降级纯 JS） |
+| `getDeviceIdStats()` | 调试统计（当前 ID / 解析信息 / 来源） |
+
+常量：`STORAGE_KEY`、`MAX_AGE_DAYS`（365）、`CLOCK_SKEW_TOLERANCE_MS`（±5 分钟）、
+`DEVICE_PLATFORMS`、`RANDOM_SUFFIX_LENGTH`。
+
+## SSO 跨 origin 身份归一
+
+iframe 嵌入 SSO 登录页（如 oauth21）时，登录成功消息中携带权威域设备 ID，
+子应用在 bindSession 之前采纳，同物理设备即归一为同一身份：
+
+```ts
+window.addEventListener('message', event => {
+  // 务必校验 event.origin 与 event.source（示例省略）
+  if (event.data?.type === 'LOGIN_SUCCESS' && event.data.deviceId) {
+    adoptDeviceId(event.data.deviceId); // 包内做格式 + 平台段双校验
+  }
+});
+```
+
+## 设备指纹（默认关闭，隐私友好）
+
+```html
+<!-- 方式一：后端/模板注入 meta 开关 -->
+<meta name="device-fp" content="true" />
+```
+
+```bash
+# 方式二：Vite 环境变量
+VITE_DEVICE_FINGERPRINT=true
+```
+
+```ts
+// 方式三：代码强制指定（非 Vite 构建器推荐）
+setupDeviceSync(http, { fingerprint: true });
+```
+
+采集维度：canvas 渲染差异 + WebGL renderer/vendor，SHA-256 取前 32 位 hex，
+进程内 Promise 缓存（并发去重、双失败返回空串而非常量哈希，防误匹配）。
+
+## 安全设计
+
+- **前后端校验对齐**：格式校验与后端 `validateDeviceId` 逐条一致（平台枚举 /
+  长度 / Base62 字符集 / 拒绝超容差未来时间 / 365 天有效期），存量非法 ID 本地即重生
+- **脏输入防御**：响应头超 128 字符忽略、日志截断外部输入、`setDeviceId` 入口校验
+- **缓存一致性**：任何来源的 ID 写入后立即失效内存缓存，下一请求即生效
+- **隐私模式降级**：存储不可用时静默降级内存层（会话内稳定），不抛异常不中断请求链路
+
+## 在 nodeServers monorepo 内开发
+
+workspace 内前端（oauth21 / firewall / posecraft）通过 vite alias 直连源码消费：
+
+```ts
+// vite.config.ts
+resolve: { alias: { stable-deviceid: fileURLToPath(new URL('../packages/shared-device/src/index.ts', import.meta.url)) } }
+```
+
+```json
+// tsconfig.json
+"paths": { "stable-deviceid": ["../packages/shared-device/src/index.ts"], "stable-deviceid/*": ["../packages/shared-device/src/*"] },
+"include": ["src/**/*.ts", "../packages/shared-device/src/**/*.ts"]
+```
+
+`package.json` dependencies 中 `"stable-deviceid": "*"` 供 workspace 链接。
+
+## 构建与发布（维护者）
+
+```bash
+cd packages/shared-device
+npm run build     # esbuild 逐模块转换 → dist/ + tsc 产出 index.d.ts
+npm publish       # prepack 自动构建；ESM-only，access: public
+```
+
+## 已知限制
+
+- 隐私模式下存储降级为会话内临时 ID，每次刷新变化（console.warn 告警）
+- `isDeviceFingerprintEnabled` 依赖 `import.meta.env`（Vite）与 DOM；非 Vite 消费方请用 meta 标签或 `fingerprint` 选项
+- `crypto.getRandomValues` 不可用的极旧浏览器以 `Math.random` 生成随机后缀（告警提示）
+- Safari ITP 会清除脚本可写存储，需配合服务端 httpOnly cookie 兜底恢复机制使用
+
+## License
+
+[MIT](./LICENSE) © 2026 qirly

package/dist/base62-timestamp.d.ts

@@ -0,0 +1,23 @@
+/**
+ * base62-timestamp.js 的类型声明（实现为纯 JS，供浏览器与 Jest 共用）
+ */
+
+/** 混淆时间戳为 Base62 字符串，返回 11 字符 */
+export declare function encodeTimestamp(timestamp: number): string;
+
+/** 解码 Base62 字符串为毫秒时间戳，含非法字符时抛错 */
+export declare function decodeTimestamp(encoded: string): number;
+
+/** 数字转 Base62 字符串（支持 BigInt） */
+export declare function toBase62(num: number | bigint): string;
+
+/** Base62 字符串转数字（BigInt），含非法字符时抛错 */
+export declare function fromBase62(str: string): bigint;
+
+export declare const BASE62_CHARS: string;
+
+export declare const ENCODED_TS_LENGTH: number;
+
+export declare const TS_OFFSET: bigint;
+
+export declare const TS_MAGIC: bigint;

package/dist/base62-timestamp.js

@@ -0,0 +1,45 @@
+const BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const ENCODED_TS_LENGTH = 11;
+const TS_OFFSET = 1704067200000n;
+const TS_MAGIC = 0x9e3779b97f4a7c15n;
+function toBase62(num) {
+  const n = typeof num === "bigint" ? num : BigInt(num);
+  if (n === 0n) return "0";
+  let result = "";
+  let remaining = n;
+  while (remaining > 0n) {
+    result = BASE62_CHARS[Number(remaining % 62n)] + result;
+    remaining = remaining / 62n;
+  }
+  return result;
+}
+function fromBase62(str) {
+  let result = 0n;
+  for (let i = 0; i < str.length; i++) {
+    const value = BASE62_CHARS.indexOf(str[i]);
+    if (value === -1) throw new Error(`Invalid Base62 character: ${str[i]}`);
+    result = result * 62n + BigInt(value);
+  }
+  return result;
+}
+function encodeTimestamp(timestamp) {
+  const adjusted = BigInt(timestamp) - TS_OFFSET;
+  const obfuscated = adjusted ^ TS_MAGIC;
+  const encoded = toBase62(obfuscated);
+  return encoded.padStart(ENCODED_TS_LENGTH, "0");
+}
+function decodeTimestamp(encoded) {
+  const obfuscated = fromBase62(encoded);
+  const adjusted = obfuscated ^ TS_MAGIC;
+  return Number(adjusted + TS_OFFSET);
+}
+export {
+  BASE62_CHARS,
+  ENCODED_TS_LENGTH,
+  TS_MAGIC,
+  TS_OFFSET,
+  decodeTimestamp,
+  encodeTimestamp,
+  fromBase62,
+  toBase62
+};

package/dist/device-fingerprint.d.ts

@@ -0,0 +1,15 @@
+/**
+ * device-fingerprint.js 的类型声明（实现为纯 JS，供浏览器与 Jest 共用）
+ */
+
+/**
+ * 采集完整设备指纹（canvas + WebGL 合并后 SHA-256，取前 32 位 hex）
+ * 结果进程内缓存，并发调用去重；两者均采集失败返回空串
+ */
+export declare function getDeviceFingerprint(): Promise<string>;
+
+/**
+ * 是否启用设备指纹（页面 meta[name=device-fp]=true 或
+ * VITE_DEVICE_FINGERPRINT=true），默认不启用
+ */
+export declare function isDeviceFingerprintEnabled(): boolean;

package/dist/device-fingerprint.js

@@ -0,0 +1,66 @@
+import { sha256 } from "./sha256.js";
+let fingerprintPromise = null;
+async function canvasFingerprint() {
+  try {
+    const canvas = document.createElement("canvas");
+    canvas.width = 240;
+    canvas.height = 60;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return "";
+    ctx.textBaseline = "top";
+    ctx.font = "14px 'Arial'";
+    ctx.fillStyle = "#f60";
+    ctx.fillRect(0, 0, 100, 30);
+    ctx.fillStyle = "#069";
+    ctx.fillText("CoreFlow device fingerprint \u{1F310}", 2, 2);
+    ctx.fillStyle = "rgba(102,204,0,0.7)";
+    ctx.fillText("CoreFlow device fingerprint \u{1F310}", 4, 4);
+    const dataUrl = canvas.toDataURL();
+    return await sha256(dataUrl);
+  } catch {
+    return "";
+  }
+}
+async function webglFingerprint() {
+  try {
+    const canvas = document.createElement("canvas");
+    const gl = canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
+    if (!gl) return "";
+    const debugInfo = gl.getExtension("WEBGL_debug_renderer_info");
+    if (!debugInfo) return "";
+    const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL) || "";
+    const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL) || "";
+    return `${vendor}|${renderer}`;
+  } catch {
+    return "";
+  }
+}
+function getDeviceFingerprint() {
+  if (!fingerprintPromise) {
+    fingerprintPromise = collectFingerprint();
+  }
+  return fingerprintPromise;
+}
+async function collectFingerprint() {
+  const [canvas, webgl] = await Promise.all([canvasFingerprint(), webglFingerprint()]);
+  if (!canvas && !webgl) {
+    return "";
+  }
+  const hash = await sha256(`${canvas}|${webgl}`);
+  return hash.slice(0, 32);
+}
+function isDeviceFingerprintEnabled() {
+  if (typeof document === "undefined") return false;
+  const meta = document.querySelector('meta[name="device-fp"]')?.getAttribute("content");
+  if (meta === "true") return true;
+  const env = import.meta.env || {};
+  return env.VITE_DEVICE_FINGERPRINT === "true";
+}
+function __resetFingerprintForTest() {
+  fingerprintPromise = null;
+}
+export {
+  __resetFingerprintForTest,
+  getDeviceFingerprint,
+  isDeviceFingerprintEnabled
+};

package/dist/device-id.d.ts

@@ -0,0 +1,50 @@
+/**
+ * device-id.js 的类型声明（实现为纯 JS，供浏览器与 Jest 共用）
+ */
+
+/** 设备 ID 在 localStorage 的存储键 */
+export declare const STORAGE_KEY: string;
+
+/** 设备 ID 最长有效期（天），与后端一致 */
+export declare const MAX_AGE_DAYS: number;
+
+/** 合法平台枚举 */
+export declare const DEVICE_PLATFORMS: readonly ['WEB', 'IOS', 'ANDROID'];
+
+/** 随机后缀长度（6 字符 Base62） */
+export declare const RANDOM_SUFFIX_LENGTH: number;
+
+/** 时钟偏差容差（毫秒，±5 分钟），与后端 CLOCK_SKEW_TOLERANCE_MS 一致 */
+export declare const CLOCK_SKEW_TOLERANCE_MS: number;
+
+/** 获取稳定 device_id（持久化 + 内存缓存，首次生成结构化 ID） */
+export declare function getStableDeviceId(): string;
+
+/** 使内存缓存的设备 ID 失效（下次 getStableDeviceId 重新读存储） */
+export declare function invalidateCachedDeviceId(): void;
+
+/**
+ * 校验设备 ID 格式（与后端 validateDeviceId 逐条对齐，同步版）
+ */
+export declare function validateDeviceIdFormat(deviceId: string): {
+  valid: boolean;
+  reason?: string;
+};
+
+/** 检测设备平台（与后端 detectPlatform 同规则） */
+export declare function getPlatform(): 'WEB' | 'IOS' | 'ANDROID';
+
+/** 设备 ID 解析结果 */
+export interface DeviceIdInfo {
+  platform: string;
+  timestamp: number;
+  createdAt: Date;
+  /** 距今天数 */
+  age: number;
+}
+
+/** 调试工具：解析设备 ID 信息（宽松解析），非法返回 null */
+export declare function parseDeviceId(deviceId: string): DeviceIdInfo | null;
+
+/** 解码 Base64 时间戳段为毫秒时间戳（转发自 base62-timestamp） */
+export declare function decodeTimestamp(encoded: string): number;

package/dist/device-id.js

@@ -0,0 +1,142 @@
+import { BASE62_CHARS, ENCODED_TS_LENGTH, encodeTimestamp, decodeTimestamp } from "./base62-timestamp.js";
+import { safeGetItem, safeSetItem, safeRemoveItem } from "./storage.js";
+const STORAGE_KEY = "cf_device_id";
+const MAX_AGE_DAYS = 365;
+const DEVICE_PLATFORMS = ["WEB", "IOS", "ANDROID"];
+const RANDOM_SUFFIX_LENGTH = 6;
+const CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1e3;
+let cachedId = null;
+function getStableDeviceId() {
+  if (cachedId) return cachedId;
+  let id = safeGetItem(STORAGE_KEY);
+  if (!isUsableDeviceId(id)) {
+    if (id) {
+      safeRemoveItem(STORAGE_KEY);
+    }
+    id = generateStructuredDeviceId();
+    safeSetItem(STORAGE_KEY, id);
+  }
+  cachedId = /** @type {string} */
+  id;
+  return cachedId;
+}
+function invalidateCachedDeviceId() {
+  cachedId = null;
+}
+function validateDeviceIdFormat(deviceId) {
+  if (typeof deviceId !== "string" || !deviceId) {
+    return { valid: false, reason: "\u7A7A\u503C\u6216\u975E\u5B57\u7B26\u4E32" };
+  }
+  if (deviceId.length > 64) {
+    return { valid: false, reason: "\u8D85\u957F" };
+  }
+  const parts = deviceId.split("-");
+  if (parts.length !== 3) {
+    return { valid: false, reason: "\u683C\u5F0F\u9519\u8BEF\uFF1A\u5E94\u4E3A PLATFORM-ENCODED_TS-RANDOM" };
+  }
+  const [platform, encodedTs, randomSuffix] = parts;
+  if (!DEVICE_PLATFORMS.includes(platform)) {
+    return { valid: false, reason: `\u65E0\u6548\u5E73\u53F0\uFF1A${platform}` };
+  }
+  if (encodedTs.length !== ENCODED_TS_LENGTH) {
+    return { valid: false, reason: `\u65F6\u95F4\u6233\u957F\u5EA6\u9519\u8BEF\uFF1A\u5E94\u4E3A ${ENCODED_TS_LENGTH}` };
+  }
+  if (randomSuffix.length !== RANDOM_SUFFIX_LENGTH) {
+    return { valid: false, reason: `\u968F\u673A\u540E\u7F00\u957F\u5EA6\u9519\u8BEF\uFF1A\u5E94\u4E3A ${RANDOM_SUFFIX_LENGTH}` };
+  }
+  if (!isBase62(encodedTs) || !isBase62(randomSuffix)) {
+    return { valid: false, reason: "\u5305\u542B\u975E\u6CD5\u5B57\u7B26\uFF08\u4EC5\u652F\u6301 0-9A-Za-z\uFF09" };
+  }
+  let timestamp;
+  try {
+    timestamp = decodeTimestamp(encodedTs);
+  } catch {
+    return { valid: false, reason: "\u65F6\u95F4\u6233\u89E3\u7801\u5931\u8D25" };
+  }
+  if (!Number.isFinite(timestamp)) {
+    return { valid: false, reason: "\u65F6\u95F4\u6233\u89E3\u7801\u7ED3\u679C\u975E\u6CD5" };
+  }
+  const now = Date.now();
+  if (timestamp > now + CLOCK_SKEW_TOLERANCE_MS) {
+    return { valid: false, reason: "\u65E0\u6548\u65F6\u95F4\u6233\uFF08\u672A\u6765\u65F6\u95F4\uFF09" };
+  }
+  const ageDays = Math.floor((now - timestamp) / (1e3 * 60 * 60 * 24));
+  if (ageDays > MAX_AGE_DAYS) {
+    return { valid: false, reason: `\u8BBE\u5907 ID \u5DF2\u8FC7\u671F\uFF08\u8D85\u8FC7 ${MAX_AGE_DAYS} \u5929\uFF09` };
+  }
+  return { valid: true };
+}
+function isUsableDeviceId(id) {
+  if (!id) return false;
+  return validateDeviceIdFormat(id).valid;
+}
+function generateStructuredDeviceId() {
+  const platform = getPlatform();
+  const now = Date.now();
+  const encodedTs = encodeTimestamp(now);
+  const randomSuffix = generateBase62Random(RANDOM_SUFFIX_LENGTH);
+  return `${platform}-${encodedTs}-${randomSuffix}`;
+}
+function getPlatform() {
+  const ua = typeof navigator !== "undefined" ? navigator.userAgent.toLowerCase() : "";
+  if (/ipad|iphone|ipod/.test(ua)) return "IOS";
+  if (/android/.test(ua)) return "ANDROID";
+  return "WEB";
+}
+function generateBase62Random(length) {
+  if (typeof crypto === "undefined" || typeof crypto.getRandomValues !== "function") {
+    console.warn("\u26A0\uFE0F [DeviceId] crypto.getRandomValues \u4E0D\u53EF\u7528\uFF0C\u968F\u673A\u540E\u7F00\u964D\u7EA7\u4E3A Math.random\uFF08\u71B5\u964D\u4F4E\uFF09");
+    let fallback = "";
+    while (fallback.length < length) {
+      fallback += BASE62_CHARS[Math.floor(Math.random() * BASE62_CHARS.length)];
+    }
+    return fallback;
+  }
+  const maxUsable = Math.floor(256 / BASE62_CHARS.length) * BASE62_CHARS.length;
+  let result = "";
+  while (result.length < length) {
+    const batch = new Uint8Array(length * 2);
+    crypto.getRandomValues(batch);
+    for (let i = 0; i < batch.length && result.length < length; i++) {
+      if (batch[i] < maxUsable) {
+        result += BASE62_CHARS[batch[i] % BASE62_CHARS.length];
+      }
+    }
+  }
+  return result;
+}
+function parseDeviceId(deviceId) {
+  try {
+    const parts = deviceId.split("-");
+    if (parts.length !== 3) return null;
+    const [platform, encodedTs] = parts;
+    if (encodedTs.length !== ENCODED_TS_LENGTH) return null;
+    const timestamp = decodeTimestamp(encodedTs);
+    const createdAt = new Date(timestamp);
+    const age = (Date.now() - timestamp) / (1e3 * 60 * 60 * 24);
+    return {
+      platform,
+      timestamp,
+      createdAt,
+      age: Math.floor(age)
+    };
+  } catch {
+    return null;
+  }
+}
+function isBase62(str) {
+  return /^[0-9A-Za-z]+$/.test(str);
+}
+export {
+  CLOCK_SKEW_TOLERANCE_MS,
+  DEVICE_PLATFORMS,
+  MAX_AGE_DAYS,
+  RANDOM_SUFFIX_LENGTH,
+  STORAGE_KEY,
+  decodeTimestamp,
+  getPlatform,
+  getStableDeviceId,
+  invalidateCachedDeviceId,
+  parseDeviceId,
+  validateDeviceIdFormat
+};

package/dist/device-setup.d.ts

@@ -0,0 +1,40 @@
+/**
+ * device-setup.js 的类型声明（实现为纯 JS，供浏览器与 Jest 共用）
+ */
+
+import type { DeviceSyncOptions } from './device-sync.js';
+
+/** 最小 axios 实例结构（真 axios 实例结构兼容可直接传入） */
+export interface AxiosLikeInstance {
+  interceptors: {
+    request: {
+      use(onFulfilled: (config: any) => any): number;
+      eject(id: number): void;
+    };
+    response: {
+      use(onFulfilled: (response: any) => any): number;
+      eject(id: number): void;
+    };
+  };
+}
+
+/** setupDeviceSync 配置项 */
+export interface SetupDeviceSyncOptions extends DeviceSyncOptions {
+  /**
+   * 设备指纹注入开关：true 强制注入；false 强制关闭；
+   * 缺省每请求按 isDeviceFingerprintEnabled()（meta 标签 / VITE_DEVICE_FINGERPRINT）判定
+   */
+  fingerprint?: boolean;
+}
+
+/**
+ * 一站式接入设备 ID 体系（axios 实例）：注册请求/响应拦截器 + 自动 initDeviceSync
+ * @returns dispose 函数：eject 本函数注册的拦截器
+ */
+export declare function setupDeviceSync(
+  axiosInstance: AxiosLikeInstance,
+  options?: SetupDeviceSyncOptions
+): () => void;
+
+/** 获取设备 ID 请求头（同步，供 fetch 场景与显式带头使用） */
+export declare function getDeviceHeaders(): { 'x-device-id': string };

package/dist/device-setup.js

@@ -0,0 +1,39 @@
+import { getStableDeviceId } from "./device-id.js";
+import { getDeviceFingerprint, isDeviceFingerprintEnabled } from "./device-fingerprint.js";
+import { handleDeviceSyncInResponse, initDeviceSync } from "./device-sync.js";
+const FP_HEADER = "x-device-fp";
+function setupDeviceSync(axiosInstance, options = {}) {
+  if (!axiosInstance || !axiosInstance.interceptors?.request?.use || !axiosInstance.interceptors?.response?.use) {
+    throw new TypeError("setupDeviceSync: \u9700\u8981\u4F20\u5165 axios \u5B9E\u4F8B\uFF08\u542B interceptors.request/response.use\uFF09");
+  }
+  initDeviceSync({ onDeviceIdChange: options.onDeviceIdChange });
+  const requestInterceptorId = axiosInstance.interceptors.request.use(async (config) => {
+    if (config.headers) {
+      config.headers["x-device-id"] = getStableDeviceId();
+      const fingerprintEnabled = options.fingerprint ?? isDeviceFingerprintEnabled();
+      if (fingerprintEnabled) {
+        try {
+          const fingerprint = await getDeviceFingerprint();
+          if (fingerprint) config.headers[FP_HEADER] = fingerprint;
+        } catch {
+        }
+      }
+    }
+    return config;
+  });
+  const responseInterceptorId = axiosInstance.interceptors.response.use((response) => {
+    handleDeviceSyncInResponse(response);
+    return response;
+  });
+  return function dispose() {
+    axiosInstance.interceptors.request.eject(requestInterceptorId);
+    axiosInstance.interceptors.response.eject(responseInterceptorId);
+  };
+}
+function getDeviceHeaders() {
+  return { "x-device-id": getStableDeviceId() };
+}
+export {
+  getDeviceHeaders,
+  setupDeviceSync
+};

package/dist/device-sync.d.ts

@@ -0,0 +1,73 @@
+/**
+ * device-sync.js 的类型声明（实现为纯 JS，供浏览器与 Jest 共用）
+ */
+
+/** 设备 ID 同步选项 */
+export interface DeviceSyncOptions {
+  /** 强制重新获取设备 ID */
+  forceRefresh?: boolean;
+  /** 设备 ID 变更回调 */
+  onDeviceIdChange?: (oldId: string, newId: string) => void;
+}
+
+/** 设备 ID 解析结果（转发自 device-id） */
+export interface DeviceIdInfo {
+  platform: string;
+  timestamp: number;
+  createdAt: Date;
+  age: number;
+}
+
+/** 获取当前设备 ID（从存储读取，隐私模式降级层也可读） */
+export declare function getCurrentDeviceId(): string | null;
+
+/**
+ * 设置设备 ID 并持久化到存储（入口校验，写后失效内存缓存）
+ * @returns 是否写入成功（非法格式拒绝写入返回 false）
+ */
+export declare function setDeviceId(deviceId: string): boolean;
+
+/**
+ * 采纳外部来源（SSO 握手）下发的权威设备 ID（跨 origin 身份归一）
+ *
+ * 双重校验（格式与后端对齐 + 平台段与本机 UA 一致）通过后走 setDeviceId。
+ * 调用方应在 bindSession/bindToken 之前调用，保证登录基准指纹与后续请求一致。
+ * @returns 是否采纳成功（校验失败返回 false，不改变本地状态）
+ */
+export declare function adoptDeviceId(deviceId: string): boolean;
+
+/**
+ * 从响应头同步设备 ID
+ * @param headers HTTP 响应头（Headers / AxiosHeaders / 普通对象）
+ * @param options 同步选项
+ * @returns 同步后的设备 ID；响应头无有效 ID 返回 null
+ */
+export declare function syncDeviceFromHeaders(
+  headers: unknown,
+  options?: DeviceSyncOptions
+): string | null;
+
+/** HTTP 响应拦截器集成（axios 响应对象 / fetch Response 均可），原样返回响应 */
+export declare function handleDeviceSyncInResponse<T>(response: T, options?: DeviceSyncOptions): T;
+
+/** 初始化设备 ID 全局配置（重复调用不会重复注册监听器） */
+export declare function initDeviceSync(options?: DeviceSyncOptions): void;
+
+/** 清除设备 ID（存储与内存缓存同步清除） */
+export declare function clearDeviceId(): void;
+
+/** 设备 ID 使用统计（调试用） */
+export declare function getDeviceIdStats(): {
+  id: string | null;
+  info: DeviceIdInfo | null;
+  source: 'localStorage' | 'none';
+};
+
+declare global {
+  interface Window {
+    /** 设备 ID 同步全局配置（initDeviceSync 写入） */
+    deviceSync?: {
+      onDeviceIdChange?: (oldId: string, newId: string) => void;
+    };
+  }
+}

package/dist/device-sync.js

@@ -0,0 +1,131 @@
+import {
+  getPlatform,
+  parseDeviceId,
+  validateDeviceIdFormat,
+  invalidateCachedDeviceId,
+  STORAGE_KEY
+} from "./device-id.js";
+import { safeGetItem, safeSetItem, safeRemoveItem } from "./storage.js";
+const MAX_HEADER_VALUE_LENGTH = 128;
+const MAX_LOG_LENGTH = 48;
+let storageListenerRegistered = false;
+function forLog(value) {
+  const safe = String(value);
+  return safe.length > MAX_LOG_LENGTH ? `${safe.slice(0, MAX_LOG_LENGTH)}\u2026` : safe;
+}
+function readHeader(headers, lowerName) {
+  if (typeof headers !== "object" || headers === null) return null;
+  let value;
+  if (typeof headers.get === "function") {
+    value = headers.get(lowerName);
+  } else {
+    const pascalName = lowerName.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("-");
+    value = headers[lowerName] ?? headers[pascalName];
+  }
+  if (value === null || value === void 0) return null;
+  const str = String(value);
+  if (str.length === 0 || str.length > MAX_HEADER_VALUE_LENGTH) return null;
+  return str;
+}
+function getCurrentDeviceId() {
+  return safeGetItem(STORAGE_KEY);
+}
+function setDeviceId(deviceId) {
+  const validation = validateDeviceIdFormat(deviceId);
+  if (!validation.valid) {
+    console.warn(`\u26A0\uFE0F [DeviceSync] \u62D2\u7EDD\u5199\u5165\u975E\u6CD5\u8BBE\u5907 ID\uFF08${validation.reason}\uFF09: ${forLog(deviceId)}`);
+    return false;
+  }
+  const oldId = getCurrentDeviceId();
+  safeSetItem(STORAGE_KEY, deviceId);
+  invalidateCachedDeviceId();
+  if (oldId && oldId !== deviceId && typeof window !== "undefined") {
+    window.deviceSync?.onDeviceIdChange?.(oldId, deviceId);
+  }
+  return true;
+}
+function adoptDeviceId(deviceId) {
+  const validation = validateDeviceIdFormat(deviceId);
+  if (!validation.valid) {
+    console.warn(`\u26A0\uFE0F [DeviceSync] \u62D2\u7EDD\u91C7\u7EB3\u975E\u6CD5\u8BBE\u5907 ID\uFF08${validation.reason}\uFF09: ${forLog(deviceId)}`);
+    return false;
+  }
+  const declaredPlatform = deviceId.split("-")[0];
+  const localPlatform = getPlatform();
+  if (declaredPlatform !== localPlatform) {
+    console.warn(`\u26A0\uFE0F [DeviceSync] \u62D2\u7EDD\u91C7\u7EB3\u5E73\u53F0\u4E0D\u4E00\u81F4\u7684\u8BBE\u5907 ID: ${forLog(declaredPlatform)} vs ${localPlatform}`);
+    return false;
+  }
+  return setDeviceId(deviceId);
+}
+function syncDeviceFromHeaders(headers, options = {}) {
+  const responseDeviceId = readHeader(headers, "x-device-id");
+  const hasDeviceIdUpdated = readHeader(headers, "x-device-id-updated");
+  if (!responseDeviceId) {
+    return null;
+  }
+  const parsed = parseDeviceId(responseDeviceId);
+  if (!parsed) {
+    console.warn(`\u26A0\uFE0F [DeviceSync] \u65E0\u6548\u7684\u8BBE\u5907 ID \u683C\u5F0F: ${forLog(responseDeviceId)}`);
+    return null;
+  }
+  const currentId = getCurrentDeviceId();
+  const shouldUpdate = options.forceRefresh || !currentId || currentId !== responseDeviceId || hasDeviceIdUpdated === "true";
+  if (shouldUpdate) {
+    setDeviceId(responseDeviceId);
+  }
+  return responseDeviceId;
+}
+function handleDeviceSyncInResponse(response, options) {
+  if (typeof window === "undefined" || !response?.headers) {
+    return response;
+  }
+  syncDeviceFromHeaders(response.headers, options);
+  return response;
+}
+function initDeviceSync(options = {}) {
+  window.deviceSync = {
+    onDeviceIdChange: options.onDeviceIdChange
+  };
+  if (storageListenerRegistered) return;
+  storageListenerRegistered = true;
+  window.addEventListener("storage", (event) => {
+    if (event.key === STORAGE_KEY && event.newValue && event.newValue !== event.oldValue) {
+      invalidateCachedDeviceId();
+      window.deviceSync?.onDeviceIdChange?.(event.oldValue ?? "", event.newValue);
+    }
+  });
+}
+function clearDeviceId() {
+  safeRemoveItem(STORAGE_KEY);
+  invalidateCachedDeviceId();
+}
+function getDeviceIdStats() {
+  const currentId = getCurrentDeviceId();
+  if (currentId) {
+    return {
+      id: currentId,
+      info: parseDeviceId(currentId),
+      source: "localStorage"
+    };
+  }
+  return {
+    id: null,
+    info: null,
+    source: "none"
+  };
+}
+function __resetDeviceSyncForTest() {
+  storageListenerRegistered = false;
+}
+export {
+  __resetDeviceSyncForTest,
+  adoptDeviceId,
+  clearDeviceId,
+  getCurrentDeviceId,
+  getDeviceIdStats,
+  handleDeviceSyncInResponse,
+  initDeviceSync,
+  setDeviceId,
+  syncDeviceFromHeaders
+};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 共享设备工具包入口
+ *
+ * 三前端（oauth21/posecraft/firewall）共用，保证 device_id 生成、传递、响应头同步逻辑一致。
+ *
+ * - device-id：稳定结构化设备 ID（localStorage 持久，跨账号复用）
+ * - device-fingerprint：canvas + WebGL 浏览器特征指纹（默认不启用）
+ * - device-sync：从响应头同步 device_id 到 localStorage
+ * - device-setup：一站式接入（axios 拦截器 + initDeviceSync，新前端 2 行接入）
+ * - sha256：Web Crypto API 哈希（非安全上下文降级纯 JS）
+ * - storage：localStorage 安全封装（隐私模式内存降级）
+ *
+ * 实现模块为纯 JS + 手写 .d.ts（根 Jest 纯 ESM 不编译 TS，需直接 import 测试），
+ * 本入口保持 TS 桶文件供 vite alias 消费。
+ *
+ * @author yijiu2025
+ * @since 2026-09-02
+ * @since 2026-09-04 补齐常量/校验/类型导出；实现层迁移为 .js + .d.ts
+ * @since 2026-09-05 新增 adoptDeviceId（SSO 归一采纳）与 setupDeviceSync（一站式接入）
+ */
+export { getStableDeviceId, invalidateCachedDeviceId, validateDeviceIdFormat, parseDeviceId, getPlatform, decodeTimestamp, STORAGE_KEY, MAX_AGE_DAYS, DEVICE_PLATFORMS, RANDOM_SUFFIX_LENGTH, CLOCK_SKEW_TOLERANCE_MS } from './device-id.js';
+export type { DeviceIdInfo } from './device-id.js';
+export { getDeviceFingerprint, isDeviceFingerprintEnabled } from './device-fingerprint.js';
+export { syncDeviceFromHeaders, handleDeviceSyncInResponse, initDeviceSync, getCurrentDeviceId, setDeviceId, adoptDeviceId, clearDeviceId, getDeviceIdStats } from './device-sync.js';
+export type { DeviceSyncOptions } from './device-sync.js';
+export { setupDeviceSync, getDeviceHeaders } from './device-setup.js';
+export type { AxiosLikeInstance, SetupDeviceSyncOptions } from './device-setup.js';
+export { sha256 } from './sha256.js';

package/dist/index.js

@@ -0,0 +1,55 @@
+import {
+  getStableDeviceId,
+  invalidateCachedDeviceId,
+  validateDeviceIdFormat,
+  parseDeviceId,
+  getPlatform,
+  decodeTimestamp,
+  STORAGE_KEY,
+  MAX_AGE_DAYS,
+  DEVICE_PLATFORMS,
+  RANDOM_SUFFIX_LENGTH,
+  CLOCK_SKEW_TOLERANCE_MS
+} from "./device-id.js";
+import {
+  getDeviceFingerprint,
+  isDeviceFingerprintEnabled
+} from "./device-fingerprint.js";
+import {
+  syncDeviceFromHeaders,
+  handleDeviceSyncInResponse,
+  initDeviceSync,
+  getCurrentDeviceId,
+  setDeviceId,
+  adoptDeviceId,
+  clearDeviceId,
+  getDeviceIdStats
+} from "./device-sync.js";
+import { setupDeviceSync, getDeviceHeaders } from "./device-setup.js";
+import { sha256 } from "./sha256.js";
+export {
+  CLOCK_SKEW_TOLERANCE_MS,
+  DEVICE_PLATFORMS,
+  MAX_AGE_DAYS,
+  RANDOM_SUFFIX_LENGTH,
+  STORAGE_KEY,
+  adoptDeviceId,
+  clearDeviceId,
+  decodeTimestamp,
+  getCurrentDeviceId,
+  getDeviceFingerprint,
+  getDeviceHeaders,
+  getDeviceIdStats,
+  getPlatform,
+  getStableDeviceId,
+  handleDeviceSyncInResponse,
+  initDeviceSync,
+  invalidateCachedDeviceId,
+  isDeviceFingerprintEnabled,
+  parseDeviceId,
+  setDeviceId,
+  setupDeviceSync,
+  sha256,
+  syncDeviceFromHeaders,
+  validateDeviceIdFormat
+};

package/dist/sha256.d.ts

@@ -0,0 +1,17 @@
+/**
+ * sha256.js 的类型声明（实现为纯 JS，供浏览器与 Jest 共用）
+ */
+
+/**
+ * SHA-256 哈希函数
+ * @param message 待哈希字符串（UTF-8 编码）
+ * @returns 64 位小写 hex 字符串
+ */
+export declare function sha256(message: string): Promise<string>;
+
+/**
+ * 纯 JS SHA-256 降级实现（不依赖 Web Crypto）
+ * @param message 待哈希字符串
+ * @returns 64 位小写 hex 字符串
+ */
+export declare function sha256Pure(message: string): string;

package/dist/sha256.js

@@ -0,0 +1,137 @@
+function hasSubtleCrypto() {
+  return typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.subtle !== "undefined" && globalThis.crypto.subtle !== null;
+}
+async function sha256(message) {
+  if (hasSubtleCrypto()) {
+    const msgBuffer = new TextEncoder().encode(message);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", msgBuffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  return sha256Pure(message);
+}
+const K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function sha256Pure(message) {
+  const bytes = new TextEncoder().encode(message);
+  const msgLen = bytes.length;
+  const paddedLen = (msgLen + 8 >> 6) + 1 << 6;
+  const padded = new Uint8Array(paddedLen);
+  padded.set(bytes);
+  padded[msgLen] = 128;
+  const bitLenHigh = Math.floor(msgLen / 536870912);
+  const bitLenLow = msgLen << 3 >>> 0;
+  const view = new DataView(padded.buffer);
+  view.setUint32(paddedLen - 8, bitLenHigh);
+  view.setUint32(paddedLen - 4, bitLenLow);
+  let h0 = 1779033703, h1 = 3144134277, h2 = 1013904242, h3 = 2773480762;
+  let h4 = 1359893119, h5 = 2600822924, h6 = 528734635, h7 = 1541459225;
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < paddedLen; offset += 64) {
+    for (let i = 0; i < 16; i++) {
+      w[i] = view.getUint32(offset + i * 4);
+    }
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ w[i - 15] >>> 3;
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ w[i - 2] >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 >>> 0;
+    }
+    let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const temp1 = h + S1 + ch + K[i] + w[i] >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = a & b ^ a & c ^ b & c;
+      const temp2 = S0 + maj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    h0 = h0 + a >>> 0;
+    h1 = h1 + b >>> 0;
+    h2 = h2 + c >>> 0;
+    h3 = h3 + d >>> 0;
+    h4 = h4 + e >>> 0;
+    h5 = h5 + f >>> 0;
+    h6 = h6 + g >>> 0;
+    h7 = h7 + h >>> 0;
+  }
+  return [h0, h1, h2, h3, h4, h5, h6, h7].map((x) => x.toString(16).padStart(8, "0")).join("");
+}
+function rotr(x, n) {
+  return (x >>> n | x << 32 - n) >>> 0;
+}
+export {
+  sha256,
+  sha256Pure
+};

package/dist/storage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * storage.js 的类型声明（实现为纯 JS，供浏览器与 Jest 共用）
+ */
+
+/** 读取键值，不可用时读内存降级层；不存在返回 null */
+export declare function safeGetItem(key: string): string | null;
+
+/** 写入键值，不可用时写内存降级层 */
+export declare function safeSetItem(key: string, value: string): void;
+
+/** 移除键值（localStorage 与内存降级层都清） */
+export declare function safeRemoveItem(key: string): void;
+
+/** 仅测试使用：重置探测缓存与内存层 */
+export declare function __resetStorageForTest(): void;

package/dist/storage.js

@@ -0,0 +1,56 @@
+const memoryStore = /* @__PURE__ */ new Map();
+let localStorageAvailable = null;
+function detectLocalStorage() {
+  try {
+    const probeKey = "__shared_device_probe__";
+    window.localStorage.setItem(probeKey, "1");
+    window.localStorage.removeItem(probeKey);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function backingStorage() {
+  if (localStorageAvailable === null) {
+    localStorageAvailable = typeof window !== "undefined" && typeof window.localStorage !== "undefined" && detectLocalStorage();
+  }
+  return localStorageAvailable ? "localStorage" : "memory";
+}
+function safeGetItem(key) {
+  try {
+    if (backingStorage() === "localStorage") {
+      return window.localStorage.getItem(key);
+    }
+  } catch {
+  }
+  return memoryStore.has(key) ? memoryStore.get(key) : null;
+}
+function safeSetItem(key, value) {
+  try {
+    if (backingStorage() === "localStorage") {
+      window.localStorage.setItem(key, value);
+      return;
+    }
+  } catch {
+  }
+  memoryStore.set(key, value);
+}
+function safeRemoveItem(key) {
+  memoryStore.delete(key);
+  try {
+    if (typeof window !== "undefined" && window.localStorage) {
+      window.localStorage.removeItem(key);
+    }
+  } catch {
+  }
+}
+function __resetStorageForTest() {
+  memoryStore.clear();
+  localStorageAvailable = null;
+}
+export {
+  __resetStorageForTest,
+  safeGetItem,
+  safeRemoveItem,
+  safeSetItem
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "stable-deviceid",
+  "version": "1.0.0",
+  "description": "跨端一致的现代浏览器设备身份库：结构化稳定设备 ID（生成/校验/自愈）、canvas+WebGL 指纹（默认关闭）、响应头身份同步、SSO 跨 origin 归一、axios 一站式接入",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "device-id",
+    "device-fingerprint",
+    "device-identity",
+    "browser-fingerprint",
+    "fraud-prevention",
+    "risk-control",
+    "sso",
+    "axios"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs && tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yijiu2025/CoreFlow.git",
+    "directory": "packages/shared-device"
+  },
+  "author": "qirly",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}