Commit Graph
1068 Commits
Author SHA1 Message Date
时瑾 ffe0c57abf feat(webui): add SNOWLUMA_WEBUI_TRUST_PROXY for reverse-proxy deploys
The previous commit tightened login rate-limiting to key off the real
TCP socket peer, which fixed the X-Forwarded-For bypass but had the
known caveat of collapsing every client into a single global bucket
when the WebUI runs behind nginx / Caddy / a SaaS CDN.

Give operators an explicit, audited way to opt back into per-client
keying without re-introducing the spoof:

* `SNOWLUMA_WEBUI_TRUST_PROXY` env var. Modes:
    - unset / empty     → keep socket peer (safe default, unchanged)
    - "loopback"        → trust X-Real-IP / X-Forwarded-For when the
                          immediate socket peer is 127.0.0.1 / ::1
                          (nginx + WebUI on the same host)
    - "1" / "true" /    → trust headers from any peer (only safe behind
      "all"               a SaaS proxy that strips client-set headers)
    - comma-separated   → trust headers only when the socket peer
      IP list             matches one of these (proxy on another box)

* When trusting headers we prefer X-Real-IP (single value the proxy
  overwrites unconditionally) and fall back to the first hop of XFF.
  We deliberately do NOT walk the full XFF chain — without a fully
  trusted proxy chain the leftmost value is still spoofable; a
  single-tier proxy is the only setup this app realistically sees.

* Boot log prints "login rate-limit keyed by: …" so operators can
  verify the mode took effect, plus an extra WARN for "all" reminding
  them it's only safe with header-stripping in front.

Logic lives in webui/client-ip.ts as a pure pickClientIp() that takes
a socket-IP resolver, so the trust-proxy matrix can be exercised
without standing up a server — see webui-client-ip.test.ts for the
11 new unit tests covering parse + dispatch + loopback / list / all /
none modes.

Smoke-tested with SNOWLUMA_WEBUI_TRUST_PROXY=loopback:
  - 5× failed login w/ X-Forwarded-For: 1.1.1.1 → 401
  - 6th attempt same XFF → 429 (locked, per-XFF)
  - 6th attempt X-Forwarded-For: 2.2.2.2 → 401 (fresh bucket)
  - X-Real-IP overrides XFF when both present
2026-05-16 21:31:54 +08:00
时瑾 d66f0b2c6b fix(bridge): point at file-upload actions in video-too-large error
QQ's short-video element protocol hard-limits a single video at 100 MB
(NapCat enforces the same cap in highwayContext.uploadVideo with the
same threshold and tells operators to switch to file upload). Mirror
that hint so OneBot bot authors who hit the cap immediately see the
correct alternative — `upload_group_file` / `upload_private_file`,
which ride the FtnUpload path and go up to 4 GiB — instead of having
to read the docs to figure out why a send_msg with a 200 MB video
silently 'won't work'.
2026-05-16 21:31:54 +08:00
时瑾 b40cee18cc fix(bridge): close two binary-size cap gaps flagged by review
Follow-up on the previous highway commit, addressing two real holes the
Copilot review caught:

* loadBinarySource HTTP path was buffering the entire response via
  `await resp.arrayBuffer()` BEFORE length-checking. A server that omits
  or understates `Content-Length` (chunked transfer, malicious upstream,
  proxy stripping headers) bypassed the cap entirely. Switch to a
  streaming reader: accumulate chunks, abort + reject as soon as the
  running total exceeds `maxBytes`. The Content-Length precheck still
  short-circuits the obvious case before we read a byte.
* video-upload `stageVideoSource` has its own local-path fast-path that
  never went through `loadBinarySource`, so the 100 MB MAX_VIDEO_SIZE
  guard ran AFTER `fs.readFileSync` had already allocated the entire
  file. A 10 GiB local-file pointer would OOM the bot before the check
  fired. Add an `fs.statSync` precheck on the local branch, and pass
  `MAX_VIDEO_SIZE` explicitly when the source falls through to
  `loadBinarySource` so the HTTP / base64 cap matches the on-disk one.

Update the DEFAULT_MAX_BINARY_SIZE comment to stop claiming video paths
are bounded by it — they're bounded by the smaller MAX_VIDEO_SIZE,
enforced inside video-upload.

Adds five regression tests:
  - chunked streamed download (no Content-Length) over cap → throws
  - Content-Length over cap → throws before reading body
  - streamed download inside cap → returns full bytes
  - local file over cap (statSync precheck) → throws
  - base64 over cap → throws
2026-05-16 21:31:54 +08:00
时瑾 b3df633c87 fix(bridge): correctness pass on highway, hook, and identity service
* highway/utils detectImageFormat: JPEG SOF marker check now excludes
  0xC4 (DHT), 0xC8 (JPG), and 0xCC (DAC). The old `(marker & 0xFC) ===
  0xC0` matched DHT et al. and then read Huffman table bytes as image
  dimensions, producing junk width/height for many real JPEGs.
* loadBinarySource takes an optional maxBytes; defaults to 1 GiB to
  defend against an authenticated client triggering a multi-GB load
  into memory. Group/private file uploads pass FILE_UPLOAD_MAX_BYTES
  (4 GiB) because QQ's file protocol legitimately supports that size.
  HTTP fetches also pick up a 60s timeout and a Content-Length precheck.
* highway-client.tcpConnect detaches its error/timeout listeners after
  a successful connect so subsequent upload IO errors don't reject an
  already-resolved promise. readHttpResponseBody uses local listener
  refs + a central detach(), eliminating MaxListenersExceededWarning
  during multi-chunk uploads.
* hook/qq-hook-client.nextRequestId now wraps inside uint32 explicitly
  and skips id 0 / in-flight ids. The previous `nextRequestId++ >>> 0`
  loses precision past Number.MAX_SAFE_INTEGER (postfix increment
  evaluates before the shift) and could collide live request ids on
  very long-running processes.
* identity-service.rememberUidUin removes stale partner entries before
  inserting a new (uid, uin) pair. The old code left orphan uidByUin /
  uinByUid entries after a uid/uin re-bind, so the two maps could
  disagree.
2026-05-16 21:31:54 +08:00
时瑾 b2c53b56f7 fix(onebot): correctness pass on actions and message parser
Action-layer fixes, all cross-checked against NapCat's reference
implementation in packages/napcat-onebot:

* download_file (extended.ts:539) now sanitizes `name` via
  path.basename + resolve/relative containment check. Previously an
  authenticated client could write `../../config/onebot_<uin>.json`
  and replace access tokens / webhook URLs.
* mark_group_msg_as_read / mark_private_msg_as_read / mark_msg_as_read
  fall back to meta.targetId when the optional group_id/user_id arg
  is missing. The old code passed 0 to the Bridge. NapCat resolves the
  peer from message_id alone in MarkMsgAsRead.ts; we now match that.
* set_friend_remark / set_group_remark refuse a missing `remark` field.
  The previous `asString(...) ?? ''` silently CLEARED the remark for
  any client that forgot the parameter. NapCat's typebox schema makes
  `remark` required; we now do the same.
* upload_forward_msg threads `group_id` down to uploadForwardNodes so
  the resulting resId lives in the correct namespace (type:3 + groupUin
  vs type:1 + selfUid — see bridge/actions/forward.ts). NapCat passes
  `peer.chatType === GROUP ? +peerUid : 0` for the same reason.
  ApiActionContext.sendForwardMsg + uploadForwardMessage signatures
  pick up an optional groupId.
* Private-message reply meta now resolves senderUin from the cached
  event (real sender), with a self-id fallback when only meta exists
  (bot's own outbound message — `cacheMessageMeta` does not populate
  the event row). The old code used meta.targetId, which is the
  conversation peer — wrong when the bot replies to its own message.
* message-parser:
    - intOr(value, fallback) helper replaces parseInt(String(...)) at
      face/at/reply/image/xml/poke/node sites so non-numeric input no
      longer produces NaN downstream. Invalid face ids skip the
      element rather than emit NaN.
    - cqUnescape decodes `&#44;` (escaped comma) — the OneBot 11 spec
      requires it and clients in the wild emit it.
* Drop the dead Array.isArray(rawAuth) branch in onebot/network/utils
  (Node's headers.authorization is `string | undefined`, never an
  array) and the unused WebHonorType import in api-handler.
2026-05-16 21:31:34 +08:00
时瑾 917f08ce4d fix(webui): tighten auth handling and remove read-side write effects
Stack of WebUI fixes prompted by an internal security/correctness pass:

* getClientIp now resolves the real socket peer via @hono/node-server's
  getConnInfo helper instead of trusting `X-Forwarded-For`. The previous
  behaviour let any client rotate that header to bypass the 5-attempts/
  15-minute login lockout.
* `?token=` is restricted to /api/logs/stream (the only endpoint that
  can't use the Authorization header, because EventSource lacks custom
  headers). Other routes used to leak tokens via access logs / Referer
  / browser history.
* change-password now invalidates every session (including the current
  one) and signals requireRelogin. Keeping the current token alive made
  the rotation pointless if the old credentials were already in an
  attacker's hands.
* GET /api/config/:uin no longer writes defaults to disk and no longer
  doubles up the payload (`{config}` only, dropping the {…config, config}
  legacy shape). Frontend's `data?.config ?? data` fallback still works.
* webui.json is moved to .bak.<ts> instead of being silently overwritten
  when it fails to parse — losing the prior hash silently was rotating
  operator credentials with no warning.
* Process load/unload/refresh routes are deduped into a single helper;
  internal error messages are logged but no longer surfaced verbatim to
  the client.
* SSE log stream tolerates a closed controller (try/catch around enqueue
  + central teardown) and runs an unref'd janitor to GC expired session
  tokens + login attempt counters every minute.
2026-05-16 21:31:28 +08:00
时瑾 2c80e1a267 refactor(onebot): make loadOneBotConfig read-only by default
GET on a load helper used to mint a fresh access_token and write it to
disk whenever the per-UIN file was missing or in legacy format. Reading
should not have side effects, and the WebUI's read-only GET handler in
particular was racing on concurrent requests and surprising operators
with materialized config files.

Introduce a `{ persistDefaults?: boolean }` option (default false). The
two boot-time call sites in `OneBotManager` (onSessionStarted, reloadConfig)
opt in explicitly; WebUI's GET path will rely on the new default once
that side of the patch lands.

Also stop reviving default 0.0.0.0 listeners when the operator has
explicitly emptied every adapter — only seed defaults on a true fresh
install (no per-uin and no global config on disk).

Drop the unused deepClone / deepMerge helpers; tryLoadJson now logs a
warning instead of silently swallowing JSON parse errors.
2026-05-16 21:31:28 +08:00
时瑾 655af833dc fix(send): keep c2c video compatQMsgSceneType at 2 (#38)
Commit 29f28d6 changed c2c video `compatQmsgSceneType` from 2 to 1
as a "symmetric asymmetry" cleanup, matching the image/ptt convention
where the field tracks the upload's sceneType (c2c=1, group=2). For
video this is wrong.

Image and ptt have *different* legacy compat elements per scene
(notOnlineImage vs customFace; ptt c2c vs group), so the server needs
to know which scene shape to emit. The legacy `videoFile` element
(packet element type 19) has no scene split — fromChatType /
toChatType live inside the element itself — so the QQ NT server
emits a single group-shaped compat payload regardless. NapCat
hardcodes `compatQMsgSceneType: 2` for *both* UploadGroupVideo and
UploadPrivateVideo for exactly this reason.

Setting it to 1 on c2c made the server emit a c2c-scene shaped
compat blob that older QQ clients failed to resolve, showing the
message as "视频已过期" on those receivers. Newer clients only read
the commonElem(48, 11) and displayed fine — which is why only "some
devices" saw the breakage.

Keep `commonElem.businessType = isGroup ? 21 : 11` untouched — that
piece of 29f28d6 is still correct and is what fixed PbSendMsg
result=79.
2026-05-16 14:51:13 +08:00
H3CoF6 e2ee528939 fix: address P0 and P1 issues from code review
- P0-1: restore customExt field in SetStatusReqSchema
- P0-2: remove duplicate setGroupAvatar implementation
- P1-3: add attach_info pagination support for get_group_album_media_list
- P1-5: clean up commented console.log statements
- P1-6: remove raw field from GroupAlbumMediaResult
2026-05-16 14:33:42 +08:00
H3CoF6 c58f4d4085 fix: fix group album upload error 2026-05-16 13:34:02 +08:00
H3CoF6 16bdf1be1e Fix merge conflict and remove one group avatar implement 2026-05-16 12:39:00 +08:00
H3CoF6 0401ac4afb feat: implement some group album actions 2026-05-16 12:17:23 +08:00
DrSmoothl ad65aa5b1b fix(send): resolve at-mention display name from the group roster
OneBot clients commonly send [CQ:at,qq=12345] without a name field; we
were piping `@12345` into the text element so QQ rendered the bare uin
instead of the member's card/nickname (napcat resolves via getGroupMember
before encoding). Move the fallback into the element builder so it
consults the IdentityService roster and only falls back to the uin when
the roster has nothing.
2026-05-16 11:55:36 +08:00
DrSmoothl a1a49944df refactor(webui): migrate routing to TanStack Router
The four-page switch lived as a string union (Page) plus an if/else
chain in AppInner, with TopBar reverse-importing Sidebar's NAV_ITEMS
to find the icon for the active tab. Adding a page touched four
places and there was no URL, no history, no deep-linking.

Move routing behind @tanstack/react-router with a layout route
(AppLayout) that owns the polling lists, processOps, selectedUin
and the unload-failed alert; child routes render through <Outlet/>
and read shared state from a new AppStateContext. AuthBoundary still
gates login / forced-password-change above the router. Sidebar uses
<Link> + useRouterState for active state; TopBar and MainLayout look
up the current path the same way.

Behaviour-preserving:
- LoginPage / ChangePasswordPage still mount above the router.
- AppLayout never unmounts during navigation, so selectedUin,
  processOps state, the polling state and the unload-failed dialog
  all survive page switches just like before.
- Logout calls history.replaceState('/') so the next login lands on
  the overview page, matching pre-router behaviour.
- The sidebar-active-pill layoutId animation and the page-transition
  AnimatePresence are preserved, keyed off pathname instead of the
  removed `active` prop.

New URLs (/, /config, /logs, /settings) work on refresh because the
backend already had SPA fallback in core/src/webui/server.ts. Bundle
grows ~84KB (gzip +27KB) for the router runtime.
2026-05-16 02:35:49 +08:00
DrSmoothl caf724b25c fix(webui): preserve config edits on save and UIN choice across tabs
Two regressions slipped into the ApiClient/ConfigPage refactor:

1. api.config.save() ran the POST response through normalizeOneBotConfig
   and used it to overwrite local state. But POST /api/config/:uin
   returns { success, reloaded, message } — no config body — so the
   normaliser produced an empty config and wiped the user's edits as
   soon as the save succeeded. Honour the "save returns canonical view"
   contract by following the POST with a GET inside the client; the
   round-trip stays hidden behind the seam.

2. selectedUin lived inside useOneBotInstanceConfig, so navigating away
   from ConfigPage unmounted the hook and lost the user's selection.
   Lift selectedUin to AppInner and make the hook externally controlled
   via { selectedUin, onSelectedUinChange }. Clear it on logout.
2026-05-16 02:22:48 +08:00
DrSmoothl 7cef104f93 refactor(webui): deepen Hook process ops behind a single seam
App.tsx held three copy-pasted handlers (load / unload / refresh) and
three parallel processXxxPid state slots that were mutually exclusive
but unenforced by the type system. The unload-failed alert was a
separate path, and OverviewPage needed 11 props to drive the table.

Extract useHookProcessOps: one inflight Set for dedup, one Map<pid,
OpKind> for view state, one run() that branches on kind via a
message table, and ownership of the unload-failed alert. OverviewPage
takes a single HookProcessOps prop and queries statusOf(pid).

App.tsx 270 → 216 LOC; OverviewPage props 11 → 7.
2026-05-16 02:13:09 +08:00
DrSmoothl b89d51d984 refactor(webui): extract ApiClient + lift OneBotInstance config editor
App.tsx was the single source of truth for token, fetch policy, 401
handling, and per-UIN config edit state — fetchApi was drilled into
every page and LogsPage read localStorage directly to build its SSE
URL, giving two parallel truths for the bearer token.

Promote the closure to a deep ApiClient module (domain methods +
request() escape hatch) injected via ApiProvider/useApi, and lift
selectedUin/config/saveStatus into useOneBotInstanceConfig so
ConfigPage is self-contained. normalizeOneBotConfig becomes a pure
function. ConfigPage now guards UIN switches when the editor is
dirty and refetches the server-normalised config after save.

ConfigPage prop count drops from 7 to 1; App.tsx from 421 to 270 LOC.
2026-05-16 02:04:11 +08:00
DrSmoothl 47921eee12 fix(sdk): catch up SNOWLUMA_ACTIONS with the 14 new core actions
`actions-sync.test.ts` walks every `registerAction(...)` in
`@snowluma/core/src/onebot/actions/` and asserts the SDK's exported
list matches. The napcat-parity work (Tier 1 + Tier 2 + Tier 3 + AI
voice) added 14 actions to core without ever touching the SDK, so the
test caught the drift:

  bot_exit              cancel_group_todo
  complete_group_todo   delete_group_folder
  get_ai_characters     get_ai_record
  get_group_ignore_add_request
  nc_get_packet_status  nc_get_rkey
  nc_get_user_status
  send_group_ai_record  send_packet
  set_diy_online_status set_group_todo

Added them to `SNOWLUMA_ACTIONS` and gave each one a typed
`SnowLumaActionMap` entry. Where the request body shape is non-trivial
(AI voice, group todo, DIY status, send_packet, nc_get_user_status),
introduced dedicated param types in `types/params.ts`; where the
response is structured (AI character list, user-status word),
introduced result types in `types/results.ts`. Everything else routes
through `JsonObject` / `EmptyData` so the SDK surface stays small.

Verified:
  pnpm --filter @snowluma/sdk typecheck → clean
  pnpm --filter @snowluma/sdk test      → 17/17 pass
2026-05-16 00:39:32 +08:00
DrSmoothl 7da52bc591 chore(release): v1.8.1 2026-05-15 23:17:44 +08:00
DrSmoothl 29f28d611f fix(send): use c2c businessType for private video / record
Private-chat video and voice sends were getting bounced by the QQ NT
server with `PbSendMsg result=79`. Highway upload logs said success,
but the final SendMsg the bot constructed used the group-scene tag
inside the outgoing commonElem, and the c2c routing path doesn't
recognise it.

The convention — verified against the receive-side decoder at
msg-push/rich-body-decoder.ts:261-330 which explicitly branches on the
pairs — is:

  image  : commonElem.businessType  c2c=10  group=20
  video  : commonElem.businessType  c2c=11  group=21
  record : commonElem.businessType  c2c=12  group=22

makeImageElem already honoured the split (`isGroup ? 20 : 10`).
makeVideoElem and makePttElem hardcoded the group value for both
scenes. Fix them to follow the same pattern.

Also fix a symmetric asymmetry inside the highway upload itself:
uploadVideoMsgInfo hardcoded `compatQmsgSceneType: 2` while
uploadImageMsgInfo and uploadPttMsgInfo both use `isGroup ? 2 : 1`.
Same root cause — group value leaking into the c2c path.

Regression test (tests/element-builder.test.ts) pins all six
businessType pairs by mocking the highway upload functions and
inspecting the proto element the builder returns; would have caught
the bug had it existed at the time element-builder.ts was written.
2026-05-15 22:56:15 +08:00
DrSmoothl 97ad2e22bb feat(onebot): implement set_group_portrait via highway cmdId 3000
Port the Lagrange.Core protocol path for group avatar upload —
napcat's NTQQ GroupService.setHeader has no oidb wrapper, but
Lagrange.Core/Internal/Context/Logic/Implementation/OperationLogic.cs
spells out the wire shape: same highway HTTP endpoint as personal
avatar, but with cmdId=3000 and a GroupAvatarExtra proto carried as
the `extend` blob (type=101, groupUin, field3={field1=1}, field5=3,
field6=1 — all four are protocol-prescribed constants).

Adds:
- GroupAvatarExtraSchema in proto/oidb-action.ts
- bridge.setGroupAvatar(groupId, source) wrapping the highway upload
- BridgeInterface.setGroupAvatar
- OneBot set_group_portrait action (was a stub returning
  'not yet implemented'; accepts the same file-source variants as
  set_qq_avatar)

5 new tests: 3 bridge-action (cmdId, extra-blob round-trip, empty-file
guard) + 2 OneBot (forwarding, param validation) — also tightens the
existing setAvatar test to assert the extend blob stays empty.
2026-05-15 19:47:35 +08:00
DrSmoothl f7457e3e59 feat(onebot): add set_diy_online_status
DIY online status reuses the existing StatusService.SetStatus wire
call. napcat hardcodes status=10 / extStatus=2000 and threads the
faceId / wording / faceType through a customExt sub-message (field 4
of SetStatus, per napcat packet/transformer/proto/action/action.ts).

Implementation:
- Extend SetStatusReqSchema with optional customExt field. Encoder
  skips undefined fields so the existing set_online_status path stays
  byte-identical on the wire (verified by a new round-trip test).
- New bridge.setDiyOnlineStatus(faceId, wording, faceType) wraps the
  same dispatchSetStatus helper as setOnlineStatus.
- OneBot action set_diy_online_status accepts napcat-style payloads
  (face_id / face_type can be string or number; wording defaults to '').

9 new tests across actions/profile and onebot/extended-actions.
2026-05-15 19:26:40 +08:00
DrSmoothl ee62f5aa0b feat(onebot): add napcat-parity actions (Tier 1 + Tier 2)
Wires 16 OneBot actions that napcat exposes but SnowLuma previously
either lacked or stubbed:

Tier 1 (pure glue over existing Bridge capabilities)
- send_packet / .send_packet: real impl over Bridge.sendRawPacket
- bot_exit, nc_get_packet_status, nc_get_rkey
- get_group_ignored_notifies / get_group_ignore_add_request: project
  fetchGroupRequests(filtered=true) into napcat shapes (was empty stub)
- delete_group_folder alias for delete_group_file_folder

Tier 2 (new oidb proto + Bridge method)
- set_/complete_/cancel_group_todo (oidb 0xF90_1/2/3)
- nc_get_user_status (oidb 0xFE1_2 with napcat's status decode)
- get_ai_characters / get_ai_record / send_group_ai_record (oidb
  0x929D / 0x929B; AI voice reuses the existing fetchGroupPttUrlByNode)

BridgeInterface now exposes sendRawPacket as the deliberate escape
hatch for send_packet — every other surface method already wraps it.

46 new tests: 13 bridge-action (mocked runOidb dispatch checks) + 33
OneBot-action (ApiHandler.handle end-to-end).
2026-05-15 19:22:35 +08:00
DrSmoothl 78d42029ba test(hook): guard against per-reconnect leak when QQ never logs in
50 onPipeUp/onPipeDown cycles → at most 1 live FakeClient, zero
listeners on every torn-down client. E2E variant additionally asserts
BridgeManager.onHookLogin / onPidDisconnected / onPacket are never
called, so no Bridge / Identity / OneBotInstance is allocated.

These prove no leak exists at this layer. Investigated after a Docker
OOM report which turned out to be QQ Browser GC-thrashing while idle on
the login screen (75-second LongTask entries from PID 61 in the report).
2026-05-15 15:03:00 +08:00
DrSmoothl 6b236f70bf refactor(bridge): split MsgPush handler into per-PkgType decoders
The 885-line msg-push-handler.ts is replaced by bridge/msg-push/:
8 per-PkgType decoders plus MsgPushRegistry (single decoder per
PkgType, catch + log on error), MsgPushContext (header decoded
once at entry), and rich-body-decoder (one deep function hides
~400 lines of element conversion shared by all three message
types).

parseMsgPush(pkt, identity) signature preserved; existing tests
pass with an import-path change only.
2026-05-15 14:32:34 +08:00
DrSmoothl 1a072bc6f1 refactor(utils): consolidate uppercase hex into toHexUpper
Adds toHexUpper alongside toHex in utils/hex.ts. Routes
group-file's bytesToHexUpper through it so the incoming
msg-push split can share one implementation.
2026-05-15 14:29:44 +08:00
DrSmoothl 85b59bc3a1 chore(release): v1.8.0 2026-05-15 01:47:06 +08:00
DrSmoothl 7f53bcd085 refactor(onebot): drop pure pass-through closures from ApiActionContext
instance-context.ts used to declare ~130 closures inside buildApiContext,
mirrored by ~130 method signatures on ApiActionContext. About 38 of
those were pure 1:1 pass-throughs — `setGroupAdmin: (gid, uid, en) =>
bridge.setGroupAdmin(gid, uid, en)`, `setOnlineStatus`, `setProfile`,
`setAvatar`, `markGroupMsgAsRead`, `getCookiesStr`, `getCsrfToken`,
`getCredentials`, the lot of them. Each was three places to edit (the
closure, the interface signature, the action call site) and zero added
value: the OneBot name matched the Bridge name and no defaults / rename
/ composition was happening.

Expose `bridge: BridgeInterface` on ApiActionContext and have action
handlers route through `ctx.bridge.<name>` for those cases. The 38
closure declarations go away; ApiActionContext shrinks from ~70 method
signatures to ~30; instance-context.ts loses ~50 lines of boilerplate.

The ~30 adapter closures stay — every one of them does real work:
  - Renames: setGroupKick → bridge.kickGroupMember, sendFriendPoke →
    bridge.sendPoke(false, …), handleDeleteFriend → bridge.deleteFriend
  - Field extraction: uploadGroupFile returns result.fileId, not the
    full {fileId} envelope
  - Baked constants: setEssenceMsg passes `true`, deleteEssenceMsg
    passes `false` to the shared setEssenceMessage module function
  - Compositions: sendPrivateMessage / sendGroupMessage / setMsgEmojiLike
    need messageStore + mediaStore + bridge wired together
  - OneBot-specific defaults: getProfileLike defaults start=0 limit=10,
    getGroupEssence defaults pageStart=0 pageLimit=50

Two small downstream nudges that fell out of the type changes:
  - extended.ts:99 — `essenceDataAll.flatMap(res => …)` now needs an
    explicit `(res: any)` since bridge.getGroupEssenceAll returns
    `Promise<any>`, not the previously-asserted `GroupEssenceMsgRet[]`.
  - extended.ts:835 — `okResponse(clientKeyInfo)` widened via spread to
    `okResponse({ ...clientKeyInfo })` because `ClientKeyInfo` is a
    named interface (no index signature) and okResponse expects
    JsonValue/JsonObject. Behavior identical; the response shape is
    unchanged.

402 tests pass (the OneBot contact-actions test added in PR6 doubles as
regression coverage for the seam).
2026-05-15 01:38:11 +08:00
DrSmoothl 29fa2696c8 test(onebot): exercise contact-actions through a fake BridgeInterface
First OneBot unit test that proves the BridgeInterface seam (PR4)
delivers real testability. The fake bridge is a Proxy over a tiny
override map — un-stubbed methods throw with a clear message, so each
test only spells out the surface it actually exercises, and a missing
stub never silently passes.

Covers the five contact-actions read paths users hit most through the
OneBot API: getLoginInfo / getFriendList / getGroupList / getGroupInfo
/ getGroupMemberList / getGroupMemberInfo / getStrangerInfo — 19 cases
spanning happy path, network-fail fallback to identity cache,
noCache=true forcing a refetch, and missing-data nulls. No SQLite, no
native packet sender, no BridgeManager — just BridgeInterface.
2026-05-15 01:28:37 +08:00
DrSmoothl 37140b4ddd refactor(bridge): extract IncomingPacketPipeline as a deep module
Bridge.onPacket previously inlined 5 distinct responsibilities (cmd
dispatch, identity-refresh decision, async member-roster refresh,
side-effect persistence, event emission) plus all the helper state
(cmdHandlers_, memberRefreshTasks_) and the per-event printer. Move
the whole stage chain into bridge/packet-pipeline.ts as
IncomingPacketPipeline, keeping the orchestration single-owned and
testable without booting Bridge.

The pipeline's public surface is three methods — registerCmd /
handlesCmd / process — plus a single constructor dep bag. Internally
the stage order is exactly as before:

  parse  →  enrich identity (sync, or async refresh)
         →  side-effects (rememberX on Identity + coalesced roster refresh)
         →  log
         →  emit on the typed event bus

Bridge keeps the protocol-layer methods (sendRawPacket,
fetchGroupList, fetchGroupMemberList, etc.) and injects
refreshMemberCache as the one pipeline dep that touches the wire.
Bridge.onPacket / registerCmd / handlesCmd are now thin pass-throughs
so the existing external test (RefreshingBridge extends Bridge,
bridge.onPacket(makePacket()) → expects forced member fetch) keeps
working unchanged.

Net diff: bridge.ts shrinks by ~245 lines; packet-pipeline.ts is
~225 lines; one dead helper (elementsToText) deleted on the way out.
Runtime behavior is byte-identical — verified by tests/bridge-member-identity.test.ts
covering the full async-refresh path.
2026-05-15 01:21:56 +08:00
DrSmoothl e6b609dd4e refactor(bridge): extract BridgeInterface as the OneBot-facing seam
OneBot used to depend on the concrete Bridge class — 778 lines, ~99
public methods including PID management, raw packet dispatch, and cmd
handler registration that no external consumer should touch. Add an
explicit BridgeInterface (bridge/bridge-interface.ts) enumerating only
the surface OneBot actually reads (verified by grepping every bridge.*
access in onebot/), and have Bridge `implements BridgeInterface` so the
compiler enforces alignment.

Net effect at runtime: zero — Bridge's methods, fields, and bodies are
unchanged; the interface is a TypeScript-only declaration. Net effect
for typing: the OneBot package (instance, instance-context,
instance-rkey, manager, media-url-resolver, and the modules under
onebot/modules/) now imports `BridgeInterface` instead of `Bridge`, so
tests / fakes can satisfy the interface without subclassing or pulling
in the SQLite/native bits.

In-tree bridge actions (actions/*, bridge-contacts, highway) keep their
concrete `Bridge` typing — they legitimately need sendRawPacket and
other low-level entry points that intentionally stay off the
interface.
2026-05-15 01:12:40 +08:00
DrSmoothl 59cdfa98a2 refactor(oidb): replace 3 positional helpers with one named runOidb
bridge-oidb.ts used to expose three thin functions —
makeOidbRequest / sendOidbAndCheck / sendOidbAndDecode — and every
action file repeated the same five-step envelope assembly with long
positional argument lists. Collapse them into one `runOidb(bridge,
call)` taking an OidbCall object: cmd / oidbCmd / subCmd / request
{ schema, value, isUid? } / response? { schema }.

Behavioural contract is preserved:
  - No `response`: verify success + gotResponse, peek envelope retCode
    iff response data is present (fire-and-check semantics).
  - With `response`: require responseData, decode through the base
    schema, validate retCode, return the inner body typed as TResp.

Migration touches 51 call sites across 9 source files (bridge-contacts,
actions/{group-file, group-admin, profile, group-message, friend,
interaction, misc}, web-actions/cookies) plus 9 test files that used
to assert on positional `.mock.calls[0]![4]` indices and now read
through `.mock.calls[0]![1].request.value` / `.cmd` / `.oidbCmd`.

Net effect: callers now name what each piece is for, and adding
cross-cutting OIDB behaviour (retry / timeout / per-cmd logging) is a
single-site change inside runOidb instead of a sweep across 9 files.
2026-05-15 01:03:25 +08:00
DrSmoothl ac10c663f1 refactor(identity): absorb QQInfo into IdentityService
QQInfo's in-memory state (self identity, friends, group rosters,
profile cache) and read methods (findFriend / findGroup /
findGroupMember / findUserProfile / nickname / uin / selfProfile) now
live directly on IdentityService. The QQInfo class is gone; its
interfaces stay in `qq-info.ts` as plain types shared across the
remember*/find* surface.

This eliminates a long-standing duplication: every observation used to
maintain both QQInfo's in-memory structures and IdentityService's
SQLite mirror in parallel, with the uidByUin/uinByUid Maps tracked
separately. With one Module owning all three layers, every remember*
hydrates one set of structures and `loadSnapshot` repopulates the
in-memory uid↔uin index from SQLite on startup — closing the cold-cache
gap that previously forced findUidByUin to fall through to a SQLite
query after every restart.

Knock-on changes:
  - `Bridge` no longer holds a QQInfo; constructor takes an
    `IdentityService`. The CmdParser signature on the cmd dispatch
    table now passes `IdentityService` to parsers.
  - `msg-push-handler.ts` drops its private `resolveUidToUin(qqInfo, …)`
    helper that bypassed IdentityService's cascade — the parser hot
    path now reads through `identity.findUinByUid(uid, groupId)` and
    benefits from the O(1) `uinByUid` map even on freshly-loaded
    sessions.
  - `BridgeManager`'s session-started callback drops the QQInfo
    parameter; OneBotInstance no longer carries a `qqInfo` field and
    exposes a `nickname` getter for the WebUI listing.
  - `contact-actions` and the per-theme bridge action files stop
    importing QQInfo; they read everything via `bridge.identity.*`.
2026-05-15 00:44:01 +08:00
DrSmoothl 030336a25c refactor(identity): consolidate UID resolution behind IdentityService
Pull the cache→DB→network-fetch fallback cascade for UIN→UID translation
into a single async `resolveUid` on IdentityService, and drop the
duplicated `resolveUserUid` helper that used to live in bridge-oidb. Bridge
injects itself as the IdentityFetcher post-construction so the network
fallback runs through the same OIDB profile fetch the helper used.

Each action module's `resolveUserUid(bridge, uin, groupId?)` call becomes
`bridge.resolveUserUid(uin, groupId?)` — same signature on Bridge, but
internally it now goes through `identity.resolveUid` so future changes
(retry, coalescing, alternative resolvers) only need to land in one place.

This is part 1 of the IdentityService deepening (RoadMap item 1). The
QQInfo bypass in msg-push-handler and the broader QQInfo absorption land
in the follow-up commit.
2026-05-15 00:32:59 +08:00
DrSmoothl 2e4dd9b01e fix(onebot): clarify set_msg_emoji_like error wording
Distinguish "message not found" from "private chats don't support
emoji reactions". The latter previously masqueraded as "not a group
message", which sounded like a missing feature; clarify that the
limitation is on QQ's side, not ours.
2026-05-14 21:32:49 +08:00
DrSmoothl 564eec21bb fix(bridge): include emoji type in group reaction request
set_msg_emoji_like silently no-op'd for unicode emoji because the
reaction request didn't tell the server which emoji namespace the
code belongs to (QQ face vs unicode codepoint). Derive the type
from the code length — short numeric ids are QQ faces, longer
codepoint strings are unicode.
2026-05-14 20:45:37 +08:00
H3CoF6 b176e929b9 feat: implement upload group avatar 2026-05-14 04:09:55 +08:00
DrSmoothl 00a70b1ccc fix(bridge): preserve full ext-biz-info on media upload round-trip
The NTV2 upload-response decoder used stub schemas that omitted fields
QQ NT echoes back (notably video.fromScene/toScene, pic.fromScene/
toScene/oldFileId, the ptt scene/waveform set), so finalizeMediaMsgInfo
re-encoded the commonElem.pbElem with those fields missing. For c2c
video this triggered `send private message rejected: result=79` on
every send_private_msg [{type:'video'}] call — the upload itself
fast-pathed fine but the follow-up SendMessage was rejected by NT.

Drop the duplicate NTV2 placeholder schemas and route NTV2ExtBizInfo
through the element-side PicExtBizInfo / VideoExtBizInfo /
PttExtBizInfo, which are field-complete. Also zero out the main
video sub-file's width/height/time/videoFormat in the upload request
to mirror NapCat — those fields belong on the thumb, not the source
mp4, and non-zero values trip schema validation on c2c sends.
2026-05-13 22:19:45 +08:00
DrSmoothl e438f353af fix(onebot): resolve self nickname via user profile when friend list omits self
The session warmup only set qqInfo.nickname when QQ's friend-list
response happened to echo self back, which it omits for some
accounts / versions / multi-account warmup races. The WebUI online
sessions card then rendered a blank nickname row above the UIN.
Fall back to a direct user-profile fetch when the friend-list scan
misses self, and seed qqInfo.nickname with the UIN at session
creation so the panel never paints empty while warmup is in flight.
2026-05-13 21:11:26 +08:00
DrSmoothl ea5a1d505a feat: add forward message preview metadata support 2026-05-13 20:53:26 +08:00
DrSmoothl ada591b1b4 bump 1.7.9 2026-05-13 16:52:19 +08:00
DrSmoothl 61e3867197 chore(release): single-source app version + add pnpm bump
- WebUI sidebar/login display and OneBot get_version_info now read the
  root package.json version via Vite `define`, removing hardcoded
  literals in webui/src/types.ts and core/onebot/actions/info.ts.
- tools/bump-version.mjs (exposed as `pnpm bump <ver>`) syncs the
  version field across the root and all five workspace packages.
- Bump everything to 1.7.8.
2026-05-13 16:51:44 +08:00
DrSmoothl c9fa119a50 fix(onebot): align forward message wrapping with OneBot 11 spec
get_forward_msg now returns full OB11Message objects (self_id, time,
message_id, sender, etc.) instead of node-segment wrappers, and event
emission keeps the resId on incoming forward segments instead of
dropping it via the unknown-element fallback. Extends ForwardNodePayload
with optional context fields so download/upload paths preserve enough
state to synthesize the OB11Message shape NapCat clients expect.
2026-05-13 16:49:29 +08:00
DrSmoothl 6760008c5c chore: refresh prebuilt linux-x64 native binary 2026-05-13 16:18:21 +08:00
DrSmoothl 37b835c537 chore: refresh prebuilt linux-x64 native binary 2026-05-13 16:18:21 +08:00
DrSmoothl 9068ce3108 fix(core): skip Electron child processes during hook auto-load
With SNOWLUMA_HOOK_AUTOLOAD=1, the QQ window came up blank — no QR code,
login stuck. Cause: the native enumerator (get_all_main_process_ids)
returned the main QQ pid plus 2 zygote subprocesses because their
cmdline contains "qq" and they transiently inherit wrapper.node via
fork copy-on-write. Auto-load fired loadModuleManual for all three,
spawning an in-process resolver thread inside each zygote. Renderer
processes Electron later forked from those zygotes then inherited
those resolver threads + the partially-initialised hook state, which
breaks QQ's IPC and prevents the login UI from rendering.

Add `shouldAutoLoadPid` which reads /proc/<pid>/cmdline and returns
false when it contains `--type=` (Electron child process marker:
zygote / renderer / gpu-process / utility). Manual loadProcess() is
unaffected — operators picking PIDs from WebUI keep full control.
SNOWLUMA_HOOK_AUTOLOAD_ALL=1 disables the filter as an escape hatch.

Verified on tempserver: container restart with autoload=1 now shows
the QR-code login screen as expected, and only the main qq pid gets
the mojo.<pid>.*.sock pair (zygotes stay clean).
2026-05-13 00:57:48 +08:00
DrSmoothl fbb7504afe feat(core): auto-inject hook on QQ process discovery
Headless / Docker deployments previously needed a human to click
"Load" in WebUI for every newly-discovered QQ process. Add an opt-in
HookManager.autoLoadOnDiscovery flag wired up through two layers:

  - SNOWLUMA_HOOK_AUTOLOAD env var (highest priority)
  - hookAutoLoad in runtime.json (persistent fallback)

When enabled, every 'process-discovered' event from PipeWatcher fires
session.load() fire-and-forget; failures stay scoped to the session via
existing error-state handling and don't break the watcher loop.

Default stays off, so non-Docker installs see no behaviour change.
2026-05-12 22:04:11 +08:00
DrSmoothl dd02535a73 chore(core): flatten single-file dirs + drop dead writeFailed surface
Two small cleanups that came out of the round-2 architecture review
and are sub-five-minutes each — bundled because each one is too
small to justify its own commit.

#5 — flatten single-file directories
  packages/core/src/bridge/builders/element-builder.ts
    -> packages/core/src/bridge/element-builder.ts
  packages/core/src/bridge/handlers/msg-push-handler.ts
    -> packages/core/src/bridge/msg-push-handler.ts

  Both dirs had exactly one file in them — a smell that says
  "planned a sibling that never landed". Moving up one level
  removes the wrapper directory.

  Touch list:
    - bridge.ts:                  2 import paths
    - bridge/actions/forward.ts:  2 import paths
    - msg-push-handler.ts:        internal ../X -> ./X for events,
                                  proto/element, proto/message (the
                                  dynamic-import-typeof references too)
    - element-builder.ts:         internal ../X -> ./X for bridge,
                                  events, highway/*
    - 4 test files:               import paths (2 regular, 2 vi.mock)

#6 — drop IdentityService.hasWriteFailure
  identity-service.ts had a `private writeFailed = false` field set
  by the runWrite catch block and exposed via `get hasWriteFailure()`,
  but a full-repo grep showed zero callers of the getter. It was a
  public API stub for a feature that hadn't been wired (a webui
  health indicator, presumably).

  Removed:
    - the field
    - the getter
    - the assignment in runWrite's catch block (the error log on
      the next line is the actual observable behavior; nothing else
      reads the flag)

  If we want a "did any write fail this session" surface later,
  it's trivial to add back with an explicit consumer in mind.

Behavior preserved end-to-end. No public API change outside the
moved files. 369 tests pass (unchanged). 3 stability runs.
2026-05-12 20:59:25 +08:00
DrSmoothl 069548918b refactor(core): split web-actions.ts into themed modules + barrel
web-actions.ts was a 330-line monolith with 14 exported functions
covering 4 distinct themes: cookie/credential primitives (the 8
functions every web call builds on), group honor leaderboards, group
essence (highlighted messages), and group notices. Same shape problem
the OIDB bridge-actions.ts split fixed three commits back, just smaller.

New layout under packages/core/src/bridge/web-actions/ :

  cookies.ts        (161 lines, 8 fns)
    forceFetchClientKey / getPSkey / getCookies / getSKey /
    getBknFromSKey / getCookiesStr / getCsrfToken / getCredentials
    — the ptlogin2-jump + bkn-derivation primitives.

  group-honor.ts    (45 lines, 1 fn)
    getGroupHonorInfo (talkative / performer / legend / emotion / ALL)

  group-essence.ts  (27 lines, 2 fns)
    getGroupEssence (paged) + getGroupEssenceAll

  group-notice.ts   (118 lines, 3 fns)
    sendGroupNotice (with optional image-from-URL-or-file upload),
    getGroupNotice (OneBot shape flatten), deleteGroupNoticeByFid

  index.ts          (27 lines)
    Barrel re-export. `bridge.ts` keeps its existing
    `from './web-actions'` import — TS resolves the directory's
    index.ts so no caller changes.

The lower-level web/* helpers (request-util, group-essence,
group-honor, group-notice) stay where they were — they're the
direct HTTP/cookie wrappers, distinct from these Bridge-level
orchestrators.

Behavior preserved end-to-end. Same ptlogin2 URL construction,
same fall-back-to-getPSkey-when-p_skey-missing path in getCookies,
same default keyIndex='19' / expireTime='1800', same djb2 bkn hash,
same NapCat-derived default 540x300 notice image dimensions, same
chinese error messages ('设置群公告失败', '获取公告失败').

Adds 35 happy-path tests across 4 new files in tests/web-actions/ :

  cookies         (13)  forceFetchClientKey response shape + defaults,
                        getPSkey pskeyItems folding, getCookies ptlogin2
                        URL params, p_skey fallback path (both success
                        and throwing), getSKey success / no-clientKey /
                        no-skey throws, getBknFromSKey determinism +
                        range, getCookiesStr formatting, getCsrfToken
                        composition, getCredentials full + empty paths.
  group-honor      (7)  TALKATIVE list vs empty list behaviour,
                        PERFORMER / LEGEND / EMOTION per-type dispatch,
                        ALL fetches all four types, groupId stringification.
  group-essence    (4)  pageStart/pageLimit forwarding, defaults,
                        null-result fallback envelope, getAll delegation.
  group-notice    (11)  text-only dispatch + defaults, options override,
                        http image fetch + upload + thread, fetch failure,
                        ec≠0 surfaces em, generic error fallback,
                        getGroupNotice feed flattening + pics mapping,
                        null-result throw, empty-feeds case,
                        deleteGroupNoticeByFid argument forwarding.

Tests use vi.mock on bridge-oidb / web/request-util / web/group-*
to isolate each theme from real HTTP, mirroring the pattern from
the bridge-actions split.

369 tests pass (was 334); 3 stability runs, same pre-existing
macOS-arm64 websocket addon failure, unrelated.
2026-05-12 20:49:36 +08:00
DrSmoothl 8a49f0c21d refactor(core): extract MediaUrlResolver + MediaIndexer from OneBotInstance
The OneBotInstance constructor still carried two non-trivial closures
inside its converterCtx object — a 26-line mediaUrlResolver that
branched bridge URL fetches by element.type + isGroup, and a 60-line
mediaSegmentSink that fanned out to mediaStore.rememberImage / Record /
Video with subtly different field maps. Both closed over `this` and
were untestable without instantiating the whole instance.

Extracted into two small, focused modules:

  onebot/media-url-resolver.ts  (64 lines)
    class MediaUrlResolver(bridge, rkeyCache)
      .resolve(element, isGroup, sessionId): Promise<string>
    Picks the right Bridge.fetchXxx based on element.type + isGroup,
    mutates element.url in-place (preserved behavior), then applies
    the cached RKey via rkeyCache.resolveMediaUrl. Bridge-fetch
    errors are swallowed so the RKey pass always runs.

  onebot/media-indexer.ts  (90 lines)
    class MediaIndexer(mediaStore)
      .remember(mediaType, element, data, isGroup, sessionId): void
    One method, dispatches to mediaStore.rememberImage / Record /
    Video with the right field map per mediaType. Defaults are
    preserved exactly (?? 0 for missing numbers, ?? '' for strings).

OneBotInstance constructor shrinks from 134 lines to ~50 lines (-62%).
The converterCtx is now visually obvious — four callbacks each one
line, delegating to the right collaborator:

    const mediaUrlResolver = new MediaUrlResolver(this.bridge, this.rkeyCache);
    const mediaIndexer = new MediaIndexer(this.mediaStore);
    this.converterCtx = {
      selfId: parseInt(this.uin, 10) || 0,
      imageUrlResolver: (el, ig) => this.rkeyCache.resolveImageUrl(this.bridge, el, ig),
      mediaUrlResolver: (el, ig, sid) => mediaUrlResolver.resolve(el, ig, sid),
      messageIdResolver: (ig, sid, seq, name) => hashMessageIdInt32(...),
      mediaSegmentSink: (mt, el, d, ig, sid) => mediaIndexer.remember(mt, el, d, ig, sid),
    };

Adds 19 happy-path tests:

  media-url-resolver.test.ts  (12 tests):
    - file element: group / c2c-with-hash / c2c-without-hash
    - record element: group / c2c
    - video element: group / c2c
    - record without mediaNode: no bridge call
    - element.url already set: short-circuit, only rkey runs
    - bridge throws: swallowed, rkey still applied
    - rkey is always called at the end

  media-indexer.test.ts  (7 tests):
    - image: full field map, file falls back to fileId
    - record: full field map, file falls back to fileName
    - video: full field map, data.file overrides element fields
    - record: file falls back to fileId when fileName also missing
    - missing numeric / string fields default to 0 / ''
    - only the matching rememberX is called

Behavior preserved end-to-end: same bridge methods, same field
mappings into MediaStore, same in-place element.url mutation, same
RKey-always-runs guarantee, same best-effort error swallowing.
The existing media-store integration test (which still wires the
sink through the real converter) continues to pass unchanged.

334 tests pass (was 317); 3 stability runs, same pre-existing
macOS-arm64 websocket addon failure, unrelated.
2026-05-12 20:35:12 +08:00