---
title: "Security policy"
description: "Security policy for OneSend: response times for reports, supported versions, scope, and the hardening checklist for self-hosted installs."
url: https://onesend.email/security/policy/
---
# Security policy

## Reporting a vulnerability

Report security vulnerabilities privately, never in a public issue. How to report, and what to include, is on the [security page](https://onesend.email/security/#reporting-a-vulnerability).

## What to expect

- We aim to acknowledge reports within 3 business days.
- We aim to send an initial assessment within 10 business days, including whether we consider the report a vulnerability and its severity.
- We aim to release a fix within 90 days of the report, sooner for critical issues, and keep you informed of progress.
- We credit reporters in the release notes unless you ask us not to.

Please give us reasonable time to fix the issue before disclosing it publicly. We will not take legal action against good-faith research that follows this policy, avoids privacy violations and service disruption, and does not access or change other users' data.

## Supported versions

OneSend has not had a stable release yet. Security fixes are made on the `main` branch and included in the next release.

| Version | Supported |
|---|---|
| `main` (latest commit) | Yes |
| 0.1.x | Yes, until 0.2.0 is released |
| Older | No |

After a 1.0 release, this table will list which release lines receive security fixes.

## Scope

In scope: the code in this repository, including `apps/server`, `apps/web`, `apps/mcp`, `apps/worker-cf`, the Mac app, the website, `packages/*`, the private modules (the inbox, the cloud services and their dashboards) and the gallery templates.

Out of scope:

- vulnerabilities in third-party email providers or their APIs;
- self-hosted deployments that do not follow the [self-hosting reference](https://onesend.email/docs/self-hosting/), for example SMTP ingress exposed to the internet without TLS, or a missing `ONESEND_SECRET` backup;
- reports from automated scanners without a demonstrated impact;
- the unrelated npm packages under the `@onesend` scope. This project has not published any packages to npm.

## Leaked API keys

API keys created since migration 0030 end in a 6-character checksum: `os_live_` (or `os_test_`, `os_pub_`), 32 random base64url characters, then the CRC-32 of everything before it in base64url. Secret scanners can check a candidate offline (`isWellFormedKey` in `packages/core/src/crypto.ts`); this repository's own secret scanning rules match both this format and older keys without the checksum. Older keys keep working.

Contain a key before it leaks: give it an expiry (`expiresAt`, then 401 `key_expired`), limit it to your servers' addresses (`allowedIps`, IPv4 and IPv6 addresses and CIDR ranges, then 403 `ip_not_allowed`), and limit what it can send to (`recipientAllowlist`, `limits`). The API keys page shows where each key was last used from. Rotate a key with **POST /v1/api-keys/{id}/rotate**: you get a new secret for the same key, and the old one keeps working for a grace period (24 hours by default, at most 7 days) while you deploy the new one. Workspace owners get an email when a key is created, rotated, revoked or reported as leaked, when a key changes configuration, and when a key is used from a new address (`ONESEND_SECURITY_ALERTS`). A leaked key cannot silence those alerts: Sandbox mode and pausing providers need a signed-in admin, system email ignores suppressions added by hand or through the API and cannot be canceled with a key, alerts the workspace cannot deliver go through the server's alert mailer (`ONESEND_ALERT_SMTP_URL`) and always to a dashboard banner for the owners, and throttled alerts are sent as an hourly digest (see [Security alerts](https://onesend.email/docs/self-hosting/#security-alerts)). When a key is revoked or reported as leaked, these stop with it: the inbox rules it set up that forward outside the workspace or call a webhook, the outside forwarding and webhooks it set on mailboxes, and the webhook steps of automations it created or added them to (once more a couple of minutes later, for something a request already running set up); the keys it created or rotated, recursively, until none is left (one alert gives their number; a very large chain finishes in background jobs and the alert says so); and the invitations it sent, with the members who joined through them, and in turn the invitations those members sent and the members who joined through them (prior members and the owner are kept). Turning that setup back on needs an admin. Not everything a key did that sends data out stops: webhook endpoints (`/v1/webhooks`), sending connections and domains it added, and campaigns it scheduled keep working, and role changes it made to existing members stay. A key can have at most 100 keys it created that are not revoked, expired ones included (`ONESEND_MAX_KEYS_PER_KEY`, 400 `too_many_keys`), and can rotate only itself and the keys in its own creator chain.

**An Admin key is a root credential for the workspace**: it can change the configuration, invite people, change roles and manage keys, and what it adds to the configuration remains after it is revoked. Use Sending only or Full access keys for applications, create Admin keys only when needed and always with `expiresAt` and `allowedIps`, and after revoking one, review the audit log for the webhooks, connections, domains, campaigns and role changes it made (see [Team and account security](https://onesend.email/docs/team/#revoking-a-key)).

### Leaked key report endpoint

`POST /v1/security/key-leak-report` accepts reports of keys found in public, in the request shape that secret scanning services commonly use. It is not part of the OpenAPI document (it is called by scanning services, not by API clients):

```json
[{ "token": "os_live_…", "type": "onesend_api_key", "url": "https://example.com/commit/abc", "source": "commit" }]
```

(`{ "tokens": [ … ] }` is accepted too; at most 100 per request.) A report is accepted when it carries one of:

- the shared secret in `ONESEND_LEAK_REPORT_SECRET`, as `Authorization: Bearer <secret>`;
- or `X-OneSend-Signature: sha256=<hex HMAC-SHA256 of the raw request body, keyed with the secret>`;
- or an ECDSA P-256 / SHA-256 signature of the raw body, base64 (DER), in `Github-Public-Key-Signature` (with `Github-Public-Key-Identifier`), made by one of the PEM public keys in `ONESEND_LEAK_REPORT_PUBLIC_KEYS` (see [Secret scanning partner programs](#secret-scanning-partner-programs)). The server never fetches keys.

Every other request gets 401 `leak_report_unauthorized`, and so does every request while neither variable is set. Use at least 32 random characters for the secret (`openssl rand -hex 32`); the server warns at startup about a shorter one.

For each token that is a working key of this server, the key is revoked at once (for a rotated key's old secret still in its grace period: when a signed-in person made the last rotation, only that old secret stops, `api_key.leak_previous_secret_revoked`; when an API key made it, possibly whoever held the leaked secret, the whole key is revoked), the action is recorded in the workspace's audit log (`api_key.leak_revoked`), inbox rules and mailbox forwarding the key set up that send mail outside the workspace are turned off, the keys it created are revoked too (recursively until none is left, `api_key.revoked` with reason `creator_key_leaked`), the invitations it sent are canceled and the members who joined through them removed (`member.removed` with reason `invited_by_revoked_key`), and the workspace owners get an email with the reported location. Conversion tracking keys (`os_pub_…`) are meant to be public and are not revoked. The answer lists each token with `label`: `true_positive` (a working key of this server) or `false_positive`, and `revoked`.

### Secret scanning partner programs

No secret scanning partnership is in place yet: registering the key format with a scanning service's partner program is a step for the project's owner. Reports signed by such a program are accepted once its public keys are configured on the server (see the leak report endpoint above).

## Hardening checklist for self-hosted installs

- Set `NODE_ENV=production` and a generated `ONESEND_SECRET` (`openssl rand -base64 32`), and store it as a secret, not in a config file.
- Set `ONESEND_PUBLIC_URL` to your HTTPS URL, put a reverse proxy with TLS in front of the HTTP port, and set `ONESEND_TRUST_PROXY` to the number of proxies (`true` for one) so rate limits see real client addresses.
- Configure `ONESEND_SMTP_TLS_KEY` and `ONESEND_SMTP_TLS_CERT` before exposing SMTP ingress, or keep it on a private network.
- Keep `ONESEND_SIGNUP=first-user` (the default) unless you want anyone to create accounts, and create the owner account before the instance is reachable from the internet: on a fresh instance the first visitor becomes the owner. With `ONESEND_SIGNUP=closed`, the owner account can be created only from the server itself.
- Never set `ONESEND_DNS_OVERRIDES` outside development; the server refuses it when `NODE_ENV=production`.
- Run the MCP server in HTTP mode only behind HTTPS, with each client sending its own API key, and with `ONESEND_MCP_ALLOWED_HOSTS` set to its public host name.
- Give each integration its own API key with the narrowest permission (Sending only or Read only), and revoke keys you no longer use. Use Conversion tracking keys (`os_pub_…`) in web pages, never secret keys. Give server keys an expiry and the addresses of your servers (`allowedIps`).
- With several server processes, set `ONESEND_RATE_LIMITER=database` so rate limits are shared.
- Keep SMTP port 2587 on the loopback interface when you use the bundled `docker-compose.yml`, which allows AUTH without TLS by default (`ONESEND_SMTP_ALLOW_INSECURE_AUTH=false` in `.env` turns that off). Behind a same-host TCP proxy, configure TLS. See [SMTP](https://onesend.email/docs/smtp/#tls).
- Verify webhook signatures in your app. See [Webhooks](https://onesend.email/docs/webhooks/#verifying-signatures).
