Skip to content
DNSid Docs

Go: package log

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

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

Package log defines the DNSid lifecycle-log abstractions: the signed events that record an agent’s identity lifecycle (issuance, key rotation, revocation, retirement, migration, and delegation) and the interfaces used to write and verify that evidence.

A lifecycle log is identified in an identity record by an “lr” value of the form {method}:{entry-ref}. This package is method-agnostic: it defines the shared LogEvent carrier, the Log (writer) and LogReader (verifier) interfaces, and a LogRegistry that maps method names to LogReader factories. Concrete log methods, such as the C2SP transparency-log binding in the c2sptlog subpackage, register themselves with a LogRegistry; unregistered methods resolve to a NoopLogReader that fails every evidence operation with a structured VerificationError.

The package also models the fixed six-state agent lifecycle machine (AgentState) and can materialize a verified event history into the state at a point in time:

registry := log.NewLogRegistry()
// A log method binding (e.g. c2sptlog.Register) populates the registry.
reader, err := registry.NewReader("c2sp-tlog:public:https://tlog.example/dnsid#N4m8yB1Qk6RzT3w7Vp2JxA")
if err != nil {
  // handle malformed lr value
}
events, err := reader.RebuildHistory(ctx, "agent.example")
if err != nil {
  // handle verification failure
}
snapshot, err := log.NewDomainLog("agent.example", events).SnapshotAt(time.Now())

Verification entry points on LogReader check the bilateral binding established by ISSUANCE (entity key and operational key signing each other’s enrollment), operational key continuity across rotations, governance relationships, and non-revocation.

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

Index

Section titled “Index”

Constants

Section titled “Constants”

Lifecycle verification codes are shared across SDK reducer conformance tests.

const (
    VerificationCodeGenesisRequired         = "GENESIS_REQUIRED"
    VerificationCodeDuplicateIssuance       = "DUPLICATE_ISSUANCE"
    VerificationCodeInvalidIssuance         = "INVALID_ISSUANCE"
    VerificationCodeTerminalState           = "TERMINAL_STATE"
    VerificationCodeDomainMismatch          = "DOMAIN_MISMATCH"
    VerificationCodeKeyContinuity           = "KEY_CONTINUITY"
    VerificationCodeInvalidRevocationReason = "INVALID_REVOCATION_REASON"
    VerificationCodeInvalidMigration        = "INVALID_MIGRATION"
    VerificationCodeSnapshotEmpty           = "SNAPSHOT_EMPTY"
    VerificationCodeSnapshotNonPrefix       = "SNAPSHOT_NON_PREFIX"
    VerificationCodeUnsupportedEvent        = "UNSUPPORTED_EVENT"
)

func ParseLogRef

Section titled “func ParseLogRef”
func ParseLogRef(lr string) (method, entryRef string, err error)

ParseLogRef splits an lr value into its method and entry reference at the first colon. It returns an error if lr has no colon, an empty method, or a method that is not lowercase alphanumeric-with-hyphens.

func ValidRevocationReason

Section titled “func ValidRevocationReason”
func ValidRevocationReason(reason string) bool

ValidRevocationReason reports whether reason is a draft 01 REVOCATION reason code.

type AgentState

Section titled “type AgentState”

AgentState is the canonical lifecycle state of a DNSid agent. The six states form the fixed protocol state machine (spec §Agent States). It is a defined type (not a type alias) to provide compile-time safety: callers must use the typed constants or ParseAgentState to construct values.

type AgentState string

The six canonical lifecycle states, in lifecycle order.

const (
    // AgentStatePending means the agent has been requested but not yet
    // provisioned.
    AgentStatePending AgentState = "PENDING"
    // AgentStateProvisioning means keys and records are being created.
    AgentStateProvisioning AgentState = "PROVISIONING"
    // AgentStateVerifying means the published identity record is awaiting
    // verification.
    AgentStateVerifying AgentState = "VERIFYING"
    // AgentStateActive means the agent identity is live and verifiable.
    AgentStateActive AgentState = "ACTIVE"
    // AgentStateRetired means the identity was terminally retired in good
    // standing.
    AgentStateRetired AgentState = "RETIRED"
    // AgentStateRevoked means the identity was terminally revoked.
    AgentStateRevoked AgentState = "REVOKED"
)

func AgentStates

Section titled “func AgentStates”
func AgentStates() []AgentState

AgentStates returns the six canonical lifecycle states in order.

func ParseAgentState

Section titled “func ParseAgentState”
func ParseAgentState(s string) (AgentState, error)

ParseAgentState converts a raw string (e.g. from a database column, JSON field, or registry response) into the typed AgentState. It returns an error if s is not one of the six canonical states.

func (AgentState) IsValid

Section titled “func (AgentState) IsValid”
func (s AgentState) IsValid() bool

IsValid reports whether s is one of the six canonical lifecycle states.

func (AgentState) String

Section titled “func (AgentState) String”
func (s AgentState) String() string

String implements fmt.Stringer.

type BilateralBinding

Section titled “type BilateralBinding”

BilateralBinding is the verified key anchor established by ISSUANCE.

type BilateralBinding struct {
    InitialOperationalThumbprint string
    InitialEntityThumbprint      string
    Timestamp                    time.Time
}

type BilateralBindingInput

Section titled “type BilateralBindingInput”

BilateralBindingInput is the current DNS record material checked against an ISSUANCE event. It is log-owned to avoid coupling log bindings to the root package’s TXT record representation.

type BilateralBindingInput struct {
    Domain         string
    GovernanceID   string
    EntityKey      jwk.Key
    OperationalKey jwk.Key
}

type DomainLog

Section titled “type DomainLog”

DomainLog is a verified lifecycle event history for a domain.

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

func NewDomainLog

Section titled “func NewDomainLog”
func NewDomainLog(domain string, events []LogEvent) *DomainLog

NewDomainLog constructs a DomainLog over events already verified by a LogReader. It copies the events slice; events must be in log order.

func (*DomainLog) Domain

Section titled “func (*DomainLog) Domain”
func (l *DomainLog) Domain() string

Domain returns the domain the history belongs to. It returns "" on a nil receiver.

func (*DomainLog) Events

Section titled “func (*DomainLog) Events”
func (l *DomainLog) Events() []LogEvent

Events returns a copy of the lifecycle events in log order. It returns nil on a nil receiver.

func (*DomainLog) SnapshotAt

Section titled “func (*DomainLog) SnapshotAt”
func (l *DomainLog) SnapshotAt(at time.Time) (*DomainSnapshot, error)

SnapshotAt replays the domain’s events with timestamps at or before at and returns the resulting lifecycle state. It enforces the lifecycle state machine while replaying and returns an error if the log is empty, if the events at or before at are not a contiguous prefix of the log, if no ISSUANCE event is found, or if an event sequence is invalid (for example, a rotation before issuance or a non-migration event after a terminal state). Events for other domains are ignored.

type DomainSnapshot

Section titled “type DomainSnapshot”

DomainSnapshot is the materialized lifecycle state at a point in time. HistoricalState holds one of the AgentState* values; ActiveKey, ActiveKeyThumbprint, and KeyBoundAt describe the operational key in effect at SnapshotAt; Events holds the lifecycle prefix the snapshot was materialized from.

type DomainSnapshot struct {
    Domain              string
    HistoricalState     AgentState
    ActiveKey           jwk.Key
    ActiveKeyThumbprint string
    KeyBoundAt          time.Time
    GovernanceID        string
    SnapshotAt          time.Time
    Events              []LogEvent
}

type LifecycleBindingVerifier

Section titled “type LifecycleBindingVerifier”

LifecycleBindingVerifier optionally combines bilateral-binding and operational-continuity verification over one consistent log snapshot. IdentityManager uses this fast path when available and otherwise calls the corresponding LogReader methods separately.

type LifecycleBindingVerifier interface {
    VerifyLifecycleBinding(ctx context.Context, input BilateralBindingInput, currentOperationalThumbprint string) (BilateralBinding, error)
}

type Log

Section titled “type Log”

Log writes signed lifecycle events for a local identity.

type Log interface {
    // Canonical returns the canonical byte encoding of event that lifecycle
    // signatures are computed over.
    Canonical(event LogEvent) ([]byte, error)
    // WriteEvent appends a fully signed event to the log and returns the
    // reference of the stored entry.
    WriteEvent(ctx context.Context, event LogEvent) (LogRef, error)
}

type LogEvent

Section titled “type LogEvent”

LogEvent is the SDK’s method-agnostic lifecycle event carrier. Only the fields relevant to Type are populated; all other fields are left at their zero values and omitted from JSON. Signature fields hold unpadded base64url values. Key algorithms are read from the embedded JWKs. A log binding that does not independently encode initial thumbprints derives them from those JWKs before returning the shared event.

type LogEvent struct {
    Type LogEventType `json:"type"`


    InitialEntityKid              string  `json:"initialEntityKid,omitempty"`
    InitialEntityPublicKey        jwk.Key `json:"initialEntityPublicKey,omitempty"`
    InitialEntityThumbprint       string  `json:"initialEntityThumbprint,omitempty"`
    InitialEntitySignature        string  `json:"initialEntitySignature,omitempty"`
    InitialOperationalKid         string  `json:"initialOperationalKid,omitempty"`
    InitialOperationalPublicKey   jwk.Key `json:"initialOperationalPublicKey,omitempty"`
    InitialOperationalThumbprint  string  `json:"initialOperationalThumbprint,omitempty"`
    InitialOperationalSignature   string  `json:"initialOperationalSignature,omitempty"`
    PreviousOperationalKid        string  `json:"previousOperationalKid,omitempty"`
    PreviousOperationalThumbprint string  `json:"previousOperationalThumbprint,omitempty"`
    PreviousOperationalSignature  string  `json:"previousOperationalSignature,omitempty"`
    NewOperationalKid             string  `json:"newOperationalKid,omitempty"`
    NewOperationalPublicKey       jwk.Key `json:"newOperationalPublicKey,omitempty"`
    NewOperationalThumbprint      string  `json:"newOperationalThumbprint,omitempty"`
    NewOperationalSignature       string  `json:"newOperationalSignature,omitempty"`


    Domain       string    `json:"domain,omitempty"`
    Timestamp    time.Time `json:"timestamp,omitempty"`
    GovernanceID string    `json:"governanceId,omitempty"`


    Reason        string    `json:"reason,omitempty"`
    PreviousLog   string    `json:"previousLog,omitempty"`
    NewLog        string    `json:"newLog,omitempty"`
    FinalEntryRef string    `json:"finalEntryRef,omitempty"`
    Delegatee     string    `json:"delegatee,omitempty"`
    Scope         string    `json:"scope,omitempty"`
    Expiry        time.Time `json:"expiry,omitempty"`
}

type LogEventType

Section titled “type LogEventType”

LogEventType is a lifecycle event type identifier.

type LogEventType string

The lifecycle event types defined by DNSid draft 01.

const (
    // LogEventIssuance establishes the bilateral binding between an entity
    // key and an operational key for a domain. It is the genesis event of a
    // lifecycle stream.
    LogEventIssuance LogEventType = "ISSUANCE"
    // LogEventKeyRotation replaces the active operational key. It is signed
    // by both the outgoing and the incoming operational key.
    LogEventKeyRotation LogEventType = "KEY_ROTATION"
    // LogEventRevocation terminally revokes the identity. Its Reason must be
    // one of the codes accepted by ValidRevocationReason.
    LogEventRevocation LogEventType = "REVOCATION"
    // LogEventRetirement terminally retires the identity in good standing.
    LogEventRetirement LogEventType = "RETIREMENT"
    // LogEventMigration moves the lifecycle stream between logs; it links the
    // previous and new lr values and the final entry in the previous log.
    LogEventMigration LogEventType = "MIGRATION"
    // LogEventDelegation grants a scoped, expiring delegation to another
    // party without changing lifecycle state.
    LogEventDelegation LogEventType = "DELEGATION"
)

type LogReader

Section titled “type LogReader”

LogReader reads and verifies lifecycle evidence for one bound lr value.

type LogReader interface {
    // Canonical returns the canonical byte encoding of event that lifecycle
    // signatures are verified over.
    Canonical(event LogEvent) ([]byte, error)
    // KeyTimestamp returns the signed lifecycle-event time at which keyThumbprint
    // became the domain's active operational key. It returns an error if the key
    // is not currently bound.
    KeyTimestamp(ctx context.Context, domain, keyThumbprint string) (time.Time, error)
    // VerifyBilateralBinding verifies the ISSUANCE proofs, entity and operational
    // signatures, and correspondence with the current DNS record.
    VerifyBilateralBinding(ctx context.Context, input BilateralBindingInput) (BilateralBinding, error)
    // VerifyOperationalContinuity verifies a rotation chain from the ISSUANCE
    // operational key to the current operational key.
    VerifyOperationalContinuity(ctx context.Context, domain, initialOperationalThumbprint, currentOperationalThumbprint string) error
    // VerifyNonRevocation verifies that the identity was not revoked or
    // retired as of time at. It requires evidence that the observed history
    // is complete and fresh, and returns the accepted proof boundary.
    VerifyNonRevocation(ctx context.Context, domain string, at time.Time) (LoggedStateEvidence, error)
    // ReadEvent reads and verifies the single event stored at ref.
    ReadEvent(ctx context.Context, ref LogRef) (LogEvent, error)
    // RebuildHistory returns the domain's verified lifecycle events in log
    // order, dropping or rejecting entries that fail verification according
    // to the method's evidence model.
    RebuildHistory(ctx context.Context, domain string) ([]LogEvent, error)
}

type LogRef

Section titled “type LogRef”

LogRef identifies an entry in a lifecycle log as {method}:{entry-ref}.

type LogRef string

type LogRegistry

Section titled “type LogRegistry”

LogRegistry maps log method names to bound LogReader factories.

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

func NewLogRegistry

Section titled “func NewLogRegistry”
func NewLogRegistry() *LogRegistry

NewLogRegistry returns an empty registry with no methods registered.

func (*LogRegistry) NewReader

Section titled “func (*LogRegistry) NewReader”
func (r *LogRegistry) NewReader(lr string) (LogReader, error)

NewReader returns a LogReader bound to the lr value. It returns an error only when lr is malformed; a nil registry, an unregistered method, or a factory that returns nil all yield a NoopLogReader, so evidence failures surface at verification time rather than at construction. NewReader is safe for concurrent use.

func (*LogRegistry) Register

Section titled “func (*LogRegistry) Register”
func (r *LogRegistry) Register(method string, factory func(lr string) LogReader) error

Register binds factory to a log method name. The method must be lowercase alphanumeric-with-hyphens ([a-z][a-z0-9-]*) and factory must be non-nil; otherwise Register returns an error. Registering an already-registered method replaces its factory. Register is safe for concurrent use.

type LoggedStateEvidence

Section titled “type LoggedStateEvidence”

LoggedStateEvidence records the proof boundary accepted for a complete lifecycle-state decision. LoggedState is historical log state, not current protocol status. HistoryStart and HistoryEnd bound the referenced log stream. PriorEvidence retains the independently verified boundaries imported by inbound migrations, oldest first. Checkpoint and CompleteThrough are opaque to callers.

type LoggedStateEvidence struct {
    LogReference     LogRef
    LoggedState      AgentState
    HistoryStart     LogRef
    HistoryEnd       LogRef
    CompleteThrough  string
    CompletenessMode string
    Checkpoint       []byte
    FreshnessTime    time.Time
    PriorEvidence    []LoggedStateEvidence
}

type NoopLogReader

Section titled “type NoopLogReader”

NoopLogReader fails every evidence operation for an unregistered method. Each method returns a *VerificationError with code “log_error” naming the unregistered Method; the error is not transient.

type NoopLogReader struct{ Method string }

func (NoopLogReader) Canonical

Section titled “func (NoopLogReader) Canonical”
func (n NoopLogReader) Canonical(LogEvent) ([]byte, error)

Canonical implements LogReader; it always fails.

func (NoopLogReader) KeyTimestamp

Section titled “func (NoopLogReader) KeyTimestamp”
func (n NoopLogReader) KeyTimestamp(context.Context, string, string) (time.Time, error)

KeyTimestamp implements LogReader; it always fails.

func (NoopLogReader) ReadEvent

Section titled “func (NoopLogReader) ReadEvent”
func (n NoopLogReader) ReadEvent(context.Context, LogRef) (LogEvent, error)

ReadEvent implements LogReader; it always fails.

func (NoopLogReader) RebuildHistory

Section titled “func (NoopLogReader) RebuildHistory”
func (n NoopLogReader) RebuildHistory(context.Context, string) ([]LogEvent, error)

RebuildHistory implements LogReader; it always fails.

func (NoopLogReader) VerifyBilateralBinding

Section titled “func (NoopLogReader) VerifyBilateralBinding”
func (n NoopLogReader) VerifyBilateralBinding(context.Context, BilateralBindingInput) (BilateralBinding, error)

VerifyBilateralBinding implements LogReader; it always fails.

func (NoopLogReader) VerifyNonRevocation

Section titled “func (NoopLogReader) VerifyNonRevocation”
func (n NoopLogReader) VerifyNonRevocation(context.Context, string, time.Time) (LoggedStateEvidence, error)

VerifyNonRevocation implements LogReader; it always fails.

func (NoopLogReader) VerifyOperationalContinuity

Section titled “func (NoopLogReader) VerifyOperationalContinuity”
func (n NoopLogReader) VerifyOperationalContinuity(context.Context, string, string, string) error

VerifyOperationalContinuity implements LogReader; it always fails.

type VerificationError

Section titled “type VerificationError”

VerificationError is a structured lifecycle-log verification failure.

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

func (*VerificationError) Code

Section titled “func (*VerificationError) Code”
func (e *VerificationError) Code() string

Code returns the machine-readable failure code (for example “log_error”).

func (*VerificationError) Error

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

Error implements the error interface; it returns the failure message.

func (*VerificationError) Message

Section titled “func (*VerificationError) Message”
func (e *VerificationError) Message() string

Message returns the human-readable failure message.

func (*VerificationError) Transient

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

Transient reports whether retrying the operation may succeed.

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.