Add Northflank sync features and enhance documentation

- Implemented new Northflank sync functionality, including routes for listing secret groups and managing syncs.
- Added types and schemas for Northflank projects and secret groups to improve data handling.
- Updated frontend components to support Northflank sync configuration and review.
- Enhanced API documentation with detailed instructions for Northflank integration and usage.
- Included new images and examples in the documentation for better clarity.

backend/src/lib/api-docs/constants.ts

@@ -2607,6 +2607,12 @@ export const SecretSyncs = {
       siteName: "The name of the Netlify site to sync secrets to.",
       siteId: "The ID of the Netlify site to sync secrets to.",
       context: "The Netlify context to sync secrets to."
+    },
+    NORTHFLANK: {
+      projectId: "The ID of the Northflank project to sync secrets to.",
+      projectName: "The name of the Northflank project to sync secrets to.",
+      secretGroupId: "The ID of the Northflank secret group to sync secrets to.",
+      secretGroupName: "The name of the Northflank secret group to sync secrets to."
     }
   }
 };

backend/src/server/routes/v1/app-connection-routers/northflank-connection-router.ts

@@ -50,4 +50,38 @@ export const registerNorthflankConnectionRouter = async (server: FastifyZodProvi
       return { projects };
     }
   });
+
+  server.route({
+    method: "GET",
+    url: `/:connectionId/projects/:projectId/secret-groups`,
+    config: {
+      rateLimit: readLimit
+    },
+    schema: {
+      params: z.object({
+        connectionId: z.string().uuid(),
+        projectId: z.string()
+      }),
+      response: {
+        200: z.object({
+          secretGroups: z
+            .object({
+              name: z.string(),
+              id: z.string()
+            })
+            .array()
+        })
+      }
+    },
+    onRequest: verifyAuth([AuthMode.JWT]),
+    handler: async (req) => {
+      const { connectionId, projectId } = req.params;
+      const secretGroups = await server.services.appConnection.northflank.listSecretGroups(
+        connectionId,
+        projectId,
+        req.permission
+      );
+      return { secretGroups };
+    }
+  });
 };

backend/src/services/app-connection/northflank/northflank-connection-fns.ts

@@ -5,7 +5,12 @@ import { BadRequestError } from "@app/lib/errors";
 import { AppConnection } from "@app/services/app-connection/app-connection-enums";
 
 import { NorthflankConnectionMethod } from "./northflank-connection-enums";
-import { TNorthflankConnection, TNorthflankConnectionConfig, TNorthflankProject } from "./northflank-connection-types";
+import {
+  TNorthflankConnection,
+  TNorthflankConnectionConfig,
+  TNorthflankProject,
+  TNorthflankSecretGroup
+} from "./northflank-connection-types";
 
 const NORTHFLANK_API_URL = "https://api.northflank.com";
 
@@ -71,3 +76,39 @@ export const listProjects = async (appConnection: TNorthflankConnection): Promis
     });
   }
 };
+
+export const listSecretGroups = async (
+  appConnection: TNorthflankConnection,
+  projectId: string
+): Promise<TNorthflankSecretGroup[]> => {
+  const { credentials } = appConnection;
+
+  try {
+    const {
+      data: {
+        data: { secrets }
+      }
+    } = await request.get<{ data: { secrets: TNorthflankSecretGroup[] } }>(
+      `${NORTHFLANK_API_URL}/v1/projects/${projectId}/secrets`,
+      {
+        headers: {
+          Authorization: `Bearer ${credentials.apiToken}`,
+          Accept: "application/json"
+        }
+      }
+    );
+
+    return secrets;
+  } catch (error: unknown) {
+    if (error instanceof AxiosError) {
+      throw new BadRequestError({
+        message: `Failed to list Northflank secret groups: ${error.message || "Unknown error"}`
+      });
+    }
+
+    throw new BadRequestError({
+      message: "Unable to list Northflank secret groups",
+      error
+    });
+  }
+};

backend/src/services/app-connection/northflank/northflank-connection-service.ts

@@ -2,8 +2,11 @@ import { logger } from "@app/lib/logger";
 import { OrgServiceActor } from "@app/lib/types";
 
 import { AppConnection } from "../app-connection-enums";
-import { listProjects as getNorthflankProjects } from "./northflank-connection-fns";
-import { TNorthflankConnection } from "./northflank-connection-types";
+import {
+  listProjects as getNorthflankProjects,
+  listSecretGroups as getNorthflankSecretGroups
+} from "./northflank-connection-fns";
+import { TNorthflankConnection, TNorthflankSecretGroup } from "./northflank-connection-types";
 
 type TGetAppConnectionFunc = (
   app: AppConnection,
@@ -24,7 +27,24 @@ export const northflankConnectionService = (getAppConnection: TGetAppConnectionF
     }
   };
 
+  const listSecretGroups = async (
+    connectionId: string,
+    projectId: string,
+    actor: OrgServiceActor
+  ): Promise<TNorthflankSecretGroup[]> => {
+    const appConnection = await getAppConnection(AppConnection.Northflank, connectionId, actor);
+    try {
+      const secretGroups = await getNorthflankSecretGroups(appConnection, projectId);
+
+      return secretGroups;
+    } catch (error) {
+      logger.error({ error, connectionId, projectId, actor: actor.type }, "Failed to list Northflank secret groups");
+      return [];
+    }
+  };
+
   return {
-    listProjects
+    listProjects,
+    listSecretGroups
   };
 };

backend/src/services/app-connection/northflank/northflank-connection-types.ts

@@ -28,3 +28,8 @@ export type TNorthflankProject = {
   id: string;
   name: string;
 };
+
+export type TNorthflankSecretGroup = {
+  id: string;
+  name: string;
+};

backend/src/services/secret-sync/northflank/northflank-sync-fns.ts

@@ -1,22 +1,123 @@
-import { logger } from "@app/lib/logger";
-import { TSecretMap, TSecretSyncWithCredentials } from "@app/services/secret-sync/secret-sync-types";
+import { request } from "@app/lib/config/request";
+import { matchesSchema } from "@app/services/secret-sync/secret-sync-fns";
+import { TSecretMap } from "@app/services/secret-sync/secret-sync-types";
 
-export const NorthflankSyncFns = {
-  syncSecrets: async (secretSync: TSecretSyncWithCredentials, secretMap: TSecretMap): Promise<void> => {
-    // TODO: Will be implemented in the follow up PR
-    logger.error({ secretSync, secretMap }, "Northflank secret sync not yet implemented");
-    throw new Error("Northflank secret sync not yet implemented");
-  },
+import { SecretSyncError } from "../secret-sync-errors";
+import { TNorthflankSyncWithCredentials } from "./northflank-sync-types";
 
-  getSecrets: async (secretSync: TSecretSyncWithCredentials): Promise<TSecretMap> => {
-    // TODO: Will be implemented in the follow up PR
-    logger.error({ secretSync }, "Northflank secret retrieval not yet implemented");
-    throw new Error("Northflank secret retrieval not yet implemented");
-  },
+const NORTHFLANK_API_URL = "https://api.northflank.com";
 
-  removeSecrets: async (secretSync: TSecretSyncWithCredentials, secretMap: TSecretMap): Promise<void> => {
-    // TODO: Will be implemented in the follow up PR
-    logger.error({ secretSync, secretMap }, "Northflank secret removal not yet implemented");
-    throw new Error("Northflank secret removal not yet implemented");
+const getNorthflankSecrets = async (secretSync: TNorthflankSyncWithCredentials): Promise<Record<string, string>> => {
+  const {
+    destinationConfig: { projectId, secretGroupId },
+    connection: {
+      credentials: { apiToken }
+    }
+  } = secretSync;
+
+  try {
+    const {
+      data: {
+        data: {
+          secrets: { variables }
+        }
+      }
+    } = await request.get<{
+      data: {
+        secrets: {
+          variables: Record<string, string>;
+        };
+      };
+    }>(`${NORTHFLANK_API_URL}/v1/projects/${projectId}/secrets/${secretGroupId}/details`, {
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        Accept: "application/json"
+      }
+    });
+
+    return variables;
+  } catch (error: unknown) {
+    throw new SecretSyncError({
+      error,
+      message: "Failed to fetch Northflank secrets"
+    });
+  }
+};
+
+const updateNorthflankSecrets = async (
+  secretSync: TNorthflankSyncWithCredentials,
+  variables: Record<string, string>
+): Promise<void> => {
+  const {
+    destinationConfig: { projectId, secretGroupId },
+    connection: {
+      credentials: { apiToken }
+    }
+  } = secretSync;
+
+  try {
+    await request.patch(
+      `${NORTHFLANK_API_URL}/v1/projects/${projectId}/secrets/${secretGroupId}`,
+      {
+        secrets: {
+          variables
+        }
+      },
+      {
+        headers: {
+          Authorization: `Bearer ${apiToken}`,
+          Accept: "application/json"
+        }
+      }
+    );
+  } catch (error: unknown) {
+    throw new SecretSyncError({
+      error,
+      message: "Failed to update Northflank secrets"
+    });
+  }
+};
+
+export const NorthflankSyncFns = {
+  syncSecrets: async (secretSync: TNorthflankSyncWithCredentials, secretMap: TSecretMap): Promise<void> => {
+    const northflankSecrets = await getNorthflankSecrets(secretSync);
+
+    const updatedVariables: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(northflankSecrets)) {
+      const shouldKeep =
+        !secretMap[key] && // this prevents duplicates from infisical secrets, because we add all of them to the updateVariables in the next loop
+        (secretSync.syncOptions.disableSecretDeletion ||
+          !matchesSchema(key, secretSync.environment?.slug || "", secretSync.syncOptions.keySchema));
+
+      if (shouldKeep) {
+        updatedVariables[key] = value;
+      }
+    }
+
+    for (const [key, { value }] of Object.entries(secretMap)) {
+      updatedVariables[key] = value;
+    }
+
+    await updateNorthflankSecrets(secretSync, updatedVariables);
+  },
+
+  getSecrets: async (secretSync: TNorthflankSyncWithCredentials): Promise<TSecretMap> => {
+    const northflankSecrets = await getNorthflankSecrets(secretSync);
+    return Object.fromEntries(Object.entries(northflankSecrets).map(([key, value]) => [key, { value }]));
+  },
+
+  removeSecrets: async (secretSync: TNorthflankSyncWithCredentials, secretMap: TSecretMap): Promise<void> => {
+    const northflankSecrets = await getNorthflankSecrets(secretSync);
+
+    const updatedVariables: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(northflankSecrets)) {
+      if (!(key in secretMap)) {
+        updatedVariables[key] = value;
+      }
+    }
+
+    await updateNorthflankSecrets(secretSync, updatedVariables);
   }
 };

backend/src/services/secret-sync/northflank/northflank-sync-schemas.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import { SecretSyncs } from "@app/lib/api-docs";
 import { AppConnection } from "@app/services/app-connection/app-connection-enums";
 import { SecretSync } from "@app/services/secret-sync/secret-sync-enums";
 import {
@@ -10,8 +11,18 @@ import {
 import { TSyncOptionsConfig } from "@app/services/secret-sync/secret-sync-types";
 
 const NorthflankSyncDestinationConfigSchema = z.object({
-  // TODO: Will be implemented in the follow up secret sync PR
-  placeholder: z.string().optional()
+  projectId: z
+    .string()
+    .trim()
+    .min(1, "Project ID is required")
+    .describe(SecretSyncs.DESTINATION_CONFIG.NORTHFLANK.projectId),
+  projectName: z.string().trim().optional().describe(SecretSyncs.DESTINATION_CONFIG.NORTHFLANK.projectName),
+  secretGroupId: z
+    .string()
+    .trim()
+    .min(1, "Secret Group ID is required")
+    .describe(SecretSyncs.DESTINATION_CONFIG.NORTHFLANK.secretGroupId),
+  secretGroupName: z.string().trim().optional().describe(SecretSyncs.DESTINATION_CONFIG.NORTHFLANK.secretGroupName)
 });
 
 const NorthflankSyncOptionsConfig: TSyncOptionsConfig = { canImportSecrets: true };