@nietzsci/clavis 0.1.0

package/tests/sdk.test.ts

@@ -0,0 +1,548 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import nacl from "tweetnacl";
+import { encodeBase64 } from "tweetnacl-util";
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+import { verifyOfflineToken } from "../src/crypto";
+import { signRequest, hashIdentity } from "../src/hmac";
+import { getMachineCode, getDeviceInfo } from "../src/fingerprint";
+import { FileStorage } from "../src/storage";
+import { Clavis } from "../src/client";
+import { ClavisError } from "../src/errors";
+
+// ============================================================
+// 辅助：服务端签名函数（复刻自 src/lib/crypto.ts 的 signPayload）
+// ============================================================
+
+function toBase64Url(b64: string): string {
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+function serverSignPayload(payload: object, privateKeyBase64: string): string {
+  const payloadJson = JSON.stringify(payload);
+  const encoder = new TextEncoder();
+  const messageBytes = encoder.encode(payloadJson);
+  const privateKeyBytes = Uint8Array.from(
+    Buffer.from(privateKeyBase64, "base64")
+  );
+
+  const signedMessage = nacl.sign(messageBytes, privateKeyBytes);
+  const signature = signedMessage.slice(0, 64);
+
+  const payloadBase64Url = toBase64Url(
+    Buffer.from(payloadJson).toString("base64")
+  );
+  const signatureBase64Url = toBase64Url(encodeBase64(signature));
+
+  return `${payloadBase64Url}.${signatureBase64Url}`;
+}
+
+// ============================================================
+// 测试：Ed25519 离线验签
+// ============================================================
+
+describe("verifyOfflineToken", () => {
+  const keyPair = nacl.sign.keyPair();
+  const publicKeyBase64 = encodeBase64(keyPair.publicKey);
+  const privateKeyBase64 = encodeBase64(keyPair.secretKey);
+
+  const testPayload = {
+    app_id: "nc_test123",
+    license_id: "lic_001",
+    identity_hash: "abc123hash",
+    tier: "pro",
+    features: ["feature_a", "feature_b"],
+    issued_at: Math.floor(Date.now() / 1000),
+    expires_at: Math.floor(Date.now() / 1000) + 86400 * 30,
+    grace_until: Math.floor(Date.now() / 1000) + 86400 * 37,
+    token_version: 1,
+  };
+
+  it("应该正确验证服务端签发的 token", () => {
+    const token = serverSignPayload(testPayload, privateKeyBase64);
+    const result = verifyOfflineToken(token, publicKeyBase64);
+
+    expect(result).not.toBeNull();
+    expect(result!.app_id).toBe("nc_test123");
+    expect(result!.license_id).toBe("lic_001");
+    expect(result!.tier).toBe("pro");
+    expect(result!.features).toEqual(["feature_a", "feature_b"]);
+    expect(result!.token_version).toBe(1);
+  });
+
+  it("应该拒绝格式错误的 token", () => {
+    expect(verifyOfflineToken("invalid", publicKeyBase64)).toBeNull();
+    expect(verifyOfflineToken("a.b.c", publicKeyBase64)).toBeNull();
+    expect(verifyOfflineToken("", publicKeyBase64)).toBeNull();
+  });
+
+  it("应该拒绝签名不匹配的 token", () => {
+    const token = serverSignPayload(testPayload, privateKeyBase64);
+    // 用不同的公钥验证
+    const otherKeyPair = nacl.sign.keyPair();
+    const otherPublicKey = encodeBase64(otherKeyPair.publicKey);
+    expect(verifyOfflineToken(token, otherPublicKey)).toBeNull();
+  });
+
+  it("应该正确处理永久授权（expires_at = null）", () => {
+    const permanentPayload = { ...testPayload, expires_at: null };
+    const token = serverSignPayload(permanentPayload, privateKeyBase64);
+    const result = verifyOfflineToken(token, publicKeyBase64);
+
+    expect(result).not.toBeNull();
+    expect(result!.expires_at).toBeNull();
+  });
+
+  it("应该正确处理空 features", () => {
+    const noFeaturePayload = { ...testPayload, features: [] };
+    const token = serverSignPayload(noFeaturePayload, privateKeyBase64);
+    const result = verifyOfflineToken(token, publicKeyBase64);
+
+    expect(result).not.toBeNull();
+    expect(result!.features).toEqual([]);
+  });
+
+  it("应该正确处理中文和特殊字符的 payload", () => {
+    const unicodePayload = {
+      ...testPayload,
+      tier: "专业版",
+      features: ["功能A", "feature/special+chars="],
+    };
+    const token = serverSignPayload(unicodePayload, privateKeyBase64);
+    const result = verifyOfflineToken(token, publicKeyBase64);
+
+    expect(result).not.toBeNull();
+    expect(result!.tier).toBe("专业版");
+    expect(result!.features).toEqual(["功能A", "feature/special+chars="]);
+  });
+});
+
+// ============================================================
+// 测试：HMAC 签名
+// ============================================================
+
+describe("signRequest", () => {
+  it("应该生成正确格式的签名头", () => {
+    const headers = signRequest({
+      method: "POST",
+      path: "/api/v1/sdk/activate",
+      body: '{"license_key":"ABC","identity_hash":"hash"}',
+      appId: "nc_test123",
+      appSecret: "secret123",
+    });
+
+    expect(headers["x-app-id"]).toBe("nc_test123");
+    expect(headers["x-timestamp"]).toMatch(/^\d+$/);
+    expect(headers["x-nonce"]).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+    );
+    expect(headers["x-signature"]).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("相同参数应产生不同 nonce 和 signature", () => {
+    const params = {
+      method: "POST",
+      path: "/api/v1/sdk/activate",
+      body: "{}",
+      appId: "nc_test",
+      appSecret: "secret",
+    };
+
+    const h1 = signRequest(params);
+    const h2 = signRequest(params);
+
+    // nonce 不同 → signature 不同
+    expect(h1["x-nonce"]).not.toBe(h2["x-nonce"]);
+  });
+
+  it("空 body 应正常签名", () => {
+    const headers = signRequest({
+      method: "GET",
+      path: "/api/v1/test",
+      body: "",
+      appId: "nc_test",
+      appSecret: "secret",
+    });
+
+    expect(headers["x-signature"]).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("签名结果应与手动计算一致", () => {
+    const method = "POST";
+    const urlPath = "/api/v1/sdk/activate";
+    const body = '{"test":true}';
+    const appSecret = "test-secret-key";
+
+    const headers = signRequest({
+      method,
+      path: urlPath,
+      body,
+      appId: "nc_verify",
+      appSecret,
+    });
+
+    // 手动重算
+    const bodyHash = crypto
+      .createHash("sha256")
+      .update(body)
+      .digest("hex");
+    const stringToSign = `${method}\n${urlPath}\n${headers["x-timestamp"]}\n${headers["x-nonce"]}\n${bodyHash}`;
+    const expectedSig = crypto
+      .createHmac("sha256", appSecret)
+      .update(stringToSign)
+      .digest("hex");
+
+    expect(headers["x-signature"]).toBe(expectedSig);
+  });
+});
+
+// ============================================================
+// 测试：identity hash
+// ============================================================
+
+describe("hashIdentity", () => {
+  it("应该生成 HMAC-SHA256 哈希", () => {
+    const hash = hashIdentity("my-machine-code", "my-secret");
+    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("相同输入应产生相同输出", () => {
+    const h1 = hashIdentity("machine1", "secret");
+    const h2 = hashIdentity("machine1", "secret");
+    expect(h1).toBe(h2);
+  });
+
+  it("不同输入应产生不同输出", () => {
+    const h1 = hashIdentity("machine1", "secret");
+    const h2 = hashIdentity("machine2", "secret");
+    expect(h1).not.toBe(h2);
+  });
+});
+
+// ============================================================
+// 测试：设备指纹
+// ============================================================
+
+describe("getMachineCode", () => {
+  it("格式应为 MC-XXXX-XXXX-XXXX-XXXX", () => {
+    const code = getMachineCode();
+    expect(code).toMatch(/^MC-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}$/);
+  });
+
+  it("同一台机器多次调用结果一致", () => {
+    const c1 = getMachineCode("my-secret");
+    const c2 = getMachineCode("my-secret");
+    expect(c1).toBe(c2);
+  });
+
+  it("不同 appSecret 产生不同机器码", () => {
+    const c1 = getMachineCode("secret-a");
+    const c2 = getMachineCode("secret-b");
+    expect(c1).not.toBe(c2);
+  });
+});
+
+describe("getDeviceInfo", () => {
+  it("应该返回完整的设备信息", () => {
+    const info = getDeviceInfo();
+    expect(info.os).toBeTruthy();
+    expect(info.osVersion).toBeTruthy();
+    expect(info.hostname).toBeTruthy();
+    expect(info.arch).toBeTruthy();
+    expect(typeof info.totalMemory).toBe("number");
+    expect(info.totalMemory).toBeGreaterThan(0);
+  });
+});
+
+// ============================================================
+// 测试：FileStorage 加密/解密
+// ============================================================
+
+describe("FileStorage", () => {
+  const tmpDir = path.join(os.tmpdir(), `clavis-test-${Date.now()}`);
+  let storage: FileStorage;
+
+  beforeEach(() => {
+    fs.mkdirSync(tmpDir, { recursive: true });
+    storage = new FileStorage(tmpDir, "nc_test_app");
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("应该正确加密保存和解密读取", () => {
+    const data = {
+      offlineToken: "some.token.here",
+      lastVerifiedAt: Math.floor(Date.now() / 1000),
+      tokenVersion: 1,
+      licenseKey: "AAAAA-BBBBB-CCCCC-DDDDD-EEEEE",
+    };
+
+    storage.save(data);
+    const loaded = storage.load();
+
+    expect(loaded).not.toBeNull();
+    expect(loaded!.offlineToken).toBe(data.offlineToken);
+    expect(loaded!.lastVerifiedAt).toBe(data.lastVerifiedAt);
+    expect(loaded!.tokenVersion).toBe(data.tokenVersion);
+    expect(loaded!.licenseKey).toBe(data.licenseKey);
+  });
+
+  it("不同 appId 不能解密对方的缓存", () => {
+    const storage1 = new FileStorage(tmpDir, "nc_app_1");
+    const storage2 = new FileStorage(tmpDir, "nc_app_2");
+
+    storage1.save({
+      offlineToken: "secret-data",
+      lastVerifiedAt: 100,
+      tokenVersion: 1,
+      licenseKey: "KEY",
+    });
+
+    // storage2 不能读 storage1 的文件（文件名不同）
+    const loaded = storage2.load();
+    expect(loaded).toBeNull();
+  });
+
+  it("无缓存文件时返回 null", () => {
+    expect(storage.load()).toBeNull();
+  });
+
+  it("clear 后应返回 null", () => {
+    storage.save({
+      offlineToken: "test",
+      lastVerifiedAt: 100,
+      tokenVersion: 1,
+      licenseKey: "KEY",
+    });
+
+    storage.clear();
+    expect(storage.load()).toBeNull();
+  });
+
+  it("文件被篡改后应返回 null", () => {
+    storage.save({
+      offlineToken: "test",
+      lastVerifiedAt: 100,
+      tokenVersion: 1,
+      licenseKey: "KEY",
+    });
+
+    // 篡改文件
+    const files = fs.readdirSync(tmpDir);
+    const cacheFile = files.find((f) => f.startsWith(".clavis_"));
+    if (cacheFile) {
+      const filePath = path.join(tmpDir, cacheFile);
+      const data = fs.readFileSync(filePath);
+      data[20] = data[20] ^ 0xff; // 翻转一个字节
+      fs.writeFileSync(filePath, data);
+    }
+
+    expect(storage.load()).toBeNull();
+  });
+});
+
+// ============================================================
+// 测试：Clavis 类初始化
+// ============================================================
+
+describe("Clavis", () => {
+  it("应该用正确配置初始化", () => {
+    const clavis = new Clavis({
+      appId: "nc_test123",
+      appSecret: "secret-key-here",
+      publicKey: encodeBase64(nacl.sign.keyPair().publicKey),
+    });
+
+    expect(clavis).toBeInstanceOf(Clavis);
+    clavis.destroy();
+  });
+
+  it("缺少必填字段时应抛出 ClavisError", () => {
+    expect(
+      () =>
+        new Clavis({
+          appId: "",
+          appSecret: "secret",
+          publicKey: "key",
+        })
+    ).toThrow(ClavisError);
+
+    expect(
+      () =>
+        new Clavis({
+          appId: "nc_test",
+          appSecret: "",
+          publicKey: "key",
+        })
+    ).toThrow(ClavisError);
+  });
+
+  it("静态方法 getMachineCode 应可正常调用", () => {
+    const code = Clavis.getMachineCode();
+    expect(code).toMatch(/^MC-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}$/);
+  });
+
+  it("静态方法 getDeviceInfo 应可正常调用", () => {
+    const info = Clavis.getDeviceInfo();
+    expect(info.os).toBeTruthy();
+  });
+
+  describe("verifyOffline", () => {
+    const keyPair = nacl.sign.keyPair();
+    const publicKeyBase64 = encodeBase64(keyPair.publicKey);
+    const privateKeyBase64 = encodeBase64(keyPair.secretKey);
+    const tmpDir = path.join(os.tmpdir(), `clavis-offline-${Date.now()}`);
+
+    beforeEach(() => {
+      fs.mkdirSync(tmpDir, { recursive: true });
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it("无缓存时应返回 valid=false", () => {
+      const clavis = new Clavis({
+        appId: "nc_test",
+        appSecret: "secret",
+        publicKey: publicKeyBase64,
+        storagePath: tmpDir,
+        autoHeartbeat: false,
+      });
+
+      const status = clavis.verifyOffline();
+      expect(status.valid).toBe(false);
+      clavis.destroy();
+    });
+
+    it("有效 token 应返回 valid=true", () => {
+      const appId = "nc_test_offline";
+      const appSecret = "test-secret";
+      const identity = "machine-001";
+      const identityHash = hashIdentity(identity, appSecret);
+
+      const payload = {
+        app_id: appId,
+        license_id: "lic_001",
+        identity_hash: identityHash,
+        tier: "pro",
+        features: ["feat_a"],
+        issued_at: Math.floor(Date.now() / 1000),
+        expires_at: Math.floor(Date.now() / 1000) + 86400 * 30,
+        grace_until: Math.floor(Date.now() / 1000) + 86400 * 37,
+        token_version: 1,
+      };
+
+      const offlineToken = serverSignPayload(payload, privateKeyBase64);
+
+      // 写入缓存
+      const storage = new FileStorage(tmpDir, appId);
+      storage.save({
+        offlineToken,
+        lastVerifiedAt: Math.floor(Date.now() / 1000),
+        tokenVersion: 1,
+        licenseKey: "AAAAA-BBBBB-CCCCC-DDDDD-EEEEE",
+      });
+
+      const clavis = new Clavis({
+        appId,
+        appSecret,
+        publicKey: publicKeyBase64,
+        storagePath: tmpDir,
+        autoHeartbeat: false,
+      });
+
+      const status = clavis.verifyOffline(identity);
+      expect(status.valid).toBe(true);
+      expect(status.tier).toBe("pro");
+      expect(status.features).toEqual(["feat_a"]);
+      expect(status.isOffline).toBe(true);
+      expect(status.daysRemaining).toBeGreaterThan(0);
+
+      clavis.destroy();
+    });
+
+    it("过期且超过宽限期应返回 valid=false", () => {
+      const appId = "nc_expired";
+      const appSecret = "test-secret";
+
+      const payload = {
+        app_id: appId,
+        license_id: "lic_expired",
+        identity_hash: "hash",
+        tier: "standard",
+        features: [],
+        issued_at: Math.floor(Date.now() / 1000) - 86400 * 60,
+        expires_at: Math.floor(Date.now() / 1000) - 86400 * 10, // 10 天前过期
+        grace_until: Math.floor(Date.now() / 1000) - 86400 * 3, // 3 天前宽限也过了
+        token_version: 1,
+      };
+
+      const offlineToken = serverSignPayload(payload, privateKeyBase64);
+
+      const storage = new FileStorage(tmpDir, appId);
+      storage.save({
+        offlineToken,
+        lastVerifiedAt: Math.floor(Date.now() / 1000),
+        tokenVersion: 1,
+        licenseKey: "KEY",
+      });
+
+      const clavis = new Clavis({
+        appId,
+        appSecret,
+        publicKey: publicKeyBase64,
+        storagePath: tmpDir,
+        autoHeartbeat: false,
+      });
+
+      const status = clavis.verifyOffline();
+      expect(status.valid).toBe(false);
+      clavis.destroy();
+    });
+
+    it("hasFeature 应正确返回", () => {
+      const appId = "nc_feat_test";
+
+      const payload = {
+        app_id: appId,
+        license_id: "lic_feat",
+        identity_hash: "hash",
+        tier: "pro",
+        features: ["dark_mode", "export_pdf"],
+        issued_at: Math.floor(Date.now() / 1000),
+        expires_at: Math.floor(Date.now() / 1000) + 86400 * 30,
+        grace_until: Math.floor(Date.now() / 1000) + 86400 * 37,
+        token_version: 1,
+      };
+
+      const offlineToken = serverSignPayload(payload, privateKeyBase64);
+      const storage = new FileStorage(tmpDir, appId);
+      storage.save({
+        offlineToken,
+        lastVerifiedAt: Math.floor(Date.now() / 1000),
+        tokenVersion: 1,
+        licenseKey: "KEY",
+      });
+
+      const clavis = new Clavis({
+        appId,
+        appSecret: "secret",
+        publicKey: publicKeyBase64,
+        storagePath: tmpDir,
+        autoHeartbeat: false,
+      });
+
+      expect(clavis.hasFeature("dark_mode")).toBe(true);
+      expect(clavis.hasFeature("export_pdf")).toBe(true);
+      expect(clavis.hasFeature("not_exist")).toBe(false);
+
+      clavis.destroy();
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "lib": ["ES2020"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests"]
+}