Repository navigation
ZenNotes 2.89.0 reaches a self-hosted server behind Cloudflare Access or any other gateway that checks headers. The desktop app, zn and the MCP server send the gateway's credentials with every request, live updates included. The desktop app also bundles zn 0.18.0.
Released from d500ea01 through #1097 and #1098 on 2026-11-20.
Features
-
Reach a server behind Cloudflare Access or another gateway (#1091, asked for by @medzsikmisi). An access gateway in front of your server turns away every request that does not carry its credentials, so nobody can reach ZenNotes at all without them. A Cloudflare Access service token is two such credentials, sent as headers. In Connect to Remote Vault, the Auth Token step now has Add extra headers: write one
Name: valueper line.CF-Access-Client-Id: <client id>.access CF-Access-Client-Secret: <client secret>Enter adds a line and Cmd/Ctrl+Enter connects. A remote you already saved takes the same box under Settings, Vault, Saved Remote Workspaces, Edit. The headers are stored in the system keychain with the auth token, never in
config.toml, and Settings shows only their names afterwards. They go with every request, uploads and images included, and with the live-update connection, so edits from other devices still arrive at once. Keep your ZenNotes auth token in its own field: the gateway checks the headers, then the server checks the token. Any gateway that checks headers works the same way, for example a proxy that wantsX-Api-Key: <key>. -
znand the MCP server send them too. They cannot read the keychain, so they take the same lines fromZENNOTES_REMOTE_HEADERS: thezninstalled from Settings, CLI (zn,zn tuiandzn mcp, from 0.18.0) and the copies bundled with the app. In an MCP client's JSON config, write the line break as\n:"ZENNOTES_REMOTE_HEADERS": "CF-Access-Client-Id: <client id>.access\nCF-Access-Client-Secret: <client secret>"
A value that does not parse stops the command with its line number before anything is sent.
Fixes
- A gateway that refuses says so. When something in front of the server turns a request away (an HTML 403), or sends it to a sign-in page on another host, ZenNotes now names the gateway instead of showing its page or failing with a parse error. The ZenNotes server's own refusals keep their own words.
zn
- The desktop app bundles zn 0.18.0, which sends
ZENNOTES_REMOTE_HEADERSon every request (ZenNotes/tui#54). A desktop-managedznalready updates itself; this raises the version a fresh install starts from.
Phones
- iPhone and Android carry the shared core of this release. Nothing changes on the phones themselves: their remote client does not send extra headers yet, so the box is hidden there.
For contributors
- One parser decides what a header list is,
packages/shared-domain/src/remote-headers.ts, used by the connect dialog, by the main process (which re-reads whatever a renderer sends) and by the bundledznand MCP server. zn'sinternal/remote/headers.gomirrors it rule for rule. Authorization is refused (the token has its own field), so are the names the connection sets itself, and a list that does not parse is dropped whole rather than sent in part. - Headers are their own secret-store entry per remote (
remote-workspace-headers:<id>), beside the token. A renderer gets only their names back (RemoteWorkspaceProfile.headerNames). supportsRemoteHeaderson the bridge capabilities hides the field where the host's remote client does not send headers (the phones, for now).apps/desktop/src/main/remote/gateway-headers.test.tsruns a stub gateway that answers 403 in HTML unless both Cloudflare headers arrive, and checks JSON, asset, upload and change-feed requests.
Verification
How to test locally:
- Run a ZenNotes server, and in front of it anything that refuses requests without a header. Cloudflare Access with a service token is the real case; a local stand-in is a small proxy that answers 403 unless
CF-Access-Client-Idis set. - In ZenNotes, run Connect to Remote Vault (command palette), enter the gateway's URL, and on the Auth Token step enter the server's token only. Connect.
- Before: the connection failed with a confusing error quoting the gateway's page. After: ZenNotes says that something in front of the server refused the request and points at the extra headers.
- Run Connect to Remote Vault again, choose Add extra headers, write the header lines, and press Cmd/Ctrl+Enter. The vault opens. Edit a note on the server from another device: it shows up at once.
- Quit and reopen ZenNotes: it reconnects through the gateway on its own. Settings, Vault, Saved Remote Workspaces, Edit lists the saved header names, never their values.
- In a terminal:
ZENNOTES_REMOTE_HEADERS=$'CF-Access-Client-Id: <id>\nCF-Access-Client-Secret: <secret>' zn list --server <gateway url> --token <token>lists the vault; without the variable,znnames the gateway.