add gateway security docs

Revert "feat(api/secrets): view secret value permission"

.github/workflows/check-api-for-breaking-changes.yml

@@ -35,7 +35,20 @@ jobs:
           echo "SECRET_SCANNING_GIT_APP_ID=793712" >> .env
           echo "SECRET_SCANNING_PRIVATE_KEY=some-random" >> .env
           echo "SECRET_SCANNING_WEBHOOK_SECRET=some-random" >> .env
-          docker run --name infisical-api -d -p 4000:4000 -e DB_CONNECTION_URI=$DB_CONNECTION_URI -e REDIS_URL=$REDIS_URL -e JWT_AUTH_SECRET=$JWT_AUTH_SECRET -e ENCRYPTION_KEY=$ENCRYPTION_KEY --env-file .env --entrypoint '/bin/sh' infisical-api
+
+          echo "Examining built image:"
+          docker image inspect infisical-api | grep -A 5 "Entrypoint"
+          
+          docker run --name infisical-api -d -p 4000:4000 \
+            -e DB_CONNECTION_URI=$DB_CONNECTION_URI \
+            -e REDIS_URL=$REDIS_URL \
+            -e JWT_AUTH_SECRET=$JWT_AUTH_SECRET \
+            -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
+            --env-file .env \
+            infisical-api
+          
+          echo "Container status right after creation:"
+          docker ps -a | grep infisical-api
         env:
           REDIS_URL: redis://172.17.0.1:6379
           DB_CONNECTION_URI: postgres://infisical:infisical@172.17.0.1:5432/infisical?sslmode=disable
@@ -49,21 +62,33 @@ jobs:
           SECONDS=0
           HEALTHY=0
           while [ $SECONDS -lt 60 ]; do
-            if docker ps | grep infisical-api | grep -q healthy; then
-              echo "Container is healthy."
-              HEALTHY=1
+            # Check if container is running
+            if docker ps | grep infisical-api; then
+              # Try to access the API endpoint
+              if curl -s -f http://localhost:4000/api/docs/json > /dev/null 2>&1; then
+                echo "API endpoint is responding. Container seems healthy."
+                HEALTHY=1
+                break
+              fi
+            else
+              echo "Container is not running!"
+              docker ps -a | grep infisical-api
               break
             fi
+            
             echo "Waiting for container to be healthy... ($SECONDS seconds elapsed)"
-
-            docker logs infisical-api
-
-            sleep 2
-            SECONDS=$((SECONDS+2))
+            sleep 5
+            SECONDS=$((SECONDS+5))
           done
-
+          
           if [ $HEALTHY -ne 1 ]; then
             echo "Container did not become healthy in time"
+            echo "Container status:"
+            docker ps -a | grep infisical-api
+            echo "Container logs (if any):"
+            docker logs infisical-api || echo "No logs available"
+            echo "Container inspection:"
+            docker inspect infisical-api | grep -A 5 "State"
             exit 1
           fi
       - name: Install openapi-diff
@@ -71,7 +96,8 @@ jobs:
       - name: Running OpenAPI Spec diff action
         run: oasdiff breaking https://app.infisical.com/api/docs/json http://localhost:4000/api/docs/json --fail-on ERR
       - name: cleanup
+        if: always()
         run: |
           docker compose -f "docker-compose.dev.yml" down
-          docker stop infisical-api
-          docker remove infisical-api
+          docker stop infisical-api || true
+          docker rm infisical-api || true

backend/src/db/migrations/20250305080145_add-secret-review-comment.ts

@@ -0,0 +1,19 @@
+import { Knex } from "knex";
+
+import { TableName } from "../schemas";
+
+export async function up(knex: Knex): Promise<void> {
+  if (!(await knex.schema.hasColumn(TableName.SecretApprovalRequestReviewer, "comment"))) {
+    await knex.schema.alterTable(TableName.SecretApprovalRequestReviewer, (t) => {
+      t.string("comment");
+    });
+  }
+}
+
+export async function down(knex: Knex): Promise<void> {
+  if (await knex.schema.hasColumn(TableName.SecretApprovalRequestReviewer, "comment")) {
+    await knex.schema.alterTable(TableName.SecretApprovalRequestReviewer, (t) => {
+      t.dropColumn("comment");
+    });
+  }
+}

backend/src/db/schemas/secret-approval-requests-reviewers.ts

@@ -13,7 +13,8 @@ export const SecretApprovalRequestsReviewersSchema = z.object({
   requestId: z.string().uuid(),
   createdAt: z.date(),
   updatedAt: z.date(),
-  reviewerUserId: z.string().uuid()
+  reviewerUserId: z.string().uuid(),
+  comment: z.string().nullable().optional()
 });
 
 export type TSecretApprovalRequestsReviewers = z.infer<typeof SecretApprovalRequestsReviewersSchema>;

backend/src/ee/routes/v1/secret-approval-request-router.ts

@@ -159,7 +159,8 @@ export const registerSecretApprovalRequestRouter = async (server: FastifyZodProv
         id: z.string()
       }),
       body: z.object({
-        status: z.enum([ApprovalStatus.APPROVED, ApprovalStatus.REJECTED])
+        status: z.enum([ApprovalStatus.APPROVED, ApprovalStatus.REJECTED]),
+        comment: z.string().optional()
       }),
       response: {
         200: z.object({
@@ -175,8 +176,25 @@ export const registerSecretApprovalRequestRouter = async (server: FastifyZodProv
         actorAuthMethod: req.permission.authMethod,
         actorOrgId: req.permission.orgId,
         approvalId: req.params.id,
-        status: req.body.status
+        status: req.body.status,
+        comment: req.body.comment
       });
+
+      await server.services.auditLog.createAuditLog({
+        ...req.auditLogInfo,
+        orgId: req.permission.orgId,
+        projectId: review.projectId,
+        event: {
+          type: EventType.SECRET_APPROVAL_REQUEST_REVIEW,
+          metadata: {
+            secretApprovalRequestId: review.requestId,
+            reviewedBy: review.reviewerUserId,
+            status: review.status as ApprovalStatus,
+            comment: review.comment || ""
+          }
+        }
+      });
+
       return { review };
     }
   });
@@ -267,7 +285,7 @@ export const registerSecretApprovalRequestRouter = async (server: FastifyZodProv
               environment: z.string(),
               statusChangedByUser: approvalRequestUser.optional(),
               committerUser: approvalRequestUser,
-              reviewers: approvalRequestUser.extend({ status: z.string() }).array(),
+              reviewers: approvalRequestUser.extend({ status: z.string(), comment: z.string().optional() }).array(),
               secretPath: z.string(),
               commits: secretRawSchema
                 .omit({ _id: true, environment: true, workspace: true, type: true, version: true })

backend/src/ee/services/audit-log/audit-log-types.ts

@@ -22,6 +22,7 @@ import {
 } from "@app/services/secret-sync/secret-sync-types";
 
 import { KmipPermission } from "../kmip/kmip-enum";
+import { ApprovalStatus } from "../secret-approval-request/secret-approval-request-types";
 
 export type TListProjectAuditLogDTO = {
   filter: {
@@ -165,6 +166,7 @@ export enum EventType {
   SECRET_APPROVAL_REQUEST = "secret-approval-request",
   SECRET_APPROVAL_CLOSED = "secret-approval-closed",
   SECRET_APPROVAL_REOPENED = "secret-approval-reopened",
+  SECRET_APPROVAL_REQUEST_REVIEW = "secret-approval-request-review",
   SIGN_SSH_KEY = "sign-ssh-key",
   ISSUE_SSH_CREDS = "issue-ssh-creds",
   CREATE_SSH_CA = "create-ssh-certificate-authority",
@@ -1314,6 +1316,16 @@ interface SecretApprovalRequest {
   };
 }
 
+interface SecretApprovalRequestReview {
+  type: EventType.SECRET_APPROVAL_REQUEST_REVIEW;
+  metadata: {
+    secretApprovalRequestId: string;
+    reviewedBy: string;
+    status: ApprovalStatus;
+    comment: string;
+  };
+}
+
 interface SignSshKey {
   type: EventType.SIGN_SSH_KEY;
   metadata: {
@@ -2482,4 +2494,5 @@ export type Event =
   | KmipOperationRevokeEvent
   | KmipOperationLocateEvent
   | KmipOperationRegisterEvent
-  | CreateSecretRequestEvent;
+  | CreateSecretRequestEvent
+  | SecretApprovalRequestReview;

backend/src/ee/services/secret-approval-request/secret-approval-request-dal.ts

@@ -100,6 +100,7 @@ export const secretApprovalRequestDALFactory = (db: TDbClient) => {
         tx.ref("lastName").withSchema("committerUser").as("committerUserLastName"),
         tx.ref("reviewerUserId").withSchema(TableName.SecretApprovalRequestReviewer),
         tx.ref("status").withSchema(TableName.SecretApprovalRequestReviewer).as("reviewerStatus"),
+        tx.ref("comment").withSchema(TableName.SecretApprovalRequestReviewer).as("reviewerComment"),
         tx.ref("email").withSchema("secretApprovalReviewerUser").as("reviewerEmail"),
         tx.ref("username").withSchema("secretApprovalReviewerUser").as("reviewerUsername"),
         tx.ref("firstName").withSchema("secretApprovalReviewerUser").as("reviewerFirstName"),
@@ -162,8 +163,10 @@ export const secretApprovalRequestDALFactory = (db: TDbClient) => {
               reviewerEmail: email,
               reviewerLastName: lastName,
               reviewerUsername: username,
-              reviewerFirstName: firstName
-            }) => (userId ? { userId, status, email, firstName, lastName, username } : undefined)
+              reviewerFirstName: firstName,
+              reviewerComment: comment
+            }) =>
+              userId ? { userId, status, email, firstName, lastName, username, comment: comment ?? "" } : undefined
           },
           {
             key: "approverUserId",

backend/src/ee/services/secret-approval-request/secret-approval-request-service.ts

@@ -320,6 +320,7 @@ export const secretApprovalRequestServiceFactory = ({
     approvalId,
     actor,
     status,
+    comment,
     actorId,
     actorAuthMethod,
     actorOrgId
@@ -372,15 +373,18 @@ export const secretApprovalRequestServiceFactory = ({
         return secretApprovalRequestReviewerDAL.create(
           {
             status,
+            comment,
             requestId: secretApprovalRequest.id,
             reviewerUserId: actorId
           },
           tx
         );
       }
-      return secretApprovalRequestReviewerDAL.updateById(review.id, { status }, tx);
+
+      return secretApprovalRequestReviewerDAL.updateById(review.id, { status, comment }, tx);
     });
-    return reviewStatus;
+
+    return { ...reviewStatus, projectId: secretApprovalRequest.projectId };
   };
 
   const updateApprovalStatus = async ({

backend/src/ee/services/secret-approval-request/secret-approval-request-types.ts

@@ -80,6 +80,7 @@ export type TStatusChangeDTO = {
 export type TReviewRequestDTO = {
   approvalId: string;
   status: ApprovalStatus;
+  comment?: string;
 } & Omit<TProjectPermission, "projectId">;
 
 export type TApprovalRequestCountDTO = TProjectPermission;

backend/src/lib/gateway/index.ts

@@ -2,7 +2,7 @@
 import crypto from "node:crypto";
 import net from "node:net";
 
-import * as quic from "@infisical/quic";
+import quicDefault, * as quicModule from "@infisical/quic";
 
 import { BadRequestError } from "../errors";
 import { logger } from "../logger";
@@ -10,6 +10,8 @@ import { logger } from "../logger";
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_RETRY_DELAY = 1000; // 1 second
 
+const quic = quicDefault || quicModule;
+
 const parseSubjectDetails = (data: string) => {
   const values: Record<string, string> = {};
   data.split("\n").forEach((el) => {

cli/config/example-infisical-relay.yaml

@@ -0,0 +1,8 @@
+public_ip: 127.0.0.1
+auth_secret: example-auth-secret
+realm: infisical.org
+# set port 5349 for tls
+# port: 5349
+# tls_private_key_path: /full-path
+# tls_ca_path:  /full-path
+# tls_cert_path: /full-path

cli/go.mod

@@ -28,8 +28,9 @@ require (
 	github.com/rs/zerolog v1.26.1
 	github.com/spf13/cobra v1.6.1
 	github.com/spf13/viper v1.8.1
-	github.com/stretchr/testify v1.9.0
+	github.com/stretchr/testify v1.10.0
 	golang.org/x/crypto v0.35.0
+	golang.org/x/sys v0.30.0
 	golang.org/x/term v0.29.0
 	gopkg.in/yaml.v2 v2.4.0
 )
@@ -115,7 +116,6 @@ require (
 	golang.org/x/net v0.35.0 // indirect
 	golang.org/x/oauth2 v0.21.0 // indirect
 	golang.org/x/sync v0.11.0 // indirect
-	golang.org/x/sys v0.30.0 // indirect
 	golang.org/x/text v0.22.0 // indirect
 	golang.org/x/time v0.6.0 // indirect
 	golang.org/x/tools v0.30.0 // indirect
@@ -139,3 +139,5 @@ require (
 )
 
 replace github.com/zalando/go-keyring => github.com/Infisical/go-keyring v1.0.2
+
+replace github.com/pion/turn/v4 => github.com/Infisical/turn/v4 v4.0.1

cli/go.sum

@@ -49,6 +49,8 @@ github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03
 github.com/BurntSushi/xgb v0.0.0-20160522181843-27f122750802/go.mod h1:IVnqGOEym/WlBOVXweHU+Q+/VP0lqqI8lqeDx9IjBqo=
 github.com/Infisical/go-keyring v1.0.2 h1:dWOkI/pB/7RocfSJgGXbXxLDcVYsdslgjEPmVhb+nl8=
 github.com/Infisical/go-keyring v1.0.2/go.mod h1:LWOnn/sw9FxDW/0VY+jHFAfOFEe03xmwBVSfJnBowto=
+github.com/Infisical/turn/v4 v4.0.1 h1:omdelNsnFfzS5cu86W5OBR68by68a8sva4ogR0lQQnw=
+github.com/Infisical/turn/v4 v4.0.1/go.mod h1:pMMKP/ieNAG/fN5cZiN4SDuyKsXtNTr0ccN7IToA1zs=
 github.com/alessio/shellescape v1.4.1 h1:V7yhSDDn8LP4lc4jS8pFkt0zCnzVJlG5JXy9BVKJUX0=
 github.com/alessio/shellescape v1.4.1/go.mod h1:PZAiSCk0LJaZkiCSkPv8qIobYglO3FPpyFjDCtHLS30=
 github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY=
@@ -365,8 +367,6 @@ github.com/pion/stun/v3 v3.0.0 h1:4h1gwhWLWuZWOJIJR9s2ferRO+W3zA/b6ijOI6mKzUw=
 github.com/pion/stun/v3 v3.0.0/go.mod h1:HvCN8txt8mwi4FBvS3EmDghW6aQJ24T+y+1TKjB5jyU=
 github.com/pion/transport/v3 v3.0.7 h1:iRbMH05BzSNwhILHoBoAPxoB9xQgOaJk+591KC9P1o0=
 github.com/pion/transport/v3 v3.0.7/go.mod h1:YleKiTZ4vqNxVwh77Z0zytYi7rXHl7j6uPLGhhz9rwo=
-github.com/pion/turn/v4 v4.0.0 h1:qxplo3Rxa9Yg1xXDxxH8xaqcyGUtbHYw4QSCvmFWvhM=
-github.com/pion/turn/v4 v4.0.0/go.mod h1:MuPDkm15nYSklKpN8vWJ9W2M0PlyQZqYt1McGuxG7mA=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
@@ -425,8 +425,8 @@ github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
-github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
-github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/subosito/gotenv v1.2.0 h1:Slr1R9HxAlEKefgq5jn9U+DnETlIUa6HfgEzj0g5d7s=
 github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw=
 github.com/tidwall/pretty v1.0.0 h1:HsD+QiTn7sK6flMKIvNmpqz1qrpP3Ps6jOKIKMooyg4=

cli/packages/cmd/gateway.go

@@ -137,15 +137,10 @@ var gatewayRelayCmd = &cobra.Command{
 }
 
 func init() {
-	gatewayCmd.SetHelpFunc(func(command *cobra.Command, strings []string) {
-		command.Flags().MarkHidden("domain")
-		command.Parent().HelpFunc()(command, strings)
-	})
 	gatewayCmd.Flags().String("token", "", "Connect with Infisical using machine identity access token")
 
 	gatewayRelayCmd.Flags().String("config", "", "Relay config yaml file path")
 
 	gatewayCmd.AddCommand(gatewayRelayCmd)
-
 	rootCmd.AddCommand(gatewayCmd)
 }

cli/packages/gateway/gateway.go

@@ -176,7 +176,7 @@ func (g *Gateway) Listen(ctx context.Context) error {
 		KeepAlivePeriod: 2 * time.Second,
 	}
 
-	g.registerRelayIsActive(ctx, relayUdpConnection.LocalAddr().String(), errCh)
+	g.registerRelayIsActive(ctx, errCh)
 	quicListener, err := quic.Listen(relayUdpConnection, tlsConfig, quicConfig)
 	if err != nil {
 		return fmt.Errorf("Failed to listen for QUIC: %w", err)
@@ -320,39 +320,49 @@ func (g *Gateway) createPermissionForStaticIps(staticIps string) error {
 	return nil
 }
 
-func (g *Gateway) registerRelayIsActive(ctx context.Context, relayAddress string, errCh chan error) error {
-	ticker := time.NewTicker(10 * time.Second)
+func (g *Gateway) registerRelayIsActive(ctx context.Context, errCh chan error) error {
+	ticker := time.NewTicker(15 * time.Second)
 	maxFailures := 3
 	failures := 0
 
+	log.Info().Msg("Starting relay connection health check")
+
 	go func() {
-		time.Sleep(2 * time.Second)
+		time.Sleep(5 * time.Second)
 		for {
 			select {
 			case <-ctx.Done():
+				log.Info().Msg("Stopping relay connection health check")
 				return
 			case <-ticker.C:
-				// Configure TLS to skip verification
-				tlsConfig := &tls.Config{
-					InsecureSkipVerify: true,
-					NextProtos:         []string{"infisical-gateway"},
-				}
-				quicConfig := &quic.Config{
-					EnableDatagrams: true,
-				}
 				func() {
-					checkCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
-					defer cancel()
-					conn, err := quic.DialAddr(checkCtx, relayAddress, tlsConfig, quicConfig)
-					if err != nil {
+					log.Debug().Msg("Performing relay connection health check")
+
+					if g.client == nil {
 						failures++
-						log.Warn().Err(err).Int("failures", failures).Msg("Relay connection check failed")
+						log.Warn().Int("failures", failures).Msg("TURN client is nil")
+						if failures >= maxFailures {
+							errCh <- fmt.Errorf("relay connection check failed: TURN client is nil")
+						}
+						return
+					}
+
+					// we try to refresh permissions - this is a lightweight operation
+					// that will fail immediately if the UDP connection is broken. good for health check
+					log.Debug().Msg("Refreshing TURN permissions to verify connection")
+					if err := g.createPermissionForStaticIps(g.config.InfisicalStaticIp); err != nil {
+						failures++
+						log.Warn().Err(err).Int("failures", failures).Msg("Failed to refresh TURN permissions")
 						if failures >= maxFailures {
 							errCh <- fmt.Errorf("relay connection check failed: %w", err)
 						}
+						return
 					}
-					if conn != nil {
-						conn.CloseWithError(0, "closed")
+
+					log.Debug().Msg("Successfully refreshed TURN permissions - connection is healthy")
+					if failures > 0 {
+						log.Info().Int("previous_failures", failures).Msg("Relay connection restored")
+						failures = 0
 					}
 				}()
 			}

cli/packages/gateway/relay.go

@@ -1,3 +1,6 @@
+//go:build !windows
+// +build !windows
+
 package gateway
 
 import (

cli/packages/gateway/relay_windows.go

@@ -0,0 +1,37 @@
+//go:build windows
+// +build windows
+
+package gateway
+
+import (
+	"errors"
+)
+
+var (
+	errMissingTlsCert      = errors.New("Missing TLS files")
+	errWindowsNotSupported = errors.New("Relay is not supported on Windows")
+)
+
+type GatewayRelay struct {
+	Config *GatewayRelayConfig
+}
+
+type GatewayRelayConfig struct {
+	PublicIP          string
+	Port              int
+	Realm             string
+	AuthSecret        string
+	RelayMinPort      uint16
+	RelayMaxPort      uint16
+	TlsCertPath       string
+	TlsPrivateKeyPath string
+	TlsCaPath         string
+}
+
+func NewGatewayRelay(configFilePath string) (*GatewayRelay, error) {
+	return nil, errWindowsNotSupported
+}
+
+func (g *GatewayRelay) Run() error {
+	return errWindowsNotSupported
+}

docs/documentation/platform/gateways/gateway-security.mdx

@@ -0,0 +1,110 @@
+---
+title: "Gateway Security Architecture"
+sidebarTitle: "Architecture"
+description: "Understand the security model and tenant isolation of Infisical's Gateway"
+---
+
+# Gateway Security Architecture
+
+The Infisical Gateway enables Infisical Cloud to securely interact with private resources using mutual TLS authentication and private PKI (Public Key Infrastructure) system to ensure secure, isolated communication between multiple tenants. 
+This document explains the internal security architecture and how tenant isolation is maintained.
+
+## Security Model Overview
+
+### Private PKI System
+Each organization (tenant) in Infisical has its own private PKI system consisting of:
+
+1. **Root CA**: The ultimate trust anchor for the organization
+2. **Intermediate CAs**:
+   - Client CA: Issues certificates for cloud components
+   - Gateway CA: Issues certificates for gateway instances
+
+This hierarchical structure ensures complete isolation between organizations as each has its own independent certificate chain.
+
+### Certificate Hierarchy
+```
+Root CA (Organization Specific)
+├── Client CA
+│   └── Client Certificates (Cloud Components)
+└── Gateway CA
+    └── Gateway Certificates (Gateway Instances)
+```
+
+## Communication Security
+
+### 1. Gateway Registration
+When a gateway is first deployed:
+
+1. Establishes initial connection using machine identity token
+2. Allocates a relay address for communication
+3. Exchanges certificates through a secure handshake:
+   - Gateway receives a unique certificate signed by organization's Gateway CA along with certificate chain for verification
+
+### 2. Mutual TLS Authentication
+All communication between gateway and cloud uses mutual TLS (mTLS):
+
+- **Gateway Authentication**:
+  - Presents certificate signed by organization's Gateway CA
+  - Certificate contains unique identifiers (Organization ID, Gateway ID)
+  - Cloud validates complete certificate chain
+
+- **Cloud Authentication**:
+  - Presents certificate signed by organization's Client CA
+  - Certificate includes required organizational unit ("gateway-client")
+  - Gateway validates certificate chain back to organization's root CA
+
+### 3. Relay Communication
+The relay system provides secure tunneling:
+
+1. **Connection Establishment**:
+   - Uses QUIC protocol over UDP for efficient, secure communication
+   - Provides built-in encryption, congestion control, and multiplexing
+   - Enables faster connection establishment and reduced latency
+   - Each organization's traffic is isolated using separate relay sessions
+
+2. **Traffic Isolation**:
+   - Each gateway gets unique relay credentials
+   - Traffic is end-to-end encrypted using QUIC's TLS 1.3
+   - Organization's private keys never leave their environment
+
+## Tenant Isolation
+
+### Certificate-Based Isolation
+- Each organization has unique root CA and intermediate CAs
+- Certificates contain organization-specific identifiers
+- Cross-tenant communication is cryptographically impossible
+
+### Gateway-Project Mapping
+- Gateways are explicitly mapped to specific projects
+- Access controls enforce organization boundaries
+- Project-level permissions determine resource accessibility
+
+### Resource Access Control
+1. **Project Verification**:
+   - Gateway verifies project membership
+   - Validates organization ownership
+   - Enforces project-level permissions
+
+2. **Resource Restrictions**:
+   - Gateways only accept connections to approved resources
+   - Each connection requires explicit project authorization
+   - Resources remain private to their assigned organization
+
+## Security Measures
+
+### Certificate Lifecycle
+- Certificates have limited validity periods
+- Automatic certificate rotation
+- Immediate certificate revocation capabilities
+
+### Monitoring and Verification
+1. **Continuous Verification**:
+   - Regular heartbeat checks
+   - Certificate chain validation
+   - Connection state monitoring
+
+2. **Security Controls**:
+   - Automatic connection termination on verification failure
+   - Audit logging of all access attempts
+   - Machine identity based authentication
+

docs/mint.json

@@ -203,7 +203,7 @@
         },
         {
           "group": "Gateway",
-          "pages": ["documentation/platform/gateways/overview"]
+          "pages": ["documentation/platform/gateways/overview", "documentation/platform/gateways/gateway-security"]
         },
         "documentation/platform/project-templates",
         {

frontend/src/hooks/api/auditLogs/constants.tsx

@@ -122,6 +122,7 @@ export const eventToNameMap: { [K in EventType]: string } = {
     "OIDC group membership mapping assigned user to groups",
   [EventType.OIDC_GROUP_MEMBERSHIP_MAPPING_REMOVE_USER]:
     "OIDC group membership mapping removed user from groups",
+  [EventType.SECRET_APPROVAL_REQUEST_REVIEW]: "Review Secret Approval Request",
   [EventType.CREATE_KMIP_CLIENT]: "Create KMIP client",
   [EventType.UPDATE_KMIP_CLIENT]: "Update KMIP client",
   [EventType.DELETE_KMIP_CLIENT]: "Delete KMIP client",

frontend/src/hooks/api/auditLogs/enums.tsx

@@ -150,5 +150,6 @@ export enum EventType {
   KMIP_OPERATION_ACTIVATE = "kmip-operation-activate",
   KMIP_OPERATION_REVOKE = "kmip-operation-revoke",
   KMIP_OPERATION_LOCATE = "kmip-operation-locate",
-  KMIP_OPERATION_REGISTER = "kmip-operation-register"
+  KMIP_OPERATION_REGISTER = "kmip-operation-register",
+  SECRET_APPROVAL_REQUEST_REVIEW = "secret-approval-request-review"
 }

frontend/src/hooks/api/secretApprovalRequest/mutation.tsx

@@ -13,9 +13,10 @@ export const useUpdateSecretApprovalReviewStatus = () => {
   const queryClient = useQueryClient();
 
   return useMutation<object, object, TUpdateSecretApprovalReviewStatusDTO>({
-    mutationFn: async ({ id, status }) => {
+    mutationFn: async ({ id, status, comment }) => {
       const { data } = await apiRequest.post(`/api/v1/secret-approval-requests/${id}/review`, {
-        status
+        status,
+        comment
       });
       return data;
     },

frontend/src/hooks/api/secretApprovalRequest/types.ts

@@ -44,6 +44,7 @@ export type TSecretApprovalRequest = {
   reviewers: {
     userId: string;
     status: ApprovalStatus;
+    comment: string;
     email: string;
     firstName: string;
     lastName: string;
@@ -114,6 +115,7 @@ export type TGetSecretApprovalRequestDetails = {
 
 export type TUpdateSecretApprovalReviewStatusDTO = {
   status: ApprovalStatus;
+  comment?: string;
   id: string;
 };
 

frontend/src/pages/secret-manager/SecretApprovalsPage/components/SecretApprovalRequest/components/SecretApprovalRequestChanges.tsx

@@ -1,19 +1,36 @@
 import { ReactNode } from "react";
+import { Controller, useForm } from "react-hook-form";
 import {
+  faAngleDown,
   faArrowLeft,
-  faCheck,
   faCheckCircle,
   faCircle,
   faCodeBranch,
+  faComment,
   faFolder,
   faXmarkCircle
 } from "@fortawesome/free-solid-svg-icons";
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { RadioGroup, RadioGroupIndicator, RadioGroupItem } from "@radix-ui/react-radio-group";
 import { twMerge } from "tailwind-merge";
+import z from "zod";
 
 import { createNotification } from "@app/components/notifications";
-import { Button, ContentLoader, EmptyState, IconButton, Tooltip } from "@app/components/v2";
+import {
+  Button,
+  ContentLoader,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+  EmptyState,
+  FormControl,
+  IconButton,
+  TextArea,
+  Tooltip
+} from "@app/components/v2";
 import { useUser } from "@app/context";
+import { usePopUp } from "@app/hooks";
 import {
   useGetSecretApprovalRequestDetails,
   useUpdateSecretApprovalReviewStatus
@@ -74,6 +91,13 @@ type Props = {
   onGoBack: () => void;
 };
 
+const reviewFormSchema = z.object({
+  comment: z.string().trim().optional().default(""),
+  status: z.nativeEnum(ApprovalStatus)
+});
+
+type TReviewFormSchema = z.infer<typeof reviewFormSchema>;
+
 export const SecretApprovalRequestChanges = ({
   approvalRequestId,
   onGoBack,
@@ -94,6 +118,16 @@ export const SecretApprovalRequestChanges = ({
     variables
   } = useUpdateSecretApprovalReviewStatus();
 
+  const { popUp, handlePopUpToggle } = usePopUp(["reviewChanges"] as const);
+  const {
+    control,
+    handleSubmit,
+    reset,
+    formState: { isSubmitting }
+  } = useForm<TReviewFormSchema>({
+    resolver: zodResolver(reviewFormSchema)
+  });
+
   const isApproving = variables?.status === ApprovalStatus.APPROVED && isUpdatingRequestStatus;
   const isRejecting = variables?.status === ApprovalStatus.REJECTED && isUpdatingRequestStatus;
 
@@ -101,23 +135,23 @@ export const SecretApprovalRequestChanges = ({
   const canApprove = secretApprovalRequestDetails?.policy?.approvers?.some(
     ({ userId }) => userId === userSession.id
   );
+
   const reviewedUsers = secretApprovalRequestDetails?.reviewers?.reduce<
-    Record<string, ApprovalStatus>
+    Record<string, { status: ApprovalStatus; comment: string }>
   >(
     (prev, curr) => ({
       ...prev,
-      [curr.userId]: curr.status
+      [curr.userId]: { status: curr.status, comment: curr.comment }
     }),
     {}
   );
-  const hasApproved = reviewedUsers?.[userSession.id] === ApprovalStatus.APPROVED;
-  const hasRejected = reviewedUsers?.[userSession.id] === ApprovalStatus.REJECTED;
 
-  const handleSecretApprovalStatusUpdate = async (status: ApprovalStatus) => {
+  const handleSecretApprovalStatusUpdate = async (status: ApprovalStatus, comment: string) => {
     try {
       await updateSecretApprovalRequestStatus({
         id: approvalRequestId,
-        status
+        status,
+        comment
       });
       createNotification({
         type: "success",
@@ -130,6 +164,16 @@ export const SecretApprovalRequestChanges = ({
         text: "Failed to update the request status"
       });
     }
+
+    handlePopUpToggle("reviewChanges", false);
+    reset({
+      comment: "",
+      status: ApprovalStatus.APPROVED
+    });
+  };
+
+  const handleSubmitReview = (data: TReviewFormSchema) => {
+    handleSecretApprovalStatusUpdate(data.status, data.comment);
   };
 
   if (isSecretApprovalRequestLoading) {
@@ -150,7 +194,7 @@ export const SecretApprovalRequestChanges = ({
   const isMergable =
     secretApprovalRequestDetails?.policy?.approvals <=
     secretApprovalRequestDetails?.policy?.approvers?.filter(
-      ({ userId }) => reviewedUsers?.[userId] === ApprovalStatus.APPROVED
+      ({ userId }) => reviewedUsers?.[userId]?.status === ApprovalStatus.APPROVED
     ).length;
   const hasMerged = secretApprovalRequestDetails?.hasMerged;
 
@@ -202,27 +246,115 @@ export const SecretApprovalRequestChanges = ({
             </div>
           </div>
           {!hasMerged && secretApprovalRequestDetails.status === "open" && (
-            <>
-              <Button
-                size="xs"
-                leftIcon={hasApproved && <FontAwesomeIcon icon={faCheck} />}
-                onClick={() => handleSecretApprovalStatusUpdate(ApprovalStatus.APPROVED)}
-                isLoading={isApproving}
-                isDisabled={isApproving || hasApproved || !canApprove}
-              >
-                {hasApproved ? "Approved" : "Approve"}
-              </Button>
-              <Button
-                size="xs"
-                colorSchema="danger"
-                leftIcon={hasRejected && <FontAwesomeIcon icon={faCheck} />}
-                onClick={() => handleSecretApprovalStatusUpdate(ApprovalStatus.REJECTED)}
-                isLoading={isRejecting}
-                isDisabled={isRejecting || hasRejected || !canApprove}
-              >
-                {hasRejected ? "Rejected" : "Reject"}
-              </Button>
-            </>
+            <DropdownMenu
+              open={popUp.reviewChanges.isOpen}
+              onOpenChange={(isOpen) => handlePopUpToggle("reviewChanges", isOpen)}
+            >
+              <DropdownMenuTrigger asChild>
+                <Button
+                  variant="outline_bg"
+                  rightIcon={<FontAwesomeIcon className="ml-2" icon={faAngleDown} />}
+                >
+                  Review
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" asChild className="mt-3">
+                <form onSubmit={handleSubmit(handleSubmitReview)}>
+                  <div className="flex w-[400px] flex-col space-y-2 p-5">
+                    <div className="text-lg font-medium">Finish your review</div>
+                    <Controller
+                      control={control}
+                      name="comment"
+                      render={({ field, fieldState: { error } }) => (
+                        <FormControl errorText={error?.message} isError={Boolean(error)}>
+                          <TextArea
+                            {...field}
+                            placeholder="Leave a comment..."
+                            reSize="none"
+                            className="text-md mt-2 h-48 border border-mineshaft-600 bg-bunker-800"
+                          />
+                        </FormControl>
+                      )}
+                    />
+                    <Controller
+                      control={control}
+                      name="status"
+                      defaultValue={ApprovalStatus.APPROVED}
+                      render={({ field, fieldState: { error } }) => (
+                        <FormControl errorText={error?.message} isError={Boolean(error)}>
+                          <RadioGroup
+                            value={field.value}
+                            onValueChange={field.onChange}
+                            className="mb-4 space-y-2"
+                            aria-label="Status"
+                          >
+                            <div className="flex items-center gap-2">
+                              <RadioGroupItem
+                                id="approve"
+                                className="h-4 w-4 rounded-full border border-gray-300 text-primary focus:ring-2 focus:ring-mineshaft-500"
+                                value={ApprovalStatus.APPROVED}
+                                aria-labelledby="approve-label"
+                              >
+                                <RadioGroupIndicator className="flex h-full w-full items-center justify-center after:h-2 after:w-2 after:rounded-full after:bg-current" />
+                              </RadioGroupItem>
+                              <span
+                                id="approve-label"
+                                className="cursor-pointer"
+                                onClick={() => field.onChange(ApprovalStatus.APPROVED)}
+                                onKeyDown={(e) => {
+                                  if (e.key === "Enter" || e.key === " ") {
+                                    e.preventDefault();
+                                    field.onChange(ApprovalStatus.APPROVED);
+                                  }
+                                }}
+                                tabIndex={0}
+                                role="button"
+                              >
+                                Approve
+                              </span>
+                            </div>
+                            <div className="flex items-center gap-2">
+                              <RadioGroupItem
+                                id="reject"
+                                className="h-4 w-4 rounded-full border border-gray-300 text-primary focus:ring-2 focus:ring-mineshaft-500"
+                                value={ApprovalStatus.REJECTED}
+                                aria-labelledby="reject-label"
+                              >
+                                <RadioGroupIndicator className="flex h-full w-full items-center justify-center after:h-2 after:w-2 after:rounded-full after:bg-current" />
+                              </RadioGroupItem>
+                              <span
+                                id="reject-label"
+                                className="cursor-pointer"
+                                onClick={() => field.onChange(ApprovalStatus.REJECTED)}
+                                onKeyDown={(e) => {
+                                  if (e.key === "Enter" || e.key === " ") {
+                                    e.preventDefault();
+                                    field.onChange(ApprovalStatus.REJECTED);
+                                  }
+                                }}
+                                tabIndex={0}
+                                role="button"
+                              >
+                                Reject
+                              </span>
+                            </div>
+                          </RadioGroup>
+                        </FormControl>
+                      )}
+                    />
+                    <div className="flex justify-end">
+                      <Button
+                        type="submit"
+                        isLoading={isApproving || isRejecting || isSubmitting}
+                        variant="outline_bg"
+                      >
+                        Submit Review
+                      </Button>
+                    </div>
+                  </div>
+                </form>
+              </DropdownMenuContent>
+            </DropdownMenu>
           )}
         </div>
         <div className="flex flex-col space-y-4">
@@ -240,7 +372,40 @@ export const SecretApprovalRequestChanges = ({
             )
           )}
         </div>
-        <div className="mt-8 flex items-center space-x-6 rounded-lg bg-mineshaft-800 px-5 py-6">
+        <div className="mt-4 flex flex-col items-center rounded-lg">
+          {secretApprovalRequestDetails?.policy?.approvers
+            .filter((requiredApprover) => reviewedUsers?.[requiredApprover.userId])
+            .map((requiredApprover) => {
+              const reviewer = reviewedUsers?.[requiredApprover.userId];
+              return (
+                <div
+                  className="mb-4 flex w-full flex-col rounded-md bg-mineshaft-800 p-6"
+                  key={`required-approver-${requiredApprover.userId}`}
+                >
+                  <div>
+                    <span className="ml-1">
+                      {`${requiredApprover.firstName || ""} ${requiredApprover.lastName || ""}`} (
+                      {requiredApprover?.email}) has{" "}
+                    </span>
+                    <span
+                      className={`${reviewer?.status === ApprovalStatus.APPROVED ? "text-green-500" : "text-red-500"}`}
+                    >
+                      {reviewer?.status === ApprovalStatus.APPROVED ? "approved" : "rejected"}
+                    </span>{" "}
+                    the request.
+                  </div>
+                  {reviewer?.comment && (
+                    <FormControl label="Comment" className="mb-0 mt-2">
+                      <TextArea value={reviewer.comment} isDisabled reSize="none">
+                        {reviewer?.comment && reviewer.comment}
+                      </TextArea>
+                    </FormControl>
+                  )}
+                </div>
+              );
+            })}
+        </div>
+        <div className="flex items-center space-x-6 rounded-lg bg-mineshaft-800 px-5 py-6">
           <SecretApprovalRequestAction
             canApprove={canApprove}
             approvalRequestId={secretApprovalRequestDetails.id}
@@ -258,7 +423,7 @@ export const SecretApprovalRequestChanges = ({
         <div className="text-sm text-bunker-300">Reviewers</div>
         <div className="mt-2 flex flex-col space-y-2 text-sm">
           {secretApprovalRequestDetails?.policy?.approvers.map((requiredApprover) => {
-            const status = reviewedUsers?.[requiredApprover.userId];
+            const reviewer = reviewedUsers?.[requiredApprover.userId];
             return (
               <div
                 className="flex flex-nowrap items-center space-x-2 rounded bg-mineshaft-800 px-2 py-1"
@@ -275,8 +440,17 @@ export const SecretApprovalRequestChanges = ({
                   <span className="text-red">*</span>
                 </div>
                 <div>
-                  <Tooltip content={status || ApprovalStatus.PENDING}>
-                    {getReviewedStatusSymbol(status)}
+                  {reviewer?.comment && (
+                    <Tooltip content={reviewer.comment}>
+                      <FontAwesomeIcon
+                        icon={faComment}
+                        size="xs"
+                        className="mr-1 text-mineshaft-300"
+                      />
+                    </Tooltip>
+                  )}
+                  <Tooltip content={reviewer?.status || ApprovalStatus.PENDING}>
+                    {getReviewedStatusSymbol(reviewer?.status)}
                   </Tooltip>
                 </div>
               </div>
@@ -290,7 +464,7 @@ export const SecretApprovalRequestChanges = ({
                 )
             )
             .map((reviewer) => {
-              const status = reviewedUsers?.[reviewer.userId];
+              const status = reviewedUsers?.[reviewer.userId].status;
               return (
                 <div
                   className="flex flex-nowrap items-center space-x-2 rounded bg-mineshaft-800 px-2 py-1"
@@ -303,6 +477,15 @@ export const SecretApprovalRequestChanges = ({
                     <span className="text-red">*</span>
                   </div>
                   <div>
+                    {reviewer.comment && (
+                      <Tooltip content={reviewer.comment}>
+                        <FontAwesomeIcon
+                          icon={faComment}
+                          size="xs"
+                          className="mr-1 text-mineshaft-300"
+                        />
+                      </Tooltip>
+                    )}
                     <Tooltip content={status || ApprovalStatus.PENDING}>
                       {getReviewedStatusSymbol(status)}
                     </Tooltip>