service

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: 12 Imported by: 0

Documentation

Overview

Package service coordinates bounded current-message verification and maps protocol-core facts into deterministic four-state internal results.

Service is the sole authentication boundary for policy projections. It validates the verify-owned target flag candidate against the authoritative selected target, upgrades current flags only after aggregate PASS, and seals complete pre-retention signature and DNS key metadata. Public fact-retention limits never reconstruct or narrow that policy evidence. Pre-target failures are sealed as fact-free unavailable projections; incoherent provenance fails closed. Service does not parse signature fields or raw f= values.

Index

Constants

View Source
const DraftIdentifier = "draft-ietf-dkim-dkim2-spec-09"

DraftIdentifier is the exact behavior baseline carried by service results.

Variables

This section is empty.

Functions

func SignatureSelectorCoherent

func SignatureSelectorCoherent(status SignatureStatus, reason Reason, selector string) bool

SignatureSelectorCoherent is the single rule for per-set selector presence (Draft-09 Section 14.6 step 8): a passing set carries no selector, an internal-contract fact that names no parsed set carries none, and every other non-passing set (fail, permerror including key and unknown or disabled algorithm errors, temperror) carries its bounded parsed selector.

Types

type Algorithm

type Algorithm string

Algorithm identifies a bounded signature algorithm family.

const (
	// AlgorithmRSASHA256 identifies RSA-SHA256.
	AlgorithmRSASHA256 Algorithm = "rsa-sha256"
	// AlgorithmEd25519SHA256 identifies Ed25519-SHA256.
	AlgorithmEd25519SHA256 Algorithm = "ed25519-sha256"
	// AlgorithmMLDSA44 identifies pure ML-DSA-44.
	AlgorithmMLDSA44 Algorithm = "mldsa44"
	// AlgorithmUnknown bounds unrecognized algorithm spellings.
	AlgorithmUnknown Algorithm = "unknown"
)

func (Algorithm) Known

func (a Algorithm) Known() bool

Known reports whether the algorithm belongs to the bounded service vocabulary.

type Assessment

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

Assessment is one closed inbound applicability decision with an optional verification result.

func (Assessment) Applicable

func (a Assessment) Applicable() bool

Applicable reports whether DKIM2 protocol fields required an actual verification.

func (Assessment) Valid

func (a Assessment) Valid() bool

Valid reports whether the assessment is either not applicable or owns one valid result.

func (Assessment) Verification

func (a Assessment) Verification() (Result, bool)

Verification returns the four-state result only when verification was applicable.

type CheckClass

type CheckClass string

CheckClass identifies a bounded verification concern.

const (
	// CheckMessage identifies raw RFC 5322 parsing.
	CheckMessage CheckClass = "message"
	// CheckProtocol identifies DKIM2 structural processing.
	CheckProtocol CheckClass = "protocol"
	// CheckBodyHash identifies current body hash verification.
	CheckBodyHash CheckClass = "body_hash"
	// CheckHeaderHash identifies current header hash verification.
	CheckHeaderHash CheckClass = "header_hash"
	// CheckSignature identifies cryptographic signature verification.
	CheckSignature CheckClass = "signature"
	// CheckKey identifies public-key validity and availability.
	CheckKey CheckClass = "key"
	// CheckTimestamp identifies timestamp policy evaluation.
	CheckTimestamp CheckClass = "timestamp"
	// CheckEnvelope identifies current SMTP envelope matching.
	CheckEnvelope CheckClass = "envelope"
	// CheckDomainAlignment identifies signing-domain alignment.
	CheckDomainAlignment CheckClass = "domain_alignment"
	// CheckNextDomain identifies structural next-domain processing.
	CheckNextDomain CheckClass = "next_domain"
	// CheckProvider identifies injected key-provider behavior.
	CheckProvider CheckClass = "provider"
	// CheckInternalContract identifies inconsistent internal facts.
	CheckInternalContract CheckClass = "internal_contract"
)

func (CheckClass) Known

func (c CheckClass) Known() bool

Known reports whether the check class belongs to the closed service vocabulary.

type CheckFact

type CheckFact struct {
	Class  CheckClass
	Reason Reason
}

CheckFact records one bounded check and reason.

type Config

type Config struct {
	Limits          Limits
	AlgorithmPolicy verify.AlgorithmPolicy
	Clock           verify.Clock
}

Config contains immutable verifier policies and limits.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns restrictive current-verification defaults.

type Custody

type Custody string

Custody identifies bounded structural next-domain coverage.

const (
	// CustodyNotEvaluated reports that earlier failure prevented reliable nd= detection.
	CustodyNotEvaluated Custody = "not_evaluated"
	// CustodyNotPresent reports successful extraction found no nd= link.
	CustodyNotPresent Custody = "not_present"
	// CustodyNDLinksEvaluated reports one or more intermediate links were evaluated.
	CustodyNDLinksEvaluated Custody = "nd_links_evaluated"
	// CustodyTerminalNDRequiresOOB reports terminal nd= requires unavailable OOB trust.
	CustodyTerminalNDRequiresOOB Custody = "terminal_nd_requires_oob"
)

func (Custody) Known

func (c Custody) Known() bool

Known reports whether custody belongs to the closed service vocabulary.

type Error

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

Error is a cause-free bounded service API error.

func (*Error) Code

func (e *Error) Code() ErrorCode

Code returns the stable service error code.

func (*Error) Error

func (e *Error) Error() string

Error returns a bounded non-sensitive diagnostic.

func (*Error) Is

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

Is matches service errors by stable code.

type ErrorCode

type ErrorCode string

ErrorCode identifies bounded service API misuse.

const (
	// ErrorInvalidConfig reports an unsafe coordinator configuration.
	ErrorInvalidConfig ErrorCode = "invalid_config"
	// ErrorInvalidRequest reports internal caller misuse.
	ErrorInvalidRequest ErrorCode = "invalid_request"
)

func (ErrorCode) Known

func (c ErrorCode) Known() bool

Known reports whether the code belongs to the closed service vocabulary.

type HistoricalState

type HistoricalState string

HistoricalState identifies one deliberately unevaluated historical dimension.

const (
	// HistoricalNotEvaluated reports that historical reconstruction or crypto did not run.
	HistoricalNotEvaluated HistoricalState = "not_evaluated"
	// HistoricalComplete reports authenticated coverage through the origin.
	HistoricalComplete HistoricalState = "complete"
	// HistoricalPartial reports authenticated coverage with an explicit
	// unavailable body. Draft-09 Section 13 makes such a history FAIL
	// body_history_unavailable, so verification no longer produces it.
	HistoricalPartial HistoricalState = "partial"
)

func (HistoricalState) Known

func (s HistoricalState) Known() bool

Known reports whether historical state belongs to the closed service vocabulary.

type Limits

type Limits struct {
	MaxRawMessageBytes  int
	MaxRecipients       int
	MaxInstanceHashSets int
	MaxSignatureSets    int
	MaxCheckFacts       int
	MaxSignatureFacts   int
}

Limits bounds service input, extraction, and retained facts.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits returns the closed service maxima.

func (Limits) Validate

func (l Limits) Validate() error

Validate rejects zero, negative, or widening service limits.

type Reason

type Reason string

Reason identifies a bounded verification outcome reason.

const (
	// ReasonNone reports no failure.
	ReasonNone Reason = "none"
	// ReasonInvalidRequest reports request API misuse.
	ReasonInvalidRequest Reason = "invalid_request"
	// ReasonLimitExceeded reports a configured resource limit.
	ReasonLimitExceeded Reason = "limit_exceeded"
	// ReasonMalformedMessage reports malformed RFC 5322 bytes.
	ReasonMalformedMessage Reason = "malformed_message"
	// ReasonMalformedProtocol reports malformed DKIM2 state.
	ReasonMalformedProtocol Reason = "malformed_protocol"
	// ReasonDuplicateHashAlgorithm reports any repeated h= algorithm name.
	ReasonDuplicateHashAlgorithm Reason = "duplicate_hash_algorithm"
	// ReasonInvalidRecipeJSON reports authenticated recipe text that is not
	// valid JSON or not a JSON object.
	ReasonInvalidRecipeJSON Reason = "invalid_recipe_json"
	// ReasonInvalidRecipe reports valid authenticated recipe JSON whose
	// schema, steps, or application are invalid (Draft-09 Section 14.2).
	ReasonInvalidRecipe Reason = "invalid_recipe"
	// ReasonFromNotAuthentic reports a From header field state that is not
	// Authentic for its responsible signature (Draft-09 Section 14.8).
	ReasonFromNotAuthentic Reason = "from_not_authentic"
	// ReasonFromSubdomainForbidden reports a From state that is Authentic
	// only through the upward match while the From domain's Domain Policy
	// Record carries the strict flag (Draft-09 Sections 3.8 and 14.8, FAIL).
	ReasonFromSubdomainForbidden Reason = "from_subdomain_forbidden"
	// ReasonDomainPolicyTemporary reports a Domain Policy Record that could
	// not be retrieved because of a temporary DNS failure (Section 3.8,
	// TEMPERROR).
	ReasonDomainPolicyTemporary Reason = "domain_policy_temporary"
	// ReasonDomainPolicyAmbiguous reports more than one Domain Policy Record
	// beginning with v=DKIM1 (Section 3.8, PERMERROR).
	ReasonDomainPolicyAmbiguous Reason = "domain_policy_ambiguous"
	// ReasonDomainPolicyInvalid reports a Domain Policy Record that begins
	// with v=DKIM1 but is not a valid tag-list, or a permanent lookup failure
	// (local interpretation D1, PERMERROR).
	ReasonDomainPolicyInvalid Reason = "domain_policy_invalid"
	// ReasonDuplicateSelector reports a repeated selector in one signature field.
	ReasonDuplicateSelector Reason = "duplicate_selector"
	// ReasonMissingProtocol reports absent required DKIM2 state.
	ReasonMissingProtocol Reason = "missing_protocol"
	// ReasonSequenceInvalid reports invalid signature or instance numbering.
	ReasonSequenceInvalid Reason = "sequence_invalid"
	// ReasonUnsupportedAlgorithm reports no checkable required algorithm.
	ReasonUnsupportedAlgorithm Reason = "unsupported_algorithm"
	// ReasonHashMismatch reports a supported digest mismatch.
	ReasonHashMismatch Reason = "hash_mismatch"
	// ReasonSignatureMismatch reports a supported signature mismatch.
	ReasonSignatureMismatch Reason = "signature_mismatch"
	// ReasonMissingKey reports absent public-key material.
	ReasonMissingKey Reason = "missing_key"
	// ReasonInvalidKey reports invalid public-key material.
	ReasonInvalidKey Reason = "invalid_key"
	// ReasonAmbiguousKey reports ambiguous public-key material.
	ReasonAmbiguousKey Reason = "ambiguous_key"
	// ReasonRevokedKey reports an explicitly revoked DNS public key.
	ReasonRevokedKey Reason = "revoked_key"
	// ReasonUnsupportedKeyType reports an unsupported DNS key type.
	ReasonUnsupportedKeyType Reason = "unsupported_key_type"
	// ReasonKeyAlgorithmMismatch reports disagreement between requested algorithm and DNS key type.
	ReasonKeyAlgorithmMismatch Reason = "key_algorithm_mismatch"
	// ReasonProviderTemporary reports typed retryable provider failure.
	ReasonProviderTemporary Reason = "provider_temporary"
	// ReasonProviderPermanent reports typed unrecoverable provider failure.
	ReasonProviderPermanent Reason = "provider_permanent"
	// ReasonProviderContract reports inconsistent provider behavior.
	ReasonProviderContract Reason = "provider_contract"
	// ReasonTimestampInvalid reports rejected timestamp state.
	ReasonTimestampInvalid Reason = "timestamp_invalid"
	// ReasonEnvelopeMismatch reports current SMTP envelope disagreement.
	ReasonEnvelopeMismatch Reason = "envelope_mismatch"
	// ReasonDomainAlignmentMismatch reports signing-domain misalignment.
	ReasonDomainAlignmentMismatch Reason = "domain_alignment_mismatch"
	// ReasonNextDomainMismatch reports structural next-domain disagreement.
	ReasonNextDomainMismatch Reason = "next_domain_mismatch"
	// ReasonCustodyMismatch reports a Chain of Custody adjacency failure: an
	// mf= or d= that does not match the previous signature's rt= (Draft-09
	// Sections 7.1 and 14.4).
	ReasonCustodyMismatch Reason = "custody_mismatch"
	// ReasonOutOfBandRequired reports terminal nd= requiring OOB trust.
	ReasonOutOfBandRequired Reason = "out_of_band_required"
	// ReasonBodyHistoryUnavailable reports a history containing a null body
	// Recipe, so the message is not Fully Verified (Draft-09 Section 13).
	ReasonBodyHistoryUnavailable Reason = "body_history_unavailable"
	// ReasonInternalContract reports inconsistent internal facts.
	ReasonInternalContract Reason = "internal_contract"
)

func (Reason) Known

func (r Reason) Known() bool

Known reports whether the reason belongs to the closed service vocabulary.

type ReplayProjection

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

ReplayProjection carries sealed replay facts across the trusted root boundary.

func (ReplayProjection) Draft

func (p ReplayProjection) Draft() string

Draft returns the exact bounded behavior baseline.

func (ReplayProjection) Exploded

func (p ReplayProjection) Exploded() bool

Exploded returns the authenticated complete-chain OR fact.

func (ReplayProjection) Format

func (ReplayProjection) Format(state fmt.State, _ rune)

Format prevents every formatting verb from exposing authenticated digest bytes.

func (ReplayProjection) GoString

func (ReplayProjection) GoString() string

GoString returns a constant representation without authenticated digest bytes.

func (ReplayProjection) OriginReplayDigest

func (p ReplayProjection) OriginReplayDigest() ([32]byte, bool)

OriginReplayDigest returns the message-wide origin digest by value.

func (ReplayProjection) ReplayEligible

func (p ReplayProjection) ReplayEligible() bool

ReplayEligible reports whether local replay policy applies to the message.

func (ReplayProjection) String

func (ReplayProjection) String() string

String returns a constant representation without authenticated digest bytes.

func (ReplayProjection) Valid

func (p ReplayProjection) Valid() bool

Valid reports whether the projection contains complete baseline facts.

type Request

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

Request owns raw RFC 5322 and current SMTP envelope bytes.

func NewRequest

func NewRequest(rawMessage, reversePath []byte, forwardPaths [][]byte) Request

NewRequest constructs an immutable internal service request.

func (Request) ForwardPaths

func (r Request) ForwardPaths() [][]byte

ForwardPaths returns independent forward-path copies.

func (Request) RawMessage

func (r Request) RawMessage() []byte

RawMessage returns an independent raw-message copy.

func (Request) ReversePath

func (r Request) ReversePath() []byte

ReversePath returns an independent reverse-path copy.

type Result

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

Result is an immutable internal current-verification outcome.

func (Result) Checks

func (r Result) Checks() []CheckFact

Checks returns immutable bounded check facts.

func (Result) Custody

func (r Result) Custody() Custody

Custody returns structural next-domain coverage.

func (Result) Draft

func (r Result) Draft() string

Draft returns the exact active behavior baseline.

func (Result) Format

func (Result) Format(state fmt.State, _ rune)

Format prevents formatting from traversing private service facts.

func (Result) GoString

func (Result) GoString() string

GoString returns a constant representation without private service facts.

func (Result) HistoricalContent

func (r Result) HistoricalContent() HistoricalState

HistoricalContent returns historical content coverage.

func (Result) HistoricalSignatures

func (r Result) HistoricalSignatures() HistoricalState

HistoricalSignatures returns historical cryptographic coverage.

func (Result) LocallyDisabledAlgorithm

func (r Result) LocallyDisabledAlgorithm() bool

LocallyDisabledAlgorithm reports whether the unsupported_algorithm outcome was decided by a locally disabled algorithm.

func (Result) PolicyProjection

func (r Result) PolicyProjection() policy.Projection

PolicyProjection returns an independent internal facade-transfer clone.

func (Result) PrimaryReason

func (r Result) PrimaryReason() Reason

PrimaryReason returns the highest-precedence bounded reason.

func (Result) ReplayProjection

func (r Result) ReplayProjection() (ReplayProjection, bool)

ReplayProjection returns one independent sealed replay projection when present.

func (Result) Scope

func (r Result) Scope() Scope

Scope returns the authenticated verification scope.

func (Result) SignatureSets

func (r Result) SignatureSets() []SignatureSetFact

SignatureSets returns immutable bounded signature-set facts.

func (Result) State

func (r Result) State() State

State returns one of the four service states.

func (Result) String

func (Result) String() string

String returns a constant representation without private service facts.

func (Result) Target

func (r Result) Target() Target

Target returns bounded target identifiers.

func (Result) VerifierProjection

func (r Result) VerifierProjection() (VerifierProjection, bool)

VerifierProjection returns one independent sealed projection when present.

type Scope

type Scope string

Scope identifies the verified message-state boundary.

const (
	// ScopeCurrent limits verification to the highest current target.
	ScopeCurrent Scope = "current"
	// ScopeChain reports authenticated verification through every inherited revision.
	ScopeChain Scope = "chain"
)

func (Scope) Known

func (s Scope) Known() bool

Known reports whether scope belongs to the closed service vocabulary.

type SignatureSetFact

type SignatureSetFact struct {
	Algorithm Algorithm
	Status    SignatureStatus
	Reason    Reason
	Selector  string
}

SignatureSetFact records one bounded signature-set outcome.

type SignatureStatus

type SignatureStatus string

SignatureStatus identifies one bounded signature-set outcome.

const (
	// SignaturePASS reports one supported signature pass.
	SignaturePASS SignatureStatus = "pass"
	// SignatureFAIL reports one supported signature mismatch.
	SignatureFAIL SignatureStatus = "fail"
	// SignaturePERMERROR reports permanent set-level failure.
	SignaturePERMERROR SignatureStatus = "permerror"
	// SignatureTEMPERROR reports typed temporary provider failure.
	SignatureTEMPERROR SignatureStatus = "temperror"
)

func (SignatureStatus) Known

func (s SignatureStatus) Known() bool

Known reports whether signature status belongs to the closed service vocabulary.

type State

type State string

State identifies one of the four current-verification outcomes.

const (
	// StatePASS reports complete success for the declared authenticated scope.
	StatePASS State = "PASS"
	// StateFAIL reports completed verification of a message that is not a
	// Fully Verified DKIM2 Message (Draft-09 Section 14.1).
	StateFAIL State = "FAIL"
	// StatePERMERROR reports permanent malformed, missing, or ambiguous state.
	StatePERMERROR State = "PERMERROR"
	// StateTEMPERROR reports a typed temporary provider failure.
	StateTEMPERROR State = "TEMPERROR"
)

func StateForReason

func StateForReason(reason Reason) State

StateForReason returns the Draft-09 Section 14.1 state that a result with this primary reason reports. The policy package owns the classification; an unknown or request-only reason is PERMERROR, which fails closed.

func (State) Known

func (s State) Known() bool

Known reports whether state belongs to the closed four-state vocabulary.

type Target

type Target struct{ Sequence, Instance uint64 }

Target identifies the current signature and instance numbers.

type Verifier

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

Verifier owns validated current-verification coordination dependencies.

func NewVerifier

func NewVerifier(provider verify.KeyProvider, fromAuthorization verify.FromAuthorization, config Config) (Verifier, error)

NewVerifier constructs a service coordinator with immutable validated policy. fromAuthorization is the explicit Draft-09 Section 11.1 choice; a zero value fails construction closed.

func (Verifier) Assess

func (v Verifier) Assess(ctx context.Context, request Request) (Assessment, error)

Assess classifies complete protocol absence before starting DKIM2 verification.

func (Verifier) Core

func (v Verifier) Core() verify.Verifier

Core returns the validated protocol-core verifier so that facades built on the same provider, limits, clock, and policy can reuse it for evaluations the coordinator does not own, such as received-DSN evaluation.

func (Verifier) Verify

func (v Verifier) Verify(ctx context.Context, request Request) (Result, error)

Verify parses raw input, delegates protocol verification, and returns one disjoint outcome.

type VerifierHopFact

type VerifierHopFact struct {
	SignerDomain       string
	Algorithms         []string
	CustodyTransition  string
	RecipeMode         string
	HistoryHeaderState string
	HistoryBodyState   string
	BodyAvailability   string
	Recipe             VerifierRecipeDescriptor
	Binding            [32]byte
	Sequence           uint64
	MessageInstance    uint64
	Feedback           bool
	FeedHere           bool
	Exploded           bool
}

VerifierHopFact stores one cloned authenticated chain record.

type VerifierProjection

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

VerifierProjection carries cloned sealed verifier evidence across the facade boundary.

func (VerifierProjection) Binding

func (p VerifierProjection) Binding() [32]byte

Binding returns the verifier-owned complete projection binding.

func (VerifierProjection) Draft

func (p VerifierProjection) Draft() string

Draft returns the exact verifier baseline.

func (VerifierProjection) Format

func (VerifierProjection) Format(state fmt.State, _ rune)

Format prevents formatting verbs from exposing message-derived facts.

func (VerifierProjection) GoString

func (VerifierProjection) GoString() string

GoString returns a constant representation without message-derived facts.

func (VerifierProjection) Hops

Hops returns detached ordered chain facts.

func (VerifierProjection) Schema

func (p VerifierProjection) Schema() string

Schema returns the exact projection identity.

func (VerifierProjection) String

func (VerifierProjection) String() string

String returns a constant representation without message-derived facts.

func (VerifierProjection) Valid

func (p VerifierProjection) Valid() bool

Valid reports whether the projection was mapped from one sealed verifier-owned source.

type VerifierRecipeDescriptor

type VerifierRecipeDescriptor struct {
	AffectedHeaders []string
	ChangeClasses   []string
	Digest          [32]byte
	BodyMode        string
}

VerifierRecipeDescriptor stores one cloned privacy-minimized Recipe descriptor.

Jump to

Keyboard shortcuts

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