mcpbroker

type AttachOutcome ¶

type AttachOutcome string

AttachOutcome is the closed result vocabulary for AttachSession.

const (
	// AttachCreated means the logical broker session was created.
	AttachCreated AttachOutcome = "created"
	// AttachReattached means a session handle was opened to existing logical state.
	AttachReattached AttachOutcome = "reattached"
)

type Attachment ¶

type Attachment interface {
	// Commit publishes a newly created logical session after its host session is
	// durable. It is idempotent. On a reattached handle it is a no-op. The
	// implementation keeps any creation token private so remote brokers can provide
	// the same transaction without exposing storage generations or CAS values.
	Commit(context.Context) error
	// Abort abandons this session handle's uncommitted creation and closes the local
	// handle. It may delete logical state only while that creation is still private;
	// once another session handle has observed the session, Abort must preserve that
	// peer and degrade to local close. It is idempotent.
	Abort(context.Context) error
	// Binding is the opaque identity of this exact logical-session incarnation.
	// It is persisted by the host and must match exactly on reattachment.
	Binding() session.ExternalBinding
	// Tools returns independently owned wrappers bound to this session handle.
	Tools() []tool.Tool
	// RefreshGrantedAuthorizationCatalogue atomically replaces static protected
	// declarations with authenticated metadata after the exact bundle grant. A
	// valid non-bundle grant returns the unchanged catalogue. The returned snapshot
	// is independently owned for the host's model-visible catalog.
	RefreshGrantedAuthorizationCatalogue(context.Context, session.ExternalAuthorization) ([]tool.Tool, error)
	// PresentAuthorization returns the live presentation URL for the exact
	// authorization. The URL is deliberately an ephemeral return value: it is not
	// part of ExternalAuthorization or any broker reference intended for storage.
	PresentAuthorization(context.Context, session.ExternalAuthorization) (string, error)
	// AuthorizationStatus queries the exact authorization and remains available
	// after closing an old session handle and reattaching to the logical session.
	AuthorizationStatus(context.Context, session.ExternalAuthorization) (session.AuthorizationStatus, error)
	// CancelAuthorization precisely cancels the exact authorization reference.
	CancelAuthorization(context.Context, session.ExternalAuthorization) (CancelOutcome, error)
	// Close releases only this local session handle and is idempotent. It never
	// deletes logical broker state.
	Close(context.Context) (CloseOutcome, error)
}

Attachment is a process-local handle to one logical broker session.

Authorization operations take session.ExternalAuthorization so callers reuse the aggregate's existing value instead of a second broker DTO. Identity is the stable authorization ID plus opaque AuthorizationBinding; ExpiresAt is freshness metadata and must not participate in lookup equality. Implementations must not infer a transaction from only the session or authorization ID.

type Availability ¶ added in v0.0.34

type Availability string

Availability is the closed vocabulary for ConnectorInventory.Availability.

const (
	// AvailabilityAvailable means the broker reached the connector inventory.
	AvailabilityAvailable Availability = "available"
	// AvailabilityUnavailable means the broker could not reach the connector inventory.
	AvailabilityUnavailable Availability = "unavailable"
)

type CancelOutcome ¶

type CancelOutcome string

CancelOutcome is the closed, idempotent result vocabulary for cancellation.

const (
	// CancelCancelled means this call cancelled the pending authorization.
	CancelCancelled CancelOutcome = "cancelled"
	// CancelAlreadyCancelled means that exact authorization was already cancelled.
	CancelAlreadyCancelled CancelOutcome = "already_cancelled"
	// CancelAlreadyResolved means that exact authorization had another terminal
	// status. AuthorizationStatus reports which one.
	CancelAlreadyResolved CancelOutcome = "already_resolved"
)

type CatalogueState ¶ added in v0.0.34

type CatalogueState string

CatalogueState is the closed vocabulary for ConnectorStatus.CatalogueState. A zero ToolCount with CatalogueStateUnknown is missing information, not proof of an empty catalogue.

const (
	// CatalogueHidden means the connector's tools are not published.
	CatalogueHidden CatalogueState = "hidden"
	// CatalogueDeclared means the connector is declared but not yet discovered.
	CatalogueDeclared CatalogueState = "declared"
	// CatalogueDiscovered means the connector's tools were discovered and published.
	CatalogueDiscovered CatalogueState = "discovered"
	// CatalogueUnknown means the catalogue state could not be determined.
	CatalogueUnknown CatalogueState = "unknown"
)

type CloseOutcome ¶

type CloseOutcome string

CloseOutcome is the closed, idempotent result vocabulary for Attachment.Close.

const (
	// CloseClosed means this call released the local session handle.
	CloseClosed CloseOutcome = "closed"
	// CloseAlreadyClosed means the session handle had already been released.
	CloseAlreadyClosed CloseOutcome = "already_closed"
)

type ConnectorInspector ¶ added in v0.0.34

type ConnectorInspector interface {
	InspectConnectors(context.Context, session.SessionID, session.ExternalBinding) (ConnectorInventory, error)
}

ConnectorInspector is optional, read-only inspection of an existing exact broker incarnation. The caller must authorize the session owner first. It never attaches, enrolls, refreshes credentials, or performs discovery.

type ConnectorInventory ¶ added in v0.0.34

type ConnectorInventory struct {
	// Availability reports whether the broker reached the inventory source.
	Availability Availability
	// EnrollmentState reports the connector's broker-owned enrollment phase.
	EnrollmentState EnrollmentState
	// Connectors contains the bounded display rows returned to the caller.
	Connectors []ConnectorStatus
	// TotalConnectors is the untruncated total discovered by the broker.
	TotalConnectors uint32
	// Truncated reports that Connectors is only a prefix of the total result.
	Truncated bool
}

ConnectorInventory describes broker-local catalogue publication, not session installation, persistence, prompt readiness, authorization validity, or health.

type ConnectorStatus ¶ added in v0.0.34

type ConnectorStatus struct {
	// Name is a display label, not a routing key or credential-bearing endpoint.
	Name string
	// CatalogueState says whether this connector's tools are published to the broker catalogue.
	CatalogueState CatalogueState
	// ToolCount is the number of published tools for this connector.
	ToolCount uint32
}

ConnectorStatus contains only a bounded display name and published tool count.

type ContinuityGuard ¶ added in v0.0.48

type ContinuityGuard struct {
	SessionID          session.SessionID
	SessionIncarnation session.IncarnationID
	OwnerPartition     OwnerPartition
	WorkloadPartition  WorkloadPartition
	ProfileDigest      ProfileDigest
	Providers          []string
}

ContinuityGuard identifies the custody record an operation applies to.

OwnerPartition and WorkloadPartition are derived by the broker's session layer from the verified caller (see ContinuityOwnerPartition and ContinuityWorkloadPartition). A custody implementation treats them as already verified and only compares them with the stored record, so every caller must derive them itself and never forward a value received from a client.

For Stage, ProfileDigest and Providers must be zero: the broker fills them from its own configuration and returns them in StagedCredentialCustody. Commit, Recover and Tombstone carry the staged values back.

type CredentialContinuityAdvertiser ¶ added in v0.0.48

type CredentialContinuityAdvertiser interface {
	CredentialContinuity() bool
}

CredentialContinuityAdvertiser reports whether a handle's broker offers credential continuity (encrypted custody is configured). A host requires custody exactly when this reports true: it fails enrollment closed rather than silently completing without custody, and keeps the legacy path otherwise, so a broker without protected storage (or an older broker) is never mistaken for a continuity failure.

type CredentialContinuityService ¶ added in v0.0.48

type CredentialContinuityService interface {
	CommitCredentialCustody(context.Context, CustodyAssertion) error
	RecoverCredentialAttachment(context.Context, CustodyAssertion, string) (RecoveredCredentialAttachment, error)
	TombstoneCredentialCustody(context.Context, CustodyAssertion) error
}

CredentialContinuityService remains usable after the session handle that staged custody has been closed. Its guards are already verified by the caller (see ContinuityGuard); implementations enforce them against the stored record.

type CredentialCustodyStager ¶ added in v0.0.48

type CredentialCustodyStager interface {
	StageCredentialCustody(context.Context, string, ContinuityGuard, WorkspaceEnrollmentRef, time.Time) (StagedCredentialCustody, error)
}

CredentialCustodyStager is available only on handles that completed protected enrollment and can derive a verified ToolHive session identity.

type CustodyAssertion ¶ added in v0.0.48

type CustodyAssertion struct {
	Guard             ContinuityGuard
	RecoveryReference string
	AttemptDeadline   time.Time
}

CustodyAssertion is bounded request data, never durable authority.

type DeleteOutcome ¶

type DeleteOutcome string

DeleteOutcome is the closed, idempotent result vocabulary for DeleteSession.

const (
	// DeleteDeleted means logical broker state existed and was deleted.
	DeleteDeleted DeleteOutcome = "deleted"
	// DeleteNotFound means no logical broker state existed; the requested end
	// state is already satisfied.
	DeleteNotFound DeleteOutcome = "not_found"
)

type EnrollmentState ¶ added in v0.0.34

type EnrollmentState string

EnrollmentState is the closed vocabulary for ConnectorInventory.EnrollmentState.

const (
	// EnrollmentNotRequired means the connector needs no enrollment step.
	EnrollmentNotRequired EnrollmentState = "not_required"
	// EnrollmentNotStarted means enrollment is required but has not begun.
	EnrollmentNotStarted EnrollmentState = "not_started"
	// EnrollmentPending means enrollment has started but not completed.
	EnrollmentPending EnrollmentState = "pending"
	// EnrollmentCompleted means enrollment has finished successfully.
	EnrollmentCompleted EnrollmentState = "completed"
	// EnrollmentUnknown means enrollment status could not be determined.
	EnrollmentUnknown EnrollmentState = "unknown"
)

type ExpectedBindingAttacher ¶ added in v0.0.48

type ExpectedBindingAttacher interface {
	AttachSessionExpectedBinding(context.Context, session.SessionID, session.ExternalBinding) (Attachment, AttachOutcome, error)
}

ExpectedBindingAttacher classifies a persisted opaque binding without creating a new logical session. It is the only binding-aware reattach capability.

type OwnerPartition ¶ added in v0.0.48

type OwnerPartition [32]byte

OwnerPartition is the one-way fingerprint of the durable owner principal.

func ContinuityOwnerPartition(principal *session.Principal) (OwnerPartition, error)

func (p OwnerPartition) Equal(other OwnerPartition) bool

func (p OwnerPartition) IsZero() bool

type ProfileDigest ¶ added in v0.0.48

type ProfileDigest [32]byte

ProfileDigest is the digest of the protected provider configuration.

func ProtectedProfileDigest(callbackURL, derivedIssuer string, profiles []ProtectedProfile) (ProfileDigest, []string, error)

func (d ProfileDigest) Equal(other ProfileDigest) bool

func (d ProfileDigest) IsZero() bool

type ProtectedProfile ¶ added in v0.0.48

type ProtectedProfile struct {
	Provider              string
	Destination           string
	Issuer                string
	AuthorizationEndpoint string
	TokenEndpoint         string
	DCRDiscoveryURL       string
	ClientID              string
	AuthMode              string
	Scopes                []string
	RequestRefreshToken   bool
}

ProtectedProfile describes immutable, non-secret configuration that binds a protected ToolHive provider to continuity custody. Secret values and paths are deliberately absent.

type RecoveredCredentialAttachment ¶ added in v0.0.48

type RecoveredCredentialAttachment struct {
	Attachment Attachment
}

RecoveredCredentialAttachment contains only a process-local provisional attachment. Hosts persist its binding, never its handle.

type Service ¶

type Service interface {
	// AttachSession opens a local session handle to the current incarnation,
	// creating logical state when necessary.
	AttachSession(context.Context, session.SessionID) (Attachment, AttachOutcome, error)
	// DeleteSession durably invalidates every session handle to the deleted logical
	// session incarnation. A later AttachSession with the same SessionID creates a
	// new incarnation; stale session handles must return ErrStateUnavailable. Any
	// generation or fencing mechanism used to enforce this remains private.
	DeleteSession(context.Context, session.SessionID) (DeleteOutcome, error)
}

Service attaches consumers to broker state keyed by the stable mecatl session identity. AttachSession does not transfer ownership: multiple process-local session handles may refer to the same logical state. DeleteSession, unlike Close, durably and idempotently destroys that logical state.

type StagedCredentialCustody ¶ added in v0.0.48

type StagedCredentialCustody struct {
	RecoveryReference string
	ExpiresAt         time.Time
	ProfileDigest     ProfileDigest
	Providers         []string
}

StagedCredentialCustody is the safe durable result of Stage.

type WorkloadPartition ¶ added in v0.0.48

type WorkloadPartition [32]byte

WorkloadPartition is the one-way fingerprint of the authenticated workload principal.

func ContinuityWorkloadPartition(principal *session.Principal) (WorkloadPartition, error)

func (p WorkloadPartition) Equal(other WorkloadPartition) bool

func (p WorkloadPartition) IsZero() bool

type WorkspaceCatalogue ¶

type WorkspaceCatalogue interface {
	Valid() bool
	Ref() WorkspaceEnrollmentRef
	Tools() []tool.Tool
	ToolNames() []string
	// contains filtered or unexported methods
}

WorkspaceCatalogue is an immutable snapshot of the complete frozen tool catalogue proven by one exact enrollment. Construct it with NewWorkspaceCatalogue; its accessors return defensive copies. The private marker seals construction to this package.

func NewWorkspaceCatalogue(ref WorkspaceEnrollmentRef, tools []tool.Tool) (WorkspaceCatalogue, error)

type WorkspaceEnrollmentAttachment ¶

type WorkspaceEnrollmentAttachment interface {
	ResetWorkspaceEnrollment(context.Context) error
	// BeginWorkspaceEnrollment creates a broker-owned enrollment and returns a
	// short-lived browser presentation for it.
	BeginWorkspaceEnrollment(context.Context) (WorkspaceEnrollmentPresentation, error)
	// ObserveWorkspaceEnrollment returns the broker's current result for this exact ref.
	ObserveWorkspaceEnrollment(context.Context, WorkspaceEnrollmentRef) (WorkspaceEnrollmentResult, error)
	// CancelWorkspaceEnrollment settles this exact enrollment as cancelled when possible.
	CancelWorkspaceEnrollment(context.Context, WorkspaceEnrollmentRef) (WorkspaceEnrollmentResult, error)
}

WorkspaceEnrollmentAttachment is the optional enrollment capability of an Attachment. Callers may begin, observe, cancel, or explicitly reset broker- owned state, but can never submit status, discovered definitions, authority, or success.

type WorkspaceEnrollmentPresentation ¶

type WorkspaceEnrollmentPresentation struct {
	// Ref is the exact enrollment transaction the browser flow must complete.
	Ref WorkspaceEnrollmentRef
	// URL is a short-lived presentation address; callers must not persist it as authority.
	URL string
}

WorkspaceEnrollmentPresentation is the ephemeral browser presentation for an enrollment. URL deliberately exists only on this non-durable value.

func (p WorkspaceEnrollmentPresentation) Valid() bool

type WorkspaceEnrollmentRef ¶

type WorkspaceEnrollmentRef struct {
	// ID identifies the enrollment transaction without exposing its process-local state.
	ID session.WorkspaceEnrollmentID
	// RequiredServices records how many broker services must be connected before the
	// enrollment may publish a complete catalogue.
	RequiredServices uint32
	// ExpiresAt is the broker's absolute expiry for this enrollment reference.
	ExpiresAt time.Time
}

WorkspaceEnrollmentRef is the durable, presentation-safe correlation for one broker-owned enrollment. It contains no URL, credential, backend selection, or discovered definition.

func (r WorkspaceEnrollmentRef) Valid() bool

type WorkspaceEnrollmentResult ¶

type WorkspaceEnrollmentResult struct {
	Ref       WorkspaceEnrollmentRef
	Status    WorkspaceEnrollmentStatus
	Catalogue WorkspaceCatalogue
}

WorkspaceEnrollmentResult is a broker-authored observation. A connected result proves one complete frozen catalogue; every other state forbids one.

func (r WorkspaceEnrollmentResult) Valid() bool

type WorkspaceEnrollmentStatus ¶

type WorkspaceEnrollmentStatus string

WorkspaceEnrollmentStatus is the closed broker-authored state of one pre-prompt workspace enrollment.

const (
	WorkspaceEnrollmentPending   WorkspaceEnrollmentStatus = "pending"
	WorkspaceEnrollmentConnected WorkspaceEnrollmentStatus = "connected"
	WorkspaceEnrollmentDenied    WorkspaceEnrollmentStatus = "denied"
	WorkspaceEnrollmentCancelled WorkspaceEnrollmentStatus = "cancelled"
	WorkspaceEnrollmentExpired   WorkspaceEnrollmentStatus = "expired"
	WorkspaceEnrollmentFailed    WorkspaceEnrollmentStatus = "failed"
)

func (s WorkspaceEnrollmentStatus) Valid() bool