nyxora 1.6.6 → 1.6.7

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.7]
+
+### UI/UX
+- **New Nyxora Brand Logo**: Replaced the standard dashboard `Bot` icon with a native, 100% transparent SVG component of the Nyxora Cosmic Star.
+- **Dashboard Avatar Overhaul**: Removed the rigid box border/shadow surrounding the agent avatar and maximized the logo scale (from 28px to 48px) for a bold, premium aesthetic.
+- **SVG Optimization**: Cropped the internal viewBox (padding) of the logo to ensure it renders with maximum density and solidity at any resolution.
+- **Favicon Update**: Synchronized the browser tab favicon with the newly optimized Nyxora logo.
+- **Network Sync**: Synchronized network dropdown ordering (ETH > BSC > Base > Optimism > Arbitrum > Sepolia) across Dashboard UI, Settings, and CLI setup.
+
+### Developer Experience
+- **Single-Command Boot**: Introduced `npm run dev` in the root workspace utilizing `concurrently` to launch the backend orchestrator (Vault/Policy/Core) and the Vite frontend simultaneously, providing a seamless "Plug & Play" dev experience.
+
+### Agent Intelligence
+- **Cross-Chain Context**: Upgraded the core LLM prompt to automatically detect network mentions in chat (e.g., "on BNB") and override the default chain dynamically.
+- **Portfolio Enforcement**: Instructed the agent to prioritize the comprehensive `check_portfolio` tool when users ask for general balances, while providing polite network confirmations.
+- **Dust Asset Precision**: Improved portfolio USD calculations to render micro-assets (< $0.01) up to 4 decimal places (e.g., ~$0.0050) preventing inaccurate $0.00 rounding.
+- **"Lean Degen" Auto-Whitelist**: AI now automatically intercepts and permanently saves Contract Addresses (CAs) into `user_whitelist.json` whenever users execute token swaps or check specific balances.
+- **Dynamic Portfolio Merging**: The `checkPortfolio` engine now executes a hyper-fast, 0% rate-limit risk Multicall that merges standard tokens, user-defined CAs, and CoinGecko's daily trending list into a clean, unified dashboard report.
+
+### Dual-Engine & OS Skills (Google Workspace MVP)
+- **Native Google Integration**: Agent can now autonomously interact with Gmail (`read_gmail_inbox`), Google Calendar (`list_calendar_events`), Google Docs (`read_google_docs`), Google Sheets (`append_row_to_sheets`), and Google Forms (`read_google_form_responses`).
+- **Security Upgrade (OS Keyring)**: Completely migrated OAuth token storage to the OS-Native Keyring Vault. Google Refresh Tokens are now securely locked and encrypted by the host OS, preventing plaintext credential theft.
+- **Performance Optimization**: Scrapped the heavy `googleapis` dependency in favor of lightweight Native `fetch`, resulting in zero NPM install warnings, smaller footprint, and faster execution.
+- **Bugfix**: Resolved TypeScript compilation errors (TS2349) related to the `pdf-parse` ESM dependency.
+## [1.6.6]
+
+### Hotfix: Global Monorepo Dependencies
+
+This release patches a critical bug where global installations via `npm install -g nyxora` would fail to start the daemon due to missing C++ native modules.
+
+#### Fixes
+- **Dependency Hoisting Fix**: Explicitly bundled essential runtime modules (isolated-vm, telegraf, @modelcontextprotocol/sdk) into the root package.json to support monolithic publishing.
+- **Zero-Crash Boot**: Resolves the MODULE_NOT_FOUND fatal error for isolated-vm when starting the daemon after a clean global install.
+- **Dashboard Stability**: Ensures the background API server connects flawlessly to the React Dashboard without encountering Connection Refused.
+## [1.6.5]
+
+### The Universal Bridge (MCP Integration)
+
+Nyxora now natively supports the Model Context Protocol (MCP). This massive upgrade transforms Nyxora from a standalone agent into a Universal Web3 Middleware. External AI clients (like Claude Desktop or Cursor IDE) can now securely interact with the Nyxora ecosystem out-of-the-box.
+
+#### Key Features
+- **StdioServerTransport**: Deep integration allowing Claude Desktop to securely spawn Nyxora as a child process.
+- **Universal Bridge**: Exposes Nyxora's core crypto actions (swap, transfer, market analysis) as standard MCP Tools.
+- **Enterprise Security**: All external MCP commands are strictly routed through Nyxora's battle-tested Policy Engine, ensuring no unauthorized transactions occur.
 ## [1.6.4]
 
 ### Added

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nyxora AI Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,16 @@
 # Nyxora Agent 🤖
-**Production-Grade Secure AI Execution Framework for Web3 Agents.**
+**Dual-Engine AI Agent: Bridging On-Chain Execution with Off-Chain Automation.**
+
 
-[![Version](https://img.shields.io/badge/version-1.6.5-blue.svg)](https://github.com/perasyudha/Nyxora)
 [![MCP Supported](https://img.shields.io/badge/MCP-Supported-blue.svg)](#)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Security: Production-Grade](https://img.shields.io/badge/Security-Production--Grade-blue.svg)](#️-advanced-security-threat-model)
 [![Execution: Cryptographic Approval](https://img.shields.io/badge/Execution-Cryptographic--Approval-orange.svg)](#️-advanced-security-threat-model)
 [![Privacy: Local-Only Keys](https://img.shields.io/badge/Privacy-Local--Only--Keys-success.svg)](#️-advanced-security-threat-model)
 
-Nyxora (v1.6.5) is a **secure, non-custodial runtime infrastructure for autonomous onchain agents** built with a robust Monorepo architecture (Node.js & React). Designed for autonomous workflows with a premium Glassmorphism UI dashboard and strict client-side key isolation. 
+Nyxora is a **secure, non-custodial runtime infrastructure for autonomous onchain agents** built with a robust Monorepo architecture (Node.js & React). Designed for autonomous workflows with a premium Glassmorphism UI dashboard and strict client-side key isolation. 
 
-**Nyxora now natively supports the Model Context Protocol (MCP)**. You can transform your external AI agents (like Claude Desktop and Cursor) into secure Web3 actors that execute swaps and fetch balances using Nyxora's secure signer vault. [View the MCP Integration Guide](https://perasyudha.github.io/Nyxora/guide/mcp-integration)
+**Nyxora now natively supports the Model Context Protocol (MCP)**. You can transform your external AI agents (like Claude Desktop and Cursor) into secure Web3 actors that execute swaps and fetch balances using Nyxora's secure signer vault. [View the MCP Integration Guide](https://nyxoraAI.github.io/Nyxora/guide/mcp-integration)
 
 It operates under an institutional-grade **Cryptographically Bound Human-in-the-Loop** execution model, ensuring that Remote AIs (LLMs) never have unilateral access to your funds.
 
@@ -24,12 +24,17 @@ It operates under an institutional-grade **Cryptographically Bound Human-in-the-
 *   **Immutable Policy Guardrails**: Transaction limits (e.g. `max_usd_per_tx`) are strictly enforced by the Policy Engine. The LLM has zero write-access to bypass these rules.
 *   **Plugin Sandbox VM**: Execute community-built external skills securely inside an airtight Node.js `vm` chamber with zero access to your file system or terminal processes.
 
-### Core Operations & Web3 Execution
-*   **System Automation & Full OS Access**: Instruct the agent to read/write local files, run terminal commands, and browse the web natively.
+### 🌐 Web3 Skills (On-Chain)
 *   **Anti-Rugpull & Security Scanner**: Nyxora can scan smart contracts via GoPlus Labs to detect Honeypots, Hidden Taxes, and malicious proxy upgrades before you buy.
-*   **Automated Limit Orders**: Set natural language rules (e.g., "Sell my PEPE if price drops below $0.001"). Nyxora runs a background cron monitor and executes the swap while you sleep (Auto-Approve Bypass configured safely).
+*   **Automated Take Profit (TP) & Cut Loss (CL)**: The trader's holy grail. Set natural language rules (e.g., "Sell my PEPE if price drops below $0.001"). Nyxora runs a background cron monitor and executes the swap while you sleep.
 *   **Cross-Chain Hybrid Market Scanner**: Real-time asset tracking combining CoinGecko global data with DexScreener on-chain metrics across Ethereum, Base, Solana, BSC, and more.
-*   **PNL & Portfolio Tracking**: The AI scans your wallets and multiplies balances by live DEX prices to give you real-time Net Worth estimations.
+*   **"Lean Degen" Auto-Whitelist**: Automatically intercepts Contract Addresses (CAs) whenever you check balances or swap tokens, saving them to your localized `user_whitelist.json` for future tracking.
+*   **Dynamic Portfolio Engine**: Merges standard tokens, your custom Degen CAs, and CoinGecko's daily trending list into a single hyper-fast Multicall scan to deliver a clean, spam-free PnL portfolio report in under 1 second.
+
+### 💻 OS & Web2 Skills (Off-Chain)
+*   **Google Workspace Automation 🚀**: Transform Nyxora into your ultimate personal assistant. The agent can read your latest Gmail inbox, check your Google Calendar, extract text from Google Docs, and even append expense/trading logs directly to your Google Sheets.
+*   **System Automation & Full OS Access**: Instruct the agent to read/write local files, run terminal commands, and browse the web natively.
+*   **Unstoppable Synergy**: Combine both engines with a single prompt. Example: *"Read the latest presale token email from my Gmail, automatically set a Take Profit limit order on Uniswap, and log the execution result to my Google Sheets."*
 
 ### AI & UI Customization
 *   **Zero-Click Multi-Session**: Instantly create isolated chat sessions with smart auto-naming triggered by your first prompt, exactly like ChatGPT.
@@ -48,7 +53,7 @@ The following diagram illustrates Nyxora's **3-Tier Monorepo Architecture**, sho
 *Nyxora separates its duties into 3 independent layers for absolute security:*
 1. **🧠 Core (The AI Brain)**: The intelligent assistant that strategizes and plans transactions, but **never** holds your funds.
 2. **🛡️ Policy Engine (The Guard)**: The security guard that verifies the Brain's plans. If the AI attempts to send funds exceeding your set limits, this engine automatically blocks it.
-3. **🔒 Signer Vault (The Safe)**: The offline vault where your Private Keys are securely locked natively in your OS Keyring (GNOME Keyring / macOS Keychain / Windows Credential Manager). It only signs transactions after they pass all rigorous security checks.
+3. **🔒 Signer Vault (The Safe)**: The offline vault where your Private Keys **and highly sensitive 3rd-party tokens (e.g., Google Workspace OAuth)** are securely locked natively in your OS Keyring (GNOME Keyring / macOS Keychain / Windows Credential Manager). It only signs transactions after they pass all rigorous security checks.
 
 *(Note: Despite the multi-layered security process appearing lengthy, the internal system validation and cryptographic signing occurs in **milliseconds**, ensuring zero latency bottlenecks).*
 
@@ -56,7 +61,7 @@ The following diagram illustrates Nyxora's **3-Tier Monorepo Architecture**, sho
 
 ## 🛡️ Advanced Security & Threat Model
 
-To dive deeper into the technical details of our Zero-Knowledge security architecture, please visit the [Nyxora Security Blueprint](https://perasyudha.github.io/Nyxora/).
+To dive deeper into the technical details of our Zero-Knowledge security architecture, please visit the [Nyxora Security Blueprint](https://nyxoraAI.github.io/Nyxora/).
 
 ---
 
@@ -84,7 +89,7 @@ nyxora dashboard
 If you wish to modify the code or run from source, you can use the Monorepo architecture.
 
 ```bash
-git clone https://github.com/perasyudha/Nyxora.git
+git clone https://github.com/nyxoraAI/Nyxora.git
 cd Nyxora
 
 # 1. Install Dependencies
@@ -96,13 +101,11 @@ npm run build
 # 3. Interactive Setup Wizard (API Keys, Wallet, Telegram)
 npm run setup
 
-# 4. Start the Nyxora background daemon
-npm start
-
-# 5. Open the Web Dashboard
-npm run dashboard
+# 4. Start the Development Server (Single-Command Boot)
+# This will start the backend vault/services and the frontend Dashboard simultaneously
+npm run dev
 ```
-> **⚠️ IMPORTANT:** Whenever you re-run `npm run setup` or manually edit the config files, you **must restart the daemon** by running `npm run restart` for the changes to take effect.
+> **⚠️ IMPORTANT:** Whenever you re-run `npm run setup` or manually edit the config files, you **must restart the dev server** for the changes to take effect.
 
 ---
 
@@ -110,7 +113,7 @@ npm run dashboard
 
 For complete technical deep-dives into our Cryptographic Architecture, please visit our official VitePress Documentation Site!
 
-> **🔗 [Read the Full Nyxora Documentation Here](https://perasyudha.github.io/Nyxora/)**
+> **🔗 [Read the Full Nyxora Documentation Here](https://nyxoraAI.github.io/Nyxora/)**
 
 *(Includes guides on Secure Wallet Imports, Architecture Blueprints, Troubleshooting, and Custom Skill Development).*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nyxora",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "license": "MIT",
   "workspaces": [
     "packages/*"
@@ -9,6 +9,7 @@
     "nyxora": "bin/nyxora.mjs"
   },
   "scripts": {
+    "dev": "concurrently -n \"BACKEND,FRONTEND\" -c \"blue,green\" \"npx ts-node -T launcher.ts\" \"npm run dev --workspace=dashboard\"",
     "start": "node ./bin/nyxora.mjs start",
     "stop": "node ./bin/nyxora.mjs stop",
     "restart": "node ./bin/nyxora.mjs restart",

package/packages/core/package.json

@@ -1,18 +1,24 @@
 {
   "name": "nyxora-agent-core",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "private": true,
   "main": "src/gateway/server.ts",
   "dependencies": {
     "@clack/prompts": "^1.4.0",
     "cors": "^2.8.6",
+    "duck-duck-scrape": "^2.2.7",
     "express": "^5.2.1",
     "express-rate-limit": "^7.5.0",
     "helmet": "^8.0.0",
     "isolated-vm": "^6.1.2",
+    "mammoth": "^1.12.0",
     "open": "^11.0.0",
     "openai": "^6.39.0",
+    "pdf-parse": "^2.4.5",
     "telegraf": "^4.16.3",
     "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/pdf-parse": "^1.1.5"
   }
 }

package/packages/core/src/agent/reasoning.ts

@@ -9,6 +9,7 @@ import { transferToolDefinition, prepareTransfer } from '../web3/skills/transfer
 import { getPriceToolDefinition, getPrice } from '../web3/skills/getPrice';
 import { swapTokenToolDefinition, prepareSwapToken } from '../web3/skills/swapToken';
 import { bridgeTokenToolDefinition, prepareBridgeToken } from '../web3/skills/bridgeToken';
+import { isSkillActive } from '../utils/skillManager';
 import { mintNftToolDefinition, prepareMintNft } from '../web3/skills/mintNft';
 import { customTxToolDefinition, prepareCustomTx } from '../web3/skills/customTx';
 import { createWalletToolDefinition, createWallet } from '../web3/skills/createWallet';
@@ -25,6 +26,18 @@ import { writeLocalFileToolDefinition, writeLocalFile } from '../system/skills/w
 import { runTerminalCommandToolDefinition, runTerminalCommand } from '../system/skills/executeShell';
 import { browseWebsiteToolDefinition, browseWebsite } from '../system/skills/browseWeb';
 import { installExternalSkillToolDefinition, installExternalSkill } from '../system/skills/installSkill';
+import { 
+  readGmailInbox, 
+  listCalendarEvents, 
+  appendRowToSheets, 
+  readGoogleDocs, 
+  readGoogleFormResponses,
+  readGmailInboxToolDefinition,
+  listCalendarEventsToolDefinition,
+  appendRowToSheetsToolDefinition,
+  readGoogleDocsToolDefinition,
+  readGoogleFormResponsesToolDefinition
+} from '../system/skills/googleWorkspace';
 import { pluginManager } from '../system/pluginManager';
 import { getPath } from '../config/paths';
 import pc from 'picocolors';
@@ -141,9 +154,9 @@ function getSystemPrompt() {
   let basePrompt = `You are an autonomous Web3 agent operating on EVM chains.
 You are equipped with a native wallet. 
 CRITICAL RULE: You must always reply in the exact same language that the user uses to talk to you. If the user speaks Indonesian, reply in Indonesian. If they speak English, reply in English.
-CRITICAL RULE: If the user asks to check "my balance", "saldo saya", or anything about their own wallet, DO NOT ask them for an address. You must immediately call the get_balance tool and LEAVE THE ADDRESS PARAMETER EMPTY. The system will automatically use the injected private key wallet.
-Always use the tools to interact with the blockchain.
-If the user doesn't specify a chain, default to: ${config.agent.default_chain}.`;
+CRITICAL RULE: When the user asks to check "my balance", "saldo saya", or anything about their own wallet generally, ALWAYS use the check_portfolio tool to show all assets on the chain that have a USD value greater than 0. LEAVE THE ADDRESS PARAMETER EMPTY. Do NOT use get_balance unless the user explicitly asks for the balance of ONE specific token (e.g., "what is my ETH balance?").
+CRITICAL RULE: If the user doesn't specify a chain, default to: ${config.agent.default_chain}. If the user mentions a specific chain (e.g., "on BNB", "di Base"), you MUST override the default and execute the tool on that specific chain.
+CRITICAL RULE: If you use the default chain because the user forgot to specify one, you MUST politely confirm which chain you checked in your response (e.g., "I checked your balance on the ${config.agent.default_chain} network..."). Do not issue scary warnings.`;
 
   // Read IDENTITY.md for core AI persona
   try {
@@ -238,8 +251,13 @@ export async function processUserInput(input: string, role: 'user' | 'system' =
           runTerminalCommandToolDefinition as any,
           browseWebsiteToolDefinition as any,
           installExternalSkillToolDefinition as any,
+          readGmailInboxToolDefinition as any,
+          listCalendarEventsToolDefinition as any,
+          appendRowToSheetsToolDefinition as any,
+          readGoogleDocsToolDefinition as any,
+          readGoogleFormResponsesToolDefinition as any,
           ...pluginManager.getToolDefinitions()
-        ],
+        ].filter(t => isSkillActive(t.function.name)),
         tool_choice: "auto",
       });
     });
@@ -395,6 +413,26 @@ export async function processUserInput(input: string, role: 'user' | 'system' =
               result = await installExternalSkill(args.url);
               break;
             }
+            case 'read_gmail_inbox': {
+              result = await readGmailInbox(args.maxResults);
+              break;
+            }
+            case 'list_calendar_events': {
+              result = await listCalendarEvents(args.maxResults);
+              break;
+            }
+            case 'append_row_to_sheets': {
+              result = await appendRowToSheets(args.spreadsheetId, args.range, args.values);
+              break;
+            }
+            case 'read_google_docs': {
+              result = await readGoogleDocs(args.documentId);
+              break;
+            }
+            case 'read_google_form_responses': {
+              result = await readGoogleFormResponses(args.formId);
+              break;
+            }
             default: {
               const externalResult = await pluginManager.executeTool(toolName, args);
               if (externalResult !== null) {
@@ -423,6 +461,13 @@ export async function processUserInput(input: string, role: 'user' | 'system' =
           name: toolName,
           content: result,
         }, sessionId);
+
+        // V2 Optimization: Zero-LLM Fast Return for data-heavy tools
+        // If the tool already returns perfectly formatted markdown, skip the second LLM call to save 5-10s latency and tokens!
+        if (toolName === 'check_portfolio' || toolName === 'check_address') {
+          logger.addEntry({ role: 'assistant', content: result }, sessionId);
+          return result;
+        }
       }
 
       // Second call to get the final answer after tool execution

package/packages/core/src/gateway/cli.ts

@@ -64,8 +64,13 @@ console.log(`================================`);
 
   // 4. Start the Express API Server (which also serves the static dashboard and Telegram bot)
   startServer();
-  getSessionToken(); // Initialize token file
+  const token = getSessionToken(); // Initialize token file
   console.log(`🌐 Nyxora API Server running on port ${process.env.PORT || 3000}`);
+  
+  setTimeout(() => {
+    console.log(pc.cyan(`\n✨ Dashboard URL: http://localhost:3000/?token=${token}`));
+    console.log(pc.gray(`   (Developers: Vite hot-reload available at http://localhost:5173/?token=${token})\n`));
+  }, 1500);
 }
 
 main().catch(console.error);

package/packages/core/src/gateway/googleAuthModule.ts

@@ -0,0 +1,181 @@
+import fs from 'fs';
+import path from 'path';
+import { getAppDir } from '../config/paths';
+
+const CREDENTIALS_PATH = path.join(getAppDir(), 'google-credentials.json');
+const FALLBACK_TOKEN_PATH = path.join(getAppDir(), 'google-tokens.json');
+
+const SCOPES = [
+  'https://www.googleapis.com/auth/gmail.readonly',
+  'https://www.googleapis.com/auth/calendar.readonly',
+  'https://www.googleapis.com/auth/documents.readonly',
+  'https://www.googleapis.com/auth/spreadsheets',
+  'https://www.googleapis.com/auth/forms.responses.readonly',
+  'https://www.googleapis.com/auth/drive.file'
+];
+
+interface GoogleCredentials {
+  client_id: string;
+  client_secret: string;
+  redirect_uris: string[];
+}
+
+let credentials: GoogleCredentials | null = null;
+let accessToken: string | null = null;
+let tokenExpiry: number = 0; // Unix timestamp in ms
+
+export async function initGoogleAuth(): Promise<boolean> {
+  if (!fs.existsSync(CREDENTIALS_PATH)) {
+    console.log(`[Google Auth] No credentials found at ${CREDENTIALS_PATH}`);
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(CREDENTIALS_PATH, 'utf8');
+    const parsed = JSON.parse(content);
+    credentials = parsed.web || parsed.installed;
+
+    // Check if we already have a refresh token saved
+    const refreshToken = await getRefreshToken();
+    if (refreshToken) {
+      console.log('[Google Auth] Refresh token found in secure storage.');
+      return true;
+    }
+    return false;
+  } catch (err) {
+    console.error('[Google Auth] Error initializing:', err);
+    return false;
+  }
+}
+
+export function getAuthUrl(): string | null {
+  if (!credentials) return null;
+
+  const params = new URLSearchParams({
+    client_id: credentials.client_id,
+    redirect_uri: credentials.redirect_uris[0],
+    response_type: 'code',
+    scope: SCOPES.join(' '),
+    access_type: 'offline',
+    prompt: 'consent'
+  });
+
+  return `https://accounts.google.com/o/oauth2/v2/auth?${params.toString()}`;
+}
+
+export async function processCallback(code: string): Promise<boolean> {
+  if (!credentials) return false;
+
+  try {
+    const res = await fetch('https://oauth2.googleapis.com/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        code,
+        client_id: credentials.client_id,
+        client_secret: credentials.client_secret,
+        redirect_uri: credentials.redirect_uris[0],
+        grant_type: 'authorization_code'
+      }).toString()
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      console.error('[Google Auth] Token exchange failed:', data);
+      return false;
+    }
+
+    if (data.access_token) {
+      accessToken = data.access_token;
+      tokenExpiry = Date.now() + (data.expires_in * 1000);
+    }
+
+    if (data.refresh_token) {
+      await saveRefreshToken(data.refresh_token);
+    }
+
+    return true;
+  } catch (err) {
+    console.error('[Google Auth] Error processing callback:', err);
+    return false;
+  }
+}
+
+export async function isAuthenticated(): Promise<boolean> {
+  const rt = await getRefreshToken();
+  return !!rt;
+}
+
+export async function getAccessToken(): Promise<string | null> {
+  if (!credentials) return null;
+
+  // If token is valid for at least 5 more minutes, use it
+  if (accessToken && Date.now() < tokenExpiry - 300000) {
+    return accessToken;
+  }
+
+  // Otherwise, refresh it
+  const refreshToken = await getRefreshToken();
+  if (!refreshToken) return null;
+
+  try {
+    const res = await fetch('https://oauth2.googleapis.com/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        refresh_token: refreshToken,
+        client_id: credentials.client_id,
+        client_secret: credentials.client_secret,
+        grant_type: 'refresh_token'
+      }).toString()
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      console.error('[Google Auth] Failed to refresh token:', data);
+      return null;
+    }
+
+    accessToken = data.access_token;
+    tokenExpiry = Date.now() + (data.expires_in * 1000);
+    return accessToken;
+  } catch (err) {
+    console.error('[Google Auth] Error refreshing token:', err);
+    return null;
+  }
+}
+
+// ---- Secure Storage for Refresh Token ----
+
+async function saveRefreshToken(token: string) {
+  try {
+    const { Entry } = require('@napi-rs/keyring');
+    const entry = new Entry('nyxora', 'google_refresh_token');
+    await entry.setPassword(token);
+    console.log('[Google Auth] Refresh token saved securely to OS Keyring.');
+  } catch (error) {
+    console.warn('[Google Auth] Keyring failed, falling back to local tokens.json');
+    fs.writeFileSync(FALLBACK_TOKEN_PATH, JSON.stringify({ refresh_token: token }), { mode: 0o600 });
+  }
+}
+
+async function getRefreshToken(): Promise<string | null> {
+  try {
+    const { Entry } = require('@napi-rs/keyring');
+    const entry = new Entry('nyxora', 'google_refresh_token');
+    const password = await entry.getPassword();
+    if (password) return password;
+  } catch (error) {
+    // Fallback to file
+    if (fs.existsSync(FALLBACK_TOKEN_PATH)) {
+      try {
+        const content = fs.readFileSync(FALLBACK_TOKEN_PATH, 'utf8');
+        const parsed = JSON.parse(content);
+        if (parsed.refresh_token) return parsed.refresh_token;
+      } catch (e) {
+        return null;
+      }
+    }
+  }
+  return null;
+}