feat(licensing): bake licensing endpoint into bundle at build time

Mirrors evolution-go/tools/build-dist/obfuscate.go: the URL of the licensing
server is now XOR-encoded into the JS bundle by tsup `define`, so it never
appears as a plain literal in dist/main.js. The Dockerfile accepts the pair
as build-args (NOT runtime env vars) so an operator cannot point the running
service at a different licensing server.

- src/licensing/endpoint.ts: read from compile-time `__LICENSE_ENDPOINT_*__`
  identifiers replaced by tsup; keep parts-array fallback for dev builds.
- tsup.config.ts: `define` reads LICENSE_ENDPOINT_ENCODED / _XOR_KEY from
  build env at the moment npm run build is invoked.
- tools/encode-url.js: helper to generate the hex pair for a given URL.
  Usage: eval "$(node tools/encode-url.js <url>)".
- Dockerfile: ARG + ENV plumbing for the build stage only.
- CHANGELOG: notes about the build-time obfuscation.

Author: DavidsonGomes

CHANGELOG.md

@@ -91,6 +91,12 @@ The following routes always remain public so the operator can recover:
 - If the licensing server is unreachable but the instance has been activated
   before, the service continues to serve traffic normally — local DB is the
   source of truth for activation state after the first successful call.
+- Release builds bake the licensing endpoint into the bundle as an XOR-encoded
+  string via tsup `define`, so the URL never appears as a plain literal in
+  `dist/main.js`. Generate the pair with `node tools/encode-url.js <url>` and
+  pass `LICENSE_ENDPOINT_ENCODED` / `LICENSE_ENDPOINT_XOR_KEY` as Docker
+  build-args (NOT runtime env vars). Local dev builds use a parts-array
+  fallback that still avoids a single string literal but is not obfuscated.
 
 ### Troubleshooting
 

Dockerfile

@@ -31,6 +31,16 @@ RUN chmod +x ./Docker/scripts/* && dos2unix ./Docker/scripts/*
 
 RUN ./Docker/scripts/generate_database.sh
 
+# Licensing endpoint is XOR-encoded into the bundle by tsup `define`. Pass the
+# pair via build-args (NEVER as runtime env vars) to keep the URL out of the
+# compiled JavaScript as a plain literal. Generate them with
+# `node tools/encode-url.js <url>`. Leaving them empty is OK for non-release
+# builds — the dev fallback in src/licensing/endpoint.ts kicks in.
+ARG LICENSE_ENDPOINT_ENCODED
+ARG LICENSE_ENDPOINT_XOR_KEY
+ENV LICENSE_ENDPOINT_ENCODED=${LICENSE_ENDPOINT_ENCODED}
+ENV LICENSE_ENDPOINT_XOR_KEY=${LICENSE_ENDPOINT_XOR_KEY}
+
 RUN NODE_OPTIONS="--max-old-space-size=2048" npm run build
 
 FROM node:24-alpine AS final

src/licensing/endpoint.ts

@@ -1,9 +1,28 @@
 // Mirrors evolution-go/pkg/core/endpoint.go
-// In release builds, set LICENSE_ENDPOINT_ENCODED + LICENSE_ENDPOINT_XOR_KEY (hex).
-// In dev, the URL is reconstructed from a parts array — same technique as the Go version.
+//
+// The licensing URL is **build-time only** — it gets baked into the bundle by
+// tsup's `define` so the operator cannot point the running service at a
+// different licensing server via env vars.
+//
+// In release builds the Dockerfile passes:
+//   LICENSE_ENDPOINT_ENCODED=<hex>   (XOR-encoded URL)
+//   LICENSE_ENDPOINT_XOR_KEY=<hex>   (XOR key)
+//
+// Use `node tools/encode-url.js https://license.evolutionfoundation.com.br`
+// to generate the pair.
+//
+// In dev (vars empty), the URL is reconstructed from a parts array — same
+// technique as evolution-go.
 
-const encodedEP = process.env.LICENSE_ENDPOINT_ENCODED ?? '';
-const xorKey = process.env.LICENSE_ENDPOINT_XOR_KEY ?? '';
+// These two identifiers are replaced at bundle time by tsup `define`.
+// Do NOT inline them or read them from process.env — see tsup.config.ts.
+declare const __LICENSE_ENDPOINT_ENCODED__: string;
+declare const __LICENSE_ENDPOINT_XOR_KEY__: string;
+
+const encodedEP =
+  typeof __LICENSE_ENDPOINT_ENCODED__ === 'string' ? __LICENSE_ENDPOINT_ENCODED__ : '';
+const xorKey =
+  typeof __LICENSE_ENDPOINT_XOR_KEY__ === 'string' ? __LICENSE_ENDPOINT_XOR_KEY__ : '';
 
 export function resolveEndpoint(): string {
   if (encodedEP && xorKey) {

tools/encode-url.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Encodes a URL with a fresh random XOR key for the licensing endpoint.
+ * Mirrors evolution-go/tools/build-dist/obfuscate.go.
+ *
+ * Usage:
+ *   node tools/encode-url.js <url>
+ *
+ * Example:
+ *   node tools/encode-url.js https://license.evolutionfoundation.com.br
+ *
+ * Pipe the output into the build:
+ *   eval "$(node tools/encode-url.js https://license.evolutionfoundation.com.br)"
+ *   npm run build
+ */
+
+const crypto = require('node:crypto');
+
+const url = process.argv[2];
+if (!url) {
+  console.error('usage: node tools/encode-url.js <url>');
+  process.exit(2);
+}
+
+const urlBytes = Buffer.from(url, 'utf8');
+const keyBytes = crypto.randomBytes(urlBytes.length);
+const encBytes = Buffer.alloc(urlBytes.length);
+for (let i = 0; i < urlBytes.length; i++) {
+  encBytes[i] = urlBytes[i] ^ keyBytes[i];
+}
+
+const encoded = encBytes.toString('hex');
+const key = keyBytes.toString('hex');
+
+// Print eval-friendly export lines.
+process.stdout.write(`export LICENSE_ENDPOINT_ENCODED=${encoded}\n`);
+process.stdout.write(`export LICENSE_ENDPOINT_XOR_KEY=${key}\n`);

tsup.config.ts

@@ -2,6 +2,11 @@ import { cpSync } from 'node:fs';
 
 import { defineConfig } from 'tsup';
 
+// Build-time licensing URL — passed via env vars only at build time, baked
+// into the bundle by `define`. See src/licensing/endpoint.ts.
+const licenseEndpointEncoded = JSON.stringify(process.env.LICENSE_ENDPOINT_ENCODED ?? '');
+const licenseEndpointXorKey = JSON.stringify(process.env.LICENSE_ENDPOINT_XOR_KEY ?? '');
+
 export default defineConfig({
   entry: ['src'],
   outDir: 'dist',
@@ -10,6 +15,10 @@ export default defineConfig({
   clean: true,
   minify: true,
   format: ['cjs', 'esm'],
+  define: {
+    __LICENSE_ENDPOINT_ENCODED__: licenseEndpointEncoded,
+    __LICENSE_ENDPOINT_XOR_KEY__: licenseEndpointXorKey,
+  },
   onSuccess: async () => {
     cpSync('src/utils/translations', 'dist/translations', { recursive: true });
   },