- 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>
46 KiB
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:
Argon2idover the owner's passphrase with a per-vault random salt → 32-byte key-encryption key → wraps the VMK.agealready models this shape (scrypt::Recipientwraps a random file key under a passphrase;x25519::Recipientwraps 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
copyto 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,
seqnumbers; - 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:
chacha20poly1305XChaCha20-Poly1305 (audit-grade, random 24-byte nonce, no nonce-reuse risk across a whole vault). Choose. - KDF:
argon2(Argon2id) for passphrase → KEK. Choose. Usezeroizeon every buffer that holds a key, passphrase or plaintext. - RNG:
getrandom/OsRngfor all secrets;randonly for non-secrets. Choose. - Key wrapping:
ageif we want an interoperable file format for vault-key backup and device-key export; otherwise a 100-linex25519+ XChaCha20 wrap is enough.ageis the lazier path because it already exists and is maintained. - Deterministic encryption of names: Syncthing uses AES-SIV. If the RustCrypto
aes-sivcrate 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-argon2for key derivation (it does not clear work memory) and do not userandfor 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}/revokesetsrevoked_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:
- Do not construct the same
GovernorConfigtwice — each config is an independent limiter. - Behind Cloudflare Tunnel the peer IP is the
cloudflaredpod IP, soPeerIpKeyExtractorwould put every client in one bucket. UseSmartIpKeyExtractor(or a custom extractor readingCF-Connecting-IP/X-Real-Client-Ipset by the edge). 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:
- 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. - Dedup only within a file (safe) plus whole-file dedup by hash of the encrypted blob (also leaks equality, but only of whole files).
- 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 (
POSTcreate +HEAD/PATCHupload). 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
PUTwithContent-Rangeplus a server-sideuploadstable (upload_id,path/blob_id,offset,length,expires_ms). Pros: reuses the existingPUT /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_idis 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
filestable 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
429with aRetry-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:
- 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.
- 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. - 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
/healthzalready exists inroutes.rs. Add/readyzthat 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 (
prometheusvsmetrics). - 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=25is 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:
cloudflaredruns inside the cluster, so there are no inbound ports and no public IPs; DNS CNAMEs point at the tunnel's*.cfargotunnel.comaddress.- Each hostname maps to the Traefik service with
origin_server_nameset so cloudflared presents the right SNI, plushttp2_origin = true. - Traefik must trust Cloudflare's IP ranges in
forwardedHeaders.trustedIPs, otherwiseX-Forwarded-Foris stripped and every request appears to come from thecloudflaredpod. 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.requestHeaderNamepointing at the header the edge sets — otherwise every client shares one bucket, as noted above. - Timeouts vs long-poll: the guide sets
readTimeout=60sandwriteTimeout=0s(disabled) because long-lived connections get killed otherwise. NotesCraft'swait=25long-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-IPorX-Real-Client-Ip), notRemoteAddr.
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/clipon 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-rs0.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-Rustocrcrate (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
- Per-vault key hierarchy with client-side encryption. Acceptance: with E2EE enabled, a client-side capture of the server's
/changesresponse and blob bodies contains no readable note text, path or filename, and the same note syncs unchanged across two devices. - 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.
- 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. - 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.
- 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.
- 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.
- Health/readiness endpoints and request-id structured logs. Acceptance:
/readyzfails 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. - 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. - 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.
- 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
- 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.
- 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.
- 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.
- 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.
- Locks and rate limits fight the long-poll.
GET /changes?wait=25holds 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. - 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).
- Unapproved dependencies.
chacha20poly1305,argon2,zeroize,rand,age,tower_governor,qrcodegen,whisper-rsandopendalare all new third-party crates and need written owner approval perAGENTS.md.whisper-rsadditionally pulls a C++ dependency (cmake, whisper.cpp) andleptesspulls 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. - 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.
- 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
agefor the key-wrap format and document the others as first-party, versioned protocols with published test vectors. - 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.
- 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.
- Mature-crate rot.
qrcodegenhas had no release since 2022 and the pure-Rustocrcrate 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
- Syncthing, Untrusted Device Encryption (spec) — https://docs.syncthing.net/specs/untrusted.html
- Syncthing, Untrusted (Encrypted) Devices (user guide) — https://docs.syncthing.net/users/untrusted
- Syncthing,
lib/protocol/encryption.go— https://github.com/syncthing/syncthing/blob/main/lib/protocol/encryption.go - T-shaped, Understanding and verifying Syncthing's untrusted peer encryption (2024) — https://t-shaped.nl/untrustedpeerencryption
- Obsidian, Security and privacy (Sync encryption, deterministic hash, path/content binding limits) — https://obsidian.md/help/sync/security
- Obsidian, How to verify Obsidian Sync's end-to-end encryption (scrypt + HKDF + AES-256-GCM) — https://obsidian.md/blog/verify-obsidian-sync-encryption/
Rust crates
chacha20poly13050.11.0 — https://crates.io/crates/chacha20poly1305 (and https://docs.rs/crate/chacha20poly1305/latest)- RustCrypto/AEADs,
chacha20poly1305 v0.11.0release notes (MSRV 1.85, edition 2024) — https://github.com/RustCrypto/AEADs/commit/e37a978ccf0992d9053fbc039470d6527108e393 argon20.6.0 (RustCrypto) — https://docs.rs/crate/argon2/latest and https://docs.rs/argon2/latest/argon2/rust-argon23.0.0 (sru-systems) — https://crates.io/crates/rust-argon2rand0.10.3 — https://crates.io/crates/randzeroize1.9.1 — https://crates.io/crates/zeroizeage0.12.1 — https://crates.io/api/v1/crates/age (crate metadata; docs at https://docs.rs/age/latest/age/)qrcodegen1.8.0 — https://crates.io/crates/qrcodegen (and https://docs.rs/qrcodegen/latest/qrcodegen/)tower_governor0.8.0 — https://crates.io/crates/tower_governor (and https://docs.rs/tower_governor/latest/tower_governor/)whisper-rs0.16.0 — https://crates.io/crates/whisper-rsopendal-service-s30.58.2 — https://crates.io/crates/opendal-service-s3 (and https://opendal.apache.org/docs/rust/opendal/services/struct.S3.html)leptess(Tesseract/Leptonica bindings) — https://github.com/houqp/leptess- Pure-Rust
ocrcrate (early project) — https://github.com/yingkitw/ocr
Storage, dedup, uploads
- restic, Foundation — Introducing Content Defined Chunking (CDC) (Rabin fingerprint, 64-byte window, 21-bit mask, 512 KiB–8 MiB chunks, random polynomial) — https://restic.net/blog/2015-09-12/restic-foundation1-cdc/
- restic, Repository design (storage ids, write order, pack layout, threat model) — https://github.com/restic/restic/blob/master/doc/design.rst
- tus resumable upload protocol 1.0.0 — https://tus.io/protocols/resumable-upload
- tus implementations (incl.
rustus) — https://tus.io/implementations - MinIO, Object Lifecycle Management (expiry, noncurrent versions, delete markers, tiering) — https://minio.community/community/minio-object-store/administration/object-management/object-lifecycle-management.html
- MinIO, What You Configure on a Bucket (versioning, object lock, replication, quotas, QoS) — https://docs.min.io/aistor/administration/bucket-configuration/
Security practice
- OWASP, Logging Cheat Sheet (security events, "when/where/who/what", data to exclude, tamper protection) — https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
Deployment
- Erfi's Lexicanum, Traefik on k3s: custom deployment, plugins, middlewares, and Cloudflare Tunnel (trusted CF ranges,
X-Real-Client-Iprate-limit criterion, timeouts) — https://erfi.dev/guides/k3s-traefik/ - TheDougie, Expose K3s Services Safely with Cloudflare Tunnels and Traefik — https://www.thedougie.com/cloudflared-traefik-k3s-setup/
Adjacent features
- Obsidian Publish (product page: features, password protection, custom domain, analytics) — https://obsidian.md/publish?pubDate=20250311
- Obsidian Web Clipper (templates, highlights, local storage, export) — https://obsidian.md/clipper
- Obsidian community plugin, Email to Vault (Mail.tm / IMAP, templated notes, attachments) — https://community.obsidian.md/plugins/email-to-vault
- vault-bridges, Obsidian Email Plugin (SMTP → API → note) — https://github.com/vault-bridges/obsidian-email-plugin
Local ground truth (not web sources)
specs/mobile-and-sync/spec.md,crates/sync/src/*,apps/notescraft-sync-server/src/*in this repository.