Skip to content

feat(bridge): link a Discord channel to a Fluxer channel - #385

Open
Ferdinand99 wants to merge 3 commits into
v5.3from
feat/53-bridge
Open

Ferdinand99 wants to merge 3 commits into
v5.3from
feat/53-bridge

Conversation

@Ferdinand99

@Ferdinand99 Ferdinand99 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What

A new Bridge module (beta) that shares one conversation between a Discord channel and a Fluxer channel. It is Sylo's own implementation, written from the design in the 5.3 plan; no code or text was taken from other bridge bots.

Linking (both servers agree)

  • A server with Edit access asks for a link from one of its channels and gets a one-time code (12 characters, only its SHA-256 is stored, valid 15 minutes, used up by the first claim).
  • Someone with Edit access in the other server uses the code and picks a channel. Sylo has to be in both servers, the module on in both, and the channels must be ordinary text channels where Sylo has View, Send and Manage Webhooks.
  • A link joins Discord to Fluxer (never two servers on the same platform), a channel is in at most one link, and a server has at most 10 links and 5 waiting requests.
  • Either server can unlink at any time. A server that paused a link is the only one that can resume it; a link Sylo stopped can be resumed by either once it is fixed. Every step writes an audit entry on both servers and posts a visible notice in both channels.
  • Each side has its own options (bot messages, join notices, copying files): what leaves a server is that server's choice.

Relay

Through a webhook Sylo makes (and recreates when it is deleted) in each channel: messages with the author's name and picture, replies (a short quote with a link to the copy), files (re-uploaded up to 8 MB, otherwise a link), Unicode emoji and custom emoji with the same name, stickers (picture link), rich embeds, polls (as text), optional join notices. Edits and deletes follow through a message map that the daily retention job sweeps after 30 days.

Safety rules

  • No ping crosses: allowed mentions none on every send, and the text turns users, roles and channels into names and breaks @everyone / @here.
  • No loops or echoes: a message from any Sylo bridge webhook, or from Sylo itself, is never relayed.
  • Bots are off by default, system messages are never relayed.
  • An age-restricted channel only links to an age-restricted channel, checked when linking, when resuming and on every message.
  • Per-webhook queue with spacing, back-off on a rate limit, a cap on what waits and a limit on how long a job may wait; one server's queue never slows another's.
  • A failing link (no permission, a webhook that cannot be remade, a deleted channel, five failed deliveries in a row) is stopped, announced in both channels, shown as a problem on the Health page and not retried.

Dashboard, API and docs

  • Bridge page in the dashboard (list of links with status, ask for a link, use a code, options of this server's side, pause, resume, unlink, waiting requests) built from the existing components. Classified in routeAccess.js: View reads, Edit changes. Accept attempts are rate limited per person, with a lock after several wrong codes.
  • bridge feature string in /api/mobile/info (additive; nothing in the app changes).
  • docs/modules/bridge.md, plus the module list, the Fluxer differences table and the app API doc.

Migration number

The Bridge is migration 83. Versions 81 (public page look) and 82 (tickets index) are other changes' numbers, so this branch has two empty placeholder steps for them. Whoever merges first replaces the placeholders with the real steps; the Bridge step must stay the 83rd.

Testing

Run on the build machine, on SQLite and Postgres 16: lint, prettier, the full npm test, npm run test:v2 and npm run build:v2. New tests cover the consent flow (cross-guild attempts, wrong, expired and used codes, own code, same platform, module off, permissions), loop prevention, mention neutralisation, replies, edits and deletes, files, emoji, stickers, embeds, polls, join notices, the age rule, rate limit and back-off, failing links, webhook recreation, isolation between servers, the message map and its expiry, the routes (access, CSRF, cross-server ids), the Health items and the page.

Merge order

The two empty steps at index 80 and 81 of MIGRATIONS are placeholders for #368 (81, the public page look) and #383 (82, the tickets index), so the Bridge keeps version 83. Do not deploy this branch to a persistent SQLite database on its own. Merge #368, then #383, then rebase this PR and drop the two () => {} steps (the real steps take their place; the Bridge step stays the 83rd). This is handled at integration.

A new Bridge module shares one conversation between a Discord channel and a
Fluxer channel. Both servers agree: one asks for a link and gets a one-time
code (hashed, valid 15 minutes), someone with Edit access in the other server
uses it. Either side can pause or unlink at any time.

Messages cross through webhooks Sylo makes in each channel, with the author's
name and picture. Replies are quoted, files are re-uploaded within limits
(otherwise a link), custom emoji map by name, stickers become a picture link,
rich embeds cross, polls become text and joins are optional. Edits and deletes
follow through a message map that keeps a message for 30 days.

Safety: no ping crosses (allowed mentions none, mentions turned into names),
Sylo's own bridge messages are never relayed again, bots are off by default,
an age-restricted channel only links to an age-restricted channel (checked on
every message), a notice shows in both channels, each webhook has its own
rate-limited queue with back-off, and a failing link is stopped, shown in
Health and not retried.

Adds migration 83 (versions 81 and 82 stay empty placeholders until the
other 5.3 changes land), the Bridge page in the dashboard, the `bridge`
feature string in /api/mobile/info and a docs page.

@graphify-labs graphify-labs Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify reviewed this change.

Code graph out of date: Health delta baseline: last indexed commit a9ec8af (diverged from this PR's base — delta is approximate). Impact and hotspot numbers below may be wrong.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 4 advisory finding(s) below merit a look before merge.

Not checked: tests were not run; no formal proof of the changed code.


Graphify review — findings

Adds a Discord ↔ Fluxer Bridge module (beta) that links one channel on each platform through webhooks, so messages, replies, files, edits and deletes carry across with the author's name and picture and no pings. A link is only created when both servers agree: one side gets a one-time code (valid 15 minutes, stored hashed) and the other redeems it, and either side can pause, resume or unlink afterwards. The dashboard and mobile app get a Bridge page and bridge API routes (config view, request, accept, cancel, options, pause, resume, unlink), advertised through the new bridge feature string so older apps hide it. Per-guild bridge data is purged with the other guild tables, and the permission-health view gains a check for what the bridge needs. Docs and README now count 44 modules, with a new Bridge module page and a Fluxer note that a Discord poll shows up as plain text on the Fluxer side.

Worth a look

  • Channel uniqueness is enforced only within each bridge side — src/db/bridge.js:44 · Escalate · medium
    • NOT verified (no proof, no reproducing execution) — needs human review
  • Guild purge returns a count instead of the removed links — src/db/bridge.js · Escalate · medium
    • NOT verified (no proof, no reproducing execution) — needs human review
  • purgeBridgeGuild: link IDs are selected, then links are deleted by guild key, with no transaction — src/db/bridge.js · Escalate · medium
    • NOT verified (no proof, no reproducing execution) — needs human review
  • Message-map extra JSON is truncated mid-string, producing invalid JSON — src/db/bridge.js · Escalate · medium
    • NOT verified (no proof, no reproducing execution) — needs human review

Review partial — this diff was larger than one review pass covers, so later files were not reviewed; some findings may be missing.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 1621 functions depend on the 856 functions this change touches.

Health — this change adds coupling hotspots:

  • worse: setGuildModule() — 152 callers, 6 callees
  • worse: getGuildModule() — 193 callers, 3 callees
  • worse: apiFetch() — 63 callers, 3 callees
  • worse: purgeGuild() — 38 callers, 4 callees
  • worse: buildHealthReport() — 5 callers, 14 callees
  • new: acceptLink() — 4 callers, 16 callees
  • new: failLink() — 4 callers, 9 callees
  • worse: moduleLines() — 1 callers, 32 callees
  • …and 26 more — each is listed as a finding

Verification — 1621 functions in the blast radius were not formally verified this run (proofs are advisory here).

Health delta baseline: last indexed commit a9ec8af (diverged from this PR's base — delta is approximate).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

  • verification_scope: 1576 function(s) in the blast radius were not formally verified this run

Test selection

Test selection

682 of 682 test file(s) selected (100%) via static blast radius.

Escalated to a full run for safety (noncode-change, uncovered-code) — the selection is not trustworthy on its own (see below). CI should run the whole suite.

  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Access/DashboardAccessTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Access/Round3Tests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Account/AccountConnectTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Account/AccountModelTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Account/ConnectCallbackSourceTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Account/NoDashboardLinkSourceTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Appeals/AppealsReviewTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Applications/ApplicationFormsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Applications/ApplicationPassthroughTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Applications/ApplicationSubmissionsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Applications/ApplicationWireTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Audit/AuditHistoryTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Audit/AuditLogTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Auth/CallbackIssuerAddressTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Auth/CallbackIssuerTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Auth/KeychainTokenStoreTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Auth/PKCETests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Auth/SignInRequestTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Auth/TokenStoreTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Changelog/ChangelogTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Commands/CommandOverridesTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Economy/CollectiblePictureTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Economy/EconomyAdminTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Economy/EconomyMembersTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Economy/InventoryTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Economy/ShopExtrasTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Economy/ShopItemsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Economy/ShopModelTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Embeds/EmbedDraftTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Embeds/ModuleLimitsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Events/CommunityReviewFixesTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Events/EventEndpointsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Giveaways/GiveawayActionsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/GuildSettings/CommandPrefixTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/GuildSettings/GuildSettingsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Health/HealthTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Import/P6Tests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Insights/InsightsTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Leaderboard/LeaderboardTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Members/MemberDataTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Members/MemberSearchTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Messages/ComposedMessagesModelTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Messages/ComposedMessagesTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Models/ModelDecodingTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Models/ServerListTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Models/Sylo52PolishTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Models/UnknownKeysTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Models/Utf16TextLimitTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/Moderation/ModerationTests.swift — full-run-safety
  • apps/sylo-ios/SyloKit/Tests/SyloKitTests/ModuleSettings/AfkSettingsTests.swift — full-run-safety
  • … and 632 more

non-code file(s) changed (README.md, docs/dashboard-v2.md, docs/fluxer.md, docs/mobile-app.md, docs/modules/README.md …) → running the full suite for safety (a code graph can't see config/fixture/data deps)

changed code file(s) with no mapped test (README.md, docs/dashboard-v2.md, docs/fluxer.md, docs/mobile-app.md, docs/modules/README.md …) — a coverage gap or a missing link — running the full suite rather than only the selected tests

Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.

… sealed tokens

- Age restriction uses the platform's real rule: on Fluxer the channel's own
  setting, its category's or the server's (fail closed when unreadable), and
  a Discord server marked age-restricted counts for its channels. Checked when
  linking, resuming and on every message.
- The person linking (request and accept) must be able to view, read and send
  in the channel themselves; Sylo's own rights that cannot be read count as
  missing.
- Deletes always reach the copy: looked up inside the queued job, run while the
  link is paused or stopped, not dropped for a full or slow lane, one job for a
  purge, the webhook that really posted a copy is remembered, the bot deletes
  the copy when the webhook cannot, and a delete that wins the race against the
  relay is honoured. Edits are looked up inside the job too.
- Webhook messages never cross, even with bots on, and bot accounts that wear a
  platform tag are skipped, so another bridge cannot make a loop.
- Webhook tokens are sealed at rest with the AES-GCM helper now shared in
  lib/seal.js (the Pigeon credential keeps its format); an unreadable token
  leads to a new webhook.
- One process-wide budget for file downloads (4 at a time, 32 MB); a file that
  does not fit crosses as a link.
- Names in Sylo's own text are escaped, poll, sticker and file names get the
  mention rules, a late failure no longer overrides a pause, the leaving
  server's own webhook is deleted, a refused message falls back to a plain name
  and then to text only, pause is rate limited, and the dashboard shows only
  the own side's name.
…ixes

- Only the owner of a server (Discord owner, Fluxer owner) can ask for a link,
  use a code, change options, pause, resume or unlink; Administrators, Edit
  users and bot masters are refused. Everyone with View access sees the status,
  read-only. requireGuildOwner(req, guildKey) in web/lib/guildOwner.js, checked
  on every action from the owner the platform reports.
- The owner of each server is recorded with the link. If either owner changes,
  the link pauses (on the next message or join, and by a five-minute sweep)
  until the new owner confirms with Resume; a code made by a previous owner is
  refused.
- A delete that hits a temporary error is retried and keeps its map entry
  until the copy is gone; the download budget is held until the copy is sent;
  an edit with an unreadable webhook token makes a new webhook instead of
  counting as a failed delivery; plain-text webhook tokens are sealed on first
  read; a paused or stopped link whose channel was deleted shows a Health item.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant