互联同步指南Encrypted sync guide
配对、设备、手机访问与冲突Pairing, devices, phone access and conflicts

The problem it solves

All of Novara's data lives on one Windows computer. To look up a password, tick a to-do or add a record while on the move, a second screen needs to see the same vault. That is exactly what encrypted sync solves: turn one of your own machines (a Windows PC, a NAS or a VPS) into a small relay, and both the desktop app and your phone's browser exchange data with it.

First, the boundary: if you do not need cross-device access, you can simply skip this. Every local feature works without a server, and no core feature requires being online.

Three parties and what each holds

In one sentence: the server is essentially an encrypted file store with version history. It reads envelope metadata to arbitrate conflicts and quotas, but never parses payload contents.

What end-to-end encryption means here

• Data is encrypted before it leaves the computer (v4 container, AES-256-GCM).
• The server relays only ciphertext blobs, keywrap records and necessary metadata — it cannot open anything.
• The real key, the SpaceKey, is generated by the first paired PC; the server never holds it in plaintext form.
• Decryption happens only inside a client runtime you authorize: desktop memory, or your phone browser's memory.

Although the space key's wrapping record (keywrap) sits on the server, it is encrypted with your lock password — without that password, the record on the server is just ciphertext that will not open.

What if the connection drops

Your Windows local vault is the authoritative copy. A powered-off server, a broken tunnel or an expired domain only means "no cross-device access for now" — the desktop keeps organizing, searching and editing as usual. When the connection returns, the sync engine reconciles by version; nothing is lost.

A few words used in this guide

• Space: the container for one sync dataset, created by a one-time CLI command, with its own space id.
• Pairing: joining a device to a space; requires the space id and the enrollment secret.
• SpaceKey: a 256-bit random key from which every version's encryption key is derived; generated by the first paired PC.
• Enrollment secret: the one-time credential printed when the space is created, used for device registration.
• Read-only token: a 24-character credential for phone browsing — read access only, revocable at any time.
• Edit credentials: credentials for the web editor that may modify data, mapped to a virtual "web-editor" device.
• Tombstone: the sync marker for deletion, ensuring "it was deleted" reaches every device too.

FAQ

The complete list

The table below lists, item by item, how the NovaraSync server relates to your data. The source of truth is the server security baseline maintained with the code (deploy/SECURITY.md); any implementation violating one line of it is a defect.

Log discipline

The server security baseline makes log redaction a top-priority prohibition: Authorization headers (device tokens, read-only tokens), blob contents, enrollment secrets, and token or edit-credential plaintext are never allowed into logs or error messages.

Auditing and logs record metadata only: which space, which device, what action, the result, byte counts, timestamps. The current server version ships no application-level log at all — the constraint is written for the future: any new log line must not carry the items above; debug logs may record shape only (lengths, hash prefixes, status codes), never content.

Where this data lives

How to check it yourself

• All /api responses carry Cache-Control: no-store set by the server — true even when bypassing the reverse proxy.
• The redirect for /web (no trailing slash) is a relative address, not built from the request Host — if you see no internal address, it is correct.
• Security response headers such as CSP are emitted by the server on every response — present even through tunnels that bypass the reverse proxy (like a temporary review channel).
• The whole data directory can be copied away directly — it is all ciphertext; still, treat it as sensitive files.

Before you start

• The server is running (any path from the self-hosting guide works; Windows direct-run is fastest).
• You have the space id and the enrollment secret — the two strings printed when the space was created.
• The desktop app is Novara 9.0 or later.

Pairing steps

1. Open the pairing dialogNovara desktop → hamburger menu → Tools → Encrypted sync → Pair.
2. Fill the server addressThe public address, e.g. https://sync.example.com. Must be https; only loopback addresses may use http.
3. Fill the space idThe first string printed by the space-create command, pasted as-is.
4. Fill the enrollment secretThe second string printed by the space-create command, pasted as-is.
5. Leave the space key empty, click PairThe local device name is free-form (used to recognize this machine in the device list). On success a dialog says "store the sync space key safely".

Why the space key stays empty

At the moment pairing succeeds, the desktop generates a 256-bit random SpaceKey, wraps it with this machine's vault password and uploads it (that is the keywrap record), then shows "store the sync space key safely". This key is the only credential for later devices to join — the server has only the ciphertext form and cannot recover the plaintext.

So the pairing dialog's rule is: empty = create the space (first device), filled = join an existing space (second and later). Two machines usually have different vault passwords and cannot unwrap each other's keywrap records, so the space key can only be read from the device that created it.

One easy trap: the same data directory

The space-create CLI writes credentials into the directory pointed to by the NOVARA_SYNC_DATA environment variable (when unset, data under the current working directory). It must be the same directory the server uses — otherwise the credentials land elsewhere, the server never sees the space, and pairing fails by construction.

The bundled 1-建空间.cmd and 2-启动服务端.cmd scripts already handle this: both point to %LOCALAPPDATA%\Novara\Server\data. On the Docker Compose path, docker compose run --rm novara-sync space create mounts the same ./data as the server.

After pairing

Once paired, the same encrypted-sync card can issue a read-only token and edit credentials for your phone (see "Read-only mobile access"), and this machine appears in the device center for management at any time (see "Add more devices"). The first sync round pushes the whole local vault up.

Read this first

What a second device needs

The pairing flow is identical to the first device; the only difference is that the space key field carries the key shown on the creating device.

Where to see the space key

• On a paired device: Settings → Encrypted sync → View space key (asks for this machine's lock password).
• Or import a previously exported .novakey backup file — display-only and copyable; it never writes itself into any configuration.

A .novakey file contains a keywrap record (JSON), not a v4 encrypted container — it cannot be imported as a database backup; the extension is deliberately distinct from .novaenc for exactly this reason. The file's passphrase is the exporting device's lock password at that time: after a password change, the old file still corresponds to the old password — inherent to backup files.

Where device tokens live

After successful pairing, this machine's device token is stored in the Windows Credential Locker (PasswordVault, DPAPI-protected), bound to the current Windows user — a new computer or a new user means pairing again; the token does not travel with files. The SpaceKey likewise lives only in memory and the credential locker; it never hits disk with sync data.

Device center: revoke and reset are different

The device you are currently using cannot revoke itself — the server refuses outright, and the local row in the UI only offers "reset token". Not a UI limitation but a guardrail: revoking yourself would cut you off on the spot, and rejoining would require pairing again.

There is no device count limit. Computers and the web editor each count as one device, each manageable individually in the device center.

FAQ

When sync runs

The desktop's sync is governed by the master switch and runs automatically at the interval you pick in settings; writing to disk can also trigger it as needed. To push a round right now, click "Sync now" on the encrypted-sync card. Every action lands in the local audit log (never any plaintext or credentials).

No sync while locked: the manual lock, the idle auto-lock and the Windows lock-screen linkage all pause sync first — no network while locked is a hard rule, never bypassed because "the server has a newer version".

How uploads are protected

• Each upload carries the base version (If-Match semantics): "I edited based on version N" declares N.
• If the server is already at N+1 or higher → it refuses with 409 version_conflict, including the current version number (no plaintext).
• The payload's SHA-256 digest is checked first, then a constant-time HMAC comparison — a container with tampered metadata never reaches disk.

When a stale version is refused, the client does not silently push the newer content over. Conflict is explicit: you inspect the difference and decide.

How a conflict is resolved

When the desktop opens the conflict panel it shows a per-area diff summary (which areas each side changed), then offers several exits:

• Export both versions — export the local and the cloud version as separate v4 encrypted files; compare or restore either later.
• Take the cloud version — discard the un-pushed local changes and pull the cloud's current version.
• Explicit force overwrite — push the local version over the cloud one; double confirmation required.

On the web side (browser editing), a 409 keeps your edits in memory: you can copy the JSON, export a .novaenc (default; the desktop can restore it directly), export plaintext JSON (double confirmation), force overwrite (double confirmation), or drop this page's changes and take the cloud version. Before a refresh with un-pushed changes, the browser also warns.

Retention and quotas

A full space returns 507 quota_exceeded with usedBytes and limitBytes in the error body — "used / limit" is exactly what you need before deleting old versions or raising the quota. All defaults are adjustable through environment variables (see "Server environment variables").

FAQ

Issue a read-only token

1. Open read-only accessDesktop → Settings → Encrypted sync card → Read-only access.
2. Click "Generate"You get a 24-character token, shown in six groups: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX.
3. Save it on the spotThe plaintext is shown exactly once — the server stores only a hash; once the dialog closes it is gone for good.

The token alphabet deliberately excludes I, L, O and U (Crockford base32): if you copy 1 as I or 0 as O, input is folded and corrected automatically. On the phone, lowercase, hyphens and stray spaces are all fine.

Two always-available switches: regenerate instantly kills the old token and old links (the button's own label states the consequence); revoke immediately cuts every session using the token — the button to press when the phone is lost.

What the link looks like

• The space id sits in the # fragment: it is never sent to the server, never lands in server logs, never in Referer. It is a locator, not a credential.
• The link carries no token and no passphrase. Sharing the link ≠ sharing access — whoever opens it still needs the token and your lock password.
• The desktop generates and copies the link; the easiest way to move it to the phone is sending it to yourself (any messenger or email) rather than typing a long URL.

Opening it on the phone

1. Tap the linkThe unlock page opens with two fields: token + passphrase.
2. Enter the tokenThe 24-character read-only token from before (normalized automatically).
3. Enter the unlock passwordThis is the Novara unlock password that wraps the space key — not the phone's password, not anything else.
4. BrowseAll four areas are browsable with search and TOTP codes; the interface has no edit, delete or create controls anywhere.

Both credentials are required: the token is only a door pass and decrypts nothing; the actual decryption happens in phone memory with your unlock password.

Want to see what the reader looks like first? The snapshot guide ships two live demos (demo data, passphrase 000000): Chinese demo · English demo — the web reader looks just like them.

Why HTTPS is mandatory

The browser's crypto (crypto.subtle) is only available in a secure context. Open a non-loopback address over http:// and the page plainly says "this browser does not support the required encryption capability" — not a blank screen, not a malfunction. Same when a self-signed certificate is not trusted by the phone: tapping "continue anyway" does not get around it; you must install the CA and enable full trust.

The server enforces its own side: API requests that are neither HTTPS nor loopback are refused with 403 and the exact error https is required for api requests. Phone and server reject plaintext symmetrically — there is no path where credentials are "quietly accepted".

Limitations, stated honestly

The server: what it holds, what it can do

So a server administrator can delete ciphertext and cause unavailability, but cannot read plaintext. Availability and confidentiality are two different things here: backups address the former, password strength the latter.

The one genuinely weak spot

Someone holding "a keywrap record + a token" can brute-force your unlock password offline. The wrapping uses PBKDF2-SHA256 at three million iterations (about 0.3 seconds per try) — that cost is the gate, and it is the only gate.

Two kinds of credentials, judged separately

• A leaked read-only token → the holder still needs your password to see anything, and can only read.
• A leaked edit credential → the holder can overwrite the cloud's ciphertext (availability damage), but still never sees plaintext — each version's integrity is protected by a keyed MAC, and they cannot forge a version your computer would accept.
• On any leak, revoke: read-only tokens revoke instantly; edit credentials can be revoked by removing that web-editor device.

Standing defenses in transport and logs

• Transport is TLS (terminated at the proxy); the server adds its own gate — non-HTTPS, non-loopback API requests get 403, so credentials are never "accepted in plaintext".
• All /api responses carry Cache-Control: no-store; security headers (CSP etc.) are emitted by the server on every response — protected even on paths bypassing the proxy.
• The log prohibition is written into the security baseline: tokens, credentials and blob contents never enter logs; audit records metadata only (who, when, what action, result, byte counts).
• Every secret comparison is constant-time; auth failures are rate-limited by counted keys and windows.

Beyond the app boundary

Stated honestly, these threats are outside Novara's reach:

• An unlocked host: screen recording, keyloggers and malicious browser extensions see what you see — as with any local app.
• Cloud AI clients: if an agent you authorized via MCP sends what it read to its model provider, that is that client's responsibility boundary; Novara's redaction and audit still applied on its side.
• Deployer responsibility: HTTPS, server patching, backup policy, managing the domain and public exposure — belong to whoever runs the server, which is you.

• No server deployed yet → the sync deployment guide (Windows / Docker / NAS / VPS, every path)
• Just want to "look something up" → the secure snapshot guide is simpler