larkit 0.0.0-stage → 0.1.0

package/src/probe/openapi.js

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CACHE_DIR } from "../shared/paths.js";
+import { getAppCredentials, loadConfig } from "../shared/config.js";
+import { ensureDir, readJson, writeJson } from "../shared/util.js";
+
+const TOKEN_FILE = path.join(CACHE_DIR, "tokens.json");
+const OPENAPI_BASE = "https://open.feishu.cn";
+
+function loadTokens() {
+  return readJson(TOKEN_FILE, {});
+}
+
+function saveTokens(tokens) {
+  ensureDir(CACHE_DIR);
+  writeJson(TOKEN_FILE, tokens);
+}
+
+export async function getTenantToken({ appId, appSecret, force = false } = {}) {
+  let resolved = appId && appSecret ? { app_id: appId, app_secret: appSecret, source: "args" } : getAppCredentials(appId);
+  if (!resolved) {
+    throw new Error(
+      "app_id/app_secret required (args, larkit.config.json apps, or FEISHU_APP_ID/FEISHU_APP_SECRET)",
+    );
+  }
+  const tokens = loadTokens();
+  const cached = tokens[resolved.app_id];
+  if (!force && cached && cached.expires_at > Date.now() + 60_000) {
+    return { ...cached, cached: true };
+  }
+  const response = await fetch(
+    `${OPENAPI_BASE}/open-apis/auth/v3/tenant_access_token/internal`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json; charset=utf-8" },
+      body: JSON.stringify({
+        app_id: resolved.app_id,
+        app_secret: resolved.app_secret,
+      }),
+      signal: AbortSignal.timeout(20_000),
+    },
+  );
+  const data = await response.json();
+  if (data.code !== 0 || !data.tenant_access_token) {
+    throw new Error(
+      `tenant_access_token failed: code=${data.code} msg=${data.msg || "unknown"}`,
+    );
+  }
+  const expiresAt = Date.now() + Math.max(60, Number(data.expire) || 7200) * 1000;
+  const token = {
+    app_id: resolved.app_id,
+    tenant_access_token: data.tenant_access_token,
+    expires_at: expiresAt,
+    obtained_at: Date.now(),
+    source: resolved.source,
+  };
+  tokens[resolved.app_id] = token;
+  saveTokens(tokens);
+  return { ...token, cached: false };
+}
+
+export function clearToken(appId) {
+  const tokens = loadTokens();
+  if (appId) delete tokens[appId];
+  else for (const key of Object.keys(tokens)) delete tokens[key];
+  saveTokens(tokens);
+  return { ok: true, cleared: appId || "all" };
+}
+
+function normalizePath(input) {
+  let p = String(input || "").trim();
+  if (!p) throw new Error("path is required");
+  if (/^https?:\/\//i.test(p)) return p;
+  if (!p.startsWith("/")) p = `/${p}`;
+  if (!p.startsWith("/open-apis/")) p = `/open-apis${p}`;
+  return `${OPENAPI_BASE}${p}`;
+}
+
+function truncateDeep(value, maxChars = 12_000) {
+  const text = JSON.stringify(value);
+  if (text.length <= maxChars) return value;
+  return {
+    _truncated: true,
+    _original_chars: text.length,
+    preview: text.slice(0, maxChars),
+  };
+}
+
+export async function probeOpenApi({
+  appId,
+  appSecret,
+  method = "GET",
+  path: apiPath,
+  query,
+  body,
+  headers = {},
+  userAccessToken,
+  tenantAccessToken,
+  forceToken = false,
+  timeout = 30_000,
+} = {}) {
+  if (!apiPath) throw new Error("path is required");
+  let token = tenantAccessToken || "";
+  let tokenSource = tenantAccessToken ? "arg" : "";
+  if (!token && !userAccessToken) {
+    const t = await getTenantToken({ appId, appSecret, force: forceToken });
+    token = t.tenant_access_token;
+    tokenSource = t.cached ? "cache" : "fresh";
+  }
+  const url = new URL(normalizePath(apiPath));
+  if (query && typeof query === "object") {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) url.searchParams.append(key, String(item));
+      } else {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  const requestHeaders = {
+    Accept: "application/json, text/plain, */*",
+    "User-Agent":
+      "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/125 Safari/537.36",
+    ...headers,
+  };
+  if (token) requestHeaders.Authorization = `Bearer ${token}`;
+  else if (userAccessToken) requestHeaders.Authorization = `Bearer ${userAccessToken}`;
+  const hasBody = body !== undefined && body !== null && method !== "GET" && method !== "HEAD";
+  if (hasBody) requestHeaders["Content-Type"] = "application/json; charset=utf-8";
+  const t0 = Date.now();
+  let response;
+  try {
+    response = await fetch(url, {
+      method: method.toUpperCase(),
+      headers: requestHeaders,
+      body: hasBody
+        ? typeof body === "string"
+          ? body
+          : JSON.stringify(body)
+        : undefined,
+      signal: AbortSignal.timeout(timeout),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      mode: "openapi",
+      error: error instanceof Error ? error.message : String(error),
+      request: { method, url: url.toString() },
+      elapsed_ms: Date.now() - t0,
+    };
+  }
+  const raw = await response.text();
+  let json = null;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    // non-JSON response
+  }
+  const code = json?.code ?? null;
+  const msg = json?.msg ?? json?.message ?? (json ? "" : raw.slice(0, 500));
+  return {
+    ok: response.ok && (code === null || code === 0),
+    mode: "openapi",
+    status: response.status,
+    code,
+    msg,
+    log_id:
+      response.headers.get("x-tt-logid") ||
+      response.headers.get("x-request-id") ||
+      json?.log_id ||
+      json?.data?.log_id,
+    token_source: tokenSource,
+    request: {
+      method: method.toUpperCase(),
+      url: url.toString(),
+      body: hasBody ? truncateDeep(body, 4000) : undefined,
+    },
+    data: json?.data !== undefined ? truncateDeep(json.data) : undefined,
+    body: json ? truncateDeep(json) : raw.slice(0, 12_000),
+    raw_bytes: Buffer.byteLength(raw),
+    elapsed_ms: Date.now() - t0,
+  };
+}
+
+export function tokenStatus() {
+  const tokens = loadTokens();
+  return Object.values(tokens).map((token) => ({
+    app_id: token.app_id,
+    expires_at: new Date(token.expires_at).toISOString(),
+    valid: token.expires_at > Date.now(),
+    source: token.source,
+  }));
+}

package/src/protocol/catalog.js

@@ -0,0 +1,146 @@
+import { readFileSync } from "node:fs";
+import { createRegistry } from "./schema.js";
+
+const COMMANDS_FILE = new URL("./data/commands.json", import.meta.url);
+
+const CONTROL = new Set([
+  "ACK",
+  "PING",
+  "CONNECT",
+  "DISCONNECT",
+  "SERVER_DISCONNET",
+  "SYNC_PACKETS",
+  "SYNC_REQUEST",
+  "SYNC_RESPONSE",
+  "PROCESS_MULTI_PACKETS",
+  "NO_TRACE_REMOVE_MESSAGE_BY_ID",
+  "NOOP",
+]);
+
+let cachedCatalog;
+
+function classify(entry, enumName) {
+  const name = (enumName || entry.name || "").toUpperCase();
+  const requestType = (entry.requestType || "").toLowerCase();
+  const responseType = (entry.responseType || "").toLowerCase();
+  if (
+    name.startsWith("PUSH_") ||
+    name.includes("PUSH") ||
+    requestType.includes("push") ||
+    responseType.includes("push")
+  ) {
+    return "push";
+  }
+  if (CONTROL.has(name) || name.startsWith("SYNC_")) return "control";
+  if (!entry.requestType) {
+    if (responseType.includes("ack") || name.endsWith("_ACK")) return "control";
+    return "push";
+  }
+  if (
+    entry.requestType &&
+    entry.responseType &&
+    requestType !== responseType
+  ) {
+    return "request";
+  }
+  return "push";
+}
+
+export function loadCatalog() {
+  if (cachedCatalog) return cachedCatalog;
+  const raw = JSON.parse(readFileSync(COMMANDS_FILE, "utf8"));
+  const registry = createRegistry();
+  const commandEnum = registry.lookup("improto.Command");
+  const enumNames = new Map();
+  if (commandEnum?.values) {
+    for (const [name, value] of Object.entries(commandEnum.values)) {
+      enumNames.set(value, name);
+    }
+  }
+  const entries = raw.map((command) => {
+    const enumName = enumNames.get(command.value);
+    const name =
+      command.version !== undefined
+        ? command.name || enumName
+        : enumName || command.name;
+    const kind = classify(
+      command,
+      command.version !== undefined ? undefined : enumName,
+    );
+    const probeType = command.requestType || command.responseType;
+    return {
+      cmd: command.value,
+      name: name || "",
+      requestType: command.requestType || "",
+      responseType: command.responseType || "",
+      version: command.version,
+      kind,
+      schemaAvailable: probeType ? registry.has(probeType) : false,
+      source: command.source || "",
+    };
+  });
+  entries.sort(
+    (a, b) => a.cmd - b.cmd || a.name.localeCompare(b.name),
+  );
+  cachedCatalog = {
+    entries,
+    byValue: new Map(entries.map((entry) => [entry.cmd, entry])),
+    byName: new Map(),
+    byType: new Map(),
+  };
+  for (const entry of entries) {
+    if (entry.name) {
+      const list = cachedCatalog.byName.get(entry.name) || [];
+      list.push(entry);
+      cachedCatalog.byName.set(entry.name, list);
+    }
+    if (entry.requestType) {
+      const list = cachedCatalog.byType.get(entry.requestType) || [];
+      list.push(entry);
+      cachedCatalog.byType.set(entry.requestType, list);
+    }
+  }
+  return cachedCatalog;
+}
+
+export function listApis(kind) {
+  const { entries } = loadCatalog();
+  return kind ? entries.filter((entry) => entry.kind === kind) : [...entries];
+}
+
+export function findApiByValue(cmd) {
+  return loadCatalog().byValue.get(Number(cmd));
+}
+
+export function findApisByName(name) {
+  return loadCatalog().byName.get(name) || [];
+}
+
+export function findApisByType(typeName) {
+  return loadCatalog().byType.get(typeName) || [];
+}
+
+export function resolveApi(cmdOrName) {
+  if (typeof cmdOrName === "number" || /^\d+$/.test(String(cmdOrName))) {
+    return findApiByValue(Number(cmdOrName));
+  }
+  return (
+    findApisByName(String(cmdOrName))[0] ||
+    findApisByType(String(cmdOrName))[0]
+  );
+}
+
+export function summarize() {
+  const entries = listApis();
+  const byKind = {};
+  let schemaAvailable = 0;
+  for (const entry of entries) {
+    byKind[entry.kind] = (byKind[entry.kind] || 0) + 1;
+    if (entry.schemaAvailable) schemaAvailable++;
+  }
+  return { total: entries.length, byKind, schemaAvailable };
+}
+
+export function catalogDataFile() {
+  return COMMANDS_FILE.pathname;
+}

package/src/protocol/data/README.md

@@ -0,0 +1,15 @@
+# Protocol data snapshots
+
+These are **data**, not executable code from the reference projects:
+
+| 文件 | 来源 | 用途 |
+| --- | --- | --- |
+| `commands.json` | 客户端 jssdk worklet 命令注册表（2020 条） | cmd / requestType / responseType / version / name |
+| `bundle.json` | 客户端 protobuf bundle（protobufjs JSON root） | 补充原生 desc 缺失的类型 |
+| `schema.json.gz` | 由 `bundle.json` + 客户端 `pb.desc` / `pb_server.desc` 合并生成 | 无 deb 运行时的完整 schema 兜底 |
+| `constants.json` | 网页版 WS 握手公开常量 | appKey / salt / URL / SDK version |
+| `reference/PROTOCOL.md` | 逆向协议笔记 | 协议文档索引 |
+| `reference/endpoints.json` | 客户端网关/卡片端点笔记 | 端点与默认请求头 |
+
+`src/protocol/descriptor.js` 是 larkit 自己的 FileDescriptorSet parser；
+`src/protocol/schema.js` 负责把上述 JSON 合并成 protobufjs registry。