feat(security): track API key usage per orgId and emit security events

- Implement ApiKeyUsageTrackerService with Redis-backed sliding-window
  aggregator tracking distinct countries per API key in 15-minute windows
- Add SecurityEventJob that flushes usage windows hourly and records
  anomalies to AuditLog with full metadata
- Add security_event_total Prometheus counter for anomaly detection
- Register security_event_total metric in metrics.providers.ts
- Add MetricsService.incrementSecurityEvent() method
- Register UsageTrackerModule and SecurityEventJob in JobsModule
- Import ConfigModule in UsageTrackerModule for dependency resolution
- Add 6 unit tests covering anomaly recording, multiple anomalies,
  no-anomaly case, and error handling

Closes #220

Author: ameeribro4-sudo

app/backend/src/jobs/jobs.module.ts

@@ -3,6 +3,9 @@ import { BullModule } from '@nestjs/bullmq';
 import { JobsController } from './jobs.controller';
 import { RETENTION_PURGE_QUEUE } from '../retention-policy/retention-purge.processor';
 import { DlqService } from './dlq.service';
+import { SecurityEventJob } from './security-event.job';
+import { UsageTrackerModule } from '../observability/usage-tracker/usage-tracker.module';
+import { AuditModule } from '../audit/audit.module';
 
 @Module({
   imports: [
@@ -11,9 +14,11 @@ import { DlqService } from './dlq.service';
     BullModule.registerQueue({ name: 'onchain' }),
     BullModule.registerQueue({ name: RETENTION_PURGE_QUEUE }),
     BullModule.registerQueue({ name: 'dead-letter' }),
+    UsageTrackerModule,
+    AuditModule,
   ],
   controllers: [JobsController],
-  providers: [DlqService],
-  exports: [DlqService],
+  providers: [DlqService, SecurityEventJob],
+  exports: [DlqService, SecurityEventJob],
 })
 export class JobsModule {}

app/backend/src/jobs/security-event.job.spec.ts

@@ -0,0 +1,136 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { SecurityEventJob } from './security-event.job';
+import { ApiKeyUsageTrackerService } from '../observability/usage-tracker/api-key-usage-tracker.service';
+import { AuditService } from '../audit/audit.service';
+import { AnomalyEvent } from '../observability/usage-tracker/api-key-usage-tracker.service';
+
+describe('SecurityEventJob', () => {
+  let job: SecurityEventJob;
+  let auditService: AuditService;
+
+  const mockAnomaly: AnomalyEvent = {
+    keyId: 'key-123',
+    orgId: 'org-456',
+    distinctCountries: 5,
+    countries: ['US', 'GB', 'DE', 'FR', 'JP'],
+    windowStart: new Date('2024-01-01T00:00:00Z'),
+    windowEnd: new Date('2024-01-01T01:00:00Z'),
+  };
+
+  const mockUsageTracker = {
+    flushAllWindows: jest.fn(),
+  };
+
+  const mockAuditService = {
+    record: jest.fn().mockResolvedValue({ id: 'audit-1' }),
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        SecurityEventJob,
+        {
+          provide: ApiKeyUsageTrackerService,
+          useValue: mockUsageTracker,
+        },
+        {
+          provide: AuditService,
+          useValue: mockAuditService,
+        },
+      ],
+    }).compile();
+
+    job = module.get<SecurityEventJob>(SecurityEventJob);
+    auditService = module.get<AuditService>(AuditService);
+
+    jest.clearAllMocks();
+  });
+
+  it('should be defined', () => {
+    expect(job).toBeDefined();
+  });
+
+  describe('flushUsageWindows', () => {
+    it('should record audit log entries for each anomaly', async () => {
+      mockUsageTracker.flushAllWindows.mockResolvedValue([mockAnomaly]);
+
+      await job.flushUsageWindows();
+
+      expect(auditService.record).toHaveBeenCalledTimes(1);
+      expect(auditService.record).toHaveBeenCalledWith({
+        actorId: 'apikey:key-123',
+        entity: 'ApiKey',
+        entityId: 'key-123',
+        action: 'security_anomaly',
+        metadata: {
+          kind: 'api_key_anomaly',
+          distinctCountries: 5,
+          countries: ['US', 'GB', 'DE', 'FR', 'JP'],
+          orgId: 'org-456',
+          windowStart: '2024-01-01T00:00:00.000Z',
+          windowEnd: '2024-01-01T01:00:00.000Z',
+        },
+      });
+    });
+
+    it('should record multiple audit entries for multiple anomalies', async () => {
+      const anomaly2: AnomalyEvent = {
+        ...mockAnomaly,
+        keyId: 'key-789',
+        orgId: null,
+        distinctCountries: 4,
+        countries: ['US', 'GB', 'DE', 'FR'],
+      };
+      mockUsageTracker.flushAllWindows.mockResolvedValue([
+        mockAnomaly,
+        anomaly2,
+      ]);
+
+      await job.flushUsageWindows();
+
+      expect(auditService.record).toHaveBeenCalledTimes(2);
+      expect(auditService.record).toHaveBeenNthCalledWith(1, {
+        actorId: 'apikey:key-123',
+        entity: 'ApiKey',
+        entityId: 'key-123',
+        action: 'security_anomaly',
+        metadata: expect.objectContaining({ kind: 'api_key_anomaly' }),
+      });
+      expect(auditService.record).toHaveBeenNthCalledWith(2, {
+        actorId: 'apikey:key-789',
+        entity: 'ApiKey',
+        entityId: 'key-789',
+        action: 'security_anomaly',
+        metadata: expect.objectContaining({
+          orgId: null,
+          distinctCountries: 4,
+        }),
+      });
+    });
+
+    it('should not record audit entries when no anomalies', async () => {
+      mockUsageTracker.flushAllWindows.mockResolvedValue([]);
+
+      await job.flushUsageWindows();
+
+      expect(auditService.record).not.toHaveBeenCalled();
+    });
+
+    it('should handle flushAllWindows errors gracefully', async () => {
+      mockUsageTracker.flushAllWindows.mockRejectedValue(
+        new Error('Redis connection failed'),
+      );
+
+      await expect(job.flushUsageWindows()).resolves.not.toThrow();
+    });
+
+    it('should handle auditService.record errors for individual entries', async () => {
+      mockUsageTracker.flushAllWindows.mockResolvedValue([mockAnomaly]);
+      mockAuditService.record.mockRejectedValueOnce(
+        new Error('DB connection lost'),
+      );
+
+      await expect(job.flushUsageWindows()).resolves.not.toThrow();
+    });
+  });
+});

app/backend/src/jobs/security-event.job.ts

@@ -0,0 +1,67 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { ApiKeyUsageTrackerService } from '../observability/usage-tracker/api-key-usage-tracker.service';
+import { AuditService } from '../audit/audit.service';
+
+/**
+ * Scheduled job that flushes API key usage windows and writes security
+ * events to the AuditLog when anomalies are detected.
+ *
+ * Runs every hour by default. The `@Cron` decorator ensures only one
+ * instance executes across a cluster when using a distributed lock
+ * (via `@nestjs/schedule`'s `BullMQ` integration or singleton mode).
+ */
+@Injectable()
+export class SecurityEventJob {
+  private readonly logger = new Logger(SecurityEventJob.name);
+
+  constructor(
+    private readonly usageTracker: ApiKeyUsageTrackerService,
+    private readonly auditService: AuditService,
+  ) {}
+
+  @Cron(CronExpression.EVERY_HOUR)
+  async flushUsageWindows(): Promise<void> {
+    try {
+      this.logger.log('Flushing API key usage windows for security events');
+
+      const anomalies = await this.usageTracker.flushAllWindows();
+
+      for (const anomaly of anomalies) {
+        await this.auditService.record({
+          actorId: `apikey:${anomaly.keyId}`,
+          entity: 'ApiKey',
+          entityId: anomaly.keyId,
+          action: 'security_anomaly',
+          metadata: {
+            kind: 'api_key_anomaly',
+            distinctCountries: anomaly.distinctCountries,
+            countries: anomaly.countries,
+            orgId: anomaly.orgId,
+            windowStart: anomaly.windowStart.toISOString(),
+            windowEnd: anomaly.windowEnd.toISOString(),
+          },
+        });
+
+        this.logger.warn(
+          `Security event recorded: keyId=${anomaly.keyId}, ` +
+            `countries=${anomaly.distinctCountries}, ` +
+            `window=${anomaly.windowStart.toISOString()} → ${anomaly.windowEnd.toISOString()}`,
+        );
+      }
+
+      if (anomalies.length === 0) {
+        this.logger.debug('No API key anomalies detected during flush');
+      } else {
+        this.logger.warn(
+          `Recorded ${anomalies.length} security event(s) from usage flush`,
+        );
+      }
+    } catch (err) {
+      this.logger.error(
+        `Security event flush failed: ${err instanceof Error ? err.message : String(err)}`,
+        err instanceof Error ? err.stack : undefined,
+      );
+    }
+  }
+}

app/backend/src/observability/metrics/metrics.providers.ts

@@ -149,4 +149,11 @@ export const metricsProviders = [
     help: 'Total number of analytics cache invalidations',
     labelNames: ['reason'],
   }),
+
+  // Security Metrics
+  makeCounterProvider({
+    name: 'security_event_total',
+    help: 'Total number of security events detected (e.g. API key anomalies)',
+    labelNames: ['kind', 'key_id', 'org_id'],
+  }),
 ];

app/backend/src/observability/metrics/metrics.service.ts

@@ -47,6 +47,8 @@ export class MetricsService {
     public emailDeliveryCounter: Counter<string>,
     @InjectMetric('email_delivery_duration_seconds')
     public emailDeliveryDuration: Histogram<string>,
+    @InjectMetric('security_event_total')
+    public securityEventCounter: Counter<string>,
   ) {}
 
   /**
@@ -252,4 +254,11 @@ export class MetricsService {
       this.errorRateCounter.inc({ error_type: 'email_delivery_failure' });
     }
   }
+
+  /**
+   * Increment the security event counter for API key anomalies.
+   */
+  incrementSecurityEvent(kind: string, keyId: string, orgId: string): void {
+    this.securityEventCounter.inc({ kind, key_id: keyId, org_id: orgId });
+  }
 }