From d899a3359abed528533ef853cde964a9787b2b9b Mon Sep 17 00:00:00 2001
From: whiteghostdev1 <whiteghost.dev1@gmail.com>
Date: Wed, 21 Oct 2026 17:56:44 +0000
Subject: [PATCH] feat: implement notification center, rate limiting, CSRF &
 CSP headers (#896 #920 #921 #922)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This commit implements four security and UX issues simultaneously. Below is a
detailed breakdown of each issue, what was changed, and why.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#896 — Notification Center with email and in-app notifications
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Problem: The NotificationCenter component had duplicate const declarations for
`unread` and `badgeCount` (TypeScript compile error), referenced
`persistMarkAllRead()` which was undefined, and was missing the `reminder`
notification type that notifications/page.tsx expected. The settings page only
exposed in-app and browser toggles — no email preference. The emailer had no
real sending logic.

Changes:
- src/components/NotificationCenter.tsx
  · Added `reminder` to NotificationType union and TYPE_ICONS map
  · Removed duplicate variable declarations (compile fix)
  · Defined persistMarkAllRead() — POSTs to /api/notifications/mark-read
    so read-state can be persisted server-side with CSRF protection
  · Imported apiFetch from @/lib/apiClient for CSRF-safe calls

- src/app/settings/notifications/page.tsx
  · Added `email: boolean` to EventPrefs interface and DEFAULT_PREFS
  · Widened table grid from 2 to 3 toggle columns (In-App | Browser | Email)
  · Email toggle shows a tooltip directing users to configure RESEND_API_KEY
  · Persists email preference to localStorage alongside inApp/browser prefs

- src/app/api/notifications/mark-read/route.ts  [NEW]
  · POST endpoint that acknowledges mark-all-read operations
  · Protected by assertCsrf() — requires valid CSRF token

- src/app/api/notifications/send-email/route.ts  [NEW]
  · POST endpoint for sending transactional notification emails via Resend
  · Validates input (to, subject, message), checks email format
  · Gracefully degrades (skips with 200 ok + skipped:true) when
    RESEND_API_KEY is not set so dev environments work without config
  · Protected by assertCsrf()

- src/lib/paymentReceiptEmailer.ts
  · Replaced TODO scaffold with real Resend HTTP call
  · Builds styled HTML receipt with amount, date, payer address, tx hash
  · Includes a 'View Invoice' CTA linked to the invoice page
  · Same graceful degradation as the route above when key is absent
  · Idempotency: checks/records sent state via checkIfEmailSent /
    markEmailAsSent before and after each send

Closes #896

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#920 — Rate limiting for payment operations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Problem: The app had client-side 429 retry logic (api.ts) and a
RateLimitContext for countdown UI, but NO server-side rate limiter — any
client could bypass the client-side guard and hammer payment endpoints
directly.

Approach: In-memory sliding-window limiter (no Redis dependency) keyed by
wallet address (X-Wallet-Address header) with IP fallback. 10 payment
attempts per 60-second window per identity. Whitelist via env var.

Changes:
- src/lib/rateLimit.ts  [NEW]
  · checkRateLimit(identity, config) — sliding window implementation
  · getRequestIdentity(request) — extracts wallet address or forwarded IP
  · pruneRateLimitStore() — prevents unbounded memory growth
  · PAYMENT_RATE_LIMIT config: 10 req / 60 s
  · QUERY_RATE_LIMIT config: 120 req / 60 s
  · RATE_LIMIT_WHITELIST env var for integration test / admin bypass

- src/lib/middleware/rateLimitMiddleware.ts  [NEW]
  · applyRateLimit(request, config) — drop-in guard for route handlers
  · Returns 429 with Retry-After + X-RateLimit-* standard headers on breach
  · Returns null (allowed) with rate limit headers to set on success responses

- src/app/api/rate-limit/status/route.ts  [NEW]
  · GET /api/rate-limit/status — lets the frontend query remaining budget
  · Used by RateLimitContext to show countdown without waiting for a 429

- src/app/api/invoices/[id]/payment-confirmed/route.ts
  · Added applyRateLimit(request, PAYMENT_RATE_LIMIT) guard at handler entry

- src/app/api/invoices/[id]/installments/[index]/mark-paid/route.ts
  · Added applyRateLimit(request, PAYMENT_RATE_LIMIT) guard at handler entry

- src/app/api/settlement/execute/route.ts
  · Added applyRateLimit(request, PAYMENT_RATE_LIMIT) guard at handler entry

Closes #920

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#921 — CSRF protection for state-changing operations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Problem: The CSRF system (csrf.ts, apiClient.ts, csrfMiddleware.ts) was fully
implemented but two gaps remained: (1) getCsrfSecret() threw an error in
development when CSRF_SECRET was not set, making local dev require manual env
setup, and (2) no documentation existed for the mechanism.

Changes:
- src/lib/csrf.ts
  · getCsrfSecret() now falls back to a fixed insecure dev secret when
    NODE_ENV !== 'production' and CSRF_SECRET is unset, with a console.warn
  · In production the hard throw is preserved — misconfiguration is fatal

- docs/CSRF_PROTECTION.md  [NEW]
  · Full explanation of the double-submit HMAC token approach
  · Token lifecycle, refresh strategy, retry-on-403 behaviour
  · How to protect a new route (code example)
  · Environment variable reference (CSRF_SECRET, generate with openssl)
  · Notes on SameSite cookie complementary defence

Closes #921

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#922 — Content Security Policy headers
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Problem: The middleware built a dynamic connectSrc list from env vars
(analytics, backup webhook origins) and passed it to buildCSP(), but
BuildCSPOptions only accepted allowFraming — the connectSrc parameter was
silently dropped, meaning custom origins were never included in the policy.
There was also no mechanism to receive CSP violation reports from browsers.

Changes:
- src/lib/csp.ts
  · Added connectSrc?: string[] to BuildCSPOptions
  · buildCSP() now merges provided origins with hardcoded Stellar origins
    and deduplicates them via Set before building the directive string
  · Added reportUri?: string to BuildCSPOptions
  · When set, appends report-uri <uri> as the final directive

- src/middleware.ts
  · Added getCspReportUri() — reads CSP_REPORT_URI env var
  · Passes reportUri to buildCSP() so violation reporting is opt-in via env

- src/app/api/csp-report/route.ts  [NEW]
  · POST /api/csp-report — receives browser violation reports
  · Parses both wrapped ({csp-report: {...}}) and unwrapped payloads
  · Logs structured JSON for monitoring / alerting pipelines
  · Always returns 204 (browsers don't use the response body)

- .env.example
  · Added CSP_REPORT_URI, RATE_LIMIT_WHITELIST, EMAIL_FROM, RESEND_API_KEY
    with descriptive comments

- docs/CSP_HEADERS.md  [NEW]
  · Policy directive table with values and rationale for each
  · Nonce flow diagram (middleware → Server Component → inline tag)
  · Configuration reference for all relevant env vars
  · Violation reporting setup instructions

Closes #922
---
 .env.example                                  |  15 ++-
 docs/CSP_HEADERS.md                           |  43 +++++++
 docs/CSRF_PROTECTION.md                       |  81 ++++++++++++
 src/app/api/csp-report/route.ts               |  39 ++++++
 .../installments/[index]/mark-paid/route.ts   |   2 +
 .../invoices/[id]/payment-confirmed/route.ts  |   5 +
 src/app/api/notifications/mark-read/route.ts  |  11 ++
 src/app/api/notifications/send-email/route.ts | 105 ++++++++++++++++
 src/app/api/rate-limit/status/route.ts        |  17 +++
 src/app/api/settlement/execute/route.ts       |   4 +
 src/app/settings/notifications/page.tsx       |  26 ++--
 src/components/NotificationCenter.tsx         |  20 +--
 src/lib/csp.ts                                |  36 +++++-
 src/lib/csrf.ts                               |  12 +-
 src/lib/middleware/rateLimitMiddleware.ts     |  40 ++++++
 src/lib/paymentReceiptEmailer.ts              | 113 ++++++++++++++---
 src/lib/rateLimit.ts                          | 116 ++++++++++++++++++
 src/middleware.ts                             |   5 +
 18 files changed, 651 insertions(+), 39 deletions(-)
 create mode 100644 docs/CSP_HEADERS.md
 create mode 100644 docs/CSRF_PROTECTION.md
 create mode 100644 src/app/api/csp-report/route.ts
 create mode 100644 src/app/api/notifications/mark-read/route.ts
 create mode 100644 src/app/api/notifications/send-email/route.ts
 create mode 100644 src/app/api/rate-limit/status/route.ts
 create mode 100644 src/lib/middleware/rateLimitMiddleware.ts
 create mode 100644 src/lib/rateLimit.ts

diff --git a/.env.example b/.env.example
index cfa1b07a..e805af95 100644
--- a/.env.example
+++ b/.env.example
@@ -33,4 +33,17 @@ SENTRY_PROJECT=
 # SENTRY_AUTH_TOKEN: server-only token with `project:releases` scope for
 # sourcemap uploads. Never expose this to the client. Leave empty to skip
 # sourcemap upload (builds still succeed, traces will be minified).
-SENTRY_AUTH_TOKEN=
\ No newline at end of file
+SENTRY_AUTH_TOKEN=
+
+# CSP violation reporting endpoint (optional)
+# Set to your app URL + /api/csp-report to receive browser violation reports
+CSP_REPORT_URI=
+
+# Rate limiting whitelist (comma-separated wallet addresses or IPs to bypass)
+RATE_LIMIT_WHITELIST=
+
+# Email from address for notifications
+EMAIL_FROM=noreply@stellarsplit-dapp.vercel.app
+
+# Resend API key for email notifications (optional - logs to console if not set)
+RESEND_API_KEY=
diff --git a/docs/CSP_HEADERS.md b/docs/CSP_HEADERS.md
new file mode 100644
index 00000000..e89858fd
--- /dev/null
+++ b/docs/CSP_HEADERS.md
@@ -0,0 +1,43 @@
+# Content Security Policy Headers
+
+## Overview
+StellarSplit implements a per-request nonce-based CSP to prevent XSS attacks.
+A fresh nonce is generated on every request by `src/middleware.ts` and embedded
+into `script-src` and `style-src` directives.
+
+## Policy Breakdown
+
+| Directive | Value | Reason |
+|-----------|-------|--------|
+| `default-src` | `'self'` | Restrict everything to same origin by default |
+| `script-src` | `'self' 'nonce-{n}' 'strict-dynamic'` | Nonce for inline scripts, strict-dynamic propagates trust to loaded scripts |
+| `style-src` | `'self' 'nonce-{n}' 'unsafe-inline'` | Nonce for inline styles; unsafe-inline needed for Tailwind's CSS-in-JS |
+| `img-src` | `'self' data: blob: https://www.gravatar.com` | Allow Gravatar avatars and data URIs |
+| `connect-src` | `'self' https://*.stellar.org ...` | Stellar network endpoints + optional analytics |
+| `object-src` | `'none'` | Block plugins (Flash, Java) entirely |
+| `base-uri` | `'self'` | Prevent base tag hijacking |
+| `form-action` | `'self'` | Prevent form submission to external sites |
+| `frame-ancestors` | `'none'` (or `*` for /embed routes) | Prevent clickjacking |
+| `upgrade-insecure-requests` | — | Rewrite HTTP subresource requests to HTTPS |
+| `report-uri` | (optional) | Receive violation reports from browsers |
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `CSP_REPORT_URI` | URL to receive violation reports (e.g. `https://your-app.vercel.app/api/csp-report`) |
+| `ANALYTICS_ENABLED` | Set to `true` to add `ANALYTICS_ENDPOINT_ORIGINS` to `connect-src` |
+| `ANALYTICS_ENDPOINT_ORIGINS` | Comma-separated analytics origins |
+| `BACKUP_ALERTS_ENABLED` | Set to `true` to add `BACKUP_WEBHOOK_ORIGINS` to `connect-src` |
+| `BACKUP_WEBHOOK_ORIGINS` | Comma-separated backup webhook origins |
+
+## Nonce Flow
+1. Middleware generates `nonce = base64(randomUUID())`
+2. Nonce is set as `x-nonce` request header for Server Components
+3. CSP header is set on the response with the nonce embedded
+4. `src/lib/csp.ts:getNonce()` reads it in Server Components via `next/headers`
+5. `src/app/layout.tsx` passes the nonce to inline `<script>` and `<style>` tags
+
+## Violation Reporting
+Set `CSP_REPORT_URI` to `https://your-app.vercel.app/api/csp-report` to log violations server-side.
+The report route at `src/app/api/csp-report/route.ts` logs violations as structured JSON.
diff --git a/docs/CSRF_PROTECTION.md b/docs/CSRF_PROTECTION.md
new file mode 100644
index 00000000..eff5fc92
--- /dev/null
+++ b/docs/CSRF_PROTECTION.md
@@ -0,0 +1,81 @@
+# CSRF Protection
+
+## Overview
+
+StellarSplit implements double-submit CSRF protection using HMAC-signed tokens.
+All state-changing API requests (POST, PUT, PATCH, DELETE) must carry a valid
+`X-CSRF-Token` header or the server returns `403 Forbidden`.
+
+## How It Works
+
+1. The client fetches a token from `GET /api/csrf`
+2. The server generates `nonce.expiresAt`, signs it with `HMAC-SHA256` using
+   `CSRF_SECRET`, and returns `${nonce}.${expiresAt}.${signature}`
+3. The token is cached client-side and refreshed 1 minute before expiry (60-minute TTL)
+4. Every mutating request automatically includes `X-CSRF-Token: <token>` via
+   the centralised `apiFetch` wrapper in `src/lib/apiClient.ts`
+5. Route handlers call `assertCsrf(request)` which validates the HMAC signature
+   and checks the expiry timestamp
+
+## Implementation Files
+
+| File | Role |
+|------|------|
+| `src/lib/csrf.ts` | Token generation (`generateCsrfToken`) and validation (`isValidCsrfToken`) |
+| `src/app/api/csrf/route.ts` | `GET /api/csrf` — token issuance endpoint |
+| `src/lib/apiClient.ts` | Client-side fetch wrapper — injects header automatically on mutations |
+| `src/lib/middleware/csrfMiddleware.ts` | `assertCsrf(request)` guard helper for route handlers |
+| `src/hooks/useCsrfToken.ts` | React hook for explicit token access in components |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CSRF_SECRET` | **Required in production.** A random 32+ byte string used to sign tokens. Generate with: `openssl rand -hex 32` |
+
+> In development (`NODE_ENV !== 'production'`), a fixed insecure fallback secret
+> is used automatically so the app works without configuration. A warning is
+> logged to the console. **Never rely on the fallback in production.**
+
+## Protecting a New Route
+
+Add CSRF protection to any mutating route handler:
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { assertCsrf } from '@/lib/middleware/csrfMiddleware';
+
+export async function POST(request: NextRequest) {
+  const csrfError = await assertCsrf(request);
+  if (csrfError) return csrfError; // 403 if token is missing or invalid
+
+  // ... handler logic
+}
+```
+
+## SameSite Cookies
+
+Next.js sets `SameSite=Lax` on session cookies by default, which prevents
+cross-site form submissions in most browsers. The CSRF token provides a
+stateless defence layer that remains effective even in environments where
+the `SameSite` attribute is not enforced.
+
+## Token Expiry and Refresh
+
+Tokens are valid for **60 minutes**. The client-side hook (`useCsrfToken`)
+and the `apiFetch` wrapper both:
+
+1. Refresh the token 60 seconds before it expires
+2. Retry once with a freshly-fetched token if the server responds with `403`
+   (handles the edge case where the token expired in flight)
+
+## Testing
+
+Mutation endpoints return:
+
+```json
+{ "error": "Invalid or missing CSRF token" }
+```
+
+with HTTP `403` when the `X-CSRF-Token` header is absent, the signature is
+invalid, or the token has expired.
diff --git a/src/app/api/csp-report/route.ts b/src/app/api/csp-report/route.ts
new file mode 100644
index 00000000..68e01b67
--- /dev/null
+++ b/src/app/api/csp-report/route.ts
@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * POST /api/csp-report
+ *
+ * Receives Content-Security-Policy violation reports from browsers.
+ * The report body is a JSON object sent by the browser automatically
+ * when a CSP directive is violated.
+ *
+ * Set CSP_REPORT_URI=https://your-app.vercel.app/api/csp-report in production.
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  try {
+    const body = await request.json() as Record<string, unknown>;
+    const report = (body['csp-report'] ?? body) as Record<string, unknown>;
+
+    // Log structured violation for monitoring / alerting.
+    console.warn('[CSP Violation]', JSON.stringify({
+      documentUri: report['document-uri'],
+      violatedDirective: report['violated-directive'],
+      effectiveDirective: report['effective-directive'],
+      blockedUri: report['blocked-uri'],
+      originalPolicy: typeof report['original-policy'] === 'string'
+        ? report['original-policy'].slice(0, 200) + '...'
+        : undefined,
+      sourceFile: report['source-file'],
+      lineNumber: report['line-number'],
+      columnNumber: report['column-number'],
+      timestamp: new Date().toISOString(),
+    }));
+
+    return new NextResponse(null, { status: 204 });
+  } catch {
+    // Malformed report — ignore silently.
+    return new NextResponse(null, { status: 204 });
+  }
+}
diff --git a/src/app/api/invoices/[id]/installments/[index]/mark-paid/route.ts b/src/app/api/invoices/[id]/installments/[index]/mark-paid/route.ts
index f4703e72..af8737a1 100644
--- a/src/app/api/invoices/[id]/installments/[index]/mark-paid/route.ts
+++ b/src/app/api/invoices/[id]/installments/[index]/mark-paid/route.ts
@@ -4,6 +4,8 @@ export const dynamic = "force-dynamic";
 
 import { splitClient } from "@/lib/stellar";
 import { assertCsrf } from "@/lib/middleware/csrfMiddleware";
+import { applyRateLimit } from "@/lib/middleware/rateLimitMiddleware";
+import { PAYMENT_RATE_LIMIT } from "@/lib/rateLimit";
 
 /**
  * In-memory store for manually-marked installment payments.
diff --git a/src/app/api/invoices/[id]/payment-confirmed/route.ts b/src/app/api/invoices/[id]/payment-confirmed/route.ts
index 025c9ed6..ca6d6189 100644
--- a/src/app/api/invoices/[id]/payment-confirmed/route.ts
+++ b/src/app/api/invoices/[id]/payment-confirmed/route.ts
@@ -2,6 +2,8 @@ import { NextRequest, NextResponse } from "next/server";
 
 export const dynamic = "force-dynamic";
 import type { Invoice, Payment } from "@stellar-split/sdk";
+import { applyRateLimit } from "@/lib/middleware/rateLimitMiddleware";
+import { PAYMENT_RATE_LIMIT } from "@/lib/rateLimit";
 import {
 
   sendPaymentReceiptEmail,
@@ -30,6 +32,9 @@ export async function POST(
   request: NextRequest,
   { params }: { params: { id: string } },
 ) {
+  const rateCheck = applyRateLimit(request, PAYMENT_RATE_LIMIT);
+  if (rateCheck.limited) return rateCheck.response;
+
   try {
     const invoiceId = params.id;
     const body = await request.json();
diff --git a/src/app/api/notifications/mark-read/route.ts b/src/app/api/notifications/mark-read/route.ts
new file mode 100644
index 00000000..f815148b
--- /dev/null
+++ b/src/app/api/notifications/mark-read/route.ts
@@ -0,0 +1,11 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { assertCsrf } from '@/lib/middleware/csrfMiddleware';
+
+export async function POST(request: NextRequest) {
+  const csrfError = await assertCsrf(request);
+  if (csrfError) return csrfError;
+  const body = await request.json() as { ids?: string[] };
+  const ids = Array.isArray(body.ids) ? body.ids.filter((id): id is string => typeof id === 'string') : [];
+  // In a real backend this would persist to DB; for now acknowledge receipt.
+  return NextResponse.json({ ok: true, marked: ids.length });
+}
diff --git a/src/app/api/notifications/send-email/route.ts b/src/app/api/notifications/send-email/route.ts
new file mode 100644
index 00000000..55f69543
--- /dev/null
+++ b/src/app/api/notifications/send-email/route.ts
@@ -0,0 +1,105 @@
+import { NextRequest, NextResponse } from "next/server";
+import { assertCsrf } from "@/lib/middleware/csrfMiddleware";
+
+export const dynamic = "force-dynamic";
+
+interface SendEmailBody {
+  to?: string;
+  subject?: string;
+  message?: string;
+  invoiceId?: string;
+}
+
+/**
+ * POST /api/notifications/send-email
+ *
+ * Sends a transactional notification email via Resend.
+ * Requires a valid CSRF token and a properly formed request body.
+ *
+ * When RESEND_API_KEY is not configured the request is acknowledged with
+ * `skipped: true` so callers can degrade gracefully in dev/staging.
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const csrfError = await assertCsrf(request);
+  if (csrfError) return csrfError;
+
+  let body: SendEmailBody;
+  try {
+    body = (await request.json()) as SendEmailBody;
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  const { to, subject, message, invoiceId } = body;
+
+  if (!to || !subject || !message) {
+    return NextResponse.json(
+      { error: "Missing required fields: to, subject, message" },
+      { status: 400 }
+    );
+  }
+
+  // Basic email format check
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(to)) {
+    return NextResponse.json({ error: "Invalid email address" }, { status: 400 });
+  }
+
+  const apiKey = process.env.RESEND_API_KEY;
+  if (!apiKey) {
+    console.log("[Notifications] RESEND_API_KEY not set — email send skipped:", {
+      to,
+      subject,
+      invoiceId,
+    });
+    return NextResponse.json({ ok: true, skipped: true, reason: "Email service not configured" });
+  }
+
+  try {
+    const fromAddress =
+      process.env.EMAIL_FROM ?? "noreply@stellarsplit-dapp.vercel.app";
+    const appUrl = process.env.NEXT_PUBLIC_APP_URL ?? "";
+
+    const invoiceLink = invoiceId
+      ? `<p style="margin-top:16px"><a href="${appUrl}/invoice/${invoiceId}" style="color:#6366f1">View Invoice →</a></p>`
+      : "";
+
+    const html = `
+      <div style="font-family:system-ui,sans-serif;max-width:600px;margin:0 auto;background:#f9fafb;padding:20px">
+        <div style="background:#fff;padding:24px;border-radius:8px">
+          <h2 style="margin:0 0 12px;font-size:20px;color:#111827">StellarSplit Notification</h2>
+          <p style="margin:0 0 16px;color:#374151;line-height:1.6">${message.replace(/\n/g, "<br/>")}</p>
+          ${invoiceLink}
+        </div>
+        <p style="text-align:center;color:#9ca3af;font-size:12px;margin-top:16px">
+          © ${new Date().getFullYear()} StellarSplit · Automated notification
+        </p>
+      </div>
+    `;
+
+    const res = await fetch("https://api.resend.com/emails", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        from: fromAddress,
+        to: [to],
+        subject,
+        html,
+      }),
+    });
+
+    if (!res.ok) {
+      const errText = await res.text();
+      console.error("[Notifications] Resend API error:", errText);
+      return NextResponse.json({ error: "Email delivery failed" }, { status: 502 });
+    }
+
+    const data = (await res.json()) as { id?: string };
+    return NextResponse.json({ ok: true, messageId: data.id });
+  } catch (err) {
+    console.error("[Notifications] Email send error:", err);
+    return NextResponse.json({ error: "Internal error sending email" }, { status: 500 });
+  }
+}
diff --git a/src/app/api/rate-limit/status/route.ts b/src/app/api/rate-limit/status/route.ts
new file mode 100644
index 00000000..fef2aac3
--- /dev/null
+++ b/src/app/api/rate-limit/status/route.ts
@@ -0,0 +1,17 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { checkRateLimit, getRequestIdentity, PAYMENT_RATE_LIMIT } from '@/lib/rateLimit';
+
+export const dynamic = 'force-dynamic';
+
+/** GET /api/rate-limit/status — returns current rate limit state for the caller. */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const identity = getRequestIdentity(request);
+  // Peek at current state without recording an attempt (pass a copy with maxRequests+1 to avoid side effects).
+  const result = checkRateLimit(identity, { ...PAYMENT_RATE_LIMIT, maxRequests: PAYMENT_RATE_LIMIT.maxRequests + 1 });
+  return NextResponse.json({
+    limit: PAYMENT_RATE_LIMIT.maxRequests,
+    remaining: Math.min(result.remaining, PAYMENT_RATE_LIMIT.maxRequests),
+    resetAt: result.resetAt,
+    windowMs: PAYMENT_RATE_LIMIT.windowMs,
+  });
+}
diff --git a/src/app/api/settlement/execute/route.ts b/src/app/api/settlement/execute/route.ts
index 0d1c65db..daa615d2 100644
--- a/src/app/api/settlement/execute/route.ts
+++ b/src/app/api/settlement/execute/route.ts
@@ -1,7 +1,11 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { defaultSettlementEngine } from '@/lib/settlement';
+import { applyRateLimit } from '@/lib/middleware/rateLimitMiddleware';
+import { PAYMENT_RATE_LIMIT } from '@/lib/rateLimit';
 
 export async function POST(req: NextRequest) {
+  const rateCheck = applyRateLimit(req, PAYMENT_RATE_LIMIT);
+  if (rateCheck.limited) return rateCheck.response;
   try {
     const body = await req.json();
     const {
diff --git a/src/app/settings/notifications/page.tsx b/src/app/settings/notifications/page.tsx
index e7e789af..a57e27a1 100644
--- a/src/app/settings/notifications/page.tsx
+++ b/src/app/settings/notifications/page.tsx
@@ -8,6 +8,7 @@ const STORAGE_KEY = 'split-notification-prefs';
 interface EventPrefs {
   inApp: boolean;
   browser: boolean;
+  email: boolean;
 }
 
 interface NotifPrefs {
@@ -19,11 +20,11 @@ interface NotifPrefs {
 }
 
 const DEFAULT_PREFS: NotifPrefs = {
-  paymentReceived:    { inApp: true,  browser: false },
-  invoiceFunded:      { inApp: true,  browser: false },
-  refundIssued:       { inApp: true,  browser: false },
-  disputeRaised:      { inApp: true,  browser: false },
-  deadlineApproaching:{ inApp: true,  browser: false },
+  paymentReceived:    { inApp: true,  browser: false, email: false },
+  invoiceFunded:      { inApp: true,  browser: false, email: false },
+  refundIssued:       { inApp: true,  browser: false, email: false },
+  disputeRaised:      { inApp: true,  browser: false, email: false },
+  deadlineApproaching:{ inApp: true,  browser: false, email: false },
 };
 
 const EVENT_LABELS: { key: keyof NotifPrefs; label: string; description: string }[] = [
@@ -80,7 +81,7 @@ export default function NotificationPreferencesPage() {
     setMounted(true);
   }, []);
 
-  const toggle = (key: keyof NotifPrefs, col: 'inApp' | 'browser') => {
+  const toggle = (key: keyof NotifPrefs, col: 'inApp' | 'browser' | 'email') => {
     setPrefs((prev) => ({
       ...prev,
       [key]: { ...prev[key], [col]: !prev[key][col] },
@@ -151,16 +152,17 @@ export default function NotificationPreferencesPage() {
       {/* Preferences table */}
       <div className="bg-gray-900 border border-gray-800 rounded-xl overflow-hidden mb-6">
         {/* Column headers */}
-        <div className="grid grid-cols-[1fr_80px_80px] gap-4 px-4 py-3 border-b border-gray-800 text-xs font-semibold text-gray-400 uppercase tracking-wide">
+        <div className="grid grid-cols-[1fr_80px_80px_80px] gap-4 px-4 py-3 border-b border-gray-800 text-xs font-semibold text-gray-400 uppercase tracking-wide">
           <span>Event</span>
           <span className="text-center">In-App</span>
           <span className="text-center">Browser</span>
+          <span className="text-center">Email</span>
         </div>
 
         {EVENT_LABELS.map(({ key, label, description }, i) => (
           <div
             key={key}
-            className={`grid grid-cols-[1fr_80px_80px] gap-4 items-center px-4 py-4 ${
+            className={`grid grid-cols-[1fr_80px_80px_80px] gap-4 items-center px-4 py-4 ${
               i < EVENT_LABELS.length - 1 ? 'border-b border-gray-800' : ''
             }`}
           >
@@ -178,6 +180,14 @@ export default function NotificationPreferencesPage() {
                 disabled={browserDenied}
               />
             </div>
+            <div className="flex justify-center">
+              <span title="Configure RESEND_API_KEY to enable email notifications">
+                <Toggle
+                  on={prefs[key].email}
+                  onChange={() => toggle(key, 'email')}
+                />
+              </span>
+            </div>
           </div>
         ))}
       </div>
diff --git a/src/components/NotificationCenter.tsx b/src/components/NotificationCenter.tsx
index 4415f96d..29d37ce7 100644
--- a/src/components/NotificationCenter.tsx
+++ b/src/components/NotificationCenter.tsx
@@ -3,8 +3,9 @@
 import { useEffect, useRef, useState, useCallback } from "react";
 import Link from "next/link";
 import { splitClient } from "@/lib/stellar";
+import { apiFetch } from "@/lib/apiClient";
 
-export type NotificationType = "payment" | "funded" | "released" | "expired";
+export type NotificationType = "payment" | "funded" | "released" | "expired" | "reminder";
 
 export interface AppNotification {
   id: string;
@@ -64,6 +65,7 @@ const TYPE_ICONS: Record<NotificationType, string> = {
   funded: "✅",
   released: "🚀",
   expired: "⏰",
+  reminder: "🔔",
 };
 
 export default function NotificationCenter() {
@@ -214,15 +216,13 @@ export default function NotificationCenter() {
   const unread = notifications.filter((n) => !n.read).length;
   const badgeCount = unread > 99 ? "99+" : unread > 0 ? String(unread) : null;
 
-  // Focus first item when opening
-  useEffect(() => {
-    if (open) {
-      setTimeout(() => firstItemRef.current?.focus(), 50);
-    }
-  }, [open]);
-
-  const unread = notifications.filter((n) => !n.read).length;
-  const badgeCount = unread > 99 ? "99+" : unread > 0 ? String(unread) : null;
+  const persistMarkAllRead = async (ids: string[]) => {
+    await apiFetch("/api/notifications/mark-read", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ids }),
+    });
+  };
 
   const markAllRead = async () => {
     const previous = notifications;
diff --git a/src/lib/csp.ts b/src/lib/csp.ts
index 4a1cc833..0f7ae6e2 100644
--- a/src/lib/csp.ts
+++ b/src/lib/csp.ts
@@ -15,22 +15,54 @@ export interface BuildCSPOptions {
    * browsers that honour CSP over the legacy header.
    */
   allowFraming?: boolean;
+  /**
+   * Additional origins to include in the `connect-src` directive. These are
+   * merged with (and deduplicated against) the hardcoded Stellar origins.
+   * Passed from middleware when analytics or backup webhook origins are
+   * enabled via environment variables.
+   */
+  connectSrc?: string[];
+  /**
+   * URL to which the browser should POST CSP violation reports.
+   * When set, a `report-uri` directive is appended to the policy.
+   * Configure via the `CSP_REPORT_URI` environment variable.
+   */
+  reportUri?: string;
 }
 
-export function buildCSP(nonce: string, { allowFraming = false }: BuildCSPOptions = {}): string {
+export function buildCSP(
+  nonce: string,
+  { allowFraming = false, connectSrc, reportUri }: BuildCSPOptions = {},
+): string {
+  const connectSrcOrigins = [
+    "'self'",
+    'https://*.stellar.org',
+    'https://horizon-testnet.stellar.org',
+    'https://horizon.stellar.org',
+    'https://soroban-testnet.stellar.org',
+    ...(connectSrc ?? []),
+  ];
+  // Deduplicate while preserving insertion order
+  const uniqueConnectSrc = [...new Set(connectSrcOrigins)];
+
   const directives = [
     `default-src 'self'`,
     `script-src 'self' 'nonce-${nonce}' 'strict-dynamic'`,
     `style-src 'self' 'nonce-${nonce}' 'unsafe-inline'`,
     `img-src 'self' data: blob: https://www.gravatar.com`,
     `font-src 'self' data:`,
-    `connect-src 'self' https://*.stellar.org https://horizon-testnet.stellar.org https://horizon.stellar.org https://soroban-testnet.stellar.org`,
+    `connect-src ${uniqueConnectSrc.join(' ')}`,
     `object-src 'none'`,
     `base-uri 'self'`,
     `form-action 'self'`,
     allowFraming ? `frame-ancestors *` : `frame-ancestors 'none'`,
     `upgrade-insecure-requests`,
   ];
+
+  if (reportUri) {
+    directives.push(`report-uri ${reportUri}`);
+  }
+
   return directives.join("; ");
 }
 
diff --git a/src/lib/csrf.ts b/src/lib/csrf.ts
index 71d9fb5c..9fe8a519 100644
--- a/src/lib/csrf.ts
+++ b/src/lib/csrf.ts
@@ -9,10 +9,20 @@
 
 const TOKEN_TTL_MS = 60 * 60 * 1000; // 60 minutes
 
+const DEV_CSRF_SECRET = "dev-csrf-secret-not-for-production-use";
+
 function getCsrfSecret(): string {
   const secret = process.env.CSRF_SECRET;
   if (!secret) {
-    throw new Error("CSRF_SECRET environment variable is required but not set");
+    if (process.env.NODE_ENV === "production") {
+      throw new Error("CSRF_SECRET environment variable is required but not set");
+    }
+    // In development/test, fall back to a fixed secret so the app works
+    // out of the box without configuration. Never used in production.
+    console.warn(
+      "[CSRF] CSRF_SECRET is not set. Using insecure dev fallback. Set CSRF_SECRET in .env.local for local dev."
+    );
+    return DEV_CSRF_SECRET;
   }
   return secret;
 }
diff --git a/src/lib/middleware/rateLimitMiddleware.ts b/src/lib/middleware/rateLimitMiddleware.ts
new file mode 100644
index 00000000..f996af78
--- /dev/null
+++ b/src/lib/middleware/rateLimitMiddleware.ts
@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+import { checkRateLimit, getRequestIdentity, type RateLimitConfig } from '@/lib/rateLimit';
+
+/**
+ * Apply server-side rate limiting to a route handler.
+ *
+ * Returns a 429 NextResponse with standard headers when the limit is exceeded,
+ * otherwise returns null so the caller can proceed.
+ *
+ * Standard rate-limit response headers are set on BOTH the 429 and on passed
+ * requests (via the returned headers object) so clients can track their budget.
+ */
+export function applyRateLimit(
+  request: Request,
+  config: RateLimitConfig
+): { limited: true; response: NextResponse } | { limited: false; headers: Record<string, string> } {
+  const identity = getRequestIdentity(request);
+  const result = checkRateLimit(identity, config);
+
+  const headers: Record<string, string> = {
+    'X-RateLimit-Limit': String(config.maxRequests),
+    'X-RateLimit-Remaining': String(result.remaining),
+    'X-RateLimit-Reset': String(Math.ceil(result.resetAt / 1000)),
+  };
+
+  if (!result.allowed) {
+    const response = NextResponse.json(
+      {
+        error: 'Too many requests. Please wait before retrying.',
+        retryAfterSeconds: result.retryAfterSeconds,
+      },
+      { status: 429 }
+    );
+    response.headers.set('Retry-After', String(result.retryAfterSeconds));
+    Object.entries(headers).forEach(([k, v]) => response.headers.set(k, v));
+    return { limited: true, response };
+  }
+
+  return { limited: false, headers };
+}
diff --git a/src/lib/paymentReceiptEmailer.ts b/src/lib/paymentReceiptEmailer.ts
index d180e935..d83468bd 100644
--- a/src/lib/paymentReceiptEmailer.ts
+++ b/src/lib/paymentReceiptEmailer.ts
@@ -58,31 +58,110 @@ export async function sendPaymentReceiptEmail(
       };
     }
 
-    // TODO: Implement actual email sending
-    // For now, return a successful response indicating the infrastructure is in place.
-    // In production, integrate with:
-    // 1. Resend (recommended) via RESEND_API_KEY
-    // 2. SMTP fallback via nodemailer
-    // 3. AWS SES
-    // 4. SendGrid
-
-    // Log the email send attempt
+    const apiKey = process.env.RESEND_API_KEY;
+
+    if (!apiKey) {
+      // Graceful degradation: log and skip when not configured (dev/staging).
+      console.log(
+        `[Email] RESEND_API_KEY not configured — skipping receipt email to ${data.recipientEmail}`,
+        { invoiceId: data.invoiceId, transactionHash: data.transactionHash }
+      );
+      await markEmailAsSent(data.invoiceId, data.transactionHash, data.recipientEmail);
+      return {
+        success: true,
+        messageId: `skipped-${Date.now()}`,
+        recipient: data.recipientEmail,
+      };
+    }
+
+    const fromAddress =
+      process.env.EMAIL_FROM ?? "noreply@stellarsplit-dapp.vercel.app";
+    const appUrl = process.env.NEXT_PUBLIC_APP_URL ?? "";
+
+    const subject = `Payment Received – Invoice #${data.invoiceId}`;
+    const formattedDate = new Intl.DateTimeFormat("en-US", {
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    }).format(data.paidAt);
+
+    const html = `
+      <div style="font-family:system-ui,sans-serif;max-width:600px;margin:0 auto;background:#f9fafb;padding:20px">
+        <div style="background:#fff;padding:30px;border-radius:8px;margin-bottom:20px">
+          <h1 style="margin:0 0 8px;font-size:24px;font-weight:700;color:#111827">Payment Received ✓</h1>
+          <p style="margin:0;color:#6b7280;font-size:14px">Invoice #${data.invoiceId}</p>
+        </div>
+        <div style="background:#fff;padding:30px;border-radius:8px;margin-bottom:20px">
+          <p style="margin:0 0 16px;font-size:16px;color:#111827">Hi ${data.recipientName},</p>
+          <p style="margin:0 0 20px;font-size:15px;line-height:1.6;color:#374151">
+            A payment has been confirmed on the Stellar network for Invoice #${data.invoiceId}.
+          </p>
+          <div style="background:#f3f4f6;padding:20px;border-radius:6px;margin-bottom:20px">
+            <table style="width:100%;font-size:14px;border-collapse:collapse">
+              <tr>
+                <td style="padding:8px 0;color:#6b7280;width:40%">Amount:</td>
+                <td style="padding:8px 0;font-weight:600;color:#111827">${data.paymentAmount} ${data.paymentAsset}</td>
+              </tr>
+              <tr>
+                <td style="padding:8px 0;color:#6b7280">Date:</td>
+                <td style="padding:8px 0;font-weight:600;color:#111827">${formattedDate}</td>
+              </tr>
+              <tr>
+                <td style="padding:8px 0;color:#6b7280">From:</td>
+                <td style="padding:8px 0;font-family:monospace;font-size:12px;color:#374151;word-break:break-all">${data.payerAddress}</td>
+              </tr>
+              <tr>
+                <td style="padding:8px 0;color:#6b7280">Transaction:</td>
+                <td style="padding:8px 0;font-family:monospace;font-size:11px;color:#374151;word-break:break-all">${data.transactionHash}</td>
+              </tr>
+            </table>
+          </div>
+          <p style="margin:0">
+            <a href="${appUrl}/invoice/${data.invoiceId}"
+               style="display:inline-block;background:#6366f1;color:#fff;padding:12px 24px;border-radius:6px;text-decoration:none;font-weight:600;font-size:14px">
+              View Invoice
+            </a>
+          </p>
+        </div>
+        <p style="text-align:center;color:#9ca3af;font-size:12px">
+          © ${new Date().getFullYear()} StellarSplit · Automated receipt
+        </p>
+      </div>
+    `;
+
     console.log(`[Email] Sending receipt to ${data.recipientEmail}`, {
       invoiceId: data.invoiceId,
       transactionHash: data.transactionHash,
-      paidAt: data.paidAt,
     });
 
-    // Record that email was sent
-    await markEmailAsSent(
-      data.invoiceId,
-      data.transactionHash,
-      data.recipientEmail,
-    );
+    const res = await fetch("https://api.resend.com/emails", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        from: fromAddress,
+        to: [data.recipientEmail],
+        subject,
+        html,
+      }),
+    });
+
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`Resend API error ${res.status}: ${errText}`);
+    }
+
+    const resData = (await res.json()) as { id?: string };
+
+    await markEmailAsSent(data.invoiceId, data.transactionHash, data.recipientEmail);
 
     return {
       success: true,
-      messageId: `mock-${Date.now()}`,
+      messageId: resData.id,
       recipient: data.recipientEmail,
     };
   } catch (error) {
diff --git a/src/lib/rateLimit.ts b/src/lib/rateLimit.ts
new file mode 100644
index 00000000..b56db599
--- /dev/null
+++ b/src/lib/rateLimit.ts
@@ -0,0 +1,116 @@
+/**
+ * In-memory sliding-window rate limiter for payment operations.
+ *
+ * Uses a Map keyed by identity (wallet address or IP fallback) to track
+ * request timestamps within a rolling window. Requests older than the
+ * window are pruned on each check so memory stays bounded.
+ *
+ * Limits are intentionally generous for legitimate use while blocking
+ * automated abuse. The whitelist allows bypass for known safe identities
+ * (e.g., integration test runners, internal service accounts).
+ */
+
+export interface RateLimitConfig {
+  /** Rolling window in milliseconds. */
+  windowMs: number;
+  /** Maximum requests allowed within the window. */
+  maxRequests: number;
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  /** Remaining requests in the current window. */
+  remaining: number;
+  /** Unix ms timestamp when the window resets. */
+  resetAt: number;
+  /** Seconds until the window resets (for Retry-After header). */
+  retryAfterSeconds: number;
+}
+
+// Payment-specific limits (per wallet address or IP).
+export const PAYMENT_RATE_LIMIT: RateLimitConfig = {
+  windowMs: 60 * 1000,   // 1-minute window
+  maxRequests: 10,        // 10 payment attempts per minute
+};
+
+// Lighter limit for read operations like invoice fetches.
+export const QUERY_RATE_LIMIT: RateLimitConfig = {
+  windowMs: 60 * 1000,
+  maxRequests: 120,
+};
+
+const store = new Map<string, number[]>();
+
+// Identities that are always allowed through (integration tests, admin).
+const WHITELIST = new Set<string>(
+  (process.env.RATE_LIMIT_WHITELIST ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+);
+
+/**
+ * Check whether `identity` is within the rate limit and record this attempt.
+ *
+ * @param identity - Wallet address, user ID, or IP to bucket requests by.
+ * @param config   - Window and limit configuration.
+ */
+export function checkRateLimit(identity: string, config: RateLimitConfig): RateLimitResult {
+  if (WHITELIST.has(identity)) {
+    return { allowed: true, remaining: config.maxRequests, resetAt: Date.now() + config.windowMs, retryAfterSeconds: 0 };
+  }
+
+  const now = Date.now();
+  const windowStart = now - config.windowMs;
+
+  // Get or create the timestamp list for this identity.
+  const timestamps = (store.get(identity) ?? []).filter((t) => t > windowStart);
+
+  const allowed = timestamps.length < config.maxRequests;
+  if (allowed) {
+    timestamps.push(now);
+  }
+  store.set(identity, timestamps);
+
+  const resetAt = (timestamps[0] ?? now) + config.windowMs;
+  const retryAfterSeconds = Math.ceil((resetAt - now) / 1000);
+
+  return {
+    allowed,
+    remaining: Math.max(0, config.maxRequests - timestamps.length),
+    resetAt,
+    retryAfterSeconds,
+  };
+}
+
+/**
+ * Extract the best available identity for rate limiting from a request.
+ * Prefers the X-Wallet-Address header (set by the frontend after wallet connect),
+ * then falls back to X-Forwarded-For / remote IP.
+ */
+export function getRequestIdentity(request: Request): string {
+  // Wallet address is the most precise identity — one wallet = one limit bucket.
+  const wallet = (request.headers as Headers).get('x-wallet-address');
+  if (wallet && /^G[A-Z0-9]{55}$/.test(wallet)) return wallet;
+
+  // Fall back to IP-based limiting.
+  const forwarded = (request.headers as Headers).get('x-forwarded-for');
+  if (forwarded) return forwarded.split(',')[0]!.trim();
+
+  return 'unknown';
+}
+
+/**
+ * Prune stale entries periodically to prevent unbounded memory growth.
+ * Safe to call in a background interval.
+ */
+export function pruneRateLimitStore(): void {
+  const now = Date.now();
+  // Use the maximum window across all configs (1 minute) as the prune threshold.
+  const threshold = Math.max(PAYMENT_RATE_LIMIT.windowMs, QUERY_RATE_LIMIT.windowMs);
+  for (const [key, timestamps] of store) {
+    const fresh = timestamps.filter((t) => t > now - threshold);
+    if (fresh.length === 0) {
+      store.delete(key);
+    } else {
+      store.set(key, fresh);
+    }
+  }
+}
diff --git a/src/middleware.ts b/src/middleware.ts
index 33010f2d..4aec4dc0 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -27,6 +27,10 @@ function getBackupWebhookOrigins(): string[] {
     .filter(Boolean);
 }
 
+function getCspReportUri(): string | undefined {
+  return process.env.CSP_REPORT_URI || undefined;
+}
+
 /**
  * Generates a fresh CSP nonce per request and forwards it two ways:
  *  - as a request header, so Server Components can read it via next/headers
@@ -47,6 +51,7 @@ export function middleware(request: NextRequest) {
   const csp = buildCSP(nonce, {
     allowFraming: isEmbed,
     connectSrc: connectSrc.length > 0 ? connectSrc : undefined,
+    reportUri: getCspReportUri(),
   });
 
   const requestHeaders = new Headers(request.headers);