A local-first multi-agent app development platform, built on PenguinHarness
/**
* QQ scan-to-connect: binding a bot by scanning a QR code in the QQ app instead of copying
* an App ID and an App Secret out of the developer console by hand.
*
* The protocol is three calls against `q.qq.com`, and it is not part of the bot OpenAPI —
* different host, different envelope (`{retcode, msg, data}` rather than
* `{err_code, message}`), no access token. That is why it lives beside qq-api.ts rather
* than inside it.
*
* 1. `create_bind_task` is handed a fresh 32-byte AES key and returns a `task_id`.
* 2. The `task_id` goes into a URL which is ENCODED INTO A QR CODE and never fetched.
* Scanning it in QQ opens the authorization page for the bots the account owns.
* 3. `poll_bind_result` is polled every couple of seconds until it reports the scan
* completed, at which point it returns the bot's App ID and its App Secret encrypted
* under the key from step 1.
*
* ## The key is the whole security model
*
* The AES key decrypts an App Secret, so it is exactly as sensitive as the secret itself.
* It is generated here, held here, used here, and dropped here — it is never returned by
* any route, never rendered, and never reaches a browser. What the browser learns is the
* QR URL, a status, and (once bound) the App ID, which is not secret. This is the same
* never-round-trip-the-secret rule the PUT handlers follow, applied to a flow where the
* secret arrives from outside rather than from the user.
*
* Tencent publishes an npm package that implements this (`@tencent-connect/qqbot-connector`).
* It is deliberately not used: it is `UNLICENSED` with no license text, its dist is
* machine-obfuscated, and it depends on a terminal QR renderer — three separate reasons a
* product that distributes its server and maintains THIRD-PARTY-NOTICES.md cannot take it.
* The protocol is fifty lines and is reimplemented here, behind an injectable seam, in the
* style of telegram-api.ts.
*/
import { createDecipheriv, randomBytes } from "node:crypto";
import { Interface, Module, Provide } from "@adelie/core/kernel";
import type { Opaque } from "@adelie/core/kernel";
/** Host serving the three bind-task calls (not the bot OpenAPI host). */
export const QQ_SCAN_BASE = "https://q.qq.com";
/**
* The page a scanned QR opens. It always points at the production host, even when the calls
* above are made against the test one — the QQ app resolves it, not this server.
*/
export const QQ_SCAN_QR_PAGE = "https://q.qq.com/qqbot/openclaw/connect.html";
/** Overall per-request deadline for the three calls. */
const CALL_TIMEOUT_MS = 15_000;
/** How often a client should poll (the interval the protocol is designed around). */
export const QQ_SCAN_POLL_MS = 2000;
/** AES-256 key length, and what `create_bind_task` is handed (base64) as `key`. */
const QQ_SCAN_KEY_BYTES = 32;
/** AES-GCM framing of `bot_encrypt_secret`: a 12-byte IV in front, a 16-byte tag at the end. */
const GCM_IV_BYTES = 12;
const GCM_TAG_BYTES = 16;
/** Where the scan stands, in the protocol's own vocabulary (0 NONE, 1 PENDING, 2 COMPLETED, 3 EXPIRED). */
export type QQBindStatus = "none" | "pending" | "completed" | "expired";
/** One bot a completed scan authorized: its App ID, and its App Secret still encrypted. */
export interface QQBoundBot {
appId: string;
/** Base64 AES-256-GCM ciphertext of the App Secret, under the task's key. */
encryptedSecret: string;
userOpenid?: string;
}
export interface QQBindPollResult {
status: QQBindStatus;
/**
* The bots a completed scan returned. The wire hands back ONE bot as a bare object; this
* is a list because the shape is worth normalizing once and because Tencent's own client
* wraps it in an array, which is where a future multi-bot response would appear.
*/
bots: QQBoundBot[];
}
/** The three calls, behind a seam so tests substitute a fake and never open a socket. */
export interface QQScanTransport {
/** Registers a bind task under a base64 AES key; resolves the task id. */
createBindTask(key: string): Promise<string>;
pollBindResult(taskId: string): Promise<QQBindPollResult>;
}
/** `{retcode, msg, data}` — the envelope all three calls share (0 = success). */
interface QQScanEnvelope<T> {
retcode?: number;
msg?: string;
data?: T;
}
/** Readable failure text out of fetch's throw shapes (nothing here may echo a request body: it carries the key). */
function fetchErrorText(err: unknown): string {
if (err instanceof Error) {
if (err.name === "TimeoutError" || err.name === "AbortError") return "request timed out";
const cause = (err as { cause?: unknown }).cause;
if (cause instanceof Error && cause.message !== "") return cause.message;
return err.message;
}
return String(err);
}
/** The protocol's numeric status, widened to a name (an unknown value reads as pending, not as failure). */
function statusOf(raw: unknown): QQBindStatus {
switch (Number(raw)) {
case 0:
return "none";
case 2:
return "completed";
case 3:
return "expired";
default:
return "pending";
}
}
/** One `data` entry of a completed poll, in the wire's own field names. */
interface QQBindResultData {
status?: number | string;
bot_appid?: number | string;
bot_encrypt_secret?: string;
user_openid?: string;
}
/** Normalizes the completed payload, which arrives as one object (and is tolerated as a list). */
function botsOf(data: QQBindResultData | QQBindResultData[] | undefined): QQBoundBot[] {
const entries = data === undefined ? [] : Array.isArray(data) ? data : [data];
const bots: QQBoundBot[] = [];
for (const entry of entries) {
const appId = entry.bot_appid;
const secret = entry.bot_encrypt_secret;
if (appId === undefined || appId === "" || typeof secret !== "string" || secret === "") {
continue;
}
bots.push({
appId: String(appId),
encryptedSecret: secret,
...(typeof entry.user_openid === "string" ? { userOpenid: entry.user_openid } : {}),
});
}
return bots;
}
/** The production factory: plain HTTPS against q.qq.com. */
export function createQQScanTransport(base = QQ_SCAN_BASE): QQScanTransport {
const post = async <T>(path: string, payload: Record<string, unknown>): Promise<T> => {
let res: Response;
try {
res = await fetch(`${base}${path}`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(payload),
signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
});
} catch (err) {
throw new Error(`QQ scan request failed: ${fetchErrorText(err)}`);
}
const body = (await res.json().catch(() => null)) as QQScanEnvelope<T> | null;
if (body === null || (body.retcode !== undefined && body.retcode !== 0)) {
const detail = body?.msg ?? `HTTP ${res.status}`;
const code = body?.retcode !== undefined ? ` (retcode ${body.retcode})` : "";
throw new Error(`QQ scan request failed: ${detail}${code}`);
}
return body.data as T;
};
return {
async createBindTask(key: string): Promise<string> {
const data = await post<{ task_id?: string }>("/lite/create_bind_task", { key });
const taskId = data?.task_id;
if (typeof taskId !== "string" || taskId === "") {
throw new Error("QQ scan request failed: no task id was returned");
}
return taskId;
},
async pollBindResult(taskId: string): Promise<QQBindPollResult> {
const data = await post<QQBindResultData | QQBindResultData[]>("/lite/poll_bind_result", {
task_id: taskId,
});
const first = Array.isArray(data) ? data[0] : data;
return { status: statusOf(first?.status), bots: botsOf(data) };
},
};
}
/** A fresh base64 AES-256 key for one bind task. */
export function newQQScanKey(): string {
return randomBytes(QQ_SCAN_KEY_BYTES).toString("base64");
}
/**
* The URL a QR code encodes. It is never fetched by this server — the QQ app opens it, and
* `_wv=2` is the in-app webview flag that makes it render as a full-screen page there.
*
* `source` is left blank, which is what Tencent's own client sends by default; the
* authorization page then labels the requester generically. The field's accepted values are
* not documented, and inventing one risks a page that refuses to load.
*/
export function qqScanQrUrl(taskId: string, source = ""): string {
return `${QQ_SCAN_QR_PAGE}?task_id=${encodeURIComponent(taskId)}&source=${encodeURIComponent(source)}&_wv=2`;
}
/**
* Decrypts `bot_encrypt_secret` into the App Secret.
*
* The framing is not self-describing, so it is stated here rather than inferred at the call
* site: base64-decode, then the first 12 bytes are the GCM IV, the LAST 16 are the auth
* tag, and everything between them is the ciphertext. The key is the base64 `key` from
* `create_bind_task`, decoded — used raw, with no derivation step.
*
* A wrong key, a corrupted payload or a truncated one all fail here as an authentication
* error rather than as plausible-looking garbage, which is the property that makes storing
* the result safe without a second check.
*/
export function decryptQQBotSecret(keyBase64: string, encryptedBase64: string): string {
const key = Buffer.from(keyBase64, "base64");
const payload = Buffer.from(encryptedBase64, "base64");
if (key.length !== QQ_SCAN_KEY_BYTES) {
throw new Error("QQ scan key is not a 32-byte AES key");
}
if (payload.length <= GCM_IV_BYTES + GCM_TAG_BYTES) {
throw new Error("QQ scan payload is too short to contain an encrypted secret");
}
const iv = payload.subarray(0, GCM_IV_BYTES);
const tag = payload.subarray(payload.length - GCM_TAG_BYTES);
const ciphertext = payload.subarray(GCM_IV_BYTES, payload.length - GCM_TAG_BYTES);
const decipher = createDecipheriv("aes-256-gcm", key, iv);
decipher.setAuthTag(tag);
let plaintext: Buffer;
try {
plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
} catch {
// The cause is never echoed: it is a crypto failure on a payload derived from a secret.
throw new Error("QQ scan result could not be decrypted");
}
const secret = plaintext.toString("utf8");
if (secret === "") throw new Error("QQ scan result decrypted to an empty secret");
return secret;
}
// ---------------------------------------------------------------------------
// The in-flight task table
// ---------------------------------------------------------------------------
/**
* How long a bind task is kept. The platform expires tasks on its own and reports it, so
* this is only the bound on remembering a key for a flow nobody finished — a browser tab
* closed mid-scan leaves a task that will otherwise never be polled again.
*/
export const QQ_SCAN_TASK_TTL_MS = 10 * 60_000;
/**
* How many bind tasks ONE Session may keep in flight. This is the ceiling that binds, and
* it is per-Session rather than process-wide on purpose: starting a scan is reachable by
* anyone who owns a Project, which is every signed-up user, so a table bounded only across
* all callers lets one of them in a loop evict everybody else's code. Eviction here can
* only ever drop the caller's OWN oldest task. Four covers a person with a couple of tabs
* open who reloads a few times.
*/
const QQ_SCAN_MAX_TASKS_PER_SESSION = 4;
/**
* Absolute bound on remembered tasks across every Session — a memory backstop, not the
* ceiling a caller runs into. It sits far above any real deployment's concurrent scans
* precisely because reaching it evicts across tenants, which the per-Session ceiling exists
* to keep from happening.
*/
const QQ_SCAN_MAX_TASKS = 4096;
/** One in-flight bind task. The key is the reason this table exists at all. */
interface QQScanTask {
/** Base64 AES key. NEVER leaves this process (see the module doc). */
key: string;
/** The Session that started the scan; another Session's poll is not this task's business. */
sessionId: string;
createdAt: number;
/** A poll is in flight and holds the right to resolve this task (see `poll`). */
claimed: boolean;
}
/** What a poll tells the caller: where the scan stands, and the credentials once it landed. */
export interface QQScanPoll {
status: QQBindStatus;
/** Present only on `completed` — the plaintext pair, for the caller to store. */
bot?: { appId: string; appSecret: string };
}
export interface QQScanServiceOpts {
now?: () => number;
}
/**
* Holds the in-flight bind tasks and their keys.
*
* Deliberately in memory: a task is alive for the couple of minutes a person spends
* scanning, and persisting an AES key that decrypts an App Secret would buy nothing except
* a second place for it to leak from. A server restart mid-scan loses the task, and the
* user starts another — which is a strictly better failure than a key at rest.
*
* A task is consumed by the poll that resolves it: completed or expired, it is gone, so a
* replayed poll of the same task id reads as unknown rather than re-authorizing anything.
* "Consumed" is claimed before the upstream request rather than deleted after it, because
* the client's poll interval fires whether or not the previous request came back.
*/
export class QQScanService {
private readonly tasks = new Map<string, QQScanTask>();
private readonly now: () => number;
/** The self-re-arming sweep, alive only while a task is remembered (see `armSweep`). */
private sweepTimer: ReturnType<typeof setTimeout> | null = null;
constructor(
private readonly transport: QQScanTransport,
opts: QQScanServiceOpts = {},
) {
this.now = opts.now ?? (() => Date.now());
}
/** Starts a scan: a fresh key, a task registered under it, and the URL for the QR. */
async start(sessionId: string): Promise<{ taskId: string; qrUrl: string; pollMs: number }> {
this.sweep();
const key = newQQScanKey();
const taskId = await this.transport.createBindTask(key);
// Evicted after the create rather than before it: a create that failed must not have
// cost the caller a live code.
this.evictOwn(sessionId);
this.tasks.set(taskId, { key, sessionId, createdAt: this.now(), claimed: false });
this.armSweep();
return { taskId, qrUrl: qqScanQrUrl(taskId), pollMs: QQ_SCAN_POLL_MS };
}
/**
* Polls one task. Returns null when the task id is not one this Session started (an
* unknown id, another Session's, one already consumed, or one another poll is resolving
* right now) — the caller answers 404, which is also what a replay gets.
*/
async poll(sessionId: string, taskId: string): Promise<QQScanPoll | null> {
const task = this.tasks.get(taskId);
if (task === undefined || task.sessionId !== sessionId || task.claimed) return null;
// CLAIMED before the await, not deleted after it. The client polls on a fixed interval
// that fires whether or not the previous request came back, so a slow platform leaves
// several polls of one task overlapping; without the claim every one of them decrypts
// the secret and binds again. The claim is released below while the task is unresolved.
task.claimed = true;
if (this.now() - task.createdAt > QQ_SCAN_TASK_TTL_MS) {
this.tasks.delete(taskId);
return { status: "expired" };
}
let result: QQBindPollResult;
try {
result = await this.transport.pollBindResult(taskId);
} catch (err) {
// A request that failed resolved nothing: the task stays pollable, which is what lets
// the client ride out a transient platform error without dropping the user's code.
task.claimed = false;
throw err;
}
if (result.status === "expired") {
this.tasks.delete(taskId);
return { status: "expired" };
}
if (result.status !== "completed") {
task.claimed = false;
return { status: result.status };
}
// Past here the task is spent whatever happens. Completed with nothing to store, and a
// payload that will not decrypt, are both states polling again cannot recover from.
this.tasks.delete(taskId);
const bot = result.bots[0];
if (bot === undefined) {
throw new Error("QQ reported the scan complete but returned no bot");
}
const appSecret = decryptQQBotSecret(task.key, bot.encryptedSecret);
return { status: "completed", bot: { appId: bot.appId, appSecret } };
}
/** Drops a task the user walked away from (the editor's cancel, and its unmount). */
cancel(sessionId: string, taskId: string): void {
if (this.tasks.get(taskId)?.sessionId === sessionId) this.tasks.delete(taskId);
}
/** Session-delete cascade and bind removal: forget anything this Session had in flight. */
cancelSession(sessionId: string): void {
for (const [taskId, task] of this.tasks) {
if (task.sessionId === sessionId) this.tasks.delete(taskId);
}
}
/**
* Drops this Session's oldest tasks until one more fits under its own ceiling. Scoped to
* the caller: the whole point of the per-Session ceiling is that filling it takes a code
* away from nobody else.
*/
private evictOwn(sessionId: string): void {
const own = [...this.tasks].filter(([, task]) => task.sessionId === sessionId);
if (own.length < QQ_SCAN_MAX_TASKS_PER_SESSION) return;
own.sort((a, b) => a[1].createdAt - b[1].createdAt);
for (const [taskId] of own.slice(0, own.length - QQ_SCAN_MAX_TASKS_PER_SESSION + 1)) {
this.tasks.delete(taskId);
}
}
/** Drops expired tasks, then the oldest ones if the table is still over its backstop. */
private sweep(): void {
const cutoff = this.now() - QQ_SCAN_TASK_TTL_MS;
for (const [taskId, task] of this.tasks) {
if (task.createdAt <= cutoff) this.tasks.delete(taskId);
}
if (this.tasks.size < QQ_SCAN_MAX_TASKS) return;
// Age comes from createdAt rather than from the Map's insertion order, so the backstop
// keeps picking the oldest however a task came to sit where it does in the table.
const byAge = [...this.tasks].sort((a, b) => a[1].createdAt - b[1].createdAt);
for (const [taskId] of byAge.slice(0, this.tasks.size - QQ_SCAN_MAX_TASKS + 1)) {
this.tasks.delete(taskId);
}
}
/**
* Keeps one unref'd timer alive while any task is remembered, so a scan the user walked
* away from stops holding its key roughly at the TTL instead of at whenever somebody
* happens to start the next scan — which may be never, and a key at rest is the one
* outcome this module is shaped to avoid. It re-arms only while the table is non-empty,
* and unref'd it is never the reason a process stays alive.
*/
private armSweep(): void {
if (this.sweepTimer !== null || this.tasks.size === 0) return;
const timer = setTimeout(() => {
this.sweepTimer = null;
this.sweep();
this.armSweep();
}, QQ_SCAN_TASK_TTL_MS);
timer.unref();
this.sweepTimer = timer;
}
}
/** The scan-to-connect transport as a node, so a test stands in a fake for the network. */
@Interface()
export abstract class QQScanTransportHandle {
abstract transport: Opaque<"QQScanTransport", QQScanTransport>;
}
@Module()
export class QQScanTransportProvider {
@Provide() qqScanTransport!: QQScanTransportHandle;
setup() {
this.qqScanTransport = { transport: createQQScanTransport() };
}
}