ocmo-cli 0.8.19__py3-none-any.whl

ocmo_cli/_client.py

@@ -0,0 +1,351 @@
+"""Client factory — builds an OcmoClient from CLI context.
+
+All SDK imports are deferred so that --help and startup remain fast.
+Supports all OCMO_* environment variables documented in sdk/ocmo/config.py.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ocmo import NamespaceView, OcmoClient
+    from ocmo.config import OcmoConfig
+
+    from ._config import CliConfig, Context
+
+from ._auth_resolve import (
+    apply_resolved_oidc_to_kwargs,
+    resolve_oidc_settings,
+)
+
+
+class OcmoCtx:
+    """CLI runtime context threaded through click.Context.obj."""
+
+    def __init__(
+        self,
+        *,
+        namespace: str | None,
+        output: str | None,
+        dry_run: bool,
+        verbose: bool,
+        quiet: bool,
+        yes: bool,
+        skip_version_check: bool,
+        no_color: bool,
+    ) -> None:
+        self.namespace = namespace
+        self.output = output
+        self.dry_run = dry_run
+        self.verbose = verbose
+        self.quiet = quiet
+        self.yes = yes
+        self.skip_version_check = skip_version_check
+        self.no_color = no_color
+        self._client: OcmoClient | None = None
+
+    def client(self) -> OcmoClient:
+        """Return a cached OcmoClient built from the CLI context and env."""
+        if self._client is None:
+            self._client = _build_client(
+                skip_version_check=self.skip_version_check,
+                verbose=self.verbose,
+            )
+        return self._client
+
+    def ns(self, namespace: str | None = None) -> NamespaceView:
+        """Return a NamespaceView for the effective namespace."""
+        ns = namespace or self.namespace or _resolve_namespace()
+        if not ns:
+            _abort_missing_namespace()
+        return self.client().ns(ns)
+
+    def require_namespace(self, namespace: str | None = None) -> str:
+        ns = namespace or self.namespace or _resolve_namespace()
+        if not ns:
+            _abort_missing_namespace()
+        assert ns is not None
+        return ns
+
+    def namespace_view(self, namespace: str | None = None) -> NamespaceView:
+        """Return a NamespaceView for the effective namespace."""
+        return self.ns(self.require_namespace(namespace))
+
+
+def _resolve_namespace() -> str | None:
+    # 1. Environment variable (SDK layer handles this too, but check here for CLI error message)
+    env = os.environ.get("OCMO_NAMESPACE")
+    if env:
+        return env
+    # 2. Config file context
+    try:
+        from ._config import load_config  # deferred
+
+        cfg = load_config()
+        return cfg.namespace() or None
+    except Exception:
+        return None
+
+
+def _fetch_oidc_from_server(server: str | None) -> dict[str, str]:
+    """Return public OIDC hints from the API ``/api/version`` endpoint."""
+    if not server:
+        return {}
+    try:
+        import httpx  # deferred
+
+        url = server.rstrip("/") + "/api/version"
+        resp = httpx.get(url, timeout=5.0)
+        resp.raise_for_status()
+        oidc = (resp.json().get("auth") or {}).get("oidc") or {}
+        return {k: str(v) for k, v in oidc.items() if v is not None}
+    except Exception:
+        return {}
+
+
+def _fetch_oidc_scopes_from_server(server: str | None) -> str | None:
+    """Return OIDC scopes advertised by the API (unauthenticated /version)."""
+    scopes = _fetch_oidc_from_server(server).get("scopes")
+    return scopes if scopes else None
+
+
+def _build_client(*, skip_version_check: bool, verbose: bool) -> OcmoClient:
+    """Build an OcmoClient with all config options from env + CLI config file."""
+    from ocmo import OcmoClient  # deferred
+
+    if verbose:
+        import logging
+
+        logging.basicConfig(level=logging.DEBUG)
+
+    return OcmoClient(config=build_ocmo_config(skip_version_check=skip_version_check))
+
+
+def _uses_token_auth(cfg: CliConfig | None = None, ctx: Context | None = None) -> bool:
+    """True when auth should use OCMO_TOKEN / token file (resolver or bearer)."""
+    if os.environ.get("OCMO_AUTH_MODE") in ("resolver-token", "bearer"):
+        return True
+    if os.environ.get("OCMO_TOKEN") or os.environ.get("OCMO_TOKEN_FILE"):
+        return True
+    try:
+        if cfg is None:
+            cfg = _load_cli_config()
+        if ctx is None:
+            ctx_name = _resolve_context_name(cfg, None)
+            ctx = cfg.contexts.get(ctx_name) if ctx_name else cfg.active_context()
+        if ctx is None:
+            return False
+        if ctx.token_file:
+            return True
+        if not ctx.auth:
+            return False
+        entry = cfg.auths.get(ctx.auth)
+        return bool(entry and (entry.token or entry.token_file))
+    except Exception:
+        return False
+
+
+def build_ocmo_config(
+    *,
+    skip_version_check: bool = False,
+    context_name: str | None = None,
+    validate_auth: bool = True,
+) -> OcmoConfig:
+    """Build OcmoConfig from environment variables and the CLI config file."""
+    from ocmo.config import OcmoConfig  # deferred
+
+    cfg = _load_cli_config()
+    ctx_name = _resolve_context_name(cfg, context_name)
+    ctx = cfg.contexts.get(ctx_name) if ctx_name else None
+
+    server = os.environ.get("OCMO_SERVER") or (ctx.server if ctx else None) or cfg.server()
+    if server:
+        os.environ.setdefault("OCMO_SERVER", server)
+
+    file_auth = _auth_kwargs_from_context(cfg, ctx)
+    token_auth = _uses_token_auth(cfg, ctx)
+    auth_profile = ctx.auth if ctx and ctx.auth else None
+
+    if token_auth:
+        file_auth = {k: v for k, v in file_auth.items() if k in ("token", "token_file")}
+    else:
+        oidc_hints = _fetch_oidc_from_server(server) if server else {}
+        entry = cfg.auths.get(ctx.auth) if ctx and ctx.auth else None
+        if entry and entry.mode == "oidc" and not (entry.token or entry.token_file):
+            resolved = resolve_oidc_settings(
+                server=server,
+                entry=entry,
+                fetch_server_oidc=_fetch_oidc_from_server,
+            )
+            apply_resolved_oidc_to_kwargs(file_auth, resolved)
+        if not os.environ.get("OCMO_OIDC_SCOPE") and file_auth.get("oidc_scope") is None:
+            scopes = oidc_hints.get("scopes")
+            if scopes:
+                file_auth["oidc_scope"] = scopes
+
+    auth_kwargs = {k: v for k, v in file_auth.items() if v is not None}
+    sdk_cfg = OcmoConfig.from_env(
+        skip_version_check=skip_version_check if skip_version_check else None,
+        oidc_cache_profile=auth_profile,
+        oidc_issuer=auth_kwargs.get("oidc_issuer"),
+        client_id=auth_kwargs.get("client_id"),
+        client_secret=auth_kwargs.get("client_secret"),
+        client_secret_file=auth_kwargs.get("client_secret_file"),
+        token=auth_kwargs.get("token"),
+        token_file=auth_kwargs.get("token_file"),
+        oidc_scope=auth_kwargs.get("oidc_scope"),
+    )
+    if validate_auth:
+        _validate_cli_auth(cfg, ctx, sdk_cfg)
+    return sdk_cfg
+
+
+def _load_cli_config() -> CliConfig:
+    from ._config import load_config
+
+    return load_config()
+
+
+def _resolve_context_name(cfg: CliConfig, explicit: str | None = None) -> str | None:
+    return explicit or os.environ.get("OCMO_CONTEXT") or cfg.current_context or None
+
+
+def _validate_cli_auth(cfg: CliConfig, ctx: Context | None, sdk_cfg: OcmoConfig) -> None:
+    """Require explicit auth configuration before API calls."""
+    from ocmo.errors import OcmoConfigError  # deferred
+
+    if sdk_cfg.auth_mode in ("resolver-token", "bearer"):
+        return
+    if sdk_cfg.token:
+        return
+    if ctx and ctx.token_file:
+        return
+
+    env_oidc = bool(os.environ.get("OCMO_CLIENT_ID") and os.environ.get("OCMO_OIDC_ISSUER"))
+    if env_oidc:
+        return
+
+    auth_name = ctx.auth if ctx else None
+    if not auth_name:
+        raise OcmoConfigError(_missing_auth_message(cfg, ctx, reason="no_auth_reference"))
+
+    entry = cfg.auths.get(auth_name)
+    if entry is None:
+        raise OcmoConfigError(_missing_auth_message(cfg, ctx, reason="missing_auth_entry"))
+
+    if entry.token or entry.token_file:
+        return
+
+    if entry.mode != "oidc":
+        raise OcmoConfigError(f"auths.{auth_name} uses unsupported mode {entry.mode!r}; expected 'oidc'.")
+
+    if not sdk_cfg.client_id or not sdk_cfg.oidc_issuer:
+        raise OcmoConfigError(_missing_auth_message(cfg, ctx, reason="incomplete_auth_entry"))
+
+
+def _missing_auth_message(cfg: CliConfig, ctx: Context | None, *, reason: str) -> str:
+    from ._config import _config_path
+
+    config_path = _config_path()
+    ctx_name = ctx and _resolve_context_name(cfg, None)
+    auth_name = ctx.auth if ctx else None
+    lines = [
+        "Authentication is not configured for the active context.",
+        "",
+        "Define an auths: entry in the config file and reference it from the context:",
+        "  auths:",
+        f"    {auth_name or 'my-oidc'}:",
+        "      mode: oidc",
+        "      # issuer / client_id optional — env, /api/version, or:",
+        "      # issuer: https://sso.example.com",
+        "      # client_id: ocmo-cli",
+        "  contexts:",
+        f"    {ctx_name or 'default'}:",
+        f"      auth: {auth_name or 'my-oidc'}",
+        "",
+        "Or set environment variables:",
+        "  OCMO_OIDC_ISSUER, OCMO_CLIENT_ID",
+        "  OCMO_CLIENT_SECRET (when required)",
+        "",
+        f"Config file: {config_path}",
+    ]
+    if reason == "missing_auth_entry" and auth_name:
+        lines.insert(2, f"Context {ctx_name!r} references auth {auth_name!r}, but auths.{auth_name} is missing.")
+    elif reason == "no_auth_reference" and ctx_name:
+        lines.insert(2, f"Context {ctx_name!r} has no auth: field.")
+    elif reason == "incomplete_auth_entry" and auth_name:
+        lines.insert(
+            2,
+            f"Could not resolve OIDC issuer and client_id for auths.{auth_name} "
+            "(set them in the config, OCMO_OIDC_ISSUER/OCMO_CLIENT_ID, or ensure "
+            "the context server exposes them via /api/version).",
+        )
+    return "\n".join(lines)
+
+
+def _auth_kwargs_from_context(cfg: CliConfig, ctx: Context | None) -> dict[str, str | None]:
+    """Merge auth settings from a specific context when env is unset."""
+    if not ctx:
+        return {}
+
+    kwargs: dict[str, str | None] = {}
+
+    if ctx.token_file and not os.environ.get("OCMO_TOKEN") and not os.environ.get("OCMO_TOKEN_FILE"):
+        kwargs["token_file"] = ctx.token_file
+
+    auth_name = ctx.auth
+    if not auth_name:
+        return kwargs
+
+    entry = cfg.auths.get(auth_name)
+    if not entry:
+        return kwargs
+
+    def _set(env_var: str, config_key: str, value: str | None) -> None:
+        if value and not os.environ.get(env_var):
+            kwargs[config_key] = value
+
+    _set("OCMO_OIDC_ISSUER", "oidc_issuer", entry.issuer or None)
+    _set("OCMO_CLIENT_ID", "client_id", entry.client_id or None)
+    _set("OCMO_CLIENT_SECRET", "client_secret", entry.client_secret or None)
+    _set("OCMO_CLIENT_SECRET_FILE", "client_secret_file", entry.client_secret_file or None)
+    _set("OCMO_TOKEN", "token", entry.token or None)
+    _set("OCMO_TOKEN_FILE", "token_file", entry.token_file or None)
+
+    return kwargs
+
+
+def _auth_kwargs_from_config() -> dict[str, str | None]:
+    """Merge auth settings from the active CLI context when env is unset."""
+    try:
+        cfg = _load_cli_config()
+    except Exception:
+        return {}
+    ctx_name = _resolve_context_name(cfg, None)
+    ctx = cfg.contexts.get(ctx_name) if ctx_name else cfg.active_context()
+    return _auth_kwargs_from_context(cfg, ctx)
+
+
+def _server_from_config() -> str | None:
+    """Read server URL from the config file context."""
+    try:
+        from ._config import load_config
+
+        cfg = load_config()
+        return cfg.server() or None
+    except Exception:
+        return None
+
+
+def _abort_missing_namespace() -> None:
+    print(
+        "Error: namespace is required. Specify it via:\n"
+        "  -n / --namespace flag\n"
+        "  OCMO_NAMESPACE environment variable\n"
+        "  current context in the config file (ocmo config set namespace <ns>)",
+        file=sys.stderr,
+    )
+    raise SystemExit(2)

ocmo_cli/_client_commands.py

@@ -0,0 +1,35 @@
+"""Factory for thin client-scoped commands (whoami, api-health, etc.)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from ._client import OcmoCtx
+from ._errors import sdk_command
+from ._options import output_option
+from ._output import as_dict
+from ._output_manifest import emit_command_output
+
+
+def client_command(
+    name: str,
+    *,
+    help: str,
+    manifest_key: str,
+    method: str,
+) -> click.Command:
+    """Build a command that calls a client method and emits manifest output."""
+
+    @click.command(name, help=help)
+    @output_option(manifest_key)
+    @click.pass_obj
+    @sdk_command
+    def cmd(ctx: OcmoCtx, output_fmt: str | None) -> None:
+        fetch: Callable[[], Any] = getattr(ctx.client(), method)
+        data = as_dict(fetch())
+        emit_command_output(manifest_key, data, output_fmt, ctx_fmt=ctx.output)
+
+    return cmd

ocmo_cli/_command_registry.py

@@ -0,0 +1,29 @@
+"""Startup-safe short help for hand-written CLI commands."""
+
+from __future__ import annotations
+
+HAND_WRITTEN_SHORT_HELP: dict[str, tuple[str, str, str]] = {
+    "auth": ("auth", "auth_group", "Authenticate with the OCMO server."),
+    "config": ("config_cmd", "config_group", "Manage local CLI configuration (server, contexts, auth)."),
+    "describe": ("describe", "describe_cmd", "Read or set the Markdown description of a tree item."),
+    "resolve": ("resolve", "resolve_group", "Resolve a config or folder to its final value(s)."),
+    "export": ("export", "export_cmd", "Export a subtree to disk, preserving tree structure."),
+    "import": ("import_", "import_cmd", "Import a directory tree into OCMO."),
+    "apply": ("apply", "apply_cmd", "Create or update a tree item from a local file."),
+    "edit": ("edit", "edit_group", "Open a tree item in $EDITOR and update it on save."),
+    "ls": ("ls", "ls_cmd", "List the direct children of a tree path, or the namespace root when ADDRESS is omitted."),
+    "tree": ("ls", "tree_cmd", "Render the subtree under a path in tree format."),
+    "diff": ("diff", "diff_cmd", "Show a unified diff between two versions or two items."),
+    "schema": ("schema", "schema_cmd", "Render the JSON Schema for a resource type."),
+    "version": ("version_cmd", "version_cmd", "Print CLI, SDK, and server versions with a compatibility verdict."),
+    "whoami": ("whoami", "whoami_cmd", "Show the identity of the current authenticated principal."),
+    "can-i": ("can_i", "can_i_cmd", "Check whether the current principal may perform one or more operations."),
+    "api-health": (
+        "api_health",
+        "api_health_cmd",
+        "Check API dependency health (database, cache, and related backends).",
+    ),
+    "completion": ("completion", "completion_cmd", "Emit a shell completion script."),
+    "timeline": ("timeline", "timeline_group", "Item-scoped audit timelines."),
+    "resolve-series": ("resolve_series", "resolve_series_group", "Resolve statistics over time."),
+}

ocmo_cli/_commands_map.py

@@ -0,0 +1,65 @@
+# AUTO-GENERATED by scripts/generate_commands.py — do not edit.
+# Run: uv run python scripts/generate_commands.py --write
+
+from __future__ import annotations
+
+from typing import Any
+
+OPERATIONS: dict[str, dict[str, Any]] = {
+    "health": {"hand_written": True},
+    "version": {"hand_written": True},
+    "whoami": {"hand_written": True},
+    "can_i": {"hand_written": True},
+    "list_namespaces": {"action": "get", "resource": "namespace"},
+    "show_namespace": {"action": "get", "resource": "namespace"},
+    "create_namespace": {"action": "create", "resource": "namespace"},
+    "update_namespace": {"action": "update", "resource": "namespace"},
+    "delete_namespace": {"action": "delete", "resource": "namespace", "confirm": "destructive"},
+    "navigate_root": {"hand_written": True},
+    "navigate_path": {"hand_written": True},
+    "search_root": {"action": "search", "resource": "tree"},
+    "search_path": {"action": "search", "resource": "tree"},
+    "list_item_versions": {"action": "get", "resource": "version"},
+    "get_item": {"action": "get", "resource": "item"},
+    "diff_item": {"hand_written": True},
+    "delete_item": {"action": "delete", "resource": "item", "confirm": "destructive"},
+    "move_item": {"hand_written": True, "action": "move", "resource": "item"},
+    "copy_item": {"hand_written": True, "action": "copy", "resource": "item"},
+    "set_tag": {"action": "tag", "resource": "item"},
+    "describe_item": {"hand_written": True},
+    "get_config_metadata_schema": {"hand_written": True},
+    "get_config_data_schema": {"hand_written": True},
+    "create_config": {"action": "create", "resource": "config"},
+    "update_config": {"action": "update", "resource": "config"},
+    "create_template": {"action": "create", "resource": "template"},
+    "update_template": {"action": "update", "resource": "template"},
+    "create_secret": {"action": "create", "resource": "secret", "confirm": "sensitive"},
+    "update_secret": {"action": "update", "resource": "secret", "confirm": "sensitive"},
+    "get_resolver_configuration_schema": {"hand_written": True},
+    "create_resolver": {"action": "create", "resource": "resolver"},
+    "update_resolver": {"action": "update", "resource": "resolver"},
+    "rotate_resolver_token": {"action": "rotate", "resource": "token", "confirm": "destructive"},
+    "list_cast_formats": {"action": "get", "resource": "cast"},
+    "download_resolved_artifact": {"skip": "Internal SDK operation; surfaced via `ocmo resolve`."},
+    "resolve_config": {"hand_written": True},
+    "resolve_parameters": {"hand_written": True, "action": "resolve", "resource": "parameters"},
+    "resolve_draft_config": {"hand_written": True, "action": "resolve", "resource": "draft"},
+    "list_global_permissions": {"action": "get", "resource": "globalpermission"},
+    "create_global_permission": {"action": "create", "resource": "globalpermission"},
+    "get_global_permission": {"action": "get", "resource": "globalpermission"},
+    "update_global_permission": {"action": "update", "resource": "globalpermission"},
+    "delete_global_permission": {"action": "delete", "resource": "globalpermission", "confirm": "destructive"},
+    "move_global_permission": {"hand_written": True, "action": "move", "resource": "globalpermission"},
+    "list_global_audit": {"action": "get", "resource": "audit"},
+    "get_global_audit_event": {"action": "get", "resource": "audit"},
+    "list_namespace_audit": {"action": "get", "resource": "audit"},
+    "get_namespace_audit_event": {"action": "get", "resource": "audit"},
+    "namespace_audit_timeline": {"hand_written": True},
+    "namespace_audit_resolve_series": {"hand_written": True},
+    "list_locks": {"action": "get", "resource": "lock"},
+    "get_lock": {"action": "get", "resource": "lock"},
+    "create_lock": {"action": "create", "resource": "lock"},
+    "replace_lock": {"action": "update", "resource": "lock"},
+    "delete_lock": {"action": "delete", "resource": "lock", "confirm": "destructive"},
+    "propagate_config": {"action": "propagate", "resource": "config"},
+}

ocmo_cli/_config.py

@@ -0,0 +1,183 @@
+"""Local CLI configuration file — kubeconfig-shaped YAML.
+
+Precedence (highest first):
+  command flag > OCMO_* env var > current context in config file > built-in default.
+
+File lives at $OCMO_CONFIG or $XDG_CONFIG_HOME/ocmo/config.yaml (default).
+Created 0600 in a 0700 directory. Refusing to read world-readable files that
+contain inline credentials.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+def _config_path() -> Path:
+    env = os.environ.get("OCMO_CONFIG")
+    if env:
+        return Path(env)
+    xdg = os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config")
+    return Path(xdg) / "ocmo" / "config.yaml"
+
+
+def format_config_path_note() -> str:
+    """Human-readable config file path for help text and command output."""
+    path = _config_path()
+    note = "" if path.exists() else " (not created yet)"
+    return f"Config file: {path}{note}"
+
+
+@dataclass
+class AuthEntry:
+    mode: str = "oidc"
+    issuer: str = ""
+    client_id: str = ""
+    client_secret: str = ""
+    client_secret_file: str = ""
+    token: str = ""
+    token_file: str = ""
+
+    def has_inline_secret(self) -> bool:
+        return bool(self.client_secret or self.token)
+
+
+@dataclass
+class Context:
+    server: str = ""
+    namespace: str = ""
+    auth: str = ""
+    token_file: str = ""
+
+
+@dataclass
+class CliConfig:
+    current_context: str = ""
+    contexts: dict[str, Context] = field(default_factory=dict)
+    auths: dict[str, AuthEntry] = field(default_factory=dict)
+
+    def active_context(self) -> Context | None:
+        name = os.environ.get("OCMO_CONTEXT") or self.current_context
+        return self.contexts.get(name)
+
+    def server(self) -> str:
+        env = os.environ.get("OCMO_SERVER")
+        if env:
+            return env
+        ctx = self.active_context()
+        return ctx.server if ctx else ""
+
+    def namespace(self) -> str:
+        env = os.environ.get("OCMO_NAMESPACE")
+        if env:
+            return env
+        ctx = self.active_context()
+        return ctx.namespace if ctx else ""
+
+
+def load_config() -> CliConfig:
+    """Load the config file if it exists; return an empty config otherwise."""
+    import yaml  # deferred
+
+    path = _config_path()
+    if not path.exists():
+        return CliConfig()
+
+    _check_permissions(path)
+
+    with path.open() as f:
+        raw: dict[str, Any] = yaml.safe_load(f) or {}
+
+    cfg = CliConfig(current_context=raw.get("current-context", ""))
+
+    for name, ctx_raw in (raw.get("contexts") or {}).items():
+        cfg.contexts[name] = Context(
+            server=ctx_raw.get("server", ""),
+            namespace=ctx_raw.get("namespace", ""),
+            auth=ctx_raw.get("auth", ""),
+            token_file=ctx_raw.get("token-file", ""),
+        )
+
+    for name, auth_raw in (raw.get("auths") or {}).items():
+        entry = AuthEntry(
+            mode=auth_raw.get("mode", "oidc"),
+            issuer=auth_raw.get("issuer", ""),
+            client_id=auth_raw.get("client_id", ""),
+            client_secret=auth_raw.get("client_secret", ""),
+            client_secret_file=auth_raw.get("client_secret_file", ""),
+            token=auth_raw.get("token", ""),
+            token_file=auth_raw.get("token_file", ""),
+        )
+        if entry.has_inline_secret():
+            print(
+                f"Warning: auth '{name}' contains an inline credential. "
+                "Consider using the *_file variant, a keyring, or an environment variable.",
+                file=sys.stderr,
+            )
+        cfg.auths[name] = entry
+
+    return cfg
+
+
+def save_config(cfg: CliConfig) -> None:
+    """Write config to disk with 0600/0700 permissions."""
+    import yaml  # deferred
+
+    path = _config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+
+    raw: dict[str, Any] = {}
+    if cfg.current_context:
+        raw["current-context"] = cfg.current_context
+    if cfg.contexts:
+        raw["contexts"] = {name: _ctx_to_dict(ctx) for name, ctx in cfg.contexts.items()}
+    if cfg.auths:
+        raw["auths"] = {name: _auth_to_dict(auth) for name, auth in cfg.auths.items()}
+
+    with path.open("w") as f:
+        yaml.safe_dump(raw, f, default_flow_style=False)
+    os.chmod(path, 0o600)
+
+
+def _ctx_to_dict(ctx: Context) -> dict[str, Any]:
+    d: dict[str, Any] = {}
+    if ctx.server:
+        d["server"] = ctx.server
+    if ctx.namespace:
+        d["namespace"] = ctx.namespace
+    if ctx.auth:
+        d["auth"] = ctx.auth
+    if ctx.token_file:
+        d["token-file"] = ctx.token_file
+    return d
+
+
+def _auth_to_dict(auth: AuthEntry) -> dict[str, Any]:
+    d: dict[str, Any] = {"mode": auth.mode}
+    for k in ("issuer", "client_id", "client_secret", "client_secret_file", "token", "token_file"):
+        v = getattr(auth, k)
+        if v:
+            d[k] = v
+    return d
+
+
+def _check_permissions(path: Path) -> None:
+    """Refuse to read a world-readable config that contains credentials."""
+    try:
+        mode = path.stat().st_mode
+    except OSError:
+        return
+    if mode & stat.S_IROTH:
+        # World-readable: read but warn unless no credentials present
+        print(
+            f"Warning: config file {path} is world-readable. "
+            "This is a security risk if it contains credentials. "
+            "Run: chmod 600 " + str(path),
+            file=sys.stderr,
+        )