Files
Marcos Paulo a71e294566
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
docs: specs, designs, research and agent rules for mobile, sync and collaboration
- specs: mobile-and-sync, collaboration, vault-launcher, e2ee, attachments-and-history, capture-and-publish, agents (brief and orchestrator notes for MiniMax and GLM agents)
- research: sync landscape, security and server, mobile platform (browsed, cited)
- design/mobile: 24 PaperCraft exports (dark and light) of the phone, desktop, sharing and launcher screens
- .claude: project skills and path rules so delegated agents follow the repo rules; CLAUDE.md imports AGENTS.md
- ARCHITECTURE and ROADMAP updated; AGENTS.md lists the approved sync dependencies

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-20 07:46:30 -03:00

46 KiB
Raw Permalink Blame History

Security and server features for the NotesCraft sync service

Research note for specs/mobile-and-sync/spec.md. Scope: end-to-end encryption for the file-sync service, device pairing and token lifecycle, large-attachment handling (chunking, dedup, resumable uploads), tombstones / GC / retention / quotas, server backup and restore, the MinIO/S3 blob backend, observability, deployment behind Traefik + Cloudflare Tunnel, and adjacent features (publish, clipper, shared links, email-to-note, voice memo, OCR).

Method

Browsed. Web search and page fetch were used on 2026-10-20 (access year 2026 for every URL in Sources). Claims below are backed by those fetches unless the text says from memory or unverified. Local ground truth came from reading specs/mobile-and-sync/spec.md, crates/sync/ (lib.rs, path.rs, hash.rs, ledger.rs, conflict.rs, merge.rs, plan.rs) and apps/notescraft-sync-server/ (routes.rs, store.rs, state.rs, config.rs).

Conventions used here: unverified = plausible but not confirmed by a fetched source in this session (typically a crate name I did not look up, or a version I did not open); from memory = stated without a fetched source.

No version number, price or API name below is invented. Where a product is named without a version, that is deliberate.


Findings

1. Two proven E2EE models exist, and both leak metadata

Obsidian Sync is the closest analogue to NotesCraft's single-owner case. Obsidian publishes a verification recipe: a per-vault random salt, a base key derived with scrypt from the vault password, an encryption key derived from the base key with HKDF-SHA256 (info = "ObsidianAesGcm"), and payload encryption with AES-256-GCM (12-byte IV prefixed, 16-byte tag appended). The vault password is separate from the account password. Obsidian states plainly that E2EE data is unrecoverable if the password is lost, and that the server keeps the encryption key out of reach.

Obsidian also documents its own limits, which are the most useful part for us:

  • Deterministic file-hash encryption. The same content under the same key always yields the same encrypted hash, so the server can detect duplicates. An attacker who can force uploads can therefore test whether a file matches one uploaded earlier.
  • No cryptographic binding between path and content. The server can read which device uploaded or deleted a file, when, and the mapping between encrypted paths and encrypted content. A compromised server can therefore re-map one encrypted file under another path — no plaintext leaks, but content can be substituted.

Syncthing's "untrusted device" model is the other reference, and it is more radical about metadata:

  • folderKey = scrypt(password, "syncthing" + folderID) (32 bytes).
  • File names are encrypted deterministically with AES-SIV (no nonce) and base32-encoded, then split across a synthetic directory tree (X.syncthing-enc/AB/CDEF…) so the server never sees the real folder structure.
  • A per-file key is HKDF-SHA256(folderKey || filename).
  • File data blocks are encrypted with XChaCha20-Poly1305 (24-byte random nonce prepended to the ciphertext) under the per-file key; block hashes are encrypted with AES-SIV using the file key and the block offset as associated data, so the same bytes at different offsets or in different files are not linkable.
  • The untrusted peer can still observe: file sizes (padded to 1 KiB granularity), which parts changed, and when.
  • Syncthing explicitly documents the consequence: because blocks must not be comparable across files, blocks cannot be reused between files on an untrusted peer — dedup and cross-file reuse are sacrificed for confidentiality.

Design consequence for NotesCraft. We want the Obsidian-grade threat model (server cannot read notes) plus the Syncthing-grade property that paths are not visible. That means the server can no longer key blobs by path; it must key them by an opaque random blob id, and the mapping blob id → path must live inside the encrypted manifest. The current server stores path in a plaintext SQLite column and uses it as the blob key — that has to become blob_id (opaque) plus an encrypted manifest if we want path confidentiality.

2. Per-vault key hierarchy, wrapping and recovery

The pattern that satisfies "single owner, many devices, self-hosted" without asking the owner to type a passphrase on every phone:

  • Vault master key (VMK): 32 random bytes generated once per vault. Never derived from a password, never transmitted in the clear.
  • KEK from passphrase: Argon2id over the owner's passphrase with a per-vault random salt → 32-byte key-encryption key → wraps the VMK. age already models this shape (scrypt::Recipient wraps a random file key under a passphrase; x25519::Recipient wraps it under a device public key).
  • Device wrap: each device holds an X25519 key pair; the VMK is wrapped to each device's public key at pairing time. Adding a phone never needs the passphrase.
  • Recovery key: a printable, high-entropy backup of the VMK (base32 / a word list) that can re-wrap the VMK under a new passphrase or a new device. This is the only way to survive "lost phone and forgotten passphrase".
  • Per-file keys: derived from the VMK with HKDF over path (+ optional content hash), so a single leaked file key does not expose the vault.
  • Key rotation: re-wrapping the VMK under new device keys is cheap; re-keying the whole vault is not. restic states the same limitation for its repository key: revocation of a leaked key without re-encrypting everything is not supported (restic mitigates it with a copy to a new repository).

What the server still sees (design the audit log and threat model around this list, not around "nothing"):

  • vault id, device ids, device names, pairing events;
  • opaque blob ids, byte sizes (padded), modification times, seq numbers;
  • when each change happened, from which device, and the change frequency;
  • client IP, TLS metadata, request sizes, long-poll timing;
  • the encrypted path and manifest blob (unreadable to it).

Notably it does not see: note titles, note bodies, folder names, or which file changed relative to which other file — unless we keep the current plaintext path column, which we should not if E2EE is a goal.

3. Rust crates: what is available, and how healthy it is

Versions below are the ones actually read on crates.io/docs.rs on 2026-10-20.

Crate Version seen Status / notes
chacha20poly1305 0.11.0 (2026-06-28) RustCrypto/AEADs. MSRV 1.85, edition 2024, Apache-2.0/MIT. One security audit by NCC Group, no significant findings. Provides XChaCha20-Poly1305 (24-byte nonce) and reduced-round variants. Actively maintained, audit-grade.
argon2 0.6.0 RustCrypto. Argon2id is the default variant. Offers both PHC password hashing and raw hash_password_into key derivation — the latter is what we want for the passphrase→KEK step. MIT/Apache.
rust-argon2 3.0.0 (sru-systems) Alternative to the above. Its own README warns it "does not attempt to clear potentially sensitive data from its work memory". Prefer the RustCrypto crate for a key-derivation path where we then hold the key in memory.
rand 0.10.3 (2026-09-20) rust-random. MSRV 1.85. Not a cryptographic library — its README says so. Use getrandom/OsRng for keys and nonces; use rand only for non-secret material (pairing codes, jitter).
zeroize 1.9.1 (2026-10-06) RustCrypto. Portable, uses write_volatile + fences, no FFI, no_std. Actively maintained. Required for the passphrase and VMK handling path.
age 0.12.1 (2026-07-14) str4d/rage, MIT/Apache, Rust 1.74. Crate description still says "[BETA]". Implements the age v1 spec: x25519, scrypt, ssh, tag, tagpq recipients; streaming API; armor. Good for exporting/importing a wrapped vault key, wrong shape for a sync protocol (it is a file-encryption format, not a chunked revision protocol).
qrcodegen 1.8.0 (2022-04-17) Nayuki, MIT. No release since 2022, but the library is complete, small and self-contained (all 40 versions, 4 ECC levels). Dormant but low-risk. Renders to raw modules; we draw the image ourselves.
tower_governor 0.8.0 (2025-08-14) MIT/Apache, governor backend, axum feature. Mature, used with axum 0.8. Provides PeerIpKeyExtractor, SmartIpKeyExtractor (looks at x-forwarded-for/x-real-ip/forwarded), GlobalKeyExtractor, use_headers() for x-ratelimit-*.
whisper-rs 0.16.0 (2026-03-12) Unlicense. Rust bindings to whisper.cpp via whisper-rs-sys (C++ build, cmake). Actively maintained. Desktop/mobile builds are heavy; the model file must be shipped or fetched.
opendal-service-s3 0.58.2 (2026-08-20) Apache OpenDAL, Apache-2.0, MSRV 1.91 (workspace is on 1.95, so fine). Speaks the S3 API incl. MinIO, supports versioning/restore, SSE-KMS/SSE-C/SSE-S3, presign, and per-service capability probing. Split-crate layout (opendal-core + opendal-service-s3).

Also plausible but unverified in this session (names I did not open): hkdf, blake3, aes-siv, x25519-dalek, subtle/aead trait crates, prometheus or metrics for exposition, tracing/tracing-subscriber, tower-http, async-imap for email, aws-sdk-s3.

Crate choices, in one line each:

  • Content cipher: chacha20poly1305 XChaCha20-Poly1305 (audit-grade, random 24-byte nonce, no nonce-reuse risk across a whole vault). Choose.
  • KDF: argon2 (Argon2id) for passphrase → KEK. Choose. Use zeroize on every buffer that holds a key, passphrase or plaintext.
  • RNG: getrandom/OsRng for all secrets; rand only for non-secrets. Choose.
  • Key wrapping: age if we want an interoperable file format for vault-key backup and device-key export; otherwise a 100-line x25519 + XChaCha20 wrap is enough. age is the lazier path because it already exists and is maintained.
  • Deterministic encryption of names: Syncthing uses AES-SIV. If the RustCrypto aes-siv crate is acceptable (unverified — I did not fetch it), reuse it; otherwise derive a per-path nonce deterministically from a separate name key and encrypt with XChaCha20-Poly1305. The second option is deterministic-AEAD misuse and must be documented and fuzzed, so prefer a real SIV.
  • Do not use rust-argon2 for key derivation (it does not clear work memory) and do not use rand for key bytes.

4. Device pairing by QR, token rotation, revocation, lockout

QR pairing. The desktop shows a QR; the phone scans it. The QR payload should be a signed, expiring blob containing: vault id, a one-time pairing code id, the vault master key wrapped to the phone's freshly generated X25519 public key, and an expiry timestamp. Two flows exist and both are worth having:

  • Phone-initiated: phone generates a keypair + pairing secret, shows a QR; desktop scans it. Wrapping key to the phone key happens on the desktop where the VMK lives.
  • Desktop-initiated: desktop shows a QR with a short pairing code; the phone types or scans it; the phone sends its public key; the desktop wraps the VMK to it.

The current server already has POST /v1/vaults/{vault}/pairing and POST /v1/devices, and pairings.code_hash is stored hashed — good. What is missing is (a) the wrapped VMK in the pairing response, (b) an explicit attempt counter, and (c) rate limiting. qrcodegen + our own renderer is enough; no image crate dependency is needed if we draw the modules as rectangles in egui.

Token rotation and revocation. The current devices table has token_hash only — no expiry, no revocation column, no "last used". Minimum viable lifecycle:

  • Access token: opaque 32 random bytes, stored as a hash, short TTL (say 15 min), presented as Authorization: Bearer.
  • Refresh token: opaque, longer TTL (say 30 days), rotated on every refresh with a short grace window so a racing client does not lock itself out; the server keeps token_hash, prev_token_hash, expires_ms, revoked_ms, device_id.
  • Revocation: POST /v1/devices/{id}/revoke sets revoked_ms; the server checks it on every request. Revoking a device must also mean: its refresh token stops working and its queued long-poll is terminated. Note the spec's own acceptance criterion — "wrong or revoked token → 401 and the client shows Sign in again without touching files".
  • Emergency: rotate the vault keys (new VMK, re-encrypt manifest) — expensive, but the recovery key makes it possible.

Rate limiting and lockout on pairing codes. tower_governor is the obvious fit for axum. Two traps, both documented in its README:

  1. Do not construct the same GovernorConfig twice — each config is an independent limiter.
  2. Behind Cloudflare Tunnel the peer IP is the cloudflared pod IP, so PeerIpKeyExtractor would put every client in one bucket. Use SmartIpKeyExtractor (or a custom extractor reading CF-Connecting-IP / X-Real-Client-Ip set by the edge).
  3. GovernorConfig::secure() is a sane preset for auth endpoints: burst of 2, replenishing one token every 4 s per peer.

Pairing lockout policy (own code, ~30 lines): a pairing code is valid for a short TTL (the server already has PAIRING_TTL_MS); after N failed redemption attempts the code is invalidated; redemption attempts are also rate limited per IP with exponential backoff. A wrong code must answer 401/403 without revealing whether it existed.

Audit log. OWASP's Logging Cheat Sheet is the right template: log authentication successes and failures, authorization failures, input-validation failures, admin actions (add/remove device, rotate key, revoke token), data export, and configuration changes. Every entry records when, where, who, what plus severity and result status. Never log: raw tokens, passwords, encryption keys, or session identifiers (hash them instead). Sanitize control characters to prevent log injection. Protect the log itself: append-only, restricted permissions, and a tamper-detection story — for a homelab, shipping the audit stream as JSON lines to the existing Loki/Alloy collector (as the Traefik guide does) is the cheapest path. Note OWASP's point that process/audit logs and security-event logs are different purposes and should be kept separate.

5. Chunking and content-defined dedup for big attachments

restic's design doc is the reference implementation worth copying:

  • Rolling Rabin fingerprint over a 64-byte window; a chunk boundary is declared when the lowest 21 bits of the fingerprint are zero. Boundaries therefore depend only on content, so inserting bytes near the start of a file does not shift every later boundary.
  • Chunks are 512 KiB – 8 MiB, target average 1 MiB.
  • The irreducible polynomial is chosen randomly at repo init and stored in the config, which is a direct defence against "watermark" chunking attacks (an attacker who knows the polynomial can craft inputs that align boundaries).
  • restic 0.18.0 added another mitigation: randomly assigning chunks to pack files, so an observer cannot infer chunk sizes from pack layout.
  • The chunking-attack literature is cited there: Alexeev, Percival & Zhang, "Chunking Attacks on File Backup Services using Content-Defined Chunking".

The tension with E2EE is explicit and unavoidable: content-defined chunking plus server-side dedup leaks equality of content across files (identical chunk ids ⇒ identical plaintext, if the chunk id is derived from plaintext). Syncthing hit the same wall and gave up cross-file dedup on untrusted peers. Three workable positions:

  1. Client-side CDC, encrypted chunks, server sees only opaque chunk ids. The client chunks with CDC, encrypts each chunk with the VMK (XChaCha20-Poly1305, random nonce) and stores blob id = BLAKE3(vault_salt || plaintext_chunk_hash). The server dedups by that id. Equality of plaintext across two files is still leaked by equal ids — mitigate by salting the id with a per-vault secret that only the client holds (server cannot recompute ids for new content, so dedup would then break)… so in practice equal chunk ids leak equality. Decide explicitly and document it.
  2. Dedup only within a file (safe) plus whole-file dedup by hash of the encrypted blob (also leaks equality, but only of whole files).
  3. Per-vault key per chunk, no cross-file reuse: the "Syncthing untrusted" position — best privacy, worst bandwidth.

Recommendation for v1: whole-file dedup by encrypted-blob hash only (the current hash field already does this), and treat CDC as a P1 feature scoped to attachments (> 8 MiB) where bandwidth actually hurts, with the equality-leak documented in the threat model. Effort: L.

6. Resumable uploads

The tus protocol (v1.0.0, MIT, SemVer-stable) is the reference: HEAD returns Upload-Offset, PATCH with Content-Type: application/offset+octet-stream appends at that offset, mismatched offset ⇒ 409, and the extensions are creation, creation-with-upload, expiration, checksum, termination, concatenation. Rust implementations exist (rustus on crates.io, Rocket integration meteoritus) but they are third-party crates and would add a dependency the project has not approved.

Two options for NotesCraft:

  • tus-compatible endpoint (POST create + HEAD/PATCH upload). Pros: standard, resumable out of the box, client-agnostic. Cons: a second upload protocol living next to the file-revision protocol, plus a new dependency.
  • Chunked PUT with Content-Range plus a server-side uploads table (upload_id, path/blob_id, offset, length, expires_ms). Pros: reuses the existing PUT /files/{path} shape, no new dependency, ~150 lines. Cons: home-grown, less interoperable.

Given "Rust only, minimal dependencies", the chunked-PUT option is the smaller diff. The 25 MiB per-file cap in routes.rs means resumability only matters for large attachments, so this is P1, not P0. Expiration of abandoned uploads should be enforced by a janitor task (the expiration idea from tus).

7. Tombstones, blob GC, retention, quotas

The current schema already has the right shape: files(vault, path, hash, size, mtime_ms, seq, deleted) with a deleted flag, so a tombstone is a row, not a deletion. What is missing:

  • GC: a janitor that removes blob objects whose blob_id is referenced by no live row and no row inside the retention window. Must run after the tombstone grace period, and must be crash-safe (mark-then-delete, never delete-then-mark).
  • Retention of old versions: the current files table keeps only the latest row per path. Keeping history means a second table (file_versions(vault, path, hash, size, seq, created_ms)) so the server can serve "restore this revision". Obsidian Sync and restic both keep version history; users expect undo-across- devices.
  • Bucket lifecycle as the safety net: MinIO lifecycle rules can expire old object versions (--noncurrent-expire-days), expire delete markers (--expire-delete-marker), or nuke everything after N days (--expire-all-object-versions). Because the app's own metadata is the source of truth for "what is live", MinIO expiry must be configured looser than the app's retention, never tighter.
  • Quotas: MinIO has bucket quotas and QoS caps, but the docs are explicit that the quota scanner is periodic, so a bucket can exceed its quota between cycles. Enforce the per-vault byte quota in the app (sum of live blob sizes) and answer 429 with a Retry-After; use the MinIO bucket quota as a backstop.

8. Backup and restore of the server

Three distinct things need backup, and they are not the same operation:

  1. Blobs (MinIO bucket): enable bucket versioning, and use bucket or site replication for off-cluster copies. MinIO's own docs are explicit that replication requires versioning on both ends, and that lifecycle expiry does not replicate delete operations. Object lock (GOVERNANCE/COMPLIANCE) gives write-once-read-many if we want a tamper-evident copy.
  2. Metadata (SQLite): take a consistent snapshot with VACUUM INTO (safe while the server runs) rather than copying the file; ship it to the backup bucket.
  3. Restore drill: the only backup that counts is one you have restored. Restore into a scratch bucket, replay the file records, and verify the SHA-256 of every blob against the record. This is a script, and it should run in CI against a seeded vault.

restic's own repository format is worth stealing two ideas from: content-addressed storage ids (so corruption is detectable by comparing the file name to its hash) and a strict write order (pack files → index → snapshot) that makes crash recovery deterministic.

9. MinIO / S3 blob backend

opendal-service-s3 0.58.2 (MSRV 1.91) is the strongest candidate: one dependency gives read/write/stat/list/copy/delete/restore/presign, explicit MinIO support (endpoint + region + credentials, path style by default), versioning-aware restore/restore_with, and SSE options. It also exposes Operator::info() so we can probe capabilities instead of guessing. The split-crate layout (opendal-core + opendal-service-s3) keeps the dependency graph shallow.

Alternatives, unverified: aws-sdk-s3 (official, heavier), rust-s3 (community), or plain reqwest + hand-rolled SigV4 (do not).

Decisions to make explicitly: path style vs virtual host style (MinIO is usually path style); whether the server encrypts at rest with SSE-S3/SSE-KMS in addition to client-side E2EE (belt and braces — but note that SSE keys live with the server, so it does not help against a malicious server, only against a stolen disk).

10. Observability and health

  • /healthz already exists in routes.rs. Add /readyz that actually checks MinIO reachability and SQLite writability — a liveness probe that returns "ok" while the bucket is unreachable moves the failure from Traefik to the client.
  • Expose Prometheus metrics: request rate/latency by route, active long-polls, blob bytes stored per vault, sync sequence lag, pairing failures, upload sessions in flight. Crate names unverified (prometheus vs metrics).
  • Structured logs with tracing (unverified crate version) plus a request-id middleware, so a client can quote a request id in a bug report.
  • The long-poll GET /changes?wait=25 is the interesting metric: it holds connections open, so connection count and long-poll duration are the two numbers that predict trouble.
  • Alert on: pairing failure spikes, token revocation events, quota rejections, GC failures (a failing GC means unbounded blob growth), and restore-verification failures.

11. Behind Traefik with TLS and Cloudflare Tunnel

The reference pattern (Cloudflare → cloudflared → Traefik → service) is documented in practice; the parts that matter for NotesCraft:

  • cloudflared runs inside the cluster, so there are no inbound ports and no public IPs; DNS CNAMEs point at the tunnel's *.cfargotunnel.com address.
  • Each hostname maps to the Traefik service with origin_server_name set so cloudflared presents the right SNI, plus http2_origin = true.
  • Traefik must trust Cloudflare's IP ranges in forwardedHeaders.trustedIPs, otherwise X-Forwarded-For is stripped and every request appears to come from the cloudflared pod. This directly breaks IP-based rate limiting (§4).
  • TLS: ACME DNS challenge through Cloudflare, or let Cloudflare terminate and Traefik serve plain HTTP internally. The guide's TLSOption uses TLS 1.2/1.3, AEAD-only cipher suites, sniStrict: true.
  • Rate limiting per route with sourceCriterion.requestHeaderName pointing at the header the edge sets — otherwise every client shares one bucket, as noted above.
  • Timeouts vs long-poll: the guide sets readTimeout=60s and writeTimeout=0s (disabled) because long-lived connections get killed otherwise. NotesCraft's wait=25 long-poll needs a read timeout comfortably above 25 s plus the change-detection jitter; mobile clients must also tolerate the proxy closing idle connections, so the client should reconnect on EOF rather than treat it as an error.
  • Client IP for the audit log: use the header the edge sets (CF-Connecting-IP or X-Real-Client-Ip), not RemoteAddr.

12. Adjacent features: who has them, and how they map onto NotesCraft

  • Publish a note as a web page. Obsidian Publish is the product to copy: hover previews, graph view, stacked pages, backlinks, custom themes via CSS/JS, custom domain, password protection with multiple passwords, SEO metadata per page, optional analytics, and mobile-friendly output. NotesCraft's version can be much simpler: the server already has the Markdown; render to static HTML on the homelab, push to the bucket, serve via the same Traefik host. No wasm build needed. NotesCraft's advantage: publish from the mobile app directly, and no third-party hosting.
  • Web clipper. Obsidian Web Clipper is a browser extension with templates, highlights, meta-tag/Schema.org/selector extraction and template variables; it emphasises "your clipped content is stored locally in your vault" and "no lock-in — exports to JSON". A browser extension is JavaScript, which clashes with the Rust-only rule, so the NotesCraft-native equivalent is a share-to-endpoint: any app POSTs a URL + extracted text to POST /v1/clip on the sync server and the vault gets a note. That keeps the client Rust (mobile share sheet, desktop CLI) and lets a browser extension be an optional, third-party convenience later.
  • Shared read-only vault links. Obsidian Publish's password protection is the model. For NotesCraft this needs per-link capability keys: generate a random read key, encrypt a subset manifest under it, and serve a read-only HTML view. Do not reuse the sync VMK for shares — a leaked share must not unlock the vault.
  • Email-to-note. The "Email to Vault" Obsidian plugin does exactly this: a disposable Mail.tm mailbox or your own IMAP server, periodic polling, each message becomes a note with From/To/CC/Subject/Body/attachments, templated path and frontmatter, and it marks messages read only optionally. NotesCraft can do the same with a Rust IMAP client (crate name unverified) or with an inbound SMTP relay in front of the sync server.
  • Voice memo transcription. whisper-rs 0.16.0 (Unlicense) is the only credible Rust path; whisper.cpp is a C++ dependency with cmake build, and models must be shipped or downloaded. Running it server-side on the homelab is much cheaper than shipping a model to every phone: the phone uploads the audio (already part of the attachment pipeline), the server transcribes, the transcript is written back as a note.
  • OCR of scanned pages. Two Rust paths: leptess (bindings to Tesseract + Leptonica, MIT, needs C/C++ dev libs and language data; last push 2024-01) and a newer pure-Rust ocr crate (Apache-2.0, no C deps, Markdown/hOCR/JSON output) — but that one is a young project (1 star) whose own README says the CRNN model training is blocked and that production use should stick to the deterministic pattern-matching engine. Both point the same way: run OCR server-side, not on the phone.

Feature table

Effort: S ≈ ≤ 2 days, M ≈ 1–2 weeks, L ≈ > 2 weeks (per developer, including tests). Priority: P0 must, P1 should, P2 later.

Feature Who has it Why it matters for NotesCraft Effort Priority
Vault master key (VMK) + per-file key derivation Obsidian Sync (scrypt→HKDF→AES-GCM); Syncthing (folder key → per-file key) The base primitive for any E2EE story; without it the server can read every note L P0
Client-side XChaCha20-Poly1305 encryption of note content Obsidian Sync (AES-256-GCM), Syncthing (XChaCha20-Poly1305) The server must be unable to read the vault; XChaCha's 24-byte nonce removes nonce-reuse risk M P0
Argon2id passphrase → KEK, with zeroize on secret buffers age (scrypt), Obsidian Sync (scrypt) Turns "my vault password" into a wrapped VMK instead of a raw secret; Argon2id is the modern choice S P0
Recovery key (printable VMK backup) age key files, restic password files, Obsidian (password is the recovery key) The only path back after losing both the passphrase and a device S P0
Key wrapping to device public keys (X25519) age (x25519 recipient), Syncthing folder keys Pairing a phone must not require re-typing the passphrase M P0
Path/filename encryption with opaque blob ids Syncthing (AES-SIV names + synthetic tree) Today the server stores plaintext path in SQLite; path privacy is the difference between "server is trusted" and "server is blind" L P0
Encrypted manifest (path↔blob mapping) Obsidian Sync (path/content mapping stays server-readable — documented as a limitation) Closes the substitution attack Obsidian documents: a compromised server can currently re-map content to another path L P1
QR device pairing Obsidian Sync / most messengers; qrcodegen crate The spec already says "shown on desktop as QR"; qrcodegen is a 2022-vintage but complete MIT library S P0
Pairing code rate limit + attempt lockout tower_governor (governor backend, axum feature) Brute-forcing a short pairing code is the cheapest attack on the whole system S P0
Access + refresh token lifecycle, rotation, revocation OAuth-style token rotation; tower_governor secure() preset The spec's acceptance criterion demands 401 on a revoked token; the current devices table has no expiry/revocation columns M P0
Audit log (auth, admin, key rotation, export) OWASP Logging Cheat Sheet; the Traefik/Alloy/Loki pattern in the homelab Required to answer "which device did what" after a compromise; the homelab already has a log pipeline to reuse M P0
Device list + "revoke this device" UI Obsidian Sync device management Single-owner, many-devices means a lost phone is a normal event, not an exception S P0
Server-side path guard + reserved-path rejection Already in crates/sync (check_syncable) Already built; keep it as the single source of truth for both client and server S P0 (done)
Health/readiness endpoints k3s probes; Traefik /ping /healthz exists but does not check MinIO/SQLite; a false "ok" hides the outage S P0
Prometheus metrics + structured logs Traefik → Alloy → Loki → Prometheus in the homelab Reuse the existing collector instead of inventing a new sink M P1
Chunked/CDC dedup for large attachments restic (Rabin fingerprint, 64-byte window, 21-bit mask, 512 KiB–8 MiB chunks) Only matters for big attachments; the CDC implementation is the hard part L P1
Resumable uploads (chunked PUT + offset) tus 1.0.0 (HEAD/PATCH/Upload-Offset) Mobile uploads die on network changes; without resume, a 20 MB PDF restarts from zero M P1
Blob GC (janitor over unreferenced blobs) restic prune; MinIO lifecycle rules Unbounded blob growth is the classic sync-server leak M P1
Version history + restore-a-revision Obsidian Sync, restic snapshots, Syncthing versioning "Restore the note I had yesterday" is the feature users miss most once sync exists L P1
Retention policy (tombstone grace, old-version expiry) MinIO lifecycle (--noncurrent-expire-days) Bounds disk growth and defines what the server keeps after a delete M P1
Per-vault quota + 429 with Retry-After MinIO bucket quotas (periodic scanner) MinIO's own docs say the scanner is periodic, so enforce the quota in the app M P1
MinIO/S3 backend via OpenDAL OpenDAL services-s3 (MinIO, versioning, SSE) Decouples the server from local disk and makes replication/backup standard S3 operations M P1
Server backup: bucket versioning + replication + VACUUM INTO snapshot MinIO site/bucket replication; restic repository format Replication requires versioning on both ends; the metadata DB is the piece people forget M P1
Automated restore drill (restore → verify every blob hash) restic check; the CI idiom An untested backup is a hypothesis M P1
Cloudflare Tunnel + Traefik deployment with TLS Cloudflare Tunnel → cloudflared → Traefik pattern No inbound ports on the homelab; the pattern is documented end-to-end M P1
Long-poll-friendly proxy timeouts + client reconnect on EOF Traefik readTimeout guidance in the tunnel guide The wait=25 long-poll breaks behind proxies with short read timeouts S P1
IP-aware rate limiting behind the tunnel (SmartIpKeyExtractor / edge header) tower_governor key extractors Without this, every client shares one token bucket and legit users get 429s S P1
Publish a note as a web page Obsidian Publish (hover previews, graph view, backlinks, themes, password protection) The cheapest "share my thinking" feature and it reuses the server + Markdown already built M P1
Share-to-endpoint web clipper (URL + selection → note) Obsidian Web Clipper (browser extension, templates, highlights) Keeps the client Rust-only: the phone's share sheet and a desktop CLI both hit the same endpoint M P1
Email-to-note "Email to Vault" Obsidian plugin (Mail.tm or own IMAP, templated notes) Receipts and confirmations arrive by mail; capturing them is a real daily-use win M P1
Voice memo transcription whisper-rs 0.16.0 (whisper.cpp) Dictation is the fastest capture mode on a phone; run it server-side so no model ships to the phone M P1
OCR of scanned pages leptess (Tesseract binding) and the young pure-Rust ocr crate Phone-camera notes become searchable text; server-side keeps the binary small M P2
Shared read-only vault links (capability URLs) Obsidian Publish password protection Needs per-link keys separate from the VMK, so a leaked link cannot unlock the vault L P2
Publish + analytics / SEO / custom domain Obsidian Publish Nice-to-have once publishing exists; can be delegated to the edge (Traefik/Cloudflare) S P2
SSO (OIDC/Logto) instead of pairing codes The spec's Open Question 4 Pairing codes are right for one owner; SSO only matters if other humans ever share a vault M P2
Multi-user / shared writable vaults Obsidian Sync teams, Nextcloud Explicitly a non-goal in specs/mobile-and-sync/spec.md L P2

Recommendations — the 10 to build next

  1. Per-vault key hierarchy with client-side encryption. Acceptance: with E2EE enabled, a client-side capture of the server's /changes response and blob bodies contains no readable note text, path or filename, and the same note syncs unchanged across two devices.
  2. Argon2id passphrase wrapping, recovery key and device key wrapping. Acceptance: a new device can be paired by scanning a QR without the owner typing the passphrase, the owner can restore a vault on a clean machine from the printed recovery key alone, and the passphrase never leaves the device.
  3. Encrypted path/blob mapping (opaque blob ids). Acceptance: the server's SQLite contains no plaintext note path, yet GET /files/{path} still resolves for a paired client and a replayed request cannot substitute one note's content for another's path.
  4. QR pairing with rate-limited, attempt-locked one-time codes. Acceptance: a pairing code expires after its TTL, is invalidated after N failed redemptions, and the server answers 401 (not 403) for both expired and non-existent codes so it leaks nothing.
  5. Token rotation and device revocation. Acceptance: after revoking a device, its refresh token stops working and the next request with its access token returns 401 with the client showing "Sign in again" and not touching any file.
  6. Audit log of security-relevant events. Acceptance: the server writes a structured, append-only record for every pairing, token issue/rotate/revoke, quota rejection and admin action — containing device id, request id and result, and never containing a token, key or passphrase.
  7. Health/readiness endpoints and request-id structured logs. Acceptance: /readyz fails when MinIO is unreachable or SQLite is read-only, and every response carries a request id that also appears in the server log line for that request.
  8. Blob GC + retention + version history, with a per-vault quota. Acceptance: after deleting a file and waiting out the grace period, a GC run removes the blob and the quota total drops; an upload that would exceed the quota is rejected with 429 and a Retry-After, and the vault can restore a previous revision of a note.
  9. Resumable uploads and CDC dedup for attachments over 8 MiB. Acceptance: an interrupted 30 MB upload resumes from the last acknowledged offset without re-sending the prefix, and two vaults sharing an identical 30 MB attachment transfer it once, with the equality leak documented in the threat model.
  10. Deployment hardening: Cloudflare Tunnel → Traefik with TLS, plus server backup and a restore drill. Acceptance: the sync endpoint is reachable only through the tunnel with a valid certificate, IP-based rate limiting still distinguishes clients behind the tunnel, and a scheduled job restores the bucket and metadata into a scratch location and fails the build when any blob hash does not match its record.

Adjacent features worth pulling forward if the team has slack, in this order: web clipper via a share endpoint (P1) → email-to-note (P1) → server-side voice transcription (P1) → publish a note as a web page (P1) → OCR (P2) → shared read-only links (P2).


Risks

  1. Scope creep into a secure-multiparty product. The spec's non-goals exclude E2EE multi-user sharing. A full key hierarchy with per-file keys, per-device wraps and rotation is the single largest item in this document; building it halfway is worse than not starting, because a partially encrypted vault that still leaks paths is harder to reason about than a plaintext one.
  2. Metadata leakage survives the content encryption. Even with E2EE, the server learns sizes, change times, device set and edit rhythm. If the notes are sensitive enough that this matters, the fix is not more cipher but less metadata (padding, batching, or a design like Syncthing's) — a different product.
  3. Deterministic vs random trade-off is easy to get wrong. Randomised per-upload keys break dedup; deterministic keys break the AEAD contract if implemented by hand. This must be a reviewed, documented design decision with test vectors, not an implementation detail. Prefer a real SIV over a hand-rolled deterministic AEAD.
  4. Key loss is unrecoverable by construction. Obsidian states it plainly: lose the E2EE password and the remote data is gone forever. The recovery key must be created, displayed and acknowledged at setup time, and there must be a "prove my recovery key works" path — before the first vault is synced.
  5. Locks and rate limits fight the long-poll. GET /changes?wait=25 holds a connection; aggressive per-IP limits plus a proxy with a short read timeout will make sync flaky on mobile. Rate-limit the write and pairing paths hard and the long-poll path barely at all.
  6. Chunking attacks. If CDC is implemented, the chunker polynomial must be random per vault and the chunk→pack mapping randomised; otherwise an attacker who can upload can align boundaries and infer file structure (the restic design doc cites the attack literature).
  7. Unapproved dependencies. chacha20poly1305, argon2, zeroize, rand, age, tower_governor, qrcodegen, whisper-rs and opendal are all new third-party crates and need written owner approval per AGENTS.md. whisper-rs additionally pulls a C++ dependency (cmake, whisper.cpp) and leptess pulls Tesseract + Leptonica, which conflicts with the "pure Rust" spirit of the project — hence the recommendation to run both server-side rather than shipping them in the mobile app.
  8. Server-side processing of user content raises the privacy bar. Running transcription/OCR on the homelab means the server processes plaintext audio and images. With E2EE content encryption, the server cannot read the payloads — so either transcription/OCR must happen on the device (contradicting the server-side plan), or those files must be excluded from E2EE. This is an architectural contradiction to resolve before shipping either feature, not after.
  9. Homegrown protocol drift. A chunked-PUT upload protocol, a custom key-wrap format and a custom capability-token format are three chances to invent a subtly broken scheme. Prefer age for the key-wrap format and document the others as first-party, versioned protocols with published test vectors.
  10. Backup that is never restored. Blobs, the SQLite metadata and the recovery key are three different backup jobs; the recovery key usually lives on paper. The restore drill (recommendation 10) is the only control that catches a silently empty bucket or a metadata snapshot taken mid-transaction.
  11. Cloudflare Tunnel hides the real client IP. Any feature that depends on client IP (rate limiting, lockout, audit) silently degrades to per-tunnel granularity unless the edge header is trusted explicitly at both Traefik and the app.
  12. Mature-crate rot. qrcodegen has had no release since 2022 and the pure-Rust ocr crate is a 1-star project with untrained models. Both are acceptable for their narrow roles, but both need a pinned-version note and an escape plan.

Sources

All URLs accessed 2026 (this research session, 2026-10-20).

E2EE design

Rust crates

Storage, dedup, uploads

Security practice

Deployment

Adjacent features

Local ground truth (not web sources)

  • specs/mobile-and-sync/spec.md, crates/sync/src/*, apps/notescraft-sync-server/src/* in this repository.