diff --git a/frontend/app/[locale]/(protected)/settings/data/page.tsx b/frontend/app/[locale]/(protected)/settings/data/page.tsx
index bc23c4a5..4f85fc6e 100644
--- a/frontend/app/[locale]/(protected)/settings/data/page.tsx
+++ b/frontend/app/[locale]/(protected)/settings/data/page.tsx
@@ -12,8 +12,8 @@ import {
// Helpers
// ---------------------------------------------------------------------------
-async function logout(): Promise
{
- return clearSession();
+function logout(): boolean {
+ return clearSession().ok;
}
const COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24 hours
diff --git a/frontend/app/[locale]/(protected)/settings/security/page.tsx b/frontend/app/[locale]/(protected)/settings/security/page.tsx
index 8c85a477..08cbb07c 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 { clearSession } from "@/lib/auth-session";
// ─────────────────────────────────────────────
// Types
@@ -268,7 +269,10 @@ 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.
+ const cleared = clearSession();
+ if (!cleared.ok) {
+ throw new Error("Unable to clear the session safely.");
+ }
window.location.href = "/login";
} catch {
setError("Failed to delete account. Please try again.");
diff --git a/frontend/app/[locale]/login/LoginForm.tsx b/frontend/app/[locale]/login/LoginForm.tsx
index 363a5990..47c30b5f 100644
--- a/frontend/app/[locale]/login/LoginForm.tsx
+++ b/frontend/app/[locale]/login/LoginForm.tsx
@@ -7,7 +7,7 @@ import { 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 { API_V1_BASE, ApiError, apiRequest } from "@/lib/api-client";
import {
resolvePostLoginPath,
storeSession,
@@ -25,8 +25,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);
@@ -91,15 +89,16 @@ export function LoginForm() {
});
const target = resolvePostLoginPath(searchParams.get("redirect"));
+ const resumeId = searchParams.get("resume");
const oauthHref = (provider: "google" | "github") =>
- `${API_BASE}/api/v1/auth/${provider}`;
+ `${API_V1_BASE}/auth/${provider}`;
async function onSubmit(values: LoginInput) {
setSubmitError(null);
try {
const data = await apiRequest(
- "/api/v1/auth/login",
+ `${API_V1_BASE}/auth/login`,
{
method: "POST",
body: values,
@@ -107,7 +106,11 @@ export function LoginForm() {
anonymous: true,
},
);
- storeSession(data);
+ const stored = storeSession(data, resumeId ?? undefined);
+ if (!stored.ok) {
+ 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/components/SessionExpiryGuard.tsx b/frontend/components/SessionExpiryGuard.tsx
new file mode 100644
index 00000000..73f75939
--- /dev/null
+++ b/frontend/components/SessionExpiryGuard.tsx
@@ -0,0 +1,17 @@
+"use client";
+
+import { useCallback, useEffect } from "react";
+import { refreshSession } from "@/lib/api-client";
+import {
+ initCrossTabLogoutSync,
+ useSessionExpiryWarning,
+} from "@/lib/session-expiry-warning";
+
+export function SessionExpiryGuard() {
+ const onRefresh = useCallback(() => refreshSession(), []);
+
+ useSessionExpiryWarning({ onRefresh });
+ useEffect(() => initCrossTabLogoutSync(), []);
+
+ return null;
+}
diff --git a/frontend/lib/__tests__/image-loader.test.ts b/frontend/lib/__tests__/image-loader.test.ts
new file mode 100644
index 00000000..b83a9935
--- /dev/null
+++ b/frontend/lib/__tests__/image-loader.test.ts
@@ -0,0 +1,43 @@
+import imageLoader, { getOptimizedImageUrl } from "../image-loader";
+
+describe("Next image loader", () => {
+ it("uses the default-export ImageLoader contract", () => {
+ const result = imageLoader({
+ src: "/documents/photo.jpg?version=2#preview",
+ width: 640,
+ quality: 80,
+ });
+
+ expect(result).toBe(
+ "/_next/image?url=%2Fdocuments%2Fphoto.jpg%3Fversion%3D2&w=640&q=80#preview",
+ );
+ });
+
+ it("keeps the named URL helper compatible with the loader", () => {
+ expect(getOptimizedImageUrl("/photo.jpg", 320, 70)).toBe(
+ imageLoader({ src: "/photo.jpg", width: 320, quality: 70 }),
+ );
+ });
+
+ it("returns signed URLs unchanged rather than proxying them", () => {
+ const signedUrl =
+ "https://cdn.example.test/photo.jpg?X-Amz-Signature=abc&X-Amz-Expires=60";
+
+ expect(imageLoader({ src: signedUrl, width: 640 })).toBe(signedUrl);
+ });
+
+ it("leaves inline and object URLs unchanged", () => {
+ expect(imageLoader({ src: "data:image/png;base64,abc", width: 640 })).toBe(
+ "data:image/png;base64,abc",
+ );
+ expect(imageLoader({ src: "blob:https://example.test/image", width: 640 })).toBe(
+ "blob:https://example.test/image",
+ );
+ });
+
+ it("rejects protocol-relative URLs", () => {
+ expect(() => imageLoader({ src: "//cdn.example.test/photo.jpg", width: 640 })).toThrow(
+ "Protocol-relative image URLs are not supported",
+ );
+ });
+});
diff --git a/frontend/lib/__tests__/session-expiry-warning.test.ts b/frontend/lib/__tests__/session-expiry-warning.test.ts
new file mode 100644
index 00000000..c038dbdd
--- /dev/null
+++ b/frontend/lib/__tests__/session-expiry-warning.test.ts
@@ -0,0 +1,153 @@
+import { act, renderHook } from "@testing-library/react";
+import {
+ getTokenExpiryMs,
+ useSessionExpiryWarning,
+} from "../session-expiry-warning";
+
+const values: Record = {};
+let storageBlocked = false;
+const localStorage = {
+ getItem: jest.fn((key: string) => {
+ if (storageBlocked) throw new DOMException("blocked", "SecurityError");
+ return values[key] ?? null;
+ }),
+};
+
+function makeToken(expiresInSeconds: number): string {
+ const payload = btoa(
+ JSON.stringify({ exp: Math.floor(Date.now() / 1000) + expiresInSeconds }),
+ )
+ .replace(/\+/g, "-")
+ .replace(/\//g, "_")
+ .replace(/=+$/, "");
+ return `header.${payload}.signature`;
+}
+
+beforeEach(() => {
+ jest.useFakeTimers();
+ jest.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+ Object.keys(values).forEach((key) => delete values[key]);
+ values["auth-token"] = makeToken(600);
+ storageBlocked = false;
+ Object.defineProperty(window, "localStorage", {
+ configurable: true,
+ value: localStorage,
+ });
+ localStorage.getItem.mockClear();
+ Object.defineProperty(window, "confirm", {
+ configurable: true,
+ value: jest.fn(() => false),
+ });
+});
+
+afterEach(() => {
+ jest.clearAllTimers();
+ jest.useRealTimers();
+ jest.restoreAllMocks();
+});
+
+describe("session expiry warning", () => {
+ it("parses base64url JWT payloads without requiring padding", () => {
+ const token =
+ "header.eyJleHAiOjE4OTM0NTYwMDAsIngiOiL_wiJ9.signature";
+
+ expect(getTokenExpiryMs(token)).toBe(
+ 1893456000000 - new Date("2026-01-01T00:00:00.000Z").getTime(),
+ );
+ });
+
+ it("postpones the prompt until a continuous typing stream stops", () => {
+ values["auth-token"] = makeToken(360);
+ const onRefresh = jest.fn().mockResolvedValue(undefined);
+ const editor = document.createElement("textarea");
+ document.body.appendChild(editor);
+ const { unmount } = renderHook(() =>
+ useSessionExpiryWarning({ onRefresh }),
+ );
+
+ act(() => {
+ for (let index = 0; index < 400; index += 1) {
+ editor.dispatchEvent(new Event("input", { bubbles: true }));
+ jest.advanceTimersByTime(200);
+ }
+ });
+
+ expect(window.confirm).not.toHaveBeenCalled();
+
+ act(() => {
+ jest.advanceTimersByTime(250);
+ jest.advanceTimersByTime(60 * 1000);
+ });
+ expect(window.confirm).toHaveBeenCalledTimes(1);
+ unmount();
+ editor.remove();
+ });
+
+ it("handles blocked localStorage without throwing from activity", () => {
+ const onRefresh = jest.fn().mockResolvedValue(undefined);
+ const editor = document.createElement("input");
+ document.body.appendChild(editor);
+ const { unmount } = renderHook(() =>
+ useSessionExpiryWarning({ onRefresh }),
+ );
+ storageBlocked = true;
+
+ expect(() => {
+ act(() => {
+ editor.dispatchEvent(new Event("focusin", { bubbles: true }));
+ editor.dispatchEvent(new Event("input", { bubbles: true }));
+ jest.advanceTimersByTime(10 * 60 * 1000);
+ });
+ }).not.toThrow();
+ expect(window.confirm).not.toHaveBeenCalled();
+ unmount();
+ editor.remove();
+ });
+
+ it("uses the latest refresh callback without restarting on identity changes", async () => {
+ values["auth-token"] = makeToken(1200);
+ const firstRefresh = jest.fn().mockResolvedValue(undefined);
+ const secondRefresh = jest.fn().mockResolvedValue(undefined);
+ Object.defineProperty(window, "confirm", {
+ configurable: true,
+ value: jest.fn(() => true),
+ });
+ const { rerender, unmount } = renderHook(
+ ({ onRefresh }: { onRefresh: () => Promise }) =>
+ useSessionExpiryWarning({ onRefresh }),
+ { initialProps: { onRefresh: firstRefresh } },
+ );
+
+ rerender({ onRefresh: secondRefresh });
+ await act(async () => {
+ jest.advanceTimersByTime(5 * 60 * 1000);
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+
+ expect(firstRefresh).not.toHaveBeenCalled();
+ expect(secondRefresh).toHaveBeenCalledTimes(1);
+ unmount();
+ });
+
+ it("cleans the timer and listeners on unmount", () => {
+ const editor = document.createElement("textarea");
+ document.body.appendChild(editor);
+ const { unmount } = renderHook(() =>
+ useSessionExpiryWarning({ onRefresh: jest.fn().mockResolvedValue(undefined) }),
+ );
+
+ act(() => {
+ jest.advanceTimersByTime(4 * 60 * 1000);
+ editor.dispatchEvent(new Event("input", { bubbles: true }));
+ });
+ unmount();
+
+ act(() => {
+ editor.dispatchEvent(new Event("input", { bubbles: true }));
+ jest.advanceTimersByTime(10 * 60 * 1000);
+ });
+ expect(window.confirm).not.toHaveBeenCalled();
+ editor.remove();
+ });
+});
diff --git a/frontend/lib/__tests__/session-expiry.test.ts b/frontend/lib/__tests__/session-expiry.test.ts
index 36742279..e1bb33df 100644
--- a/frontend/lib/__tests__/session-expiry.test.ts
+++ b/frontend/lib/__tests__/session-expiry.test.ts
@@ -59,7 +59,7 @@ describe("Concurrent 401 → single refresh (Issue #1024)", () => {
// 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")) {
+ if (url.includes("/api/v1/auth/refresh")) {
refreshCallCount += 1;
return Promise.resolve(
new Response(
@@ -100,7 +100,7 @@ describe("Concurrent 401 → single refresh (Issue #1024)", () => {
(window as any).location = { href: "" };
(global as any).fetch = jest.fn((url: string) => {
- if (url.includes("/auth/refresh")) {
+ if (url.includes("/api/v1/auth/refresh")) {
return Promise.resolve(
new Response(JSON.stringify({ error: "invalid_grant" }), {
status: 401,
diff --git a/frontend/lib/__tests__/session-state-preserver.test.ts b/frontend/lib/__tests__/session-state-preserver.test.ts
new file mode 100644
index 00000000..fe2105a2
--- /dev/null
+++ b/frontend/lib/__tests__/session-state-preserver.test.ts
@@ -0,0 +1,282 @@
+import {
+ clearAllSessionState,
+ clearSessionState,
+ commitSessionResume,
+ commitSessionState,
+ consumeSessionResume,
+ consumeSessionState,
+ preserveSessionState,
+ readSessionState,
+ type SessionStateResult,
+} from "../session-state-preserver";
+
+const values: Record = {};
+const accessTokens: Record = {};
+let blockGet = false;
+let blockLocalGet = false;
+let blockSetKey: string | null = null;
+let blockRemove = false;
+
+const sessionStorage = {
+ getItem: jest.fn((key: string) => {
+ if (blockGet) throw new DOMException("blocked", "SecurityError");
+ return values[key] ?? null;
+ }),
+ setItem: jest.fn((key: string, value: string) => {
+ if (blockSetKey === key) throw new DOMException("blocked", "SecurityError");
+ values[key] = value;
+ }),
+ removeItem: jest.fn((key: string) => {
+ if (blockRemove) throw new DOMException("blocked", "SecurityError");
+ delete values[key];
+ }),
+ get length() {
+ return Object.keys(values).length;
+ },
+ key: jest.fn((index: number) => Object.keys(values)[index] ?? null),
+};
+
+const localStorage = {
+ getItem: jest.fn((key: string) => {
+ if (blockLocalGet) throw new DOMException("blocked", "SecurityError");
+ return accessTokens[key] ?? null;
+ }),
+ setItem: jest.fn((key: string, value: string) => {
+ accessTokens[key] = value;
+ }),
+ removeItem: jest.fn((key: string) => {
+ delete accessTokens[key];
+ }),
+};
+
+function makeToken(subject: string, nonce = ""): string {
+ const payload = btoa(JSON.stringify({ sub: subject, iat: nonce }))
+ .replace(/\+/g, "-")
+ .replace(/\//g, "_")
+ .replace(/=+$/, "");
+ return `header.${payload}.signature`;
+}
+
+function unwrap(result: SessionStateResult): T {
+ if (!result.ok) throw new Error(result.error.code);
+ return result.value;
+}
+
+beforeEach(() => {
+ Object.keys(values).forEach((key) => delete values[key]);
+ Object.keys(accessTokens).forEach((key) => delete accessTokens[key]);
+ accessTokens["auth-token"] = makeToken("user-a", "old");
+ blockGet = false;
+ blockLocalGet = false;
+ blockSetKey = null;
+ blockRemove = false;
+ Object.defineProperty(window, "sessionStorage", {
+ configurable: true,
+ value: sessionStorage,
+ });
+ Object.defineProperty(window, "localStorage", {
+ configurable: true,
+ value: localStorage,
+ });
+ sessionStorage.getItem.mockClear();
+ sessionStorage.setItem.mockClear();
+ sessionStorage.removeItem.mockClear();
+ sessionStorage.key.mockClear();
+ localStorage.getItem.mockClear();
+ localStorage.setItem.mockClear();
+ localStorage.removeItem.mockClear();
+});
+
+describe("transactional session state", () => {
+ it("reads without removing and commits only after the caller is ready", () => {
+ const resumeId = unwrap(
+ preserveSessionState("upload-form", { fileName: "deed.pdf" }),
+ );
+ expect(resumeId).toEqual(expect.any(String));
+
+ const read = readSessionState<{ fileName: string }>("upload-form");
+ expect(unwrap(read)).toEqual({ fileName: "deed.pdf" });
+ expect(sessionStorage.removeItem).not.toHaveBeenCalled();
+
+ expect(commitSessionState("upload-form")).toEqual({ ok: true, value: undefined });
+ expect(sessionStorage.removeItem).toHaveBeenCalledTimes(2);
+ expect(readSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "not-found", key: "upload-form" },
+ });
+ });
+
+ it("consumes a matching session exactly once", () => {
+ unwrap(preserveSessionState("upload-form", { title: "Land deed" }));
+
+ expect(unwrap(consumeSessionState("upload-form"))).toEqual({
+ title: "Land deed",
+ });
+ expect(sessionStorage.removeItem).toHaveBeenCalledTimes(2);
+ expect(consumeSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "not-found", key: "upload-form" },
+ });
+ expect(sessionStorage.removeItem).toHaveBeenCalledTimes(2);
+ });
+
+ it("consumes pending state transactionally on an explicit resume", () => {
+ const resumeId = unwrap(
+ preserveSessionState("upload-form", { title: "Land deed" }),
+ );
+ const newToken = makeToken("user-a", "new");
+ accessTokens["auth-token"] = newToken;
+
+ expect(readSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "session-mismatch", key: "upload-form" },
+ });
+ expect(unwrap(consumeSessionResume(resumeId, newToken))).toEqual({
+ "upload-form": { title: "Land deed" },
+ });
+ expect(values["smalda-session-state:upload-form"]).toBeUndefined();
+ expect(values["smalda-session-state:__pending__"]).toBeUndefined();
+ expect(readSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "not-found", key: "upload-form" },
+ });
+ });
+
+ it("rejects a resume committed by a different JWT subject", () => {
+ accessTokens["auth-token"] = makeToken("user-a");
+ const resumeId = unwrap(
+ preserveSessionState("upload-form", { title: "Land deed" }),
+ );
+
+ accessTokens["auth-token"] = makeToken("user-b");
+ expect(commitSessionResume(resumeId, makeToken("user-b"))).toEqual({
+ ok: false,
+ error: { code: "session-mismatch", key: "upload-form" },
+ });
+ accessTokens["auth-token"] = makeToken("user-a");
+ expect(unwrap(commitSessionResume(resumeId, makeToken("user-a")))).toBe(1);
+ expect(values["smalda-session-state:upload-form"]).toBeUndefined();
+ expect(values["smalda-session-state:__pending__"]).toBeUndefined();
+ });
+
+ it("does not preserve state for an unverifiable token", () => {
+ accessTokens["auth-token"] = "opaque-old-token";
+
+ expect(
+ preserveSessionState("upload-form", { title: "Land deed" }),
+ ).toEqual({
+ ok: false,
+ error: { code: "unauthenticated", key: "upload-form" },
+ });
+ });
+
+ it("rejects a resume when the subject cannot be verified", () => {
+ const resumeId = unwrap(
+ preserveSessionState("upload-form", { title: "Land deed" }),
+ );
+ accessTokens["auth-token"] = "opaque-new-token";
+
+ expect(commitSessionResume(resumeId, "opaque-new-token")).toEqual({
+ ok: false,
+ error: { code: "session-mismatch", key: "upload-form" },
+ });
+ });
+
+ it("surfaces blocked reads and removal failures without losing state", () => {
+ unwrap(preserveSessionState("upload-form", { title: "Land deed" }));
+ blockGet = true;
+ expect(readSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "storage", key: "smalda-session-state:upload-form" },
+ });
+ blockGet = false;
+
+ blockLocalGet = true;
+ expect(readSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "storage", key: "auth-token" },
+ });
+ blockLocalGet = false;
+
+ blockRemove = true;
+ expect(consumeSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "removal", key: "smalda-session-state:upload-form" },
+ });
+ blockRemove = false;
+ expect(unwrap(readSessionState("upload-form"))).toEqual({
+ title: "Land deed",
+ });
+ });
+
+ it("does not claim resume success when state removal fails", () => {
+ const resumeId = unwrap(
+ preserveSessionState("upload-form", { title: "Land deed" }),
+ );
+ const newToken = makeToken("user-a", "new");
+ accessTokens["auth-token"] = newToken;
+ blockRemove = true;
+
+ expect(consumeSessionResume(resumeId, newToken)).toEqual({
+ ok: false,
+ error: { code: "removal", key: "smalda-session-state:upload-form" },
+ });
+
+ blockRemove = false;
+ expect(values["smalda-session-state:upload-form"]).toBeDefined();
+ expect(values["smalda-session-state:__pending__"]).toBeDefined();
+ });
+
+ it("rolls back a state write when the pending index cannot be written", () => {
+ blockSetKey = "smalda-session-state:__pending__";
+ expect(preserveSessionState("upload-form", { title: "Land deed" })).toEqual({
+ ok: false,
+ error: { code: "storage", key: "smalda-session-state:__pending__" },
+ });
+ blockSetKey = null;
+ expect(readSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "not-found", key: "upload-form" },
+ });
+ });
+
+ it("rejects File and Blob values instead of silently losing their bytes", () => {
+ expect(
+ preserveSessionState("upload", new File(["data"], "deed.pdf")),
+ ).toEqual({
+ ok: false,
+ error: { code: "serialization", key: "upload" },
+ });
+ expect(preserveSessionState("upload", new Blob(["data"]))).toEqual({
+ ok: false,
+ error: { code: "serialization", key: "upload" },
+ });
+ });
+
+ it("clears all preserved entries for an explicit logout", () => {
+ unwrap(preserveSessionState("first", { value: 1 }));
+ unwrap(preserveSessionState("second", { value: 2 }));
+
+ expect(clearAllSessionState()).toEqual({ ok: true, value: undefined });
+ expect(readSessionState("first")).toEqual({
+ ok: false,
+ error: { code: "not-found", key: "first" },
+ });
+ expect(readSessionState("second")).toEqual({
+ ok: false,
+ error: { code: "not-found", key: "second" },
+ });
+ });
+
+ it("can explicitly clear a single entry", () => {
+ unwrap(preserveSessionState("upload-form", { title: "Land deed" }));
+ expect(clearSessionState("upload-form")).toEqual({
+ ok: true,
+ value: undefined,
+ });
+ expect(readSessionState("upload-form")).toEqual({
+ ok: false,
+ error: { code: "not-found", key: "upload-form" },
+ });
+ });
+});
diff --git a/frontend/lib/api-client.ts b/frontend/lib/api-client.ts
index 3b019871..9837a27e 100644
--- a/frontend/lib/api-client.ts
+++ b/frontend/lib/api-client.ts
@@ -15,10 +15,26 @@
* never surfaced.
*/
-const API_BASE = (process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001").replace(
- /\/+$/,
- "",
+import {
+ clearAllSessionState,
+ getPendingSessionResumeId,
+ type SessionStateError,
+ type SessionStateResult,
+} from "@/lib/session-state-preserver";
+
+function normalizeApiBase(value: string): string {
+ return value
+ .trim()
+ .replace(/\/+$/, "")
+ .replace(/(?:\/api)+(?:\/v1)?$/, "");
+}
+
+const API_BASE = normalizeApiBase(
+ process.env.NEXT_PUBLIC_API_URL?.trim() || "http://localhost:3001",
);
+export const API_V1_BASE = `${API_BASE}/api/v1`;
+const REFRESH_ENDPOINT = `${API_V1_BASE}/auth/refresh`;
+const LOGOUT_ENDPOINT = `${API_V1_BASE}/auth/logout`;
const ACCESS_TOKEN_KEY = "auth-token";
const REFRESH_TOKEN_KEY = "refresh-token";
@@ -42,12 +58,14 @@ export class ApiError extends Error {
readonly kind: ApiErrorKind;
readonly messageKey: string;
readonly backendMessage?: string;
+ readonly stateError?: SessionStateError;
constructor(opts: {
status: number | null;
kind: ApiErrorKind;
messageKey: string;
backendMessage?: string;
+ stateError?: SessionStateError;
}) {
super(opts.messageKey);
this.name = "ApiError";
@@ -55,6 +73,7 @@ export class ApiError extends Error {
this.kind = opts.kind;
this.messageKey = opts.messageKey;
this.backendMessage = opts.backendMessage;
+ this.stateError = opts.stateError;
}
}
@@ -79,6 +98,17 @@ export function isDefinitiveRefreshError(error: unknown): boolean {
return error instanceof RefreshError && error.definitive;
}
+export class RefreshInvalidatedError extends Error {
+ constructor() {
+ super("Refresh invalidated");
+ this.name = "RefreshInvalidatedError";
+ }
+}
+
+export function isRefreshInvalidatedError(error: unknown): boolean {
+ return error instanceof RefreshInvalidatedError;
+}
+
export function classifyStatus(status: number): ApiErrorMapping {
switch (status) {
case 401:
@@ -101,12 +131,20 @@ export function classifyStatus(status: number): ApiErrorMapping {
function getAccessToken(): string | null {
if (typeof window === "undefined") return null;
- return window.localStorage.getItem(ACCESS_TOKEN_KEY);
+ try {
+ return window.localStorage.getItem(ACCESS_TOKEN_KEY);
+ } catch {
+ return null;
+ }
}
function getRefreshToken(): string | null {
if (typeof window === "undefined") return null;
- return window.localStorage.getItem(REFRESH_TOKEN_KEY);
+ try {
+ return window.localStorage.getItem(REFRESH_TOKEN_KEY);
+ } catch {
+ return null;
+ }
}
function setAccessToken(token: string): void {
@@ -126,6 +164,11 @@ function getRefreshSnapshot(): RefreshSnapshot {
};
}
+/**
+ * If another tab already rotated the tokens while we were mid-refresh, adopt
+ * its result instead of racing it (avoids the server treating our stale
+ * refresh token as reused and revoking the whole token family — see #1398).
+ */
function getAdoptedRefreshToken(snapshot: RefreshSnapshot): string | null {
const accessToken = getAccessToken();
const refreshToken = getRefreshToken();
@@ -171,14 +214,14 @@ function waitForCrossTabRefresh(snapshot: RefreshSnapshot): Promise {
- if (typeof window === "undefined") return false;
+// ── Session clearing ────────────────────────────────────────────────────────
- const token = window.localStorage.getItem(ACCESS_TOKEN_KEY);
+async function logoutServerSession(token: string | null): Promise {
+ if (typeof window === "undefined") return false;
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), LOGOUT_TIMEOUT_MS);
try {
- const response = await fetch(`${API_BASE}/api/v1/auth/logout`, {
+ const response = await fetch(LOGOUT_ENDPOINT, {
method: "POST",
credentials: "include",
headers: token ? { Authorization: `Bearer ${token}` } : undefined,
@@ -192,23 +235,53 @@ async function logoutServerSession(): Promise {
}
}
-export async function clearSession(): Promise {
- if (typeof window === "undefined") return false;
- const logoutRequest = logoutServerSession();
- window.localStorage.removeItem(ACCESS_TOKEN_KEY);
- window.localStorage.removeItem(REFRESH_TOKEN_KEY);
- // Signal other tabs to also redirect to login
- window.localStorage.setItem("logout-event", Date.now().toString());
- return logoutRequest;
+/**
+ * Clears the local session (and, best-effort, revokes it server-side).
+ *
+ * `preserveSessionState` skips clearing transactional form state preserved
+ * across a redirect (used when a 401 bounces the user to login mid-flow, so
+ * they don't lose in-progress work). `notify: false` skips broadcasting the
+ * cross-tab logout-event, used when reacting to *another* tab's logout to
+ * avoid an infinite storage-event ping-pong.
+ */
+export function clearSession(
+ options: { preserveSessionState?: boolean; notify?: boolean } = {},
+): SessionStateResult {
+ invalidateRefresh();
+ if (typeof window === "undefined") {
+ return { ok: false, error: { code: "unavailable" } };
+ }
+
+ // Best-effort server-side revocation; do not block local logout on it.
+ void logoutServerSession(getAccessToken());
+
+ let result: SessionStateResult = { ok: true, value: undefined };
+ try {
+ window.localStorage.removeItem(ACCESS_TOKEN_KEY);
+ window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+ if (options.notify !== false) {
+ window.localStorage.setItem("logout-event", Date.now().toString());
+ }
+ } catch {
+ result = { ok: false, error: { code: "storage" } };
+ }
+
+ if (options.preserveSessionState) return result;
+ const stateResult = clearAllSessionState();
+ return stateResult.ok ? result : stateResult;
}
/**
* 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.
+ * If a session-state resume group is pending, its id is attached as `?resume=`
+ * so the login/register flow can restore it after re-authenticating.
*/
-function redirectToLogin(): void {
- if (typeof window === "undefined") return;
+function redirectToLogin(): SessionStateResult {
+ if (typeof window === "undefined") {
+ return { ok: false, error: { code: "unavailable" } };
+ }
const pathname =
typeof window.location.pathname === "string" ? window.location.pathname : "/";
const search =
@@ -216,12 +289,34 @@ function redirectToLogin(): void {
const currentPath = pathname + search;
const params = new URLSearchParams();
params.set("redirect", currentPath);
+ const resume = getPendingSessionResumeId();
+ if (resume.ok && resume.value) params.set("resume", resume.value);
window.location.href = `/login?${params.toString()}`;
+ return resume.ok ? { ok: true, value: undefined } : resume;
}
// ── Refresh logic ───────────────────────────────────────────────────────────
let refreshPromise: Promise | null = null;
+let refreshAbortController: AbortController | null = null;
+let authGeneration = 0;
+
+/**
+ * Invalidates any in-flight or future refresh tied to the current generation.
+ * Called on explicit login/logout so a stale refresh response from before a
+ * storeSession()/clearSession() call can never win a race against it.
+ */
+export function invalidateRefresh(): void {
+ authGeneration += 1;
+ refreshPromise = null;
+ const controller = refreshAbortController;
+ refreshAbortController = null;
+ try {
+ controller?.abort();
+ } catch {
+ return;
+ }
+}
/**
* Attempt a silent token refresh. Deduplicates concurrent refresh calls
@@ -239,19 +334,29 @@ async function refreshAccessToken(expectedAccessToken?: string): Promise
return currentAccessToken;
}
+ const generation = authGeneration;
+ const controller = new AbortController();
+ refreshAbortController = controller;
+
refreshPromise = (async () => {
const snapshot = getRefreshSnapshot();
try {
const refreshToken = snapshot.refreshToken;
- const res = await fetch(`${API_BASE}/api/v1/auth/refresh`, {
+ if (!refreshToken) {
+ throw new RefreshError(null, true);
+ }
+
+ const res = await fetch(REFRESH_ENDPOINT, {
method: "POST",
credentials: "include",
- headers: refreshToken
- ? { "Content-Type": "application/json" }
- : undefined,
- body: refreshToken ? JSON.stringify({ refreshToken }) : undefined,
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ refreshToken }),
+ signal: controller.signal,
});
+ if (generation !== authGeneration || controller.signal.aborted) {
+ throw new RefreshInvalidatedError();
+ }
if (!res.ok) {
throw new RefreshError(
res.status,
@@ -266,24 +371,36 @@ async function refreshAccessToken(expectedAccessToken?: string): Promise
if (typeof data.access_token !== "string" || !data.access_token) {
throw new RefreshError(res.status, false);
}
- setAccessToken(data.access_token);
if (
- typeof data.refresh_token === "string" &&
- data.refresh_token &&
- typeof window !== "undefined"
+ generation !== authGeneration ||
+ controller.signal.aborted ||
+ getRefreshToken() !== refreshToken
) {
+ throw new RefreshInvalidatedError();
+ }
+
+ setAccessToken(data.access_token);
+ // The backend rotates the refresh token on every use (see #1398's
+ // reuse-detection); persist whatever it returns or the next refresh
+ // will look like reuse of an already-rotated token.
+ if (typeof data.refresh_token === "string" && data.refresh_token) {
window.localStorage.setItem(REFRESH_TOKEN_KEY, data.refresh_token);
- } else if (typeof window !== "undefined") {
+ } else {
window.localStorage.removeItem(REFRESH_TOKEN_KEY);
}
return data.access_token;
} catch (error) {
+ if (error instanceof RefreshInvalidatedError) throw error;
+ if (generation !== authGeneration || controller.signal.aborted) {
+ throw new RefreshInvalidatedError();
+ }
const adoptedToken = await waitForCrossTabRefresh(snapshot);
if (adoptedToken) return adoptedToken;
if (error instanceof RefreshError) throw error;
throw new RefreshError(null, false);
} finally {
- refreshPromise = null;
+ if (refreshPromise) refreshPromise = null;
+ if (refreshAbortController === controller) refreshAbortController = null;
}
})();
@@ -326,11 +443,34 @@ async function extractBackendMessage(
return undefined;
}
+function invalidatedRequestError(): ApiError {
+ return new ApiError({
+ status: null,
+ kind: "network",
+ messageKey: "errors.status.network",
+ });
+}
+
+function authRequiredError(): ApiError {
+ const cleared = clearSession({ preserveSessionState: true });
+ const redirected = redirectToLogin();
+ let stateError: SessionStateError | undefined;
+ if (!cleared.ok) stateError = cleared.error;
+ else if (!redirected.ok) stateError = redirected.error;
+ return new ApiError({
+ status: 401,
+ kind: "authRequired",
+ messageKey: "errors.status.unauthorized",
+ stateError,
+ });
+}
+
async function executeRequest(
path: string,
options: RequestOptions,
): Promise {
const { anonymous = false, ...fetchOpts } = options;
+ const requestGeneration = authGeneration;
const url = path.startsWith("http") ? path : `${API_BASE}${path}`;
const doFetch = async (token: string | null): Promise => {
@@ -377,19 +517,20 @@ async function executeRequest(
});
}
+ if (requestGeneration !== authGeneration) {
+ throw invalidatedRequestError();
+ }
+
if (res.status === 401 && !anonymous) {
try {
const newToken = await refreshAccessToken(requestAccessToken ?? undefined);
res = await doFetch(newToken);
} catch (error) {
+ if (isRefreshInvalidatedError(error)) {
+ throw invalidatedRequestError();
+ }
if (isDefinitiveRefreshError(error)) {
- await clearSession();
- redirectToLogin();
- throw new ApiError({
- status: 401,
- kind: "authRequired",
- messageKey: "errors.status.unauthorized",
- });
+ throw authRequiredError();
}
if (error instanceof RefreshError) {
const mapping =
@@ -403,6 +544,13 @@ async function executeRequest(
}
throw error;
}
+
+ if (requestGeneration !== authGeneration) {
+ throw invalidatedRequestError();
+ }
+ if (res.status === 401) {
+ throw authRequiredError();
+ }
}
if (!res.ok) {
diff --git a/frontend/lib/auth-session.ts b/frontend/lib/auth-session.ts
index bda35877..d7a49b25 100644
--- a/frontend/lib/auth-session.ts
+++ b/frontend/lib/auth-session.ts
@@ -7,6 +7,12 @@
* should read the session off the context instead of touching storage.
*/
+import { invalidateRefresh } from "@/lib/api-client";
+import {
+ clearAllSessionState,
+ consumeSessionResume,
+ type SessionStateResult,
+} from "@/lib/session-state-preserver";
import { routing, type Locale } from "@/i18n/routing";
const ACCESS_TOKEN_KEY = "auth-token";
@@ -18,16 +24,74 @@ export interface LoginResponse {
refresh_token?: string;
}
-export function storeSession(tokens: LoginResponse): void {
- if (typeof window === "undefined") return;
- if (tokens.access_token) {
+function unavailable(): SessionStateResult {
+ return { ok: false, error: { code: "unavailable" } };
+}
+
+function invalidSession(): SessionStateResult {
+ return { ok: false, error: { code: "unauthenticated" } };
+}
+
+function readLocalStorageItem(key: string): SessionStateResult {
+ if (typeof window === "undefined") return unavailable();
+ try {
+ return { ok: true, value: window.localStorage.getItem(key) };
+ } catch {
+ return { ok: false, error: { code: "storage", key } };
+ }
+}
+
+function restoreLocalStorageItem(key: string, value: string | null): void {
+ try {
+ if (value === null) window.localStorage.removeItem(key);
+ else window.localStorage.setItem(key, value);
+ } catch {
+ return;
+ }
+}
+
+/**
+ * Persist login tokens. When `resumeId` is present (from the login page's
+ * `?resume=` param, set when a 401 bounced the user here mid-flow), the
+ * preserved form state for that resume group is restored transactionally;
+ * otherwise any leftover preserved state is cleared. On any failure the
+ * previous tokens are restored so a half-applied login never sticks.
+ */
+export function storeSession(
+ tokens: LoginResponse,
+ resumeId?: string,
+): SessionStateResult {
+ if (typeof window === "undefined") return unavailable();
+ if (!tokens?.access_token) return invalidSession();
+
+ invalidateRefresh();
+ const previousAccess = readLocalStorageItem(ACCESS_TOKEN_KEY);
+ const previousRefresh = readLocalStorageItem(REFRESH_TOKEN_KEY);
+ if (!previousAccess.ok) return previousAccess;
+ if (!previousRefresh.ok) return previousRefresh;
+
+ try {
window.localStorage.setItem(ACCESS_TOKEN_KEY, tokens.access_token);
+ if (tokens.refresh_token) {
+ window.localStorage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
+ } else {
+ window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+ }
+ } catch {
+ restoreLocalStorageItem(ACCESS_TOKEN_KEY, previousAccess.value);
+ restoreLocalStorageItem(REFRESH_TOKEN_KEY, previousRefresh.value);
+ return { ok: false, error: { code: "storage" } };
}
- if (tokens.refresh_token) {
- window.localStorage.setItem(REFRESH_TOKEN_KEY, tokens.refresh_token);
- } else {
- window.localStorage.removeItem(REFRESH_TOKEN_KEY);
+
+ const stateResult = resumeId
+ ? consumeSessionResume(resumeId, tokens.access_token)
+ : clearAllSessionState();
+ if (!stateResult.ok) {
+ restoreLocalStorageItem(ACCESS_TOKEN_KEY, previousAccess.value);
+ restoreLocalStorageItem(REFRESH_TOKEN_KEY, previousRefresh.value);
+ return { ok: false, error: stateResult.error };
}
+ return { ok: true, value: undefined };
}
export { clearSession } from "./api-client";
@@ -62,6 +126,17 @@ function removeLocalePrefix(pathname: string): string {
return segments.length > 1 ? `/${segments.slice(1).join("/")}` : "/";
}
+/**
+ * Resolve the `?redirect=` param that the protected-route 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 default post-login
+ * path, 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 {
if (!raw || !raw.startsWith("/")) return DEFAULT_POST_LOGIN_PATH;
if (raw.startsWith("//") || raw.startsWith("/\\")) {
diff --git a/frontend/lib/bundle-config.ts b/frontend/lib/bundle-config.ts
index 91bea31b..b8c50867 100644
--- a/frontend/lib/bundle-config.ts
+++ b/frontend/lib/bundle-config.ts
@@ -1,7 +1,8 @@
-export interface BundleConfig {
- dynamicImportHeavyDeps: boolean;
-}
-
-export const bundleConfig: BundleConfig = {
- dynamicImportHeavyDeps: true,
-};
+/**
+ * The map route owns the application’s intentional client-only bundle split.
+ * Leaflet and the map content depend on browser APIs, so the boundary must
+ * remain `ssr: false`; the policy lives at the actual dynamic import site.
+ */
+export const clientOnlyBundleBoundary = {
+ ssr: false,
+} as const;
diff --git a/frontend/lib/image-loader.ts b/frontend/lib/image-loader.ts
index 8ad7bd65..acd0f91a 100644
--- a/frontend/lib/image-loader.ts
+++ b/frontend/lib/image-loader.ts
@@ -1,5 +1,77 @@
-export function getOptimizedImageUrl(src: string, width = 300, quality = 75): string {
- if (!src) return '';
- if (src.startsWith('data:') || src.startsWith('blob:')) return src;
- return `${src}?w=${width}&q=${quality}`;
+import type { ImageLoader } from "next/image";
+
+const NEXT_IMAGE_PATH = "/_next/image";
+const DEFAULT_QUALITY = 75;
+const SIGNED_QUERY_KEYS = new Set([
+ "signature",
+ "sig",
+ "token",
+ "expires",
+ "policy",
+ "key-pair-id",
+ "x-amz-signature",
+ "x-amz-credential",
+ "x-amz-date",
+ "x-amz-security-token",
+]);
+
+/**
+ * Build URLs through Next's built-in image optimizer. That endpoint negotiates
+ * WebP (or another configured format) from the request's Accept header. A
+ * custom loader has a single-string contract, so it cannot expose a separate
+ * fallback itself; callers needing one must provide it explicitly.
+ *
+ * Signed image URLs are returned unchanged. Proxying or rewriting those URLs
+ * can invalidate provider signatures, and the original URL is the safe
+ * unoptimized source when its signature is opaque to this application; it is
+ * not a separate browser-format fallback. Non-local HTTP
+ * sources still need an explicit `images.remotePatterns` entry before Next's
+ * optimizer will fetch them.
+ */
+function buildNextImageUrl(
+ src: string,
+ width: number,
+ quality = DEFAULT_QUALITY,
+): string {
+ if (!src || src.startsWith("data:") || src.startsWith("blob:")) return src;
+ if (src.startsWith("//")) {
+ throw new Error("Protocol-relative image URLs are not supported");
+ }
+
+ const hashIndex = src.indexOf("#");
+ const source = hashIndex === -1 ? src : src.slice(0, hashIndex);
+ const fragment = hashIndex === -1 ? "" : src.slice(hashIndex);
+ const queryIndex = source.indexOf("?");
+ const query = queryIndex === -1 ? "" : source.slice(queryIndex + 1);
+ const isSigned = [...new URLSearchParams(query).keys()].some((key) => {
+ const normalizedKey = key.toLowerCase();
+ return (
+ SIGNED_QUERY_KEYS.has(normalizedKey) ||
+ normalizedKey.startsWith("x-amz-")
+ );
+ });
+
+ const isNextImageUrl =
+ source === NEXT_IMAGE_PATH || source.startsWith(`${NEXT_IMAGE_PATH}?`);
+ if (isSigned || isNextImageUrl) return src;
+
+ const params = new URLSearchParams();
+ params.set("url", source);
+ params.set("w", String(width));
+ params.set("q", String(quality));
+
+ return `${NEXT_IMAGE_PATH}?${params.toString()}${fragment}`;
}
+
+export function getOptimizedImageUrl(
+ src: string,
+ width = 300,
+ quality = DEFAULT_QUALITY,
+): string {
+ return buildNextImageUrl(src, width, quality);
+}
+
+const imageLoader: ImageLoader = ({ src, width, quality }) =>
+ buildNextImageUrl(src, width, quality);
+
+export default imageLoader;
diff --git a/frontend/lib/session-expiry-warning.ts b/frontend/lib/session-expiry-warning.ts
index b62dc203..3f5f131b 100644
--- a/frontend/lib/session-expiry-warning.ts
+++ b/frontend/lib/session-expiry-warning.ts
@@ -1,33 +1,86 @@
"use client";
-import { useEffect, useRef, useCallback } from "react";
+import { useCallback, useEffect, useRef } from "react";
+import { clearSession } from "@/lib/api-client";
const ACCESS_TOKEN_KEY = "auth-token";
+const WARNING_BEFORE_MS = 5 * 60 * 1000;
+const ACTIVITY_GRACE_MS = 60 * 1000;
+const ACTIVITY_DEBOUNCE_MS = 250;
+const ACTIVITY_EVENTS = [
+ "keydown",
+ "beforeinput",
+ "input",
+ "focusin",
+ "pointerdown",
+ "mousedown",
+ "click",
+] as const;
+
+function decodeBase64Url(value: string): string | null {
+ try {
+ const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+ const padding = (4 - (normalized.length % 4)) % 4;
+ const binary = atob(normalized + "=".repeat(padding));
+ if (typeof TextDecoder === "undefined") return binary;
+ const bytes = Uint8Array.from(binary, (character) =>
+ character.charCodeAt(0),
+ );
+ return new TextDecoder().decode(bytes);
+ } catch {
+ return null;
+ }
+}
-// ── JWT expiry helper ───────────────────────────────────────────────────────
+export function getTokenExpiryMs(token: string): number | null {
+ const payloadPart = token.split(".")[1];
+ if (!payloadPart) return null;
+ const decoded = decodeBase64Url(payloadPart);
+ if (!decoded) return null;
-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
+ const payload: unknown = JSON.parse(decoded);
+ if (
+ typeof payload !== "object" ||
+ payload === null ||
+ !("exp" in payload) ||
+ typeof payload.exp !== "number" ||
+ !Number.isFinite(payload.exp)
+ ) {
+ return null;
+ }
return payload.exp * 1000 - Date.now();
} catch {
return null;
}
}
-// ── Cross-tab logout sync ───────────────────────────────────────────────────
+function readAccessToken(): string | null {
+ if (typeof window === "undefined") return null;
+ try {
+ return window.localStorage.getItem(ACCESS_TOKEN_KEY);
+ } catch {
+ return null;
+ }
+}
+
+function isEditingTarget(target: EventTarget | null): boolean {
+ if (!(target instanceof HTMLElement)) return false;
+ return (
+ target.isContentEditable ||
+ target instanceof HTMLInputElement ||
+ target instanceof HTMLTextAreaElement ||
+ target instanceof HTMLSelectElement ||
+ target.getAttribute("role") === "textbox"
+ );
+}
-/**
- * Listen for the `logout-event` localStorage key written by clearSession()
- * in other tabs and redirect to login. Call once on app bootstrap.
- */
export function initCrossTabLogoutSync(): () => void {
if (typeof window === "undefined") return () => {};
function handler(event: StorageEvent) {
if (event.key === "logout-event" && event.newValue) {
+ clearSession({ notify: false });
window.location.href = "/login";
}
}
@@ -36,77 +89,162 @@ export function initCrossTabLogoutSync(): () => void {
return () => window.removeEventListener("storage", handler);
}
-// ── Session expiry warning hook ─────────────────────────────────────────────
-
-const WARNING_BEFORE_MS = 5 * 60 * 1000; // warn 5 minutes before expiry
-
-interface UseSessionExpiryWarningOptions {
- /** Called when the user clicks "Stay signed in" — should trigger a refresh. */
- onRefresh: () => Promise;
- /** Whether the user is currently authenticated (skip if false). */
+export interface UseSessionExpiryWarningOptions {
+ onRefresh?: () => Promise;
enabled?: boolean;
}
-/**
- * Polls the access token's `exp` claim and prompts the user with a
- * "Stay signed in?" dialog a few minutes before the session expires.
- *
- * If the user confirms, calls `onRefresh`. If they dismiss or the token
- * expires, the consumer should handle the redirect (the api-client's 401
- * interceptor will do this automatically on the next request).
- */
export function useSessionExpiryWarning({
onRefresh,
enabled = true,
}: UseSessionExpiryWarningOptions) {
+ const onRefreshRef = useRef(onRefresh);
+ onRefreshRef.current = onRefresh;
+ const warningTokenRef = useRef(null);
const warningShownRef = useRef(false);
const promptRef = useRef | null>(null);
+ const activityDebounceRef = useRef | null>(null);
+ const lastActivityAtRef = useRef(null);
- const clearTimer = useCallback(() => {
+ const clearTimers = useCallback(() => {
if (promptRef.current !== null) {
clearTimeout(promptRef.current);
promptRef.current = null;
}
+ if (activityDebounceRef.current !== null) {
+ clearTimeout(activityDebounceRef.current);
+ activityDebounceRef.current = null;
+ }
}, []);
useEffect(() => {
if (!enabled || typeof window === "undefined") return;
- function schedulePrompt() {
- clearTimer();
-
- const token = window.localStorage.getItem(ACCESS_TOKEN_KEY);
+ let disposed = false;
+ warningShownRef.current = false;
+ lastActivityAtRef.current = null;
+ const listenerOptions: AddEventListenerOptions = { capture: true };
+
+ function schedulePrompt(
+ afterActivity = false,
+ activityAt?: number,
+ ) {
+ if (promptRef.current !== null) {
+ clearTimeout(promptRef.current);
+ promptRef.current = null;
+ }
+ if (disposed) return;
+
+ const token = readAccessToken();
if (!token) return;
-
- const remainingMs = getTokenExpiryMs(token);
- if (remainingMs === null || remainingMs <= 0) return;
-
- const delayMs = Math.max(remainingMs - WARNING_BEFORE_MS, 0);
+ if (warningTokenRef.current !== token) {
+ warningTokenRef.current = token;
+ warningShownRef.current = false;
+ }
+ if (warningShownRef.current) return;
+
+ const now = Date.now();
+ const currentRemainingMs = getTokenExpiryMs(token);
+ if (currentRemainingMs === null || currentRemainingMs <= 0) return;
+ const remainingAtReference =
+ currentRemainingMs +
+ (afterActivity && activityAt !== undefined
+ ? Math.max(0, now - activityAt)
+ : 0);
+ if (remainingAtReference <= 0) return;
+ const warningDelayAtReference = Math.max(
+ remainingAtReference - WARNING_BEFORE_MS,
+ 0,
+ );
+ const delayMs = afterActivity
+ ? Math.min(
+ remainingAtReference,
+ warningDelayAtReference + ACTIVITY_GRACE_MS,
+ )
+ : warningDelayAtReference;
promptRef.current = setTimeout(() => {
+ promptRef.current = null;
+ if (disposed) return;
+
+ const currentToken = readAccessToken();
+ if (currentToken !== token) {
+ warningTokenRef.current = null;
+ warningShownRef.current = false;
+ lastActivityAtRef.current = null;
+ schedulePrompt();
+ return;
+ }
if (warningShownRef.current) return;
+ warningTokenRef.current = token;
warningShownRef.current = true;
- // Simple confirm dialog — can be replaced with a custom UI later
- const staySignedIn = window.confirm(
- "Your session is about to expire. Stay signed in?",
- );
-
- if (staySignedIn) {
- onRefresh()
- .then(() => {
- warningShownRef.current = false;
- schedulePrompt();
- })
- .catch(() => {
- // Refresh failed — api-client will redirect on next 401
- });
+ let staySignedIn = false;
+ try {
+ staySignedIn = window.confirm(
+ "Your session is about to expire. Stay signed in?",
+ );
+ } catch {
+ return;
}
+ if (!staySignedIn) return;
+
+ const refresh = onRefreshRef.current;
+ if (!refresh) return;
+ Promise.resolve()
+ .then(() => refresh())
+ .then(() => {
+ if (disposed) return;
+ warningTokenRef.current = null;
+ warningShownRef.current = false;
+ schedulePrompt();
+ })
+ .catch(() => {
+ if (disposed) return;
+ warningTokenRef.current = null;
+ warningShownRef.current = false;
+ schedulePrompt(true);
+ });
}, delayMs);
}
- schedulePrompt();
+ function handleActivity(event: Event) {
+ const activeElement = document.activeElement;
+ const editingEvent =
+ isEditingTarget(event.target) ||
+ ((event.type === "click" ||
+ event.type === "pointerdown" ||
+ event.type === "mousedown") &&
+ isEditingTarget(activeElement));
+ if (!editingEvent) return;
+
+ const activityAt = Date.now();
+ lastActivityAtRef.current = activityAt;
+ if (promptRef.current !== null) {
+ clearTimeout(promptRef.current);
+ promptRef.current = null;
+ }
+ if (activityDebounceRef.current !== null) {
+ clearTimeout(activityDebounceRef.current);
+ }
+ activityDebounceRef.current = setTimeout(() => {
+ activityDebounceRef.current = null;
+ schedulePrompt(true, lastActivityAtRef.current ?? activityAt);
+ }, ACTIVITY_DEBOUNCE_MS);
+ }
- return clearTimer;
- }, [enabled, onRefresh, clearTimer]);
+ schedulePrompt();
+ ACTIVITY_EVENTS.forEach((eventName) => {
+ window.addEventListener(eventName, handleActivity, listenerOptions);
+ });
+
+ return () => {
+ disposed = true;
+ ACTIVITY_EVENTS.forEach((eventName) => {
+ window.removeEventListener(eventName, handleActivity, listenerOptions);
+ });
+ lastActivityAtRef.current = null;
+ clearTimers();
+ };
+ }, [enabled, clearTimers]);
}
diff --git a/frontend/lib/session-state-preserver.ts b/frontend/lib/session-state-preserver.ts
index a5cbf70b..8a819c1a 100644
--- a/frontend/lib/session-state-preserver.ts
+++ b/frontend/lib/session-state-preserver.ts
@@ -1,55 +1,627 @@
/**
- * Simple helper to preserve in-progress form and upload state across a
- * session-expiry redirect.
+ * Transactional storage for JSON-only form state across an authentication
+ * redirect. State is bound to the current access token and to a one-time
+ * resume group; a resume commit requires JWT `sub` claims and verifies that
+ * the replacement token belongs to the same subject. Use
+ * readSessionState followed by commitSessionState when a value can fail while
+ * it is being applied; consumeSessionResume returns restored values while
+ * removing the pending group transactionally. restoreSessionState is the
+ * one-shot consume variant.
*
- * Usage:
- * // Before the redirect (e.g. in a form component):
- * preserveSessionState("upload-form", { file: fileData, annotations: [...] });
- *
- * // After login, restore:
- * const saved = restoreSessionState("upload-form");
- * if (saved) { /* repopulate form */ }
- *
- * State is stored in sessionStorage so it survives a redirect but is
- * automatically cleared when the tab is closed.
+ * File and Blob instances are intentionally rejected because JSON does not
+ * preserve their bytes. Preserve metadata such as a file name and obtain the
+ * original file again through the upload flow.
*/
const SESSION_STATE_PREFIX = "smalda-session-state:";
+const PENDING_RESUMES_KEY = `${SESSION_STATE_PREFIX}__pending__`;
+const ACCESS_TOKEN_KEY = "auth-token";
+const STORAGE_VERSION = 1;
-/**
- * Save in-progress state before a session-expiry redirect.
- * Serializes to JSON and stores in sessionStorage.
- */
-export function preserveSessionState(
+export type JsonValue =
+ | string
+ | number
+ | boolean
+ | null
+ | JsonValue[]
+ | { [key: string]: JsonValue };
+
+export type SessionStateErrorCode =
+ | "invalid-key"
+ | "unavailable"
+ | "unauthenticated"
+ | "not-found"
+ | "serialization"
+ | "storage"
+ | "parse"
+ | "session-mismatch"
+ | "resume-not-found"
+ | "removal";
+
+export interface SessionStateError {
+ code: SessionStateErrorCode;
+ key?: string;
+}
+
+export type SessionStateResult =
+ | { ok: true; value: T }
+ | { ok: false; error: SessionStateError };
+
+interface StoredSessionState {
+ version: typeof STORAGE_VERSION;
+ key: string;
+ resumeId: string;
+ sessionId: string;
+ subject: string | null;
+ state: JsonValue;
+}
+
+interface PendingResume {
+ resumeId: string;
+ keys: string[];
+}
+
+interface StorageWrite {
+ key: string;
+ value: string | null;
+}
+
+function failure(
+ code: SessionStateErrorCode,
+ key?: string,
+): SessionStateResult {
+ return { ok: false, error: key ? { code, key } : { code } };
+}
+
+function propagateFailure(
+ result: { ok: false; error: SessionStateError },
+): SessionStateResult {
+ return result;
+}
+
+function getStateKey(key: string): string {
+ return `${SESSION_STATE_PREFIX}${key}`;
+}
+
+function getStorage(): Storage | null {
+ if (typeof window === "undefined") return null;
+ try {
+ return window.sessionStorage;
+ } catch {
+ return null;
+ }
+}
+
+function readAccessToken(): SessionStateResult {
+ if (typeof window === "undefined") return failure("unavailable");
+ try {
+ return { ok: true, value: window.localStorage.getItem(ACCESS_TOKEN_KEY) };
+ } catch {
+ return failure("storage", ACCESS_TOKEN_KEY);
+ }
+}
+
+function readItem(
+ storage: Storage,
key: string,
- state: T,
+): SessionStateResult {
+ try {
+ return { ok: true, value: storage.getItem(key) };
+ } catch {
+ return failure("storage", key);
+ }
+}
+
+function writeItem(
+ storage: Storage,
+ key: string,
+ value: string,
+): SessionStateResult {
+ try {
+ storage.setItem(key, value);
+ return { ok: true, value: undefined };
+ } catch {
+ return failure("storage", key);
+ }
+}
+
+function removeItem(
+ storage: Storage,
+ key: string,
+): SessionStateResult {
+ try {
+ storage.removeItem(key);
+ return { ok: true, value: undefined };
+ } catch {
+ return failure("removal", key);
+ }
+}
+
+function restoreItem(
+ storage: Storage,
+ key: string,
+ previousValue: string | null,
): void {
- if (typeof window === "undefined") return;
try {
- window.sessionStorage.setItem(
- `${SESSION_STATE_PREFIX}${key}`,
- JSON.stringify(state),
- );
+ if (previousValue === null) storage.removeItem(key);
+ else storage.setItem(key, previousValue);
} catch {
- // sessionStorage full or unavailable — best-effort only
+ // Rollback is best effort; the original failure is returned to the caller.
}
}
-/**
- * Restore previously-saved state after login. Returns null if nothing was
- * saved under the given key. Clears the stored state after reading so it
- * isn't restored twice.
- */
-export function restoreSessionState(
+function isRecord(value: unknown): value is Record {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isJsonValue(value: unknown, ancestors = new Set