@optima-chat/dev-skills 0.7.37 → 0.7.40

package/dist/bin/helpers/billing-http.js

@@ -1,16 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateEnv = validateEnv;
+exports.validateEnvCnProd = validateEnvCnProd;
 exports.getServiceToken = getServiceToken;
 exports.callBilling = callBilling;
 exports.callSkills = callSkills;
+exports.resolveUserIdByEmail = resolveUserIdByEmail;
 const child_process_1 = require("child_process");
 const infisical_secrets_1 = require("./infisical-secrets");
 const db_utils_1 = require("./db-utils");
 const USER_AUTH_URLS = {
     stage: 'https://auth.stage.optima.onl',
     prod: 'https://auth.optima.onl',
+    'cn-prod': 'https://auth-cn.optima.chat',
 };
+// cn-prod URLs are hardcoded: cn Infisical (secrets-cn.optima.chat) is a
+// separate instance dev-skills has no machine identity for, and these domains
+// are stable. AWS envs keep reading /shared-secrets/domain-urls.
+const CN_PROD_BILLING_URL = 'https://billing-cn.optima.chat';
 /**
  * Validate the --env flag value at command entry, before any I/O.
  *
@@ -27,12 +34,38 @@ function validateEnv(env) {
     }
     return env;
 }
+/**
+ * Variant for commands that also support cn-prod — currently grant-balance /
+ * grant-subscription, which reach billing + user-auth over HTTPS only.
+ * Other commands resolve users via the AWS RDS SSH tunnel, which does not
+ * exist for cn-prod (Aliyun VPC-internal RDS) — keep them on validateEnv so a
+ * cn-prod typo fails fast instead of dying inside the tunnel setup.
+ */
+function validateEnvCnProd(env) {
+    if (env !== 'stage' && env !== 'prod' && env !== 'cn-prod') {
+        throw new Error(`--env must be "stage", "prod" or "cn-prod" (got: ${env})`);
+    }
+    return env;
+}
 // T1 discovered: client_id differs per env (stage=dev-skills-ubd3qz6n,
 // prod=dev-skills-hinxa0rs). Both stored in Infisical alongside the
 // secret at /shared-secrets/oauth-clients/.
 const DEV_SKILLS_OAUTH_PATH = '/shared-secrets/oauth-clients';
 const DEV_SKILLS_CLIENT_ID_KEY = 'DEV_SKILLS_OAUTH_CLIENT_ID';
 const DEV_SKILLS_CLIENT_SECRET_KEY = 'DEV_SKILLS_OAUTH_CLIENT_SECRET';
+// cn-prod: the client (dev-skills-ecee51qo) lives in cn user-auth, but its
+// credentials are mirrored into AWS Infisical (prod environment, same path)
+// under CN_PROD-prefixed keys so we reuse the existing Infisical access —
+// zero new credential chain. Canonical copy lives in cn Infisical
+// /shared-secrets/oauth-clients (DEV_SKILLS_OAUTH_CLIENT_ID/SECRET).
+const DEV_SKILLS_CN_CLIENT_ID_KEY = 'DEV_SKILLS_CN_PROD_OAUTH_CLIENT_ID';
+const DEV_SKILLS_CN_CLIENT_SECRET_KEY = 'DEV_SKILLS_CN_PROD_OAUTH_CLIENT_SECRET';
+// cn-prod tokens must carry this scope: resolveUserIdByEmail calls cn
+// user-auth POST /api/v1/internal/users/lookup, whose guard
+// (verify_internal_service_token) requires it. user-auth issues
+// request∩allowed_scopes and an unscoped request yields scope="" (verified
+// against cn-prod 2026-06-12), so the request must name it explicitly.
+const CN_PROD_TOKEN_SCOPE = 'internal:users:write';
 // ───── Cache (process-lifetime) ─────────────────────────────────────────────
 // One CLI invocation does at most a handful of HTTP calls. We mint the M2M
 // token once and reuse it. Cross-invocation re-mint is fine — JWT TTL is
@@ -47,6 +80,8 @@ const tokenCache = {};
 const billingUrlCache = {};
 const skillsUrlCache = {};
 function getBillingUrl(env) {
+    if (env === 'cn-prod')
+        return CN_PROD_BILLING_URL;
     if (billingUrlCache[env])
         return billingUrlCache[env];
     const url = (0, infisical_secrets_1.fetchInfisicalSecret)(env, '/shared-secrets/domain-urls', 'BILLING_URL');
@@ -66,12 +101,19 @@ function getServiceToken(env) {
     const cfg = (0, db_utils_1.getInfisicalConfig)();
     const tok = (0, db_utils_1.getInfisicalToken)(cfg);
     // Fetch BOTH client_id and client_secret from Infisical — they differ per env.
-    const clientId = (0, infisical_secrets_1.fetchInfisicalSecret)(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_ID_KEY, cfg, tok);
-    const clientSecret = (0, infisical_secrets_1.fetchInfisicalSecret)(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_SECRET_KEY, cfg, tok);
+    // cn-prod credentials are mirrored in the AWS Infisical *prod* environment
+    // (fetchInfisicalSecret has no cn-prod env slug), under CN-specific keys.
+    const isCn = env === 'cn-prod';
+    const infisicalEnv = isCn ? 'prod' : env;
+    const idKey = isCn ? DEV_SKILLS_CN_CLIENT_ID_KEY : DEV_SKILLS_CLIENT_ID_KEY;
+    const secretKey = isCn ? DEV_SKILLS_CN_CLIENT_SECRET_KEY : DEV_SKILLS_CLIENT_SECRET_KEY;
+    const clientId = (0, infisical_secrets_1.fetchInfisicalSecret)(infisicalEnv, DEV_SKILLS_OAUTH_PATH, idKey, cfg, tok);
+    const clientSecret = (0, infisical_secrets_1.fetchInfisicalSecret)(infisicalEnv, DEV_SKILLS_OAUTH_PATH, secretKey, cfg, tok);
     const authUrl = USER_AUTH_URLS[env];
     if (!authUrl)
         throw new Error(`Unknown env: ${env}`);
-    const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}`;
+    const scopeParam = isCn ? `&scope=${encodeURIComponent(CN_PROD_TOKEN_SCOPE)}` : '';
+    const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}${scopeParam}`;
     const response = (0, child_process_1.execSync)(`curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`, { encoding: 'utf-8' });
     let parsed;
     try {
@@ -151,3 +193,40 @@ async function callBilling(env, method, path, body) {
 async function callSkills(env, method, path, body) {
     return callService(getSkillsUrl(env), env, method, path, body);
 }
+/**
+ * Resolve a user's id by email via user-auth's internal lookup endpoint
+ * (POST /api/v1/internal/users/lookup). cn-prod only: AWS envs resolve via
+ * the RDS SSH tunnel (db-utils resolveUserId) and their dev-skills clients
+ * don't carry the internal:users:write scope this endpoint requires.
+ */
+async function resolveUserIdByEmail(env, email) {
+    console.log(`Looking up user by email: ${email}`);
+    const token = getServiceToken(env);
+    const authUrl = USER_AUTH_URLS[env];
+    if (!authUrl)
+        throw new Error(`Unknown env: ${env}`);
+    const res = await fetch(`${authUrl}/api/v1/internal/users/lookup`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email }),
+    });
+    const text = await res.text();
+    if (res.status === 404) {
+        throw new Error(`User not found (${env}): ${email}`);
+    }
+    if (!res.ok) {
+        throw new Error(formatServiceError(res.status, res.statusText, text));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`user-auth lookup returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+    }
+    if (!parsed.user_id) {
+        throw new Error(`user-auth lookup response missing user_id: ${text.slice(0, 200)}`);
+    }
+    console.log(`✓ Found user: ${parsed.user_id}`);
+    return parsed.user_id;
+}

package/dist/bin/helpers/db-utils.js

@@ -34,25 +34,48 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RDS_HOSTS = void 0;
+exports.isCnEnv = isCnEnv;
 exports.escapeSQL = escapeSQL;
 exports.getGitHubVariable = getGitHubVariable;
 exports.getInfisicalConfig = getInfisicalConfig;
 exports.getInfisicalToken = getInfisicalToken;
 exports.getInfisicalSecrets = getInfisicalSecrets;
+exports.getCnInfisicalToken = getCnInfisicalToken;
+exports.getCnSecrets = getCnSecrets;
 exports.parseDatabaseUrl = parseDatabaseUrl;
-exports.setupSSHTunnel = setupSSHTunnel;
+exports.ensureTunnel = ensureTunnel;
 exports.queryDB = queryDB;
+exports.connectCnDB = connectCnDB;
+exports.connectCnDBFromUrl = connectCnDBFromUrl;
 exports.connectAuthDB = connectAuthDB;
 exports.connectBillingDB = connectBillingDB;
 exports.resolveUserId = resolveUserId;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 // ─── Constants ──────────────────────────────────────────────────────────────
 exports.RDS_HOSTS = {
     stage: 'optima-stage-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com',
     prod: 'optima-prod-postgres.ctg866o0ehac.ap-southeast-1.rds.amazonaws.com',
 };
+// Shared bastion (optima-bi-data EC2, shared-services stack). Reached via SSM —
+// no public port 22 dependency, so it is immune to the MaxStartups throttling that
+// the open-to-world sshd suffers under internet scan load. SSH path kept as fallback.
+const AWS_REGION = 'ap-southeast-1';
+const BASTION_INSTANCE_ID = 'i-03286fb0a9ce7e6b1';
 const EC2_HOST = '3.0.210.113';
+// ─── cn-prod (阿里云) 常量 ────────────────────────────────────────────────────
+// cn-prod 跑在阿里云 SAE，与海外 AWS 完全独立：独立 Infisical (secrets-cn.optima.chat)
+// + 内网 RDS（无公网端点）经 buildbox ECS 跳板 SSH 隧道访问。设计见 optima-dev-skills#21。
+const CN_INFISICAL_URL = process.env.INFISICAL_CN_URL || 'https://secrets-cn.optima.chat';
+const CN_INFISICAL_ORG = process.env.INFISICAL_CN_ORG || 'f44012fa-0659-4f7e-b0ac-ed01244efc8a';
+const CN_INFISICAL_PROJECT = process.env.INFISICAL_CN_PROJECT || '4deef229-11be-40a5-8f56-b61f0bce7240';
+const CN_RDS_HOST = 'pgm-2zexwx9eso9e4yla.pg.rds.aliyuncs.com';
+const CN_BUILDBOX_HOST = process.env.OPTIMA_CN_BUILDBOX_HOST || '47.94.105.163';
+/** env 是否指向 cn-prod（阿里云）。接受 `cn` / `cn-prod`。 */
+function isCnEnv(env) {
+    return env === 'cn' || env === 'cn-prod';
+}
 // ─── SQL escaping ───────────────────────────────────────────────────────────
 /** Escape a string value for safe inclusion in SQL single-quoted literals. */
 function escapeSQL(value) {
@@ -60,7 +83,8 @@ function escapeSQL(value) {
 }
 // ─── GitHub Variables ───────────────────────────────────────────────────────
 function getGitHubVariable(name) {
-    return (0, child_process_1.execSync)(`gh variable get ${name} -R Optima-Chat/optima-dev-skills`, { encoding: 'utf-8' }).trim();
+    // `gh variable` has no `get` subcommand (only list/set/delete); read the value via the REST variables endpoint.
+    return (0, child_process_1.execSync)(`gh api repos/Optima-Chat/optima-dev-skills/actions/variables/${name} --jq .value`, { encoding: 'utf-8' }).trim();
 }
 // ─── Infisical ──────────────────────────────────────────────────────────────
 function getInfisicalConfig() {
@@ -84,12 +108,102 @@ function getInfisicalSecrets(config, token, environment, secretPath) {
     }
     return secrets;
 }
+// ─── cn Infisical（独立实例，admin email/password 认证）──────────────────────
+/** curl → JSON，用 execFileSync 传参（避免 shell 引号坑，跨平台安全）。 */
+function curlJson(args) {
+    const out = (0, child_process_1.execFileSync)('curl', ['-s', ...args], { encoding: 'utf-8' });
+    try {
+        return JSON.parse(out || '{}');
+    }
+    catch {
+        throw new Error(`cn Infisical: non-JSON response: ${String(out).slice(0, 200)}`);
+    }
+}
+/**
+ * 认证 cn Infisical（admin email/password → org-scoped token）。
+ * ⚠️ 字段名坑：login 返回 `accessToken`（不是 token），select-organization 才返回 `token`。
+ */
+function getCnInfisicalToken() {
+    const email = process.env.INFISICAL_CN_EMAIL;
+    const password = process.env.INFISICAL_CN_PASSWORD;
+    if (!email || !password) {
+        throw new Error('cn Infisical 需要 INFISICAL_CN_EMAIL + INFISICAL_CN_PASSWORD 环境变量（admin user，1P "Infisical cn-prod admin (secrets-cn.optima.chat)"）。见 optima-dev-skills#21。');
+    }
+    const login = curlJson([
+        '-X', 'POST', `${CN_INFISICAL_URL}/api/v3/auth/login`,
+        '-H', 'Content-Type: application/json',
+        '-d', JSON.stringify({ email, password }),
+    ]);
+    if (!login.accessToken)
+        throw new Error(`cn Infisical login 失败: ${JSON.stringify(login).slice(0, 200)}`);
+    const org = curlJson([
+        '-X', 'POST', `${CN_INFISICAL_URL}/api/v3/auth/select-organization`,
+        '-H', 'Content-Type: application/json',
+        '-H', `Authorization: Bearer ${login.accessToken}`,
+        '-d', JSON.stringify({ organizationId: CN_INFISICAL_ORG }),
+    ]);
+    if (!org.token)
+        throw new Error(`cn Infisical select-organization 失败: ${JSON.stringify(org).slice(0, 200)}`);
+    return org.token;
+}
+/** 读 cn Infisical 某 folder（prod env）→ key→value map。expand=true 让服务端解析 `${...}` 引用。 */
+function getCnSecrets(token, secretPath, expand = false) {
+    const data = curlJson([
+        `${CN_INFISICAL_URL}/api/v3/secrets/raw?workspaceId=${CN_INFISICAL_PROJECT}&environment=prod&secretPath=${encodeURIComponent(secretPath)}&expandSecretReferences=${expand}`,
+        '-H', `Authorization: Bearer ${token}`,
+    ]);
+    const secrets = {};
+    for (const s of data.secrets || [])
+        secrets[s.secretKey] = s.secretValue;
+    return secrets;
+}
 // ─── Database URL parsing ───────────────────────────────────────────────────
+/** decodeURIComponent，但密码未做 URL 编码、含裸 % 时不炸：原样返回。 */
+function safeDecode(s) {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+}
+/**
+ * 解析 DATABASE_URL。不用正则一把抓：userinfo 从 authority 的**最后一个 @** 右切，
+ * 密码含 @ * + $ 等特殊字符也不会把密码段误并进 host（曾导致隧道目标变成
+ * `密码片段@pgm-xxx` 且把密码打进 console）。容忍驱动后缀（postgresql+asyncpg://）。
+ * ⚠️ 所有错误信息不回显 URL 本身 —— DATABASE_URL 含凭证，不能进日志。
+ */
 function parseDatabaseUrl(url) {
-    const match = url.match(/^postgresql:\/\/([^:]+):([^@]+)@([^:]+):(\d+)\/([^?]+)/);
-    if (!match)
-        throw new Error('Failed to parse DATABASE_URL (format: postgresql://user:pass@host:port/db)');
-    return { user: decodeURIComponent(match[1]), password: decodeURIComponent(match[2]), host: match[3], port: parseInt(match[4], 10), database: match[5] };
+    const fail = (why) => {
+        throw new Error(`Failed to parse DATABASE_URL (${why}; format: postgresql://user:pass@host:port/db)`);
+    };
+    const scheme = url.match(/^postgres(?:ql)?(?:\+\w+)?:\/\//);
+    if (!scheme)
+        fail('unsupported scheme');
+    const rest = url.slice(scheme[0].length);
+    const slash = rest.indexOf('/');
+    const authority = slash === -1 ? rest : rest.slice(0, slash);
+    const at = authority.lastIndexOf('@');
+    if (at === -1)
+        fail('missing user:pass@');
+    const userinfo = authority.slice(0, at);
+    const colon = userinfo.indexOf(':');
+    if (colon === -1)
+        fail('missing password in userinfo');
+    // host 只允许域名字符 —— 解析错位时密码片段会落到这里，fail-closed 别让它流向隧道命令/日志
+    const hostport = authority.slice(at + 1).match(/^([A-Za-z0-9.-]+)(?::(\d+))?$/);
+    if (!hostport)
+        fail('invalid host:port');
+    const database = slash === -1 ? '' : rest.slice(slash + 1).split('?')[0];
+    if (!database)
+        fail('missing database name');
+    return {
+        user: safeDecode(userinfo.slice(0, colon)),
+        password: safeDecode(userinfo.slice(colon + 1)),
+        host: hostport[1],
+        port: hostport[2] ? parseInt(hostport[2], 10) : 5432,
+        database,
+    };
 }
 // ─── SSH tunnel ─────────────────────────────────────────────────────────────
 // 端口被占不等于 tunnel 还能转发：AWS bastion idle 断连后，本地 ssh 进程还活着、
@@ -104,27 +218,55 @@ function isTunnelHealthy(localPort) {
         return false;
     }
 }
-function killOrphanTunnel(localPort) {
+function portPids(localPort) {
     try {
-        const pids = (0, child_process_1.execSync)(`lsof -ti:${localPort}`, { encoding: 'utf-8' }).trim();
-        if (pids)
-            (0, child_process_1.execSync)(`kill -9 ${pids.split(/\s+/).join(' ')}`, { stdio: 'ignore' });
+        return (0, child_process_1.execSync)(`lsof -ti:${localPort}`, { encoding: 'utf-8' }).trim().split(/\s+/).filter(Boolean);
+    }
+    catch {
+        return [];
     }
-    catch { /* nothing to kill */ }
 }
-function setupSSHTunnel(dbHost, localPort) {
-    let portInUse = false;
+// lsof 只能看到「有进程 bind」的端口。Docker 发布端口走 iptables DNAT 时主机上
+// 没有进程绑定（lsof 空），但流量照样被内核截给容器 —— 在这种端口上建隧道，
+// psql 连的还是容器里的库。所以空闲判定必须用客户端视角：真去 connect，有人
+// 应答（无论进程还是 DNAT）就算被占。
+function isPortResponding(localPort) {
     try {
-        (0, child_process_1.execSync)(`lsof -ti:${localPort}`, { stdio: 'ignore' });
-        portInUse = true;
+        // 单条命令：connect 失败 bash 即 exit 非 0（再跟一条命令会把退出码盖掉）；
+        // fd 随 bash 进程退出自动关闭。
+        (0, child_process_1.execSync)(`bash -c 'exec 3<>/dev/tcp/127.0.0.1/${localPort}'`, { stdio: 'ignore', timeout: 2000 });
+        return true;
     }
-    catch { /* free */ }
-    if (portInUse) {
-        if (isTunnelHealthy(localPort))
-            return;
-        console.log(`! SSH tunnel on port ${localPort} not responding (zombie), replacing...`);
-        killOrphanTunnel(localPort);
+    catch {
+        return false;
     }
+}
+// 端口被占 ≠ 是我们的隧道：本机 Docker PG 也会监听这些端口，且对 pg_isready
+// 完全健康 —— 曾把 prod 凭证发给本机 15433 上的 Docker PG，报「密码错误」。
+// 判别器 = 占用进程的 comm：ssh（legacy 隧道）或 session-manager-plugin（SSM）。
+function isTunnelProcessOnPort(localPort) {
+    return portPids(localPort).some(pid => {
+        try {
+            const comm = (0, child_process_1.execSync)(`ps -o comm= -p ${pid}`, { encoding: 'utf-8' }).trim();
+            return comm === 'ssh' || comm.includes('session-manager');
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function killOrphanTunnel(localPort) {
+    // 只杀我们的隧道进程 —— 端口上若是别人（docker-proxy/postgres），kill -9 是破坏性的。
+    for (const pid of portPids(localPort)) {
+        try {
+            const comm = (0, child_process_1.execSync)(`ps -o comm= -p ${pid}`, { encoding: 'utf-8' }).trim();
+            if (comm === 'ssh' || comm.includes('session-manager'))
+                (0, child_process_1.execSync)(`kill -9 ${pid}`, { stdio: 'ignore' });
+        }
+        catch { /* already gone */ }
+    }
+}
+function setupSSHTunnel(dbHost, localPort) {
     const sshKeyPath = `${process.env.HOME}/.ssh/optima-ec2-key`;
     if (!fs.existsSync(sshKeyPath))
         throw new Error(`SSH key not found: ${sshKeyPath}. Please obtain optima-ec2-key from xbfool.`);
@@ -137,6 +279,160 @@ function setupSSHTunnel(dbHost, localPort) {
         `-o ExitOnForwardFailure=yes -o ConnectTimeout=10 ` +
         `-L ${localPort}:${dbHost}:5432 ec2-user@${EC2_HOST}`, { stdio: 'inherit' });
 }
+/** Block the current (sync) call for `ms` without spawning a subprocess. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function assertSSMPrereqs() {
+    for (const [bin, hint] of [
+        ['session-manager-plugin', 'https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html'],
+        ['aws', 'AWS CLI v2: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html'],
+    ]) {
+        try {
+            (0, child_process_1.execSync)(`command -v ${bin}`, { stdio: 'ignore' });
+        }
+        catch {
+            throw new Error(`${bin} not found — required for the SSM DB tunnel. Install: ${hint}\n(or set OPTIMA_DB_TUNNEL=ssh to fall back to the legacy SSH tunnel)`);
+        }
+    }
+}
+/**
+ * Open a local→RDS tunnel through the shared bastion using SSM port forwarding.
+ * No public SSH port is touched. A healthy existing tunnel on the port is reused
+ * (the ~2s SSM cold start is paid once, then every query is just a round-trip).
+ */
+function setupSSMTunnel(dbHost, localPort) {
+    assertSSMPrereqs();
+    console.log(`Creating SSM tunnel: localhost:${localPort} -> ${BASTION_INSTANCE_ID} -> ${dbHost}:5432`);
+    const logFile = `${os.tmpdir()}/optima-ssm-tunnel-${localPort}.log`;
+    const out = fs.openSync(logFile, 'w');
+    const child = (0, child_process_1.spawn)('aws', [
+        'ssm', 'start-session',
+        '--region', AWS_REGION,
+        '--target', BASTION_INSTANCE_ID,
+        '--document-name', 'AWS-StartPortForwardingSessionToRemoteHost',
+        '--parameters', `host=${dbHost},portNumber=5432,localPortNumber=${localPort}`,
+    ], { detached: true, stdio: ['ignore', out, out] });
+    child.unref();
+    // Wait until the remote leg actually forwards (pg_isready probes RDS through the
+    // tunnel). Local port binds instantly; the remote hop needs ~1-2s to come up.
+    const deadlineMs = Date.now() + 20000;
+    while (Date.now() < deadlineMs) {
+        if (isTunnelHealthy(localPort)) {
+            console.log(`✓ SSM tunnel ready on port ${localPort}`);
+            return;
+        }
+        sleepSync(500);
+    }
+    let tail = '(no log)';
+    try {
+        tail = fs.readFileSync(logFile, 'utf-8').split('\n').slice(-8).join('\n');
+    }
+    catch { /* ignore */ }
+    throw new Error(`SSM tunnel on port ${localPort} did not become ready within 20s.\n--- ${logFile} ---\n${tail}`);
+}
+/**
+ * 隧道 localhost:localPort → cn 内网 RDS，经 buildbox ECS 跳板（sshpass SSH）。
+ * 密码经 SSHPASS 环境变量传给 `sshpass -e`：不进命令行（ps 不可见）、不经 shell 引号展开。
+ */
+function setupCnSSHTunnel(dbHost, localPort) {
+    const pw = process.env.OPTIMA_CN_BUILDBOX_PASSWORD;
+    if (!pw)
+        throw new Error('cn DB 隧道需要 OPTIMA_CN_BUILDBOX_PASSWORD 环境变量（buildbox root 密码，1P "Aliyun cn-prod buildbox ECS (root)"）。见 optima-dev-skills#21。');
+    try {
+        (0, child_process_1.execSync)('command -v sshpass', { stdio: 'ignore' });
+    }
+    catch {
+        throw new Error('sshpass not found — cn buildbox 隧道需要（apt install sshpass / brew install esolitos/ipa/sshpass）。Windows 用 WSL。');
+    }
+    console.log(`Creating cn tunnel: localhost:${localPort} -> buildbox ${CN_BUILDBOX_HOST} -> ${dbHost}:5432`);
+    (0, child_process_1.execSync)(`sshpass -e ssh -f -N -o StrictHostKeyChecking=no ` +
+        `-o ServerAliveInterval=30 -o ServerAliveCountMax=3 ` +
+        `-o ExitOnForwardFailure=yes -o ConnectTimeout=12 ` +
+        `-L ${localPort}:${dbHost}:5432 root@${CN_BUILDBOX_HOST}`, { stdio: 'inherit', env: { ...process.env, SSHPASS: pw } });
+    const deadlineMs = Date.now() + 20000;
+    while (Date.now() < deadlineMs) {
+        if (isTunnelHealthy(localPort)) {
+            console.log(`✓ cn tunnel ready on port ${localPort}`);
+            return;
+        }
+        sleepSync(500);
+    }
+    throw new Error(`cn tunnel on port ${localPort} did not become ready within 20s`);
+}
+// ─── Tunnel port registry ───────────────────────────────────────────────────
+// 端口动态分配：固定端口（旧 15432-15435）会撞本机服务（Docker PG 占 15433 →
+// prod 凭证发给错误的库报「密码错误」）。每个 RDS host 一条隧道，实际端口记在
+// 注册文件里，复用前验证「端口上确实是我们的隧道进程且健康」。
+const TUNNEL_REGISTRY = `${os.homedir()}/.cache/optima-dev-skills/tunnel-ports.json`;
+// 基址刻意避开 1543x/543x：本机 Docker PG 常映射在那一带，DNAT 端口即使我们的
+// 隧道进程 bind 成功，OUTPUT 链的 DNAT 仍会把 127.0.0.1 流量截给容器（实测），
+// 复用判定无法从外部区分 —— 离它远点是最便宜的防线。
+const TUNNEL_PORT_SCAN_BASE = 25432;
+const TUNNEL_PORT_SCAN_LIMIT = 100;
+function readTunnelRegistry() {
+    try {
+        return JSON.parse(fs.readFileSync(TUNNEL_REGISTRY, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeTunnelRegistry(reg) {
+    // 注册文件非并发安全（全量覆盖、无锁）：并发 CLI 进程可能互相覆盖记录或抢同
+    // 一空闲端口。后果 fail-closed（多建一条隧道 / 第二个 bind 失败报错重试），
+    // 对单人运维 CLI 可接受，不为此引入锁。
+    fs.mkdirSync(`${os.homedir()}/.cache/optima-dev-skills`, { recursive: true });
+    fs.writeFileSync(TUNNEL_REGISTRY, JSON.stringify(reg, null, 2));
+}
+/** First free local port, preferring the registry's previous assignment. */
+function pickTunnelPort(preferred) {
+    const candidates = preferred ? [preferred] : [];
+    for (let p = TUNNEL_PORT_SCAN_BASE; p < TUNNEL_PORT_SCAN_BASE + TUNNEL_PORT_SCAN_LIMIT; p++) {
+        if (p !== preferred)
+            candidates.push(p);
+    }
+    for (const p of candidates) {
+        if (portPids(p).length === 0 && !isPortResponding(p))
+            return p;
+    }
+    throw new Error(`No free local port in ${TUNNEL_PORT_SCAN_BASE}-${TUNNEL_PORT_SCAN_BASE + TUNNEL_PORT_SCAN_LIMIT - 1} for the DB tunnel`);
+}
+/**
+ * Ensure a local→RDS tunnel to `dbHost` exists and return its local port.
+ * One tunnel per RDS host (auth/billing on the same instance share it) —
+ * registry 按 dbHost 记端口，换库自然换隧道，不存在「端口被占就当同一条」的错配。
+ * AWS defaults to SSM (no public port 22; set OPTIMA_DB_TUNNEL=ssh for legacy SSH);
+ * `via: 'cn-buildbox'` 走阿里云 buildbox ECS 跳板（cn 内网 RDS 无公网端点）。
+ */
+function ensureTunnel(dbHost, via = 'aws') {
+    // dbHost 可能来自解析的 DATABASE_URL，且会进 ssh 命令行/日志 —— 只放行域名字符。
+    if (!/^[A-Za-z0-9.-]+$/.test(dbHost))
+        throw new Error('ensureTunnel: dbHost contains unexpected characters (refusing to build tunnel command)');
+    const reg = readTunnelRegistry();
+    const known = reg[dbHost];
+    if (known !== undefined && isTunnelProcessOnPort(known)) {
+        if (isTunnelHealthy(known))
+            return known; // warm reuse — no cold start
+        console.log(`! Tunnel on port ${known} not responding (zombie), replacing...`);
+        killOrphanTunnel(known);
+    }
+    // Foreign process on the recorded port (e.g. a local Docker PG) → pick a
+    // different port instead of talking to whatever squats there.
+    const port = pickTunnelPort(known);
+    if (via === 'cn-buildbox') {
+        setupCnSSHTunnel(dbHost, port);
+    }
+    else if ((process.env.OPTIMA_DB_TUNNEL || 'ssm').toLowerCase() === 'ssh') {
+        setupSSHTunnel(dbHost, port);
+    }
+    else {
+        setupSSMTunnel(dbHost, port);
+    }
+    reg[dbHost] = port;
+    writeTunnelRegistry(reg);
+    return port;
+}
 // ─── psql ───────────────────────────────────────────────────────────────────
 function findPsqlPath() {
     try {
@@ -160,14 +456,49 @@ function queryDB(conn, sql) {
     }).trim();
 }
 // ─── High-level connection helpers ──────────────────────────────────────────
+/**
+ * 连 cn-prod 某服务库：creds 取自 cn Infisical 的 /shared-secrets/database-users +
+ * /database-names（按 prefix，如 AUTH/BILLING），经 buildbox 跳板隧道（动态端口）。
+ */
+function connectCnDB(prefix) {
+    const token = getCnInfisicalToken();
+    const users = getCnSecrets(token, '/shared-secrets/database-users');
+    const names = getCnSecrets(token, '/shared-secrets/database-names');
+    const user = users[`${prefix}_DB_USER`];
+    const password = users[`${prefix}_DB_PASSWORD`];
+    const database = names[`${prefix}_DB_NAME`];
+    if (!user || !password || !database) {
+        throw new Error(`cn DB creds 不全 for ${prefix}（需 ${prefix}_DB_USER/PASSWORD@database-users + ${prefix}_DB_NAME@database-names）。该服务 cn 可能用字面 DATABASE_URL，见 optima-dev-skills#21。`);
+    }
+    const port = ensureTunnel(CN_RDS_HOST, 'cn-buildbox');
+    const conn = { host: 'localhost', port, user, password, database };
+    return { query: (sql) => queryDB(conn, sql) };
+}
+/**
+ * 连 cn-prod 某服务库，creds 来自该服务 /services/<svc> 的字面/展开 DATABASE_URL。
+ * 用于 cred 不在 shared-secrets/database-users 的服务（如 gateway-core）。
+ * expandSecretReferences=true 让 cn Infisical 解析 `${...}` 引用为字面值。
+ */
+function connectCnDBFromUrl(servicePath) {
+    const token = getCnInfisicalToken();
+    const secrets = getCnSecrets(token, servicePath, true);
+    const dbUrl = secrets['DATABASE_URL'];
+    if (!dbUrl)
+        throw new Error(`cn DATABASE_URL 未找到 at ${servicePath}`);
+    // 注意：DATABASE_URL 含凭证，报错只说事实，不回显值
+    if (dbUrl.includes('${'))
+        throw new Error(`cn DATABASE_URL 仍含未解析引用（expand 失败）at ${servicePath}`);
+    const parsed = parseDatabaseUrl(dbUrl); // host = cn 内网 RDS（经 buildbox 隧道到达）
+    const port = ensureTunnel(parsed.host, 'cn-buildbox');
+    const conn = { host: 'localhost', port, user: parsed.user, password: parsed.password, database: parsed.database };
+    return { query: (sql) => queryDB(conn, sql) };
+}
 /** Connect to user-auth DB and return a query function. */
 async function connectAuthDB(env, infisicalConfig, token) {
     const infisicalEnv = env === 'stage' ? 'staging' : 'prod';
     const secrets = getInfisicalSecrets(infisicalConfig, token, infisicalEnv, '/shared-secrets/database-users');
     const host = exports.RDS_HOSTS[env];
-    const port = env === 'stage' ? 15432 : 15433;
-    setupSSHTunnel(host, port);
-    await new Promise(r => setTimeout(r, 1000));
+    const port = ensureTunnel(host);
     const conn = { host: 'localhost', port, user: secrets['AUTH_DB_USER'], password: secrets['AUTH_DB_PASSWORD'], database: 'optima_auth' };
     return { query: (sql) => queryDB(conn, sql) };
 }
@@ -179,9 +510,7 @@ async function connectBillingDB(env, infisicalConfig, token) {
     if (!dbUrl)
         throw new Error('DATABASE_URL not found for billing service');
     const parsed = parseDatabaseUrl(dbUrl);
-    const port = env === 'stage' ? 15434 : 15435;
-    setupSSHTunnel(parsed.host, port);
-    await new Promise(r => setTimeout(r, 1000));
+    const port = ensureTunnel(parsed.host);
     const conn = { host: 'localhost', port, user: parsed.user, password: parsed.password, database: parsed.database };
     return { query: (sql) => queryDB(conn, sql) };
 }