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 by email to security@herkos.email.

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, and every relay sees your IP address, even when they cannot read message contents. What Herkos does not give away (since 30-09-2026) is who is writing to whom when a relay asks for NIP-42 authentication:
• Looking up where to deliver. A recipient's relay and Blossom lists are asked for on a separate connection that never identifies you, first on relays that do not require authentication (purplepag.es, user.kindpag.es, nos.lol, offchain.pub).
• Profiles and the scheduler. The name and picture shown for anyone else (kind 0), and the relay list of the scheduler DVM when you schedule or cancel an email, are asked for the same way: anonymously first and, if a relay insists, with the temporary key described below, never with yours (since 01-10-2026; before, a relay that asked for authentication got your key, and could tell whose profile you were looking at). Only your own profile is still read as you.
• Delivering. Gift wraps go to the recipient's DM relays, on that same separate connection. If one of them requires authentication, Herkos answers with a key made for the purpose and kept only in memory, never with yours; each account on the device has its own. The relay can still see that the same device (same IP, same temporary key) sent several envelopes during a session.
• Large emails. The encrypted copy of an email over 32 KB is uploaded to Blossom servers, including the recipients'. Only your own servers (your Blossom list) get the upload authorised with your key. Any other server gets it anonymously and, if it insists on an authorisation, one signed with the same temporary key as above (since 01-10-2026; before, every server got your key). A server that only accepts known keys refuses it, and the copy stays on the other servers.
• Your own data. Syncing your mailbox, labels, settings and drafts authenticates, where a relay asks, as the account the data belongs to, even during an account switch. On your own relays that tells them nothing they did not know: the requests name your key anyway. Your own relay and Blossom lists are public and are asked for without identifying you, and so are relays named in an email link.
• 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, and Herkos only trusts it when UnifiedPush delivers it encrypted (RFC 8291); an unencrypted payload only wakes the app up to fetch the mail itself.
• The web version keeps your key in the browser, which is the weakest place for it. The installed apps hand your secret key to the operating system's secure storage (Android Keystore, Windows Credential Manager, libsecret, the iOS/macOS Keychain). A browser has none of that: the key sits in the origin's storage and passes through JavaScript on every signature, within reach of any code that runs in the page — a browser extension with access to every site, an XSS bug in the app or in a dependency, a tampered deployment — and of any infostealer that copies the browser profile. There is also no moment where you verify the code once: a signed binary is checked at install time, while a web page ships fresh code on every visit. Log in to the web version with a remote signer (NIP-46 bunker, Amber), so the key never reaches the browser, or treat it as a throwaway identity and keep your real key in an installed app.
• 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.