authkeys 0.4.0__py3-none-any.whl

authkeys/__init__.py

@@ -0,0 +1,382 @@
+"""authkeys: pluggable ``AuthorizedKeysCommand`` provider for OpenSSH.
+
+Resolves a user's authorized SSH keys from one or more configured *sources*
+(local files, an HTTP endpoint, LDAP certificates, ...), with optional TTL
+caching and user/group aliasing. Designed to be driven either from the CLI as an
+``AuthorizedKeysCommand`` or as a long-running key server (``authkeys serve``).
+"""
+
+import re
+import threading
+from configparser import SectionProxy
+from dataclasses import dataclass
+from typing import Callable, Dict, Iterable, List, NamedTuple, Optional, Union
+
+from duho import logging
+
+from . import groupmembers, usermaps, utils
+from .cache import AuthKeysCache, AuthKeysCacheBackend
+from .config import AuthkeysConfig
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("authkeys")
+except Exception:  # not installed (bare source checkout)
+    __version__ = "0+unknown"
+
+LOGGER = logging.getLogger("authkeys")
+
+
+# A recognized `authorized_keys` key-type token (prefix or exact set), per the
+# OpenSSH manual: ssh-rsa/ssh-dss/ssh-ed25519(-sk)/sk-ssh-ed25519@openssh.com/
+# ecdsa-sha2-*/sk-ecdsa-sha2-*, and their `*-cert-v01@openssh.com` cert variants.
+# Anything else as the first token (or any token containing `=`, i.e. an
+# options list like `command="...",no-pty`) is an options prefix, not a type.
+_KEY_TYPE_RE = re.compile(r"^(ssh-|ecdsa-|sk-)")
+
+
+def _is_options_prefix(token: str) -> bool:
+    return "=" in token or not _KEY_TYPE_RE.match(token)
+
+
+class AuthorizedKey(NamedTuple):
+    type: str
+    key: str
+    comment: str
+    options: str = ""
+
+    def __repr__(self) -> str:
+        base = f"{self.type} {self.key} {self.comment}" if self.comment else f"{self.type} {self.key}"
+        if self.options:
+            return f"{self.options} {base}"
+        return base
+
+    @classmethod
+    def parse(cls, authorized_key: str, comment: "Optional[str]" = None) -> "AuthorizedKey":
+        options = ""
+        first, _, rest = authorized_key.partition(" ")
+        if first and _is_options_prefix(first):
+            options = first
+            authorized_key = rest
+        parts = authorized_key.split(" ", maxsplit=2)
+        if len(parts) < 2:
+            raise ValueError(authorized_key)
+        if len(parts) == 3 and comment is None:
+            comment = parts[2]
+        return cls(parts[0], parts[1], comment or "", options)
+
+    @classmethod
+    def parse_all(
+        cls, keys: "Union[str, Iterable[Union[AuthorizedKey, str]], None]"
+    ) -> "Iterable[AuthorizedKey]":
+        keys = keys or ""
+        if isinstance(keys, str):
+            keys = keys.splitlines()
+        for key in keys:
+            if isinstance(key, str):
+                key = key.strip()
+                if not key or key.startswith("#"):
+                    continue
+                key = cls.parse(key)
+            if key:
+                yield key
+
+
+class AuthkeysSource:
+    """Base class for key sources. Subclasses yield raw ``authorized_keys`` lines."""
+
+    def __init__(self, conf: SectionProxy, globals: dict) -> None:
+        pass
+
+    def authorized_keys(self, username: str) -> Iterable[str]:
+        return ()
+
+
+Usermap = Callable[[str, str, "Source"], str]
+Sanitizer = Callable[[str, str, AuthorizedKey], "Optional[AuthorizedKey]"]
+
+
+class UserConfig:
+    authorized_users: "List[str]"
+    authorized_groups: "List[str]"
+
+    def __init__(self, authorized_users=None, authorized_groups=None) -> None:
+        self.authorized_users = authorized_users or []
+        self.authorized_groups = authorized_groups or []
+
+
+def default_sanitize(src: str, uid: str, key: AuthorizedKey) -> AuthorizedKey:
+    if not key.comment:
+        key = key._replace(comment=f"{uid}(src={src})")
+    return key
+
+
+@dataclass
+class Source:
+    cached: bool
+    enabled: bool
+    backend: "Optional[AuthkeysSource]"
+    sanitize: "Optional[Sanitizer]"
+    expire: "Optional[int]"  # per-source TTL override; None => use [cache] expire
+
+    @classmethod
+    def from_config(
+        cls, config: SectionProxy, globals: dict, defaults: "Source"
+    ) -> "Source":
+        cached = config.getboolean("cached", defaults.cached)
+        enabled = config.getboolean("enabled", defaults.enabled)
+        backend = config.get("backend")
+        sanitize = config.get("sanitize")
+        if enabled and backend:
+            backend = utils.call(backend, config, globals)
+        if isinstance(sanitize, str):
+            sanitize = utils.import_module_object(sanitize)
+        elif sanitize is None:
+            sanitize = defaults.sanitize
+        expire = config.get("expire")
+        try:
+            expire = int(expire) if expire is not None else None
+        except (TypeError, ValueError):
+            LOGGER.error(f"Invalid source 'expire' {expire!r}; using [cache] expire")
+            expire = None
+        return cls(
+            cached=cached,
+            enabled=enabled,
+            backend=backend,
+            sanitize=sanitize,
+            expire=expire,
+        )
+
+
+class AuthKeys:
+    def __init__(self) -> None:
+        self.globals: dict = {}
+        self.sources: "Dict[str, Source]" = {}
+        self.usermap: Usermap = usermaps.none
+        self.users: "Dict[str, UserConfig]" = {}
+        self.cache: "Optional[AuthKeysCache]" = None
+        self.use_expired_on_error = False
+        self.groupmembers = groupmembers.system_groupmembers
+        self.source_defaults = Source(
+            cached=True,
+            enabled=True,
+            backend=None,
+            sanitize=default_sanitize,
+            expire=None,
+        )
+        # Guards the per-(uid, source) cache miss -> compute -> store section so
+        # the threaded key server (ThreadingHTTPServer) doesn't race on the
+        # shared cache backend (esp. the file backend's read/write).
+        self._lock = threading.RLock()
+
+    def load_config(self, config: AuthkeysConfig) -> None:
+        for section in config.sections():
+            if not section.startswith("source:"):
+                continue
+            name = section[len("source:"):]
+            src_config = config[section]
+            LOGGER.info(f"Registering source {name}")
+            self.sources[name] = Source.from_config(
+                src_config, self.globals, self.source_defaults
+            )
+
+        self.usermap = utils.import_module_object(
+            config["globals"].get("usermap") or "authkeys.usermaps.none"
+        )
+        self.groupmembers = utils.import_module_object(
+            config["globals"].get("groupmembers")
+            or "authkeys.groupmembers.system_groupmembers"
+        )
+
+        cache_conf = config["cache"]
+        cache_backend = utils.import_module_object(
+            cache_conf.get("backend") or "authkeys.cache.AuthKeysCacheMemBackend"
+        )
+        # Parse the TTL independently: a malformed `expire` should fall back to
+        # the default, not disable caching entirely (and not mask a genuine
+        # backend construction error below).
+        try:
+            ttl = int(cache_conf.get("expire", 300))
+        except (TypeError, ValueError):
+            LOGGER.error(
+                f"Invalid cache 'expire' value {cache_conf.get('expire')!r}; "
+                f"falling back to default TTL 300"
+            )
+            ttl = 300
+        neg_raw = cache_conf.get("negative_expire")
+        try:
+            negative_ttl = int(neg_raw) if neg_raw is not None else None
+        except (TypeError, ValueError):
+            LOGGER.error(f"Invalid 'negative_expire' {neg_raw!r}; using expire")
+            negative_ttl = None
+        try:
+            self.cache = AuthKeysCache(
+                backend=cache_backend.from_config(cache_conf),
+                ttl=ttl,
+                negative_ttl=negative_ttl,
+            )
+        except Exception as e:
+            LOGGER.error(f"Could not load cache due to\n{e}")
+            self.cache = None
+
+        self.use_expired_on_error = utils.parse_bool(
+            cache_conf.get("expired_on_error")
+        )
+
+    def user_config_path(self, username: str):
+        """Return a user's ``~/.ssh/authkeys.conf`` path, or None if unknown.
+
+        POSIX-only (uses ``pwd``); returns None when the user has no local
+        account, so the caller can fall back to resolving the literal username.
+        """
+        from pathlib import Path
+
+        from . import config as _config
+
+        try:
+            user = utils.get_user(username)
+        except Exception:
+            return None
+        return Path(user.pw_dir) / _config.USER_CONF_PATH
+
+    def resolve(
+        self, username: str, *, load_delegation: bool = True
+    ) -> "List[AuthorizedKey]":
+        """Load per-user delegation (if any) and resolve keys.
+
+        Used by both the CLI and the HTTP server so ``[authorized]``
+        user/group delegation behaves identically for each. Only the shared
+        ``self.users`` mutation in ``load_user_config`` is done under the lock;
+        the resolution (which may fetch from a slow upstream) runs OUTSIDE it so
+        one hung source can't stall concurrent requests. Returns a
+        fully-materialized list.
+        """
+        if load_delegation:
+            path = self.user_config_path(username)
+            try:
+                user_conf = AuthkeysConfig.from_config(path) if path else None
+                if user_conf is not None:
+                    with self._lock:
+                        self.load_user_config(username, user_conf)
+            except Exception as e:
+                LOGGER.error(
+                    f"Could not load delegation config for {username}: {e}"
+                )
+        return list(self.authorized_keys(username))
+
+    def load_user_config(self, username: str, parser: AuthkeysConfig) -> None:
+        config = UserConfig()
+        authorized = parser["authorized"] if parser.has_section("authorized") else None
+        groups = authorized.getlist("groups", []) if authorized else []
+        if not authorized or "users" not in authorized:
+            config.authorized_users = [username]
+        else:
+            config.authorized_users = authorized.getlist("users", [])
+        config.authorized_groups = list(groups)
+        LOGGER.info(f"Authorized Users: {config.authorized_users}")
+        LOGGER.info(f"Authorized Groups: {groups}")
+        for groupname in groups:
+            try:
+                members = self.groupmembers(groupname, self.globals)
+            except Exception as e:
+                LOGGER.error(f"Could not resolve group '{groupname}': {e}")
+                continue
+            LOGGER.info(f"{groupname}: {members}")
+            for usr in members:
+                if usr not in config.authorized_users:
+                    config.authorized_users.append(usr)
+
+        self.users[username] = config
+
+    def _parse_source_lines(
+        self, src_name: str, uid: str, raw_lines: "Iterable[str]", sanitize
+    ) -> "List[AuthorizedKey]":
+        """Parse raw source lines into keys, skipping (not aborting on) bad ones.
+
+        A single malformed line must not discard the whole source's keys, so each
+        line is parsed defensively -- a ``ValueError`` on one line is logged and
+        skipped and parsing continues.
+        """
+        keys: "List[AuthorizedKey]" = []
+        for raw in raw_lines:
+            for line in (raw.splitlines() if isinstance(raw, str) else [raw]):
+                try:
+                    parsed = list(AuthorizedKey.parse_all(line))
+                except ValueError as e:
+                    LOGGER.warning(
+                        f"Skipping malformed key line from {src_name} for {uid}: {e}"
+                    )
+                    continue
+                for key in parsed:
+                    if sanitize:
+                        key = sanitize(src_name, uid, key)
+                        if not key:
+                            continue
+                    keys.append(key)
+        return keys
+
+    def _resolve_source_user(
+        self, src_name: str, src: "Source", usr: str, uid: str
+    ) -> "List[AuthorizedKey]":
+        """Resolve one source for one user, with the cache guarded by ``self._lock``.
+
+        The lock guards only the cache read and write -- NOT the upstream fetch --
+        so one slow/hung source cannot stall other users' logins (esp. concurrent
+        ``serve`` requests). Two threads may fetch a cold key concurrently; that is
+        correctness-safe (last write wins). Returns a fully-materialized list; the
+        caller yields outside any lock.
+        """
+        cache_key = (uid, src_name)
+        src_ttl = getattr(src, "expire", None)
+        if self.cache and src.cached:
+            with self._lock:
+                cached = self.cache.get(cache_key, ttl=src_ttl)
+            if cached is not None:
+                LOGGER.info(f"Using cached source: {src_name} for {usr} -> {uid}")
+                return list(AuthorizedKey.parse_all(cached))
+
+        try:
+            LOGGER.info(f"Using source: {src_name} for {usr} -> {uid}")
+            keys = self._parse_source_lines(
+                src_name, uid, src.backend.authorized_keys(uid), src.sanitize
+            )
+            if self.cache and src.cached:
+                with self._lock:
+                    self.cache[cache_key] = "\n".join(str(k) for k in keys)
+            return keys
+        except Exception as e:
+            LOGGER.error(
+                f"Error while loading keys for {usr} from {src_name}\n{e}"
+            )
+            if self.use_expired_on_error and self.cache:
+                with self._lock:
+                    expired = self.cache.get(cache_key, include_expired=True)
+                if expired:
+                    LOGGER.warning(
+                        f"Falling back to expired keys for {src_name}: "
+                        f"{usr} -> {uid}"
+                    )
+                    return list(AuthorizedKey.parse_all(expired))
+            return []
+
+    def authorized_keys(self, username: str) -> "Iterable[AuthorizedKey]":
+        usr_config = self.users.get(username) or UserConfig([username])
+        # Dedup on (options, type, key) -- NOT the whole tuple -- so the same
+        # public key coming from two sources (with different per-source
+        # comments) is emitted once, keeping the first comment seen. An
+        # option-bearing key (e.g. `command="...",no-pty ssh-rsa AAAA`) is
+        # kept distinct from the bare form of the same key, since the options
+        # materially change what the key is allowed to do.
+        seen: "set" = set()
+
+        for src_name, src in self.sources.items():
+            if not src.enabled or src.backend is None:
+                continue
+            for usr in usr_config.authorized_users:
+                uid = self.usermap(usr, src_name, src)
+                for key in self._resolve_source_user(src_name, src, usr, uid):
+                    identity = (key.options, key.type, key.key)
+                    if identity not in seen:
+                        seen.add(identity)
+                        yield key

authkeys/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m authkeys`` entry point.
+
+If no subcommand is given, ``resolve`` is assumed, so ``authkeys <user>``
+behaves like ``authkeys resolve <user>`` — matching the console script.
+"""
+
+from .cli import run
+
+if __name__ == "__main__":
+    raise SystemExit(run())

authkeys/cache.py

@@ -0,0 +1,211 @@
+"""TTL cache for resolved authorized keys.
+
+Entries are keyed by ``(uid, source_name)`` and store the serialized keys plus a
+timestamp. :class:`AuthKeysCache` applies the TTL; backends only persist and
+retrieve ``(value, timestamp)`` pairs.
+"""
+
+from pathlib import Path
+from time import time
+from typing import Iterable, Optional, Tuple
+
+# (uid, source_name)
+CacheKey = Tuple[str, str]
+# (serialized_keys, stored_at_epoch)
+CacheEntry = Tuple[str, float]
+
+
+class AuthKeysCacheBackend:
+    """Persist ``(value, timestamp)`` pairs keyed by :data:`CacheKey`.
+
+    Enumeration/deletion (``keys``/``__delitem__``/``sweep``) are optional; a
+    backend that can't support them (e.g. an in-memory one across processes)
+    raises ``NotImplementedError`` so the ``authkeys cache`` subcommand can report
+    the limitation gracefully.
+    """
+
+    @classmethod
+    def from_config(cls, config) -> "AuthKeysCacheBackend":
+        return cls()
+
+    def __getitem__(self, key: CacheKey) -> "Optional[CacheEntry]":  # pragma: no cover
+        raise NotImplementedError
+
+    def __setitem__(self, key: CacheKey, value: str) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+    def keys(self) -> "Iterable[CacheKey]":  # pragma: no cover
+        raise NotImplementedError
+
+    def __delitem__(self, key: CacheKey) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+    def sweep(
+        self, *, max_age: "Optional[float]" = None, max_entries: "Optional[int]" = None
+    ) -> int:
+        """Evict expired/excess entries; return the number removed."""
+        removed = 0
+        entries = [(k, self[k]) for k in self.keys()]
+        entries = [(k, e) for k, e in entries if e]
+        if max_age is not None:
+            cutoff = time() - max_age
+            for k, e in list(entries):
+                if e[1] < cutoff:
+                    del self[k]
+                    removed += 1
+                    entries.remove((k, e))
+        if max_entries is not None and len(entries) > max_entries:
+            # Drop the oldest first.
+            entries.sort(key=lambda ke: ke[1][1])
+            for k, _e in entries[: len(entries) - max_entries]:
+                del self[k]
+                removed += 1
+        return removed
+
+
+class AuthKeysCacheMemBackend(AuthKeysCacheBackend):
+    def __init__(self) -> None:
+        self.db: "dict[CacheKey, CacheEntry]" = {}
+
+    def __getitem__(self, key: CacheKey) -> "Optional[CacheEntry]":
+        return self.db.get(key)
+
+    def __setitem__(self, key: CacheKey, value: str) -> None:
+        self.db[key] = (value, time())
+
+    def keys(self) -> "Iterable[CacheKey]":
+        return list(self.db.keys())
+
+    def __delitem__(self, key: CacheKey) -> None:
+        self.db.pop(key, None)
+
+
+class AuthKeysCacheFileBackend(AuthKeysCacheBackend):
+    """Cache keys under ``<path>/<source>/<uid>``; mtime is the timestamp."""
+
+    def __init__(self, path: "str | Path") -> None:
+        self.path = Path(path)
+
+    @classmethod
+    def from_config(cls, config) -> "AuthKeysCacheFileBackend":
+        for path in config.getlist("path", []):
+            path = Path(path)
+            if path.exists():
+                return cls(path)
+        raise FileNotFoundError(
+            "No existing cache 'path' configured for the file cache backend"
+        )
+
+    def cached_entry_path(self, key: CacheKey) -> "Optional[Path]":
+        uid, src = key
+        if not (self.path and self.path.exists()):
+            return None
+        src_cache = self.path / src
+        # Cache entries reveal which principals a host trusts -> keep them private.
+        src_cache.mkdir(exist_ok=True)
+        try:
+            src_cache.chmod(0o700)
+        except OSError:
+            pass
+        return src_cache / uid
+
+    def __getitem__(self, key: CacheKey) -> "Optional[CacheEntry]":
+        cached = self.cached_entry_path(key)
+        if cached and cached.exists():
+            return cached.read_text(), cached.stat().st_mtime
+        return None
+
+    def __setitem__(self, key: CacheKey, value: str) -> None:
+        cached = self.cached_entry_path(key)
+        if not cached:
+            return
+        # Write atomically (temp file in the same dir + os.replace) so a concurrent
+        # reader -- including a separate sshd-spawned process, which the in-process
+        # lock does not cover -- never sees a truncated entry.
+        import os
+        import tempfile
+
+        fd, tmp = tempfile.mkstemp(dir=str(cached.parent), prefix=".tmp-")
+        try:
+            os.write(fd, value.encode("utf-8"))
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        try:
+            os.chmod(tmp, 0o600)
+        except OSError:
+            pass
+        os.replace(tmp, str(cached))
+
+    def keys(self) -> "Iterable[CacheKey]":
+        if not (self.path and self.path.exists()):
+            return []
+        found = []
+        for src_dir in self.path.iterdir():
+            if src_dir.is_dir():
+                for entry in src_dir.iterdir():
+                    if entry.is_file() and not entry.name.startswith(".tmp-"):
+                        found.append((entry.name, src_dir.name))
+        return found
+
+    def __delitem__(self, key: CacheKey) -> None:
+        cached = self.cached_entry_path(key)
+        if cached and cached.exists():
+            cached.unlink()
+
+
+# Marker distinguishing a cached "this (uid, source) genuinely has no keys"
+# (negative hit) from a cached key set. It must never be a valid key line.
+_NEGATIVE_MARKER = "\x00authkeys:empty"
+
+
+class AuthKeysCache:
+    """TTL cache with a distinct (shorter) TTL for negative (empty) results.
+
+    ``ttl`` is the positive TTL. ``negative_ttl`` (defaults to ``ttl``) bounds a
+    cached "no keys" result so a newly-added key appears sooner. An *errored*
+    resolution is never stored here -- only genuine results -- so
+    ``expired_on_error`` never resurrects an outage as "empty".
+    """
+
+    def __init__(
+        self,
+        backend: AuthKeysCacheBackend,
+        ttl: int = 1,
+        negative_ttl: "Optional[int]" = None,
+    ) -> None:
+        self.ttl = ttl
+        self.negative_ttl = ttl if negative_ttl is None else negative_ttl
+        self.backend = backend
+
+    def _fresh(self, stored_at: float, ttl: int) -> bool:
+        return (time() - ttl) <= stored_at
+
+    def get(
+        self,
+        key: CacheKey,
+        *,
+        include_expired: bool = False,
+        ttl: "Optional[int]" = None,
+    ) -> "Optional[str]":
+        result = self.backend[key]
+        if not result:
+            return None
+        value, stored_at = result
+        is_negative = value == _NEGATIVE_MARKER
+        effective = self.negative_ttl if is_negative else (
+            self.ttl if ttl is None else ttl
+        )
+        if include_expired or self._fresh(stored_at, effective):
+            return "" if is_negative else value
+        return None
+
+    def set(self, key: CacheKey, value: str, *, negative: bool = False) -> None:
+        self.backend[key] = _NEGATIVE_MARKER if negative else value
+
+    def __getitem__(self, key: CacheKey) -> "Optional[str]":
+        return self.get(key, include_expired=False)
+
+    def __setitem__(self, key: CacheKey, value: str) -> None:
+        # Empty string => negative (known-empty) entry with the negative TTL.
+        self.set(key, value, negative=(value == ""))