dsn

package
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package dsn parses the bounded MIME structure required before DKIM2 delivery-status evidence can be evaluated.

It deliberately validates only the RFC 6522 report envelope and exposes byte-preserving part views. It does not interpret delivery-status fields, verify embedded DKIM2 state, or make signing or authorization decisions.

Index

Constants

View Source
const (
	// LimitNameMaxMessageBytes identifies the full report byte ceiling.
	LimitNameMaxMessageBytes = "max_message_bytes"
	// LimitNameMaxPartBytes identifies the individual MIME-part byte ceiling.
	LimitNameMaxPartBytes = "max_part_bytes"
	// LimitNameMaxBoundaryBytes identifies the MIME-boundary byte ceiling.
	LimitNameMaxBoundaryBytes = "max_boundary_bytes"
)
View Source
const MaxSigningIdentityCandidates = 64

MaxSigningIdentityCandidates bounds the ordered Draft-09 Section 16.2 candidate list, and therefore the number of local profile lookups one DSN can cause. Candidates beyond the bound are dropped after ordering, so the bound can only turn a signable report into an unsigned one, never select a non-matching signing domain.

View Source
const (

	// PropagationFixedPartsBound is the ceiling of every rendered byte of a
	// propagated report outside the embedded original: the outer header block,
	// the human part, the machine part, the part headers, and the boundaries
	// with each bounded value at its maximum. A rebuilt report is never larger
	// than the received one plus this bound.
	PropagationFixedPartsBound = 4096
)

Variables

This section is empty.

Functions

func IsErrorCode

func IsErrorCode(err error, code ErrorCode) bool

IsErrorCode reports whether err contains the requested DSN error code.

func IsEvidenceErrorCode

func IsEvidenceErrorCode(err error, code EvidenceErrorCode) bool

IsEvidenceErrorCode reports whether err contains the requested evidence code.

func IsRebuildErrorCode

func IsRebuildErrorCode(err error, code RebuildErrorCode) bool

IsRebuildErrorCode reports whether err carries the requested failure class.

func IsReceivedErrorCode

func IsReceivedErrorCode(err error, code ReceivedErrorCode) bool

IsReceivedErrorCode reports whether err carries the requested failure class.

func ProvePropagatedReport

func ProvePropagatedReport(raw, nextHop []byte, domain string) error

ProvePropagatedReport re-parses a signed propagated report and requires exactly one Message-Instance m=1 and one DKIM2-Signature i=1 under the signing domain with mf=<> and rt= equal to the next-hop recipient, the Draft-09 Section 16.3 single-signature invariant of a propagated DSN.

Types

type ContentType

type ContentType string

ContentType identifies the restricted DSN MIME media types exposed by this package.

const (
	// ContentTypeDeliveryStatus identifies the required second report part.
	ContentTypeDeliveryStatus ContentType = "message/delivery-status"
	// ContentTypeRFC822 identifies a complete embedded original message.
	ContentTypeRFC822 ContentType = "message/rfc822"
	// ContentTypeRFC822Headers identifies an embedded original-message header block.
	ContentTypeRFC822Headers ContentType = "text/rfc822-headers"
)

type EmbeddedResult

type EmbeddedResult string

EmbeddedResult is the closed outcome of the embedded-original verification stage.

const (
	// EmbeddedVerified reports a complete message/rfc822 original whose highest signature and instance verify.
	EmbeddedVerified EmbeddedResult = "verified"
	// EmbeddedVerifiedHeadersOnly reports a text/rfc822-headers original whose header evidence verifies.
	EmbeddedVerifiedHeadersOnly EmbeddedResult = "verified_headers_only"
	// EmbeddedUnverified reports permanent embedded verification failure.
	EmbeddedUnverified EmbeddedResult = "unverified"
	// EmbeddedTemporaryError reports a temporary DNS or key failure during embedded verification.
	EmbeddedTemporaryError EmbeddedResult = "temperror"
	// EmbeddedAbsent reports an embedded original that carries no DKIM2-Signature at all.
	EmbeddedAbsent EmbeddedResult = "absent"
	// EmbeddedNotEvaluated reports that the structure stage stopped the
	// evaluation before any embedded evidence could be assessed. It never
	// carries a temporary meaning.
	EmbeddedNotEvaluated EmbeddedResult = "not_evaluated"
)

func (EmbeddedResult) Known

func (r EmbeddedResult) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is a typed, content-free DSN structural parser error.

func (*Error) Actual

func (e *Error) Actual() int

Actual returns the observed bounded size when relevant.

func (*Error) Code

func (e *Error) Code() ErrorCode

Code returns the stable error code.

func (*Error) Error

func (e *Error) Error() string

Error returns a deterministic diagnostic without raw message-derived content.

func (*Error) Is

func (e *Error) Is(target error) bool

Is matches DSN errors by their stable code.

func (*Error) Limit

func (e *Error) Limit() int

Limit returns the configured resource ceiling when relevant.

func (*Error) LimitName

func (e *Error) LimitName() string

LimitName returns the bounded resource-limit name when relevant.

func (*Error) PartIndex

func (e *Error) PartIndex() int

PartIndex returns the one-based MIME part index when the error is part-specific.

type ErrorCode

type ErrorCode string

ErrorCode identifies one closed DSN structural parser failure.

const (
	// ErrorCodeInvalidOptions reports incoherent resource limits.
	ErrorCodeInvalidOptions ErrorCode = "invalid_options"
	// ErrorCodeInvalidMessage reports raw RFC 5322 input rejected before DSN parsing.
	ErrorCodeInvalidMessage ErrorCode = "invalid_message"
	// ErrorCodeMissingContentType reports an absent required Content-Type field.
	ErrorCodeMissingContentType ErrorCode = "missing_content_type"
	// ErrorCodeInvalidContentType reports malformed or duplicate MIME content-type metadata.
	ErrorCodeInvalidContentType ErrorCode = "invalid_content_type"
	// ErrorCodeInvalidReportType reports a multipart report without report-type=delivery-status.
	ErrorCodeInvalidReportType ErrorCode = "invalid_report_type"
	// ErrorCodeInvalidBoundary reports a missing, invalid, or unsafe MIME boundary.
	ErrorCodeInvalidBoundary ErrorCode = "invalid_boundary"
	// ErrorCodeMalformedMultipart reports structurally malformed multipart framing.
	ErrorCodeMalformedMultipart ErrorCode = "malformed_multipart"
	// ErrorCodeInvalidPartCount reports a report that does not contain exactly three parts.
	ErrorCodeInvalidPartCount ErrorCode = "invalid_part_count"
	// ErrorCodeInvalidPart reports a MIME part that is not a bounded raw RFC 5322 entity.
	ErrorCodeInvalidPart ErrorCode = "invalid_part"
	// ErrorCodeInvalidPartContentType reports an unexpected required DSN part media type.
	ErrorCodeInvalidPartContentType ErrorCode = "invalid_part_content_type"
	// ErrorCodeLimitExceeded reports a configured parser resource limit violation.
	ErrorCodeLimitExceeded ErrorCode = "limit_exceeded"
)

type Evidence

type Evidence struct {
	// contains filtered or unexported fields
}

Evidence stores the authenticated embedded DKIM2 target without retaining message content. recipientLinked is index-aligned with recipientDomains and recipientPaths and records which highest-signature rt= paths a structurally complete RFC 3464 recipient group names; it is set only by Evaluate.

func (Evidence) Form

func (e Evidence) Form() EvidenceForm

Form returns the retained original representation.

func (Evidence) MailFrom

func (e Evidence) MailFrom() []byte

MailFrom returns a detached exact highest-signature mf= path. It is retained only to bind the outer DSN recipient to the authenticated original sender.

func (Evidence) RecipientDomains

func (e Evidence) RecipientDomains() []string

RecipientDomains returns detached canonical DNS domains from every highest embedded rt= recipient.

func (Evidence) SigningIdentityCandidates

func (e Evidence) SigningIdentityCandidates(preferred string) []SigningIdentityCandidate

SigningIdentityCandidates returns every domain that can sign this DSN under Draft-09 Sections 7.1 item 4 and 16.2, in a deterministic preference order:

  1. candidates matching an RFC 3464-linked rt= address before candidates matching only unlinked rt= addresses;
  2. within that tier, the preferred domain (when it is itself a candidate);
  3. then more labels (the most specific domain) first;
  4. then ascending octet order of the canonical name as the final tie-break.

Candidates are the rt= domains and their parent domains: Section 7.2 step 5 removes labels only from the left of Parameter1, so exactly those names can match. Each enumerated name is admitted only through signature.RelaxedDomainMatch, the single owner of the rule. preferred is never added when it does not match; invalid evidence yields no candidates.

func (Evidence) Target

func (e Evidence) Target() verify.Target

Target returns the authenticated highest embedded DKIM2 target identifiers.

func (Evidence) Valid

func (e Evidence) Valid() bool

Valid reports whether the evidence binds one supported original representation to an authenticated target.

type EvidenceError

type EvidenceError struct {
	// contains filtered or unexported fields
}

EvidenceError is a typed, content-free DSN evidence failure.

func (*EvidenceError) Code

func (e *EvidenceError) Code() EvidenceErrorCode

Code returns the stable evidence failure code.

func (*EvidenceError) Error

func (e *EvidenceError) Error() string

Error returns a bounded diagnostic that never includes original message or envelope content.

func (*EvidenceError) Is

func (e *EvidenceError) Is(target error) bool

Is matches evidence errors by stable code.

func (*EvidenceError) Unwrap

func (e *EvidenceError) Unwrap() error

Unwrap exposes an already content-free verifier or parser cause for typed callers.

type EvidenceErrorCode

type EvidenceErrorCode string

EvidenceErrorCode identifies one content-free DSN evidence failure.

const (
	// EvidenceErrorCodeInvalidEvaluator reports an uninitialized verifier dependency.
	EvidenceErrorCodeInvalidEvaluator EvidenceErrorCode = "invalid_evaluator"
	// EvidenceErrorCodeInvalidRequest reports an unsafe DSN evidence request shape.
	EvidenceErrorCodeInvalidRequest EvidenceErrorCode = "invalid_request"
	// EvidenceErrorCodeInvalidEmbeddedMessage reports malformed embedded RFC 5322 bytes.
	EvidenceErrorCodeInvalidEmbeddedMessage EvidenceErrorCode = "invalid_embedded_message"
	// EvidenceErrorCodeInvalidEmbeddedClaims reports malformed authenticated protocol claims.
	EvidenceErrorCodeInvalidEmbeddedClaims EvidenceErrorCode = "invalid_embedded_claims"
	// EvidenceErrorCodeDeliveryStatusLinkage reports an invalid RFC 3464 recipient link.
	EvidenceErrorCodeDeliveryStatusLinkage EvidenceErrorCode = "delivery_status_linkage"
	// EvidenceErrorCodeVerificationFailed reports non-passing cryptographic original evidence.
	EvidenceErrorCodeVerificationFailed EvidenceErrorCode = "verification_failed"
	// EvidenceErrorCodeVerificationIndeterminate reports transient or otherwise non-final verification evidence.
	EvidenceErrorCodeVerificationIndeterminate EvidenceErrorCode = "verification_indeterminate"
	// EvidenceErrorCodeUnsignedEmbeddedMessage reports a well-formed embedded
	// original that carries no DKIM2-Signature header field at all. Such an
	// original is outside the Section 16 DSN model; it is never a relaxed form
	// of a failing signature, which keeps EvidenceErrorCodeVerificationFailed.
	EvidenceErrorCodeUnsignedEmbeddedMessage EvidenceErrorCode = "unsigned_embedded_message"
)

type EvidenceEvaluator

type EvidenceEvaluator struct {
	// contains filtered or unexported fields
}

EvidenceEvaluator owns the narrow Draft-09 Section 16 embedded-original verification boundary.

func NewEvidenceEvaluator

func NewEvidenceEvaluator(verifier verify.Verifier) (EvidenceEvaluator, error)

NewEvidenceEvaluator constructs a DSN evaluator from one validated DKIM2 verifier.

func (EvidenceEvaluator) Evaluate

func (e EvidenceEvaluator) Evaluate(ctx context.Context, request EvidenceRequest) (Evidence, error)

Evaluate verifies an embedded original before DSN signing authorization. Complete originals require complete body and header verification, while headers-only originals use the dedicated header-only verifier and never substitute a body. A well-formed original of either representation without any DKIM2-Signature header field is classified as EvidenceErrorCodeUnsignedEmbeddedMessage before verification; the presence of at least one such field, valid or not, always selects the strict verification path.

type EvidenceForm

type EvidenceForm string

EvidenceForm identifies the bounded representation retained for the original message.

const (
	// EvidenceFormComplete identifies a complete message/rfc822 original with body evidence.
	EvidenceFormComplete EvidenceForm = "complete"
	// EvidenceFormHeadersOnly identifies a text/rfc822-headers original without body evidence.
	EvidenceFormHeadersOnly EvidenceForm = "headers_only"
)

type EvidenceRequest

type EvidenceRequest struct {
	// Report is the parser-owned RFC 6522 DSN report.
	Report Report
	// PostfixBounceOrder admits only the bounded field ordering and folding
	// emitted by current Postfix bounce(8), after the caller has independently
	// proven the dedicated trusted-Postfix route.
	PostfixBounceOrder bool
}

EvidenceRequest carries one parsed DSN whose embedded protocol object must be authenticated without pretending signed claims were externally observed.

type LocalHopResult

type LocalHopResult string

LocalHopResult is the closed outcome of the Section 16.4 item 2 identity stage.

const (
	// LocalHopLocal reports a verified, datasource-local completion signature bound to the outer recipient.
	LocalHopLocal LocalHopResult = "local"
	// LocalHopNotLocal reports a completion signature under a domain the tenant does not control.
	LocalHopNotLocal LocalHopResult = "not_local"
	// LocalHopMismatch reports a local domain whose mf= does not bind to the outer recipient or its d=.
	LocalHopMismatch LocalHopResult = "mismatch"
	// LocalHopTemporaryError reports a temporary datasource failure during locality resolution.
	LocalHopTemporaryError LocalHopResult = "temperror"
	// LocalHopNotEvaluated reports that an earlier stage stopped or that no tenant was available.
	LocalHopNotEvaluated LocalHopResult = "not_evaluated"
)

func (LocalHopResult) Known

func (r LocalHopResult) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type Options

type Options struct {
	// MaxMessageBytes bounds the complete RFC 5322 report.
	MaxMessageBytes int
	// MaxPartBytes bounds each of the exactly three MIME parts.
	MaxPartBytes int
	// MaxBoundaryBytes bounds the MIME boundary before delimiter scanning.
	MaxBoundaryBytes int
}

Options bounds structural report parsing before any DSN interpretation occurs.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns restrictive resource limits for DSN structural parsing.

type OuterAlignmentResult

type OuterAlignmentResult string

OuterAlignmentResult is the closed outcome of the Section 16.4 item 1 alignment stage.

const (
	// OuterAlignmentAligned reports that the outer signer relaxed-matches a completion rt= domain.
	OuterAlignmentAligned OuterAlignmentResult = "aligned"
	// OuterAlignmentMisaligned reports that no completion rt= domain relaxed-matches the outer signer.
	OuterAlignmentMisaligned OuterAlignmentResult = "misaligned"
	// OuterAlignmentNotEvaluated reports that an earlier stage stopped the evaluation.
	OuterAlignmentNotEvaluated OuterAlignmentResult = "not_evaluated"
)

func (OuterAlignmentResult) Known

func (r OuterAlignmentResult) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type Part

type Part struct {
	// contains filtered or unexported fields
}

Part exposes one immutable MIME part without interpreting its content.

func (Part) BodyBytes

func (p Part) BodyBytes() []byte

BodyBytes returns a detached exact MIME-part content representation.

func (Part) ContentType

func (p Part) ContentType() ContentType

ContentType returns the validated restricted media type for the part.

func (Part) Headers

func (p Part) Headers() rawmsg.HeaderBlock

Headers returns the immutable MIME-part header block.

func (Part) RawBytes

func (p Part) RawBytes() []byte

RawBytes returns a detached exact MIME-part representation, including MIME headers.

type PropagationResult

type PropagationResult string

PropagationResult is the closed informational propagation projection.

const (
	// PropagationNotApplicable reports an embedded original without DKIM2 signatures.
	PropagationNotApplicable PropagationResult = "not_applicable"
	// PropagationEligible reports that a rebuild toward the previous hop can be attempted.
	PropagationEligible PropagationResult = "eligible"
	// PropagationTerminalOrigin reports that this system originated the message.
	PropagationTerminalOrigin PropagationResult = "terminal_origin"
	// PropagationNotFailure reports that no linked group carries Action: failed.
	PropagationNotFailure PropagationResult = "not_failure"
	// PropagationForbiddenNullPreviousSender reports a previous hop with mf=<>.
	PropagationForbiddenNullPreviousSender PropagationResult = "forbidden_null_previous_sender"
	// PropagationForbiddenIdentityMisaligned reports that the propagated
	// report's signing domain, the completion d=, does not relaxed-match the
	// rt= address of the previous hop, which becomes the highest signature of
	// the rebuilt report (Draft-09 Sections 7.1 item 4, 16.2, and 16.3).
	PropagationForbiddenIdentityMisaligned PropagationResult = "forbidden_identity_misaligned"
	// PropagationUnsupportedChain reports a custody chain this system does not
	// qualify for reconstruction: an nd= previous hop, a run member that does
	// not verify, a run whose detection exceeded the bounded authority lookup
	// limit, or a run whose custody structure is malformed. All four fail
	// closed into the same value so that the projection never distinguishes
	// a forged local signature from a merely unsupported one.
	PropagationUnsupportedChain PropagationResult = "unsupported_chain"
	// PropagationNotReconstructable reports a condition visible without a rebuild that prevents reconstruction.
	PropagationNotReconstructable PropagationResult = "not_reconstructable"
	// PropagationNotEvaluated reports that an earlier stage stopped or that no tenant was available.
	PropagationNotEvaluated PropagationResult = "not_evaluated"
)

func (PropagationResult) Known

func (r PropagationResult) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type RebuildError

type RebuildError struct {
	// contains filtered or unexported fields
}

RebuildError is a typed, content-free rebuild failure.

func (*RebuildError) Code

func (e *RebuildError) Code() RebuildErrorCode

Code returns the closed failure class.

func (*RebuildError) Error

func (e *RebuildError) Error() string

Error returns a bounded diagnostic without report, address, or identity content.

func (*RebuildError) Format

func (e *RebuildError) Format(state fmt.State, _ rune)

Format routes every formatting verb through the bounded diagnostic.

func (*RebuildError) Unwrap

func (e *RebuildError) Unwrap() error

Unwrap exposes the context or content-free protocol cause.

type RebuildErrorCode

type RebuildErrorCode string

RebuildErrorCode is the closed class of a rebuild Go error.

const (
	// RebuildErrorInvalidRequest reports an invalid evaluator, evaluation, or request value.
	RebuildErrorInvalidRequest RebuildErrorCode = "invalid_request"
	// RebuildErrorNotEligible reports an evaluation whose propagation projection is not eligible.
	RebuildErrorNotEligible RebuildErrorCode = "not_eligible"
	// RebuildErrorCanceled reports caller cancellation.
	RebuildErrorCanceled RebuildErrorCode = "canceled"
	// RebuildErrorInternal reports an internal contract violation.
	RebuildErrorInternal RebuildErrorCode = "internal"
)

func (RebuildErrorCode) Known

func (c RebuildErrorCode) Known() bool

Known reports whether the code belongs to the closed vocabulary.

type RebuildFailure

type RebuildFailure string

RebuildFailure is the closed internal cause of a not-reconstructable rebuild.

const (
	// RebuildFailureRecipeInvalid reports malformed authenticated recipe JSON in the run.
	RebuildFailureRecipeInvalid RebuildFailure = "recipe_invalid"
	// RebuildFailureApplicationInvalid reports a recipe that cannot be applied.
	RebuildFailureApplicationInvalid RebuildFailure = "application_invalid"
	// RebuildFailureSourceUnavailable reports a copy from unavailable state.
	RebuildFailureSourceUnavailable RebuildFailure = "source_unavailable"
	// RebuildFailureLimitExceeded reports a descent ceiling or a rebuilt report larger than the received one plus the fixed parts.
	RebuildFailureLimitExceeded RebuildFailure = "limit_exceeded"
	// RebuildFailureHashMismatch reports a reconstructed state that does not match its instance.
	RebuildFailureHashMismatch RebuildFailure = "hash_mismatch"
	// RebuildFailureUnsupportedHash reports an instance without a supported hash tuple.
	RebuildFailureUnsupportedHash RebuildFailure = "unsupported_hash"
	// RebuildFailurePreviousHopUnverified reports a previous hop signature that does not verify.
	RebuildFailurePreviousHopUnverified RebuildFailure = "previous_hop_unverified"
	// RebuildFailurePreviousHopTimestamp reports a previous hop t= outside the completion window.
	RebuildFailurePreviousHopTimestamp RebuildFailure = "previous_hop_timestamp"
	// RebuildFailurePreviousHopAlignment reports a failed previous hop d=/mf= match.
	RebuildFailurePreviousHopAlignment RebuildFailure = "previous_hop_alignment"
	// RebuildFailureCustodyRejected reports a broken custody link in the chain below and including the previous hop.
	RebuildFailureCustodyRejected RebuildFailure = "custody_rejected"
	// RebuildFailureNullPreviousSender reports a previous hop whose mf= is the null reverse path.
	RebuildFailureNullPreviousSender RebuildFailure = "null_previous_sender"
	// RebuildFailureAmbiguousPreviousRecipient reports a previous hop rt= with more than one path.
	RebuildFailureAmbiguousPreviousRecipient RebuildFailure = "ambiguous_previous_recipient"
	// RebuildFailureSourceRoute reports a previous hop rt= or mf= carrying an obsolete RFC 5321 source route.
	RebuildFailureSourceRoute RebuildFailure = "source_route"
	// RebuildFailureProtocolFieldsAltered reports a preserved protocol field that changed during the descent.
	RebuildFailureProtocolFieldsAltered RebuildFailure = "protocol_fields_altered"
	// RebuildFailureInternal reports an internal rendering or contract failure.
	RebuildFailureInternal RebuildFailure = "internal"
)

func (RebuildFailure) Known

func (f RebuildFailure) Known() bool

Known reports whether the failure belongs to the closed vocabulary.

type RebuildOutcome

type RebuildOutcome string

RebuildOutcome is the closed result of one rebuild attempt.

const (
	// RebuildRebuilt reports a complete Section 16.3 report ready for signing.
	RebuildRebuilt RebuildOutcome = "rebuilt"
	// RebuildNotReconstructable reports that the previous state could not be proven or rendered.
	RebuildNotReconstructable RebuildOutcome = "not_reconstructable"
	// RebuildTemporary reports a temporary key-provider failure while verifying the previous hop.
	RebuildTemporary RebuildOutcome = "temporary"
)

func (RebuildOutcome) Known

func (o RebuildOutcome) Known() bool

Known reports whether the outcome belongs to the closed vocabulary.

type RebuildRequest

type RebuildRequest struct {
	// Evaluation is the received-DSN evaluation that reached propagation = eligible.
	Evaluation ReceivedEvaluation
	// ReportingMTA is the canonical lowercase DNS name of this system.
	ReportingMTA string
	// Timestamp is the signing instant in Unix seconds, rendered as Date.
	Timestamp uint64
	// MessageIDToken is a fresh bounded alphanumeric token for the Message-ID.
	MessageIDToken []byte
}

RebuildRequest binds one eligible evaluation to the deterministic inputs of the rebuilt report.

func (RebuildRequest) Format

func (r RebuildRequest) Format(state fmt.State, _ rune)

Format routes every request formatting form through the redacted summary.

func (RebuildRequest) GoString

func (r RebuildRequest) GoString() string

GoString returns the constant secret-safe request Go representation.

func (RebuildRequest) String

func (RebuildRequest) String() string

String returns a constant secret-safe request summary.

type RebuiltReport

type RebuiltReport struct {
	// contains filtered or unexported fields
}

RebuiltReport is the immutable outcome of one rebuild. A rebuilt report exposes the unsigned report bytes, the exact next-hop recipient, the signing domain proven by the removed completion signature, and the form of the third part; every other outcome exposes only closed values.

func (RebuiltReport) Bytes

func (r RebuiltReport) Bytes() []byte

Bytes returns a detached copy of the unsigned rebuilt report or nil.

func (RebuiltReport) EightBitMIMERequired

func (r RebuiltReport) EightBitMIMERequired() bool

EightBitMIMERequired reports whether the embedded original's body carries a non-ASCII byte, which is an 8BITMIME question for the re-injection client rather than an SMTPUTF8 one.

func (RebuiltReport) Failure

func (r RebuiltReport) Failure() RebuildFailure

Failure returns the closed cause of a not-reconstructable rebuild.

func (RebuiltReport) Form

func (r RebuiltReport) Form() EvidenceForm

Form returns the representation of the rebuilt third part.

func (RebuiltReport) Format

func (r RebuiltReport) Format(state fmt.State, _ rune)

Format routes every report formatting form through the redacted summary.

func (RebuiltReport) GoString

func (r RebuiltReport) GoString() string

GoString returns the constant secret-safe report Go representation.

func (RebuiltReport) NextHopRecipient

func (r RebuiltReport) NextHopRecipient() []byte

NextHopRecipient returns a detached copy of the exact bracketed previous-hop mf= or nil.

func (RebuiltReport) Outcome

func (r RebuiltReport) Outcome() RebuildOutcome

Outcome returns the closed rebuild outcome.

func (RebuiltReport) SMTPUTF8Required

func (r RebuiltReport) SMTPUTF8Required() bool

SMTPUTF8Required reports whether any header field of the rebuilt DSN, including the header block of the embedded original, carries a non-ASCII byte in the RFC 6531/6532 sense. The next-hop path is covered by the To: field; an 8-bit body alone never sets it.

func (RebuiltReport) SigningDomain

func (r RebuiltReport) SigningDomain() string

SigningDomain returns the canonical d= of the removed completion signature or an empty string.

func (RebuiltReport) String

func (RebuiltReport) String() string

String returns a constant secret-safe report summary.

func (RebuiltReport) Valid

func (r RebuiltReport) Valid() bool

Valid reports whether the report was produced by Rebuild and is coherent.

type ReceivedError

type ReceivedError struct {
	// contains filtered or unexported fields
}

ReceivedError is a typed, content-free received-DSN evaluation failure. It carries only the closed stage and failure class; the wrapped cause is a context error or an already content-free protocol error.

func (*ReceivedError) Code

func (e *ReceivedError) Code() ReceivedErrorCode

Code returns the closed failure class.

func (*ReceivedError) Error

func (e *ReceivedError) Error() string

Error returns a bounded diagnostic without report, address, or identity content.

func (*ReceivedError) Format

func (e *ReceivedError) Format(state fmt.State, _ rune)

Format routes every formatting verb through the bounded diagnostic.

func (*ReceivedError) Is

func (e *ReceivedError) Is(target error) bool

Is matches received errors by their closed failure class.

func (*ReceivedError) Stage

func (e *ReceivedError) Stage() ReceivedStage

Stage returns the closed stage in which the failure occurred.

func (*ReceivedError) Unwrap

func (e *ReceivedError) Unwrap() error

Unwrap exposes the context or content-free protocol cause.

type ReceivedErrorCode

type ReceivedErrorCode string

ReceivedErrorCode identifies one closed received-DSN evaluation failure class.

const (
	// ReceivedErrorInvalidRequest reports an unusable evaluator, request, or outer report.
	ReceivedErrorInvalidRequest ReceivedErrorCode = "invalid_request"
	// ReceivedErrorCanceled reports caller context cancellation or deadline expiry.
	ReceivedErrorCanceled ReceivedErrorCode = "canceled"
	// ReceivedErrorInternal reports an impossible internal state.
	ReceivedErrorInternal ReceivedErrorCode = "internal"
)

func (ReceivedErrorCode) Known

func (c ReceivedErrorCode) Known() bool

Known reports whether the code belongs to the closed vocabulary.

type ReceivedEvaluation

type ReceivedEvaluation struct {
	// contains filtered or unexported fields
}

ReceivedEvaluation is the immutable outcome of one received-DSN evaluation. It exposes the closed projection plus the bounded facts a later rebuild needs; it never exposes report text, addresses, or message bytes except the syntactically validated status code, ENVID, and matching ORCPT value.

func (ReceivedEvaluation) CompletionDomain

func (e ReceivedEvaluation) CompletionDomain() string

CompletionDomain returns the canonical d= of the completion signature once it was verified and proven local, otherwise an empty string.

func (ReceivedEvaluation) CompletionInstance

func (e ReceivedEvaluation) CompletionInstance() uint64

CompletionInstance returns the m= referenced by the completion signature or zero.

func (ReceivedEvaluation) CompletionSequence

func (e ReceivedEvaluation) CompletionSequence() uint64

CompletionSequence returns the i= of the verified completion signature or zero.

func (ReceivedEvaluation) CompletionTimestamp

func (e ReceivedEvaluation) CompletionTimestamp() uint64

CompletionTimestamp returns the completion signature's t= value or zero.

func (ReceivedEvaluation) Embedded

func (e ReceivedEvaluation) Embedded() EmbeddedResult

Embedded returns the closed embedded-verification outcome, or EmbeddedNotEvaluated when the structure stage stopped the evaluation.

func (ReceivedEvaluation) Form

Form returns the embedded original representation once structure passed.

func (ReceivedEvaluation) Format

func (e ReceivedEvaluation) Format(state fmt.State, _ rune)

Format routes every evaluation formatting form through the redacted summary.

func (ReceivedEvaluation) GoString

func (e ReceivedEvaluation) GoString() string

GoString returns the constant secret-safe evaluation Go representation.

func (ReceivedEvaluation) LocalHop

func (e ReceivedEvaluation) LocalHop() LocalHopResult

LocalHop returns the closed local-hop identity outcome.

func (ReceivedEvaluation) OriginalEnvelopeID

func (e ReceivedEvaluation) OriginalEnvelopeID() ([]byte, bool)

OriginalEnvelopeID returns a detached copy of the report's Original-Envelope-Id when present.

func (ReceivedEvaluation) OriginalRecipientFor

func (e ReceivedEvaluation) OriginalRecipientFor(path []byte) ([]byte, bool)

OriginalRecipientFor returns the propagation group's verbatim Original-Recipient value only when its xtext-decoded address equals the given canonical bracketed path. The rebuild passes the previous hop's single rt= path, which is the recipient the sender-supplied ORCPT would name; the evaluation itself never interprets the value beyond linkage.

func (ReceivedEvaluation) OuterAlignment

func (e ReceivedEvaluation) OuterAlignment() OuterAlignmentResult

OuterAlignment returns the closed outer-signer alignment outcome.

func (ReceivedEvaluation) Propagation

func (e ReceivedEvaluation) Propagation() PropagationResult

Propagation returns the closed informational propagation projection.

func (ReceivedEvaluation) PropagationStatus

func (e ReceivedEvaluation) PropagationStatus() []byte

PropagationStatus returns a detached copy of the propagation group's syntactically valid Status code, or nil without a propagation group.

func (ReceivedEvaluation) RecipientLinkage

func (e ReceivedEvaluation) RecipientLinkage() RecipientLinkageResult

RecipientLinkage returns the closed recipient-linkage outcome.

func (ReceivedEvaluation) Run

Run returns the detected local hop run when the local-hop stage passed.

func (ReceivedEvaluation) String

func (ReceivedEvaluation) String() string

String returns a constant secret-safe evaluation summary.

func (ReceivedEvaluation) Structure

func (e ReceivedEvaluation) Structure() StructureResult

Structure returns the closed structure outcome.

func (ReceivedEvaluation) Valid

func (e ReceivedEvaluation) Valid() bool

Valid reports whether the evaluation was produced by a ReceivedEvaluator and is coherent.

type ReceivedEvaluator

type ReceivedEvaluator struct {
	// contains filtered or unexported fields
}

ReceivedEvaluator owns the read-only Draft-09 Section 16.4 evaluation of an inbound DKIM2-signed delivery-status notification. It never authorizes signing and never rebuilds a report.

func NewReceivedEvaluator

func NewReceivedEvaluator(verifier verify.Verifier, config ReceivedEvaluatorConfig) (ReceivedEvaluator, error)

NewReceivedEvaluator constructs a received-DSN evaluator from one validated verifier.

func (ReceivedEvaluator) Evaluate

Evaluate runs the seven Section 16.4 stages in order and stops at the first failure. Protocol outcomes are encoded in the returned evaluation; only invalid requests, cancellation, and internal contract violations return a Go error.

func (ReceivedEvaluator) Rebuild

Rebuild turns an eligible evaluation into an unsigned Draft-09 Section 16.3 report: it removes the local hop run and every unsigned field above the previous hop, descends the run to the previous hop's instance while re-proving every state, restores the pruned wire order for every header name the run's recipes did not rewrite, proves the surviving protocol fields byte-exact before any key fetch, verifies the previous hop signature over that state at the completion instant, degrades to text/rfc822-headers when body evidence was unavailable, and generates the fresh report parts. Protocol outcomes are returned in the report; only invalid requests, ineligible evaluations, cancellation, and internal contract violations return a Go error.

type ReceivedEvaluatorConfig

type ReceivedEvaluatorConfig struct {
	// Parser bounds RFC 6522 structural parsing; the zero value selects DefaultOptions.
	Parser Options
	// RunLimits bounds local-hop run detection; the zero value selects the defaults.
	RunLimits verify.LocalHopRunLimits
}

ReceivedEvaluatorConfig bounds one received-DSN evaluator.

type ReceivedRequest

type ReceivedRequest struct {
	// Raw is the complete outer RFC 5322 report.
	Raw []byte
	// OuterRecipient is the single observed bracketed outer SMTP forward path.
	OuterRecipient []byte
	// Authority resolves local authority domains for the caller's tenant; nil means no tenant.
	Authority verify.LocalAuthority
}

ReceivedRequest carries one inbound DSN whose outer message the caller has already verified as an ordinary message.

type ReceivedStage

type ReceivedStage string

ReceivedStage identifies one closed received-DSN evaluation stage.

const (
	// ReceivedStagePreflight identifies request or evaluator validation before parsing.
	ReceivedStagePreflight ReceivedStage = "preflight"
	// ReceivedStageStructure identifies RFC 6522 and RFC 3464 structure evaluation.
	ReceivedStageStructure ReceivedStage = "structure"
	// ReceivedStageEmbeddedVerification identifies embedded-original verification.
	ReceivedStageEmbeddedVerification ReceivedStage = "embedded_verification"
	// ReceivedStageLocalHop identifies local-hop identity and run detection.
	ReceivedStageLocalHop ReceivedStage = "local_hop"
	// ReceivedStageOuterAlignment identifies outer signer alignment.
	ReceivedStageOuterAlignment ReceivedStage = "outer_alignment"
	// ReceivedStageRecipientLinkage identifies RFC 3464 recipient linkage.
	ReceivedStageRecipientLinkage ReceivedStage = "recipient_linkage"
	// ReceivedStageFailureClass identifies propagation-group selection.
	ReceivedStageFailureClass ReceivedStage = "failure_class"
	// ReceivedStagePreviousHop identifies previous-hop classification.
	ReceivedStagePreviousHop ReceivedStage = "previous_hop"
)

func ReceivedStageOf

func ReceivedStageOf(err error) ReceivedStage

ReceivedStageOf returns the closed stage of a typed received error or the zero value.

func (ReceivedStage) Known

func (s ReceivedStage) Known() bool

Known reports whether the stage belongs to the closed vocabulary.

type RecipientLinkageResult

type RecipientLinkageResult string

RecipientLinkageResult is the closed outcome of the RFC 3464 recipient linkage stage.

const (
	// RecipientLinkageLinked reports at least one recipient group naming an authenticated rt= path.
	RecipientLinkageLinked RecipientLinkageResult = "linked"
	// RecipientLinkageUnlinked reports that no recipient group names an authenticated rt= path.
	RecipientLinkageUnlinked RecipientLinkageResult = "unlinked"
	// RecipientLinkageNotEvaluated reports that an earlier stage stopped the evaluation.
	RecipientLinkageNotEvaluated RecipientLinkageResult = "not_evaluated"
)

func (RecipientLinkageResult) Known

func (r RecipientLinkageResult) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type Report

type Report struct {
	// contains filtered or unexported fields
}

Report exposes the three required RFC 6522 report parts without interpreting their fields.

func Parse

func Parse(data []byte) (Report, error)

Parse parses one RFC 6522 multipart/report delivery-status envelope with restrictive defaults.

func ParseWithOptions

func ParseWithOptions(data []byte, options Options) (Report, error)

ParseWithOptions parses only the bounded DSN report structure and does not verify DSN or DKIM2 semantics.

func (Report) DeliveryStatus

func (r Report) DeliveryStatus() Part

DeliveryStatus returns the required message/delivery-status second part.

func (Report) HumanReadable

func (r Report) HumanReadable() Part

HumanReadable returns the first report part without imposing a content type on it.

func (Report) OriginalMessage

func (r Report) OriginalMessage() Part

OriginalMessage returns the required message/rfc822 or text/rfc822-headers third part.

func (Report) RawMessage

func (r Report) RawMessage() rawmsg.Message

RawMessage returns the validated byte-preserving top-level report representation.

type SigningIdentityCandidate

type SigningIdentityCandidate struct {
	// contains filtered or unexported fields
}

SigningIdentityCandidate is one ordered candidate signing domain for a locally generated DSN. Its domain relaxed-matches (Draft-09 Section 7.2, rt= address as Parameter1, d= as Parameter2) at least one rt= address of the highest DKIM2-Signature of the reported message.

func (SigningIdentityCandidate) Domain

func (c SigningIdentityCandidate) Domain() string

Domain returns the canonical candidate signing domain.

func (SigningIdentityCandidate) Linked

func (c SigningIdentityCandidate) Linked() bool

Linked reports whether the candidate matches an rt= address that an RFC 3464 Final-Recipient or Original-Recipient field of the report names.

func (SigningIdentityCandidate) Preferred

func (c SigningIdentityCandidate) Preferred() bool

Preferred reports whether the candidate is the operator-preferred domain.

type StructureResult

type StructureResult string

StructureResult is the closed outcome of the RFC 6522 and RFC 3464 structure stage.

const (
	// StructureValid reports exact three-part framing and a strict generic RFC 3464 body.
	StructureValid StructureResult = "valid"
	// StructureMalformed reports framing or delivery-status syntax outside the closed profile.
	StructureMalformed StructureResult = "malformed"
	// StructureLimitExceeded reports a configured DSN parser resource limit violation.
	StructureLimitExceeded StructureResult = "limit_exceeded"
)

func (StructureResult) Known

func (r StructureResult) Known() bool

Known reports whether the value belongs to the closed vocabulary.

Directories

Path Synopsis
Package dsntest builds deterministic DKIM2-signed messages and RFC 6522 delivery-status reports for received-DSN evaluation tests.
Package dsntest builds deterministic DKIM2-signed messages and RFC 6522 delivery-status reports for received-DSN evaluation tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL