Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add email parsing logic from single source (#2159)

Leendert de Borstac28ad0d25ee
diff --git a/apps/browser-extension/src/utils/EncryptionUtility.ts b/apps/browser-extension/src/utils/EncryptionUtility.ts
index 70efe6155..1bb69d64b 100644
--- a/apps/browser-extension/src/utils/EncryptionUtility.ts
+++ b/apps/browser-extension/src/utils/EncryptionUtility.ts
@@ -5,6 +5,24 @@ import argon2 from 'argon2-browser/dist/argon2-bundled.min.js';
import { devWarn } from '@/utils/devLogger/DevLogger';
import type { EncryptionKey } from '@/utils/dist/core/models/vault';
import type { Email, EmailKeyWrap, MailboxEmail } from '@/utils/dist/core/models/webapi';
+import { parseEmailSource, type ParsedEmailAttachment } from '@/utils/RustCore';
+
+/**
+ * A decrypted email. Its metadata (subject, sender) is decrypted from the individually encrypted fields, while
+ * the bodies and attachments are derived from the raw RFC 822 source.
+ */
+export type DecryptedEmail = {
+ /** The email with its metadata fields decrypted. */
+ email: Email;
+ /** The html body parsed out of the source, null when the message has no html part. */
+ htmlBody: string | null;
+ /** The plain text body parsed out of the source, null when the message has no text part. */
+ textBody: string | null;
+ /** The attachments contained in the source, in the index order `extractEmailAttachment` expects. */
+ attachments: ParsedEmailAttachment[];
+ /** The decrypted source bytes. */
+ sourceBytes: Uint8Array | null;
+};
/**
* Utility class for encryption operations including:
@@ -375,44 +393,50 @@ export class EncryptionUtility {
throw new Error('Encryption key not found');
}
+ /**
+ * Unwraps the symmetric key an email's contents are encrypted with, as base64.
+ */
+ private static async resolveEmailSymmetricKey(email: { wraps: EmailKeyWrap[] }, encryptionKeys: EncryptionKey[]): Promise<string> {
+ const wrap = EncryptionUtility.resolveEmailWrap(email, encryptionKeys);
+ const privateKey = await EncryptionUtility.getPrivateKeyObject(wrap.encryptionKey);
+ const symmetricKey = await EncryptionUtility.decryptWithPrivateKeyObject(wrap.encryptedSymmetricKey, privateKey);
+
+ return Buffer.from(symmetricKey).toString('base64');
+ }
+
/**
* Decrypts an individual email based on the provided public/private key pairs.
*/
- public static async decryptEmail(
- email: Email,
- encryptionKeys: EncryptionKey[]
- ): Promise<Email> {
+ public static async decryptEmail(email: Email, encryptionKeys: EncryptionKey[]): Promise<DecryptedEmail> {
try {
- const wrap = EncryptionUtility.resolveEmailWrap(email, encryptionKeys);
-
- // Decrypt symmetric key with asymmetric private key
- const privateKey = await EncryptionUtility.getPrivateKeyObject(wrap.encryptionKey);
- const symmetricKey = await EncryptionUtility.decryptWithPrivateKeyObject(
- wrap.encryptedSymmetricKey,
- privateKey
- );
- const symmetricKeyBase64 = Buffer.from(symmetricKey).toString('base64');
+ const symmetricKeyBase64 = await EncryptionUtility.resolveEmailSymmetricKey(email, encryptionKeys);
- // Create a new object to avoid mutating the original
const decryptedEmail = { ...email };
-
- // Decrypt all email fields
decryptedEmail.subject = await EncryptionUtility.symmetricDecrypt(email.subject, symmetricKeyBase64);
decryptedEmail.fromDisplay = await EncryptionUtility.symmetricDecrypt(email.fromDisplay, symmetricKeyBase64);
decryptedEmail.fromDomain = await EncryptionUtility.symmetricDecrypt(email.fromDomain, symmetricKeyBase64);
decryptedEmail.fromLocal = await EncryptionUtility.symmetricDecrypt(email.fromLocal, symmetricKeyBase64);
- if (email.messageHtml) {
- decryptedEmail.messageHtml = await EncryptionUtility.symmetricDecrypt(email.messageHtml, symmetricKeyBase64);
- }
- if (email.messagePlain) {
- decryptedEmail.messagePlain = await EncryptionUtility.symmetricDecrypt(email.messagePlain, symmetricKeyBase64);
- }
- if (email.messageSource) {
- decryptedEmail.messageSource = await EncryptionUtility.symmetricDecrypt(email.messageSource, symmetricKeyBase64);
+ const sourceBytes = email.messageSource ? await EncryptionUtility.symmetricDecryptBytes(Uint8Array.from(atob(email.messageSource), c => c.charCodeAt(0)), symmetricKeyBase64) : null;
+ decryptedEmail.messageSource = '';
+
+ let htmlBody: string | null = null;
+ let textBody: string | null = null;
+ let attachments: ParsedEmailAttachment[] = [];
+
+ if (sourceBytes) {
+ try {
+ const parsed = await parseEmailSource(sourceBytes);
+ htmlBody = parsed.htmlBody;
+ textBody = parsed.textBody;
+ attachments = parsed.attachments;
+ } catch (err) {
+ // A parse failure costs the bodies, not the email: the raw source view renders without the parser.
+ devWarn(`[Email] Could not parse the source of email ${email.id}:`, err);
+ }
}
- return decryptedEmail;
+ return { email: decryptedEmail, htmlBody, textBody, attachments, sourceBytes };
} catch (err) {
throw new Error(err instanceof Error ? err.message : 'Failed to decrypt email');
}
@@ -431,15 +455,7 @@ export class EncryptionUtility {
): Promise<MailboxEmail[]> {
const results = await Promise.all(emails.map(async email => {
try {
- const wrap = EncryptionUtility.resolveEmailWrap(email, encryptionKeys);
-
- // Decrypt symmetric key with asymmetric private key
- const privateKey = await EncryptionUtility.getPrivateKeyObject(wrap.encryptionKey);
- const symmetricKey = await EncryptionUtility.decryptWithPrivateKeyObject(
- wrap.encryptedSymmetricKey,
- privateKey
- );
- const symmetricKeyBase64 = Buffer.from(symmetricKey).toString('base64');
+ const symmetricKeyBase64 = await EncryptionUtility.resolveEmailSymmetricKey(email, encryptionKeys);
// Create a new object to avoid mutating the original
const decryptedEmail = { ...email };
@@ -473,17 +489,7 @@ export class EncryptionUtility {
encryptionKeys: EncryptionKey[]
): Promise<Uint8Array> {
try {
- const wrap = EncryptionUtility.resolveEmailWrap(email, encryptionKeys);
-
- // Decrypt the symmetric key using private key (returns raw bytes)
- const privateKey = await EncryptionUtility.getPrivateKeyObject(wrap.encryptionKey);
- const symmetricKey = await EncryptionUtility.decryptWithPrivateKeyObject(
- wrap.encryptedSymmetricKey,
- privateKey
- );
-
- // Convert symmetric key to base64 string if symmetricDecrypt expects it
- const symmetricKeyBase64 = Buffer.from(symmetricKey).toString('base64');
+ const symmetricKeyBase64 = await EncryptionUtility.resolveEmailSymmetricKey(email, encryptionKeys);
// Decrypt the attachment using raw bytes
return await EncryptionUtility.symmetricDecryptBytes(encryptedBytes, symmetricKeyBase64);
diff --git a/apps/browser-extension/src/utils/RustCore.ts b/apps/browser-extension/src/utils/RustCore.ts
index d68dcba8f..1fc6db3ee 100644
--- a/apps/browser-extension/src/utils/RustCore.ts
+++ b/apps/browser-extension/src/utils/RustCore.ts
@@ -171,6 +171,47 @@ export async function getIdentityAgeRanges(): Promise<string[]> {
return core.getIdentityAgeRanges() as string[];
}
+/**
+ * A single attachment of a parsed email message. Metadata only: fetch the bytes with
+ * {@link extractEmailAttachment} using this attachment's index in {@link ParsedEmail.attachments}.
+ */
+export type ParsedEmailAttachment = {
+ filename: string;
+ mimeType: string;
+ size: number;
+};
+
+/** Result of parsing a raw RFC 822 email source. Body fields are null when the message has no such part. */
+export type ParsedEmail = {
+ htmlBody: string | null;
+ textBody: string | null;
+ attachments: ParsedEmailAttachment[];
+};
+
+/**
+ * Parse a raw RFC 822 email source into its html/plain bodies and attachment metadata.
+ */
+export async function parseEmailSource(source: Uint8Array): Promise<ParsedEmail> {
+ await initRustCore();
+ return core.parseEmailSource(source) as ParsedEmail;
+}
+
+/**
+ * Turn a stored email source into the raw RFC 822 message bytes for showing the message source without parsing it.
+ */
+export async function decodeEmailSource(source: Uint8Array): Promise<Uint8Array> {
+ await initRustCore();
+ return core.decodeEmailSource(source) as Uint8Array;
+}
+
+/**
+ * Extract the decoded bytes of one attachment, identified by its index in the parsed attachment list.
+ */
+export async function extractEmailAttachment(source: Uint8Array, index: number): Promise<Uint8Array> {
+ await initRustCore();
+ return core.extractEmailAttachment(source, index) as Uint8Array;
+}
+
/**
* Generate a random 32-byte seed as a 64-character hex string, suitable for the
* `seed` argument of {@link generatePassword}.
diff --git a/apps/browser-extension/src/utils/dist/core/models/webapi/index.d.ts b/apps/browser-extension/src/utils/dist/core/models/webapi/index.d.ts
index c64316ad6..c6c7f1f2a 100644
--- a/apps/browser-extension/src/utils/dist/core/models/webapi/index.d.ts
+++ b/apps/browser-extension/src/utils/dist/core/models/webapi/index.d.ts
@@ -211,15 +211,7 @@ type EmailAttachment = {
};
type Email = {
- /** The body of the email message. Null for source-only stored emails: derive it by parsing the source */
- messageHtml: string | null;
- /** The plain text body of the email message. Null for source-only stored emails: derive it by parsing the source */
- messagePlain: string | null;
- /**
- * The raw RFC 822 source of the email message (ciphertext, base64). For source-only stored emails the
- * decrypted plaintext is gzip-compressed and starts with the gzip magic bytes 0x1f 0x8b; parse the
- * (decompressed) source to derive the bodies and attachments.
- */
+ /** The raw RFC 822 source of the email message (ciphertext, base64) */
messageSource: string;
/** The number of attachments contained in the email message */
attachmentCount: number;
diff --git a/apps/mobile-app/utils/dist/core/models/webapi/index.d.ts b/apps/mobile-app/utils/dist/core/models/webapi/index.d.ts
index baebb60e1..c6c7f1f2a 100644
--- a/apps/mobile-app/utils/dist/core/models/webapi/index.d.ts
+++ b/apps/mobile-app/utils/dist/core/models/webapi/index.d.ts
@@ -211,12 +211,10 @@ type EmailAttachment = {
};
type Email = {
- /** The body of the email message */
- messageHtml: string;
- /** The plain text body of the email message */
- messagePlain: string;
- /** The raw RFC 822 source of the email message */
+ /** The raw RFC 822 source of the email message (ciphertext, base64) */
messageSource: string;
+ /** The number of attachments contained in the email message */
+ attachmentCount: number;
/** The ID of the email */
id: number;
/** The subject of the email */
diff --git a/apps/server/AliasVault.Api/Controllers/V2/Email/EmailController.cs b/apps/server/AliasVault.Api/Controllers/V2/Email/EmailController.cs
index fdc50ad70..8432ba1db 100644
--- a/apps/server/AliasVault.Api/Controllers/V2/Email/EmailController.cs
+++ b/apps/server/AliasVault.Api/Controllers/V2/Email/EmailController.cs
@@ -55,8 +55,6 @@ public class EmailController(ILogger<EmailController> logger, IAliasServerDbCont
Date = email.Date,
DateSystem = DateTime.SpecifyKind(email.DateSystem, DateTimeKind.Utc),
SecondsAgo = (int)DateTime.UtcNow.Subtract(email.DateSystem).TotalSeconds,
- MessageHtml = email.MessageHtml,
- MessagePlain = email.MessagePlain,
MessageSource = email.MessageSourceBytes is not null ? Convert.ToBase64String(email.MessageSourceBytes) : email.MessageSource,
AttachmentCount = email.AttachmentCount,
Wraps = callerWraps.Select(w => new EmailKeyWrapApiModel { PublicKey = w.EncryptionKey.PublicKey, EncryptedSymmetricKey = w.EncryptedSymmetricKey }).ToList(),
diff --git a/apps/server/Databases/AliasServerDb/Email.cs b/apps/server/Databases/AliasServerDb/Email.cs
index 71cc12d2e..a2e12eec0 100644
--- a/apps/server/Databases/AliasServerDb/Email.cs
+++ b/apps/server/Databases/AliasServerDb/Email.cs
@@ -76,12 +76,12 @@ public class Email
public DateTime DateSystem { get; set; }
/// <summary>
- /// Gets or sets the HTML content of the email message.
+ /// Gets or sets the HTML content of the email message. No longer served by the v2 API and no longer filled in since 0.31.0 in favor of MessageSource. TODO: remove this column in a future version.
/// </summary>
public string? MessageHtml { get; set; }
/// <summary>
- /// Gets or sets the plain text content of the email message.
+ /// Gets or sets the plain text content of the email message. No longer served by the v2 API and no longer filled in since 0.31.0 in favor of MessageSource. TODO: remove this column in a future version.
/// </summary>
public string? MessagePlain { get; set; }
diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Email/EmailApiModel.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Email/EmailApiModel.cs
index bfe4f60bd..1d29408b4 100644
--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Email/EmailApiModel.cs
+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Email/EmailApiModel.cs
@@ -13,19 +13,9 @@ namespace AliasVault.Shared.Models.WebApi.V2.Email;
public class EmailApiModel : EmailApiModelBase
{
/// <summary>
- /// Gets or sets the HTML content of the email message.
- /// </summary>
- public string? MessageHtml { get; set; }
-
- /// <summary>
- /// Gets or sets the plain text content of the email message.
- /// </summary>
- public string? MessagePlain { get; set; }
-
- /// <summary>
- /// Gets or sets the source content of the email message as base64 ciphertext. For source-only stored
- /// emails the decrypted plaintext is gzip-compressed: clients detect this via the gzip magic bytes
- /// (0x1f 0x8b) and parse the bodies and attachments from the decompressed source.
+ /// Gets or sets the source content of the email message as base64 ciphertext which contains the raw RFC 822 message bytes.
+ /// The other MessagePlain and MessageHtml DB fields are no longer served by the v2 API as these columns are deprecated,
+ /// only filled in for legacy emails (pre-0.31.0) and will be removed from the DB in a future version.
/// </summary>
public string? MessageSource { get; set; }
diff --git a/core/models/src/webapi/Email.ts b/core/models/src/webapi/Email.ts
index 3230dd653..69848754c 100644
--- a/core/models/src/webapi/Email.ts
+++ b/core/models/src/webapi/Email.ts
@@ -2,17 +2,7 @@ import { EmailAttachment } from "./EmailAttachment";
import { EmailKeyWrap } from "./EmailKeyWrap";
export type Email = {
- /** The body of the email message. Null for source-only stored emails: derive it by parsing the source */
- messageHtml: string | null;
-
- /** The plain text body of the email message. Null for source-only stored emails: derive it by parsing the source */
- messagePlain: string | null;
-
- /**
- * The raw RFC 822 source of the email message (ciphertext, base64). For source-only stored emails the
- * decrypted plaintext is gzip-compressed and starts with the gzip magic bytes 0x1f 0x8b; parse the
- * (decompressed) source to derive the bodies and attachments.
- */
+ /** The raw RFC 822 source of the email message (ciphertext, base64) */
messageSource: string;
/** The number of attachments contained in the email message */
diff --git a/core/rust/Cargo.lock b/core/rust/Cargo.lock
index 80cd22533..da5038152 100644
--- a/core/rust/Cargo.lock
+++ b/core/rust/Cargo.lock
@@ -19,6 +19,7 @@ dependencies = [
"digest",
"flate2",
"getrandom",
+ "mail-parser",
"num-bigint",
"rand",
"serde",
@@ -352,6 +353,21 @@ dependencies = [
"subtle",
]
+[[package]]
+name = "encoding_rs"
+version = "0.8.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
[[package]]
name = "flate2"
version = "1.1.9"
@@ -412,12 +428,40 @@ dependencies = [
"scroll",
]
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "hashify"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd1246c0e5493286aeb2dde35b1f4eb9c4ce00e628641210a5e553fc001a1f26"
+dependencies = [
+ "indexmap",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
[[package]]
name = "heck"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
@@ -458,6 +502,16 @@ version = "0.4.29"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+[[package]]
+name = "mail-parser"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4084ec5c2f90b341d0c70990e92a23b128f75ca14fc1dd5edd8fd5c9b417da4d"
+dependencies = [
+ "encoding_rs",
+ "hashify",
+]
+
[[package]]
name = "memchr"
version = "2.7.6"
diff --git a/core/rust/Cargo.toml b/core/rust/Cargo.toml
index 507439f97..69d1f6da8 100644
--- a/core/rust/Cargo.toml
+++ b/core/rust/Cargo.toml
@@ -64,6 +64,9 @@ wasm-bindgen = { version = "0.2", optional = true }
serde-wasm-bindgen = { version = "0.6", optional = true }
console_error_panic_hook = { version = "0.1", optional = true }
+# Parse emails from source
+mail-parser = { version = "0.11.6", features = ["full_encoding"] }
+
[dev-dependencies]
# Build dependencies for UniFFI
diff --git a/core/rust/src/email_parser/mod.rs b/core/rust/src/email_parser/mod.rs
new file mode 100644
index 000000000..60f7ce21f
--- /dev/null
+++ b/core/rust/src/email_parser/mod.rs
@@ -0,0 +1,142 @@
+//! Email MIME parsing for source-only stored emails.
+use mail_parser::{MessageParser, MimeHeaders};
+use serde::Serialize;
+use std::io::Read;
+
+use crate::error::{VaultError, VaultResult};
+
+/// A single attachment of a parsed email message. Metadata only: fetch the bytes with
+/// [`extract_email_attachment`] using this attachment's index in [`ParsedEmail::attachments`].
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ParsedEmailAttachment {
+ pub filename: String,
+ pub mime_type: String,
+ /// The decoded attachment size in bytes.
+ pub size: u64,
+}
+
+/// The result of parsing a raw RFC 822 email source.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ParsedEmail {
+ pub html_body: Option<String>,
+ pub text_body: Option<String>,
+ /// The attachments contained in the message, in the index order [`extract_email_attachment`] expects.
+ pub attachments: Vec<ParsedEmailAttachment>,
+}
+
+/// Parse a raw RFC 822 email source into its bodies and attachment metadata, transparently
+/// gunzipping gzip-compressed input.
+pub fn parse_email_source(source: &[u8]) -> VaultResult<ParsedEmail> {
+ let raw = decode_email_source(source)?;
+
+ let message = MessageParser::default()
+ .parse(raw.as_slice())
+ .ok_or_else(|| VaultError::General("Failed to parse email source as a MIME message".to_string()))?;
+
+ let has_html_part = message.html_body.iter().any(|id| message.part(*id).is_some_and(|part| part.is_text_html()));
+ let has_text_part = message.text_body.iter().any(|id| message.part(*id).is_some_and(|part| part.is_text() && !part.is_text_html()));
+ let html_body = if has_html_part { message.body_html(0).map(|body| body.to_string()) } else { None };
+ let text_body = if has_text_part { message.body_text(0).map(|body| body.to_string()) } else { None };
+
+ let attachments = message
+ .attachments()
+ .map(|part| ParsedEmailAttachment {
+ filename: part.attachment_name().unwrap_or_default().to_string(),
+ mime_type: part
+ .content_type()
+ .map(|content_type| match content_type.subtype() {
+ Some(subtype) => format!("{}/{}", content_type.ctype(), subtype),
+ None => content_type.ctype().to_string(),
+ })
+ .unwrap_or_else(|| "application/octet-stream".to_string()),
+ size: part.contents().len() as u64,
+ })
+ .collect();
+
+ Ok(ParsedEmail { html_body, text_body, attachments })
+}
+
+/// Turn a stored email source into the raw RFC 822 message bytes: gunzip the source-only storage
+/// format, repair the double encoding of the legacy format. Clients use this for the source view.
+pub fn decode_email_source(source: &[u8]) -> VaultResult<Vec<u8>> {
+ Ok(match decompress_if_gzip(source)? {
+ MaybeDecompressed::Decompressed(raw) => raw,
+ MaybeDecompressed::AsIs(raw) => repair_legacy_double_encoding(raw),
+ })
+}
+
+/// Extract the decoded bytes of a single attachment, identified by its index in
+/// [`ParsedEmail::attachments`]. Only that attachment's bytes are returned, so downloading one
+/// attachment never marshals the whole message.
+pub fn extract_email_attachment(source: &[u8], index: usize) -> VaultResult<Vec<u8>> {
+ let raw = decode_email_source(source)?;
+
+ let message = MessageParser::default()
+ .parse(raw.as_slice())
+ .ok_or_else(|| VaultError::General("Failed to parse email source as a MIME message".to_string()))?;
+
+ // Bind before returning: the attachments iterator borrows `message`, which owns the parsed source.
+ let extracted = message.attachments().nth(index).map(|part| part.contents().to_vec());
+
+ extracted.ok_or_else(|| VaultError::General(format!("Email has no attachment at index {}", index)))
+}
+
+/// Parse a raw RFC 822 email source and return the result as a JSON string (for uniffi/ffi callers).
+pub fn parse_email_source_json(source: &[u8]) -> VaultResult<String> {
+ let parsed = parse_email_source(source)?;
+ serde_json::to_string(&parsed).map_err(VaultError::from)
+}
+
+/// The outcome of the gzip check, which also tells the caller which storage format the source came from.
+enum MaybeDecompressed {
+ Decompressed(Vec<u8>),
+ AsIs(Vec<u8>),
+}
+
+/// Gunzip the input when it starts with the gzip magic bytes (0x1f 0x8b), pass it through otherwise.
+fn decompress_if_gzip(source: &[u8]) -> VaultResult<MaybeDecompressed> {
+ if source.len() < 2 || source[0] != 0x1f || source[1] != 0x8b {
+ return Ok(MaybeDecompressed::AsIs(source.to_vec()));
+ }
+
+ let mut decoder = flate2::read::GzDecoder::new(source);
+ let mut decompressed = Vec::new();
+ decoder
+ .read_to_end(&mut decompressed)
+ .map_err(|e| VaultError::General(format!("Failed to gunzip email source: {}", e)))?;
+ Ok(MaybeDecompressed::Decompressed(decompressed))
+}
+
+/// Undo the double UTF-8 encoding that legacy (pre source-only format) emails were stored with.
+///
+/// The server (pre-0.31.0) used to persist the raw source as a string via MimeKit's `MimeMessage.ToString()`, which
+/// decodes the message bytes as Latin-1 (one char per byte), and then encrypted that string as UTF-8.
+/// Every non-ASCII byte was therefore encoded twice on the way in: `é` (`C3 A9`) was stored as `C3 83 C2 A9`.
+/// That went unnoticed while clients rendered the separately stored (correctly decoded) html/plain columns,
+/// but shows up as incorrect now that the bodies are parsed out of the source itself. Mapping each decoded
+/// character back to a single byte reverses it exactly.
+///
+/// Only input that is valid UTF-8 consisting solely of characters <= U+00FF can be such a round trip, so
+/// anything else - including an already correct raw source - is returned unchanged.
+fn repair_legacy_double_encoding(raw: Vec<u8>) -> Vec<u8> {
+ let text = match std::str::from_utf8(&raw) {
+ Ok(text) => text,
+ Err(_) => return raw,
+ };
+
+ if !text.chars().any(|c| c as u32 > 0x7f) {
+ // Pure ASCII: the double encoding was a no-op, so there is nothing to undo.
+ return raw;
+ }
+
+ if text.chars().any(|c| c as u32 > 0xff) {
+ return raw;
+ }
+
+ text.chars().map(|c| c as u8).collect()
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/core/rust/src/email_parser/tests.rs b/core/rust/src/email_parser/tests.rs
new file mode 100644
index 000000000..2eee08c8b
--- /dev/null
+++ b/core/rust/src/email_parser/tests.rs
@@ -0,0 +1,232 @@
+use super::*;
+use std::io::Write;
+
+const PLAIN_EMAIL: &str = "From: Alice <[email protected]>\r\n\
+Subject: Hello\r\n\
+Date: Mon, 10 Aug 2026 12:00:00 +0000\r\n\
+Content-Type: text/plain; charset=utf-8\r\n\
+\r\n\
+Hello Bob, this is a plain text email.\r\n";
+
+const MULTIPART_EMAIL: &str = "From: Alice <[email protected]>\r\n\
+Subject: Multipart\r\n\
+MIME-Version: 1.0\r\n\
+Content-Type: multipart/mixed; boundary=\"outer\"\r\n\
+\r\n\
+--outer\r\n\
+Content-Type: multipart/alternative; boundary=\"inner\"\r\n\
+\r\n\
+--inner\r\n\
+Content-Type: text/plain; charset=utf-8\r\n\
+\r\n\
+Plain version.\r\n\
+--inner\r\n\
+Content-Type: text/html; charset=utf-8\r\n\
+\r\n\
+<html><body><p>Html version.</p></body></html>\r\n\
+--inner--\r\n\
+--outer\r\n\
+Content-Type: application/pdf\r\n\
+Content-Disposition: attachment; filename=\"report.pdf\"\r\n\
+Content-Transfer-Encoding: base64\r\n\
+\r\n\
+JVBERi1oZWxsbw==\r\n\
+--outer--\r\n";
+
+const UNICODE_EMAIL: &str = "From: Alice <[email protected]>\r\n\
+Subject: Unicode\r\n\
+MIME-Version: 1.0\r\n\
+Content-Type: text/plain; charset=utf-8\r\n\
+Content-Transfer-Encoding: 8bit\r\n\
+\r\n\
+Special symbols: é€ñ ∑ • ≈\r\n";
+
+fn gzip(data: &[u8]) -> Vec<u8> {
+ let mut encoder = flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::default());
+ encoder.write_all(data).unwrap();
+ encoder.finish().unwrap()
+}
+
+/// Reproduce how the server used to store a legacy email source: the raw bytes read back as Latin-1
+/// (MimeKit's `MimeMessage.ToString()`) and then encoded as UTF-8 again when the string was encrypted.
+fn legacy_double_encode(raw: &[u8]) -> Vec<u8> {
+ raw.iter().map(|byte| *byte as char).collect::<String>().into_bytes()
+}
+
+#[test]
+fn parses_plain_text_email() {
+ let parsed = parse_email_source(PLAIN_EMAIL.as_bytes()).unwrap();
+
+ assert_eq!(parsed.text_body.as_deref(), Some("Hello Bob, this is a plain text email.\r\n"));
+ assert!(parsed.html_body.is_none(), "plain-only email must not get a synthesized html body");
+ assert!(parsed.attachments.is_empty());
+}
+
+#[test]
+fn parses_multipart_email_with_attachment() {
+ let parsed = parse_email_source(MULTIPART_EMAIL.as_bytes()).unwrap();
+
+ assert!(parsed.html_body.as_deref().unwrap().contains("<p>Html version.</p>"));
+ assert!(parsed.text_body.as_deref().unwrap().contains("Plain version."));
+ assert_eq!(parsed.attachments.len(), 1);
+
+ let attachment = &parsed.attachments[0];
+ assert_eq!(attachment.filename, "report.pdf");
+ assert_eq!(attachment.mime_type, "application/pdf");
+ assert_eq!(attachment.size, 10);
+ assert_eq!(extract_email_attachment(MULTIPART_EMAIL.as_bytes(), 0).unwrap(), b"%PDF-hello");
+}
+
+#[test]
+fn gunzips_compressed_source_transparently() {
+ let compressed = gzip(MULTIPART_EMAIL.as_bytes());
+ assert_eq!(&compressed[..2], &[0x1f, 0x8b], "gzip output must carry the magic bytes clients sniff");
+
+ let parsed = parse_email_source(&compressed).unwrap();
+ assert!(parsed.html_body.as_deref().unwrap().contains("<p>Html version.</p>"));
+ assert_eq!(parsed.attachments.len(), 1);
+ let decoded = decode_email_source(&compressed).unwrap();
+ assert!(String::from_utf8_lossy(&decoded).contains("Subject: Multipart"), "source view must show the decompressed source");
+}
+
+#[test]
+fn html_only_email_has_no_synthesized_text_body() {
+ let email = "From: [email protected]\r\nTo: [email protected]\r\nSubject: X\r\nContent-Type: text/html\r\n\r\n<p>Hi</p>\r\n";
+ let parsed = parse_email_source(email.as_bytes()).unwrap();
+
+ assert!(parsed.html_body.is_some());
+ assert!(parsed.text_body.is_none(), "html-only email must not get a synthesized text body");
+}
+
+#[test]
+fn legacy_double_encoded_source_is_repaired() {
+ let stored = legacy_double_encode(UNICODE_EMAIL.as_bytes());
+ assert_ne!(stored, UNICODE_EMAIL.as_bytes(), "the fixture must actually be double encoded");
+
+ let parsed = parse_email_source(&stored).unwrap();
+
+ assert_eq!(parsed.text_body.as_deref(), Some("Special symbols: é€ñ ∑ • ≈\r\n"));
+
+ let decoded = decode_email_source(&stored).unwrap();
+ assert_eq!(decoded, UNICODE_EMAIL.as_bytes(), "the source view must show the repaired bytes");
+}
+
+#[test]
+fn legacy_double_encoded_attachment_bytes_are_repaired() {
+ let email = "From: [email protected]\r\n\
+Subject: Attachment\r\n\
+MIME-Version: 1.0\r\n\
+Content-Type: multipart/mixed; boundary=\"b\"\r\n\
+\r\n\
+--b\r\n\
+Content-Type: text/plain; charset=utf-8\r\n\
+\r\n\
+Body\r\n\
+--b\r\n\
+Content-Type: text/plain; charset=utf-8\r\n\
+Content-Disposition: attachment; filename=\"notes.txt\"\r\n\
+Content-Transfer-Encoding: 8bit\r\n\
+\r\n\
+Prijs: 10€\r\n\
+--b--\r\n";
+
+ let parsed = parse_email_source(&legacy_double_encode(email.as_bytes())).unwrap();
+
+ assert_eq!(parsed.attachments.len(), 1);
+ let content = extract_email_attachment(&legacy_double_encode(email.as_bytes()), 0).unwrap();
+ assert_eq!(String::from_utf8(content).unwrap().trim_end(), "Prijs: 10€");
+}
+
+#[test]
+fn compressed_source_is_never_repaired() {
+ // Source-only stored emails hold the message bytes verbatim: applying the legacy repair to them
+ // would map each decoded scalar back to a single byte and mangle every non-ASCII character.
+ let parsed = parse_email_source(&gzip(UNICODE_EMAIL.as_bytes())).unwrap();
+
+ assert_eq!(parsed.text_body.as_deref(), Some("Special symbols: é€ñ ∑ • ≈\r\n"));
+}
+
+#[test]
+fn ascii_only_source_is_passed_through_unchanged() {
+ // ASCII survives the legacy double encoding untouched, so the repair must be a no-op for it.
+ assert_eq!(decode_email_source(PLAIN_EMAIL.as_bytes()).unwrap(), PLAIN_EMAIL.as_bytes());
+}
+
+#[test]
+fn decodes_legacy_cjk_charsets() {
+ // Requires mail-parser's full_encoding feature: without it these charsets have no decoder and
+ // the body degrades to replacement characters. MimeKit decoded them before the client-side parse.
+ let cases: [(&str, &[u8], &str); 3] = [
+ ("shift_jis", b"\x83n\x83\x8d\x81[", "ハロー"),
+ ("gbk", b"\xc4\xe3\xba\xc3", "你好"),
+ ("euc-kr", b"\xbe\xc8\xb3\xe7", "안녕"),
+ ];
+
+ for (charset, body, expected) in cases {
+ let mut email = format!("From: [email protected]\r\nTo: [email protected]\r\nSubject: X\r\nMIME-Version: 1.0\r\nContent-Type: text/plain; charset={}\r\nContent-Transfer-Encoding: 8bit\r\n\r\n", charset).into_bytes();
+ email.extend_from_slice(body);
+
+ let parsed = parse_email_source(&email).unwrap();
+ assert_eq!(parsed.text_body.as_deref(), Some(expected), "charset {} did not decode", charset);
+ }
+}
+
+#[test]
+fn extracts_attachments_by_index() {
+ let email = "From: [email protected]\r\n\
+Subject: Two\r\n\
+MIME-Version: 1.0\r\n\
+Content-Type: multipart/mixed; boundary=\"b\"\r\n\
+\r\n\
+--b\r\n\
+Content-Type: text/plain\r\n\
+\r\n\
+Body\r\n\
+--b\r\n\
+Content-Type: application/octet-stream\r\n\
+Content-Disposition: attachment; filename=\"first.bin\"\r\n\
+Content-Transfer-Encoding: base64\r\n\
+\r\n\
+Zmlyc3Q=\r\n\
+--b\r\n\
+Content-Type: application/octet-stream\r\n\
+Content-Disposition: attachment; filename=\"second.bin\"\r\n\
+Content-Transfer-Encoding: base64\r\n\
+\r\n\
+c2Vjb25k\r\n\
+--b--\r\n";
+
+ let parsed = parse_email_source(email.as_bytes()).unwrap();
+ assert_eq!(parsed.attachments.iter().map(|a| a.filename.as_str()).collect::<Vec<_>>(), ["first.bin", "second.bin"]);
+
+ assert_eq!(extract_email_attachment(email.as_bytes(), 0).unwrap(), b"first");
+ assert_eq!(extract_email_attachment(email.as_bytes(), 1).unwrap(), b"second");
+ assert!(extract_email_attachment(email.as_bytes(), 2).is_err(), "an out of range index must error, not return empty bytes");
+}
+
+#[test]
+fn extracts_attachments_from_compressed_source() {
+ let compressed = gzip(MULTIPART_EMAIL.as_bytes());
+
+ assert_eq!(extract_email_attachment(&compressed, 0).unwrap(), b"%PDF-hello");
+}
+
+#[test]
+fn invalid_gzip_input_errors() {
+ let bogus = [0x1f, 0x8b, 0x00, 0x01, 0x02];
+ assert!(parse_email_source(&bogus).is_err());
+}
+
+#[test]
+fn json_output_uses_camel_case_fields() {
+ let json = parse_email_source_json(MULTIPART_EMAIL.as_bytes()).unwrap();
+ assert!(json.contains("\"htmlBody\""));
+ assert!(json.contains("\"textBody\""));
+ assert!(json.contains("\"mimeType\""));
+ assert!(!json.contains("\"contentBase64\""), "attachment bytes must not ride along in the parse result");
+}
diff --git a/core/rust/src/lib.rs b/core/rust/src/lib.rs
index 3de537c5c..ac2c5b8db 100644
--- a/core/rust/src/lib.rs
+++ b/core/rust/src/lib.rs
@@ -20,6 +20,7 @@ pub mod vault_merge;
pub mod vault_codec;
pub mod vault_pruner;
pub mod credential_matcher;
+pub mod email_parser;
pub mod password_generator;
pub mod identity_generator;
pub mod srp;
@@ -44,6 +45,7 @@ pub use credential_matcher::{
filter_credentials, extract_domain, extract_root_domain,
AutofillMatchingMode, CredentialMatcherInput, CredentialMatcherOutput,
};
+pub use email_parser::{ParsedEmail, ParsedEmailAttachment};
pub use password_generator::{generate_password, PasswordSettings};
pub use identity_generator::{generate_identity, Identity, IdentityRequest};
pub use srp::{
diff --git a/core/rust/src/uniffi_api.rs b/core/rust/src/uniffi_api.rs
index 22431a62f..352573e60 100644
--- a/core/rust/src/uniffi_api.rs
+++ b/core/rust/src/uniffi_api.rs
@@ -189,6 +189,27 @@ pub fn get_identity_languages() -> Vec<String> {
crate::identity_generator::available_languages()
}
+/// Parse a raw RFC 822 email source into its html/plain bodies and attachment metadata, returned as
+/// a JSON string (`{htmlBody, textBody, attachments: [{filename, mimeType, size}]}`). Input that
+/// starts with the gzip magic bytes (0x1f 0x8b) is gunzipped, so the decrypted
+/// `MessageSource` of both legacy and source-only emails can be passed as-is.
+#[uniffi::export]
+pub fn parse_email_source(source: Vec<u8>) -> Result<String, VaultError> {
+ crate::email_parser::parse_email_source_json(&source)
+}
+
+/// Turn a stored email source into the raw RFC 822 message bytes for showing the message source without parsing it.
+#[uniffi::export]
+pub fn decode_email_source(source: Vec<u8>) -> Result<Vec<u8>, VaultError> {
+ crate::email_parser::decode_email_source(&source)
+}
+
+/// Extract the decoded bytes of one attachment, identified by its index in the parsed attachment list.
+#[uniffi::export]
+pub fn extract_email_attachment(source: Vec<u8>, index: u32) -> Result<Vec<u8>, VaultError> {
+ crate::email_parser::extract_email_attachment(&source, index as usize)
+}
+
/// Get the list of age range option values ("random" plus 5-year ranges).
#[uniffi::export]
pub fn get_identity_age_ranges() -> Vec<String> {
diff --git a/core/rust/src/wasm.rs b/core/rust/src/wasm.rs
index c0b259424..74f50b3db 100644
--- a/core/rust/src/wasm.rs
+++ b/core/rust/src/wasm.rs
@@ -1,5 +1,6 @@
//! WASM bindings for browser extension.
+use serde::Serialize;
use wasm_bindgen::prelude::*;
use crate::credential_matcher::{
@@ -358,6 +359,37 @@ pub fn get_identity_languages_js() -> Vec<String> {
crate::identity_generator::available_languages()
}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Email Parser WASM Bindings
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// Parse a raw RFC 822 email source into its html/plain bodies and attachment metadata.
+/// Input that starts with the gzip magic bytes (0x1f 0x8b) is gunzipped, so the
+/// decrypted `MessageSource` of both legacy and source-only emails can be passed as-is.
+#[wasm_bindgen(js_name = parseEmailSource)]
+pub fn parse_email_source_js(source: &[u8]) -> Result<JsValue, JsValue> {
+ let parsed = crate::email_parser::parse_email_source(source)
+ .map_err(|e| JsValue::from_str(&format!("Email parse failed: {}", e)))?;
+
+ parsed
+ .serialize(&serde_wasm_bindgen::Serializer::new().serialize_maps_as_objects(true).serialize_missing_as_null(true))
+ .map_err(|e| JsValue::from_str(&format!("Failed to serialize output: {}", e)))
+}
+
+/// Turn a stored email source into the raw RFC 822 message bytes for showing the message source without parsing it.
+#[wasm_bindgen(js_name = decodeEmailSource)]
+pub fn decode_email_source_js(source: &[u8]) -> Result<Vec<u8>, JsValue> {
+ crate::email_parser::decode_email_source(source)
+ .map_err(|e| JsValue::from_str(&format!("Email source decode failed: {}", e)))
+}
+
+/// Extract the decoded bytes of one attachment, identified by its index in the parsed attachment list.
+#[wasm_bindgen(js_name = extractEmailAttachment)]
+pub fn extract_email_attachment_js(source: &[u8], index: usize) -> Result<Vec<u8>, JsValue> {
+ crate::email_parser::extract_email_attachment(source, index)
+ .map_err(|e| JsValue::from_str(&format!("Email attachment extraction failed: {}", e)))
+}
+
/// Get the list of age range option values ("random" plus 5-year ranges).
#[wasm_bindgen(js_name = getIdentityAgeRanges)]
pub fn get_identity_age_ranges_js() -> Vec<String> {