@southwind-ai/license 0.1.0

package/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/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@southwind-ai/license",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@southwind-ai/shared": "workspace:*",
+    "fflate": "^0.8.3"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./offline-code": "./src/offline-code.ts",
+    "./bounded-json-body": "./src/bounded-json-body.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/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/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/src/client.ts

@@ -0,0 +1,86 @@
+import type {
+  LicenseFailureReason,
+  LicenseUsageRecord,
+  SignedLicense,
+} from "@southwind-ai/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/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/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/src/installation.ts

@@ -0,0 +1,150 @@
+import type { LicenseFailureReason, SignedLicense } from "@southwind-ai/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
+  );
+}

package/src/license-parser.ts

@@ -0,0 +1,56 @@
+import type { SignedLicense, SignedLicenseV1 } from "@southwind-ai/shared";
+import { createLicenseSigningPayload } from "./payload.js";
+
+export function parseSignedLicenseV1(
+  rawLicense: string,
+): SignedLicenseV1 | undefined {
+  try {
+    const value = JSON.parse(rawLicense) as unknown;
+    if (!isRecord(value)) return undefined;
+    if (
+      !hasExactKeys(value, [
+        "algorithm",
+        "claims",
+        "formatVersion",
+        "publicKeyId",
+        "signature",
+      ])
+    ) {
+      return undefined;
+    }
+    if (typeof value.signature !== "string" || !value.signature.length) {
+      return undefined;
+    }
+    const license = value as unknown as SignedLicenseV1;
+    createLicenseSigningPayload({
+      formatVersion: license.formatVersion,
+      algorithm: license.algorithm,
+      publicKeyId: license.publicKeyId,
+      claims: license.claims,
+    });
+    return license;
+  } catch {
+    return undefined;
+  }
+}
+
+export function parseSignedLicense(
+  rawLicense: string,
+): SignedLicense | undefined {
+  return parseSignedLicenseV1(rawLicense);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasExactKeys(
+  value: Record<string, unknown>,
+  expected: readonly string[],
+): boolean {
+  const keys = Object.keys(value);
+  return (
+    keys.length === expected.length &&
+    keys.every((key) => expected.includes(key))
+  );
+}