briar-cli 1.1.1__py3-none-any.whl

briar/credentials/_store.py

@@ -0,0 +1,63 @@
+"""`CredentialStore` — Strategy contract for credential resolution.
+
+Today, every cred is read directly from process env vars (via
+``CredEnv``). This abstraction lets you keep the same call sites
+(``store.read(env_name)``) while swapping the backing source —
+EnvFile (today), AWS Secrets Manager, SSM Parameter Store, Vault.
+
+Four verbs:
+- ``read(name)``: look up one var by canonical name (e.g.
+  ``AWS_ACME_ACCESS_KEY_ID``). Returns ``""`` if not found —
+  callers check truthiness.
+- ``list()``: enumerate names of all credentials known to the store
+  (used by ``briar secrets doctor`` to report set/missing).
+- ``fingerprint(name)``: md5 of the stored value (for rotation detection
+  without exposing the value itself).
+- ``expires_at(name)``: parse expiration for time-bound creds (AWS STS
+  session tokens). Returns ISO-8601 string or ``""``."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar, List
+
+
+class CredentialStore(ABC):
+    kind: ClassVar[str] = ""
+
+    @abstractmethod
+    def read(self, name: str) -> str:
+        """Return the value for `name`, or ``""`` if missing."""
+
+    @abstractmethod
+    def write(self, name: str, value: str) -> None:
+        """Persist a credential. Overwrites existing values of the
+        same name. Used by ``briar auth login`` after a successful
+        acquire. Failures raise — callers propagate so the operator
+        sees the underlying SDK error."""
+
+    @abstractmethod
+    def delete(self, name: str) -> bool:
+        """Remove a credential. Returns True if a value existed and was
+        removed, False if the name was unknown. Used by
+        ``briar auth logout``."""
+
+    @abstractmethod
+    def list(self) -> List[str]:
+        """Enumerate every credential name this store knows."""
+
+    def fingerprint(self, name: str) -> str:
+        """Default: md5 of the value. Override for stores that can
+        compute hashes server-side."""
+        import hashlib
+
+        value = self.read(name)
+        if not value:
+            return ""
+        return hashlib.md5(value.encode("utf-8")).hexdigest()
+
+    def expires_at(self, name: str) -> str:
+        """Default: no expiration tracking. AWS STS session tokens
+        encode expiry inside the credential itself — overridden by
+        the EnvFile / AwsSecretsManager stores."""
+        return ""

briar/credentials/aws_secrets.py

@@ -0,0 +1,102 @@
+"""AWS Secrets Manager `CredentialStore`.
+
+Reads ``briar/<name>`` secrets at first call and caches in-memory for
+the process lifetime (SecretsManager charges per API call). Region
+comes from ``AWS_REGION`` env var or the boto3 default; auth uses the
+ambient credential chain (IAM role on EC2, SSO profile locally,
+static keys via env).
+
+Composite secrets (a single ``SecretId`` whose ``SecretString`` is a
+JSON object) are also supported via the ``key`` argument convention:
+``store.read("BITBUCKET_ACME_USERNAME")`` → looks up secret
+``briar/BITBUCKET_ACME_USERNAME``; if the SecretString parses as
+JSON, the ``value`` key (or ``BITBUCKET_ACME_USERNAME``) wins."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Dict, List
+
+from briar.credentials._store import CredentialStore
+
+
+log = logging.getLogger(__name__)
+
+
+class AwsSecretsManagerStore(CredentialStore):
+    kind = "aws-secretsmanager"
+    PREFIX = "briar/"
+
+    def __init__(self) -> None:
+        self._client = None
+        self._cache: Dict[str, str] = {}
+
+    def _make_client(self):
+        if self._client is not None:
+            return self._client
+        import boto3
+
+        self._client = boto3.client("secretsmanager")
+        return self._client
+
+    def read(self, name: str) -> str:
+        if name in self._cache:
+            return self._cache[name]
+        client = self._make_client()
+        try:
+            resp = client.get_secret_value(SecretId=f"{self.PREFIX}{name}")
+        except Exception as exc:  # noqa: BLE001
+            log.debug("aws-secretsmanager read miss name=%s err=%s", name, exc)
+            self._cache[name] = ""
+            return ""
+        value = resp.get("SecretString") or ""
+        # Composite-secret support: if SecretString parses as JSON,
+        # look for `{value}` or the bare key. Otherwise treat as scalar.
+        try:
+            parsed = json.loads(value)
+            if isinstance(parsed, dict):
+                value = str(parsed.get("value") or parsed.get(name) or value)
+        except (ValueError, TypeError):
+            pass
+        self._cache[name] = value
+        return value
+
+    def write(self, name: str, value: str) -> None:
+        """Upsert via PutSecretValue; falls through to CreateSecret on
+        first-time write."""
+        client = self._make_client()
+        secret_id = f"{self.PREFIX}{name}"
+        try:
+            client.put_secret_value(SecretId=secret_id, SecretString=value)
+        except Exception as exc:  # noqa: BLE001
+            if "resourcenotfoundexception" in str(exc).lower() or "not found" in str(exc).lower():
+                client.create_secret(Name=secret_id, SecretString=value)
+            else:
+                log.exception("aws-secretsmanager write name=%s", name)
+                raise
+        self._cache[name] = value
+
+    def delete(self, name: str) -> bool:
+        """Force-delete with no recovery window."""
+        client = self._make_client()
+        secret_id = f"{self.PREFIX}{name}"
+        try:
+            client.delete_secret(SecretId=secret_id, ForceDeleteWithoutRecovery=True)
+        except Exception as exc:  # noqa: BLE001
+            if "resourcenotfoundexception" in str(exc).lower():
+                return False
+            raise
+        self._cache.pop(name, None)
+        return True
+
+    def list(self) -> List[str]:
+        client = self._make_client()
+        out: List[str] = []
+        paginator = client.get_paginator("list_secrets")
+        for page in paginator.paginate():
+            for entry in page.get("SecretList", []) or []:
+                full = entry.get("Name") or ""
+                if full.startswith(self.PREFIX):
+                    out.append(full[len(self.PREFIX) :])
+        return sorted(out)

briar/credentials/envfile.py

@@ -0,0 +1,171 @@
+"""`EnvFileStore` — thin wrapper over process env vars (which is
+where `/etc/briar/secrets.env` lands once systemd reads it via
+``EnvironmentFile=``).
+
+This is the only `CredentialStore` backend that needs to work today.
+It exposes the existing env-var surface through the new abstraction
+so `briar secrets doctor` and any future store-backed code can use
+one API regardless of where credentials live."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import List
+
+from briar.credentials._store import CredentialStore
+
+
+log = logging.getLogger(__name__)
+
+
+# Where the secrets file lives. Resolution chain (first match wins):
+#   1. $BRIAR_SECRETS_FILE       — explicit operator override
+#   2. /etc/briar/secrets.env    — if already present (droplet convention,
+#                                  systemd reads it via EnvironmentFile=)
+#   3. $XDG_CONFIG_HOME/briar/secrets.env  (or ~/.config/briar/secrets.env)
+#                                — laptop default (XDG-compliant)
+# The chain "just works" on both deploy shapes without requiring the
+# laptop user to set BRIAR_SECRETS_FILE manually.
+def _secrets_path() -> Path:
+    explicit = os.environ.get("BRIAR_SECRETS_FILE", "").strip()
+    if explicit:
+        return Path(explicit)
+    system = Path("/etc/briar/secrets.env")
+    if system.exists():
+        return system
+    base_str = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    base = Path(base_str) if base_str else Path.home() / ".config"
+    return base / "briar" / "secrets.env"
+
+
+_NAME_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+def _validate_name(name: str) -> None:
+    if not _NAME_RE.match(name):
+        raise ValueError(f"EnvFileStore: invalid env-var name {name!r} — must match {_NAME_RE.pattern}")
+
+
+# Canonical credential name prefixes — used by `list()` to enumerate
+# which env vars are "credentials" vs unrelated process state.
+# Updating CredEnv? Update this list too.
+_KNOWN_PREFIXES: tuple = (
+    "AWS_",
+    "GITHUB_",
+    "BITBUCKET_",
+    "JIRA_",
+    "LINEAR_",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "GEMINI_API_KEY",
+    "BRIAR_DATABASE_URL",
+    "TELEGRAM_",
+    "SLACK_",
+    "SMTP_",
+    "EMAIL_",
+    "PAGERDUTY_",
+)
+
+
+class EnvFileStore(CredentialStore):
+    kind = "envfile"
+
+    def read(self, name: str) -> str:
+        return os.environ.get(name, "")
+
+    def write(self, name: str, value: str) -> None:
+        """Update ``os.environ`` for the running process AND persist
+        durably to the secrets file. Atomic via temp-file + rename.
+
+        Idempotent: a line with the same KEY is replaced in-place;
+        new keys are appended at the end.
+
+        Parent directory is auto-created (``mkdir(parents=True,
+        exist_ok=True)``) — the XDG default path
+        (``~/.config/briar/``) doesn't exist on first use.
+
+        File-write failures **raise** ``OSError`` AFTER ``os.environ``
+        has been updated. Two reasons: (1) the calling process still
+        benefits from the in-memory update; (2) the caller (typically
+        ``briar auth login``) needs the exception so the per-key
+        ok/FAIL summary reflects what was actually durable. Previous
+        behaviour was to swallow the error and lie — fixed."""
+        _validate_name(name)
+        os.environ[name] = value
+
+        path = _secrets_path()
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if not path.exists():
+                path.touch(mode=0o600)
+        except OSError as exc:
+            raise OSError(f"envfile-store: could not prepare {path}: {exc}") from exc
+
+        try:
+            existing = path.read_text()
+        except OSError as exc:
+            raise OSError(f"envfile-store: could not read {path}: {exc}") from exc
+
+        new_line = f"{name}={value}\n"
+        # Match `KEY=value` (possibly with leading whitespace, possibly
+        # `export KEY=value`) so we replace in place rather than appending
+        # a duplicate that shadows the first one.
+        pattern = re.compile(rf"^(?:export\s+)?{re.escape(name)}=.*\n?", re.MULTILINE)
+        if pattern.search(existing):
+            updated = pattern.sub(new_line, existing, count=1)
+        else:
+            tail = "" if existing.endswith("\n") or not existing else "\n"
+            updated = existing + tail + new_line
+
+        try:
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_text(updated)
+            os.chmod(tmp, 0o600)
+            tmp.replace(path)
+        except OSError as exc:
+            raise OSError(f"envfile-store: could not persist {name} to {path}: {exc}") from exc
+
+    def delete(self, name: str) -> bool:
+        """Remove from both ``os.environ`` and the persisted file.
+        Returns True iff something was actually removed (from either
+        location). Logout-friendly: if neither has the value, return
+        False so the CLI can report "nothing to do"."""
+        _validate_name(name)
+        env_had = name in os.environ
+        if env_had:
+            del os.environ[name]
+
+        path = _secrets_path()
+        file_had = False
+        if path.exists():
+            try:
+                existing = path.read_text()
+            except OSError:
+                return env_had
+            pattern = re.compile(rf"^(?:export\s+)?{re.escape(name)}=.*\n?", re.MULTILINE)
+            if pattern.search(existing):
+                file_had = True
+                updated = pattern.sub("", existing, count=1)
+                try:
+                    tmp = path.with_suffix(path.suffix + ".tmp")
+                    tmp.write_text(updated)
+                    os.chmod(tmp, 0o600)
+                    tmp.replace(path)
+                except OSError as exc:
+                    log.warning("envfile-store: could not persist deletion of %s: %s", name, exc)
+
+        return env_had or file_had
+
+    def list(self) -> List[str]:
+        return sorted(k for k in os.environ if any(k.startswith(p) for p in _KNOWN_PREFIXES))
+
+    def expires_at(self, name: str) -> str:
+        """AWS STS session tokens carry expiry inside the token itself,
+        but parsing that requires the STS GetSessionToken API. For
+        env-file creds we can't tell — return ``""`` and let the
+        operator rotate based on the local SSO session timeout."""
+        return ""

briar/credentials/infisical.py

@@ -0,0 +1,183 @@
+"""Infisical `CredentialStore` — symmetric counterpart to
+``InfisicalBootstrap``.
+
+The Bootstrap is the BULK-HYDRATE side (pull every secret from a
+project at process startup → into ``os.environ``). This Store is the
+READ/WRITE-PER-NAME side (read/write/delete one secret on demand —
+used by ``briar auth login --store infisical`` and any future
+on-demand fetch).
+
+Both share the same machine-identity credentials:
+  INFISICAL_CLIENT_ID + INFISICAL_CLIENT_SECRET + INFISICAL_PROJECT_ID
+(+ optional INFISICAL_ENV, defaults to ``prod``;
+   + optional INFISICAL_HOST, defaults to https://app.infisical.com)
+
+These are the values an `InfisicalAcquirer` walks the operator
+through capturing — "logging into Infisical" in the briar UX is
+really "give briar the machine-identity credentials it needs to
+talk to Infisical from now on".
+
+Lazy-imports ``infisical_sdk`` so it's an opt-in extra:
+``pip install briar-cli[infisical]``."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from briar.credentials._store import CredentialStore
+
+
+log = logging.getLogger(__name__)
+
+
+def _import_infisical_sdk() -> Optional[Any]:
+    try:
+        return importlib.import_module("infisical_sdk")
+    except ImportError:
+        return None
+
+
+class InfisicalStore(CredentialStore):
+    kind = "infisical"
+    DEFAULT_HOST = "https://app.infisical.com"
+    DEFAULT_ENV = "prod"
+    SECRET_PATH = "/"  # KV-style flat namespace under the project
+
+    def __init__(self) -> None:
+        self._client_id = os.environ.get("INFISICAL_CLIENT_ID", "")
+        self._client_secret = os.environ.get("INFISICAL_CLIENT_SECRET", "")
+        self._project_id = os.environ.get("INFISICAL_PROJECT_ID", "")
+        self._env = os.environ.get("INFISICAL_ENV", self.DEFAULT_ENV)
+        self._host = os.environ.get("INFISICAL_HOST", self.DEFAULT_HOST)
+        self._client = None
+        self._cache: Dict[str, str] = {}
+
+    def _build_client(self):
+        """Universal-auth bind. Same dance as InfisicalBootstrap so a
+        process that has both store + bootstrap pointed at the same
+        Infisical project doesn't double-authenticate."""
+        if self._client is not None:
+            return self._client
+        sdk = _import_infisical_sdk()
+        if sdk is None:
+            raise RuntimeError("infisical_sdk not installed — run `pip install briar-cli[infisical]`")
+        if not all((self._client_id, self._client_secret, self._project_id)):
+            raise RuntimeError(
+                "InfisicalStore: missing INFISICAL_CLIENT_ID + _CLIENT_SECRET + _PROJECT_ID "
+                "— run `briar auth login --provider infisical` to set them"
+            )
+        self._client = sdk.InfisicalSDKClient(host=self._host)
+        self._client.auth.universal_auth.login(
+            client_id=self._client_id,
+            client_secret=self._client_secret,
+        )
+        return self._client
+
+    # ── read side ────────────────────────────────────────────────────
+
+    def read(self, name: str) -> str:
+        """Silent miss when Infisical isn't configured — matches
+        ``EnvFileStore`` semantics so the doctor can audit without
+        forcing every caller to install the extra."""
+        if name in self._cache:
+            return self._cache[name]
+        if not all((self._client_id, self._client_secret, self._project_id)):
+            self._cache[name] = ""
+            return ""
+        try:
+            client = self._build_client()
+            resp = client.secrets.get_secret_by_name(
+                secret_name=name,
+                project_id=self._project_id,
+                environment_slug=self._env,
+                secret_path=self.SECRET_PATH,
+            )
+        except Exception as exc:  # noqa: BLE001 — translate to "missing" per the store contract
+            log.debug("infisical-store read miss name=%s err=%s", name, exc)
+            self._cache[name] = ""
+            return ""
+        # Tolerate both attribute + dict shapes (SDK versions differ).
+        value = getattr(resp, "secretValue", None)
+        if value is None and isinstance(resp, dict):
+            value = resp.get("secretValue") or (resp.get("secret") or {}).get("secretValue")
+        if value is None:
+            secret = getattr(resp, "secret", None)
+            value = getattr(secret, "secretValue", None) if secret is not None else None
+        value = str(value or "")
+        self._cache[name] = value
+        return value
+
+    # ── write side ───────────────────────────────────────────────────
+
+    def write(self, name: str, value: str) -> None:
+        """Upsert. Try ``update`` first — falls back to ``create`` if
+        the secret doesn't exist yet (the symmetric pattern used by
+        ``AwsSecretsManagerStore.write``)."""
+        client = self._build_client()
+        try:
+            client.secrets.update_secret_by_name(
+                secret_name=name,
+                project_id=self._project_id,
+                environment_slug=self._env,
+                secret_path=self.SECRET_PATH,
+                secret_value=value,
+            )
+        except Exception as exc:  # noqa: BLE001
+            msg = str(exc).lower()
+            if "not found" in msg or "notfound" in msg or "404" in msg:
+                client.secrets.create_secret_by_name(
+                    secret_name=name,
+                    project_id=self._project_id,
+                    environment_slug=self._env,
+                    secret_path=self.SECRET_PATH,
+                    secret_value=value,
+                )
+            else:
+                log.exception("infisical-store write name=%s", name)
+                raise
+        self._cache[name] = value
+
+    def delete(self, name: str) -> bool:
+        client = self._build_client()
+        try:
+            client.secrets.delete_secret_by_name(
+                secret_name=name,
+                project_id=self._project_id,
+                environment_slug=self._env,
+                secret_path=self.SECRET_PATH,
+            )
+        except Exception as exc:  # noqa: BLE001
+            msg = str(exc).lower()
+            if "not found" in msg or "notfound" in msg or "404" in msg:
+                return False
+            raise
+        self._cache.pop(name, None)
+        return True
+
+    # ── enumeration ──────────────────────────────────────────────────
+
+    def list(self) -> List[str]:
+        """Empty list when not configured — symmetric to read()."""
+        if not all((self._client_id, self._client_secret, self._project_id)):
+            return []
+        try:
+            client = self._build_client()
+            resp = client.secrets.list_secrets(
+                project_id=self._project_id,
+                environment_slug=self._env,
+                secret_path=self.SECRET_PATH,
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.debug("infisical-store list failed err=%s", exc)
+            return []
+        names: List[str] = []
+        for s in (getattr(resp, "secrets", None) or []) if not isinstance(resp, dict) else (resp.get("secrets") or []):
+            n = getattr(s, "secretKey", None)
+            if n is None and isinstance(s, dict):
+                n = s.get("secretKey", "")
+            if n:
+                names.append(str(n))
+        return sorted(names)

briar/credentials/ssm.py

@@ -0,0 +1,83 @@
+"""AWS SSM Parameter Store `CredentialStore`.
+
+SSM is significantly cheaper than Secrets Manager (free for the first
+~10k standard parameter ops/month). Use ``SecureString`` parameters
+with KMS encryption — this store always passes ``WithDecryption=True``.
+
+Convention: parameter names are prefixed with ``/briar/`` so a single
+IAM policy can grant access by path."""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, List
+
+from briar.credentials._store import CredentialStore
+
+
+log = logging.getLogger(__name__)
+
+
+class SsmParameterStore(CredentialStore):
+    kind = "ssm"
+    PREFIX = "/briar/"
+
+    def __init__(self) -> None:
+        self._client = None
+        self._cache: Dict[str, str] = {}
+
+    def _make_client(self):
+        if self._client is not None:
+            return self._client
+        import boto3
+
+        self._client = boto3.client("ssm")
+        return self._client
+
+    def read(self, name: str) -> str:
+        if name in self._cache:
+            return self._cache[name]
+        client = self._make_client()
+        try:
+            resp = client.get_parameter(Name=f"{self.PREFIX}{name}", WithDecryption=True)
+        except Exception as exc:  # noqa: BLE001
+            log.debug("ssm read miss name=%s err=%s", name, exc)
+            self._cache[name] = ""
+            return ""
+        value = str((resp.get("Parameter") or {}).get("Value") or "")
+        self._cache[name] = value
+        return value
+
+    def write(self, name: str, value: str) -> None:
+        """Upsert via PutParameter with Overwrite=True. SecureString
+        type forces KMS encryption (default key under the account)."""
+        client = self._make_client()
+        client.put_parameter(
+            Name=f"{self.PREFIX}{name}",
+            Value=value,
+            Type="SecureString",
+            Overwrite=True,
+        )
+        self._cache[name] = value
+
+    def delete(self, name: str) -> bool:
+        client = self._make_client()
+        try:
+            client.delete_parameter(Name=f"{self.PREFIX}{name}")
+        except Exception as exc:  # noqa: BLE001
+            if "parameternotfound" in str(exc).lower():
+                return False
+            raise
+        self._cache.pop(name, None)
+        return True
+
+    def list(self) -> List[str]:
+        client = self._make_client()
+        out: List[str] = []
+        paginator = client.get_paginator("get_parameters_by_path")
+        for page in paginator.paginate(Path=self.PREFIX, Recursive=True, WithDecryption=False):
+            for entry in page.get("Parameters", []) or []:
+                full = entry.get("Name") or ""
+                if full.startswith(self.PREFIX):
+                    out.append(full[len(self.PREFIX) :])
+        return sorted(out)