Files
WebHooker/docs/zh/guide/groups.md
T
翅膀喵andRhenCloud 978c53eeb3 fix(security): harden webhook delivery pipeline and group storage (#11)
* fix(log): preserve structured error details

Error objects lose their useful details when serialized as plain JSON.
Keep the message, stack and cause in structured log output.

* fix(runtime): bound shared in-flight waits

A canceled request can leave its shared promise pending forever.
Bound joins and coordinate a single replacement so later requests
make progress without multiplying upstream work.

* fix(bot): reject oversized callback bodies

Reject declared oversized bot callbacks before reading their bodies.
This keeps unauthenticated requests from wasting worker resources.

* test(d1): exercise real sqlite transactions

Exercise real foreign keys, transactions and conditional statements
instead of mocks that cannot reproduce lost updates or cascades.

* fix(storage): preserve claims across kv fallback

Only missing tables justify KV fallback; other failures must surface.
Remember fallback writes so migration to D1 cannot forget claims
and replay completed work. Share marker checks without extra writes.

* fix(filter): use isolated linear-time patterns

Backtracking patterns can exhaust worker CPU on untrusted payloads.
Use linear-time matching and separate bounded cache namespaces so
glob and regex entries cannot corrupt each other.

* fix(filter): read each event branch correctly

Deployment and check branches live in event-specific nested fields.
Read those fields and remove only the actual leading ref prefix.

* fix(filter): read only own payload properties

Inherited object properties are not webhook payload data.
Read own properties only so JSONPath cannot traverse prototypes.

* fix(filter): validate executable condition trees

Malformed trees and unsupported patterns must not silently turn an
exclude rule into a pass. Validate the shape and only the patterns
the evaluator actually executes.

* fix(i18n): bound and cache translation loads

Repeated misses and simultaneous override loads spend KV reads for
the same language. Cache confirmed misses and share bounded loads
without caching read failures as missing translations.

* i18n(bot): explain command and account failures

Explain account linking, command failures and skipped delivery
outcomes consistently in both supported languages.

* fix(github): bound and reuse app token fetches

Repeated token exchanges waste requests and JWT work for every event.
Reuse valid installation tokens, share refreshes and back off briefly
after failures while keeping every shared wait bounded.

* fix(github): restrict enrichment request urls

Webhook-provided URLs must never receive an installation token on
another host. Restrict enrichment to GitHub repository API paths,
reject redirects and bound optional requests.

* fix(formatter): preserve invalid code points

Out-of-range numeric entities can throw while formatting a delivery.
Keep invalid code points verbatim instead of aborting the message.

* fix(formatter): preserve bounded markdown text

Code spans, fences, indentation and autolinks are Markdown content,
not HTML tags to strip. Preserve them while bounding cleanup input
and reusing results across routes for the same event.

* fix(formatter): strip only leading ref prefixes

A short branch or tag may itself contain refs/heads or refs/tags.
Strip one leading full-ref prefix at the caller and keep short names
unchanged when generating labels and links.

* fix(gitea): link push authors to their forge

A Gitea author is not the same-named GitHub account.
Build author profile links from the originating forge.

* fix(formatter): render deployment state values

The deployment status object stringifies as [object Object].
Render its actual state in the status field.

* fix(formatter): read security severity levels

The scanner severity is not the security severity of an alert.
Prefer the security level so critical and high alerts get the right
label and color.

* fix(formatter): hide actions on other forges

Action buttons call the GitHub API as the linked user.
Hide them for other forges to avoid operating on a same-named
GitHub repository.

* fix(check): isolate updates by check suite

Same-named checks from different suites must not edit one message.
Include the suite or app identity and retain the former key for
controlled adoption of existing tracked messages.

* fix(logs): scope queries before limiting results

Filter authorized groups in SQL before LIMIT and aggregate only
visible rows. Preserve current group attribution for late writes,
surface read failures and combine related totals in one scan.

* perf(d1): index pruning and failed send queries

Pruning and failure views should not scan all historical rows.
Index the high-value access paths without adding a write-heavy
index for infrequent delivery-detail lookups.

* fix(discord): bound individual api requests

An unbounded API request can outlive an update-chain lock.
Bound each request so another holder cannot race a late edit.

* fix(discord): defer long rate-limit waits

Long rate-limit sleeps block delivery progress inside a worker.
Return a retryable 429 for the queue when the wait exceeds the bound.

* fix(discord): encode channel path segments

Stored channel and message ids are path segments, not URL paths.
Encode them so aliases cannot address another Discord resource.

* fix(discord): reuse nonces after lost responses

A successful create may lose its response. Reuse a stable nonce
with enforce_nonce so retries recover that message instead of
posting duplicates or accepting an unreadable success.

* fix(discord): constrain embeds and role mentions

Respect combined embed and component limits as well as field caps.
Restrict allowed mentions to validated route roles so payload text
cannot notify everyone.

* fix(discord): resume bounded command syncs

Application changes, command rollbacks and large guild lists can
leave commands stale indefinitely. Track the current hash per app
and resume bounded paginated work without needless KV writes.

* fix(github): verify installation management

An installation id is user-controlled, and repository access is not
installation management. Verify the owning account or an active
organization admin using the user token and read:org scope.

* fix(github): resolve immutable member ids

A login can be renamed and reclaimed before its first sign-in.
Resolve the current immutable user id when membership is granted
so a future holder of the login cannot inherit access.

* fix(auth): revoke stale sessions and tokens

Revoked or rotated credentials must stop working despite stale KV
replicas. Track the live token and revocations in D1 and preserve
immutable identity bindings rather than trusting a recycled login.

* fix(auth): bind sessions and tokens to identity

Automatic retries can repeat non-idempotent user actions.
Disable those retries and expose a write hook so bot handlers can
record completion immediately before the GitHub write.

* fix(discord): defer and deduplicate interactions

Acknowledge slow actions before Discord times out and deduplicate
interaction writes. Preserve comment text and reject edits whose
source changed after the modal opened.

* fix(telegram): always verify webhook secrets

Webhook verification must not silently disable itself when the
optional secret is absent. Derive a stable secret from the bot
token and reject callbacks when verification is unavailable.

* fix(telegram): bound individual api requests

Bound individual platform calls so they cannot outlive the lock
protecting a message update or stall a whole delivery invocation.

* fix(telegram): honor nested rate-limit delays

Telegram places retry_after inside parameters, not at the top level.
Read that value and defer long waits to the delivery queue.

* fix(telegram): report unreadable send results

An unreadable successful response may already have sent the message.
Report an explicit uncertain result instead of retrying a create
without an idempotency key or pretending it succeeded.

* fix(telegram): keep editable messages as text

Guessing photo versus text from message content makes later edits
use the wrong API and a smaller caption budget. Always send text
and use the avatar as a link preview.

* fix(telegram): render hard breaks as newlines

Telegram HTML does not support br tags. Render Markdown hard breaks
as plain newlines so otherwise valid messages are accepted.

* fix(telegram): clamp visible html characters

Telegram counts visible characters, not HTML source bytes.
Truncate without splitting tags, entities or surrogate pairs.

* fix(telegram): honor the author emoji toggle

The author marker must obey the group emoji preference just like
formatter-added decoration.

* fix(telegram): keep completed commands claimed

Redelivery after a completed write must never post another comment.
Keep completion claims despite reply failures, scope updates per bot
and only issue account-login links in private chats.

* fix(feishu): bound individual api requests

Bound individual platform calls so they cannot outlive the lock
protecting a message update or stall a whole delivery invocation.

* fix(feishu): classify retryable api failures

Business error codes can be transient even in HTTP 200 responses.
Classify token and rate-limit errors for retry and defer long waits.

* fix(feishu): retry sends with stable uuids

An unreadable response does not prove a send failed.
Reuse the same uuid for retries so recovering the result cannot
create a second Feishu message.

* fix(feishu): refresh and evict tokens safely

Separate app token caches, stop reusing refused tokens and share
refreshes. Cache failures briefly and keep valid tokens in memory
when a best-effort KV cache write fails.

* fix(feishu): use the card update endpoint

Delayed card updates use the card update endpoint; the config
endpoint cannot update an interaction response.

* fix(feishu): neutralize untrusted mentions

Forge text is untrusted and can contain at-all tags.
Neutralize mentions in card bodies and footers before rendering.

* fix(feishu): authenticate and dedupe callbacks

Authenticate signed or token-verified callbacks before dispatching
commands. Decode encrypted envelopes and handle card actions using
the correct fields without claiming irrelevant chat events.

* fix(target): normalize actual destinations

Different target spellings can name the same actual destination.
Normalize channel, thread and topic identities for ownership checks
and per-route duplicate suppression.

* fix(config): transact per-group configuration

Whole-table writes and cached snapshots can overwrite other groups
or resurrect removed configuration. Use per-group guarded writes,
one-time identity migration and explicit unreadable-row failures.

* fix(group): preserve identity through lifecycle

Group names are mutable and reusable, so they cannot own durable
state. Preserve immutable identities across lifecycle operations and
commit invite use with membership under transaction-time guards.

* fix(oauth): confirm account links and installs

A login link or installation id is not proof of account ownership.
Verify installation management, bind browser state and require an
explicit account-link confirmation before granting chat access.

* fix(queue): fence leases and record target outcomes

Retries must remember completed targets and distinguish active
lease holders. Fence state updates, preserve permanent outcomes and
reject missing parked payloads instead of dispatching empty data.

* fix(dispatch): isolate and resume tenant sends

Check tenant sources before filters and never dispatch orphan routes.
Record each target outcome, isolate update chains by forge and group
identity, and keep stale events from overwriting newer messages.

* fix(queue): bound batches and resume deliveries

A queue invocation has shared query and subrequest limits.
Use a small batch and shared send budget, renew fenced leases and
resume only unfinished work without exhausting unstarted messages.

* fix(admin): guard revisions and tenant targets

Read-time authorization alone cannot protect concurrent edits.
Guard revisions, current roles and destination ownership in the
write transaction, and use per-group endpoints for isolated changes.

* fix(webhook): confirm only accepted deliveries

Acknowledging before queue acceptance permanently loses deliveries.
Confirm only accepted work, release failed claims, scope replay
identities and strip tenant-supplied installation authority.

* fix(storage): prune abandoned parked payloads

Oversized payloads can remain after interrupted enqueue attempts.
Prune objects beyond their retry lifetime without deleting payloads
that a current delivery may still need.

* fix(console): expose api conflict statuses

Callers need the HTTP status to distinguish stale edits from other
failures and reload current data after a conflict.

* refactor(console): model group revisions

Carry server revisions explicitly so console writes can reject
changes based on an outdated group snapshot.

* fix(console): send loaded route revisions

Send the revision actually loaded with the route list and adopt the
server response after a save. Reload on conflict instead of silently
overwriting another editor.

* fix(console): guard fragment saves by revision

Fragments share a group version with other configuration writes.
Submit the loaded revision and reload on conflict to preserve
concurrent edits.

* fix(console): save groups with guarded writes

Whole-list saves can overwrite unrelated groups. Use per-group
revision-aware writes, retain rename results and confirm deletion
on the exact group, routes and version shown to the user.

* fix(console): reject edits of stale routes

A conflict reload can leave an older route editor open.
Compare its original value before saving so it cannot overwrite
the newly loaded route.

* fix(console): show overview loading failures

Failed overview requests must not look like an empty dashboard or
a successful refresh. Show the reason while retaining prior data.

* fix(console): explain rejected install bindings

Explain why an installation binding was refused instead of silently
returning to the console with no visible outcome.

* fix(console): allow selecting a group named all

The all sentinel collides with a valid group id.
Use a value that cannot be a group id so that group stays selectable.

* fix(console): discard stale log detail responses

An older detail request can finish after a newer selection or close.
Discard it so the dialog never shows the previously clicked record.

* fix(console): retain legacy group owners

Groups predating member roles store owners in adminIds.
Load those as owners so adding a member never drops all old owners.

* fix(console): lock member edits during saves

Edits made during a save are overwritten by its result.
Disable member controls and guard handlers until the write settles.

* fix(console): show invite loading failures

Failed invite loads must not look like no pending invites.
Show the error and discard responses from a previously shown group.

* fix(console): retain legacy discord log targets

A stored log target without platform means Discord.
Keep that meaning in the editor instead of clearing the target.

* fix(console): retain undisplayed forge sources

An editor that only displays some providers must preserve the others.
Keep stored custom sources when saving unrelated group settings.

* fix(console): lock the group editor while saving

Prevent edits while a group save is in flight and make super-only
installation settings readonly instead of silently ignoring edits.

* fix(console): lock route edits and show failures

Lock the route editor while saving and show fragment load failures
with a retry action rather than presenting a false empty list.

* fix(config): expose the legal contact override

Declare the public runtime key so the documented environment
override reaches legal pages in deployed Nuxt builds.

* build(deploy): migrate d1 before deployment

Apply pending D1 migrations before deploying code that requires
them. Stop deployment when migration fails instead of running
against an incomplete schema.

* docs(worker): align guides with runtime behavior

Synchronize both language guides, API references and examples with
the implemented authorization, storage and delivery behavior.
Document migration requirements and accepted operational limits.

* fix(storage): repair orphaned KV routes

Repair orphaned KV routes before serving KV-only configuration.

* fix(security): fully escape forge HTML

---------

Co-authored-by: RhenCloud <i@rhen.cloud>
2026-10-24 16:19:06 +08:00

11 KiB
Raw Blame History

分组与访问控制

路由归属于分组。分组用于划分管理权限,并可限制进入其中的事件。它们存储在 D1(d1_groups,首次加载时从旧版 KV config:groups 键同步),可通过 Web 控制台或 Admin API 管理。批量保存分组时单次最多 100 个分组。

分组模式

{
  "id": "backend-team",
  "name": "Backend Team",
  "members": [
    { "login": "rhencloud", "role": "owner" },
    { "login": "octobot", "role": "admin" },
    { "login": "reader", "role": "viewer" }
  ],
  "owners": ["myorg"],
  "providers": ["github", "gitea"],
  "installationId": 12345678,
  "logTarget": { "platform": "discord", "channelId": "123456789", "threadId": "987654321" }
}
字段 类型 必需 说明
id string 是 小写 id(a-z0-9、-);被每条路由的 groupId 引用。可编辑:重命名会同步其路由、片段、历史记录、webhook secret 与待处理邀请;被删除或重命名的 id 会保留若干天不可复用
name string 是 人类可读的分组名
members object[] 是¹ { login, role } 条目;角色为 owner、admin 或 viewer。服务端会把每个条目绑定到 GitHub user id(添加成员时解析,或在其首次登录时绑定);绑定后只匹配该账号,即使登录名易主
adminIds string[] 否 已废弃的旧字段;存在时视为角色为 owner 的 members
owners string[] 否 允许进入该分组的事件所属组织/用户登录名;空 = 全部
providers string[] 否 允许进入该分组的来源平台(github、gitea、custom);空 = 全部
installationId number 否 绑定到该分组的 GitHub App 安装 id;仅接受该安装的事件(空 = 全部)。仅超级管理员可改(由经过验证的安装流程设置)
isolated boolean 否 隔离分组(自助注册的个人分组)只接收其自身 /webhook/{groupId} 入口的事件,直到超级管理员为其绑定来源(installationId 或 owners)。仅超级管理员可改
emoji boolean 否 该分组消息是否包含表情(默认 true)
forgeSources object[] 否 来源主机:{ host, type, name? } 条目(type 为 github 或 gitea,name 为可选显示名称),用于标注该分组消息底部;空 = 不标注
lang string 否 该分组所有路由的消息语言(如 en、zh;可通过 KV i18n:<lang> 自定义)——见消息语言——默认 en
logTarget object 否 Webhook 日志频道:Discord 目标 { platform, channelId, threadId? }、Telegram 目标 { platform, chatId, topicId? } 或飞书目标 { platform, chatId },接收该分组路由每次分发 webhook 的摘要

¹ 必须提供 members 或旧字段 adminIds。非空的 members 列表至少要有一个 owner;空列表也可以(这样的分组只能由超级管理员管理)。forgeSources 最多 20 项,每项 name 最多 50 个字符,不能有类型与主机都相同的两项。

角色

每个分组成员拥有三种角色之一。超级管理员(ADMIN_USER_IDS)始终绕过这些限制。

角色 查看路由/日志 编辑路由 管理成员与邀请 编辑分组设置
owner ✓ ✓ ✓ ✓(除 owners)
admin ✓ ✓ ✗ ✗
viewer ✓(只读) ✗ ✗ ✗

权限模型

  • 超级管理员(ADMIN_USER_IDS)可查看和编辑所有分组与全部路由;只有他们能编辑分组的来源隔离字段(owners、installationId、isolated)——owner 保存时会保留已存储的值。
  • Owner 管理自己分组的路由、成员、邀请、名称、id、emoji 与 providers。不能移除最后一个 owner,也不能在没有其他 owner 时降级自己。
  • Admin 编辑自己分组内的路由并查看日志;viewer 只有只读控制台。
  • 分组管理端点通过 /admin/api/groups/:id/routes 一次操作一个分组;groupId 强制取自路径参数。
  • owners 列表把该分组的路由限制为这些用户或组织所拥有仓库的事件(repository.owner.login / organization.login);要按事件触发者过滤,请使用 actor 过滤器。
  • 所属分组已不存在的路由永远不会触发。
  • 每次分组写入都是单行的比较并交换更新:两个人编辑不同分组时互不覆盖;基于过期副本对同一分组的编辑会被拒绝(409,控制台会重新加载),而不是回滚较新的修改。路由与片段列表也按分组以同样方式处理。
  • 写入提交时会再次核对角色:在操作者失去角色(或被移除)之前通过鉴权的请求,提交时会被拒绝。
  • 删除分组需要带上控制台确认时看到的快照(revision、routesRevision 与分组 version):确认之后新增或修改的任何内容(路由、片段、设置)都会让删除返回 409,而不会被一并删掉。含无法读取路由的分组不会被删除。
  • 投递目标有归属:非超级管理员不能把路由或日志频道指向另一个分组已在使用的频道/群聊,除非也能编辑那个分组的路由(否则返回 403)。此前已被两个分组共用的频道,只在原有用途中继续有效。
  • providers 列表限制该分组路由会分发哪个 forge(github、gitea)的事件。即使组织/用户名冲突,也可借此将 GitHub 与 Gitea 分组分开。

Webhook 日志频道

分组可以设置 logTarget 指向一个 Discord 频道/子区、Telegram 群组/话题或飞书群聊。每当该分组的路由分发(dispatch)一个 webhook,就会向那里发送一条摘要消息:事件类型/动作、仓库、投递 ID,以及每条「路由 × 目标」一行的 ✅/❌ 结果(失败时附带错误信息;之前尝试中已处理的目标会如实标注;最多列出前 10 行,其余以 +N 汇总)。全部成功时消息为绿色,任一失败为红色,含结果未知的之前尝试时为灰色。同一投递重试得到相同结果时不会再发摘要。摘要使用分组的消息语言。日志消息尽力发送,本身不会被记入 D1 发送日志。

来源平台标识

分组通过 forgeSources 定义自己接收事件的 forge,即一组 { host, type, name? } 条目(type 为 github 或 gitea)。该分组路由发出的每条消息都会使用与事件来源类型匹配、且 host 与仓库 URL 主机名一致的第一条配置作为底部标识(GitHub 事件匹配 github.com)。标识文本为条目的可选 name——未填则回退为 host——因此两个自建 Gitea 实例可以显示为「内网 Gitea」/「Git2 仓库」,同时通过各自主机名完成匹配:

{
  "forgeSources": [
    { "host": "github.com", "type": "github", "name": "GitHub 主站" },
    { "host": "git1.example.com", "type": "gitea", "name": "内网 Gitea" },
    { "host": "git2.example.com", "type": "gitea" }
  ]
}
  • Discord — embed 底部在仓库名旁显示标识(内网 Gitea · acme/widget),并以站点图标作为底部图标:GitHub 使用 fluidicon.png,Gitea 实例使用 /assets/img/favicon.png(均为 Discord 可渲染的栅格 PNG——.ico favicon 会被 Discord 静默忽略)。
  • Telegram — 底部行以带超链接的标识开头([内网 Gitea](https://git1.example.com))。
  • 仓库主机没有匹配条目的事件(如自定义 webhook,或仓库托管在别处)不显示标识。

该标识与 Group.emoji 相互独立,并跟随该分组分发的所有消息(包括工作流/检查消息的就地更新)。

邀请

Owner(与超级管理员)可以在分组的 成员 面板创建单次使用、有效期 7 天的邀请链接。接受邀请后,用户以被邀请的角色(admin 或 viewer——绝不会是 owner)加入;已有 viewer 会被升级为 admin。邀请在整个有效期内存储在 KV 的 invite:{token} 键下;"已使用"记录与成员变更在同一个 D1 事务中提交,因此即使两人同时打开同一链接,也只能使用一次。

  • 邀请属于签发它的分组 instance:之后以同一 id 新建的分组不会接受它。
  • 撤销邀请会记录在 D1 中并立即生效,即使 KV 里仍有该邀请。
  • 签发人不再是该分组 owner 时,邀请失效。
  • 如果该登录名仍挂在一个绑定到其他 GitHub 账号的成员条目上(登录名的前任持有者),接受会因冲突失败且邀请保持可用;需 owner 先移除陈旧条目。

自助注册

设置 ALLOW_SELF_SIGNUP=1 后,没有分组权限的 GitHub 用户首次登录时会获得个人分组(u-{userId},归其所有),而不是 403。这是完全自助式 SaaS 安装的入口;关闭它可保持控制台仅邀请制。

个人分组是隔离的(该字段出现前创建的 u-<数字> 分组同样视为隔离,除非超级管理员设置 isolated: false):运营者的全局 POST /webhook 入口永远不会分发到它们,因此自助用户无法通过添加通配路由收到其他租户的事件。它们通过自己的分组 webhook 接收事件,或接收其能证明自己管理的 GitHub App 安装的事件(安装流程会用用户本人的 GitHub token 校验)。