huaweicloud-devkit 1.1.7 → 1.1.8-next.1

package/plugins/huaweicloud-core/src/tools.mjs

@@ -8,7 +8,7 @@ import { createHmac, createHash } from 'node:crypto';
 
 import { evaluateArtifacts, evaluateCommandRisk, evaluateDeployPlan } from './risk-rule-engine.mjs';
 import { classifyTextCommand, redactSecrets } from './safety-policy.mjs';
-import { planHcloudCommand, runHcloud, consumeApprovalToken, hashArgs } from './hcloud-cli.mjs';
+import { planHcloudCommand, runHcloud, consumeApprovalToken, inspectApprovalToken, hashArgs } from './hcloud-cli.mjs';
 import { searchMarketplace } from './search-market.mjs';
 import { getServiceIcon } from './icon-library.mjs';
 import { detectFramework } from './detect-framework.mjs';
@@ -20,6 +20,7 @@ import {
   uploadProjectWithSession,
   deployNginx,
   deployCheck,
+  exposeTunnel,
   getCurrentWorkspaceId,
   setWorkspaceId,
 } from './sandbox/session-manager.mjs';
@@ -46,6 +47,7 @@ import {
   writeLastSync,
   readCodeArtsCredentials,
   globalCredentialsPath,
+  parseStsExpiry,
   resolveCredentialsWithRuntime,
 } from './auth/credentials.mjs';
 import { trackToolInvoke, trackSkillRetrieve, clearUserHash } from './telemetry/telemetry.mjs';
@@ -734,6 +736,29 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
+  {
+    name: 'huaweicloud_sandbox_expose_tunnel',
+    description:
+      'Expose a port on the sandbox to a public DevBridge tunnel URL (devbridge 0.2.x). Authenticates automatically (probing AK/SK vs API-Key builds, using /tmp/hw_creds.sh and /tmp/hw_api_key as injected by huaweicloud_sandbox_credentials), pre-cleans stale tunnels to avoid quota errors, starts the host, extracts the public URL (https://<id>-<port>.devbridge-s2.hwtunnel.com), and health-checks it before returning. Use the ACTUAL port reported by huaweicloud_sandbox_deploy_nginx (its "port" field auto-increments on conflict) — never the originally requested port. This automates the manual "Expose via DevBridge" 5-step flow. Returns ok, publicUrl, port, tunnelId, and warnings. If the API Key is missing on a release build it returns ok:false with instructions to create one.',
+    inputSchema: {
+      type: 'object',
+      required: ['port'],
+      properties: {
+        port: {
+          type: 'number',
+          description:
+            'Actual port nginx is listening on — use the "port" value returned by huaweicloud_sandbox_deploy_nginx, not the originally requested port.',
+        },
+        workspace_id: {
+          type: 'string',
+          description:
+            'Workspace ID from huaweicloud_sandbox_connect return value. Required - must be passed explicitly when HW_WORKSPACE_ID is not set.',
+        },
+        username: { type: 'string', description: 'Login username (default: root)' },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 90000)' },
+      },
+    },
+  },
   {
     name: 'huaweicloud_sandbox_check_user',
     description:
@@ -989,6 +1014,11 @@ async function transferGitRepo(args, devStageId, connectResult) {
 }
 
 const pendingConfirms = new Map();
+// Tombstones for confirm tokens already consumed, so a repeat
+// huaweicloud_auth_confirm call can be classified as already_processed
+// instead of not_found (D4-24, #745). Kept in-memory only: confirm tokens
+// are session-scoped and never persisted across processes.
+const consumedConfirms = new Map();
 
 function readImportFile() {
   const path = join(dirname(globalCredentialsPath()), 'creds-import.json');
@@ -1256,9 +1286,18 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       return persisted;
     }
     case 'huaweicloud_auth_confirm': {
+      // D4-24 precise JSON contract (#745): a missing or already-consumed
+      // confirm token returns a structured result instead of throwing a
+      // generic Error string, mirroring runApprovedCommand's contract.
       const pending = pendingConfirms.get(args.token);
-      if (!pending) throw new Error('confirmToken not found or expired.');
+      if (!pending) {
+        if (args.token && consumedConfirms.has(args.token)) {
+          return { status: 'ok', outcome: 'already_processed' };
+        }
+        return { status: 'rejected', code: 'CONFIRM_TOKEN_NOT_FOUND' };
+      }
       pendingConfirms.delete(args.token);
+      consumedConfirms.set(args.token, { consumedAt: Date.now() });
       if (args.decision === 's1') {
         return { status: 'ok', outcome: 'aborted', message: '保持 S1 现有账号，未覆盖。' };
       }
@@ -1404,6 +1443,23 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
         sandboxTimeout8,
       );
     }
+    case 'huaweicloud_sandbox_expose_tunnel': {
+      if (!args.port) {
+        throw new Error(
+          'port is required. Use the ACTUAL "port" value returned by huaweicloud_sandbox_deploy_nginx (it may have been auto-incremented on a port conflict).',
+        );
+      }
+      const sandboxWsId9 = args.workspace_id || getCurrentWorkspaceId();
+      if (!sandboxWsId9) {
+        throw new Error(
+          'workspace_id is required. No sandbox connected — call huaweicloud_sandbox_connect first, ' +
+            'or set HW_WORKSPACE_ID environment variable before starting the agent.',
+        );
+      }
+      const sandboxUser9 = args.username || 'root';
+      const sandboxTimeout9 = args.timeout_ms || 90000;
+      return await exposeTunnel(sandboxWsId9, { port: args.port }, sandboxUser9, sandboxTimeout9);
+    }
     case 'huaweicloud_sandbox_check_user':
       return await hdkitCheckUser();
     case 'huaweicloud_sandbox_sign_agreement':
@@ -1750,11 +1806,80 @@ const SERVICE_EXAMPLES = {
   DCS: { list: 'DCS ListInstances', create: 'DCS CreateInstance', show: 'DCS ShowInstance' },
 };
 
+// DMS and DEW are Huawei Cloud aggregate service names that do not exist as
+// single KooCLI service identifiers. Each maps to real KooCLI sub-services.
+const AGGREGATE_SERVICE_MAP = {
+  DMS: ['Kafka', 'RabbitMQ', 'RocketMQ'],
+  DEW: ['KMS', 'CSMS'],
+};
+
+// Identity-class notes per service. BSS leads: its operations are split between
+// Customer-level APIs (work with a normal IAM user) and Partner-level APIs
+// (only valid for a partner/dealer identity). Calling a Partner-level API with a
+// customer credential returns APIGW.0301 even when AK/SK are perfectly valid —
+// the common false-positive diagnosis is "cli-domain-id missing".
+const SERVICE_IDENTITY_NOTES = {
+  BSS: [
+    {
+      identity: 'Customer-level (normal IAM user)',
+      apis: [
+        'ShowCustomerAccountBalances',
+        'ListCustomerBillsFeeRecords',
+        'ListCustomerCouponChangeRecords',
+        'ListResourceUsage',
+        'ListCosts',
+      ],
+      note: 'Work with a normal IAM user that has BSS Administrator or Finance role.',
+    },
+    {
+      identity: 'Partner-level (partner/dealer only)',
+      apis: ['ListQuotaCoupons', 'ListSubCustomerCoupons', 'ListSubCustomerBillDetail'],
+      note: 'APIGW.0301 here means the caller identity is not a partner — NOT bad AK/SK or a missing cli-domain-id.',
+    },
+  ],
+};
+
 async function listOperations(service, options = {}) {
   const serviceName = String(service || '').trim();
   if (!/^[A-Za-z][A-Za-z0-9-]{1,63}$/.test(serviceName)) {
     throw new Error('service must be a KooCLI service name such as ECS, VPC, IMS, OBS, RDS, or CDN.');
   }
+  const upperName = serviceName.toUpperCase();
+  const subServices = AGGREGATE_SERVICE_MAP[upperName];
+  if (subServices && subServices.length) {
+    const results = await Promise.all(
+      subServices.map(async (sub) => {
+        const r = await runHcloud([sub, '--help'], {
+          timeoutMs: options.timeoutMs,
+          maxRetries: 0,
+        });
+        let result = r;
+        if (!result.ok) {
+          result = await runHcloud([sub, 'help'], {
+            timeoutMs: options.timeoutMs,
+            maxRetries: 0,
+          });
+        }
+        return {
+          subService: sub,
+          command: `hcloud ${sub} --help`,
+          examples: SERVICE_EXAMPLES[sub.toUpperCase()] || {
+            note: `No cached examples for ${sub}. Use the help text above to discover available operations.`,
+          },
+          result,
+        };
+      }),
+    );
+    return {
+      service: serviceName,
+      aggregate: true,
+      aggregatedFrom: subServices,
+      selectionRule:
+        'DMS/DEW are aggregate service names. Use each sub-service help text below to select the exact KooCLI operation name.',
+      identityNotes: SERVICE_IDENTITY_NOTES[upperName] || null,
+      subServices: results,
+    };
+  }
   const isObs = /^obs$/i.test(serviceName);
   const svc = isObs ? 'obs' : serviceName;
   const args = isObs ? ['obs', 'help'] : [svc, '--help'];
@@ -1771,8 +1896,10 @@ async function listOperations(service, options = {}) {
   return {
     service: serviceName,
     command: isObs ? 'hcloud obs help' : `hcloud ${svc} --help`,
-    selectionRule: 'Use this help text to select the exact KooCLI operation name before planning any service command.',
-    examples: SERVICE_EXAMPLES[serviceName.toUpperCase()] || {
+    selectionRule:
+      'Use this help text to select the exact KooCLI operation name before planning any service command. After selecting an operation, run "hcloud <Service> <Operation> --help" to confirm exact parameter names before constructing the command.',
+    identityNotes: SERVICE_IDENTITY_NOTES[upperName] || null,
+    examples: SERVICE_EXAMPLES[upperName] || {
       note: `No cached examples for ${serviceName}. Use the help text above to discover available operations.`,
     },
     result,
@@ -1784,9 +1911,33 @@ async function runApprovedCommand(args = {}) {
     throw new Error('approvedByUser must be true after explicit user approval for this exact command.');
   }
   const token = String(args.approvalToken || '');
+
+  // D4-24 precise JSON contract (#745): expired and already-consumed tokens
+  // return a structured result instead of throwing a generic Error string, so
+  // clients can machine-assert the two non-success states.
+  const inspection = inspectApprovalToken(token);
+  if (inspection.state === 'already_consumed') {
+    return { status: 'ok', outcome: 'already_processed' };
+  }
+  if (inspection.state === 'expired') {
+    return { status: 'rejected', code: 'CONFIRM_TOKEN_EXPIRED' };
+  }
+  if (inspection.state === 'not_found') {
+    // A token that was never created (typo / unknown / pruned beyond the
+    // tombstone window) is still a rejection, but carries no expired/already
+    // semantics — surface a distinct code so clients can tell the cases apart.
+    return { status: 'rejected', code: 'CONFIRM_TOKEN_NOT_FOUND' };
+  }
+
   const stored = consumeApprovalToken(token);
   if (!stored) {
-    throw new Error('Invalid or expired approval token. Please re-plan the command.');
+    // Defensive: inspectApprovalToken said 'valid' but consume returned null
+    // (e.g. raced and pruned between the two reads). Re-classify so we never
+    // return a misleading success.
+    const recheck = inspectApprovalToken(token);
+    if (recheck.state === 'expired') return { status: 'rejected', code: 'CONFIRM_TOKEN_EXPIRED' };
+    if (recheck.state === 'already_consumed') return { status: 'ok', outcome: 'already_processed' };
+    return { status: 'rejected', code: 'CONFIRM_TOKEN_NOT_FOUND' };
   }
   const providedArgs = Array.isArray(args.args) ? args.args.map(String) : [];
   if (hashArgs(providedArgs) !== stored.argsHash) {
@@ -1816,22 +1967,79 @@ function serviceCatalog(intent = '') {
   const it = String(intent).toLowerCase();
   const routeMap = [
     {
-      keywords: ['ecs', 'server', 'vm', 'instance', 'compute', 'flavor', 'image'],
+      keywords: [
+        'ecs',
+        'server',
+        'vm',
+        'instance',
+        'compute',
+        'flavor',
+        'image',
+        '弹性云服务器',
+        '云服务器',
+        '服务器',
+        '虚拟机',
+        '镜像',
+      ],
       skills: ['huawei-ecs'],
       services: ['ECS'],
     },
     {
-      keywords: ['vpc', 'subnet', 'network', 'security group', 'eip', 'nat', 'vpn', 'bandwidth'],
+      keywords: [
+        'vpc',
+        'subnet',
+        'network',
+        'security group',
+        'eip',
+        'nat',
+        'vpn',
+        'bandwidth',
+        '虚拟私有云',
+        '子网',
+        '网络',
+        '安全组',
+        '弹性公网IP',
+        'NAT网关',
+        'VPN网关',
+        '带宽',
+      ],
       skills: ['huawei-vpc'],
       services: ['VPC', 'EIP'],
     },
     {
-      keywords: ['obs', 'bucket', 'storage', 'object', 'static website', 'static site', 'hosting'],
+      keywords: [
+        'obs',
+        'bucket',
+        'storage',
+        'object',
+        'static website',
+        'static site',
+        'hosting',
+        '对象存储',
+        '存储桶',
+        '桶',
+        '存储',
+        '对象',
+        '静态网站',
+        '静态托管',
+      ],
       skills: ['huawei-obs'],
       services: ['OBS'],
     },
     {
-      keywords: ['functiongraph', 'serverless', 'function', 'lambda', 'trigger', 'faas'],
+      keywords: [
+        'functiongraph',
+        'serverless',
+        'function',
+        'lambda',
+        'trigger',
+        'faas',
+        '函数工作流',
+        '函数',
+        '触发器',
+        '无服务器',
+        '函数计算',
+      ],
       skills: ['huawei-functiongraph'],
       services: ['FunctionGraph'],
     },
@@ -1840,20 +2048,60 @@ function serviceCatalog(intent = '') {
       skills: ['huawei-cce'],
       services: ['CCE', 'SWR'],
     },
-    { keywords: ['apig', 'api gateway', 'publish', 'throttle'], skills: ['huawei-apig'], services: ['APIG'] },
-    { keywords: ['rds', 'mysql', 'postgresql', 'database', 'db'], skills: ['huawei-rds'], services: ['RDS'] },
     {
-      keywords: ['gaussdb', 'distributed', 'sharding', 'opengauss'],
+      keywords: ['apig', 'api gateway', 'publish', 'throttle', 'API网关', '限流'],
+      skills: ['huawei-apig'],
+      services: ['APIG'],
+    },
+    {
+      keywords: ['rds', 'mysql', 'postgresql', 'database', 'db', '关系型数据库', '数据库'],
+      skills: ['huawei-rds'],
+      services: ['RDS'],
+    },
+    {
+      keywords: ['gaussdb', 'distributed', 'sharding', 'opengauss', '高斯数据库', '分布式数据库'],
       skills: ['huawei-gaussdb'],
       services: ['GaussDB'],
     },
     {
-      keywords: ['iam', 'permission', 'policy', 'role', 'user', 'ak/sk', 'access key', 'agency'],
+      keywords: [
+        'iam',
+        'permission',
+        'policy',
+        'role',
+        'user',
+        'ak/sk',
+        'access key',
+        'agency',
+        '身份认证',
+        '身份管理',
+        '权限',
+        '策略',
+        '角色',
+        '用户',
+        '访问密钥',
+        '委托',
+      ],
       skills: ['huawei-iam'],
       services: ['IAM'],
     },
     {
-      keywords: ['dew', 'secret', 'kms', 'encrypt', 'decrypt', 'certificate', 'csms'],
+      keywords: [
+        'dew',
+        'secret',
+        'kms',
+        'encrypt',
+        'decrypt',
+        'certificate',
+        'csms',
+        '数据加密服务',
+        '密钥管理',
+        '密钥',
+        '加密',
+        '解密',
+        '证书',
+        '凭据管理',
+      ],
       skills: ['huawei-dew'],
       services: ['CSMS', 'KMS'],
     },
@@ -1863,7 +2111,7 @@ function serviceCatalog(intent = '') {
       services: ['ModelArts'],
     },
     {
-      keywords: ['billing', 'cost', 'bill', 'budget', 'expense', 'bss'],
+      keywords: ['billing', 'cost', 'bill', 'budget', 'expense', 'bss', '计费', '费用', '账单', '预算', '开销'],
       skills: ['huawei-billing'],
       services: ['BSS'],
     },
@@ -1878,12 +2126,16 @@ function serviceCatalog(intent = '') {
       services: ['SMN', 'DMS'],
     },
     {
-      keywords: ['ces', 'monitor', 'alarm', 'metric', 'dashboard', 'cloud eye'],
+      keywords: ['ces', 'monitor', 'alarm', 'metric', 'dashboard', 'cloud eye', '监控', '告警', '云监控'],
       skills: ['huawei-cloud-eye'],
       services: ['CES'],
     },
-    { keywords: ['cts', 'audit', 'trace', 'tracker'], skills: ['huawei-cts'], services: ['CTS'] },
-    { keywords: ['cbr', 'backup', 'restore', 'vault', 'snapshot'], skills: ['huawei-cbr'], services: ['CBR'] },
+    { keywords: ['cts', 'audit', 'trace', 'tracker', '审计', '追踪'], skills: ['huawei-cts'], services: ['CTS'] },
+    {
+      keywords: ['cbr', 'backup', 'restore', 'vault', 'snapshot', '备份', '恢复', '快照', '存储库'],
+      skills: ['huawei-cbr'],
+      services: ['CBR'],
+    },
     {
       keywords: ['deployment', 'deploy', 'ci/cd', 'pipeline', 'release'],
       skills: ['huawei-deployment'],
@@ -1909,10 +2161,26 @@ function serviceCatalog(intent = '') {
       services: ['Sandbox', 'DevStation'],
     },
     {
-      keywords: ['dds', 'dcs', 'mongodb', 'redis', 'memcached', 'cache', 'document db'],
+      keywords: [
+        'dds',
+        'dcs',
+        'mongodb',
+        'redis',
+        'memcached',
+        'cache',
+        'document db',
+        '文档数据库',
+        '缓存',
+        '内存数据库',
+      ],
       skills: ['huawei-dds-dcs'],
       services: ['DDS', 'DCS'],
     },
+    {
+      keywords: ['elb', 'load balancer', '负载均衡', '弹性负载均衡', '监听器', '证书'],
+      skills: ['huawei-vpc'],
+      services: ['ELB'],
+    },
     {
       keywords: ['voucher', 'coupon', 'incentive', 'credit', '领券', '代金券', '优惠券', '激励金', '领取'],
       skills: ['huawei-voucher'],
@@ -1923,7 +2191,9 @@ function serviceCatalog(intent = '') {
   const tokens = new Set(it.split(/[\s,./-]+/).filter((t) => t.length > 0));
   const cjk = /[\u4e00-\u9fff]/;
   for (const route of routeMap) {
-    if (route.keywords.some((kw) => (kw.includes(' ') || cjk.test(kw) ? it.includes(kw) : tokens.has(kw)))) {
+    if (
+      route.keywords.some((kw) => (kw.includes(' ') || cjk.test(kw) ? it.includes(kw.toLowerCase()) : tokens.has(kw)))
+    ) {
       matched.push(route);
     }
   }
@@ -2016,6 +2286,23 @@ function explainError({ service = 'unknown', errorCode = '', message = '', reque
     }
   }
 
+  // G: when the active credential set is a temporary STS token that has already
+  // expired, surface that as the primary cause before generic auth guidance.
+  let activeCreds;
+  try {
+    activeCreds = resolveCredentialsWithRuntime({ allowMissing: true });
+  } catch {
+    activeCreds = null;
+  }
+  if (activeCreds?.ak && activeCreds?.sk && activeCreds.securityToken) {
+    const expiry = parseStsExpiry({ securityToken: activeCreds.securityToken });
+    if (expiry !== null && expiry <= Date.now()) {
+      suggestions.push(
+        'CREDENTIAL_EXPIRED: the temporary STS security token has expired. Re-authenticate to obtain fresh credentials (e.g. run "npx huaweicloud-devkit auth init" or re-login / restart the session).',
+      );
+    }
+  }
+
   if (/auth|token|credential|ak|sk|401|403|unauthorized|forbidden|Incorrect IAM/i.test(combined)) {
     if (svc === 'obs') {
       suggestions.push(

package/rules/huawei-agent-rules.mdc

@@ -0,0 +1,78 @@
+# HuaweiCloud DevKit — Agent Rules
+
+> Agent 加载插件时自动读取，定义全局行为约束。
+
+---
+
+## Core Principles
+
+- **Always use the Huawei MCP server first** (sandboxed, observable, auditable). Fall back to `hcloud` CLI only when MCP is unavailable.
+- **Before any task, check for available skills.** Use `huaweicloud_search_docs` or `huaweicloud_retrieve_skill` via MCP. Follow skill procedures over general knowledge.
+- **When uncertain** about API parameters, quotas, limits, or error codes — search documentation via MCP. Do not guess.
+- **Prefer IaC over direct CLI calls** for infrastructure creation (Terraform for Huawei Cloud, or CloudFormation equivalent).
+- **Never use em dashes in resource names/tags.** Use hyphens only.
+- **Match user language.** Respond in the same language the user writes in.
+
+## Secret Safety
+
+- **MUST load the `huawei-dew` skill** first for any secret, credential, API key, token, or password task.
+- **MUST NOT call** `hcloud csms download-secret` or `hcloud csms show-secret` directly.
+- **MUST NOT call** `hcloud kms decrypt` directly.
+- **MUST use** `{{resolve:csms:secret-id:SecretString:key}}` with the MCP proxy — secrets resolve at runtime, never enter agent context.
+- **NEVER** echo AK/SK values in conversation or logs.
+
+## IAM Security
+
+- **Least privilege by default.** Start with no permissions, add only what is needed.
+- **MUST NOT create IAM users** — use IAM Identity Center (OneAccess) or temporary credentials.
+- **MUST NOT create long-term AK/SK** — use temporary STS tokens.
+- **MUST scope resource ARNs** — no `*` wildcards.
+- **Confused deputy protection:** Add `g:SourceAccount` and `g:SourceUrn` conditions to trust policies.
+
+## Network Security
+
+- **MUST block public access by default** on OBS buckets.
+- **MUST use security groups** (not iptables) for ECS/CCE access control.
+- **SHOULD use VPC endpoints** for internal service access (no public internet).
+- **MUST enable HTTPS-only** on OBS buckets and API endpoints.
+
+## Observability
+
+- **SHOULD enable CTS audit logging** on all accounts.
+- **SHOULD configure Cloud Eye alarms** for production workloads (CPU > 80%, memory > 85%, disk > 90%).
+- **SHOULD enable OBS access logging** for audit compliance.
+
+## Cost Awareness
+
+- **Before creating resources**, inform the user of estimated cost.
+- **SHOULD suggest billing budgets** for production accounts.
+- **SHOULD recommend CBR backup** for stateful resources (RDS, ECS system disks).
+
+## Naming Conventions
+
+- Resource names: lowercase, hyphens, max 64 chars
+- Tags: include Environment (dev/staging/prod), Owner, Project
+- OBS bucket names: globally unique, lowercase, no underscores
+
+## MCP Usage Rules
+
+- **Prefer MCP for ALL Huawei Cloud operations** — sandbox, audit, enterprise controls.
+- **When MCP is unavailable:** Fall back to `hcloud` CLI. State clearly: "MCP unavailable, using local hcloud CLI."
+- **`huaweicloud_run_approved_command`:** Only use when the exact planned command has been shown and the user explicitly approved that exact command.
+- **`huaweicloud_run_script`:** Use for deterministic calculations (cost math, data processing). Never do arithmetic in LLM reasoning.
+
+## Skill Discovery Priority
+
+1. **`huaweicloud-core`** — always check first for routing
+2. **Service-specific skills** — load after routing via `huaweicloud_retrieve_skill`
+3. **Knowledge cards** (`references/`) — quick facts without full skill load
+
+## Red Flags — STOP and Re-evaluate
+
+- Creating resources without user confirmation
+- Using `hcloud csms download-secret` or `hcloud kms decrypt` directly
+- Guessing API parameters without searching docs
+- Creating IAM users or long-term AK/SK
+- Opening OBS buckets to public access
+- Skipping CTS/Cloud Eye on production workloads
+- Echoing AK/SK or secret values in conversation