@nietzsci/clavis 0.1.0

package/src/crypto.ts

@@ -0,0 +1,84 @@
+// ============================================================
+// Ed25519 离线验签
+// 与服务端 src/lib/crypto.ts 的 signPayload/verifyToken 完全对齐
+// ============================================================
+
+import nacl from "tweetnacl";
+import { decodeBase64, encodeUTF8 } from "tweetnacl-util";
+import type { TokenPayload } from "./types";
+
+// ---- base64url 辅助 ----
+
+function fromBase64Url(b64url: string): string {
+  let b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  while (b64.length % 4 !== 0) b64 += "=";
+  return b64;
+}
+
+/**
+ * 验证 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
+ */
+export function verifyOfflineToken(
+  token: string,
+  publicKeyBase64: string
+): TokenPayload | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 2) return null;
+
+    const [payloadBase64Url, signatureBase64Url] = parts;
+
+    // 1. 解码 payload JSON 字符串
+    // 服务端用 Buffer.from(payloadJson).toString("base64") 再转 base64url
+    // 所以这里逆向：base64url → base64 → Buffer → UTF-8
+    const payloadB64 = fromBase64Url(payloadBase64Url);
+    const payloadBytes = Uint8Array.from(atob(payloadB64), (c) =>
+      c.charCodeAt(0)
+    );
+    const payloadJson = new TextDecoder().decode(payloadBytes);
+
+    // 2. 解码签名（64 字节）
+    const signatureB64 = fromBase64Url(signatureBase64Url);
+    const signatureBytes = decodeBase64(signatureB64);
+
+    // 3. 解码公钥
+    const publicKeyBytes = decodeBase64(publicKeyBase64);
+
+    // 4. 重新 encode payloadJson 为字节（与签名时一致）
+    const messageBytes = new TextEncoder().encode(payloadJson);
+
+    // 5. 构造 signedMessage = signature(64) + message
+    const signedMessage = new Uint8Array(
+      signatureBytes.length + messageBytes.length
+    );
+    signedMessage.set(signatureBytes);
+    signedMessage.set(messageBytes, signatureBytes.length);
+
+    // 6. 验签
+    const verified = nacl.sign.open(signedMessage, publicKeyBytes);
+    if (!verified) return null;
+
+    // 7. 解析 payload
+    return JSON.parse(payloadJson) as TokenPayload;
+  } catch {
+    return null;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,46 @@
+// ============================================================
+// Clavis SDK 错误码
+// ============================================================
+
+export class ClavisError extends Error {
+  code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "ClavisError";
+    this.code = code;
+  }
+}
+
+/** 错误码枚举 */
+export const ErrorCodes = {
+  // 网络
+  NETWORK_ERROR: "NETWORK_ERROR",
+  API_ERROR: "API_ERROR",
+
+  // 签名
+  INVALID_SIGNATURE: "INVALID_SIGNATURE",
+  MISSING_AUTH_HEADERS: "MISSING_AUTH_HEADERS",
+  TIMESTAMP_EXPIRED: "TIMESTAMP_EXPIRED",
+
+  // 授权码
+  LICENSE_NOT_FOUND: "LICENSE_NOT_FOUND",
+  LICENSE_EXPIRED: "LICENSE_EXPIRED",
+  LICENSE_REVOKED: "LICENSE_REVOKED",
+  ACTIVATION_LIMIT: "ACTIVATION_LIMIT",
+  ACTIVATION_NOT_FOUND: "ACTIVATION_NOT_FOUND",
+
+  // 离线验证
+  NO_CACHED_TOKEN: "NO_CACHED_TOKEN",
+  TOKEN_SIGNATURE_INVALID: "TOKEN_SIGNATURE_INVALID",
+  TOKEN_EXPIRED: "TOKEN_EXPIRED",
+  TOKEN_GRACE_EXPIRED: "TOKEN_GRACE_EXPIRED",
+  IDENTITY_MISMATCH: "IDENTITY_MISMATCH",
+  CLOCK_DRIFT_DETECTED: "CLOCK_DRIFT_DETECTED",
+
+  // 配置
+  MISSING_CONFIG: "MISSING_CONFIG",
+  INVALID_CONFIG: "INVALID_CONFIG",
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/src/fingerprint.ts

@@ -0,0 +1,46 @@
+// ============================================================
+// 设备指纹生成
+// ============================================================
+
+import crypto from "crypto";
+import os from "os";
+import type { DeviceInfo } from "./types";
+
+/**
+ * 生成设备机器码
+ *
+ * 取硬件特征的 HMAC-SHA256 哈希，格式化为 MC-XXXX-XXXX-XXXX-XXXX
+ * 同一台机器多次调用结果一致（确定性）
+ */
+export function getMachineCode(appSecret?: string): string {
+  const cpus = os.cpus();
+  const data = [
+    os.hostname(),
+    os.platform(),
+    os.arch(),
+    cpus[0]?.model || "",
+    cpus.length.toString(),
+    os.totalmem().toString(),
+  ].join("|");
+
+  const key = appSecret || "clavis-default-key";
+  const hash = crypto.createHmac("sha256", key).update(data).digest("hex");
+
+  // 格式化为 MC-XXXX-XXXX-XXXX-XXXX
+  return `MC-${hash.substring(0, 4).toUpperCase()}-${hash.substring(4, 8).toUpperCase()}-${hash.substring(8, 12).toUpperCase()}-${hash.substring(12, 16).toUpperCase()}`;
+}
+
+/**
+ * 获取设备信息
+ */
+export function getDeviceInfo(): DeviceInfo {
+  const cpus = os.cpus();
+  return {
+    os: os.platform(),
+    osVersion: os.release(),
+    hostname: os.hostname(),
+    arch: os.arch(),
+    cpuModel: cpus[0]?.model || "unknown",
+    totalMemory: os.totalmem(),
+  };
+}

package/src/hmac.ts

@@ -0,0 +1,67 @@
+// ============================================================
+// HMAC-SHA256 请求签名
+// 与服务端 src/lib/api-auth.ts 的 validateHmacSignature 完全对齐
+// ============================================================
+
+import crypto from "crypto";
+
+export 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 比较签名
+ */
+export function signRequest(params: {
+  method: string;
+  path: string;
+  body: string;
+  appId: string;
+  appSecret: string;
+}): SignedHeaders {
+  const timestamp = Math.floor(Date.now() / 1000).toString();
+  const nonce = crypto.randomUUID();
+
+  const bodyHash = crypto
+    .createHash("sha256")
+    .update(params.body || "")
+    .digest("hex");
+
+  const stringToSign = `${params.method.toUpperCase()}\n${params.path}\n${timestamp}\n${nonce}\n${bodyHash}`;
+
+  const signature = crypto
+    .createHmac("sha256", params.appSecret)
+    .update(stringToSign)
+    .digest("hex");
+
+  return {
+    "x-app-id": params.appId,
+    "x-timestamp": timestamp,
+    "x-nonce": nonce,
+    "x-signature": signature,
+  };
+}
+
+/**
+ * 生成 identity hash
+ *
+ * 服务端期望的 identity_hash = HMAC-SHA256(appSecret, identity).hex()
+ */
+export function hashIdentity(identity: string, appSecret: string): string {
+  return crypto
+    .createHmac("sha256", appSecret)
+    .update(identity)
+    .digest("hex");
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// ============================================================
+// @nietzsci/clavis 主入口
+// ============================================================
+
+// 主类（默认导出）
+import { Clavis } from "./client";
+export default Clavis;
+
+// 同时提供命名导出（兼容两种写法）
+export { Clavis } from "./client";
+
+// 类型
+export type {
+  ClavisConfig,
+  ActivateResult,
+  LicenseStatus,
+  TokenPayload,
+  HeartbeatResult,
+  PricingPlan,
+  DeviceInfo,
+  CacheData,
+  ApiResponse,
+} from "./types";
+
+// 错误
+export { ClavisError, ErrorCodes } from "./errors";
+export type { ErrorCode } from "./errors";
+
+// 工具函数
+export { verifyOfflineToken } from "./crypto";
+export { signRequest, hashIdentity } from "./hmac";
+export { getMachineCode, getDeviceInfo } from "./fingerprint";
+export { FileStorage } from "./storage";

package/src/storage.ts

@@ -0,0 +1,90 @@
+// ============================================================
+// 本地缓存管理（AES-256-GCM 加密）
+// ============================================================
+
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import type { CacheData } from "./types";
+
+/**
+ * 文件存储
+ *
+ * 缓存内容用 AES-256-GCM 加密，密钥由 identity 派生。
+ * 换设备（identity 不同）后旧缓存自动失效。
+ *
+ * 文件格式：iv(12) + tag(16) + ciphertext
+ */
+export class FileStorage {
+  private filePath: string;
+  private encryptionKey: Buffer;
+
+  constructor(storagePath: string, appId: string) {
+    // 缓存文件以 appId 区分，避免多应用冲突
+    const safeName = appId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    this.filePath = path.join(storagePath, `.clavis_${safeName}`);
+    // 密钥由 appId 派生（同一应用同一路径 = 同一密钥）
+    this.encryptionKey = crypto.createHash("sha256").update(appId).digest();
+  }
+
+  /** 保存缓存数据（AES-256-GCM 加密） */
+  save(data: CacheData): void {
+    const json = JSON.stringify(data);
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv("aes-256-gcm", this.encryptionKey, iv);
+    const encrypted = Buffer.concat([
+      cipher.update(json, "utf8"),
+      cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    const combined = Buffer.concat([iv, tag, encrypted]);
+
+    // 确保目录存在
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(this.filePath, combined);
+  }
+
+  /** 读取缓存数据（解密） */
+  load(): CacheData | null {
+    try {
+      if (!fs.existsSync(this.filePath)) return null;
+
+      const data = fs.readFileSync(this.filePath);
+      if (data.length < 28) return null; // iv(12) + tag(16) = 28 最小
+
+      const iv = data.subarray(0, 12);
+      const tag = data.subarray(12, 28);
+      const encrypted = data.subarray(28);
+
+      const decipher = crypto.createDecipheriv(
+        "aes-256-gcm",
+        this.encryptionKey,
+        iv
+      );
+      decipher.setAuthTag(tag);
+
+      const decrypted =
+        decipher.update(encrypted, undefined, "utf8") +
+        decipher.final("utf8");
+
+      return JSON.parse(decrypted) as CacheData;
+    } catch {
+      return null;
+    }
+  }
+
+  /** 清除缓存文件 */
+  clear(): void {
+    try {
+      if (fs.existsSync(this.filePath)) {
+        fs.unlinkSync(this.filePath);
+      }
+    } catch {
+      // 忽略删除失败
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+// ============================================================
+// Clavis SDK 类型定义
+// ============================================================
+
+/** SDK 初始化配置 */
+export 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;
+}
+
+/** 配置（所有字段已填充默认值） */
+export interface ClavisConfigResolved {
+  appId: string;
+  appSecret: string;
+  publicKey: string;
+  baseUrl: string;
+  storagePath: string;
+  offlineGraceDays: number;
+  heartbeatInterval: number;
+  autoHeartbeat: boolean;
+}
+
+/** 激活结果 */
+export interface ActivateResult {
+  success: boolean;
+  tier: string;
+  features: string[];
+  expiresAt: string | null;
+  offlineToken: string;
+}
+
+/** 授权状态 */
+export interface LicenseStatus {
+  valid: boolean;
+  tier: string;
+  features: string[];
+  expiresAt: string | null;
+  daysRemaining: number | null;
+  isOffline: boolean;
+  isTrial: boolean;
+  inGracePeriod: boolean;
+}
+
+/** 离线 Token Payload（与服务端 signPayload 的 payload 完全一致） */
+export 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;
+}
+
+/** 心跳结果 */
+export interface HeartbeatResult {
+  serverTimestamp: number;
+  status: string;
+  offlineToken?: string;
+}
+
+/** 定价方案 */
+export interface PricingPlan {
+  id: string;
+  tier: string;
+  name: string;
+  duration: string;
+  durationDays: number;
+  price: number;
+}
+
+/** 设备信息 */
+export interface DeviceInfo {
+  os: string;
+  osVersion: string;
+  hostname: string;
+  arch: string;
+  cpuModel: string;
+  totalMemory: number;
+}
+
+/** 本地缓存数据结构 */
+export interface CacheData {
+  offlineToken: string;
+  lastVerifiedAt: number;
+  tokenVersion: number;
+  licenseKey: string;
+}
+
+/** API 响应通用结构 */
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}