opencode-qwen-cli-auth 2.2.9 → 2.3.0

package/dist/lib/auth/auth.js

@@ -1,25 +1,69 @@
+/**
+ * @fileoverview OAuth authentication utilities for Qwen Plugin
+ * Implements OAuth 2.0 Device Authorization Grant flow (RFC 8628)
+ * Handles token storage, refresh, and validation
+ * @license MIT
+ */
+
 import { generatePKCE } from "@openauthjs/openauth/pkce";
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync, statSync } from "fs";
 import { QWEN_OAUTH, DEFAULT_QWEN_BASE_URL, TOKEN_REFRESH_BUFFER_MS, VERIFICATION_URI } from "../constants.js";
 import { getTokenPath, getQwenDir, getTokenLockPath, getLegacyTokenPath } from "../config.js";
 import { logError, logWarn, logInfo, LOGGING_ENABLED } from "../logger.js";
-const MAX_REFRESH_RETRIES = 1;
-const REFRESH_RETRY_DELAY_MS = 1000;
+
+/** Maximum number of retries for token refresh operations */
+const MAX_REFRESH_RETRIES = 2;
+/** Delay between retry attempts in milliseconds */
+const REFRESH_RETRY_DELAY_MS = 2000;
+/** Timeout for OAuth HTTP requests in milliseconds */
 const OAUTH_REQUEST_TIMEOUT_MS = 15000;
+/** Lock timeout for multi-process token refresh coordination */
 const LOCK_TIMEOUT_MS = 10000;
+/** Interval between lock acquisition attempts */
 const LOCK_ATTEMPT_INTERVAL_MS = 100;
+/** Backoff multiplier for lock retry interval */
 const LOCK_BACKOFF_MULTIPLIER = 1.5;
+/** Maximum interval between lock attempts */
 const LOCK_MAX_INTERVAL_MS = 2000;
+/** Maximum number of lock acquisition attempts */
 const LOCK_MAX_ATTEMPTS = 20;
+
+/**
+ * Checks if an error is an AbortError (from AbortController)
+ * @param {*} error - The error to check
+ * @returns {boolean} True if error is an AbortError
+ */
 function isAbortError(error) {
     return typeof error === "object" && error !== null && ("name" in error) && error.name === "AbortError";
 }
+
+/**
+ * Checks if an error has a specific error code (for Node.js system errors)
+ * @param {*} error - The error to check
+ * @param {string} code - The error code to look for (e.g., "EEXIST", "ENOENT")
+ * @returns {boolean} True if error has the specified code
+ */
 function hasErrorCode(error, code) {
     return typeof error === "object" && error !== null && ("code" in error) && error.code === code;
 }
+
+/**
+ * Creates a promise that resolves after specified milliseconds
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>} Promise that resolves after delay
+ */
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Performs fetch with timeout using AbortController
+ * Automatically aborts request if it exceeds timeout
+ * @param {string} url - URL to fetch
+ * @param {RequestInit} [init] - Fetch options
+ * @param {number} [timeoutMs=OAUTH_REQUEST_TIMEOUT_MS] - Timeout in milliseconds
+ * @returns {Promise<Response>} Fetch response
+ * @throws {Error} If request times out
+ */
 async function fetchWithTimeout(url, init, timeoutMs = OAUTH_REQUEST_TIMEOUT_MS) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
@@ -39,14 +83,23 @@ async function fetchWithTimeout(url, init, timeoutMs = OAUTH_REQUEST_TIMEOUT_MS)
         clearTimeout(timeoutId);
     }
 }
+
+/**
+ * Normalizes resource URL to valid HTTPS URL format
+ * Adds https:// prefix if missing and validates URL format
+ * @param {string|undefined} resourceUrl - URL to normalize
+ * @returns {string|undefined} Normalized URL or undefined if invalid
+ */
 function normalizeResourceUrl(resourceUrl) {
     if (!resourceUrl)
         return undefined;
     try {
         let normalizedUrl = resourceUrl;
+        // Add https:// prefix if protocol is missing
         if (!normalizedUrl.startsWith("http://") && !normalizedUrl.startsWith("https://")) {
             normalizedUrl = `https://${normalizedUrl}`;
         }
+        // Validate URL format
         new URL(normalizedUrl);
         if (LOGGING_ENABLED) {
             logInfo("Valid resource_url found and normalized:", normalizedUrl);
@@ -58,21 +111,37 @@ function normalizeResourceUrl(resourceUrl) {
         return undefined;
     }
 }
+
+/**
+ * Validates OAuth token response has required fields
+ * @param {Object} json - Token response JSON
+ * @param {string} context - Context for error messages (e.g., "token response", "refresh response")
+ * @returns {boolean} True if response is valid
+ */
 function validateTokenResponse(json, context) {
+    // Check access_token exists and is string
     if (!json.access_token || typeof json.access_token !== "string") {
         logError(`${context} missing access_token`);
         return false;
     }
+    // Check refresh_token exists and is string
     if (!json.refresh_token || typeof json.refresh_token !== "string") {
         logError(`${context} missing refresh_token`);
         return false;
     }
+    // Check expires_in is valid positive number
     if (typeof json.expires_in !== "number" || json.expires_in <= 0) {
         logError(`${context} invalid expires_in:`, json.expires_in);
         return false;
     }
     return true;
 }
+/**
+ * Converts raw token data to standardized stored token format
+ * Handles different field name variations (expiry_date vs expires)
+ * @param {Object} data - Raw token data from OAuth response or file
+ * @returns {Object|null} Normalized token data or null if invalid
+ */
 function toStoredTokenData(data) {
     if (!data || typeof data !== "object") {
         return null;
@@ -81,6 +150,7 @@ function toStoredTokenData(data) {
     const accessToken = typeof raw.access_token === "string" ? raw.access_token : undefined;
     const refreshToken = typeof raw.refresh_token === "string" ? raw.refresh_token : undefined;
     const tokenType = typeof raw.token_type === "string" && raw.token_type.length > 0 ? raw.token_type : "Bearer";
+    // Handle both expiry_date and expires field names
     const expiryDate = typeof raw.expiry_date === "number"
         ? raw.expiry_date
         : typeof raw.expires === "number"
@@ -89,6 +159,7 @@ function toStoredTokenData(data) {
                 ? Number(raw.expiry_date)
                 : undefined;
     const resourceUrl = typeof raw.resource_url === "string" ? normalizeResourceUrl(raw.resource_url) : undefined;
+    // Validate all required fields are present and valid
     if (!accessToken || !refreshToken || typeof expiryDate !== "number" || !Number.isFinite(expiryDate) || expiryDate <= 0) {
         return null;
     }
@@ -100,6 +171,12 @@ function toStoredTokenData(data) {
         resource_url: resourceUrl,
     };
 }
+
+/**
+ * Builds token success object from stored token data
+ * @param {Object} stored - Stored token data from file
+ * @returns {Object} Token success object for SDK
+ */
 function buildTokenSuccessFromStored(stored) {
     return {
         type: "success",
@@ -109,12 +186,20 @@ function buildTokenSuccessFromStored(stored) {
         resourceUrl: stored.resource_url,
     };
 }
+/**
+ * Writes token data to disk atomically using temp file + rename
+ * Uses secure file permissions (0o600 - owner read/write only)
+ * @param {Object} tokenData - Token data to write
+ * @throws {Error} If write operation fails
+ */
 function writeStoredTokenData(tokenData) {
     const qwenDir = getQwenDir();
+    // Create directory if it doesn't exist with secure permissions
     if (!existsSync(qwenDir)) {
         mkdirSync(qwenDir, { recursive: true, mode: 0o700 });
     }
     const tokenPath = getTokenPath();
+    // Use atomic write: write to temp file then rename
     const tempPath = `${tokenPath}.tmp.${Date.now().toString(36)}-${Math.random().toString(16).slice(2)}`;
     try {
         writeFileSync(tempPath, JSON.stringify(tokenData, null, 2), {
@@ -124,6 +209,7 @@ function writeStoredTokenData(tokenData) {
         renameSync(tempPath, tokenPath);
     }
     catch (error) {
+        // Clean up temp file on error
         try {
             if (existsSync(tempPath)) {
                 unlinkSync(tempPath);
@@ -134,12 +220,19 @@ function writeStoredTokenData(tokenData) {
         throw error;
     }
 }
+
+/**
+ * Migrates legacy token from old plugin location to new location
+ * Checks if new token file exists, if not tries to migrate from legacy path
+ */
 function migrateLegacyTokenIfNeeded() {
     const tokenPath = getTokenPath();
+    // Skip if new token file already exists
     if (existsSync(tokenPath)) {
         return;
     }
     const legacyPath = getLegacyTokenPath();
+    // Skip if legacy file doesn't exist
     if (!existsSync(legacyPath)) {
         return;
     }
@@ -158,12 +251,19 @@ function migrateLegacyTokenIfNeeded() {
         logWarn("Failed to migrate legacy token:", error);
     }
 }
+/**
+ * Acquires exclusive lock for token refresh to prevent concurrent refreshes
+ * Uses file-based locking with exponential backoff retry strategy
+ * @returns {Promise<string>} Lock file path if acquired successfully
+ * @throws {Error} If lock cannot be acquired within timeout
+ */
 async function acquireTokenLock() {
     const lockPath = getTokenLockPath();
     const lockValue = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
     let waitMs = LOCK_ATTEMPT_INTERVAL_MS;
     for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt++) {
         try {
+            // Try to create lock file with exclusive flag
             writeFileSync(lockPath, lockValue, {
                 encoding: "utf-8",
                 flag: "wx",
@@ -172,12 +272,14 @@ async function acquireTokenLock() {
             return lockPath;
         }
         catch (error) {
+            // EEXIST means lock file already exists
             if (!hasErrorCode(error, "EEXIST")) {
                 throw error;
             }
             try {
                 const stats = statSync(lockPath);
                 const ageMs = Date.now() - stats.mtimeMs;
+                // Remove stale lock if it's older than timeout
                 if (ageMs > LOCK_TIMEOUT_MS) {
                     try {
                         unlinkSync(lockPath);
@@ -196,22 +298,36 @@ async function acquireTokenLock() {
                     logWarn("Failed to inspect token lock file", statError);
                 }
             }
+            // Wait with exponential backoff before retry
             await sleep(waitMs);
             waitMs = Math.min(Math.floor(waitMs * LOCK_BACKOFF_MULTIPLIER), LOCK_MAX_INTERVAL_MS);
         }
     }
     throw new Error("Token refresh lock timeout");
 }
+
+/**
+ * Releases token refresh lock
+ * Silently ignores errors if lock file doesn't exist
+ * @param {string} lockPath - Path to lock file to release
+ */
 function releaseTokenLock(lockPath) {
     try {
         unlinkSync(lockPath);
     }
     catch (error) {
+        // Ignore ENOENT (file not found) errors
         if (!hasErrorCode(error, "ENOENT")) {
             logWarn("Failed to release token lock file", error);
         }
     }
 }
+/**
+ * Requests device code from Qwen OAuth server
+ * Initiates OAuth 2.0 Device Authorization Grant flow
+ * @param {{ challenge: string, verifier: string }} pkce - PKCE challenge and verifier
+ * @returns {Promise<Object|null>} Device auth response or null on failure
+ */
 export async function requestDeviceCode(pkce) {
     try {
         const res = await fetchWithTimeout(QWEN_OAUTH.DEVICE_CODE_URL, {
@@ -236,10 +352,12 @@ export async function requestDeviceCode(pkce) {
         if (LOGGING_ENABLED) {
             logInfo("Device code response received:", json);
         }
+        // Validate required fields are present
         if (!json.device_code || !json.user_code || !json.verification_uri) {
             logError("device code response missing fields:", json);
             return null;
         }
+        // Fix verification_uri_complete if missing client parameter
         if (!json.verification_uri_complete || !json.verification_uri_complete.includes(VERIFICATION_URI.CLIENT_PARAM_KEY)) {
             const baseUrl = json.verification_uri_complete || json.verification_uri;
             const separator = baseUrl.includes("?") ? "&" : "?";
@@ -255,6 +373,14 @@ export async function requestDeviceCode(pkce) {
         return null;
     }
 }
+/**
+ * Polls Qwen OAuth server for access token using device code
+ * Implements OAuth 2.0 Device Flow polling with proper error handling
+ * @param {string} deviceCode - Device code from requestDeviceCode
+ * @param {string} verifier - PKCE code verifier
+ * @param {number} [interval=2] - Polling interval in seconds
+ * @returns {Promise<Object>} Token result object with type: success|pending|slow_down|failed|denied|expired
+ */
 export async function pollForToken(deviceCode, verifier, interval = 2) {
     try {
         const res = await fetchWithTimeout(QWEN_OAUTH.TOKEN_URL, {
@@ -274,6 +400,7 @@ export async function pollForToken(deviceCode, verifier, interval = 2) {
             const json = await res.json().catch(() => ({}));
             const errorCode = typeof json.error === "string" ? json.error : undefined;
             const errorDescription = typeof json.error_description === "string" ? json.error_description : "No details provided";
+            // Handle standard OAuth 2.0 Device Flow errors
             if (errorCode === "authorization_pending") {
                 return { type: "pending" };
             }
@@ -286,6 +413,7 @@ export async function pollForToken(deviceCode, verifier, interval = 2) {
             if (errorCode === "access_denied") {
                 return { type: "denied" };
             }
+            // Log and return fatal error for unknown errors
             logError("token poll failed:", {
                 status: res.status,
                 error: errorCode,
@@ -309,6 +437,7 @@ export async function pollForToken(deviceCode, verifier, interval = 2) {
                 all_fields: Object.keys(json),
             });
         }
+        // Validate token response structure
         if (!validateTokenResponse(json, "token response")) {
             return {
                 type: "failed",
@@ -332,6 +461,7 @@ export async function pollForToken(deviceCode, verifier, interval = 2) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         const lowered = message.toLowerCase();
+        // Identify transient errors that may succeed on retry
         const transient = lowered.includes("timed out") || lowered.includes("network") || lowered.includes("fetch");
         logWarn("token poll failed:", { message, transient });
         return {
@@ -341,6 +471,11 @@ export async function pollForToken(deviceCode, verifier, interval = 2) {
         };
     }
 }
+/**
+ * Performs single token refresh attempt
+ * @param {string} refreshToken - Refresh token to use
+ * @returns {Promise<Object>} Token result object with type: success|failed
+ */
 async function refreshAccessTokenOnce(refreshToken) {
     try {
         const res = await fetchWithTimeout(QWEN_OAUTH.TOKEN_URL, {
@@ -360,6 +495,7 @@ async function refreshAccessTokenOnce(refreshToken) {
             const lowered = text.toLowerCase();
             const isUnauthorized = res.status === 401 || res.status === 403;
             const isRateLimited = res.status === 429;
+            // Identify transient errors (5xx, timeout, network)
             const transient = res.status >= 500 || lowered.includes("timed out") || lowered.includes("network");
             logError("token refresh failed:", { status: res.status, text });
             return {
@@ -379,6 +515,7 @@ async function refreshAccessTokenOnce(refreshToken) {
                 all_fields: Object.keys(json),
             });
         }
+        // Validate refresh response structure
         if (!validateTokenResponse(json, "refresh response")) {
             return {
                 type: "failed",
@@ -402,6 +539,7 @@ async function refreshAccessTokenOnce(refreshToken) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         const lowered = message.toLowerCase();
+        // Identify transient errors that may succeed on retry
         const transient = lowered.includes("timed out") || lowered.includes("network") || lowered.includes("fetch");
         logError("token refresh error:", { message, transient });
         return {
@@ -411,33 +549,47 @@ async function refreshAccessTokenOnce(refreshToken) {
         };
     }
 }
+/**
+ * Refreshes access token using refresh token with lock coordination
+ * Implements retry logic for transient failures
+ * @param {string} refreshToken - Refresh token to use
+ * @returns {Promise<Object>} Token result object with type: success|failed
+ */
 export async function refreshAccessToken(refreshToken) {
+    // Acquire lock to prevent concurrent refresh operations
     const lockPath = await acquireTokenLock();
     try {
+        // Check if another process already refreshed the token
         const latest = loadStoredToken();
         if (latest && !isTokenExpired(latest.expiry_date)) {
             return buildTokenSuccessFromStored(latest);
         }
+        // Use latest refresh token if available
         const effectiveRefreshToken = latest?.refresh_token || refreshToken;
+        // Retry loop for transient failures
         for (let attempt = 0; attempt <= MAX_REFRESH_RETRIES; attempt++) {
             const result = await refreshAccessTokenOnce(effectiveRefreshToken);
             if (result.type === "success") {
                 saveToken(result);
                 return result;
             }
+            // Non-retryable errors: 401/403 (unauthorized)
             if (result.status === 401 || result.status === 403) {
                 logError(`Refresh token rejected (${result.status}), re-authentication required`);
                 clearStoredToken();
                 return { type: "failed", status: result.status, error: "refresh_token_rejected", fatal: true };
             }
+            // Non-retryable errors: 429 (rate limited)
             if (result.status === 429) {
                 logError("Token refresh rate-limited (429), aborting retries");
                 return { type: "failed", status: 429, error: "rate_limited", fatal: true };
             }
+            // Non-retryable errors: fatal flag set
             if (result.fatal) {
                 logError("Token refresh failed with fatal error", result);
                 return result;
             }
+            // Retry transient failures
             if (attempt < MAX_REFRESH_RETRIES) {
                 if (LOGGING_ENABLED) {
                     logInfo(`Token refresh transient failure, retrying attempt ${attempt + 2}/${MAX_REFRESH_RETRIES + 1}...`);
@@ -449,14 +601,24 @@ export async function refreshAccessToken(refreshToken) {
         return { type: "failed", error: "refresh_failed" };
     }
     finally {
+        // Always release lock
         releaseTokenLock(lockPath);
     }
 }
+/**
+ * Generates PKCE challenge and verifier for OAuth flow
+ * @returns {Promise<{challenge: string, verifier: string}>} PKCE challenge and verifier pair
+ */
 export async function createPKCE() {
     const { challenge, verifier } = await generatePKCE();
     return { challenge, verifier };
 }
+/**
+ * Loads stored token from disk with legacy migration
+ * @returns {Object|null} Stored token data or null if not found/invalid
+ */
 export function loadStoredToken() {
+    // Migrate legacy token if needed
     migrateLegacyTokenIfNeeded();
     const tokenPath = getTokenPath();
     if (!existsSync(tokenPath)) {
@@ -470,6 +632,7 @@ export function loadStoredToken() {
             logWarn("Invalid token data, re-authentication required");
             return null;
         }
+        // Check if token file needs format update
         const needsRewrite = typeof parsed.expiry_date !== "number" ||
             typeof parsed.token_type !== "string" ||
             typeof parsed.expires === "number" ||
@@ -489,6 +652,9 @@ export function loadStoredToken() {
         return null;
     }
 }
+/**
+ * Clears stored token from both current and legacy paths
+ */
 export function clearStoredToken() {
     const targets = [getTokenPath(), getLegacyTokenPath()];
     for (const tokenPath of targets) {
@@ -504,6 +670,11 @@ export function clearStoredToken() {
         }
     }
 }
+/**
+ * Saves token result to disk
+ * @param {{ type: string, access: string, refresh: string, expires: number, resourceUrl?: string }} tokenResult - Token result from OAuth flow
+ * @throws {Error} If token result is invalid or write fails
+ */
 export function saveToken(tokenResult) {
     if (tokenResult.type !== "success") {
         throw new Error("Cannot save non-success token result");
@@ -523,14 +694,25 @@ export function saveToken(tokenResult) {
         throw error;
     }
 }
+/**
+ * Checks if token is expired (with buffer)
+ * @param {number} expiresAt - Token expiry timestamp in milliseconds
+ * @returns {boolean} True if token is expired or expiring soon
+ */
 export function isTokenExpired(expiresAt) {
     return Date.now() >= expiresAt - TOKEN_REFRESH_BUFFER_MS;
 }
+
+/**
+ * Gets valid access token, refreshing if expired
+ * @returns {Promise<{ accessToken: string, resourceUrl?: string }|null>} Valid token or null if unavailable
+ */
 export async function getValidToken() {
     const stored = loadStoredToken();
     if (!stored) {
         return null;
     }
+    // Return cached token if still valid
     if (!isTokenExpired(stored.expiry_date)) {
         return {
             accessToken: stored.access_token,
@@ -540,6 +722,7 @@ export async function getValidToken() {
     if (LOGGING_ENABLED) {
         logInfo("Token expired, refreshing...");
     }
+    // Token expired, try to refresh
     const refreshResult = await refreshAccessToken(stored.refresh_token);
     if (refreshResult.type !== "success") {
         logError("Token refresh failed, re-authentication required");
@@ -551,6 +734,12 @@ export async function getValidToken() {
         resourceUrl: refreshResult.resourceUrl,
     };
 }
+
+/**
+ * Constructs DashScope API base URL from resource_url
+ * @param {string} [resourceUrl] - Resource URL from token (optional)
+ * @returns {string} DashScope API base URL
+ */
 export function getApiBaseUrl(resourceUrl) {
     if (resourceUrl) {
         try {
@@ -564,6 +753,7 @@ export function getApiBaseUrl(resourceUrl) {
                 logWarn("Invalid resource_url protocol, using default DashScope endpoint");
                 return DEFAULT_QWEN_BASE_URL;
             }
+            // Ensure URL ends with /v1 suffix
             let baseUrl = normalizedResourceUrl.replace(/\/$/, "");
             const suffix = "/v1";
             if (!baseUrl.endsWith(suffix)) {

package/dist/lib/auth/browser.js

@@ -1,31 +1,41 @@
 /**
- * Browser utilities for OAuth flow
- * Handles platform-specific browser opening
+ * @fileoverview Browser utilities for OAuth flow
+ * Handles platform-specific browser opening for OAuth authorization URL
+ * @license MIT
  */
+
 import { spawn } from "node:child_process";
 import { PLATFORM_OPENERS } from "../constants.js";
+
 /**
  * Gets the platform-specific command to open a URL in the default browser
- * @returns Browser opener command for the current platform
+ * @returns {string} Browser opener command for the current platform (darwin: 'open', win32: 'start', linux: 'xdg-open')
  */
 export function getBrowserOpener() {
     const platform = process.platform;
+    // macOS uses 'open' command
     if (platform === "darwin")
         return PLATFORM_OPENERS.darwin;
+    // Windows uses 'start' command
     if (platform === "win32")
         return PLATFORM_OPENERS.win32;
+    // Linux uses 'xdg-open' command
     return PLATFORM_OPENERS.linux;
 }
+
 /**
  * Opens a URL in the default browser
  * Silently fails if browser cannot be opened (user can copy URL manually)
- * @param url - URL to open
+ * @param {string} url - The URL to open in browser (typically OAuth verification URL)
+ * @returns {void}
  */
 export function openBrowserUrl(url) {
     try {
         const opener = getBrowserOpener();
+        // Spawn browser process with detached stdio to avoid blocking
         spawn(opener, [url], {
             stdio: "ignore",
+            // Use shell on Windows for 'start' command to work properly
             shell: process.platform === "win32",
         });
     }

package/dist/lib/config.js

@@ -1,30 +1,46 @@
+/**
+ * @fileoverview Configuration utilities for Qwen OAuth Plugin
+ * Manages paths for configuration, tokens, and cache directories
+ * @license MIT
+ */
+
 import { homedir } from "os";
 import { join } from "path";
 import { readFileSync, existsSync } from "fs";
+
 /**
  * Get plugin configuration directory
+ * @returns {string} Path to ~/.opencode/qwen/
  */
 export function getConfigDir() {
     return join(homedir(), ".opencode", "qwen");
 }
+
 /**
  * Get Qwen CLI credential directory (~/.qwen)
+ * This directory is shared with the official qwen-code CLI for token storage
+ * @returns {string} Path to ~/.qwen/
  */
 export function getQwenDir() {
     return join(homedir(), ".qwen");
 }
+
 /**
  * Get plugin configuration file path
+ * @returns {string} Path to ~/.opencode/qwen/auth-config.json
  */
 export function getConfigPath() {
     return join(getConfigDir(), "auth-config.json");
 }
+
 /**
  * Load plugin configuration from ~/.opencode/qwen/auth-config.json
  * Returns default config if file doesn't exist
+ * @returns {{ qwenMode: boolean }} Configuration object with qwenMode flag
  */
 export function loadPluginConfig() {
     const configPath = getConfigPath();
+    // Return default config if config file doesn't exist
     if (!existsSync(configPath)) {
         return { qwenMode: true }; // Default: QWEN_MODE enabled
     }
@@ -33,15 +49,20 @@ export function loadPluginConfig() {
         return JSON.parse(content);
     }
     catch (error) {
+        // Log warning and return default config on parse error
         console.warn(`[qwen-oauth-plugin] Failed to load config from ${configPath}:`, error);
         return { qwenMode: true };
     }
 }
+
 /**
  * Get QWEN_MODE setting
  * Priority: QWEN_MODE env var > config file > default (true)
+ * @param {{ qwenMode?: boolean|string|null }} config - Configuration object from file
+ * @returns {boolean} True if QWEN_MODE is enabled, false otherwise
  */
 export function getQwenMode(config) {
+    // Environment variable takes highest priority
     const envValue = process.env.QWEN_MODE;
     if (envValue !== undefined) {
         return envValue === "1" || envValue.toLowerCase() === "true";
@@ -49,31 +70,44 @@ export function getQwenMode(config) {
     // Ensure boolean type, avoid string "false" being truthy
     const val = config.qwenMode;
     if (val === undefined || val === null) return true; // default: enabled
+    // Handle string values from config file
     if (typeof val === "string") {
         return val === "1" || val.toLowerCase() === "true";
     }
+    // Convert to boolean for actual boolean values
     return !!val;
 }
+
 /**
  * Get token storage path
+ * Token file contains OAuth credentials: access_token, refresh_token, expiry_date, resource_url
+ * @returns {string} Path to ~/.qwen/oauth_creds.json
  */
 export function getTokenPath() {
     return join(getQwenDir(), "oauth_creds.json");
 }
+
 /**
  * Get token lock path for multi-process refresh coordination
+ * Prevents concurrent token refresh operations across multiple processes
+ * @returns {string} Path to ~/.qwen/oauth_creds.lock
  */
 export function getTokenLockPath() {
     return join(getQwenDir(), "oauth_creds.lock");
 }
+
 /**
  * Get legacy token storage path used by old plugin versions
+ * Used for backward compatibility and token migration
+ * @returns {string} Path to ~/.opencode/qwen/oauth_token.json
  */
 export function getLegacyTokenPath() {
     return join(getConfigDir(), "oauth_token.json");
 }
+
 /**
  * Get cache directory for prompts
+ * @returns {string} Path to ~/.opencode/cache/
  */
 export function getCacheDir() {
     return join(homedir(), ".opencode", "cache");