Skip to content
DNSid Docs

Go: package c2sptlog

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/log/c2sptlog. Guides and account setup: https://docs.dnsid.ai.

import "github.com/dnsid-ai/dnsid-go/log/c2sptlog"

Package c2sptlog binds DNSid lifecycle logs to C2SP transparency logs: it reads, verifies, and writes DNSid lifecycle events stored as entries in a tiled Merkle log that follows the C2SP tlog-tiles, tlog-checkpoint, tlog-witness, and tlog-policy specifications (see PinnedSpecificationVersions for the exact pinned versions).

The log method is “c2sp-tlog”. An identity record references a stream with an lr value of the form c2sp-tlog:<scope>:<log-prefix>#<stream-id> (Reference); individual entries are addressed by appending @<index>. Client implements the log package’s LogReader interface on top of a Source that supplies inclusion-proven entries, a Policy that verifies signed checkpoints and witness cosignature quorums, and an optional Appender for writes. NewVerificationRegistry provides the standard verification setup:

registry, err := c2sptlog.NewVerificationRegistry(ctx,
  c2sptlog.VerificationRegistryConfig{
    PolicyURL:      "https://policy.example/dnsid-policy",
    ExpectedOrigin: "tlog.example/log", // Reference.Origin of the record's lr
  })

A parsed TrustProfile may instead bind one exact scope and log prefix to its policy and accepted bundle signers; profiles are independently distributed rather than discovered from the log. NewDnsidManagedVerificationRegistry is the separately named, opt-in factory for SDK-embedded Identity Digital trust roots; the generic factory never selects those roots implicitly. The policy URL is caller-selected trusted configuration and is never derived from an unverified log reference. The factory uses one bounded, redirect-free, rebinding-resistant ResourceFetcher for policy and standard log resources; custom fetchers must declare all public-read SecurityGuarantees. Supplying independently trusted BundleVerifiers and MaxBundleLifetime makes verified per-domain stream bundles the preferred source; RequireStreamBundle disables raw-scan fallback for deployment checks. Configure CheckpointMaxAge to enable fresh logged-state and non-revocation checks, which otherwise fail closed. Advanced deployments can compose ParsePolicy, NewScanSource, Register, and a durable checkpoint store directly.

Every event is an entity- or operational-key-signed JCS-canonical JSON envelope. Verification replays a domain’s entries in log order, checks the lifecycle signature chain (ISSUANCE bilateral signatures, rotation old-key/new-key signatures, entity signatures on later events), and logical predecessor metadata (Chain) in every scope. EventID excludes signatures; signature-only copies never advance state. Indexes and exact complete entry bytes remain inclusion evidence. DNSidMethodRevision pins this breaking pre-1.0 correction; old index/leaf chains are not accepted. A TrustedC2spCheckpointStore protects verified checkpoints against rollback.

Multi-party signing flows use PreparedEvent: Client.PrepareEvent builds the unsigned envelope, Client.SignPreparedEvent collects each SignerRole signature, and Client.WritePreparedEvent appends the exact signed bytes. VerifyStreamBundle verifies an offline, producer-signed evidence bundle without network access. RebuildHistoryThrough supplies exact-cutoff source evidence for caller-configured migration verification, including valid later copies of the final logical event.

See https://docs.dnsid.ai for protocol guides and account setup.

Index

Section titled “Index”

Constants

Section titled “Constants”

const (
    // StreamBundleType is the required "type" value of a stream bundle.
    StreamBundleType = "dnsid-c2sp-stream-bundle"
    // StreamBundleVersion is the bundle format version this package
    // produces and accepts.
    StreamBundleVersion = 1
    // StreamBundleTrustedIndex is the only supported completeness mode: the
    // producer asserts the bundle is complete through the checkpoint size.
    StreamBundleTrustedIndex = "trusted-index"
)

const (
    // Method is the DNSid log method name this package registers.
    Method = "c2sp-tlog"
    // Kind is the required "kind" value in every c2sp-tlog event envelope.
    Kind = "dnsid.lifecycle"
)

Exact C2SP versions and source revisions implemented by this binding. Source revisions identify the named specification file in C2SP/C2SP.

const (
    C2SPCheckpointSpecification  = "https://c2sp.org/tlog-checkpoint@v1.0.0"
    C2SPTilesSpecification       = "https://c2sp.org/tlog-tiles@v0.1.0"
    C2SPProofRevision            = "ab17a74116563005f908b9167e6421cc929a5c2b"
    C2SPPolicyRevision           = "1896a5aea5559b3203d275d0206d872f59348cf5"
    C2SPWitnessSpecification     = "https://c2sp.org/tlog-witness@v1.0.0"
    C2SPCosignatureSpecification = "https://c2sp.org/tlog-cosignature@v1.0.1"
    C2SPMirrorRevision           = "d0fe789122c75b903bfc1680b0b8b8dc570f0db3"
    C2SPSignedNoteSpecification  = "https://c2sp.org/signed-note@v1.0.0"
    DNSidEventEnvelopeVersion    = 1
    // DNSidMethodRevision pins the breaking logical-identity contract in dnsid-ietf-spec.
    DNSidMethodRevision = "d5a65d06f76eff4db81e50f8767a600d2ca7fc2a"
)

func Canonical

Section titled “func Canonical”
func Canonical(event dnsidlog.LogEvent) ([]byte, error)

Canonical returns the canonical JCS signing bytes for event without any stream context. Use Client.Canonical when the event is destined for a specific stream, since all streams contextualize the signed payload.

func CanonicalFromEntry

Section titled “func CanonicalFromEntry”
func CanonicalFromEntry(entry []byte) (canonicalResult []byte, errResult error)

CanonicalFromEntry recovers the signed bytes from stored entry bytes by stripping the signatures and re-canonicalizing. It returns an error if entry is empty, oversized, or not canonical JCS.

func EntryBytes

Section titled “func EntryBytes”
func EntryBytes(event dnsidlog.LogEvent) ([]byte, error)

EntryBytes returns the canonical entry bytes for event, including its signatures, without any stream context. It returns an error if the event has no signatures or exceeds the maximum entry size. Use Client.EntryBytes for stream-contextualized entries.

func EventID

Section titled “func EventID”
func EventID(signedBytes []byte) string

EventID derives logical identity from canonical signing bytes, not signatures or leaf evidence.

func GenerateStreamID

Section titled “func GenerateStreamID”
func GenerateStreamID() (string, error)

GenerateStreamID returns an opaque identity-instance stream identifier with 128 bits of cryptographically secure randomness, encoded as unpadded base64url. Callers must generate a new value for each replacement identity.

func LeafHash

Section titled “func LeafHash”
func LeafHash(entry []byte) tlog.Hash

LeafHash returns the RFC 6962 leaf hash of exact entry bytes, as used for inclusion-proof verification, not logical event identity.

func LogEventFromEntry

Section titled “func LogEventFromEntry”
func LogEventFromEntry(entry []byte) (eventResult dnsidlog.LogEvent, errResult error)

LogEventFromEntry parses stored entry bytes into the shared lifecycle event representation. The entry must be canonical JCS with a complete, well-formed signature set and valid lifecycle fields; the signatures themselves are not cryptographically verified.

func NewDnsidManagedVerificationRegistry

Section titled “func NewDnsidManagedVerificationRegistry”
func NewDnsidManagedVerificationRegistry(ctx context.Context, config DnsidManagedVerificationConfig) (*dnsidlog.LogRegistry, error)

NewDnsidManagedVerificationRegistry creates a LogRegistry for the reviewed, SDK-embedded trust roots of DNSid-managed DNSid logs. Calling this separately named factory is an explicit application trust decision; the generic NewVerificationRegistry never selects these roots implicitly.

Development and production verification prefer signed stream bundles with safe raw-scan fallback. The default checkpoint store is restart-ephemeral; deployments needing rollback protection across restarts should inject durable storage and retain the returned registry for the process lifetime.

func NewVerificationRegistry

Section titled “func NewVerificationRegistry”
func NewVerificationRegistry(ctx context.Context, config VerificationRegistryConfig) (*dnsidlog.LogRegistry, error)

NewVerificationRegistry creates a LogRegistry ready for verification of c2sp-tlog lifecycle references. It loads and parses the caller-selected trust policy, configures the bounded standard tiled-log scanner, and installs a process-lifetime checkpoint store unless the caller supplies a durable one.

PolicyURL is trusted configuration, not discovery. Applications must not derive it from an unverified identity record or from the log prefix itself. Advanced deployments with private transports or custom stream sources should compose ParsePolicy, NewScanSource, and Register directly.

func Register

Section titled “func Register”
func Register(registry *dnsidlog.LogRegistry, opts ...Option) error

Register installs the “c2sp-tlog” method in registry so that LogRegistry.NewReader builds a Client (with opts applied) for every c2sp-tlog lr value. It returns an error if registry is nil; an lr value that fails to parse yields a reader whose every method returns that parse error.

type Appender

Section titled “type Appender”

Appender appends exact canonical entry bytes to the log and returns the index assigned to the new entry.

type Appender interface {
    Append(ctx context.Context, entry []byte) (uint64, error)
}

type ApplicationSigningController

Section titled “type ApplicationSigningController”

ApplicationSigningController pauses or resumes new application signatures.

type ApplicationSigningController interface {
    SetApplicationSigningPaused(context.Context, bool) error
}

type ApplicationSigningControllerFunc

Section titled “type ApplicationSigningControllerFunc”

ApplicationSigningControllerFunc adapts a function to ApplicationSigningController.

type ApplicationSigningControllerFunc func(context.Context, bool) error

func (ApplicationSigningControllerFunc) SetApplicationSigningPaused

Section titled “func (ApplicationSigningControllerFunc) SetApplicationSigningPaused”
func (f ApplicationSigningControllerFunc) SetApplicationSigningPaused(ctx context.Context, paused bool) error

SetApplicationSigningPaused calls f to update application-signing state.

type BoundedResourceFetcher

Section titled “type BoundedResourceFetcher”

BoundedResourceFetcher fetches one resource while enforcing maxBytes during the read. Implementations must honor ctx cancellation and accurately report their transport properties through SecurityGuarantees. A supplied fetcher is trusted caller infrastructure; the SDK still checks the returned length.

type BoundedResourceFetcher interface {
    FetchBounded(ctx context.Context, rawURL string, maxBytes int64) ([]byte, error)
    SecurityGuarantees() ResourceFetchGuarantees
}

type C2spConsistencyProofSource

Section titled “type C2spConsistencyProofSource”

C2spConsistencyProofSource supplies an RFC 6962 consistency proof between two checkpoint sizes. Implementations return untrusted hashes.

type C2spConsistencyProofSource interface {
    FetchConsistencyProof(ctx context.Context, reference Reference, fromSize, toSize uint64) ([][]byte, error)
}

type C2spFullLogSource

Section titled “type C2spFullLogSource”

C2spFullLogSource supplies all raw entries in [0, treeSize). It is an optional fallback for proving an old prefix when no consistency-proof source is available. The SDK recomputes both roots; the source is not trusted.

type C2spFullLogSource interface {
    FetchEntriesThrough(ctx context.Context, reference Reference, treeSize uint64) ([][]byte, error)
}

type Chain

Section titled “type Chain”

Chain is c2sp-tlog logical predecessor metadata for every scope. Sequence is zero for genesis; successors name the preceding event’s ID (excluding signatures) and computed state hash. Derive values with Client.ChainForWrite; log indexes and leaf hashes are inclusion evidence only.

type Chain struct {
    Sequence          uint64
    PreviousEventID   string
    PreviousStateHash string
}

type CheckpointAdvanceError

Section titled “type CheckpointAdvanceError”

CheckpointAdvanceError rejects a candidate without replacing trusted state. Root hashes are copied from the checkpoints. Fetch and storage errors retain their original types instead of being classified as inconsistent evidence.

type CheckpointAdvanceError struct {
    Kind        CheckpointAdvanceErrorKind
    Origin      string
    OldTreeSize uint64
    NewTreeSize uint64
    OldRootHash []byte
    NewRootHash []byte
    // SplitView means an observed equal-size root conflict, not proven malice.
    // False never authorizes recovery or implies the failure is safe.
    SplitView bool
    Cause     error
}

func (*CheckpointAdvanceError) Error

Section titled “func (*CheckpointAdvanceError) Error”
func (e *CheckpointAdvanceError) Error() string

func (*CheckpointAdvanceError) Transient

Section titled “func (*CheckpointAdvanceError) Transient”
func (e *CheckpointAdvanceError) Transient() bool

Transient is false: retrying must never reset checkpoint trust.

func (*CheckpointAdvanceError) Unwrap

Section titled “func (*CheckpointAdvanceError) Unwrap”
func (e *CheckpointAdvanceError) Unwrap() error

Unwrap preserves the underlying evidence verification failure.

type CheckpointAdvanceErrorKind

Section titled “type CheckpointAdvanceErrorKind”

CheckpointAdvanceErrorKind describes an observed continuity failure, not its cause.

type CheckpointAdvanceErrorKind string

const (
    // CheckpointAdvanceRollback indicates a smaller candidate tree.
    CheckpointAdvanceRollback CheckpointAdvanceErrorKind = "rollback"
    // CheckpointAdvanceRootConflict indicates different roots at equal sizes.
    CheckpointAdvanceRootConflict CheckpointAdvanceErrorKind = "root_conflict"
    // CheckpointAdvanceConsistencyFailed indicates invalid supplied proof or scan evidence.
    CheckpointAdvanceConsistencyFailed CheckpointAdvanceErrorKind = "consistency_failed"
    // CheckpointAdvanceConsistencyUnavailable indicates no supported consistency source.
    CheckpointAdvanceConsistencyUnavailable CheckpointAdvanceErrorKind = "consistency_unavailable"
)

type Client

Section titled “type Client”

Client binds one c2sp-tlog stream reference to a Source, Policy, and optional Appender. It implements the log package’s LogReader, LifecycleBindingVerifier, and Log interfaces: reads verify inclusion proofs, lifecycle signatures, and logical stream-chain metadata before any event is returned. Methods on a nil *Client return errors rather than panicking.

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

func New

Section titled “func New”
func New(lr string, opts ...Option) (*Client, error)

New constructs a Client bound to the parsed lr value. It returns an error if lr is not a valid c2sp-tlog reference. Missing collaborators are not an error here: operations that need an absent Source or Appender fail when called.

func (*Client) AppendPreparedEntry

Section titled “func (*Client) AppendPreparedEntry”
func (c *Client) AppendPreparedEntry(ctx context.Context, entry []byte) (dnsidlog.LogRef, error)

AppendPreparedEntry parses and safely writes canonical prepared bytes. Deprecated: use ParsePreparedEvent and WritePreparedEvent directly.

func (*Client) Canonical

Section titled “func (*Client) Canonical”
func (c *Client) Canonical(event dnsidlog.LogEvent) ([]byte, error)

Canonical returns the canonical JCS bytes that lifecycle signatures for event are computed over, contextualized with the client’s reference and excluding signatures. ISSUANCE and inbound MIGRATION events derive seq=0; later events require CanonicalWithChain.

func (*Client) CanonicalWithChain

Section titled “func (*Client) CanonicalWithChain”
func (c *Client) CanonicalWithChain(event dnsidlog.LogEvent, chain Chain) ([]byte, error)

CanonicalWithChain is Canonical with caller-supplied logical stream-chain metadata, as required for non-genesis events in every scope.

func (*Client) ChainForWrite

Section titled “func (*Client) ChainForWrite”
func (c *Client) ChainForWrite(ctx context.Context, event dnsidlog.LogEvent) (Chain, error)

ChainForWrite derives the logical stream-chain metadata for event from the client’s verified history. ISSUANCE derives seq=0 without reading history.

func (*Client) EntryBytes

Section titled “func (*Client) EntryBytes”
func (c *Client) EntryBytes(event dnsidlog.LogEvent) ([]byte, error)

EntryBytes returns the canonical, fully contextualized entry bytes without appending them. ISSUANCE entries receive seq=0; later events require EntryBytesWithChain.

func (*Client) EntryBytesWithChain

Section titled “func (*Client) EntryBytesWithChain”
func (c *Client) EntryBytesWithChain(event dnsidlog.LogEvent, chain Chain) ([]byte, error)

EntryBytesWithChain returns canonical contextualized entry bytes with the caller-supplied logical stream-chain metadata, without appending them.

func (*Client) KeyTimestamp

Section titled “func (*Client) KeyTimestamp”
func (c *Client) KeyTimestamp(ctx context.Context, domain, keyThumbprint string) (timestamp time.Time, err error)

KeyTimestamp returns the signed event timestamp of the verified event that bound keyThumbprint for domain. Inclusion verification has already enforced that this timestamp does not exceed the accepted log timestamp. It returns an error if keyThumbprint is not the currently active operational key.

func (*Client) ParsePreparedEvent

Section titled “func (*Client) ParsePreparedEvent”
func (c *Client) ParsePreparedEvent(entry []byte) (*PreparedEvent, error)

ParsePreparedEvent treats received bytes as untrusted, canonicalizes the envelope independently, and preserves unknown signed fields.

func (*Client) PrepareEvent

Section titled “func (*Client) PrepareEvent”
func (c *Client) PrepareEvent(event dnsidlog.LogEvent) (*PreparedEvent, error)

PrepareEvent builds an unsigned method-specific envelope. ISSUANCE and inbound MIGRATION derive seq=0; later events use PrepareEventWithChain.

func (*Client) PrepareEventWithChain

Section titled “func (*Client) PrepareEventWithChain”
func (c *Client) PrepareEventWithChain(event dnsidlog.LogEvent, chain Chain) (*PreparedEvent, error)

PrepareEventWithChain is PrepareEvent with caller-supplied public stream-chain metadata, as required for non-genesis events in every scope.

func (*Client) PreparedEntryBytes

Section titled “func (*Client) PreparedEntryBytes”
func (c *Client) PreparedEntryBytes(ctx context.Context, prepared *PreparedEvent) (result []byte, err error)

PreparedEntryBytes returns exact canonical bytes after validating all required signatures. It never appends.

func (*Client) ReadEvent

Section titled “func (*Client) ReadEvent”
func (c *Client) ReadEvent(ctx context.Context, ref dnsidlog.LogRef) (event dnsidlog.LogEvent, err error)

ReadEvent reads and verifies the single event addressed by a final event reference <lr>@<index>. The entry’s inclusion proof must verify, its index must match the reference, and the entry must appear in the domain’s verified lifecycle history; otherwise an error is returned.

func (*Client) RebuildHistory

Section titled “func (*Client) RebuildHistory”
func (c *Client) RebuildHistory(ctx context.Context, domain string) ([]dnsidlog.LogEvent, error)

RebuildHistory returns domain’s verified lifecycle events in log order. Each event’s inclusion proof, signature chain, and logical stream-chain metadata are verified; with a GlobalCandidateSource, invalid or unrelated candidates are skipped rather than fatal.

func (*Client) RebuildHistoryThrough

Section titled “func (*Client) RebuildHistoryThrough”
func (c *Client) RebuildHistoryThrough(ctx context.Context, domain string, finalRef dnsidlog.LogRef) (result MigrationVerificationResult, err error)

RebuildHistoryThrough verifies an exact signed migration cutoff. It can be called by an injected MigrationVerifier after selecting the source’s trust configuration. Later source events are not imported. A valid later copy of the final logical event is allowed; its exact occurrence evidence is retained.

func (*Client) SignPreparedEvent

Section titled “func (*Client) SignPreparedEvent”
func (c *Client) SignPreparedEvent(ctx context.Context, prepared *PreparedEvent, role SignerRole, kp dnsid.KeyProvider) (*PreparedEvent, error)

SignPreparedEvent validates every signature already present and adds exactly one role signature. ctx is used when historical stream keys are required.

func (*Client) SignPreparedEventWithKey

Section titled “func (*Client) SignPreparedEventWithKey”
func (c *Client) SignPreparedEventWithKey(ctx context.Context, prepared *PreparedEvent, role SignerRole, kp dnsid.KeyProvider, kid string) (*PreparedEvent, error)

SignPreparedEventWithKey validates every signature already present and adds role using the named active or pending key. It is intended for transitions such as KEY_ROTATION whose new-key proof must be made before activation.

func (*Client) VerifyBilateralBinding

Section titled “func (*Client) VerifyBilateralBinding”
func (c *Client) VerifyBilateralBinding(ctx context.Context, input dnsidlog.BilateralBindingInput) (binding dnsidlog.BilateralBinding, err error)

VerifyBilateralBinding verifies the signed ISSUANCE event against the current DNS record material and returns its trusted continuity anchor.

func (*Client) VerifyGovernanceRelationship

Section titled “func (*Client) VerifyGovernanceRelationship”
func (c *Client) VerifyGovernanceRelationship(ctx context.Context, domain, governanceID string) (err error)

VerifyGovernanceRelationship verifies that a verified ISSUANCE event for domain names governanceID as the governing organization.

func (*Client) VerifyLifecycleBinding

Section titled “func (*Client) VerifyLifecycleBinding”
func (c *Client) VerifyLifecycleBinding(ctx context.Context, input dnsidlog.BilateralBindingInput, currentOperationalThumbprint string) (binding dnsidlog.BilateralBinding, err error)

VerifyLifecycleBinding verifies the bilateral ISSUANCE binding and operational continuity over one verified lifecycle snapshot.

func (*Client) VerifyNonRevocation

Section titled “func (*Client) VerifyNonRevocation”
func (c *Client) VerifyNonRevocation(ctx context.Context, domain string, at time.Time) (evidence dnsidlog.LoggedStateEvidence, err error)

VerifyNonRevocation verifies that domain’s identity was neither revoked nor retired as of time at. It requires the configured Source to implement CompleteSource, because proving the absence of a REVOCATION entry needs a complete view of the stream and a positive maximum checkpoint age; without either it fails closed. Success returns the exact accepted proof boundaries, including every prior stream imported by migration.

func (*Client) VerifyOperationalContinuity

Section titled “func (*Client) VerifyOperationalContinuity”
func (c *Client) VerifyOperationalContinuity(ctx context.Context, domain, initialOperationalThumbprint, currentOperationalThumbprint string) (err error)

VerifyOperationalContinuity verifies that the current operational key is connected to the ISSUANCE key by the validated rotation chain.

func (*Client) WriteEvent

Section titled “func (*Client) WriteEvent”
func (c *Client) WriteEvent(ctx context.Context, event dnsidlog.LogEvent) (dnsidlog.LogRef, error)

WriteEvent canonicalizes, validates, and appends a fully signed lifecycle event, returning the final event reference <lr>@<index>. In every scope, only ISSUANCE and inbound MIGRATION events can be written this way (they derive seq=0); later events must supply chain metadata via WriteEventWithChain.

func (*Client) WriteEventWithChain

Section titled “func (*Client) WriteEventWithChain”
func (c *Client) WriteEventWithChain(ctx context.Context, event dnsidlog.LogEvent, chain Chain) (dnsidlog.LogRef, error)

WriteEventWithChain is WriteEvent with caller-supplied logical stream-chain metadata, as required for non-genesis events in every scope. The chain is validated against the verified history before the entry is appended.

func (*Client) WritePreparedEvent

Section titled “func (*Client) WritePreparedEvent”
func (c *Client) WritePreparedEvent(ctx context.Context, prepared *PreparedEvent) (dnsidlog.LogRef, error)

WritePreparedEvent validates and appends the exact prepared bytes unchanged.

type CompleteHistoryResult

Section titled “type CompleteHistoryResult”

CompleteHistoryResult binds one complete history read to the exact accepted checkpoint and completeness mechanism that produced it. FreshnessTime is informational; Client independently verifies Checkpoint under its Policy.

type CompleteHistoryResult struct {
    Entries          []ProvenEntry
    Checkpoint       []byte
    CompleteThrough  uint64
    CompletenessMode string
    FreshnessTime    time.Time
}

type CompleteSource

Section titled “type CompleteSource”

CompleteSource is a Source that can additionally return every entry for the domain together with the exact completeness boundary. Non-revocation verification requires a CompleteSource, since a missing REVOCATION entry would otherwise be undetectable.

type CompleteSource interface {
    Source
    // RebuildCompleteHistory returns one checkpoint-bound complete history.
    RebuildCompleteHistory(ctx context.Context, lr Reference, domain string) (CompleteHistoryResult, error)
}

type DnsidManagedVerificationConfig

Section titled “type DnsidManagedVerificationConfig”

DnsidManagedVerificationConfig configures shared infrastructure for NewDnsidManagedVerificationRegistry. Trust roots, freshness, resource limits, and bundle requirements are fixed by the managed catalog; callers needing different policy use NewVerificationRegistry.

type DnsidManagedVerificationConfig struct {
    // ResourceFetcher is shared by every managed log reader. When nil, the
    // standard safe bounded fetcher is used.
    ResourceFetcher BoundedResourceFetcher
    // TrustedCheckpointStore is shared by every managed log reader. When nil,
    // an in-memory store protects against rollback for this registry's lifetime.
    TrustedCheckpointStore TrustedC2spCheckpointStore
}

type GlobalCandidateSource

Section titled “type GlobalCandidateSource”

GlobalCandidateSource marks a Source whose RebuildHistory result is a set of candidates scanned from a global log. Invalid and unrelated candidates are ignored; failures returned by the source itself remain fatal. Sources that return selected-stream evidence remain strict by default.

type GlobalCandidateSource interface {
    Source
    // GlobalCandidates reports whether RebuildHistory results are unfiltered
    // candidates from a global log rather than a selected stream.
    GlobalCandidates() bool
}

type ManagedIssuanceActivationController

Section titled “type ManagedIssuanceActivationController”

ManagedIssuanceActivationController prevents ACTIVE publication while the bilateral ISSUANCE outcome is unresolved.

type ManagedIssuanceActivationController interface {
    SetManagedIssuanceActivationBlocked(context.Context, bool) error
}

type ManagedIssuanceActivationControllerFunc

Section titled “type ManagedIssuanceActivationControllerFunc”

ManagedIssuanceActivationControllerFunc adapts a function to the activation controller interface.

type ManagedIssuanceActivationControllerFunc func(context.Context, bool) error

func (ManagedIssuanceActivationControllerFunc) SetManagedIssuanceActivationBlocked

Section titled “func (ManagedIssuanceActivationControllerFunc) SetManagedIssuanceActivationBlocked”
func (f ManagedIssuanceActivationControllerFunc) SetManagedIssuanceActivationBlocked(ctx context.Context, blocked bool) error

SetManagedIssuanceActivationBlocked calls f.

type ManagedIssuanceInProgressError

Section titled “type ManagedIssuanceInProgressError”

ManagedIssuanceInProgressError reports that durable state already owns the identity instance, so a fresh ISSUANCE must not be generated.

type ManagedIssuanceInProgressError struct {
    Issuance *ManagedIssuanceState
}

func (*ManagedIssuanceInProgressError) Error

Section titled “func (*ManagedIssuanceInProgressError) Error”
func (e *ManagedIssuanceInProgressError) Error() string

type ManagedIssuanceOperationError

Section titled “type ManagedIssuanceOperationError”

ManagedIssuanceOperationError reports a preparation or submission failure. State and retry flags are stable management semantics; RetrySameBytes is true only after completed bytes have been fixed and must be replayed unchanged.

type ManagedIssuanceOperationError struct {
    Issuance         *ManagedIssuanceState
    State            dnsid.SubmissionState
    TransientFailure bool
    RetrySameBytes   bool
    Err              error
}

func (*ManagedIssuanceOperationError) Error

Section titled “func (*ManagedIssuanceOperationError) Error”
func (e *ManagedIssuanceOperationError) Error() string

func (*ManagedIssuanceOperationError) ShouldRetrySameBytes

Section titled “func (*ManagedIssuanceOperationError) ShouldRetrySameBytes”
func (e *ManagedIssuanceOperationError) ShouldRetrySameBytes() bool

ShouldRetrySameBytes reports whether recovery must resubmit the exact persisted bytes with the same idempotency key.

func (*ManagedIssuanceOperationError) Transient

Section titled “func (*ManagedIssuanceOperationError) Transient”
func (e *ManagedIssuanceOperationError) Transient() bool

Transient reports whether retrying the operation may succeed.

func (*ManagedIssuanceOperationError) Unwrap

Section titled “func (*ManagedIssuanceOperationError) Unwrap”
func (e *ManagedIssuanceOperationError) Unwrap() error

type ManagedIssuanceOptions

Section titled “type ManagedIssuanceOptions”

ManagedIssuanceOptions configures a new registry-managed split ISSUANCE.

type ManagedIssuanceOptions struct {
    Domain            string
    GovernanceID      string
    Client            *Client
    EntityPublicKey   jwk.Key
    KeyProvider       dnsid.KeyProvider
    RegistryClient    dnsid.RegistryPreparedEventClient
    IdempotencyKey    string
    Store             ManagedIssuanceStore
    ActivationControl ManagedIssuanceActivationController
}

type ManagedIssuanceState

Section titled “type ManagedIssuanceState”

ManagedIssuanceState is the durable recovery record for one registry-managed ISSUANCE. Once EntryBytes is set it is immutable and every retry reuses it with IdempotencyKey.

type ManagedIssuanceState struct {
    Domain                string                  `json:"domain"`
    GovernanceID          string                  `json:"governance_id"`
    LogReference          string                  `json:"log_reference"`
    EntityThumbprint      string                  `json:"entity_thumbprint"`
    OperationalKid        string                  `json:"operational_kid"`
    OperationalThumbprint string                  `json:"operational_thumbprint"`
    EntryBytes            []byte                  `json:"entry_bytes,omitempty"`
    EntryHash             string                  `json:"entry_hash,omitempty"`
    IdempotencyKey        string                  `json:"idempotency_key"`
    Submission            *dnsid.SubmissionResult `json:"submission,omitempty"`
    LastErrorCode         string                  `json:"last_error_code,omitempty"`
    TerminalFailure       bool                    `json:"terminal_failure"`
    Complete              bool                    `json:"complete"`
    ActivationBlocked     bool                    `json:"activation_blocked"`
}

func BeginManagedIssuance

Section titled “func BeginManagedIssuance”
func BeginManagedIssuance(ctx context.Context, opts ManagedIssuanceOptions) (*ManagedIssuanceState, error)

BeginManagedIssuance starts one durable split ISSUANCE. Any existing state for the domain blocks preparation, including a completed issuance.

func CompleteManagedIssuance

Section titled “func CompleteManagedIssuance”
func CompleteManagedIssuance(ctx context.Context, domain string, store ManagedIssuanceStore, activation ManagedIssuanceActivationController) (*ManagedIssuanceState, error)

CompleteManagedIssuance marks publication/setup convergence complete and releases the activation block. It requires an accepted exact-byte result. Callers invoke it only after externally verifying required DNS, JWKS, and status resources; this log coordinator does not publish those resources.

func ResumeManagedIssuance

Section titled “func ResumeManagedIssuance”
func ResumeManagedIssuance(ctx context.Context, opts ResumeManagedIssuanceOptions) (*ManagedIssuanceState, error)

ResumeManagedIssuance resumes preparation with the same idempotency key when no completed bytes exist, or resubmits the exact persisted bytes otherwise.

type ManagedIssuanceStore

Section titled “type ManagedIssuanceStore”

ManagedIssuanceStore provides exclusive durable state for one identity instance. CreateManagedIssuance atomically persists initial when no operation exists and returns the existing operation otherwise.

type ManagedIssuanceStore interface {
    CreateManagedIssuance(context.Context, *ManagedIssuanceState) (*ManagedIssuanceState, error)
    LoadManagedIssuance(context.Context, string) (*ManagedIssuanceState, error)
    PersistManagedIssuance(context.Context, *ManagedIssuanceState) error
}

type ManagedKeyRotationActivationError

Section titled “type ManagedKeyRotationActivationError”

ManagedKeyRotationActivationError reports accepted registry submission with incomplete local activation, supersession, pause release, or persistence.

type ManagedKeyRotationActivationError struct {
    Rotation *ManagedKeyRotationState
    Err      error
}

func (*ManagedKeyRotationActivationError) Error

Section titled “func (*ManagedKeyRotationActivationError) Error”
func (e *ManagedKeyRotationActivationError) Error() string

func (*ManagedKeyRotationActivationError) Unwrap

Section titled “func (*ManagedKeyRotationActivationError) Unwrap”
func (e *ManagedKeyRotationActivationError) Unwrap() error

type ManagedKeyRotationOptions

Section titled “type ManagedKeyRotationOptions”

ManagedKeyRotationOptions configures a new managed operational-key rotation. Store and ApplicationSigning are mandatory durability and safety boundaries.

type ManagedKeyRotationOptions struct {
    Domain             string
    Client             *Client
    KeyProvider        dnsid.KeyProvider
    RegistryClient     dnsid.RegistryPreparedEventClient
    IdempotencyKey     string
    Store              ManagedKeyRotationStore
    ApplicationSigning ApplicationSigningController
}

type ManagedKeyRotationState

Section titled “type ManagedKeyRotationState”

ManagedKeyRotationState is the durable recovery record for one registry-managed operational-key rotation. EntryBytes and IdempotencyKey are immutable once first persisted and are reused verbatim on every retry.

type ManagedKeyRotationState struct {
    Domain                   string                  `json:"domain"`
    LogReference             string                  `json:"log_reference"`
    PreviousKid              string                  `json:"previous_kid"`
    PreviousThumbprint       string                  `json:"previous_thumbprint"`
    NewKid                   string                  `json:"new_kid"`
    NewThumbprint            string                  `json:"new_thumbprint"`
    EntryBytes               []byte                  `json:"entry_bytes"`
    EntryHash                string                  `json:"entry_hash"`
    IdempotencyKey           string                  `json:"idempotency_key"`
    Submission               *dnsid.SubmissionResult `json:"submission,omitempty"`
    Activated                bool                    `json:"activated"`
    ApplicationSigningPaused bool                    `json:"application_signing_paused"`
}

func ResumeManagedOperationalKeyRotation

Section titled “func ResumeManagedOperationalKeyRotation”
func ResumeManagedOperationalKeyRotation(ctx context.Context, opts ResumeManagedKeyRotationOptions) (*ManagedKeyRotationState, error)

ResumeManagedOperationalKeyRotation retries only a persisted rotation’s exact completed bytes and idempotency key, or finishes local reconciliation after an accepted submission.

func RotateManagedOperationalKey

Section titled “func RotateManagedOperationalKey”
func RotateManagedOperationalKey(ctx context.Context, opts ManagedKeyRotationOptions) (*ManagedKeyRotationState, error)

RotateManagedOperationalKey prepares and submits one registry-managed C2SP KEY_ROTATION. The registry exclusively owns publication and append recovery; this function activates locally only after an accepted result is bound to the exact persisted bytes and final event reference.

type ManagedKeyRotationStore

Section titled “type ManagedKeyRotationStore”

ManagedKeyRotationStore durably saves each recoverable rotation state.

type ManagedKeyRotationStore interface {
    PersistManagedKeyRotation(context.Context, *ManagedKeyRotationState) error
}

type ManagedKeyRotationStoreFunc

Section titled “type ManagedKeyRotationStoreFunc”

ManagedKeyRotationStoreFunc adapts a function to ManagedKeyRotationStore.

type ManagedKeyRotationStoreFunc func(context.Context, *ManagedKeyRotationState) error

func (ManagedKeyRotationStoreFunc) PersistManagedKeyRotation

Section titled “func (ManagedKeyRotationStoreFunc) PersistManagedKeyRotation”
func (f ManagedKeyRotationStoreFunc) PersistManagedKeyRotation(ctx context.Context, state *ManagedKeyRotationState) error

PersistManagedKeyRotation calls f to persist state.

type ManagedKeyRotationSubmissionError

Section titled “type ManagedKeyRotationSubmissionError”

ManagedKeyRotationSubmissionError reports a submission or persistence failure after exact completed entry bytes have been fixed.

type ManagedKeyRotationSubmissionError struct {
    Rotation         *ManagedKeyRotationState
    State            dnsid.SubmissionState
    TransientFailure bool
    RetrySameBytes   bool
    Err              error
}

func (*ManagedKeyRotationSubmissionError) Error

Section titled “func (*ManagedKeyRotationSubmissionError) Error”
func (e *ManagedKeyRotationSubmissionError) Error() string

func (*ManagedKeyRotationSubmissionError) ShouldRetrySameBytes

Section titled “func (*ManagedKeyRotationSubmissionError) ShouldRetrySameBytes”
func (e *ManagedKeyRotationSubmissionError) ShouldRetrySameBytes() bool

ShouldRetrySameBytes reports whether recovery must resubmit the exact persisted bytes with the same idempotency key.

func (*ManagedKeyRotationSubmissionError) Transient

Section titled “func (*ManagedKeyRotationSubmissionError) Transient”
func (e *ManagedKeyRotationSubmissionError) Transient() bool

Transient reports whether retrying the operation may succeed.

func (*ManagedKeyRotationSubmissionError) Unwrap

Section titled “func (*ManagedKeyRotationSubmissionError) Unwrap”
func (e *ManagedKeyRotationSubmissionError) Unwrap() error

type MemoryTrustedC2spCheckpointStore

Section titled “type MemoryTrustedC2spCheckpointStore”

MemoryTrustedC2spCheckpointStore protects against rollback for the lifetime of this store instance. Use durable injected storage for protection across restarts.

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

func NewMemoryTrustedC2spCheckpointStore

Section titled “func NewMemoryTrustedC2spCheckpointStore”
func NewMemoryTrustedC2spCheckpointStore() *MemoryTrustedC2spCheckpointStore

NewMemoryTrustedC2spCheckpointStore returns an empty in-memory store. It is safe for concurrent use.

func (*MemoryTrustedC2spCheckpointStore) CompareAndSwap

Section titled “func (*MemoryTrustedC2spCheckpointStore) CompareAndSwap”
func (s *MemoryTrustedC2spCheckpointStore) CompareAndSwap(origin string, expected *TrustedC2spCheckpoint, candidate TrustedC2spCheckpoint) (bool, error)

CompareAndSwap implements TrustedC2spCheckpointStore. It returns an error on a nil receiver or when candidate’s Origin does not match origin.

func (*MemoryTrustedC2spCheckpointStore) Load

Section titled “func (*MemoryTrustedC2spCheckpointStore) Load”
func (s *MemoryTrustedC2spCheckpointStore) Load(origin string) (*TrustedC2spCheckpoint, error)

Load implements TrustedC2spCheckpointStore. It returns a copy of the stored checkpoint, nil when none is recorded, and an error on a nil receiver.

type MigrationVerificationLimits

Section titled “type MigrationVerificationLimits”

MigrationVerificationLimits bound recursive migration verification. Zero values select finite defaults.

type MigrationVerificationLimits struct {
    // MaxDepth bounds migrations in one stitched history.
    MaxDepth int
    // MaxHistoryEvents bounds all imported and destination events.
    MaxHistoryEvents int
    // MaxResponseBytes bounds the JSON-encoded MigrationVerificationResult.
    MaxResponseBytes int64
}

type MigrationVerificationResult

Section titled “type MigrationVerificationResult”

MigrationVerificationResult is the verified state imported by an inbound migration. PriorHistory must be the fully verified history of PreviousLog through the migration event’s FinalEntryRef. PriorEvidence and the aligned PriorHistoryReferences are required when the result is used for complete non-revocation evidence.

type MigrationVerificationResult struct {
    EntityKey              jwk.Key
    ActiveOperationalKey   jwk.Key
    PriorHistory           []dnsidlog.LogEvent
    PriorEvidence          *dnsidlog.LoggedStateEvidence
    PriorHistoryReferences []dnsidlog.LogRef
    // FinalOccurrence retains the exact C2SP cutoff occurrence, including a
    // later signature-valid copy, when RebuildHistoryThrough produced the result.
    FinalOccurrence *ProvenEntry
}

type MigrationVerifier

Section titled “type MigrationVerifier”

MigrationVerifier verifies the prior-log history referenced by an inbound migration and returns the identity keys and history established by it. It must propagate ctx to recursive verification so depth and cycle limits apply.

type MigrationVerifier func(context.Context, dnsidlog.LogEvent) (MigrationVerificationResult, error)

type Option

Section titled “type Option”

Option configures a Client constructed by New or Register.

type Option func(*Client)

func WithAppender

Section titled “func WithAppender”
func WithAppender(appender Appender) Option

WithAppender sets the Appender used to write entries. Write operations require an Appender.

func WithMigrationVerificationLimits

Section titled “func WithMigrationVerificationLimits”
func WithMigrationVerificationLimits(limits MigrationVerificationLimits) Option

WithMigrationVerificationLimits configures recursion and imported-history bounds. Zero fields use finite defaults.

func WithMigrationVerifier

Section titled “func WithMigrationVerifier”
func WithMigrationVerifier(verifier MigrationVerifier) Option

WithMigrationVerifier configures verification and stitching of inbound migrations. Without one, inbound migration fails closed.

func WithPolicy

Section titled “func WithPolicy”
func WithPolicy(policy Policy) Option

WithPolicy sets the checkpoint and proof verification policy. The zero Policy rejects all proofs because it has no log verifier.

func WithSource

Section titled “func WithSource”
func WithSource(source Source) Option

WithSource sets the Source the Client reads proven entries from. All read and verification operations require a Source.

func WithTrustedCheckpointStore

Section titled “func WithTrustedCheckpointStore”
func WithTrustedCheckpointStore(store TrustedC2spCheckpointStore) Option

WithTrustedCheckpointStore sets the store that records the largest verified checkpoint per origin, protecting subsequent reads against log rollback. Without a store, no rollback protection is applied.

type Policy

Section titled “type Policy”

Policy is the local trust configuration for verifying c2sp-tlog checkpoints and inclusion proofs. LogVerifier is required and must match the log’s signing key; WitnessVerifiers and WitnessQuorum define which witness cosignatures are accepted and how many are required (public streams require a quorum of at least 1). CheckpointTime, when set, overrides the default witness-timestamp rule. Now defaults to time.Now. MaxCheckpointAge, when positive, rejects checkpoints whose accepted timestamp is older; ClockSkew is the tolerated clock difference for witness timestamps. Prefer building a Policy with ParsePolicy from a tlog-policy document; the zero Policy rejects all proofs.

type Policy struct {
    LogVerifier      note.Verifier
    WitnessVerifiers []note.Verifier
    WitnessQuorum    int
    CheckpointTime   func(*formatlog.Checkpoint, *note.Note) (time.Time, error)
    Now              func() time.Time
    MaxCheckpointAge time.Duration
    ClockSkew        time.Duration
    // contains filtered or unexported fields
}

func ParsePolicy

Section titled “func ParsePolicy”
func ParsePolicy(document []byte) (policyResult Policy, errResult error)

ParsePolicy parses the official line-oriented C2SP tlog-policy format for a verification-only client. Witness URLs are optional transport hints and are ignored. Definitions are ordered: groups and quorum may reference only preceding witnesses or groups.

func (Policy) VerifyProof

Section titled “func (Policy) VerifyProof”
func (p Policy) VerifyProof(ref Reference, entry, rawProof []byte) (*VerifiedProof, error)

VerifyProof verifies rawProof as an inclusion proof for entry in the log identified by ref. It parses the proof, verifies the embedded checkpoint’s log signature, witness quorum, and freshness under the policy, and checks the RFC 6962 inclusion path from the entry’s leaf hash to the checkpoint root. It returns an error if any step fails.

type PreparedEvent

Section titled “type PreparedEvent”

PreparedEvent preserves the complete method-specific envelope while its lifecycle signatures are collected. Its accessors return copies.

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

func (*PreparedEvent) Bytes

Section titled “func (*PreparedEvent) Bytes”
func (p *PreparedEvent) Bytes() ([]byte, error)

Bytes returns the current canonical envelope, including any signatures already collected. It may be incomplete and is intended for signer handoff.

func (*PreparedEvent) Event

Section titled “func (*PreparedEvent) Event”
func (p *PreparedEvent) Event() (dnsidlog.LogEvent, error)

Event returns the envelope parsed as the shared lifecycle event representation, including any signatures collected so far. It returns an error on a nil receiver.

func (*PreparedEvent) EventID

Section titled “func (*PreparedEvent) EventID”
func (p *PreparedEvent) EventID() string

EventID returns the derived logical event identity, unchanged by signatures.

func (*PreparedEvent) Reference

Section titled “func (*PreparedEvent) Reference”
func (p *PreparedEvent) Reference() Reference

Reference returns the stream reference the event was prepared for. It returns the zero Reference on a nil receiver.

func (*PreparedEvent) RequiredSignatures

Section titled “func (*PreparedEvent) RequiredSignatures”
func (p *PreparedEvent) RequiredSignatures() []SignerRole

RequiredSignatures returns a copy of the signer roles this event type requires before it can be written. It returns nil on a nil receiver.

func (*PreparedEvent) SignedBytes

Section titled “func (*PreparedEvent) SignedBytes”
func (p *PreparedEvent) SignedBytes() []byte

SignedBytes returns a copy of the canonical bytes each SignerRole signs (the envelope without its signatures). It returns nil on a nil receiver.

type ProvenEntry

Section titled “type ProvenEntry”

ProvenEntry is a raw log entry together with its inclusion evidence: the entry’s index in the log, its exact canonical bytes, and a marshaled proof binding the entry to a signed checkpoint. The proof is untrusted until verified by Policy.VerifyProof.

type ProvenEntry struct {
    Index uint64
    Entry []byte
    Proof []byte
}

type Reference

Section titled “type Reference”

Reference is the parsed DNSid c2sp-tlog lr value: c2sp-tlog:<scope>:<log-prefix>#<stream-id>. Scope is “public”, “testnet”, or “private-{name}”; LogPrefix is the log’s base URL; StreamID names one identity-instance lifecycle stream.

type Reference struct {
    Scope     string
    LogPrefix string
    StreamID  string
}

func ParseFinalEventRef

Section titled “func ParseFinalEventRef”
func ParseFinalEventRef(ref dnsidlog.LogRef) (reference Reference, indexResult uint64, err error)

ParseFinalEventRef parses a final event reference of the form <lr>@<index> into its Reference and entry index. The index must be decimal with no leading zeros. It returns a *dnsid.ParseError on any violation.

func ParseReference

Section titled “func ParseReference”
func ParseReference(lr string) (refResult Reference, err error)

ParseReference parses and validates an lr value into a Reference. It returns a *dnsid.ParseError if lr is malformed or fails Validate.

func (Reference) FinalEventRef

Section titled “func (Reference) FinalEventRef”
func (r Reference) FinalEventRef(index uint64) dnsidlog.LogRef

FinalEventRef returns the reference of the entry at index in this stream, in the form <lr>@<index>.

func (Reference) Origin

Section titled “func (Reference) Origin”
func (r Reference) Origin() (origin string, err error)

Origin returns the C2SP checkpoint origin derived from LogPrefix.

func (Reference) String

Section titled “func (Reference) String”
func (r Reference) String() string

String returns the reference in lr form: c2sp-tlog:<scope>:<log-prefix>#<stream-id>.

func (Reference) Validate

Section titled “func (Reference) Validate”
func (r Reference) Validate() (err error)

Validate checks that the reference is well formed and canonical: a known scope, an absolute lowercase http(s) LogPrefix with no userinfo, query, fragment, dot segments, trailing slash, default port, or non-canonical percent-encodings, and a non-empty StreamID. Public scopes require https. It returns a *dnsid.ValidationError describing the first violation.

type ResourceFetchError

Section titled “type ResourceFetchError”

ResourceFetchError is returned when a policy or standard C2SP resource cannot be fetched safely. Unsafe destinations, redirects, malformed URLs, and response-limit failures are permanent; network availability failures and retryable HTTP statuses are transient.

type ResourceFetchError struct {
    Kind             ResourceFetchErrorKind
    URL              string
    MaximumBytes     int64
    HTTPStatus       int
    TransientFailure bool
    Cause            error
}

func (*ResourceFetchError) Error

Section titled “func (*ResourceFetchError) Error”
func (e *ResourceFetchError) Error() string

func (*ResourceFetchError) Transient

Section titled “func (*ResourceFetchError) Transient”
func (e *ResourceFetchError) Transient() bool

Transient reports whether retrying an unchanged fetch may succeed.

func (*ResourceFetchError) Unwrap

Section titled “func (*ResourceFetchError) Unwrap”
func (e *ResourceFetchError) Unwrap() error

type ResourceFetchErrorKind

Section titled “type ResourceFetchErrorKind”

ResourceFetchErrorKind classifies failures from standard C2SP resource retrieval.

type ResourceFetchErrorKind string

const (
    // ResourceFetchMalformedURL indicates that the resource URL is invalid.
    ResourceFetchMalformedURL ResourceFetchErrorKind = "malformed_url"
    // ResourceFetchUnsafeDestination indicates that destination safety checks failed.
    ResourceFetchUnsafeDestination ResourceFetchErrorKind = "unsafe_destination"
    // ResourceFetchRedirect indicates that the resource returned a redirect.
    ResourceFetchRedirect ResourceFetchErrorKind = "redirect"
    // ResourceFetchResponseLimit indicates that the resource exceeded its byte limit.
    ResourceFetchResponseLimit ResourceFetchErrorKind = "response_limit"
    // ResourceFetchHTTPStatus indicates that the resource returned a non-success status.
    ResourceFetchHTTPStatus ResourceFetchErrorKind = "http_status"
    // ResourceFetchUnavailable indicates a network or transport failure.
    ResourceFetchUnavailable ResourceFetchErrorKind = "unavailable"
)

type ResourceFetchGuarantees

Section titled “type ResourceFetchGuarantees”

ResourceFetchGuarantees declares the security properties provided by a BoundedResourceFetcher. The verification convenience factory requires every property for policy and public-log reads.

type ResourceFetchGuarantees struct {
    HTTPSOnly                     bool
    RejectsRedirects              bool
    ValidatesAllResolvedAddresses bool
    ConnectsToValidatedAddress    bool
    BoundsResponseDuringRead      bool
}

func (ResourceFetchGuarantees) SupportsPublicReads

Section titled “func (ResourceFetchGuarantees) SupportsPublicReads”
func (g ResourceFetchGuarantees) SupportsPublicReads() bool

SupportsPublicReads reports whether all transport guarantees required for a public c2sp-tlog policy and standard-resource scan are present.

type ResumeManagedIssuanceOptions

Section titled “type ResumeManagedIssuanceOptions”

ResumeManagedIssuanceOptions identifies the authoritative persisted operation by Domain. Resume never trusts caller-supplied recovery state, prepares a different event, or changes the idempotency key.

type ResumeManagedIssuanceOptions struct {
    Domain            string
    Client            *Client
    EntityPublicKey   jwk.Key
    KeyProvider       dnsid.KeyProvider
    RegistryClient    dnsid.RegistryPreparedEventClient
    Store             ManagedIssuanceStore
    ActivationControl ManagedIssuanceActivationController
}

type ResumeManagedKeyRotationOptions

Section titled “type ResumeManagedKeyRotationOptions”

ResumeManagedKeyRotationOptions resumes a previously persisted rotation.

type ResumeManagedKeyRotationOptions struct {
    KeyProvider        dnsid.KeyProvider
    RegistryClient     dnsid.RegistryPreparedEventClient
    Rotation           *ManagedKeyRotationState
    Store              ManagedKeyRotationStore
    ApplicationSigning ApplicationSigningController
}

type ScanSource

Section titled “type ScanSource”

ScanSource reads the standard C2SP tiled-log surface and authenticates a complete raw-log scan against its signed checkpoint and level-zero tiles. Configure the Client with the same Policy passed to NewScanSource.

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

func NewScanSource

Section titled “func NewScanSource”
func NewScanSource(policy Policy, config ScanSourceConfig) (*ScanSource, error)

NewScanSource constructs a bounded C2SP network scanner. It is SSRF-resistant unless the caller supplies a custom Transport.

func (*ScanSource) FetchEntriesThrough

Section titled “func (*ScanSource) FetchEntriesThrough”
func (s *ScanSource) FetchEntriesThrough(ctx context.Context, reference Reference, treeSize uint64) ([][]byte, error)

FetchEntriesThrough implements C2spFullLogSource by returning the requested prefix from a fresh authenticated scan. The scan may have advanced beyond treeSize; its authenticated entries still independently prove the requested checkpoint prefix.

func (*ScanSource) GlobalCandidates

Section titled “func (*ScanSource) GlobalCandidates”
func (*ScanSource) GlobalCandidates() bool

GlobalCandidates implements GlobalCandidateSource: scan results are unfiltered global-log candidates, so the Client skips invalid or unrelated entries instead of failing.

func (*ScanSource) ReadEvent

Section titled “func (*ScanSource) ReadEvent”
func (s *ScanSource) ReadEvent(ctx context.Context, ref dnsidlog.LogRef) (ProvenEntry, error)

ReadEvent implements Source by running a full authenticated scan and returning the entry at the reference’s index. It returns an error if the index is outside the scanned checkpoint size.

func (*ScanSource) RebuildCompleteHistory

Section titled “func (*ScanSource) RebuildCompleteHistory”
func (s *ScanSource) RebuildCompleteHistory(ctx context.Context, reference Reference, domain string) (CompleteHistoryResult, error)

RebuildCompleteHistory implements CompleteSource by binding the returned candidates to the exact authenticated full-scan checkpoint.

func (*ScanSource) RebuildHistory

Section titled “func (*ScanSource) RebuildHistory”
func (s *ScanSource) RebuildHistory(ctx context.Context, reference Reference, domain string) ([]ProvenEntry, error)

RebuildHistory implements Source by scanning the complete log once, authenticating every entry against the signed checkpoint, and returning the entries whose fqdn matches domain, each with a derived inclusion proof.

type ScanSourceConfig

Section titled “type ScanSourceConfig”

ScanSourceConfig bounds a standard checkpoint/tile/entry-bundle scan. ResourceFetcher is mutually exclusive with HTTPClient and Transport. The lower-level Transport option is used verbatim, so its caller owns destination safety; NewVerificationRegistry applies the stricter public-read capability contract before constructing a scanner.

type ScanSourceConfig struct {
    HTTPClient          *http.Client
    Transport           http.RoundTripper
    ResourceFetcher     BoundedResourceFetcher
    MaxTreeSize         uint64
    MaxCheckpointBytes  int64
    MaxEntryBundleBytes int64
    MaxTotalEntryBytes  int64
}

type SignerRole

Section titled “type SignerRole”

SignerRole identifies a DNSid lifecycle signature in a C2SP event envelope.

type SignerRole string

const (
    // SignerEntity is the accountable entity key: it signs ISSUANCE and
    // every post-issuance event other than KEY_ROTATION.
    SignerEntity SignerRole = "entity"
    // SignerOperationalCountersignature is the operational key's
    // countersignature on ISSUANCE.
    SignerOperationalCountersignature SignerRole = "operational_countersignature"
    // SignerPreviousOperational is the outgoing operational key's signature
    // on KEY_ROTATION.
    SignerPreviousOperational SignerRole = "previous_operational"
    // SignerNewOperational is the incoming operational key's signature on
    // KEY_ROTATION.
    SignerNewOperational SignerRole = "new_operational"
)

type Source

Section titled “type Source”

Source supplies raw, inclusion-proven entries from a c2sp-tlog log. A Source is a transport: everything it returns is untrusted until the Client verifies proofs, signatures, and lifecycle order.

type Source interface {
    // ReadEvent returns the proven entry addressed by a final event
    // reference of the form <lr>@<index>.
    ReadEvent(ctx context.Context, ref dnsidlog.LogRef) (ProvenEntry, error)
    // RebuildHistory returns the proven entries relevant to domain in the
    // stream identified by lr, in ascending index order.
    RebuildHistory(ctx context.Context, lr Reference, domain string) ([]ProvenEntry, error)
}

type SpecificationVersions

Section titled “type SpecificationVersions”

SpecificationVersions is a read-only snapshot of the exact standards profile implemented by this package. Mutating a returned value cannot alter package metadata.

type SpecificationVersions struct {
    Checkpoint    string
    Tiles         string
    Proof         string
    Policy        string
    Witness       string
    Cosignature   string
    Mirror        string
    SignedNote    string
    EventEnvelope int
}

func PinnedSpecificationVersions

Section titled “func PinnedSpecificationVersions”
func PinnedSpecificationVersions() SpecificationVersions

PinnedSpecificationVersions returns the exact C2SP and DNSid envelope versions implemented by this package.

type StreamBundleSource

Section titled “type StreamBundleSource”

StreamBundleSource adapts verified bundle evidence to Source and CompleteSource without trusting the producer’s event parsing.

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

func (*StreamBundleSource) ReadEvent

Section titled “func (*StreamBundleSource) ReadEvent”
func (s *StreamBundleSource) ReadEvent(_ context.Context, ref dnsidlog.LogRef) (ProvenEntry, error)

ReadEvent implements Source over the bundle’s entries. It returns an error if ref does not address this bundle’s reference or names an index the bundle does not contain.

func (*StreamBundleSource) RebuildCompleteHistory

Section titled “func (*StreamBundleSource) RebuildCompleteHistory”
func (s *StreamBundleSource) RebuildCompleteHistory(_ context.Context, reference Reference, domain string) (CompleteHistoryResult, error)

RebuildCompleteHistory implements CompleteSource: a verified bundle’s trusted-index completeness assertion and entries share one checkpoint.

func (*StreamBundleSource) RebuildHistory

Section titled “func (*StreamBundleSource) RebuildHistory”
func (s *StreamBundleSource) RebuildHistory(_ context.Context, reference Reference, domain string) ([]ProvenEntry, error)

RebuildHistory implements Source over the bundle’s entries. It returns copies of every bundled entry, or an error if reference or domain does not match the bundle.

type StreamBundleTrust

Section titled “type StreamBundleTrust”

StreamBundleTrust contains verifier-controlled inputs. PolicyDocument is hashed byte-for-byte and parsed as tlog-policy; it is never taken from the bundle. BundleVerifier is retained for single-key callers; BundleVerifiers allows independently configured keys to overlap during signer rotation.

type StreamBundleTrust struct {
    PolicyDocument         []byte
    BundleVerifier         note.Verifier
    BundleVerifiers        []note.Verifier
    Now                    func() time.Time
    MaxBundleLifetime      time.Duration
    MaxCheckpointAge       time.Duration
    ClockSkew              time.Duration
    MaxBundleBytes         int
    MaxEvents              int
    MaxTreeSize            uint64
    TrustedCheckpointStore TrustedC2spCheckpointStore
    MigrationVerifier      MigrationVerifier
    MigrationLimits        MigrationVerificationLimits
}

type TrustProfile

Section titled “type TrustProfile”

TrustProfile binds one exact C2SP log to its independently distributed trust policy and accepted stream-bundle signers. Runtime freshness and resource limits remain caller configuration.

type TrustProfile struct {
    Version            int      `json:"version"`
    Scope              string   `json:"scope"`
    LogPrefix          string   `json:"log_prefix"`
    PolicyDocument     string   `json:"tlog_policy"`
    BundleVerifierKeys []string `json:"bundle_verifier_keys"`
}

func ParseTrustProfile

Section titled “func ParseTrustProfile”
func ParseTrustProfile(data []byte) (TrustProfile, error)

ParseTrustProfile parses and validates a DNSid C2SP trust-profile document.

type TrustedC2spCheckpoint

Section titled “type TrustedC2spCheckpoint”

TrustedC2spCheckpoint is append-only state scoped by checkpoint origin. A store may be seeded out of band; otherwise its first accepted checkpoint is trust on first use.

type TrustedC2spCheckpoint struct {
    Origin      string
    TreeSize    uint64
    RootHash    []byte
    WitnessTime time.Time
}

type TrustedC2spCheckpointStore

Section titled “type TrustedC2spCheckpointStore”

TrustedC2spCheckpointStore atomically advances trusted checkpoint state. Administrative re-baselining must use an independently authorized, verified replacement and exact expected state, with verification stopped. See https://github.com/dnsid-ai/dnsid-go/blob/main/CHECKPOINT_RECOVERY.md. Verification never resets trust; custom stores may reject administrative downgrades.

type TrustedC2spCheckpointStore interface {
    // Load returns the trusted checkpoint for origin, or nil (with a nil
    // error) when none has been recorded.
    Load(origin string) (*TrustedC2spCheckpoint, error)
    // CompareAndSwap stores candidate only if the current state for origin
    // equals expected (nil expected means no state recorded). It reports
    // whether the swap happened; false with a nil error means another writer
    // advanced the state first and the caller should reload and retry.
    CompareAndSwap(origin string, expected *TrustedC2spCheckpoint, candidate TrustedC2spCheckpoint) (bool, error)
}

type VerificationRegistryConfig

Section titled “type VerificationRegistryConfig”

VerificationRegistryConfig configures NewVerificationRegistry. Exactly one of TrustProfile, PolicyDocument, and PolicyURL must be set. A PolicyURL is a caller-selected trust-policy location; it is never inferred from an identity’s untrusted lr value.

type VerificationRegistryConfig struct {
    // TrustProfile binds one exact scope and log prefix to an independently
    // distributed policy document and bundle signer keys.
    TrustProfile *TrustProfile
    // PolicyDocument contains an independently trusted C2SP tlog-policy
    // document. The bytes are parsed locally and are not fetched from the log.
    PolicyDocument []byte
    // PolicyURL is an independently trusted HTTPS location from which to fetch
    // the C2SP tlog-policy document. Redirects are rejected.
    PolicyURL string
    // ExpectedOrigin, when set, is the checkpoint origin (Reference.Origin)
    // the policy's log key must be named for. It stops a trusted policy for
    // log A being installed for a record naming log B. TrustProfile enforces
    // this from its own scope and log prefix, so it is optional there.
    ExpectedOrigin string
    // Transport applies DNSid deployment transport controls (custom DNS server,
    // extra CA bundle, private-network permission) to the policy fetch and all
    // log reads, exactly as Config.Transport does for the IdentityManager. Pass
    // the same value to both when verifying against a private registry such as
    // dnsid local. Mutually exclusive with ResourceFetcher and with
    // ScanSourceConfig.HTTPClient / ScanSourceConfig.Transport.
    Transport dnsid.TransportConfig
    // ScanSourceConfig configures the bounded standard tiled-log scanner. A
    // custom Transport is accepted only by lower-level NewScanSource; this safe
    // factory accepts nil or *http.Transport and wraps it with safe dialing.
    ScanSourceConfig ScanSourceConfig
    // ResourceFetcher is trusted caller infrastructure used for both PolicyURL
    // and all standard log resources. Its public-read guarantees are validated
    // eagerly. It is mutually exclusive with scanner HTTP transport options.
    ResourceFetcher BoundedResourceFetcher
    // TrustedCheckpointStore records accepted checkpoints. When nil, an
    // in-memory store protects against rollback for this process's lifetime.
    TrustedCheckpointStore TrustedC2spCheckpointStore
    // MaxPolicyBytes bounds a PolicyURL response. Zero uses 1 MiB.
    MaxPolicyBytes int64
    // CheckpointMaxAge enables fresh logged-state and non-revocation checks.
    // Zero leaves freshness unset, so those checks fail closed.
    CheckpointMaxAge time.Duration
    // AllowedClockSkew permits this much future skew in checkpoint witness
    // timestamps. Zero is the default and negative values are rejected.
    AllowedClockSkew time.Duration
    // BundleVerifiers are independently trusted stream-bundle signer keys.
    // When non-empty, bundles are preferred over raw global-log scans.
    BundleVerifiers []note.Verifier
    // MaxBundleLifetime is required when BundleVerifiers is non-empty.
    MaxBundleLifetime time.Duration
    // MaxStreamBundleBytes and MaxStreamBundleEvents bound bundle responses.
    // Zero uses the package defaults.
    MaxStreamBundleBytes  int
    MaxStreamBundleEvents int
    // RequireStreamBundle disables raw-scan history fallback. ReadEvent may use
    // the scanner to discover the FQDN before requiring its bundle history.
    RequireStreamBundle bool
}

type VerifiedProof

Section titled “type VerifiedProof”

VerifiedProof is the accepted result of checkpoint and inclusion-proof verification: the proven entry index, the parsed checkpoint and its signed note, and the timestamps derived from accepted witness cosignatures (CheckpointIntegrationTime adds the policy’s clock skew to CheckpointWitnessTime).

type VerifiedProof struct {
    Index                     uint64
    Checkpoint                *formatlog.Checkpoint
    CheckpointNote            *note.Note
    CheckpointWitnessTime     time.Time
    CheckpointIntegrationTime time.Time
    CheckpointFreshnessTime   time.Time
    // LogTime is retained for compatibility and equals CheckpointIntegrationTime.
    LogTime time.Time
}

type VerifiedStreamBundle

Section titled “type VerifiedStreamBundle”

VerifiedStreamBundle is the result of VerifyStreamBundle: the verified lifecycle events and materialized snapshot for one stream, its logged state, the bundle’s expiry and completeness bound, the accepted signer, and a Source over the bundle’s proven entries for further Client operations. LoggedState is historical log state, not current protocol status.

type VerifiedStreamBundle struct {
    Reference           Reference
    FQDN                string
    Events              []dnsidlog.LogEvent
    Snapshot            *dnsidlog.DomainSnapshot
    LoggedState         string
    Expires             time.Time
    CompleteThroughSize uint64
    SignerKeyID         string
    Source              *StreamBundleSource
}

func VerifyStreamBundle

Section titled “func VerifyStreamBundle”
func VerifyStreamBundle(ctx context.Context, data []byte, trust StreamBundleTrust) (*VerifiedStreamBundle, error)

VerifyStreamBundle verifies an offline stream bundle without network access. It checks, in order: size and canonical JCS form, the accepted bundle signer’s Ed25519 signature, format version and type, expiry against local time and MaxBundleLifetime, that the bundle’s policy hash matches the verifier-supplied PolicyDocument, and then replays every bundled entry through full Client verification (inclusion proofs against the embedded checkpoint, lifecycle signatures, and stream chain). The bundle’s own state summary must match the replayed result. Nothing in data is trusted until all checks pass.

Generated by gomarkdoc

Known Systems AI, Inc. is an affiliate of Identity Digital that solves identity fragmentation for the AI agent economy. As agents become more autonomous and interoperable, they introduce risk and security challenges existing systems weren't designed for—starting with a consistent way to verify ownership across organizational boundaries. Known Systems AI, Inc. combines Identity Digital's DNS expertise with an Immutable Log to establish a global coordination layer for AI agent identity, and participates in open standards communities, including the Linux Foundation. For more information, visit DNSid.ai.