Merge branch 'main' into feature/hardover-shelves

tests/api/admin-api-tokens.routes.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Component: Admin API Tokens Route Tests
+ * Documentation: documentation/testing.md
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createPrismaMock } from '../helpers/prisma';
+
+// Valid UUIDs for testing
+const ADMIN_ID = '11111111-1111-1111-1111-111111111111';
+const USER_ID = '22222222-2222-2222-2222-222222222222';
+const ADMIN2_ID = '33333333-3333-3333-3333-333333333333';
+const NONEXISTENT_ID = '99999999-9999-9999-9999-999999999999';
+
+let authRequest: any;
+
+const prismaMock = createPrismaMock();
+const requireAuthMock = vi.hoisted(() => vi.fn());
+const requireAdminMock = vi.hoisted(() => vi.fn());
+const checkApiTokenCreateRateLimitMock = vi.hoisted(() => vi.fn());
+const generateApiTokenMock = vi.hoisted(() => vi.fn());
+
+vi.mock('@/lib/db', () => ({
+  prisma: prismaMock,
+}));
+
+vi.mock('@/lib/middleware/auth', () => ({
+  requireAuth: requireAuthMock,
+  requireAdmin: requireAdminMock,
+}));
+
+vi.mock('@/lib/utils/apiTokenRateLimit', () => ({
+  checkApiTokenCreateRateLimit: checkApiTokenCreateRateLimitMock,
+}));
+
+vi.mock('@/lib/utils/api-token', () => ({
+  generateApiToken: generateApiTokenMock,
+}));
+
+describe('Admin API tokens routes', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    authRequest = {
+      user: { id: ADMIN_ID, username: 'admin', role: 'admin' },
+      json: vi.fn(),
+    };
+    requireAuthMock.mockImplementation((_req: any, handler: any) => handler(authRequest));
+    requireAdminMock.mockImplementation((_req: any, handler: any) => handler());
+    checkApiTokenCreateRateLimitMock.mockReturnValue({ allowed: true });
+    generateApiTokenMock.mockReturnValue({
+      fullToken: 'rmab_test_full_token',
+      tokenHash: 'hashed_token',
+      tokenPrefix: 'rmab_test',
+    });
+  });
+
+  describe('POST /api/admin/api-tokens', () => {
+    it('creates token for self with own role when no userId specified', async () => {
+      authRequest.json.mockResolvedValueOnce({ name: 'Test Token' });
+
+      prismaMock.user.findUnique.mockResolvedValueOnce({
+        id: ADMIN_ID,
+        role: 'admin',
+        plexUsername: 'admin',
+      });
+      prismaMock.apiToken.count.mockResolvedValueOnce(0);
+      prismaMock.apiToken.create.mockResolvedValueOnce({
+        id: 'token-1',
+        name: 'Test Token',
+        tokenPrefix: 'rmab_test',
+        role: 'admin',
+        expiresAt: null,
+        createdAt: new Date(),
+      });
+
+      const { POST } = await import('@/app/api/admin/api-tokens/route');
+      const response = await POST({} as any);
+      const payload = await response.json();
+
+      expect(response.status).toBe(201);
+      expect(payload.token.role).toBe('admin');
+      expect(payload.fullToken).toBe('rmab_test_full_token');
+    });
+
+    it('creates token for another user with their role', async () => {
+      authRequest.json.mockResolvedValueOnce({
+        name: 'Token for User',
+        userId: USER_ID,
+      });
+
+      prismaMock.user.findUnique.mockResolvedValueOnce({
+        id: USER_ID,
+        role: 'user',
+        plexUsername: 'regularuser',
+      });
+      prismaMock.apiToken.count.mockResolvedValueOnce(0);
+      prismaMock.apiToken.create.mockResolvedValueOnce({
+        id: 'token-2',
+        name: 'Token for User',
+        tokenPrefix: 'rmab_test',
+        role: 'user',
+        expiresAt: null,
+        createdAt: new Date(),
+      });
+
+      const { POST } = await import('@/app/api/admin/api-tokens/route');
+      const response = await POST({} as any);
+      const payload = await response.json();
+
+      expect(response.status).toBe(201);
+      expect(payload.token.role).toBe('user');
+    });
+
+    it('rejects role override when role differs from target user role', async () => {
+      authRequest.json.mockResolvedValueOnce({
+        name: 'Escalation Attempt',
+        userId: USER_ID,
+        role: 'admin', // Trying to give admin role to a regular user
+      });
+
+      prismaMock.user.findUnique.mockResolvedValueOnce({
+        id: USER_ID,
+        role: 'user', // Target user is actually a regular user
+        plexUsername: 'regularuser',
+      });
+
+      const { POST } = await import('@/app/api/admin/api-tokens/route');
+      const response = await POST({} as any);
+      const payload = await response.json();
+
+      expect(response.status).toBe(400);
+      expect(payload.error).toContain("must match target user's role");
+    });
+
+    it('rejects role downgrade when role differs from target user role', async () => {
+      authRequest.json.mockResolvedValueOnce({
+        name: 'Downgrade Attempt',
+        userId: ADMIN2_ID,
+        role: 'user', // Trying to give user role to an admin
+      });
+
+      prismaMock.user.findUnique.mockResolvedValueOnce({
+        id: ADMIN2_ID,
+        role: 'admin', // Target user is actually an admin
+        plexUsername: 'otheradmin',
+      });
+
+      const { POST } = await import('@/app/api/admin/api-tokens/route');
+      const response = await POST({} as any);
+      const payload = await response.json();
+
+      expect(response.status).toBe(400);
+      expect(payload.error).toContain("must match target user's role");
+    });
+
+    it('accepts role when it matches target user role', async () => {
+      authRequest.json.mockResolvedValueOnce({
+        name: 'Matching Role',
+        userId: USER_ID,
+        role: 'user', // Explicitly specifying role that matches
+      });
+
+      prismaMock.user.findUnique.mockResolvedValueOnce({
+        id: USER_ID,
+        role: 'user',
+        plexUsername: 'regularuser',
+      });
+      prismaMock.apiToken.count.mockResolvedValueOnce(0);
+      prismaMock.apiToken.create.mockResolvedValueOnce({
+        id: 'token-3',
+        name: 'Matching Role',
+        tokenPrefix: 'rmab_test',
+        role: 'user',
+        expiresAt: null,
+        createdAt: new Date(),
+      });
+
+      const { POST } = await import('@/app/api/admin/api-tokens/route');
+      const response = await POST({} as any);
+
+      expect(response.status).toBe(201);
+    });
+
+    it('returns 404 when target user does not exist', async () => {
+      authRequest.json.mockResolvedValueOnce({
+        name: 'Token for Ghost',
+        userId: NONEXISTENT_ID,
+      });
+
+      prismaMock.user.findUnique.mockResolvedValueOnce(null);
+
+      const { POST } = await import('@/app/api/admin/api-tokens/route');
+      const response = await POST({} as any);
+      const payload = await response.json();
+
+      expect(response.status).toBe(404);
+      expect(payload.error).toBe('Target user not found');
+    });
+
+    it('returns 429 when rate limited', async () => {
+      checkApiTokenCreateRateLimitMock.mockReturnValueOnce({
+        allowed: false,
+        retryAfterSeconds: 60,
+      });
+
+      authRequest.json.mockResolvedValueOnce({ name: 'Rate Limited Token' });
+
+      const { POST } = await import('@/app/api/admin/api-tokens/route');
+      const response = await POST({} as any);
+
+      expect(response.status).toBe(429);
+      expect(response.headers.get('Retry-After')).toBe('60');
+    });
+  });
+});

tests/app/bookdate.page.test.tsx

@@ -216,7 +216,7 @@ describe('BookDatePage', () => {
     await screen.findByText(/Could not load recommendations/);
     fireEvent.click(screen.getByRole('button', { name: 'Go to Settings' }));
 
-    expect(routerMock.push).toHaveBeenCalledWith('/settings');
+    expect(routerMock.push).toHaveBeenCalledWith('/admin/settings');
   });
 
   it('shows empty state and triggers recommendation generation', async () => {

tests/components/requests/RequestCard.test.tsx

@@ -10,23 +10,9 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const cancelRequestMock = vi.hoisted(() => vi.fn());
-const manualSearchMock = vi.hoisted(() => vi.fn());
 
 vi.mock('@/lib/hooks/useRequests', () => ({
   useCancelRequest: () => ({ cancelRequest: cancelRequestMock, isLoading: false }),
-  useManualSearch: () => ({ triggerManualSearch: manualSearchMock, isLoading: false }),
-}));
-
-vi.mock('@/components/requests/InteractiveTorrentSearchModal', () => ({
-  InteractiveTorrentSearchModal: ({
-    isOpen,
-    requestId,
-  }: {
-    isOpen: boolean;
-    requestId?: string;
-  }) => (
-    <div data-testid="interactive-modal" data-open={String(isOpen)} data-request-id={requestId} />
-  ),
 }));
 
 vi.mock('next/image', () => ({
@@ -40,7 +26,7 @@ vi.mock('@/contexts/PreferencesContext', () => ({
 
 vi.mock('@/contexts/AuthContext', () => ({
   useAuth: () => ({
-    user: { id: 'user-1', role: 'user', permissions: { interactiveSearch: true } },
+    user: { id: 'user-1', role: 'user' },
     accessToken: 'test-token',
     isLoading: false,
     login: vi.fn(),
@@ -66,7 +52,6 @@ const baseRequest = {
 describe('RequestCard', () => {
   beforeEach(() => {
     cancelRequestMock.mockReset();
-    manualSearchMock.mockReset();
   });
 
   afterEach(() => {
@@ -109,29 +94,29 @@ describe('RequestCard', () => {
     expect(await screen.findByText('Failure details')).toBeInTheDocument();
   });
 
-  it('triggers manual search, interactive search, and cancel actions', async () => {
+  it('triggers cancel action', async () => {
     const { RequestCard } = await import('@/components/requests/RequestCard');
 
-    manualSearchMock.mockResolvedValueOnce(undefined);
     cancelRequestMock.mockResolvedValueOnce(undefined);
     vi.spyOn(window, 'confirm').mockReturnValue(true);
 
     render(<RequestCard request={baseRequest} />);
 
-    fireEvent.click(screen.getByRole('button', { name: 'Manual Search' }));
-    await waitFor(() => {
-      expect(manualSearchMock).toHaveBeenCalledWith('req-1');
-    });
-
-    fireEvent.click(screen.getByRole('button', { name: 'Interactive Search' }));
-    expect(screen.getByTestId('interactive-modal')).toHaveAttribute('data-open', 'true');
-
     fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
     await waitFor(() => {
       expect(cancelRequestMock).toHaveBeenCalledWith('req-1');
     });
   });
 
+  it('does not show manual search or interactive search buttons', async () => {
+    const { RequestCard } = await import('@/components/requests/RequestCard');
+
+    render(<RequestCard request={baseRequest} />);
+
+    expect(screen.queryByRole('button', { name: 'Manual Search' })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Interactive Search' })).toBeNull();
+  });
+
   it('shows setup indicator when progress is zero', async () => {
     const { RequestCard } = await import('@/components/requests/RequestCard');
 
@@ -153,25 +138,9 @@ describe('RequestCard', () => {
 
     render(<RequestCard request={baseRequest} showActions={false} />);
 
-    expect(screen.queryByRole('button', { name: 'Manual Search' })).toBeNull();
     expect(screen.queryByRole('button', { name: 'Cancel' })).toBeNull();
   });
 
-  it('alerts when manual search fails', async () => {
-    const { RequestCard } = await import('@/components/requests/RequestCard');
-
-    manualSearchMock.mockRejectedValueOnce(new Error('Search failed'));
-    const alertSpy = vi.spyOn(window, 'alert').mockImplementation(() => {});
-
-    render(<RequestCard request={baseRequest} />);
-
-    fireEvent.click(screen.getByRole('button', { name: 'Manual Search' }));
-
-    await waitFor(() => {
-      expect(alertSpy).toHaveBeenCalledWith('Search failed');
-    });
-  });
-
   it('does not cancel when confirmation is declined', async () => {
     const { RequestCard } = await import('@/components/requests/RequestCard');
 

tests/helpers/prisma.ts

@@ -48,6 +48,7 @@ export const createPrismaMock = () => ({
   goodreadsShelf: createModelMock(),
   bookMapping: createModelMock(),
   hardcoverShelf: createModelMock(),
+  apiToken: createModelMock(),
   work: createModelMock(),
   workAsin: createModelMock(),
   watchedSeries: createModelMock(),

tests/middleware/auth.middleware.test.ts

@@ -3,9 +3,11 @@
  * Documentation: documentation/backend/services/auth.md
  */
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { NextResponse } from 'next/server';
 import { createPrismaMock } from '../helpers/prisma';
+import crypto from 'crypto';
 
 const prismaMock = createPrismaMock();
 const verifyAccessTokenMock = vi.fn();
@@ -18,7 +20,9 @@ vi.mock('@/lib/utils/jwt', () => ({
   verifyAccessToken: verifyAccessTokenMock,
 }));
 
-const makeRequest = (authHeader?: string) => ({
+const makeRequest = (authHeader?: string, pathname = '/api/requests', method = 'GET') => ({
+  method,
+  nextUrl: { pathname },
   headers: {
     get: (key: string) => {
       if (key.toLowerCase() === 'authorization') {
@@ -29,6 +33,11 @@ const makeRequest = (authHeader?: string) => ({
   },
 });
 
+// Helper to create a valid API token hash for testing
+const createTestApiToken = (token: string) => {
+  return crypto.createHash('sha256').update(token).digest('hex');
+};
+
 describe('auth middleware', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -159,6 +168,189 @@ describe('auth middleware', () => {
     expect(result).toBe(true);
   });
 
+  it('rejects JWT tokens for soft-deleted users', async () => {
+    verifyAccessTokenMock.mockReturnValue({
+      sub: 'user-1',
+      plexId: 'plex-1',
+      username: 'user',
+      role: 'user',
+      iat: 1,
+      exp: 2,
+    });
+    prismaMock.user.findUnique.mockResolvedValue({
+      id: 'user-1',
+      deletedAt: new Date(),
+    });
+    const { requireAuth } = await import('@/lib/middleware/auth');
+
+    const response = await requireAuth(makeRequest('Bearer token') as any, vi.fn());
+    const payload = await response.json();
+
+    expect(response.status).toBe(401);
+    expect(payload.message).toMatch(/user not found/i);
+  });
+
+  describe('API token authentication', () => {
+    const testToken = 'rmab_test1234567890abcdef';
+    const testTokenHash = createTestApiToken(testToken);
+
+    it('rejects API tokens for soft-deleted users', async () => {
+      prismaMock.apiToken.findUnique.mockResolvedValue({
+        id: 'token-1',
+        tokenHash: testTokenHash,
+        role: 'user',
+        expiresAt: null,
+        tokenUser: {
+          id: 'user-1',
+          plexUsername: 'deleteduser',
+          role: 'user',
+          deletedAt: new Date(),
+        },
+      });
+      const { requireAuth } = await import('@/lib/middleware/auth');
+
+      const response = await requireAuth(makeRequest(`Bearer ${testToken}`) as any, vi.fn());
+      const payload = await response.json();
+
+      expect(response.status).toBe(401);
+      expect(payload.message).toMatch(/invalid.*expired/i);
+    });
+
+    it('rejects API tokens for missing users', async () => {
+      prismaMock.apiToken.findUnique.mockResolvedValue({
+        id: 'token-1',
+        tokenHash: testTokenHash,
+        role: 'user',
+        expiresAt: null,
+        tokenUser: null,
+      });
+      const { requireAuth } = await import('@/lib/middleware/auth');
+
+      const response = await requireAuth(makeRequest(`Bearer ${testToken}`) as any, vi.fn());
+      const payload = await response.json();
+
+      expect(response.status).toBe(401);
+      expect(payload.message).toMatch(/invalid.*expired/i);
+    });
+
+    it('accepts valid API tokens for active users on allowed endpoints', async () => {
+      prismaMock.apiToken.findUnique.mockResolvedValue({
+        id: 'token-1',
+        tokenHash: testTokenHash,
+        role: 'user',
+        expiresAt: null,
+        tokenUser: {
+          id: 'user-1',
+          plexUsername: 'activeuser',
+          role: 'user',
+          deletedAt: null,
+        },
+      });
+      prismaMock.apiToken.update.mockResolvedValue({});
+      const { requireAuth } = await import('@/lib/middleware/auth');
+
+      const handler = vi.fn(async (req: any) =>
+        NextResponse.json({ ok: true, userId: req.user?.id })
+      );
+      const response = await requireAuth(
+        makeRequest(`Bearer ${testToken}`, '/api/requests', 'GET') as any,
+        handler
+      );
+      const payload = await response.json();
+
+      expect(handler).toHaveBeenCalled();
+      expect(payload.userId).toBe('user-1');
+    });
+
+    it('blocks API tokens on endpoints not in the allowlist', async () => {
+      prismaMock.apiToken.findUnique.mockResolvedValue({
+        id: 'token-1',
+        tokenHash: testTokenHash,
+        role: 'admin',
+        expiresAt: null,
+        tokenUser: {
+          id: 'user-1',
+          plexUsername: 'activeuser',
+          role: 'admin',
+          deletedAt: null,
+        },
+      });
+      prismaMock.apiToken.update.mockResolvedValue({});
+      const { requireAuth } = await import('@/lib/middleware/auth');
+
+      const handler = vi.fn();
+      const response = await requireAuth(
+        makeRequest(`Bearer ${testToken}`, '/api/admin/settings', 'GET') as any,
+        handler
+      );
+      const payload = await response.json();
+
+      expect(handler).not.toHaveBeenCalled();
+      expect(response.status).toBe(403);
+      expect(payload.message).toMatch(/not available via API token/i);
+    });
+
+    it('allows API tokens on all 5 permitted endpoints', async () => {
+      const allowedPaths = [
+        '/api/auth/me',
+        '/api/requests',
+        '/api/admin/metrics',
+        '/api/admin/downloads/active',
+        '/api/admin/requests/recent',
+      ];
+
+      for (const path of allowedPaths) {
+        vi.clearAllMocks();
+        prismaMock.apiToken.findUnique.mockResolvedValue({
+          id: 'token-1',
+          tokenHash: testTokenHash,
+          role: 'admin',
+          expiresAt: null,
+          tokenUser: {
+            id: 'user-1',
+            plexUsername: 'activeuser',
+            role: 'admin',
+            deletedAt: null,
+          },
+        });
+        prismaMock.apiToken.update.mockResolvedValue({});
+        const { requireAuth } = await import('@/lib/middleware/auth');
+
+        const handler = vi.fn(async () => NextResponse.json({ ok: true }));
+        const response = await requireAuth(
+          makeRequest(`Bearer ${testToken}`, path, 'GET') as any,
+          handler
+        );
+
+        expect(handler).toHaveBeenCalled();
+        expect(response.status).toBe(200);
+      }
+    });
+
+    it('does not restrict JWT-authenticated users to the allowlist', async () => {
+      verifyAccessTokenMock.mockReturnValue({
+        sub: 'user-1',
+        plexId: 'plex-1',
+        username: 'user',
+        role: 'admin',
+        iat: 1,
+        exp: 2,
+      });
+      prismaMock.user.findUnique.mockResolvedValue({ id: 'user-1' });
+      const { requireAuth } = await import('@/lib/middleware/auth');
+
+      const handler = vi.fn(async () => NextResponse.json({ ok: true }));
+      // Use a non-allowlisted endpoint — JWT should still work
+      const response = await requireAuth(
+        makeRequest('Bearer jwttoken', '/api/admin/settings', 'POST') as any,
+        handler
+      );
+
+      expect(handler).toHaveBeenCalled();
+      expect(response.status).toBe(200);
+    });
+  });
+
   it('returns current user from token', async () => {
     verifyAccessTokenMock.mockReturnValue({
       sub: 'user-1',

tests/services/auth/local-auth-provider.test.ts

@@ -167,6 +167,31 @@ describe('LocalAuthProvider', () => {
     expect(result.error).toMatch(/invalid username or password/i);
   });
 
+  it('normalizes username to lowercase on login', async () => {
+    prismaMock.user.findFirst.mockResolvedValue({
+      id: 'user-ci',
+      plexId: 'local-admin',
+      plexUsername: 'admin',
+      role: 'admin',
+      authProvider: 'local',
+      authToken: 'enc:hash',
+      registrationStatus: 'approved',
+      deletedAt: null,
+    });
+    prismaMock.user.update.mockResolvedValue({});
+    bcryptCompare.mockResolvedValue(true);
+
+    const { LocalAuthProvider } = await import('@/lib/services/auth/LocalAuthProvider');
+    const provider = new LocalAuthProvider();
+    await provider.handleCallback({ username: 'Admin', password: 'pass' });
+
+    expect(prismaMock.user.findFirst).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({ plexUsername: 'admin' }),
+      })
+    );
+  });
+
   it('blocks registration when disabled', async () => {
     configMock.get.mockResolvedValueOnce('false');
 
@@ -237,6 +262,51 @@ describe('LocalAuthProvider', () => {
     expect(result.error).toContain('Username already taken');
   });
 
+  it('stores lowercase username and plexId on registration', async () => {
+    configMock.get.mockResolvedValueOnce('true'); // registration enabled
+    configMock.get.mockResolvedValueOnce('false'); // no admin approval
+    prismaMock.user.findFirst.mockResolvedValue(null);
+    prismaMock.user.count.mockResolvedValue(1);
+    prismaMock.user.create.mockResolvedValue({
+      id: 'user-ci2',
+      plexId: 'local-myuser',
+      plexUsername: 'myuser',
+      role: 'user',
+    });
+    bcryptHash.mockResolvedValue('hash');
+
+    const { LocalAuthProvider } = await import('@/lib/services/auth/LocalAuthProvider');
+    const provider = new LocalAuthProvider();
+    await provider.register({ username: 'MyUser', password: 'password123' });
+
+    expect(prismaMock.user.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          plexId: 'local-myuser',
+          plexUsername: 'myuser',
+        }),
+      })
+    );
+  });
+
+  it('rejects duplicate username case-insensitively on registration', async () => {
+    configMock.get.mockResolvedValueOnce('true'); // registration enabled
+    prismaMock.user.findFirst.mockResolvedValue({ id: 'user-existing' });
+
+    const { LocalAuthProvider } = await import('@/lib/services/auth/LocalAuthProvider');
+    const provider = new LocalAuthProvider();
+    const result = await provider.register({ username: 'User', password: 'password123' });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Username already taken');
+    // The lookup should use the lowercased username
+    expect(prismaMock.user.findFirst).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({ plexUsername: 'user' }),
+      })
+    );
+  });
+
   it('creates admin user on first registration', async () => {
     configMock.get.mockResolvedValueOnce('true'); // registration enabled
     configMock.get.mockResolvedValueOnce('false'); // no admin approval

tests/utils/apiTokenRateLimit.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Component: API Token Rate Limit Tests
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  checkApiTokenCreateRateLimit,
+  checkApiTokenRevokeRateLimit,
+  _resetBuckets,
+  _getBucketCount,
+} from '@/lib/utils/apiTokenRateLimit';
+import { MAX_TOKENS_PER_USER } from '@/lib/constants/api-tokens';
+
+describe('API Token Rate Limiting', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    _resetBuckets();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    _resetBuckets();
+  });
+
+  describe('checkApiTokenCreateRateLimit', () => {
+    it('allows requests under the limit', () => {
+      const actorId = 'user-create-1';
+
+      for (let i = 0; i < 10; i++) {
+        const result = checkApiTokenCreateRateLimit(actorId);
+        expect(result.allowed).toBe(true);
+      }
+    });
+
+    it('blocks requests over the limit (10/min)', () => {
+      const actorId = 'user-create-2';
+
+      // Use up the limit
+      for (let i = 0; i < 10; i++) {
+        checkApiTokenCreateRateLimit(actorId);
+      }
+
+      // 11th request should be blocked
+      const result = checkApiTokenCreateRateLimit(actorId);
+      expect(result.allowed).toBe(false);
+      expect(result.retryAfterSeconds).toBeGreaterThan(0);
+    });
+
+    it('resets after the window expires', () => {
+      const actorId = 'user-create-3';
+
+      // Use up the limit
+      for (let i = 0; i < 10; i++) {
+        checkApiTokenCreateRateLimit(actorId);
+      }
+
+      // Should be blocked
+      expect(checkApiTokenCreateRateLimit(actorId).allowed).toBe(false);
+
+      // Advance time past the window (60 seconds)
+      vi.advanceTimersByTime(61 * 1000);
+
+      // Should be allowed again
+      expect(checkApiTokenCreateRateLimit(actorId).allowed).toBe(true);
+    });
+
+    it('tracks different actors separately', () => {
+      const actor1 = 'user-create-4';
+      const actor2 = 'user-create-5';
+
+      // Use up actor1's limit
+      for (let i = 0; i < 10; i++) {
+        checkApiTokenCreateRateLimit(actor1);
+      }
+
+      // actor1 should be blocked
+      expect(checkApiTokenCreateRateLimit(actor1).allowed).toBe(false);
+
+      // actor2 should still be allowed
+      expect(checkApiTokenCreateRateLimit(actor2).allowed).toBe(true);
+    });
+  });
+
+  describe('checkApiTokenRevokeRateLimit', () => {
+    it('allows requests under the limit', () => {
+      const actorId = 'user-revoke-1';
+
+      for (let i = 0; i < 20; i++) {
+        const result = checkApiTokenRevokeRateLimit(actorId);
+        expect(result.allowed).toBe(true);
+      }
+    });
+
+    it('blocks requests over the limit (20/min)', () => {
+      const actorId = 'user-revoke-2';
+
+      // Use up the limit
+      for (let i = 0; i < 20; i++) {
+        checkApiTokenRevokeRateLimit(actorId);
+      }
+
+      // 21st request should be blocked
+      const result = checkApiTokenRevokeRateLimit(actorId);
+      expect(result.allowed).toBe(false);
+      expect(result.retryAfterSeconds).toBeGreaterThan(0);
+    });
+
+    it('returns correct retryAfterSeconds', () => {
+      const actorId = 'user-revoke-3';
+
+      // Use up the limit
+      for (let i = 0; i < 20; i++) {
+        checkApiTokenRevokeRateLimit(actorId);
+      }
+
+      // Advance 30 seconds into the window
+      vi.advanceTimersByTime(30 * 1000);
+
+      const result = checkApiTokenRevokeRateLimit(actorId);
+      expect(result.allowed).toBe(false);
+      // Should have ~30 seconds left
+      expect(result.retryAfterSeconds).toBeLessThanOrEqual(30);
+      expect(result.retryAfterSeconds).toBeGreaterThan(0);
+    });
+  });
+
+  describe('lazy eviction', () => {
+    it('deletes expired buckets when they are next accessed', () => {
+      const actorId = 'user-evict-1';
+
+      // Create a bucket
+      checkApiTokenCreateRateLimit(actorId);
+      expect(_getBucketCount()).toBe(1);
+
+      // Expire the window
+      vi.advanceTimersByTime(61 * 1000);
+
+      // Accessing the same key should evict the old bucket and create a fresh one
+      checkApiTokenCreateRateLimit(actorId);
+      // Should still be 1 (old one deleted, new one created)
+      expect(_getBucketCount()).toBe(1);
+    });
+
+    it('does not delete buckets that are still active', () => {
+      // Create buckets for two actors
+      checkApiTokenCreateRateLimit('actor-a');
+      checkApiTokenCreateRateLimit('actor-b');
+      expect(_getBucketCount()).toBe(2);
+
+      // Advance partially (not past the 60s window)
+      vi.advanceTimersByTime(30 * 1000);
+
+      // Both should still be there
+      checkApiTokenCreateRateLimit('actor-a');
+      expect(_getBucketCount()).toBe(2);
+    });
+  });
+
+  describe('periodic sweep', () => {
+    it('sweeps all expired buckets every 100 checks', () => {
+      // Create 10 unique actor buckets
+      for (let i = 0; i < 10; i++) {
+        checkApiTokenCreateRateLimit(`sweep-actor-${i}`);
+      }
+      expect(_getBucketCount()).toBe(10);
+
+      // Expire all windows
+      vi.advanceTimersByTime(61 * 1000);
+
+      // Add some fresh buckets that should NOT be swept
+      checkApiTokenCreateRateLimit('sweep-fresh-1');
+      checkApiTokenCreateRateLimit('sweep-fresh-2');
+
+      // We've done 10 + 2 = 12 calls so far. Need 100 total to trigger sweep.
+      // Do 88 more calls with unique actors to reach 100
+      for (let i = 0; i < 88; i++) {
+        checkApiTokenCreateRateLimit(`sweep-filler-${i}`);
+      }
+
+      // After the 100th call, the sweep should have removed the 10 expired buckets.
+      // Remaining: 2 fresh + 88 filler = 90
+      expect(_getBucketCount()).toBe(90);
+    });
+  });
+
+  describe('_resetBuckets', () => {
+    it('clears all buckets', () => {
+      checkApiTokenCreateRateLimit('reset-1');
+      checkApiTokenCreateRateLimit('reset-2');
+      expect(_getBucketCount()).toBeGreaterThan(0);
+
+      _resetBuckets();
+      expect(_getBucketCount()).toBe(0);
+    });
+  });
+
+  describe('MAX_TOKENS_PER_USER constant', () => {
+    it('is set to 25', () => {
+      expect(MAX_TOKENS_PER_USER).toBe(25);
+    });
+  });
+});