NAME

Mail::DKIM2::HeaderPlan - every Message-Instance's header hash without undo

SYNOPSIS

use Mail::DKIM2::HeaderPlan;

my $plan = Mail::DKIM2::HeaderPlan->new($header_text,
    IgnorePrefixes => \@prefixes);
my @instances = map { Mail::DKIM2::MessageInstance->parse($_) }
                highest_first($plan->values('Message-Instance'));
$plan->plan(@instances);

for my $mi (@instances) {
    my $m = $mi->get_tag('m');
    die $plan->recipe_error($m) if $plan->recipe_error($m);
    my $hh = $plan->header_hash($m, 'sha256');
}

DESCRIPTION

The undo walk checks a chain by rebuilding each previous header from the one above it, and canonicalizing and hashing every field again at each level. A HeaderPlan splits the fields once, unfolds and canonicalizes a value only if its name is in the header hash, and works out from the header Recipes which values (as received, or Recipe literals) each instance's fields were, name by name. A name no Recipe touches costs nothing at the levels below. The hashes and the verdicts, in their wording, are those of "undo" in Mail::DKIM2::MessageInstance and h_digest; Mail::DKIM2::Verifier's StreamBody option uses a HeaderPlan with a Mail::DKIM2::BodyPlan.

METHODS

new($header, %options)

$header is the header fields as received: one string, each field with its line break, or a list of fields, each with its continuation lines and line break (as Mail::DKIM2::HeaderParser collects them). Fields are split as Email::Simple splits them: a line that begins with white space or has no colon continues the field above. IgnorePrefixes is as for Mail::DKIM2::Verifier.

fields($header)

A function: [$name, $value] for every field of $header (as new takes it), in order, the value unfolded as Email::Simple's header_raw gives it.

values($name)

The values of the fields named $name (any case), top first.

plan(@instances)

The Mail::DKIM2::MessageInstance objects of the chain, highest m= first. Computes every instance's header hashes and checks each header Recipe. Returns the plan.

header_hash($m, $alg)

The base64 header hash of instance $m by $alg; undef below a header Recipe that does not undo, or for an algorithm the instance does not use.

recipe_error($m)

Why instance $m's header Recipe does not undo, in "undo" in Mail::DKIM2::MessageInstance's words; undef if it does.

values_at($m, $name)

An arrayref of the values of the fields named $name in the header as it was when instance $m was the highest -- the header Recipes above it applied -- each as Email::Simple's header_raw gives it, bottom up; undef if a header Recipe on the way down does not undo. The Verifier reads each version's From fields from it (-07 section 11). New in 0.23.

rewrites_instances()

True if a header Recipe names Message-Instance. Undoing one changes the instances the levels below it see, which a HeaderPlan does not follow; a caller uses the undo walk for such a message.

AUTHOR

Bron Gondwana <brong@fastmailteam.com>

COPYRIGHT AND LICENSE

Copyright (c) 2025-2026 Fastmail Pty Ltd. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.