@zhin.js/adapter-icqq 1.1.28 → 1.1.30

package/lib/endpoint.js

@@ -6,7 +6,10 @@ import { receiveOneBotLikeSideEvent } from '@zhin.js/adapter-onebot-events';
 import { buildSystem, toCanonicalSegments } from '@zhin.js/core';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
-import { runIcqqLoginAssistStep } from './icqq-login-assist.js';
+import { IcqqLoginDriver, icqqLinkHost } from './icqq-login-assist.js';
+import { messages as t } from './i18n.js';
+import { redactingIcqqLogger } from './sdk-logger.js';
+import { sanitizeIcqqLoginMessage } from './icqq-login-errors.js';
 import { IcqqContentResolver } from './content-resolver.js';
 import { InboundMessageDeduper, findIcqqNestedMessageSource, isIcqqBotMentioned, isIcqqMessagePostType, normalizeIcqqInboundMessage, messageLookupFromIcqqSource, resolveIcqqQuoteIdFromEvent, resolveIcqqInboundMedia, resolveIcqqSelfUserId, shouldSkipSelfInboundMessage, } from './icqq-inbound.js';
 import { icqqNoticeDedupeKey, isIcqqNoticePayload, isIcqqRequestPayload, } from './icqq-inbox.js';
@@ -36,6 +39,14 @@ const BOUND_EVENTS = [
     'system.login.error',
     'system.login.auth',
 ];
+/**
+ * Log level of an ICQQ `system.*` event by meaning: coming online and login challenges waiting for
+ * the person (QR code, device lock, slider, identity check) are normal progress (`info`); only
+ * failures (login errors, going offline) are `warn`, so a routine login stays out of the warnings.
+ */
+export function icqqSystemEventLogLevel(type) {
+    return type === 'online' || type.startsWith('login.') && type !== 'login.error' ? 'info' : 'warn';
+}
 export class IcqqEndpoint extends ManagedIcqqClient {
     [endpointSpec];
     #logger;
@@ -53,6 +64,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
     #retirementEpoch = 0;
     #retirementArmed = false;
     #disposeNativeEvents;
+    #disposeQrcodeError;
     #resolveStartOnline;
     #heldInbound = [];
     #inflightInbound = new Set();
@@ -62,7 +74,15 @@ export class IcqqEndpoint extends ManagedIcqqClient {
     loginControl;
     #reloginTimer;
     #reloginAttempts = 0;
+    /** Error code of the failure the automatic relogin is retrying (reported when it gives up). */
+    #lastAutoFailure = 'network';
     #reloginInFlight;
+    /**
+     * Login flow of this Endpoint instance (ADR 0058). While a person answers a challenge no
+     * automatic relogin runs: a relogin starts a new SDK login, which issues a new challenge and
+     * voids the URL / ticket the operator is working on.
+     */
+    #login;
     #offlineNoticeAt = 0;
     #challengeNoticeAt = 0;
     #management = Object.freeze({
@@ -170,12 +190,28 @@ export class IcqqEndpoint extends ManagedIcqqClient {
             get transportState() { return state(); },
             management: this.#management, control: this.#control, profile: createIcqqSelfProfile(this),
             get content() { return content(); },
+            login: {
+                // The lease signal aborts on stop / retirement: never let a slow SDK call block it.
+                relogin: async ({ signal }) => { await (signal ? raceAbort(this.relogin(), signal) : this.relogin()); },
+                refreshChallenge: async ({ signal }) => {
+                    await (signal ? raceAbort(this.refreshLoginChallenge(), signal) : this.refreshLoginChallenge());
+                },
+            },
         });
+        // The SDK logs verification links (sid / sig) and the phone at `mark` level: redact them.
+        if (this.logger)
+            this.logger = redactingIcqqLogger(this.logger);
         this.#contentResolver = new IcqqContentResolver(this);
         this.#content = this.#contentResolver.port;
         this.#logger = getAdapterLogger('icqq', options.config.id);
         this.#options = options;
         this.endpointName = options.config.id;
+        this.#login = new IcqqLoginDriver({
+            assist: options.loginAssist, client: this, endpointKey: this.endpointName, owner: this.#loginAssistOwner,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.endpointIdentity ? { endpointIdentity: options.endpointIdentity } : {}),
+            logger: this.#logger, ...(options.locale ? { locale: options.locale } : {}),
+        });
         this.loginControl = Object.freeze({
             endpointId: this.endpointName,
             state: () => ({
@@ -185,6 +221,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
                 pending: this.#pendingLoginTasks(),
             }),
             pending: () => this.#pendingLoginTasks(),
+            flow: () => this.#loginFlow(),
             relogin: async () => { this.#options.signal?.throwIfAborted(); await this.relogin(); },
             submit: (taskId, value) => !this.#options.signal?.aborted && this.#options.loginAssist.submit(taskId, value, this.#options.endpointIdentity),
             cancel: (taskId, reason) => !this.#options.signal?.aborted && this.#options.loginAssist.cancel(taskId, reason, this.#options.endpointIdentity),
@@ -208,10 +245,21 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         // reconn_interval policy. No account-level logout or second retry timer.
         this.emit('internal.error.network', -2, `ICQQ ${operation} failed`);
     }
-    /** Force a login attempt (manual recovery command). */
+    /** Force a login attempt (Console「重新登录」, recovery command): a new login flow. */
     relogin() {
         return this.#startRelogin(true);
     }
+    /**
+     * Console「刷新二维码」: a new QR code in place while a QR challenge is shown; any other
+     * challenge cannot be refreshed alone, so this logs in again.
+     */
+    async refreshLoginChallenge() {
+        if (this.#stopped || this.#retiring || this.#options.signal?.aborted)
+            throw new Error('ICQQ endpoint 已停止');
+        if (await this.#login.refresh())
+            return;
+        await this.relogin();
+    }
     #startRelogin(resetAttempts) {
         if (this.#stopped || this.#retiring) {
             return Promise.reject(new Error('ICQQ endpoint 已停止'));
@@ -220,7 +268,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
             return this.#reloginInFlight;
         if (resetAttempts)
             this.#reloginAttempts = 0;
-        const task = this.#performRelogin();
+        const task = this.#performRelogin(resetAttempts);
         this.#reloginInFlight = task;
         void task.catch(() => undefined).finally(() => {
             if (this.#reloginInFlight === task)
@@ -231,10 +279,15 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         });
         return task;
     }
-    async #performRelogin() {
+    async #performRelogin(manual) {
         this.#clearReloginTimer();
         this.cancelReconnect();
-        this.#logger.info(formatCompact({ op: 'icqq_relogin', endpoint: this.endpointName }));
+        this.#logger.info(formatCompact({ op: 'icqq_relogin', endpoint: this.endpointName, manual }));
+        // A requested relogin is a new attempt; an automatic retry continues the current timeline.
+        if (manual)
+            this.#login.begin(t(this.#options.locale, 'loginReconnecting'));
+        else
+            this.#login.connect(t(this.#options.locale, 'loginReconnecting'));
         try {
             await this.login(this.#options.config.password);
         }
@@ -247,15 +300,37 @@ export class IcqqEndpoint extends ManagedIcqqClient {
             throw error;
         }
     }
+    /**
+     * Automatic backoff relogin, only for failures that need no verification (network drop, kicked,
+     * a plain login that did not finish). Never while a person answers a challenge (ADR 0058 §6).
+     */
     #scheduleRelogin(reason) {
         if (!this.#options.config.autoReconnect || this.#stopped || this.#retiring)
             return;
+        if (this.#login.busy)
+            return;
+        // A failed verification or an expired challenge waits for the person (next: relogin / refresh).
+        if (reason === 'relogin_failed' && this.#login.awaitingPerson)
+            return;
         if (this.#reloginTimer || this.#reloginInFlight)
             return;
-        if (this.#reloginAttempts >= 8)
+        if (this.#reloginAttempts >= ICQQ_RELOGIN_ATTEMPTS) {
+            // Exhausted: the attempt ends and waits for the person.
+            if (!this.#login.awaitingPerson) {
+                const message = t(this.#options.locale, 'loginRetryExhausted', { attempts: ICQQ_RELOGIN_ATTEMPTS });
+                this.#login.fail(this.#lastAutoFailure, message, 'relogin');
+                this.#notifyOffline('relogin_exhausted', false, true);
+            }
             return;
+        }
         const attempt = this.#reloginAttempts++;
         const delayMs = Math.min(300_000, 5_000 * (2 ** Math.min(attempt, 5)));
+        const locale = this.#options.locale;
+        this.#login.info(t(locale, 'loginRetryScheduled', {
+            reason: t(locale, reason === 'kickoff' ? 'loginReasonKickoff' : reason === 'login_network' ? 'loginReasonNetwork' : 'loginReasonFailed'),
+            seconds: Math.round(delayMs / 1000),
+            attempt: attempt + 1,
+        }));
         this.#logger.info(formatCompact({
             op: 'icqq_relogin_scheduled',
             endpoint: this.endpointName,
@@ -277,6 +352,18 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         clearTimeout(this.#reloginTimer);
         this.#reloginTimer = undefined;
     }
+    /** This incarnation's latest login flow (snapshot, including the active challenge's material). */
+    #loginFlow() {
+        if (this.#options.signal?.aborted)
+            return undefined;
+        const flow = this.#options.loginAssist.getFlow('icqq', this.endpointName);
+        const identity = this.#options.endpointIdentity;
+        if (!flow || !identity)
+            return flow;
+        const own = flow.endpointIdentity;
+        return own && own.canonicalId === identity.canonicalId && own.instanceId === identity.instanceId
+            && own.epoch === identity.epoch && own.incarnationId === identity.incarnationId ? flow : undefined;
+    }
     #pendingLoginTasks() {
         if (this.#options.signal?.aborted)
             return [];
@@ -288,12 +375,12 @@ export class IcqqEndpoint extends ManagedIcqqClient {
                 && task.endpointIdentity.incarnationId === this.#options.endpointIdentity.incarnationId
             : task.endpointKey === this.endpointName));
     }
-    #notifyOffline(reason, willRetry) {
+    #notifyOffline(reason, willRetry, force = false) {
         const notifier = this.#options.notifier;
         if (!notifier?.configured)
             return;
         const now = Date.now();
-        if (now - this.#offlineNoticeAt < 60_000)
+        if (!force && now - this.#offlineNoticeAt < 60_000)
             return;
         this.#offlineNoticeAt = now;
         const recovery = willRetry
@@ -323,18 +410,22 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         if (now - this.#challengeNoticeAt < 30_000)
             return;
         this.#challengeNoticeAt = now;
-        const label = step === 'qrcode' ? '二维码验证'
+        const id = this.endpointName;
+        const label = step === 'qrcode' ? '扫码登录'
             : step === 'slider' ? '滑块验证'
-                : step === 'device' ? '设备确认'
-                    : '登录确认';
-        const qrCommand = `icqq login qr ${this.endpointName}`;
-        const confirmCommand = `icqq login confirm ${this.endpointName}`;
-        const codeCommand = `icqq login code ${this.endpointName} <内容>`;
-        const text = `[Zhin] ICQQ ${this.endpointName} 需要${label}。\n`
-            + (step === 'qrcode' || step === 'auth'
-                ? `在 QQ 回复 \`${qrCommand}\` 获取二维码，完成后回复 \`${confirmCommand}\`。`
-                : `在 QQ 回复 \`icqq login status ${this.endpointName}\` 查看验证链接，再用 \`${codeCommand}\` 提交验证码；也可以打开 Console 的 ICQQ 页面。`);
-        void notifier.send(text).then((sent) => {
+                : step === 'device' ? '设备锁验证'
+                    : step === 'sms' ? '短信验证码'
+                        : '身份验证';
+        const next = step === 'qrcode'
+            ? `在 QQ 回复 \`icqq login qr ${id}\` 获取二维码，用手机 QQ 扫码并在手机上确认，登录会自动继续；没有继续时回复 \`icqq login confirm ${id}\`。`
+            : step === 'slider'
+                ? `打开 Console 的 ICQQ 页面，用验证码辅助页完成滑块即可；也可以回复 \`icqq login status ${id}\` 查看滑块链接，再用 \`icqq login code ${id} <ticket>\` 提交。`
+                : step === 'device'
+                    ? `回复 \`icqq login status ${id}\` 查看验证链接，用手机完成验证后回复 \`icqq login confirm ${id}\`；改用短信验证码请回复 \`icqq login code ${id} sms\`。`
+                    : step === 'sms'
+                        ? `收到短信后回复 \`icqq login code ${id} <6 位验证码>\`。`
+                        : `需要复制设备信息到验证页，请打开 Console 的 ICQQ 页面按步骤完成；完成后点「已完成，继续登录」或回复 \`icqq login confirm ${id}\`。`;
+        void notifier.send(`[Zhin] ICQQ ${id} 需要${label}。\n${next}`).then((sent) => {
             if (sent)
                 return;
             this.#logger.warn(formatCompact({
@@ -397,6 +488,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         signal.addEventListener('abort', onAbort, { once: true });
         try {
             this.#bindClientEvents();
+            this.#login.begin();
             await raceAbort(Promise.resolve(this.login(this.#options.config.password)), signal);
             await onlineReady;
             signal.throwIfAborted();
@@ -441,6 +533,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         this.#assertExternalLifecycle('stop');
         this.#stopped = true;
         this.#clearReloginTimer();
+        this.#login.invalidate();
         this.#armRetirementFence();
         await Promise.allSettled([...this.#inflightInbound]);
         this.#resolveStartOnline?.();
@@ -448,6 +541,8 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         this.#heldInbound.length = 0;
         this.#disposeNativeEvents?.();
         this.#disposeNativeEvents = undefined;
+        this.#disposeQrcodeError?.();
+        this.#disposeQrcodeError = undefined;
         for (const event of BOUND_EVENTS) {
             // The retirement guard owns this matcher until a late login handshake
             // has finished. start()/open() replace it with the normal listener.
@@ -744,7 +839,7 @@ export class IcqqEndpoint extends ManagedIcqqClient {
             this.#scheduleRelogin('kickoff');
         });
         this.on('system.login.qrcode', (event) => {
-            this.#logger.info('icqq 收到二维码登录事件，等待 LoginAssist / 终端确认后继续');
+            this.#logger.info('icqq 收到二维码登录事件，等待扫码（Console / 终端 / QQ 命令）');
             this.#handleLoginChallenge('qrcode', event);
         });
         this.on('system.login.device', (event) => {
@@ -754,11 +849,24 @@ export class IcqqEndpoint extends ManagedIcqqClient {
             this.#handleLoginChallenge('slider', event);
         });
         this.on('system.login.error', (event) => {
-            this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'login_error');
-            this.#logSystemEvent('login.error', event);
-            this.#notifyOffline('login_error', this.#options.config.autoReconnect);
-            this.#scheduleRelogin('login_error');
+            const raw = event && typeof event === 'object' ? event : {};
+            this.#logSystemEvent('login.error', event, {
+                ...(typeof raw.code === 'number' ? { code: raw.code } : {}),
+                message: sanitizeIcqqLoginMessage(raw.message),
+            });
+            if (this.#retiring || this.#stopped || this.#options.signal?.aborted)
+                return;
+            this.#handleLoginError(event);
+        });
+        // The SDK's second scan query (inside qrcodeLogin) failed: report it instead of verifying forever.
+        // Only our listener is removed on stop (the SDK has its own one on this internal event).
+        this.#disposeQrcodeError?.();
+        const disposeQrcodeError = this.on('internal.error.qrcode', (code, message) => {
+            if (this.#retiring || this.#stopped || this.#options.signal?.aborted)
+                return;
+            this.#login.qrcodeError(code, message);
         });
+        this.#disposeQrcodeError = () => { disposeQrcodeError(); };
         this.on('system.login.auth', (event) => {
             this.#handleLoginChallenge('auth', event);
         });
@@ -768,12 +876,12 @@ export class IcqqEndpoint extends ManagedIcqqClient {
             if (this.#retiring)
                 return;
             this.#everOnline = true;
+            this.#login.online();
             this.#clearReloginTimer();
             this.#reloginAttempts = 0;
             this.#notifyRecovered();
             try {
                 this.#resolveStartOnline?.();
-                this.#options.loginAssist.cancelOwned(this.#loginAssistOwner, 'online');
                 try {
                     // transport 重连不清除（账号不变）；stop/retire 由基类撤销登记。上报失败不影响上线流程。
                     this[endpointSpec].reportSelfUserId(resolveIcqqSelfUserId(this));
@@ -829,28 +937,50 @@ export class IcqqEndpoint extends ManagedIcqqClient {
         const payload = serializeIcqqEvent(event) ?? (event && typeof event === 'object'
             ? event
             : null);
-        this.#logSystemEvent(`login.${step}`, event);
+        // Verification links carry a session id (sid / sig): logs get the challenge kind and host only.
+        this.#logSystemEvent(`login.${step}`, event, loginChallengeLogLine(step, payload));
         this.#clearReloginTimer();
         this.#notifyChallenge(step);
-        void runIcqqLoginAssistStep({
-            assist: this.#options.loginAssist,
-            locale: this.#options.locale,
-            client: this,
-            adapter: 'icqq',
-            endpointKey: this.endpointName,
-            owner: this.#loginAssistOwner,
-            signal: this.#options.signal, endpointIdentity: this.#options.endpointIdentity,
-            logger: this.#logger,
-            step,
-            event: payload ?? event,
-        });
+        // The QR image is a Buffer, which serialization drops; the driver reads the raw event.
+        const raw = event && typeof event === 'object' ? event : {};
+        this.#login.challenge(step, { ...(payload ?? {}), ...raw });
     }
-    #logSystemEvent(type, event) {
-        const payload = serializeIcqqEvent(event);
+    /**
+     * `system.login.error` (ADR 0058 §5–6): a wrong code stays on its challenge; a verification
+     * failure ends the attempt and waits for the person (`next`). Only a plain login that failed on
+     * the network or for an unknown reason, without any challenge, keeps the automatic backoff.
+     */
+    #handleLoginError(event) {
+        const { mapping, hadChallenge, retrying } = this.#login.loginError(event);
         this.#logger.warn(formatCompact({
+            op: 'icqq_login_error', endpoint: this.endpointName, code: mapping.code,
+            ...(mapping.platformCode !== undefined ? { platform_code: mapping.platformCode } : {}),
+        }));
+        if (retrying)
+            return;
+        const autoRetry = this.#options.config.autoReconnect
+            && (mapping.code === 'network' || (mapping.code === 'unknown' && !hadChallenge));
+        this.#notifyOffline('login_error', autoRetry);
+        if (autoRetry) {
+            this.#login.outcome({ result: 'rejected', code: mapping.code, message: mapping.message, next: 'wait' });
+            this.#lastAutoFailure = mapping.code === 'network' ? 'network' : 'unknown';
+            this.#scheduleRelogin(mapping.code === 'network' ? 'login_network' : 'login_failed');
+            return;
+        }
+        this.#clearReloginTimer();
+        this.#login.fail(mapping.code, mapping.message, mapping.next);
+    }
+    /**
+     * `safe` replaces the payload in the log line and the `system.receive` side event (login
+     * challenges keep only kind and host: links carry a sid, plus phone / device / QR image).
+     */
+    #logSystemEvent(type, event, safe) {
+        const payload = safe === undefined ? serializeIcqqEvent(event) : safe;
+        const line = payload;
+        this.#logger[icqqSystemEventLogLevel(type)](formatCompact({
             op: `system.${type}`,
             endpoint: this.endpointName,
-            ...(payload ? { event: JSON.stringify(payload) } : {}),
+            ...(line ? { event: JSON.stringify(line) } : {}),
         }));
         this.#dispatchIcqqSystemSideEvent(type, payload);
     }
@@ -1262,6 +1392,11 @@ function resolveNativeClientConfig(config) {
         reconn_interval: config.autoReconnect ? 5 : 0,
     };
 }
+/** Log line of a login challenge: its kind and the link's host, never the link, image or device. */
+export function loginChallengeLogLine(kind, payload) {
+    const host = icqqLinkHost(payload?.url);
+    return { kind, ...(host ? { host } : {}) };
+}
 function serializeIcqqEvent(event) {
     if (!event || typeof event !== 'object')
         return null;
@@ -1286,4 +1421,6 @@ function serializeIcqqEvent(event) {
     return Object.keys(out).length > 0 ? out : null;
 }
 const INBOUND_HOLD_LIMIT = 32;
+/** Automatic backoff relogins before the attempt fails and waits for the person. */
+const ICQQ_RELOGIN_ATTEMPTS = 8;
 const ICQQ_SERIALIZE_SKIP = ['group', 'member', 'friend', 'discuss', 'client'];

package/lib/i18n.d.ts

@@ -1 +1 @@
-export declare const messages: (locale: import("zhin.js").Locale | undefined, key: "direct" | "addUsage" | "uinRequired" | "uinInvalid" | "endpointAdded" | "endpointAddFailed" | "loginQr" | "loginSlider" | "loginSms" | "loginAuth" | "loginOther", values?: import("zhin.js").MessageValues) => string;
+export declare const messages: (locale: import("zhin.js").Locale | undefined, key: "direct" | "addUsage" | "uinRequired" | "uinInvalid" | "endpointAdded" | "endpointAddFailed" | "loginConnecting" | "loginReconnecting" | "loginRetryScheduled" | "loginReasonKickoff" | "loginReasonNetwork" | "loginReasonFailed" | "loginSubmit" | "loginVerifying" | "loginVerifyingSlider" | "loginVerifyingDevice" | "loginVerifyingSms" | "loginVerifyingAuth" | "loginSdkCallFailed" | "qrTitle" | "qrShort" | "qrStepScan" | "qrStepConfirm" | "qrStepContinue" | "qrConfirm" | "qrScanned" | "qrNotScanned" | "qrExpired" | "qrRefreshing" | "qrExpiredRefreshing" | "sliderTitle" | "sliderShort" | "sliderStepOpen" | "sliderStepDevtools" | "sliderStepCopy" | "sliderLink" | "sliderInput" | "sliderRandstrMissing" | "deviceTitle" | "deviceShort" | "deviceStepScan" | "deviceStepNoLink" | "deviceStepVerify" | "deviceStepContinue" | "deviceStepSms" | "deviceLink" | "deviceContinue" | "deviceSms" | "smsSendFailed" | "smsTitle" | "smsShort" | "smsPhoneFallback" | "smsInput" | "smsHint" | "smsResend" | "smsResent" | "authTitle" | "authShort" | "authStepCopy" | "authStepOpen" | "authStepScript" | "authStepVerify" | "authStepContinue" | "authWarning" | "authJson" | "authScript" | "authScriptCollapsed" | "authLink" | "authContinue" | "loginErrorCodeInvalid" | "loginErrorRateLimited" | "loginErrorExpired" | "loginErrorRisk" | "loginErrorCredential" | "loginErrorNetwork" | "loginErrorUnknown" | "loginErrorTokenIncompatible" | "loginRetryExhausted", values?: import("zhin.js").MessageValues) => string;