larkit 0.0.0-stage → 0.1.0

package/src/protocol/data/constants.json

@@ -0,0 +1,8 @@
+{
+  "webAppKey": "5f45da0e6c7a17dcba80494ef0ab9b21",
+  "accessKeySalt": "f8a69f1719916z",
+  "baseUrl": "wss://msg-frontier.feishu.cn/ws/v2",
+  "ticketUrl": "https://login.feishu.cn/suite/passport/frontier_ticket/",
+  "sdkVersion": "7.68.5",
+  "origin": "https://www.feishu.cn"
+}

package/src/protocol/data/reference/PROTOCOL.md

@@ -0,0 +1,66 @@
+# larkit 协议笔记（逆向自飞书客户端）
+
+> 从 Linux 客户端 `/opt/bytedance/feishu/webcontent/` 提取。用于 headless 客户端 SDK 开发。
+
+## 1. 传输面总览
+
+```
+业务请求 ──┬─ HTTP pb 网关（写操作）── internal-api-lark-api.feishu.cn/im/gateway/
+           ├─ WS frontier 长连接（信令/推送）── cookie 认证 connect
+           └─ 开放 API（JSON）── open.feishu.cn/open-apis/...（应用/用户 token）
+```
+
+## 2. frame / packet 编解码
+
+- **frame**：WS 字节流外层帧（详见 `src/codec/frame.ts`）。
+- **packet**：`improto.Packet`
+  - 字段：`cmd`(命令号)、`cid`(requestId，网关必填，否则 "extract packet fail")、`payloadType`、`payload`、`status`
+  - `payloadType=1(PB2)` 时 `payload` 是业务 protobuf 字节
+  - 网关响应是**裸 packet**（不是 frame 包 packet）
+
+## 3. HTTP pb 网关
+
+- `POST https://internal-api-lark-api.feishu.cn/im/gateway/`
+- `Content-Type: application/x-protobuf`
+- body = `encodePacket({cmd, cid=requestId, payloadType: PB2, payload})`
+- 头：`Cookie`(larkit 登录 cookie) + `gatewayHeaders()` 全套（见 endpoints.json）
+- 命令级版本：`x-command-version` / `x-web-version`（见 endpoints.json.commandWebVersions）
+
+### 已验证路由
+| cmd | 名称 | 结果 |
+|---|---|---|
+| 5 | PUT_MESSAGE | ✅ 发文本/richText 卡片 |
+| 13 | PUT_CHAT | ✅ 建群 |
+| 7004/7025/7026 | 卡片相关 | ⚠️ 网关接受，wire 组错时报 "PB payload unmarshal failed" |
+
+### 不路由（读操作）
+- 1 MGET_MESSAGES / 7 PULL_CHAT_MESSAGES / 33 PULL_RECENT_CHATS / 1020 GET_CHAT_MESSAGES
+- 报 `command: N not found` 或 fallback 到 `PullFeedGroups invalid request`
+- **结论：读消息走开放 API 或网页版另一个 HTTP 通道，不在此 pb 网关**
+
+## 4. WS frontier 长连接
+
+- 实现见 `src/connect.ts`（逆向移植网页版 cookie 认证建连）
+- cookie 登录后 connect，绑定 `LarkClient`
+- **当前只收信令/设备状态**（7001/7017/6000/1105079），**不收 PUSH_MESSAGES(6)/5053**
+- 网页版消息推送走另一条通道（待挖）
+
+## 5. 消息 / 卡片
+
+- `entities.Message.Type`：TEXT=4，CARD=14
+- `entities.CardContent.Type`：UNKNOWN=0 / VOTE=1 / TEXT=2 / VCHAT=3 / **OPEN_CARD=4**
+- 个人账号 PUT_MESSAGE：type=14 + `Content{cardType, richText}` 可发 richText 元素卡片（BUTTON/MARKDOWN/DIV/...）；open-card(4) 发不了（系统错误）
+- 开放 API 发 open-card（schema 2.0）成功；PATCH `/open-apis/im/v1/messages/{om_xxx}` 更新卡片成功
+
+## 6. 卡片交互 actionv2
+
+- 端点：`POST https://internal-api.feishu.cn/lark/card/api/actionv2`（v2_2，cookie 认证）
+- body 见 `endpoints.json.actionCardActionV2Body`
+- **三个关键参数 `card_id / action_id / refresh_token` 由服务端在卡片消息推送的 `cardEntity` 里下发**
+- 推送通道（PUSH_MESSAGES 6）当前 SDK 收不到 → 端到端点击验证待打通读消息链路
+
+## 7. 凭证
+
+- 用户 cookie：`larkit auth cookie`（`~/.larkit/credentials.json`）
+- 应用：`cli_aa69ba6ab1389ce2`，tenant_access_token 走 `/open-apis/auth/v3/tenant_access_token/internal`
+- 开放 API 读群消息需 scope `im:message.group_msg`（当前未授权）

package/src/protocol/data/reference/endpoints.json

@@ -0,0 +1,46 @@
+{
+  "_source": "飞书 Linux 客户端 webcontent/jssdk（worklet 信令层）运行时配置提取 + 实测验证",
+  "gateway": {
+    "fetchURL": "https://internal-api-lark-api.feishu.cn/im/gateway/",
+    "transport": "POST application/x-protobuf",
+    "body": "improto.Packet{cmd, cid=requestId, payloadType=PB2(=1), payload=业务 proto 字节}",
+    "note": "只路由 PUT 类写命令（5/13/7004/7025/7026 等）；PULL/GET/MGET 读命令（1/7/33/1020）不路由或 fallback 到 PullFeedGroups"
+  },
+  "internalApi": "https://internal-api.feishu.cn",
+  "openApi": "https://open.feishu.cn",
+  "ticketURL": "https://{passportHost}/suite/passport/frontier_ticket/",
+  "webClient": "https://www.feishu.cn/messenger",
+  "actionCardApis": {
+    "v2_0": "https://{openHost}/open-apis/api/v2/message/action",
+    "v2_1": "https://{openHost}/open-apis/card/api/actionv2",
+    "v2_2": "https://internal-api.feishu.cn/lark/card/api/actionv2",
+    "v3": "https://{openHost}/open-apis/message/v3/action",
+    "vote": "https://{openHost}/lark-vote/Vote"
+  },
+  "actionCardActionV2Body": {
+    "common": { "uid": "<用户数字uid>", "mid": "<消息数字id>", "card_id": "<卡片数字id>" },
+    "action": {
+      "creator_tenant_id": "<卡片创建者租户数字id>",
+      "action_id": "act_v1_<...>",
+      "refresh_token": "<uuid>",
+      "card_schema": "1"
+    },
+    "note": "card_id/action_id/refresh_token 由服务端在卡片消息推送（PUSH_MESSAGES 6）的 content.cardEntity 里下发"
+  },
+  "commandWebVersions": {
+    "_note": "x-command-version 命令级覆盖；默认 DEFAULT_WEB_VERSION=7.61.0",
+    "5": "7.67.0",
+    "13": "2.7.0",
+    "105": "7.69.0",
+    "11021": "2.7.0",
+    "11106": "7.60.0"
+  },
+  "defaultGatewayHeaders": {
+    "x-appid": "161471",
+    "x-lgw-os-type": "3",
+    "x-lgw-terminal-type": "2",
+    "x-lgw-req-sdk-type": "220",
+    "x-lsc-bizid": "1",
+    "x-lsc-version": "1"
+  }
+}

package/src/protocol/descriptor.js

@@ -0,0 +1,358 @@
+/**
+ * FileDescriptorSet -> protobufjs-compatible JSON root.
+ *
+ * This is larkit's own parser.  It only reads descriptor bytes that the Feishu
+ * client ships (pb.desc / pb_server.desc); it does not import any SDK code.
+ */
+
+const TYPE_MESSAGE = 11;
+const TYPE_ENUM = 14;
+
+const SCALAR = {
+  1: "double",
+  2: "float",
+  3: "int64",
+  4: "uint64",
+  5: "int32",
+  6: "fixed64",
+  7: "fixed32",
+  8: "bool",
+  9: "string",
+  10: "group",
+  11: "message",
+  12: "bytes",
+  13: "uint32",
+  14: "enum",
+  15: "sfixed32",
+  16: "sfixed64",
+  17: "sint32",
+  18: "sint64",
+};
+
+class Reader {
+  constructor(input) {
+    this.buf =
+      input instanceof Uint8Array ? input : new Uint8Array(input);
+    this.pos = 0;
+  }
+
+  get eof() {
+    return this.pos >= this.buf.length;
+  }
+
+  readVarint() {
+    let result = 0n;
+    let shift = 0n;
+    while (this.pos < this.buf.length) {
+      const byte = this.buf[this.pos++];
+      result |= BigInt(byte & 0x7f) << shift;
+      if ((byte & 0x80) === 0) return result;
+      shift += 7n;
+      if (shift > 70n) throw new Error("varint too long");
+    }
+    throw new Error("truncated varint");
+  }
+
+  readTag() {
+    if (this.eof) return null;
+    const value = Number(this.readVarint());
+    return { field: value >>> 3, wireType: value & 7 };
+  }
+
+  readBytes() {
+    const length = Number(this.readVarint());
+    if (length < 0 || this.pos + length > this.buf.length) {
+      throw new Error("truncated length-delimited field");
+    }
+    const out = this.buf.subarray(this.pos, this.pos + length);
+    this.pos += length;
+    return out;
+  }
+
+  readString() {
+    return new TextDecoder().decode(this.readBytes());
+  }
+
+  skip(wireType) {
+    if (wireType === 0) {
+      this.readVarint();
+    } else if (wireType === 1) {
+      this.pos += 8;
+    } else if (wireType === 2) {
+      const length = Number(this.readVarint());
+      this.pos += length;
+    } else if (wireType === 5) {
+      this.pos += 4;
+    } else if (wireType === 3) {
+      // group: skip until matching end-group
+      while (!this.eof) {
+        const tag = this.readTag();
+        if (!tag) break;
+        if (tag.wireType === 4) break;
+        this.skip(tag.wireType);
+      }
+    } else if (wireType === 4) {
+      // end-group marker; caller handles
+    } else {
+      throw new Error(`unsupported wire type ${wireType}`);
+    }
+    if (this.pos > this.buf.length) throw new Error("truncated field");
+  }
+}
+
+function lowerCamel(name) {
+  return String(name).replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+
+function parseFieldProto(bytes) {
+  const reader = new Reader(bytes);
+  const field = { name: "", number: 0, label: 0, type: 0 };
+  let tag;
+  while ((tag = reader.readTag()) !== null) {
+    if (tag.field === 1 && tag.wireType === 2) field.name = reader.readString();
+    else if (tag.field === 3 && tag.wireType === 0)
+      field.number = Number(reader.readVarint());
+    else if (tag.field === 4 && tag.wireType === 0)
+      field.label = Number(reader.readVarint());
+    else if (tag.field === 5 && tag.wireType === 0)
+      field.type = Number(reader.readVarint());
+    else if (tag.field === 6 && tag.wireType === 2)
+      field.typeName = reader.readString();
+    else if (tag.field === 7 && tag.wireType === 2)
+      field.defaultValue = reader.readString();
+    else if (tag.field === 8 && tag.wireType === 2) {
+      const options = new Reader(reader.readBytes());
+      let optionTag;
+      while ((optionTag = options.readTag()) !== null) {
+        if (optionTag.field === 1 && optionTag.wireType === 0) {
+          field.packed = Number(options.readVarint()) === 1;
+        } else {
+          options.skip(optionTag.wireType);
+        }
+      }
+    } else if (tag.field === 10 && tag.wireType === 2)
+      field.jsonName = reader.readString();
+    else reader.skip(tag.wireType);
+  }
+  return field;
+}
+
+function parseEnumProto(bytes) {
+  const reader = new Reader(bytes);
+  const out = { name: "", values: [] };
+  let tag;
+  while ((tag = reader.readTag()) !== null) {
+    if (tag.field === 1 && tag.wireType === 2) {
+      out.name = reader.readString();
+    } else if (tag.field === 2 && tag.wireType === 2) {
+      const valueReader = new Reader(reader.readBytes());
+      let name;
+      let number = 0;
+      let valueTag;
+      while ((valueTag = valueReader.readTag()) !== null) {
+        if (valueTag.field === 1 && valueTag.wireType === 2) {
+          name = valueReader.readString();
+        } else if (valueTag.field === 2 && valueTag.wireType === 0) {
+          number = Number(valueReader.readVarint());
+        } else {
+          valueReader.skip(valueTag.wireType);
+        }
+      }
+      if (name) out.values.push({ name, number });
+    } else {
+      reader.skip(tag.wireType);
+    }
+  }
+  return out;
+}
+
+function parseDescriptorProto(bytes) {
+  const reader = new Reader(bytes);
+  const out = {
+    name: "",
+    fields: [],
+    nested: [],
+    enums: [],
+    mapEntry: false,
+  };
+  let tag;
+  while ((tag = reader.readTag()) !== null) {
+    if (tag.field === 1 && tag.wireType === 2) {
+      out.name = reader.readString();
+    } else if (tag.field === 2 && tag.wireType === 2) {
+      out.fields.push(parseFieldProto(reader.readBytes()));
+    } else if (tag.field === 3 && tag.wireType === 2) {
+      out.nested.push(parseDescriptorProto(reader.readBytes()));
+    } else if (tag.field === 4 && tag.wireType === 2) {
+      out.enums.push(parseEnumProto(reader.readBytes()));
+    } else if (tag.field === 7 && tag.wireType === 2) {
+      const options = new Reader(reader.readBytes());
+      let optionTag;
+      while ((optionTag = options.readTag()) !== null) {
+        if (optionTag.field === 7 && optionTag.wireType === 0) {
+          out.mapEntry = Number(options.readVarint()) === 1;
+        } else {
+          options.skip(optionTag.wireType);
+        }
+      }
+    } else {
+      reader.skip(tag.wireType);
+    }
+  }
+  return out;
+}
+
+function parseFileDescriptorProto(bytes) {
+  const reader = new Reader(bytes);
+  const file = { name: "", package: "", messages: [], enums: [] };
+  let tag;
+  while ((tag = reader.readTag()) !== null) {
+    if (tag.field === 1 && tag.wireType === 2) file.name = reader.readString();
+    else if (tag.field === 2 && tag.wireType === 2)
+      file.package = reader.readString();
+    else if (tag.field === 3 && tag.wireType === 2) reader.readString();
+    else if (tag.field === 4 && tag.wireType === 2)
+      file.messages.push(parseDescriptorProto(reader.readBytes()));
+    else if (tag.field === 5 && tag.wireType === 2)
+      file.enums.push(parseEnumProto(reader.readBytes()));
+    else reader.skip(tag.wireType);
+  }
+  return file;
+}
+
+function fieldTypeName(field) {
+  if (field.type === TYPE_MESSAGE || field.type === TYPE_ENUM) {
+    return (field.typeName || "").replace(/^\./, "") || "bytes";
+  }
+  return SCALAR[field.type] || "bytes";
+}
+
+function attach(root, fq, definition) {
+  const parts = fq.split(".").filter(Boolean);
+  let node = root;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i];
+    const nested = node.nested || (node.nested = {});
+    const child = nested[key];
+    if (child && typeof child === "object" && "nested" in child) {
+      node = child;
+    } else if (child && typeof child === "object") {
+      child.nested = child.nested || {};
+      node = child;
+    } else {
+      const next = { nested: {} };
+      nested[key] = next;
+      node = next;
+    }
+  }
+  const last = parts[parts.length - 1];
+  const nested = node.nested || (node.nested = {});
+  nested[last] = definition;
+}
+
+function collectMessage(root, scope, descriptor) {
+  if (descriptor.mapEntry) return;
+  const fq = scope ? `${scope}.${descriptor.name}` : descriptor.name;
+  const node = { fields: {} };
+  attach(root, fq, node);
+
+  for (const field of descriptor.fields) {
+    const key = field.jsonName || lowerCamel(field.name);
+    const def = { type: fieldTypeName(field), id: field.number };
+    if (field.label === 3) def.rule = "repeated";
+    else if (field.label === 2) def.rule = "required";
+    if (field.packed || field.defaultValue !== undefined) {
+      def.options = {};
+      if (field.packed) def.options.packed = true;
+      if (field.defaultValue !== undefined)
+        def.options.default = field.defaultValue;
+    }
+    node.fields[key] = def;
+  }
+
+  // Map entries are represented as nested messages whose parent field points
+  // at the entry type.  Convert them to protobufjs map fields (keyType/type).
+  for (const sub of descriptor.nested) {
+    if (!sub.mapEntry) continue;
+    const keyField = sub.fields.find((field) => field.number === 1);
+    const valueField = sub.fields.find((field) => field.number === 2);
+    if (!keyField || !valueField) continue;
+    const entryFq = `${fq}.${sub.name}`;
+    for (const field of descriptor.fields) {
+      const raw = (field.typeName || "").replace(/^\./, "");
+      if (raw !== entryFq) continue;
+      const key = field.jsonName || lowerCamel(field.name);
+      node.fields[key] = {
+        keyType: fieldTypeName(keyField),
+        type: fieldTypeName(valueField),
+        id: field.number,
+      };
+    }
+  }
+
+  for (const sub of descriptor.nested) {
+    if (!sub.mapEntry) collectMessage(root, fq, sub);
+  }
+  for (const enumDescriptor of descriptor.enums) {
+    const values = {};
+    for (const value of enumDescriptor.values) {
+      values[value.name] = value.number;
+    }
+    attach(root, `${fq}.${enumDescriptor.name}`, { values });
+  }
+}
+
+export function parseFileDescriptorSet(input) {
+  const reader = new Reader(input);
+  const root = { nested: {} };
+  let tag;
+  while ((tag = reader.readTag()) !== null) {
+    if (tag.field === 1 && tag.wireType === 2) {
+      const file = parseFileDescriptorProto(reader.readBytes());
+      for (const message of file.messages) {
+        collectMessage(root, file.package, message);
+      }
+      for (const enumDescriptor of file.enums) {
+        const values = {};
+        for (const value of enumDescriptor.values) {
+          values[value.name] = value.number;
+        }
+        attach(
+          root,
+          file.package
+            ? `${file.package}.${enumDescriptor.name}`
+            : enumDescriptor.name,
+          { values },
+        );
+      }
+    } else {
+      reader.skip(tag.wireType);
+    }
+  }
+  return root;
+}
+
+export function mergeRoots(...roots) {
+  const out = { nested: {} };
+  for (const root of roots) mergeInto(out, root);
+  return out;
+}
+
+function mergeInto(target, source) {
+  const targetNested = target.nested || (target.nested = {});
+  const sourceNested = source?.nested || {};
+  for (const [key, value] of Object.entries(sourceNested)) {
+    const existing = targetNested[key];
+    if (
+      existing &&
+      typeof existing === "object" &&
+      typeof value === "object" &&
+      "nested" in existing &&
+      "nested" in value
+    ) {
+      mergeInto(existing, value);
+    } else {
+      targetNested[key] = value;
+    }
+  }
+}