Documentation
¶
Overview ¶
Package config is the product-neutral half of a product's configuration: where the project and user config files are, how a TOML file is decoded without ever reading a secret, the profile base every product shares (credentials, Vault, TLS, SSH bastion, production, session limits), the policy fingerprint, the diff helpers that mark loosenings, and the store of the policies the human approved.
The rule every product follows: the AI may tighten a policy (the change applies at once); only the human loosens it (the console shows the diff and applies it after a typed confirmation).
Index ¶
- Constants
- func ApprovedKey(root, profile string) string
- func ApprovedPath(p kit.Product, stateDir, key string) (string, error)
- func CheckProfileName(name string, production bool) error
- func CheckValue(p kit.Product, key, val string) error
- func Decode(p kit.Product, data []byte, name string, into any) (toml.MetaData, error)
- func EmbedsPassword(s string) bool
- func FindProjectRoot(p kit.Product, cwd string) (string, bool)
- func Fingerprint(v any) string
- func IsLoopback(host string) bool
- func LoadApproved(p kit.Product, stateDir, key string, into any) (bool, error)
- func LooserLimit(o, n int64) bool
- func ProjectConfigPath(p kit.Product, root string) string
- func ProjectHash(root string) string
- func ProjectKey(p kit.Product, cwd string) string
- func ProjectKeyOf(root string) string
- func SSHString(s *SSHProfile) string
- func SaveApproved(p kit.Product, stateDir, key string, v any) error
- func SecretKey(key toml.Key) bool
- func SortedSet(s []string) []string
- func TLSRank(mode string) int
- func TLSVerifiesChain(mode, ca string) bool
- func UnsafeRune(r rune) bool
- func UserConfigPath(p kit.Product) (string, error)
- func ValidServerName(s string) bool
- type Base
- type Change
- type Policy
- type RawSSH
- type SSHProfile
Constants ¶
const ( CredentialsAsk = "ask" CredentialsKeychain = "keychain" CredentialsVault = "vault" )
Credentials modes: where the console gets a secret.
const ( SSHAuthKey = "key" SSHAuthAgent = "agent" SSHAuthPassword = "password" )
SSH authentication methods.
const ( TLSDisable = "disable" TLSPrefer = "prefer" TLSRequire = "require" TLSVerifyCA = "verify-ca" TLSVerifyFull = "verify-full" )
TLS modes of a network profile, as libpq's sslmode, in increasing strength.
const ConfigFile = "config.toml"
ConfigFile is the name of a project or user config file.
const DefaultSSHPort = 22
DefaultSSHPort is the bastion port when ssh.port is unset.
const MaxProfileName = 64
MaxProfileName bounds a profile name, in bytes.
Variables ¶
This section is empty.
Functions ¶
func ApprovedKey ¶
ApprovedKey names the approved-policy file of a profile: <ProjectHash(root)>-<profile>, or user-<profile> for a profile that comes from the user config only (root == "").
func ApprovedPath ¶
ApprovedPath is <stateDir>/<p.Name>/approved/<key>.json.
func CheckProfileName ¶
CheckProfileName refuses a name unusable in file and socket names, and, for a production profile, a name too short or too common to be typed as an approval.
func CheckValue ¶
CheckValue refuses a config value that embeds a password or holds a character that could hide text on the approval screen, where config values are shown to the human.
func Decode ¶
Decode decodes TOML data into into. name labels errors. It refuses a key that looks like a secret (password, token, ...) at any depth and any key into does not declare, and never quotes a value in an error.
func EmbedsPassword ¶
EmbedsPassword reports whether s looks like a DSN carrying a password: user:pw@host, scheme://user:pw@host, or a keyword DSN with password=.
func FindProjectRoot ¶
FindProjectRoot walks up from cwd to the first directory holding .<p.Name>/config.toml.
func Fingerprint ¶
Fingerprint returns the hex sha256 of v's JSON encoding. The caller passes a canonical form (sorted lists, defaults applied) so that list order does not change it. A value JSON cannot encode is fingerprinted from its Go syntax, which still differs from every valid policy.
func IsLoopback ¶
IsLoopback reports a host that names this machine: "localhost" or a loopback IP literal. Any other name, even one that resolves to loopback, is remote.
func LoadApproved ¶
LoadApproved decodes the approved policy of key into into. It returns false and no error when no policy was approved yet.
func LooserLimit ¶
LooserLimit reports whether moving a limit from o to n loosens it. Zero means unlimited.
func ProjectConfigPath ¶
ProjectConfigPath is <root>/.<p.Name>/config.toml.
func ProjectHash ¶
ProjectHash returns the first 8 hex digits of sha256 of the absolute, cleaned project root.
func ProjectKey ¶
ProjectKey names the project of cwd in socket paths: ProjectHash of the project root, or "user" when cwd is outside any project (profiles from the user config only). The console and its clients must agree on it.
func ProjectKeyOf ¶
ProjectKeyOf is ProjectKey for a known project root ("" for none).
func SaveApproved ¶
SaveApproved atomically writes v, indented JSON with a final newline, as the approved policy of key, mode 0600 in a 0700 directory.
func SortedSet ¶
SortedSet returns a sorted, de-duplicated, non-nil copy of s: the canonical form of a list field.
func TLSRank ¶
TLSRank orders TLS modes by strength. "" is prefer, the mode of profiles approved before the setting existed; an unknown mode ranks -1.
func TLSVerifiesChain ¶
TLSVerifiesChain reports a tls mode that verifies the server's certificate chain: verify-ca and verify-full, and require with tls_ca, as libpq.
func UnsafeRune ¶
UnsafeRune reports a character that could alter or hide text on a terminal: a control character (C0, DEL, C1), an invalid byte or a format character such as a bidi override.
func UserConfigPath ¶
UserConfigPath is <user config dir>/<p.Name>/config.toml.
func ValidServerName ¶
ValidServerName reports a DNS name or an IP literal.
Types ¶
type Base ¶
type Base struct {
User string `json:"user"`
Credentials string `json:"credentials"`
// VaultPath is the Vault path read for the login when Credentials is
// "vault".
VaultPath string `json:"vault_path,omitempty"`
// CredentialsTTL makes the console ask for the secret again (and
// reconnect) once the connection is that old; 0 keeps it for the
// session.
CredentialsTTL time.Duration `json:"credentials_ttl,omitempty"`
TLS string `json:"tls,omitempty"`
TLSCA string `json:"tls_ca,omitempty"`
TLSCert string `json:"tls_cert,omitempty"`
TLSKey string `json:"tls_key,omitempty"`
Production bool `json:"production"`
SSH *SSHProfile `json:"ssh,omitempty"`
// IdleTimeout ends the console session after that long without
// activity, MaxSession after that long in all.
IdleTimeout time.Duration `json:"idle_timeout"`
MaxSession time.Duration `json:"max_session"`
}
Base is the profile part every product shares. A product embeds it in its profile (or keeps its own fields with the same meaning) and calls DiffBase from its Policy.Diff.
type Change ¶
Change is one difference between two policies. For list fields each added or removed element is its own Change, with Old empty for an addition and New empty for a removal. Loosens marks a change the human must confirm in the console before it applies.
func DiffBase ¶
DiffBase lists the changes of the shared profile part and marks each loosening: any change of user (another login), a credentials mode other than ask, another Vault path, a weaker tls mode, any change of tls_ca, tls_cert or tls_key, production true→false, any change of the ssh table (a credentials mode other than ask for the bastion), a longer session limit, a longer or removed credentials_ttl.
type Policy ¶
type Policy interface {
// Diff lists the changes from approved (a value of the same type) to
// this policy, each marked Loosens or not.
Diff(approved Policy) []Change
// Describe is the policy as lines for the console's status screen.
Describe() []string
}
Policy is the security-relevant view of one profile of a product. The console fingerprints it, compares the current policy with the last approved one and asks the human before applying any loosening. A product's own loosening rules live in its Diff: lockkit never decides what loosens a product's fields.
type RawSSH ¶
type RawSSH struct {
Host string `toml:"host"`
Port int `toml:"port"`
User string `toml:"user"`
Auth string `toml:"auth"`
Key string `toml:"key"`
Credentials string `toml:"credentials"`
}
RawSSH is the [profiles.<name>.ssh] table as written.
type SSHProfile ¶
type SSHProfile struct {
Host string `json:"host"`
Port int `json:"port"`
User string `json:"user"`
Auth string `json:"auth"`
Key string `json:"key,omitempty"`
Credentials string `json:"credentials"`
}
SSHProfile is the bastion a network profile is reached through. Host and Port of the profile are then seen from the bastion. It never holds a secret: a key passphrase or an SSH password follows Credentials.
func ParseSSH ¶
func ParseSSH(p kit.Product, r RawSSH, credentials string, errf func(string, ...any) error) (*SSHProfile, error)
ParseSSH validates the ssh table of a profile whose own credentials mode is credentials. errf prefixes errors with the profile. A product checks first that its backend can be reached through a TCP forward.