@budibase/worker 3.23.23 → 3.23.25

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@budibase/worker",
   "email": "hi@budibase.com",
-  "version": "3.23.23",
+  "version": "3.23.25",
   "description": "Budibase background service",
   "main": "src/index.ts",
   "repository": {
@@ -109,5 +109,5 @@
       }
     }
   },
-  "gitHead": "e04af85aab2242716869fa9a8f62cd99f8d5e0da"
+  "gitHead": "aaca0ff0f2cf886148a72826d4ecd9c8b90a62b2"
 }

package/src/api/controllers/global/auth.ts

@@ -5,6 +5,7 @@ import {
   events,
   utils as utilsCore,
   configs,
+  cache,
 } from "@budibase/backend-core"
 import {
   ConfigType,
@@ -37,6 +38,44 @@ const { setCookie, getCookie, clearCookie } = utilsCore
 
 // LOGIN / LOGOUT
 
+const normalizeEmail = (e: string) => (e || "").toLowerCase()
+const failKey = (email: string) => `auth:login:fail:${normalizeEmail(email)}`
+const lockKey = (email: string) => `auth:login:lock:${normalizeEmail(email)}`
+const isLocked = async (email: string) => {
+  return !!(await cache.get(lockKey(email)))
+}
+
+const handleLockoutResponse = (ctx: Ctx, email: string) => {
+  ctx.set("X-Account-Locked", "1")
+  ctx.set("Retry-After", String(env.LOGIN_LOCKOUT_SECONDS))
+  console.log(
+    `[auth] login blocked (post-failure) due to lock email=${normalizeEmail(email)}`
+  )
+  return ctx.throw(403, "Account temporarily locked. Try again later.")
+}
+const onFailed = async (email: string) => {
+  if (!email) return
+  const key = failKey(email)
+  const currentAttempt = Number((await cache.get(key)) || 0) || 0
+  const nextAttempt = currentAttempt + 1
+  await cache.store(key, nextAttempt, env.LOGIN_LOCKOUT_SECONDS)
+  console.log(
+    `[auth] failed login email=${normalizeEmail(email)} count=${nextAttempt}`
+  )
+  if (nextAttempt >= env.LOGIN_MAX_FAILED_ATTEMPTS) {
+    await cache.store(lockKey(email), "1", env.LOGIN_LOCKOUT_SECONDS)
+    await cache.destroy(key)
+    console.log(
+      `[auth] account locked email=${normalizeEmail(email)} for ${env.LOGIN_LOCKOUT_SECONDS}s`
+    )
+  }
+}
+const clearFailureState = async (email: string) => {
+  if (!email) return
+  await cache.destroy(failKey(email))
+  await cache.destroy(lockKey(email))
+}
+
 async function passportCallback(
   ctx: Ctx,
   user: User,
@@ -75,14 +114,37 @@ export const login = async (
 ) => {
   const email = ctx.request.body.username
 
-  const user = await userSdk.db.getUserByEmail(email)
-  if (user && (await userSdk.db.isPreventPasswordActions(user))) {
+  const dbUser = await userSdk.db.getUserByEmail(email)
+  if (dbUser && (await userSdk.db.isPreventPasswordActions(dbUser))) {
+    console.log(
+      `[auth] login prevented due to sso enforcement email=${normalizeEmail(email)}`
+    )
     ctx.throw(403, "Invalid credentials")
   }
 
   return passport.authenticate(
     "local",
     async (err: any, user: User, info: any) => {
+      if (err || !user) {
+        if (dbUser) {
+          await onFailed(email)
+        }
+        if (await isLocked(email)) {
+          return handleLockoutResponse(ctx, email)
+        }
+        const reason =
+          (info && info.message) || (err && err.message) || "unknown"
+        console.log(
+          `[auth] password auth failed email=${normalizeEmail(email)} reason=${reason}`
+        )
+        // delegate to shared passport failure handling to preserve specific messages (e.g. expired)
+        return passportCallback(ctx, user as any, err, info)
+      }
+
+      await clearFailureState(email)
+      console.log(
+        `[auth] password auth success email=${normalizeEmail(user.email)}`
+      )
       await passportCallback(ctx, user, err, info)
       await context.identity.doInUserContext(user, ctx, async () => {
         await events.auth.login("local", user.email)
@@ -133,6 +195,60 @@ export const reset = async (
 ) => {
   const { email } = ctx.request.body
 
+  const lcEmail = (email || "").toLowerCase()
+  const ip = (ctx.ip || "").toString()
+
+  // rate limit keys
+  const emailKey = `auth:pwdreset:email:${lcEmail}`
+  const ipKey = `auth:pwdreset:ip:${ip}`
+
+  const increment = async (key: string, windowSeconds: number) => {
+    const currentAttempt = Number((await cache.get(key)) || 0) || 0
+    const nextAttempt = currentAttempt + 1
+    await cache.store(key, nextAttempt, windowSeconds)
+    return nextAttempt
+  }
+
+  // apply per-email and per-ip rate limits
+  const nextEmail = await increment(
+    emailKey,
+    env.PASSWORD_RESET_RATE_EMAIL_WINDOW_SECONDS
+  )
+  const nextIp = await increment(
+    ipKey,
+    env.PASSWORD_RESET_RATE_IP_WINDOW_SECONDS
+  )
+
+  const emailLimited = nextEmail > env.PASSWORD_RESET_RATE_EMAIL_LIMIT
+  const ipLimited = nextIp > env.PASSWORD_RESET_RATE_IP_LIMIT
+
+  if (emailLimited || ipLimited) {
+    // surfaced for ui to display
+    ctx.set(
+      "X-RateLimit-Email-Limit",
+      String(env.PASSWORD_RESET_RATE_EMAIL_LIMIT)
+    )
+    ctx.set(
+      "X-RateLimit-Email-Remaining",
+      String(Math.max(env.PASSWORD_RESET_RATE_EMAIL_LIMIT - nextEmail, 0))
+    )
+    ctx.set("X-RateLimit-IP-Limit", String(env.PASSWORD_RESET_RATE_IP_LIMIT))
+    ctx.set(
+      "X-RateLimit-IP-Remaining",
+      String(Math.max(env.PASSWORD_RESET_RATE_IP_LIMIT - nextIp, 0))
+    )
+    // best-effort retry window
+    const retryAfter = Math.max(
+      env.PASSWORD_RESET_RATE_EMAIL_WINDOW_SECONDS,
+      env.PASSWORD_RESET_RATE_IP_WINDOW_SECONDS
+    )
+    ctx.set("Retry-After", String(retryAfter))
+    console.log(
+      `[auth] password reset rate limited email=${lcEmail} ip=${ip} emailCount=${nextEmail} ipCount=${nextIp}`
+    )
+    return ctx.throw(429, "Too many password reset requests. Try again later.")
+  }
+
   await authSdk.reset(email)
 
   ctx.body = {

package/src/api/controllers/global/configs.ts

@@ -10,6 +10,7 @@ import {
   tenancy,
 } from "@budibase/backend-core"
 import * as pro from "@budibase/pro"
+import { BUILDER_URLS } from "@budibase/shared-core"
 import {
   AIInnerConfig,
   Config,
@@ -676,23 +677,23 @@ export async function configChecklist(ctx: Ctx<void, ConfigChecklistResponse>) {
           apps: {
             checked: workspaces.length > 0,
             label: "Create your first app",
-            link: "/builder/portal/workspaces",
+            link: BUILDER_URLS.WORKSPACES,
           },
           smtp: {
             checked: !!smtpConfig,
             label: "Set up email",
-            link: "/builder/portal/settings/email",
+            link: BUILDER_URLS.SETTINGS_EMAIL,
             fallback: smtpConfig?.fallback || false,
           },
           adminUser: {
             checked: userExists,
             label: "Create your first user",
-            link: "/builder/portal/users/users",
+            link: BUILDER_URLS.SETTINGS_PEOPLE_USERS,
           },
           sso: {
             checked: !!googleConfig || !!oidcConfig,
             label: "Set up single sign-on",
-            link: "/builder/portal/settings/auth",
+            link: BUILDER_URLS.SETTINGS_AUTH,
           },
           branding,
         }

package/src/api/controllers/system/tenants.ts

@@ -1,4 +1,5 @@
 import { GetTenantInfoResponse, UserCtx } from "@budibase/types"
+import { LockRequest, LockReason } from "@budibase/types"
 import * as tenantSdk from "../../../sdk/tenants"
 
 export async function destroy(ctx: UserCtx<void, void>) {
@@ -18,6 +19,34 @@ export async function destroy(ctx: UserCtx<void, void>) {
   }
 }
 
+export async function lock(ctx: UserCtx<LockRequest, void>) {
+  if (!ctx.internal) {
+    ctx.throw(403, "Only internal user can lock a tenant")
+  }
+
+  const { reason } = ctx.request.body
+  if (reason !== undefined && !Object.values(LockReason).includes(reason)) {
+    ctx.throw(
+      400,
+      `Invalid lock reason. Valid values: ${Object.values(LockReason).join(", ")}`
+    )
+  }
+
+  const tenantId = ctx.params.tenantId
+
+  try {
+    if (reason) {
+      await tenantSdk.lockTenant(tenantId, reason)
+    } else {
+      await tenantSdk.unlockTenant(tenantId)
+    }
+    ctx.status = 204
+  } catch (err) {
+    ctx.log.error(err)
+    throw err
+  }
+}
+
 export async function info(ctx: UserCtx<void, GetTenantInfoResponse>) {
   ctx.body = await tenantSdk.tenantInfo(ctx.params.tenantId)
 }

package/src/api/routes/global/auth.ts

@@ -2,6 +2,7 @@ import * as authController from "../../controllers/global/auth"
 import { auth } from "@budibase/backend-core"
 import Joi from "joi"
 import { loggedInRoutes } from "../endpointGroups"
+import { lockout } from "../../../middleware"
 
 function buildAuthValidation() {
   // prettier-ignore
@@ -31,6 +32,7 @@ loggedInRoutes
   .post(
     "/api/global/auth/:tenantId/login",
     buildAuthValidation(),
+    lockout,
     authController.login
   )
   .post("/api/global/auth/logout", authController.logout)

package/src/api/routes/global/tests/auth.spec.ts

@@ -140,6 +140,59 @@ describe("/api/global/auth", () => {
           })
         })
       })
+
+      describe("lockout", () => {
+        it("locks the account after 5 failed attempts and unlocks after TTL", async () => {
+          const tenantId = config.tenantId!
+          const email = config.user!.email!
+          const correctPassword = config.userPassword
+          const wrongPassword = "incorrect123"
+          const { withEnv } = require("../../../../environment")
+
+          await withEnv(
+            {
+              LOGIN_MAX_FAILED_ATTEMPTS: 5,
+              LOGIN_LOCKOUT_SECONDS: 2,
+            },
+            async () => {
+              // 5 consecutive wrong attempts
+              for (let i = 0; i < 5; i++) {
+                await config.api.auth.login(tenantId, email, wrongPassword, {
+                  status: 403,
+                })
+              }
+
+              // lock should be active now - further attempts (wrong or right) return 403
+              await config.api.auth.login(tenantId, email, wrongPassword, {
+                status: 403,
+              })
+
+              await config.api.auth.login(tenantId, email, correctPassword, {
+                status: 403,
+              })
+
+              // wait for TTL to expire (add buffer for redis expiration granularity)
+              await new Promise(r => setTimeout(r, 3000))
+
+              // Clear any remaining lockout state to ensure clean test
+              await config.doInTenant(async () => {
+                const { cache } = require("@budibase/backend-core")
+                const normalizeEmail = (e: string) => (e || "").toLowerCase()
+                const lockKey = (email: string) =>
+                  `auth:login:lock:${normalizeEmail(email)}`
+                await cache.destroy(lockKey(email))
+              })
+
+              const response = await config.api.auth.login(
+                tenantId,
+                email,
+                correctPassword
+              )
+              expectSetAuthCookie(response)
+            }
+          )
+        })
+      })
     })
 
     describe("POST /api/global/auth/logout", () => {

package/src/api/routes/system/tenants.ts

@@ -2,3 +2,4 @@ import * as controller from "../../controllers/system/tenants"
 import { adminRoutes } from "../endpointGroups"
 
 adminRoutes.delete("/api/system/tenants/:tenantId", controller.destroy)
+adminRoutes.put("/api/system/tenants/:tenantId/lock", controller.lock)

package/src/api/routes/system/tests/tenants.spec.ts

@@ -1,5 +1,13 @@
 import { TestConfiguration } from "../../../../tests"
 import { tenancy } from "@budibase/backend-core"
+import { LockReason } from "@budibase/types"
+import * as tenantSdk from "../../../../sdk/tenants"
+
+jest.mock("../../../../sdk/tenants", () => ({
+  lockTenant: jest.fn(),
+  unlockTenant: jest.fn(),
+  deleteTenant: jest.fn(),
+}))
 
 describe("/api/global/tenants", () => {
   const config = new TestConfiguration()
@@ -58,4 +66,85 @@ describe("/api/global/tenants", () => {
       expect(res.body).toEqual(config.adminOnlyResponse())
     })
   })
+
+  describe("PUT /api/system/tenants/:tenantId/lock", () => {
+    it("allows locking tenant with valid reason", async () => {
+      const user = await config.createTenant()
+
+      await config.api.tenants.lock(
+        user.tenantId,
+        {
+          reason: LockReason.FREE_TIER,
+        },
+        {
+          headers: config.internalAPIHeaders(),
+        }
+      )
+
+      expect(tenantSdk.lockTenant).toHaveBeenCalledWith(
+        user.tenantId,
+        LockReason.FREE_TIER
+      )
+      expect(tenantSdk.unlockTenant).not.toHaveBeenCalled()
+    })
+
+    it("unlocks tenant when no reason provided", async () => {
+      const user = await config.createTenant()
+
+      await config.api.tenants.lock(
+        user.tenantId,
+        {},
+        {
+          headers: config.internalAPIHeaders(),
+        }
+      )
+
+      expect(tenantSdk.unlockTenant).toHaveBeenCalledWith(user.tenantId)
+      expect(tenantSdk.lockTenant).not.toHaveBeenCalled()
+    })
+
+    it("rejects invalid lock reason", async () => {
+      const user = await config.createTenant()
+
+      const status = 400
+      const res = await config.api.tenants.lock(
+        user.tenantId,
+        {
+          reason: "invalid_reason" as any,
+        },
+        {
+          status,
+          headers: config.internalAPIHeaders(),
+        }
+      )
+
+      expect(res.body.message).toContain("Invalid lock reason. Valid values:")
+      expect(res.body.message).toContain(LockReason.FREE_TIER)
+      expect(tenantSdk.lockTenant).not.toHaveBeenCalled()
+      expect(tenantSdk.unlockTenant).not.toHaveBeenCalled()
+    })
+
+    it("rejects non-internal user", async () => {
+      const user = await config.createTenant()
+
+      const status = 403
+      const res = await config.api.tenants.lock(
+        user.tenantId,
+        {
+          reason: LockReason.FREE_TIER,
+        },
+        {
+          status,
+          headers: config.authHeaders(user),
+        }
+      )
+
+      expect(res.body).toEqual({
+        message: "Only internal user can lock a tenant",
+        status,
+      })
+      expect(tenantSdk.lockTenant).not.toHaveBeenCalled()
+      expect(tenantSdk.unlockTenant).not.toHaveBeenCalled()
+    })
+  })
 })

package/src/environment.ts

@@ -87,6 +87,20 @@ const environment = {
   PASSPORT_OIDCAUTH_FAILURE_REDIRECT:
     process.env.PASSPORT_OIDCAUTH_FAILURE_REDIRECT || "/error",
 
+  LOGIN_MAX_FAILED_ATTEMPTS:
+    parseIntSafe(process.env.LOGIN_MAX_FAILED_ATTEMPTS) || 5,
+  LOGIN_LOCKOUT_SECONDS: parseIntSafe(process.env.LOGIN_LOCKOUT_SECONDS) || 900,
+
+  // password reset rate limiting
+  PASSWORD_RESET_RATE_EMAIL_LIMIT:
+    parseIntSafe(process.env.PASSWORD_RESET_RATE_EMAIL_LIMIT) || 3,
+  PASSWORD_RESET_RATE_EMAIL_WINDOW_SECONDS:
+    parseIntSafe(process.env.PASSWORD_RESET_RATE_EMAIL_WINDOW_SECONDS) || 900,
+  PASSWORD_RESET_RATE_IP_LIMIT:
+    parseIntSafe(process.env.PASSWORD_RESET_RATE_IP_LIMIT) || 20,
+  PASSWORD_RESET_RATE_IP_WINDOW_SECONDS:
+    parseIntSafe(process.env.PASSWORD_RESET_RATE_IP_WINDOW_SECONDS) || 900,
+
   // Budibase AI
   BUDIBASE_AI_API_KEY: process.env.BUDIBASE_AI_API_KEY,
   BUDIBASE_AI_DEFAULT_MODEL: process.env.BUDIBASE_AI_DEFAULT_MODEL,

package/src/middleware/index.ts

@@ -0,0 +1,3 @@
+export { default as cloudRestricted } from "./cloudRestricted"
+export { handleScimBody } from "./handleScimBody"
+export { default as lockout } from "./lockout"

package/src/middleware/lockout.ts

@@ -0,0 +1,36 @@
+import { cache } from "@budibase/backend-core"
+import { Ctx } from "@budibase/types"
+import { Next } from "koa"
+import env from "../environment"
+import * as userSdk from "../sdk/users"
+
+const normalizeEmail = (e: string) => (e || "").toLowerCase()
+const lockKey = (email: string) => `auth:login:lock:${normalizeEmail(email)}`
+
+const isLocked = async (email: string) => {
+  return !!(await cache.get(lockKey(email)))
+}
+
+/**
+ * Middleware to check if an account is locked due to failed login attempts.
+ * If locked, returns 403 with appropriate headers.
+ */
+export default async (ctx: Ctx, next: Next) => {
+  const email = ctx.request.body.username
+
+  if (!email) {
+    return await next()
+  }
+
+  const dbUser = await userSdk.db.getUserByEmail(email)
+  if (dbUser && (await isLocked(email))) {
+    console.log(
+      `[auth] login blocked due to lock email=${normalizeEmail(email)}`
+    )
+    ctx.set("X-Account-Locked", "1")
+    ctx.set("Retry-After", String(env.LOGIN_LOCKOUT_SECONDS))
+    ctx.throw(403, "Account temporarily locked. Try again later.")
+  }
+
+  return await next()
+}

package/src/middleware/tests/lockout.spec.ts

@@ -0,0 +1,95 @@
+import lockout from "../lockout"
+import { cache } from "@budibase/backend-core"
+import * as userSdk from "../../sdk/users"
+import env from "../../environment"
+
+jest.mock("@budibase/backend-core", () => ({
+  cache: {
+    get: jest.fn(),
+  },
+}))
+
+jest.mock("../../sdk/users", () => ({
+  db: {
+    getUserByEmail: jest.fn(),
+  },
+}))
+
+describe("lockout middleware", () => {
+  let ctx: any
+  let next: jest.Mock
+
+  beforeEach(() => {
+    ctx = {
+      request: {
+        body: {},
+      },
+      set: jest.fn(),
+      throw: jest.fn(),
+    }
+    next = jest.fn()
+    jest.clearAllMocks()
+  })
+
+  it("should call next if no email provided", async () => {
+    ctx.request.body = {}
+
+    await lockout(ctx, next)
+
+    expect(next).toHaveBeenCalled()
+    expect(ctx.throw).not.toHaveBeenCalled()
+  })
+
+  it("should call next if user not found", async () => {
+    ctx.request.body = { username: "test@example.com" }
+    ;(userSdk.db.getUserByEmail as jest.Mock).mockResolvedValue(null)
+
+    await lockout(ctx, next)
+
+    expect(next).toHaveBeenCalled()
+    expect(ctx.throw).not.toHaveBeenCalled()
+  })
+
+  it("should call next if user exists but not locked", async () => {
+    ctx.request.body = { username: "test@example.com" }
+    ;(userSdk.db.getUserByEmail as jest.Mock).mockResolvedValue({
+      email: "test@example.com",
+    })
+    ;(cache.get as jest.Mock).mockResolvedValue(null)
+
+    await lockout(ctx, next)
+
+    expect(next).toHaveBeenCalled()
+    expect(ctx.throw).not.toHaveBeenCalled()
+  })
+
+  it("should throw 403 if user is locked", async () => {
+    ctx.request.body = { username: "test@example.com" }
+    ;(userSdk.db.getUserByEmail as jest.Mock).mockResolvedValue({
+      email: "test@example.com",
+    })
+    ;(cache.get as jest.Mock).mockResolvedValue("1")
+
+    // Mock ctx.throw to actually throw
+    ctx.throw = jest.fn().mockImplementation((status, message) => {
+      const error = new Error(message)
+      ;(error as any).status = status
+      throw error
+    })
+
+    await expect(lockout(ctx, next)).rejects.toThrow(
+      "Account temporarily locked. Try again later."
+    )
+
+    expect(next).not.toHaveBeenCalled()
+    expect(ctx.set).toHaveBeenCalledWith("X-Account-Locked", "1")
+    expect(ctx.set).toHaveBeenCalledWith(
+      "Retry-After",
+      String(env.LOGIN_LOCKOUT_SECONDS)
+    )
+    expect(ctx.throw).toHaveBeenCalledWith(
+      403,
+      "Account temporarily locked. Try again later."
+    )
+  })
+})

package/src/sdk/tenants/tenants.ts

@@ -1,5 +1,11 @@
-import { db as dbCore, platform, tenancy } from "@budibase/backend-core"
+import {
+  configs,
+  db as dbCore,
+  platform,
+  tenancy,
+} from "@budibase/backend-core"
 import { quotas } from "@budibase/pro"
+import { ConfigType, LockReason, SettingsConfig } from "@budibase/types"
 
 export async function deleteTenant(tenantId: string) {
   await quotas.bustCache()
@@ -8,6 +14,28 @@ export async function deleteTenant(tenantId: string) {
   await removeGlobalDB(tenantId)
 }
 
+export async function lockTenant(tenantId: string, lockReason: LockReason) {
+  return await setLock(tenantId, lockReason)
+}
+
+export async function unlockTenant(tenantId: string) {
+  return await setLock(tenantId)
+}
+
+async function setLock(tenantId: string, lockReason?: LockReason) {
+  const db = tenancy.getTenantDB(tenantId)
+  const settingsConfig = await db.tryGet<SettingsConfig>(
+    configs.generateConfigID(ConfigType.SETTINGS)
+  )
+  if (!settingsConfig?.config) {
+    throw new Error(
+      `Cannot lock. Settings config not found for tenant ${tenantId}`
+    )
+  }
+  settingsConfig.config.lockedBy = lockReason
+  await db.put(settingsConfig)
+}
+
 async function removeGlobalDB(tenantId: string) {
   try {
     const db = tenancy.getTenantDB(tenantId)

package/src/sdk/tenants/tests/tenants.spec.ts

@@ -0,0 +1,162 @@
+import { structures } from "../../../tests"
+import { lockTenant, unlockTenant } from "../tenants"
+import { configs, tenancy } from "@budibase/backend-core"
+import { LockReason, ConfigType, SettingsConfig } from "@budibase/types"
+
+// Mock the backend-core modules
+jest.mock("@budibase/backend-core", () => {
+  const actual = jest.requireActual("@budibase/backend-core")
+  return {
+    ...actual,
+    tenancy: {
+      ...actual.tenancy,
+      getTenantDB: jest.fn(),
+      getGlobalDBName: jest.fn(),
+    },
+    configs: {
+      ...actual.configs,
+      generateConfigID: jest.fn(),
+    },
+    db: {
+      ...actual.db,
+      getAllWorkspaces: jest.fn(),
+      getDB: jest.fn(),
+      dbExists: jest.fn(),
+      getGlobalUserParams: jest.fn(),
+    },
+    platform: {
+      ...actual.platform,
+      getPlatformDB: jest.fn(),
+    },
+  }
+})
+
+// Mock the pro module
+jest.mock("@budibase/pro", () => ({
+  quotas: {
+    bustCache: jest.fn(),
+  },
+  constants: {
+    licenses: {
+      CLOUD_FREE_LICENSE: "CLOUD_FREE_LICENSE",
+      UNLIMITED_LICENSE: "UNLIMITED_LICENSE",
+    },
+  },
+  licensing: {
+    cache: {
+      getCachedLicense: jest.fn(),
+    },
+  },
+}))
+
+const mockDb = {
+  put: jest.fn(),
+  tryGet: jest.fn(),
+}
+
+const mockedTenancy = jest.mocked(tenancy)
+const mockedConfigs = jest.mocked(configs)
+
+describe("tenants", () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    // Setup mock database
+    mockedTenancy.getTenantDB.mockReturnValue(mockDb as any)
+    // Setup mock config ID generation
+    mockedConfigs.generateConfigID.mockReturnValue("config_settings")
+  })
+
+  describe("lockTenant", () => {
+    it("should lock tenant with provided reason", async () => {
+      const tenantId = structures.tenant.id()
+      const lockReason = LockReason.FREE_TIER
+
+      const settingsConfig: SettingsConfig = {
+        _id: "config_settings",
+        type: ConfigType.SETTINGS,
+        config: {},
+      }
+
+      mockDb.tryGet.mockResolvedValue(settingsConfig)
+
+      await lockTenant(tenantId, lockReason)
+
+      expect(mockDb.tryGet).toHaveBeenCalledWith(
+        configs.generateConfigID(ConfigType.SETTINGS)
+      )
+      expect(mockDb.put).toHaveBeenCalledWith({
+        ...settingsConfig,
+        config: {
+          ...settingsConfig.config,
+          lockedBy: lockReason,
+        },
+      })
+    })
+
+    it("should throw error when settings config not found", async () => {
+      const tenantId = structures.tenant.id()
+      const lockReason = LockReason.FREE_TIER
+
+      mockDb.tryGet.mockResolvedValue(null)
+
+      await expect(lockTenant(tenantId, lockReason)).rejects.toThrow(
+        `Cannot lock. Settings config not found for tenant ${tenantId}`
+      )
+    })
+
+    it("should throw error when settings config has no config property", async () => {
+      const tenantId = structures.tenant.id()
+      const lockReason = LockReason.FREE_TIER
+
+      const settingsConfig = {
+        _id: "config_settings",
+        type: ConfigType.SETTINGS,
+      }
+
+      mockDb.tryGet.mockResolvedValue(settingsConfig)
+
+      await expect(lockTenant(tenantId, lockReason)).rejects.toThrow(
+        `Cannot lock. Settings config not found for tenant ${tenantId}`
+      )
+    })
+  })
+
+  describe("unlockTenant", () => {
+    it("should unlock tenant by removing lock reason", async () => {
+      const tenantId = structures.tenant.id()
+
+      const settingsConfig: SettingsConfig = {
+        _id: "config_settings",
+        type: ConfigType.SETTINGS,
+        config: {
+          lockedBy: LockReason.FREE_TIER,
+        },
+      }
+
+      mockDb.tryGet.mockResolvedValue(settingsConfig)
+
+      await unlockTenant(tenantId)
+
+      expect(mockDb.tryGet).toHaveBeenCalledWith(
+        configs.generateConfigID(ConfigType.SETTINGS)
+      )
+      expect(mockDb.put).toHaveBeenCalledWith({
+        ...settingsConfig,
+        config: {
+          ...settingsConfig.config,
+          lockedBy: undefined,
+        },
+      })
+    })
+
+    it("should throw error when settings config not found", async () => {
+      const tenantId = structures.tenant.id()
+
+      mockDb.tryGet.mockResolvedValue(null)
+
+      await expect(unlockTenant(tenantId)).rejects.toThrow(
+        `Cannot lock. Settings config not found for tenant ${tenantId}`
+      )
+    })
+  })
+})

package/src/tests/api/tenants.ts

@@ -1,5 +1,6 @@
 import TestConfiguration from "../TestConfiguration"
 import { TestAPI, TestAPIOpts } from "./base"
+import { LockRequest } from "@budibase/types"
 
 export class TenantAPI extends TestAPI {
   config: TestConfiguration
@@ -14,4 +15,12 @@ export class TenantAPI extends TestAPI {
       .set(opts?.headers)
       .expect(opts?.status ? opts.status : 204)
   }
+
+  lock = (tenantId: string, body: LockRequest, opts?: TestAPIOpts) => {
+    return this.request
+      .put(`/api/system/tenants/${tenantId}/lock`)
+      .send(body)
+      .set(opts?.headers)
+      .expect(opts?.status ? opts.status : 204)
+  }
 }