openyida 2026.9.22 → 2026.9.23-beta.1

package/README.md

@@ -74,6 +74,13 @@ openyida login
 
 OpenYida login defaults to OAuth token mode. It opens the DingTalk OAuth authorization page, receives the local loopback callback, exchanges `code` / `authCode` with the Yida server, and stores `access_token` / `refresh_token` in the user auth store when available. If the user auth store is not writable, OpenYida explicitly falls back to the current project cache and reports that narrower persistence scope.
 
+In a sandbox, headless shell, or CI dashboard where the loopback callback cannot complete, use the device authorization flow. Open the displayed verification URL on any device and enter the user code. `--env-hint` optionally pins the intended environment profile at authorization time:
+
+```bash
+openyida login --device
+openyida login --device --env-hint pre
+```
+
 When the user names a target Yida entry URL, pass it to the login command so OpenYida can select the matching environment and auth profile. For example:
 
 ```bash
@@ -383,7 +390,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
-| `openyida login [target-url] [--env <name>\|--intl\|--overseas\|--global\|--yidaapps\|--alibaba] [--client-id <clientId>] [--endpoint <url>] [--no-browser]` | Login with OAuth token mode |
+| `openyida login [target-url] [--env <name>\|--intl\|--overseas\|--global\|--yidaapps\|--alibaba] [--client-id <clientId>] [--endpoint <url>] [--no-browser] [--device] [--env-hint <name>]` | Login with OAuth token mode |
 | `openyida logout` | Logout / unbind current project auth |
 | `openyida auth <status\|login\|refresh\|logout\|profiles\|profile switch>` | Token login state and profile management |
 | `openyida org <list\|switch> [--json] [--corp-id <corpId>]` | Organization management (list / switch existing profiles first) |

package/bin/yida.js

@@ -279,6 +279,7 @@ function getFirstPositionalArg(cliArgs, startIndex = 0) {
     '--login-url',
     '--profile',
     '--user-id',
+    '--env-hint',
   ]);
   for (let index = startIndex; index < cliArgs.length; index++) {
     const arg = cliArgs[index];
@@ -386,6 +387,7 @@ function applyLoginEnvironmentFlags(cliArgs, options = {}) {
     '--client-id',
     '--profile',
     '--user-id',
+    '--env-hint',
   ]);
   const targetUrlFlags = new Set([
     '--endpoint',
@@ -537,13 +539,23 @@ function printLoginHelp() {
 }
 
 function buildTokenLoginOptions(loginArgs) {
+  const device = loginArgs.includes('--device');
   return {
     clientId: getArgValue(loginArgs, '--client-id'),
     corpId: getArgValue(loginArgs, '--corp-id'),
     userId: getArgValue(loginArgs, '--user-id'),
     authProfile: getArgValue(loginArgs, '--profile'),
     quiet: process.env.YIDA_QUIET === '1' || loginArgs.includes('--quiet'),
-    noBrowser: loginArgs.includes('--no-browser'),
+    noBrowser: device || loginArgs.includes('--no-browser'),
+    device,
+    envHint: getArgValue(loginArgs, '--env-hint'),
+    // Machine-readable progress events for agent runtimes (sandbox browsers,
+    // CI dashboards). Emits one JSON line per state transition.
+    onDeviceState: (state) => {
+      if (device) {
+        process.stdout.write(JSON.stringify({ type: 'device_login_state', ...state }) + '\n');
+      }
+    },
   };
 }
 

package/lib/auth/oauth-device.js

@@ -0,0 +1,278 @@
+/**
+ * oauth-device.js - Device Authorization Grant (RFC 8628) flow.
+ *
+ * Enables headless / sandbox login: the CLI requests a device code from the
+ * auth service, the user completes authorization on ANY device (phone,
+ * another browser, CI dashboard), and the CLI polls until tokens are issued.
+ *
+ * The /device/* endpoints use a unified camelCase contract (deviceCode,
+ * userCode, verificationUri, grantType, accessToken, ...) matching the
+ * tianshu CliAuthRpc device endpoints. Legacy CLI token endpoints
+ * (/dingtalk/token, /refresh, /status) keep their snake_case contract and are
+ * not handled here.
+ *
+ * Reuses the same token normalization / profile persistence pipeline as the
+ * loopback flow in oauth-loopback.js.
+ */
+
+const { requestJson } = require('./token-auth');
+
+const DEVICE_CODE_PATH = '/device/code';
+const DEVICE_TOKEN_PATH = '/device/token';
+const DEFAULT_DEVICE_TIMEOUT_MS = 10 * 60 * 1000; // device codes are usually valid 10 minutes
+const DEFAULT_POLL_INTERVAL_MS = 5 * 1000;
+const SLOW_DOWN_EXTRA_DELAY_MS = 5 * 1000;
+
+const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+
+function createDeviceTimeoutError() {
+  const timeout = new Error('device authorization timed out; device code may still be pending');
+  timeout.code = 'device_timeout';
+  return timeout;
+}
+
+function assertBeforeDeadline(deadline) {
+  if (Date.now() >= deadline) {
+    throw createDeviceTimeoutError();
+  }
+}
+
+function positiveNumber(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function errorDescription(payload) {
+  return payload.errorDescription || payload.error_description || payload.errorMsg
+    || payload.error_msg || payload.message || payload.raw || '';
+}
+
+/**
+ * Request a device code from the auth service.
+ *
+ * @param {object} options
+ * @param {string} options.authBaseUrl - e.g. https://yida-group.alibaba-inc.com/openapi/cli/v1/auth
+ * @param {string} options.clientId
+ * @param {string} [options.scope] - defaults handled by caller
+ * @param {string} [options.envHint] - environment name to pin the token audience
+ * @param {string} [options.timeoutMs] - overall flow timeout
+ * @returns {Promise<{deviceCode, userCode, verificationUri,
+ *   verificationUriComplete, expiresIn, interval}>}
+ */
+async function requestDeviceCode(options = {}) {
+  const { authBaseUrl, clientId } = options;
+  if (!authBaseUrl || !clientId) {
+    throw new Error('device code flow requires authBaseUrl and clientId');
+  }
+  const body = { clientId };
+  if (options.scope) { body.scope = options.scope; }
+  if (options.envHint) { body.envHint = options.envHint; }
+
+  const response = await requestJson(
+    'POST',
+    `${authBaseUrl}${DEVICE_CODE_PATH}`,
+    body
+  );
+  const payload = unwrapPayload(response);
+  if (!payload.deviceCode || !payload.userCode || !payload.verificationUri) {
+    const message = payload.message || payload.errorDescription || payload.errorMsg
+      || 'auth service did not return a usable device code';
+    const error = new Error(message);
+    error.payload = payload;
+    throw error;
+  }
+  return payload;
+}
+
+/**
+ * Poll the token endpoint until the device flow completes.
+ *
+ * @param {object} options
+ * @param {string} options.authBaseUrl
+ * @param {string} options.clientId
+ * @param {string} options.deviceCode
+ * @param {number} [options.intervalMs] - from /device/code response
+ * @param {number} [options.timeoutMs] - overall wall clock budget
+ * @param {(state: object) => void} [options.onState] - progress callback for agents
+ * @returns {Promise<object>} token payload (accessToken, refreshToken, ...)
+ */
+async function pollDeviceToken(options = {}) {
+  const { authBaseUrl, clientId, deviceCode } = options;
+  if (!authBaseUrl || !clientId || !deviceCode) {
+    throw new Error('device token polling requires authBaseUrl, clientId and deviceCode');
+  }
+  const intervalMs = Math.max(1, positiveNumber(options.intervalMs, DEFAULT_POLL_INTERVAL_MS));
+  const deadline = Date.now() + positiveNumber(options.timeoutMs, DEFAULT_DEVICE_TIMEOUT_MS);
+  let currentInterval = intervalMs;
+
+  // First poll immediately, then honor the interval.
+  for (;;) {
+    assertBeforeDeadline(deadline);
+    let response;
+    try {
+      response = await requestJson('POST', `${authBaseUrl}${DEVICE_TOKEN_PATH}`, {
+        grantType: DEVICE_GRANT_TYPE,
+        deviceCode: deviceCode,
+        clientId: clientId,
+      });
+    } catch (error) {
+      const payload = error.payload || {};
+      const errorCode = payload.error || payload.errorCode || payload.error_msg || payload.errorMsg;
+      if (errorCode === 'authorization_pending') {
+        await waitFor(deadline, currentInterval, options);
+        continue;
+      }
+      if (errorCode === 'slow_down') {
+        currentInterval += SLOW_DOWN_EXTRA_DELAY_MS;
+        if (options.onState) {
+          options.onState({ state: 'slow_down', intervalMs: currentInterval });
+        }
+        await waitFor(deadline, currentInterval, options);
+        continue;
+      }
+      if (errorCode === 'expired_token') {
+        const expired = new Error('device code expired; run login --device again');
+        expired.code = 'device_code_expired';
+        throw expired;
+      }
+      if (errorCode === 'access_denied') {
+        const denied = new Error('authorization was denied on the verification page');
+        denied.code = 'device_access_denied';
+        throw denied;
+      }
+      if (errorCode) {
+        // RFC 8628 only permits polling to continue for
+        // authorization_pending and slow_down. Preserve the server's
+        // permanent OAuth error so callers can diagnose it immediately.
+        error.code = String(errorCode);
+        const description = errorDescription(payload);
+        if (description) { error.message = String(description); }
+        throw error;
+      }
+      if (error.statusCode === 400 || error.statusCode === 429) {
+        // Unstructured 400/429 bodies can be produced by gateways. Retry
+        // those transient shapes, while the OAuth errors above remain
+        // terminal unless the RFC explicitly permits continued polling.
+        if (options.onState) {
+          options.onState({
+            state: 'poll_retry',
+            statusCode: error.statusCode,
+            body: String(errorDescription(payload)).slice(0, 200),
+          });
+        }
+        await waitFor(deadline, currentInterval, options);
+        continue;
+      }
+      throw error;
+    }
+
+    const payload = unwrapPayload(response);
+    if (!payload.accessToken && !payload.access_token) {
+      // 2xx without a token is unexpected; surface raw payload for diagnosis.
+      const invalid = new Error('auth service returned 2xx without accessToken');
+      invalid.payload = payload;
+      throw invalid;
+    }
+    return payload;
+  }
+}
+
+function waitFor(deadline, intervalMs, options) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) {
+    throw createDeviceTimeoutError();
+  }
+  if (options && options.onState) {
+    options.onState({ state: 'pending', nextPollMs: Math.min(intervalMs, remaining) });
+  }
+  return new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remaining)));
+}
+
+function unwrapPayload(response) {
+  if (response && typeof response === 'object' && response.content && typeof response.content === 'object') {
+    return response.content;
+  }
+  return response || {};
+}
+
+/**
+ * Run the full device code flow and return a token payload for
+ * normalizeTokenResponse(). Designed to be called from tokenLogin().
+ *
+ * @param {object} options - same option bag as tokenLogin plus:
+ *   options.authBaseUrl  resolved auth base (with /openapi/cli/v1/auth prefix)
+ *   options.envHint      environment name to pin audience
+ *   options.quiet        suppress human-oriented stderr
+ *   options.onState      optional machine-readable progress callback
+ */
+async function runDeviceCodeFlow(options = {}) {
+  const code = await requestDeviceCode(options);
+
+  // The server may return verification URIs as absolute paths (e.g.
+  // /openapi/cli/v1/auth/device/verify); resolve them against the business
+  // base URL so users and agent hosts get clickable links.
+  const resolveUrl = (value) => {
+    if (!value || /^https?:\/\//i.test(value)) {
+      return value;
+    }
+    try {
+      const origin = new URL(options.baseUrl || options.authBaseUrl).origin;
+      return new URL(value, origin).toString();
+    } catch {
+      return value;
+    }
+  };
+  const verificationUri = resolveUrl(code.verificationUri);
+  const verificationUriComplete = resolveUrl(code.verificationUriComplete);
+
+  const intro = [
+    '',
+    'Device code login:',
+    `  1. Open ${verificationUri}`,
+    `  2. Enter code: ${code.userCode}`,
+    '',
+  ];
+  if (verificationUriComplete) {
+    intro.push(`  Or open directly: ${verificationUriComplete}`, '');
+  }
+  if (!options.quiet) {
+    process.stderr.write(intro.join('\n') + '\n');
+  }
+
+  if (options.onState) {
+    options.onState({
+      state: 'awaiting_verification',
+      verification_uri: verificationUri,
+      verification_uri_complete: verificationUriComplete,
+      user_code: code.userCode,
+      expires_in: code.expiresIn,
+      interval: code.interval,
+    });
+  }
+
+  const tokenPayload = await pollDeviceToken({
+    authBaseUrl: options.authBaseUrl,
+    clientId: options.clientId,
+    deviceCode: code.deviceCode,
+    intervalMs: (code.interval || 5) * 1000,
+    timeoutMs: Math.min(
+      positiveNumber(code.expiresIn, 600) * 1000,
+      positiveNumber(options.timeoutMs, Number.POSITIVE_INFINITY)
+    ),
+    onState: options.onState,
+  });
+
+  if (!options.quiet) {
+    process.stderr.write('Device authorization completed.\n');
+  }
+  return tokenPayload;
+}
+
+module.exports = {
+  runDeviceCodeFlow,
+  requestDeviceCode,
+  pollDeviceToken,
+  DEVICE_CODE_PATH,
+  DEVICE_TOKEN_PATH,
+  DEVICE_GRANT_TYPE,
+};

package/lib/auth/token-auth.js

@@ -302,25 +302,43 @@ async function tokenLogin(options = {}) {
   const baseUrl = resolveTokenBaseUrl(options);
   const authBaseUrl = appendPath(baseUrl, DEFAULT_AUTH_PATH_PREFIX);
   const clientId = options.clientId || process.env.OPENYIDA_DINGTALK_CLIENT_ID || DINGTALK_OAUTH_CLIENT_ID;
-  const callback = await runDingtalkLoopback({
-    clientId,
-    loginOrigin: resolveDingtalkLoginOrigin(options),
-    scope: options.scope || process.env.OPENYIDA_DINGTALK_SCOPE || 'openid corpid',
-    prompt: options.prompt,
-    port: options.port,
-    quiet: options.quiet,
-    noBrowser: options.noBrowser,
-    timeoutMs: options.timeoutMs,
-  });
+  const scope = options.scope || process.env.OPENYIDA_DINGTALK_SCOPE || 'openid corpid';
+
+  let response;
+  if (options.device) {
+    // Device Authorization Grant (RFC 8628): sandbox / headless login.
+    const { runDeviceCodeFlow } = require('./oauth-device');
+    response = await runDeviceCodeFlow({
+      authBaseUrl,
+      clientId,
+      scope,
+      envHint: options.envHint,
+      quiet: options.quiet,
+      onState: options.onDeviceState,
+      timeoutMs: options.timeoutMs || env.OPENYIDA_OAUTH_TIMEOUT_MS,
+    });
+    requireOkResponse(response);
+  } else {
+    const callback = await runDingtalkLoopback({
+      clientId,
+      loginOrigin: resolveDingtalkLoginOrigin(options),
+      scope,
+      prompt: options.prompt,
+      port: options.port,
+      quiet: options.quiet,
+      noBrowser: options.noBrowser,
+      timeoutMs: options.timeoutMs,
+    });
 
-  const response = await requestJson('POST', appendPath(authBaseUrl, '/dingtalk/token'), {
-    code: callback.code,
-    authCode: callback.authCode,
-    redirectUri: callback.redirectUri,
-    state: callback.state,
-    clientId,
-  });
-  requireOkResponse(response);
+    response = await requestJson('POST', appendPath(authBaseUrl, '/dingtalk/token'), {
+      code: callback.code,
+      authCode: callback.authCode,
+      redirectUri: callback.redirectUri,
+      state: callback.state,
+      clientId,
+    });
+    requireOkResponse(response);
+  }
 
   const normalized = normalizeTokenResponse(response, baseUrl, clientId);
   if (!normalized.access_token) {

package/lib/core/command-manifest.js

@@ -1034,7 +1034,7 @@ const COMMAND_GROUPS = [
     id: 'auth',
     titleKey: 'help.group_auth',
     commands: [
-      command('login', ['login'], 'login [target-url] [--env <name>|--intl|--overseas|--global|--yidaapps|--alibaba] [--client-id <clientId>] [--endpoint <url>] [--no-browser]', 'help.cmd_login', {
+      command('login', ['login'], 'login [target-url] [--env <name>|--intl|--overseas|--global|--yidaapps|--alibaba] [--client-id <clientId>] [--endpoint <url>] [--no-browser] [--device] [--env-hint <name>]', 'help.cmd_login', {
         requiresLogin: false,
         output: 'json',
       }),

package/lib/core/locales/en.js

@@ -373,8 +373,8 @@ Examples:
     save_permission_usage: 'Usage: openyida save-permission <appType> <formUuid> [--package-uuid <packageUuid>] [--data-permission <json>] [--action-permission <json>]',
     save_permission_example: "Example: openyida save-permission APP_XXX FORM-XXX --data-permission '{\"role\":\"DEFAULT\",\"dataRange\":\"SELF\"}'",
     exec_failed: '\n❌ Execution failed: {0}',
-    login_usage: 'Usage: openyida login [entryUrl|--public|--alibaba|--intl] [--no-browser] [--check-only] [--json] [--client-id <clientId>]',
-    login_example: 'Examples:\n  openyida login                         # Automatically open the browser via OAuth loopback login\n  openyida login --no-browser            # Let the caller handle the authorization URL\n  openyida login --check-only --json     # Check token auth status only\n  openyida login --intl                  # Login against the international environment\n  OPENYIDA_NO_BROWSER=1 openyida login   # Suppress auto-opening the browser with an environment variable\n  openyida auth login                    # Login alias',
+    login_usage: 'Usage: openyida login [entryUrl|--public|--alibaba|--intl] [--no-browser] [--device] [--env-hint <name>] [--check-only] [--json] [--client-id <clientId>]',
+    login_example: 'Examples:\n  openyida login                         # Automatically open the browser via OAuth loopback login\n  openyida login --device                # Use device authorization in a headless environment\n  openyida login --device --env-hint pre # Pin device authorization to an environment profile\n  openyida login --no-browser            # Let the caller handle the authorization URL\n  openyida login --check-only --json     # Check token auth status only\n  openyida login --intl                  # Login against the international environment\n  OPENYIDA_NO_BROWSER=1 openyida login   # Suppress auto-opening the browser with an environment variable\n  openyida auth login                    # Login alias',
     login_unsupported_option: 'Removed legacy login option is no longer supported: {0}. Use token/OAuth login; env token mode reads only OPENYIDA_* tokens.',
     auth_usage: 'Usage: openyida auth <status|login|refresh|logout|profiles|profile switch>',
     auth_example: 'Examples:\n  openyida auth status                         # View login status\n  openyida auth profiles                       # List existing login profiles\n  openyida auth profile switch <auth_profile>  # Switch current project to an existing profile\n  openyida auth login                          # Add a profile when the target does not exist\n  openyida auth refresh                        # Refresh login session\n  openyida auth logout                         # Unbind current project auth\n  openyida auth logout --profile <auth_profile> # Delete a shared profile explicitly',

package/lib/core/locales/zh.js

@@ -373,8 +373,8 @@ openyida - 宜搭命令行工具
     save_permission_usage: '用法: openyida save-permission <appType> <formUuid> [--package-uuid <packageUuid>] [--data-permission <json>] [--action-permission <json>]',
     save_permission_example: "示例: openyida save-permission APP_XXX FORM-XXX --data-permission '{\"role\":\"DEFAULT\",\"dataRange\":\"SELF\"}'",
     exec_failed: '\n❌ 执行失败: {0}',
-    login_usage: '用法: openyida login [entryUrl|--public|--alibaba|--intl] [--no-browser] [--check-only] [--json] [--client-id <clientId>]',
-    login_example: '示例:\n  openyida login                         # 通过 OAuth loopback 自动打开浏览器登录\n  openyida login --no-browser            # 不自动打开浏览器，由调用方接管授权链接\n  openyida login --check-only --json     # 只检查 token 登录态\n  openyida login --intl                  # 使用国际站环境登录\n  OPENYIDA_NO_BROWSER=1 openyida login   # 通过环境变量抑制自动打开浏览器\n  openyida auth login                    # 登录入口别名',
+    login_usage: '用法: openyida login [entryUrl|--public|--alibaba|--intl] [--no-browser] [--device] [--env-hint <name>] [--check-only] [--json] [--client-id <clientId>]',
+    login_example: '示例:\n  openyida login                         # 通过 OAuth loopback 自动打开浏览器登录\n  openyida login --device                # 在无浏览器或沙箱环境使用设备授权登录\n  openyida login --device --env-hint pre # 将设备授权限定到指定环境 profile\n  openyida login --no-browser            # 不自动打开浏览器，由调用方接管授权链接\n  openyida login --check-only --json     # 只检查 token 登录态\n  openyida login --intl                  # 使用国际站环境登录\n  OPENYIDA_NO_BROWSER=1 openyida login   # 通过环境变量抑制自动打开浏览器\n  openyida auth login                    # 登录入口别名',
     login_unsupported_option: '已删除的旧登录参数不再支持: {0}。请使用 token/OAuth 登录；env token 模式下只读取 OPENYIDA_* token。',
     first_run_title: '  🤖 OpenYida - AI 问答模式已开启！                         ',
     first_run_welcome: '  {0}欢迎首次使用 OpenYida！{1} 以下是快速上手指南：',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.9.22",
+  "version": "2026.9.23-beta.1",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",