feature: Local Syncing Logseq DB with local devices - #12919

Hello folks! I was reading this discussion here about syncing logseq DB with other devices locally, and I think a got a pretty nice solution I want to present you!

Like many people in that thread, I used to keep my Markdown graph in sync between my desktop, laptop and phone with Syncthing. After moving to the DB version that stopped being an option — syncing a live SQLite database at the file level corrupts graphs (WAL files, per-device client-ops state) and can't merge concurrent edits. The real answer is the sync server, and the codebase already ships almost everything needed: the Node.js adapter for self-hosting (ADR 0001) and the custom sync server URL setting. The only thing missing was a way to use them without a Logseq account, fully offline.

This PR fills that gap. The whole experience ends up being:

DB_SYNC_DATA_DIR=~/logseq-sync-data node worker/dist/node-adapter.js

Local sync mode: no Cognito auth configured.
Access token: 4f3c…9b21
(persisted at ~/logseq-sync-data/local-token; set DB_SYNC_LOCAL_TOKEN to override)

Pair a device: open http://192.168.1.10:8787/pair#4f3c…9b21
or scan:
█▀▀▀▀▀█ ▀▄█▄▀ █▀▀▀▀▀█
█ ███ █ ▀█▄▀▄ █ ███ █  …

Then on my phone I just scan the QR code with the camera → tap "Open in Logseq" → confirm. No account, no typing a token on a phone keyboard, no internet dependency. Graph data never leaves my network.

What's in the PR

1. Local-token mode on the self-hosted Node adapter

When DB_SYNC_LOCAL_TOKEN is set, that shared secret becomes the only accepted credential: JWT/Cognito verification is skipped entirely and every request maps to a single local user (DB_SYNC_LOCAL_USER_ID, default local-user). The check lives at the single auth choke point (worker/auth.cljs#auth-claims) with a constant-time comparison, so it covers HTTP, WebSocket sync and assets uniformly. The hosted Cloudflare deployment never sets this env var, so its behavior is completely unchanged.

On the client, the Sync Server settings (desktop dialog, also reachable from mobile settings) get an Access token field next to the existing custom URL. The token is stored alongside the URL, only ever sent to a custom server (never to the official service), and flows to the DB worker as a static credential that replaces the Cognito id-token — no token refresh, no login. The login gates around sync (upload menu, header indicator, mobile graph list, rtc start/restart flows) now also accept this mode, following the precedent that rtc-group? already returns true when a custom sync server is configured.

2. Zero-config token

You shouldn't need to invent a secret to sync your own notes. If the adapter starts with no Cognito configuration, it generates a token on first run, persists it at <data-dir>/local-token (mode 0600), reuses it on every restart, and prints it at startup. DB_SYNC_LOCAL_TOKEN still overrides it.

3. One-scan device pairing

Typing a 64-char token on a phone was the last painful step, so the server also prints a pairing link and a terminal QR code. The QR encodes http://<lan-ip>:<port>/pair#<token> — note the token travels in the URL fragment, so it's never sent over the network; the unauthenticated /pair page contains no secret and just turns location.origin + fragment into a logseq://sync-setup?url=…&token=… deep link client-side. The app handles that link on both desktop (electron protocol handler) and mobile (existing deeplink dispatcher) and always shows a confirmation dialog before applying anything, so a malicious link can't silently redirect someone's sync to another server.

Security considerations

I deliberately kept a shared secret instead of adding a no-auth mode: the moment a phone syncs, the server listens on the LAN, and the token is the only thing standing between "sync works" and "anyone on the Wi-Fi can read/wipe your notes". The auto-generated token keeps that protection without any setup cost.
In local mode the token is exclusive — a JWT that would otherwise verify is rejected, so there's no accidental mixed-auth surface.
Docs tell users to treat the QR/pairing link as a secret and to only expose the server on a trusted network or behind TLS.

Known limitations (intentional scope)

Local-token mode is single-user: every device acts as the same user, so member invitations/roles don't apply. That matches the "my own devices" use case this targets.
The QR//pair page is Node-adapter only (not the Cloudflare worker) — it only makes sense for self-hosting.
Possible follow-ups I left out to keep this reviewable: mDNS discovery (find the server with no URL at all) and showing a pairing QR inside the desktop app's settings.

How I tested it

pnpm test:node-adapter: 203 tests / ~4200 assertions passing, including new coverage for local-token auth (match/mismatch/missing/JWT-rejected-when-local), token generation/persistence/env-precedence.
All shadow-cljs builds (app, db-worker, db-worker-node, electron, mobile) compile with 0 warnings; clj-kondo clean on every touched file.
Live end-to-end on my LAN: server on my desktop, real devices pointed at http://192.168.x.x:8787 — wrong/missing token → 401, token → 200, graph upload/download/edit syncing across devices, /pair page and QR verified on a real terminal (which caught a fun bug: Closure advanced compilation renames .isTTY, hence the string-access fix in the last commit).

Docs are included: docs/self-hosted-sync.md (user-facing walkthrough) plus updates to deps/db-sync/README.md.

I know self-hosting has been a much-requested topic and that ADR 0001 already pointed at "pluggable auth providers" as follow-up work — I hope this is a useful step in that direction. Happy to adjust naming, split the PR, or rework any part of the approach based on your feedback. Thanks for the amazing work on the DB version! 💜