@metaplay/metaplay-auth 1.9.1 → 1.9.3-next.878

package/index.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { Command } from 'commander'
 import Docker from 'dockerode'
-import { writeFile } from 'fs/promises'
-import { exit } from 'process'
+import { writeFile } from 'node:fs/promises'
+import { exit } from 'node:process'
 import * as semver from 'semver'
 
 import { KubeConfig } from '@kubernetes/client-node'
@@ -13,7 +13,7 @@ import { portalBaseUrl, setPortalBaseUrl } from './src/config.js'
 import { checkGameServerDeployment, debugGameServer } from './src/deployment.js'
 import { logger, setLogLevel } from './src/logging.js'
 import { TargetEnvironment } from './src/targetenvironment.js'
-import { isValidFQDN, removeTrailingSlash, fetchHelmChartVersions, resolveBestMatchingVersion, executeHelmCommand, getGameServerHelmRelease } from './src/utils.js'
+import { isValidFQDN, removeTrailingSlash, fetchHelmChartVersions, resolveBestMatchingVersion, checkHelmVersion, executeHelmCommand, getGameServerHelmRelease } from './src/utils.js'
 import { PACKAGE_VERSION } from './src/version.js'
 
 /** Stack API base url override, specified with the '--stack-api' global flag. */
@@ -250,6 +250,10 @@ program
       setLogLevel(10)
     }
 
+    // Show a deprecation warning.
+    console.warn('Warning: The metaplay-auth CLI is deprecated and will only receive critical updates.')
+    console.warn('         Please upgrade to Metaplay SDK release 32 or newer and the new Metaplay CLI (https://github.com/metaplay/cli).')
+
     // Store the portal base URL for accessing globally
     const overridePortalUrl: string | undefined = opts.portalBaseUrl ?? process.env.AUTHCLI_PORTAL_BASEURL
     if (overridePortalUrl) {
@@ -275,29 +279,34 @@ program
   .description('login to the Metaplay cloud using a machine account (using credentials in environment variable METAPLAY_CREDENTIALS)')
   .option('--dev-credentials', 'machine user credentials to use, only for dev purposes, use METAPLAY_CREDENTIALS env variable for better safety!')
   .action(async (options) => {
-    // Get credentials from command line or from METAPLAY_CREDENTIALS environment variable
-    let credentials: string
-    if (options.devCredentials) {
-      credentials = options.devCredentials
-    } else {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      credentials = process.env.METAPLAY_CREDENTIALS!
-      if (!credentials || credentials === '') {
-        throw new Error('Unable to find the credentials, the environment variable METAPLAY_CREDENTIALS is not defined!')
+    try {
+      // Get credentials from command line or from METAPLAY_CREDENTIALS environment variable
+      let credentials: string
+      if (options.devCredentials) {
+        credentials = options.devCredentials
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        credentials = process.env.METAPLAY_CREDENTIALS!
+        if (!credentials || credentials === '') {
+          throw new Error('Unable to find the credentials, the environment variable METAPLAY_CREDENTIALS is not defined!')
+        }
       }
-    }
 
-    // Parse the clientId and clientSecret from the credentials (separate by a '+' character)
-    // \note We can't be certain that the secret does not contain pluses so split at the first occurrence
-    const splitOffset = credentials.indexOf('+')
-    if (splitOffset === -1) {
-      throw new Error('Invalid format for credentials, you should copy-paste the value from the developer portal verbatim')
-    }
-    const clientId = credentials.substring(0, splitOffset)
-    const clientSecret = credentials.substring(splitOffset + 1)
+      // Parse the clientId and clientSecret from the credentials (separate by a '+' character)
+      // \note We can't be certain that the secret does not contain pluses so split at the first occurrence
+      const splitOffset = credentials.indexOf('+')
+      if (splitOffset === -1) {
+        throw new Error('Invalid format for credentials, you should copy-paste the value from the developer portal verbatim')
+      }
+      const clientId = credentials.substring(0, splitOffset)
+      const clientSecret = credentials.substring(splitOffset + 1)
 
-    // Login with machine user and save the tokens
-    await machineLoginAndSaveTokens(clientId, clientSecret)
+      // Login with machine user and save the tokens
+      await machineLoginAndSaveTokens(clientId, clientSecret)
+    } catch (error) {
+      console.error(`Error during machine login: ${error instanceof Error ? error.message : String(error)}`)
+      exit(1)
+    }
   })
 
 program
@@ -716,7 +725,10 @@ program
             })
           } catch (error) {
             const errMessage = error instanceof Error ? error.message : String(error)
-            throw new Error(`Failed to fetch docker image ${imageName} from target environment registry: ${errMessage}`)
+            throw new Error(
+              `Failed to fetch docker image ${imageName} from target environment registry: ${errMessage}`,
+              { cause: error }
+            )
           }
 
           // Resolve the labels
@@ -726,7 +738,10 @@ program
             imageLabels = (await localDockerImage.inspect()).Config.Labels || {}
           } catch (error) {
             const errMessage = error instanceof Error ? error.message : String(error)
-            throw new Error(`Failed to resolve docker image metadata from pulled image ${imageName}: ${errMessage}`)
+            throw new Error(
+              `Failed to resolve docker image metadata from pulled image ${imageName}: ${errMessage}`,
+              { cause: error }
+            )
           }
         }
 
@@ -763,7 +778,10 @@ program
           try {
             helmChartRange = new semver.Range(helmChartVersionSpec)
           } catch (error) {
-            throw new Error(`Helm chart version '${helmChartVersionSpec}' is not a valid SemVer range: ${String(error)}`)
+            throw new Error(
+              `Helm chart version '${helmChartVersionSpec}' is not a valid SemVer range: ${String(error)}`,
+              { cause: error }
+            )
           }
         }
 
@@ -783,6 +801,9 @@ program
         }
         logger.debug('Resolved Helm chart version: ', resolvedHelmChartVersion)
 
+        // Check that the Helm version is compatible
+        await checkHelmVersion()
+
         // Fetch kubeconfig and write it to a temporary file
         // \todo allow passing a custom kubeconfig file?
         const kubeconfigPayload = await targetEnv.getKubeConfigWithEmbeddedCredentials()
@@ -866,6 +887,9 @@ program
           exit(0)
         }
 
+        // Check that the Helm version is compatible
+        await checkHelmVersion()
+
         // Construct Helm invocation.
         const deploymentName = gameServerHelmRelease.name
         const helmArgs = ['uninstall', '--wait'] // \note waits for resources to be deleted before returning
@@ -915,7 +939,7 @@ program
           kubeconfig.loadFromString(kubeconfigPayload)
         } catch (error) {
           const errMessage = error instanceof Error ? error.message : String(error)
-          throw new Error(`Failed to load or validate kubeconfig. ${errMessage}`)
+          throw new Error(`Failed to load or validate kubeconfig. ${errMessage}`, { cause: error })
         }
 
         // Resolve Helm deployment

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metaplay/metaplay-auth",
   "description": "Utility CLI for authenticating with the Metaplay Auth and making authenticated calls to infrastructure endpoints.",
-  "version": "1.9.1",
+  "version": "1.9.3-next.878",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://metaplay.io",
@@ -17,29 +17,28 @@
   },
   "devDependencies": {
     "@metaplay/eslint-config": "workspace:*",
-    "@types/dockerode": "3.3.39",
-    "@types/express": "5.0.2",
-    "@types/js-yaml": "4.0.9",
-    "@types/jsonwebtoken": "9.0.9",
+    "@types/dockerode": "3.3.44",
+    "@types/express": "5.0.3",
+    "@types/js-yaml": "^4.0.9",
+    "@types/jsonwebtoken": "9.0.10",
     "@types/jwk-to-pem": "2.0.3",
-    "@types/node": "22.15.29",
-    "@types/semver": "7.7.0",
-    "esbuild": "0.25.5",
-    "tsx": "4.19.4",
-    "typescript": "5.8.3",
-    "vitest": "3.1.3",
-    "@aws-sdk/client-ecr": "3.810.0",
-    "@kubernetes/client-node": "1.0.0-rc7",
-    "@ory/client": "1.20.11",
-    "commander": "12.1.0",
-    "dockerode": "4.0.6",
-    "h3": "1.15.3",
-    "js-yaml": "4.1.0",
+    "@types/node": "24.5.2",
+    "@types/semver": "7.7.1",
+    "esbuild": "0.25.10",
+    "tsx": "4.20.5",
+    "typescript": "5.9.2",
+    "vitest": "3.2.4",
+    "@aws-sdk/client-ecr": "3.891.0",
+    "@kubernetes/client-node": "1.3.0",
+    "commander": "14.0.1",
+    "dockerode": "4.0.8",
+    "h3": "1.15.4",
+    "js-yaml": "^4.1.0",
     "jsonwebtoken": "9.0.2",
     "jwk-to-pem": "2.0.7",
     "open": "8.4.2",
     "semver": "7.7.2",
     "tslog": "4.9.3",
-    "eslint": "9.31.0"
+    "eslint": "9.35.0"
   }
 }

package/src/auth.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/prefer-nullish-coalescing */
 
 import { toNodeListener, createApp, defineEventHandler, getQuery, sendError } from 'h3'
 import jwt, { JwtPayload } from 'jsonwebtoken'
@@ -6,8 +7,6 @@ import { randomBytes, createHash } from 'node:crypto'
 import { createServer } from 'node:http'
 import open from 'open'
 
-import { Configuration, OidcApi } from '@ory/client'
-
 import { portalBaseUrl } from './config.js'
 import { logger } from './logging.js'
 import { setSecret, getSecret, removeSecret } from './secret_store.js'
@@ -23,11 +22,6 @@ const clientId = 'c16ea663-ced3-46c6-8f85-38c9681fe1f0'
 const baseURL = 'https://auth.metaplay.dev'
 const authorizationEndpoint = `${baseURL}/oauth2/auth`
 const tokenEndpoint = `${baseURL}/oauth2/token`
-const oidcApi = new OidcApi(
-  new Configuration({
-    basePath: baseURL,
-  })
-)
 
 /**
  * A helper function which generates a code verifier and challenge for exchanging code from Ory server.
@@ -45,16 +39,9 @@ function generateCodeVerifierAndChallenge(): { verifier: string; challenge: stri
  * @returns An object containing the user's info.
  */
 export async function getUserinfo(token: string): Promise<any> {
-  logger.debug('Trying to find OIDC well-known endpoints...')
-  const oidcRes = await oidcApi.discoverOidcConfiguration()
-
-  const userinfoEndpoint = oidcRes.data?.userinfo_endpoint
-  if (!userinfoEndpoint) {
-    throw new Error('No userinfo endpoint found in OIDC configuration')
-  }
-  logger.debug(`Found userinfo endpoint: ${userinfoEndpoint}`)
-
-  const userinfoRes = await fetch(userinfoEndpoint, {
+  // To relieve pressure on Ory endpoints, get the userinfo directly from portal,
+  // instead of discovering OIDC endpoints from Ory first. Portal is where Ory would redirect the request anyway.
+  const userinfoRes = await fetch(`${portalBaseUrl}/api/external/userinfo`, {
     headers: {
       Authorization: `Bearer ${token}`,
     },
@@ -201,8 +188,30 @@ export async function machineLoginAndSaveTokens(clientId: string, clientSecret:
     body: params.toString(),
   })
 
-  // Return type checked manually by Teemu on 2024-3-7.
-  const tokens = (await res.json()) as { access_token: string; token_type: string; expires_in: number; scope: string }
+  // Improved error handling for response
+  let tokens: { access_token: string; token_type: string; expires_in: number; scope: string }
+  if (!res.ok) {
+    let message: string | undefined
+    try {
+      const errorBody: any = await res.json()
+      message = errorBody && (errorBody.error_description || errorBody.error || errorBody.message)
+    } catch (_error) {
+      try {
+        message = await res.text()
+      } catch (_error) {
+        message = undefined
+      }
+    }
+    throw new Error(`Machine login failed: ${message || `HTTP ${res.status}`}`)
+  }
+  try {
+    tokens = (await res.json()) as { access_token: string; token_type: string; expires_in: number; scope: string }
+  } catch (error) {
+    throw new Error(
+      "Invalid response from authentication server. Please check your network connection and credentials and try again.",
+      { cause: error }
+    )
+  }
 
   logger.debug('Received machine authentication tokens, saving them for future use...')
 
@@ -214,7 +223,29 @@ export async function machineLoginAndSaveTokens(clientId: string, clientSecret:
     },
   })
 
-  const userInfo = (await userInfoResponse.json()) as { given_name: string; family_name: string }
+  let userInfo: { given_name: string; family_name: string }
+  if (!userInfoResponse.ok) {
+    let message: string | undefined
+    try {
+      const errorBody: any = await userInfoResponse.json()
+      message = errorBody && (errorBody.error_description || errorBody.error || errorBody.message)
+    } catch (_error) {
+      try {
+        message = await userInfoResponse.text()
+      } catch (_error) {
+        message = undefined
+      }
+    }
+    throw new Error(`Failed to fetch user info: ${message || `HTTP ${userInfoResponse.status}`}`)
+  }
+  try {
+    userInfo = (await userInfoResponse.json()) as { given_name: string; family_name: string }
+  } catch (error) {
+    throw new Error(
+      "Invalid response from user info endpoint. Please check your network connection and try again.",
+      { cause: error }
+    )
+  }
 
   console.log(
     `You are now logged in with machine user ${userInfo.given_name} ${userInfo.family_name} (clientId=${clientId}) and can execute the other commands.`
@@ -267,7 +298,6 @@ export async function extendCurrentSession(): Promise<void> {
 async function extendCurrentSessionWithRefreshToken(
   refreshToken: string
 ): Promise<{ id_token: string; access_token: string; refresh_token: string }> {
-  // TODO: similar to the todo task in getTokensWithAuthorizationCode, http request can be handled by ory/client.
   const params = new URLSearchParams({
     grant_type: 'refresh_token',
     refresh_token: refreshToken,
@@ -292,9 +322,12 @@ async function extendCurrentSessionWithRefreshToken(
     logger.error(`Failed to refresh tokens via endpoint ${tokenEndpoint}`)
     logger.error('Fetch error details:', error)
     if (error.cause?.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
-      throw new Error(`Failed to refresh tokens: SSL certificate validation failed for ${tokenEndpoint}. Is someone trying to tamper with your internet connection?`)
+      throw new Error(
+        `Failed to refresh tokens: SSL certificate validation failed for ${tokenEndpoint}. Is someone trying to tamper with your internet connection?`,
+        { cause: error }
+      )
     }
-    throw new Error(`Failed to refresh tokens via ${tokenEndpoint}: ${error}`)
+    throw new Error(`Failed to refresh tokens via ${tokenEndpoint}: ${error}`, { cause: error })
   }
 
   // Check if the response is OK
@@ -323,14 +356,12 @@ async function extendCurrentSessionWithRefreshToken(
  * @param code
  * @returns
  */
-
 async function getTokensWithAuthorizationCode(
   state: string,
   redirectUri: string,
   verifier: string,
   code: string
 ): Promise<{ id_token: string; access_token: string; refresh_token: string }> {
-  // TODO: the authorization code exchange flow might be better to be handled by ory/client, could check if there's any useful tools there.
   try {
     const response = await fetch(tokenEndpoint, {
       method: 'POST',
@@ -364,7 +395,7 @@ export async function loadTokens(): Promise<TokenSet> {
     return tokens
   } catch (error) {
     if (error instanceof Error) {
-      throw new Error(`Error loading tokens: ${error.message}`)
+      throw new Error(`Error loading tokens: ${error.message}`, { cause: error })
     }
 
     throw error
@@ -393,7 +424,7 @@ export async function saveTokens(tokens: Record<string, string>): Promise<void>
     showTokenInfo(tokens.access_token)
   } catch (error) {
     if (error instanceof Error) {
-      throw new Error(`Failed to save tokens: ${error.message}`)
+      throw new Error(`Failed to save tokens: ${error.message}`, { cause: error })
     }
 
     throw error
@@ -409,7 +440,7 @@ export async function removeTokens(): Promise<void> {
     logger.debug('Removed tokens.')
   } catch (error) {
     if (error instanceof Error) {
-      throw new Error(`Error removing tokens: ${error.message}`)
+      throw new Error(`Error removing tokens: ${error.message}`, { cause: error })
     }
 
     throw error

package/src/buildCommand.ts

@@ -1,7 +1,7 @@
 import { Command } from 'commander'
-import { readFileSync, existsSync } from 'fs'
-import path from 'path'
-import { exit } from 'process'
+import { readFileSync, existsSync } from 'node:fs'
+import path from 'node:path'
+import { exit } from 'node:process'
 import * as semver from 'semver'
 
 import { pathJoin, executeCommand, ExecuteCommandResult } from './utils.js'

package/src/deployment.ts

@@ -1,10 +1,10 @@
-import { unlink, writeFile } from 'fs/promises'
-import os from 'os'
-import path from 'path'
-import { exit } from 'process'
+import { unlink, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { exit } from 'node:process'
 import { EnvironmentDetails, TargetEnvironment } from 'targetenvironment.js'
-import { promises as dns } from 'dns'
-import tls from 'tls'
+import { promises as dns } from 'node:dns'
+import tls from 'node:tls'
 
 import {
   KubeConfig,
@@ -48,7 +48,7 @@ async function fetchGameServerPods(k8sApi: CoreV1Api, namespace: string): Promis
   } catch (error) {
     // \todo Better error handling ..
     console.error('Failed to fetch pods from Kubernetes:', error)
-    throw new Error('Failed to fetch pods from Kubernetes')
+    throw new Error('Failed to fetch pods from Kubernetes', { cause: error })
   }
 }
 
@@ -337,7 +337,7 @@ async function fetchPodLogs(k8sApi: CoreV1Api, pod: V1Pod): Promise<string> {
   } catch (error) {
     // \todo Better error handling ..
     console.log('Failed to fetch pod logs from Kubernetes:', error)
-    throw new Error('Failed to fetch pod logs from Kubernetes')
+    throw new Error('Failed to fetch pod logs from Kubernetes', { cause: error })
   }
 }
 
@@ -363,7 +363,9 @@ async function checkGameServerPod(
 }
 
 async function delay(ms: number): Promise<void> {
-  await new Promise<void>((resolve) => setTimeout(resolve, ms))
+  await new Promise<void>((resolve) => {
+    setTimeout(resolve, ms)
+  })
 }
 
 function anyPodsInPhase(podStatuses: GameServerPodStatus[], phase: GameServerPodPhase): boolean {
@@ -457,7 +459,7 @@ async function waitForDomainResolution(hostname: string): Promise<void> {
       return
     } catch (err) {
       if (Date.now() > timeoutAt) {
-        throw new Error(`Could not resolve domain ${hostname} before timeout.`)
+        throw new Error(`Could not resolve domain ${hostname} before timeout.`, { cause: err })
       }
 
       if (err instanceof Error && (err as NodeJS.ErrnoException).code === 'ENOTFOUND') {
@@ -587,6 +589,7 @@ export async function debugGameServer(targetEnv: TargetEnvironment, targetPodNam
       if (!metadata?.name) {
         throw new Error('Unable to resolve name for the Kubernetes pod!')
       }
+      // eslint-disable-next-line no-param-reassign
       targetPodName = metadata.name
     } else {
       const podNames = gameServerPods.map((pod) => pod.metadata?.name).join(', ')

package/src/secret_store.ts

@@ -1,7 +1,7 @@
-import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'crypto'
-import { promises as fs } from 'fs'
-import { homedir } from 'os'
-import { join } from 'path'
+import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 
 import { logger } from './logging.js'
 
@@ -36,7 +36,7 @@ async function loadSecrets(): Promise<Secrets> {
       return {}
     }
     if (password.length === 0) {
-      throw new Error('The file is encrypted. Please set the METAPLAY_AUTH_PASSWORD environment variable.')
+      throw new Error('The file is encrypted. Please set the METAPLAY_AUTH_PASSWORD environment variable.', { cause: error })
     }
      
     throw error

package/src/stackapi.ts

@@ -4,7 +4,7 @@ export class StackAPI {
   private readonly stackApiBaseUrl: string
 
   constructor(accessToken: string, stackApiBaseUrl: string | undefined) {
-    if (accessToken == null) {
+    if (!accessToken) {
       throw new Error('accessToken must be provided')
     }
 

package/src/targetenvironment.ts

@@ -133,9 +133,9 @@ export class TargetEnvironment {
     } catch (error: any) {
       logger.error(`Failed to fetch ${method} ${url}:`, error)
       if (error.cause?.code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
-        throw new Error(`Failed to to fetch ${url}: SSL certificate validation failed. Is someone trying to tamper with your internet connection?`)
+        throw new Error(`Failed to to fetch ${url}: SSL certificate validation failed. Is someone trying to tamper with your internet connection?`, { cause: error })
       }
-      throw new Error(`Failed to fetch ${url}: ${error}`)
+      throw new Error(`Failed to fetch ${url}: ${error}`, { cause: error })
     }
 
     if (response.status !== 200) {
@@ -183,13 +183,13 @@ export class TargetEnvironment {
       // User-friendly error messages for well-known HTTP errors.
       if (error instanceof FetchJsonHttpError) {
         if (error.response.status === 404) {
-          throw new Error(`Environment ${this.humanId} does not exist.`)
+          throw new Error(`Environment ${this.humanId} does not exist.`, { cause: error })
         } else if (error.response.status === 403) {
-          throw new Error(`Your account does not have permissions to access environment ${this.humanId}.`)
+          throw new Error(`Your account does not have permissions to access environment ${this.humanId}.`, { cause: error })
         }
       }
       const errorMessage = (error instanceof Error) ? error.message : String(error)
-      throw new Error(`Failed to fetch Kubernetes KubeConfig: ${errorMessage}`)
+      throw new Error(`Failed to fetch Kubernetes KubeConfig: ${errorMessage}`, { cause: error })
     }
 
     if (!kubeExecCredential.spec.cluster) {

package/src/utils.ts

@@ -1,12 +1,12 @@
-import { spawn } from 'child_process'
+import { spawn } from 'node:child_process'
 import yaml from 'js-yaml'
-import path from 'path'
+import path from 'node:path'
 import * as semver from 'semver'
 
 import { logger } from './logging.js'
-import { tmpdir } from 'os'
-import { randomBytes } from 'crypto'
-import { unlink, writeFile } from 'fs/promises'
+import { tmpdir } from 'node:os'
+import { randomBytes } from 'node:crypto'
+import { unlink, writeFile } from 'node:fs/promises'
 
 /**
  * Checks if the given string is a fully qualified domain name (FQDN).
@@ -44,9 +44,9 @@ export function splitUrlComponents(urlString: string): {
     const subpaths = url.pathname.slice(1) ?? null
 
     return { scheme, hostname, port, subpaths }
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+     
   } catch (error) {
-    throw new Error('Invalid URL')
+    throw new Error('Invalid URL', { cause: error })
   }
 }
 
@@ -220,6 +220,58 @@ export function resolveBestMatchingVersion(versions: string[], range: semver.Ran
   return sortedVersions[0]
 }
 
+/**
+ * Check that the installed Helm version is compatible with the required version range.
+ * Validates that Helm version is >= 3.18.0 and < 3.18.5.
+ *
+ * Version 3.18.5 (and recent other patch versions) tightened up the Helm chart validation logic
+ * and we can't retroactively fix the charts. The path forward is to upgrade to more recent Metaplay
+ * SDK versions and switch to the new CLI (https://github.com/metaplay/cli).
+ *
+ * @throws Error if Helm is not installed, version cannot be determined, or version is incompatible
+ */
+export async function checkHelmVersion(): Promise<void> {
+  try {
+    // Execute 'helm version' command to get version information
+    const result = await executeCommand('helm', ['version', '--short'])
+
+    if (result.exitCode !== 0) {
+      throw new Error(`Helm version command failed with exit code ${result.exitCode}: ${result.stderr.join('')}`)
+    }
+
+    // Parse version from output (format: "v3.18.0+g123abc")
+    const versionOutput = result.stdout.join('').trim()
+    const versionRegex = /v(\d+\.\d+\.\d+)/
+    const versionMatch = versionRegex.exec(versionOutput)
+
+    if (!versionMatch) {
+      throw new Error(`Could not parse Helm version from output: ${versionOutput}`)
+    }
+
+    const helmVersion = versionMatch[1]
+    logger.debug(`Detected Helm version: ${helmVersion}`)
+
+    // Check version constraints: >= 3.18.0 and <= 3.18.4
+    const minVersion = '3.18.0'
+    const maxVersion = '3.18.4'
+
+    if (!semver.gte(helmVersion, minVersion)) {
+      throw new Error(`Locally installed Helm version ${helmVersion} is too old. Use Helm v${maxVersion} which is the latest compatible version`)
+    }
+
+    if (!semver.lte(helmVersion, maxVersion)) {
+      throw new Error(`Locally installed Helm version ${helmVersion} is too new. Use Helm v${maxVersion} which is the latest compatible version`)
+    }
+
+    logger.debug(`Helm version ${helmVersion} is compatible`)
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('ENOENT')) {
+      throw new Error('Helm is not installed or not found in PATH. Please install Helm version >= 3.18.0 and < 3.18.5', { cause: error })
+    }
+    throw error
+  }
+}
+
 /**
  * Execute a Helm command by invoking the Helm CLI client with the given kubeconfig and arguments to `helm`.
  * The provided kubeconfig is written to a temporary file and cleaned up after, and passed to `helm` with
@@ -230,6 +282,7 @@ export async function executeHelmCommand(kubeconfigPayload: string, args: string
   const kubeconfigPath = pathJoin(tmpdir(), randomBytes(20).toString('hex'))
   logger.debug(`Write temporary kubeconfig in ${kubeconfigPath}`)
   await writeFile(kubeconfigPath, kubeconfigPayload, { mode: 0o600 })
+  // eslint-disable-next-line no-param-reassign
   args = args.concat(['--kubeconfig', kubeconfigPath])
 
   // Use try-finally to remove the temp kubeconfig at the end
@@ -241,7 +294,7 @@ export async function executeHelmCommand(kubeconfigPayload: string, args: string
       // \todo output something from Helm result?
     } catch (error) {
       const errMessage = error instanceof Error ? error.message : String(error)
-      throw new Error(`Failed to execute 'helm': ${errMessage}. You need to have Helm v3 installed to deploy a game server with metaplay-auth.`)
+      throw new Error(`Failed to execute 'helm': ${errMessage}. You need to have Helm v3 installed to deploy a game server with metaplay-auth.`, { cause: error })
     }
 
     // Throw on Helm non-success exit code

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.9.1"
+export const PACKAGE_VERSION = "1.9.3-next.878"