@zhin.js/adapter-icqq 1.1.28 → 1.1.29

package/src/icqq-login-control.ts

@@ -6,7 +6,7 @@
 import { adapterFeatureId, isAdapterIndex } from 'zhin.js/adapter';
 import type { FeatureId, PluginId } from 'zhin.js';
 import { IcqqAdapter } from './adapter.js';
-import type { PendingLoginTask } from '@zhin.js/core';
+import type { LoginFlowSnapshot, PendingLoginTask } from '@zhin.js/core';
 
 export interface IcqqLoginControlState {
   readonly endpointId: string;
@@ -19,8 +19,11 @@ export interface IcqqLoginControl {
   readonly endpointId: string;
   state(): IcqqLoginControlState;
   pending(): readonly PendingLoginTask[];
+  /** Latest login flow of this incarnation (ADR 0058), including the active challenge. */
+  flow(): LoginFlowSnapshot | undefined;
   /** Force a login attempt; rejects when the endpoint is stopped or the SDK login fails. */
   relogin(): Promise<void>;
+  /** Answer a challenge; throws `LoginSubmissionError` when the answer does not fit it. */
   submit(taskId: string, value: string | Record<string, unknown>): boolean;
   cancel(taskId: string, reason?: string): boolean;
 }

package/src/icqq-login-descriptors.ts

@@ -0,0 +1,200 @@
+/**
+ * Challenge descriptors of the ICQQ login flow (ADR 0058 §2–3).
+ *
+ * The guidance text lives here (not in the SDK): the Console, the terminal and the QQ-chat
+ * commands all render these descriptors. Copy blocks with device data are `sensitive`; the helper
+ * script is static text and never contains device or user data.
+ */
+import type { Locale } from 'zhin.js/i18n';
+import type { LoginChallengeDescriptor, LoginHelpStep } from '@zhin.js/core';
+import { messages as t } from './i18n.js';
+
+/** Challenge ids are stable per kind so the Console can keep UI state across re-opened challenges. */
+export const ICQQ_CHALLENGE_IDS = Object.freeze({
+  qrcode: 'icqq-qrcode', slider: 'icqq-slider', device: 'icqq-device', sms: 'icqq-sms', auth: 'icqq-auth',
+});
+
+/** SMS resend cooldown (QQ refuses a second code within a minute). */
+export const ICQQ_SMS_COOLDOWN_MS = 60_000;
+
+/** Page the `auth` helper script runs on (QQ's "send verification code" page). */
+export const ICQQ_AUTH_SCRIPT_HOST = 'accounts.qq.com';
+export const ICQQ_AUTH_SCRIPT_PATH = '/login/attack';
+
+export function qrcodeDescriptor(input: { image?: string }, locale?: Locale): LoginChallengeDescriptor {
+  return {
+    id: ICQQ_CHALLENGE_IDS.qrcode,
+    kind: 'qrcode',
+    title: t(locale, 'qrTitle'),
+    help: {
+      short: t(locale, 'qrShort'),
+      steps: [t(locale, 'qrStepScan'), t(locale, 'qrStepConfirm'), t(locale, 'qrStepContinue')],
+    },
+    media: { ...(input.image ? { qrImage: input.image } : {}), refreshable: true },
+    actions: [{ id: 'confirm', label: t(locale, 'qrConfirm'), variant: 'primary' }],
+  };
+}
+
+export function sliderDescriptor(url: string | undefined, locale?: Locale): LoginChallengeDescriptor {
+  const query = url ? sliderCaptchaQuery(url) : undefined;
+  return {
+    id: ICQQ_CHALLENGE_IDS.slider,
+    kind: 'slider',
+    title: t(locale, 'sliderTitle'),
+    help: {
+      short: t(locale, 'sliderShort'),
+      steps: [
+        { text: t(locale, 'sliderStepOpen'), ...(url ? { blockId: 'slider-link', doneWhen: 'opened' as const } : {}) },
+        t(locale, 'sliderStepDevtools'),
+        t(locale, 'sliderStepCopy'),
+      ],
+    },
+    ...(url ? { blocks: [{ kind: 'link' as const, id: 'slider-link', label: t(locale, 'sliderLink'), url }] } : {}),
+    ...(query ? { media: { captcha: { provider: 'tencent' as const, query } } } : {}),
+    input: { kind: 'ticket', label: t(locale, 'sliderInput'), extract: 'ticket-json-or-url' },
+    actions: [{ id: 'submit', label: t(locale, 'loginSubmit'), variant: 'primary', requiresInput: true }],
+  };
+}
+
+export function deviceDescriptor(input: { url?: string; phone?: string }, locale?: Locale): LoginChallengeDescriptor {
+  const steps: LoginHelpStep[] = [
+    input.url ? { text: t(locale, 'deviceStepScan'), blockId: 'verify-link', doneWhen: 'opened' } : t(locale, 'deviceStepNoLink'),
+    t(locale, 'deviceStepVerify'),
+    t(locale, 'deviceStepContinue'),
+  ];
+  if (input.phone) steps.push(t(locale, 'deviceStepSms'));
+  return {
+    id: ICQQ_CHALLENGE_IDS.device,
+    kind: 'device',
+    title: t(locale, 'deviceTitle'),
+    help: { short: t(locale, 'deviceShort'), steps },
+    ...(input.url ? { blocks: [{ kind: 'link' as const, id: 'verify-link', label: t(locale, 'deviceLink'), url: input.url, showQr: true }] } : {}),
+    actions: [
+      { id: 'continue', label: t(locale, 'deviceContinue'), variant: 'primary' },
+      // The SDK only reports a phone when SMS verification is possible for this lock.
+      ...(input.phone ? [{ id: 'sms', label: t(locale, 'deviceSms'), variant: 'secondary' as const }] : []),
+    ],
+  };
+}
+
+export function smsDescriptor(input: { phone?: string }, locale?: Locale): LoginChallengeDescriptor {
+  return {
+    id: ICQQ_CHALLENGE_IDS.sms,
+    kind: 'sms',
+    title: t(locale, 'smsTitle'),
+    help: { short: t(locale, 'smsShort', { phone: input.phone || t(locale, 'smsPhoneFallback') }) },
+    input: { kind: 'code', label: t(locale, 'smsInput'), length: 6, pattern: '^\\d{6}$', patternHint: t(locale, 'smsHint') },
+    actions: [
+      { id: 'submit', label: t(locale, 'loginSubmit'), variant: 'primary', requiresInput: true },
+      { id: 'resend', label: t(locale, 'smsResend'), variant: 'secondary', cooldownMs: ICQQ_SMS_COOLDOWN_MS },
+    ],
+  };
+}
+
+export function authDescriptor(input: { url?: string; device?: unknown }, locale?: Locale): LoginChallengeDescriptor {
+  const deviceJson = formatDeviceJson(input.device);
+  const hasLink = !!input.url;
+  const steps: LoginHelpStep[] = [];
+  if (deviceJson) steps.push({ text: t(locale, 'authStepCopy'), blockId: 'device-json', doneWhen: 'copied' });
+  steps.push(hasLink ? { text: t(locale, 'authStepOpen'), blockId: 'verify-link', doneWhen: 'opened' } : t(locale, 'authStepOpen'));
+  steps.push(deviceJson ? { text: t(locale, 'authStepScript'), blockId: 'helper-script', doneWhen: 'copied' } : t(locale, 'authStepVerify'));
+  steps.push({ text: t(locale, 'authStepContinue'), doneWhen: 'manual' });
+  return {
+    id: ICQQ_CHALLENGE_IDS.auth,
+    kind: 'auth',
+    title: t(locale, 'authTitle'),
+    help: { short: t(locale, 'authShort'), steps, ...(deviceJson ? { warning: t(locale, 'authWarning') } : {}) },
+    blocks: [
+      ...(deviceJson ? [{
+        kind: 'copy' as const, id: 'device-json', label: t(locale, 'authJson'), content: deviceJson, format: 'json' as const,
+        sensitive: true, ...(hasLink ? { thenOpen: 'verify-link' } : {}),
+      }] : []),
+      ...(hasLink ? [{ kind: 'link' as const, id: 'verify-link', label: t(locale, 'authLink'), url: input.url!, showQr: true }] : []),
+      ...(deviceJson ? [{
+        kind: 'copy' as const, id: 'helper-script', label: t(locale, 'authScript'), content: icqqAuthHelperScript(locale),
+        format: 'script' as const, collapsed: true, collapsedLabel: t(locale, 'authScriptCollapsed'), bookmarklet: true,
+      }] : []),
+    ],
+    actions: [{ id: 'continue', label: t(locale, 'authContinue'), variant: 'primary' }],
+  };
+}
+
+/** Query string of the slider URL (for the hosted captcha helper), or undefined for a non-http URL. */
+export function sliderCaptchaQuery(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return undefined;
+    const query = parsed.search.replace(/^\?/u, '');
+    return query || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Device information of `system.login.auth` as pretty JSON (string fields only), or undefined. */
+export function formatDeviceJson(device: unknown): string | undefined {
+  if (!device || typeof device !== 'object' || Array.isArray(device)) return undefined;
+  const fields: Record<string, string> = {};
+  for (const [key, value] of Object.entries(device as Record<string, unknown>)) {
+    if (typeof value === 'string') fields[key] = value;
+    else if (typeof value === 'number' && Number.isFinite(value)) fields[key] = String(value);
+  }
+  if (typeof fields.guid !== 'string' || !fields.guid) return undefined;
+  return JSON.stringify(fields, null, 2);
+}
+
+const SCRIPT_TEXT = {
+  'zh-CN': {
+    wrongPage: '请在 accounts.qq.com/login/attack（发送验证码的页面）运行这段脚本',
+    prompt: '粘贴从 Zhin 复制的设备 JSON',
+    badJson: '设备 JSON 格式不正确，请重新复制',
+    noGuid: '设备 JSON 缺少 guid，请重新复制',
+    notReady: '页面还没有加载完成，请刷新后再运行',
+    done: '设备信息已写入。请在页面上继续完成验证，完成后回到 Zhin 点「已完成，继续登录」',
+  },
+  en: {
+    wrongPage: 'Run this script on accounts.qq.com/login/attack (the page that sends the verification code)',
+    prompt: 'Paste the device JSON copied from Zhin',
+    badJson: 'The device JSON is not valid. Copy it again',
+    noGuid: 'The device JSON has no guid. Copy it again',
+    notReady: 'The page has not finished loading. Reload it and run the script again',
+    done: 'Device information set. Finish the verification on the page, then choose “Done, continue logging in” in Zhin',
+  },
+} as const;
+
+/**
+ * Static helper script for the `auth` challenge. It runs only on the QQ verification page, asks for
+ * the device JSON with `prompt()`, checks it, sets `window.__INITIAL_STATE__.deviceInfo` and reports
+ * the result. It never submits anything and contains no device or user data. No `//` comments: the
+ * same text becomes a one-line bookmarklet.
+ */
+export function icqqAuthHelperScript(locale?: Locale): string {
+  const text = SCRIPT_TEXT[locale === 'en' ? 'en' : 'zh-CN'];
+  const s = (value: string) => JSON.stringify(value);
+  return [
+    '(function () {',
+    `  if (location.hostname !== ${s(ICQQ_AUTH_SCRIPT_HOST)} || location.pathname !== ${s(ICQQ_AUTH_SCRIPT_PATH)}) {`,
+    `    alert(${s(text.wrongPage)});`,
+    '    return;',
+    '  }',
+    `  var raw = prompt(${s(text.prompt)});`,
+    '  if (!raw) return;',
+    '  var info;',
+    '  try { info = JSON.parse(raw); } catch (error) {',
+    `    alert(${s(text.badJson)});`,
+    '    return;',
+    '  }',
+    "  if (!info || typeof info !== 'object' || typeof info.guid !== 'string' || !info.guid) {",
+    `    alert(${s(text.noGuid)});`,
+    '    return;',
+    '  }',
+    '  var state = window.__INITIAL_STATE__;',
+    "  if (!state || typeof state !== 'object') {",
+    `    alert(${s(text.notReady)});`,
+    '    return;',
+    '  }',
+    '  state.deviceInfo = info;',
+    `  alert(${s(text.done)});`,
+    '})();',
+  ].join('\n');
+}

package/src/icqq-login-errors.ts

@@ -0,0 +1,112 @@
+/**
+ * ICQQ `system.login.error` → LoginAssist error codes (ADR 0058 §5).
+ *
+ * One table: exact SDK codes first (`LoginErrorCode` of the legacy wtlogin path, `NTLoginErrorCode`
+ * of the NT path), then message patterns for errors the SDK only reports as text. The platform's
+ * message is kept only as a sanitized single line (no control characters, no local file paths).
+ */
+import type { Locale } from 'zhin.js/i18n';
+import type { LoginErrorCode, LoginNextAction } from '@zhin.js/core';
+import { messages as t } from './i18n.js';
+
+export interface IcqqLoginErrorRule {
+  /** Exact SDK error codes. */
+  readonly codes?: readonly number[];
+  /** Matched against the SDK message when no code rule applies. */
+  readonly pattern?: RegExp;
+  readonly code: LoginErrorCode;
+  readonly next: LoginNextAction;
+  /** What the SDK means (documentation). */
+  readonly note: string;
+  /** Localized message used instead of the SDK text (when the SDK text would mislead). */
+  readonly messageKey?: 'loginErrorTokenIncompatible';
+}
+
+/** Ordered: the first matching rule wins; code rules are checked before message rules. */
+export const ICQQ_LOGIN_ERROR_TABLE: readonly IcqqLoginErrorRule[] = Object.freeze([
+  // --- exact codes ---
+  { codes: [1, 140022013, 150022029, 150022032], code: 'credential_invalid', next: 'relogin',
+    note: 'WrongPassword / AccountOrPasswordError / MultiplePasswordIncorrect / PasswordModifiedDuringLogin' },
+  // The saved token does not fit the protocol; logging in again reads the same file, so only
+  // removing it helps.
+  { codes: [123456], code: 'credential_invalid', next: 'none', note: 'token incompatible', messageKey: 'loginErrorTokenIncompatible' },
+  { codes: [140022009], code: 'credential_invalid', next: 'relogin', note: 'RefusePasswordLogin (log in by QR code instead)' },
+  { codes: [163, 150022026, 140022016], code: 'code_invalid', next: 'retry_input', note: 'WrongSmsCode / SmsInvalid / IllegalTicket' },
+  { codes: [162, 150022022, 150022023], code: 'rate_limited', next: 'wait', note: 'TooManySms / TooOften / TooManyTimesToday' },
+  { codes: [40, 235, 140022005, 140022019, 150022021, 150022030, 150022033], code: 'risk_blocked', next: 'none',
+    note: 'AccountFrozen / device blacklisted / Frozen / NeedVerifyRealName / BlackAccount / IllegalAccount / LhrEfundFreeze' },
+  { codes: [140022014, 150022035, 150022039], code: 'challenge_expired', next: 'relogin', note: 'ExpireTicket / LongTimeOfNoOperation / CookieExpired' },
+  { codes: [140022002, 140022003, 150022031], code: 'network', next: 'wait', note: 'SystemFailed / TimeoutRetry / InterfaceUnavailable' },
+  // --- message patterns (the SDK reuses codes such as 237 for different texts) ---
+  { pattern: /频繁|频率|too (?:many|often)|frequent/iu, code: 'rate_limited', next: 'wait', note: 'too frequent' },
+  { pattern: /冻结|拉黑|封禁|封号|风险|风控|安全原因|frozen|blocked/iu, code: 'risk_blocked', next: 'none', note: 'risk control' },
+  // Before the ticket rule: "ticket 已过期" is an expired challenge, not a wrong answer.
+  { pattern: /过期|超时|expired|timed? ?out/iu, code: 'challenge_expired', next: 'relogin', note: 'expired' },
+  { pattern: /验证码(?:错误|不正确|无效)|ticket|wrong code/iu, code: 'code_invalid', next: 'retry_input', note: 'wrong code' },
+  { pattern: /密码|password/iu, code: 'credential_invalid', next: 'relogin', note: 'password' },
+  { pattern: /网络|繁忙|network|busy/iu, code: 'network', next: 'wait', note: 'network' },
+]);
+
+export interface IcqqLoginErrorMapping {
+  readonly code: LoginErrorCode;
+  readonly next: LoginNextAction;
+  /** Sanitized platform message, or a localized label when the SDK gave none. */
+  readonly message: string;
+  /** The SDK code, for logs. */
+  readonly platformCode?: number;
+}
+
+const LABEL_KEYS = {
+  code_invalid: 'loginErrorCodeInvalid',
+  rate_limited: 'loginErrorRateLimited',
+  challenge_expired: 'loginErrorExpired',
+  risk_blocked: 'loginErrorRisk',
+  credential_invalid: 'loginErrorCredential',
+  network: 'loginErrorNetwork',
+  unknown: 'loginErrorUnknown',
+} as const satisfies Record<LoginErrorCode, string>;
+
+/** Map one `system.login.error` payload (`{ code, message }`). */
+export function mapIcqqLoginError(event: unknown, locale?: Locale, uin?: string): IcqqLoginErrorMapping {
+  const raw = event && typeof event === 'object' ? event as { code?: unknown; message?: unknown } : {};
+  const platformCode = typeof raw.code === 'number' && Number.isFinite(raw.code) ? raw.code : undefined;
+  const text = typeof raw.message === 'string' ? raw.message : '';
+  const rule = ICQQ_LOGIN_ERROR_TABLE.find((item) => platformCode !== undefined && item.codes?.includes(platformCode))
+    ?? ICQQ_LOGIN_ERROR_TABLE.find((item) => item.pattern && text && item.pattern.test(text));
+  const code: LoginErrorCode = rule?.code ?? 'unknown';
+  return Object.freeze({
+    code,
+    next: rule?.next ?? 'relogin',
+    message: rule?.messageKey ? t(locale, rule.messageKey, { uin: uin || '<uin>' })
+      : sanitizeIcqqLoginMessage(text) || t(locale, LABEL_KEYS[code]),
+    ...(platformCode !== undefined ? { platformCode } : {}),
+  });
+}
+
+/** Localized label of an error code. */
+export function icqqLoginErrorLabel(code: LoginErrorCode, locale?: Locale): string {
+  return t(locale, LABEL_KEYS[code]);
+}
+
+/** Classify a failed `sendSmsCode()`: too frequent → `rate_limited`, anything else `unknown`. */
+export function classifyIcqqSmsFailure(error: unknown): Extract<LoginErrorCode, 'rate_limited' | 'unknown'> {
+  const text = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
+  const code = error && typeof error === 'object' && typeof (error as { code?: unknown }).code === 'number'
+    ? (error as { code: number }).code : undefined;
+  if (code === 162 || /频繁|频率|上限|too (?:many|often)|frequent|limit/iu.test(text)) return 'rate_limited';
+  return 'unknown';
+}
+
+/**
+ * One line, no control characters, local file paths replaced, at most 200 characters.
+ * (The device-blacklist message embeds the absolute path of `device.json`.)
+ */
+export function sanitizeIcqqLoginMessage(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  // eslint-disable-next-line no-control-regex
+  let text = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+  text = text
+    .replace(/(["'“”])(?:[A-Za-z]:)?[\\/][^"'“”]*\1/gu, '$1…$1')
+    .replace(/(?:^|(?<=\s))(?:[A-Za-z]:)?(?:[\\/][\w.@-]+){2,}/gu, '…');
+  return text.length > 200 ? `${text.slice(0, 199)}…` : text;
+}

package/src/sdk-logger.ts

@@ -0,0 +1,57 @@
+/**
+ * Redacting wrapper for the ICQQ SDK's own logger.
+ *
+ * The SDK logs slider / device-lock / identity verification links (they carry a session id: `sid`,
+ * `sig`, `uin-token`) and the account's phone number at `mark` level, which `log_level: 'info'`
+ * does not suppress. The wrapper keeps every SDK diagnostic but strips link queries and phone
+ * numbers before they reach the SDK's log4js logger.
+ *
+ * Not covered (SDK code that bypasses its logger): the terminal QR code drawing and the
+ * `console.log(proto.toJSON())` of the legacy 237 branch; see the README "登录" section.
+ */
+const LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'mark'] as const;
+type Level = typeof LEVELS[number];
+const REDACTED = Symbol('icqq.redacted-logger');
+
+export interface IcqqSdkLogger {
+  level?: unknown;
+  trace(...args: unknown[]): unknown;
+  debug(...args: unknown[]): unknown;
+  info(...args: unknown[]): unknown;
+  warn(...args: unknown[]): unknown;
+  error(...args: unknown[]): unknown;
+  fatal(...args: unknown[]): unknown;
+  mark(...args: unknown[]): unknown;
+}
+
+/** Links keep scheme, host and path; query and fragment become `…`. Phone numbers become `***`. */
+export function redactIcqqLogText(text: string): string {
+  return text
+    .replace(/(https?:\/\/[^\s?#"'<>]+)[?#][^\s"'<>]*/giu, '$1?…')
+    // Masked (138****0000) and full mainland numbers, with or without a country code.
+    .replace(/(?<![\w*])(?:\+?86[- ]?)?1\d{2}(?:\*{2,}|\d{4})\d{4}(?![\w*])/gu, '***')
+    .replace(/(?<![\w*])\d{2,3}\*{2,}\d{2,4}(?![\w*])/gu, '***');
+}
+
+function redactArg(value: unknown): unknown {
+  if (typeof value === 'string') return redactIcqqLogText(value);
+  if (value instanceof Error) return redactIcqqLogText(value.stack ?? value.message);
+  return value;
+}
+
+/** Wrap the SDK logger; `level` reads and writes through to the original. */
+export function redactingIcqqLogger<T extends IcqqSdkLogger>(original: T): T {
+  if ((original as { [REDACTED]?: true })[REDACTED]) return original;
+  const wrapper = Object.create(null) as Record<Level, (...args: unknown[]) => unknown> & { level?: unknown; [REDACTED]?: true };
+  for (const level of LEVELS) {
+    wrapper[level] = (...args: unknown[]) => original[level](...args.map(redactArg));
+  }
+  Object.defineProperty(wrapper, 'level', {
+    get: () => original.level,
+    set: (value: unknown) => { original.level = value; },
+    enumerable: true,
+  });
+  Object.defineProperty(wrapper, REDACTED, { value: true });
+  return wrapper as unknown as T;
+}
+