create-windy 0.1.0

package/template/packages/license-sdk/src/offline-code.ts

@@ -0,0 +1,319 @@
+import { strFromU8, strToU8, zlibSync } from "fflate";
+import type { SignedLicense } from "@windy/shared";
+import { canonicalizeJson } from "./canonical-json.js";
+import { parseSignedLicense } from "./license-parser.js";
+import {
+  decodeBase32,
+  encodeBase32,
+  isBase32Character,
+  segmentChecksum,
+} from "./offline-code-base32.js";
+import {
+  decodeEd25519Signature,
+  ED25519_SIGNATURE_BYTES,
+  encodeEd25519Signature,
+  fromCompactTuple,
+  toCompactTuple,
+} from "./offline-code-wire.js";
+import { OFFLINE_ACTIVATION_CODE_LIMITS } from "./offline-code-limits.js";
+import {
+  decompressOfflineCode,
+  OfflineCodeDecompressionLimitError,
+} from "./offline-code-decompression.js";
+
+const PREFIX = "W1";
+const DATA_CHARACTERS_PER_SEGMENT = 25;
+const CHECKSUM_CHARACTERS = 2;
+const MAX_CANONICAL_BYTES = OFFLINE_ACTIVATION_CODE_LIMITS.decompressedBytes;
+
+export type OfflineActivationCodeErrorCode =
+  | "empty"
+  | "invalid-prefix"
+  | "unsupported-version"
+  | "invalid-character"
+  | "invalid-length"
+  | "input-too-long"
+  | "decompression-limit"
+  | "group-checksum"
+  | "payload-checksum"
+  | "damaged-payload"
+  | "invalid-license";
+
+export class OfflineActivationCodeError extends Error {
+  constructor(
+    readonly code: OfflineActivationCodeErrorCode,
+    message: string,
+    readonly groupIndex?: number,
+  ) {
+    super(message);
+    this.name = "OfflineActivationCodeError";
+  }
+}
+
+export interface DecodedOfflineActivationCode {
+  license: SignedLicense;
+  canonicalLicense: string;
+}
+
+export function encodeOfflineActivationCode(license: SignedLicense): string {
+  const canonicalLicense = canonicalizeJson(license);
+  const validated = parseSignedLicense(canonicalLicense);
+  if (!validated) {
+    throw new OfflineActivationCodeError("invalid-license", "License 格式无效");
+  }
+  const raw = strToU8(JSON.stringify(toCompactTuple(validated)));
+  if (raw.byteLength > MAX_CANONICAL_BYTES) {
+    throw new OfflineActivationCodeError("invalid-license", "License 内容过长");
+  }
+  const compressed = zlibSync(raw, { level: 9 });
+  if (compressed.byteLength > OFFLINE_ACTIVATION_CODE_LIMITS.compressedBytes) {
+    throw new OfflineActivationCodeError(
+      "invalid-license",
+      "License 压缩内容过长",
+    );
+  }
+  let signature: Uint8Array;
+  try {
+    signature = decodeEd25519Signature(validated.signature);
+  } catch (error) {
+    throw new OfflineActivationCodeError(
+      "invalid-license",
+      error instanceof Error ? error.message : "License ED25519 签名无效",
+    );
+  }
+  const envelope = new Uint8Array(
+    4 + compressed.byteLength + ED25519_SIGNATURE_BYTES + 4,
+  );
+  writeUint32(envelope, 0, raw.byteLength);
+  envelope.set(compressed, 4);
+  envelope.set(signature, 4 + compressed.byteLength);
+  writeUint32(
+    envelope,
+    envelope.byteLength - 4,
+    crc32(strToU8(canonicalLicense)),
+  );
+  return formatGroups(encodeBase32(envelope));
+}
+
+export function decodeOfflineActivationCode(
+  input: string,
+): DecodedOfflineActivationCode {
+  const normalized = normalizeInput(input);
+  const encoded = verifyAndJoinGroups(normalized.slice(PREFIX.length));
+  let envelope: Uint8Array;
+  try {
+    envelope = decodeBase32(encoded);
+  } catch {
+    throw new OfflineActivationCodeError(
+      "damaged-payload",
+      "激活码末尾数据不完整或已损坏",
+    );
+  }
+  if (envelope.byteLength < 10) {
+    throw new OfflineActivationCodeError(
+      "invalid-length",
+      "激活码数据长度不足",
+    );
+  }
+  const expectedLength = readUint32(envelope, 0);
+  if (expectedLength === 0 || expectedLength > MAX_CANONICAL_BYTES) {
+    throw new OfflineActivationCodeError(
+      "damaged-payload",
+      "激活码声明的内容长度无效",
+    );
+  }
+  let raw: Uint8Array;
+  try {
+    raw = decompressOfflineCode(
+      envelope.subarray(4, -(ED25519_SIGNATURE_BYTES + 4)),
+      expectedLength,
+    );
+  } catch (error) {
+    if (error instanceof OfflineCodeDecompressionLimitError) {
+      throw new OfflineActivationCodeError(
+        "decompression-limit",
+        "离线激活码内容超过安全上限",
+      );
+    }
+    throw new OfflineActivationCodeError(
+      "damaged-payload",
+      "激活码压缩内容已损坏",
+    );
+  }
+  if (raw.byteLength !== expectedLength) {
+    throw new OfflineActivationCodeError(
+      "damaged-payload",
+      "激活码内容长度校验失败",
+    );
+  }
+  let compact: unknown;
+  try {
+    compact = JSON.parse(strFromU8(raw));
+  } catch {
+    throw new OfflineActivationCodeError(
+      "damaged-payload",
+      "激活码紧凑内容已损坏",
+    );
+  }
+  const signature = encodeEd25519Signature(
+    envelope.subarray(-(ED25519_SIGNATURE_BYTES + 4), -4),
+  );
+  let canonicalLicense: string;
+  try {
+    canonicalLicense = canonicalizeJson(fromCompactTuple(compact, signature));
+  } catch (error) {
+    throw new OfflineActivationCodeError(
+      "damaged-payload",
+      error instanceof Error ? error.message : "激活码紧凑字段无效",
+    );
+  }
+  if (
+    crc32(strToU8(canonicalLicense)) !==
+    readUint32(envelope, envelope.byteLength - 4)
+  ) {
+    throw new OfflineActivationCodeError(
+      "payload-checksum",
+      "激活码整体校验失败",
+    );
+  }
+  const license = parseSignedLicense(canonicalLicense);
+  if (!license || canonicalizeJson(license) !== canonicalLicense) {
+    throw new OfflineActivationCodeError(
+      "invalid-license",
+      "激活码不是规范的 License",
+    );
+  }
+  return { license, canonicalLicense };
+}
+
+export function splitOfflineActivationCode(code: string): string[] {
+  const normalized = normalizeInput(code);
+  const body = normalized.slice(PREFIX.length);
+  return [PREFIX, ...chunkGroups(body)];
+}
+
+export function offlineActivationCodeErrorMessage(error: unknown): string {
+  if (!(error instanceof OfflineActivationCodeError))
+    return "离线激活码无法识别";
+  if (error.code === "group-checksum" && error.groupIndex) {
+    return `第 ${error.groupIndex} 段输入有误，请对照签发页面重新输入`;
+  }
+  return error.message;
+}
+
+function normalizeInput(input: string): string {
+  if (input.length > OFFLINE_ACTIVATION_CODE_LIMITS.printedCharacters) {
+    throw new OfflineActivationCodeError("input-too-long", "离线激活码过长");
+  }
+  const compact = input.toUpperCase().replace(/[\s-]/g, "");
+  if (compact.length > OFFLINE_ACTIVATION_CODE_LIMITS.normalizedCharacters) {
+    throw new OfflineActivationCodeError("input-too-long", "离线激活码过长");
+  }
+  if (!compact)
+    throw new OfflineActivationCodeError("empty", "请输入离线激活码");
+  const normalized = compact.replace(/O/g, "0").replace(/[IL]/g, "1");
+  if (!normalized.startsWith("W")) {
+    throw new OfflineActivationCodeError(
+      "invalid-prefix",
+      "激活码必须以 W1 开头",
+    );
+  }
+  if (!normalized.startsWith(PREFIX)) {
+    throw new OfflineActivationCodeError(
+      "unsupported-version",
+      "不支持该激活码版本",
+    );
+  }
+  for (const character of normalized.slice(PREFIX.length)) {
+    if (!isBase32Character(character)) {
+      throw new OfflineActivationCodeError(
+        "invalid-character",
+        `激活码包含无法识别的字符：${character}`,
+      );
+    }
+  }
+  return normalized;
+}
+
+function formatGroups(encoded: string): string {
+  const segments: string[] = [];
+  for (
+    let offset = 0;
+    offset < encoded.length;
+    offset += DATA_CHARACTERS_PER_SEGMENT
+  ) {
+    const data = encoded.slice(offset, offset + DATA_CHARACTERS_PER_SEGMENT);
+    segments.push(data + segmentChecksum(data, segments.length));
+  }
+  return `${PREFIX}-${segments.join("-")}`;
+}
+
+function verifyAndJoinGroups(body: string): string {
+  if (body.length < 2) {
+    throw new OfflineActivationCodeError(
+      "invalid-length",
+      "激活码缺少数据分组",
+    );
+  }
+  const segments = chunkGroups(body);
+  return segments
+    .map((segment, index) => {
+      if (
+        segment.length <= CHECKSUM_CHARACTERS ||
+        segment.length > DATA_CHARACTERS_PER_SEGMENT + CHECKSUM_CHARACTERS
+      ) {
+        throw new OfflineActivationCodeError(
+          "invalid-length",
+          "激活码分段长度无效",
+          index + 1,
+        );
+      }
+      const data = segment.slice(0, -CHECKSUM_CHARACTERS);
+      if (
+        segment.slice(-CHECKSUM_CHARACTERS) !== segmentChecksum(data, index)
+      ) {
+        throw new OfflineActivationCodeError(
+          "group-checksum",
+          `第 ${index + 1} 段校验失败`,
+          index + 1,
+        );
+      }
+      return data;
+    })
+    .join("");
+}
+
+function chunkGroups(body: string): string[] {
+  const size = DATA_CHARACTERS_PER_SEGMENT + CHECKSUM_CHARACTERS;
+  const groups: string[] = [];
+  for (let offset = 0; offset < body.length; offset += size) {
+    groups.push(body.slice(offset, offset + size));
+  }
+  return groups;
+}
+
+function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function readUint32(bytes: Uint8Array, offset: number): number {
+  return new DataView(
+    bytes.buffer,
+    bytes.byteOffset,
+    bytes.byteLength,
+  ).getUint32(offset);
+}
+
+function writeUint32(bytes: Uint8Array, offset: number, value: number): void {
+  new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).setUint32(
+    offset,
+    value,
+  );
+}

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

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import { licenseVersionKey, type LicenseV1Claims } from "@windy/shared";
+import {
+  createLicenseSigningPayload,
+  getLicensePayloadHandler,
+  LicensePayloadError,
+  parseLicenseSigningPayload,
+} from "./payload.js";
+
+const claims: LicenseV1Claims = {
+  licenseId: "license_1",
+  productCode: "windy-platform",
+  customer: { id: "customer_1", code: "C001", name: "示例客户" },
+  project: { id: "project_1", code: "P001", name: "生产项目" },
+  contract: { id: "contract_1", contractNumber: "HT-001", version: "1" },
+  machineCode: "machine_1",
+  issuedAt: "2026-07-10T00:00:00.000Z",
+  expiresAt: "2027-07-10T00:00:00.000Z",
+  licenseVersion: {
+    key: licenseVersionKey("standard"),
+    name: "普通付费版",
+  },
+};
+
+describe("License V1 payload handler", () => {
+  test("字段构造顺序不同仍产生相同 canonical payload", () => {
+    const reversed = Object.fromEntries(
+      Object.entries(claims).reverse(),
+    ) as unknown as LicenseV1Claims;
+    const base = signedPayload(claims);
+    const reordered = signedPayload(reversed);
+
+    expect(reordered).toBe(base);
+    expect(parseLicenseSigningPayload(1, base).claims).toEqual(claims);
+    expect(base.startsWith('{"algorithm":"ED25519","claims":')).toBe(true);
+  });
+
+  test("拒绝未知版本、legacy 缺省版本和非 canonical payload", () => {
+    expect(() => getLicensePayloadHandler(2)).toThrow(LicensePayloadError);
+    expect(() => getLicensePayloadHandler(undefined)).toThrow(
+      "不支持的 License 格式版本",
+    );
+    const pretty = JSON.stringify(
+      {
+        formatVersion: 1,
+        algorithm: "ED25519",
+        publicKeyId: "key_1",
+        claims,
+      },
+      null,
+      2,
+    );
+    expect(() => parseLicenseSigningPayload(1, pretty)).toThrow(
+      "必须使用 RFC 8785 canonical JSON",
+    );
+  });
+
+  test("V1 明确拒绝 legacy 容量字段", () => {
+    expect(() =>
+      signedPayload({ ...claims, maxUsers: 10 } as unknown as LicenseV1Claims),
+    ).toThrow("未知：maxUsers");
+  });
+});
+
+function signedPayload(value: LicenseV1Claims): string {
+  return createLicenseSigningPayload({
+    formatVersion: 1,
+    algorithm: "ED25519",
+    publicKeyId: "key_1",
+    claims: value,
+  });
+}

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

@@ -0,0 +1,201 @@
+import type {
+  LicenseFormatVersion,
+  LicenseV1Claims,
+  SignedLicenseV1,
+} from "@windy/shared";
+import { canonicalizeJson } from "./canonical-json.js";
+
+export type LicensePayloadErrorCode =
+  | "INVALID_LICENSE_PAYLOAD"
+  | "UNSUPPORTED_LICENSE_FORMAT";
+
+export class LicensePayloadError extends Error {
+  constructor(
+    readonly code: LicensePayloadErrorCode,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "LicensePayloadError";
+  }
+}
+
+export interface LicenseV1SigningDocument {
+  formatVersion: 1;
+  algorithm: "ED25519";
+  publicKeyId: string;
+  claims: LicenseV1Claims;
+}
+
+export interface LicensePayloadHandler<
+  TVersion extends LicenseFormatVersion,
+  TDocument,
+> {
+  readonly formatVersion: TVersion;
+  serialize(document: TDocument): string;
+  parse(payload: string): TDocument;
+}
+
+export const licenseV1PayloadHandler: LicensePayloadHandler<
+  1,
+  LicenseV1SigningDocument
+> = {
+  formatVersion: 1,
+  serialize(document) {
+    try {
+      assertV1Document(document);
+      return canonicalizeJson(document);
+    } catch (error) {
+      throw normalizePayloadError(error);
+    }
+  },
+  parse(payload) {
+    try {
+      const document = parseJson(payload);
+      assertV1Document(document);
+      if (canonicalizeJson(document) !== payload) {
+        invalidPayload("V1 signed payload 必须使用 RFC 8785 canonical JSON");
+      }
+      return document;
+    } catch (error) {
+      throw normalizePayloadError(error);
+    }
+  },
+};
+
+export function getLicensePayloadHandler(
+  formatVersion: unknown,
+): LicensePayloadHandler<1, LicenseV1SigningDocument> {
+  if (formatVersion === 1) return licenseV1PayloadHandler;
+  throw unsupported(formatVersion);
+}
+
+export function createLicenseSigningPayload(
+  license: Omit<SignedLicenseV1, "signature">,
+): string {
+  return licenseV1PayloadHandler.serialize(license);
+}
+
+export function parseLicenseSigningPayload(
+  formatVersion: unknown,
+  payload: string,
+): LicenseV1SigningDocument {
+  return getLicensePayloadHandler(formatVersion).parse(payload);
+}
+
+export const parseLicenseSigningDocument = parseLicenseSigningPayload;
+
+function assertV1Document(
+  value: unknown,
+): asserts value is LicenseV1SigningDocument {
+  const document = object(value, "V1 signing document");
+  exactKeys(document, ["algorithm", "claims", "formatVersion", "publicKeyId"]);
+  if (document.formatVersion !== 1) invalidPayload("formatVersion 必须为 1");
+  if (document.algorithm !== "ED25519") {
+    invalidPayload("algorithm 必须为 ED25519");
+  }
+  text(document.publicKeyId, "publicKeyId");
+  assertV1Claims(document.claims);
+}
+
+function assertV1Claims(value: unknown): asserts value is LicenseV1Claims {
+  const claims = object(value, "claims");
+  exactKeys(claims, [
+    "contract",
+    "customer",
+    "expiresAt",
+    "issuedAt",
+    "licenseId",
+    "licenseVersion",
+    "machineCode",
+    "productCode",
+    "project",
+  ]);
+  for (const key of [
+    "licenseId",
+    "productCode",
+    "machineCode",
+    "issuedAt",
+    "expiresAt",
+  ] as const) {
+    text(claims[key], key);
+  }
+  reference(claims.customer, "customer");
+  reference(claims.project, "project");
+  const contract = object(claims.contract, "contract");
+  exactKeys(contract, ["contractNumber", "id", "version"]);
+  for (const key of ["id", "contractNumber", "version"] as const) {
+    text(contract[key], `contract.${key}`);
+  }
+  const version = object(claims.licenseVersion, "licenseVersion");
+  exactKeys(version, ["key", "name"]);
+  text(version.key, "licenseVersion.key");
+  text(version.name, "licenseVersion.name");
+}
+
+function reference(value: unknown, label: string): void {
+  const ref = object(value, label);
+  exactKeys(ref, ["code", "id", "name"]);
+  for (const key of ["id", "code", "name"] as const) {
+    text(ref[key], `${label}.${key}`);
+  }
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    invalidPayload(`${label} 必须为 JSON 对象`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+): void {
+  const actual = Object.keys(value);
+  const unexpected = actual.filter((key) => !allowed.includes(key));
+  const missing = allowed.filter((key) => !Object.hasOwn(value, key));
+  if (unexpected.length || missing.length) {
+    invalidPayload(
+      `字段不匹配（缺少：${missing.join(",") || "无"}；未知：${unexpected.join(",") || "无"}）`,
+    );
+  }
+}
+
+function text(value: unknown, label: string): void {
+  if (typeof value !== "string" || !value.length) {
+    invalidPayload(`${label} 必须为非空字符串`);
+  }
+}
+
+function parseJson(payload: string): unknown {
+  try {
+    return JSON.parse(payload);
+  } catch (error) {
+    throw new LicensePayloadError(
+      "INVALID_LICENSE_PAYLOAD",
+      "signed payload 不是有效 JSON",
+      { cause: error },
+    );
+  }
+}
+
+function invalidPayload(message: string): never {
+  throw new LicensePayloadError("INVALID_LICENSE_PAYLOAD", message);
+}
+
+function unsupported(formatVersion: unknown): never {
+  throw new LicensePayloadError(
+    "UNSUPPORTED_LICENSE_FORMAT",
+    `不支持的 License 格式版本：${String(formatVersion)}`,
+  );
+}
+
+function normalizePayloadError(error: unknown): LicensePayloadError {
+  if (error instanceof LicensePayloadError) return error;
+  return new LicensePayloadError(
+    "INVALID_LICENSE_PAYLOAD",
+    "License payload 不是有效的 canonical JSON",
+    { cause: error },
+  );
+}

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

@@ -0,0 +1,64 @@
+export interface LicenseStorage {
+  read(key: string): string | undefined | Promise<string | undefined>;
+  write(key: string, value: string): void | Promise<void>;
+}
+
+export interface LicenseSource {
+  readCurrent(): string | undefined | Promise<string | undefined>;
+}
+
+/**
+ * Adapter boundary for a single-current-License store.
+ * Implementations must leave either the old or the new complete document readable.
+ */
+export interface AtomicLicenseStore extends LicenseSource {
+  replaceCurrentAtomically(value: string): void | Promise<void>;
+}
+
+export class MemoryLicenseStorage implements LicenseStorage {
+  private readonly values = new Map<string, string>();
+
+  read(key: string): string | undefined {
+    return this.values.get(key);
+  }
+
+  write(key: string, value: string): void {
+    this.values.set(key, value);
+  }
+}
+
+export class MemoryAtomicLicenseStore implements AtomicLicenseStore {
+  constructor(private current?: string) {}
+
+  readCurrent(): string | undefined {
+    return this.current;
+  }
+
+  replaceCurrentAtomically(value: string): void {
+    this.current = value;
+  }
+}
+
+export class BrowserLicenseStorage implements LicenseStorage {
+  constructor(private readonly prefix = "windy-license") {}
+
+  read(key: string): string | undefined {
+    if (typeof window === "undefined") {
+      return undefined;
+    }
+
+    return window.localStorage.getItem(this.storageKey(key)) || undefined;
+  }
+
+  write(key: string, value: string): void {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    window.localStorage.setItem(this.storageKey(key), value);
+  }
+
+  private storageKey(key: string): string {
+    return `${this.prefix}:${key}`;
+  }
+}