opencode-qwen-cli-auth 2.2.9 → 2.3.1

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.d.ts

@@ -29,6 +29,14 @@ export declare function getTokenPath(): string;
  * Get token lock path for multi-process refresh coordination
  */
 export declare function getTokenLockPath(): string;
+/**
+ * Get multi-account storage path
+ */
+export declare function getAccountsPath(): string;
+/**
+ * Get multi-account lock path
+ */
+export declare function getAccountsLockPath(): string;
 /**
  * Get legacy token storage path used by old plugin versions
  */

package/dist/lib/config.js

@@ -1,30 +1,90 @@
+/**
+ * @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 { join, resolve, relative, isAbsolute, parse, dirname } 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");
 }
+
+const ACCOUNTS_FILENAME = "oauth_accounts.json";
+const DEFAULT_ACCOUNTS_PATH = join(getQwenDir(), ACCOUNTS_FILENAME);
+
+function isRootPath(pathValue) {
+    const parsed = parse(pathValue);
+    return pathValue === parsed.root;
+}
+
+function isPathInsideBase(pathValue, baseDir) {
+    const rel = relative(baseDir, pathValue);
+    if (rel === "") {
+        return true;
+    }
+    return !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+function resolveAccountsPathFromEnv() {
+    const envPath = process.env.OPENCODE_QWEN_ACCOUNTS_PATH;
+    if (typeof envPath !== "string" || envPath.trim().length === 0) {
+        return null;
+    }
+    const trimmed = envPath.trim();
+    if (trimmed.includes("\0")) {
+        console.warn("[qwen-oauth-plugin] Ignoring OPENCODE_QWEN_ACCOUNTS_PATH with invalid null-byte");
+        return null;
+    }
+    const resolved = resolve(trimmed);
+    if (isRootPath(resolved)) {
+        console.warn("[qwen-oauth-plugin] Ignoring OPENCODE_QWEN_ACCOUNTS_PATH pointing to root path");
+        return null;
+    }
+    const baseDir = getQwenDir();
+    if (!isPathInsideBase(resolved, baseDir)) {
+        console.warn("[qwen-oauth-plugin] Ignoring OPENCODE_QWEN_ACCOUNTS_PATH outside ~/.qwen for safety");
+        return null;
+    }
+    const parsed = parse(resolved);
+    if (!parsed.base || parsed.base.length === 0) {
+        console.warn("[qwen-oauth-plugin] Ignoring OPENCODE_QWEN_ACCOUNTS_PATH without filename");
+        return null;
+    }
+    return resolved;
+}
+
 /**
  * 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 +93,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 +114,64 @@ 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 multi-account storage path
+ * @returns {string} Path to ~/.qwen/oauth_accounts.json or OPENCODE_QWEN_ACCOUNTS_PATH override
+ */
+export function getAccountsPath() {
+    return resolveAccountsPathFromEnv() || DEFAULT_ACCOUNTS_PATH;
+}
+
+/**
+ * Get multi-account lock path
+ * @returns {string} Path to ~/.qwen/oauth_accounts.lock (or sidecar lock for override path)
+ */
+export function getAccountsLockPath() {
+    const accountsPath = getAccountsPath();
+    if (dirname(accountsPath) !== getQwenDir()) {
+        return `${accountsPath}.lock`;
+    }
+    return join(getQwenDir(), "oauth_accounts.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");

package/dist/lib/constants.js

@@ -1,12 +1,24 @@
 /**
- * Constants for Qwen OAuth Plugin
+ * @fileoverview Constants for Qwen OAuth Plugin
+ * Centralized configuration for OAuth endpoints, headers, error codes, and other constants
+ * @license MIT
  */
-/** Plugin identifier */
+
+/** Plugin identifier for logging and debugging */
 export const PLUGIN_NAME = "qwen-oauth-plugin";
-/** Provider ID for opencode configuration (used in model references like qwen-code/coder-model) */
+
+/**
+ * Provider ID for opencode configuration
+ * Used in model references like qwen-code/coder-model
+ */
 export const PROVIDER_ID = "qwen-code";
-/** Dummy API key (actual auth via OAuth) */
+
+/**
+ * Dummy API key placeholder
+ * Actual authentication is handled via OAuth flow, not API key
+ */
 export const DUMMY_API_KEY = "qwen-oauth";
+
 /**
  * Default Qwen DashScope base URL (fallback if resource_url is missing)
  * Note: This plugin is for OAuth authentication only. For API key authentication,
@@ -15,27 +27,43 @@ export const DUMMY_API_KEY = "qwen-oauth";
  * IMPORTANT: OAuth endpoints use /api/v1, DashScope OpenAI-compatible uses /compatible-mode/v1
  * - OAuth endpoints: /api/v1/oauth2/ (for authentication)
  * - Chat API: /v1/ (for completions)
+ *
+ * @constant {string}
  */
 // NOTE:
 // qwen-code (official CLI) defaults to DashScope OpenAI-compatible endpoint when
 // `resource_url` is missing. This is required for the free OAuth flow to behave
 // the same as the CLI.
 export const DEFAULT_QWEN_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1";
-/** Qwen OAuth endpoints and configuration */
+
+/**
+ * Qwen OAuth endpoints and configuration
+ * Source: Qwen Code CLI (https://github.com/QwenLM/qwen-code)
+ * @namespace
+ */
 export const QWEN_OAUTH = {
+    /** OAuth 2.0 Device Code endpoint */
     DEVICE_CODE_URL: "https://chat.qwen.ai/api/v1/oauth2/device/code",
+    /** OAuth 2.0 Token endpoint */
     TOKEN_URL: "https://chat.qwen.ai/api/v1/oauth2/token",
     /**
      * Qwen OAuth Client ID
-     * Source: Qwen Code CLI (https://github.com/QwenLM/qwen-code)
      * This is a public client ID used for OAuth Device Authorization Grant flow (RFC 8628)
+     * @constant {string}
      */
     CLIENT_ID: "f0304373b74a44d2b584a3fb70ca9e56",
+    /** OAuth scopes requested: openid, profile, email, and model completion access */
     SCOPE: "openid profile email model.completion",
+    /** OAuth 2.0 Device Code grant type (RFC 8628) */
     GRANT_TYPE_DEVICE: "urn:ietf:params:oauth:grant-type:device_code",
+    /** OAuth 2.0 Refresh Token grant type */
     GRANT_TYPE_REFRESH: "refresh_token",
 };
-/** HTTP Status Codes */
+
+/**
+ * HTTP Status Codes for error handling
+ * @namespace
+ */
 export const HTTP_STATUS = {
     OK: 200,
     BAD_REQUEST: 400,
@@ -43,21 +71,37 @@ export const HTTP_STATUS = {
     FORBIDDEN: 403,
     TOO_MANY_REQUESTS: 429,
 };
+
 /**
- * DashScope headers
+ * DashScope headers for OAuth authentication
  * Note: OAuth requires X-DashScope-AuthType to indicate qwen-oauth authentication
+ * @namespace
  */
 export const PORTAL_HEADERS = {
+    /** Header name for auth type specification */
     AUTH_TYPE: "X-DashScope-AuthType",
+    /** Header value for qwen-oauth authentication */
     AUTH_TYPE_VALUE: "qwen-oauth",
 };
-/** Device flow polling configuration */
+
+/**
+ * Device flow polling configuration
+ * Controls backoff strategy for OAuth token polling
+ * @namespace
+ */
 export const DEVICE_FLOW = {
+    /** Initial polling interval in milliseconds */
     INITIAL_POLL_INTERVAL: 2000, // 2 seconds
+    /** Maximum polling interval in milliseconds */
     MAX_POLL_INTERVAL: 10000, // 10 seconds
+    /** Backoff multiplier for exponential backoff */
     BACKOFF_MULTIPLIER: 1.5,
 };
-/** Error messages */
+
+/**
+ * Error messages for user-facing errors
+ * @namespace
+ */
 export const ERROR_MESSAGES = {
     TOKEN_REFRESH_FAILED: "Failed to refresh token, authentication required",
     DEVICE_AUTH_TIMEOUT: "Device authorization timed out",
@@ -65,14 +109,27 @@ export const ERROR_MESSAGES = {
     REQUEST_PARSE_ERROR: "Error parsing request",
     NO_RESOURCE_URL: "No resource_url in token response, using default",
 };
-/** OAuth error codes */
+
+/**
+ * OAuth error codes from RFC 8628 Device Flow
+ * @namespace
+ */
 export const OAUTH_ERRORS = {
+    /** User has not yet authorized the device code */
     AUTHORIZATION_PENDING: "authorization_pending",
+    /** Server requests slower polling (slow_down error) */
     SLOW_DOWN: "slow_down",
+    /** User denied the authorization request */
     ACCESS_DENIED: "access_denied",
+    /** Device code has expired */
     EXPIRED_TOKEN: "expired_token",
 };
-/** Log stages for request logging */
+
+/**
+ * Log stages for request logging
+ * Used for debugging and tracing request lifecycle
+ * @namespace
+ */
 export const LOG_STAGES = {
     BEFORE_TRANSFORM: "before-transform",
     AFTER_TRANSFORM: "after-transform",
@@ -81,29 +138,53 @@ export const LOG_STAGES = {
     DEVICE_CODE_REQUEST: "device-code-request",
     TOKEN_POLL: "token-poll",
 };
-/** Platform-specific browser opener commands */
+
+/**
+ * Platform-specific browser opener commands
+ * Used for opening OAuth verification URL in default browser
+ * @namespace
+ */
 export const PLATFORM_OPENERS = {
     darwin: "open",
     win32: "start",
     linux: "xdg-open",
 };
-/** OAuth authorization labels */
+
+/**
+ * OAuth authorization labels for UI display
+ * @namespace
+ */
 export const AUTH_LABELS = {
+    /** Label shown in OpenCode auth provider selection */
     OAUTH: "Qwen Code (qwen.ai OAuth)",
+    /** Instructions shown to user during OAuth flow */
     INSTRUCTIONS: "Visit the URL shown in your browser to complete authentication.",
 };
-/** OAuth verification URI parameters */
+
+/**
+ * OAuth verification URI parameters
+ * Used to construct complete verification URL with client identification
+ * @namespace
+ */
 export const VERIFICATION_URI = {
     /** Query parameter key for client identification */
     CLIENT_PARAM_KEY: "client=",
     /** Full query parameter for Qwen Code client */
     CLIENT_PARAM_VALUE: "client=qwen-code",
 };
-/** Token refresh buffer (refresh 30 seconds before expiry) */
+
+/**
+ * Token refresh buffer in milliseconds
+ * Tokens are refreshed 30 seconds before expiry to avoid race conditions
+ * @constant {number}
+ */
 export const TOKEN_REFRESH_BUFFER_MS = 30 * 1000; // 30 seconds
-/** Stream processing configuration */
+
+/**
+ * Stream processing configuration
+ * @namespace
+ */
 export const STREAM_CONFIG = {
     /** Maximum buffer size for SSE pass-through mode (1MB) */
     MAX_BUFFER_SIZE: 1024 * 1024,
 };
-//# sourceMappingURL=constants.js.map

package/dist/lib/logger.js

@@ -1,10 +1,34 @@
+/**
+ * @fileoverview Logging utilities for Qwen OAuth Plugin
+ * Provides configurable logging for debugging and request tracing
+ * @license MIT
+ */
+
 import { writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-// Logging configuration
+
+/**
+ * Flag to enable request logging to file
+ * Controlled by ENABLE_PLUGIN_REQUEST_LOGGING environment variable
+ * @constant {boolean}
+ */
 export const LOGGING_ENABLED = process.env.ENABLE_PLUGIN_REQUEST_LOGGING === "1";
+
+/**
+ * Flag to enable debug logging to console
+ * Controlled by DEBUG_QWEN_PLUGIN or ENABLE_PLUGIN_REQUEST_LOGGING environment variables
+ * @constant {boolean}
+ */
 export const DEBUG_ENABLED = process.env.DEBUG_QWEN_PLUGIN === "1" || LOGGING_ENABLED;
+
+/**
+ * Directory path for log files
+ * Logs are stored in ~/.opencode/logs/qwen-plugin/
+ * @constant {string}
+ */
 const LOG_DIR = join(homedir(), ".opencode", "logs", "qwen-plugin");
+
 // Log startup message about logging state
 if (LOGGING_ENABLED) {
     console.log("[qwen-oauth-plugin] Request logging ENABLED - logs will be saved to:", LOG_DIR);
@@ -12,23 +36,34 @@ if (LOGGING_ENABLED) {
 if (DEBUG_ENABLED && !LOGGING_ENABLED) {
     console.log("[qwen-oauth-plugin] Debug logging ENABLED");
 }
+
+/**
+ * Request counter for generating unique request IDs in logs
+ * @type {number}
+ */
 let requestCounter = 0;
+
 /**
  * Log request data to file (only when LOGGING_ENABLED is true)
- * @param stage - The stage of the request (e.g., "before-transform", "after-transform")
- * @param data - The data to log
+ * Creates JSON files with request/response data for debugging
+ * @param {string} stage - The stage of the request (e.g., "before-transform", "after-transform", "response")
+ * @param {Object} data - The data to log (request/response objects, metadata, etc.)
+ * @returns {void}
  */
 export function logRequest(stage, data) {
     // Only log if explicitly enabled via environment variable
     if (!LOGGING_ENABLED)
         return;
+    
     // Ensure log directory exists on first log
     if (!existsSync(LOG_DIR)) {
         mkdirSync(LOG_DIR, { recursive: true });
     }
+    
     const timestamp = new Date().toISOString();
     const requestId = ++requestCounter;
     const filename = join(LOG_DIR, `request-${requestId}-${stage}.json`);
+    
     try {
         writeFileSync(filename, JSON.stringify({
             timestamp,
@@ -43,10 +78,13 @@ export function logRequest(stage, data) {
         console.error("[qwen-oauth-plugin] Failed to write log:", error.message);
     }
 }
+
 /**
  * Log debug information (only when DEBUG_ENABLED is true)
- * @param message - Debug message
- * @param data - Optional data to log
+ * Used for detailed debugging during development
+ * @param {string} message - Debug message describing the context
+ * @param {*} [data] - Optional data to log (objects, values, etc.)
+ * @returns {void}
  */
 export function logDebug(message, data) {
     if (!DEBUG_ENABLED)
@@ -58,10 +96,13 @@ export function logDebug(message, data) {
         console.log(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log error (always enabled for important issues)
- * @param message - Error message
- * @param data - Optional data to log
+ * Used for critical errors that need attention
+ * @param {string} message - Error message describing what went wrong
+ * @param {*} [data] - Optional data to log (error objects, context, etc.)
+ * @returns {void}
  */
 export function logError(message, data) {
     if (data !== undefined) {
@@ -71,10 +112,13 @@ export function logError(message, data) {
         console.error(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log warning (always enabled for important issues)
- * @param message - Warning message
- * @param data - Optional data to log
+ * Used for non-critical issues that may need attention
+ * @param {string} message - Warning message describing the issue
+ * @param {*} [data] - Optional data to log (context, values, etc.)
+ * @returns {void}
  */
 export function logWarn(message, data) {
     if (data !== undefined) {
@@ -84,10 +128,13 @@ export function logWarn(message, data) {
         console.warn(`[qwen-oauth-plugin] ${message}`);
     }
 }
+
 /**
  * Log info message (always enabled)
- * @param message - Info message
- * @param data - Optional data to log
+ * Used for general informational messages
+ * @param {string} message - Info message describing the event
+ * @param {*} [data] - Optional data to log (context, values, etc.)
+ * @returns {void}
  */
 export function logInfo(message, data) {
     if (data !== undefined) {
@@ -97,4 +144,3 @@ export function logInfo(message, data) {
         console.log(`[qwen-oauth-plugin] ${message}`);
     }
 }
-//# sourceMappingURL=logger.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-qwen-cli-auth",
-  "version": "2.2.9",
+  "version": "2.3.1",
   "description": "Qwen OAuth authentication plugin for opencode - use your Qwen account instead of API keys",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",