Security Policy

Herkos handles private keys and encrypted messages, so we take security reports seriously and would rather hear about a problem early than late.

Reporting a vulnerability

Please do not open a public issue for security problems.

Report it privately through GitHub's private vulnerability reporting, or by email to [email protected].

Useful things to include: what the problem is, how to reproduce it, which platform and version you tested, and what an attacker could achieve. A proof of concept helps a lot.

Never include your own nsec, secret key or bunker secret in a report.

We aim to acknowledge reports within a few days. Since Herkos is a small project, please allow reasonable time for a fix before disclosing publicly. We are happy to credit you in the advisory unless you prefer otherwise.

What is in scope

The Herkos application itself: key handling and storage, encryption and decryption of messages (including the NIP-59 sender checks and Bcc isolation in local_packages/nostr_mail), the app lock, relay and bridge communication, attachment handling, and the build and release pipeline.

What is out of scope

• The Nostr protocol and its NIPs themselves — report those upstream.
• Relays, bridges and Blossom servers operated by third parties. Herkos ships with defaults but does not run them; report issues to their operators.
• The upstream project Nostr Mail Client, unless the issue is specific to changes made in Herkos.
• Missing hardening that we already document as a known limitation (see below).

Known limitations, stated plainly

These are design trade-offs, not vulnerabilities. We would rather write them down than have someone discover them the hard way:

• Mail to traditional addresses is not end-to-end encrypted. Messages between Nostr users use NIP-17 gift-wrap and are E2E encrypted. When you write to a regular email address, a bridge converts the message and can read it.
• The app lock (PIN and biometrics) is a convenience barrier, not encryption at rest. It stops someone who picks up an unlocked device; it does not protect against an attacker with full access to the device or its storage.
• On Windows, biometric-only authentication cannot be enforced. Windows Hello does not allow selecting the method, so the system PIN always remains available as a fallback.
• Losing your key means losing the account. There is no recovery, by design.
• Metadata is not fully hidden. Relays can observe connection patterns even when they cannot read message contents. In particular, when Herkos looks up where to deliver a message (the recipient's DM relay list) on a relay that requires NIP-42 authentication, it authenticates with your key, so that relay can see that you are about to write to that recipient. Fixing this needs the per-request identity control of NDK 0.9 (the upstream SDK does it since nostr_mail 3.1.0); it is on the roadmap.
• With several accounts on one device, a relay's NIP-42 challenge is answered by the account that is logged in when it arrives, which during an account switch can be a different one than the account whose data was requested. Same root cause and same fix as above.
• Read state and folders are public metadata (for now). Marking an email as read, starred, archived or moved publishes an unencrypted NIP-32 label event tied to your public key, including custom folder names. A sender who knows the id of an email they sent you can tell when you acted on it. Encrypting these labels is planned; until then, treat folder names as public.
• Push notifications and scheduled sending use third-party services. The push server (api.nmail.li by default) learns your public key, a push token and when you receive mail; the scheduler DVM learns your public key and the already-encrypted messages it must publish. Both are opt-in and documented in PRIVACY.md. The text of a push notification is chosen by the push server; on the Google-services build it passes through FCM in the clear, and on UnifiedPush it is only trusted when it arrives encrypted (RFC 8291).
• Bridged mail is only as trustworthy as the bridge. Herkos verifies that a message marked as coming through a bridge really was signed by a bridge you have configured (or one of the defaults). It cannot verify anything about the legacy From: address the bridge relays.
• Attachments are opened by the operating system. Herkos never launches executable or script file types and asks before handing any other non-previewable attachment to the system default app, but the app that opens the file is outside our control.

Supported versions

Security fixes are applied to the latest released version. Given the size of the project, older versions are not maintained — please update before reporting.