feat(backend): gate experimental modules with feature flags

Author: Chibey-max

backend/docs/feature-flags.md

@@ -0,0 +1,35 @@
+# Backend Feature Flags Runbook
+
+## Purpose
+Feature flags gate experimental backend routes at the API edge so unfinished modules are fully unreachable when disabled.
+
+Safe default: any missing flag is treated as `false`.
+
+## Configuration
+Set `FEATURE_FLAGS_JSON` as a JSON object at process start:
+
+```bash
+FEATURE_FLAGS_JSON='{"experimental.oracleHooks":false,"experimental.betaCalculators":false}'
+```
+
+Optional response strategy for disabled routes:
+
+- `FEATURE_FLAGS_DISABLED_STATUS=404` (default, hides route existence)
+- `FEATURE_FLAGS_DISABLED_STATUS=403` (explicitly forbidden)
+
+## Current Flags
+| Flag name | Default | Owner | Meaning |
+|---|---|---|---|
+| `experimental.oracleHooks` | `false` | Backend Platform Team | Enables `/experimental/oracle-hooks/*` ingestion hooks for oracle event experiments. |
+| `experimental.betaCalculators` | `false` | Underwriting Engine Team | Enables `/experimental/beta-calculators/*` premium preview APIs under validation. |
+
+## Lifecycle
+1. Creation: add a single-purpose flag and owner in this document before merging code.
+2. Enablement: turn on only in non-production first, monitor error rate and access logs.
+3. Promotion: after stable metrics and review, enable for production rollout with change ticket.
+4. Removal: once fully adopted, delete guard/decorator usage and remove the flag from env + docs.
+
+## Operational Guardrails
+- Feature flags do not replace authentication or authorization controls.
+- Keep total flag count low to avoid long-lived configuration sprawl.
+- Disabled-access attempts are logged (`FeatureFlagsGuard`) for metrics pipelines.

backend/src/app.module.ts

@@ -16,6 +16,9 @@ import { QuoteModule } from './quote/quote.module';
 import { PolicyModule } from './policy/policy.module';
 import { NotificationsModule } from './notifications/notifications.module';
 import { TxModule } from './tx/tx.module';
+import { FeatureFlagsModule } from './feature-flags/feature-flags.module';
+import { OracleHooksController } from './experimental/oracle-hooks.controller';
+import { BetaCalculatorsController } from './experimental/beta-calculators.controller';
 
 @Module({
   imports: [
@@ -42,7 +45,8 @@ import { TxModule } from './tx/tx.module';
     PolicyModule,
     NotificationsModule,
     TxModule,
+    FeatureFlagsModule,
   ],
+  controllers: [OracleHooksController, BetaCalculatorsController],
 })
 export class AppModule {}
-

backend/src/dto/beta-calculator.dto.ts

@@ -0,0 +1,11 @@
+import { IsNumber, Min } from 'class-validator';
+
+export class BetaCalculatorDto {
+  @IsNumber()
+  @Min(0)
+  basePremium!: number;
+
+  @IsNumber()
+  @Min(0)
+  riskMultiplier!: number;
+}

backend/src/experimental/beta-calculators.controller.ts

@@ -0,0 +1,14 @@
+import { Body, Controller, Post } from '@nestjs/common';
+import { BetaCalculatorDto } from '../dto/beta-calculator.dto';
+import { Feature } from '../feature-flags/feature.decorator';
+
+@Controller('experimental/beta-calculators')
+@Feature('experimental.betaCalculators')
+export class BetaCalculatorsController {
+  @Post('premium-preview')
+  premiumPreview(@Body() body: BetaCalculatorDto) {
+    return {
+      premium: Number((body.basePremium * body.riskMultiplier).toFixed(2)),
+    };
+  }
+}

backend/src/experimental/oracle-hooks.controller.ts

@@ -0,0 +1,14 @@
+import { Body, Controller, Post } from '@nestjs/common';
+import { Feature } from '../feature-flags/feature.decorator';
+
+@Controller('experimental/oracle-hooks')
+@Feature('experimental.oracleHooks')
+export class OracleHooksController {
+  @Post('ingest')
+  ingest(@Body() body: Record<string, unknown>) {
+    return {
+      accepted: true,
+      receivedKeys: Object.keys(body || {}),
+    };
+  }
+}

backend/src/feature-flags/constants.ts

@@ -0,0 +1,4 @@
+export const FEATURE_METADATA_KEY = 'feature_flag_name';
+
+export const FEATURE_FLAGS_JSON_ENV = 'FEATURE_FLAGS_JSON';
+export const FEATURE_FLAGS_DISABLED_STATUS_ENV = 'FEATURE_FLAGS_DISABLED_STATUS';

backend/src/feature-flags/feature-flags.bootstrap.ts

@@ -0,0 +1,16 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { FeatureFlagsService } from './feature-flags.service';
+
+@Injectable()
+export class FeatureFlagsBootstrap implements OnModuleInit {
+  private readonly logger = new Logger(FeatureFlagsBootstrap.name);
+
+  constructor(private readonly featureFlagsService: FeatureFlagsService) {}
+
+  onModuleInit() {
+    const flags = this.featureFlagsService.getFlags();
+    this.logger.log(
+      `Feature flags loaded at boot: ${Object.keys(flags).length} configured flag(s)`,
+    );
+  }
+}

backend/src/feature-flags/feature-flags.guard.ts

@@ -0,0 +1,43 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { FEATURE_METADATA_KEY } from './constants';
+import { FeatureFlagsService } from './feature-flags.service';
+
+@Injectable()
+export class FeatureFlagsGuard implements CanActivate {
+  private readonly logger = new Logger(FeatureFlagsGuard.name);
+
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly featureFlagsService: FeatureFlagsService,
+  ) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const featureName = this.reflector.getAllAndOverride<string>(
+      FEATURE_METADATA_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!featureName || this.featureFlagsService.isEnabled(featureName)) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest();
+    this.logger.warn(
+      `Blocked disabled feature access feature=${featureName} method=${request.method} path=${request.url} ip=${request.ip}`,
+    );
+
+    if (this.featureFlagsService.getDisabledStatusCode() === 403) {
+      throw new ForbiddenException('Feature disabled');
+    }
+
+    throw new NotFoundException('Feature disabled');
+  }
+}

backend/src/feature-flags/feature-flags.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { FeatureFlagsService } from './feature-flags.service';
+import { FeatureFlagsGuard } from './feature-flags.guard';
+import { FeatureFlagsBootstrap } from './feature-flags.bootstrap';
+
+@Module({
+  providers: [FeatureFlagsService, FeatureFlagsGuard, FeatureFlagsBootstrap],
+  exports: [FeatureFlagsService, FeatureFlagsGuard],
+})
+export class FeatureFlagsModule {}

backend/src/feature-flags/feature-flags.service.ts

@@ -0,0 +1,52 @@
+import { Injectable, Logger } from '@nestjs/common';
+import {
+  FEATURE_FLAGS_DISABLED_STATUS_ENV,
+  FEATURE_FLAGS_JSON_ENV,
+} from './constants';
+
+type FeatureMap = Record<string, boolean>;
+
+@Injectable()
+export class FeatureFlagsService {
+  private readonly logger = new Logger(FeatureFlagsService.name);
+  private readonly featureMap: FeatureMap;
+  private readonly disabledStatusCode: 403 | 404;
+
+  constructor() {
+    this.featureMap = this.parseFlags(process.env[FEATURE_FLAGS_JSON_ENV]);
+    this.disabledStatusCode =
+      process.env[FEATURE_FLAGS_DISABLED_STATUS_ENV] === '403' ? 403 : 404;
+  }
+
+  isEnabled(featureName: string): boolean {
+    return this.featureMap[featureName] === true;
+  }
+
+  getDisabledStatusCode(): 403 | 404 {
+    return this.disabledStatusCode;
+  }
+
+  getFlags(): FeatureMap {
+    return { ...this.featureMap };
+  }
+
+  private parseFlags(rawValue: string | undefined): FeatureMap {
+    if (!rawValue) {
+      return {};
+    }
+
+    try {
+      const parsed = JSON.parse(rawValue) as Record<string, unknown>;
+      return Object.entries(parsed).reduce<FeatureMap>((acc, [key, value]) => {
+        acc[key] = value === true;
+        return acc;
+      }, {});
+    } catch (error) {
+      const details = error instanceof Error ? error.message : String(error);
+      this.logger.error(
+        `${FEATURE_FLAGS_JSON_ENV} is not valid JSON; defaulting all features to disabled. ${details}`,
+      );
+      return {};
+    }
+  }
+}