Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
import { createHmac } from "node:crypto";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, type Mocked, test, vi } from "vitest";
import { KeyStorePrefixes, KeyStoreTtls, TKeyStoreFactory } from "@app/keystore/keystore";
import { crypto } from "@app/lib/crypto/cryptography";
import { BadRequestError } from "@app/lib/errors";
import { emailDispatchGuardFactory, EmailDispatchPurpose } from "./email-dispatch-guard";
const AUTH_SECRET = "test-secret-for-email-dispatch-unit-tests";
const NOW_MS = 1_700_000_000_000;
vi.mock("@app/lib/config/env", () => ({
getConfig: () => ({ AUTH_SECRET })
}));
vi.mock("@app/lib/logger", () => ({
logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() }
}));
const hmac = (value: string) => createHmac("sha256", AUTH_SECRET).update(value).digest("hex");
type KeyStoreSlice = Pick<
TKeyStoreFactory,
| "setItemWithExpiryNX"
| "ttl"
| "incrementByAndRefreshExpiryIfUnderLimit"
| "deleteItemsByKeyIn"
| "probeDistinctMember"
>;
type MockedKeyStore = Mocked<KeyStoreSlice>;
const setup = () => {
const keyStore = {
setItemWithExpiryNX: vi.fn().mockResolvedValue("OK"),
ttl: vi.fn().mockResolvedValue(-2),
incrementByAndRefreshExpiryIfUnderLimit: vi.fn().mockResolvedValue(1),
deleteItemsByKeyIn: vi.fn().mockResolvedValue(2),
probeDistinctMember: vi.fn().mockResolvedValue(true)
} as MockedKeyStore;
return { keyStore, guard: emailDispatchGuardFactory({ keyStore: keyStore as never }) };
};
const expectRejected = async <T, E extends Error>(
promise: Promise<T>,
ErrorType: new (...args: never[]) => E
): Promise<E> => {
try {
await promise;
throw new Error("Expected rejection");
} catch (e) {
expect(e).toBeInstanceOf(ErrorType);
return e as E;
}
};
describe("emailDispatchGuard", () => {
beforeAll(async () => {
process.env.FIPS_ENABLED = "false";
await crypto.initialize({} as never, {} as never, {} as never);
});
afterAll(() => {
delete process.env.FIPS_ENABLED;
});
beforeEach(() => {
vi.useFakeTimers();
vi.setSystemTime(new Date(NOW_MS));
});
afterEach(() => {
vi.useRealTimers();
vi.clearAllMocks();
});
describe("hashAddress", () => {
test("keys the code on the literal address and the throttles on the mailbox", () => {
const { guard } = setup();
const { emailHash, mailboxHash } = guard.hashAddress("[email protected]");
expect(emailHash).toBe(hmac("[email protected]"));
expect(mailboxHash).toBe(hmac("[email protected]"));
});
test("dots survive outside Google, where they distinguish real people", () => {
const { guard } = setup();
expect(guard.hashAddress("[email protected]").mailboxHash).toBe(hmac("[email protected]"));
expect(guard.hashAddress("[email protected]").mailboxHash).not.toBe(hmac("[email protected]"));
});
});
describe("checkMailboxCooldown", () => {
// The signup bombing campaign varied dots and +tags; account recovery was reachable by varying
// case alone, since its lookup lowercased the address while its rate-limit key did not. Both
// collapse onto one bucket here or the cooldown is bypassable by changing a single character.
test.each([
["[email protected]", "[email protected]"],
["[email protected]", "[email protected]"],
["[email protected]", "[email protected]"],
["[email protected]", "[email protected]"],
["[email protected]", "[email protected]"]
])("%s shares the bucket of %s", async (variant, mailbox) => {
const { keyStore, guard } = setup();
await guard.checkMailboxCooldown({ purpose: EmailDispatchPurpose.Signup, email: variant });
expect(keyStore.ttl).toHaveBeenCalledWith(
KeyStorePrefixes.EmailDispatchCooldown(EmailDispatchPurpose.Signup, hmac(mailbox))
);
});
test("signup and recovery do not share a bucket", async () => {
const { keyStore, guard } = setup();
await guard.checkMailboxCooldown({ purpose: EmailDispatchPurpose.Signup, email: "[email protected]" });
await guard.checkMailboxCooldown({
purpose: EmailDispatchPurpose.AccountRecovery,
email: "[email protected]"
});
const keys = keyStore.ttl.mock.calls.map(([key]) => key);
expect(new Set(keys).size).toBe(2);
});
test("reports remaining TTL when the cooldown is active", async () => {
const { keyStore, guard } = setup();
keyStore.ttl.mockResolvedValue(30);
const err = await expectRejected(
guard.checkMailboxCooldown({ purpose: EmailDispatchPurpose.Signup, email: "[email protected]" }),
BadRequestError
);
expect(err.details).toMatchObject({ cooldownSeconds: 30 });
});
test("clamps remaining TTL to a minimum of 1", async () => {
const { keyStore, guard } = setup();
// -1 is "exists, no expiry", which still counts as an active cooldown.
keyStore.ttl.mockResolvedValue(-1);
const err = await expectRejected(
guard.checkMailboxCooldown({ purpose: EmailDispatchPurpose.Signup, email: "[email protected]" }),
BadRequestError
);
expect(err.details).toMatchObject({ cooldownSeconds: 1 });
});
});
describe("startMailboxCooldown", () => {
test("writes the cooldown for the normalized mailbox", async () => {
const { keyStore, guard } = setup();
const mailboxHash = hmac("[email protected]");
await guard.startMailboxCooldown({ purpose: EmailDispatchPurpose.Signup, mailboxHash });
expect(keyStore.setItemWithExpiryNX).toHaveBeenCalledWith(
KeyStorePrefixes.EmailDispatchCooldown(EmailDispatchPurpose.Signup, mailboxHash),
KeyStoreTtls.EmailDispatchCooldownInSeconds,
"1"
);
});
test("checking leaves no state behind", async () => {
const { keyStore, guard } = setup();
await guard.checkMailboxCooldown({ purpose: EmailDispatchPurpose.Signup, email: "[email protected]" });
expect(keyStore.setItemWithExpiryNX).not.toHaveBeenCalled();
});
test("loses the race gracefully when another request armed it first", async () => {
const { keyStore, guard } = setup();
keyStore.setItemWithExpiryNX.mockResolvedValue(null);
keyStore.ttl.mockResolvedValue(42);
const err = await expectRejected(
guard.startMailboxCooldown({
purpose: EmailDispatchPurpose.Signup,
mailboxHash: hmac("[email protected]")
}),
BadRequestError
);
expect(err.details).toMatchObject({ cooldownSeconds: 42 });
});
});
describe("consumeMailboxAllowance", () => {
const mailboxHash = hmac("[email protected]");
const args = { purpose: EmailDispatchPurpose.Signup, mailboxHash };
test("allows a send while under the cap", async () => {
const { keyStore, guard } = setup();
keyStore.incrementByAndRefreshExpiryIfUnderLimit.mockResolvedValueOnce(5);
await expect(guard.consumeMailboxAllowance(args)).resolves.toBe(true);
});
test("refuses once the cap is reached", async () => {
const { keyStore, guard } = setup();
keyStore.incrementByAndRefreshExpiryIfUnderLimit.mockResolvedValueOnce(-1);
await expect(guard.consumeMailboxAllowance(args)).resolves.toBe(false);
});
test("uses the primitive that does not extend the window on refusal", async () => {
const { keyStore, guard } = setup();
await guard.consumeMailboxAllowance(args);
expect(keyStore.incrementByAndRefreshExpiryIfUnderLimit).toHaveBeenCalledWith(
KeyStorePrefixes.EmailDispatchMailboxSends(EmailDispatchPurpose.Signup, mailboxHash),
5,
KeyStoreTtls.EmailDispatchMailboxWindowInSeconds
);
});
});
describe("clearMailboxThrottle", () => {
test("drops both the cooldown and the send counter for that purpose", async () => {
const { keyStore, guard } = setup();
const mailboxHash = hmac("[email protected]");
await guard.clearMailboxThrottle({ purpose: EmailDispatchPurpose.AccountRecovery, mailboxHash });
expect(keyStore.deleteItemsByKeyIn).toHaveBeenCalledWith([
KeyStorePrefixes.EmailDispatchCooldown(EmailDispatchPurpose.AccountRecovery, mailboxHash),
KeyStorePrefixes.EmailDispatchMailboxSends(EmailDispatchPurpose.AccountRecovery, mailboxHash)
]);
});
});
describe("probeTraffic", () => {
test("stores only HMACs, never the address or the IP", async () => {
const { keyStore, guard } = setup();
await guard.probeTraffic({
purpose: EmailDispatchPurpose.Signup,
mailboxHash: hmac("[email protected]"),
ip: "203.0.113.7"
});
const members = keyStore.probeDistinctMember.mock.calls.map(([, member]) => member);
expect(members).toContain(hmac("203.0.113.7"));
expect(members).not.toContain("203.0.113.7");
expect(members).not.toContain("[email protected]");
});
});
});