@optima-chat/dev-skills 0.8.1 → 0.9.0

package/bin/helpers/billing-http.ts

@@ -255,6 +255,111 @@ export async function callSkills<T = unknown>(
   return callService<T>(getSkillsUrl(env), env, method, path, body);
 }
 
+// ───── Admin-USER token (ROPC password grant) ───────────────────────────────
+// Distinct from getServiceToken (M2M client_credentials): user-auth's /admin/*
+// endpoints gate on get_current_admin_user — a real role=ADMIN *user* — which an
+// M2M token (no user_id) can't satisfy. So ban/unban mint a password-grant token
+// for the seeded admin account. Per-env ROPC client = the same public client
+// generate-test-token uses; admin email/password live in Infisical
+// /shared-secrets/credentials. Cached separately from the M2M tokenCache.
+const adminTokenCache: Record<string, string> = {};
+
+const ADMIN_ROPC_CLIENT: Record<string, string> = {
+  stage: 'commerce-cli-stage-ihbbwplz',
+  prod: 'commerce-cli-ecs-pro-i2r5of1h',
+  'cn-prod': 'dev-skill-cli-cn-pro-acvkmcuq',
+  'cn-stage': 'dev-skill-cli-cn-sta-3dvsxzdo',
+};
+
+const ADMIN_CREDS_PATH = '/shared-secrets/credentials';
+
+export async function getAdminUserToken(env: string): Promise<string> {
+  if (adminTokenCache[env]) return adminTokenCache[env];
+
+  let email: string;
+  let password: string;
+  if (env === 'cn-prod' || env === 'cn-stage') {
+    // cn Infisical (separate instance; needs INFISICAL_CN_EMAIL/PASSWORD at runtime).
+    const cnTok = getCnInfisicalToken();
+    const creds = getCnSecrets(cnTok, ADMIN_CREDS_PATH, false, env === 'cn-stage' ? 'staging' : 'prod');
+    email = creds['USER_AUTH_ADMIN_EMAIL'];
+    password = creds['USER_AUTH_ADMIN_PASSWORD'];
+  } else {
+    const cfg = getInfisicalConfig();
+    const tok = getInfisicalToken(cfg);
+    email = fetchInfisicalSecret(env, ADMIN_CREDS_PATH, 'USER_AUTH_ADMIN_EMAIL', cfg, tok);
+    password = fetchInfisicalSecret(env, ADMIN_CREDS_PATH, 'USER_AUTH_ADMIN_PASSWORD', cfg, tok);
+  }
+  if (!email || !password) {
+    throw new Error(`admin 凭证缺失（Infisical ${ADMIN_CREDS_PATH} 的 USER_AUTH_ADMIN_EMAIL/PASSWORD，env=${env}）`);
+  }
+
+  const clientId = ADMIN_ROPC_CLIENT[env];
+  const authUrl = USER_AUTH_URLS[env];
+  if (!clientId || !authUrl) throw new Error(`Unknown env: ${env}`);
+
+  // fetch (not execSync curl) so the password never lands in a shell command line.
+  const form = new URLSearchParams({
+    grant_type: 'password',
+    username: email,
+    password,
+    client_id: clientId,
+  });
+  const res = await fetch(`${authUrl}/api/v1/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: form,
+  });
+  const text = await res.text();
+  let parsed: { access_token?: string };
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`user-auth admin token endpoint returned non-JSON (${env}): ${text.slice(0, 200)}`);
+  }
+  if (!parsed.access_token) {
+    throw new Error(`admin-user token mint failed (${env}): ${text.slice(0, 200)}`);
+  }
+  adminTokenCache[env] = parsed.access_token;
+  return parsed.access_token;
+}
+
+/**
+ * Authenticated call to user-auth as the admin USER (role=ADMIN), for the
+ * /api/v1/admin/* endpoints that getServiceToken's M2M token can't reach
+ * (ban/unban). Mirrors callService's shape; single retry on 5xx.
+ */
+export async function callUserAuthAsAdmin<T = unknown>(
+  env: string,
+  method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
+  path: string,
+  body?: object,
+): Promise<ServiceResponse<T>> {
+  const authUrl = USER_AUTH_URLS[env];
+  if (!authUrl) throw new Error(`Unknown env: ${env}`);
+  const token = await getAdminUserToken(env);
+
+  const doFetch = async () => fetch(`${authUrl}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  let res = await doFetch();
+  if (res.status >= 500) res = await doFetch();
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(formatServiceError(res.status, res.statusText, text));
+  }
+  let parsed: T;
+  try {
+    parsed = text ? (JSON.parse(text) as T) : (undefined as unknown as T);
+  } catch {
+    throw new Error(`user-auth admin returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+  }
+  return { status: res.status, body: parsed };
+}
+
 /**
  * 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
@@ -292,25 +397,6 @@ export async function resolveUserIdByEmail(env: string, email: string): Promise<
   return parsed.user_id;
 }
 
-/**
- * Resolve email → userId across all envs, picking the path that exists for
- * each cloud. AWS (stage/prod) reaches the database over the RDS SSH tunnel
- * (db-utils.resolveUserId). cn-prod / cn-stage have no tunnel into the Aliyun
- * VPC-internal RDS, so they resolve via user-auth's internal HTTP lookup
- * (resolveUserIdByEmail) — the cn dev-skills token carries the
- * internal:users:write scope that endpoint requires. Lets the entitlement
- * subcommands support cn the same way grant-subscription already does, without
- * each call site re-implementing the branch.
- */
-export async function resolveUserIdByEmailAnyEnv(env: string, email: string): Promise<string> {
-  if (env === 'cn-prod' || env === 'cn-stage') {
-    return resolveUserIdByEmail(env, email);
-  }
-  const cfg = getInfisicalConfig();
-  const token = getInfisicalToken(cfg);
-  return resolveUserId(email, env, cfg, token);
-}
-
 /**
  * Resolve a user's id by phone via user-auth's internal lookup endpoint
  * (POST /api/v1/internal/users/lookup with {phone}). Mirrors

package/bin/helpers/entitlement/grant.ts

@@ -1,8 +1,9 @@
-import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
+import { resolveTargetUser } from '../grant-subscription';
 
 interface GrantArgs {
-  email: string;
+  identifier: string;
   productKey: string;
   justification: string;
   yes: boolean;
@@ -11,16 +12,16 @@ interface GrantArgs {
 
 function parseArgs(argv: string[]): GrantArgs {
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-    console.log(`Usage: optima-entitlement grant --email <user> --product-key <slug> --justification "..." [options]
+    console.log(`Usage: optima-entitlement grant <email|phone|userId> --product-key <slug> --justification "..." [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
   --product-key <productKey>
   --justification "..."            Required by billing (400 otherwise); stored on entitlement.justification
 
 Optional:
-  --yes                            Skip prod confirmation prompt (no-op on stage)
-  --env stage|prod|cn-prod|cn-stage  (default: stage)
+  --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy=<clientId>.`);
     process.exit(0);
@@ -30,15 +31,18 @@ Hardcoded server-side: source=ADMIN_GRANT, priceCents=0, currency=USD, grantedBy
     const a = argv[i];
     const next = argv[i + 1];
     switch (a) {
-      case '--email': out.email = next; i++; break;
+      case '--email': out.identifier = next; i++; break; // back-compat alias for the positional identifier
       case '--product-key': out.productKey = next; i++; break;
       case '--justification': out.justification = next; i++; break;
       case '--yes': out.yes = true; break;
       case '--env': out.env = next; i++; break;
-      default: throw new Error(`Unknown arg: ${a}`);
+      default:
+        if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
+        if (out.identifier) throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        out.identifier = a;
     }
   }
-  if (!out.email) throw new Error('--email required');
+  if (!out.identifier) throw new Error('target user required (<email|phone|userId> positional, or --email)');
   if (!out.productKey) throw new Error('--product-key required');
   if (!out.justification) throw new Error('--justification required (billing returns 400 otherwise)');
   return out as GrantArgs;
@@ -48,15 +52,17 @@ export async function runGrant(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
   validateEnvCnProd(args.env);
 
-  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
+  // Shared resolver: accepts email/phone/userId, reverse-verifies + phone-asserts
+  // on cn-prod, email-only via SSH tunnel on AWS (gateway#923).
+  const { userId } = await resolveTargetUser(args.env, args.identifier);
 
   await confirmIfProd(
     args.env,
-    `Action: GRANT product '${args.productKey}' to user ${args.email} (userId=${userId}) on ${args.env.toUpperCase()}\nJustification: ${args.justification}`,
+    `Action: GRANT product '${args.productKey}' to ${args.identifier} (userId=${userId}) on ${args.env.toUpperCase()}\nJustification: ${args.justification}`,
     args.yes,
   );
 
-  console.log(`\n🎁 Granting ${args.productKey} to ${args.email}...`);
+  console.log(`\n🎁 Granting ${args.productKey} to ${args.identifier}...`);
   const res = await callBilling(args.env, 'POST', '/api/billing/admin/grant-entitlement', {
     userId,
     productKey: args.productKey,

package/bin/helpers/entitlement/list.ts

@@ -1,19 +1,20 @@
-import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
+import { resolveTargetUser } from '../grant-subscription';
 
 interface ListArgs {
-  email: string;
+  identifier: string;
   env: string;
 }
 
 function parseArgs(argv: string[]): ListArgs {
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-    console.log(`Usage: optima-entitlement list --email <user-email> [options]
+    console.log(`Usage: optima-entitlement list <email|phone|userId> [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
 
 Optional:
-  --env stage|prod|cn-prod|cn-stage  (default: stage)`);
+  --env stage|prod|cn-prod|cn-stage   (default: stage)`);
     process.exit(0);
   }
   const out: Partial<ListArgs> = { env: 'stage' };
@@ -21,12 +22,15 @@ Optional:
     const a = argv[i];
     const next = argv[i + 1];
     switch (a) {
-      case '--email': out.email = next; i++; break;
+      case '--email': out.identifier = next; i++; break; // back-compat alias for the positional identifier
       case '--env': out.env = next; i++; break;
-      default: throw new Error(`Unknown arg: ${a}`);
+      default:
+        if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
+        if (out.identifier) throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        out.identifier = a;
     }
   }
-  if (!out.email) throw new Error('--email required');
+  if (!out.identifier) throw new Error('target user required (<email|phone|userId> positional, or --email)');
   return out as ListArgs;
 }
 
@@ -43,7 +47,7 @@ export async function runList(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
   validateEnvCnProd(args.env);
 
-  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
+  const { userId } = await resolveTargetUser(args.env, args.identifier);
 
   const res = await callBilling<{ entitlements: EntitlementRow[] }>(
     args.env,
@@ -53,12 +57,12 @@ export async function runList(argv: string[]): Promise<void> {
 
   const rows = res.body.entitlements ?? [];
   if (rows.length === 0) {
-    console.log(`(no entitlements for ${args.email} on ${args.env})`);
+    console.log(`(no entitlements for ${args.identifier} on ${args.env})`);
     return;
   }
   // Newest first per spec
   rows.sort((a, b) => b.purchasedAt.localeCompare(a.purchasedAt));
-  console.log(`${rows.length} entitlement(s) for ${args.email}:\n`);
+  console.log(`${rows.length} entitlement(s) for ${args.identifier}:\n`);
   console.log('id'.padEnd(38) + ' | ' + 'productKey'.padEnd(32) + ' | ' + 'status'.padEnd(9) + ' | ' + 'source'.padEnd(12) + ' | purchasedAt              | refundedAt');
   console.log('-'.repeat(140));
   for (const r of rows) {

package/bin/helpers/entitlement/revoke.ts

@@ -1,8 +1,9 @@
-import { callBilling, validateEnvCnProd, resolveUserIdByEmailAnyEnv } from '../billing-http';
+import { callBilling, validateEnvCnProd } from '../billing-http';
 import { confirmIfProd } from '../confirm-prompt';
+import { resolveTargetUser } from '../grant-subscription';
 
 interface RevokeArgs {
-  email: string;
+  identifier: string;
   productKey: string;
   reason: string;
   yes: boolean;
@@ -18,16 +19,16 @@ interface EntitlementRow {
 
 function parseArgs(argv: string[]): RevokeArgs {
   if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
-    console.log(`Usage: optima-entitlement revoke --email <user> --product-key <slug> --reason "..." [options]
+    console.log(`Usage: optima-entitlement revoke <email|phone|userId> --product-key <slug> --reason "..." [options]
 
 Required:
-  --email <user-email>             Resolved to userId via user-auth DB
+  <email|phone|userId>             Target user. phone/userId only on cn-prod / cn-stage (AWS resolves email only).
   --product-key <productKey>
   --reason "..."                   Required by billing (400 otherwise); stored on entitlement.refundReason
 
 Optional:
-  --yes                            Skip prod confirmation prompt (no-op on stage)
-  --env stage|prod|cn-prod|cn-stage  (default: stage)
+  --yes                            Skip prod/cn-prod confirmation prompt (no-op on stage / cn-stage)
+  --env stage|prod|cn-prod|cn-stage   (default: stage)
 
 Refuses non-ADMIN_GRANT sources (PAYMENT, PARTNER) with source-specific
 error pointing to the right reversal flow.`);
@@ -38,15 +39,18 @@ error pointing to the right reversal flow.`);
     const a = argv[i];
     const next = argv[i + 1];
     switch (a) {
-      case '--email': out.email = next; i++; break;
+      case '--email': out.identifier = next; i++; break; // back-compat alias for the positional identifier
       case '--product-key': out.productKey = next; i++; break;
       case '--reason': out.reason = next; i++; break;
       case '--yes': out.yes = true; break;
       case '--env': out.env = next; i++; break;
-      default: throw new Error(`Unknown arg: ${a}`);
+      default:
+        if (a.startsWith('--')) throw new Error(`Unknown arg: ${a}`);
+        if (out.identifier) throw new Error(`Unexpected positional arg: ${a} (identifier already set to ${out.identifier})`);
+        out.identifier = a;
     }
   }
-  if (!out.email) throw new Error('--email required');
+  if (!out.identifier) throw new Error('target user required (<email|phone|userId> positional, or --email)');
   if (!out.productKey) throw new Error('--product-key required');
   if (!out.reason) throw new Error('--reason required (billing returns 400 otherwise)');
   return out as RevokeArgs;
@@ -60,7 +64,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
   const args = parseArgs(argv);
   validateEnvCnProd(args.env);
 
-  const userId = await resolveUserIdByEmailAnyEnv(args.env, args.email);
+  const { userId } = await resolveTargetUser(args.env, args.identifier);
 
   // Step 1: Fetch user's entitlements
   const listRes = await callBilling<{ entitlements: EntitlementRow[] }>(
@@ -75,10 +79,10 @@ export async function runRevoke(argv: string[]): Promise<void> {
 
   // Step 3: Validate count (partial unique index enforces ≤1 ACTIVE)
   if (matches.length === 0) {
-    throw new Error(`no active entitlement for (user=${args.email}, product=${args.productKey}) on ${args.env}`);
+    throw new Error(`no active entitlement for (user=${args.identifier}, product=${args.productKey}) on ${args.env}`);
   }
   if (matches.length > 1) {
-    throw new Error(`unexpected: ${matches.length} ACTIVE entitlements for (user, product) — partial unique constraint should prevent this. Inspect with: optima-entitlement list --email ${args.email}`);
+    throw new Error(`unexpected: ${matches.length} ACTIVE entitlements for (user, product) — partial unique constraint should prevent this. Inspect with: optima-entitlement list ${args.identifier}`);
   }
   const target = matches[0];
 
@@ -89,7 +93,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
 
   await confirmIfProd(
     args.env,
-    `Action: REVOKE entitlement ${target.id} (productKey=${target.productKey}) for user ${args.email} (userId=${userId}) on ${args.env.toUpperCase()}\nReason: ${args.reason}`,
+    `Action: REVOKE entitlement ${target.id} (productKey=${target.productKey}) for ${args.identifier} (userId=${userId}) on ${args.env.toUpperCase()}\nReason: ${args.reason}`,
     args.yes,
   );
 
@@ -102,7 +106,7 @@ export async function runRevoke(argv: string[]): Promise<void> {
   // this branch only ever runs for ADMIN_GRANT (priceCents=0) — Stripe
   // refund path in billing (admin-products.ts:296-307) is gated on
   // source=PAYMENT and won't trigger here.
-  console.log(`\n♻️  Revoking entitlement ${target.id} for ${args.email}...`);
+  console.log(`\n♻️  Revoking entitlement ${target.id} for ${args.identifier}...`);
   const res = await callBilling(args.env, 'POST', '/api/billing/admin/refund-entitlement', {
     entitlementId: target.id,
     refundReason: args.reason,

package/bin/helpers/grant-balance.ts

@@ -5,17 +5,20 @@
 // 改调 billing 服务态端点（grantCredits → bonus 积分）。
 // ⚠️ 语义变化：旧 wallet granted 无期限；积分 bonus 桶标准 30 天有效期。
 import { randomUUID } from 'crypto';
-import { getInfisicalConfig, getInfisicalToken, resolveUserId } from './db-utils';
-import { callBilling, resolveUserIdByEmail, validateEnvCnProd } from './billing-http';
+import { callBilling, validateEnvCnProd } from './billing-http';
+import { resolveTargetUser } from './grant-subscription';
 
-function parseArgs(args: string[]): { email: string; amountUsd: number; description: string | null; env: string } {
+function parseArgs(args: string[]): { identifier: string; amountUsd: number; description: string | null; env: string } {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log(`Usage: optima-grant-balance <email> --amount <usd> [options]
+    console.log(`Usage: optima-grant-balance <email|phone|userId> --amount <usd> [options]
 
 Grant credits to a user (bonus bucket, expires in 30 days).
 Used for promotional grants, compensation, referral rewards, etc.
 $1 = 700 credits (P15 unified ledger; the USD wallet is retired).
 
+Target user: <email|phone|userId> (positional). phone/userId only on
+cn-prod / cn-stage; AWS stage/prod resolve email only.
+
 Options:
   --amount <usd>        USD amount to grant (required, e.g. 5 for $5.00 = 3500 credits)
   --description <text>  Description for audit trail (optional)
@@ -24,13 +27,12 @@ Options:
 
 Examples:
   optima-grant-balance user@example.com --amount 5 --env prod
-  optima-grant-balance user@example.com --amount 10 --description "Service outage compensation"
-  optima-grant-balance user@example.com --amount 1 --env cn-prod   # ¥-priced env, still USD input ($1 = 700 credits)
+  optima-grant-balance 18898654855 --amount 1 --env cn-prod   # 手机号（cn 用户多为手机号注册）
   optima-grant-balance user@example.com --amount 1 --env cn-stage  # 阿里云预发`);
     process.exit(0);
   }
 
-  const email = args[0];
+  const identifier = args[0];
   let amountUsd = 0;
   let description: string | null = null;
   let env = 'stage';
@@ -47,25 +49,19 @@ Examples:
   }
   validateEnvCnProd(env);
 
-  return { email, amountUsd, description, env };
+  return { identifier, amountUsd, description, env };
 }
 
 async function main() {
-  const { email, amountUsd, description, env } = parseArgs(process.argv.slice(2));
+  const { identifier, amountUsd, description, env } = parseArgs(process.argv.slice(2));
 
-  console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} (${Math.round(amountUsd * 700)} credits) to ${email} [${env.toUpperCase()}]\n`);
+  console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} (${Math.round(amountUsd * 700)} credits) to ${identifier} [${env.toUpperCase()}]\n`);
   if (description) console.log(`   Reason: ${description}`);
 
-  // cn-prod / cn-stage have no SSH tunnel into the Aliyun RDS — resolve via
-  // user-auth's internal lookup API instead of the direct SQL path.
-  let userId: string;
-  if (env === 'cn-prod' || env === 'cn-stage') {
-    userId = await resolveUserIdByEmail(env, email);
-  } else {
-    const infisicalConfig = getInfisicalConfig();
-    const token = getInfisicalToken(infisicalConfig);
-    userId = await resolveUserId(email, env, infisicalConfig, token);
-  }
+  // Shared resolver: classify→resolve→reverse-verify echo→phone-assert on cn
+  // (so phone/userId works for cn's phone-registered users, gateway#923);
+  // email-only via the RDS SSH tunnel on AWS.
+  const { userId } = await resolveTargetUser(env, identifier);
 
   // 幂等键 per-invocation 生成、callBilling 的 5xx retry 复用同 body —— 「已
   // commit 但响应 5xx」场景重试不双发（billing spec R2-M3）。
@@ -80,7 +76,7 @@ async function main() {
   );
 
   console.log(`✓ Granted ${body.credits} credits (lot ${body.lotId})`);
-  console.log(`\n✅ Done! ${email} received ${body.credits} bonus credits (expires in 30 days)\n`);
+  console.log(`\n✅ Done! ${identifier} received ${body.credits} bonus credits (expires in 30 days)\n`);
 }
 
 main().catch(error => {

package/bin/helpers/grant-subscription.ts

@@ -111,22 +111,37 @@ Options:
   return { identifier, plan, months, env };
 }
 
-async function main() {
-  const { identifier, plan, months, env } = parseArgs(process.argv.slice(2));
-
+/**
+ * Resolve a CLI identifier (`<email|phone|userId>`) to a userId + verified
+ * account identity, handling the AWS-vs-cn split. Shared by grant-subscription,
+ * grant-balance, the optima-entitlement subcommands, and optima-account so all
+ * four accept the same identifier forms (gateway#923: phone/userId on cn).
+ *
+ * - AWS (stage/prod): email-only via the RDS SSH tunnel; no internal HTTP
+ *   reverse-verify (the AWS dev-skills token lacks internal:users:write).
+ * - cn-prod / cn-stage: no tunnel into the Aliyun RDS — classify → resolve via
+ *   user-auth internal endpoints → getUserById reverse-verify → phone-assert.
+ *   cn-stage shares cn-prod's HTTP path (same internal endpoints, cn-stage M2M
+ *   token); the split is AWS-vs-cn, NOT prod-vs-stage.
+ *
+ * Prints a `🎯 目标账号` line in BOTH branches before returning, so a wrong
+ * userId is caught by eye before any destructive call (ban/grant/revoke).
+ */
+export async function resolveTargetUser(
+  env: string,
+  identifier: string,
+): Promise<{
+  userId: string;
+  kind: 'email' | 'phone' | 'userId';
+  identity: { phone: string | null; email: string | null };
+}> {
   const kind = classifyIdentifier(identifier);
   assertAwsEmailOnly(env, kind);
-  console.log(`\n🎁 Granting ${plan} subscription to ${identifier} (${kind}) for ${months} month(s) [${env.toUpperCase()}]\n`);
-
-  // identity is the verified target account to print on success. AWS keeps the
-  // pre-change behavior (email-only, no internal HTTP reverse-verify); only
-  // cn-prod / cn-stage run the full classify→resolve→getUserById→phone-assert防呆 path.
-  let userId: string;
-  let identity: { phone: string | null; email: string | null };
 
   if (env === 'cn-prod' || env === 'cn-stage') {
     // cn-prod / cn-stage have no SSH tunnel into the Aliyun RDS — resolve via
     // user-auth, and the dev-skills token carries internal:users:write for lookups.
+    let userId: string;
     if (kind === 'userId') {
       userId = identifier;
     } else if (kind === 'phone') {
@@ -136,28 +151,39 @@ async function main() {
     }
 
     // Reverse-verify: fetch and loudly print the target account identity
-    // before granting, so a wrong userId is caught by eye (gateway#923).
+    // before any mutation, so a wrong userId is caught by eye (gateway#923).
     const acct = await getUserById(env, userId);
     console.log(
       `🎯 目标账号: userId=${userId} 手机=${acct.phone || '(无)'} email=${acct.email || '(无)'} 当前plan=${acct.current_plan || '?'}`,
     );
 
     // Hard assertion: a phone-input grant must land on an account whose phone
-    // matches. Runs BEFORE callBilling — a mismatch aborts without granting.
+    // matches. Runs BEFORE the caller's mutation — a mismatch aborts.
     if (kind === 'phone') {
       assertPhoneMatch(identifier, acct.phone);
     }
-    identity = { phone: acct.phone, email: acct.email };
-  } else {
-    // AWS (stage/prod): email-only, resolved via the RDS SSH tunnel. No
-    // internal HTTP reverse-verify (token lacks internal:users:write → 403).
-    const infisicalConfig = getInfisicalConfig();
-    const token = getInfisicalToken(infisicalConfig);
-    userId = await resolveUserId(identifier, env, infisicalConfig, token);
-    console.log(`🎯 目标账号: userId=${userId} email=${identifier}`);
-    identity = { phone: null, email: identifier };
+    return { userId, kind, identity: { phone: acct.phone, email: acct.email } };
   }
 
+  // AWS (stage/prod): email-only, resolved via the RDS SSH tunnel. No internal
+  // HTTP reverse-verify (token lacks internal:users:write → 403), but still
+  // echo the resolved account so destructive ops have a confirmation line (R1).
+  const infisicalConfig = getInfisicalConfig();
+  const token = getInfisicalToken(infisicalConfig);
+  const userId = await resolveUserId(identifier, env, infisicalConfig, token);
+  console.log(`🎯 目标账号: userId=${userId} email=${identifier}`);
+  return { userId, kind, identity: { phone: null, email: identifier } };
+}
+
+async function main() {
+  const { identifier, plan, months, env } = parseArgs(process.argv.slice(2));
+
+  console.log(`\n🎁 Granting ${plan} subscription to ${identifier} (${classifyIdentifier(identifier)}) for ${months} month(s) [${env.toUpperCase()}]\n`);
+
+  // Shared resolver: classify → resolve → reverse-verify echo → phone-assert
+  // (cn-prod/cn-stage), or email-only via SSH tunnel (AWS). See resolveTargetUser.
+  const { userId, identity } = await resolveTargetUser(env, identifier);
+
   const { body } = await callBilling<{
     success: boolean;
     subscriptionId: string;