@nietzsci/clavis 0.1.0

package/examples/node-example.ts

@@ -0,0 +1,67 @@
+/**
+ * Clavis SDK — Node.js 使用示例
+ *
+ * 运行：npx tsx examples/node-example.ts
+ */
+
+import { Clavis } from "../src/index";
+
+async function main() {
+  // 1. 初始化 SDK
+  const clavis = new Clavis({
+    appId: "nc1a2b3c4d5e6f7g8h",
+    appSecret: "your-app-secret-from-dashboard",
+    publicKey: "your-ed25519-public-key-base64",
+    baseUrl: "http://100.70.90.125:3100",
+    autoHeartbeat: true,
+    heartbeatInterval: 3600,
+  });
+
+  // 2. 获取机器码
+  const machineCode = Clavis.getMachineCode();
+  console.log("机器码:", machineCode);
+
+  // 3. 获取设备信息
+  const deviceInfo = Clavis.getDeviceInfo();
+  console.log("设备信息:", deviceInfo);
+
+  // 4. 监听授权状态变化
+  const unsubscribe = clavis.onStatusChange((status) => {
+    console.log("授权状态变化:", status);
+  });
+
+  // 5. 到期前 7 天提醒
+  clavis.onExpiring(7, () => {
+    console.log("警告: 授权即将在 7 天内到期！");
+  });
+
+  try {
+    // 6. 激活授权码
+    const result = await clavis.activate(
+      "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
+      machineCode
+    );
+    console.log("激活结果:", result);
+
+    // 7. 离线验证（不需要网络）
+    const status = clavis.verifyOffline(machineCode);
+    console.log("离线验证:", status);
+
+    // 8. 检查功能权限
+    if (clavis.hasFeature("dark_mode")) {
+      console.log("已授权: 深色模式");
+    }
+
+    // 9. 混合验证（优先离线，失败则在线）
+    const checkResult = await clavis.checkLicense(machineCode);
+    console.log("授权状态:", checkResult);
+  } catch (err) {
+    console.error("操作失败:", err);
+  }
+
+  // 10. 清理
+  unsubscribe();
+  clavis.destroy();
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@nietzsci/clavis",
+  "version": "0.1.0",
+  "description": "Clavis 软件授权 SDK — 离线验证 + HMAC 签名 + 设备指纹",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3",
+    "tweetnacl-util": "^0.15.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,594 @@
+// ============================================================
+// Clavis 主类
+// ============================================================
+
+import crypto from "crypto";
+import type {
+  ClavisConfig,
+  ClavisConfigResolved,
+  ActivateResult,
+  LicenseStatus,
+  HeartbeatResult,
+  PricingPlan,
+  TokenPayload,
+  ApiResponse,
+  CacheData,
+} from "./types";
+import { ClavisError, ErrorCodes } from "./errors";
+import { verifyOfflineToken } from "./crypto";
+import { signRequest, hashIdentity } from "./hmac";
+import { getMachineCode, getDeviceInfo } from "./fingerprint";
+import { FileStorage } from "./storage";
+
+type StatusChangeCallback = (status: LicenseStatus) => void;
+
+export class Clavis {
+  private config: ClavisConfigResolved;
+  private storage: FileStorage;
+  private heartbeatTimer?: ReturnType<typeof setInterval>;
+  private statusListeners: StatusChangeCallback[] = [];
+  private expiryListeners: { days: number; callback: () => void; fired: boolean }[] = [];
+  private lastStatus: LicenseStatus | null = null;
+  private currentLicenseKey: string | null = null;
+  private currentIdentityHash: string | null = null;
+
+  constructor(config: ClavisConfig) {
+    if (!config.appId || !config.appSecret || !config.publicKey) {
+      throw new ClavisError(
+        ErrorCodes.MISSING_CONFIG,
+        "appId, appSecret, publicKey 为必填项"
+      );
+    }
+
+    this.config = {
+      appId: config.appId,
+      appSecret: config.appSecret,
+      publicKey: config.publicKey,
+      baseUrl: (config.baseUrl || "https://c.nietzsci.com").replace(/\/+$/, ""),
+      storagePath: config.storagePath || process.cwd(),
+      offlineGraceDays: config.offlineGraceDays ?? 7,
+      heartbeatInterval: config.heartbeatInterval ?? 3600,
+      autoHeartbeat: config.autoHeartbeat ?? true,
+    };
+
+    this.storage = new FileStorage(this.config.storagePath, this.config.appId);
+  }
+
+  // ===== 静态工具方法 =====
+
+  /** 生成设备机器码 */
+  static getMachineCode(appSecret?: string): string {
+    return getMachineCode(appSecret);
+  }
+
+  /** 获取设备信息 */
+  static getDeviceInfo() {
+    return getDeviceInfo();
+  }
+
+  // ===== 激活 =====
+
+  /**
+   * 激活授权码（需要联网）
+   *
+   * @param licenseKey 授权码，格式 XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
+   * @param identity   设备标识（机器码或自定义字符串），SDK 会自动 HMAC 哈希
+   */
+  async activate(
+    licenseKey: string,
+    identity: string
+  ): Promise<ActivateResult> {
+    // 1. 生成 identity hash
+    const identityHash = hashIdentity(identity, this.config.appSecret);
+
+    // 2. 构造请求体
+    const body = JSON.stringify({
+      license_key: licenseKey,
+      identity_hash: identityHash,
+    });
+
+    // 3. 发送签名请求
+    const data = await this.apiPost<{
+      offline_token: string;
+      tier: string;
+      features: string[];
+      expires_at: string | null;
+    }>("/api/v1/sdk/activate", body);
+
+    // 4. 存储 offline token 到本地
+    this.storage.save({
+      offlineToken: data.offline_token,
+      lastVerifiedAt: Math.floor(Date.now() / 1000),
+      tokenVersion: 0, // 激活时不知道具体版本，从 token 解析
+      licenseKey,
+    });
+
+    // 5. 记录当前 license 信息
+    this.currentLicenseKey = licenseKey;
+    this.currentIdentityHash = identityHash;
+
+    // 6. 启动自动心跳
+    if (this.config.autoHeartbeat) {
+      this.startHeartbeat(licenseKey, identity);
+    }
+
+    const result: ActivateResult = {
+      success: true,
+      tier: data.tier,
+      features: data.features,
+      expiresAt: data.expires_at,
+      offlineToken: data.offline_token,
+    };
+
+    // 7. 通知状态变化
+    this.notifyStatusChange(this.buildStatusFromActivate(result, false));
+
+    return result;
+  }
+
+  // ===== 验证 =====
+
+  /**
+   * 检查授权状态（优先离线，失败则在线）
+   */
+  async checkLicense(identity: string): Promise<LicenseStatus> {
+    // 1. 尝试离线验证
+    const offlineResult = this.verifyOffline(identity);
+    if (offlineResult.valid) return offlineResult;
+
+    // 2. 离线失败则尝试在线验证
+    const cached = this.storage.load();
+    if (!cached?.licenseKey) {
+      return offlineResult; // 没有缓存，返回离线失败结果
+    }
+
+    return this.verifyOnline(cached.licenseKey, identity);
+  }
+
+  /**
+   * 纯离线验证（零网络请求）
+   *
+   * @param identity 可选的设备标识，用于 identity_hash 匹配校验
+   */
+  verifyOffline(identity?: string): LicenseStatus {
+    const invalid: LicenseStatus = {
+      valid: false,
+      tier: "",
+      features: [],
+      expiresAt: null,
+      daysRemaining: null,
+      isOffline: true,
+      isTrial: false,
+      inGracePeriod: false,
+    };
+
+    // 1. 读取本地缓存
+    const cached = this.storage.load();
+    if (!cached?.offlineToken) {
+      return { ...invalid, tier: "none" };
+    }
+
+    // 2. Ed25519 公钥验签
+    const payload = verifyOfflineToken(
+      cached.offlineToken,
+      this.config.publicKey
+    );
+    if (!payload) {
+      return { ...invalid, tier: "invalid_signature" };
+    }
+
+    // 3. 检查 app_id 匹配
+    if (payload.app_id !== this.config.appId) {
+      return { ...invalid, tier: "app_mismatch" };
+    }
+
+    // 4. 检查 identity_hash 匹配
+    if (identity) {
+      const expectedHash = hashIdentity(identity, this.config.appSecret);
+      if (payload.identity_hash !== expectedHash) {
+        return { ...invalid, tier: "identity_mismatch" };
+      }
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+
+    // 5. 时钟回拨检测
+    if (cached.lastVerifiedAt > now + 60) {
+      // 允许 60 秒误差
+      return { ...invalid, tier: "clock_drift" };
+    }
+
+    // 6. 检查授权到期
+    const isExpired =
+      payload.expires_at !== null && payload.expires_at < now;
+    const inGracePeriod = isExpired && payload.grace_until > now;
+    const graceExpired = isExpired && payload.grace_until <= now;
+
+    if (graceExpired) {
+      return {
+        ...invalid,
+        tier: payload.tier,
+        features: payload.features,
+        expiresAt: payload.expires_at
+          ? new Date(payload.expires_at * 1000).toISOString()
+          : null,
+        daysRemaining: 0,
+      };
+    }
+
+    // 7. 计算剩余天数
+    let daysRemaining: number | null = null;
+    if (payload.expires_at !== null) {
+      daysRemaining = Math.ceil((payload.expires_at - now) / 86400);
+      if (daysRemaining < 0) daysRemaining = 0;
+    }
+
+    // 8. 更新 lastVerifiedAt
+    this.storage.save({
+      ...cached,
+      lastVerifiedAt: now,
+    });
+
+    const status: LicenseStatus = {
+      valid: true,
+      tier: payload.tier,
+      features: payload.features,
+      expiresAt: payload.expires_at
+        ? new Date(payload.expires_at * 1000).toISOString()
+        : null,
+      daysRemaining,
+      isOffline: true,
+      isTrial: payload.tier === "trial",
+      inGracePeriod,
+    };
+
+    // 通知状态变化
+    this.notifyStatusChange(status);
+
+    // 检查到期提醒
+    this.checkExpiryReminders(daysRemaining);
+
+    return status;
+  }
+
+  /**
+   * 在线验证（备用）
+   */
+  async verifyOnline(
+    licenseKey: string,
+    identity: string
+  ): Promise<LicenseStatus> {
+    const identityHash = hashIdentity(identity, this.config.appSecret);
+
+    const body = JSON.stringify({
+      license_key: licenseKey,
+      identity_hash: identityHash,
+    });
+
+    try {
+      const data = await this.apiPost<{
+        valid: boolean;
+        status: string;
+        tier: string;
+        features: string[];
+        expires_at: string | null;
+        days_remaining: number | null;
+        offline_token?: string;
+      }>("/api/v1/sdk/verify", body);
+
+      // 如果服务端返回了新的 offline_token，更新缓存
+      if (data.offline_token) {
+        this.storage.save({
+          offlineToken: data.offline_token,
+          lastVerifiedAt: Math.floor(Date.now() / 1000),
+          tokenVersion: 0,
+          licenseKey,
+        });
+      }
+
+      const status: LicenseStatus = {
+        valid: data.valid,
+        tier: data.tier,
+        features: data.features,
+        expiresAt: data.expires_at,
+        daysRemaining: data.days_remaining,
+        isOffline: false,
+        isTrial: data.tier === "trial",
+        inGracePeriod: false,
+      };
+
+      this.notifyStatusChange(status);
+      return status;
+    } catch (err) {
+      // 在线验证也失败，返回离线验证的结果
+      return {
+        valid: false,
+        tier: "",
+        features: [],
+        expiresAt: null,
+        daysRemaining: null,
+        isOffline: true,
+        isTrial: false,
+        inGracePeriod: false,
+      };
+    }
+  }
+
+  /**
+   * 检查是否有某个功能
+   */
+  hasFeature(featureName: string): boolean {
+    const cached = this.storage.load();
+    if (!cached?.offlineToken) return false;
+
+    const payload = verifyOfflineToken(
+      cached.offlineToken,
+      this.config.publicKey
+    );
+    if (!payload) return false;
+
+    return payload.features.includes(featureName);
+  }
+
+  // ===== 支付 =====
+
+  /**
+   * 获取定价方案列表
+   */
+  async getPricingPlans(): Promise<PricingPlan[]> {
+    const url = `${this.config.baseUrl}/api/v1/public/app-info?app_id=${encodeURIComponent(this.config.appId)}`;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new ClavisError(
+        ErrorCodes.API_ERROR,
+        `获取定价方案失败: ${response.status}`
+      );
+    }
+
+    const json = (await response.json()) as ApiResponse<{
+      pricing: PricingPlan[];
+    }>;
+
+    if (!json.success || !json.data) {
+      throw new ClavisError(
+        ErrorCodes.API_ERROR,
+        json.error?.message || "获取定价方案失败"
+      );
+    }
+
+    return json.data.pricing || [];
+  }
+
+  /**
+   * 获取支付页面 URL
+   */
+  getPaymentUrl(planId: string, identity?: string): string {
+    let url = `${this.config.baseUrl}/activate/${this.config.appId}?plan=${encodeURIComponent(planId)}`;
+    if (identity) {
+      url += `&identity=${encodeURIComponent(identity)}`;
+    }
+    return url;
+  }
+
+  // ===== 生命周期 =====
+
+  /**
+   * 解绑当前设备（需要联网）
+   */
+  async deactivate(licenseKey: string, identity: string): Promise<void> {
+    const identityHash = hashIdentity(identity, this.config.appSecret);
+
+    const body = JSON.stringify({
+      license_key: licenseKey,
+      identity_hash: identityHash,
+    });
+
+    await this.apiPost("/api/v1/sdk/deactivate", body);
+
+    // 清除本地缓存
+    this.storage.clear();
+    this.stopHeartbeat();
+  }
+
+  /**
+   * 心跳（通常自动调用）
+   */
+  async heartbeat(
+    licenseKey: string,
+    identity: string
+  ): Promise<HeartbeatResult> {
+    const identityHash = hashIdentity(identity, this.config.appSecret);
+
+    const body = JSON.stringify({
+      license_key: licenseKey,
+      identity_hash: identityHash,
+    });
+
+    const data = await this.apiPost<{
+      server_timestamp: number;
+      status: string;
+      offline_token?: string;
+    }>("/api/v1/sdk/heartbeat", body);
+
+    // 如果服务端返回了新的 offline_token，更新缓存
+    if (data.offline_token) {
+      this.storage.save({
+        offlineToken: data.offline_token,
+        lastVerifiedAt: Math.floor(Date.now() / 1000),
+        tokenVersion: 0,
+        licenseKey,
+      });
+    }
+
+    return {
+      serverTimestamp: data.server_timestamp,
+      status: data.status,
+      offlineToken: data.offline_token,
+    };
+  }
+
+  /**
+   * 监听授权状态变化
+   * @returns 取消监听函数
+   */
+  onStatusChange(callback: StatusChangeCallback): () => void {
+    this.statusListeners.push(callback);
+    return () => {
+      this.statusListeners = this.statusListeners.filter(
+        (cb) => cb !== callback
+      );
+    };
+  }
+
+  /**
+   * 到期前提醒
+   * @param daysBeforeExpiry 到期前多少天触发
+   * @returns 取消监听函数
+   */
+  onExpiring(daysBeforeExpiry: number, callback: () => void): () => void {
+    const listener = { days: daysBeforeExpiry, callback, fired: false };
+    this.expiryListeners.push(listener);
+    return () => {
+      this.expiryListeners = this.expiryListeners.filter(
+        (l) => l !== listener
+      );
+    };
+  }
+
+  /**
+   * 销毁（清理心跳定时器和监听器）
+   */
+  destroy(): void {
+    this.stopHeartbeat();
+    this.statusListeners = [];
+    this.expiryListeners = [];
+    this.lastStatus = null;
+  }
+
+  // ===== 内部方法 =====
+
+  /** 发送带 HMAC 签名的 POST 请求 */
+  private async apiPost<T>(path: string, body: string): Promise<T> {
+    const headers = signRequest({
+      method: "POST",
+      path,
+      body,
+      appId: this.config.appId,
+      appSecret: this.config.appSecret,
+    });
+
+    const url = `${this.config.baseUrl}${path}`;
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          ...headers,
+          "Content-Type": "application/json",
+        },
+        body,
+      });
+    } catch (err) {
+      throw new ClavisError(
+        ErrorCodes.NETWORK_ERROR,
+        `网络请求失败: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+
+    const json = (await response.json()) as ApiResponse<T>;
+
+    if (!response.ok || !json.success) {
+      const code = json.error?.code || ErrorCodes.API_ERROR;
+      const message = json.error?.message || `API 请求失败: ${response.status}`;
+      throw new ClavisError(code, message);
+    }
+
+    return json.data as T;
+  }
+
+  /** 启动自动心跳 */
+  private startHeartbeat(licenseKey: string, identity: string): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(async () => {
+      try {
+        await this.heartbeat(licenseKey, identity);
+      } catch {
+        // 心跳失败静默处理，不影响主流程
+      }
+    }, this.config.heartbeatInterval * 1000);
+
+    // 允许 Node.js 进程正常退出
+    if (this.heartbeatTimer && typeof this.heartbeatTimer === "object" && "unref" in this.heartbeatTimer) {
+      (this.heartbeatTimer as NodeJS.Timeout).unref();
+    }
+  }
+
+  /** 停止心跳 */
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+  }
+
+  /** 通知状态变化 */
+  private notifyStatusChange(status: LicenseStatus): void {
+    // 只在状态变化时通知
+    if (
+      this.lastStatus === null ||
+      this.lastStatus.valid !== status.valid ||
+      this.lastStatus.tier !== status.tier
+    ) {
+      this.lastStatus = status;
+      for (const cb of this.statusListeners) {
+        try {
+          cb(status);
+        } catch {
+          // 回调异常不影响 SDK
+        }
+      }
+    }
+  }
+
+  /** 检查到期提醒 */
+  private checkExpiryReminders(daysRemaining: number | null): void {
+    if (daysRemaining === null) return;
+
+    for (const listener of this.expiryListeners) {
+      if (!listener.fired && daysRemaining <= listener.days) {
+        listener.fired = true;
+        try {
+          listener.callback();
+        } catch {
+          // 回调异常不影响 SDK
+        }
+      }
+    }
+  }
+
+  /** 从激活结果构造 LicenseStatus */
+  private buildStatusFromActivate(
+    result: ActivateResult,
+    isOffline: boolean
+  ): LicenseStatus {
+    let daysRemaining: number | null = null;
+    if (result.expiresAt) {
+      const expiresMs = new Date(result.expiresAt).getTime();
+      daysRemaining = Math.ceil((expiresMs - Date.now()) / (86400 * 1000));
+      if (daysRemaining < 0) daysRemaining = 0;
+    }
+
+    return {
+      valid: result.success,
+      tier: result.tier,
+      features: result.features,
+      expiresAt: result.expiresAt,
+      daysRemaining,
+      isOffline,
+      isTrial: result.tier === "trial",
+      inGracePeriod: false,
+    };
+  }
+}