awid

package
v1.24.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 19, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultTimeout is the default HTTP timeout used by the client.
	DefaultTimeout = 10 * time.Second

	MaxResponseSize = 10 * 1024 * 1024
)
View Source 
const (
	LifetimeEphemeral  = "ephemeral"
	LifetimePersistent = "persistent"

	CustodySelf      = "self"
	CustodyCustodial = "custodial"
)
View Source 
const AnnouncementMaxAge = 7 * 24 * time.Hour

AnnouncementMaxAge is the maximum age for rotation and replacement announcements. Announcements older than this are rejected to prevent replay attacks.

View Source 
const DefaultAWIDRegistryURL = "https://api.awid.ai"

Variables

This section is empty.

Functions

func AWIDTXTName added in v1.3.0 

func AWIDTXTName(domain string) string

func ArchiveKey 

func ArchiveKey(keysDir, oldDID string, pub ed25519.PublicKey, priv ed25519.PrivateKey) error

ArchiveKey writes a keypair to keysDir/rotated/ named by the old DID. Colons in the DID are replaced with dashes for filesystem compatibility.

func AtomicWriteFile added in v1.4.0 

func AtomicWriteFile(path string, data []byte) error

AtomicWriteFile exposes the atomic secret-file writer for higher-level CLI state that must survive partial failures safely.

func BuildTeamID added in v1.7.0 

func BuildTeamID(domain, name string) string

BuildTeamID returns the canonical colon-form team identifier "<name>:<domain>".

func CanonicalDidLogPayload added in v1.3.0 

func CanonicalDidLogPayload(didAW string, head *DidKeyEvidence) string

func CanonicalJSON 

func CanonicalJSON(env *MessageEnvelope) string

CanonicalJSON builds the canonical JSON payload for message signing. Fields are sorted lexicographically, no whitespace, minimal escaping. Optional fields (conversation_id, from_stable_id, message_id, to_stable_id) are omitted when empty. See also LogEntry.CanonicalJSON which always includes all fields with null for absent values.

func CanonicalJSONValue added in v1.7.0 

func CanonicalJSONValue(v any) (string, error)

CanonicalJSONValue builds canonical JSON for an arbitrary JSON-compatible value. It is used for generic DIDKey-authenticated payload signing on the aw id sign / aw id request code path.

HTML escaping is explicitly disabled via json.Encoder.SetEscapeHTML(false) so the output bytes match Python's canonical_json_bytes on the awid / verifier sides, which call json.dumps(..., ensure_ascii=False, separators=(",", ":")). Go's default json.Marshal would escape <, >, and & to \u003c, \u003e, \u0026; any signed payload containing those chars (common in free-form user notes and URLs) would silently fail signature verification across languages. Go's encoder does NOT escape non-ASCII by default, so it already matches Python's ensure_ascii=False for unicode — tested by TestCanonicalJSONValuePreservesUnicode.

This matches the shared onboardingDIDKeySignPayload helper used by the onboarding signing family (cli-signup, claim-human, bootstrap-redeem).

func CanonicalReplacementJSON added in v0.40.0 

func CanonicalReplacementJSON(address, controllerDID, oldDID, newDID, timestamp string) string

CanonicalReplacementJSON builds the canonical JSON for controller-authorized address replacement signing.

func CanonicalRotationJSON 

func CanonicalRotationJSON(oldDID, newDID, timestamp string) string

CanonicalRotationJSON builds the canonical JSON for rotation signing. Fields: new_did, old_did, timestamp — sorted lexicographically.

func CanonicalServerOrigin added in v1.24.0 

func CanonicalServerOrigin(raw string) (string, error)

CanonicalServerOrigin normalizes an aweb delivery origin.

Delivery origins are origins, not API base URLs: scheme + host + optional non-default port, with no path, userinfo, query, or fragment.

func ComputeDIDKey 

func ComputeDIDKey(pub ed25519.PublicKey) string

ComputeDIDKey encodes an Ed25519 public key as a did:key DID string.

func ComputeStableID 

func ComputeStableID(pub ed25519.PublicKey) string

ComputeStableID derives the canonical did:aw stable identifier from an Ed25519 public key. Algorithm: SHA-256 the 32-byte public key, take the first 20 bytes, base58btc encode.

func CoordinationWakeFilter 

func CoordinationWakeFilter(evt AgentEvent, autofeed bool) bool

CoordinationWakeFilter wakes on coordination events only when autofeed is enabled.

func DefaultWakeFilter 

func DefaultWakeFilter(evt AgentEvent, autofeed bool) bool

DefaultWakeFilter combines protocol and coordination filters. This matches the behavior of the previous hardcoded shouldWakeForEvent.

func DescribeIdentityClass added in v1.0.0 

func DescribeIdentityClass(lifetime string) string

func EncodeTeamCertificateHeader added in v1.7.0 

func EncodeTeamCertificateHeader(cert *TeamCertificate) (string, error)

EncodeTeamCertificateHeader encodes a certificate for the X-AWID-Team-Certificate HTTP header (base64 JSON).

func ExtractPublicKey 

func ExtractPublicKey(did string) (ed25519.PublicKey, error)

ExtractPublicKey decodes a did:key DID string to an Ed25519 public key.

func GenerateKeypair 

func GenerateKeypair() (ed25519.PublicKey, ed25519.PrivateKey, error)

GenerateKeypair creates a new Ed25519 keypair using crypto/rand.

func GenerateUUID4 added in v1.7.0 

func GenerateUUID4() (string, error)

GenerateUUID4 returns a random UUID v4 string.

func HTTPErrorBody 

func HTTPErrorBody(err error) (string, bool)

HTTPErrorBody returns the response body for API errors.

func HTTPStatusCode 

func HTTPStatusCode(err error) (int, bool)

HTTPStatusCode returns the HTTP status code for API errors.

func HandleFromAddress added in v1.7.0 

func HandleFromAddress(address string) string

HandleFromAddress extracts the handle/name portion from a public address.

func IdentityHasPublicAddress added in v1.0.0 

func IdentityHasPublicAddress(lifetime string) bool

func IsCoordinationEvent 

func IsCoordinationEvent(evt AgentEvent) bool

IsCoordinationEvent returns true for events that belong to the coordination layer: work_available, claim_update, claim_removed.

func IsHostedSpawnInviteToken added in v1.22.0 

func IsHostedSpawnInviteToken(token string) bool

func IsProtocolEvent 

func IsProtocolEvent(evt AgentEvent) bool

IsProtocolEvent returns true for events that belong to the protocol layer: communication wake events, control signals, and stream errors.

func IsSelfCustodial added in v1.0.0 

func IsSelfCustodial(custody string) bool

func LoadPublicKey 

func LoadPublicKey(path string) (ed25519.PublicKey, error)

LoadPublicKey reads an Ed25519 public key from a PEM file.

func LoadSigningKey 

func LoadSigningKey(path string) (ed25519.PrivateKey, error)

LoadSigningKey reads an Ed25519 private key from a PEM file.

func NormalizeHostedHandleAddress added in v1.21.0 

func NormalizeHostedHandleAddress(target string) string

NormalizeHostedHandleAddress converts @handle/agent shorthand into the canonical hosted address handle.aweb.ai/agent. Dotted handles are already explicit namespaces, so @acme.com/bot becomes acme.com/bot. This is the direct-recipient form; contact-handle namespace expansion is normalized server-side because bare @handle is not a direct recipient.

func NormalizeLifetime added in v1.0.0 

func NormalizeLifetime(lifetime string) string

func OtherConversationParticipants added in v1.24.3 

func OtherConversationParticipants(participantDIDs, participantAddresses []string, selfStableID, selfDID, selfAddress string) ([]string, []string)

OtherConversationParticipants removes the caller's single participant row from paired DID/address participant lists and returns the remaining values.

func ParseTeamID added in v1.7.0 

func ParseTeamID(teamID string) (domain, name string, err error)

ParseTeamID parses the canonical colon-form team identifier "<name>:<domain>". It returns the normalized domain and lowercased team name.

func ProtocolWakeFilter 

func ProtocolWakeFilter(evt AgentEvent, _ bool) bool

ProtocolWakeFilter wakes on protocol events (communication, control, error). Connected events are excluded — they are informational only.

func PublicAddress added in v1.0.0 

func PublicAddress(address, lifetime string) string

func PublicKeyPath added in v1.4.0 

func PublicKeyPath(signingKeyPath string) string

PublicKeyPath returns the sibling public-key PEM path for a signing key path.

func RegisterIdentity added in v1.10.0 

func RegisterIdentity(
	ctx context.Context,
	registryBaseURL string,
	did string,
	stableID string,
	signingKey ed25519.PrivateKey,
) error

func RoutingHandle added in v1.0.0 

func RoutingHandle(alias, address, lifetime string) string

func SaveKeypair 

func SaveKeypair(keysDir, address string, pub ed25519.PublicKey, priv ed25519.PrivateKey) error

SaveKeypair writes a keypair to keysDir as PEM files named by agent address. Private key: 0600. Public key: 0644.

func SaveKeypairAt added in v1.4.0 

func SaveKeypairAt(keyPath, pubPath string, pub ed25519.PublicKey, priv ed25519.PrivateKey) error

SaveKeypairAt writes a keypair to explicit PEM file paths.

func SaveSigningKey added in v1.5.0 

func SaveSigningKey(path string, priv ed25519.PrivateKey) error

SaveSigningKey writes only the private signing key PEM to the given path.

func SaveTeamCertificate added in v1.7.0 

func SaveTeamCertificate(path string, cert *TeamCertificate) error

SaveTeamCertificate writes a certificate to disk as JSON with 0600 permissions.

func ScanKeysForPublicKey 

func ScanKeysForPublicKey(keysDir string, target ed25519.PublicKey) (string, error)

ScanKeysForPublicKey searches keysDir (and keysDir/rotated/) for a private key whose derived public key matches target. Returns the path to the private key file, or empty string if not found.

func SignArbitraryPayload added in v1.7.0 

func SignArbitraryPayload(key ed25519.PrivateKey, payload map[string]any, timestamp string) (didKey string, signature string, canonical string, err error)

SignArbitraryPayload signs a JSON object after injecting the required timestamp field into the signed payload.

func SignMessage 

func SignMessage(key ed25519.PrivateKey, env *MessageEnvelope) (string, error)

SignMessage signs the canonical JSON payload of an envelope. Returns the signature as base64 (RFC 4648, no padding).

func SignRotation 

func SignRotation(oldKey ed25519.PrivateKey, oldDID, newDID, timestamp string) (string, error)

SignRotation signs a rotation announcement with the old key. Returns the signature as base64 (RFC 4648, no padding).

func SigningKeyPath 

func SigningKeyPath(keysDir, address string) string

SigningKeyPath returns the path to an agent's signing key file.

func VerifyDidKeyResolution added in v1.3.0 

func VerifyDidKeyResolution(res *DidKeyResolution, cached *VerifiedLogHead, now time.Time) (StableIdentityOutcome, *VerifiedLogHead, error)

func VerifyReplacementSignature added in v0.40.0 

func VerifyReplacementSignature(controllerPub ed25519.PublicKey, address, controllerDID, oldDID, newDID, timestamp, signature string) (bool, error)

VerifyReplacementSignature verifies a controller-authorized replacement announcement.

func VerifyRotationSignature 

func VerifyRotationSignature(oldPub ed25519.PublicKey, oldDID, newDID, timestamp, signature string) (bool, error)

VerifyRotationSignature verifies a rotation_signature using the old public key.

func VerifyTeamCertificate added in v1.7.0 

func VerifyTeamCertificate(cert *TeamCertificate, teamPub ed25519.PublicKey) error

VerifyTeamCertificate checks the certificate signature against the team's public key. Returns nil if valid, an error describing the failure otherwise.

Types

type APIError 

type APIError struct {
	StatusCode int
	Body       string
}

APIError represents an HTTP error from the aweb API.

func (*APIError) Error 

func (e *APIError) Error() string

type AckResponse 

type AckResponse struct {
	MessageID      string `json:"message_id"`
	AcknowledgedAt string `json:"acknowledged_at"`
}

type AgentEvent 

type AgentEvent struct {
	Type           AgentEventType  `json:"type"`
	Raw            json.RawMessage `json:"raw,omitempty"`
	AgentID        string          `json:"agent_id,omitempty"`
	TeamID         string          `json:"team_id,omitempty"`
	WakeMode       string          `json:"wake_mode,omitempty"`
	Channel        string          `json:"channel,omitempty"`
	MessageID      string          `json:"message_id,omitempty"`
	ConversationID string          `json:"conversation_id,omitempty"`
	FromAlias      string          `json:"from_alias,omitempty"`
	FromStableID   string          `json:"from_stable_id,omitempty"`
	FromDID        string          `json:"from_did,omitempty"`
	FromAddress    string          `json:"from_address,omitempty"`
	SessionID      string          `json:"session_id,omitempty"`
	Subject        string          `json:"subject,omitempty"`
	UnreadCount    int             `json:"unread_count,omitempty"`
	SenderWaiting  bool            `json:"sender_waiting,omitempty"`
	TaskID         string          `json:"task_id,omitempty"`
	Title          string          `json:"title,omitempty"`
	Status         string          `json:"status,omitempty"`
	SignalID       string          `json:"signal_id,omitempty"`
	Text           string          `json:"text,omitempty"`
}

AgentEvent is a typed event emitted by GET /v1/events/stream.

func (AgentEvent) IsActionableCoordination added in v0.30.0 

func (e AgentEvent) IsActionableCoordination() bool

func (AgentEvent) IsInterruptWake added in v0.30.0 

func (e AgentEvent) IsInterruptWake() bool

type AgentEventStream 

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

AgentEventStream decodes typed events from GET /v1/events/stream. It is intentionally low-level: EOF and reconnect/backoff strategy are left to callers.

func (*AgentEventStream) Close 

func (s *AgentEventStream) Close() error

func (*AgentEventStream) Next 

func (s *AgentEventStream) Next(_ context.Context) (*AgentEvent, error)

Next reads the next typed agent event, skipping unknown event names. The ctx parameter is accepted for EventSource interface conformance; cancellation is handled by the underlying HTTP response body context.

type AgentEventType 

type AgentEventType string

AgentEventType identifies a typed event emitted by GET /v1/events/stream. 

const (
	AgentEventConnected        AgentEventType = "connected"
	AgentEventActionableMail   AgentEventType = "actionable_mail"
	AgentEventActionableChat   AgentEventType = "actionable_chat"
	AgentEventWorkAvailable    AgentEventType = "work_available"
	AgentEventClaimUpdate      AgentEventType = "claim_update"
	AgentEventClaimRemoved     AgentEventType = "claim_removed"
	AgentEventControlPause     AgentEventType = "control_pause"
	AgentEventControlResume    AgentEventType = "control_resume"
	AgentEventControlInterrupt AgentEventType = "control_interrupt"
	AgentEventError            AgentEventType = "error"
)

type AgentLogEntry 

type AgentLogEntry struct {
	Operation string `json:"operation"`
	DID       string `json:"did,omitempty"`
	OldDID    string `json:"old_did,omitempty"`
	NewDID    string `json:"new_did,omitempty"`
	Timestamp string `json:"timestamp"`
	SignedBy  string `json:"signed_by"`
}

AgentLogEntry is a single entry in an agent's identity log.

type AgentLogResponse 

type AgentLogResponse struct {
	Entries []AgentLogEntry `json:"entries"`
}

AgentLogResponse is returned by GET /v1/agents/me/log or /v1/agents/{ns}/{alias}/log.

type AgentView 

type AgentView struct {
	AgentID       string `json:"agent_id"`
	Alias         string `json:"alias"`
	DIDKey        string `json:"did_key"`
	DIDAW         string `json:"did_aw,omitempty"`
	Address       string `json:"address,omitempty"`
	HumanName     string `json:"human_name,omitempty"`
	AgentType     string `json:"agent_type,omitempty"`
	WorkspaceType string `json:"workspace_type,omitempty"`
	Role          string `json:"role,omitempty"`
	Hostname      string `json:"hostname,omitempty"`
	WorkspacePath string `json:"workspace_path,omitempty"`
	Repo          string `json:"repo,omitempty"`
	Status        string `json:"status,omitempty"`
	LastSeen      string `json:"last_seen,omitempty"`
	Online        bool   `json:"online,omitempty"`
	Lifetime      string `json:"lifetime,omitempty"`
}

type AlreadyRegisteredError added in v1.4.0 

type AlreadyRegisteredError struct {
	DIDAW          string
	ExistingDIDKey string
}

func (*AlreadyRegisteredError) Error added in v1.4.0 

func (e *AlreadyRegisteredError) Error() string

type BootstrapRedeemRequest added in v1.7.0 

type BootstrapRedeemRequest struct {
	Token  string `json:"token"`
	DIDKey string `json:"did_key"`
	DIDAW  string `json:"did_aw,omitempty"`
}

BootstrapRedeemRequest is sent to POST /api/v1/onboarding/bootstrap-redeem.

type BootstrapRedeemResponse added in v1.7.0 

type BootstrapRedeemResponse struct {
	Certificate   string `json:"certificate"`
	TeamID        string `json:"team_id"`
	Lifetime      string `json:"lifetime"`
	Alias         string `json:"alias"`
	DIDAW         string `json:"did_aw,omitempty"`
	MemberAddress string `json:"member_address,omitempty"`
}

BootstrapRedeemResponse is returned by POST /api/v1/onboarding/bootstrap-redeem.

type ChainResolver 

type ChainResolver struct {
	DIDKey   *DIDKeyResolver
	Registry *RegistryResolver
	Pin      *PinResolver
}

ChainResolver dispatches resolution by identifier format. did:key identifiers use DIDKeyResolver; registry identifiers use RegistryResolver.

func (*ChainResolver) Resolve 

func (r *ChainResolver) Resolve(ctx context.Context, identifier string) (*ResolvedIdentity, error)

func (*ChainResolver) VerifyStableIdentity added in v1.3.0 

func (r *ChainResolver) VerifyStableIdentity(ctx context.Context, address, stableID string) *StableIdentityVerification

type ChatCreateSessionRequest 

type ChatCreateSessionRequest struct {
	SessionID     string   `json:"session_id,omitempty"`
	ToAliases     []string `json:"to_aliases,omitempty"`
	ToDIDs        []string `json:"to_dids,omitempty"`
	ToAddresses   []string `json:"to_addresses,omitempty"`
	Message       string   `json:"message"`
	Leaving       bool     `json:"leaving,omitempty"`
	WaitSeconds   *int     `json:"wait_seconds,omitempty"`
	ReplyTo       string   `json:"reply_to,omitempty"`
	FromDID       string   `json:"from_did,omitempty"`
	Signature     string   `json:"signature,omitempty"`
	Timestamp     string   `json:"timestamp,omitempty"`
	MessageID     string   `json:"message_id,omitempty"`
	SignedPayload string   `json:"signed_payload,omitempty"`
}

type ChatCreateSessionResponse 

type ChatCreateSessionResponse struct {
	SessionID        string            `json:"session_id"`
	MessageID        string            `json:"message_id"`
	Participants     []ChatParticipant `json:"participants"`
	SSEURL           string            `json:"sse_url"`
	TargetsConnected []string          `json:"targets_connected"`
	TargetsLeft      []string          `json:"targets_left"`
}

type ChatHistoryParams 

type ChatHistoryParams struct {
	SessionID  string
	UnreadOnly bool
	Limit      int
}

type ChatHistoryResponse 

type ChatHistoryResponse struct {
	Messages []ChatMessage `json:"messages"`
}

type ChatListSessionsResponse 

type ChatListSessionsResponse struct {
	Sessions []ChatSessionItem `json:"sessions"`
}

type ChatMarkReadRequest 

type ChatMarkReadRequest struct {
	UpToMessageID string `json:"up_to_message_id"`
}

type ChatMarkReadResponse 

type ChatMarkReadResponse struct {
	Success        bool `json:"success"`
	MessagesMarked int  `json:"messages_marked"`
}

type ChatMessage 

type ChatMessage struct {
	MessageID               string                   `json:"message_id"`
	ConversationID          string                   `json:"conversation_id,omitempty"`
	FromAgent               string                   `json:"from_agent"`
	FromAddress             string                   `json:"from_address,omitempty"`
	ToAddress               string                   `json:"to_address,omitempty"`
	Body                    string                   `json:"body"`
	Timestamp               string                   `json:"timestamp"`
	SenderLeaving           bool                     `json:"sender_leaving"`
	ReplyToMessageID        string                   `json:"reply_to_message_id,omitempty"`
	FromDID                 string                   `json:"from_did,omitempty"`
	ToDID                   string                   `json:"to_did,omitempty"`
	FromStableID            string                   `json:"from_stable_id,omitempty"`
	ToStableID              string                   `json:"to_stable_id,omitempty"`
	Signature               string                   `json:"signature,omitempty"`
	SigningKeyID            string                   `json:"signing_key_id,omitempty"`
	SignedPayload           string                   `json:"signed_payload,omitempty"`
	RotationAnnouncement    *RotationAnnouncement    `json:"rotation_announcement,omitempty"`
	ReplacementAnnouncement *ReplacementAnnouncement `json:"replacement_announcement,omitempty"`
	VerificationStatus      VerificationStatus       `json:"verification_status,omitempty"`
	IsContact               *bool                    `json:"is_contact,omitempty"`
}

type ChatParticipant 

type ChatParticipant struct {
	AgentID string `json:"agent_id"`
	Alias   string `json:"alias"`
	DID     string `json:"did,omitempty"`
	Address string `json:"address,omitempty"`
}

type ChatPendingItem 

type ChatPendingItem struct {
	SessionID            string   `json:"session_id"`
	TeamID               string   `json:"team_id,omitempty"`
	Participants         []string `json:"participants"`
	ParticipantDIDs      []string `json:"participant_dids,omitempty"`
	ParticipantAddresses []string `json:"participant_addresses,omitempty"`
	LastMessage          string   `json:"last_message"`
	LastFrom             string   `json:"last_from"`
	LastFromStableID     string   `json:"last_from_stable_id,omitempty"`
	LastFromDID          string   `json:"last_from_did,omitempty"`
	LastFromAddress      string   `json:"last_from_address,omitempty"`
	UnreadCount          int      `json:"unread_count"`
	LastActivity         string   `json:"last_activity"`
	SenderWaiting        bool     `json:"sender_waiting"`
	TimeRemainingSeconds *int     `json:"time_remaining_seconds"`
}

type ChatPendingResponse 

type ChatPendingResponse struct {
	Pending         []ChatPendingItem `json:"pending"`
	MessagesWaiting int               `json:"messages_waiting"`
}

type ChatSendMessageRequest 

type ChatSendMessageRequest struct {
	Body          string `json:"body"`
	Leaving       bool   `json:"leaving,omitempty"`
	ExtendWait    bool   `json:"hang_on,omitempty"`
	ReplyTo       string `json:"reply_to,omitempty"`
	FromDID       string `json:"from_did,omitempty"`
	Signature     string `json:"signature,omitempty"`
	Timestamp     string `json:"timestamp,omitempty"`
	MessageID     string `json:"message_id,omitempty"`
	SignedPayload string `json:"signed_payload,omitempty"`
}

ChatSendMessage sends a message in an existing chat session.

type ChatSendMessageResponse 

type ChatSendMessageResponse struct {
	MessageID          string `json:"message_id"`
	Delivered          bool   `json:"delivered"`
	ExtendsWaitSeconds int    `json:"extends_wait_seconds"`
}

type ChatSessionItem 

type ChatSessionItem struct {
	SessionID            string   `json:"session_id"`
	TeamID               string   `json:"team_id,omitempty"`
	Participants         []string `json:"participants"`
	ParticipantDIDs      []string `json:"participant_dids,omitempty"`
	ParticipantAddresses []string `json:"participant_addresses,omitempty"`
	CreatedAt            string   `json:"created_at"`
	LastActivity         string   `json:"last_activity,omitempty"`
	SenderWaiting        bool     `json:"sender_waiting,omitempty"`
}

ChatListSessions lists chat sessions the authenticated agent participates in.

type CheckUsernameRequest added in v1.7.0 

type CheckUsernameRequest struct {
	Username string `json:"username"`
}

CheckUsernameRequest is the body for POST /api/v1/onboarding/check-username.

type CheckUsernameResponse added in v1.7.0 

type CheckUsernameResponse struct {
	Available bool   `json:"available"`
	Reason    string `json:"reason,omitempty"`
}

CheckUsernameResponse is the reply from POST /api/v1/onboarding/check-username. Reason is empty when Available is true; otherwise one of "taken", "invalid_format", "reserved".

func CheckUsername added in v1.7.0 

func CheckUsername(ctx context.Context, onboardingURL, username string) (*CheckUsernameResponse, error)

CheckUsername validates a username against the hosted onboarding service. No auth required.

type ClaimHumanRequest 

type ClaimHumanRequest struct {
	Username string `json:"username"`
	Email    string `json:"email"`
	DIDKey   string `json:"did_key"`
}

ClaimHumanRequest is sent to POST /api/v1/claim-human.

type ClaimHumanResponse 

type ClaimHumanResponse struct {
	Status string `json:"status"`
	Email  string `json:"email,omitempty"`
}

ClaimHumanResponse is returned by POST /api/v1/claim-human.

type CliSignupRequest added in v1.7.0 

type CliSignupRequest struct {
	Username string `json:"username"`
	DIDKey   string `json:"did_key"`
	DIDAW    string `json:"did_aw"`
	Alias    string `json:"alias"`
}

CliSignupRequest is the body for POST /api/v1/onboarding/cli-signup. DIDKey must be the did:key the CLI just registered at awid via POST /v1/did. DIDAW is the stable id (did:aw:...) for that same keypair.

type CliSignupResponse added in v1.7.0 

type CliSignupResponse struct {
	UserID          string `json:"user_id"`
	Username        string `json:"username"`
	OrgID           string `json:"org_id"`
	NamespaceDomain string `json:"namespace_domain"`
	TeamID          string `json:"team_id"`
	APIKey          string `json:"api_key"`
	Certificate     string `json:"certificate"`
	DIDAW           string `json:"did_aw"`
	MemberAddress   string `json:"member_address"`
	Alias           string `json:"alias"`
}

CliSignupResponse carries the hosted onboarding reply: the signed team certificate plus the identity metadata the CLI needs to write .aw/identity.yaml. Certificate is a base64-encoded team certificate JSON document.

func CliSignup added in v1.7.0 

func CliSignup(
	ctx context.Context,
	onboardingURL string,
	req *CliSignupRequest,
	signingKey ed25519.PrivateKey,
) (*CliSignupResponse, error)

CliSignup creates a hosted aweb.ai account + personal namespace + default team + signed team certificate, tying it to a did:aw the CLI already registered at awid. The request is DIDKey-signed by signingKey (which must match req.DIDKey).

Critical implementation detail: the JSON body is marshaled exactly once, those bytes are hashed for body_sha256 in the signature envelope, and those same bytes are sent as the HTTP request body. Re-marshalling after hashing would desync the hash from the wire bytes and the server would reject the signature.

type Client 

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

Client is an aweb HTTP client.

It is designed to be easy to extract into a standalone repo and to be used by: - the `aw` CLI - higher-level coordination products built on the same transport

func New 

func New(baseURL string) (*Client, error)

New creates a new client.

func NewWithCertificate added in v1.7.0 

func NewWithCertificate(baseURL string, signingKey ed25519.PrivateKey, cert *TeamCertificate) (*Client, error)

NewWithCertificate creates an authenticated client that uses DIDKey signatures and a team certificate instead of API key authentication.

func NewWithIdentity 

func NewWithIdentity(baseURL string, signingKey ed25519.PrivateKey, did string) (*Client, error)

NewWithIdentity creates an authenticated client with signing capability.

func (*Client) AcceptSpawnInvite added in v1.22.0 

func (c *Client) AcceptSpawnInvite(ctx context.Context, req *SpawnAcceptInviteRequest) (*SpawnAcceptInviteResponse, error)

func (*Client) AckMessage 

func (c *Client) AckMessage(ctx context.Context, messageID string) (*AckResponse, error)

func (*Client) Address added in v1.7.0 

func (c *Client) Address() string

Address returns the client's address, if configured.

func (*Client) AgentLog 

func (c *Client) AgentLog(ctx context.Context, address string) (*AgentLogResponse, error)

AgentLog fetches the identity log for an agent. If address is empty, fetches the caller's own log (requires API key). Otherwise address should be "namespace/alias" for a peer lookup.

func (*Client) BootstrapRedeem added in v1.7.0 

func (c *Client) BootstrapRedeem(ctx context.Context, req *BootstrapRedeemRequest) (*BootstrapRedeemResponse, error)

BootstrapRedeem redeems a one-time bootstrap token into a team certificate.

func (*Client) ChatCreateSession 

func (c *Client) ChatCreateSession(ctx context.Context, req *ChatCreateSessionRequest) (*ChatCreateSessionResponse, error)

func (*Client) ChatHistory 

func (c *Client) ChatHistory(ctx context.Context, p ChatHistoryParams) (*ChatHistoryResponse, error)

func (*Client) ChatListSessions 

func (c *Client) ChatListSessions(ctx context.Context) (*ChatListSessionsResponse, error)

func (*Client) ChatMarkRead 

func (c *Client) ChatMarkRead(ctx context.Context, sessionID string, req *ChatMarkReadRequest) (*ChatMarkReadResponse, error)

func (*Client) ChatPending 

func (c *Client) ChatPending(ctx context.Context) (*ChatPendingResponse, error)

func (*Client) ChatSendMessage 

func (c *Client) ChatSendMessage(ctx context.Context, sessionID string, req *ChatSendMessageRequest) (*ChatSendMessageResponse, error)

func (*Client) ChatStream 

func (c *Client) ChatStream(ctx context.Context, sessionID string, deadline time.Time, after *time.Time) (*SSEStream, error)

ChatStream opens an SSE stream for a session.

deadline is required by the aweb API and must be a future time. after controls replay: if non-nil, the server replays only messages created after that timestamp; if nil, no replay (server polls from now). Uses a dedicated HTTP client without response timeout since SSE connections are long-lived.

func (*Client) CheckTOFUPin 

func (c *Client) CheckTOFUPin(ctx context.Context, status VerificationStatus, fromAddress, fromDID, fromStableID string, ra *RotationAnnouncement, repl *ReplacementAnnouncement) VerificationStatus

CheckTOFUPin checks a verified message against the TOFU pin store. On first contact, creates a pin. On subsequent contact with matching DID, updates last_seen. On DID mismatch, checks for a valid rotation announcement before returning IdentityMismatch. Returns the status unchanged if no pin store is set, the message is not verified, or from_did/from_address is empty. Uses the resolver to determine the sender's lifetime (ephemeral agents skip pinning) and custody (custodial agents return VerifiedCustodial).

When fromStableID is present, pins are keyed by stable_id instead of did:key. The pin stores the last observed did:key for that stable identity, so a stable_id can survive key rotation while still enforcing continuity.

func (*Client) ClaimHuman 

func (c *Client) ClaimHuman(ctx context.Context, req *ClaimHumanRequest) (*ClaimHumanResponse, error)

ClaimHuman calls the cloud onboarding endpoint to attach a human account to an existing CLI-created agent identity. It is not an awid registry route.

func (*Client) CreateContact 

func (c *Client) CreateContact(ctx context.Context, req *ContactCreateRequest) (*ContactCreateResponse, error)

func (*Client) CreateSpawnInvite added in v1.22.0 

func (c *Client) CreateSpawnInvite(ctx context.Context, req *SpawnCreateInviteRequest) (*SpawnCreateInviteResponse, error)

func (*Client) DID 

func (c *Client) DID() string

DID returns the client's DID, or empty for legacy/custodial clients.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, path string) error

Delete performs an HTTP DELETE request.

func (*Client) DeleteContact 

func (c *Client) DeleteContact(ctx context.Context, contactID string) (*ContactDeleteResponse, error)

DeleteContact removes a contact by ID. Uses do() directly because the existing delete() helper discards the response body.

func (*Client) Deregister 

func (c *Client) Deregister(ctx context.Context) error

Deregister deregisters the authenticated agent (self). Server destroys the keypair, marks agent as deregistered, frees the alias for reuse.

func (*Client) DeregisterAgent 

func (c *Client) DeregisterAgent(ctx context.Context, namespace, alias string) error

DeregisterAgent deregisters a peer agent by address. Used by team controllers to clean up ephemeral agents.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method, path string, in any, out any) error

Do performs an HTTP request with optional JSON body and response decoding.

func (*Client) DoRaw 

func (c *Client) DoRaw(ctx context.Context, method, path, accept string, in any) (*http.Response, error)

DoRaw performs an HTTP request and returns the raw response.

func (*Client) DoRawWithHeaders added in v1.23.0 

func (c *Client) DoRawWithHeaders(ctx context.Context, method, path, accept string, in any, extraHeaders map[string]string) (*http.Response, error)

DoRawWithHeaders performs an HTTP request and returns the raw response.

func (*Client) DoWithHeaders added in v1.23.0 

func (c *Client) DoWithHeaders(ctx context.Context, method, path string, in any, out any, extraHeaders map[string]string) error

DoWithHeaders performs an HTTP request with optional JSON body, response decoding, and additional request headers.

func (*Client) EventStream 

func (c *Client) EventStream(ctx context.Context, deadline time.Time) (*AgentEventStream, error)

EventStream opens GET /v1/events/stream using the active client auth. deadline is sent as an ISO8601/RFC3339 timestamp because the server expects an absolute time.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, path string, out any) error

Get performs an HTTP GET request and decodes the JSON response.

func (*Client) HTTPClient added in v1.3.0 

func (c *Client) HTTPClient() *http.Client

HTTPClient returns the HTTP client used for standard JSON API calls.

func (*Client) Heartbeat 

func (c *Client) Heartbeat(ctx context.Context) (*HeartbeatResponse, error)

Heartbeat reports agent liveness to the aweb server.

func (*Client) Inbox 

func (c *Client) Inbox(ctx context.Context, p InboxParams) (*InboxResponse, error)

func (*Client) InterruptAgent 

func (c *Client) InterruptAgent(ctx context.Context, alias string) (*SendControlSignalResponse, error)

func (*Client) LatestClientVersion 

func (c *Client) LatestClientVersion() string

LatestClientVersion returns the most recent X-Latest-Client-Version header value seen in any API response, or empty if no header was received.

func (*Client) ListAgents 

func (c *Client) ListAgents(ctx context.Context) (*ListAgentsResponse, error)

ListAgents lists agents visible in the authenticated team.

func (*Client) ListContacts 

func (c *Client) ListContacts(ctx context.Context) (*ContactListResponse, error)

func (*Client) ListConversations added in v1.20.0 

func (c *Client) ListConversations(ctx context.Context, limit int) (*ConversationsResponse, error)

func (*Client) ListConversationsWithParams added in v1.20.2 

func (c *Client) ListConversationsWithParams(ctx context.Context, params ConversationListParams) (*ConversationsResponse, error)

func (*Client) ListNamespaces 

func (c *Client) ListNamespaces(ctx context.Context) (*ListNamespacesResponse, error)

ListNamespaces fetches the namespaces owned by the authenticated user. Uses the /api/ prefix on the hosted admin surface.

func (*Client) MailConversation added in v1.19.0 

func (c *Client) MailConversation(ctx context.Context, conversationID string, limit int) (*InboxResponse, error)

func (*Client) NetworkDirectoryGet 

func (c *Client) NetworkDirectoryGet(ctx context.Context, domain, handle string) (*NetworkDirectoryAgent, error)

func (*Client) NetworkDirectorySearch 

func (c *Client) NetworkDirectorySearch(ctx context.Context, p NetworkDirectoryParams) (*NetworkDirectoryResponse, error)

func (*Client) NormalizeRecipientBinding added in v1.7.0 

func (c *Client) NormalizeRecipientBinding(status VerificationStatus, toDID string, toStableID string) VerificationStatus

NormalizeRecipientBinding applies the local recipient-binding check after signature verification and any sender-side trust normalization.

func (*Client) NormalizeSenderTrust added in v1.0.7 

func (c *Client) NormalizeSenderTrust(ctx context.Context, status VerificationStatus, rawAddress, fromDID, fromStableID string, ra *RotationAnnouncement, repl *ReplacementAnnouncement, isContact *bool) (VerificationStatus, *bool)

NormalizeSenderTrust applies sender-specific trust normalization after signature verification. It suppresses contact tags for ephemeral senders and then applies continuity pinning using shared resolver metadata.

func (*Client) Patch 

func (c *Client) Patch(ctx context.Context, path string, in any, out any) error

Patch performs an HTTP PATCH request with a JSON body and decodes the JSON response.

func (*Client) PauseAgent 

func (c *Client) PauseAgent(ctx context.Context, alias string) (*SendControlSignalResponse, error)

func (*Client) Post 

func (c *Client) Post(ctx context.Context, path string, in any, out any) error

Post performs an HTTP POST request with a JSON body and decodes the JSON response.

func (*Client) PostWithHeaders added in v1.23.0 

func (c *Client) PostWithHeaders(ctx context.Context, path string, in any, out any, extraHeaders map[string]string) error

PostWithHeaders performs an HTTP POST with additional request headers.

func (*Client) Put 

func (c *Client) Put(ctx context.Context, path string, in any, out any) error

Put performs an HTTP PUT request with a JSON body and decodes the JSON response.

func (*Client) ResolveIdentity added in v1.7.0 

func (c *Client) ResolveIdentity(ctx context.Context, identifier string) (*ResolvedIdentity, error)

func (*Client) ResumeAgent 

func (c *Client) ResumeAgent(ctx context.Context, alias string) (*SendControlSignalResponse, error)

func (*Client) RotateKey 

func (c *Client) RotateKey(ctx context.Context, req *RotateKeyRequest) (*RotateKeyResponse, error)

RotateKey sends a key rotation request to the server. The client must have been created with NewWithIdentity (has a signing key). The rotation_signature is computed by signing the canonical rotation payload with the current (old) key.

func (*Client) RotateKeyCustodial 

func (c *Client) RotateKeyCustodial(ctx context.Context, req *RotateKeyCustodialRequest) (*RotateKeyResponse, error)

RotateKeyCustodial sends a rotation request where the server holds the old key. For custodial→self: server signs the rotation on behalf, client provides new key material. For custodial→custodial: server generates new keypair; key material fields are omitted.

func (*Client) SendControlSignal 

func (c *Client) SendControlSignal(ctx context.Context, alias string, signal ControlSignal) (*SendControlSignalResponse, error)

func (*Client) SendMessage 

func (c *Client) SendMessage(ctx context.Context, req *SendMessageRequest) (*SendMessageResponse, error)

func (*Client) SendMessageByIdentity added in v1.7.0 

func (c *Client) SendMessageByIdentity(ctx context.Context, req *SendMessageRequest) (*SendMessageResponse, error)

func (*Client) SetAddress 

func (c *Client) SetAddress(address string)

SetAddress sets the client's agent address (namespace/alias) for use in signed message envelopes.

func (*Client) SetHTTPClient 

func (c *Client) SetHTTPClient(httpClient *http.Client)

SetHTTPClient replaces the client's HTTP client used for normal API calls. A nil client is ignored.

func (*Client) SetPinStore 

func (c *Client) SetPinStore(ps *PinStore, path string)

SetPinStore sets the TOFU pin store for sender identity verification. If path is non-empty, the store is persisted to disk after updates.

func (*Client) SetRequireRecipientBindingForDirectAddresses added in v1.18.5 

func (c *Client) SetRequireRecipientBindingForDirectAddresses(required bool)

SetRequireRecipientBindingForDirectAddresses controls whether signed direct address sends must bind the recipient address to a current did:key before posting. Persistent identity clients should enable this so private or hidden registry addresses fail closed instead of falling through to local routing.

func (*Client) SetResolver 

func (c *Client) SetResolver(r IdentityResolver)

SetResolver sets the identity resolver used to resolve recipient DIDs for to_did binding in signed envelopes.

func (*Client) SetSSEClient 

func (c *Client) SetSSEClient(httpClient *http.Client)

SetSSEClient replaces the client's HTTP client used for SSE requests. A nil client is ignored.

func (*Client) SetStableID 

func (c *Client) SetStableID(id string)

SetStableID sets the client's stable identifier (did:aw:...) for use as from_stable_id in outgoing signed envelopes.

func (*Client) SigningKey 

func (c *Client) SigningKey() ed25519.PrivateKey

SigningKey returns the client's signing key, or nil for legacy/custodial clients.

func (*Client) StableID added in v1.7.0 

func (c *Client) StableID() string

StableID returns the client's stable identifier, if configured.

func (*Client) SuggestAliasPrefix 

func (c *Client) SuggestAliasPrefix(ctx context.Context) (*SuggestAliasPrefixResponse, error)

SuggestAliasPrefix suggests the next available classic alias prefix for the authenticated team.

POST /v1/agents/suggest-alias-prefix

func (*Client) TeamID added in v1.20.0 

func (c *Client) TeamID() string

type Contact 

type Contact struct {
	ContactID      string `json:"contact_id"`
	ContactAddress string `json:"contact_address"`
	Label          string `json:"label,omitempty"`
	CreatedAt      string `json:"created_at"`
}

type ContactCreateRequest 

type ContactCreateRequest struct {
	ContactAddress string `json:"contact_address"`
	Label          string `json:"label,omitempty"`
}

type ContactCreateResponse 

type ContactCreateResponse struct {
	ContactID      string `json:"contact_id"`
	ContactAddress string `json:"contact_address"`
	Label          string `json:"label"`
	CreatedAt      string `json:"created_at"`
}

type ContactDeleteResponse 

type ContactDeleteResponse struct {
	Deleted bool `json:"deleted"`
}

type ContactListResponse 

type ContactListResponse struct {
	Contacts []Contact `json:"contacts"`
}

type ControlSignal 

type ControlSignal string
const (
	ControlSignalPause     ControlSignal = "pause"
	ControlSignalResume    ControlSignal = "resume"
	ControlSignalInterrupt ControlSignal = "interrupt"
)

func (ControlSignal) Valid 

func (s ControlSignal) Valid() bool

type ConversationItem added in v1.20.0 

type ConversationItem struct {
	ConversationType     string   `json:"conversation_type"`
	ConversationID       string   `json:"conversation_id,omitempty"`
	LegacyMessageID      string   `json:"legacy_message_id,omitempty"`
	Status               string   `json:"status,omitempty"`
	Participants         []string `json:"participants,omitempty"`
	ParticipantDIDs      []string `json:"participant_dids,omitempty"`
	ParticipantAddresses []string `json:"participant_addresses,omitempty"`
	Subject              string   `json:"subject,omitempty"`
	LastMessageAt        string   `json:"last_message_at,omitempty"`
	LastMessageFrom      string   `json:"last_message_from,omitempty"`
	LastMessagePreview   string   `json:"last_message_preview,omitempty"`
	UnreadCount          int      `json:"unread_count,omitempty"`
}

type ConversationListParams added in v1.20.2 

type ConversationListParams struct {
	Limit              int
	Cursor             string
	ConversationType   string
	ParticipantDID     string
	ParticipantAddress string
}

type ConversationsResponse added in v1.20.0 

type ConversationsResponse struct {
	Conversations []ConversationItem `json:"conversations"`
	NextCursor    string             `json:"next_cursor,omitempty"`
}

type DIDKeyResolver 

type DIDKeyResolver struct{}

DIDKeyResolver extracts the public key from a did:key string. No network call required.

func (*DIDKeyResolver) Resolve 

func (r *DIDKeyResolver) Resolve(_ context.Context, identifier string) (*ResolvedIdentity, error)

type DIDMapping added in v1.4.0 

type DIDMapping struct {
	DIDAW         string    `json:"did_aw"`
	CurrentDIDKey string    `json:"current_did_key"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

type DidKeyEvidence added in v1.3.0 

type DidKeyEvidence struct {
	Seq            int     `json:"seq"`
	Operation      string  `json:"operation"`
	PreviousDIDKey *string `json:"previous_did_key"`
	NewDIDKey      string  `json:"new_did_key"`
	PrevEntryHash  *string `json:"prev_entry_hash"`
	EntryHash      string  `json:"entry_hash"`
	StateHash      string  `json:"state_hash"`
	AuthorizedBy   string  `json:"authorized_by"`
	Signature      string  `json:"signature"`
	Timestamp      string  `json:"timestamp"`
}

type DidKeyResolution added in v1.3.0 

type DidKeyResolution struct {
	DIDAW         string          `json:"did_aw"`
	CurrentDIDKey string          `json:"current_did_key"`
	LogHead       *DidKeyEvidence `json:"log_head"`
}

type DiscoveryResponse added in v1.7.0 

type DiscoveryResponse struct {
	OnboardingURL string   `json:"onboarding_url"`
	AwebURL       string   `json:"aweb_url"`
	RegistryURL   string   `json:"registry_url"`
	Version       string   `json:"version,omitempty"`
	Features      []string `json:"features,omitempty"`
}

func DiscoverServices added in v1.7.0 

func DiscoverServices(ctx context.Context, baseURL string) (*DiscoveryResponse, error)

type DomainAuthority added in v1.3.0 

type DomainAuthority struct {
	ControllerDID string
	RegistryURL   string
	DNSName       string
	Inherited     bool
}

func DiscoverAuthoritativeRegistry added in v1.3.0 

func DiscoverAuthoritativeRegistry(ctx context.Context, resolver TXTResolver, domain string) (DomainAuthority, error)

func ParseAWIDTXTRecord added in v1.3.0 

func ParseAWIDTXTRecord(record, dnsName string) (DomainAuthority, error)

func VerifyExactDomainAuthority added in v1.3.0 

func VerifyExactDomainAuthority(ctx context.Context, resolver TXTResolver, domain string) (DomainAuthority, error)

type EventSource 

type EventSource interface {
	Next(ctx context.Context) (*AgentEvent, error)
	Close() error
}

EventSource is the protocol-layer abstraction for receiving agent events. Implementations handle connection management and reconnection internally.

type HeartbeatResponse 

type HeartbeatResponse struct {
	AgentID    string `json:"agent_id"`
	Alias      string `json:"alias"`
	LastSeenAt string `json:"last_seen_at"`
}

HeartbeatResponse is returned by POST /v1/agents/heartbeat.

type IdentityClass added in v1.0.0 

type IdentityClass string
const (
	IdentityClassEphemeral  IdentityClass = LifetimeEphemeral
	IdentityClassPersistent IdentityClass = LifetimePersistent
)

func IdentityClassFromLifetime added in v1.0.0 

func IdentityClassFromLifetime(lifetime string) IdentityClass

type IdentityResolver 

type IdentityResolver interface {
	Resolve(ctx context.Context, identifier string) (*ResolvedIdentity, error)
}

IdentityResolver resolves an identifier to a ResolvedIdentity.

type InboxMessage 

type InboxMessage struct {
	MessageID               string                   `json:"message_id"`
	ConversationID          string                   `json:"conversation_id,omitempty"`
	FromAgentID             string                   `json:"from_agent_id"`
	FromAlias               string                   `json:"from_alias"`
	ToAlias                 string                   `json:"to_alias,omitempty"`
	FromAddress             string                   `json:"from_address,omitempty"`
	ToAddress               string                   `json:"to_address,omitempty"`
	Subject                 string                   `json:"subject"`
	Body                    string                   `json:"body"`
	Priority                MessagePriority          `json:"priority"`
	ThreadID                *string                  `json:"thread_id"`
	ReadAt                  *string                  `json:"read_at"`
	CreatedAt               string                   `json:"created_at"`
	FromDID                 string                   `json:"from_did,omitempty"`
	ToDID                   string                   `json:"to_did,omitempty"`
	FromStableID            string                   `json:"from_stable_id,omitempty"`
	ToStableID              string                   `json:"to_stable_id,omitempty"`
	Signature               string                   `json:"signature,omitempty"`
	SigningKeyID            string                   `json:"signing_key_id,omitempty"`
	SignedPayload           string                   `json:"signed_payload,omitempty"`
	RotationAnnouncement    *RotationAnnouncement    `json:"rotation_announcement,omitempty"`
	ReplacementAnnouncement *ReplacementAnnouncement `json:"replacement_announcement,omitempty"`
	VerificationStatus      VerificationStatus       `json:"verification_status,omitempty"`
	IsContact               *bool                    `json:"is_contact,omitempty"`
}

type InboxParams 

type InboxParams struct {
	UnreadOnly bool
	Limit      int
	MessageID  string
}

type InboxResponse 

type InboxResponse struct {
	Messages []InboxMessage `json:"messages"`
}

type ListAgentsResponse 

type ListAgentsResponse struct {
	TeamID string      `json:"team_id"`
	Agents []AgentView `json:"agents"`
}

type ListNamespacesResponse 

type ListNamespacesResponse struct {
	Namespaces []Namespace `json:"namespaces"`
}

ListNamespacesResponse is returned by GET /api/v1/auth/namespaces.

type MessageEnvelope 

type MessageEnvelope struct {
	From           string `json:"from"`
	FromDID        string `json:"from_did"`
	To             string `json:"to"`
	ToDID          string `json:"to_did"`
	Type           string `json:"type"`
	Priority       string `json:"priority,omitempty"`
	WaitSeconds    *int   `json:"wait_seconds,omitempty"`
	Subject        string `json:"subject"`
	Body           string `json:"body"`
	Timestamp      string `json:"timestamp"`
	FromStableID   string `json:"from_stable_id,omitempty"`
	ToStableID     string `json:"to_stable_id,omitempty"`
	MessageID      string `json:"message_id,omitempty"`
	ConversationID string `json:"conversation_id,omitempty"`
	ReplyTo        string `json:"reply_to,omitempty"`
	SenderLeaving  bool   `json:"sender_leaving,omitempty"`
	HangOn         bool   `json:"hang_on,omitempty"`

	RequireRecipientBinding bool `json:"-"`

	Signature    string `json:"signature,omitempty"`
	SigningKeyID string `json:"signing_key_id,omitempty"`
}

MessageEnvelope holds the fields used for signing and verification. Transport-only fields (Signature, SigningKeyID) are not part of the signed payload but are carried here for convenience.

type MessagePriority 

type MessagePriority string
const (
	PriorityLow    MessagePriority = "low"
	PriorityNormal MessagePriority = "normal"
	PriorityHigh   MessagePriority = "high"
	PriorityUrgent MessagePriority = "urgent"
)

type Namespace 

type Namespace struct {
	Slug       string `json:"slug"`
	Tier       string `json:"tier"`
	AgentCount int    `json:"agent_count,omitempty"`
}

Namespace describes a namespace owned by a user.

type NamespaceReverifyResult added in v1.7.3 

type NamespaceReverifyResult struct {
	NamespaceID        string `json:"namespace_id"`
	Domain             string `json:"domain"`
	ControllerDID      string `json:"controller_did,omitempty"`
	VerificationStatus string `json:"verification_status"`
	LastVerifiedAt     string `json:"last_verified_at,omitempty"`
	CreatedAt          string `json:"created_at"`
	OldControllerDID   string `json:"old_controller_did,omitempty"`
	NewControllerDID   string `json:"new_controller_did,omitempty"`
}

type NetTXTResolver added in v1.3.0 

type NetTXTResolver struct {
	Resolver *net.Resolver
}

func (*NetTXTResolver) LookupTXT added in v1.3.0 

func (r *NetTXTResolver) LookupTXT(ctx context.Context, name string) ([]string, error)

type NetworkAddress 

type NetworkAddress struct {
	Domain    string
	Alias     string
	IsNetwork bool
}

NetworkAddress represents either a network address (domain/alias) or a plain local alias.

func ParseNetworkAddress 

func ParseNetworkAddress(target string) NetworkAddress

ParseNetworkAddress parses a target string into a NetworkAddress. If the string contains a '/', it is treated as a network address (domain/alias). Otherwise it is a plain local alias.

func (NetworkAddress) String 

func (a NetworkAddress) String() string

String returns the canonical string form of the address.

type NetworkDirectoryAgent 

type NetworkDirectoryAgent struct {
	OrgName      string   `json:"org_name"`
	Domain       string   `json:"org_slug"`
	Alias        string   `json:"alias"`
	Name         string   `json:"name,omitempty"`
	Capabilities []string `json:"capabilities"`
	Description  string   `json:"description"`
}

type NetworkDirectoryParams 

type NetworkDirectoryParams struct {
	Capability string
	Domain     string
	Query      string
	Limit      int
}

type NetworkDirectoryResponse 

type NetworkDirectoryResponse struct {
	Agents []NetworkDirectoryAgent `json:"agents"`
	Total  int                     `json:"total"`
}

type Pin 

type Pin struct {
	Address  string `yaml:"address"`
	Handle   string `yaml:"handle,omitempty"`
	StableID string `yaml:"stable_id,omitempty"`
	// DIDKey is the last did:key observed for this identity when the pin key is
	// a stable_id. It allows key-rotation checks without treating stable_id as a
	// blind trust anchor.
	DIDKey    string `yaml:"did_key,omitempty"`
	FirstSeen string `yaml:"first_seen"`
	LastSeen  string `yaml:"last_seen"`
	Server    string `yaml:"server"`
}

Pin records an agent's TOFU-pinned identity.

type PinResolver 

type PinResolver struct {
	Store *PinStore
}

PinResolver looks up identity from the local TOFU pin store.

func (*PinResolver) Resolve 

func (r *PinResolver) Resolve(_ context.Context, identifier string) (*ResolvedIdentity, error)

type PinResult 

type PinResult string

PinResult describes the outcome of a TOFU pin check. 

const (
	PinOK       PinResult = "ok"       // DID matches stored pin.
	PinNew      PinResult = "new"      // No pin existed; caller should store one.
	PinMismatch PinResult = "mismatch" // DID differs from stored pin.
	PinSkipped  PinResult = "skipped"  // Ephemeral agent — no pin check.
)

type PinStore 

type PinStore struct {
	Pins      map[string]*Pin   `yaml:"pins"`
	Addresses map[string]string `yaml:"addresses"`
	// contains filtered or unexported fields
}

PinStore manages TOFU identity pins for known agents. Pins are keyed by did:key or stable_id (did:aw). The Addresses map is a reverse index from address to pin key for the identity-mismatch check.

func LoadPinStore 

func LoadPinStore(path string) (*PinStore, error)

LoadPinStore reads a pin store from disk. Returns an empty store if the file does not exist.

func NewPinStore 

func NewPinStore() *PinStore

NewPinStore returns an empty pin store.

func (*PinStore) CheckPin 

func (ps *PinStore) CheckPin(address, did, lifetime string) PinResult

CheckPin checks whether a DID matches the stored pin for an address. Ephemeral agents always return PinSkipped. If no pin exists for the address, returns PinNew. If the stored DID matches, returns PinOK. If it differs, returns PinMismatch.

func (*PinStore) RemoveAddress added in v1.0.7 

func (ps *PinStore) RemoveAddress(address string) bool

RemoveAddress removes any reverse index and pin associated with an address. Returns true when anything was removed.

func (*PinStore) Save 

func (ps *PinStore) Save(path string) error

Save writes the pin store to disk atomically. Creates parent directories if needed. The file is written with 0600 permissions.

func (*PinStore) StorePin 

func (ps *PinStore) StorePin(did, address, handle, server string)

StorePin records or updates a TOFU pin. If a pin for this DID already exists, only last_seen is updated. Otherwise a new pin is created and the reverse index is updated.

type RecipientResolutionError added in v1.18.5 

type RecipientResolutionError struct {
	Target      string
	MessageType string
	Err         error
}

RecipientResolutionError means a signed message could not bind its direct recipient to a current did:key, so sending must stop before posting.

func (*RecipientResolutionError) Error added in v1.18.5 

func (e *RecipientResolutionError) Error() string

func (*RecipientResolutionError) Unwrap added in v1.18.5 

func (e *RecipientResolutionError) Unwrap() error

type RegistryAddress added in v1.4.0 

type RegistryAddress struct {
	AddressID       string            `json:"address_id"`
	Domain          string            `json:"domain"`
	Name            string            `json:"name"`
	DIDAW           string            `json:"did_aw"`
	CurrentDIDKey   string            `json:"current_did_key"`
	Reachability    string            `json:"reachability"`
	VisibleToTeamID *string           `json:"visible_to_team_id,omitempty"`
	Delivery        *RegistryDelivery `json:"delivery,omitempty"`
	CreatedAt       string            `json:"created_at"`
}

type RegistryAddressList added in v1.4.0 

type RegistryAddressList struct {
	Addresses []RegistryAddress `json:"addresses"`
}

type RegistryCertificate added in v1.7.0 

type RegistryCertificate struct {
	CertificateID string `json:"certificate_id"`
	TeamID        string `json:"team_id"`
	MemberDIDKey  string `json:"member_did_key"`
	MemberDIDAW   string `json:"member_did_aw,omitempty"`
	MemberAddress string `json:"member_address,omitempty"`
	Alias         string `json:"alias"`
	Lifetime      string `json:"lifetime"`
	IssuedAt      string `json:"issued_at"`
	RevokedAt     string `json:"revoked_at,omitempty"`
}

RegistryCertificate represents a registered team membership certificate.

type RegistryClient added in v1.4.0 

type RegistryClient struct {
	DefaultRegistryURL string
	Resolver           *RegistryResolver
	HTTPClient         *http.Client
	RequestID          string
}

func NewAWIDRegistryClient added in v1.4.0 

func NewAWIDRegistryClient(httpClient *http.Client, dnsResolver TXTResolver) *RegistryClient

func (*RegistryClient) CreateTeam added in v1.7.0 

func (c *RegistryClient) CreateTeam(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	displayName string,
	teamDIDKey string,
	controllerKey ed25519.PrivateKey,
) (*RegistryTeam, error)

CreateTeam registers a team under a namespace at awid. Auth: namespace controller DIDKey signature.

func (*RegistryClient) DeleteAddress added in v1.7.0 

func (c *RegistryClient) DeleteAddress(
	ctx context.Context,
	domain string,
	name string,
	controllerSigningKey ed25519.PrivateKey,
	reason string,
) (string, error)

func (*RegistryClient) DeleteAddressAt added in v1.7.0 

func (c *RegistryClient) DeleteAddressAt(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	controllerSigningKey ed25519.PrivateKey,
	reason string,
) error

func (*RegistryClient) DeleteNamespace added in v1.7.0 

func (c *RegistryClient) DeleteNamespace(
	ctx context.Context,
	domain string,
	controllerSigningKey ed25519.PrivateKey,
	reason string,
) (string, error)

func (*RegistryClient) DeleteNamespaceAt added in v1.7.0 

func (c *RegistryClient) DeleteNamespaceAt(
	ctx context.Context,
	registryURL string,
	domain string,
	controllerSigningKey ed25519.PrivateKey,
	reason string,
) error

func (*RegistryClient) DeleteTeam added in v1.7.0 

func (c *RegistryClient) DeleteTeam(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	controllerKey ed25519.PrivateKey,
	reason string,
) error

DeleteTeam removes a team after the caller has already revoked any active certificates. Auth: namespace controller DIDKey signature.

func (*RegistryClient) DiscoverRegistry added in v1.4.0 

func (c *RegistryClient) DiscoverRegistry(ctx context.Context, domain string) (string, error)

func (*RegistryClient) FetchTeamCertificate added in v1.18.1 

func (c *RegistryClient) FetchTeamCertificate(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	certificateID string,
	signingKey ed25519.PrivateKey,
) (*TeamCertificate, error)

FetchTeamCertificate downloads a signed team certificate blob from awid. Auth: the certificate subject's DIDKey signature, or another DID authorized by awid policy for this certificate.

func (*RegistryClient) GetDIDFull added in v1.4.0 

func (c *RegistryClient) GetDIDFull(ctx context.Context, registryURL, didAW string, signingKey ed25519.PrivateKey) (*DIDMapping, error)

func (*RegistryClient) GetDIDLog added in v1.4.0 

func (c *RegistryClient) GetDIDLog(ctx context.Context, registryURL, didAW string) ([]DidKeyEvidence, error)

func (*RegistryClient) GetNamespace added in v1.4.0 

func (c *RegistryClient) GetNamespace(ctx context.Context, domain string) (*RegistryNamespace, string, error)

func (*RegistryClient) GetNamespaceAddress added in v1.5.0 

func (c *RegistryClient) GetNamespaceAddress(ctx context.Context, domain, name string) (*RegistryAddress, string, error)

func (*RegistryClient) GetNamespaceAddressAt added in v1.5.0 

func (c *RegistryClient) GetNamespaceAddressAt(ctx context.Context, registryURL, domain, name string) (*RegistryAddress, string, error)

func (*RegistryClient) GetNamespaceAddressAtSigned added in v1.7.0 

func (c *RegistryClient) GetNamespaceAddressAtSigned(
	ctx context.Context,
	registryURL, domain, name string,
	signingKey ed25519.PrivateKey,
) (*RegistryAddress, string, error)

func (*RegistryClient) GetNamespaceAddressSigned added in v1.7.0 

func (c *RegistryClient) GetNamespaceAddressSigned(
	ctx context.Context,
	domain, name string,
	signingKey ed25519.PrivateKey,
) (*RegistryAddress, string, error)

func (*RegistryClient) GetNamespaceAt added in v1.4.0 

func (c *RegistryClient) GetNamespaceAt(ctx context.Context, registryURL, domain string) (*RegistryNamespace, string, error)

func (*RegistryClient) GetTeam added in v1.7.0 

func (c *RegistryClient) GetTeam(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
) (*RegistryTeam, error)

GetTeam fetches team details from awid.

func (*RegistryClient) ListCertificates added in v1.7.0 

func (c *RegistryClient) ListCertificates(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	activeOnly bool,
) ([]RegistryCertificate, error)

ListCertificates lists certificates for a team.

func (*RegistryClient) ListDIDAddressesAt added in v1.11.0 

func (c *RegistryClient) ListDIDAddressesAt(ctx context.Context, registryURL, didAW string) ([]RegistryAddress, error)

func (*RegistryClient) ListNamespaceAddresses added in v1.4.0 

func (c *RegistryClient) ListNamespaceAddresses(ctx context.Context, domain string) ([]RegistryAddress, string, error)

func (*RegistryClient) ListNamespaceAddressesAt added in v1.4.0 

func (c *RegistryClient) ListNamespaceAddressesAt(ctx context.Context, registryURL, domain string) ([]RegistryAddress, string, error)

func (*RegistryClient) ListNamespaceAddressesAtSigned added in v1.7.0 

func (c *RegistryClient) ListNamespaceAddressesAtSigned(
	ctx context.Context,
	registryURL, domain string,
	signingKey ed25519.PrivateKey,
) ([]RegistryAddress, string, error)

func (*RegistryClient) ListNamespaceAddressesSigned added in v1.7.0 

func (c *RegistryClient) ListNamespaceAddressesSigned(
	ctx context.Context,
	domain string,
	signingKey ed25519.PrivateKey,
) ([]RegistryAddress, string, error)

func (*RegistryClient) RegisterAddress added in v1.5.0 

func (c *RegistryClient) RegisterAddress(
	ctx context.Context,
	domain string,
	name string,
	didAW string,
	currentDIDKey string,
	reachability string,
	controllerSigningKey ed25519.PrivateKey,
	visibleToTeamID string,
) (*RegistryAddress, string, error)

func (*RegistryClient) RegisterAddressAt added in v1.5.0 

func (c *RegistryClient) RegisterAddressAt(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	didAW string,
	currentDIDKey string,
	reachability string,
	controllerSigningKey ed25519.PrivateKey,
	visibleToTeamID string,
) (*RegistryAddress, error)

func (*RegistryClient) RegisterCertificate added in v1.7.0 

func (c *RegistryClient) RegisterCertificate(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	cert *TeamCertificate,
	teamKey ed25519.PrivateKey,
) error

RegisterCertificate registers a team membership certificate at awid. Auth: team controller DIDKey signature (using the team private key).

func (*RegistryClient) RegisterIdentity added in v1.10.0 

func (c *RegistryClient) RegisterIdentity(
	ctx context.Context,
	registryURL string,
	did string,
	stableID string,
	signingKey ed25519.PrivateKey,
) (*DIDMapping, error)

func (*RegistryClient) RegisterNamespace added in v1.5.0 

func (c *RegistryClient) RegisterNamespace(
	ctx context.Context,
	domain string,
	controllerDID string,
	signingKey ed25519.PrivateKey,
) (*RegistryNamespace, string, error)

func (*RegistryClient) RegisterNamespaceAt added in v1.5.0 

func (c *RegistryClient) RegisterNamespaceAt(
	ctx context.Context,
	registryURL string,
	domain string,
	controllerDID string,
	signingKey ed25519.PrivateKey,
) (*RegistryNamespace, error)

func (*RegistryClient) RegisterNamespaceWithDeliveryOrigin added in v1.24.0 

func (c *RegistryClient) RegisterNamespaceWithDeliveryOrigin(
	ctx context.Context,
	domain string,
	controllerDID string,
	signingKey ed25519.PrivateKey,
	defaultDeliveryOrigin string,
) (*RegistryNamespace, string, error)

func (*RegistryClient) RegisterNamespaceWithDeliveryOriginAt added in v1.24.0 

func (c *RegistryClient) RegisterNamespaceWithDeliveryOriginAt(
	ctx context.Context,
	registryURL string,
	domain string,
	controllerDID string,
	signingKey ed25519.PrivateKey,
	defaultDeliveryOrigin string,
) (*RegistryNamespace, error)

func (*RegistryClient) ResolveKey added in v1.4.0 

func (c *RegistryClient) ResolveKey(ctx context.Context, didAW string) (*DidKeyResolution, error)

func (*RegistryClient) ResolveKeyAt added in v1.4.0 

func (c *RegistryClient) ResolveKeyAt(ctx context.Context, registryURL, didAW string) (*DidKeyResolution, error)

func (*RegistryClient) ResolveTeamMember added in v1.7.0 

func (c *RegistryClient) ResolveTeamMember(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	alias string,
) (*TeamMemberReference, error)

ResolveTeamMember resolves an active (team_id, alias) team-member reference.

func (*RegistryClient) ReverifyNamespaceAt added in v1.7.3 

func (c *RegistryClient) ReverifyNamespaceAt(
	ctx context.Context,
	registryURL string,
	domain string,
) (*NamespaceReverifyResult, error)

func (*RegistryClient) RevokeCertificate added in v1.7.0 

func (c *RegistryClient) RevokeCertificate(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	certificateID string,
	teamKey ed25519.PrivateKey,
) error

RevokeCertificate revokes a team membership certificate at awid. Auth: team controller DIDKey signature (using the team private key).

func (*RegistryClient) RotateDIDKey added in v1.4.0 

func (c *RegistryClient) RotateDIDKey(
	ctx context.Context,
	registryURL string,
	didAW string,
	oldSigningKey ed25519.PrivateKey,
	newSigningKey ed25519.PrivateKey,
) (*DIDMapping, error)

func (*RegistryClient) SetFallbackRegistryURL added in v1.4.0 

func (c *RegistryClient) SetFallbackRegistryURL(raw string) error

func (*RegistryClient) SetTeamVisibility added in v1.7.0 

func (c *RegistryClient) SetTeamVisibility(
	ctx context.Context,
	registryURL string,
	domain string,
	name string,
	visibility string,
	teamKey ed25519.PrivateKey,
) (*RegistryTeam, error)

SetTeamVisibility updates a team's visibility metadata at awid. Auth: team controller DIDKey signature (using the team private key).

func (*RegistryClient) UpdateNamespaceDeliveryOrigin added in v1.24.0 

func (c *RegistryClient) UpdateNamespaceDeliveryOrigin(
	ctx context.Context,
	domain string,
	controllerSigningKey ed25519.PrivateKey,
	deliveryOrigin string,
) (*RegistryNamespace, string, error)

func (*RegistryClient) UpdateNamespaceDeliveryOriginAt added in v1.24.0 

func (c *RegistryClient) UpdateNamespaceDeliveryOriginAt(
	ctx context.Context,
	registryURL string,
	domain string,
	controllerSigningKey ed25519.PrivateKey,
	deliveryOrigin string,
) (*RegistryNamespace, error)

type RegistryDelivery added in v1.23.0 

type RegistryDelivery struct {
	Origin string `json:"origin,omitempty"`
	Source string `json:"source,omitempty"`
}

type RegistryError added in v1.4.0 

type RegistryError struct {
	StatusCode int
	Detail     string
}

func (*RegistryError) Error added in v1.4.0 

func (e *RegistryError) Error() string

type RegistryNamespace added in v1.4.0 

type RegistryNamespace struct {
	NamespaceID           string `json:"namespace_id"`
	Domain                string `json:"domain"`
	ControllerDID         string `json:"controller_did,omitempty"`
	VerificationStatus    string `json:"verification_status"`
	DefaultDeliveryOrigin string `json:"default_delivery_origin,omitempty"`
	LastVerifiedAt        string `json:"last_verified_at,omitempty"`
	CreatedAt             string `json:"created_at"`
}

type RegistryResolver added in v1.3.0 

type RegistryResolver struct {
	HTTPClient  *http.Client
	DNSResolver TXTResolver
	Now         func() time.Time
	// contains filtered or unexported fields
}

func NewRegistryResolver added in v1.3.0 

func NewRegistryResolver(httpClient *http.Client, dnsResolver TXTResolver) *RegistryResolver

func (*RegistryResolver) DiscoverRegistry added in v1.3.0 

func (r *RegistryResolver) DiscoverRegistry(ctx context.Context, domain string) (string, error)

func (*RegistryResolver) Resolve added in v1.3.0 

func (r *RegistryResolver) Resolve(ctx context.Context, identifier string) (*ResolvedIdentity, error)

func (*RegistryResolver) SetFallbackRegistryURL added in v1.3.0 

func (r *RegistryResolver) SetFallbackRegistryURL(raw string) error

func (*RegistryResolver) SetLookupSigningKey added in v1.18.3 

func (r *RegistryResolver) SetLookupSigningKey(key ed25519.PrivateKey)

SetLookupSigningKey configures optional DIDKey authentication for namespace address reads so private reachability rows can be resolved when authorized.

func (*RegistryResolver) SetLookupTeamCertificate added in v1.18.6 

func (r *RegistryResolver) SetLookupTeamCertificate(cert *TeamCertificate)

SetLookupTeamCertificate configures the optional team certificate presented alongside signed namespace address reads.

func (*RegistryResolver) VerifyStableIdentity added in v1.3.0 

func (r *RegistryResolver) VerifyStableIdentity(ctx context.Context, address, stableID string) *StableIdentityVerification

type RegistryTeam added in v1.7.0 

type RegistryTeam struct {
	TeamID      string `json:"team_id"`
	Domain      string `json:"domain"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name"`
	TeamDIDKey  string `json:"team_did_key"`
	Visibility  string `json:"visibility"`
	CreatedAt   string `json:"created_at"`
}

RegistryTeam represents a team from the awid registry.

type ReplacementAnnouncement added in v0.40.0 

type ReplacementAnnouncement struct {
	Address             string `json:"address"`
	OldDID              string `json:"old_did"`
	NewDID              string `json:"new_did"`
	ControllerDID       string `json:"controller_did"`
	Timestamp           string `json:"timestamp"`
	ControllerSignature string `json:"controller_signature"`
}

ReplacementAnnouncement is attached when a public address has been controller-authorized onto a fresh identity after loss or migration.

type ResolvedIdentity added in v1.0.0 

type ResolvedIdentity struct {
	DID           string
	StableID      string
	Address       string // address when known; may be empty for addressless references
	ControllerDID string
	Handle        string
	PublicKey     ed25519.PublicKey
	RegistryURL   string
	Custody       string // "self" or "custodial"
	Lifetime      string // "persistent" or "ephemeral"
	ResolvedAt    time.Time
	ResolvedVia   string // "did:key", "registry", "pin"
}

ResolvedIdentity holds resolved identity information for an identity reference.

type RotateKeyCustodialRequest 

type RotateKeyCustodialRequest struct {
	NewDID       string            // did:key of the new key (empty for custodial→custodial)
	NewPublicKey ed25519.PublicKey // raw new public key (nil for custodial→custodial)
	Custody      string            // "self" or "custodial"
}

RotateKeyCustodialRequest is the input to Client.RotateKeyCustodial. For custodial→self graduation: set Custody="self" and provide NewDID/NewPublicKey. For custodial→custodial rotation: set Custody="custodial" and leave NewDID/NewPublicKey empty.

type RotateKeyRequest 

type RotateKeyRequest struct {
	NewDID       string            // did:key of the new key
	NewPublicKey ed25519.PublicKey // raw new public key
	Custody      string            // "self" or "custodial"
}

RotateKeyRequest is the input to Client.RotateKey.

type RotateKeyResponse 

type RotateKeyResponse struct {
	Status       string `json:"status"`
	OldDID       string `json:"old_did"`
	NewDID       string `json:"new_did"`
	NewPublicKey string `json:"new_public_key,omitempty"`
	Custody      string `json:"custody"`
}

RotateKeyResponse is returned by PUT /v1/agents/me/rotate.

type RotationAnnouncement 

type RotationAnnouncement struct {
	OldDID          string `json:"old_did"`
	NewDID          string `json:"new_did"`
	Timestamp       string `json:"timestamp"`
	OldKeySignature string `json:"old_key_signature"`
}

RotationAnnouncement is attached to messages after key rotation. The old key signs the transition to the new key.

type SSEEvent 

type SSEEvent struct {
	Event string
	Data  string
	ID    string
	Retry int
}

SSEEvent is a single Server-Sent Event.

type SSEStream 

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

SSEStream decodes a text/event-stream body.

It is intentionally minimal; callers can unmarshal Data as JSON based on Event.

func NewSSEStream 

func NewSSEStream(body io.ReadCloser) *SSEStream

func (*SSEStream) Close 

func (s *SSEStream) Close() error

func (*SSEStream) Next 

func (s *SSEStream) Next() (*SSEEvent, error)

Next reads the next SSE event. It returns io.EOF when the stream ends.

type SendControlSignalRequest 

type SendControlSignalRequest struct {
	Signal ControlSignal `json:"signal"`
}

type SendControlSignalResponse 

type SendControlSignalResponse struct {
	SignalID string        `json:"signal_id"`
	Signal   ControlSignal `json:"signal"`
}

type SendMessageRequest 

type SendMessageRequest struct {
	ToAgentID      string          `json:"to_agent_id,omitempty"`
	ToAlias        string          `json:"to_alias,omitempty"`
	ToDID          string          `json:"to_did,omitempty"`
	ToStableID     string          `json:"to_stable_id,omitempty"`
	ToAddress      string          `json:"to_address,omitempty"`
	ConversationID string          `json:"conversation_id,omitempty"`
	Subject        string          `json:"subject,omitempty"`
	Body           string          `json:"body"`
	Priority       MessagePriority `json:"priority,omitempty"`
	MessageID      string          `json:"message_id,omitempty"`
	Timestamp      string          `json:"timestamp,omitempty"`
	FromDID        string          `json:"from_did,omitempty"`
	Signature      string          `json:"signature,omitempty"`
	SignedPayload  string          `json:"signed_payload,omitempty"`
}

type SendMessageResponse 

type SendMessageResponse struct {
	MessageID      string `json:"message_id"`
	ConversationID string `json:"conversation_id,omitempty"`
	Status         string `json:"status"`
	DeliveredAt    string `json:"delivered_at"`
}

type SpawnAcceptInviteRequest added in v1.0.0 

type SpawnAcceptInviteRequest struct {
	Token               string `json:"token"`
	Alias               string `json:"alias,omitempty"`
	Name                string `json:"name,omitempty"`
	HumanName           string `json:"human_name,omitempty"`
	AgentType           string `json:"agent_type,omitempty"`
	DID                 string `json:"did,omitempty"`
	PublicKey           string `json:"public_key,omitempty"`
	Custody             string `json:"custody,omitempty"`
	Lifetime            string `json:"lifetime,omitempty"`
	AddressReachability string `json:"address_reachability,omitempty"`
}

type SpawnAcceptInviteResponse added in v1.22.0 

type SpawnAcceptInviteResponse struct {
	OrgID               string `json:"org_id,omitempty"`
	OrgSlug             string `json:"org_slug,omitempty"`
	TeamID              string `json:"team_id"`
	TeamSlug            string `json:"team_slug"`
	NamespaceSlug       string `json:"namespace_slug"`
	Namespace           string `json:"namespace"`
	IdentityID          string `json:"identity_id"`
	Alias               string `json:"alias,omitempty"`
	Name                string `json:"name,omitempty"`
	Address             string `json:"address,omitempty"`
	APIKey              string `json:"api_key,omitempty"`
	ServerURL           string `json:"server_url"`
	DID                 string `json:"did,omitempty"`
	StableID            string `json:"stable_id,omitempty"`
	Custody             string `json:"custody,omitempty"`
	Lifetime            string `json:"lifetime,omitempty"`
	AccessMode          string `json:"access_mode"`
	Created             bool   `json:"created"`
	AddressReachability string `json:"address_reachability,omitempty"`
	TeamCert            string `json:"team_cert,omitempty"`
}

type SpawnCreateInviteRequest added in v1.22.0 

type SpawnCreateInviteRequest struct {
	AliasHint        string `json:"alias_hint,omitempty"`
	AccessMode       string `json:"access_mode,omitempty"`
	MaxUses          int    `json:"max_uses,omitempty"`
	ExpiresInSeconds int    `json:"expires_in_seconds,omitempty"`
}

type SpawnCreateInviteResponse added in v1.22.0 

type SpawnCreateInviteResponse struct {
	InviteID      string `json:"invite_id"`
	Token         string `json:"token"`
	TokenPrefix   string `json:"token_prefix"`
	AliasHint     string `json:"alias_hint,omitempty"`
	AccessMode    string `json:"access_mode"`
	MaxUses       int    `json:"max_uses"`
	ExpiresAt     string `json:"expires_at"`
	NamespaceSlug string `json:"namespace_slug"`
	Namespace     string `json:"namespace"`
	ServerURL     string `json:"server_url"`
}

type StableIdentityOutcome added in v1.3.0 

type StableIdentityOutcome string
const (
	StableIdentityVerified  StableIdentityOutcome = "OK_VERIFIED"
	StableIdentityDegraded  StableIdentityOutcome = "OK_DEGRADED"
	StableIdentityHardError StableIdentityOutcome = "HARD_ERROR"
)

type StableIdentityVerification added in v1.3.0 

type StableIdentityVerification struct {
	Outcome       StableIdentityOutcome
	CurrentDIDKey string
	Error         string
}

type StableIdentityVerifier added in v1.3.0 

type StableIdentityVerifier interface {
	VerifyStableIdentity(ctx context.Context, address, stableID string) *StableIdentityVerification
}

type SuggestAliasPrefixResponse 

type SuggestAliasPrefixResponse struct {
	TeamID     string `json:"team_id"`
	NamePrefix string `json:"name_prefix"`
}

type TXTResolver added in v1.3.0 

type TXTResolver interface {
	LookupTXT(ctx context.Context, name string) ([]string, error)
}

type TeamCertificate added in v1.7.0 

type TeamCertificate struct {
	Version       int    `json:"version"`
	CertificateID string `json:"certificate_id"`
	Team          string `json:"team_id"`
	TeamDIDKey    string `json:"team_did_key"`
	MemberDIDKey  string `json:"member_did_key"`
	MemberDIDAW   string `json:"member_did_aw,omitempty"`
	MemberAddress string `json:"member_address,omitempty"`
	Alias         string `json:"alias"`
	Lifetime      string `json:"lifetime"`
	IssuedAt      string `json:"issued_at"`
	Signature     string `json:"signature"`
}

TeamCertificate is a team membership proof signed by the team controller. The JSON representation is used for both file storage and the X-AWID-Team-Certificate HTTP header.

func DecodeTeamCertificateHeader added in v1.7.0 

func DecodeTeamCertificateHeader(encoded string) (*TeamCertificate, error)

DecodeTeamCertificateHeader decodes a certificate from the X-AWID-Team-Certificate HTTP header.

func LoadTeamCertificate added in v1.7.0 

func LoadTeamCertificate(path string) (*TeamCertificate, error)

LoadTeamCertificate reads a certificate from disk.

func SignTeamCertificate added in v1.7.0 

func SignTeamCertificate(teamKey ed25519.PrivateKey, fields TeamCertificateFields) (*TeamCertificate, error)

SignTeamCertificate creates and signs a team membership certificate using the team's Ed25519 private key.

type TeamCertificateFields added in v1.7.0 

type TeamCertificateFields struct {
	Team          string // team identifier (e.g. "backend:acme.com")
	MemberDIDKey  string
	MemberDIDAW   string // optional; from identity.yaml, empty for ephemeral
	MemberAddress string // optional; from identity.yaml, empty for ephemeral
	Alias         string
	Lifetime      string
}

TeamCertificateFields are the inputs for signing a certificate.

type TeamMemberReference added in v1.7.0 

type TeamMemberReference struct {
	TeamID        string `json:"team_id"`
	CertificateID string `json:"certificate_id"`
	MemberDIDKey  string `json:"member_did_key"`
	MemberDIDAW   string `json:"member_did_aw,omitempty"`
	MemberAddress string `json:"member_address,omitempty"`
	Alias         string `json:"alias"`
	Lifetime      string `json:"lifetime"`
	IssuedAt      string `json:"issued_at"`
}

TeamMemberReference resolves a (team_id, alias) reference to an active member.

type VerificationStatus 

type VerificationStatus string
const (
	Verified          VerificationStatus = "verified"
	VerifiedLegacy    VerificationStatus = "verified_legacy"
	VerifiedCustodial VerificationStatus = "verified_custodial"
	Unverified        VerificationStatus = "unverified"
	Failed            VerificationStatus = "failed"
	IdentityMismatch  VerificationStatus = "identity_mismatch"
)

func SignedPayloadConversationStatus added in v1.19.0 

func SignedPayloadConversationStatus(signedPayload, conversationID string) VerificationStatus

func VerifyMessage 

func VerifyMessage(env *MessageEnvelope) (VerificationStatus, error)

VerifyMessage checks the signature on a message envelope. Returns Unverified if DID or signature is missing (legacy message). Returns Failed if the DID is malformed, the signature doesn't verify, or SigningKeyID disagrees with FromDID. Returns Verified if the signature is valid. Does not check TOFU pins or custody — callers handle those.

func VerifySignedPayload 

func VerifySignedPayload(signedPayload, signatureB64, fromDID, signingKeyID string) (VerificationStatus, error)

VerifySignedPayload verifies a signature against a pre-computed canonical payload string. Use this when the server returns signed_payload alongside the message, avoiding reconstruction from display fields.

type VerifiedLogHead added in v1.3.0 

type VerifiedLogHead struct {
	Seq           int
	EntryHash     string
	StateHash     string
	CurrentDIDKey string
	FetchedAt     time.Time
}

func VerifyDidLogEntries added in v1.4.0 

func VerifyDidLogEntries(didAW string, entries []DidKeyEvidence, now time.Time) (*VerifiedLogHead, error)

type WakeFilter 

type WakeFilter func(evt AgentEvent, autofeed bool) bool

WakeFilter decides whether an agent event should trigger a wake cycle. The autofeed parameter indicates whether automatic work dispatch is enabled.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.