@alibarbar/common 1.0.10 → 1.1.1

package/dist/storage.d.mts

@@ -15,6 +15,39 @@ interface StorageOptions {
     /** 是否启用加密，默认为 true */
     encrypt?: boolean;
 }
+/**
+ * 存储初始化配置
+ */
+interface StorageInitOptions {
+    /** 是否自动生成密钥对（如果未设置），默认为 true */
+    autoGenerateKeys?: boolean;
+    /** 是否持久化密钥到 localStorage，默认为 false */
+    persistKeys?: boolean;
+    /** 密钥存储键名（用于持久化），如果未提供将自动生成随机键名 */
+    keyStorageKey?: string;
+    /** 用于加密持久化私钥的密码（如果提供，将使用 PBKDF2 + AES-GCM 加密） */
+    keyEncryptionPassword?: string;
+    /** PBKDF2 迭代次数，默认为 100000 */
+    pbkdf2Iterations?: number;
+    /** RSA密钥长度，默认为 2048 */
+    keyModulusLength?: number;
+    /** 是否启用HMAC数据完整性校验，默认为 true */
+    enableHMAC?: boolean;
+    /** 是否启用时间戳验证（防重放攻击），默认为 true */
+    enableTimestampValidation?: boolean;
+    /** 时间戳有效期（毫秒），默认 7 天，0 表示不验证 */
+    timestampMaxAge?: number;
+    /** 是否为生产环境（影响日志输出），默认为 false */
+    isProduction?: boolean;
+    /** 是否强制重新初始化（即使已经初始化过），默认为 false */
+    forceReinitialize?: boolean;
+}
+/**
+ * 初始化存储密钥对
+ * @param options - 初始化选项
+ * @returns Promise<void>
+ */
+declare function initializeStorageKeys(options?: StorageInitOptions): Promise<void>;
 /**
  * 设置全局RSA密钥对
  * @param keyPair - RSA密钥对
@@ -26,79 +59,17 @@ declare function setStorageKeyPair(keyPair: RSAKeyPair): void;
  */
 declare function getStorageKeyPair(): RSAKeyPair | null;
 /**
- * localStorage封装（支持过期时间和RSA加密）
+ * 清除持久化的密钥（如果存在）
  */
-declare const localStorage: {
-    /**
-     * 设置值
-     * @param key - 键
-     * @param value - 值
-     * @param options - 选项（过期时间、密钥等）
-     * @returns Promise<void>
-     */
-    set<T>(key: string, value: T, options?: {
-        expiry?: number;
-        publicKey?: CryptoKey;
-    }): Promise<void>;
-    /**
-     * 获取值
-     * @param key - 键
-     * @param options - 选项（默认值、私钥等）
-     * @returns Promise<T | undefined> 值或默认值
-     */
-    get<T>(key: string, options?: {
-        defaultValue?: T;
-        privateKey?: CryptoKey;
-    }): Promise<T | undefined>;
-    /**
-     * 移除值
-     * @param key - 键
-     */
-    remove(key: string): void;
-    /**
-     * 清空所有值
-     */
-    clear(): void;
-    /**
-     * 获取所有键
-     * @returns 键数组
-     */
-    keys(): string[];
-};
+declare function clearPersistedKeys(): void;
 /**
- * sessionStorage封装（支持RSA加密）
+ * 获取密钥使用计数
  */
-declare const sessionStorage: {
-    /**
-     * 设置值
-     * @param key - 键
-     * @param value - 值
-     * @param options - 选项（公钥等）
-     * @returns Promise<void>
-     */
-    set<T>(key: string, value: T, options?: {
-        publicKey?: CryptoKey;
-    }): Promise<void>;
-    /**
-     * 获取值
-     * @param key - 键
-     * @param options - 选项（默认值、私钥等）
-     * @returns Promise<T | undefined> 值或默认值
-     */
-    get<T>(key: string, options?: {
-        defaultValue?: T;
-        privateKey?: CryptoKey;
-    }): Promise<T | undefined>;
-    /**
-     * 移除值
-     * @param key - 键
-     */
-    remove(key: string): void;
-    /**
-     * 清空所有值
-     */
-    clear(): void;
-};
+declare function getKeyUsageCount(): number;
+/**
+ * 重置密钥使用计数
+ */
+declare function resetKeyUsageCount(): void;
 /**
  * Cookie操作封装
  */
@@ -138,9 +109,10 @@ declare const cookie: {
     getAll(): Record<string, string>;
 };
 /**
- * 统一存储接口（自动选择存储方式，支持RSA加密）
+ * 统一安全存储接口（自动选择存储方式，支持RSA加密）
+ * 这是推荐的主要导出接口
  */
-declare const storage: {
+declare const secureStorage: {
     /**
      * 设置值（优先使用localStorage，失败则使用sessionStorage）
      * @param key - 键
@@ -171,6 +143,11 @@ declare const storage: {
      * 清空所有值
      */
     clear(): void;
+    /**
+     * 获取所有键名
+     * @returns 键名数组
+     */
+    keys(): string[];
 };
 
-export { type StorageOptions, cookie, getStorageKeyPair, localStorage, sessionStorage, setStorageKeyPair, storage };
+export { type StorageInitOptions, type StorageOptions, clearPersistedKeys, cookie, getKeyUsageCount, getStorageKeyPair, initializeStorageKeys, resetKeyUsageCount, secureStorage, setStorageKeyPair };

package/dist/storage.d.ts

@@ -15,6 +15,39 @@ interface StorageOptions {
     /** 是否启用加密，默认为 true */
     encrypt?: boolean;
 }
+/**
+ * 存储初始化配置
+ */
+interface StorageInitOptions {
+    /** 是否自动生成密钥对（如果未设置），默认为 true */
+    autoGenerateKeys?: boolean;
+    /** 是否持久化密钥到 localStorage，默认为 false */
+    persistKeys?: boolean;
+    /** 密钥存储键名（用于持久化），如果未提供将自动生成随机键名 */
+    keyStorageKey?: string;
+    /** 用于加密持久化私钥的密码（如果提供，将使用 PBKDF2 + AES-GCM 加密） */
+    keyEncryptionPassword?: string;
+    /** PBKDF2 迭代次数，默认为 100000 */
+    pbkdf2Iterations?: number;
+    /** RSA密钥长度，默认为 2048 */
+    keyModulusLength?: number;
+    /** 是否启用HMAC数据完整性校验，默认为 true */
+    enableHMAC?: boolean;
+    /** 是否启用时间戳验证（防重放攻击），默认为 true */
+    enableTimestampValidation?: boolean;
+    /** 时间戳有效期（毫秒），默认 7 天，0 表示不验证 */
+    timestampMaxAge?: number;
+    /** 是否为生产环境（影响日志输出），默认为 false */
+    isProduction?: boolean;
+    /** 是否强制重新初始化（即使已经初始化过），默认为 false */
+    forceReinitialize?: boolean;
+}
+/**
+ * 初始化存储密钥对
+ * @param options - 初始化选项
+ * @returns Promise<void>
+ */
+declare function initializeStorageKeys(options?: StorageInitOptions): Promise<void>;
 /**
  * 设置全局RSA密钥对
  * @param keyPair - RSA密钥对
@@ -26,79 +59,17 @@ declare function setStorageKeyPair(keyPair: RSAKeyPair): void;
  */
 declare function getStorageKeyPair(): RSAKeyPair | null;
 /**
- * localStorage封装（支持过期时间和RSA加密）
+ * 清除持久化的密钥（如果存在）
  */
-declare const localStorage: {
-    /**
-     * 设置值
-     * @param key - 键
-     * @param value - 值
-     * @param options - 选项（过期时间、密钥等）
-     * @returns Promise<void>
-     */
-    set<T>(key: string, value: T, options?: {
-        expiry?: number;
-        publicKey?: CryptoKey;
-    }): Promise<void>;
-    /**
-     * 获取值
-     * @param key - 键
-     * @param options - 选项（默认值、私钥等）
-     * @returns Promise<T | undefined> 值或默认值
-     */
-    get<T>(key: string, options?: {
-        defaultValue?: T;
-        privateKey?: CryptoKey;
-    }): Promise<T | undefined>;
-    /**
-     * 移除值
-     * @param key - 键
-     */
-    remove(key: string): void;
-    /**
-     * 清空所有值
-     */
-    clear(): void;
-    /**
-     * 获取所有键
-     * @returns 键数组
-     */
-    keys(): string[];
-};
+declare function clearPersistedKeys(): void;
 /**
- * sessionStorage封装（支持RSA加密）
+ * 获取密钥使用计数
  */
-declare const sessionStorage: {
-    /**
-     * 设置值
-     * @param key - 键
-     * @param value - 值
-     * @param options - 选项（公钥等）
-     * @returns Promise<void>
-     */
-    set<T>(key: string, value: T, options?: {
-        publicKey?: CryptoKey;
-    }): Promise<void>;
-    /**
-     * 获取值
-     * @param key - 键
-     * @param options - 选项（默认值、私钥等）
-     * @returns Promise<T | undefined> 值或默认值
-     */
-    get<T>(key: string, options?: {
-        defaultValue?: T;
-        privateKey?: CryptoKey;
-    }): Promise<T | undefined>;
-    /**
-     * 移除值
-     * @param key - 键
-     */
-    remove(key: string): void;
-    /**
-     * 清空所有值
-     */
-    clear(): void;
-};
+declare function getKeyUsageCount(): number;
+/**
+ * 重置密钥使用计数
+ */
+declare function resetKeyUsageCount(): void;
 /**
  * Cookie操作封装
  */
@@ -138,9 +109,10 @@ declare const cookie: {
     getAll(): Record<string, string>;
 };
 /**
- * 统一存储接口（自动选择存储方式，支持RSA加密）
+ * 统一安全存储接口（自动选择存储方式，支持RSA加密）
+ * 这是推荐的主要导出接口
  */
-declare const storage: {
+declare const secureStorage: {
     /**
      * 设置值（优先使用localStorage，失败则使用sessionStorage）
      * @param key - 键
@@ -171,6 +143,11 @@ declare const storage: {
      * 清空所有值
      */
     clear(): void;
+    /**
+     * 获取所有键名
+     * @returns 键名数组
+     */
+    keys(): string[];
 };
 
-export { type StorageOptions, cookie, getStorageKeyPair, localStorage, sessionStorage, setStorageKeyPair, storage };
+export { type StorageInitOptions, type StorageOptions, clearPersistedKeys, cookie, getKeyUsageCount, getStorageKeyPair, initializeStorageKeys, resetKeyUsageCount, secureStorage, setStorageKeyPair };