feat: add extension bridge key management and desktop pet widget

- Implemented commands for generating, retrieving, and rotating an extension bridge key using UUIDs and HMAC-SHA256 for signature verification.
- Added a new PetWidget component that displays a customizable desktop pet with state management, including focus and idle states, and interaction messages.
- Introduced a fallback manifest for the pet widget to ensure graceful degradation when manifest data is missing.

Author: PythonSmall-Q

CHANGELOG.md

@@ -5,6 +5,58 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.4.0] - 2026-05-16
+
+### Added
+
+#### Extension Bridge Authentication
+
+- **Extension bridge key management** — the desktop app now generates a shared bridge key on first launch, stores it locally, and exposes it in Settings with copy and rotate actions
+- **Capability negotiation for extension auth** — VS Code and browser extensions now probe the desktop API before signing requests, so old app versions without bridge auth support do not receive key-protected traffic
+- **VS Code extension key entry** — the extension now includes an input command and settings key for saving, updating, and reusing the bridge key
+- **Browser extension key entry** — the browser popup now keeps the bridge key field visible, auto-fills the saved key, and allows users to modify and re-save it at any time
+
+#### Desktop Pet / Widget Center
+
+- **Desktop pet widget** — added a built-in manifest-driven desktop pet widget with idle / focus / rest states and tap messages
+- **Pet resource pack import** — users can import JSON pet packs and apply the manifest to all existing pet widgets from a prominent entry in Widget Center
+- **Pet size controls** — Widget Center now exposes a visible pet settings panel for adjusting default pet window width and height in bulk
+- **Pet default sizing** — the default pet window size was increased to better match the richer pet UI
+
+#### Data Migration and Compatibility
+
+- **Legacy database migration** — Windows startup now detects the old Roaming data directory and automatically copies the legacy database into the new app data location, including SQLite `-wal` / `-shm` sidecar files
+- **Fallback compatibility** — [Crucial] older data directories remain readable during the transition so existing users do not hit a blank or empty state after the 1.2.0 path change
+
+#### Widget Center / Registry
+
+- **Widget Center pet section** — the widget marketplace now surfaces the pet widget more prominently alongside the official widget catalog
+- **Widget registry alignment** — built-in pet registry sizing was aligned with the new default pet window dimensions
+
+### Changed
+
+#### Local API and Sync Flow
+
+- **Local API status payload expanded** — `/api/status` now advertises whether extension bridge authentication is required so clients can decide whether to send signed traffic
+- **Signed request flow tightened** — both extensions only attach signatures when the desktop API explicitly declares support, preventing bridge-key traffic from reaching older app builds
+
+#### Settings UX
+
+- **Settings bridge section** — the desktop Settings page now shows the bridge key in full, supports one-click copy, and lets users rotate the key without leaving the page
+- **Browser and VS Code key UX** — both extensions now emphasize that the bridge key can be updated after initial save instead of being a one-time setup
+
+#### Default Widget Behavior
+
+- **Pet widget startup size** — the pet widget defaults were updated in both registry metadata and tray-based widget creation paths so new windows open at a more natural size
+
+### Fixed
+
+- Fixed browser and VS Code extensions sending bridge signatures to older desktop API versions that did not support key-based auth
+- Fixed pet widget sizing being too tight for the richer built-in manifest-based UI
+- Fixed legacy Windows users from landing on an empty database path after the app data migration change
+- Fixed the browser extension key field being hidden after save, which made updating the saved key awkward
+
+
 ## [1.2.0] - 2026-05-10
 
 ### Added

browser-extension (2).zip

@@ -3,9 +3,18 @@
     "message": "TimeLens Browser Companion"
   },
   "extensionDescription": {
-    "message": "Companion extension for TimeLens. Tracks active tab sessions, detects idle time, and syncs browser usage data to the local desktop app."
+    "message": "TimeLens browser companion that tracks tab sessions and syncs browser usage to the desktop app."
   },
   "extensionActionTitle": {
     "message": "TimeLens Browser Companion"
+  },
+  "extensionBridgeKey": {
+    "message": "Extension bridge key"
+  },
+  "bridgeKeyHint": {
+    "message": "Get the key from TimeLens Settings > Local API / Extension Bridge."
+  },
+  "save": {
+    "message": "Save"
   }
 }

browser-extension/_locales/en/messages.json

@@ -7,5 +7,14 @@
   },
   "extensionActionTitle": {
     "message": "TimeLens 浏览器伴侣"
+  },
+  "extensionBridgeKey": {
+    "message": "扩展网桥密钥"
+  },
+  "bridgeKeyHint": {
+    "message": "从 TimeLens 设置 > 本地 API / 扩展网桥中获取密钥。"
+  },
+  "save": {
+    "message": "保存"
   }
 }

browser-extension/_locales/zh_CN/messages.json

@@ -26,6 +26,7 @@ const STORAGE_KEYS = {
 const MAX_RECENT_SESSIONS   = 100;
 const MAX_PENDING_SESSIONS  = 200;
 const API_BASE              = "http://127.0.0.1:49152";
+let authRequiredCache = { value: false, expiresAt: 0 };
 
 // Consider the user idle after 60 s without mouse/keyboard input.
 const IDLE_THRESHOLD_SECONDS = 60;
@@ -274,21 +275,31 @@ async function flushPendingSessions() {
 
 async function syncSessionToDesktop(session) {
   try {
+    const bridgeKey = await getBridgeKey();
+    const body = JSON.stringify({
+      browser_name: session.browserName,
+      tab_url: session.url,
+      host: session.host || "",
+      title: session.title || "",
+      started_at: new Date(session.startedAt).toISOString(),
+      ended_at: new Date(session.endedAt).toISOString(),
+      duration_seconds: Math.max(0, Math.round((session.durationMs || 0) / 1000)),
+      locale: session.locale || getLocale(),
+    });
+
+    const headers = {
+      "Content-Type": "application/json",
+    };
+
+    // Only attach signature when desktop API explicitly requires bridge auth.
+    if (bridgeKey && await shouldAttachBridgeSignature()) {
+      headers["X-Extension-Signature"] = await signRequestBody(body, bridgeKey);
+    }
+
     const response = await fetch(`${API_BASE}/api/browser/session`, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        browser_name: session.browserName,
-        tab_url: session.url,
-        host: session.host || "",
-        title: session.title || "",
-        started_at: new Date(session.startedAt).toISOString(),
-        ended_at: new Date(session.endedAt).toISOString(),
-        duration_seconds: Math.max(0, Math.round((session.durationMs || 0) / 1000)),
-        locale: session.locale || getLocale(),
-      }),
+      headers,
+      body,
     });
 
     if (!response.ok) {
@@ -342,3 +353,64 @@ async function pingApiStatus() {
     });
   }
 }
+
+/**
+ * Old desktop APIs do not expose auth capability. In that case default to false
+ * and do not send key/signature headers.
+ */
+async function shouldAttachBridgeSignature() {
+  const now = Date.now();
+  if (authRequiredCache.expiresAt > now) {
+    return authRequiredCache.value;
+  }
+
+  try {
+    const response = await fetch(`${API_BASE}/api/status`);
+    if (!response.ok) {
+      authRequiredCache = { value: false, expiresAt: now + 30_000 };
+      return false;
+    }
+    const data = await response.json();
+    const required = data?.extension_bridge_auth_required === true;
+    authRequiredCache = { value: required, expiresAt: now + 30_000 };
+    return required;
+  } catch {
+    authRequiredCache = { value: false, expiresAt: now + 15_000 };
+    return false;
+  }
+}
+
+/**
+ * Get the stored extension bridge key from local storage
+ */
+async function getBridgeKey() {
+  const { "timelens.bridgeKey": key } = await chrome.storage.local.get("timelens.bridgeKey");
+  return key || "";
+}
+
+/**
+ * Sign a request body using HMAC-SHA256
+ * @param {string} body - The request body JSON string
+ * @param {string} key - The bridge key
+ * @returns {Promise<string>} The hex-encoded HMAC signature
+ */
+async function signRequestBody(body, key) {
+  // Use SubtleCrypto API available in Service Workers
+  const encoder = new TextEncoder();
+  const keyData = encoder.encode(key);
+  const bodyData = encoder.encode(body);
+
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+
+  const signature = await crypto.subtle.sign("HMAC", cryptoKey, bodyData);
+  const signatureArray = new Uint8Array(signature);
+  return Array.from(signatureArray)
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}

browser-extension/background.js

@@ -22,6 +22,13 @@ const TRANSLATIONS = {
     activeTab: "Active tab",
     unknownSite: "Unknown site",
     extensionDisabled: "Desktop app has browser sync disabled.",
+    extensionBridgeKey: "Extension bridge key",
+    bridgeKeyHint: "Get the key from TimeLens Settings > Local API / Extension Bridge.",
+    bridgeKeyPlaceholder: "Paste extension bridge key from TimeLens Settings",
+    save: "Save",
+    saveOrUpdate: "Save / Update",
+    bridgeKeySaved: "Extension bridge key saved successfully.",
+    bridgeKeyCleared: "Extension bridge key cleared.",
   },
   "zh-CN": {
     connection: "桌面端连接",
@@ -46,6 +53,13 @@ const TRANSLATIONS = {
     activeTab: "活动标签页",
     unknownSite: "未知站点",
     extensionDisabled: "桌面端已关闭浏览器同步。",
+    extensionBridgeKey: "扩展网桥密钥",
+    bridgeKeyHint: "从 TimeLens 设置 > 本地 API / 扩展网桥中获取密钥。",
+    bridgeKeyPlaceholder: "粘贴从 TimeLens 设置中获取的扩展网桥密钥",
+    save: "保存",
+    saveOrUpdate: "保存/更新",
+    bridgeKeySaved: "扩展网桥密钥已保存。",
+    bridgeKeyCleared: "扩展网桥密钥已清除。",
   },
 };
 

browser-extension/i18n.js

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "__MSG_extensionName__",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "__MSG_extensionDescription__",
   "default_locale": "en",
   "permissions": ["storage", "tabs", "alarms", "idle"],

browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "timelens-browser-extension",
   "version": "1.1.0",
-  "description": "Browser companion for TimeLens — tracks tab sessions and syncs screen-time data with the desktop app.",
+  "description": "TimeLens browser companion that tracks tab sessions and syncs browser usage to the desktop app.",
   "scripts": {
     "lint": "web-ext lint --source-dir .",
     "build": "web-ext build --source-dir . --artifacts-dir dist --overwrite-dest",

browser-extension/package.json

@@ -22,6 +22,22 @@ <h2 data-i18n="connection">Desktop connection</h2>
         <p id="status-text" class="muted">Trying to reach the local TimeLens API.</p>
       </section>
 
+      <section id="bridge-key-panel" class="panel">
+        <div class="panel-head">
+          <h2 data-i18n="extensionBridgeKey">Extension bridge key</h2>
+        </div>
+        <div style="display: flex; gap: 8px;">
+          <input
+            id="bridge-key-input"
+            type="password"
+            placeholder="Paste extension bridge key from TimeLens Settings"
+            style="flex: 1; padding: 8px; border: 1px solid #ccc; border-radius: 4px; font-size: 12px;"
+          />
+          <button id="save-key-button" class="ghost-button" type="button" data-i18n="saveOrUpdate">Save / Update</button>
+        </div>
+        <p class="muted" style="margin-top: 8px; font-size: 11px;" data-i18n="bridgeKeyHint">Get the key from TimeLens Settings > Local API / Extension Bridge.</p>
+      </section>
+
       <section class="panel">
         <div class="panel-head">
           <h2 data-i18n="today">Today in TimeLens</h2>

browser-extension/popup.html

@@ -15,10 +15,40 @@ const todayList = document.querySelector("#today-list");
 const recentList = document.querySelector("#recent-list");
 const activeTabPill = document.querySelector("#active-tab-pill");
 const refreshButton = document.querySelector("#refresh-button");
+const bridgeKeyPanel = document.querySelector("#bridge-key-panel");
+const bridgeKeyInput = document.querySelector("#bridge-key-input");
+const saveKeyButton = document.querySelector("#save-key-button");
 const locale = getLocale();
 
 applyStaticTranslations();
 
+if (bridgeKeyInput) {
+  bridgeKeyInput.placeholder = t("bridgeKeyPlaceholder", {}, locale);
+}
+
+// Setup bridge key UI
+if (saveKeyButton) {
+  saveKeyButton.addEventListener("click", async () => {
+    const key = bridgeKeyInput?.value.trim() || "";
+    await chrome.storage.local.set({ "timelens.bridgeKey": key });
+    if (key) {
+      alert(t("bridgeKeySaved", {}, locale));
+    } else {
+      alert(t("bridgeKeyCleared", {}, locale));
+    }
+  });
+}
+
+// Load saved bridge key into input so users can modify it anytime.
+async function loadBridgeKey() {
+  const { "timelens.bridgeKey": savedKey } = await chrome.storage.local.get("timelens.bridgeKey");
+  if (bridgeKeyInput) {
+    bridgeKeyInput.value = savedKey || "";
+  }
+}
+
+void loadBridgeKey();
+
 refreshButton.addEventListener("click", () => {
   loadAll();
 });