Added mailboxes as local data sources (#1022)

app/MindWork AI Studio/Tools/Mail/MailContentKey.cs

@@ -0,0 +1,66 @@
+using System.Globalization;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace AIStudio.Tools.Mail;
+
+/// <summary>
+/// Gives a mail the key of its document in the index, the same in every folder it lies in.
+/// </summary>
+/// <remarks>
+/// The key follows the mail rather than its place: a mail moved to another folder, or found again
+/// after the server reset the UIDs of a folder (UIDVALIDITY), keeps its key, so only its location
+/// changes and nothing gets embedded again. In the order the server can tell, it comes from:
+/// <list type="number">
+///   <item>the EMAILID of RFC 8474, which the server keeps for a mail across all its folders;</item>
+///   <item>the X-GM-MSGID, which is the same for Gmail;</item>
+///   <item>a hash over Message-ID, Date, From, Subject and the size, all of which a server reports
+///   without the mail itself being fetched. Two mails alike in all of these are copies of one mail.</item>
+/// </list>
+/// The key is "mail:" and a SHA-256 in hex, whichever of the three it comes from. The value it
+/// hashes names its origin, so an EMAILID which happens to read like a Gmail id cannot meet one.
+/// The key goes through no Path API, see "Indexed data sources" in AGENTS.md.
+/// </remarks>
+public static class MailContentKey
+{
+    public const string PREFIX = "mail:";
+
+    /// <summary>
+    /// Builds the key of a mail.
+    /// </summary>
+    /// <param name="identity">What the server reported about the mail.</param>
+    /// <returns>The key, starting with "mail:".</returns>
+    public static string Create(MailIdentity identity)
+    {
+        if (!string.IsNullOrWhiteSpace(identity.EmailId))
+            return Hash($"emailid\n{identity.EmailId.Trim()}");
+
+        if (identity.GmailMessageId is { } gmailMessageId)
+            return Hash($"x-gm-msgid\n{gmailMessageId.ToString(CultureInfo.InvariantCulture)}");
+
+        var fields = new StringBuilder("headers");
+        fields.Append('\n').Append(NormalizeMessageId(identity.MessageId));
+        fields.Append('\n').Append(identity.Date?.ToUniversalTime().ToString("O", CultureInfo.InvariantCulture));
+        fields.Append('\n').Append(string.Join(',', identity.FromAddresses.Select(address => address.Trim().ToLowerInvariant())));
+        fields.Append('\n').Append(NormalizeWhitespace(identity.Subject));
+        fields.Append('\n').Append(identity.Size.ToString(CultureInfo.InvariantCulture));
+        return Hash(fields.ToString());
+    }
+
+    private static string Hash(string value) => PREFIX + Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(value)));
+
+    /// <summary>
+    /// The Message-ID without its angle brackets, which one reader keeps and the next one drops.
+    /// </summary>
+    private static string NormalizeMessageId(string? messageId)
+    {
+        var trimmed = messageId?.Trim() ?? string.Empty;
+        return trimmed.Length > 1 && trimmed[0] == '<' && trimmed[^1] == '>' ? trimmed[1..^1].Trim() : trimmed;
+    }
+
+    /// <summary>
+    /// A subject with every run of whitespace as one space, since folding a long header line
+    /// leaves line breaks behind which not every reader unfolds alike.
+    /// </summary>
+    private static string NormalizeWhitespace(string? text) => string.Join(' ', (text ?? string.Empty).Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries));
+}