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
- func IsErrorCode(err error, code ErrorCode) bool
- func IsEvidenceErrorCode(err error, code EvidenceErrorCode) bool
- func IsRebuildErrorCode(err error, code RebuildErrorCode) bool
- func IsReceivedErrorCode(err error, code ReceivedErrorCode) bool
- func ProvePropagatedReport(raw, nextHop []byte, domain string) error
- type ContentType
- type EmbeddedResult
- type Error
- type ErrorCode
- type Evidence
- type EvidenceError
- type EvidenceErrorCode
- type EvidenceEvaluator
- type EvidenceForm
- type EvidenceRequest
- type LocalHopResult
- type Options
- type OuterAlignmentResult
- type Part
- type PropagationResult
- type RebuildError
- type RebuildErrorCode
- type RebuildFailure
- type RebuildOutcome
- type RebuildRequest
- type RebuiltReport
- func (r RebuiltReport) Bytes() []byte
- func (r RebuiltReport) EightBitMIMERequired() bool
- func (r RebuiltReport) Failure() RebuildFailure
- func (r RebuiltReport) Form() EvidenceForm
- func (r RebuiltReport) Format(state fmt.State, _ rune)
- func (r RebuiltReport) GoString() string
- func (r RebuiltReport) NextHopRecipient() []byte
- func (r RebuiltReport) Outcome() RebuildOutcome
- func (r RebuiltReport) SMTPUTF8Required() bool
- func (r RebuiltReport) SigningDomain() string
- func (RebuiltReport) String() string
- func (r RebuiltReport) Valid() bool
- type ReceivedError
- type ReceivedErrorCode
- type ReceivedEvaluation
- func (e ReceivedEvaluation) CompletionDomain() string
- func (e ReceivedEvaluation) CompletionInstance() uint64
- func (e ReceivedEvaluation) CompletionSequence() uint64
- func (e ReceivedEvaluation) CompletionTimestamp() uint64
- func (e ReceivedEvaluation) Embedded() EmbeddedResult
- func (e ReceivedEvaluation) Form() EvidenceForm
- func (e ReceivedEvaluation) Format(state fmt.State, _ rune)
- func (e ReceivedEvaluation) GoString() string
- func (e ReceivedEvaluation) LocalHop() LocalHopResult
- func (e ReceivedEvaluation) OriginalEnvelopeID() ([]byte, bool)
- func (e ReceivedEvaluation) OriginalRecipientFor(path []byte) ([]byte, bool)
- func (e ReceivedEvaluation) OuterAlignment() OuterAlignmentResult
- func (e ReceivedEvaluation) Propagation() PropagationResult
- func (e ReceivedEvaluation) PropagationStatus() []byte
- func (e ReceivedEvaluation) RecipientLinkage() RecipientLinkageResult
- func (e ReceivedEvaluation) Run() (verify.LocalHopRun, bool)
- func (ReceivedEvaluation) String() string
- func (e ReceivedEvaluation) Structure() StructureResult
- func (e ReceivedEvaluation) Valid() bool
- type ReceivedEvaluator
- type ReceivedEvaluatorConfig
- type ReceivedRequest
- type ReceivedStage
- type RecipientLinkageResult
- type Report
- type SigningIdentityCandidate
- type StructureResult
Constants ¶
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" )
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.
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 ¶
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 ¶
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.
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 ¶
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 ¶
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:
- candidates matching an RFC 3464-linked rt= address before candidates matching only unlinked rt= addresses;
- within that tier, the preferred domain (when it is itself a candidate);
- then more labels (the most specific domain) first;
- 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.
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) 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.
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 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 ¶
func (e ReceivedEvaluation) Form() EvidenceForm
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 ¶
func (e ReceivedEvaluation) Run() (verify.LocalHopRun, bool)
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 ¶
func (e ReceivedEvaluator) Evaluate(ctx context.Context, request ReceivedRequest) (ReceivedEvaluation, error)
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 ¶
func (e ReceivedEvaluator) Rebuild(ctx context.Context, request RebuildRequest) (RebuiltReport, error)
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 ¶
Parse parses one RFC 6522 multipart/report delivery-status envelope with restrictive defaults.
func ParseWithOptions ¶
ParseWithOptions parses only the bounded DSN report structure and does not verify DSN or DKIM2 semantics.
func (Report) DeliveryStatus ¶
DeliveryStatus returns the required message/delivery-status second part.
func (Report) HumanReadable ¶
HumanReadable returns the first report part without imposing a content type on it.
func (Report) OriginalMessage ¶
OriginalMessage returns the required message/rfc822 or text/rfc822-headers third part.
func (Report) RawMessage ¶
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.