Merge branch 'main' into feat/89-mobile-ux-polish

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)

BRANDING.md

@@ -0,0 +1,42 @@
+# NiffyInsur Brand Guidelines
+
+This document outlines the visual identity and styling standards for NiffyInsur.
+
+## Color Palette
+
+### Primary (Azure Blue)
+- **HSL**: `217 91% 60%`
+- **Hex**: `#3b82f6`
+- **Usage**: Buttons, links, primary brand elements.
+
+### Secondary (Slate)
+- **HSL**: `222 47% 11%` (Foreground) / `0 0% 100%` (Background)
+- **Usage**: Typography, borders, subtle UI elements.
+
+### Status Colors
+- **Success**: `142 71% 45%` (Green)
+- **Warning**: `48 96% 53%` (Yellow)
+- **Destructive**: `0 84% 60%` (Red)
+
+## Typography
+
+### Headings & Body
+- **Font**: [Inter](https://rsms.me/inter/)
+- **Weight**: 400 (Regular), 500 (Medium), 600 (Semi-Bold), 700 (Bold)
+
+### Technical & Data
+- **Font**: [IBM Plex Mono](https://github.com/IBM/plex)
+- **Usage**: Addresses, transaction hashes, smart contract code, numbers.
+
+## UI Principles
+
+1. **Glassmorphism**: Use the `.glass` utility for cards and overlays to create depth.
+   - Example: `<div className="glass rounded-lg p-6">...</div>`
+2. **Interactive States**:
+   - **Hover**: Subtle scaling or opacity shift.
+   - **Focus**: Clear Azure Blue ring (`focus-ring` utility).
+3. **Dark Mode**: Automatically respects system preferences, manual override available via `ThemeToggle`.
+
+## Assets
+- **Logo Mark**: [icon.svg](/frontend/public/icon.svg)
+- **Manifest**: [site.webmanifest](/frontend/public/site.webmanifest)

backend/.env.example

@@ -41,9 +41,14 @@ 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)
+# Comma-separated list of approved public frontend origins.
+# Local dev: use your Next.js dev server origin (e.g. http://localhost:3001).
+# Multiple origins: FRONTEND_ORIGINS=https://app.example.com,https://www.example.com
+# Production: all entries MUST start with https:// — http:// and wildcard * are rejected at startup.
+# Mobile app origins: add them here as additional comma-separated entries when needed.
+FRONTEND_ORIGINS=http://localhost:3001
+# Comma-separated list of allowed origins for the admin UI (optional, separate from public).
+# Leave empty if there is no separate admin UI.
 ADMIN_CORS_ORIGINS=http://localhost:3002
 
 # Staff Auth (required in non-production)

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.