feat(sync): verify LatestNews API key before saving

Author: bruceblink

shared/synchub-contract.ts

@@ -18,3 +18,29 @@ export function syncHubHeaders(apiKey: string) {
         "X-API-Key": apiKey.trim(),
     };
 }
+
+export type SyncHubConnectionResult = { ok: true; message: string } | { ok: false; message: string };
+
+export async function verifyLatestNewsSyncHubConnection(
+    endpoint: string,
+    apiKey: string,
+    fetcher: typeof fetch = fetch
+): Promise<SyncHubConnectionResult> {
+    const normalizedKey = apiKey.trim();
+    if (!normalizedKey.startsWith("shk_")) {
+        return { ok: false, message: "请输入有效的 LatestNews API Key" };
+    }
+
+    try {
+        const response = await fetcher(latestNewsSyncHubURL(endpoint, "favorites"), {
+            headers: syncHubHeaders(normalizedKey),
+        });
+        const result = (await response.json()) as { code?: number | string; message?: string };
+        if (response.ok || (response.status === 404 && result.code === "NOT_FOUND")) {
+            return { ok: true, message: "连接成功，API Key 可用于 LatestNews 同步" };
+        }
+        return { ok: false, message: result.message || `连接失败（HTTP ${response.status}）` };
+    } catch {
+        return { ok: false, message: "无法连接 SyncHub，请检查服务地址和网络" };
+    }
+}

src/routes/history.tsx

@@ -13,6 +13,7 @@ import { useRelativeTime } from "~/hooks/useRelativeTime";
 import { useReadingState } from "~/hooks/useReadingState";
 import { getReadingStateList } from "@shared/reading-state";
 import { formatReadingHistoryExport } from "@shared/history-export";
+import { verifyLatestNewsSyncHubConnection } from "@shared/synchub-contract";
 import { filterReadingHistory, hasReadingHistoryFilters } from "@shared/history-filter";
 import {
     getSyncHubConfig,
@@ -78,6 +79,7 @@ function HistoryPage() {
     const [stateTab, setStateTab] = useState<HistoryTab>("history");
     const [syncHubEndpoint, setSyncHubEndpoint] = useState(() => getSyncHubConfig().endpoint);
     const [syncHubApiKey, setSyncHubApiKey] = useState(() => getSyncHubConfig().apiKey);
+    const [syncHubChecking, setSyncHubChecking] = useState(false);
 
     const sourceOptions = useMemo(() => {
         const map = new Map<string, { count: number; name: string }>();
@@ -182,20 +184,28 @@ function HistoryPage() {
                     className="min-w-0 rounded-xl border border-zinc-200 bg-white px-3 py-2 text-sm outline-none focus:border-cyan-500 dark:border-zinc-700 dark:bg-zinc-800"
                 />
                 <input
+                    type="password"
                     value={syncHubApiKey}
                     onChange={(event) => setSyncHubApiKey(event.target.value)}
                     placeholder="LatestNews API Key (shk_...)"
                     className="min-w-0 rounded-xl border border-zinc-200 bg-white px-3 py-2 text-sm outline-none focus:border-cyan-500 dark:border-zinc-700 dark:bg-zinc-800"
                 />
                 <button
                     type="button"
+                    disabled={syncHubChecking}
                     onClick={() => {
-                        saveSyncHubConfig({ endpoint: syncHubEndpoint, apiKey: syncHubApiKey });
-                        window.location.reload();
+                        setSyncHubChecking(true);
+                        void verifyLatestNewsSyncHubConnection(syncHubEndpoint, syncHubApiKey).then((result) => {
+                            setSyncHubChecking(false);
+                            toaster(result.message, { type: result.ok ? "success" : "error" });
+                            if (!result.ok) return;
+                            saveSyncHubConfig({ endpoint: syncHubEndpoint, apiKey: syncHubApiKey });
+                            window.location.reload();
+                        });
                     }}
-                    className="rounded-xl bg-cyan-500 px-3 py-2 text-sm font-medium text-zinc-900"
+                    className="rounded-xl bg-cyan-500 px-3 py-2 text-sm font-medium text-zinc-900 disabled:cursor-wait disabled:opacity-60"
                 >
-                    保存同步
+                    {syncHubChecking ? "正在验证" : "验证并保存"}
                 </button>
                 {(syncHubEndpoint !== defaultSyncHubEndpoint || syncHubApiKey) && (
                     <button

test/synchub-service.test.ts

@@ -6,6 +6,7 @@ import {
     defaultSyncHubEndpoint,
     normalizeSyncHubEndpoint,
     latestNewsSyncHubCollections,
+    verifyLatestNewsSyncHubConnection,
 } from "../shared/synchub-contract";
 
 describe("SyncHub service contract", () => {
@@ -15,6 +16,43 @@ describe("SyncHub service contract", () => {
         expect(normalizeSyncHubEndpoint(" https://self-hosted.example/ ")).toBe("https://self-hosted.example");
     });
 
+    it("verifies an application-bound API key before saving", async () => {
+        const fetcher = async (input: string | URL | Request, init?: RequestInit) => {
+            expect(input).toBe("https://sync.likanug.app/api/v1/metadata/latestnews/favorites");
+            expect(init?.headers).toEqual({
+                "Content-Type": "application/json",
+                "X-API-Key": "shk_latestnews",
+            });
+            return new Response(JSON.stringify({ code: 0, message: "ok", data: { payload: [] } }), {
+                status: 200,
+            });
+        };
+
+        await expect(verifyLatestNewsSyncHubConnection("", " shk_latestnews ", fetcher)).resolves.toEqual({
+            ok: true,
+            message: "连接成功，API Key 可用于 LatestNews 同步",
+        });
+    });
+
+    it("accepts an authenticated empty collection and reports rejected keys", async () => {
+        const emptyFetcher = async () =>
+            new Response(JSON.stringify({ code: "NOT_FOUND", message: "metadata document not found" }), {
+                status: 404,
+            });
+        await expect(
+            verifyLatestNewsSyncHubConnection("https://sync.example/", "shk_valid", emptyFetcher)
+        ).resolves.toMatchObject({ ok: true });
+
+        const rejectedFetcher = async () =>
+            new Response(JSON.stringify({ code: "UNAUTHENTICATED", message: "invalid api key" }), {
+                status: 401,
+            });
+        await expect(verifyLatestNewsSyncHubConnection("", "shk_rejected", rejectedFetcher)).resolves.toEqual({
+            ok: false,
+            message: "invalid api key",
+        });
+    });
+
     it("uses the LatestNews application route and API key header", async () => {
         expect(latestNewsSyncHubCollections).toEqual(["reading-history", "favorites", "preferences"]);
         expect(latestNewsSyncHubURL("https://sync.likanug.app/", "favorites")).toBe(