openlore

Documentation

Index

• Variables
• func NewMCPServer(fs bashfs.FileSystem, opts ...MCPOption) *mcp.Server
• type AuthConfig
• type AuthIdentity
• type DirFS
  • func NewDirFS(root string, files config.FilesConfig) *DirFS
  • func (d *DirFS) ReadDir(p string) ([]bashfs.FileInfo, error)
  • func (d *DirFS) ReadFile(p string) ([]byte, error)
  • func (d *DirFS) Stat(p string) (*bashfs.FileInfo, error)
  • func (d *DirFS) WithBus(bus *eventbus.Bus) *DirFS
  • func (d *DirFS) WriteFile(p string, content []byte) error
• type DocsetSpec
• type EmbedFS
  • func NewEmbedFS(efs embed.FS, root string, files config.FilesConfig) *EmbedFS
  • func (e *EmbedFS) ReadDir(p string) ([]bashfs.FileInfo, error)
  • func (e *EmbedFS) ReadFile(p string) ([]byte, error)
  • func (e *EmbedFS) Stat(p string) (*bashfs.FileInfo, error)
• type FSAdapter
  • func NewFSAdapter(fsys fs.FS) *FSAdapter
  • func (a *FSAdapter) ReadDir(p string) ([]bashfs.FileInfo, error)
  • func (a *FSAdapter) ReadFile(p string) ([]byte, error)
  • func (a *FSAdapter) Stat(p string) (*bashfs.FileInfo, error)
• type FileSystem
• type FilesConfig
• type FolderConfig
• type Identity
• type MCPOption
  • func WithMCPEnvVars(vars map[string]string) MCPOption
  • func WithMCPInstructions(instructions string) MCPOption
  • func WithMCPServerName(name string) MCPOption
  • func WithMCPShellDescription(desc string) MCPOption
• type MergeFS
  • func NewMergeFS() *MergeFS
  • func (m *MergeFS) FilteredView(allowedMounts map[string]bool) *MergeFS
  • func (m *MergeFS) Mount(name string, fs bashfs.FileSystem)
  • func (m *MergeFS) ReadDir(p string) ([]bashfs.FileInfo, error)
  • func (m *MergeFS) ReadFile(p string) ([]byte, error)
  • func (m *MergeFS) SetRoot(fs bashfs.FileSystem)
  • func (m *MergeFS) Stat(p string) (*bashfs.FileInfo, error)
• type OnConnectFunc
• type OnDisconnectFunc
• type Option
• type PasskeysConfig
• type PathMapping
• type SFTPHandler
  • func NewSFTPHandler(fs bashfs.FileSystem) *SFTPHandler
  • func (h *SFTPHandler) Filecmd(r *sftp.Request) error
  • func (h *SFTPHandler) Filelist(r *sftp.Request) (sftp.ListerAt, error)
  • func (h *SFTPHandler) Fileread(r *sftp.Request) (io.ReaderAt, error)
  • func (h *SFTPHandler) Filewrite(r *sftp.Request) (io.WriterAt, error)
• type Server
  • func NewServer(rootDir string, opts ...config.Option) (*Server, error)
  • func (s *Server) Config() config.Config
  • func (s *Server) FileSystem() bashfs.FileSystem
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Mount(name string, fs bashfs.FileSystem)
  • func (s *Server) MountFS(name string, fsys fs.FS)
  • func (s *Server) OnConnect(fn OnConnectFunc)
  • func (s *Server) OnDisconnect(fn OnDisconnectFunc)
  • func (s *Server) SetRootBashFS(fsys bashfs.FileSystem)
  • func (s *Server) SetRootFS(fsys fs.FS)
  • func (s *Server) SetSessionFSFn(fn SessionFSFn)
  • func (s *Server) Shutdown(ctx context.Context) error
• type SessionFSFn

Variables

var (
	WithConfigFile      = config.WithConfigFile
	WithEmbeddedConfig  = config.WithEmbeddedConfig
	WithPort            = config.WithPort
	WithMetricsPort     = config.WithMetricsPort
	WithHostKeyPath     = config.WithHostKeyPath
	WithAllowKeyless    = config.WithAllowKeyless
	WithDefaultCwd      = config.WithDefaultCwd
	WithMOTD            = config.WithMOTD
	WithMOTDFile        = config.WithMOTDFile
	WithAuthFile        = config.WithAuthFile
	WithAllowedPatterns = config.WithAllowedPatterns
	WithIgnorePatterns  = config.WithIgnorePatterns
	WithLogger          = config.WithLogger
	WithSkillsDir       = config.WithSkillsDir
	WithHTTPPort        = config.WithHTTPPort
	WithTLS             = config.WithTLS
	WithCAKeysFile      = config.WithCAKeysFile
	WithHostCertFile    = config.WithHostCertFile
	WithPasskeys        = config.WithPasskeys
	LoadAuthConfig      = config.LoadAuthConfig
)

Configuration options re-exported for external consumers.

Functions

func NewMCPServer

func NewMCPServer(fs bashfs.FileSystem, opts ...MCPOption) *mcp.Server

NewMCPServer creates an MCP server backed by the given filesystem. The returned server exposes two tools — `shell` and `list_commands` — that let agents browse and operate on the filesystem via a restricted shell.

Types

type AuthConfig

type AuthConfig = config.AuthConfig

AuthConfig is loaded from auth.json.

type AuthIdentity

type AuthIdentity = config.AuthIdentity

AuthIdentity defines a user identity with access to a lore spec.

type DirFS

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

DirFS serves files from a real directory on disk.

DirFS is read-only by default. Call WithBus(...) to obtain a copy that supports WriteFile and emits a KindPostWrite event on each successful write. (P1-06.)

func NewDirFS

func NewDirFS(root string, files config.FilesConfig) *DirFS

NewDirFS creates a new DirFS rooted at the given directory.

func (*DirFS) ReadDir

func (d *DirFS) ReadDir(p string) ([]bashfs.FileInfo, error)

func (*DirFS) ReadFile

func (d *DirFS) ReadFile(p string) ([]byte, error)

func (*DirFS) Stat

func (d *DirFS) Stat(p string) (*bashfs.FileInfo, error)

func (*DirFS) WithBus

func (d *DirFS) WithBus(bus *eventbus.Bus) *DirFS

WithBus returns a copy of DirFS that allows writes via WriteFile and fans every successful write out as a KindPostWrite event on the supplied bus. Pass nil to disable writes.

func (*DirFS) WriteFile

func (d *DirFS) WriteFile(p string, content []byte) error

WriteFile writes content to the path inside the DirFS root. Errors if the DirFS was constructed without a bus (read-only mode). On success, emits a KindPostWrite event so subscribers (DB writer, SSE fanout, Notifier, post_write shell hooks) can react.

type DocsetSpec

type DocsetSpec = config.DocsetSpec

DocsetSpec defines a named set of path mappings for a docset.

type EmbedFS

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

EmbedFS serves files from an embed.FS.

func NewEmbedFS

func NewEmbedFS(efs embed.FS, root string, files config.FilesConfig) *EmbedFS

NewEmbedFS creates a new EmbedFS.

func (*EmbedFS) ReadDir

func (e *EmbedFS) ReadDir(p string) ([]bashfs.FileInfo, error)

func (*EmbedFS) ReadFile

func (e *EmbedFS) ReadFile(p string) ([]byte, error)

func (*EmbedFS) Stat

func (e *EmbedFS) Stat(p string) (*bashfs.FileInfo, error)

type FSAdapter

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

FSAdapter adapts a standard fs.FS to the bashfs.FileSystem interface.

func NewFSAdapter

func NewFSAdapter(fsys fs.FS) *FSAdapter

NewFSAdapter creates a new FSAdapter.

func (*FSAdapter) ReadDir

func (a *FSAdapter) ReadDir(p string) ([]bashfs.FileInfo, error)

func (*FSAdapter) ReadFile

func (a *FSAdapter) ReadFile(p string) ([]byte, error)

func (*FSAdapter) Stat

func (a *FSAdapter) Stat(p string) (*bashfs.FileInfo, error)

type FileSystem

type FileSystem = bashfs.FileSystem

FileSystem is the read-only filesystem interface used by OpenLore.

type FilesConfig

type FilesConfig = config.FilesConfig

FilesConfig controls which files are served.

type FolderConfig

type FolderConfig = config.FolderConfig

FolderConfig defines an additional named folder mount.

type Identity

type Identity struct {
	RemoteAddr     string
	User           string
	PublicKey      ssh.PublicKey
	SessionID      string
	ConnectedAt    time.Time
	IdentityName   string               // matched identity name from auth config
	LoreName       string               // name of the lore spec this identity uses
	PathAccess     []config.PathMapping // resolved path mappings
	PublishDocsets []string             // writable docsets (nil = all in lore)
}

Identity represents a connected SSH user.

type MCPOption

type MCPOption func(*mcpConfig)

MCPOption configures the MCP server constructed by NewMCPServer.

func WithMCPEnvVars

func WithMCPEnvVars(vars map[string]string) MCPOption

WithMCPEnvVars sets environment variables on the shell for every command execution.

func WithMCPInstructions

func WithMCPInstructions(instructions string) MCPOption

WithMCPInstructions sets server instructions that are automatically injected into the client's context when it connects.

func WithMCPServerName

func WithMCPServerName(name string) MCPOption

WithMCPServerName overrides the MCP server name reported in the initialize response. Clients see this in their connector list.

func WithMCPShellDescription

func WithMCPShellDescription(desc string) MCPOption

WithMCPShellDescription overrides the shell tool's description.

type MergeFS

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

MergeFS merges multiple filesystems under named mount points. An optional root filesystem serves content directly at "/".

func NewMergeFS

func NewMergeFS() *MergeFS

NewMergeFS creates an empty MergeFS.

func (*MergeFS) FilteredView

func (m *MergeFS) FilteredView(allowedMounts map[string]bool) *MergeFS

FilteredView returns a new MergeFS that only includes the specified mount names. The root filesystem is always included. If allowedMounts is nil, returns the original.

func (*MergeFS) Mount

func (m *MergeFS) Mount(name string, fs bashfs.FileSystem)

Mount adds a filesystem under the given name.

func (*MergeFS) ReadDir

func (m *MergeFS) ReadDir(p string) ([]bashfs.FileInfo, error)

func (*MergeFS) ReadFile

func (m *MergeFS) ReadFile(p string) ([]byte, error)

func (*MergeFS) SetRoot

func (m *MergeFS) SetRoot(fs bashfs.FileSystem)

SetRoot sets the root filesystem that serves content at "/".

func (*MergeFS) Stat

func (m *MergeFS) Stat(p string) (*bashfs.FileInfo, error)

type OnConnectFunc

type OnConnectFunc func(Identity)

OnConnectFunc is called when a new SSH session is established.

type OnDisconnectFunc

type OnDisconnectFunc func(Identity)

OnDisconnectFunc is called when an SSH session ends.

type Option

type Option = config.Option

Option is a functional option for configuring the server.

type PasskeysConfig

type PasskeysConfig = config.PasskeysConfig

PasskeysConfig holds WebAuthn passkey configuration.

type PathMapping

type PathMapping = config.PathMapping

PathMapping represents a path entry.

type SFTPHandler

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

SFTPHandler implements the SFTP server interfaces using a bashfs.FileSystem.

func NewSFTPHandler

func NewSFTPHandler(fs bashfs.FileSystem) *SFTPHandler

NewSFTPHandler creates a new SFTP handler backed by the given filesystem.

func (*SFTPHandler) Filecmd

func (h *SFTPHandler) Filecmd(r *sftp.Request) error

Filecmd rejects all file commands (read-only filesystem).

func (*SFTPHandler) Filelist

func (h *SFTPHandler) Filelist(r *sftp.Request) (sftp.ListerAt, error)

Filelist handles SFTP directory listing and stat requests.

func (*SFTPHandler) Fileread

func (h *SFTPHandler) Fileread(r *sftp.Request) (io.ReaderAt, error)

Fileread handles SFTP file read requests.

func (*SFTPHandler) Filewrite

func (h *SFTPHandler) Filewrite(r *sftp.Request) (io.WriterAt, error)

Filewrite rejects all write requests (read-only filesystem).

type Server

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

Server is the main OpenLore SSH server.

func NewServer

func NewServer(rootDir string, opts ...config.Option) (*Server, error)

NewServer creates a new OpenLore SSH server. rootDir is the primary directory to serve (can be empty if using Mount). Options are applied using the functional options pattern via config.Option.

func (*Server) Config

func (s *Server) Config() config.Config

Config returns the resolved configuration.

func (*Server) FileSystem

func (s *Server) FileSystem() bashfs.FileSystem

FileSystem returns the server's filesystem.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the SSH server (blocks).

func (*Server) Mount

func (s *Server) Mount(name string, fs bashfs.FileSystem)

Mount adds a named filesystem mount point using a bashfs.FileSystem.

func (*Server) MountFS

func (s *Server) MountFS(name string, fsys fs.FS)

MountFS adds a named filesystem mount point using a standard fs.FS.

func (*Server) OnConnect

func (s *Server) OnConnect(fn OnConnectFunc)

OnConnect registers a callback for new connections.

func (*Server) OnDisconnect

func (s *Server) OnDisconnect(fn OnDisconnectFunc)

OnDisconnect registers a callback for disconnections.

func (*Server) SetRootBashFS

func (s *Server) SetRootBashFS(fsys bashfs.FileSystem)

SetRootBashFS sets the root filesystem using a bashfs.FileSystem. Paths that don't match any mount fall through to this filesystem.

func (*Server) SetRootFS

func (s *Server) SetRootFS(fsys fs.FS)

SetRootFS sets the root filesystem using a standard fs.FS.

func (*Server) SetSessionFSFn

func (s *Server) SetSessionFSFn(fn SessionFSFn)

SetSessionFSFn registers a per-session filesystem decorator. When set, the server calls fn(identity, baseFS) for each new SSH session and uses the returned filesystem for that session's shell.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server.

type SessionFSFn

type SessionFSFn func(id Identity, base bashfs.FileSystem) bashfs.FileSystem

SessionFSFn returns the filesystem to use for a given SSH session identity. The default implementation returns the base FS unchanged.