Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
10.1 KB
Raw Blame
//! Plaintext envelope codec for the Windows DPAPI backend; this module does not encrypt.
//! The caller must wipe encoded bytes on every path and validate the decoded ID against
//! the requested ID and hashed filename. Errors contain only fixed, non-sensitive text.

use super::{check_id, Secret, StoreError};
use sha2::{Digest, Sha256};

const MAGIC: &[u8; 8] = b"GDSEC\0\x01\0";
const HEADER_LEN: usize = MAGIC.len() + 12;
const NAME_DOMAIN: &[u8] = b"gentle-dot/windows-secret-filename/v1\0";

fn malformed() -> StoreError {
    StoreError::Failed("invalid Windows secret envelope".to_owned())
}

fn allocation_error() -> StoreError {
    StoreError::Failed("Windows secret buffer allocation failed".to_owned())
}

fn check_service(service: &str) -> Result<(), StoreError> {
    if service.is_empty() || service.contains('\0') {
        return Err(StoreError::Failed("invalid Windows secret service".to_owned()));
    }
    length(service.len())?;
    Ok(())
}

fn length(len: usize) -> Result<u32, StoreError> {
    u32::try_from(len).map_err(|_| malformed())
}

// DPAPI's input count is a DWORD. Include the entire envelope, not just the value.
fn envelope_len(service: usize, id: usize, value: usize) -> Result<usize, StoreError> {
    length(service)?;
    length(id)?;
    length(value)?;
    let total = HEADER_LEN.checked_add(service)
        .and_then(|n| n.checked_add(id))
        .and_then(|n| n.checked_add(value))
        .ok_or_else(malformed)?;
    length(total)?;
    Ok(total)
}

pub(super) fn filename(service: &str, id: &str) -> Result<String, StoreError> {
    check_id(id)?;
    check_service(service)?;
    let mut hash = Sha256::new();
    hash.update(NAME_DOMAIN);
    hash.update(length(service.len())?.to_le_bytes());
    hash.update(service.as_bytes());
    hash.update(length(id.len())?.to_le_bytes());
    hash.update(id.as_bytes());
    let digest = hash.finalize();
    let mut name = String::new();
    name.try_reserve_exact(68).map_err(|_| allocation_error())?;
    const HEX: &[u8; 16] = b"0123456789abcdef";
    for byte in digest {
        name.push(HEX[(byte >> 4) as usize] as char);
        name.push(HEX[(byte & 15) as usize] as char);
    }
    name.push_str(".bin");
    Ok(name)
}

pub(super) fn encode(service: &str, id: &str, value: &Secret) -> Result<Vec<u8>, StoreError> {
    check_id(id)?;
    check_service(service)?;
    let value = value.expose().as_bytes();
    let total = envelope_len(service.len(), id.len(), value.len())?;
    let lengths = [length(service.len())?, length(id.len())?, length(value.len())?];
    let mut bytes = Vec::new();
    bytes.try_reserve_exact(total).map_err(|_| allocation_error())?;
    bytes.extend_from_slice(MAGIC);
    for len in lengths {
        bytes.extend_from_slice(&len.to_le_bytes());
    }
    bytes.extend_from_slice(service.as_bytes());
    bytes.extend_from_slice(id.as_bytes());
    bytes.extend_from_slice(value);
    Ok(bytes)
}

fn take<'a>(bytes: &'a [u8], offset: &mut usize, len: usize) -> Result<&'a [u8], StoreError> {
    let end = offset.checked_add(len).ok_or_else(malformed)?;
    let part = bytes.get(*offset..end).ok_or_else(malformed)?;
    *offset = end;
    Ok(part)
}

fn read_length(bytes: &[u8], offset: &mut usize) -> Result<usize, StoreError> {
    let mut field = [0; 4];
    field.copy_from_slice(take(bytes, offset, 4)?);
    usize::try_from(u32::from_le_bytes(field)).map_err(|_| malformed())
}

pub(super) fn decode(service: &str, bytes: &[u8]) -> Result<(String, Secret), StoreError> {
    check_service(service)?;
    length(bytes.len())?;
    let mut offset = 0;
    if take(bytes, &mut offset, MAGIC.len())? != MAGIC {
        return Err(malformed());
    }
    let service_len = read_length(bytes, &mut offset)?;
    let id_len = read_length(bytes, &mut offset)?;
    let value_len = read_length(bytes, &mut offset)?;
    if envelope_len(service_len, id_len, value_len)? != bytes.len() {
        return Err(malformed());
    }
    let stored_service = std::str::from_utf8(take(bytes, &mut offset, service_len)?)
        .map_err(|_| malformed())?;
    check_service(stored_service)?;
    if stored_service != service {
        return Err(StoreError::Failed("Windows secret service mismatch".to_owned()));
    }
    let id = std::str::from_utf8(take(bytes, &mut offset, id_len)?)
        .map_err(|_| StoreError::InvalidId)?;
    check_id(id)?;
    let value = std::str::from_utf8(take(bytes, &mut offset, value_len)?)
        .map_err(|_| StoreError::NotText)?;
    if offset != bytes.len() {
        return Err(malformed());
    }
    // Validate the borrowed fields before allocating or copying any value bytes.
    let mut owned_id = String::new();
    owned_id.try_reserve_exact(id.len()).map_err(|_| allocation_error())?;
    owned_id.push_str(id);
    let mut owned_value = String::new();
    owned_value.try_reserve_exact(value.len()).map_err(|_| allocation_error())?;
    owned_value.push_str(value);
    Ok((owned_id, Secret::new(owned_value)))
}

#[cfg(test)]
mod tests {
    use super::*;

    const SERVICE: &str = "synthetic.codec.service";

    fn frame(service: &[u8], id: &[u8], value: &[u8]) -> Vec<u8> {
        let mut bytes = MAGIC.to_vec();
        for len in [service.len(), id.len(), value.len()] {
            bytes.extend_from_slice(&(len as u32).to_le_bytes());
        }
        bytes.extend_from_slice(service);
        bytes.extend_from_slice(id);
        bytes.extend_from_slice(value);
        bytes
    }

    #[test]
    fn roundtrip_unicode_empty_and_large_synthetic_values() {
        for value in [String::new(), "synthetic ✓ 🦀".to_owned(), "x".repeat(8192)] {
            let bytes = encode(SERVICE, "test/token", &Secret::new(value.clone())).unwrap();
            assert_eq!(bytes, frame(SERVICE.as_bytes(), b"test/token", value.as_bytes()));
            let (id, secret) = decode(SERVICE, &bytes).unwrap();
            assert_eq!(id, "test/token");
            assert_eq!(secret.expose(), value);
        }
        let id = "x".repeat(super::super::MAX_ID_LEN);
        let bytes = encode("synthetic.服务", &id, &Secret::new("synthetic")).unwrap();
        assert_eq!(decode("synthetic.服务", &bytes).unwrap().0, id);
    }

    #[test]
    fn rejects_missing_truncated_unknown_and_trailing_bytes() {
        let bytes = encode(SERVICE, "test/token", &Secret::new("synthetic")).unwrap();
        for end in 0..bytes.len() {
            assert!(decode(SERVICE, &bytes[..end]).is_err());
        }
        let mut unknown = bytes.clone();
        unknown[0] ^= 1;
        assert!(decode(SERVICE, &unknown).is_err());
        let mut trailing = bytes;
        trailing.push(0);
        assert!(decode(SERVICE, &trailing).is_err());
    }

    #[test]
    fn rejects_overflowing_lengths_without_large_allocations() {
        let mut bytes = frame(SERVICE.as_bytes(), b"id", b"value");
        for offset in [MAGIC.len(), MAGIC.len() + 4, MAGIC.len() + 8] {
            bytes[offset..offset + 4].copy_from_slice(&u32::MAX.to_le_bytes());
            assert!(decode(SERVICE, &bytes).is_err());
            bytes = frame(SERVICE.as_bytes(), b"id", b"value");
        }
        assert!(envelope_len(usize::MAX, 1, 1).is_err());
        assert!(envelope_len(u32::MAX as usize, 1, 1).is_err());
        assert!(envelope_len(1, 1, u32::MAX as usize).is_err());
        assert_eq!(envelope_len(1, 1, 8192).unwrap(), HEADER_LEN + 8194);
    }

    #[test]
    fn service_binding_and_value_text_are_checked() {
        let bytes = frame(SERVICE.as_bytes(), b"id", b"synthetic");
        assert!(decode("other.service", &bytes).is_err());
        assert_eq!(decode(SERVICE, &frame(SERVICE.as_bytes(), b"id", &[0xff])).unwrap_err(), StoreError::NotText);
        assert!(decode(SERVICE, &frame(&[0xff], b"id", b"synthetic")).is_err());
        for bad in ["", "service\0name"] {
            assert!(filename(bad, "id").is_err());
            assert!(encode(bad, "id", &Secret::new("synthetic")).is_err());
            assert!(decode(bad, &bytes).is_err());
            assert!(decode(SERVICE, &frame(bad.as_bytes(), b"id", b"synthetic")).is_err());
        }
    }

    #[test]
    fn filenames_are_opaque_lower_hex_and_case_distinct() {
        let name = filename(SERVICE, "test/token").unwrap();
        assert_eq!(name.len(), 68);
        assert!(name.ends_with(".bin"));
        assert!(name[..64].bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)));
        assert!(!name.contains("test/token"));
        assert_eq!(name, filename(SERVICE, "test/token").unwrap());
        assert_ne!(filename(SERVICE, "ID").unwrap().to_lowercase(), filename(SERVICE, "id").unwrap().to_lowercase());
        assert_ne!(filename("ab", "c").unwrap(), filename("a", "bc").unwrap());
        assert_ne!(filename("other.service", "id").unwrap(), filename(SERVICE, "id").unwrap());
    }

    #[test]
    fn rejects_invalid_ids_in_every_entry_point() {
        for id in ["", "with space", "\0", "ñ", &"x".repeat(super::super::MAX_ID_LEN + 1)] {
            assert_eq!(filename(SERVICE, id).unwrap_err(), StoreError::InvalidId);
            assert_eq!(encode(SERVICE, id, &Secret::new("synthetic")).unwrap_err(), StoreError::InvalidId);
            assert_eq!(decode(SERVICE, &frame(SERVICE.as_bytes(), id.as_bytes(), b"synthetic")).unwrap_err(), StoreError::InvalidId);
        }
        assert_eq!(decode(SERVICE, &frame(SERVICE.as_bytes(), &[0xff], b"synthetic")).unwrap_err(), StoreError::InvalidId);
    }

    #[test]
    fn errors_and_secret_debug_do_not_expose_payloads() {
        let marker = "synthetic-redaction-marker";
        let bytes = frame(marker.as_bytes(), b"id", marker.as_bytes());
        let errors = [
            decode(SERVICE, &bytes).unwrap_err(),
            decode(SERVICE, &frame(SERVICE.as_bytes(), marker.as_bytes(), &[0xff])).unwrap_err(),
            filename(SERVICE, "synthetic-redaction-marker invalid").unwrap_err(),
            encode("synthetic-redaction-marker\0", "id", &Secret::new(marker)).unwrap_err(),
        ];
        for error in errors {
            assert!(!format!("{error:?} {error}").contains(marker));
        }
        let (_, secret) = decode(SERVICE, &frame(SERVICE.as_bytes(), b"id", marker.as_bytes())).unwrap();
        assert!(!format!("{secret:?}").contains(marker));
    }
}