Merge branch 'main' into feat/policy-beneficiary

Author: jhayniffy

.env.example

@@ -1,5 +1,10 @@
 # Copy this file to .env and fill in values.
 # .env is gitignored — never commit secrets.
+#
+# CONVENTION:
+#   NEXT_PUBLIC_*  → safe to expose in the browser bundle
+#   (no prefix)    → server-only; NEVER import in client components
+#                    use `import '@/lib/server-guard'` to enforce this
 
 # ── Redis ─────────────────────────────────────────────────────────────────────
 REDIS_HOST=127.0.0.1

.github/workflows/ci.yml

@@ -12,6 +12,34 @@ permissions:
   contents: read
 
 jobs:
+  # ── Frontend quality gate ─────────────────────────────────────────────────
+  frontend:
+    name: Frontend (lint → typecheck → build)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint (fail on warnings)
+        run: npm run lint -- --max-warnings=0
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
   # ── Soroban ABI golden-vector drift guard ────────────────────────────────
   golden-vectors:
     name: Soroban ABI golden vectors
@@ -148,7 +176,7 @@ jobs:
   e2e-tests:
     name: Playwright E2E tests
     runs-on: ubuntu-latest
-    needs: quality-build
+    needs: frontend
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -167,7 +195,69 @@ jobs:
         with:
           name: playwright-failure-${{ github.run_id }}
           path: |
+ feat/accessibility-audit
+            sbom-backend.json
+            sbom-frontend.json
+          retention-days: 90
+
+  # ── Frontend ──────────────────────────────────────────────────────────────
+  frontend:
+    name: Frontend (Next.js / TypeScript)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run check-docs
+      - run: npm run build
+      - run: npm test
+
+  # ── Accessibility (axe) ───────────────────────────────────────────────────
+  accessibility:
+    name: Accessibility (axe / Playwright)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - run: npm ci
+      - run: npm run build
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run axe accessibility checks
+        run: npx playwright test tests/accessibility.spec.ts --reporter=list
+        env:
+          BASE_URL: http://localhost:3000
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: axe-report-${{ github.sha }}
+          path: frontend/playwright-report/
+          retention-days: 14
+
             test-results
             playwright-report
             traces
             .playwright/traces
+

.github/workflows/load-tests.yml

@@ -0,0 +1,109 @@
+name: Load Tests (Staging)
+
+# Runs on a schedule against staging, or manually via workflow_dispatch.
+# NEVER targets production endpoints.
+#
+# Secrets required (set in GitHub repo settings → Secrets):
+#   STAGING_BASE_URL   — e.g. https://staging.niffyinsur.com/api
+#   STAGING_TEST_JWT   — short-lived JWT for authenticated write flows
+#                        (see backend/loadtests/README.md for generation)
+#
+# Failure alerts: the job fails when k6 thresholds are breached.
+# GitHub will send a notification to the repo watchers.
+# For Slack/PagerDuty alerts, add a notification step after the k6 run.
+
+on:
+  # Run every Monday at 08:00 UTC
+  schedule:
+    - cron: '0 8 * * 1'
+  # Allow manual trigger from the Actions tab
+  workflow_dispatch:
+    inputs:
+      target_url:
+        description: 'Override staging base URL (default: STAGING_BASE_URL secret)'
+        required: false
+        type: string
+
+jobs:
+  load-test:
+    name: k6 Load Tests
+    runs-on: ubuntu-latest
+    # Only run on the default branch to avoid accidental staging hammering from PRs
+    if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install k6
+        run: |
+          sudo gpg -k
+          sudo gpg --no-default-keyring \
+            --keyring /usr/share/keyrings/k6-archive-keyring.gpg \
+            --keyserver hkp://keyserver.ubuntu.com:80 \
+            --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
+          echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] \
+            https://dl.k6.io/deb stable main" \
+            | sudo tee /etc/apt/sources.list.d/k6.list
+          sudo apt-get update -qq
+          sudo apt-get install -y k6
+
+      - name: Set target URL
+        id: url
+        run: |
+          URL="${{ github.event.inputs.target_url || secrets.STAGING_BASE_URL }}"
+          if [ -z "$URL" ]; then
+            echo "::error::STAGING_BASE_URL secret is not set. Aborting."
+            exit 1
+          fi
+          echo "base_url=$URL" >> "$GITHUB_OUTPUT"
+
+      - name: Smoke test (sanity check before load)
+        env:
+          BASE_URL: ${{ steps.url.outputs.base_url }}
+        run: k6 run --vus 2 --duration 30s backend/loadtests/smoke.js
+
+      - name: Load test — claims list (read-heavy)
+        env:
+          BASE_URL: ${{ steps.url.outputs.base_url }}
+        run: |
+          k6 run \
+            --out json=backend/docs/perf/$(date +%Y-%m-%d)-claims-list.json \
+            backend/loadtests/claims-list.js
+
+      - name: Load test — health and quotes
+        env:
+          BASE_URL: ${{ steps.url.outputs.base_url }}
+        run: |
+          k6 run \
+            --out json=backend/docs/perf/$(date +%Y-%m-%d)-health-quotes.json \
+            backend/loadtests/health-and-quotes.js
+
+      - name: Load test — authenticated write flow
+        env:
+          BASE_URL: ${{ steps.url.outputs.base_url }}
+          TEST_JWT: ${{ secrets.STAGING_TEST_JWT }}
+        # Only run if the secret is available (skip on forks)
+        if: env.TEST_JWT != ''
+        run: |
+          k6 run \
+            --out json=backend/docs/perf/$(date +%Y-%m-%d)-claim-submit.json \
+            backend/loadtests/claim-submit.js
+
+      - name: Upload k6 reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: k6-reports-${{ github.run_id }}
+          path: backend/docs/perf/*.json
+          retention-days: 90
+
+      # Optional: post a Slack notification on threshold breach
+      # Uncomment and configure SLACK_WEBHOOK_URL secret to enable.
+      # - name: Notify Slack on failure
+      #   if: failure()
+      #   uses: slackapi/slack-github-action@v1
+      #   with:
+      #     payload: |
+      #       {"text": "⚠️ Load test thresholds breached on staging. Check the run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"}
+      #   env:
+      #     SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

.nvmrc

@@ -0,0 +1 @@
+22

CONTRIBUTING.md

@@ -1,3 +1,86 @@
+ feat/accessibility-audit
+# Contributing to NiffyInsur
+
+## Accessibility Testing
+
+Accessibility is a first-class requirement. Every PR that touches UI must pass the checks below before merge.
+
+### Automated axe checks (CI)
+
+The `accessibility` CI job runs `@axe-core/playwright` against the quote, policy, claims, and vote routes. **No critical violations are permitted.** The job uploads a Playwright report as an artifact on failure.
+
+Run locally:
+
+```bash
+cd frontend
+npm install
+npm run build
+npx playwright test tests/accessibility.spec.ts
+```
+
+### Manual axe spot-check
+
+1. Install the [axe DevTools browser extension](https://www.deque.com/axe/devtools/).
+2. Open each targeted route: `/quote`, `/policy`, `/claims`, `/claims/<id>`.
+3. Run the full-page scan. Resolve any **critical** or **serious** violations before opening a PR.
+
+### Keyboard-only walkthrough
+
+Verify these flows using only the keyboard (no mouse):
+
+| Flow | Steps |
+|------|-------|
+| Get a quote | Tab through all form fields → submit → confirm quote preview updates |
+| Purchase policy | Complete all 4 wizard steps using Tab / Shift+Tab / Enter / Space |
+| File a claim | Complete all 4 wizard steps; confirm focus moves to new step heading on advance |
+| Cast a vote | Tab to Approve / Reject buttons → Enter to open confirm modal → Tab within modal → confirm or cancel |
+| Connect wallet | Tab to "Connect Wallet" button → Enter → confirm status announced |
+
+Focus must always be visible. After a modal opens, focus must move inside it. After a modal closes, focus must return to the trigger.
+
+### Screen reader spot-check (per major release)
+
+Test at minimum one major flow per release with a screen reader:
+
+- **macOS / iOS**: VoiceOver (`Cmd+F5` to toggle)
+- **Windows**: NVDA (free) or Narrator
+- **Android**: TalkBack
+
+Checklist:
+- [ ] Transaction status updates are announced (aria-live regions on wizard and policy pages)
+- [ ] Step changes in wizards are announced (focus moves to hidden `<h2>` with step name)
+- [ ] Quote preview updates are announced on the quote page
+- [ ] Vote tally countdown is announced via `aria-live="polite"`
+- [ ] Modal title is read when dialog opens
+- [ ] Icon-only buttons have accessible names (aria-label or sr-only text)
+- [ ] Claim status badges convey outcome via text/shape, not color alone
+
+### Reduced-motion
+
+Verify that setting `prefers-reduced-motion: reduce` (OS accessibility setting or DevTools emulation) stops all non-essential animations. Loading spinners should become static; slide/fade transitions should be instant.
+
+### Heading hierarchy
+
+Each page must have exactly one `<h1>`. Use the browser Accessibility Tree panel (DevTools → Accessibility) or the [HeadingsMap extension](https://rumoroso.bitbucket.io/headingsmap/) to verify a logical heading order with no skipped levels.
+
+### Landmarks
+
+Every page must have at minimum: `<main>`, `<nav>` (if navigation present), and `<footer>` (if present). Verify with the Accessibility Tree or axe.
+
+### Color contrast
+
+All text must meet WCAG AA contrast ratios (4.5:1 normal text, 3:1 large text). Use the axe scan or the browser color-contrast checker. Claim outcomes (Approved / Rejected / Pending) must not rely on color alone — shape indicators and text labels are required.
+
+### Adding new UI
+
+When adding new interactive components:
+
+1. Icon-only controls **must** have `aria-label` or a visually hidden label.
+2. Async state changes (transactions, loading) **must** update an `aria-live` region.
+3. Multi-step wizards **must** move focus to a step heading on step change.
+4. Modals **must** trap focus and return it to the trigger on close (Radix Dialog handles this automatically).
+5. Animations **must** respect `prefers-reduced-motion` via the global CSS rule in `globals.css`.
+
 # Contributing
 
 ## Soroban ABI golden vectors
@@ -48,3 +131,4 @@ Before tagging a release:
 - **Never** commit real private keys (Stellar secret keys start with `S`).
 - Use only placeholder G-addresses and C-addresses in vector `inputs`.
 - The CI job checks for secret-key patterns and will fail if any are found.
+ main

README.md

@@ -0,0 +1,54 @@
+# niff-Stellar-shurance
+
+Decentralized insurance platform built on the Stellar/Soroban blockchain.
+
+## Setup
+
+```bash
+# 1. Clone
+git clone https://github.com/your-org/niff-Stellar-shurance.git && cd niff-Stellar-shurance
+
+# 2. Install
+cp frontend/.env.example frontend/.env.local   # fill in values
+cd frontend && npm install
+
+# 3. Run
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Requirements
+
+- Node.js `>=22` (see `.nvmrc`)
+- npm `>=10`
+
+## Project Structure
+
+```
+frontend/src/
+├── app/          # Next.js App Router routes & layouts
+├── features/     # Feature modules: policies/, claims/, wallet/
+│   └── <feature>/{components,hooks,api}/
+├── components/ui/ # Shared primitive components (Shadcn-style)
+├── lib/          # Utilities, Stellar SDK wrappers, schemas
+└── styles/       # Global CSS and Tailwind theme tokens
+```
+
+## Quality Gates
+
+```bash
+npm run lint        # ESLint (fails on warnings)
+npm run typecheck   # tsc --noEmit strict check
+npm run build       # Production build
+```
+
+CI runs all three sequentially on every push/PR to `main`.
+
+## Environment Variables
+
+Copy `frontend/.env.example` → `frontend/.env.local`.
+
+- `NEXT_PUBLIC_*` variables are safe for the browser.
+- All other variables are **server-only** — never import them in Client Components.
+  Use `import '@/lib/server-guard'` at the top of server-only modules to enforce this at build time.