@nietzsci/clavis 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @clavis/sdk
+
+Clavis 软件授权 SDK — 离线验证 + HMAC 签名 + 设备指纹
+
+## 安装
+
+```bash
+npm install @clavis/sdk
+```
+
+## 快速开始
+
+```typescript
+import { Clavis } from "@clavis/sdk";
+
+// 初始化
+const clavis = new Clavis({
+  appId: "nc1a2b3c4d5e6f7g8h",       // 从 Clavis 管理后台获取
+  appSecret: "your-app-secret",        // 从 Clavis 管理后台获取
+  publicKey: "your-ed25519-public-key", // 从 Clavis 管理后台获取
+});
+
+// 获取机器码
+const machineCode = Clavis.getMachineCode();
+
+// 激活
+const result = await clavis.activate("XXXXX-XXXXX-XXXXX-XXXXX-XXXXX", machineCode);
+
+// 离线验证（零网络请求）
+const status = clavis.verifyOffline(machineCode);
+console.log(status.valid, status.tier, status.features);
+
+// 销毁
+clavis.destroy();
+```
+
+## API
+
+### `new Clavis(config)`
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| appId | string | 是 | - | 应用 ID |
+| appSecret | string | 是 | - | 应用密钥 |
+| publicKey | string | 是 | - | Ed25519 公钥 (base64) |
+| baseUrl | string | 否 | `https://c.nietzsci.com` | API 地址 |
+| storagePath | string | 否 | `process.cwd()` | 缓存路径 |
+| offlineGraceDays | number | 否 | 7 | 离线宽限天数 |
+| heartbeatInterval | number | 否 | 3600 | 心跳间隔（秒） |
+| autoHeartbeat | boolean | 否 | true | 自动心跳 |
+
+### 激活
+
+```typescript
+const result = await clavis.activate(licenseKey, identity);
+// result: { success, tier, features, expiresAt, offlineToken }
+```
+
+### 离线验证
+
+```typescript
+const status = clavis.verifyOffline(identity);
+// status: { valid, tier, features, expiresAt, daysRemaining, isOffline, isTrial, inGracePeriod }
+```
+
+### 混合验证（优先离线）
+
+```typescript
+const status = await clavis.checkLicense(identity);
+```
+
+### 功能检查
+
+```typescript
+if (clavis.hasFeature("dark_mode")) {
+  // 启用深色模式
+}
+```
+
+### 事件监听
+
+```typescript
+// 状态变化
+const unsub = clavis.onStatusChange((status) => {
+  console.log("授权状态:", status);
+});
+
+// 到期提醒
+clavis.onExpiring(7, () => {
+  console.log("即将到期！");
+});
+```
+
+### 解绑
+
+```typescript
+await clavis.deactivate(licenseKey, identity);
+```
+
+### 支付
+
+```typescript
+const plans = await clavis.getPricingPlans();
+const url = clavis.getPaymentUrl(planId, identity);
+```
+
+## 工具函数
+
+```typescript
+import { getMachineCode, getDeviceInfo, verifyOfflineToken, hashIdentity } from "@clavis/sdk";
+
+// 设备指纹
+const code = getMachineCode();        // MC-XXXX-XXXX-XXXX-XXXX
+const info = getDeviceInfo();         // { os, osVersion, hostname, ... }
+
+// 离线验签
+const payload = verifyOfflineToken(token, publicKey);
+
+// identity 哈希
+const hash = hashIdentity(identity, appSecret);
+```
+
+## 安全说明
+
+- `appSecret` 不要暴露在前端代码中，仅在 Node.js 服务端使用
+- 浏览器端只能做离线验证（公钥验签），激活/心跳/解绑需通过后端代理
+- 本地缓存使用 AES-256-GCM 加密，防止直接读取 token

package/dist/index.d.mts

@@ -0,0 +1,291 @@
+/** SDK 初始化配置 */
+interface ClavisConfig {
+    /** 应用 ID，格式 nc_xxx */
+    appId: string;
+    /** 应用密钥，用于 HMAC 签名（服务端 SDK 使用，纯客户端不传） */
+    appSecret: string;
+    /** Ed25519 公钥（标准 base64），用于离线验证 */
+    publicKey: string;
+    /** API 地址，默认 https://c.nietzsci.com */
+    baseUrl?: string;
+    /** 本地缓存路径（Node.js 环境），默认 process.cwd() */
+    storagePath?: string;
+    /** 离线宽限天数，默认 7 */
+    offlineGraceDays?: number;
+    /** 心跳间隔（秒），默认 3600 */
+    heartbeatInterval?: number;
+    /** 是否自动心跳，默认 true */
+    autoHeartbeat?: boolean;
+}
+/** 激活结果 */
+interface ActivateResult {
+    success: boolean;
+    tier: string;
+    features: string[];
+    expiresAt: string | null;
+    offlineToken: string;
+}
+/** 授权状态 */
+interface LicenseStatus {
+    valid: boolean;
+    tier: string;
+    features: string[];
+    expiresAt: string | null;
+    daysRemaining: number | null;
+    isOffline: boolean;
+    isTrial: boolean;
+    inGracePeriod: boolean;
+}
+/** 离线 Token Payload（与服务端 signPayload 的 payload 完全一致） */
+interface TokenPayload {
+    app_id: string;
+    license_id: string;
+    identity_hash: string;
+    tier: string;
+    features: string[];
+    issued_at: number;
+    expires_at: number | null;
+    grace_until: number;
+    token_version: number;
+}
+/** 心跳结果 */
+interface HeartbeatResult {
+    serverTimestamp: number;
+    status: string;
+    offlineToken?: string;
+}
+/** 定价方案 */
+interface PricingPlan {
+    id: string;
+    tier: string;
+    name: string;
+    duration: string;
+    durationDays: number;
+    price: number;
+}
+/** 设备信息 */
+interface DeviceInfo {
+    os: string;
+    osVersion: string;
+    hostname: string;
+    arch: string;
+    cpuModel: string;
+    totalMemory: number;
+}
+/** 本地缓存数据结构 */
+interface CacheData {
+    offlineToken: string;
+    lastVerifiedAt: number;
+    tokenVersion: number;
+    licenseKey: string;
+}
+/** API 响应通用结构 */
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+
+type StatusChangeCallback = (status: LicenseStatus) => void;
+declare class Clavis {
+    private config;
+    private storage;
+    private heartbeatTimer?;
+    private statusListeners;
+    private expiryListeners;
+    private lastStatus;
+    private currentLicenseKey;
+    private currentIdentityHash;
+    constructor(config: ClavisConfig);
+    /** 生成设备机器码 */
+    static getMachineCode(appSecret?: string): string;
+    /** 获取设备信息 */
+    static getDeviceInfo(): DeviceInfo;
+    /**
+     * 激活授权码（需要联网）
+     *
+     * @param licenseKey 授权码，格式 XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
+     * @param identity   设备标识（机器码或自定义字符串），SDK 会自动 HMAC 哈希
+     */
+    activate(licenseKey: string, identity: string): Promise<ActivateResult>;
+    /**
+     * 检查授权状态（优先离线，失败则在线）
+     */
+    checkLicense(identity: string): Promise<LicenseStatus>;
+    /**
+     * 纯离线验证（零网络请求）
+     *
+     * @param identity 可选的设备标识，用于 identity_hash 匹配校验
+     */
+    verifyOffline(identity?: string): LicenseStatus;
+    /**
+     * 在线验证（备用）
+     */
+    verifyOnline(licenseKey: string, identity: string): Promise<LicenseStatus>;
+    /**
+     * 检查是否有某个功能
+     */
+    hasFeature(featureName: string): boolean;
+    /**
+     * 获取定价方案列表
+     */
+    getPricingPlans(): Promise<PricingPlan[]>;
+    /**
+     * 获取支付页面 URL
+     */
+    getPaymentUrl(planId: string, identity?: string): string;
+    /**
+     * 解绑当前设备（需要联网）
+     */
+    deactivate(licenseKey: string, identity: string): Promise<void>;
+    /**
+     * 心跳（通常自动调用）
+     */
+    heartbeat(licenseKey: string, identity: string): Promise<HeartbeatResult>;
+    /**
+     * 监听授权状态变化
+     * @returns 取消监听函数
+     */
+    onStatusChange(callback: StatusChangeCallback): () => void;
+    /**
+     * 到期前提醒
+     * @param daysBeforeExpiry 到期前多少天触发
+     * @returns 取消监听函数
+     */
+    onExpiring(daysBeforeExpiry: number, callback: () => void): () => void;
+    /**
+     * 销毁（清理心跳定时器和监听器）
+     */
+    destroy(): void;
+    /** 发送带 HMAC 签名的 POST 请求 */
+    private apiPost;
+    /** 启动自动心跳 */
+    private startHeartbeat;
+    /** 停止心跳 */
+    private stopHeartbeat;
+    /** 通知状态变化 */
+    private notifyStatusChange;
+    /** 检查到期提醒 */
+    private checkExpiryReminders;
+    /** 从激活结果构造 LicenseStatus */
+    private buildStatusFromActivate;
+}
+
+declare class ClavisError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/** 错误码枚举 */
+declare const ErrorCodes: {
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly API_ERROR: "API_ERROR";
+    readonly INVALID_SIGNATURE: "INVALID_SIGNATURE";
+    readonly MISSING_AUTH_HEADERS: "MISSING_AUTH_HEADERS";
+    readonly TIMESTAMP_EXPIRED: "TIMESTAMP_EXPIRED";
+    readonly LICENSE_NOT_FOUND: "LICENSE_NOT_FOUND";
+    readonly LICENSE_EXPIRED: "LICENSE_EXPIRED";
+    readonly LICENSE_REVOKED: "LICENSE_REVOKED";
+    readonly ACTIVATION_LIMIT: "ACTIVATION_LIMIT";
+    readonly ACTIVATION_NOT_FOUND: "ACTIVATION_NOT_FOUND";
+    readonly NO_CACHED_TOKEN: "NO_CACHED_TOKEN";
+    readonly TOKEN_SIGNATURE_INVALID: "TOKEN_SIGNATURE_INVALID";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly TOKEN_GRACE_EXPIRED: "TOKEN_GRACE_EXPIRED";
+    readonly IDENTITY_MISMATCH: "IDENTITY_MISMATCH";
+    readonly CLOCK_DRIFT_DETECTED: "CLOCK_DRIFT_DETECTED";
+    readonly MISSING_CONFIG: "MISSING_CONFIG";
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * 验证 offline token 的 Ed25519 签名
+ *
+ * token 格式: base64url(payload_json).base64url(signature_64bytes)
+ *
+ * 签名流程（服务端 signPayload）：
+ *   1. payloadJson = JSON.stringify(payload)
+ *   2. messageBytes = TextEncoder.encode(payloadJson)
+ *   3. signedMessage = nacl.sign(messageBytes, privateKey) → 64字节签名 + 消息
+ *   4. signature = signedMessage.slice(0, 64)
+ *   5. token = base64url(payloadJson) + "." + base64url(signature)
+ *
+ * 验签流程（本函数）：
+ *   1. 从 token 拆出 payloadBase64Url 和 signatureBase64Url
+ *   2. payloadJson = base64url_decode(payloadBase64Url) → UTF-8 字符串
+ *   3. messageBytes = TextEncoder.encode(payloadJson)
+ *   4. signatureBytes = base64url_decode(signatureBase64Url) → 64 字节
+ *   5. 构造 signedMessage = signature + message
+ *   6. nacl.sign.open(signedMessage, publicKey) → 验证成功则返回 message
+ *   7. 解析 payloadJson 为 TokenPayload
+ */
+declare function verifyOfflineToken(token: string, publicKeyBase64: string): TokenPayload | null;
+
+interface SignedHeaders {
+    "x-app-id": string;
+    "x-timestamp": string;
+    "x-nonce": string;
+    "x-signature": string;
+}
+/**
+ * 生成 HMAC 签名请求头
+ *
+ * 签名算法：
+ *   string_to_sign = "${METHOD}\n${path}\n${timestamp}\n${nonce}\n${SHA256(body)}"
+ *   signature = HMAC_SHA256(appSecret, string_to_sign).hex()
+ *
+ * 服务端验证时：
+ *   - 时间窗口 ±300 秒
+ *   - Nonce 去重（Redis SET NX，TTL 600 秒）
+ *   - timingSafeEqual 比较签名
+ */
+declare function signRequest(params: {
+    method: string;
+    path: string;
+    body: string;
+    appId: string;
+    appSecret: string;
+}): SignedHeaders;
+/**
+ * 生成 identity hash
+ *
+ * 服务端期望的 identity_hash = HMAC-SHA256(appSecret, identity).hex()
+ */
+declare function hashIdentity(identity: string, appSecret: string): string;
+
+/**
+ * 生成设备机器码
+ *
+ * 取硬件特征的 HMAC-SHA256 哈希，格式化为 MC-XXXX-XXXX-XXXX-XXXX
+ * 同一台机器多次调用结果一致（确定性）
+ */
+declare function getMachineCode(appSecret?: string): string;
+/**
+ * 获取设备信息
+ */
+declare function getDeviceInfo(): DeviceInfo;
+
+/**
+ * 文件存储
+ *
+ * 缓存内容用 AES-256-GCM 加密，密钥由 identity 派生。
+ * 换设备（identity 不同）后旧缓存自动失效。
+ *
+ * 文件格式：iv(12) + tag(16) + ciphertext
+ */
+declare class FileStorage {
+    private filePath;
+    private encryptionKey;
+    constructor(storagePath: string, appId: string);
+    /** 保存缓存数据（AES-256-GCM 加密） */
+    save(data: CacheData): void;
+    /** 读取缓存数据（解密） */
+    load(): CacheData | null;
+    /** 清除缓存文件 */
+    clear(): void;
+}
+
+export { type ActivateResult, type ApiResponse, type CacheData, Clavis, type ClavisConfig, ClavisError, type DeviceInfo, type ErrorCode, ErrorCodes, FileStorage, type HeartbeatResult, type LicenseStatus, type PricingPlan, type TokenPayload, Clavis as default, getDeviceInfo, getMachineCode, hashIdentity, signRequest, verifyOfflineToken };

package/dist/index.d.ts

@@ -0,0 +1,291 @@
+/** SDK 初始化配置 */
+interface ClavisConfig {
+    /** 应用 ID，格式 nc_xxx */
+    appId: string;
+    /** 应用密钥，用于 HMAC 签名（服务端 SDK 使用，纯客户端不传） */
+    appSecret: string;
+    /** Ed25519 公钥（标准 base64），用于离线验证 */
+    publicKey: string;
+    /** API 地址，默认 https://c.nietzsci.com */
+    baseUrl?: string;
+    /** 本地缓存路径（Node.js 环境），默认 process.cwd() */
+    storagePath?: string;
+    /** 离线宽限天数，默认 7 */
+    offlineGraceDays?: number;
+    /** 心跳间隔（秒），默认 3600 */
+    heartbeatInterval?: number;
+    /** 是否自动心跳，默认 true */
+    autoHeartbeat?: boolean;
+}
+/** 激活结果 */
+interface ActivateResult {
+    success: boolean;
+    tier: string;
+    features: string[];
+    expiresAt: string | null;
+    offlineToken: string;
+}
+/** 授权状态 */
+interface LicenseStatus {
+    valid: boolean;
+    tier: string;
+    features: string[];
+    expiresAt: string | null;
+    daysRemaining: number | null;
+    isOffline: boolean;
+    isTrial: boolean;
+    inGracePeriod: boolean;
+}
+/** 离线 Token Payload（与服务端 signPayload 的 payload 完全一致） */
+interface TokenPayload {
+    app_id: string;
+    license_id: string;
+    identity_hash: string;
+    tier: string;
+    features: string[];
+    issued_at: number;
+    expires_at: number | null;
+    grace_until: number;
+    token_version: number;
+}
+/** 心跳结果 */
+interface HeartbeatResult {
+    serverTimestamp: number;
+    status: string;
+    offlineToken?: string;
+}
+/** 定价方案 */
+interface PricingPlan {
+    id: string;
+    tier: string;
+    name: string;
+    duration: string;
+    durationDays: number;
+    price: number;
+}
+/** 设备信息 */
+interface DeviceInfo {
+    os: string;
+    osVersion: string;
+    hostname: string;
+    arch: string;
+    cpuModel: string;
+    totalMemory: number;
+}
+/** 本地缓存数据结构 */
+interface CacheData {
+    offlineToken: string;
+    lastVerifiedAt: number;
+    tokenVersion: number;
+    licenseKey: string;
+}
+/** API 响应通用结构 */
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+
+type StatusChangeCallback = (status: LicenseStatus) => void;
+declare class Clavis {
+    private config;
+    private storage;
+    private heartbeatTimer?;
+    private statusListeners;
+    private expiryListeners;
+    private lastStatus;
+    private currentLicenseKey;
+    private currentIdentityHash;
+    constructor(config: ClavisConfig);
+    /** 生成设备机器码 */
+    static getMachineCode(appSecret?: string): string;
+    /** 获取设备信息 */
+    static getDeviceInfo(): DeviceInfo;
+    /**
+     * 激活授权码（需要联网）
+     *
+     * @param licenseKey 授权码，格式 XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
+     * @param identity   设备标识（机器码或自定义字符串），SDK 会自动 HMAC 哈希
+     */
+    activate(licenseKey: string, identity: string): Promise<ActivateResult>;
+    /**
+     * 检查授权状态（优先离线，失败则在线）
+     */
+    checkLicense(identity: string): Promise<LicenseStatus>;
+    /**
+     * 纯离线验证（零网络请求）
+     *
+     * @param identity 可选的设备标识，用于 identity_hash 匹配校验
+     */
+    verifyOffline(identity?: string): LicenseStatus;
+    /**
+     * 在线验证（备用）
+     */
+    verifyOnline(licenseKey: string, identity: string): Promise<LicenseStatus>;
+    /**
+     * 检查是否有某个功能
+     */
+    hasFeature(featureName: string): boolean;
+    /**
+     * 获取定价方案列表
+     */
+    getPricingPlans(): Promise<PricingPlan[]>;
+    /**
+     * 获取支付页面 URL
+     */
+    getPaymentUrl(planId: string, identity?: string): string;
+    /**
+     * 解绑当前设备（需要联网）
+     */
+    deactivate(licenseKey: string, identity: string): Promise<void>;
+    /**
+     * 心跳（通常自动调用）
+     */
+    heartbeat(licenseKey: string, identity: string): Promise<HeartbeatResult>;
+    /**
+     * 监听授权状态变化
+     * @returns 取消监听函数
+     */
+    onStatusChange(callback: StatusChangeCallback): () => void;
+    /**
+     * 到期前提醒
+     * @param daysBeforeExpiry 到期前多少天触发
+     * @returns 取消监听函数
+     */
+    onExpiring(daysBeforeExpiry: number, callback: () => void): () => void;
+    /**
+     * 销毁（清理心跳定时器和监听器）
+     */
+    destroy(): void;
+    /** 发送带 HMAC 签名的 POST 请求 */
+    private apiPost;
+    /** 启动自动心跳 */
+    private startHeartbeat;
+    /** 停止心跳 */
+    private stopHeartbeat;
+    /** 通知状态变化 */
+    private notifyStatusChange;
+    /** 检查到期提醒 */
+    private checkExpiryReminders;
+    /** 从激活结果构造 LicenseStatus */
+    private buildStatusFromActivate;
+}
+
+declare class ClavisError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/** 错误码枚举 */
+declare const ErrorCodes: {
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly API_ERROR: "API_ERROR";
+    readonly INVALID_SIGNATURE: "INVALID_SIGNATURE";
+    readonly MISSING_AUTH_HEADERS: "MISSING_AUTH_HEADERS";
+    readonly TIMESTAMP_EXPIRED: "TIMESTAMP_EXPIRED";
+    readonly LICENSE_NOT_FOUND: "LICENSE_NOT_FOUND";
+    readonly LICENSE_EXPIRED: "LICENSE_EXPIRED";
+    readonly LICENSE_REVOKED: "LICENSE_REVOKED";
+    readonly ACTIVATION_LIMIT: "ACTIVATION_LIMIT";
+    readonly ACTIVATION_NOT_FOUND: "ACTIVATION_NOT_FOUND";
+    readonly NO_CACHED_TOKEN: "NO_CACHED_TOKEN";
+    readonly TOKEN_SIGNATURE_INVALID: "TOKEN_SIGNATURE_INVALID";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly TOKEN_GRACE_EXPIRED: "TOKEN_GRACE_EXPIRED";
+    readonly IDENTITY_MISMATCH: "IDENTITY_MISMATCH";
+    readonly CLOCK_DRIFT_DETECTED: "CLOCK_DRIFT_DETECTED";
+    readonly MISSING_CONFIG: "MISSING_CONFIG";
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * 验证 offline token 的 Ed25519 签名
+ *
+ * token 格式: base64url(payload_json).base64url(signature_64bytes)
+ *
+ * 签名流程（服务端 signPayload）：
+ *   1. payloadJson = JSON.stringify(payload)
+ *   2. messageBytes = TextEncoder.encode(payloadJson)
+ *   3. signedMessage = nacl.sign(messageBytes, privateKey) → 64字节签名 + 消息
+ *   4. signature = signedMessage.slice(0, 64)
+ *   5. token = base64url(payloadJson) + "." + base64url(signature)
+ *
+ * 验签流程（本函数）：
+ *   1. 从 token 拆出 payloadBase64Url 和 signatureBase64Url
+ *   2. payloadJson = base64url_decode(payloadBase64Url) → UTF-8 字符串
+ *   3. messageBytes = TextEncoder.encode(payloadJson)
+ *   4. signatureBytes = base64url_decode(signatureBase64Url) → 64 字节
+ *   5. 构造 signedMessage = signature + message
+ *   6. nacl.sign.open(signedMessage, publicKey) → 验证成功则返回 message
+ *   7. 解析 payloadJson 为 TokenPayload
+ */
+declare function verifyOfflineToken(token: string, publicKeyBase64: string): TokenPayload | null;
+
+interface SignedHeaders {
+    "x-app-id": string;
+    "x-timestamp": string;
+    "x-nonce": string;
+    "x-signature": string;
+}
+/**
+ * 生成 HMAC 签名请求头
+ *
+ * 签名算法：
+ *   string_to_sign = "${METHOD}\n${path}\n${timestamp}\n${nonce}\n${SHA256(body)}"
+ *   signature = HMAC_SHA256(appSecret, string_to_sign).hex()
+ *
+ * 服务端验证时：
+ *   - 时间窗口 ±300 秒
+ *   - Nonce 去重（Redis SET NX，TTL 600 秒）
+ *   - timingSafeEqual 比较签名
+ */
+declare function signRequest(params: {
+    method: string;
+    path: string;
+    body: string;
+    appId: string;
+    appSecret: string;
+}): SignedHeaders;
+/**
+ * 生成 identity hash
+ *
+ * 服务端期望的 identity_hash = HMAC-SHA256(appSecret, identity).hex()
+ */
+declare function hashIdentity(identity: string, appSecret: string): string;
+
+/**
+ * 生成设备机器码
+ *
+ * 取硬件特征的 HMAC-SHA256 哈希，格式化为 MC-XXXX-XXXX-XXXX-XXXX
+ * 同一台机器多次调用结果一致（确定性）
+ */
+declare function getMachineCode(appSecret?: string): string;
+/**
+ * 获取设备信息
+ */
+declare function getDeviceInfo(): DeviceInfo;
+
+/**
+ * 文件存储
+ *
+ * 缓存内容用 AES-256-GCM 加密，密钥由 identity 派生。
+ * 换设备（identity 不同）后旧缓存自动失效。
+ *
+ * 文件格式：iv(12) + tag(16) + ciphertext
+ */
+declare class FileStorage {
+    private filePath;
+    private encryptionKey;
+    constructor(storagePath: string, appId: string);
+    /** 保存缓存数据（AES-256-GCM 加密） */
+    save(data: CacheData): void;
+    /** 读取缓存数据（解密） */
+    load(): CacheData | null;
+    /** 清除缓存文件 */
+    clear(): void;
+}
+
+export { type ActivateResult, type ApiResponse, type CacheData, Clavis, type ClavisConfig, ClavisError, type DeviceInfo, type ErrorCode, ErrorCodes, FileStorage, type HeartbeatResult, type LicenseStatus, type PricingPlan, type TokenPayload, Clavis as default, getDeviceInfo, getMachineCode, hashIdentity, signRequest, verifyOfflineToken };