Merge pull request #1162 from Osifowora/Storage-Upload-Quotas

feat(backend): add per-user storage upload quotas + per-user upload rate limiting

Author: Devsol-01

backend/src/app.module.ts

@@ -12,6 +12,7 @@ import { IdempotencyInterceptor } from './common/interceptors/idempotency.interc
 import { MetricsInterceptor } from './common/interceptors/metrics.interceptor';
 import { AdminConfirmationInterceptor } from './common/interceptors/admin-confirmation.interceptor';
 import { AdminConfirmationFilter } from './common/filters/admin-confirmation.filter';
+import { StorageQuotaExceptionFilter } from './common/filters/storage-quota-exception.filter';
 import { TieredThrottlerGuard } from './common/guards/tiered-throttler.guard';
 import { AdminConfirmationGuard } from './common/guards/admin-confirmation.guard';
 import { CommonModule } from './common/common.module';
@@ -64,6 +65,7 @@ import { SandboxModule } from './modules/sandbox/sandbox.module';
 import { FeedbackModule } from './modules/feedback/feedback.module';
 import { StatisticsModule } from './modules/statistics/statistics.module';
 import { FeatureFlagsModule } from './modules/feature-flags/feature-flags.module';
+import { StorageQuotaModule } from './modules/storage-quota/storage-quota.module';
 
 const envValidationSchema = Joi.object({
   NODE_ENV: Joi.string().valid('development', 'production', 'test').required(),
@@ -342,6 +344,7 @@ const envValidationSchema = Joi.object({
     SandboxModule,
     FeedbackModule,
     CommonModule,
+    StorageQuotaModule,
     ThrottlerModule.forRoot([
       {
         name: 'default',
@@ -385,6 +388,14 @@ const envValidationSchema = Joi.object({
         ttl: 60_000, // 1 minute
         limit: 10,
       },
+      {
+        // Upload endpoints (avatar / KYC documents / dispute evidence /
+        // feedback screenshots). Per-tier cap is enforced by TieredThrottlerGuard;
+        // this top-level limit exists as a safety floor for anonymous traffic.
+        name: 'upload',
+        ttl: 60_000, // 1 minute
+        limit: 5,
+      },
       {
         // Admin high-risk endpoints require confirmation and tight throttling.
         // Intentionally restrictive: 2 requests per 5 minutes per admin.
@@ -410,6 +421,10 @@ const envValidationSchema = Joi.object({
       provide: APP_FILTER,
       useClass: AdminConfirmationFilter,
     },
+    {
+      provide: APP_FILTER,
+      useClass: StorageQuotaExceptionFilter,
+    },
     {
       provide: APP_INTERCEPTOR,
       useClass: RequestLoggingInterceptor,
@@ -443,7 +458,11 @@ const envValidationSchema = Joi.object({
 export class AppModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
     consumer
-      .apply(CorrelationIdMiddleware, CompressionMetricsMiddleware, TenantContextMiddleware)
+      .apply(
+        CorrelationIdMiddleware,
+        CompressionMetricsMiddleware,
+        TenantContextMiddleware,
+      )
       .forRoutes('*');
   }
 }

backend/src/common/filters/storage-quota-exception.filter.ts

@@ -0,0 +1,60 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common';
+import { Response, Request } from 'express';
+import { StorageQuotaExceededException } from '../../modules/storage-quota/storage-quota.types';
+
+/**
+ * Maps {@link StorageQuotaExceededException} to an HTTP response.
+ *
+ * Status code policy:
+ *   - 'storage'      → 402 Payment Required (semantically: quota is
+ *                       capacity-bound, not request-bound).
+ *   - 'concurrency'  → 429 Too Many Requests.
+ *   - 'frequency'    → 429 Too Many Requests.
+ *
+ * The downstream rate-limiter (`TieredThrottlerGuard`) already produces
+ * 429s for the upload throttler bucket, so when this filter fires the
+ * exception has already escaped that layer and represents a deeper
+ * capacity / concurrency check.
+ *
+ * Kept globally registered in CommonModule; any other HTTP exception
+ * falls through to the standard Nest filter chain.
+ */
+@Catch(StorageQuotaExceededException)
+export class StorageQuotaExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(StorageQuotaExceptionFilter.name);
+
+  catch(exception: StorageQuotaExceededException, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const status =
+      exception.kind === 'storage'
+        ? HttpStatus.PAYMENT_REQUIRED
+        : HttpStatus.TOO_MANY_REQUESTS;
+
+    const body = {
+      success: false,
+      statusCode: status,
+      errorCode: exception.code,
+      quotaKind: exception.kind,
+      message: exception.message,
+      meta: exception.meta,
+      endpoint: `${request?.method ?? '?'} ${request?.originalUrl ?? request?.url ?? '/'}`,
+      timestamp: new Date().toISOString(),
+    };
+
+    this.logger.warn(
+      `[storage-quota] ${exception.kind} ${request?.method ?? '?'} ${request?.originalUrl ?? request?.url ?? '/'} — ${exception.message}`,
+    );
+
+    response.status(status).json(body);
+  }
+}

backend/src/common/guards/tiered-throttler.guard.ts

@@ -39,6 +39,7 @@ const TIER_LIMITS: Record<
     rpc: { limit: 5, ttl: 60000 },
     export: { limit: 1, ttl: 15 * 60 * 1000 },
     vote: { limit: 5, ttl: 60_000 },
+    upload: { limit: 10, ttl: 60_000 },
     'admin-high-risk': { limit: 0, ttl: 5 * 60 * 1000 }, // Not allowed
   },
   [UserTier.VERIFIED]: {
@@ -49,6 +50,7 @@ const TIER_LIMITS: Record<
     rpc: { limit: 15, ttl: 60000 },
     export: { limit: 3, ttl: 15 * 60 * 1000 },
     vote: { limit: 10, ttl: 60_000 },
+    upload: { limit: 30, ttl: 60_000 },
     'admin-high-risk': { limit: 0, ttl: 5 * 60 * 1000 }, // Not allowed
   },
   [UserTier.PREMIUM]: {
@@ -59,6 +61,7 @@ const TIER_LIMITS: Record<
     rpc: { limit: 30, ttl: 60000 },
     export: { limit: 4, ttl: 15 * 60 * 1000 },
     vote: { limit: 20, ttl: 60_000 },
+    upload: { limit: 60, ttl: 60_000 },
     'admin-high-risk': { limit: 0, ttl: 5 * 60 * 1000 }, // Not allowed
   },
   [UserTier.ENTERPRISE]: {
@@ -69,6 +72,7 @@ const TIER_LIMITS: Record<
     rpc: { limit: 100, ttl: 60000 },
     export: { limit: 8, ttl: 15 * 60 * 1000 },
     vote: { limit: 30, ttl: 60_000 },
+    upload: { limit: 120, ttl: 60_000 },
     'admin-high-risk': { limit: 0, ttl: 5 * 60 * 1000 }, // Not allowed
   },
   [UserTier.ADMIN]: {
@@ -79,6 +83,7 @@ const TIER_LIMITS: Record<
     rpc: { limit: 100, ttl: 60000 },
     export: { limit: 6, ttl: 15 * 60 * 1000 },
     vote: { limit: 30, ttl: 60_000 },
+    upload: { limit: 240, ttl: 60_000 },
     'admin-high-risk': { limit: 2, ttl: 5 * 60 * 1000 }, // 2 per 5 minutes
   },
 };
@@ -201,10 +206,7 @@ export class TieredThrottlerGuard extends ThrottlerGuard {
 
         response.setHeader('Retry-After', retryAfter);
         response.setHeader('X-RateLimit-Remaining', 0);
-        response.setHeader(
-          'X-RateLimit-Reset',
-          resetAt,
-        );
+        response.setHeader('X-RateLimit-Reset', resetAt);
 
         throw new HttpException(
           {

backend/src/config/configuration.ts

@@ -241,6 +241,17 @@ export default () => ({
     localDir: process.env.STORAGE_LOCAL_DIR || './uploads',
     virusScanningEnabled: process.env.UPLOAD_VIRUS_SCANNING === 'true',
   },
+  storageQuota: {
+    enabled: process.env.STORAGE_QUOTA_ENABLED !== 'false',
+    reservationTtlHours: parseInt(
+      process.env.STORAGE_QUOTA_RESERVATION_TTL_HOURS || '4',
+      10,
+    ),
+    cleanupIntervalMinutes: parseInt(
+      process.env.STORAGE_QUOTA_CLEANUP_INTERVAL_MINUTES || '15',
+      10,
+    ),
+  },
   adminNotifications: {
     maxPerMinute: parseInt(process.env.ADMIN_NOTIF_MAX_PER_MINUTE || '60', 10),
     maxPerHour: parseInt(process.env.ADMIN_NOTIF_MAX_PER_HOUR || '500', 10),

backend/src/migrations/1800460000000-CreateStorageQuotasTables.ts

@@ -0,0 +1,72 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CreateStorageQuotasTables1800460000000 implements MigrationInterface {
+  name = 'CreateStorageQuotasTables1800460000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS "storage_quotas" (
+        "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+        "userId" uuid NOT NULL,
+        "tenantId" varchar(64) NOT NULL DEFAULT '',
+        "maxTotalBytes" bigint NOT NULL DEFAULT 0,
+        "usedBytes" bigint NOT NULL DEFAULT 0,
+        "reservedBytes" bigint NOT NULL DEFAULT 0,
+        "maxActiveUploads" integer NOT NULL DEFAULT 0,
+        "activeUploads" integer NOT NULL DEFAULT 0,
+        "maxUploadsPerHour" integer NOT NULL DEFAULT 0,
+        "uploadsThisHour" integer NOT NULL DEFAULT 0,
+        "uploadWindowStartedAt" timestamptz NULL,
+        "tier" varchar(32) NOT NULL DEFAULT 'free',
+        "createdAt" timestamptz NOT NULL DEFAULT now(),
+        "updatedAt" timestamptz NOT NULL DEFAULT now(),
+        "version" integer NOT NULL DEFAULT 0,
+        CONSTRAINT "uq_storage_quotas_user_tenant" UNIQUE ("userId", "tenantId"),
+        CONSTRAINT "pk_storage_quotas" PRIMARY KEY ("id")
+      )
+    `);
+
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "idx_storage_quotas_user" ON "storage_quotas" ("userId")`,
+    );
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS "storage_quota_ledger" (
+        "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+        "reservationId" varchar(64) NOT NULL,
+        "userId" uuid NOT NULL,
+        "tenantId" varchar(64) NOT NULL DEFAULT '',
+        "uploadKind" varchar(32) NOT NULL DEFAULT 'generic',
+        "uploadId" varchar(128) NULL,
+        "byteDelta" bigint NOT NULL,
+        "status" varchar(16) NOT NULL DEFAULT 'pending',
+        "expiresAt" timestamptz NULL,
+        "finalBytes" bigint NULL,
+        "reason" varchar(256) NULL,
+        "createdAt" timestamptz NOT NULL DEFAULT now(),
+        CONSTRAINT "uq_storage_quota_ledger_reservation" UNIQUE ("reservationId"),
+        CONSTRAINT "pk_storage_quota_ledger" PRIMARY KEY ("id")
+      )
+    `);
+
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "idx_storage_quota_ledger_user_created" ON "storage_quota_ledger" ("userId", "createdAt")`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "idx_storage_quota_ledger_tenant_created" ON "storage_quota_ledger" ("tenantId", "createdAt")`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "idx_storage_quota_ledger_status_expires" ON "storage_quota_ledger" ("status", "expiresAt")`,
+    );
+    await queryRunner.query(
+      `CREATE INDEX IF NOT EXISTS "idx_storage_quota_ledger_upload" ON "storage_quota_ledger" ("uploadKind", "uploadId")`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS "storage_quota_ledger"`);
+    await queryRunner.query(`DROP TABLE IF EXISTS "storage_quotas"`);
+  }
+}

backend/src/modules/disputes/disputes.service.ts

@@ -31,6 +31,11 @@ import {
 } from '../../common/entities/audit-log.entity';
 import { StorageService } from '../storage/storage.service';
 import { JobQueueService } from '../job-queue/job-queue.service';
+import {
+  StorageQuotaService,
+  QuotaReservation,
+} from '../storage-quota/storage-quota.service';
+import { QuotaUploadKind } from '../storage-quota/entities/storage-quota-ledger.entity';
 
 const ALLOWED_TRANSITIONS: Record<DisputeStatus, DisputeStatus[]> = {
   [DisputeStatus.OPEN]: [
@@ -87,6 +92,7 @@ export class DisputesService {
     private readonly auditLogService: AuditLogService,
     private readonly storageService: StorageService,
     private readonly jobQueueService: JobQueueService,
+    private readonly quotaService: StorageQuotaService,
   ) {}
 
   async createDispute(
@@ -392,12 +398,43 @@ export class DisputesService {
     dto: UploadEvidenceDto,
   ): Promise<DisputeEvidence> {
     // Verify dispute exists
-    await this.findOne(disputeId);
+    const dispute = await this.findOne(disputeId);
+
+    // Reserve quota BEFORE writing to storage. Attribution goes to the
+    // disputer only — `dto.uploadedBy` is a freeform staff label (e.g.
+    // "Hospital Admin") and must NOT be used as the quota userId, since
+    // it is not a UUID and would collide with other staff uploads for
+    // the same dispute on the (userId, tenantId) UNIQUE index.
+    const attributedUserId = dispute.disputedBy;
+    if (!attributedUserId) {
+      throw new BadRequestException(
+        'Cannot attribute upload quota: dispute has no attributed disputer',
+      );
+    }
+    await this.quotaService.ensureQuotaRow(attributedUserId, 'verified');
+
+    const reservation: QuotaReservation = await this.quotaService.reserve(
+      attributedUserId,
+      file.size,
+      {
+        uploadKind: QuotaUploadKind.DISPUTE_EVIDENCE,
+        reason: 'dispute-evidence',
+      },
+    );
 
-    // Persist file to storage
-    const storagePath = await this.storageService.saveFile(file);
+    // Write file. If this fails we MUST release the reservation.
+    let storagePath: string;
+    try {
+      storagePath = await this.storageService.saveFile(file);
+    } catch (err) {
+      await this.quotaService.release(reservation.reservationId, {
+        reason: 'storage-write-failed',
+      });
+      throw err;
+    }
 
-    // Create evidence record with PENDING status
+    // Create evidence record with PENDING status and the reservation token
+    // so the dispute-evidence processor can reconcile on completion.
     const evidence = this.evidenceRepository.create({
       disputeId,
       originalFilename: file.originalname,
@@ -407,18 +444,27 @@ export class DisputesService {
       uploadedBy: dto.uploadedBy,
       processingStatus: EvidenceProcessingStatus.PENDING,
       jobId: null,
+      quotaReservationId: reservation.reservationId,
     });
     const savedEvidence = await this.evidenceRepository.save(evidence);
 
     // Enqueue background processing job
-    const job = await this.jobQueueService.addEvidenceProcessingJob({
-      evidenceId: savedEvidence.id,
-      disputeId,
-      storagePath,
-      mimeType: file.mimetype,
-      originalFilename: file.originalname,
-      uploadedBy: dto.uploadedBy,
-    });
+    let job;
+    try {
+      job = await this.jobQueueService.addEvidenceProcessingJob({
+        evidenceId: savedEvidence.id,
+        disputeId,
+        storagePath,
+        mimeType: file.mimetype,
+        originalFilename: file.originalname,
+        uploadedBy: dto.uploadedBy,
+      });
+    } catch (err) {
+      await this.quotaService.release(reservation.reservationId, {
+        reason: 'job-enqueue-failed',
+      });
+      throw err;
+    }
 
     // Store job ID on the evidence record for status polling
     await this.evidenceRepository.update(savedEvidence.id, {

backend/src/modules/disputes/entities/dispute-evidence.entity.ts

@@ -75,6 +75,17 @@ export class DisputeEvidence {
   @Column({ type: 'jsonb', nullable: true })
   processingMetadata: Record<string, any> | null;
 
+  /**
+   * Token returned by {@link StorageQuotaService.reserve} when the evidence
+   * upload was accepted. The dispute-evidence processor calls `commit()`
+   * on success or `release()` on failure so the per-user quota ledger
+   * reconciles correctly even when the upload is short-circuited.
+   */
+  @ApiProperty({ nullable: true })
+  @Index()
+  @Column({ type: 'varchar', length: 64, nullable: true })
+  quotaReservationId: string | null;
+
   @ApiProperty()
   @CreateDateColumn()
   createdAt: Date;