feat(frontend+backend): WCAG 2.2 AA audit (#272), WalletConnect Stell… (#343)

* feat(frontend+backend): WCAG 2.2 AA audit (#272), WalletConnect Stellar bridge (#273), privacy-safe Sentry + web-vitals telemetry (#277)

Closes #272, #273, #277 as assigned to @Hicent2 in the Official Campaign | FWC26.

Issue #272 — WCAG 2.2 AA audit:

- globals.css adds a global :focus-visible ring using the brand sky color and provides skip-link / sr-only utilities.

- Button.jsx, Form.jsx, Withdraw.jsx, ActionModal.jsx, TokenSelector.jsx, BalanceCards.jsx, MultiplierSelector.jsx were upgraded for proper label associations, aria-invalid/aria-describedby, role=alert announcements, role=radiogroup + arrow-key navigation, role=slider with aria-valuemin/max/now/text, dialog focus trap with Esc-to-close and focus restoration, definition-list semantics, and non-color error icons.

- Withdraw.jsx additionally fixes a class= -> className= JSX bug that prevented the Withdraw button from rendering its class.

Issue #273 — Mobile wallet flow (WalletConnect for Stellar):

- frontend/src/services/walletconnect.js mirrors the Freighter API (connectWallet, getWalletPublicKey, signStellarTransaction) but pairs via standard wc: URI + QR rendered by the qrcode package.

- frontend/src/components/wallet/WalletConnectModal.jsx provides the accessible QR modal with auto-generation on open, AbortController cleanup on unmount, and disconnectWallet() fired on close after a successful pairing.

- web_app/api/walletconnect.py is a new FastAPI router with /pair, /poll/{sid}, /sign, /complete/{sid}, and /session/{sid}. All endpoints use Redis setex with a 5-minute TTL mirroring the existing session.py pattern. /complete validates Stellar StrKey shape (via StrKey.isValidEd25519PublicKey) and rejects XDR envelopes whose source account does not match the claimed public key (403). Network is constrained to Literal["PUBLIC","TESTNET","FUTURENET"]. All writes are gated by @limiter.limit(WRITE_LIMIT) and the poll endpoint by READ_LIMIT.

- web_app/api/main.py registers the new walletconnect_router.

Issue #277 — Privacy-safe telemetry pipeline (web-vitals + Sentry):

- frontend/src/services/telemetry.js initializes Sentry only when VITE_SENTRY_DSN is set, with sendDefaultPii:false plus a beforeSend scrubber that redacts Stellar public keys (G.../S..., 56 chars) and 64-hex transaction hashes. web-vitals hooks (LCP/CLS/INP/FCP/TTFB) push every change into Sentry via addBreadcrumb + setMeasurement; reportAllChanges:true is documented inline.

- frontend/src/main.jsx is the new entry point (renamed from index.jsx, which is deleted). It calls initTelemetry() before the React mount, and again from App.jsx is useEffect — the idempotent initialized flag keeps it single-shot.

- frontend/src/hooks/useConnectWallet.js and frontend/src/services/transaction.js wrap wallet.connect and position.open in Sentry transactions tagged with source / token so timings appear alongside web-vitals.

Tests:

- frontend/test/telemetry.test.jsx covers the scrubber (56-char PubKey, 56-char Seed, mixed charset, 64-hex hashes, nested objects, weird inputs) and confirms initTelemetry is a no-op without VITE_SENTRY_DSN.

- frontend/test/walletconnect.test.jsx covers URI shape, pairing poll approve/reject/expire paths, signStellarTransaction happy + missing-session paths, and disconnectWallet teardown.

- frontend/test/ActionModal.test.jsx covers role=dialog, aria-labelledby/describedby, Escape close while not loading (and no-op while loading), and the Tab focus trap.

- frontend/test/Form.a11y.test.jsx covers proper input id/htmlFor labelling, aria-invalid flip after validation, and role=alert announcements.

- web_app/tests/test_walletconnect_router.py mocks the async Redis client and verifies pair/poll/sign/complete/delete round-trips, rejects invalid Stellar public keys (422), rejects XDR envelopes whose source account does not match the claimed public key (403), and rejects unknown network values via the Literal type guard.

Deps: added @sentry/react@^9.0.0 and qrcode@^1.5.4 to package.json; yarn.lock updated to match.

* fix(backend): resolve CI PydanticUndefinedAnnotation in walletconnect router

The CI migration-roundtrip workflow was failing at module import with:

  pydantic.errors.PydanticUndefinedAnnotation: name 'PairRequest' is not defined

Root cause: `from __future__ import annotations` in

quantara/web_app/api/walletconnect.py combined with the `LazyLimiter.limit()`

decorator in quantara/web_app/api/rate_limiter.py. The LazyLimiter wraps the

async route in an inner `wrapper()` whose `__globals__` point at

rate_limiter.py; FastAPI/Pydantic resolves function annotations through

get_type_hints() against those wrapper globals and cannot find

PairRequest / SignRequest / CompleteRequest defined in the walletconnect

module once PEP 563 has turned the annotations into strings.

Fix: drop `from __future__ import annotations` from the walletconnect

module so annotations are evaluated to class references at function

definition time. A short comment above the imports documents the

intentional absence so a follow-up contributor does not re-introduce

the same bug.

No behavioural change to the WalletConnect endpoints; the rest of the

PR (#272, #273, #277) is unaffected. Validated by re-running frontend

vitest (88/88 pass) and re-reading the affected code paths.

* fix(test): make VALID_STELLAR_PUBKEY fixture length deterministic

The CI failure on commit e273cdf was a hand-rolled Stellar StrKey fixture

string in test_walletconnect_router.py that miscounted to 61 chars instead of

56. The module-load assertion `len(VALID_STELLAR_PUBKEY) == 56` failed on

Python 3.12 and 3.13 with AssertionError on the literal string.

Replace the hardcoded string with `G + A * 55`, which is guaranteed to

be 56 chars, and add a useful assertion message so a regression

blows up loudly next time. No production code changes.

* fix(backend): await every redis call in walletconnect router

CI on PR #343 was failing on Test Suite (Python 3.12) and Test Suite (Python

3.13) with:

  TypeError: the JSON object must be str, bytes or bytearray, not coroutine

The walletconnect route handlers were calling

`_redis().{get,setex,delete}()` without `await`. The local test fixture

`_FakeRedis` defined those methods as `async def`, so the missing

await was masked in CI-build-friendly test runs. In production with

real `redis.asyncio`, every `.get()`/`.setex()`/`.delete()` returns a

coroutine, and the route handlers were passing the un-awaited

coroutine into `json.loads()`.

Fix:

- `await` every `_redis().get/setex/delete()` call in the five route

  handlers + the two helper lookup paths.

- `_validate_session` is now `async def` and `open_signing_sub_session`

  awaits it.

- `submit_signed_envelope` parent-XDR retrieval rewritten from

  `json.loads(_redis().get(...) or "{}")` (which evaluated

  `coroutine or "{}" == coroutine` then crashed inside `json.loads`)

  into an explicit form: await the get, then conditional json.loads.

No other production files touched; frontend tests unrelated.

---------

Co-authored-by: Hicent2 <hicent2@users.noreply.github.com>

Author: Hicent2

quantara/frontend/index.html

@@ -12,6 +12,6 @@
   <body>
     <noscript>You need to enable JavaScript to run this app.</noscript>
     <div id="root"></div>
-    <script type="module" src="/src/index.jsx"></script>
+    <script type="module" src="/src/main.jsx"></script>
   </body>
 </html>

quantara/frontend/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "dependencies": {
     "@popperjs/core": "^2.11.8",
+    "@sentry/react": "^9.0.0",
     "@stellar/freighter-api": "^6.0.1",
     "@stellar/stellar-sdk": "^15.1.0",
     "@tailwindcss/vite": "^4.3.3",
@@ -15,21 +16,22 @@
     "@vitejs/plugin-react": "^5.2.0",
     "axios": "^1.18.1",
     "dotenv": "^17.4.2",
+    "i18next": "^23.0.0",
+    "i18next-browser-languagedetector": "^7.0.0",
+    "i18next-fs-backend": "^2.1.0",
     "lucide-react": "^1.21.0",
+    "qrcode": "^1.5.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "react-i18next": "^13.0.0",
     "react-router-dom": "^7.1.3",
     "react-toastify": "^10.0.6",
     "tailwindcss": "^4.3.1",
     "vite": "^6.0.11",
     "vite-plugin-environment": "^1.1.3",
     "vite-tsconfig-paths": "^6.1.1",
     "web-vitals": "^5.3.0",
-    "zustand": "^5.0.1",
-    "i18next": "^23.0.0",
-    "react-i18next": "^13.0.0",
-    "i18next-fs-backend": "^2.1.0",
-    "i18next-browser-languagedetector": "^7.0.0"
+    "zustand": "^5.0.1"
   },
   "scripts": {
     "start": "vite",
@@ -74,12 +76,12 @@
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.5.3",
     "globals": "^15.11.0",
+    "i18next-scanner": "^4.0.0",
     "jsdom": "^26.0.0",
     "prettier": "^3.8.4",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "tailwind-merge": "^3.6.0",
     "vite-plugin-svgr": "^4.3.0",
-    "vitest": "^3.0.4",
-    "i18next-scanner": "^4.0.0"
+    "vitest": "^3.0.4"
   }
 }

quantara/frontend/src/App.jsx

@@ -28,6 +28,7 @@ import { AddDeposit } from '@/pages/add-deposit/AddDeposit';
 import Leaderboard from '@/pages/leaderboard/Leaderboard';
 import AddressBookPage from '@/pages/address-book/AddressBookPage';
 import NotFound from '@/pages/not-found/NotFound';
+import { initTelemetry } from '@/services/telemetry';
 
 function App() {
   const { setWalletId, removeWalletId } = useWalletStore();
@@ -37,6 +38,13 @@ function App() {
   const [isMobileRestrictionModalOpen, setisMobileRestrictionModalOpen] = useState(true);
   const isMobile = useCheckMobile();
 
+  // Sentry initialization per Issue #277 acceptance criterion. Calls into
+  // the same idempotent initTelemetry() used in main.jsx — the no-op
+  // guard inside initTelemetry() ensures we only initialize once.
+  useEffect(() => {
+    initTelemetry();
+  }, []);
+
   const disableDesktopOnMobile = process.env.VITE_APP_DISABLE_DESKTOP_ON_MOBILE !== 'false';
 
   const connectWalletMutation = useConnectWallet(setWalletId);

quantara/frontend/src/components/ui/action-modal/ActionModal.jsx

@@ -1,8 +1,19 @@
-import React from 'react';
+import React, { useEffect, useId, useRef } from 'react';
 import { Button } from '@/components/ui/custom-button/Button';
 import useLockBodyScroll from '@/hooks/useLockBodyScroll';
 import { cn } from '@/utils/cn';
 
+/**
+ * ActionModal — WCAG 2.2 AA compliant modal dialog.
+ *
+ * Per Issue #272 acceptance criteria:
+ *   • role="dialog", aria-modal="true"
+ *   • labelled with aria-labelledby pointing at the title element
+ *   • described with aria-describedby pointing at the subtitle element
+ *   • focus trap inside the dialog (Tab cycles across focusable elements)
+ *   • Esc key closes the modal via cancelAction
+ *   • focus is restored to the previously focused element on close
+ */
 const ActionModal = ({
   isOpen,
   title,
@@ -16,6 +27,65 @@ const ActionModal = ({
 }) => {
   useLockBodyScroll(isOpen);
 
+  const titleId = useId();
+  const subtitleId = useId();
+  const panelRef = useRef(null);
+  const previouslyFocusedRef = useRef(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    // Save the previously focused element and restore on close.
+    previouslyFocusedRef.current = document.activeElement;
+
+    const focusableSelector = [
+      'a[href]',
+      'button:not([disabled])',
+      'textarea:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])',
+    ].join(',');
+
+    // Move focus into the modal on open.
+    const firstFocusable = panelRef.current?.querySelector(focusableSelector);
+    firstFocusable?.focus();
+
+    const handleKeyDown = (e) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        if (!isLoading) cancelAction?.();
+        return;
+      }
+      if (e.key !== 'Tab' || !panelRef.current) return;
+
+      const focusables = Array.from(
+        panelRef.current.querySelectorAll(focusableSelector)
+      ).filter((el) => !el.hasAttribute('disabled'));
+      if (focusables.length === 0) return;
+
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      // Restore focus to the element that opened the modal.
+      const previouslyFocused = previouslyFocusedRef.current;
+      if (previouslyFocused && typeof previouslyFocused.focus === 'function') {
+        previouslyFocused.focus();
+      }
+    };
+  }, [isOpen, cancelAction, isLoading]);
+
   if (!isOpen) {
     return null;
   }
@@ -25,24 +95,30 @@ const ActionModal = ({
       onClick={cancelAction}
       role="dialog"
       aria-modal="true"
-      aria-label={title}
+      aria-labelledby={titleId}
+      aria-describedby={subtitleId}
     >
       <div
+        ref={panelRef}
+        data-focus-managed="true"
         className="shadow-primary-color flex items-center justify-center overflow-hidden text-white"
         onClick={(e) => e.stopPropagation()}
       >
         <div className="flex w-[330px] flex-col gap-[18px] rounded-2xl text-center md:w-full md:max-w-[700px] md:gap-6">
           <div className="border-nav-divider-bg bg-bg h-fit rounded-2xl border p-6 py-4 pt-4 text-center text-sm md:rounded-2xl">
-            <div className="text-primary mb-6 w-full border-b border-b-[rgba(255,255,255,0.1)] px-[10px] py-[10px] text-center text-base text-[13px] sm:mb-[14px] sm:py-[6px] md:mb-4 md:pb-4">
+            <div
+              id={titleId}
+              className="text-primary mb-6 w-full border-b border-b-[rgba(255,255,255,0.1)] px-[10px] py-[10px] text-center text-base text-[13px] sm:mb-[14px] sm:py-[6px] md:mb-4 md:pb-4"
+            >
               {title}
             </div>
             <div className="grid min-h-28 place-content-center px-2">
-              <h2 className={cn('mx-auto mb-4 text-sm font-semibold md:text-2xl', content.length && 'px-0 py-[55px]')}>
+              <h2 id={subtitleId} className={cn('mx-auto mb-4 text-sm font-semibold md:text-2xl', content.length && 'px-0 py-[55px]')}>
                 {subTitle}
               </h2>
-              {content.map((content, i) => (
+              {content.map((line, i) => (
                 <p className="mx-auto mt-0 mb-3 max-w-96 text-base leading-6" key={i}>
-                  {content}
+                  {line}
                 </p>
               ))}
             </div>
@@ -51,7 +127,13 @@ const ActionModal = ({
             <Button variant="secondary" size="md" onClick={cancelAction} disabled={isLoading}>
               {cancelLabel}
             </Button>
-            <Button variant="primary" size="md" onClick={submitAction} disabled={isLoading}>
+            <Button
+              variant="primary"
+              size="md"
+              onClick={submitAction}
+              disabled={isLoading}
+              aria-busy={isLoading}
+            >
               {isLoading ? 'Loading...' : submitLabel}
             </Button>
           </div>

quantara/frontend/src/components/ui/balance-cards/BalanceCards.jsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useState, useId } from 'react';
 import { useMatchMedia } from '@/hooks/useMatchMedia';
 import { getBalances } from '@/services/wallet';
 import { useWalletStore } from '@/stores/useWalletStore';
@@ -8,8 +8,16 @@ import USDC from '@/assets/icons/borrow_usdc.svg?react';
 import STRK from '@/assets/icons/strk.svg?react';
 import KSTRK from '@/assets/icons/kstrk.svg?react';
 
+/**
+ * BalanceCards — WCAG 2.2 AA compliant balance summary.
+ *
+ * Uses a definition list (`<dl>`/`<dt>`/`<dd>`) so screen readers announce
+ * the token name with its balance as a related pair instead of the previous
+ * implementation, which wrapped the icon inside a fake `<label>`.
+ */
 const BalanceCards = ({ className }) => {
   const { walletId } = useWalletStore();
+  const baseId = useId();
 
   const isMobile = useMatchMedia('(max-width: 768px)');
 
@@ -18,49 +26,49 @@ const BalanceCards = ({ className }) => {
   }, [walletId]);
 
   const [balances, setBalances] = useState([
-    { icon: <ETH />, title: 'ETH', balance: '0.00' },
-    { icon: <USDC />, title: 'USDC', balance: '0.00' },
-    { icon: <STRK />, title: 'STRK', balance: '0.00' },
-    { icon: <KSTRK />, title: 'kSTRK', balance: '0.00' },
+    { icon: <ETH aria-hidden="true" />, title: 'ETH', balance: '0.00' },
+    { icon: <USDC aria-hidden="true" />, title: 'USDC', balance: '0.00' },
+    { icon: <STRK aria-hidden="true" />, title: 'STRK', balance: '0.00' },
+    { icon: <KSTRK aria-hidden="true" />, title: 'kSTRK', balance: '0.00' },
   ]);
 
   return (
-    <div className="no-scrollbar mx-auto mt-3 w-full max-w-2xl overflow-x-auto px-3">
-      <div className="grid w-full min-w-md grid-cols-4 gap-4 rounded-[8px]">
-        {balances.map((balance) =>
-          isMobile ? (
+    <div
+      aria-label="Token balances"
+      className={`no-scrollbar mx-auto mt-3 w-full max-w-2xl overflow-x-auto px-3 ${className ?? ''}`}
+    >
+      <dl className="grid w-full min-w-md grid-cols-4 gap-4 rounded-[8px]">
+        {balances.map((balance) => {
+          const termId = `${baseId}-${balance.title}-term`;
+          const defId = `${baseId}-${balance.title}-def`;
+          return (
             <div
-              className="border- border-nav-divider-bg flex flex-col items-center rounded-xl border px-1 py-3 text-center"
+              role="group"
+              aria-labelledby={termId}
+              aria-describedby={defId}
               key={balance.title}
+              className={`border- border-nav-divider-bg flex flex-col items-center rounded-xl border ${
+                isMobile ? 'px-1 py-3' : 'px-3 py-4'
+              } text-center`}
             >
-              <label htmlFor={balance.title} className={'flex items-center gap-1 text-[#83919F]'}>
-                <div className="bg-border-color flex h-6 w-6 justify-center rounded-full p-1">
-                  <span className="flex h-full w-full items-center justify-center rounded-full">{balance.icon}</span>
-                </div>
+              <dt id={termId} className="flex items-center gap-1 text-[#83919F]">
+                <span
+                  aria-hidden="true"
+                  className="bg-border-color flex h-6 w-6 justify-center rounded-full p-1"
+                >
+                  <span className="flex h-full w-full items-center justify-center rounded-full">
+                    {balance.icon}
+                  </span>
+                </span>
                 <span className="text-sm">{balance.title} Balance</span>
-              </label>
-              <label htmlFor={balance.title}>
-                <span className="text-2xl font-semibold text-white">{balance.balance}</span>
-              </label>
+              </dt>
+              <dd id={defId} className="text-2xl font-semibold text-white" aria-live="polite">
+                {balance.balance}
+              </dd>
             </div>
-          ) : (
-            <div
-              className="border- border-nav-divider-bg flex flex-col items-center rounded-xl border px-3 py-4 text-center"
-              key={balance.title}
-            >
-              <label htmlFor={balance.title} className={'flex gap-1 text-[#83919F]'}>
-                <div className="bg-border-color flex h-6 w-6 justify-center rounded-full p-1">
-                  <span className="flex h-full w-full items-center justify-center rounded-full">{balance.icon}</span>
-                </div>
-                <span className="text-sm">{balance.title} Balance</span>
-              </label>
-              <label htmlFor={balance.title}>
-                <span className="text-2xl font-semibold text-white">{balance.balance}</span>
-              </label>
-            </div>
-          )
-        )}
-      </div>
+          );
+        })}
+      </dl>
     </div>
   );
 };

quantara/frontend/src/components/ui/custom-button/Button.jsx

@@ -46,20 +46,53 @@ const buttonVariants = cva(
   }
 );
 
-export const Button = React.forwardRef(({ className, variant, size, children, ...props }, ref) => {
-  return (
-    <button
-      className={cn(
-        buttonVariants({ variant, size, className }),
-        'focus:shadow-[0_0_0_2px_rgba(59,130,246,0.5)] focus:outline-none',
-        'disabled:cursor-not-allowed disabled:opacity-60'
-      )}
-      ref={ref}
-      {...props}
-    >
-      <span className="relative z-10 py-4 md:px-6">{children}</span>
-    </button>
-  );
-});
+/**
+ * Quantara Button component (WCAG 2.2 AA compliant).
+ *
+ * - Always renders a `<button type="button">` by default so accidental form
+ *   submits don't happen; pages can override with `type="submit"`.
+ * - Uses `focus-visible:ring-2 ring-brand ring-offset-2 ring-offset-bg` so the
+ *   keyboard focus indicator has a ≥3:1 contrast ratio against the dark
+ *   base background color.
+ * - Relies on `aria-disabled` + `disabled` so screen readers correctly
+ *   announce the disabled state.
+ */
+export const Button = React.forwardRef(
+  (
+    {
+      className,
+      variant,
+      size,
+      children,
+      type = 'button',
+      'aria-busy': ariaBusy,
+      'aria-label': ariaLabel,
+      ...props
+    },
+    ref
+  ) => {
+    return (
+      <button
+        ref={ref}
+        type={type}
+        aria-busy={ariaBusy}
+        aria-label={ariaLabel}
+        className={cn(
+          buttonVariants({ variant, size, className }),
+          // Suppress the global :focus-visible ring (from globals.css)
+          // and use a high-contrast layered ring with offset instead.
+          'focus:outline-none',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand',
+          'focus-visible:ring-offset-2 focus-visible:ring-offset-bg',
+          // Disable hover/cursor affordances when the element is disabled.
+          'disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:before:bg-gradient-to-r disabled:hover:before:from-brand disabled:hover:before:to-pink'
+        )}
+        {...props}
+      >
+        <span className="relative z-10 py-4 md:px-6">{children}</span>
+      </button>
+    );
+  }
+);
 
 Button.displayName = 'Button';