DKIM2

[juliebin]

• Give your PR a recognizable title. For example: "FE-123: Add new prop to component" or "Resolve Issue Create new-pricing-increases-costs #123: Fix bug in component"
• Your PR title will be visible in changelogs

What Changed

• What changes does this PR propose?
• Provide screenshots or screen recordings for any visual changes.

How To Test or Verify

• Describe any steps that may help reviewers verify changes.
• Anything beyond basic unit testing, such as assistive tech usage, or special interactions.

PR Checklist

Below are some checklists to follow for the correct procedure in different circumstance. The first list ("All PRs Checklist") should be followed for ALL PRs. The next 2 are additive to this list depending on what type of PR you are using.

For example: If you are submitting a content change to one of the support documents, your checklist would include the:

• "All PRs Checklist"
• AND the "Content Changes Checklist

If you are submitting a feature addition, enhancement, or bug fix, your checklist would include the:

• "All PRs Checklist"
• AND the "Development Changes Checklist"

All PRs Checklist

• Give your pull request a meaningful name.
• Use lowercase filenames.
• Apply at least one team label according to which team is the content expert (ie. team-FE or team-SAZ)
• Pull request approval from the FE team or content experts (see label applied above) that isn't the content creator.

Content Changes Checklist

• Check that your article looks correct in the preview here or in a Netlify deploy preview.
• Check the links in your article.
• Check the images in your article (if there are any)
• Check to make sure you are using markdown appropriately as outlined in examples/article.md in the root of the project directory and on the momentum doc's preface article
• Check to make sure the Copy and Tone Guidelines are followed.

Development Changes Checklist (some checks are automatic github actions and will not be listed here. ie. "all tests pass")

• The appropriate tests are created in cypress/ directory in the root of the project
• The lighthouse score is passing according to the FE Support Docs' Service Outline SLI/SLOs

---

Note

Low Risk
Documentation-only changes with no runtime or configuration behavior; main risk is inaccurate operator guidance if the draft spec or product behavior diverges from the text.

Overview
Adds a full DKIM2 documentation set for Momentum 4, targeting draft ietf-dkim-dkim2-spec-02, placed next to the existing DKIM1 articles.

The new /momentum/4/dkim2 overview explains DKIM2 vs DKIM1, the dkim2 {} config stanza, Lua-driven signing/verification via validate_data_spool_each_rcpt, key reuse, coexistence with DKIM1/ARC, and documented implementation gaps (lower-hop crypto, DSN, forwarder/recipe automation).

Child pages document msys.validate.dkim2.sign() (hooks, options, forwarder bridges, recipes), verify() (§10.4 per-recipient checks, result table, §9.4 SMTP guidance), ar_clauses() for combined Authentication-Results, and a debug reference (debug_level, reason codes, recipe-chain paniclog strings, dkim2_* context keys).

content/momentum/navigation.yml gains a “Using DKIM2” section with links to signing and verifying anchors under Configuring Momentum.

^{Reviewed by Cursor Bugbot for commit 129960a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[netlify]

✅ Deploy Preview for support-docs ready!

Name	Link
🔨 Latest commit	129960a
🔍 Latest deploy log	https://app.netlify.com/projects/support-docs/deploys/6a36afb984e43f000880c6b7
😎 Deploy Preview	https://deploy-preview-848--support-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 86efa82. Configure here.}

[juliebin]

I'll restructure the page into sub-pages.

[deepakpn]

Suggested rewrite:

  Lower-hop signatures not cryptographically verified (§9.1 / §9.2 / §10.5–10.6): Momentum runs the full cryptographic procedure — key fetch (§10.5) and EVP signature verification (§10.6) — only on the highest-i
  signature, which §9.1 makes a SHOULD. Earlier hops (i < max_i) get no key lookup and no crypto (status="chain_verified"); their integrity rests on the §8.3/§10.4 chain-of-custody check and the §9.2/§10 recipe
  reconstruction, which reverse-applies each hop's recipe to rebuild the original message and confirms the reconstructed instance-1 hashes match MI[1]'s h=. This proves end-to-end content integrity but does not
  authenticate each lower hop's signing key, so earlier-hop signer identities should not be used for Reviser reputation. The spec does not yet clearly mandate per-hop crypto (§9.1 is SHOULD; §9.3 implies it for
  reputation purposes but defers to a TBA doc, and §15 is TBA). Full per-hop verification — reverse-applying subsequent recipes to rebuild each hop's state and EVP-verifying each signature — would close this and
  is deferred to a future release.

[deepakpn]

Suggested rewrite:

- §9.1 / §11 DSN: Per §9.1, after a failed DKIM2 verification the
MTA MUST NOT generate a DSN; the spec recommends rejecting with a 5xx
during the SMTP conversation as the best alternative. This is not
automatically enforced — verify() only reports a verdict, so policy
must explicitly reject rather than bounce on verify failure. On the
generation side (§11), Momentum does not yet address a DSN to the
mf= of the highest-numbered DKIM2-Signature of the original message,
nor suppress DSN generation when that highest-numbered mf= is <>
(null sender). Inbound DSN authentication (§11.1.2, a SHOULD) is also
not implemented: the reject/propagate decision is scriptable via the
inbound hooks, but verifying the embedded returned message's
signatures — and checking signing-domain alignment against its
highest-i= rt= — has no exposed API, since verify() operates
only on the live message.

[deepakpn]

Suggested rewrite:

- Content modifier recipe composition: When an upstream-signed
message passes through a Momentum stage that modifies it — the
engagement tracker rewriting URLs, a footer filter, a list processor
changing headers — sign() automatically detects the change (its
freshly computed header/body hashes no longer match the prior
Message-Instance) and requires a recipe= describing how to reverse
the hop; without one the sign call fails. When the full diff isn't
available, the workaround is a null recipe declaring the change
irreversible: recipe='{"b":null}' for a body change,
recipe='{"h":null}' for header changes (a precise recipe when the
diff is available). This lets signing succeed and this hop's
signature verifies downstream — but earlier signatures' content can
no longer be reconstructed past this hop, so the inner chain is
broken for that field and acceptance depends on the verifier's
policy toward a broken chain. (Originated mail needs no recipe —
there's no prior instance to diff against.) Automatic change-recording
by pipeline stages is not yet built; a planned Recipe Accumulator API
would let sign() assemble the recipe without operator involvement.

[dkoerichbird]

The link is wrong; it should be: /momentum/4/using-dkim#generating-dkim-keys

[dkoerichbird]

(Lack of consistency) In the corresponding table in verify.md, the "test/simulation" is not considered a production exception.

[deepakpn]

iiuc, you're suggesting to move the second bullet out of "production exceptions", which sounds good to me.

[dkoerichbird]

Didn't get it: "the full set".

[deepakpn]

Seems like that can be removed.

[dkoerichbird]

I think this whole section ("Per-signature reason codes") should reside in the verify.md page. It is not just debugging; it is about what can be found in the validation results.

Same for "recipe_chain detail strings" below.

[dkoerichbird]

nit: "replay-from-different-sender"

[deepakpn]

I find replay-to-different-sender. and the replay-to-different-recipient in next bullet confusing. Maybe just remove those phrases, since rest of the description is clear enough?