Go: dnsid — errors

Generated from the Go source by scripts/gen-docs.sh — do not edit; run it to regenerate. Canonical deep reference: pkg.go.dev/github.com/dnsid-ai/dnsid-go. Guides and account setup: https://docs.dnsid.ai.

Part of the root package github.com/dnsid-ai/dnsid-go — see Core: IdentityManager for the package overview.

func MissingRequiredField

func MissingRequiredField(rec *TXTRecord) string

MissingRequiredField returns the first missing required non-signature DNSid TXT tag name, or "" if the unsigned record has all required signing inputs.

type AgentError

AgentError matches the OpenAPI AgentError schema.

type AgentError struct {
    Code        string `json:"code"`
    Title       string `json:"title"`
    Detail      string `json:"detail"`
    Remediation string `json:"remediation"`
}

type ArgumentError

ArgumentError is the shared SDK ArgumentError category.

type ArgumentError = sdkerrors.ArgumentError

func NewArgumentError

func NewArgumentError(msg string, cause error) *ArgumentError

NewArgumentError creates an argument error with an optional underlying cause.

type ParseError

ParseError is the shared SDK ParseError category.

type ParseError = sdkerrors.ParseError

func NewParseError

func NewParseError(msg string, cause error) *ParseError

NewParseError creates a parse error with an optional underlying cause.

type RegistryAPIError

RegistryAPIError represents a registry transport failure or non-2xx API response. The registry error schema uses fields “error” and “message”.

type RegistryAPIError struct {
    StatusCode int
    Code       string `json:"error,omitempty"`
    Message    string `json:"message,omitempty"`
    Cause      error  `json:"-"`
}

func (*RegistryAPIError) Error

func (e *RegistryAPIError) Error() string

Error implements error, formatting the HTTP status with the registry’s error code and message when present.

func (*RegistryAPIError) RetrySameEntry

func (e *RegistryAPIError) RetrySameEntry() bool

RetrySameEntry reports whether the registry requires retrying the exact submitted bytes with the same idempotency key. An unclassified HTTP 5xx is indeterminate and therefore also requires an exact-byte retry. Known terminal protocol errors override that transport-level fallback.

func (*RegistryAPIError) SubmissionState

func (e *RegistryAPIError) SubmissionState() SubmissionState

SubmissionState maps a prepared-event submission failure to the durable lifecycle state shared by managed coordinators.

func (*RegistryAPIError) Transient

func (e *RegistryAPIError) Transient() bool

Transient reports whether retrying the registry operation may succeed. Prepared-event callers must additionally honor RetrySameEntry so a retry never regenerates signed bytes.

func (*RegistryAPIError) Unwrap

func (e *RegistryAPIError) Unwrap() error

Unwrap returns the underlying transport failure, if any.

type RegistryWorkflowError

RegistryWorkflowError reports a terminal or interrupted registry workflow.

type RegistryWorkflowError struct {
    Registration *AgentRegistration
    Status       string
    Cause        error
}

func (*RegistryWorkflowError) Error

func (e *RegistryWorkflowError) Error() string

Error implements error, naming the terminal workflow status when the registration is available.

func (*RegistryWorkflowError) Unwrap

func (e *RegistryWorkflowError) Unwrap() error

Unwrap returns the cancellation or timeout that interrupted the workflow.

type ValidationError

ValidationError is returned when input parses successfully but fails a semantic or structural rule: required tags missing, FQDN normalization violations, policy-flag whitelist violations, host equality checks, etc. A ValidationError is always permanent.

type ValidationError struct {
    Message string
    Cause   error
}

func NewValidationError

func NewValidationError(msg string, cause error) *ValidationError

NewValidationError constructs a ValidationError wrapping cause with msg.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Error implements error.

func (*ValidationError) Is

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

Is matches any other *ValidationError. ValidationError is a category, not an identity: errors.Is(anyValidationError, anyOther) returns true. Use errors.As to read Message / Cause.

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error

Unwrap returns the wrapped cause, if any.

type VerificationCode

VerificationCode is a machine-readable classifier for *VerificationError. Codes group failures by cause so callers can branch on type without pattern-matching on error strings.

type VerificationCode string

Core verification codes defined by the language-agnostic SDK contract.

const (
    VerificationCodeDNSResolution     VerificationCode = "dns_resolution"
    VerificationCodeDNSSECFailed      VerificationCode = "dnssec_failed"
    VerificationCodeRecordInvalid     VerificationCode = "record_invalid"
    VerificationCodeSignatureInvalid  VerificationCode = "signature_invalid"
    VerificationCodeTLSError          VerificationCode = "tls_error"
    VerificationCodeKeyAgeExceeded    VerificationCode = "key_age_exceeded"
    VerificationCodeStatusUnavailable VerificationCode = "status_unavailable"
    VerificationCodeStatusNotActive   VerificationCode = "status_not_active"
    VerificationCodeLogError          VerificationCode = "log_error"
    // VerificationCodeCounterpartyNotAccepted reports that configured
    // VerificationConfig.TrustedEntities policy denied a counterparty whose
    // DNSid record verified. Always permanent.
    VerificationCodeCounterpartyNotAccepted VerificationCode = "counterparty_not_accepted"
)

Lifecycle log verification codes emitted when strict lifecycle state-machine enforcement rejects an agent’s log evidence. Values are the uppercase identifiers defined by the cross-SDK lifecycle contract.

const (
    VerificationCodeChainContinuity   VerificationCode = "CHAIN_CONTINUITY"
    VerificationCodeDuplicateIssuance VerificationCode = "DUPLICATE_ISSUANCE"
    VerificationCodeInvalidEvidence   VerificationCode = "INVALID_EVIDENCE"
    VerificationCodeIncompleteStream  VerificationCode = "INCOMPLETE_STREAM"
    VerificationCodeKeyContinuity     VerificationCode = "KEY_CONTINUITY"
    VerificationCodeInvalidMigration  VerificationCode = "INVALID_MIGRATION"
    VerificationCodeTerminalState     VerificationCode = "TERMINAL_STATE"
)

Application-profile codes retained for JOSE, HTTP-signature, and OIDC callers. Core VerifyDomain does not emit these codes.

VerificationCodeAudienceMismatch, VerificationCodeIssuerMismatch, and VerificationCodeLifetimeTooLong are specific claim-validation failures. They are children of VerificationCodeInvalidClaims for errors.Is purposes: an error with one of these codes also satisfies errors.Is(err, ErrInvalidClaims). See VerificationError.Is.

const (
    VerificationCodeKeyNotFound        VerificationCode = "key_not_found"
    VerificationCodeAgentNotFound      VerificationCode = "agent_not_found"
    VerificationCodeTokenExpired       VerificationCode = "token_expired"
    VerificationCodeTokenNotYetValid   VerificationCode = "token_not_yet_valid"
    VerificationCodeMalformedToken     VerificationCode = "malformed_token"
    VerificationCodeInvalidClaims      VerificationCode = "invalid_claims"
    VerificationCodeAudienceMismatch   VerificationCode = "audience_mismatch"
    VerificationCodeIssuerMismatch     VerificationCode = "issuer_mismatch"
    VerificationCodeLifetimeTooLong    VerificationCode = "lifetime_too_long"
    VerificationCodePolicyNotSatisfied VerificationCode = "policy_not_satisfied"
)

VerificationCodeJWKSUnavailable is a Go binding extension for JWKS fetch failures, which the core contract does not otherwise name.

const VerificationCodeJWKSUnavailable VerificationCode = "jwks_unavailable"

type VerificationError

VerificationError is returned when runtime verification fails: signature mismatch, JWKS fetch failure, status check failure, key not found, revoked agent, expired/invalid token, etc. The Code classifies the failure; Transient indicates whether retrying might succeed.

Fields are unexported and accessed via Code(), Transient(), AgentState(), and Message(). This prevents accidental mutation of the package-level sentinel values (ErrTokenExpired, ErrTXTRecordNotFound, etc.) that callers may obtain via errors.As. The wrapped cause is exposed via Unwrap().

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

func NewVerificationError

func NewVerificationError(code VerificationCode, transient bool, msg string, cause error, opts ...VerificationErrorOption) *VerificationError

NewVerificationError constructs a VerificationError.

func (*VerificationError) AgentState

func (e *VerificationError) AgentState() AgentState

AgentState returns the agent state recorded with this error, if any (populated when a status check returned a specific state).

func (*VerificationError) Code

func (e *VerificationError) Code() VerificationCode

Code returns the failure classifier.

func (*VerificationError) Error

func (e *VerificationError) Error() string

Error implements error.

func (*VerificationError) Is

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

Is matches another *VerificationError with the same Code. It also matches a sentinel exemplar whose Code is a parent category of the receiver’s Code (see invalidClaimsChildren). This lets callers compare against a sentinel — e.g. errors.Is(err, ErrTXTRecordNotFound) — without holding the original pointer, and lets specific claim errors satisfy the broader errors.Is(err, ErrInvalidClaims) check.

func (*VerificationError) Message

func (e *VerificationError) Message() string

Message returns the human-readable detail string.

func (*VerificationError) Transient

func (e *VerificationError) Transient() bool

Transient reports whether retrying might succeed.

func (*VerificationError) Unwrap

func (e *VerificationError) Unwrap() error

Unwrap returns the wrapped cause, if any.

func (*VerificationError) VerifiedEntityKeyThumbprint

func (e *VerificationError) VerifiedEntityKeyThumbprint() string

VerifiedEntityKeyThumbprint returns the observed verified record-signing key’s RFC 7638 SHA-256 thumbprint for a VerificationCodeCounterpartyNotAccepted error; empty for other codes.

func (*VerificationError) VerifiedGovernanceID

func (e *VerificationError) VerifiedGovernanceID() string

VerifiedGovernanceID returns the observed verified governance ID for a VerificationCodeCounterpartyNotAccepted error; empty for other codes.

type VerificationErrorOption

VerificationErrorOption configures optional fields on a VerificationError.

type VerificationErrorOption func(*VerificationError)

func WithAgentState

func WithAgentState(state AgentState) VerificationErrorOption

WithAgentState attaches an agent state to a VerificationError. Used when a status check returned a specific state (e.g. “revoked”).

func WithVerifiedIdentity

func WithVerifiedIdentity(governanceID, entityKeyThumbprint string) VerificationErrorOption

WithVerifiedIdentity records the observed verified governance ID and record-signing key thumbprint on a counterparty acceptance denial. It never carries configured allowlist or pin values.