@jchat/runtime 0.0.2 → 1.0.0-alpha.1

package/src/domain.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test"
+import {
+  isAllowedConfiguredDomain,
+  isPublicDomain,
+  normalizeDomain,
+  resolveActivationDomain
+} from "./domain"
+
+describe("instance domain", () => {
+  test("normalizes and classifies public, local, and configured domains", () => {
+    expect(normalizeDomain("HTTPS://WWW.Example.com.:8080")).toEqual({
+      host: "example.com",
+      isLocalhost: false
+    })
+    expect(normalizeDomain("localhost:3000")).toEqual({
+      host: "localhost",
+      isLocalhost: true
+    })
+    expect(isPublicDomain("example.com")).toBe(true)
+    expect(isPublicDomain("localhost")).toBe(false)
+    expect(isPublicDomain("192.0.2.10")).toBe(false)
+    expect(isPublicDomain("chat.local")).toBe(false)
+    expect(isPublicDomain("chat.test")).toBe(false)
+    expect(isAllowedConfiguredDomain("chat.example.com")).toBe(true)
+    expect(isAllowedConfiguredDomain("localhost:3000")).toBe(true)
+    expect(isAllowedConfiguredDomain("chat.test")).toBe(false)
+    expect(isAllowedConfiguredDomain("")).toBe(false)
+  })
+
+  test("resolves current-host and parent-domain activation scopes", () => {
+    expect(resolveActivationDomain("demo.example.com", "extended", "path")).toBe("demo.example.com")
+    expect(resolveActivationDomain("chat.example.com", "standard", "subdomain")).toBe(
+      "chat.example.com"
+    )
+    expect(resolveActivationDomain("chat.example.com", "extended", "subdomain")).toBe(
+      "chat.example.com"
+    )
+    expect(
+      resolveActivationDomain("chat.example.com", "extended", "subdomain", "parent-domain")
+    ).toBe("example.com")
+    expect(
+      resolveActivationDomain("chat.example.co.uk", "extended", "subdomain", "parent-domain")
+    ).toBe("example.co.uk")
+  })
+})

package/src/domain.ts

@@ -0,0 +1,75 @@
+import net from "node:net"
+
+export type Plan = "standard" | "extended"
+export type RoutingMode = "path" | "subdomain"
+export type DomainScope = "current-host" | "parent-domain"
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1"])
+const RESERVED_SUFFIXES = [".local", ".test", ".invalid", ".example"]
+
+export type NormalizedDomain = {
+  host: string
+  isLocalhost: boolean
+}
+
+/** Normalize the host used for instance binding; ports and www are not significant. */
+export function normalizeDomain(value: string): NormalizedDomain {
+  const raw = value.trim()
+  if (!raw) throw new Error("Instance domain is required")
+
+  const url = new URL(raw.includes("://") ? raw : `https://${raw}`)
+  const hostname = url.hostname.toLowerCase().replace(/\.$/, "")
+  const host = hostname === "www.localhost" ? "localhost" : hostname.replace(/^www\./, "")
+  if (!host || host.includes("@") || /\s/.test(host)) {
+    throw new Error("Invalid instance domain")
+  }
+  return { host, isLocalhost: LOCAL_HOSTS.has(host) }
+}
+
+export function isPublicDomain(value: string): boolean {
+  const { host, isLocalhost } = normalizeDomain(value)
+  return (
+    !isLocalhost &&
+    net.isIP(host) === 0 &&
+    host.includes(".") &&
+    !RESERVED_SUFFIXES.some((suffix) => host.endsWith(suffix))
+  )
+}
+
+export function isAllowedConfiguredDomain(value: string): boolean {
+  try {
+    const normalized = normalizeDomain(value)
+    return normalized.isLocalhost || isPublicDomain(value)
+  } catch {
+    return false
+  }
+}
+
+function getRootDomain(value: string): string | null {
+  const { host, isLocalhost } = normalizeDomain(value)
+  if (isLocalhost || net.isIP(host) !== 0) return null
+
+  const parts = host.split(".")
+  if (parts.length <= 2) return host
+
+  const secondLevelTlds = new Set(["co", "com", "org", "net", "gov", "edu", "ac", "sch"])
+  const topLevel = parts.at(-1) ?? ""
+  const secondLevel = parts.at(-2) ?? ""
+  if (secondLevelTlds.has(secondLevel) && topLevel.length === 2 && parts.length >= 3) {
+    return parts.slice(-3).join(".")
+  }
+  return parts.slice(-2).join(".")
+}
+
+export function resolveActivationDomain(
+  host: string,
+  plan: Plan,
+  routingMode: RoutingMode,
+  domainScope: DomainScope = "current-host"
+): string {
+  const normalizedHost = normalizeDomain(host).host
+  if (routingMode === "subdomain" && plan === "extended" && domainScope === "parent-domain") {
+    return getRootDomain(normalizedHost) ?? normalizedHost
+  }
+  return normalizedHost
+}

package/src/env.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "bun:test"
+import { ServerConfigSchema } from "./env"
+
+const BASE = {
+  JCHAT_PORT: "3000",
+  JCHAT_COOKIE_SECRET: "secret",
+  JCHAT_DATABASE_URL: "postgresql://user:pass@localhost:5432/jchat",
+  JCHAT_REDIS_DATABASE_URL: "redis://default:pass@localhost:6379",
+  JCHAT_STORAGE_TYPE: "LOCAL",
+  JCHAT_BOT_NAME: "Bot",
+  JCHAT_BOT_EMAIL: "bot@jchat.com",
+  JCHAT_ADDON_ENCRYPTION_KEY: "1234567890123456",
+  JCHAT_DOMAIN: "localhost"
+}
+
+describe("ServerConfigSchema", () => {
+  it("parses the base environment and coerces the port", () => {
+    const result = ServerConfigSchema.safeParse(BASE)
+
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.JCHAT_PORT).toBe(3000)
+  })
+
+  it("defaults the omitted port to 3000", () => {
+    const { JCHAT_PORT: _, ...environment } = BASE
+    const result = ServerConfigSchema.safeParse(environment)
+
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.JCHAT_PORT).toBe(3000)
+  })
+
+  it("rejects malformed, out-of-range, and reserved ports", () => {
+    for (const port of ["abc", "0", "65536", "80", "443"]) {
+      expect(ServerConfigSchema.safeParse({ ...BASE, JCHAT_PORT: port }).success).toBe(false)
+    }
+  })
+
+  it("validates PostgreSQL and Redis connection URLs", () => {
+    const cases: Array<[Record<string, string>, boolean]> = [
+      [{ JCHAT_DATABASE_URL: "mysql://user:pass@localhost:3306/db" }, false],
+      [{ JCHAT_DATABASE_URL: "postgresql://no-port" }, false],
+      [{ JCHAT_REDIS_DATABASE_URL: "rediss://default:pass@localhost:6380" }, true],
+      [{ JCHAT_REDIS_DATABASE_URL: "http://localhost:6379" }, false],
+      [{ JCHAT_REDIS_DATABASE_URL: "redis://default:pass@localhost" }, false]
+    ]
+
+    for (const [override, expected] of cases) {
+      expect(ServerConfigSchema.safeParse({ ...BASE, ...override }).success).toBe(expected)
+    }
+  })
+
+  it("accepts only a full main-domain public site origin", () => {
+    const cases: Array<[string, boolean]> = [
+      ["https://example.com", true],
+      ["example.com", false],
+      ["https://www.example.com", false]
+    ]
+
+    for (const [siteUrl, expected] of cases) {
+      expect(ServerConfigSchema.safeParse({ ...BASE, JCHAT_SITE_URL: siteUrl }).success).toBe(
+        expected
+      )
+    }
+  })
+
+  it("allows a missing domain during initial installation", () => {
+    const { JCHAT_DOMAIN: _, ...environment } = BASE
+    const result = ServerConfigSchema.safeParse(environment)
+
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.JCHAT_DOMAIN).toBeUndefined()
+  })
+
+  it("accepts root and nested domains in supported routing modes", () => {
+    const cases = [
+      { JCHAT_DOMAIN: "example.com" },
+      { JCHAT_DOMAIN: "chat.example.com", JCHAT_ROUTING_MODE: "path" },
+      { JCHAT_DOMAIN: "chat.example.com", JCHAT_ROUTING_MODE: "subdomain" }
+    ]
+
+    for (const override of cases) {
+      expect(ServerConfigSchema.safeParse({ ...BASE, ...override }).success).toBe(true)
+    }
+  })
+
+  it("requires provider-specific storage settings", () => {
+    const providers = [
+      {
+        type: "MINIO",
+        config: {
+          JCHAT_MINIO_ENDPOINT: "http://localhost:9000",
+          JCHAT_MINIO_BUCKET_NAME: "bucket",
+          JCHAT_MINIO_ACCESS_KEY_ID: "key",
+          JCHAT_MINIO_SECRET_ACCESS_KEY: "secret",
+          JCHAT_MINIO_PUBLIC_URL: "https://files.example.com"
+        }
+      },
+      {
+        type: "AWS_S3",
+        config: {
+          JCHAT_AWS_REGION: "us-east-1",
+          JCHAT_AWS_BUCKET_NAME: "bucket",
+          JCHAT_AWS_ACCESS_KEY_ID: "key",
+          JCHAT_AWS_SECRET_ACCESS_KEY: "secret"
+        }
+      },
+      {
+        type: "CLOUDFLARE_R2",
+        config: {
+          JCHAT_CLOUDFLARE_ACCOUNT_ID: "account",
+          JCHAT_CLOUDFLARE_BUCKET_NAME: "bucket",
+          JCHAT_CLOUDFLARE_ACCESS_KEY_ID: "key",
+          JCHAT_CLOUDFLARE_SECRET_ACCESS_KEY: "secret",
+          JCHAT_CLOUDFLARE_PUBLIC_URL: "https://cdn.example.com"
+        }
+      },
+      {
+        type: "GCS",
+        config: {
+          JCHAT_GCS_PROJECT_ID: "project",
+          JCHAT_GCS_BUCKET_NAME: "bucket",
+          JCHAT_GCS_CLIENT_EMAIL: "service@example.iam.gserviceaccount.com",
+          JCHAT_GCS_PRIVATE_KEY: "-----BEGIN RSA PRIVATE KEY-----"
+        }
+      }
+    ] as const
+
+    for (const provider of providers) {
+      expect(
+        ServerConfigSchema.safeParse({
+          ...BASE,
+          JCHAT_STORAGE_TYPE: provider.type
+        }).success
+      ).toBe(false)
+      expect(
+        ServerConfigSchema.safeParse({
+          ...BASE,
+          JCHAT_STORAGE_TYPE: provider.type,
+          ...provider.config
+        }).success
+      ).toBe(true)
+    }
+
+    expect(ServerConfigSchema.safeParse({ ...BASE, JCHAT_STORAGE_TYPE: "FTP" }).success).toBe(false)
+  })
+})

package/src/env.ts

@@ -0,0 +1,261 @@
+import { StorageType, isMainDomain } from "@jchat/shared"
+import { replaceKeys } from "string-ts"
+import * as z from "zod"
+
+export function makeTypedEnv<T>(schema: { parse: (data: unknown) => T }) {
+  return (args: Record<string, unknown>) => schema.parse(replaceKeys(args, "VITE_", ""))
+}
+
+export const ServerConfigSchema = z
+  .object({
+    JCHAT_PORT: z
+      .string()
+      .regex(/^\d+$/)
+      .transform(Number)
+      .refine((port) => port >= 1 && port <= 65535, {
+        message: "Port must be between 1 and 65535"
+      })
+      .refine((port) => port !== 80 && port !== 443, {
+        message: "Avoid ports 80/443 (reserved for HTTP/HTTPS)"
+      })
+      .default(3000),
+
+    JCHAT_COOKIE_SECRET: z.string().min(1),
+
+    //DATABASE CONFIG
+    JCHAT_DATABASE_URL: z
+      .url()
+      .startsWith("postgresql://")
+      .regex(/^postgresql:\/\/([^:]+):([^@]+)@([^:]+):(\d+)\/([^?]+)(\?.*)?$/, {
+        message: "Must be in format: postgresql://username:password@host:port/database?schema"
+      }),
+    JCHAT_REDIS_DATABASE_URL: z
+      .url()
+      .refine((url) => url.startsWith("rediss://") || url.startsWith("redis://"), {
+        message: "Must use redis:// or rediss:// protocol"
+      })
+      .refine(
+        (url) => {
+          const pattern = /^(rediss?):\/\/(?:([^:]+):([^@]+)@)?([^:]+):(\d+)$/
+          return pattern.test(url)
+        },
+        {
+          message: "Must be in format: rediss://default:<password>@<host>:<port>"
+        }
+      ),
+
+    JCHAT_STORAGE_TYPE: z.enum(StorageType),
+
+    JCHAT_MINIO_ENDPOINT: z.string().optional(),
+    JCHAT_MINIO_BUCKET_NAME: z.string().optional(),
+    JCHAT_MINIO_ACCESS_KEY_ID: z.string().optional(),
+    JCHAT_MINIO_SECRET_ACCESS_KEY: z.string().optional(),
+    JCHAT_MINIO_PUBLIC_URL: z.string().optional(),
+
+    JCHAT_AWS_REGION: z.string().optional(),
+    JCHAT_AWS_BUCKET_NAME: z.string().optional(),
+    JCHAT_AWS_ACCESS_KEY_ID: z.string().optional(),
+    JCHAT_AWS_SECRET_ACCESS_KEY: z.string().optional(),
+
+    JCHAT_CLOUDFLARE_ACCOUNT_ID: z.string().optional(),
+    JCHAT_CLOUDFLARE_BUCKET_NAME: z.string().optional(),
+    JCHAT_CLOUDFLARE_ACCESS_KEY_ID: z.string().optional(),
+    JCHAT_CLOUDFLARE_SECRET_ACCESS_KEY: z.string().optional(),
+    JCHAT_CLOUDFLARE_PUBLIC_URL: z.string().optional(),
+
+    JCHAT_GCS_BUCKET_NAME: z.string().optional(),
+    JCHAT_GCS_PROJECT_ID: z.string().optional(),
+    JCHAT_GCS_CLIENT_EMAIL: z.string().optional(),
+    JCHAT_GCS_PRIVATE_KEY: z.string().optional(),
+    JCHAT_GCS_KEY_FILE: z.string().optional(),
+
+    JCHAT_BOT_NAME: z.string().trim().min(3),
+    JCHAT_BOT_EMAIL: z.email(),
+
+    JCHAT_DOMAIN: z.string().optional(),
+    JCHAT_SITE_URL: z.url().optional(),
+    JCHAT_ROUTING_MODE: z.enum(["path", "subdomain"]).default("subdomain"),
+
+    JCHAT_ADDON_ENCRYPTION_KEY: z.string().min(16),
+
+    NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+
+    SYSTEM_BOOTSTRAP_COMPLETE: z.boolean().optional()
+  })
+  .superRefine((env, ctx) => {
+    if (env.JCHAT_SITE_URL) {
+      let siteHostname: string | undefined
+      try {
+        siteHostname = new URL(env.JCHAT_SITE_URL).hostname
+      } catch {}
+
+      if (siteHostname && !isMainDomain(siteHostname)) {
+        ctx.addIssue({
+          path: ["JCHAT_SITE_URL"],
+          code: "custom",
+          message: "JCHAT_SITE_URL must use the client main/root domain"
+        })
+      }
+    }
+
+    if (
+      env.JCHAT_STORAGE_TYPE === "MINIO" &&
+      !(
+        env.JCHAT_MINIO_ENDPOINT &&
+        env.JCHAT_MINIO_BUCKET_NAME &&
+        env.JCHAT_MINIO_ACCESS_KEY_ID &&
+        env.JCHAT_MINIO_SECRET_ACCESS_KEY &&
+        env.JCHAT_MINIO_PUBLIC_URL
+      )
+    ) {
+      if (!env.JCHAT_MINIO_ENDPOINT)
+        ctx.addIssue({
+          path: ["JCHAT_MINIO_ENDPOINT"],
+          code: "custom",
+          message: "JCHAT_MINIO_ENDPOINT is required when JCHAT_STORAGE_TYPE is MINIO"
+        })
+      if (!env.JCHAT_MINIO_BUCKET_NAME)
+        ctx.addIssue({
+          path: ["JCHAT_MINIO_BUCKET_NAME"],
+          code: "custom",
+          message: "JCHAT_MINIO_BUCKET_NAME is required when JCHAT_STORAGE_TYPE is MINIO"
+        })
+      if (!env.JCHAT_MINIO_ACCESS_KEY_ID)
+        ctx.addIssue({
+          path: ["JCHAT_MINIO_ACCESS_KEY_ID"],
+          code: "custom",
+          message: "JCHAT_MINIO_ACCESS_KEY_ID is required when JCHAT_STORAGE_TYPE is MINIO"
+        })
+      if (!env.JCHAT_MINIO_SECRET_ACCESS_KEY)
+        ctx.addIssue({
+          path: ["JCHAT_MINIO_SECRET_ACCESS_KEY"],
+          code: "custom",
+          message: "JCHAT_MINIO_SECRET_ACCESS_KEY is required when JCHAT_STORAGE_TYPE is MINIO"
+        })
+      if (!env.JCHAT_MINIO_PUBLIC_URL)
+        ctx.addIssue({
+          path: ["JCHAT_MINIO_PUBLIC_URL"],
+          code: "custom",
+          message: "JCHAT_MINIO_PUBLIC_URL is required when JCHAT_STORAGE_TYPE is MINIO"
+        })
+    }
+
+    if (
+      env.JCHAT_STORAGE_TYPE === "AWS_S3" &&
+      !(
+        env.JCHAT_AWS_REGION &&
+        env.JCHAT_AWS_ACCESS_KEY_ID &&
+        env.JCHAT_AWS_SECRET_ACCESS_KEY &&
+        env.JCHAT_AWS_BUCKET_NAME
+      )
+    ) {
+      if (!env.JCHAT_AWS_REGION)
+        ctx.addIssue({
+          path: ["JCHAT_AWS_REGION"],
+          code: "custom",
+          message: "JCHAT_AWS_REGION is required when JCHAT_STORAGE_TYPE is AWS_S3"
+        })
+      if (!env.JCHAT_AWS_ACCESS_KEY_ID)
+        ctx.addIssue({
+          path: ["JCHAT_AWS_ACCESS_KEY_ID"],
+          code: "custom",
+          message: "JCHAT_AWS_ACCESS_KEY_ID is required when JCHAT_STORAGE_TYPE is AWS_S3"
+        })
+      if (!env.JCHAT_AWS_SECRET_ACCESS_KEY)
+        ctx.addIssue({
+          path: ["JCHAT_AWS_SECRET_ACCESS_KEY"],
+          code: "custom",
+          message: "JCHAT_AWS_SECRET_ACCESS_KEY is required when JCHAT_STORAGE_TYPE is AWS_S3"
+        })
+      if (!env.JCHAT_AWS_BUCKET_NAME)
+        ctx.addIssue({
+          path: ["JCHAT_AWS_BUCKET_NAME"],
+          code: "custom",
+          message: "JCHAT_AWS_BUCKET_NAME is required when JCHAT_STORAGE_TYPE is AWS_S3"
+        })
+    }
+
+    if (
+      env.JCHAT_STORAGE_TYPE === "CLOUDFLARE_R2" &&
+      !(
+        env.JCHAT_CLOUDFLARE_ACCOUNT_ID &&
+        env.JCHAT_CLOUDFLARE_ACCESS_KEY_ID &&
+        env.JCHAT_CLOUDFLARE_SECRET_ACCESS_KEY &&
+        env.JCHAT_CLOUDFLARE_BUCKET_NAME &&
+        env.JCHAT_CLOUDFLARE_PUBLIC_URL
+      )
+    ) {
+      if (!env.JCHAT_CLOUDFLARE_ACCOUNT_ID)
+        ctx.addIssue({
+          path: ["JCHAT_CLOUDFLARE_ACCOUNT_ID"],
+          code: "custom",
+          message:
+            "JCHAT_CLOUDFLARE_ACCOUNT_ID is required when JCHAT_STORAGE_TYPE is CLOUDFLARE_R2"
+        })
+      if (!env.JCHAT_CLOUDFLARE_ACCESS_KEY_ID)
+        ctx.addIssue({
+          path: ["JCHAT_CLOUDFLARE_ACCESS_KEY_ID"],
+          code: "custom",
+          message:
+            "JCHAT_CLOUDFLARE_ACCESS_KEY_ID is required when JCHAT_STORAGE_TYPE is CLOUDFLARE_R2"
+        })
+      if (!env.JCHAT_CLOUDFLARE_SECRET_ACCESS_KEY)
+        ctx.addIssue({
+          path: ["JCHAT_CLOUDFLARE_SECRET_ACCESS_KEY"],
+          code: "custom",
+          message:
+            "JCHAT_CLOUDFLARE_SECRET_ACCESS_KEY is required when JCHAT_STORAGE_TYPE is CLOUDFLARE_R2"
+        })
+      if (!env.JCHAT_CLOUDFLARE_BUCKET_NAME)
+        ctx.addIssue({
+          path: ["JCHAT_CLOUDFLARE_BUCKET_NAME"],
+          code: "custom",
+          message:
+            "JCHAT_CLOUDFLARE_BUCKET_NAME is required when JCHAT_STORAGE_TYPE is CLOUDFLARE_R2"
+        })
+      if (!env.JCHAT_CLOUDFLARE_PUBLIC_URL)
+        ctx.addIssue({
+          path: ["JCHAT_CLOUDFLARE_PUBLIC_URL"],
+          code: "custom",
+          message:
+            "JCHAT_CLOUDFLARE_PUBLIC_URL is required when JCHAT_STORAGE_TYPE is CLOUDFLARE_R2"
+        })
+    }
+
+    if (
+      env.JCHAT_STORAGE_TYPE === "GCS" &&
+      !(
+        env.JCHAT_GCS_PROJECT_ID &&
+        env.JCHAT_GCS_BUCKET_NAME &&
+        env.JCHAT_GCS_CLIENT_EMAIL &&
+        env.JCHAT_GCS_PRIVATE_KEY
+      )
+    ) {
+      if (!env.JCHAT_GCS_PROJECT_ID)
+        ctx.addIssue({
+          path: ["JCHAT_GCS_PROJECT_ID"],
+          code: "custom",
+          message: "JCHAT_GCS_PROJECT_ID is required when JCHAT_STORAGE_TYPE is GCS"
+        })
+      if (!env.JCHAT_GCS_BUCKET_NAME)
+        ctx.addIssue({
+          path: ["JCHAT_GCS_BUCKET_NAME"],
+          code: "custom",
+          message: "JCHAT_GCS_BUCKET_NAME is required when JCHAT_STORAGE_TYPE is GCS"
+        })
+      if (!env.JCHAT_GCS_CLIENT_EMAIL)
+        ctx.addIssue({
+          path: ["JCHAT_GCS_CLIENT_EMAIL"],
+          code: "custom",
+          message: "JCHAT_GCS_CLIENT_EMAIL is required when JCHAT_STORAGE_TYPE is GCS"
+        })
+      if (!env.JCHAT_GCS_PRIVATE_KEY)
+        ctx.addIssue({
+          path: ["JCHAT_GCS_PRIVATE_KEY"],
+          code: "custom",
+          message: "JCHAT_GCS_PRIVATE_KEY is required when JCHAT_STORAGE_TYPE is GCS"
+        })
+    }
+  })
+
+export type ServerConfig = z.infer<typeof ServerConfigSchema>

package/src/index.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test"
+import crypto from "node:crypto"
+import { hasEntitlement, parsePayload, verifyEntitlement, verifySignature } from "./index"
+
+const keyPair = crypto.generateKeyPairSync("rsa", { modulusLength: 2048 })
+const publicKeyPem = keyPair.publicKey.export({ type: "spki", format: "pem" }).toString()
+
+function createToken(
+  overrides: Record<string, unknown> = {},
+  headerOverrides: Record<string, unknown> = {}
+) {
+  const header = Buffer.from(
+    JSON.stringify({ alg: "RS256", typ: "JWT", ...headerOverrides })
+  ).toString("base64url")
+  const payload = Buffer.from(
+    JSON.stringify({
+      iss: "https://license.jchat.local",
+      aud: "jchat-chat",
+      licenseId: "license-1",
+      domain: "www.example.com:8080",
+      buyer: "Customer",
+      installationId: "install-1",
+      machineFingerprint: "machine-1",
+      plan: "extended",
+      entitlements: ["site.create.multi"],
+      purchaseProvider: "envato",
+      environment: "production",
+      routingMode: "path",
+      iat: 1,
+      ...overrides
+    })
+  ).toString("base64url")
+  const signingInput = `${header}.${payload}`
+  const signature = crypto
+    .sign("sha256", Buffer.from(signingInput), keyPair.privateKey)
+    .toString("base64url")
+  return `${signingInput}.${signature}`
+}
+
+const options = { publicKeyPem }
+
+describe("license runtime", () => {
+  test("parses and verifies a normalized perpetual public-domain license", () => {
+    const token = createToken()
+    const payload = parsePayload(token)
+    expect(payload?.licenseId).toBe("license-1")
+    expect(payload).not.toHaveProperty("exp")
+    expect(verifySignature(token, "example.com", options)).toBe(true)
+    expect(verifyEntitlement(token, "example.com:3000", "install-1", "machine-1", options)).toBe(
+      true
+    )
+    expect(hasEntitlement(token, "www.example.com", "site.create.multi", options)).toBe(true)
+  })
+
+  test("rejects forged signatures and binding mismatches", () => {
+    const token = createToken()
+    expect(verifySignature(`${token}x`, "example.com", options)).toBe(false)
+    expect(verifySignature(token, "other.example.com", options)).toBe(false)
+    expect(verifyEntitlement(token, "example.com", "other-install", "machine-1", options)).toBe(
+      false
+    )
+    expect(verifyEntitlement(token, "example.com", "install-1", "other-machine", options)).toBe(
+      false
+    )
+  })
+
+  test("rejects issuer, audience, and algorithm mismatches", () => {
+    expect(
+      verifySignature(createToken({ iss: "https://other.example" }), "example.com", options)
+    ).toBe(false)
+    expect(verifySignature(createToken({ aud: "other-app" }), "example.com", options)).toBe(false)
+    expect(verifySignature(createToken({}, { alg: "HS256" }), "example.com", options)).toBe(false)
+  })
+
+  test("rejects malformed and incomplete claims", () => {
+    for (const overrides of [
+      { licenseId: undefined },
+      { domain: 42 },
+      { buyer: "" },
+      { installationId: undefined },
+      { machineFingerprint: undefined },
+      { plan: "multi" },
+      { entitlements: "site.create.multi" },
+      { purchaseProvider: "unknown" },
+      { environment: "staging" },
+      { routingMode: "host" },
+      { iat: "now" }
+    ]) {
+      expect(parsePayload(createToken(overrides))).toBeNull()
+    }
+    expect(parsePayload("header.invalid.signature")).toBeNull()
+  })
+
+  test("enforces standard and extended entitlement consistency", () => {
+    const standard = createToken({ plan: "standard", entitlements: [] })
+    expect(verifyEntitlement(standard, "example.com", "install-1", "machine-1", options)).toBe(true)
+    expect(hasEntitlement(standard, "example.com", "site.create.multi", options)).toBe(false)
+
+    expect(parsePayload(createToken({ plan: "standard" }))).toBeNull()
+    expect(parsePayload(createToken({ plan: "extended", entitlements: [] }))).toBeNull()
+  })
+
+  test("allows only vendor-issued development claims on localhost", () => {
+    const development = createToken({
+      domain: "localhost",
+      plan: "standard",
+      entitlements: [],
+      environment: "development"
+    })
+    expect(
+      verifyEntitlement(development, "www.localhost:3000", "install-1", "machine-1", options)
+    ).toBe(true)
+
+    expect(parsePayload(createToken({ domain: "localhost" }))).toBeNull()
+    expect(parsePayload(createToken({ environment: "development" }))).toBeNull()
+  })
+})