feat(secrets): add qbz-secrets crate for device-bound secret wrapping

Foundation for the offline-cache hardening story. The offline cache
needs to persist per-track AES content keys to disk, but storing them
plaintext would make copying the SQLite DB enough to decrypt the
cached audio on another machine.

qbz-secrets provides a uniform wrap/unwrap API backed by:

1. **OS keyring** (preferred): libsecret/gnome-keyring on Linux,
   Keychain on macOS, DPAPI on Windows. A 256-bit master AES key
   lives inside the OS secure store; all wraps go through it. This
   is the gold-standard device binding used by commercial music
   apps (Spotify, Apple Music, Tidal) for the same class of data.

2. **HKDF fallback**: when the OS keyring is not reachable (headless
   setups — Raspberry Pi, Docker, the future qbzd daemon on a
   server), the master key is derived on demand via HKDF-SHA256
   over service_name + machine_id + a persistent per-install UUID.
   Weaker than keyring (reversible by anyone with filesystem access
   to both sources) but still device-bound against cross-machine
   copy attacks, and lets daemon/headless variants work at all.

Every wrap uses AES-256-GCM with a fresh random 12-byte nonce. The
on-disk envelope carries a version byte + backend marker + nonce +
ciphertext+tag, so (a) we detect tampering via GCM, (b) we refuse to
silently unwrap a blob produced by a backend we can't reach, and (c)
we have a forward-compat path for future key rotation.

4 unit tests cover: small-secret round-trip, 16-byte content-key
round-trip (the exact CMAF use case), GCM tamper detection, and
nonce-randomness (two wraps of the same input differ).

This crate intentionally has zero QBZ dependencies — it's a generic
primitive. Next commits wire it into the offline cache schema + the
DB migration.

cc
This commit is contained in:
vicrodh committed 2026-04-17 00:53:01 -06:00
1 parent 391e797c9a
commit 1743c9e5ec
9 files changed
+729

No files matched your search

+38
View File
@@ -0,0 +1,38 @@
[package]
name = "qbz-secrets"
version.workspace = true
edition.workspace = true
license.workspace = true
description = "Device-bound secret wrapping for QBZ (offline cache keys, tokens)"
[dependencies]
# AES-256-GCM for the at-rest wrap/unwrap
aes-gcm = "0.10"
# KDF for the fallback path when OS keyring isn't available
hkdf = "0.12"
sha2 = "0.10"
# RNG for nonces + install UUID generation
rand = "0.9"
# OS keyring backends: libsecret/secret-service (Linux), Keychain (macOS),
# DPAPI (Windows). Default features on v3 already pick the right backend
# per platform; if it fails at runtime we fall through to the KDF path.
keyring = "3"
# UUID for the persistent install identifier (salt component for fallback)
uuid = { version = "1", features = ["v4", "serde"] }
# Serde for the on-disk wrapper blob envelope
serde = { workspace = true }
# Base64 for keyring-roundtripped master key (secret-service expects a UTF-8 string)
base64 = { workspace = true }
# Errors
thiserror = { workspace = true }
log = { workspace = true }
[dev-dependencies]
tempfile = "3"