nooklet

ADR 032: The desktop shell owns the one graph list; tokens in the keychain; no restarts

View source on GitHubRead as markdown

Date: 2026-10-04. Status: accepted (proposal 005, accepted by the owner). Amends ADR 028 and its B-704 amendment; narrows ADR 025's "a client remembers a list" for the desktop app. Work record: docs/progress/desktop-graphs.md. Bugs: B-780 (umbrella), B-781..B-785.

Context#

The owner, using the desktop app against the production server: "the graph behaviour on desktop is still super confusing". Proposal 005 mapped five places that each showed or added graphs, two lists that never met (desktop.json in the launcher, each origin's localStorage in the in-app menu), an add flow that asked for the address and the token on two screens a restart apart, phone-only choices ("Just this device", promote, "keep as a device-only graph") on a Mac, and a restart for every switch between This Mac and a server, because the shell decided once per launch whether to start its bundled server.

Decision#

  1. One list, owned by the shell. desktop.json holds the server graphs (address + label) and which graph was last open; This Mac's graphs are read from <data>/graphs/*/graph.json, as before (only a display-name override is stored). A server graph's device token is in the system keychain (keyring crate: macOS Keychain, Windows Credential Manager), keyed by the graph's address, never in the file. apps/desktop/src-tauri/src/graph_list.rs, token_store.rs.
  2. One menu. The sidebar's graph menu reads the shell's list from __NOOKLET_DESKTOP__.graphs (apps/web/src/shell/DesktopGraphMenu.tsx), grouped On this Mac / On servers (by host). The per-origin localStorage list is not shown on desktop; it stays only as replica bookkeeping (replica key, graph identity for mismatch detection), since dropping it would orphan existing replicas and their unsynced changes. The native Graphs… item (was "Switch Server…") opens the same menu.
  3. One add form, checked by the shell. "Create on this Mac" (a name) or "Connect to a server" (address + token or pairing link, one button). The shell makes the calls the web client would — POST <graph>/api/v1/graph.overview with the token, and for a pairing code first pairing.redeem (ADR 029) — from Rust (connect.rs, ureq), where CORS does not apply. Only an accepted token is stored. Every failure (unreachable, refused, wrong shape) is shown on the form.
  4. The token reaches the page through the initialization script, scoped. A window is built for one graph. When that is a server graph with a keychain token, the script carries that one token and exposes it as __NOOKLET_DESKTOP__.graphToken only when location.origin is the graph's origin and location.pathname is its path or below (/g/work, /g/work/…, never /g/workshop), checked before any page script runs; elsewhere it is null. The script is main-frame only, so no iframe sees it. The web client's bootstrap uses it and never stores it. There is no ConnectView on desktop: a server graph without a token opens on the add form, pre-filled with its address (views/DesktopConnectView.tsx).
  5. No restarts. The bundled server always runs. Switching is the window navigating to the graph's address; on_navigation lets it through when this window can show it (This Mac's graphs, the server graph it was built for) and otherwise opens a new window built for that graph and closes the old one. A new window starts on the launcher, which is now only "Connecting…" and, for an unreachable server, "Couldn't reach ." with Try again and Open a graph on this Mac.
  6. Requests from the page still use B-643's navigation door (nooklet-desktop.invalid), now four kinds (new-local-graph, connect-server, rename, remove), each carrying a random per-window key that only the window's main-frame documents receive, and answered with a nooklet:desktop-reply event. ADR 028's new-local-graph?label / open-local-graph and its amendment's add-server-graph are gone; so are the launcher's Tauri commands except server_status.
  7. No device-only graph on desktop. The mismatch screen offers "Re-sync from the server" and "Open another graph" only. "Just this device" and promote are not offered on desktop.
  8. Migration. A desktop.json in the previous shape (remote_graphs / active_graph_id / active_local_graph, or the older remote_url) is read once, rewritten, and kept as desktop.json.v1.bak. Every address is kept. Tokens were never in that file, so a migrated server graph asks for its token on first open; the form is pre-filled with the token that origin's storage still holds from the older version, if any, so moving it to the keychain is one click.

Rejected#

  • Swap the script on the live window. Tauri 2.11 / wry 0.55 add initialization scripts only when a webview is created. Reaching into WKUserContentController through with_webview could add scripts later but cannot remove one without removeAllUserScripts, which also removes Tauri's own; a stale token script would then stay in every later document. A new window per server graph is the supported path.
  • All server tokens in one script, each guarded by its origin check. No window rebuilds, but every token would be in the script text handed to every document's web content process, whichever origin it shows.
  • A token in the URL fragment of the graph's address. It would land in that origin's history and storage, and a reload would need it stored per origin, which is the localStorage copy this replaces.
  • Tauri IPC for server origins (ADR 028's rejection stands): a remote page, or a note's content, would get the command set.
  • Polishing the wording only, a launcher-only switcher, or syncing the two lists: proposal 005's alternatives, for the reasons given there.

Costs#

  • Opening a server graph swaps the window: the new one is placed where the old one was (size, position, full screen or zoomed), but its page loads from scratch and the swap may flash. Switching among This Mac's graphs, or from a server graph back to This Mac, stays in the window.
  • The keychain. An unsigned or ad-hoc-signed build is a different "app" to the keychain after each rebuild, so macOS may ask once per build whether nooklet may read its item. Linux, not a release target, has no persistent store in this build (the keyring crate's default there), so server graphs ask for their token at every launch there.
  • The door's exposure, slightly wider. Any page the window's main frame shows can, with the key the script gives it, create an empty graph on This Mac, add a server graph of its choosing (with a token of its choosing; the window then shows that server's page, which gets nothing it could not get in a browser), rename a graph, or remove a server graph from the list (its token is forgotten; the server keeps the graph; unsynced changes stay in this Mac's replica until it is added again). Iframes cannot: they never get the key. The window only ever shows nooklet pages in practice (external links open in the browser).
  • A token in the script text: the window built for a server graph hands its script, token included, to whatever web content process renders its main frame. Only that graph's origin gets the value; another origin loaded in the same main frame would have the text in its process, not in its JavaScript.
  • The bundled server always runs, also while a server graph is open: one idle Node process. Not measured (proposal 005's "Still unverified" stands).
  • "Show graphs on this server (root token)" is not offered on desktop (it would be another cross-origin call the shell would have to make with a root token); the phone and a browser tab keep it. Superseded by the amendment below (B-787).
  • Unverified in a real window (the owner's check, listed in the progress file): that WKWebView delivers each navigation to on_navigation, the window swap, the keychain prompt, and the menu item. cargo test covers the list, migration, verification against a local HTTP listener, request parsing, which navigation needs a new window, and — run in Node — which documents see the token; Chromium e2e covers the page side with the shell emulated.

Amendment (2026-10-05, B-786, B-787): deleting a graph on This Mac; listing a server's graphs#

Work record: docs/progress/desktop-night-bugs.md.

Deleting a This-Mac graph (B-786). A sixth request, delete-mac-graph (its own kind, not remove with a mac: key, so a page and a shell of different versions can never turn "forget a server" into "delete a folder"). On This Mac the folder is the graph, so:

  1. The page asks only after the B-712 dialog's typed delete (graph-removal.ts#macDeletionDialog).
  2. The shell refuses, before touching anything (mac_delete.rs#check_deletable): the graph open in the window; default (This Mac's main graph: the CLI, the MCP endpoint, the launcher's "Open a graph on this Mac" and the server's bare-address redirect all open it, and graph retire asks --force for it); the last graph on this Mac; and any request whose window is not on the bundled server's own origin. The typed confirmation is the page's, and a server graph's page is whatever that server serves, so only the client this app ships may ask.
  3. The folder is checked (graph_folder): a real directory directly in graphs/, not a symlink, inside graphs/ once resolved. The page names a graph by id only.
  4. The server lets go first, through B-713's retire. The bundled server holds a graph's SQLite file, mirror, indexer and sockets once anything asked for it (ADR 025's lazy registry); moving the folder under it would leave it writing to the moved file. So the shell calls DELETE http://127.0.0.1:<port>/graphs/<id> with <data>/root.token (the same data folder the sidecar serves), which closes everything and moves the folder to graphs-retired/<id>-<time>/. With nothing listening, nooklet graph retire <id> (the bundled CLI) does the same move and itself refuses while serve.pid names a live server. A server on the port that refuses that root token, or does not know the graph, is serving another data folder: nothing is touched.
  5. Then the Trash (trash crate, NSFileManager trashItemAtURL), not rm -rf. If the Trash refuses, the graph stays in graphs-retired/ and the error says where.

Rejected: rm -rf (not recoverable); leaving it in graphs-retired/ only (recoverable, but a person deleting a graph expects to find it in the Trash and to get the space back by emptying it); moving graphs/<id> to the Trash directly (the running server would keep the moved database open); Finder's AppleScript delete (the trash crate's default: offers "Put Back" but asks for an Automation permission). Costs: Finder may not offer "Put Back" for an NSFileManager trash, so restoring is dragging the folder back and renaming it; the webview's replica of the deleted graph (OPFS file, localStorage entry) stays in the bundled server's origin storage (B-880).

Listing a server's graphs (B-787). A seventh request, list-server-graphs with an address and a root token. The shell makes the web client's GET <server>/graphs from Rust (connect.rs#list_server_graphs) and answers with {id, label, address} rows; the page offers them and fills the address of the one picked. The root token is used for that one request: nothing on that path takes the keychain or writes a file, no error quotes it, and the form clears it once a graph is picked.

The server has no op that turns a root token into a device token for an EXISTING graph: POST /graphs mints an admin token only for a graph it creates, pairing.create needs that graph's admin token, and the graph app's bearer check (auth/tokens.ts#bearerAuth) reads only the graph's own token table, never the root token. So the desktop form, like the phone's and the browser's, then asks for the picked graph's device token or a pairing link. Adding a root-gated "mint a device token for graph X" endpoint would remove that step, but it would make the root token a key to every graph's data rather than to the list, which ADR 025 kept it from being; not done.

Both requests are announced by flags in the script (deleteMac, listServerGraphs, as reveal): a server graph's page comes from that server and may be newer than the shell, and without the flag it would send a request nothing answers.