baton-auth 0.1.3__py3-none-any.whl

baton_auth/__init__.py

@@ -0,0 +1,45 @@
+"""baton: pass auth context between agents as leases, never as secrets."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .crypto import CryptoError, zeroize
+from .models import (
+    BatonError,
+    Context,
+    Credential,
+    Lease,
+    LeaseError,
+    RefreshError,
+    UnknownContext,
+    UnknownCredential,
+    VaultLocked,
+)
+
+try:
+    __version__ = version("baton-auth")
+except PackageNotFoundError:  # running from an unpackaged source tree
+    __version__ = "0+local"
+
+__all__ = [
+    "BatonError",
+    "Context",
+    "Credential",
+    "CryptoError",
+    "Lease",
+    "LeaseError",
+    "RefreshError",
+    "UnknownContext",
+    "UnknownCredential",
+    "VaultLocked",
+    "Vault",
+    "zeroize",
+    "__version__",
+]
+
+
+def __getattr__(name: str):
+    if name == "Vault":
+        from .vault import Vault
+
+        return Vault
+    raise AttributeError(name)

baton_auth/__main__.py

@@ -0,0 +1,7 @@
+"""Run the operator CLI with ``python -m baton_auth``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

baton_auth/broker.py

@@ -0,0 +1,342 @@
+"""Brokered HTTP: the agent asks for a URL, the broker attaches the credential.
+
+This is the second half of the never-hand-over-the-secret rule. Egress for APIs
+goes through here so the token is used by the tool layer, not pasted into a
+prompt. Signing schemes live with the credential, not with the caller.
+
+SigV4 uses SHA-256 because the AWS specification fixes it; everything else in
+baton uses BLAKE3.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import ipaddress
+import socket
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import quote, urlparse
+
+import httpx
+
+from .models import BatonError, Credential, LeaseError, UnknownCredential
+from .redact import Redactor
+from .vault import Vault
+
+MAX_BODY = 200_000
+
+_SAFE_HEADERS = {
+    "content-type",
+    "content-length",
+    "date",
+    "etag",
+    "last-modified",
+    "location",
+    "retry-after",
+    "x-ratelimit-limit",
+    "x-ratelimit-remaining",
+    "x-ratelimit-reset",
+    "x-request-id",
+}
+
+# Cloud metadata and internal link-local endpoints blocked by default
+_METADATA_HOSTS = frozenset({
+    "169.254.169.254",
+    "metadata.google.internal",
+    "metadata.local",
+    "fd00:ec2::254",
+})
+
+
+def validate_target_url(
+    url: str,
+    *,
+    allow_private: bool = False,
+    allow_loopback: bool = True,
+) -> None:
+    """SSRF guard: reject non-http schemes, metadata services, and internal/private IPs."""
+    parsed = urlparse(url)
+    scheme = parsed.scheme.lower()
+    if scheme not in ("http", "https"):
+        raise BrokerError(f"unsupported URL scheme {scheme!r} (must be http or https)")
+
+    host = parsed.hostname
+    if not host:
+        raise BrokerError("missing host in URL")
+
+    host_lower = host.lower()
+    if host_lower in _METADATA_HOSTS:
+        raise BrokerError(f"SSRF protection: access to metadata endpoint {host!r} is blocked")
+
+    try:
+        addr_infos = socket.getaddrinfo(host, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
+    except socket.gaierror as exc:
+        raise BrokerError(f"could not resolve host {host!r}: {exc}") from exc
+
+    for _, _, _, _, sockaddr in addr_infos:
+        ip_str = sockaddr[0]
+        try:
+            ip = ipaddress.ip_address(ip_str)
+        except ValueError:
+            continue
+
+        if not allow_loopback and ip.is_loopback:
+            raise BrokerError(f"SSRF protection: loopback address {ip_str} is blocked")
+
+        if ip.is_link_local:
+            raise BrokerError(f"SSRF protection: link-local address {ip_str} is blocked")
+
+        if not allow_private and ip.is_private and not ip.is_loopback:
+            raise BrokerError(f"SSRF protection: private network address {ip_str} is blocked")
+
+
+
+class BrokerError(BatonError):
+    """Request could not be attributed to a credential."""
+
+
+@dataclass(slots=True)
+class HttpResponse:
+    url: str
+    status: int
+    headers: dict[str, str] = field(default_factory=dict)
+    body: str = ""
+    truncated: bool = False
+    service: str = ""
+    credential: str = ""
+    redactions: int = 0
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "url": self.url,
+            "status": self.status,
+            "headers": self.headers,
+            "body": self.body,
+            "truncated": self.truncated,
+            "service": self.service,
+            "credential": self.credential,
+            "redactions": self.redactions,
+        }
+
+
+def pick_credential(creds: list[Credential], service: str | None) -> Credential:
+    if service:
+        for c in creds:
+            if c.name == service or c.provider == service:
+                return c
+        raise UnknownCredential(f"no credential for service {service!r} in context")
+    if len(creds) == 1:
+        return creds[0]
+    raise BrokerError(
+        "context has several credentials; name one with service=" + str([c.name for c in creds])
+    )
+
+
+def _pick_credential_name(vault: Vault, names: list[str], service: str | None) -> str:
+    """Select using public metadata before decrypting or refreshing a credential."""
+    if service:
+        for name in names:
+            provider = vault.get_credential_provider(name)
+            if provider is None:
+                raise UnknownCredential(f"unknown credential {name!r} (see `baton cred list`)")
+            if name == service or provider == service:
+                return name
+        raise UnknownCredential(f"no credential for service {service!r} in context")
+    if len(names) == 1:
+        return names[0]
+    raise BrokerError(
+        "context has several credentials; name one with service=" + str(names)
+    )
+
+
+def _sigv4(
+    cred: Credential, method: str, url: str, headers: dict[str, str], body: bytes
+) -> dict[str, str]:
+    """AWS Signature Version 4 for a single request."""
+    akid = cred.secret.get("access_key_id", "")
+    secret = cred.secret.get("secret_access_key", "")
+    if not akid or not secret:
+        raise BrokerError(f"credential {cred.name} lacks AWS key material")
+    region = cred.secret.get("region") or "us-east-1"
+    service = str(cred.auth.get("service") or "execute-api")
+
+    parsed = urlparse(url)
+    host = parsed.netloc
+    now = datetime.now(timezone.utc)
+    amzdate = now.strftime("%Y%m%dT%H%M%SZ")
+    datestamp = now.strftime("%Y%m%d")
+
+    signed = {k.lower(): v for k, v in headers.items()}
+    signed["host"] = host
+    signed["x-amz-date"] = amzdate
+    if cred.secret.get("session_token"):
+        signed["x-amz-security-token"] = cred.secret["session_token"]
+
+    canonical_uri = quote(parsed.path or "/", safe="/-_.~")
+    canonical_query = "&".join(
+        sorted(
+            quote(k, safe="-_.~") + "=" + quote(v, safe="-_.~")
+            for k, v in (httpx.QueryParams(parsed.query).multi_items() if parsed.query else [])
+        )
+    )
+    keys = sorted(signed)
+    canonical_headers = "".join(f"{k}:{signed[k].strip()}\n" for k in keys)
+    signed_headers = ";".join(keys)
+    payload_hash = hashlib.sha256(body).hexdigest()
+
+    canonical_request = "\n".join(
+        [method, canonical_uri, canonical_query, canonical_headers, signed_headers, payload_hash]
+    )
+    scope = f"{datestamp}/{region}/{service}/aws4_request"
+    string_to_sign = "\n".join(
+        [
+            "AWS4-HMAC-SHA256",
+            amzdate,
+            scope,
+            hashlib.sha256(canonical_request.encode()).hexdigest(),
+        ]
+    )
+
+    def _hmac(key: bytes, msg: str) -> bytes:
+        return hmac.new(key, msg.encode(), hashlib.sha256).digest()
+
+    k_date = _hmac(b"AWS4" + secret.encode(), datestamp)
+    k_region = _hmac(k_date, region)
+    k_service = _hmac(k_region, service)
+    k_signing = _hmac(k_service, "aws4_request")
+    signature = hmac.new(k_signing, string_to_sign.encode(), hashlib.sha256).hexdigest()
+
+    out = dict(headers)
+    for k in ("host", "x-amz-date", "x-amz-security-token"):
+        if k in signed and k not in {h.lower() for h in out}:
+            out[k] = signed[k]
+    out["Authorization"] = (
+        f"AWS4-HMAC-SHA256 Credential={akid}/{scope}, "
+        f"SignedHeaders={signed_headers}, Signature={signature}"
+    )
+    return out
+
+
+def attach_auth(
+    cred: Credential, method: str, url: str, headers: dict[str, str], body: bytes
+) -> tuple[dict[str, str], dict[str, str]]:
+    """Return (headers, query overrides) with the credential applied."""
+    scheme = str(cred.auth.get("scheme", "bearer"))
+    field_name = str(cred.auth.get("field", "token"))
+    secret = cred.secret.get(field_name, "")
+    out = dict(headers)
+    query: dict[str, str] = {}
+
+    if scheme == "sigv4":
+        return _sigv4(cred, method, url, out, body), query
+    if scheme == "bearer":
+        if not secret:
+            raise BrokerError(f"credential {cred.name} has no {field_name}")
+        out["Authorization"] = f"Bearer {secret}"
+    elif scheme == "header":
+        header_name = str(cred.auth.get("header", "x-api-key"))
+        if not secret:
+            raise BrokerError(f"credential {cred.name} has no {field_name}")
+        out[header_name] = secret
+    elif scheme == "basic":
+        user = cred.secret.get(str(cred.auth.get("user", "username")), "")
+        password = cred.secret.get(str(cred.auth.get("password", "password")), "")
+        out["Authorization"] = "Basic " + base64.b64encode(f"{user}:{password}".encode()).decode()
+    elif scheme == "query":
+        if not secret:
+            raise BrokerError(f"credential {cred.name} has no {field_name}")
+        query[str(cred.auth.get("param", "key"))] = secret
+    elif scheme == "none":
+        pass
+    else:
+        raise BrokerError(f"unsupported auth scheme {scheme!r}")
+    return out, query
+
+
+def request(
+    vault: Vault,
+    target: str,
+    method: str,
+    url: str,
+    *,
+    service: str | None = None,
+    headers: dict[str, str] | None = None,
+    body: bytes | None = None,
+    json_body: Any | None = None,
+    timeout: float = 30.0,
+    allow_private: bool = False,
+    allow_loopback: bool = True,
+) -> HttpResponse:
+    validate_target_url(url, allow_private=allow_private, allow_loopback=allow_loopback)
+    lease = None
+    if target.startswith("btn_"):
+        lease = vault.resolve_lease(target)
+        if not lease.allows(service):
+            raise LeaseError(f"lease does not grant {service!r}")
+        context_name = lease.context
+    else:
+        context_name = target
+
+    ctx = vault.get_context(context_name)
+    if not ctx.credentials:
+        raise BrokerError(f"context {context_name} has no credentials")
+    cred_name = _pick_credential_name(vault, ctx.credentials, service)
+    cred = vault.get_credential(cred_name, auto_refresh=True)
+
+    payload = body if body is not None else b""
+    if json_body is not None:
+        import json as _json
+
+        payload = _json.dumps(json_body).encode()
+        headers = {**(headers or {}), "content-type": "application/json"}
+
+    public_url = url
+    final_headers, query = attach_auth(cred, method.upper(), url, dict(headers or {}), payload)
+    if query:
+        sep = "&" if "?" in url else "?"
+        url = url + sep + "&".join(f"{k}={quote(v, safe='')}" for k, v in query.items())
+
+    # A redirect destination has not passed the SSRF guard. Return the 3xx
+    # response so the caller can explicitly make a separately validated request.
+    with httpx.Client(timeout=timeout, follow_redirects=False) as client:
+        resp = client.request(method.upper(), url, headers=final_headers, content=payload or None)
+
+    # Query auth percent-encodes values. Echoes in bodies or Location headers
+    # need to be scrubbed in both their original and wire representations.
+    secret_values = list(cred.secret.values())
+    redactor = Redactor([*secret_values, *(quote(value, safe="") for value in secret_values)])
+    raw = resp.text
+    truncated = len(raw) > MAX_BODY
+    clean, hits = redactor.redact_counted(raw[:MAX_BODY])
+    safe_headers = {
+        k: v for k, v in resp.headers.items() if k.lower() in _SAFE_HEADERS
+    }
+    clean_headers = {}
+    for k, v in safe_headers.items():
+        clean_headers[k], n = redactor.redact_counted(v)
+        hits += n
+    # Never return the URL after query authentication has added a secret.
+    safe_url, n = redactor.redact_counted(public_url)
+    hits += n
+
+    vault.audit(
+        lease.id if lease else None,
+        None,
+        "http",
+        f"{method.upper()} {urlparse(url).netloc}{urlparse(url).path}",
+        resp.is_success,
+        {"status": resp.status_code, "credential": cred.name},
+    )
+    return HttpResponse(
+        url=safe_url,
+        status=resp.status_code,
+        headers=clean_headers,
+        body=clean,
+        truncated=truncated,
+        service=service or cred.provider,
+        credential=cred.name,
+        redactions=hits,
+    )

baton_auth/catalog.py

@@ -0,0 +1,268 @@
+"""Provider presets: how a secret becomes a working CLI auth.
+
+A preset is the whole domain knowledge of this tool. For each provider it fixes
+(a) the secret fields, (b) the materialization steps that make a CLI accept
+those fields in an isolated HOME, and (c) how the brokered HTTP layer attaches
+the credential.
+
+Templating: `{field}` is substituted from the secret payload, `{HOME}` from the
+sandbox home. Anything else left unresolved is a hard error at plan time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .models import BatonError, Credential
+
+
+class PresetError(BatonError):
+    """Invalid provider or missing required fields."""
+
+
+@dataclass(frozen=True, slots=True)
+class Preset:
+    provider: str
+    fields: tuple[str, ...] = ()
+    optional: tuple[str, ...] = ()
+    materialize: tuple[dict[str, Any], ...] = ()
+    auth: dict[str, Any] = field(default_factory=dict)
+    hint: str = ""
+
+    @property
+    def all_fields(self) -> tuple[str, ...]:
+        return self.fields + self.optional
+
+
+_GH_HOSTS = "github.com:\n    oauth_token: {token}\n    git_protocol: https\n"
+_GH_HOSTS_USER = "    user: {user}\n"
+
+PRESETS: dict[str, Preset] = {
+    "aws": Preset(
+        provider="aws",
+        fields=("access_key_id", "secret_access_key"),
+        optional=("session_token", "region"),
+        materialize=(
+            {
+                "kind": "env",
+                "map": {
+                    "AWS_ACCESS_KEY_ID": "{access_key_id}",
+                    "AWS_SECRET_ACCESS_KEY": "{secret_access_key}",
+                    "AWS_SESSION_TOKEN": "{session_token}",
+                    "AWS_REGION": "{region}",
+                    "AWS_DEFAULT_REGION": "{region}",
+                },
+            },
+            {
+                "kind": "ini",
+                "path": ".aws/credentials",
+                "section": "default",
+                "map": {
+                    "aws_access_key_id": "{access_key_id}",
+                    "aws_secret_access_key": "{secret_access_key}",
+                    "aws_session_token": "{session_token}",
+                },
+            },
+        ),
+        auth={"scheme": "sigv4", "service": "execute-api"},
+        hint="AWS access key (or STS session credentials)",
+    ),
+    "gcp": Preset(
+        provider="gcp",
+        fields=("service_account_json",),
+        materialize=(
+            {
+                "kind": "file",
+                "path": ".config/gcloud/baton-sa.json",
+                "mode": "0600",
+                "template": "{service_account_json}",
+            },
+            {
+                "kind": "env",
+                "map": {
+                    "GOOGLE_APPLICATION_CREDENTIALS": "{HOME}/.config/gcloud/baton-sa.json",
+                    "CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE": "{HOME}/.config/gcloud/baton-sa.json",
+                },
+            },
+        ),
+        auth={"scheme": "bearer", "field": "access_token"},
+        hint="GCP service-account JSON blob",
+    ),
+    "github": Preset(
+        provider="github",
+        fields=("token",),
+        optional=("user",),
+        materialize=(
+            {
+                "kind": "env",
+                "map": {"GH_TOKEN": "{token}", "GITHUB_TOKEN": "{token}"},
+            },
+            {"kind": "file", "path": ".config/gh/hosts.yml", "template": _GH_HOSTS},
+            {
+                "kind": "file",
+                "path": ".config/gh/hosts.yml",
+                "optional": True,
+                "template": _GH_HOSTS_USER,
+            },
+        ),
+        auth={"scheme": "bearer", "field": "token"},
+        hint="GitHub PAT (ghp_/github_pat_) or fine-grained token",
+    ),
+    "gitlab": Preset(
+        provider="gitlab",
+        fields=("token",),
+        materialize=(
+            {"kind": "env", "map": {"GITLAB_TOKEN": "{token}", "GLAB_TOKEN": "{token}"}},
+        ),
+        auth={"scheme": "header", "header": "PRIVATE-TOKEN", "field": "token"},
+        hint="GitLab PAT (glpat-)",
+    ),
+    "npm": Preset(
+        provider="npm",
+        fields=("token",),
+        materialize=(
+            {"kind": "env", "map": {"NPM_TOKEN": "{token}"}},
+            {
+                "kind": "file",
+                "path": ".npmrc",
+                "template": "//registry.npmjs.org/:_authToken={token}\n",
+            },
+        ),
+        auth={"scheme": "bearer", "field": "token"},
+        hint="npm registry token",
+    ),
+    "docker": Preset(
+        provider="docker",
+        fields=("username", "password"),
+        optional=("registry",),
+        materialize=(
+            {
+                "kind": "docker_auth",
+                "path": ".docker/config.json",
+                "registry": "{registry}",
+                "username": "{username}",
+                "password": "{password}",
+            },
+        ),
+        auth={"scheme": "basic", "user": "username", "password": "password"},
+        hint="Container registry credentials",
+    ),
+    "kube": Preset(
+        provider="kube",
+        fields=("kubeconfig",),
+        materialize=(
+            {
+                "kind": "file",
+                "path": ".kube/config",
+                "mode": "0600",
+                "template": "{kubeconfig}",
+            },
+            {"kind": "env", "map": {"KUBECONFIG": "{HOME}/.kube/config"}},
+        ),
+        auth={"scheme": "bearer", "field": "token"},
+        hint="Full kubeconfig YAML",
+    ),
+    "ssh": Preset(
+        provider="ssh",
+        fields=("private_key",),
+        optional=("public_key", "known_hosts", "key_name"),
+        materialize=(
+            {
+                "kind": "file",
+                "path": ".ssh/{key_name}",
+                "mode": "0600",
+                "template": "{private_key}\n",
+            },
+            {
+                "kind": "file",
+                "path": ".ssh/{key_name}.pub",
+                "mode": "0644",
+                "optional": True,
+                "template": "{public_key}\n",
+            },
+            {
+                "kind": "file",
+                "path": ".ssh/known_hosts",
+                "mode": "0644",
+                "optional": True,
+                "template": "{known_hosts}",
+            },
+        ),
+        hint="SSH private key material",
+    ),
+    "generic": Preset(
+        provider="generic",
+        fields=("token",),
+        materialize=(),
+        auth={"scheme": "bearer", "field": "token"},
+        hint="Bare token; add env mapping with --env NAME={token}",
+    ),
+}
+
+
+def preset(provider: str) -> Preset:
+    if not provider.strip():
+        raise PresetError("provider name cannot be empty")
+    return PRESETS.get(provider) or Preset(
+        provider=provider,
+        auth={"scheme": "bearer", "field": "token"},
+        hint="Custom provider; bearer token by default",
+    )
+
+
+def build_credential(
+    name: str,
+    provider: str,
+    values: dict[str, str],
+    *,
+    expires_at: float | None = None,
+    notes: str = "",
+    env_map: dict[str, str] | None = None,
+    refresh: dict[str, Any] | None = None,
+    auth: dict[str, Any] | None = None,
+) -> Credential:
+    """Validate field coverage and assemble a Credential from a preset."""
+    p = preset(provider)
+    if provider == "ssh" and "key_name" not in values:
+        values = {**values, "key_name": "id_baton"}
+    auth_spec = dict(auth) if auth is not None else dict(p.auth)
+    if provider in PRESETS and provider != "generic":
+        required = list(p.fields)
+    elif auth_spec.get("scheme") == "basic":
+        required = ["username", "password"]
+    elif auth_spec.get("scheme") == "none":
+        required = []
+    else:
+        required = [str(auth_spec.get("field", "token"))]
+    if auth is not None:
+        if auth_spec.get("scheme") == "basic":
+            required.extend(("username", "password"))
+        elif auth_spec.get("scheme") in {"bearer", "header", "query"}:
+            required.append(str(auth_spec.get("field", "token")))
+    missing = [f for f in dict.fromkeys(required) if not values.get(f)]
+    if missing:
+        raise PresetError(f"{provider}: missing required field(s): {', '.join(missing)}")
+    if not any(values.values()):
+        raise PresetError(f"{provider}: provide at least one secret field")
+    allowed = set(p.all_fields) | {"refresh_token", "client_id", "client_secret"}
+    unknown = [k for k in values if k not in allowed]
+    if unknown and provider in PRESETS and provider != "generic":
+        raise PresetError(f"{provider}: unknown field(s): {', '.join(unknown)}")
+
+    steps: list[dict[str, Any]] = [dict(s) for s in p.materialize]
+    if env_map:
+        steps.append({"kind": "env", "map": dict(env_map)})
+
+    # Incomplete optional steps are dropped at plan time; prune empty templates here.
+    return Credential(
+        name=name,
+        provider=provider,
+        secret={k: v for k, v in values.items() if v},
+        materialize=steps,
+        auth=auth_spec,
+        refresh=dict(refresh or {}),
+        expires_at=expires_at,
+        notes=notes,
+        meta={"preset": provider},
+    )