rullst-orm 13.0.0-alpha.2

use aes_gcm::{
    Aes256Gcm,
    aead::{Aead, Generate, KeyInit, Nonce, Payload},
};
use base64::{
    Engine as _,
    engine::general_purpose::{STANDARD, URL_SAFE_NO_PAD},
};

const ENVELOPE_PREFIX: &str = "RULLST";
const ENVELOPE_VERSION: &str = "v2";
const DEFAULT_KEY_ID: &str = "default";
const KEY_LENGTH: usize = 32;
const NONCE_LENGTH: usize = 12;
const TAG_LENGTH: usize = 16;
const MAX_KEY_ID_LENGTH: usize = 128;
const AAD_DOMAIN: &[u8] = b"rullst-orm:field-encryption:aes-256-gcm";
const KEY_ENV: &str = "RULLST_ENCRYPTION_KEY";
const KEY_ID_ENV: &str = "RULLST_ENCRYPTION_KEY_ID";
const KEYRING_ENV: &str = "RULLST_ENCRYPTION_KEYRING";

mod secret_serde;
#[doc(hidden)]
pub use secret_serde::with_redacted_secrets;
pub use secret_serde::{deserialize_optional_plaintext_secret, deserialize_plaintext_secret};
mod settings;
mod sqlx_codec;

/// A decrypted secret whose `Debug` output and serde form never contain the
/// plaintext.
///
/// SQLx encoding/decoding encrypts and decrypts the column value. `Serialize`
/// emits an authenticated `RULLST:v2` envelope under the configured
/// `RULLST_ENCRYPTION_KEY` (and fails without one); `Deserialize` decrypts such
/// an envelope and still accepts any other string as plaintext input.
/// Because the envelope binds no model, field or owner, `Deserialize` is for
/// trusted stores only: deserialize client input with
/// [`deserialize_plaintext_secret`] or [`deserialize_optional_plaintext_secret`].
/// Generated ORM audit, event and search projections serialize it as `"***"`.
/// Use [`SecretString::reveal_audited`] for deliberate exposure.
#[derive(Clone, PartialEq, Eq)]
pub struct SecretString(String);

impl SecretString {
    pub fn new(val: impl Into<String>) -> Self {
        SecretString(val.into())
    }

    /// Reveals the real value only when explicitly requested.
    /// In a real implementation, this might take an `AuditLogToken` to log the access.
    pub fn reveal_audited(&self) -> &str {
        &self.0
    }
}

// In standard debug, it should never leak.
impl std::fmt::Debug for SecretString {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("[ENCRYPTED_SECRET]")
    }
}

/// Compliance metadata generated by `#[derive(PersonalData)]`.
pub struct PrivacyReport {
    /// The model's table: `#[orm(table = "...")]`, else the ORM's `<struct>s`
    /// default.
    pub table_name: String,
    /// Whether any persisted field is encrypted at rest.
    pub has_encrypted_data: bool,
    /// Persisted `#[orm(encrypted)]` and `SecretString` fields. A `#[privacy]`
    /// tag only redacts `Debug`; see [`ComplianceModel::personal_fields`].
    pub encrypted_fields: Vec<&'static str>,
}

pub trait ComplianceModel {
    fn compliance_schema() -> PrivacyReport;

    /// The fields the application declared as personal data with
    /// `#[privacy]` on `#[derive(PersonalData)]`; empty by default.
    /// Added in v13.
    fn personal_fields() -> Vec<&'static str> {
        Vec::new()
    }
}

/// Strongly-typed error domain for Rullst ORM privacy and column encryption.
#[derive(Debug, thiserror::Error, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum PrivacyError {
    /// The encryption key is missing or not exactly 32 bytes long.
    #[error("RULLST_ENCRYPTION_KEY must be exactly 32 bytes long")]
    InvalidKeyLength,

    /// A prefixed base64 or hexadecimal key could not be decoded.
    #[error("RULLST_ENCRYPTION_KEY has invalid {0} encoding")]
    InvalidKeyEncoding(&'static str),

    /// A key identifier was empty, too long, or contained an envelope delimiter.
    #[error("Invalid field-encryption key identifier")]
    InvalidKeyId,

    /// A versioned encrypted value did not contain the required fields.
    #[error("Invalid field-encryption envelope")]
    InvalidEnvelope,

    /// The encrypted value belongs to an unknown future format.
    #[error("Unsupported field-encryption envelope version: {0}")]
    UnsupportedEnvelopeVersion(String),

    /// The configured keyring does not contain the key selected by the envelope.
    #[error("Field-encryption key `{0}` was not found in the configured keyring")]
    KeyNotFound(String),

    /// The operating system could not provide a cryptographically secure nonce.
    #[error("Operating-system randomness is unavailable")]
    RandomnessUnavailable,

    /// AES-GCM encryption failed.
    #[error("Encryption failed: {0}")]
    EncryptionFailed(String),

    /// AES-GCM decryption failed.
    #[error("Decryption failed: {0}")]
    DecryptionFailed(String),

    /// The payload is shorter than the 12-byte nonce requirement.
    #[error("Invalid encrypted payload (too short)")]
    PayloadTooShort,

    /// Base64 decoding failed.
    #[error("Base64 decode error: {0}")]
    Base64Error(String),

    /// Decrypted payload is not valid UTF-8.
    #[error("UTF-8 decoding error: {0}")]
    Utf8Error(String),

    /// Missing environment variable key.
    #[error("Environment variable error: {0}")]
    EnvError(String),
}

fn validate_key(key: &[u8]) -> Result<(), PrivacyError> {
    if key.len() == KEY_LENGTH {
        Ok(())
    } else {
        Err(PrivacyError::InvalidKeyLength)
    }
}

fn validate_key_id(key_id: &str) -> Result<(), PrivacyError> {
    if key_id.is_empty()
        || key_id.len() > MAX_KEY_ID_LENGTH
        || !key_id
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
    {
        Err(PrivacyError::InvalidKeyId)
    } else {
        Ok(())
    }
}

fn authenticated_data(key_id: &str, context: &[u8]) -> Vec<u8> {
    let mut aad = Vec::with_capacity(AAD_DOMAIN.len() + key_id.len() + context.len() + 4);
    aad.extend_from_slice(AAD_DOMAIN);
    aad.push(0);
    aad.extend_from_slice(ENVELOPE_VERSION.as_bytes());
    aad.push(0);
    aad.extend_from_slice(key_id.as_bytes());
    aad.push(0);
    aad.extend_from_slice(context);
    aad
}

fn model_context(table: &str, column: &str) -> Vec<u8> {
    let mut context = Vec::with_capacity(table.len() + column.len() + 1);
    context.extend_from_slice(table.as_bytes());
    context.push(0);
    context.extend_from_slice(column.as_bytes());
    context
}

fn encrypt_with_context(
    plaintext: &str,
    key: &[u8],
    key_id: &str,
    context: &[u8],
) -> Result<String, PrivacyError> {
    validate_key(key)?;
    validate_key_id(key_id)?;
    let cipher = Aes256Gcm::new_from_slice(key)
        .map_err(|error| PrivacyError::EncryptionFailed(error.to_string()))?;
    let nonce =
        Nonce::<Aes256Gcm>::try_generate().map_err(|_| PrivacyError::RandomnessUnavailable)?;
    let aad = authenticated_data(key_id, context);
    let ciphertext = cipher
        .encrypt(
            &nonce,
            Payload {
                msg: plaintext.as_bytes(),
                aad: &aad,
            },
        )
        .map_err(|error| PrivacyError::EncryptionFailed(error.to_string()))?;

    Ok(format!(
        "{ENVELOPE_PREFIX}:{ENVELOPE_VERSION}:{key_id}:{}:{}",
        URL_SAFE_NO_PAD.encode(nonce),
        URL_SAFE_NO_PAD.encode(ciphertext)
    ))
}

struct ParsedEnvelope<'a> {
    key_id: &'a str,
    nonce: Vec<u8>,
    ciphertext: Vec<u8>,
}

fn parse_envelope(encrypted: &str) -> Result<ParsedEnvelope<'_>, PrivacyError> {
    let mut fields = encrypted.split(':');
    if fields.next() != Some(ENVELOPE_PREFIX) {
        return Err(PrivacyError::InvalidEnvelope);
    }
    let version = fields.next().ok_or(PrivacyError::InvalidEnvelope)?;
    if version != ENVELOPE_VERSION {
        return Err(PrivacyError::UnsupportedEnvelopeVersion(
            version.to_string(),
        ));
    }
    let key_id = fields.next().ok_or(PrivacyError::InvalidEnvelope)?;
    validate_key_id(key_id)?;
    let encoded_nonce = fields.next().ok_or(PrivacyError::InvalidEnvelope)?;
    let encoded_ciphertext = fields.next().ok_or(PrivacyError::InvalidEnvelope)?;
    if fields.next().is_some() {
        return Err(PrivacyError::InvalidEnvelope);
    }

    let nonce = URL_SAFE_NO_PAD
        .decode(encoded_nonce)
        .map_err(|error| PrivacyError::Base64Error(error.to_string()))?;
    if nonce.len() != NONCE_LENGTH {
        return Err(PrivacyError::PayloadTooShort);
    }
    let ciphertext = URL_SAFE_NO_PAD
        .decode(encoded_ciphertext)
        .map_err(|error| PrivacyError::Base64Error(error.to_string()))?;
    if ciphertext.len() < TAG_LENGTH {
        return Err(PrivacyError::PayloadTooShort);
    }

    Ok(ParsedEnvelope {
        key_id,
        nonce,
        ciphertext,
    })
}

fn decrypt_envelope(
    envelope: &ParsedEnvelope<'_>,
    key: &[u8],
    context: &[u8],
) -> Result<String, PrivacyError> {
    validate_key(key)?;
    let cipher = Aes256Gcm::new_from_slice(key)
        .map_err(|error| PrivacyError::DecryptionFailed(error.to_string()))?;
    let nonce = Nonce::<Aes256Gcm>::try_from(envelope.nonce.as_slice())
        .map_err(|error| PrivacyError::DecryptionFailed(error.to_string()))?;
    let aad = authenticated_data(envelope.key_id, context);
    let plaintext = cipher
        .decrypt(
            &nonce,
            Payload {
                msg: &envelope.ciphertext,
                aad: &aad,
            },
        )
        .map_err(|error| PrivacyError::DecryptionFailed(error.to_string()))?;
    String::from_utf8(plaintext).map_err(|error| PrivacyError::Utf8Error(error.to_string()))
}

fn current_key_id() -> Result<String, PrivacyError> {
    match settings::setting(KEY_ID_ENV)? {
        Some(key_id) => {
            validate_key_id(&key_id)?;
            Ok(key_id)
        }
        None => Ok(DEFAULT_KEY_ID.to_string()),
    }
}

fn decode_configured_key(value: &str) -> Result<Vec<u8>, PrivacyError> {
    let key = if let Some(encoded) = value.strip_prefix("base64:") {
        STANDARD
            .decode(encoded)
            .map_err(|_| PrivacyError::InvalidKeyEncoding("base64"))?
    } else if let Some(encoded) = value.strip_prefix("hex:") {
        let (pairs, remainder) = encoded.as_bytes().as_chunks::<2>();
        if !remainder.is_empty() {
            return Err(PrivacyError::InvalidKeyEncoding("hex"));
        }
        pairs
            .iter()
            .map(|pair| {
                let pair = std::str::from_utf8(pair)
                    .map_err(|_| PrivacyError::InvalidKeyEncoding("hex"))?;
                u8::from_str_radix(pair, 16).map_err(|_| PrivacyError::InvalidKeyEncoding("hex"))
            })
            .collect::<Result<Vec<_>, _>>()?
    } else {
        value.as_bytes().to_vec()
    };
    validate_key(&key)?;
    Ok(key)
}

fn current_key() -> Result<Vec<u8>, PrivacyError> {
    decode_configured_key(&settings::required_setting(KEY_ENV)?)
}

fn parse_keyring(
    keyring: &str,
) -> Result<serde_json::Map<String, serde_json::Value>, PrivacyError> {
    serde_json::from_str(keyring).map_err(|error| {
        PrivacyError::EnvError(format!(
            "{KEYRING_ENV} must be a JSON object of key IDs to 32-byte keys: {error}"
        ))
    })
}

fn configured_key(key_id: &str) -> Result<Vec<u8>, PrivacyError> {
    if current_key_id()? == key_id {
        return current_key();
    }

    let values = parse_keyring(&settings::required_setting(KEYRING_ENV)?)?;
    let key = values
        .get(key_id)
        .and_then(serde_json::Value::as_str)
        .ok_or_else(|| PrivacyError::KeyNotFound(key_id.to_string()))?
        .to_string();
    decode_configured_key(&key)
}

/// Decrypts a pre-v12 value, which names no key: the current key first, then
/// the `RULLST_ENCRYPTION_KEYRING` keys (`default`, the implicit ID of those
/// values, before the others), so legacy rows stay readable after rotation.
/// AES-GCM authentication rejects every key but the one that wrote the value.
fn decrypt_legacy_configured(encrypted: &str) -> Result<String, PrivacyError> {
    let rejected = match decrypt_legacy_aes_gcm(encrypted, &current_key()?) {
        Err(error @ PrivacyError::DecryptionFailed(_)) => error,
        other => return other,
    };
    let Some(keyring) = settings::setting(KEYRING_ENV)? else {
        return Err(rejected);
    };
    let values = parse_keyring(&keyring)?;
    let candidates = values.get(DEFAULT_KEY_ID).into_iter().chain(
        values
            .iter()
            .filter(|(key_id, _)| key_id.as_str() != DEFAULT_KEY_ID)
            .map(|(_, key)| key),
    );
    for candidate in candidates {
        let key = candidate.as_str().ok_or_else(|| {
            PrivacyError::EnvError(format!("{KEYRING_ENV} values must be key strings"))
        })?;
        match decrypt_legacy_aes_gcm(encrypted, &decode_configured_key(key)?) {
            Err(PrivacyError::DecryptionFailed(_)) => continue,
            other => return other,
        }
    }
    Err(rejected)
}

/// Encrypts an ORM model field using the configured current key and an
/// authenticated table/column context.
///
/// `RULLST_ENCRYPTION_KEY`, `RULLST_ENCRYPTION_KEY_ID` and
/// `RULLST_ENCRYPTION_KEYRING` are each read from the process environment,
/// then from `./.env` (never loaded into the process environment).
pub fn encrypt_model_field(
    plaintext: &str,
    table: &str,
    column: &str,
) -> Result<String, PrivacyError> {
    let key_id = current_key_id()?;
    let key = current_key()?;
    encrypt_with_context(plaintext, &key, &key_id, &model_context(table, column))
}

/// Decrypts an ORM model field and selects its key from the configured current
/// key or `RULLST_ENCRYPTION_KEYRING` JSON object.
pub fn decrypt_model_field(
    encrypted: &str,
    table: &str,
    column: &str,
) -> Result<String, PrivacyError> {
    let envelope = parse_envelope(encrypted)?;
    let key = configured_key(envelope.key_id)?;
    decrypt_envelope(&envelope, &key, &model_context(table, column))
}

pub fn encrypt_aes_gcm(plaintext: &str, key: &str) -> Result<String, PrivacyError> {
    encrypt_with_context(plaintext, key.as_bytes(), DEFAULT_KEY_ID, b"")
}

pub fn decrypt_aes_gcm(encrypted: &str, key: &str) -> Result<String, PrivacyError> {
    let key_bytes = key.as_bytes();
    validate_key(key_bytes)?;
    if encrypted.starts_with(&format!("{ENVELOPE_PREFIX}:")) {
        let envelope = parse_envelope(encrypted)?;
        return decrypt_envelope(&envelope, key_bytes, b"");
    }

    decrypt_legacy_aes_gcm(encrypted, key_bytes)
}

fn decrypt_legacy_aes_gcm(encrypted: &str, key: &[u8]) -> Result<String, PrivacyError> {
    // v12 reads the pre-v12 nonce+ciphertext base64 representation so existing
    // `SecretString` rows can be loaded and rewritten into the versioned format.
    let payload = STANDARD
        .decode(encrypted)
        .map_err(|error| PrivacyError::Base64Error(error.to_string()))?;
    if payload.len() < NONCE_LENGTH + TAG_LENGTH {
        return Err(PrivacyError::PayloadTooShort);
    }

    let cipher = Aes256Gcm::new_from_slice(key)
        .map_err(|error| PrivacyError::DecryptionFailed(error.to_string()))?;
    let nonce = Nonce::<Aes256Gcm>::try_from(&payload[..NONCE_LENGTH])
        .map_err(|error| PrivacyError::DecryptionFailed(error.to_string()))?;
    let ciphertext = &payload[NONCE_LENGTH..];

    let plaintext = cipher
        .decrypt(&nonce, ciphertext)
        .map_err(|error| PrivacyError::DecryptionFailed(error.to_string()))?;

    String::from_utf8(plaintext).map_err(|error| PrivacyError::Utf8Error(error.to_string()))
}

fn encrypt_configured_secret(plaintext: &str) -> Result<String, PrivacyError> {
    let key_id = current_key_id()?;
    let key = current_key()?;
    encrypt_with_context(plaintext, &key, &key_id, b"")
}

fn decrypt_configured_secret(encrypted: &str) -> Result<String, PrivacyError> {
    if encrypted.starts_with(&format!("{ENVELOPE_PREFIX}:")) {
        let envelope = parse_envelope(encrypted)?;
        let key = configured_key(envelope.key_id)?;
        decrypt_envelope(&envelope, &key, b"")
    } else {
        decrypt_legacy_configured(encrypted)
    }
}

#[cfg(test)]
mod tests;