Encrypted-at-rest storage for plugin secret settings

[minemeraj]

Summary

Plugin settings declared with type: "secret" are stored in the database as plaintext. The secret type only masks the field in the admin UI; it does not encrypt the value at rest. I'd like EmDash to support encrypting secret-typed settings before they're persisted (and decrypting on read), so plugins can accept API keys and other credentials through the admin settings form without those credentials sitting in the database in cleartext.

Motivation

Several plugins legitimately need to store credentials that an operator enters in the admin UI — for example email providers (Resend/SES API keys), OAuth client secrets, or webhook signing keys. Today the only "safe" place for those is a Worker/environment secret, which means those values can't be managed from the admin UI and require a redeploy to change.

The auto-generated settings form + secret field type is exactly the right UX for this, but because the stored value is plaintext, using it for real credentials means anyone with database read access (a D1/SQLite dump, a leaked backup, an unrelated SQL-injection, a support engineer with DB access) can read every stored secret. For something like a session-signing key this is the difference between "annoying to rotate" and "attacker can forge sessions."

Current behavior (as I understand it)

• The SettingField union includes secret, and the admin renders it as a masked input.
• Values are persisted to the shared plugin settings/KV store (_plugin_storage / the options table) as plain strings.
• I couldn't find any encrypt/decrypt path around settings persistence in the runtime — secret appears to be a display concern only.

If I've misread this and there's already encryption I missed, please point me at it and I'll close this.

Proposal

Encrypt values for fields declared type: "secret" at rest, transparently:

• On write, encrypt the value with a site-level key before storing.
• On read (getPluginSetting / getPluginSettings / the in-plugin ctx.kv/settings accessor), decrypt transparently so plugin code sees the plaintext, unchanged.
• Never return decrypted secrets to the admin client — keep the "write-only / masked" behavior in the settings API response (show "configured" state, not the value).

Open questions / things for maintainers to decide:

• Key source. A natural fit on Cloudflare is a dedicated env secret (e.g. EMDASH_SECRETS_KEY) used with WebCrypto AES-GCM; on Node, an env var likewise. Falling back to an existing site secret is possible but couples concerns.
• Migration. Existing plaintext secret values would need a one-time re-encrypt (lazy on next save, or a migration step). A stored marker (e.g. a version prefix on the ciphertext) lets read code tell encrypted from legacy plaintext.
• Scope. Could apply only to admin.settingsSchema secret fields, or more broadly to any KV key a plugin marks sensitive.

Alternatives considered

• Keep secrets in env/Worker secrets only. This is the current recommendation and stays the strongest option, but it removes admin-UI configurability and requires a redeploy to rotate — the exact friction the settings form is meant to remove.
• Per-plugin encryption in userland. A plugin could encrypt before calling the settings API, but every plugin would reinvent key management, and the auto-generated form couldn't be used. Centralizing in core is what makes the secret field type trustworthy.

Context

I hit this building a Better Auth plugin whose config (verification toggles, canonical URL, Google + auth secrets) I wanted fully manageable from the admin UI, mirroring how emdash-smtp exposes its provider settings. Everything works, but I've had to document a "secrets are stored plaintext; prefer keeping them as Worker secrets" caveat, and left the credential fields as env-fallback rather than truly admin-managed. Encrypting secret settings at rest would let plugins like this (and email-transport plugins) offer real credential management from the admin panel safely.

Happy to help with a PR if the maintainers are open to the direction.

Filed with AI assistance (Kiro / Claude Sonnet 4.5).

[marks-zyz]

Confirming this from the other side, with what the installed package says: you did not miss an encrypt/decrypt path, but the key for one already ships.

emdash@0.36.0, src/config/secrets.ts:

• EMDASH_ENCRYPTION_KEY is parsed and validated at runtime startup (validateEncryptionKeyAtStartup), and the CLI generates it (emdash secrets generate).
• The comment on that function says it plainly: the key "is currently inert (no consumers), and the follow-up PR that actually uses it will throw at point of use". resolveSecrets repeats it: "Future plugin-secret encryption code will read it via its own dedicated helper."

So a deployment that sets a malformed key gets an error in the startup logs today ("Plugin-secret encryption will fail once it ships"), which reads as if encryption were active. It is not.

On the read path, src/api/handlers/plugin-settings.ts confirms secret is a display concern: buildSettingsResponse returns secretsSet[key] = true/false instead of the value, and the stored string goes to the options table unchanged.

Two notes that may help scope this:

Prior art on the same trade-off. WordPress plugins in this exact category (email providers with AWS credentials) landed on "database by default, constants for real deployments": WP Offload SES recommends WPOSES_AWS_ACCESS_KEY_ID in wp-config.php "instead of storing your credentials in the database, for better security". Encryption at rest with a key that lives in the environment protects against a leaked dump, replica, or read-only SQLi — not against someone who already has the server. Worth saying out loud in the docs either way, because right now type: "secret" reads like a security guarantee.

A middle step that costs nothing. Until the encryption lands, a plugin can prefer an environment value over the panel value and tell the operator where the credential came from. We ship an SES transport that does this: the host env wins over the settings field, and the plugin's admin page prints the origin of every value plus a warning when a credential is coming from the database. It keeps the settings form useful for people without deploy access, without quietly turning it into the recommended path.

Happy to test a PR when the helper lands, on Cloudflare (D1 + Workers) with a real SES credential.