dkim2

package module
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: 34 Imported by: 0

README

DKIM2 Reference Implementation

This repository contains an actively developed Go reference implementation of DKIM2 based on draft-ietf-dkim-dkim2-spec-09 with the DNS companion draft-ietf-dkim-dkim2-dns-02. The migration from Draft-08 is recorded in docs/specs/draft-09-migration-disposition.md; the operator upgrade steps are in docs/operator/draft-09-migration.md. The baseline is not an external conformance claim until the real Exim matrix and external interoperability peers are requalified against Draft-09.

The first design goal is precision: the core implementation must work from a controlled RFC 5322 message representation, preserve wire-significant details, and keep adapter behavior separate from the protocol engine.

New to DKIM2? Start Here

The administrator guides explain DKIM2 with examples, diagrams, and step-by-step configurations for people who run mail servers, not protocol drafts:

Repository Status

github.com/croessner/dkim2 is the canonical development, issue, release, and Go module repository. github.com/go-dkim2/dkim2 is a public read-only mirror for project discovery; it is not an alternative Go module path. Contributions, issues, and security reports belong in the canonical repository.

The implementation tracks active Internet-Drafts and is therefore experimental. Published v0.x releases provide reproducible interoperability and deployment evidence, but do not claim final-RFC stability.

Architecture

flowchart LR
    subgraph mta["Mail transfer agents"]
        postfix["Postfix"]
        exim["Exim"]
    end

    subgraph adapters["MTA adapters"]
        milter["dkim2-milter\nMilter-v6 Unix-socket adapter"]
        eximAdapter["dkim2-exim\nlocal_scan and transport-filter adapter"]
        propagator["dkim2-dsn-propagator\nLMTP intake and SMTP re-injection adapter"]
    end

    client["dkim2ctl\nOpenAPI client and conformance runner"]
    daemon["dkim2d\nlocal HTTP/JSON daemon"]
    library["github.com/croessner/dkim2\nstandalone DKIM2 library"]

    postfix -->|"Milter-v6 over Unix socket"| milter
    exim -->|"local_scan and transport_filter"| eximAdapter
    postfix -->|"LMTP over Unix socket"| propagator
    propagator -->|"null-sender SMTP re-injection"| postfix
    milter -->|"generated OpenAPI client\nloopback HTTP with route capability"| daemon
    eximAdapter -->|"generated OpenAPI client\nloopback HTTP with route capability"| daemon
    propagator -->|"generated OpenAPI client\nloopback HTTP with propagation capability"| daemon
    client -->|"generated OpenAPI client\nsmoke and fixture requests"| daemon
    daemon -->|"domain requests and action plans"| library

The arrows show the runtime request flow. dkim2-milter and dkim2-exim are transport adapters: they collect MTA-specific message and envelope evidence, call dkim2d, validate its response, and apply only the admitted action plan. dkim2-dsn-propagator is the MTA-neutral delivery-status propagation adapter: it receives one delivery-status notification for a forwarded message over LMTP, asks dkim2d to evaluate, rebuild, and sign the notification the previous hop must receive, re-injects that notification through a trusted Milter-free submission listener, commits the reserved propagation coordinate, and only then acknowledges the LMTP transaction. dkim2ctl uses the same local OpenAPI boundary for smoke and conformance workflows. dkim2d is the service layer around the standalone library, which owns DKIM2 protocol semantics.

Current contents:

  • docs/guide/: example-driven administrator guides for DKIM2 concepts, tags, dkim2d, keys and DNS, Postfix, and Exim.
  • docs/man/: manual pages for dkim2d(8), dkim2-milter(8), dkim2-dsn-propagator(8), dkim2-exim(8), and dkim2ctl(1), rendered from docs/man/src/ and the real command help by make man.
  • docs/ARCHITECTURE.md: current architecture, ownership boundaries, and implementation plan.
  • AGENTS.md and POLICY.md: repository development rules and engineering policy.
  • Makefile and .golangci.yml: repository-wide local guardrails.
  • docs/ci.md: GitHub Actions lanes, privilege boundaries, and release gates.
  • go.work: local development workspace.
  • Root library module: the standalone DKIM2 library at github.com/croessner/dkim2 (repository root go.mod, root package files, and the admincontract/, authresults/, headerfold/, internal/, and provider/ packages). Consumers fetch it directly with go get github.com/croessner/dkim2@latest and import github.com/croessner/dkim2; no replace directive to a local checkout is needed.
  • cmd/dkim2d: standalone HTTP/JSON daemon module.
  • cmd/dkim2-milter: standalone Milter adapter module.
  • cmd/dkim2-exim: source-linked Exim local_scan() and transport-filter adapter module.
  • cmd/dkim2ctl: standalone OpenAPI-backed client and test-client module.
  • cmd/dkim2-dsn-propagator: standalone MTA-neutral delivery-status propagation adapter module with LMTP intake and null-sender SMTP re-injection.
  • internal/*: implemented raw-message, parser, canonicalization, verification, policy, recipe, signing, revision, route-authority, restricted-release, and datasource protocol foundations.
  • internal/datasource: storage-neutral exact profile and administrative policy contracts with immutable in-memory and confined flat-file providers.
  • internal/datasource/signingprofile: the sole bridge from validated datasource results and opaque key-handle bindings to signing profiles.
  • docs/datasource-ldap-sql-design.md: storage-neutral LDAP, PostgreSQL, MySQL, and MariaDB mapping, consistency, resource, and privacy contract.
  • docs/operator/datasource-backends.md: canonical flat-file, LDAP, PostgreSQL, MySQL, and MariaDB installation, configuration, lifecycle, monitoring, backup, and troubleshooting guide.
  • docs/operator/ldap-schema-reference.md: operator-facing LDAP tree, object-class, attribute, ACL, publication, and legacy-isolation reference.
  • docs/operator/datasource-key-rotation.md: DNS overlap, higher-generation activation, retirement, and rollback runbook.
  • docs/operator/opendkim-migration.md: protected dry-run, apply, publication, and higher-generation rollback workflow.
  • docs/operator/draft-09-migration.md: Draft-09 upgrade, the NONE state, Domain Policy Records and f=strict, REST and signal changes, the replay restart, the consumers that move together, and rollback.
  • docs/operator/draft-08-migration.md: historical Draft-08/DNS-02 upgrade, configuration, REST and signal changes, mail-flow consequences, replay-store transition, the consumers that move together, and rollback.
  • docs/operator/draft-07-migration.md: historical Draft-07/DNS-01 upgrade, replay-store transition, removed configuration, mail-flow changes, and known limitations.
  • docs/replay-store-redis.md: production Redis/Valkey replay-store topologies, ACLs, eviction, persistence, loss window, retries, health, TLS, rotation, integration, and dependency guidance.
  • docs/operator/replay-redis-migration.md: moving from the removed valkey replay backend to redis (v0.2.0 breaking configuration change).
  • docs/conformance.md: public evidence classes, tested capability boundaries, adapter limitations, reproducible report commands, and the separate real Exim qualification boundary.
  • docs/security-testing.md: closed fuzz/resource inventories, abuse-profile commands, deterministic evidence, privacy limits, and vulnerability policy.
  • docs/reference/README.md: public API, compatibility, issue, external evidence, and known-limitation navigation for the preview candidate.
  • docs/operator/postfix-compose.md: hardened no-host-exposure-by-default Postfix/Milter deployment, lifecycle, backup, and rollback guide.
  • docs/operator/deployment-walkthrough.md: vendor-neutral conceptual map of a DKIM2 deployment with signal-flow diagrams for verification, signing, transit revision, bounce signing, and delivery-status propagation.
  • docs/operator/container-supply-chain.md: reproducible product images, multi-architecture layouts, SBOM, provenance, and vulnerability policy.
  • docs/specs/openapi: authoritative source-of-truth OpenAPI contract.
  • testdata/vectors: draft-versioned verification, DNS, custody, crypto, signing, revision, and insertion vectors.
  • internal/*/testdata: package-owned canonicalization, recipe application and generation, parser, fuzz, and regression fixtures.

Operator Navigation

First-time installers start with the administrator guides; the manual pages give a per-command reference (man ./docs/man/dkim2d.8). Experienced operators continue with the Postfix administrator guide for the installation order, route decisions, parameter rationale and acceptance matrix, and the deployment walkthrough for illustrated mail flows. Continue with docs/operator/postfix-compose.md for the implemented hardened Postfix deployment, trust topology, protected state, configuration, validation, lifecycle, backup, restore, and troubleshooting. Follow docs/operator/container-supply-chain.md for image construction, supported platforms, immutable digest selection, SBOM, provenance, vulnerability, reproducibility, and publication evidence. The offline native-domain workflow is documented in docs/operator/native-domain-onboarding.md, with parser-checked starting documents in docs/operator/examples/dkim2d-domain-admin-ldap.yaml and docs/operator/examples/dkim2d-domain-intent.yaml. The component references are cmd/dkim2d/README.md, cmd/dkim2-milter/README.md, cmd/dkim2ctl/README.md, and cmd/dkim2-dsn-propagator/README.md; all HTTP request and response shapes remain authoritative only in docs/specs/openapi/dkim2d.yaml. The preview's public API, compatibility, issue, and limitation entry point is docs/reference/README.md.

The source-linked Exim adapter, packaging validators, operations guide, and five-row qualification runner are implemented. Its current capability is unqualified_draft09: the historical Draft-04 matrix passed all five supported rows with 43 cases per row, but that candidate-bound evidence is not relabeled or imported for Draft-09. Portable and full Draft-09 conformance omit Exim execution and reject an evidence root until a fresh, separately authorized five-row Draft-09 run is bound to unchanged candidate bytes. No prebuilt universal Exim binary or container image is claimed. LDAP, PostgreSQL, MySQL, and MariaDB datasource providers, deployable schema artifacts, and the offline legacy OpenDKIM migration are implemented. They require operator-supplied verified-TLS services and distinct least-authority principals. Every network runtime accepts one complete committed native v2 or v3 generation. The offline dkim2d datasource domain CLI implements native onboarding across all four network backends. Tagged releases and their associated evidence define release claims; an arbitrary worktree or mirror checkout does not.

Current Behavior

The public library signs origin messages, hash-unchanged forwarding copies, recipe-backed revisions, and authorized next-domain transitions. Signing uses exact outgoing SMTP envelope evidence, authority-issued copy tickets, opaque private-key handles, deterministic Draft-09 fields, final message reparsing, custody checks, and cryptographic self-verification. Out-of-band outputs remain closed until their exact route-bound release.

Verification implements the Draft-09 algorithms rsa-sha256, ed25519-sha256, and pure ML-DSA-44 (mldsa44, DNS k=mldsa44), and evaluates Message-Instance h= and DKIM2-Signature s= values as hash-all/sig-all (,) and hash-any/sig-any (|) groups. PASS means a Fully Verified DKIM2 Message; FAIL means verification completed and the message is not Fully Verified. A signing profile holds up to three credentials and signs as rsa,ed25519 | mldsa44, so verifiers without ML-DSA still pass through the classical group. RSA signing keys need at least 2048 bits. Delivery-status notifications are signed only under a local domain that relaxed-matches an rt= recipient of the reported message (Draft-09 Section 16.2), otherwise they leave unsigned with an explicit reason.

Datasource selection is exact and fail closed. Providers return immutable same-generation profiles and policies with opaque private-key handle IDs; they never return private keys or signing capabilities. The memory provider is the static reference implementation. The flat-file provider accepts a strict, bounded dkim2-datasource-v1 JSON snapshot through an owned confined directory descriptor and publishes reloads atomically. Replay detection now has a storage-neutral library contract, bounded memory and disabled providers, and a daemon-owned Redis-compatible provider (Redis 7.0+ or Valkey 7.2+, standalone, Sentinel, or cluster) using privacy-preserving keys and nonce-bearing SET NX GET PX writes that stay correct under client retries. The daemon now owns strict typed configuration, protected-generation loading, the generated process, sign, and revise OpenAPI boundary, distinct local route-capability authentication, replay and signing-store wiring, readiness, and bounded Fx lifecycle. LDAP loads an immutable committed native v2 or v3 generation through verified TLS. PostgreSQL, MySQL, and MariaDB also load immutable committed native v2 or v3 generations through verified TLS. Every network provider builds a validated in-memory signer from the same generation and uses no local private manifest.

Inbound delivery-status notifications are evaluated read-only inside POST /v1/process and projected as the closed delivery_status fact. "Local" is datasource authority over a signing domain, never an address in mf=, and no received-DSN fact can authorize a signing operation. Draft-09 Section 16.3 propagation is a separate replay-gated route, POST /v1/dsn/propagate with POST /v1/dsn/propagate/commit, whose signing authority is the removed completion signature's domain and whose recipient is the cryptographically verified previous hop's mf=. Forwarding domains therefore need an active delivery_status signing profile.

dkim2ctl provides a generated-client-backed loopback smoke check and a strict draft-versioned fixture runner. It validates every fixture offline before protected-file or network access, emits deterministic JSON Lines, and keeps credentials, message and envelope bytes, paths, URLs, response bodies, and raw errors out of diagnostics.

Useful verification commands:

go test ./...   # root library module only; run at the repository root
go test ./cmd/dkim2d/...
go test ./cmd/dkim2-milter/...
go test ./cmd/dkim2ctl/...
go test ./cmd/dkim2-dsn-propagator/...
make test
make test-redis
make check-conformance
make conformance
make conformance-postfix
make conformance-all
make check-security
make fuzz-security
make security
make check-images
make check-deployment
make deployment-postfix
make deployment-security
make check-operator-docs
make check-datasource-schema
make check-datasource-postgresql
make check-datasource-mysql
make test-datasource-services
make check-ci
make check-container-release
make check-release
make guardrails
make release-guardrails

Public Validators

Several public DKIM2 validators are available. This project's validator is dkim2.pub; other services include dkim2.com and dkim2.eu.

Documentation

Overview

Package dkim2 provides verification and signing for draft-ietf-dkim-dkim2-spec-09.

A Verifier requires an injected PublicKeyProvider. VerifyRequest owns cloned raw RFC 5322 bytes; those bytes are the sole authority for message and DKIM2 protocol fields. Bracketed SMTP reverse-path and forward-path bytes are separate current-envelope evidence and are never inferred from headers. Results and requests expose copies rather than caller-owned mutable storage.

Verify returns exactly PASS, FAIL, PERMERROR, or TEMPERROR. Caller context cancellation and API misuse return a zero result with a Go error. Message, parser, limit, protocol, key, provider, timestamp, envelope, custody, hash, and cryptographic outcomes return a populated result with a nil Go error. The precedence is caller/API error, PERMERROR, FAIL, TEMPERROR, then PASS; these states do not prescribe local MTA acceptance policy.

EvaluatePolicy applies a separate immutable local policy decision to the sealed projection embedded in a library-created VerifyResult. Verification state remains authoritative and unchanged. Strict mode is the default; permissive and testing modes require explicit options. A continue verdict is non-terminal and is neither PASS nor accept. Every successful evaluation returns exactly one matching disposition action.

The public verifier authenticates every inherited signature flag on aggregate PASS. Draft-07 Section 10.10 removed the donotmodify and donotexplode flags: received spellings are inert unknown flags, signing never emits them, and policy derives no compliance state from them. Feedback output is bounded intent without a destination or route. The retired DNS key-record t= tag carries no policy meaning; only the explicitly configured local testing mode relaxes a verdict. Pre-target malformed, missing, sequence, or limit outcomes remain valid fact-free PERMERROR results for policy evaluation. Policy results, findings, actions, and errors contain only bounded enums, booleans, counts, and sequence numbers, never message, identity, selector, key, provider, or route material.

Provider status is exactly found, missing, invalid, ambiguous, revoked, unsupported_key_type, or algorithm_mismatch, and a declared status accompanies a nil error. Found results contain a matching *rsa.PublicKey or ed25519.PublicKey; accepted public material is cloned before use. Private keys, crypto.Signer, open-ended material, mismatched algorithms, and inconsistent status/material pairs are not accepted. Provider failures are classified only through typed temporary or permanent errors, never error text. An error matching the active caller context remains Go control flow. Missing, invalid, ambiguous, revoked, unsupported, mismatch, typed permanent, and contract failures produce structured PERMERROR results. Typed temporary failure produces TEMPERROR only without a higher-priority fact. A provider-owned deadline while the caller context is live is temporary only when explicitly typed temporary; otherwise it is a provider contract error.

NewDNSPublicKeyProvider constructs the DNS-backed provider for the tested draft-ietf-dkim-dkim2-dns-02 behavior baseline. The 2026-09-14 migration from the individual DNS draft changed identifiers, not normative behavior. The provider derives an absolute <selector>._domainkey.<signing-domain>. owner from signed values, so transports and callers must treat that name as sensitive diagnostic data. TXTTransport returns already-concatenated bytes for one TXT resource record while retaining the RR count. More than one RR is fail-closed ambiguous; records are never selected or concatenated across RR boundaries. NetTXTTransport maps each net.Resolver string to one RR and supplies zero TTL, so it cannot populate the provider cache. TTL-aware injected transports may enable bounded positive, authoritative-negative, and stable-error caching.

Draft-09 Sections 7.1 item 3 and 11.1 also make a From header field Authentic when d= is a subdomain of the From domain, unless the From domain publishes a Section 3.8 Domain Policy Record with f=strict at _domainkey.<domain>. NewVerifier and NewSigner therefore require an explicit choice: a key provider that also implements DomainPolicyProvider (as DNSPublicKeyProvider does through the same resolver, cache, and limits), WithDomainPolicyProvider / WithSignerDomainPolicyProvider, or the documented downward-only WithoutSubdomainFromAuthorization / WithoutSignerSubdomainFromAuthorization. Policy records are queried only after every signature proof passed. Signers themselves choose d= downward only and never query a Domain Policy Record.

DNS key records use PKCS#1 RSAPublicKey DER for RSA, exactly 32 raw bytes for Ed25519, and exactly the 1312-octet raw FIPS 204 public key for the Draft-09 Section 3.4 post-quantum mldsa44 algorithm. DNS-02 defines no key type for it; k=mldsa44 is the documented local interpretation. The Draft-07 mldsa44-ed25519-sha512 composite is no longer defined: such signature sets are ignored as unsupported algorithms and k=mldsa44-ed25519-sha512 records are unsupported key types, exactly like any other unknown token. Empty p= is revoked. Non-empty p= accepts omitted terminal Base64 padding as DNS-02 specifies while still requiring canonical zero pad bits. The parser recognizes lowercase k= as the DNS-02 grammar requires; the inherited DNS-00 ABNF typo is corrected there. The active DKIM2 signature grammar exposes no q= option; DNS TXT is the only lookup binding. The t= tag is retired by DNS-02 Section 3.4.1: it is validated only by the generic tag-list rules and is otherwise ignored, so DNS key records never yield testing or strict-identity semantics. DNSSECStatus is bounded transport diagnostic metadata and never changes key acceptance, cache lifetime, or verification facts.

DNSProviderConfig bounds cache capacity, TTL classes, transport concurrency, coalesced waiters, and lookup duration. Non-final canceled waiters leave a shared lookup independently. The final canceled waiter cancels the transport context and remains cleanup owner until the context-compliant transport returns. A deliberately context-ignoring injected transport can therefore hold that final caller and its single bounded flight slot; no helper goroutine is created to pretend arbitrary Go code can be forcibly canceled.

Aggregate PASS reports scope=chain, authenticated content coverage as complete or partial only for explicit unavailable-body history, and historical signatures as complete. Non-PASS results retain scope=current and do not claim historical coverage. The verifier reconstructs bounded Message-Instance history and verifies every inherited signature after current PASS. Custody structure is reported separately as not_evaluated, not_present, nd_links_evaluated, or terminal_nd_requires_oob. Pre-extraction parser or early-limit uncertainty is not_evaluated, never not_present; not_present is reported only after successful extraction establishes absence. Structural link evaluation is not historical content or signature verification. A terminal current nd= requires unmodeled out-of-band trust and therefore returns PERMERROR.

NewSigner exposes exactly three request paths. SignOriginator creates the initial Message-Instance and DKIM2-Signature. SignExisting consumes only a capability issued by VerifyForRevision and derives hash-unchanged forwarding or revision from the Section 12.1 digest gate; callers cannot select the role. SignNextDomain consumes the same sealed revision evidence plus a fresh, single-use published-next-domain capability and emits one terminal nd= signature. All paths snapshot the raw message plus the independently observed exact outgoing SMTP reverse path and ordered forward paths. Signing requires that envelope observation to equal the authority-issued exact-copy route ticket; it is never inferred from the ticket. All paths also require the closed final_network_form_pre_dot_stuffing transport declaration. Signing profiles contain public verification material and opaque private-key handles; injected private signers receive only one closed algorithm and native SHA-256 digest.

Fanout planning binds raw pre-sign bytes, envelope paths, disclosure class, route scope, purpose, and revision capability before signing. Signing limits may narrow but never widen the protocol, recipe, verification, route, crypto, and callback owners' hard ceilings. Every successful message is inserted, reparsed, custody-checked, and cryptographically self-verified before its reservation commits to unrestricted completion or the exact restricted-release state.

Internal datasource providers resolve exact immutable signing profiles and administrative policies without becoming protocol authorities. The datasource/signingprofile package is the only bridge to the signing domain: it validates same-snapshot results and maps provider-neutral key-handle IDs through an immutable registry to existing inert PrivateKeyHandle values. Datasource success never replaces the fresh DNS publication check, signing validation, route authorization, or private signer callback. The confined flat-file provider owns a duplicated directory descriptor, strictly decodes bounded versioned JSON, publishes complete snapshots atomically, and stops serving after a failed reload until explicit recovery.

Verifier.EvaluateReceivedDSN exposes the read-only Draft-09 Section 16.4 evaluation of an inbound DKIM2-signed delivery-status notification after the caller verified the outer message as an ordinary message with the same verifier. It takes the exact outer bytes, the observed null reverse path and single forward path, and an optional tenant-bound LocalAuthority, and proves in order RFC 6522 and strict generic RFC 3464 structure, embedded-original verification through the dedicated embedded verifiers, local-hop identity, outer-signer alignment, recipient linkage, failure class, and the previous hop. The completion signature's Section 10.4 window is evaluated at the outer DSN's highest-signature t= instead of the clock, because a DSN may legitimately arrive long after the forwarding it reports on. "Local" is datasource authority over the completion signature's d=, never an address in mf=; a verified foreign signer naming a local address is not_local. The local hop is a run: the completion signature plus every Section 12.3 nd= or same-tenant imaginary-hop member below it, each verified cryptographically; a non-verifying member or an nd= previous hop is an unsupported chain. The result is the closed delivery_status projection with bounded sequence facts and no content; it can never authorize signing. Without an authority the local hop and propagation are not evaluated. WithReceivedDSNEvaluation attaches the evaluation to EvaluatePolicy or EvaluateAuthenticationPolicy, which record the received-DSN mapping-table row as one finding on the single PolicyDecision: reject, tempfail, and continue rows replace the outer verdict, accept rows keep it, and an outer verification or final replay state other than PASS keeps the outer policy unchanged.

Signer.RebuildDSNForPropagation and Signer.SignPropagatedDSN implement Draft-09 Section 16.3 propagation of a received DSN to the previous hop. The signer re-runs the received-DSN evaluation on the exact request bytes with the mandatory tenant-bound LocalAuthority, and only an eligible evaluation is rebuilt: the local hop run's DKIM2-Signature fields and every Message-Instance above the previous hop's instance are removed by tag value, every Section 4 hash-excluded field above the previous hop signature is removed as fixed local policy, the run is descended through the authenticated recipes with every intermediate state re-proven, and the previous hop signature is verified over the reconstructed state with its Section 10.4 window evaluated at the completion signature's t=. Body evidence that was unavailable at any point degrades the embedded part to text/rfc822-headers. The rebuilt header block keeps the pruned wire order for every name the run's recipes did not rewrite, custody is validated over the whole chain below and including the previous hop, and a previous hop mf= or rt= carrying an obsolete source route is not reconstructable. The fresh report carries a fixed English human part with Content-Language en, Reporting-MTA, an optional verbatim Original-Envelope-Id, one recipient group naming the previous hop's single rt= path with Action failed and the 4.X.Y or 5.X.Y status of the propagation group or 5.0.0, and no destination-specific field. The signing domain is the canonical d= of the removed completion signature; the route purpose delivery_status_propagation, disclosure single, class external, binds the null reverse path to the authenticated previous mf=, and the signed DSN carries exactly one Message-Instance m=1 and one DKIM2-Signature i=1 with mf=<> and rt= equal to that address. PropagatedDSN reports SMTPUTF8Required when any header field of the DSN carries a non-ASCII byte and EightBitMIMERequired when only the embedded body does. Not reconstructable, null previous sender, unsupported chain, terminal origin, non-failure, and ineligible states never produce output. ReplayDeriver.DerivePropagation derives the propagation replay coordinate under a distinct domain-separation frame, and ReplayPropagationStore reserves it with a lease and commits it in two phases.

SigningResult is a closed sum. Only UnrestrictedSignedMessage has Bytes. OutOfBandAcceptanceSignedMessage deliberately has no generic byte, marshal, text, or release surface. Its type-specific release method atomically consumes the same ticket lineage only after proving the exact sealed OOB receiver, envelope, and route. A terminal next-domain result remains OOB-restricted until that release or a later authorized ordinary completion. Once an adapter legitimately receives released bytes, it can still duplicate or misroute them; the library does not claim replay prevention outside the bound release arrangement.

Supported PASS plus an unknown algorithm may pass; unknown-only coverage is PERMERROR, and a supported signature or current hash mismatch prevents PASS according to the precedence above. Callers should inspect typed state, ReasonCode, CheckClass, and SignatureSetFact values rather than parse text.

Defaults and hard maxima are 128 MiB raw message bytes, 2,000 current recipients, 16 Message-Instance hash sets, 16 signature sets, 128 retained check facts, and 16 retained signature facts. Options may narrow but never widen these limits. Timestamp policy permits five minutes of future skew as local verification policy, not a draft requirement, and enforces a non-disableable 14-day maximum age.

MAIL FROM comparison uses bracketed paths, ASCII-only domain lowercasing, case-sensitive local parts, and <> matching only <>. Every current recipient must occur in signed rt=; signed extras and order differences are allowed. Signing-domain d= uses relaxed right-label alignment against the signed MAIL FROM domain and is distinct from exact envelope-path comparison.

Index

Examples

Constants

View Source
const (
	// ObservationVerifyCompleted identifies a completed verification observation.
	ObservationVerifyCompleted = internalobs.KindVerifyCompleted
	// ObservationDNSLookupCompleted identifies a completed DNS lookup observation.
	ObservationDNSLookupCompleted = internalobs.KindDNSLookupCompleted
	// ObservationOperationVerify identifies signature verification work.
	ObservationOperationVerify = internalobs.OperationVerify
	// ObservationOperationDNSLookup identifies DNS key lookup work.
	ObservationOperationDNSLookup = internalobs.OperationDNSLookup
	// ObservationResultSuccess identifies successful work.
	ObservationResultSuccess = internalobs.ResultSuccess
	// ObservationResultFailure identifies a closed expected failure.
	ObservationResultFailure = internalobs.ResultFailure
	// ObservationResultTemporary identifies temporary failure.
	ObservationResultTemporary = internalobs.ResultTemporary
	// ObservationResultInternal identifies contained internal failure.
	ObservationResultInternal = internalobs.ResultInternal
	// ObservationReasonNone identifies an outcome without a failure reason.
	ObservationReasonNone = internalobs.ReasonNone
	// ObservationReasonProtocol identifies protocol-driven failure.
	ObservationReasonProtocol = internalobs.ReasonProtocol
	// ObservationReasonPolicy identifies local-policy failure.
	ObservationReasonPolicy = internalobs.ReasonPolicy
	// ObservationReasonUnavailable identifies unavailable infrastructure.
	ObservationReasonUnavailable = internalobs.ReasonUnavailable
	// ObservationErrorNone identifies an outcome without an error.
	ObservationErrorNone = internalobs.ErrorNone
	// ObservationErrorCanceled identifies caller cancellation.
	ObservationErrorCanceled = internalobs.ErrorCanceled
	// ObservationErrorDeadline identifies deadline expiry.
	ObservationErrorDeadline = internalobs.ErrorDeadline
	// ObservationErrorTemporary identifies retryable failure.
	ObservationErrorTemporary = internalobs.ErrorTemporary
	// ObservationErrorPermanent identifies non-retryable failure.
	ObservationErrorPermanent = internalobs.ErrorPermanent
	// ObservationErrorInternal identifies contained internal failure.
	ObservationErrorInternal = internalobs.ErrorInternal
	// ObservationAlgorithmNone identifies absence of an algorithm.
	ObservationAlgorithmNone = internalobs.AlgorithmNone
	// ObservationAlgorithmRSA identifies the RSA family.
	ObservationAlgorithmRSA = internalobs.AlgorithmRSA
	// ObservationAlgorithmEd25519 identifies the Ed25519 family.
	ObservationAlgorithmEd25519 = internalobs.AlgorithmEd25519
	// ObservationAlgorithmMLDSA44 identifies the pure ML-DSA-44 family.
	ObservationAlgorithmMLDSA44 = internalobs.AlgorithmMLDSA44
	// ObservationAlgorithmUnknown identifies a bounded unknown family.
	ObservationAlgorithmUnknown = internalobs.AlgorithmUnknown
	// ObservationCacheNotUsed identifies a lookup without caching.
	ObservationCacheNotUsed = internalobs.CacheNotUsed
	// ObservationCacheHit identifies a cache hit.
	ObservationCacheHit = internalobs.CacheHit
	// ObservationCacheMiss identifies a cache miss.
	ObservationCacheMiss = internalobs.CacheMiss
	// ObservationBucketNone identifies an empty or absent quantity.
	ObservationBucketNone = internalobs.BucketNone
	// ObservationBucketSmall identifies a bounded small quantity.
	ObservationBucketSmall = internalobs.BucketSmall
	// ObservationBucketMedium identifies a bounded medium quantity.
	ObservationBucketMedium = internalobs.BucketMedium
	// ObservationBucketLarge identifies a bounded large quantity.
	ObservationBucketLarge = internalobs.BucketLarge
	// ObservationBucketOverflow identifies a quantity above the largest bound.
	ObservationBucketOverflow = internalobs.BucketOverflow
)
View Source
const (
	// HardMaxPolicyAuthenticatedHops bounds authenticated facts consumed by one public evaluation.
	HardMaxPolicyAuthenticatedHops = 128
	// HardMaxPolicyFindings bounds retained findings returned by one public evaluation.
	HardMaxPolicyFindings = 128
)
View Source
const (
	// ReplayKeyAlgorithm identifies the frozen privacy-preserving replay-key algorithm.
	ReplayKeyAlgorithm = replay.KeyAlgorithm
	// ReplayStoredValue is the legacy nonce-free first-seen marker that
	// ParseReplayFirstSeenValue still accepts as a foreign record.
	ReplayStoredValue = replay.StoredValue
	// ReplayFirstSeenValuePrefix starts the nonce-bearing first-seen value.
	ReplayFirstSeenValuePrefix = replay.FirstSeenValuePrefix
)
View Source
const (
	// ReplayCheckFirstSeen means the identity was atomically retained for the first time.
	ReplayCheckFirstSeen = replay.CheckFirstSeen
	// ReplayCheckReplayed means the identity already existed without retention extension.
	ReplayCheckReplayed = replay.CheckReplayed
	// ReplayCheckDisabled means explicit local policy selected no replay storage.
	ReplayCheckDisabled = replay.CheckDisabled
)
View Source
const (
	// ReplayStoreReady permits enabled storage operations.
	ReplayStoreReady = replay.StoreReady
	// ReplayStoreDegraded reports a fail-closed enabled provider impairment.
	ReplayStoreDegraded = replay.StoreDegraded
	// ReplayStoreDisabled reports an explicitly selected disabled provider.
	ReplayStoreDisabled = replay.StoreDisabled
	// ReplayStoreClosing rejects new operations while admitted work drains.
	ReplayStoreClosing = replay.StoreClosing
	// ReplayStoreClosed rejects all later operations.
	ReplayStoreClosed = replay.StoreClosed
)
View Source
const (
	// ReplayErrorInvalidRequest classifies invalid input or a missing required value.
	ReplayErrorInvalidRequest = replay.ErrorCodeInvalidRequest
	// ReplayErrorMisconfigured classifies incomplete or unsafe construction.
	ReplayErrorMisconfigured = replay.ErrorCodeMisconfigured
	// ReplayErrorLimitExceeded classifies a hard bounded-resource refusal.
	ReplayErrorLimitExceeded = replay.ErrorCodeLimitExceeded
	// ReplayErrorUnavailable classifies a proved pre-dispatch backend outage.
	ReplayErrorUnavailable = replay.ErrorCodeUnavailable
	// ReplayErrorIndeterminate classifies a write that may have crossed mutation dispatch.
	ReplayErrorIndeterminate = replay.ErrorCodeIndeterminate
	// ReplayErrorInconsistent classifies an authoritative contradictory backend outcome.
	ReplayErrorInconsistent = replay.ErrorCodeInconsistent
	// ReplayErrorCancelled classifies pre-dispatch caller cancellation.
	ReplayErrorCancelled = replay.ErrorCodeCancelled
	// ReplayErrorDeadlineExceeded classifies a pre-dispatch elapsed caller deadline.
	ReplayErrorDeadlineExceeded = replay.ErrorCodeDeadlineExceeded
	// ReplayErrorClosed classifies work rejected after close begins.
	ReplayErrorClosed = replay.ErrorCodeClosed
	// ReplayErrorInternalInvariant classifies impossible in-process state.
	ReplayErrorInternalInvariant = replay.ErrorCodeInternalInvariant
)
View Source
const (
	// ReplayPropagationStatePending reports a reserved coordinate whose attempt has not committed.
	ReplayPropagationStatePending = replay.PropagationStatePending
	// ReplayPropagationStateCommitted reports a coordinate whose propagated report was accepted.
	ReplayPropagationStateCommitted = replay.PropagationStateCommitted
	// ReplayPropagationCommittedValue is the exact stored value of a committed coordinate.
	ReplayPropagationCommittedValue = replay.PropagationCommittedValue
	// ReplayPropagationPendingPrefix starts the stored value of a pending coordinate.
	ReplayPropagationPendingPrefix = replay.PropagationPendingPrefix
)
View Source
const (
	// ReplayPropagationReserved means the coordinate is now pending under a fresh lease.
	ReplayPropagationReserved = replay.PropagationReserved
	// ReplayPropagationPending means another attempt holds a live lease.
	ReplayPropagationPending = replay.PropagationPending
	// ReplayPropagationAlreadyCommitted means the coordinate was committed within retention.
	ReplayPropagationAlreadyCommitted = replay.PropagationAlreadyCommitted
	// ReplayPropagationReservationDisabled means explicit local policy selected no replay storage.
	ReplayPropagationReservationDisabled = replay.PropagationReservationDisabled
)
View Source
const (
	// ReplayPropagationCommitted means the coordinate is committed.
	ReplayPropagationCommitted = replay.PropagationCommitted
	// ReplayPropagationCommitUnresolved means the token resolves to no pending or committed coordinate within retention.
	ReplayPropagationCommitUnresolved = replay.PropagationCommitUnresolved
	// ReplayPropagationCommitDisabled means explicit local policy selected no replay storage.
	ReplayPropagationCommitDisabled = replay.PropagationCommitDisabled
)
View Source
const (
	// HardMaxRawMessageBytes is the public verification maximum raw RFC 5322 message size.
	HardMaxRawMessageBytes = rawmsg.HardMaxMessageBytes
	// HardMaxRecipients is the public verification maximum current SMTP recipient count.
	HardMaxRecipients = 2_000
	// HardMaxInstanceHashSets is the public verification maximum hash-set count per Message-Instance.
	HardMaxInstanceHashSets = 16
	// HardMaxSignatureSets is the public verification maximum signature-set count per DKIM2-Signature.
	HardMaxSignatureSets = 16
	// HardMaxCheckFacts is the public verification maximum retained check-fact count.
	HardMaxCheckFacts = 128
	// HardMaxSignatureFacts is the public verification maximum retained signature-set-fact count.
	HardMaxSignatureFacts = 16
)
View Source
const DraftIdentifier = "draft-ietf-dkim-dkim2-spec-09"

DraftIdentifier identifies the exact DKIM2 behavior baseline implemented by this verification facade.

View Source
const MinSigningRSABits = cryptodkim2.MinSigningRSABits

MinSigningRSABits is the local RSA signing floor: RSA signing credentials and loaded signing profiles require a modulus of at least 2048 bits (Draft-09 Section 3.2 SHOULD made a local MUST). Verification still accepts 1024 to 8192 bits.

View Source
const ReplayPropagationKeyDomainLabel = replay.PropagationKeyDomainLabel

ReplayPropagationKeyDomainLabel is the distinct domain-separation frame of propagation coordinates.

View Source
const VerifierProjectionSchema = "dkim2.verifier-projection.v1"

VerifierProjectionSchema identifies the stable transport-neutral verifier projection.

Variables

This section is empty.

Functions

func EnvelopePathDomain

func EnvelopePathDomain(path []byte) (string, bool)

EnvelopePathDomain returns the canonical lowercase A-label DNS domain of one non-null SMTP path, converting a U-label domain with the strict IDNA profile (Draft-09 Section 18). Null paths, address literals, and invalid paths report false. Adapters use it to select a signing domain from an SMTPUTF8 envelope without their own IDNA mapping.

func HeaderFromDomain

func HeaderFromDomain(rawMessage []byte) (string, bool)

HeaderFromDomain derives the canonical DNS domain of the single RFC 5322 author mailbox of a message that is eligible for header_from null-sender originator signing; see ClassifyHeaderFromNullSender. The derivation succeeds only for exactly one From header field that holds exactly one mailbox, not a group, whose addr-spec is ASCII and whose domain is a DNS name accepted by the canonicalization used for delivery-status signing identities and d= values. Every other class reports false.

func IsReplayError

func IsReplayError(err error) bool

IsReplayError reports whether err is one direct member of the closed taxonomy.

func MLDSA44Available

func MLDSA44Available() error

MLDSA44Available reports an error when the cryptographic runtime cannot provide ML-DSA-44, for example a binary built against the FIPS 140-3 Go Cryptographic Module v1.0.0. Verifier construction and mldsa44 signing credentials fail closed in that runtime; daemons call it at startup to report the reason.

func MLDSA44SignerOptions

func MLDSA44SignerOptions() *mldsa.Options

MLDSA44SignerOptions returns the options every mldsa44 PrivateKeySigner passes to crypto/mldsa PrivateKey.Sign: pure ML-DSA.Sign over the message representative with the Draft-09 Section 3.4 context string "DKIM2". Signers use the default hedged (randomized) Sign, never SignDeterministic.

func MaxCarriedTXTRecords

func MaxCarriedTXTRecords() int

MaxCarriedTXTRecords returns how many TXT resource records of one answer a transport hands over with their payloads. Draft-09 Sections 3.7 and 3.8 ignore records that begin with a foreign v= tag before deciding uniqueness, so every record up to this bound must be inspectable; a larger answer is reported count-only and stays ambiguous.

func NewPermanentProviderError

func NewPermanentProviderError() error

NewPermanentProviderError constructs a cause-free permanent provider error.

func NewReplayError

func NewReplayError(code ReplayErrorCode) error

NewReplayError constructs one stable replay failure without protected detail.

func NewTemporaryProviderError

func NewTemporaryProviderError() error

NewTemporaryProviderError constructs a cause-free temporary provider error.

func Observe

func Observe(ctx context.Context, sink ObservationSink, event ObservationEvent)

Observe invokes one sink while containing invalid input and sink panics.

func ProjectedPrivateKeyHandle

func ProjectedPrivateKeyHandle(handle PrivateKeyHandle) (signing.PrivateKeyHandle, error)

ProjectedPrivateKeyHandle returns the detached internal handle needed by repository-owned datasource bridges. The return type prevents use outside sibling modules that are permitted to import the internal signing package.

func ReplayFirstSeenValue

func ReplayFirstSeenValue(nonce ReplayNonce) (string, error)

ReplayFirstSeenValue renders the nonce-bearing first-seen value "v2:<nonce>".

func ReplayPropagationPendingValue

func ReplayPropagationPendingValue(leaseExpiry time.Time, nonce ReplayNonce) (string, error)

ReplayPropagationPendingValue renders the nonce-bearing pending value "pending:<unixms>:<nonce>" for one lease expiry and write nonce.

func UseReplayStorageKey

func UseReplayStorageKey(key ReplayKey, use func(storageKey string) error) error

UseReplayStorageKey authorizes one synchronous pre-dispatch callback for a protected key.

func ValidEnvelopePath

func ValidEnvelopePath(path []byte, allowNull bool) bool

ValidEnvelopePath reports whether exact bracketed SMTP path bytes satisfy the DKIM2 envelope path grammar, including RFC 6531 UTF-8 local parts and U-label domains. allowNull admits the null reverse path "<>". Adapters use it so that SMTPUTF8 admission has one owner.

Types

type APIError

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

APIError is a bounded typed error for verifier construction or request misuse.

func (*APIError) Code

func (e *APIError) Code() APIErrorCode

Code returns the stable API-error code.

func (*APIError) Error

func (e *APIError) Error() string

Error returns a bounded diagnostic without message, envelope, key, or provider data.

func (*APIError) Is

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

Is matches API errors by their stable code.

type APIErrorCode

type APIErrorCode string

APIErrorCode identifies bounded verifier construction or request misuse.

const (
	// APIErrorCodeInvalidProvider reports a missing or unusable provider dependency.
	APIErrorCodeInvalidProvider APIErrorCode = "invalid_provider"
	// APIErrorCodeInvalidOption reports an unsafe verifier option.
	APIErrorCodeInvalidOption APIErrorCode = "invalid_option"
	// APIErrorCodeInvalidRequest reports programmer misuse of the request contract.
	APIErrorCodeInvalidRequest APIErrorCode = "invalid_request"
)

func (APIErrorCode) Known

func (c APIErrorCode) Known() bool

Known reports whether the code is in the closed public API-error vocabulary.

type Algorithm

type Algorithm string

Algorithm identifies a bounded DKIM2 signature algorithm family.

const (
	// AlgorithmRSASHA256 identifies RSA-SHA256 verification.
	AlgorithmRSASHA256 Algorithm = "rsa-sha256"
	// AlgorithmEd25519SHA256 identifies Ed25519-SHA256 verification.
	AlgorithmEd25519SHA256 Algorithm = "ed25519-sha256"
	// AlgorithmMLDSA44 identifies Draft-09 Section 3.4 pure ML-DSA-44
	// signing and verification with the "DKIM2" context string.
	AlgorithmMLDSA44 Algorithm = "mldsa44"
	// AlgorithmUnknown represents an unrecognized message-derived algorithm without retaining its spelling.
	AlgorithmUnknown Algorithm = "unknown"
)

func (Algorithm) Known

func (a Algorithm) Known() bool

Known reports whether the algorithm is in the closed public vocabulary.

type AuthenticationReason

type AuthenticationReason = ReasonCode

AuthenticationReason identifies the authoritative Draft-09 result reason.

type AuthenticationReplayClass

type AuthenticationReplayClass string

AuthenticationReplayClass identifies one final replay classification.

const (
	// AuthenticationReplayNotChecked means replay is inapplicable before final PASS.
	AuthenticationReplayNotChecked AuthenticationReplayClass = "not_checked"
	// AuthenticationReplayNotEligible means the message passed but only the
	// originator's i=1 signature authenticated it, so no intermediary re-sent
	// it and Draft-09 Section 15.1 replay counting does not apply.
	AuthenticationReplayNotEligible AuthenticationReplayClass = "not_eligible"
	// AuthenticationReplayDisabled means the explicit no-store mode accepted the message.
	AuthenticationReplayDisabled AuthenticationReplayClass = "disabled"
	// AuthenticationReplayFirstSeen means the message-wide identity was inserted once.
	AuthenticationReplayFirstSeen AuthenticationReplayClass = "first_seen"
	// AuthenticationReplayExploded means authenticated fanout permits repeated delivery.
	AuthenticationReplayExploded AuthenticationReplayClass = "exploded"
	// AuthenticationReplayReplayed means an unexpected duplicate was observed.
	AuthenticationReplayReplayed AuthenticationReplayClass = "replayed"
	// AuthenticationReplayIndeterminate means storage could not provide a final answer.
	AuthenticationReplayIndeterminate AuthenticationReplayClass = "indeterminate"
)

func (AuthenticationReplayClass) Known

func (c AuthenticationReplayClass) Known() bool

Known reports whether the class belongs to the closed Draft-09 vocabulary.

type AuthenticationResult

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

AuthenticationResult is one sealed final stateful Draft-09 result. It layers local replay delivery policy over the stateless DKIM2 validity result, which Verification returns unchanged.

func (AuthenticationResult) Format

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

Format prevents formatting from traversing verification or replay facts.

func (AuthenticationResult) GoString

func (AuthenticationResult) GoString() string

GoString returns a content-free final-result representation.

func (AuthenticationResult) PrimaryReason

func (r AuthenticationResult) PrimaryReason() AuthenticationReason

PrimaryReason returns the replay-owned reason, or none after final PASS.

func (AuthenticationResult) ReplayClass

ReplayClass returns the final bounded replay classification.

func (AuthenticationResult) State

State returns the authoritative final authentication state.

func (AuthenticationResult) String

func (AuthenticationResult) String() string

String returns a content-free final-result representation.

func (AuthenticationResult) Valid

func (r AuthenticationResult) Valid() bool

Valid reports whether cryptographic evidence and the final replay state are coherent.

func (AuthenticationResult) Verification

func (r AuthenticationResult) Verification() VerifyResult

Verification returns immutable message-local cryptographic evidence.

type Authenticator

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

Authenticator owns verification and the mandatory stateful replay decision.

func NewAuthenticator

func NewAuthenticator(verifier *Verifier, store ReplayStore, deriver *ReplayDeriver, retention ReplayRetention, options ...AuthenticatorOption) (*Authenticator, error)

NewAuthenticator constructs one enabled fail-closed Draft-09 authenticator.

func NewDisabledAuthenticator

func NewDisabledAuthenticator(verifier *Verifier, options ...AuthenticatorOption) (*Authenticator, error)

NewDisabledAuthenticator constructs the sole explicit no-store authentication mode. Replay options require a store, so any option fails closed.

func (*Authenticator) Authenticate

func (a *Authenticator) Authenticate(ctx context.Context, request VerifyRequest) (AuthenticationResult, error)

Authenticate performs message-local verification then one message-wide replay mutation.

func (*Authenticator) AuthenticateVerified

func (a *Authenticator) AuthenticateVerified(ctx context.Context, verification VerifyResult) (AuthenticationResult, error)

AuthenticateVerified coordinates replay for immutable evidence already produced by the owned verifier.

type AuthenticatorOption

type AuthenticatorOption func(*Authenticator)

AuthenticatorOption configures optional local replay delivery policy.

func WithDirectDeliveryReplayCounting

func WithDirectDeliveryReplayCounting() AuthenticatorOption

WithDirectDeliveryReplayCounting makes local replay policy count messages authenticated only by the originator's i=1 signature. Draft-09 Section 15.1 leaves replay counting to local delivery policy and does not count such direct deliveries by default; a receiver that acts on every accepted message, such as a reflector, may count them so an identical direct delivery is reported as a replay. The constructors enforce that it is used only with an enabled replay store.

type BodyUnavailablePolicy

type BodyUnavailablePolicy uint8

BodyUnavailablePolicy controls whether a revision may emit explicit b:null.

const (
	// RejectUnavailableBody fails when the prior body cannot be represented.
	RejectUnavailableBody BodyUnavailablePolicy = iota
	// AllowUnavailableBody permits explicit b:null when representation is
	// impossible (Draft-09 Section 12.1 MAY).
	//
	// Warning: a message whose history contains a null body Recipe is never
	// a Fully Verified DKIM2 Message (Draft-09 Section 13). Every later
	// verifier reports PERMERROR body_history_unavailable (Section 14.2), and every later
	// transit or revision signer, including this library's
	// VerifyForRevision, refuses to sign it again. Use it only where the
	// recipients accept that outcome by local arrangement.
	AllowUnavailableBody
)

func (BodyUnavailablePolicy) Known

func (p BodyUnavailablePolicy) Known() bool

Known reports whether policy belongs to the closed revision vocabulary.

type CheckClass

type CheckClass string

CheckClass identifies a bounded verification concern without exposing message-derived values.

const (
	// CheckClassMessage identifies raw message handling.
	CheckClassMessage CheckClass = "message"
	// CheckClassProtocol identifies DKIM2 field and sequence handling.
	CheckClassProtocol CheckClass = "protocol"
	// CheckClassBodyHash identifies current body-hash verification.
	CheckClassBodyHash CheckClass = "body_hash"
	// CheckClassHeaderHash identifies current header-hash verification.
	CheckClassHeaderHash CheckClass = "header_hash"
	// CheckClassSignature identifies cryptographic signature verification.
	CheckClassSignature CheckClass = "signature"
	// CheckClassKey identifies public-key validity or availability.
	CheckClassKey CheckClass = "key"
	// CheckClassTimestamp identifies timestamp policy evaluation.
	CheckClassTimestamp CheckClass = "timestamp"
	// CheckClassEnvelope identifies current SMTP envelope comparison.
	CheckClassEnvelope CheckClass = "envelope"
	// CheckClassDomainAlignment identifies signing-domain alignment.
	CheckClassDomainAlignment CheckClass = "domain_alignment"
	// CheckClassNextDomain identifies structural next-domain evaluation.
	CheckClassNextDomain CheckClass = "next_domain"
	// CheckClassProvider identifies public-key-provider behavior.
	CheckClassProvider CheckClass = "provider"
	// CheckClassInternalContract identifies an unknown or inconsistent internal fact.
	CheckClassInternalContract CheckClass = "internal_contract"
)

func (CheckClass) Known

func (c CheckClass) Known() bool

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

type CheckFact

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

CheckFact records one bounded verification check and reason.

func (CheckFact) Class

func (f CheckFact) Class() CheckClass

Class returns the bounded verification concern.

func (CheckFact) Reason

func (f CheckFact) Reason() ReasonCode

Reason returns the bounded verification reason.

type ClassifiedProviderError

type ClassifiedProviderError interface {
	error
	ProviderErrorClass() ProviderErrorClass
}

ClassifiedProviderError exposes machine-readable provider failure class without a raw cause.

type CustodyStructure

type CustodyStructure string

CustodyStructure identifies the separately evaluated structural next-domain coverage.

const (
	// CustodyStructureNotEvaluated reports that earlier failure prevented reliable next-domain presence detection.
	CustodyStructureNotEvaluated CustodyStructure = "not_evaluated"
	// CustodyStructureNotPresent reports that no next-domain link was present.
	CustodyStructureNotPresent CustodyStructure = "not_present"
	// CustodyStructureNDLinksEvaluated reports that one or more intermediate next-domain links were evaluated.
	CustodyStructureNDLinksEvaluated CustodyStructure = "nd_links_evaluated"
	// CustodyStructureTerminalNDRequiresOOB reports that the current terminal next-domain needs unmodeled OOB trust.
	CustodyStructureTerminalNDRequiresOOB CustodyStructure = "terminal_nd_requires_oob"
)

func (CustodyStructure) Known

func (s CustodyStructure) Known() bool

Known reports whether the custody structure belongs to the closed public vocabulary.

type DNSProviderConfig

type DNSProviderConfig struct {
	Limits DNSResolverLimits
	Clock  func() time.Time
	Parent context.Context
}

DNSProviderConfig configures one instance-owned DNS public-key provider.

Example

ExampleDNSProviderConfig demonstrates TTL-backed caching and caller cancellation.

transport, err := newDNSExampleTransport()
if err != nil {
	fmt.Println("fixture error")
	return
}
config := dkim2.DefaultDNSProviderConfig()
config.Clock = func() time.Time { return time.Unix(1700000000, 0) }
config.Limits.MaxCacheEntries = 4
config.Limits.MaxPositiveTTL = 30 * time.Second
config.Limits.LookupTimeout = 2 * time.Second
provider, err := dkim2.NewDNSPublicKeyProviderWithConfig(transport, config)
if err != nil {
	fmt.Println("provider error")
	return
}
verifier, err := dkim2.NewVerifier(provider, dkim2.WithVerificationClock(func() time.Time { return time.Unix(1700000000, 0) }), dkim2.WithoutSubdomainFromAuthorization())
if err != nil {
	fmt.Println("verifier error")
	return
}
first, firstErr := verifier.Verify(context.Background(), syntheticExampleRequest())
second, secondErr := verifier.Verify(context.Background(), syntheticExampleRequest())
ctx, cancel := context.WithCancel(context.Background())
cancel()
canceled, canceledErr := verifier.Verify(ctx, syntheticExampleRequest())
fmt.Println(first.State(), second.State(), firstErr == nil && secondErr == nil, "lookups", transport.calls)
fmt.Println(errors.Is(canceledErr, context.Canceled), canceled.State() == "", "lookups", transport.calls)
fmt.Println(config.Limits.MaxCacheEntries, config.Limits.MaxPositiveTTL, config.Limits.LookupTimeout)
Output:
PASS PASS true lookups 1
true true lookups 1
4 30s 2s

func DefaultDNSProviderConfig

func DefaultDNSProviderConfig() DNSProviderConfig

DefaultDNSProviderConfig returns restrictive cache, concurrency, and lookup defaults.

type DNSPublicKeyProvider

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

DNSPublicKeyProvider resolves public verification keys through DNS TXT records.

func NewDNSPublicKeyProvider

func NewDNSPublicKeyProvider(transport TXTTransport) (*DNSPublicKeyProvider, error)

NewDNSPublicKeyProvider constructs a DNS-backed provider with restrictive defaults.

Example

ExampleNewDNSPublicKeyProvider demonstrates injected DNS verification; the fixture record carries the retired t=y:s tag, which DNS-02 ignores.

transport, err := newDNSExampleTransport()
if err != nil {
	fmt.Println("fixture error")
	return
}
config := dkim2.DefaultDNSProviderConfig()
config.Clock = func() time.Time { return time.Unix(1700000000, 0) }
provider, err := dkim2.NewDNSPublicKeyProviderWithConfig(transport, config)
if err != nil {
	fmt.Println("provider error")
	return
}
verifier, err := dkim2.NewVerifier(provider, dkim2.WithVerificationClock(func() time.Time { return time.Unix(1700000000, 0) }), dkim2.WithoutSubdomainFromAuthorization())
if err != nil {
	fmt.Println("verifier error")
	return
}
result, err := verifier.Verify(context.Background(), syntheticExampleRequest())
if err != nil {
	fmt.Println("caller or API error")
	return
}
fact := result.SignatureSets()[0]
fmt.Println(result.State(), result.PrimaryReason())
fmt.Println(fact.Algorithm(), fact.Status(), fact.Reason())
fmt.Println("lookups", transport.calls)
Output:
PASS none
rsa-sha256 pass none
lookups 1

func NewDNSPublicKeyProviderWithConfig

func NewDNSPublicKeyProviderWithConfig(transport TXTTransport, config DNSProviderConfig) (*DNSPublicKeyProvider, error)

NewDNSPublicKeyProviderWithConfig constructs a configured bounded DNS-backed provider.

func (DNSPublicKeyProvider) Format

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

Format prevents formatting from traversing the retained DNS resolver.

func (DNSPublicKeyProvider) GoString

func (DNSPublicKeyProvider) GoString() string

GoString returns a constant representation without retained DNS transport state.

func (*DNSPublicKeyProvider) LookupDomainPolicy

func (p *DNSPublicKeyProvider) LookupDomainPolicy(ctx context.Context, query DomainPolicyQuery) (DomainPolicyStatus, error)

LookupDomainPolicy resolves one Domain Policy Record through the provider's bounded DNS resolver, sharing its transport, cache, and single-flight coordination with key lookups.

func (*DNSPublicKeyProvider) LookupPublicKey

func (p *DNSPublicKeyProvider) LookupPublicKey(ctx context.Context, query PublicKeyQuery) (PublicKeyResult, error)

LookupPublicKey resolves one canonical public query without applying verifier key policy.

func (DNSPublicKeyProvider) MarshalJSON

func (DNSPublicKeyProvider) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of retained DNS resolver dependencies.

func (DNSPublicKeyProvider) MarshalText

func (DNSPublicKeyProvider) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of retained DNS resolver dependencies.

func (DNSPublicKeyProvider) String

func (DNSPublicKeyProvider) String() string

String returns a constant representation without retained DNS transport state.

type DNSResolverLimits

type DNSResolverLimits struct {
	MaxSelectorBytes, MaxSelectorLabels             int
	MaxSigningDomainBytes, MaxSigningDomainLabels   int
	MaxOwnerBytes, MaxTXTRecords, MaxTXTRecordBytes int
	MaxTags, MaxTagNameBytes, MaxTagValueBytes      int
	MaxDecodedKeyBytes, MaxCacheEntries             int
	MaxPositiveTTL, MaxNegativeTTL                  time.Duration
	MaxStableErrorTTL                               time.Duration
	MaxConcurrentLookups, MaxCoalescedWaiters       int
	LookupTimeout                                   time.Duration
}

DNSResolverLimits bounds public DNS resolution, caching, and concurrency resources.

type DNSSECStatus

type DNSSECStatus string

DNSSECStatus is optional verdict-neutral resolver diagnostic metadata.

const (
	// DNSSECStatusSecure reports a transport-provided secure diagnostic.
	DNSSECStatusSecure DNSSECStatus = "secure"
	// DNSSECStatusInsecure reports a transport-provided insecure diagnostic.
	DNSSECStatusInsecure DNSSECStatus = "insecure"
	// DNSSECStatusBogus reports a transport-provided bogus diagnostic.
	DNSSECStatusBogus DNSSECStatus = "bogus"
	// DNSSECStatusIndeterminate reports a transport-provided indeterminate diagnostic.
	DNSSECStatusIndeterminate DNSSECStatus = "indeterminate"
	// DNSSECStatusUnavailable reports that no DNSSEC diagnostic is available.
	DNSSECStatusUnavailable DNSSECStatus = "unavailable"
)

func (DNSSECStatus) Known

func (s DNSSECStatus) Known() bool

Known reports whether the status belongs to the closed diagnostic vocabulary.

type DSNEvidenceError

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

DSNEvidenceError preserves only a closed failure stage while retaining the existing public signing error through errors.Unwrap.

func (*DSNEvidenceError) Error

func (e *DSNEvidenceError) Error() string

Error returns a bounded diagnostic without message, envelope, or identity data.

func (*DSNEvidenceError) Format

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

Format routes every formatting verb through the bounded diagnostic.

func (*DSNEvidenceError) Stage

Stage returns the closed failure stage or the zero value.

func (*DSNEvidenceError) Unwrap

func (e *DSNEvidenceError) Unwrap() error

Unwrap preserves existing SigningError and context classification.

type DSNEvidenceStage

type DSNEvidenceStage string

DSNEvidenceStage identifies one closed content-free DSN authorization stage.

const (
	// DSNEvidenceStagePreflight identifies invalid evaluator or request state.
	DSNEvidenceStagePreflight DSNEvidenceStage = "preflight"
	// DSNEvidenceStageMIMEParse identifies outer DSN framing failure.
	DSNEvidenceStageMIMEParse DSNEvidenceStage = "mime_parse"
	// DSNEvidenceStageEmbeddedMessage identifies embedded RFC 5322 parsing failure.
	DSNEvidenceStageEmbeddedMessage DSNEvidenceStage = "embedded_message"
	// DSNEvidenceStageEmbeddedVerification identifies embedded cryptographic evidence failure.
	DSNEvidenceStageEmbeddedVerification DSNEvidenceStage = "embedded_verification"
	// DSNEvidenceStageEmbeddedUnsigned identifies a well-formed embedded
	// original without any DKIM2-Signature header field. Draft-09 Section 16
	// defines DKIM2 DSN handling only for DKIM2-signed originals, so such a
	// report cannot be authorized for signing. The wrapped cause remains
	// SigningErrorAuthorizationDenied; only a caller with an explicit
	// compatibility policy may let the report leave unsigned and unchanged.
	DSNEvidenceStageEmbeddedUnsigned DSNEvidenceStage = "embedded_unsigned"
	// DSNEvidenceStageEmbeddedClaims identifies invalid authenticated protocol claims.
	DSNEvidenceStageEmbeddedClaims DSNEvidenceStage = "embedded_claims"
	// DSNEvidenceStageDeliveryStatusLinkage identifies RFC 3464 recipient linkage failure.
	DSNEvidenceStageDeliveryStatusLinkage DSNEvidenceStage = "delivery_status_linkage"
	// DSNEvidenceStageOuterRecipientLinkage identifies outer recipient and mf= mismatch.
	DSNEvidenceStageOuterRecipientLinkage DSNEvidenceStage = "outer_recipient_linkage"
	// DSNEvidenceStageSigningDomain identifies a failed Section 16.2 signing
	// identity resolution: an unavailable or inconsistent local profile
	// source, or cancellation during resolution.
	DSNEvidenceStageSigningDomain DSNEvidenceStage = "signing_domain"
	// DSNEvidenceStageIdentityUnavailable identifies a report for which no
	// local delivery_status profile domain relaxed-matches an rt= address of
	// the highest DKIM2-Signature of the reported message (Draft-09 Sections
	// 7.1 item 4 and 16.2). The report cannot be DKIM2 signed; callers
	// deliver it unsigned. The wrapped cause is SigningErrorAuthorizationDenied.
	DSNEvidenceStageIdentityUnavailable DSNEvidenceStage = "identity_unavailable"
	// DSNEvidenceStageFromNotAuthentic identifies a report for which Section
	// 16.2 candidates with a local profile exist, but none makes the report's
	// own From header field Authentic (Draft-09 Sections 11 and 12.4). The
	// report cannot be DKIM2 signed; callers deliver it unsigned. The wrapped
	// cause is SigningErrorAuthorizationDenied.
	DSNEvidenceStageFromNotAuthentic DSNEvidenceStage = "from_not_authentic"
	// DSNEvidenceStageAuthorized identifies completed pre-policy evidence authorization.
	DSNEvidenceStageAuthorized DSNEvidenceStage = "authorized"
)

func DSNEvidenceStageOf

func DSNEvidenceStageOf(err error) DSNEvidenceStage

DSNEvidenceStageOf returns a closed stage only for a typed DSN evidence failure.

func (DSNEvidenceStage) Known

func (s DSNEvidenceStage) Known() bool

Known reports whether the stage belongs to the fixed DSN evidence pipeline.

type DSNIdentity

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

DSNIdentity is one canonical DNS domain that may be preferred as the signing identity of a delivery-status notification. It never becomes the signing domain on its own: Draft-09 Section 16.2 admits only domains that relaxed-match an rt= address of the reported message.

func NewDSNIdentity

func NewDSNIdentity(domain string) (DSNIdentity, error)

NewDSNIdentity validates and canonicalizes one preferred delivery-status signing identity.

func (DSNIdentity) Domain

func (i DSNIdentity) Domain() string

Domain returns the canonical DNS domain or an empty string.

func (DSNIdentity) Format

func (i DSNIdentity) Format(state fmt.State, _ rune)

Format routes every identity formatting form through the redacted representation.

func (DSNIdentity) GoString

func (i DSNIdentity) GoString() string

GoString returns the constant secret-safe identity representation.

func (DSNIdentity) String

func (DSNIdentity) String() string

String prevents identity formatting from becoming a caller-controlled diagnostic channel.

func (DSNIdentity) Valid

func (i DSNIdentity) Valid() bool

Valid reports whether the identity carries a canonical nonempty DNS domain.

type DSNProfileSource

type DSNProfileSource interface {
	DeliveryStatusProfile(ctx context.Context, domain string) (profile SigningProfile, found bool, err error)
}

DSNProfileSource resolves the local delivery_status signing profile of one candidate domain for ResolveDSNSigningIdentity. Implementations return found=false with a nil error only when the domain has no such profile; every unavailable, ambiguous, or otherwise undecided answer is an error.

type DSNPropagationError

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

DSNPropagationError preserves only a closed failure stage while exposing the caller context error or the public signing error through errors.Unwrap.

func (*DSNPropagationError) Error

func (e *DSNPropagationError) Error() string

Error returns a bounded diagnostic without message, envelope, or identity data.

func (*DSNPropagationError) Format

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

Format routes every formatting verb through the bounded diagnostic.

func (*DSNPropagationError) Stage

Stage returns the closed failure stage or the zero value.

func (*DSNPropagationError) Unwrap

func (e *DSNPropagationError) Unwrap() error

Unwrap preserves context and signing error classification.

type DSNPropagationEvidence

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

DSNPropagationEvidence is the immutable outcome of RebuildDSNForPropagation. It carries the received-DSN evaluation, the closed rebuild outcome, and, for a rebuilt report, the unsigned report, the signing domain proven by the removed completion signature, and the authenticated next-hop recipient. No accessor exposes the report bytes before signing.

func (DSNPropagationEvidence) EightBitMIMERequired

func (e DSNPropagationEvidence) EightBitMIMERequired() bool

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

func (DSNPropagationEvidence) Evaluation

Evaluation returns the received-DSN evaluation the rebuild was based on.

func (DSNPropagationEvidence) Format

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

Format routes every evidence formatting form through the redacted representation.

func (DSNPropagationEvidence) GoString

func (e DSNPropagationEvidence) GoString() string

GoString returns the constant secret-safe evidence representation.

func (DSNPropagationEvidence) MarshalJSON

func (DSNPropagationEvidence) MarshalJSON() ([]byte, error)

MarshalJSON rejects direct serialization outside generated response DTOs.

func (DSNPropagationEvidence) MarshalText

func (DSNPropagationEvidence) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of sealed evidence.

func (DSNPropagationEvidence) NextHopRecipient

func (e DSNPropagationEvidence) NextHopRecipient() []byte

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

func (DSNPropagationEvidence) OriginalForm

OriginalForm returns the representation of the rebuilt third part or the empty value.

func (DSNPropagationEvidence) Outcome

Outcome returns the closed rebuild outcome.

func (DSNPropagationEvidence) Rebuilt

func (e DSNPropagationEvidence) Rebuilt() bool

Rebuilt reports whether an unsigned report is ready for SignPropagatedDSN.

func (DSNPropagationEvidence) SMTPUTF8Required

func (e DSNPropagationEvidence) SMTPUTF8Required() bool

SMTPUTF8Required reports whether any header field of the rebuilt DSN, including the embedded original's header block and the To: field carrying the next-hop path, contains a non-ASCII byte; an 8-bit body alone does not set it.

func (DSNPropagationEvidence) SigningDomain

func (e DSNPropagationEvidence) SigningDomain() string

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

func (DSNPropagationEvidence) String

func (DSNPropagationEvidence) String() string

String returns a constant representation without sealed evidence facts.

func (DSNPropagationEvidence) Valid

func (e DSNPropagationEvidence) Valid() bool

Valid reports whether the evidence was issued by RebuildDSNForPropagation and is coherent.

type DSNPropagationOutcome

type DSNPropagationOutcome string

DSNPropagationOutcome is the closed result of one rebuild attempt.

const (
	// DSNPropagationRebuilt reports an unsigned Section 16.3 report ready for SignPropagatedDSN.
	DSNPropagationRebuilt DSNPropagationOutcome = "rebuilt"
	// DSNPropagationNotEligible reports an evaluation whose propagation projection is not eligible.
	DSNPropagationNotEligible DSNPropagationOutcome = "not_eligible"
	// DSNPropagationNotReconstructable reports a rebuild that could not prove or render the previous state.
	DSNPropagationNotReconstructable DSNPropagationOutcome = "not_reconstructable"
	// DSNPropagationTemporaryError reports a temporary key failure while verifying the previous hop.
	DSNPropagationTemporaryError DSNPropagationOutcome = "temperror"
)

func (DSNPropagationOutcome) Known

func (o DSNPropagationOutcome) Known() bool

Known reports whether the outcome belongs to the closed vocabulary.

type DSNPropagationRequest

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

DSNPropagationRequest carries cloned received-DSN bytes, the observed null reverse path and single forward path, the tenant-bound local authority, and the canonical reporting MTA name rendered into the rebuilt report.

func NewDSNPropagationRequest

func NewDSNPropagationRequest(raw, reversePath []byte, forwardPaths [][]byte, authority LocalAuthority, reportingMTA string) DSNPropagationRequest

NewDSNPropagationRequest snapshots one propagation request. The authority is mandatory because propagation without locality is meaningless.

func (DSNPropagationRequest) Format

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

Format routes every request formatting form through the redacted representation.

func (DSNPropagationRequest) GoString

func (r DSNPropagationRequest) GoString() string

GoString returns the constant secret-safe request representation.

func (DSNPropagationRequest) MarshalJSON

func (DSNPropagationRequest) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of message or envelope bytes.

func (DSNPropagationRequest) MarshalText

func (DSNPropagationRequest) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of message or envelope bytes.

func (DSNPropagationRequest) String

func (DSNPropagationRequest) String() string

String prevents raw DSN or envelope content from reaching diagnostics.

type DSNPropagationSigningRequest

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

DSNPropagationSigningRequest binds rebuilt evidence to a propagation route ticket, the delivery_status profile of the signing domain, and metadata.

func NewDSNPropagationSigningRequest

func NewDSNPropagationSigningRequest(evidence DSNPropagationEvidence, ticket RouteCopyTicket, profile SigningProfile, metadata SigningMetadata, transport SigningTransportForm) DSNPropagationSigningRequest

NewDSNPropagationSigningRequest constructs one propagation signing request without accepting caller-supplied message, envelope, or domain values.

func (DSNPropagationSigningRequest) Format

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

Format routes every signing-request formatting form through the redacted representation.

func (DSNPropagationSigningRequest) GoString

func (r DSNPropagationSigningRequest) GoString() string

GoString returns the constant secret-safe signing-request representation.

func (DSNPropagationSigningRequest) String

String prevents signing request formatting from exposing protected state.

type DSNPropagationStage

type DSNPropagationStage string

DSNPropagationStage identifies one closed content-free propagation stage.

const (
	// DSNPropagationStagePreflight identifies invalid signer or request state.
	DSNPropagationStagePreflight DSNPropagationStage = "preflight"
	// DSNPropagationStageEvaluation identifies the received-DSN evaluation.
	DSNPropagationStageEvaluation DSNPropagationStage = "evaluation"
	// DSNPropagationStageRebuild identifies the Section 16.3 rebuild.
	DSNPropagationStageRebuild DSNPropagationStage = "rebuild"
	// DSNPropagationStageSigning identifies the propagation signing operation.
	DSNPropagationStageSigning DSNPropagationStage = "signing"
)

func DSNPropagationStageOf

func DSNPropagationStageOf(err error) DSNPropagationStage

DSNPropagationStageOf returns the closed stage only for a typed propagation failure.

func (DSNPropagationStage) Known

func (s DSNPropagationStage) Known() bool

Known reports whether the stage belongs to the closed vocabulary.

type DSNSigningEvidence

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

DSNSigningEvidence is an opaque exact-input authorization produced only by EvaluateDSNForSigning and bound to one signing identity only by ResolveDSNSigningIdentity. It carries no raw-message accessor.

func (DSNSigningEvidence) Format

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

Format routes every evidence formatting form through the redacted representation.

func (DSNSigningEvidence) GoString

func (e DSNSigningEvidence) GoString() string

GoString returns the constant secret-safe evidence representation.

func (DSNSigningEvidence) Resolved

func (e DSNSigningEvidence) Resolved() bool

Resolved reports whether ResolveDSNSigningIdentity bound the evidence to a Section 16.2 signing identity with an Authentic report From.

func (DSNSigningEvidence) SigningDomain

func (e DSNSigningEvidence) SigningDomain() string

SigningDomain returns the canonical DSN signing identity chosen by ResolveDSNSigningIdentity, or an empty string before resolution.

func (DSNSigningEvidence) String

func (DSNSigningEvidence) String() string

String prevents DSN evidence from exposing raw message or recipient data.

func (DSNSigningEvidence) Valid

func (e DSNSigningEvidence) Valid() bool

Valid reports whether the opaque evidence was issued by the DSN boundary. It does not imply that a signing identity was resolved.

type DSNSigningEvidenceRequest

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

DSNSigningEvidenceRequest carries the exact outer evidence needed before a locally generated DSN can be authorized for signing, and an optional operator-preferred identity for the Section 16.2 candidate order.

func NewDSNSigningEvidenceRequest

func NewDSNSigningEvidenceRequest(outerRaw, outerReversePath []byte, outerForwardPaths [][]byte) DSNSigningEvidenceRequest

NewDSNSigningEvidenceRequest snapshots one DSN evidence request whose delivery-status fields must follow the strict RFC 3464 sequence.

func NewPostfixDSNSigningEvidenceRequest

func NewPostfixDSNSigningEvidenceRequest(outerRaw, outerReversePath []byte, outerForwardPaths [][]byte) DSNSigningEvidenceRequest

NewPostfixDSNSigningEvidenceRequest snapshots a DSN evidence request whose delivery-status field order may use the exact bounded form emitted by Postfix bounce(8).

Security precondition: trusted adapters must select this constructor only after independently proving that Postfix bounce(8) generated the DSN. It is not a parser hint for untrusted message input. Generic and non-Postfix paths must use NewDSNSigningEvidenceRequest.

func (DSNSigningEvidenceRequest) Format

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

Format routes every request formatting form through the redacted representation.

func (DSNSigningEvidenceRequest) GoString

func (r DSNSigningEvidenceRequest) GoString() string

GoString returns the constant secret-safe request representation.

func (DSNSigningEvidenceRequest) String

String prevents raw DSN or envelope content from reaching diagnostics.

func (DSNSigningEvidenceRequest) WithPreferredIdentity

func (r DSNSigningEvidenceRequest) WithPreferredIdentity(preferred DSNIdentity) DSNSigningEvidenceRequest

WithPreferredIdentity returns a copy of the request that prefers one operator-configured domain within its Section 16.2 linkage tier. The preferred domain is used only when it relaxed-matches an rt= address of the reported message; it is never a signing domain on its own. An invalid identity clears the preference.

type DSNSigningRequest

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

DSNSigningRequest binds one issued DSN evidence object to a purpose-specific route ticket and profile.

func NewDSNSigningRequest

func NewDSNSigningRequest(evidence DSNSigningEvidence, ticket RouteCopyTicket, profile SigningProfile, metadata SigningMetadata, transport SigningTransportForm) DSNSigningRequest

NewDSNSigningRequest constructs one exact DSN signing request without accepting caller-supplied message or envelope bytes.

func (DSNSigningRequest) Format

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

Format routes every signing-request formatting form through the redacted representation.

func (DSNSigningRequest) GoString

func (r DSNSigningRequest) GoString() string

GoString returns the constant secret-safe signing-request representation.

func (DSNSigningRequest) String

func (DSNSigningRequest) String() string

String prevents DSN signing request formatting from exposing protected state.

type DomainPolicyProvider

type DomainPolicyProvider interface {
	LookupDomainPolicy(context.Context, DomainPolicyQuery) (DomainPolicyStatus, error)
}

DomainPolicyProvider resolves Draft-09 Section 3.8 Domain Policy Records for the upward Authentic From match (Sections 7.1 item 3 and 11.1). It returns a known status with a nil error, the active caller context error, or a classified temporary or permanent provider error. A temporary error is TEMPERROR; a permanent error and every contract violation are treated as an invalid record (PERMERROR). Implementations must not place raw causes or DNS data in either return value. DNSPublicKeyProvider implements it with the same bounded resolver, cache, and transport as key lookups.

type DomainPolicyQuery

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

DomainPolicyQuery identifies the canonical A-label From domain whose Domain Policy Record is looked up at _domainkey.<domain> (Draft-09 Sections 3.8 and 18). The lookup uses the domain exactly, without any tree walk.

func NewDomainPolicyQuery

func NewDomainPolicyQuery(domain string) (DomainPolicyQuery, error)

NewDomainPolicyQuery constructs one canonical explicit Domain Policy Record query.

func (DomainPolicyQuery) Domain

func (q DomainPolicyQuery) Domain() string

Domain returns the canonical A-label domain that holds the record.

func (DomainPolicyQuery) Format

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

Format prevents formatting from traversing the queried domain.

func (DomainPolicyQuery) GoString

func (DomainPolicyQuery) GoString() string

GoString returns a constant representation without the queried domain.

func (DomainPolicyQuery) MarshalJSON

func (DomainPolicyQuery) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of the queried domain.

func (DomainPolicyQuery) MarshalText

func (DomainPolicyQuery) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of the queried domain.

func (DomainPolicyQuery) String

func (DomainPolicyQuery) String() string

String returns a constant representation without the queried domain.

type DomainPolicyStatus

type DomainPolicyStatus string

DomainPolicyStatus identifies one closed Draft-09 Section 3.8 Domain Policy Record outcome. A temporary DNS failure is not a status: providers report it as a classified temporary provider error.

const (
	// DomainPolicyAuthorized reports that subdomains may make From header
	// fields of the domain Authentic: no record (NXDOMAIN, NODATA, or no
	// record beginning with v=DKIM1), no f= tag, or no strict flag.
	DomainPolicyAuthorized DomainPolicyStatus = "authorized"
	// DomainPolicyStrict reports one record whose f= tag carries the
	// case-sensitive strict flag.
	DomainPolicyStrict DomainPolicyStatus = "strict"
	// DomainPolicyAmbiguous reports more than one record beginning with
	// v=DKIM1 (PERMERROR).
	DomainPolicyAmbiguous DomainPolicyStatus = "ambiguous"
	// DomainPolicyInvalid reports a record that begins with v=DKIM1 but is
	// not a valid tag-list, or a permanent lookup failure (PERMERROR).
	DomainPolicyInvalid DomainPolicyStatus = "invalid"
)

func (DomainPolicyStatus) Known

func (s DomainPolicyStatus) Known() bool

Known reports whether the status is in the closed provider vocabulary.

type Ed25519SigningCredential

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

Ed25519SigningCredential is one immutable Ed25519-SHA256 public credential paired with an opaque private-key handle.

func NewEd25519SigningCredential

func NewEd25519SigningCredential(selector string, publicKey ed25519.PublicKey, handle PrivateKeyHandle) (Ed25519SigningCredential, error)

NewEd25519SigningCredential validates and snapshots one Ed25519-SHA256 credential.

func (Ed25519SigningCredential) Format

func (c Ed25519SigningCredential) Format(state fmt.State, _ rune)

Format routes every credential formatting form through the redacted summary.

func (Ed25519SigningCredential) GoString

func (c Ed25519SigningCredential) GoString() string

GoString returns the constant secret-safe credential Go representation.

func (Ed25519SigningCredential) String

func (c Ed25519SigningCredential) String() string

String returns a constant secret-safe credential summary.

func (Ed25519SigningCredential) Valid

func (c Ed25519SigningCredential) Valid() bool

Valid reports whether the Ed25519 credential remains coherent.

type ExistingSigningRequest

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

ExistingSigningRequest is one immutable exact verified forwarding or revision request.

func NewExistingSigningRequest

func NewExistingSigningRequest(capability VerifiedRevisionInput, rawMessage, reversePath []byte, forwardPaths [][]byte, ticket RouteCopyTicket, profile SigningProfile, metadata SigningMetadata, transport SigningTransportForm, bodyPolicy BodyUnavailablePolicy, literalPolicy RecipeLiteralPolicy) ExistingSigningRequest

NewExistingSigningRequest snapshots one verified forwarding or revision request.

func (ExistingSigningRequest) Format

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

Format routes every request formatting form through the redacted summary.

func (ExistingSigningRequest) GoString

func (r ExistingSigningRequest) GoString() string

GoString returns the constant secret-safe request Go representation.

func (ExistingSigningRequest) String

func (r ExistingSigningRequest) String() string

String returns a constant secret-safe request summary.

type HeaderFromNullSenderClass

type HeaderFromNullSenderClass string

HeaderFromNullSenderClass is the closed eligibility outcome of a message offered for originator signing with a null reverse path under the explicit header_from policy.

const (
	// HeaderFromNullSenderEligible marks an automatic reply or disposition
	// notification whose single From mailbox yields the signing domain.
	HeaderFromNullSenderEligible HeaderFromNullSenderClass = "eligible"
	// HeaderFromNullSenderProtocolFields marks a message that already carries
	// a DKIM2-Signature or Message-Instance header field. A new originator
	// instance would conflict with that history, and such null-sender mail is
	// a signed delivery-status notification that belongs on the Section 16
	// path.
	HeaderFromNullSenderProtocolFields HeaderFromNullSenderClass = "dkim2_protocol_fields"
	// HeaderFromNullSenderDeliveryStatus marks an RFC 3464 delivery-status
	// notification, a top-level multipart/report with report-type
	// delivery-status. DSNs are signed only through the Section 16 route,
	// never as originator mail.
	HeaderFromNullSenderDeliveryStatus HeaderFromNullSenderClass = "delivery_status_report"
	// HeaderFromNullSenderContentTypeAmbiguous marks a message whose
	// top-level Content-Type is repeated, overlong, or unparsable, so it
	// cannot be proven not to be a delivery-status notification.
	HeaderFromNullSenderContentTypeAmbiguous HeaderFromNullSenderClass = "content_type_ambiguous"
	// HeaderFromNullSenderAuthorUnusable marks a message whose header section
	// is unparsable or whose From does not yield one canonical DNS domain.
	HeaderFromNullSenderAuthorUnusable HeaderFromNullSenderClass = "author_unusable"
)

func ClassifyHeaderFromNullSender

func ClassifyHeaderFromNullSender(rawMessage []byte) (string, HeaderFromNullSenderClass)

ClassifyHeaderFromNullSender decides whether a message with a null reverse path may be signed as originator mail under the header_from policy and, if so, returns the canonical From domain that binds d=. Draft-ietf-dkim-dkim2- spec Section 10.8 requires no d= match when mf= is "<>", so the signer binds d= to the message author instead of choosing it freely. Messages carrying DKIM2 protocol fields and RFC 3464 delivery-status notifications are never eligible; DSNs stay on the dedicated Section 16 route. Only the header section is parsed, so the body is never copied.

type HistoricalState

type HistoricalState string

HistoricalState identifies whether one historical verification dimension was evaluated.

const (
	// HistoricalStateNotEvaluated reports that the historical dimension was not evaluated.
	HistoricalStateNotEvaluated HistoricalState = "not_evaluated"
	// HistoricalStateComplete reports authenticated coverage through the origin.
	HistoricalStateComplete HistoricalState = "complete"
	// HistoricalStatePartial 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.
	HistoricalStatePartial HistoricalState = "partial"
)

func (HistoricalState) Known

func (s HistoricalState) Known() bool

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

type LocalAuthority

type LocalAuthority interface {
	LookupLocalAuthority(ctx context.Context, domain string) (LocalAuthorityStatus, error)
}

LocalAuthority answers whether a canonical DNS domain is a local authority domain. It carries no tenant value: the daemon binds the tenant when it constructs the implementation. The library validates domain syntax before every call and never passes a malformed d=. Any returned error is treated as a temporary datasource failure, never as not_local; a status outside the closed vocabulary is a contract violation and is also temporary.

type LocalAuthorityStatus

type LocalAuthorityStatus string

LocalAuthorityStatus is the closed answer of one local-authority lookup.

const (
	// LocalAuthorityLocal reports that the bound tenant holds an active signing profile of any use for the domain.
	LocalAuthorityLocal LocalAuthorityStatus = "local"
	// LocalAuthorityNotLocal reports that the domain is not a local authority domain for the bound tenant.
	LocalAuthorityNotLocal LocalAuthorityStatus = "not_local"
)

func (LocalAuthorityStatus) Known

func (s LocalAuthorityStatus) Known() bool

Known reports whether the status belongs to the closed vocabulary.

type MLDSA44SigningCredential

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

MLDSA44SigningCredential is one immutable pure ML-DSA-44 public credential paired with an opaque private-key handle.

func NewMLDSA44SigningCredential

func NewMLDSA44SigningCredential(selector string, publicKey *mldsa.PublicKey, handle PrivateKeyHandle) (MLDSA44SigningCredential, error)

NewMLDSA44SigningCredential validates and snapshots one mldsa44 credential. It fails closed when the cryptographic runtime cannot provide ML-DSA-44 (the FIPS 140-3 Go Cryptographic Module v1.0.0) or the key is not an ML-DSA-44 key.

func (MLDSA44SigningCredential) Format

func (c MLDSA44SigningCredential) Format(state fmt.State, _ rune)

Format routes every credential formatting form through the redacted summary.

func (MLDSA44SigningCredential) GoString

func (c MLDSA44SigningCredential) GoString() string

GoString returns the constant secret-safe credential Go representation.

func (MLDSA44SigningCredential) String

func (c MLDSA44SigningCredential) String() string

String returns a constant secret-safe credential summary.

func (MLDSA44SigningCredential) Valid

func (c MLDSA44SigningCredential) Valid() bool

Valid reports whether the mldsa44 credential remains coherent.

type ManagedReplayStore

type ManagedReplayStore interface {
	ReplayStore
	State() ReplayStoreState
	Close(context.Context) error
}

ManagedReplayStore adds bounded lifecycle control to a replay store.

type NetTXTTransport

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

NetTXTTransport adapts standard-library TXT lookup semantics without inventing TTL data.

func NewNetTXTTransport

func NewNetTXTTransport(resolver *net.Resolver) (*NetTXTTransport, error)

NewNetTXTTransport constructs a standard-library TXT transport.

func (NetTXTTransport) Format

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

Format prevents formatting from traversing the retained resolver.

func (NetTXTTransport) GoString

func (NetTXTTransport) GoString() string

GoString returns a constant representation without retained resolver state.

func (*NetTXTTransport) LookupTXT

func (t *NetTXTTransport) LookupTXT(ctx context.Context, absoluteName string) (TXTLookupResult, error)

LookupTXT preserves returned RR boundaries and reports zero TTL provenance.

func (NetTXTTransport) MarshalJSON

func (NetTXTTransport) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of retained resolver dependencies.

func (NetTXTTransport) MarshalText

func (NetTXTTransport) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of retained resolver dependencies.

func (NetTXTTransport) String

func (NetTXTTransport) String() string

String returns a constant representation without retained resolver state.

type NextDomainPublicationRequest

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

NextDomainPublicationRequest is one closed candidate future credential request.

func NewEd25519NextDomainPublicationRequest

func NewEd25519NextDomainPublicationRequest(domain string, credential Ed25519SigningCredential) NextDomainPublicationRequest

NewEd25519NextDomainPublicationRequest binds one Ed25519 future credential to its nd= domain.

func NewMLDSA44NextDomainPublicationRequest

func NewMLDSA44NextDomainPublicationRequest(domain string, credential MLDSA44SigningCredential) NextDomainPublicationRequest

NewMLDSA44NextDomainPublicationRequest binds one mldsa44 future credential to its nd= domain.

func NewRSANextDomainPublicationRequest

func NewRSANextDomainPublicationRequest(domain string, credential RSASigningCredential) NextDomainPublicationRequest

NewRSANextDomainPublicationRequest binds one RSA future credential to its nd= domain.

func (NextDomainPublicationRequest) Format

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

Format routes every publication-request formatting form through the redacted summary.

func (NextDomainPublicationRequest) GoString

func (r NextDomainPublicationRequest) GoString() string

GoString returns the constant secret-safe publication-request Go representation.

func (NextDomainPublicationRequest) String

String returns a constant secret-safe publication-request summary.

type NextDomainSigningRequest

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

NextDomainSigningRequest is one exact terminal nd= creation or continuation request.

func NewNextDomainSigningRequest

func NewNextDomainSigningRequest(
	capability VerifiedRevisionInput,
	rawMessage, reversePath []byte,
	forwardPaths [][]byte,
	ticket RouteCopyTicket,
	profile SigningProfile,
	metadata SigningMetadata,
	transport SigningTransportForm,
	bodyPolicy BodyUnavailablePolicy,
	literalPolicy RecipeLiteralPolicy,
	nextDomain string,
	published PublishedNextDomainCapability,
) NextDomainSigningRequest

NewNextDomainSigningRequest snapshots one exact terminal nd= request.

func (NextDomainSigningRequest) Format

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

Format routes every request formatting form through the redacted summary.

func (NextDomainSigningRequest) GoString

func (r NextDomainSigningRequest) GoString() string

GoString returns the constant secret-safe request Go representation.

func (NextDomainSigningRequest) String

func (r NextDomainSigningRequest) String() string

String returns a constant secret-safe request summary.

type NoopObservationSink

type NoopObservationSink struct{}

NoopObservationSink discards observations.

func (NoopObservationSink) Observe

Observe discards one bounded event.

type ObservationAlgorithm

type ObservationAlgorithm = internalobs.Algorithm

ObservationAlgorithm identifies one bounded algorithm family.

type ObservationBucket

type ObservationBucket = internalobs.Bucket

ObservationBucket identifies one bounded duration, size, or count class.

type ObservationCacheResult

type ObservationCacheResult = internalobs.CacheResult

ObservationCacheResult identifies one bounded cache result.

type ObservationErrorClass

type ObservationErrorClass = internalobs.ErrorClass

ObservationErrorClass identifies one bounded error class.

type ObservationEvent

type ObservationEvent = internalobs.Event

ObservationEvent is the immutable closed library observation value.

func NewObservationEvent

func NewObservationEvent(kind ObservationKind, operation ObservationOperation, result ObservationResult, reason ObservationReason, errorClass ObservationErrorClass, algorithm ObservationAlgorithm, cache ObservationCacheResult, duration, message, recipients, signatures, chain ObservationBucket) (ObservationEvent, bool)

NewObservationEvent validates and constructs one closed library event.

type ObservationKind

type ObservationKind = internalobs.Kind

ObservationKind identifies one library-owned observation point.

type ObservationOperation

type ObservationOperation = internalobs.Operation

ObservationOperation identifies one bounded operation.

type ObservationReason

type ObservationReason = internalobs.Reason

ObservationReason identifies one bounded reason.

type ObservationResult

type ObservationResult = internalobs.Result

ObservationResult identifies one bounded result.

type ObservationSink

type ObservationSink interface {
	Observe(context.Context, ObservationEvent)
}

ObservationSink receives immutable bounded observations.

type OriginatorSigningRequest

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

OriginatorSigningRequest is one immutable exact originator signing request.

func NewHeaderFromNullSenderSigningRequest

func NewHeaderFromNullSenderSigningRequest(rawMessage []byte, forwardPaths [][]byte, ticket RouteCopyTicket, profile SigningProfile, metadata SigningMetadata, transport SigningTransportForm) OriginatorSigningRequest

NewHeaderFromNullSenderSigningRequest snapshots one originator signing request for a message our own trusted systems emit with the null reverse path, such as an automatic reply or an RFC 8098 disposition notification. The signature carries mf=<> and the given recipients in rt=; SignOriginator admits it only when the profile domain equals HeaderFromDomain of the message. The caller owns the decision that the submission route is trusted.

func NewOriginatorSigningRequest

func NewOriginatorSigningRequest(rawMessage, reversePath []byte, forwardPaths [][]byte, ticket RouteCopyTicket, profile SigningProfile, metadata SigningMetadata, transport SigningTransportForm) OriginatorSigningRequest

NewOriginatorSigningRequest snapshots one originator signing request. A null reverse path is refused on this path; see NewHeaderFromNullSenderSigningRequest.

func (OriginatorSigningRequest) Format

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

Format routes every request formatting form through the redacted summary.

func (OriginatorSigningRequest) GoString

func (r OriginatorSigningRequest) GoString() string

GoString returns the constant secret-safe request Go representation.

func (OriginatorSigningRequest) String

func (r OriginatorSigningRequest) String() string

String returns a constant secret-safe request summary.

type OutOfBandAcceptanceSignedMessage

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

OutOfBandAcceptanceSignedMessage is a terminal nd= result with no generic byte escape.

func (OutOfBandAcceptanceSignedMessage) Facts

Facts returns bounded immutable operation facts.

func (OutOfBandAcceptanceSignedMessage) Format

func (m OutOfBandAcceptanceSignedMessage) Format(state fmt.State, _ rune)

Format routes every message formatting form through the redacted summary.

func (OutOfBandAcceptanceSignedMessage) GoString

GoString returns the constant secret-safe message Go representation.

func (OutOfBandAcceptanceSignedMessage) ReleaseForOutOfBandAcceptance

func (m OutOfBandAcceptanceSignedMessage) ReleaseForOutOfBandAcceptance(
	ctx context.Context,
	ticket RouteCopyTicket,
	reversePath []byte,
	forwardPaths [][]byte,
	receiverBinding, routeScope []byte,
) ([]byte, error)

ReleaseForOutOfBandAcceptance atomically releases bytes only for the exact sealed receiver, envelope, route, and ticket lineage.

func (OutOfBandAcceptanceSignedMessage) String

String returns a constant secret-safe message summary.

func (OutOfBandAcceptanceSignedMessage) Valid

Valid reports whether this is a coherent OOB-restricted terminal result.

type PolicyAction

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

PolicyAction stores one immutable local disposition.

func (PolicyAction) Kind

func (a PolicyAction) Kind() PolicyActionKind

Kind returns the closed action kind.

func (PolicyAction) Terminal

func (a PolicyAction) Terminal() bool

Terminal reports whether the action is terminal for DKIM2 policy.

func (PolicyAction) Valid

func (a PolicyAction) Valid() bool

Valid reports whether the action is initialized and known.

type PolicyActionKind

type PolicyActionKind string

PolicyActionKind identifies one closed disposition action.

const (
	// PolicyActionAccept matches an accept verdict.
	PolicyActionAccept PolicyActionKind = "accept"
	// PolicyActionReject matches a reject verdict.
	PolicyActionReject PolicyActionKind = "reject"
	// PolicyActionTempfail matches a temporary-failure verdict.
	PolicyActionTempfail PolicyActionKind = "tempfail"
	// PolicyActionContinue matches explicit non-terminal continuation.
	PolicyActionContinue PolicyActionKind = "continue"
)

func (PolicyActionKind) Known

func (k PolicyActionKind) Known() bool

Known reports whether the action kind belongs to the closed vocabulary.

type PolicyActionPlan

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

PolicyActionPlan stores exactly one immutable local disposition.

func (PolicyActionPlan) Actions

func (p PolicyActionPlan) Actions() []PolicyAction

Actions returns an independent copy containing exactly one action.

func (PolicyActionPlan) Valid

func (p PolicyActionPlan) Valid() bool

Valid reports whether the plan contains exactly one coherent disposition.

type PolicyDecision

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

PolicyDecision stores one immutable public local-policy outcome.

func EvaluateAuthenticationPolicy

func EvaluateAuthenticationPolicy(result AuthenticationResult, options ...PolicyOption) (PolicyDecision, error)

EvaluateAuthenticationPolicy evaluates local policy from the authoritative final Draft-09 result, extended by the received-DSN facts when WithReceivedDSNEvaluation attached them; a final state other than PASS keeps the outer policy and retains the facts as the outer-policy finding.

func EvaluatePolicy

func EvaluatePolicy(result VerifyResult, options ...PolicyOption) (PolicyDecision, error)

EvaluatePolicy evaluates only the sealed projection embedded by library verification, extended by the received-DSN facts when WithReceivedDSNEvaluation attached them.

Example

ExampleEvaluatePolicy demonstrates strict policy over a library-created passing result.

package main

import (
	"context"
	"crypto/rsa"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"math/big"
	"time"

	_ "embed"
	dkim2 "github.com/croessner/dkim2"
)

//go:embed testdata/vectors/draft-ietf-dkim-dkim2-spec-09/public-golden.json
var publicExampleCorpus []byte

type syntheticKeyProvider struct{ key *rsa.PublicKey }

// LookupPublicKey returns the frozen synthetic RSA public key.
func (p syntheticKeyProvider) LookupPublicKey(_ context.Context, query dkim2.PublicKeyQuery) (dkim2.PublicKeyResult, error) {
	if query.Algorithm() != dkim2.AlgorithmRSASHA256 {
		return dkim2.MissingPublicKey(query.Algorithm()), nil
	}
	return dkim2.FoundRSAPublicKey(p.key), nil
}

func main() {
	verifier, _ := dkim2.NewVerifier(syntheticKeyProvider{key: syntheticExampleRSAKey()}, dkim2.WithVerificationClock(func() time.Time { return time.Unix(1700000000, 0) }), dkim2.WithoutSubdomainFromAuthorization())
	result, _ := verifier.Verify(context.Background(), syntheticExampleRequest())
	decision, _ := dkim2.EvaluatePolicy(result)
	action := decision.ActionPlan().Actions()[0]
	fmt.Println(decision.VerificationState(), decision.Verdict(), decision.PrimaryReason())
	fmt.Println(action.Kind(), action.Terminal())

}

// syntheticExampleRequest decodes the frozen synthetic current-message fixture.
func syntheticExampleRequest() dkim2.VerifyRequest {
	return syntheticExampleRequestNamed("rsa_pass")
}

// syntheticExampleRequestNamed decodes one frozen synthetic current-message fixture.
func syntheticExampleRequestNamed(name string) dkim2.VerifyRequest {
	type vector struct {
		Raw     string   `json:"raw_base64"`
		Reverse string   `json:"reverse_path_base64"`
		Forward []string `json:"forward_paths_base64"`
	}
	var corpus struct {
		Vectors map[string]vector `json:"vectors"`
	}
	_ = json.Unmarshal(publicExampleCorpus, &corpus)
	fixture := corpus.Vectors[name]
	raw, _ := base64.StdEncoding.DecodeString(fixture.Raw)
	reverse, _ := base64.StdEncoding.DecodeString(fixture.Reverse)
	forward := make([][]byte, len(fixture.Forward))
	for index, encoded := range fixture.Forward {
		forward[index], _ = base64.StdEncoding.DecodeString(encoded)
	}
	return dkim2.NewVerifyRequest(raw, reverse, forward)
}

// syntheticExampleRSAKey reconstructs the frozen synthetic RSA public key.
func syntheticExampleRSAKey() *rsa.PublicKey {
	var corpus struct {
		RSAModulus  string `json:"rsa_modulus_base64"`
		RSAExponent int    `json:"rsa_exponent"`
	}
	_ = json.Unmarshal(publicExampleCorpus, &corpus)
	modulus, _ := base64.StdEncoding.DecodeString(corpus.RSAModulus)
	return &rsa.PublicKey{N: new(big.Int).SetBytes(modulus), E: corpus.RSAExponent}
}
Output:
PASS accept protocol_pass
accept true
Example (TestingUnavailable)

ExampleEvaluatePolicy_testingUnavailable demonstrates explicit non-terminal observation of unavailable protocol input.

package main

import (
	"context"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"time"

	_ "embed"
	dkim2 "github.com/croessner/dkim2"
)

//go:embed testdata/vectors/draft-ietf-dkim-dkim2-spec-09/public-golden.json
var publicExampleCorpus []byte

type syntheticMissingProvider struct{}

// LookupPublicKey returns deterministic key absence without network access.
func (syntheticMissingProvider) LookupPublicKey(_ context.Context, query dkim2.PublicKeyQuery) (dkim2.PublicKeyResult, error) {
	return dkim2.MissingPublicKey(query.Algorithm()), nil
}

func main() {
	verifier, _ := dkim2.NewVerifier(syntheticMissingProvider{}, dkim2.WithVerificationClock(func() time.Time { return time.Unix(1700000000, 0) }), dkim2.WithoutSubdomainFromAuthorization())
	result, _ := verifier.Verify(context.Background(), syntheticExampleRequestNamed("missing_protocol"))
	decision, _ := dkim2.EvaluatePolicy(result, dkim2.WithPolicyMode(dkim2.PolicyModeTesting))
	action := decision.ActionPlan().Actions()[0]
	fmt.Println(decision.VerificationState(), decision.Verdict(), decision.PrimaryReason())
	fmt.Println(action.Kind(), action.Terminal())

}

// syntheticExampleRequestNamed decodes one frozen synthetic current-message fixture.
func syntheticExampleRequestNamed(name string) dkim2.VerifyRequest {
	type vector struct {
		Raw     string   `json:"raw_base64"`
		Reverse string   `json:"reverse_path_base64"`
		Forward []string `json:"forward_paths_base64"`
	}
	var corpus struct {
		Vectors map[string]vector `json:"vectors"`
	}
	_ = json.Unmarshal(publicExampleCorpus, &corpus)
	fixture := corpus.Vectors[name]
	raw, _ := base64.StdEncoding.DecodeString(fixture.Raw)
	reverse, _ := base64.StdEncoding.DecodeString(fixture.Reverse)
	forward := make([][]byte, len(fixture.Forward))
	for index, encoded := range fixture.Forward {
		forward[index], _ = base64.StdEncoding.DecodeString(encoded)
	}
	return dkim2.NewVerifyRequest(raw, reverse, forward)
}
Output:
PERMERROR continue testing_mode_observe
continue false

func (PolicyDecision) ActionPlan

func (d PolicyDecision) ActionPlan() PolicyActionPlan

ActionPlan returns an immutable action plan whose collection accessor clones.

func (PolicyDecision) FeedbackIntent

func (d PolicyDecision) FeedbackIntent() PolicyFeedbackIntent

FeedbackIntent returns bounded authenticated feedback intent by value.

func (PolicyDecision) Findings

func (d PolicyDecision) Findings() []PolicyFinding

Findings returns an independent ordered copy of policy findings.

func (PolicyDecision) Format

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

Format prevents formatting from traversing sealed policy facts.

func (PolicyDecision) GoString

func (PolicyDecision) GoString() string

GoString returns a constant representation without sealed policy facts.

func (PolicyDecision) IsZero

func (d PolicyDecision) IsZero() bool

IsZero reports whether the decision carries no initialized policy state.

func (PolicyDecision) MarshalJSON

func (PolicyDecision) MarshalJSON() ([]byte, error)

MarshalJSON rejects direct serialization outside generated response DTOs.

func (PolicyDecision) MarshalText

func (PolicyDecision) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of sealed policy state.

func (PolicyDecision) Mode

func (d PolicyDecision) Mode() PolicyMode

Mode returns the explicit local policy mode.

func (PolicyDecision) PrimaryReason

func (d PolicyDecision) PrimaryReason() PolicyReason

PrimaryReason returns the exact deterministic policy reason.

func (PolicyDecision) String

func (PolicyDecision) String() string

String returns a constant representation without sealed policy facts.

func (PolicyDecision) Valid

func (d PolicyDecision) Valid() bool

Valid reports whether the public decision is initialized and internally coherent.

func (PolicyDecision) Verdict

func (d PolicyDecision) Verdict() PolicyVerdict

Verdict returns the local disposition separate from verification.

func (PolicyDecision) VerificationState

func (d PolicyDecision) VerificationState() ResultState

VerificationState returns the unchanged authoritative verification state.

type PolicyError

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

PolicyError stores cause-free and message-free policy failure metadata.

func (*PolicyError) Code

func (e *PolicyError) Code() PolicyErrorCode

Code returns the closed public policy error code.

func (*PolicyError) ConfiguredLimit

func (e *PolicyError) ConfiguredLimit() int

ConfiguredLimit returns the configured limit without input content.

func (*PolicyError) Error

func (e *PolicyError) Error() string

Error returns one stable diagnostic without verification or message content.

func (*PolicyError) Is

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

Is supports errors.Is matching by closed public error code.

func (*PolicyError) LimitName

func (e *PolicyError) LimitName() string

LimitName returns an allowlisted public policy limit name.

func (*PolicyError) ObservedCount

func (e *PolicyError) ObservedCount() int

ObservedCount returns the bounded observed count.

type PolicyErrorCode

type PolicyErrorCode string

PolicyErrorCode identifies one bounded public policy-evaluation failure.

const (
	// PolicyErrorInvalidOption reports an unknown, duplicate, zero, or widening option.
	PolicyErrorInvalidOption PolicyErrorCode = "invalid_option"
	// PolicyErrorInvalidInput reports absent or incoherent sealed verification provenance.
	PolicyErrorInvalidInput PolicyErrorCode = "invalid_input"
	// PolicyErrorLimitExceeded reports a configured public policy resource limit.
	PolicyErrorLimitExceeded PolicyErrorCode = "limit_exceeded"
	// PolicyErrorInternalContract reports an impossible internal policy result.
	PolicyErrorInternalContract PolicyErrorCode = "internal_contract"
)

func (PolicyErrorCode) Known

func (c PolicyErrorCode) Known() bool

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

type PolicyFeedbackIntent

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

PolicyFeedbackIntent stores bounded authenticated feedback routing intent.

func (PolicyFeedbackIntent) Format

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

Format prevents formatting from traversing relay identifiers.

func (PolicyFeedbackIntent) GoString

func (PolicyFeedbackIntent) GoString() string

GoString returns a constant representation without relay identifiers.

func (PolicyFeedbackIntent) HistoryCoverage

func (i PolicyFeedbackIntent) HistoryCoverage() PolicyHistoryCoverage

HistoryCoverage returns explicit feedback-history coverage.

func (PolicyFeedbackIntent) MarshalJSON

func (PolicyFeedbackIntent) MarshalJSON() ([]byte, error)

MarshalJSON rejects direct serialization outside generated response DTOs.

func (PolicyFeedbackIntent) MarshalText

func (PolicyFeedbackIntent) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of authenticated relay state.

func (PolicyFeedbackIntent) RelayRequired

func (i PolicyFeedbackIntent) RelayRequired() bool

RelayRequired reports whether an authenticated eligible relay exists.

func (PolicyFeedbackIntent) RelaySequence

func (i PolicyFeedbackIntent) RelaySequence() uint64

RelaySequence returns the highest eligible relay sequence or zero.

func (PolicyFeedbackIntent) Requested

func (i PolicyFeedbackIntent) Requested() bool

Requested reports whether authenticated feedback was requested.

func (PolicyFeedbackIntent) String

func (PolicyFeedbackIntent) String() string

String returns a constant representation without relay identifiers.

func (PolicyFeedbackIntent) Valid

func (i PolicyFeedbackIntent) Valid() bool

Valid reports whether feedback intent is coherent and initialized.

type PolicyFinding

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

PolicyFinding records one immutable bounded policy fact.

func (PolicyFinding) Format

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

Format prevents formatting from traversing sequence identifiers.

func (PolicyFinding) GoString

func (PolicyFinding) GoString() string

GoString returns a constant representation without sequence identifiers.

func (PolicyFinding) MarshalJSON

func (PolicyFinding) MarshalJSON() ([]byte, error)

MarshalJSON rejects direct serialization outside generated response DTOs.

func (PolicyFinding) MarshalText

func (PolicyFinding) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of authenticated sequence state.

func (PolicyFinding) Reason

func (f PolicyFinding) Reason() PolicyReason

Reason returns the closed finding reason.

func (PolicyFinding) Sequence

func (f PolicyFinding) Sequence() (uint64, bool)

Sequence returns an optional authenticated sequence and presence flag.

func (PolicyFinding) Severity

func (f PolicyFinding) Severity() PolicyFindingSeverity

Severity returns the frozen severity for the reason.

func (PolicyFinding) String

func (PolicyFinding) String() string

String returns a constant representation without sequence identifiers.

func (PolicyFinding) Valid

func (f PolicyFinding) Valid() bool

Valid reports whether the finding came from a coherent internal decision.

type PolicyFindingSeverity

type PolicyFindingSeverity string

PolicyFindingSeverity identifies one bounded finding severity.

const (
	// PolicySeverityInfo reports informational authenticated state.
	PolicySeverityInfo PolicyFindingSeverity = "info"
	// PolicySeverityWarning reports a non-terminal concern or override.
	PolicySeverityWarning PolicyFindingSeverity = "warning"
	// PolicySeverityPermanent reports a permanent failure or violation.
	PolicySeverityPermanent PolicyFindingSeverity = "permanent"
	// PolicySeverityTemporary reports a retryable verification failure.
	PolicySeverityTemporary PolicyFindingSeverity = "temporary"
)

func (PolicyFindingSeverity) Known

func (s PolicyFindingSeverity) Known() bool

Known reports whether the severity belongs to the closed vocabulary.

type PolicyHistoryCoverage

type PolicyHistoryCoverage string

PolicyHistoryCoverage identifies authenticated policy-history coverage.

const (
	// PolicyHistoryNotEvaluated reports deliberately unevaluated history.
	PolicyHistoryNotEvaluated PolicyHistoryCoverage = "not_evaluated"
	// PolicyHistoryComplete reports exact contiguous authenticated history.
	PolicyHistoryComplete PolicyHistoryCoverage = "complete"
	// PolicyHistoryIndeterminate reports explicitly partial authenticated history.
	PolicyHistoryIndeterminate PolicyHistoryCoverage = "indeterminate"
)

func (PolicyHistoryCoverage) Known

func (h PolicyHistoryCoverage) Known() bool

Known reports whether coverage belongs to the closed vocabulary.

type PolicyMode

type PolicyMode string

PolicyMode identifies one explicit local policy posture.

const (
	// PolicyModeStrict enforces verification failure and proven violations.
	PolicyModeStrict PolicyMode = "strict"
	// PolicyModePermissive accepts permanent verification failures with findings.
	PolicyModePermissive PolicyMode = "permissive"
	// PolicyModeTesting observes outcomes without a terminal DKIM2 disposition.
	PolicyModeTesting PolicyMode = "testing"
)

func (PolicyMode) Known

func (m PolicyMode) Known() bool

Known reports whether the mode belongs to the closed vocabulary.

type PolicyOption

type PolicyOption func(*policyConfig) error

PolicyOption narrows one public policy setting exactly once.

func WithPolicyMaxAuthenticatedHops

func WithPolicyMaxAuthenticatedHops(limit int) PolicyOption

WithPolicyMaxAuthenticatedHops narrows the authenticated-hop evaluation limit.

func WithPolicyMaxFindings

func WithPolicyMaxFindings(limit int) PolicyOption

WithPolicyMaxFindings narrows the retained-finding evaluation limit.

func WithPolicyMode

func WithPolicyMode(mode PolicyMode) PolicyOption

WithPolicyMode selects one explicit local policy posture.

func WithReceivedDSNEvaluation

func WithReceivedDSNEvaluation(evaluation ReceivedDSNEvaluation) PolicyOption

WithReceivedDSNEvaluation attaches the read-only received-DSN evaluation of the same inbound message, so that one evaluation yields one PolicyDecision covering the outer verification and the received-DSN mapping table. The row selected in stage order is recorded as the last finding: reject, tempfail, and continue rows replace the outer verdict, accept rows keep it, and an outer verification or final replay state other than PASS keeps the outer policy. The caller must pass the evaluation produced for the message whose result is evaluated; the evaluation carries no identifiers, so the library cannot verify that binding. An invalid evaluation or a second use of the option is rejected.

type PolicyReason

type PolicyReason string

PolicyReason identifies one closed policy decision or finding reason.

const (
	// PolicyReasonInvalidInput reports invalid policy input.
	PolicyReasonInvalidInput PolicyReason = "invalid_input"
	// PolicyReasonLimitExceeded reports a policy resource limit.
	PolicyReasonLimitExceeded PolicyReason = "limit_exceeded"
	// PolicyReasonInternalContract reports impossible internal state.
	PolicyReasonInternalContract PolicyReason = "internal_contract"
	// PolicyReasonProtocolPass reports authoritative verification success.
	PolicyReasonProtocolPass PolicyReason = "protocol_pass"
	// PolicyReasonProtocolFail reports authoritative integrity failure.
	PolicyReasonProtocolFail PolicyReason = "protocol_fail"
	// PolicyReasonProtocolPermerror reports authoritative permanent error.
	PolicyReasonProtocolPermerror PolicyReason = "protocol_permerror"
	// PolicyReasonProtocolTemperror reports authoritative temporary error.
	PolicyReasonProtocolTemperror PolicyReason = "protocol_temperror"
	// PolicyReasonPermissiveOverride reports an explicit permissive override.
	PolicyReasonPermissiveOverride PolicyReason = "permissive_override"
	// PolicyReasonTestingModeObserve reports explicit local observation mode.
	PolicyReasonTestingModeObserve PolicyReason = "testing_mode_observe"
	// PolicyReasonFeedbackRequested reports an authenticated feedback request.
	PolicyReasonFeedbackRequested PolicyReason = "feedback_requested"
	// PolicyReasonFeedbackRelaySelected reports the selected authenticated relay.
	PolicyReasonFeedbackRelaySelected PolicyReason = "feedback_relay_selected"
	// PolicyReasonFeedHereInert reports a relay flag without causal consent.
	PolicyReasonFeedHereInert PolicyReason = "feedhere_inert"
	// PolicyReasonExplodedReported reports an authenticated explosion flag.
	PolicyReasonExplodedReported PolicyReason = "exploded_reported"
	// PolicyReasonReceivedDSNOuterPolicy reports that the outer verification is not PASS, so the outer policy applies unchanged to a received DSN.
	PolicyReasonReceivedDSNOuterPolicy PolicyReason = "received_dsn_outer_policy"
	// PolicyReasonReceivedDSNStructureInvalid reports a received DSN whose structure member is not valid.
	PolicyReasonReceivedDSNStructureInvalid PolicyReason = "received_dsn_structure_invalid"
	// PolicyReasonReceivedDSNEmbeddedUnverified reports permanent verification failure of the embedded original.
	PolicyReasonReceivedDSNEmbeddedUnverified PolicyReason = "received_dsn_embedded_unverified"
	// PolicyReasonReceivedDSNEmbeddedAbsent reports an unsigned embedded original outside Section 16.4.
	PolicyReasonReceivedDSNEmbeddedAbsent PolicyReason = "received_dsn_embedded_absent"
	// PolicyReasonReceivedDSNTemporaryFailure reports a temporary key or datasource failure during received-DSN evaluation.
	PolicyReasonReceivedDSNTemporaryFailure PolicyReason = "received_dsn_temporary_failure"
	// PolicyReasonReceivedDSNTenantUnavailable reports that locality was not evaluated because no tenant was available.
	PolicyReasonReceivedDSNTenantUnavailable PolicyReason = "received_dsn_tenant_unavailable"
	// PolicyReasonReceivedDSNIdentityMismatch reports a local-hop mismatch or a misaligned outer signer.
	PolicyReasonReceivedDSNIdentityMismatch PolicyReason = "received_dsn_identity_mismatch"
	// PolicyReasonReceivedDSNNotLocal reports a received DSN in transit through a relay.
	PolicyReasonReceivedDSNNotLocal PolicyReason = "received_dsn_not_local"
	// PolicyReasonReceivedDSNRecipientUnlinked reports that no recipient group links to the completion rt= path.
	PolicyReasonReceivedDSNRecipientUnlinked PolicyReason = "received_dsn_recipient_unlinked"
	// PolicyReasonReceivedDSNLinked reports a fully linked received DSN with any propagation value.
	PolicyReasonReceivedDSNLinked PolicyReason = "received_dsn_linked"
)

func (PolicyReason) Known

func (r PolicyReason) Known() bool

Known reports whether the reason belongs to the frozen public vocabulary.

type PolicyVerdict

type PolicyVerdict string

PolicyVerdict identifies one local policy disposition separate from verification.

const (
	// PolicyVerdictAccept authorizes normal continuation.
	PolicyVerdictAccept PolicyVerdict = "accept"
	// PolicyVerdictReject reports permanent local-policy rejection.
	PolicyVerdictReject PolicyVerdict = "reject"
	// PolicyVerdictTempfail reports retryable local deferral.
	PolicyVerdictTempfail PolicyVerdict = "tempfail"
	// PolicyVerdictContinue withholds a terminal DKIM2 decision.
	PolicyVerdictContinue PolicyVerdict = "continue"
)

func (PolicyVerdict) Known

func (v PolicyVerdict) Known() bool

Known reports whether the verdict belongs to the closed vocabulary.

type PrivateKeyHandle

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

PrivateKeyHandle is an opaque immutable reference understood only by a caller-provided PrivateKeySigner.

func NewPrivateKeyHandle

func NewPrivateKeyHandle(identity []byte) (PrivateKeyHandle, error)

NewPrivateKeyHandle constructs an opaque handle from provider-owned identity bytes without retaining or exposing those bytes.

func (PrivateKeyHandle) Format

func (h PrivateKeyHandle) Format(state fmt.State, _ rune)

Format routes every handle formatting form through the redacted summary.

func (PrivateKeyHandle) GoString

func (h PrivateKeyHandle) GoString() string

GoString returns the constant secret-safe handle Go representation.

func (PrivateKeyHandle) String

func (h PrivateKeyHandle) String() string

String returns a constant secret-safe handle summary.

func (PrivateKeyHandle) Valid

func (h PrivateKeyHandle) Valid() bool

Valid reports whether the handle was constructed from a nonempty identity.

type PrivateKeySignRequest

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

PrivateKeySignRequest carries only one closed algorithm and the message representative of the Section 12.8 signature input that algorithm signs: the 32-byte SHA-256 digest for rsa-sha256 and ed25519-sha256, and the complete Section 12.8 input bytes for mldsa44, which is pure ML-DSA (Draft-09 Section 3.4: the field values are not hashed first).

func (PrivateKeySignRequest) Algorithm

func (r PrivateKeySignRequest) Algorithm() Algorithm

Algorithm returns the requested signing algorithm.

func (PrivateKeySignRequest) Digest deprecated

func (r PrivateKeySignRequest) Digest() []byte

Digest returns a copy of the 32-byte SHA-256 signature-input digest for rsa-sha256 and ed25519-sha256. It returns nil for mldsa44, which signs the complete input; use MessageRepresentative for every algorithm.

Deprecated: use MessageRepresentative, which covers every algorithm.

func (PrivateKeySignRequest) Format

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

Format routes every request formatting form through the redacted summary.

func (PrivateKeySignRequest) GoString

func (r PrivateKeySignRequest) GoString() string

GoString returns the constant secret-safe request Go representation.

func (PrivateKeySignRequest) MessageRepresentative

func (r PrivateKeySignRequest) MessageRepresentative() []byte

MessageRepresentative returns a copy of the exact bytes the algorithm's signing primitive consumes. A signer passes it unchanged to rsa.SignPKCS1v15 with crypto.SHA256, to ed25519.Sign, or, for mldsa44, to the hedged crypto/mldsa PrivateKey.Sign with MLDSA44SignerOptions (context string "DKIM2").

func (PrivateKeySignRequest) String

func (r PrivateKeySignRequest) String() string

String returns a constant secret-safe request summary.

func (PrivateKeySignRequest) Valid

func (r PrivateKeySignRequest) Valid() bool

Valid reports whether the request was created by the signing facade.

type PrivateKeySignResult

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

PrivateKeySignResult is the closed immutable result of one digest-signing callback.

func NewPrivateKeySignResult

func NewPrivateKeySignResult(signature []byte) PrivateKeySignResult

NewPrivateKeySignResult constructs a detached successful callback result.

func (PrivateKeySignResult) Format

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

Format routes every result formatting form through the redacted summary.

func (PrivateKeySignResult) GoString

func (r PrivateKeySignResult) GoString() string

GoString returns the constant secret-safe result Go representation.

func (PrivateKeySignResult) IsZero

func (r PrivateKeySignResult) IsZero() bool

IsZero reports whether no declared callback result is present.

func (PrivateKeySignResult) String

func (r PrivateKeySignResult) String() string

String returns a constant secret-safe result summary.

type PrivateKeySigner

type PrivateKeySigner interface {
	SignDigest(context.Context, PrivateKeyHandle, PrivateKeySignRequest) (PrivateKeySignResult, error)
}

PrivateKeySigner signs one message representative through an opaque handle. The method keeps its historical name; for mldsa44 the representative is the complete Section 12.8 input, not a digest.

type PropagatedDSN

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

PropagatedDSN is the signed propagated report with its bounded transport facts.

func (PropagatedDSN) Bytes

func (p PropagatedDSN) Bytes() []byte

Bytes returns a detached copy of the complete signed DSN or nil.

func (PropagatedDSN) EightBitMIMERequired

func (p PropagatedDSN) EightBitMIMERequired() bool

EightBitMIMERequired reports whether the re-injection needs the 8BITMIME extension because the embedded original's body carries a non-ASCII byte.

func (PropagatedDSN) Facts

Facts returns the bounded signed-message facts.

func (PropagatedDSN) Format

func (p PropagatedDSN) Format(state fmt.State, _ rune)

Format routes every formatting form through the redacted representation.

func (PropagatedDSN) GoString

func (p PropagatedDSN) GoString() string

GoString returns the constant secret-safe representation.

func (PropagatedDSN) MarshalJSON

func (PropagatedDSN) MarshalJSON() ([]byte, error)

MarshalJSON rejects direct serialization outside generated response DTOs.

func (PropagatedDSN) MarshalText

func (PropagatedDSN) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of message bytes.

func (PropagatedDSN) NextHopRecipient

func (p PropagatedDSN) NextHopRecipient() []byte

NextHopRecipient returns a detached copy of the exact bracketed SMTP forward path or nil.

func (PropagatedDSN) SMTPUTF8Required

func (p PropagatedDSN) SMTPUTF8Required() bool

SMTPUTF8Required reports whether the re-injection needs the SMTPUTF8 extension because a header field of the signed DSN carries a non-ASCII byte.

func (PropagatedDSN) SigningDomain

func (p PropagatedDSN) SigningDomain() string

SigningDomain returns the canonical domain that signed the report or an empty string.

func (PropagatedDSN) String

func (PropagatedDSN) String() string

String returns a constant representation without message bytes.

func (PropagatedDSN) Valid

func (p PropagatedDSN) Valid() bool

Valid reports whether the value was produced by SignPropagatedDSN.

type ProviderErrorClass

type ProviderErrorClass string

ProviderErrorClass identifies an explicitly classified provider failure.

const (
	// ProviderErrorClassTemporary identifies a provider failure that may succeed later.
	ProviderErrorClassTemporary ProviderErrorClass = "temporary"
	// ProviderErrorClassPermanent identifies an unrecoverable provider failure.
	ProviderErrorClassPermanent ProviderErrorClass = "permanent"
)

func ProviderErrorClassOf

func ProviderErrorClassOf(err error) ProviderErrorClass

ProviderErrorClassOf returns a known typed provider class or the zero value.

func (ProviderErrorClass) Known

func (c ProviderErrorClass) Known() bool

Known reports whether the class is in the closed provider-error vocabulary.

type PublicKeyProvider

type PublicKeyProvider interface {
	LookupPublicKey(context.Context, PublicKeyQuery) (PublicKeyResult, error)
}

PublicKeyProvider resolves static public-key intent without exposing provider-specific models.

The legal return matrix is closed: a zero result may accompany either the active caller context error or a classified temporary or permanent provider error; a declared found, missing, invalid, or ambiguous result must accompany a nil error. Revoked, unsupported-key-type, and algorithm-mismatch results also carry no material and accompany nil error. Every other pair is a provider contract violation. Implementations must not place raw causes, provider metadata, private keys, or signer objects in either return value. A provider-owned deadline while the caller context is live is valid only when classified temporary; permanent or unclassified deadline errors are provider contract violations.

type PublicKeyQuery

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

PublicKeyQuery contains only canonical values needed for injected key lookup.

func NewPublicKeyQuery

func NewPublicKeyQuery(
	signingDomain string,
	selector string,
	algorithm Algorithm,
) (PublicKeyQuery, error)

NewPublicKeyQuery constructs one canonical explicit DNS lookup query.

func (PublicKeyQuery) Algorithm

func (q PublicKeyQuery) Algorithm() Algorithm

Algorithm returns the bounded signature algorithm required for lookup.

func (PublicKeyQuery) Format

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

Format prevents formatting from traversing DNS owner identifiers.

func (PublicKeyQuery) GoString

func (PublicKeyQuery) GoString() string

GoString returns a constant representation without DNS owner identifiers.

func (PublicKeyQuery) MarshalJSON

func (PublicKeyQuery) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of DNS query identifiers.

func (PublicKeyQuery) MarshalText

func (PublicKeyQuery) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of DNS query identifiers.

func (PublicKeyQuery) Selector

func (q PublicKeyQuery) Selector() string

Selector returns the canonical selector required for lookup.

func (PublicKeyQuery) SigningDomain

func (q PublicKeyQuery) SigningDomain() string

SigningDomain returns the canonical signing domain required for lookup.

func (PublicKeyQuery) String

func (PublicKeyQuery) String() string

String returns a constant representation without DNS owner identifiers.

type PublicKeyResult

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

PublicKeyResult is a closed immutable provider outcome with explicit public-key variants.

func AlgorithmMismatchPublicKey

func AlgorithmMismatchPublicKey(algorithm Algorithm) PublicKeyResult

AlgorithmMismatchPublicKey constructs a requested-algorithm mismatch result without material.

func AmbiguousPublicKey

func AmbiguousPublicKey(algorithm Algorithm) PublicKeyResult

AmbiguousPublicKey constructs an ambiguous-key result without key material.

func FoundEd25519PublicKey

func FoundEd25519PublicKey(key ed25519.PublicKey) PublicKeyResult

FoundEd25519PublicKey constructs a found Ed25519-SHA256 result with cloned public material.

func FoundMLDSA44PublicKey

func FoundMLDSA44PublicKey(raw []byte) PublicKeyResult

FoundMLDSA44PublicKey constructs a found mldsa44 result from the raw 1312-octet FIPS 204 ML-DSA-44 public-key encoding carried in DNS p=. The material is cloned and structurally validated; any other length, an encoding crypto/mldsa rejects, or a runtime without ML-DSA-44 support (the FIPS 140-3 Go Cryptographic Module v1.0.0) fails closed as an invalid-key result.

func FoundRSAPublicKey

func FoundRSAPublicKey(key *rsa.PublicKey) PublicKeyResult

FoundRSAPublicKey constructs a found RSA-SHA256 result with cloned public material.

func InvalidPublicKey

func InvalidPublicKey(algorithm Algorithm) PublicKeyResult

InvalidPublicKey constructs an invalid-key result without key material.

func MissingPublicKey

func MissingPublicKey(algorithm Algorithm) PublicKeyResult

MissingPublicKey constructs a key-not-found result without key material.

func RevokedPublicKey

func RevokedPublicKey(algorithm Algorithm) PublicKeyResult

RevokedPublicKey constructs an explicitly revoked result without key material.

func UnsupportedKeyTypePublicKey

func UnsupportedKeyTypePublicKey(algorithm Algorithm) PublicKeyResult

UnsupportedKeyTypePublicKey constructs an unsupported DNS key-type result without material.

func (PublicKeyResult) Algorithm

func (r PublicKeyResult) Algorithm() Algorithm

Algorithm returns the declared bounded algorithm family.

func (PublicKeyResult) Ed25519PublicKey

func (r PublicKeyResult) Ed25519PublicKey() (ed25519.PublicKey, bool)

Ed25519PublicKey returns an independent Ed25519 public-key copy when that variant is present.

func (PublicKeyResult) Format

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

Format prevents formatting from traversing public-key material.

func (PublicKeyResult) GoString

func (PublicKeyResult) GoString() string

GoString returns a constant representation without public-key material.

func (PublicKeyResult) IsZero

func (r PublicKeyResult) IsZero() bool

IsZero reports whether no declared provider outcome is present.

func (PublicKeyResult) MLDSA44PublicKey

func (r PublicKeyResult) MLDSA44PublicKey() ([]byte, bool)

MLDSA44PublicKey returns an independent copy of the raw 1312-octet ML-DSA-44 public-key encoding when that variant is present.

func (PublicKeyResult) MarshalJSON

func (PublicKeyResult) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of provider result material.

func (PublicKeyResult) MarshalText

func (PublicKeyResult) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of provider result material.

func (PublicKeyResult) PublicKeySPKI

func (r PublicKeyResult) PublicKeySPKI() ([]byte, bool)

PublicKeySPKI returns the canonical SubjectPublicKeyInfo DER of the found public key of any variant, so publication tooling can compare DNS results with stored credentials through one encoder.

func (PublicKeyResult) RSAPublicKey

func (r PublicKeyResult) RSAPublicKey() (*rsa.PublicKey, bool)

RSAPublicKey returns an independent RSA public-key copy when that variant is present.

func (PublicKeyResult) Status

func (r PublicKeyResult) Status() PublicKeyStatus

Status returns the declared closed lookup outcome.

func (PublicKeyResult) String

func (PublicKeyResult) String() string

String returns a constant representation without public-key material.

type PublicKeyStatus

type PublicKeyStatus string

PublicKeyStatus identifies a closed key lookup outcome.

const (
	// PublicKeyStatusFound reports exactly one declared public key.
	PublicKeyStatusFound PublicKeyStatus = "found"
	// PublicKeyStatusMissing reports no matching public key.
	PublicKeyStatusMissing PublicKeyStatus = "missing"
	// PublicKeyStatusInvalid reports provider-detected invalid public key state.
	PublicKeyStatusInvalid PublicKeyStatus = "invalid"
	// PublicKeyStatusAmbiguous reports more than one matching public key.
	PublicKeyStatusAmbiguous PublicKeyStatus = "ambiguous"
	// PublicKeyStatusRevoked reports an explicitly empty DNS public key.
	PublicKeyStatusRevoked PublicKeyStatus = "revoked"
	// PublicKeyStatusUnsupportedKeyType reports an unrecognized DNS key type.
	PublicKeyStatusUnsupportedKeyType PublicKeyStatus = "unsupported_key_type"
	// PublicKeyStatusAlgorithmMismatch reports disagreement between requested algorithm and DNS key type.
	PublicKeyStatusAlgorithmMismatch PublicKeyStatus = "algorithm_mismatch"
)

func (PublicKeyStatus) Known

func (s PublicKeyStatus) Known() bool

Known reports whether the status is in the closed provider vocabulary.

type PublishedNextDomainCapability

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

PublishedNextDomainCapability is opaque fresh single-use publication evidence.

func (PublishedNextDomainCapability) Format

func (c PublishedNextDomainCapability) Format(state fmt.State, _ rune)

Format routes every publication-capability formatting form through the redacted summary.

func (PublishedNextDomainCapability) GoString

GoString returns the constant secret-safe publication-capability Go representation.

func (PublishedNextDomainCapability) String

String returns a constant secret-safe publication-capability summary.

func (PublishedNextDomainCapability) Valid

Valid reports only whether the capability has an issued coherent shape.

type RSASigningCredential

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

RSASigningCredential is one immutable RSA-SHA256 public credential paired with an opaque private-key handle.

func NewRSASigningCredential

func NewRSASigningCredential(selector string, publicKey *rsa.PublicKey, handle PrivateKeyHandle) (RSASigningCredential, error)

NewRSASigningCredential validates and snapshots one RSA-SHA256 credential.

func (RSASigningCredential) Format

func (c RSASigningCredential) Format(state fmt.State, _ rune)

Format routes every credential formatting form through the redacted summary.

func (RSASigningCredential) GoString

func (c RSASigningCredential) GoString() string

GoString returns the constant secret-safe credential Go representation.

func (RSASigningCredential) String

func (c RSASigningCredential) String() string

String returns a constant secret-safe credential summary.

func (RSASigningCredential) Valid

func (c RSASigningCredential) Valid() bool

Valid reports whether the RSA credential remains coherent.

type ReasonCode

type ReasonCode string

ReasonCode identifies a bounded verification reason without retaining raw causes or input.

const (
	// AuthenticationReasonDuplicateMessageWithoutExploded reports an unexpected
	// replay. It is a local delivery-policy rejection (Draft-09 Section 15.1);
	// the underlying VerifyResult still reports the DKIM2 validity PASS.
	AuthenticationReasonDuplicateMessageWithoutExploded ReasonCode = "duplicate_message_without_exploded"
	// AuthenticationReasonReplayIndeterminate reports unavailable or ambiguous replay storage.
	AuthenticationReasonReplayIndeterminate ReasonCode = "replay_indeterminate"
	// AuthenticationReasonReplayEvidenceUnavailable reports a missing
	// authenticated m=1 hash declaration identity.
	AuthenticationReasonReplayEvidenceUnavailable ReasonCode = "replay_evidence_unavailable"
)
const (
	// ReasonNone reports no failure reason for a successful fact.
	ReasonNone ReasonCode = "none"
	// ReasonInvalidRequest reports invalid public request state.
	ReasonInvalidRequest ReasonCode = "invalid_request"
	// ReasonLimitExceeded reports a configured resource limit violation.
	ReasonLimitExceeded ReasonCode = "limit_exceeded"
	// ReasonMalformedMessage reports malformed RFC 5322 input.
	ReasonMalformedMessage ReasonCode = "malformed_message"
	// ReasonMalformedProtocol reports malformed DKIM2 protocol input.
	ReasonMalformedProtocol ReasonCode = "malformed_protocol"
	// ReasonDuplicateHashAlgorithm reports any repeated h= algorithm name.
	ReasonDuplicateHashAlgorithm ReasonCode = "duplicate_hash_algorithm"
	// ReasonInvalidRecipeJSON reports authenticated recipe text that is not
	// valid JSON or not a JSON object.
	ReasonInvalidRecipeJSON ReasonCode = "invalid_recipe_json"
	// ReasonInvalidRecipe reports valid authenticated recipe JSON whose
	// schema, steps, or application are invalid (Draft-09 Section 14.2).
	// Diagnostics never carry the recipe step text.
	ReasonInvalidRecipe ReasonCode = "invalid_recipe"
	// ReasonFromNotAuthentic reports a From header field state that is not
	// Authentic for its responsible signature (Draft-09 Section 14.8).
	ReasonFromNotAuthentic ReasonCode = "from_not_authentic"
	// ReasonFromSubdomainForbidden reports a From header field state that
	// only a subdomain d= makes Authentic while the From domain's Domain
	// Policy Record carries the strict flag (Draft-09 Sections 3.8, 11.1, and
	// 14.8; FAIL).
	ReasonFromSubdomainForbidden ReasonCode = "from_subdomain_forbidden"
	// ReasonDomainPolicyTemporary reports a Domain Policy Record that could
	// not be retrieved because of a temporary DNS failure (Draft-09 Sections
	// 3.8 and 14.1; TEMPERROR).
	ReasonDomainPolicyTemporary ReasonCode = "domain_policy_temporary"
	// ReasonDomainPolicyAmbiguous reports more than one Domain Policy Record
	// beginning with v=DKIM1 (Draft-09 Section 3.8; PERMERROR).
	ReasonDomainPolicyAmbiguous ReasonCode = "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 fail-closed interpretation; PERMERROR).
	ReasonDomainPolicyInvalid ReasonCode = "domain_policy_invalid"
	// ReasonDuplicateSelector reports a repeated selector in one signature field.
	ReasonDuplicateSelector ReasonCode = "duplicate_selector"
	// ReasonMissingProtocol reports required DKIM2 protocol state is absent.
	ReasonMissingProtocol ReasonCode = "missing_protocol"
	// ReasonSequenceInvalid reports invalid instance or signature numbering.
	ReasonSequenceInvalid ReasonCode = "sequence_invalid"
	// ReasonUnsupportedAlgorithm reports that no required supported algorithm was checkable.
	ReasonUnsupportedAlgorithm ReasonCode = "unsupported_algorithm"
	// ReasonHashMismatch reports a supported current-message hash mismatch.
	ReasonHashMismatch ReasonCode = "hash_mismatch"
	// ReasonSignatureMismatch reports a supported cryptographic signature mismatch.
	ReasonSignatureMismatch ReasonCode = "signature_mismatch"
	// ReasonMissingKey reports that required public-key material is absent.
	ReasonMissingKey ReasonCode = "missing_key"
	// ReasonInvalidKey reports invalid public-key material.
	ReasonInvalidKey ReasonCode = "invalid_key"
	// ReasonAmbiguousKey reports ambiguous public-key material.
	ReasonAmbiguousKey ReasonCode = "ambiguous_key"
	// ReasonRevokedKey reports an explicitly revoked DNS public key.
	ReasonRevokedKey ReasonCode = "revoked_key"
	// ReasonUnsupportedKeyType reports an unsupported DNS key type.
	ReasonUnsupportedKeyType ReasonCode = "unsupported_key_type"
	// ReasonKeyAlgorithmMismatch reports disagreement between requested algorithm and DNS key type.
	ReasonKeyAlgorithmMismatch ReasonCode = "key_algorithm_mismatch"
	// ReasonProviderTemporary reports a typed temporary provider failure.
	ReasonProviderTemporary ReasonCode = "provider_temporary"
	// ReasonProviderPermanent reports a typed permanent provider failure.
	ReasonProviderPermanent ReasonCode = "provider_permanent"
	// ReasonProviderContract reports an inconsistent or unclassified provider outcome.
	ReasonProviderContract ReasonCode = "provider_contract"
	// ReasonTimestampInvalid reports an expired, future, or unrepresentable timestamp.
	ReasonTimestampInvalid ReasonCode = "timestamp_invalid"
	// ReasonEnvelopeMismatch reports current SMTP envelope disagreement.
	ReasonEnvelopeMismatch ReasonCode = "envelope_mismatch"
	// ReasonDomainAlignmentMismatch reports signing-domain alignment failure.
	ReasonDomainAlignmentMismatch ReasonCode = "domain_alignment_mismatch"
	// ReasonNextDomainMismatch reports structural next-domain disagreement.
	ReasonNextDomainMismatch ReasonCode = "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 ReasonCode = "custody_mismatch"
	// ReasonOutOfBandRequired reports a terminal next-domain requiring unmodeled OOB trust.
	ReasonOutOfBandRequired ReasonCode = "out_of_band_required"
	// ReasonBodyHistoryUnavailable reports a history that contains a null
	// body Recipe, so the message is not a Fully Verified DKIM2 Message
	// (Draft-09 Section 13).
	ReasonBodyHistoryUnavailable ReasonCode = "body_history_unavailable"
	// ReasonInternalContract reports an unknown or inconsistent internal fact.
	ReasonInternalContract ReasonCode = "internal_contract"
)

func (ReasonCode) Known

func (r ReasonCode) Known() bool

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

type ReceivedDSNEmbedded

type ReceivedDSNEmbedded string

ReceivedDSNEmbedded is the closed embedded member of the delivery_status projection.

const (
	// ReceivedDSNEmbeddedVerified reports a verified complete embedded original.
	ReceivedDSNEmbeddedVerified ReceivedDSNEmbedded = "verified"
	// ReceivedDSNEmbeddedVerifiedHeadersOnly reports verified header-only embedded evidence.
	ReceivedDSNEmbeddedVerifiedHeadersOnly ReceivedDSNEmbedded = "verified_headers_only"
	// ReceivedDSNEmbeddedUnverified reports permanent embedded verification failure.
	ReceivedDSNEmbeddedUnverified ReceivedDSNEmbedded = "unverified"
	// ReceivedDSNEmbeddedTemperror reports a temporary DNS or key failure.
	ReceivedDSNEmbeddedTemperror ReceivedDSNEmbedded = "temperror"
	// ReceivedDSNEmbeddedAbsent reports an embedded original without any DKIM2-Signature.
	ReceivedDSNEmbeddedAbsent ReceivedDSNEmbedded = "absent"
	// ReceivedDSNEmbeddedNotEvaluated reports that the structure stage stopped
	// the evaluation before any embedded evidence could be assessed.
	ReceivedDSNEmbeddedNotEvaluated ReceivedDSNEmbedded = "not_evaluated"
)

func (ReceivedDSNEmbedded) Known

func (s ReceivedDSNEmbedded) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type ReceivedDSNError

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

ReceivedDSNError preserves only a closed failure stage while exposing the caller context error or the public API error through errors.Unwrap.

func (*ReceivedDSNError) Error

func (e *ReceivedDSNError) Error() string

Error returns a bounded diagnostic without message, envelope, or identity data.

func (*ReceivedDSNError) Format

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

Format routes every formatting verb through the bounded diagnostic.

func (*ReceivedDSNError) Stage

Stage returns the closed failure stage or the zero value.

func (*ReceivedDSNError) Unwrap

func (e *ReceivedDSNError) Unwrap() error

Unwrap preserves context and API error classification.

type ReceivedDSNEvaluation

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

ReceivedDSNEvaluation is the immutable read-only outcome of one received-DSN evaluation. It exposes only the closed projection and bounded sequence facts; it can never authorize signing and is never an input to a signing route.

func (ReceivedDSNEvaluation) CompletionSequence

func (e ReceivedDSNEvaluation) CompletionSequence() uint64

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

func (ReceivedDSNEvaluation) Embedded

Embedded returns the closed embedded member, which is ReceivedDSNEmbeddedNotEvaluated when the structure stage stopped the evaluation.

func (ReceivedDSNEvaluation) Format

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

Format routes every evaluation formatting form through the redacted representation.

func (ReceivedDSNEvaluation) GoString

func (e ReceivedDSNEvaluation) GoString() string

GoString returns the constant secret-safe evaluation representation.

func (ReceivedDSNEvaluation) LocalHop

LocalHop returns the closed local_hop member.

func (ReceivedDSNEvaluation) LocalHopRunLength

func (e ReceivedDSNEvaluation) LocalHopRunLength() int

LocalHopRunLength returns the number of local run members when the local hop was proven, otherwise zero.

func (ReceivedDSNEvaluation) MarshalJSON

func (ReceivedDSNEvaluation) MarshalJSON() ([]byte, error)

MarshalJSON rejects direct serialization outside generated response DTOs.

func (ReceivedDSNEvaluation) MarshalText

func (ReceivedDSNEvaluation) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of sealed evaluation state.

func (ReceivedDSNEvaluation) OriginalForm

OriginalForm returns the embedded original representation once structure passed.

func (ReceivedDSNEvaluation) OuterAlignment

OuterAlignment returns the closed outer_alignment member.

func (ReceivedDSNEvaluation) Propagation

Propagation returns the closed informational propagation member.

func (ReceivedDSNEvaluation) RecipientLinkage

RecipientLinkage returns the closed recipient_linkage member.

func (ReceivedDSNEvaluation) String

func (ReceivedDSNEvaluation) String() string

String returns a constant representation without sealed evaluation facts.

func (ReceivedDSNEvaluation) Structure

Structure returns the closed structure member.

func (ReceivedDSNEvaluation) Valid

func (e ReceivedDSNEvaluation) Valid() bool

Valid reports whether the evaluation was issued by Verifier.EvaluateReceivedDSN and is coherent.

type ReceivedDSNLocalHop

type ReceivedDSNLocalHop string

ReceivedDSNLocalHop is the closed local_hop member of the delivery_status projection.

const (
	// ReceivedDSNLocalHopLocal reports a verified, datasource-local completion signature bound to the outer recipient.
	ReceivedDSNLocalHopLocal ReceivedDSNLocalHop = "local"
	// ReceivedDSNLocalHopNotLocal reports a completion signature under a domain the tenant does not control.
	ReceivedDSNLocalHopNotLocal ReceivedDSNLocalHop = "not_local"
	// ReceivedDSNLocalHopMismatch reports a local domain whose mf= does not bind to the outer recipient or its d=.
	ReceivedDSNLocalHopMismatch ReceivedDSNLocalHop = "mismatch"
	// ReceivedDSNLocalHopTemperror reports a temporary datasource failure.
	ReceivedDSNLocalHopTemperror ReceivedDSNLocalHop = "temperror"
	// ReceivedDSNLocalHopNotEvaluated reports an earlier stop or the absence of a tenant.
	ReceivedDSNLocalHopNotEvaluated ReceivedDSNLocalHop = "not_evaluated"
)

func (ReceivedDSNLocalHop) Known

func (s ReceivedDSNLocalHop) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type ReceivedDSNOriginalForm

type ReceivedDSNOriginalForm string

ReceivedDSNOriginalForm identifies the embedded original representation.

const (
	// ReceivedDSNOriginalComplete identifies a message/rfc822 embedded original.
	ReceivedDSNOriginalComplete ReceivedDSNOriginalForm = "complete"
	// ReceivedDSNOriginalHeadersOnly identifies a text/rfc822-headers embedded original.
	ReceivedDSNOriginalHeadersOnly ReceivedDSNOriginalForm = "headers_only"
)

func (ReceivedDSNOriginalForm) Known

func (f ReceivedDSNOriginalForm) Known() bool

Known reports whether the form belongs to the closed vocabulary.

type ReceivedDSNOuterAlignment

type ReceivedDSNOuterAlignment string

ReceivedDSNOuterAlignment is the closed outer_alignment member of the delivery_status projection.

const (
	// ReceivedDSNOuterAlignmentAligned reports that the outer signer relaxed-matches a completion rt= domain.
	ReceivedDSNOuterAlignmentAligned ReceivedDSNOuterAlignment = "aligned"
	// ReceivedDSNOuterAlignmentMisaligned reports that no completion rt= domain relaxed-matches the outer signer.
	ReceivedDSNOuterAlignmentMisaligned ReceivedDSNOuterAlignment = "misaligned"
	// ReceivedDSNOuterAlignmentNotEvaluated reports an earlier stop.
	ReceivedDSNOuterAlignmentNotEvaluated ReceivedDSNOuterAlignment = "not_evaluated"
)

func (ReceivedDSNOuterAlignment) Known

func (s ReceivedDSNOuterAlignment) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type ReceivedDSNPropagation

type ReceivedDSNPropagation string

ReceivedDSNPropagation is the closed informational propagation member of the delivery_status projection.

const (
	// ReceivedDSNPropagationNotApplicable reports an embedded original without DKIM2 signatures.
	ReceivedDSNPropagationNotApplicable ReceivedDSNPropagation = "not_applicable"
	// ReceivedDSNPropagationEligible reports that a rebuild toward the previous hop can be attempted.
	ReceivedDSNPropagationEligible ReceivedDSNPropagation = "eligible"
	// ReceivedDSNPropagationTerminalOrigin reports that this system originated the message.
	ReceivedDSNPropagationTerminalOrigin ReceivedDSNPropagation = "terminal_origin"
	// ReceivedDSNPropagationNotFailure reports that no linked group carries Action: failed.
	ReceivedDSNPropagationNotFailure ReceivedDSNPropagation = "not_failure"
	// ReceivedDSNPropagationForbiddenNullPreviousSender reports a previous hop with mf=<>.
	ReceivedDSNPropagationForbiddenNullPreviousSender ReceivedDSNPropagation = "forbidden_null_previous_sender"
	// ReceivedDSNPropagationForbiddenIdentityMisaligned reports a completion
	// d= that does not relaxed-match the previous hop's rt= address, so the
	// propagated report would violate Draft-09 Section 16.2.
	ReceivedDSNPropagationForbiddenIdentityMisaligned ReceivedDSNPropagation = "forbidden_identity_misaligned"
	// ReceivedDSNPropagationUnsupportedChain reports an nd= previous hop or a non-verifying run member.
	ReceivedDSNPropagationUnsupportedChain ReceivedDSNPropagation = "unsupported_chain"
	// ReceivedDSNPropagationNotReconstructable reports a rebuild-preventing condition visible without a rebuild.
	ReceivedDSNPropagationNotReconstructable ReceivedDSNPropagation = "not_reconstructable"
	// ReceivedDSNPropagationNotEvaluated reports an earlier stop or the absence of a tenant.
	ReceivedDSNPropagationNotEvaluated ReceivedDSNPropagation = "not_evaluated"
)

func (ReceivedDSNPropagation) Known

func (s ReceivedDSNPropagation) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type ReceivedDSNRecipientLinkage

type ReceivedDSNRecipientLinkage string

ReceivedDSNRecipientLinkage is the closed recipient_linkage member of the delivery_status projection.

const (
	// ReceivedDSNRecipientLinkageLinked reports at least one recipient group naming an authenticated rt= path.
	ReceivedDSNRecipientLinkageLinked ReceivedDSNRecipientLinkage = "linked"
	// ReceivedDSNRecipientLinkageUnlinked reports that no recipient group names an authenticated rt= path.
	ReceivedDSNRecipientLinkageUnlinked ReceivedDSNRecipientLinkage = "unlinked"
	// ReceivedDSNRecipientLinkageNotEvaluated reports an earlier stop.
	ReceivedDSNRecipientLinkageNotEvaluated ReceivedDSNRecipientLinkage = "not_evaluated"
)

func (ReceivedDSNRecipientLinkage) Known

Known reports whether the value belongs to the closed vocabulary.

type ReceivedDSNRequest

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

ReceivedDSNRequest carries cloned outer DSN bytes, the observed null reverse path and single forward path, and the tenant-bound local authority.

func NewReceivedDSNRequest

func NewReceivedDSNRequest(raw, reversePath []byte, forwardPaths [][]byte, authority LocalAuthority) ReceivedDSNRequest

NewReceivedDSNRequest snapshots one received-DSN evaluation request. A nil authority means no tenant is available; locality is then not evaluated.

func (ReceivedDSNRequest) Format

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

Format routes every request formatting form through the redacted representation.

func (ReceivedDSNRequest) GoString

func (r ReceivedDSNRequest) GoString() string

GoString returns the constant secret-safe request representation.

func (ReceivedDSNRequest) MarshalJSON

func (ReceivedDSNRequest) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of message or envelope bytes.

func (ReceivedDSNRequest) MarshalText

func (ReceivedDSNRequest) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of message or envelope bytes.

func (ReceivedDSNRequest) String

func (ReceivedDSNRequest) String() string

String prevents raw DSN or envelope content from reaching diagnostics.

type ReceivedDSNStage

type ReceivedDSNStage string

ReceivedDSNStage identifies one closed received-DSN evaluation stage.

const (
	// ReceivedDSNStagePreflight identifies request or evaluator validation.
	ReceivedDSNStagePreflight ReceivedDSNStage = "preflight"
	// ReceivedDSNStageStructure identifies RFC 6522 and RFC 3464 structure evaluation.
	ReceivedDSNStageStructure ReceivedDSNStage = "structure"
	// ReceivedDSNStageEmbeddedVerification identifies embedded-original verification.
	ReceivedDSNStageEmbeddedVerification ReceivedDSNStage = "embedded_verification"
	// ReceivedDSNStageLocalHop identifies local-hop identity and run detection.
	ReceivedDSNStageLocalHop ReceivedDSNStage = "local_hop"
	// ReceivedDSNStageOuterAlignment identifies outer signer alignment.
	ReceivedDSNStageOuterAlignment ReceivedDSNStage = "outer_alignment"
	// ReceivedDSNStageRecipientLinkage identifies RFC 3464 recipient linkage.
	ReceivedDSNStageRecipientLinkage ReceivedDSNStage = "recipient_linkage"
	// ReceivedDSNStageFailureClass identifies propagation-group selection.
	ReceivedDSNStageFailureClass ReceivedDSNStage = "failure_class"
	// ReceivedDSNStagePreviousHop identifies previous-hop classification.
	ReceivedDSNStagePreviousHop ReceivedDSNStage = "previous_hop"
)

func ReceivedDSNStageOf

func ReceivedDSNStageOf(err error) ReceivedDSNStage

ReceivedDSNStageOf returns the closed stage only for a typed received-DSN failure.

func (ReceivedDSNStage) Known

func (s ReceivedDSNStage) Known() bool

Known reports whether the stage belongs to the closed vocabulary.

type ReceivedDSNStructure

type ReceivedDSNStructure string

ReceivedDSNStructure is the closed structure member of the delivery_status projection.

const (
	// ReceivedDSNStructureValid reports exact RFC 6522 framing and a strict generic RFC 3464 body.
	ReceivedDSNStructureValid ReceivedDSNStructure = "valid"
	// ReceivedDSNStructureMalformed reports framing or delivery-status syntax outside the closed profile.
	ReceivedDSNStructureMalformed ReceivedDSNStructure = "malformed"
	// ReceivedDSNStructureLimitExceeded reports a DSN parser resource limit violation.
	ReceivedDSNStructureLimitExceeded ReceivedDSNStructure = "limit_exceeded"
)

func (ReceivedDSNStructure) Known

func (s ReceivedDSNStructure) Known() bool

Known reports whether the value belongs to the closed vocabulary.

type RecipeLiteralPolicy

type RecipeLiteralPolicy uint8

RecipeLiteralPolicy controls whether a generated inverse recipe may disclose literals.

const (
	// RecipeCopyOnly forbids embedding previous content as literals.
	RecipeCopyOnly RecipeLiteralPolicy = iota
	// RecipeAllowLiterals permits bounded literal disclosure.
	RecipeAllowLiterals
)

func (RecipeLiteralPolicy) Known

func (p RecipeLiteralPolicy) Known() bool

Known reports whether policy belongs to the closed recipe vocabulary.

type RecordedHop

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

RecordedHop is one DKIM2 hop as the message's header fields record it: who signed, which Message-Instance it signed and what its Recipe says it changed. It is NOT verified. A mail client or other consumer may present it only for a message that a verifier it trusts (for example its own receiving server, through its Authentication-Results) reported as PASS; such a PASS covers the complete chain and therefore every recorded field.

func DescribeRecordedChain

func DescribeRecordedChain(rawMessage []byte) ([]RecordedHop, error)

DescribeRecordedChain returns the DKIM2 hops recorded in rawMessage, ordered by sequence, or none for a message without DKIM2 fields. rawMessage must keep its CRLF line endings; only the header section is parsed (the body is neither needed nor copied), with the verifier's extraction and collection rules under the default limits. No key is looked up and nothing is verified, so the result is a description, not evidence. Malformed, over-limit or otherwise unusable input yields an invalid_request error instead of a partial chain.

func (RecordedHop) Format

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

Format prevents formatting verbs from exposing message-derived facts.

func (RecordedHop) GoString

func (RecordedHop) GoString() string

GoString returns a constant representation without message-derived facts.

func (RecordedHop) IntroducesInstance

func (h RecordedHop) IntroducesInstance() bool

IntroducesInstance reports whether this hop produced its Message-Instance; a later hop signing the same instance only relayed the message unchanged.

func (RecordedHop) MessageInstance

func (h RecordedHop) MessageInstance() uint64

MessageInstance returns the recorded Message-Instance number (m=) the hop signed.

func (RecordedHop) Recipe

Recipe returns the privacy-minimized descriptor of the recorded Recipe: affected header names, change classes and the body mode, never header values or body content.

func (RecordedHop) RecipeMode

func (h RecordedHop) RecipeMode() string

RecipeMode returns applied when the hop recorded a Recipe for its revision, else unchanged.

func (RecordedHop) Sequence

func (h RecordedHop) Sequence() uint64

Sequence returns the recorded signature sequence (i=).

func (RecordedHop) SignerDomain

func (h RecordedHop) SignerDomain() string

SignerDomain returns the recorded canonical signer domain (d=), in its A-label form.

func (RecordedHop) String

func (RecordedHop) String() string

String returns a constant representation without message-derived facts.

func (RecordedHop) Valid

func (h RecordedHop) Valid() bool

Valid reports whether the hop carries coherent recorded facts.

type ReplayCheck

type ReplayCheck = replay.Check

ReplayCheck identifies one successful replay-store outcome.

type ReplayClock

type ReplayClock = replay.Clock

ReplayClock supplies one deterministic operation time to the memory store.

type ReplayClockFunc

type ReplayClockFunc = replay.ClockFunc

ReplayClockFunc adapts one function to the memory-store clock seam.

type ReplayCountingPolicy

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

ReplayCountingPolicy is the local delivery policy that decides which authenticated messages replay detection counts (Draft-09 Section 15.1). It is the single owner of that decision for every replay path. The zero value is the default: only messages re-sent by an intermediary are counted.

func DirectDeliveryReplayCountingPolicy

func DirectDeliveryReplayCountingPolicy() ReplayCountingPolicy

DirectDeliveryReplayCountingPolicy also counts direct deliveries that carry only the originator's i=1 signature.

func (ReplayCountingPolicy) Counts

func (p ReplayCountingPolicy) Counts(identities ReplayIdentitySet) bool

Counts reports whether replay detection counts the message of a valid identity set under this policy.

func (ReplayCountingPolicy) CountsDirectDeliveries

func (p ReplayCountingPolicy) CountsDirectDeliveries() bool

CountsDirectDeliveries reports whether i=1-only messages are counted.

type ReplayDeriver

type ReplayDeriver = replay.Deriver

ReplayDeriver owns one cloned deployment-local HMAC secret and its lifecycle.

func NewReplayDeriver

func NewReplayDeriver(secret []byte, epoch uint32) (*ReplayDeriver, error)

NewReplayDeriver validates and clones one exact replay-key secret and epoch.

type ReplayDisabledStore

type ReplayDisabledStore = replay.DisabledStore

ReplayDisabledStore is an explicit no-storage replay provider.

func NewReplayDisabledStore

func NewReplayDisabledStore() *ReplayDisabledStore

NewReplayDisabledStore constructs one explicit disabled replay provider.

type ReplayError

type ReplayError = replay.Error

ReplayError is one typed content-free replay failure.

type ReplayErrorCode

type ReplayErrorCode = replay.ErrorCode

ReplayErrorCode identifies one stable replay failure class.

func ReplayErrorCodeOf

func ReplayErrorCodeOf(err error) ReplayErrorCode

ReplayErrorCodeOf returns the stable code for one direct replay failure.

type ReplayIdentity

type ReplayIdentity = replay.Identity

ReplayIdentity is one immutable message-wide authenticated replay identity.

type ReplayIdentitySet

type ReplayIdentitySet = replay.IdentitySet //nolint:staticcheck // Public compatibility remains until the documented API window closes.

ReplayIdentitySet is the compatibility container for one message-wide identity.

func ReplayIdentities

func ReplayIdentities(result VerifyResult) (ReplayIdentitySet, error)

ReplayIdentities adapts only one coherent verifier-owned aggregate-current-PASS projection.

type ReplayKey

type ReplayKey = replay.Key

ReplayKey is an opaque fixed-length replay-storage capability.

type ReplayLease

type ReplayLease = replay.Lease

ReplayLease is an immutable validated whole-millisecond propagation pending lease.

func NewReplayLease

func NewReplayLease(duration time.Duration) (ReplayLease, error)

NewReplayLease validates and constructs one propagation pending lease.

type ReplayLimits

type ReplayLimits = replay.Limits

ReplayLimits contains reusable hard-bounded replay-provider resources.

type ReplayMemoryConfig

type ReplayMemoryConfig struct {
	Limits ReplayLimits
	Clock  ReplayClock
}

ReplayMemoryConfig contains bounded resources and a required injected clock.

type ReplayMemoryStore

type ReplayMemoryStore = replay.MemoryStore

ReplayMemoryStore is a deterministic bounded heap-expiring replay provider.

func NewReplayMemoryStore

func NewReplayMemoryStore(config ReplayMemoryConfig) (*ReplayMemoryStore, error)

NewReplayMemoryStore validates and constructs one bounded memory replay provider.

type ReplayNonce

type ReplayNonce = replay.Nonce

ReplayNonce is one random write identity embedded in a stored replay value so a retried provider write recognizes its own earlier commit.

func NewReplayNonce

func NewReplayNonce(random io.Reader) (ReplayNonce, error)

NewReplayNonce reads one non-zero nonce from random, or from crypto/rand when random is nil.

func ParseReplayFirstSeenValue

func ParseReplayFirstSeenValue(value string) (nonce ReplayNonce, legacy bool, ok bool)

ParseReplayFirstSeenValue decodes one stored first-seen value, accepting the nonce-bearing form and the legacy ReplayStoredValue.

type ReplayPropagationCommit

type ReplayPropagationCommit = replay.PropagationCommit

ReplayPropagationCommit identifies one successful propagation commit outcome.

type ReplayPropagationReservation

type ReplayPropagationReservation = replay.PropagationReservation

ReplayPropagationReservation identifies one successful propagation reservation outcome.

type ReplayPropagationState

type ReplayPropagationState = replay.PropagationState

ReplayPropagationState is the closed stored state of one propagation coordinate.

func ParseReplayPropagationValue

func ParseReplayPropagationValue(value string) (ReplayPropagationState, time.Time, bool)

ParseReplayPropagationValue decodes one stored propagation value in the committed, nonce-bearing pending, or legacy pending form.

type ReplayPropagationStore

type ReplayPropagationStore interface {
	ReservePropagation(context.Context, ReplayKey, ReplayRetention, ReplayLease) (ReplayPropagationReservation, error)
	CommitPropagation(context.Context, ReplayKey) (ReplayPropagationCommit, error)
}

ReplayPropagationStore reserves and commits propagation coordinates in two phases.

type ReplayRetention

type ReplayRetention = replay.Retention

ReplayRetention is an immutable validated whole-millisecond retention period.

func DefaultReplayRetention

func DefaultReplayRetention() ReplayRetention

DefaultReplayRetention returns the frozen fourteen-day default.

func NewReplayRetention

func NewReplayRetention(duration time.Duration) (ReplayRetention, error)

NewReplayRetention validates and constructs one replay retention period.

type ReplayStore

type ReplayStore interface {
	CheckAndRemember(context.Context, ReplayKey, ReplayRetention) (ReplayCheck, error)
}

ReplayStore atomically checks and retains replay identities.

type ReplayStoreState

type ReplayStoreState = replay.StoreState

ReplayStoreState identifies one bounded replay-store lifecycle state.

type ResultState

type ResultState string

ResultState identifies one of the four public DKIM2 verification outcomes.

const (
	// ResultStatePASS reports complete success for the declared authenticated scope.
	ResultStatePASS ResultState = "PASS"
	// ResultStateFAIL reports that verification completed and the message is
	// not a Fully Verified DKIM2 Message (Draft-09 Section 14.1).
	ResultStateFAIL ResultState = "FAIL"
	// ResultStatePERMERROR reports unrecoverable malformed, missing, unsupported, or ambiguous state.
	ResultStatePERMERROR ResultState = "PERMERROR"
	// ResultStateTEMPERROR reports a typed temporary public-key-provider failure.
	ResultStateTEMPERROR ResultState = "TEMPERROR"
)

func (ResultState) Known

func (s ResultState) Known() bool

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

type RevisionVerification

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

RevisionVerification is one initialized dedicated revision outcome.

func (RevisionVerification) Format

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

Format routes every outcome formatting form through the redacted summary.

func (RevisionVerification) GoString

func (r RevisionVerification) GoString() string

GoString returns the constant secret-safe outcome Go representation.

func (RevisionVerification) Status

Status returns the closed revision outcome.

func (RevisionVerification) String

func (r RevisionVerification) String() string

String returns a constant secret-safe outcome summary.

func (RevisionVerification) Valid

func (r RevisionVerification) Valid() bool

Valid reports whether the outcome was produced by VerifyForRevision.

type RevisionVerificationStatus

type RevisionVerificationStatus string

RevisionVerificationStatus identifies one dedicated all-hop revision outcome.

const (
	// RevisionVerificationVerified reports complete ordinary proof.
	RevisionVerificationVerified RevisionVerificationStatus = "verified"
	// RevisionVerificationTerminalNextDomainAuthorizationRequired reports a
	// clean terminal nd= chain that requires authorized completion or continuation.
	RevisionVerificationTerminalNextDomainAuthorizationRequired RevisionVerificationStatus = "terminal_next_domain_authorization_required"
	// RevisionVerificationProtocolRejected reports rejected inherited evidence.
	RevisionVerificationProtocolRejected RevisionVerificationStatus = "protocol_rejected"
	// RevisionVerificationUnsupported reports unsupported-only inherited evidence.
	RevisionVerificationUnsupported RevisionVerificationStatus = "unsupported"
	// RevisionVerificationProviderTemporary reports retryable key lookup failure.
	RevisionVerificationProviderTemporary RevisionVerificationStatus = "provider_temporary"
	// RevisionVerificationProviderRejected reports permanent key rejection.
	RevisionVerificationProviderRejected RevisionVerificationStatus = "provider_rejected"
	// RevisionVerificationProviderContract reports an illegal provider matrix.
	RevisionVerificationProviderContract RevisionVerificationStatus = "provider_contract"
	// RevisionVerificationLimitExceeded reports exhausted verification bounds.
	RevisionVerificationLimitExceeded RevisionVerificationStatus = "limit_exceeded"
)

func (RevisionVerificationStatus) Known

func (s RevisionVerificationStatus) Known() bool

Known reports whether status belongs to the closed revision vocabulary.

type RouteAuthorityResult

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

RouteAuthorityResult is one closed authority callback result.

func NewRouteIssuedResult

func NewRouteIssuedResult(query RouteFinalizeQuery, parentID, parentSeal [sha256.Size]byte, ticketIDs, ticketSeals [][sha256.Size]byte) RouteAuthorityResult

NewRouteIssuedResult constructs exact fanout issuance bound to the supplied query.

func NewRouteTransitionResult

func NewRouteTransitionResult(status RouteAuthorityStatus, query RouteTicketQuery, replacementIDs, replacementSeals [][sha256.Size]byte) RouteAuthorityResult

NewRouteTransitionResult constructs an exact ticket transition acknowledgement.

func RouteDeniedResult

func RouteDeniedResult() RouteAuthorityResult

RouteDeniedResult constructs the sole content-free authority denial.

func (RouteAuthorityResult) Format

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

Format routes every result formatting form through the redacted summary.

func (RouteAuthorityResult) GoString

func (r RouteAuthorityResult) GoString() string

GoString returns the constant secret-safe authority-result Go representation.

func (RouteAuthorityResult) IsZero

func (r RouteAuthorityResult) IsZero() bool

IsZero reports whether no authority outcome was declared.

func (RouteAuthorityResult) String

func (r RouteAuthorityResult) String() string

String returns a constant secret-safe authority-result summary.

type RouteAuthorityStatus

type RouteAuthorityStatus string

RouteAuthorityStatus identifies a method-specific authority outcome.

const (
	// RouteAuthorityIssued reports successful parent and ticket issuance.
	RouteAuthorityIssued RouteAuthorityStatus = "issued"
	// RouteAuthorityReserved reports successful atomic reservation.
	RouteAuthorityReserved RouteAuthorityStatus = "reserved"
	// RouteAuthorityReleased reports successful pre-boundary release.
	RouteAuthorityReleased RouteAuthorityStatus = "released"
	// RouteAuthorityBurned reports successful external-boundary commitment.
	RouteAuthorityBurned RouteAuthorityStatus = "burned"
	// RouteAuthorityReplacementIssued reports successful same-lineage replacement.
	RouteAuthorityReplacementIssued RouteAuthorityStatus = "replacement_issued"
	// RouteAuthorityConsumed reports successful restricted release consumption.
	RouteAuthorityConsumed RouteAuthorityStatus = "consumed"
	// RouteAuthorityDenied reports a content-free authority denial.
	RouteAuthorityDenied RouteAuthorityStatus = "denied"
)

func (RouteAuthorityStatus) Known

func (s RouteAuthorityStatus) Known() bool

Known reports whether status belongs to the closed route authority vocabulary.

type RouteCopyTicket

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

RouteCopyTicket is one immutable non-reusable exact-copy capability.

func (RouteCopyTicket) Format

func (t RouteCopyTicket) Format(state fmt.State, _ rune)

Format routes every ticket formatting form through the redacted summary.

func (RouteCopyTicket) GoString

func (t RouteCopyTicket) GoString() string

GoString returns the constant secret-safe ticket Go representation.

func (RouteCopyTicket) String

func (t RouteCopyTicket) String() string

String returns a constant secret-safe ticket summary.

func (RouteCopyTicket) TotalMultiplicity

func (t RouteCopyTicket) TotalMultiplicity() int

TotalMultiplicity returns the sealed parent fanout copy count.

func (RouteCopyTicket) Valid

func (t RouteCopyTicket) Valid() bool

Valid reports whether the ticket carries a coherent authority seal.

type RouteDisclosure

type RouteDisclosure string

RouteDisclosure identifies one closed recipient-disclosure shape.

const (
	// RouteDisclosureSingle identifies one ordinary disclosed recipient.
	RouteDisclosureSingle RouteDisclosure = "single"
	// RouteDisclosureAuthorizedGroup identifies an explicitly authorized recipient group.
	RouteDisclosureAuthorizedGroup RouteDisclosure = "authorized_group"
	// RouteDisclosureBccSeparated identifies a privacy-preserving one-recipient copy.
	RouteDisclosureBccSeparated RouteDisclosure = "bcc_separated"
)

func (RouteDisclosure) Known

func (d RouteDisclosure) Known() bool

Known reports whether the disclosure belongs to the closed route vocabulary.

type RouteEntry

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

RouteEntry is one immutable intended signing output copy.

func NewDeliveryStatusPropagationRouteEntry

func NewDeliveryStatusPropagationRouteEntry(source SigningSource, reversePath []byte, forwardPaths [][]byte, routeScope []byte) (RouteEntry, error)

NewDeliveryStatusPropagationRouteEntry constructs one exact propagated-DSN route descriptor: purpose delivery_status_propagation, disclosure single, class external, the null reverse path, and exactly one forward path, the authenticated previous-hop mf= of the rebuilt report. It is purpose-separated from DSN signing and originator tickets so that neither can authorize a propagation and a propagation ticket can authorize nothing else.

func NewDeliveryStatusRouteEntry

func NewDeliveryStatusRouteEntry(source SigningSource, reversePath []byte, forwardPaths [][]byte, disclosure RouteDisclosure, routeScope []byte) (RouteEntry, error)

NewDeliveryStatusRouteEntry constructs one exact DSN route descriptor. It is purpose-separated from originator tickets so a generic signing ticket cannot authorize a null reverse-path delivery-status operation.

func NewExistingRouteEntry

func NewExistingRouteEntry(capability VerifiedRevisionInput, source SigningSource, reversePath []byte, forwardPaths [][]byte, disclosure RouteDisclosure, routeScope []byte) (RouteEntry, error)

NewExistingRouteEntry constructs one exact forwarding or revision route descriptor bound to a verified revision capability.

func NewInControlExistingRouteEntry

func NewInControlExistingRouteEntry(
	capability VerifiedRevisionInput,
	source SigningSource,
	reversePath []byte,
	forwardPaths [][]byte,
	disclosure RouteDisclosure,
	routeScope, receiverBinding []byte,
) (RouteEntry, error)

NewInControlExistingRouteEntry constructs an existing-message route that stays under the operator's control; inbound receiver evidence is required exactly for terminal next-domain completion and absent for ordinary predecessors.

func NewNextDomainContinuationRouteEntry

func NewNextDomainContinuationRouteEntry(
	capability VerifiedRevisionInput,
	source SigningSource,
	reversePath []byte,
	forwardPaths [][]byte,
	disclosure RouteDisclosure,
	routeScope, inboundReceiverBinding, outboundReceiverBinding []byte,
) (RouteEntry, error)

NewNextDomainContinuationRouteEntry constructs one exact terminal nd= route with independently sealed inbound and outbound OOB receiver evidence.

func NewNextDomainRouteEntry

func NewNextDomainRouteEntry(
	capability VerifiedRevisionInput,
	source SigningSource,
	reversePath []byte,
	forwardPaths [][]byte,
	disclosure RouteDisclosure,
	routeScope, receiverBinding []byte,
) (RouteEntry, error)

NewNextDomainRouteEntry constructs one outbound-only OOB route for creating a terminal nd= signature from an ordinary predecessor.

func NewOriginatorRouteEntry

func NewOriginatorRouteEntry(source SigningSource, reversePath []byte, forwardPaths [][]byte, disclosure RouteDisclosure, routeScope []byte) (RouteEntry, error)

NewOriginatorRouteEntry constructs one exact originator route descriptor.

func NewReceiverBoundExistingRouteEntry

func NewReceiverBoundExistingRouteEntry(
	capability VerifiedRevisionInput,
	source SigningSource,
	reversePath []byte,
	forwardPaths [][]byte,
	disclosure RouteDisclosure,
	routeScope, receiverBinding []byte,
) (RouteEntry, error)

NewReceiverBoundExistingRouteEntry constructs an ordinary external route carrying exact inbound OOB receiver-transaction evidence for nd completion.

func (RouteEntry) Format

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

Format routes every route-entry formatting form through the redacted summary.

func (RouteEntry) GoString

func (e RouteEntry) GoString() string

GoString returns the constant secret-safe route-entry Go representation.

func (RouteEntry) String

func (e RouteEntry) String() string

String returns a constant secret-safe route-entry summary.

type RouteFanoutAuthority

RouteFanoutAuthority owns issuance and atomic ticket transitions.

func NewRequestRouteAuthority

func NewRequestRouteAuthority() RouteFanoutAuthority

NewRequestRouteAuthority constructs one operation-scoped in-memory route authority. Callers must create a fresh value per request and discard it after the resulting signing operation completes.

type RouteFanoutPlan

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

RouteFanoutPlan is the immutable finalized parent route plan.

func (RouteFanoutPlan) CopyCount

func (p RouteFanoutPlan) CopyCount() int

CopyCount returns the exact finalized multiplicity.

func (RouteFanoutPlan) Format

func (p RouteFanoutPlan) Format(state fmt.State, _ rune)

Format routes every plan formatting form through the redacted summary.

func (RouteFanoutPlan) GoString

func (p RouteFanoutPlan) GoString() string

GoString returns the constant secret-safe route-plan Go representation.

func (RouteFanoutPlan) String

func (p RouteFanoutPlan) String() string

String returns a constant secret-safe route-plan summary.

func (RouteFanoutPlan) Valid

func (p RouteFanoutPlan) Valid() bool

Valid reports whether the plan carries a coherent authority seal.

type RouteFanoutRequest

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

RouteFanoutRequest snapshots one complete ordered collection of intended copies.

func NewRouteFanoutRequest

func NewRouteFanoutRequest(entries []RouteEntry) (RouteFanoutRequest, error)

NewRouteFanoutRequest constructs a complete immutable fanout request.

func (RouteFanoutRequest) Format

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

Format routes every request formatting form through the redacted summary.

func (RouteFanoutRequest) GoString

func (r RouteFanoutRequest) GoString() string

GoString returns the constant secret-safe fanout-request Go representation.

func (RouteFanoutRequest) String

func (r RouteFanoutRequest) String() string

String returns a constant secret-safe fanout-request summary.

type RouteFinalizeQuery

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

RouteFinalizeQuery carries only opaque exact fanout bindings to an authority.

func (RouteFinalizeQuery) BindingDigest

func (q RouteFinalizeQuery) BindingDigest(index int) []byte

BindingDigest returns a detached exact binding digest by ordered index.

func (RouteFinalizeQuery) Count

func (q RouteFinalizeQuery) Count() int

Count returns the coupled copy and ticket count.

func (RouteFinalizeQuery) Format

func (q RouteFinalizeQuery) Format(state fmt.State, _ rune)

Format routes every query formatting form through the redacted summary.

func (RouteFinalizeQuery) GoString

func (q RouteFinalizeQuery) GoString() string

GoString returns the constant secret-safe query Go representation.

func (RouteFinalizeQuery) String

func (q RouteFinalizeQuery) String() string

String returns a constant secret-safe query summary.

func (RouteFinalizeQuery) Valid

func (q RouteFinalizeQuery) Valid() bool

Valid reports whether the query has a complete authority-bound shape.

type RouteTicketQuery

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

RouteTicketQuery carries only opaque exact ticket-transition identities.

func (RouteTicketQuery) BindingIdentity

func (q RouteTicketQuery) BindingIdentity() [sha256.Size]byte

BindingIdentity returns the opaque exact-copy binding.

func (RouteTicketQuery) CapabilitySeal

func (q RouteTicketQuery) CapabilitySeal() [sha256.Size]byte

CapabilitySeal returns the opaque authority-issued ticket seal.

func (RouteTicketQuery) Format

func (q RouteTicketQuery) Format(state fmt.State, _ rune)

Format routes every query formatting form through the redacted summary.

func (RouteTicketQuery) GoString

func (q RouteTicketQuery) GoString() string

GoString returns the constant secret-safe query Go representation.

func (RouteTicketQuery) ParentIdentity

func (q RouteTicketQuery) ParentIdentity() [sha256.Size]byte

ParentIdentity returns the opaque parent identity.

func (RouteTicketQuery) String

func (q RouteTicketQuery) String() string

String returns a constant secret-safe query summary.

func (RouteTicketQuery) TicketIdentity

func (q RouteTicketQuery) TicketIdentity() [sha256.Size]byte

TicketIdentity returns the opaque ticket identity.

func (RouteTicketQuery) Valid

func (q RouteTicketQuery) Valid() bool

Valid reports whether every opaque transition identity is present.

type SignatureSetFact

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

SignatureSetFact records one bounded algorithm-family and signature-set outcome.

func (SignatureSetFact) Algorithm

func (f SignatureSetFact) Algorithm() Algorithm

Algorithm returns the bounded signature algorithm family.

func (SignatureSetFact) Format

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

Format prevents formatting from traversing the message-derived selector.

func (SignatureSetFact) GoString

func (SignatureSetFact) GoString() string

GoString returns a constant representation without the selector.

func (SignatureSetFact) Reason

func (f SignatureSetFact) Reason() ReasonCode

Reason returns the bounded signature-set reason.

func (SignatureSetFact) Selector

func (f SignatureSetFact) Selector() (string, bool)

Selector returns the parsed selector of a non-passing set (Draft-09 Section 14.6 step 8); a passing set and an internal-contract fact carry none.

func (SignatureSetFact) Status

func (f SignatureSetFact) Status() SignatureStatus

Status returns the bounded signature-set status.

func (SignatureSetFact) String

func (SignatureSetFact) String() string

String returns a constant representation so formatting never carries the message-derived selector; callers read it explicitly through Selector.

type SignatureStatus

type SignatureStatus string

SignatureStatus identifies a bounded per-signature-set outcome.

const (
	// SignatureStatusPASS reports a supported passing signature set.
	SignatureStatusPASS SignatureStatus = "pass"
	// SignatureStatusFAIL reports a supported failing signature set.
	SignatureStatusFAIL SignatureStatus = "fail"
	// SignatureStatusPERMERROR reports permanent key or protocol state for the
	// set, including an unknown or locally disabled algorithm.
	SignatureStatusPERMERROR SignatureStatus = "permerror"
	// SignatureStatusTEMPERROR reports typed temporary provider state for the set.
	SignatureStatusTEMPERROR SignatureStatus = "temperror"
)

func (SignatureStatus) Known

func (s SignatureStatus) Known() bool

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

type SignedMessageFacts

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

SignedMessageFacts contains bounded immutable non-secret operation facts.

func (SignedMessageFacts) Algorithms

func (f SignedMessageFacts) Algorithms() []Algorithm

Algorithms returns detached generated algorithms in canonical order.

func (SignedMessageFacts) Authorizations

func (f SignedMessageFacts) Authorizations() []SigningAuthorizationFact

Authorizations returns detached completed authorization facts.

func (SignedMessageFacts) BodyUnavailable

func (f SignedMessageFacts) BodyUnavailable() bool

BodyUnavailable reports whether the revision emitted explicit b:null.

func (SignedMessageFacts) BodyUnavailableReason

func (f SignedMessageFacts) BodyUnavailableReason() SigningBodyUnavailableReason

BodyUnavailableReason returns the bounded reason only for explicit b:null.

func (SignedMessageFacts) EnvelopeForm

func (f SignedMessageFacts) EnvelopeForm() SigningEnvelopeForm

EnvelopeForm returns the generated signature envelope form.

func (SignedMessageFacts) Flags

Flags returns detached generated known flags.

func (SignedMessageFacts) Format

func (f SignedMessageFacts) Format(state fmt.State, _ rune)

Format routes every facts formatting form through the redacted summary.

func (SignedMessageFacts) GoString

func (f SignedMessageFacts) GoString() string

GoString returns the constant secret-safe facts Go representation.

func (SignedMessageFacts) Multiplicity

func (f SignedMessageFacts) Multiplicity() int

Multiplicity returns the sealed parent fanout copy count.

func (SignedMessageFacts) NewInstanceNumber

func (f SignedMessageFacts) NewInstanceNumber() uint64

NewInstanceNumber returns the emitted m= number or zero.

func (SignedMessageFacts) RecipeOutcome

func (f SignedMessageFacts) RecipeOutcome() SigningRecipeOutcome

RecipeOutcome returns whether an inverse recipe was emitted.

func (SignedMessageFacts) Restriction

func (f SignedMessageFacts) Restriction() SigningRestriction

Restriction returns the strongest closed output restriction.

func (SignedMessageFacts) Role

Role returns the exact hash-derived role.

func (SignedMessageFacts) Sequence

func (f SignedMessageFacts) Sequence() uint64

Sequence returns the emitted i= number.

func (SignedMessageFacts) String

func (f SignedMessageFacts) String() string

String returns a constant secret-safe facts summary.

func (SignedMessageFacts) Valid

func (f SignedMessageFacts) Valid() bool

Valid reports whether every closed fact correlation is coherent.

type SignedMessageFlag

type SignedMessageFlag string

SignedMessageFlag identifies one emitted known protocol flag.

const (
	// SignedMessageFlagFeedback reports emitted feedback.
	SignedMessageFlagFeedback SignedMessageFlag = "feedback"
	// SignedMessageFlagFeedHere reports emitted feedhere.
	SignedMessageFlagFeedHere SignedMessageFlag = "feedhere"
	// SignedMessageFlagExploded reports emitted exploded.
	SignedMessageFlagExploded SignedMessageFlag = "exploded"
)

func (SignedMessageFlag) Known

func (f SignedMessageFlag) Known() bool

Known reports whether flag belongs to the emitted closed vocabulary.

type Signer

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

Signer owns revision proof, fanout planning, authorization, publication, private signing, insertion, and final atomic proof for all three signing paths.

func NewSigner

func NewSigner(publicKeys PublicKeyProvider, routes RouteFanoutAuthority, authorizer SigningAuthorizer, privateKeys PrivateKeySigner, options ...SignerOption) (*Signer, error)

NewSigner constructs the complete three-path signing facade.

Its incoming-chain verification (VerifyForRevision) requires the same explicit Draft-09 Section 11.1 choice as NewVerifier: publicKeys also implements DomainPolicyProvider, WithSignerDomainPolicyProvider is passed, or WithoutSignerSubdomainFromAuthorization is passed; otherwise construction fails with SigningErrorInvalidOptions. The signer's own d= choice stays downward only (disposition D8).

func (*Signer) EvaluateDSNForSigning

func (s *Signer) EvaluateDSNForSigning(ctx context.Context, request DSNSigningEvidenceRequest) (DSNSigningEvidence, error)

EvaluateDSNForSigning derives the opaque pre-policy authorization for a null reverse-path DSN after RFC 6522/3464 structure and recipient linkage, embedded DKIM2 verification, and outer-recipient binding all pass. It never touches a signing profile; ResolveDSNSigningIdentity selects the Draft-09 Section 16.2 signing identity afterwards. A returned original without any DKIM2-Signature header field fails with DSNEvidenceStageEmbeddedUnsigned; one that carries such a field always takes the strict verification path.

func (*Signer) IssueNextDomainPublication

func (s *Signer) IssueNextDomainPublication(ctx context.Context, request NextDomainPublicationRequest) (PublishedNextDomainCapability, error)

IssueNextDomainPublication performs one fresh authoritative publication lookup.

func (*Signer) PlanPropagationRoute

func (s *Signer) PlanPropagationRoute(ctx context.Context, evidence DSNPropagationEvidence, routeScope []byte) (RouteCopyTicket, error)

PlanPropagationRoute plans exactly one delivery_status_propagation route ticket over the rebuilt report that the evidence carries. The ticket source is the report's own bytes, so it matches the message SignPropagatedDSN signs; the reverse path is null, the single forward path is the authenticated previous-hop mf=, and the disclosure and route class are the fixed single external shape. Neither the caller nor the route scope can select the recipient or the signing domain: both stay derived from the removed completion signature and the verified previous hop.

func (*Signer) PlanRouteFanout

func (s *Signer) PlanRouteFanout(ctx context.Context, request RouteFanoutRequest) (RouteFanoutPlan, []RouteCopyTicket, error)

PlanRouteFanout finalizes one complete intended fanout and returns its exact tickets.

func (*Signer) RebuildDSNForPropagation

func (s *Signer) RebuildDSNForPropagation(ctx context.Context, request DSNPropagationRequest) (DSNPropagationEvidence, error)

RebuildDSNForPropagation evaluates one received DSN under Draft-09 Section 16.4 with the signer's own verifier and, when the evaluation is eligible, rebuilds it under Section 16.3 into an unsigned report addressed to the authenticated previous hop. The signing domain is the canonical d= of the removed completion signature; neither the request nor the adapter can select it. Protocol outcomes are returned in the evidence; only invalid requests, cancellation, and internal contract violations return a Go error.

func (*Signer) ResolveDSNSigningIdentity

func (s *Signer) ResolveDSNSigningIdentity(ctx context.Context, evidence DSNSigningEvidence, source DSNProfileSource) (DSNSigningEvidence, SigningProfile, error)

ResolveDSNSigningIdentity is the single owner of the Draft-09 Section 16.2 DSN signing identity. It walks the candidates of dsn.Evidence.SigningIdentityCandidates (domains that relaxed-match an rt= address of the highest DKIM2-Signature of the reported message, RFC 3464 linked recipients first, then the preferred identity, then the most specific domain) and binds the first candidate that has a local delivery_status profile and makes the report's own From header field Authentic (Sections 11 and 12.4) through the downward match only: the DSN identity resolver never uses a subdomain d= to make a parent From Authentic and never queries a Domain Policy Record (Sections 11.1 and 12.4, local disposition D8). It returns the bound evidence and that profile.

No candidate with a profile yields DSNEvidenceStageIdentityUnavailable; candidates with a profile that all leave the From non-Authentic yield DSNEvidenceStageFromNotAuthentic. Both are explicit "cannot be DKIM2 signed" outcomes, never a fallback to another domain. A profile source error, a profile for a different domain, or cancellation fails with DSNEvidenceStageSigningDomain and preserves the cause.

func (*Signer) SignDSN

SignDSN signs only a DSN previously authorized by EvaluateDSNForSigning.

func (*Signer) SignExisting

SignExisting executes the sole combined verified forwarding or revision path.

func (*Signer) SignNextDomain

SignNextDomain executes the distinct terminal next-domain request path.

func (*Signer) SignOriginator

SignOriginator executes the sole originator request path. A null reverse path is admitted only through NewHeaderFromNullSenderSigningRequest and only when the profile domain is the single From mailbox domain.

func (*Signer) SignPropagatedDSN

func (s *Signer) SignPropagatedDSN(ctx context.Context, request DSNPropagationSigningRequest) (PropagatedDSN, SigningRecovery, error)

SignPropagatedDSN signs only a report rebuilt by RebuildDSNForPropagation. The ticket must carry the delivery_status_propagation purpose with the null reverse path and the authenticated next-hop recipient, the profile must belong to the derived signing domain, and the result must carry exactly one Message-Instance m=1 and one DKIM2-Signature i=1 with mf=<> and rt= equal to the previous hop's mf=.

func (*Signer) VerifyForRevision

func (s *Signer) VerifyForRevision(ctx context.Context, request VerifyRequest) (RevisionVerification, VerifiedRevisionInput, error)

VerifyForRevision verifies all inherited protocol evidence and seals clean exact input.

type SignerOption

type SignerOption func(*signerConfig) error

SignerOption configures one validated signing facade dependency.

func WithSignerDomainPolicyProvider

func WithSignerDomainPolicyProvider(provider DomainPolicyProvider) SignerOption

WithSignerDomainPolicyProvider selects the Domain Policy Record provider the signer's incoming-chain verification (VerifyForRevision) uses for the upward Authentic From match. The signer's own d= choice stays downward only (disposition D8).

func WithSigningClock

func WithSigningClock(clock func() time.Time) SignerOption

WithSigningClock injects the single deterministic operation clock.

func WithSigningLimits

func WithSigningLimits(limits SigningLimits) SignerOption

WithSigningLimits applies one immutable narrow-only limit set.

func WithoutSignerSubdomainFromAuthorization

func WithoutSignerSubdomainFromAuthorization() SignerOption

WithoutSignerSubdomainFromAuthorization makes the signer's incoming-chain verification use the local downward-only policy.

type SigningAuthorizationFact

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

SigningAuthorizationFact records one bounded completed authorization stage.

func (SigningAuthorizationFact) Format

func (f SigningAuthorizationFact) Format(state fmt.State, _ rune)

Format routes every authorization-fact formatting form through the redacted summary.

func (SigningAuthorizationFact) GoString

func (f SigningAuthorizationFact) GoString() string

GoString returns the constant secret-safe authorization-fact Go representation.

func (SigningAuthorizationFact) Purpose

Purpose returns the completed authorization purpose.

func (SigningAuthorizationFact) Restriction

Restriction returns the completed authorization restriction.

func (SigningAuthorizationFact) Status

Status returns the completed authorization status.

func (SigningAuthorizationFact) String

func (f SigningAuthorizationFact) String() string

String returns a constant secret-safe authorization-fact summary.

func (SigningAuthorizationFact) Valid

func (f SigningAuthorizationFact) Valid() bool

Valid reports whether this is one coherent signing authorization fact.

type SigningAuthorizationPurpose

type SigningAuthorizationPurpose string

SigningAuthorizationPurpose identifies one closed authorization decision.

const (
	// SigningAuthorizationPolicy authorizes exact modification and route facts.
	SigningAuthorizationPolicy SigningAuthorizationPurpose = "policy"
	// SigningAuthorizationFeedbackRelay authorizes inherited feedback relay.
	SigningAuthorizationFeedbackRelay SigningAuthorizationPurpose = "feedback_relay"
	// SigningAuthorizationRecipientDisclosure authorizes exact multi-recipient disclosure.
	SigningAuthorizationRecipientDisclosure SigningAuthorizationPurpose = "recipient_disclosure"
	// SigningAuthorizationReceiveNextDomain authorizes receipt from one inherited nd= hop.
	SigningAuthorizationReceiveNextDomain SigningAuthorizationPurpose = "receive_terminal_next_domain"
	// SigningAuthorizationSendNextDomain authorizes one exact terminal nd= route.
	SigningAuthorizationSendNextDomain SigningAuthorizationPurpose = "send_terminal_next_domain"
)

func (SigningAuthorizationPurpose) Known

Known reports whether the purpose belongs to the closed signing vocabulary.

type SigningAuthorizationQuery

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

SigningAuthorizationQuery carries exact bounded authorization evidence.

func (SigningAuthorizationQuery) Binding

Binding returns the opaque exact-operation authorization binding.

func (SigningAuthorizationQuery) Format

func (q SigningAuthorizationQuery) Format(state fmt.State, _ rune)

Format routes every query formatting form through the redacted summary.

func (SigningAuthorizationQuery) GoString

func (q SigningAuthorizationQuery) GoString() string

GoString returns the constant secret-safe query Go representation.

func (SigningAuthorizationQuery) OutOfBandFacts

OutOfBandFacts returns exact trusted-boundary evidence for receive/send purposes.

func (SigningAuthorizationQuery) PolicyFacts

PolicyFacts returns bounded policy facts and the inherited restriction.

func (SigningAuthorizationQuery) Purpose

Purpose returns the closed authorization purpose.

func (SigningAuthorizationQuery) Recipients

func (q SigningAuthorizationQuery) Recipients() [][]byte

Recipients returns detached exact envelope recipients only across this trusted boundary.

func (SigningAuthorizationQuery) String

func (q SigningAuthorizationQuery) String() string

String returns a constant secret-safe query summary.

func (SigningAuthorizationQuery) Valid

func (q SigningAuthorizationQuery) Valid() bool

Valid reports whether the query contains one coherent sealed purpose.

type SigningAuthorizationResult

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

SigningAuthorizationResult is a closed query-bound authorization result.

func AuthorizeSigning

AuthorizeSigning constructs an approval for the exact supplied query.

func DenySigning

DenySigning constructs a denial for the exact supplied query.

func (SigningAuthorizationResult) Format

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

Format routes every result formatting form through the redacted summary.

func (SigningAuthorizationResult) GoString

func (r SigningAuthorizationResult) GoString() string

GoString returns the constant secret-safe result Go representation.

func (SigningAuthorizationResult) IsZero

func (r SigningAuthorizationResult) IsZero() bool

IsZero reports whether no declared authorization result is present.

func (SigningAuthorizationResult) String

String returns a constant secret-safe result summary.

type SigningAuthorizationStatus

type SigningAuthorizationStatus string

SigningAuthorizationStatus identifies one closed declared authorization result.

const (
	// SigningAuthorizationAuthorized approves the exact supplied query.
	SigningAuthorizationAuthorized SigningAuthorizationStatus = "authorized"
	// SigningAuthorizationDenied denies the exact supplied query.
	SigningAuthorizationDenied SigningAuthorizationStatus = "denied"
)

func (SigningAuthorizationStatus) Known

func (s SigningAuthorizationStatus) Known() bool

Known reports whether status belongs to the closed authorization vocabulary.

type SigningAuthorizer

type SigningAuthorizer interface {
	Authorize(context.Context, SigningAuthorizationQuery) (SigningAuthorizationResult, error)
}

SigningAuthorizer decides exact policy, OOB, feedback, and disclosure queries.

type SigningBodyUnavailableReason

type SigningBodyUnavailableReason string

SigningBodyUnavailableReason identifies why an explicit b:null was required.

const (
	// SigningBodyUnavailableUnrepresentable reports that the prior body cannot
	// be represented by the bounded inverse recipe.
	SigningBodyUnavailableUnrepresentable SigningBodyUnavailableReason = "unrepresentable"
	// SigningBodyUnavailableLiteralRequired reports a forbidden literal was required.
	SigningBodyUnavailableLiteralRequired SigningBodyUnavailableReason = "literal_required"
)

func (SigningBodyUnavailableReason) Known

Known reports whether reason belongs to the closed unavailable-body vocabulary.

type SigningCredential

type SigningCredential interface {
	// contains filtered or unexported methods
}

SigningCredential is one validated credential of any signable algorithm: RSASigningCredential, Ed25519SigningCredential, or MLDSA44SigningCredential. The interface is sealed to this package.

type SigningEnvelopeForm

type SigningEnvelopeForm string

SigningEnvelopeForm identifies the generated signature envelope shape.

const (
	// SigningEnvelopeOrdinary identifies the ordinary mf=/rt= form.
	SigningEnvelopeOrdinary SigningEnvelopeForm = "ordinary_mf_rt"
	// SigningEnvelopeNextDomain identifies the terminal nd= form.
	SigningEnvelopeNextDomain SigningEnvelopeForm = "next_domain"
)

func (SigningEnvelopeForm) Known

func (f SigningEnvelopeForm) Known() bool

Known reports whether form belongs to the closed signing vocabulary.

type SigningError

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

SigningError is a bounded cause-free public signing failure.

func (*SigningError) Code

func (e *SigningError) Code() SigningErrorCode

Code returns the stable public signing error code.

func (*SigningError) Error

func (e *SigningError) Error() string

Error returns a secret-safe stable diagnostic.

func (*SigningError) Format

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

Format renders every fmt form through the bounded diagnostic.

func (*SigningError) Is

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

Is matches public signing errors by stable code.

type SigningErrorCode

type SigningErrorCode string

SigningErrorCode identifies one bounded signing failure.

const (
	SigningErrorInvalidOptions           SigningErrorCode = "invalid_options"
	SigningErrorInvalidRequest           SigningErrorCode = "invalid_request"
	SigningErrorCapabilityMismatch       SigningErrorCode = "capability_mismatch"
	SigningErrorMalformedInput           SigningErrorCode = "malformed_input"
	SigningErrorProtocolTampering        SigningErrorCode = "protocol_tampering"
	SigningErrorSequenceFailure          SigningErrorCode = "sequence_failure"
	SigningErrorReferenceFailure         SigningErrorCode = "reference_failure"
	SigningErrorHashStateAmbiguity       SigningErrorCode = "hash_state_ambiguity"
	SigningErrorChainFailure             SigningErrorCode = "chain_failure"
	SigningErrorAuthorizationDenied      SigningErrorCode = "authorization_denied"
	SigningErrorAuthorizationUnavailable SigningErrorCode = "authorization_unavailable"
	SigningErrorPolicyRestriction        SigningErrorCode = "policy_restriction"
	SigningErrorDisclosureDenied         SigningErrorCode = "disclosure_denied"
	SigningErrorUnsupportedAlgorithm     SigningErrorCode = "unsupported_algorithm"
	SigningErrorKeyMismatch              SigningErrorCode = "key_mismatch"
	SigningErrorCallbackTemporary        SigningErrorCode = "callback_temporary"
	SigningErrorCallbackPermanent        SigningErrorCode = "callback_permanent"
	SigningErrorCryptographicSelfCheck   SigningErrorCode = "cryptographic_self_check_failure"
	SigningErrorLimitExceeded            SigningErrorCode = "limit_exceeded"
	SigningErrorInternalInvariant        SigningErrorCode = "internal_invariant_failure"
)

Public signing failures use the protocol core's closed vocabulary.

func (SigningErrorCode) Known

func (c SigningErrorCode) Known() bool

Known reports whether the code belongs to the public signing vocabulary.

type SigningFlag

type SigningFlag string

SigningFlag identifies one caller-requestable baseline flag. Draft-07 Section 10.10 removed donotmodify and donotexplode, so feedback is the sole requestable flag.

const (
	// SigningFlagFeedback requests authenticated feedback.
	SigningFlagFeedback SigningFlag = "feedback"
)

func (SigningFlag) Known

func (f SigningFlag) Known() bool

Known reports whether the flag may be requested by a caller.

type SigningLimits

type SigningLimits struct {
	// MaxMessageBytes bounds exact input and completed output bytes.
	MaxMessageBytes int
	// MaxHeaderBytes bounds the completed raw header block.
	MaxHeaderBytes int
	// MaxHeaderFields bounds completed header occurrences.
	MaxHeaderFields int
	// MaxFieldBytes bounds one generated protocol field.
	MaxFieldBytes int
	// MaxLineBytes bounds one generated physical header line.
	MaxLineBytes int
	// MaxInstances bounds all Message-Instance fields.
	MaxInstances int
	// MaxSignatures bounds all DKIM2-Signature fields.
	MaxSignatures int
	// MaxProtocolFields bounds both protocol field families together.
	MaxProtocolFields int
	// MaxHashSetsPerInstance bounds hash sets in one instance.
	MaxHashSetsPerInstance int
	// MaxSignatureSetsPerField bounds signature sets in one field.
	MaxSignatureSetsPerField int
	// MaxTotalSignatureSets bounds inherited and generated signature sets.
	MaxTotalSignatureSets int
	// MaxPublicKeyLookups bounds inherited and generated publication lookups.
	MaxPublicKeyLookups int
	// MaxSignatureInputBytes bounds one Section 12.8 input.
	MaxSignatureInputBytes int
	// MaxCanonicalWorkBytes bounds aggregate canonical work.
	MaxCanonicalWorkBytes int
	// MaxGeneratedRecipients bounds recipients rendered into one new field.
	MaxGeneratedRecipients int
	// MaxParentOutputCopiesAndTickets bounds the coupled fanout cardinality.
	MaxParentOutputCopiesAndTickets int
	// MaxEnvelopePathBytes bounds decoded generated envelope paths.
	MaxEnvelopePathBytes int
	// MaxDecodedRecipeBytes bounds one generated or inherited recipe.
	MaxDecodedRecipeBytes int
	// MaxGeneratedSignatureSets bounds sets emitted in the new field.
	MaxGeneratedSignatureSets int
	// MaxAuthorizationCalls bounds applicable authorization callbacks.
	MaxAuthorizationCalls int
	// MaxPrivateSigningCalls bounds generated private signing callbacks.
	MaxPrivateSigningCalls int
	// MaxNonceBytes bounds optional signing nonce bytes.
	MaxNonceBytes int
	// MinRSABits is the smallest accepted RSA key size.
	MinRSABits int
	// MaxRSABits is the largest accepted RSA key size.
	MaxRSABits int
	// MaxPrivateSignatureBytes bounds one private callback result.
	MaxPrivateSignatureBytes int
	// MaxRouteDescriptorBytes bounds aggregate fanout descriptor bytes.
	MaxRouteDescriptorBytes int
	// MaxRouteWorkUnits bounds fanout planning work.
	MaxRouteWorkUnits int
	// MaxUniquePreSignSourceBytes bounds unique source bytes hashed per fanout.
	MaxUniquePreSignSourceBytes int
	// MaxRouteAuthorityCalls bounds one signing or release attempt.
	MaxRouteAuthorityCalls int
}

SigningLimits contains public narrow-only signing ceilings.

Zero-valued fields use the corresponding hard default. Callers narrowing related dimensions must keep the resulting set coherent.

func DefaultSigningLimits

func DefaultSigningLimits() SigningLimits

DefaultSigningLimits returns every public hard ceiling explicitly.

func (SigningLimits) Validate

func (l SigningLimits) Validate() error

Validate rejects widening and incoherent narrowed limits.

type SigningMetadata

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

SigningMetadata is immutable optional nonce and requested-flag metadata.

func NewSigningMetadata

func NewSigningMetadata(nonce []byte, noncePresent bool, flags []SigningFlag) (SigningMetadata, error)

NewSigningMetadata validates and snapshots optional nonce and requested flags.

func (SigningMetadata) Format

func (m SigningMetadata) Format(state fmt.State, _ rune)

Format routes every metadata formatting form through the redacted summary.

func (SigningMetadata) GoString

func (m SigningMetadata) GoString() string

GoString returns the constant secret-safe metadata Go representation.

func (SigningMetadata) String

func (m SigningMetadata) String() string

String returns a constant secret-safe metadata summary.

type SigningModificationFacts

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

SigningModificationFacts contains only bounded authenticated modification facts.

func (SigningModificationFacts) BodyChanged

func (f SigningModificationFacts) BodyChanged() bool

BodyChanged reports whether the authoritative body hash changed.

func (SigningModificationFacts) ExistingHeadersChanged

func (f SigningModificationFacts) ExistingHeadersChanged() bool

ExistingHeadersChanged reports whether inherited non-protocol headers changed.

func (SigningModificationFacts) Format

func (f SigningModificationFacts) Format(state fmt.State, _ rune)

Format routes every facts formatting form through the redacted summary.

func (SigningModificationFacts) GoString

func (f SigningModificationFacts) GoString() string

GoString returns the constant secret-safe facts Go representation.

func (SigningModificationFacts) String

func (f SigningModificationFacts) String() string

String returns a constant secret-safe facts summary.

func (SigningModificationFacts) Valid

func (f SigningModificationFacts) Valid() bool

Valid reports whether the facts came from a sealed signing query.

type SigningOutOfBandFacts

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

SigningOutOfBandFacts exposes exact values only across the trusted authorizer boundary.

func (SigningOutOfBandFacts) Format

func (f SigningOutOfBandFacts) Format(state fmt.State, _ rune)

Format routes every OOB facts formatting form through the redacted summary.

func (SigningOutOfBandFacts) ForwardPaths

func (f SigningOutOfBandFacts) ForwardPaths() [][]byte

ForwardPaths returns detached purpose-bound exact SMTP recipient evidence.

func (SigningOutOfBandFacts) GoString

func (f SigningOutOfBandFacts) GoString() string

GoString returns the constant secret-safe OOB facts Go representation.

func (SigningOutOfBandFacts) PredecessorDomain

func (f SigningOutOfBandFacts) PredecessorDomain() string

PredecessorDomain returns the authenticated canonical predecessor domain.

func (SigningOutOfBandFacts) PredecessorKind

func (f SigningOutOfBandFacts) PredecessorKind() SigningPredecessorKind

PredecessorKind returns the authenticated predecessor envelope form.

func (SigningOutOfBandFacts) ProfileDomain

func (f SigningOutOfBandFacts) ProfileDomain() string

ProfileDomain returns the exact canonical signing domain.

func (SigningOutOfBandFacts) ProposedNextDomain

func (f SigningOutOfBandFacts) ProposedNextDomain() string

ProposedNextDomain returns the terminal nd= value or empty for receive authorization.

func (SigningOutOfBandFacts) ReceiverBinding

func (f SigningOutOfBandFacts) ReceiverBinding() []byte

ReceiverBinding returns the detached exact receiver-transaction evidence.

func (SigningOutOfBandFacts) ReversePath

func (f SigningOutOfBandFacts) ReversePath() []byte

ReversePath returns detached purpose-bound exact SMTP reverse-path evidence.

func (SigningOutOfBandFacts) RouteScope

func (f SigningOutOfBandFacts) RouteScope() []byte

RouteScope returns the detached exact trusted route-scope handle.

func (SigningOutOfBandFacts) String

func (f SigningOutOfBandFacts) String() string

String returns a constant secret-safe OOB facts summary.

func (SigningOutOfBandFacts) Valid

func (f SigningOutOfBandFacts) Valid() bool

Valid reports whether the facts form one exact receive or send authorization.

type SigningPredecessorKind

type SigningPredecessorKind string

SigningPredecessorKind identifies the authenticated predecessor envelope form.

const (
	// SigningPredecessorOrdinary identifies an ordinary mf=/rt= predecessor.
	SigningPredecessorOrdinary SigningPredecessorKind = "ordinary"
	// SigningPredecessorNextDomain identifies a terminal nd= predecessor.
	SigningPredecessorNextDomain SigningPredecessorKind = "next_domain"
)

func (SigningPredecessorKind) Known

func (k SigningPredecessorKind) Known() bool

Known reports whether the predecessor kind belongs to the closed signing vocabulary.

type SigningProfile

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

SigningProfile is an immutable canonical signing domain with one credential for each of up to three signable algorithms. The emitted s= tag joins the classical credentials (rsa-sha256, ed25519-sha256) as one sig-all group and puts an mldsa44 credential in a separate sig-any alternative after "|" (Draft-09 Section 10.9 phased deployment).

func NewDualSigningProfile

func NewDualSigningProfile(domain string, rsaCredential RSASigningCredential, ed25519Credential Ed25519SigningCredential) (SigningProfile, error)

NewDualSigningProfile constructs a canonical RSA-then-Ed25519 profile.

func NewEd25519SigningProfile

func NewEd25519SigningProfile(domain string, credential Ed25519SigningCredential) (SigningProfile, error)

NewEd25519SigningProfile constructs a single-algorithm Ed25519-SHA256 profile.

func NewMLDSA44SigningProfile

func NewMLDSA44SigningProfile(domain string, credential MLDSA44SigningCredential) (SigningProfile, error)

NewMLDSA44SigningProfile constructs a single-algorithm mldsa44 profile.

func NewProjectedSigningProfile

func NewProjectedSigningProfile(projected signing.Profile) (SigningProfile, error)

NewProjectedSigningProfile seals one already validated internal datasource projection for sibling command modules without rebuilding its credentials.

The parameter deliberately remains an internal type: only modules inside this repository may cross this narrow datasource-to-signing bridge.

func NewRSASigningProfile

func NewRSASigningProfile(domain string, credential RSASigningCredential) (SigningProfile, error)

NewRSASigningProfile constructs a single-algorithm RSA-SHA256 profile.

func NewSigningProfile

func NewSigningProfile(domain string, credentials ...SigningCredential) (SigningProfile, error)

NewSigningProfile constructs a profile from one credential per algorithm in any order; the profile owner sorts them into the canonical signing order and rejects duplicate algorithms, duplicate selectors (across every s= group), nil credentials, and more than three credentials.

func (SigningProfile) Format

func (p SigningProfile) Format(state fmt.State, _ rune)

Format routes every profile formatting form through the redacted summary.

func (SigningProfile) GoString

func (p SigningProfile) GoString() string

GoString returns the constant secret-safe profile Go representation.

func (SigningProfile) String

func (p SigningProfile) String() string

String returns a constant secret-safe profile summary.

func (SigningProfile) Valid

func (p SigningProfile) Valid() bool

Valid reports whether the profile remains canonical and coherent.

type SigningRecipeOutcome

type SigningRecipeOutcome string

SigningRecipeOutcome identifies whether an inverse recipe was emitted.

const (
	// SigningRecipeUnchanged reports that no recipe was emitted.
	SigningRecipeUnchanged SigningRecipeOutcome = "unchanged"
	// SigningRecipeGenerated reports one emitted inverse recipe.
	SigningRecipeGenerated SigningRecipeOutcome = "recipe"
)

func (SigningRecipeOutcome) Known

func (o SigningRecipeOutcome) Known() bool

Known reports whether outcome belongs to the closed recipe vocabulary.

type SigningRecovery

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

SigningRecovery owns one shared consumptive same-lineage route recovery action.

func (SigningRecovery) Format

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

Format routes every recovery formatting form through the redacted summary.

func (SigningRecovery) GoString

func (r SigningRecovery) GoString() string

GoString returns the constant secret-safe recovery Go representation.

func (SigningRecovery) Recover

Recover consumes this recovery action and returns a same-lineage replacement when ready.

func (SigningRecovery) RecoveryPending

func (r SigningRecovery) RecoveryPending() bool

RecoveryPending reports whether authority cleanup must be retried.

func (SigningRecovery) ReplacementReady

func (r SigningRecovery) ReplacementReady() bool

ReplacementReady reports whether Recover will yield an already issued ticket.

func (SigningRecovery) String

func (r SigningRecovery) String() string

String returns a constant secret-safe recovery summary.

func (SigningRecovery) Valid

func (r SigningRecovery) Valid() bool

Valid reports whether recovery has one actionable closed state.

type SigningRestriction

type SigningRestriction string

SigningRestriction identifies one closed signing output restriction.

const (
	// SigningRestrictionUnrestricted permits ordinary message release.
	SigningRestrictionUnrestricted SigningRestriction = "unrestricted"
	// SigningRestrictionOutOfBandAcceptance requires exact OOB-bound release.
	SigningRestrictionOutOfBandAcceptance SigningRestriction = "requires_out_of_band_acceptance"
)

func (SigningRestriction) Known

func (r SigningRestriction) Known() bool

Known reports whether restriction belongs to the closed signing vocabulary.

type SigningResult

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

SigningResult is a closed signing result sum.

func (SigningResult) Format

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

Format routes every result formatting form through the redacted summary.

func (SigningResult) GoString

func (r SigningResult) GoString() string

GoString returns the constant secret-safe result Go representation.

func (SigningResult) OutOfBandAcceptance

func (r SigningResult) OutOfBandAcceptance() (OutOfBandAcceptanceSignedMessage, bool)

OutOfBandAcceptance returns the OOB-restricted no-byte variant when present.

func (SigningResult) String

func (r SigningResult) String() string

String returns a constant secret-safe result summary.

func (SigningResult) Unrestricted

func (r SigningResult) Unrestricted() (UnrestrictedSignedMessage, bool)

Unrestricted returns the sole byte-releasable variant when present.

func (SigningResult) Valid

func (r SigningResult) Valid() bool

Valid reports whether exactly one coherent result variant is present.

type SigningRole

type SigningRole string

SigningRole identifies the role derived by the exact Section 12.1 hash gate.

const (
	// SigningRoleOriginator creates the initial protocol fields.
	SigningRoleOriginator SigningRole = "originator"
	// SigningRoleHashUnchangedForwarder appends a signature without a new instance.
	SigningRoleHashUnchangedForwarder SigningRole = "hash_unchanged_forwarder"
	// SigningRoleReviser appends one inverse-recipe instance and signature.
	SigningRoleReviser SigningRole = "reviser"
)

func (SigningRole) Known

func (r SigningRole) Known() bool

Known reports whether role belongs to the closed signing vocabulary.

type SigningSource

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

SigningSource is one immutable exact pre-sign RFC 5322 source identity.

func NewSigningSource

func NewSigningSource(rawMessage []byte) (SigningSource, error)

NewSigningSource snapshots exact pre-sign RFC 5322 bytes for fanout planning.

func (SigningSource) Format

func (s SigningSource) Format(state fmt.State, _ rune)

Format routes every source formatting form through the redacted summary.

func (SigningSource) GoString

func (s SigningSource) GoString() string

GoString returns the constant secret-safe source Go representation.

func (SigningSource) String

func (s SigningSource) String() string

String returns a constant secret-safe source summary.

func (SigningSource) Valid

func (s SigningSource) Valid() bool

Valid reports whether the source owns initialized exact bytes.

type SigningTransportForm

type SigningTransportForm string

SigningTransportForm identifies the closed signable transport declaration.

const (
	// SigningTransportFinalNetworkPreDotStuffing declares final network-form
	// RFC 5322 bytes before SMTP dot-stuffing.
	SigningTransportFinalNetworkPreDotStuffing SigningTransportForm = "final_network_form_pre_dot_stuffing"
)

func (SigningTransportForm) Known

func (f SigningTransportForm) Known() bool

Known reports whether form is the sole signable transport declaration.

type TXTAbsenceClass

type TXTAbsenceClass string

TXTAbsenceClass distinguishes authoritative NXDOMAIN and NODATA results.

const (
	// TXTAbsenceNXDOMAIN reports authoritative owner-name absence.
	TXTAbsenceNXDOMAIN TXTAbsenceClass = "nxdomain"
	// TXTAbsenceNODATA reports an existing owner without TXT data.
	TXTAbsenceNODATA TXTAbsenceClass = "nodata"
)

func (TXTAbsenceClass) Known

func (a TXTAbsenceClass) Known() bool

Known reports whether the absence class belongs to the closed public vocabulary.

type TXTLookupResult

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

TXTLookupResult owns one immutable mutually exclusive found or absent answer.

func NewAbsentTXTLookupResult

func NewAbsentTXTLookupResult(absence TXTAbsenceClass, ttl time.Duration, dnssec DNSSECStatus) (TXTLookupResult, error)

NewAbsentTXTLookupResult constructs an authoritative negative result.

func NewAmbiguousTXTLookupResult

func NewAmbiguousTXTLookupResult(recordCount int, ttl time.Duration, dnssec DNSSECStatus) (TXTLookupResult, error)

NewAmbiguousTXTLookupResult constructs count-only ambiguity without payload traversal. The Section 3.7 filter cannot inspect such an answer, so it resolves as an ambiguous key.

func NewFoundTXTLookupResult

func NewFoundTXTLookupResult(payloads [][]byte, ttl time.Duration, dnssec DNSSECStatus) (TXTLookupResult, error)

NewFoundTXTLookupResult constructs found state from raw payloads using count-first validation: up to MaxCarriedTXTRecords payloads are kept, a larger answer becomes count-only ambiguity without payload traversal.

func (TXTLookupResult) Absence

func (r TXTLookupResult) Absence() TXTAbsenceClass

Absence returns the authoritative negative class when absent.

func (TXTLookupResult) DNSSECStatus

func (r TXTLookupResult) DNSSECStatus() DNSSECStatus

DNSSECStatus returns verdict-neutral bounded diagnostic metadata.

func (TXTLookupResult) Format

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

Format prevents formatting from traversing DNS TXT result storage.

func (TXTLookupResult) GoString

func (TXTLookupResult) GoString() string

GoString returns a constant representation without DNS TXT payload bytes.

func (TXTLookupResult) IsZero

func (r TXTLookupResult) IsZero() bool

IsZero reports whether no declared public transport result is present.

func (TXTLookupResult) MarshalJSON

func (TXTLookupResult) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization outside the bounded provider boundary.

func (TXTLookupResult) MarshalText

func (TXTLookupResult) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of DNS TXT result storage.

func (TXTLookupResult) NegativeTTL

func (r TXTLookupResult) NegativeTTL() time.Duration

NegativeTTL returns authoritative negative TTL provenance.

func (TXTLookupResult) PositiveTTL

func (r TXTLookupResult) PositiveTTL() time.Duration

PositiveTTL returns found-answer TTL provenance.

func (TXTLookupResult) RecordCount

func (r TXTLookupResult) RecordCount() int

RecordCount returns the exact RR count without requiring ambiguous payload traversal.

func (TXTLookupResult) Records

func (r TXTLookupResult) Records() []TXTRecord

Records returns the detached TXT payloads, or nil when absent or count-only ambiguous.

func (TXTLookupResult) Status

func (r TXTLookupResult) Status() TXTLookupStatus

Status returns the mutually exclusive lookup status.

func (TXTLookupResult) String

func (TXTLookupResult) String() string

String returns a constant representation without DNS TXT payload bytes.

type TXTLookupStatus

type TXTLookupStatus string

TXTLookupStatus identifies a mutually exclusive found or absent DNS answer.

const (
	// TXTLookupStatusFound reports one or more TXT resource records.
	TXTLookupStatusFound TXTLookupStatus = "found"
	// TXTLookupStatusAbsent reports authoritative DNS name or data absence.
	TXTLookupStatusAbsent TXTLookupStatus = "absent"
)

func (TXTLookupStatus) Known

func (s TXTLookupStatus) Known() bool

Known reports whether the status belongs to the closed public vocabulary.

type TXTRecord

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

TXTRecord owns one already-concatenated TXT resource-record payload.

func (TXTRecord) Format

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

Format prevents formatting from traversing DNS TXT payload bytes.

func (TXTRecord) GoString

func (TXTRecord) GoString() string

GoString returns a constant representation without DNS TXT payload bytes.

func (TXTRecord) MarshalJSON

func (TXTRecord) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization outside the bounded provider boundary.

func (TXTRecord) MarshalText

func (TXTRecord) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of DNS TXT payload bytes.

func (TXTRecord) Payload

func (r TXTRecord) Payload() []byte

Payload returns an independent payload copy.

func (TXTRecord) String

func (TXTRecord) String() string

String returns a constant representation without DNS TXT payload bytes.

type TXTTransport

type TXTTransport interface {
	LookupTXT(context.Context, string) (TXTLookupResult, error)
}

TXTTransport resolves one absolute DNS TXT owner through caller context.

Implementations return a declared result with nil error, a zero result with caller context error, or a zero result with an existing typed public provider error. Raw and contradictory combinations are contract violations later.

type UnrestrictedSignedMessage

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

UnrestrictedSignedMessage is a fully proved message with a generic byte-copy accessor.

func (UnrestrictedSignedMessage) Bytes

func (m UnrestrictedSignedMessage) Bytes() []byte

Bytes returns an independent copy of the complete RFC 5322 output.

func (UnrestrictedSignedMessage) Facts

Facts returns bounded immutable operation facts.

func (UnrestrictedSignedMessage) Format

func (m UnrestrictedSignedMessage) Format(state fmt.State, _ rune)

Format routes every message formatting form through the redacted summary.

func (UnrestrictedSignedMessage) GeneratedFields

func (m UnrestrictedSignedMessage) GeneratedFields() [][]byte

GeneratedFields returns detached complete RFC 5322 fields in the exact insertion order proved by the signing coordinator.

func (UnrestrictedSignedMessage) GoString

func (m UnrestrictedSignedMessage) GoString() string

GoString returns the constant secret-safe message Go representation.

func (UnrestrictedSignedMessage) SigningIdentity

func (m UnrestrictedSignedMessage) SigningIdentity() (domain string, timestamp uint64, err error)

SigningIdentity returns the domain and Unix timestamp of the newly generated signature on a proved unrestricted result. It excludes inherited signatures and fails closed for zero or incoherent results. Restricted results do not expose this accessor; their existing release boundaries remain unchanged.

func (UnrestrictedSignedMessage) String

func (m UnrestrictedSignedMessage) String() string

String returns a constant secret-safe message summary.

func (UnrestrictedSignedMessage) Valid

func (m UnrestrictedSignedMessage) Valid() bool

Valid reports whether this is a coherent unrestricted result.

type VerificationAssessment

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

VerificationAssessment separates DKIM2 applicability from the four verification states.

func (VerificationAssessment) Applicable

func (a VerificationAssessment) Applicable() bool

Applicable reports whether DKIM2 protocol fields started a verification.

func (VerificationAssessment) Format

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

Format prevents formatting verbs from traversing verification facts.

func (VerificationAssessment) GoString

func (VerificationAssessment) GoString() string

GoString returns a constant content-free assessment representation.

func (VerificationAssessment) MarshalJSON

func (VerificationAssessment) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization outside an owning transport adapter.

func (VerificationAssessment) MarshalText

func (VerificationAssessment) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of retained verification facts.

func (VerificationAssessment) String

func (VerificationAssessment) String() string

String returns a constant content-free assessment representation.

func (VerificationAssessment) Valid

func (a VerificationAssessment) Valid() bool

Valid reports whether this is exactly one closed applicability variant.

func (VerificationAssessment) Verification

func (a VerificationAssessment) Verification() (VerifyResult, bool)

Verification returns an immutable four-state result only for applicable input.

type VerificationLimits

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

VerificationLimits is an immutable closed configuration whose values may only narrow hard maxima.

func DefaultVerificationLimits

func DefaultVerificationLimits() VerificationLimits

DefaultVerificationLimits returns the closed defaults, which equal the hard maxima.

func (VerificationLimits) MaxCheckFacts

func (l VerificationLimits) MaxCheckFacts() int

MaxCheckFacts returns the configured retained check-fact limit.

func (VerificationLimits) MaxInstanceHashSets

func (l VerificationLimits) MaxInstanceHashSets() int

MaxInstanceHashSets returns the configured Message-Instance hash-set limit.

func (VerificationLimits) MaxRawMessageBytes

func (l VerificationLimits) MaxRawMessageBytes() int

MaxRawMessageBytes returns the configured raw-message byte limit.

func (VerificationLimits) MaxRecipients

func (l VerificationLimits) MaxRecipients() int

MaxRecipients returns the configured current-recipient count limit.

func (VerificationLimits) MaxSignatureFacts

func (l VerificationLimits) MaxSignatureFacts() int

MaxSignatureFacts returns the configured retained signature-set-fact limit.

func (VerificationLimits) MaxSignatureSets

func (l VerificationLimits) MaxSignatureSets() int

MaxSignatureSets returns the configured DKIM2-Signature set limit per field.

type VerificationScope

type VerificationScope string

VerificationScope identifies which message state was verified.

const (
	// VerificationScopeCurrent limits the result to the highest current signature and instance.
	VerificationScopeCurrent VerificationScope = "current"
	// VerificationScopeChain reports authenticated verification through every inherited revision.
	VerificationScopeChain VerificationScope = "chain"
)

func (VerificationScope) Known

func (s VerificationScope) Known() bool

Known reports whether the scope belongs to the closed public vocabulary.

type VerificationTarget

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

VerificationTarget identifies the current signature sequence and Message-Instance number.

func (VerificationTarget) Format

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

Format prevents formatting from traversing sequence identifiers.

func (VerificationTarget) GoString

func (VerificationTarget) GoString() string

GoString returns a constant representation without sequence identifiers.

func (VerificationTarget) Instance

func (t VerificationTarget) Instance() uint64

Instance returns the target Message-Instance number.

func (VerificationTarget) MarshalJSON

func (VerificationTarget) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization outside explicit mapped response boundaries.

func (VerificationTarget) MarshalText

func (VerificationTarget) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of sequence identifiers.

func (VerificationTarget) Sequence

func (t VerificationTarget) Sequence() uint64

Sequence returns the target DKIM2-Signature sequence number.

func (VerificationTarget) String

func (VerificationTarget) String() string

String returns a constant representation without sequence identifiers.

type VerifiedRevisionInput

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

VerifiedRevisionInput is an opaque exact-input capability with no raw-message accessor.

func (VerifiedRevisionInput) Format

func (c VerifiedRevisionInput) Format(state fmt.State, _ rune)

Format routes every capability formatting form through the redacted summary.

func (VerifiedRevisionInput) GoString

func (c VerifiedRevisionInput) GoString() string

GoString returns the constant secret-safe capability Go representation.

func (VerifiedRevisionInput) String

func (c VerifiedRevisionInput) String() string

String returns a constant secret-safe capability summary.

func (VerifiedRevisionInput) Valid

func (c VerifiedRevisionInput) Valid() bool

Valid reports only whether the capability has an issued structural shape.

type Verifier

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

Verifier is the public current-verification facade.

Example

ExampleVerifier demonstrates secret-safe structured result handling.

package main

import (
	"context"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"time"

	_ "embed"
	dkim2 "github.com/croessner/dkim2"
)

//go:embed testdata/vectors/draft-ietf-dkim-dkim2-spec-09/public-golden.json
var publicExampleCorpus []byte

type syntheticMissingProvider struct{}

// LookupPublicKey returns deterministic key absence without network access.
func (syntheticMissingProvider) LookupPublicKey(_ context.Context, query dkim2.PublicKeyQuery) (dkim2.PublicKeyResult, error) {
	return dkim2.MissingPublicKey(query.Algorithm()), nil
}

func main() {
	verifier, err := dkim2.NewVerifier(
		syntheticMissingProvider{},
		dkim2.WithVerificationClock(func() time.Time { return time.Unix(1700000000, 0) }), dkim2.WithoutSubdomainFromAuthorization(),
	)
	if err != nil {
		fmt.Println("construction error")
		return
	}
	result, err := verifier.Verify(context.Background(), syntheticExampleRequest())
	if err != nil {
		fmt.Println("caller or API error")
		return
	}

	switch result.State() {
	case dkim2.ResultStatePASS:
		fmt.Println("PASS")
	case dkim2.ResultStateFAIL:
		fmt.Println("FAIL")
	case dkim2.ResultStatePERMERROR:
		fmt.Println("PERMERROR")
	case dkim2.ResultStateTEMPERROR:
		fmt.Println("TEMPERROR")
	}
	fmt.Println(result.PrimaryReason())
	fmt.Println(result.Scope(), result.HistoricalContent(), result.HistoricalSignatures(), result.CustodyStructure())
	fmt.Println(result.CheckCount(), result.SignatureSetCount())
	for _, check := range result.Checks() {
		fmt.Println(check.Class(), check.Reason())
	}
	for _, signature := range result.SignatureSets() {
		fmt.Println(signature.Algorithm(), signature.Status(), signature.Reason())
	}

}

// syntheticExampleRequest decodes the frozen synthetic current-message fixture.
func syntheticExampleRequest() dkim2.VerifyRequest {
	return syntheticExampleRequestNamed("rsa_pass")
}

// syntheticExampleRequestNamed decodes one frozen synthetic current-message fixture.
func syntheticExampleRequestNamed(name string) dkim2.VerifyRequest {
	type vector struct {
		Raw     string   `json:"raw_base64"`
		Reverse string   `json:"reverse_path_base64"`
		Forward []string `json:"forward_paths_base64"`
	}
	var corpus struct {
		Vectors map[string]vector `json:"vectors"`
	}
	_ = json.Unmarshal(publicExampleCorpus, &corpus)
	fixture := corpus.Vectors[name]
	raw, _ := base64.StdEncoding.DecodeString(fixture.Raw)
	reverse, _ := base64.StdEncoding.DecodeString(fixture.Reverse)
	forward := make([][]byte, len(fixture.Forward))
	for index, encoded := range fixture.Forward {
		forward[index], _ = base64.StdEncoding.DecodeString(encoded)
	}
	return dkim2.NewVerifyRequest(raw, reverse, forward)
}
Output:
PERMERROR
missing_key
current not_evaluated not_evaluated not_present
7 1
body_hash none
domain_alignment none
envelope none
header_hash none
key missing_key
next_domain none
timestamp none
rsa-sha256 permerror missing_key
Example (TemporaryProvider)

ExampleVerifier_temporaryProvider demonstrates bounded provider-failure inspection.

package main

import (
	"context"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"time"

	_ "embed"
	dkim2 "github.com/croessner/dkim2"
)

//go:embed testdata/vectors/draft-ietf-dkim-dkim2-spec-09/public-golden.json
var publicExampleCorpus []byte

type syntheticTemporaryProvider struct{}

// LookupPublicKey returns typed temporary state without exposing a provider cause.
func (syntheticTemporaryProvider) LookupPublicKey(context.Context, dkim2.PublicKeyQuery) (dkim2.PublicKeyResult, error) {
	return dkim2.PublicKeyResult{}, dkim2.NewTemporaryProviderError()
}

func main() {
	verifier, err := dkim2.NewVerifier(syntheticTemporaryProvider{}, dkim2.WithVerificationClock(func() time.Time { return time.Unix(1700000000, 0) }), dkim2.WithoutSubdomainFromAuthorization())
	if err != nil {
		fmt.Println("construction error")
		return
	}
	result, err := verifier.Verify(context.Background(), syntheticExampleRequest())
	if err != nil {
		fmt.Println("caller or API error")
		return
	}
	fact := result.SignatureSets()[0]
	fmt.Println(result.State(), result.PrimaryReason())
	fmt.Println(fact.Algorithm(), fact.Status(), fact.Reason())

}

// syntheticExampleRequest decodes the frozen synthetic current-message fixture.
func syntheticExampleRequest() dkim2.VerifyRequest {
	return syntheticExampleRequestNamed("rsa_pass")
}

// syntheticExampleRequestNamed decodes one frozen synthetic current-message fixture.
func syntheticExampleRequestNamed(name string) dkim2.VerifyRequest {
	type vector struct {
		Raw     string   `json:"raw_base64"`
		Reverse string   `json:"reverse_path_base64"`
		Forward []string `json:"forward_paths_base64"`
	}
	var corpus struct {
		Vectors map[string]vector `json:"vectors"`
	}
	_ = json.Unmarshal(publicExampleCorpus, &corpus)
	fixture := corpus.Vectors[name]
	raw, _ := base64.StdEncoding.DecodeString(fixture.Raw)
	reverse, _ := base64.StdEncoding.DecodeString(fixture.Reverse)
	forward := make([][]byte, len(fixture.Forward))
	for index, encoded := range fixture.Forward {
		forward[index], _ = base64.StdEncoding.DecodeString(encoded)
	}
	return dkim2.NewVerifyRequest(raw, reverse, forward)
}
Output:
TEMPERROR provider_temporary
rsa-sha256 temperror provider_temporary

func NewVerifier

func NewVerifier(provider PublicKeyProvider, options ...VerifierOption) (*Verifier, error)

NewVerifier constructs a fully initialized current-verification facade.

Construction requires an explicit Draft-09 Section 11.1 choice (local interpretation D9): provider also implements DomainPolicyProvider (as DNSPublicKeyProvider does), WithDomainPolicyProvider is passed, or WithoutSubdomainFromAuthorization is passed. A missing or conflicting choice fails with APIErrorCodeInvalidOption.

func (*Verifier) Assess

func (v *Verifier) Assess(ctx context.Context, request VerifyRequest) (output VerificationAssessment, resultErr error)

Assess classifies complete DKIM2 protocol absence before starting verification.

func (*Verifier) EvaluateReceivedDSN

func (v *Verifier) EvaluateReceivedDSN(ctx context.Context, request ReceivedDSNRequest) (ReceivedDSNEvaluation, error)

EvaluateReceivedDSN evaluates one inbound DKIM2-signed delivery-status notification under Draft-09 Section 16.4 after the caller verified the outer message as an ordinary message with this verifier. It shares the verifier's key provider, limits, clock, and observation sink and adds the tenant-bound local authority carried by the request. The request must carry the observed null reverse path and exactly one forward path. Protocol outcomes are returned in the evaluation; only invalid requests, cancellation, and internal contract violations return a Go error.

func (Verifier) Format

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

Format prevents formatting from traversing injected provider state.

func (Verifier) GoString

func (Verifier) GoString() string

GoString returns a constant representation without injected provider state.

func (Verifier) MarshalJSON

func (Verifier) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization of retained verifier dependencies.

func (Verifier) MarshalText

func (Verifier) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of retained verifier dependencies.

func (Verifier) String

func (Verifier) String() string

String returns a constant representation without injected provider state.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, request VerifyRequest) (output VerifyResult, resultErr error)

Verify delegates chain-authenticated verification and preserves the disjoint result/error contract.

type VerifierHop

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

VerifierHop is one immutable authenticated chain record.

func (VerifierHop) BodyAvailability

func (h VerifierHop) BodyAvailability() string

BodyAvailability returns known or unavailable.

func (VerifierHop) CustodyTransition

func (h VerifierHop) CustodyTransition() string

CustodyTransition returns origin, ordinary, next_domain, or terminal_next_domain.

func (VerifierHop) Exploded

func (h VerifierHop) Exploded() bool

Exploded reports authenticated exploded presence.

func (VerifierHop) FeedHere

func (h VerifierHop) FeedHere() bool

FeedHere reports authenticated feedhere presence.

func (VerifierHop) Feedback

func (h VerifierHop) Feedback() bool

Feedback reports authenticated feedback presence.

func (VerifierHop) Format

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

Format prevents formatting verbs from exposing message-derived facts.

func (VerifierHop) GoString

func (VerifierHop) GoString() string

GoString returns a constant representation without message-derived facts.

func (VerifierHop) HistoryBodyState

func (h VerifierHop) HistoryBodyState() string

HistoryBodyState returns the authenticated historical body state.

func (VerifierHop) HistoryHeaderState

func (h VerifierHop) HistoryHeaderState() string

HistoryHeaderState returns the authenticated historical header state.

func (VerifierHop) HopBinding

func (h VerifierHop) HopBinding() [32]byte

HopBinding returns the verifier-owned record binding.

func (VerifierHop) MessageInstance

func (h VerifierHop) MessageInstance() uint64

MessageInstance returns the authenticated Message-Instance number.

func (VerifierHop) Recipe

Recipe returns the immutable Recipe descriptor.

func (VerifierHop) RecipeMode

func (h VerifierHop) RecipeMode() string

RecipeMode returns unchanged or applied.

func (VerifierHop) Sequence

func (h VerifierHop) Sequence() uint64

Sequence returns the authenticated signature sequence.

func (VerifierHop) SignatureAlgorithms

func (h VerifierHop) SignatureAlgorithms() []string

SignatureAlgorithms returns sorted unique successfully verified algorithms.

func (VerifierHop) SignerDomain

func (h VerifierHop) SignerDomain() string

SignerDomain returns the canonical verified signer domain.

func (VerifierHop) String

func (VerifierHop) String() string

String returns a constant representation without message-derived facts.

func (VerifierHop) Valid

func (h VerifierHop) Valid() bool

Valid reports whether the hop owns complete cloned evidence.

type VerifierOption

type VerifierOption func(*verifierConfig) error

VerifierOption narrows one validated verifier setting during construction.

func WithDomainPolicyProvider

func WithDomainPolicyProvider(provider DomainPolicyProvider) VerifierOption

WithDomainPolicyProvider selects the conforming Draft-09 Section 11.1 behavior with an explicit Domain Policy Record provider: a subdomain d= makes a parent From Authentic unless the From domain publishes f=strict.

func WithMaxCheckFacts

func WithMaxCheckFacts(limit int) VerifierOption

WithMaxCheckFacts narrows the retained public check-fact limit.

func WithMaxInstanceHashSets

func WithMaxInstanceHashSets(limit int) VerifierOption

WithMaxInstanceHashSets narrows the hash-set limit per Message-Instance field.

func WithMaxRawMessageBytes

func WithMaxRawMessageBytes(limit int) VerifierOption

WithMaxRawMessageBytes narrows the raw RFC 5322 message-size limit.

func WithMaxRecipients

func WithMaxRecipients(limit int) VerifierOption

WithMaxRecipients narrows the current SMTP recipient-count limit.

func WithMaxSignatureFacts

func WithMaxSignatureFacts(limit int) VerifierOption

WithMaxSignatureFacts narrows the retained public signature-set-fact limit.

func WithMaxSignatureSets

func WithMaxSignatureSets(limit int) VerifierOption

WithMaxSignatureSets narrows the signature-set limit per DKIM2-Signature field.

func WithObservationSink

func WithObservationSink(sink ObservationSink) VerifierOption

WithObservationSink injects one bounded nonnormative observation receiver.

func WithVerificationClock

func WithVerificationClock(clock func() time.Time) VerifierOption

WithVerificationClock injects the deterministic time source used by timestamp policy.

func WithoutSubdomainFromAuthorization

func WithoutSubdomainFromAuthorization() VerifierOption

WithoutSubdomainFromAuthorization selects the documented local policy that never uses the upward Authentic From match and never queries a Domain Policy Record. Messages that Draft-09 defines as PASS through a subdomain d= then FAIL with from_not_authentic.

type VerifierProjection

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

VerifierProjection is sealed complete-chain verifier evidence for policy consumers.

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

func (p VerifierProjection) Hops() []VerifierHop

Hops returns detached ordered chain records.

func (VerifierProjection) Schema

func (p VerifierProjection) Schema() string

Schema returns the stable 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 is complete and bounded.

type VerifierRecipeDescriptor

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

VerifierRecipeDescriptor is a privacy-minimized authenticated Recipe summary.

func (VerifierRecipeDescriptor) AffectedHeaderCount

func (d VerifierRecipeDescriptor) AffectedHeaderCount() int

AffectedHeaderCount returns the coherence count for AffectedHeaders.

func (VerifierRecipeDescriptor) AffectedHeaders

func (d VerifierRecipeDescriptor) AffectedHeaders() []string

AffectedHeaders returns sorted unique lower-case header names without values.

func (VerifierRecipeDescriptor) BodyMode

func (d VerifierRecipeDescriptor) BodyMode() string

BodyMode returns absent, steps, or unavailable.

func (VerifierRecipeDescriptor) ChangeClasses

func (d VerifierRecipeDescriptor) ChangeClasses() []string

ChangeClasses returns sorted unique conservative change classes.

func (VerifierRecipeDescriptor) ChangeCount

func (d VerifierRecipeDescriptor) ChangeCount() int

ChangeCount returns the number of normalized change dimensions.

func (VerifierRecipeDescriptor) Digest

func (d VerifierRecipeDescriptor) Digest() [32]byte

Digest returns the verifier-owned normalized descriptor binding.

func (VerifierRecipeDescriptor) Format

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

Format prevents formatting verbs from exposing message-derived facts.

func (VerifierRecipeDescriptor) GoString

func (VerifierRecipeDescriptor) GoString() string

GoString returns a constant representation without message-derived facts.

func (VerifierRecipeDescriptor) HasHeaderChanges

func (d VerifierRecipeDescriptor) HasHeaderChanges() bool

HasHeaderChanges reports whether any authenticated header dimension is present.

func (VerifierRecipeDescriptor) String

String returns a constant representation without message-derived facts.

func (VerifierRecipeDescriptor) Valid

func (d VerifierRecipeDescriptor) Valid() bool

Valid reports whether the descriptor is a closed bounded projection.

type VerifyRequest

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

VerifyRequest contains immutable raw RFC 5322 bytes and independent current SMTP envelope evidence.

func NewVerifyRequest

func NewVerifyRequest(rawMessage, reversePath []byte, forwardPaths [][]byte) VerifyRequest

NewVerifyRequest constructs a request by cloning every caller-owned byte slice.

func (VerifyRequest) Format

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

Format prevents formatting from traversing message or envelope bytes.

func (VerifyRequest) ForwardPaths

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

ForwardPaths returns independent copies of the current bracketed SMTP forward-paths.

func (VerifyRequest) GoString

func (VerifyRequest) GoString() string

GoString returns a constant representation without message or envelope bytes.

func (VerifyRequest) MarshalJSON

func (VerifyRequest) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization outside the explicitly generated REST request.

func (VerifyRequest) MarshalText

func (VerifyRequest) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of message or envelope bytes.

func (VerifyRequest) RawMessage

func (r VerifyRequest) RawMessage() []byte

RawMessage returns an independent copy of the authoritative RFC 5322 bytes.

func (VerifyRequest) ReversePath

func (r VerifyRequest) ReversePath() []byte

ReversePath returns an independent copy of the current bracketed SMTP reverse-path.

func (VerifyRequest) String

func (VerifyRequest) String() string

String returns a constant representation without message or envelope bytes.

type VerifyResult

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

VerifyResult is an immutable structured current-verification outcome.

func (VerifyResult) CheckCount

func (r VerifyResult) CheckCount() int

CheckCount returns the bounded number of retained check facts.

func (VerifyResult) Checks

func (r VerifyResult) Checks() []CheckFact

Checks returns an independent copy of the bounded check facts.

func (VerifyResult) CustodyStructure

func (r VerifyResult) CustodyStructure() CustodyStructure

CustodyStructure returns separately evaluated structural next-domain coverage.

func (VerifyResult) Draft

func (r VerifyResult) Draft() string

Draft returns the exact DKIM2 draft identifier governing this result.

func (VerifyResult) Format

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

Format prevents formatting from traversing sealed or message-derived facts.

func (VerifyResult) GoString

func (VerifyResult) GoString() string

GoString returns a constant representation without sealed or message-derived facts.

func (VerifyResult) HistoricalContent

func (r VerifyResult) HistoricalContent() HistoricalState

HistoricalContent returns the historical content and recipe coverage state.

func (VerifyResult) HistoricalSignatures

func (r VerifyResult) HistoricalSignatures() HistoricalState

HistoricalSignatures returns the historical cryptographic-signature coverage state.

func (VerifyResult) MarshalJSON

func (VerifyResult) MarshalJSON() ([]byte, error)

MarshalJSON rejects serialization outside explicit mapped response boundaries.

func (VerifyResult) MarshalText

func (VerifyResult) MarshalText() ([]byte, error)

MarshalText rejects diagnostic serialization of sealed verification facts.

func (VerifyResult) PrimaryReason

func (r VerifyResult) PrimaryReason() ReasonCode

PrimaryReason returns the deterministic highest-precedence bounded reason.

func (VerifyResult) Scope

func (r VerifyResult) Scope() VerificationScope

Scope returns the authenticated verification scope.

func (VerifyResult) SignatureSetCount

func (r VerifyResult) SignatureSetCount() int

SignatureSetCount returns the bounded number of retained signature-set facts.

func (VerifyResult) SignatureSets

func (r VerifyResult) SignatureSets() []SignatureSetFact

SignatureSets returns an independent copy of the bounded signature-set facts.

func (VerifyResult) State

func (r VerifyResult) State() ResultState

State returns one of the four public verification states.

func (VerifyResult) String

func (VerifyResult) String() string

String returns a constant representation without sealed or message-derived facts.

func (VerifyResult) Target

func (r VerifyResult) Target() VerificationTarget

Target returns the current verification target metadata.

func (VerifyResult) Valid

func (r VerifyResult) Valid() bool

Valid reports whether the result is a complete library-owned current-verification aggregate.

func (VerifyResult) VerifierProjection

func (r VerifyResult) VerifierProjection() (VerifierProjection, bool)

VerifierProjection returns detached complete-chain evidence when present.

Directories

Path Synopsis
Package admincontract owns the versioned provider-neutral datasource administration commitment grammar shared with external lifecycle writers.
Package admincontract owns the versioned provider-neutral datasource administration commitment grammar shared with external lifecycle writers.
Package authresults owns the bounded local Authentication-Results profile.
Package authresults owns the bounded local Authentication-Results profile.
cmd
dkim2-milter module
dkim2ctl module
dkim2d module
Package headerfold restores the fold points of daemon-projected DKIM2 header field values for adapters that write header fields themselves.
Package headerfold restores the fold points of daemon-projected DKIM2 header field values for adapters that write header fields themselves.
internal
canonical
Package canonical owns DKIM2 canonical byte transformations and digest result containers for the draft-ietf-dkim-dkim2-spec-09 baseline.
Package canonical owns DKIM2 canonical byte transformations and digest result containers for the draft-ietf-dkim-dkim2-spec-09 baseline.
combine
Package combine owns the Draft-09 AND/OR group structure shared by the Message-Instance h= (Section 9.3) and DKIM2-Signature s= (Section 10.9) tags: an ordered list of groups separated by "|", each an ordered list of sets separated by ",".
Package combine owns the Draft-09 AND/OR group structure shared by the Message-Instance h= (Section 9.3) and DKIM2-Signature s= (Section 10.9) tags: an ordered list of groups separated by "|", each an ordered list of sets separated by ",".
cryptodkim2
Package cryptodkim2 owns shared DKIM2 public-key validation and signature verification.
Package cryptodkim2 owns shared DKIM2 public-key validation and signature verification.
datasource
Package datasource owns storage-neutral profile and administrative-policy contracts without binding protocol code to provider models.
Package datasource owns storage-neutral profile and administrative-policy contracts without binding protocol code to provider models.
datasource/flatfile
Package flatfile decodes strict bounded versioned datasource documents into immutable in-memory snapshots.
Package flatfile decodes strict bounded versioned datasource documents into immutable in-memory snapshots.
datasource/memory
Package memory provides the immutable static datasource reference provider.
Package memory provides the immutable static datasource reference provider.
datasource/signingprofile
Package signingprofile is the sole bridge from validated datasource results to signing profiles.
Package signingprofile is the sole bridge from validated datasource results to signing profiles.
domainname
Package domainname owns the Draft-09 Section 18 conversion of protocol domain names from U-labels to A-labels.
Package domainname owns the Draft-09 Section 18 conversion of protocol domain names from U-labels to A-labels.
dsn
Package dsn parses the bounded MIME structure required before DKIM2 delivery-status evidence can be evaluated.
Package dsn parses the bounded MIME structure required before DKIM2 delivery-status evidence can be evaluated.
dsn/dsntest
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.
instance
Package instance parses Message-Instance header fields for the DKIM2 draft baseline draft-ietf-dkim-dkim2-spec-09.
Package instance parses Message-Instance header fields for the DKIM2 draft baseline draft-ietf-dkim-dkim2-spec-09.
keyresolver
Package keyresolver owns bounded DNS-02 query, TXT transport, key-record, decoding, cache, and coalesced-flight semantics.
Package keyresolver owns bounded DNS-02 query, TXT transport, key-record, decoding, cache, and coalesced-flight semantics.
mailbox
Package mailbox owns bounded parsing of RFC 5322 author address lists for DKIM2 From authenticity (Draft-09 Section 11).
Package mailbox owns bounded parsing of RFC 5322 author address lists for DKIM2 From authenticity (Draft-09 Section 11).
niliface
Package niliface detects unusable nil-backed interface dependencies.
Package niliface detects unusable nil-backed interface dependencies.
observability
Package observability defines bounded library observation events without binding protocol code to a telemetry implementation.
Package observability defines bounded library observation events without binding protocol code to a telemetry implementation.
policy
Package policy owns deterministic local decisions over sealed DKIM2 verification facts.
Package policy owns deterministic local decisions over sealed DKIM2 verification facts.
provider
Package provider owns the shared, cause-free classification for injected DKIM2 providers and authorizers.
Package provider owns the shared, cause-free classification for injected DKIM2 providers and authorizers.
rawmsg
Package rawmsg owns the raw RFC 5322 message representation used by DKIM2 protocol code.
Package rawmsg owns the raw RFC 5322 message representation used by DKIM2 protocol code.
recipe
Package recipe strictly parses, applies, and generates bounded DKIM2 message reconstruction recipes for draft-ietf-dkim-dkim2-spec-09.
Package recipe strictly parses, applies, and generates bounded DKIM2 message reconstruction recipes for draft-ietf-dkim-dkim2-spec-09.
replay
Package replay owns storage-neutral replay detection contracts and invariants.
Package replay owns storage-neutral replay detection contracts and invariants.
routeplan
Package routeplan owns bounded DKIM2 fanout planning and ticket state.
Package routeplan owns bounded DKIM2 fanout planning and ticket state.
service
Package service coordinates bounded current-message verification and maps protocol-core facts into deterministic four-state internal results.
Package service coordinates bounded current-message verification and maps protocol-core facts into deterministic four-state internal results.
signature
Package signature parses DKIM2-Signature header fields for the DKIM2 draft baseline draft-ietf-dkim-dkim2-spec-09.
Package signature parses DKIM2-Signature header fields for the DKIM2 draft baseline draft-ietf-dkim-dkim2-spec-09.
signing
Package signing owns shared signing-operation contracts, restrictive limits, usage accounting, and bounded error vocabulary for the DKIM2 draft baseline.
Package signing owns shared signing-operation contracts, restrictive limits, usage accounting, and bounded error vocabulary for the DKIM2 draft baseline.
tagvalue
Package tagvalue owns shared DKIM2 tag-list scanning rules.
Package tagvalue owns shared DKIM2 tag-list scanning rules.
verify
Package verify coordinates DKIM2 static-key verification contracts.
Package verify coordinates DKIM2 static-key verification contracts.
Package provider exposes storage-neutral datasource construction and lookup.
Package provider exposes storage-neutral datasource construction and lookup.
flatfile
Package flatfile exposes the explicit flat-file signing provider adapter.
Package flatfile exposes the explicit flat-file signing provider adapter.

Jump to

Keyboard shortcuts

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