create-windy 0.6.9 → 0.6.10

package/template/apps/server/src/license/pairing-service.test.ts

@@ -0,0 +1,320 @@
+import { generateKeyPairSync, sign } from "node:crypto";
+import { describe, expect, test } from "bun:test";
+import {
+  createLicensePairingCode,
+  createLicenseSigningPayload,
+} from "@southwind-ai/license";
+import {
+  licenseVersionKey,
+  type LicenseV1Claims,
+  type SignedLicenseV1,
+} from "@southwind-ai/shared";
+import { LicensePairingService } from "./pairing-service.js";
+import { PlatformLicenseRuntime } from "./runtime-service.js";
+
+describe("License 手机配对会话", () => {
+  test("过期会话拒绝投递并清理为 expired", async () => {
+    const fixture = createFixture();
+    let now = new Date();
+    const service = new LicensePairingService(fixture.runtime, {
+      ttlMs: 1_000,
+      now: () => now,
+    });
+    const created = service.create(callback);
+    now = new Date(now.getTime() + 1_001);
+
+    expect(service.status(created.request.sessionId).status).toBe("expired");
+    await expect(
+      service.deliver(
+        created.request.sessionId,
+        created.request.token,
+        JSON.stringify(fixture.license),
+      ),
+    ).rejects.toMatchObject({ code: "PAIRING_EXPIRED", status: 410 });
+  });
+
+  test("错误 token 和篡改签名都不能进入 delivered", async () => {
+    const fixture = createFixture();
+    const service = new LicensePairingService(fixture.runtime);
+    const created = service.create(callback);
+
+    await expect(
+      service.deliver(
+        created.request.sessionId,
+        "invalid-delivery-token",
+        JSON.stringify(fixture.license),
+      ),
+    ).rejects.toMatchObject({ code: "PAIRING_TOKEN_INVALID", status: 403 });
+
+    const tampered = {
+      ...fixture.license,
+      signature: `A${fixture.license.signature.slice(1)}`,
+    };
+    await expect(
+      service.deliver(
+        created.request.sessionId,
+        created.request.token,
+        JSON.stringify(tampered),
+      ),
+    ).rejects.toMatchObject({
+      code: "PAIRING_LICENSE_REJECTED",
+      details: { reasons: expect.arrayContaining(["invalid-signature"]) },
+    });
+    expect(service.status(created.request.sessionId).status).toBe("waiting");
+  });
+
+  test("同 token 和同 canonical License 可幂等重放，其它 License 拒绝", async () => {
+    const other = signedLicense("license_other");
+    const fixture = createFixture([other]);
+    const service = new LicensePairingService(fixture.runtime);
+    const created = service.create(callback);
+    const delivered = await service.deliver(
+      created.request.sessionId,
+      created.request.token,
+      JSON.stringify(fixture.license),
+    );
+
+    await expect(
+      service.deliver(
+        created.request.sessionId,
+        `${created.request.token}x`,
+        JSON.stringify(fixture.license),
+      ),
+    ).rejects.toMatchObject({ code: "PAIRING_TOKEN_INVALID", status: 403 });
+
+    await expect(
+      service.deliver(
+        created.request.sessionId,
+        created.request.token,
+        JSON.stringify(fixture.license, null, 2),
+      ),
+    ).resolves.toEqual(delivered);
+    await expect(
+      service.deliver(
+        created.request.sessionId,
+        created.request.token,
+        JSON.stringify(other.license),
+      ),
+    ).rejects.toMatchObject({ code: "PAIRING_LICENSE_CONFLICT", status: 409 });
+  });
+
+  test("连续五次错误确认后锁定并销毁待安装 License", async () => {
+    const fixture = createFixture();
+    const service = new LicensePairingService(fixture.runtime);
+    const created = service.create(callback);
+    await service.deliver(
+      created.request.sessionId,
+      created.request.token,
+      JSON.stringify(fixture.license),
+    );
+
+    for (let attempt = 1; attempt <= 4; attempt += 1) {
+      await expect(
+        service.confirm(created.request.sessionId, "00000000", actorContext),
+      ).rejects.toMatchObject({
+        code: "PAIRING_CODE_INVALID",
+        details: { attemptsRemaining: 5 - attempt },
+      });
+    }
+    await expect(
+      service.confirm(created.request.sessionId, "00000000", actorContext),
+    ).rejects.toMatchObject({ code: "PAIRING_LOCKED", status: 423 });
+    expect(service.status(created.request.sessionId)).toMatchObject({
+      status: "locked",
+      attemptsRemaining: 0,
+    });
+    expect(fixture.store.installCalls).toBe(0);
+  });
+
+  test("正确配对码只触发一次既有原子安装入口", async () => {
+    const fixture = createFixture();
+    const service = new LicensePairingService(fixture.runtime);
+    const created = service.create(callback);
+    const delivered = await service.deliver(
+      created.request.sessionId,
+      created.request.token,
+      JSON.stringify(fixture.license),
+    );
+    expect(delivered).toMatchObject({
+      id: created.request.sessionId,
+      status: "delivered",
+      license: {
+        licenseVersion: { key: "advanced", name: "高级付费版" },
+        expiresAt: "2030-08-01T00:00:00.000Z",
+      },
+    });
+    expect(delivered).not.toHaveProperty("token");
+    expect(delivered).not.toHaveProperty("customer");
+    expect(service.status(created.request.sessionId)).toMatchObject({
+      license: {
+        licenseVersion: { key: "advanced", name: "高级付费版" },
+        expiresAt: "2030-08-01T00:00:00.000Z",
+      },
+    });
+    const code = await createLicensePairingCode(
+      created.request,
+      fixture.license,
+    );
+
+    const installed = await service.confirm(
+      created.request.sessionId,
+      `${code.slice(0, 4)}-${code.slice(4).toLowerCase()}`,
+      actorContext,
+    );
+    expect(installed.result.status).toBe("installed");
+    expect(service.status(created.request.sessionId).status).toBe("consumed");
+    expect(fixture.store.installCalls).toBe(1);
+    await expect(
+      service.confirm(created.request.sessionId, code, actorContext),
+    ).rejects.toMatchObject({ code: "PAIRING_CONSUMED", status: 409 });
+    expect(fixture.store.installCalls).toBe(1);
+  });
+
+  test("安装器拒绝时保留 delivered 会话供管理员修正后重试", async () => {
+    const fixture = createFixture();
+    let installCalls = 0;
+    fixture.runtime.install = async () => {
+      installCalls += 1;
+      if (installCalls === 1) throw new Error("storage unavailable");
+      return {
+        result: {
+          status: "rejected",
+          failures: ["license-not-newer"],
+        },
+        snapshot: {
+          status: "missing",
+          restricted: true,
+          reminder: { level: "none" },
+          canViewDetails: true,
+        },
+      } as Awaited<ReturnType<PlatformLicenseRuntime["install"]>>;
+    };
+    const service = new LicensePairingService(fixture.runtime);
+    const created = service.create(callback);
+    await service.deliver(
+      created.request.sessionId,
+      created.request.token,
+      JSON.stringify(fixture.license),
+    );
+    const code = await createLicensePairingCode(
+      created.request,
+      fixture.license,
+    );
+
+    await expect(
+      service.confirm(created.request.sessionId, code, actorContext),
+    ).rejects.toThrow("storage unavailable");
+    expect(service.status(created.request.sessionId).status).toBe("delivered");
+    const result = await service.confirm(
+      created.request.sessionId,
+      code,
+      actorContext,
+    );
+    expect(result.result.status).toBe("rejected");
+    expect(service.status(created.request.sessionId).status).toBe("delivered");
+    expect(installCalls).toBe(2);
+  });
+
+  test("会话容量只回收终态，活跃会话满时 fail closed", () => {
+    const fixture = createFixture();
+    const service = new LicensePairingService(fixture.runtime, {
+      maxSessions: 1,
+    });
+    service.create(callback);
+    expect(() => service.create(callback)).toThrow(
+      expect.objectContaining({ code: "PAIRING_CAPACITY_REACHED" }),
+    );
+  });
+
+  test("SDK 拒绝公网或不安全回调且失败创建不占用容量", () => {
+    const fixture = createFixture();
+    const service = new LicensePairingService(fixture.runtime, {
+      maxSessions: 1,
+    });
+    expect(() =>
+      service.create(
+        (sessionId) =>
+          `https://license.example.com/api/license/runtime/pairing/sessions/${sessionId}/deliver`,
+      ),
+    ).toThrow(expect.objectContaining({ code: "PAIRING_REQUEST_INVALID" }));
+    expect(service.create(callback).status).toBe("waiting");
+  });
+});
+
+function callback(sessionId: string) {
+  return `https://windy.internal/api/license/runtime/pairing/sessions/${sessionId}/deliver`;
+}
+
+const actorContext = {
+  actor: {
+    id: "user_1",
+    type: "user" as const,
+    name: "管理员",
+    roleCodes: ["admin"],
+    permissionKeys: ["system.license.manage"],
+  },
+  requestId: "request_pairing",
+};
+
+function createFixture(additional: ReturnType<typeof signedLicense>[] = []) {
+  const signed = signedLicense();
+  const store = {
+    current: undefined as string | undefined,
+    installCalls: 0,
+    readCurrent() {
+      return this.current;
+    },
+    replaceCurrentAtomically(value: string) {
+      this.installCalls += 1;
+      this.current = value;
+    },
+  };
+  const runtime = new PlatformLicenseRuntime({
+    productCode: "windy-platform",
+    machineCode: "machine_1",
+    publicKeys: Object.fromEntries(
+      [signed, ...additional].map((current) => [
+        current.license.publicKeyId,
+        current.publicKeyPem,
+      ]),
+    ),
+    store,
+  });
+  return { runtime, store, license: signed.license };
+}
+
+function signedLicense(licenseId = "license_pairing") {
+  const claims: LicenseV1Claims = {
+    licenseId,
+    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-08-01T00:00:00.000Z",
+    expiresAt: "2030-08-01T00:00:00.000Z",
+    licenseVersion: {
+      key: licenseVersionKey("advanced"),
+      name: "高级付费版",
+    },
+  };
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const unsigned = {
+    formatVersion: 1,
+    algorithm: "ED25519",
+    publicKeyId: `pairing-key-${licenseId}`,
+    claims,
+  } as const;
+  const license: SignedLicenseV1 = {
+    ...unsigned,
+    signature: sign(
+      null,
+      Buffer.from(createLicenseSigningPayload(unsigned)),
+      privateKey,
+    ).toString("base64"),
+  };
+  return {
+    license,
+    publicKeyPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
+  };
+}

package/template/apps/server/src/license/pairing-service.ts

@@ -0,0 +1,321 @@
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import {
+  canonicalizeJson,
+  createLicensePairingCode,
+  createLicensePairingRequest,
+  normalizeLicensePairingCode,
+  type LicensePairingRequestV1,
+} from "@southwind-ai/license";
+import type { LicenseInstallActorContext } from "./runtime-service.js";
+import type { PlatformLicenseRuntime } from "./runtime-service.js";
+
+export type LicensePairingStatus =
+  | "waiting"
+  | "delivered"
+  | "expired"
+  | "locked"
+  | "consumed";
+
+export interface LicensePairingServiceOptions {
+  ttlMs?: number;
+  maxSessions?: number;
+  maxConfirmationAttempts?: number;
+  now?: () => Date;
+}
+
+export class LicensePairingError extends Error {
+  constructor(
+    readonly code: string,
+    readonly status: number,
+    message: string,
+    readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "LicensePairingError";
+  }
+}
+
+interface PairingSession {
+  request: LicensePairingRequestV1;
+  status: LicensePairingStatus;
+  createdAtMs: number;
+  failedAttempts: number;
+  rawLicense?: string;
+  pairingCode?: string;
+  licenseSummary?: {
+    licenseVersion: { key: string; name: string };
+    expiresAt: string;
+  };
+}
+
+export class LicensePairingService {
+  private readonly sessions = new Map<string, PairingSession>();
+  private readonly ttlMs: number;
+  private readonly maxSessions: number;
+  private readonly maxAttempts: number;
+  private readonly now: () => Date;
+  private mutationQueue: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly runtime: PlatformLicenseRuntime,
+    options: LicensePairingServiceOptions = {},
+  ) {
+    this.ttlMs = positiveInteger(options.ttlMs, 5 * 60 * 1000, "ttlMs");
+    this.maxSessions = positiveInteger(options.maxSessions, 256, "maxSessions");
+    this.maxAttempts = positiveInteger(
+      options.maxConfirmationAttempts,
+      5,
+      "maxConfirmationAttempts",
+    );
+    this.now = options.now || (() => new Date());
+  }
+
+  create(callbackUrl: string | ((sessionId: string) => string)) {
+    this.reclaimCapacity();
+    const now = this.now().getTime();
+    const target = this.runtime.pairingTarget();
+    const sessionId = randomUUID();
+    const request: LicensePairingRequestV1 = {
+      type: "windy-license-pairing",
+      version: 1,
+      sessionId,
+      token: randomBytes(32).toString("base64url"),
+      nonce: randomBytes(24).toString("base64url"),
+      productCode: target.productCode,
+      machineCode: target.machineCode,
+      callbackUrl:
+        typeof callbackUrl === "function"
+          ? callbackUrl(sessionId)
+          : callbackUrl,
+      expiresAt: new Date(now + this.ttlMs).toISOString(),
+    };
+    let qrPayload: string;
+    try {
+      qrPayload = createLicensePairingRequest(request);
+    } catch {
+      throw pairingError(
+        "PAIRING_REQUEST_INVALID",
+        400,
+        "配对请求不符合内网回调安全约束",
+      );
+    }
+    this.sessions.set(request.sessionId, {
+      request,
+      status: "waiting",
+      createdAtMs: now,
+      failedAttempts: 0,
+    });
+    return {
+      request,
+      qrPayload,
+      status: "waiting" as const,
+    };
+  }
+
+  status(sessionId: string) {
+    const session = this.requireSession(sessionId);
+    this.expire(session);
+    return this.present(session);
+  }
+
+  async deliver(
+    sessionId: string,
+    token: string,
+    rawLicense: string,
+  ): Promise<ReturnType<LicensePairingService["status"]>> {
+    return this.exclusive(async () => {
+      const session = this.requireSession(sessionId);
+      this.expire(session);
+      if (!safeEqual(token, session.request.token)) {
+        throw pairingError("PAIRING_TOKEN_INVALID", 403, "配对投递凭证无效");
+      }
+      if (session.status !== "waiting" && session.status !== "delivered") {
+        this.requireState(session, "waiting");
+      }
+      const validation = await this.runtime.validateCandidate(rawLicense);
+      if (!validation.valid || !validation.license) {
+        throw new LicensePairingError(
+          "PAIRING_LICENSE_REJECTED",
+          400,
+          "License 验签或目标校验失败",
+          { reasons: validation.failures },
+        );
+      }
+      const canonicalLicense = canonicalizeJson(validation.license);
+      if (session.status === "delivered") {
+        if (
+          session.rawLicense &&
+          safeEqual(canonicalLicense, session.rawLicense)
+        ) {
+          return this.present(session);
+        }
+        throw pairingError(
+          "PAIRING_LICENSE_CONFLICT",
+          409,
+          "配对会话已经投递了其它 License",
+        );
+      }
+      const pairingCode = await createLicensePairingCode(
+        session.request,
+        canonicalLicense,
+      );
+      this.expire(session);
+      this.requireState(session, "waiting");
+      session.pairingCode = pairingCode;
+      session.rawLicense = canonicalLicense;
+      session.licenseSummary = {
+        licenseVersion: validation.license.claims.licenseVersion,
+        expiresAt: validation.license.claims.expiresAt,
+      };
+      session.status = "delivered";
+      return this.present(session);
+    });
+  }
+
+  async confirm(
+    sessionId: string,
+    code: string,
+    context: LicenseInstallActorContext,
+  ) {
+    return this.exclusive(async () => {
+      const session = this.requireSession(sessionId);
+      this.expire(session);
+      this.requireState(session, "delivered");
+      let normalized = "";
+      try {
+        normalized = normalizeLicensePairingCode(code);
+      } catch {
+        // Invalid syntax is intentionally counted as an incorrect attempt.
+      }
+      if (!session.pairingCode || !safeEqual(normalized, session.pairingCode)) {
+        session.failedAttempts += 1;
+        if (session.failedAttempts >= this.maxAttempts) {
+          this.finish(session, "locked");
+          throw pairingError(
+            "PAIRING_LOCKED",
+            423,
+            "配对确认次数过多，会话已锁定",
+          );
+        }
+        throw new LicensePairingError(
+          "PAIRING_CODE_INVALID",
+          400,
+          "配对码错误",
+          { attemptsRemaining: this.maxAttempts - session.failedAttempts },
+        );
+      }
+      const candidate = session.rawLicense;
+      if (!candidate) {
+        throw pairingError(
+          "PAIRING_STATE_INVALID",
+          409,
+          "配对会话缺少待安装 License",
+        );
+      }
+      const installed = await this.runtime.install(candidate, context);
+      if (installed.result.status !== "rejected") {
+        this.finish(session, "consumed");
+      }
+      return installed;
+    });
+  }
+
+  private present(session: PairingSession) {
+    return {
+      id: session.request.sessionId,
+      status: session.status,
+      expiresAt: session.request.expiresAt,
+      attemptsRemaining: Math.max(0, this.maxAttempts - session.failedAttempts),
+      ...(session.licenseSummary ? { license: session.licenseSummary } : {}),
+    };
+  }
+
+  private requireSession(sessionId: string): PairingSession {
+    const session = this.sessions.get(sessionId);
+    if (!session)
+      throw pairingError("PAIRING_NOT_FOUND", 404, "配对会话不存在");
+    return session;
+  }
+
+  private requireState(
+    session: PairingSession,
+    expected: LicensePairingStatus,
+  ) {
+    if (session.status === expected) return;
+    const status = session.status === "expired" ? 410 : 409;
+    throw new LicensePairingError(
+      `PAIRING_${session.status.toUpperCase()}`,
+      status,
+      `配对会话当前状态为 ${session.status}`,
+    );
+  }
+
+  private expire(session: PairingSession): void {
+    if (
+      (session.status === "waiting" || session.status === "delivered") &&
+      this.now().getTime() >= Date.parse(session.request.expiresAt)
+    ) {
+      this.finish(session, "expired");
+    }
+  }
+
+  private finish(session: PairingSession, status: LicensePairingStatus): void {
+    session.status = status;
+    session.rawLicense = undefined;
+    session.pairingCode = undefined;
+    if (status !== "consumed") session.licenseSummary = undefined;
+  }
+
+  private reclaimCapacity(): void {
+    for (const session of this.sessions.values()) this.expire(session);
+    if (this.sessions.size < this.maxSessions) return;
+    const reclaimable = [...this.sessions.values()]
+      .filter(({ status }) =>
+        ["expired", "locked", "consumed"].includes(status),
+      )
+      .sort((left, right) => left.createdAtMs - right.createdAtMs);
+    for (const session of reclaimable) {
+      this.sessions.delete(session.request.sessionId);
+      if (this.sessions.size < this.maxSessions) return;
+    }
+    throw pairingError(
+      "PAIRING_CAPACITY_REACHED",
+      503,
+      "配对会话已满，请稍后再试",
+    );
+  }
+
+  private async exclusive<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.mutationQueue.then(operation);
+    this.mutationQueue = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+}
+
+function safeEqual(left: string, right: string): boolean {
+  const leftDigest = Buffer.from(left);
+  const rightDigest = Buffer.from(right);
+  return (
+    leftDigest.length === rightDigest.length &&
+    timingSafeEqual(leftDigest, rightDigest)
+  );
+}
+
+function positiveInteger(
+  value: number | undefined,
+  fallback: number,
+  name: string,
+): number {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+    throw new RangeError(`${name} 必须为正整数`);
+  }
+  return resolved;
+}
+
+function pairingError(code: string, status: number, message: string) {
+  return new LicensePairingError(code, status, message);
+}

package/template/apps/server/src/license/restriction.test.ts

@@ -28,6 +28,17 @@ describe("License 限制模式 HTTP 白名单", () => {
       ["POST", "/api/auth/logout", true],
       ["GET", "/api/license/runtime", true],
       ["POST", "/api/license/runtime/install", true],
+      ["POST", "/api/license/runtime/pairing/sessions", true],
+      ["GET", "/api/license/runtime/pairing/sessions/session_1", true],
+      ["POST", "/api/license/runtime/pairing/sessions/session_1/deliver", true],
+      [
+        "OPTIONS",
+        "/api/license/runtime/pairing/sessions/session_1/deliver",
+        true,
+      ],
+      ["POST", "/api/license/runtime/pairing/sessions/session_1/confirm", true],
+      ["GET", "/api/license/runtime/pairing/sessions", false],
+      ["PUT", "/api/license/runtime/pairing/sessions/session_1/deliver", false],
       ["POST", "/api/ready", false],
       ["GET", "/api/metrics/extra", false],
       ["GET", "/api/auth/session/extra", false],

package/template/apps/server/src/license/restriction.ts

@@ -18,6 +18,7 @@ const RESTRICTED_HTTP_ALLOWLIST = new Set([
   "GET /api/license/runtime",
   "GET /api/admin/bootstrap",
   "POST /api/license/runtime/install",
+  "POST /api/license/runtime/pairing/sessions",
   "GET /api/system/roles/export",
   "GET /api/system/departments/export",
   "GET /api/system/menus/export",
@@ -27,6 +28,10 @@ const RESTRICTED_HTTP_ALLOWLIST = new Set([
 ]);
 
 const RESTRICTED_HTTP_TEMPLATE_ALLOWLIST = new Set([
+  "GET /api/license/runtime/pairing/sessions/:sessionId",
+  "POST /api/license/runtime/pairing/sessions/:sessionId/deliver",
+  "OPTIONS /api/license/runtime/pairing/sessions/:sessionId/deliver",
+  "POST /api/license/runtime/pairing/sessions/:sessionId/confirm",
   "POST /api/system/users/exports",
   "GET /api/system/users/exports/:id",
   "POST /api/system/users/exports/:id/cancel",