Merge branch 'main' into branding/theme

Author: jhayniffy

.github/workflows/ci.yml

@@ -39,6 +39,21 @@ jobs:
       - name: Record wasm SHA-256
         run: sha256sum target/wasm32-unknown-unknown/release/niffyinsure.wasm | tee niffyinsure.wasm.sha256
 
+      - name: Simulate wasm drift (staging acceptance test)
+        run: |
+          ACTUAL=$(cat niffyinsure.wasm.sha256 | awk '{print $1}')
+          EXPECTED=$(jq -r '.contracts[0].expectedWasmHash' contracts/deployment-registry.json)
+          # In CI the registry holds a placeholder; drift is detected when they differ.
+          # In staging, set NIFFYINSURE_EXPECTED_WASM_HASH to a known-wrong value to
+          # verify the alert path fires. Exit 0 here — alerting is runtime, not build-time.
+          if [ "$EXPECTED" = "\${NIFFYINSURE_EXPECTED_WASM_HASH}" ]; then
+            echo "Registry uses env placeholder — skipping drift comparison in CI"
+          elif [ "$ACTUAL" != "$EXPECTED" ]; then
+            echo "::warning::Wasm drift detected: expected=$EXPECTED actual=$ACTUAL"
+          else
+            echo "Wasm hash matches registry: $ACTUAL"
+          fi
+
       - uses: actions/upload-artifact@v4
         with:
           name: niffyinsure-wasm-${{ github.sha }}
@@ -84,6 +99,57 @@ jobs:
       - run: npm run build
       - run: npm test
 
+  # ── Dependency audit / supply-chain ─────────────────────────────────────
+  # Policy: CRITICAL CVEs fail the build. HIGH CVEs produce a warning and
+  # must be triaged within 7 days. Accepted risks require a signed-off entry
+  # in docs/ops/audit-exceptions.md before the override label is applied.
+  # Override process:
+  #   1. Engineer opens a PR adding the CVE to audit-exceptions.md with
+  #      justification, mitigations, and a review-by date.
+  #   2. A second engineer approves the PR.
+  #   3. Add the GitHub label `audit-exception-approved` to the failing PR.
+  #   4. Re-run this job — it will pass once the exception is documented.
+  dependency-audit:
+    name: Dependency Audit (npm / SBOM)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Audit backend dependencies
+        working-directory: backend
+        run: |
+          npm install --ignore-scripts
+          # Fail on critical; warn on high (exit 0 so we can capture output)
+          npm audit --audit-level=critical
+          npm audit --audit-level=high || echo "::warning::High-severity advisories found — triage within 7 days per audit policy"
+
+      - name: Audit frontend dependencies
+        working-directory: frontend
+        run: |
+          npm ci --ignore-scripts
+          npm audit --audit-level=critical
+          npm audit --audit-level=high || echo "::warning::High-severity advisories found — triage within 7 days per audit policy"
+
+      - name: Generate SBOM (backend)
+        working-directory: backend
+        run: npx --yes @cyclonedx/cyclonedx-npm --output-format JSON --output-file ../sbom-backend.json
+
+      - name: Generate SBOM (frontend)
+        working-directory: frontend
+        run: npx --yes @cyclonedx/cyclonedx-npm --output-format JSON --output-file ../sbom-frontend.json
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sbom-${{ github.sha }}
+          path: |
+            sbom-backend.json
+            sbom-frontend.json
+          retention-days: 90
+
   # ── Frontend ──────────────────────────────────────────────────────────────
   frontend:
     name: Frontend (Next.js / TypeScript)

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/package.json

@@ -39,6 +39,7 @@
     "@nestjs/platform-express": "^10.4.5",
     "@nestjs/swagger": "^7.4.2",
     "@nestjs/terminus": "^10.2.1",
+    "@nestjs/schedule": "^4.1.0",
     "@nestjs/throttler": "^6.5.0",
     "@prisma/client": "^6.6.0",
     "@types/form-data": "^2.2.1",

backend/prisma/schema.prisma

@@ -156,6 +156,41 @@ model FeatureFlag {
   @@map("feature_flags")
 }
 
+/// Deduplication table for wasm drift alerts — one row per (contract, actual-hash) pair.
+/// Prevents repeated webhook spam for the same unresolved drift.
+model WasmDriftAlert {
+  id            String   @id @default(uuid())
+  dedupKey      String   @unique /// "<contractName>:<actualHash>"
+  contractName  String
+  contractId    String
+  expectedHash  String
+  actualHash    String
+  resolvedAt    DateTime?
+  createdAt     DateTime @default(now())
+
+  @@index([contractName])
+  @@map("wasm_drift_alerts")
+}
+
+/// Tracks staff-initiated privacy requests (GDPR/CCPA-style) for off-chain data.
+/// On-chain and IPFS data is immutable and cannot be erased — see runbook.
+model PrivacyRequest {
+  id                    String    @id @default(uuid())
+  subjectWalletAddress  String
+  requestType           String    /// "ANONYMIZE" | "DELETE"
+  requestedBy           String    /// staff actor (wallet address or email)
+  status                String    @default("IN_PROGRESS") /// "IN_PROGRESS" | "COMPLETED" | "FAILED"
+  rowsAffected          Int       @default(0)
+  notes                 String?
+  errorMessage          String?
+  completedAt           DateTime?
+  createdAt             DateTime  @default(now())
+
+  @@index([subjectWalletAddress])
+  @@index([status])
+  @@map("privacy_requests")
+}
+
 /// 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.ts

@@ -12,6 +12,7 @@ import {
   HttpStatus,
 } from '@nestjs/common';
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { IsEnum, IsOptional, IsString } from 'class-validator';
 import { Request } from 'express';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { AdminRoleGuard } from './guards/admin-role.guard';
@@ -20,6 +21,13 @@ 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';
+import { PrivacyService, PrivacyRequestType } from '../maintenance/privacy.service';
+
+class PrivacyRequestDto {
+  @IsString() subjectWalletAddress!: string;
+  @IsEnum(['ANONYMIZE', 'DELETE']) requestType!: PrivacyRequestType;
+  @IsOptional() @IsString() notes?: string;
+}
 
 @ApiTags('admin')
 @ApiBearerAuth('JWT-auth')
@@ -29,6 +37,7 @@ export class AdminController {
   constructor(
     private readonly adminService: AdminService,
     private readonly auditService: AuditService,
+    private readonly privacyService: PrivacyService,
   ) {}
 
   /**
@@ -90,6 +99,28 @@ export class AdminController {
    * officer and are subject to applicable insurance-regulation obligations.
    * The audit row created here serves as the immutable record of that action.
    */
+  /** POST /admin/privacy/requests — execute anonymization or deletion for a subject. */
+  @Post('privacy/requests')
+  @HttpCode(HttpStatus.ACCEPTED)
+  @ApiOperation({ summary: 'Submit a privacy request (anonymize or delete off-chain data)' })
+  async submitPrivacyRequest(@Body() dto: PrivacyRequestDto, @Req() req: Request) {
+    const actor = (req.user as any)?.walletAddress ?? 'unknown';
+    return this.privacyService.handleRequest({
+      subjectWalletAddress: dto.subjectWalletAddress,
+      requestType: dto.requestType,
+      requestedBy: actor,
+      ipAddress: req.ip,
+      notes: dto.notes,
+    });
+  }
+
+  /** GET /admin/privacy/requests — list all privacy requests. */
+  @Get('privacy/requests')
+  @ApiOperation({ summary: 'List privacy requests' })
+  async listPrivacyRequests(@Query('page') page = 1, @Query('limit') limit = 20) {
+    return this.privacyService.listRequests(Number(page), Number(limit));
+  }
+
   @Patch('feature-flags/:key')
   @ApiOperation({ summary: 'Set a feature flag value' })
   async setFeatureFlag(

backend/src/admin/admin.module.ts

@@ -4,9 +4,10 @@ import { AdminService } from './admin.service';
 import { AuditService } from './audit.service';
 import { PrismaModule } from '../prisma/prisma.module';
 import { AuthModule } from '../auth/auth.module';
+import { MaintenanceModule } from '../maintenance/maintenance.module';
 
 @Module({
-  imports: [PrismaModule, AuthModule],
+  imports: [PrismaModule, AuthModule, MaintenanceModule],
   controllers: [AdminController],
   providers: [AdminService, AuditService],
   exports: [AuditService],

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 || {}),
+    };
+  }
+}