@alibarbar/common 1.1.2 → 1.1.4

package/dist/storage.d.mts

@@ -1,141 +1,83 @@
-import { RSAKeyPair } from './crypto.mjs';
-
-/**
- * 存储工具函数
- */
-
-/**
- * 存储配置选项
- */
-interface StorageOptions {
-    /** RSA公钥（用于加密） */
-    publicKey?: CryptoKey;
-    /** RSA私钥（用于解密） */
-    privateKey?: CryptoKey;
-    /** 是否启用加密，默认为 true */
-    encrypt?: boolean;
+interface SecureStorageOptions {
+    /** 存储后端：localStorage 或 sessionStorage */
+    storage?: Storage;
+    /** 命名空间前缀 */
+    namespace?: string;
+    /** 默认过期时间（毫秒） */
+    defaultExpire?: number | null;
 }
 /**
- * 存储初始化配置
- */
-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密钥对
- */
-declare function setStorageKeyPair(keyPair: RSAKeyPair): void;
-/**
- * 获取全局密钥对
- * @returns 全局密钥对或null
+ * RSA 混合加密存储类（单例模式）
  */
-declare function getStorageKeyPair(): RSAKeyPair | null;
-/**
- * 清除持久化的密钥（如果存在）
- */
-declare function clearPersistedKeys(): void;
-/**
- * 获取密钥使用计数
- */
-declare function getKeyUsageCount(): number;
-/**
- * 重置密钥使用计数
- */
-declare function resetKeyUsageCount(): void;
-/**
- * Cookie操作封装
- */
-declare const cookie: {
+declare class SecureStorage {
+    private static _instances;
+    static get instances(): Map<string, SecureStorage>;
+    private readonly namespace;
+    private readonly storage;
+    private readonly defaultExpire;
+    private readonly instanceKey;
+    constructor(options: SecureStorageOptions);
     /**
-     * 设置Cookie
-     * @param key - 键
-     * @param value - 值
-     * @param options - Cookie选项
+     * 获取单例实例（静态方法）
      */
-    set(key: string, value: string, options?: {
-        expires?: number | Date;
-        path?: string;
-        domain?: string;
-        secure?: boolean;
-        sameSite?: "strict" | "lax" | "none";
-    }): void;
+    static getInstance(options: SecureStorageOptions): SecureStorage;
     /**
-     * 获取Cookie
-     * @param key - 键
-     * @returns Cookie值
+     * 清除所有单例实例（用于测试或重置）
      */
-    get(key: string): string | undefined;
+    static clearInstances(): void;
     /**
-     * 移除Cookie
-     * @param key - 键
-     * @param options - Cookie选项
+     * 获取当前所有实例的数量（用于调试）
      */
-    remove(key: string, options?: {
-        path?: string;
-        domain?: string;
-    }): void;
+    static getInstanceCount(): number;
     /**
-     * 获取所有Cookie
-     * @returns Cookie对象
+     * 获取完整键名（带命名空间）
+     */
+    private _getFullKey;
+    /**
+     * 检查数据是否过期
+     */
+    private _isExpired;
+    /**
+     * 设置值
+     */
+    set<T>(key: string, value: T, expire?: number | null): Promise<boolean>;
+    /**
+     * 获取值
+     */
+    get<T = unknown>(key: string, defaultValue?: T | null): Promise<T | null>;
+    /**
+     * 删除值
+     */
+    remove(key: string): boolean;
+    /**
+     * 检查键是否存在
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 清空所有数据
+     */
+    clear(): number;
+    /**
+     * 获取所有键名
      */
-    getAll(): Record<string, string>;
-};
-/**
- * 统一安全存储接口（通过后端适配器封装 localStorage / sessionStorage / Cookie）
- */
-type SecureStorageBackendType = 'local' | 'session' | 'cookie';
-interface SecureStorageInstance {
-    set<T>(key: string, value: T, options?: {
-        expiry?: number;
-        publicKey?: CryptoKey;
-        privateKey?: CryptoKey;
-        defaultValue?: T;
-    }): Promise<void>;
-    get<T>(key: string, options?: {
-        defaultValue?: T;
-        privateKey?: CryptoKey;
-    }): Promise<T | undefined>;
-    remove(key: string): void;
-    clear(): void;
     keys(): string[];
+    /**
+     * 获取数据条数
+     */
+    size(): number;
+    /**
+     * 清理过期数据
+     */
+    clearExpired(): Promise<number>;
+    /**
+     * 获取实例的唯一标识
+     */
+    getInstanceKey(): string;
+    /**
+     * 检查是否为单例实例
+     */
+    isSingleton(): boolean;
 }
-/**
- * 工厂函数：根据后端类型创建 SecureStorage 实例
- * 使用方可在应用启动时自行决定使用 local / session / cookie
- */
-declare function createSecureStorage(type?: SecureStorageBackendType): SecureStorageInstance;
-/**
- * 默认导出的 SecureStorage：使用 localStorage 作为后端
- * 与之前 `secureStorage` 的语义保持一致
- */
-declare const secureStorage: SecureStorageInstance;
+declare const secureStorage: SecureStorage;
 
-export { type SecureStorageInstance, type StorageInitOptions, type StorageOptions, clearPersistedKeys, cookie, createSecureStorage, getKeyUsageCount, getStorageKeyPair, initializeStorageKeys, resetKeyUsageCount, secureStorage, setStorageKeyPair };
+export { SecureStorage, type SecureStorageOptions, SecureStorage as default, secureStorage };

package/dist/storage.d.ts

@@ -1,141 +1,83 @@
-import { RSAKeyPair } from './crypto.js';
-
-/**
- * 存储工具函数
- */
-
-/**
- * 存储配置选项
- */
-interface StorageOptions {
-    /** RSA公钥（用于加密） */
-    publicKey?: CryptoKey;
-    /** RSA私钥（用于解密） */
-    privateKey?: CryptoKey;
-    /** 是否启用加密，默认为 true */
-    encrypt?: boolean;
+interface SecureStorageOptions {
+    /** 存储后端：localStorage 或 sessionStorage */
+    storage?: Storage;
+    /** 命名空间前缀 */
+    namespace?: string;
+    /** 默认过期时间（毫秒） */
+    defaultExpire?: number | null;
 }
 /**
- * 存储初始化配置
- */
-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密钥对
- */
-declare function setStorageKeyPair(keyPair: RSAKeyPair): void;
-/**
- * 获取全局密钥对
- * @returns 全局密钥对或null
+ * RSA 混合加密存储类（单例模式）
  */
-declare function getStorageKeyPair(): RSAKeyPair | null;
-/**
- * 清除持久化的密钥（如果存在）
- */
-declare function clearPersistedKeys(): void;
-/**
- * 获取密钥使用计数
- */
-declare function getKeyUsageCount(): number;
-/**
- * 重置密钥使用计数
- */
-declare function resetKeyUsageCount(): void;
-/**
- * Cookie操作封装
- */
-declare const cookie: {
+declare class SecureStorage {
+    private static _instances;
+    static get instances(): Map<string, SecureStorage>;
+    private readonly namespace;
+    private readonly storage;
+    private readonly defaultExpire;
+    private readonly instanceKey;
+    constructor(options: SecureStorageOptions);
     /**
-     * 设置Cookie
-     * @param key - 键
-     * @param value - 值
-     * @param options - Cookie选项
+     * 获取单例实例（静态方法）
      */
-    set(key: string, value: string, options?: {
-        expires?: number | Date;
-        path?: string;
-        domain?: string;
-        secure?: boolean;
-        sameSite?: "strict" | "lax" | "none";
-    }): void;
+    static getInstance(options: SecureStorageOptions): SecureStorage;
     /**
-     * 获取Cookie
-     * @param key - 键
-     * @returns Cookie值
+     * 清除所有单例实例（用于测试或重置）
      */
-    get(key: string): string | undefined;
+    static clearInstances(): void;
     /**
-     * 移除Cookie
-     * @param key - 键
-     * @param options - Cookie选项
+     * 获取当前所有实例的数量（用于调试）
      */
-    remove(key: string, options?: {
-        path?: string;
-        domain?: string;
-    }): void;
+    static getInstanceCount(): number;
     /**
-     * 获取所有Cookie
-     * @returns Cookie对象
+     * 获取完整键名（带命名空间）
+     */
+    private _getFullKey;
+    /**
+     * 检查数据是否过期
+     */
+    private _isExpired;
+    /**
+     * 设置值
+     */
+    set<T>(key: string, value: T, expire?: number | null): Promise<boolean>;
+    /**
+     * 获取值
+     */
+    get<T = unknown>(key: string, defaultValue?: T | null): Promise<T | null>;
+    /**
+     * 删除值
+     */
+    remove(key: string): boolean;
+    /**
+     * 检查键是否存在
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 清空所有数据
+     */
+    clear(): number;
+    /**
+     * 获取所有键名
      */
-    getAll(): Record<string, string>;
-};
-/**
- * 统一安全存储接口（通过后端适配器封装 localStorage / sessionStorage / Cookie）
- */
-type SecureStorageBackendType = 'local' | 'session' | 'cookie';
-interface SecureStorageInstance {
-    set<T>(key: string, value: T, options?: {
-        expiry?: number;
-        publicKey?: CryptoKey;
-        privateKey?: CryptoKey;
-        defaultValue?: T;
-    }): Promise<void>;
-    get<T>(key: string, options?: {
-        defaultValue?: T;
-        privateKey?: CryptoKey;
-    }): Promise<T | undefined>;
-    remove(key: string): void;
-    clear(): void;
     keys(): string[];
+    /**
+     * 获取数据条数
+     */
+    size(): number;
+    /**
+     * 清理过期数据
+     */
+    clearExpired(): Promise<number>;
+    /**
+     * 获取实例的唯一标识
+     */
+    getInstanceKey(): string;
+    /**
+     * 检查是否为单例实例
+     */
+    isSingleton(): boolean;
 }
-/**
- * 工厂函数：根据后端类型创建 SecureStorage 实例
- * 使用方可在应用启动时自行决定使用 local / session / cookie
- */
-declare function createSecureStorage(type?: SecureStorageBackendType): SecureStorageInstance;
-/**
- * 默认导出的 SecureStorage：使用 localStorage 作为后端
- * 与之前 `secureStorage` 的语义保持一致
- */
-declare const secureStorage: SecureStorageInstance;
+declare const secureStorage: SecureStorage;
 
-export { type SecureStorageInstance, type StorageInitOptions, type StorageOptions, clearPersistedKeys, cookie, createSecureStorage, getKeyUsageCount, getStorageKeyPair, initializeStorageKeys, resetKeyUsageCount, secureStorage, setStorageKeyPair };
+export { SecureStorage, type SecureStorageOptions, SecureStorage as default, secureStorage };