create-windy 0.1.0

package/template/packages/example-work-order/src/manifest.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { workOrderModule } from "./manifest.js";
+
+describe("示例工单 Module Manifest", () => {
+  test("业务能力保留 API 与任务但不进入 Windy Admin Surface", () => {
+    const manifest = workOrderModule();
+
+    expect(manifest.name).not.toBe("system");
+    expect(manifest.features[0]).toMatchObject({
+      key: "work-order.ticket",
+      allowedLicenseVersions: ["standard", "advanced"],
+    });
+    expect(manifest.permissions.map(({ key }) => key)).toEqual([
+      "work-order.ticket.read",
+      "work-order.ticket.create",
+      "work-order.ticket.manage",
+    ]);
+    expect(manifest.apiPermissions).toHaveLength(5);
+    expect(manifest.menus).toEqual([]);
+    expect(manifest.adminRoutes).toEqual([]);
+    expect(manifest.auditActions).toEqual(
+      expect.arrayContaining(["crud.create", "crud.update", "crud.delete"]),
+    );
+    expect(manifest.tasks).toContainEqual(
+      expect.objectContaining({
+        key: "work-order.ticket.snapshot",
+        featureKey: "work-order.ticket",
+        permissionKey: "work-order.ticket.manage",
+      }),
+    );
+    expect(manifest.providers).toEqual([
+      {
+        key: "work-order.ticket.search",
+        kind: "search",
+        contractVersion: "1",
+        providerVersion: "0.1.0",
+        label: "示例工单",
+        enabledByDefault: true,
+        permissionKey: "work-order.ticket.read",
+        featureKey: "work-order.ticket",
+        deepLink: {
+          surface: "business",
+          routeTemplate: "/work-orders/:id",
+          idParameter: "id",
+        },
+      },
+    ]);
+    expect(manifest.metadata).toMatchObject({
+      removableExample: true,
+      persistence: "postgresql-with-memory-fallback",
+      uiComposition: "external-business-app",
+    });
+  });
+});

package/template/packages/example-work-order/src/manifest.ts

@@ -0,0 +1,120 @@
+import {
+  defineSearchProvider,
+  featureKey,
+  licenseVersionKey,
+} from "@windy/shared";
+
+const FEATURE_KEY = featureKey("work-order.ticket");
+
+export function workOrderModule() {
+  return {
+    name: "work-order",
+    version: "0.1.0",
+    label: "示例工单",
+    description: "可删除的业务模块示例，演示完整平台能力接入。",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      permission("read", "查看工单"),
+      permission("create", "创建工单"),
+      permission("manage", "管理工单"),
+    ],
+    apiPermissions: [
+      binding("GET", "/api/work-orders", "work-order.ticket.read"),
+      binding("GET", "/api/work-orders/:id", "work-order.ticket.read"),
+      binding("POST", "/api/work-orders", "work-order.ticket.create"),
+      binding("PUT", "/api/work-orders/:id", "work-order.ticket.manage"),
+      binding("DELETE", "/api/work-orders/:id", "work-order.ticket.manage"),
+    ],
+    features: [
+      {
+        key: FEATURE_KEY,
+        label: "示例工单",
+        module: "work-order",
+        description: "面向部门与负责人的轻量工单流转示例。",
+        visible: "visible" as const,
+        enabled: true,
+        stage: "stable" as const,
+        allowedLicenseVersions: [
+          licenseVersionKey("standard"),
+          licenseVersionKey("advanced"),
+        ],
+      },
+    ],
+    migrations: [],
+    schemaExports: [
+      {
+        key: "work-order.database.schema",
+        exportName: "workOrders",
+        migrationIds: ["0018_cheerful_alex_power"],
+      },
+    ],
+    tasks: [
+      {
+        key: "work-order.ticket.snapshot",
+        label: "工单待办快照",
+        description: "统计当前工单待办和高优先级积压，写入调度执行结果。",
+        permissionKey: "work-order.ticket.manage",
+        featureKey: FEATURE_KEY,
+        intervalSeconds: 900,
+        maxAttempts: 3,
+        retryDelaySeconds: 60,
+      },
+    ],
+    tools: [],
+    providers: [
+      defineSearchProvider({
+        key: "work-order.ticket.search",
+        kind: "search",
+        contractVersion: "1",
+        providerVersion: "0.1.0",
+        label: "示例工单",
+        enabledByDefault: true,
+        permissionKey: "work-order.ticket.read",
+        featureKey: FEATURE_KEY,
+        deepLink: {
+          surface: "business",
+          routeTemplate: "/work-orders/:id",
+          idParameter: "id",
+        },
+      }),
+    ],
+    auditActions: [
+      "crud.create" as const,
+      "crud.update" as const,
+      "crud.delete" as const,
+      "data.search" as const,
+    ],
+    metadata: {
+      removableExample: true,
+      persistence: "postgresql-with-memory-fallback",
+      dataOwnership: ["ownerId", "departmentId"],
+      uiComposition: "external-business-app",
+    },
+  };
+}
+
+function permission(action: "read" | "create" | "manage", label: string) {
+  return {
+    key: `work-order.ticket.${action}`,
+    label,
+    module: "work-order",
+    moduleLabel: "示例工单",
+    resource: "ticket",
+    resourceLabel: "工单",
+    action,
+  };
+}
+
+function binding(
+  method: "GET" | "POST" | "PUT" | "DELETE",
+  path: string,
+  permissionKey: string,
+) {
+  return {
+    method,
+    path,
+    permissionKey,
+    featureKey: "work-order.ticket",
+  };
+}

package/template/packages/example-work-order/src/schema.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { workOrderPriorities, workOrderWorkflowStatuses } from "./contract.js";
+
+const title = z.string().trim().min(1, "工单标题不能为空").max(120);
+const description = z.string().trim().min(1, "问题描述不能为空").max(2_000);
+const ownerId = z.string().trim().min(1).max(120);
+const departmentId = z.string().trim().min(1).max(120);
+
+export const createWorkOrderSchema = z
+  .object({
+    title,
+    description,
+    priority: z.enum(workOrderPriorities),
+  })
+  .strict();
+
+export const updateWorkOrderSchema = z
+  .object({
+    title: title.optional(),
+    description: description.optional(),
+    priority: z.enum(workOrderPriorities).optional(),
+    workflowStatus: z.enum(workOrderWorkflowStatuses).optional(),
+    ownerId: ownerId.optional(),
+    departmentId: departmentId.optional(),
+  })
+  .strict()
+  .refine((value) => Object.keys(value).length > 0, "至少提交一个变更字段");

package/template/packages/license-sdk/index.ts

@@ -0,0 +1,13 @@
+export * from "./src/canonical-json.js";
+export * from "./src/client.js";
+export * from "./src/device.js";
+export * from "./src/file-storage.js";
+export * from "./src/installation.js";
+export * from "./src/offline-code.js";
+export * from "./src/offline-code-limits.js";
+export * from "./src/bounded-json-body.js";
+export * from "./src/payload.js";
+export * from "./src/storage.js";
+export * from "./src/v1-test-vector.js";
+export * from "./src/validation.js";
+export * from "./src/verification.js";

package/template/packages/license-sdk/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@windy/license-sdk",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@windy/shared": "workspace:*",
+    "fflate": "^0.8.3"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./offline-code": "./src/offline-code.ts",
+    "./bounded-json-body": "./src/bounded-json-body.ts"
+  }
+}

package/template/packages/license-sdk/src/bounded-json-body.test.ts

@@ -0,0 +1,65 @@
+import { expect, test } from "bun:test";
+import {
+  BoundedJsonBodyError,
+  readBoundedJsonObject,
+} from "./bounded-json-body.js";
+import { OFFLINE_ACTIVATION_CODE_LIMITS } from "./offline-code-limits.js";
+
+test("Content-Length 超限时在读取请求流前稳定拒绝", async () => {
+  const request = new Request("http://localhost/api/license/runtime/install", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "content-length": String(OFFLINE_ACTIVATION_CODE_LIMITS.requestBytes + 1),
+    },
+    body: "{}",
+  });
+
+  await expect(readBoundedJsonObject(request)).rejects.toMatchObject({
+    code: "body-too-large",
+    status: 413,
+    message: "请求体过大，离线激活请求最多允许 64 KiB",
+  } satisfies Partial<BoundedJsonBodyError>);
+});
+
+test("拒绝与实际请求体不一致的 Content-Length", async () => {
+  const request = new Request("http://localhost/api/license/runtime/install", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "content-length": "1",
+    },
+    body: "{}",
+  });
+
+  await expect(readBoundedJsonObject(request)).rejects.toMatchObject({
+    code: "invalid-content-length",
+    status: 400,
+    message: "请求体长度与 Content-Length 不一致",
+  } satisfies Partial<BoundedJsonBodyError>);
+});
+
+test("无 Content-Length 的分块请求超过上限时停止读取", async () => {
+  const chunk = new Uint8Array(40 * 1024).fill(65);
+  let cancelled = false;
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(chunk);
+      controller.enqueue(chunk);
+    },
+    cancel() {
+      cancelled = true;
+    },
+  });
+  const request = new Request("http://localhost/api/license/runtime/install", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body,
+  });
+
+  await expect(readBoundedJsonObject(request)).rejects.toMatchObject({
+    code: "body-too-large",
+    status: 413,
+  } satisfies Partial<BoundedJsonBodyError>);
+  expect(cancelled).toBe(true);
+});

package/template/packages/license-sdk/src/bounded-json-body.ts

@@ -0,0 +1,135 @@
+import { OFFLINE_ACTIVATION_CODE_LIMITS } from "./offline-code-limits.js";
+
+export type BoundedJsonBodyErrorCode =
+  | "body-too-large"
+  | "invalid-content-length"
+  | "invalid-json"
+  | "invalid-object";
+
+export class BoundedJsonBodyError extends Error {
+  constructor(
+    readonly code: BoundedJsonBodyErrorCode,
+    message: string,
+    readonly status: 400 | 413,
+  ) {
+    super(message);
+    this.name = "BoundedJsonBodyError";
+  }
+}
+
+export async function readBoundedJsonObject(
+  request: Request,
+  maximumBytes = OFFLINE_ACTIVATION_CODE_LIMITS.requestBytes,
+): Promise<Record<string, unknown>> {
+  const declaredLength = parseContentLength(
+    request.headers.get("content-length"),
+  );
+  if (declaredLength !== undefined && declaredLength > maximumBytes) {
+    throw bodyTooLarge();
+  }
+
+  const bytes = await readBoundedBytes(request, maximumBytes);
+  if (declaredLength !== undefined && declaredLength !== bytes.byteLength) {
+    throw new BoundedJsonBodyError(
+      "invalid-content-length",
+      "请求体长度与 Content-Length 不一致",
+      400,
+    );
+  }
+
+  let value: unknown;
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    value = JSON.parse(text);
+  } catch {
+    throw new BoundedJsonBodyError(
+      "invalid-json",
+      "请求体必须是有效的 JSON",
+      400,
+    );
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new BoundedJsonBodyError(
+      "invalid-object",
+      "请求体必须是 JSON 对象",
+      400,
+    );
+  }
+  return value as Record<string, unknown>;
+}
+
+export function boundedJsonBodyErrorResponse(
+  error: unknown,
+): Response | undefined {
+  if (!(error instanceof BoundedJsonBodyError)) return undefined;
+  return Response.json(
+    {
+      error:
+        error.code === "body-too-large"
+          ? "LICENSE_REQUEST_BODY_TOO_LARGE"
+          : "LICENSE_REQUEST_BODY_INVALID",
+      reason: error.message,
+    },
+    { status: error.status },
+  );
+}
+
+function parseContentLength(value: string | null): number | undefined {
+  if (value === null) return undefined;
+  if (!/^(0|[1-9]\d*)$/.test(value)) {
+    throw new BoundedJsonBodyError(
+      "invalid-content-length",
+      "Content-Length 必须是有效的非负整数",
+      400,
+    );
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new BoundedJsonBodyError(
+      "invalid-content-length",
+      "Content-Length 超出安全范围",
+      400,
+    );
+  }
+  return parsed;
+}
+
+async function readBoundedBytes(
+  request: Request,
+  maximumBytes: number,
+): Promise<Uint8Array> {
+  if (!request.body) return new Uint8Array();
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value.byteLength > maximumBytes - total) {
+        await reader.cancel();
+        throw bodyTooLarge();
+      }
+      chunks.push(value);
+      total += value.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const joined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    joined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return joined;
+}
+
+function bodyTooLarge(): BoundedJsonBodyError {
+  return new BoundedJsonBodyError(
+    "body-too-large",
+    "请求体过大，离线激活请求最多允许 64 KiB",
+    413,
+  );
+}

package/template/packages/license-sdk/src/canonical-json.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { CanonicalJsonError, canonicalizeJson } from "./canonical-json.js";
+
+describe("RFC 8785 canonical JSON", () => {
+  test("按 UTF-16 key 排序并使用 ECMAScript primitive 序列化", () => {
+    expect(
+      canonicalizeJson({
+        numbers: [Number("333333333.33333329"), 1e30, 4.5, 0.002, 1e-27],
+        string: '€$\u000f\nA\'B"\\"/',
+        literals: [null, true, false],
+      }),
+    ).toBe(
+      '{"literals":[null,true,false],"numbers":[333333333.3333333,1e+30,4.5,0.002,1e-27],"string":"€$\\u000f\\nA\'B\\"\\\\\\"/"}',
+    );
+  });
+
+  test("拒绝非 JSON 值、非有限数与非法 Unicode", () => {
+    expect(() => canonicalizeJson({ value: undefined })).toThrow(
+      CanonicalJsonError,
+    );
+    expect(() => canonicalizeJson(Number.NaN)).toThrow(
+      "JCS 不支持 NaN 或无穷大",
+    );
+    expect(() => canonicalizeJson("\ud800")).toThrow(
+      "JCS 不支持未配对的 UTF-16 surrogate",
+    );
+  });
+});

package/template/packages/license-sdk/src/canonical-json.ts

@@ -0,0 +1,104 @@
+export type CanonicalJsonPrimitive = string | number | boolean | null;
+export type CanonicalJsonValue =
+  | CanonicalJsonPrimitive
+  | CanonicalJsonValue[]
+  | { [key: string]: CanonicalJsonValue };
+
+export type CanonicalJsonErrorCode =
+  | "CANONICAL_JSON_INVALID_TYPE"
+  | "CANONICAL_JSON_INVALID_NUMBER"
+  | "CANONICAL_JSON_INVALID_UNICODE"
+  | "CANONICAL_JSON_CYCLE";
+
+export class CanonicalJsonError extends Error {
+  constructor(
+    readonly code: CanonicalJsonErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "CanonicalJsonError";
+  }
+}
+
+/**
+ * RFC 8785 JSON Canonicalization Scheme (JCS) serializer.
+ *
+ * V1 intentionally accepts JSON values only: no undefined, BigInt, custom
+ * toJSON conversion, non-finite numbers, or unpaired UTF-16 surrogates.
+ */
+export function canonicalizeJson(value: unknown): string {
+  return serialize(value, new Set<object>());
+}
+
+function serialize(value: unknown, ancestors: Set<object>): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "string") return serializeString(value);
+  if (typeof value === "number") return serializeNumber(value);
+  if (typeof value !== "object") {
+    throw new CanonicalJsonError(
+      "CANONICAL_JSON_INVALID_TYPE",
+      `JCS 不支持 ${typeof value} 值`,
+    );
+  }
+  if (ancestors.has(value)) {
+    throw new CanonicalJsonError("CANONICAL_JSON_CYCLE", "JCS 不支持循环引用");
+  }
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => serialize(item, ancestors)).join(",")}]`;
+    }
+    const object = value as Record<string, unknown>;
+    const members = Object.keys(object)
+      .sort(compareUtf16)
+      .map(
+        (key) => `${serializeString(key)}:${serialize(object[key], ancestors)}`,
+      );
+    return `{${members.join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function serializeNumber(value: number): string {
+  if (!Number.isFinite(value)) {
+    throw new CanonicalJsonError(
+      "CANONICAL_JSON_INVALID_NUMBER",
+      "JCS 不支持 NaN 或无穷大",
+    );
+  }
+  return JSON.stringify(value);
+}
+
+function serializeString(value: string): string {
+  assertUnicodeScalarSequence(value);
+  return JSON.stringify(value);
+}
+
+function assertUnicodeScalarSequence(value: string): void {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!Number.isFinite(next) || next < 0xdc00 || next > 0xdfff) {
+        invalidUnicode();
+      }
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      invalidUnicode();
+    }
+  }
+}
+
+function invalidUnicode(): never {
+  throw new CanonicalJsonError(
+    "CANONICAL_JSON_INVALID_UNICODE",
+    "JCS 不支持未配对的 UTF-16 surrogate",
+  );
+}
+
+function compareUtf16(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

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

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { WindyLicenseClient } from "./client.js";
+import { MemoryAtomicLicenseStore, MemoryLicenseStorage } from "./storage.js";
+import { LICENSE_V1_TEST_VECTOR } from "./v1-test-vector.js";
+
+const vectorLicense = JSON.stringify({
+  formatVersion: 1,
+  algorithm: "ED25519",
+  publicKeyId: LICENSE_V1_TEST_VECTOR.keyId,
+  claims: LICENSE_V1_TEST_VECTOR.claims,
+  signature: LICENSE_V1_TEST_VECTOR.signature,
+});
+
+describe("WindyLicenseClient", () => {
+  test("使用固定向量和多公钥环打开 V1 License", async () => {
+    const client = new WindyLicenseClient({
+      licenseSource: new MemoryAtomicLicenseStore(vectorLicense),
+      stateStorage: new MemoryLicenseStorage(),
+      productCode: "windy-platform",
+      machineCode: "machine-vector-001",
+      publicKeys: {
+        unrelated: LICENSE_V1_TEST_VECTOR.publicKeyPem,
+        [LICENSE_V1_TEST_VECTOR.keyId]: LICENSE_V1_TEST_VECTOR.publicKeyPem,
+      },
+      now: () => new Date("2026-07-10T10:00:00.000Z"),
+    });
+
+    const result = await client.recordOpen();
+
+    expect(result.valid).toBe(true);
+    expect(result.failures).toEqual([]);
+    expect(result.license?.claims.licenseId).toBe("license_vector_v1");
+  });
+
+  test("未知 publicKeyId 时拒绝运行", async () => {
+    const client = new WindyLicenseClient({
+      licenseSource: new MemoryAtomicLicenseStore(vectorLicense),
+      stateStorage: new MemoryLicenseStorage(),
+      productCode: "windy-platform",
+      machineCode: "machine-vector-001",
+      publicKeys: {},
+      now: () => new Date("2026-07-10T10:00:00.000Z"),
+    });
+
+    const result = await client.recordOpen();
+
+    expect(result.valid).toBe(false);
+    expect(result.failures).toEqual(["unknown-public-key"]);
+  });
+
+  test("明显回拨持续暂停，小幅 NTP 偏差不误判且时间恢复后自动恢复", async () => {
+    let now = new Date("2026-07-10T10:00:00.000Z");
+    const state = new MemoryLicenseStorage();
+    const client = new WindyLicenseClient({
+      licenseSource: new MemoryAtomicLicenseStore(vectorLicense),
+      stateStorage: state,
+      productCode: "windy-platform",
+      machineCode: "machine-vector-001",
+      publicKeys: {
+        [LICENSE_V1_TEST_VECTOR.keyId]: LICENSE_V1_TEST_VECTOR.publicKeyPem,
+      },
+      clockToleranceMs: 5 * 60 * 1000,
+      now: () => now,
+    });
+
+    expect((await client.recordOpen()).valid).toBe(true);
+    now = new Date("2026-07-10T09:54:00.000Z");
+    expect((await client.recordOpen()).failures).toContain("clock-rollback");
+    expect(await state.read("last-trusted-at")).toBe(
+      "2026-07-10T10:00:00.000Z",
+    );
+    expect((await client.recordOpen()).failures).toContain("clock-rollback");
+
+    now = new Date("2026-07-10T09:58:00.000Z");
+    const recovered = await client.recordOpen();
+    expect(recovered.valid).toBe(true);
+    expect(recovered.failures).not.toContain("clock-rollback");
+    expect(await state.read("last-trusted-at")).toBe(
+      "2026-07-10T10:00:00.000Z",
+    );
+  });
+});