Documentation
¶
Overview ¶
Package config provides centralized configuration management for the application. It has no external dependency on other internal packages to avoid import cycles.
Per the Open CLI Collective Secret-Handling Standard §1.2 / §2.3, no access secret is ever written here. The per-user OAuth token lives only in the OS keyring (via cli-common's credstore). The OAuth client JSON is deployment material (§1.2) and lives in a plain file referenced by oauth_client_path. This file owns config.yml: the authoritative credential_ref (§1.3), the OAuth client JSON path, the optional §1.4 file-backend opt-in, and the pre-existing non-secret tuning (cache TTL, granted scopes).
Index ¶
- Constants
- func CacheDirPath() (string, error)
- func DefaultOAuthClientPath() (string, error)
- func ExpandPath(p string) string
- func GetCacheDir() (string, error)
- func GetCacheTTL() time.Duration
- func GetCacheTTLHours() int
- func GetConfigDir() (string, error)
- func GetConfigPath() (string, error)
- func GetConfigPathNoCreate() (string, error)
- func GetCredentialsPath() (string, error)
- func GetTokenPath() (string, error)
- func LegacyCacheDir() (string, error)
- func LegacyConfigJSONPath() (string, error)
- func SaveConfig(cfg *Config) error
- func ShortenPath(path string) string
- type Config
- type KeyringConfig
Constants ¶
const ( // DirName is the name of the configuration directory. DirName = "google-readonly" // CredentialsFile is the legacy OAuth client JSON filename (deployment // material). Superseded by OAuthClientFile; retained so the one-time // migration can find and relocate it. CredentialsFile = "credentials.json" // OAuthClientFile is the post-migration OAuth client JSON filename // (deployment material per §1.2 — not a secret, not in the keyring). OAuthClientFile = "oauth_client.json" // TokenFile is the legacy OAuth token fallback filename. Superseded by // the keyring; retained so the one-time migration can find it. TokenFile = "token.json" // ConfigFile is the legacy JSON config filename, read once for // transparent upgrade to ConfigFileYAML. ConfigFile = "config.json" // ConfigFileYAML is the authoritative config filename. ConfigFileYAML = "config.yml" // DefaultCredentialRef applies when config.yml is absent or omits // credential_ref. Callers still resolve it via credstore.ParseRef — the // service/profile are never assumed structurally (§1.3). DefaultCredentialRef = "google-readonly/default" // DefaultCacheTTLHours is the default cache TTL in hours. DefaultCacheTTLHours = 24 )
const ( // DirPerm is the permission for config directories (owner rwx only). DirPerm = 0700 // TokenPerm is the permission for the config file (owner rw only). The // config holds no secret, but there is no reason for it to be world // readable. TokenPerm = 0600 // OutputDirPerm is the permission for output directories. OutputDirPerm = 0755 // OutputFilePerm is the permission for output files, and for the OAuth // client JSON (deployment material — non-secret, org-internal). OutputFilePerm = 0644 )
File and directory permission constants for consistent security settings.
Variables ¶
This section is empty.
Functions ¶
func CacheDirPath ¶ added in v1.0.49
CacheDirPath resolves the OS-designated cache directory WITHOUT creating it (used by `config clear --all --dry-run` and tests). os.UserCacheDir gives the canonical per-OS root: Linux $XDG_CACHE_HOME or ~/.cache, macOS ~/Library/Caches, Windows %LocalAppData%. We append only DirName — no platform-specific suffix — to keep all three consistent.
func DefaultOAuthClientPath ¶ added in v1.0.48
DefaultOAuthClientPath is the expanded absolute default for OAuthClientPath: <configdir>/oauth_client.json.
func ExpandPath ¶ added in v1.0.48
ExpandPath resolves a leading ~ and makes the path absolute. Stored config values are always expanded; ~ is for display only (ShortenPath).
func GetCacheDir ¶ added in v1.0.49
GetCacheDir returns the cache directory, creating it if needed.
func GetCacheTTL ¶ added in v1.0.30
GetCacheTTL returns the configured cache TTL duration.
func GetCacheTTLHours ¶ added in v1.0.30
func GetCacheTTLHours() int
GetCacheTTLHours returns the configured cache TTL in hours.
func GetConfigDir ¶
GetConfigDir returns the configuration directory, creating it if needed.
func GetConfigPath ¶ added in v1.0.30
GetConfigPath returns the authoritative config file path (config.yml).
func GetConfigPathNoCreate ¶ added in v1.0.49
GetConfigPathNoCreate is GetConfigPath WITHOUT creating the config dir — for side-effect-free paths such as `config clear --dry-run`.
func GetCredentialsPath ¶
GetCredentialsPath returns the path to the LEGACY credentials.json (deployment material). Used by the one-time migration to relocate it to OAuthClientPath; not the runtime client-JSON source post-migration.
func GetTokenPath ¶
GetTokenPath returns the path to the LEGACY token.json fallback. Used only by the one-time migration into the keyring.
func LegacyCacheDir ¶ added in v1.0.49
LegacyCacheDir resolves the pre-B2b cache directory (a "cache" subdir of the config dir) WITHOUT creating anything — for the one-time relocation only.
func LegacyConfigJSONPath ¶ added in v1.0.48
LegacyConfigJSONPath returns the pre-migration config.json path.
func SaveConfig ¶ added in v1.0.30
SaveConfig writes config.yml at 0600 under a 0700 directory. OAuthClientPath is persisted expanded + absolute so os.ReadFile never sees a literal ~.
func ShortenPath ¶
ShortenPath replaces the home directory prefix with ~ for display, so errors and `config show` do not expose usernames.
Types ¶
type Config ¶ added in v1.0.30
type Config struct {
// CredentialRef is the authoritative <service>/<profile> keyring ref
// (§1.3). Resolved via credstore.ParseRef; never hard-coded.
CredentialRef string `yaml:"credential_ref" json:"credential_ref,omitempty"`
// OAuthClientPath is the absolute path to the OAuth client JSON
// (deployment material). Stored expanded + absolute; `~` is display-only
// via ShortenPath. An org may override the default location here.
OAuthClientPath string `yaml:"oauth_client_path" json:"oauth_client_path,omitempty"`
// CacheTTLHours is preserved pre-existing tuning (not a secret).
CacheTTLHours int `yaml:"cache_ttl_hours" json:"cache_ttl_hours"`
// GrantedScopes is preserved: detects when a token's scopes drift from
// what init granted. Not a secret.
GrantedScopes []string `yaml:"granted_scopes,omitempty" json:"granted_scopes,omitempty"`
// Keyring carries the optional §1.4 explicit file-backend opt-in.
Keyring KeyringConfig `yaml:"keyring,omitempty" json:"-"`
}
Config is google-readonly's config.yml. Everything here is safe for an org to ship via MDM (§1.2); none of it is an access secret. JSON tags are retained so a legacy config.json is read transparently for one upgrade.
func LoadConfig ¶ added in v1.0.30
LoadConfig loads config.yml. If config.yml is absent but a legacy config.json exists, it is read transparently (the user keeps working); the one-time migration rewrites it as config.yml and removes the JSON. An absent config entirely yields defaults. Defaults are always applied.
type KeyringConfig ¶ added in v1.0.48
type KeyringConfig struct {
Backend string `yaml:"backend,omitempty" json:"-"`
}
KeyringConfig is the §1.4 backend selector. Backend == "file" forces the encrypted-file backend; empty means OS default selection (fail-closed on Linux when no Secret Service is available).