Merge pull request InsurNiffy#1035 from kaynaomi-oss/feature/883-geo-block-policy-initiation

Closes InsurNiffy#883

Author: jhayniffy

backend/.env.example

@@ -175,6 +175,10 @@ ADMIN_CORS_ORIGINS=http://localhost:3002
 # [optional] Canonical combined CORS allowlist. When set, takes precedence over FRONTEND_ORIGINS + ADMIN_CORS_ORIGINS.
 CORS_ALLOWED_ORIGINS=
 
+# Compliance
+# [optional] Comma-separated ISO 3166-1 alpha-2 country codes blocked from policy initiation (geo-compliance). Empty = no blocking.
+BLOCKED_COUNTRIES=
+
 # Observability
 # [required] Minimum application log level.
 LOG_LEVEL=info

backend/src/config/env.definitions.ts

@@ -56,6 +56,7 @@ export interface EnvironmentVariables {
   FRONTEND_ORIGINS: string;
   ADMIN_CORS_ORIGINS: string;
   CORS_ALLOWED_ORIGINS: string;
+  BLOCKED_COUNTRIES: string;
   LOG_LEVEL: LogLevel;
   CACHE_TTL_SECONDS: number;
   QUOTE_SIMULATION_CACHE_ENABLED: 'true' | 'false' | '1' | '0';
@@ -703,6 +704,15 @@ export const ENV_DEFINITIONS: EnvDefinitionMap = {
     required: 'optional',
     schema: Joi.string().allow('').default(''),
   },
+  BLOCKED_COUNTRIES: {
+    key: 'BLOCKED_COUNTRIES',
+    section: 'Compliance',
+    description:
+      'Comma-separated ISO 3166-1 alpha-2 country codes blocked from policy initiation (geo-compliance). Empty = no blocking.',
+    example: 'KP,IR,CU',
+    required: 'optional',
+    schema: Joi.string().allow('').default(''),
+  },
   LOG_LEVEL: {
     key: 'LOG_LEVEL',
     section: 'Observability',

backend/src/policy/__tests__/geo-block.guard.spec.ts

@@ -0,0 +1,67 @@
+/**
+ * Tests for GeoBlockGuard.
+ *
+ * Verifies:
+ *   - Requests from a blocked country are rejected with 451.
+ *   - Requests from an allowed country pass.
+ *   - A missing geo header defaults to allow (no false positives).
+ */
+
+import { ExecutionContext, HttpException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { GeoBlockGuard } from '../geo-block.guard';
+
+function makeContext(headers: Record<string, string>): ExecutionContext {
+  const request = { headers };
+  return {
+    switchToHttp: () => ({
+      getRequest: () => request,
+    }),
+  } as unknown as ExecutionContext;
+}
+
+function makeConfigService(blockedCountries: string): ConfigService {
+  return { get: () => blockedCountries } as unknown as ConfigService;
+}
+
+describe('GeoBlockGuard', () => {
+  it('rejects requests from a blocked country with 451', () => {
+    const guard = new GeoBlockGuard(makeConfigService('KP,IR,CU'));
+    const ctx = makeContext({ 'cf-ipcountry': 'IR' });
+
+    expect(() => guard.canActivate(ctx)).toThrow(HttpException);
+    try {
+      guard.canActivate(ctx);
+    } catch (err) {
+      expect((err as HttpException).getStatus()).toBe(451);
+    }
+  });
+
+  it('allows requests from a non-blocked country', () => {
+    const guard = new GeoBlockGuard(makeConfigService('KP,IR,CU'));
+    const ctx = makeContext({ 'cf-ipcountry': 'US' });
+
+    expect(guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('allows requests with no geo header (no false positives)', () => {
+    const guard = new GeoBlockGuard(makeConfigService('KP,IR,CU'));
+    const ctx = makeContext({});
+
+    expect(guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('falls back to X-Country-Code when CF-IPCountry is absent', () => {
+    const guard = new GeoBlockGuard(makeConfigService('KP,IR,CU'));
+    const ctx = makeContext({ 'x-country-code': 'kp' });
+
+    expect(() => guard.canActivate(ctx)).toThrow(HttpException);
+  });
+
+  it('allows all requests when BLOCKED_COUNTRIES is empty', () => {
+    const guard = new GeoBlockGuard(makeConfigService(''));
+    const ctx = makeContext({ 'cf-ipcountry': 'IR' });
+
+    expect(guard.canActivate(ctx)).toBe(true);
+  });
+});

backend/src/policy/geo-block.guard.ts

@@ -0,0 +1,48 @@
+/**
+ * GeoBlockGuard — optional jurisdiction block on policy initiation.
+ *
+ * Reads the CF-IPCountry header (Cloudflare) or X-Country-Code header
+ * (fallback, e.g. for non-Cloudflare deployments) and rejects requests
+ * from countries listed in the BLOCKED_COUNTRIES env var with 451
+ * (Unavailable For Legal Reasons).
+ *
+ * Fails open: a missing geo header allows the request (no false positives).
+ * Configurable without code changes via BLOCKED_COUNTRIES (comma-separated
+ * ISO 3166-1 alpha-2 codes).
+ */
+
+import { Injectable, CanActivate, ExecutionContext, HttpException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Request } from 'express';
+
+@Injectable()
+export class GeoBlockGuard implements CanActivate {
+  constructor(private readonly configService: ConfigService) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<Request>();
+    const countryCode =
+      (request.headers['cf-ipcountry'] as string | undefined) ??
+      (request.headers['x-country-code'] as string | undefined);
+
+    if (!countryCode) return true;
+
+    const blocked = (this.configService.get<string>('BLOCKED_COUNTRIES') ?? '')
+      .split(',')
+      .map((code) => code.trim().toUpperCase())
+      .filter(Boolean);
+
+    if (blocked.includes(countryCode.trim().toUpperCase())) {
+      throw new HttpException(
+        {
+          statusCode: 451,
+          error: 'Unavailable For Legal Reasons',
+          message: `Policy initiation is not available in your region (${countryCode.trim().toUpperCase()}).`,
+        },
+        451,
+      );
+    }
+
+    return true;
+  }
+}

backend/src/policy/policy.controller.ts

@@ -4,6 +4,7 @@ import { Throttle } from '@nestjs/throttler';
 import { PolicyService } from './policy.service';
 import { BuildTransactionDto } from './dto/build-transaction.dto';
 import { WalletRateLimitGuard } from '../rate-limit/wallet-rate-limit.guard';
+import { GeoBlockGuard } from './geo-block.guard';
 
 @ApiTags('Policy')
 @Controller('policy')
@@ -39,11 +40,12 @@ export class PolicyController {
   @Post('build-transaction')
   @HttpCode(HttpStatus.OK)
   @Throttle({ default: { limit: 10, ttl: 60_000 } })
-  @UseGuards(WalletRateLimitGuard)
+  @UseGuards(WalletRateLimitGuard, GeoBlockGuard)
   @ApiOperation({ summary: 'Build unsigned initiate_policy transaction' })
   @ApiResponse({ status: 200, description: 'Unsigned transaction XDR + fee estimates' })
   @ApiResponse({ status: 400, description: 'Validation / account / simulation error' })
   @ApiResponse({ status: 429, description: 'Rate limited — protects RPC quotas' })
+  @ApiResponse({ status: 451, description: 'Blocked jurisdiction (BLOCKED_COUNTRIES)' })
   @ApiResponse({ status: 503, description: 'Contract not deployed or RPC unavailable' })
   async buildTransaction(@Body() dto: BuildTransactionDto) {
     return this.policyService.buildTransaction(dto);

backend/src/policy/policy.module.ts

@@ -9,11 +9,12 @@ import { RenewalReminderService } from "./renewal-reminder.service";
 import { RpcModule } from "../rpc/rpc.module";
 import { NotificationsModule } from "../notifications/notifications.module";
 import { TenantModule } from "../tenant/tenant.module";
+import { GeoBlockGuard } from "./geo-block.guard";
 
 @Module({
   imports: [ScheduleModule.forRoot(), RpcModule, NotificationsModule, TenantModule],
   controllers: [PolicyController, RenewalController],
-  providers: [PolicyService, PolicyReadService, RenewalService, RenewalReminderService],
+  providers: [PolicyService, PolicyReadService, RenewalService, RenewalReminderService, GeoBlockGuard],
   exports: [PolicyService, PolicyReadService, RenewalService],
 })
 export class PolicyModule {}