editheader: a script can rewrite the message it is filing

addheader and deleteheader (RFC 5293), advertised over ManageSieve.
addheader inserts at the top of the header by default and at the
bottom under :last; deleteheader removes every instance of a name, the
nth under :index/:last, or only the instances whose value matches
under :is/:contains/:matches with the comparator honoured.

The evaluator only DECIDES. The edits travel in script order in the
structured result - order matters, because "deleteheader X; addheader
X" is a replace and the other way round is not - and
LocalDelivery::ApplySieveHeaderEdits_ rewrites the stored file BEFORE
redirects are queued, so a forwarded copy carries the edits (RFC 5293
2: an edit affects all subsequent actions), then refreshes the
recorded message size so the database row agrees with the file.

Failure handling follows the rules engine's header rewriting: a failed
load or save is reported through RuleGuard::ReportActionFailed, and a
half-parsed file is never written back - MimeLoadResult exists
precisely to tell "could not open" from "parsed half way", and writing
edits onto either would be worse than the edits not happening.

Received and Return-Path are protected AT UPLOAD, with the refusal
naming the header: the trace of how a message travelled is not a
script's to edit (RFC 5293 7). Field names are validated as legal
header names, so "Bad Name" fails with a line number rather than
producing a header no parser will read back.

The tests assert on the DELIVERED BYTES over POP3 - the file the
user's client downloads - including placement above and below existing
fields, with the negative control that a non-matching value pattern
deletes nothing. One honest limit lives in a comment where it bites:
value patterns match an RFC 2047-encoded value in its encoded form,
which can only make a delete NOT happen - the safe direction.

Suite: 1546/1546.

Author: chrisholloway5

Roadmap.md

@@ -57,7 +57,7 @@ strong and where it is thin far more honestly than any prose summary.
 | [Transport security and deliverability](#transport-security-and-deliverability) | 43 | – | 4 | 1 |
 | [IMAP](#imap) | 58 | – | 17 | 3 |
 | [POP3](#pop3) | 21 | – | 6 | – |
-| [Sieve, ManageSieve and rules](#sieve-managesieve-and-rules) | 57 | 0 | 7 | – |
+| [Sieve, ManageSieve and rules](#sieve-managesieve-and-rules) | 58 | 0 | 6 | – |
 | [Authentication and cryptography](#authentication-and-cryptography) | 57 | 0 | 18 | – |
 | [Anti-spam, anti-virus and content control](#anti-spam-anti-virus-and-content-control) | 54 | – | 13 | – |
 | [Storage, accounts and data model](#storage-accounts-and-data-model) | 86 | – | 10 | – |
@@ -72,7 +72,7 @@ strong and where it is thin far more honestly than any prose summary.
 | [Future-proofing: standards and protocols](#future-proofing-standards-and-protocols) | 2 | – | 4 | 2 |
 | [Future-proofing: platform and supply chain](#future-proofing-platform-and-supply-chain) | 5 | 1 | 2 | 2 |
 | [Future-proofing: deployment and operations](#future-proofing-deployment-and-operations) | 4 | 1 | 4 | – |
-| **Total** | **632** | **12** | **136** | **15** |
+| **Total** | **633** | **12** | **135** | **15** |
 
 Three things stand out and are worth naming rather than leaving to be inferred.
 **Storage and the administration surface are the best-covered areas**, and the
@@ -448,7 +448,7 @@ the source, not from documentation.
 
 ### Sieve, ManageSieve and rules
 
-57 shipped · 0 underway · 7 not started · 0 deferred
+58 shipped · 0 underway · 6 not started · 0 deferred
 
 | | Capability | Detail |
 |:-:|---|---|
@@ -498,7 +498,7 @@ the source, not from documentation.
 | ✅ | copy (RFC 3894) | Not implemented. There is no :copy tag on fileinto or redirect, so a redirect always cancels the implicit keep unless an explicit keep is also written **Shipped in dc9301a** - the row above described the state before it. |
 | ✅ | date and index (RFC 5260) | **Both shipped 16 August 2026**, advertised as "date" and "index" over ManageSieve. `date` and `currentdate` extract all thirteen RFC 5260 4.1 date-parts (year through weekday, including julian as Modified Julian Day and the composed iso8601/std11 forms), with real zone arithmetic: the header's wall clock and its zone are parsed SEPARATELY - `Time::GetDateTimeFromMimeHeader` folds them together and cannot express `:originalzone` - so `:zone` re-expresses the same instant and `:originalzone` keeps the header's own clock. The decisive test files on an hour the raw header never states (15:30 +0200 matched as hour 13 under :zone "+0000"), with the negative control that the unconverted hour must NOT also match. One trap found on the way, now recorded in the code: `Time::GetTimeAdjustForTimezone` answers "what do I add to reach UTC" - the NEGATED zone - and the first build shipped "+0200" as "-0200" until the end-to-end test caught it. An unknown date-part and a malformed :zone are refused at upload. `:index`/`:last` select among repeated header fields on the header, address and date tests (not envelope, which has nothing to index into); a missing nth instance matches nothing, not even "". |
 | ✅ | duplicate (RFC 7352) | **Shipped 16 August 2026.** The test in all three identifier spellings - Message-ID by default, `:header` for a named header's value, `:uniqueid` for a literal, each SOURCE-TAGGED before hashing so equal text under different spellings cannot collide (RFC 7352 3) - with `:handle` for independent windows, `:seconds` (default seven days) and `:last` measuring the window from the last occurrence. The seen-store (`SieveDuplicateTracker`) is a deliberate sibling of the vacation tracker - same file format, same SHA-256 key hashing against attacker-supplied Message-IDs forging records, same atomic sibling-write-and-rename - but it FAILS OPEN where vacation fails closed, because the common script discards on "duplicate": a wrong "duplicate" destroys a legitimate message, a wrong "new" delivers a copy twice. Unreadable store, full store (10,000 live records - no eviction, since a sender who controls their own Message-IDs could roll everyone else's records out), failed write: all answer "not a duplicate". Per-account file in the Sieve directory, removed with the account, surviving restarts. A message with no Message-ID is never a duplicate and never tracked. |
-| ⬜ | editheader (RFC 5293) | Not implemented. addheader/deleteheader are not even in the known-command list, so a script using them fails CHECKSCRIPT with "unknown command" |
+| ✅ | editheader (RFC 5293) | **Shipped 16 August 2026.** `addheader` (top of the header by default, bottom under `:last`) and `deleteheader` (every instance, the nth under `:index`/`:last`, or only value-matching instances under `:is`/`:contains`/`:matches` with the comparator honoured), advertised over ManageSieve. The evaluator only DECIDES - the edits travel in script order in the structured result, and `LocalDelivery::ApplySieveHeaderEdits_` rewrites the stored file BEFORE redirects are queued, so a forwarded copy carries them (RFC 5293 2: an edit affects all subsequent actions), then refreshes the recorded message size. A failed load or write is reported through `RuleGuard::ReportActionFailed`, the same visibility the rules engine's header rewriting gets, and a half-parsed file is never written back. Received and Return-Path are protected AT UPLOAD: the trace of how a message travelled is not a script's to edit (RFC 5293 7), and the refusal names the header. Field names are validated as legal header names. End-to-end tests assert on the DELIVERED BYTES over POP3 - placement above/below existing fields included - with the negative control that a non-matching value pattern deletes nothing. One honest limit, in a comment where it bites: value patterns match an RFC 2047-encoded value in its encoded form, which can only make a delete not happen. |
 | ⬜ | enotify (RFC 5435) | Not implemented, and refused rather than ignored: `notify` is not in the known-command allowlist, so a script using it fails at upload with "unknown command". There are no notification methods, no valid_notify_method test and no NOTIFY capability advertised over ManageSieve. |
 | ✅ | envelope (RFC 5228 §5.4) and body (RFC 5173) | **Both shipped.** `envelope` landed in dc9301a (the SMTP envelope reaches the evaluator, so `envelope "to"` works without the Delivered-To header). `body` landed 15 August 2026 with all three RFC 5173 transforms: `:raw` (the undecoded body, MIME structure ignored), `:text` (the default - the decoded text of every text/* part) and `:content` (the decoded parts whose MIME type matches, where "image" matches every subtype and "" matches every part). Transfer encoding and charset are decoded before matching, which is the point: a filter written against plain text keeps working when the sender's client base64-encodes the part. The MIME walk is depth-capped at 20 because it runs on the delivery thread. Advertised in the ManageSieve capability line under the standing rule - only once the delivery-side step exists - with seven end-to-end tests in `SieveBodyDelivery.cs` asserting **where a delivered message was filed** rather than what the evaluator reported, two of them negative controls (a non-matching body must stay in INBOX; a message with no body must match nothing, not even the empty key). |
 | ✅ | ihave (RFC 5463) and environment (RFC 5183) | **Both shipped 16 August 2026.** `ihave` answers from the SAME list `require` validates against (`SieveParser::IsSupportedExtension`), so the two can never disagree - and its dangerous half is handled: an ihave-guarded block may USE the extensions it tested for without a require line (`CollectIhaveGrants_`, scoped to the block, flowing through `allof` but deliberately not `anyof` or `not`, whose truth proves nothing about the block running). Without that grant the test is a trap - reporting an extension available that the script cannot then use. Testing for an extension this server lacks is legal at upload and evaluates false, which is the command's whole purpose. `environment` answers name/version/location(MDA)/phase(during)/host/domain truthfully and reports remote-host/remote-ip as honestly UNKNOWN - the sending client's identity does not reach the evaluator - and an unknown item matches nothing, not even the empty key. End-to-end in `SieveEnvironmentDelivery.cs`, including the grant proven by a script whose guarded block uses the body test with no require for it. |

hmailserver/source/Server/Common/Sieve/ManageSieveServer.cpp

@@ -281,7 +281,15 @@ namespace HM
       // delivers a copy twice). End-to-end tests in SieveDuplicateDelivery.cs
       // deliver the same Message-ID twice and assert the first lands in INBOX and
       // the second where the script files duplicates.
-      const char *AdvertisedSieveExtensions = "fileinto copy relational subaddress vacation vacation-seconds imap4flags body mailbox regex ihave environment date index spamtest spamtestplus duplicate";
+      // editheader (RFC 5293) moved in on 16 August 2026, under the same rule. Its
+      // delivery-side step is LocalDelivery::ApplySieveHeaderEdits_, which rewrites
+      // the stored file with the script's addheader/deleteheader edits in script
+      // order, BEFORE redirects are queued so forwarded copies carry them, and
+      // refreshes the recorded size. Received and Return-Path are protected at
+      // upload: the trace of how a message travelled is not a script's to edit.
+      // End-to-end tests in SieveEditheaderDelivery.cs read the delivered message
+      // over POP3 and assert on its actual bytes.
+      const char *AdvertisedSieveExtensions = "fileinto copy relational subaddress vacation vacation-seconds imap4flags body mailbox regex ihave environment date index spamtest spamtestplus duplicate editheader";
 
       AnsiString EscapeQuoted(const String &value)
       {

hmailserver/source/Server/Common/Sieve/SieveEvaluator.cpp

@@ -410,6 +410,55 @@ namespace HM
          return;
       }
 
+      if (name == _T("addheader") || name == _T("deleteheader"))
+      {
+         // editheader (RFC 5293). The evaluator only DECIDES; the delivery path
+         // rewrites the stored file, in script order, from these records. With no
+         // structured result - the COM diagnostic path - the summary token below
+         // is still produced, so a test evaluation shows what would happen.
+         SieveArgumentSet set;
+         String ignored;
+         if (!SieveParser::SplitArguments(command->arguments, set, ignored))
+            return;
+
+         SieveHeaderEdit edit;
+         edit.isAdd = name == _T("addheader");
+
+         if (edit.isAdd)
+         {
+            if (set.stringLists.size() != 2 || set.stringLists[0].size() != 1 || set.stringLists[1].size() != 1)
+               return;
+
+            edit.name = set.stringLists[0][0];
+            edit.value = set.stringLists[1][0];
+            edit.addLast = set.lastGiven;
+         }
+         else
+         {
+            if (set.stringLists.empty() || set.stringLists[0].size() != 1)
+               return;
+
+            edit.name = set.stringLists[0][0];
+            edit.indexGiven = set.indexGiven;
+            edit.index = set.indexValue;
+            edit.indexFromEnd = set.lastGiven && set.indexGiven;
+
+            if (set.stringLists.size() >= 2)
+            {
+               edit.patternsGiven = true;
+               edit.patterns = set.stringLists[1];
+               edit.matchType = set.matchTypeGiven ? set.matchType : _T("is");
+               edit.caseSensitive = set.comparatorGiven && set.comparator.Compare(_T("i;octet")) == 0;
+            }
+         }
+
+         if (result_)
+            result_->headerEdits.push_back(edit);
+
+         actions_.push_back(name + _T(":") + edit.name);
+         return;
+      }
+
       // "require" carries no run-time behaviour.
    }
 

hmailserver/source/Server/Common/Sieve/SieveEvaluator.h

@@ -66,6 +66,34 @@ namespace HM
       int loopCount = 0;
    };
 
+   // One addheader or deleteheader (RFC 5293), in script order. Order matters:
+   // "deleteheader X" then "addheader X" is a replace, the other way round is a
+   // no-op plus an add, and the RFC has both meanings.
+   struct SieveHeaderEdit
+   {
+      bool isAdd = false;
+
+      String name;
+
+      // addheader: the value to add; :last appends below existing instances
+      // instead of prepending above them.
+      String value;
+      bool addLast = false;
+
+      // deleteheader: which instances go. indexGiven selects the nth (from the
+      // end under indexFromEnd); with patterns given, only instances whose value
+      // matches one of them (with the recorded match type / comparator / case
+      // rules already resolved to a simple triple here, so the delivery side does
+      // not need the evaluator).
+      bool indexGiven = false;
+      int index = 0;
+      bool indexFromEnd = false;
+      bool patternsGiven = false;
+      std::vector<String> patterns;
+      String matchType;              // "is", "contains" or "matches"
+      bool caseSensitive = false;    // i;octet
+   };
+
    // Everything a script decided, for callers that need more than the ';'-joined
    // summary string.
    struct SieveResult
@@ -75,6 +103,7 @@ namespace HM
       bool flagsGiven = false;       // the script set the local copy's IMAP flags
       std::vector<String> flags;     // those flags, canonicalised and de-duplicated
       std::vector<String> redirects; // addresses to send a copy to
+      std::vector<SieveHeaderEdit> headerEdits; // editheader (RFC 5293), in script order
       SieveVacationDecision vacation;
    };
 

hmailserver/source/Server/Common/Sieve/SieveParser.cpp

@@ -177,6 +177,9 @@ namespace HM
          // seen-store fails OPEN - see SieveDuplicateTracker for why that is the
          // opposite of the vacation tracker's direction.
          L"duplicate",
+         // RFC 5293: addheader / deleteheader. Received and Return-Path are
+         // protected - a script cannot edit the trace of how a message got here.
+         L"editheader",
          L"comparator-i;ascii-casemap",
          L"comparator-i;octet",
          L"comparator-i;ascii-numeric"
@@ -493,7 +496,8 @@ namespace HM
       {
          L"require", L"if", L"elsif", L"else", L"stop", L"keep", L"discard",
          L"fileinto", L"redirect", L"vacation",
-         L"setflag", L"addflag", L"removeflag"
+         L"setflag", L"addflag", L"removeflag",
+         L"addheader", L"deleteheader"
       };
 
       for (const wchar_t *candidate : known)
@@ -1183,6 +1187,76 @@ namespace HM
       if (!isControl && name != _T("require") && !SplitArguments(command->arguments, set, errorMessage))
          return false;
 
+      if (name == _T("addheader") || name == _T("deleteheader"))
+      {
+         bool isAdd = name == _T("addheader");
+
+         if (!NeedExtension_(_T("editheader"), _T("'") + name + _T("'"), command->line, errorMessage))
+            return false;
+
+         if (!CheckTags_(set,
+                         isAdd ? _T("last") : _T("index last comparator is contains matches"),
+                         _T("'") + name + _T("'"), errorMessage))
+            return false;
+
+         size_t lists = set.stringLists.size();
+
+         if (isAdd)
+         {
+            if (lists != 2 || set.stringLists[0].size() != 1 || set.stringLists[1].size() != 1)
+            {
+               errorMessage.Format(_T("Line %d: 'addheader' takes a field name and a value."), command->line);
+               return false;
+            }
+         }
+         else
+         {
+            if (lists < 1 || lists > 2 || set.stringLists[0].size() != 1)
+            {
+               errorMessage.Format(_T("Line %d: 'deleteheader' takes a field name and optionally a list of value patterns."), command->line);
+               return false;
+            }
+
+            if (!ValidateIndexArguments_(set, command->line, errorMessage))
+               return false;
+
+            if (set.comparatorGiven && set.comparator.Compare(_T("i;ascii-numeric")) == 0)
+            {
+               errorMessage.Format(_T("Line %d: the \"i;ascii-numeric\" comparator cannot be used with 'deleteheader'."), command->line);
+               return false;
+            }
+         }
+
+         // The field name must be a legal header name, and the trace of how the
+         // message got here is not a script's to edit (RFC 5293 7).
+         const String &fieldName = set.stringLists[0][0];
+
+         if (fieldName.IsEmpty())
+         {
+            errorMessage.Format(_T("Line %d: the field name cannot be empty."), command->line);
+            return false;
+         }
+
+         for (int i = 0; i < fieldName.GetLength(); i++)
+         {
+            wchar_t ch = fieldName[i];
+            if (ch <= L' ' || ch >= 127 || ch == L':')
+            {
+               errorMessage.Format(_T("Line %d: '%s' is not a legal header field name."), command->line, fieldName.c_str());
+               return false;
+            }
+         }
+
+         if (fieldName.CompareNoCase(_T("Received")) == 0 || fieldName.CompareNoCase(_T("Return-Path")) == 0)
+         {
+            errorMessage.Format(_T("Line %d: the %s header records how a message travelled and cannot be edited by a script."),
+               command->line, fieldName.c_str());
+            return false;
+         }
+
+         return true;
+      }
+
       if (name == _T("keep") || name == _T("fileinto"))
       {
          if (!CheckTags_(set, name == _T("fileinto") ? _T("copy flags create") : _T("flags"), _T("'") + name + _T("'"), errorMessage))