Harden the server and the app for production, and give Deckle a test suite

[authorTom]

A full review of Deckle for production. It fixes six security issues and five ways data could be lost, and adds the project's first test suite, which CI now runs before the build.

Before deploying

Behind Caddy, Traefik or nginx, set DECKLE_TRUST_PROXY=true, or a number for a chain of proxies. Login throttling no longer believes X-Forwarded-For from anyone. Without the setting, every visitor behind a proxy shares one counter, so ten wrong passwords lock everyone out for 15 minutes. This is a new setting with a safe default, so the release is a minor bump (1.7.0) under the versioning policy.

Security

• API key readable through the file API. A path like ./.deckle-state/assistant.json got past the reserved-folder check, which compared the raw first path segment. The check now runs on the resolved path, ignores letter case, and also covers a custom DECKLE_STATE_DIR inside the library. It also put the key within reach of the assistant's read-only read_file tool.
• Password guessing wasn't throttled. The client address came from a header any client can set. server/throttle.mjs now takes the address from the connection unless a proxy is trusted, reads the header from the right-hand end, and caps how many addresses it tracks.
• One unreadable file crashed the server. Files are opened before headers are written, and streamed through pipeline.
• Sessions. Changing the password signs everyone out, the password check no longer reveals its length through timing, a malformed cookie is treated as signed out, and sign-out needs the app's request header.
• Content-Security-Policy (script-src 'self') on every response. It still allows calls to any AI provider, including LM Studio on the local network.
• App-side:
  • Bookmark hrefs are drawn only for http(s) URLs.
  • ZIP inflation is capped at the size the archive declares.
  • AI tool paths, memory paths and the queue's inbox limit reject .. and hidden folders, whatever the storage underneath allows.
• npm audit fix updates linkify-it, postcss, nanoid and browserslist.

Data loss

• Autosave: flushes are serialised, so a slow older write can't land after a newer one.
• Tasks and bookmarks: both now use one useDataFile hook.
  • It doesn't save before the file has loaded; changes made while loading are replayed onto what loads.
  • Saves run in order, and switching libraries writes a pending change to the library it belongs to.
  • A file it can't read is copied aside (.deckle/*.unreadable-*.json) before anything replaces it. The API refuses to write over one, with 500 store_unreadable.
• Queue: index updates are locked, so concurrent runs can't drop rows or restore a stale status (which could make a run execute twice).
• API:
  • Completing a recurring task rolls it forward, as the app does.
  • A PATCH is validated before the note is moved.
  • Bodies that aren't JSON objects get a 400.
  • Due dates must be real dates, and colours must be hex.
  • An export whose client disconnects no longer hangs.

Structure

The server's setup moved from server/index.mjs into a side-effect-free server/app.mjs, which the tests drive directly. index.mjs now only boots it. The README, .env.example, compose.yaml, the OpenAPI document and the changelog are updated.

Test plan

• npm test: 285 tests in 20 files, covering:
  • the server through its real HTTP handler, auth and throttling, and /api/v1
  • the file API, including the reserved-folder and symlink cases
  • ZIP round-trips, zip bombs, and every storage backend (including the remote adapter against a live server)
  • the queue under concurrency, the assistant's tools, and the hooks (useDataFile, and useNotes autosave ordering)
• npm run build
• Smoke test in headless Chrome against the built server, with a password: sign-in (including a wrong password), creating a note, typing into it, the note reaching disk, the command palette, and a reload with a javascript: bookmark on disk. No CSP violations and no page errors.
• Docker image build: not run locally, because no Docker daemon was available. The Dockerfile is unchanged and copies all of server/.

Known and not addressed

There are 35 moderate npm advisories, all from Tiptap v2 (mergeAttributes and __proto__). The fix exists only in Tiptap v3, a major editor migration that belongs in its own PR. Deckle never passes attribute objects that could reach that path, because content comes from Markdown through the DOM parser.

🤖 Generated with Claude Code