From f5e4da10ce1847f003013b87f812fafb617de1a5 Mon Sep 17 00:00:00 2001
From: Thompson <140930314+Godbrand0@users.noreply.github.com>
Date: Mon, 28 Sep 2026 18:23:28 -0400
Subject: [PATCH] Require signed ownership proof for wallet linking; add
 non-color cues to status badges

Wallet (#32): linking a Stellar address now runs challenge -> Freighter signMessage -> PATCH with signature. A Freighter account that differs from the profile's address is held pending until the user explicitly confirms, and AuthUser.stellarAddress overrides a stale cached address on load.

Badges (#49): every status/difficulty badge gets a distinct icon; paid is the only solid-filled badge (vs. funded's tinted lock); open/refunded use dashed outlines. Darker text shades and a WCAG AA contrast test cover all pairs in both themes.
---
 src/app/connect/ConnectPanel.tsx         |  28 +++++
 src/components/ui/Badge.contrast.test.ts |  57 +++++++++
 src/components/ui/Badge.test.tsx         |  30 +++++
 src/components/ui/Badge.tsx              | 134 ++++++++++++++++++---
 src/context/WalletContext.test.tsx       | 119 +++++++++++++++++--
 src/context/WalletContext.tsx            | 145 ++++++++++++++++++++---
 src/lib/messages.ts                      |   5 +
 src/lib/wallet.ts                        |  35 ++++++
 8 files changed, 509 insertions(+), 44 deletions(-)
 create mode 100644 src/components/ui/Badge.contrast.test.ts

diff --git a/src/app/connect/ConnectPanel.tsx b/src/app/connect/ConnectPanel.tsx
index ec385a3..3aea880 100644
--- a/src/app/connect/ConnectPanel.tsx
+++ b/src/app/connect/ConnectPanel.tsx
@@ -62,6 +62,9 @@ export function ConnectPanel() {
     error,
     initializing: walletInitializing,
     linkState,
+    pendingRelinkAddress,
+    confirmRelink,
+    cancelRelink,
     connect,
     disconnect,
   } = useWallet();
@@ -229,6 +232,31 @@ export function ConnectPanel() {
                 </p>
               </div>
             )}
+            {pendingRelinkAddress && (
+              <div
+                role="alertdialog"
+                aria-labelledby="relink-title"
+                className="mt-3 rounded-lg bg-amber-50 px-4 py-3 text-sm text-amber-800 ring-1 ring-inset ring-amber-200 dark:bg-amber-500/10 dark:text-amber-200 dark:ring-amber-500/30"
+              >
+                <p id="relink-title" className="font-medium">
+                  {messages["connect.wallet.relinkTitle"]}
+                </p>
+                <p className="mt-1">
+                  {t("connect.wallet.relinkBody", {
+                    address: `${pendingRelinkAddress.slice(0, 4)}...${pendingRelinkAddress.slice(-4)}`,
+                    onFile: `${user?.stellarAddress?.slice(0, 4)}...${user?.stellarAddress?.slice(-4)}`,
+                  })}
+                </p>
+                <div className="mt-3 flex gap-2">
+                  <Button size="sm" onClick={confirmRelink} loading={connecting}>
+                    {messages["connect.wallet.relinkConfirm"]}
+                  </Button>
+                  <Button size="sm" variant="ghost" onClick={cancelRelink}>
+                    {messages["connect.wallet.relinkCancel"]}
+                  </Button>
+                </div>
+              </div>
+            )}
             <Button
               className="mt-4 w-full"
               variant="outline"
diff --git a/src/components/ui/Badge.contrast.test.ts b/src/components/ui/Badge.contrast.test.ts
new file mode 100644
index 0000000..6faa99a
--- /dev/null
+++ b/src/components/ui/Badge.contrast.test.ts
@@ -0,0 +1,57 @@
+/**
+ * Badge.contrast.test.ts (#49)
+ *
+ * WCAG AA (4.5:1) check for every status/difficulty badge text/background
+ * pair, light and dark. Tailwind palette hexes are inlined; translucent dark
+ * backgrounds (`/10`) are composited over the dark page background.
+ */
+
+const HEX = {
+  white: "#ffffff",
+  "slate-100": "#f1f5f9", "slate-300": "#cbd5e1", "slate-700": "#334155", "slate-800": "#1e293b",
+  "sky-50": "#f0f9ff", "sky-300": "#7dd3fc", "sky-500": "#0ea5e9", "sky-800": "#075985",
+  "amber-50": "#fffbeb", "amber-300": "#fcd34d", "amber-500": "#f59e0b", "amber-800": "#92400e",
+  "indigo-50": "#eef2ff", "indigo-300": "#a5b4fc", "indigo-500": "#6366f1", "indigo-800": "#3730a3",
+  "violet-50": "#f5f3ff", "violet-300": "#c4b5fd", "violet-500": "#8b5cf6", "violet-800": "#5b21b6",
+  "emerald-50": "#ecfdf5", "emerald-300": "#6ee7b7", "emerald-500": "#10b981", "emerald-700": "#047857", "emerald-800": "#065f46", "emerald-950": "#022c22",
+  "rose-50": "#fff1f2", "rose-300": "#fda4af", "rose-500": "#f43f5e", "rose-800": "#9f1239",
+  "fuchsia-50": "#fdf4ff", "fuchsia-300": "#f0abfc", "fuchsia-500": "#d946ef", "fuchsia-800": "#86198f",
+} as const;
+
+type RGB = [number, number, number];
+const rgb = (h: string): RGB => [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16)) as RGB;
+const over = (fg: RGB, a: number, bg: RGB): RGB => fg.map((c, i) => c * a + bg[i] * (1 - a)) as RGB;
+const lum = ([r, g, b]: RGB) => {
+  const f = (c: number) => ((c /= 255) <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+};
+const ratio = (a: RGB, b: RGB) => {
+  const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+const PAGE_DARK = rgb("#0a0a0f"); // globals.css dark background
+const tint = (name: keyof typeof HEX) => over(rgb(HEX[name]), 0.1, PAGE_DARK);
+const c = (name: keyof typeof HEX) => rgb(HEX[name]);
+
+// [label, foreground, background]
+const PAIRS: Array<[string, RGB, RGB]> = [
+  ["open light", c("slate-700"), c("slate-100")],
+  ["open dark", c("slate-300"), c("slate-800")],
+  ["refunded light", c("slate-700"), c("slate-100")],
+  ["refunded dark", c("slate-300"), c("slate-800")],
+  ["paid light", c("white"), c("emerald-700")],
+  ["paid dark", c("emerald-950"), c("emerald-500")],
+  ...(["sky", "amber", "indigo", "violet", "rose", "fuchsia", "emerald"] as const).flatMap(
+    (h): Array<[string, RGB, RGB]> => [
+      [`${h} light`, c(`${h}-800` as keyof typeof HEX), c(`${h}-50` as keyof typeof HEX)],
+      [`${h} dark`, c(`${h}-300` as keyof typeof HEX), tint(`${h}-500` as keyof typeof HEX)],
+    ],
+  ),
+];
+
+describe("badge colour contrast", () => {
+  it.each(PAIRS)("%s meets WCAG AA", (_label, fg, bg) => {
+    expect(ratio(fg, bg)).toBeGreaterThanOrEqual(4.5);
+  });
+});
diff --git a/src/components/ui/Badge.test.tsx b/src/components/ui/Badge.test.tsx
index 599fe90..b237a33 100644
--- a/src/components/ui/Badge.test.tsx
+++ b/src/components/ui/Badge.test.tsx
@@ -89,3 +89,33 @@ describe("Badge", () => {
     expect(screen.getByText("Custom").className).toMatch(/test-extra-class/);
   });
 });
+
+describe("non-colour cues (#49)", () => {
+  it.each([...ALL_STATUSES])("renders a decorative icon alongside the %s label", (status) => {
+    const { container } = render(<StatusBadge status={status} />);
+    const svg = container.querySelector("svg");
+    expect(svg).toBeInTheDocument();
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("gives every status a distinct icon", () => {
+    const icons = ALL_STATUSES.map((status) => {
+      const { container, unmount } = render(<StatusBadge status={status} />);
+      const html = container.querySelector("svg")?.getAttribute("class");
+      unmount();
+      return html;
+    });
+    expect(new Set(icons).size).toBe(ALL_STATUSES.length);
+  });
+
+  it("makes funded and paid differ by fill as well as icon", () => {
+    render(
+      <>
+        <StatusBadge status="funded" />
+        <StatusBadge status="paid" />
+      </>,
+    );
+    expect(screen.getByText("Paid").className).toMatch(/bg-emerald-700/);
+    expect(screen.getByText("Funded").className).not.toMatch(/bg-emerald-700/);
+  });
+});
diff --git a/src/components/ui/Badge.tsx b/src/components/ui/Badge.tsx
index 950d5fe..f2b611c 100644
--- a/src/components/ui/Badge.tsx
+++ b/src/components/ui/Badge.tsx
@@ -1,38 +1,130 @@
+import {
+  CheckCheck,
+  CircleDashed,
+  Eye,
+  Flame,
+  Gem,
+  GitMerge,
+  Lock,
+  Sprout,
+  TimerOff,
+  Undo2,
+  UserCheck,
+  Zap,
+  type LucideIcon,
+} from "lucide-react";
 import { cn } from "@/lib/utils";
 import type { BountyStatus, Difficulty } from "@/types";
 
-const statusStyles: Record<BountyStatus, string> = {
-  open: "bg-slate-100 text-slate-700 ring-slate-200 dark:bg-slate-800 dark:text-slate-300 dark:ring-slate-700",
-  funded: "bg-sky-50 text-sky-700 ring-sky-200 dark:bg-sky-500/10 dark:text-sky-300 dark:ring-sky-500/30",
-  claimed: "bg-amber-50 text-amber-700 ring-amber-200 dark:bg-amber-500/10 dark:text-amber-300 dark:ring-amber-500/30",
-  in_review: "bg-indigo-50 text-indigo-700 ring-indigo-200 dark:bg-indigo-500/10 dark:text-indigo-300 dark:ring-indigo-500/30",
-  merged: "bg-violet-50 text-violet-700 ring-violet-200 dark:bg-violet-500/10 dark:text-violet-300 dark:ring-violet-500/30",
-  paid: "bg-emerald-50 text-emerald-700 ring-emerald-200 dark:bg-emerald-500/10 dark:text-emerald-300 dark:ring-emerald-500/30",
-  refunded: "bg-slate-100 text-slate-600 ring-slate-200 dark:bg-slate-800 dark:text-slate-400 dark:ring-slate-700",
-  expired: "bg-rose-50 text-rose-700 ring-rose-200 dark:bg-rose-500/10 dark:text-rose-300 dark:ring-rose-500/30",
+/**
+ * Badge encoding (#49)
+ *
+ * Colour is never the only carrier of meaning. Every state pairs a hue with
+ * (1) a distinct lucide icon and (2) a text label, and the money-adjacent
+ * pairs that are most easily confused get a third cue:
+ *
+ *   funded (escrowed)  → Lock icon, tinted sky, solid outline
+ *   paid   (released)  → CheckCheck icon, *filled* emerald, white text
+ *
+ * `paid` is the only status with a solid fill, so it reads differently from
+ * every tinted badge even in greyscale. `refunded` and `open` use a dashed
+ * outline (nothing is committed / money returned) to separate them from the
+ * solid-outlined states. Emerald is used for the terminal "money delivered"
+ * state and for `beginner`; both are non-interactive pills, so they don't
+ * collide with the emerald button affordance (buttons are never pill-shaped
+ * with an icon prefix).
+ *
+ * Contrast (WCAG AA, 4.5:1) of every text/background pair is asserted in
+ * Badge.contrast.test.ts against the Tailwind palette hexes below.
+ */
+interface BadgeStyle {
+  className: string;
+  Icon: LucideIcon;
+}
+
+const statusStyles: Record<BountyStatus, BadgeStyle> = {
+  open: {
+    Icon: CircleDashed,
+    className:
+      "bg-slate-100 text-slate-700 ring-slate-300 ring-dashed dark:bg-slate-800 dark:text-slate-300 dark:ring-slate-600",
+  },
+  funded: {
+    Icon: Lock,
+    className:
+      "bg-sky-50 text-sky-800 ring-sky-300 dark:bg-sky-500/10 dark:text-sky-300 dark:ring-sky-500/40",
+  },
+  claimed: {
+    Icon: UserCheck,
+    className:
+      "bg-amber-50 text-amber-800 ring-amber-300 dark:bg-amber-500/10 dark:text-amber-300 dark:ring-amber-500/40",
+  },
+  in_review: {
+    Icon: Eye,
+    className:
+      "bg-indigo-50 text-indigo-800 ring-indigo-300 dark:bg-indigo-500/10 dark:text-indigo-300 dark:ring-indigo-500/40",
+  },
+  merged: {
+    Icon: GitMerge,
+    className:
+      "bg-violet-50 text-violet-800 ring-violet-300 dark:bg-violet-500/10 dark:text-violet-300 dark:ring-violet-500/40",
+  },
+  paid: {
+    Icon: CheckCheck,
+    className:
+      "bg-emerald-700 text-white ring-emerald-700 font-semibold dark:bg-emerald-500 dark:text-emerald-950 dark:ring-emerald-500",
+  },
+  refunded: {
+    Icon: Undo2,
+    className:
+      "bg-slate-100 text-slate-700 ring-slate-400 ring-dashed dark:bg-slate-800 dark:text-slate-300 dark:ring-slate-500",
+  },
+  expired: {
+    Icon: TimerOff,
+    className:
+      "bg-rose-50 text-rose-800 ring-rose-300 dark:bg-rose-500/10 dark:text-rose-300 dark:ring-rose-500/40",
+  },
 };
 
-const difficultyStyles: Record<Difficulty, string> = {
-  beginner: "bg-emerald-50 text-emerald-700 ring-emerald-200 dark:bg-emerald-500/10 dark:text-emerald-300 dark:ring-emerald-500/30",
-  intermediate: "bg-amber-50 text-amber-700 ring-amber-200 dark:bg-amber-500/10 dark:text-amber-300 dark:ring-amber-500/30",
-  advanced: "bg-rose-50 text-rose-700 ring-rose-200 dark:bg-rose-500/10 dark:text-rose-300 dark:ring-rose-500/30",
-  expert: "bg-fuchsia-50 text-fuchsia-700 ring-fuchsia-200 dark:bg-fuchsia-500/10 dark:text-fuchsia-300 dark:ring-fuchsia-500/30",
+const difficultyStyles: Record<Difficulty, BadgeStyle> = {
+  beginner: {
+    Icon: Sprout,
+    className:
+      "bg-emerald-50 text-emerald-800 ring-emerald-300 dark:bg-emerald-500/10 dark:text-emerald-300 dark:ring-emerald-500/40",
+  },
+  intermediate: {
+    Icon: Zap,
+    className:
+      "bg-amber-50 text-amber-800 ring-amber-300 dark:bg-amber-500/10 dark:text-amber-300 dark:ring-amber-500/40",
+  },
+  advanced: {
+    Icon: Flame,
+    className:
+      "bg-rose-50 text-rose-800 ring-rose-300 dark:bg-rose-500/10 dark:text-rose-300 dark:ring-rose-500/40",
+  },
+  expert: {
+    Icon: Gem,
+    className:
+      "bg-fuchsia-50 text-fuchsia-800 ring-fuchsia-300 dark:bg-fuchsia-500/10 dark:text-fuchsia-300 dark:ring-fuchsia-500/40",
+  },
 };
 
 function BaseBadge({
   className,
+  Icon,
   children,
 }: {
   className?: string;
+  Icon?: LucideIcon;
   children: React.ReactNode;
 }) {
   return (
     <span
       className={cn(
-        "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium ring-1 ring-inset",
+        "inline-flex items-center gap-1 rounded-full px-2.5 py-0.5 text-xs font-medium ring-1 ring-inset",
         className,
       )}
     >
+      {Icon && <Icon aria-hidden="true" className="h-3 w-3 shrink-0" />}
       {children}
     </span>
   );
@@ -54,14 +146,22 @@ const statusLabels: Record<BountyStatus, string> = {
 
 export function StatusBadge({ status }: { status: BountyStatus }) {
   return (
-    <BaseBadge className={statusStyles[status]}>
+    <BaseBadge
+      className={statusStyles[status].className}
+      Icon={statusStyles[status].Icon}
+    >
       {statusLabels[status]}
     </BaseBadge>
   );
 }
 
 export function DifficultyBadge({ difficulty }: { difficulty: Difficulty }) {
-  return <BaseBadge className={difficultyStyles[difficulty]}>{difficulty}</BaseBadge>;
+  const { className, Icon } = difficultyStyles[difficulty];
+  return (
+    <BaseBadge className={cn("capitalize", className)} Icon={Icon}>
+      {difficulty}
+    </BaseBadge>
+  );
 }
 
 export function Badge({ children, className }: { children: React.ReactNode; className?: string }) {
diff --git a/src/context/WalletContext.test.tsx b/src/context/WalletContext.test.tsx
index e9ea9dd..98c6126 100644
--- a/src/context/WalletContext.test.tsx
+++ b/src/context/WalletContext.test.tsx
@@ -12,6 +12,7 @@ import {
   checkNetworkMismatch,
   connectWallet,
   getActiveFreighterAddress,
+  signOwnershipMessage,
 } from "@/lib/wallet";
 import { apiRequest } from "@/lib/api";
 
@@ -31,6 +32,7 @@ jest.mock("@/lib/wallet", () => ({
   // about the mismatch paths specifically override these.
   getActiveFreighterAddress: jest.fn().mockResolvedValue(null),
   checkNetworkMismatch: jest.fn().mockResolvedValue(null),
+  signOwnershipMessage: jest.fn(),
 }));
 
 // WalletContext imports apiRequest for profile linking on connect(), which
@@ -45,8 +47,17 @@ const mockGetActiveFreighterAddress = getActiveFreighterAddress as jest.Mock;
 const mockCheckNetworkMismatch = checkNetworkMismatch as jest.Mock;
 const mockConnectWallet = connectWallet as jest.Mock;
 const mockApiRequest = apiRequest as jest.Mock;
+const mockSign = signOwnershipMessage as jest.Mock;
 const mockRefresh = jest.fn();
 
+/** Backend stub: challenge POST returns a nonce message, everything else resolves. */
+function stubBackend() {
+  mockSign.mockResolvedValue("SIG");
+  mockApiRequest.mockImplementation(async (path: string) =>
+    path.endsWith("/challenge") ? { message: "mergefi.link:NONCE1", nonce: "NONCE1" } : undefined,
+  );
+}
+
 function TestConsumer() {
   const {
     address,
@@ -57,6 +68,9 @@ function TestConsumer() {
     initializing,
     linkState,
     network,
+    pendingRelinkAddress,
+    confirmRelink,
+    cancelRelink,
     connect,
     disconnect,
     getError,
@@ -78,6 +92,9 @@ function TestConsumer() {
       <div data-testid="link-state">{linkState}</div>
       <div data-testid="read-after-connect">{readAfterConnect}</div>
       <div data-testid="recheck-result">{recheckResult}</div>
+      <div data-testid="pending-relink">{pendingRelinkAddress ?? "none"}</div>
+      <button onClick={() => void confirmRelink()}>confirm-relink</button>
+      <button onClick={cancelRelink}>cancel-relink</button>
       <button onClick={() => void connect()}>connect</button>
       <button onClick={disconnect}>disconnect</button>
       <button
@@ -120,6 +137,7 @@ beforeEach(() => {
   mockConnectWallet.mockReset();
   mockApiRequest.mockReset();
   mockRefresh.mockReset();
+  mockSign.mockReset();
 });
 
 describe("WalletContext — mount reconciliation (#402)", () => {
@@ -331,7 +349,7 @@ describe("WalletContext — connect() (#231)", () => {
       address: "GNEWADDRESS",
       network: "TESTNET",
     });
-    mockApiRequest.mockResolvedValue(undefined);
+    stubBackend();
 
     render(
       <WalletProvider>
@@ -342,13 +360,44 @@ describe("WalletContext — connect() (#231)", () => {
     fireEvent.click(screen.getByText("connect"));
 
     await waitFor(() => expect(mockRefresh).toHaveBeenCalledTimes(1));
+    // Proof of ownership (#32): challenge -> sign -> PATCH carrying signature.
     expect(mockApiRequest).toHaveBeenCalledWith(
-      "/users/user-1/stellar-address",
-      expect.objectContaining({ method: "PATCH" }),
-    );
+      "/users/user-1/stellar-address/challenge",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(mockSign).toHaveBeenCalledWith("mergefi.link:NONCE1", "GNEWADDRESS");
+    const patch = mockApiRequest.mock.calls.find(([, init]) => init?.method === "PATCH");
+    expect(patch?.[0]).toBe("/users/user-1/stellar-address");
+    expect(JSON.parse(patch?.[1].body)).toEqual({
+      stellarAddress: "GNEWADDRESS",
+      nonce: "NONCE1",
+      message: "mergefi.link:NONCE1",
+      signature: "SIG",
+    });
     expect(screen.getByTestId("error")).toHaveTextContent("none");
   });
 
+  it("does not link the profile when the user declines to sign (#32)", async () => {
+    mockUseAuth.mockReturnValue({ user: { id: "user-1" }, loading: false, refresh: mockRefresh });
+    mockConnectWallet.mockResolvedValue({ address: "GNEWADDRESS", network: "TESTNET" });
+    stubBackend();
+    mockSign.mockRejectedValue(new Error("User declined access"));
+
+    render(
+      <WalletProvider>
+        <TestConsumer />
+      </WalletProvider>,
+    );
+    fireEvent.click(screen.getByText("connect"));
+
+    await waitFor(() =>
+      expect(screen.getByTestId("error")).toHaveTextContent(/didn't sign the ownership proof/),
+    );
+    expect(mockApiRequest.mock.calls.some(([, init]) => init?.method === "PATCH")).toBe(false);
+    expect(mockRefresh).not.toHaveBeenCalled();
+    expect(screen.getByTestId("link-state")).toHaveTextContent("local");
+  });
+
   it("getError() returns the fresh failure reason synchronously right after connect() settles (#235)", async () => {
     mockConnectWallet.mockRejectedValue(
       new Error("Wallet access was not granted."),
@@ -584,25 +633,77 @@ describe("WalletContext — linkState (#456)", () => {
     await waitFor(() => expect(screen.getByTestId("link-state")).toHaveTextContent("linked"));
   });
 
-  it("is 'local', not 'linked', when the profile holds a different address", async () => {
-    // Payouts still go to the on-file address, so presenting this as complete
-    // would misdescribe where the money goes.
+  it("holds a different Freighter account as pending instead of re-linking it (#32)", async () => {
     mockUseAuth.mockReturnValue({
       user: { id: "user-1", stellarAddress: "GDIFFERENTADDRESS" },
       loading: false,
       refresh: mockRefresh,
     });
     mockConnectWallet.mockResolvedValue({ address: ADDRESS, network: "TESTNET" });
-    mockApiRequest.mockResolvedValue(undefined);
+    stubBackend();
 
     render(
       <WalletProvider>
         <TestConsumer />
       </WalletProvider>,
     );
+    await waitFor(() => expect(screen.getByTestId("address")).toHaveTextContent("GDIFFERENTADDRESS"));
 
     fireEvent.click(screen.getByText("connect"));
-    await waitFor(() => expect(screen.getByTestId("link-state")).toHaveTextContent("local"));
+    await waitFor(() => expect(screen.getByTestId("pending-relink")).toHaveTextContent(ADDRESS));
+
+    // Nothing sent, nothing adopted, until the user confirms.
+    expect(mockApiRequest).not.toHaveBeenCalled();
+    expect(screen.getByTestId("address")).toHaveTextContent("GDIFFERENTADDRESS");
+    expect(window.localStorage.getItem(WALLET_KEY)).toBe("GDIFFERENTADDRESS");
+
+    fireEvent.click(screen.getByText("confirm-relink"));
+    await waitFor(() => expect(mockRefresh).toHaveBeenCalledTimes(1));
+    expect(screen.getByTestId("pending-relink")).toHaveTextContent("none");
+    expect(screen.getByTestId("address")).toHaveTextContent(ADDRESS);
+    expect(mockSign).toHaveBeenCalledWith("mergefi.link:NONCE1", ADDRESS);
+  });
+
+  it("discards a pending re-link on cancel without touching the profile (#32)", async () => {
+    mockUseAuth.mockReturnValue({
+      user: { id: "user-1", stellarAddress: "GDIFFERENTADDRESS" },
+      loading: false,
+      refresh: mockRefresh,
+    });
+    mockConnectWallet.mockResolvedValue({ address: ADDRESS, network: "TESTNET" });
+    stubBackend();
+
+    render(
+      <WalletProvider>
+        <TestConsumer />
+      </WalletProvider>,
+    );
+    fireEvent.click(screen.getByText("connect"));
+    await waitFor(() => expect(screen.getByTestId("pending-relink")).toHaveTextContent(ADDRESS));
+    fireEvent.click(screen.getByText("cancel-relink"));
+
+    expect(screen.getByTestId("pending-relink")).toHaveTextContent("none");
+    expect(mockApiRequest).not.toHaveBeenCalled();
+    expect(screen.getByTestId("link-state")).toHaveTextContent("linked");
+  });
+
+  it("treats the profile address as authoritative over a stale cached one on load (#32)", async () => {
+    window.localStorage.setItem(WALLET_KEY, "GSTALECACHED");
+    mockUseAuth.mockReturnValue({
+      user: { id: "user-1", stellarAddress: "GONFILEADDRESS" },
+      loading: false,
+      refresh: mockRefresh,
+    });
+
+    render(
+      <WalletProvider>
+        <TestConsumer />
+      </WalletProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("address")).toHaveTextContent("GONFILEADDRESS"));
+    expect(window.localStorage.getItem(WALLET_KEY)).toBe("GONFILEADDRESS");
+    expect(screen.getByTestId("link-state")).toHaveTextContent("linked");
   });
 
   it("stays 'local' when the profile PATCH fails, so the UI can offer a retry", async () => {
diff --git a/src/context/WalletContext.tsx b/src/context/WalletContext.tsx
index 5559adc..b35dc57 100644
--- a/src/context/WalletContext.tsx
+++ b/src/context/WalletContext.tsx
@@ -13,6 +13,7 @@ import {
   connectWallet as freighterConnect,
   getActiveFreighterAddress,
   checkNetworkMismatch,
+  signOwnershipMessage,
 } from "@/lib/wallet";
 import { apiRequest } from "@/lib/api";
 import { STELLAR_NETWORK } from "@/lib/config";
@@ -68,6 +69,14 @@ interface WalletContextValue {
   recheckNetworkMismatch: () => Promise<boolean>;
   /** How durable the current connection is. See {@link WalletLinkState}. */
   linkState: WalletLinkState;
+  /**
+   * Set when Freighter's account differs from the address already linked to
+   * the profile. Nothing is re-linked (or even adopted locally) until the
+   * user calls `confirmRelink()`; `cancelRelink()` discards it (#32).
+   */
+  pendingRelinkAddress: string | null;
+  confirmRelink: () => Promise<string | null>;
+  cancelRelink: () => void;
   connect: () => Promise<string | null>;
   disconnect: () => void;
   /**
@@ -82,6 +91,13 @@ interface WalletContextValue {
   getError: () => string | null;
 }
 
+/** Challenge issued by `POST /users/:id/stellar-address/challenge`. */
+interface OwnershipChallenge {
+  /** Exact text to sign. Server-built: embeds domain, address, nonce, expiry. */
+  message: string;
+  nonce: string;
+}
+
 const WalletContext = createContext<WalletContextValue | null>(null);
 
 export function WalletProvider({ children }: { children: React.ReactNode }) {
@@ -93,6 +109,9 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
   const [addressMismatch, setAddressMismatch] = useState(false);
   const [networkMismatch, setNetworkMismatch] = useState(false);
   const [initializing, setInitializing] = useState(true);
+  const [pendingRelinkAddress, setPendingRelinkAddress] = useState<
+    string | null
+  >(null);
   const errorRef = useRef<string | null>(null);
   const updateError = useCallback((message: string | null) => {
     errorRef.current = message;
@@ -194,36 +213,104 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
     }
   }, [user, authLoading]);
 
-  const connect = useCallback(async () => {
-    updateError(null);
-    setConnecting(true);
+  // #32: `AuthUser.stellarAddress` is the backend's source of truth for the
+  // payout wallet. A localStorage value written in an earlier session — or
+  // from another device that has since linked something else — must not be
+  // shown as "connected" once the profile says otherwise, so the profile
+  // address overwrites the cache whenever they disagree. A profile with no
+  // address leaves a cached one alone: that's the honest "local" state.
+  useEffect(() => {
+    if (authLoading || !user?.stellarAddress) return;
+    const onFile = user.stellarAddress;
+    if (addressRef.current === onFile) return;
     try {
-      const connection = await freighterConnect();
-      setAddress(connection.address);
-      setNetwork(connection.network);
+      window.localStorage.setItem(WALLET_KEY, onFile);
+    } catch {
+      // Private-mode storage failure: in-memory state below still corrects.
+    }
+    setAddress(onFile);
+    setNetwork(STELLAR_NETWORK);
+    setAddressMismatch(false);
+  }, [user?.stellarAddress, authLoading]);
+
+  /**
+   * Link `walletAddress` to the profile, gated on a signed proof of
+   * ownership (#32). The backend issues a nonce-bearing challenge; Freighter
+   * signs it; the PATCH carries the signature for server-side verification.
+   * Never sends a bare address.
+   */
+  const linkWithProof = useCallback(
+    async (userId: string, walletAddress: string) => {
+      const challenge = await apiRequest<OwnershipChallenge>(
+        `/users/${userId}/stellar-address/challenge`,
+        {
+          method: "POST",
+          body: JSON.stringify({ stellarAddress: walletAddress }),
+        },
+      );
+      const signature = await signOwnershipMessage(
+        challenge.message,
+        walletAddress,
+      );
+      await apiRequest(`/users/${userId}/stellar-address`, {
+        method: "PATCH",
+        body: JSON.stringify({
+          stellarAddress: walletAddress,
+          nonce: challenge.nonce,
+          message: challenge.message,
+          signature,
+        }),
+      });
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const adoptAndLink = useCallback(
+    async (walletAddress: string) => {
+      setAddress(walletAddress);
+      setNetwork(STELLAR_NETWORK);
       setAddressMismatch(false);
       setNetworkMismatch(false);
-      window.localStorage.setItem(WALLET_KEY, connection.address);
+      window.localStorage.setItem(WALLET_KEY, walletAddress);
 
       if (user) {
         try {
-          await apiRequest(`/users/${user.id}/stellar-address`, {
-            method: "PATCH",
-            body: JSON.stringify({ stellarAddress: connection.address }),
-          });
-          await refresh();
-        } catch {
+          await linkWithProof(user.id, walletAddress);
+        } catch (err) {
           // The wallet is still usable for signing this session even if the
-          // backend write failed, but the user needs to know their payout
-          // wallet wasn't actually saved to their profile (#229). Leaving
+          // link failed, but the user needs to know their payout wallet
+          // wasn't actually saved to their profile (#229). Leaving
           // `linkState` at "local" is what makes that visible — the Connect
           // CTA stays available so they can retry the link.
           updateError(
-            "Wallet connected, but couldn't save it to your profile — try reconnecting.",
+            err instanceof Error && /reject|declin|denied/i.test(err.message)
+              ? "Wallet connected, but you didn't sign the ownership proof, so it wasn't linked to your profile."
+              : "Wallet connected, but couldn't save it to your profile — try reconnecting.",
           );
         }
       }
-      return connection.address;
+      return walletAddress;
+    },
+    [user, linkWithProof, updateError],
+  );
+
+  const connect = useCallback(async () => {
+    updateError(null);
+    setPendingRelinkAddress(null);
+    setConnecting(true);
+    try {
+      const connection = await freighterConnect();
+      // A different account than the one on file must never silently replace
+      // the payout wallet (#32). Hold it as pending and let the UI ask.
+      if (
+        user?.stellarAddress &&
+        user.stellarAddress !== connection.address
+      ) {
+        setPendingRelinkAddress(connection.address);
+        return null;
+      }
+      return await adoptAndLink(connection.address);
     } catch (err) {
       // connectWallet() (lib/wallet.ts) already throws a real Error with a
       // specific, actionable message for every failure path it detects —
@@ -240,7 +327,22 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
     } finally {
       setConnecting(false);
     }
-  }, [user, refresh, updateError]);
+  }, [user, adoptAndLink, updateError]);
+
+  const confirmRelink = useCallback(async () => {
+    if (!pendingRelinkAddress) return null;
+    updateError(null);
+    setConnecting(true);
+    try {
+      const target = pendingRelinkAddress;
+      setPendingRelinkAddress(null);
+      return await adoptAndLink(target);
+    } finally {
+      setConnecting(false);
+    }
+  }, [pendingRelinkAddress, adoptAndLink, updateError]);
+
+  const cancelRelink = useCallback(() => setPendingRelinkAddress(null), []);
 
   const disconnect = useCallback(() => {
     // Best-effort local clear: localStorage throws in Safari private browsing.
@@ -251,6 +353,7 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
     }
     setAddress(null);
     setNetwork(null);
+    setPendingRelinkAddress(null);
     // Clear the mismatch flags too. They used to survive a disconnect, and
     // `useWalletAction` blocks on them — so "disconnect and reconnect" left
     // the user in a loop that the UI gave them no way out of (#456).
@@ -299,6 +402,9 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
       networkMismatch,
       recheckNetworkMismatch,
       linkState,
+      pendingRelinkAddress,
+      confirmRelink,
+      cancelRelink,
       connect,
       disconnect,
       getError,
@@ -313,6 +419,9 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
       networkMismatch,
       recheckNetworkMismatch,
       linkState,
+      pendingRelinkAddress,
+      confirmRelink,
+      cancelRelink,
       connect,
       disconnect,
       getError,
diff --git a/src/lib/messages.ts b/src/lib/messages.ts
index e1f2eca..58bcc12 100644
--- a/src/lib/messages.ts
+++ b/src/lib/messages.ts
@@ -66,6 +66,11 @@ export const messages = {
   "connect.wallet.mismatchTitle": "Wallet address mismatch",
   "connect.wallet.mismatchBody":
     "The connected wallet ({address}) differs from the payout address on file ({onFile}). Payouts are sent to the address on file until you reconnect.",
+  "connect.wallet.relinkTitle": "Replace your payout wallet?",
+  "connect.wallet.relinkBody":
+    "Freighter is now using {address}, but your payout address on file is {onFile}. Replacing it redirects all future payouts and requires you to sign an ownership proof with the new wallet. Nothing changes unless you confirm.",
+  "connect.wallet.relinkConfirm": "Sign and replace wallet",
+  "connect.wallet.relinkCancel": "Keep current wallet",
   "connect.wallet.disconnect": "Disconnect wallet",
   "connect.completeTitle": "You're connected",
   "connect.completeBody": "GitHub and your payout wallet are both linked. You're ready to fund or claim bounties.",
diff --git a/src/lib/wallet.ts b/src/lib/wallet.ts
index 83777e9..b4454b9 100644
--- a/src/lib/wallet.ts
+++ b/src/lib/wallet.ts
@@ -5,6 +5,7 @@ import {
   getAddress,
   getNetwork,
   signTransaction as freighterSignTransaction,
+  signMessage as freighterSignMessage,
 } from "@stellar/freighter-api";
 import { STELLAR_NETWORK } from "./config";
 import type { StellarNetwork } from "./env";
@@ -110,3 +111,37 @@ export async function signTransaction(xdr: string, address: string) {
     networkPassphrase: NETWORK_PASSPHRASES[STELLAR_NETWORK],
   });
 }
+
+/**
+ * Sign a server-issued ownership challenge with Freighter (#32).
+ *
+ * This is message signing, not transaction signing: nothing is submitted to
+ * the network and no funds can move. Replay protection comes from the nonce
+ * and domain the backend embeds in `message`, which the caller must not
+ * construct itself.
+ *
+ * Resolves to the signature as base64. Throws if the user rejects the
+ * request or the signer isn't the address being proven.
+ */
+export async function signOwnershipMessage(
+  message: string,
+  address: string,
+): Promise<string> {
+  const result = await freighterSignMessage(message, {
+    address,
+    networkPassphrase: NETWORK_PASSPHRASES[STELLAR_NETWORK],
+  });
+  if (result.error || !result.signedMessage) {
+    throw new Error(
+      result.error?.message ?? "Wallet did not sign the ownership message.",
+    );
+  }
+  if (result.signerAddress && result.signerAddress !== address) {
+    throw new Error("The signing wallet doesn't match the address being linked.");
+  }
+  const signed = result.signedMessage;
+  if (typeof signed === "string") return signed;
+  let binary = "";
+  for (const byte of signed as Uint8Array) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}