Merge pull request #4531 from Infisical/ENG-2785

Infisical Version Upgrade Tool

backend/package-lock.json

@@ -83,6 +83,7 @@
         "ioredis": "^5.3.2",
         "isomorphic-dompurify": "^2.22.0",
         "jmespath": "^0.16.0",
+        "js-yaml": "^4.1.0",
         "jsonwebtoken": "^9.0.2",
         "jsrp": "^0.2.4",
         "jwks-rsa": "^3.1.0",
@@ -143,6 +144,7 @@
         "@smithy/types": "^4.3.1",
         "@types/bcrypt": "^5.0.2",
         "@types/jmespath": "^0.15.2",
+        "@types/js-yaml": "^4.0.9",
         "@types/jsonwebtoken": "^9.0.5",
         "@types/jsrp": "^0.2.6",
         "@types/libsodium-wrappers": "^0.7.13",
@@ -13160,6 +13162,13 @@
       "integrity": "sha512-pegh49FtNsC389Flyo9y8AfkVIZn9MMPE9yJrO9svhq6Fks2MwymULWjZqySuxmctd3ZH4/n7Mr98D+1Qo5vGA==",
       "dev": true
     },
+    "node_modules/@types/js-yaml": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
+      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/json-schema": {
       "version": "7.0.15",
       "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
@@ -20452,6 +20461,7 @@
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
       "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
+      "license": "MIT",
       "dependencies": {
         "argparse": "^2.0.1"
       },

backend/package.json

@@ -73,7 +73,8 @@
     "seed": "knex --knexfile ./dist/db/knexfile.ts --client pg seed:run",
     "seed-dev": "knex --knexfile ./src/db/knexfile.ts --client pg seed:run",
     "db:reset": "npm run migration:rollback -- --all && npm run migration:latest",
-    "email:dev": "email dev --dir src/services/smtp/emails"
+    "email:dev": "email dev --dir src/services/smtp/emails",
+    "validate-upgrade-path": "tsx ./scripts/validate-upgrade-path-file.ts"
   },
   "keywords": [],
   "author": "",
@@ -87,6 +88,7 @@
     "@smithy/types": "^4.3.1",
     "@types/bcrypt": "^5.0.2",
     "@types/jmespath": "^0.15.2",
+    "@types/js-yaml": "^4.0.9",
     "@types/jsonwebtoken": "^9.0.5",
     "@types/jsrp": "^0.2.6",
     "@types/libsodium-wrappers": "^0.7.13",
@@ -203,6 +205,7 @@
     "ioredis": "^5.3.2",
     "isomorphic-dompurify": "^2.22.0",
     "jmespath": "^0.16.0",
+    "js-yaml": "^4.1.0",
     "jsonwebtoken": "^9.0.2",
     "jsrp": "^0.2.4",
     "jwks-rsa": "^3.1.0",

backend/scripts/validate-upgrade-path-file.ts

@@ -0,0 +1,107 @@
+/* eslint-disable no-console */
+import { readFile } from "fs/promises";
+import * as yaml from "js-yaml";
+import * as path from "path";
+import { z } from "zod";
+
+import { upgradePathConfigSchema } from "../src/services/upgrade-path/upgrade-path-schemas";
+
+async function validateUpgradePathConfig(): Promise<void> {
+  try {
+    const yamlPath = path.join(__dirname, "..", "upgrade-path.yaml");
+    const resolvedPath = path.resolve(yamlPath);
+    const expectedBaseDir = path.resolve(__dirname, "..");
+
+    if (!resolvedPath.startsWith(expectedBaseDir)) {
+      throw new Error("Invalid configuration file path");
+    }
+
+    try {
+      await readFile(yamlPath, "utf8");
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        console.log("Warning: No upgrade-path.yaml file found");
+        return;
+      }
+      throw error;
+    }
+
+    const yamlContent = await readFile(yamlPath, "utf8");
+
+    if (yamlContent.length > 1024 * 1024) {
+      throw new Error("Config file too large (>1MB)");
+    }
+
+    let config: unknown;
+    try {
+      config = yaml.load(yamlContent, {
+        schema: yaml.FAILSAFE_SCHEMA,
+        filename: yamlPath,
+        onWarning: (warning) => {
+          console.log(`YAML Warning: ${warning.message}`);
+        }
+      });
+    } catch (yamlError) {
+      if (yamlError instanceof yaml.YAMLException) {
+        throw new Error(
+          `YAML parsing failed: ${yamlError.message} at line ${yamlError.mark?.line}, column ${yamlError.mark?.column}`
+        );
+      }
+      throw new Error(`YAML parsing failed: ${yamlError instanceof Error ? yamlError.message : "Unknown YAML error"}`);
+    }
+
+    if (!config) {
+      console.log("Warning: Empty configuration file");
+      return;
+    }
+
+    if (typeof config !== "object" || config === null) {
+      throw new Error("Configuration must be a valid YAML object");
+    }
+
+    const result = upgradePathConfigSchema.safeParse(config);
+
+    if (!result.success) {
+      console.log("Validation failed with the following errors:");
+      result.error.issues.forEach((issue: z.ZodIssue) => {
+        const issuePath = issue.path.length > 0 ? `[${issue.path.join(".")}]` : "";
+        console.log(`  - ${issuePath}: ${issue.message}`);
+      });
+      throw new Error("Schema validation failed");
+    }
+
+    const validatedConfig = result.data;
+    const versions = validatedConfig?.versions || {};
+    const versionCount = Object.keys(versions).length;
+
+    if (versionCount === 0) {
+      console.log("Warning: No versions found in the configuration");
+    } else {
+      console.log(`Validated ${versionCount} version configuration(s)`);
+
+      const commonPatterns = [
+        /^v?\d+\.\d+\.\d+$/,
+        /^v?\d+\.\d+\.\d+\.\d+$/,
+        /^infisical\/v?\d+\.\d+\.\d+$/,
+        /^infisical\/v?\d+\.\d+\.\d+-\w+$/
+      ];
+
+      for (const versionKey of Object.keys(versions)) {
+        const isCommonPattern = commonPatterns.some((pattern) => pattern.test(versionKey));
+        if (!isCommonPattern) {
+          console.log(`Warning: Version key '${versionKey}' doesn't match common patterns. This may be intentional.`);
+        }
+      }
+    }
+
+    console.log("upgrade-path.yaml format is valid");
+  } catch (error) {
+    console.error(`Validation failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+    process.exit(1);
+  }
+}
+
+validateUpgradePathConfig().catch((error) => {
+  console.error("Unexpected error:", error);
+  process.exit(1);
+});

backend/src/@types/fastify.d.ts

@@ -115,6 +115,7 @@ import { TSlackServiceFactory } from "@app/services/slack/slack-service";
 import { TSuperAdminServiceFactory } from "@app/services/super-admin/super-admin-service";
 import { TTelemetryServiceFactory } from "@app/services/telemetry/telemetry-service";
 import { TTotpServiceFactory } from "@app/services/totp/totp-service";
+import { TUpgradePathService } from "@app/services/upgrade-path/upgrade-path-service";
 import { TUserDALFactory } from "@app/services/user/user-dal";
 import { TUserServiceFactory } from "@app/services/user/user-service";
 import { TUserEngagementServiceFactory } from "@app/services/user-engagement/user-engagement-service";
@@ -314,6 +315,7 @@ declare module "fastify" {
       identityAuthTemplate: TIdentityAuthTemplateServiceFactory;
       notification: TNotificationServiceFactory;
       offlineUsageReport: TOfflineUsageReportServiceFactory;
+      upgradePath: TUpgradePathService;
     };
     // this is exclusive use for middlewares in which we need to inject data
     // everywhere else access using service layer

backend/src/lib/config/env.ts

@@ -129,6 +129,8 @@ const envSchema = z
     POSTHOG_HOST: zpStr(z.string().optional().default("https://app.posthog.com")),
     POSTHOG_PROJECT_API_KEY: zpStr(z.string().optional().default("phc_nSin8j5q2zdhpFDI1ETmFNUIuTG4DwKVyIigrY10XiE")),
     LOOPS_API_KEY: zpStr(z.string().optional()),
+    // GitHub API token for upgrade path tool
+    GITHUB_API_TOKEN: zpStr(z.string().optional()),
     // jwt options
     AUTH_SECRET: zpStr(z.string()).default(process.env.JWT_AUTH_SECRET), // for those still using old JWT_AUTH_SECRET
     JWT_AUTH_LIFETIME: zpStr(z.string().default("10d")),

backend/src/server/routes/index.ts

@@ -313,6 +313,7 @@ import { telemetryQueueServiceFactory } from "@app/services/telemetry/telemetry-
 import { telemetryServiceFactory } from "@app/services/telemetry/telemetry-service";
 import { totpConfigDALFactory } from "@app/services/totp/totp-config-dal";
 import { totpServiceFactory } from "@app/services/totp/totp-service";
+import { upgradePathServiceFactory } from "@app/services/upgrade-path/upgrade-path-service";
 import { userDALFactory } from "@app/services/user/user-dal";
 import { userServiceFactory } from "@app/services/user/user-service";
 import { userAliasDALFactory } from "@app/services/user-alias/user-alias-dal";
@@ -764,6 +765,8 @@ export const registerRoutes = async (
     userAliasDAL
   });
 
+  const upgradePathService = upgradePathServiceFactory({ keyStore });
+
   const totpService = totpServiceFactory({
     totpConfigDAL,
     userDAL,
@@ -2236,7 +2239,8 @@ export const registerRoutes = async (
     reminder: reminderService,
     bus: eventBusService,
     sse: sseService,
-    notification: notificationService
+    notification: notificationService,
+    upgradePath: upgradePathService
   });
 
   const cronJobs: CronJob[] = [];

backend/src/server/routes/v1/index.ts

@@ -58,6 +58,7 @@ import { registerSecretRequestsRouter } from "./secret-requests-router";
 import { registerSecretSharingRouter } from "./secret-sharing-router";
 import { registerSecretTagRouter } from "./secret-tag-router";
 import { registerSlackRouter } from "./slack-router";
+import { registerUpgradePathRouter } from "./upgrade-path-router";
 import { registerSsoRouter } from "./sso-router";
 import { registerUserActionRouter } from "./user-action-router";
 import { registerUserEngagementRouter } from "./user-engagement-router";
@@ -217,4 +218,5 @@ export const registerV1Routes = async (server: FastifyZodProvider) => {
   );
 
   await server.register(registerEventRouter, { prefix: "/events" });
+  await server.register(registerUpgradePathRouter, { prefix: "/upgrade-path" });
 };

backend/src/server/routes/v1/upgrade-path-router.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+
+import { BadRequestError } from "@app/lib/errors";
+import { logger } from "@app/lib/logger";
+import { publicEndpointLimit } from "@app/server/config/rateLimiter";
+import { versionSchema } from "@app/services/upgrade-path/upgrade-path-schemas";
+
+export const registerUpgradePathRouter = async (server: FastifyZodProvider) => {
+  server.route({
+    method: "GET",
+    url: "/versions",
+    config: {
+      rateLimit: publicEndpointLimit
+    },
+    schema: {
+      response: {
+        200: z.object({
+          versions: z.array(
+            z.object({
+              tagName: z.string(),
+              name: z.string(),
+              publishedAt: z.string(),
+              prerelease: z.boolean(),
+              draft: z.boolean()
+            })
+          )
+        })
+      }
+    },
+    handler: async (req) => {
+      try {
+        const versions = await req.server.services.upgradePath.getGitHubReleases();
+
+        return {
+          versions
+        };
+      } catch (error) {
+        logger.error(error, "Failed to fetch versions");
+        if (error instanceof z.ZodError) {
+          throw new BadRequestError({ message: "Invalid query parameters" });
+        }
+        throw new BadRequestError({ message: "Failed to fetch GitHub releases" });
+      }
+    }
+  });
+
+  server.route({
+    method: "POST",
+    url: "/calculate",
+    config: {
+      rateLimit: publicEndpointLimit
+    },
+    schema: {
+      body: z.object({
+        fromVersion: versionSchema,
+        toVersion: versionSchema
+      }),
+      response: {
+        200: z.object({
+          path: z.array(
+            z.object({
+              version: z.string(),
+              name: z.string(),
+              publishedAt: z.string(),
+              prerelease: z.boolean()
+            })
+          ),
+          breakingChanges: z.array(
+            z.object({
+              version: z.string(),
+              changes: z.array(
+                z.object({
+                  title: z.string(),
+                  description: z.string(),
+                  action: z.string()
+                })
+              )
+            })
+          ),
+          features: z.array(
+            z.object({
+              version: z.string(),
+              name: z.string(),
+              body: z.string(),
+              publishedAt: z.string()
+            })
+          ),
+          hasDbMigration: z.boolean(),
+          config: z.record(z.unknown())
+        })
+      }
+    },
+    handler: async (req) => {
+      try {
+        const { fromVersion, toVersion } = req.body;
+
+        const result = await req.server.services.upgradePath.calculateUpgradePath(fromVersion, toVersion);
+
+        logger.info(
+          { pathLength: result.path.length, hasBreaking: result.breakingChanges.length > 0 },
+          "Upgrade path calculated"
+        );
+
+        return result;
+      } catch (error) {
+        logger.error(error, "Failed to calculate upgrade path");
+        if (error instanceof z.ZodError) {
+          throw new BadRequestError({ message: `Invalid input: ${error.errors.map((e) => e.message).join(", ")}` });
+        }
+        if (error instanceof Error) {
+          throw new BadRequestError({ message: error.message });
+        }
+        throw new BadRequestError({ message: "Failed to calculate upgrade path" });
+      }
+    }
+  });
+};

backend/src/services/upgrade-path/github-client.ts

@@ -0,0 +1,242 @@
+/* eslint-disable no-await-in-loop */
+import RE2 from "re2";
+
+import { getConfig } from "@app/lib/config/env";
+
+import { FormattedRelease, GitHubApiError, GitHubRelease } from "./types";
+
+interface GitHubClientConfig {
+  token?: string;
+  timeout: number;
+  maxRetries: number;
+  retryDelay: number;
+  maxPagesPerRequest: number;
+  perPage: number;
+}
+
+interface RateLimitInfo {
+  remaining: number;
+  reset: Date;
+  used: number;
+  limit: number;
+}
+
+const getDefaultConfig = (): GitHubClientConfig => ({
+  token: getConfig().GITHUB_API_TOKEN,
+  timeout: 30000,
+  maxRetries: 3,
+  retryDelay: 1000,
+  maxPagesPerRequest: 10,
+  perPage: 100
+});
+
+const getHeaders = (token?: string): Record<string, string> => {
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "Infisical-Upgrade-Path-Tool/1.0",
+    "X-GitHub-Api-Version": "2022-11-28"
+  };
+
+  if (token) {
+    headers.Authorization = `token ${token}`;
+  }
+
+  return headers;
+};
+
+const delay = (ms: number): Promise<void> => {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+};
+
+const isMainInfisicalRelease = (tagName: string): boolean => {
+  if (
+    tagName.startsWith("infisical-cli/") ||
+    tagName.startsWith("infisical-k8-operator/") ||
+    tagName.startsWith("infisical-k8s-operator/")
+  ) {
+    return false;
+  }
+
+  const patterns = [
+    new RE2(/^v\d+\.\d+\.\d+/),
+    new RE2(/^\d+\.\d+\.\d+/),
+    new RE2(/^infisical\/v?\d+\.\d+\.\d+/),
+    new RE2(/^infisical\/v?\d+\.\d+\.\d+[-\w]*/)
+  ];
+
+  return patterns.some((pattern) => pattern.test(tagName));
+};
+
+const normalizeVersion = (tagName: string): string => {
+  const versionMatch = tagName.match(new RE2(/(\d+\.\d+\.\d+(?:\.\d+)?)/));
+  if (versionMatch) {
+    return `v${versionMatch[1]}`;
+  }
+
+  if (tagName.startsWith("infisical/")) {
+    const withoutPrefix = tagName.replace(new RE2(/^infisical\//), "");
+    return withoutPrefix.replace(new RE2(/-[a-zA-Z]+$/), "");
+  }
+  return tagName.replace(new RE2(/-[a-zA-Z]+$/), "");
+};
+
+const compareVersions = (v1: string, v2: string): number => {
+  const normalize = (v: string) => {
+    const versionMatch = v.match(new RE2(/(\d+\.\d+\.\d+(?:\.\d+)?)/));
+    if (versionMatch) {
+      return versionMatch[1];
+    }
+    if (v.startsWith("infisical/")) {
+      return v.replace(new RE2(/^infisical\/v?/), "").replace(new RE2(/-[a-zA-Z]+$/), "");
+    }
+    return v.replace(new RE2(/^v/), "").replace(new RE2(/-[a-zA-Z]+$/), "");
+  };
+
+  const clean1 = normalize(v1);
+  const clean2 = normalize(v2);
+
+  const parts1 = clean1.split(".").map(Number);
+  const parts2 = clean2.split(".").map(Number);
+
+  const maxLength = Math.max(parts1.length, parts2.length);
+  while (parts1.length < maxLength) parts1.push(0);
+  while (parts2.length < maxLength) parts2.push(0);
+
+  for (let i = 0; i < maxLength; i += 1) {
+    if (parts1[i] > parts2[i]) return 1;
+    if (parts1[i] < parts2[i]) return -1;
+  }
+  return 0;
+};
+
+const isVersionAtLeastMinimum = (tagName: string, minimumVersion = "0.147.0"): boolean => {
+  return compareVersions(tagName, minimumVersion) >= 0;
+};
+
+const makeRequest = async <T>(
+  url: string,
+  config: GitHubClientConfig,
+  retryCount = 0
+): Promise<{ data: T; rateLimit: RateLimitInfo }> => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeout);
+
+  try {
+    const response = await fetch(url, {
+      headers: getHeaders(config.token),
+      signal: controller.signal
+    });
+
+    clearTimeout(timeout);
+
+    const rateLimit: RateLimitInfo = {
+      remaining: parseInt(response.headers.get("X-RateLimit-Remaining") || "0", 10),
+      reset: new Date(parseInt(response.headers.get("X-RateLimit-Reset") || "0", 10) * 1000),
+      used: parseInt(response.headers.get("X-RateLimit-Used") || "0", 10),
+      limit: parseInt(response.headers.get("X-RateLimit-Limit") || "5000", 10)
+    };
+
+    if (!response.ok) {
+      const error: GitHubApiError = new Error(`GitHub API error: ${response.status}`);
+      error.status = response.status;
+      error.headers = response.headers;
+
+      if (response.status === 403) {
+        const resetTime = rateLimit.reset.toISOString();
+        error.message = `GitHub API rate limit exceeded. Remaining: ${rateLimit.remaining}, Reset at: ${resetTime}. ${
+          !config.token ? "Consider setting GITHUB_TOKEN environment variable." : ""
+        }`;
+      }
+
+      if (retryCount < config.maxRetries && (response.status >= 500 || response.status === 403)) {
+        await delay(config.retryDelay * 2 ** retryCount);
+        return await makeRequest<T>(url, config, retryCount + 1);
+      }
+
+      throw error;
+    }
+
+    const data = (await response.json()) as T;
+    return { data, rateLimit };
+  } catch (error) {
+    clearTimeout(timeout);
+
+    if (error instanceof Error && error.name === "AbortError") {
+      if (retryCount < config.maxRetries) {
+        await delay(config.retryDelay * 2 ** retryCount);
+        return await makeRequest<T>(url, config, retryCount + 1);
+      }
+      throw new Error(`Request timeout after ${config.timeout}ms`);
+    }
+
+    if (retryCount < config.maxRetries && !(error as GitHubApiError).status) {
+      await delay(config.retryDelay * 2 ** retryCount);
+      return await makeRequest<T>(url, config, retryCount + 1);
+    }
+
+    throw error;
+  }
+};
+
+export const fetchReleases = async (includePrerelease = false): Promise<FormattedRelease[]> => {
+  const config = getDefaultConfig();
+  const allReleases: GitHubRelease[] = [];
+  let page = 1;
+  let hasMorePages = true;
+  let reachedMinimumVersion = false;
+
+  const maxConcurrentRequests = Math.min(3, config.maxPagesPerRequest);
+
+  while (hasMorePages && page <= config.maxPagesPerRequest && !reachedMinimumVersion) {
+    const requests: Promise<{ data: GitHubRelease[]; rateLimit: RateLimitInfo }>[] = [];
+
+    for (let i = 0; i < maxConcurrentRequests && page <= config.maxPagesPerRequest; i += 1, page += 1) {
+      const url = `https://api.github.com/repos/Infisical/infisical/releases?page=${page}&per_page=${config.perPage}`;
+      requests.push(makeRequest<GitHubRelease[]>(url, config));
+    }
+
+    const results = await Promise.allSettled(requests);
+    let hasData = false;
+
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        const { data } = result.value;
+        if (data.length > 0) {
+          for (const release of data) {
+            if (!release.draft && isMainInfisicalRelease(release.tag_name)) {
+              if (isVersionAtLeastMinimum(release.tag_name)) {
+                allReleases.push(release);
+              } else {
+                reachedMinimumVersion = true;
+                break;
+              }
+            }
+          }
+          hasData = true;
+        }
+      }
+    }
+
+    if (!hasData || results.every((r) => r.status === "fulfilled" && r.value.data.length < config.perPage)) {
+      hasMorePages = false;
+    }
+  }
+
+  const formattedReleases = allReleases
+    .map(
+      (release): FormattedRelease => ({
+        tagName: release.tag_name,
+        normalizedTagName: normalizeVersion(release.tag_name),
+        name: release.name,
+        body: release.body,
+        publishedAt: release.published_at,
+        prerelease: release.prerelease,
+        draft: release.draft
+      })
+    )
+    .sort((a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime());
+
+  return formattedReleases.filter((release) => includePrerelease || !release.prerelease);
+};

backend/src/services/upgrade-path/index.ts

@@ -0,0 +1,2 @@
+export type { TUpgradePathService, TUpgradePathServiceFactory } from "./upgrade-path-service";
+export { upgradePathServiceFactory } from "./upgrade-path-service";

backend/src/services/upgrade-path/types.ts

@@ -0,0 +1,66 @@
+export interface GitHubRelease {
+  tag_name: string;
+  name: string;
+  body: string;
+  published_at: string;
+  prerelease: boolean;
+  draft: boolean;
+}
+
+export interface FormattedRelease {
+  tagName: string;
+  normalizedTagName: string;
+  name: string;
+  body: string;
+  publishedAt: string;
+  prerelease: boolean;
+  draft: boolean;
+}
+
+export interface BreakingChange {
+  title: string;
+  description: string;
+  action: string;
+}
+
+export interface VersionConfig {
+  breaking_changes?: BreakingChange[];
+  db_schema_changes?: string;
+  notes?: string;
+}
+
+export interface UpgradePathConfig {
+  versions?: Record<string, VersionConfig>;
+}
+
+export interface UpgradePathResult {
+  path: Array<{
+    version: string;
+    name: string;
+    publishedAt: string;
+    prerelease: boolean;
+  }>;
+  breakingChanges: Array<{
+    version: string;
+    changes: BreakingChange[];
+  }>;
+  features: Array<{
+    version: string;
+    name: string;
+    body: string;
+    publishedAt: string;
+  }>;
+  hasDbMigration: boolean;
+  config: Record<string, unknown>;
+}
+
+export interface GitHubApiError extends Error {
+  status?: number;
+  headers?: Headers;
+}
+
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  ttl: number;
+}

backend/src/services/upgrade-path/upgrade-path-schemas.ts

@@ -0,0 +1,24 @@
+import RE2 from "re2";
+import { z } from "zod";
+
+export const versionSchema = z
+  .string()
+  .min(1)
+  .max(50)
+  .regex(new RE2(/^[a-zA-Z0-9._/-]+$/), "Invalid version format");
+
+export const breakingChangeSchema = z.object({
+  title: z.string().min(1).max(200),
+  description: z.string().min(1).max(1000),
+  action: z.string().min(1).max(500)
+});
+
+export const versionConfigSchema = z.object({
+  breaking_changes: z.array(breakingChangeSchema).optional(),
+  db_schema_changes: z.string().max(1000).optional(),
+  notes: z.string().max(2000).optional()
+});
+
+export const upgradePathConfigSchema = z.object({
+  versions: z.record(versionSchema, versionConfigSchema).optional().nullable()
+});

backend/src/services/upgrade-path/upgrade-path-service.ts

@@ -0,0 +1,259 @@
+import { readFile } from "fs/promises";
+import * as yaml from "js-yaml";
+import * as path from "path";
+import RE2 from "re2";
+import { z } from "zod";
+
+import { TKeyStoreFactory } from "@app/keystore/keystore";
+import { logger } from "@app/lib/logger";
+
+import { fetchReleases } from "./github-client";
+import { BreakingChange, FormattedRelease, UpgradePathConfig, UpgradePathResult, VersionConfig } from "./types";
+import { versionConfigSchema, versionSchema } from "./upgrade-path-schemas";
+
+export type TUpgradePathServiceFactory = {
+  keyStore: TKeyStoreFactory;
+};
+export type TUpgradePathService = ReturnType<typeof upgradePathServiceFactory>;
+
+interface CalculateUpgradePathParams {
+  fromVersion: string;
+  toVersion: string;
+}
+
+export const upgradePathServiceFactory = ({ keyStore }: TUpgradePathServiceFactory) => {
+  const sanitizeCacheKey = (key: string): string => {
+    return key.replace(new RE2(/[^a-zA-Z0-9\-:._]/g), "_");
+  };
+  const getGitHubReleases = async (): Promise<FormattedRelease[]> => {
+    const cacheKey = "upgrade-path:releases";
+
+    try {
+      const cached = await keyStore.getItem(cacheKey);
+      if (cached) {
+        const cachedReleases = JSON.parse(cached) as FormattedRelease[];
+        if (cachedReleases.length > 0) {
+          return cachedReleases;
+        }
+      }
+    } catch (error) {
+      logger.error(error, "Failed to retrieve releases from cache");
+    }
+
+    try {
+      const releases = await fetchReleases(false);
+      const filteredReleases = releases.filter((v) => !v.tagName.includes("nightly"));
+
+      await keyStore.setItemWithExpiry(cacheKey, 24 * 60 * 60, JSON.stringify(filteredReleases));
+      return filteredReleases;
+    } catch (error) {
+      throw new Error(`GitHub releases unavailable: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+  };
+
+  const getUpgradePathConfig = async (): Promise<Record<string, z.infer<typeof versionConfigSchema>>> => {
+    const cacheKey = "upgrade-path:config";
+
+    try {
+      const cached = await keyStore.getItem(cacheKey);
+      if (cached) return JSON.parse(cached) as Record<string, VersionConfig>;
+    } catch (error) {
+      logger.error(error, "Failed to retrieve config from cache");
+    }
+
+    try {
+      const yamlPath = path.join(__dirname, "..", "..", "..", "upgrade-path.yaml");
+      const resolvedPath = path.resolve(yamlPath);
+      const expectedBaseDir = path.resolve(__dirname, "..", "..", "..");
+      if (!resolvedPath.startsWith(expectedBaseDir)) {
+        throw new Error("Invalid configuration file path");
+      }
+
+      const yamlContent = await readFile(yamlPath, "utf8");
+
+      if (yamlContent.length > 1024 * 1024) {
+        throw new Error("Config file too large");
+      }
+
+      const config = yaml.load(yamlContent, { schema: yaml.FAILSAFE_SCHEMA }) as UpgradePathConfig;
+      const versionConfig = config?.versions || {};
+
+      await keyStore.setItemWithExpiry(cacheKey, 24 * 60 * 60, JSON.stringify(versionConfig));
+      return versionConfig;
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        const empty = {};
+        await keyStore.setItemWithExpiry(cacheKey, 24 * 60 * 60, JSON.stringify(empty));
+        return empty;
+      }
+      throw new Error(`Config load failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+  };
+
+  const normalizeVersion = (version: string): string => {
+    const versionRegex = new RE2(/(\d+\.\d+\.\d+(?:\.\d+)?)/);
+    const versionMatch = version.match(versionRegex);
+    if (versionMatch) {
+      return versionMatch[1];
+    }
+
+    if (version.startsWith("infisical/")) {
+      return version.replace(new RE2(/^infisical\/v?/), "").replace(new RE2(/-[a-zA-Z]+$/), "");
+    }
+    return version.replace(new RE2(/^v/), "").replace(new RE2(/-[a-zA-Z]+$/), "");
+  };
+
+  const validateParams = (params: CalculateUpgradePathParams) => {
+    const { fromVersion, toVersion } = params;
+
+    versionSchema.parse(fromVersion);
+    versionSchema.parse(toVersion);
+
+    if (fromVersion === toVersion) {
+      throw new Error("Versions cannot be identical");
+    }
+
+    if (fromVersion.includes("nightly") || toVersion.includes("nightly")) {
+      throw new Error("Nightly releases are not supported for upgrade path calculation");
+    }
+
+    return { fromVersion, toVersion };
+  };
+
+  const calculateUpgradePath = async (params: CalculateUpgradePathParams): Promise<UpgradePathResult> => {
+    const { fromVersion, toVersion } = validateParams(params);
+    const cacheKey = sanitizeCacheKey(`upgrade-path:${fromVersion}:${toVersion}`);
+
+    try {
+      const cached = await keyStore.getItem(cacheKey);
+      if (cached) return JSON.parse(cached) as UpgradePathResult;
+    } catch (error) {
+      logger.error(error, "Failed to retrieve upgrade path from cache");
+    }
+
+    const [releases, config] = await Promise.all([getGitHubReleases(), getUpgradePathConfig()]);
+
+    const cleanFrom = normalizeVersion(fromVersion);
+    const cleanTo = normalizeVersion(toVersion);
+
+    const compareVersions = (v1: string, v2: string): number => {
+      const normalize = (v: string) => normalizeVersion(v);
+      const clean1 = normalize(v1);
+      const clean2 = normalize(v2);
+
+      const parts1 = clean1.split(".").map(Number);
+      const parts2 = clean2.split(".").map(Number);
+
+      const maxLength = Math.max(parts1.length, parts2.length);
+      while (parts1.length < maxLength) parts1.push(0);
+      while (parts2.length < maxLength) parts2.push(0);
+
+      for (let i = 0; i < maxLength; i += 1) {
+        if (parts1[i] > parts2[i]) return 1;
+        if (parts1[i] < parts2[i]) return -1;
+      }
+      return 0;
+    };
+
+    if (compareVersions(cleanFrom, cleanTo) >= 0) {
+      throw new Error("fromVersion must be older than toVersion");
+    }
+
+    const fromIdx = releases.findIndex((r) => normalizeVersion(r.normalizedTagName) === cleanFrom);
+    const toIdx = releases.findIndex((r) => normalizeVersion(r.normalizedTagName) === cleanTo);
+
+    let upgradePath: FormattedRelease[] = [];
+    const filteredPath: FormattedRelease[] = [];
+
+    if (fromIdx !== -1 && toIdx !== -1) {
+      if (fromIdx <= toIdx) throw new Error("Invalid version order");
+      upgradePath = releases.slice(toIdx, fromIdx + 1).reverse();
+      const [first, last] = [upgradePath[0], upgradePath[upgradePath.length - 1]];
+
+      filteredPath.push(first);
+      if (last !== first) filteredPath.push(last);
+    }
+
+    const breakingChanges: Array<{ version: string; changes: BreakingChange[] }> = [];
+    const features: Array<{ version: string; name: string; body: string; publishedAt: string }> = [];
+    let hasDbMigration = false;
+
+    const isVersionInRange = (version: string, fromVer: string, toVer: string): boolean => {
+      const versionComp = compareVersions(version, fromVer);
+      const toVersionComp = compareVersions(version, toVer);
+      return versionComp > 0 && toVersionComp < 0;
+    };
+
+    Object.keys(config).forEach((configVersion) => {
+      const versionConfig = config[configVersion];
+      if (versionConfig?.breaking_changes?.length) {
+        if (isVersionInRange(configVersion, cleanFrom, cleanTo)) {
+          breakingChanges.push({
+            version: configVersion,
+            changes: versionConfig.breaking_changes
+          });
+        }
+      }
+    });
+    for (let i = 0; i < upgradePath.length; i += 1) {
+      const version = upgradePath[i];
+      const isFromVersion = normalizeVersion(version.normalizedTagName) === cleanFrom;
+
+      if (!isFromVersion) {
+        const versionNumber = normalizeVersion(version.tagName);
+        const possibleKeys = [
+          version.tagName,
+          version.normalizedTagName,
+          versionNumber,
+          `v${versionNumber}`,
+          version.tagName.replace(new RE2(/^infisical\//), ""),
+          version.tagName.replace(new RE2(/^infisical\/v?/), "").replace(new RE2(/-[a-zA-Z]+$/), "")
+        ];
+
+        for (const key of possibleKeys) {
+          const versionConfig = config[key];
+          if (
+            versionConfig?.db_schema_changes &&
+            typeof versionConfig.db_schema_changes === "string" &&
+            versionConfig.db_schema_changes.trim()
+          ) {
+            hasDbMigration = true;
+            break;
+          }
+        }
+      }
+
+      // Collect release notes and features
+      if (version.body) {
+        features.push({
+          version: version.tagName,
+          name: version.name,
+          body: version.body,
+          publishedAt: version.publishedAt
+        });
+      }
+    }
+
+    const result: UpgradePathResult = {
+      path: filteredPath.map((r) => ({
+        version: r.tagName,
+        name: r.name,
+        publishedAt: r.publishedAt,
+        prerelease: r.prerelease
+      })),
+      breakingChanges,
+      features,
+      hasDbMigration,
+      config
+    };
+
+    await keyStore.setItemWithExpiry(cacheKey, 60 * 60, JSON.stringify(result));
+    return result;
+  };
+
+  return {
+    getGitHubReleases,
+    getUpgradePathConfig,
+    calculateUpgradePath: (fromVersion: string, toVersion: string) => calculateUpgradePath({ fromVersion, toVersion })
+  };
+};

backend/upgrade-path.yaml

@@ -0,0 +1,26 @@
+# Upgrade Path Configuration File
+#
+# This file defines breaking changes and database migration information for Infisical versions.
+# Used by the upgrade path tool to help users understand what changes are required between versions.
+#
+# Expected format:
+# versions:
+#   "version_key":  # Can be "v1.2.3", "1.2.3", or "infisical/v1.2.3-postgres"
+#     breaking_changes:  # Optional: list of breaking changes for this version
+#       - title: "Short descriptive title"
+#         description: "Detailed description of what changed"
+#         action: "Specific steps users need to take"
+#     db_schema_changes: "Optional: Description of database changes and migration details"
+#     notes: "Optional: Additional notes or important information about this version"
+#
+# Example:
+# versions:
+#   "v1.2.3":
+#     breaking_changes:
+#       - title: "API Endpoint Changes"
+#         description: "Authentication endpoints have been restructured"
+#         action: "Update all API calls to use new /auth/v2/ endpoints"
+#     db_schema_changes: "Major schema restructuring with table reorganization. Extended migration time: 3 minutes."
+#     notes: "Critical update requiring maintenance window. Test thoroughly before production deployment."
+
+versions: