bookclerk_library::secrets
Encrypted secrets store — DB-backed credential storage.
Secrets are kept in the encrypted_secrets table (M10 migration). Each row
stores opaque ciphertext with column-level metadata describing which KDF
and cipher were used, so every secret carries its own self-contained
decryption recipe.
- New writes:
sealed-v1— XChaCha20-Poly1305 with the process DEK (frommaster.key). No per-row Argon2. No plaintext writes ever. - Legacy reads:
json-encrypted(Argon2id + BOOKCLERK_AUTH_PASSWORD) still decrypted.json(plaintext) is migrated on read if master key is available, otherwise rejected.
unseal_secret keeps a process-wide plaintext cache (identity +
ciphertext fingerprint). Content-source plugins should just call
load/unseal normally — repeated acquire/scan loads stay cheap without
per-plugin caches. Upsert/delete invalidate the matching entries.
BOOKCLERK_AUTH_PASSWORD, BOOKCLERK_DATABASE_POSTGRES_URL, and
BOOKCLERK_D1_API_TOKEN / CLOUDFLARE_API_TOKEN are env-only bootstrap
credentials. They are needed to open the DB or bootstrap the master key and
cannot be stored here. config.toml also stays on disk.
BOOKCLERK_OPERATOR_TOKEN is an optional env override for the durable
operator token row (kind = operator_token); see crate::operator_token.
| Item | Kind | Summary |
|---|---|---|
EncryptedSecretRecord |
struct | A row from the encrypted_secrets table. |
EncryptedBlob |
struct | Raw output from encrypt_secret (legacy Argon2id path). |
SecretStore |
struct | Thin wrapper around a DatabaseConnection for encrypted_secrets CRUD. |
clear_unseal_cache |
function | Drop every cached plaintext unseal. |
encrypt_secret |
function | Encrypt plaintext with Argon2id key derivation + XChaCha20-Poly1305 (legacy). |
decrypt_secret |
function | Decrypt ciphertext using Argon2id + XChaCha20-Poly1305 (legacy json-encrypted). |
build_sealed_record |
function | Build a EncryptedSecretRecord skeleton sealed with the process DEK. |
unseal_secret |
function | Unseal a sealed-v1 record using the process DEK. |
bytes_to_b64_string |
function | Seal arbitrary bytes as base64 string — used by D1 transport layer. |
b64_string_to_bytes |
function | Decode a b64:-prefixed string to bytes. Returns None if not prefixed. |
upsert_secret |
function | Insert or replace a secret in the DB using a single ON CONFLICT statement. |
upsert_secret_on |
function | Insert or replace a secret using an open connection or transaction. |
get_secret |
function | Fetch a single secret by its composite key. Returns None if not found. |
list_secrets |
function | List all secrets of a given kind. |
delete_secrets_for_account |
function | Delete integration-account secrets for account_id under provider (the owning plugin key). |
delete_secret |
function | Delete a secret by its composite key. No-op if it does not exist. |
delete_secret_on |
function | Delete a secret by composite key on an open connection or transaction. |
FORMAT_SEALED_V1 |
constant | Format tag for new writes: DEK-sealed XChaCha20-Poly1305 (no per-row Argon2). |
KDF_M_COST |
constant | Argon2id memory cost in KiB (64 MiB — OWASP minimum). Legacy only. |
KDF_T_COST |
constant | Argon2id time cost (iterations). Legacy only. |
KDF_P_COST |
constant | Argon2id parallelism factor. Legacy only. |
KDF_ALGORITHM |
constant | KDF algorithm identifier. Legacy only. |
CIPHER_ALGORITHM |
constant | Cipher algorithm identifier stored alongside ciphertext rows. |
pub struct EncryptedSecretRecord {
pub id: Option<i64>,
pub kind: String,
pub provider: Option<String>,
pub account_type: String,
pub account_id: Option<String>,
pub name: String,
pub format: String,
pub ciphertext: Vec<u8>,
pub kdf_algorithm: Option<String>,
pub kdf_salt: Option<Vec<u8>>,
pub kdf_m_cost: Option<u32>,
pub kdf_t_cost: Option<u32>,
pub kdf_p_cost: Option<u32>,
pub cipher_algorithm: Option<String>,
pub cipher_nonce: Option<Vec<u8>>,
pub created_at: String,
pub updated_at: String,
}
A row from the encrypted_secrets table.
Fields
id: Surrogate primary key assigned by the database.kind: Secret kind discriminator (source_auth,s3, …).provider: Source / service name ("audible","libro","s3", …) orNone.account_type: Ownership namespace — seesecret_account_typeconstants.account_id: Per-provider account identifier (file stem, email, …) orNone.name: Human-readable label / file-stem equivalent (e.g."alice.audible").format: Payload format:"sealed-v1"— XChaCha20-Poly1305 with process DEK (no per-row Argon2)"audible-rs-auth"— sealed-v1 wrapping a plain audible-rs envelope"json-encrypted"— legacy: JSON encrypted with Argon2id + XChaCha20-Poly1305
ciphertext: Encrypted payload bytes for this secret.kdf_algorithm: KDF algorithm id for legacy rows (for exampleargon2id).kdf_salt: Random salt for legacy Argon2 key derivation.kdf_m_cost: Argon2 memory cost in KiB for legacy rows.kdf_t_cost: Argon2 time cost (iterations) for legacy rows.kdf_p_cost: Argon2 parallel lane count stored for legacyjson-encryptedrows.cipher_algorithm: Cipher algorithm identifier (e.g."xchacha20poly1305") orNone.cipher_nonce: AEAD nonce bytes used withciphertext.created_at: RFC 3339 timestamp when the row was inserted.updated_at: RFC 3339 timestamp when the row was last modified.
Implements: Clone, Debug, Deserialize<'de>, Serialize
pub struct EncryptedBlob {
pub kdf_salt: Vec<u8>,
pub cipher_nonce: Vec<u8>,
pub ciphertext: Vec<u8>,
}
Raw output from encrypt_secret (legacy Argon2id path).
Fields
kdf_salt: Random salt for legacy Argon2 key derivation.cipher_nonce: AEAD nonce bytes used withciphertext.ciphertext: Encrypted payload bytes for this secret.
pub struct SecretStore<'a> {
/* private fields */
}
Thin wrapper around a DatabaseConnection for encrypted_secrets CRUD.
Construct with SecretStore::new or call the standalone async fn
helpers directly. All methods are async.
pub fn new(db: &'a DatabaseConnection) -> Self
Constructs a store handle over an existing database connection.
db- SeaORM connection owned by the caller for the lifetime of this handle.
A SecretStore that delegates to the standalone CRUD helpers.
pub async fn upsert(&self, record: &EncryptedSecretRecord) -> Result<()>
Inserts or replaces a sealed secret row.
record- Fully populated sealed secret identity and ciphertext.
Returns LibraryError when the database write fails.
pub async fn get(
&self,
kind: &str,
provider: Option<&str>,
account_type: &str,
account_id: Option<&str>,
name: &str,
) -> Result<Option<EncryptedSecretRecord>>
Loads one sealed secret by identity columns, if present.
kind- Secret kind (source_auth,s3, …).provider- Optional provider / plugin id filter.account_type-integrationoroperator.account_id- Optional account id filter.name- Logical secret name within that identity.
Ok(Some(record)) when found, Ok(None) otherwise.
Returns LibraryError when the database read fails.
pub async fn list(&self, kind: &str) -> Result<Vec<EncryptedSecretRecord>>
Lists sealed secrets with the given kind.
kind- Secret kind to filter on.
All matching sealed rows (ciphertext included).
Returns LibraryError when the database read fails.
pub async fn delete(
&self,
kind: &str,
provider: Option<&str>,
account_type: &str,
account_id: Option<&str>,
name: &str,
) -> Result<()>
Deletes one sealed secret by identity columns.
kind- Secret kind (source_auth,s3, …).provider- Optional provider / plugin id filter.account_type-integrationoroperator.account_id- Optional account id filter.name- Logical secret name within that identity.
Returns LibraryError when the database delete fails.
pub fn clear_unseal_cache()
Drop every cached plaintext unseal.
Call when the process DEK identity changes. Password wrap of the same DEK
(BCK1 → BCK2) does not require this — ciphertext and plaintext stay valid.
pub fn encrypt_secret(plaintext: &[u8], password: &str) -> Result<EncryptedBlob>
Encrypt plaintext with Argon2id key derivation + XChaCha20-Poly1305 (legacy).
Use build_sealed_record for new writes. This function is retained for
legacy test compat and the json-encrypted migration path.
Returns an error when the operation fails.
pub fn decrypt_secret(
ciphertext: &[u8],
password: &str,
kdf_salt: &[u8],
cipher_nonce: &[u8],
) -> Result<Vec<u8>>
Decrypt ciphertext using Argon2id + XChaCha20-Poly1305 (legacy json-encrypted).
Use unseal_secret for new reads. This function handles legacy DB rows.
Returns an error when the operation fails.
pub fn build_sealed_record(
plaintext: &[u8],
kind: &str,
provider: &str,
account_type: &str,
account_id: &str,
name: &str,
) -> Result<EncryptedSecretRecord>
Build a EncryptedSecretRecord skeleton sealed with the process DEK.
Callers must fill in kind, provider, account_type, account_id,
name, and timestamps before upserting.
Returns an error when the operation fails.
pub fn unseal_secret(record: &EncryptedSecretRecord) -> Result<Vec<u8>>
Unseal a sealed-v1 record using the process DEK.
Also handles legacy json-encrypted (using BOOKCLERK_AUTH_PASSWORD) and
rejects json plaintext.
Successful unseals are cached process-wide (keyed by secret identity + ciphertext fingerprint) so repeated loads during acquire/scan do not re-decrypt. Callers — including content-source plugins — need not cache.
Returns an error when the operation fails.
pub fn bytes_to_b64_string(bytes: &[u8]) -> String
Seal arbitrary bytes as base64 string — used by D1 transport layer.
pub fn b64_string_to_bytes(s: &str) -> Option<Vec<u8>>
Decode a b64:-prefixed string to bytes. Returns None if not prefixed.
pub async fn upsert_secret(
db: &DatabaseConnection,
record: &EncryptedSecretRecord,
) -> Result<()>
Insert or replace a secret in the DB using a single ON CONFLICT statement.
provider and account_id should always be Some for new writes.
Returns an error when the operation fails.
pub async fn upsert_secret_on<C: ConnectionTrait>(
db: &C,
record: &EncryptedSecretRecord,
) -> Result<()>
Insert or replace a secret using an open connection or transaction.
Returns an error when the operation fails.
pub async fn get_secret(
db: &DatabaseConnection,
kind: &str,
provider: Option<&str>,
account_type: &str,
account_id: Option<&str>,
name: &str,
) -> Result<Option<EncryptedSecretRecord>>
Fetch a single secret by its composite key. Returns None if not found.
Returns an error when the operation fails.
pub async fn list_secrets(
db: &DatabaseConnection,
kind: &str,
) -> Result<Vec<EncryptedSecretRecord>>
List all secrets of a given kind.
Returns an error when the operation fails.
pub async fn delete_secrets_for_account(
db: &DatabaseConnection,
provider: &str,
account_id: &str,
) -> Result<()>
Delete integration-account secrets for account_id under provider
(the owning plugin key).
Operator-typed secrets (e.g. S3 destination credentials) are never
matched — they have account_type = "operator" and survive account
revocation.
Returns an error when the operation fails.
pub async fn delete_secret(
db: &DatabaseConnection,
kind: &str,
provider: Option<&str>,
account_type: &str,
account_id: Option<&str>,
name: &str,
) -> Result<()>
Delete a secret by its composite key. No-op if it does not exist.
Returns an error when the operation fails.
pub async fn delete_secret_on<C: ConnectionTrait>(
db: &C,
kind: &str,
provider: Option<&str>,
account_type: &str,
account_id: Option<&str>,
name: &str,
) -> Result<()>
Delete a secret by composite key on an open connection or transaction.
Returns an error when the operation fails.
pub const FORMAT_SEALED_V1: &str = "sealed-v1";
Format tag for new writes: DEK-sealed XChaCha20-Poly1305 (no per-row Argon2).
pub const KDF_M_COST: u32 = 65_536;
Argon2id memory cost in KiB (64 MiB — OWASP minimum). Legacy only.
pub const KDF_T_COST: u32 = 3;
Argon2id time cost (iterations). Legacy only.
pub const KDF_P_COST: u32 = 1;
Argon2id parallelism factor. Legacy only.
pub const KDF_ALGORITHM: &str = "argon2id";
KDF algorithm identifier. Legacy only.
pub const CIPHER_ALGORITHM: &str = "xchacha20poly1305";
Cipher algorithm identifier stored alongside ciphertext rows.
Generated from crates/bookclerk-library at main · View as Markdown