config

package
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultInboxMaxUploadSize int64 = 10 * 1024 * 1024

Variables

This section is empty.

Functions

func ValidateAuthConfig added in v0.3.0 

func ValidateAuthConfig(auth *AuthConfig) error

ValidateAuthConfig validates a parsed static authorization policy. Legacy authority fields are deliberately ignored.

Types

type AuthConfig 

type AuthConfig struct {
	AllowKeyless    *bool                 `json:"allow_keyless,omitempty"`
	UnknownIdentity string                `json:"unknown_identity,omitempty"`
	DefaultCwd      string                `json:"default_cwd,omitempty"`
	Docsets         map[string]DocsetSpec `json:"docsets"`
	Roles           map[string]RoleSpec   `json:"roles,omitempty"`
	// Default is a legacy authority field retained only for JSON parsing. It is ignored.
	Default    map[string]string `json:"default,omitempty"`
	Identities []AuthIdentity    `json:"identities"`
}

AuthConfig is loaded from lore.json.

func LoadAuthConfig 

func LoadAuthConfig(path string) (*AuthConfig, error)

LoadAuthConfig loads auth configuration from a JSON file.

type AuthIdentity 

type AuthIdentity struct {
	Name    string `json:"name"`
	Comment string `json:"comment,omitempty"`
	// PublicKey is optional: an identity may exist purely as a passkey/token
	// login target (no SSH key). Empty = no SSH public-key auth for this identity.
	PublicKey string   `json:"public_key,omitempty"`
	Roles     []string `json:"roles,omitempty"`
	// Docsets is a legacy authority field retained only for JSON parsing. It is ignored.
	Docsets map[string]string `json:"docsets"`
	// Home names the docset that serves as this identity's home directory. Its
	// display path becomes $HOME and the session's initial working directory.
	// Home ownership provides implicit rw unless a nested docset takes precedence.
	Home string `json:"home,omitempty"`
	// Capabilities is a legacy authority field retained only for JSON parsing. It is ignored.
	Capabilities []string `json:"capabilities,omitempty"`

	// Match lists the token-claim predicates that resolve TO this identity.
	// Resolution criteria live on the identity they select (rather than a
	// separate rule list) since every rule maps to exactly one identity. The
	// human case needs no entry: a token whose `sub` equals this identity's
	// Name resolves here implicitly. WIF exchanges (jwt-bearer) match on
	// `sub`/`sub_prefix`/`aud`/`claims` entries with narrowing `scope`/`ttl`.
	Match []IdentityMatch `json:"match,omitempty"`
}

AuthIdentity defines a user identity and its role membership.

type AuthTokensConfig added in v0.2.0 

type AuthTokensConfig struct {
	Issuer     string `yaml:"issuer" json:"issuer,omitempty"`           // `iss` claim + JWKS base
	Audience   string `yaml:"audience" json:"audience,omitempty"`       // required `aud`; one per instance
	AccessTTL  string `yaml:"access_ttl" json:"access_ttl,omitempty"`   // duration string, default 30m
	RefreshTTL string `yaml:"refresh_ttl" json:"refresh_ttl,omitempty"` // duration string, default 720h
}

AuthTokensConfig controls the bearer-token issuer for the MCP + HTTP API. It is server infrastructure and loaded from openlore.yml (hence yaml tags).

type CapabilityRules added in v0.3.0 

type CapabilityRules struct {
	Capabilities []string `json:"capabilities,omitempty"`
}

type Config 

type Config struct {
	ConfigVersion   string
	Port            int
	MetricsPort     int
	HostKeyPath     string
	AllowKeyless    bool
	UnknownIdentity string // "allow" (default) or "deny"
	DefaultCwd      string
	MOTD            string
	AuthFile        string
	SkillsDir       string
	// WritableDir is the disk-backed content root layered over embedded docs.
	// Its directory hierarchy is exposed directly at the virtual root.
	WritableDir string
	// DataDir is the server's writable control-plane data root. Distinct from
	// docset content. Defaults to ./.openlore.
	DataDir         string
	HTTPPort        int
	ExternalSSHPort int // advertised SSH port (for X-SSH-Port header behind a LB)
	// MCPEnabled controls whether the always-on MCP-over-HTTP endpoint runs.
	// Default true. The endpoint is mounted at MCPPath on the HTTP server.
	MCPEnabled bool
	MCPPath    string
	// MCPRequireAuth overrides the SSH-derived authentication posture for the
	// MCP endpoint. Nil inherits !AllowKeyless; true forces OAuth so clients
	// such as Claude open the browser login flow.
	MCPRequireAuth *bool
	// APIEnabled controls whether the plain JSON HTTP API (backed by the MCP
	// server) runs. Default true. It is mounted at APIPath on the HTTP server.
	APIEnabled   bool
	APIPath      string
	TLSCert      string
	TLSKey       string
	CAKeysFile   string
	HostCertFile string
	Files        FilesConfig
	Passkeys     PasskeysConfig
	// Shellexec is the external-command middleware config (pre_read, pre_commit,
	// post_write) run by the built-in shellexec plugin. Replaces the legacy
	// event-bus `hooks` path with middleware on the read/write chains.
	Shellexec ShellexecConfig
	Logger    *slog.Logger

	// Readonly is the global write lock. Default true: the substrate is a
	// read-only filesystem and no write verbs are available. Set false to
	// enable the experimental writable substrate (SetWriteable is called at
	// startup). Global readonly is a hard physical lock — a per-docset
	// readonly=false cannot loosen it.
	Readonly bool

	// WriteConflictPolicy is the global default policy for whole-file overwrite
	// verbs (`>`, tee, sed -i, publish). Default "hash" (compare-and-swap); set
	// "last_write_wins" for unconditional overwrites. A per-docset override
	// (DocsetSpec.WriteConflictPolicy) takes precedence for that docset.
	WriteConflictPolicy vfs.WriteConflictPolicy

	// MaxJobs bounds concurrent async `spawn` jobs (Part D). Default 8.
	MaxJobs int

	// Tokens configures bearer-token issuance/verification for the MCP + HTTP
	// API. This is server infrastructure (issuer identity, audience, signing
	// key, TTLs) — not per-lore access policy — so it lives in openlore.yml
	// alongside passkeys, not in lore.json. When nil, token auth is disabled
	// and the MCP/HTTP endpoints behave as anonymous callers (Phase 0).
	Tokens  *AuthTokensConfig
	Inbox   InboxConfig
	Plugins PluginsConfig

	// OIDCIssuers are external IdPs whose JWTs may be exchanged for OpenLore
	// tokens at the token endpoint via the jwt-bearer grant (workload identity
	// federation). When set, each issuer's JWKS is fetched (discovery) and its
	// assertions are verified and mapped to identities. Server infrastructure,
	// hence openlore.yml.
	OIDCIssuers []OIDCIssuer
	// contains filtered or unexported fields
}

Config holds the resolved server configuration.

func New 

func New(opts ...Option) (Config, error)

New creates a Config by applying options to the defaults. Returns an error if both a config file and embedded config are used.

func (Config) MCPAuthRequired added in v0.3.0 

func (cfg Config) MCPAuthRequired() bool

MCPAuthRequired resolves the MCP-specific override. When it is omitted, MCP retains the historical behavior of mirroring the SSH keyless posture.

type DocsetAccess added in v0.3.0 

type DocsetAccess struct {
	Allow map[string]string `json:"allow,omitempty"`
	Deny  []string          `json:"deny,omitempty"`
}

type DocsetSpec 

type DocsetSpec struct {
	Paths  []PathMapping `json:"paths"`
	Access DocsetAccess  `json:"access,omitempty"`
	// AgentSkills is ignored. Collections are selected dynamically by xattr.
	AgentSkills bool `json:"-"`
	// Aliases are alternate display roots for the first path. They expose the
	// same content while the first path remains canonical for home, inbox,
	// policy, hooks, and changesets.
	Aliases []string `json:"aliases,omitempty"`
	// Inbox names a subfolder (VFS path, relative to a docset root or absolute)
	// that the `publish` grant confines create/edit to. Empty = the docset has
	// no inbox, so a `publish` grant on it can write nothing.
	Inbox string `json:"inbox,omitempty"`
	// MaxWriteSize caps a single write's bytes for this docset; 0 = default (2.5MB).
	MaxWriteSize int64 `json:"max_write_size,omitempty"`

	// Readonly is the per-docset policy check (enforced in the write pipeline,
	// not on the substrate). nil means "inherit" (writable when the global lock
	// is open). A docset can only further restrict: setting it true blocks
	// writes to this docset even when the global lock is open; setting it false
	// is meaningless when the global lock is closed.
	Readonly *bool `json:"readonly,omitempty"`

	// WriteConflictPolicy overrides the global write-conflict policy for writes
	// to this docset. "" inherits Config.WriteConflictPolicy; "hash" forces
	// compare-and-swap overwrites; "last_write_wins" forces unconditional ones.
	WriteConflictPolicy string `json:"write_conflict_policy,omitempty"`

	// OKF, when non-nil, activates the built-in Open Knowledge Format validator
	// for this docset's subtree (see OKFDocsetConfig). nil means OKF is off for
	// this docset; scope narrower subtrees with nested docsets.
	OKF *OKFDocsetConfig `json:"okf,omitempty"`
}

DocsetSpec defines a named set of path mappings.

type FilesConfig 

type FilesConfig struct {
	Allowed []string
	Denied  []string
	Ignore  []string
}

FilesConfig controls which files are served.

type IdentityMatch added in v0.2.0 

type IdentityMatch struct {
	Sub       string            `json:"sub,omitempty"`
	SubPrefix string            `json:"sub_prefix,omitempty"`
	Aud       string            `json:"aud,omitempty"`
	Claims    map[string]string `json:"claims,omitempty"`
	Scope     string            `json:"scope,omitempty"` // narrowing scope for matched tokens (WIF)
	TTL       string            `json:"ttl,omitempty"`   // caps brokered token TTL (WIF)
}

IdentityMatch is a token-claim predicate attached to an AuthIdentity. When a verified assertion's claims satisfy it (all specified fields must hold), the assertion resolves to the enclosing identity. Exact `sub` takes precedence over `sub_prefix`/`aud`/`claims` pattern matches; `scope` narrows and `ttl` caps the brokered OpenLore token.

type InboxConfig added in v0.4.0 

type InboxConfig struct {
	MaxUploadSize int64
	AllowedTypes  map[string]string
}

type JWKSSpec added in v0.2.0 

type JWKSSpec struct {
	Mode string `yaml:"mode" json:"mode,omitempty"` // "discovery" (default)
}

JWKSSpec configures how an OIDC issuer's public keys are obtained. Only "discovery" (fetch from the issuer's .well-known/openid-configuration) is supported today; empty defaults to discovery.

type OIDCIssuer added in v0.2.0 

type OIDCIssuer struct {
	IssuerURL string   `yaml:"issuer_url" json:"issuer_url"`
	JWKS      JWKSSpec `yaml:"jwks" json:"jwks,omitempty"`
}

OIDCIssuer is an external IdP trusted for WIF token exchange. Server infrastructure, loaded from openlore.yml.

type OKFDocsetConfig added in v0.3.0 

type OKFDocsetConfig struct {
	// Enforce rejects non-conformant writes when true (nil → true, the default).
	// When false, a non-conformant write is logged but allowed through.
	Enforce *bool `json:"enforce,omitempty"`
	// Patterns are globs matched against a write target's basename to select
	// which files are validated. Empty defaults to ["*.md"].
	Patterns []string `json:"patterns,omitempty"`
}

OKFDocsetConfig configures the built-in Open Knowledge Format validator for a docset. Its presence on a DocsetSpec activates OKF validation across that docset's subtree (defaults: enforce=true, patterns=["*.md"]).

It lives on the docset (in lore.json) rather than as a global block so OKF scoping is defined in the same place as the docset's paths and grants and can never drift from them: a write is validated by the OKF config of the docset that owns its path (the longest matching display root, exactly as authz resolves grants). Include/exclude for narrower subtrees is expressed with nested docsets — a child docset with OKF adds validation to that subtree; a child docset without OKF shadows a parent's OKF and exempts that subtree.

type Option 

type Option func(*Config) error

Option is a functional option for configuring the server.

func WithAPIEnabled added in v0.2.0 

func WithAPIEnabled(enabled bool) Option

WithAPIEnabled toggles the JSON HTTP API.

func WithAPIPath added in v0.2.0 

func WithAPIPath(path string) Option

WithAPIPath sets the path the JSON HTTP API is mounted at on the HTTP server (e.g. "/api").

func WithAllowKeyless 

func WithAllowKeyless(allow bool) Option

WithAllowKeyless controls whether keyless SSH connections are allowed.

func WithAllowedPatterns 

func WithAllowedPatterns(patterns []string) Option

WithAllowedPatterns sets the file patterns to serve.

func WithAuthFile 

func WithAuthFile(path string) Option

WithAuthFile sets the path to the auth.json file.

func WithCAKeysFile 

func WithCAKeysFile(path string) Option

WithCAKeysFile sets the path to a file containing trusted CA public keys for SSH certificate authentication (analogous to OpenSSH TrustedUserCAKeys).

func WithConfigFile 

func WithConfigFile(path string) Option

WithConfigFile loads configuration from a YAML file. Fields in the file override defaults. If the file does not exist, no error is returned and the config is unchanged.

func WithDataDir added in v0.2.0 

func WithDataDir(dir string) Option

WithDataDir sets the server's writable control-plane data root.

func WithDefaultCwd 

func WithDefaultCwd(cwd string) Option

WithDefaultCwd sets the default working directory for shell sessions.

func WithEmbeddedConfig 

func WithEmbeddedConfig(data []byte, motdFallback string) Option

WithEmbeddedConfig loads config from an embedded YAML byte slice. The MOTD fallback is set separately from the config fields.

func WithHTTPPort 

func WithHTTPPort(port int) Option

WithHTTPPort sets the HTTP front page server port. 0 disables it.

func WithHostCertFile 

func WithHostCertFile(path string) Option

WithHostCertFile sets the path to the SSH host certificate file (signed by a CA, analogous to OpenSSH HostCertificate).

func WithHostKeyPath 

func WithHostKeyPath(path string) Option

WithHostKeyPath sets the path to the SSH host key.

func WithIgnorePatterns 

func WithIgnorePatterns(patterns []string) Option

WithIgnorePatterns sets the ignore patterns.

func WithLogger 

func WithLogger(logger *slog.Logger) Option

WithLogger sets the structured logger.

func WithMCPEnabled added in v0.2.0 

func WithMCPEnabled(enabled bool) Option

WithMCPEnabled toggles the MCP-over-HTTP endpoint.

func WithMCPPath added in v0.2.0 

func WithMCPPath(path string) Option

WithMCPPath sets the path the MCP-over-HTTP endpoint is mounted at on the HTTP server (e.g. "/mcp").

func WithMOTD 

func WithMOTD(motd string) Option

WithMOTD sets the message of the day, replacing any previous value.

func WithMOTDFile 

func WithMOTDFile(path string) Option

WithMOTDFile loads the MOTD from a file path, replacing any previous value.

func WithMetricsPort 

func WithMetricsPort(port int) Option

WithMetricsPort sets the metrics HTTP port. 0 disables metrics.

func WithPasskeys 

func WithPasskeys(pk PasskeysConfig) Option

WithPasskeys sets the passkeys configuration.

func WithPort 

func WithPort(port int) Option

WithPort sets the SSH server port.

func WithReadonly added in v0.2.0 

func WithReadonly(readonly bool) Option

WithReadonly sets the global write lock. true (the default) keeps the substrate read-only; false enables the experimental writable substrate.

func WithSkillsDir 

func WithSkillsDir(dir string) Option

WithSkillsDir sets the directory for loading runtime skills.

func WithTLS 

func WithTLS(cert, key string) Option

WithTLS sets TLS certificate and key paths for the HTTP server.

func WithWritableDir added in v0.3.0 

func WithWritableDir(dir string) Option

WithWritableDir sets the disk-backed content root layered over embedded docs.

func WithWriteConflictPolicy added in v0.2.0 

func WithWriteConflictPolicy(policy string) Option

WithWriteConflictPolicy sets the global default write-conflict policy for whole-file overwrite verbs. Empty resolves to the default (hash). Invalid values are rejected.

type PasskeysConfig 

type PasskeysConfig struct {
	Enabled      bool
	RPID         string
	RPName       string
	RPOrigins    []string
	LorePath     string
	PasskeysFile string
	SessionTTL   string // parsed as time.Duration
}

PasskeysConfig holds WebAuthn passkey configuration.

type PathMapping 

type PathMapping struct {
	Source  string // the real path (relative to root dir or assets/lore)
	Display string // the path shown in the shell (empty = same as Source)
}

PathMapping represents a path entry — either a simple string path or a source→display mapping.

func (PathMapping) MarshalJSON added in v0.3.0 

func (p PathMapping) MarshalJSON() ([]byte, error)

MarshalJSON preserves the two input forms accepted by UnmarshalJSON.

func (*PathMapping) UnmarshalJSON 

func (p *PathMapping) UnmarshalJSON(data []byte) error

UnmarshalJSON supports both string and {"source": "display"} forms.

type PluginsConfig added in v0.4.0 

type PluginsConfig struct{ Skills SkillsPluginConfig }

type RoleSpec added in v0.3.0 

type RoleSpec struct {
	Comment string          `json:"comment,omitempty"`
	Allow   CapabilityRules `json:"allow,omitempty"`
	Deny    CapabilityRules `json:"deny,omitempty"`
}

RoleSpec is a reusable set of capabilities. Docset grants are resource-side ACL entries, not properties of the role itself.

type ShellexecCmd added in v0.2.0 

type ShellexecCmd struct {
	// Cmd is the shell command line to execute.
	Cmd string `yaml:"cmd"`
	// Timeout is a duration string (e.g. "30s") capping wall-clock runtime.
	// Empty means 30s. A timeout counts as a failure.
	Timeout string `yaml:"timeout"`
	// FailOnError makes a non-zero exit fatal to the operation for pre_read /
	// pre_commit (the read/write is aborted). Defaults to true (nil → true).
	// Ignored for post_write, which never halts the log.
	FailOnError *bool `yaml:"fail_on_error"`
	// Debounce is a duration string coalescing repeated pre_read hits on the
	// same path. Empty means 2s. Only applies to pre_read.
	Debounce string `yaml:"debounce"`
	// Async runs the command in the background (fire-and-forget). Default false
	// (synchronous). An async pre_read / pre_commit cannot abort the operation.
	Async bool `yaml:"async"`
}

ShellexecCmd is a single external command run by the shellexec plugin. It is run via `sh -c` with the OPENLORE_* env protocol.

type ShellexecConfig added in v0.2.0 

type ShellexecConfig struct {
	PreRead   []ShellexecCmd `yaml:"pre_read"`
	PreCommit []ShellexecCmd `yaml:"pre_commit"`
	PostWrite []ShellexecCmd `yaml:"post_write"`
}

ShellexecConfig is the openlore.yml `shellexec:` block: external commands run as middleware on the read and write paths. pre_read runs before a read (may abort it), pre_commit runs before a write commits (may reject it), post_write runs after a durable commit (fire-and-forget: never halts the log).

func (ShellexecConfig) IsEmpty added in v0.2.0 

func (c ShellexecConfig) IsEmpty() bool

IsEmpty reports whether no shellexec commands are configured.

type SkillsPluginConfig added in v0.4.0 

type SkillsPluginConfig struct {
	Enabled        bool
	RemoteCheckTTL time.Duration
	RemoteTimeout  time.Duration
	RemoteMaxBytes int64
}

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.