config

type AuthConfig struct {
	AllowKeyless    *bool                     `json:"allow_keyless,omitempty"`
	UnknownIdentity string                    `json:"unknown_identity,omitempty"`
	DefaultCwd      string                    `json:"default_cwd,omitempty"`
	Rules           map[string]rules.RuleSpec `json:"rules,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"`
}

type AuthIdentity struct {
	Name             string            `json:"name"`
	Comment          string            `json:"comment,omitempty"`
	CreatedBy        string            `json:"created_by,omitempty"`
	ClientIDMetadata *ClientIDMetadata `json:"client_id_metadata,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"`
	// Delegates are identities permitted to act on behalf of this principal.
	// An omitted Roles field inherits all principal roles; a present field is
	// intersected with the principal's roles. Denials always subtract authority.
	Delegates []DelegateEntry `json:"delegates,omitempty"`
}

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 1h
	RefreshTTL string `yaml:"refresh_ttl" json:"refresh_ttl,omitempty"` // duration string, default 720h
}

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

type ClientIDMetadata struct {
	URL        string    `json:"url"`
	PinnedName string    `json:"pinned_name"`
	FirstSeen  time.Time `json:"first_seen"`
}

type Config struct {
	ConfigVersion   string
	Debug           bool
	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 and JSON API HTTP endpoints. Nil inherits !AllowKeyless; true forces
	// OAuth so HTTP clients must authenticate.
	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
	MTLS         MTLSConfig
	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
	Rules     RulesConfig

	// 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:
	// under a public posture the MCP/HTTP endpoints serve anonymous callers
	// (Phase 0); under a token-required posture (HTTPAuthRequired) they fail
	// closed with 401, since no caller can present a token.
	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
}

type DelegateEntry struct {
	Identity         string   `json:"identity"`
	Roles            []string `json:"roles,omitempty"`
	DenyDocsets      []string `json:"deny_docsets,omitempty"`
	DenyCapabilities []string `json:"deny_capabilities,omitempty"`
	ClientAuth       string   `json:"client_auth,omitempty"`
}

type DirConfigPermission struct {
	Edit []string `json:"edit,omitempty"`
}

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

type DocsetSpec struct {
	Paths  []PathMapping             `json:"paths"`
	Access DocsetAccess              `json:"access,omitempty"`
	Rules  map[string]rules.RuleSpec `json:"rules,omitempty"`
	Config *DirConfigPermission      `json:"config,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"`
}

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

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)
}

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

type JWKSSpec struct {
	Mode string `yaml:"mode" json:"mode,omitempty"` // "discovery" (default) or "url"
	URL  string `yaml:"url" json:"url,omitempty"`   // JWKS document URL; required iff mode is "url"
}

type MTLSConfig struct {
	CABundle string `yaml:"ca_bundle" json:"ca_bundle,omitempty"`
}

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

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"`
}

type Option func(*Config) error

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

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)
}

type PluginsConfig struct{ Skills SkillsPluginConfig }

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

type RulesConfig struct {
	Growth    float64
	Tokenizer tokenizer.Tokenizer
}

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"`
}

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

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