@ciphore/radiocli 0.2.4 → 0.2.5

package/dist/player/airplay-sender-patch.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { airPlaySenderRoot } from './airplay-sender-package.js';
 const require = createRequire(import.meta.url);
 const setupAp2DigestGuard = 'this.status === SETUP_AP2_1 && response.code === 401';
 const responseHeadersMarker = '    headers = response.headers';
@@ -58,6 +59,10 @@ const bufferedSocketDataHandler = `  var blob = Buffer.alloc(0)
     self.clearTimeout()
 
     blob = Buffer.concat([blob, Buffer.from(data)])
+    if (blob.length > 1024 * 1024) {
+      self.cleanup('invalid_response')
+      return
+    }
     while (blob.length > 0) {
       var endIndex = blob.indexOf('\\r\\n\\r\\n')
 
@@ -69,6 +74,10 @@ const bufferedSocketDataHandler = `  var blob = Buffer.alloc(0)
       var headers = blob.slice(0, endIndex).toString()
       var lengthMatch = /(?:^|\\r\\n)Content-Length:\\s*(\\d+)/i.exec(headers)
       var contentLength = lengthMatch ? parseInt(lengthMatch[1], 10) : 0
+      if (!Number.isSafeInteger(contentLength) || contentLength > 1024 * 1024) {
+        self.cleanup('invalid_response')
+        return
+      }
       var messageLength = endIndex + contentLength
 
       if (blob.length < messageLength) {
@@ -82,13 +91,15 @@ const bufferedSocketDataHandler = `  var blob = Buffer.alloc(0)
     }
   })`;
 let installed = false;
-export function installAirPlaySenderPatch(packageName = 'node-airtunes2') {
+export function installAirPlaySenderPatch(packageName = airPlaySenderRoot) {
     if (installed) {
         return true;
     }
     let rtspPath;
+    let devicePath;
     try {
         rtspPath = require.resolve(`${packageName}/lib/rtsp.js`);
+        devicePath = require.resolve(`${packageName}/lib/device_airtunes.js`);
     }
     catch {
         return false;
@@ -99,17 +110,18 @@ export function installAirPlaySenderPatch(packageName = 'node-airtunes2') {
         return false;
     }
     moduleLoader._extensions['.js'] = (module, filename) => {
-        if (filename !== rtspPath) {
+        if (filename !== rtspPath && filename !== devicePath) {
             originalLoader(module, filename);
             return;
         }
-        module._compile(patchAirTunesRtspSource(readFileSync(filename, 'utf8')), filename);
+        const source = readFileSync(filename, 'utf8');
+        module._compile(filename === rtspPath ? patchAirTunesRtspSource(source) : patchAirTunesDeviceSource(source), filename);
     };
     installed = true;
     return true;
 }
 export function patchAirTunesRtspSource(source) {
-    let patched = source;
+    let patched = patchQueuedControls(patchLegacyDigest(source));
     if (patched.includes(socketDataHandlerMarker) && !patched.includes('Buffer.concat([blob, Buffer.from(data)])')) {
         patched = patched.replace(socketDataHandlerMarker, bufferedSocketDataHandler);
     }
@@ -136,3 +148,89 @@ export function patchAirTunesRtspSource(source) {
 `;
     return patched.replace(processDataResponseMarker, `${setupAp2DigestRetry}${processDataResponseMarker}`);
 }
+/** A zero starting volume is intentional, including when a session starts muted. */
+export function patchAirTunesDeviceSource(source) {
+    return source.replaceAll('options.volume || 50', 'options.volume ?? 50').replaceAll('this.options.volume || 30', 'this.options.volume ?? 30');
+}
+function patchLegacyDigest(source) {
+    if (source.includes('// RadioCLI legacy Digest'))
+        return source;
+    return source.replace('  this.status = this.airplay2 ? PAIR_SETUP_1 : PAIR_PIN_SETUP_1\n  this.sendNextRequest()', `  if (!this.airplay2 && this.mode === 0 && (this.radioCliDigest || this.status === OPTIONS)) {
+    if (this.radioCliDigest) {
+      this.radioCliDigest.password = passcode
+      this.radioCliDigestTried = true
+      this.sendNextRequest(this.radioCliDigest)
+    }
+    return
+  }
+  this.status = this.airplay2 ? PAIR_SETUP_1 : PAIR_PIN_SETUP_1
+  this.sendNextRequest()`)
+        .replace("  var head = method + ' ' + uri + ' RTSP/1.0'", "  if (!this.airplay2 && this.mode === 0) di = di || this.radioCliDigest\n  var head = method + ' ' + uri + ' RTSP/1.0'")
+        .replace("    if (dimode == 'airplay2') {", "    if (dimode == 'airplay2' || (!this.airplay2 && this.mode === 0)) {")
+        .replace("      diResponse = md5(ha1 + ':' + di.nonce + ':' + ha2)", "      diResponse = (!this.airplay2 && this.mode === 0 ? md5norm : md5)(ha1 + ':' + di.nonce + ':' + ha2)")
+        .replace(processDataResponseMarker, `  // RadioCLI legacy Digest: keep password authentication separate from PIN pairing.
+  if (!this.airplay2 && this.mode === 0 && response.code === 401 &&
+      (this.status === OPTIONS || /^Digest\\s/i.test(headers['WWW-Authenticate'] || headers['www-authenticate'] || ''))) {
+    const auth = headers['WWW-Authenticate'] || headers['www-authenticate']
+    if (this.radioCliDigestTried || typeof auth !== 'string' || !/^Digest\\s/i.test(auth)) {
+      this.emit('pair_failed')
+      this.cleanup('bad_password')
+      return
+    }
+    const realm = parseAuthenticate(auth, 'realm')
+    const nonce = parseAuthenticate(auth, 'nonce')
+    if (!realm || !nonce || /[\\r\\n"]/.test(realm + nonce)) {
+      this.emit('pair_failed')
+      this.cleanup('bad_password')
+      return
+    }
+    this.radioCliDigest = {realm, nonce, username: 'iTunes', password: this.password}
+    if (!this.password) {
+      this.emit('need_password')
+      return
+    }
+    this.radioCliDigestTried = true
+    this.sendNextRequest(this.radioCliDigest)
+    return
+  }
+  if (response.code === 200) this.radioCliDigestTried = false
+${processDataResponseMarker}`);
+}
+/** The upstream sender silently drops controls while another RTSP request is in flight. */
+function patchQueuedControls(source) {
+    if (source.includes('this.radioCliPendingVolume'))
+        return source;
+    return source.replace(`Client.prototype.setVolume = function (volume, callback) {
+  if (this.status !== PLAYING)
+    return`, `Client.prototype.setVolume = function (volume, callback) {
+  if (this.status !== PLAYING) {
+    if (this.status !== CLOSED && this.status !== TEARDOWN) this.radioCliPendingVolume = [volume, callback]
+    return
+  }`)
+        .replace(`Client.prototype.setTrackInfo = function (name, artist, album, callback) {
+  if (this.status !== PLAYING)
+    return`, `Client.prototype.setTrackInfo = function (name, artist, album, callback) {
+  if (this.status !== PLAYING) {
+    if (this.status !== CLOSED && this.status !== TEARDOWN) this.radioCliPendingTrack = [name, artist, album, callback]
+    return
+  }`)
+        .replace(`  this.sendNextRequest()
+}
+
+Client.prototype.parseObject`, `  if (this.status === PLAYING && this.radioCliPendingVolume) {
+    const pending = this.radioCliPendingVolume
+    this.radioCliPendingVolume = null
+    this.setVolume(...pending)
+    return
+  }
+  if (this.status === PLAYING && this.radioCliPendingTrack) {
+    const pending = this.radioCliPendingTrack
+    this.radioCliPendingTrack = null
+    this.setTrackInfo(...pending)
+    return
+  }
+  this.sendNextRequest()
+}
+
+Client.prototype.parseObject`);
+}

package/dist/player/airplay-setup.js

@@ -0,0 +1,51 @@
+import { statSync } from 'node:fs';
+import { packageInstallCommand } from '../platform/packages.js';
+const airPlaySenderInstallGuidance = 'Reinstall RadioCLI with optional dependencies enabled (npm install -g @ciphore/radiocli --include=optional), then rerun radiocli doctor. Use the same installation method and prefix as the current install.';
+export function hasSystemdSystemManager() {
+    try {
+        return process.platform === 'linux' && statSync('/run/systemd/system').isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Only apt and Arch have verified Avahi package recipes here. */
+export function linuxAirPlaySetupPlan({ manager, elevation, hasCommand, systemd, serviceReady, existingCommands }) {
+    const commands = [];
+    const notes = ['Experimental Linux AirPlay is optional. Avahi supplies shared local-network discovery; enabling its system service affects the whole machine.'];
+    if (!hasCommand('ffmpeg') && !existingCommands.some(command => command.component === 'ffmpeg')) {
+        const command = manager ? packageInstallCommand(manager, 'ffmpeg', { elevation }) : null;
+        if (command)
+            commands.push({ ...command, component: null, label: 'AirPlay FFmpeg' });
+        else
+            notes.push('Install FFmpeg manually for AirPlay, then rerun radiocli setup --airplay.');
+    }
+    if (!hasCommand('avahi-browse') || !serviceReady && !hasCommand('avahi-daemon')) {
+        const recipe = manager === 'apt' ? ['apt-get', 'install', '-y', 'avahi-daemon', 'avahi-utils']
+            : manager === 'pacman' ? ['pacman', '-S', '--needed', '--noconfirm', 'avahi'] : null;
+        if (recipe)
+            commands.push(setupAction('Avahi discovery', recipe, elevation));
+        else
+            notes.push('Install Avahi daemon and avahi-browse with your distribution package manager; no verified automatic Avahi recipe is available for this manager.');
+    }
+    if (!serviceReady) {
+        if (systemd && hasCommand('systemctl') && (hasCommand('avahi-daemon') || manager === 'apt' || manager === 'pacman')) {
+            commands.push(setupAction('Enable and start shared Avahi service', ['systemctl', 'enable', '--now', 'avahi-daemon.service'], elevation));
+        }
+        else
+            notes.push('Start the Avahi daemon with your system service manager, then rerun radiocli doctor. RadioCLI will not guess or change this service configuration.');
+    }
+    return { commands, notes };
+}
+export function airPlaySetupVerification(readiness) {
+    const ready = readiness.ready && readiness.discoveryService === 'ready';
+    return [
+        ready ? 'AirPlay: experimental prerequisites ready. Select a receiver to verify playback.' : `AirPlay: Setup required. ${readiness.message}`,
+        ...(!readiness.senderLoaded ? [airPlaySenderInstallGuidance] : []),
+        ...(readiness.discoveryService === 'unverified' ? ['Avahi service readiness is unverified. Install busctl or verify the running daemon with your system administrator; receiver discovery remains available explicitly.'] : [])
+    ];
+}
+function setupAction(label, invocation, elevation) {
+    const [program, ...args] = elevation ? [elevation, ...invocation] : invocation;
+    return { component: null, label, program: program, args, display: [program, ...args].join(' ') };
+}

package/dist/player/airplay-worker.js

@@ -2,12 +2,13 @@ import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { airPlaySenderHealth } from './airplay-sender-health.js';
 import { installAirPlaySenderPatch } from './airplay-sender-patch.js';
+import { airPlaySenderRoot } from './airplay-sender-package.js';
+import { canRetryPlainHttp, ffmpegCertificateFailure, ffmpegInputArguments, ffmpegInputFailure } from './ffmpeg-input.js';
 import { parseWorkerMessage, decodeWorkerStart, maxWorkerMessageBytes, serializeWorkerMessage } from './airplay-worker-protocol.js';
 const require = createRequire(import.meta.url);
-// node-airtunes2 writes diagnostics with console.log; keep stdout reserved for JSON events.
-console.log = (...args) => {
-    process.stderr.write(`${args.map(String).join(' ')}\n`);
-};
+// The optional sender logs raw authentication exchanges, including receiver codes.
+// Only our bounded protocol events may leave this isolated process.
+console.log = console.info = console.debug = console.warn = console.error = () => undefined;
 const encodedStart = process.argv[2];
 if (!encodedStart) {
     emit({ type: 'error', message: 'Missing AirPlay worker start payload.' });
@@ -18,15 +19,21 @@ const start = decodeStartPayload(encodedStart);
 const airtunes = new AirTunes();
 let deviceKey = '';
 let ffmpeg = null;
+const decoders = new Set();
 let muted = start.muted;
 let volume = start.volume;
+let stationName = start.stationName;
 let retuning = false;
 let stopping = false;
+let finishStop;
 airtunes.on('device', (key, status) => {
+    if (stopping)
+        return;
     if (typeof key === 'string') {
         deviceKey = key;
     }
     if (status === 'ready') {
+        publishStation();
         emit({ type: 'ready' });
     }
     else if (status === 'playing' || status === 'pair_success') {
@@ -36,13 +43,18 @@ airtunes.on('device', (key, status) => {
         emit({ type: 'password-required' });
     }
     else if (status === 'stopped') {
-        emit({ type: 'stopped' });
+        fail('AirPlay receiver disconnected. Select the receiver again to reconnect.');
+    }
+    else if (status === 'pair_failed') {
+        fail('AirPlay receiver rejected the code or pairing request.');
     }
     else if (status === 'error') {
-        emit({ type: 'error', message: 'AirPlay receiver reported an error.' });
+        fail('AirPlay receiver reported an error.');
     }
 });
 airtunes.on('buffer', status => {
+    if (stopping)
+        return;
     const statusText = String(status);
     emit({ type: 'buffer', status: statusText });
     if (retuning && statusText === 'playing') {
@@ -50,9 +62,9 @@ airtunes.on('buffer', status => {
         emit({ type: 'retuned' });
     }
 });
-airtunes.on('error', error => {
-    emit({ type: 'error', message: error instanceof Error ? error.message : String(error) });
-});
+airtunes.on('error', () => fail('AirPlay sender failed. Select the receiver again to reconnect.'));
+airtunes.on('drain', () => { if (!stopping)
+    ffmpeg?.stdout.resume(); });
 const device = airtunes.add(start.device.host, {
     port: start.device.port,
     volume: muted ? 0 : volume,
@@ -85,7 +97,13 @@ process.stdin.on('data', chunk => {
 });
 process.once('SIGTERM', () => stop(0));
 process.once('SIGINT', () => stop(0));
+process.once('SIGHUP', () => stop(0));
+process.stdin.once('end', () => stop(0));
+process.once('uncaughtException', () => fail('AirPlay sender failed.'));
+process.once('unhandledRejection', () => fail('AirPlay sender failed.'));
 function handleCommand(command) {
+    if (stopping)
+        return;
     if (command.type === 'stop') {
         stop(0);
     }
@@ -99,30 +117,26 @@ function handleCommand(command) {
     }
     else if (command.type === 'retune') {
         retuning = true;
+        stationName = command.stationName;
         airtunes.reset();
         startFfmpeg(command.streamUrl);
+        publishStation();
     }
     else if (command.type === 'passcode') {
         device.setPasscode?.(command.code);
     }
 }
-function startFfmpeg(streamUrl) {
+function startFfmpeg(streamUrl, plainHttp = false) {
+    if (stopping)
+        return;
     const previous = ffmpeg;
     const child = spawn(start.ffmpegPath, [
         '-hide_banner',
         '-loglevel',
         'error',
-        // Recover from transient source drops without tearing down the AirPlay session.
-        // These are input options and must precede -i. -reconnect_streamed is essential for
-        // non-seekable radio; with no retry cap ffmpeg keeps trying until the station returns.
-        '-reconnect',
-        '1',
-        '-reconnect_on_network_error',
-        '1',
-        '-reconnect_streamed',
-        '1',
-        '-reconnect_delay_max',
-        '2',
+        // Reconnect only network inputs, retaining the receiver session across
+        // transient source drops without breaking local file playback.
+        ...ffmpegInputArguments(streamUrl, { plainHttp, reconnect: true }),
         '-i',
         streamUrl,
         '-f',
@@ -136,33 +150,44 @@ function startFfmpeg(streamUrl) {
         stdio: ['ignore', 'pipe', 'pipe']
     });
     ffmpeg = child;
-    if (previous && !previous.killed) {
-        previous.kill('SIGTERM');
-    }
+    decoders.add(child);
+    child.once('close', () => { decoders.delete(child); finishStop?.(); });
+    if (previous)
+        stopDecoder(previous);
+    let pcmStarted = false;
+    let diagnostic = '';
     child.stdout.on('data', chunk => {
         if (ffmpeg === child && !stopping) {
-            airtunes.write(chunk);
+            pcmStarted ||= chunk.length > 0;
+            if (!airtunes.write(chunk))
+                child.stdout.pause();
         }
     });
+    // Inspect only a bounded tail; never forward stream URLs or credentials.
     child.stderr.on('data', chunk => {
-        if (ffmpeg === child) {
-            process.stderr.write(chunk);
-        }
+        diagnostic = (diagnostic + String(chunk)).slice(-8192);
+        const failure = ffmpegInputFailure(diagnostic) ?? ffmpegCertificateFailure(diagnostic);
+        if (failure && ffmpeg === child && !stopping)
+            fail(failure);
     });
-    child.once('error', error => {
+    child.stderr.resume();
+    child.once('error', () => {
         if (ffmpeg !== child || stopping) {
             return;
         }
-        emit({ type: 'error', message: error.message });
-        stop(1);
+        fail('FFmpeg could not start for AirPlay playback. Run radiocli doctor.');
     });
-    child.once('exit', code => {
+    child.once('close', (code, signal) => {
         if (ffmpeg !== child || stopping) {
             return;
         }
+        if (!plainHttp && !signal && !pcmStarted && canRetryPlainHttp(streamUrl, diagnostic)) {
+            startFfmpeg(streamUrl, true);
+            return;
+        }
         ffmpeg = null;
         if (code !== 0) {
-            emit({ type: 'error', message: `ffmpeg exited with code ${code}` });
+            emit({ type: 'error', message: ffmpegInputFailure(diagnostic) ?? `ffmpeg exited with code ${code}` });
         }
         stop(code ?? 0);
     });
@@ -172,6 +197,24 @@ function setAirPlayVolume(nextVolume) {
         airtunes.setVolume(deviceKey, nextVolume);
     }
 }
+function publishStation() {
+    if (deviceKey)
+        airtunes.setTrackInfo(deviceKey, stationName, 'RadioCLI', 'Live radio');
+}
+function fail(message) {
+    if (stopping)
+        return;
+    emit({ type: 'error', message });
+    stop(1);
+}
+function stopDecoder(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.kill('SIGTERM');
+    const force = setTimeout(() => child.kill('SIGKILL'), 500);
+    force.unref();
+    child.once('close', () => clearTimeout(force));
+}
 function emit(event) {
     process.stdout.write(serializeWorkerMessage(event));
 }
@@ -183,7 +226,7 @@ function loadAirTunesSender() {
     }
     installAirPlaySenderPatch();
     try {
-        return require('node-airtunes2');
+        return require(airPlaySenderRoot);
     }
     catch {
         emit({ type: 'error', message: 'AirPlay sender bridge could not be loaded.' });
@@ -204,17 +247,30 @@ function stop(code) {
         return;
     }
     stopping = true;
-    if (ffmpeg && !ffmpeg.killed) {
-        ffmpeg.kill('SIGTERM');
-    }
+    process.exitCode = code;
+    for (const child of decoders)
+        stopDecoder(child);
     ffmpeg = null;
-    const watchdog = setTimeout(() => process.exit(code), 1500);
-    watchdog.unref();
-    airtunes.stopAll(() => {
+    let senderStopped = false;
+    const watchdog = setTimeout(() => {
+        for (const child of decoders)
+            child.kill('SIGKILL');
+        process.exit(code);
+    }, 1500);
+    finishStop = () => {
+        if (!senderStopped || decoders.size)
+            return;
         clearTimeout(watchdog);
         emit({ type: 'stopped' });
         process.exit(code);
-    });
+    };
+    try {
+        airtunes.stopAll(() => { senderStopped = true; finishStop?.(); });
+    }
+    catch {
+        senderStopped = true;
+        finishStop();
+    }
 }
 function clampVolume(nextVolume) {
     return Math.min(100, Math.max(0, Math.round(nextVolume)));

package/dist/player/backend-install.js

@@ -1,19 +1,22 @@
 import { ffplayInstallCommand, mpvInstallCommand } from '../platform/packages.js';
-import { identifyPlatform, nativeAdapters, readLinuxOsRelease } from '../platform/runtime.js';
+import { readLinuxOsRelease } from '../platform/runtime.js';
 import { commandExists } from '../platform/executables.js';
+import { airPlayPolicy } from './airplay-policy.js';
+export { isAirPlayPlatformSupported } from './airplay-policy.js';
 import { airPlaySenderHealth } from './airplay-sender-health.js';
 export const ffplayLimitedControlsMessage = 'ffplay fallback has limited controls. Install mpv for pause, mute, volume, and media keys.';
 export const vlcLimitedControlsMessage = 'VLC fallback has limited controls. Install mpv for pause, mute, volume, and media keys.';
-export const airPlayMacOSOnlyMessage = 'AirPlay output is available only on macOS and is not supported on this operating system.';
-export function isAirPlayPlatformSupported(platform = process.platform) {
-    return nativeAdapters(identifyPlatform({ platform })).airPlay;
+export function airPlayLocalDeviceLabel(platform = process.platform) {
+    return platform === 'darwin' ? 'this Mac' : 'this device';
 }
-export function detectPlaybackBackends({ platform = process.platform, hasCommand = commandExists, hasAirPlaySender = hasAirPlaySenderPackage } = {}) {
+export function detectPlaybackBackends({ platform = process.platform, settings, env, release, hasCommand = commandExists, hasAirPlaySender = hasAirPlaySenderPackage } = {}) {
     const backends = ['mpv', 'ffplay'].filter(hasCommand);
     if (hasCommand('cvlc') || hasCommand('vlc')) {
         backends.push('vlc');
     }
-    if (isAirPlayPlatformSupported(platform) && hasCommand('ffmpeg') && hasCommand('dns-sd') && hasAirPlaySender()) {
+    // This is only a cheap candidate check. Discovery and explicit diagnostics
+    // separately verify the daemon and isolated native sender loadability.
+    if (airPlayPolicy(settings, { platform, env, release }).enabled && hasCommand('ffmpeg') && hasCommand(platform === 'linux' ? 'avahi-browse' : 'dns-sd') && hasAirPlaySender()) {
         backends.push('airplay');
     }
     return backends;

package/dist/player/ffmpeg-input.js

@@ -0,0 +1,37 @@
+// FFmpeg releases in circulation do not propagate tls_verify to resources
+// opened by HLS/DASH/IMF demuxers. Restrict network fallbacks to self-contained
+// media; mpv supplies verified networking for multi-resource inputs.
+const mediaFormats = 'aac,ac3,aiff,amr,ape,asf,au,avi,caf,eac3,flac,flv,live_flv,matroska,webm,mov,mp4,m4a,3gp,3g2,mj2,mp3,mpeg,mpegts,nut,ogg,w64,wav,wv';
+export function ffmpegInputArguments(target, options = {}) {
+    const network = /^https?:\/\//i.test(target);
+    const plainHttp = options.plainHttp && /^http:\/\//i.test(target);
+    if (!network)
+        return ['-protocol_whitelist', 'file,crypto,data'];
+    const args = ['-format_whitelist', mediaFormats];
+    if (plainHttp)
+        args.push('-protocol_blacklist', 'https,tls');
+    else
+        args.push('-tls_verify', '1');
+    if (options.reconnect)
+        args.push('-reconnect', '1', '-reconnect_on_network_error', '1', '-reconnect_streamed', '1', '-reconnect_delay_max', '2');
+    return args;
+}
+/** First verify any HTTP -> HTTPS redirect. FFmpeg rejects the unused TLS
+ * option on ordinary HTTP media; retry only that exact failure, with TLS
+ * protocols blocked even if the server changes its redirect. */
+export function canRetryPlainHttp(target, diagnostic) {
+    return /^http:\/\//i.test(target) && /(?:^|[\r\n])Option tls_verify not found\.?\s*(?:[\r\n]|$)/.test(diagnostic);
+}
+export function ffmpegInputFailure(diagnostic) {
+    if (/not on whitelist|on blacklist/i.test(diagnostic))
+        return 'This input is unavailable with FFmpeg. Use a direct audio stream, or select mpv for local playback of HLS/DASH and other network playlists.';
+    return undefined;
+}
+export function ffmpegCertificateFailure(diagnostic) {
+    // Backends use different TLS libraries. Generic handshake/I/O errors can be
+    // transient; only specific certificate failures are permanent here.
+    if (/certificate (?:verify|verification) failed|peer certificate failed verification|certificate's owner does not match hostname|unable to verify peer certificate|invalid certificate chain|SNI or certificate check failed|Creating security context failed \(0x800903(?:25|27|28)\)/i.test(diagnostic)) {
+        return 'The stream certificate could not be verified. Choose a valid HTTPS stream or repair the native certificate configuration.';
+    }
+    return undefined;
+}