From 733dfb643e0e06b922d6a4396ba0f3c468cbbcae Mon Sep 17 00:00:00 2001
From: Maryermarh <Maryermarh@users.noreply.github.com>
Date: Fri, 25 Sep 2026 03:20:20 +0100
Subject: [PATCH] fix(auth): centralize session recovery and sanitize SVG
 uploads

Add proactive expiry checks and centralized 401 refresh/logout handling, safely rasterize static SVG uploads, and clarify sanitizer module boundaries.

Closes #1309
Closes #1310
Closes #1311
Closes #1312
---
 backend/src/auth/auth.controller.ts           |   8 +
 backend/src/dispute/dispute.controller.ts     |   6 +-
 backend/src/dispute/dispute.service.ts        |  10 +-
 backend/src/documents/documents.controller.ts |  11 +-
 .../pipes/file-validation.pipe.spec.ts        | 140 ++++++
 .../documents/pipes/file-validation.pipe.ts   | 415 +++++++++++++++-
 .../pipes/mime-type-validation.pipe.ts        |   1 +
 frontend/__tests__/abdulrcrtw.test.ts         |   2 +-
 .../(protected)/admin/providers/page.tsx      |  69 ++-
 .../[locale]/(protected)/admin/users/page.tsx |  98 ++--
 .../(protected)/disputes/[id]/page.tsx        | 274 +++++-----
 .../[locale]/(protected)/disputes/page.tsx    |  87 ++--
 .../(protected)/documents/upload/page.tsx     |  81 ++-
 frontend/app/[locale]/(protected)/layout.tsx  |  81 +--
 .../(protected)/settings/data/page.tsx        |  47 +-
 .../(protected)/settings/security/page.tsx    |   3 +-
 frontend/app/[locale]/2fa/setup/page.tsx      |  53 +-
 frontend/app/[locale]/2fa/verify/page.tsx     |  33 +-
 .../app/[locale]/forgot-password/page.tsx     |  20 +-
 frontend/app/[locale]/login/LoginForm.tsx     |  21 +-
 frontend/app/[locale]/reset-password/page.tsx |  25 +-
 frontend/app/[locale]/verify-email/page.tsx   |  54 +-
 frontend/components/LanguageSwitcher.tsx      |  20 +-
 frontend/components/SessionBootstrap.test.tsx |  72 +++
 frontend/components/SessionBootstrap.tsx      |  72 +++
 .../components/disputes/FileDisputeModal.tsx  |  21 +-
 .../components/layout/NotificationBell.tsx    |  39 +-
 frontend/lib/__tests__/session-expiry.test.ts | 156 +++---
 frontend/lib/api-client.ts                    | 466 ++++++++++++------
 frontend/lib/auth-session.test.ts             | 131 +++++
 frontend/lib/auth-session.ts                  | 261 +++++++++-
 frontend/lib/disputes.test.ts                 |  94 ++++
 frontend/lib/disputes.ts                      | 218 ++++++++
 frontend/lib/document-mapper.test.ts          |  36 ++
 frontend/lib/document-mapper.ts               |  36 ++
 frontend/lib/document-sanitizer.test.ts       |  83 ++++
 frontend/lib/document-sanitizer.ts            | 258 +++++++++-
 frontend/lib/sanitize.ts                      |  25 +-
 frontend/lib/session-expiry-warning.ts        |  20 +-
 frontend/package-lock.json                    |   2 +-
 frontend/package.json                         |   1 +
 frontend/test-utils/LoginForm.test.tsx        |  24 +-
 .../test-utils/admin-users-mutations.test.tsx |  94 ++++
 frontend/test-utils/api-client.test.ts        | 307 ++++++++++--
 .../test-utils/language-switcher.test.tsx     |  18 +-
 frontend/test-utils/mocks/handlers.ts         | 118 ++++-
 .../test-utils/notification-bell.test.tsx     |  99 ++++
 47 files changed, 3296 insertions(+), 914 deletions(-)
 create mode 100644 frontend/components/SessionBootstrap.test.tsx
 create mode 100644 frontend/components/SessionBootstrap.tsx
 create mode 100644 frontend/lib/auth-session.test.ts
 create mode 100644 frontend/lib/disputes.test.ts
 create mode 100644 frontend/lib/disputes.ts
 create mode 100644 frontend/lib/document-mapper.test.ts
 create mode 100644 frontend/lib/document-mapper.ts
 create mode 100644 frontend/lib/document-sanitizer.test.ts
 create mode 100644 frontend/test-utils/admin-users-mutations.test.tsx
 create mode 100644 frontend/test-utils/notification-bell.test.tsx

diff --git a/backend/src/auth/auth.controller.ts b/backend/src/auth/auth.controller.ts
index dfa80d44..facd1a8e 100644
--- a/backend/src/auth/auth.controller.ts
+++ b/backend/src/auth/auth.controller.ts
@@ -13,6 +13,7 @@ import { AuthGuard } from '@nestjs/passport';
 import { Request, Response } from 'express';
 import { Profile as GoogleProfile } from 'passport-google-oauth20';
 import { Profile as GithubProfile } from 'passport-github2';
+import { User } from '../users/entities/user.entity';
 
 import { AuthService } from './auth.service';
 import { RegisterAuthDto } from './dto/register-auth.dto';
@@ -54,6 +55,13 @@ export class AuthController {
     return { message: 'Logged out successfully' };
   }
 
+  @Get('me')
+  @UseGuards(JwtAuthGuard)
+  getCurrentUser(@Req() req: Request & { user?: User }) {
+    const user = req.user!;
+    return { id: user.id, role: user.role };
+  }
+
   @Get('google')
   @UseGuards(AuthGuard('google'))
   googleAuth() {
diff --git a/backend/src/dispute/dispute.controller.ts b/backend/src/dispute/dispute.controller.ts
index f953ab27..0ebad0af 100644
--- a/backend/src/dispute/dispute.controller.ts
+++ b/backend/src/dispute/dispute.controller.ts
@@ -66,8 +66,12 @@ export class DisputeController {
     @Param('id') id: string,
     @Req() req: Request & { user?: User },
   ): Promise<DisputeResponseDto> {
-    const dispute = await this.disputeService.findOne(id);
     const user = req.user!;
+    const dispute = await this.disputeService.findOne(
+      id,
+      user.id,
+      user.role === 'admin',
+    );
 
     if (dispute.filedBy !== user.id && user.role !== 'admin') {
       throw new ForbiddenException('Access denied');
diff --git a/backend/src/dispute/dispute.service.ts b/backend/src/dispute/dispute.service.ts
index 1b38ada4..33719154 100644
--- a/backend/src/dispute/dispute.service.ts
+++ b/backend/src/dispute/dispute.service.ts
@@ -1,9 +1,9 @@
 import {
+  BadRequestException,
   Injectable,
   NotFoundException,
   UnauthorizedException,
 } from '@nestjs/common';
-import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 import { Dispute, DisputeStatus, ALLOWED_DISPUTE_TRANSITIONS } from './entities/dispute.entity';
@@ -94,12 +94,16 @@ export class DisputeService {
     };
   }
 
-  async findOne(id: string, userId: string): Promise<DisputeResponseDto> {
+  async findOne(
+    id: string,
+    userId?: string,
+    isAdmin = false,
+  ): Promise<DisputeResponseDto> {
     const dispute = await this.disputeRepo.findOne({ where: { id } });
     if (!dispute) {
       throw new NotFoundException(`Dispute ${id} not found`);
     }
-    if (dispute.filedBy !== userId) {
+    if (!isAdmin && userId && dispute.filedBy !== userId) {
       throw new UnauthorizedException('Unauthorized access');
     }
     return this.toResponseDto(dispute);
diff --git a/backend/src/documents/documents.controller.ts b/backend/src/documents/documents.controller.ts
index ee818019..22b2cc22 100644
--- a/backend/src/documents/documents.controller.ts
+++ b/backend/src/documents/documents.controller.ts
@@ -37,7 +37,12 @@ import { FileValidationPipe } from './pipes/file-validation.pipe';
 import { ListDocumentsDto } from './dto/list-documents.dto';
 import { DocumentResponseDto } from './dto/document-response.dto';
 
-const ALLOWED_MIME_TYPES = ['application/pdf', 'image/png', 'image/jpeg'];
+const ALLOWED_MIME_TYPES = [
+  'application/pdf',
+  'image/png',
+  'image/jpeg',
+  'image/svg+xml',
+];
 const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024;
 const DEFAULT_USER_QUOTA = 20;
 
@@ -49,7 +54,9 @@ const fileFilter: multer.Options['fileFilter'] = (_req, file, callback) => {
   }
 
   return callback(
-    new BadRequestException('Only PDF, PNG, or JPEG files are allowed'),
+    new BadRequestException(
+      'Only PDF, PNG, JPEG, or SVG files are allowed',
+    ),
   );
 };
 
diff --git a/backend/src/documents/pipes/file-validation.pipe.spec.ts b/backend/src/documents/pipes/file-validation.pipe.spec.ts
index d3a6fdce..5cf00850 100644
--- a/backend/src/documents/pipes/file-validation.pipe.spec.ts
+++ b/backend/src/documents/pipes/file-validation.pipe.spec.ts
@@ -44,6 +44,10 @@ async function createValidPng(): Promise<Buffer> {
     .toBuffer();
 }
 
+function createSvg(markup: string): Buffer {
+  return Buffer.from(markup, 'utf8');
+}
+
 describe('FileValidationPipe', () => {
   let pipe: FileValidationPipe;
 
@@ -90,6 +94,142 @@ describe('FileValidationPipe', () => {
     expect(result.mimetype).toBe('image/jpeg');
   });
 
+  it('should accept static SVG content and store a bounded PNG', async () => {
+    const buffer = createSvg(`
+      <svg xmlns="http://www.w3.org/2000/svg" width="120" height="40" viewBox="0 0 120 40">
+        <title>Parcel A &amp; B</title>
+        <defs>
+          <linearGradient id="paint">
+            <stop offset="0" stop-color="#fff" />
+          </linearGradient>
+        </defs>
+        <path id="shape" d="M0 0 L120 40" fill="url(#paint)" stroke="#123456" stroke-width="2" />
+        <text aria-label="https://maps.example/Parcel"><textPath href="#shape">Parcel A</textPath></text>
+      </svg>
+    `);
+    const file = createFile(buffer, 'image/svg+xml', 'survey.svg');
+
+    const result = await pipe.transform(file);
+
+    expect(result.mimetype).toBe('image/png');
+    expect(result.buffer.subarray(1, 4).toString('ascii')).toBe('PNG');
+    expect(result.size).toBe(result.buffer.length);
+  });
+
+  it.each<[string, RegExp]>([
+    ['<script>alert(1)</script>', /active or resource-bearing content/i],
+    ['<script />', /active or resource-bearing content/i],
+    ['<animate attributeName="href" values="javascript:alert(1)" />', /active or resource-bearing content/i],
+    ['<style>rect { fill: red }</style>', /active or resource-bearing content/i],
+    ['<foreignObject><div>html</div></foreignObject>', /active or resource-bearing content/i],
+    ['<image href="data:image/png;base64,AA==" />', /active or resource-bearing content/i],
+    ['<feImage href="https://attacker.example/pixel.png" />', /active or resource-bearing content/i],
+  ])('should reject active SVG element %s', async (element, expectedError) => {
+    const buffer = createSvg(
+      `<svg xmlns="http://www.w3.org/2000/svg">${element}</svg>`,
+    );
+    const file = createFile(buffer, 'image/svg+xml', 'active.svg');
+
+    await expect(pipe.transform(file)).rejects.toThrow(expectedError);
+  });
+
+  it.each([
+    '<rect width="1" height="1" onload="alert(1)" />',
+    '<rect width="1" height="1" style="fill:url(https://attacker.example/paint)" />',
+  ])('should reject active SVG attribute in %s', async (element) => {
+    const buffer = createSvg(
+      `<svg xmlns="http://www.w3.org/2000/svg">${element}</svg>`,
+    );
+    const file = createFile(buffer, 'image/svg+xml', 'active-attribute.svg');
+
+    await expect(pipe.transform(file)).rejects.toThrow(
+      /active or unsafe attributes/i,
+    );
+  });
+
+  it('should preserve inert descriptive attributes that contain URL-like text', async () => {
+    const buffer = createSvg(
+      '<svg xmlns="http://www.w3.org/2000/svg"><text aria-label="url(https://maps.example/reference)" data-reference="url(https://maps.example/data)">Parcel</text></svg>',
+    );
+
+    const result = await pipe.transform(
+      createFile(buffer, 'image/svg+xml', 'descriptive.svg'),
+    );
+
+    expect(result.mimetype).toBe('image/png');
+  });
+
+  it.each([
+    '<rect fill="url(/**/https://attacker.example/paint)" />',
+    '<rect fill="u\\72l(https://attacker.example/paint)" />',
+  ])('should reject obfuscated external CSS URLs in %s', async (element) => {
+    const buffer = createSvg(
+      `<svg xmlns="http://www.w3.org/2000/svg">${element}</svg>`,
+    );
+
+    await expect(
+      pipe.transform(
+        createFile(buffer, 'image/svg+xml', 'external-css.svg'),
+      ),
+    ).rejects.toThrow(/external or embedded resource/i);
+  });
+
+  it('should reject unsupported elements and oversized tags before rasterization', async () => {
+    const unsupported = createSvg(
+      '<svg xmlns="http://www.w3.org/2000/svg"><unknown /></svg>',
+    );
+    const oversized = createSvg(
+      `<svg xmlns="http://www.w3.org/2000/svg"><rect data-note="${'a'.repeat(64 * 1024)}" /></svg>`,
+    );
+
+    await expect(
+      pipe.transform(
+        createFile(unsupported, 'image/svg+xml', 'unknown.svg'),
+      ),
+    ).rejects.toThrow(/not supported/i);
+    await expect(
+      pipe.transform(
+        createFile(oversized, 'image/svg+xml', 'oversized.svg'),
+      ),
+    ).rejects.toThrow(BadRequestException);
+  });
+
+  it('should reject external SVG references', async () => {
+    const buffer = createSvg(
+      '<svg xmlns="http://www.w3.org/2000/svg">' +
+        '<text><textPath href="https://attacker.example/path">Parcel</textPath></text>' +
+        '</svg>',
+    );
+    const file = createFile(buffer, 'image/svg+xml', 'external.svg');
+
+    await expect(pipe.transform(file)).rejects.toThrow(
+      /resource-bearing|external|embedded resource/i,
+    );
+  });
+
+  it('should reject data URLs in SVG attributes', async () => {
+    const buffer = createSvg(
+      '<svg xmlns="http://www.w3.org/2000/svg">' +
+        '<text><textPath href="data:image/png;base64,AA==">Parcel</textPath></text>' +
+        '</svg>',
+    );
+    const file = createFile(buffer, 'image/svg+xml', 'data.svg');
+
+    await expect(pipe.transform(file)).rejects.toThrow(
+      /resource-bearing|external|embedded resource/i,
+    );
+  });
+
+  it('should reject SVG entities and external resources', async () => {
+    const buffer = createSvg(`
+      <!DOCTYPE svg [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+      <svg xmlns="http://www.w3.org/2000/svg"><text>&xxe;</text></svg>
+    `);
+    const file = createFile(buffer, 'image/svg+xml', 'entity.svg');
+
+    await expect(pipe.transform(file)).rejects.toThrow(/unsafe XML content/i);
+  });
+
   it('should reject an executable renamed to .pdf', async () => {
     const buffer = Buffer.from('MZ\x90\x00');
     const file = createFile(buffer, 'application/pdf', 'malware.pdf');
diff --git a/backend/src/documents/pipes/file-validation.pipe.ts b/backend/src/documents/pipes/file-validation.pipe.ts
index b27ded6a..c3d4fdf6 100644
--- a/backend/src/documents/pipes/file-validation.pipe.ts
+++ b/backend/src/documents/pipes/file-validation.pipe.ts
@@ -6,8 +6,142 @@ import {
 import { PDFDocument, PDFName } from 'pdf-lib';
 const sharp = require('sharp') as (...args: any[]) => any;
 
-const ALLOWED_MIME_TYPES = ['application/pdf', 'image/png', 'image/jpeg'];
+const ALLOWED_MIME_TYPES = [
+  'application/pdf',
+  'image/png',
+  'image/jpeg',
+  'image/svg+xml',
+];
 const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024;
+const MAX_SVG_RASTER_DIMENSION = 4096;
+const MAX_SVG_ELEMENTS = 50_000;
+const MAX_SVG_DEPTH = 128;
+const MAX_SVG_TAG_LENGTH = 64 * 1024;
+const MAX_SVG_ATTRIBUTES_PER_ELEMENT = 256;
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+const XLINK_NAMESPACE = 'http://www.w3.org/1999/xlink';
+
+const DISALLOWED_SVG_ELEMENTS = new Set([
+  'script',
+  'foreignobject',
+  'style',
+  'animate',
+  'animatemotion',
+  'animatetransform',
+  'set',
+  'discard',
+  'handler',
+  'listener',
+  'iframe',
+  'object',
+  'embed',
+  'audio',
+  'video',
+  'link',
+  'meta',
+  'a',
+  'image',
+  'feimage',
+  'font-face-uri',
+  'color-profile',
+  'mpath',
+  'use',
+]);
+
+const ALLOWED_SVG_ELEMENTS = new Set([
+  'svg',
+  'g',
+  'defs',
+  'title',
+  'desc',
+  'path',
+  'rect',
+  'circle',
+  'ellipse',
+  'line',
+  'polyline',
+  'polygon',
+  'text',
+  'tspan',
+  'textpath',
+  'lineargradient',
+  'radialgradient',
+  'stop',
+  'clippath',
+  'pattern',
+  'marker',
+  'symbol',
+  'view',
+  'mask',
+  'filter',
+  'fegaussianblur',
+  'feoffset',
+  'feblend',
+  'fecolormatrix',
+  'fecomponenttransfer',
+  'fecomposite',
+  'fediffuselighting',
+  'feconvolvematrix',
+  'fedisplacementmap',
+  'fedropshadow',
+  'feflood',
+  'fefunca',
+  'fefuncb',
+  'fefuncg',
+  'fefuncr',
+  'femerge',
+  'femergenode',
+  'femorphology',
+  'fepointlight',
+  'fespecularlighting',
+  'fespotlight',
+  'fetile',
+  'feturbulence',
+  'switch',
+  'font',
+  'font-face',
+  'font-face-format',
+  'font-face-name',
+  'glyph',
+  'missing-glyph',
+  'hkern',
+  'vkern',
+  'tref',
+  'cursor',
+]);
+
+const URL_ATTRIBUTES = new Set([
+  'href',
+  'xlink:href',
+  'src',
+  'srcset',
+  'action',
+  'formaction',
+  'poster',
+  'background',
+  'codebase',
+  'cite',
+  'icon',
+  'manifest',
+  'profile',
+  'usemap',
+  'ping',
+  'longdesc',
+]);
+
+const CSS_URL_ATTRIBUTES = new Set([
+  'background-image',
+  'clip-path',
+  'color-profile',
+  'cursor',
+  'fill',
+  'filter',
+  'marker-end',
+  'marker-mid',
+  'marker-start',
+  'mask',
+  'stroke',
+]);
 
 interface DetectedType {
   mime: string;
@@ -81,6 +215,11 @@ export class FileValidationPipe implements PipeTransform<
       );
     }
 
+    if (detectedType.mime === 'image/svg+xml') {
+      await this.sanitizeSvg(file);
+      return file;
+    }
+
     if (detectedType.mime === 'application/pdf') {
       await this.validatePdf(file.buffer);
     }
@@ -119,6 +258,11 @@ export class FileValidationPipe implements PipeTransform<
       return { mime: 'image/jpeg', ext: 'jpg' };
     }
 
+    const svg = this.decodeSvg(buffer);
+    if (svg && this.looksLikeSvg(svg)) {
+      return { mime: 'image/svg+xml', ext: 'svg' };
+    }
+
     if (buffer[0] === 0x50 && buffer[1] === 0x4b) {
       return { mime: 'application/zip', ext: 'zip' };
     }
@@ -155,6 +299,268 @@ export class FileValidationPipe implements PipeTransform<
     return undefined;
   }
 
+  private decodeSvg(buffer: Buffer): string | null {
+    try {
+      return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+    } catch {
+      return null;
+    }
+  }
+
+  private stripXmlDeclaration(source: string): string {
+    return source.replace(
+      /^\uFEFF?\s*<\?xml\s+version\s*=\s*(['"])1\.0\1(?:\s+encoding\s*=\s*(['"])UTF-8\2)?(?:\s+standalone\s*=\s*(['"])(?:yes|no)\3)?\s*\?>\s*/i,
+      '',
+    );
+  }
+
+  private hasSvgRoot(source: string): boolean {
+    return /^<svg(?:\s|>)/i.test(this.stripXmlDeclaration(source));
+  }
+
+  private looksLikeSvg(source: string): boolean {
+    return this.hasSvgRoot(source) || /<svg(?:\s|>)/i.test(source);
+  }
+
+  private assertSafeSvg(source: string): void {
+    const body = this.stripXmlDeclaration(source);
+    if (
+      /<!--|<!\[CDATA\[|<\?|<!DOCTYPE|<!ENTITY/i.test(body) ||
+      /&(?!(?:amp|lt|gt|quot|apos);)/.test(body)
+    ) {
+      throw new BadRequestException('SVG contains unsafe XML content');
+    }
+    if (!/^<svg(?:\s|>)/i.test(body)) {
+      throw new BadRequestException('Invalid SVG document');
+    }
+
+    const stack: string[] = [];
+    let elementCount = 0;
+    let rootClosed = false;
+    let index = 0;
+
+    while (index < body.length) {
+      if (body[index] !== '<') {
+        index += 1;
+        continue;
+      }
+
+      if (rootClosed) {
+        if (/\S/.test(body.slice(index))) {
+          throw new BadRequestException('Invalid SVG document');
+        }
+        break;
+      }
+
+      const tagEnd = this.findSvgTagEnd(body, index + 1);
+      if (tagEnd === -1) {
+        throw new BadRequestException('Invalid SVG document');
+      }
+
+      const rawTag = body.slice(index + 1, tagEnd);
+      if (!rawTag || rawTag.startsWith('!') || rawTag.startsWith('?')) {
+        throw new BadRequestException('SVG contains unsafe XML content');
+      }
+
+      if (rawTag.startsWith('/')) {
+        const closingMatch = /^\/\s*([A-Za-z_][A-Za-z0-9_.-]*)\s*$/.exec(
+          rawTag,
+        );
+        if (!closingMatch) {
+          throw new BadRequestException('Invalid SVG document');
+        }
+
+        const name = closingMatch[1].toLowerCase();
+        if (stack.pop() !== name) {
+          throw new BadRequestException('Invalid SVG document');
+        }
+        if (stack.length === 0) rootClosed = true;
+      } else {
+        const openingMatch = /^([A-Za-z_][A-Za-z0-9_.-]*)([\s\S]*)$/.exec(
+          rawTag,
+        );
+        if (!openingMatch || openingMatch[1].includes(':')) {
+          throw new BadRequestException('Invalid SVG document');
+        }
+
+        const name = openingMatch[1].toLowerCase();
+        const attributes = openingMatch[2].replace(/\/\s*$/, '');
+        const selfClosing = /\/\s*$/.test(openingMatch[2]);
+
+        elementCount += 1;
+        if (elementCount > MAX_SVG_ELEMENTS || stack.length >= MAX_SVG_DEPTH) {
+          throw new BadRequestException('SVG exceeds structural limits');
+        }
+        if (DISALLOWED_SVG_ELEMENTS.has(name)) {
+          throw new BadRequestException(
+            'SVG contains active or resource-bearing content that is not allowed',
+          );
+        }
+        if (!ALLOWED_SVG_ELEMENTS.has(name)) {
+          throw new BadRequestException(
+            `SVG element ${name} is not supported`,
+          );
+        }
+
+        if (stack.length === 0) {
+          if (name !== 'svg' || /\S/.test(body.slice(0, index))) {
+            throw new BadRequestException('Invalid SVG document');
+          }
+          if (selfClosing) rootClosed = true;
+        } else if (name === 'svg') {
+          throw new BadRequestException('Invalid SVG document');
+        }
+
+        this.validateSvgAttributes(attributes);
+        if (!selfClosing) stack.push(name);
+      }
+
+      index = tagEnd + 1;
+    }
+
+    if (stack.length !== 0 || !rootClosed) {
+      throw new BadRequestException('Invalid SVG document');
+    }
+  }
+
+  private findSvgTagEnd(source: string, start: number): number {
+    let quote: "'" | '"' | null = null;
+
+    for (let index = start; index < source.length; index += 1) {
+      if (index - start > MAX_SVG_TAG_LENGTH) return -1;
+
+      const character = source[index];
+      if (quote) {
+        if (character === quote) quote = null;
+      } else if (character === "'" || character === '"') {
+        quote = character;
+      } else if (character === '>') {
+        return index;
+      } else if (character === '<') {
+        return -1;
+      }
+    }
+
+    return -1;
+  }
+
+  private validateSvgAttributes(input: string): void {
+    let remaining = input.trim();
+    const names = new Set<string>();
+
+    while (remaining) {
+      const match =
+        /^([A-Za-z_][A-Za-z0-9_.:-]*)\s*=\s*(["'])([\s\S]*?)\2(?=\s|$)/.exec(
+          remaining,
+        );
+      if (!match) {
+        throw new BadRequestException('Invalid SVG attributes');
+      }
+
+      const name = match[1].toLowerCase();
+      const value = match[3];
+      if (
+        names.has(name) ||
+        names.size >= MAX_SVG_ATTRIBUTES_PER_ELEMENT
+      ) {
+        throw new BadRequestException('Invalid SVG attributes');
+      }
+      names.add(name);
+
+      if (name === 'xmlns' || name.startsWith('xmlns:')) {
+        if (value !== SVG_NAMESPACE && value !== XLINK_NAMESPACE) {
+          throw new BadRequestException('SVG contains an external reference');
+        }
+        remaining = remaining.slice(match[0].length).trim();
+        continue;
+      }
+
+      if (
+        name.includes(':') &&
+        name !== 'xlink:href' &&
+        name !== 'xml:space' &&
+        name !== 'xml:lang'
+      ) {
+        throw new BadRequestException('SVG contains an external reference');
+      }
+
+      if (
+        name.startsWith('on') ||
+        name === 'style' ||
+        name === 'xml:base' ||
+        value.includes('<') ||
+        /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value)
+      ) {
+        throw new BadRequestException(
+          'SVG contains active or unsafe attributes',
+        );
+      }
+
+      if (
+        URL_ATTRIBUTES.has(name) &&
+        !/^#[A-Za-z0-9_.:-]+$/.test(value)
+      ) {
+        throw new BadRequestException(
+          'SVG contains an external or embedded resource',
+        );
+      }
+
+      if (CSS_URL_ATTRIBUTES.has(name)) {
+        const normalizedCssValue = value.replace(/\/\*[\s\S]*?\*\//g, '');
+        if (
+          (normalizedCssValue.includes('\\') ||
+            /\b(?:url|var|attr)\s*\(/i.test(normalizedCssValue)) &&
+          !/^url\(\s*#[A-Za-z0-9_.:-]+\s*\)$/i.test(
+            normalizedCssValue.trim(),
+          )
+        ) {
+          throw new BadRequestException(
+            'SVG contains an external or embedded resource',
+          );
+        }
+      }
+
+      remaining = remaining.slice(match[0].length).trim();
+    }
+  }
+
+  private async sanitizeSvg(file: Express.Multer.File): Promise<void> {
+    const source = this.decodeSvg(file.buffer);
+    if (!source) {
+      throw new BadRequestException('Invalid or malformed SVG file');
+    }
+
+    this.assertSafeSvg(source);
+
+    try {
+      const sanitized = await sharp(file.buffer, {
+        limitInputPixels: 40_000_000,
+        timeout: 5_000,
+      })
+        .resize({
+          width: MAX_SVG_RASTER_DIMENSION,
+          height: MAX_SVG_RASTER_DIMENSION,
+          fit: 'inside',
+          withoutEnlargement: true,
+        })
+        .png()
+        .toBuffer();
+
+      if (sanitized.length > MAX_FILE_SIZE_BYTES) {
+        throw new BadRequestException(
+          `File exceeds maximum size of ${MAX_FILE_SIZE_BYTES} bytes`,
+        );
+      }
+
+      file.buffer = sanitized;
+      file.size = sanitized.length;
+      file.mimetype = 'image/png';
+    } catch (error) {
+      if (error instanceof BadRequestException) throw error;
+      throw new BadRequestException('Invalid or unsafe SVG file');
+    }
+  }
+
   private validateSize(file: Express.Multer.File): void {
     if (file.size > MAX_FILE_SIZE_BYTES) {
       throw new BadRequestException(
@@ -216,7 +622,12 @@ export class FileValidationPipe implements PipeTransform<
 
   private async stripImageMetadata(buffer: Buffer): Promise<Buffer> {
     try {
-      return await sharp(buffer).withMetadata({}).toBuffer();
+      return await sharp(buffer, {
+        limitInputPixels: 40_000_000,
+        timeout: 5_000,
+      })
+        .withMetadata({})
+        .toBuffer();
     } catch {
       throw new BadRequestException('Failed to process image metadata');
     }
diff --git a/backend/src/documents/pipes/mime-type-validation.pipe.ts b/backend/src/documents/pipes/mime-type-validation.pipe.ts
index 594a7819..f2e5cd84 100644
--- a/backend/src/documents/pipes/mime-type-validation.pipe.ts
+++ b/backend/src/documents/pipes/mime-type-validation.pipe.ts
@@ -10,6 +10,7 @@ export class MimeTypeValidationPipe implements PipeTransform {
     'application/pdf',
     'image/png',
     'image/jpeg',
+    'image/svg+xml',
   ];
 
   transform(file: { mimetype: string }) {
diff --git a/frontend/__tests__/abdulrcrtw.test.ts b/frontend/__tests__/abdulrcrtw.test.ts
index e15c6312..6959e4dd 100644
--- a/frontend/__tests__/abdulrcrtw.test.ts
+++ b/frontend/__tests__/abdulrcrtw.test.ts
@@ -1,5 +1,5 @@
 import { sanitizeText, isSafeUrl } from '../lib/sanitize';
-import { toPublicDocumentView } from '../lib/document-sanitizer';
+import { toPublicDocumentView } from '../lib/document-mapper';
 
 describe('abdulrcrtw Frontend Features (FE-95, FE-94, FE-93, FE-92)', () => {
   it('sanitizeText escapes HTML characters', () => {
diff --git a/frontend/app/[locale]/(protected)/admin/providers/page.tsx b/frontend/app/[locale]/(protected)/admin/providers/page.tsx
index 5cad2961..42fe56d4 100644
--- a/frontend/app/[locale]/(protected)/admin/providers/page.tsx
+++ b/frontend/app/[locale]/(protected)/admin/providers/page.tsx
@@ -1,7 +1,12 @@
 "use client";
 
 import React, { useCallback, useEffect, useRef, useState } from "react";
-import { useRouter } from "next/navigation";
+import { ApiError, getApiUrl, request } from "@/lib/api-client";
+import {
+  clearSession,
+  getJwtClaims,
+  getValidAccessToken,
+} from "@/lib/auth-session";
 import {
   AlertTriangle,
   Building2,
@@ -41,17 +46,6 @@ const REFRESH_INTERVAL_SECONDS = 60;
 // Helpers
 // ---------------------------------------------------------------------------
 
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
-
-function getAuthHeaders(): HeadersInit {
-  const token =
-    typeof window !== "undefined" ? localStorage.getItem("auth-token") : null;
-  return {
-    "Content-Type": "application/json",
-    ...(token ? { Authorization: `Bearer ${token}` } : {}),
-  };
-}
-
 function parseStatus(raw: unknown): ProviderStatus {
   if (typeof raw === "boolean") return raw ? "online" : "offline";
   if (typeof raw === "string") {
@@ -252,8 +246,6 @@ function ProviderCardSkeleton() {
 // ---------------------------------------------------------------------------
 
 export default function AdminProvidersPage() {
-  const router = useRouter();
-
   const [statsMap, setStatsMap] = useState<StatsMap>({});
   const [initialLoading, setInitialLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -264,36 +256,30 @@ export default function AdminProvidersPage() {
   // ── Admin access check ──────────────────────────────────────────────────
 
   useEffect(() => {
-    const token = localStorage.getItem("auth-token");
+    const token = getValidAccessToken();
     if (!token) {
-      router.replace("/login");
+      clearSession();
+      window.location.assign("/login");
       return;
     }
-    try {
-      const payload = JSON.parse(atob(token.split(".")[1]));
-      if (payload?.role !== "admin") {
-        router.replace("/dashboard");
-      }
-    } catch {
-      router.replace("/login");
+
+    const claims = getJwtClaims(token);
+    if (!claims) {
+      clearSession();
+      window.location.assign("/login");
+      return;
     }
-  }, [router]);
+    if (claims.role !== "admin") window.location.assign("/");
+  }, []);
 
   // ── Fetch stats ──────────────────────────────────────────────────────────
 
   const fetchStats = useCallback(async () => {
     setError(null);
     try {
-      const res = await fetch(`${API_BASE}/api/external-validation/stats`, {
-        headers: getAuthHeaders(),
-      });
-      if (res.status === 403) {
-        router.replace("/dashboard");
-        return;
-      }
-      if (!res.ok) throw new Error(`Failed to load provider stats: ${res.status}`);
-
-      const json: unknown = await res.json();
+      const json = await request<unknown>(
+        getApiUrl("external-validation/stats"),
+      );
       const entries = Array.isArray(json) ? json : [];
 
       setStatsMap((prev) => {
@@ -308,11 +294,15 @@ export default function AdminProvidersPage() {
         return next;
       });
     } catch (err: unknown) {
+      if (err instanceof ApiError && err.status === 403) {
+        window.location.assign("/");
+        return;
+      }
       setError(err instanceof Error ? err.message : "Failed to load provider stats");
     } finally {
       setInitialLoading(false);
     }
-  }, [router]);
+  }, []);
 
   // ── Auto-refresh every 60s, with visible countdown ─────────────────────
 
@@ -342,12 +332,9 @@ export default function AdminProvidersPage() {
     setCheckErrors((prev) => ({ ...prev, [id]: null }));
 
     try {
-      const res = await fetch(`${API_BASE}/api/external-validation/health`, {
-        headers: getAuthHeaders(),
-      });
-      if (!res.ok) throw new Error(`Health check failed: ${res.status}`);
-
-      const json: unknown = await res.json();
+      const json = await request<unknown>(
+        getApiUrl("external-validation/health"),
+      );
       const checkedAt = new Date().toISOString();
 
       setStatsMap((prev) => {
diff --git a/frontend/app/[locale]/(protected)/admin/users/page.tsx b/frontend/app/[locale]/(protected)/admin/users/page.tsx
index faf72619..9b26efaf 100644
--- a/frontend/app/[locale]/(protected)/admin/users/page.tsx
+++ b/frontend/app/[locale]/(protected)/admin/users/page.tsx
@@ -1,7 +1,17 @@
 "use client";
 
 import React, { useCallback, useEffect, useRef, useState } from "react";
-import { useRouter } from "next/navigation";
+import {
+  ApiError,
+  getApiUrl,
+  request,
+  requestRaw,
+} from "@/lib/api-client";
+import {
+  clearSession,
+  getJwtClaims,
+  getValidAccessToken,
+} from "@/lib/auth-session";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -31,27 +41,9 @@ interface PaginatedUsers {
 // Helpers
 // ---------------------------------------------------------------------------
 
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
-
-function getAuthHeaders(): HeadersInit {
-  const token =
-    typeof window !== "undefined" ? localStorage.getItem("auth-token") : null;
-  return {
-    "Content-Type": "application/json",
-    ...(token ? { Authorization: `Bearer ${token}` } : {}),
-  };
-}
-
 function getCurrentUserId(): string | null {
-  if (typeof window === "undefined") return null;
-  try {
-    const token = localStorage.getItem("auth-token");
-    if (!token) return null;
-    const payload = JSON.parse(atob(token.split(".")[1]));
-    return payload?.sub ?? null;
-  } catch {
-    return null;
-  }
+  const token = getValidAccessToken();
+  return token ? getJwtClaims(token)?.sub ?? null : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -121,8 +113,6 @@ function DeleteModal({ user, onConfirm, onCancel, isLoading, error }: DeleteModa
 const PAGE_SIZE = 20;
 
 export default function AdminUsersPage() {
-  const router = useRouter();
-
   const [users, setUsers] = useState<AdminUser[]>([]);
   const [total, setTotal] = useState(0);
   const [page, setPage] = useState(1);
@@ -152,15 +142,21 @@ export default function AdminUsersPage() {
   // ── Check admin access ──────────────────────────────────────────────────
 
   useEffect(() => {
-    const token = localStorage.getItem("auth-token");
-    if (!token) { router.replace("/login"); return; }
-    try {
-      const payload = JSON.parse(atob(token.split(".")[1]));
-      if (payload?.role !== "admin") { router.replace("/dashboard"); }
-    } catch {
-      router.replace("/login");
+    const token = getValidAccessToken();
+    if (!token) {
+      clearSession();
+      window.location.assign("/login");
+      return;
+    }
+
+    const claims = getJwtClaims(token);
+    if (!claims) {
+      clearSession();
+      window.location.assign("/login");
+      return;
     }
-  }, [router]);
+    if (claims.role !== "admin") window.location.assign("/");
+  }, []);
 
   // ── Fetch users ─────────────────────────────────────────────────────────
 
@@ -176,21 +172,22 @@ export default function AdminUsersPage() {
     if (appliedSearch) params.set("search", appliedSearch);
 
     try {
-      const res = await fetch(`${API_BASE}/api/users?${params}`, {
-        headers: getAuthHeaders(),
-      });
-      if (res.status === 403) { router.replace("/dashboard"); return; }
-      if (!res.ok) throw new Error(`Failed to load users: ${res.status}`);
-      const json: PaginatedUsers = await res.json();
+      const json = await request<PaginatedUsers>(
+        getApiUrl(`users?${params}`),
+      );
       setUsers(json.data);
       setTotal(json.total);
       setSelected(new Set());
     } catch (err: unknown) {
+      if (err instanceof ApiError && err.status === 403) {
+        window.location.assign("/");
+        return;
+      }
       setError(err instanceof Error ? err.message : "Failed to load users");
     } finally {
       setLoading(false);
     }
-  }, [page, roleFilter, statusFilter, appliedSearch, router]);
+  }, [page, roleFilter, statusFilter, appliedSearch]);
 
   useEffect(() => { fetchUsers(); }, [fetchUsers]);
 
@@ -202,12 +199,10 @@ export default function AdminUsersPage() {
     }
     setActionLoading((prev) => ({ ...prev, [`role_${user.id}`]: true }));
     try {
-      const res = await fetch(`${API_BASE}/api/users/${user.id}`, {
+      await requestRaw(getApiUrl(`users/${user.id}`), {
         method: "PATCH",
-        headers: getAuthHeaders(),
-        body: JSON.stringify({ role: newRole }),
+        body: { role: newRole },
       });
-      if (!res.ok) throw new Error("Role update failed");
       setUsers((prev) => prev.map((u) => u.id === user.id ? { ...u, role: newRole } : u));
     } catch {
       // show inline error or toast — kept simple here
@@ -222,12 +217,10 @@ export default function AdminUsersPage() {
     const newStatus: UserStatus = user.status === "active" ? "suspended" : "active";
     setActionLoading((prev) => ({ ...prev, [`status_${user.id}`]: true }));
     try {
-      const res = await fetch(`${API_BASE}/api/users/${user.id}`, {
+      await requestRaw(getApiUrl(`users/${user.id}`), {
         method: "PATCH",
-        headers: getAuthHeaders(),
-        body: JSON.stringify({ status: newStatus }),
+        body: { status: newStatus },
       });
-      if (!res.ok) throw new Error("Status update failed");
       setUsers((prev) => prev.map((u) => u.id === user.id ? { ...u, status: newStatus } : u));
     } catch {
       // silent — real app would toast
@@ -243,11 +236,9 @@ export default function AdminUsersPage() {
     setDeleteLoading(true);
     setDeleteError(null);
     try {
-      const res = await fetch(`${API_BASE}/api/users/${deleteTarget.id}`, {
+      await requestRaw(getApiUrl(`users/${deleteTarget.id}`), {
         method: "DELETE",
-        headers: getAuthHeaders(),
       });
-      if (!res.ok) throw new Error("Delete failed");
       setUsers((prev) => prev.filter((u) => u.id !== deleteTarget.id));
       setDeleteTarget(null);
     } catch (err: unknown) {
@@ -265,14 +256,13 @@ export default function AdminUsersPage() {
     try {
       await Promise.all(
         Array.from(selected).map((id) =>
-          fetch(`${API_BASE}/api/users/${id}`, {
-            method: "DELETE",
-            headers: getAuthHeaders(),
-          })
-        )
+          requestRaw(getApiUrl(`users/${id}`), { method: "DELETE" }),
+        ),
       );
       setUsers((prev) => prev.filter((u) => !selected.has(u.id)));
       setSelected(new Set());
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : "Bulk delete failed");
     } finally {
       setBulkDeleting(false);
     }
diff --git a/frontend/app/[locale]/(protected)/disputes/[id]/page.tsx b/frontend/app/[locale]/(protected)/disputes/[id]/page.tsx
index e0c26bd8..9b31bbe5 100644
--- a/frontend/app/[locale]/(protected)/disputes/[id]/page.tsx
+++ b/frontend/app/[locale]/(protected)/disputes/[id]/page.tsx
@@ -1,77 +1,52 @@
 "use client";
 
-import React, { useEffect, useState, useCallback } from "react";
-import Link from "next/link";
+import React, { useCallback, useEffect, useState } from "react";
+import { Link } from "@/i18n/navigation";
 import { useParams } from "next/navigation";
 import { request } from "@/lib/api-client";
+import {
+  disputeStatusLabel,
+  disputeStatuses,
+  normalizeAuthUser,
+  normalizeDispute,
+  type AuthUser,
+  type Dispute,
+  type DisputeStatus,
+} from "@/lib/disputes";
 import { useToast } from "@/components/ui/use-toast";
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type DisputeStatus = "OPEN" | "UNDER_REVIEW" | "RESOLVED" | "REJECTED";
-
-interface Dispute {
-  id: string;
-  documentId: string;
-  description: string;
-  reason: string | null;
-  status: DisputeStatus;
-  filedBy: string;
-  createdAt: string;
-  timeline: { status: DisputeStatus; createdAt: string }[];
-  resolution?: string | null;
-  resolvedAt?: string | null;
-  document: {
-    title: string;
-    status: string;
-    riskScore: number;
-  };
-}
-
-interface User {
-  id: string;
-  role: "USER" | "ADMIN";
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 const STATUS_CLASSES: Record<DisputeStatus, string> = {
-  OPEN: "bg-blue-100 text-blue-800",
-  UNDER_REVIEW: "bg-yellow-100 text-yellow-800",
-  RESOLVED: "bg-green-100 text-green-800",
-  REJECTED: "bg-red-100 text-red-800",
+  open: "bg-blue-100 text-blue-800",
+  in_review: "bg-yellow-100 text-yellow-800",
+  resolved: "bg-green-100 text-green-800",
+  dismissed: "bg-red-100 text-red-800",
 };
 
-// ---------------------------------------------------------------------------
-// Page
-// ---------------------------------------------------------------------------
-
 export default function DisputeDetailPage() {
   const params = useParams<{ id: string }>();
   const disputeId = params.id;
   const { toast } = useToast();
 
   const [dispute, setDispute] = useState<Dispute | null>(null);
-  const [user, setUser] = useState<User | null>(null); // Assume we get user info from an auth hook
+  const [user, setUser] = useState<AuthUser | null>(null);
   const [loading, setLoading] = useState(true);
+  const [updating, setUpdating] = useState(false);
   const [error, setError] = useState<string | null>(null);
-  const [adminStatus, setAdminStatus] = useState<DisputeStatus>("OPEN");
-  const [adminResolution, setAdminResolution] = useState("");
+  const [adminStatus, setAdminStatus] = useState<DisputeStatus>("open");
 
   const fetchDispute = useCallback(async () => {
     if (!disputeId) return;
     setLoading(true);
+    setError(null);
     try {
-      const disputeData = await request<Dispute>(`/api/disputes/${disputeId}`);
-      setDispute(disputeData);
-      setAdminStatus(disputeData.status);
-      // In a real app, user data would come from a context or hook
-      const userData = await request<User>("/api/users/me");
-      setUser(userData);
+      const [disputeResponse, userResponse] = await Promise.all([
+        request<unknown>(`disputes/${disputeId}`),
+        request<unknown>("auth/me"),
+      ]);
+      const normalizedDispute = normalizeDispute(disputeResponse);
+      setDispute(normalizedDispute);
+      setAdminStatus(normalizedDispute.status);
+      setUser(normalizeAuthUser(userResponse));
     } catch (err) {
       setError(err instanceof Error ? err.message : "Failed to load dispute.");
     } finally {
@@ -80,45 +55,36 @@ export default function DisputeDetailPage() {
   }, [disputeId]);
 
   useEffect(() => {
-    fetchDispute();
+    void fetchDispute();
   }, [fetchDispute]);
 
-  const handleWithdrawDispute = async () => {
-    if (!disputeId) return;
-    try {
-      await request(`/api/disputes/${disputeId}`, { method: "DELETE" });
-      toast({
-        title: "Dispute Withdrawn",
-        description: "The dispute has been successfully withdrawn.",
-      });
-      // Redirect or update UI
-    } catch (err) {
-      toast({
-        title: "Error",
-        description: "Failed to withdraw the dispute.",
-        variant: "destructive",
-      });
-    }
-  };
-
   const handleAdminUpdate = async () => {
-    if (!disputeId) return;
+    if (!disputeId || user?.role !== "admin") return;
+    setUpdating(true);
     try {
-      await request(`/api/disputes/${disputeId}`, {
-        method: "PATCH",
-        body: { status: adminStatus, resolution: adminResolution },
-      });
+      const response = await request<unknown>(
+        `disputes/${disputeId}/status`,
+        {
+          method: "PATCH",
+          body: { status: adminStatus },
+        },
+      );
+      const updatedDispute = normalizeDispute(response);
+      setDispute(updatedDispute);
+      setAdminStatus(updatedDispute.status);
       toast({
         title: "Dispute Updated",
-        description: "The dispute has been successfully updated.",
+        description: "The dispute status has been successfully updated.",
       });
-      fetchDispute(); // Refetch to show updated data
     } catch (err) {
       toast({
         title: "Error",
-        description: "Failed to update the dispute.",
+        description:
+          err instanceof Error ? err.message : "Failed to update dispute status.",
         variant: "destructive",
       });
+    } finally {
+      setUpdating(false);
     }
   };
 
@@ -134,7 +100,9 @@ export default function DisputeDetailPage() {
   if (!dispute) {
     return (
       <main className="mx-auto max-w-2xl px-4 py-8">
-        <p className="text-sm text-red-600">{error ?? "Dispute not found."}</p>
+        <p className="text-sm text-red-600">
+          {error ?? "Dispute not found."}
+        </p>
         <Link
           href="/disputes"
           className="mt-3 block text-sm text-blue-600 underline"
@@ -145,6 +113,12 @@ export default function DisputeDetailPage() {
     );
   }
 
+  const documentStatus = dispute.document?.status;
+  const documentRiskScore = dispute.document?.riskScore;
+  const timeline = dispute.timeline;
+  const resolution = dispute.resolution;
+  const resolvedAt = dispute.resolvedAt;
+
   return (
     <main className="mx-auto max-w-2xl px-4 py-8">
       <Link
@@ -159,11 +133,11 @@ export default function DisputeDetailPage() {
           Dispute #{dispute.id.substring(0, 8)}
         </h1>
         <span
-          className={`inline-block rounded-full px-3 py-1 text-sm font-semibold ${
+          className={`inline-block rounded-full px-3 py-1 text-sm font-semibold capitalize ${
             STATUS_CLASSES[dispute.status]
           }`}
         >
-          {dispute.status.replace("_", " ")}
+          {disputeStatusLabel(dispute.status)}
         </span>
       </div>
       <p className="text-sm text-gray-500">
@@ -180,13 +154,17 @@ export default function DisputeDetailPage() {
               href={`/documents/${dispute.documentId}`}
               className="text-blue-600 hover:underline"
             >
-              {dispute.document.title}
+              {dispute.document?.title ?? `Document ${dispute.documentId}`}
             </Link>
           </p>
-          <div className="mt-2 flex space-x-4 text-xs">
-            <span>Status: {dispute.document.status}</span>
-            <span>Risk Score: {dispute.document.riskScore}%</span>
-          </div>
+          {(documentStatus || typeof documentRiskScore === "number") && (
+            <div className="mt-2 flex space-x-4 text-xs">
+              {documentStatus && <span>Status: {documentStatus}</span>}
+              {typeof documentRiskScore === "number" && (
+                <span>Risk Score: {documentRiskScore}%</span>
+              )}
+            </div>
+          )}
         </section>
 
         <section className="rounded-xl border border-gray-200 bg-white p-5 shadow-sm">
@@ -198,55 +176,62 @@ export default function DisputeDetailPage() {
           </p>
           {dispute.reason && (
             <p className="mt-2 text-xs text-gray-500">
-              Classified as: {dispute.reason}
+              Classified as: {dispute.reason.name}
             </p>
           )}
         </section>
 
-        <section className="rounded-xl border border-gray-200 bg-white p-5 shadow-sm">
-          <h2 className="text-sm font-semibold text-gray-900">
-            Status Timeline
-          </h2>
-          <ol className="mt-4 space-y-4">
-            {dispute.timeline.map((event, index) => (
-              <li key={index} className="flex items-start gap-3">
-                <span
-                  aria-hidden="true"
-                  className={`mt-1 h-2.5 w-2.5 shrink-0 rounded-full ${
-                    index === dispute.timeline.length - 1
-                      ? "bg-green-500"
-                      : "bg-gray-300"
-                  }`}
-                />
-                <div>
-                  <p className="text-sm font-medium text-gray-900">
-                    {event.status.replace("_", " ")}
-                  </p>
-                  <p className="text-xs text-gray-500">
-                    {new Date(event.createdAt).toLocaleString()}
-                  </p>
-                </div>
-              </li>
-            ))}
-          </ol>
-        </section>
+        {timeline.length > 0 && (
+          <section className="rounded-xl border border-gray-200 bg-white p-5 shadow-sm">
+            <h2 className="text-sm font-semibold text-gray-900">
+              Status Timeline
+            </h2>
+            <ol className="mt-4 space-y-4">
+              {timeline.map((event, index) => (
+                <li
+                  key={`${event.status}-${event.createdAt}`}
+                  className="flex items-start gap-3"
+                >
+                  <span
+                    aria-hidden="true"
+                    className={`mt-1 h-2.5 w-2.5 shrink-0 rounded-full ${
+                      index === timeline.length - 1
+                        ? "bg-green-500"
+                        : "bg-gray-300"
+                    }`}
+                  />
+                  <div>
+                    <p className="text-sm font-medium capitalize text-gray-900">
+                      {disputeStatusLabel(event.status)}
+                    </p>
+                    <p className="text-xs text-gray-500">
+                      {new Date(event.createdAt).toLocaleString()}
+                    </p>
+                  </div>
+                </li>
+              ))}
+            </ol>
+          </section>
+        )}
 
-        {(dispute.status === "RESOLVED" || dispute.status === "REJECTED") &&
-          dispute.resolution && (
+        {(dispute.status === "resolved" || dispute.status === "dismissed") &&
+          resolution && (
             <section className="rounded-xl border border-gray-200 bg-white p-5 shadow-sm">
               <h2 className="text-sm font-semibold text-gray-900">
                 Resolution
               </h2>
               <p className="mt-2 whitespace-pre-line text-sm text-gray-700">
-                {dispute.resolution}
-              </p>
-              <p className="mt-2 text-xs text-gray-500">
-                Resolved on {new Date(dispute.resolvedAt!).toLocaleDateString()}
+                {resolution}
               </p>
+              {resolvedAt && (
+                <p className="mt-2 text-xs text-gray-500">
+                  Resolved on {new Date(resolvedAt).toLocaleDateString()}
+                </p>
+              )}
             </section>
           )}
 
-        {user?.role === "ADMIN" && (
+        {user?.role === "admin" && (
           <section className="rounded-xl border border-blue-200 bg-blue-50 p-5 shadow-sm">
             <h2 className="text-sm font-semibold text-blue-900">
               Admin Controls
@@ -262,52 +247,29 @@ export default function DisputeDetailPage() {
                 <select
                   id="admin-status"
                   value={adminStatus}
-                  onChange={(e) =>
-                    setAdminStatus(e.target.value as DisputeStatus)
+                  onChange={(event) =>
+                    setAdminStatus(event.target.value as DisputeStatus)
                   }
                   className="mt-1 block w-full rounded-md border-gray-300 shadow-sm"
                 >
-                  <option>OPEN</option>
-                  <option>UNDER_REVIEW</option>
-                  <option>RESOLVED</option>
-                  <option>REJECTED</option>
+                  {disputeStatuses.map((status) => (
+                    <option key={status} value={status}>
+                      {disputeStatusLabel(status)}
+                    </option>
+                  ))}
                 </select>
               </div>
-              <div>
-                <label
-                  htmlFor="admin-resolution"
-                  className="block text-sm font-medium text-gray-700"
-                >
-                  Resolution Notes
-                </label>
-                <textarea
-                  id="admin-resolution"
-                  rows={4}
-                  value={adminResolution}
-                  onChange={(e) => setAdminResolution(e.target.value)}
-                  className="mt-1 block w-full rounded-md border-gray-300 shadow-sm"
-                />
-              </div>
               <button
+                type="button"
                 onClick={handleAdminUpdate}
-                className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
+                disabled={updating || adminStatus === dispute.status}
+                className="rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:opacity-50"
               >
-                Save Changes
+                {updating ? "Saving..." : "Save Changes"}
               </button>
             </div>
           </section>
         )}
-
-        {dispute.status === "OPEN" && user?.id === dispute.filedBy && (
-          <div className="mt-6">
-            <button
-              onClick={handleWithdrawDispute}
-              className="text-sm text-red-600 hover:underline"
-            >
-              Withdraw Dispute
-            </button>
-          </div>
-        )}
       </div>
     </main>
   );
diff --git a/frontend/app/[locale]/(protected)/disputes/page.tsx b/frontend/app/[locale]/(protected)/disputes/page.tsx
index 613c7f91..74dd03ad 100644
--- a/frontend/app/[locale]/(protected)/disputes/page.tsx
+++ b/frontend/app/[locale]/(protected)/disputes/page.tsx
@@ -1,42 +1,27 @@
 "use client";
 
 import React, { useCallback, useEffect, useState } from "react";
-import Link from "next/link";
+import { Link } from "@/i18n/navigation";
 import { request } from "@/lib/api-client";
 import { FileDisputeModal } from "@/components/disputes/FileDisputeModal";
-import { useToast } from "@/components/ui/use-toast";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type DisputeStatus = "OPEN" | "UNDER_REVIEW" | "RESOLVED" | "REJECTED";
-
-interface Dispute {
-  id: string;
-  documentId: string;
-  description: string;
-  reason: string | null;
-  status: DisputeStatus;
-  filedBy: string;
-  createdAt: string;
-  resolution?: string | null;
-}
-
-interface Document {
-  id: string;
-  title: string;
-}
+import {
+  disputeStatusLabel,
+  normalizeDisputeList,
+  normalizeDocumentList,
+  type Dispute,
+  type DisputeDocumentSummary,
+  type DisputeStatus,
+} from "@/lib/disputes";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 const STATUS_CLASSES: Record<DisputeStatus, string> = {
-  OPEN: "bg-blue-100 text-blue-800",
-  UNDER_REVIEW: "bg-yellow-100 text-yellow-800",
-  RESOLVED: "bg-green-100 text-green-800",
-  REJECTED: "bg-red-100 text-red-800",
+  open: "bg-blue-100 text-blue-800",
+  in_review: "bg-yellow-100 text-yellow-800",
+  resolved: "bg-green-100 text-green-800",
+  dismissed: "bg-red-100 text-red-800",
 };
 
 // ---------------------------------------------------------------------------
@@ -45,21 +30,20 @@ const STATUS_CLASSES: Record<DisputeStatus, string> = {
 
 export default function DisputesPage() {
   const [disputes, setDisputes] = useState<Dispute[]>([]);
-  const [documents, setDocuments] = useState<Document[]>([]);
+  const [documents, setDocuments] = useState<DisputeDocumentSummary[]>([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [showModal, setShowModal] = useState(false);
-  const [statusFilter, setStatusFilter] = useState<DisputeStatus | "ALL">(
-    "ALL",
+  const [statusFilter, setStatusFilter] = useState<DisputeStatus | "all">(
+    "all",
   );
-  const { toast } = useToast();
 
   const fetchDisputes = useCallback(async () => {
     setLoading(true);
     setError(null);
     try {
-      const disputesData = await request<Dispute[]>("/api/disputes");
-      setDisputes(disputesData);
+      const response = await request<unknown>("disputes");
+      setDisputes(normalizeDisputeList(response).data);
     } catch (err) {
       setError(err instanceof Error ? err.message : "Failed to load disputes.");
     } finally {
@@ -69,10 +53,8 @@ export default function DisputesPage() {
 
   const fetchDocuments = useCallback(async () => {
     try {
-      const documentsData = await request<{ documents: Document[] }>(
-        "/api/documents",
-      );
-      setDocuments(documentsData.documents);
+      const response = await request<unknown>("documents");
+      setDocuments(normalizeDocumentList(response).data);
     } catch (err) {
       // Documents are optional for the page to render, so we don't set a page-level error
       console.error("Failed to load documents:", err);
@@ -89,7 +71,7 @@ export default function DisputesPage() {
   };
 
   const filteredDisputes =
-    statusFilter === "ALL"
+    statusFilter === "all"
       ? disputes
       : disputes.filter((d) => d.status === statusFilter);
 
@@ -127,15 +109,15 @@ export default function DisputesPage() {
           id="status-filter"
           value={statusFilter}
           onChange={(e) =>
-            setStatusFilter(e.target.value as DisputeStatus | "ALL")
+            setStatusFilter(e.target.value as DisputeStatus | "all")
           }
           className="rounded-md border-gray-300 shadow-sm focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50"
         >
-          <option value="ALL">All Statuses</option>
-          <option value="OPEN">Open</option>
-          <option value="UNDER_REVIEW">Under Review</option>
-          <option value="RESOLVED">Resolved</option>
-          <option value="REJECTED">Rejected</option>
+          <option value="all">All Statuses</option>
+          <option value="open">Open</option>
+          <option value="in_review">Under Review</option>
+          <option value="resolved">Resolved</option>
+          <option value="dismissed">Dismissed</option>
         </select>
       </div>
 
@@ -155,7 +137,7 @@ export default function DisputesPage() {
             No disputes filed
           </h3>
           <p className="mt-1 text-sm text-gray-500">
-            {statusFilter === "ALL"
+            {statusFilter === "all"
               ? "When you file a dispute it will appear here."
               : `You have no disputes with the status '${statusFilter}'.`}
           </p>
@@ -203,15 +185,22 @@ export default function DisputesPage() {
                     className="px-4 py-3 text-gray-700 truncate"
                     style={{ maxWidth: "200px" }}
                   >
-                    {dispute.description}
+                    <span className="block truncate">
+                      {dispute.description}
+                    </span>
+                    {dispute.reason && (
+                      <span className="mt-1 block text-xs text-gray-500">
+                        {dispute.reason.name}
+                      </span>
+                    )}
                   </td>
                   <td className="px-4 py-3">
                     <span
-                      className={`inline-block rounded-full px-2 py-0.5 text-xs font-medium ${
+                      className={`inline-block rounded-full px-2 py-0.5 text-xs font-medium capitalize ${
                         STATUS_CLASSES[dispute.status]
                       }`}
                     >
-                      {dispute.status.replace("_", " ")}
+                      {disputeStatusLabel(dispute.status)}
                     </span>
                   </td>
                   <td className="px-4 py-3 text-gray-600 whitespace-nowrap">
diff --git a/frontend/app/[locale]/(protected)/documents/upload/page.tsx b/frontend/app/[locale]/(protected)/documents/upload/page.tsx
index c45a3ef3..d732f454 100644
--- a/frontend/app/[locale]/(protected)/documents/upload/page.tsx
+++ b/frontend/app/[locale]/(protected)/documents/upload/page.tsx
@@ -1,9 +1,16 @@
 "use client";
 
 import React, { useState, useRef } from "react";
-import { useRouter } from "next/navigation";
-
-const ALLOWED_TYPES = ["application/pdf", "image/png", "image/jpeg"];
+import { useRouter } from "@/i18n/navigation";
+import { getApiUrl, request } from "@/lib/api-client";
+import { sanitizeSvg } from "@/lib/document-sanitizer";
+
+const ALLOWED_TYPES = [
+  "application/pdf",
+  "image/png",
+  "image/jpeg",
+  "image/svg+xml",
+];
 const MAX_SIZE_BYTES = 20 * 1024 * 1024; // 20MB
 
 export default function DocumentUploadPage() {
@@ -19,7 +26,9 @@ export default function DocumentUploadPage() {
 
   function validateFile(file: File): string | null {
     if (!ALLOWED_TYPES.includes(file.type)) {
-      return "Invalid file type. Only PDF, PNG, and JPEG files are allowed.";
+      return (
+        "Invalid file type. Only PDF, PNG, JPEG, and SVG files are allowed."
+      );
     }
     if (file.size > MAX_SIZE_BYTES) {
       return "File is too large. Maximum file size allowed is 20MB.";
@@ -27,19 +36,36 @@ export default function DocumentUploadPage() {
     return null;
   }
 
-  function handleFileChange(file: File | null) {
+  async function prepareFile(file: File): Promise<File | string> {
+    const validationError = validateFile(file);
+    if (validationError) return validationError;
+    if (file.type !== "image/svg+xml") return file;
+
+    try {
+      const sanitized = sanitizeSvg(await file.text());
+      const sanitizedFile = new File([sanitized], file.name, {
+        type: "image/svg+xml",
+        lastModified: file.lastModified,
+      });
+      return validateFile(sanitizedFile) ?? sanitizedFile;
+    } catch {
+      return "The SVG file could not be sanitized safely.";
+    }
+  }
+
+  async function handleFileChange(file: File | null) {
     if (!file) return;
-    const valError = validateFile(file);
-    if (valError) {
-      setError(valError);
+    const preparedFile = await prepareFile(file);
+    if (typeof preparedFile === "string") {
+      setError(preparedFile);
       setSelectedFile(null);
       return;
     }
 
     setError("");
-    setSelectedFile(file);
+    setSelectedFile(preparedFile);
     if (!title) {
-      setTitle(file.name.replace(/\.[^/.]+$/, ""));
+      setTitle(preparedFile.name.replace(/\.[^/.]+$/, ""));
     }
   }
 
@@ -88,26 +114,24 @@ export default function DocumentUploadPage() {
         setProgress((prev) => (prev >= 90 ? prev : prev + 20));
       }, 200);
 
-      const response = await fetch("/api/documents/upload", {
-        method: "POST",
-        body: formData,
-      });
-
-      clearInterval(interval);
-      setProgress(100);
-
-      if (response.status === 202 || response.ok) {
-        const data = await response.json().catch(() => ({ id: "new-doc-id" }));
+      try {
+        const data = await request<{ id?: string; documentId?: string }>(
+          getApiUrl("documents/upload"),
+          {
+            method: "POST",
+            body: formData,
+          },
+        );
+        setProgress(100);
         const docId = data.id || data.documentId || "new-doc-id";
         setTimeout(() => {
           router.push(`/documents/${docId}`);
         }, 500);
-      } else {
-        const data = await response.json().catch(() => ({}));
-        setError(data.message || "Failed to upload document. Please try again.");
+      } finally {
+        clearInterval(interval);
       }
     } catch {
-      setError("Network error uploading document.");
+      setError("Failed to upload document. Please try again.");
     } finally {
       setUploading(false);
     }
@@ -118,7 +142,8 @@ export default function DocumentUploadPage() {
       <div className="rounded-xl border border-gray-800 bg-gray-950 p-8 shadow-2xl">
         <h1 className="text-2xl font-bold">Upload New Document</h1>
         <p className="mt-1 text-xs text-gray-400">
-          Upload PDF, PNG, or JPEG documents (up to 20MB) for automated AI verification.
+          Upload PDF, PNG, JPEG, or SVG documents (up to 20MB) for automated
+          AI verification.
         </p>
 
         <form onSubmit={handleUpload} className="mt-6">
@@ -151,7 +176,7 @@ export default function DocumentUploadPage() {
             <input
               ref={fileInputRef}
               type="file"
-              accept=".pdf,.png,.jpeg,.jpg"
+              accept=".pdf,.png,.jpeg,.jpg,.svg,image/svg+xml"
               className="hidden"
               onChange={(e) => handleFileChange(e.target.files?.[0] || null)}
             />
@@ -174,7 +199,9 @@ export default function DocumentUploadPage() {
                 <p className="text-sm font-medium text-gray-200">
                   Drag and drop your file here, or <span className="text-blue-400 underline">browse</span>
                 </p>
-                <p className="mt-1 text-xs text-gray-500">Supports PDF, PNG, JPEG (Max 20MB)</p>
+                <p className="mt-1 text-xs text-gray-500">
+                  Supports PDF, PNG, JPEG, SVG (Max 20MB)
+                </p>
               </div>
             )}
           </div>
diff --git a/frontend/app/[locale]/(protected)/layout.tsx b/frontend/app/[locale]/(protected)/layout.tsx
index c9ad4c43..854e74c2 100644
--- a/frontend/app/[locale]/(protected)/layout.tsx
+++ b/frontend/app/[locale]/(protected)/layout.tsx
@@ -2,6 +2,7 @@ import { getTranslations, setRequestLocale } from "next-intl/server";
 import { Link } from "@/i18n/navigation";
 import LanguageSwitcher from "@/components/LanguageSwitcher";
 import NotificationBell from "@/components/layout/NotificationBell";
+import { SessionBootstrap } from "@/components/SessionBootstrap";
 
 export const dynamic = "force-dynamic";
 
@@ -19,49 +20,51 @@ export default async function ProtectedLayout({
   const t = await getTranslations("nav");
 
   return (
-    <div className="min-h-screen bg-gray-50">
-      <nav className="sticky top-0 z-40 border-b border-gray-200 bg-white">
-        <div className="mx-auto flex h-14 max-w-7xl items-center justify-between px-4 sm:px-6">
-          <div className="flex items-center gap-6">
-            <Link href="/" className="text-lg font-bold text-gray-900">
-              SMALDA
-            </Link>
-            <div className="hidden items-center gap-4 sm:flex">
-              <Link
-                href="/"
-                className="text-sm font-medium text-gray-600 hover:text-gray-900"
-              >
-                {t("dashboard")}
-              </Link>
-              <Link
-                href="/documents"
-                className="text-sm font-medium text-gray-600 hover:text-gray-900"
-              >
-                {t("documents")}
-              </Link>
-              <Link
-                href="/admin"
-                className="text-sm font-medium text-gray-600 hover:text-gray-900"
-              >
-                Admin
-              </Link>
-              <Link
-                href="/settings"
-                className="text-sm font-medium text-gray-600 hover:text-gray-900"
-              >
-                {t("settings")}
+    <SessionBootstrap>
+      <div className="min-h-screen bg-gray-50">
+        <nav className="sticky top-0 z-40 border-b border-gray-200 bg-white">
+          <div className="mx-auto flex h-14 max-w-7xl items-center justify-between px-4 sm:px-6">
+            <div className="flex items-center gap-6">
+              <Link href="/" className="text-lg font-bold text-gray-900">
+                SMALDA
               </Link>
+              <div className="hidden items-center gap-4 sm:flex">
+                <Link
+                  href="/"
+                  className="text-sm font-medium text-gray-600 hover:text-gray-900"
+                >
+                  {t("dashboard")}
+                </Link>
+                <Link
+                  href="/documents"
+                  className="text-sm font-medium text-gray-600 hover:text-gray-900"
+                >
+                  {t("documents")}
+                </Link>
+                <Link
+                  href="/admin"
+                  className="text-sm font-medium text-gray-600 hover:text-gray-900"
+                >
+                  Admin
+                </Link>
+                <Link
+                  href="/settings"
+                  className="text-sm font-medium text-gray-600 hover:text-gray-900"
+                >
+                  {t("settings")}
+                </Link>
+              </div>
             </div>
-          </div>
 
-          <div className="flex items-center gap-3">
-            <NotificationBell />
-            <LanguageSwitcher />
+            <div className="flex items-center gap-3">
+              <NotificationBell />
+              <LanguageSwitcher />
+            </div>
           </div>
-        </div>
-      </nav>
+        </nav>
 
-      <main className="mx-auto max-w-7xl px-4 py-6 sm:px-6">{children}</main>
-    </div>
+        <main className="mx-auto max-w-7xl px-4 py-6 sm:px-6">{children}</main>
+      </div>
+    </SessionBootstrap>
   );
 }
diff --git a/frontend/app/[locale]/(protected)/settings/data/page.tsx b/frontend/app/[locale]/(protected)/settings/data/page.tsx
index dc3c869d..a9041db3 100644
--- a/frontend/app/[locale]/(protected)/settings/data/page.tsx
+++ b/frontend/app/[locale]/(protected)/settings/data/page.tsx
@@ -1,25 +1,17 @@
 "use client";
 
 import React, { useEffect, useRef, useState } from "react";
-import { useRouter } from "next/navigation";
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+import {
+  getApiUrl,
+  logoutSession,
+  request,
+  requestBlob,
+} from "@/lib/api-client";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-function getAuthHeaders(): HeadersInit {
-  const token =
-    typeof window !== "undefined" ? localStorage.getItem("auth-token") : null;
-  return token ? { Authorization: `Bearer ${token}` } : {};
-}
-
-function logout() {
-  localStorage.removeItem("auth-token");
-  document.cookie = "token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";
-}
-
 const COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24 hours
 const STORAGE_KEY = "last_data_export_ts";
 
@@ -162,8 +154,6 @@ function DeleteConfirmationModal({
 // ---------------------------------------------------------------------------
 
 export default function SettingsDataPage() {
-  const router = useRouter();
-
   // ── Export state ───────────────────────────────────────────────────────────
   const [isExporting, setIsExporting] = useState(false);
   const [exportError, setExportError] = useState<string | null>(null);
@@ -184,11 +174,7 @@ export default function SettingsDataPage() {
     setIsExporting(true);
     setExportError(null);
     try {
-      const res = await fetch(`${API_BASE}/api/users/me/export`, {
-        headers: getAuthHeaders(),
-      });
-      if (!res.ok) throw new Error(`Export failed: ${res.status}`);
-      const blob = await res.blob();
+      const blob = await requestBlob(getApiUrl("users/me/export"));
       const url = URL.createObjectURL(blob);
       const a = document.createElement("a");
       a.href = url;
@@ -215,24 +201,13 @@ export default function SettingsDataPage() {
     setIsDeleting(true);
     setDeleteError(null);
     try {
-      const res = await fetch(`${API_BASE}/api/users/me/data`, {
+      await request(getApiUrl("users/me/data"), {
         method: "DELETE",
-        headers: {
-          "Content-Type": "application/json",
-          ...getAuthHeaders(),
-        },
-        body: JSON.stringify({ password }),
+        body: { password },
       });
 
-      if (!res.ok) {
-        const body = await res.json().catch(() => ({}));
-        throw new Error(
-          body?.message ?? `Deletion failed: ${res.status}`
-        );
-      }
-
-      logout();
-      router.push("/?deleted=true");
+      await logoutSession();
+      window.location.assign("/?deleted=true");
     } catch (err: unknown) {
       setDeleteError(
         err instanceof Error ? err.message : "Deletion failed. Please try again."
diff --git a/frontend/app/[locale]/(protected)/settings/security/page.tsx b/frontend/app/[locale]/(protected)/settings/security/page.tsx
index 8c85a477..cb5febb2 100644
--- a/frontend/app/[locale]/(protected)/settings/security/page.tsx
+++ b/frontend/app/[locale]/(protected)/settings/security/page.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import React, { useState } from "react";
+import { logoutSession } from "@/lib/api-client";
 
 // ─────────────────────────────────────────────
 // Types
@@ -268,7 +269,7 @@ function DangerZone() {
     try {
       // Replace with: await api.delete('/users/me')
       await new Promise((r) => setTimeout(r, 800));
-      // On success the auth layer should clear the session and redirect.
+      await logoutSession();
       window.location.href = "/login";
     } catch {
       setError("Failed to delete account. Please try again.");
diff --git a/frontend/app/[locale]/2fa/setup/page.tsx b/frontend/app/[locale]/2fa/setup/page.tsx
index b2871eca..458929ba 100644
--- a/frontend/app/[locale]/2fa/setup/page.tsx
+++ b/frontend/app/[locale]/2fa/setup/page.tsx
@@ -1,10 +1,9 @@
 "use client";
 
 import React, { useEffect, useState } from "react";
-import { useRouter } from "next/navigation";
+import { getApiUrl, request } from "@/lib/api-client";
 
 export default function TwoFactorSetupPage() {
-  const router = useRouter();
   const [step, setStep] = useState<"loading" | "scan" | "confirmed">("loading");
   const [otpUri, setOtpUri] = useState<string>("");
   const [secret, setSecret] = useState<string>("");
@@ -16,15 +15,15 @@ export default function TwoFactorSetupPage() {
   useEffect(() => {
     async function init2FA() {
       try {
-        const response = await fetch("/api/auth/2fa/setup", { method: "POST" });
-        if (response.ok) {
-          const data = await response.json();
-          setOtpUri(data.otpauthUrl || `otpauth://totp/SMALDA?secret=${data.secret}`);
-          setSecret(data.secret || "JBSWY3DPEHPK3PXP");
-          setStep("scan");
-        } else {
-          setError("Failed to initialize 2FA setup. Please try again.");
-        }
+        const data = await request<{
+          otpauthUrl?: string;
+          secret?: string;
+        }>(getApiUrl("auth/2fa/setup"), { method: "POST" });
+        setOtpUri(
+          data.otpauthUrl || `otpauth://totp/SMALDA?secret=${data.secret}`,
+        );
+        setSecret(data.secret || "JBSWY3DPEHPK3PXP");
+        setStep("scan");
       } catch {
         setError("Network error initializing 2FA.");
       }
@@ -43,21 +42,23 @@ export default function TwoFactorSetupPage() {
     setError("");
 
     try {
-      const response = await fetch("/api/auth/2fa/verify", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ code: totpCode, secret }),
-      });
-
-      if (response.ok) {
-        const data = await response.json();
-        setBackupCodes(data.backupCodes || ["CODE-1234-5678", "CODE-8765-4321", "CODE-9988-7766"]);
-        setStep("confirmed");
-      } else {
-        setError("Invalid verification code. Please check your authenticator app.");
-      }
+      const data = await request<{ backupCodes?: string[] }>(
+        getApiUrl("auth/2fa/verify"),
+        {
+          method: "POST",
+          body: { code: totpCode, secret },
+        },
+      );
+      setBackupCodes(
+        data.backupCodes || [
+          "CODE-1234-5678",
+          "CODE-8765-4321",
+          "CODE-9988-7766",
+        ],
+      );
+      setStep("confirmed");
     } catch {
-      setError("Network error verifying code.");
+      setError("Invalid verification code. Please check your authenticator app.");
     } finally {
       setVerifying(false);
     }
@@ -167,7 +168,7 @@ export default function TwoFactorSetupPage() {
             </div>
 
             <button
-              onClick={() => router.push("/settings")}
+              onClick={() => window.location.assign("/settings")}
               className="mt-6 w-full rounded-md bg-blue-600 py-2.5 text-sm font-medium text-white hover:bg-blue-500"
             >
               Done & Return to Settings
diff --git a/frontend/app/[locale]/2fa/verify/page.tsx b/frontend/app/[locale]/2fa/verify/page.tsx
index c2600d60..4bea9b6e 100644
--- a/frontend/app/[locale]/2fa/verify/page.tsx
+++ b/frontend/app/[locale]/2fa/verify/page.tsx
@@ -1,10 +1,10 @@
 "use client";
 
 import React, { useState, useEffect } from "react";
-import { useRouter, useSearchParams } from "next/navigation";
+import { useSearchParams } from "next/navigation";
+import { ApiError, getApiUrl, requestRaw } from "@/lib/api-client";
 
 export default function TwoFactorVerifyPage() {
-  const router = useRouter();
   const searchParams = useSearchParams();
   const challengeToken = searchParams.get("challenge");
 
@@ -36,31 +36,30 @@ export default function TwoFactorVerifyPage() {
     setError("");
 
     try {
-      const response = await fetch("/api/auth/2fa/challenge", {
+      await requestRaw(getApiUrl("auth/2fa/challenge"), {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          challengeToken,
-          code,
-          isBackupCode,
-        }),
+        body: { challengeToken, code, isBackupCode },
+        anonymous: true,
       });
-
-      if (response.ok) {
-        router.push("/dashboard");
-      } else {
+      window.location.assign("/");
+    } catch (error: unknown) {
+      if (error instanceof ApiError && error.status !== null) {
         const nextAttempts = failedAttempts + 1;
         setFailedAttempts(nextAttempts);
 
         if (nextAttempts >= 3) {
           setLockoutSeconds(15);
-          setError("Too many failed attempts. Please wait 15 seconds before trying again.");
+          setError(
+            "Too many failed attempts. Please wait 15 seconds before trying again.",
+          );
         } else {
-          setError(`Invalid 2FA code. Attempt ${nextAttempts} of 3 before temporary lockout.`);
+          setError(
+            `Invalid 2FA code. Attempt ${nextAttempts} of 3 before temporary lockout.`,
+          );
         }
+      } else {
+        setError("Network error during verification.");
       }
-    } catch {
-      setError("Network error during verification.");
     } finally {
       setLoading(false);
     }
diff --git a/frontend/app/[locale]/forgot-password/page.tsx b/frontend/app/[locale]/forgot-password/page.tsx
index a9ac471c..471dfee8 100644
--- a/frontend/app/[locale]/forgot-password/page.tsx
+++ b/frontend/app/[locale]/forgot-password/page.tsx
@@ -3,8 +3,7 @@
 import React, { useState } from "react";
 import { useTranslations } from "next-intl";
 import { Link } from "@/i18n/navigation";
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+import { ApiError, getApiUrl, requestRaw } from "@/lib/api-client";
 
 export default function ForgotPasswordPage() {
   const t = useTranslations("auth.forgotPassword");
@@ -25,17 +24,18 @@ export default function ForgotPasswordPage() {
 
     setLoading(true);
     try {
-      await fetch(`${API_BASE}/api/auth/forgot-password`, {
+      await requestRaw(getApiUrl("auth/forgot-password"), {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ email }),
+        body: { email },
+        anonymous: true,
       });
-      // The confirmation is shown unconditionally: whether the response was
-      // ok, not-found, or anything else, the account's existence must never
-      // leak through this form.
       setSubmitted(true);
-    } catch {
-      setError(t("errorGeneric"));
+    } catch (error: unknown) {
+      if (error instanceof ApiError) {
+        setSubmitted(true);
+      } else {
+        setError(t("errorGeneric"));
+      }
     } finally {
       setLoading(false);
     }
diff --git a/frontend/app/[locale]/login/LoginForm.tsx b/frontend/app/[locale]/login/LoginForm.tsx
index 9e21ffc0..76e9a9cc 100644
--- a/frontend/app/[locale]/login/LoginForm.tsx
+++ b/frontend/app/[locale]/login/LoginForm.tsx
@@ -3,11 +3,11 @@
 import { useEffect, useState } from "react";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
-import { useTranslations } from "next-intl";
+import { useLocale, useTranslations } from "next-intl";
 import { useSearchParams } from "next/navigation";
 import { Link, useRouter } from "@/i18n/navigation";
 import { loginSchema, type LoginInput } from "@/lib/schemas/auth";
-import { ApiError, apiRequest } from "@/lib/api-client";
+import { ApiError, getApiUrl, request } from "@/lib/api-client";
 import {
   resolvePostLoginPath,
   storeSession,
@@ -24,8 +24,6 @@ import {
   Input,
 } from "@/components/ui";
 
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
-
 function ResetSuccessToast({ message }: { message: string }) {
   const [visible, setVisible] = useState(true);
 
@@ -60,6 +58,7 @@ type SubmitError =
 
 export function LoginForm() {
   const t = useTranslations("auth.login");
+  const locale = useLocale();
   // Field-level messages arrive from the zod schema as full key paths
   // (`errors.email.invalid`), so they resolve against the message root.
   const tKey = useTranslations();
@@ -89,27 +88,31 @@ export function LoginForm() {
     defaultValues: { email: "", password: "" },
   });
 
-  const target = resolvePostLoginPath(searchParams.get("redirect"));
+  const target = resolvePostLoginPath(searchParams.get("redirect"), locale);
 
   // OAuth is a full-page handoff to the backend, which redirects back with a
   // token — so these are plain anchors, not locale-aware client-side links.
   const oauthHref = (provider: "google" | "github") =>
-    `${API_BASE}/api/auth/${provider}`;
+    getApiUrl(`auth/${provider}`);
 
   async function onSubmit(values: LoginInput) {
     setSubmitError(null);
     try {
-      const data = await apiRequest<LoginResponse>(
-        `${API_BASE}/api/auth/login`,
+      const data = await request<LoginResponse>(
+        getApiUrl("auth/login"),
         {
           method: "POST",
           body: values,
+          anonymous: true,
           // Lets the backend set a session cookie too, for when the token
           // stops living in localStorage.
           credentials: "include",
         },
       );
-      storeSession(data);
+      if (!storeSession(data)) {
+        setSubmitError({ kind: "api", messageKey: "errors.status.unknown" });
+        return;
+      }
       // replace, so Back does not land the user on a login page they have
       // already passed through.
       router.replace(target);
diff --git a/frontend/app/[locale]/reset-password/page.tsx b/frontend/app/[locale]/reset-password/page.tsx
index 8fa5c999..87d875af 100644
--- a/frontend/app/[locale]/reset-password/page.tsx
+++ b/frontend/app/[locale]/reset-password/page.tsx
@@ -4,8 +4,7 @@ import React, { Suspense, useState } from "react";
 import { useTranslations } from "next-intl";
 import { useSearchParams } from "next/navigation";
 import { Link, useRouter } from "@/i18n/navigation";
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+import { ApiError, getApiUrl, requestRaw } from "@/lib/api-client";
 const MIN_PASSWORD_LENGTH = 6;
 
 function InvalidTokenNotice({
@@ -80,21 +79,21 @@ function ResetPasswordForm() {
 
     setLoading(true);
     try {
-      const res = await fetch(`${API_BASE}/api/auth/reset-password`, {
+      await requestRaw(getApiUrl("auth/reset-password"), {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ token, password }),
+        body: { token, password },
+        anonymous: true,
       });
-
-      if (res.status === 400 || res.status === 401 || res.status === 410) {
+      router.push("/login?reset=success");
+    } catch (error: unknown) {
+      if (
+        error instanceof ApiError &&
+        (error.status === 400 || error.status === 401 || error.status === 410)
+      ) {
         setTokenInvalid(true);
-        return;
+      } else {
+        setError(t("errorGeneric"));
       }
-      if (!res.ok) throw new Error(`Reset failed: ${res.status}`);
-
-      router.push("/login?reset=success");
-    } catch {
-      setError(t("errorGeneric"));
     } finally {
       setLoading(false);
     }
diff --git a/frontend/app/[locale]/verify-email/page.tsx b/frontend/app/[locale]/verify-email/page.tsx
index ff1bc41b..550a56f5 100644
--- a/frontend/app/[locale]/verify-email/page.tsx
+++ b/frontend/app/[locale]/verify-email/page.tsx
@@ -1,12 +1,12 @@
 "use client";
 
 import React, { useEffect, useState } from "react";
-import { useSearchParams, useRouter } from "next/navigation";
-import Link from "next/link";
+import { useSearchParams } from "next/navigation";
+import { Link } from "@/i18n/navigation";
+import { ApiError, getApiUrl, requestRaw } from "@/lib/api-client";
 
 export default function VerifyEmailPage() {
   const searchParams = useSearchParams();
-  const router = useRouter();
   const token = searchParams.get("token");
 
   const [status, setStatus] = useState<"loading" | "success" | "failure">("loading");
@@ -23,28 +23,31 @@ export default function VerifyEmailPage() {
 
     async function verify() {
       try {
-        const response = await fetch(`/api/auth/verify-email?token=${encodeURIComponent(token)}`, {
-          method: "GET",
-        });
-
-        if (response.ok) {
-          setStatus("success");
-          setTimeout(() => {
-            router.push("/login");
-          }, 3000);
+        await requestRaw(
+          `${getApiUrl("auth/verify-email")}?token=${encodeURIComponent(token)}`,
+          { method: "GET", anonymous: true },
+        );
+        setStatus("success");
+        setTimeout(() => {
+          window.location.assign("/login");
+        }, 3000);
+      } catch (error: unknown) {
+        setStatus("failure");
+        if (error instanceof ApiError) {
+          setErrorMessage(
+            error.backendMessage ||
+              "Failed to verify email. The token may be expired or invalid.",
+          );
         } else {
-          const data = await response.json().catch(() => ({}));
-          setStatus("failure");
-          setErrorMessage(data.message || "Failed to verify email. The token may be expired or invalid.");
+          setErrorMessage(
+            "Network error verifying email. Please check your connection.",
+          );
         }
-      } catch (err) {
-        setStatus("failure");
-        setErrorMessage("Network error verifying email. Please check your connection.");
       }
     }
 
     verify();
-  }, [token, router]);
+  }, [token]);
 
   async function handleResend(e: React.FormEvent) {
     e.preventDefault();
@@ -52,17 +55,12 @@ export default function VerifyEmailPage() {
 
     setResendStatus("sending");
     try {
-      const response = await fetch("/api/auth/resend-verification", {
+      await requestRaw(getApiUrl("auth/resend-verification"), {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ email: resendEmail }),
+        body: { email: resendEmail },
+        anonymous: true,
       });
-
-      if (response.ok) {
-        setResendStatus("sent");
-      } else {
-        setResendStatus("error");
-      }
+      setResendStatus("sent");
     } catch {
       setResendStatus("error");
     }
diff --git a/frontend/components/LanguageSwitcher.tsx b/frontend/components/LanguageSwitcher.tsx
index 88d304ad..d1a370ec 100644
--- a/frontend/components/LanguageSwitcher.tsx
+++ b/frontend/components/LanguageSwitcher.tsx
@@ -4,8 +4,8 @@ import { useTransition } from "react";
 import { useLocale, useTranslations } from "next-intl";
 import { usePathname, useRouter } from "@/i18n/navigation";
 import { routing } from "@/i18n/routing";
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+import { getApiUrl, requestRaw } from "@/lib/api-client";
+import { hasStoredSession } from "@/lib/auth-session";
 
 /**
  * Persist the chosen language to the backend so it can be reused elsewhere
@@ -14,21 +14,11 @@ const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
  */
 async function persistPreferredLanguage(language: string): Promise<void> {
   try {
-    const token =
-      typeof window !== "undefined"
-        ? localStorage.getItem("auth-token")
-        : null;
-
-    // Not signed in — the language still switches locally via the cookie/URL.
-    if (!token) return;
+    if (!hasStoredSession()) return;
 
-    await fetch(`${API_BASE}/api/users/me`, {
+    await requestRaw(getApiUrl("users/me"), {
       method: "PATCH",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({ preferredLanguage: language }),
+      body: { preferredLanguage: language },
     });
   } catch {
     // Swallow — persistence is non-blocking.
diff --git a/frontend/components/SessionBootstrap.test.tsx b/frontend/components/SessionBootstrap.test.tsx
new file mode 100644
index 00000000..7747a89f
--- /dev/null
+++ b/frontend/components/SessionBootstrap.test.tsx
@@ -0,0 +1,72 @@
+import React from "react";
+import { act, render, screen, waitFor } from "@testing-library/react";
+
+const mockEnsureValidSession = jest.fn();
+const mockInitCrossTabLogoutSync = jest.fn(() => jest.fn());
+
+jest.mock("@/lib/api-client", () => ({
+  ApiError: class ApiError extends Error {},
+  ensureValidSession: (...args: unknown[]) =>
+    mockEnsureValidSession(...args),
+}));
+
+jest.mock("@/lib/session-expiry-warning", () => ({
+  initCrossTabLogoutSync: () => mockInitCrossTabLogoutSync(),
+}));
+
+import { SessionBootstrap } from "./SessionBootstrap";
+
+describe("SessionBootstrap", () => {
+  beforeEach(() => {
+    mockEnsureValidSession.mockReset();
+    mockInitCrossTabLogoutSync.mockClear();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("gates protected children until a current session is established", async () => {
+    let resolveSession!: (accessToken: string) => void;
+    mockEnsureValidSession.mockReturnValue(
+      new Promise<string>((resolve) => {
+        resolveSession = resolve;
+      }),
+    );
+
+    render(
+      <SessionBootstrap>
+        <div>protected content</div>
+      </SessionBootstrap>,
+    );
+
+    expect(screen.queryByText("protected content")).not.toBeInTheDocument();
+    resolveSession("access-token");
+    await waitFor(() =>
+      expect(screen.getByText("protected content")).toBeInTheDocument(),
+    );
+    expect(mockInitCrossTabLogoutSync).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps children gated after bounded session verification failures", async () => {
+    jest.useFakeTimers();
+    mockEnsureValidSession.mockRejectedValue(new Error("network unavailable"));
+
+    render(
+      <SessionBootstrap>
+        <div>protected content</div>
+      </SessionBootstrap>,
+    );
+
+    await act(async () => {
+      await jest.runAllTimersAsync();
+    });
+
+    expect(mockEnsureValidSession).toHaveBeenCalledTimes(3);
+    expect(screen.queryByText("protected content")).not.toBeInTheDocument();
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "Session verification failed.",
+    );
+    expect(screen.getByRole("button", { name: "Retry" })).toBeInTheDocument();
+  });
+});
diff --git a/frontend/components/SessionBootstrap.tsx b/frontend/components/SessionBootstrap.tsx
new file mode 100644
index 00000000..56f56fe9
--- /dev/null
+++ b/frontend/components/SessionBootstrap.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import { useEffect, useState, type ReactNode } from "react";
+import { ApiError, ensureValidSession } from "@/lib/api-client";
+import { initCrossTabLogoutSync } from "@/lib/session-expiry-warning";
+
+interface SessionBootstrapProps {
+  children: ReactNode;
+}
+
+const MAX_BOOTSTRAP_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 250;
+
+export function SessionBootstrap({ children }: SessionBootstrapProps) {
+  const [ready, setReady] = useState(false);
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    let active = true;
+    const stopLogoutSync = initCrossTabLogoutSync();
+
+    const establishSession = async () => {
+      for (let attempt = 1; attempt <= MAX_BOOTSTRAP_ATTEMPTS; attempt += 1) {
+        try {
+          const accessToken = await ensureValidSession();
+          if (!active) return;
+          if (accessToken) {
+            setReady(true);
+            return;
+          }
+
+          const params = new URLSearchParams();
+          params.set(
+            "redirect",
+            window.location.pathname + window.location.search,
+          );
+          window.location.href = `/login?${params.toString()}`;
+          return;
+        } catch (error: unknown) {
+          if (!active) return;
+          if (error instanceof ApiError && error.kind === "authRequired") return;
+          if (attempt === MAX_BOOTSTRAP_ATTEMPTS) {
+            setFailed(true);
+            return;
+          }
+          await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+          if (!active) return;
+        }
+      }
+    };
+
+    void establishSession();
+
+    return () => {
+      active = false;
+      stopLogoutSync();
+    };
+  }, []);
+
+  if (ready) return children;
+  if (failed) {
+    return (
+      <main role="alert">
+        <p>Session verification failed.</p>
+        <button type="button" onClick={() => window.location.reload()}>
+          Retry
+        </button>
+      </main>
+    );
+  }
+  return null;
+}
diff --git a/frontend/components/disputes/FileDisputeModal.tsx b/frontend/components/disputes/FileDisputeModal.tsx
index cc4d14fa..cf9507a0 100644
--- a/frontend/components/disputes/FileDisputeModal.tsx
+++ b/frontend/components/disputes/FileDisputeModal.tsx
@@ -2,16 +2,16 @@
 
 import React, { useState } from "react";
 import { request } from "@/lib/api-client";
+import {
+  normalizeDispute,
+  type Dispute,
+  type DisputeDocumentSummary,
+} from "@/lib/disputes";
 import { useToast } from "@/components/ui/use-toast";
 
-interface Document {
-  id: string;
-  title: string;
-}
-
 interface FileDisputeModalProps {
-  documents: Document[];
-  onDisputeFiled: (newDispute: any) => void;
+  documents: DisputeDocumentSummary[];
+  onDisputeFiled: (newDispute: Dispute) => void;
   onClose: () => void;
 }
 
@@ -25,6 +25,7 @@ export function FileDisputeModal({
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const { toast } = useToast();
+  const availableDocuments = Array.isArray(documents) ? documents : [];
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
@@ -40,11 +41,11 @@ export function FileDisputeModal({
     setSubmitting(true);
 
     try {
-      const newDispute = await request("/api/disputes", {
+      const response = await request<unknown>("disputes", {
         method: "POST",
         body: { documentId, description },
       });
-      onDisputeFiled(newDispute);
+      onDisputeFiled(normalizeDispute(response));
       toast({
         title: "Dispute Filed",
         description: "Your dispute has been successfully filed.",
@@ -78,7 +79,7 @@ export function FileDisputeModal({
               className="mt-1 block w-full rounded-md border-gray-300 py-2 pl-3 pr-10 text-base focus:border-indigo-500 focus:outline-none focus:ring-indigo-500 sm:text-sm"
             >
               <option value="">Select a document</option>
-              {documents.map((doc) => (
+              {availableDocuments.map((doc) => (
                 <option key={doc.id} value={doc.id}>
                   {doc.title}
                 </option>
diff --git a/frontend/components/layout/NotificationBell.tsx b/frontend/components/layout/NotificationBell.tsx
index a7500676..19c58619 100644
--- a/frontend/components/layout/NotificationBell.tsx
+++ b/frontend/components/layout/NotificationBell.tsx
@@ -3,8 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useRouter } from "@/i18n/navigation";
 import Link from "next/link";
-
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+import { getApiUrl, request, requestRaw } from "@/lib/api-client";
 const WS_BASE = (
   process.env.NEXT_PUBLIC_WS_URL ?? "ws://localhost:3001"
 ).replace(/^http/, "ws");
@@ -30,12 +29,6 @@ const NOTIFICATION_ICONS: Record<NotificationType, string> = {
   dispute_update: "\u2691",
 };
 
-function getAuthHeaders(): HeadersInit {
-  const token =
-    typeof window !== "undefined" ? localStorage.getItem("auth-token") : null;
-  return token ? { Authorization: `Bearer ${token}` } : {};
-}
-
 function formatRelativeTime(iso: string): string {
   const now = Date.now();
   const then = new Date(iso).getTime();
@@ -82,23 +75,18 @@ export default function NotificationBell() {
   const fetchNotifications = useCallback(async () => {
     setLoading(true);
     try {
-      const [listRes, countRes] = await Promise.all([
-        fetch(`${API_BASE}/api/notifications?limit=5`, {
-          headers: getAuthHeaders(),
-        }),
-        fetch(`${API_BASE}/api/notifications/unread-count`, {
-          headers: getAuthHeaders(),
-        }),
+      const [listData, countData] = await Promise.all([
+        request<unknown>(getApiUrl("notifications?limit=5")),
+        request<{ count?: number; unreadCount?: number }>(
+          getApiUrl("notifications/unread-count"),
+        ),
       ]);
-
-      if (listRes.ok) {
-        const data = await listRes.json();
-        setNotifications(Array.isArray(data) ? data : (data?.data ?? []));
-      }
-      if (countRes.ok) {
-        const data = await countRes.json();
-        setUnreadCount(data?.count ?? data?.unreadCount ?? 0);
-      }
+      setNotifications(
+        Array.isArray(listData)
+          ? (listData as Notification[])
+          : ((listData as { data?: Notification[] })?.data ?? []),
+      );
+      setUnreadCount(countData.count ?? countData.unreadCount ?? 0);
     } catch {
       // Silently fail — notification polling is non-critical
     } finally {
@@ -159,9 +147,8 @@ export default function NotificationBell() {
 
   async function handleMarkAllRead() {
     try {
-      await fetch(`${API_BASE}/api/notifications/read-all`, {
+      await requestRaw(getApiUrl("notifications/read-all"), {
         method: "PATCH",
-        headers: { ...getAuthHeaders(), "Content-Type": "application/json" },
       });
       setNotifications((prev) => prev.map((n) => ({ ...n, read: true })));
       setUnreadCount(0);
diff --git a/frontend/lib/__tests__/session-expiry.test.ts b/frontend/lib/__tests__/session-expiry.test.ts
index 36742279..ef037465 100644
--- a/frontend/lib/__tests__/session-expiry.test.ts
+++ b/frontend/lib/__tests__/session-expiry.test.ts
@@ -1,11 +1,3 @@
-/**
- * Tests for graceful session expiry handling (Issue #1024).
- *
- * Core requirement: 10 concurrent requests that all get 401 should trigger
- * exactly 1 refresh call.
- */
-
-// Mock localStorage
 const store: Record<string, string> = {};
 const localStorageMock = {
   getItem: jest.fn((key: string) => store[key] ?? null),
@@ -26,107 +18,107 @@ const localStorageMock = {
 
 Object.defineProperty(window, "localStorage", { value: localStorageMock });
 
-// We need to isolate the module so the refreshPromise singleton is fresh
-// and we can spy on fetch calls.
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-let apiClient: typeof import("../api-client");
+const originalFetch = globalThis.fetch;
+
+function encodeJwtPart(value: object): string {
+  return btoa(JSON.stringify(value))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function createJwt(
+  expiresAt = Math.floor(Date.now() / 1000) + 3600,
+): string {
+  const header = encodeJwtPart({ alg: "HS256", typ: "JWT" });
+  const payload = encodeJwtPart({
+    sub: "user-1",
+    email: "user@example.com",
+    role: "user",
+    exp: expiresAt,
+  });
+  return `${header}.${payload}.signature`;
+}
 
 beforeEach(() => {
   jest.resetModules();
   localStorageMock.clear();
-  // Clear the module cache so the refreshPromise singleton resets
-  jest.isolateModules(() => {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    apiClient = require("../api-client");
-  });
-  // Seed a valid refresh token so the refresh path can execute
-  store["refresh-token"] = "fake-refresh-token";
-  store["auth-token"] = "expired-access-token";
+  store["auth-refresh-token"] = createJwt();
+  store["auth-token"] = createJwt(Math.floor(Date.now() / 1000) - 1);
 });
 
-describe("Concurrent 401 → single refresh (Issue #1024)", () => {
-  it("triggers exactly one refresh when 10 parallel requests get 401", async () => {
-    // Reload inside isolatedModules to get a fresh singleton
-    let freshApiClient: typeof import("../api-client");
-    jest.isolateModules(() => {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      freshApiClient = require("../api-client");
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("concurrent proactive refresh", () => {
+  it("uses one refresh for ten requests with expired access tokens", async () => {
+    let apiClient: typeof import("../api-client");
+    await jest.isolateModulesAsync(async () => {
+      apiClient = await import("../api-client");
     });
 
     let refreshCallCount = 0;
-
-    // Mock fetch: first call to any endpoint returns 401,
-    // the refresh call returns 200 with a new token,
-    // and retried calls return 200.
-    (global as any).fetch = jest.fn((url: string) => {
-      if (url.includes("/auth/refresh")) {
+    globalThis.fetch = jest.fn((url: string) => {
+      if (url.includes("/api/v1/auth/refresh")) {
         refreshCallCount += 1;
         return Promise.resolve(
-          new Response(
-            JSON.stringify({ access_token: "new-access-token" }),
-            { status: 200, headers: { "Content-Type": "application/json" } },
-          ),
+          new Response(JSON.stringify({ access_token: createJwt() }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
         );
       }
-      // Non-refresh endpoints: succeed on the second attempt (after refresh)
       return Promise.resolve(
         new Response(JSON.stringify({ ok: true }), { status: 200 }),
       );
     }) as jest.Mock;
 
-    // Fire 10 concurrent requests — each will get a 401, triggering the
-    // refresh path. The refreshPromise singleton should deduplicate them.
-    const promises = Array.from({ length: 10 }, (_, i) =>
-      freshApiClient!.request(`/api/documents/${i}`),
+    await Promise.all(
+      Array.from({ length: 10 }, (_, index) =>
+        apiClient!.request(`documents/${index}`),
+      ),
     );
 
-    await Promise.all(promises);
-
-    // Assert: exactly 1 refresh call despite 10 concurrent 401s
     expect(refreshCallCount).toBe(1);
   });
 
-  it("clears session and redirects when refresh fails", async () => {
-    let freshApiClient: typeof import("../api-client");
-    jest.isolateModules(() => {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      freshApiClient = require("../api-client");
+  it("clears storage and redirects when proactive refresh fails", async () => {
+    let apiClient: typeof import("../api-client");
+    await jest.isolateModulesAsync(async () => {
+      apiClient = await import("../api-client");
     });
 
-    // Override window.location for the redirect assertion
-    const originalLocation = window.location;
-    // @ts-expect-error — partial mock of Location
-    delete (window as any).location;
-    (window as any).location = { href: "" };
-
-    (global as any).fetch = jest.fn((url: string) => {
-      if (url.includes("/auth/refresh")) {
-        return Promise.resolve(
-          new Response(JSON.stringify({ error: "invalid_grant" }), {
-            status: 401,
-          }),
-        );
-      }
-      return Promise.resolve(
-        new Response(JSON.stringify({ error: "unauthorized" }), {
+    let redirect = "";
+    Object.defineProperty(window, "location", {
+      value: {
+        pathname: "/dashboard",
+        search: "",
+        get href() {
+          return redirect;
+        },
+        set href(value: string) {
+          redirect = value;
+        },
+      },
+      configurable: true,
+    });
+    globalThis.fetch = jest.fn(() =>
+      Promise.resolve(
+        new Response(JSON.stringify({ error: "invalid_grant" }), {
           status: 401,
         }),
-      );
-    }) as jest.Mock;
-
-    try {
-      await freshApiClient!.request("/api/documents/1");
-    } catch {
-      // Expected — api-client throws after refresh failure
-    }
-
-    // Should have cleared localStorage tokens
+      ),
+    ) as jest.Mock;
+
+    await expect(
+      apiClient!.request("documents/1"),
+    ).rejects.toMatchObject({
+      status: 401,
+      kind: "authRequired",
+    });
     expect(store["auth-token"]).toBeUndefined();
-    expect(store["refresh-token"]).toBeUndefined();
-    // Should have redirected to login preserving the path
-    expect(window.location.href).toContain("/login?redirect=");
-
-    // Restore
-    (window as any).location = originalLocation;
+    expect(store["auth-refresh-token"]).toBeUndefined();
+    expect(redirect).toContain("/login?redirect=");
   });
 });
diff --git a/frontend/lib/api-client.ts b/frontend/lib/api-client.ts
index b83d5359..46c180f0 100644
--- a/frontend/lib/api-client.ts
+++ b/frontend/lib/api-client.ts
@@ -1,26 +1,58 @@
 /**
- * Central fetch wrapper with JWT handling and auto refresh-on-401.
- *
- * Exports a `request(path, options)` helper that:
- *   - reads NEXT_PUBLIC_API_URL as the base URL
- *   - attaches the JWT from localStorage as a Bearer header
- *   - on 401, attempts a silent refresh via POST /auth/refresh
- *   - if refresh also fails, clears the session and redirects to /login
- *   - parses JSON responses
- *   - throws typed ApiError for non-2xx responses
- *
- * Status codes map to i18n keys under `errors.status.*`. Consumers
- * catch ApiError and render <ErrorBanner messageKey={err.messageKey} />.
- * Raw backend error text, stack traces, and internal identifiers are
- * never surfaced.
+ * Central fetch wrapper for the versioned SMALDA API. Managed authentication is
+ * limited to the configured API origin under /api/v1; callers receive the same
+ * typed ApiError contract after one bounded reauthentication attempt.
  */
 
-const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+import {
+  clearSession,
+  getValidAccessToken,
+  getValidRefreshToken,
+  hasStoredSession,
+  setAccessToken,
+} from "./auth-session";
+
+export { clearSession } from "./auth-session";
+
+const CONFIGURED_API_URL =
+  process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001";
+const API_ORIGIN = new URL(CONFIGURED_API_URL).origin;
+const API_ROOT_PATH = "/api/v1";
+
+export const API_V1_ROOT = `${API_ORIGIN}${API_ROOT_PATH}`;
+
+function apiPath(path: string): string {
+  const trimmedPath = path.trim();
+  if (
+    trimmedPath.startsWith("//") ||
+    /^[A-Za-z][A-Za-z0-9+.-]*:/.test(trimmedPath) ||
+    /[\\\u0000-\u001f\u007f]/i.test(path) ||
+    /%(?:5c|0[0-9a-f]|1[0-9a-f]|7f)/i.test(path)
+  ) {
+    throw new Error("API path must be a safe relative path");
+  }
 
-const ACCESS_TOKEN_KEY = "auth-token";
-const REFRESH_TOKEN_KEY = "refresh-token";
+  let normalized = trimmedPath.replace(/^\/+/, "");
+  if (normalized === "api" || normalized === "api/v1") normalized = "";
+  else if (normalized.startsWith("api/v1/")) normalized = normalized.slice(7);
+  else if (normalized.startsWith("api/")) normalized = normalized.slice(4);
+
+  const url = new URL(normalized, `${API_V1_ROOT}/`);
+  if (
+    url.origin !== API_ORIGIN ||
+    (url.pathname !== API_ROOT_PATH &&
+      !url.pathname.startsWith(`${API_ROOT_PATH}/`))
+  ) {
+    throw new Error("API path escaped the configured API root");
+  }
 
-// ── ApiError ────────────────────────────────────────────────────────────────
+  return url.toString();
+}
+
+/** Builds a canonical backend URL while treating NEXT_PUBLIC_API_URL as the origin. */
+export function getApiUrl(path: string): string {
+  return apiPath(path);
+}
 
 export type ApiErrorKind =
   | "authRequired"
@@ -75,76 +107,76 @@ export function classifyStatus(status: number): ApiErrorMapping {
   }
 }
 
-// ── Token helpers ───────────────────────────────────────────────────────────
-
-function getAccessToken(): string | null {
-  if (typeof window === "undefined") return null;
-  return window.localStorage.getItem(ACCESS_TOKEN_KEY);
-}
-
-function getRefreshToken(): string | null {
-  if (typeof window === "undefined") return null;
-  return window.localStorage.getItem(REFRESH_TOKEN_KEY);
-}
-
-function setAccessToken(token: string): void {
-  if (typeof window === "undefined") return;
-  window.localStorage.setItem(ACCESS_TOKEN_KEY, token);
-}
-
-export function clearSession(): void {
-  if (typeof window === "undefined") return;
-  window.localStorage.removeItem(ACCESS_TOKEN_KEY);
-  window.localStorage.removeItem(REFRESH_TOKEN_KEY);
-  document.cookie = "token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";
-  // Signal other tabs to also redirect to login
-  window.localStorage.setItem("logout-event", Date.now().toString());
-}
-
-/**
- * Preserve the current path (including locale) as the post-login destination,
- * then redirect to login. The login page's resolvePostLoginPath reads the
- * `?redirect=` param so the user lands back where they were after signing in.
- */
 function redirectToLogin(): void {
   if (typeof window === "undefined") return;
+
   const currentPath = window.location.pathname + window.location.search;
   const params = new URLSearchParams();
   params.set("redirect", currentPath);
   window.location.href = `/login?${params.toString()}`;
 }
 
-// ── Refresh logic ───────────────────────────────────────────────────────────
+class RefreshError extends Error {
+  readonly kind: "network" | "transient" | "session";
+  readonly status: number | null;
+
+  constructor(
+    kind: "network" | "transient" | "session",
+    status: number | null = null,
+  ) {
+    super(kind);
+    this.name = "RefreshError";
+    this.kind = kind;
+    this.status = status;
+  }
+}
 
 let refreshPromise: Promise<string> | null = null;
 
-/**
- * Attempt a silent token refresh. Deduplicates concurrent refresh calls
- * so that multiple 401s in-flight only trigger one refresh request.
- */
 async function refreshAccessToken(): Promise<string> {
   if (refreshPromise) return refreshPromise;
 
   refreshPromise = (async () => {
     try {
-      const refreshToken = getRefreshToken();
-      if (!refreshToken) {
-        throw new Error("No refresh token available");
+      const refreshToken = getValidRefreshToken();
+      if (!refreshToken) throw new RefreshError("session");
+
+      let response: Response;
+      try {
+        response = await fetch(getApiUrl("auth/refresh"), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          credentials: "include",
+          cache: "no-store",
+          body: JSON.stringify({ refreshToken }),
+        });
+      } catch {
+        throw new RefreshError("network");
       }
 
-      const res = await fetch(`${API_BASE}/auth/refresh`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ refreshToken }),
-      });
+      if (!response.ok) {
+        if ([400, 401, 403].includes(response.status)) {
+          throw new RefreshError("session", response.status);
+        }
+        throw new RefreshError("transient", response.status);
+      }
 
-      if (!res.ok) {
-        throw new Error("Refresh failed");
+      let data: unknown;
+      try {
+        data = await response.json();
+      } catch {
+        throw new RefreshError("transient", 502);
       }
 
-      const data = (await res.json()) as { access_token: string };
-      setAccessToken(data.access_token);
-      return data.access_token;
+      const accessToken =
+        typeof data === "object" && data !== null
+          ? (data as Record<string, unknown>).access_token
+          : null;
+      if (typeof accessToken !== "string" || !setAccessToken(accessToken)) {
+        throw new RefreshError("transient", 502);
+      }
+
+      return accessToken;
     } finally {
       refreshPromise = null;
     }
@@ -153,7 +185,83 @@ async function refreshAccessToken(): Promise<string> {
   return refreshPromise;
 }
 
-// ── Request helper ──────────────────────────────────────────────────────────
+function networkError(): ApiError {
+  return new ApiError({
+    status: null,
+    kind: "network",
+    messageKey: "errors.status.network",
+  });
+}
+
+function authRequiredError(): ApiError {
+  return new ApiError({
+    status: 401,
+    kind: "authRequired",
+    messageKey: "errors.status.unauthorized",
+  });
+}
+
+function handleRefreshFailure(error: unknown): never {
+  if (error instanceof RefreshError) {
+    if (error.kind === "network") throw networkError();
+    if (error.kind === "transient") {
+      const status = error.status ?? 503;
+      const { kind, messageKey } = classifyStatus(status);
+      throw new ApiError({ status, kind, messageKey });
+    }
+  }
+
+  clearSession();
+  redirectToLogin();
+  throw authRequiredError();
+}
+
+/** Returns a current access token, refreshing proactively when a valid refresh token exists. */
+export async function ensureValidSession(): Promise<string | null> {
+  const accessToken = getValidAccessToken();
+  if (accessToken) return accessToken;
+  if (!hasStoredSession()) return null;
+
+  try {
+    return await refreshAccessToken();
+  } catch (error) {
+    handleRefreshFailure(error);
+  }
+}
+
+/**
+ * Attempts access-token revocation only; the backend logout contract has no
+ * refresh-token or session identifier. Local credentials are always cleared.
+ */
+export async function logoutSession(): Promise<boolean> {
+  let accessToken = getValidAccessToken();
+  if (!accessToken && hasStoredSession()) {
+    try {
+      accessToken = await refreshAccessToken();
+    } catch {
+      clearSession();
+      return false;
+    }
+  }
+
+  let acknowledged = false;
+  if (accessToken) {
+    try {
+      const response = await fetch(getApiUrl("auth/logout"), {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}` },
+        credentials: "omit",
+        cache: "no-store",
+      });
+      acknowledged = response.ok;
+    } catch {
+      acknowledged = false;
+    }
+  }
+
+  clearSession();
+  return acknowledged;
+}
 
 export interface RequestOptions extends Omit<RequestInit, "body"> {
   body?: BodyInit | null | unknown;
@@ -161,122 +269,186 @@ export interface RequestOptions extends Omit<RequestInit, "body"> {
   anonymous?: boolean;
 }
 
-/**
- * Extract a human-readable error message from the backend's error response.
- * Handles common NestJS error shapes:
- *   { message: "..." }
- *   { message: ["...", "..."] }
- *   { error: "..." }
- */
 async function extractBackendMessage(
-  res: Response,
+  response: Response,
 ): Promise<string | undefined> {
   try {
-    const body = await res.json();
+    const body = await response.json();
     if (typeof body === "object" && body !== null) {
       if (typeof body.message === "string") return body.message;
-      if (Array.isArray(body.message) && body.message.length > 0)
+      if (Array.isArray(body.message) && body.message.length > 0) {
         return body.message.join(", ");
+      }
       if (typeof body.error === "string") return body.error;
     }
   } catch {
-    // response body wasn't parseable as JSON — that's fine
+    return undefined;
   }
   return undefined;
 }
 
-/**
- * Core request function. Callers use this instead of raw `fetch`.
- *
- *   const data = await request<{ id: string }>("/documents", { method: "POST", body: { title: "..." } });
- *
- * On a 401 response the function will:
- *   1. Attempt a silent refresh via POST /auth/refresh
- *   2. If refresh succeeds, retry the original request with the new token
- *   3. If refresh also fails, clear the session and redirect to /login
- */
-export async function request<T = unknown>(
-  path: string,
-  options: RequestOptions = {},
-): Promise<T> {
-  const { anonymous = false, ...fetchOpts } = options;
+async function throwForResponse(response: Response): Promise<void> {
+  if (response.ok) return;
+
+  const { kind, messageKey } = classifyStatus(response.status);
+  const backendMessage = await extractBackendMessage(response);
+  throw new ApiError({
+    status: response.status,
+    kind,
+    messageKey,
+    backendMessage,
+  });
+}
+
+function resolveUrl(path: string): string {
+  if (/^https?:\/\//i.test(path)) return path;
+  return getApiUrl(path);
+}
+
+function isManagedApiUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return (
+      parsed.origin === API_ORIGIN &&
+      (parsed.pathname === API_ROOT_PATH ||
+        parsed.pathname.startsWith(`${API_ROOT_PATH}/`))
+    );
+  } catch {
+    return false;
+  }
+}
 
-  const url = path.startsWith("http") ? path : `${API_BASE}${path}`;
+function isRefreshEndpoint(url: string): boolean {
+  try {
+    return (
+      new URL(url).pathname.replace(/\/+$/, "") ===
+      `${API_ROOT_PATH}/auth/refresh`
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isFormDataBody(body: unknown): body is FormData {
+  return typeof FormData !== "undefined" && body instanceof FormData;
+}
+
+function isUrlSearchParamsBody(body: unknown): body is URLSearchParams {
+  return typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams;
+}
+
+function isDirectBody(body: unknown): body is BodyInit {
+  return (
+    typeof body === "string" ||
+    (typeof FormData !== "undefined" && body instanceof FormData) ||
+    (typeof URLSearchParams !== "undefined" &&
+      body instanceof URLSearchParams) ||
+    (typeof Blob !== "undefined" && body instanceof Blob) ||
+    (typeof ArrayBuffer !== "undefined" &&
+      (body instanceof ArrayBuffer || ArrayBuffer.isView(body)))
+  );
+}
+
+async function sendRequest(
+  path: string,
+  options: RequestOptions,
+): Promise<Response> {
+  const { anonymous = false, ...fetchOptions } = options;
+  const url = resolveUrl(path);
+  const managedApiRequest = isManagedApiUrl(url);
+  const callerSuppliedAuthorization = new Headers(
+    fetchOptions.headers,
+  ).has("Authorization");
+  const managesAuthentication =
+    managedApiRequest &&
+    !isRefreshEndpoint(url) &&
+    !anonymous &&
+    !callerSuppliedAuthorization;
 
   const doFetch = async (token: string | null): Promise<Response> => {
-    const headers = new Headers(fetchOpts.headers);
-    if (!headers.has("Content-Type") && !(fetchOpts.body instanceof FormData)) {
+    const headers = new Headers(fetchOptions.headers);
+    if (
+      !headers.has("Content-Type") &&
+      !isFormDataBody(fetchOptions.body) &&
+      !isUrlSearchParamsBody(fetchOptions.body)
+    ) {
       headers.set("Content-Type", "application/json");
     }
-    if (!anonymous && token && !headers.has("Authorization")) {
+
+    if (!managedApiRequest) {
+      headers.delete("Authorization");
+    } else if (managesAuthentication && token) {
       headers.set("Authorization", `Bearer ${token}`);
     }
 
-    let body: BodyInit | null | undefined = undefined;
-    if (fetchOpts.body !== undefined && fetchOpts.body !== null) {
-      if (
-        typeof fetchOpts.body === "string" ||
-        fetchOpts.body instanceof FormData ||
-        fetchOpts.body instanceof Blob ||
-        fetchOpts.body instanceof ArrayBuffer
-      ) {
-        body = fetchOpts.body as BodyInit;
-      } else {
-        body = JSON.stringify(fetchOpts.body);
-      }
+    let body: BodyInit | null | undefined;
+    if (fetchOptions.body !== undefined && fetchOptions.body !== null) {
+      body = isDirectBody(fetchOptions.body)
+        ? fetchOptions.body
+        : JSON.stringify(fetchOptions.body);
     }
 
-    return fetch(url, { ...fetchOpts, headers, body });
+    return fetch(url, { ...fetchOptions, headers, body });
   };
 
-  // First attempt
-  let res: Response;
+  let token: string | null = null;
+  if (managesAuthentication) token = await ensureValidSession();
+
+  let response: Response;
   try {
-    const token = getAccessToken();
-    res = await doFetch(token);
+    response = await doFetch(token);
   } catch {
-    throw new ApiError({
-      status: null,
-      kind: "network",
-      messageKey: "errors.status.network",
-    });
+    throw networkError();
   }
 
-  // Handle 401 with refresh
-  if (res.status === 401 && !anonymous) {
+  if (response.status === 401 && managesAuthentication) {
+    let replacementToken = getValidAccessToken();
+    if (!replacementToken || replacementToken === token) {
+      try {
+        replacementToken = await refreshAccessToken();
+      } catch (error) {
+        handleRefreshFailure(error);
+      }
+    }
+
     try {
-      const newToken = await refreshAccessToken();
-      res = await doFetch(newToken);
+      response = await doFetch(replacementToken);
     } catch {
-      // Refresh failed — clear session and redirect
-      clearSession();
-      redirectToLogin();
-      throw new ApiError({
-        status: 401,
-        kind: "authRequired",
-        messageKey: "errors.status.unauthorized",
-      });
+      throw networkError();
     }
   }
 
-  // Handle non-2xx
-  if (!res.ok) {
-    const { kind, messageKey } = classifyStatus(res.status);
-    const backendMessage = await extractBackendMessage(res);
-    throw new ApiError({
-      status: res.status,
-      kind,
-      messageKey,
-      backendMessage,
-    });
-  }
+  return response;
+}
 
-  // 204 No Content
-  if (res.status === 204) return undefined as T;
-  return (await res.json()) as T;
+export async function requestRaw(
+  path: string,
+  options: RequestOptions = {},
+): Promise<Response> {
+  const response = await sendRequest(path, options);
+  await throwForResponse(response);
+  return response;
 }
 
-// ── Backward-compatible alias ───────────────────────────────────────────────
+export async function requestBlob(
+  path: string,
+  options: RequestOptions = {},
+): Promise<Blob> {
+  const response = await sendRequest(path, options);
+  await throwForResponse(response);
+  if (response.status === 204) return new Blob();
+  return response.blob();
+}
+
+export async function request<T = unknown>(
+  path: string,
+  options: RequestOptions = {},
+): Promise<T> {
+  const response = await sendRequest(path, options);
+  await throwForResponse(response);
+  if (response.status === 204) return undefined as T;
+  return (await response.json()) as T;
+}
 
 /**
  * @deprecated Use `request` instead. Kept for backward compatibility.
diff --git a/frontend/lib/auth-session.test.ts b/frontend/lib/auth-session.test.ts
new file mode 100644
index 00000000..1ef225ed
--- /dev/null
+++ b/frontend/lib/auth-session.test.ts
@@ -0,0 +1,131 @@
+import {
+  clearSession,
+  getJwtExpiration,
+  getValidAccessToken,
+  getValidRefreshToken,
+  hasStoredSession,
+  resolvePostLoginPath,
+  storeSession,
+} from "./auth-session";
+
+const store: Record<string, string> = {};
+const localStorageMock = {
+  getItem: jest.fn((key: string) => store[key] ?? null),
+  setItem: jest.fn((key: string, value: string) => {
+    store[key] = value;
+  }),
+  removeItem: jest.fn((key: string) => {
+    delete store[key];
+  }),
+  clear: jest.fn(() => {
+    Object.keys(store).forEach((key) => delete store[key]);
+  }),
+  get length() {
+    return Object.keys(store).length;
+  },
+  key: jest.fn((index: number) => Object.keys(store)[index] ?? null),
+};
+
+function encodeJwtPart(value: object): string {
+  return btoa(JSON.stringify(value))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function createJwt(
+  expiresAt = Math.floor(Date.now() / 1000) + 3600,
+): string {
+  return `${encodeJwtPart({ alg: "HS256", typ: "JWT" })}.${encodeJwtPart({
+    sub: "user-1",
+    email: "user@example.com",
+    role: "user",
+    exp: expiresAt,
+  })}.signature`;
+}
+
+beforeEach(() => {
+  Object.keys(store).forEach((key) => delete store[key]);
+  Object.defineProperty(window, "localStorage", {
+    value: localStorageMock,
+    configurable: true,
+  });
+});
+
+describe("auth-session", () => {
+  it("stores and returns current backend-shaped JWTs", () => {
+    const accessToken = createJwt();
+    const refreshToken = createJwt();
+
+    expect(
+      storeSession({ access_token: accessToken, refresh_token: refreshToken }),
+    ).toBe(true);
+    expect(getValidAccessToken()).toBe(accessToken);
+    expect(getValidRefreshToken()).toBe(refreshToken);
+    expect(getJwtExpiration(accessToken)).toBeGreaterThan(Date.now() / 1000);
+    expect(hasStoredSession()).toBe(true);
+  });
+
+  it("fails closed for expired and malformed access tokens", () => {
+    store["auth-token"] = createJwt(Math.floor(Date.now() / 1000) - 1);
+    expect(getValidAccessToken()).toBeNull();
+
+    store["auth-token"] = "not-a-jwt";
+    expect(getValidAccessToken()).toBeNull();
+    expect(getJwtExpiration("not-a-jwt")).toBeNull();
+  });
+
+  it("removes a stale refresh token when the response has none", () => {
+    store["auth-refresh-token"] = createJwt();
+
+    expect(storeSession({ access_token: createJwt() })).toBe(true);
+    expect(getValidRefreshToken()).toBeNull();
+  });
+
+  it("does not fall back from a malformed canonical refresh token", () => {
+    store["auth-refresh-token"] = "malformed";
+    store["refresh-token"] = createJwt();
+    expect(getValidRefreshToken()).toBeNull();
+  });
+
+  it("rejects an expired session instead of partially storing it", () => {
+    expect(
+      storeSession({
+        access_token: createJwt(Math.floor(Date.now() / 1000) - 1),
+        refresh_token: createJwt(),
+      }),
+    ).toBe(false);
+    expect(hasStoredSession()).toBe(false);
+  });
+
+  it("strips the active locale before locale-aware navigation", () => {
+    expect(resolvePostLoginPath("/fr/settings/security", "fr")).toBe(
+      "/settings/security",
+    );
+    expect(resolvePostLoginPath("/fr?next=1", "fr")).toBe("/?next=1");
+    expect(resolvePostLoginPath("/fr//evil.example", "fr")).toBe("/");
+    expect(resolvePostLoginPath("/fr/\\evil.example", "fr")).toBe("/");
+    expect(resolvePostLoginPath(null, "fr")).toBe("/");
+  });
+
+  it("handles unavailable browser storage without throwing", () => {
+    Object.defineProperty(window, "localStorage", {
+      value: {
+        getItem: jest.fn(() => {
+          throw new Error("blocked");
+        }),
+        setItem: jest.fn(() => {
+          throw new Error("blocked");
+        }),
+        removeItem: jest.fn(() => {
+          throw new Error("blocked");
+        }),
+      },
+      configurable: true,
+    });
+
+    expect(getValidAccessToken()).toBeNull();
+    expect(storeSession({ access_token: createJwt() })).toBe(false);
+    expect(() => clearSession()).not.toThrow();
+  });
+});
diff --git a/frontend/lib/auth-session.ts b/frontend/lib/auth-session.ts
index d6eda3f3..fc407aad 100644
--- a/frontend/lib/auth-session.ts
+++ b/frontend/lib/auth-session.ts
@@ -1,38 +1,244 @@
 /**
- * Client-side session plumbing shared by the auth pages.
- *
- * FE-43's auth context is not in place yet, so the login page persists the
- * tokens it gets back from `POST /api/auth/login` through here. When the
- * context lands it should take ownership of these functions and the pages
- * should read the session off the context instead of touching storage.
+ * Browser-side ownership of the backend's snake-case JWT session response.
+ * Tokens are stored separately because the backend rotates only the access
+ * token during refresh; malformed or expired tokens are never returned for use.
  */
 
 const ACCESS_TOKEN_KEY = "auth-token";
 const REFRESH_TOKEN_KEY = "auth-refresh-token";
+const LEGACY_REFRESH_TOKEN_KEY = "refresh-token";
+const LOGOUT_EVENT_KEY = "logout-event";
+
+const JWT_ALGORITHM = "HS256";
 
-/** Shape of `POST /api/auth/login` — mirrors backend/src/auth/auth.service.ts. */
 export interface LoginResponse {
   access_token: string;
   refresh_token?: string;
 }
 
-export function storeSession(tokens: LoginResponse): void {
-  if (typeof window === "undefined") return;
-  if (tokens.access_token) {
-    window.localStorage.setItem(ACCESS_TOKEN_KEY, tokens.access_token);
+export interface JwtClaims {
+  sub: string;
+  email: string;
+  role: string;
+  exp: number;
+}
+
+function getLocalStorage(): Storage | null {
+  if (typeof window === "undefined") return null;
+
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function readToken(key: string): string | null {
+  const storage = getLocalStorage();
+  if (!storage) return null;
+
+  try {
+    return storage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function removeToken(key: string): void {
+  const storage = getLocalStorage();
+  if (!storage) return;
+
+  try {
+    storage.removeItem(key);
+  } catch {
+    return;
+  }
+}
+
+function decodeJwtPart(part: string): unknown {
+  if (!/^[A-Za-z0-9_-]+$/.test(part)) {
+    throw new Error("Invalid JWT encoding");
+  }
+  if (
+    typeof globalThis.atob !== "function" ||
+    typeof TextDecoder === "undefined"
+  ) {
+    throw new Error("JWT decoding is unavailable");
+  }
+
+  const padding = "=".repeat((4 - (part.length % 4)) % 4);
+  const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = globalThis.atob(base64 + padding);
+  const bytes = Uint8Array.from(binary, (character) =>
+    character.charCodeAt(0),
+  );
+
+  return JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+  );
+}
+
+function isJwtPayload(value: unknown): value is JwtClaims {
+  if (typeof value !== "object" || value === null) return false;
+
+  const payload = value as Record<string, unknown>;
+  return (
+    typeof payload.sub === "string" &&
+    payload.sub.length > 0 &&
+    typeof payload.email === "string" &&
+    payload.email.length > 0 &&
+    typeof payload.role === "string" &&
+    payload.role.length > 0 &&
+    typeof payload.exp === "number" &&
+    Number.isSafeInteger(payload.exp) &&
+    payload.exp > 0
+  );
+}
+
+export function getJwtClaims(token: string): JwtClaims | null {
+  try {
+    const parts = token.split(".");
+    if (
+      parts.length !== 3 ||
+      !/^[A-Za-z0-9_-]+$/.test(parts[2])
+    ) {
+      return null;
+    }
+
+    const header = decodeJwtPart(parts[0]);
+    if (
+      typeof header !== "object" ||
+      header === null ||
+      (header as Record<string, unknown>).alg !== JWT_ALGORITHM
+    ) {
+      return null;
+    }
+
+    const payload = decodeJwtPart(parts[1]);
+    return isJwtPayload(payload) ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+export function getJwtExpiration(token: string): number | null {
+  return getJwtClaims(token)?.exp ?? null;
+}
+
+function isTokenCurrent(token: string, now: number): boolean {
+  const expiration = getJwtExpiration(token);
+  return expiration !== null && expiration * 1000 > now;
+}
+
+export function getValidAccessToken(): string | null {
+  const token = readToken(ACCESS_TOKEN_KEY);
+  return token && isTokenCurrent(token, Date.now()) ? token : null;
+}
+
+export function getValidRefreshToken(): string | null {
+  const canonicalToken = readToken(REFRESH_TOKEN_KEY);
+  if (canonicalToken !== null) {
+    return isTokenCurrent(canonicalToken, Date.now()) ? canonicalToken : null;
   }
-  if (tokens.refresh_token) {
-    window.localStorage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
+
+  const legacyToken = readToken(LEGACY_REFRESH_TOKEN_KEY);
+  return legacyToken && isTokenCurrent(legacyToken, Date.now())
+    ? legacyToken
+    : null;
+}
+
+export function hasStoredSession(): boolean {
+  return (
+    readToken(ACCESS_TOKEN_KEY) !== null ||
+    readToken(REFRESH_TOKEN_KEY) !== null ||
+    readToken(LEGACY_REFRESH_TOKEN_KEY) !== null
+  );
+}
+
+export function setAccessToken(token: string): boolean {
+  if (!isTokenCurrent(token, Date.now())) return false;
+
+  const storage = getLocalStorage();
+  if (!storage) return false;
+
+  try {
+    storage.setItem(ACCESS_TOKEN_KEY, token);
+    return storage.getItem(ACCESS_TOKEN_KEY) === token;
+  } catch {
+    return false;
+  }
+}
+
+export function storeSession(tokens: LoginResponse): boolean {
+  if (
+    typeof window === "undefined" ||
+    !tokens.access_token ||
+    !isTokenCurrent(tokens.access_token, Date.now()) ||
+    (tokens.refresh_token !== undefined &&
+      !isTokenCurrent(tokens.refresh_token, Date.now()))
+  ) {
+    return false;
+  }
+
+  const storage = getLocalStorage();
+  if (!storage) return false;
+
+  try {
+    storage.setItem(ACCESS_TOKEN_KEY, tokens.access_token);
+    if (tokens.refresh_token) {
+      storage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
+    } else {
+      storage.removeItem(REFRESH_TOKEN_KEY);
+    }
+    storage.removeItem(LEGACY_REFRESH_TOKEN_KEY);
+
+    const storedRefreshToken = tokens.refresh_token
+      ? storage.getItem(REFRESH_TOKEN_KEY)
+      : null;
+    return (
+      storage.getItem(ACCESS_TOKEN_KEY) === tokens.access_token &&
+      storedRefreshToken === (tokens.refresh_token ?? null) &&
+      storage.getItem(LEGACY_REFRESH_TOKEN_KEY) === null
+    );
+  } catch {
+    try {
+      storage.removeItem(ACCESS_TOKEN_KEY);
+      storage.removeItem(REFRESH_TOKEN_KEY);
+      storage.removeItem(LEGACY_REFRESH_TOKEN_KEY);
+    } catch {
+      return false;
+    }
+    return false;
+  }
+}
+
+function clearSessionCookie(): void {
+  if (typeof window === "undefined") return;
+
+  try {
+    window.document.cookie =
+      "token=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;";
+  } catch {
+    return;
   }
 }
 
 export function clearSession(): void {
+  removeToken(ACCESS_TOKEN_KEY);
+  removeToken(REFRESH_TOKEN_KEY);
+  removeToken(LEGACY_REFRESH_TOKEN_KEY);
+  clearSessionCookie();
+
   if (typeof window === "undefined") return;
-  window.localStorage.removeItem(ACCESS_TOKEN_KEY);
-  window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+
+  try {
+    window.localStorage.setItem(LOGOUT_EVENT_KEY, Date.now().toString());
+  } catch {
+    return;
+  }
 }
 
-export const DEFAULT_POST_LOGIN_PATH = "/dashboard";
+export const DEFAULT_POST_LOGIN_PATH = "/";
 
 /**
  * A newline or other control character would let a value smuggle itself past
@@ -50,17 +256,36 @@ function hasControlCharacter(value: string): boolean {
  * Resolve the `?redirect=` param that FE-44's middleware appends when it
  * bounces an unauthenticated request, into a path that is safe to navigate to.
  *
- * Anything that could leave the origin falls back to the dashboard, so a
+ * Anything that could leave the origin falls back to the root landing page, so a
  * crafted `/login?redirect=…` link cannot be used as an open redirect:
  * absolute URLs carry a scheme and therefore never start with `/`, while
  * `//evil.com` and its `/\evil.com` backslash variant are treated as
  * protocol-relative by browsers and so are rejected explicitly.
  */
-export function resolvePostLoginPath(raw: string | null | undefined): string {
+export function resolvePostLoginPath(
+  raw: string | null | undefined,
+  activeLocale?: string,
+): string {
   if (!raw || !raw.startsWith("/")) return DEFAULT_POST_LOGIN_PATH;
   if (raw.startsWith("//") || raw.startsWith("/\\")) {
     return DEFAULT_POST_LOGIN_PATH;
   }
   if (hasControlCharacter(raw)) return DEFAULT_POST_LOGIN_PATH;
+
+  if (activeLocale) {
+    const localePrefix = `/${activeLocale}`;
+    const pathOnly = raw.split(/[?#]/, 1)[0];
+    if (pathOnly === localePrefix) {
+      const suffix = raw.slice(localePrefix.length);
+      if (suffix.startsWith("?") || suffix.startsWith("#")) {
+        return `/${suffix}`;
+      }
+      return DEFAULT_POST_LOGIN_PATH;
+    }
+    if (pathOnly.startsWith(`${localePrefix}/`)) {
+      return resolvePostLoginPath(raw.slice(localePrefix.length));
+    }
+  }
+
   return raw;
 }
diff --git a/frontend/lib/disputes.test.ts b/frontend/lib/disputes.test.ts
new file mode 100644
index 00000000..00e5edb3
--- /dev/null
+++ b/frontend/lib/disputes.test.ts
@@ -0,0 +1,94 @@
+import {
+  normalizeAuthUser,
+  normalizeDispute,
+  normalizeDisputeList,
+  normalizeDocumentList,
+} from "./disputes";
+
+const disputeFixture = {
+  id: "dispute-1",
+  documentId: "document-1",
+  description: "The ownership information is incorrect.",
+  reason: { id: "reason-1", name: "Incorrect information" },
+  status: "open",
+  filedBy: "user-1",
+  createdAt: "2026-01-02T12:00:00.000Z",
+};
+
+const documentFixture = {
+  id: "document-1",
+  title: "Land Title",
+  status: "verified",
+  riskScore: 12,
+  riskFlags: [],
+  createdAt: "2026-01-01T12:00:00.000Z",
+  updatedAt: "2026-01-02T12:00:00.000Z",
+};
+
+describe("dispute response boundaries", () => {
+  it("normalizes the exact dispute list envelope", () => {
+    const result = normalizeDisputeList({
+      data: [disputeFixture],
+      total: 1,
+    });
+
+    expect(result.total).toBe(1);
+    expect(result.data).toHaveLength(1);
+    expect(result.data[0]).toMatchObject({
+      id: "dispute-1",
+      status: "open",
+      reason: { id: "reason-1", name: "Incorrect information" },
+      timeline: [],
+      resolution: null,
+      resolvedAt: null,
+      document: null,
+    });
+  });
+
+  it("normalizes the exact document list envelope", () => {
+    const result = normalizeDocumentList({
+      data: [documentFixture],
+      total: 1,
+      page: 1,
+      limit: 20,
+    });
+
+    expect(result).toEqual({
+      data: [
+        {
+          id: "document-1",
+          title: "Land Title",
+          status: "verified",
+          riskScore: 12,
+        },
+      ],
+      total: 1,
+      page: 1,
+      limit: 20,
+    });
+  });
+
+  it("tolerates the detail DTO without optional enrichment", () => {
+    expect(() => normalizeDispute(disputeFixture)).not.toThrow();
+    expect(normalizeDispute(disputeFixture).document).toBeNull();
+    expect(
+      normalizeDispute({ ...disputeFixture, reason: "legacy reason" }).reason,
+    ).toBeNull();
+  });
+
+  it("rejects an array where an envelope is required", () => {
+    expect(() => normalizeDisputeList([disputeFixture])).toThrow(
+      "Invalid dispute list response",
+    );
+    expect(() =>
+      normalizeDocumentList({ documents: [documentFixture] }),
+    ).toThrow("Invalid document list response");
+  });
+
+  it("normalizes the minimal authenticated user response", () => {
+    expect(normalizeAuthUser({ id: "admin-1", role: "admin" })).toEqual({
+      id: "admin-1",
+      role: "admin",
+    });
+  });
+});
diff --git a/frontend/lib/disputes.ts b/frontend/lib/disputes.ts
new file mode 100644
index 00000000..4f5c6d60
--- /dev/null
+++ b/frontend/lib/disputes.ts
@@ -0,0 +1,218 @@
+export const disputeStatuses = [
+  "open",
+  "in_review",
+  "resolved",
+  "dismissed",
+] as const;
+
+export type DisputeStatus = (typeof disputeStatuses)[number];
+
+export interface DisputeReason {
+  id: string;
+  name: string;
+}
+
+export interface DisputeTimelineEntry {
+  status: DisputeStatus;
+  createdAt: string;
+}
+
+export interface DisputeDocument {
+  title?: string;
+  status?: string;
+  riskScore?: number;
+}
+
+export interface Dispute {
+  id: string;
+  documentId: string;
+  description: string;
+  reason: DisputeReason | null;
+  status: DisputeStatus;
+  filedBy: string;
+  createdAt: string;
+  timeline: DisputeTimelineEntry[];
+  resolution: string | null;
+  resolvedAt: string | null;
+  document: DisputeDocument | null;
+}
+
+export interface DisputeList {
+  data: Dispute[];
+  total: number;
+}
+
+export interface DisputeDocumentSummary {
+  id: string;
+  title: string;
+  status?: string;
+  riskScore?: number;
+}
+
+export interface DocumentList {
+  data: DisputeDocumentSummary[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface AuthUser {
+  id: string;
+  role: "admin" | "user";
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function requiredString(
+  record: Record<string, unknown>,
+  key: string,
+): string {
+  const value = record[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid dispute response: ${key} must be a string`);
+  }
+  return value;
+}
+
+function disputeStatus(value: unknown): DisputeStatus {
+  if (
+    typeof value === "string" &&
+    disputeStatuses.includes(value as DisputeStatus)
+  ) {
+    return value as DisputeStatus;
+  }
+  throw new Error("Invalid dispute response: unsupported status");
+}
+
+function disputeReason(value: unknown): DisputeReason | null {
+  const record = asRecord(value);
+  if (
+    !record ||
+    typeof record.id !== "string" ||
+    typeof record.name !== "string"
+  ) {
+    return null;
+  }
+  return { id: record.id, name: record.name };
+}
+
+function disputeTimeline(value: unknown): DisputeTimelineEntry[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const record = asRecord(entry);
+    if (!record) return [];
+    try {
+      return [
+        {
+          status: disputeStatus(record.status),
+          createdAt: requiredString(record, "createdAt"),
+        },
+      ];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function disputeDocument(value: unknown): DisputeDocument | null {
+  const record = asRecord(value);
+  if (!record) return null;
+  return {
+    title: typeof record.title === "string" ? record.title : undefined,
+    status: typeof record.status === "string" ? record.status : undefined,
+    riskScore:
+      typeof record.riskScore === "number" ? record.riskScore : undefined,
+  };
+}
+
+export function normalizeDispute(value: unknown): Dispute {
+  const record = asRecord(value);
+  if (!record) throw new Error("Invalid dispute response");
+
+  return {
+    id: requiredString(record, "id"),
+    documentId: requiredString(record, "documentId"),
+    description:
+      typeof record.description === "string" ? record.description : "",
+    reason: disputeReason(record.reason),
+    status: disputeStatus(record.status),
+    filedBy: requiredString(record, "filedBy"),
+    createdAt: requiredString(record, "createdAt"),
+    timeline: disputeTimeline(record.timeline),
+    resolution:
+      typeof record.resolution === "string" ? record.resolution : null,
+    resolvedAt:
+      typeof record.resolvedAt === "string" ? record.resolvedAt : null,
+    document: disputeDocument(record.document),
+  };
+}
+
+export function normalizeDisputeList(value: unknown): DisputeList {
+  const record = asRecord(value);
+  if (!record || !Array.isArray(record.data)) {
+    throw new Error("Invalid dispute list response");
+  }
+
+  const data = record.data.map(normalizeDispute);
+  return {
+    data,
+    total: typeof record.total === "number" ? record.total : data.length,
+  };
+}
+
+export function normalizeDocumentList(value: unknown): DocumentList {
+  const record = asRecord(value);
+  if (!record || !Array.isArray(record.data)) {
+    throw new Error("Invalid document list response");
+  }
+
+  const data = record.data.flatMap((value) => {
+    const document = asRecord(value);
+    if (
+      !document ||
+      typeof document.id !== "string" ||
+      typeof document.title !== "string"
+    ) {
+      return [];
+    }
+    return [
+      {
+        id: document.id,
+        title: document.title,
+        status:
+          typeof document.status === "string" ? document.status : undefined,
+        riskScore:
+          typeof document.riskScore === "number"
+            ? document.riskScore
+            : undefined,
+      },
+    ];
+  });
+
+  return {
+    data,
+    total: typeof record.total === "number" ? record.total : data.length,
+    page: typeof record.page === "number" ? record.page : 1,
+    limit: typeof record.limit === "number" ? record.limit : data.length,
+  };
+}
+
+export function normalizeAuthUser(value: unknown): AuthUser {
+  const record = asRecord(value);
+  if (
+    !record ||
+    typeof record.id !== "string" ||
+    (record.role !== "admin" && record.role !== "user")
+  ) {
+    throw new Error("Invalid authenticated user response");
+  }
+  return { id: record.id, role: record.role };
+}
+
+export function disputeStatusLabel(status: DisputeStatus): string {
+  return status.replace("_", " ");
+}
diff --git a/frontend/lib/document-mapper.test.ts b/frontend/lib/document-mapper.test.ts
new file mode 100644
index 00000000..e7c6594a
--- /dev/null
+++ b/frontend/lib/document-mapper.test.ts
@@ -0,0 +1,36 @@
+const mockDomPurifySanitize = jest.fn();
+
+jest.mock("dompurify", () => ({
+  __esModule: true,
+  default: { sanitize: mockDomPurifySanitize },
+}));
+
+import { toPublicDocumentView } from "./document-mapper";
+
+describe("toPublicDocumentView", () => {
+  it("maps API records without loading the browser sanitizer", () => {
+    const rawDocument = {
+      id: "doc-1",
+      documentHash: "0x123",
+      isVerified: "false",
+      ownerSecret: "private",
+    };
+    const result = toPublicDocumentView(rawDocument);
+
+    expect(result.isVerified).toBe(false);
+    expect(result.documentHash).toBe("0x123");
+    expect((result as { ownerSecret?: string }).ownerSecret).toBeUndefined();
+    expect(mockDomPurifySanitize).not.toHaveBeenCalled();
+  });
+
+  it("accepts only explicit truthy serialized values", () => {
+    expect(
+      toPublicDocumentView({ id: "1", documentHash: "0x1", isVerified: "true" })
+        .isVerified,
+    ).toBe(true);
+    expect(
+      toPublicDocumentView({ id: "2", documentHash: "0x2", isVerified: 1 })
+        .isVerified,
+    ).toBe(true);
+  });
+});
diff --git a/frontend/lib/document-mapper.ts b/frontend/lib/document-mapper.ts
new file mode 100644
index 00000000..be66f178
--- /dev/null
+++ b/frontend/lib/document-mapper.ts
@@ -0,0 +1,36 @@
+/**
+ * Maps untrusted API document records onto the fields intentionally exposed
+ * to the UI. This module has no DOM or sanitizer dependency.
+ */
+
+export interface PublicDocumentView {
+  id: string;
+  documentHash: string;
+  isVerified: boolean;
+  timestamp: string;
+}
+
+interface RawDocument {
+  id: string;
+  documentHash: string;
+  isVerified: boolean | string | number;
+  timestamp?: string;
+}
+
+function toVerified(value: RawDocument["isVerified"]): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value === 1;
+  if (typeof value === "string") {
+    return value.toLowerCase() === "true" || value === "1";
+  }
+  return false;
+}
+
+export function toPublicDocumentView(doc: RawDocument): PublicDocumentView {
+  return {
+    id: doc.id,
+    documentHash: doc.documentHash,
+    isVerified: toVerified(doc.isVerified),
+    timestamp: doc.timestamp || new Date().toISOString(),
+  };
+}
diff --git a/frontend/lib/document-sanitizer.test.ts b/frontend/lib/document-sanitizer.test.ts
new file mode 100644
index 00000000..61771638
--- /dev/null
+++ b/frontend/lib/document-sanitizer.test.ts
@@ -0,0 +1,83 @@
+import { sanitizeSvg } from "./document-sanitizer";
+
+describe("sanitizeSvg", () => {
+  it("removes active content and unsafe external references", () => {
+    const sanitized = sanitizeSvg(`
+      <svg xmlns="http://www.w3.org/2000/svg" onload="alert(1)">
+        <script>alert(1)</script>
+        <foreignObject><div xmlns="http://www.w3.org/1999/xhtml">html</div></foreignObject>
+        <animate attributeName="href" values="javascript:alert(1)" />
+        <rect width="10" height="10" onclick="alert(1)" fill="url(https://attacker.example/paint)" />
+        <rect width="10" height="10" fill="u\\72l(https://attacker.example/paint)" />
+        <image href="data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=" />
+        <a href="javascript:alert(1)">link</a>
+      </svg>
+    `);
+
+    expect(sanitized).toContain("<rect");
+    expect(sanitized).not.toMatch(
+      /script|foreignObject|animate|onload|onclick|javascript:|data:|attacker\.example/i,
+    );
+  });
+
+  it("preserves ordinary SVG attributes, local references, and CSS URLs", () => {
+    const sanitized = sanitizeSvg(`
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="120"
+        height="40"
+        viewBox="0 0 120 40"
+        preserveAspectRatio="xMidYMid meet"
+        aria-labelledby="title"
+      >
+        <title id="title">Parcel A &amp; B</title>
+        <defs>
+          <linearGradient id="paint">
+            <stop offset="0" stop-color="#ffffff" />
+          </linearGradient>
+        </defs>
+        <path id="shape" d="M0 0 L120 40" fill="url(#paint)" stroke="#123456" stroke-width="2" />
+        <text aria-label="https://maps.example/Parcel"><textPath href="#shape">Parcel A</textPath></text>
+        <text aria-label="url(https://maps.example/reference)" data-reference="url(https://maps.example/data)">Reference text</text>
+      </svg>
+    `);
+
+    expect(sanitized).toContain('viewBox="0 0 120 40"');
+    expect(sanitized).toContain('preserveAspectRatio="xMidYMid meet"');
+    expect(sanitized).toContain('d="M0 0 L120 40"');
+    expect(sanitized).toContain('fill="url(#paint)"');
+    expect(sanitized).toContain('stroke="#123456"');
+    expect(sanitized).toContain('href="#shape"');
+    expect(sanitized).toContain('aria-label="https://maps.example/Parcel"');
+    expect(sanitized).toContain(
+      'aria-label="url(https://maps.example/reference)"',
+    );
+    expect(sanitized).toContain(
+      'data-reference="url(https://maps.example/data)"',
+    );
+  });
+
+  it("rejects DTD and external entity declarations", () => {
+    expect(() =>
+      sanitizeSvg(`
+        <!DOCTYPE svg [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+        <svg xmlns="http://www.w3.org/2000/svg"><text>&xxe;</text></svg>
+      `),
+    ).toThrow("Unsafe SVG declaration");
+  });
+
+  it("serializes predefined XML entities without custom expansion", () => {
+    const sanitized = sanitizeSvg(
+      '<svg xmlns="http://www.w3.org/2000/svg"><text>A &amp; B</text></svg>',
+    );
+
+    expect(sanitized).toContain("A &amp; B");
+    expect(sanitized).not.toContain("A & B");
+  });
+
+  it("rejects non-SVG XML roots", () => {
+    expect(() =>
+      sanitizeSvg('<html xmlns="http://www.w3.org/1999/xhtml"></html>'),
+    ).toThrow("Invalid SVG document");
+  });
+});
diff --git a/frontend/lib/document-sanitizer.ts b/frontend/lib/document-sanitizer.ts
index 565dd9df..6f9b941f 100644
--- a/frontend/lib/document-sanitizer.ts
+++ b/frontend/lib/document-sanitizer.ts
@@ -1,22 +1,246 @@
-export interface PublicDocumentView {
-  id: string;
-  documentHash: string;
-  isVerified: boolean;
-  timestamp: string;
+"use client";
+
+import DOMPurify from "dompurify";
+
+/**
+ * Browser-only SVG sanitization for untrusted upload markup. This module owns
+ * active-content removal; scalar values and API response mapping live in
+ * separate modules.
+ */
+
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+const XLINK_NAMESPACE = "http://www.w3.org/1999/xlink";
+const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+
+const FORBIDDEN_SVG_ELEMENTS = new Set([
+  "script",
+  "foreignobject",
+  "iframe",
+  "object",
+  "embed",
+  "style",
+  "animate",
+  "animatemotion",
+  "animatetransform",
+  "set",
+  "discard",
+  "audio",
+  "video",
+  "handler",
+  "listener",
+  "link",
+  "meta",
+  "image",
+  "feimage",
+  "font-face-uri",
+  "use",
+  "a",
+]);
+
+const ALLOWED_SVG_ELEMENTS = new Set([
+  "svg",
+  "g",
+  "defs",
+  "title",
+  "desc",
+  "path",
+  "rect",
+  "circle",
+  "ellipse",
+  "line",
+  "polyline",
+  "polygon",
+  "text",
+  "tspan",
+  "textpath",
+  "lineargradient",
+  "radialgradient",
+  "stop",
+  "clippath",
+  "pattern",
+  "marker",
+  "symbol",
+  "view",
+  "mask",
+  "filter",
+  "fegaussianblur",
+  "feoffset",
+  "feblend",
+  "fecolormatrix",
+  "fecomponenttransfer",
+  "fecomposite",
+  "fediffuselighting",
+  "feconvolvematrix",
+  "fedisplacementmap",
+  "fedropshadow",
+  "feflood",
+  "fefunca",
+  "fefuncb",
+  "fefuncg",
+  "fefuncr",
+  "femerge",
+  "femergenode",
+  "femorphology",
+  "fepointlight",
+  "fespecularlighting",
+  "fespotlight",
+  "fetile",
+  "feturbulence",
+  "switch",
+  "font",
+  "font-face",
+  "font-face-format",
+  "font-face-name",
+  "glyph",
+  "missing-glyph",
+  "hkern",
+  "vkern",
+  "tref",
+  "cursor",
+]);
+
+const URL_ATTRIBUTES = new Set([
+  "href",
+  "src",
+  "srcset",
+  "action",
+  "formaction",
+  "poster",
+  "background",
+  "codebase",
+  "cite",
+  "icon",
+  "manifest",
+  "profile",
+  "usemap",
+  "ping",
+  "longdesc",
+]);
+
+const CSS_URL_ATTRIBUTES = new Set([
+  "background-image",
+  "clip-path",
+  "color-profile",
+  "cursor",
+  "fill",
+  "filter",
+  "marker-end",
+  "marker-mid",
+  "marker-start",
+  "mask",
+  "stroke",
+]);
+
+function parseSvg(markup: string): SVGSVGElement {
+  const document = new window.DOMParser().parseFromString(
+    markup,
+    "image/svg+xml",
+  );
+  const root = document.documentElement;
+
+  if (
+    document.querySelector("parsererror") ||
+    root.localName.toLowerCase() !== "svg" ||
+    root.namespaceURI !== SVG_NAMESPACE
+  ) {
+    throw new Error("Invalid SVG document");
+  }
+
+  return root as SVGSVGElement;
 }
 
-interface RawDocument {
-  id: string;
-  documentHash: string;
-  isVerified: boolean | string | number;
-  timestamp?: string;
+function isLocalReference(value: string): boolean {
+  return /^#[A-Za-z0-9_.:-]+$/.test(value);
 }
 
-export function toPublicDocumentView(doc: RawDocument): PublicDocumentView {
-  return {
-    id: doc.id,
-    documentHash: doc.documentHash,
-    isVerified: Boolean(doc.isVerified),
-    timestamp: doc.timestamp || new Date().toISOString(),
-  };
+function isLocalCssReference(value: string): boolean {
+  return /^url\(\s*#[A-Za-z0-9_.:-]+\s*\)$/i.test(value.trim());
+}
+
+/** Sanitizes untrusted SVG markup and throws when no DOM sanitizer is available. */
+export function sanitizeSvg(markup: string): string {
+  if (
+    typeof window === "undefined" ||
+    !DOMPurify.isSupported ||
+    typeof window.DOMParser === "undefined" ||
+    typeof window.XMLSerializer === "undefined"
+  ) {
+    throw new Error("SVG sanitization is unavailable");
+  }
+
+  if (
+    /<!\s*(?:DOCTYPE|ENTITY)\b/i.test(markup) ||
+    /<\?(?!xml(?:\s|\?))/i.test(markup)
+  ) {
+    throw new Error("Unsafe SVG declaration");
+  }
+
+  const purified = String(
+    DOMPurify.sanitize(markup, {
+      USE_PROFILES: { svg: true, svgFilters: true },
+      FORBID_TAGS: Array.from(FORBIDDEN_SVG_ELEMENTS),
+      FORBID_ATTR: ["style"],
+      ALLOW_ARIA_ATTR: true,
+      ALLOW_UNKNOWN_PROTOCOLS: false,
+    }),
+  );
+  const root = parseSvg(purified);
+
+  for (const element of [root, ...Array.from(root.querySelectorAll("*"))]) {
+    if (
+      element.namespaceURI !== SVG_NAMESPACE ||
+      FORBIDDEN_SVG_ELEMENTS.has(element.localName.toLowerCase()) ||
+      !ALLOWED_SVG_ELEMENTS.has(element.localName.toLowerCase())
+    ) {
+      element.remove();
+      continue;
+    }
+
+    for (const attribute of Array.from(element.attributes)) {
+      const name = attribute.name.toLowerCase();
+      const localName = attribute.localName.toLowerCase();
+      const value = attribute.value;
+
+      if (name === "xmlns" || name.startsWith("xmlns:")) {
+        const isKnownNamespace =
+          value === SVG_NAMESPACE || value === XLINK_NAMESPACE;
+        if (!isKnownNamespace) element.removeAttributeNode(attribute);
+        continue;
+      }
+
+      if (
+        name.startsWith("on") ||
+        name === "style" ||
+        name === "xml:base" ||
+        (attribute.namespaceURI === XLINK_NAMESPACE && localName !== "href") ||
+        (attribute.namespaceURI === XML_NAMESPACE &&
+          localName !== "space" &&
+          localName !== "lang") ||
+        (attribute.namespaceURI !== null &&
+          attribute.namespaceURI !== XLINK_NAMESPACE &&
+          attribute.namespaceURI !== XML_NAMESPACE)
+      ) {
+        element.removeAttributeNode(attribute);
+        continue;
+      }
+
+      if (URL_ATTRIBUTES.has(localName) && !isLocalReference(value)) {
+        element.removeAttributeNode(attribute);
+        continue;
+      }
+
+      if (CSS_URL_ATTRIBUTES.has(localName)) {
+        const normalizedCssValue = value.replace(/\/\*[\s\S]*?\*\//g, "");
+        if (
+          (normalizedCssValue.includes("\\") ||
+            /\b(?:url|var|attr)\s*\(/i.test(normalizedCssValue)) &&
+          !isLocalCssReference(normalizedCssValue)
+        ) {
+          element.removeAttributeNode(attribute);
+        }
+      }
+    }
+  }
+
+  return new window.XMLSerializer().serializeToString(root);
 }
diff --git a/frontend/lib/sanitize.ts b/frontend/lib/sanitize.ts
index 1908af95..83a7dcc5 100644
--- a/frontend/lib/sanitize.ts
+++ b/frontend/lib/sanitize.ts
@@ -1,18 +1,27 @@
+/**
+ * Sanitizers for scalar values rendered by the UI. `sanitizeText` is for
+ * text-only contexts, and `isSafeUrl` is for link targets. Neither function
+ * parses or sanitizes HTML or SVG markup.
+ */
+
 export function sanitizeText(input: string): string {
-  if (!input) return '';
+  if (!input) return "";
   return input
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#x27;');
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#x27;");
 }
 
+/**
+ * Returns true for HTTP(S), mailto, and relative inputs resolved against localhost.
+ */
 export function isSafeUrl(url: string): boolean {
   if (!url) return false;
   try {
-    const parsed = new URL(url, 'http://localhost');
-    return ['http:', 'https:', 'mailto:'].includes(parsed.protocol);
+    const parsed = new URL(url, "http://localhost");
+    return ["http:", "https:", "mailto:"].includes(parsed.protocol);
   } catch {
     return false;
   }
diff --git a/frontend/lib/session-expiry-warning.ts b/frontend/lib/session-expiry-warning.ts
index b62dc203..9d046502 100644
--- a/frontend/lib/session-expiry-warning.ts
+++ b/frontend/lib/session-expiry-warning.ts
@@ -1,22 +1,10 @@
 "use client";
 
 import { useEffect, useRef, useCallback } from "react";
+import { getJwtExpiration } from "./auth-session";
 
 const ACCESS_TOKEN_KEY = "auth-token";
 
-// ── JWT expiry helper ───────────────────────────────────────────────────────
-
-function getTokenExpiryMs(token: string): number | null {
-  try {
-    const payload = JSON.parse(atob(token.split(".")[1]));
-    if (!payload.exp) return null;
-    // exp is in seconds; return ms until expiry
-    return payload.exp * 1000 - Date.now();
-  } catch {
-    return null;
-  }
-}
-
 // ── Cross-tab logout sync ───────────────────────────────────────────────────
 
 /**
@@ -78,8 +66,10 @@ export function useSessionExpiryWarning({
       const token = window.localStorage.getItem(ACCESS_TOKEN_KEY);
       if (!token) return;
 
-      const remainingMs = getTokenExpiryMs(token);
-      if (remainingMs === null || remainingMs <= 0) return;
+      const expiration = getJwtExpiration(token);
+      if (expiration === null) return;
+      const remainingMs = expiration * 1000 - Date.now();
+      if (remainingMs <= 0) return;
 
       const delayMs = Math.max(remainingMs - WARNING_BEFORE_MS, 0);
 
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 1abce39b..2c04edfe 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -14,6 +14,7 @@
         "@types/leaflet.markercluster": "^1.5.6",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
+        "dompurify": "^3.4.1",
         "jspdf": "^3.0.1",
         "leaflet": "^1.9.4",
         "leaflet.markercluster": "^1.5.3",
@@ -5880,7 +5881,6 @@
       "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.1.tgz",
       "integrity": "sha512-JahakDAIg1gyOm7dlgWSDjV4n7Ip2PKR55NIT6jrMfIgLFgWo81vdr1/QGqWtFNRqXP9UV71oVePtjqS2ebnPw==",
       "license": "(MPL-2.0 OR Apache-2.0)",
-      "optional": true,
       "optionalDependencies": {
         "@types/trusted-types": "^2.0.7"
       }
diff --git a/frontend/package.json b/frontend/package.json
index a0f9175d..756a4bba 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -24,6 +24,7 @@
     "@types/leaflet.markercluster": "^1.5.6",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "dompurify": "^3.4.1",
     "jspdf": "^3.0.1",
     "leaflet": "^1.9.4",
     "leaflet.markercluster": "^1.5.3",
diff --git a/frontend/test-utils/LoginForm.test.tsx b/frontend/test-utils/LoginForm.test.tsx
index 23393f2b..98b2c587 100644
--- a/frontend/test-utils/LoginForm.test.tsx
+++ b/frontend/test-utils/LoginForm.test.tsx
@@ -32,11 +32,12 @@ jest.mock("@/lib/api-client", () => ({
       this.messageKey = messageKey;
     }
   },
-  apiRequest: (...args: unknown[]) => mockApiRequest(...args),
+  request: (...args: unknown[]) => mockApiRequest(...args),
+  getApiUrl: (path: string) => `http://localhost:3001/api/v1/${path}`,
 }));
 
 jest.mock("@/lib/auth-session", () => ({
-  resolvePostLoginPath: () => "/dashboard",
+  resolvePostLoginPath: () => "/",
   storeSession: (...args: unknown[]) => mockStoreSession(...args),
 }));
 
@@ -52,7 +53,8 @@ describe("LoginForm", () => {
   beforeEach(() => {
     mockReplace.mockClear();
     mockApiRequest.mockReset();
-    mockStoreSession.mockClear();
+    mockStoreSession.mockReset();
+    mockStoreSession.mockReturnValue(true);
     mockSearchParams.delete("redirect");
     mockSearchParams.delete("reset");
   });
@@ -62,11 +64,11 @@ describe("LoginForm", () => {
 
     expect(screen.getByRole("link", { name: "Continue with Google" })).toHaveAttribute(
       "href",
-      "http://localhost:3001/api/auth/google",
+      "http://localhost:3001/api/v1/auth/google",
     );
     expect(screen.getByRole("link", { name: "Continue with GitHub" })).toHaveAttribute(
       "href",
-      "http://localhost:3001/api/auth/github",
+      "http://localhost:3001/api/v1/auth/github",
     );
   });
 
@@ -93,11 +95,15 @@ describe("LoginForm", () => {
 
     await waitFor(() => expect(mockApiRequest).toHaveBeenCalledTimes(1));
     expect(mockApiRequest).toHaveBeenCalledWith(
-      "http://localhost:3001/api/auth/login",
-      expect.objectContaining({ method: "POST", credentials: "include" }),
+      "http://localhost:3001/api/v1/auth/login",
+      expect.objectContaining({
+        method: "POST",
+        credentials: "include",
+        anonymous: true,
+      }),
     );
     expect(mockStoreSession).toHaveBeenCalledWith({ access_token: "access-token" });
-    expect(mockReplace).toHaveBeenCalledWith("/dashboard");
+    expect(mockReplace).toHaveBeenCalledWith("/");
   });
 
   it("disables submission and shows the loading label while the request is pending", async () => {
@@ -115,7 +121,7 @@ describe("LoginForm", () => {
 
     expect(await screen.findByRole("button", { name: "Signing in…" })).toBeDisabled();
     resolveRequest({ access_token: "access-token" });
-    await waitFor(() => expect(mockReplace).toHaveBeenCalledWith("/dashboard"));
+    await waitFor(() => expect(mockReplace).toHaveBeenCalledWith("/"));
   });
 
   it("renders an inline error when credentials are rejected", async () => {
diff --git a/frontend/test-utils/admin-users-mutations.test.tsx b/frontend/test-utils/admin-users-mutations.test.tsx
new file mode 100644
index 00000000..ce9a0e44
--- /dev/null
+++ b/frontend/test-utils/admin-users-mutations.test.tsx
@@ -0,0 +1,94 @@
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import AdminUsersPage from "@/app/[locale]/(protected)/admin/users/page";
+
+const mockRequest = jest.fn();
+const mockRequestRaw = jest.fn();
+
+jest.mock("@/lib/api-client", () => ({
+  ApiError: class ApiError extends Error {},
+  getApiUrl: (path: string) => `http://localhost:3001/api/v1/${path}`,
+  request: (...args: unknown[]) => mockRequest(...args),
+  requestRaw: (...args: unknown[]) => mockRequestRaw(...args),
+}));
+
+jest.mock("@/lib/auth-session", () => ({
+  clearSession: jest.fn(),
+  getJwtClaims: () => ({ role: "admin", sub: "admin-1" }),
+  getValidAccessToken: () => "admin-access-token",
+}));
+
+const users = [
+  {
+    id: "user-1",
+    fullName: "Alice Example",
+    email: "alice@example.com",
+    role: "user",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    lastLoginAt: null,
+    status: "active",
+  },
+  {
+    id: "user-2",
+    fullName: "Bob Example",
+    email: "bob@example.com",
+    role: "user",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    lastLoginAt: null,
+    status: "active",
+  },
+];
+
+function renderPage() {
+  return render(<AdminUsersPage />);
+}
+
+async function selectAliceForDeletion() {
+  fireEvent.click(await screen.findByRole("checkbox", { name: "Select Alice Example" }));
+  fireEvent.click(screen.getByRole("button", { name: "Delete 1 selected" }));
+}
+
+describe("AdminUsersPage bulk deletion", () => {
+  beforeEach(() => {
+    mockRequest.mockReset();
+    mockRequestRaw.mockReset();
+    mockRequest.mockResolvedValue({
+      data: users,
+      total: users.length,
+      page: 1,
+      pageSize: 20,
+    });
+    jest.spyOn(window, "confirm").mockReturnValue(true);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("keeps selected users when a managed deletion fails", async () => {
+    mockRequestRaw.mockRejectedValue(new Error("delete failed"));
+    renderPage();
+
+    await selectAliceForDeletion();
+
+    await waitFor(() => expect(mockRequestRaw).toHaveBeenCalledTimes(1));
+    expect(mockRequestRaw).toHaveBeenCalledWith(
+      "http://localhost:3001/api/v1/users/user-1",
+      { method: "DELETE" },
+    );
+    expect(screen.getByText("alice@example.com")).toBeInTheDocument();
+    expect(screen.getByRole("alert")).toHaveTextContent("delete failed");
+  });
+
+  it("removes selected users only after all managed deletions succeed", async () => {
+    mockRequestRaw.mockResolvedValue({} as Response);
+    renderPage();
+
+    await selectAliceForDeletion();
+
+    await waitFor(() =>
+      expect(screen.queryByText("alice@example.com")).not.toBeInTheDocument(),
+    );
+    expect(screen.getByText("bob@example.com")).toBeInTheDocument();
+  });
+});
diff --git a/frontend/test-utils/api-client.test.ts b/frontend/test-utils/api-client.test.ts
index a490dd64..093329a0 100644
--- a/frontend/test-utils/api-client.test.ts
+++ b/frontend/test-utils/api-client.test.ts
@@ -1,6 +1,14 @@
-import { ApiError, clearSession, request } from "@/lib/api-client";
-
-const API_BASE = "http://localhost:3001";
+import {
+  clearSession,
+  ensureValidSession,
+  getApiUrl,
+  logoutSession,
+  request,
+  requestBlob,
+  requestRaw,
+} from "@/lib/api-client";
+
+const API_V1_BASE = "http://localhost:3001/api/v1";
 
 // ── localStorage mock ───────────────────────────────────────────────────────
 
@@ -30,13 +38,38 @@ let lsMock: ReturnType<typeof createLocalStorageMock>;
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
+function encodeJwtPart(value: object): string {
+  return btoa(JSON.stringify(value))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+function createJwt(
+  expiresAt = Math.floor(Date.now() / 1000) + 3600,
+): string {
+  const header = encodeJwtPart({ alg: "HS256", typ: "JWT" });
+  const payload = encodeJwtPart({
+    sub: "user-1",
+    email: "user@example.com",
+    role: "user",
+    exp: expiresAt,
+  });
+  return `${header}.${payload}.signature`;
+}
+
+function createExpiredJwt(): string {
+  return createJwt(Math.floor(Date.now() / 1000) - 1);
+}
+
 function setTokens(access: string, refresh?: string) {
   lsMock.setItem("auth-token", access);
-  if (refresh) lsMock.setItem("refresh-token", refresh);
+  if (refresh) lsMock.setItem("auth-refresh-token", refresh);
 }
 
 function clearTokens() {
   lsMock.removeItem("auth-token");
+  lsMock.removeItem("auth-refresh-token");
   lsMock.removeItem("refresh-token");
 }
 
@@ -103,6 +136,8 @@ beforeEach(() => {
   locationHref = "";
   Object.defineProperty(window, "location", {
     value: {
+      pathname: "/dashboard",
+      search: "",
       get href() {
         return locationHref;
       },
@@ -121,27 +156,130 @@ afterEach(() => {
 
 // ── Tests ───────────────────────────────────────────────────────────────────
 
+describe("canonical API authentication", () => {
+  it("builds canonical versioned URLs from the configured origin", () => {
+    expect(getApiUrl("auth/login")).toBe(`${API_V1_BASE}/auth/login`);
+    expect(getApiUrl("documents/upload")).toBe(
+      `${API_V1_BASE}/documents/upload`,
+    );
+    expect(getApiUrl("/api/documents")).toBe(`${API_V1_BASE}/documents`);
+  });
+
+  it("rejects malformed, external, and canonical-root-escaping API URLs", () => {
+    expect(() => getApiUrl("auth\\login")).toThrow();
+    expect(() => getApiUrl("\nauth/login")).toThrow();
+    expect(() => getApiUrl("auth%0d%0aX-Injected:%20yes")).toThrow();
+    expect(() => getApiUrl("../outside")).toThrow();
+    expect(() => getApiUrl("https://evil.example/attack")).toThrow();
+  });
+
+  it("never forwards managed or caller bearer tokens to external origins", async () => {
+    mockFetch.mockResolvedValueOnce(mockResponse({ external: true }));
+    setTokens(createJwt(), createJwt());
+
+    await request("https://attacker.example/collect", {
+      headers: { Authorization: "Bearer caller-token" },
+    });
+
+    const [, options] = mockFetch.mock.calls[0];
+    expect(options.headers.get("Authorization")).toBeNull();
+    expect(lsMock.getItem("auth-token")).not.toBeNull();
+  });
+
+  it("proactively establishes a session from an expired access token", async () => {
+    const refreshedToken = createJwt();
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ access_token: refreshedToken }),
+    );
+    setTokens(createExpiredJwt(), createJwt());
+
+    await expect(ensureValidSession()).resolves.toBe(refreshedToken);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch.mock.calls[0][0]).toBe(`${API_V1_BASE}/auth/refresh`);
+  });
+
+  it.each([429, 503])(
+    "preserves the local session when refresh is temporarily unavailable",
+    async (status) => {
+      mockFetch.mockResolvedValueOnce(
+        mockResponse({ message: "Unavailable" }, { status }),
+      );
+      setTokens(createExpiredJwt(), createJwt());
+
+      await expect(ensureValidSession()).rejects.toMatchObject({ status });
+      expect(lsMock.getItem("auth-token")).not.toBeNull();
+      expect(lsMock.getItem("auth-refresh-token")).not.toBeNull();
+    },
+  );
+
+  it("preserves the local session when a refresh success is malformed", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ access_token: "not-a-valid-jwt" }),
+    );
+    setTokens(createExpiredJwt(), createJwt());
+
+    await expect(ensureValidSession()).rejects.toMatchObject({
+      status: 502,
+      kind: "server",
+    });
+    expect(lsMock.getItem("auth-token")).not.toBeNull();
+    expect(lsMock.getItem("auth-refresh-token")).not.toBeNull();
+  });
+
+  it("revokes a valid access token and clears every stored credential", async () => {
+    const accessToken = createJwt();
+    setTokens(accessToken, createJwt());
+    mockFetch.mockResolvedValueOnce(mockResponse({ message: "Logged out" }));
+
+    await expect(logoutSession()).resolves.toBe(true);
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch).toHaveBeenCalledWith(
+      `${API_V1_BASE}/auth/logout`,
+      expect.objectContaining({ method: "POST", credentials: "omit" }),
+    );
+    expect(mockFetch.mock.calls[0][1].headers.get("Authorization")).toBe(
+      `Bearer ${accessToken}`,
+    );
+    expect(lsMock.getItem("auth-token")).toBeNull();
+    expect(lsMock.getItem("auth-refresh-token")).toBeNull();
+  });
+
+  it("clears local credentials when logout revocation is temporarily unavailable", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ message: "Unavailable" }, { status: 503 }),
+    );
+    setTokens(createJwt(), createJwt());
+
+    await expect(logoutSession()).resolves.toBe(false);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(lsMock.getItem("auth-token")).toBeNull();
+    expect(lsMock.getItem("auth-refresh-token")).toBeNull();
+  });
+});
+
 describe("request()", () => {
   // ── Success path ────────────────────────────────────────────────────────
 
   it("attaches JWT and returns parsed JSON on success", async () => {
     mockFetch.mockResolvedValueOnce(mockResponse({ ok: true }));
 
-    setTokens("my-jwt-token");
-    const data = await request<{ ok: boolean }>("/api/test");
+    const accessToken = createJwt();
+    setTokens(accessToken);
+    const data = await request<{ ok: boolean }>("/test");
 
     expect(data).toEqual({ ok: true });
     expect(mockFetch).toHaveBeenCalledTimes(1);
     const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toBe(`${API_BASE}/api/test`);
-    expect(opts.headers.get("Authorization")).toBe("Bearer my-jwt-token");
+    expect(url).toBe(`${API_V1_BASE}/test`);
+    expect(opts.headers.get("Authorization")).toBe(`Bearer ${accessToken}`);
   });
 
   it("sends no Authorization header when anonymous is true", async () => {
     mockFetch.mockResolvedValueOnce(mockResponse({ public: true }));
 
-    setTokens("should-not-be-sent");
-    const data = await request<{ public: boolean }>("/api/public", {
+    setTokens(createJwt());
+    const data = await request<{ public: boolean }>("/public", {
       anonymous: true,
     });
 
@@ -155,9 +293,9 @@ describe("request()", () => {
       mockResponse({ message: "Something broke" }, { status: 422 }),
     );
 
-    setTokens("token");
+    setTokens(createJwt());
 
-    await expect(request("/api/fail")).rejects.toMatchObject({
+    await expect(request("/fail")).rejects.toMatchObject({
       name: "ApiError",
       status: 422,
       kind: "validation",
@@ -168,9 +306,9 @@ describe("request()", () => {
   it("throws ApiError with network kind on fetch failure", async () => {
     mockFetch.mockRejectedValueOnce(new Error("Network error"));
 
-    setTokens("token");
+    setTokens(createJwt());
 
-    await expect(request("/api/network-fail")).rejects.toMatchObject({
+    await expect(request("/network-fail")).rejects.toMatchObject({
       name: "ApiError",
       status: null,
       kind: "network",
@@ -180,16 +318,45 @@ describe("request()", () => {
   it("returns undefined for 204 No Content", async () => {
     mockFetch.mockResolvedValueOnce(mockResponse(null, { status: 204 }));
 
-    setTokens("token");
-    const result = await request("/api/resource/1", { method: "DELETE" });
+    setTokens(createJwt());
+    const result = await request("/resource/1", { method: "DELETE" });
     expect(result).toBeUndefined();
   });
 
+  it("returns the raw response for successful non-JSON mutations", async () => {
+    const response = mockResponse(null, { status: 204 });
+    mockFetch.mockResolvedValueOnce(response);
+    setTokens(createJwt());
+
+    await expect(requestRaw("/resource/1", { method: "DELETE" })).resolves.toBe(
+      response,
+    );
+  });
+
+  it("rejects raw mutations on non-2xx responses", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ message: "Delete failed" }, { status: 409 }),
+    );
+    setTokens(createJwt());
+
+    await expect(
+      requestRaw("/resource/1", { method: "DELETE" }),
+    ).rejects.toMatchObject({ name: "ApiError", status: 409 });
+  });
+
+  it("returns a blob for managed binary downloads", async () => {
+    const response = mockResponse({ export: true });
+    mockFetch.mockResolvedValueOnce(response);
+    setTokens(createJwt());
+
+    await expect(requestBlob("/users/me/export")).resolves.toBeInstanceOf(Blob);
+  });
+
   it("serializes plain-object bodies to JSON", async () => {
     mockFetch.mockResolvedValueOnce(mockResponse({ id: "1" }));
 
-    setTokens("token");
-    await request("/api/data", {
+    setTokens(createJwt());
+    await request("/data", {
       method: "POST",
       body: { title: "Test" },
     });
@@ -202,33 +369,29 @@ describe("request()", () => {
   // ── 401 → refresh success → retry success ──────────────────────────────
 
   it("refreshes token on 401 and retries the original request", async () => {
-    // First call: 401
+    const accessToken = createJwt();
+    const refreshedToken = createJwt();
     mockFetch.mockResolvedValueOnce(
       mockResponse({ message: "Unauthorized" }, { status: 401 }),
     );
-    // Refresh call: success
     mockFetch.mockResolvedValueOnce(
-      mockResponse({ access_token: "new-jwt-token" }),
+      mockResponse({ access_token: refreshedToken }),
     );
-    // Retry call: success
     mockFetch.mockResolvedValueOnce(mockResponse({ data: "fresh" }));
 
-    setTokens("expired-jwt", "valid-refresh-token");
-    const data = await request<{ data: string }>("/api/data");
+    setTokens(accessToken, createJwt());
+    const data = await request<{ data: string }>("/data");
 
     expect(data).toEqual({ data: "fresh" });
     expect(mockFetch).toHaveBeenCalledTimes(3);
-
-    // First call had old token
+    expect(mockFetch.mock.calls[1][0]).toBe(`${API_V1_BASE}/auth/refresh`);
     expect(mockFetch.mock.calls[0][1].headers.get("Authorization")).toBe(
-      "Bearer expired-jwt",
+      `Bearer ${accessToken}`,
     );
-    // Retry had new token
     expect(mockFetch.mock.calls[2][1].headers.get("Authorization")).toBe(
-      "Bearer new-jwt-token",
+      `Bearer ${refreshedToken}`,
     );
-    // Token was updated in storage
-    expect(lsMock.getItem("auth-token")).toBe("new-jwt-token");
+    expect(lsMock.getItem("auth-token")).toBe(refreshedToken);
   });
 
   // ── 401 → refresh failure → clear session + redirect ───────────────────
@@ -243,17 +406,17 @@ describe("request()", () => {
       mockResponse({ message: "Invalid" }, { status: 401 }),
     );
 
-    setTokens("expired-token", "bad-refresh-token");
+    setTokens(createJwt(), createJwt());
 
-    await expect(request("/api/secret")).rejects.toMatchObject({
+    await expect(request("/secret")).rejects.toMatchObject({
       name: "ApiError",
       status: 401,
       kind: "authRequired",
     });
 
     expect(lsMock.getItem("auth-token")).toBeNull();
-    expect(lsMock.getItem("refresh-token")).toBeNull();
-    expect(locationHref).toBe("/login");
+    expect(lsMock.getItem("auth-refresh-token")).toBeNull();
+    expect(locationHref).toBe("/login?redirect=%2Fdashboard");
   });
 
   it("clears session and redirects when no refresh token exists", async () => {
@@ -262,16 +425,76 @@ describe("request()", () => {
       mockResponse({ message: "Unauthorized" }, { status: 401 }),
     );
 
-    setTokens("expired-token"); // no refresh token
+    setTokens(createJwt());
 
-    await expect(request("/api/secret")).rejects.toMatchObject({
+    await expect(request("/secret")).rejects.toMatchObject({
       name: "ApiError",
       status: 401,
       kind: "authRequired",
     });
 
     expect(lsMock.getItem("auth-token")).toBeNull();
-    expect(locationHref).toBe("/login");
+    expect(locationHref).toBe("/login?redirect=%2Fdashboard");
+  });
+
+  it("refreshes an expired access token before sending the request", async () => {
+    const refreshedToken = createJwt();
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ access_token: refreshedToken }),
+    );
+    mockFetch.mockResolvedValueOnce(mockResponse({ data: "fresh" }));
+    setTokens(createExpiredJwt(), createJwt());
+
+    const data = await request<{ data: string }>("/data");
+
+    expect(data).toEqual({ data: "fresh" });
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(mockFetch.mock.calls[0][0]).toBe(`${API_V1_BASE}/auth/refresh`);
+    expect(mockFetch.mock.calls[1][1].headers.get("Authorization")).toBe(
+      `Bearer ${refreshedToken}`,
+    );
+  });
+
+  it("fails closed without a request when stored tokens are malformed", async () => {
+    setTokens("not-a-jwt", createJwt(Math.floor(Date.now() / 1000) - 1));
+
+    await expect(request("/secret")).rejects.toMatchObject({
+      status: 401,
+      kind: "authRequired",
+    });
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(lsMock.getItem("auth-token")).toBeNull();
+  });
+
+  it("does not recurse when the refresh endpoint itself returns 401", async () => {
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ message: "Invalid refresh token" }, { status: 401 }),
+    );
+
+    await expect(
+      request("/auth/refresh", {
+        method: "POST",
+        body: { refreshToken: createJwt() },
+      }),
+    ).rejects.toMatchObject({ status: 401, kind: "authRequired" });
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the session when reauthentication has a network failure", async () => {
+    const accessToken = createJwt();
+    mockFetch.mockResolvedValueOnce(
+      mockResponse({ message: "Unauthorized" }, { status: 401 }),
+    );
+    mockFetch.mockRejectedValueOnce(new Error("offline"));
+    setTokens(accessToken, createJwt());
+
+    await expect(request("/secret")).rejects.toMatchObject({
+      status: null,
+      kind: "network",
+    });
+    expect(lsMock.getItem("auth-token")).toBe(accessToken);
+    expect(lsMock.getItem("auth-refresh-token")).not.toBeNull();
+    expect(locationHref).toBe("");
   });
 
   it("does not attempt refresh for anonymous requests", async () => {
@@ -280,7 +503,7 @@ describe("request()", () => {
     );
 
     await expect(
-      request("/api/public", { anonymous: true }),
+      request("/public", { anonymous: true }),
     ).rejects.toMatchObject({
       name: "ApiError",
       status: 401,
@@ -295,10 +518,12 @@ describe("request()", () => {
 // ── clearSession ────────────────────────────────────────────────────────────
 
 describe("clearSession()", () => {
-  it("removes both tokens from localStorage", () => {
-    setTokens("access", "refresh");
+  it("removes canonical and legacy tokens from localStorage", () => {
+    setTokens(createJwt(), createJwt());
+    lsMock.setItem("refresh-token", createJwt());
     clearSession();
     expect(lsMock.getItem("auth-token")).toBeNull();
+    expect(lsMock.getItem("auth-refresh-token")).toBeNull();
     expect(lsMock.getItem("refresh-token")).toBeNull();
   });
 });
diff --git a/frontend/test-utils/language-switcher.test.tsx b/frontend/test-utils/language-switcher.test.tsx
index 2b8c3a9c..57bacb2c 100644
--- a/frontend/test-utils/language-switcher.test.tsx
+++ b/frontend/test-utils/language-switcher.test.tsx
@@ -12,6 +12,20 @@ jest.mock("@/i18n/navigation", () => ({
   useRouter: () => ({ replace: mockReplace, push: jest.fn() }),
 }));
 
+function createJwt(): string {
+  const encode = (value: object) =>
+    btoa(JSON.stringify(value))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+  return `${encode({ alg: "HS256", typ: "JWT" })}.${encode({
+    sub: "user-1",
+    email: "user@example.com",
+    role: "user",
+    exp: Math.floor(Date.now() / 1000) + 3600,
+  })}.signature`;
+}
+
 function renderSwitcher(locale = "en") {
   return render(
     <NextIntlClientProvider locale={locale} messages={messages}>
@@ -48,7 +62,7 @@ describe("LanguageSwitcher", () => {
   });
 
   it("saves the preferred language to the backend when authenticated", async () => {
-    localStorage.setItem("auth-token", "test-token");
+    localStorage.setItem("auth-token", createJwt());
     const fetchMock = jest.fn().mockResolvedValue({ ok: true } as Response);
     global.fetch = fetchMock as unknown as typeof fetch;
 
@@ -57,7 +71,7 @@ describe("LanguageSwitcher", () => {
 
     await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
     const [url, options] = fetchMock.mock.calls[0];
-    expect(String(url)).toContain("/api/users/me");
+    expect(String(url)).toContain("/api/v1/users/me");
     expect(options).toMatchObject({ method: "PATCH" });
     expect(
       JSON.parse((options as RequestInit).body as string)
diff --git a/frontend/test-utils/mocks/handlers.ts b/frontend/test-utils/mocks/handlers.ts
index 5cde6786..e2fe93ee 100644
--- a/frontend/test-utils/mocks/handlers.ts
+++ b/frontend/test-utils/mocks/handlers.ts
@@ -1,10 +1,24 @@
 import { http, HttpResponse } from "msw";
 
-const API_BASE = "http://localhost:3001";
+const API_BASE = "http://localhost:3001/api/v1";
+
+function createAccessToken(): string {
+  const encode = (value: object) =>
+    btoa(JSON.stringify(value))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+  return `${encode({ alg: "HS256", typ: "JWT" })}.${encode({
+    sub: "user-1",
+    email: "alice@example.com",
+    role: "user",
+    exp: Math.floor(Date.now() / 1000) + 3600,
+  })}.signature`;
+}
 
 export const handlers = [
   // Auth — login
-  http.post(`${API_BASE}/api/auth/login`, async ({ request }) => {
+  http.post(`${API_BASE}/auth/login`, async ({ request }) => {
     const body = (await request.json()) as { email: string; password: string };
     if (body.email === "bad@example.com") {
       return HttpResponse.json(
@@ -12,11 +26,11 @@ export const handlers = [
         { status: 401 }
       );
     }
-    return HttpResponse.json({ token: "fake-jwt-token" });
+    return HttpResponse.json({ access_token: createAccessToken() });
   }),
 
   // Auth — verify
-  http.get(`${API_BASE}/api/auth/verify`, ({ request }) => {
+  http.get(`${API_BASE}/auth/verify`, ({ request }) => {
     const auth = request.headers.get("Authorization");
     if (!auth || !auth.startsWith("Bearer ")) {
       return HttpResponse.json({ message: "Unauthorized" }, { status: 401 });
@@ -24,8 +38,96 @@ export const handlers = [
     return HttpResponse.json({ valid: true });
   }),
 
+  http.get(`${API_BASE}/auth/me`, ({ request }) => {
+    const auth = request.headers.get("Authorization");
+    if (!auth) {
+      return HttpResponse.json({ message: "Unauthorized" }, { status: 401 });
+    }
+    return HttpResponse.json({ id: "user-1", role: "user" });
+  }),
+
+  http.get(`${API_BASE}/documents`, () =>
+    HttpResponse.json({
+      data: [
+        {
+          id: "doc-1",
+          title: "Land Title Alpha",
+          status: "verified",
+          riskScore: 12,
+          riskFlags: [],
+          createdAt: "2025-06-01T10:00:00Z",
+          updatedAt: "2025-06-01T10:00:00Z",
+        },
+      ],
+      total: 1,
+      page: 1,
+      limit: 20,
+    }),
+  ),
+
+  http.get(`${API_BASE}/disputes`, () =>
+    HttpResponse.json({
+      data: [
+        {
+          id: "dispute-1",
+          documentId: "doc-1",
+          description: "The ownership information is incorrect.",
+          reason: { id: "reason-1", name: "Incorrect information" },
+          status: "open",
+          filedBy: "user-1",
+          createdAt: "2025-06-02T10:00:00Z",
+        },
+      ],
+      total: 1,
+    }),
+  ),
+
+  http.post(`${API_BASE}/disputes`, async ({ request }) => {
+    const body = (await request.json()) as {
+      documentId: string;
+      description: string;
+    };
+    return HttpResponse.json(
+      {
+        id: "dispute-2",
+        documentId: body.documentId,
+        description: body.description,
+        reason: null,
+        status: "open",
+        filedBy: "user-1",
+        createdAt: "2025-06-03T10:00:00Z",
+      },
+      { status: 201 },
+    );
+  }),
+
+  http.get(`${API_BASE}/disputes/:id`, () =>
+    HttpResponse.json({
+      id: "dispute-1",
+      documentId: "doc-1",
+      description: "The ownership information is incorrect.",
+      reason: { id: "reason-1", name: "Incorrect information" },
+      status: "open",
+      filedBy: "user-1",
+      createdAt: "2025-06-02T10:00:00Z",
+    }),
+  ),
+
+  http.patch(`${API_BASE}/disputes/:id/status`, async ({ request }) => {
+    const { status } = (await request.json()) as { status: string };
+    return HttpResponse.json({
+      id: "dispute-1",
+      documentId: "doc-1",
+      description: "The ownership information is incorrect.",
+      reason: { id: "reason-1", name: "Incorrect information" },
+      status,
+      filedBy: "user-1",
+      createdAt: "2025-06-02T10:00:00Z",
+    });
+  }),
+
   // Documents — list
-  http.get(`${API_BASE}/api/admin/documents`, ({ request }) => {
+  http.get(`${API_BASE}/admin/documents`, ({ request }) => {
     const url = new URL(request.url);
     const page = Number(url.searchParams.get("page") ?? "1");
     return HttpResponse.json({
@@ -51,14 +153,14 @@ export const handlers = [
   }),
 
   // Documents — export PDF
-  http.get(`${API_BASE}/api/documents/:id/export/pdf`, () => {
+  http.get(`${API_BASE}/documents/:id/export/pdf`, () => {
     return HttpResponse.arrayBuffer(new ArrayBuffer(0), {
       headers: { "Content-Type": "application/pdf" },
     });
   }),
 
   // Users — me
-  http.get(`${API_BASE}/api/users/me`, ({ request }) => {
+  http.get(`${API_BASE}/users/me`, ({ request }) => {
     const auth = request.headers.get("Authorization");
     if (!auth) {
       return HttpResponse.json({ message: "Unauthorized" }, { status: 401 });
@@ -71,7 +173,7 @@ export const handlers = [
     });
   }),
 
-  http.patch(`${API_BASE}/api/users/me`, async ({ request }) => {
+  http.patch(`${API_BASE}/users/me`, async ({ request }) => {
     const body = (await request.json()) as Record<string, unknown>;
     return HttpResponse.json({ ok: true, ...body });
   }),
diff --git a/frontend/test-utils/notification-bell.test.tsx b/frontend/test-utils/notification-bell.test.tsx
new file mode 100644
index 00000000..d848b6ff
--- /dev/null
+++ b/frontend/test-utils/notification-bell.test.tsx
@@ -0,0 +1,99 @@
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import NotificationBell from "@/components/layout/NotificationBell";
+
+const mockRequest = jest.fn();
+const mockRequestRaw = jest.fn();
+const mockRouterPush = jest.fn();
+
+jest.mock("@/lib/api-client", () => ({
+  getApiUrl: (path: string) => `http://localhost:3001/api/v1/${path}`,
+  request: (...args: unknown[]) => mockRequest(...args),
+  requestRaw: (...args: unknown[]) => mockRequestRaw(...args),
+}));
+
+jest.mock("@/i18n/navigation", () => ({
+  useRouter: () => ({ push: mockRouterPush }),
+}));
+
+class MockWebSocket {
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  onerror: (() => void) | null = null;
+  close = jest.fn();
+}
+
+function arrangeUnreadNotification() {
+  mockRequest.mockImplementation((url: string) => {
+    if (url.includes("unread-count")) {
+      return Promise.resolve({ count: 1 });
+    }
+    return Promise.resolve([
+      {
+        id: "notification-1",
+        type: "verification_complete",
+        title: "Verification complete",
+        body: "Your document is ready",
+        read: false,
+        createdAt: new Date().toISOString(),
+      },
+    ]);
+  });
+}
+
+function renderBell() {
+  return render(<NotificationBell />);
+}
+
+describe("NotificationBell", () => {
+  beforeEach(() => {
+    mockRequest.mockReset();
+    mockRequestRaw.mockReset();
+    mockRouterPush.mockReset();
+    Object.defineProperty(globalThis, "WebSocket", {
+      value: MockWebSocket,
+      configurable: true,
+    });
+    arrangeUnreadNotification();
+  });
+
+  it("keeps notifications unread when mark-all-read fails", async () => {
+    mockRequestRaw.mockRejectedValue(new Error("request failed"));
+    renderBell();
+
+    fireEvent.click(
+      await screen.findByRole("button", { name: /notifications, 1 unread/i }),
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Mark all as read" }));
+
+    await waitFor(() => expect(mockRequestRaw).toHaveBeenCalledTimes(1));
+    expect(mockRequestRaw).toHaveBeenCalledWith(
+      "http://localhost:3001/api/v1/notifications/read-all",
+      { method: "PATCH" },
+    );
+    expect(
+      screen.getByRole("button", { name: /notifications, 1 unread/i }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Mark all as read" }),
+    ).toBeInTheDocument();
+  });
+
+  it("updates notifications only after mark-all-read succeeds", async () => {
+    mockRequestRaw.mockResolvedValue({} as Response);
+    renderBell();
+
+    fireEvent.click(
+      await screen.findByRole("button", { name: /notifications, 1 unread/i }),
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Mark all as read" }));
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole("button", { name: "Notifications" }),
+      ).toBeInTheDocument();
+      expect(
+        screen.queryByRole("button", { name: "Mark all as read" }),
+      ).not.toBeInTheDocument();
+    });
+  });
+});