@mohasinac/appkit 3.0.4 → 3.1.0

package/dist/features/auth/repository/__tests__/sms-counter.repository.test.js

@@ -0,0 +1,171 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockDocRef, mockCollection, mockTxn } = makeMockDb();
+vi.mock("../../../../providers/db-firebase/admin", () => ({
+    getAdminDb: () => db,
+}));
+vi.mock("../../../../providers/db-firebase", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, prepareForFirestore: (d) => d };
+});
+vi.mock("../../../../contracts/field-ops", () => ({
+    serverTimestamp: () => new Date(),
+    increment: (n) => n,
+    arrayUnion: (...args) => args,
+    arrayRemove: (...args) => args,
+    deleteField: () => null,
+    registerFieldOps: vi.fn(),
+}));
+vi.mock("../../../../errors/normalize", () => ({ normalizeError: vi.fn() }));
+vi.mock("../../../../monitoring", () => ({
+    serverLogger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+import { SmsCounterRepository } from "../sms-counter.repository";
+import { SMS_DAILY_LIMIT } from "../../schemas";
+const repo = new SmsCounterRepository();
+beforeEach(() => {
+    vi.clearAllMocks();
+    db.collection.mockReturnValue(mockCollection);
+    mockCollection.doc.mockReturnValue(mockDocRef);
+    mockTxn.get.mockResolvedValue(makeSnap(null));
+    mockTxn.set.mockReturnValue(undefined);
+    mockTxn.update.mockReturnValue(undefined);
+    db.runTransaction.mockImplementation(async (cb) => cb(mockTxn));
+});
+// ---------------------------------------------------------------------------
+// checkAndIncrement
+// ---------------------------------------------------------------------------
+describe("SmsCounterRepository.checkAndIncrement", () => {
+    it("first call of the day (no doc) → returns { allowed: true, count: 1 }", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.checkAndIncrement("2026-06-27");
+        expect(result.allowed).toBe(true);
+        expect(result.count).toBe(1);
+    });
+    it("uses Firestore transaction (runTransaction called)", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndIncrement("2026-06-27");
+        expect(db.runTransaction).toHaveBeenCalledOnce();
+    });
+    it("increments existing count by 1", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: 4 }));
+        const result = await repo.checkAndIncrement("2026-06-27");
+        expect(result.count).toBe(5);
+        expect(result.allowed).toBe(true);
+    });
+    it("count at SMS_DAILY_LIMIT - 1 → increments to limit, returns allowed: true", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: SMS_DAILY_LIMIT - 1 }));
+        const result = await repo.checkAndIncrement("2026-06-27");
+        expect(result.allowed).toBe(true);
+        expect(result.count).toBe(SMS_DAILY_LIMIT);
+    });
+    it("count at SMS_DAILY_LIMIT → returns { allowed: false, count: limit }", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: SMS_DAILY_LIMIT }));
+        const result = await repo.checkAndIncrement("2026-06-27");
+        expect(result.allowed).toBe(false);
+        expect(result.count).toBe(SMS_DAILY_LIMIT);
+    });
+    it("count exceeds SMS_DAILY_LIMIT → still returns { allowed: false }", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: SMS_DAILY_LIMIT + 5 }));
+        const result = await repo.checkAndIncrement("2026-06-27");
+        expect(result.allowed).toBe(false);
+    });
+    it("when allowed, calls tx.set with incremented count", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: 2 }));
+        await repo.checkAndIncrement("2026-06-27");
+        expect(mockTxn.set).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ count: 3 }), { merge: true });
+    });
+    it("when NOT allowed, does NOT call tx.set", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: SMS_DAILY_LIMIT }));
+        await repo.checkAndIncrement("2026-06-27");
+        expect(mockTxn.set).not.toHaveBeenCalled();
+    });
+    it("uses dateStr as the document ID (one doc per date)", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndIncrement("2026-06-27");
+        expect(mockCollection.doc).toHaveBeenCalledWith("2026-06-27");
+    });
+    it("stores updatedAt timestamp in the tx.set payload", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndIncrement("2026-06-27");
+        const setArg = mockTxn.set.mock.calls[0][1];
+        expect(setArg).toHaveProperty("updatedAt");
+    });
+});
+// ---------------------------------------------------------------------------
+// getCount
+// ---------------------------------------------------------------------------
+describe("SmsCounterRepository.getCount", () => {
+    it("returns 0 when no document exists for the date", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap(null));
+        const count = await repo.getCount("2026-06-27");
+        expect(count).toBe(0);
+    });
+    it("returns the stored count", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap({ count: 7 }));
+        const count = await repo.getCount("2026-06-27");
+        expect(count).toBe(7);
+    });
+    it("returns 0 if document exists but count field is missing", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap({}));
+        const count = await repo.getCount("2026-06-27");
+        expect(count).toBe(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// checkAndSetUserCooldown
+// ---------------------------------------------------------------------------
+describe("SmsCounterRepository.checkAndSetUserCooldown", () => {
+    it("first call (no existing cooldown doc) → returns { allowed: true }", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.checkAndSetUserCooldown("user-ravi");
+        expect(result.allowed).toBe(true);
+        expect(result.retryAfterSeconds).toBe(0);
+    });
+    it("uses Firestore transaction", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndSetUserCooldown("user-ravi");
+        expect(db.runTransaction).toHaveBeenCalledOnce();
+    });
+    it("cooldown expired (last request >15 min ago) → returns { allowed: true }", async () => {
+        const sixteenMinutesAgo = new Date(Date.now() - 16 * 60 * 1000);
+        mockTxn.get.mockResolvedValue(makeSnap({ lastRequestedAt: { toDate: () => sixteenMinutesAgo } }));
+        const result = await repo.checkAndSetUserCooldown("user-ravi");
+        expect(result.allowed).toBe(true);
+        expect(result.retryAfterSeconds).toBe(0);
+    });
+    it("within 15 min cooldown → returns { allowed: false, retryAfterSeconds > 0 }", async () => {
+        const twoMinutesAgo = new Date(Date.now() - 2 * 60 * 1000);
+        mockTxn.get.mockResolvedValue(makeSnap({ lastRequestedAt: { toDate: () => twoMinutesAgo } }));
+        const result = await repo.checkAndSetUserCooldown("user-ravi");
+        expect(result.allowed).toBe(false);
+        expect(result.retryAfterSeconds).toBeGreaterThan(0);
+        // 15 min - 2 min = 13 min = 780s (±1s tolerance)
+        expect(result.retryAfterSeconds).toBeGreaterThanOrEqual(778);
+        expect(result.retryAfterSeconds).toBeLessThanOrEqual(780);
+    });
+    it("just within cooldown (1 second in) → retryAfterSeconds ≈ 899", async () => {
+        const oneSecondAgo = new Date(Date.now() - 1000);
+        mockTxn.get.mockResolvedValue(makeSnap({ lastRequestedAt: { toDate: () => oneSecondAgo } }));
+        const result = await repo.checkAndSetUserCooldown("user-ravi");
+        expect(result.allowed).toBe(false);
+        expect(result.retryAfterSeconds).toBeGreaterThanOrEqual(898);
+        expect(result.retryAfterSeconds).toBeLessThanOrEqual(900);
+    });
+    it("document ID is user_cooldown_{userId}", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndSetUserCooldown("user-ravi");
+        expect(mockCollection.doc).toHaveBeenCalledWith("user_cooldown_user-ravi");
+    });
+    it("when allowed, calls tx.set with lastRequestedAt timestamp", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndSetUserCooldown("user-ravi");
+        expect(mockTxn.set).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ lastRequestedAt: expect.any(Date) }), { merge: true });
+    });
+    it("when NOT allowed, does NOT call tx.set", async () => {
+        const twoMinutesAgo = new Date(Date.now() - 2 * 60 * 1000);
+        mockTxn.get.mockResolvedValue(makeSnap({ lastRequestedAt: { toDate: () => twoMinutesAgo } }));
+        await repo.checkAndSetUserCooldown("user-ravi");
+        expect(mockTxn.set).not.toHaveBeenCalled();
+    });
+});

package/dist/features/auth/repository/__tests__/sms-counter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/auth/repository/__tests__/sms-counter.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockTxn } = makeMockDb();
+vi.mock("../../../../providers/db-firebase", () => ({
+    getAdminDb: () => db,
+    BaseRepository: class {
+        get db() { return db; }
+        constructor(col) { this.collection = col; }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        getCollection() { return db.collection(this.collection); }
+    },
+}));
+vi.mock("../../../../monitoring", () => ({
+    serverLogger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+import { SmsCounterRepository } from "../sms-counter.repository";
+import { SMS_DAILY_LIMIT } from "../../schemas";
+const repo = new SmsCounterRepository();
+beforeEach(() => {
+    vi.clearAllMocks();
+    db.runTransaction.mockImplementation(async (fn) => fn(mockTxn));
+    mockTxn.set.mockReturnValue(undefined);
+});
+describe("SmsCounterRepository.checkAndIncrement", () => {
+    it("first call of the day → count becomes 1, allowed: true", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.checkAndIncrement("2026-01-01");
+        expect(result.allowed).toBe(true);
+        expect(result.count).toBe(1);
+    });
+    it("count at LIMIT - 1 → increments, allowed: true", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: SMS_DAILY_LIMIT - 1, date: "2026-01-01", updatedAt: new Date() }));
+        const result = await repo.checkAndIncrement("2026-01-01");
+        expect(result.allowed).toBe(true);
+        expect(result.count).toBe(SMS_DAILY_LIMIT);
+    });
+    it("count at LIMIT → not allowed, count unchanged", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap({ count: SMS_DAILY_LIMIT, date: "2026-01-01", updatedAt: new Date() }));
+        const result = await repo.checkAndIncrement("2026-01-01");
+        expect(result.allowed).toBe(false);
+        expect(result.count).toBe(SMS_DAILY_LIMIT);
+        expect(mockTxn.set).not.toHaveBeenCalled();
+    });
+    it("uses Firestore transaction (runTransaction called)", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndIncrement("2026-01-01");
+        expect(db.runTransaction).toHaveBeenCalledOnce();
+    });
+    it("next UTC day uses different doc ID → starts at 1", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.checkAndIncrement("2026-01-02");
+        expect(result.allowed).toBe(true);
+        expect(result.count).toBe(1);
+    });
+});
+describe("SmsCounterRepository.checkAndSetUserCooldown", () => {
+    it("first call → allowed: true, sets cooldown doc", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        const result = await repo.checkAndSetUserCooldown("user-1");
+        expect(result.allowed).toBe(true);
+        expect(result.retryAfterSeconds).toBe(0);
+        expect(mockTxn.set).toHaveBeenCalledOnce();
+    });
+    it("called within 15 minutes → allowed: false with retryAfterSeconds", async () => {
+        const recentlyRequested = new Date(Date.now() - 5 * 60 * 1000); // 5 min ago
+        mockTxn.get.mockResolvedValue(makeSnap({
+            lastRequestedAt: { toDate: () => recentlyRequested },
+        }));
+        const result = await repo.checkAndSetUserCooldown("user-1");
+        expect(result.allowed).toBe(false);
+        expect(result.retryAfterSeconds).toBeGreaterThan(0);
+        expect(result.retryAfterSeconds).toBeLessThanOrEqual(10 * 60); // ~10 min remaining
+    });
+    it("called after 15 minutes → allowed: true", async () => {
+        const old = new Date(Date.now() - 20 * 60 * 1000); // 20 min ago
+        mockTxn.get.mockResolvedValue(makeSnap({
+            lastRequestedAt: { toDate: () => old },
+        }));
+        const result = await repo.checkAndSetUserCooldown("user-1");
+        expect(result.allowed).toBe(true);
+        expect(mockTxn.set).toHaveBeenCalledOnce();
+    });
+    it("uses Firestore transaction", async () => {
+        mockTxn.get.mockResolvedValue(makeSnap(null));
+        await repo.checkAndSetUserCooldown("user-1");
+        expect(db.runTransaction).toHaveBeenCalledOnce();
+    });
+});

package/dist/features/auth/repository/__tests__/token.repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/auth/repository/__tests__/token.repository.test.js

@@ -0,0 +1,260 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap, makeQuerySnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockDocRef, mockCollection, mockQuery, mockBatch } = makeMockDb();
+vi.mock("../../../../providers/db-firebase/admin", () => ({
+    getAdminDb: () => db,
+}));
+vi.mock("../../../../providers/db-firebase", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, prepareForFirestore: (d) => d };
+});
+vi.mock("../../../../contracts/field-ops", () => ({
+    serverTimestamp: () => new Date(),
+    increment: (n) => n,
+    arrayUnion: (...args) => args,
+    arrayRemove: (...args) => args,
+    deleteField: () => null,
+    registerFieldOps: vi.fn(),
+}));
+vi.mock("../../../../security", () => ({
+    encryptPiiFields: (d) => d,
+    decryptPiiFields: (d) => d,
+    addPiiIndices: (d) => d,
+    piiBlindIndex: (v) => `blind:${v}`,
+    encryptPayoutDetails: (d) => d,
+    decryptPayoutDetails: (d) => d,
+    encryptShippingConfig: (d) => d,
+    decryptShippingConfig: (d) => d,
+    USER_PII_FIELDS: [],
+    TOKEN_PII_FIELDS: [],
+    TOKEN_PII_INDEX_MAP: {},
+}));
+vi.mock("../../../../utils", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, resolveDate: (d) => (d instanceof Date ? d : d ? new Date(d) : null) };
+});
+vi.mock("../../../../errors/normalize", () => ({ normalizeError: vi.fn() }));
+vi.mock("../../../../monitoring", () => ({
+    serverLogger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+import { EmailVerificationTokenRepository, PasswordResetTokenRepository, } from "../token.repository";
+const emailRepo = new EmailVerificationTokenRepository();
+const passwordRepo = new PasswordResetTokenRepository();
+function makeEmailToken(overrides = {}) {
+    return {
+        id: "token-email-abc123",
+        userId: "user-ravi",
+        token: "secure-random-token",
+        email: "ravi@example.com",
+        expiresAt: new Date(Date.now() + 60 * 60 * 1000), // 1 hour from now
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides,
+    };
+}
+function makePasswordResetToken(overrides = {}) {
+    return {
+        id: "pw-token-abc123",
+        userId: "user-ravi",
+        token: "pw-reset-token",
+        email: "ravi@example.com",
+        expiresAt: new Date(Date.now() + 30 * 60 * 1000), // 30 min from now
+        used: false,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+        ...overrides,
+    };
+}
+beforeEach(() => {
+    vi.clearAllMocks();
+    db.collection.mockReturnValue(mockCollection);
+    mockCollection.doc.mockReturnValue(mockDocRef);
+    mockCollection.where.mockReturnValue(mockQuery);
+    mockCollection.get = vi.fn().mockResolvedValue(makeQuerySnap([]));
+    mockQuery.where.mockReturnValue(mockQuery);
+    mockQuery.orderBy.mockReturnValue(mockQuery);
+    mockQuery.limit.mockReturnValue(mockQuery);
+    mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+    mockDocRef.get.mockResolvedValue(makeSnap(makeEmailToken(), "token-email-abc123"));
+    mockDocRef.set.mockResolvedValue(undefined);
+    mockDocRef.update.mockResolvedValue(undefined);
+    mockDocRef.delete.mockResolvedValue(undefined);
+    db.batch.mockReturnValue(mockBatch);
+});
+// ---------------------------------------------------------------------------
+// EmailVerificationTokenRepository.findByToken
+// ---------------------------------------------------------------------------
+describe("EmailVerificationTokenRepository.findByToken", () => {
+    it("returns token document when found", async () => {
+        const token = makeEmailToken();
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: token.id, data: token }]));
+        const result = await emailRepo.findByToken("secure-random-token");
+        expect(result).not.toBeNull();
+        expect(result?.token).toBe("secure-random-token");
+    });
+    it("returns null when token does not exist", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        const result = await emailRepo.findByToken("nonexistent-token");
+        expect(result).toBeNull();
+    });
+    it("queries by token field", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await emailRepo.findByToken("abc");
+        expect(mockCollection.where).toHaveBeenCalledWith("token", "==", "abc");
+    });
+});
+// ---------------------------------------------------------------------------
+// EmailVerificationTokenRepository.isExpired
+// ---------------------------------------------------------------------------
+describe("EmailVerificationTokenRepository.isExpired", () => {
+    it("returns false when expiresAt is in the future", () => {
+        const token = makeEmailToken({ expiresAt: new Date(Date.now() + 60000) });
+        expect(emailRepo.isExpired(token)).toBe(false);
+    });
+    it("returns true when expiresAt is in the past", () => {
+        const token = makeEmailToken({ expiresAt: new Date(Date.now() - 1000) });
+        expect(emailRepo.isExpired(token)).toBe(true);
+    });
+    it("returns true when expiresAt is null/undefined", () => {
+        const token = makeEmailToken({ expiresAt: null });
+        expect(emailRepo.isExpired(token)).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// EmailVerificationTokenRepository.deleteAllForUser
+// ---------------------------------------------------------------------------
+describe("EmailVerificationTokenRepository.deleteAllForUser", () => {
+    it("deletes all tokens for the user in batch", async () => {
+        const tokens = [
+            makeEmailToken({ id: "t-1" }),
+            makeEmailToken({ id: "t-2" }),
+        ];
+        mockQuery.get.mockResolvedValue(makeQuerySnap(tokens.map((t) => ({ id: t.id, data: t }))));
+        await emailRepo.deleteAllForUser("user-ravi");
+        expect(mockBatch.delete).toHaveBeenCalledTimes(2);
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+    it("commits even when no tokens exist for the user", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await emailRepo.deleteAllForUser("user-no-tokens");
+        expect(mockBatch.delete).not.toHaveBeenCalled();
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+// ---------------------------------------------------------------------------
+// EmailVerificationTokenRepository.findByEmail (blind-index lookup)
+// ---------------------------------------------------------------------------
+describe("EmailVerificationTokenRepository.findByEmail", () => {
+    it("first queries emailIndex (blind index), not raw email", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await emailRepo.findByEmail("ravi@example.com");
+        expect(mockCollection.where).toHaveBeenCalledWith("emailIndex", "==", "blind:ravi@example.com");
+    });
+    it("falls back to plaintext email lookup when index returns empty", async () => {
+        // First call (index) returns empty, second call (email) also empty
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await emailRepo.findByEmail("ravi@example.com");
+        // Two where calls — first for emailIndex, second for email
+        expect(mockCollection.where).toHaveBeenCalledTimes(2);
+    });
+    it("does NOT fall back if index returns results", async () => {
+        const token = makeEmailToken();
+        mockQuery.get.mockResolvedValueOnce(makeQuerySnap([{ id: token.id, data: token }]));
+        await emailRepo.findByEmail("ravi@example.com");
+        expect(mockCollection.where).toHaveBeenCalledTimes(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// EmailVerificationTokenRepository.deleteExpired
+// ---------------------------------------------------------------------------
+describe("EmailVerificationTokenRepository.deleteExpired", () => {
+    it("batch-deletes all expired tokens", async () => {
+        const tokens = [makeEmailToken({ id: "t-expired-1" }), makeEmailToken({ id: "t-expired-2" })];
+        mockQuery.get.mockResolvedValue(makeQuerySnap(tokens.map((t) => ({ id: t.id, data: t }))));
+        const count = await emailRepo.deleteExpired();
+        expect(count).toBe(2);
+        expect(mockBatch.delete).toHaveBeenCalledTimes(2);
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+    it("queries expiresAt < now", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await emailRepo.deleteExpired();
+        expect(mockCollection.where).toHaveBeenCalledWith("expiresAt", "<", expect.any(Date));
+    });
+});
+// ---------------------------------------------------------------------------
+// PasswordResetTokenRepository.markAsUsed
+// ---------------------------------------------------------------------------
+describe("PasswordResetTokenRepository.markAsUsed", () => {
+    it("sets used: true on the token", async () => {
+        const token = makePasswordResetToken({ used: false });
+        mockDocRef.get.mockResolvedValue(makeSnap(token, "pw-token-abc123"));
+        await passwordRepo.markAsUsed("pw-token-abc123");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ used: true }));
+    });
+    it("sets usedAt timestamp", async () => {
+        const token = makePasswordResetToken();
+        mockDocRef.get.mockResolvedValue(makeSnap(token, "pw-token-abc123"));
+        await passwordRepo.markAsUsed("pw-token-abc123");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ usedAt: expect.any(Date) }));
+    });
+    it("calls doc(tokenId) to target the correct token", async () => {
+        const token = makePasswordResetToken();
+        mockDocRef.get.mockResolvedValue(makeSnap(token, "pw-token-abc123"));
+        await passwordRepo.markAsUsed("pw-token-abc123");
+        expect(mockCollection.doc).toHaveBeenCalledWith("pw-token-abc123");
+    });
+});
+// ---------------------------------------------------------------------------
+// PasswordResetTokenRepository.findUnusedForUser
+// ---------------------------------------------------------------------------
+describe("PasswordResetTokenRepository.findUnusedForUser", () => {
+    it("returns only tokens where used == false for the user", async () => {
+        const unused = makePasswordResetToken({ used: false });
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: unused.id, data: unused }]));
+        const results = await passwordRepo.findUnusedForUser("user-ravi");
+        expect(results).toHaveLength(1);
+    });
+    it("queries userId and used==false filters", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await passwordRepo.findUnusedForUser("user-ravi");
+        expect(mockCollection.where).toHaveBeenCalledWith("userId", "==", "user-ravi");
+        expect(mockQuery.where).toHaveBeenCalledWith("used", "==", false);
+    });
+    it("returns empty array when all tokens for user are used", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        const results = await passwordRepo.findUnusedForUser("user-ravi");
+        expect(results).toEqual([]);
+    });
+});
+// ---------------------------------------------------------------------------
+// PasswordResetTokenRepository.isExpired
+// ---------------------------------------------------------------------------
+describe("PasswordResetTokenRepository.isExpired", () => {
+    it("returns false when expiresAt is in the future", () => {
+        const token = makePasswordResetToken({ expiresAt: new Date(Date.now() + 60000) });
+        expect(passwordRepo.isExpired(token)).toBe(false);
+    });
+    it("returns true when expiresAt is in the past", () => {
+        const token = makePasswordResetToken({ expiresAt: new Date(Date.now() - 1000) });
+        expect(passwordRepo.isExpired(token)).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// PasswordResetTokenRepository.findByEmail (blind-index lookup)
+// ---------------------------------------------------------------------------
+describe("PasswordResetTokenRepository.findByEmail", () => {
+    it("queries by HMAC blind index (not plaintext email)", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await passwordRepo.findByEmail("ravi@example.com");
+        expect(mockCollection.where).toHaveBeenCalledWith("emailIndex", "==", "blind:ravi@example.com");
+    });
+    it("does not expose raw email in the Firestore query field", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await passwordRepo.findByEmail("ravi@example.com");
+        // First call is index lookup — must NOT use raw email
+        const firstCallArg = mockCollection.where.mock.calls[0][2];
+        expect(firstCallArg).not.toBe("ravi@example.com");
+        expect(firstCallArg).toMatch(/^blind:/);
+    });
+});

package/dist/features/auth/repository/__tests__/token.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/auth/repository/__tests__/token.test.js

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { makeMockDb, makeSnap, makeQuerySnap } from "../../../../../tests/helpers/mock-firestore";
+const { db, mockDocRef, mockCollection, mockQuery, mockBatch } = makeMockDb();
+vi.mock("../../../../providers/db-firebase", () => ({
+    getAdminDb: () => db,
+    BaseRepository: class {
+        get db() { return db; }
+        constructor(col) { this.collection = col; }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        getCollection() { return db.collection(this.collection); }
+        mapDoc(snap) {
+            return { id: snap.id, ...snap.data() };
+        }
+        async findBy(field, value) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const snap = await db.collection(this.collection).where(field, "==", value).get();
+            return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
+        }
+        async findOneBy(field, value) {
+            const results = await this.findBy(field, value);
+            return results[0] ?? null;
+        }
+        async findById(id) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const snap = await db.collection(this.collection).doc(id).get();
+            return snap.exists ? { id: snap.id, ...snap.data() } : null;
+        }
+        async findByIdOrFail(id) {
+            const doc = await this.findById(id);
+            if (!doc)
+                throw new Error("Not found");
+            return doc;
+        }
+        async create(data) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ref = await db.collection(this.collection).add(data);
+            return { id: ref.id, ...data };
+        }
+    },
+}));
+vi.mock("../../../../monitoring", () => ({
+    serverLogger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../../../errors/normalize", () => ({
+    normalizeError: vi.fn(),
+}));
+vi.mock("../../../../security", () => ({
+    TOKEN_PII_FIELDS: ["email"],
+    TOKEN_PII_INDEX_MAP: { email: "emailIndex" },
+    encryptPiiFields: (data) => data,
+    decryptPiiFields: (data) => data,
+    addPiiIndices: (data) => data,
+    piiBlindIndex: (v) => `idx:${v}`,
+}));
+vi.mock("../../../../utils", () => ({
+    resolveDate: (d) => (d instanceof Date ? d : d ? new Date(d) : null),
+}));
+import { EmailVerificationTokenRepository, PasswordResetTokenRepository, } from "../token.repository";
+const emailRepo = new EmailVerificationTokenRepository();
+const passwordRepo = new PasswordResetTokenRepository();
+beforeEach(() => {
+    vi.clearAllMocks();
+    mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+    mockDocRef.get.mockResolvedValue(makeSnap(null));
+    mockDocRef.set.mockResolvedValue(undefined);
+    mockDocRef.update.mockResolvedValue(undefined);
+    mockDocRef.delete.mockResolvedValue(undefined);
+    mockCollection.doc.mockReturnValue(mockDocRef);
+    mockCollection.add.mockResolvedValue({ id: "token-id-123" });
+    db.collection.mockReturnValue(mockCollection);
+    db.batch.mockReturnValue(mockBatch);
+    mockBatch.commit.mockResolvedValue(undefined);
+});
+describe("EmailVerificationTokenRepository.findByToken", () => {
+    it("token exists → returns document", async () => {
+        const tokenData = { userId: "user-1", email: "a@b.com", expiresAt: new Date(Date.now() + 60000) };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: "tok-1", data: tokenData }]));
+        const result = await emailRepo.findByToken("some-token");
+        expect(result).not.toBeNull();
+        expect(result?.userId).toBe("user-1");
+    });
+    it("token does not exist → returns null", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        const result = await emailRepo.findByToken("nonexistent-token");
+        expect(result).toBeNull();
+    });
+});
+describe("EmailVerificationTokenRepository.isExpired", () => {
+    it("expiresAt in past → returns true", () => {
+        const pastToken = { id: "t1", userId: "u", email: "a@b.com", expiresAt: new Date(Date.now() - 1000) };
+        expect(emailRepo.isExpired(pastToken)).toBe(true);
+    });
+    it("expiresAt in future → returns false", () => {
+        const futureToken = { id: "t1", userId: "u", email: "a@b.com", expiresAt: new Date(Date.now() + 60000) };
+        expect(emailRepo.isExpired(futureToken)).toBe(false);
+    });
+});
+describe("EmailVerificationTokenRepository.deleteAllForUser", () => {
+    it("batch-deletes all tokens for the user", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([
+            { id: "tok-1", data: { userId: "user-1" } },
+            { id: "tok-2", data: { userId: "user-1" } },
+        ]));
+        await emailRepo.deleteAllForUser("user-1");
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+    it("no tokens for user → still calls commit (empty batch)", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        await emailRepo.deleteAllForUser("user-no-tokens");
+        expect(mockBatch.commit).toHaveBeenCalledOnce();
+    });
+});
+describe("EmailVerificationTokenRepository.findByEmail", () => {
+    it("uses HMAC blind index for lookup (emailIndex field)", async () => {
+        const tokenData = { userId: "u", emailIndex: "idx:a@b.com", expiresAt: new Date() };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: "tok-1", data: tokenData }]));
+        await emailRepo.findByEmail("a@b.com");
+        expect(mockCollection.where).toHaveBeenCalledWith("emailIndex", "==", "idx:a@b.com");
+    });
+});
+describe("PasswordResetTokenRepository.markAsUsed", () => {
+    it("sets usedAt timestamp and used: true on the document", async () => {
+        mockDocRef.get.mockResolvedValue(makeSnap({ userId: "user-1", token: "tok", used: false }));
+        await passwordRepo.markAsUsed("tok-1");
+        expect(mockDocRef.update).toHaveBeenCalledWith(expect.objectContaining({ used: true, usedAt: expect.any(Date) }));
+    });
+});
+describe("PasswordResetTokenRepository.findUnusedForUser", () => {
+    it("returns null when all tokens have used: true", async () => {
+        mockQuery.get.mockResolvedValue(makeQuerySnap([]));
+        const result = await passwordRepo.findUnusedForUser("user-1");
+        expect(result).toEqual([]);
+    });
+    it("returns unused tokens (used: false)", async () => {
+        const tokenData = { userId: "user-1", token: "abc", used: false, expiresAt: new Date() };
+        mockQuery.get.mockResolvedValue(makeQuerySnap([{ id: "tok-1", data: tokenData }]));
+        const result = await passwordRepo.findUnusedForUser("user-1");
+        expect(result).toHaveLength(1);
+    });
+});