api

package
v0.1.0-alpha.2 Latest Latest
Warning

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

Go to latest
Published: Jun 29, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source
const (
	FactExpiration    = "expiration"
	FactNode          = "node"
	FactClientPeerID  = "client_peer_id"
	FactGroup         = "group"
	FactRole          = "role"
	FactUser          = "user"
	FactEmail         = "email"
	FactAllowService  = "allow_service"
	FactNetworkTarget = "allow_network_target"
)

Biscuit fact names

View Source
const (
	ServiceTypeStringMCP       = "mcp"
	ServiceTypeStringInference = "inference"
)

Protocol Type strings for REST and JSON mapping.

View Source
const AuthProtocolID protocol.ID = "/sam/auth/1.0.0"
View Source
const CatalogTarget = "/sam/catalog"

CatalogTarget is the special target service name used to retrieve tool catalogs from remote nodes.

View Source
const DefaultAudience = "sam-mesh-audience"
View Source
const DefaultServiceType = "system"

DefaultServiceType is the default type for services without a namespace.

View Source
const EnrollProtocolID protocol.ID = "/sam/enroll/1.0.0"
View Source
const GossipEvents = "/sam/mesh/events/v1"
View Source
const GossipHubSync = "/sam/hub/sync/v1"
View Source
const InferenceServicePrefix = "inference:"

InferenceServicePrefix is the conventional prefix used for LLM gateway inference services.

View Source
const MCPProtocolID protocol.ID = "/sam/mcp/1.0.0"
View Source
const MCPServicePrefix = "mcp:"

MCPServicePrefix is the conventional prefix (namespace + separator) used for Model Context Protocol (MCP) services. When an MCP client attempts to connect to an MCP service on a remote peer, and the target service name does not contain a namespace separator (':'), this prefix is automatically prepended to the service name prior to routing and policy evaluation.

Variables

View Source
var (
	ServiceType_name = map[int32]string{
		0: "SERVICE_TYPE_UNSPECIFIED",
		1: "SERVICE_TYPE_MCP",
		2: "SERVICE_TYPE_INFERENCE",
	}
	ServiceType_value = map[string]int32{
		"SERVICE_TYPE_UNSPECIFIED": 0,
		"SERVICE_TYPE_MCP":         1,
		"SERVICE_TYPE_INFERENCE":   2,
	}
)

Enum value maps for ServiceType.

View Source
var (
	MeshEvent_Type_name = map[int32]string{
		0: "BANNED",
		1: "KEY_ROTATION",
	}
	MeshEvent_Type_value = map[string]int32{
		"BANNED":       0,
		"KEY_ROTATION": 1,
	}
)

Enum value maps for MeshEvent_Type.

View Source
var File_api_sam_proto protoreflect.FileDescriptor

Functions

func OIDCClaimToFact

func OIDCClaimToFact() map[string]string

OIDCClaimToFact returns a copy of the OIDC claims to Biscuit facts map. This ensures that the global map is immutable and thread-safe for concurrent readers.

func ParseServiceTarget

func ParseServiceTarget(target string) (svcType, svcName string)

ParseServiceTarget parses a service target string into its type and name components. The target convention is "type:name" (e.g., "mcp:my_tool"). If no colon is present, the type defaults to the "system" namespace. The global wildcard "*" is a special case that maps to type "*" and name "*".

func ServiceTypeToString

func ServiceTypeToString(t ServiceType) (string, error)

ServiceTypeToString converts a ServiceType protobuf enum back to its standard string identifier.

Types

type Attenuation

type Attenuation struct {
	Policies []string `yaml:"policies"`
	Checks   []string `yaml:"checks"`
	Rules    []string `yaml:"rules"`
}

type AuthFrame

type AuthFrame struct {
	Biscuit       []byte `protobuf:"bytes,1,opt,name=biscuit,proto3" json:"biscuit,omitempty"`
	TargetService string `protobuf:"bytes,2,opt,name=target_service,json=targetService,proto3" json:"target_service,omitempty"` // Optional: specific service requested
	// contains filtered or unexported fields
}

func (*AuthFrame) Descriptor deprecated

func (*AuthFrame) Descriptor() ([]byte, []int)

Deprecated: Use AuthFrame.ProtoReflect.Descriptor instead.

func (*AuthFrame) GetBiscuit

func (x *AuthFrame) GetBiscuit() []byte

func (*AuthFrame) GetTargetService

func (x *AuthFrame) GetTargetService() string

func (*AuthFrame) ProtoMessage

func (*AuthFrame) ProtoMessage()

func (*AuthFrame) ProtoReflect

func (x *AuthFrame) ProtoReflect() protoreflect.Message

func (*AuthFrame) Reset

func (x *AuthFrame) Reset()

func (*AuthFrame) String

func (x *AuthFrame) String() string

type AuthResponse

type AuthResponse struct {
	Success bool   `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	Error   string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"` // populated only if success is false
	// contains filtered or unexported fields
}

func (*AuthResponse) Descriptor deprecated

func (*AuthResponse) Descriptor() ([]byte, []int)

Deprecated: Use AuthResponse.ProtoReflect.Descriptor instead.

func (*AuthResponse) GetError

func (x *AuthResponse) GetError() string

func (*AuthResponse) GetSuccess

func (x *AuthResponse) GetSuccess() bool

func (*AuthResponse) ProtoMessage

func (*AuthResponse) ProtoMessage()

func (*AuthResponse) ProtoReflect

func (x *AuthResponse) ProtoReflect() protoreflect.Message

func (*AuthResponse) Reset

func (x *AuthResponse) Reset()

func (*AuthResponse) String

func (x *AuthResponse) String() string

type Binding

type Binding struct {
	Group string `yaml:"group,omitempty"`
	User  string `yaml:"user,omitempty"`
	Email string `yaml:"email,omitempty"`
	Role  string `yaml:"role"`
}

type CommandBackend

type CommandBackend struct {
	Command []string          `protobuf:"bytes,1,rep,name=command,proto3" json:"command,omitempty"`
	Env     map[string]string `` /* 133-byte string literal not displayed */
	// contains filtered or unexported fields
}

func (*CommandBackend) Descriptor deprecated

func (*CommandBackend) Descriptor() ([]byte, []int)

Deprecated: Use CommandBackend.ProtoReflect.Descriptor instead.

func (*CommandBackend) GetCommand

func (x *CommandBackend) GetCommand() []string

func (*CommandBackend) GetEnv

func (x *CommandBackend) GetEnv() map[string]string

func (*CommandBackend) ProtoMessage

func (*CommandBackend) ProtoMessage()

func (*CommandBackend) ProtoReflect

func (x *CommandBackend) ProtoReflect() protoreflect.Message

func (*CommandBackend) Reset

func (x *CommandBackend) Reset()

func (*CommandBackend) String

func (x *CommandBackend) String() string

type DiscoveredProvider

type DiscoveredProvider struct {
	PeerId         string `protobuf:"bytes,1,opt,name=peer_id,json=peerId,proto3" json:"peer_id,omitempty"`
	LocalProxyUrl  string `protobuf:"bytes,2,opt,name=local_proxy_url,json=localProxyUrl,proto3" json:"local_proxy_url,omitempty"`
	SrvName        string `protobuf:"bytes,3,opt,name=srv_name,json=srvName,proto3" json:"srv_name,omitempty"`
	SrvDescription string `protobuf:"bytes,4,opt,name=srv_description,json=srvDescription,proto3" json:"srv_description,omitempty"`
	// contains filtered or unexported fields
}

func (*DiscoveredProvider) Descriptor deprecated

func (*DiscoveredProvider) Descriptor() ([]byte, []int)

Deprecated: Use DiscoveredProvider.ProtoReflect.Descriptor instead.

func (*DiscoveredProvider) GetLocalProxyUrl

func (x *DiscoveredProvider) GetLocalProxyUrl() string

func (*DiscoveredProvider) GetPeerId

func (x *DiscoveredProvider) GetPeerId() string

func (*DiscoveredProvider) GetSrvDescription

func (x *DiscoveredProvider) GetSrvDescription() string

func (*DiscoveredProvider) GetSrvName

func (x *DiscoveredProvider) GetSrvName() string

func (*DiscoveredProvider) ProtoMessage

func (*DiscoveredProvider) ProtoMessage()

func (*DiscoveredProvider) ProtoReflect

func (x *DiscoveredProvider) ProtoReflect() protoreflect.Message

func (*DiscoveredProvider) Reset

func (x *DiscoveredProvider) Reset()

func (*DiscoveredProvider) String

func (x *DiscoveredProvider) String() string

type EnrollRequest

type EnrollRequest struct {
	Jwt    string `protobuf:"bytes,1,opt,name=jwt,proto3" json:"jwt,omitempty"`
	PeerId string `protobuf:"bytes,2,opt,name=peer_id,json=peerId,proto3" json:"peer_id,omitempty"`
	// contains filtered or unexported fields
}

func (*EnrollRequest) Descriptor deprecated

func (*EnrollRequest) Descriptor() ([]byte, []int)

Deprecated: Use EnrollRequest.ProtoReflect.Descriptor instead.

func (*EnrollRequest) GetJwt

func (x *EnrollRequest) GetJwt() string

func (*EnrollRequest) GetPeerId

func (x *EnrollRequest) GetPeerId() string

func (*EnrollRequest) ProtoMessage

func (*EnrollRequest) ProtoMessage()

func (*EnrollRequest) ProtoReflect

func (x *EnrollRequest) ProtoReflect() protoreflect.Message

func (*EnrollRequest) Reset

func (x *EnrollRequest) Reset()

func (*EnrollRequest) String

func (x *EnrollRequest) String() string

type EnrollResponse

type EnrollResponse struct {
	BiscuitToken []byte   `protobuf:"bytes,1,opt,name=biscuit_token,json=biscuitToken,proto3" json:"biscuit_token,omitempty"`
	ErrorMessage string   `protobuf:"bytes,2,opt,name=error_message,json=errorMessage,proto3" json:"error_message,omitempty"`
	HubPublicKey []byte   `protobuf:"bytes,3,opt,name=hub_public_key,json=hubPublicKey,proto3" json:"hub_public_key,omitempty"`
	HubAddresses []string `protobuf:"bytes,4,rep,name=hub_addresses,json=hubAddresses,proto3" json:"hub_addresses,omitempty"`
	Expiration   int64    `protobuf:"varint,5,opt,name=expiration,proto3" json:"expiration,omitempty"`
	// contains filtered or unexported fields
}

func (*EnrollResponse) Descriptor deprecated

func (*EnrollResponse) Descriptor() ([]byte, []int)

Deprecated: Use EnrollResponse.ProtoReflect.Descriptor instead.

func (*EnrollResponse) GetBiscuitToken

func (x *EnrollResponse) GetBiscuitToken() []byte

func (*EnrollResponse) GetErrorMessage

func (x *EnrollResponse) GetErrorMessage() string

func (*EnrollResponse) GetExpiration

func (x *EnrollResponse) GetExpiration() int64

func (*EnrollResponse) GetHubAddresses

func (x *EnrollResponse) GetHubAddresses() []string

func (*EnrollResponse) GetHubPublicKey

func (x *EnrollResponse) GetHubPublicKey() []byte

func (*EnrollResponse) ProtoMessage

func (*EnrollResponse) ProtoMessage()

func (*EnrollResponse) ProtoReflect

func (x *EnrollResponse) ProtoReflect() protoreflect.Message

func (*EnrollResponse) Reset

func (x *EnrollResponse) Reset()

func (*EnrollResponse) String

func (x *EnrollResponse) String() string

type HubInfoResponse

type HubInfoResponse struct {
	OidcIssuer   string   `protobuf:"bytes,1,opt,name=oidc_issuer,json=oidcIssuer,proto3" json:"oidc_issuer,omitempty"`
	ClientId     string   `protobuf:"bytes,2,opt,name=client_id,json=clientId,proto3" json:"client_id,omitempty"`
	Audience     string   `protobuf:"bytes,3,opt,name=audience,proto3" json:"audience,omitempty"`
	HubAddresses []string `protobuf:"bytes,4,rep,name=hub_addresses,json=hubAddresses,proto3" json:"hub_addresses,omitempty"`
	// contains filtered or unexported fields
}

func (*HubInfoResponse) Descriptor deprecated

func (*HubInfoResponse) Descriptor() ([]byte, []int)

Deprecated: Use HubInfoResponse.ProtoReflect.Descriptor instead.

func (*HubInfoResponse) GetAudience

func (x *HubInfoResponse) GetAudience() string

func (*HubInfoResponse) GetClientId

func (x *HubInfoResponse) GetClientId() string

func (*HubInfoResponse) GetHubAddresses

func (x *HubInfoResponse) GetHubAddresses() []string

func (*HubInfoResponse) GetOidcIssuer

func (x *HubInfoResponse) GetOidcIssuer() string

func (*HubInfoResponse) ProtoMessage

func (*HubInfoResponse) ProtoMessage()

func (*HubInfoResponse) ProtoReflect

func (x *HubInfoResponse) ProtoReflect() protoreflect.Message

func (*HubInfoResponse) Reset

func (x *HubInfoResponse) Reset()

func (*HubInfoResponse) String

func (x *HubInfoResponse) String() string

type MeshEvent

type MeshEvent struct {
	Type         MeshEvent_Type `protobuf:"varint,1,opt,name=type,proto3,enum=sam.v1.MeshEvent_Type" json:"type,omitempty"`
	PeerId       string         `protobuf:"bytes,2,opt,name=peer_id,json=peerId,proto3" json:"peer_id,omitempty"`
	Timestamp    int64          `protobuf:"varint,3,opt,name=timestamp,proto3" json:"timestamp,omitempty"`
	NewPublicKey []byte         `protobuf:"bytes,4,opt,name=new_public_key,json=newPublicKey,proto3" json:"new_public_key,omitempty"`
	Signature    []byte         `protobuf:"bytes,5,opt,name=signature,proto3" json:"signature,omitempty"`
	// contains filtered or unexported fields
}

func (*MeshEvent) Descriptor deprecated

func (*MeshEvent) Descriptor() ([]byte, []int)

Deprecated: Use MeshEvent.ProtoReflect.Descriptor instead.

func (*MeshEvent) GetNewPublicKey

func (x *MeshEvent) GetNewPublicKey() []byte

func (*MeshEvent) GetPeerId

func (x *MeshEvent) GetPeerId() string

func (*MeshEvent) GetSignature

func (x *MeshEvent) GetSignature() []byte

func (*MeshEvent) GetTimestamp

func (x *MeshEvent) GetTimestamp() int64

func (*MeshEvent) GetType

func (x *MeshEvent) GetType() MeshEvent_Type

func (*MeshEvent) ProtoMessage

func (*MeshEvent) ProtoMessage()

func (*MeshEvent) ProtoReflect

func (x *MeshEvent) ProtoReflect() protoreflect.Message

func (*MeshEvent) Reset

func (x *MeshEvent) Reset()

func (*MeshEvent) String

func (x *MeshEvent) String() string

type MeshEvent_Type

type MeshEvent_Type int32
const (
	MeshEvent_BANNED       MeshEvent_Type = 0
	MeshEvent_KEY_ROTATION MeshEvent_Type = 1
)

func (MeshEvent_Type) Descriptor

func (MeshEvent_Type) Enum

func (x MeshEvent_Type) Enum() *MeshEvent_Type

func (MeshEvent_Type) EnumDescriptor deprecated

func (MeshEvent_Type) EnumDescriptor() ([]byte, []int)

Deprecated: Use MeshEvent_Type.Descriptor instead.

func (MeshEvent_Type) Number

func (MeshEvent_Type) String

func (x MeshEvent_Type) String() string

func (MeshEvent_Type) Type

type NodeConfig

type NodeConfig struct {
	Version     string          `yaml:"version"`
	Attenuation Attenuation     `yaml:"attenuation"`
	Services    []ServiceConfig `yaml:"services"`
}

NodeConfig defines the optional attenuation rules and static services for a specific SAM Node.

type PolicyConfig

type PolicyConfig struct {
	Version  string                `yaml:"version"`
	Bindings []Binding             `yaml:"bindings"`
	Roles    map[string]RolePolicy `yaml:"roles"`
}

PolicyConfig is the root authorization configuration for the SAM Hub.

type RegisterServiceRequest

type RegisterServiceRequest struct {
	Service *ServiceInfo `protobuf:"bytes,1,opt,name=service,proto3" json:"service,omitempty"`
	// Types that are valid to be assigned to Backend:
	//
	//	*RegisterServiceRequest_TargetUrl
	//	*RegisterServiceRequest_Command
	Backend isRegisterServiceRequest_Backend `protobuf_oneof:"backend"`
	// contains filtered or unexported fields
}

func (*RegisterServiceRequest) Descriptor deprecated

func (*RegisterServiceRequest) Descriptor() ([]byte, []int)

Deprecated: Use RegisterServiceRequest.ProtoReflect.Descriptor instead.

func (*RegisterServiceRequest) GetBackend

func (x *RegisterServiceRequest) GetBackend() isRegisterServiceRequest_Backend

func (*RegisterServiceRequest) GetCommand

func (x *RegisterServiceRequest) GetCommand() *CommandBackend

func (*RegisterServiceRequest) GetService

func (x *RegisterServiceRequest) GetService() *ServiceInfo

func (*RegisterServiceRequest) GetTargetUrl

func (x *RegisterServiceRequest) GetTargetUrl() string

func (*RegisterServiceRequest) ProtoMessage

func (*RegisterServiceRequest) ProtoMessage()

func (*RegisterServiceRequest) ProtoReflect

func (x *RegisterServiceRequest) ProtoReflect() protoreflect.Message

func (*RegisterServiceRequest) Reset

func (x *RegisterServiceRequest) Reset()

func (*RegisterServiceRequest) String

func (x *RegisterServiceRequest) String() string

type RegisterServiceRequest_Command

type RegisterServiceRequest_Command struct {
	Command *CommandBackend `protobuf:"bytes,3,opt,name=command,proto3,oneof"`
}

type RegisterServiceRequest_TargetUrl

type RegisterServiceRequest_TargetUrl struct {
	TargetUrl string `protobuf:"bytes,2,opt,name=target_url,json=targetUrl,proto3,oneof"`
}

type RolePolicy

type RolePolicy struct {
	AllowedTargets  []string `yaml:"allowed_targets,omitempty"`
	AllowedServices []string `yaml:"allowed_services,omitempty"`
	CustomDatalog   []string `yaml:"custom_datalog,omitempty"`
}

RolePolicy defines the capabilities granted to a specific authorization role.

AllowedTargets restricts the logical endpoints a peer can route connections to. Targets act similarly to Active Directory network groups and must be specified using the format of the resolved Biscuit facts. IP address ranges are NOT allowed. Valid examples:

  • "group:backend-nodes"
  • "user:admin@example.com"
  • "role:developer"
  • "node:12D3KooW..."

AllowedServices defines the application-level services a peer can invoke. Services are prefixed by their protocol/type to permit fine-grained scoping. Wildcards are supported (e.g., "mcp:*"). Valid examples:

  • "mcp:local-shell-tools"
  • "inference:openrouter"
  • "system:query_db"

type ServiceConfig

type ServiceConfig struct {
	Type        string            `yaml:"type"` // e.g., "mcp", "inference"
	Name        string            `yaml:"name"`
	Description string            `yaml:"description"`
	TargetURL   string            `yaml:"target_url,omitempty"`
	Command     []string          `yaml:"command,omitempty"`
	Env         map[string]string `yaml:"env,omitempty"`
}

type ServiceInfo

type ServiceInfo struct {
	Type        ServiceType `protobuf:"varint,1,opt,name=type,proto3,enum=sam.v1.ServiceType" json:"type,omitempty"`
	Name        string      `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
	Description string      `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`
	// contains filtered or unexported fields
}

func (*ServiceInfo) Descriptor deprecated

func (*ServiceInfo) Descriptor() ([]byte, []int)

Deprecated: Use ServiceInfo.ProtoReflect.Descriptor instead.

func (*ServiceInfo) GetDescription

func (x *ServiceInfo) GetDescription() string

func (*ServiceInfo) GetName

func (x *ServiceInfo) GetName() string

func (*ServiceInfo) GetType

func (x *ServiceInfo) GetType() ServiceType

func (*ServiceInfo) ProtoMessage

func (*ServiceInfo) ProtoMessage()

func (*ServiceInfo) ProtoReflect

func (x *ServiceInfo) ProtoReflect() protoreflect.Message

func (*ServiceInfo) Reset

func (x *ServiceInfo) Reset()

func (*ServiceInfo) String

func (x *ServiceInfo) String() string

type ServiceType

type ServiceType int32
const (
	ServiceType_SERVICE_TYPE_UNSPECIFIED ServiceType = 0
	ServiceType_SERVICE_TYPE_MCP         ServiceType = 1
	ServiceType_SERVICE_TYPE_INFERENCE   ServiceType = 2
)

func ParseServiceType

func ParseServiceType(s string) (ServiceType, error)

ParseServiceType converts a string identifier (e.g. from JSON or REST) to the ServiceType protobuf enum.

func (ServiceType) Descriptor

func (ServiceType) Enum

func (x ServiceType) Enum() *ServiceType

func (ServiceType) EnumDescriptor deprecated

func (ServiceType) EnumDescriptor() ([]byte, []int)

Deprecated: Use ServiceType.Descriptor instead.

func (ServiceType) Number

func (x ServiceType) Number() protoreflect.EnumNumber

func (ServiceType) String

func (x ServiceType) String() string

func (ServiceType) Type

Jump to

Keyboard shortcuts

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