souls

package
v1.5.2 Latest Latest
Warning

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

Go to latest
Published: Jun 14, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package souls discovers principal-owned lesser souls and manages local incorporation bindings.

Index

Constants

View Source
const (

	// SoulAuthorityModelWalletPrincipal is Host's wallet/principal authority model.
	SoulAuthorityModelWalletPrincipal = "wallet_principal"
	// SoulAuthorityModelInstanceTrust is Host's managed instance-key authority model.
	SoulAuthorityModelInstanceTrust = "instance_trust"
	// SoulAnchorStateHostedOffchain is Host's hosted/off-chain anchor state.
	SoulAnchorStateHostedOffchain = "hosted_offchain"
	// SoulAnchorStateImmutableOnchain is Host's on-chain anchor state.
	SoulAnchorStateImmutableOnchain = "immutable_onchain"
	// SoulOperationalBindingHostedBound is Host's hosted-bound operational binding marker.
	SoulOperationalBindingHostedBound = "hosted_bound_soul"
)

Variables

View Source
var (
	// ErrHostTrustNotConfigured indicates the effective instance trust base URL is unavailable.
	ErrHostTrustNotConfigured = errors.New("host trust not configured")
	// ErrHostInstanceKeyMissing indicates no server-side Host instance key can be resolved.
	ErrHostInstanceKeyMissing = errors.New("host instance key missing")
	// ErrHostInstanceKeyUnavailable indicates the configured Host instance key secret could not be resolved.
	ErrHostInstanceKeyUnavailable = errors.New("host instance key unavailable")
	// ErrHostUnavailable indicates the Host instance-key API is unreachable or returned an unusable response.
	ErrHostUnavailable = errors.New("host unavailable")
	// ErrHostSigningPayloadUnsupported indicates Host returned signing metadata Lesser does not support.
	ErrHostSigningPayloadUnsupported = errors.New("host signing payload unsupported")
)
View Source
var (
	// ErrTrustNotConfigured indicates the instance trust base URL is unavailable.
	ErrTrustNotConfigured = errors.New("trust not configured")
	// ErrSoulNotAvailable indicates a soul is not available to the current authenticated principal.
	ErrSoulNotAvailable = errors.New("soul not available")
	// ErrSoulAlreadyBound indicates the target soul is already incorporated elsewhere.
	ErrSoulAlreadyBound = errors.New("soul already bound")
	// ErrTargetAgentRequired indicates the incorporation target agent identifier was omitted.
	ErrTargetAgentRequired = errors.New("target agent is required")
	// ErrTargetAgentNotFound indicates the requested local target agent does not exist.
	ErrTargetAgentNotFound = errors.New("target agent not found")
	// ErrTargetAgentMustBeAgent indicates the requested local target exists but is not an agent account.
	ErrTargetAgentMustBeAgent = errors.New("target account must be an agent")
	// ErrTargetAgentNotOwned indicates the requested local target agent is not owned by the authenticated principal.
	ErrTargetAgentNotOwned = errors.New("target agent not owned by authenticated principal")
	// ErrTargetAgentAlreadyHasSoul indicates the target local agent is already bound to another soul.
	ErrTargetAgentAlreadyHasSoul = errors.New("target agent already has soul")
)

Functions

This section is empty.

Types

type BootstrapBeginInput added in v1.5.0

type BootstrapBeginInput struct {
	// Username is the Lesser-local body handle Host receives as local_id.
	Username      string
	BodyID        string // Lesser-local state/UI identity; never serialized as Host local_id.
	WalletAddress string
	Capabilities  []string
}

BootstrapBeginInput is the Lesser-local request for Host registration begin.

type BootstrapBeginResult added in v1.5.0

type BootstrapBeginResult struct {
	RegistrationID     string
	HostSoulAgentID    string
	WalletAddress      string
	AuthorityModel     string
	AnchorState        string
	RegistrationStatus string
	WalletChallenge    BootstrapWalletChallenge
	HostRequestID      string
}

BootstrapBeginResult contains Host begin output needed by the GraphQL state.

type BootstrapConversationCompleteInput added in v1.5.0

type BootstrapConversationCompleteInput struct {
	RegistrationID string
	ConversationID string
}

BootstrapConversationCompleteInput is the Lesser-local request for completing a Host mint conversation.

type BootstrapConversationCompleteResult added in v1.5.0

type BootstrapConversationCompleteResult struct {
	RegistrationID       string
	HostSoulAgentID      string
	ConversationID       string
	Status               string
	ProducedDeclarations string
	CompletedAt          *time.Time
	HostRequestID        string
}

BootstrapConversationCompleteResult contains Host completion state.

type BootstrapConversationMessageInput added in v1.5.0

type BootstrapConversationMessageInput struct {
	RegistrationID string
	ConversationID string
	Message        string
	Model          string
}

BootstrapConversationMessageInput is the Lesser-local request for sending a Host mint-conversation turn through the server-side instance-key route.

type BootstrapConversationMessageResult added in v1.5.0

type BootstrapConversationMessageResult struct {
	RegistrationID string
	ConversationID string
	Model          string
	FullResponse   string
	HostRequestID  string
}

BootstrapConversationMessageResult contains the Host conversation ids and terminal assistant response metadata collected from the SSE stream.

type BootstrapFinalizeInput added in v1.5.0

type BootstrapFinalizeInput struct {
	RegistrationID     string
	ConversationID     string
	BoundarySignatures map[string]string
	IssuedAt           time.Time
	ExpectedVersion    int
	SelfAttestation    string
}

BootstrapFinalizeInput is the Lesser-local request for Host hosted/off-chain finalize and publication.

type BootstrapFinalizePreflightInput added in v1.5.0

type BootstrapFinalizePreflightInput struct {
	RegistrationID     string
	ConversationID     string
	BoundarySignatures map[string]string
}

BootstrapFinalizePreflightInput is the Lesser-local request for Host finalize preflight/signing material.

type BootstrapFinalizePreflightResult added in v1.5.0

type BootstrapFinalizePreflightResult struct {
	Version                     string
	DigestHex                   string
	IssuedAt                    *time.Time
	ExpectedVersion             int
	NextVersion                 int
	SelfAttestationSigning      BootstrapFinalizeSigningInput
	BoundaryRequirementsJSON    string
	FinalizeRequestTemplateJSON string
	RegistrationPreviewJSON     string
	HostRequestID               string
}

BootstrapFinalizePreflightResult contains Host-owned finalize signing material. Lesser relays these fields unchanged; it never reconstructs the signing payload locally.

type BootstrapFinalizeResult added in v1.5.0

type BootstrapFinalizeResult struct {
	Version                 string
	HostSoulAgentID         string
	PublishedVersion        int
	AgentDomain             string
	AgentLocalID            string
	AgentAuthorityModel     string
	AgentAnchorState        string
	AgentOperationalBinding string
	AgentStatus             string
	AgentLifecycleStatus    string
	PrincipalAddress        string
	Publication             BootstrapPublicationEvidence
	Promotion               BootstrapPromotionEvidence
	HostRequestID           string
}

BootstrapFinalizeResult contains Host finalize/publication output needed for Lesser local soul binding and workflow projection.

type BootstrapFinalizeSigningInput added in v1.5.0

type BootstrapFinalizeSigningInput struct {
	SignerWallet    string
	SigningMethod   string
	MessageEncoding string
	MessageHex      string
	DigestHex       string
	CanonicalJSON   string
}

BootstrapFinalizeSigningInput contains the Host-owned self-attestation signing payload.

type BootstrapPrincipalPreflightInput added in v1.5.0

type BootstrapPrincipalPreflightInput struct {
	RegistrationID       string
	PrincipalAddress     string
	PrincipalDeclaration string
	DeclaredAt           time.Time
}

BootstrapPrincipalPreflightInput is the Lesser-local request for Host principal declaration preflight.

type BootstrapPrincipalPreflightResult added in v1.5.0

type BootstrapPrincipalPreflightResult struct {
	Version          string
	PrincipalAddress string
	SignerAddress    string
	SigningMethod    string
	MessageEncoding  string
	MessageHex       string
	DigestHex        string
	CanonicalJSON    string
	DeclaredAt       *time.Time
	HostRequestID    string
}

BootstrapPrincipalPreflightResult contains Host-owned signing material.

type BootstrapPrincipalVerifyInput added in v1.5.0

type BootstrapPrincipalVerifyInput struct {
	RegistrationID       string
	WalletSignature      string
	PrincipalAddress     string
	PrincipalDeclaration string
	PrincipalSignature   string
	DeclaredAt           time.Time
}

BootstrapPrincipalVerifyInput is the Lesser-local request for Host proof verification.

type BootstrapPrincipalVerifyResult added in v1.5.0

type BootstrapPrincipalVerifyResult struct {
	RegistrationID   string
	HostSoulAgentID  string
	WalletAddress    string
	PrincipalAddress string
	OperationID      string
	PromotionStage   string
	HostRequestID    string
}

BootstrapPrincipalVerifyResult contains Host verification output needed by the GraphQL state.

type BootstrapPromotionEvidence added in v1.5.0

type BootstrapPromotionEvidence struct {
	AgentID                  string
	RegistrationID           string
	Stage                    string
	RequestStatus            string
	ReviewStatus             string
	ReadinessStatus          string
	AuthorityModel           string
	AnchorState              string
	LatestConversationID     string
	LatestConversationStatus string
	PublishedVersion         int
	GraduatedAt              *time.Time
}

BootstrapPromotionEvidence contains Host promotion continuity fields.

type BootstrapPublicationEvidence added in v1.5.0

type BootstrapPublicationEvidence struct {
	AgentID                    string
	PublishedVersion           int
	AuthorityModel             string
	RegistrationURI            string
	RegistrationS3Key          string
	VersionedRegistrationURI   string
	VersionedRegistrationS3Key string
	AnchorState                string
	PublishedAt                *time.Time
}

BootstrapPublicationEvidence contains Host publication evidence for the versioned hosted/off-chain registration artifact.

type BootstrapWalletChallenge added in v1.5.0

type BootstrapWalletChallenge struct {
	ID        string
	Address   string
	ChainID   int
	Nonce     string
	Message   string
	IssuedAt  *time.Time
	ExpiresAt *time.Time
}

BootstrapWalletChallenge contains the Host-issued wallet signing message.

type HostBootstrapError added in v1.5.0

type HostBootstrapError struct {
	Code          string
	Message       string
	Source        string
	StatusCode    int
	HostRequestID string
	DetailsJSON   string
	Err           error
}

HostBootstrapError describes a bounded, client-safe failure returned while talking to Host's instance-key bootstrap API.

func (*HostBootstrapError) Error added in v1.5.0

func (e *HostBootstrapError) Error() string

func (*HostBootstrapError) Unwrap added in v1.5.0

func (e *HostBootstrapError) Unwrap() error

type HostedBootstrapPublishInput added in v1.5.2

type HostedBootstrapPublishInput struct {
	RegistrationID string
	ConversationID string
	LocalID        string
}

HostedBootstrapPublishInput is the hosted-first no-wallet publish request.

type Service

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

Service resolves principal-bound souls for a Lesser instance and manages explicit incorporation bindings.

func NewService

func NewService(accountRepo accountRepository, instanceRepo instanceRepository, cfg *config.Config, logger *zap.Logger) *Service

NewService creates a new soul service.

func (*Service) BeginBootstrapRegistration added in v1.5.0

func (s *Service) BeginBootstrapRegistration(ctx context.Context, input BootstrapBeginInput) (*BootstrapBeginResult, error)

BeginBootstrapRegistration calls Host's instance-key registration begin route.

func (*Service) BeginHostedBootstrapRegistration added in v1.5.2

func (s *Service) BeginHostedBootstrapRegistration(ctx context.Context, input BootstrapBeginInput) (*BootstrapBeginResult, error)

BeginHostedBootstrapRegistration calls Host's M7.1 instance-trust begin route.

func (*Service) BindHostedBootstrap added in v1.5.2

func (s *Service) BindHostedBootstrap(ctx context.Context, targetAgentUsername string, result *BootstrapFinalizeResult) (*Soul, error)

BindHostedBootstrap binds a Host-published instance-trust soul to a local body after validating the hosted authority, anchor, domain, and local id returned by Host.

func (*Service) CompleteBootstrapConversation added in v1.5.0

CompleteBootstrapConversation completes a Host mint conversation and returns the Host-owned declaration output checkpoint.

func (*Service) FinalizeBootstrap added in v1.5.0

func (s *Service) FinalizeBootstrap(ctx context.Context, input BootstrapFinalizeInput) (*BootstrapFinalizeResult, error)

FinalizeBootstrap relays Host finalize and publication. Hosted/off-chain success does not require on-chain mint transaction fields.

func (*Service) Incorporate

func (s *Service) Incorporate(ctx context.Context, principalUsername string, targetAgentUsername string, agentID string) (*Soul, error)

Incorporate explicitly binds a soul to a local agent chosen by the authenticated principal.

func (*Service) ListMine

func (s *Service) ListMine(ctx context.Context, username string) ([]Soul, error)

ListMine returns the current user's discoverable souls for this instance.

func (*Service) PrepareBootstrapFinalize added in v1.5.0

PrepareBootstrapFinalize calls Host finalize preflight and fails closed on unsupported signing metadata.

func (*Service) PrepareBootstrapPrincipalDeclaration added in v1.5.0

func (s *Service) PrepareBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalPreflightInput) (*BootstrapPrincipalPreflightResult, error)

PrepareBootstrapPrincipalDeclaration calls Host's principal declaration preflight route and fails closed on unsupported signing metadata.

func (*Service) PublishHostedBootstrap added in v1.5.2

func (s *Service) PublishHostedBootstrap(ctx context.Context, input HostedBootstrapPublishInput) (*BootstrapFinalizeResult, error)

PublishHostedBootstrap relays the hosted-first no-wallet finalize request.

func (*Service) ResolveBoundAgent added in v1.1.41

func (s *Service) ResolveBoundAgent(ctx context.Context, agentUsername string) (*Soul, error)

ResolveBoundAgent returns the canonical bound soul identity for a local agent username. It returns (nil, nil) when the agent is not soul-bound.

func (*Service) SendBootstrapConversationMessage added in v1.5.0

func (s *Service) SendBootstrapConversationMessage(ctx context.Context, input BootstrapConversationMessageInput) (*BootstrapConversationMessageResult, error)

SendBootstrapConversationMessage relays one mint-conversation turn to Host's instance-key SSE route and consumes the terminal event so GraphQL receives a bounded same-origin mutation result.

func (*Service) VerifyBootstrapPrincipalDeclaration added in v1.5.0

func (s *Service) VerifyBootstrapPrincipalDeclaration(ctx context.Context, input BootstrapPrincipalVerifyInput) (*BootstrapPrincipalVerifyResult, error)

VerifyBootstrapPrincipalDeclaration calls Host's combined wallet/proof/ principal declaration verification route.

func (*Service) WithHTTPClient

func (s *Service) WithHTTPClient(client *http.Client) *Service

WithHTTPClient overrides the HTTP client used for lesser-host requests.

func (*Service) WithHostInstanceKeyResolver added in v1.5.0

func (s *Service) WithHostInstanceKeyResolver(resolver func(context.Context, *config.Config, string) (string, error)) *Service

WithHostInstanceKeyResolver overrides instance-key resolution for tests.

type Soul

type Soul struct {
	AgentID                string
	Domain                 string
	LocalID                string
	ENSName                *string
	Wallet                 string
	TokenID                string
	MetaURI                string
	Avatar                 *SoulAvatar
	PrincipalAddress       string
	PrincipalSignature     string
	PrincipalDeclaration   string
	PrincipalDeclaredAt    string
	Status                 string
	LifecycleStatus        string
	LifecycleReason        string
	SuccessorAgentID       string
	PredecessorAgentID     string
	SelfDescriptionVersion *int
	Capabilities           []string
	MintTxHash             string
	MintedAt               *time.Time
	UpdatedAt              *time.Time
	Bound                  bool
	BoundAgentUsername     string
	BoundPrincipalAddress  string
	BoundAt                time.Time
	BoundUpdatedAt         time.Time
}

Soul represents a host-discovered soul plus local binding state.

type SoulAvatar added in v1.2.14

type SoulAvatar struct {
	TokenURI               string
	Image                  string
	CurrentStyleID         *int
	CurrentStyleName       string
	CurrentRendererAddress string
	Styles                 []SoulAvatarStyle
}

SoulAvatar represents the current soul avatar plus all configured style variants.

type SoulAvatarStyle added in v1.2.14

type SoulAvatarStyle struct {
	StyleID         int
	StyleName       string
	RendererAddress string
	Image           string
	Selected        bool
}

SoulAvatarStyle represents one renderer-backed avatar style option.

Jump to

Keyboard shortcuts

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