Merge pull request #145 from Chisom92/feat/51-admin-operational-api

51 admin operational api

Author: jhayniffy

backend/.env.example

@@ -40,6 +40,12 @@ JWT_SECRET=super-secret-jwt-key-change-in-prod
 JWT_EXPIRES_IN=7d
 ADMIN_TOKEN=admin-token-for-cli
 
+# CORS
+# Comma-separated list of allowed origins for the public API
+CORS_ORIGINS=http://localhost:3001
+# Comma-separated list of allowed origins for the admin UI (separate from public)
+ADMIN_CORS_ORIGINS=http://localhost:3002
+
 # Staff Auth (required in non-production)
 DEFAULT_ADMIN_EMAIL=admin@niffyinsure.com
 DEFAULT_ADMIN_PASSWORD=

backend/prisma/schema.prisma

@@ -129,6 +129,33 @@ enum VoteType {
   REJECT
 }
 
+/// Immutable operational audit trail written by admin endpoints.
+/// Rows must never be updated or deleted — append-only.
+model AdminAuditLog {
+  id          String   @id @default(uuid())
+  actor       String   /// wallet address or staff email of the operator
+  action      String   /// e.g. "reindex", "pause", "feature_flag_update"
+  payload     Json     /// full request payload for forensic replay
+  ipAddress   String?
+  createdAt   DateTime @default(now())
+
+  @@index([actor])
+  @@index([action])
+  @@index([createdAt])
+  @@map("admin_audit_logs")
+}
+
+/// Runtime feature flags toggled by admin operators.
+model FeatureFlag {
+  key         String   @id
+  enabled     Boolean  @default(false)
+  description String?
+  updatedBy   String
+  updatedAt   DateTime @updatedAt
+
+  @@map("feature_flags")
+}
+
 /// Off-chain metadata for allowlisted SEP-41 asset contracts.
 /// Populated by the indexer when it observes AssetAdded events.
 /// Used by the frontend and API to display correct symbol/decimals.

backend/src/admin/admin.controller.spec.ts

@@ -0,0 +1,95 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { ForbiddenException } from '@nestjs/common';
+import { AdminController } from './admin.controller';
+import { AdminService } from './admin.service';
+import { AuditService } from './audit.service';
+import { AdminRoleGuard } from './guards/admin-role.guard';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+
+const mockAdminService = { enqueueReindex: jest.fn(), setFeatureFlag: jest.fn(), getFeatureFlags: jest.fn() };
+const mockAuditService = { write: jest.fn(), findAll: jest.fn() };
+
+const adminReq = (role = 'admin') => ({ user: { walletAddress: 'GADMIN', role }, ip: '127.0.0.1' });
+
+describe('AdminController', () => {
+  let controller: AdminController;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [AdminController],
+      providers: [
+        { provide: AdminService, useValue: mockAdminService },
+        { provide: AuditService, useValue: mockAuditService },
+      ],
+    })
+      .overrideGuard(JwtAuthGuard).useValue({ canActivate: () => true })
+      .overrideGuard(AdminRoleGuard).useValue({ canActivate: (ctx: any) => {
+        const role = ctx.switchToHttp().getRequest().user?.role;
+        if (role !== 'admin') throw new ForbiddenException('Admin role required');
+        return true;
+      }})
+      .compile();
+
+    controller = module.get(AdminController);
+  });
+
+  describe('POST /admin/reindex', () => {
+    it('enqueues job and writes audit row', async () => {
+      mockAdminService.enqueueReindex.mockResolvedValue('job-123');
+      const result = await controller.reindex({ fromLedger: 500 }, adminReq() as any);
+      expect(result).toEqual({ jobId: 'job-123', fromLedger: 500, status: 'queued' });
+      expect(mockAdminService.enqueueReindex).toHaveBeenCalledWith(500);
+      expect(mockAuditService.write).toHaveBeenCalledWith(
+        expect.objectContaining({ actor: 'GADMIN', action: 'reindex', payload: expect.objectContaining({ fromLedger: 500 }) }),
+      );
+    });
+  });
+
+  describe('GET /admin/audits', () => {
+    it('returns paginated audit logs', async () => {
+      mockAuditService.findAll.mockResolvedValue({ items: [], total: 0, page: 1, limit: 20 });
+      const result = await controller.getAudits({ page: 1, limit: 20 });
+      expect(mockAuditService.findAll).toHaveBeenCalledWith(1, 20, undefined);
+      expect(result.total).toBe(0);
+    });
+  });
+
+  describe('PATCH /admin/feature-flags/:key', () => {
+    it('updates flag and writes audit row', async () => {
+      const flag = { key: 'claims_enabled', enabled: false, updatedBy: 'GADMIN' };
+      mockAdminService.setFeatureFlag.mockResolvedValue(flag);
+      const result = await controller.setFeatureFlag('claims_enabled', { enabled: false }, adminReq() as any);
+      expect(result).toEqual(flag);
+      expect(mockAuditService.write).toHaveBeenCalledWith(
+        expect.objectContaining({ action: 'feature_flag_update', payload: expect.objectContaining({ key: 'claims_enabled', enabled: false }) }),
+      );
+    });
+  });
+
+  describe('Role guard — non-admin access denied', () => {
+    it('throws ForbiddenException for support_readonly on reindex', async () => {
+      const guard = new AdminRoleGuard();
+      const ctx = {
+        switchToHttp: () => ({ getRequest: () => ({ user: { role: 'support_readonly' } }) }),
+      } as any;
+      expect(() => guard.canActivate(ctx)).toThrow(ForbiddenException);
+    });
+
+    it('throws ForbiddenException when no user present', async () => {
+      const guard = new AdminRoleGuard();
+      const ctx = {
+        switchToHttp: () => ({ getRequest: () => ({}) }),
+      } as any;
+      expect(() => guard.canActivate(ctx)).toThrow(ForbiddenException);
+    });
+
+    it('allows admin role through', () => {
+      const guard = new AdminRoleGuard();
+      const ctx = {
+        switchToHttp: () => ({ getRequest: () => ({ user: { role: 'admin' } }) }),
+      } as any;
+      expect(guard.canActivate(ctx)).toBe(true);
+    });
+  });
+});

backend/src/admin/admin.controller.ts

@@ -0,0 +1,110 @@
+import {
+  Controller,
+  Post,
+  Get,
+  Patch,
+  Body,
+  Param,
+  Query,
+  UseGuards,
+  Req,
+  HttpCode,
+  HttpStatus,
+} from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { Request } from 'express';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { AdminRoleGuard } from './guards/admin-role.guard';
+import { AdminService } from './admin.service';
+import { AuditService } from './audit.service';
+import { ReindexDto } from './dto/reindex.dto';
+import { AuditQueryDto } from './dto/audit-query.dto';
+import { FeatureFlagDto } from './dto/feature-flag.dto';
+
+@ApiTags('admin')
+@ApiBearerAuth('JWT-auth')
+@UseGuards(JwtAuthGuard, AdminRoleGuard)
+@Controller('admin')
+export class AdminController {
+  constructor(
+    private readonly adminService: AdminService,
+    private readonly auditService: AuditService,
+  ) {}
+
+  /**
+   * POST /admin/reindex
+   *
+   * Enqueues an async reindex job starting from the given ledger sequence.
+   * Returns a jobId so operators can track progress via the queue dashboard.
+   *
+   * Requires: admin role + valid JWT.
+   * Writes an immutable audit row with actor and full payload.
+   */
+  @Post('reindex')
+  @HttpCode(HttpStatus.ACCEPTED)
+  @ApiOperation({ summary: 'Enqueue a ledger reindex job from a given ledger' })
+  async reindex(@Body() dto: ReindexDto, @Req() req: Request) {
+    const actor = (req.user as any)?.walletAddress ?? 'unknown';
+    const jobId = await this.adminService.enqueueReindex(dto.fromLedger);
+    await this.auditService.write({
+      actor,
+      action: 'reindex',
+      payload: { fromLedger: dto.fromLedger, jobId },
+      ipAddress: req.ip,
+    });
+    return { jobId, fromLedger: dto.fromLedger, status: 'queued' };
+  }
+
+  /**
+   * GET /admin/audits
+   *
+   * Paginated read of the immutable admin audit log.
+   * Requires: admin role + valid JWT.
+   */
+  @Get('audits')
+  @ApiOperation({ summary: 'Paginated admin audit log' })
+  async getAudits(@Query() query: AuditQueryDto) {
+    return this.auditService.findAll(query.page, query.limit, query.action);
+  }
+
+  /**
+   * GET /admin/feature-flags
+   *
+   * Lists all feature flags and their current state.
+   */
+  @Get('feature-flags')
+  @ApiOperation({ summary: 'List all feature flags' })
+  async listFeatureFlags() {
+    return this.adminService.getFeatureFlags();
+  }
+
+  /**
+   * PATCH /admin/feature-flags/:key
+   *
+   * Toggles a feature flag on or off.
+   * Writes an immutable audit row with actor and full payload.
+   *
+   * Legal note: disabling flags that gate user-facing activity (e.g. claim
+   * filing, policy creation) constitutes a staff-initiated pause of user
+   * operations. Such actions must be authorised by a designated compliance
+   * officer and are subject to applicable insurance-regulation obligations.
+   * The audit row created here serves as the immutable record of that action.
+   */
+  @Patch('feature-flags/:key')
+  @ApiOperation({ summary: 'Set a feature flag value' })
+  async setFeatureFlag(
+    @Param('key') key: string,
+    @Body() dto: FeatureFlagDto,
+    @Req() req: Request,
+  ) {
+    const actor = (req.user as any)?.walletAddress ?? 'unknown';
+    const flag = await this.adminService.setFeatureFlag(key, dto.enabled, dto.description, actor);
+    await this.auditService.write({
+      actor,
+      action: 'feature_flag_update',
+      payload: { key, enabled: dto.enabled, description: dto.description },
+      ipAddress: req.ip,
+    });
+    return flag;
+  }
+}

backend/src/admin/admin.module.ts

@@ -1,9 +1,14 @@
 import { Module } from '@nestjs/common';
+import { AdminController } from './admin.controller';
+import { AdminService } from './admin.service';
+import { AuditService } from './audit.service';
+import { PrismaModule } from '../prisma/prisma.module';
+import { AuthModule } from '../auth/auth.module';
 
 @Module({
-  // controllers: [AdminController],
-  // providers: [AdminService],
-  // exports: [AdminService],
+  imports: [PrismaModule, AuthModule],
+  controllers: [AdminController],
+  providers: [AdminService, AuditService],
+  exports: [AuditService],
 })
 export class AdminModule {}
-

backend/src/admin/admin.service.ts

@@ -0,0 +1,40 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { PrismaService } from '../prisma/prisma.service';
+import { Queue } from 'bullmq';
+import { getBullMQConnection } from '../redis/client';
+
+@Injectable()
+export class AdminService {
+  private readonly logger = new Logger(AdminService.name);
+  private reindexQueue: Queue;
+
+  constructor(private readonly prisma: PrismaService) {
+    this.reindexQueue = new Queue('reindex', {
+      connection: getBullMQConnection(),
+      defaultJobOptions: {
+        attempts: 3,
+        backoff: { type: 'exponential', delay: 2_000 },
+        removeOnComplete: { count: 50 },
+        removeOnFail: { count: 100 },
+      },
+    });
+  }
+
+  async enqueueReindex(fromLedger: number): Promise<string> {
+    const job = await this.reindexQueue.add('reindex', { fromLedger }, { jobId: `reindex-${fromLedger}-${Date.now()}` });
+    this.logger.log(`Reindex job enqueued: ${job.id} from ledger ${fromLedger}`);
+    return job.id!;
+  }
+
+  async setFeatureFlag(key: string, enabled: boolean, description: string | undefined, actor: string) {
+    return this.prisma.featureFlag.upsert({
+      where: { key },
+      create: { key, enabled, description, updatedBy: actor },
+      update: { enabled, description, updatedBy: actor },
+    });
+  }
+
+  async getFeatureFlags() {
+    return this.prisma.featureFlag.findMany({ orderBy: { key: 'asc' } });
+  }
+}

backend/src/admin/audit.service.ts

@@ -0,0 +1,32 @@
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from '../prisma/prisma.service';
+
+export interface AuditMeta {
+  actor: string;
+  action: string;
+  payload: Record<string, unknown>;
+  ipAddress?: string;
+}
+
+@Injectable()
+export class AuditService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async write(meta: AuditMeta): Promise<void> {
+    await this.prisma.adminAuditLog.create({ data: meta });
+  }
+
+  async findAll(page: number, limit: number, action?: string) {
+    const where = action ? { action } : {};
+    const [items, total] = await Promise.all([
+      this.prisma.adminAuditLog.findMany({
+        where,
+        orderBy: { createdAt: 'desc' },
+        skip: (page - 1) * limit,
+        take: limit,
+      }),
+      this.prisma.adminAuditLog.count({ where }),
+    ]);
+    return { items, total, page, limit };
+  }
+}

backend/src/admin/dto/audit-query.dto.ts

@@ -0,0 +1,25 @@
+import { IsOptional, IsInt, Min, Max, IsString } from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class AuditQueryDto {
+  @ApiPropertyOptional({ default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page: number = 1;
+
+  @ApiPropertyOptional({ default: 20, maximum: 100 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit: number = 20;
+
+  @ApiPropertyOptional({ description: 'Filter by action type' })
+  @IsOptional()
+  @IsString()
+  action?: string;
+}

backend/src/admin/dto/feature-flag.dto.ts

@@ -0,0 +1,13 @@
+import { IsBoolean, IsOptional, IsString } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class FeatureFlagDto {
+  @ApiProperty()
+  @IsBoolean()
+  enabled!: boolean;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  description?: string;
+}

backend/src/admin/dto/reindex.dto.ts

@@ -0,0 +1,9 @@
+import { IsInt, Min } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ReindexDto {
+  @ApiProperty({ description: 'Ledger sequence to reindex from', minimum: 0 })
+  @IsInt()
+  @Min(0)
+  fromLedger!: number;
+}