@1endpoint/coding-helper 0.1.2 → 0.1.3

package/README.md

@@ -19,8 +19,10 @@ npx @1endpoint/coding-helper
 1. Choose **English** or **Tiếng Việt**.
 2. Choose **Setup**.
 3. Select **DSH** or **Claude Code**.
-4. Select models from the 1endpoint catalog.
-5. Review the selection, then choose **Confirm**.
+4. Paste your API key into the masked prompt, or select **Open Console** and press Enter to create a key first.
+5. Choose whether to save the key locally or use it for this session only.
+6. Select models from the 1endpoint catalog.
+7. Review the selection, then choose **Confirm**.
 
 Use **↑ / ↓** to move and **Enter** to select. Press **Escape** to cancel. Confirmation is a selection, not a typed `y/n` answer.
 
@@ -34,9 +36,21 @@ If the catalog cannot be loaded, choose **Retry**, explicitly choose **Manual mo
 
 ## 2. Provide your API key
 
-The helper does **not** save your API key. Set `ONEENDPOINT_API_KEY` in the terminal where you will launch the tool, using your secret manager or a hidden prompt.
+Paste your key directly into the helper's **masked API-key prompt**. The key is not shown on screen or placed in command arguments.
 
-For **Bash**, the following prompt keeps the key out of the command itself and hides it while you type:
+Need a key? Select **Open Console** and press **Enter**. The helper opens [API keys](https://console.1endpoint.dev/api-keys), or the [Vietnamese API-key page](https://console.1endpoint.dev/vi/api-keys) when Vietnamese is selected. Create a key, copy it, return to the terminal and paste it into the prompt.
+
+Choose how to use the key:
+
+- **Save locally:** remember it for the selected tool, so future launches do not require manual environment export. The saved file is plaintext, **not encrypted**, protected with private file permissions (0600 file, 0700 directory on POSIX systems). Other processes running as your user may still access it.
+- **This session only:** keep it in memory for this helper process. After setup, select **Start a new session now** to launch with it. Reopening the helper later requires entering the key again.
+- **Use an existing key:** reuse an available environment or saved key without displaying its value.
+
+DSH and Claude Code store their keys separately. An explicit session key takes priority, followed by `ONEENDPOINT_API_KEY`, then the selected tool's saved key. The helper never puts keys in generated tool settings, model configuration, backups or logs.
+
+### Optional: use an environment variable
+
+If you prefer a secret manager or shell environment instead of local storage, provide `ONEENDPOINT_API_KEY`. For **Bash**, this hidden prompt keeps the key out of the command itself:
 
 ```bash
 read -r -s -p "1endpoint API key: " ONEENDPOINT_API_KEY
@@ -60,7 +74,7 @@ For Claude Code:
 npx @1endpoint/coding-helper doctor --tool claude
 ```
 
-Doctor checks your saved connection configuration, whether the tool is installed, and whether the key environment variable is present. It does not validate the key against the server or make an inference request.
+Doctor checks your saved connection configuration, whether the tool is installed, and whether an environment or saved API key is available. It does not validate the key against the server or make an inference request.
 
 ## 4. Start a new tool session
 
@@ -130,7 +144,13 @@ npx @1endpoint/coding-helper remove --tool dsh --dry-run
 npx @1endpoint/coding-helper remove --tool dsh --yes
 ```
 
-Use `--tool claude` for Claude Code. Removal deletes only the helper-generated connection configuration. **Your original tool settings, runtime conversations and configuration backups are preserved.** To return to your ordinary setup, launch `dsh` or `claude` directly.
+Use `--tool claude` for Claude Code. The menu asks whether to **keep or delete the saved API key**. For scripted removal, add `--remove-key` to delete it explicitly:
+
+```bash
+npx @1endpoint/coding-helper remove --tool dsh --yes --remove-key
+```
+
+Without that choice, the saved key is retained. Removal deletes only the helper-generated connection configuration and, when selected, its saved key. **Your original tool settings, runtime conversations and configuration backups are preserved.** To return to your ordinary setup, launch `dsh` or `claude` directly.
 
 ### Recover from damaged connection configuration
 
@@ -162,7 +182,7 @@ This is an independent integration, not an official DeepSeek or Anthropic produc
 | --- | --- |
 | Node version error | Install Node.js 22.19 or newer, then reopen your terminal. |
 | CLI not found | Install the selected coding tool and make sure its executable is on your `PATH`. |
-| API key missing | Set `ONEENDPOINT_API_KEY` in the same terminal, then run Doctor again. |
+| API key missing | Open the helper and paste a key, or press Enter on Open Console to create one. Choose Save locally for future launches. |
 | Catalog unavailable | Choose Retry, or explicitly choose manual entry with a known public model ID. |
 | New model is not taking effect | Close the old session and start a new one with the helper's Run action. |
 | Ordinary tool launch ignores the helper | Launch through `npx @1endpoint/coding-helper run --tool dsh` or `--tool claude`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1endpoint/coding-helper",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Safe isolated 1endpoint setup for DeepSeek Harness and Claude Code CLI",
   "type": "module",
   "bin": {

package/src/browser.mjs

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process'
+
+/** Explicitly open only the Console create-key page; never accepts a caller URL. */
+export function openConsole({ language = 'en', spawnImpl = spawn, platform = process.platform } = {}) {
+  const url = language === 'vi' ? 'https://console.1endpoint.dev/vi/api-keys' : 'https://console.1endpoint.dev/api-keys'
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'rundll32.exe' : 'xdg-open'
+  const args = platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url]
+  return new Promise((resolve, reject) => {
+    let child, timer, settled = false
+    const fail = () => {
+      const error = new Error('Could not open Console. Try again or open the Console API keys page manually.')
+      error.code = 'BROWSER_OPEN_FAILED'
+      return error
+    }
+    const finish = error => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (child) {
+        child.off('error', onError)
+        child.off('close', onClose)
+        // Absorb a late spawn error after timeout.
+        child.on('error', () => {})
+      }
+      if (error) reject(error)
+      else resolve()
+    }
+    const onError = () => finish(fail())
+    const onClose = code => finish(code === 0 ? undefined : fail())
+    try {
+      child = spawnImpl(command, args, { shell: false, stdio: 'ignore', windowsHide: true })
+      child.once('error', onError)
+      child.once('close', onClose)
+      timer = setTimeout(() => {
+        try { child.kill() } catch {}
+        finish(fail())
+      }, 5000)
+    } catch { finish(fail()) }
+  })
+}

package/src/cli.mjs

@@ -7,13 +7,14 @@ import { wizard, colorize } from './ui.mjs'
 import { setup, reconfigure, remove, backup, loadState, stateRoot, validateTool, assertSafePath } from './state.mjs'
 import { launchClaude, childEnvironment } from './adapters/claude.mjs'
 import { launchDsh } from './adapters/dsh.mjs'
+import { getCredential, saveCredential, removeCredential } from './credentials.mjs'
 
 const HELP = `@1endpoint/coding-helper — isolated 1endpoint coding-tool setup
 
 Usage:
   coding-helper setup --tool dsh|claude --model PUBLIC_MODEL [--dry-run] [--update]
   coding-helper reconfigure --tool dsh|claude --model PUBLIC_MODEL [--dry-run]
-  coding-helper remove --tool dsh|claude [--yes] [--dry-run] [--force]
+  coding-helper remove --tool dsh|claude [--yes] [--dry-run] [--force] [--remove-key]
   coding-helper doctor --tool dsh|claude
   coding-helper run --tool dsh|claude [--profile web|headless|acp|sdk] -- [tool args]
   coding-helper backup --tool dsh|claude
@@ -24,7 +25,9 @@ Wizard fetches public 1endpoint text models for independent tool/tier selections
 Claude setup/reconfigure accepts --haiku-model ID --sonnet-model ID --opus-model ID
 and optional --fable-model ID for supporting versions. --model is the main/default fallback.
 Node.js >=22.19 is required.
-API key: export ONEENDPOINT_API_KEY in your shell; never pass it as an argument.
+Paste your API key privately in the menu, or press Enter on Open Console to create one.
+Choose private local storage or session-only use. Saved keys are plaintext private files, not encrypted.
+ONEENDPOINT_API_KEY remains an optional environment override; never pass keys as arguments.
 State: ONEENDPOINT_HELPER_HOME or ~/.1endpoint/coding-helper (isolated tool homes).
 No existing DSH/Claude settings are edited. Setup/doctor make no API requests.
 Claude launch excludes project/local settings, hooks and permissions; managed policy applies.
@@ -38,12 +41,12 @@ function parse(argv) {
   while (args.length) {
     const arg = args.shift()
     if (arg === '--') { forwarded.push(...args); break }
-    if (['--dry-run', '--update', '--yes', '--force'].includes(arg)) { if (options[arg]) throw new Error('Duplicate option.'); options[arg] = true; continue }
+    if (['--dry-run', '--update', '--yes', '--force', '--remove-key'].includes(arg)) { if (options[arg]) throw new Error('Duplicate option.'); options[arg] = true; continue }
     if (!['--tool', '--model', '--profile', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'].includes(arg)) throw new Error('Unknown option. Use --help. API keys must never be command-line arguments.')
     if (options[arg] !== undefined || !args.length || args[0].startsWith('-')) throw new Error('Missing or duplicate option value.')
     options[arg] = args.shift()
   }
-  const allowed = { setup: ['--tool', '--model', '--dry-run', '--update', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], reconfigure: ['--tool', '--model', '--dry-run', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], remove: ['--tool', '--yes', '--dry-run', '--force'], doctor: ['--tool'], backup: ['--tool'], run: ['--tool', '--profile'] }
+  const allowed = { setup: ['--tool', '--model', '--dry-run', '--update', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], reconfigure: ['--tool', '--model', '--dry-run', '--haiku-model', '--sonnet-model', '--opus-model', '--fable-model'], remove: ['--tool', '--yes', '--dry-run', '--force', '--remove-key'], doctor: ['--tool'], backup: ['--tool'], run: ['--tool', '--profile'] }
   if (!allowed[command] || Object.keys(options).some(key => !allowed[command].includes(key)) || (command !== 'run' && forwarded.length)) throw new Error('Invalid command/options. Use --help.')
   validateTool(options['--tool'])
   if (options['--tool'] !== 'claude' && ['haiku', 'sonnet', 'opus', 'fable'].some(role => options[`--${role}-model`])) throw new Error('Tier model flags are only supported for Claude.')
@@ -63,7 +66,10 @@ async function executable(command, env) {
   return null
 }
 async function main(argv, context = {}) {
-  if (!argv.length) return wizard({ dispatch: main })
+  if (!argv.length) return wizard({ dispatch: main, getKeyStatus: async ({ tool }) => {
+    const credential = await getCredential({ stateDir: stateRoot(), tool })
+    return { available: Boolean(credential.key), source: credential.source }
+  } })
   if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) { console.log(HELP); return }
   if (argv.length === 1 && ['--version', '-v'].includes(argv[0])) {
     const metadata = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf8'))
@@ -76,8 +82,12 @@ async function main(argv, context = {}) {
     const result = await remove({ stateDir, tool, dryRun: options['--dry-run'], yes: options['--yes'], force: options['--force'] })
     console.log(`${result.dryRun ? t('Preview removal', 'Xem trước việc xóa') : result.changed ? t('Removed helper configuration', 'Đã xóa cấu hình riêng') : t('Already removed', 'Cấu hình đã được xóa')}: ${tool}`)
     for (const file of result.files) console.log(`  ${file}`)
+    if (options['--remove-key'] || context.removeKey) {
+      await removeCredential({ stateDir, tool, dryRun: Boolean(options['--dry-run']) })
+      console.log(options['--dry-run'] ? t('Saved-key removal preview only.', 'Chỉ xem trước việc xóa khóa đã lưu.') : t('Saved API key removed (if present).', 'Đã xóa khóa API đã lưu (nếu có).'))
+    }
     if (result.force) console.log(t('Forced recovery removes only fixed helper configuration paths; modified contents are not backed up.', 'Khôi phục cưỡng chế chỉ xóa đường dẫn cấu hình riêng cố định; nội dung đã sửa không được sao lưu.'))
-    console.log(t('Existing user settings, runtime homes, backups and unknown files were preserved.', 'Đã giữ nguyên cài đặt gốc, dữ liệu phiên chạy, bản sao lưu và các tệp khác.'))
+    console.log(t('Original tool settings, conversations and backups are unchanged.', 'Cài đặt gốc, hội thoại và bản sao lưu được giữ nguyên.'))
     return
   }
   if (command === 'setup' || command === 'reconfigure') {
@@ -87,25 +97,31 @@ async function main(argv, context = {}) {
     for (const file of result.files) console.log(`  ${file.path}`)
     if (context.language !== 'vi') for (const hint of result.hints || []) console.log(hint)
     else console.log(tool === 'claude' ? 'Không nạp cài đặt, hook và quyền project/local. Chính sách quản trị vẫn áp dụng; không bỏ qua quyền.' : 'DSH dùng home và cấu hình riêng; không sửa cài đặt gốc. Chế độ sdk-minimal không được hỗ trợ.')
-    console.log(t('Set ONEENDPOINT_API_KEY in your shell, then use run --tool ', 'Đặt ONEENDPOINT_API_KEY trong môi trường shell, sau đó dùng run --tool ') + tool + t('. No key was saved.', '. Không lưu khóa API.'))
+    if (!result.dryRun && context.apiKey && context.saveKey) {
+      await saveCredential({ stateDir, tool, key: context.apiKey })
+      console.log(t('API key saved privately for this tool. Local storage is not encrypted.', 'Đã lưu khóa API riêng cho công cụ này. Tệp lưu cục bộ không được mã hóa.'))
+    } else if (context.apiKey) console.log(t('API key is available for this session only.', 'Khóa API chỉ dùng trong phiên này.'))
+    else console.log(t('Use the interactive menu to paste an API key, or provide ONEENDPOINT_API_KEY in your environment.', 'Mở menu để dán khóa API, hoặc cung cấp ONEENDPOINT_API_KEY qua môi trường.'))
     if (!result.dryRun && !context.language) console.log(colorize('RESTART REQUIRED: existing sessions are not updated. Start a new session through coding-helper run --tool ' + tool + '.', 'warning'))
     return
   }
   if (command === 'backup') { console.log('Secret-free configuration backup: ' + await backup({ stateDir, tool })); return }
   const { state, plan } = await loadState(stateDir, tool)
+  const credential = context.apiKey ? { key: context.apiKey, source: 'session' } : await getCredential({ stateDir, tool })
   const bin = await executable(plan.command, process.env)
   if (command === 'doctor') {
     console.log(`${t('Configuration integrity: OK', 'Tính toàn vẹn cấu hình: OK')} (${tool})`)
     console.log(`${t('CLI installed', 'Đã cài CLI')}: ${bin ? t('yes', 'có') : t('no', 'chưa')}`)
-    console.log(`ONEENDPOINT_API_KEY: ${process.env.ONEENDPOINT_API_KEY ? t('present (not validated)', 'đã có (chưa xác thực)') : t('missing', 'chưa có')}`)
+    console.log(`${t('API key', 'Khóa API')}: ${credential.key ? t('available (not validated)', 'đã có (chưa xác thực)') : t('missing', 'chưa có')}`)
     console.log(t('No credentials read from tool files. No network or inference check performed.', 'Không đọc thông tin đăng nhập từ tệp công cụ. Không kiểm tra mạng hoặc gọi mô hình.'))
     if (context.language !== 'vi') for (const hint of plan.hints || []) console.log(hint)
-    if (!bin || !process.env.ONEENDPOINT_API_KEY) process.exitCode = 1
+    if (!bin || !credential.key) process.exitCode = 1
     return
   }
   if (!bin) throw new Error('CLI not found on PATH. Install the tool from its official distribution first.')
-  const key = process.env.ONEENDPOINT_API_KEY
-  if (!key || /[\r\n\0]/.test(key)) throw new Error('Set a valid ONEENDPOINT_API_KEY in the environment. It is never saved.')
+  const key = credential.key
+  if (!key || /[\s\x00-\x1f\x7f-\x9f]/.test(key)) throw new Error(t('Add an API key through the interactive menu or set ONEENDPOINT_API_KEY.', 'Thêm khóa API qua menu hoặc đặt ONEENDPOINT_API_KEY.'))
+  if (context.apiKey && context.saveKey) await saveCredential({ stateDir, tool, key })
   let launch
   try { launch = (tool === 'dsh' ? launchDsh : launchClaude)({ stateDir, model: state.model, roleModels: state.roles, args: forwarded, profile: options['--profile'] || 'web' }) }
   catch { throw new Error('Unsupported tool arguments: routing, agent/plugin and permission-bypass overrides are not allowed.') }

package/src/credentials.mjs

@@ -0,0 +1,158 @@
+import fs from 'node:fs/promises'
+import { constants } from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { assertSafePath, validateTool } from './state.mjs'
+
+// Opt-in local storage is plaintext, NOT encryption. Credentials are kept only in
+// credentials/<tool>.json (0600), inside credentials/ (0700), never manifests or
+// backups. Atomic replacement leaves the previous credential intact on failure.
+const failure = () => new Error('Unable to access a safe credential store. Check ownership, permissions, and saved credential format.')
+const invalidKey = () => new Error('Provide a valid API key token without whitespace or control characters.')
+const MAX_BYTES = 16384
+const posix = process.platform !== 'win32'
+
+function token(key) {
+  if (typeof key !== 'string' || !key.length || key.length > 8192 || /[\s\p{Cc}\p{Cf}]/u.test(key)) throw invalidKey()
+  return key
+}
+function locations(stateDir, tool) {
+  validateTool(tool)
+  if (typeof stateDir !== 'string' || !stateDir.length) throw failure()
+  const root = path.resolve(stateDir)
+  return { root, dir: path.join(root, 'credentials'), file: path.join(root, 'credentials', `${tool}.json`), lock: path.join(root, '.setup.lock') }
+}
+function owned(stat) {
+  if (posix && typeof process.getuid === 'function' && stat.uid !== process.getuid()) throw failure()
+}
+function privateFile(stat) {
+  owned(stat)
+  if (!stat.isFile() || stat.nlink !== 1 || (posix && (stat.mode & 0o7777) !== 0o600) || stat.size > MAX_BYTES) throw failure()
+}
+async function optionalStat(file) {
+  try { return await fs.lstat(file) } catch (error) { if (error.code === 'ENOENT') return null; throw error }
+}
+async function inspect(paths) {
+  await assertSafePath(paths.file)
+  const root = await optionalStat(paths.root)
+  if (root) {
+    owned(root)
+    if (!root.isDirectory() || (posix && (root.mode & 0o022))) throw failure()
+  }
+  const dir = await optionalStat(paths.dir)
+  if (dir) {
+    owned(dir)
+    if (!dir.isDirectory() || (posix && (dir.mode & 0o7777) !== 0o700)) throw failure()
+  }
+  const stat = await optionalStat(paths.file)
+  if (stat) privateFile(stat)
+  return stat
+}
+function sameFile(a, b) { return a.dev === b.dev && a.ino === b.ino }
+async function readSaved(paths, tool) {
+  const stat = await inspect(paths)
+  if (!stat) return null
+  const handle = await fs.open(paths.file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0))
+  try {
+    const opened = await handle.stat()
+    privateFile(opened)
+    if (!sameFile(stat, opened)) throw failure()
+    const raw = await handle.readFile('utf8')
+    const after = await handle.stat()
+    privateFile(after)
+    if (Buffer.byteLength(raw) > MAX_BYTES || !sameFile(opened, after)) throw failure()
+    const current = await inspect(paths)
+    if (!current || !sameFile(opened, current)) throw failure()
+    const saved = JSON.parse(raw)
+    if (!saved || typeof saved !== 'object' || Array.isArray(saved) || Object.keys(saved).sort().join(',') !== 'key,tool,version' || saved.version !== 1 || saved.tool !== tool) throw failure()
+    return token(saved.key)
+  } finally { await handle.close() }
+}
+
+export async function getCredential({ stateDir, tool, env = process.env }) {
+  validateTool(tool)
+  const key = env.ONEENDPOINT_API_KEY
+  // An invalid nonempty environment token must not silently fall back to disk.
+  if (key !== undefined && key !== '') return { key: token(key), source: 'environment' }
+  try {
+    const saved = await readSaved(locations(stateDir, tool), tool)
+    return saved === null ? { key: undefined, source: 'missing' } : { key: saved, source: 'saved' }
+  } catch { throw failure() }
+}
+
+export async function credentialExists({ stateDir, tool }) {
+  return (await getCredential({ stateDir, tool, env: {} })).source === 'saved'
+}
+
+async function withLock(paths, operation) {
+  await inspect(paths)
+  await fs.mkdir(paths.root, { recursive: true, mode: 0o700 })
+  await inspect(paths)
+  await assertSafePath(paths.lock)
+  let lock
+  try { lock = await fs.open(paths.lock, 'wx', 0o600) } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Another setup may be active. Review the helper lock before retrying.')
+    throw error
+  }
+  try { return await operation() } finally {
+    const held = await lock.stat()
+    await lock.close()
+    await assertSafePath(paths.lock)
+    const current = await optionalStat(paths.lock)
+    if (!current || !sameFile(held, current)) throw failure()
+    await fs.unlink(paths.lock)
+  }
+}
+
+export async function saveCredential({ stateDir, tool, key }) {
+  const paths = locations(stateDir, tool)
+  token(key)
+  try {
+    return await withLock(paths, async () => {
+      const previous = await readSaved(paths, tool)
+      if (previous === key) return { changed: false }
+      await fs.mkdir(paths.dir, { mode: 0o700, recursive: true })
+      await inspect(paths)
+      const temp = path.join(paths.dir, `.${tool}-${randomUUID()}.tmp`)
+      let handle
+      try {
+        handle = await fs.open(temp, 'wx', 0o600)
+        await handle.chmod(0o600)
+        await handle.writeFile(JSON.stringify({ version: 1, tool, key }) + '\n', 'utf8')
+        await handle.sync()
+        await handle.close()
+        handle = null
+        // The only commit is rename: all fallible preparation happens first.
+        await inspect(paths)
+        await assertSafePath(temp)
+        privateFile(await fs.lstat(temp))
+        await fs.rename(temp, paths.file)
+        return { changed: true }
+      } finally {
+        if (handle) await handle.close()
+        await fs.unlink(temp).catch(error => { if (error.code !== 'ENOENT') throw error })
+      }
+    })
+  } catch (error) {
+    if (error.message === 'Another setup may be active. Review the helper lock before retrying.') throw error
+    throw failure()
+  }
+}
+
+export async function removeCredential({ stateDir, tool, dryRun = false }) {
+  const paths = locations(stateDir, tool)
+  try {
+    const present = await inspect(paths)
+    if (dryRun || !present) return { changed: false, dryRun }
+    return await withLock(paths, async () => {
+      const current = await inspect(paths)
+      if (!current) return { changed: false, dryRun: false }
+      // Fixed validated path only; malformed JSON can be safely removed too.
+      await fs.unlink(paths.file)
+      return { changed: true, dryRun: false }
+    })
+  } catch (error) {
+    if (error.message === 'Another setup may be active. Review the helper lock before retrying.') throw error
+    throw failure()
+  }
+}

package/src/ui.mjs

@@ -1,5 +1,6 @@
 import { createInterface } from 'node:readline/promises'
 import { fetchModels } from './catalog.mjs'
+import { openConsole } from './browser.mjs'
 import * as claudeAdapter from './adapters/claude.mjs'
 
 const palette = { heading: 36, info: 34, success: 32, warning: 33, error: 31, muted: 90, selected: 35 }
@@ -31,12 +32,19 @@ export async function select({ message, choices, input = process.stdin, output =
   const wasPaused = typeof input.isPaused === 'function' && input.isPaused()
   let index = 0, rendered = false, buffer = '', timer, settled = false
   const pageSize = Math.min(choices.length, 8, Math.max(1, (output.rows || 24) - 4))
-  const lines = pageSize + 2
-  // Conservative cell budget also prevents wrapping wide Unicode labels.
-  const fit = text => {
-    const chars = Array.from(clean(text))
-    const limit = Math.max(8, Math.floor((output.columns || 120) / 2) - 1)
-    return chars.length > limit ? chars.slice(0, limit - 1).join('') + '…' : chars.join('')
+  let renderedLines = 0
+  const wrap = text => {
+    const width = Math.max(4, (output.columns || 120) - 1)
+    const lines = ['']
+    let cells = 0
+    for (const { segment } of new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(clean(text))) {
+      const cp = segment.codePointAt(0)
+      const size = /^\p{Mark}+$/u.test(segment) ? 0 : /\p{Extended_Pictographic}/u.test(segment) || cp >= 0x1100 && (cp <= 0x115f || cp >= 0x2e80 && cp <= 0xa4cf || cp >= 0xac00 && cp <= 0xd7a3 || cp >= 0xf900 && cp <= 0xfaff || cp >= 0xfe10 && cp <= 0xfe6f || cp >= 0xff01 && cp <= 0xff60 || cp >= 0x20000) ? 2 : 1
+      if (cells + size > width) { lines.push(''); cells = 0 }
+      lines[lines.length - 1] += segment
+      cells += size
+    }
+    return lines
   }
   return new Promise((resolve, reject) => {
     const cleanup = () => {
@@ -59,16 +67,24 @@ export async function select({ message, choices, input = process.stdin, output =
     }
     function onFailure() { finish(uiError()) }
     function draw() {
-      if (rendered) output.write(`\u001b[${lines}A\r`)
-      output.write('\u001b[2K' + colorize(fit(message), 'heading', { output }) + '\n')
+      if (rendered) output.write(`\u001b[${renderedLines}A\r\u001b[J`)
+      const rows = wrap(message).map(text => ({ text, kind: 'heading' }))
       const start = Math.min(Math.max(0, index - pageSize + 1), choices.length - pageSize)
-      choices.slice(start, start + pageSize).forEach((choice, offset) => {
-        const i = start + offset
-        const text = `${i === index ? '❯' : ' '} ${choice.label}${choice.description ? ` — ${choice.description}` : ''}`
-        output.write('\u001b[2K' + colorize(fit(text), i === index ? 'selected' : 'info', { output }) + '\n')
-      })
       const hint = language === 'vi' ? '↑/↓ chọn · Enter xác nhận · Esc hủy' : '↑/↓ select · Enter accept · Esc cancel'
-      output.write('\u001b[2K' + colorize(fit(`${index + 1}/${choices.length} · ${hint}`), 'muted', { output }) + '\n')
+      const footer = wrap(`${index + 1}/${choices.length} · ${hint}`)
+      let candidates = choices.slice(start, start + pageSize).map((choice, offset) => ({
+        i: start + offset,
+        lines: wrap(`${start + offset === index ? '❯' : ' '} ${choice.label}${choice.description ? ` — ${choice.description}` : ''}`)
+      }))
+      const budget = Math.max(1, (output.rows || 24) - rows.length - footer.length - 1)
+      while (candidates.length > 1 && candidates.reduce((n, c) => n + c.lines.length, 0) > budget) {
+        if (candidates[0].i < index) candidates.shift()
+        else candidates.pop()
+      }
+      for (const candidate of candidates) for (const text of candidate.lines) rows.push({ text, kind: candidate.i === index ? 'selected' : 'info' })
+      for (const text of footer) rows.push({ text, kind: 'muted' })
+      for (const { text, kind } of rows) output.write('\u001b[2K' + colorize(text, kind, { output }) + '\n')
+      renderedLines = rows.length
       rendered = true
     }
     function onData(chunk) {
@@ -114,6 +130,81 @@ export async function select({ message, choices, input = process.stdin, output =
   })
 }
 
+/** Masked single-token entry. Bracketed paste is buffered until its end marker. */
+export async function readApiKey({ input = process.stdin, output = process.stdout, language = 'en' } = {}) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') throw uiError()
+  const wasRaw = Boolean(input.isRaw), wasPaused = input.isPaused?.()
+  let value = '', buffer = '', pasting = false, pasted = '', settled = false, timer
+  return new Promise((resolve, reject) => {
+    const finish = (error, result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      for (const event of ['data', 'error', 'end', 'close']) input.off(event, event === 'data' ? onData : onFailure)
+      output.off('error', onFailure)
+      try { input.setRawMode(wasRaw) } catch {}
+      try { if (wasPaused) input.pause() } catch {}
+      try { output.write('\u001b[?2004l\n') } catch {}
+      value = ''; pasted = ''; buffer = ''
+      if (error) reject(error)
+      else resolve(result)
+    }
+    const invalid = () => {
+      const error = new Error(language === 'vi' ? 'Khóa API phải là một chuỗi duy nhất, không có khoảng trắng hoặc ký tự điều khiển.' : 'API key must be a single token without whitespace or control characters.')
+      error.code = 'UI_INVALID_KEY'
+      finish(error)
+    }
+    const valid = text => /^[\x21-\x7e]+$/.test(text) && text.length <= 8192
+    function onFailure() { finish(uiError()) }
+    function onData(chunk) {
+      try {
+        clearTimeout(timer)
+        buffer += chunk.toString('utf8')
+        while (buffer && !settled) {
+          if (pasting) {
+            const end = buffer.indexOf('\u001b[201~')
+            if (end < 0) {
+              // Retain a possible split terminator; no pasted byte is interpreted as a key.
+              if (buffer.length > 6) { pasted += buffer.slice(0, -6); buffer = buffer.slice(-6) }
+              if (pasted.length > 8192) return invalid()
+              return
+            }
+            pasted += buffer.slice(0, end)
+            buffer = buffer.slice(end + 6)
+            if (!valid(pasted) || value.length + pasted.length > 8192) return invalid()
+            value += pasted; output.write('*'.repeat(pasted.length)); pasted = ''; pasting = false
+            continue
+          }
+          if (buffer.startsWith('\u001b[200~')) { buffer = buffer.slice(6); pasting = true; continue }
+          if ('\u001b[200~'.startsWith(buffer) && buffer[0] === '\u001b') {
+            timer = setTimeout(() => finish(uiError(true)), 35); return
+          }
+          const char = buffer[0]; buffer = buffer.slice(1)
+          if (char === '\u0003' || char === '\u001b') return finish(uiError(true))
+          if (char === '\r' || char === '\n') {
+            if (!valid(value) || buffer.length) return invalid()
+            return finish(null, value)
+          }
+          if (char === '\x7f' || char === '\b') {
+            if (value) { value = value.slice(0, -1); output.write('\b \b') }
+            continue
+          }
+          if (!valid(char) || value.length >= 8192) return invalid()
+          value += char; output.write('*')
+        }
+      } catch { finish(uiError()) }
+    }
+    try {
+      input.on('data', onData)
+      for (const event of ['error', 'end', 'close']) input.on(event, onFailure)
+      output.on('error', onFailure)
+      input.setRawMode(true)
+      output.write('\u001b[?2004h' + (language === 'vi' ? 'Dán khóa API (ẩn): ' : 'Paste API key (masked): '))
+      input.resume()
+    } catch { finish(uiError()) }
+  })
+}
+
 async function modelQuestion(input, output, language = 'en') {
   const controller = new AbortController()
   const terminal = createInterface({ input, output, terminal: true })
@@ -139,7 +230,7 @@ async function modelQuestion(input, output, language = 'en') {
 }
 
 /** Gather CLI arguments only. State and tool execution belong to dispatch. */
-export async function wizard({ dispatch, input = process.stdin, output = process.stdout, loadModels = fetchModels }) {
+export async function wizard({ dispatch, input = process.stdin, output = process.stdout, loadModels = fetchModels, getKeyStatus = async () => ({ available: false }), openConsole: openBrowser = openConsole }) {
   if (typeof dispatch !== 'function') throw new Error('Wizard requires a CLI dispatcher.')
   let language = 'en'
   const t = (en, vi) => language === 'vi' ? vi : en
@@ -152,7 +243,7 @@ export async function wizard({ dispatch, input = process.stdin, output = process
     language = await choose('Language / Ngôn ngữ', [
       { label: 'English', value: 'en' }, { label: 'Tiếng Việt', value: 'vi' }
     ])
-    const action = await choose(t('1endpoint coding-helper · isolated configuration; no API key is requested or saved', '1endpoint coding-helper · cấu hình riêng; không yêu cầu hoặc lưu khóa API'), [
+    const action = await choose(t('1endpoint coding-helper · isolated configuration', '1endpoint coding-helper · cấu hình riêng'), [
       { label: t('Setup', 'Cấu hình'), value: 'setup' },
       { label: t('Reconfigure', 'Cấu hình lại'), value: 'reconfigure' },
       { label: t('Remove', 'Xóa cấu hình'), value: 'remove' },
@@ -165,6 +256,44 @@ export async function wizard({ dispatch, input = process.stdin, output = process
       { label: 'DSH', value: 'dsh' }, { label: 'Claude Code', value: 'claude' }
     ])
     const argv = [action, '--tool', tool]
+    const context = { language }
+    if (['setup', 'reconfigure', 'run'].includes(action)) {
+      let available = false
+      try { available = (await getKeyStatus({ tool }))?.available === true } catch {}
+      if (action !== 'run' || !available) {
+        while (true) {
+          const keyAction = await choose(t('API key', 'Khóa API'), [
+            { label: t('Paste key (masked)', 'Dán khóa (ẩn)'), value: 'paste' },
+            { label: t('Open Console create API key', 'Mở Console tạo khóa API'), value: 'open', description: t('Enter opens the API keys page', 'Enter mở trang khóa API') },
+            ...(available ? [{ label: t('Use existing saved/environment key', 'Dùng khóa đã lưu hoặc biến môi trường'), value: 'existing' }] : []),
+            { label: t('Skip; use environment key later', 'Bỏ qua; dùng khóa môi trường sau'), value: 'skip' },
+            { label: t('Cancel', 'Hủy'), value: 'cancel' }
+          ])
+          if (keyAction === 'cancel') return
+          if (keyAction === 'existing' || keyAction === 'skip') break
+          if (keyAction === 'open') {
+            try { await openBrowser({ language }) }
+            catch { output.write(t('Could not open Console. Select Open Console to retry, or paste a key.\n', 'Không mở được Console. Chọn Mở Console để thử lại hoặc dán khóa.\n')) }
+            continue
+          }
+          let key
+          try { key = await readApiKey({ input, output, language }) }
+          catch (error) {
+            if (error.code !== 'UI_INVALID_KEY') throw error
+            output.write(error.message + '\n'); continue
+          }
+          output.write(t('Local keys are plaintext, mode 0600: accessible to your user account, not encrypted.\n', 'Khóa cục bộ ở dạng văn bản thuần, quyền 0600: tài khoản của bạn có thể đọc, không được mã hóa.\n'))
+          const storage = await choose(t('Key storage', 'Lưu khóa'), [
+            { label: t('Save locally', 'Lưu cục bộ'), value: 'save' },
+            { label: t('This run only', 'Chỉ lần chạy này'), value: 'session' },
+            { label: t('Cancel', 'Hủy'), value: 'cancel' }
+          ])
+          if (storage === 'cancel') return
+          context.apiKey = key; context.saveKey = storage === 'save'
+          break
+        }
+      }
+    }
     if (action === 'setup' || action === 'reconfigure') {
       let models, manual = false
       while (!models && !manual) {
@@ -192,7 +321,7 @@ export async function wizard({ dispatch, input = process.stdin, output = process
         const optionalRoles = claudeAdapter.CLAUDE_OPTIONAL_ROLES || []
         let activeRoles = [...roles]
         if (optionalRoles.length) {
-          const extra = await choose(t('Claude tier support depends on your installed version; no version is guessed.', 'Các cấp Claude tùy thuộc phiên bản đã cài; không tự suy đoán phiên bản.'), [
+          const extra = await choose(t('Select the tiers supported by your Claude Code version.', 'Chọn các cấp được phiên bản Claude Code của bạn hỗ trợ.'), [
             { label: t('Standard Haiku / Sonnet / Opus', 'Các cấp chuẩn Haiku / Sonnet / Opus'), value: false },
             { label: t('Include optional tiers', 'Thêm cấp tùy chọn'), value: true, description: t('Only if your installed Claude supports ', 'Chỉ chọn nếu Claude đã cài hỗ trợ ') + optionalRoles.map(role => role.label).join(', ') }
           ])
@@ -224,16 +353,28 @@ export async function wizard({ dispatch, input = process.stdin, output = process
       ])
       if (mode === 'cancel') return
       if (mode === 'force') output.write(colorize(t('WARNING: Force recovery deletes fixed helper configuration paths, including modified contents, without backup.\n', 'CẢNH BÁO: xóa cưỡng chế xóa các đường dẫn cấu hình riêng cố định, kể cả nội dung đã sửa, không sao lưu.\n'), 'warning', { output }))
+      context.removeKey = await choose(t('Saved key for this tool', 'Khóa đã lưu cho công cụ này'), [
+        { label: t('Keep saved key', 'Giữ khóa đã lưu'), value: false },
+        { label: t('Remove saved key too', 'Xóa cả khóa đã lưu'), value: true }
+      ])
       if (!await confirm(mode === 'force' ? t('Confirm forced recovery deletion without backup?', 'Xác nhận xóa cưỡng chế không sao lưu?') : t('Confirm removal of helper-owned configuration?', 'Xác nhận xóa cấu hình riêng?'))) return
       argv.push('--yes')
       if (mode === 'force') argv.push('--force')
     }
-    const result = await dispatch(argv, { language })
+    const result = await dispatch(argv, context)
     if (action === 'setup' || action === 'reconfigure') {
       const warning = t(`Restart your ${tool === 'dsh' ? 'DSH' : 'Claude Code'} session to apply. Existing sessions do not update automatically. Start a new session through coding-helper.\n`, `Khởi động lại phiên ${tool === 'dsh' ? 'DSH' : 'Claude Code'} để áp dụng. Phiên hiện có không tự cập nhật. Mở phiên mới thông qua coding-helper.\n`)
       const colored = colorize(warning, 'warning', { output })
       output.write(colored === warning ? warning : `\u001b[1m${colored}\u001b[0m`)
     }
+    if ((action === 'setup' || action === 'reconfigure') && context.apiKey && !context.saveKey) {
+      output.write(t('This key is only available now. Paste it again when reopening coding-helper.\n', 'Khóa chỉ có trong lần chạy này. Dán lại khi mở coding-helper lần sau.\n'))
+      const launch = await choose(t('Start a new session?', 'Mở phiên mới?'), [
+        { label: t('Finish', 'Hoàn tất'), value: false },
+        { label: t('Start new session now (may incur charges)', 'Mở phiên mới ngay (có thể phát sinh phí)'), value: true }
+      ])
+      if (launch) return dispatch(['run', '--tool', tool], { language, apiKey: context.apiKey, saveKey: false })
+    }
     return result
   } catch (error) {
     if (error.code === 'UI_CANCELLED') {