System Architecture
Core Features
Data Management
Frontend Components
Extensibility
The following files were used as context for generating this wiki page:
This document outlines the execution flow initiated when a user attempts to test an integration connection from the IntegrationPlatformTestPage in the frontend. The core purpose of this flow is to securely retrieve and decrypt sensitive integration credentials (like API keys or OAuth tokens) from the backend's credential vault, enabling the system to verify the connection's validity.
The process begins with a user action in the browser, triggering an API call to the backend. The backend then fetches the encrypted credentials, decrypts them using a master secret key, and finally uses these plaintext credentials to perform the actual connection test. This secure handling ensures that sensitive information is never exposed directly to the frontend and is only decrypted when needed for operational purposes.
IntegrationPlatformTestPageThe execution begins on the IntegrationPlatformTestPage component, which is a React page responsible for rendering the user interface to manage and test integration connections. When a user navigates to this page, it loads and displays a list of available integration providers and existing connections.
When a user clicks the "Test" button associated with a specific connection, this action triggers the handleTestConnection function within this component. The page passes the unique connectionId and providerSlug of the selected connection to this handler. The primary role of this component in this flow is to initiate the client-side interaction that leads to the backend process.
Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:329-331
handleTestConnectionThe handleTestConnection function is an asynchronous client-side handler defined within the IntegrationPlatformTestPage. It is invoked when a user clicks the "Test" button for a particular integration connection.
This function takes the connectionId and providerSlug as arguments. Its main responsibility is to make an API call to the backend to initiate the actual connection test. It uses the testConnection mutation provided by the useIntegrationMutations hook (which internally uses api.post) to send an HTTP POST request to the backend's /v1/integrations/connections/:id/test endpoint. During this process, it updates the isLoading state to provide visual feedback to the user and logs the outcome (success or error message) to the frontend's action log.
Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:376-384
testConnectionThis method is a NestJS controller endpoint (@Post(':id/test')) within the ConnectionsController in the backend. It serves as the API entry point for testing an integration connection.
Upon receiving the POST request from the frontend, the method extracts the connectionId from the URL parameters. It first retrieves the Connection object from the database using this.connectionService.getConnection(id). The crucial step for credential access is then performed: it calls this.credentialVaultService.getDecryptedCredentials(connection.id) to obtain the plaintext credentials required for the test. Depending on the providerSlug (e.g., 'aws'), it might delegate to a specific testing method (this.testAwsConnection) or use a generic handler defined in the integration manifest. If the connection test is successful, it activates the connection; otherwise, it sets the connection to an error state with a descriptive message.
This method handles several potential errors:
HttpException.HttpException.this.connectionService.setConnectionError to update the connection's status in the database, providing user-facing error messages.Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:586-630
getDecryptedCredentialsThe getDecryptedCredentials method resides within the CredentialVaultService. Its purpose is to retrieve the latest encrypted credentials for a given connectionId and convert them into a usable, plaintext format.
This method takes the connectionId as input. It queries the credentialRepository to fetch the latestVersion of credentials associated with that connection. The retrieved latestVersion contains an encryptedPayload, which is a JSON object where sensitive values are stored as EncryptedData objects (containing encrypted, iv, tag, and salt as base64 strings). The method then iterates through this payload, calling this.decrypt() for each EncryptedData object to transform it back into its original plaintext string. Non-encrypted values are passed through directly. The final output is a Record<string, string | string[]> containing all decrypted credentials.
Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:241-274
decryptThe decrypt method is a private, core cryptographic function within the CredentialVaultService. It performs the actual decryption of a single piece of sensitive data.
This method accepts an EncryptedData object as input. It first calls this.getSecretKey() to retrieve the application's master encryption key. Using this key and the salt from the EncryptedData, it derives the specific cryptographic key required for decryption using scryptSync. It then initializes an aes-256-gcm decipher using createDecipheriv, sets the authentication tag (tag) to verify data integrity, and finally performs the decryption. The result is the original plaintext string.
Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:80-92
getSecretKeyThe getSecretKey method is a private helper function within the CredentialVaultService. Its sole responsibility is to retrieve the master encryption key required for cryptographic operations.
This method accesses the process.env.SECRET_KEY environment variable. This environment variable holds the critical secret key used to encrypt and decrypt all sensitive credentials stored in the vault.
This method is a critical failure point. If the SECRET_KEY environment variable is not set, the method will throw an Error, preventing any decryption operations and effectively rendering the credential vault unusable. This highlights the importance of proper environment configuration for security.
Sources: apps/api/src/integration-platform/services/credential-vault.service.ts:65-71
apps/app): Handles user interaction and initiates API requests.apps/api/src/integration-platform/controllers): Acts as the API gateway, receiving requests and orchestrating business logic.apps/api/src/integration-platform/services): Contains core business logic, such as credential management and cryptographic operations.CredentialVaultService): Abstracts database interactions for credential storage.SECRET_KEY: This is a critical configuration error that would prevent all decryption, leading to system-wide credential access failures.EncryptedData is tampered with or malformed, decryption will fail.ConnectionsController catches exceptions during the connection test and updates the connection's status in the database (setConnectionError), providing persistent feedback.CredentialVaultService.getSecretKey explicitly throws an error if the SECRET_KEY is not set, indicating a critical deployment issue.scryptSync, createDecipheriv) involved in decryption are CPU-intensive. While generally fast for individual credentials, decrypting a large number of credentials concurrently could introduce latency.