@southwind-ai/license 0.1.0

package/src/payload.ts

@@ -0,0 +1,201 @@
+import type {
+  LicenseFormatVersion,
+  LicenseV1Claims,
+  SignedLicenseV1,
+} from "@southwind-ai/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/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}`;
+  }
+}

package/src/test-fixtures.ts

@@ -0,0 +1,59 @@
+import { generateKeyPairSync, sign } from "node:crypto";
+import type {
+  LegacyPrototypeLicenseClaims as LicenseClaims,
+  LegacyPrototypeSignedLicense as SignedLicense,
+  LicenseV1Claims,
+  SignedLicenseV1,
+} from "@southwind-ai/shared";
+import { createLicenseSigningPayload } from "./payload.js";
+import { legacyPrototypeLicensePayloadReader } from "./verification.js";
+
+export function createSignedLicense(inputClaims: LicenseClaims): {
+  license: SignedLicense;
+  publicKeyPem: string;
+} {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const signature = sign(
+    null,
+    Buffer.from(
+      legacyPrototypeLicensePayloadReader.serializeForVerification(inputClaims),
+    ),
+    privateKey,
+  ).toString("base64");
+
+  return {
+    publicKeyPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    license: {
+      claims: inputClaims,
+      signature,
+      publicKeyId: "key_1",
+      algorithm: "ED25519",
+    },
+  };
+}
+
+export function createSignedLicenseV1(
+  claims: LicenseV1Claims,
+  keyId = "key_v1",
+): {
+  license: SignedLicenseV1;
+  publicKeyPem: string;
+} {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const unsigned = {
+    formatVersion: 1,
+    algorithm: "ED25519",
+    publicKeyId: keyId,
+    claims,
+  } as const;
+  const signature = sign(
+    null,
+    Buffer.from(createLicenseSigningPayload(unsigned)),
+    privateKey,
+  ).toString("base64");
+
+  return {
+    publicKeyPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    license: { ...unsigned, signature },
+  };
+}

package/src/v1-test-vector.ts

@@ -0,0 +1,49 @@
+import { licenseVersionKey, type LicenseV1Claims } from "@southwind-ai/shared";
+
+/** Public, non-secret interoperability vector shared by SDK and issuer tests. */
+export const LICENSE_V1_TEST_VECTOR: {
+  claims: LicenseV1Claims;
+  keyId: string;
+  publicKeyPem: string;
+  signedPayload: string;
+  payloadDigest: string;
+  signature: string;
+} = {
+  claims: {
+    licenseId: "license_vector_v1",
+    productCode: "windy-platform",
+    customer: {
+      id: "customer_vector",
+      code: "C-001",
+      name: "固定向量客户",
+    },
+    project: {
+      id: "project_vector",
+      code: "P-001",
+      name: "固定向量项目",
+    },
+    contract: {
+      id: "contract_vector",
+      contractNumber: "HT-2026-001",
+      version: "1",
+    },
+    machineCode: "machine-vector-001",
+    issuedAt: "2026-07-10T00:00:00.000Z",
+    expiresAt: "2030-07-10T00:00:00.000Z",
+    licenseVersion: {
+      key: licenseVersionKey("advanced"),
+      name: "高级付费版",
+    },
+  },
+  keyId: "development-version-model-v1",
+  publicKeyPem:
+    "-----BEGIN PUBLIC KEY-----\n" +
+    "MCowBQYDK2VwAyEAbYwI4vgDmeP9rj+Vu5QkqW83LZsKJJCs1athjcE5J5s=\n" +
+    "-----END PUBLIC KEY-----\n",
+  signedPayload:
+    '{"algorithm":"ED25519","claims":{"contract":{"contractNumber":"HT-2026-001","id":"contract_vector","version":"1"},"customer":{"code":"C-001","id":"customer_vector","name":"固定向量客户"},"expiresAt":"2030-07-10T00:00:00.000Z","issuedAt":"2026-07-10T00:00:00.000Z","licenseId":"license_vector_v1","licenseVersion":{"key":"advanced","name":"高级付费版"},"machineCode":"machine-vector-001","productCode":"windy-platform","project":{"code":"P-001","id":"project_vector","name":"固定向量项目"}},"formatVersion":1,"publicKeyId":"development-version-model-v1"}',
+  payloadDigest:
+    "1cbe2a782b74cb79ba03bc987b0736155db56742a9bc619f612af2a162ec535b",
+  signature:
+    "y1tMY82+iYlAfzRvC+IdZoLlufZ3b7EW0TysskwZHi7fXye07K6vQ9cTSvkg3dn+vhMeLeyt+3VjpOLhxFTQBQ==",
+};

package/src/validation.ts

@@ -0,0 +1,143 @@
+import type {
+  LicenseFailureReason,
+  LicenseUsageRecord,
+  SignedLicense,
+} from "@southwind-ai/shared";
+import { parseSignedLicense } from "./license-parser.js";
+import type { LicensePublicKeySource } from "./verification.js";
+import { verifySignedLicense } from "./verification.js";
+
+export { parseSignedLicense, parseSignedLicenseV1 } from "./license-parser.js";
+
+const DEFAULT_CLOCK_TOLERANCE_MS = 5 * 60 * 1000;
+const RFC_3339 =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+export interface LicenseValidationOptions {
+  productCode: string;
+  machineCode: string;
+  publicKeys: LicensePublicKeySource;
+  now?: Date;
+  lastTrustedAt?: string;
+  clockToleranceMs?: number;
+}
+
+export interface LicenseDocumentVerificationResult {
+  valid: boolean;
+  license?: SignedLicense;
+  failures: LicenseFailureReason[];
+}
+
+export interface LicenseRuntimeValidationResult extends LicenseDocumentVerificationResult {
+  usage: LicenseUsageRecord;
+  nextTrustedAt?: string;
+}
+
+export async function verifyLicenseDocument(
+  rawLicense: string,
+  publicKeys: LicensePublicKeySource,
+): Promise<LicenseDocumentVerificationResult> {
+  const license = parseSignedLicense(rawLicense);
+  if (!license) return { valid: false, failures: ["invalid-format"] };
+
+  const result = await verifySignedLicense(license, publicKeys);
+  return result.valid
+    ? { valid: true, license, failures: [] }
+    : { valid: false, failures: result.failures };
+}
+
+export async function validateLicenseDocument(
+  rawLicense: string,
+  options: LicenseValidationOptions,
+): Promise<LicenseRuntimeValidationResult> {
+  const now = options.now ?? new Date();
+  const openedAt = validNow(now);
+  const verified = await verifyLicenseDocument(rawLicense, options.publicKeys);
+  const failures = [...verified.failures];
+  const license = verified.license;
+
+  if (license) {
+    const issuedAt = parseDateTime(license.claims.issuedAt);
+    const expiresAt = parseDateTime(license.claims.expiresAt);
+    if (
+      issuedAt === undefined ||
+      expiresAt === undefined ||
+      expiresAt <= issuedAt
+    ) {
+      failures.push("invalid-format");
+    } else if (now.getTime() > expiresAt) {
+      failures.push("expired");
+    }
+    if (license.claims.productCode !== options.productCode) {
+      failures.push("product-mismatch");
+    }
+    if (license.claims.machineCode !== options.machineCode) {
+      failures.push("machine-mismatch");
+    }
+  }
+
+  const clock = evaluateClock(
+    now.getTime(),
+    options.lastTrustedAt,
+    options.clockToleranceMs ?? DEFAULT_CLOCK_TOLERANCE_MS,
+  );
+  if (clock.rollback) failures.push("clock-rollback");
+
+  const uniqueFailures = [...new Set(failures)];
+  const valid = Boolean(license) && uniqueFailures.length === 0;
+  return {
+    valid,
+    license,
+    failures: uniqueFailures,
+    nextTrustedAt: clock.nextTrustedAt,
+    usage: {
+      machineCode: options.machineCode,
+      openedAt,
+      previousOpenedAt: options.lastTrustedAt,
+      status: uniqueFailures.includes("clock-rollback")
+        ? "clock-rollback"
+        : valid
+          ? "valid"
+          : uniqueFailures.includes("expired")
+            ? "expired"
+            : "invalid",
+      reason: uniqueFailures[0],
+    },
+  };
+}
+
+function evaluateClock(
+  now: number,
+  lastTrustedAt: string | undefined,
+  toleranceMs: number,
+): { rollback: boolean; nextTrustedAt?: string } {
+  if (!Number.isFinite(toleranceMs) || toleranceMs < 0) {
+    throw new RangeError("clockToleranceMs 必须为非负有限数");
+  }
+  if (!lastTrustedAt) {
+    return { rollback: false, nextTrustedAt: new Date(now).toISOString() };
+  }
+  const previous = parseDateTime(lastTrustedAt);
+  if (previous === undefined) {
+    return { rollback: true };
+  }
+  if (now + toleranceMs < previous) {
+    return { rollback: true, nextTrustedAt: lastTrustedAt };
+  }
+  return {
+    rollback: false,
+    nextTrustedAt: new Date(Math.max(now, previous)).toISOString(),
+  };
+}
+
+function parseDateTime(value: string): number | undefined {
+  if (!RFC_3339.test(value)) return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : undefined;
+}
+
+function validNow(now: Date): string {
+  if (!Number.isFinite(now.getTime()))
+    throw new RangeError("now 必须是有效时间");
+  return now.toISOString();
+}