Security Whitepaper

Thymer is an offline-first, collaborative editor for notes, tasks, and planning. Workspace content is end-to-end encrypted: it is encrypted on members' devices before it is sent to Thymer, and Thymer's servers do not hold plaintext workspace keys.

This paper explains its security properties: who holds the keys, how a device joins a workspace, what is and is not encrypted, and which threats end-to-end encryption does not address. It also publishes the algorithms and key-management flow used by the current implementation. It focuses on the E2EE design rather than providing an exhaustive account of Thymer's infrastructure and organizational security controls. It is not a formal proof or an independent security audit.

Common questions

Can Thymer employees read my notes? No. Thymer employees cannot decrypt stored workspace content from the data held on Thymer's servers: the content is encrypted, and the plaintext keys needed to decrypt it never reach the servers. The service also stores and can see the account and operational metadata described in §5. As with any application, E2EE does not protect data on a device running malicious or compromised software.

What if I forget my password? Thymer cannot restore access to your encrypted data through an ordinary password reset. Your password is used on your device to derive the key that decrypts your private key, and Thymer has no copy of that decryption key. A Recovery Key lets you regain access and choose a new password, so save it when it is generated and keep it somewhere secure outside Thymer. If you lose both your password and Recovery Key, Thymer cannot recover your private key. A device that is still authorized may continue to provide access, other workspace members may retain shared content, and an enabled Markdown Mirror may have stored local Markdown files.

What can workspace members see? Every approved member receives the workspace key and can read the shared workspace content available to them. Selected personal values receive a separate per-user encryption layer. Roles and permissions are enforced by the service.

1. Security model

A Thymer workspace works like a shared vault in a team password manager:

• Every workspace has a random 256-bit workspace key. It encrypts the workspace's content.
• Every user has their own public/private key pair, generated on their device.
• A separate copy of the workspace key is encrypted to each approved member's public key. When an admin approves a new member, the admin's device, not the server, encrypts a copy of the workspace key for them.
• Each user's private key is encrypted with keys derived from their password. The password never leaves the device.
• The server stores and synchronizes ciphertext. It does not receive plaintext versions of that data, workspace keys, private keys, passwords, Recovery Keys, or export passwords.

End-to-end encryption keeps workspace content encrypted on Thymer's servers and during synchronization. A signed-in member's device must decrypt the content locally so Thymer can provide offline use, search, and editing. Protecting the device and its operating-system account is therefore important too.

2. Cryptographic algorithms

Thymer uses established, publicly documented cryptographic primitives. Symmetric encryption, sealed-box key sharing, and attachment streaming are implemented with libsodium. On the JavaScript client, scrypt, HKDF-SHA256, and SHA-256 are provided by noble-hashes. Thymer does not define a custom cipher, hash function, key-derivation function, or random-number generator.

¹ 32,768 is the current client default and uses approximately 32 MiB per derivation. It is not fixed by the protocol: work factors are stored with each account or export and can be increased without re-encrypting workspace content.

3. Accounts and key flow

Registration starts on the user's device. The client derives a master key from the password with scrypt, separates encryption and authentication material with HKDF-SHA256, and generates the user's X25519 key pair. The server receives the public key and an encrypted private key, but never the plaintext private key.

The diagram combines two stages: registration creates and stores the wrapped key material; login verifies the user and returns the password-encrypted private key for local decryption.

YOUR DEVICE                                :                THYMER SERVER
                                           :
account password                           :
      |                                    :
      |  scrypt (N=2^15 [32,768], r=8,     :
      |          p=1, random 128-bit salt) :
      v                                    :
256-bit master key                         :
      |                                    :
      +-- HKDF-SHA256("AUTHENTICATION")    :
      |             |                      :
      |             +-- authentication value ------------> scrypt + HKDF
      |                                    :                     |
      |                                    :        +------------+------+
      |                                    :        |                   |
      |                                    :        v                   v
      |                                    : stored verifier      wrapping key
      |                                    :                            +
      |                                    :                  encrypted private key
      |                                    :               (uploaded at registration)
      |                                    :                            |
      |                                    :       stored outer-wrapped encrypted private key
      |                                    :                            |  unwrap at login
      +-- HKDF-SHA256("ENCRYPTION")        :                            |
                    |                      :                            |
                    v                      :                            |
          password encryption key          :                            |
                    +                      :                            |
          encrypted user private key <----------------------------------+
                    |                      :
                    |  decrypt locally     :    +-- sealed workspace key
                    v                      :    |   (one copy per member, sealed
             user private key              :    |    to their public key; the
                    +                      :    |    server cannot open it)
          sealed workspace key <----------------+
                    |
                    |  open locally
                    v
          256-bit workspace key
                    |
                    +-- encrypts workspace content and attachments

The server never stores the client authentication value directly. It applies independently salted scrypt and HKDF, stores one derived value as the verifier, and uses another to wrap the already password-encrypted private key. A database attacker therefore cannot use the stored verifier as a login credential and must perform both the client- and server-side derivation for each password guess. This does not replace the need for a strong password.

At login, the client re-derives the encryption and authentication material. After successful authentication, it decrypts the private key, opens the member's sealed copy of the workspace key, and decrypts content locally. A password change re-encrypts the existing private key under a newly derived key; it does not require re-encrypting the workspace.

4. Sharing and membership

Each invitee generates a key pair on their own device. When an admin approves the invitation, the admin's client encrypts the workspace key to the invitee's public key with a libsodium sealed box. The server carries the public key and encrypted result, but never receives the plaintext workspace key.

ADMIN DEVICE                  :     THYMER SERVER       :         NEW MEMBER DEVICE
                              :                         :
                              :                         :     generates key pair
                              :                         :     (keeps private key)
                              :                         :              |
new member public key <--------------------- public key ---------------+
      +                       :                         :
workspace key                 :                         :
      |                       :                         :
      |  libsodium sealed box :                         :
      v                       :                         :
sealed workspace key -----------> store and deliver -----------> sealed workspace key
                              :   (cannot open it)      :                 +
                              :                         :         member private key
                              :                         :                 |
                              :                         :                 |  open locally
                              :                         :                 v
                              :                         :           workspace key
                              :                         :
key fingerprint <========== compare out-of-band (optional) ==========> key fingerprint

Thymer displays public-key fingerprints so the admin and invitee can compare them through an independent channel. Verification is optional, and Thymer does not currently provide a key-transparency log. Without fingerprint verification, an invitation relies on the service not substituting a public key during approval.

Removing a member revokes their service access. When a removed member's client next communicates with Thymer, it is signed out of the workspace. This cannot erase keys or plaintext they previously obtained, including downloaded files or local Markdown files created by an enabled Markdown Mirror. The current implementation does not automatically rotate the workspace key after removal, so removal is an administrative access boundary rather than retroactive cryptographic revocation. If a workspace key ever has to be replaced, the content can be moved into a newly created workspace, which receives its own random key; an export brought into the new workspace, for example through Markdown Mirror, is one way to do this.

5. Encrypted data and visible metadata

Thymer encrypts protected values on the device before synchronization. Authenticated encryption detects modification of an encrypted value. Attachments use authenticated encryption, and attachment filenames are encrypted. Current attachment uploads use authenticated streaming encryption. The server still receives the structural and operational metadata required to synchronize a collaborative workspace.

MEMBER A DEVICE                         :   THYMER SERVER   :      MEMBER B DEVICE
                                        :                   :
protected content or file               :                   :
      +                                 :                   :
workspace key                           :                   :
      |                                 :                   :
      |  XChaCha20-Poly1305 (content)   :                   :
      |  secretstream (current uploads) :                   :
      v                                 :                   :
ciphertext -------------------------------> store and sync ---------> ciphertext
                                        :  (cannot decrypt) :             +
                                        :                   :       workspace key
                                        :                   :             |
                                        :                   :             |  authenticate
                                        :                   :             |  and decrypt
                                        :                   :             v
                                        :                   : protected content or file

The server uses visible structure and property names to synchronize concurrent edits and enforce permissions while treating encrypted values as opaque data. The current cryptographic layer does not provide an end-to-end guarantee against a malicious service replaying an older valid ciphertext or rearranging server-managed structure.

6. Recovery

A Recovery Key is randomly generated on the user's device with approximately 134 bits of entropy and provides a second way to unlock the same user private key. It uses the same scrypt and HKDF construction as the account password, with independent salts and its own encrypted copy of the private key. It lets the user regain access and set a new password without giving Thymer plaintext recovery material. Save the Recovery Key when it is generated and keep it somewhere secure outside Thymer. Replacing a Recovery Key invalidates the previous one. Losing both the password and Recovery Key means Thymer cannot recover the user's private key. Loss of both credentials does not erase existing plaintext copies, however. A device that is still authorized may continue to provide access. In a team workspace, other members continue to have access to shared content, so one member losing both credentials does not make the shared workspace inaccessible to the team. An administrator can re-invite that person with a newly generated key pair, restoring their access to shared workspace content without recovering the lost private key. An enabled Markdown Mirror may also have stored local Markdown files.

7. Local data

Thymer is offline-first. After login, the client stores decrypted workspace data and the keys needed to use it in its local application database; downloaded attachments may also be cached decrypted. OS account security, full-disk encryption, device locking, and backup security therefore remain important. Logging out clears the local workspace database and in-memory workspace keys, it does not guarantee erasure of all browser storage/cache.

8. Threat model and limitations

Thymer uses one symmetric key per workspace rather than per-item keys. It does not currently provide forward secrecy for stored data, automatic workspace-key rotation after member removal, a key-transparency log, or an end-to-end freshness and rollback guarantee. These are distinct properties and should not be inferred from content confidentiality.

Document status

References

• libsodium: XChaCha20-Poly1305, sealed boxes, secretstream
• RFC 8439: ChaCha20 and Poly1305 · RFC 7748: Elliptic Curves for Security · RFC 7914: scrypt · RFC 5869: HKDF
• draft-irtf-cfrg-xchacha: XChaCha20-Poly1305

Questions, or something we should fix? Contact us at [email protected]; we welcome reports about this design and its implementation.