create-windy 0.1.0

package/template/packages/license-sdk/src/client.ts

@@ -0,0 +1,86 @@
+import type {
+  LicenseFailureReason,
+  LicenseUsageRecord,
+  SignedLicense,
+} from "@windy/shared";
+import type { LicenseSource, LicenseStorage } from "./storage.js";
+import type { LicensePublicKeySource } from "./verification.js";
+import { parseSignedLicense, validateLicenseDocument } from "./validation.js";
+
+export interface LicenseClientOptions {
+  licenseSource: LicenseSource;
+  stateStorage: LicenseStorage;
+  productCode: string;
+  machineCode: string;
+  publicKeys: LicensePublicKeySource;
+  now?: () => Date;
+  clockToleranceMs?: number;
+}
+
+export interface LicenseOpenResult {
+  valid: boolean;
+  license?: SignedLicense;
+  usage: LicenseUsageRecord;
+  failures: LicenseFailureReason[];
+}
+
+const LAST_TRUSTED_AT_KEY = "last-trusted-at";
+
+export class WindyLicenseClient {
+  private readonly now: () => Date;
+
+  constructor(private readonly options: LicenseClientOptions) {
+    this.now = options.now ?? (() => new Date());
+  }
+
+  async readLicense(): Promise<SignedLicense | undefined> {
+    const rawLicense = await this.options.licenseSource.readCurrent();
+    return rawLicense ? parseSignedLicense(rawLicense) : undefined;
+  }
+
+  async recordOpen(): Promise<LicenseOpenResult> {
+    const openedAt = this.now();
+    const rawLicense = await this.options.licenseSource.readCurrent();
+    const previousOpenedAt =
+      await this.options.stateStorage.read(LAST_TRUSTED_AT_KEY);
+
+    if (!rawLicense) {
+      return {
+        valid: false,
+        failures: ["invalid-format"],
+        usage: {
+          machineCode: this.options.machineCode,
+          openedAt: openedAt.toISOString(),
+          previousOpenedAt,
+          status: "invalid",
+          reason: "invalid-format",
+        },
+      };
+    }
+
+    const result = await validateLicenseDocument(rawLicense, {
+      productCode: this.options.productCode,
+      machineCode: this.options.machineCode,
+      publicKeys: this.options.publicKeys,
+      now: openedAt,
+      lastTrustedAt: previousOpenedAt,
+      clockToleranceMs: this.options.clockToleranceMs,
+    });
+    if (
+      !result.failures.includes("clock-rollback") &&
+      result.nextTrustedAt &&
+      result.nextTrustedAt !== previousOpenedAt
+    ) {
+      await this.options.stateStorage.write(
+        LAST_TRUSTED_AT_KEY,
+        result.nextTrustedAt,
+      );
+    }
+    return {
+      valid: result.valid,
+      license: result.license,
+      failures: result.failures,
+      usage: result.usage,
+    };
+  }
+}

package/template/packages/license-sdk/src/device.ts

@@ -0,0 +1,46 @@
+export interface DeviceCodeParts {
+  hostname?: string;
+  platform?: string;
+  arch?: string;
+  tenant?: string;
+}
+
+export function createDeviceCode(parts: DeviceCodeParts): string {
+  const stableParts = [
+    parts.hostname || "unknown-host",
+    parts.platform || "unknown-platform",
+    parts.arch || "unknown-arch",
+    parts.tenant || "default",
+  ];
+
+  return btoaSafe(stableParts.join("|"));
+}
+
+export function createDeviceQrPayload(machineCode: string): string {
+  return JSON.stringify({
+    type: "windy-device-code",
+    version: 1,
+    machineCode,
+  });
+}
+
+export function readDeviceCodeFromQrPayload(
+  payload: string,
+): string | undefined {
+  try {
+    const parsed = JSON.parse(payload) as { machineCode?: unknown };
+    return typeof parsed.machineCode === "string"
+      ? parsed.machineCode
+      : undefined;
+  } catch {
+    return payload.trim() || undefined;
+  }
+}
+
+function btoaSafe(value: string): string {
+  if (typeof btoa === "function") {
+    return btoa(value);
+  }
+
+  return Buffer.from(value, "utf8").toString("base64");
+}

package/template/packages/license-sdk/src/file-storage.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { WindyLicenseClient } from "./client.js";
+import {
+  FileSystemAtomicLicenseStore,
+  FixedPathLicenseSource,
+} from "./file-storage.js";
+import { MemoryLicenseStorage } from "./storage.js";
+import { LICENSE_V1_TEST_VECTOR } from "./v1-test-vector.js";
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { force: true, recursive: true })),
+  );
+});
+
+describe("filesystem License adapters", () => {
+  test("固定路径挂载复用统一 V1 校验器", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "runtime", "current.license.json");
+    const store = new FileSystemAtomicLicenseStore(path);
+    await store.replaceCurrentAtomically(
+      JSON.stringify({
+        formatVersion: 1,
+        algorithm: "ED25519",
+        publicKeyId: LICENSE_V1_TEST_VECTOR.keyId,
+        claims: LICENSE_V1_TEST_VECTOR.claims,
+        signature: LICENSE_V1_TEST_VECTOR.signature,
+      }),
+    );
+
+    const client = new WindyLicenseClient({
+      licenseSource: new FixedPathLicenseSource(path),
+      stateStorage: new MemoryLicenseStorage(),
+      productCode: "windy-platform",
+      machineCode: "machine-vector-001",
+      publicKeys: {
+        [LICENSE_V1_TEST_VECTOR.keyId]: LICENSE_V1_TEST_VECTOR.publicKeyPem,
+      },
+      now: () => new Date("2026-07-10T10:00:00.000Z"),
+    });
+
+    await expect(client.recordOpen()).resolves.toMatchObject({
+      valid: true,
+      failures: [],
+    });
+  });
+
+  test("模拟原子提交前崩溃时旧文件保持完整且临时文件被清理", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "current.license.json");
+    await writeFile(path, '{"license":"old"}', "utf8");
+    const store = new CrashBeforeCommitStore(path);
+
+    await expect(
+      store.replaceCurrentAtomically('{"license":"new"}'),
+    ).rejects.toThrow("模拟进程崩溃");
+
+    await expect(store.readCurrent()).resolves.toBe('{"license":"old"}');
+    expect(await readdir(directory)).toEqual(["current.license.json"]);
+  });
+});
+
+class CrashBeforeCommitStore extends FileSystemAtomicLicenseStore {
+  protected override async beforeCommit(): Promise<void> {
+    throw new Error("模拟进程崩溃");
+  }
+}
+
+async function temporaryDirectory(): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), "windy-license-sdk-"));
+  temporaryDirectories.push(directory);
+  return directory;
+}

package/template/packages/license-sdk/src/file-storage.ts

@@ -0,0 +1,77 @@
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import type { AtomicLicenseStore, LicenseSource } from "./storage.js";
+
+export class FixedPathLicenseSource implements LicenseSource {
+  constructor(protected readonly licensePath: string) {}
+
+  async readCurrent(): Promise<string | undefined> {
+    try {
+      return await readFile(this.licensePath, "utf8");
+    } catch (error) {
+      if (isMissingFile(error)) return undefined;
+      throw error;
+    }
+  }
+}
+
+/**
+ * Atomic filesystem adapter. Temporary data is synced before the same-directory
+ * rename; the directory is synced afterwards so a crash cannot expose a partial file.
+ */
+export class FileSystemAtomicLicenseStore
+  extends FixedPathLicenseSource
+  implements AtomicLicenseStore
+{
+  constructor(
+    licensePath: string,
+    private readonly fileMode = 0o600,
+  ) {
+    super(licensePath);
+  }
+
+  async replaceCurrentAtomically(value: string): Promise<void> {
+    const directory = dirname(this.licensePath);
+    const temporaryPath = join(
+      directory,
+      `.${basename(this.licensePath)}.${process.pid}.${randomUUID()}.tmp`,
+    );
+    await mkdir(directory, { recursive: true });
+
+    let temporaryFile: Awaited<ReturnType<typeof open>> | undefined;
+    try {
+      temporaryFile = await open(temporaryPath, "wx", this.fileMode);
+      await temporaryFile.writeFile(value, "utf8");
+      await temporaryFile.sync();
+      await temporaryFile.close();
+      temporaryFile = undefined;
+      await this.beforeCommit();
+      await rename(temporaryPath, this.licensePath);
+      await syncDirectory(directory);
+    } finally {
+      await temporaryFile?.close().catch(() => undefined);
+      await unlink(temporaryPath).catch(() => undefined);
+    }
+  }
+
+  /** Test seam for simulating a process failure before the atomic commit. */
+  protected async beforeCommit(): Promise<void> {}
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}

package/template/packages/license-sdk/src/installation.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from "bun:test";
+import { licenseVersionKey, type LicenseV1Claims } from "@windy/shared";
+import { LicenseInstaller } from "./installation.js";
+import type { AtomicLicenseStore } from "./storage.js";
+import { MemoryAtomicLicenseStore } from "./storage.js";
+import { createSignedLicenseV1 } from "./test-fixtures.js";
+
+function claims(overrides: Partial<LicenseV1Claims> = {}): LicenseV1Claims {
+  return {
+    licenseId: "license_1",
+    productCode: "windy-platform",
+    customer: { id: "customer_1", code: "C-1", name: "客户一" },
+    project: { id: "project_1", code: "P-1", name: "项目一" },
+    contract: { id: "contract_1", contractNumber: "HT-1", version: "1" },
+    machineCode: "machine_1",
+    issuedAt: "2026-07-10T00:00:00.000Z",
+    expiresAt: "2030-07-10T00:00:00.000Z",
+    licenseVersion: {
+      key: licenseVersionKey("standard"),
+      name: "普通付费版",
+    },
+    ...overrides,
+  };
+}
+
+function installer(
+  store: AtomicLicenseStore,
+  publicKeys: Record<string, string>,
+  trustedReplacementAuthority?: ConstructorParameters<
+    typeof LicenseInstaller
+  >[0]["trustedReplacementAuthority"],
+  trustedInvalidCurrentRecoveryAuthority?: ConstructorParameters<
+    typeof LicenseInstaller
+  >[0]["trustedInvalidCurrentRecoveryAuthority"],
+): LicenseInstaller {
+  return new LicenseInstaller({
+    store,
+    productCode: "windy-platform",
+    machineCode: "machine_1",
+    publicKeys,
+    now: new Date("2026-08-01T00:00:00.000Z"),
+    trustedReplacementAuthority,
+    trustedInvalidCurrentRecoveryAuthority,
+  });
+}
+
+describe("LicenseInstaller", () => {
+  test("签发时间更新的 License 立即替换，即使新到期时间更短", async () => {
+    const current = createSignedLicenseV1(claims(), "key_current");
+    const candidate = createSignedLicenseV1(
+      claims({
+        licenseId: "license_2",
+        issuedAt: "2026-07-20T00:00:00.000Z",
+        expiresAt: "2027-07-20T00:00:00.000Z",
+        licenseVersion: {
+          key: licenseVersionKey("advanced"),
+          name: "高级付费版",
+        },
+      }),
+      "key_candidate",
+    );
+    const store = new MemoryAtomicLicenseStore(JSON.stringify(current.license));
+
+    const result = await installer(store, {
+      key_current: current.publicKeyPem,
+      key_candidate: candidate.publicKeyPem,
+    }).install(JSON.stringify(candidate.license));
+
+    expect(result.status).toBe("installed");
+    expect(result.license?.claims.expiresAt).toBe("2027-07-20T00:00:00.000Z");
+    expect(JSON.parse((await store.readCurrent())!).claims.licenseId).toBe(
+      "license_2",
+    );
+  });
+
+  test("历史 License 不能覆盖签发时间更晚的当前 License", async () => {
+    const current = createSignedLicenseV1(
+      claims({
+        licenseId: "license_new",
+        issuedAt: "2026-07-20T00:00:00.000Z",
+      }),
+      "key_current",
+    );
+    const old = createSignedLicenseV1(
+      claims({
+        licenseId: "license_old",
+        issuedAt: "2026-07-10T00:00:00.000Z",
+      }),
+      "key_old",
+    );
+    const original = JSON.stringify(current.license);
+    const store = new MemoryAtomicLicenseStore(original);
+
+    const result = await installer(store, {
+      key_current: current.publicKeyPem,
+      key_old: old.publicKeyPem,
+    }).install(JSON.stringify(old.license));
+
+    expect(result).toMatchObject({
+      status: "rejected",
+      failures: ["license-not-newer"],
+    });
+    expect(await store.readCurrent()).toBe(original);
+  });
+
+  test("篡改 signed issuedAt 不能伪装成新 License", async () => {
+    const current = createSignedLicenseV1(claims(), "key_current");
+    const candidate = createSignedLicenseV1(
+      claims({ licenseId: "license_2", issuedAt: "2026-07-05T00:00:00.000Z" }),
+      "key_candidate",
+    );
+    const original = JSON.stringify(current.license);
+    const store = new MemoryAtomicLicenseStore(original);
+    const tampered = {
+      ...candidate.license,
+      claims: {
+        ...candidate.license.claims,
+        issuedAt: "2026-07-20T00:00:00.000Z",
+      },
+    };
+
+    const result = await installer(store, {
+      key_current: current.publicKeyPem,
+      key_candidate: candidate.publicKeyPem,
+    }).install(JSON.stringify(tampered));
+
+    expect(result.failures).toEqual(["invalid-signature"]);
+    expect(await store.readCurrent()).toBe(original);
+  });
+
+  test("可信替换关系可显式授权非递增 issuedAt 的替换", async () => {
+    const current = createSignedLicenseV1(
+      claims({
+        licenseId: "license_current",
+        issuedAt: "2026-07-20T00:00:00.000Z",
+      }),
+      "key_current",
+    );
+    const replacement = createSignedLicenseV1(
+      claims({
+        licenseId: "license_replacement",
+        issuedAt: "2026-07-19T00:00:00.000Z",
+      }),
+      "key_replacement",
+    );
+    const store = new MemoryAtomicLicenseStore(JSON.stringify(current.license));
+
+    const result = await installer(
+      store,
+      {
+        key_current: current.publicKeyPem,
+        key_replacement: replacement.publicKeyPem,
+      },
+      ({ current: installed, candidate }) =>
+        installed.claims.licenseId === "license_current" &&
+        candidate.claims.licenseId === "license_replacement",
+    ).install(JSON.stringify(replacement.license));
+
+    expect(result.status).toBe("installed");
+  });
+
+  test("未知公钥和写入失败都不覆盖当前 License", async () => {
+    const current = createSignedLicenseV1(claims(), "key_current");
+    const candidate = createSignedLicenseV1(
+      claims({ licenseId: "license_2", issuedAt: "2026-07-20T00:00:00.000Z" }),
+      "key_unknown",
+    );
+    const original = JSON.stringify(current.license);
+    const unknownKeyStore = new MemoryAtomicLicenseStore(original);
+
+    const unknownKeyResult = await installer(unknownKeyStore, {
+      key_current: current.publicKeyPem,
+    }).install(JSON.stringify(candidate.license));
+    expect(unknownKeyResult.failures).toContain("unknown-public-key");
+    expect(await unknownKeyStore.readCurrent()).toBe(original);
+
+    const failingStore = new FailingAtomicStore(original, false);
+    const storageResult = await installer(failingStore, {
+      key_current: current.publicKeyPem,
+      key_unknown: candidate.publicKeyPem,
+    }).install(JSON.stringify(candidate.license));
+    expect(storageResult.failures).toEqual(["storage-failure"]);
+    expect(await failingStore.readCurrent()).toBe(original);
+  });
+
+  test("提交完成后适配器报错时通过回读确认新文件完整", async () => {
+    const candidate = createSignedLicenseV1(claims(), "key_candidate");
+    const store = new FailingAtomicStore(undefined, true);
+
+    const result = await installer(store, {
+      key_candidate: candidate.publicKeyPem,
+    }).install(JSON.stringify(candidate.license));
+
+    expect(result.status).toBe("installed");
+    expect(JSON.parse((await store.readCurrent())!).claims.licenseId).toBe(
+      "license_1",
+    );
+  });
+
+  test("损坏 current 只在可信恢复授权后由同一安装器原子替换", async () => {
+    const candidate = createSignedLicenseV1(claims(), "key_candidate");
+    const store = new MemoryAtomicLicenseStore("{broken");
+    const publicKeys = { key_candidate: candidate.publicKeyPem };
+
+    const rejected = await installer(store, publicKeys).install(
+      JSON.stringify(candidate.license),
+    );
+    expect(rejected.failures).toEqual(["current-license-invalid"]);
+    expect(await store.readCurrent()).toBe("{broken");
+
+    const recovered = await installer(
+      store,
+      publicKeys,
+      undefined,
+      ({ rawCurrent, candidate: verifiedCandidate }) =>
+        rawCurrent === "{broken" &&
+        verifiedCandidate.claims.licenseId === "license_1",
+    ).install(JSON.stringify(candidate.license));
+
+    expect(recovered.status).toBe("installed");
+    expect(JSON.parse((await store.readCurrent())!).claims.licenseId).toBe(
+      "license_1",
+    );
+  });
+});
+
+class FailingAtomicStore implements AtomicLicenseStore {
+  constructor(
+    private value: string | undefined,
+    private readonly commitBeforeFailure: boolean,
+  ) {}
+
+  readCurrent(): string | undefined {
+    return this.value;
+  }
+
+  replaceCurrentAtomically(value: string): never {
+    if (this.commitBeforeFailure) this.value = value;
+    throw new Error("模拟磁盘写入失败");
+  }
+}

package/template/packages/license-sdk/src/installation.ts

@@ -0,0 +1,150 @@
+import type { LicenseFailureReason, SignedLicense } from "@windy/shared";
+import { canonicalizeJson } from "./canonical-json.js";
+import type { AtomicLicenseStore } from "./storage.js";
+import type { LicenseValidationOptions } from "./validation.js";
+import {
+  validateLicenseDocument,
+  verifyLicenseDocument,
+} from "./validation.js";
+
+export type LicenseInstallFailure =
+  | LicenseFailureReason
+  | "current-license-invalid"
+  | "license-not-newer"
+  | "storage-failure";
+
+export interface LicenseInstallResult {
+  status: "installed" | "unchanged" | "rejected";
+  license?: SignedLicense;
+  failures: LicenseInstallFailure[];
+}
+
+export type TrustedReplacementAuthority = (input: {
+  current: SignedLicense;
+  candidate: SignedLicense;
+}) => boolean | Promise<boolean>;
+
+export type TrustedInvalidCurrentRecoveryAuthority = (input: {
+  rawCurrent: string;
+  candidate: SignedLicense;
+}) => boolean | Promise<boolean>;
+
+export interface LicenseInstallerOptions extends Omit<
+  LicenseValidationOptions,
+  "lastTrustedAt"
+> {
+  store: AtomicLicenseStore;
+  /** Must resolve from authenticated, locally trusted replacement metadata. */
+  trustedReplacementAuthority?: TrustedReplacementAuthority;
+  /** Must only be enabled by an authenticated, audited local recovery flow. */
+  trustedInvalidCurrentRecoveryAuthority?: TrustedInvalidCurrentRecoveryAuthority;
+}
+
+export class LicenseInstaller {
+  constructor(private readonly options: LicenseInstallerOptions) {}
+
+  async install(rawCandidate: string): Promise<LicenseInstallResult> {
+    const candidateResult = await validateLicenseDocument(rawCandidate, {
+      productCode: this.options.productCode,
+      machineCode: this.options.machineCode,
+      publicKeys: this.options.publicKeys,
+      now: this.options.now,
+      clockToleranceMs: this.options.clockToleranceMs,
+    });
+    const candidate = candidateResult.license;
+    if (!candidateResult.valid || !candidate) {
+      return {
+        status: "rejected",
+        failures: candidateResult.failures,
+      };
+    }
+
+    let rawCurrent: string | undefined;
+    try {
+      rawCurrent = await this.options.store.readCurrent();
+    } catch {
+      return { status: "rejected", failures: ["storage-failure"] };
+    }
+
+    if (rawCurrent) {
+      const currentResult = await verifyLicenseDocument(
+        rawCurrent,
+        this.options.publicKeys,
+      );
+      const current = currentResult.license;
+      if (!currentResult.valid || !current) {
+        const recoveryAllowed = Boolean(
+          await this.options.trustedInvalidCurrentRecoveryAuthority?.({
+            rawCurrent,
+            candidate,
+          }),
+        );
+        if (!recoveryAllowed) {
+          return {
+            status: "rejected",
+            failures: ["current-license-invalid"],
+          };
+        }
+      } else {
+        if (sameLicense(current, candidate)) {
+          return { status: "unchanged", license: current, failures: [] };
+        }
+        if (!(await this.isNewerOrReplacement(current, candidate))) {
+          return {
+            status: "rejected",
+            license: current,
+            failures: ["license-not-newer"],
+          };
+        }
+      }
+    }
+
+    const serializedCandidate = canonicalizeJson(candidate);
+    try {
+      await this.options.store.replaceCurrentAtomically(serializedCandidate);
+      return { status: "installed", license: candidate, failures: [] };
+    } catch {
+      return this.resolveUncertainCommit(candidate);
+    }
+  }
+
+  private async isNewerOrReplacement(
+    current: SignedLicense,
+    candidate: SignedLicense,
+  ): Promise<boolean> {
+    if (
+      Date.parse(candidate.claims.issuedAt) >
+      Date.parse(current.claims.issuedAt)
+    ) {
+      return true;
+    }
+    return Boolean(
+      await this.options.trustedReplacementAuthority?.({ current, candidate }),
+    );
+  }
+
+  private async resolveUncertainCommit(
+    candidate: SignedLicense,
+  ): Promise<LicenseInstallResult> {
+    try {
+      const committedRaw = await this.options.store.readCurrent();
+      const committed = committedRaw
+        ? await verifyLicenseDocument(committedRaw, this.options.publicKeys)
+        : undefined;
+      if (committed?.license && sameLicense(committed.license, candidate)) {
+        return { status: "installed", license: candidate, failures: [] };
+      }
+    } catch {
+      // The adapter could not prove which complete value survived.
+    }
+    return { status: "rejected", failures: ["storage-failure"] };
+  }
+}
+
+function sameLicense(left: SignedLicense, right: SignedLicense): boolean {
+  return (
+    left.claims.licenseId === right.claims.licenseId &&
+    left.publicKeyId === right.publicKeyId &&
+    left.signature === right.signature
+  );
+}