IP Allowlist (#564)

* prisma extension is default formatter for primsa files

* Add ipAllowlist to configuration schema

* created allowlist migration

* Add trust proxy env var and fastify param

* add checkIpInAllowlist function, refactor handleAccessToken

* added ipAllowlist in keypair auth

* added ipAllowlist to websocketAuth

* Add routes

* Add IP_ALLOWLIST to features in health

* chore: Update unauthorized IP address error message

* Added mandatory env vars to test env

* fixed webhooks

* updated chain tests

* removed url tests

* migrated tests to vitest

* Address PR Comments

* Added IP Allowlist test cases

* remove stray console.log

* Made tests consistent

* enforce node 20

---------

Co-authored-by: Farhan Khwaja <132962163+farhanW3@users.noreply.github.com>

Author: d4mr

.env.test

@@ -2,4 +2,7 @@ THIRDWEB_API_SECRET_KEY="test"
 POSTGRES_CONNECTION_URL="postgresql://postgres:postgres@localhost:5432/postgres?sslmode=disable"
 ADMIN_WALLET_ADDRESS="test"
 ENCRYPTION_PASSWORD="test"
-ENABLE_KEYPAIR_AUTH="true"
+ENABLE_KEYPAIR_AUTH="true"
+ENABLE_HTTPS="true"
+REDIS_URL="redis://127.0.0.1:6379/0"
+THIRDWEB_API_SECRET_KEY="my-thirdweb-secret-key"

.jest/setEnvVars.js

@@ -7,5 +7,8 @@
   "editor.formatOnSave": true,
   "eslint.rules.customizations": [{ "rule": "*", "severity": "warn" }],
   "typescript.tsdk": "node_modules/typescript/lib",
-  "typescript.enablePromptUseWorkspaceTsdk": true
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "[prisma]": {
+    "editor.defaultFormatter": "Prisma.prisma"
+  }
 }

.vscode/settings.json

@@ -2,6 +2,9 @@
   "name": "web3-api",
   "version": "0.1.0",
   "license": "Apache-2.0",
+  "engines": {
+    "node": "20.x"
+  },
   "description": "thirdweb's web3-api server",
   "main": "src/server/index.ts",
   "author": "thirdweb engineering <eng@thirdweb.com>",
@@ -26,7 +29,8 @@
     "lint:fix": "eslint --fix 'src/**/*.ts'",
     "test:load": "npx tsx ./test/load/index.ts",
     "test:load:benchmark": "npx tsx ./test/load/scripts/account.ts",
-    "test:unit": "jest"
+    "test:unit": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@aws-sdk/client-kms": "^3.398.0",
@@ -79,7 +83,6 @@
     "@types/cookie": "^0.5.1",
     "@types/crypto-js": "^4.2.2",
     "@types/express": "^4.17.17",
-    "@types/jest": "^29.5.11",
     "@types/jsonwebtoken": "^9.0.6",
     "@types/node": "^18.15.4",
     "@types/node-cron": "^3.0.8",
@@ -88,16 +91,16 @@
     "@types/ws": "^8.5.5",
     "@typescript-eslint/eslint-plugin": "^5.55.0",
     "@typescript-eslint/parser": "^5.55.0",
+    "@vitest/coverage-v8": "^2.0.3",
     "commander": "^11.0.0",
     "eslint": "^9.3.0",
     "eslint-config-prettier": "^8.7.0",
-    "jest": "^29.7.0",
     "nodemon": "^3.1.2",
     "openapi-typescript-codegen": "^0.25.0",
     "prettier": "^2.8.7",
-    "ts-jest": "^29.1.1",
     "ts-node": "^10.9.1",
-    "typescript": "^5.1.3"
+    "typescript": "^5.1.3",
+    "vitest": "^2.0.3"
   },
   "lint-staged": {
     "*.{js,ts}": "eslint --cache --fix",

jest.config.ts

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "configuration" ADD COLUMN     "ipAllowlist" TEXT[] DEFAULT ARRAY[]::TEXT[];

package.json

@@ -30,25 +30,26 @@ model Configuration {
   contractSubscriptionsRetryDelaySeconds String  @default("10") @map("contractSubscriptionsRetryDelaySeconds")
 
   // AWS
-  awsAccessKeyId                     String? @map("awsAccessKeyId")
-  awsSecretAccessKey                 String? @map("awsSecretAccessKey")
-  awsRegion                          String? @map("awsRegion")
+  awsAccessKeyId                     String?  @map("awsAccessKeyId")
+  awsSecretAccessKey                 String?  @map("awsSecretAccessKey")
+  awsRegion                          String?  @map("awsRegion")
   // GCP
-  gcpApplicationProjectId            String? @map("gcpApplicationProjectId")
-  gcpKmsLocationId                   String? @map("gcpKmsLocationId")
-  gcpKmsKeyRingId                    String? @map("gcpKmsKeyRingId")
-  gcpApplicationCredentialEmail      String? @map("gcpApplicationCredentialEmail")
-  gcpApplicationCredentialPrivateKey String? @map("gcpApplicationCredentialPrivateKey")
+  gcpApplicationProjectId            String?  @map("gcpApplicationProjectId")
+  gcpKmsLocationId                   String?  @map("gcpKmsLocationId")
+  gcpKmsKeyRingId                    String?  @map("gcpKmsKeyRingId")
+  gcpApplicationCredentialEmail      String?  @map("gcpApplicationCredentialEmail")
+  gcpApplicationCredentialPrivateKey String?  @map("gcpApplicationCredentialPrivateKey")
   // Auth
-  authDomain                         String  @default("") @map("authDomain") // TODO: Remove defaults on major
-  authWalletEncryptedJson            String  @default("") @map("authWalletEncryptedJson") // TODO: Remove defaults on major
+  authDomain                         String   @default("") @map("authDomain") // TODO: Remove defaults on major
+  authWalletEncryptedJson            String   @default("") @map("authWalletEncryptedJson") // TODO: Remove defaults on major
   // Webhook
-  webhookUrl                         String? @map("webhookUrl")
-  webhookAuthBearerToken             String? @map("webhookAuthBearerToken")
+  webhookUrl                         String?  @map("webhookUrl")
+  webhookAuthBearerToken             String?  @map("webhookAuthBearerToken")
   // Wallet balance
-  minWalletBalance                   String  @default("20000000000000000") @map("minWalletBalance")
-  accessControlAllowOrigin           String  @default("https://thirdweb.com,https://embed.ipfscdn.io") @map("accessControlAllowOrigin")
-  clearCacheCronSchedule             String  @default("*/30 * * * * *") @map("clearCacheCronSchedule")
+  minWalletBalance                   String   @default("20000000000000000") @map("minWalletBalance")
+  accessControlAllowOrigin           String   @default("https://thirdweb.com,https://embed.ipfscdn.io") @map("accessControlAllowOrigin")
+  ipAllowlist                        String[] @default([]) @map("ipAllowlist")
+  clearCacheCronSchedule             String   @default("*/30 * * * * *") @map("clearCacheCronSchedule")
 
   @@map("configuration")
 }

src/prisma/migrations/20240704112555_ip_allowlist/migration.sql

@@ -50,6 +50,9 @@ export const initServer = async () => {
   const server: FastifyInstance = fastify({
     connectionTimeout: SERVER_CONNECTION_TIMEOUT,
     disableRequestLogging: true,
+    // env.TRUST_PROXY is used to determine if the X-Forwarded-For header should be trusted.
+    // See: https://fastify.dev/docs/latest/Reference/Server/#trustproxy
+    trustProxy: env.TRUST_PROXY,
     ...(env.ENABLE_HTTPS ? httpsObject : {}),
   }).withTypeProvider<TypeBoxTypeProvider>();
 

src/prisma/schema.prisma

@@ -252,6 +252,16 @@ const handleWebsocketAuth = async (
     // Set as a header for `getUsers` to parse the token.
     req.headers.authorization = `Bearer ${jwt}`;
     const user = await getUser(req);
+
+    const isIpInAllowlist = await checkIpInAllowlist(req);
+    if (!isIpInAllowlist) {
+      return {
+        isAuthed: false,
+        error:
+          "Unauthorized IP Address. See: https://portal.thirdweb.com/engine/features/security",
+      };
+    }
+
     if (
       user?.session?.permissions === Permission.Owner ||
       user?.session?.permissions === Permission.Admin
@@ -309,6 +319,12 @@ const handleKeypairAuth = async (
       throw error;
     }
 
+    const isIpInAllowlist = await checkIpInAllowlist(req);
+    if (!isIpInAllowlist) {
+      error =
+        "Unauthorized IP Address. See: https://portal.thirdweb.com/engine/features/security";
+      throw error;
+    }
     return { isAuthed: true };
   } catch (e) {
     if (e instanceof jsonwebtoken.TokenExpiredError) {
@@ -337,22 +353,39 @@ const handleAccessToken = async (
   req: FastifyRequest,
   getUser: ReturnType<typeof ThirdwebAuth<TAuthData, TAuthSession>>["getUser"],
 ): Promise<AuthResponse> => {
+  let token: Awaited<ReturnType<typeof getAccessToken>> = null;
+
   try {
-    const token = await getAccessToken({ jwt });
-    if (token && token.revokedAt === null) {
-      const user = await getUser(req);
-      if (
-        user?.session?.permissions === Permission.Owner ||
-        user?.session?.permissions === Permission.Admin
-      ) {
-        return { isAuthed: true, user };
-      }
-    }
+    token = await getAccessToken({ jwt });
   } catch (e) {
     // Missing or invalid signature. This will occur if the JWT not intended for this auth pattern.
+    return { isAuthed: false };
   }
 
-  return { isAuthed: false };
+  if (!token || token.revokedAt) {
+    return { isAuthed: false };
+  }
+
+  const user = await getUser(req);
+
+  if (
+    user?.session?.permissions !== Permission.Owner &&
+    user?.session?.permissions !== Permission.Admin
+  ) {
+    return { isAuthed: false };
+  }
+
+  const isIpInAllowlist = await checkIpInAllowlist(req);
+
+  if (!isIpInAllowlist) {
+    return {
+      isAuthed: false,
+      error:
+        "Unauthorized IP Address. See: https://portal.thirdweb.com/engine/features/security",
+    };
+  }
+
+  return { isAuthed: true, user };
 };
 
 /**
@@ -453,3 +486,21 @@ const hashRequestBody = (req: FastifyRequest): string => {
     .update(JSON.stringify(req.body), "utf8")
     .digest("hex");
 };
+
+/**
+ * Check if the request IP is in the allowlist.
+ * Fetches cached config if available.
+ * env.TRUST_PROXY is used to determine if the X-Forwarded-For header should be trusted.
+ * @param req FastifyRequest
+ * @returns boolean
+ * @async
+ */
+const checkIpInAllowlist = async (req: FastifyRequest) => {
+  const config = await getConfig();
+
+  if (config.ipAllowlist.length === 0) {
+    return true;
+  }
+
+  return config.ipAllowlist.includes(req.ip);
+};

src/server/index.ts

@@ -0,0 +1,35 @@
+import { Static, Type } from "@sinclair/typebox";
+import { FastifyInstance } from "fastify";
+import { StatusCodes } from "http-status-codes";
+import { getConfig } from "../../../../utils/cache/getConfig";
+import { standardResponseSchema } from "../../../schemas/sharedApiSchemas";
+
+export const responseBodySchema = Type.Object({
+  result: Type.Array(Type.String()),
+});
+
+export async function getIpAllowlist(fastify: FastifyInstance) {
+  fastify.route<{
+    Reply: Static<typeof responseBodySchema>;
+  }>({
+    method: "GET",
+    url: "/configuration/ip-allowlist",
+    schema: {
+      summary: "Get Allowed IP Addresses",
+      description: "Get the list of allowed IP addresses",
+      tags: ["Configuration"],
+      operationId: "getIpAllowlist",
+      response: {
+        ...standardResponseSchema,
+        [StatusCodes.OK]: responseBodySchema,
+      },
+    },
+    handler: async (req, res) => {
+      const config = await getConfig(false);
+
+      res.status(200).send({
+        result: config.ipAllowlist,
+      });
+    },
+  });
+}

src/server/middleware/auth.ts

@@ -0,0 +1,60 @@
+import { Static, Type } from "@sinclair/typebox";
+import { FastifyInstance } from "fastify";
+import { StatusCodes } from "http-status-codes";
+import { updateConfiguration } from "../../../../db/configuration/updateConfiguration";
+import { getConfig } from "../../../../utils/cache/getConfig";
+import { standardResponseSchema } from "../../../schemas/sharedApiSchemas";
+import { responseBodySchema } from "./get";
+
+const requestBodySchema = Type.Object({
+  ips: Type.Array(
+    Type.String({
+      minLength: 7,
+      description: "IP address as a string",
+    }),
+    {
+      description: "Array of IP addresses to allowlist",
+    },
+  ),
+});
+
+requestBodySchema.examples = [
+  {
+    ips: ["8.8.8.8", "172.217.255.255"],
+  },
+];
+
+export async function setIpAllowlist(fastify: FastifyInstance) {
+  fastify.route<{
+    Body: Static<typeof requestBodySchema>;
+    Reply: Static<typeof responseBodySchema>;
+  }>({
+    method: "PUT",
+    url: "/configuration/ip-allowlist",
+    schema: {
+      summary: "Set IP Allowlist",
+      description: "Replaces the IP Allowlist array to allow calls to Engine",
+      tags: ["Configuration"],
+      operationId: "setIpAllowlist",
+      body: requestBodySchema,
+      response: {
+        ...standardResponseSchema,
+        [StatusCodes.OK]: responseBodySchema,
+      },
+    },
+    handler: async (req, res) => {
+      const ips = req.body.ips.map((ip) => ip.trim());
+      const dedupe = Array.from(new Set([...ips]));
+
+      await updateConfiguration({
+        ipAllowlist: dedupe,
+      });
+
+      // Fetch and return the updated configuration
+      const config = await getConfig(false);
+      res.status(200).send({
+        result: config.ipAllowlist,
+      });
+    },
+  });
+}

src/server/routes/configuration/ip/get.ts

@@ -124,6 +124,8 @@ import { checkGroupStatus } from "./transaction/group";
 
 // Indexer
 import { setUrlsToCorsConfiguration } from "./configuration/cors/set";
+import { getIpAllowlist } from "./configuration/ip/get";
+import { setIpAllowlist } from "./configuration/ip/set";
 import { getContractEventLogs } from "./contract/events/getContractEventLogs";
 import { getEventLogs } from "./contract/events/getEventLogsByTimestamp";
 import { pageEventLogs } from "./contract/events/paginateEventLogs";
@@ -175,6 +177,8 @@ export const withRoutes = async (fastify: FastifyInstance) => {
   await fastify.register(updateCacheConfiguration);
   await fastify.register(getContractSubscriptionsConfiguration);
   await fastify.register(updateContractSubscriptionsConfiguration);
+  await fastify.register(getIpAllowlist);
+  await fastify.register(setIpAllowlist);
 
   // Webhooks
   await fastify.register(getAllWebhooksData);

src/server/routes/configuration/ip/set.ts

@@ -5,7 +5,7 @@ import { isDatabaseHealthy } from "../../../db/client";
 import { env } from "../../../utils/env";
 import { redis } from "../../../utils/redis/redis";
 
-type EngineFeature = "KEYPAIR_AUTH" | "CONTRACT_SUBSCRIPTIONS";
+type EngineFeature = "KEYPAIR_AUTH" | "CONTRACT_SUBSCRIPTIONS" | "IP_ALLOWLIST";
 
 const ReplySchemaOk = Type.Object({
   status: Type.String(),
@@ -15,6 +15,7 @@ const ReplySchemaOk = Type.Object({
     Type.Union([
       Type.Literal("KEYPAIR_AUTH"),
       Type.Literal("CONTRACT_SUBSCRIPTIONS"),
+      Type.Literal("IP_ALLOWLIST"),
     ]),
   ),
 });
@@ -61,7 +62,8 @@ export async function healthCheck(fastify: FastifyInstance) {
 }
 
 const getFeatures = (): EngineFeature[] => {
-  const features: EngineFeature[] = [];
+  // IP Allowlist is always available as a feature, but added as a feature for backwards compatibility.
+  const features: EngineFeature[] = ["IP_ALLOWLIST"];
 
   if (env.ENABLE_KEYPAIR_AUTH) features.push("KEYPAIR_AUTH");
   // Contract Subscriptions requires Redis.