granny-devops 0.8.0__tar.gz → 0.9.0__tar.gz

{granny_devops-0.8.0 → granny_devops-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: granny-devops
-Version: 0.8.0
+Version: 0.9.0
 Summary: Cloud tools collection -- AWS infrastructure, CDN, and DevOps automation
 Author-email: Martin Wieser <martin.wieser@pseekoo.com>
 License: MIT License
@@ -286,6 +286,13 @@ granny email workmail create-user example.com --email user@example.com
 granny create s3-website example.com --help
 granny create scaleway-container --name my-app --port 3000
 granny create mailjet-dns example.com
+
+# Authentik admin (provider + application + group plumbing)
+granny authentik provision-stoz3n-dash development     # idempotent per-stage setup
+granny authentik list providers
+granny authentik rotate-secret stoz3n-dash-staging
+granny authentik add-user-to-group martin              # defaults to dash_admins
+granny authentik api GET /api/v3/core/users/me/        # generic escape hatch
 ```
 
 ## Capability matrix
@@ -302,6 +309,7 @@ granny create mailjet-dns example.com
 | AWS inventory | VPCs, Lambdas |
 | Cross-cloud inventory | GPU instances + reservations, credit balances, MTD spend + forecast (AWS, GCP, Azure) |
 | SSL automation | Bunny, Cloudflare, ACM |
+| SSO / IdP | Authentik (provider + application + group provisioning, per-stage stoz3n-dash workflow) |
 
 ## As a library
 

{granny_devops-0.8.0 → granny_devops-0.9.0}/README.md

@@ -154,6 +154,13 @@ granny email workmail create-user example.com --email user@example.com
 granny create s3-website example.com --help
 granny create scaleway-container --name my-app --port 3000
 granny create mailjet-dns example.com
+
+# Authentik admin (provider + application + group plumbing)
+granny authentik provision-stoz3n-dash development     # idempotent per-stage setup
+granny authentik list providers
+granny authentik rotate-secret stoz3n-dash-staging
+granny authentik add-user-to-group martin              # defaults to dash_admins
+granny authentik api GET /api/v3/core/users/me/        # generic escape hatch
 ```
 
 ## Capability matrix
@@ -170,6 +177,7 @@ granny create mailjet-dns example.com
 | AWS inventory | VPCs, Lambdas |
 | Cross-cloud inventory | GPU instances + reservations, credit balances, MTD spend + forecast (AWS, GCP, Azure) |
 | SSL automation | Bunny, Cloudflare, ACM |
+| SSO / IdP | Authentik (provider + application + group provisioning, per-stage stoz3n-dash workflow) |
 
 ## As a library
 

granny_devops-0.9.0/granny/authentik/__init__.py

@@ -0,0 +1,33 @@
+"""Authentik management — REST API wrapper + per-stage stoz3n-dash provisioning.
+
+Powered by the ``AUTHENTIK_API_TOKEN`` secret (resolves via env var or
+Vaultwarden under ``granny/infra/authentik-api-token``) and the
+non-secret ``AUTHENTIK_URL`` (default ``https://auth.pseekoo.io``).
+
+Public API::
+
+    from granny.authentik import AuthentikClient, STOZ3N_DASH_STAGES, provision_stoz3n_dash
+
+    client = AuthentikClient.from_environment()
+    result = provision_stoz3n_dash(client, stage="development")
+    print(result.client_id, result.client_secret)
+"""
+
+from granny.authentik.client import AuthentikClient, AuthentikError
+from granny.authentik.provision import (
+    ADMIN_GROUP_NAME,
+    OIDC_SCOPES,
+    STOZ3N_DASH_STAGES,
+    ProvisionResult,
+    provision_stoz3n_dash,
+)
+
+__all__ = [
+    "ADMIN_GROUP_NAME",
+    "AuthentikClient",
+    "AuthentikError",
+    "OIDC_SCOPES",
+    "ProvisionResult",
+    "STOZ3N_DASH_STAGES",
+    "provision_stoz3n_dash",
+]

granny_devops-0.9.0/granny/authentik/client.py

@@ -0,0 +1,258 @@
+"""Thin wrapper around the Authentik REST API.
+
+Uses ``requests`` (already a granny core dependency) so this module does
+not require any optional extras.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class AuthentikError(RuntimeError):
+    """Raised on non-2xx responses from the Authentik API."""
+
+    def __init__(self, status: int, body: str) -> None:
+        super().__init__(f"HTTP {status}: {body[:400]}")
+        self.status = status
+        self.body = body
+
+
+class AuthentikClient:
+    """Authenticated client for the Authentik v3 REST API.
+
+    Construct directly when you already have the credentials, or use
+    :meth:`from_environment` to resolve via granny's normal env/vault
+    pipeline.
+    """
+
+    def __init__(self, base_url: str, token: str, *, timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._token = token
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            }
+        )
+
+    @classmethod
+    def from_environment(cls) -> "AuthentikClient":
+        """Build a client from env vars + Vaultwarden fallback.
+
+        Resolution order for the token (explicit env always wins so a
+        rotated value in ``.env`` is picked up immediately without having
+        to invalidate the vault session cache):
+
+        1. ``AK_TOKEN`` (env / .env / .deploy.env) — short alias matching
+           the standalone Authentik scripts.
+        2. ``AUTHENTIK_API_TOKEN`` (env / .env / .deploy.env or
+           Vaultwarden at ``granny/infra/authentik-api-token``, via the
+           normal :func:`granny.credentials.get_secret` chain).
+
+        For the base URL, ``AUTHENTIK_URL`` wins; default
+        ``https://auth.pseekoo.io``.
+        """
+        import os
+
+        from granny.credentials import get_secret
+
+        token = os.environ.get("AK_TOKEN") or get_secret("AUTHENTIK_API_TOKEN")
+        if not token:
+            raise AuthentikError(
+                0,
+                "AUTHENTIK_API_TOKEN (or AK_TOKEN) is not set. "
+                "Either export it, add it to .env/.deploy.env, or push the "
+                "token to Vaultwarden under granny/infra/authentik-api-token "
+                "and install the [vault] extra.",
+            )
+        base_url = os.environ.get("AUTHENTIK_URL") or "https://auth.pseekoo.io"
+        return cls(base_url=base_url, token=token)
+
+    # ── HTTP plumbing ────────────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Execute one API request and return the decoded JSON body.
+
+        Returns ``None`` on 204 / empty bodies.
+        """
+        if not path.startswith("/"):
+            path = "/" + path
+        url = self.base_url + path
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+        resp = self._session.request(
+            method=method.upper(),
+            url=url,
+            params=clean_params or None,
+            json=body,
+            timeout=self._timeout,
+        )
+        if resp.status_code >= 400:
+            raise AuthentikError(resp.status_code, resp.text)
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError:
+            return resp.text
+
+    def paginate(self, path: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Walk an Authentik list endpoint, returning all pages concatenated."""
+        out: list[dict[str, Any]] = []
+        page = 1
+        while True:
+            p = dict(params or {})
+            p["page"] = page
+            data = self.request("GET", path, params=p) or {}
+            out.extend(data.get("results", []))
+            if not data.get("pagination", {}).get("next"):
+                break
+            page += 1
+        return out
+
+    # ── High-level lookups ───────────────────────────────────────────────
+
+    def find_flow_pk(self, slug: str) -> str:
+        results = self.request("GET", "/api/v3/flows/instances/", params={"slug": slug}).get(
+            "results", []
+        )
+        for f in results:
+            if f["slug"] == slug:
+                return f["pk"]
+        raise AuthentikError(404, f"No flow with slug={slug!r}")
+
+    def find_signing_key_pk(self, *, prefer_self_signed: bool = True) -> str:
+        """Return the pk of a key pair that can sign tokens."""
+        keys = self.paginate("/api/v3/crypto/certificatekeypairs/")
+        candidates = [k for k in keys if k.get("private_key_available")]
+        if not candidates:
+            raise AuthentikError(404, "No usable signing key pairs found")
+        if prefer_self_signed:
+            for k in candidates:
+                if "self-signed" in k["name"].lower():
+                    return k["pk"]
+        return candidates[0]["pk"]
+
+    def find_scope_mappings(self, scope_names: tuple[str, ...] | list[str]) -> list[str]:
+        """Resolve scope-property-mapping pks by ``scope_name``."""
+        mappings = self.paginate("/api/v3/propertymappings/provider/scope/")
+        by_scope = {m["scope_name"]: m["pk"] for m in mappings}
+        try:
+            return [by_scope[scope] for scope in scope_names]
+        except KeyError as exc:
+            raise AuthentikError(404, f"Scope mapping for {exc.args[0]!r} not found") from exc
+
+    def find_group_by_name(self, name: str) -> dict[str, Any] | None:
+        for g in self.request("GET", "/api/v3/core/groups/", params={"name": name}).get(
+            "results", []
+        ):
+            if g["name"] == name:
+                return g
+        return None
+
+    def find_user_by_username(self, username: str) -> dict[str, Any] | None:
+        for u in self.request("GET", "/api/v3/core/users/", params={"username": username}).get(
+            "results", []
+        ):
+            if u["username"] == username:
+                return u
+        return None
+
+    def find_provider_by_name(self, name: str) -> dict[str, Any] | None:
+        for p in self.request("GET", "/api/v3/providers/oauth2/", params={"name": name}).get(
+            "results", []
+        ):
+            if p["name"] == name:
+                return p
+        return None
+
+    def find_application_by_slug(self, slug: str) -> dict[str, Any] | None:
+        """Look up an application by slug.
+
+        Uses a direct GET on the slug-keyed detail endpoint instead of the
+        list endpoint. Authentik's application list quietly hides records
+        whose policy bindings restrict ``view`` permissions, even for
+        superusers — direct GET by slug bypasses that filter.
+        """
+        try:
+            return self.request("GET", f"/api/v3/core/applications/{slug}/")
+        except AuthentikError as exc:
+            if exc.status == 404:
+                return None
+            raise
+
+    def find_provider_by_pk(self, pk: int | str) -> dict[str, Any] | None:
+        """Look up an OAuth2 provider by primary key (integer)."""
+        try:
+            return self.request("GET", f"/api/v3/providers/oauth2/{pk}/")
+        except AuthentikError as exc:
+            if exc.status == 404:
+                return None
+            raise
+
+    # ── Mutating helpers ─────────────────────────────────────────────────
+
+    def ensure_group(self, name: str) -> dict[str, Any]:
+        """Create a group if missing; return the (existing or new) group dict."""
+        existing = self.find_group_by_name(name)
+        if existing:
+            return existing
+        return self.request("POST", "/api/v3/core/groups/", body={"name": name})
+
+    def add_user_to_group(self, username: str, group_name: str) -> None:
+        user = self.find_user_by_username(username)
+        if not user:
+            raise AuthentikError(404, f"User {username!r} not found")
+        group = self.find_group_by_name(group_name)
+        if not group:
+            raise AuthentikError(
+                404, f"Group {group_name!r} not found — create it with ensure_group first"
+            )
+        self.request(
+            "POST",
+            f"/api/v3/core/groups/{group['pk']}/add_user/",
+            body={"pk": user["pk"]},
+        )
+
+    def remove_user_from_group(self, username: str, group_name: str) -> None:
+        user = self.find_user_by_username(username)
+        if not user:
+            raise AuthentikError(404, f"User {username!r} not found")
+        group = self.find_group_by_name(group_name)
+        if not group:
+            raise AuthentikError(404, f"Group {group_name!r} not found")
+        self.request(
+            "POST",
+            f"/api/v3/core/groups/{group['pk']}/remove_user/",
+            body={"pk": user["pk"]},
+        )
+
+    def rotate_client_secret(self, provider_name: str) -> dict[str, Any]:
+        """Rotate ``client_secret`` on an existing OAuth2 provider.
+
+        Authentik regenerates the secret server-side when we PATCH it to
+        an empty string. The returned dict carries the new value (when
+        the API echoes it back — varies by version).
+        """
+        provider = self.find_provider_by_name(provider_name)
+        if not provider:
+            raise AuthentikError(404, f"Provider {provider_name!r} not found")
+        return self.request(
+            "PATCH",
+            f"/api/v3/providers/oauth2/{provider['pk']}/",
+            body={"client_secret": ""},
+        )

granny_devops-0.9.0/granny/authentik/provision.py

@@ -0,0 +1,235 @@
+"""Per-stage stoz3n-dash app provisioning in Authentik.
+
+The :data:`STOZ3N_DASH_STAGES` map defines the slug + redirect_uri + launch
+URL for each environment. Keep this synchronised with the canonical doc at
+``stoz3n-agent-dash/docs/authentik-sso.md``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from granny.authentik.client import AuthentikClient
+
+STOZ3N_DASH_STAGES: dict[str, dict[str, str]] = {
+    "development": {
+        "slug": "stoz3n-dash-dev",
+        "name": "Stoz3n Dashboard (dev)",
+        "redirect_uri": "http://localhost:8000/api/auth/oidc/callback",
+        "launch_url": "http://localhost:5173",
+    },
+    "staging": {
+        "slug": "stoz3n-dash-staging",
+        "name": "Stoz3n Dashboard (staging)",
+        "redirect_uri": "https://facts-dev.stozn.ai/api/auth/oidc/callback",
+        "launch_url": "https://dash-dev.stozn.ai",
+    },
+    "production": {
+        "slug": "stoz3n-dash",
+        "name": "Stoz3n Dashboard",
+        "redirect_uri": "https://facts.stozn.ai/api/auth/oidc/callback",
+        "launch_url": "https://dash.stozn.ai",
+    },
+}
+
+ADMIN_GROUP_NAME = "dash_admins"
+AUTHORIZATION_FLOW_SLUG = "default-provider-authorization-explicit-consent"
+INVALIDATION_FLOW_SLUG = "default-provider-invalidation-flow"
+OIDC_SCOPES: tuple[str, ...] = ("openid", "profile", "email")
+
+
+@dataclass
+class ProvisionResult:
+    """Outcome of :func:`provision_stoz3n_dash`."""
+
+    stage: str
+    base_url: str
+    issuer: str
+    client_id: str
+    client_secret: str  # empty string if Authentik didn't echo it back
+    redirect_uri: str
+    admin_group: str
+    scopes: str
+    provider_pk: str
+    application_slug: str
+    group_pk: str
+    created_provider: bool
+    created_application: bool
+    created_binding: bool
+    created_group: bool
+
+    @property
+    def authorization_endpoint(self) -> str:
+        return f"{self.base_url}/application/o/authorize/"
+
+    @property
+    def token_endpoint(self) -> str:
+        return f"{self.base_url}/application/o/token/"
+
+    @property
+    def userinfo_endpoint(self) -> str:
+        return f"{self.base_url}/application/o/userinfo/"
+
+    def chat_agent_oidc_block(self) -> dict[str, dict[str, str]]:
+        """JSON snippet to paste into the chat-agent's encrypted config."""
+        return {
+            "oidc": {
+                "issuer": self.issuer,
+                "authorization_endpoint": self.authorization_endpoint,
+                "token_endpoint": self.token_endpoint,
+                "userinfo_endpoint": self.userinfo_endpoint,
+                "client_id": self.client_id,
+                "client_secret": self.client_secret
+                or "<rerun with --rotate or run granny authentik rotate-secret>",
+                "redirect_uri": self.redirect_uri,
+                "admin_group": self.admin_group,
+                "scopes": self.scopes,
+            }
+        }
+
+    def dashboard_oidc_block(self) -> dict[str, dict[str, str]]:
+        """JSON snippet to paste into the dashboard repo's encrypted config."""
+        return {
+            "oidc": {
+                "client_secret": self.client_secret
+                or "<rerun with --rotate or run granny authentik rotate-secret>"
+            }
+        }
+
+
+def provision_stoz3n_dash(
+    client: AuthentikClient,
+    *,
+    stage: str,
+    rotate_secret: bool = False,
+) -> ProvisionResult:
+    """End-to-end idempotent provisioning of one stoz3n-dashboard stage.
+
+    Steps:
+
+    1. Resolve authorization flow + signing key + OIDC scope mappings.
+    2. Ensure the ``dash_admins`` group exists.
+    3. Create or PATCH the OAuth2 provider.
+    4. Create or PATCH the application.
+    5. Create the application→group policy binding if absent.
+
+    Re-running is safe; nothing is destroyed. ``rotate_secret=True`` forces
+    a new ``client_secret`` to be minted on an existing provider.
+    """
+    if stage not in STOZ3N_DASH_STAGES:
+        raise ValueError(
+            f"Unknown stage {stage!r}; choose one of {sorted(STOZ3N_DASH_STAGES)}"
+        )
+    cfg = STOZ3N_DASH_STAGES[stage]
+    provider_name = cfg["slug"]
+    app_slug = cfg["slug"]
+
+    # 1. Foreign keys
+    authorization_flow = client.find_flow_pk(AUTHORIZATION_FLOW_SLUG)
+    invalidation_flow = client.find_flow_pk(INVALIDATION_FLOW_SLUG)
+    signing_key = client.find_signing_key_pk()
+    scope_mappings = client.find_scope_mappings(OIDC_SCOPES)
+
+    # 2. Admin group
+    existing_group = client.find_group_by_name(ADMIN_GROUP_NAME)
+    created_group = existing_group is None
+    group = existing_group or client.ensure_group(ADMIN_GROUP_NAME)
+
+    # 3. Provider — three reconciliation paths:
+    #   a. App+provider already exist under our slug → adopt them. We honor
+    #      the existing provider's pk so its client_id stays stable; only
+    #      rename + reconfigure fields. This is the production path where
+    #      a pre-existing app may already be live with consumers.
+    #   b. Provider exists by name (our convention) but no app → PATCH it
+    #      in place.
+    #   c. Nothing exists → POST a fresh provider.
+    existing_app_for_adoption = client.find_application_by_slug(app_slug)
+    adopt_pk: int | str | None = None
+    if existing_app_for_adoption is not None:
+        adopt_pk = existing_app_for_adoption.get("provider")
+    existing_provider = (
+        client.find_provider_by_pk(adopt_pk) if adopt_pk is not None else None
+    ) or client.find_provider_by_name(provider_name)
+
+    provider_body: dict[str, object] = {
+        "name": provider_name,
+        "authorization_flow": authorization_flow,
+        "invalidation_flow": invalidation_flow,
+        "client_type": "confidential",
+        "redirect_uris": [{"matching_mode": "strict", "url": cfg["redirect_uri"]}],
+        "signing_key": signing_key,
+        "property_mappings": scope_mappings,
+        "sub_mode": "user_username",
+        "include_claims_in_id_token": True,
+        "access_token_validity": "minutes=10",
+        "refresh_token_validity": "days=30",
+    }
+    if existing_provider:
+        if rotate_secret:
+            provider_body["client_secret"] = ""  # empty → Authentik regenerates
+        provider = client.request(
+            "PATCH",
+            f"/api/v3/providers/oauth2/{existing_provider['pk']}/",
+            body=provider_body,
+        )
+        created_provider = False
+    else:
+        provider = client.request("POST", "/api/v3/providers/oauth2/", body=provider_body)
+        created_provider = True
+
+    # 4. Application
+    app_body = {
+        "name": cfg["name"],
+        "slug": app_slug,
+        "provider": provider["pk"],
+        "meta_launch_url": cfg["launch_url"],
+        "policy_engine_mode": "any",
+    }
+    if existing_app_for_adoption:
+        client.request("PATCH", f"/api/v3/core/applications/{app_slug}/", body=app_body)
+        created_application = False
+        target_pk = existing_app_for_adoption["pk"]
+    else:
+        new_app = client.request("POST", "/api/v3/core/applications/", body=app_body)
+        created_application = True
+        target_pk = new_app["pk"]
+
+    # 5. Group → application policy binding
+    bindings = client.request(
+        "GET", "/api/v3/policies/bindings/", params={"target": target_pk}
+    ).get("results", [])
+    has_binding = any(b.get("group") == group["pk"] for b in bindings)
+    if has_binding:
+        created_binding = False
+    else:
+        client.request(
+            "POST",
+            "/api/v3/policies/bindings/",
+            body={
+                "target": target_pk,
+                "group": group["pk"],
+                "enabled": True,
+                "order": 0,
+                "negate": False,
+                "timeout": 30,
+            },
+        )
+        created_binding = True
+
+    return ProvisionResult(
+        stage=stage,
+        base_url=client.base_url,
+        issuer=f"{client.base_url}/application/o/{app_slug}",
+        client_id=provider["client_id"],
+        client_secret=provider.get("client_secret") or "",
+        redirect_uri=cfg["redirect_uri"],
+        admin_group=ADMIN_GROUP_NAME,
+        scopes=" ".join(OIDC_SCOPES),
+        provider_pk=str(provider["pk"]),
+        application_slug=app_slug,
+        group_pk=str(group["pk"]),
+        created_provider=created_provider,
+        created_application=created_application,
+        created_binding=created_binding,
+        created_group=created_group,
+    )