@rage-against-the-pixel/unity-cli 3.0.2 → 4.0.1

package/dist/license-client.js

@@ -34,23 +34,56 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LicensingClient = exports.LicenseType = void 0;
+exports.LicensingClientDiagnostic = LicensingClientDiagnostic;
+exports.GetLegacyLicenseVersion = GetLegacyLicenseVersion;
+exports.ActivateLicense = ActivateLicense;
+exports.IsSharedRunnerIdentity = IsSharedRunnerIdentity;
+exports.ReturnLicense = ReturnLicense;
+exports.PrintLicenseContext = PrintLicenseContext;
+exports.GetLicenseFilePath = GetLicenseFilePath;
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const logging_1 = require("./logging");
-const unity_hub_1 = require("./unity-hub");
+const unity_cli_1 = require("./unity-cli");
 const utilities_1 = require("./utilities");
+const process_tracker_1 = require("./process-tracker");
 var LicenseType;
 (function (LicenseType) {
     LicenseType["personal"] = "personal";
     LicenseType["professional"] = "professional";
     LicenseType["floating"] = "floating";
 })(LicenseType || (exports.LicenseType = LicenseType = {}));
+/**
+ * The v3 licensing client, which drives Unity.Licensing.Client directly.
+ * v4 uses it as the fallback when the official Unity CLI cannot activate or return a license,
+ * for example a personal license on a headless runner, and for Unity 4.x and 5.x editors.
+ */
+/** How long one Unity Licensing Client command may run. */
+const LICENSING_CLIENT_TIMEOUT_MS = 10 * 60 * 1000;
+// literal alternations only, so matching stays linear on any line
+const LICENSING_DIAGNOSTIC_PATTERN = /error|fail|seat|entitlement|activation|limit|denied|invalid|expired/i;
+/**
+ * The lines of sanitized licensing client output that say why a command failed, such as a seat limit.
+ * @param lines The client output, already sanitized.
+ * @returns At most the last 3 matching lines, each cut to 300 characters, or undefined when none match.
+ */
+function LicensingClientDiagnostic(lines) {
+    const matches = lines
+        .map(line => line.trim())
+        .filter(line => line.length > 0 && LICENSING_DIAGNOSTIC_PATTERN.test(line))
+        .slice(-3)
+        .map(line => line.length > 300 ? `${line.slice(0, 300)}...` : line);
+    return matches.length > 0 ? matches.join('\n') : undefined;
+}
 class LicensingClient {
-    unityHub = new unity_hub_1.UnityHub();
     logger = logging_1.Logger.instance;
     licenseClientPath;
+    secrets = [];
+    isLicenseClientPatched = false;
+    /** Where the 4.x/5.x license link lives, and the folders the client may have written Unity_lic.ulf to. */
+    legacyLicense;
     licenseVersion;
     /**
      * Creates an instance of LicensingClient.
@@ -59,20 +92,186 @@ class LicensingClient {
     constructor(licenseVersion = undefined) {
         this.licenseVersion = licenseVersion;
     }
+    /**
+     * Finds Unity.Licensing.Client: UNITY_LICENSING_CLIENT_PATH, then the copy the official Unity CLI manages,
+     * then the Hub's external modules folder, then the client bundled with the editor in UNITY_EDITOR_PATH.
+     * @returns The licensing client executable.
+     */
     async init() {
-        try {
-            await fs.promises.access(this.unityHub.executable, fs.constants.R_OK);
-            await fs.promises.access(this.unityHub.rootDirectory, fs.constants.R_OK);
+        const licensingClientExecutable = process.platform === 'win32' ? 'Unity.Licensing.Client.exe' : 'Unity.Licensing.Client';
+        let licenseClientPath = process.env.UNITY_LICENSING_CLIENT_PATH;
+        const legacyVersion = this.licenseVersion ?? GetLegacyLicenseVersion();
+        if (!licenseClientPath && process.platform === 'darwin' && (legacyVersion === '4.x' || legacyVersion === '5.x')) {
+            // the macOS client the Unity CLI downloads cannot be patched for 4.x/5.x, so use the one Unity Hub bundled
+            licenseClientPath = await LicensingClient.getHubBundledClient();
         }
-        catch (error) {
-            throw new Error('Unity Hub is not installed or not accessible. Please install Unity Hub before using the Licensing Client.');
+        if (!licenseClientPath) {
+            try {
+                const cli = await unity_cli_1.UnityCli.Get();
+                licenseClientPath = await cli.GetLicensingClientPath();
+            }
+            catch (error) {
+                this.logger.debug(`The Unity CLI did not report a licensing client: ${error}`);
+            }
         }
-        const licensingClientExecutable = process.platform === 'win32' ? 'Unity.Licensing.Client.exe' : 'Unity.Licensing.Client';
-        const licenseClientPath = await (0, utilities_1.ResolveGlobToPath)([this.unityHub.rootDirectory, '**', licensingClientExecutable]);
+        if (!licenseClientPath) {
+            const candidates = LicensingClient.externalModulesDirectories()
+                .map(directory => [directory, '**', licensingClientExecutable]);
+            const editorPath = process.env.UNITY_EDITOR_PATH;
+            if (editorPath && editorPath.length > 0) {
+                candidates.push([path.dirname(editorPath), '**', 'Licensing', 'Client', licensingClientExecutable]);
+            }
+            licenseClientPath = await (0, utilities_1.ResolvePathCandidates)(candidates);
+        }
+        if (!licenseClientPath) {
+            throw new Error('Failed to find Unity.Licensing.Client. Set UNITY_LICENSING_CLIENT_PATH to its location.');
+        }
+        await LicensingClient.ensureMacLicenseDirectory();
         this.licenseClientPath = licenseClientPath;
         await fs.promises.access(this.licenseClientPath, fs.constants.X_OK);
+        this.logger.debug(`Using Unity Licensing Client at ${this.licenseClientPath}`);
         return this.licenseClientPath;
     }
+    /**
+     * Extracts the licensing client bundled with Unity Hub 3.12.0 on macOS. Its resolver is a separate assembly that
+     * the 4.x/5.x patch works on, unlike the single-file macOS client the Unity CLI downloads, whose licenses stay 6.x.
+     * Only the client is copied out; the Hub is not installed.
+     * @returns The extracted client executable.
+     */
+    static async getHubBundledClient() {
+        const hubVersion = '3.12.0';
+        const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+        const cacheDirectory = await LicensingClient.privateDirectory(`hub-client-${hubVersion}-${arch}`);
+        const findClient = async () => (await fs.promises.readdir(cacheDirectory, { recursive: true }))
+            .map(entry => path.join(cacheDirectory, entry.toString()))
+            .find(entry => path.basename(entry) === 'Unity.Licensing.Client' && fs.statSync(entry).isFile());
+        if (fs.existsSync(cacheDirectory)) {
+            const cached = await findClient();
+            if (cached) {
+                return cached;
+            }
+        }
+        const dmgPath = path.join((0, utilities_1.GetTempDir)(), `UnityHubSetup-${hubVersion}-${arch}.dmg`);
+        const mountPoint = path.join((0, utilities_1.GetTempDir)(), `UnityHub-${hubVersion}-${arch}`);
+        // pinned so a tampered download never reaches the client that receives the Unity ID
+        const dmgSha256 = {
+            'x64': '1b5e9698b6353cb814618ea12c6ca014d50fc33efe086da6b67e5b442a77bb3e',
+            'arm64': '0026d98a375d926090b144ca3d54e982612aa24a59404e004e333dc34c4b832a',
+        };
+        await (0, utilities_1.DownloadFile)(`https://public-cdn.cloud.unity3d.com/hub/${hubVersion}/UnityHubSetup-${arch}.dmg`, dmgPath, { sha256: dmgSha256[arch] });
+        await fs.promises.mkdir(mountPoint, { recursive: true });
+        try {
+            await (0, utilities_1.Exec)('hdiutil', ['attach', dmgPath, '-nobrowse', '-readonly', '-mountpoint', mountPoint], { silent: true, showCommand: true });
+            try {
+                const client = await (0, utilities_1.ResolveGlobToPath)([mountPoint, '**', 'Unity.Licensing.Client']);
+                const sourceDirectory = LicensingClient.clientRootDirectory(client);
+                await fs.promises.rm(cacheDirectory, { recursive: true, force: true });
+                await fs.promises.cp(sourceDirectory, cacheDirectory, { recursive: true, verbatimSymlinks: true });
+            }
+            finally {
+                await (0, utilities_1.Exec)('hdiutil', ['detach', mountPoint, '-quiet'], { silent: true, showCommand: true });
+            }
+        }
+        finally {
+            await fs.promises.rm(dmgPath, { force: true });
+        }
+        const extracted = await findClient();
+        if (!extracted) {
+            throw new Error(`Failed to extract Unity.Licensing.Client from Unity Hub ${hubVersion}`);
+        }
+        logging_1.Logger.instance.info(`Using the Unity Licensing Client bundled with Unity Hub ${hubVersion}: ${extracted}`);
+        return extracted;
+    }
+    /**
+     * On macOS the client writes Unity_lic.ulf to /Library/Application Support/Unity. When that folder is missing or not
+     * writable it asks for an administrator password in a dialog, which never returns on a headless runner.
+     * The Unity Hub installer used to create it; without the Hub, it is created here with non-interactive sudo.
+     */
+    static async ensureMacLicenseDirectory() {
+        if (process.platform !== 'darwin') {
+            return;
+        }
+        const directory = '/Library/Application Support/Unity';
+        try {
+            await fs.promises.access(directory, fs.constants.W_OK);
+            return;
+        }
+        catch {
+            // missing or not writable
+        }
+        // owned by the current user rather than world-writable
+        const user = os.userInfo().username;
+        for (const args of [['-n', 'mkdir', '-p', directory], ['-n', 'chown', user, directory], ['-n', 'chmod', '755', directory]]) {
+            const exitCode = await new Promise((resolve) => {
+                const child = (0, child_process_1.spawn)('sudo', args, { stdio: 'ignore' });
+                child.on('error', () => resolve(1));
+                child.on('close', (code) => resolve(code ?? 1));
+            });
+            if (exitCode !== 0) {
+                logging_1.Logger.instance.warn(`Could not prepare ${directory} (sudo ${args.slice(1).join(' ')} exited with code ${exitCode}). Activation may wait for an administrator password.`);
+                return;
+            }
+        }
+    }
+    /**
+     * Gets a folder under ~/.unity-cli/licensing that only the current user can read and write, creating it when needed.
+     * Used instead of the shared temp folder for the patched licensing client and the license it writes.
+     * @param name The folder name.
+     */
+    static async privateDirectory(name) {
+        const root = path.join(os.homedir(), '.unity-cli', 'licensing');
+        await fs.promises.mkdir(root, { recursive: true, mode: 0o700 });
+        if (process.platform !== 'win32') {
+            await fs.promises.chmod(root, 0o700);
+        }
+        return path.join(root, name);
+    }
+    /**
+     * The folder that holds the whole licensing client: the bundle root for a macOS bundle (…/Contents/MacOS/client), otherwise the executable's folder.
+     */
+    static clientRootDirectory(clientPath) {
+        const macOSDirectory = path.dirname(clientPath);
+        if (path.basename(macOSDirectory) === 'MacOS' && path.basename(path.dirname(macOSDirectory)) === 'Contents') {
+            return path.dirname(path.dirname(macOSDirectory));
+        }
+        return macOSDirectory;
+    }
+    /**
+     * Lists the files under a directory that can hold compiled code: executables, libraries and extensionless binaries.
+     */
+    static async listBinaries(directory) {
+        const results = [];
+        for (const entry of await fs.promises.readdir(directory, { withFileTypes: true, recursive: true })) {
+            if (!entry.isFile()) {
+                continue;
+            }
+            const extension = path.extname(entry.name).toLowerCase();
+            // the macOS client is named Unity.Licensing.Client, so its extension reads as ".client"
+            const isClient = entry.name.startsWith('Unity.Licensing.') && !['.md', '.config', '.json', '.plist', '.xml', '.txt'].includes(extension);
+            if (isClient || ['', '.exe', '.dll', '.dylib', '.so'].includes(extension)) {
+                results.push(path.join(entry.parentPath, entry.name));
+            }
+        }
+        return results;
+    }
+    /**
+     * The folders the Unity Hub and the official Unity CLI download Unity.Licensing.Client to.
+     */
+    static externalModulesDirectories() {
+        switch (process.platform) {
+            case 'win32':
+                return [path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'UnityHub', 'external-modules')];
+            case 'darwin':
+                return [path.join(os.homedir(), 'Library', 'Application Support', 'UnityHub', 'external-modules')];
+            default: {
+                const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+                return [
+                    path.join(configHome, 'UnityHub', 'external-modules'),
+                    path.join(configHome, 'unityhub', 'external-modules'),
+                ];
+            }
+        }
+    }
     getUnityCommonDir() {
         const result = process.env['UNITY_COMMON_DIR'];
         if (result) {
@@ -155,6 +354,11 @@ class LicensingClient {
         }
         throw new Error('Services config value is not a valid JSON string or base64 encoded JSON string.');
     }
+    /**
+     * Writes the floating license server's services-config.json where Unity's licensing reads it.
+     * @param configSource A path to the configuration file, raw JSON, or base64 encoded JSON.
+     * @returns The path the configuration was written to.
+     */
     async setupServicesConfig(configSource) {
         const servicesConfigPath = this.servicesConfigPath();
         if (fs.existsSync(configSource)) {
@@ -281,27 +485,8 @@ class LicensingClient {
     }
     async patchLicenseVersion() {
         if (!this.licenseVersion) {
-            // check if the UNITY_EDITOR_PATH is set. If it is, use it to determine the license version
-            const versionMatch = process.env.UNITY_EDITOR_PATH?.match(/(\d+)\.(\d+)\.(\d+)/);
-            if (versionMatch) {
-                switch (versionMatch[1]) {
-                    case '4': {
-                        this.licenseVersion = '4.x';
-                        break;
-                    }
-                    case '5': {
-                        this.licenseVersion = '5.x';
-                        break;
-                    }
-                    default: {
-                        this.licenseVersion = '6.x'; // default to 6.x for any other
-                        break;
-                    }
-                }
-            }
-            else {
-                this.licenseVersion = '6.x'; // default to 6.x if not set
-            }
+            // use the editor in UNITY_EDITOR_PATH to determine the license version, defaulting to 6.x
+            this.licenseVersion = GetLegacyLicenseVersion() ?? '6.x';
         }
         if (this.licenseVersion !== '6.x') {
             if (this.licenseVersion !== '5.x' && this.licenseVersion !== '4.x') {
@@ -312,32 +497,78 @@ class LicensingClient {
         if (!this.licenseClientPath) {
             this.licenseClientPath = await this.init();
         }
-        if (this.licenseVersion === '6.x') {
-            return; // no patching needed
+        if (this.licenseVersion === '6.x' || this.isLicenseClientPatched) {
+            return; // no patching needed, or already done for this instance
         }
-        const clientDirectory = path.dirname(this.licenseClientPath);
-        const patchedDirectory = path.join(os.tmpdir(), `UnityLicensingClient-${this.licenseVersion.replace('.', '_')}`);
-        if (await fs.promises.mkdir(patchedDirectory, { recursive: true }) === undefined) {
-            this.logger.debug('Unity Licensing Client was already patched, reusing');
+        const clientRoot = LicensingClient.clientRootDirectory(this.licenseClientPath);
+        // a private per-user folder rather than the shared temp folder: it holds a client that receives the Unity ID and the license it writes
+        const patchedDirectory = await LicensingClient.privateDirectory(`patched-client-${this.licenseVersion.replace('.', '_')}`);
+        const patchedClientPath = path.join(patchedDirectory, path.relative(clientRoot, this.licenseClientPath));
+        const sourceMarker = path.join(patchedDirectory, '.source-sha256');
+        const sourceHash = await (0, utilities_1.Sha256FileHex)(this.licenseClientPath);
+        const isCurrent = (await fs.promises.readFile(sourceMarker, 'utf-8').catch(() => '')).trim() === sourceHash;
+        if (isCurrent) {
+            this.logger.debug('Unity Licensing Client was already patched from the same client, reusing');
         }
         else {
-            let found = false;
-            for (const fileName of await fs.promises.readdir(clientDirectory)) {
-                if (fileName === 'Unity.Licensing.EntitlementResolver.dll') {
-                    await this.patchBinary(path.join(clientDirectory, fileName), path.join(patchedDirectory, fileName), Buffer.from('6.x', 'utf16le'), Buffer.from(this.licenseVersion, 'utf16le'));
-                    found = true;
+            await fs.promises.rm(patchedDirectory, { recursive: true, force: true });
+            await fs.promises.mkdir(patchedDirectory, { recursive: true, mode: 0o700 });
+            // copy the whole client, then patch whichever binary holds the "6.x" license version:
+            // older clients ship it in Unity.Licensing.EntitlementResolver.dll, the single-file client the Unity CLI downloads embeds it in the executable
+            await fs.promises.cp(clientRoot, patchedDirectory, { recursive: true, verbatimSymlinks: true });
+            const patchedFiles = [];
+            // Windows and Linux builds hold the value as a UTF-16 string; the macOS build only as the
+            // UTF-8 constant k_UnityLicenseVersionCompatibility, so that one is matched with its name
+            const constantName = Buffer.concat([Buffer.from('k_UnityLicenseVersionCompatibility'), Buffer.from([0x06])]);
+            const patterns = [
+                [Buffer.from('6.x', 'utf16le'), Buffer.from(this.licenseVersion, 'utf16le')],
+                [Buffer.concat([constantName, Buffer.from('6.x')]), Buffer.concat([constantName, Buffer.from(this.licenseVersion)])],
+            ];
+            const binaries = await LicensingClient.listBinaries(patchedDirectory);
+            // the UTF-8 constant is only patched when no UTF-16 value exists, which leaves the Windows and Linux patch as it was
+            for (const [searchValue, replaceValue] of patterns) {
+                for (const file of binaries) {
+                    try {
+                        await this.patchBinary(file, file, searchValue, replaceValue);
+                        patchedFiles.push(file);
+                    }
+                    catch (error) {
+                        if (!(error instanceof Error && error.message === 'Could not find the search value')) {
+                            throw error;
+                        }
+                    }
                 }
-                else {
-                    await fs.promises.symlink(path.join(clientDirectory, fileName), path.join(patchedDirectory, fileName));
+                if (patchedFiles.length > 0) {
+                    break;
                 }
             }
-            if (!found) {
-                throw new Error('Could not find Unity.Licensing.EntitlementResolver.dll in the unityhub installation');
+            if (patchedFiles.length === 0) {
+                const searched = (await LicensingClient.listBinaries(patchedDirectory)).map(file => path.relative(patchedDirectory, file));
+                await fs.promises.rm(patchedDirectory, { recursive: true, force: true });
+                throw new Error(`Could not find the 6.x license version in any Unity Licensing Client binary under ${clientRoot}. Searched:\n${searched.map(file => `  > ${file}`).join('\n')}`);
+            }
+            this.logger.debug(`Patched the license version in:\n${patchedFiles.map(file => `  > ${file}`).join('\n')}`);
+            await fs.promises.chmod(patchedClientPath, 0o755);
+            if (process.platform === 'darwin') {
+                // patching invalidates the signature, and macOS kills binaries with a broken one
+                const isBundle = fs.existsSync(path.join(patchedDirectory, 'Contents', 'MacOS'));
+                const targets = isBundle ? [patchedDirectory] : patchedFiles;
+                for (const target of targets) {
+                    await new Promise((resolve, reject) => {
+                        const child = (0, child_process_1.spawn)('codesign', ['--force', '--deep', '--sign', '-', target], { stdio: 'ignore' });
+                        child.on('error', reject);
+                        child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`codesign failed with exit code ${code}`)));
+                    });
+                }
             }
+            // records which client the copy came from, so a newer client is patched again instead of reused
+            await fs.promises.writeFile(sourceMarker, sourceHash, { encoding: 'utf-8', mode: 0o600 });
         }
-        this.licenseClientPath = path.join(patchedDirectory, path.basename(this.licenseClientPath));
+        this.licenseClientPath = patchedClientPath;
+        this.isLicenseClientPatched = true;
         const unityCommonDir = this.getUnityCommonDir();
         const legacyLicenseFile = path.join(unityCommonDir, `Unity_v${this.licenseVersion}.ulf`);
+        this.legacyLicense ??= { linkPath: legacyLicenseFile, commonDirectory: unityCommonDir, patchedDirectory };
         await fs.promises.mkdir(unityCommonDir, { recursive: true });
         try {
             await fs.promises.symlink(path.join(patchedDirectory, 'Unity_lic.ulf'), legacyLicenseFile);
@@ -360,24 +591,42 @@ class LicensingClient {
         }
         let output = '';
         let exitCode = 0;
-        this.logger.startGroup(`\x1b[34m${this.licenseClientPath} ${args.join(' ')}\x1b[0m`);
+        let timedOut = false;
+        let killedBy = null;
+        // values that must never reach a log, even outside CI where ::add-mask:: does nothing
+        const sensitiveFlags = ['--username', '--password', '--serial', '--return-floating'];
+        const argSecrets = args.filter((_, i) => i > 0 && sensitiveFlags.includes(args[i - 1]));
+        const secrets = [...this.secrets, ...argSecrets];
+        const redact = (text) => (0, utilities_1.redactSensitiveLiterals)(text, secrets);
+        this.logger.startGroup(`\x1b[34m${this.licenseClientPath} ${redact(args.join(' '))}\x1b[0m`);
+        const logOffset = await this.getClientLogSize();
         await fs.promises.access(this.licenseClientPath, fs.constants.R_OK | fs.constants.X_OK);
         try {
             exitCode = await new Promise((resolve, reject) => {
                 fs.accessSync(this.licenseClientPath, fs.constants.R_OK | fs.constants.X_OK);
+                const startedAt = Date.now();
                 const child = (0, child_process_1.spawn)(this.licenseClientPath, args, {
-                    stdio: ['ignore', 'pipe', 'pipe']
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    ...(0, process_tracker_1.OwnedSpawnOptions)(),
                 });
+                // the background instance the client can start stays reachable through this record
+                (0, process_tracker_1.TrackOwnedProcess)(child, startedAt);
                 const sigintHandler = () => child.kill('SIGINT');
                 const sigtermHandler = () => child.kill('SIGTERM');
                 process.once('SIGINT', sigintHandler);
                 process.once('SIGTERM', sigtermHandler);
+                // a client that waits on something that never comes must not hold a CI job until it times out
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    child.kill('SIGKILL');
+                }, LICENSING_CLIENT_TIMEOUT_MS);
                 let hasCleanedUpListeners = false;
                 function removeListeners() {
                     if (hasCleanedUpListeners) {
                         return;
                     }
                     hasCleanedUpListeners = true;
+                    clearTimeout(timer);
                     process.removeListener('SIGINT', sigintHandler);
                     process.removeListener('SIGTERM', sigtermHandler);
                 }
@@ -391,17 +640,38 @@ class LicensingClient {
                     removeListeners();
                     reject(error);
                 });
-                child.on('close', (code) => {
+                // the client can start a background instance that inherits its stdout and stderr,
+                // so 'close' may never fire; settle on 'exit' and stop reading the pipes shortly after
+                let settled = false;
+                const settle = (code, signal) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
                     removeListeners();
-                    resolve(code === null ? 0 : code);
+                    killedBy = signal;
+                    // a client killed by a signal did not finish its work, so it is a failure, not exit code 0
+                    resolve(timedOut ? -1 : code === null ? (signal ? -2 : 0) : code);
+                };
+                child.on('close', settle);
+                child.on('exit', (code, signal) => {
+                    setTimeout(() => {
+                        child.stdout.destroy();
+                        child.stderr.destroy();
+                        settle(code, signal);
+                    }, 1000);
                 });
             });
         }
         finally {
+            if (timedOut) {
+                this.logger.error(`Unity Licensing Client did not finish within ${LICENSING_CLIENT_TIMEOUT_MS / 60000} minutes. Its log: ${LicensingClient.ClientLogPath()}`);
+                await this.printClientLogProblems(logOffset, secrets);
+            }
+            // any client output can carry emails and tokens, so it gets the same sanitizing as the client log
+            const maskedLines = this.maskSerialInOutput(output).split(/\r?\n/).map(line => LicensingClient.sanitizeLogLine(line, secrets));
             if (!silent || exitCode !== 0) {
-                const maskedOutput = this.maskSerialInOutput(output);
-                const splitLines = maskedOutput.split(/\r?\n/);
-                for (const line of splitLines) {
+                for (const line of maskedLines) {
                     if (line === undefined || line.length === 0) {
                         continue;
                     }
@@ -410,12 +680,61 @@ class LicensingClient {
             }
             this.logger.endGroup();
             if (exitCode !== 0) {
-                const message = this.getExitCodeMessage(exitCode);
+                let message = timedOut ? 'Timed out' : killedBy ? `Killed by ${killedBy}` : this.getExitCodeMessage(exitCode);
+                // Unity ID throttles sign-ins when many jobs activate with one account at once; naming it lets the
+                // failure be marked for a rerun once those jobs finish
+                if (/maximum same user attempt retry count/i.test(output)) {
+                    message = 'Unity ID sign-in rate limit reached: too many sign-in attempts for this account';
+                }
+                // the client's own reason, such as a seat limit, lets the failure be classified; exit 17 alone does not say
+                const diagnostic = LicensingClientDiagnostic(maskedLines);
+                if (diagnostic) {
+                    message += `\n${diagnostic}`;
+                }
                 throw new Error(`License command failed with exit code ${exitCode}: ${message}`);
             }
         }
         return output;
     }
+    /**
+     * Redacts the known secrets, email addresses and long token-like strings (JWTs, access and refresh tokens) from a client log line.
+     * The line is split on separator characters and each piece is checked on its own, which stays linear on any input.
+     */
+    static sanitizeLogLine(line, secrets) {
+        return (0, utilities_1.SanitizeLogText)(line, secrets);
+    }
+    /**
+     * Prints the last lines the client logged since `offset`, to show why a command hung.
+     * The log can hold account details and tokens, so every line is sanitized first.
+     */
+    async printClientLogProblems(offset, secrets, maxLines = 40) {
+        try {
+            const content = await fs.promises.readFile(LicensingClient.ClientLogPath());
+            const lines = content.subarray(offset).toString('utf-8').split(/\r?\n/)
+                .filter(line => line.trim().length > 0)
+                .slice(-maxLines)
+                .map(line => LicensingClient.sanitizeLogLine(line, secrets));
+            if (lines.length > 0) {
+                this.logger.info(`Last lines the Unity Licensing Client logged (redacted):\n${lines.join('\n')}`);
+            }
+        }
+        catch (error) {
+            this.logger.debug(`Could not read the Unity Licensing Client log: ${error}`);
+        }
+    }
+    /**
+     * Stops Unity.Licensing.Client instances that this job's unity-cli commands started, directly or through the
+     * official Unity CLI or an editor run. A command line activation can wait on such an instance indefinitely.
+     * Clients other jobs started are left alone, even on a shared self-hosted runner. Only done in CI.
+     */
+    static async StopBackgroundClients() {
+        if (process.env.CI !== 'true') {
+            return;
+        }
+        // matched on the executable's own name, so a process that only mentions it on its command line is left alone
+        const clients = (await (0, process_tracker_1.FindOwnedProcesses)()).filter(proc => (0, process_tracker_1.IsExecutableNamed)(proc, 'Unity.Licensing.Client'));
+        await Promise.all(clients.map(client => (0, utilities_1.KillProcess)(client).catch(() => undefined)));
+    }
     maskSerialInOutput(output) {
         return output.replace(/([\w-]+-XXXX)/g, (_, serial) => {
             const maskedSerial = serial.slice(0, -4) + `XXXX`;
@@ -529,11 +848,12 @@ class LicensingClient {
                 const output = await this.exec([`--acquire-floating`], true);
                 const tokenMatch = output.match(/with token:\s*"(?<token>[\w-]+)"/);
                 if (!tokenMatch || !tokenMatch.groups || !tokenMatch.groups['token']) {
-                    throw new Error(`Failed to acquire floating license lease: No token found in output.\n  ${output}`);
+                    throw new Error(`Failed to acquire floating license lease: No token found in output.\n  ${(0, utilities_1.SanitizeLogText)(output)}`);
                 }
                 const token = tokenMatch.groups['token'];
                 this.logger.CI_mask(token);
-                this.logger.info(output);
+                // the token is returned to the caller (and printed with --json); the log never shows it
+                this.logger.info((0, utilities_1.redactSensitiveLiterals)(output, [token]));
                 return token;
             }
             default: { // personal and professional license activation
@@ -604,6 +924,20 @@ class LicensingClient {
         }
         return licenses;
     }
+    /**
+     * The machine binding values the licensing client reports for this machine (Legacy.MachineBinding1, 2, ...).
+     * @returns The values, or an empty list when the client cannot report them.
+     */
+    async GetMachineBindings() {
+        try {
+            const context = await this.exec(['--showContext'], true);
+            return [...context.matchAll(/Legacy\.MachineBinding\d+[ \t]+(\S+)/g)].map(match => match[1]);
+        }
+        catch (error) {
+            this.logger.debug(`Failed to read the machine bindings: ${error}`);
+            return [];
+        }
+    }
     async activateLicense(licenseType, username, password, serial = undefined) {
         const args = [
             `--activate-ulf`,
@@ -619,13 +953,37 @@ class LicensingClient {
         if (licenseType === LicenseType.personal) {
             args.push(`--include-personal`);
         }
+        // keep redacting the account details in every later command's output, such as --showEntitlements
+        this.secrets.push(username, password, ...(serial ? [serial, serial.slice(0, -4) + 'XXXX'] : []));
         await this.exec(args);
         const activeLicenses = await this.GetActiveEntitlements();
         if (!activeLicenses.includes(licenseType)) {
             throw new Error(`Failed to activate license of type '${licenseType}'`);
         }
+        await this.linkLegacyLicenseFile();
         this.logger.info(`Successfully activated license of type '${licenseType}'`);
     }
+    /**
+     * Points Unity_v4.x.ulf or Unity_v5.x.ulf at the license the client actually wrote. Clients that ignore
+     * UNITY_COMMON_DIR, such as the macOS one, write Unity_lic.ulf to the regular folder instead of the patched one.
+     */
+    async linkLegacyLicenseFile() {
+        if (!this.legacyLicense) {
+            return;
+        }
+        const { linkPath, commonDirectory, patchedDirectory } = this.legacyLicense;
+        const candidates = [path.join(patchedDirectory, 'Unity_lic.ulf'), path.join(commonDirectory, 'Unity_lic.ulf')];
+        const licensePath = candidates.find(candidate => fs.existsSync(candidate));
+        if (!licensePath) {
+            this.logger.warn(`No Unity_lic.ulf was written to ${candidates.join(' or ')}`);
+            return;
+        }
+        await fs.promises.rm(linkPath, { force: true });
+        await fs.promises.symlink(licensePath, linkPath);
+        // the license version decides whether a 4.x or 5.x editor accepts the file
+        const licenseVersion = (await fs.promises.readFile(licensePath, 'utf-8')).match(/<LicenseVersion Value="([^"]+)"/)?.[1];
+        this.logger.info(`Linked ${linkPath} to ${licensePath} (license version ${licenseVersion ?? 'unknown'})`);
+    }
     async returnLicense(licenseType, token) {
         if (licenseType === LicenseType.floating) {
             if (!token || token.length === 0) {
@@ -651,4 +1009,327 @@ class LicensingClient {
     }
 }
 exports.LicensingClient = LicensingClient;
+/**
+ * Gets the license version a 4.x or 5.x editor in UNITY_EDITOR_PATH reads, or undefined for newer editors.
+ * @param editorPath The editor executable. Defaults to UNITY_EDITOR_PATH.
+ */
+function GetLegacyLicenseVersion(editorPath = process.env.UNITY_EDITOR_PATH) {
+    // anchored per path segment, so the match stays linear on any input
+    for (const segment of (editorPath ?? '').split(/[\\/ ]/)) {
+        const major = /^(\d{1,4})\.\d{1,4}\.\d/.exec(segment)?.[1];
+        if (major === undefined) {
+            continue;
+        }
+        switch (major) {
+            case '4':
+                return '4.x';
+            case '5':
+                return '5.x';
+            default:
+                return undefined;
+        }
+    }
+    return undefined;
+}
+/** How long one official CLI license command may run before it falls back. */
+const UNITY_CLI_LICENSE_TIMEOUT_MS = 3 * 60 * 1000;
+/**
+ * Activates a Unity license through the official Unity CLI first.
+ * Falls back to the Unity Licensing Client with the Unity ID email and password when the CLI fails,
+ * for example a personal license on a headless runner with no browser sign-in.
+ * 4.x and 5.x editors read their own license file, so they always use the Unity Licensing Client.
+ * @param options The activation options.
+ * @returns The floating license token, when one is known.
+ */
+async function ActivateLicense(options) {
+    const logger = logging_1.Logger.instance;
+    const legacyLicenseVersion = GetLegacyLicenseVersion();
+    if (legacyLicenseVersion) {
+        logger.info(`Unity ${legacyLicenseVersion} editors read their own license file, activating with the Unity Licensing Client...`);
+        await LicensingClient.StopBackgroundClients();
+        return await new LicensingClient(legacyLicenseVersion).Activate(options);
+    }
+    const licenseFile = options.licenseFile ?? process.env.UNITY_LICENSE;
+    if (licenseFile && licenseFile.trim().length > 0 &&
+        (options.licenseType === LicenseType.personal || options.licenseType === LicenseType.professional)) {
+        try {
+            if (await activateFromLicenseFile(licenseFile)) {
+                // lets a CI step tell whether it needs to store a fresh license
+                logger.CI_setOutput('license-source', 'license-file');
+                return undefined;
+            }
+        }
+        catch (error) {
+            logger.warn(`The license file could not be used, activating with the account instead.\n${error}`);
+        }
+    }
+    logger.CI_setOutput('license-source', 'account');
+    let cliError;
+    try {
+        const result = await activateWithUnityCli(options);
+        if (result.activated) {
+            await logLicenseBinding();
+            return result.token;
+        }
+        cliError = result.reason;
+    }
+    catch (error) {
+        cliError = error;
+    }
+    logger.warn(`Unity CLI license activation failed, falling back to the Unity Licensing Client.\n${cliError}`);
+    if (options.licenseType !== LicenseType.floating &&
+        !options.username && !process.env.UNITY_USERNAME_BASE64) {
+        throw new Error(`Unity CLI license activation failed, and no Unity ID email and password were given for the fallback.\n${cliError}`);
+    }
+    await LicensingClient.StopBackgroundClients();
+    const token = await new LicensingClient().Activate(options);
+    await logLicenseBinding();
+    return token;
+}
+/**
+ * Logs whether the license file now on disk names this machine's binding, which is what a cached copy is checked
+ * against on the next run. Only a yes or no is logged, never the binding or the file.
+ */
+async function logLicenseBinding() {
+    try {
+        const content = await fs.promises.readFile(GetLicenseFilePath(), 'utf-8');
+        const bindings = await new LicensingClient().GetMachineBindings();
+        if (bindings.length > 0) {
+            logging_1.Logger.instance.info(`The license file is bound to this machine's identity: ${bindings.some(binding => content.includes(binding)) ? 'yes' : 'no'}`);
+        }
+    }
+    catch (error) {
+        logging_1.Logger.instance.info(`Could not compare the license file with this machine's identity: ${error instanceof Error ? error.message : error}`);
+    }
+}
+/**
+ * Whether this is a GitHub-hosted macOS or Linux runner. Those report one machine identity to Unity across every job
+ * and repo, so returning a license there revokes it for all of them. Windows and self-hosted runners have their own.
+ */
+function IsSharedRunnerIdentity() {
+    return process.env.RUNNER_ENVIRONMENT === 'github-hosted' && (process.platform === 'darwin' || process.platform === 'linux');
+}
+/**
+ * Returns a Unity license through the official Unity CLI first, then the Unity Licensing Client.
+ * @param licenseType The type of license to return.
+ * @param token The floating license token from activation. A floating license with a token is returned by the Unity Licensing Client.
+ * @param when `auto` (the default) skips returning a personal or professional license on a shared runner identity.
+ */
+async function ReturnLicense(licenseType, token = undefined, when = 'auto') {
+    try {
+        if (when === 'never') {
+            logging_1.Logger.instance.info('Skipping the license return (--when never).');
+        }
+        else if (when === 'auto' && licenseType !== LicenseType.floating && IsSharedRunnerIdentity()) {
+            logging_1.Logger.instance.info('Skipping the license return: GitHub-hosted macOS and Linux runners share one machine identity, so a return would revoke the license for every job and repo on it. Use --when always to return anyway.');
+        }
+        else {
+            await returnLicense(licenseType, token);
+        }
+    }
+    finally {
+        // returning is the last licensing step of a job, so stop what the licensing calls left running in the background
+        await LicensingClient.StopBackgroundClients();
+        await stopUnityCliHelpers();
+    }
+}
+/**
+ * Stops background processes the official Unity CLI left running from its own folder, when this job's unity-cli
+ * commands started them. Only done in CI.
+ */
+async function stopUnityCliHelpers() {
+    const cliPath = process.env.UNITY_CLI_PATH;
+    if (process.env.CI !== 'true' || !cliPath) {
+        return;
+    }
+    const cliDirectory = path.dirname(cliPath);
+    const helpers = (await (0, process_tracker_1.FindOwnedProcesses)())
+        .filter(proc => (0, process_tracker_1.IsPathUnder)(proc.executablePath ?? proc.commandLine.split(' ')[0] ?? '', cliDirectory));
+    await Promise.all(helpers.map(helper => (0, utilities_1.KillProcess)(helper).catch(() => undefined)));
+}
+async function returnLicense(licenseType, token) {
+    const logger = logging_1.Logger.instance;
+    const legacyLicenseVersion = GetLegacyLicenseVersion();
+    if (legacyLicenseVersion || (licenseType === LicenseType.floating && token)) {
+        await LicensingClient.StopBackgroundClients();
+        await new LicensingClient(legacyLicenseVersion).Deactivate(licenseType, token);
+        return;
+    }
+    try {
+        const cli = await unity_cli_1.UnityCli.Get();
+        const { exitCode, envelope } = await cli.RunJson(['license', 'return', '--yes'], { timeoutMs: UNITY_CLI_LICENSE_TIMEOUT_MS });
+        if (exitCode === 0 && envelope?.success !== false && !(await isLicenseActive(cli))) {
+            logger.info(`Successfully returned license of type '${licenseType}'`);
+            return;
+        }
+        logger.warn(`unity license return exited with code ${exitCode}${formatEnvelopeErrors(envelope)}, falling back to the Unity Licensing Client...`);
+    }
+    catch (error) {
+        logger.warn(`Unity CLI license return failed, falling back to the Unity Licensing Client.\n${error}`);
+    }
+    if (licenseType === LicenseType.floating) {
+        throw new Error('The Unity CLI could not return the floating license. Pass the token from activation to return it with the Unity Licensing Client.');
+    }
+    await LicensingClient.StopBackgroundClients();
+    await new LicensingClient().Deactivate(licenseType);
+}
+/**
+ * Prints the license state from the official Unity CLI, then the Unity Licensing Client context.
+ */
+async function PrintLicenseContext() {
+    try {
+        const cli = await unity_cli_1.UnityCli.Get();
+        await cli.Run(['license', 'status'], { stream: true });
+    }
+    catch (error) {
+        logging_1.Logger.instance.warn(`Failed to read the Unity CLI license status: ${error}`);
+    }
+    await new LicensingClient(GetLegacyLicenseVersion()).Context();
+}
+/**
+ * Gets where Unity reads the machine's license file, Unity_lic.ulf.
+ */
+function GetLicenseFilePath() {
+    switch (process.platform) {
+        case 'win32':
+            return path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'Unity', 'Unity_lic.ulf');
+        case 'darwin':
+            return path.join('/Library', 'Application Support', 'Unity', 'Unity_lic.ulf');
+        default:
+            return path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), 'unity3d', 'Unity', 'Unity_lic.ulf');
+    }
+}
+/**
+ * Activates from a cached license file: `unity license activate --file` first, then by placing the file where Unity reads it.
+ * The file's contents are never logged.
+ * @param licenseFile A path to the license file, its raw XML, or base64.
+ * @returns True when a license is active afterwards.
+ */
+async function activateFromLicenseFile(licenseFile) {
+    const logger = logging_1.Logger.instance;
+    const trimmed = licenseFile.trim();
+    let content;
+    if (!trimmed.startsWith('<') && fs.existsSync(trimmed)) {
+        content = await fs.promises.readFile(trimmed, 'utf-8');
+    }
+    else if (trimmed.startsWith('<')) {
+        content = trimmed;
+    }
+    else if (/\.ulf$/i.test(trimmed) || /^([A-Za-z]:[\\/]|[\\/~.])/.test(trimmed)) {
+        // base64 of a license starts with "PD" or "PE", so this is a path to a file that is not there
+        throw new Error(`The license file was not found: ${trimmed}`);
+    }
+    else {
+        content = Buffer.from(trimmed, 'base64').toString('utf-8');
+    }
+    if (!content.includes('<License') || !content.includes('</root>')) {
+        throw new Error('The license file is not a Unity license (Unity_lic.ulf).');
+    }
+    // a license file is bound to the machine it was issued to: it still activates offline on another machine, but the
+    // licensing servers resolve no entitlements for it, and the editor fails later. Runner images change that identity.
+    const bindings = await new LicensingClient().GetMachineBindings();
+    if (bindings.length > 0 && !bindings.some(binding => content.includes(binding))) {
+        logger.warn('The cached license file was issued to a different machine identity, likely before a runner image change. Activating with the account instead.');
+        return false;
+    }
+    logger.info('Activating from the cached license file...');
+    const tempDirectory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'unity-license-'));
+    const tempFile = path.join(tempDirectory, 'Unity_lic.ulf');
+    try {
+        await fs.promises.writeFile(tempFile, content, { encoding: 'utf-8', mode: 0o600 });
+        try {
+            const cli = await unity_cli_1.UnityCli.Get();
+            const { exitCode, envelope } = await cli.RunJson(['license', 'activate', '--file', tempFile], { timeoutMs: UNITY_CLI_LICENSE_TIMEOUT_MS });
+            if (exitCode === 0 && envelope?.success !== false && await isLicenseActive(cli)) {
+                logger.info('Successfully activated from the cached license file with the Unity CLI');
+                return true;
+            }
+            logger.warn(`unity license activate --file exited with code ${exitCode}${formatEnvelopeErrors(envelope)}, placing the license file directly...`);
+        }
+        catch (error) {
+            logger.warn(`Unity CLI activation from the license file failed, placing the license file directly...\n${error}`);
+        }
+        const licensePath = GetLicenseFilePath();
+        await fs.promises.mkdir(path.dirname(licensePath), { recursive: true });
+        await fs.promises.copyFile(tempFile, licensePath);
+        const active = await new LicensingClient().GetActiveEntitlements();
+        if (active.length > 0) {
+            logger.info(`Successfully activated from the cached license file (${active.join(', ')})`);
+            return true;
+        }
+        return false;
+    }
+    finally {
+        await fs.promises.rm(tempDirectory, { recursive: true, force: true });
+    }
+}
+async function activateWithUnityCli(options) {
+    const args = ['license', 'activate'];
+    const redactLiterals = [];
+    switch (options.licenseType) {
+        case LicenseType.personal:
+            args.push('--personal', '--accept-eula');
+            break;
+        case LicenseType.professional:
+            if (!options.serial) {
+                return { activated: false, reason: 'A serial is required to activate a professional license with the Unity CLI.' };
+            }
+            args.push('--serial', options.serial.trim());
+            redactLiterals.push(options.serial.trim());
+            break;
+        case LicenseType.floating:
+            if (!options.servicesConfig) {
+                throw new Error('Services config path is required for floating license activation');
+            }
+            await new LicensingClient().setupServicesConfig(options.servicesConfig);
+            args.push('--floating');
+            break;
+    }
+    const cli = await unity_cli_1.UnityCli.Get();
+    logging_1.Logger.instance.info(`Activating a ${options.licenseType} license with the Unity CLI...`);
+    const { exitCode, envelope } = await cli.RunJson(args, { timeoutMs: UNITY_CLI_LICENSE_TIMEOUT_MS, redactLiterals });
+    if (exitCode !== 0 || envelope?.success === false) {
+        return { activated: false, reason: `unity license activate exited with code ${exitCode}${formatEnvelopeErrors(envelope)}` };
+    }
+    if (!(await isLicenseActive(cli))) {
+        return { activated: false, reason: 'unity license activate succeeded, but unity license status reports no active license' };
+    }
+    const token = findToken(envelope?.data);
+    if (token) {
+        logging_1.Logger.instance.CI_mask(token);
+    }
+    logging_1.Logger.instance.info(`Successfully activated license of type '${options.licenseType}' with the Unity CLI`);
+    return { activated: true, token };
+}
+/**
+ * Reads whether a license is active. Throws when the CLI gives no clear answer (a timeout or an unparseable result),
+ * so callers fall back instead of assuming the license is gone. LICENSE_NOT_ACTIVE exits 4 with active: false.
+ */
+async function isLicenseActive(cli) {
+    const { exitCode, envelope } = await cli.RunJson(['license', 'status'], { timeoutMs: UNITY_CLI_LICENSE_TIMEOUT_MS });
+    const active = envelope?.data?.active;
+    if ((exitCode === 0 || exitCode === 4) && typeof active === 'boolean') {
+        return active;
+    }
+    throw new Error(`unity license status exited with code ${exitCode} without a license state${formatEnvelopeErrors(envelope)}`);
+}
+function findToken(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item === 'string' && /token/i.test(key) && item.length > 0) {
+            return item;
+        }
+        const nested = findToken(item);
+        if (nested) {
+            return nested;
+        }
+    }
+    return undefined;
+}
+function formatEnvelopeErrors(envelope) {
+    const errors = envelope?.errors ?? [];
+    return errors.length > 0 ? `\n${errors.map(e => `  > ${e.code}: ${e.message}`).join('\n')}` : '';
+}
 //# sourceMappingURL=license-client.js.map