Skip to content

v0.49.0 — At-rest encryption + new widgets

Choose a tag to compare

View all tags
@dmellok dmellok released this 16 Jun 08:36
· 722 commits to main since this release
v0.49.0
0237157

Highlights

At-rest encryption for connector secrets. Manifest-declared secret: true settings (HA tokens, plugin API keys) are now AES-GCM-wrapped on disk and unwrapped transparently when the scheduler / push / fetch pipelines read them. The wire format enc:v1:<base64(nonce||ciphertext||tag)> carries a version tag so future algorithm upgrades are mechanical.

Two new widgets. Countdown, Date (N-days hero against a target date with a friendly meta line) and Year, Progress (year-in-weeks or life-in-weeks dot grid with a percentage hero). Both pure client-side, no network.

Key resolution

  • TESSERAE_SECRET_KEY env var (64 hex chars = 32 bytes) takes precedence. openssl rand -hex 32 is the easy way to mint one.
  • If unset, the box derives a stable key from the Flask session secret via HKDF-SHA256. The fallback works for the default self-host case; setting the env explicitly is recommended for real installs so rotating the session secret doesn't lock you out of your own connectors.

Upgrade notes

  • Upgrading 0.48.x → 0.49.0 needs no action. Existing plaintext secrets keep working (the unwrap path is a no-op for non-prefixed input) and migrate to ciphertext the next time you Save any setting under Plugins / Renderers / Devices.
  • Migrating to a new install works out of the box for the default setup. The built-in Backups and Migrate flows include settings.json, which carries the session secret the fallback key derives from. Same secret on both machines means the same decryption key.
  • If you set TESSERAE_SECRET_KEY, copy that env var to the new install before importing the data zip. The key lives in your environment, not in data/, so without it the new machine derives a different key and connector secrets won't decrypt.
  • Downgrading 0.49.0 → 0.48.x. Any secret re-saved on 0.49 is stored as enc:v1:<base64> on disk; an older Tesserae would read that literal string as your HA token and fail to authenticate. Restore settings.json from a pre-0.49 backup or re-save each affected secret in the older version.

Internals

  • New app.secret_box module (AES-GCM + HKDF via PyCA cryptography).
  • SettingsStore gains an optional secret_box= constructor arg and a set_secret_box() injector. Wrap-on-write / unwrap-on-read is transparent to consumers; get_section recursively unwraps any _secret-suffixed string at any depth so plugin server modules that read their own state directly (e.g. ha_core) keep seeing plaintext.
  • Wrong-key reads raise SecretBoxError (loud failure, not a silent empty token) so a misconfigured TESSERAE_SECRET_KEY surfaces immediately instead of as a 401 from HA.
  • Added cryptography>=42,<46 as a runtime dependency. Rust-backed primitives, manylinux wheel available so the Docker base image stays slim.
  • 968 tests passing, ruff + mypy strict clean.

Zero plugin-code changes needed

The encryption layer sits under the existing secret-handling APIs (get_for_runtime, update_for_namespace, get_section). Every existing widget keeps reading its settings the same way and gets plaintext back. No migration script, no breakage.

Assets 2
Loading